#### CHARACTER

#### Synopsis

    HELP:   Read character data from a file
    TYPE:   OBJECT
    SYNTAX: CHARACTER(NET.{},FILE['str'/STREAM/DUMMY...],BLKSIZE=num,RECLENGTH=num,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,ENL2LF,DECODE=NONE/FIODEC/CRYDEC/CMPDEC/ALWAYS,DECRYPT[{}...],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,SUPPADDING,PRNCONTROL=DETACH/RETAIN/ERASE/REPLACE,RPLFFD[=num],SUBSYSTEM(),FRCBLK,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 char operates on blocks of text data. If the input data is encoded (e.g. Base64), encrypted or compressed, it is automatically decoded, decrypted and/or decompressed.

Through the 'decode' parameter, you can extend or limit the number of encoding layers to remove. For example, to retrieve a Base64-encoded text from a GZIP file instead of the decoded version of this text you can set DECODE=CRYDEC. To decode encoded XML data after decompression you must define DECODE=CMPDEC. This is the default. The base decoding of text can result in valid but nonsensical text. There is no uniqueness for a clear decision in this case. To enforce decoding of possible base encodings where the result is still a character or text stream, you must set DECODE=ALWAYS.

If a 4 byte record length format is detected, the record lengths are removed to build a valid character block with a certain number of records.

For decryption, you must provide the required decryption parameters, e.g. a key reference or passphrase. Several decryption methods can be enabled at once with the corresponding parameters and will be used to transparently read the data.

Decompression is done automatically because a compressed data stream is binary and contains no valid characters.

If you provide a record length, the character stream is wrapped into fixed-length records. This is useful to exchange fixed-length text records with open standards like PGP or GZIP.

If you provide a binary delimiter, the data stream is wrapped into variable-length text records.

The character data is converted from the provided CCSID to UTF-8. If no CCSID is provided or auto detection fails, the default CCSID is determined in a system-dependent way in the following order:

- Stored CCSID from the file system (if available)
- From the environment variable LANG
- ISO-8859-1 (Latin-1) on ASCII and IBM-1047 (Open Systems Latin-1) on EBCDIC systems

The character data blocks can be converted to any code page on write. If you don't need character conversion, the binary version of reading files might be more suitable.

In contrast to the read text method, the read char method does not scan for line delimiters to build valid records. This means that the data will remain a chunk of character data.

If you provide row specifications through the table object, the character blob is split into neutral FL5 table elements (rows and columns).

#### 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: RECLENGTH=num - Length to activate fixed length record wrapping [0-OFF]`
- `SWITCH: SKIPEQUAL - Skip conversion if formats are equal (e.g. UTF-8 to UTF-8)`
- `SWITCH: KEEPBOM - Keep byte order mark for faster conversion`
- `NUMBER: DECODE=NONE/FIODEC/CRYDEC/CMPDEC/ALWAYS - Decode encoded data first (remove base encodings)`
  - `NONE - No automated decoding`
  - `FIODEC - Base decoding after file IO, before decryption`
  - `CRYDEC - Base decoding after decryption, before decompression`
  - `CMPDEC - Base decoding after decompression, before formatting if XML`
  - `ALWAYS - Always decode encoded data (like CMPDEC but also if CHAR or TEXT)`
- `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 parse end of record [NONE]`
  - `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)`
- `SWITCH: SUPPADDING - Suppress trailing padding/equal characters`
- `NUMBER: RPLFFD=num - Replace form feeds, filling rest of page with empty records assuming n lines per page [60]`
- `SWITCH: FRCBLK - Enforce block orientation on record oriented devices [FALSE]`
- `SWITCH: NOARCH - Disable the attempt to read archives (prevent multiple opens to the same file) [FALSE]`