SNAPC: Snapshot dump

Use this general macro, similar to the system error macro (SERRC), to collect diagnostic data to be used for problem determination. If the amount of data needed to analyze a problem is limited and the location of the data can be predetermined, a snapshot dump can be used instead of the typical SERRC dump to reduce the use of system resources and make the diagnostic data more precise.

The storage dump locations are specified by LISTC macros indicated in the LIST parameter.

The SNAPC macro may be used whenever an operational program (E-type) or the control program (C-type) detects an error.

Last updated

  • Changed in 2021 (information only; no code change).
  • Changed in 2020 (information only; no code change).
  • Changed for PUT10.
  • Changed for PUT00.

Format

Read syntax diagramSkip visual syntax diagramlabelSNAPCaction ,snpnum,PROG= label1,MSG=label2reg2,REGS=NO,REGS=YES,ECB=YES,ECB=NO,LIST=label3reg3,PREFIX=U,PREFIX= letter,TRACE=NO,TRACE=YES
label
A symbolic name that can be assigned to the macro statement.
action
A positional parameter that specifies the action to be taken by the SNAPC service routine upon completion of the dump:
R
Returns to next sequential instruction (NSI)
E
Exits the entry control block (ECB). If E is coded for this parameter the ECB exits regardless of the specification of ECB parameter.
snpnum
A positional parameter that specifies the snapshot dump code, where snpnum is one of the following:
(errcode)
A symbolic equate for a snapshot error code, enclosed in parentheses.
sd
A hexadecimal system error number in the range X'0' - X'7FFFFFFF'.
reg1
The symbolic name of a register that contains the snapshot error code. Valid symbols are R0 to R7, R14, and R15.

The defined prefix is appended to the front of the error number.

PROG=label1
Specifies the location of the program name to be used in the snapshot dump, where label1 is the label of an addressable character constant field. The length of the constant is the length of the program name (maximum length is 16 bytes). If you do not specify this parameter and an ECB can be associated with the program with the error, the 4-byte application name in CE3TRNAME is used in the snapshot dump and the console message. If you do not specify this parameter and no ECB can be associated with the program with the error, the 4-byte application name that is located 4 bytes past the address in R8 is used in the snapshot dump and the console message.
MSG
Specifies the address of the appended message, where:
label2
A symbolic label.
reg2
The name of a register that contains the address. Specify a register that is different from reg1 and reg3.
When this parameter is specified, the MSG parameter is the label of the message (MESSAG) of the form:
MESSAG   EQU   *
MSGLEN   DC    AL1(L'MSGSTUF)
MSGSTUF  DC    C'THIS IS THE APPEND MESSAGE'
REGS
Specifies whether the contents of the general registers are to be included when a snapshot dump is displayed to the system console.
Note: The registers will always be included in the snapshot dump when formatted by either ICDF or STPP.
NO
The contents of the general registers are not included in the snapshot dump.
YES
The contents of the general registers are included in the snapshot dump.
ECB
Specifies whether the SS, SSU, and terminal address are obtained from the ECB.
YES
Specifies that the SS, SSU, and terminal address are obtained from the ECB.
NO
Specifies that the SS, SSU, and terminal address are not obtained from the ECB.
  • The SS and SSU are forced to the BSS and
  • The terminal address is unavailable and will be displayed as N.A.
  • Return is to the CPU loop.

Code ECB=NO only when no ECB can be associated with the program in error. ECB=NO can only be coded when running in the SVM.

LIST
Specifies the location of one or more LISTC macro calls, which are used to identify additional main storage areas to be dumped, where:
label3
A symbolic label.
reg3
The name of a register that contains the address. Specify a register that is different from reg1 and reg2.

If this parameter is not specified, no data area will be dumped.

If this parameter is specified, the LIST parameter is the label of the data areas that are specified by LISTC macros.

PREFIX=U|letter
Specifies the prefix of the snapshot dump code. By using a prefix an application will have a SNAPC code name space associated with it. When coded, the PREFIX parameter is a single alphabetic character.
U
Specifies that U is the prefix of the snapshot dump code.
letter
The letter that is used for the prefix of the snapshot dump code.
Note: The letters I and W–Z are reserved for IBM® use.
TRACE=YES|NO
Specifies whether the ECB trace (macro and function trace) also will be dumped. Do not code this parameter if ECB=NO is coded. If ECB=YES is coded, the TRACE parameter can be coded to dump the ECB macro trace.

This parameter dumps the 40 most recent function or macro trace entries, so there will only be 40 entries in the postprocessed SNAPC dump. Use the SERRC macro if more entries are required to solve the problem.

Notes:
  • If TRACE is coded, the ECB might give up control.
  • The TRACE parameter can be called only from an E-type program (shared object).

Entry requirements

  • If an ECB is associated with the error, R9 must contain its address.
  • If the PROG parameter is not coded and no ECB can be associated with the program with the error, R8 is assumed to contain the address that is used to locate the program name. The program name is located 4 bytes past the address contained in R8.

Return conditions

  • Control is returned, as specified by the first positional parameter action, to NSI when 'R' is indicated or to the EXITC macro processing when 'E' is indicated.
  • A storage dump is taken and the system operator is informed of the error via a CRAS set if the console notification is not suppressed by the ZASER command with the SNAP and CONSOFF parameters specified.
  • The condition code and the contents of all registers are preserved on return to NSI.

Programming considerations

  • For information about macro register conventions, see Register conventions.
  • The SNAPC service routine uses up to 16 4-KB blocks to collect the specified data. Overflow data is truncated.

Examples

This example forces a snapshot dump bearing ID number 12345 and a prefix of 'A' to be issued. Control will return to the program after the dump and the registers will be included in the dump. The ECB will be used for the SS and SSU names, and the terminal ID and the program name will at label NAME. The LISTC definitions are at label SNAPSTUF and the appended message will be at label MESS. 

         SNAPC R,12345,PROG=NAME,MSG=MESS,REGS=YES,ECB=YES,            *
               LIST=SNAPSTUF,PREFIX=A
⋮
MESS     DC   AL1(L'MSGSTUF)
MSGSTUF  DC   C'PROGRAM BLEW UP'
NAME     DC   C'C001'
SNAPSTUF LISTC NAME=MYSTUFF,TAG=EBW000,LEN=4,INDIR=YES
         LISTC NAME=DATA10,TAG=CE1CR0,LEN=1000,INDIR=YES
         LISTC END