CL Command Reference - STRWCH
CL Command List > STRWCH Reference
Description:
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.
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.