A value of *NOTAVL will
be returned for the create object auditing information unless you have either all
object (*ALLOBJ) or audit (*AUDIT) special authority.
| 1 | Receiver variable | Output | Char(*) |
| 2 | Length of receiver variable | Input | Binary(4) |
| 3 | Library name | Input | Char(10) |
| 4 | Attributes to retrieve | Input | Char(*) |
| 5 | Error code | I/O | Char(*) |
The Retrieve Library Description (QLIRLIBD) API lets you retrieve attributes for a specific library, similar to the Retrieve Library Description (RTVLIBD) command. This API also returns the number of objects in a library and the total library size, the size of the objects in the library plus the size of the library object itself. Currently, the only other function that does this is the Display Library (DSPLIB) command with OUTPUT(*PRINT).
A value of *NOTAVL will
be returned for the create object auditing information unless you have either all
object (*ALLOBJ) or audit (*AUDIT) special authority.
The variable that is to receive the information requested. If this area is smaller than the actual length of the data returned, the API returns only the data that the area can hold. Refer to Format of Data Returned for details about the format.
The length of the receiver variable. The minimum length is 8 bytes. If the length is larger than the size of the receiver variable, results may be unpredictable.
The name of the library for which information is being retrieved.
The information for the library that you want to retrieve.
The information must be in the following format:
| Number of elements in request array | BINARY(4)
The total number of all of the request keys. |
| Request keys | ARRAY of BINARY(4)
An array of request keys to identify what fields of information about the library are requested. The size of the array is defined in the preceding number of elements in request array value. For a list of the valid key identifiers, see the topic Keys. |
The structure in which to return error information. For the format of the structure, see Error Code Parameter.
For detailed descriptions of the fields, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | BINARY(4) | Variable length records returned |
| 12 | C | BINARY(4) | Variable length records available |
| 16 | 10 | CHAR(*) | Variable length record for each key specified. For the specific format of the variable length record, see Format for Variable Length Record. |
For detailed descriptions of the fields, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Length of returned data |
| 4 | 4 | BINARY(4) | Key identifier |
| 8 | 8 | BINARY(4) | Size of field |
| 12 | C | CHAR(*) | Field value |
| CHAR(*) | Reserved | ||
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. This value includes the length of this field and all the fields following it in the structure.
If insufficient space is provided for the receiver variable, this value would be set to the last byte of the last complete variable length record.
Field value. The value of the field returned.
Key identifier. The key that identifies the returned field. For a list of the valid keys, see Keys.
Length of returned data. The length associated with a particular field.
The length includes the space required to hold the following fields:
Reserved. An unused field. This field contains hexadecimal zeros. If multiple keys are requested, a reserved value is added for boundary alignment.
Size of field. The size of the returned field.
Variable length records available. The number of complete variable length records that can be returned. All variable length records are returned if enough space is provided.
Variable length records returned. The number of variable length records actually returned.
The following table lists the valid key identifiers that can be specified in the attributes to retrieve parameter. See the Field Descriptions for the descriptions of the valid key fields.
| Key ID | Type | Field |
|---|---|---|
| 1 | CHAR(1) | Type of library |
| 2 | BINARY(4) | Auxiliary storage pool (ASP) number |
| 3 | CHAR(10) | Create authority |
| 4 | CHAR(10) | Create object auditing |
| 5 | CHAR(50) | Text description |
| 6 | CHAR(12) | Library size information |
| 7 | BINARY(4) | Number of objects in library |
| 8 | CHAR(10) | Auxiliary storage pool (ASP) device name |
|
9 |
CHAR(10) | Auxiliary storage pool (ASP) group name
|
Auxiliary storage pool (ASP) device name. The name of the ASP device where storage is allocated for the library. The following special values may be returned:
| *N | The name of the ASP device cannot be determined. |
| *SYSBAS | The system ASP (ASP 1) or basic user ASPs (ASPs 2-32). |
Auxiliary storage
pool (ASP) group name. The name of the ASP group where storage is
allocated for the library. The ASP group name is the name of the primary ASP
within the ASP group. The value returned may be the same as the value returned
for the auxiliary storage pool (ASP) device name field. The following special
values may be returned:
| *N | The name of the ASP group cannot be determined. |
| *SYSBAS | System ASP (ASP 1) or basic user ASPs (ASPs
2-32) |
Auxiliary storage pool (ASP) number. The number of the auxiliary storage pool (ASP) from which the system allocates storage for the library.
Possible values are:
| 1 | System ASP |
| 2-32 | Basic user ASPs |
| 33-255 | Primary or secondary ASPs |
Create authority. The default public authority for an object created into the library. This is the authority given to a user who does not have specific authority to the object, who is not on an authorization list specified for the object, and whose user groups have no specific authority to the object. When you create an object into the library, the AUT parameter on the create command for the object determines the public authority for the object. If the AUT value on the create command for the object is *LIBCRTAUT, which is the default, the public authority for the object is set to the CRTAUT value for the library.
The valid values are:
| *ALL | The user can perform all authorized operations on an object created in this library. |
| *CHANGE | The user can read the object description and has read, add, update, and delete authority to an object created in this library. |
| *EXCLUDE | The user is prevented from accessing an object created in this library. |
| *SYSVAL | The default authority for an object created in this library is determined by the value specified by the QCRTAUT system value. |
| *USE | The user can read the object and its description but cannot change them for an object created in this library. |
| Authorization list name | The name of the authorization list that secures an object created in this library. The default public authority is taken from the authorization list, and the public authority for the object is specified as *AUTL. |
Create object auditing. The auditing value for objects created in this library.
The valid values are:
| *ALL | All change or read access to the object is logged. |
| *CHANGE | All change access to the object by all users is logged. |
| *NONE | Use or change access to the object is not logged (no audit entry is sent to the security journal). |
|
*NOTAVL |
The auditing value is not available because you
do not have either all object (*ALLOBJ) or audit (*AUDIT) special authority.
|
| *SYSVAL | The value specified in the system value QCRTOBJAUD is used. |
| *USRPRF | The user profile of the user who accesses the object is used to determine if an audit record is sent for this access. The OBJAUD parameter of the Change User Auditing (CHGUSRAUD) command is used to turn auditing on for a specific user. |
Library size information. Information about the size of the library, which includes the size of the objects in the library plus the size of the library object itself. Only objects to which you have an authority other than *EXCLUDE are included in the total library size. See Library Size Information Format for the format of this key.
Number of objects in library. The total number of objects in the specified library. The count includes objects to which you may not be authorized.
Text description. The user-defined text that briefly describes the library and its function.
Type of library. The library type.
Possible values are:
| '0' | The library is a production library. Database files in production libraries cannot be opened for updating if a user, while in debug mode, requested that production libraries be protected. |
| '1' | The library is a test library. All objects in a test library can be updated during a test. See the Start Debug (STRDBG) command in the online help for more details. |
The following table shows the layout of the library size information key. For detailed descriptions of the fields, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Library size |
| 4 | 4 | BINARY(4) | Library size multiplier |
| 8 | 8 | CHAR(1) | Information status |
| 9 | 9 | CHAR(3) | Reserved |
Information status. Whether or not all objects in the library were calculated in the library size.
The following values can be returned:
| '0' | Some objects in the library are locked, or the user does not have any authority to the object. The size of these objects was not included in the total library size. |
| '1' | The size of all the objects in the library was used in determining the total library size. |
Library size. The size of the library object and all of the objects in the library in units of the library size multiplier. If the information status field is 1, the total library size is equal to or smaller than the library size multiplied by the library size multiplier. If the information status field is 0, the total library size could be greater than the library size multiplied by the library size multiplier because the size of some objects has not been included in the total library size.
Library size multiplier. The value to multiply the library size by to get the total library size.
The following values can be returned:
| 1 | The total library size is smaller than 1, 000, 000, 000 bytes. |
| 1024 | The total library size is between 1, 000, 000, 000 and 1, 024, 000, 000, 000 bytes. |
| 1 048 576 | The total library size is larger than 1, 024, 000, 000, 000 bytes. |
Reserved. An unused field. This field contains hexadecimal zeros.
| Message ID | Error Message Text |
|---|---|
| CPF2115 E | Object &1 in &2 type *&3 damaged. |
| CPF2150 E | Object information function failed. |
| CPF2151 E | Operation failed for &2 in &1 type *&3. |
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3C19 E | Error occurred with receiver variable specified. |
| CPF3C24 E | Length of the receiver variable is not valid. |
| CPF3C82 E | Key &1 not valid for API &2. |
| CPF3C88 E | Number of variable length records &1 is not valid. |
| CPF3C89 E | Key &1 specified more than once. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF8100 E | All CPF81xx messages could be returned. xx is from 01 to FF. |
| CPF980B E | Object &1 in library &2 not available. |
| 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. |
| Top | Object API categories | API by category |