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	Type	Field
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	Type	Field
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 ]