#### RECORD

#### Synopsis

    HELP:   Write records to a file
    TYPE:   OBJECT
    SYNTAX: RECORD(NET.{},FILE='str'/STREAM/DUMMY,FALLOC(),REMOVE,REMAIN,APPEND,FLUSH,RECMODE=STOP/CUT/WRAP/SKIP,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,LENFORMAT.{},PRNCONTROL=DETACH/RETAIN/ERASE/REPLACE,RPLFFD[=num],SUPPADDING,PADCHAR='bin'/BINARY-ZERO/ASCII-BLANK/EBCDIC-BLANK/UTF08-BLANK/UTF16BE-BLANK/UTF16LE-BLANK/UTF32BE-BLANK/UTF32LE-BLANK,NOSPANNED,CCSID='str'/DEFAULT/ASCII/EBCDIC/SYSTEM/LOCAL,CASE=UPPER/LOWER/FOLD/SUPPER/SLOWER/USRTAB,BOM,KEPBOM,CHRMODE=STOP/IGNORE/SUBSTITUTE/IDENTITY/TRANSLIT,SUBCHAR[num/SYSTEM...],SYSTABLE=ICONV,USRTABLE='str'/NPAS/SEPA/DELA/DLAX,ONEMAP,COMBINED=NFD/NFC/AUTO/ON/OFF,REPORTFILE='str'/STDOUT/STDERR,BLK2REC,REGEXP(),COMPRESS/CMP.{},ENCRYPT/ENC.{},ENCODE/COD.{},ARCHIVE/LIB.{},LANG='str',PLATFORM=WIN/UNX/ZOS/USS/VSE/BS2/MAC,OWNER='str',ENVID='str',HASH(),SIGNATURE.{},INDSIZ=num,INDCHR=SPACE/TABULATOR,NOCMNT,NOMKDIR,TABLE(),ATTRIB(),AVSCAN(),PREPROCESS[()...],POSTPROCESS/PSTPRO[()...])

#### Description

Write record formats the list of elements as records for host data set formats or to archive the dataset in a format like GZIP, ZIP, PGP or as a FLAMFILE on a local or remote system.

The following options are supported:

- Cutting or wrapping of records which are too long
- ASA and machine print control character handling
- All kind of mainframe records formats, length and block size
- Different record formats for the distributed world
- Free definition of padding character for fixed length formats
- Validation of or replacements in records using regular expressions

If a record is marked as text record, character conversion from UTF-8 to a defined CCSID is done.

The following options are supported for character conversion:

- Stop, ignore or substitution of invalid or incomplete character
- A free defined substitution character list
- Different system substitution / transliteration tables
- A user defined substitution table to change the system tables
- Case management (upper, lower, folding and special casing)
- Transliteration between subsets (mapping) and normalization
- BOM management and automatic detection of char sets
- Reporting of ignored or substituted characters

During record I/O, encryption and compression can be applied. When selecting output formats like GZIP, PGP or ZIP, records are converted to data blocks. By default, a record length field (L4X) is put in front of binary records. For text records, a text delimiter is add by default. You can also specify a binary delimiter or another kind of 4 byte length field. The default text record conversion to a data block is compatible with a text file on non-mainframe platforms.

If you chose to retain control characters, then all record attributes (slot number, ASA and MCC) are stored in front the a binary record. If text handling used, then ASA and machine control character are lost, except the print control at READ.RECORD() was retain, in which case character conversion does not make much sense.

The file attributes can only be stored in a FLAMFILE, GZIP or ZIP member header or if an ASCII armor header is used. If you create, for example, a BZIP2 or binary PGP file, then all the DCB parameter are lost. When reading the file back, a PS-VB dataset will be created by default. The combinations below produce an archive that allow restoring the host data set without losing meta data (except load module entry addresses of a PDS(E) load library):

    read.record(...) write.record(... archive.fl4())
    read.record(...) write.record(... archive.zip())
    read.record(...) write.record(... comp.bzip() archive.zip())
    read.record(...) write.record(... encr.pgp()  archive.zip())
    read.record(...) write.record(... comp.gzip() encr.pgp())
    read.record(...) write.record(... encr.pgp(armor()))
    read.record(...) write.record(... comp.bzip() encode.armor())

This functionality uses a private extension field in GZIP, ZIP or ARMOR headers and a per-record length field in the data. You can also use a binary delimiter for variable length records. When archiving files with FLCL, you must read them with FLCL to restore the datasets correctly. To read such a file, the example below can be used:

    read.record(file='infile' DECODE) write.record()

Write record supports different encoding schemes (e.g. Base64). By default, the encoding is done record by record. If you enforce block orientation for the encoding, the record boundaries are lost and the resulting blocks can wrapped to new records, if you define all the corresponding parameters accordingly. When writing archive formats, the encoding is done after all compression/encryption.

If the data to be written consists of table elements and the 'TABLE' object is not specified or with no further formatting (i.e. TABLE()), then the original record in system representation without header 'TABLE(FORMAT=ORG DEFAULTS(SYSTEM,NOHDLN))' is written. Character conversion is done on a per-element basis. There is no report file or BOM support if table formatting is used. Use the 'TABLE' object to reformat the table.

#### Arguments

- `STRING: FILE='str'/STREAM/DUMMY - Name/URL of file to write [''==origin.ext]`
  - `STREAM - Read from stdin or write to stdout`
  - `DUMMY - Read EOF or write nothing`
- `SWITCH: REMAIN - Remain existing files (don't overwrite) [FALSE]`
- `SWITCH: APPEND - Append data to this file or add member to archive [FALSE]`
- `SWITCH: FLUSH - Enforce flush in front of close file [FALSE]`
- `NUMBER: RECMODE=STOP/CUT/WRAP/SKIP - Mode used to write 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`
- `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`
  - `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: 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 variable records)`
- `STRING: PADCHAR='bin'/BINARY-ZERO/ASCII-BLANK/EBCDIC-BLANK/UTF08-BLANK/UTF16BE-BLANK/UTF16LE-BLANK/UTF32BE-BLANK/UTF32LE-BLANK - Character to pad records to a fixed length [system] or used for empty variable length records [NONE]`
  - `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`
- `SWITCH: NOSPANNED - Deactivate write of large spanned records to V(B)S datasets [FALSE]`
- `SWITCH: KEPBOM - Keep byte order mark for faster conversion`
- `SWITCH: BLK2REC - Convert block with delimiter to records (including suppression of trailing whitespace`
- `NUMBER: INDSIZ=num - Number of XML indentation characters per indentation level [2 (SPACE) or 1 (TAB)]`
- `NUMBER: INDCHR=SPACE/TABULATOR - Indentation character used to indent XML tags [SPACE]`
  - `SPACE - Use the space character as indentation character`
  - `TABULATOR - Use the tabulator character as indentation character`
- `SWITCH: NOCMNT - Do not write out XML comments [FALSE]`
- `SWITCH: NOMKDIR - Don't create path if path not exists [FALSE]`