Retrieve Subsystem Information (QWDRSBSD) API
Required Parameter Group:
| 1 | Receiver variable | Output | Char(*) |
| 2 | Length of receiver variable | Input | Binary(4) |
| 3 | Format name | Input | Char(8) |
| 4 | Qualified subsystem name | Input | Char(*) |
| 5 | Error code | I/O | Char(*) |
Optional Parameter:
| 6 | Number of qualified subsystem names | Input | Binary(4) |
Default Public Authority: *USE
Threadsafe: Yes
The Retrieve Subsystem Information (QWDRSBSD) API retrieves information about one or more specific subsystems or all active subsystems.
Authorities and Locks
- Subsystem Description Authority
- *USE
- Library Authority
- *EXECUTE
- Subsystem Description Lock
- *EXCLRD
The subsystem description authority and library authority are not required when *ACTIVE is specified for the qualified subsystem name parameter.
Required Parameter Group
- Receiver variable
- OUTPUT; CHAR(*)
The variable to receive the subsystem information. This area must be large enough to accommodate the information specified.
- Length of receiver variable
- INPUT; BINARY(4)
The length of the receiver variable. The length must be at least 8 bytes. If the variable is not long enough to hold the subsystem information, the data is truncated.
- Format name
- INPUT; CHAR(8)
The format of the subsystem information. You can use this format:
SBSI0100 Basic subsystem information. For details, see SBSI0100 Format. SBSI0200 Multiple subsystems information. All entries are the same size. For details, see SBSI0200 Format. SBSI0300 Multiple subsystems information. Different entries may be different sizes. For details, see SBSI0300 Format. The SBSI0200 format or the SBSI0300 format must be specified if *ACTIVE is specified in the first 10 characters of the qualified subsystem name or if the number of qualified subsystem names parameter is greater than 1.
- Qualified subsystem name
- INPUT; ARRAY(*) of CHAR(20)
An array of CHAR(20) values giving the names of the subsystems about which to retrieve information and the library in which the subsystem description is located. The number of qualified subsystem names parameter specifies how many elements are in this array.
The first 10 characters contain the subsystem name. You can use the following special value for the subsystem name:
*ACTIVE Return information about all active subsystems. If *ACTIVE is specified for the first 10 characters: - SBSI0200 or SBSI0300 must be specified for the format name parameter.
- the value in the second 10 characters must be blank.
The second 10 characters contain the library name. You can use one of these special values for the library name:
*CURLIB The job's current library *LIBL The library list If *ACTIVE is specified in the first 10 characters, the value in the second 10 characters must be blank.
If information for a subsystem description is requested more than once in the array, the receiver variable will not contain duplicate information for that subsystem description.
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
Optional Parameter
- Number of qualified subsystem names
- INPUT; BINARY(4)
The number of names specified in the qualified subsystem name parameter. If this parameter is not specified, the number of names specified defaults to 1. If this parameter is specified, the number specified must be in the range 1 to 65535. If a number greater than 1 is specified, SBSI0200 or SBSI0300 must be specified for the format name parameter.
SBSI0100 Format
The following table shows the information returned in the receiving variable for the SBSI0100 format. For a detailed description of each field, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | CHAR(10) | Subsystem description name |
| 18 | 12 | CHAR(10) | Subsystem description library name |
| 28 | 1C | CHAR(10) | Subsystem status |
| 38 | 26 | CHAR(10) | Sign-on device file name |
| 48 | 30 | CHAR(10) | Sign-on device file library name |
| 58 | 3A | CHAR(10) | Secondary language library name |
| 68 | 44 | BINARY(4) | Maximum active jobs |
| 72 | 48 | BINARY(4) | Currently active jobs |
| 76 | 4C | BINARY(4) | Number of storage pools defined |
| Offsets vary. These five fields repeat, in the order listed, for each pool defined for the subsystem. | BINARY(4) | Pool ID | |
| CHAR(10) | Pool name | ||
 CHAR(1) |
