DB2 Server for VSE. Operations Guide / Handbooks (2004-2007)

show users

Status of Connected Users:

1998-07-24

10:13:41

users are connected to SQL/DS.

SQL/DS users are active.

User ID: PETERS

SQL ID: SMITH

not processing

SQL/DS users are waiting.

User ID: DORA

SQL ID: TASK115

User ID: MICHAEL

SQL ID: MIKE2

SQL/DS users are inactive.

User ID: JENNY

SQL ID: JENNY

SQL/DS agents are available.

SQL/DS user connections are available.

ARI0065I Operator command processing is complete.

Figure 83. A Typical SHOW USERS Display on a VM Operator Console or ISQL Terminal

START PROC

►► START PROC

▼

procedure-name

►◄

AUTHID authid

The START PROC command can be used to:

v Allow the database administrator to restart a stored procedure that was stopped

by the STOP PROC command

v Allow the database administrator to refresh a stored procedure after replacing a

stored procedure’s load module or phase. This is required because the IBM

Language Environment loads stored procedures and does not refresh the loaded

copy as long as the Language Environment is intact.

The START PROC command starts a stored procedure that was stopped previously.

If the stored procedure was not stopped prior to the START PROC command, a

message is displayed and no action is taken. In this case, since the procedure is left

in STARTED status, the command is considered to be successful.

Upon successful completion of the START PROC command, queued requests for

the specified stored procedures are allowed to begin execution. Additionally, the

abnormal termination counts for the specified stored procedures are set to zero.

Note: This command can be issued only from the operator console.

procedure-name Identifies the procedure to be started. An asterisk (’*’) contained in

the last position of a procedure name acts as a wildcard. For

example, ’ABC*’ indicates the command should be applied to all

stored procedures whose names begin with ’ABC’.

Message ARI4151I is displayed for each procedure started. If the

name specified does not contain a wildcard, and is not found,

message ARI4152E is displayed.

Note: procedure-name cannot be AUTHID or ACTION, because

these are treated as keywords by the START PROC and

STOP PROC commands.

Chapter 3. Operating the Application Server

137

authid

The authorization ID for this stored procedure. This field is used

for procedures that can be run only from one authorization ID.

Generally, if no authorization ID is specified, only the public

version of the stored procedure (that is, the one that does not have

an AUTHID associated with it) is started. However, START PROC *

is a special case. If START PROC * is issued, all versions of all

procedures are started.

Marks all procedures as eligible to be invoked by the SQL CALL

statement.

The following are examples of the START PROC command.

START PROC *

START PROC PROC2*

START PROC PROC1

START PROC MYPROC AUTHID USER1

START PROC * AUTHID USER1

START PROC MYPROC AUTHID USER1 YOURPROC AUTHID USER2

The first statement above starts all stored procedures. The second starts the public

version (that is, the version that does not have an AUTHID associated with it) of

all procedures whose names start with ’PROC2’. The third statement starts the

public version of one stored procedure, PROC1. The fourth example starts the

version of procedure MYPROC that is accessible only by authorization ID USER1.

The fifth starts all procedures that are accessible only by authorization ID USER1.

The last statement starts the version of MYPROC that is accessible only by USER1

and the version of YOURPROC that is accessible only by USER2.

The following example shows the output from the START PROC command.

start proc proc* tquery2 yyy

Starting stored procedure(s)

1997-07-21

13:56:22

ARI4151I START PROC successful for PROC1.

ARI4151I START PROC successful for PROC2.

ARI4153I Stored procedure PROC3 is already started.

ARI4151I START PROC successful for PROC3.

ARI4151I START PROC successful for TQUERY2.

ARI4154I Stored procedure YYY is not found.

ARI4152E START PROC failed for YYY.

Reason Code 1.

ARI0065I Operator command processing is complete.

start proc storproc1 authid user1

Starting stored procedure(s)

1997-09-21

14:01:00

ARI4151I START PROC successful for STORPROC1 for AUTHID

USER1.

ARI0065I Operator command processing is complete.

Figure 84. A Typical START PROC Display on a VM Operator Console

START PSERVER

►► START PSERVER

▼

name

►◄

GROUP

138

Operation

The START PSERVER command is used to start a stored procedure server, establish

a connection between it and the database machine, and initialize the stored

procedure environment.

When the START PSERVER command is issued, the database manager checks the

cached information from SYSTEM.SYSPSERVERS for a row in which the value of

the column PSERVER matches the name specified on the command. If a row is

found, the action taken depends on the status:

v If the status is STARTED, message ARI4164I is issued and no action is taken.

v If the status is STARTING, message ARI4165I is issued, followed by message

ARI4167E with reason code 5.

v If the status is STOPPING, message ARI4165I is issued, followed by message

ARI4167E with reason code 6.

v If the status is STOPPED, the cache is updated to indicate that the stored

procedure server is starting and processing of the command continues.

If the name is not found, message ARI4163I is displayed. In this case, if only one

stored procedure server is to be started, the command terminates. If more than one

stored procedure server is to be started, the database manager continues with the

next one.

Starting a stored procedure server is a two part process. In the first part, when the

START PSERVER command is issued, the status of the stored procedure server is

updated to STARTING. A storage block is reserved, to be used for the connection

between the database manager and the stored procedure server. The second part

takes place the first time SQL CALL is processed. If the stored procedure server

that is to run the stored procedure has a status of STARTING, the database

manager completes the START PSERVER processing prior to sending the SQL

CALL statement to the stored procedure server.

Note: If the stored procedure server does not start successfully within the time

specified by the PTIMEOUT initialization parameter, message ARI4168I is

displayed and the command terminates.

This command can be issued only from the operator console.

GROUP

Indicates that any names that are specified are server group names,

rather than individual server names. This enables the database

administrator to start all servers in a given group with a single

command.

name

The name of the stored procedure server, or of the stored

procedure server group, that is to be started.

An asterisk (’*’) in the last position of the name acts as a wildcard.

For example, ’ABC*’ indicates that the command should be applied

to all stored procedure servers (or server groups, if the GROUP

keyword is specified) that have names beginning with ’ABC’.

Note: name cannot be any of the following:

v GROUP

v IMPLICIT

v NOIMPLICIT

v NORMAL

v QUICK

because these are treated as keywords by the START

PSERVER and STOP PSERVER commands.

Chapter 3. Operating the Application Server

139

Starts all stored procedure servers. Note that ’START PSERVER

GROUP *’ and ’START PSERVER *’ have the same result - all

stored procedures servers will be started.

The following are examples of the START PSERVER command.

START PSERVER *

START PSERVER SERV1

START PSERVER SERV1*

START PSERVER GROUP GRP1 GRP2

The first example starts all stored procedure servers for the database. The second

statement starts SERV1 only. The third starts any server whose name starts with

’SERV1’. The last statement starts all servers in groups GRP1 and GRP2.

The following example shows the output from the START PSERVER command.

start pserver *

Starting stored procedure server(s)

1997-09-21

14:23:06

Starting stored procedure server PSERV1

Starting stored procedure server PSERV2

ARI4164I Stored procedure server DEFSERV

is already started.

ARI4165I START PSERVER cannot be processed for SERYYZ

because it has a status of STARTING.

ARI4167E START PSERVER for SERYYZ failed.

Reason Code 5.

ARI0065I Operator command processing is complete.

start pserver group pserv

Starting stored procedure server(s)

1997-09-21

14:37:40

ARI4165I START PSERVER cannot be processed for PSERV1

because it has a status of STARTING.

ARI4167E START PSERVER for PSERV1 failed.

Reason Code 5.

ARI4165I START PSERVER cannot be processed for PSERV2

because it has a status of STARTING.

ARI4167E START PSERVER for PSERV2 failed.

Reason Code 5.

ARI0065I Operator command processing is complete.

start pserver seryyy seryyx

