Retrieve Watch Information (QSCRWCHI) API

The Retrieve Watch Information (QSCRWCHI) API returns the details about a specific watch session.

The information returned by QSCRWCHI API is similar to the information produced by Option 5 - Display on the Work with Watches (WRKWCH) panel.

Authorities and Locks

Authority to use the API

To use this API, you must have service (*SERVICE) special authority or must be authorized to the Service watch and Service trace functions of the IBM i through System i™ Navigator's Application Administration support. The Change Function Usage (CHGFCNUSG) command, with a function ID of QIBM_SERVICE_WATCH and QIBM_SERVICE_TRACE, can also be used to change the list of users that are allowed to perform watch operations.

Required Parameter Group

Receiver variable

OUTPUT; CHAR(*)

The variable that is to receive the information about the watch session.

Length of receiver variable

INPUT; BINARY(4)

The size of the receiver variable. If the length is larger than the size of the receiver variable, the results may not be predictable. The minimum length is 8 bytes.

Receiver format name

INPUT; CHAR(8)

The format of the watch information to be returned.You must use one of the following format names:

WCHI0100

Session details and watched events.

For more information, see Format of the Generated Information.

Session ID

INPUT; CHAR(10)

The identifier of the watch session for which information will be retrieved.

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error code parameter. If this parameter is omitted, diagnostic and escape messages are issued to the application.

Format of the Generated Information

For detailed descriptions of the fields in the list returned, see Field Descriptions.

WCHI0100 Format

The following information is returned in the receiver variable for the WCHI0100 format.

Message information

LIC log information

PAL information

Field Descriptions

Bytes available. The length of all data available to return. All available data is returned if enough space is provided.

Bytes returned. The length of the data actually returned. The number of bytes returned is always less than or equal to both the number of bytes available and the receiving variable length.

Call watch program options. The times at which the watch program will be called. The program will always be called when the watched for event occurs. Additional times for the program to be called could be:

Compare against. The part of the message the data specified in message comparison data field is to be compared against. Possible values are:

Date and time the watch was started. The timestamp of when the watch was started. The format for this field is the system time-stamp format.

Length of LIC log comparison data. The length of the text specified in LIC log comparison data field, ranging from 0 through 72.

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

Length of message comparison data. The length of the text specified in message comparison data field ranging from 0 through 72.

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

Length of PAL comparison data. The length of the text specified in PAL comparison data field ranging from 0 through 10.

Length of PAL information. The length of the structure containing the information of the PAL to watch.

Length of time to watch. The time limit, in minutes, for watching for a message, a LIC log entry or a PAL entry. Only available on watch sessions started by trace commands. This field will be set to zero for sessions not started by trace commands. When the specified amount of time has elapsed, the watch exit program is called (if one was specified on Watch Exit Program parameter), the watch is ended, and message CPI3999 is sent to the history log. Possible special values are:

LIC log compare against. The part of the LIC log the data specified in LIC log comparison data field is to be compared against. Possible values are:

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 field specified by the LIC log compare against field, the watched for condition is 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 binary timestamp, 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. The prefix MCH may be specified o 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. A hexadecimal digit or a question mark can be specified 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. Possible special values are:

LIC log minor code. The LIC log minor code to be watched. A hexadecimal digit or a question mark can be specified 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. Possible special values are:

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

Message severity code. The severity code, ranging from 0 through 99, of the message to be watched.

Message type. The message type assigned to the message to be watched. Possible special values are:

Message watched. The message to be watched. Possible values are:

Number of call watch program options. The number of values specified in the call watch program options field array. If zero is specified the watch program will be called only when the specified event occurs.

Number of LIC logs. The number of LIC logs being watched.

Number of messages. The number of messages being watched.

Number of PALs. The number of PALs being watched.

Offset to call watch program options. The offset to the array that defines when the watch program is to be called. If this value is 0 then the watch program will be called only when the specified event occurs.

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

Offset to LIC log information. The offset to the first structure that holds the LIC log information. If this value is set to 0 then there are no LIC logs being watched.

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

Offset to message information. The offset to the first structure that holds the message information. If this value is set to 0 then there are no messages being watched.

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

Offset to PAL information. The offset to the first structure that holds the PAL information. If this value is set to 0 then there are no PALs being watched.

Origin. The name of the command or the API that started the watch. Valid values are:

PAL compare against.The part of the PAL the data specified in PAL comparison data field is to be compared against. Possible special values are:

PAL comparison data. The comparison data to be used if a PAL entry matching the specified system reference code was created. If the data specified by PAL compare against field matches the specified text, the watched for condition is true. This text is case sensitive. Question marks (?) and asterisk (*) wildcard characters can be specified in the text string. A question mark is a single-character wildcard character 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. A single asterisk wildcard character can be specified at the end of the comparison data value. For example, 'ABC*' will match any value that begins with the letters 'ABC'.

Relational operator. The relational operator against which the message severity code is compared. Possible special values are:

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

Run priority. The priority for the job where the watch session work will be run. See the Work management topic collection for more information about the run priority.

Started by job CCSID. The Code Character Set identifier of the job that started the watch session.

Started by job name. The name of the job that started the watch session.

Started by job number. The number of the job that started the watch session.

Started by job user. The user of the job that started the watch session.

Status. The status of the watch session. Valid values are:

System reference code. The system reference code to be watched. A hexadecimal digit or a question mark can be specified 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. A generic name that is a character string of one or more characters followed by an asterisk (*) can also be specified; for example, ABC*. The asterisk substitutes for any valid characters. A generic name specifies all PALs with system reference codes that begin with the generic prefix.

Possible special values are:

Time interval. The interval of time, in seconds, of how often the trace exit program is called. Only available on watch sessions started by trace commands. This field will be set to zero for sessions not started by trace commands.

User ID. The user identifier of user that started the watch session.

Watched job name. The name of the job to be watched. This field will be set to blanks if something different from *JOBLOG is specified for watched message queue name field. Possible special values are:

Watched job number. The job number (000001-999999) to further qualify the job name and user name. This field will be set to 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. Possible special values are:

Watched job user name. The user name of the job to be watched. This field will be set to blanks if something different from *JOBLOG is specified for watched message queue name field. Possible special values are:

Watched message queue library. The name of the library where the message queue is located.

Watched message queue name. The name of the message queue to watch. Possible special values are:

Watch program library. The name of the library where the user exit program is located. This field is set to blanks when *NONE is specified for the watch program name.

Watch program name. The name of the program called to notify that a specified watch event occurred. Possible values are:

Watch session type. Identifies the type of watch according to its origin. Possible special values are:

Error Messages

[ Back to top | Problem Management APIs | APIs by category ]