ENTER TRACENUM

Write a trace entry.

ENTER TRACENUM

Conditions: INVREQ, LENGERR

This command is threadsafe.

Description

The ENTER TRACENUM command makes a trace entry in the currently active trace destinations. CICS® writes the trace entry only if the main and user trace flags are on, unless you specify the EXCEPTION option, in which case a user trace entry is always written, even if the main and user trace flags are off. Exception trace entries are always written to the internal trace table (even if internal tracing is set off), but they are written to other destinations only if they are active.

You can use the exception trace option in an application program to write a trace entry when the program detects an exception or abnormal condition. To do this, include an ENTER TRACENUM(data-value) EXCEPTION command in your program's exception or abnormal condition error-handling routine.

To write an exception trace entry in an error situation when an application program has given up control, you can issue an ENTER TRACENUM(data-value) EXCEPTION command from a user-written program error program (PEP). See the Writing a program error program for programming information about modifying the DFHPEP program.

Note ENTER TRACENUM replaces the earlier ENTER TRACEID command, which is still supported for compatibility with releases of CICS earlier than Version 3. You should use ENTER TRACENUM for all new programs, and whenever you apply maintenance to old programs.

For information about the trace entry format, see Using traces in problem determination .

Options

EXCEPTION: specifies that CICS is to write a user exception trace entry. The EXCEPTION option overrides the main user trace flag, and CICS writes the trace entry even if the user trace flag is off. Exception trace entries are identified by the characters *EXCU when the trace entries are formatted by the trace utility program. See the CICS exception tracing for more information about user exception trace entries.
FROM(data-area): specifies a data area whose contents are to be entered into the data field of the trace table entry. If you omit the FROM option, two fullwords of binary zeros are passed.
FROMLENGTH(data-area): specifies a halfword binary data area containing the length of the trace data, in the range 0–4000 bytes. If FROMLENGTH is not specified, a length of 8 bytes is assumed.
RESOURCE(name): specifies an 8-character name to be entered into the resource field of the trace table entry.
TRACENUM(data-value): specifies the trace identifier for a user trace table entry as a halfword binary value in the range 0 through 199.

Conditions

16 INVREQ

RESP2 values:

1: TRACENUM is outside the range 0 through 199.
2: There is no valid trace destination.
3: The user trace flag is set OFF and EXCEPTION has not been specified.

Default action: terminate the task abnormally.

22 LENGERR

RESP2 values:

4: FROMLENGTH is outside the range 0 through 4000.

Default action: terminate the task abnormally.

Examples

The following COBOL example shows how to write a user trace entry with a trace identifier of 123, with trace data from a data area called USER-TRACE-ENTRY:

EXEC CICS ENTER TRACENUM(123)
     FROM(USER-TRACE-ENTRY)
END-EXEC.