EXTRACT-ELEMENT

The EXTRACT-ELEMENT statement outputs library members to files, unless the user specifies otherwise. If the statement is entered in the EDT command line, the member data is written to the current EDT work file by default.

LMS creates the files in accordance with

• the entry in the task file table (TFT), if the file has been assigned via the link name,

• the stored file attributes and the FILE-ATTRIBUTES operand and

• the catalog entry.

The files can have RECORD-FORMAT=UNDEFINED and arbitrary BUFFER-LENGTH and RECORD-SIZE values. However, the maximum record length of 32 Kbytes (including the record header) must not be exceeded.

If the ISAM keys of an ISAM file have been included in the member, the ISAM keys are also output when EXTRACT-ELEMENT is issued.

If information on ISAM secondary keys was stored when the file was added, the secondary keys are recreated. If some or all of the secondary keys cannot be recreated, the file is generated without those keys.

The EXTRACT-ELEMENT statement is permitted for the member types S, M, R, J, P, D, X, C, L and member types derived from them.

C-type members, PAM files under type X, PAM LLM files under type L and types derived from them are generated as PAM files.

The generated file contains the CCS name of the source member as its CCS catalog attribute. If the member data is written to an EDT work file, the EXTRACT-ELEMENT statement is permitted only for textual member types or types derived from them, whereby the CCSN of each member is passed to EDT.

If a text member is extracted to an existing PAM file, the (possibly implicit) setting of the operand ACCESS METHOD determines the new access method (SAM or ISAM) of the target file.

If the EXTRACT-ELEMENT statement is entered for L-type members which are not valid LLM members, LMS outputs the messages:
BND5303 TYPE L ELEMENT 'xxx' VERSION 'xxx' NOT A VALID LLM. STATEMENT ABORTED
BND1102 BINDER ABNORMALLY TERMINATED. SEVERITY CLASS: 'RECOVERABLE ERROR'

Note

Valid member names are not always permitted as file names.

Generating ISAM files

When members are output to ISAM files, LMS generates the ISAM keys as follows:

• If the ISAM keys are also added when an ISAM file is included as a library member, LMS generates the ISAM file with those ISAM keys which have been stored.

• If no ISAM keys have been stored in the input member, an ISAM file with KEY-POSITION = 5 and KEY-LENGTH = 8 is created. LMS then normally generates ISAM keys with an initial value of 1000 and an increment of 1000. If the member is too large for this increment (more than 100,000 records), the increment will be calculated from the number of records.

Notes

• R-type members are output up to the END record. Any records which come afterwards are ignored.

• Correction journal records (TXTP) are not included in the output in the case of C-type members.

• RECORD-SIZE is supplied with values only with RECORD-FORMAT=FIXED; with RECORD-FORMAT=VARIABLE, the value is 0.

EXTRACT-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 / *ALL / *UPPER-LIMIT /
		|			|		<composed-name 1..24 with-under with-wild(52)>
		|			|	,BASE = *STD / <composed-name 1..24 with-under with-wild>
		|		<composed-name 1..64 with-under with-wild(132)>(...)
		|			|	VERSION = *HIGH EST -EXIST ING / *ALL / *UPPER-LIMIT /
		|			|		<composed-name 1..24 with-under with-wild(52)>
		|			|	,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 with-wild(52)>
		|			|			|	,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 with-wild(52)>
		|			|			|	,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-FILE = *STD / *BY-SOURCE / <filename 1..54 without-gen-vers with-wild-constr> / *LINK(...)
	*LINK(...)
		|	LINK-NAME = <structured-name 1..8>
,FILE-ATTRIBUTES = * BY-ELEM ENT / *BY-CATALOG / *LMS-DEFAULT / *PARAMETERS(...)
	*PARAMETERS(...)
		|	ACCESS-METHOD = *LMS-DEF AULT / *ISAM / *SAM
,INFORMATION = *TEXT / list-poss(2): *TEXT / *COMMENT
,PROTECTION = *LMS-DEF AULT / *STD / *BY-SOURCE
,WRITE-MODE = *LMS-DEF AULT / *CREATE / *REPLACE / *EXTEND / *ANY
,DIALOG-CONTROL = *LMS-DEF AULT / *NO / *YES / *ERROR

ELEMENT = *LIBRARY-ELEMENT(...)

Specifies the desired member designation.

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

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

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

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 extracted from the library and included in a file.

VERSION = *HIGHEST-EXISTING / *UPPER-LIMIT /
<composed-name 1..24 with-under with-wild(52)>
Version of the member to be output.

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

VERSION = *UPPER-LIMIT
The highest possible version X’FF’ in the library under the specified TYPE and name is output.

VERSION = <composed-name 1..24 with-under with-wild(52)>

Explicitly specifies the version of the member to be output.

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 = *LMS-DEFAULT / *ALL / <alphanum-name 1..8 with-wild(20)>

Type of the member to be output.

USER-DATE = *ANY / *TODAY / <date 8..10 with-compl> / *INTERVAL(...)

Date given by the user.

USER-DATE = *ANY
The member to be output has any date.

USER-DATE = *TODAY
The member with the current date is output.

USER-DATE = <date 8..10 with-compl>
The member whose date is entered explicitly in the form [YY]YY-MM-DD is output.

USER-DATE = *INTERVAL(...)
All members lying in the specified interval are output.

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.

EXCEPT-ELEMENT = *ELEMENT(...)

Specifies the members that are not to be output. 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-FILE = *STD / *BY-SOURCE /
<filename 1..54 without-gen-vers with-wild-constr> / *LINK(...)
Name of the target file. A construction specification references the member name.

TO-FILE = *STD
Unless otherwise specified, the member data is output to a file which is given the same name as the member. However, if the EXTRACT-ELEMENT statement comes from the EDT command line, the data is written by default to the current EDT work file.

TO-FILE = *BY-SOURCE
The file name is the same as the member name.

TO-FILE = *LINK(...)
The member is output to the file that was assigned via the link name.

LINK-NAME = <structured-name 1..8>
Link name of the library which was declared with a /ADD-FILE-LINK command before LMS was called and which must be known to LMS.

