Copy Library (CPYLIB)

The Copy Library (CPYLIB) command copies the contents of a library to a new library. If the new library does not exist, the command optionally creates it before the copy.

All copied objects are created in the same auxiliary storage pool (ASP) as the new library. Any objects that already exist in the new library remain in the new library after the new objects are copied.

Note: If the new library is created by this command:

• The new library is created in the same ASP as the existing library.
• The library type, create authority and create object auditing values of the existing library are copied to the new library.
• The public authority of the new library is the same as the create authority for the QSYS library. The create authority for the QSYS library can be displayed by using the Display Library Description (DSPLIBD) command. If the create authority for the QSYS library is changed with the Change Library (CHGLIB) command after the new library is created, the new authority will not affect the public authority for the new library.
• The private authorities for the existing library are not copied to the new library.
• You can use the Grant Object Authority (GRTOBJAUT) command specifying the existing library for the Reference object (REFOBJ) parameter to copy authorities from the existing library to the new library.
• The owner of the new library is either the user profile of the user who issues the command or the group profile if the user profile of the user who issues the command is a member user profile that has specified that the group profile should be the owner.
• The new library is not secured by an authorization list even if the existing library was secured by an authorization list.
• The journal inherit rules for the existing library are not copied to the new library.

  Use the Display Library Description (DSPLIBD) command to display journal information for the library. Refer to the Start Journal Library (STRJRNLIB) command for more information about journaling a library.

Restrictions:

• Only object types supported by the Create Duplicate Object (CRTDUPOBJ) command can be copied. The restrictions for the CRTDUPOBJ command also apply to this command.
• If this command is interrupted prior to completion, the results are unpredictable.
• If another job is processing any of the objects in the library specified for the Existing library (FROMLIB) parameter, the results may be unpredictable. For example:
  • Objects created in the existing library after the copy starts are not copied.
  • If objects are deleted from the existing library after the copy starts, a user of this command gets an error message.
  • If objects in the existing library are in use or are locked by another job, the copy may not be successful.
• Other jobs should not attempt to use objects in the library specified for the New library (TOLIB) parameter until the copy is complete.

Parameters

Existing library (FROMLIB)

Specifies the existing library to be copied.

This is a required parameter.

name

Specify the name of the existing library to be copied.

New library (TOLIB)

Specifies the new library to which objects will be copied from the existing library.

This is a required parameter.

name

Specify the name of the library to which objects will be copied.

Create library (CRTLIB)

Specifies whether the new library should be created.

*YES

The new library will be created by this command before the contents of the existing library are copied to it. If the new library already exists, an error message will be issued.

*NO

The new library should not be created. If the new library does not exist, an error message will be issued.

Duplicate data (DATA)

Specifies whether the data records in database physical files or save files in the existing library are copied to the newly-created object in the new library. Members of physical files are copied whether or not the data contained in them is copied. The specified value is not used for objects which are not database physical files or save files.

*YES

The data records in the members of database physical files or save files in the existing library are copied to the new object in the new library.

Note: The relative record numbers in the new file are the same as those in the original file.

*NO

The data records in the members of database physical files or save files in the existing library are not copied to the new object in the new library.

Duplicate constraints (CST)

Specifies whether any constraints associated with database physical files in the existing library are copied to the newly-created files in the new library. The specified value is not used for objects which are not database physical files.

*YES

The constraints associated with a database physical file in the existing library are copied to the newly-created file in the new library.

*NO

The constraints associated with a database physical file in the existing library are not copied to the newly-created file in the new library.

Duplicate triggers (TRG)

Specifies whether any triggers associated with database files in the existing library are copied to the newly-created files in the new library. The specified value is not used for objects which are not database files.

Note: There are special considerations of which to be aware relating to the duplication of triggers. For example, the duplication will differ depending on whether or not the trigger program associated with the existing file was in the same library as the existing file. For additional information, see the Database category in the IBM i Information Center at http://www.ibm.com/systems/i/infocenter/.

*YES

The triggers associated with a database file in the existing library are copied to the newly-created file in the new library.

*NO

The triggers associated with a database file in the existing library are not copied to the newly-created file in the new library.

Duplicate file identifiers (FILEID)

Specifies whether the file level and member level identifiers for a database file in the existing library will be used for the newly-created file in the new library. The specified value is not used for objects which are not database files.

*NO

The file level and member level identifiers for a database file in the existing library will not be used for the newly-created file in the new library. The file level and member level identifiers for the newly-created file will be generated by the system; for example, 1070224092922.

*YES

The file level and member level identifiers for a database file in the existing library will be used for the newly-created file in the new library. Having two database files with the same file level and member level identifiers can impact database operations. This value should only be used when an exact duplicate database file is expected.

Duplicate access control (ACCCTL)

Specifies whether any row access controls, or column access controls associated with existing database physical files are copied to the newly-created files in the new library. The specified value is not used for objects which are not database physical files. The duplication of a file with access controls will not change the library name of any files referenced by the row, or column access controls.

*ALL

All the row access controls, and column access controls associated with an existing database physical file are copied to the newly-created file in the new library. If the database file being copied has active permission, or masks and the data parameter DATA(*YES) is specified, the column access controls and the row access controls must be copied.

*ROW

The row access controls associated with an existing database physical file are copied to the newly-created file in the new library. If the database file being copied has active masks and the data parameter DATA(*YES) is specified, the row access controls must be copied.

*COL

The column access controls associated with an existing database physical file are copied to the newly-created file in the new library. If the database file being copied has active permissions and the data parameter DATA(*YES) is specified, the column access controls must be copied.

*NONE

None of the row access controls, or column access controls associated with an existing database physical file are copied to the newly-created file in the new library. If the database file being copied has active permissions, or masks, the data parameter DATA(*NO) must be specified.

Examples

Example 1: Copying the Contents of a Library to a New library After Creating the New Library

CPYLIB   FROMLIB(MYLIB)  TOLIB(NEWLIB)

This command copies the contents of library MYLIB into library NEWLIB after creating library NEWLIB. The data records, constraints, and triggers associated with a database physical file in library MYLIB will be copied to the database physical file created in library NEWLIB. New file level and member level identifiers will be generated for each database file created in library NEWLIB. This means that the file level and member level identifiers for a database file created in library NEWLIB will not be the same as the file level and member level identifiers for the database file in library MYLIB from which it was copied.

Example 2: Copying the Contents of a Library to an Existing Library

CPYLIB   FROMLIB(MYLIBA)  TOLIB(MYLIBB)  CRTLIB(*NO) +
         DATA(*YES)  CST(*NO)  TRG(*NO)  FILEID(*YES)
MONMSG   MSGID(CPF2358)

This command copies the contents of library MYLIBA into existing library MYLIBB. All copied objects are created in the same auxiliary storage pool (ASP) as library MYLIBB. Any objects that already exist in library MYLIBB will not be copied from library MYLIBA and those objects will remain in library MYLIBB after other new objects are copied. The data records in a database physical file in library MYLIBA will be copied to the database physical file created in library MYLIBB. The constraints and triggers associated with a database file in library MYLIBA will not be copied to the database file created in library MYLIBB. The file level and member level identifiers for each database file created in library MYLIBB will be the same as the file level and member level identifiers for the database file in library MYLIBA from which it was copied.

The MONMSG command allows you to ignore escape message CPF2358 which may be signalled if all objects in library MYLIBA cannot be copied to library MYLIBB. One reason an object cannot be copied is if the object already exists in library MYLIBB.

Error messages

*ESCAPE Messages

CPF2358

Library &1 not copied or partially copied.

CPF2365

FROMLIB and TOLIB parameters cannot specify the same library.