Exit Program for Watch for Event

The Watch for event functionality is started by the STRWCH command or the Start Watch (QSCSWCH) API, and has the capability to notify the user by calling a user exit program when the specified event occurs. An event can be a message being sent to a message queue, job log, or LIClog. The user-written program will be called in the cicumstances specified in the Watch option setting parameter.

Authorities and Locks

None.

Required Parameter Group

Watch option setting

INPUT; CHAR(10)

The reason indicating why the user-written program was called. The possible values are:

*MSGID	A match on a message id and any associated comparison data specified on watch for message parameter occurred.
*LICLOG	A match on a LIC log and any associated comparison data specified on the watch for LIC Log entry parameter occurred.

Session ID

INPUT; CHAR(10)

The name of the session that is calling the exit program.

Error detected

OUTPUT; CHAR(10)

Indicates if an error on the user-written program was found.

The possible values are:

*ERROR	Error detected by watch exit program. The watch session that was passed in Session ID parameter will be ended. If the watch session to be ended originally specified multiple message ids or LIC log entries, all of them will no longer be watched.
<blanks>	No error detected by watch exit program.

Note: Any value other than "*ERROR" or <blanks> will be considered an error and the watch session that was passed in Session ID parameter will be ended. If the watch session to be ended originally specified multiple message ids or LIC log entries, all of them will no longer be watched.

Event data

INPUT; CHAR(*)

The format of the watch information depends on the Watch option setting causing the exit program to be called.

The format of the Event data is as follows if the Watch 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(1)	Reserved
12	C	CHAR(10)	Message queue name
22	16	CHAR(10)	Message queue library
32	20	CHAR(10)	Job name
42	2A	CHAR(10)	Job user name
52	34	CHAR(6)	Job number
58	3A	CHAR(4)	Reserved
62	3E	CHAR(256)	Sending program name
318	13E	CHAR(10)	Sending module name
328	148	BINARY(4)	Offset to sending procedure name
332	14C	BINARY(4)	Length of sending procedure name
336	150	CHAR(10)	Receiving program name
346	15A	CHAR(10)	Receiving module name
356	164	BINARY(4)	Offset to receiving procedure name
360	168	BINARY(4)	Length of receiving procedure name
364	16C	BINARY(4)	Message severity
368	170	CHAR(10)	Message type
378	17A	CHAR(8)	Message timestamp
386	182	CHAR(4)	Message key
390	186	CHAR(10)	Message file name
400	190	CHAR(10)	Message file library
410	19A	CHAR(2)	Reserved
412	19C	BINARY(4)	Offset to comparison data
416	1A0	BINARY(4)	Length of comparison data
420	1A4	CHAR(10)	Compare Against
430	1AE	CHAR(2)	Reserved
432	1B0	BINARY(4)	Comparison data CCSID
436	1B4	BINARY(4)	Offset where comparison data was found
440	1B8	BINARY(4)	Offset to replacement data
444	1BC	BINARY(4)	Length of replacement data
448	1C0	BINARY(4)	Replacement data CCSID
*	*	CHAR(*)	Sending procedure name
*	*	CHAR(*)	Receiving procedure name
*	*	CHAR(*)	Message comparison data
*	*	CHAR(*)	Message replacement data

The format of the Event data is as follows if the Watch option setting is *LICLOG:

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	CHAR(8)	LIC Log timestamp
28	1C	CHAR(8)	TDE number
36	24	CHAR(16)	Task name
52	34	CHAR(30)	Server type
82	52	CHAR(2)	Exception ID
84	54	CHAR(10)	LIC job name
94	5E	CHAR(10)	LIC job user name
104	68	CHAR(6)	LIC job number
110	6E	CHAR(4)	Reserved
114	72	CHAR(8)	Thread ID
122	7A	CHAR(8)	LIC module compile timestamp
130	82	CHAR(8)	LIC module offset
138	8A	CHAR(8)	LIC module RU name
146	92	CHAR(48)	LIC module name
194	DA	CHAR(128)	LIC module entry point name
322	142	CHAR(2)	Reserved
324	144	BINARY(4)	Offset to comparison data
328	148	BINARY(4)	Length of comparison data
*	*	CHAR(*)	LIC Log comparison data

Field Descriptions

Compare against. The part of the message the data specified in message comparison data field was compared against. This field is set to blanks if zero was specified for the length of comparison data field. The possible values are:

Comparison data CCSID. The coded character set identifier (CCSID) of the message comparison data.

Exception ID. The exception that caused the LIC log entry to be requested. This is a 2-byte hexadecimal field formed by concatenating to the high-order 1-byte exception group number a low-order 1-byte exception subtype number. Exception identifier is binary zeros if the LIC log entry was not requested as a result of an exception.

Job name. The name of the job that sent the message.

Job number. The job number (000001-999999) to further qualify the job name and user name of the job that sent the message.

Job user name. The user name of the job that sent the message.

Length of watch information. The length of the Event data parameter passed to the user-written exit program, including the 4-byte length of this field.

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

Length of receiving procedure name. The length of the procedure the message was sent to when the message was sent to a procedure within an ILE program. This field is set to zero if the message was sent to an original program model (OPM) program or when the message is sent to a nonprogram message queue.

Length of replacement data. The length of the message replacement data, in bytes.

