LMS V3.6 (en)

ADD-ELEMENT adds files as non-delta members or delta members to a library. The member data is read from SYSDTA as standard. It can, however, also be read from an explicitly specified file or *OMF. However, if the statement is entered in the command line of EDT, the member data is automatically read from the current EDT work file.

The files are always added as a member to a library without a prefix, i.e. with catalog ID or user ID, unless the user has explicitly specified a prefix in the construction specification.

Files cataloged with RECORD-FORMAT=*UNDEFINED can also be incorporated in libraries. Files having RECORD-FORMAT=*FIXED can only be stored using SOURCE-ATTRIBUTES=*KEEP.
The record formats FIXED and UNDEFINED are converted into the VARIABLE record format, i.e. are given a 4-byte record header. The record length, including record header, must not exceed 32 Kbytes.
File generation groups can only be incorporated using link names and a valid LMS member designation.

In the case of the ADD-ELEMENT statement, LMS adopts the catalog attribute CCS of the file as a member attribute. If the data is read from SYSDTA, the member generated is given the CCS name set for SYSDTA as an attribute. If the data is read from *OMF, the member is assigned “no code”. If the data is read from an EDT work file, the member generated is given the currently set CCS name of EDT as an attribute.

ADD-ELEMENT

FROM-FILE = STD / SYSDTA(...) / ALL / <filename 1..80 without-vers with-wild> / LINK(...) / *OMF
	*SYSDTA(...)
		\|	END = *́END ́** / <c-string 1..8>
	*LINK(...)
		\|	LINK-NAME = <structured-name 1..8>
,TO-ELEMENT = LIB RARY -ELEM* ENT (...)
	*LIBRARY-ELEMENT(...)
		\|	LIBRARY = STD / LINK(...) / <filename 1..54 without-vers>
		\|		*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 / 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-wild-constr>(...)
		\|			\|	VERSION = LMS-DEF AULT / HIGHEST-EXISTING / *INCREMENT /
		\|			\|		*UPPER-LIMIT / <composed-name 1..24 with-under>
		\|			\|	,BASE = *STD / <composed-name 1..24 with-under with-wild>
		\|	,TYPE = *LMS-DEF AULT / <alphanum-name 1..8>
		\|	,USER-DATE = TODAY / BY-SOURCE /<date 8..10 with-compl>
		\|	,STORAGE-FORM = LMS-DEF AULT / STD / FULL / DELTA
,ELEMENT-ATTRIBUTES = LMS-DEF AULT / PARAMETERS(...)
	*PARAMETERS(...)
		\|	SOURCE-ATTRIBUTES = LMS-DEF AULT / STD / IGNORE / KEEP(...)
		\|		*KEEP(...)
		\|			\|	KEEP-TYPES = LMS-DEF AULT / STD / *ALL
,DELETE-SOURCE = LMS-DEF AULT / NO / *YES
,PROTECTION = LMS-DEF AULT / STD / *BY-SOURCE
,WRITE-MODE = LMS-DEF AULT / CREATE / REPLACE / EXTEND / *ANY
,DIALOG-CONTROL = LMS-DEF AULT / NO / YES / ERROR

