Trace Exit Program for Trace TCP/IP Application command

Required Parameter Group:

Trace option setting

Input

Char(10)

Application

Input

Char(10)

Error detected

Output

Char(10)

Comparison data¹

Input

Char(*)

QSYSINC/H member name: ESCWCHT

Note 1: Valid only when watch for trace event facility is enabled (WCHMSG or WCHLICLOG or WCHPAL 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, or a PAL entry. PAL stands for Product Activity Log which shows errors that have occurred (such as in disk and tape units, communications, and work stations). 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 starting¹.

*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.

*MSGID¹

A match on a message specified on WCHMSG parameter occurred.

*LICLOG¹

A match on a LIC log specified on the WCHLICLOG parameter occurred.

*CMPDATA¹

The major and minor code of a LIC log matched, but the comparison data did not.

*INTVAL¹

The time interval specified on TRCPGMITV parameter is elapsed.

*WCHTIMO¹

The length of time to watch specified on WCHTIMO is elapsed.

*PAL¹

A match on a PAL and any associated comparison data specified on the WCHPAL parameter occurred.

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

BINARY(4)

Length of trace information

CHAR(7)

Message watched

CHAR(9)

Reserved

BINARY(4)

Offset to comparison data

BINARY(4)

Length of comparison data

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

BINARY(4)

Length of trace information

CHAR(4)

LIC Log major code

CHAR(4)

LIC Log minor code

CHAR(8)

LIC Log identifier

BINARY(4)

Offset to comparison data

BINARY(4)

Length of comparison data

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

BINARY(4)

Length of trace information (always 4 at this time)

The format of the Comparison data is as follows if the Trace option setting is *PAL:

Offset

Type

Field

Dec

Hex

BINARY(4)

Length of trace information

CHAR(8)

System reference code

CHAR(10)

Device name

CHAR(4)

Device type

CHAR(4)

Model

CHAR(15)

Serial number

CHAR(10)

Resource name

CHAR(8)

Log identifier

CHAR(8)

PAL timestamp

CHAR(4)

Reference code

CHAR(8)

Secondary code

CHAR(8)

Table identifier

CHAR(1)

Reserved

BINARY(4)

Sequence

BINARY(4)

Offset to comparison data

100

BINARY(4)

Length of comparison data

104

CHAR(10)

PAL compare against

CHAR(*)

PAL comparison data

Field Descriptions

Device name. The name of a physical device or program that has an entry in the log.

Device type. The number or word used to identify a product.

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.

Log identifier. The unique identifier that ties together all data related to a single error condition.

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.

Start of change Message watched. The message that ocurred. The following special values can be passed:

message id

The 7-character message identifier of the message that occurred.

*IMMED

An immediate or impromptu message occurred.

Model. The numbers or letters used to identify the feature level of a product with a given type (for example, Model A or Model 1).

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

PAL timestamp. The timestamp of when the PAL entry was added. The format for this field is the system time-stamp format. The Convert Date and Time Format (QWCCVTDT) API can be used to convert a time-stamp value to character format.

Reference code.The code that identifies the unique condition for logging the PAL entry.

Resource name. The name of a physical device that has an entry in the log. A resource name is assigned at first by the system, but may have been changed to a new value by a user.

Secondary code. The code for the failing condition (for example, IOP return code, processor step code, program return code, or major minor code).

Sequence.The numbers assigned to the entries in the log that indicate the sequence in which the entries were added. The highest number is the most recent.

Serial number. The number assigned to a part or machine type at the time of manufacture.

System reference code. The code that identifies a unique logging condition. The system reference code is made up of the first four digits of the translate table ID followed by the four digits of the reference code.

Table ID.The identifier of the table that identifies a group of reference codes.

Related Information

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

Exit program introduced: V5R3

[ Back to top | Communications APIs | APIs by category ]