This section summarizes the features of Abend-AID’s database diagnostics for the following optional support:

• Abend-AID for Db2
• Abend-AID for IMS
• Abend-AID for IDMS.

 Abend-AID for Db2

Abend-AID for Db2 provides support for IBM’s relational database manager, Db2. It presents the information needed to solve not only everyday but also unique, complex DB2 abends in a few concise report pages.

The Abend-AID for Db2 report provides a diagnostic report containing information about the statement in error and the specific SQL command that failed. It identifies the cause of the error and suggests a course of action.

A comprehensive Db2 Environment section under TSO, CALL, or RRSAF (Recoverable Resource Manager Services Attachment Facility) attach mode processing contains a summary of information to assist you in resolving the problem. This section includes:

• SQL code interpretation
• SQL statement in error
• Interpreted contents of the SQLCA
• Contents of the SQLDA, for dynamic SQL
• Display of the columns referenced
• Names and contents of the host variables
• Plan name, bind time, and bind date
• Package bind information and package precompile information
• Db2 release, subsystem, and authorization ID
• Related information.

The Abend-AID for Db2 report also provides abend return codes with corresponding explanations. This information is especially useful for resolving S04E reason codes.

The following figure illustrates an Abend-AID for Db2 Analysis of Error section for an S04E abend.

 Abend-AID for Db2 Analysis of Error Section – S04E Abend

Using Report Types

Four different situations will produce an Abend-AID report with Db2 support. Each of these situations produces a report with slightly different types of information. Different parts of the Abend-AID report are significant. The following describes the four situations and corresponding importance of the Analysis of Error, Error Location, and Db2 sections of the Abend-AID report. Other sections do not differ among the four report types and should be viewed as needed.

• Non-Db2 system error occurs in a Db2 program:
  • Analysis of Error section is important and should be viewed first.
  • Error Location section contains useful information about the location of the error.
  • Db2 section should be checked for supporting information (for example, the last SQL code returned).
• Db2 system abend occurs (S04E, S04F):
  • Analysis of Error section is important and should be viewed first. Location of the error is found here.
  • Error Location section is not pertinent because the abend does not occur in the application program.
  • Db2 section should always be viewed.
• Negative SQL code – user abend is forced:
  • Analysis of Error section is significant only if customized diagnostic messages are provided for the user abend.
  • Error Location section is not pertinent because the abend does not occur in the application program.
  • Db2 section is most valuable. Location and description of the error is found here. View this section first.
• Negative SQL code – SNAP-AID called by the application program:
  • Analysis of Error section is not present because no abend occurs.
  • Error Location section points to the application program, but the location is the call to SNAP-AID, not where the Db2 error occurred.
  • Db2 section is most valuable. Location and description of the error is found here. View this section first.

If your shop standards do not require the forcing of user abends for negative SQL codes, you should consider using SNAP-AID. The program can then be terminated or continue to execute based on the severity of the error.

Using SNAP-AID to Report Negative SQL Codes

Abend-AID is automatically invoked when an abend occurs. However, when a negative SQL code is encountered, an abend does not occur and program processing continues. Abend-AID for Db2 provides support for more than 500 SQL codes. To obtain complete Db2 information at various points in the program without terminating the program, use SNAP-AID. A simple call to the SNAPAID module in the application program is all that is needed to invoke this support. The following three figures show examples of a SNAP-AID call in an application program.

In SNAP-AID Example for a COBOL Program and SNAP-AID Example for a PL/I Program, the SQLCODE is a field in the SQL Communications Area (SQLCA) that contains the last SQL return code. The RETURN-CODE is the step’s completion code that appears in the job log. It can be used to indicate if further steps of the job should be run.

 SNAP-AID Example for a COBOL Program

 SNAP-AID Example for a PL/I Program

The method shown in the following figure preserves structured programming and brings the call to SNAPAID closer to the statement that produced the error.

 SNAP-AID Example for a COBOL Program

Many shops prefer to issue user abends when negative SQL codes indicate severe errors. The following are examples of coding user abend codes.