Starting stored procedure server(s)

1997-09-21

14:37:40

ARI4163I Stored procedure server SERYYY is not defined.

ARI4167E START PSERVER for SERYYY failed.

Reason Code 1.

ARI4166I Unable to acquire storage for a pseudoagent

for server SERYYX.

ARI4167E START PSERVER for SERYYX failed.

Reason Code 3.

ARI0065I Operator command processing is complete.

Figure 85. A Typical START PSERVER Display on a VM Operator Console

START TCPIP

►► START TCPIP

►◄

TCPPORT nnnnn

The START TCPIP command is used to restart TCP/IP support. Once the TCP/IP

support for the application server is initiated, a TCP/IP agent is created to handle

all TCP/IP related functions. If any TCP/IP function failure was detected by the

140

Operation

TCP/IP agent, the TCP/IP support for the application server will be disabled. It is

possible to restart the TCPIP support for the application server without recycling

the application server.

TCPIP

Requests to restart TCP/IP support using the port number

previously used during database startup.

TCPPORT nnnnn

Requests to restart TCP/IP support using the port number nnnnn

specified. nnnnn must be a number within 1 and 65535.

Note: For VSE, the same TCP/IP port number can be used among different

application servers to initialize TCP/IP support. In this case, the last server

using the duplicate port number will become the target server owning the

port. All later incoming connect requests using this port number will be

connected to this target server. To avoid misdirected connection requests,

duplicate port numbers should not be used.

STOP PROC

ACTION QUEUE

▼

►► STOP PROC

procedure-name

►◄

AUTHID authid

ACTION REJECT

AUTHID authid

The STOP PROC command is introduced to allow the database administrator to

temporarily stop access to one or more stored procedures. The database

administrator can choose to either queue or reject requests to run a stored

procedure that has been stopped.

The database administrator may need to stop access to one or more stored

procedures for any of the following reasons:

v Stop usage of a stored procedure that is not behaving correctly.

v Add or replace the load module or phase associated with a stored procedure.

When STOP PROC is issued, the database manager looks for the procedure in the

cache. If it is found, the status of the procedure is updated, and message ARI4155I

is displayed indicating that the command was successful. If the procedure is not

found, message ARI4154I is displayed, and then message ARI4157E is displayed,

indicating that the command was not successful.

The database manager automatically performs a STOP PROC ACTION REJECT

operation on any stored procedure that exceeds the installation-defined maximum

abnormal termination count.

The STOP PROC command prevents the database manager from accepting SQL

CALL statements for one or more stored procedures. The STOP PROC command

does not prevent CALL statements that have already been assigned to a stored

procedure server from running.

Chapter 3. Operating the Application Server

141

The effects of the STOP PROC command do not persist after SQLEND has been

issued. If the installation wishes to permanently disable a procedure, any of the

following actions can be taken:

v Update the LOADMOD column in the SYSTEM.SYSROUTINES table entry, to

identify a nonexistent load module or phase.

v Use the DROP PROCEDURE statement to remove the row associated with the

stored procedure from the SYSTEM.SYSROUTINES table.

v Rename the load module or phase associated with the stored procedure.

v Delete the load module or phase associated with the stored procedure.

Note: This command is valid only when issued at the operator console.

procedure-name

Identifies the procedure to be stopped. An asterisk (’*’) contained in the

last position of a procedure names acts as a wildcard. For example, ’ABC*’

indicates that the command should be applied to all stored procedures

whose names begin with ’ABC’.

Note: procedure-name cannot be AUTHID or ACTION, because these are

treated as keywords by the START PROC and STOP PROC

commands.

authid The authorization ID for this stored procedure. This field is used for

procedures that can be run only from one authorization ID. Generally, if no

authorization ID is specified, only the public version of the stored

procedure (that is, the one that does not have an AUTHID associated with

it) is stopped. However, STOP PROC * is a special case. If STOP PROC * is

issued, all versions of all procedures are stopped.

Stops all stored procedures.

ACTION

Identifies the action to be taken when an SQL CALL statement is received

while the STOP PROC command is in effect. If the STOP PROC command

is issued multiple times for a given procedure, the action taken is

determined by the ACTION keyword on the most recent STOP PROC

command.

QUEUE

Updates the cached information for the procedure with a status of

STOP-QUE, which causes the request to be queued until the stored

procedure is started via the START PROC command, or until the

request exceeds the installation timeout value. This is the default.

REJECT

Updates the cached information for the procedure with a status of

STOP-REJ, which causes the request to be rejected.

The following are examples of the STOP PROC command.

STOP PROC *

STOP PROC PROC2*

STOP PROC PROC1

STOP PROC PROC1 ACTION REJECT

STOP PROC MYPROC AUTHID USER1

The first statement above stops all stored procedures. The second stops the public

version (that is, the version that does not have an AUTHID associated with it) for

all procedures whose names start with ’PROC2’. The third statement stops the

142

Operation

public version of one stored procedure, PROC1. The fourth example also stops

procedure PROC1, but changes the cached status to STOP-REJ, so that further

attempts to call this procedure will be rejected rather than queued. The last

example stops the procedure MYPROC, which is accessible only by authorization

ID USER1.

The following example shows the output from the STOP PROC command.

stop proc proc* tquery1 tquery2 authid user2 yyy action queue

Stopping stored procedure(s)

1997-09-21

15:02:04

ARI4155I STOP PROC successful for PROC1.

ARI4156I New calls to stored procedure PROC1

will be QUEUED.

ARI4155I STOP PROC successful for PROC2.

ARI4156I New calls to stored procedure PROC2

will be QUEUED.

ARI4155I STOP PROC successful for PROC3.

ARI4156I New calls to stored procedure PROC3

will be QUEUED.

ARI4159I Stored procedure TQUERY1 is already stopped.

ARI4155I STOP PROC successful for TQUERY1.

ARI4156I New calls to stored procedure TQUERY1

will be QUEUED.

ARI4155I STOP PROC successful for TQUERY2 for AUTHID

USER2.

ARI4156I New calls to stored procedure TQUERY2

with AUTHID USER2 will be QUEUED.

ARI4154I Stored procedure YYY is not found.

ARI4157E STOP PROC failed for YYY.

Reason Code 1.

ARI0065I Operator command processing is complete.

stop proc badproc action reject

Stopping stored procedure(s)

1997-09-21

15:09:07

ARI4159I Stored procedure BADPROC is already stopped.

ARI4155I STOP PROC successful for BADPROC.

ARI4156I New calls to stored procedure BADPROC

will be REJECTED.

ARI0065I Operator command processing is complete.

Figure 86. A Typical STOP PROC Display on a VM Operator Console

STOP PSERVER

NOIMPLICIT

NORMAL

▼

►► STOP PSERVER

name

►◄

GROUP

IMPLICIT

QUICK

The STOP PSERVER command is used to stop the handler on a stored procedure

server, sever the connection between the stored procedure server and the database

machine, and stop the stored procedure server.

When the STOP PSERVER command is issued, the database manager checks the

cached information from SYSTEM.SYSPSERVERS for a row in which the value of

the column PSERVER matches the name specified on the command. If such a row

is not found, message ARI4163I is issued. In this case, if only one stored procedure

server is to be stopped, the command terminates. If more than one stored

procedure server is to be stopped, the database manager continues with the next

one. Note that the stored procedure server does not have to be started for the

Chapter 3. Operating the Application Server

143

STOP PSERVER command to be successful. This can be useful, for example if the

database administrator wants to enable implicit starts for a procedure server that

was stopped with the NOIMPLICIT option. In this case the database administrator

would issue the STOP PSERVER command for that procedure server, specifying

IMPLICIT. A STOP PSERVER NORMAL can also be overruled by a STOP

PSERVER QUICK. However, a STOP PSERVER QUICK cannot be overruled by a

subsequent STOP PSERVER NORMAL.

