Retrieve Watch Information (QSCRWCHI) API
Required Parameter Group:
| 1 | Receiver variable | Output | Char(*) |
| 2 | Length of receiver variable | Input | Binary(4) |
| 3 | Receiver format name | Input | Char(8) |
| 4 | Session ID | Input | Char(10) |
| 5 | Error Code | I/O | Char(*) |
Default Public Authority: *EXCLUDE
Threadsafe: No
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.
The QSYS2.WATCH_INFO view and QSYS2.WATCH_DETAIL table function can be used as an alternative to this API. See WATCH_INFO view and WATCH_DETAIL table function for more information.
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.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | CHAR(10) | Origin |
| 18 | 12 | CHAR(10) | User ID |
| 28 | 1C | CHAR(10) | Status |
| 38 | 26 | CHAR(10) | Started by job name |
| 48 | 30 | CHAR(10) | Started by job user |
| 58 | 3A | CHAR(6) | Started by job number |
| 64 | 40 | CHAR(4) | Reserved |
| 68 | 44 | BINARY(4) | Started by job CCSID |
| 72 | 48 | CHAR(10) | Watch session type |
| 82 | 52 | CHAR(10) | Watch program name |
| 92 | 5C | CHAR(10) | Watch program library |
| 102 | 66 | CHAR(2) | Reserved |
| 104 | 68 | BINARY(4) | Run priority |
| 108 | 6C | BINARY(4) | Length of time to watch |
| 112 | 70 | BINARY(4) | Time Interval |
| 116 | 74 | CHAR(8) | Date and time the watch was started |
| 124 | 7C | BINARY(4) | Offset to call watch program options |
| 128 | 80 | BINARY(4) | Number of call watch program options |
| 132 | 84 | BINARY(4) | Offset to message information |
| 136 | 88 | BINARY(4) | Number of messages |
| 140 | 8C | BINARY(4) | Offset to LIC log information |
| 144 | 90 | BINARY(4) | Number of LIC logs |
| 148 | 94 | BINARY(4) | Offset to PAL information |
| 152 | 98 | BINARY(4) | Number of PALs |
| 156 | 9C | CHAR(*) | Reserved |
| * | * | Array of CHAR(10) | Call watch program options |
| * | * | Array of Message information | Message information |
| * | * | Array of LIC log information | LIC log information |
| * | * | Array of PAL information | PAL information |
Message information
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Length of message information |
| 4 | 4 | CHAR(7) | Message watched |
| 11 | B | CHAR(1) | Reserved |
| 12 | C | CHAR(10) | Watched message queue name |
| 22 | 16 | CHAR(10) | Watched message queue library |
| 32 | 20 | CHAR(10) | Watched job name |
| 42 | 2A | CHAR(10) | Watched job user name |
| 52 | 34 | CHAR(6) | Watched job number |
| 58 | 3A | CHAR(6) | Reserved |
| 64 | 40 | BINARY(4) | Offset to message comparison data |
| 68 | 44 | BINARY(4) | Length of message comparison data |
| 72 | 48 | CHAR(10) | Compare against |
| 82 | 52 | CHAR(10) | Message type |
| 92 | 5C | CHAR(3) | Relational operator |
| 92 | 5F | CHAR(1) | Reserved |
| 96 | 60 | BINARY(4) | Message severity code |
| * | * | CHAR(*) | Message comparison data |
| * | * | CHAR(*) | Reserved |
LIC log information
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Length of LIC log information |
| 4 | 4 | CHAR(4) | LIC log major code |
| 8 | 8 | CHAR(4) | LIC log minor code |
| 12 | C | BINARY(4) | Offset to LIC log comparison data |
| 16 | 10 | BINARY(4) | Length of LIC log comparison data |
| 20 | 14 | CHAR(10) | LIC log compare against |
| * | * | CHAR(*) | LIC log comparison data |
| * | * | CHAR(*) | Reserved |
PAL information
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Length of PAL information |
| 4 | 4 | CHAR(8) | System reference code |
| 12 | C | BINARY(4) | Offset to PAL comparison data |
| 16 | 10 | BINARY(4) | Length of PAL comparison data |
| 20 | 14 | CHAR(10) | PAL compare against |
| * | * | CHAR(*) | PAL comparison data |
| * | * | CHAR(*) | Reserved |
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:
| *STRWCH | The watch program will also be called before starting watching for any event. |
| *ENDWCH | The watch program will also be called when the watch session is ending.
Possible reasons might be:
Note: A watch session might end because an error was detected on the watch exit program. In this case, the watch program will not be called at *ENDWCH time. |
Compare against. The part of the message the data specified in message comparison data field is to be compared against. Possible values are:
| *MSGDTA | The message comparison data will be compared against the message replacement data. |
| *FROMPGM | The message 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 message 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. |
| *NONE | No message comparison data was specified. |
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:
| 0 | There is no time limit for watching for a particular message or LIC log entry or PAL entry. |
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:
| *ALL | The LIC log comparison data will be compared against all the fields described below. |
| *TDENBR | The LIC log comparison data will be compared against the number of the task dispatching element (TDE) which requested the LIC log entry. |
| *TASKNAME | The LIC log comparison data will be compared against the name of the task which requested the LIC log entry. Task name is blank (hex 40s) if the LIC log entry is not requested by a task. |
| *SVRTYPE | The LIC log comparison data will be compared against the type of server that requested the LIC log entry. Server type is blank (hex 40s) if the LIC log entry is not requested by a server. |
| *JOBNAME | The LIC log comparison data will be compared against the name of the job which requested the LIC log entry. LIC job name is blank (hex 40s) if the LIC log entry is not requested by a job. |
| *JOBUSR | The LIC log comparison data will be compared against the user name of the job which requested the LIC log entry. LIC user name is blank (hex 40s) if the LIC log entry is not requested by a job. |
| *JOBNBR | The LIC log comparison data will be compared against the job number (000001-999999) to further qualify the job name and user name of the job which requested the LIC log entry. LIC job number is blank (hex 40s) if the LIC log entry is not requested by a job. |
| *THDID | The LIC log comparison data will be compared against the thread which requested the LIC log entry. Thread identifier is binary zeros if the LIC log entry is not requested by a thread. |
| *EXCPID | The LIC log comparison data will be compared against the exception that caused the LIC log entry to be requested. This is a 2-byte hexadecimal field formed by concatenating to the high-order 1-byte exception group number a low-order 1-byte exception subtype number. Exception identifier is binary zeros if the LIC log entry is not requested as a result of an exception. |
| *MODNAME | The LIC log comparison data will be compared against the LIC module name which requested the LIC log entry. If the module name is greater than 64 characters, the LIC module name is truncated to 64 characters. |
| *MODRUNAME | The LIC log comparison data will be compared against the LIC module replacement unit name. LIC module RU name is always in upper case EBCDIC. |
| *MODEPNAME | The LIC log comparison data will be compared against the name of the entry point which requested the LIC log entry. If the entry point name is greater than 128 characters, the LIC module entry point name is truncated to 128 characters. |
| *MODOFFSET | The LIC log comparison data will be compared against the byte offset into the LIC module text which requested the LIC log entry. |
| *MODTSP | The LIC log comparison data will be compared against the timestamp of when the LIC module was compiled. The format for this field is the system time-stamp format. |
| *NONE | No LIC log comparison data was specified. |
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:
| *ALL | Any LIC log entry major code will be considered to be a match. |
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:
| *ALL | Any LIC log entry minor code will be considered to be a match. |
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:
| *ALL | All the message types are to be watched. This includes completion, command, diagnostic, escape, informational, inquiry, notify, reply, request, sender's copy, scope and status message types. |
| *COMP | A completion message is to be watched. |
| *DIAG | A diagnostic message is to be watched. |
| *ESCAPE | An escape message is to be watched. |
| *INFO | An informational message is to be watched. |
| *INQ | An inquiry message is to be watched. |
| *NOTIFY | A notify message is to be watched. |
| *SCOPE | A scope message is to be watched. |
| *STATUS | A status message is to be watched. |
Message watched. The message to be watched. Possible values are:
| message id | The 7-character message identifier of the message to be watched. |
| generic-name | The generic name of the message 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 message name specifies all messages with identifiers that begin with the generic prefix. |
| *IMMED | All immediate or impromptu messages will be watched. |
| *ALL | All messages are to be watched. This includes stored messages and immediate messages. |
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:
| QSCSWCH | Session started by Start Watch (QSCSWCH) API. |
| STRWCH | Session started by Start Watch (STRWCH) command. |
| STRTRC | Session started by Start Trace (STRTRC) command. |
| STRCMNTRC | Session started by Start Communications Trace (STRCMNTRC) command. |
| TRCINT | Session started by Trace Internal (TRCINT) command. |
| TRCCNN | Session started by Trace Connection (TRCCNN) command. |
| TRCTCPAPP | Session started by Trace TCP/IP Application (TRCTCPAPP) command. |
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:
| *RSCNAME | The PAL comparison data will be compared against the resource name. |
| *RSCTYPE | The message comparison data will be compared against the resource type. |
| *RSCMODEL | The PAL comparison data will be compared against the resource model. |
| *NONE | No PAL comparison data was specified. |
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:
| *EQ | Equal. |
| *GT | Greater than. |
| *LT | Less than. |
| *GE | Greater than or equal. |
| *LE | Less than or equal. |
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:
| ACTIVE | Session in ACTIVE status. |
| ENDING | Session in ENDING status. |
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:
| *ALL | Any PAL system reference code will be considered to be a match. |
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:
| generic-name | 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. |
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:
| *ALL | All jobs with the specified job name and user name are watched. |
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:
| generic-name | 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. |
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:
| *JOBLOG | Watch messages added to the job logs of the jobs specified for the watched job field. |
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:
| *NONE | Watch program not specified or not found. |
Watch session type. Identifies the type of watch according to its origin. Possible special values are:
| *SRVMON | Watch session started using the Service Monitor function of the operating system. |
| *STRWCH | Watch session started using the Start Watch (STRWCH) command or Start Watch (QSCSWCH) API. |
| *TRCCMD | Watch session started using Start Communications Trace (STRCMNTRC), Start Trace (STRTRC), Trace Internal (TRCINT), Trace Connection (TRCCNN) and Trace TCP/IP Application (TRTCPAPP) commands. |
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF1E99 E | Unexpected error occurred. |
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3C19 E | Error occurred with receiver variable specified. |
| CPF3C20 E | Error found by program &1. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3C24 E | Length of the receiver variable is not valid. |
| CPF39E1 E | Watch session &1 not found. |
| CPF39E6 E | The user does not have the required authority. |
| CPF98A2 E | Not authorized to &1 command or API. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
API introduced: IBM® i 7.1
[ Back to top | Problem Management APIs | APIs by category ]