A value of *NOTAVL will
be returned for the object auditing information unless you have either all
object (*ALLOBJ) or audit (*AUDIT) special authority.
| 1 | Qualified user space object | Input | Char(20) |
| 2 | Format name | Input | Char(8) |
| 3 | Object and library name | Input | Char(20) |
| 4 | Object type | Input | Char(10) |
| 5 | Error Code | I/O | Char(*) |
| 6 | Authority control | Input | Char(*) |
| 7 | Selection control | Input | Char(*) |
| 8 | Auxiliary storage pool (ASP) control | Input | Char(*) |
The List Objects (QUSLOBJ) API lets you generate a list of object names and descriptive information based on specified selection parameters. This API returns information similar to the Display Object Description (DSPOBJD) command. An advantage over the DSPOBJD command is that you can perform authority checking on the objects and libraries. You can get a list of objects with only a certain status, which you cannot do with the DSPOBJD command. The QUSLOBJ API places the list in the specified user space. The generated list replaces any existing list in the user space.
You can use the QUSLOBJ API to:
The QUSLOBJ API returns information in several formats. All formats except OBJL0100 include an information status field that describes the completeness and validity of the information. Be sure to check the information status field before using any other information returned.
If you are authorized to the library, some object information is always
returned for the objects meeting the search criteria identified in the required
parameter group. To return any detailed object information in format OBJL0200
and above, the user must be authorized to the objects. The information status
field in format OBJL0200 is set to 'A' when the user is not authorized to the
objects. A value of *NOTAVL will
be returned for the object auditing information unless you have either all
object (*ALLOBJ) or audit (*AUDIT) special authority.
The name of the *USRSPC object that is to receive the generated list. The first 10 characters contain the user space object name, and the second 10 characters contain the name of the library where the user space is located. The special values supported for the library name are *LIBL and *CURLIB.
The format of the information returned on each object that is requested. You must use one of the following format names:
| OBJL0100 | Object names (fastest) |
| OBJL0200 | Text description and extended attribute |
| OBJL0300 | Basic object information |
| OBJL0400 | Creation information |
| OBJL0500 | Save and restore information; journal information |
| OBJL0600 | Usage information |
| OBJL0700 | All object information (slowest) |
For details about the formats, see Format of the Generated Lists. For performance reasons, you should choose the format that returns only as much information as you need. The higher the number of the format name, the more information is returned and the more time it takes to process.
The object and library names to place in the *USRSPC object. The first 10 characters contain the object name, which may be a simple name, a generic name, or the special values of *ALL, *ALLUSR, or *IBM. If *ALLUSR or *IBM is used, the library name must be *LIBL or QSYS and the object type parameter must be *LIB.
Library name errors are reported with escape messages when a single library is specified. When searching a set of libraries (library specified as *ALL, *ALLUSR, *LIBL, or *USRLIBL or auxiliary storage pool (ASP) device name specified as *ALLAVL), library errors are reported with diagnostic messages and processing continues. Library authority error messages are not sent when searching a set of libraries. Escape messages are not sent for object name errors. To determine if errors occurred on the object, use the number of list entries field returned in the generic header and the information status field in format OBJL0200.
The second 10 characters identify the name of the library or libraries to search for the specified objects. The following special values are allowed:
| *ALL | All libraries in the auxiliary storage pools defined by the auxiliary storage pool (ASP) control parameter are searched. |
| *ALLUSR | All user libraries in the auxiliary storage pools (ASPs) defined by the auxiliary storage pool (ASP) control parameter are searched. User libraries are all libraries with names that do not begin with the letter Q. For information on the libraries included, see *ALLUSR in Generic library names. |
| *CURLIB | The thread's current library is searched. When this value is used, the auxiliary storage pool (ASP) device name in the auxiliary storage pool (ASP) control parameter must be an asterisk (*), if specified. |
| *LIBL | All libraries in the thread's library list are searched. When this value is used, the auxiliary storage pool (ASP) device name in the auxiliary storage pool (ASP) control parameter must be an asterisk (*), if specified. |
| *USRLIBL | All libraries in the user portion of the thread's library list are searched. When this value is used, the auxiliary storage pool (ASP) device name in the auxiliary storage pool (ASP) control parameter must be an asterisk (*), if specified. |
The types of objects to search for. You may either enter a specific object
type, or a special value of *ALL. For a complete list of the available object
types, see the
External object
types
information.
The structure in which to return error information. For the format of the structure, see Error Code Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the application.
This parameter is used to specify the authority check that should be done for objects and libraries. Detailed object information will only be returned for an object when you have the specified authority to the object. If this parameter is omitted, the following occurs:
This parameter is useful to select objects to which you are authorized. To accomplish this, specify a select or omit status value in the selection control parameter. The object name information in format OBJL0100 is always returned for objects meeting the search criteria identified in the required parameter group. (This assumes the thread has the required authority to the library.) The information status field is set to an 'A' when the thread does not have the object authority specified.
The following example shows what you would specify to obtain a subset of all objects that you have object management authority to.
The authority control parameter would contain:
The selection control parameter would contain:
Because the program that calls the QUSLOBJ API adopts authority, the authority check should be done at the call level previous to the current level (thus call level 1). With call level 1, the list would not include any objects for which you have adopted authority by the current program.
The select or omit status value of 1 indicates that the returned list will omit the objects you do not have object management authority to. This authority is specified in the object authorities field.
The format of this parameter is described in Authority Control Format.
The criteria used to select or filter objects from the list based on specified information status values.
This parameter is useful to reduce the total number of objects returned in the list. The list of objects can be generated with only the specific status that you are interested in. For example, this might be all damaged objects or all objects that the caller of the API is not authorized to. The list of objects also can be generated with all objects except objects of a specific status.
The following example shows what you would specify to select all damaged objects:
The format of this parameter is described in Selection Control Format.
The information used to define the auxiliary storage pool (ASP) to search. See Auxiliary Storage Pool (ASP) Control Format for details.
The following shows the format of the authority control parameter. For detailed descriptions of the fields in the table, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Length of authority control format |
| 4 | 4 | BINARY(4) | Call level |
| 8 | 8 | BINARY(4) | Displacement to object authorities |
| 12 | C | BINARY(4) | Number of object authorities |
| 16 | 10 | BINARY(4) | Displacement to library authorities |
| 20 | 14 | BINARY(4) | Number of library authorities |
| 24 | 18 | BINARY(4) | Reserved |
| ARRAY(*) of CHAR(10) | Object authorities | ||
| ARRAY(*) of CHAR(10) | Library authorities | ||
The following shows the format of the selection control parameter. For detailed descriptions of the fields in the table, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Length of selection control format |
| 4 | 4 | BINARY(4) | Select or omit status value |
| 8 | 8 | BINARY(4) | Displacement to statuses |
| 12 | C | BINARY(4) | Number of statuses |
| 16 | 10 | BINARY(4) | Reserved |
| ARRAY(*) of CHAR(1) | Statuses | ||
The following shows the format of the auxiliary storage pool (ASP) control parameter. This parameter is used to define the auxiliary storage pools (ASPs) to search. For detailed descriptions of the fields in the table, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Length of auxiliary storage pool (ASP) control format |
| 4 | 4 | CHAR(10) | Auxiliary storage pool (ASP) device name |
| 14 | E | CHAR(10) | Auxiliary storage pool (ASP) search type |
Auxiliary storage pool (ASP) device name. The name of an auxiliary storage pool (ASP) device in which storage is allocated for the library that contains the object. The ASP device must have a status of 'Available'. This field must be an asterisk (*) if optional parameter group 3 is specified when *CURLIB, *LIBL, or *USRLIBL is specified as the library name in the object and library name parameter. If optional parameter group 3 is omitted in cases where it is valid for the ASP device name to have a value other than an asterisk (*), the thread's library name space will be used. One of the following special values may be specified:
| * | The ASPs in the thread's library name space. |
| *SYSBAS | The system ASP (ASP 1) and defined basic user ASPs (ASPs 2-32). |
| *CURASPGRP | The ASPs in the current thread's ASP group. |
| *ALLAVL | All available ASPs. This includes the system ASP
(ASP 1), all defined basic user ASPs (ASPs 2-32), and all available primary and
secondary ASPs (ASPs 33-255 with a status of 'Available').
The ASP groups are searched
in ascending alphabetical order by the primary ASP name. The system ASP and
all defined basic user ASPs are searched after the ASP groups. ASPs and libraries
to which you are not authorized are bypassed and no authority error messages
are sent. |
Auxiliary storage pool (ASP) search type. The type of the search when a specific auxiliary storage pool (ASP) device name is specified for the ASP device name field. This field must be blanks when a special value is specified for the auxiliary storage pool (ASP) device name field. One of the following values may be specified:
| *ASP | Only the single ASP named in the auxiliary storage pool (ASP) device name field will be searched. |
| *ASPGRP | All ASPs in the auxiliary storage pool (ASP) group named in the auxiliary storage pool (ASP) device name field will be searched. The device name must be the name of the primary auxiliary storage pool (ASP) in the group. |
Call level. The number of call levels to go back in the call stack to do the authority check. If optional parameter group 2 is omitted, a call level of 0 is used.
For example, if the program that calls this API adopts authority, you probably would not want the authority check to use the adopted authority. Therefore, the authority check should be done at the call level previous to the current level. This field should then contain a 1. You can check the authority at various call levels by specifying a number equivalent to the call level. For example, to check the authority at the current call level, specify a 0. To check the authority at the previous call level, specify a 1.
This field must be greater than or equal to 0 and less than the number of programs in the call stack.
Displacement to library authorities. The displacement, in bytes, from the beginning of the authority control format to the list of library authorities. The displacement value must be at least 28, which is past the reserved portion of the format.
Displacement to object authorities. The displacement, in bytes, from the beginning of the authority control format to the list of object authorities. The displacement value must be at least 28, which is past the reserved portion of the format.
Displacement to statuses. The displacement, in bytes, from the beginning of the selection control format to the list of statuses requested. The displacement value must be at least 20, which is past the reserved portion of the format.
Length of authority control format. The total length of the authority control format. The length can be 0 bytes to indicate that no authority control information is provided. Otherwise, the minimum size is 48 bytes, which allows for one object and one library authority. An error is returned if the length specified is less than the minimum and not 0.
Length of auxiliary storage pool (ASP) control format. The total length of the auxiliary storage pool (ASP) control format. The length can be 0 bytes to indicate that no auxiliary storage pool (ASP) control information is provided. Otherwise, the length must be 24 bytes. An error is returned if the length specified is not 24 or 0.
Length of selection control format. The total length of the selection control format. The length can be 0 bytes to indicate that no selection control information is provided. Otherwise, the minimum size is 21 bytes, which allows for one status value. An error is returned if the length specified is less than the minimum and not 0.
Library authorities. The authority to check for libraries. The array can contain up to ten 10-character fields. If optional parameter group 2 is omitted, *EXECUTE authority is checked for on the libraries.
The authority values can be specified in any combination. If *ALL, *CHANGE, or *USE is specified with any of the other authority values, the authority checked is the cumulative authority value.
The maximum number of authorities that can be specified is 10. This equals all of the specific object and data authorities that can be listed separately.
The following identifies the type of authority you have to the library:
| *ALL | All authority |
| *CHANGE | Change authority |
| *USE | Use authority |
| *OBJOPR | Object operational authority |
| *OBJMGT | Object management authority |
| *OBJEXIST | Object existence authority |
| *OBJALTER | Alter authority |
| *OBJREF | Reference authority |
| *READ | Read authority |
| *ADD | Add authority |
| *UPD | Update authority |
| *DLT | Delete authority |
| *EXECUTE | Execute authority |
Number of library authorities. The number of authorities specified in the library authorities array. You can specify 1 through 10 authorities.
Number of object authorities. The number of authorities specified in the object authorities array. You can specify 1 through 11 authorities.
Number of statuses. The number of statuses specified in the statuses array. You can specify 1 through 5 statuses.
Object authorities. The authority to check for objects. The array can contain up to eleven 10-character fields. If optional parameter group 2 is omitted, *ANY authority is checked for on the objects.
The authority values can be specified in any combination with the exception of the special value *ANY. This must be specified as the only value. If *ALL, *CHANGE, *USE, or *AUTLMGT is specified with any of the other authority values, the authority checked is the cumulative authority value.
The maximum number of authorities that can be specified is 11, which equals all the specific object and data authorities and *AUTLMGT authority.
The following identifies the type of authority you have to the object:
| *ALL | All authority |
| *CHANGE | Change authority |
| *USE | Use authority |
| *AUTLMGT | Authorization list management authority. (This value is valid only if the object type is *AUTL. It will be ignored for other object types.) |
| *OBJOPR | Object operational authority |
| *OBJMGT | Object management authority |
| *OBJEXIST | Object existence authority |
| *OBJALTER | Alter authority |
| *OBJREF | Reference authority |
| *READ | Read authority |
| *ADD | Add authority |
| *UPD | Update authority |
| *DLT | Delete authority |
| *EXECUTE | Execute authority |
| *ANY | Some authority other than *EXCLUDE. (If this value is specified, no other values can be specified.) |
Reserved. This field is reserved. It must be set to hexadecimal zeros.
Select or omit status value. An indicator that determines whether objects are selected or omitted from the list based on the statuses specified.
This field is useful in generating a list of objects with a certain information status, such as damaged or partially damaged objects. It can also be used to generate a list of all objects except objects with a certain information status, such as unauthorized objects.
Valid values are:
| 0 | Select on status value |
| 1 | Omit on status value |
Statuses. The status of objects to select or omit from the list of objects generated. Valid values are all of the possible values listed under the information status field (format OBJL0200). The special value * can be used to select all objects with any information status field. If optional parameter group 2 is omitted, all objects with any information status are selected.
The object list consists of:
For details about the user area and generic header, see User space format for list APIs. For details about the other items, see the following sections. For a detailed description of each field in the information returned, see Field Descriptions.
When you retrieve list entry information from a user space, you must use the entry size returned in the generic header. The size of each entry may be padded at the end. If you do not use the entry size, the result may not be valid. For examples of how to process lists, see API Examples.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | User space name |
| 10 | A | CHAR(10) | User space library name |
| 20 | 14 | CHAR(8) | Format name |
| 28 | 1C | CHAR(10) | Object name specified |
| 38 | 26 | CHAR(10) | Object library name specified |
| 48 | 30 | CHAR(10) | Object type specified |
| 58 | 3A | CHAR(2) | Reserved |
| 60 | 3C | BINARY(4) | Error code bytes provided |
| 64 | 40 | BINARY(4) | Length of authority control format |
| 68 | 44 | BINARY(4) | Call level |
| 72 | 48 | BINARY(4) | Displacement to object authorities |
| 76 | 4C | BINARY(4) | Number of object authorities |
| 80 | 50 | BINARY(4) | Displacement to library authorities |
| 84 | 54 | BINARY(4) | Number of library authorities |
| 88 | 58 | BINARY(4) | Length of selection control format |
| 92 | 5C | BINARY(4) | Select or omit status value |
| 96 | 60 | BINARY(4) | Displacement to statuses |
| 100 | 64 | BINARY(4) | Number of statuses |
| 104 | 68 | BINARY(4) | Length of auxiliary storage pool (ASP) control format |
| 108 | 6C | CHAR(10) | Auxiliary storage pool (ASP) device name |
| 118 | 76 | CHAR(10) | Auxiliary storage pool (ASP) search type |
| ARRAY(*) of CHAR(10) | Object authorities | ||
| ARRAY(*) of CHAR(10) | Library authorities | ||
| ARRAY(*) of CHAR(1) | Statuses | ||
The following information is returned in the list data section of the OBJL0100 format. For detailed descriptions of the fields in the table, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | Object name used |
| 10 | A | CHAR(10) | Object library name used |
| 20 | 14 | CHAR(10) | Object type used |
The following information is returned in the list data section of the OBJL0200 format. For detailed descriptions of the fields in the table, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | Everything from the OBJL0100 format | |
| 30 | 1E | CHAR(1) | Information status |
| 31 | 1F | CHAR(10) | Extended object attribute |
| 41 | 29 | CHAR(50) | Text description |
| 91 | 5B | CHAR(10) | User-defined attribute |
| 101 | 65 | CHAR(7) | Reserved |
The following information is returned in the list data section of the OBJL0300 format. For detailed descriptions of the fields in the table, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | Everything from the OBJL0200 format | |
| 108 | 6C | BINARY(4) | Object auxiliary storage pool (ASP) number |
| 112 | 70 | CHAR(10) | Object owner |
| 122 | 7A | CHAR(2) | Object domain |
| 124 | 7C | CHAR(8) | Creation date and time |
| 132 | 84 | CHAR(8) | Change date and time |
| 140 | 8C | CHAR(10) | Storage |
| 150 | 96 | CHAR(1) | Object compression status |
| 151 | 97 | CHAR(1) | Allow change by program |
| 152 | 98 | CHAR(1) | Changed by program |
| 153 | 99 | CHAR(10) | Object auditing value |
| 163 | A3 | CHAR(1) | Digitally signed |
| 164 | A4 | CHAR(1) | Digitally signed by system-trusted source |
| 165 | A5 | CHAR(1) | Digitally signed more than once |
| 166 | A6 | CHAR(2) | Reserved |
| 168 | A8 | BINARY(4) | Library auxiliary storage pool (ASP) number |
The following information is returned in the list data section of the OBJL0400 format. For detailed descriptions of the fields in the table, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | Everything from the OBJL0300 format | |
| 172 | AC | CHAR(10) | Source file name |
| 182 | B6 | CHAR(10) | Source file library name |
| 192 | C0 | CHAR(10) | Source file member name |
| 202 | CA | CHAR(13) | Source file updated date and time |
| 215 | D7 | CHAR(10) | Creator's user profile |
| 225 | E1 | CHAR(8) | System where object was created |
| 233 | E9 | CHAR(9) | System level |
| 242 | F2 | CHAR(16) | Compiler |
| 258 | 102 | CHAR(8) | Object level |
| 266 | 10A | CHAR(1) | User changed |
| 267 | 10B | CHAR(16) | Licensed program |
| 283 | 11B | CHAR(10) | Program temporary fix (PTF) |
| 293 | 125 | CHAR(10) | Authorized program analysis report (APAR) |
| 303 | 12F | CHAR(10) | Primary group |
| 313 | 139 | CHAR(2) | Reserved |
| 315 | 13B | CHAR(1) | Optimum space alignment |
| 316 | 13C | BINARY(4) |
Primary associated space size
|
| 320 | 140 | CHAR(4) | Reserved |
The following information is returned in the list data section of the OBJL0500 format. For detailed descriptions of the fields in the table, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | Everything from the OBJL0400 format | |
| 324 | 144 | CHAR(8) | Object saved date and time |
| 332 | 14C | CHAR(8) | Object restored date and time |
| 340 | 154 | BINARY(4) | Saved size |
| 344 | 158 | BINARY(4) | Saved size multiplier |
| 348 | 15C | BINARY(4) | Save sequence number |
| 352 | 160 | CHAR(10) | Save command |
| 362 | 16A | CHAR(71) | Save volume ID |
| 433 | 1B1 | CHAR(10) | Save device |
| 443 | 1BB | CHAR(10) | Save file name |
| 453 | 1C5 | CHAR(10) | Save file library name |
| 463 | 1CF | CHAR(17) | Save label |
| 480 | 1E0 | CHAR(8) | Save active date and time |
| 488 | 1E8 | CHAR(1) | Journal status |
| 489 | 1E9 | CHAR(10) | Journal name |
| 499 | 1F3 | CHAR(10) | Journal library name |
| 509 | 1FD | CHAR(1) | Journal images |
| 510 | 1FE | CHAR(1) | Journal entries to be omitted |
| 511 | 1FF | CHAR(8) | Journal start date and time |
| 519 | 207 | CHAR(13) | Reserved |
The following information is returned in the list data section of the OBJL0600 format. For detailed descriptions of the fields in the table, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | Everything from the OBJL0500 format | |
| 532 | 214 | CHAR(8) | Last-used date and time |
| 540 | 21C | CHAR(8) | Reset date and time |
| 548 | 224 | BINARY(4) | Days-used count |
| 552 | 228 | CHAR(1) | Usage information updated |
| 553 | 229 | CHAR(10) | Object auxiliary storage pool (ASP) device name |
| 563 | 233 | CHAR(10) | Library auxiliary storage pool (ASP) device name |
| 573 | 23D | CHAR(3) | Reserved |
The following information is returned in the list data section of the OBJL0700 format. For detailed descriptions of the fields in the table, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | Everything from the OBJL0600 format | |
| 576 | 240 | BINARY(4) | Object size |
| 580 | 244 | BINARY(4) | Object size multiplier |
| 584 | 248 | CHAR(1) |
Object overflowed
auxiliary storage pool (ASP) indicator
|
|
585 |
249 | CHAR(10) | Object auxiliary storage pool (ASP)
group name |
|
595 |
253 | CHAR(10) | Library auxiliary storage pool (ASP)
group name |
|
605 |
25D | CHAR(10) | Starting journal receiver name for apply
|
|
615 |
267 | CHAR(10) | Starting journal receiver library name
|
|
625 |
271 | CHAR(10) | Starting journal receiver
library auxiliary storage pool (ASP) device name
|
|
635 |
27B | CHAR(10) | Starting journal receiver
library auxiliary storage pool (ASP) group name
|
|
645 |
285 | CHAR(3) | Reserved
|
Allow change by program. A 1-character variable that is used to return the allow change by program flag. A 1 is returned if the object can be changed with the Change Object Description (QLICOBJD) API. A 0 is returned if the object cannot be changed with the API.
Authorized program analysis report (APAR). The identifier of the authorized program analysis report (APAR) that caused this object to be replaced. The field is blank if the object did not change because of an APAR.
Auxiliary storage pool (ASP) device name. The name of the auxiliary storage pool (ASP) device to be searched for the library, as specified in the call to the API.
Auxiliary storage pool (ASP) search type. The type of the auxiliary storage pool (ASP) search, as specified in the call to the API.
Call level. The number of call levels to go back in the call stack to do the authority check. If optional parameter group 2 is omitted, a call level of 0 is used.
For example, if the program that calls this API adopts authority, you would probably not want the authority check to use the adopted authority. Therefore, the authority check should be done at the call level previous to the current level. This field should then contain a 1. You can check the authority at various call levels by specifying a number equivalent to the call level. For example, to check the authority at the current call level, specify a 0. To check the authority at the previous call level, specify a 1.
This field must be greater than or equal to 0 and less than the number of programs in the call stack.
Changed by program. A 1-character variable that is used to return the changed by program flag. A 1 is returned if the object has been changed with the QLICOBJD API. A 0 is returned if the object has not been changed by the API.
Change date and time. The time at which the object was last changed, in system time-stamp format.
Compiler. The licensed program identifier, version number, release level, and modification level of the compiler. The field has a pppppppVvvRrrMmm format where:
| ppppppp | The licensed program identifier. |
| Vvv | The character V is followed by a 2-character version number. |
| Rrr | The character R is followed by a 2-character release level. |
| Mmm | The character M is followed by a 2-character modification level. |
The field is blank if you do not compile the program.
Creation date and time. The time at which the object was created, in system time-stamp format. See the Convert Date and Time Format (QWCCVTDT) API for more information about using this time-stamp format.
Creator's user profile. The name of the user that created the object.
Days-used count. The number of days the object was used. If the object does not have a last-used date, the count is 0.
Digitally signed. A 1-character variable that indicates whether the object has a digital signature.
| 0 | The object does not have a digital signature. |
| 1 | The object has a digital signature. |
Digitally signed by system-trusted source. A 1-character variable indicates whether the object is signed by a source that is trusted by the system.
| 0 | None of the object signatures came from a source that is trusted by the system. |
| 1 | The object is signed by a source that is trusted by the system. If the object has multiple signatures, at least one of the signatures came from a source that is trusted by the system. |
Digitally signed more than once. A 1-character variable that indicates whether the object has more than one digital signature.
| 0 | The object has only one digital signature or does not have a digital signature. Refer to the digitally signed variable to determine whether the object has a digital signature. |
| 1 | The object has more than one digital signature. Refer to the digitally signed by system-trusted source variable to determine whether the object has a digital signature from a source trusted by the system. |
Displacement to library authorities. The displacement, in bytes, from the beginning of this input parameter structure to the list of library authorities, as specified in the call to the API.
Displacement to object authorities. The displacement, in bytes, from the beginning of this input parameter structure to the list of object authorities, as specified in the call to the API.
Displacement to statuses. The displacement, in bytes, from the beginning of this input parameter structure to the list of statuses requested, as specified in the call to the API.
Error code bytes provided. The length of the area that the calling application provides for the error code, in bytes.
Extended object attribute. The extended attribute of the object, such as a program or file type. Extended attributes further describe the object. For example, an object type of *PGM may have a value of RPG (RPG program) or CLP (CL program), and an object type of *FILE may have a value of PF (physical file), LF (logical file), DSPF (display file), SAVF (save file), and so on.
Format name. The format of the returned output.
Information status. Whether or not the QUSLOBJ API returns the requested information for this object. Possible values are:
| blank | The requested information is returned. No errors occurred. |
| A | No information is returned. The thread that called this API needs either the authority specified in the object authorities field or *ANY authority (the default) to the object. |
| D | The requested information is returned but may be incomplete. The object is damaged and should be deleted and created again as soon as possible. |
| L | No information is returned because the object is locked. |
| P | The requested information is returned. However,
the object is partially damaged. In most instances, to recover from partial
object damage, you delete the damaged object and either restore a saved copy or
create the object again. For some damaged objects, special recovery procedures
are possible. Refer to the
Backup and Recovery book for more
information on damaged objects. |
If two or more conditions occur that include no authorization (A) to the object, the status is set to A. If the object is damaged (D) and locked (L), or if the object is partially damaged (P) and locked, the status is set to L.
If the value of this field is A or L, your application should not use the other fields for the object. Only the object name, library, and type fields contain accurate data.
Journal entries to be omitted. The journal entries to be omitted. The field is 1 if open and close operations do not generate open and close journal entries. The field is 0 if no entries are omitted. This field is blank if the object has never been journaled.
Journal images. The type of images that are written to the journal receiver for updates to the object. The field is 0 if only after images are generated for changes to the object. The field is 1 if both before and after images are generated for changes to the object. This field is blank if the object has never been journaled.
Journal library name. The name of the library that contains the journal. This field is blank if the object has never been journaled.
Journal name. The name of the current or last journal. This field is blank if the object has never been journaled.
Journal start date and time. The time at which journaling for the object was last started, in system time-stamp format. This field contains hexadecimal zeros if the object has never been journaled.
Journal status. The 1-character variable that returns the current journaling status of an object. The value is 1 if the object currently is being journaled; the value is 0 if the object currently is not being journaled.
Last-used date and time. The date and time at which the object was last used, in system time-stamp format. If the object has no last-used date, the field contains hexadecimal zeros.
Length of authority control format. The total length of the authority control format, as specified in the call to the API.
Length of auxiliary storage pool (ASP) control format. The total length of the auxiliary storage pool (ASP) control format, as specified in the call to the API.
Length of selection control format. The total length of the selection control format, as specified in the call to the API.
Library authorities. The authority to check for libraries. The array can contain up to ten 10-character fields. If optional parameter group 2 is omitted, *EXECUTE authority is checked for on the libraries.
The authority values can be specified in any combination. If *ALL, *CHANGE, or *USE is specified with any of the other authority values, the authority checked is the cumulative authority value.
The maximum number of authorities that can be specified is 11. This equals all of the specific object and data authorities that can be listed separately.
The following identifies the type of authority you have to the library:
| *ALL | All authority |
| *CHANGE | Change authority |
| *USE | Use authority |
| *OBJOPR | Object operational authority |
| *OBJMGT | Object management authority |
| *OBJEXIST | Object existence authority |
| *OBJALTER | Alter authority |
| *OBJREF | Reference authority |
| *READ | Read authority |
| *ADD | Add authority |
| *UPD | Update authority |
| *DLT | Delete authority |
| *EXECUTE | Execute authority |
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 object. The
following special values may be returned:
| *N | The name of the ASP device cannot be
determined. |
| *SYSBAS | System ASP (ASP 1) or basic user ASPs (ASPs 2-32) |
Library
auxiliary storage pool (ASP) group name. The name of the auxiliary
storage pool (ASP) group where storage is allocated for the library that
contains the object. The name of the ASP group is the name of the primary ASP
within the ASP group. The value returned may be the same as the value returned
for the library 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) |
Library auxiliary storage pool (ASP) number. The number of the auxiliary storage pool (ASP) where storage is allocated for the library that contains the object. Valid values are:
| 1 | System ASP |
| 2-32 | Basic user ASP |
| 33-255 | Primary or secondary ASP |
Licensed program. The name, release level, and modification level of the licensed program if the retrieved object is part of a licensed program. The 7-character name starts in character position 1, the version number starts in position 8, the release level starts in position 11, and the modification level starts in position 14. The field is blank if the retrieved object is not a part of a licensed program.
Number of library authorities. The number of authorities specified in the library authorities array. You can specify 1 through 10 authorities.
Number of object authorities. The number of authorities specified in the object authorities array. You can specify 1 through 11 authorities.
Number of statuses. The number of statuses specified in the statuses array. You can specify 1 through 5 statuses.
Object auditing value. A 10-character variable that is used to return the type of auditing for an object. The valid values are:
| *NONE | No auditing occurs for this object when it is read or changed regardless of the user who is accessing the object. |
| *USRPRF | Audit this object only if the user accessing the object is being audited. The user profile for the thread is tested to determine if auditing should be done for this object. The user profile can specify if only change access is audited or if both read and change accesses are audited for this object. |
| *CHANGE | Audit all change access to this object by all users on the system. |
| *ALL | Audit all access to this object by all users on the system. All access is defined as a read or change operation. |
|
*NOTAVL |
The auditing value is not available because you
do not have either all object (*ALLOBJ) or audit (*AUDIT) special authority.
|
Object authorities. The authority to check for objects. The array can contain up to eleven 10-character fields. If optional parameter group 2 is omitted, *ANY authority is checked for on the objects.
The authority values can be specified in any combination with the exception of the special value *ANY. This must be specified as the only value. If *ALL, *CHANGE, *USE, or *AUTLMGT is specified with any of the other authority values, the authority checked is the cumulative authority value.
The maximum number of authorities that can be specified is 11, which equals all the specific object and data authorities and *AUTLMGT authority.
The following identifies the type of authority you have to the object:
| *ALL | All authority |
| *CHANGE | Change authority |
| *USE | Use authority |
| *AUTLMGT | Authorization list management authority. (This value is valid only if the object type is *AUTL. It will be ignored for other object types.) |
| *OBJOPR | Object operational authority |
| *OBJMGT | Object management authority |
| *OBJEXIST | Object existence authority |
| *OBJALTER | Alter authority |
| *OBJREF | Reference authority |
| *READ | Read authority |
| *ADD | Add authority |
| *UPD | Update authority |
| *DLT | Delete authority |
| *EXECUTE | Execute authority |
| *ANY | Any authority other than *EXCLUDE. (If this value is specified, no other values can be specified.) |
Object auxiliary storage pool (ASP) device name. The name of the
auxiliary storage pool (ASP) device where storage is allocated for the object.
The following special values
may 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) |
Object
auxiliary storage pool (ASP) group name. The name of the auxiliary
storage pool (ASP) group where storage is allocated for the object. The name
of the ASP group is the name of the primary ASP within the ASP group. The
value returned may be the same as the value returned for the object 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) |
Object auxiliary storage pool (ASP) number. The number of the auxiliary storage pool (ASP) where storage is allocated for the object. Valid values are:
| 1 | System ASP |
| 2-32 | Basic user ASP |
| 33-255 | Primary or secondary ASP |
Object compression status. Whether the object is compressed or decompressed. The status is returned in a 1-character variable with one of these values:
| Y | Compressed. |
| N | Permanently decompressed and compressible. |
| X | Permanently decompressed and not compressible. |
| T | Temporarily decompressed. |
| F | Saved with storage freed; compression status cannot be determined. |
Temporarily decompressed objects exist in both decompressed and
compressed form. Permanently decompressed objects exist in
decompressed form only. The system handles some decompression automatically,
depending on the type of object, the operation performed on it, and its
frequency of use. For an overview of object compression and decompression, see
the Compress
or decompress objects topic. For
details about how to explicitly compress and decompress objects, see the online help
for these commands: Compress Object (CPROBJ), Decompress Object (DCPOBJ), and
Reclaim Temporary Storage (RCLTMPSTG).
Object domain. The domain that contains the object. The value is *U if the object is in the user domain, or *S if the object is in the system domain.
Object level. The object control level for the created object.
Object library name specified. The name of the object library, as specified in the call to the API.
Object library name used. The name of the library that contains the object.
Object name specified. The name of the object, as specified in the call to the API.
Object name used. The name of the object.
Object
overflowed auxiliary storage pool (ASP) indicator.
The 1-character variable
that returns the object overflowed auxiliary storage pool (ASP) indicator. The
value is 1 if the object overflowed the ASP in which it resides; the value is 0
if the object has not overflowed the ASP. For objects in the system ASP (ASP 1)
or in a primary or secondary ASP (ASPs 33-255), a 0 is always returned because
it is not possible for an object that resides in the system ASP or in a primary
or secondary ASP to overflow its ASP.
Object owner. The name of the object owner's user profile.
Object restored date and time. The time at which the object was restored, in system time-stamp format. If the object has never been restored, the field contains hexadecimal zeros.
Object saved date and time. The time at which the object was saved, in system time-stamp format. If the object has never been saved, the field contains hexadecimal zeros.
Object size. The size of the object in units of the object size
multiplier. The object size in bytes is equal to or smaller than the object size in
units multiplied by the object size multiplier.
The object size includes the
size returned in the primary associated space
size field (format OBJL0400).
Object size multiplier. The value to multiply the object size by to get the object size in bytes.
The following values can be returned:
| 1 | The object size is smaller than 1 000 000 000 bytes. |
| 1024 | The object size is between 1 000 000 000 and 1 023 999 998 976 bytes. |
| 1048576 | The object size is larger than 1 023 999 998 976 bytes. |
Object type specified. The type of the object, as specified in the call to the API.
Object type used. The type of the object. For a list of all
the available object types, see the
External object
types information.
Optimum space alignment. A 1-character variable that indicates whether the space associated with the object has been optimally aligned. Optimum alignment may allow for better performance of applications that use the object. The possible values are as follows:
| 0 | The space associated with the object has not been optimally aligned. |
| 1 | The space associated with the object has been optimally aligned. |
| 2 | There is not a space associated with the object. |
Primary associated
space size. The size, in bytes, of the primary associated space used by the
object. If the object does not have an associated space, the size is 0.
Primary group. The name of the user who is the primary group for the object. If no primary group exists for the object, this field contains a value of *NONE.
Program temporary fix (PTF). The number of the program temporary fix (PTF) number that caused this object to be replaced. This field is blank if the object was not changed because of a PTF.
Reserved. An unused field. It contains hexadecimal zeros.
Reset date and time. The date the days-used count was last reset to zero, in system time-stamp format. If the days-used count has never been reset, the field contains hexadecimal zeros.
Save active date and time. The date and time the object was last saved when the SAVACT(*LIB, *SYSDFN, or *YES) save operation was specified, in system time-stamp format. This parameter is found on the Save Library (SAVLIB), Save Object (SAVOBJ), Save Changed Object (SAVCHGOBJ), and Save Document Library Object (SAVDLO) CL commands. If the object has never been saved or if SAVACT(*NO) was specified on the last save operation for the object, the field contains hexadecimal zeros.
Save command. The command used to save the object. The field is blank if the object was not saved.
Save device. The type of device to which the object was last saved. The field is *SAVF if the last save operation was to a save file. The field is *DKT if the last save operation was to diskette. The field is *TAP if the last save operation was to tape. The field is *OPT if the last save operation was to optical. The field is blank if the object was not saved.
Save file library name. The name of the library that contains the save file if the object was saved to a save file. The field is blank if the object was not saved to a save file.
Save file name. The name of the save file if the object was saved to a save file. The field is blank if the object was not saved to a save file.
Save label. The file label used when the object was saved. The variable is blank if the object was not saved to tape, diskette, or optical. The value of the variable corresponds to the value specified for the LABEL of OPTFILE parameter on the command used to save the object.
Save sequence number. The tape sequence number assigned when the object was saved on tape. If the object was not saved to tape, the field contains zeros.
Save volume ID. The tape, diskette, or optical volumes that are used for saving the object. The variable returns a maximum of 10 six-character volumes. The volume IDs begin in character positions 1, 8, 15, 22, 29, 36, 43, 50, 57, and 64. Each volume ID entry is separated by a single character. If the object was saved in parallel format, the separator character contains a 2 before the first volume in the second media file, a 3 before the third media file, and so on, up to a 0 before the tenth media file. Otherwise, the separator characters are blank. If more than 10 volumes are used and the object was saved in serial format, 1 is returned in the 71st character of the variable. If the object was saved in parallel format, a 2 is returned in the 71st character of the variable. Otherwise, the 71st character is blank. The field is blank if the object was last saved to a save file or if it was never saved.
Saved size. The size of the object in units of the saved size multiplier at the time of the last save operation. The saved size in bytes is equal to or smaller than the saved size in units multiplied by the saved size multiplier. The saved size includes the size of the primary associated space, if one existed. The field contains zeros if the object was not saved.
Saved size
multiplier. The value to multiply the saved size by to get the saved
size in bytes.
The following values can be returned:
| 1 | The saved size is smaller than 1 000 000 000 bytes. |
| 1024 | The saved size is between 1 000 000 000 and 1 023 999 998 976 bytes. |
| 1048576 | The saved size is larger than
1 023 999 998 976 bytes.
|
Select or omit status value. An indicator that determines whether objects are selected or omitted from the list based on the statuses specified.
This field is useful in generating a list of objects with a certain information status, such as damaged or partially damaged objects. It can also be used to generate a list of all objects except objects with a certain information status, such as unauthorized objects.
| 0 | Select on status value |
| 1 | Omit on status value |
Source file library name. The name of the library that contains the source file used to create the object. The field is blank if no source file created the object.
Source file member name. The name of the member in the source file. The field is blank if no source file created the object.
Source file name. The name of the source file used to create the object. The field is blank if no source file created the object.
Source file updated date and time. The date and time the member in the source file was last updated. This field is in the CYYMMDDHHMMSS format where:
| C | Century, where 0 indicates years 19xx and 1 indicates years 20xx. |
| YY | Year |
| MM | Month |
| DD | Day |
| HH | Hour |
| MM | Minute |
| SS | Second |
The field is blank if no source file created the object.
Starting journal receiver
library name. The name of the library that contains the starting journal
receiver for apply. This field is blank if the object has never been journaled.
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 the
object has never been journaled. The following special values may 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 auxiliary storage pool (ASP) group name. The name
of the auxiliary storage pool (ASP) group where storage is allocated for the
library that contains the starting journal receiver. The name of the ASP group
is the name of the primary ASP within the ASP group. The value returned may be
the same as the value returned for the journal receiver library auxiliary storage
pool (ASP) device name field. This field is blank if the object has never been
journaled. The following special values may be returned:
| *N | The name of the ASP group 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) or Remove
Journaled Changes (RMVJRNCHG) command. This field is blank if the object has
never been journaled.
For a file object, the journal receiver will contain the entry representing
the start-of-the-save operation. However, if there are members within the
file that contain partial transactions, then those members may require an
earlier journal receiver. Use the Display File Description (DSPFD) command
to determine the partial transaction state of the members of the file.
Statuses. The status of objects to select or omit from the list of objects generated. Valid values are all of the possible values listed under the information status field (format OBJL0200). The special value * can be used to select all objects with any information status field. If optional parameter group 2 is omitted, all objects with any information status are selected.
Storage. The storage status of the object data. *FREE indicates the object data is freed and the object is suspended. *KEEP indicates the object data is not freed and the object is not suspended.
System level. The level of the operating system when the object was created. The field has a VvvRrrMmm format where:
| Vvv | The character V is followed by a 2-character version number. |
| Rrr | The character R is followed by a 2-character release level. |
| Mmm | The character M is followed by a 2-character modification level. |
System where object was created. The name of the system on which the object was created.
Text description. The text description of the object. The field is blank if no text description is specified.
Usage information updated. Whether the object usage information is updated for this object type. The indicator is returned as Y (Yes) or N (No).
User changed. Whether the user program was changed. A character 1 is returned if the user changed the object. If the object was not changed by the user, the field is character 0.
User-defined attribute. Further defines an object type. This field is set by the user while using the QLICOBJD API.
User space library name. The library that contains the user space, as specified in the call to the API.
User space name. The name of the user space.
| Message ID | Error Message Text |
|---|---|
| CPFB8ED E | Device description &1 not correct for operation. |
| CPF21AA E | Number of statuses must be between 1 and 5. |
| CPF21AB E | Status value &1 not valid. |
| CPF21AC E | Length or displacement value &1 not valid. |
| CPF21A7 E | Authority value &1 not valid. |
| CPF21A8 E | Must specify *ANY as only authority value. |
| CPF21A9 E | Select or omit value &1 not valid. |
| CPF2173 E | Value for ASPDEV not valid with special value for library. |
| CPF218C E | &1 not a primary or secondary ASP. |
| CPF218D E | &1 not a primary ASP when *ASPGRP specified. |
| CPF22F7 E | Number of authorities must be between 1 and &1. |
| CPF22F9 E | Call level &1 not valid. |
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3CAA E | List is too large for user space &1. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3CF2 E | Error(s) occurred during running of &1 API. |
| CPF3C20 E | Error found by program &1. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3C3B E | Value for parameter &2 for API &1 not valid. |
| CPF3C31 E | Object type &1 is not valid. |
| CPF3C36 E | Number of parameters, &1, entered for this API was not valid. |
| 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. |
| 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. |
| CPF9804 E | Object &2 in library &3 damaged. |
| CPF9807 E | One or more libraries in library list deleted. |
| CPF9808 E | Cannot allocate one or more libraries on library list. |
| CPF9810 E | Library &1 not found. |
| CPF9814 E | Device &1 not found. |
| CPF9820 E | Not authorized to use library &1. |
| CPF9825 E | Not authorized to device &1. |
| CPF9830 E | Cannot assign library &1. |
| CPF9833 E | *CURASPGRP or *ASPGRPPRI specified and thread has no ASP group. |
| CPF9838 E | User profile storage limit exceeded. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
| Top | Object APIs | APIs by category |