Retrieve Object Description (QUSROBJD) API

The Retrieve Object Description (QUSROBJD) API lets you retrieve object information about a specific object. This information is similar to the information returned using the Display Object Description (DSPOBJD) command or Retrieve Object Description (RTVOBJD) command.

You can use the QUSROBJD API to:

• Determine who owns which objects in the specified libraries
• Provide disk management functions based on the object's size and use
• Provide backup analysis based on when the object was last saved or last updated
• Provide source member and object analysis from source member information to verify that the current source was used to create the specified object
• Work with a list of objects created by the QUSLOBJ API

Authorities and Locks

A value of *NOTAVL will be returned for the object auditing information unless you have either all object (*ALLOBJ) or audit (*AUDIT) special authority.

Auxiliary Storage Pool (ASP) Device Authority

*EXECUTE when a specific auxiliary storage pool (ASP) device name or *ALLAVL is specified for the auxiliary storage pool (ASP) control parameter.

Library Authority

*EXECUTE

Object Authority for Non-*FILE Objects

Any authority other than *EXCLUDE

Object Authority for *FILE Objects

*OBJOPR

Library Lock

None

Object Lock

*SHRRD

Required Parameter Group

Receiver variable

OUTPUT; CHAR(*)

The variable that is to receive the requested information. It can be smaller than the format requested as long as the next parameter, length of receiver variable, specifies the length correctly. When this variable is smaller than the format, the API returns only the data that the variable can hold.

Length of receiver variable

INPUT; BINARY(4)

The length of the receiver variable. The minimum length is 8 bytes. Do not specify a length that is longer than the receiver variable; the results are unpredictable.

Format name

INPUT; CHAR(8)

The content and format of the information returned for each specified member. The possible format names are:

OBJD0100	Basic information (fastest)
OBJD0200	Information similar to that displayed by the programming development manager (PDM)
OBJD0300	Service information
OBJD0400	Full information (slowest)

These are described in the following sections.

Object and library name

INPUT; CHAR(20)

The object for which you want to retrieve information, and the library in which it is located. The first 10 characters contain the object name, and the second 10 characters contain the library name. You can use these special values for the library name:

*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.

Object type

INPUT; CHAR(10)

The type of object for which you want to retrieve the information. You can only specify external object types. For a complete list of the available object types, see the External object types information.

Optional Parameter Group 1

Error code

I/O; CHAR(*)

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.

Optional Parameter Group 2

Auxiliary storage pool (ASP) control

Input; CHAR(*)

The information used to define the auxiliary storage pool (ASP) to search. See Auxiliary Storage Pool (ASP) Control Format for details. If optional parameter group 2 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.

Auxiliary Storage Pool (ASP) Control Format

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.

Field Descriptions

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 2 is specified when *CURLIB or *LIBL is specified as the library name in the object and library name parameter. If optional parameter group 2 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:

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:

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.

OBJD0100 Format

The following information is returned for the OBJD0100 format. For detailed descriptions of the fields in the table, see Field Descriptions.

Offset		Type	Field
Dec	Hex
0	0	BINARY(4)	Bytes returned
4	4	BINARY(4)	Bytes available
8	8	CHAR(10)	Object name
18	12	CHAR(10)	Object library name
28	1C	CHAR(10)	Object type
38	26	CHAR(10)	Return library
48	30	BINARY(4)	Object auxiliary storage pool (ASP) number
52	34	CHAR(10)	Object owner
62	3E	CHAR(2)	Object domain
64	40	CHAR(13)	Creation date and time
77	4D	CHAR(13)	Object change date and time

OBJD0200 Format

The following information is returned for the OBJD0200 format. For detailed descriptions of the fields in the table, see Field Descriptions.

OBJD0300 Format

The following information is returned for the OBJD0300 format. For detailed descriptions of the fields in the table, see Field Descriptions.

OBJD0400 Format

The following information is returned for the OBJD0400 format. For detailed descriptions of the fields in the table, see Field Descriptions.

