openUTM V7.0 (en)

The UTM Diagarea is a task-specific trace area in which all events are logged. This area thus contains all the events that occurred immediately before a service or application aborted.

The UTM Diagarea is written cyclically. Two cycles are separated by a dividing line comprising '=' characters and blanks. The newest entry is above the dividing line and the oldest entry is below the dividing line. Every entry is 136 long. The total number of entries that can be accommodated by the UTM Diagarea depends on the UTM generation parameter MAX TRACEREC.

The following types of entries are written to the UTM Diagarea:

UTM records (type KDCS)
UTM records of type KDCS are written when the following events occur:
- a KDCS call in a program unit or
- an internal call to the UTM system code or
- a call to the administration programming interface or
- an internal PEND ER call by openUTM (system PEND ER) in response to a serious error.

Additional trace information is written for calls from the administration interface (KDCS-opcode=ADMI), see section "Administration DIAGAREA".

If a PEND ER is issued by the system, then the entry in bytes 22- 57 contains an error text.

UTM records when starting and terminating user-specific event exits:
- FORMAT exit program (types FOXS and FOXE)
- INPUT exit program (types INXS and INXE)
- START exit program (types STXS and STXE)
- VORGANG exit program (types VGXS and VGXE)
- HTTP exit program (Typ HTXS und HTXE)
UTM records to identify the service (type VGID)
A VGID record is written to the UTM Diagarea every time a program unit is started and when a PGWT call returns.

FORM records (type FHCL)
A FORM record is written on a call to a formatting system.

UTM records when HTTP functions are called (type HTTP )
A HTTP record is written when a HTTP function is called.

Header for the records in the UTM Diagarea

Every record starts with a header containing the following information:

Byte		Meaning
dec.	hexadec.	Meaning
0-1	00-01	Count of the current entries in the DIAGAREAs (UTM and DB)
2-5	02-05	Type identifications (KDCS, VGID, INXS, INXE, STXS, STXE, VGXS, VGXE, ITRC, HTXS , HTXE, HTTP, FOXS, FOXE, FHCL)
6-7	06-07	Currently not used (preset to ’= =’)
8-15	08-0F	Time stamp

Structure of the header

As of byte 16, the content of the records depends on the record type.

Structure of the UTM Diagarea for a KDCS call from a program unit

Byte		Field name and meaning
dec.	hexadec.
16-19	10-13	KCOP:¹	user operation code: INIT, MGET, MPUT, etc.
			internal operation code: see "table KCOP"
20-21	14-15	KCOM: operation modification
22-23	16-17	KCLA: area length or queue level (in the case of QCRE) or KCLKBPRG: length of KB program area with INIT
24-25	18-19	KCLM: message length or KCLPAB: length of standard primary work area with INIT KCWTIME: wait time in seconds in the case of DGET
26-33	1A-21	KCRN: reference name
								MCOM call
34-41	22-29	KCMF:format name or edit profile name KCLT: LTERM name of the LTERM partner or KCUS: user ID or KCPA: name of the partner application (with APRO call)						KCPOS: destination of positive confirmation job
42-43	2A-2B	KCDF: screen function, see "table KCDF"						KCNEG: Destination of negative confirmation job
		DPUT/DADM		DGET	QCRE	PADM	APRO
