RETURN-ELEMENT

Provided that the user has reserved the base specified for the target version in the output library, the RETURN-ELEMENT statement copies members of a source library into the output library, deletes the members from the source library and then releases the reservations in the output library.

For the first version of a member, no base yet exists. In this case, RETURN-ELEMENT requires administer authorization.

The source and target member base types may differ if text members are returned.

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 operation. This record is written as the first record of its record type and is followed by the comment record containing the text specified for COMMENT. Any comment records which already existed are copied after it. If, in addition, the member is written to the base of a different version (i.e. not the first version under a name), all the rights of the base version are applied to the new version. STATE is set to FREE for both versions. The CCSN is adopted from the source file. The USER-DATE is determined anew.

RETURN-ELEMENT

ELEMENT = *LIB RARY -ELEM ENT (...)
	*LIBRARY-ELEMENT(...)
		|	LIBRARY = *STD / <filename 1..54 without-vers> / *LINK(...)
		|		*LINK(...)
		|			|	LINK-NAME = <structured-name 1..8>
		|	,ELEMENT = *ALL(...) / <composed-name 1..64 with-under with-wild(132)>(...)
		|		*ALL(...)
		|			|	VERSION = *HIGH EST -EXIST ING / *UPPER-LIMIT /
		|			|		<composed-name 1..24 with-under>
		|			|	,BASE = *STD / <composed-name 1..24 with-under with-wild>
		|		<composed-name 1..64 with-under with-wild(132)>(...)
		|			|	VERSION = *HIGH EST -EXIST ING / *UPPER-LIMIT /
		|			|		<composed-name 1..24 with-under>
		|			|	,BASE = *STD / <composed-name 1..24 with-under with-wild>

	|	,TYPE = *LMS-DEF AULT / *ALL / <alphanum-name 1..8 with-wild(20)>
	|	,USER-DATE = *ANY / *TODAY / <date 8..10 with-compl> / *INTERVAL(...)
	|		*INTERVAL(...)
	|			|	FROM = 1900-01-01 / <date 8..10 with-compl>
	|			|	,TO = *TODAY / <date 8..10 with-compl>
	|	,CREATION-DATE = *ANY / *TODAY / <date 8..10 with-compl> / *INTERVAL(...)
	|		*INTERVAL(...)
	|			|	FROM = 1900-01-01 / <date 8..10 with-compl>
	|			|	,TO = *TODAY / <date 8..10 with-compl>
	|	,MODIFICATION-DATE = *ANY / *TODAY / <date 8..10 with-compl> / *INTERVAL(...)
	|		*INTERVAL(...)
	|			|	FROM = 1900-01-01 / <date 8..10 with-compl>
	|			|	,TO = *TODAY / <date 8..10 with-compl>
	|	,EXCEPT-ELEMENT = *NONE / *ELEMENT(...)
	|		*ELEMENT(...)
	|			|	ELEMENT = *ANY (...) / <composed-name 1..64 with-under with-wild(132)>(...)
	|			|		*ANY(...)
	|			|			|	VERSION = *ANY / *HIGHEST-EXISTING / *UPPER-LIMIT /
	|			|			|		<composed-name 1..24 with-under>
	|			|			|	,BASE = *STD / <composed-name 1..24 with-under with-wild>
	|			|		<composed-name 1..64 with-under with-wild(132)>(...)
	|			|			|	VERSION = *ANY / *HIGHEST-EXISTING / *UPPER-LIMIT /
	|			|			|		<composed-name 1..24 with-under>
	|			|			|	,BASE = *STD / <composed-name 1..24 with-under with-wild>
	|			|	,TYPE = *ANY / *LMS-DEFAULT / <alphanum-name 1..8 with-wild(20)>
	|			|	,USER-DATE = *ANY / *TODAY / <date 8..10 with-compl> / *INTERVAL(...)
	|			|		*INTERVAL(...)
	|			|			|	FROM = 1900-01-01 / <date 8..10 with-compl>
	|			|			|	,TO = *TODAY / <date 8..10 with-compl>

		|			|	,CREATION-DATE = *ANY / *TODAY / <date 8..10 with-compl> / *INTERVAL(...)
		|			|		*INTERVAL(...)
		|			|			|	FROM = 1900-01-01 / <date 8..10 with-compl>
		|			|			|	,TO = *TODAY / <date 8..10 with-compl>
		|			|	,MODIFICATION-DATE = *ANY / *TODAY / <date 8..10 with-compl> / *INTERVAL(...)
		|			|		*INTERVAL(...)
		|			|			|	FROM = 1900-01-01 / <date 8..10 with-compl>
		|			|			|	,TO = *TODAY / <date 8..10 with-compl>
