The Start Watch (STRWCH) command starts the watch for event function, which notifies the user by calling a user specified program when the specified event (a message, a LIC log entry or PAL entry) occurs. PAL stands for Product Activity Log which shows errors that have occurred (such as in disk and tape units, communications, and work stations).
Up to 10000 watch sessions can be active at a time but active watch session identifiers must be unique across the system.
The watch session continues until ended with the End Watch (ENDWCH) command or with the End Watch (QSCEWCH) API. A watch session can be ended from the same job or a different job.
Restrictions:
To use this command, you must have service (*SERVICE) special authority, or be authorized to the Service watch function of IBM i through System i Navigator's Application Administration support. The Change Function Usage (CHGFCNUSG) command, with a function ID of QIBM_SERVICE_WATCH, can also be used to change the list of users that are allowed to start and end watch operations.
When the Watched job (WCHJOB) parameter is specified, the issuer of the command must be running under a user profile which is the same as the job user identity of the job being watched, or the issuer of the command must be running under a user profile which has job control (*JOBCTL) special authority. Job control (*JOBCTL) special authority is also required if a generic user name is specified for the WCHJOB parameter.
If you specify *ALL for the watched job name, or a generic user name, you must have all object (*ALLOBJ) special authority, or be authorized to the Watch any job function of IBM i through System i Navigator's Application Administration support. The Change Function Usage (CHGFCNUSG) command, with a function ID of QIBM_WATCH_ANY_JOB, can also be used to change the list of users that are allowed to start and end watch operations.
You must have operational (*OBJOPR) and execute (*EXECUTE) authorities to the watch program to be called, and execute (*EXECUTE) authority to the library where the program is located.
You must have use (*USE) authority to the message queues specified in Watched message queue (WCHMSGQ) parameter, and use (*USE) authority to the library where the message queue is located.
Specifies the user exit program to be called to notify that a specified watch event occurred. The exit program will be called once for each message, LIC log entry and PAL entry specified on this command. That is, if a message is watched on a message queue and in a job log, and the message is sent to both locations, the exit program will be called twice.
This is a required parameter.
The watch program will be called:
After a match of a message, type, severity and any associated comparison data specified for the WCHMSG parameter, or a match of a Licensed Internal Code (LIC) log entry and any associated comparison data specified for the WCHLICLOG parameter, or a match of a Product Activity Log (PAL) entry and any associated comparison data specified for the WCHPAL parameter occurs.
Whenever it was defined in the Call watch program (CALLWCHPGM) parameter.
There are three input parameters and one output parameter associated with the watch program. The four parameters are required:
Allowed values for the "Watch option setting" parameter are:
*MSGID
A match on a message id or immediate/impromptu message, message type, message severity and any associated comparison data specified on WCHMSG parameter occurred.
*LICLOG
A match on a LIC log andany associated comparison data specified on the WCHLICLOG parameter occurred.
*PAL
A match on a Product Activity Log (PAL) and any associated comparison data specified on the WCHPAL parameter occurred.
*STRWCH
The watch program will be called before starting watching for any event.
*ENDWCH
The watch program will be called when 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.
The "Session ID" parameter contains the name of the watch session that is calling the user exit program.
Allowed values for the "Error detected" parameter 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 or LIC log entries or PAL entries, all of them will no longer be watched. CPI3999 message will be sent to the job log and the history log to indicate an error in the exit program caused the watch session to be ended.
<blanks>
No error detected by watch exit program.
Notes:
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 messages or LIC log entries or PAL entries, all of them will no longer be watched. CPI3999 message will be sent to the job log and the history log to indicate an error in the exit program caused the watch session to be ended.
Allowed values for the "Event data" parameter when *MSGID is specified for the "Watch option setting" parameter will be the following structure:
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) 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
Allowed values for the "Event data" parameter when *LICLOG is specified for the "Watch option setting" parameter will be the following structure:
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 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
Allowed values for the "Event data" parameter when *PAL is specified for the "Watch option setting" parameter will be the following structure:
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
Allowed values for the "Event data" parameter when *STRWCH or *ENDWCH is specified for the "Watch option setting" parameter will be the following structure:
OFFSET TYPE FIELD
Dec Hex
0 0 BINARY(4) Length of watch information
(always 4 at this time)
For more information on the watch exit program interface, refer to the APIs topic collection in the Programming category in the IBM i Information Center at http://www.ibm.com/systems/i/infocenter/
Qualifier 1: Watch program
name
Specify the name of the watch exit program.
Qualifier 2: Library
*LIBL
All libraries in the job's library list are searched until the first match is found.
*CURLIB
The current library for the job is used to locate the program. If no library is specified as the current library for the job, the QGPL library is used.
name
Specify the name of the library where the user exit program is located.
Specifies the times at which the program specified for the Watch program (WCHPGM) parameter will be called. The program will always be called when the watched for event occurs. You can specify additional times for the program to be called.
Single values
*WCHEVT
The watch program will be called when the watched for event occurs and also be called before starting.
Other values (up to 2 repetitions)
*STRWCH
The watch program will be called when the watched for event occurs and also be called before starting watching for any event.
*ENDWCH
The watch program will be called when the watched for event occurs and also be called when 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.
Specifies up to five messages which are to be watched. If a value other than *NONE is specified, you must specify where to watch for the message on the Watched message queue (WCHMSGQ) parameter. When the watched for message is added to the specified message queue or log, the watch exit program is called.
Note: Moved and resent messages will not be watched. Only the original instance of the message can be watched.
Single values
*NONE
No messages will be watched.
Element 1: Message to watch
*ALL
All messages are to be watched. This includes stored messages and immediate messages. Be aware that watching for all messages might cause performance degradation on your system. Use it cautiously.
*IMMED
All immediate or impromptu messages will be watched. No messages stored in a message file are watched.
generic-name
Specify the generic message identifier to be watched. A generic name is a character string of one or more characters followed by an asterisk (*); for example, ABC*. The asterisk substitutes for any valid characters. A generic message name specifies all messages with message identifiers that begin with the generic prefix.
name
Specify the 7-character message identifier to be watched.
Element 2: Comparison data
Specify comparison data to be used if a message matching the specified message is added to the specified message queue or log. If the message data, the "From program" or the "To program" includes the specified text, the watched for condition is true. If the message data, the "From program" or the "To program" does not contain the specified text, the watch function just continues.
*NONE
No comparison data is specified. If a message matching the specified message is added to the specified message queue or log, the watched for condition is true.
character-value
Specify the text string used to compare against the message data, the "From program" or the "To program" of the watched for message. This text is case sensitive and can be quoted in order to specify imbedded or trailing blanks.
Element 3: Compare against
Specify which part of the message the comparison data specified for element 2 is to be compared against.
*MSGDATA
The comparison data will be compared against the message replacement data.
*FROMPGM
The comparison data will be compared against the name of the program sending the message, or the name of the ILE program that contains the procedure sending the message.
*TOPGM
The comparison data will be compared against the name of the program the message was sent to, or the name of the ILE program that contains the procedure the message was sent to.
Element 4: Message type
Specify the message type assigned to the message to be watched.
*ALL
All the message types are to be watched. This includes completion, command, diagnostic, escape, informational, inquiry, notify, reply, request, sender's copy, scope and status message types.
*COMP
A completion message is to be watched.
*DIAG
A diagnostic message is to be watched.
*ESCAPE
An escape message is to be watched.
*INFO
An informational message is to be watched.
*INQ
An inquiry message is to be watched.
*NOTIFY
A notify message is to be watched.
*SCOPE
A scope message is to be watched.
*STATUS
A status message is to be watched.
Element 5: Relational operator
Specify one relational operator against which the message severity code is compared.
*GE
Greater than or equal.
*EQ
Equal.
*GT
Greater than.
*LT
Less than.
*LE
Less than or equal.
Element 6: Severity code
Specifies the severity code of the message to be watched.
00
The severity code assigned to the message to be watched for is 00.
Severity-code
Specify a value, ranging from 00 through 99, as the severity level associated with the message to be watched.
Specifies where to watch for the messages specified on the WCHMSG parameter. You can specify to watch the message being added to the system operator message queue, the history log, other message queues, and job logs. Up to three message queues or special values can be specified.
Element 1: Message queue
Single values
*SYSOPR
Watch messages added to the system operator message queue (QSYSOPR message queue in library QSYS).
*JOBLOG
Watch messages added to the job logs of the jobs specified for the Watched job (WCHJOB) parameter.
*HSTLOG
Watch messages added to the history log (QHST message queue in library QSYS).
Qualifier 1: Message queue
name
Specify the name of the message queue to watch.
Qualifier 2: Library
*LIBL
All libraries in the library list for the current thread are searched until the first match is found.
name
Specify the name of the library where the message queue is located.
Specifies the job whose job log is watched for the messages specified on the Watch for message (WCHMSG) parameter. The specified job will only be watched if *JOBLOG is specified on the Watched message queue (WCHMSGQ) parameter. Up to five job names may be specified.
Single values
*
Only the job log of the job that issued this watch command is watched.
Element 1: Job name
Qualifier 1: Job name
generic-name
Specify the generic name of the job to be watched. A generic name is a character string of one or more characters followed by an asterisk (*); for example, ABC*. The asterisk substitutes for any valid characters. A generic job name specifies all jobs with job names that begin with the generic prefix.
*ALL
All jobs with the specified job user name are watched. *ALL for the job name is considered to be a generic job specification because it will watch all jobs that meet the job user name qualifier that you specified.
name
Specify the name of the job to be watched.
Qualifier 2: User
generic-name
Specify the generic name of the user name of the job to be watched. A generic name is a character string of one or more characters followed by an asterisk (*); for example, ABC*. The asterisk substitutes for any valid characters. A generic user name specifies all jobs with the specified job name and with user names that begin with the generic prefix.
*ALL
All jobs with the specified job name are watched. *ALL for the job user name is considered to be a generic job specification because it will watch all jobs that meet the job name qualifier that you specified.
name
Specify the user name of the job to be watched.
Qualifier 3: Number
*ALL
All jobs with the specified job name and user name are watched. *ALL for the job number is considered to be a generic job specification because it will watch all jobs that meet the job name and job user name qualifiers that you specified.
000001-999999
Specify the job number to further qualify the job name and user name. You cannot specify a job number if a generic job name or a generic user name qualifier is specified.
Specifies up to five licensed internal code (LIC) log entry identifiers which are to be watched for. Each LIC log entry contains a major and a minor code. The watched for condition will be met if a LIC log entry is added that matches the specified major and minor codes and any comparison data specified.
Single values
*NONE
No LIC log entries will be watched for.
Element 1: Major code
*ALL
Any LIC log entry major code will be considered to be a match. If *ALL is specified for the major code, you cannot specify *ALL for the LIC log entry minor code.
character-value
Specify the LIC log major code to be watched for. You can specify either a hexadecimal digit or a question mark for each character in the four-digit code. A question mark is a wildcard character that will match any digit in that position. Up to three wildcard characters can be specified.
Element 2: Minor code
*ALL
Any LIC log entry minor code will be considered to be a match. If *ALL is specified for the minor code, you cannot specify *ALL for the LIC log entry major code.
character-value
Specify the LIC log minor code to be watched for. You can specify either a hexadecimal digit or a question mark for each character in the four-digit code. A question mark is a wildcard character that will match any digit in that position. Up to three wildcard characters can be specified.
Element 3: Comparison data
Specify comparison data to be used if a log entry matching the specified major and minor codes is added to the licensed internal code (LIC) log. If this text is found in the LIC log entry data fields of the watched for log entry, the watched for condition is true.
*NONE
No comparison data is specified. If a LIC log entry matching the specified major and minor codes is added to the LIC log, the watched for condition is true.
character-value
Specify the text string used to compare against the entry data of the watched for log entry. If this text is found in the LIC log entry data field specified for element 4, the watch condition is considered to be true. This text is case sensitive. If *ALL is specified in the LIC log compare against field, the LIC log fields which will be compared are TDE number, task name, server type, job name, user ID, job number, thread ID, exception ID, LIC module compile timestamp, LIC module offset, LIC module RU name, LIC module name, LIC module entry point name. The comparison data cannot be used to match across two fields, and can match an entire field or a substring of any field.
When watching for an exception ID, all four hexadecimal digits of the exception ID must be specified. Also, the prefix MCH may be specified if you want to compare only against the exception ID field and avoid possible substring matches with the other fields.
Element 4: Compare against
Specify which part of the LIC log the comparison data specified for element 3 is to be compared against.
*ALL
The LIC log comparison data will be compared against all the fields described below.
*TDENBR
The LIC log comparison data will be compared against the number of the task dispatching element (TDE) which requested the LIC log entry.
*TASKNAME
The LIC log comparison data will be compared against the name of the task which requested the LIC log entry. Task name is blank (hex 40s) if the LIC log entry is not requested by a task.
*SVRTYPE
The LIC log comparison data will be compared against the type of server that requested the LIC log entry. Server type is blank (hex 40s) if the LIC log entry is not requested by a server.
*JOBNAME
The LIC log comparison data will be compared against the name of the job which requested the LIC log entry. LIC job name is blank (hex 40s) if the LIC log entry is not requested by a job.
*JOBUSR
The LIC log comparison data will be compared against the user name of the job which requested the LIC log entry. LIC user name is blank (hex 40s) if the LIC log entry is not requested by a job.
*JOBNBR
The LIC log comparison data will be compared against 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 is not requested by a job.
*THDID
The LIC log comparison data will be compared against the thread which requested the LIC log entry. Thread identifier is binary zeros if the LIC log entry is not requested by a thread.
*EXCPID
The LIC log comparison data will be compared against 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 is not requested as a result of an exception.
*MODNAME
The LIC log comparison data will be compared against the LIC module name which requested the LIC log entry. If the module name is greater than 64 characters, the LIC module name is truncated to 64 characters.
*MODRUNAME
The LIC log comparison data will be compared against the LIC module replacement unit name. LIC module RU name is always in upper case EBCDIC.
*MODEPNAME
The LIC log comparison data will be compared against 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.
*MODOFFSET
The LIC log comparison data will be compared against the byte offset into the LIC module text which requested the LIC log entry.
*MODTSP
The LIC log comparison data will be compared against the timestamp of when the LIC module was compiled. The format for this field is the system time-stamp format.
Specifies up to five Product Activity Log (PAL) entries which are to be watched for. When the watched for PAL occurs, the watch exit program is called.
Single values
*NONE
No PAL entries will be watched for.
Other values (up to 5 repetitions)
Element 1: System reference code
*ALL
Any system reference code will be considered to be a match.
character-value
Specify the system reference code (SRC) to be watched for. You can specify either a hexadecimal digit or a question mark for each character in the eight-digit code. A question mark is a wildcard character that will match any digit in that position. Up to seven wildcard characters can be specified. You can also specify a generic SRC that is a character string of one or more characters followed by an asterisk (*); for example, ABC*. The asterisk substitutes for any valid characters. A generic SRC specifies all PAL entries with system reference codes that begin with the generic prefix.
Element 2: Comparison data
Specify comparison data to be used if a PAL entry matching the specified system reference code occurs. If the field specified in element 3 matches the specified text, the watched for condition is true. If the field specified in element 3 does not match the specified text, the watch function just continues.
*NONE
No comparison data is specified. If a PAL entry matching the specified system reference code occurs, the watched for condition is true.
character-value
Specify the text string used to compare against the field specified in element 3 of the watched for PAL entry. This text is case sensitive.
You can specify question mark (?) and asterisk (*) wildcard characters in the text string. A question mark is a single-character wildcard and will match any character in the same position. For example, '??123' will match any value that is five characters long and ends with '123'. Multiple question mark wildcard characters can be specified for the comparison data value.
An asterisk is a multiple-character wildcard character. You can specify a single asterisk wildcard character at the end of the comparison data value. For example, 'ABC*' will match any value that begins with the letters 'ABC'.
Element 3: Compare against
Specify which part of the PAL entry the comparison data specified for element 2 is to be compared against.
*RSCNAME
The comparison data will be compared against the name of the physical device that has the 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.
*RSCTYPE
The comparison data will be compared against the number or word used to identify a product.
*RSCMODEL
The comparison data will be compared against the numbers or letters used to identify the feature level of a product with a given type.
Specifies the priority of the job where the watch session work will be run.
25
A job priority of 25 will be used.
1-99
Specify the run priority of the job. For more information on job run priority, refer to the Work management topic collection in the IBM i Information Center at http://www.ibm.com/systems/i/infocenter/
This command starts the watch session named "OWN_JOB" to start watching for any message starting with CPF00 to occur on the job that called the STRWCH command and whose severity code is greater than or equal to 50. When a CPF00* message is sent to the current job log, MYPGM program in MYLIB library will be called to be notified of the event. .* Update Example 1 p9C33203
Example 2: Start a Watch for a Message Specifying a Run Priority
This command starts a watch session to call MYLIB/EXTPGM user exit program when CPF1804 message is found on the System Operator message queue or within the *ALL/MYUSER/MYJOBNAME job log. A unique watch session identifier will be generated. The session identifier will be returned in the message data of CPC3901 completion message sent after the watch session starts successfully. The job where the user exit program will be called will run with a run priority of 10.
Example 3: Start a Watch for an Immediate Message Specifying Comparison Data
This command starts a watch session to call MYLIB/EXTPGM user exit program when an immediate (or impromptu) message is sent to message queue QHST in library QSYS by QSCSWCH program.
Example 4: Start a Watch for Several Messages Types in my Job Logs
This command starts a watch session to call MYLIB/EXTPGM user exit program when any diagnostic, status or escape message with a severity code greater than 50 is sent to a job log running under MYUSER user profile.
This command starts LICLOGSSN to watch for a Licensed Internal Code (LIC) log entry that has a major code starting with 99 and a minor code of 9932 generated on the system. Also, the LIC log information should contain the text "MYJOBNAME". The first match of EXTPGM program found in the library list will be called notifying that the event occurred.
Example 6: Start a Watch for a PAL Entry and Call Exit Program at Start and End Times
This command starts PALSSN to watch for a Product Activity Log (PAL) entry that has a system reference code starting with B600512 generated on the system. Also, the PAL resource name contains the text "MYRSC". The program USRLIB/USRPGM will be called notifying that the event occurred, but it will also be called before starting watching for any event and when the watch session is ending.