44	2C	KCMOD: mode (“A”/”R”/”_”)		KCQTYP: destination type ("U"/"Q"/"T")	KCQMODE: mode ("S"/ "W"/bin. zero)	KCACT: action (ON/OFF/CON/DIS)	KCPI: service ID
45-47	2D-2F	KCTAG: days		empty	empty
48-49	30-31	KCSTD: hours				KCADRLT: new LTERM name of the printer
50-51	32-33	KCMIN: minutes						KCCOMID: complex ID
52-53	34-35	KCSEC: seconds					KCOF: OSI TP functions
54	36	KCQTYP: destination type ("U"/"Q"/bin. zero)
55-57	37-39	empty				empty
58-89	3A-59	KCRFELD in KCKBC: KB return information areasee "table KCDF"
92-95 (32-Bit) 96-103 (64-Bit)²	5C-5F (32-Bit) 60-67 (64-Bit)²	Return address to the program unit (the address points to a position after the KDCS call in the program unit)
96-99 (32-Bit) 104-111 (64-Bit)²	60-63 (32-Bit) 68-6F (64-Bit)²	Address of the user data area (2nd parameter of the KDCS call)
100-103 (32-Bit) 112-119 (64-Bit)²	64-67 (32-Bit) 70-77 (64-Bit)²	Service index
104-111 (32-Bit) 120-127 (64-Bit)²	68-6F (32-Bit) 80-87 (64-Bit)²	KCLOGTER in KCKBC: LTERM name
112-119 (32-Bit) 128-135 (64-Bit)²	70-77 (32-Bit) 88-8F (64-Bit)²	KCBENID in KCKBC: name of the current user ID

Structure of an entry of the UTM Diagarea for a KDCS call

¹If KCOP=INFO (bytes 16-19) and in the event of operation modification KCOM=CK (bytes 20-21), the message area of the logged call is written to the next entry of the UTM Diagarea at a length KCPAC. This information is of interest for diagnostic purposes, as it logs the call to be checked.

² The 64 bit specifications only apply to Unix, Linux and Windows systems.

The following entries are possible in the KCDF field (bytes 42-43; screen function):

Contents KCDF, hexadecimal	Symbolic name	Meaning
0000	-----	no screen function
0001	KCREPL	clear screen and output format
0001	KCRESTRT	screen restart after PEND RS
0002	KCERAS	erase unprotected fields
0004	KCALARM	BEL function
0008	KCREPR	local printer output

For internal calls from openUTM, the following codes are entered in the KCOP field:

KCOP contents	Situation in which this entry was written	Entries in subsequent fields
STRT	Start of UTM application program, beginning of start handling in the UTM system code	No entry
WAIT	UTM process is waiting in the system code for the next request	No entry
CONT	Continuation in UTM system code after execution of formatting or a DB action via KDCROOT or after the INPUT exit is called	KCRCCC, KCRCKZ and KCRCDC only. for INPUT exit: parameters, see table "UTM Diagarea after a call of the INPUT exit"
NOOP	Buffer area of MESSAREA must be emptied (only possible when event monitor is switched on)	- - -
ADMI	UTM administration action	UTM internal interface

Structure of KCRFELD

Byte		Field name and meaning
dec.	hexadec.	Field name and meaning
58-59	3A-3B	KCRDF: screen function return KCRWVG: number of waiting services with DGET
60-61	3C-3D	KCRLM: actual length of the message
		INFO CK call		MGET call	SIGN ON call
62	3E	KCRINFCC: KDCS return code of the KDCS call checked		KCVGST: service status	KCRSIGN1: primary code
63	3F			KCTAST: transaction status	KCRSIGN2: secondary code
64	40			empty	KCRSIGN2: secondary code
65	41	empty	KCRMGT: message type
66-68	42-44	KCRCCC: KCDS return code
69	45	KCRCKZ: identifier: P (productive or live operation application),
70-73	46-49	KCRCDC: internal return code
74-81	4A-51	KCRMF: return of the format identifier , edit profile or the abstract syntax
82-89	52-59	KCRPI: service identification return KCRUS: user ID in the case of SIGN ST or creator of the message with DGET KCRQN: name assigned by openUTM to the temporary queue in the case of QCRE NN

UTM Diagarea after a call of the INPUT exit

After the INPUT exit is called, openUTM enters the most important parameters that the exit receives or sets (KCPAC) in the KDCS record:

