#### CHARACTER

#### Synopsis

    HELP:   Write character data to a file
    TYPE:   OBJECT
    SYNTAX: CHARACTER(NET.{},FILE='str'/STREAM/DUMMY,FALLOC(),REMOVE,REMAIN,APPEND,FLUSH,METHOD=L4I/L4X/B4I/B4X/S4I/S4X/HLI/HLX/HBI/HBX/HSI/HSX/DLM,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],FRCREC,CCSID='str'/DEFAULT/ASCII/EBCDIC/SYSTEM/LOCAL,CASE=UPPER/LOWER/FOLD/SUPPER/SLOWER/USRTAB,BOM,KEPBOM,CHRMODE=STOP/IGNORE/SUBSTITUTE/IDENTITY/TRANSLIT,ELF2NL,SUBCHAR[num/SYSTEM...],SYSTABLE=ICONV,USRTABLE='str'/NPAS/SEPA/DELA/DLAX,ONEMAP,REPORTFILE='str'/STDOUT/STDERR,COMBINED=NFD/NFC/AUTO/ON/OFF,COMPRESS/CMP.{},ENCRYPT/ENC.{},ENCODE/COD.{},ARCHIVE/LIB.{},LANG='str',PLATFORM=WIN/UNX/ZOS/USS/VSE/BS2/MAC,OWNER='str',ENVID='str',HASH(),SIGNATURE.{},NOMKDIR,TABLE(),ATTRIB(),AVSCAN(),PREPROCESS[()...],POSTPROCESS/PSTPRO[()...])

#### Description

Write character formats all UTF-8 text elements to one block. With this UTF-8 based text block a character set conversion is done. After this such block can then optionally compressed, encrypted and encoded and is written or appended to the specified file on a local or remote system.

During the character conversion it supports:

- 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

For compression, encryption, encoding and archiving, one of the supported methods can be used. For each of these methods, specific parameters can be set to control the outbound conversions.

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 a standard CSV (comma separated value) format is written. 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: METHOD=L4I/L4X/B4I/B4X/S4I/S4X/HLI/HLX/HBI/HBX/HSI/HSX/DLM - Method to convert records in blocks [NONE]`
  - `L4I - Adds 4 byte length fields: Little endian integer, length inclusive`
  - `L4X - Adds 4 byte length fields: Little endian integer, length exclusive (ZIP)`
  - `B4I - Adds 4 byte length fields: Big endian integer, length inclusive`
  - `B4X - Adds 4 byte length fields: Big endian integer, length exclusive (USS)`
  - `S4I - Adds 4 byte length fields: System endian integer, length inclusive`
  - `S4X - Adds 4 byte length fields: System endian integer, length exclusive (VAR)`
  - `HLI - Adds 4 byte length fields: Little endian short (LL00), length inclusive`
  - `HLX - Adds 4 byte length fields: Little endian short (LL00), length exclusive`
  - `HBI - Adds 4 byte length fields: Big endian short (LL00), length inclusive (MVS)`
  - `HBX - Adds 4 byte length fields: Big endian short (LL00), length exclusive`
  - `HSI - Adds 4 byte length fields: System endian short (LL00), length inclusive`
  - `HSX - Adds 4 byte length fields: System endian short (LL00), length exclusive`
  - `DLM - Adds provided binary record delimiter`
- `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 [system]`
  - `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: FRCREC - Enforce record orientation on record oriented devices [FALSE]`
- `SWITCH: KEPBOM - Keep byte order mark for faster conversion`
- `SWITCH: NOMKDIR - Don't create path if path not exists [FALSE]`