Note: This command can be issued only from the operator console.

GROUP

Indicates that any names that are specified are server group names,

rather than individual server names. This enables the database

administrator to stop all servers in a given group with a single

command.

name

The name of the stored procedure server, or of the stored

procedure server group, that is to be stopped.

An asterisk (’*’) in the last position of the name acts as a wildcard.

For example, ’ABC*’ indicates that the command should be applied

to all stored procedure servers (or server groups, if the GROUP

keyword is specified) that have names beginning with ’ABC’.

Note: name cannot be any of the following:

v GROUP

v IMPLICIT

v NOIMPLICIT

v NORMAL

v QUICK

because these are treated as keywords by the START

PSERVER and STOP PSERVER commands.

Stops all stored procedure servers. Note that ’STOP PSERVER

GROUP *’ and ’STOP PSERVER *’ have the same result - all stored

procedures servers will be stopped.

IMPLICIT/NOIMPLICIT

Determines whether the database manager can implicitly activate

the stored procedure server. When the database manager is looking

for a stored procedure server to use to run a stored procedure,

there is a situation in which it will issue the START PSERVER

command to start a stored procedure server, which will then be

used to run the stored procedure. This is known as an implicit

start.

When the STOP PSERVER command is issued, the

IMPLICIT/NOIMPLICIT option defaults to NOIMPLICIT.

However, any stored procedure server that have not been explicitly

stopped since the database manager was started can be implicitly

started. In other words, the STOP PSERVER command must be

issued to disallow implicit startups of stored procedure servers.

Note that a status of NOIMPLICIT is not maintained after

SQLEND. This means that servers that were stopped with the

NOIMPLICIT option prior to an SQLEND must be explicitly

stopped after the database manager is restarted if implicit startups

are to be disallowed.

144

Operation

QUICK/NORMAL

Determines whether a stored procedure that is currently running in

the server being stopped should be allowed to finish. Specifying

NORMAL will allow the procedure to end normally, and after it

finishes, processing of the STOP PSERVER command will continue.

Specifying QUICK will terminate the stored procedure

immediately. The default is NORMAL. In either case, no new

stored procedure will be started in the server being stopped.

The following are examples of the STOP PSERVER command.

STOP PSERVER *

STOP PSERVER SERV1

STOP PSERVER SERV1*

STOP PSERVER GROUP GRP1 GRP2

The first example stops all stored procedure servers for the database. The second

statement stops SERV1 only. The third stops any server whose name starts with

’SERV1’. The last statement stops all servers in groups GRP1 and GRP2.

The following example shows the output from the STOP PSERVER command.

stop pserver pserv1 implicit

Stopping stored procedure server(s)

1997-09-21

15:42:53

ARI4171I Stored procedure server PSERV1

has been stopped. It can be implicitly started.

ARI0065I Operator command processing is complete.

stop pserver pserv1*

Stopping stored procedure server(s)

1997-09-21

15:44:43

ARI4172I Stored procedure server PSERV1

is already stopped.

ARI4171I Stored procedure server PSERV1

has been stopped. It cannot be implicitly started.

ARI4171I Stored procedure server PSERV10

has been stopped. It cannot be implicitly started.

ARI4173I Stored procedure server PSERV15 is waiting for

stored procedure PROCX to finish.

Stopping stored procedure server PSERV15

ARI4173I Stored procedure server PSERV16 is waiting for

stored procedure PROCY to finish.

Stopping stored procedure server PSERV16

ARI0065I Operator command processing is complete.

ARI4171I Stored procedure server PSERV16

has been stopped. It cannot be implicitly started.

ARI4171I Stored procedure server PSERV15

has been stopped. It cannot be implicitly started.

stop pserver group group1 group2

Stopping stored procedure server(s)

1997-09-21

16:09:10

ARI4172I Stored procedure server PSERV1

is already stopped.

ARI4171I Stored procedure server PSERV1

has been stopped. It cannot be implicitly started.

ARI4171I Stored procedure server PSERV2

has been stopped. It cannot be implicitly started.

ARI4171I Stored procedure server PSERV3

has been stopped. It cannot be implicitly started.

ARI0065I Operator command processing is complete.

Figure 87. A Typical STOP PSERVER Display on a VM Operator Console

Chapter 3. Operating the Application Server

145

Chapter 4. Recovering from System or Media Failures

This chapter contains information on recovering from system and media failures.

The first part of this chapter discusses how to restart the application server if the

system ends abnormally. The second part, Resolving CICS In-Doubt Logical Units

of Work, discusses how to resolve logical units of work that have not been

committed or rolled back when you restart the application server. CICS in-doubt

logical units of work can only occur in a DB2 Server for VM VSE guest sharing

environment. The final part of this chapter discusses what to do if you have a

DASD failure.

General Recovery

While the application server is processing, serious errors can occur. These errors

can cause the operating system, the CICS subsystem, or the application server to

end abnormally. The errors can be detected by the following:

v Hardware

v Operating system

v Other subsystems

v Operator

v application server

When an error causes the application server to end abnormally, it displays error

messages and reason codes. Also, if the error condition appears to be an internal

error, a minidump is sent to the application server console. A minidump is sent to

the display device indicated in the DSPLYDEV initialization parameter on a VSE

system. You should save all this information for problem determination and refer

to the DB2 Server for VSE & VM Diagnosis Guide and Reference manual.

First Failure Data Capture support is also available in a VM/ESA system to help in

problem determination if the following conditions exist:

v You specify AUTO for the PROTOCOL parameter of the SQLSTART EXEC and

the requester connects using DRDA.

v An error occurs in the DRDA portions of the database manager code.

With First Failure Data Capture support, if an error occurs, relevant diagnostic

information, control blocks, and data areas are captured at the error detection point

in a VM console and sent to the print queue of the application server or requester.

For further information on first failure data capture support, see the DB2 Server for

VSE & VM Diagnosis Guide and Reference manual.

For general recovery, restart the application server the same way you would

usually start it. For example, in VSE:

// JOB MULTI

// EXEC PROC=ARIS75DB

// EXEC PROC=ARIS75PL

// EXEC ARISQLDS,SIZE=AUTO,PARM=’PARMID=WARM1’

And in VM,

147

SQLSTART DBNAME(server-name) ID(MYBOOT) PARM(PARMID=WARMSTRT)

After you restart the application server, you must resolve any in-doubt logical

units of work. In-doubt logical units of work can only occur for VSE guests

accessing an application server on VM.

Resolving DRDA 2 In-Doubt Logical Units of Work

A DRDA 2 in-doubt logical unit of work, also know as a distributed unit of work

(DUOW), occurs when phase one of the commit processing was completed

successfully but phase two did not. A prepare to commit log record for the unit of

work was written but the commit log record was not. This situation can occur

when a system failure occurs somewhere at the point in time after the prepare to

commit has occurred and before the second phase of the commit has occurred.

The system failure could be a DB2 Server for VSE & VM failure, a network failure,

a failure on VM CRR for VM or a failure on CICS for VSE, or a failure on the

application requester.

When a DUOW is in-doubt, it holds a real agent on the application server. The

SHOW CONNECT command would show that a real agent is being held and that

it prepared for commit or rollback.

show connect

Status of Connected Users

1998-04-07

13:42:03

Checkpoint agent is not active.

User Agent:

User-ID: SYSA

SQL-ID: VSEMCH12

is prepared for COMMIT or ROLLBACK.

VM ID = VSEMCH12

Coordinator = DBDCCICS

Resource Adapter = 0

Transaction= ABC

Sigon ID= SYSA

Terminal= D080

Users are active.

Users are waiting.

Users are inactive.

Agents are available.

User connections are available.

ARI0065I Operator command processing is complete.

Figure 88. SHOW CONNECT Example of DUOW

To distinguish a DUOW in-doubt agent from a CICS in-doubt agent, look at the

