Start Watch (QSCSWCH) API

The Start Watch (QSCSWCH) API 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. The watch session continues until ended with the End Watch (QSCEWCH) API or with the End Watch (ENDWCH) command.

Note: A watch session can be ended from the same job or a different job.

Authorities and Locks

Authority to use the API

To use this API, you must have service (*SERVICE) special authority, or be authorized to the Service watch function of Opearting 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.

Authority to watch program

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.

Authority to message queue

You must have use (*USE) authority to the message queue specified in watched message queue name field, and use (*USE) authority to the library where the message queue is located.

Authority to watched job

When a message is being watched within a job, the issuer of the API 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 API 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 in the watched job user name field.

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.

Required Parameter Group

Session ID

INPUT; CHAR(10)

The session identifier for this watch. This watch session identifier must be unique across all active watche sessions on the system. You cannot specify a session identifier that starts with "QSC". You can use this special value for this parameter:

*GEN	The system will generate a unique session identifier for this watch that will be returned as output in Started session ID parameter.

Started session ID

OUTPUT; CHAR(10)

The identifier of the watch session just started.

Watch program

INPUT; CHAR(20)

The program to be called to notify that a specified watch event occurred. The watch program will be called after a match of a message identifier and any associated comparison data specified for the watch for message parameter, or a match of a Licensed Internal Code (LIC) log entry and any associated comparison data specified for the watch for LIC log entry parameter occurs.

The exit program will be called once for each message id and LIC log entry specified on this API. 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.

For more information about the watch exit program interface, refer to the System API Reference information in the iSeries Information Center at http://www.iseries.ibm.com/infocenter .

The information must be in the following format:

Watch program name

CHAR(10)
The name of the user-written program to call.

Watch program library

CHAR(10)
The library where the user-written program is located. You can use one of these special values for this field:

*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.

Watch for message

INPUT; CHAR(*)

The message identifiers which are to be watched for and where to watch for them. The information must be in the following format:

Number of messages being watched

BINARY(4)
The total number of all of the messages to watch for within this session. Up to 100 messages might be watched at the same time by a single session.

Message information

Each message being watched contains a message id, where to watch for the message (message queue or job log) and it may specify a message comparison data. Refer to Format for message information for the format of this field.

Watch for LIC log entry

INPUT; CHAR(*)

The licensed internal code (LIC) log entry identifiers which are to be watched for. 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. The information must be in the following format:

Number of LIC logs being watched

BINARY(4)
The total number of all of the LIC logs to watch for. Up to five LIC logs can be specified.

LIC log information

Each LIC log entry contains a major and a minor code and it may specify a LIC log comparison data. Refer to Format for LIC log information for the format of this field.

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error Code Parameter.

Format for message information

The following table shows the format for the messages to be watched for. For a detailed description of each field, see Field Descriptions.

Format for LIC log information

The following table shows the format for the LIC logs to be watched for. For a detailed description of each field, see Field Descriptions.

Field Descriptions

Compare against. The part of the message the data specified in message comparison data field is to be compared against. You must specify blanks if zero was specified for the length of message comparison data field. You can specify the following special values for this field:

Length of LIC log comparison data. The length of the text specified in LIC log comparison data field. Valid values are 0 through 72.

Length of LIC log information. The length of the structure containing the information of the LIC log to watch for.

Length of message comparison data. The length of the text specified in message comparison data field. Valid values are 0 through 72.

Length of message information. The length of the structure containing the information of the message to watch for.

LIC log comparison data. The 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. 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 binary 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.

LIC log major code. 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. You can specify the following special value for this field:

LIC log minor code. 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. You can specify the following special value for this field:

Message comparison data. The 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. This text is case sensitive.

Message id. The 7-character message identifier to be watched for.

Offset to LIC log comparison data. The offset to the field that holds the LIC log comparison data.

Offset to message comparison data. The offset to the field that holds the message comparison data.

Reserved. A reserved field. This field must be set to hexadecimal or binary zero.

Watched job name. The name of the job to be watched. You must specify blanks if something different from *JOBLOG is specified for watched message queue name field. You can specify the following special values for this field:

Watched job number. The job number (000001-999999) to further qualify the job name and user name. You must specify blanks if a generic job name or a generic user name qualifier is specified, or if something different from *JOBLOG is specified for watched message queue name field. You can specify the following special value for this field:

Watched job user name. The user name of the job to be watched. You must specify blanks if '*' is specified for the watched job name field or something different from *JOBLOG is specified for watched message queue name field. You can specify the following special value for this field:

Watched message queue library. The name of the library where the message queue is located. This field is ignored if *SYSOPR, *JOBLOG or *HSTLOG was specified in the message queue name. You can specify the following special value for this field:

Watched message queue name. The name of the message queue to watch. You can specify the following special values for this field:

Error Messages

The following messages may be sent from this function: