SERRC: System error

Use this general macro to cause a storage dump and send a message to the system operator via a CRAS terminal. You can use this macro whenever an operational program or the control program detects an abnormal condition that requires a dump of main storage as an aid to error analysis.

Note: All system activity is suspended while the storage dump is written. If the cause of the error is well understood and less than 32 KB of data is required to fully document the problem, use the SNAPC macro. The SNAPC macro uses far fewer processor resources; in particular, system activity is not halted during its processing.

Last updated

Changed in 2020.
Changed in 2019.
Changed for PUT08 (information only; no code change).
Changed for PUT06.
Changed for PUT00.

Format

label

A symbolic name that can be assigned to the macro statement.

action

The action to be taken by the system error routine upon completion of the dump, where:

E: Exits from the entry control block (ECB) if one is associated with the error. Otherwise, return to the CPU Loop.
R: Returns to next sequential instruction.
C: Specifies a catastrophic error. When a catastrophic error occurs, the z/TPF system IPLs and returns to 1052 state, unless the system error number is listed in an internal table in program CPSF. If the error number is listed in program CPSF, the system returns to NORM state.

senum

The 6-digit hexadecimal system error number (range: X'000001' to X'FFFFFF') used to identify the dump. z/TPF system error numbers are documented in z/TPF Messages (System Error, Offline, and Program Status Word). Code this parameter in one of the following ways:

hexnum: A hexadecimal system error number in the range X'000001' to X'FFFFFF'.
(errnum): A symbolic system error number, as defined in CZ1SE (IBM® error numbers), enclosed in parentheses.
reg: The symbolic name of a register containing the system error number. Valid symbols are R0 through R7, R14, and R15. If you specify MSG=YES, reg cannot be R0. Do not specify the same register as reg1 or reg2.

PREFIX=letter

Specifies an uppercase alphabetic character that is concatenated with the system error number in the console message and in the dump. The letters I and W–Z are reserved for IBM use. The default is PREFIX=I for IBM code, and PREFIX=U for non-IBM code.

MSG

Specifies one of the following values:

YES: Specifies that R0 must contain the address of a user supplied message that is to be appended to the operator notification of the dump.
Note: The address is handled as a 64-bit address if the dump occurred when running in 64-bit mode. If the system is not running in 64-bit mode, it is assumed to be a 31-bit address.
NO: Specifies there is no user supplied message.

ECB

Specifies whether or not an ECB is associated with this error.

YES: Specifies that an ECB is associated with this error. Dump the ECB and all working storage mapped in the EVM.
NO: Specifies that no ECB is associated with this error. If this option is coded, no working storage will be dumped unless there is a Dump Override Table entry associated with this system error that specifies an area of working storage, or unless a portion of working storage has been specified using the LIST or SLIST parameters.

LIST

Specifies the location of one or more LISTC macro calls, which are used to identify additional main storage areas to be dumped. Specify one of the following:

label2: A symbolic label.
reg1: The name of a register containing the address. Valid register names are R1 through R7, R14, and R15. Do not specify the same register as reg or reg2. If senum is coded as a register, SLIST can not specify the same register as senum and cannot specify R14 or R0.
Note: The address is handled as a 64-bit address if the dump occurred when running in 64-bit mode. If the system is not running in 64-bit mode, it is assumed to be a 31-bit address.

Parentheses cannot be used. If you specify MSG=YES, reg1 cannot be R0.

SLIST

Specifies the address of a user-defined list of storage areas to be dumped. Specify one of the following values:

label3: A symbolic label (EBW034, for example).
reg2: The name of a register containing the address. Valid register names are R0 through R7, R14, and R15. Do not specify the same register as reg or reg1. If you specify MSG=YES, reg2 cannot be R0.
Note: The address is handled as a 64-bit address if the dump occurred when running in 64-bit mode. If the system is not running in 64-bit mode, it is assumed to be a 31-bit address.

SYSDUMP

Specifies whether a dump of system storage will be performed.