,TO-ELEMENT = *LIB RARY -ELEM ENT (...)
	*LIBRARY-ELEMENT(...)
		|	LIBRARY = <filename 1..54 without-vers> / *LINK(...)
		|		*LINK(...)
		|			|	LINK-NAME = <structured-name 1..8>
		|	,ELEMENT = *BY-SOUR CE (...) / <composed-name 1..132 with-under with-wild-constr>(...)
		|		*BY-SOURCE(...)
		|			|	VERSION = *INCR EMENT / *LMS-DEFAULT / *BY-SOURCE / *HIGHEST-EXISTING /
		|			|					*UPPER-LIMIT / <composed-name 1..24 with-under>
		|			|	,BASE = *STD / <composed-name 1..24 with-under with-wild>
		|		<composed-name 1..132 with-under with-wildcard-constr>(...)
		|			|	VERSION = *INCR EMENT / *LMS-DEFAULT / *BY-SOURCE / *HIGHEST-EXISTING /
		|			|					*UPPER-LIMIT / <composed-name 1..24 with-under>
		|			|	,BASE = *STD / <composed-name 1..24 with-under with-wild>
		|	,TYPE = *BY-SOUR CE / *LMS-DEFAULT / <alphanum-name 1..20 with-wild-constr>
		|	,USER-DATE = *BY-SOUR CE / *TODAY / <date 8..10 with-compl>
		|	,STORAGE-FORM = *LMS-DEF AULT / *STD / *FULL / *DELTA
,COMMENT = *BY-SOUR CE / <c-string 1..72 with-low>
,WRITE-MODE = *LMS-DEF AULT / *CREATE / *REPLACE / *ANY
,DIALOG-CONTROL = *LMS-DEF AULT / *NO / *YES / *ERROR

ELEMENT = *LIBRARY-ELEMENT(...)

Specifications for the desired member designation(s).

LIBRARY = *STD / <filename 1..54 without-vers> / *LINK(...)
Specifies the library containing the relevant members.

LIBRARY = <filename 1..54 without-vers>
Name of the library.

LIBRARY = *STD
The library opened by OPEN-LIBRARY.

LIBRARY = *LINK(...)
The library assigned by means of the link name.

LINK-NAME = <structured-name 1..8>
Link name of the library.

ELEMENT = *ALL / <composed-name 1..64 with-under with-wild(132)>(...) Names of the members to be returned.

VERSION = *HIGHEST-EXISTING / *UPPER-LIMIT /
<composed-name 1..24 with-under>
Version of the members to be returned.

VERSION = *HIGHEST-EXISTING
Returns the member with the highest existing version with reference to BASE.

VERSION = *UPPER-LIMIT
Returns the highest possible version X’FF’ with the specified TYPE and name in the library.

VERSION = <composed-name 1..24 with-under>
A 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)> The type of the members which are to be returned.

USER-DATE = *ANY / *TODAY / <date 8..10 with-compl> / *INTERVAL(...)Date given by the user.

USER-DATE = *ANY
Returns members without regard to this date.

USER-DATE = *TODAY
Returns only members with the current date.

USER-DATE = <date 8..10 with-compl>

Returns only members with the specified date.

USER-DATE = *INTERVAL(...)
Returns only members with a user date which falls within the specified interval.

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 which are to be excluded from the above selection.

EXCEPT-ELEMENT = *NONE
No members are to be excluded.

EXCEPT-ELEMENT = *ELEMENT(...)
Specifies the members that are to be excluded. 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 where and under what name the member is to be copied.

LIBRARY = <filename 1..54 without-vers> / *LINK(...)
Specifies the library into which the member is to be copied.

