gtpg2m3vGeneral Macros

SNAPC-Snapshot Dump

This general macro, similar to the system error macro (SERRC), collects 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.

Format




label
A symbolic name may be assigned to the macro statement.

action
Required. This positional parameter specifies the action to be taken by the SNAPC service routine upon completion of the dump:

R
Return to next sequential instruction (NSI)

E
Exit the entry control block (ECB) If E is coded for this parameter the ECB exits irrespective of the specification of ECB parameter.

snpnum
Required - this positional parameter specifies the snapshot dump code. There are three ways to code this information:

(errcode)
A symbolic equate for a snapshot error code, enclosed in parentheses.

sd
A hexadecimal system error number in the range X'0-7FFFFFFF'.

Rx
The symbolic name of a register which contains the snapshot error code. Valid symbols are R0 through R7, R14, and R15.

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

PROG=label1
Optional - this parameter specifies the location of the program name to be used in the snapshot dump. When specified, the PROG keyword 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 not specified, the four-byte program name located four bytes off R8 is used in the snapshot dump and the console message. This parameter should be coded when R8 does not point to a valid program.

MSG=label2
Optional - this parameter specifies the address of the appended message. When specified, the MSG operand 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=NO|YES
Optional - this parameter specifies whether the general registers are to be included when a snapshot dump is displayed to the system console. The default value is NO.
Note:
The registers will always be included in the snapshot dump when formatted by either ICDF or STPP.

ECB=YES|NO
Optional - this parameter specifies whether the SS, SSU, and terminal address are to be taken from the ECB. The default value is YES.

If ECB=NO:

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

LIST=label3
Optional. This parameter specifies the location and length of the data to be dumped. If not specified, no data area will be dumped. When specified, this LIST parameter is the label of the data areas specified by LISTC macros.

PREFIX=U|letter
Optional. This parameter 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 keyword is a single alphabetic character. The default prefix is U. The letters I and W-Z are reserved for IBM use.

Entry Requirements

Return Conditions

Programming Considerations

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