Tracing DL/I calls with image capture

DL/I image capture program (DFSDLTR0) is a trace program that can trace and record DL/I calls issued by batch, BMP, and online (DBCTL environment) programs. You can also use the image capture program with command-level programs, and you can produce calls for use as input to DFSDDLT0.

You can use the image capture program to:
  • Test your program

    If the image capture program detects an error in a call it traces, it reproduces as much of the call as possible, although it cannot document where the error occurred, and cannot always reproduce the full SSA.

  • Produce input for DFSDDLT0 (DL/I test program)

    You can use the output produced by the image capture program as input to DFSDDLT0. The image capture program produces status statements, comment statements, call statements, and compare statements for DFSDDLT0. For example, you can use the image capture program with a command-level program, to produce calls for DFSDDLT0.

  • Debug your program

    When your program terminates abnormally, you can rerun the program using the image capture program. The image capture program can then reproduce and document the conditions that led to the program failure. You can use the information in the report produced by the image capture program to find and fix the problem.

Using image capture with DFSDDLT0

The image capture program produces the following control statements that you can use as input to DFSDDLT0:
  • Status statements
    When you invoke the image capture program, it produces the status statement. The status statement it produces:
    • Sets print options so that DFSDDLT0 prints all call trace comments, all DL/I calls, and the results of all comparisons.
    • Determines the new relative PCB number each time a PCB change occurs while the application program is executing.
  • Comments statement
    The image capture program also produces a comments statement when you invoke it. The comments statements give:
    • The time and date IMS started the trace
    • The name of the PSB being traced

    The image capture program also produces a comments statement preceding any call in which IMS finds an error.

  • Call statements

    The image capture program produces a call statement for each DL/I call or EXEC DLI command the application program issues. It also generates a CHKP call when it starts the trace and after each commit point or CHKP request.

  • Compare statements

    If you specify COMP on the DLITRACE control statement, the image capture program produces data and PCB comparison statements.

Running image capture online

When you run the image capture program online, the trace output goes to the IMS log data set. To run the image capture program online, you issue the IMS TRACE command from the z/OS® console.

If you trace a BMP and you want to use the trace results with DFSDDLT0, the BMP must have exclusive write access to the databases it processes. If the application program does not have exclusive access, the results of DFSDDLT0 may differ from the results of the application program.

The following diagram shows TRACE command format:

Figure 0.
Read syntax diagramSkip visual syntax diagram ⁄ TRACE SET ONOFF PSB psbname NOCOMPCOMP
SET ON|OFF
Turns the trace on or off.
PSB psbname
Specifies the name of the PSB you want to trace. You can trace more than one PSB at the same time, by issuing a separate TRACE command for each PSB.
COMP|NOCOMP
Specifies whether you want the image capture program to produce data and PCB compare statements to be used with DFSDDLT0.

Running image capture as a batch job

To run the image capture program as a batch job, you use the DLITRACE control statement in the DFSVSAMP DD data set.

In the DLITRACE control statement, you specify:

  • Whether you want to trace all of the DL/I calls the program issues or trace only a certain group of calls.
  • Whether you want the trace output to go to:
    • A sequential data set that you specify
    • The IMS log data set
    • Both sequential and IMS log data sets

If the program being traced issues CHKP and XRST calls, the checkpoint and restart information may not be directly reproducible when you use the trace output with DFSDDLT0.

When you run DFSDDLT0 in an IMS DL/I or DBB batch region with trace output, the results are the same as the application program's results, but only if the database has not been altered.

For information about the format of the DLITRACE control statement in the DFSVSAMP DD data set, see Defining DL/I call image trace.

Example of DLITRACE

This example shows a DLITRACE control statement that traces the first 14 DL/I calls or commands that the program issues, sends the output to the IMS log data set, and produces data and PCB comparison statements for DFSDDLT0.
//DFSVSAMP DD *
DLITRACE LOG=YES,STOP=14,COMP
/*

Special JCL requirements

The following are special JCL requirements:
//IEFRDER DD
If you want log data set output, this DD statement is required to define the IMS log data set.
//DFSTROUT DD|anyname
If you want sequential data set output, this DD statement is required to define that data set. If you want to specify an alternate DDNAME (anyname), it must be specified using the DDNAME parameter on the DLITRACE control statement.

The DCB parameters on the JCL statement are not required. The data set characteristics are:

  • RECFM=FB
  • LRECL=80

Notes on using image capture

  • If the program being traced issues CHKP and XRST calls, the checkpoint and restart information may not be directly reproducible when you use the trace output with the DFSDDLT0.
  • When you run DFSDDLT0 in an IMS DL/I or DBB batch region with trace output, the results are the same as the results of the application program provided the database was not altered.

Retrieving image capture data from the log data set

If the trace output is sent to the IMS log data set, you can retrieve it by using utility DFSERA10 and a DL/I call trace exit routine, DFSERA50. DFSERA50 deblocks, formats, and numbers the image capture program records to be retrieved. To use DFSERA50, you must insert a DD statement defining a sequential output data set in the DFSERA10 input stream. The default ddname for this DD statement is TRCPUNCH. The card must specify BLKSIZE=A, where A can be any multiple of 80 ranging from 80 to 32720. For example, 27920.

For example, you can use the following examples of DFSERA10 input control statements in the SYSIN data set to retrieve the image capture program data from the log data set:

  • Print all image capture program records: 
    Column 1       Column 10
OPTION         PRINT OFFSET=5,VALUE=5F,FLDTYP=X
  • Print selected image capture program records by PSB name: 
    Column 1       Column 10
OPTION         PRINT OFFSET=5,VALUE=5F,COND=M
OPTION         PRINT OFFSET=25,VLDTYP=C,FLDLEN=8,
               VALUE=psbname,COND=E
  • Format image capture program records (in a format that can be used as input to DFSDDLT0): 
    Column 1       Column 10
OPTION         PRINT OFFSET=5,VALUE=5F,COND=M
OPTION         PRINT EXITR=DFSERA50,OFFSET=25,FLDTYP=C
               VALUE=psbname,FLDLEN=8,DDNAME=OUTDDN,COND=E
The DDNAME= parameter is used to name the DD statement used by DFSERA50. The data set defined on the OUTDDN DD statement is used instead of the default TRCPUNCH DD statement. For this example, the DD appears as: 
//OUTDDN DD ...,DCB=(BLKSIZE=27920),...