The replace (REPLACE) parameter is used on create commands. It specifies that the existing object, if one exists, is replaced by the object of the same name, library, and object type that is being created.
The user of the new object is granted the same authority as for the object being replaced. If the object being replaced is secured by an authorization list, then the new object is secured by the same authorization list. The public authority of the new object is the same as the public authority of the replaced object. The AUT parameter from the create command is ignored. All private authorities from the replaced object are copied to the new object. The owner of the new object is not copied from the replaced object. The owner of the new object is the creator of the new object or the creator's group profile. Some objects such as panel groups, display files, and menus cannot be replaced if they are in use by the current job or another job.
If the object being created is a program or service program, then the user profile (USRPRF parameter) value from the replaced program is used. The user profile (USRPRF parameter) value from the Create Program (CRTPGM) or Create Service Program (CRTSRVPGM) command is ignored. If the value of the user profile (USRPRF parameter) of the program or service program being replaced is *OWNER, then only the current owner of the program or service program being replaced can create the new program or service program that replaces the existing program or service program. If the owner of the existing object and the object being created do not match, the object is not created and message CPF2146 is sent.
If the object being created is a program or service program, then the use adopted authority (USEADPAUT) value from the replaced program or service program is used as long as the user creating the object can create programs/service programs with the USEADPAUT(*YES) attribute. The QUSEADPAUT system value determines whether or not users can create programs or service programs to use adopted authority. For example, if the existing object being replaced has USEADPAUT(*YES) and you do not have authority to create a program or service program that uses adopted authority, the program or service program created will have USEADPAUT(*NO). In this case, the USEADPAUT value was not copied. If you have authority to create programs or service programs that use adopted authority, the created program or service program will have the same USEADPAUT value as the program or service program being replaced. An informational message is sent which indicates whether the USEADPAUT value was copied to the object being replaced.
If the object being created is a file, and the default, or *YES, is specified on the REPLACE parameter, an existing device file other than save file and a DDM file with the same qualified name will be replaced by the new file. For example, an existing display file can be replaced by a new printer file, or tape file, etc.
Object management (*OBJMGT), object existence (*OBJEXIST), and read (*READ) authorities are required for the existing object to allow replacement of the existing object with a new object.
The existing object is renamed and moved to library QRPLOBJ or library QRPLxxxxx if the object resides on an Independent ASP (where 'xxxxx' is the number of the primary ASP of the ASP group) when the creation of the new object is successful. The replaced object is renamed with a Q appended to a time stamp and moved to library QRPLOBJ or library QRPLxxxxx if the object resides on an Independent ASP. If the existing object could not be moved to the QRPLOBJ library because QRPLOBJ was locked by another job, for example, the existing object will be moved to the QTEMP library for the job. If the existing object could not be moved to the QTEMP library for the job, the existing object will be deleted. If the existing object could not be moved to the QRPLxxxxx library because QRPLxxxxx was locked by another job, for example, the existing object will be deleted.
Programs can be replaced while they are being run; however, if the replaced program refers to the program message queue after the renaming of the replaced program to the Qtimestamp name, the program fails and an error message is sent stating that the program message queue is not found.
A database file, physical or logical, and a save file cannot be replaced by any file.
Library QRPLOBJ is cleared when an initial program load (IPL) of the system is done. Library QRPLxxxxx is cleared when the primary ASP of the ASP group is varied on.