Skip to Content
Information

This site will undergo a brief period of maintenance on Friday, 18 December at 12:30 AM Central/12:00 PM IST. During a 30 minute window, site availability may be intermittent.

Information
Space announcement This documentation space provides the same content as before, but the organization of the content has changed. The content is now organized based on logical branches instead of legacy book titles. We hope that the new structure will help you quickly find the content that you need.

Using SNAP-AID

This section describes how to use Abend-AID’s SNAP-AID facility. You can use SNAP-AID to produce Abend-AID output without terminating the program. The SNAP-AID report includes working storage and file information. SNAP-AID is invoked by a simple call to the module SNAPAID from COBOL, PL/I, Assembler, or FORTRAN programs. SNAP-AID can help in resolving logic problems or when working with a Db2 or IDMS database management system.

SNAP-AID General Information

Beginning with Abend-AID Release 9.5, the SNAPAID module has been enhanced to operate in any addressing mode (24-bit, 31-bit, or 64-bit). The SNAPAID module is distributed with an addressing mode of 31 (AMODE=31), a residency mode of ANY (RMODE=ANY), and REENTRANT and REUSABLE attributes. This AMODE and RMODE combination satisfies the requirements of most SNAP-AID users. Prior to Abend-AID Release 9.5, SNAP-AID did not support being called by a program executing in 64-bit mode and was distributed AMODE=ANY and RMODE=24. It has always been REENTRANT and REUSABLE. SNAP-AID users can do either of the following:

  • If the SNAPAID module is included within a load module for which some other combination of AMODE or RMODE is desired, it can be re-linked or re-bound. However, you may encounter error messages from the IBM binder. To avoid binder error messages, you can re-link or re-bind the SNAPAID module that BMC distributes using the IBM linkage editor or binder with any AMODE or RMODE. Refer to the IBM DFSMS/MVS program management manual or the z/OS MVS program management user's space and reference manual for a list of valid combinations of AMODE and RMODE.
  • IX_Assembler_programs •An alternate method is to call the SNAPAID module dynamically. For Assembler programs, issue a LOAD for the SNAPAID module and a CALL to it.

Beginning with Abend-AID Release 9.5, the SNAPAID module has been reduced in size. It now loads and calls another module that performs all of the functions that versions prior to 9.5 performed.

If you have combined the SNAPAID module with the calling program through use of the linkage editor or binder instead of calling it dynamically, you do not have to replace it. SNAPAID versions prior to Release 9.5 will continue to operate correctly. However, re-linking or re-binding a load module to replace an older SNAPAID module with a Release 9.5 or more current version has the following advantages:

  • SNAPAID passes all of the 64-bit register contents to Abend-AID. Consequently, a program executing in AMODE=64 can call SNAPAID.
  • If statically loaded (included with the calling program within a load module), the resulting load module requires less storage space because the SNAPAID module is smaller.
  • If statically loaded, the calling program is able to take advantage of future enhancements to the SNAP-AID process without the need to re-link or re-bind the load module because of the Release 9.5 or more current version’s loading and calling a processing module.

Assembler programmers, note the following:

  • General register 13 must point to a save area that is at least 72 bytes long. Upon being entered in AMODE24/31, SNAP-AID saves all general register contents into this save area. Upon being entered in AMODE64, the SNAP-AID Release 9.5 or more current version saves bits 32 through 63 of all the general registers into this save area.
  • All GPR, AR, and CR register contents that exist at the time SNAP-AID is called are restored except for general register 15, which contains a return code. See SNAP-AID Return Codes for more information.
  • The save area that is pointed to by general register 13 must reside in a storage area that is addressable by the SNAP-AID caller while in the AMODE existing at the time SNAP-AID is called. An AMODE24 caller cannot pass a save area that resides in 31-bit or 64-bit storage. An AMODE31 caller cannot pass a save area that resides in 64-bit storage.

Invoking SNAP-AID

Warning

Note