In the following figure, the SQLCODE is a field in the SQLCA that contains the last SQL return code. ‘ILBOABN0’ is the COBOL-supplied routine to force an abend. A user-written routine that produces a dump can be used instead of ‘ILBOABN0’.

User Abend Example for a COBOL Program

In the following figure, the SQLCODE is a field in the SQLCA that contains the last SQL return code. PLIRETC is the PL/I-supplied routine to set a return code.

User Abend Example for a PL/I Program

Refer to Using Abend-AID SNAP-AID for additional information on SNAP-AID.

  With TSO, CALL, IMS, or RRSAF Attach Mode

 Whenever an Abend-AID report is produced for a DB2 program, diagnostic information about the last SQL completion code is provided in the DB2 Environment Data section. DB2 support does not require any language processing to pinpoint the exact SQL statement and the host variable names.

The DB2 Environment Data section combines IBM dump, SQLCA, and DB2 catalog information to provide essential data needed to resolve infrequent but complex DB2 errors.

In the TSO, CALL, IMS, or RRSAF attach mode environment, the following information is also provided:

• Full text and statement number of SQL statement in error as well as any related SQL statements
• The source data name of all host variables referenced
• When appropriate and required, the name, type, and table name of all columns referenced
• Bind options, date, and time
• Precompile options
• DBRM library name
• Names and types of all DB2 objects on which the Application Plan is dependent
• DB2 release, authorization ID, subsystem ID, plan name, and DBRM name
• Detailed Plan Package data, including bind, precompile, and dependency information.

TSO/CALL/IMS/RRSAF Attach Mode – SQL Code and Statement in Error through TSO/CALL/IMS/RRSAF Attach Mode – SQLCA and Plan Dependencies show examples of the Abend-AID for Db2 Environment section under TSO, CALL, IMS, or RRSAF attach mode processing.

TSO/CALL/IMS/RRSAF Attach Mode – SQL Code and Statement in Error

TSO/CALL/IMS/RRSAF Attach Mode – General Information and Host Variables Referenced

TSO/CALL/IMS/RRSAF Attach Mode – SQLCA and Plan Dependencies

With IMS or DL/I Attach Mode

IMS or DL/I attach mode support is the same as support for TSO, CALL, or RRSAF attach mode. For all of these attach modes, DB2 catalog information is combined with the user’s parameters to produce a comprehensive DB2 Environment Data section.

Without DB2 Catalog Access

If, for any reason, Abend-AID is not able to access the DB2 catalogs, a DB2 Environment Data section is still available. In this situation, IBM dump and SQLCA information is formatted to provide essential data needed to resolve complex DB2 errors.

When the DB2 catalogs cannot be accessed, the following information is provided:

• Statement number and verb of the SQL statement in error
• DB2 release, authorization ID, subsystem ID, plan name, and DBRM name
• COBOL base locator cell and offset of all host variables referenced in the SQL statement in error. When XLS is used, the host variable names are provided instead of base locator cell/offset.

The following figure shows the SQL Return Code and Db2 General Information areas of the Abend-AID for Db2 Environment Data section. These areas identify the SQL verb in error for the SQL statement returning the SQL code.

Non-Catalog Access – SQL Code and Verb in Error

The following figure shows the Host Variables Referenced area of the Abend-AID report. Because the variable names cannot be accessed from the Db2 catalog, this area includes the COBOL base locator cell and offset of the host variables; or for other languages, the relative addresses.

Non-Catalog Access – Host Variables Referenced

If COBOL XLS is used, Abend-AID for Db2 can provide the data name for each host variable. The following figure shows the same host variables when COBOL XLS is used.

Non-Catalog Access – Host Variables Referenced Using COBOL XLS

Using Db2 Plan Package Support

With Db2 Version 2 Release 3, IBM introduced Db2 Plan Packages, reducing the complexity of Db2 plan management and eliminating time-consuming rebinds of large plans. Abend-AID for Db2 Plan Package support provides the following additional information in the Db2 section of the Abend-AID report:

• Package information
• Package bind information
• Package precompile information
• Package dependencies.

