#### RECORD

#### Synopsis

    HELP:   Read records from a file
    TYPE:   OBJECT
    SYNTAX: RECORD(NET.{},FILE['str'/STREAM/DUMMY...],RECMODE=STOP/CUT/WRAP/SKIP,PRNCONTROL=DETACH/RETAIN/ERASE/REPLACE,RPLFFD[=num],SUPPADDING,PADCHARACTER='bin'/BINARY-ZERO/ASCII-BLANK/EBCDIC-BLANK/UTF08-BLANK/UTF16BE-BLANK/UTF16LE-BLANK/UTF32BE-BLANK/UTF32LE-BLANK,ORGANIZATION=SEQ/PS/LIB/PDS/USS/EDS/ESDS/KDS/KSDS/RDS/RRDS,BLKSIZE=num,RECFORMAT=NONE/BIN/TXT/TXT-ASA/TXT-MCC/DLM/DLM-ASA/DLM-MCC/VAR/VAR-ASA/VAR-MCC/FIX/FIX-ASA/FIX-MCC/VAR-REL/VAR-REL-ASA/VAR-REL-MCC/FIX-REL/FIX-REL-ASA/FIX-REL-MCC/F/FA/FM/FS/FSA/FSM/FB/FBA/FBM/FBS/FBSA/FBSM/FE/FEA/FEM/FK/FKA/FKM/FR/FRA/FRM/U/UA/UM/V/VA/VM/VS/VSA/VSM/VB/VBA/VBM/VBS/VBSA/VBSM/VE/VEA/VEM/VK/VKA/VKM/VR/VRA/VRM/ORG,RECLENGTH=num,RECDELIM='bin'/CR-ASCII/LF-ASCII/NL-ASCII/CRLF-ASCII/CR-EBCDIC/LF-EBCDIC/NL-EBCDIC/CRLF-EBCDIC/CR-UTF08/LF-UTF08/NL-UTF08/CRLF-UTF08/CR-UTF16BE/LF-UTF16BE/NL-UTF16BE/CRLF-UTF16BE/CR-UTF16LE/LF-UTF16LE/NL-UTF16LE/CRLF-UTF16LE/CR-UTF32BE/LF-UTF32BE/NL-UTF32BE/CRLF-UTF32BE/CR-UTF32LE/LF-UTF32LE/NL-UTF32LE/CRLF-UTF32LE,RECCOUNT=num,LENFORMAT.{},KEYPOSITION=num,KEYLENGTH=num,NOSPANNED,REGEXP(),DECODE[=NONE/ARCHIVE/DECOMP/RECORD/CMPDEC/ALWAYS],DECRYPT[{}...],FDECODE/COD.{},CCSID='str'/DEFAULT/ASCII/EBCDIC/BOMUTF/BOMUCS/SYSTEM/LOCAL,CHRMODE=STOP/IGNORE/SUBSTITUTE/IDENTITY/TRANSLIT,SKIPEQUAL,USRTABLE='str'/NPAS/SEPA/DELA/DLAX,ONEMAP,COMBINED=NFD/NFC/AUTO/ON/OFF,BOM,KEEPBOM,SUBSYSTEM(),REMOVE,LANG='str',PLATFORM=WIN/UNX/ZOS/USS/VSE/BS2/MAC,OWNER='str',ENVID='str',HASH(),SIGNATURE.{},CHECK,TABLE(),AVSCAN(),NOARCH,PREPROCESS[()...],POSTPROCESS/PSTPRO[()...])

#### Description

Read record provides a list of records from a host-like data set format or from a member in an archive file.

If a record contains text data, you can mark it by defining the correct CCSID. This will result in character set conversion from the provided CCSID to UTF-8 for each record. If the CCSID is not provided, the record is handled as binary data.

The following options are supported:

- Stop, cut or wrap if a record is longer then provided record length
- Print control character handling as attributes
- Padding of fixed-length record formats at write operations
- Suppress trailing padding characters for fixed-length record formats at read
- Suppress trailing padding characters for variable record formats at write
- All kind of record formats and length including entry, index, keyed and relative data sets, including management of slot numbers
- Support of various file allocation, space parameters and subsystems
- Validation of records using regular expressions

If decryption parameters or a member name are specified, transparent reading of FLAM4FILEs is activated automatically. You can enforce or prevent this by setting the DECODE parameter accordingly.

Archives, decryption and decompression are supported for different types of files when writing. FLAM4 archives support storing records, but you can also use ZIP archives, GZIP or ASCII armored files to archive host record datasets. This solution uses FLAM specific extensions of the respective formats. Therefore, you must use FLCL to recreate the correct host data set by activating the decode switch. This works for all kinds of datasets (PS, PO, VSAM) except load libraries, which cannot be recreated with loadable modules.

Decoding of FLAMFILEs or other supported formats can be enforced with the keyword 'DECODE' (default is the level 'RECORD'). If the DECODE parameter is not specified, the raw record will be processed.

The DECODE switch also enables support for reading different archive formats, automatic decryption and decompression, followed by a final record conversion based on length fields or a binary delimiter, if one was used to store the record-oriented dataset. Auto-decoding capabilities can be limited by assigning one of the defined levels to the DECODE parameter.

If DECODE is not specified (read records from dataset), but a binary record delimiter is set, the default record format is DLM and does not have to be assigned explicitly.

If no length fields or binary delimiters are detected and the original record length is known, the data is wrapped into records of this length by default, which is useful if fixed record length dataset formats are exchanged.

For not cataloged data sets or record-oriented file formats on non record-oriented platforms (WIN, UNIX, ...), you can define file organization, block size, record format and record length. If you work with cataloged files or FLAMFILEs, these parameters are not required.

For non-record-oriented platforms, you can define a lot of different length formats. If you don't specify a length format at read and a 4 byte record length format is detected (a FILEDATA=RECORD file is allocated with FILEDATA=BINARY), the length fields in the data are used to build the records.

If you provide row specifications through the table object, each record is split into neutral FL5 table elements.

#### Arguments

- `STRING: FILE['str'/STREAM/DUMMY...] - Name/URL of file to read [''==stdin]`
  - `STREAM - Read from stdin or write to stdout`
  - `DUMMY - Read EOF or write nothing`
- `NUMBER: RECMODE=STOP/CUT/WRAP/SKIP - Mode used to read records [STOP]`
  - `STOP - Stop if record too long`
  - `CUT - Cut if record too long`
  - `WRAP - Wrap if record too long`
  - `SKIP - Skip if record too long`
- `NUMBER: RPLFFD=num - Replace form feeds, filling rest of page with empty records assuming n lines per page [60]`
- `SWITCH: SUPPADDING - Suppress trailing padding characters (useful for fixed-length records)`
- `STRING: PADCHARACTER='bin'/BINARY-ZERO/ASCII-BLANK/EBCDIC-BLANK/UTF08-BLANK/UTF16BE-BLANK/UTF16LE-BLANK/UTF32BE-BLANK/UTF32LE-BLANK - Define padding character for suppression [automatic]`
  - `BINARY-ZERO - Padding with 0x00`
  - `ASCII-BLANK - Padding with 0x20`
  - `EBCDIC-BLANK - Padding with 0x40`
  - `UTF08-BLANK - Padding with 0x20`
  - `UTF16BE-BLANK - Padding with 0x0020`
  - `UTF16LE-BLANK - Padding with 0x2000`
  - `UTF32BE-BLANK - Padding with 0x00000020`
  - `UTF32LE-BLANK - Padding with 0x20000000`
- `NUMBER: ORGANIZATION=SEQ/PS/LIB/PDS/USS/EDS/ESDS/KDS/KSDS/RDS/RRDS - File organization [catalog/SEQ]`
  - `SEQ - Sequential data set [DEFAULT]`
  - `PS - Sequential data set [DEFAULT]`
  - `LIB - Library (ZOS-PDSE)`
  - `PDS - Partitioned data set (ZOS-PDS)`
  - `USS - UNIX files (path based)`
  - `EDS - Entry data set (VSAM-ESDS)`
  - `ESDS - Entry data set (VSAM-ESDS)`
  - `KDS - Keyed data set (VSAM-KSDS)`
  - `KSDS - Keyed data set (VSAM-KSDS)`
  - `RDS - Relative data set (VSAM-RRDS)`
  - `RRDS - Relative data set (VSAM-RRDS)`
