Retrieve PEX Information (QYPERPEX, qypeRetrievePexInfo) API
Required Parameter Group:
| 1 | Receiver variable | Output | Char(*) |
| 2 | Length of receiver variable | Input | Binary(4) |
| 3 | Format name | Input | Char(8) |
| 4 | PEX session name | Input | Char(10) |
| 5 | Error Code | I/O | Char(*) |
Service Program Name: QYPESVPG
Default Public Authority: *USE
Threadsafe: Yes
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
For detailed descriptions of the fields in this table, see Field Descriptions| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | BINARY(4) | Offset to first entry |
| 12 | C | BINARY(4) | Number of entries returned |
| 16 | 10 | BINARY(4) | Size of each entry |
| 20 | 14 | BINARY(4) | Number of entries available |
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.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | Session name |
| 10 | A | CHAR(2) | Reserved |
| 12 | C | BINARY(4) | Collection type |
| 16 | 10 | BINARY(4) | State |
| 20 | 14 | BINARY(4) | State qualifier |
| 24 | 18 | BINARY(4) | Event count |
| 28 | 1C | BINARY(4) | Filtered event count |
| 32 | 20 | CHAR(8) | Start complete time |
| 40 | 28 | CHAR(8) | Resume time |
| 48 | 30 | BINARY(4) | Storage used |
| 52 | 34 | CHAR(10) | Job name of the job that created the session |
| 62 | 3E | CHAR(10) | User name of the job that created the session |
| 72 | 48 | CHAR(6) | Job number of the job that created the session |
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.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | Session name |
| 10 | A | CHAR(2) | Reserved |
| 12 | C | BINARY(4) | Collection type |
| 16 | 10 | BINARY(4) | State |
| 20 | 14 | BINARY(4) | State qualifier |
| 24 | 18 | BINARY(4) | Event count |
| 28 | 1C | BINARY(4) | Filtered event count |
| 32 | 20 | CHAR(8) | Start complete time |
| 40 | 28 | CHAR(8) | Resume time |
| 48 | 30 | BINARY(4) | Storage used |
| 52 | 34 | CHAR(10) | Job name of the job that created the session |
| 62 | 3E | CHAR(10) | User name of the job that created the session |
| 72 | 48 | CHAR(6) | Job number of the job that created the session |
| 78 | 4E | CHAR(10) | Definition name |
| 88 | 58 | CHAR(10) | Filter name |
| 98 | 62 | CHAR(2) | Reserved |
| 100 | 64 | BINARY(4) | Sampling interval |
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:
| 1 | Trace. |
| 2 | Stats. |
| 3 | Stats hierarchical. |
| 6 | Profile. |
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:
| 0 | Created |
| 1 | Active |
| 2 | Suspended |
| 3 | Deleted |
| 4 | Stopped |
| 5 | Stopping (stop pending) |
| 6 | Starting |
State qualifier. Specifies additional details about the state of the session.
Possible values are:
| 0 | Normal(normal) |
| 2 | Wrapped (normal) |
| 4096 | Storage limit reached (limit) |
| 4098 | ASP storage limit reached (limit) |
| 4099 | User profile storage limit reached (limit) |
| 4100 | Byte stream file storage limit reached (limit) |
| 8193 | Internal error (error) |
| 8194 | Damage encountered (error) |
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
| Message | Error Message Text |
|---|---|
| CPFAF04 E | Session &1 is not active. |
| CPF3C1E E | Required parameter &1 omitted. |
| CPF3C3C E | Value for parameter &1 not valid. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3CF2 E | Error(s) occurred during running of &1 API. |
API introduced: V5R3
| Top | Performance Management APIs | APIs by category |