/TRACE Command: EXIT through PSB .-ON--. >>-+-/TRACE-+--SET--+-----+-------------------------------------> '-/TRA---' '-OFF-' >--+-EXIT--+-ALL--+--DFSMSCE0------------------------------------+->< | +-LRDI-+ | | +-LRIN-+ | | +-LRLT-+ | | +-LRTR-+ | | +-PRCH-+ | | +-PRIS-+ | | +-TR62-+ | | +-TRBT-+ | | +-TROT-+ | | '-TRVT-' | | .-------. | | V | | +-LINE--+---line#-+-+--+--------------+--| A |----------------+ | '-ALL-------' '-LEVEL--+-1-+-' | | +-2-+ | | +-3-+ | | '-4-' | | .-------. | | V | | +-LINK--+---link#-+-+--+--------------+--| A |----------------+ | '-ALL-------' '-LEVEL--+-1-+-' | | +-2-+ | | +-3-+ | | '-4-' | | .--------. | | V | | +-LUNAME--+-+---luname-+-+--+-INPUT--+-+----------------------+ | | '-ALL--------' '-OUTPUT-' | | | | .--------. | | | | V | | | | '-luname--TPNAME----tpname-+-' | +-MONITOR--| B |----------------------------------------------+ +-MSCT--------------------------------------------------------+ | .---------------. | | V | | +-NODE--+-+---+-nodename--+-+-+----+--+--------------+--| A |-+ | | | '-nodename*-' | | '-LEVEL--+-1-+-' | | | '-ALL---------------' | +-2-+ | | '-nodename--USER--username-' +-3-+ | | '-4-' | +-OSAMGTF-----------------------------------------------------+ +-PI--+------------------+--+--------------------+------------+ | | .-LOG--. | | .-MEDIUM-. | | | '-OPTION--+------+-' '-VOLUME--+--------+-' | | +-TIME-+ +-LOW----+ | | '-ALL--' '-HIGH---' | | .-------------. | | V | | +-PROGRAM----programname-+------------------------------------+ | .-NOCOMP-. | '-PSB--psbname--+--------+------------------------------------' '-COMP---' A: |--+-----------------+--+----------+----------------------------| '-MODULE--+-DDM-+-' '-TAKEOVER-' +-MFS-+ '-ALL-' B: .-------------------------------------. V .-ALL-------------------. | |--+---+-APDB--+-----------------------+-+-+-+------------------> | | | .-------------------. | | | | | | V | | | | | | '---+-dbname--------+-+-' | | | | +-areaname------+ | | | | '-partitionname-' | | | +-APMQ----------------------------+ | | +-LA------------------------------+ | | '-SCHD----------------------------' | '-ALL-------------------------------------' >--+--------------------------------+--+--------------------+---| | .----------------. | '-INTERVAL--#seconds-' | V | | '-REGION--+---+-reg#-------+-+-+-' | +-reg#-reg#--+ | | '-regionname-' | '---ALL--------------'
/TRACE Command: TABLE through UNITYPE .-ON--. >>-+-/TRACE-+--SET--+-----+-------------------------------------> '-/TRA---' '-OFF-' >--+-TABLE--+-ALL--+--+-------------------+--+--------------------+-+->< | +-CSLT-+ | .-NOLOG-. | | .-MEDIUM-. | | | +-DISP-+ '-OPTION--+-------+-' '-VOLUME--+--------+-' | | +-DL/I-+ '-LOG---' +-LOW----+ | | +-DLOG-+ '-HIGH---' | | +-FAST-+ | | +-FPTT-+ | | +-IDC0-+ | | +-LATC-+ | | +-LOCK-+ | | +-LRTT-+ | | +-LUMI-+ | | +-OCMD-+ | | +-OTMT-+ | | +-QMGR-+ | | +-ORTT-+ | | +-RETR-+ | | +-RRST-+ | | +-SCHD-+ | | +-SQTT-+ | | +-STRG-+ | | '-SUBS-' | +-TCO------------------------------------------------------------+ | .-00--------------. | +-TIMEOUT--+-----------------+-----------------------------------+ | '-time#--+------+-' | | +-MSG--+ | | '-AUTO-' | +-TMEMBER--+-tmembername-+--+----------------------+-------------+ | '-ALL---------' '-TPIPE--+-tpipename-+-' | | '-ALL-------' | | .----------. | | V | | +-TRANSACTION----tranname-+--------------------------------------+ +-TRAP--+-1-+----------------------------------------------------+ | '-2-' | | .-------------. | | V | | '-UNITYPE----unitypename-+--+--------------+---------------------' '-LEVEL--+-1-+-' +-2-+ +-3-+ '-4-'
Table 169 lists the environments (DB/DC, DBCTL, and DCCTL) from which the command and keywords can be issued.
Command / Keywords | DB/DC | DBCTL | DCCTL |
---|---|---|---|
/TRACE | X | X | X |
AUTO | X | X | |
COMP | X | X | |
EXIT | X | X | |
INPUT | X | X | |
LEVEL | X | X | |
LINE | X | X | |
LINK | X | X | |
LUNAME | X | X | |
MODULE | X | X | |
MONITOR | X | X | X |
MSG | X | X | |
NOCOMP | X | X | |
NODE | X | X | |
OPTION | X | X | X |
OSAMGTF | X | X | |
OUTPUT | X | X | |
PI | X | X | |
PROGRAM | X | X | X |
PSB | X | X | |
SET | X | X | X |
TABLE | X | X | X |
TAKEOVER | X | X | |
TCO | X | X | X |
TIMEOUT | X | X | |
TMEMBER | X | X | |
TPIPE | X | X | |
TPNAME | X | X | |
TRANSACTION | X | X | |
TRAP | X | X | |
UNITYPE | X | X | |
USER | X | X | |
VOLUME | X | X | X |
/TRACE directs and controls the IMS capabilities for tracing internal IMS events. It also starts, stops, and defines the activity to be monitored by the IMS Monitor.
The information developed by the LINE, LINK, NODE, UNITYPE, TRANSACTION, PROGRAM, PSB, and TCO keywords is written on the IMS system log (type X'5F' for PSB, and type X'67' records for the other keywords mentioned.) PI (program isolation) and TABLE trace information is kept in storage or logged (type X'67' records), depending on specification of additional keywords. The MONITOR keyword provides no such output on the system log; it only controls the IMS Monitor. The monitor develops its own output data and writes it on a separate data set. For an explanation of the output reports provided by the monitor, refer to the IMS Version 9: Utilities Reference: System.
The status and options of the current IMS traces can be displayed with the /DISPLAY TRACE command.
LEVEL indicates the extent of the control block trace information desired. The indicated control blocks are only traced at relevant times. All levels are inclusive of numerically lower levels. The following list displays the levels and their associated blocks.
If the first /TRACE SET ON command does not specify LEVEL, a default of 4 will be used. Specifying LEVEL on subsequent commands will change the defaults.
The INPUT and OUTPUT keywords provide the operator with the flexibility to control the volume of trace data for LU 6.2 devices.
Specifying the keyword INPUT with the LUNAME keyword indicates tracing is activated or deactivated for input and synchronous outbound activities. Specifying the parameter ALL with the INPUT keyword causes all future LU 6.2 input and synchronous outbound activities to be traced as well.
Specifying the keyword OUTPUT with the LUNAME keyword indicates tracing is activated or deactivated for asynchronous outbound activities. Specifying the parameter ALL with OUTPUT causes all future LU 6.2 asynchronous outbound activities to be traced as well.
Specifying neither INPUT or OUTPUT is the same as both INPUT and Tracing is activated or deactivated for input and both synchronous and asynchronous outbound activities. Specifying the parameter ALL in this case causes all future LU 6.2 inbound activities, synchronous and asynchronous outbound activities to be traced as well.
The network-qualified LU name is optional for the LUNAME keyword. If the LU name is not a network-qualified LU name and no TP name is specified, tracing is activated or deactivated for all the network-qualified LU names in the system whose LU name matches the LU name specified.
If the specified resource does not exist and tracing is activated, a structure is created to retain the status.
MODULE indicates which modules are to have their control blocks traced.
If the first /TRACE SET ON command does not specify MODULE, a default of ALL will be used. Specifying MODULE on subsequent commands will change the defaults.
When activating the monitor, you must specify one or more of the following MONITOR parameters to indicate the events to be monitored:
You can specify the ALL parameter to indicate all databases, areas, and partitions, or you can explicitly enter database names, area names, and partition names.
The duration of the monitoring must be less than twenty-four hours (86,400 seconds). When INTERVAL is not specified, monitoring will continue until the /TRACE SET MONITOR OFF command is issued, or until IMS shuts down.
INTERVAL does not define when the Monitor will be turned off, because the IMS Monitor will not be turned off until the first attempt is made to write a monitor log record after the defined interval has expired.
You can specify any combination of ALL, APDB, APMQ, INTERVAL, LA, REGION, and SCHD parameters on the MONITOR keyword, as shown in Table 170
Table 170 lists the environments (DB/DC, DBCTL, and DCCTL) from which the MONITOR keyword parameters can be issued.
Keyword Parameter | DB/DC | DBCTL | DCCTL |
---|---|---|---|
ALL | X | X | X |
APDB | X | X | |
APMQ | X | X | |
INTERVAL | X | X | X |
LA | X | X | |
REGION | X | X | X |
SCHD | X | X | X |
The IMS Monitor report output varies depending upon which keywords or parameters you specify. Sections of the report can be misleading if required records are excluded. For example, if you specify the APDB parameter without the SCHD parameter, PSB/PCB relationships will not be correctly represented. To get the total DL/I call reports without the IMS line activity, the correct parameters to specify are APDB, APMQ, and SCHD.
The monitor writes log records until one of the following occurs:
When deactivating the monitor, no parameters are required. Any parameters that are entered, other than ALL, are ignored. ALL is the default. If the monitor is to be reactivated, a new set of MONITOR keyword parameters must be selected.
The NODE parameter can be generic if the USER keyword is not specified and applies to nodes that already exist. Generic NODE parameters do not cause any dynamic nodes to be created.
For ISC nodes, the /TRACE NODE nodename without the USER applies to all half-sessions for NODE nodename, including dynamic ISC sessions that are dynamically allocated later.
For nodes that do not exist, /TRACE SET ON NODE nodename without the USER keyword causes the dynamic NODE nodename to be created to maintain knowledge of the trace request when the node becomes active. Until the node becomes active, /DISPLAY NODE shows a type of UNK (unknown). If the trace is subsequently turned off and the temporary node still exists, it is deleted at the next checkpoint.
/TRACE NODE nodename USER username is valid:
If global resource information is kept in Resource Manager, /TRACE NODE sets a global trace status for the node and sets the trace status locally. If global resource information is not kept in Resource Manager, /TRACE NODE sets the trace status locally. If the node does not exist in an ETO environment, IMS creates the node and sets trace status for the local node.
If PI is entered without the OPTION keyword, the program isolation trace is kept in storage without being logged. If you are using the program isolation trace to provide statistics and performance data, you should enter OPTION(ALL).
Table 171 lists various /TRACE command formats and shows whether the command influences tracing, logging, and the additional time field.
Command | Tracing | Logging | Additional Time Field |
---|---|---|---|
/TRACE SET ON PI | Yes | No | No |
/TRACE SET OFF PI | No | No | No |
/TRACE SET ON PI OPTION1 | Yes | Yes | No |
/TRACE SET OFF PI OPTION1 | Yes | No | No |
/TRACE SET ON PI OPTION TIME | Yes | No | Yes |
/TRACE SET OFF PI OPTION TIME | Yes | No | No |
/TRACE SET ON PI OPTION ALL | Yes | Yes | Yes |
/TRACE SET OFF PI OPTION ALL | Yes | No | No |
Note:
|
The log option includes the possibility of externally tracing to a data set other than the IMS OLDS. If specified, DASD external tracing has first priority, TAPE external tracing has second priority, and IMS OLDS has third priority. External tracing to the OLDS is not done without operator approval. EXTERNAL trace is available to the alternate system only for DASD/TAPE type, but not for OLDS. For more information, see IMS Version 9: Diagnosis Guide and Reference and IMS Version 9: Operations Guide.
Entries for Fast Path have no elapsed wait time.
Each record will contain the following items if applicable:
If the batch message program (BMP) being traced is the Queue Control Facility (QCF) program product 5697-E99, a 6701-MRQB record is logged by the QCF module DFSQMRQ0. The default program name for the QCF BMP is MRQPSB, and can be overridden on the MSGQUEUE SYSGEN macro.
Items logged in the 6701-MRQB record, if applicable, are:
For more information about the QCF module DFSQMRQ0 and the 6701-MRQB trace, refer to IMS Version 9: Diagnosis Guide and Reference. For more information about the QCF product, refer to IMS Queue Control Facility for z/OS, User's Guide V1R2 (SC26-9685-02).
When CPI Communications driven transaction programs issue the DL/I APSB call specifying a PSB that contains alternate PCBs, only the PROGRAM keyword is applicable.
For LU 6.2, the PSB keyword is applicable only if the CPI Communications driven transaction program has issued a DL/I APSB call to allocate a PSB.
The /TRACE SET PSB psbname COMP command only applies to BMPs in a DBCTL environment.
The information resulting from the use of this keyword is written on the X'5F' log record.
The following trace into trace tables can be turned on or off with the online /TRACE command.
Table 172 shows the environments in which the trace tables are valid.
Trace Table | DB/DC | DBCTL | DCCTL |
---|---|---|---|
ALL | X | X | X |
CSLT | X | X | X |
DISP | X | X | X |
DL/I | X | X | X |
DLOG | X | X | X |
FAST | X | X | X |
|FPTT | X | X | X |
IDC0 | X | X | |
LATC | X | X | X |
LOCK | X | X | |
LRTT | X | X | X |
LUMI | X | X | |
MSCT | X | X | |
OCMD | X | X | X |
ORTT | X | X | |
OTMT | X | X | |
QMGR | X | X | |
RETR | X | X | |
RRST | X | X | |
SCHD | X | X | X |
SQTT | X | X | |
STRG | X | X | X |
SUBS | X | X | X |
Fast Path Trace is activated by including the FPTRACE DD statement in the dependent region JCL to define the destination of the trace output and by issuing the operator command /TRACE SET ON TABLE FAST.
Recommendation: Only run this trace in a test environment because the FPTRACE output is very large.
LUMI is not valid for an RSR tracking subsystem.
The meaning of the OPTION parameters are:
The log option includes the possibility of externally tracing to a data set other than the IMS OLDS. If specified, DASD external tracing has first priority, TAPE external tracing has second priority, and IMS OLDS has third priority. External tracing to the OLDS is not done without operator approval. This option is ignored for the retrieve trace and the Fast Path trace, (default).
FPTRACE has its own SYSOUT. EXTERNAL trace is available to the alternate system only for DASD/TAPE type, but not for OLDS. For more information, see IMS Version 9: Diagnosis Guide and Reference and IMS Version 9: Operations Guide.
The same trace table is used for DL/I, LOCK, and PI trace information. Whether or not this table is logged will depend on the logging option of the last /TRACE command that was entered for DL/I, PI, or LOCK.
The VOLUME keyword is valid on active and RSR tracking subsystems.
TAKEOVER only applies in an XRF environment. When TAKEOVER is used with SET OFF, the trace is turned off before takeover. When an output message is dequeued for a terminal, takeover tracing will stop for that terminal.
If both regular and takeover tracing are entered, the most recent setting will override any previous settings; for example, takeover tracing will override regular tracing if regular tracing was entered first. This means that either regular or TAKEOVER tracing can be in effect, but not both.
/TRACE TAKEOVER can be issued only from an XRF active system. It is rejected if entered from an alternate or non-XRF system. It is recovered across restart and takeover, and only needs to be entered once until cold start. Tracing occurs only if the session was active at the time of the takeover.
If time# is 0, or not specified, then when I/O is initiated for a node, the node will be placed on a queue, so that its status can be displayed with the /DISPLAY TIMEOVER command. You will not be notified if the node does not receive a response and the time elapses, and the node will not be reactivated.
If time# is not 0, then the following keywords can be used.
If you wish to change the time period or the action to be taken if timeout occurs, you can enter the /TRACE SET ... TIMEOUT command while the Timeout Detection facility is already active. However, if nodes are receiving or sending input or output, they will function according to the previous settings of the /TRACE ... TIMEOUT command. If this is undesirable, then you should enter the /TRACE SET OFF TIMEOUT command before reentering /TRACE SET ... TIMEOUT.
If the timeout trace facility failed during IMS initialization, the /TRACE SET ... TIMEOUT command is rejected with an error message.
The VTAM TIMEOUT I/O facility is automatically started during IMS shutdown. It is set for 1 minute and AUTO.
While processing the /TRACE TMEMBER TPIPE command, IMS creates a temporary transaction pipe (if one does not already exist) with the trace status. IMS sets the synchronization status for this transaction pipe when it sends or receives the first message for the transaction pipe.
Each record will contain the following items, if applicable:
For more information about this trace, see the discussion of the DLA3LOG trace in IMS Version 9: Diagnosis Guide and Reference.
The UNITYPE keyword is used to trace all terminals of a specific type. Parameters (unitypename) are similar to the identifiers displayed in the TYPE column by the /DISPLAY NODE and /DISPLAY LINE/PTERM commands. Table 173 shows the terminal types for UNITYPE parameters.
UNITYPE Parameter | Terminal Type |
---|---|
2260R | 2260/2265 REMOTE |
3286 | 3284/3286 |
SYSTEM/7 | SYSTEM 7 |
2980 | 2980 |
3270R | 3270 REMOTE |
3270I | 3270 LOCAL |
RDR/PTR | LOCAL SYSIN/SYSOUT |
SYSTEM/3 | SYSTEM 3 |
FIN | 3600 |
3277 | 3270 VTAM |
SYS/7BS | SYSTEM 7 BSC |
SLU1 | SLU TYPE 1 |
SLU2 | SLU TYPE 2 |
SLUP | SLU TYPE P |
LU 6 | LU TYPE 6 |
NTO | NTO |
CONSOLE | z/OS SYSTEM CONSOLE |
TWX | TWX SWITCHED |
3275SW | 3270 SWITCHED |
MSCBSC | Binary Synchronous Communication |
MSCMTM | Memory to Memory Communication |
MSCCTC | Channel to Channel Adapter |
MSCVTAM | MSC VTAM |
If global resource information is kept in Resource Manager, /TRACE UNITYPE sets a global trace status for all of the nodes of a specific type. This requires that the inactive static nodes be processed on every IMS system. The UNITYPE keyword is similar to specifying a generic parameter. If global resource information is not kept in Resource Manager, /TRACE UNITYPE sets the trace status locally.
To turn on message format service module and communication analyzer level 4 control block tracing for all physical terminals on line 4.
Entry ET:
/TRACE SET ON LINE 4 LEVEL 4 MODULE MFS
Response ET:
DFS058I TRACE COMMAND COMPLETED
To turn on tracing for a logical link:
Entry ET:
/TRACE SET ON LINK 2 LEVEL 4 MODULE ALL
Response ET:
DFS058I TRACE COMMAND COMPLETED
Entry ET:
/TRACE SET ON MONITOR ALL
Response ET:
DFS058I TRACE COMMAND COMPLETED DFS2500I DATASET DFSDCMON SUCCESSFULLY ALLOCATED DFS2212I DC MONITOR STARTED
Explanation: The monitor is activated and all events will be monitored.
Entry ET:
/TRACE SET OFF MONITOR
Response ET:
DFS058I TRACE COMMAND COMPLETED DFS2500I DATASET DFSDCMON SUCCESSFULY DEALLOCATED DFS2212I DC MONITOR STOPPED
Explanation: The monitor is deactivated.
Entry ET:
/TRACE SET ON MONITOR LA
Response ET:
DFS058I TRACE COMMAND COMPLETED
Explanation: The monitor is activated. Line and logical link activities will be monitored. The monitoring of events from the previous activation of the monitor no longer apply.
To turn on program isolation tracing, include the additional time field in the trace record and have the trace information logged:
Entry ET:
/TRACE SET PI OPTION ALL
Response ET:
DFS058I TRACE COMMAND COMPLETED
To turn off logging of program isolation trace data but continue the trace in storage:
Entry ET:
/TRACE SET OFF PI OPTION LOG
Response ET:
DFS058I TRACE COMMAND COMPLETED
To stop program isolation tracing.
Entry ET:
/TRACE SET OFF PI
Response ET:
DFS058I TRACE COMMAND COMPLETED
To trace all DL/I calls issued for PSB AALST:
Entry ET:
/TRACE SET ON PSB AALST COMP
Response ET:
DFS058I TRACE COMMAND COMPLETED
To turn on online tracing into the DL/I trace table:
Entry ET:
/TRACE SET ON TABLE DL/I
Response ET:
DFS058I TRACE COMMAND COMPLETED
To turn on the dispatcher's trace tables and have them written to the system log:
Entry ET:
/TRACE SET ON TABLE DISP OPTION LOG
When the dispatcher's trace tables are no longer required:
Entry ET:
/TRACE SET OFF TABLE DISP
Response ET:
DFS058I TRACE COMMAND COMPLETED
To turn on storage manager trace tables:
Entry ET:
/TRACE SET ON TABLE STRG
Response ET:
DFS058I TRACE COMMAND COMPLETED
When the storage manager trace tables are no longer needed:
Entry ET:
/TRACE SET OFF TABLE STRG
Response ET:
DFS058I TRACE COMMAND COMPLETED
Entry ET:
/TRACE SET ON TMEMBER CLIENT1 TPIPE TPIPESY
Response ET:
DFS058I 15:45:05 TRACE COMMAND COMPLETED SYS3 DFS996I *IMS READY* SYS3
To log the PCB, I/O area, and PST whenever module DFSDLA30 is invoked to process transaction APPLE:
Entry ET:
/TRACE SET ON TRANSACTION APPLE
Response ET:
DFS058I TRACE COMMAND COMPLETED
To trace all 2740 model 2 terminals:
Entry ET:
/TRACE SET ON UNITYPE 2740II
Response ET:
DFS058I TRACE COMMAND COMPLETED
This is an example of temporary nodes created to retain trace status data.
Entry ET:
/TRACE SET ON NODE DTSLU607
Response ET:
DFS058 TRACE COMMAND COMPLETED
Entry ET:
/DISPLAY NODE DTSLU607
Response ET:
NODE-USR TYPE CID RECD ENQCT DEQCT QCT SENT DTSLU607 UNK 00000000 0 0 0 0 0 TRA *90127/091634*
Entry ET:
/DISPLAY NODE DTSLU607
Response ET:
NODE-USR TYPE CID RECD ENQCT DEQCT QCT SENT DTSLU607 LUT6 -N/A UNK 00000000 0 0 0 0 0 TRA -IMSUS01 01000002 0 0 0 0 0 SIGN(IMSUS01 ) IDLE CON TRA PRI -IMSUS02 01000004 0 0 0 0 0 SIGN(IMSUS02 ) IDLE CON TRA PRI *90127/091432*
Explanation: The /TRACE command is issued for a dynamic ISC NODE that does not yet exist, DTSLU607, causing a temporary node to be created to retain the trace status. Once the ISC parallel sessions IMSUS01 and IMSUS02 are allocated, the trace status is applied to them both.