Offset		Type	Field
Dec	Hex
0	0		Everything from the OBJD0300 format
460	1CC	CHAR(7)	Last-used date
467	1D3	CHAR(1)	Usage information updated
468	1D4	BINARY(4)	Days-used count
472	1D8	BINARY(4)	Object size
476	1DC	BINARY(4)	Object size multiplier
480	1E0	CHAR(1)	Object compression status
481	1E1	CHAR(1)	Allow change by program
482	1E2	CHAR(1)	Changed by program
483	1E3	CHAR(10)	User-defined attribute
493	1ED	CHAR(1)	Object overflowed auxiliary storage pool (ASP) indicator
494	1EE	CHAR(13)	Save active date and time
507	1FB	CHAR(10)	Object auditing value
517	205	CHAR(10)	Primary group
527	20F	CHAR(1)	Journal status
528	210	CHAR(10)	Journal name
538	21A	CHAR(10)	Journal library name
548	224	CHAR(1)	Journal images
549	225	CHAR(1)	Journal entries to be omitted
550	226	CHAR(13)	Journal start date and time
563	233	CHAR(1)	Digitally signed
564	234	BINARY(4)	Saved size in units
568	238	BINARY(4)	Saved size multiplier
572	23C	BINARY(4)	Library auxiliary storage pool (ASP) number
576	240	CHAR(10)	Object auxiliary storage pool (ASP) device name
586	24A	CHAR(10)	Library auxiliary storage pool (ASP) device name
596	254	CHAR(1)	Digitally signed by system-trusted source
597	255	CHAR(1)	Digitally signed more than once
598	256	CHAR(2)	Reserved
600	258	BINARY(4)	Primary associated space size
604	25C	CHAR(1)	Optimum space alignment
605	25D	CHAR(10)	Object auxiliary storage pool (ASP) group name
615	267	CHAR(10)	Library auxiliary storage pool (ASP) group name
625	271	CHAR(10)	Starting journal receiver name for apply
635	27B	CHAR(10)	Starting journal receiver library name
645	285	CHAR(10)	Starting journal receiver library auxiliary storage pool (ASP) device name
655	28F	CHAR(10)	Starting journal receiver library auxiliary storage pool (ASP) group name
665	299	CHAR(1)	Reserved

Field Descriptions

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.

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.

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.

Compiler. The licensed program identifier, version number, release level, and modification level of the compiler.

The field has a pppppppVvvRrrMmm format where:

The field is blank if you do not compile the program.

Creation date and time. The date and time the object was created. The creation date and time field is in the CYYMMDDHHMMSS 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.

Digitally signed by system-trusted source. A 1-character variable that indicates whether the object is signed by 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.

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.

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. The format is the same as the creation date description. This field is blank 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 is currently being journaled; the value is 0 if the object is currently not being journaled.

Last-used date. The date the object was last used. This field is in the CYYMMDD format, which is the same format used for the reset date. If the object has no last-used date, the field is blank.

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.

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:

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 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 device 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. A value from one of the following ranges is returned:

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 current user is being audited. The current user 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 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:

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 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 device 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. A value from one of the following ranges is returned:

Object change date and time. The date and time the object was last changed. The format is the same as the creation date description, or it is blank if the object was not changed.

Object compression status. Whether the object is compressed or decompressed. The status is returned in a 1-character variable with one of these values:

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. The name of the library that contains the object.

Object name. 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 an object that resides in the system ASP or in a primary or secondary ASP cannot overflow its ASP.

Object owner. The name of the object owner's user profile.

Object restored date and time. The date and time the object was last restored. The format is the same as for the creation date, or it is blank if the object was never restored.

Object saved date and time. The date and time the object was last saved. The format is the same as for the creation date description, or it is blank if the object was never saved.

Object size. The size of the object in units of the object size multiplier. The object size is equal to or smaller than the object size multiplied by the object size multiplier. The object size includes the value 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. The object type. 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 manipulate 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. The date the days-used count was last reset to 0. The reset date field is in the CYYMMDD format:

If the days-used count was not reset, the date is blank.

Return library. The name of the library that contains the object if *LIBL or *CURLIB is specified for the library name on the object parameter.

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. The format is the same as for the creation date description, or it is blank if the object was never saved or if SAVACT(*NO) was specified on the last save operation for the object.

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 or 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.

Saved size. The size of the object in bytes of storage at the time of the last save operation. The field contains zeros if the object was not saved. This field will contain a size up to 2 GB. If the saved size is actually greater than 2GB, -1 is returned in this field. Fields saved size in units and saved size multiplier should be used to get the saved size that is larger than 2GB.

Saved size in units. The size of the object in units of the saved size multiplier at the time of the last save operation. The saved size is equal to or smaller than the saved size multiplied by the saved size multiplier. 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.

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.

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. The field is in the same format as the creation time and date. The field is blank if no source file created the object.

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.

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 can not 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 for apply. The name of the ASP group is the name of the primary ASP within the group. The value returned may 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 the object has never been journaled. The following special values may be returned:

*N	The name of the ASP device can not 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 the object has never been journaled.

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.

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:

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.

Error Messages