Resource Adapter value. If the resource adapter has a value of 254, it is a DUOW

in-doubt on VM. If the resource adapter has a value of 255 is a DUOW in-doubt on

VSE. If the resource adapter has any other value it is a CICS in-doubt. The value in

our example is 254, so this is a VM DUOW. For more information we issue the

SHOW INDOUBT command.

148

Operation

show indoubt

Status of in-doubt units of work

1997-03-05

13:46:54

TRANID: 26CD User ID: GMERKE

is prepared for COMMIT or ROLLBACK.

LUWID: CAIBMOML.OMXNV108.D6BD1D33FA93.0001

EXTNAM: ADHOC.EXE

01CC0001

Requester: DDCS/2

V2.1.1

at BEDROCK

Package: GMERKE.ADHOC

Section: 1

PTC state started: 1997-03-05

13:40:32

Heuristic state started: N/A

Damage: No

ARI0065I Operator command processing is complete.

Figure 89. SHOW INDOUBT Example of DUOW

The SHOW INDOUBT command gives more information for the DUOW. CICS

in-doubt units of work will not appear in the SHOW INDOUBT display. This

example shows that this DUOW has not been resolved yet. This can be determined

because the state is prepared for COMMIT or ROLLBACK and the heuristic state

started time is N/A and the damage is no.

Normally, in-doubt units of work are resolved automatically by resynchronization

recovery. In VM, resynchronization recovery occurs shortly after the application

server has been initialized. It is driven by the VM CRR recovery server. In VSE,

resynchronization recovery occurs when the DRDA 2 TRUE is enabled for the

application server. This happens when an application requester tries to establish a

DRDA 2 connection to the application server. If it is successful, there would be no

in-doubt agent displayed by the SHOW CONNECT command and there would be

no in-doubt units of work displayed by the SHOW INDOUBT command. If it is

unsuccessful, the DUOW must be resolved manually.

The logs on the application requester must be examined to determine what action

should be taken. The application requester is the coordinator of the DUOW. Most

application requesters also have commands to show which units of work are

in-doubt and what there status is. DB2 Common Server has the “DB2 LIST

INDOUBT TRANSACTIONS” command. DB2 for MVS has the “DISPLAY

THREAD(*) TYPE(INDOUBT) LOCATION(*)” command. The information from the

application requester should be used to determine if the DUOW should be

committed or rolled back.

The FORCE command is used to resolve the DUOW. The SHOW CONNECT

command tells us the in-doubt agent is number 1. If the decision is to commit the

transaction, then the FORCE 1 COMMIT command would be issued. Since this is a

DUOW in-doubt, you will be prompted to confirm this action. If you are sure,

reply 1 for yes and the in-doubt agent will be committed. A subsequent SHOW

CONNECT command will show that the agent is free. A subsequent SHOW

INDOUBT command will show that the in-doubt was heuristically committed.

show indoubt

Status of in-doubt units of work

1997-03-05

14:06:54

TRANID: 26CD User ID: GMERKE

is COMMITTED-H.

LUWID: CAIBMOML.OMXNV108.D6BD1D33FA93.0001

EXTNAM: ADHOC.EXE

01CC0001

Requester: DDCS/2

V2.1.1

at BEDROCK

Package: GMERKE.ADHOC

Section: 1

PTC state started: 1997-03-05

13:40:32

Heuristic state started: 1997-03-05

14:05:07

Damage: Unknown

ARI0065I Operator command processing is complete.

Chapter 4. Recovering from System or Media Failures

149

The heuristic state started time is updated with the time that the FORCE command

was performed. The damage is set to unknown. If resynchronization recovery is

performed after the DUOW in-doubt was forced, damage may result. If the

in-doubt was committed and recovery asked commit to be done, then damage is

update to no. Similarly, damage is no if the in-doubt was rolled back and recovery

asked rollback to be done. However, damage is yes if the in-doubt was committed

and recovery wanted rollback or if the in-doubt was rolled back and recovery

wanted commit.

If a DUOW in-doubt was resolved manually, the entry in the SHOW INDOUBT

display will remain there until it is removed with the RESET INDOUBT command.

The RESET INDOUBT command should not be used until the database

administrator is sure that the in-doubt has been correctly resolved at all of the

participating sites of the DUOW.

Useful CRR Commands (Valid for VM only)

DB2 for VM uses CRR (Coordinated Resource Recovery) to manage distributed

unit of work activity. When an in-doubt unit of work is created in DB2 for VM, the

CRR recovery server will also have information regarding it. This information can

be seen using the “CRR QUERY LUWID” CRR command. If the CRR QUERY

LUWID command were to be issued for the in-doubt agent described above, the

following information would be displayed on the CRR console:

crr query luwid 178

Time: 15:20:45

CRR QUERY LUWID - VMSYSR

Date: 03/06/97

LUNAME - CAIBMOML.OECGW001

LUWID

Token

▌1▐CAIBMOML.OMXNV108.D6BD1D33FA93.0001

00000178

Name

Process

▌2▐SQLMACGM

RESYNCHRONIZATION PENDING

Syncpoint Role

Syncpoint State

Status

INITIATOR CASCADE

COMMITTED

Transaction Tag

▌3▐DB2 FOR VM

5.1.0

PACKAGE: GMERKE.ADHOC

Initiator Name

CAIBMOML.OMXNV108 SQLMACGM

Recovery TPN

’06F2’X

Recovery Token

Index

CAIBMOML.OMXNV108.20B5A76838B5AA31

▌4▐

Resync Role

Resync State

Access Userid

RESYNC NEEDED

SQLMACGM

Resources

*LOCAL SQLMACGM

Recovery TPN

SQLMACGM

Recovery Token

Index

▌6▐

000026CD

▌5▐

Resync Role

Resync State

Access Userid

▌8▐ RESYNC NEEDED

RESYNC NEEDED ▌7▐

SQLMACGM

DMS5BC3065I Operator command processing complete

Here are some notes on how this information relates to the information displayed

by SHOW INDOUBT at the DB2 for VM application server:

▌1▐

This is the LUWID of the in-doubt transaction. It should match the LUWID

displayed on the SHOW INDOUBT command.

150

Operation

▌2▐

This is the RESID for the DB2 for VM Application Server. It indicates at

which DB2 for VM server the SHOW INDOUBT command should be

issued.

▌3▐

This is a transaction tag set up by DB2 for VM. It consists of the following

information:

v Identification of the database (i.e. DB2 for VM).

v The version, release and modification level of the database (i.e. 5.1.0).

v The name of the executing package (i.e. PACKAGE: GMERKE.ADHOC).

Note that in some cases this can say ″PACKAGE: NONE″. This means

that the no package was active at the time.

▌4▐

This index number indicates the first of two protected resources displayed

by the CRR command. This refers to the protected conversation with the

remote requester (and its sync point manager).

Note: The index number can be used with the “CRR RESYNC” CRR

command to heuristically force this resource from CRR. See VM/ESA

CMS File Pool Planning, Administration, and Operation for more

details.

▌5▐

This index number indicates the second of two protected resources

displayed by the CRR command. This refers to the resource at the DB2 for

VM application server itself.

Note: The index number can be used with the “CRR RESYNC” CRR

command to heuristically force this resource from CRR. See VM/ESA

CMS File Pool Planning, Administration, and Operation (SC24-5751), for

more details.

▌6▐

The recovery token is DB2 for VM’s internal logical unit of work identifier.

This should match the TRANID value displayed by SHOW INDOUBT. If

this value is zero, then the unit of work at DB2 for VM was read-only.

▌7▐

This is the state of the unit of work according to CRR. A value of

“RESYNC NEEDED” indicates that resynchronization recovery must still

be done. When resynchronization recovery has completed successfully, this

value changes to “COMMITTED” or “BACKOUT” depending on what was

required.

▌8▐

