The trace facility lets you trace functions and subcomponents at varying levels of detail. If tracing is active, the database manager writes trace records to an output file, or to memory and then to an output file, whenever execution reaches an internal trace point.
After tracing is complete, you can use the trace formatter supplied with the database manager to select, format, and display or print records from the trace file. Refer to Formatting DB2 Server for VM Trace Output and Formatting DB2 Server for VSE Trace Output for descriptions of the trace formatter.
To use tracing, you must:
The trace output file is usually on tape, and is created with IBM standard (EBCDIC) tape labels as a default. You can, however, direct tracing to a CMS file as described later in this chapter. IBM provides an application program, the trace formatter, to select and print trace records from the trace file.
The trace facility requires a CMS FILEDEF command for the trace output file. A FILEDEF command for standard label tape processing is provided in the SQLSTART EXEC. You can override the supplied FILEDEF command by issuing your own FILEDEF command before invoking the SQLSTART EXEC. You must specify the PERM option on your CMS FILEDEF commands if you are running single user mode and the program is written in a language other than Assembler.
The trace file can be a standard labeled tape or unlabeled tape or a CMS file. If the trace tape file is to be multivolume, you must use standard labels. The SQLSTART EXEC does not enter a CMS LABELDEF command. The SQLSTART EXEC specifies standard label (SL) processing on the FILEDEF command. If you want to change the tape label processing, enter appropriate CMS FILEDEF and LABELDEF commands before you enter SQLSTART. You must ensure that the ddname for both the FILEDEF and LABELDEF is ARITRAC. For more information on DB2 Server for VM tape support, refer to the DB2 Server for VM System Administration manual. For more information about tape label processing in CMS, refer to the VM/ESA: CMS User's Guide manual.
The output of the trace can be directed to either tape or disk.
To direct the output to tape, include a TLBL statement in your job control for generating a trace. Omit any ASSGN statement for the trace tape unit. The database manager dynamically assigns and unassigns the trace tape unit.
The database manager creates a trace output file on tape with IBM* standard (EBCDIC) tape labels. A block size of 4096 bytes is used.
An example of a TLBL statement for a trace output file is as follows:
// TLBL ARITRAC,'TRACE.FILE2' |
| Note: | The TLBL statement must have the file name parameter specified as ARITRAC. All other parameters are optional. |
The trace tape is never rewound except at end-of-volume.
To direct the output to disk, you need a DLBL, an EXTENT, and an ASSGN statement. If the file is managed by the VSE/VSAM Space Management for SAM Feature, the EXTENT statement may be optional, and the ASSGN statement is not applicable. In any case, the file name on the DLBL statement must be ARITRAC.
When the database manager is tracing to DASD, it uses a block size of 4088 bytes for the trace file.
The following is an example of the required job control for a trace output DASD SAM file (not managed by VSAM).
// DLBL ARITRAC,'TRACE.FILE1' // EXTENT ,VSER01,1,0,301,120 // ASSGN SYS007,195 |
Notes:
If you do not want to use the default symbolic unit (SYS007), you must specify the desired symbolic unit as the first EXTENT parameter and in the ASSGN statement. If you are also using the DB2 Server for VSE & VM accounting facility with output to DASD, either the trace or the accounting file must be directed to a symbolic unit other than SYS007.
The following is an example of the job control required for a trace output DASD SAM file that is managed by the VSE/VSAM Space Management for SAM Feature.
// DLBL ARITRAC,'TRACE.FILE1'0,VSAM,DISP=(OLD,KEEP), C
RECORDS=1000,RECSIZE=4088
// EXTENT ,VSER01
|
| Note: | Unlike standalone SAM, the VSE/VSAM Space Management for the SAM feature lets
you extend the file. It also automatically provides secondary space
allocation should you exceed the primary allocation. You can monitor
the actual space usage in the file by using the VSAM Access Method
Services.
|
In multiple user mode, you can start tracing using the following:
| Note: | If you specify the TRACDRRM or TRACWUM initialization parameters, you receive trace output only if you have users who are operating under the DRDA protocol. |
The initialization parameters allow the later parts of initialization to be traced and do not require any operator command entry. The operator command TRACE ON allows tracing to be started at any time after initialization is complete. It also has options to trace only specified agents or a specified authorization ID.
Tracing can be stopped either by allowing the system to end (normally or abnormally) or by issuing the operator command TRACE OFF.
In single user mode, tracing can be started only through the TRACCONV, TRACDBSS, TRACDSC, TRACRDS, TRACSTG initialization parameters. Tracing is stopped only when the application server ends (normally or abnormally).
The trace facility, as a default, directs its output to tape. You can, however, direct trace output to memory or to a CMS file. For more information on directing trace output to memory, see Starting a Trace or Appendix A, DB2 Server for VSE & VM Initialization Parameters.
You can direct trace output to a CMS file because the database manager uses the CMS simulation of OS QSAM to process the trace file, and CMS OS QSAM is device independent.
To trace to a CMS file, use the following CMS FILEDEF command before starting the application server.
FILEDEF ARITRAC DISK filename filetype filemode (PERM |
Notes:
After issuing the above CMS FILEDEF command, you can start the application server. As usual, depending on whether you are in single or multiple user mode, you can start tracing through the initialization parameters or through the TRACE operator command.
If you start tracing through the TRACCONV, TRACDBSS, TRACDRRM, TRACDSC, TRACRDS, TRACSTG, and TRACWUM initialization parameters, the application server prompts for the cuu of the trace tape. When tracing to a CMS file, specify in the cuu parameter the virtual device number of the CMS minidisk containing the trace file.
Similarly, if initiating tracing with the TRACE operator command, specify the virtual device number of the trace minidisk for the cuu parameter of the TRACE ON command.
If you do the following:
the trace CMS output file only contains the trace output of the second or last activation of tracing. This can be avoided in either of two ways:
If the trace fills the CMS minidisk on which the trace file resides, the following occurs:
When the application server is running with tracing active, and the system ends (normally or abnormally), the application server displays message ARI0099I if the trace file is successfully closed. The same situation results if the TRACE OFF command is entered. If this message is not displayed, the file has not been closed and some trace data has been lost.
| Note: | It is possible to enable tracing but produce no trace output, for example, when you trace only a specified authorization ID. In this situation, the file is opened and closed successfully, but no CMS file is created. |
See the DB2 Server for VSE & VM Database Administration manual for information on how to trace the VSE resource adapters.
You can trace functions and subcomponents within the following components: