Rename Object (QLIRNMO) API

Required Parameter Group:

1	From qualified object name	Input	Char(20)
2	Object type	Input	Char(10)
3	Target qualified object name	Input	Char(20)
4	Replace object	Input	Char(1)
5	Error code	I/O	Char(*)

Optional Parameter Group 1:

6	From library auxiliary storage pool (ASP) device name	Input	Char(10)
7	Target library auxiliary storage pool (ASP) device name	Input	Char(10)

Default Public Authority: *USE

Threadsafe: Conditional; see Usage Notes.

The Rename Object (QLIRNMO) API renames an existing object to a new object name or moves the object to a different library or both, and optionally replaces the existing target object. This API combines the functions of the Rename Object (RNMOBJ) and the Move Object (MOVOBJ) commands. The API allows you to rename and move in one step, and optionally replace the existing object in the target library.

When the replace object parameter requests to replace an existing object and the target object already exists, the following occur:

The *PUBLIC and private authorities from the target object replace the authorities on the renamed object.
The owner of the object is the owner of the from object.
If the object is not a *PGM object, the target object is deleted.
For a *PGM object, the object is renamed and moved to library QRPLOBJ (or the QRPLxxxxx library if the target object is in a library in primary or secondary auxiliary storage pool 'xxxxx'). If an error occurs with the QRPLOBJ library, the object is moved into the QTEMP library. If an error occurs with the QRPLxxxxx or QTEMP library, the object is deleted. The renamed program will have the same user profile (USRPRF) value as the target program. If the target program has the adopted authority USRPRF(*OWNER) attribute, the owner of the from program must be the same as the owner of the target program. An error message is issued if the owners do not match. For more information about adopted authority, see the Security reference topic collection. The use adopted authority (USEADPAUT) value from the target program is copied to the from program as long as the user who performs the rename operation can create and update programs with the USEADPAUT(*YES) attribute. The QUSEADPAUT system value determines whether or not users can create and update programs to use adopted authority. If the program being replaced has USEADPAUT(*YES) and the user cannot create and update programs to use adopted authority, the USEADPAUT value of the from program remains the same.
For a *CRQD object, the from change request description will have the same user profile (USRPRF) value as the target change request description. If the target change request description has a user profile value of USRPRF(*OWNER), the owner of the from object must be the same as the target object. An error message is issued if the owners do not match.

Restrictions

All restrictions that apply to the Move Object (MOVOBJ) and Rename Object (RNMOBJ) commands also apply to the QLIRNMO API.

Authorities and Locks

Auxiliary Storage Pool (ASP) Device Authority

*USE when a specific ASP device name is specified for optional parameter group 1.

Library Authority

*CHANGE

Note: If you are renaming an object that can only exist in library QSYS, the library authority is not checked.

Object Authority

*OBJMGT

Notes:

Object types of *FILE, *JRN, *JRNRCV, and *MSGQ need *OBJOPR and *OBJMGT authorities.
An object type of *AUTL needs *AUTLMGT authority.

Library Lock

*SHRUPD

Object Lock

*EXCL

If you replace an object, you must be the owner of the from object or have *ALLOBJ special authority. *ALLOBJ authority is needed to replace the authority on the from object.

When the request is to replace an existing object and the target object already exists, the following authority considerations apply:

For *PGM and *CRQD objects, the user must have *OBJEXIST, *OBJMGT, and *READ authorities to the existing target object.
For *FILE objects, the user must have *OBJOPR, *OBJMGT, and *OBJEXIST authorities to the existing target object.
For *AUTL objects, the user must be the owner and have *AUTLMGT authority to the existing target object.
For *LIB and *SBSD objects, the user must have *OBJEXIST, *OBJMGT, and *USE authorities to the existing target object.
For other object types, the user must have *OBJEXIST authority to the existing target object in addition to the other authorities listed under "Object Authority".

Required Parameter Group

From qualified object name

INPUT; CHAR(20)

The object being renamed 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
*LIBL	The thread's library list

Object type

INPUT; CHAR(10)

The type of object being renamed. If the from object and the target object belong to the same library, only a rename operation is done. The object type must be supported on the RNMOBJ command. If the from object and the target object belong to different libraries, a move operation is done. The object type must be supported on the MOVOBJ command. If both a rename and a move operation are done, the object type must be supported on both the RNMOBJ and MOVOBJ commands. An asterisk (*) must precede the object type. For a list of the object types that cannot be moved or renamed, see the Renaming objects and Moving objects from one library to another topics.

Target qualified object name

INPUT; CHAR(20)

The new name of the object and the new library in which it will be located. The object name can be the same name as the original object or a new name. The library name can be the same name as the original library or a new name. If the object name is the same as the original object, the library name must not be the same as the original library unless the target and from library auxiliary storage pool (ASP) device names are not the same. The first 10 characters contain the object name, and the second 10 characters contain the library name.

Replace object

INPUT; CHAR(1)

Whether to replace an existing object with the same name as the target object and library name parameter in the auxiliary storage pool named in the target library auxiliary storage pool (ASP) device name parameter. The following values can be specified:

0	Do not replace the existing object in the target library. If 0 is specified and the target object already exists, an error message is returned to the application.
1	Replace the existing object in the target library.
2	Replace the existing object in the target library. For an existing PGM object, send an informational message which identifies the new name of the object and the target library where it was moved. If the existing PGM object was moved to the QRPLOBJ library (or the QRPLxxxxx library if the target object is in a library in a primary or secondary auxiliary storage pool (ASP) where 'xxxxx' is the number of the primary ASP of the ASP group), informational message CPI2121 is sent. If the existing PGM object was moved to the QTEMP library, informational message CPI2118 is sent. If the existing PGM object was deleted because it could not be moved into the replaced object library or QTEMP, no message is sent.

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error code parameter.