This indicates the role that CRR is taking on for this logical unit of work. A

value of “RESYNC NEEDED” indicates that resynchronization has started.

When resynchronization recovery has completed successfully, this value

changes to “FORGET”.

When resynchronization recovery has completed successfully at DB2 for VM, the

CRR QUERY LUWID command will show information about this unit of work

until resynchronization has completed with the requester’s sync point manager.

That is, when resource for “index 1” of the unit of work (as displayed by the CRR

QUERY LUWID command) has been resynchronized, CRR will forget about this

luwid.

The following CRR operator command may be used to manage activity at the CRR

operator console:

CRR ERASE LU

Erases specified LU name and TPN entries from

the CRR log name table

CRR ERASE LUWID

Erases CRR log records for a specified LUWID

Chapter 4. Recovering from System or Media Failures

151

instance, which prevents any further CRR recovery

server activity on this LUWID instance

CRR QUERY LOG

Displays the status of the CRR log minidisks

CRR QUERY LOGTABLE Displays LU names and TPNs in the CRR log

name table

CRR QUERY LU

Displays status of logical units of work known to

this CRR recovery server and associated with the

specified LU name

CRR QUERY LUWID

Displays status of sync point processing and

resynchronization processing for an LUWID

instance known to this CRR recovery server

CRR RESUME

Restarts the automatic periodic retry of

resynchronization for a specified LUWID that was

suspended by the CRR SUSPEND command and

also bypasses the timed wait interval

CRR RESYNC

Provides a heuristic response for an unavailable

protected resource or protected conversation so

resynchronization can continue

CRR SUSPEND

Stops the automatic periodic retry of

resynchronization for a specified LUWID until the

CRR operator enters the CRR RESUME command

These CRR commands are discussed in chapter “CRR Administration” of the

VM/ESA: CMS File Pool Planning, Administration, and Operation manual.

Resolving CICS In-Doubt Logical Units of Work

A logical unit of work is a sequence of SQL statements. Users control when logical

units of work begin and end. They expect all SQL statements within a logical unit

of work either to finish successfully as a unit or fail as a unit.

When the system fails, the logical units of work that were in progress at the time

of the failure must be resolved. Usually, the application server automatically

resolves outstanding logical units of work the next time you start the system.

If a failure occurs when a CICS online user was in the process of ending

(committing) a logical unit of work, your intervention may be required. The logical

units of work that were being committed at the time of failure are in-doubt logical

units of work.

In the CICS subsystem, the CICS restart resynchronization facility automatically

resolves in-doubt units of work when you enter the CIRB or CIRA transactions. To

activate this facility, you must update the CICS tables to include the

resynchronization transactions.

You must manually resolve in-doubt logical units of work if the CICS restart

resynchronization facility fails. The procedures are listed below.

If you enter the CIRB or CIRA transaction without resolving the in-doubt logical

units of work, the CIRB transaction lists the units that must be resolved, issues

diagnostic messages, and ends.

152

Operation

To resolve in-doubt logical units of work, you must enter the SHOW ACTIVE,

SHOW CONNECT or SHOW SYSTEM command. (The latter two issue the SHOW

ACTIVE command internally.) The SHOW ACTIVE command determines the

status of the logical units of work. The agents that you must force are indicated in

the SHOW ACTIVE display by the phrase “IS PREPARED FOR COMMIT OR

ROLLBACK”. For example, in VM:

User Agent

7 User ID: JONES is prepared

for commit or rollback

VM ID= VSE1

COORDINATOR= DBDCCICS RESOURCE ADAPTER= 0

TRANSACTION= TPSP CICS SIGNON= PETER TERMINAL= L012

And in VSE,

F4 004

User Agent

7 User ID: JONES is prepared

F4 004

for commit or rollback

F4 004

COORDINATOR= DBDCCICS RESOURCE ADAPTER= 0

F4 004

TRANSACTION= TPSP CICS SIGNON= PETER TERMINAL= L012

The fields in the SHOW ACTIVE display have the following meanings:

COORDINATOR is the CICS subsystem ID.

RESOURCE ADAPTER is the DB2 Server for VSE resource adapter ID.

TRANSACTION is the CICS transaction identifier (TRANSID) for the

application.

CICS SIGNON is the CICS signon user ID (if any).

TERMINAL is the CICS terminal ID (if any).

The CICS SIGNON and TERMINAL values may be blank if the data was not

available to the application server.

If TRANSACTION=CISQ or if the transaction accessed only the application server,

you should commit the logical unit of work. (CISQ is the default CICS transaction

identifier for the ISQL facility.) Use the FORCE command, described on page 51.

For the above example, you enter:

FORCE 7 COMMIT

If the transaction accessed multiple resources, you should contact the transaction

owner. Otherwise, see the DB2 Server for VSE System Administration, or DB2 Server

for VM System Administration manual for more information on deciding whether to

force a commit or roll back.

Application server processing continues when logical units of work are in-doubt,

but:

v The resource adapter identified in the SHOW ACTIVE display may not start

normal processing for new online applications.

v The locks held by the in-doubt logical units of work are not available to other

users.

v The agent structure is not available to other users.

Chapter 4. Recovering from System or Media Failures

153

Recovery from Media Failure

Human or machine error could cause the storage media of the log or the database

to be unreadable or damaged. For these extreme cases, you must replace the

damaged database VSAM file or VM minidisk and restart the application server in

recovery mode.

Usually, the database administrator does the media recovery. Replacing a database

VSAM file requires knowledge of the physical design of the database. Refer to the

DB2 Server for VSE System Administration manual for media recovery procedures.

Replacing a database minidisk requires knowledge of the physical design of the

database. Refer to the DB2 Server for VM System Administration manual for media

recovery procedures.

After you restore the VSE database, you must ensure coordinated recovery from

multiple resource access as discussed in the previous section.

154

Operation

Chapter 5. Tracing the DB2 Server for VSE & VM System

This chapter describes how to start and stop a DB2 Server for VSE & VM trace.

The database manager provides a facility that traces logic and data flow within the

VSE partition or VM virtual machine. This trace facility is useful for problem

determination and isolation. You can also use it to audit security.

DB2

Server for VSE & VM Tracing

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” on page 166 and

“Formatting DB2 Server for VSE Trace Output” on page 168 for descriptions of the

trace formatter.

To use tracing, you must:

1. Ensure that your job control to start the application server contains statements

that identify the trace output file.

2. Decide what functions and subcomponents you would like to trace, and at

what level of detail.

3. Start the trace.

Specifying CMS FILEDEF for a DB2 Server for VM Trace

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.

155

Specifying Job Control for a DB2 Server for VSE Trace

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:

1. The DLBL file name must be ARITRAC.

2. The DASD allocation (301,120) is 4 cylinders on 3350 volume VSER01 starting

at cylinder 10. The volume is on disk drive 195.

3. If you run the tracing more than once, you have to specify a new DASD

allocation each time unless you want to write over the old file. (You should

also specify a different file-id.)

4. This example uses the default symbolic unit for DB2 Server for VSE DASD

output (SYS007).

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.

156

Operation

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),

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.

The DLBL file name must be ARITRAC.

The DLBL parameter “VSAM” indicates that this is a VSAM-managed

file.

The example assumes you wish to implicitly define the file to VSAM

the first time that the file is accessed.

DISP=(OLD,KEEP) indicates that the file is not to be reset at OPEN

time (OLD), and is not to be deleted at CLOSE time (KEEP). This

allows you to implicitly define the file the first time the file is used. It

also lets you extend the file (add records to it) in subsequent runs of

the application server.

VSAM uses the RECORDS and RECSIZE parameters when it is

implicitly defining the files. The parameters help VSAM determine how

much primary and secondary space to allocate for the file.

In this example, the primary allocation is about 4 million bytes (1000 x

4088). The secondary allocation is about 20% of the primary allocation.

