Change Object Description (QLICOBJD) API

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 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 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 stamp (date and time the object was changed) field is also updated unless you also specify that the change date and time stamp field is not to be updated. You can only specify that the change date and time stamp 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, a journal entry (type ZB) is 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. If an error occurred while the API was accessing the object, blanks are returned.

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 the External object types information.

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.

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

• Allow change by program
• Days used count and reset date
• Last used date
  
• Change date and time stamp

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.

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

Change date and time stamp. The date and time the object was last changed. This is useful if you want to update an object's change date and time stamp and do not want to update any other fields or if you want to update the last used date (key 15) and do not want to update the change date and time stamp.

This key cannot be specified with any other key except key 15 (last used date). If it is, message CPF21A6 is issued.

Note: For database files, the last change date/time is updated for all members in the file and the file itself.

Compiler. The name, version level, release level, and modification level of the compiler. Objects created with IBM products will have the licensed program name of the compiler in the compiler name field and a version field in the VxRxMy format where x must be 0-9 and y must be 0-9 or A-Z. If you want to conform with the system, this format should be followed.

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.

Days used count and 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'.

This key (11) and the last used date (key 15) 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 the member's days used count (key 17) 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 the Detect unused objects on the system information. Use the Set Attributes Qp0lSetAttr() API to update this field for *DOC object types. If this key is not allowed for an object type, error message CPF2131 is issued.

Note: For database files, the days used count reset date and the days used count are updated for all members in the file.

Last used date. 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'.

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 the Detect unused objects on the system information. Use the Set Attributes Qp0lSetAttr() API to update this field for *DOC object types. If this key is not allowed for an object type, error message CPF2131 is issued.

Note: For database files, the last used date and number of 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 (15) and the days used count (key 11) 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 the member's last used date (key 17) 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.

Licensed program. The name, version level, release level, and modification level of the licensed program. Objects that are a part of an IBM licensed program have a valid licensed program name (7 characters containing 0-9 and uppercase A-Z). The version is in the VxRxMy format where x must be 0-9 and y must be 0-9 or A-Z. If you want to conform with the system, this format should be followed.

Member's days used count and reset date. This key is used to:

• Reset the number of days a database file member has been used on the system.
• Update the member's date that the 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.

This key (17) and the days used count (key 11) 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 the last used date (key 15) 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.

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.

Note: This key updates 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.

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.

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.

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/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:

If you want to conform with the system, this format should be followed.

Text. The user-defined text that briefly describes the object and its function.

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.