Change Object Description (QLICOBJD) API
Required Parameter Group:
| 1 | Returned library name | Output | Char(10) |
| 2 | Object and library name | Input | Char(20) |
| 3 | Object type | Input | Char(10) |
| 4 | Changed object information | Input | Char(*) |
| 5 | Error code | I/O | Char(*) |
Default Public Authority: *USE
Threadsafe: Yes
The Change Object Description (QLICOBJD) API lets you change object information for a specific object similar to the Change Object Description (CHGOBJD) command. Unlike the CHGOBJD command, this can be used on all library-based external object types. This API supports changing more parts of the object descriptive information than are supported using the CHGOBJD command.
Before any change other than to the text or the days used count and days used count reset date is made with this API, the allow change by program field for the object is checked. If this API cannot be used to change the object, message CPF219B is issued.
When an object has been successfully updated by the API, the changed by program field is updated. In addition, the change date and time (date and time the object was changed) field is also updated unless you also specify that the change date and time field is not to be updated. You can only specify that the change date and time field is not to be updated when the only field to be updated is the last used date field.
If the object being changed is currently journaled, journal entries of type CG, CH, or ZB as appropriate for the object type are deposited in the journal to record the change.
Note: For additional information regarding journaling, see Journal management.
Authorities and Locks
- Library Authority
- *EXECUTE
- Non-*FILE Object Authority
- *OBJMGT
- *FILE Object Authority
- *OBJOPR and *OBJMGT
- Object Lock
- *EXCLRD
Required Parameter Group
- Returned library name
- OUTPUT; CHAR(10)
The name of the library that contains the changed object. If *CURLIB, *LIBL, or a name is specified for the library name in the object and library name parameter, the value returned is the name of the library where the object was found.
- Object and library name
- INPUT; CHAR(20)
The object for which you want to change 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 job's current library *LIBL The job's library list
- Object type
- INPUT; CHAR(10)
The type of object for which you want to change the information. You can only specify specific external object types. An asterisk (*) must precede the object type. For a complete list of the available object types, see External object types.
- Changed object information
- INPUT; CHAR(*)
The information for the object that you want to change. The information must be in the following format:
Number of variable length records BINARY(4)
Total number of all of the variable length records. If the value of this field is less than 0, an error message is returned. It is not an error if this field is 0. If it is 0, the API will make no changes to the object's description.Variable length records The fields of the object's description to change and the data used for the change. For the specific format of the variable length record, see Format for Variable Length Record.
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
Format for Variable Length Record
The following table defines the format for the variable length records.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Key |
| 4 | 4 | BINARY(4) | Length of data |
| 8 | 8 | CHAR(*) | Data |
If the length of the data is longer than the related field's data length, the data will be truncated at the right. No message will be issued.
If the length of the data is smaller than the related field's data length, the data will be padded with blanks at the right. No message will be issued.
It is not an error to specify a key more than once. If duplicate keys are specified, the last specified value for that key is used.
Each variable length record must be 4-byte aligned. If not, unpredictable results may occur.
Field Descriptions
Data. The data used to change a specific field of the object description.
Validity checking is done on the values specified for the following keys to verify that they are '0' or '1'.
- Key 8 (Allow change by program)
- Key 11 (Reset days used count and update days used count reset date)
- Key 15 (Update last used date and days used count)
- Key 16 (Update change date and time)
Validity checking is done on the value specified for key 19 (Created by user) to verify that it is not *IBM.
Validity checking is done on the value specified for key 20 (Creation date and time) to verify that it contains numeric data in the correct ranges. The date portion of the value (CYYMMDD) must be in the range of 0280824 (August 24, 1928) to 1710509 (May 9, 2071). The time portion of the value (HHMMSS) must be in the range 000000 to 235959.
The data specified for other keys is not validity checked.
Key. Identifies a field of the object's description to change. Only specific fields of the object's description can be changed. See Keys for the list of valid keys.
Length of data. The length of the data used to change a specific field of the object's description. If the value of this field is 0 or negative, an error message is returned.
Keys
The following table lists the valid keys for the key field of the variable length record.
| Key | Type | Field |
|---|---|---|
| 1 | CHAR(30) | Source file |
| 2 | CHAR(13) | Source file date and time |
| 3 | CHAR(13) | Compiler |
| 4 | CHAR(8) | Object control level |
| 5 | CHAR(13) | Licensed program |
| 6 | CHAR(7) | Program temporary fix (PTF) |
| 7 | CHAR(6) | Authorized program analysis report (APAR) |
| 8 | CHAR(1) | Allow change by program |
| 9 | CHAR(10) | User-defined attribute |
| 10 | CHAR(50) | Text |
| 11 | CHAR(1) | Reset days used count and update days used count reset date |
| 12 | CHAR(4) | Product option load ID |
| 13 | CHAR(4) | Product option ID |
| 14 | CHAR(4) | Component ID |
| 15 | CHAR(1) | Update last used date and days used count |
| 16 | CHAR(1) | Update change date and time |
| 17 | CHAR(10) | Reset member's days used count and update member's days used count reset date |
| 18 | CHAR(8) | System created on |
| 19 | CHAR(10) | Created by user |
| 20 | CHAR(13) | Creation date and time |
| 21 | CHAR(16) | Build identifier |
Field Descriptions
Allow change by program. Whether to allow users to make changes to the object's description other than to the text or the days used count and days used count reset date with this API. It must have a value of '0' or '1'.
| '0' | Changes other than to the text or the days used count and days used count reset date are not allowed with this API. Once this field has been changed to '0', this API cannot be used to make any further changes to the object's description other than to the text or the days used count and days used count reset date. |
| '1' | Changes are allowed with this API. This API can be used to make all changes to the object's description. |
Authorized program analysis report (APAR). The authorized program analysis report identification that caused this object to be patched. IBM® APARs have an uppercase alphabetic character followed by 5 decimal numbers. If you want to conform with the system, this format should be followed.
Build identifier. The build identifier defined for the object. This field is set by IBM for objects built using Rational tools.
Compiler. 
The name and the
level of the compiler used to create the object.
Objects
created with IBM products will have the licensed program name of the compiler in the compiler name field and
a version field. If you want to conform with the
system, this format should be followed.
| Compiler name | CHAR(7) |
The product number or identifier of the
compiler. Example: 5770WDS
| Version | CHAR(6) |
The data in the version field is not validity
checked. To conform with the system, the version field should be specified as one of the
following formats:
| VxRyMz | Where x is any numeric character 0 through 9, y is any numeric
character 0 through 9, and z is any numeric character 0 through 9 or uppercase letter
A through Z. For example, V7R2M0 is
version 7, release 2, modification 0. |
| vvrrmm | Where vv are any numeric characters 00 through 35 representing the version
of the product, rr are any numeric characters 00 through 35 representing the release of the
product, and mm can be 00 through 09 or 0A through 0Z representing the modification of the
product. For example, 110300 is version 11, release 3, modification 0. This format must be used
if the version or release of the product is greater than 9.
With this format the 'V', 'R' and 'M' characters are not included in the key data.
The version shown on the Display Object Description panel and returned by object-related APIs
include the 'V', 'R' and 'M' characters. |
Component ID. The product administrator owns this field. It can be used to track information about objects, such as object size, at a lower level than the product option ID.
Created by user. The name of the user that created the object. A value of *IBM may not be specified. If it is, message CPF2199 is issued.
Creation date and time. The date and time the object was created. The date and time is specified in the CYYMMDDHHMMSS format:
| C | Century, where 0 indicates years 19xx and 1 indicates years 20xx, etc. |
| YY | Year |
| MM | Month |
| DD | Day |
| HH | Hour |
| MM | Minute |
| SS | Second |
The date portion of the value (CYYMMDD) must be in the range of 0280824 (August 24, 1928) to 1710509 (May 9, 2071). The time portion of the value (HHMMSS) must be in the range 000000 to 235959. Changing the creation date of a database file does not change the creation date of any file members in the file.
Licensed program. The product
number and level of the licensed program associated with the object. Objects that
are a part of an IBM licensed program have a valid licensed program name and a
version field. If you want to conform with the system, this format should be
followed.
| Licensed program name | CHAR(7) |
The program name (7 characters
containing 0-9 and uppercase A-Z). Example: 5770ST1
| Version | CHAR(6) |
The data in the version field is not validity
checked. To conform with the system, the version field should be specified as one of the
following formats:
| VxRyMz | Where x is any numeric character 0 through 9, y is any numeric
character 0 through 9, and z is any numeric character 0 through 9 or uppercase letter
A through Z. For example, V7R2M0 is
version 7, release 2, modification 0. |
| vvrrmm | Where vv are any numeric characters 00 through 35 representing the version
of the product, rr are any numeric characters 00 through 35 representing the release of the
product, and mm can be 00 through 09 or 0A through 0Z representing the modification of the
product. For example, 110300 is version 11, release 3, modification 0. This format must be used
if the version or release of the product is greater than 9.
With this format the 'V', 'R' and 'M' characters are not included in the key data.
The version shown on the Display Object Description panel and returned by object-related APIs
include the 'V', 'R' and 'M' characters. |
Object control level. The object control level for the object. IBM programs will have an 8-character decimal value.
Product option ID. Identifies part of a licensed program (product). Products can have multiple options. Objects that are a part of an IBM licensed program must be 0000 (*BASE) through 0099. If you want to conform with the system, this format should be followed.
Product option load ID. The language identifier associated with the object. Objects that are a part of an IBM licensed program must have one of the allowed languages in the 29xx format. If you want to conform with the system, this format should be followed.
Program temporary fix. The program temporary fix (PTF) that resulted in the creation of the object. For IBM objects the first 2 characters are a prefix ID, and the remaining 5 characters are the program change ID (decimal). The field is blank if the object was not changed because of a PTF. If you want to conform with the system, this format should be followed.
Reset days used count and update days used count reset date. This key is used to:
- Reset the number of days an object has been used on the system.
- Update the date the days used count was last reset to 0.
It must have a value of '0' or '1'.
| '0' | Neither the days used count nor the days used count reset date shown on the Display Object Description panel is updated. |
| '1' | The days used count is set to 0. The days used count
reset date shown on the Display Object Description panel is updated to the current
system date.
Note: For a database file, the days used count is reset and the days used count reset date is updated for all members in the file. |
This key (11) and key 15 (update last used date and days used count) cannot both be specified with a value of '1'. These keys are incompatible because key 11 will change the days used count to 0 and key 15 will increase the days used count. If both keys 11 and 15 are specified with a value of '1', error message CPF21A1 is issued.
This key (11) with a value of '1' and key 17 (reset member's days used count and update member's days used count reset date) cannot both be specified. These keys are incompatible because key 11 will change the days used count for all members in a file and key 17 will change the days used count for a single member. If key 11 with a value of '1' and key 17 are both specified, error message CPF21A1 is issued.
This key cannot be specified for *DOC object types or when object usage information is not updated for the specified object type. Object usage information is not updated for all object types. For more details on usage information, see Detecting unused objects on the system. Use Qp0lSetAttr()--Set Attributes to update this field for *DOC object types. If this key is not allowed for an object type, error message CPF2131 is issued.
Reset member's days used count and update member's days used count reset date. This key is used to:
- Reset the number of days a database file member has been used on the system.
- Update the date that the member's days used count was last reset to 0.
This field must be a valid 10-character file-member name and must be padded with blank characters. No special values are allowed.
Note: This key resets the days used count for a single member only. To reset the days used count for all members in a database file, specify key 11.
This key can be specified only for an object type of *FILE. If the object is not a *FILE object, error message CPF2131 is issued.
This key (17) and key 11 (reset days used count and update days used count reset date) with a value of '1' cannot both be specified. These keys are incompatible because key 11 will change the days used count for all members in a file and key 17 will change the days used count for a single member. If key 11 with a value of '1' and key 17 are both specified, error message CPF21A1 is issued.
This key (17) and key 15 (update last used date and days used count) with a value of '1' cannot both be specified. These keys are incompatible because key 15 will increase the days used count and key 17 will change the days used count to 0 for a member. If key 15 with a value of '1' and key 17 are both specified, error message CPF21A1 is issued.
Source file. The name of the source file used to create the object, the name of the library in which it is located, and the name of the source file member.
| Source file name | CHAR(10) |
| Library name | CHAR(10) |
| Member name | CHAR(10) |
Objects created with IBM products have valid object names for the qualified source file name. If you want to conform with the system, this format should be followed.
Source file date and time. The date and time the member in the source file was last updated. Objects created with IBM products will be in the CYYMMDDHHMMSS format:
| C | Century, where 0 indicates years 19xx and 1 indicates years 20xx. |
| YY | Year |
| MM | Month |
| DD | Day |
| HH | Hour |
| MM | Minute |
| SS | Second |
If you want to conform with the system, this format should be followed.
System created on. The name of the system where the object was created.
Text. The user-defined text that briefly describes the object and its function.
Update change date and time. Update the date and time the object was last changed. This is useful if you want to update an object's change date and time and do not want to update any other fields or if you want to update the last used date and days used count (key 15) and do not want to update the change date and time.
| '0' | The change date and time is not updated. |
| '1' | The change date and time is updated to the
current system date and time.
Note: For a database file, the change date and time is updated for all members in the file and the file itself. |
This key cannot be specified with any other key except key 15 (update last used date and days used count). If it is, message CPF21A6 is issued.
Update last used date and days used count. This key is used to:
- Update the last used date to the current system date.
- Increase the days used count.
It must have a value of '0' or '1'.
| '0' | The last used date is not updated. The days used count is not increased. |
| '1' | The last used date is updated to the current
system date. If this is the first use of the object today (since midnight), the
days used count is increased.
Note: For a database file, the last used date and days used count are updated for all members in the file. The last used date cannot be changed for a database file that does not have any members. Error message CPF21A2 will be issued. |
This key cannot be specified for *DOC object types or when object usage information is not updated for the specified object type. Object usage information is not updated for all object types. For more details on usage information, see Detecting unused objects on the system. Use Qp0lSetAttr()--Set Attributes to update this field for *DOC object types. If this key is not allowed for an object type, error message CPF2131 is issued.
This key (15) and key 11 (reset days used count and update days used count reset date) cannot both be specified with a value of '1'. These keys are incompatible because key 11 will change the days used count to 0 and key 15 will increase the days used count. If keys 11 and 15 are both specified with a value of '1', error message CPF21A1 is issued.
This key (15) with a value of '1' and key 17 (reset member's days used count and update the member's days used count reset date) cannot both be specified. These keys are incompatible because key 15 will increase the days used count and key 17 will change the days used count to 0 for a member. If key 15 with a value of '1' and key 17 are both specified, error message CPF21A1 is issued.
User-defined attribute. An attribute you define. This should not be confused with the extended attribute of the object. The extended attribute is set by the system when an object is created.
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF21A1 E | Key &1 not allowed with key &2. |
| CPF21A2 E | Last used date for &1 in &2 type *FILE cannot be changed. |
| CPF21A6 E | Cannot specify key &1 with other specified keys. |
| CPF2131 E | Key &1 not allowed with object type *&2. |
| CPF2150 E | Object information function failed. |
| CPF2151 E | Operation failed for &2 in &1 type *&3. |
| CPF219B E | Cannot change &1 in &2 type *&3. |
| CPF219E E | Object type *&1 not valid external object type. |
| CPF2199 E | &2 not valid for key &1. |
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF2451 E | Message queue &1 is allocated to another job. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3C4D E | Length &1 for key &2 not valid. |
| CPF3C88 E | Number of variable length records &1 is not valid. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF36F7 E | Message queue QSYSOPR is allocated to another job. |
| CPF7000 E | Errors from journaling. |
| CPF7304 E | File &1 in &2 not changed. |
| 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. |
| 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. |
| CPF9811 E | Program &1 in library &2 not found. |
| CPF9812 E | File &1 in library &2 not found. |
| CPF9814 E | Device &1 not found. |
| CPF9815 E | Member &5 file &2 in library &3 not found. |
| CPF9820 E | Not authorized to use library &1. |
| CPF9821 E | Not authorized to program &1 in library &2. |
| CPF9822 E | Not authorized to file &1 in library &2. |
| CPF9825 E | Not authorized to device &1. |
| CPF9830 E | Cannot assign library &1. |
| CPF9831 E | Cannot assign device &1. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
API introduced: V2R2
[ Back to top | Object APIs | APIs by category ]