SNAP call

The SNAP call is used to collect diagnostic information.

This topic contains Product-sensitive Programming Interface information.

Format

Read syntax diagramSkip visual syntax diagramSNAPdb pcbaibi/o area
Call Name DB/DC DBCTL DCCTL DB Batch TM Batch
SNAP X X   X  

Parameters

db pcb
Specifies the address that refers to a full-function PCB that is defined in a calling program PSB. This parameter is an input and output parameter.
aib
Specifies the AIB for the call. This parameter is an input and output parameter. These fields must be initialized in the AIB:
AIBID
Eye catcher. This 8-byte field must contain DFSAIBbb.
AIBLEN
AIB lengths. This field must contain the actual length of the AIB that the application program obtained.
AIBRSNM1
Resource name. This 8-byte, left-justified field must contain the name of a full-function DB PCB.
AIBOALEN
I/O area length. This field must contain the length of the I/O area specified in the call list.
i/o area
Specifies the area in your program that contains SNAP operation parameters. This parameter is an input parameter. The following figure shows the SNAP operation parameters you specify, including:
  • Length for bytes 1 through 2
  • Destination for bytes 3 through 10
  • Identification for bytes 11 through 18
  • SNAP options for bytes 19 through 22
Figure 1. I/O area for SNAP operation parameters
begin figure description - This figure is described in the surrounding text. end figure description.

The following table explains the values that you can specify.

Table 1. SNAP operation parameters
Byte Value Meaning
1-2 xx This 2-byte binary field specifies the length of the SNAP operation parameters. The length must include this 2-byte length field.

When you do not specify operation parameters, IMS uses default values. This chart lists the lengths that result from your parameter specifications.
If you supply values for: And IMS supplies default values for: Then the length (in hexadecimal) is:
Destination, Identification, SNAP options   16
Destination, Identification SNAP options 12
Destination Identification, SNAP options 10
  Destination, Identification, SNAP options 2
If you specify another length, IMS uses default values for the destination, identification, and SNAP operation parameters.
3-10   This 8-byte field tells IMS where to send SNAP output. You can direct output to the IMS log by specifying LOG or bbbbb
  Directs the output to the IMS log. This is the default destination.
dcbaddr Directs the output to the data set defined by this DCB address.

The application program must open the data set before the SNAP call refers to it. This option is valid only in a batch environment. The output data set must conform to the rules for a z/OS® SNAP data set.
ddname Directs the output to the data set defined by the corresponding DD statement. The DD statement must conform to the rules for a z/OS SNAP data set. The data set specified by ddname is opened and closed for this SNAP request.

In a DB/DC environment, you must supply the DD statement in the JCL for the control region.

If the destination is invalid, IMS directs output to the IMS log.
11-18 cccccccc This is an eight-character name you can supply to identify the SNAP. If you do not supply a name, IMS uses the default value, NOTGIVEN.
19-22 cccc This four-character field identifies which data elements you want the SNAP output to include. YYYN is the default.
19   Buffer Pool:
Y Dump all buffer pools and sequential buffering control blocks with a SNAP call.
N Do not dump buffer pools or sequential buffering control blocks with a SNAP call.
20   Control Blocks:
Y Dump control blocks related to the current DB PCB with a SNAP call.
N Do not dump control blocks related to the current DB PCB with a SNAP call.
21 Y Dump all control blocks for this PSB with a SNAP call. Specifying Y in byte 21 produces a snap dump for the current DB PCB request in byte 20 to Y, regardless of the current value.
N Do not dump all control blocks for this PSB with a SNAP call. In this case, the current DB PCB SNAP request in position 20 is used as specified.
19-21 ALL This is equivalent to specifying YYY in positions 19-21.
22   Region:
Y Dump the entire region on the DCB address or data set ddname that you supplied in bytes 3-10 with a SNAP call. IMS processes this request before it acts on any SNAP requests made in bytes 19-21. If the destination is the IMS log, IMS does not dump the entire region. Instead, it processes the request as if you had specified ALL.
N Do not dump the entire region with a SNAP call.
S Dump subpools 0-127 with a SNAP call.

After the SNAP call, IMS can return the AB, AD, or bb (blank) status code. For a description of these codes and the response required, see IMS Version 15.4 Messages and Codes, Volume 4: IMSComponent Codes.

Usage

Any application program can issue this call.

Restrictions

For function shipping in the CICS® environment, the local and remote CICS must both be DBCTL.