The EXTRACT-ELEMENT statement outputs members to files. LMSCONV 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
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 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 output file.
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 permissible for member types S, M, R, J, P, D, X, C. Members of type C, and PAM members under type X, are created as PAM files.
The file created contains the CCS name of the source member as its CCS catalog attribute.
Valid member names are not always permitted as file names.
Generating ISAM files
When members are output to ISAM files, LMSCONV generates the ISAM keys as follows:
If the ISAM keys are also added when an ISAM file is included as a library member, LMSCONV 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. LMSCONV 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.
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.
Format
EXTRACT-ELEMENT | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||
Operands
ELEMENT = *LIBRARY-ELEMENT(...)
Specifications for 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.
ELEMENT = *ALL(...) / <composed-name 1..64 with-under with-wild(132)>(...)
Name of the members to be extracted from the library.
ELEMENT = *ALL(...)
All members are taken from the library.
ELEMENT = <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 / *ALL / *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 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.
TYPE = *DEFAULT / *ALL / <alphanum-name 1..8 with-wild(20)>
Type of the member to be adopted.
TYPE = *DEFAULT
If the value is *DEFAULT and the current value set with MODIFY-DEFAULTS is *NONE, LMSCONV requires a type specification.
TYPE = *ALL
All types are adopted.
TYPE = <alphanum-name 1..8 with-wild(20)>
Only the specified type is adopted.
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 selected.
USER-DATE = <date 8..10 with-compl>
The member whose date is entered explicitly in the form [YY]YY-MM-DD is chosen.
USER-DATE = *INTERVAL(...)
All members lying in the specified interval are chosen.
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.
TO-FILE = *STD / *BY-SOURCE / <filename 1..54 without-gen-vers with-wild-constr> / *LINK(...)
Name of the target file.
TO-FILE = *STD
Unless otherwise specified, the member data is output to a file which is given the same name as the member.
TO-FILE = *BY-SOURCE
The file name is the same as the member name.
TO-FILE = <filename 1..54 without-gen-vers with-wild-constr>
Name of the target file. A design specification refers to 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>
File link name.
FILE-ATTRIBUTES = *BY-ELEMENT / *BY-CATALOG / *DEFAULT / *PARAMETERS(...)
File attributes specified when the file is created. LMSCONV defines the file attributes in accordance with the following hierarchy:
LINK entry
file attributes stored in the member
catalog entry
LMSCONV 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 = *DEFAULT / *ISAM / *SAM
Specifies the access method ISAM or SAM for the target file. The default value is *ISAM or the current value set with MODIFY-DEFAULTS.
WRITE-MODE = *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.
WRITE-MODE = *DEFAULT
The default value is *CREATE (see below) or the current value set with MODIFY-DEFAULTS.
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 = *DEFAULT / *NO / *YES / *ERROR
This operand specifies whether or not the execution of the statement is carried out interactively with the user.
For more detailed information on dialog control, see the MODIFY-DEFAULTS statement.
DIALOG-CONTROL = *DEFAULT
The default value is *NO or the current value set with MODIFY-DEFAULTS..
DIALOG-CONTROL = *NO
All members are processed without dialog queries, i.e. without the user being able to take control.
Exception: If a member or a library is locked, LMSCONV inquires whether the attempt to access it shall be repeated.
DIALOG-CONTROL = *YES / *ERROR
See the description in the MODIFY-DEFAULTS statement.
Note
Extracting an element into a SAM node file on Net-Storage can fail because the CCSN of the element cannot be converted into the NETCCSN of the node file. This can have several cause:
- An inappropriate CCSN is assigned to the element. In this case a suitable CCSN can be assigned with // MODIFY-ELEMENT-ATTRIBUTES.
- An unsuitable NETCCSN is stored in the file attributes for the element (can be seen in the output of // SHOW-ELEMENT TEXT-INFORMATION = * FILE-ATTRIBUTES). In this case, the node file into which the element is to be extracted must be assigned the appropriate NETCCSN with / MODIFY-FILE-ATTRIBUTES. The element can then be extracted by specifying FILE-ATTRIBUTES = * BY-CATALOG.
- No NETCCSN is saved for the element (e.g. because it was not originally a node file or because the SOURCE-ATTRIBUTES = * KEEP operand was not specified when the node file was added to the library), and the user's preset NETCCSN does not match CCSN. In general, the user attribute NET-CODED-CHARACTER-SET should be changed accordingly in this case. In individual cases, however, the same procedure can be used as in case 2.
Examples
Member ELEM1 is output by EXTRACT-ELEMENT to file TEST having the specified file attributes.
/add-file-link file-name=test,link-name=out,access-method=*sam, - / record-format=*variable /start-lmsconv //open-library library=libin //extract-element (,elem1,s),*link(link-name=out) //end
If all the members in a library are to be output by name, the following statement must be specified:
//extract-element (elem=*all,type =*all)
Note
It is not possible to modify the element's NETCCSN. That means that after changing the CCSN and extracting a member the resulting SAM node file may eventually not be edited if the required code conversion cannot be executed. In this case, the correct code table should be set using the MODIFY-FILE-ATTRIBUTES command.