The following figure shows the Db2 General Information area of an Abend-AID for Db2 report with plan package support.

Db2 General Information Section

Using Db2 Stored Procedure Support

Abend-AID for Db2 provides diagnostic information for stored procedures in Language Environment (LE). Stored procedures (user-written applications) run in a special Db2 stored procedure address space. It is difficult to diagnose problems because only the SQLCODE is returned to the calling program. Abend-AID for Db2 provides diagnostic information for easy problem resolution.

The following figure shows Abend-AID for Db2 diagnostic information when the application is a stored procedure.

Db2 Diagnostic and General Information Section

Supported Reason Codes

The following table shows the Db2 subcomponent that are supported by Abend-AID for Db2.

Db2 Subcomponent Support Information

ROLLBACK Statement

Use the Db2 ROLLBACK statement to terminate the current unit of recovery, back out the database changes that were made within that unit of recovery, and start a new unit of recovery. BMC considers ROLLBACK to be an important part of error recovery processing. Note the method that Abend-AID uses to handle Db2 diagnosis during ROLLBACK.

When a ROLLBACK occurs, the control blocks that Abend-AID relies on to diagnose Db2 problems are freed. If Abend-AID is invoked after a ROLLBACK, Abend-AID finds the control blocks for the new unit of recovery and reports that the DB2 connection was not utilized. For ROLLBACK recovery, we recommend a call to the module SNAPAID before the ROLLBACK is issued. SNAP-AID allows Abend-AID to properly diagnose the Db2 problem and return control back to the program. When the program regains control, you can issue the ROLLBACK, and the integrity of the database is preserved.

File-AID for DB2 Access

If you’re using the Abend-AID Viewer to view Db2 reports, you can directly access a Db2 database through File-AID for DB2. A current version of File-AID for DB2 must be available on the operating system. The File-AID for DB2 access option is available on the Db2 Information menu in the Abend-AID Viewer. See DB2 Information Menu for more information. This option is available only if you access the Abend-AID Viewer via the ISPF viewing access method, as explained in Logging onto the Abend-AID Viewer.

 Abend-AID for IMS

Abend-AID for IMS provides information about the IMS DB and TM environments, the application program, and the abending program’s PCBs and JCBs. In addition, the last six calls to the database are listed. Abend-AID for IMS diagnoses all IMS user abends and gives both the cause of the error and the solution. Additional information such as the contents of DFSPRPX0 and DFSECP is provided, if appropriate.

Abend-AID for IMS Section – COBOL XLS through Abend-AID for IMS PCB and Call Trace Summary show Abend-AID for IMS examples.

 Abend-AID for IMS Section – COBOL XLS

 Abend-AID for IMS Section – COBOL Basic Support

 Abend-AID for IMS Section – Database Calls (Batch Statistics)

 Abend-AID for IMS PCB and Call Trace Summary

Abend-AID for IMS consists of modules that locate and interpret IMS control blocks. It includes specialized diagnostic modules for IMS-generated user abends. An Abend-AID for IMS report provides you with the following information:

• Extended Error Analysis section to diagnose the cause of most IMS user abends and to provide possible solutions to the problem.
• Contents of the Key Feedback Area in an expanded format.
• Trace of the last six calls to the IMS database for every database PCB in the application program’s PSB. All non-blank status codes are displayed with their respective descriptions.
• Display of the current segment from the I/O area.
• Segment Search Arguments (SSA) displayed in an easy-to-read format. The segments used in the most recent IMS call are identified and printed with their applicable names and lengths.
• DFSPRPX0 and DFSECP modules printed in hexadecimal format to assist in the resolution of the abend.
• Database call statistics from the PST accounting area, for reference when debugging loops and reviewing I/O.
• IMS environment-specific information:
  • Type of IMS environment
  • IMS release number
  • Name of application program and language
  • PSB Name
  • Location of last IMS call in the program
  • Terminal PCBs
  • Alternate terminal PCBs
  • Database PCBs with index PCBs.
• From the IMS PSB:
  • Program name
  • Programming language
• From other control blocks:
  • Release of IMS
  • Region type
  • PSB Name