YES: The default for control program errors.
NO: The default for operational program errors.
If no override exists for dumps created with the SYSDUMP=NO parameter, system storage will not be dumped. Dump overrides are coded in the CUDP copy member of the CCUEXT user exit (CIDP or UIDP in CCCPSE for IBM overrides). You can also enter the ZIDOT command with the OVERRIDE parameter to display a list of errors that are being overridden. You can override the SYSDUMP=NO parameter by using the UCCSRM user exit.

Note: System storage will always be dumped if there is no ECB associated with the error.

DSECT=YES

Generates a DSECT describing the macro expansion, and the equates associated with various macro options. This parameter is intended for CP use only.

OPR

Specifies whether the dump will be an OPR or a CTL dump as follows:

YES: Specifies that if the dump is in the control program, the dump is displayed as an OPR dump. This parameter enables the dump to be controlled by the ZASER command with the DUPL or NODUPL parameter.
NO: Specifies that if the dump is in the control program, the dump will display as a CTL dump.

CPADDR

Specifies whether this dump will use the overrides coded in the IDOTC macro for the CSECT in which the dump takes place. This parameter is ignored for dumps that are not in the control program (CP).

YES: Specifies that the dump will use the IDOTC macro to determine which areas to dump.
NO: Specifes that the dump will not use the IDOTC macro to determine which areas to dump.
reg3: A register that points to an address in the CP that dump processing uses as the CSECT address (instead of the current address) to determine which IDOTC storage definitions to use.

HEAP

Specifies whether or not the dump will include 31-bit and 64-bit ECB heap buffers. This is valid only when ECB=YES.

YES: Specifies that the dump will include in-use ECB heap buffers.
NO: Specifies that the dump will not include any part of the ECB heap.
ALL: Specifies that the dump will include both in-use ECB heap buffers and available heap areas.

ECBSTACK

Specifies whether or not the application stack will be dumped. When ECB=NO is coded, this parameter is ignored.

YES: Specifies that the application stack will be dumped.
NO: Specifies that the application stack will not be dumped.

CSTATIC

Specifes whether the C static area will be dumped. When ECB=NO is coded, this parameter is ignored.

YES: Specifies that the C static area will be dumped.
NO: Specifies that the C static area will not be dumped.

Entry requirements

If an ECB is associated with the error, the address of the ECB must be in R9. This address must be valid for the address space in which the macro is invoked.

Return conditions

Control is returned as specified by action as follows:

E

To EXITC processing

R

To NSI in the calling program

C

To catastrophic processing.
On return to NSI, the contents of all registers are preserved.

Programming considerations

For information about macro register conventions, see Register conventions.
The positional parameters (MSG, OP, CP, ECB, NEB) from previous z/TPF system releases are supported only for migration purposes. Use the keyword parameters described previously for any new SERRC macro calls.
Note:
1. If no keyword parameters are used, the old format macro expansion will be generated and no prefix character will be concatenated with the system error number.
2. The prefix character will default to U for SERRC calls in user programs from previous z/TPF system releases that have not been reassembled.
If this macro is issued with an exit before 1052 state, state change will be disabled for the failing MDBF subsystem.
If this macro is issued with an exit while state change is in progress, and the system error was caused by the BSS state change ECB, the error will be forced irrecoverable. If the error was caused by the state change ECB for a non-BSS subsystem, the subsystem will be cycled down and state change will be disabled for the subsystem.
The Selective Memory Dump Table in copy member CPST of the CCCPSE CSECT defines large data areas in main storage that are normally not dumped. If data from one of these areas is required for problem diagnosis, the user must create a dump override for the system error by coding an IDOTB macro call in copy member CUDP of the CCUEXT CSECT. (For IBM system errors, update copy member CIDP in the CCCPSE CSECT.)
If MSG=YES is specified, a user-supplied message will be sent to CRAS in addition to the system error message which is normally sent by the system error routine. The user must load R0 with the address of the message prior to executing the SERRC macro. The maximum size of this message is 255 bytes including the character count, which must appear in the first byte. Control characters (such as line feed and EOM) are not permitted; however, the carriage return character is supported.
Note: The GENMSG macro with the TEXTONLY option may be used to build the correct message format.
If LIST is specified, the user must code a valid sequence of LISTC macros at the specified location. Refer to the LISTC macro description for more information.
If the LISTC macro points to an I-stream unique global area and the dump is in the system virtual memory (SVM), the SVM global of the main I-stream will be dumped.
If the addresses specified using the SLIST parameter point to an I-stream unique global area and the dump is in the SVM, the SVM global of the main I-stream will be dumped.
If SLIST is coded, the user must build a list containing the parameters to be used in dumping additional storage. Each entry in the list consists of 3 words. The first byte of the first word is an indicator byte, and the last 3 bytes of the first word are unused. The second word contains a starting address. The third word contains an ending address or the number of bytes, less one, to be dumped.
Note: The SLIST parameter works only with 31-bit addresses. Use the LIST parameter for dumping 64-bit address storage.
The format of the list is as follows:
- 1st word, first byte
  The list entry is ignored if the value provided is other than those defined.
  - 00 – HEX dump request (3rd word contains an address).
  - 01 – EBCDIC dump request (3rd word contains an address).
  - 02 – HEX dump request (3rd word contains length -1).
  - 03 – EBCDIC dump request (3rd word contains length -1).
  - F0 – Ignore this entry.
  - FF – End of list.
