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 Writing a program error program for programming information about modifying the DFHPEP program.

For information about the trace entry format, see Using CICS trace.

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 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. Use a name that identifies the user trace, for example, the name of the calling program.
TRACENUM(data-value): specifies the trace identifier for a user trace table entry as a halfword binary value in the range 0 through 199. Trace identifiers can be used to filter a dump, so you might want to specify a value that enables convenient filtering. See Using dumps in problem determination.
It is advisable to specify a number that is not already in use. For example, numbers 1 through 20 might be in use if CICSPlex® SM is installed. The following numbers might be in use if various CICS sample programs are installed: 4-8, 11-13, 15-20, 27, 33, 35-37, 50-52, 77, 101-102, 190. Also, check your own system for user trace numbers already in use.

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.