Length of sending procedure name. The length of the procedure sending the message when the message was sent from a procedure within an ILE program. This field is set to zero if the message was sent from an original program model (OPM) program.

LIC job name. The name of the job which requested the LIC log entry. LIC job name is blank (hex 40s) if the LIC log entry was not requested by a job.

LIC job number. The job number (000001-999999) to further qualify the job name and user name of the job which requested the LIC log entry. LIC job number is blank (hex 40s) if the LIC log entry was not requested by a job.

LIC job user name. The user name of the job which requested the LIC log entry. LIC user name is blank (hex 40s) if the LIC log entry was not requested by a job.

LIC Log identifier. The LIC Log entry identifier of the LIC Log that occurred. The LIC log entry identifier is binary zeros if the entry was not added to the LIC log by the time this event was signaled.

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 LIC log entry.

LIC Log timestamp. The timestamp of when the entry was requested to be added to the LIC log. 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.

LIC module compile timestamp. The timestamp of when the LIC module was compiled. The format for this field is the system time-stamp format.

LIC module offset. The byte offset into the LIC module text which requested the LIC log entry.

LIC module RU name. The replaceable unit name of the module which requested the LIC log entry. LIC module RU name is always in upper case EBCDIC.

LIC module name. The name of the module which requested the LIC log entry. If the module name is greater than 64 characters, the LIC module name is truncated to 64 characters.

LIC module entry point name. The name of the entry point which requested the LIC log entry. If the entry point name is greater than 128 characters, the LIC module entry point name is truncated to 128 characters.

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

Message file library. The name of the library containing the message file.

Message file name. The name of the message file that was used to send the message.

Message ID. The identifier of the message that occurred.

Message key. The message reference key of the message that occurred. This field is set to blanks if *JOBLOG is specified for the message queue name.

Message queue library. The name of the library where the message queue is located. This field is set to blanks if *JOBLOG is specified for the message queue name.

Message queue name. The name of the message queue where the message was sent. If *JOBLOG is passed, it means that the message id was sent to a program message queue in the job specified in job name, job user name and job number fields

Message replacement data. The values for substitution variables in the message sent. Note that pointer values will not be valid when received by the exit program.

Message severity. The severity code, ranging from 00 through 99, of the message.

Message timestamp. The timestamp of when the message was sent. 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. Notice that when *JOBLOG is specified for the message queue name field, the time-stamp passed might not match exactly with the time sent shown in the corresponding job log.

Message type. The type assigned to the message when it was sent. The possible values are:

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

Offset to receiving procedure name. The offset to the field that holds the procedure the message was sent to when the message was sent to a procedure within an ILE program. This field is set to zero if the message was sent to an original program model (OPM) program or when the message is sent to a nonprogram message queue.

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

Offset to sending procedure name. The offset to the field that holds the procedure sending the message when the message was sent from a procedure within an ILE program. This field is set to zero if the message was sent from an original program model (OPM) program.

Offset where comparison data was found. The offset in the message replacement data, the sending program name or the receiving program name, where the message comparison data was found. This field is set to zero if zero was specified for the length of comparison data field.

Receiving module name. The name of the module the message was sent to when the message was sent to a procedure within an ILE program. If the message was sent to an original program model (OPM) program, this field is set to blanks. This field will be blank if the message is sent to a nonprogram message queue.

Receiving procedure name. The name of the procedure the message was sent to when the message was sent to a procedure within an ILE program. A nested procedure name has each procedure name separated by a colon. The outermost procedure name is identified first followed by the procedures it contains. The innermost procedure is identified last in the string.

Receiving program name. The name of the program the message was sent to, or the Integrated Language Environment (ILE) program name that contains the procedure the message was sent to. This field will be blank if the message is sent to a nonprogram message queue.

Replacement data CCSID. The coded character set identifier (CCSID) that the message data is in. This only applies to the part of the replacement data that corresponds to a convertible character data type (*CCHAR). All other replacement data will not be converted before it is returned and can be considered to have a CCSID of 65535. If there is no *CCHAR replacement data, 65535 is returned.

For more information about message handler and its use of CCSIDs, see CCSIDs: Message Support in the Globalization topic. For more information about the *CCHAR field type, see the Add Message Description (ADDMSGD) command.

Sending module name. The name of the module that contains the sending message when the sender is a procedure within an ILE program.

Sending procedure name. The name of the procedure sending the message when the sender is a procedure within an ILE program. A nested procedure name has each procedure name separated by a colon. The outermost procedure name is identified first followed by the procedures it contains. The innermost procedure is identified last in the string.

Sending program name. The program name or ILE program name that contains the procedure sending the message.

Server type. The type of server that requested the LIC log entry. Server type is blank (hex 40s) if the LIC log entry was not requested by a server.

Task name. The name of the task which requested the LIC log entry. Task name is blank (hex 40s) if the LIC log entry was not requested by a task.

TDE number. The number of the task dispatching element (TDE) which requested the LIC log entry.

Thread ID. The thread which requested the LIC log entry. Thread identifier is binary zeros if the LIC log entry was not requested by a thread.

Usage Notes

1. A message might be removed by a different job before the user exit program tries to use that message.
2. A message key for a nonprogram message queue could be reused for a new message before the exit program used the message.

Related Information

See the following for more information:

• Start Watch (STRWCH) command
• Start Watch (QSCSWCH) API