Start Watch (STRWCH)

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 or LIC log) occurs. 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 Operating System through iSeries 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 Operating System through iSeries 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 operatinal (*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.

Keyword	Description	Choices	Notes
SSNID	Session ID	Name, *GEN	Required, Positional 1
WCHPGM	Watch program	Qualified object name	Required, Positional 2
Qualifier 1: Watch program	Name
Qualifier 2: Library	Name, LIBL, CURLIB
WCHMSG	Watch for message	Single values: NONE Other values (up to 5 repetitions): Element list*	Optional
Element 1: Message identifier	Name
Element 2: Comparison data	Character value, *NONE
Element 3: Compare against	MSGDTA, FROMPGM, *TOPGM
WCHMSGQ	Watched message queue	Values (up to 3 repetitions): Element list	Optional
Element 1: Message queue	Single values: SYSOPR, JOBLOG, HSTLOG Other values: Qualified object name*
Qualifier 1: Message queue	Name
Qualifier 2: Library	Name, *LIBL
WCHJOB	Watched job	Single values: * Other values (up to 5 repetitions): Element list	Optional
Element 1: Job name	Qualified job name
Qualifier 1: Job name	Generic name, name, *ALL
Qualifier 2: User	Generic name, name, *ALL
Qualifier 3: Number	000001-999999, *ALL
WCHLICLOG	Watch for LIC log entry	Single values: NONE Other values (up to 5 repetitions): Element list*	Optional
Element 1: Major code	Character value, *ALL
Element 2: Minor code	Character value, *ALL
Element 3: Comparison data	Character value, *NONE

Watch program (WCHPGM)

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 id and LIC log 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 identifier 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 occurs.

There are three input parameters and one output parameter associated with the watch program. The four parameters are required:

1   Watch option setting   Input    Char(10)
2   Session Id             Input    Char(10)
3   Error detected         Output   Char(10)
4   Event data             Input    Char(*)

Allowed values for the "Watch option setting" parameter are:

*MSGID: A match on a message id and any associated comparison data specified on WCHMSG parameter occurred.
*LICLOG: A match on a LIC log and any associated comparison data specified on the WCHLICLOG parameter occurred.

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 message ids or LIC log entries, all of them will no longer be watched. CPI3999 message will be sent to the job log and message queue QSYSOPR to indicate an error in the exit program caused the watch session to be ended.
<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. CPI3999 message will be sent to the job log and message queue QSYSOPR 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 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)     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

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(2)      Reserved
324  144   BINARY(4)    Offset to comparison data
328  148   BINARY(4)    Length of comparison data
 *    *    CHAR(*)      LIC log comparison data

For more information on the watch exit program interface, refer to the System API Reference information in the iSeries Information Center at http://www.iseries.ibm.com/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.

Watch for message (WCHMSG)

Specifies up to five message identifiers which are to be watched for. 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.

Single values

*NONE: No messages will be watched for.

Element 1: Message identifier

name: Specify the 7-character message identifier to be watched for.

Element 2: Comparison data

Specify comparison data to be used if a message matching the specified message ID 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 ID 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.

Watched job (WCHJOB)

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.

Watch for LIC log entry (WCHLICLOG)

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 fields compared of a watched for log entry, the watch condition is considered to be true. This text is case sensitive. The LIC log fields which can 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.

Examples

Example 1: Start a Watch on Your Job

STRWCH   SSNID(OWN_JOB) WCHPGM(MYLIB/MYPGM)
         WCHMSG((CPF0001)) WCHMSGQ((*JOBLOG))

This command starts the watch session named "OWN_JOB" to start watching for CPF0001 message to occur on the job that called the STRWCH command. When CPF0001 message is sent to the current job log, MYPGM program in MYLIB library will be called to be notified of the event.

Example 2: Start a Watch for a Message

STRWCH   SSNID(*GEN) WCHPGM(MYLIB/EXTPGM)
         WCHMSG((CPF1804))
         WCHMSGQ((*SYSOPR) (*JOBLOG))
         WCHJOB((*ALL/MYUSER/MYJOBNAME))

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.

Example 3: Start a Watch for a Message Specifying Comparison Data

STRWCH   SSNID(FRMPGM) WCHPGM(MYLIB/EXTPGM)
         WCHMSG((CPC3922 QSCSWCH *FROMPGM))
         WCHMSGQ((*HSTLOG))

This command starts a watch session to call MYLIB/EXTPGM user exit program when CPC3922 message is sent to message queue QHST in library QSYS by QSCSWCH program.

Example 4: Start a Watch for a LIC Log Entry

STRWCH   SSNID(LICLOGSSN) WCHPGM(*LIBL/EXTPGM)
         WCHLICLOG(('99??' 9932 MYJOBNAME))

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.