PROVIDE-ELEMENT

The PROVIDE-ELEMENT statement reserves members of a source library and makes copies of these members available in an output library. The source library is to be named explicitly. If WRITE-CONTROL is activated, the reserved members are protected against modification by anyone else. If a convention is also set, the entire version space above the specified version is reserved for the holder.

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

PROVIDE-ELEMENT

ELEMENT = *LIB RARY -ELEM ENT (...)
	*LIBRARY-ELEMENT(...)
		|	LIBRARY = <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 = *STD / <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 = *LMS-DEF AULT / *BY-SOURCE / *HIGHEST-EXISTING / *INCREMENT /
		|			|					*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 = *LMS-DEF AULT / *BY-SOURCE / *HIGHEST-EXISTING / *INCREMENT /
		|			|					*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
,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 = <filename 1..54 without-vers> / *LINK(...)
Specifies the library containing the members to be made available.

LIBRARY = <filename 1..54 without-vers>
Name of the 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 made available.

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

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

VERSION = *UPPER-LIMIT
Makes available 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 made available.

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

USER-DATE = *ANY
Makes available members without regard to the date.

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

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

Makes available only members with the specified date.

USER-DATE = *INTERVAL(...)
Makes available 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 USER-DATE.

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 made available.

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

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

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

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 = *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 = *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.

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 = *LMS-DEFAULT / *BY-SOURCE / *HIGHEST-EXISTING /
*INCREMENT / *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-wild-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 copied. 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.

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

WRITE-MODE = *CREATE
The target member must not yet exist and is created as a new member.

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

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 MODIFY-LMS-DEFAULTS statement.

Statement return code

(SC2)	SC1	Maincode	Meaning/Guaranteed messages
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 Read and hold authorization for 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.

Notes

• 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.

• 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 comment records which already exist 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), the member attributes STATE and HOLDER and all the rights of the base version are adopted for the new version. The CCSN is adopted from the source file. The USER-DATE is determined anew.

• The user is entered as the HOLDER of the source member. The source member has the status 'IN-HOLD', so it is no longer possible to issue a PROVIDE-ELEMENT statement for that member until it regains the FREE status. This can be implemented by RETURN-ELEMENT or MODIFY-ELEMENT-ATTRIBUTES.