Description

The requirements for the caller are:

Before issuing the SNAP(X) macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.

Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after regaining control.

DSORG=PS,RECFM=VBA,MACRF=(W),BLKSIZE=nnn,LRECL=xxx,
and DDNAME=any name but SYSABEND, SYSMDUMP or SYSUDUMP

If the DD name for the SNAP dump has the XTIOT, UCB nocapture, or DSAB-above-the-line options of dynamic allocation, your DCB must point to a DCBE before you open the DCB. The DCBE must have the LOC=ANY option. You can code that even if the DD name does not have any of these dynamic allocation options. To point the DCB to the DCBE, code the DCBE operand on the DCB macro, or store into the DCBDCBE field if you also turn on the DCBH0 and DCBH1 bits. The DCBE can reside above the 16 MB line even if your program runs in 24-bit.

In order for the OPEN for the DCB to succeed, it is necessary for the NON_VSAM_XTIOT=YES option in the DEVSUPxx member of PARMLIB to be active.

For dynamic allocation, XTIOT option bit is S99TIOTEX, the UCB nocapture option bit is S99ACUCB, and the DSAB-above-the-line option bit is S99DSABA. These options are defined by the IEFZB4D0 macro. For more information about the XTIOT option for dynamic allocation of the dump data set, see S99PARMS programming interface in MVS Data Area Volume 6 from z/OS Internet Library.

If a standard dump of 120 characters per line is requested, BLKSIZE must be either 882 or 1632, and LRECL must be 125. A high-density dump printed on a 3800 Printing Subsystem has 204 characters per line. To obtain a high-density dump, you must code CHARS=DUMP on the DD statement describing the dump data set. The BLKSIZE= must be either 1470 or 2724, and the LRECL= must be 209. You can also code CHARS=DUMP on the DD statement describing a dump data set that will not be printed immediately. If you specify CHARS=DUMP and the output device is not a 3800, print lines are truncated and print data is lost. If you open a SNAP data set in a problem program that will be processed by the system loader, your problem program must close the data set.

The DCB and TCB must reside in 24-bit addressable storage. All other parameters can reside above 16 megabytes if the issuer is executing in 31-bit addressing mode.

If the program is in AR mode, issue SNAPX rather than SNAP; issue the SYSSTATE ASCENV=AR macro before SNAPX. SYSSTATE ASCENV=AR tells the system to generate code appropriate for AR mode.

None.

None.

The standard form of the SNAP macro is written as follows:

NUC      CB        ERR
SQA      Q         IO
LSQA     TRT       ALLVNUC
PCDATA
SWA      DM        SUM

PSW
REGS
SA or SAH
JPA or LPA or ALLPA
SPLS
SUBTASKS

The parameters are explained as follows:

DCB=dcb addr

Specifies the address of a previously opened data control block for the data set that is to contain the dump.

Note:

1. DCB must reside in 24-bit addressable storage.
2. The DCB parameter is not required when you issue the list form of SNAP or SNAPX to format a parameter list for the DUMPOPT/DUMPOPX parameter of the ABEND, CALLRTM, or SETRP macros. If the parameter list you specify on DUMPOPT/DUMPOPX contains a DCB value, the system overrides it. The DCB parameter is required when you issue the list form of SNAP or SNAPX to format a parameter list for an execute form of SNAP or SNAPX if the execute form does not specify the DCB parameter. That is, if you specify both a list and execute form of SNAP or SNAPX, you must specify DCB on one or the other.
3. If the DD name for the SNAP dump has the XTIOT, UCB nocapture, or DSAB-above-the-line options of dynamic allocation, your DCB must point to a DCBE before you open the DCB. See the "Programming Requirements" section for more details.

,TCB=tcb addr

Specifies the address of a fullword on a fullword boundary containing the address of the task control block for a task of the current job step. If omitted, or if the fullword contains 0, the dump is for the active task. If a register is designated, the register can contain 0 to indicate the active task, or can contain the address of a TCB.

Note: TCB must reside in 24-bit addressable storage.

,ID=id nmbr

Specifies the number that is to be printed in the identification heading with the dump. If the number specified is not in the acceptable value range, it will not be printed properly in the heading.

,SDATA=ALL

,SDATA=(sys data code)

Specifies the system control program information to be dumped:

ALL

All of the SDATA options except ALLVNUC (The read-only portion of the nucleus is not included in the dump unless ALLVNUC is also specified as an option.)

NUC

The PSA, SQA, LSQA, and the read/write portion of the nucleus (if the entire nucleus is required, specify the ALLVNUC option.)

Note: The CVT will be included if this option is specified.

SQA

The system queue area (subpools 226, 239, and 245).

LSQA

The local system queue area and subpools 229, 230, and 249.

Note: Subpools 229, 230, and 249 will be dumped only for the current task.

SWA

The scheduler work area related to the task (subpools 236 and 237).

CB

The control blocks for the task.

Q

The global resource serialization control blocks for the task.

TRT

