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,RENAME='str',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:

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