DB2 Server for VSE & VM: Operation

Formatting DB2 Server for VSE Trace Output

You control the trace formatter by supplying control statements that identify the trace output file. The trace output file can be on tape or disk. If the file is on disk it might be managed by the VSE/VSAM Space Management for SAM Feature, or it might be a standalone SAM file.

Following is an example of job control to invoke the trace formatter. This example contains a DUMPALL parameter. DUMPALL causes the trace formatter to display on SYSLST all the trace records from the trace file. In the example, the tape is mounted on the virtual address 181, and the file ID is "FORMATTER". The ASSGN statement for a trace tape file must always specify SYS004 as the symbolic unit. 



// JOB TRACEJOB
// TLBL ARITRAC,'FORMATTER'
// ASSGN SYS004,181
// EXEC ARIMTRA,SIZE=AUTO
DUMPALL
/*
/&

Your job control statements will differ when the trace file is on disk. If your trace output file is on disk, specify the trace formatter DISK control statement. If you are using both DISK and DUMPALL, DISK must precede DUMPALL.

Following are three examples of starting the trace formatter. The examples show how to run the trace formatter when the trace output is:

The formatter examples work with the corresponding DB2 Server for VSE trace examples shown in Specifying Job Control for a DB2 Server for VSE Trace.

The following is an example of the job control required to invoke the trace formatter when the trace output file is on tape. 



// JOB RUN TRACE FORMATTER
// TLBL ARITRAC,file-id     <-- File-id of trace tape (optional)
// ASSGN SYS004,cuu             Address of tape unit
// EXEC ARIMTRA,SIZE=AUTO
     *
  control statements for trace formatter
     *
/*
/&

Notes:

  1. The tape should be mounted on the physical device specified by cuu before running the job.

  2. The tape file-id must be the same file-id as was specified on the TLBL statement when the tape was created.

  3. The trace formatter requires at least 65K (115K if the trace file is a VSAM-managed file) of virtual storage to run.

The following is an example of the job control required to run the trace formatter when the trace output file resides on DASD and is not VSAM-managed. 



// JOB RUN TRACE FORMATTER
// DLBL ARITRAC,'TRACE.FILE1'
// EXTENT ,VSER01,1,0,301,120
// ASSGN SYS006,195
// EXEC ARIMTRA,SIZE=AUTO
   DISK
     *
   other control statements for trace formatter
     *
/*
/&

Notes:

  1. The DLBL file name must be ARITRAC.

  2. In this example, the DB2 Server for VSE default symbolic unit for DASD input is used (SYS006).

  3. DISK is a trace formatter control statement. DISK is required whenever the trace output file is on DASD.

  4. The trace formatter requires at least 65K (115K if the trace file is a VSAM-managed file) of virtual storage to run.

The following is an example of the job control required to run the trace formatter when the trace output file resides on DASD and is managed by the VSE/VSAM Space Management for SAM Feature. 



// JOB RUN TRACE FORMATTER
// DLBL ARITRAC,'TRACE.FILE1',0,VSAM,DISP=(,DELETE)
// EXEC ARIMTRA,SIZE=AUTO
   DISK
     *
   other control statements for trace formatter
     *
/*
/&

Notes:

  1. The file name on the DLBL statement must be ARITRAC.

  2. The DLBL parameter "VSAM" indicates that this is a VSAM-managed file.

  3. DISP=(,DELETE) indicates that when the file is closed it is to be deleted from the VSAM catalog. If you want to keep the file, specify DISP=(,KEEP).

  4. This example omits the DLBL "CAT=" parameter. It assumes that the trace output file is in the VSAM job catalog.

  5. DISK is a trace formatter control statement. DISK is required whenever the trace output file is on DASD.

  6. The trace formatter requires at least 65K (115K if the trace file is a VSAM-managed file) of virtual storage to run.

COMP and SUBCOMP have been updated for DSC.

Trace Formatter Control Statements

Control statements for the trace formatter select the trace records to be printed. The control statements are identified by these keywords: 

 AGENTNO          HEADER
 COMP             RETCODE
 DATE             SUBCOMP
 DBNAME           TIME
 DISK (VSE Only)  TRACENO
 DUMPALL          USERID
 EXTLUWID

In general, each keyword takes one or more parameters. Each parameter is separated by one or more blanks. Do not use commas to separate the parameters. Each control statement can contain only one keyword, in columns 1 to 71 inclusive, with no continuations. You can supply the control statements in any order. Do not place blank control statements in the input to the trace formatter in DB2 Server for VSE; and do not place blank records in the control statement file, SQLTRFMT SQLTRACE in DB2 Server for VM.

The purpose and syntax of each keyword is described as follows:

AGENTNO nn
defines the ordinal numbers of the agent structures for which trace records are to be formatted. An agent number consists of up to 2 digits. Up to six agent numbers can be specified on the AGENTNO control statement, in any order, separated by one or more blanks.

Certain agent numbers are fixed:

The operator agent is always agent 1.
The checkpoint agent is always agent 2.
In single user mode, agent 3 is the only user agent. In multiple user mode, agent 3 is the ready/recovery agent, and higher numbers are user agents.

If TCP/IP support is active, agent 4 is the TCP/IP agent, and higher numbers are user agents. If TCP/IP support is not active, agent 4 and higher numbers are user agents.

If the AGENTNO keyword is omitted, agent number values are not considered in choosing trace records to be formatted.

COMP CONV

COMP DBSS

COMP DSC

COMP DRRM

COMP RDS

COMP STG

COMP WUM
defines the DB2 Server for VSE or DB2 Server for VM component for which trace records are to be formatted. Only one component can be chosen.

If the COMP keyword is omitted, the component that the trace record describes is not considered in choosing trace records to be formatted. The COMP keyword should not be used with the SUBCOMP keyword.

DATE mm/dd/yy

DATE mm/dd/yy mm/dd/yy
defines the date or date interval for which trace records are to be formatted. If only one date is specified, trace records created on that date are formatted. If two dates are specified, trace records created in that interval are formatted. The dates must be specified in month/day/year notation. Each portion of a date must be specified as two digits; that is, a leading zero must be entered where needed, for example, DATE 01/01/90.

If the date statement is omitted, the date is not considered in choosing trace records to be formatted.

Notes:

  1. Year numbers less than 43 are assumed to be in the 21st century.

  2. A date range which crosses the century boundary cannot be used and the trace formatter must be run twice; once for the desired range in each century.

DBNAME server_name
defines the server name for which trace records are to be formatted. A server name consists of up to 18 characters or numbers. Up to six server names can be specified on the DBNAME control statement, separated by one or more blanks.

If you omit the server name, server name values are not considered when you choose records to be formatted.

DISK (Valid for VSE only)
informs the trace formatter that the file generated by the trace is on DASD. You must specify this keyword when the trace file is on DASD. If you specify both the DISK and the DUMPALL keywords, the DISK keyword must precede the DUMPALL keyword.

If the DISK keyword is omitted, the trace input file is assumed to be a tape file.

DUMPALL
requests that all trace object records be formatted. This keyword takes no parameters. This keyword cannot be combined with any other keywords except with DISK.

EXTLUWID N nnnnnnn
Nnnnnnnn is the eight character SNA NETID of the external logical unit of work for which you want to format trace records. The first character (N) is always required. If you specify the first character only, trace points for all connected SNA NETIDs which begin with that character will be returned. Additional characters up to a total of 35 can be added from left to right so that you can format records for specific SNA NETIDs only.

HEADER
specifies that only the header object of the trace output record is to be formatted. Module names, return codes, and variable data are not displayed. This keyword takes no parameters.

RETCODE P

RETCODE N

RETCODE *
defines the types of return codes for which trace records are to be formatted. Only one character can be specified for the RETCODE parameter. The choices are: 
 P   Positive (Nonzero) Return Codes Only
 N   Negative Return Codes Only
 *   All Nonzero Return Codes

If the RETCODE keyword is chosen, only trace point records with return codes of the specified value are chosen for formatting. If the RETCODE keyword is omitted, the return codes are not considered in choosing trace records to be formatted.

SUBCOMP subcomponent
defines the subcomponents of DBSS, RDS, DRRM, RA, or DSC, for which trace records are to be formatted. The allowable codes are:

For DBSS: 

 DC     Data Control
 DM     Data Manipulation
 ENTRY  DBSS Entry Calls
 EXIT   Returns to RDS from DBSS Entry Calls
 INDEX  Index
 LOCK   Lock Management
 LOG    Log/Recovery Management
 LUW    Logical Unit of Work Management
 SORT   Sort
 STAT   Update Statistics
 STOR   Storage Management

For RDS: 

 AG     Access Generator
 EXEC   Executive
 INT    Interpreter and Authorization
 OPT    Optimizer
 PA     Parser
 AU     Security Audit Trace
 SG     Statement Generator

For DRRM: 

 DICT     DDM/FD:OCA Dictionary and FD:OCA descriptors and data
 GEN      DDM Generator
 PARSE    DDM Parser
 RDIIN    RDIIN Manager

For DSC: 

 AGENT   Agent handling (data stream trace)


 
 COM     Communications

For RA: 

 RA      Resource Adapter Control Flow
 COM     Communications

The SUBCOMP keyword enables you to list the specific subcomponents to be traced. Subcomponents can be specified in any order, each separated by one or more blanks. Up to eight subcomponents can be specified. If the SUBCOMP keyword is omitted, subcomponents are not considered in choosing trace records to be formatted.

The COMP keyword should not be used with the SUBCOMP keyword.

TIME hh:mm:ss hh:mm:ss
defines the time interval for which trace records are to be formatted. The hour:minute:second time specification requires using 24-hour clock notation. Each portion of a time must be entered as two digits; that is, a leading zero must be entered where needed, for example, TIME 09:05:00 14:04:59.

Specifying a time interval that passes through midnight must be done in two different runs of the trace formatter.

It is possible to specify only one time with the TIME keyword. For example, TIME 12:00:00 specifies that only the trace records created during that second of time be formatted.

If TIME is omitted, the time value is not considered in choosing trace records to be formatted.

TRACENO nnnnn
defines the trace point numbers for which trace records are to be formatted. A trace point number consists of up to 5 digits. Up to six trace point numbers can be specified on the TRACENO control statement, in any order, separated by one or more blanks. Trace points are assigned to specific places in the components or modules that make up the DB2 Server for VSE & VM system.

If the TRACENO keyword is omitted, trace point numbers are not considered in choosing trace records to be formatted.

USERID auth_id
defines the authorization IDs for which trace records are to be formatted. An authorization ID consists of up to 8 letters or numbers. Up to six authorization IDs can be specified on the USERID control statement, separated by one or more blanks.

Certain authorization IDs are fixed:

The operator agent (agent 1) is always OPERATOR.
The checkpoint agent (agent 2) is always CHECKPT.
The ready/recovery agent (agent 3 in multiple user mode) is always RECOVERY.
The TCP/IP agent (agent 4 if it exists) is always TCPIP.

If the USERID keyword is omitted, authorization ID values are not considered in choosing trace records to be formatted.

The following example demonstrates the use of trace formatter keywords. Note the following characteristics: 

 Component:  RDS component
 Subcomponent:  Parser
 Trace Numbers:  4400, 4401, 4402
 Date of Creation:  March 11, 1988
 Time of Creation:  Between 9:12:00 AM and 1:12:00 PM
 Agent Number:  4
 User: JOHNDOE

To print a listing from the trace file for all the trace records that have these characteristics, the input control statements to the trace formatter will be as follows: 

 TRACENO  4400 4401 4402
 DATE     03/11/88
 TIME     09:12:00  13:12:00
 AGENTNO  4
 USERID   JOHNDOE

Note:The control statements can be placed in any order. Because the trace-point numbers are known, the COMP and SUBCOMP keywords are not required.

Format of DB2 Server for VSE & VM Trace Output

Each time a trace point is encountered in a function or subcomponent that is activated for trace and the agent or authorization ID is active for trace, trace-point output is produced.

The first printed line is the Trace Header and it has the following format:

TRACEPOINT=nnnn
identifies the trace point number

DBSS_OP=nn

RDS_OP=nn

DSC_OP=nn...
identifies trace point as DBSS, DSC, or RDS components and gives the current DBSS, DSC, or RDS OPCODE being executed. Special OPCODE numbers are assigned to DBSS non-OPCODE functions such as checkpoint, archive, and warm start, among others.

While other components may be listed on this line, their opcodes will always be zero.

The RDS OPCODEs come from the RDIIN control block on external calls to RDS in RDIIN field RDICTYPE. RDS places the OPCODE in field RDAOPCOD in the RDAREA control block for trace and for problem determination.

The DBSS OPCODEs, excluding special OPCODEs as described in the following paragraphs, originate from DBSS interface (DBSI) calls as the OPCODE parameter. These DBSS OPCODEs are placed in field YT1OPCOD in the YTABLE1 control block for trace and for problem determination.

Certain DBSS functions are executed without formal DBSI calls to the agent that executes that function. In YT1OPCOD, DBSS sets special pseudo-OPCODEs to cover a number of these situations as follows:

OPCODE=99:
DBSS performs warm-start DB2 Server for VSE & VM initialization as a result of the initialization parameter STARTUP=W.

OPCODE=98:
DBSS performs database generation and initialization as a result of the DB2 Server for VSE & VM initialization parameter STARTUP=C.

OPCODE=97:
DBSS is initialized and restores the database from an archive tape as a result of the DB2 Server for VSE & VM initialization parameter STARTUP=R.

OPCODE=96:
DBSS is initialized and adds new dbspaces to the database as a result of the DB2 Server for VSE & VM initialization parameter STARTUP=S.

OPCODE=95:
DBSS is initialized and adds new dbextents to the database as a result of the DB2 Server for VSE & VM initialization parameter STARTUP=E.

OPCODE=94:
DBSS is initialized and redefines or formats the log data sets (COLDLOG) as a result of the DB2 Server for VSE & VM initialization parameter STARTUP=L.

OPCODE=93:
DBSS performs an DB2 Server for VSE & VM checkpoint or checkpoint and archive in the checkpoint agent (agent 2).

OPCODE=92:
DBSS performs an asynchronous ROLLBACK or COMMIT of a LUW. This can be caused by conditions such as deadlock and the FORCE operator command.

OPCODE=91:
DBSS executes, in the operator agent, a DB2 Server for VSE & VM operator command from the DB2 Server for VSE & VM operator.

USERID=cccccccc
identifies the DB2 Server for VSE & VM authorization ID.
For STG trace points, agent 0, the userid field will be set to PROTOTYP. PROTOTYP is not an authorized ID, but is set to help identify that the storage operation is from prototype storage and not from general purpose agent storage.
The operator agent, agent 1, always has the authorization ID OPERATOR. The DB2 Server for VSE & VM initialization occurs under that authorization ID.
The checkpoint agent, agent 2, always has the authorization ID CHECKPT.
The ready/recovery agent is agent 3, and can be used in multiple user mode only. Agent 3 always has the authorization ID RECOVERY.
The TCP/IP agent is 4 if TCP/IP support is active. It has the authorization ID TCPIP.

COMP=compname
identifies the name of the subcomponent or function being traced. This is the same as the name specified through the TRACE ON operator command.

AGENT=nn
nn is the ordinal of the DB2 Server for VSE & VM agent structure. The operator is always agent 1. The checkpoint is always agent 2. In single user mode, agent 3 is the only user agent. In multiple user mode, agent 3 is always the ready/recovery agent. In multiple user mode, agents 4 through n are the user agents, where n is the NCUSERS parameter value plus three.
Note:For STG tracing, some trace points will have agent=0 for the PROTOTYP.

If TCP/IP support is active, agent 4 is always the TCP/IP agent and then agents 5 through n are the user agents, where n is the NCUSERS parameter value plus four.

DATE=mm/dd/yy
identifies the date of trace point activation.

DBNAME=cccccccc
is the server name being traced. DBNAME appears only in the trace point header when tracing RA, DRRM or CONV from the application requester.

TIME=hh:mm:ss
indicates the time of trace point activation. Time is adjusted to local time as specified by VSE Job Control through the ZONE JCS, or the VM SYSTIME system generation macro. The time is in 24 hour notation. Thus 2:00 p.m. is 14:00:00. The time zone adjustment is made at Trace Format and Print time.

[LUW_ID='hhhhhhhh'X]
is the DBSS Logical Unit of Work ID. This output line appears for DBSS trace points only.

[EXTLUWID='NETID.LUNAME.LUWID_INSTANCE.LUWID_SEQUENCE_NUM']
is the Logical Unit of Work ID for the DRDA protocol.

NETID
The SNA network associated with the connection. It can be one to eight characters long.

LUNAME
The logical unit associated with the connection. In VM, a logical unit is a gateway. It can be one to eight characters long.

LUWID_INSTANCE
A 12 character timestamp in hex.

LUWID_SEQUENCE_NUM
The LUWID sequence number 0001.

For both level 1 and 2 tracing, except for DBSS entry and DBSS exit trace points, the trace header is always followed by:

For both level 1 and 2 tracing for DBSS entry trace points, the trace header is always followed by: 

 DBSS ENTRY: L_OPCODE='DBSS-opcode-name'

For both level 1 and 2 tracing for DBSS exit trace points, the trace header is always followed by: 

 DBSS EXIT: L_OPCODE='DBSS-opcode-name'
 RETCODE=---n...n
 (RETCODE is the DBSS Return Code)

For all level two trace points and for components having only 1 level of tracing, processing and debugging variables are displayed after the above information. Variables are displayed in the general form:

The L or G prefix indicates that the variable is only locally addressable to the issuing module (L), or is globally addressable through control blocks to all modules (G).

Varname should be the name of the data item (simple entity, structure or substructure) by which the issuing module addresses the data item.

Value-or-string is of the form:

Trace output may also contain printable character strings that are trace point dependent and clarify processing being performed or the data being displayed.

[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]