The GTF trace and system trace data. If system tracing is active and the requestor is authorized, all system trace entries for all address spaces are included in the dump. Unauthorized requestors obtain those system trace entries, after the job-start time stamp in the ASCB, for their current address space. If GTF tracing is active, only the GTF trace entries for the current address space are included in the dump.

DM

Data management control blocks for the task.

ERR

Recovery/termination control blocks for the task. These control blocks summarize information that describes abnormal terminations of the task.

IO

Input/Output supervisor control blocks for the task.

ALLVNUC

The entire virtual nucleus, the PSA, LSQA, and SQA. (The NUC option will not dump the read-only section of the nucleus.) If the SNAP parameter list is used for a SYSMDUMP, the ALLVNUC option is converted to ALLNUC on the SVC dump parameter list.

Note: The CVT is included if this option is specified.

PCDATA

Program call information for the task.

The SUM option is valid for an abending task or on a list form of the SNAP macro pointed to by the DUMPOPT keyword of the ABEND or SETRP macro. The option SUM causes the dump to contain a summary dump. If SUM is the only option requested, the dump contains a dump header, control blocks, and the other areas listed below. The header information, which is provided for all ABEND dumps, consists of the following information:

• The dump title
• The ABEND code and program status word (PSW) at the time of the error
• If the PSW contains the address of an active load module:
  • The name and PSW address of the load module in error
  • The offset, into the load module, at which the error occurred

The following control blocks and areas are also included in the dump:

• The control blocks dumped for the CB option
• The error control blocks (RTM2WAs and SCBs)
• The save areas
• The registers at the time of the error, except for register 1
• The contents of the load module (if the PSW contains the address of an active load module)
• The module pointed to by the last PRB (if it can be found)
• 1K of storage before and after the addresses pointed to by the PSW and the registers at the time of the error
  Note: This storage will only be dumped if the caller is authorized to obtain it. The storage is printed by ascending storage addresses with duplicate addresses removed.
• System trace entries after the job-start time stamp in the ASCB for the current address space
  Note: The GTF trace records are not included.

If other options are specified with SUM, the summary dump is dispersed throughout the dump.

,PDATA=ALL

,PDATA=(prob data code)

Specifies the problem program information to be dumped:

ALL

All of the following fields.

PSW

Program status word when the SNAP or ABEND macro was issued.

REGS

Contents of the floating-point registers and general-purpose registers when the SNAP or ABEND macro was issued. Also, contents of the vector registers, vector status register, and the vector mask register when the SNAP or ABEND macro was issued for any task that uses the Vector Facility.

SA

Save area linkage information, program call linkage information, and a back trace through save areas.

SAH

Save area linkage information and program call linkage information.

JPA

Contents of job pack area.

LPA

Contents of active link pack area for the requested task.

ALLPA

Contents of job pack area and active link pack area for the requested task.

SPLS

Virtual storage subpools 0-127, 131-132, 252.

SUBTASKS

The designated task and the program data information for all of its subtasks.

,STORAGE=(strt addr,end addr)

,LIST=list addr

Specifies one or more pairs of starting and ending addresses or a list of starting and ending addresses of areas to be dumped. Each starting address is rounded down to a fullword boundary; each ending address is rounded up to a fullword boundary. The area is then dumped in fullword increments. Callers executing in either 24-bit or 31-bit addressing mode must set the high-order bit of the fullword containing the last address in this list to 1. Callers executing in 31-bit addressing mode must ensure that this bit is cleared in all other addresses in the list because SNAP processing truncates the list at the first address that contains a 1 in the high order bit.

,STRHDR=(hdr addr)

,STRHDR=hdr list addr

Specifies one or more header addresses or the address of a list of header addresses. Each header address must be the address of a one byte header length field, which is followed by the text of the header. The header has a maximum length of 100 characters.

If the STORAGE parameter was specified, the STRHDR (storage header) value must be one or more header addresses. The number of pairs of starting and ending addresses specified for STORAGE must be the same as the number of header addresses specified for STRHDR. If a header is not desired for a storage area, a comma must be used to indicate its absence.

If the LIST parameter was specified, the STRHDR value must be the address of a list of header addresses. The list of addresses must begin on a fullword boundary, and the high order bit of the fullword containing the last address of the list must be set to 1. The number of pairs of starting and ending addresses supplied with the LIST parameter must be the same as the number of addresses in the list supplied with STRHDR. If a header is not desired for a storage area, the STRHDR list must contain a zero address to indicate its absence.

,SUBPLST=sbp list addr

Specifies the address of a list of subpool numbers to be dumped. Each entry in the list must be a two-byte entry and must specify a valid subpool number. The first halfword of the list must contain the number of subpools in the list and must be on a fullword boundary. If you specify an invalid subpool number or a subpool number for which you do not have authorization, the number is skipped and you receive a comment in the dump output indicating the error. If a subpool contains 4k blocks of data that are mapped from a linear data set, the dump includes only the blocks that have changed since the last DIV SAVE function was invoked.

Note: A maximum of seven subpool numbers is permitted on the list form of the SNAP macro pointed to by the DUMPOPT keyword of ABEND or SETRP.

Control is returned to the instruction following the SNAP macro. When control is returned, register 15 contains one of the following return codes: