#### REC

#### Synopsis

    HELP:   Write a file record-oriented (mainly mainframe world)
    TYPE:   OBJECT
    SYNTAX: REC(NET.{},NAME/FILE='str'/STREAM/DUMMY,FALLOC(),REMOVE,REMAIN,NOMKDIR,APPEND,FLUSH,RECMOD=STOP/CUT/WRAP/SKIP,PRNCTR=DETACH/RETAIN/ERASE/REPLACE,RPLFFD[=num],RECCNT=num,LENFMT.{},SUPPAD,PADCHR='bin'/BINARY-ZERO/ASCII-BLANK/EBCDIC-BLANK/UTF08-BLANK/UTF16BE-BLANK/UTF16LE-BLANK/UTF32BE-BLANK/UTF32LE-BLANK,CHRSET=NONE/SYSTEM/ASCII/UCS1/UTF8/EBCDIC/UCS2BE/UTF16BE/UCS2LE/UTF16LE/UCS4BE/UTF32BE/UCS4LE/UTF32LE/LOCAL,RECDLM='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,ACSTIM=num,MODTIM=num/ORIGINAL,NOSPAN,ATTRIB(),PREPRO[()...],POSTPRO/PSTPRO[()...])

#### Description

This object defines the record-oriented write operation for files. This method writes each data list entry as one record to a data set. You can define the behavior (STOP/CUT/WRAP) if the record is longer than the accepted record length for this file. You can activate the suppression of padding characters and set the padding character. You can define the file organization, block size, record format, add a delimiter behind each record and a lot of other parameters (see below).

A dynamic allocation of the file can be used. This is very powerful and simplifies the generation of files on mainframe systems. The default values for this dynamic allocation depend on the data itself and the original file where the data came from. For example, if you have read an FB80 data set with a GZIP data stream which was formatted based on delimiters in text records and you write it to a file on z/OS without any further parameters, then a PS-VB data set (not FB) with data dependent records is allocated with the correct size. If the result of the decompression is still binary data, then still a PS-FB80 dataset will be allocated. But you can also define other parameters for the file allocation. In this case, the data is converted to this format as good as possible.

On non-mainframe platforms (Windows, Unix, ...), the record I/O module can be used to write records terminated by a delimiter (TXT/DLM) or in a fixed or variable length format. For variable format, the length format must be defined. The default in this case is a 4 byte integer in the platform-dependent endianness. This default conforms to FILEDATA=RECORD for USS on a z/OS mainframe system.

If you chose a host record format for the write on a non-record-oriented Attributes (length, slot number of RRDS, print control character) are stored in front of each record on non-record-oriented systems. Example: If you read a RRDS with print control characters (FRA) and you write this on UNIX as record format VRA to a file, the file format looks like this:

If you chose a host record format for writing on a non-record-oriented system, then the length (only if it is a variable format) and other attributes (slot number, print control character) are stored in front of the data. Here is an example for VRA (variable, relative record format with ASA print control character):

        LLLLnnnnnnnnCdddd..dddd
        LLLLnnnnnnnnCdddd..dddd
        LLLLnnnnnnnnCdddd..dddd
        ...
        ...
        ...
        LLLLnnnnnnnnCdddd..dddd
        LLLLnnnnnnnnCdddd..dddd

Where LLLL is the record length, nn...nn is the slot number, C is the print control character and dd..dd is the record data. To read such a file on the UNIX system, the record format and length format (if you write with defaults, you can read with defaults) must be defined correctly.

This feature allows to unload an RRDS to a WINDOWS or UNIX system and to load this RRDS again with same records and gaps between. Each supported record format has a corresponding representation on non-mainframe systems. This means this unload and load is possible for each kind of data set type of mainframe systems.

To retain the modification time of the original file, the `modtime` parameter can be set to `ORIGINAL`.

#### Arguments

- `STRING: NAME/FILE='str'/STREAM/DUMMY - Name/URL of file to write [auto]`
  - `STREAM - Read from stdin or write to stdout`
  - `DUMMY - Read EOF or write nothing`
- `SWITCH: REMAIN - Remain existing files (don't overwrite) [FALSE]`
- `SWITCH: NOMKDIR - Don't create path if path not exists [FALSE]`
- `SWITCH: APPEND - Append data to this file [FALSE]`
- `SWITCH: FLUSH - Enforce flush in front of close file [FALSE]`
- `NUMBER: RECMOD=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`
- `NUMBER: RPLFFD=num - Replace form feeds, filling rest of page with empty records assuming n lines per page [60]`
- `NUMBER: RECCNT=num - Initial amount of records for preallocation [128]`
- `SWITCH: SUPPAD - Suppress trailing padding characters (useful for variable length records)`
- `STRING: PADCHR='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`
- `NUMBER: CHRSET=NONE/SYSTEM/ASCII/UCS1/UTF8/EBCDIC/UCS2BE/UTF16BE/UCS2LE/UTF16LE/UCS4BE/UTF32BE/UCS4LE/UTF32LE/LOCAL - Character set [SYSTEM]`
  - `NONE - No character set defined`
  - `SYSTEM - SYSTEM (environment specific (on mainframe EBCDIC else ASCII))`
  - `ASCII - ASCII (mainly used in the for open system)`
  - `UCS1 - UCS-1 (for text formatting identical to ASCII < 64k)`
  - `UTF8 - UTF-8 (for text formatting identical to ASCII < 2M)`
  - `EBCDIC - EBCDIC (mainly used on IBM mainframe)`
  - `UCS2BE - UCS-2 Big Endian (multibyte character set < 64k)`
  - `UTF16BE - UTF-16 Big Endian (multibyte character set < 2M)`
  - `UCS2LE - UCS-2 Little Endian (multibyte character set < 64k)`
  - `UTF16LE - UTF-16 Little Endian (multibyte character set < 2M)`
  - `UCS4BE - UCS-4 Big Endian (multibyte character set < 64k)`
  - `UTF32BE - UTF-32 Big Endian (multibyte character set < 2M)`
  - `UCS4LE - UCS-4 Little Endian (multibyte character set < 64k)`
  - `UTF32LE - UTF-32 Little Endian (multibyte character set < 2M)`
  - `LOCAL - LOCAL (platform specific (on mainframe EBCDIC else ASCII))`
- `STRING: RECDLM='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: ACSTIM=num - Define the last access time for this file`
- `NUMBER: MODTIM=num/ORIGINAL - Define the last modification time for this file`
  - `ORIGINAL - Copy modification time from the original file`
- `SWITCH: NOSPAN - Deactivate write of large spanned records to V(B)S datasets [FALSE]`