| 1 | Receiver variable | Output | Char(*) |
| 2 | Length of receiver variable | Input | Binary(4) |
| 3 | Format | Input | Char(8) |
| 4 | Authorization list name | Input | Char(10) |
| 5 | Error code | I/O | Char(*) |
The Retrieve Authorization List Information (QSYRTVAI) API returns to the caller information about the number of authorization list entries that are in use for the specified authorization list. The returned information can be use to determine how full an authorization list is.
The normal view of an authorization list (AUTL) is that it is a single object (structure) with the capacity to secure 16,777,215 objects. However, to successfully manage the fullness of an AUTL, a more comprehensive view of an AUTL is required.
When an object is secured by an AUTL, each piece of the object may have to be individually secured by the AUTL. This means that when an object is secured by an AUTL, multiple entries in the AUTL may be used by the system to secure all of the parts of the object. For example, when a database file with multiple members is secured by an AUTL, multiple entries in the AUTL will be used. Because of this, using commands like DSPAUTLOBJ (Display Authorization List Objects) and APIs like QSYLATLO (List Authorization List Objects), is not an effective way to determine whether an AUTL is becoming full.
In addition, the first time an AUTL is used to secure an object that resides in an independent auxiliary storage pool (ASP), the system creates an internal structure in the independent ASP that is transparently tied to the AUTL object. This internal structure is called an authorization list extension. The authorization list extension has entries just like the AUTL but these entries can only be used to secure objects that reside in the independent ASP. An authorization list extension also has a maximum of 16,777,215 entries. These entries are in addition to the 16,777,215 entries in the base AUTL which are used to secure objects in the system and basic user auxiliary storage pools (*SYSBAS). The system can have a maximum of 223 independent ASPs; therefore, the theoretical combined limit for an AUTL and its extensions is 3,758,096,160 entries (224 multiplied by 16,777,215).
If an attempt is made to secure an object that resides in an independent ASP with an AUTL but all of the entries in the authorization list extension for the object's independent ASP have been used; an MCH2804 exception will occur indicating that the storage limit for the AUTL has been reached. This would happen even if there were unused entries available for objects that reside in *SYSBAS. Likewise, if an attempt is made to secure an object that resides in *SYSBAS with an AUTL but all of the AUTL's *SYSBAS entries have been used; an MCH2804 exception will occur even if there are unused entries available in authorization list extensions for the AUTL.
To effectively manage the fullness of an AUTL, a user needs to ensure that no single set of entries (the *SYSBAS set and the authorization list extension sets) exceed their individual 16,777,215 entry limit.
This API returns information about the total number of entries used for *SYSBAS and all varied on independent ASPs for the specified AUTL as well as detailed entry use information for *SYSBAS and each varied on independent ASP.
The variable used to return the information about the AUTL. An approximation of the size needed for this receiver variable can be obtained by calling the QSYRTVAI API with the length of receiver variable set to 8 bytes. The bytes available value that is returned in this receiver variable will indicate the approximate size needed for the receiver variable. The receiver variable format is defined in RTAI0100 Format.
The length of the receiver variable. This value must be at least 8.
The name of the format that is used to return the AUTL's information.
The following value is allowed:
| RTAI0100 | Authorization list information is returned. |
The name of the authorization list for which information is to be returned. The name must be specified in uppercase.
The structure in which to return error information. For the format of the structure, see Error code parameter.
The following tables describe the receiver variable that is returned by the QSYRTVAI API.
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(8) | Total entries used |
| 16 | 10 | BINARY(4) | Offset to ASP information sets |
| 20 | 14 | BINARY(4) | Number of ASP information sets |
| 24 | 18 | BINARY(4) | Length of ASP information set entry |
| * | * | Array of CHAR(*) | ASP information sets |
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | ASP name |
| 10 | A | CHAR(1) | AUTL extension indicator |
| 11 | B | CHAR(1) | Reserved |
| 12 | C | BINARY(4) | Number of entries used |
| 16 | 10 | BINARY(4) | Number entries available |
ASP name. The name of the ASP whose information is being returned. The system ASP and basic user ASP information is returned with an ASP name of *SYSBAS. For independent ASPs, the ASP name is the name of the varied on device description associated with the independent ASP.
AUTL extension indicator. This field indicates whether an authorization list extension exists for the specified AUTL on the varied on independent ASP. The possible values for this field are:
Bytes available. The number of bytes of data available to be returned to the user.
If the bytes available field is larger than the bytes returned field, all of the ASP information will not be included in the receiver variable.
Bytes returned. The number of bytes of data returned to the user in the receiver variable.
Length of ASP information set entry. The length of a single ASP information set.
Number of ASP information sets. The number of ASP information sets. This is the total number of information sets that could be returned. There is always one ASP information set for *SYSBAS. Additional ASP information sets are provided for each varied on independent ASP even if the authorization list does not currently secure any objects in the independent ASP. The ASP information set for *SYSBAS is always the first ASP information set returned.
Number of entries used. The number of entries used for securing objects that reside in the ASP. This field can have a value from zero to 2,097,104.
Number entries available. The number of entries available for securing additional objects that reside in the ASP. This field can have a value from zero to 2,097,104.
Offset to ASP information sets. The offset from the beginning of the receiver variable to the begining of the ASP information sets.
Reserved. Reserved space used for boundary alignment.
Total entries used. The total number of authorization list entries used for all objects secured by the authorization list that reside in the system ASP, basic user ASPs, and all varied on independent ASPs. This field can have a value ranging from zero to the (number-of-varied-on-independent-ASPs + 1) multiplied by 16,777,215.
| Message ID | Error Message Text |
|---|---|
| CPF22F0 E | Unexpected errors occurred during processing. |
| CPF3C19 E | Error occurred with receiver variable specified. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3C24 E | Length of receiver variable is not valid. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF8132 E | Authorization list &4 damaged. |
| CPF9801 E | Object &2 in library &3 not found. |
| CPF9802 E | Not authorized to object &2 in &3. |
| CPF9803 E | Cannot allocate object &2 in library &3. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
[ Back to top | Security APIs | APIs by category ]