- `NUMBER: RECFORMAT=NONE/BIN/TXT/TXT-ASA/TXT-MCC/DLM/DLM-ASA/DLM-MCC/VAR/VAR-ASA/VAR-MCC/FIX/FIX-ASA/FIX-MCC/VAR-REL/VAR-REL-ASA/VAR-REL-MCC/FIX-REL/FIX-REL-ASA/FIX-REL-MCC/F/FA/FM/FS/FSA/FSM/FB/FBA/FBM/FBS/FBSA/FBSM/FE/FEA/FEM/FK/FKA/FKM/FR/FRA/FRM/U/UA/UM/V/VA/VM/VS/VSA/VSM/VB/VBA/VBM/VBS/VBSA/VBSM/VE/VEA/VEM/VK/VKA/VKM/VR/VRA/VRM/ORG - Record format for read operation [catalog/VAR]`
  - `NONE - No format defined`
  - `BIN - Open - Binary (undefined) data (only the last record are shorter then record length)`
  - `TXT - Open - Text data with standard delimiter (result is a stripped variable length records)`
  - `TXT-ASA - Open - Text data with standard delimiter and ASA byte in front (result variable length records with ASA attribute)`
  - `TXT-MCC - Open - Text data with standard delimiter and MCC byte in front (result variable length records with MCC attribute)`
  - `DLM - Open - Records separated by a special delimiter with the result of variable length records`
  - `DLM-ASA - Open - ASA records separated by a special delimiter with the result of variable length records`
  - `DLM-MCC - Open - MCC records separated by a special delimiter with the result of variable length records`
  - `VAR - Open - Variable length record (if necessary define length format)`
  - `VAR-ASA - Open - Variable length record with ASA print control character (if necessary define length format)`
  - `VAR-MCC - Open - Variable length record with machine print control codes (if necessary define length format)`
  - `FIX - Open - Fixed-length record (file size = N * record length)`
  - `FIX-ASA - Open - Fixed-length record with ASA print control character (file size = N * (record length + 1))`
  - `FIX-MCC - Open - Fixed-length record with machine print control codes (file size = N * (record length + 1))`
  - `VAR-REL - Open - Variable relative record (if necessary define length format)`
  - `VAR-REL-ASA - Open - Variable relative record with ASA print control character (if necessary define length format)`
  - `VAR-REL-MCC - Open - Variable relative record with machine print control codes (if necessary define length format)`
  - `FIX-REL - Open - Fix relative record (file size = N * (record length + 8))`
  - `FIX-REL-ASA - Open - Fix relative record with ASA print control character (file size = N * (record length + 9))`
  - `FIX-REL-MCC - Open - Fix relative record with machine print control codes (file size = N * (record length + 9))`
  - `F - Host - Fixed-length, unblocked`
  - `FA - Host - Fixed-length, unblocked, ASA print control characters`
  - `FM - Host - Fixed-length, unblocked, machine print control codes`
  - `FS - Host - Fixed-length, standard`
  - `FSA - Host - Fixed-length, standard, ASA print control characters`
  - `FSM - Host - Fixed-length, standard, machine print control codes`
  - `FB - Host - Fixed-length, blocked`
  - `FBA - Host - Fixed-length, blocked, ASA print control characters`
  - `FBM - Host - Fixed-length, blocked, machine print control codes`
  - `FBS - Host - Fixed-length, blocked, standard`
  - `FBSA - Host - Fixed-length, blocked, standard, ASA print control characters`
  - `FBSM - Host - Fixed-length, blocked, standard, machine print control codes`
  - `FE - Host - Fixed-length, ESDS`
  - `FEA - Host - Fixed-length, ESDS, ASA print control characters`
  - `FEM - Host - Fixed-length, ESDS, machine print control codes`
  - `FK - Host - Fixed-length, KSDS`
  - `FKA - Host - Fixed-length, KSDS, ASA print control characters`
  - `FKM - Host - Fixed-length, KSDS, machine print control codes`
  - `FR - Host - Fixed-length, RRDS`
  - `FRA - Host - Fixed-length, RRDS, ASA print control characters`
  - `FRM - Host - Fixed-length, RRDS, machine print control codes`
  - `U - Host - Undefined-length`
  - `UA - Host - Undefined-length, ASA print control characters`
  - `UM - Host - Undefined-length, machine print control codes`
  - `V - Host - Variable`
  - `VA - Host - Variable, ASA print control characters`
  - `VM - Host - Variable, machine print control codes`
  - `VS - Host - Variable, spanned`
  - `VSA - Host - Variable, spanned, ASA print control characters`
  - `VSM - Host - Variable, spanned, machine print control codes`
  - `VB - Host - Variable, blocked`
  - `VBA - Host - Variable, blocked, ASA print control characters`
  - `VBM - Host - Variable, blocked, machine print control codes`
  - `VBS - Host - Variable, blocked, spanned`
  - `VBSA - Host - Variable, blocked, spanned, ASA print control characters`
  - `VBSM - Host - Variable, blocked, spanned, machine print control codes`
  - `VE - Host - Variable, ESDS`
  - `VEA - Host - Variable, ESDS, ASA print control characters`
  - `VEM - Host - Variable, ESDS, machine print control codes`
  - `VK - Host - Variable, KSDS`
  - `VKA - Host - Variable, KSDS, ASA print control characters`
  - `VKM - Host - Variable, KSDS, machine print control codes`
  - `VR - Host - Variable, RRDS`
  - `VRA - Host - Variable, RRDS, ASA print control characters`
  - `VRM - Host - Variable, RRDS, machine print control codes`
  - `ORG - Use original record format as default (like none)`