Byte		Field name and meaning
dec.	hexadec.	Field name and meaning
16-19	10-13	KCOP: "CONT" is entered here
20-25	14-19	empty
26-33	1A-21	KCIFCH: first 8 characters of input
34-35	22-23	KCICVST: service status: "ES"/"ET"/"RS"/"EC
36-37	24-25	KCIFKEY: value of F key: 1,...,24
38-39	26-27	KCIKKEY: value of K key: 1,...,14
40-41	28-29	KCICFINF: information about control fields: "UN"/"NO"/"ON"/"MO"
42-49	2A-31	KCINTAC/KCINCMD: next TAC to be started or next user command
50-51	32-33	KCICCD: code for effect of input: "ER"/"CC"/"SC"/"ST"/"CD"
52	34	KCICUT: truncate TAC: "Y"/"N"
53	35	---
54-57	36-39	KCIERRCD: error info for data display terminal
58-...	3A-...	the following is not relevant for diagnostics

Structure of an UTM Diagarea entry after a call of the INPUT exit

Error texts in UTM Diagarea after SYSTEM PEND ER

To allow more rapid diagnosis in the event of a SYSTEM-PEND ER, the corresponding line of the UTM Diagarea contains a printable error text in bytes 22-57.

The following table contains a list of all error texts, plus the relevant cause of the error, the module where the PEND ER occurred and the type of error involved (system error or user error).

The error texts marked with *) appear only on BS2000 systems and the values marked with **) appear only on Unix, Linux and Windows systems.

Error text	Cause, module	Error type
APPL. PROGRAM DOES NOT EXIST	No indicator (KCRARA) for a program unit existed when program unit started (70Z with KR01).	System error
APPL. PROGRAM WITHOUT PEND	Program unit run was not terminated with PEND. (84Z)	User error
ASYNC. PROGRAM NOT FOUND	Asynchronous program no longer available (program may have been exchanged). PEND ER dump follows with 70Z and KR02.	User error
ERROR IN "START-TP" OF LGCON	The language connection module supplied an incorrect return code when program unit was started.	System error
KB END LABEL OVERWRITTEN	The KB in the application program is greater than specified in the UTM generation (70Z with KR04). Action: change KB= operand in the MAX statement or adjust program unit.	User error
SPAB END LABEL OVERWRITTEN	The SPAB in the application program is greater than specified in UTM generation (70Z with KR05). Action: change SPAB= operand in MAX statement	User error
KCRCCC >= 70Z AFTER UTM SVC	UTM SVC set KCRCCC in KB header to >= 70Z	User/system error
ROOTDATA CODE INVALID **)	UTM SVC set ROOTDATA CODE to an invalid value	System error
ERROR ROUTINE XT... ENTERED **)	A signal with the number ...(in KDCRTDI) occurred.	User/system error
ERROR ROUTINE EXIT ENTERED **)	An illegal exit() call (COBOL: STOP RUN statement) was recognized while a program unit was running; see also under return code KCRCDC= EXIT.	User error
ERR IN STXIT-ROUTINE OF LGCON *)	During STXIT handling, an faulty return code was supplied by the Language Connection Module.	User/system error
STXIT WITH XT.. ENTERED *)	A STXIT with weight .. occurred.	System error
DB ERRORCODE = TA_CHAIN_RSET	The database connection module supplied return code' TA_CHAIN_RSET' . If this return code was issued by one of the messages K210, K211 or K216 with XAER_DUPID, the cause could be that the previous application run was terminated abnormally, and left a transaction in the database and that a new KDCFILE was generated in this state. Action in this event: shut down and restart the database.	System error
KDCS CALL IN VORGANG EXIT	An illegal KDCS call was made in the VORGANG exit program.	User error
VORGANGEXIT PROGRAM NOT LOADED	The VORGANG exit program is not loaded.	User error
KDCS CALL IN FORMAT EXIT *)	An illegal KDCS call was made in the FORMAT EXIT program.	User error
DATABASE DOWN AT USER DB CALL	The database was no longer connected at the time of the CALL to the database from the application program unit.	User/ system error
ILLEGAL RTCODE FROM DBCON	The database connection module supplied an illegal error code.	System error
NO DB CALL ALLOWED IN SIGN-ON	The sign-on service has issued an illegal DB-USER-CALL	User error
PROGRAM INDEX = 0 INVALID **)	UTM SVC set an invalid program index.	System error
DYNAM. PROGRAM LOADING FAILED *)	An error occurred when loading a program. PEND ER dump with 70Z and KR09	User/system error