FROM-FILE = *STD / *SYSDTA(...) / *ALL / <filename 1..80 without-vers with-wild>/*LINK(..) / *OMF

Specifies the file to be added to the library as a member.

FROM-FILE = *STD
Data records are read from the default file, i.e. the system file SYSDTA. If the statement is entered from the EDT command line, however, the default file from which the data records are read is the current EDT work file.
Permissible member types:

for non-delta members: S, M, P, J, D, X or types derived from them
for delta members: analogous

FROM-FILE = *SYSDTA(...)
The records are read with RDATA from system file SYSDTA. The records must directly follow the ADD-ELEMENT statement.
Permissible member types:

for non-delta members: S, M, P, J, D, X, R or types derived from them
for delta members: S, M, P, J, D, X or types derived from them
END = '*END' / <c-string 1..8>
End criterion for the input. The sequence of records must be concluded with ’*END’ or a self-defined end criterion (see example, "ADD-ELEMENT"). If the input data contains no end criterion, reading continues to EOF.
Note
If records are read from the system file SYSDTA, they must not begin with “/”. The reason for this is that the RDATA macro interprets such records as commands and thus passes the return code for EOF. Therefore it is not possible to pass system commands as records.

FROM-FILE = *ALL
LMS attempts to incorporate all files of the ID into the library. If an error occurs in a file, this file is skipped and the process continues with the next one.

FROM-FILE = <filename 1..80 without-vers with-wild>
The data is read from the specified file.
Permissible member types:

for non-delta members: S, M, P, J, D, X, R, L, C or types derived from them
for delta members: S, M, P, J, D, X or types derived from them

Files of the PAM type can be stored only as non-delta members under the member type X or member types derived from it.

FROM-FILE = *LINK(...)
The data is read from the file specified via the link name.

LINK-NAME = <structured-name 1..8>
Link name referencing the file.

FROM-FILE = *OMF

Applies only to R-type members.
The data is read from the OMF file. All modules from the OMF file are incorporated. If the EAM area contains more than one module of the same name, LMS adds the last module processed to the library.

TO-ELEMENT = *LIBRARY-ELEMENT(...)
Specifies the destination and name under which the member is to be added.

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

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

LIBRARY = *LINK(...)
The library assigned via a 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.

LIBRARY = <filename 1..54 without-vers>
Name of the library to which the file is to be added as a member.

ELEMENT = *BY-SOURCE(...) /
<composed-name 1..132 with-under with-wildcard-constr>(...)
Name that the new member to be added is to receive. A construction specification refers to the file name.

ELEMENT = *BY-SOURCE(...)
The member name corresponds to the file name, or to the module name in the case of *OMF.

VERSION = *LMS-DEFAULT / *HIGHEST-EXISTING / *INCREMENT /
*UPPER-LIMIT / <composed-name 1..24 with-under>
Version that the new member to be added is to receive.

VERSION = *HIGHEST-EXISTING
Depending on the convention applicable for the type, the highest version appropriate to BASE among the existing members of the same type and name is overwritten; 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 "Convention: STD-TREE").

VERSION = *UPPER-LIMIT

The highest possible version X’FF’ is generated.

VERSION = <composed-name 1..24 with-under>
The text specified here is interpreted as the version designation.

BASE = *STD / <composed-name 1..24 with-under with-wild>
Defines the base for the target member. If the BASE operand is entered in the form <composed-name 1..23>*, it will be interpreted as a prefix.
For further information on the effects of BASE, see "Version designations".

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

Specifies the name under which the member is stored.

VERSION = *LMS-DEFAULT / *HIGHEST-EXISTING / *INCREMENT /
*UPPER-LIMIT / <composed-name 1..24 with-under>
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>
Defines the base for the target member. For further information concerning specification of the base, see "Version designations".

TYPE = *LMS-DEFAULT / <alphanum-name 1..8>
Type that the new member to be added is to receive.

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

USER-DATE = *TODAY
The current date is given.

USER-DATE = *BY-SOURCE
The CHANGE-DATE of the file 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 new member to be added. 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 special is required, full storage is selected.

STORAGE-FORM = *FULL
The new member is generated as a non-delta member (if this is not possible, an error message is issued).

STORAGE-FORM = DELTA

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

ELEMENT-ATTRIBUTES = *LMS-DEFAULT / *PARAMETERS(...)
Determines whether the file characteristics and also the ISAM key are incorporated into the output member.

ELEMENT-ATTRIBUTES = *PARAMETERS(...)

SOURCE-ATTRIBUTES = *LMS-DEFAULT / *STD/ *IGNORE / *KEEP

Stores file attributes. This operand has no effect if the data is read from SYSDTA, *OMF or an EDT work file. Original attributes are not stored.
If the data is read from a file of the type UPAM, this entry has no effect; it is always as though *KEEP had been specified.

SOURCE-ATTRIBUTES = *STD

No file attributes are stored. In the case of ISAM files, it is only possible to include in the member ISAM files using KEY-POSITION = 5, KEY-LENGTH <= 16 and RECORD-FORMAT = VARIABLE. A warning will be issued stating that the ISAM keys were not included.

SOURCE-ATTRIBUTES = *IGNORE
The same as for SOURCE-ATTRIBUTES = *STD, but no warning is issued.

SOURCE-ATTRIBUTES = *KEEP(...)
The following file attributes are stored unchanged in the new member being added: ACCESS-METHOD, RECORD-FORMAT, RECORD-SIZE, BUFFER-LENGTH, PERFORMANCE, USAGE, ACCESS and USER-ACCESS. If ACCESS-
METHOD=ISAM, LMS also stores the PADDING-FACTOR, LOGICAL-FLAG-LENGTH, VALUE-FLAG-LENGTH, PROPAGATE-VALUE-FLAG, the ISAM keys and information on ISAM secondary keys.

LMS stores the Last Byte Pointer (LBP) in addition to the previously stored file attributes

for PAM members of type X
for members of type C if KEEP-TYPES = *ALL has been specified

KEEP-TYPES = *LMS-DEFAULT / *STD / *ALL
Specifies types of members for which file attributes are to be stored.
KEEP-TYPES = *STD
Attributes are stored for members of base types S,M,P,D,J,X.
KEEP-TYPES = *ALL
Attributes are stored for members of all base types that are permissible for ADD-ELEMENT.

DELETE-SOURCE = *LMS-DEFAULT / *NO / *YES
Here, the user can specify whether the original file is to be retained or deleted. This operand has no effect if the data is read from SYSDTA, *OMF or an EDT work file.

DELETE-SOURCE=*NO
The original file will not be deleted.

DELETE-SOURCE=*YES
The original file will be deleted.

PROTECTION= *LMS-DEFAULT / *STD / *BY-SOURCE

Member protection for the member being added. This operand has no effect if the data is read from SYSDTA, *OMF or an EDT work file.

PROTECTION=*STD
If the member already exists, its member protection remains unchanged. If the member does not yet exist and initial member protection has been specified for the library and/or the member type, the member will receive that protection.

PROTECTION=*BY-SOURCE
The member is provided member protection according to the file protection attributes of the access mechanism activated for the file. ADD-ELEMENT is rejected with an error message if the file is protected by the access mechanism Access Control List (ACL).

WRITE-MODE = *LMS-DEFAULT / *CREATE / *REPLACE / *EXTEND / *ANYOverwriting 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
A member will only be overwritten if a member having the same name is already present. Otherwise ADD-ELEMENT will be rejected with an error message.

WRITE-MODE = *EXTEND
A member will however only be extended if no ISAM keys are stored in the member and the file attributes stored in the member match the attributes of the file, except for the file name. Otherwise ADD-ELEMENT will be rejected with an error message.
EXTEND is not permitted for delta members or when input is from SYSDTA.

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
2 2 2 2 2	0 0 0 0 0 0 1 32 64 64 64 64 64 64 64 64 64 64 64 64 64 64 64 130 130 130 130	CMD0001 LMS0064 LMS0071 LMS0095 LMS0102 LMS0129 CMD0230 LMS1002 LMS0020 LMS0213 LMS0214 LMS0301 LMS0509 LMS0510 LMS1003 LMS1004 PLA0223 PLA0224 PLA0229 PLA0233 PLA0475 PLA0476 PLA0478 LMS0041 LMS0411 LMS0412 LMS0413	No error GCCSN macro error; no CCS name specified XHCS not loaded Input records missing Incomplete module in EAM file 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 File 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 FROM-FILE: read authorization for the file

If more than one file is affected by the statement, files without read authorization are excluded from the statement.

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 can use this functionality. The library owner must also have ownership of the file which is to be added as a member.

Notes

When adding a file to a library, it is the creation date of the member and not that of the file which applies.
If SOURCE-ATTRIBUTES=*KEEP is specified, the following should be noted:Should any ISAM keys be present, this can impair subsequent processing such as language processing and /CALL-PROCEDURE. This parameter value is particularly suited to archiving.
When creating a member, be sure to observe the convention applicable to the member type.
When temporary files with wildcards are being added, no construction specification of the target member name is permitted, i.e. only ELEM = *BY-SOURCE is permitted.
When temporary files are being added with ELEM = *BY-SOURCE, the member receives the internal file name. This member cannot be output to a file again under another task without explicit specification of a file name.
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. 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.

If PROTECTION=*BY-SOURCE is specified, bear in mind the following:

The BACL, GUARDS and standard access control mechanisms can include the data protection attributes of the access protection mechanism activated for a file in corresponding member proctection.

If the access protection mechanism activated for the file includes the access rights (read, write, execute), the member receives the following, corresponding protection mechanism:

Protection mechanism of file		Protection mechanism of member
Standard access control (ACCESS / USER-ACCESS)		Protection by BACL (without password)
BACL		Protection by BACL (without password)
GUARDS ¹		Protection by GUARD

¹Special case:
If one of the access rights for the file has a value of NONE (no access possible) in the GUARDS protection mechanism, the corresponding right for the member is set to BACL protection with USER=NONE (no access possible).

Existing file passwords are not included in the corresponding member protection.
When files are added to existing members, any existing member protection settings for the access rights (read, write, execute) are lost.

The hold right is handled in the same way as when PROTECTION=STD, i.e. if the member already exists, its member protection remains unchanged in regard to the hold right. If the member does not yet exist and initial protection regarding the hold right has been specified for the library or the member type, the member receives that setting.

Examples

Adding a member
The member “testelem” is added to library LIB1 under the same name. The type specification must be specified explicitly here in the ADD-ELEMENT statement since the type is preset to *NONE as standard.
```
/show-file-attributes
TESTELEM
.
//start-lms
//open-library lib1,*update
//add-element from-file=testelem,to-elem=*lib(type=d)
.
.
```

Reading from SYSDTA and definition of the end criterion

/start-lms -------------------------------------------------------------------  (1) 
//open-library lib1,*update --------------------------------------------------   (2) 
//modify-lms-defaults (type=d) -----------------------------------------------   (3) 
//add-element *sysdta(end=c'stop'),to-element=*lib(element=letter.a) ---------   (4) 
* Dear... --------------------------------------------------------------------  (5) 
. 
. 
. 
*STOP ------------------------------------------------------------------------  (6) 
//end ------------------------------------------------------------------------  (7)

(1)	LMS is started.
(2)	The library with the name lib1 is opened for reading and writing.
(3)	The LMS default value *NONE for the type specification is changed to “D” in the member type specification. This setting applies to the entire LMS run unless a new MODIFY-LMS-DEFAULTS statement affecting this member type is issued or the type is changed locally in a statement.
(4)	Records are to be read in from SYSDTA, where the word STOP is defined as the end criterion. The records are to be stored under the member name letter.a in the library lib1 opened by OPEN-LIBRARY. The member type need no longer be specified.
(5)	Text input. The text ’Dear ...’ is stored exactly as keyed.
(6)	The addition of records is terminated by specifying stop.
(7)	LMS is terminated.

Your Browser is not longer supported

Please use Google Chrome, Mozilla Firefox or Microsoft Edge to view the page correctly

ADD-ELEMENT

Statement return code

Required access rights