You should always set RECSIZE to 4088 because the database manager

uses VB records with a block size of 4088 when tracing to disk.

Note that VSE/VSAM allows up to 15 secondary allocations to the file

if the primary allocation is filled.

An EXTENT statement with the volume serial number (VSER01 in this

example) is normally required for implicit define.

No ASSGN statement is required for VSE/VSAM-managed files.

This example omits the “DLBL CAT=” parameter. The example assumes

that the file is in the VSAM job catalog.

10.

The VSAM catalog must own sufficient unallocated space on the

specified volume to satisfy the space allocation requirements for this

file.

Tracing in Multiple User Mode

In multiple user mode, you can start tracing using the following:

v The TRACCONV, TRACDBSS, TRACDRRM, TRACDSC, TRACRDS, TRACSTG,

and TRACWUM initialization parameters

v The TRACE operator command.

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.

Chapter 5. Tracing the DB2 Server for VSE & VM System

157

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.

Tracing in Single User Mode

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).

Tracing to a CMS File

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” on page 160 or Appendix A, “DB2 Server

for VSE & VM Initialization Parameters,” on page 179.

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:

1. The ddname for the trace file must be ARITRAC, as shown.

2. The file mode letter can be any properly accessed CMS minidisk.

3. The file mode number must be 4. This is required because the trace record

format is CMS OS QSAM variable blocked (RECFM VB).

4. You can always specify the PERM option. It is required if you are running the

application server in single user mode, and the application program is written

in a language other than the Assembler language.

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.

158

Operation

Special Considerations for Multiple Activations of Tracing

If you do the following:

v Activate tracing (using the TRACE ON command or the TRACCONV,

TRACDBSS, TRACDRRM, TRACDSC, TRACRDS, TRACSTG, and TRACWUM

initialization parameters).

v Terminate tracing (enter the TRACE OFF command)

v Reactivate tracing (enter the TRACE ON command).

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:

v When you end tracing with the intention of restarting it, enter the TRACE OFF

NOCLOSE command. Note that when the application server ends, it closes the

trace file.

v Specify the option DISP MOD on the ARITRAC FILEDEF command. This causes

subsequent activations of tracing to add the output to the end of the existing

trace output file.

If the trace fills the CMS minidisk on which the trace file resides, the following

occurs:

v The CMS system issues a message indicating that the CMS minidisk is full. This

message has a DMS prefix.

v Error message ARI0081E (with REASON=12 and CODE=0) is issued.

v Normal operation continues with no trace output.

v In multiple user mode, the operator can enter the SQLEND operator command.

This is necessary only if you do not want the application server to run without

trace output.

v When the CMS minidisk frequently fills, you should use a larger minidisk or

one with more free space for trace output. You may also consider directing the

trace output to memory using the TRACEBUF parameter, refer to Appendix A,

“DB2 Server for VSE & VM Initialization Parameters,” on page 179.

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.

Tracing the DB2 Server for VSE Resource Adapter

See the DB2 Server for VSE & VM Database Administration manual for information

on how to trace the VSE resource adapters.

Choosing the Functions to Be Traced

You can trace functions and subcomponents within the following components:

Data Conversion (CONV)

This component performs numeric data conversion and returns data to

Chapter 5. Tracing the DB2 Server for VSE & VM System

159

user host variables when the DRDA protocol is used. It is also responsible

for performing data conversion on character and graphic data regardless of

the protocol in use.

Database Storage Subsystem (DBSS)

This component is the storage manager. It provides locking mechanisms to

ensure that multiple concurrent users do not interfere with each other. It

also handles recovery, database I/O, and sorting.

Distributed Relational Resource Manager (DRRM)

This component interprets the data streams used in DRDA protocol. It

builds (generates) DRDA data streams from DB2 Server for VSE & VM

internal format and it translates (parses) DRDA data streams back into DB2

Server for VSE & VM internal format.

Data System Control (DSC)

This component enables communication. It controls the initialization and

termination, and acts as the supervisor of the database machine or

partition.

Relational Data System (RDS)

This component supports the relational model of data. It allows users to

see data as though it exists in tables containing rows and columns. It also

translates all SQL statements into specific tasks for the Database Storage

Subsystem.

Storage (STG)

This component will enable tracing of both system and working storage

used by DB2 Server for VSE & VM on the application server side.

Work Unit Manager (WUM)

This component controls the flow of DDM requests and replies when the

DRDA protocol is used. It is the interface between the DRDA component

DRRM and the non-DRDA components RDS and DSC.

Starting a Trace

In multiple user mode, you can start a trace by using either the TRACE operator

command or the TRACCONV, TRACDBSS, TRACRDS, TRACWUM, TRACDRRM,

TRACSTG, or TRACDSC initialization parameters. In single user mode, you can

use only the TRACCONV, TRACDBSS, TRACRDS, TRACDSC and TRACSTG

initialization parameters. In single user mode, the TRACWUM and TRACDRRM

parameters are ignored, even if you specify them. You cannot enter the TRACE

operator command in single user mode.

This section describes how to start a trace using the TRACE operator command.

Appendix A, “DB2 Server for VSE & VM Initialization Parameters,” on page 179

describes the trace initialization parameters.

Both methods of starting a trace have their advantages. The initialization

parameters allow part of the 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

specific agents or authorization IDs.

In VM, the SQLSTART EXEC issues the following CMS FILEDEF command to

define the default trace output file:

FILEDEF ARITRAC TAP2 SL (BLOCK 4096 NOCHANGE

160

Operation

If you want to use different FILEDEF options, enter a CMS FILEDEF command

before invoking the SQLSTART EXEC.

Note: The ddname in the FILEDEF command statement must be ARITRAC. If

your tape volume is unlabeled, use only the TAPn and NL parameters. The

initialization ends abruptly if end of volume is reached on an unlabeled

output tape file.

If the tape volumes have the standard labels required for multivolume output, use

the TAPn and SL parameters. If you require multivolume output, omit the

FILEDEF LEAVE and NOEOV parameters. The LEAVE parameter suppresses

rewinding before OPEN processing and after CLOSE processing.

For standard label tapes, the CMS LABELDEF command is optional. When you use

the CMS LABELDEF command, you must enter it with the ddname ARITRAC

parameter prior to invoking the SQLSTART EXEC.

The trace output file can be a tape or a CMS file. You can use both IBM standard

tape labels and unlabeled tapes. Tape rewinding is controlled by CMS FILEDEF

command parameters. The CMS FILEDEF command supplied by the SQLSTART

EXEC assumes tape output with the use of IBM standard tape labels. It also

rewinds the tape.

In VSE, to run the trace facility, include statements for the trace output file in your

job control that starts the application server. The statements you need vary

depending on whether you want the trace output on tape or on disk:

v When you trace to tape, you need a TLBL statement for the trace output file.

Your TLBL statement must have the file name parameter specified as ARITRAC.

All other TLBL parameters are optional. Omit any ASSGN statement for the

trace tape unit. The application server dynamically assigns and unassigns the

trace tape unit.

Trace output tape files are created with IBM Standard (EBCDIC) Tape Labels.

The trace tape is never rewound except at end-of-volume. You must rewind the

tape manually or by using job control statements.

v When you trace to disk, you need a DLBL, an EXTENT, and an ASSGN

statement. The file name specified on the DLBL statement must be ARITRAC. If

the file is managed by the VSE/VSAM Space Management for SAM Feature, the

EXTENT statement is optional and the ASSGN statement is not applicable.

To activate a trace in multiple user mode, enter the TRACE operator command:

►►

TRACE

cuu

►◄

(1)

DUMP

TRACEBUF n

DISK

Notes:

Valid for VSE only.

indicates trace activation. If trace is already active, you must first enter the

TRACE OFF command before you can enter the TRACE ON command.

Chapter 5. Tracing the DB2 Server for VSE & VM System

161

cuu

is the virtual address of the trace device used for trace output. In VM this is

specified in the ARITRAC FILEDEF command. The default address is 182. If

you are tracing to tape, a tape volume must be mounted and ready on the tape

unit. If you are tracing to a CMS file, enter the virtual device number of the

minidisk.

DISK (Valid for VSE only)

indicates that trace output is to a DASD SAM file.

Note: You must specify either cuu or DISK.

DUMP

causes a snapshot dump of the VSE partition or VM virtual machine at a

particular trace point. If you specify this option, you are prompted for further

information as described on page 164.

TRACEBUF n

is an optional parameter that specifies the amount of memory, in kilobytes, that

you want to allocate for storing trace records. A trace buffer n kilobytes in size

is created. This buffer holds the last n kilobytes of trace information in memory

until either a TRACE OFF is issued or the application server ends (normally

with an SQLEND, or abnormally). The number of kilobytes, n, can be any

integer in the range 0 to 99999. If you specify a value of 0, the trace is written

directly to the trace output file. When you enter either TRACE OFF or

SQLEND, you may choose not to create the trace output file by including the

TRCPURGE parameter. This parameter instructs the database manager to

purge the contents of the trace buffer instead of writing it to the output file.

A suggested size for the trace buffer is 100 kilobytes or more. It is

recommended that you increase the Virtual Machine memory or virtual storage

size of the database partition by the size of trace buffer before you start a trace

in memory. See item 5 on page 165 in the following TRACE command

sequence.

After you enter the TRACE command, the application server requests further

information by prompting.

Note: When the prompting messages appear on the DB2 Server for VM operator

terminal, the display status area displays “RUNNING” instead of “VM

READ”. This occurs because the application server continues to service DB2

Server for VM users while it is waiting for the operator reply.

The application server prompts you for the following information:

1. You are prompted to specify the DB2 Server for VSE & VM authorization ID,

agent number, or * (for ALL) to indicate the authorization ID or agent

structures that you want traced.

For traces, the operator agent is agent 1, the checkpoint agent is agent 2, and

the ready/recovery agent is agent 3. The first general purpose agent is agent 4,

the second is agent 5, and so on.

The authorization ID for the operator agent is OPERATOR. The authorization

ID for the checkpoint agent is CHECKPT. The authorization ID for the

ready/recovery agent is RECOVERY. The authorization ID for a general

purpose agent is the DB2 Server for VSE & VM authorization ID of the

connected user.

2. You are prompted by message ARI0087D to specify whether you want to trace

the Data Conversion (CONV), Database Storage Subsystem (DBSS), Relational

162

Operation

Data System (RDS), Work Unit Manager (WUM), Distributed Relational

Resource Manager (DRRM), Storage (STG), Data System Control (DSC), or all

of these components. The CONV component performs CCSID and numeric

conversion. The RDS component is a compiler and translator for the SQL

language. The DBSS component controls and accesses the application server.

The DSC component controls communications and agent handling. The STG

component controls DB2 Server for VSE & VM system and working storage on

the application server side. The WUM and DRRM components support the DB2

Server for VM DRDA protocol. You will not be prompted for WUM or DRRM

if PROTOCOL=SQLDS.

3. For DBSS, RDS, DRRM, and DSC tracing, the system prompts you to specify

the list of functions and subcomponents and their trace levels (level 0, 1, or 2).

The CONV, WUM, and STG components have no subcomponents; therefore,

the system prompts you only for trace levels. For CONV and WUM, if you

request tracing at level 0, no tracing is done. If you request tracing at level 1,

tracing displays only module entry and exit points. If you request tracing at

level 2, tracing displays module entry, report, and exit points. If you request

tracing at any level other than 0, 1, or 2, it is an error. For STG, if you request

tracing at level 0, no tracing is done. If you request tracing level 1, tracing

displays storage trace values that may include amount requested/freed, the

storage pointer, and the return code. STG does not have a level 2 trace. For

each function or subcomponent, enter the name of the component or function

and the level number as follows:

component1 level-number1 [component2 level-number2] ...

For example: Request tracing at level 1 for LUW and level 2 for DC.

LUW 1 DC 2

Leave at least one blank between the component name and the level number.

The DBSS functions and subcomponents that you can supply in response to

message ARI0090D are:

ENTRY

(DBSS entry calls)

EXIT

(Returns from DBSS entry calls)

LOG

(Log and Recovery Management)

LOCK

(Lock Management)

LUW

(Logical Unit of Work Management)

(Data Control)

(Data Manipulation)

STOR

(Storage Management)

SORT

(DBSS Sort)

INDEX

(DBSS Index)

STAT

(DBSS Update Statistics)

(For all of the above)

DBSS has unique subcomponents, ENTRY and EXIT, which provide tracing for

DBSS calls before entering or after exiting the module.

ENTRY and EXIT tracing at level 1 display only DBSS Call entry or exit points.

Tracing at level 2 displays the base control information and auxiliary structures,

depending on the DBSS opcode.

Chapter 5. Tracing the DB2 Server for VSE & VM System

163

The RDS functions and subcomponents you can supply in response to message

ARI0088D are:

EXEC

(Executives)

(Parser)

OPT

(Optimizer)

(Access Generator)

INT

(Interpreter and Authorization)

(Security Audit Trace)

(Statement Generator)

(For all of the above)

For information on using the security audit trace facility, refer to the DB2 Server

for VSE & VM Database Administration manual.

The DSC functions and subcomponents you can supply in response to message

ARI00142D are:

AGENT

(Agent handling)

COM

(Communications)

(For all of the above)

Tracing the AGENT subcomponent in DB2 Server for VM provides a data

stream trace for the application server. You can use it to isolate a DRDA data

stream trace. To produce a data stream trace for the application requester, refer

to the DB2 Server for VSE & VM Database Administration manual.

The DRRM functions and subcomponents that you can supply in response to

message ARI0140D are:

DICT

(DDM/FD:OCA Dictionary and FD:OCA descriptors and data)

GEN

(DDM Generator)

PARSE

(DDM Parser)

RDIIN

(RDIIN Manager)

(For all of the above)

The CONV component has no subcomponents, so in response to message

ARI0160D, you supply only trace levels.

The STG component has no subcomponents, so in response to message

ARI0162D, you supply only trace levels.

The WUM component has no subcomponents, so in response to message

ARI0141D, you supply only trace levels.

4. If you specify DUMP for the TRACE command, you are prompted to specify a

CONV, DBSS, RDS, DRRM, WUM, STG, or DSC trace-point number. This

causes a snapshot dump of the database partition machine to occur the first

time the specified trace point is activated. Snapshot dumps do not occur with

subsequent activation of the trace point.

The snapshot dump is generated by the CP DUMP command, or the VSE

PDUMP macro.

Note: The function or subcomponent containing the trace point must be

activated for tracing to cause activation of the snapshot dump. Also, the

type of dump is controlled by the initialization parameter DUMPTYPE.

This parameter has three possible values: P, F, or N. F is the default. If

164

Operation

you specify P, a partial dump of everything except the DB2 Server for

VSE & VM code occurs. If you specify F, a full machine dump occurs. If

you specify N, no dump occurs.

In DB2 Server for VM, partial virtual machine dumps are sent to the virtual

printer and full virtual machine dumps are sent to the virtual reader. Refer to

the DB2 Server for VSE & VM Diagnosis Guide and Reference manual for dump

handling instructions.

5. If you specify TRACEBUF for the TRACE ON command and there is sufficient

free storage available to allocate a trace buffer, you will receive a message

ARI0154I indicating the amount of contiguous memory available. If the amount

of storage n kilobytes specified by the TRACEBUF parameter is not available,

then the maximum size of the currently available contiguous storage is

displayed in error message ARI0155E and the trace will not be started. You can

reenter the TRACE ON command for a different size of trace buffer or not

select the trace buffer.

Note: The amount of free storage fluctuates during execution of the DB2 Server

for VSE & VM program. If a substantial portion is used by the trace

buffer there is a higher probability that an agent may be rolled back or

the database system may shutdown because of the lack of storage.

For traces started by initialization parameters you cannot trace only a selected

authorization ID or agent number or dump at a specified trace point.

Stopping a Trace

In single user mode, the trace ends when the application server ends. (Remember,

you cannot enter operator commands in single user mode.) To deactivate a trace in

multiple user mode, enter the following operator command:

►► TRACE OFF

►◄

NOCLOSE

TRCPURGE

OFF

indicates trace deactivation.

specifies that the trace file is to be closed. In DB2 Server for VSE it also

specifies that the trace file is to be unassigned. The default is CLOSE. If you

specify the CLOSE parameter, the trace file will be overwritten when issuing a

subsequent TRACE ON command.

NOCLOSE

specifies that the trace file is to be left open for further tracing into the same

file with a subsequent TRACE ON.

If you are tracing to tape, specify either CLOSE or NOCLOSE and then TRACE

ON to create multiple trace output files.

In DB2 Server for VM you must specify the LEAVE option on the ARITRAC

FILEDEF command.

Chapter 5. Tracing the DB2 Server for VSE & VM System

165

Note: You can use the LEAVE option to process these files sequentially when

you are formatting trace output.

TRCPURGE

Specify this optional parameter if you want to purge the contents of the trace

buffer when the TRACE OFF command is processed. In this instance an output

trace file will not be created for the trace buffer. Otherwise the contents of the

trace buffer, if it exists, will be flushed out to the trace output file. The

TRCPURGE parameter is ignored if there is no trace buffer in use when

TRACE OFF is issued.

If you end normally, the trace file is closed automatically. If the application server

is ended abnormally, the file may not be closed successfully. A message is

displayed whenever the trace file is closed successfully.

If the trace file is a tape and is not closed successfully, you can still try to format it.

Information near the end of the trace might not be processed, however, and the

trace formatting utility will probably terminate abnormally. You can also try to

write a tape mark on the trace tape before you attempt to format it. (The trace tape

is not automatically rewound.)

Formatting DB2 Server for VM Trace Output

The trace formatter is a DB2 Server for VSE & VM-supplied program that

transforms the information on the trace tape into a printed report. You control the

trace formatter by supplying control statements as input.

Note: You should not attempt to use the trace formatter in the CMS Subset

environment.

The trace formatter is invoked through an EXEC called SQLTRFMT. To invoke the

SQLTRFMT EXEC, enter SQLTRFMT.

►► SQLTRFMT

►◄

The SQLTRFMT EXEC issues the following CMS command to define the trace

formatter’s default input file:

FILEDEF ARITRAC TAP2 SL (NOCHANGE

Notes:

1. The SQLTRFMT EXEC does not issue a CMS LABELDEF command.

2. The ARITRAC FILEDEF command used for the formatter must correspond to

the ARITRAC FILEDEF command used for the trace itself. If you enter your

own trace file ARITRAC FILEDEF command for the trace, you must enter the

same FILEDEF command before invoking the SQLTRFMT EXEC.

3. If you want the additional standard label checking provided by the CMS

LABELDEF command, you must enter the LABELDEF command before

invoking the SQLTRFMT EXEC. The LABELDEF file name, ddname, must be

ARITRAC.

166

Operation

4. The trace formatter does not require the application server to be running. You

must, however, have read access to the production minidisk to run the trace

formatter.

5. The trace formatter cannot run in CMS DOS mode. If you run the trace

formatter in CMS DOS mode, the CMS session ends abnormally.

If you are tracing to tape, you must ensure that the trace tape is mounted on

virtual device number 182 or the virtual device number specified in your (optional)

FILEDEF command, before invoking the SQLTRFMT EXEC.

If you direct the trace output to a CMS file, you must enter a CMS FILEDEF

command for the file before invoking the SQLTRFMT EXEC. Use the same

FILEDEF that you entered before invoking the SQLSTART EXEC to start the trace.

Refer to “Tracing to a CMS File” on page 158 for use of the FILEDEF command.

Before invoking the SQLTRFMT EXEC, run the SQLINIT EXEC, if you have not

already done so. This ensures that the trace formatter can use the resource adapter

to generate messages. For more information on the SQLINIT EXEC and resource

adapter tracing, refer to the DB2 Server for VSE & VM Diagnosis Guide and Reference

manual.

During its processing, the SQLTRFMT EXEC invokes XEDIT to edit a card-image

CMS file called SQLTRFMT SQLTRACE A1. The first time you issue the

SQLTRFMT EXEC, you can see that the file is empty. The SQLTRFMT EXEC creates

it on your A-disk. You should place the trace formatter control statements in this

file. The trace formatter control statements are explained in the section “Trace

Formatter Control Statements” on page 170.

When you are finished entering the control statements, use the PF3 key to file the

results and continue processing, or you can use the XEDIT command FILE. The

SQLTRFMT SQLTRACE is then stored on your A-disk and is used as the SYSIN

file for the trace formatter program.

The SQLTRFMT EXEC then prompts as to whether you want to direct the trace

output to the virtual printer or to a CMS file. If you choose to print the data, the

SQLTRFMT EXEC prints to the virtual printer 00E. If you want, you can enter CP

SPOOL and TAG commands before invoking the SQLTRFMT EXEC to direct the

output to a particular class or device. If you want the output directed to a CMS

file, the SQLTRFMT EXEC prompts you for a file name, file type, and as an option,

file mode. If you do not specify a file mode, the trace formatter uses A1.

The trace formatting program can generate considerable output. You should ensure

that there is enough space on your A-disk or other specified minidisk before

directing trace formatter output to a CMS file.

Note: The output file contains 121-character records. The first character is an ANSI

carriage control character. If you route your output to a CMS file and later

want to print the file, use the CC option on the PRINT command to indicate

that the carriage control characters are present.

After you specify where you want the formatted output to go, the SQLTRFMT

EXEC invokes the program that formats the trace data. Upon completion, the

SQLTRFMT EXEC returns control to CMS. If any control statements are in error,

the trace formatter program prints messages in the output CMS file or to the

virtual printer (whichever you selected). The SQLTRFMT EXEC displays a message

that indicates whether it ran successfully or encountered an error.

Chapter 5. Tracing the DB2 Server for VSE & VM System

167

The SQLTRFMT SQLTRACE A1 is not erased upon completion. On subsequent

runs, the SQLTRFMT EXEC invokes XEDIT for this file and lets you modify it.

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:

v A tape file

v A standalone SAM DASD file

v A SAM DASD file managed by the VSE/VSAM Space Management for SAM

feature.

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” on

page 156.

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

•

168

Operation

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.

Chapter 5. Tracing the DB2 Server for VSE & VM System

169

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.

170

Operation

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

Chapter 5. Tracing the DB2 Server for VSE & VM System

171

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:

Data Control

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:

Access Generator

EXEC

Executive

INT

Interpreter and Authorization

OPT

Optimizer

Parser

Security Audit Trace

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:

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.

172

Operation

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:

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

USERID

JOHNDOE

Chapter 5. Tracing the DB2 Server for VSE & VM System

173

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.

174

Operation

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

Chapter 5. Tracing the DB2 Server for VSE & VM System

175

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:

v If module entry trace point

MOD_CALLED=’entry point name’

v If module exit trace point

MOD_RETURNED=’module name’ (followed by)

RETCODE=−−−n...n

(present if module passed a return code)

v If neither module entry nor module exit (middle of some module)

MOD_REPORT=’module name’

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:

v L_varname=value-or-string

v G_varname=value-or-string

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.

176

Operation

DB2 Server for VSE. Operations Guide / Handbooks (2004-2007) - page 25