#### TEXT

#### Synopsis

    HELP:   Write text data to a file
    TYPE:   OBJECT
    SYNTAX: TEXT(NET.{},FILE='str'/STREAM/DUMMY,FALLOC(),REMOVE,REMAIN,APPEND,FLUSH,METHOD=HOST/BIN/REC/TXT/NL/USS/LF/UNIX/CR/OLDMAC/CRLF/WINDOWS/SYSTEM/ORIGINAL/L4I/L4X/B4I/B4X/S4I/S4X/HLI/HLX/HBI/HBX/HSI/HSX/DLM,RPLTAB/RPLHTB[=num],RPLVTB[=num],RPLBSP,RPLCTR=SPACE/SUBSTITUTE/DELETE,SUPCTR,SUPTWS,CCSID='str'/DEFAULT/ASCII/EBCDIC/SYSTEM/LOCAL,CASE=UPPER/LOWER/FOLD/SUPPER/SLOWER/USRTAB,BOM,KEPBOM,ELF2NL,CHRMODE=STOP/IGNORE/SUBSTITUTE/IDENTITY/TRANSLIT,SUBCHAR[num/SYSTEM...],SYSTABLE=ICONV,USRTABLE='str'/NPAS/SEPA/DELA/DLAX,ONEMAP,COMBINED=NFD/NFC/AUTO/ON/OFF,REPORTFILE='str'/STDOUT/STDERR,REGEXP(),COMPRESS/CMP.{},ENCRYPT/ENC.{},ENCODE/COD.{},ARCHIVE/LIB.{},PRNCONTROL=DETACH/RETAIN/ERASE/REPLACE,RPLFFD[=num],FRCREC,LANG='str',PLATFORM=WIN/UNX/ZOS/USS/VSE/BS2/MAC,OWNER='str',ENVID='str',DUMP,HASH(),SIGNATURE.{},INDSIZ=num,INDCHR=SPACE/TABULATOR,NOCMNT,NOMKDIR,TABLE(),ATTRIB(),AVSCAN(),PREPROCESS[()...],POSTPROCESS/PSTPRO[()...])

#### Description

Write text formats UTF-8 text elements into a list of records / lines, each terminated by a delimiter. These text records are converted to a character set defined by the CSSID. The resulting record list can optionally be compressed, encrypted and/or encoded and is written or appended to the specified file on a local or remote system.

Text formatting also supports:

- Different methods to define the record/line delimiter
- Suppression of trailing whitespace
- Replacement of horizontal tabs by whitespace characters
- Suppression or replacement of remaining control characters
- Validation of or replacements in records using regular expressions

During character conversion these options are supported:

- Stopping, ignoring or substitution when encountering an invalid or incomplete character
- A freely 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 character 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 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=HOST/BIN/REC/TXT/NL/USS/LF/UNIX/CR/OLDMAC/CRLF/WINDOWS/SYSTEM/ORIGINAL/L4I/L4X/B4I/B4X/S4I/S4X/HLI/HLX/HBI/HBX/HSI/HSX/DLM - Method for text formatting [SYSTEM]`
  - `HOST - Adds no delimiter (HOST)`
  - `BIN - Adds no delimiter (HOST)`
  - `REC - Adds no delimiter (HOST)`
  - `TXT - Adds the system specific delimiter (DEFAULT)`
  - `NL - Adds delimiter new line (USS)`
  - `USS - Adds delimiter for USS (new line)`
  - `LF - Adds delimiter line feed (UNIX)`
  - `UNIX - Adds delimiter for UNIX (line feed)`
  - `CR - Adds delimiter carriage return (MAC)`
  - `OLDMAC - Adds delimiter for old MACs (carriage return)`
  - `CRLF - Adds delimiter carriage return line feed (WIN)`
  - `WINDOWS - Adds delimiter for WINDOWS (carriage return line feed)`
  - `SYSTEM - Adds the system specific delimiter (DEFAULT)`
  - `ORIGINAL - Adds the original data at the end of a line (only for band FMT)`
  - `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 binary record delimiter`
- `NUMBER: RPLTAB/RPLHTB=num - Replace horizontal tabulators by spaces using this tab width [0 - no replacement]`
- `NUMBER: RPLVTB=num - Replace vertical tabulators by new lines using this tab width [0 = no replacement]`
- `SWITCH: RPLBSP - Replace backspace (deletes the backspace and the byte before) [FALSE]`
- `NUMBER: RPLCTR=SPACE/SUBSTITUTE/DELETE - Replace remaining control characters [NONE]`
  - `SPACE - Replace control characters with whitespace character (0x20/0x40)`
  - `SUBSTITUTE - Replace control characters with substitution character (0x1A/0x3F)`
  - `DELETE - Remove control characters`
- `SWITCH: SUPCTR - Suppress control characters [FALSE] (RPLCTR=DELETE)`
- `SWITCH: SUPTWS - Suppress trailing whitespaces [FALSE]`
- `SWITCH: KEPBOM - Keep byte order mark for faster conversion`
- `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: DUMP - Write text dump of binary data [FALSE]`
- `NUMBER: INDSIZ=num - Number of XML indentation characters per indentation level [2 (SPACE) or 1 (TAB)]`
- `NUMBER: INDCHR=SPACE/TABULATOR - Indentation character used to indent XML tags [SPACE]`
  - `SPACE - Use the space character as indentation character`
  - `TABULATOR - Use the tabulator character as indentation character`
- `SWITCH: NOCMNT - Do not write out XML comments [FALSE]`
- `SWITCH: NOMKDIR - Don't create path if path not exists [FALSE]`