Retrieve Library Description (QLIRLIBD) API
Required Parameter Group:
| 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(*) |
Default Public Authority: *USE
Threadsafe: Yes
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). This API also returns an indication of whether or not the library is currently journaled and other journaling attributes for the library.
The QSYS2.LIBRARY_INFO table function can be used as an alternative to this API. See LIBRARY_INFO table function for more information.
Authorities and Locks
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.
- Library Authority
- *READ
- Library Lock
- *SHRRD
Required Parameter Group
- Receiver variable
- OUTPUT; CHAR(*)
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.
- Length of receiver variable
- INPUT; BINARY(4)
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.
- Library name
- INPUT; CHAR(10)
The name of the library for which information is being retrieved.
- Attributes to retrieve
- INPUT; CHAR(*)
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 Keys.
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
Format of Data Returned
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. |
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 | ||
Field Descriptions
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:
- This field
- The key identifier
- The size of (returned) field
- The field value
- The reserved field (if multiple keys are requested)
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.
Keys
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 |
| 10 | CHAR(1) | Currently journaled |
| 11 | CHAR(10) | Current or last journal name |
| 12 | CHAR(10) | Current or last journal library name |
| 13 | CHAR(1) | Journal images |
| 14 | CHAR(1) | Omit journal entry |
| 15 | CHAR(1) | New objects inherit journaling |
| 16 | CHAR(8) | Journaling last started date and time |
| 17 | CHAR(10) | Starting journal receiver name for apply |
| 18 | CHAR(10) | Starting journal receiver library name for apply |
| 19 | CHAR(10) | Starting journal receiver library auxiliary storage pool (ASP) device name |
| 20 | CHAR(10) | Starting journal receiver library auxiliary storage pool (ASP) group name |
| 21 | CHAR(*) | Journal inherit rules |
Field Descriptions
Auxiliary storage pool (ASP) device name. The name of the ASP device where storage is allocated for the library. The following special values can 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 can be the same as the value returned for the auxiliary storage pool (ASP) device name field. The following special values can 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. The following values can be returned:
| 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 following values can be returned:
| *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 following values can be returned:
| *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. |
Current or last journal library name. The name of the library that contains the journal that receives the journaled changes to the library, if the library is currently journaled. If the library was previously journaled but is not currently journaled, this field contains the name of the library that contains the last journal to which the library was journaled. This field is blank if journaling has never been started for this library.
Current or last journal name. The name of the journal that receives the journaled changes to the library, if the library is currently journaled. If the library was previously journaled but is not currently journaled, this field contains the name of the last journal to which the library was journaled. This field is blank if journaling has never been started for this library.
Currently journaled. An indication of whether or not the library is currently journaled. See the Start Journal Library (STRJRNLIB) command for more information about starting journaling for a library. The following values can be returned:
| '0' | The library is not currently journaled. |
| '1' | The library is currently journaled. |
Other journaling-related fields may contain data even though the library is not currently journaled.
Journal images. The type of images that are written to the journal receiver for updates to the library. The following values can be returned:
| blank | Journaling has never been started for this library. |
| '0' | Only after images are generated for changes to the library. |
Journal inherit rules. The rules specifying the conditions when journaling is to be inherited from the library. Journaling can be started when a new journal-eligible object created into, moved into, or restored into this library. Each rule defines the object types, object names, and operations that determine the objects for which journaling should be started and which journaling attributes those objects should have. See the Start Journal Library (STRJRNLIB) command for more information about journaling a library. The journal inherit rules are defined in a commonly shared format, Qjo_Inherit_Rules_t. See Journal Inherit Rules for more information about this layout.
Journaling last started date and time. The date and time at which journaling was last started for the library, in system time-stamp format. See Convert Date and Time Format (QWCCVTDT) API for information about using this time-stamp format. This field contains hexadecimal zeros if journaling has never been started for the library.
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.
New objects inherit journaling. Identifies whether or not new journal-eligible objects created into, moved into, or restored into this library should inherit journaling from the library according to the journal inherit rules. The journal inherit rules can be retrieved using key 21 (Journal inherit rules).
Note: You should examine the inherit rules overridden field in the journal inherit rules to determine whether or not the journal inherit rules are overridden by the existence of a data area with the name QDFTJRN in the library, regardless of the value of this field.
The following values can be returned:
| '0' | The new journal-eligible objects will not inherit journaling from the library. |
| '1' | The new journal-eligible objects will inherit journaling from the library according to the journal inherit rules. |
Number of objects in library. The total number of external objects in the specified library. The count includes objects to which you may not be authorized.
Omit journal entry. The journal entries that will not be written. Journal entries cannot be omitted for libraries. The following values can be returned:
| blank | Journaling has never been started for this library. |
| '0' | No entries are omitted. |
Starting journal receiver library auxiliary storage pool (ASP) device name. The name of the auxiliary storage pool (ASP) device where storage is allocated for the library that contains the starting journal receiver for apply. This field is blank if either the library has never been journaled or the library has not been saved and restored since journaling was started. The following special values can be returned:
| *N | The name of the ASP device cannot be determined. |
| *SYSBAS | System ASP (ASP 1) or defined basic user ASPs (ASPs 2-32) |
Starting journal receiver library name. The name of the library that contains the starting journal receiver for apply. This field is blank if either the library has never been journaled or the library has not been saved and restored since journaling was started.
Starting journal receiver library auxiliary storage pool (ASP) group name. The name of the auxiliary storage pool (ASP) group where storage is allocated for the starting journal receiver library. The name of the ASP group is the name of the primary ASP within the group. The value returned can be the same as the value returned for the starting journal receiver library auxiliary storage pool (ASP) device name field. This field is blank if either the library has never been journaled or the library has not been saved and restored since journaling was started. The following special values can be returned:
| *N | The name of the ASP device cannot be determined. |
| *SYSBAS | System ASP (ASP 1) or defined basic user ASPs (ASPs 2-32) |
Starting journal receiver name for apply. The name of the oldest journal receiver needed to successfully use the Apply Journaled Changes (APYJRNCHG) command. This field is blank if either the library has never been journaled or the library has not been saved and restored since journaling was started.
Text description. The user-defined text that briefly describes the library and its function.
Type of library. The library type. The following values can be returned:
| '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 on-line help for more details. |
Library Size Information Format
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 |
Field Descriptions
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.
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF210E E | Library &1 not available for reason code &2. |
| 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. |
API introduced: V3R1
[ Back to top | Object APIs | APIs by category ]