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:
- 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.
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
- If an ECB is associated with the error, R9 must contain its
address.
- If PROG parameter is not coded, R8 is assumed to point to a standard
E-type program header.
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
- The SNAPC service routine will use up to eight 4KB blocks to collect the
specified data. Overflow data will be truncated.
- If a page fault occurs while SNAPC is processing a requested dump in VEQR
mode (because an address belongs to another ECB), SNAPC continues processing
the requested dump. If a page fault occurs in an application running in
VEQR mode, a SNAP dump is generated to log the application's address
violation for correction.
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