Do not call SNAP-AID from a program running in access register mode. Exit access register mode before calling SNAP-AID, then return to access register mode when execution of your program resumes

To invoke SNAP-AID with a DD specified, perform the following steps:

  1. Code a call to the module SNAPAID or SNPAID for FORTRAN. The following figure shows a SNAPAID call from a COBOL program.SNAPAID Call in a COBOL Program

    aausnpad00135.jpg

    The following figure shows SNAPAID calls from a PL/I program.

    SNAPAID Calls in a PL/I Program

    aausnpad00137.jpg

  2. Compile and link-edit or bind the program using one of the following:
    • The DYNAM compiler option, which is available for COBOL

    • A //SYSLIB DD statement for the link edit that includes the Abend-AID load library: 

      //SYSLIB DD DSN=SYS1.ABENDAID,DISP=SHR

    •  A linkage editor INCLUDE statement for the SNAPAID subroutine module: 

      //SYSIN DD *
       INCLUDE SYSLIB(SNAPAID)
  3. Add an //ABENDAID DD statement to the execution JCL.

The SNAP-AID report is written to an output destination chosen in the same manner as is done for a normal Abend-AID report. The only exception to this is that a SNAP-AID report cannot be written to the SYSUDUMP, SYSABEND, or SYSMDUMP IBM dump DDs. Normally, the SNAP-AID report is written using the site default report shared directory named by CWROUTE. However, you can override this destination by specifying as follows:

  • //ABNLTERM DD, which overrides
  • CWEXIT02, which overrides
  • CWJOBTAB, which overrides
  • CWROUTE routing group specification, which overrides
  • CWROUTE site default report shared directory specification.

To write the SNAP-AID report to the //ABENDAID DD, use CWEXIT02, CWJOBTAB, or a CWROUTE routing group to designate that the report be written to SYSOUT. See Advanced-configuration space for more information about routing report output.

 SNAP-AID Execution

SNAP-AID performs identically to Abend-AID with the following exceptions:

  • An //ABENDAID DD statement must be present to produce SNAP-AID output. If one is not present, it can be dynamically allocated.
  • SNAP-AID reports the pseudo abend code SNAP.
  • The SNAP-AID report is entitled “Abend-AID Snapshot.”
  • The system produces no IBM dump.
  • The //ABNLIGNR DD statement has no effect on SNAP-AID and does not suppress SNAP-AID output.
  • The //ABNLIGNS DD statement can be used to suppress SNAP-AID output.

 Using SNAP-AID and Code Debug TSO

To take full advantage of the Abend-AID SNAP-AID feature while using Code Debug TSO, the ABENDAID DD must be allocated to the test session prior to the SNAP-AID call. An Abend-AID report can also be generated any time during the interactive session by issuing the AA SNAP command. If the AA SNAP command is used, the //ABENDAID DD will be dynamically allocated by Code Debug TSO.

  SNAP-AID Return Codes

Return codes from SNAP-AID are:

0:

OK. SNAP-AID is complete.

4:

SNAP-AID cannot locate the required Abend-AID modules, or a compatible Abend-AID hook is not installed. SNAP-AID is bypassed.

8:

No //ABENDAID DD statement is available, or the //ABENDAID DD statement DCB attributes are invalid.

12:

There is not enough memory to allow SNAP-AID to run. SNAP-AID is bypassed.

16:

SNAP-AID execution abnormally terminated.

20:

A subsequent call has been made to SNAP-AID, but SNAP-AID has been disabled for one of the reasons listed above.

24

SNAP-AID cannot process the request because the TIOT (Task Input/Output Table) is not available.

SNAP-AID Parameter List

