Watch for Event Exit Program
Required Parameter Group:
| 1 | Watch option setting | Input | Char(10) |
| 2 | Session ID | Input | Char(10) |
| 3 | Error detected | Output | Char(10) |
| 4 | Event data | Input | Char(*) |
QSYSINC/H member name: ESCWCHT
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.
- 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 length62 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) Error 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:
| *MSGDTA | The message comparison data was compared against the message replacement data. |
| *FROMPGM | The message comparison data was compared against the sending program name. |
| *TOPGM | The message comparison data was compared against the receiving program name. |
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.
Error Log identifier. The unique identifier of the machine error log entry that ties together all data related to a single error condition. The error log identifier can be specified on the ERRLOGID keyword of the Print Error Log (PRTERRLOG) CL command to generate a spooled printer file or an outfile of the machine error log entry.
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:
| *ALL | The LIC log comparison data was compared against all the fields described below. |
| *TDENBR | The LIC log comparison data was compared against the TDE number. |
| *TASKNAME | The LIC log comparison data was compared against the task name. |
| *SVRTYPE | The LIC log comparison data was compared against the server type. |
| *JOBNAME | The LIC log comparison data was compared against the LIC job name. |
| *JOBUSR | The LIC log comparison data was compared against the LIC job user name. |
| *JOBNBR | The LIC log comparison data was compared against the LIC job number. |
| *THDID | The LIC log comparison data was compared against the thread ID. |
| *EXCPID | The LIC log comparison data was compared against the exception ID. |
| *MODNAME | The LIC log comparison data was compared against the LIC module name. |
| *MODRUNAME | The LIC log comparison data was compared against the LIC module replacement unit name. |
| *MODEPNAME | The LIC log comparison data was compared against the LIC module entry point name. |
| *MODOFFSET | The LIC log comparison data was compared against the LIC module offset. |
| *MODTSP | The LIC log comparison data was compared against the LIC module compile timestamp. |
LIC log compare against specified. The character indicating if the LIC log compare against field was specified. The possible values are:
| 0 | The LIC log compare against field was not specified. |
| 1 | The LIC log compare against field was specified. |
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. The LIC log identifier can be specified on the DMPID keyword of the Print Internal Data (PRTINTDTA) CL command to write the machine internal data to a spooled printer file.
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.
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:
| 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.
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:
| *RSCNAME | The PAL comparison data will be compared against the resource name. |
| *RSCTYPE | The PAL comparison data will be compared against the resource type. |
| *RSCMODEL | The PAL comparison data will be compared against the resource model. |
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
- A message might be removed by a different job before the user exit program tries to use that message.
- A message key for a nonprogram message queue could be reused for a new message before the exit program used the message.
- 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.
- 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.
- When the watched event occurs, the watch exit program is called in a prestart job (job QSCWCHPS) in subsystem QUSRWRK. The exit program is not called in the job where the watched event occurred. After an exit program is called, in job QSCWCHPS, the job ends and another QSCWCHPS job will be created to handle subsequent watch processing.
Related Information
See the following for more information:
- Start Watch (STRWCH) command
- Start Watch (QSCSWCH) API
Exit program introduced: V5R4
[ Back to top | Problem Management APIs | APIs by category ]