- `NUMBER: RECLENGTH=num - Maximum record length for read operation [catalog/512]`
- `STRING: RECDELIM='bin'/CR-ASCII/LF-ASCII/NL-ASCII/CRLF-ASCII/CR-EBCDIC/LF-EBCDIC/NL-EBCDIC/CRLF-EBCDIC/CR-UTF08/LF-UTF08/NL-UTF08/CRLF-UTF08/CR-UTF16BE/LF-UTF16BE/NL-UTF16BE/CRLF-UTF16BE/CR-UTF16LE/LF-UTF16LE/NL-UTF16LE/CRLF-UTF16LE/CR-UTF32BE/LF-UTF32BE/NL-UTF32BE/CRLF-UTF32BE/CR-UTF32LE/LF-UTF32LE/NL-UTF32LE/CRLF-UTF32LE - Delimiter used to define end of record (if RECF=DLM used)`
  - `CR-ASCII - Delimiter: carriage return in ASCII (0x0D)`
  - `LF-ASCII - Delimiter: line feed in ASCII (0x0A)`
  - `NL-ASCII - Delimiter: new line in ASCII (0x85)`
  - `CRLF-ASCII - Delimiter: carriage return line feed in ASCII (0x0D0A)`
  - `CR-EBCDIC - Delimiter: carriage return in EBCDIC (0x0D)`
  - `LF-EBCDIC - Delimiter: line feed in EBCDIC (0x25)`
  - `NL-EBCDIC - Delimiter: new line in EBCDIC (0x15)`
  - `CRLF-EBCDIC - Delimiter: carriage return line feed in EBCDIC (0x0D25)`
  - `CR-UTF08 - Delimiter: carriage return in UTF-8 (0x0D)`
  - `LF-UTF08 - Delimiter: line feed in UTF-8 (0x0A)`
  - `NL-UTF08 - Delimiter: new line in UTF-8 (0xC285)`
  - `CRLF-UTF08 - Delimiter: carriage return line feed in UTF-8 (0x0D0A)`
  - `CR-UTF16BE - Delimiter: carriage return in UTF-16BE (0x000D)`
  - `LF-UTF16BE - Delimiter: line feed in UTF-16BE (0x000A)`
  - `NL-UTF16BE - Delimiter: new line in UTF-16BE (0x0085)`
  - `CRLF-UTF16BE - Delimiter: carriage return line feed in UTF-16BE (0x000D000A)`
  - `CR-UTF16LE - Delimiter: carriage return in UTF-16LE (0x0D00)`
  - `LF-UTF16LE - Delimiter: line feed in UTF-16LE (0x0A00)`
  - `NL-UTF16LE - Delimiter: new line in UTF-16LE (0x8500)`
  - `CRLF-UTF16LE - Delimiter: carriage return line feed in UTF-16LE (0x0D000A00)`
  - `CR-UTF32BE - Delimiter: carriage return in UTF-32BE (0x0000000D)`
  - `LF-UTF32BE - Delimiter: line feed in UTF-32BE (0x0000000A)`
  - `NL-UTF32BE - Delimiter: new line in UTF-32BE (0x00000085)`
  - `CRLF-UTF32BE - Delimiter: carriage return line feed in UTF-32BE (0x0000000D0000000A)`
  - `CR-UTF32LE - Delimiter: carriage return in UTF-32LE (0x0D000000)`
  - `LF-UTF32LE - Delimiter: line feed in UTF-32LE (0x0A000000)`
  - `NL-UTF32LE - Delimiter: new line in UTF-32LE (0x85000000)`
  - `CRLF-UTF32LE - Delimiter: carriage return line feed in UTF-32LE (0x0D0000000A000000)`
- `NUMBER: RECCOUNT=num - Amount of records handled in one read operation [catalog/128]`
- `NUMBER: KEYPOSITION=num - Key position (>=1) for index/key sequential data sets [0=NONE]`
- `NUMBER: KEYLENGTH=num - Key length (>=1) for index/key sequential data sets [if KEYPOS>0 then 8]`
- `SWITCH: NOSPANNED - Deactivate read of large spanned records from V(B)S datasets [FALSE]`
- `NUMBER: DECODE=NONE/ARCHIVE/DECOMP/RECORD/CMPDEC/ALWAYS - Decode encoded, encrypted or compressed data [0=NONE]`
  - `NONE - No automated decoding`
  - `ARCHIVE - Transparently read archives`
  - `DECOMP - Decryption and decompression of encrypted and/or compressed data`
  - `RECORD - Decode record length fields or delimiter (is default) after decompression`
  - `CMPDEC - Additional base decoding after decompression, before formatting`
  - `ALWAYS - Always decode encoded data (causes the same as CMPDEC)`
- `SWITCH: SKIPEQUAL - Skip conversion if formats are equal (e.g. UTF-8 to UTF-8)`
- `SWITCH: KEEPBOM - Keep byte order mark for faster conversion`
- `SWITCH: NOARCH - Disable the attempt to read archives (prevent multiple opens to the same file) [FALSE]`