Retrieve Watch List (QSCRWCHL) 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 | Watch selection information | Input | Char(*) |
| 5 | Watch selection information format | Input | Char(8) |
| 6 | Error Code | I/O | Char(*) |
Default Public Authority: *EXCLUDE
Threadsafe: No
The Retrieve Watch List (QSCRWCHL) API generates a list of all or some watch sessions on the system.
The QSCRWCHL API produces a list similar to the list produced by the Work with Watches (WRKWCH) command.
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 list of watch sessions.
- 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 list to be returned.You can use these special values for this parameter:
WCHL0100 Basic watch list. For more information, see Format of the Generated List.
- Watch selection information
- INPUT; CHAR(*)
The information that identifies the watch information to be returned. The format of this information depends on the specified Watch selection format.
- Watch selection information format
- INPUT; CHAR(8)
Indicates which watch sessions will be retrieved. The possible values are:
WCHF0100 The list of watch sessions will be retrieved according to what is specified in WCHF0100 Watch Selection Information.
- 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 List
For detailed descriptions of the fields in the list returned, see Field Descriptions.
WCHL0100 Format
The following information is returned in the receiver variable for the WCHL0100 format.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | BINARY(4) | Offset to watch sessions list |
| 12 | C | BINARY(4) | Number of watch sessions |
| 16 | 10 | BINARY(4) | Size of watch session entry |
| 20 | 14 | CHAR(*) | Reserved |
| These fields repeat, in the order listed, for each session. | CHAR(10) | Session ID | |
| CHAR(10) | Origin | ||
| CHAR(10) | User ID | ||
| CHAR(10) | Status | ||
Watch selection information format
For detailed descriptions of the fields in the list returned, see Field Descriptions.
WCHF0100 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | Session ID |
| 10 | 14 | CHAR(10) | Watch session type |
| 20 | 1E | CHAR(10) | Origin |
| 30 | 28 | CHAR(10) | User ID |
| 40 | 32 | CHAR(10) | Status |
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.
Number of watch sessions. The number of watch sessions returned on the API call.
Offset to watch sessions list. The offset from the beginning of the structure to the start of the watch sessions list.
Origin. The name of the command or the API that started the watch. Valid values are:
| *ALL | All watch sessions will be retrieved (input only). |
| 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 |
Reserved. A reserved field. This field is set to hexadecimal or binary zero.
Session ID. The session identifier for the watch. Valid values are:
| *ALL | All watch sessions will be retrieved (input only). |
| generic-name | The generic name of the session to retrieve. 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 session name specifies all sessions with identifiers that begin with the generic prefix. (input only) |
| name | The session identifier |
Size of watch session entry. The size in bytes of a watch session entry (session id, origin, user id, and status). The watch session list consists of one or more watch session entries.
Status. The status of the watch session. Valid values are:
| *ALL | Watch sessions in any status will be retrieved (input only). |
| ACTIVE | Session in ACTIVE status |
| ENDING | Session in ENDING status |
User ID. The user identifier of user that started the watch session. Valid values are:
| *ALL | Watch sessions started by any user will be retrieved (input only). |
| * | Watch sessions started by the user calling the API are retrieved. (input only) |
| name | The name of the user that started the watch session |
Watch session type. Identifies the type of watch according to its origin. Valid values are:
| *ALL | Watch sessions of any type will be retrieved (input only). |
| *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. |
| CPF3C1D E | Length specified in parameter &1 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. |
| CPF3C3A E | Value for parameter &2 for API &1 not valid. |
| 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 ]