Trace Exit Program for Trace TCP/IP Application command

Note 1: Valid only when watch for trace event facility is enabled (WCHMSG or WCHLICLOG parameters were specified)

The Trace TCP/IP Application (TRCTCPAPP) command has the capability to call a user-written program, if specified in the TRCPGM parameter. This user written program will be called in the following circumstances:

For SET(*ON), the trace program will be called:

• Before the application trace starts.
• After the communications and Licensed Internal Code (LIC) traces, if requested, start.

For SET(*OFF), the trace program will be called:

• Before the LIC traces, if requested, end.
• After the communications trace, if requested, ends.
• After the application trace ends.

For SET(*END), the trace program will be called:

• After the LIC and communications traces, if requested, end.
• After the application trace ends.

Also, the Trace TCP/IP Application (TRCTCPAPP) command has the capability to watch for a specific event and end the trace when this event occurs. An event can be a message being sent to a specific message queue, history log or job log; or a LIClog. If specified in the TRCPGM parameter, the watch for trace event facility will call a user-written program at the moments specified in the Trace option setting parameter.

See the online help for more information on the TRCTCPAPP command.

Authorities and Locks

None.

Required Parameter Group

Trace option setting

INPUT; CHAR(10)

The reason indicating the moment at which the user-written program was called. The possible values are:

*ON	- The collection of trace information is started, or  - The watch for trace facility is starting1.
*OFF	The collection of trace information is stopped and the trace information is written to spooled printer files of the user.
*END	Tracing is ended and all trace information is deleted. No trace information output is created.
*MSGID1	A match on a message id specified on WCHMSG parameter occurred.
*LICLOG1	A match on a LIC log specified on the WCHLICLOG parameter occurred.
*CMPDATA1	The major and minor code of a LIC log matched, but the comparison data did not.
*INTVAL1	The time interval specified on TRCPGMITV parameter is elapsed.
*WCHTIMO1	The length of time to watch specified on WCHTIMO is elapsed.

Application.

INPUT; CHAR(10)

The possible values for the "Application" parameter are the same as the values for the APP parameter on the TRCTCPAPP command. Ignored by watch for trace event facility.

Error detected

OUTPUT; CHAR(10)

Indicates if the trace event facility should stop or continue running, or if an error on the user-written program was found. The possible values are:

• *CONTINUE¹ - The trace and the watch for trace event facility.
• *STOP¹ - The trace and the watch for trace event facility will be ended.
• *ERROR - Error detected by customer trace program.

Comparison data

INPUT; CHAR(*)

The format of the trace information depends on the Trace option setting causing the exit program to be called. The format of the Comparison data is as follows if the Trace option setting is *MSGID:

Offset		Type	Field
Dec	Hex
0	0	BINARY(4)	Length of trace information
4	4	CHAR(7)	Message ID
11	B	CHAR(9)	Reserved
20	14	BINARY(4)	Offset to comparison data
24	18	BINARY(4)	Length of comparison data
28	1C	CHAR(*)	Message comparison data

The format of the Comparison data is as follows if the Trace option setting is *LICLOG or *CMPDATA:

Offset		Type	Field
Dec	Hex
0	0	BINARY(4)	Length of trace information
4	4	CHAR(4)	LIC Log major code
8	8	CHAR(4)	LIC Log minor code
12	C	CHAR(8)	LIC Log identifier
20	14	BINARY(4)	Offset to comparison data
24	18	BINARY(4)	Length of comparison data
28	1C	CHAR(*)	LIC Log comparison data

The format of the Comparison data is as follows if the Trace option setting is *ON, *INTVAL or *WCHTIMO:

Offset		Type	Field
Dec	Hex
0	0	BINARY(4)	Length of trace information (always 4 at this time)

Field Descriptions

Length of trace information.  The length of the Comparison data parameter passed to the user-written exit program.

Length of comparison data.  The length of the user specified text to be compared against the event data.

LIC Log identifier. The LIC Log entry identifier of the LIC Log that occurred.

LIC Log major code. The major code of the LIC Log that occurred.

LIC Log minor code. The minor code of the LIC Log that occurred.

LIC Log comparison data. The user specified text string used to compare against the entry data of the watched for log entry.

Message ID.  The identifier of the message that occurred.

Message comparison data. The user specified text string used to compare against the entry data of the watched for message ID.

Offset to comparison data.  The offset to the field that holds the comparison data.

Related Information

See the Trace TCP/IP Application (TRCTCPAPP) command for more information.