The SNAP-AID parameter list lets you do the following:

  • Customize your SNAP-AID report by selecting or suppressing specified report sections. These report sections include:
    • Location in program of the call to SNAP-AID
    • Register contents and PSWs
    • Trace of program flow and program attributes
    • Program Storage
    • File information - data management control blocks
    • IMS diagnostic information and PCBs
    • IDMS diagnostic and status information
    • Db2 diagnostic and status information
    • Abend-AID for WebSphere MQ diagnostic and status information
    • Current COBOL sort information.
  • Cause dynamic allocation of the //ABENDAID DD. The creation of the dynamic allocation request can receive input from various sources and employs a hierarchy in deciding which source to create the dynamic allocation parameters from:
    1. Data passed in the parameter list takes precedence over all other sources.

    2. For optional parameter values not passed, model information can be extracted from one of the following sources:

      • An existing //CEEDUMP DD
      • An existing //SYSUDUMP DD
      • An existing //PLIDUMP DD
      • An existing //PL1DUMP DD.

      If the //CEEDUMP DD was dynamically allocated, it will not be considered eligible for a model. If more than one of the above DDs exists, the first one found in the above order will be used as a model.

    3. If no existing //CEEDUMP, //SYSUDUMP, //PLIDUMP, or //PL1DUMP DD is found, the default values established by the Abend-AID installer will be used.
    4. If the Abend-AID installer did not establish one or more defaults, the Abend-AID defaults will be used.
  • Display storage ranges between selected addresses.

To code a SNAP-AID parameter list, define the parameter interface in your program with the following fields:

  • Identification: This six-byte field must be coded as SNPRML.
  • Action flag: This field is used to select the action (display or suppress) that SNAPAID applies to the sections specified. Valid values are:
    • 0 (default): Display all report sections
    • 1: Display specified report sections
    • 2: Suppress specified report sections.
  • Section selection flags: When the action flag is set to 1 or 2, use the section selection flags to identify the report sections to be displayed or suppressed. Valid values are:
    • 0 (default): Do not apply the action specified by the action flag.
    • 1: Apply the action specified by the action flag.
  • Parameter list version: When the version is set to 1, the dynamic allocation parameters are recognized. Otherwise, they are not recognized.
  • Comment: This ten-character field is specified in the program to identify the SNAPAID call that generated the report. The content of the comment field is displayed in the DESC field on the report data set directory.

  • Dynamic allocation request: When the request is set to D, dynamic allocation of the //ABENDAID DD is requested. When the request is set to F, dynamic allocation and FREE=CLOSE are requested. Otherwise, dynamic allocation is not requested.

    Warning

    Note

    If an //ABNLTERM DD is allocated by your JCL or dynamically allocated because of a global request, then the SNAP-AID report will be routed to the //ABNLTERM allocation and not to the //ABENDAID allocation.

  • Output class: When the class is set to any valid JES class, that class is used for the allocation. A class of * denotes usage of the MSGCLASS value. Specifying an invalid class or no class causes the model or default class to be used.
  • Hold the output: When the optional hold parameter is set to Y, the output will be placed in the hold queue by JES. When hold is set to N, the output will be directed to the output queue by JES. Otherwise, whether to hold output or not will be determined by the model or default hold specification.
  • Destination: This optional eight-character field specifies the node to which you want to direct the output. Consult the DD DEST section of your JCL reference manual for more information on nodes. If you leave this field blank, the destination will be determined by the model or default destination value.
  • User ID: This optional eight-character field specifies the user ID at the node destination where that you want the output routed. If you leave this field blank, the user ID will be determined by the model or default user ID value.
  • Output writer name: This optional eight-character field specifies a custom output writer to be used to process the output. Note that the use of this parameter is mutually exclusive with user ID. If both are specified, user ID will be used. Output writer names are site-dependent.

  • User form name: This optional four-character field specifies the form name to be used for the output. If you leave this field blank, the form name will be determined by the model or default form name value. User form names are site-dependent.

    Warning

    Note

    The 

    Abend-AID

     installation library hlq. CTL contains parameter list interface layouts: member PRMICBL for COBOL, member PRMIPLI for PL/I, and member PRMIASM for Assembler.

  • You can use two additional parameters to specify a range of storage to be displayed in the Program Storage section. The field name specified as the second parameter defines the beginning storage address. The third name specified as the third parameter defines the ending storage address. Subsequent pairs of parameters are processed as additional ranges of storage to be displayed. If these parameters are used, the specified ranges of storage replace the Program Storage section.