Pool size units |
||
| CHAR(5) | Reserved | ||
| BINARY(4) | Pool size | ||
| BINARY(4) | Pool activity level | ||
SBSI0200 Format
The following table shows the information returned in the receiving variable for the SBSI0200 format. For a detailed description of each field, 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 subsystem entry |
| 12 | C | BINARY(4) | Number of subsystem entries returned |
| 16 | 10 | BINARY(4) | Size of a subsystem entry |
| 20 | 14 | CHAR(*) | Reserved |
| Offsets vary. These fields repeat, in the order listed, for each subsystem. | CHAR(10) | Subsystem description name | |
| CHAR(10) | Subsystem description library name | ||
| CHAR(12) | Subsystem extended status | ||
| BINARY(4) | Maximum active jobs | ||
| BINARY(4) | Currently active jobs | ||
| CHAR(10) | Subsystem monitor job name | ||
| CHAR(10) | Subsystem monitor job user | ||
| CHAR(6) | Subsystem monitor job number | ||
| CHAR(50) | Subsystem description text | ||
| CHAR(*) | Reserved | ||
SBSI0300 Format
The following table shows the information returned in the receiving variable for the SBSI0300 format. For a detailed description of each field, 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 subsystem entry |
| 12 | C | BINARY(4) | Number of subsystem entries returned |
| 16 | 10 | CHAR(*) | Reserved |
| Offsets vary. These fields repeat, in the order listed, for each subsystem. | BINARY(4) | Displacement to next subsystem entry | |
| CHAR(10) | Subsystem description name | ||
| CHAR(10) | Subsystem description library name | ||
| CHAR(12) | Subsystem extended status | ||
| BINARY(4) | Maximum active jobs | ||
| BINARY(4) | Currently active jobs | ||
| CHAR(10) | Subsystem monitor job name | ||
| CHAR(10) | Subsystem monitor job user | ||
| CHAR(6) | Subsystem monitor job number | ||
| CHAR(10) | Sign-on device file name | ||
| CHAR(10) | Sign-on device file library name | ||
| CHAR(10) | Secondary language library name | ||
| BINARY(4) | Displacement to ASP group information | ||
| BINARY(4) | Number of ASP group information entries | ||
| BINARY(4) | Length of one ASP group information entry | ||
| CHAR(50) | Subsystem description text | ||
| CHAR(1) | Controlling subsystem flag | ||
| CHAR(*) | Reserved | ||
| Array(*) of CHAR(*) | ASP group information entry | ||
Format of ASP Group Information Entry
The auxiliary storage pool (ASP) group information entry describes the data that is returned for each ASP group in the subsystem description.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| The fields repeat for each entry returned in the ASP group information. | CHAR(10) | ASP group name | |
| CHAR(*) | Reserved | ||
Field Descriptions
ASP group name. The name of the ASP group. This is the name of the primary ASP device in an ASP group or the name of an ASP device description. This specifies the ASP group setting for the subsystem monitor job.
Bytes available. The total length of all data available.
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.
Controlling subsystem flag. Whether this subsystem is the controlling subsystem. The following values are returned:
| 0 | This subsystem is not the controlling subsystem. |
| 1 | This subsystem is the controlling subsystem. |
Currently active jobs. The number of jobs currently active in the subsystem. This number includes held jobs but excludes jobs that are disconnected or suspended because of a transfer secondary job or a transfer group job. If the subsystem status is *INACTIVE, this number is 0.
Displacement to ASP group information. The number of bytes from the first byte of the current subsystem entry to the first ASP group information entry. Zero indicates that this subsystem description does not have an ASP group.
Displacement to next subsystem entry. The number of bytes from the first byte of the current subsystem entry to the information for the next subsystem.
Length of one ASP group information entry. The length of one ASP group information entry. Zero indicates that this subsystem description does not have an ASP group.
Maximum active jobs. The maximum number of jobs that can run or use resources in the subsystem at one time. If the subsystem description specifies *NOMAX, indicating that there is no maximum, this number is -1.
Number of ASP group information entries. The number of entries in the subsystem description's ASP group information. Zero indicates that this subsystem description does not have an ASP group.
Number of subsystem entries returned. The number of subsystems for which entries are returned. This number determines how many times the entire set of fields describing a subsystem is repeated.
Number of storage pools defined. The number of storage pools defined for the subsystem. The maximum number of storage pools for a subsystem is currently 10. This number determines how many times the pool ID, pool name, pool size, pool activity level, and reserved fields are repeated. Those five fields are repeated as a group for each pool defined for the subsystem.
Offset to first subsystem entry. The number of bytes from the first byte of the receiver variable to the information for the first subsystem.
Pool activity level. The maximum number of jobs that can be active in the pool at one time. If the pool name indicates a system-defined pool, the number returned is 0.
Pool ID. The pool ID for the subsystem pool.
Pool name. The name of the subsystem pool. If the pool is user-defined, the value of this field is *USERPOOL. If the pool is system-defined, the value is one of these names:
| *BASE | The system base pool, which can be shared with other subsystems. The QBASPOOL system value defines the base pool's minimum size. The base pool contains all main storage not allocated to other pools. The QBASACTLVL system value defines its activity level. |
| *INTERACT | The shared pool used for interactive work. |
| *NOSTG | No storage size or activity level is assigned to this storage pool. |
| *SHRPOOL1-*SHRPOOL60 | Shared pools. |
| *SPOOL | The shared pool for spooling writers. |
The Change Shared Storage Pool (CHGSHRPOOL) command specifies the size and activity level of shared pools.
Pool size. If the pool name is *USERPOOL, the amount of storage, in kilobytes or megabytes (see Pool size units), that the pool attempts to allocate. If the pool has any other name, the value of this field is 0.
Pool size units.
The units of the returned pool size field.
| K | Pool size is returned in kilobytes for this pool. |
| M | Pool size is returned in megabytes for this pool. |
| blank | No pool size is returned for this pool. |
Reserved. An ignored field.
Secondary language library name. The name of the subsystem's secondary language library.
Sign-on device file library name. The name of the library in which the sign-on device file resides.
Sign-on device file name. The name of the sign-on device file.
Size of a subsystem entry. The number of bytes in the entry for a subsystem.
Subsystem description library name. The name of the library in which the subsystem description resides.
Subsystem description name. The name of the subsystem about which information is being returned.
Subsystem description text. The text description of the subsystem description. The field is blank if there is no text description.
Subsystem extended status. Possible values that can be returned for subsystem extended status are:
| *ACTIVE | The subsystem is running. |
| *ENDING | An ENDSBS command has been issued for the subsystem or an ENDSYS command has been issued, but the subsystem is still running. |
| *INACTIVE | The subsystem is not running. |
| *RESTRICTED | An ENDSBS command for the controlling subsystem, an ENDSYS *ALL command, or an ENDSYS command has placed the controlling subsystem in a restricted condition. |
| *STARTING | A STRSBS command has been issued for the subsystem, but it is still in the process of being started. |
Subsystem monitor job name. The name for the subsystem monitor job as identified to the system. The field is blank if the subsystem extended status field is *INACTIVE.
Subsystem monitor job number. The system-assigned number for the subsystem monitor job. The field is blank if the subsystem extended status field is *INACTIVE.
Subsystem monitor job user. The name of the user profile under which the subsystem monitor job is running. The field is blank if the subsystem extended status field is *INACTIVE.
Subsystem status. Possible values that can be returned for subsystem status are:
| *ACTIVE | The subsystem is running. |
| *INACTIVE | The subsystem is not running. |
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF1605 E | Cannot allocate subsystem description &1. |
| CPF1606 E | Error during allocation of subsystem &1. |
| CPF1607 E | Previous request pending for subsystem &1. |
| CPF1608 E | Subsystem description &1 not found. |
| CPF1619 E | Subsystem description &1 in library &2 damaged. |
| CPF1835 E | Not authorized to subsystem description. |
| CPF187A E | List of active subsystems not available. |
| CPF1877 E | Incorrect format specified. |
| CPF1878 E | Library name not valid for subsystem &1. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3CF2 E | Error(s) occurred during running of &1 API. |
| 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. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF8122 E | &8 damage on library &4. |
| CPF9807 E | One or more libraries in library list deleted. |
| CPF9810 E | Library &1 not found. |
| CPF9820 E | Not authorized to use library &1. |
| CPF9830 E | Cannot assign library &1. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
API introduced: V2R1