#### CHAR

#### Synopsis

    HELP:   Read character data from memory
    TYPE:   OBJECT
    SYNTAX: CHAR(BLKSIZE=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[{}...],TABLE(),AVSCAN())

#### Description

Format char reads the byte stream for character conversion. There is no delimiter parsing. The data stream is simply split into block elements defined by the block size parameter.

The character data is converted from the provided CCSID to UTF-8. If no CCSID is provided, a system-dependent process is used to find the default CCSID. First, if available, the stored CCSID from the filesystem is used. If this is not successful, the environment variable LANG is used to determine the default CCSID. If this fails too, ISO-8859-1 (Latin-1) is used on a ASCII and IBM-1047 (Open Systems Latin-1) on EBCDIC systems.

During the character conversion, these options are supported:

- 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
- Auto detection of charsets

#### Arguments

- `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)`