Commands and APIs about watch for event function

You can use CL commands and APIs to work with watches.

The following commands are used to work with the watch event function.

Start Watch command

The Start Watch (STRWCH) command starts a watch session and notifies you when a specified message, a Licensed Internal Code log entry, or a Product Activity Log entry occurs. When the watched-for message is added to the specified message queue or log, or when the watched-for log entry is added, the exit program specified in the Watch program (WCHPGM) parameter is called. The watch session can be ended by the End Watch (ENDWCH) command or by the End Watch (QSCEWCH) API.

When you watch for messages, specify the message queue or job log where you expect the message to be sent. You can narrow the search by specifying a text string to be compared against the message data, against the From program, or against the To program of the watched-for message.

When you watch for Licensed Internal Code log entries, specify the Licensed Internal Code log major and minor codes. You can narrow the search by specifying a text string that is to be compared against:
  • The number of the task dispatching element (TDE)
  • The name of the task
  • The type of server
  • The name of the job
  • The user name of the job
  • The job number to further qualify the job name and user name of the job
  • The thread identifier
  • The exception identifier
  • The LIC module name
  • The LIC module replacement unit name
  • The name of the entry point
  • The byte offset into the LIC module text
  • The timestamp of when the LIC module is compiled
When you watch for Product Activity Log entries, specify the particular system reference code (SRC) to be watched for. You can narrow the search by specifying a text string that is to be compared against:
  • The name of the physical device that has the entry in the log
  • The number or word that is used to identify a product
  • The numbers or letters that are used to identify the feature level of a product with a given type

You can specify the priority of the job where the watch session is run. By default, a job priority of 25 is used.

Work with Watches command

You can start a new watch or end an active watch with the Work with Watches (WRKWCH) command. With this command, you can also show a list of active watches on the system.

End Watch command

The End Watch (ENDWCH) command ends a watch session that is started by the Start Watch (STRWCH) command or by the Start Watch (QSCSWCH) API. Watch sessions that are started by trace commands (such as STRTRC, TRCINT, TRCCNN, STRCMNTRC, TRCTCPAPP) are ended, but the associated trace remains active.

Start Watch and End Watch APIs

The Start Watch (QSCSWCH) and End Watch (QSCEWCH) APIs are used in a similar way to the STRWCH and ENDWCH commands. The End Watch (QSCEWCH) API ends a watch session that was started by the STRWCH (Start Watch) command or by the Start Watch (QSCSWCH) API.

Note: Watch sessions started by trace commands (such as STRTRC, TRCINT, TRCCNN, STRCMNTRC, TRCTCPAPP) are ended but the associated trace remains active. A watch session can be ended by the same job that issues the start function or by a different job.

Using the watch for event function with trace commands

Watch support enhances the trace functions by automatically monitoring and ending traces when certain predetermined criteria are met. This prevents the loss of valuable trace data and reduces the amount of time that you spend in monitoring traces.