Optional Parameter Group 1

From library auxiliary storage pool (ASP) device name

INPUT; CHAR(10)

The name of the auxiliary storage pool (ASP) device from which storage is allocated for the library containing the object to be renamed or moved. For all operations other than a library rename, the ASP device must have status of 'Available'. For a library rename operation, the ASP device must have a status of 'Active' or 'Available' and the target library auxiliary storage pool (ASP) device and the from library auxiliary storage pool (ASP) device must be the same device. If this parameter is omitted in cases where it is valid for this parameter to have a value other than an asterisk (*), the thread's library name space will be used.

This parameter must be an asterisk (*) if specified when *CURLIB or *LIBL is specified as the library name in the from qualified object name parameter. If a library to be renamed is in an auxiliary storage pool (ASP) device that is not currently part of the thread's library name space, specify current-library-name in the first 10 characters and QSYS in the second 10 characters of the from qualified object name and the auxiliary-storage-pool-device-name in the from library auxiliary storage pool (ASP) device name.

One of the following special values may be specified:

*	The ASPs in the thread's library name space.
*CURASPGRP	The ASPs in the thread's ASP group.
*SYSBAS	The system ASP (1) and defined basic user ASPs (2-32).

Target library auxiliary storage pool (ASP) device name

INPUT; CHAR(10)

The name of the auxiliary storage pool (ASP) device from which storage is allocated for the library to contain the object after the rename or move. For all operations other than a library rename, the ASP device must have status of 'Available'. For a library rename operation, the ASP device must have a status of 'Active' or 'Available' and the target library auxiliary storage pool (ASP) device and the from library auxiliary storage pool (ASP) device must be the same device. If this parameter is omitted, the thread's library name space will be used.

If a library to be renamed is to be in an auxiliary storage pool (ASP) device that is not currently part of the thread's library name space, specify new-library-name in the first 10 characters and QSYS in the second 10 characters of the target qualified object name and specify either *SAME or an auxiliary-storage-pool-device-name in the target library auxiliary storage pool (ASP) device name that is the same as specified in the from library auxiliary storage pool (ASP) device name.

One of the following special values may be specified:

*	The ASPs in the thread's library name space.
*SAME	The library to which the object will be renamed or moved is in the same ASP as the library containing the object to be renamed or moved.
*CURASPGRP	The ASPs in the thread's ASP group.
*SYSBAS	The system ASP (ASP 1) and defined basic user ASPs (ASPs 2-32).

Usage Notes

This API is conditionally threadsafe. For multithreaded jobs, see the restrictions in the Rename Object (RNMOBJ) command.

Error Messages

Message ID	Error Message Text
CPFB8ED E	Device description &1 not correct for operation.
CPF180B E	Function &1 not allowed.
CPF21A3 E	&1 not valid for replace object option.
CPF21A4 E	Objects cannot be moved into QTEMP.
CPF21A5 E	Cannot replace object &1 in &2 type *&3.
CPF2111 E	Library &1 already exists.
CPF2112 E	Object &1 in &2 type *&3 already exists.
CPF2132 E	Object &1 already exists in library &2.
CPF2136 E	Renaming library &1 failed.
CPF2139 E	Rename of library &1 failed.
CPF2140 E	Rename of library &1 previously failed.
CPF2146 E	Owner of object &1 and object being replaced not the same.
CPF2160 E	Object type *&1 not eligible for requested function.
CPF2164 E	Rename of library &2 not complete.
CPF2166 E	System library cannot be renamed or deleted.
CPF2173 E	Value for ASPDEV not valid with special value for library.
CPF2176 E	Library &1 damaged.
CPF218C E	&1 not a primary or secondary ASP
CPF2183 E	Object &1 cannot be moved into library &3.
CPF2189 E	Not authorized to object &1 in &2 type *&3.
CPF219E E	Object type *&1 not valid external object type.
CPF2193 E	Object &1 cannot be moved into library &4.
CPF22BC E	Object &1 type &3 is not program defined.
CPF24B4 E	Severe error while addressing parameter list.
CPF2512 E	Operation not allowed for message queue &1.
CPF2691 E	Rename of &2 type *&5 did not complete.
CPF2692 E	Object &2 type *&5 must be varied off.
CPF2693 E	&2 type *&5 cannot be used for rename.
CPF2694 E	Object &2 type *&5 cannot be renamed.
CPF3C3A E	Value for parameter &2 for API &1 not valid.
CPF3C90 E	Literal value cannot be changed.
CPF3CF1 E	Error code parameter not valid.
CPF3200 E	All CPF32xx messages could be returned. xx is from 01 to FF.
CPF7010 E	Object &1 in &2 type *&3 already exists.
CPF88C4 E	Value &1 for new object is more than 8 characters.
CPF9801 E	Object &2 in library &3 not found.
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.
CPF9809 E	Library &1 cannot be accessed.
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.
CPF9820 E	Not authorized to use library &1.
CPF9821 E	Not authorized to program &1 in library &2.
CPF9825 E	Not authorized to device &1.
CPF9830 E	Cannot assign library &1.
CPF9831 E	Cannot assign device &1.
CPF9833 E	CURASPGRP or ASPGRPPRI specified and thread has no ASP group.
CPF9872 E	Program or service program &1 in library &2 ended. Reason code &3.

API introduced: V2R3

[ Back to top | Object APIs | APIs by category ]