The following are examples of SNAPAID calls in the Procedure Division to produce a SNAP-AID report:

Example 1: Without using a parameter list:

  • COBOL: 

    CALL 'SNAPAID'.

  • Assembler:

    LA R1,0 Indicate 'no parameter list'
    CALL SNAPAID

Example 2: Using a parameter list:

  • COBOL:

    CALL 'SNAPAID' USING PARM-INTERFACE.

  • PL/I:

    CALL SNAPAID (PARM_INTERFACE)

  • Assembler:

     OI   ADDR0,X'80' Set end-of-list bit
    LA   R1,PARMLIST Point to parameter list
    B    AROUND_LIST
    PARMLIST DS   0F
    ADDR0 DC      A(SNPMITR) Address of SNAPAID parameters
    AROUND_LIST EQU *
    CALL SNAPAID

Example 3: Using a parameter list specifying a range of addresses:

  • COBOL:

    CALL 'SNAPAID' USING PARM-INTERFACE
    WS-RANGE1-BEG WS-RANGE1-END.

  • PL/I:

    CALL SNAPAID (PARM_INTERFACE,
    RANGE1_BEG,RANGE1_END);

  • Assembler:

     OI  ADDR2,X'80' Set end-of-list bit
    LA   R1,PARMLIST Point to parameter list
    B    AROUND_LIST
    PARMLIST DS   0F
    ADDR0  DC   A(SNPMITR) Address of SNAPAID parameters
    ADDR1  DC   A(BEGDATA) Address of storage dump start
    ADDR2  DC   A(ENDDATA) Address of storage dump stop
    AROUND_LIST EQU *
    CALL SNAPAID

Example 4: Using a parameter list specifying ranges of addresses:

  • COBOL:

    CALL 'SNAPAID' USING PARM-INTERFACE
    WS-RANGE1-BEG WS-RANGE1-END
    WS-RANGE2-BEG WS-RANGE2-END.

  • PL/I:

    CALL SNAPAID (PARM_INTERFACE
    RANGE1_BEG,RANGE1_END,
    RANGE2_BEG,RANGE1_END);

  • Assembler:

     OI ADDR4,X'80' Set end-of-list bit
    LA R1,PARMLIST Point to parameter list
    B AROUND_LIST
    PARMLIST DS 0F
    ADDR0  DC   A(SNPMITR) Address of SNAPAID parameters
    ADDR1  DC   A(BEGDATA) Address of storage dump start
    ADDR2  DC   A(ENDDATA) Address of storage dump stop
    ADDR3  DC   A(BEGDATA#) Address of storage dump start
    ADDR4  DC   A(ENDDATA#) Address of storage dump stop
    AROUND_LIST EQU *
    CALL SNAPAID


Warning

Note

The 

Abend-AID

 installation library hlq .CTL contains sample programs that produce SNAP-AID reports using a parameter list: member PRMSCBL for COBOL, member PRMSPLI for PL/I, and member PRMSASM for Assembler.

Parameter Interface Defined in a COBOL Program

aausnpad00139.jpg

Parameter Interface Defined in a PL/I Program

aausnpad00141.jpg

Parameter Interface Defined in an Assembler Program

aausnpad00143.jpg

Suppressing SNAP-AID

SNAP-AID output can be suppressed without removing the call to SNAP-AID from your program. The way you do this depends on how the //ABENDAID DD statement is allocated.

  • If the //ABENDAID DD is allocated by a DD statement in the execution JCL, remove the //ABENDAID DD statement from the JCL.
  • If the //ABENDAID DD is dynamically allocated because of a request in the SNAP-AID parameter list, add the //ABNLIGNS DD to the execution JCL.

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*

BMC AMI DevX Abend-AID 17.02