Watch for Event Exit Program

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, LIC log, 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). The user-written program will be called in the circumstances 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, type, severity 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.
*PAL	A match on a PAL and any associated comparison data specified on the watch for PAL entry parameter occurred.
*STRWCH	The watch program is being called before starting watching for any event.
*ENDWCH	The watch program is being called because the watch session is ending. Possible reasons might be: End Watch (ENDWCH) command or End Watch (QSCEWCH) API was issued. One or more of the watch for event jobs ended abnormally or ended by user action. Note: A watch session might end because an error was detected on the watch exit program. In this case, the watch program will not be called at *ENDWCH time.

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 messages, LIC log entries, or PAL 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, LIC log entries, or PAL 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 watch information
4	4	CHAR(7)	Message watched
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	BINARY(4)	Original replacement data length
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
452	1C4	CHAR(10)	Sending user profile
462	1CE	CHAR(10)	Target job name
472	1D8	CHAR(10)	Target job user name
482	1E2	CHAR(6)	Target job number
*	*	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 watch 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(1)	LIC log compare against specified
323	143	CHAR(1)	Reserved
324	144	BINARY(4)	Offset to comparison data
328	148	BINARY(4)	Length of comparison data
332	14C	CHAR(10)	LIC log compare against
*	*	CHAR(*)	LIC log comparison data

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

Offset		Type	Field
Dec	Hex
0	0	BINARY(4)	Length of watch information
4	4	CHAR(8)	System reference code
12	C	CHAR(10)	Device name
22	16	CHAR(4)	Device type
26	1A	CHAR(4)	Model
30	1E	CHAR(15)	Serial Number
45	2D	CHAR(10)	Resource Name
55	37	CHAR(8)	Log identifier
63	3F	CHAR(8)	PAL timestamp
71	47	CHAR(4)	Reference code
75	4B	CHAR(8)	Secondary code
83	53	CHAR(8)	Table identifier
91	5B	CHAR(1)	Reserved
92	5C	BINARY(4)	Sequence
96	60	BINARY(4)	Offset to comparison data
100	64	BINARY(4)	Length of comparison data
104	68	CHAR(10)	PAL compare against
*	*	CHAR(*)	PAL comparison data

The format of the Event data is as follows if the Watch option setting is *STRWCH or *ENDWCH:

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

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.

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.

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, LIC log, or PAL 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.Only up to 1024 bytes of replacement data will be returned.

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 compare against. The part of the LIC log the data specified in LIC log 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:

LIC log compare against specified. The character indicating if the LIC log compare against field was specified. The possible values are:

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.

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

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

Message file library. The name of the library containing the message file. This field is set to blanks for status messages and if *IMMED is specified for the message watched.

Message file name. The name of the message file that was used to send the message. This field is set to blanks for status messages and if *IMMED is specified for the message watched.

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 was sent to a program message queue in the job specified in target job name, target job user name and target 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. For an immediate message this field contains the text of the message.

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:

*CMD	Command
*COMP	Completion
*COPY	Sender's copy
*DIAG	Diagnostic
*ESCAPE	Escape
*INFO	Informational
*INQ	Inquiry
*NOTIFY	Notify
*RPY	Reply
*RQS	Request
*SCOPE	Scope
*STATUS	Status

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

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.

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.

Original replacement data length. The original replacement data length when the message was sent, in bytes. This length can exceed 1024 bytes, but only 1024 are returned.

PAL compare against. The field of the PAL the data specified in PAL 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:

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

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.

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.

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

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 CCSID support for messages in the Globalization topic. For more information about the *CCHAR field type, see the Add Message Description (ADDMSGD) command.

Reserved. A reserved field. This field is set to hexadecimal or binary zero.

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

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.

Sending user profile. The name of the user profile that the thread was running under when the message was sent. For jobs that swap user profiles, this user profile name and the job user name can be different.

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.

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.

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 identifier. The identifier of the table that identifies a group of reference codes.

Target job name. The name of the job the message was sent to. This field is set to blanks, unless *JOBLOG is specified for the message queue name field. The target job name and sending job name will be the same, unless a message was sent from one job to a different job.

Target job number. The job number (000001-999999) to further qualify the job name and user name of the job the message was sent to. This field is set to blanks, unless *JOBLOG is specified for the message queue name field. The target job name and sending job name will be the same, unless a message was sent from one job to a different job.

Target job user name. The user name of the job the message was sent to. This field is set to blanks, unless *JOBLOG is specified for the message queue name field. The target job name and sending job name will be the same, unless a message was sent from one job to a different job.

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.
3. A watch exit program should be prepared to handle the maximum message replacement data size. The maximum size supported by watches is 1024 bytes. This means that only up to 1024 bytes of replacement data will be passed to the user exit program. Also, the specified comparison data is compared against only the first 1024 bytes.
4. A watch exit program may not be called to handle the messages in the order the messages were sent because watch events are not handled by one job. They are handled by multiple jobs.

Related Information

See the following for more information:

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

[ Back to top | Problem Management APIs | APIs by category ]