- 2nd word contains the starting address of storage area to be dumped.
  Note: This must be a 31-bit address. Use the LIST parameter for dumping 64-bit address storage.
- 3rd word contains the ending address of a storage area to be dumped, or the number of bytes to be dumped, minus one.
Note:
1. The list must start on a fullword boundary.
2. The storage actually dumped will begin and end on a doubleword boundary, and will include all bytes specified, up to a maximum of 4096 bytes.
3. If the start address is greater than the end address, a doubleword of storage beginning with the start address is dumped.
If the location specified by the LIST parameter is in memory belonging to another ECB, the dump contains the phrase Address Error for the LISTC with the erroneous address.

Examples

The following is an example of an operational program system error:

    XYZ      SERRC E,(CE93C0),PREFIX=A      OPR-A0003C0 with exit

             SERRC R,(CE91E4),PREFIX=Q,     OPR-Q0001E4 with return, use
               SLIST=EBW008             area at EBW008 defined as
                                        follows:

EBW008: X'01'               EBCDIC dump, 3rd word contains address
EBW012: X'000D3180'         Start of area to be dumped
EBW016: X'000D35A0'         End of area to be dumped
EBW020: X'02'               HEX dump, 3rd word contains length - 1
EBW024: X'000E4400'         Start of area to be dumped
EBW028: X'000000FF'         Length -1 of area to be dumped
EBW032: X'F0'               Ignore this entry
EBW036: -----------         Irrelevant
EBW040: -----------         Irrelevant
EBW044: X'FF'               End of list

The following is an example of an operational program system error:

             SERRC E,(CE91F0),PREFIX=H,     OPR-H0001F0 with exit and
               LIST=ABC                 LISTC calls coded as follows:

ABC      DS    0F
         LISTC TAG=EBW034,              dump EBW034-EBW037
               LEN=4,
               NAME=ITEM1
         LISTC TAG=EBW038,              dump 24 bytes at the location
               LEN=24,                  pointed to by EBW038
               NAME=ITEM2,
               INDIR=YES
         LISTC END                      terminate the list

The following is an example of a control program system error:

             SERRC C,(CECRS235),            CTL-I000235 catastrophic
               ECB=NO,                  no associated ECB
               PREFIX=I                 IBM system error

The following is an example of a control program system error:

             LA    R7,CA9SO2                CTL-I0000E1 ..
DMPRTN   SERRC R,R7,PREFIX=I            .. with return

The following is an example of a control program system error:

             LA    R0,DPMSG3                message defined as follows
         SERRC E,(CE929C),              CTL-I00029C with exit
               MSG=YES,                 message address in R0
               PREFIX=W                 IBM system error

DPMSG3   DC    AL1(L'SDP3)
SDP3     DC    C'SIPC WRITE ERROR - INDETERMINATE'

Generate the macro expansion DSECT
```
             SERRC DSECT=YES
```