LIBRARY = <filename 1..54 without-vers>
Name of the library into which the member is to be copied. If the library does not yet exist, it is created.

LIBRARY = *LINK(...)
The library assigned by means of the link name.

LINK-NAME = <structured-name 1..8>
Link name of the library.

ELEMENT = *BY-SOURCE(...) / <composed-name 1..132 with-under with-wild-constr>(...)

Name to be given to the target member.

ELEMENT = *BY-SOURCE(...)
The target member is given the same name as the source member.

VERSION = *INCREMENT / *LMS-DEFAULT / *BY-SOURCE /
*HIGHEST-EXISTING / *UPPER-LIMIT / <composed-name 1..24 with-under>Version which the target member is to receive.

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.

VERSION = *BY-SOURCE
The target member is given the same version as the source member.

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 = *UPPER-LIMIT
The highest possible version X’FF’ is generated.

VERSION = <composed-name 1..24 with-under>
The target member receives the version specified here.

BASE = *STD / <composed-name 1..24 with-under with-wild>
Defines the base for the target member. If BASE=*STD applies, the version held by the user is the base version (in the event of ambiguity, an error message is issued).

ELEMENT = <composed-name 1..132 with-under with-wild-constr>(...) Specifies the name which the target member is to receive. The name may also be entered with wildcards.

VERSION = *INCREMENT / *LMS-DEFAULT / *BY-SOURCE /
*HIGHEST-EXISTING / *UPPER-LIMIT / <composed-name 1..24 with-under>Version which the target member is to receive. For a description of the operands, see above.

BASE = *STD / <composed-name 1..24 with-under with-wild>
Defines the base for the target member.

TYPE = *BY-SOURCE / *LMS-DEFAULT /
<alphanum-name 1..20 with-wildcard-constr>
Type which the target member is to receive.

TYPE = *BY-SOURCE

The target member is given the same type designation as the source member.

USER-DATE = *BY-SOURCE / *TODAY / <date 8..10 with-compl>
Date given by the user.

USER-DATE = *BY-SOURCE
The new member is given the same date as the source 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 / *STD /*FULL / *DELTA
Storage form for the member being generated. 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 = *STD
The member is generated in accordance with the storage form required for the member scope. Contradictory requirements result in errors. If nothing is specified, 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.

COMMENT = *BY-SOURCE / <c-string1..72 with-low>
For the specification of a comment text.

COMMENT = *BY-SOURCE
Adopts the comment text from the source member.

COMMENT = <c-string 1..72 with-low>
Comment text which is to be inserted in the target member. The comment text of the source is also retained.

WRITE-MODE = *LMS-DEFAULT / *CREATE / *REPLACE / *ANY
Controls overwriting.

WRITE-MODE = *CREATE

The new member must not yet exist and is created as a new member.

WRITE-MODE = *REPLACE
The new member already exists and is replaced.

WRITE-MODE = *ANY
The new 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 MODIFY-LMS-DEFAULTS statement.

Statement return code

(SC2)	SC1	Maincode	Meaning
2	0 0 1 32 64 64 64 64 64 64 64 64 64 64 64 64 64 64 64 130 130 130 130	CMD0001 LMS0129 CMD0230 LMS1002 LMS0020 LMS0213 LMS0214 LMS0302 LMS0509 LMS0510 LMS1003 LMS1004 PLA0223 PLA0224 PLA0229 PLA0233 PLA0475 PLA0476 PLA0478 LMS0041 LMS0411 LMS0412 LMS0413	No error Statement aborted by user Syntax error Internal error Target member or target file does not exist Name exists as delta member Name exists as full member Member not found Target member or target file already exists Base not found Error during wildcard processing with at least one member or file Other error Only leaves of a delta tree can be overwritten Storage form not allowed No access right for the member Borrow status prevents member access Function violates version automation Version does not match applicable convention Increase causes version overflow System address space exhausted Library locked Member locked Type locked

Required access rights

For ELEMENT:	Read authorization for LIBRARY and ELEMENT
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).

If members are to be stored in delta form, the user must have read authorization 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.

Note

When creating a member, be sure to take into account the convention applicable to the member type. 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 issues an error message.