KDCDIAG allows you to switch UTM functions on and off which will support you during error diagnosis. The following functions can be called:
Switch test mode on or off.
Create a UTM dump during live operation for diagnostic purposes.
Cause openUTM to generate a dump when a specific event occurs.
Switch UTM event monitor KDCMON on or off.
Switch the BCAM trace function on or off. This function traces all connection-related activities in the application. The BCAM trace function can only be switched on for individual, explicitly specified communication partners.
Switch the OSS trace function on or off. The OSS trace helps with the diagnosis of problems affecting OSI TP connections.
Output debug information for the database connection.
Switch over log files for the UTM application.
Effect in cluster operation
The effect on UTM cluster applications is described in the sections devoted to the individual operands since some of the changes made with KDCDIAG apply locally to the node whereas others take effect globally in the cluster. Changes made locally in a node apply at the most for the duration of the current application run. Changes made globally in the cluster apply at the most for the duration of the current cluster application run.
Period of validity of the changes
Every change remains effective for the duration of the application run or until it is reset.
KDCDIAG [ DUMP=YES ]
[ ,{ DUMP-MESSAGE | DUMP-MESSAGE{1|2|3} }= { (MSG, msg-nr) | (SIGN, sign) | (RCCC, rccc) | (RCDC, rcdc) | *NONE } ]
[ ,INSERT1= (insert-nr, value, { EQ | NE }) ]
[ ,INSERT2= (insert-nr, value, { EQ | NE }) ]
[ ,INSERT3= (insert-nr, value, { EQ | NE }) ]
[ ,KDCMON= { ON | OFF } ]
[ ,TESTMODE={ ON | OFF } ]
[ ,BTRACE= { ON | OFF } [ , { LTERM ={ ltermname | (ltermname_1,...,ltermname_10) } | LPAP = { lpapname | (lpapname_1,...,lpapname_10) } | USER = { username | (username_1,...,username_10) } | MUX = ( mux-name, proname, bcamappl ) 1 } ]
[ ,OTRACE= { ON | (SPI,INT,OSS,SERV,PROT) | OFF } ]
[ ,STXIT-LOG={ ON | OFF } ] 1
[ ,XA-DEBUG={ YES | ALL | OFF} ]
[ ,XA-DEBUG-OUT={ SYSOUT | FILE} ]
1 Only on BS2000 systems
For administration using message queuing you must specify KDCDIAGA.
DUMP=YES | ||
Requests a UTM dump during live operation. The UTM dump (taken from only one process in the application) is created with the reason "REASON=DIAGDP". In UTM cluster applications, the operand applies locally in the node. | ||
DUMP-MESSAGE=[1...3] | ||
Here, you specify an event that forces openUTM to create a UTM dump if it occurs. The command KDCDIAG DUMP-MESSAGE= is only evaluated when test mode is enabled (TESTMODE=ON). In UTM cluster applications, the operand applies globally in the cluster . The dump is created by the process in which the error occurs. The application is not terminated. The parameters DUMP-MESSAGE1, DUMP-MESSAGE2 and DUMP-MESSAGE3 allow you to define up to three different events for which a message dump is to be generated if they occur. The specification DUMP-MESSAGE is synonymous with DUMP-MESSAGE1. For each KDCDIAG demand, you can specify a maximum of one DUMP-MESSAGE[i] parameter. You can specify the following events:
The dump ID is dependent on the event:
| ||
MSG, msg-no | ||
Specify UTM message number in the form Knnn or Pnnn for msg-no. A dump is generated each time the specified message number occurs until such time as the message number is reset. The message numbers | ||
SIGN, sign | ||
Specify a SIGNON status code (3 characters) for sign, e.g. U04, where KCRSIGN1 must have the value U, I, A or R. If this code occurs when a user signs on then the process in which the SIGNON status occurred generates a UTM dump with the ID SG-U04. This happens irrespective of whether a signon service has been generated in the application or not. The message dump for this event is then automatically deactivated. | ||
RCCC, rccc | ||
Specify a KDCS return code (KCRCCC, e.g. "40Z") for rccc and an incompatible KDCS return code (KCRCDC, e.g. "KD10") for rcdc. If this return code occurs on a KDCS call then the process in which the return code occurred generates a UTM dump with the ID CC-40Z or DCKD10. The message dump for this event is then automatically deactivated. For all KDCS return codes >= 70Z and the associated incompatible KDCS return codes for which a PENDER dump is never generated (e.g. 70Z/K316), no dump is generated either. | ||
*NONE | Explicit deactivation of an event for a message dump. | |
INSERT1...INSERT3=(insert-no, value, {EQ | NE}) | ||
Here you can specify up to three inserts as additional conditions for the message msg-no in order to further restrict the generation of a dump. INSERTx is only evaluated if DUMP-MESSAGE[i] is also specified. A message dump is only generated if all the criteria specified in INSERT1 ... INSERT3 are met. You will find the sequence of the inserts of a message in the relevant, system-specific openUTM manual ”Messages, Debugging and Diagnostics”. insert-no value
EQ | NE | ||
KDCMON= | ||
Switches the UTM event monitor on or off. In UTM cluster applications, the operand applies locally in the node. | ||
ON | Switches on the UTM event monitor. | |
OFF | Switches the UTM event monitor back off. | |
TESTMODE= | Switches the test mode on and off. In UTM cluster applications, the operand applies globally in the cluster. | |
ON | Test mode is switched on. This means that additional internal UTM routines conduct plausibility checks and that internal TRACE information is recorded. Trace information is written in the KTA module and - with OSI TP applications - also in the XAPTP module. Trace mode should only be switched on in order to generate diagnostic documents. | |
OFF | Switch test mode off. Default: displays the current setting. | |
BTRACE= | Switches the BCAM trace function of UTM on and off. The BCAM trace function of UTM traces all connection-specific activities occurring in a UTM application. The BTRACE function can be switched on using the start parameter BTRACE when the application is started. You can switch on the BTRACE function for all connections in an application or on a partner-specific basis for connections to specified LTERM and LPAP partners. | |
ON | The BTRACE function is usually switched on; it logs events relating to all connections to any given communication partner in the application (clients and partner applications in a distributed processing environment based on LU6.1). In UTM cluster applications, the specification of BTRACE=ON without any other parameters applies globally in the cluster. | |
ON, LPAP=lpapname|(lpapname_1,...,lpapname_10) | ||
In UTM cluster applications, the operand applies locally in the node. | ||
or | ||
ON, LTERM=ltermname|(ltermname_1,...,ltermname_10) | ||
In UTM cluster applications, the operand applies locally in the node. | ||
or | ||
ON, USER=username|(username_1,...,username_10) | ||
In UTM cluster applications, the operand applies globally in the cluster. | ||
or | ||
ON, MUX=(mux_name,proname,bcamappl) (only on BS2000 systems) | ||
In UTM cluster applications, the operand applies locally in the node. The BTRACE function is switched on a partner-specific basis and all events relating to connections with specified partners or users or the MUX partners are logged. The following specifications must be made:
The BTRACE function can only be switched on explicitly for connections with certain partner applications, clients or users if it is not already switched on for all connections in that application. If you wish to switch on the BTRACE functions for a few partner applications and a few clients, call the KDCDIAG command repeatedly:
| ||
OFF | The BTRACE function is switched off on all of the application’s connections, even if it was originally switched on a partner-specific basis. In UTM cluster applications, the specification of BTRACE=OFF without any other parameters applies globally in the cluster. | |
OFF, LPAP=lpapname|(lpapname_1,...,lpapname_10) | ||
In UTM cluster applications, the operand applies locally in the node. | ||
or | ||
OFF, LTERM=ltermname|(ltermname_1,...,ltermname_10) | ||
In UTM cluster applications, the operand applies locally in the node. | ||
or | ||
OFF, USER=username|(username_1,...,username_10) | ||
In UTM cluster applications, the operand applies globally in the cluster. | ||
or | ||
OFF, MUX=(mux_name,proname,bcamappl) (only on BS2000 systems) | ||
In UTM cluster applications, the operand applies locally in the node. This switches off the BTRACE function for connections to the partner applications specified in lpapname_1,...,lpapname_10 or to the clients specified in ltermname_1,...,ltermname_10 or to the users specified in username_1,...,username_10 or the MUX partner. | ||
OTRACE= | Switching the OSS trace function on and off. In UTM cluster applications, the operand applies globally in the cluster . Trace records of the types SPI, INT, OSS, SERV and PROT are logged. | |
ON | Switches on the OSS trace function for all types of record. | |
(SPI, INT, OSS, SERV, PROT) | ||
Switches the OSS trace function on. The trace records for the specified type are logged. The types can be entered in any sequence. SPI INT OSS SERV PROT | ||
OFF | Switches off the OSS trace function; the trace files are closed and can be evaluated. For further details, please refer to the openUTM manual ”Messages, Debugging and Diagnostics” and the OSS manual. | |
STXIT-LOG= | Only on BS2000 systems: Enable/disable extended STXIT logging in the event of STXIT handling problems. Several K099 messages are issued to SYSOUT when a STXIT event occurs. In UTM cluster applications, the operand applies locally in the node. | |
ON | Enables STXIT logging. | |
OFF | Disables STXIT logging. | |
XA-DEBUG= | Specifies whether debug information for the XA database connection is to be output. In UTM cluster applications, the operand applies locally in the node. | |
YES | XA-DEBUG is enabled, and calls to the XA interface are logged. | |
ALL | Extended XA-DEBUG: specific data areas are output in addition to the calls to the XA interface. | |
OFF | Disables XA-DEBUG. | |
XA-DEBUG-OUT= | ||
Controls the output destinations for XA-DEBUG. In UTM cluster applications, the operand applies locally in the node. | ||
SYSOUT | The log is written to SYSOUT/stderr, default. | |
FILE | The log is written to a file. If you specify only XA-DEBUG in the KDCDIAG command, without entering a value for XA-DEBUG-OUT then this may lead to a modification of the value which you specified in the start parameter when starting the UTM application (see openUTM manual “Using UTM Applications”). Otherwise log entries are written to SYSOUT/stderr. | |
It only makes sense to change the two operands XA-DEBUG and XA-DEBUG-OUT in a UTM application in which a database connection has been generated over the XA interface.
Output from KDCDIAG
If KDCDIAG DUMP=YES then the message “DIAGNOSTIC DUMP CREATED” is issued. With the other operands, UTM displays the new and old settings for diagnostic aids on the administrator terminal:
STATUS NEW OLD
TESTMODE ON|OFF ON|OFF
KDCMON ON|OFF ON|OFF
OSS-TRACE ON|OFF ON|OFF
SPI INT OSS SERV PROT SPI INT OSS SERV PROT
BTRACE ON S|ON A|OFF ON S|ON A|OFF
LTERM/LPAP/USER BTRACE
NEW OLD
ltermname ON|OFF ON|OFF
lpapname ON|OFF ON|OFF
username ON|OFF ON|OFF
STXIT-LOG ON|OFF ON|OFF
XA-DEBUG YES|ALL|OFF YES|ALL|OFF
XA-DEBUG-OUT SYSOUT|FILE SYSOUT|FILE
Explanation of the output
TESTMODE | The line for TESTMODE is always displayed, regardless of whether or not the KDCDIAG call contains the TESTMODE operand. |
KDCMON | The line for KDCMON is always displayed, regardless of whether the KDCDIAG call contains the KDCMON operand or not. |
BTRACE | The line for BTRACE is always displayed. With BTRACE (ON) (switched on), the display also shows whether the trace function is switched on for all connections in the application (ON A, A=all) or just for connections to a few communication partners (ON S, S=select). |
OSS-TRACE | The line for OSS-TRACE is always displayed if the OTRACE operand was specified in the KDCDIAG call. |
LTERM/LPAP/USER | |
Is only displayed if the BCAM trace function is/was explicitly switched on for connections to particular communication partners (LPAP, LTERM or MUX partners) or for users. | |