COPY-ELEMENT copies members and libraries one to one. The copied members may receive new member designations. The source and target member base types may differ if text members are copied.
The following copy options are available:
copying one or more members in the same library
copying one or more members to a different library
copying a complete library (see example on "COPY-ELEMENT")
The copied members can be stored as either non-delta or delta members. If the input library and the output library are the same when copying delta members, the copied delta members must be given new member names. Leaves of delta trees may be overwritten.
The source member can be deleted after copying using DELETE-SOURCE = *YES, thus allowing you to move a member.
Copy with structure (STORAGE-FORM = *BY-SOURCE)
When this format is used, LMS recognizes the form in which members are stored in the PLAM libraries. Correspondingly, delta trees are copied as delta trees and all other members are copied to the output file as non-delta members.
Notes
If the copying process is aborted, the copied part of a delta tree is retained.
VERSION, BASE and all date operands must be set to their default values. The complete name range, i.e. as version=*, is always copied.
Specification of library lists causes errors.
Example
Members A/1 and A/2 are maintained in the library. The statement “Copy member A to B” causes member B/2 to be generated when STORAGE-FORM=*STD is specified, and members B/1 and B/2 when STORAGE-FORM=*BY-SOURCE is specified.
Overwriting the target name range (WRITE-MODE=*SUBSTITUTE)
Specifying WRITE-MODE=*SUBSTITUTE makes the copied member the only member in the target library with its type and name. Before copying the member into the target library, LMS deletes all members having the same type and name as the target member. This means that all user specifications in TO-ELEMENT (such as VERSION = *INCREMENT) are applied only to the empty target name range. If, for example, *INCREMENT is specified, the default version is generated.
Restrictions
The STORAGE-FORM= operand must not have the value *BY-SOURCE.
The input library must not be the same as the output library.
If an error occurs during deletion of the target name range (because, for example, a member is write-protected), the COPY-ELEMENT statement is aborted.
COPY-ELEMENT | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ELEMENT = *LIBRARY-ELEMENT(...)
Specifies the desired member designation.
LIBRARY = *STD / <filename 1..54 without-vers> / *LINK(...)
Specifies the library containing the members to be copied.
LIBRARY = *STD
The library opened by OPEN-LIBRARY.
LIBRARY = <filename 1..54 without-vers>
Name of the library from which the members are to be copied.
LIBRARY = *LINK(...)
The library assigned via the link name.
LINK-NAME = <structured-name 1..8>
Link name of the library; this name was defined by means of a /ADD-FILE-LINK command prior to calling LMS.
ELEMENT = *ALL (...) / <composed-name 1..64 with-under with-wild(132)>(...) Name of the member to be copied.
VERSION = *HIGHEST-EXISTING / *ALL / *UPPER-LIMIT /
<composed-name 1..24 with-under with-wild(52)>
Version of the member to be copied.
VERSION = *HIGHEST-EXISTING
The member with the highest existing version with reference to BASE is copied.
VERSION = *UPPER-LIMIT
The highest possible version X’FF’ in the library under the specified TYPE and name is copied.
VERSION = <composed-name 1..24 with-under with-wild(52)>
The text specified here is interpreted as the version designation.
BASE = *STD / <composed-name 1..24 with-under with-wild>
Prefix for the version selection. In conjunction with VERSION=*HIGHEST-
EXISTING, it is then possible to use a certain prefix to reference the highest existing version. BASE=*STD has the same effect as BASE=*.
TYPE = *LMS-DEFAULT / *ALL / <alphanum-name 1..8 with-wild(20)>Type of the member to be copied.
USER-DATE = *ANY / *TODAY / <date 8..10 with-compl> / *INTERVAL(...)Date given by the user.
USER-DATE = *ANY
The member to be copied has any date.
USER-DATE = *TODAY
The member with the current date is copied.
USER-DATE = <date 8..10 with-compl>
The member whose date is entered explicitly in the form [YY]YY-MM-DD is copied.
USER-DATE = *INTERVAL(...)
All members lying in the specified interval are copied.
FROM = 1900-01-01 / <date 8..10 with-compl>
Beginning of interval.
TO = *TODAY / <date 8..10 with-compl>
End of interval.
CREATION-DATE = *ANY / *TODAY / <date 8..10 with-compl> / *INTERVAL(...)Creation date of the member. For a description of the operands, see the USER-DATE operand of this statement.
MODIFICATION-DATE = *ANY / *TODAY / <date 8..10 with-compl> / *INTERVAL(...) Date of the last modification to the member. For a description of the operands, see the USER-DATE operand of this statement.
EXCEPT-ELEMENT = *NONE / *ELEMENT(...)
Specifies the members to be excluded from the above selection.
EXCEPT-ELEMENT = *NONE
No members are excluded from copying.
EXCEPT-ELEMENT = *ELEMENT(...)
Specifies the members that are to be excluded from copying. A member is excluded when all the fields of the EXCEPT-ELEMENT structure that are not set to *ANY identify the member as a hit. If all the fields of the EXCEPT-ELEMENT structure are set to *ANY, then all members will be excluded.
For a description of the operands, see the *LIBRARY-ELEMENT operand of this statement.
TO-ELEMENT = *LIBRARY-ELEMENT(...)
Specifies the destination and name under which the member is to be added.
LIBRARY = *STD / *BY-SOURCE / <filename 1..54 without-vers> / *LINK(...) Specifies the new library name or library to which the member is to be added.
LIBRARY = *STD
The library opened by OPEN-LIBRARY.
LIBRARY = *BY-SOURCE
The member is copied to the library which contains the member being copied.
LIBRARY = <filename 1..54 without-vers>
Name of the library to which the file is to be added as a member. If the library does not yet exist, it will be created.
LIBRARY = *LINK(...)
The library assigned via the link name.
LINK-NAME = <structured-name 1..8>
Link name of the library; this name was defined by means of a /ADD-FILE-LINK command prior to calling LMS.
ELEMENT = *BY-SOURCE(...) /
<composed-name 1..132 with-under with-wild-constr>(...)
Name that the new member to be added is to receive.
ELEMENT = *BY-SOURCE(...)
The new name is the same as the old name.
VERSION = *LMS-DEFAULT / *BY-SOURCE / *HIGHEST-EXISTING /
*INCREMENT / *UPPER-LIMIT /
<composed-name 1..52 with-under with-wild-constr>
Version that the new member to be added is to receive.
VERSION = *BY-SOURCE
The new member receives the same version as the original member. If the original member has no version specification, the new member receives X’FF’ as the version specification.
VERSION = *HIGHEST-EXISTING
Depending on the convention applicable for the type, this overwrites the highest existing version with reference to BASE among the members of the same type and name; otherwise a default version is generated.
VERSION = *INCREMENT
Depending on the convention applicable for the type, this generates a new, higher version among existing members having the same type and name; otherwise a default version is generated (see also section "Version conventions" (4.6.3 Version conventions)).
VERSION = *UPPER-LIMIT
The highest possible version X’FF’ is generated.
VERSION = <composed-name 1..52 with-under with-wild-constr>
The new member receives the version specified here.
BASE = *STD / <composed-name 1..24 with-under with-wild>
Defines the base for the target member. For further information concerning specification of the base, see "Version designations".
ELEMENT = <composed-name 1..132 with-under with-wild-constr>(...) Name of the new member to be added. It can also be entered using wildcards.
VERSION = *LMS-DEFAULT / *BY-SOURCE / *HIGHEST-EXISTING / *INCREMENT / *UPPER-LIMIT / <composed-name 1..52 with-under with-wild-constr>
Version that the new member to be added is to receive.
For description of operands, see above.
BASE = *STD / <composed-name 1..24 with-under with-wild>
Prefix for the version selection. In conjunction with VERSION=*HIGHEST-
EXISTING, it is then possible to use a certain prefix to reference the highest existing version. BASE=*STD has the same effect as BASE=*. For further information concerning specification of the base, see "Version designations".
TYPE = *BY-SOURCE / *LMS-DEFAULT / <alphanum-name 1..20 with-wild-constr>Type that the new member to be added is to receive.
TYPE = *BY-SOURCE
The new member receives the same type designation as the original member.
USER-DATE = *BY-SOURCE / *TODAY / <date 8..10 with-compl>
Date given by the user.
USER-DATE = *BY-SOURCE
The new member receives the same date as the original member.
USER-DATE = *TODAY
The current date is given.
USER-DATE = <date 8..10 with-compl>
The date must be entered in the form [YY]YY-MM-DD.
STORAGE-FORM = *LMS-DEFAULT / *BY-SOURCE / *STD / *FULL / *DELTA
Storage form for the member being created. The storage form must not contradict the settings made by means of the MODIFY-TYPE-ATTRIBUTES or MODIFY-LIBRARY-ATTRIBUTES statements, and all members of a given type and name must have the same storage form.
STORAGE-FORM = *BY-SOURCE
VERSION, BASE and all date operands must be set to their default values. The complete name range, i.e. as version=*, is always copied.
The member being added is copied with the same structure, i.e. delta trees are again stored as such and full members are copied as full members. If delta trees are copied with the same structure, the target name must not yet exist in the target type (i.e. WRITE-MODE has no effect).
STORAGE-FORM = *STD
The member is generated in accordance with the storage form required for the member scope. Contradictory requirements result in errors. If nothing special is required, full storage is selected.
STORAGE-FORM = *FULL
The new member is generated as a full member (if this is not possible, an error message is issued).
STORAGE-FORM = *DELTA
The new member is generated as a delta member (if this is not possible, an error message is issued). This entry is permissible for member types: S, P, D, J, M, X and members types derived from them.
PROTECTION = *LMS-DEFAULT / *STD / *BY-SOURCE
Member protection for the copied member.
PROTECTION = *STD
If the member already exists, the member protection remains unchanged. If the member does not yet exist and if an initial member protection is defined for the library or type of member, then the copied member will receive this protection.
PROTECTION = *BY-SOURCE
The copied member receives the same protection as the original member.
DELETE-SOURCE = *NO / *YES
Here the user can specify whether the source member is to be kept, or whether it is to be deleted.
DELETE-SOURCE = *NO
The source member is not deleted.
DELETE-SOURCE = *YES
The source member is deleted.
WRITE-MODE = *LMS-DEFAULT / *CREATE / *REPLACE / *EXTEND / *SUBSTITUTE / *ANY
Overwriting of a member having the same name. If the member does not exist under this name, it will be created as a new member.
If the member to be stored is a delta member, it is necessary to ensure that the member is a leaf of the delta tree. Only leaves of a delta tree may be overwritten.
WRITE-MODE = *CREATE
The target member must not yet exist and is created as a new member.
WRITE-MODE = *REPLACE
The target member must already exist and is then replaced.
WRITE-MODE = *EXTEND
The target member is extended if it already exists. Otherwise, it will be created as a new member. *EXTEND is not permitted for delta members,
WRITE-MODE = *SUBSTITUTE
All members having the same type and name as the source member are deleted from the target library. The source member is then copied into the library.
WRITE-MODE = *ANY
The target member is replaced if it already exists. Otherwise it will be created as a new member.
DIALOG-CONTROL = *LMS-DEFAULT / *NO / *YES / *ERROR
This operand determines whether or not a dialog is to be conducted with the user during execution of a statement.
For more detailed information on dialog control, see the DIALOG-CONTROL operand of the MODIFY-LMS-DEFAULTS statement.
Statement return code
(SC2) | SC1 | Maincode | Meaning |
| 0 | CMD0001 | No error |
Required access rights
For LIBRARY-ELEMENT: read authorization for LIBRARY and ELEMENT
If more than one member is affected by the statement, members without read authorization are excluded from the statement.
When copying deltas with STORAGE-FORM=*BY-SOURCE, the delta tree will only be copied if read authorization exists for all its members.
For TO-ELEMENT: Read and write authorization for LIBRARY
Administer authorization where the specified member designation is new. Otherwise, only write authorization for the member existing under the specified member designation (administer authorization no longer required).
For STORAGE-FORM=*DELTA, read authorization must be granted for the member defined by BASE.
If WRITE-CONTROL is active and a base version exists, the USERID of the user must be entered as the HOLDER of the member specified by BASE. Only if write authorization has been granted can a new version be generated or this base version overwritten. In this case, administer authorization is no longer required.
If PROTECTION=*BY-SOURCE is specified, only the owner of the library file can use this functionality.
Notes
When creating a member, be sure to observe the convention applicable to the type of member involved. Especially when the target type has the convention STD-TREE, problems can occur if the source side contains side branch versions whose main branch version is deleted. In this case, the affected side branches cannot be copied; LMS does issue an error message, however.
Exception: copying a complete delta tree with STORAGE-FORM=*BY-SOURCE is always possible.
STATE and HOLDER of the source member are not applied to the target member even with PROTECTION=*BY-SOURCE.
If WRITE-CONTROL is active in the output library, the access method adds a comment (record type 2) to the member which is to be written. The comment logs the HOLDER, DATE and TIME of the process. The record is written as the first record of the record type. Any existing comment records are copied after this first record. If, in addition, the member is written to the base of a different version (i.e. not the first version under a name), the member attributes STATE and HOLDER and all the rights of the base version are applied to the new version. The CCSN is adopted from the source file. The USER-DATE is determined anew.
Examples with WRITE-MODE=*SUBSTITUTE
Input library X contains the S-type member A/1. Output library Y contains the S-type member A/2.
//COPY-ELEM ELEMENT= *LIB(LIB=X,ELEM=A,TYPE=S),-TO ELEMENT= *LIB(LIB=Y),WRITE-MODE=*SUBSTITUTEFollowing this statement, member A/1 is the only member of type S and name A existing in the output library. Member A/2 has been deleted.
All the members of a product version are located in input library X. These members are to be copied into an existing output library Y in such a way that, after the copying process is concluded, Y contains only the copied product version and no other version. This can be done with the following statement.
//COPY-ELEM ELEMENT= *LIB(LIB=X,ELEM=*,TYPE=*),-TO ELEMENT= *LIB(LIB=Y),WRITE-MODE=*SUBSTITUTE
Example of how to copy an entire library
Library lib1 is copied in its entirety and is given the name lib2. By specifying ’*’ for member and type, no knowledge is required of the members contained, i.e. all members are copied one to one to the newly created library lib2.
/START-LMS
//OPEN-LIBRARY LIB1
//SHOW-ELEMENT-ATTRIBUTES
INPUT LIBRARY= :1OSQ:$USER.LIB1
TYP NAME VER (VAR#) DATE NAME VER (VAR#) DATE
(D) LETTER.A @ (0001) 2011-04-12 TESTELEM @ (0001) 2011-04-12
2 (D)-ELEMENT(S) IN THIS TABLE OF CONTENTS
TYP NAME VER (VAR#) DATE
(S) TEST3 @ (0001) 2011-04-12
1 (S)-ELEMENT(S) IN THIS TABLE OF CONTENTS
--------------------------------------------------------------------------
3 ELEMENT(S) IN THIS TABLE OF CONTENTS
//COPY-ELEMENT (,ELEM=*,TYPE=*),TO-ELEM=*LIB(LIBRARY=LIB2)
//SHOW-LIBRARY-STATUS
STATUS FILENAME MODE LINK DEF-TYPE
OPEN :1OSQ:$USER.LIB2
OPEN :1OSQ:$USER.LIB1 READ
//SHOW-ELEMENT-ATTRIBUTES *LIB(LIBRARY=LIB2)
INPUT LIBRARY= :N:$USER.LIB2
TYP NAME VER (VAR#) DATE NAME VER (VAR#) DATE
(D) LETTER.A @ (0001) 2011-04-12 TESTELEM @ (0001) 2011-04-12
2 (D)-ELEMENT(S) IN THIS TABLE OF CONTENTS
TYP NAME VER (VAR#) DATE
(S) TEST3 @ (0001) 2011-04-12
1 (S)-ELEMENT(S) IN THIS TABLE OF CONTENTS
--------------------------------------------------------------------------
3 ELEMENT(S) IN THIS TABLE OF CONTENTS
//END