FILE-ATTRIBUTES = *BY-ELEMENT / *BY-CATALOG / *LMS-DEFAULT /*PARAMETERS(...)
File attributes that are defined when the file is created. This operand has no effect if the member data is written to the current EDT work file. LMS defines the file attributes in accordance with the following hierarchy:

1. LINK entry

2. file attributes stored in the member

3. catalog entry

4. LMS default values

The following specifications take effect only when TO-FILE=*LINK has not been specified.

FILE-ATTRIBUTES = *BY-ELEMENT
The file attributes stored in the member take priority.

FILE-ATTRIBUTES = *BY-CATALOG

The attributes stored in the catalog entry take priority. If there is no catalog entry, specifying *BY-CATALOG has the same effect as *BY-ELEMENT.

FILE-ATTRIBUTES = *PARAMETERS(...)

ACCESS-METHOD = *LMS-DEFAULT / *ISAM / *SAM

Specifies the access method ISAM or SAM for the target file.

INFORMATION = *TEXT / list-poss(2): *TEXT / *COMMENT
The section of the member which is to be processed.

INFORMATION = *TEXT
The text itself, i.e. record type 1, is to be output.

INFORMATION = *COMMENT
The separately stored comment, i.e. record type 2, is to be output.

PROTECTION = *LMS-DEFAULT / *STD / *BY-SOURCE
Setting and activation of an access protection mechanism for the file created; this protection corresponds to the member protection in effect for the member. This operand has no effect if the member data is written to the current EDT work file.

PROTECTION = *STD
The member protection in effect for the member is not taken into account in setting the access protection mechanism for the file which is created.

PROTECTION = *BY-SOURCE
The file created is provided with an access protection mechanism corresponding to the member protection which is in effect for the member.

Note

With PROTECTION=*BY-SOURCE, the file is provided with the BACL access protection mechanism, even if it offers no additional protection to the member’s access rights (read, write, execute).
If desired, the values of the ACCESS and USER-ACCESS file attributes (record type 164), which may have been stored in the member (see FILE-ATTRIBUTES), can be used to set the values of the default access control mechanism, regardless of the entry in the PROTECTION operand.

WRITE-MODE = *LMS-DEFAULT / *CREATE / *REPLACE / *EXTEND / *ANY

Overwriting of a file having the same name. If the file does not exist under this name, it will be created as a new file. If the member data is written to the current EDT work file, this operand has no effect, i.e. if the current work file already contains data, the member data is appended to it, and if the current work file is empty, the member data is written at the beginning.

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

WRITE-MODE = *REPLACE
The file must already exist and is replaced.

WRITE-MODE = *EXTEND
The file is extended if it already exists. Otherwise, it will be created as a new file.

WRITE-MODE = *ANY
The file is replaced if it already exists. Otherwise it will be created as a new file.

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 130 130 130 130	CMD0001 LMS0053 LMS0129 LMS0199 LMS0274 LMS0286 CMD0230 LMS1002 LMS0020 LMS0035 LMS0302 LMS0509 LMS1003 LMS1004 PLA0229 LMS0041 LMS0411 LMS0412 LMS0413	No error Member and file attributes different Statement aborted by user Record length invalid with fixed record format Block control value changed File attributes not modified Syntax error Internal error Target member or target file does not exist Member protection not transferrable to file Member not found Target member or target file already exists Error during wildcard processing with at least one member or file Other error No access right for the member System address space exhausted Library locked Member locked Type locked

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.

For TO-FILE: read and write authorization for the file

With PROTECTION=*BY-SOURCE, members can be output as files only for the user’s own ID, and only the owner of the library file can use this functionality.

Note

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

This functionality is rejected if GUARD protection is set for one or more types of access (read, write, execute) to the member and no special protection or BACL protection deviating from USER=NONE is set for at least one type of access (r, w, x).

Existing passwords in member protection are not taken into account.

When PROTECTION=*BY-SOURCE is specified and members are output to existing files provided with additional protection by the protection attributes of a password, these attributes are set to NONE (any existing password is deleted).

Examples

• Member ELEM1 is output via EXTRACT-ELEMENT to file TEST with the specified file attributes.

  /ADD-FILE-LINK FILE-NAME=TEST,LINK-NAME=OUT,ACCESS-METHOD=*SAM,/
                RECORD-FORMAT=*VARIABLE
  /START-LMS
  //MOD-LOGG-PAR LOGG=*MAX
  //OPEN-LIBRARY LIBRARY=LIBIN
  //EXTRACT-ELEMENT *LIB(LIBIN,ELEM1,S),TO-FILE=*LINK(LINK-NAME-OUT)
  INPUT  LIBRARY= :1OSQ:$USER.LIBIN
  OUTPUT FILE
         EXTRACT (S)ELEM1/@(0001)/2011-03-27 AS :1OSQ:$USER.TEST
         , REPLACED EMPTY FILE
  

• If all the members in a library are to be output by name, the following statement must be specified:

  //EXTRACT-ELEMENT *LIB(ELEM=*ALL,TYPE=*ALL)
  INPUT  LIBRARY= :1OSQ:$USER.LIBIN
  OUTPUT FILE
         EXTRACT (S)ELEM1/@(0001)/2011-03-27 AS :1OSQ:$USER.ELEM1
         EXTRACT (S)EXT.FILE.1/@(0001)/2011-03-27 AS :1OSQ:$USER.EXT.FILE.1
         EXTRACT (S)EXT.FILE.2/@(0001)/2011-03-27 AS :1OSQ:$USER.EXT.FILE.2
         EXTRACT (S)EXT.FILE.3/@(0001)/2011-03-27 AS :1OSQ:$USER.EXT.FILE.3
         EXTRACT (S)EXT.FILE.4/@(0001)/2011-03-27 AS :1OSQ:$USER.EXT.FILE.4
         EXTRACT (S)EXT.FILE.5/@(0001)/2011-03-27 AS :1OSQ:$USER.EXT.FILE.5
  //END