• When it is possible to determine the last IMS call:
  • Program name and the displacement into the program from which the call was made.
  • PCB used in this call is printed as the current PCB.
• For the current PCB:
  • Key feedback area
  • Database PCBs, the SSA (segment search argument) used in this call
  • Segments returned in the I/O area.
• Information for database PCBs:
  • PCB address, name, number
  • Database name
  • Segment level
  • Status code
  • Process options
  • Segment name last retrieved
  • Key length
  • Number of segments
  • Call trace from the JCB
  • Key feedback area.
• For terminal PCBs:
  • PCB address
  • Logical terminal name
  • Status code from the last call using this PCB
  • JCB call trace for this PCB. Up to the last six calls to the database are given.

File-AID Access

From the IMS section, you can directly access an IMS database through File-AID for IMS. Edit and Browse commands in the report take you into File-AID edit and browse modes within the database. A current version of File-AID for IMS must be available on the operating system.

 Abend-AID for IDMS

Abend-AID for IDMS captures all data prior to rollback, in contrast to the normal dump, which can display data only after rollback is completed. Thus, a true analysis of the data is provided at the time of abend.

You can obtain the following information from an Abend-AID for IDMS report:

• A specialized Error Analysis section that includes:
  • The text and location of the IDMS command in error
  • The particular error status code
  • An error message.
• An IDMS Command Trace section that assists in tracking the program flow of the last ten calls. This section identifies:
  • Program reference statement of each call
  • Complete text of the database command
  • Status code of each call
  • Database key cross-reference with the time and actual database (DB) key in both hexadecimal and decimal.
• A Currency Table that provides references for current:
  • Record
  • Set
  • Area.
• Record information that includes:
  • Current and previous record contents for all record types
  • Working-storage record areas when they differ from current records.
• Database information that includes:
  • Number of commits
  • Most recent commit
  • Database keys in decimal
  • Database statistics section.
• IDMS environmental data that includes:
  • Subschema
  • Version number
  • Region type
  • IDMS release number
  • Central version system ID.

The following figure shows a sample Abend-AID for IDMS Analysis of Error Section for COBOL XLS.

 Abend-AID for IDMS Analysis of Error Section - COBOL XLS

Abend-AID for IDMS Analysis of Error Section - COBOL Basic Support shows a sample Abend-AID for IDMS Analysis of Error Section for COBOL Basic Support. This section reports on the status code of the call directly preceding the ROLLBACK. Usually, this call is the failing database call. If you have made additional database calls between the failing database call and the ROLLBACK, Abend-AID for IDMS still reports on the last call preceding ROLLBACK.

 Abend-AID for IDMS Analysis of Error Section - COBOL Basic Support

The following figure shows an example of Abend-AID for IDMS call tracing.

 Abend-AID for IDMS Command Trace

The following figure shows an example of Abend-AID for IDMS currency information. Currency tables list the database keys translated to page and line, program reference (DML offset, sequence number or statement number), and usage mode for each area. At a glance, you can see what currency has been established.

 Abend-AID for IDMS Currency Information

The following figure shows an example of the current and previous record areas. Contents for all records are shown. Working-storage record contents are displayed if they differ from the current record area.

 Abend-AID for IDMS Current and Previous Record Areas

With SNAP-AID

Abend-AID for IDMS is available for CA-IDMS Release 12.01 and more current, and for programs that are run in the central version or local mode. It automatically provides IDMS data for non-IDMS abends such as a S0C7 system abend.

With SNAP-AID, you can dynamically obtain complete IDMS information during program execution. If you choose to continue program processing when not using the auto-status precompile option, call the module SNAPAID in your program to produce a complete Abend-AID report with IDMS-specific information. See Using Abend-AID SNAP-AID for additional information.

You can set this option to Y if a potential for S106 (out of memory) abends exists with certain application programs. The //ABNLIFRE DD statement is also available for individual application programs. If specified in the execution JCL, this statement causes the work areas that are acquired by Abend-AID for IDMS for each bind run unit to be freed when a finish is issued.