Error texts in UTM Diagarea after SYSTEM PEND ER

Service identification entry (type VGID)

Byte 32-Bit		Byte: 64-Bit )**		Meaning
dec.	hexadec.	dec.	hexadec.	Meaning
16	10	16	10	Service ID
17	11	17	11	Session counter
18-19	12-13	18-19	12-13	Transaction counter in the service
20-23	14-17	24-31	18-1F	Service counter
24-27	18-1B	32-39	20-27	Sum of USED and ERROR for the current TAC
28-31	1C-1F	40-47	28-2F	Length of the global transaction identifier (GTRID) of the XID
32-35	20-23	48-55	30-37	Length of the branch qualifier (BQUAL) of the XID
36-115	24-73	56-137	38-89	The first 80 bytes of the XID data ^*)
116-117	74-75	138-139	8A-8B	Index to the program table
118-119	76-77	140-141	8C-8D	Index of the service exit in the program table
120-127	78-7F	142-149	8E-95	Name of the transaction code that started the service
128-135	80-87	150-157	96-9D	Name of the current transaction code

Structure of the service identification entry

*) For details on XID, GRTID and BQUAL, please refer to the corresponding XA specification
**) only valid for Unix, Linux and Windows systems

VORGANG exit entry (types VGXS and VGXE)

Byte 32-Bit		Byte: 64-Bit )**		Meaning
dec.	hexadec.	dec.	hexadec.	Meaning
16	10	16	10	Service ID
17	11	17	11	Session counter
18-19	12-13	18-19	12-13	Transaction counter in the service
20-23	14-17	24-31	18-1F	Service counter
24-27	18-1B	32-39	20-27	Sum of USED and ERROR for the current TAC
28-31	1C-1F	40-47	28-2F	Length of the global transaction identifier (GTRID) of the XID
32-35	20-23	48-55	30-37	Length of the branch qualifier (BQUAL) of the XID
36-115	24-73	56-137	38-89	The first 80 bytes of the XID data ^*)
116-117	74-75	138-139	8A-8B	Index to the program table
118-119	76-77	140-141	8C-8D	Index of the service exit in the program table
120-127	78-7F	142-149	8E-95	Name of the transaction code that started the service
128-135	80-87	150-157	96-9D	Name of the SERVICE exit program

Structure of the SERVICE exit entry

*) For details on XID, GRTID and BQUAL, please refer to the corresponding XA specification
**) only valid for Unix, Linux and Windows systems

FORMAT exit entry (types FOXS and FOXE)

Byte		Meaning
dec.	hexadec.	Meaning
16-31	10-1F	String FORMATEXIT
32-39	20-27	Program name of the FORMAT exit
40-47	28-2F	Format name
48-63	30-3F	Type of formatting as a character string (e.g. OUTPUTFORMATTING)

Structure of the FORMAT exit entry

INPUT exit entry (types INXS and INXE)

Byte		Meaning
dec.	hexadec.	Meaning
16-31	10-1F	String INPUT-EXIT-FORM or INPUT-EXIT-USER or INPUT-EXIT-LINE
32-39	20-27	Program name of the INPUT exit
40-47	28-2F	The first 8 characters of the input message
48-55	30-37	Format name
56-63	38-3F	TAC name
64-65	40-41	Status
66-67	42-43	F key
68-69	44-45	K key
70-71	46-47	Control field
72-79	48-4F	Lterm name
80-87	50-57	User name
88-119	58-77	(Not used)
120-127	78-7F	Next TAC or command
128-129	80-81	Continuation code
130	82	CUT TAC
131	83	(Not used)
132-135	84-87	Error code

Structure of the INPUT exit entry

START exit entry (types STXS and STXE)

Byte		Meaning
dec.	hexadec.	Meaning
16-31	10-1F	String START-EXIT-# (# = 1 - 8 stands for the number of the START exit.)
32-39	20-27	Program name of the START exit
40-47	28-2F	String STARTUP (fixed name of the TAC)
48-63	30-3F	Indicator, if the first process or the follow-up process is the string

Structure of the START exit entry