Retrieve PEX Information (QYPERPEX, qypeRetrievePexInfo) API

The Retrieve PEX Information (QypeRetrievePexInformation) API retrieves information about a PEX session. It can be used to retrieve the following:

• Session name
• Collection type
• State
• State qualifier
• Event count
• Filtered event count
• Start complete time
• Resume time
• Storage used
• Qualified job name of the job that created the session
• Definition name
• Filter name
• Sampling interval

Authorities and Locks

None

Required Parameter Group

Receiver variable

OUTPUT; CHAR(*)

The variable that is to receive the information requested. The minimum size for this area is 8 bytes. You can specify the size of this area to be smaller than the format requested if you specify the length of receiver variable parameter correctly. As a result, the API returns only the data that the area can hold.

Length of receiver variable

INPUT; BINARY(4)

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

Format name

INPUT; CHAR(8)

The content and format of the information returned for the PEX session.

The possible format names are:

PEXI0100	Basic information about the PEX session.
PEXI0200	Detailed information about the PEX session.

PEX session name

INPUT; CHAR(10)

The name of a PEX session. Special values supported:

*ALL	All PEX sessions.

Error code

I/O; CHAR(*)

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

Header section

PEXI0100 Format

The following information is returned for one entry with the PEXI0100 format. For detailed descriptions of the fields in the table, see Field Descriptions.

PEXI0200 Format

The following information is returned for one entry with the PEXI0200 format. For detailed descriptions of the fields in the table, see Field Descriptions.

Field Descriptions

Bytes available. Number of bytes available to be returned by the API. If this value is larger than the bytes returned it means that the API had more information to return than the receiver variable could hold.

Bytes returned. Number of bytes returned by the API and placed in the receiver variable. If this value is smaller than the bytes available, it means that the API had more information to return than the receiver variable could hold.

Collection type. Indicates type of data being collected in the PEX session.

Possible values are:

Definition name. Name of definition used by the session.

Event count. Number of events in the session.

Filter name. Name of filter used by the session. This field will contain a value if a valid filter name was specified with the FTR keyword of the STRPEX command. If no filter name was specified in STRPEX, this field will be all blanks.

Filtered event count. Number of filtered events in the session. A filtered event is one that is not collected. It is filtered out based on specifications supplied in the Add Pex Filter (ADDPEXFTR) command.

Job name of the job that created the session. The name of the job that did the STRPEX command to start the session.

Job number of the job that created the session. The system-assigned number of the job that did the STRPEX command to start the session.

Number of entries available. Number of fixed-length entries that were available to be returned to the caller of the API, given sufficient space in the receiver variable. If this value is larger than the number of entries returned, it means that the API had more information to return than the receiver variable could hold.

Number of entries returned. The number of fixed-length entries following the header section. If this value is smaller than the number of entries available, it means that the API had more information to return than the receiver variable could hold.

Offset to first entry. The offset, in bytes, from the start of the header section to the beginning of the actual data returned by the API.

Reserved. An ignored field.

Resume time. Time (in 8 byte time of day format) that the session was resumed, if STRPEX OPTION(*RESUME) was used. If STRPEX (*RESUME) was not used, this field will be set to x'00' (nulls).

Sampling interval. Size of sampling interval in milliseconds. This field will contain a value if a sampling interval was specified with the INTERVAL keyword of the ADDPEXDFN command for the PEX definition used by this session.

Session name. The name of the PEX session.

Size of each entry. The size in bytes of each fixed-length entry following the header section.

Start complete time. Time (in 8 byte time of day format) that the session completed its start activity.

State. Specifies the internal state of the session.

Possible values are:

State qualifier. Specifies additional details about the state of the session.

Possible values are:

Storage used. Number of bytes of storage used by the session.

User name of the job that created the session. The user name of the job that did the STRPEX command to start the session.

Error messages