#### ARMOR

#### Synopsis

    HELP:   Activate ASCII Armor encoding
    TYPE:   OBJECT
    SYNTAX: ARMOR(FORMAT=OFF/STD/EXT,CHRSET=NONE/SYSTEM/ASCII/UCS1/UTF8/EBCDIC/UCS2BE/UTF16BE/UCS2LE/UTF16LE/UCS4BE/UTF32BE/UCS4LE/UTF32LE/LOCAL,DELIM/RECDLM=HOST/BIN/TXT/NL/USS/LF/UNIX/CR/OLDMAC/CRLF/WINDOWS/DLM/SYSTEM,COMMENT='str')

#### Description

The overlay 'encode' can be used to convert the output data using one of a couple of base encoding schemes, resulting in printable text. Base encoding data results in expansion of the data. The ratio of expansion depends on the base used.

Currently, Base16 (hexadecimal), Base32 and Base64 encodings are supported. Each of them is an object with further configurations options.

Most base encoding schemes append some padding bytes to the end of output data to pad it to a multiple of a specific length. As a result, encoding can be performed in one of two modes:

The block mode converts the data as one large block of data. Padding will only be added at the end of the output file. This mode is the default for all write modes except for 'write.record()'. This implies that record-based data will not retain the old record boundaries after encoding. As the output is printable text when encoding, it can optionally be split into multiple lines. The 'line' parameter specifies after how many characters a line is wrapped. The line delimiter can be configured via the 'delim' parameter. By default, the system-specific delimiter is used.

When writing record-oriented (write.record()), each output line results in one record. Note that if the 'line' parameter is specified and a line delimiter is set, then the total maximum record length will be line length plus the length of the delimiter.

In record mode (default for wrote.record()), each output record is encoded independently, which results in retaining the ability to access specific records by only decoding those specific records. Each output record is padded as required by the respective encoding scheme. Due to base encoding resulting in expansion of the data, the resulting records will be longer after encoding and shrink when decoding. A file that has been encoded in record mode, must also be read in record mode subsequently to decode the data correctly. Otherwise, the result might be garbage.

The character set used (ASCII (UTF-8) or EBCDIC) can also be configured. By default, the system-specific default character set is used.

Optionally, there is support for ASCII/EBCDIC armor headers and trailers around the base encoded data. This feature is mainly required to encode and decode PGP files (see RCF4880), but can also be used for other data and is independent of the encoding method (Base16/32/64). ASCII-armored data data is wrapped into lines, which can be written as records or as blocks with lines and delimiters. The default line length is 72 if no length is specified.

The special OpenPGP encoding creates an ASCII armor output conforming to RFC4880 including the checksum. If you don't want the optional CRC24 checksum or if you want to use a line length other than 76, the Base64 encoding object with ASCII armor enabled should be used.

Additionally, a CRC checksum can be appended to the encoded data using the mechanism defined for OpenPGP. For Base64, CRC24 is used (RFC4480). For all other encoding schemas, CRC variants are used that match the schema's block size. Therefore, Base16 use CRC32 and Base32 uses CRC40, known from the GSM network. The CRC calculation is optional and independent of the data, encoding schema and the ASCII armor support. When reading, the verification is only done, if the corresponding switch is enabled, because it make no sense to consume CPU cycles for the CRC calculation and at the end, there is no checksum found to compare the calculated value.

#### Arguments

- `NUMBER: FORMAT=OFF/STD/EXT - Format of ARMOR header (which information is printed) [EXT]`
  - `OFF - Disable the printout of key value lines in ARMOR header`
  - `STD - Only the standard key value pairs (Version, Comment, Chrset) for ARMOR header`
  - `EXT - All available key value pairs are printed to ARMOR header (required for archiving)`
- `NUMBER: CHRSET=NONE/SYSTEM/ASCII/UCS1/UTF8/EBCDIC/UCS2BE/UTF16BE/UCS2LE/UTF16LE/UCS4BE/UTF32BE/UCS4LE/UTF32LE/LOCAL - Character set [SYSTEM]`
  - `NONE - No character set defined`
  - `SYSTEM - SYSTEM (environment specific (on mainframe EBCDIC else ASCII))`
  - `ASCII - ASCII (mainly used in the for open system)`
  - `UCS1 - UCS-1 (for text formatting identical to ASCII < 64k)`
  - `UTF8 - UTF-8 (for text formatting identical to ASCII < 2M)`
  - `EBCDIC - EBCDIC (mainly used on IBM mainframe)`
  - `UCS2BE - UCS-2 Big Endian (multibyte character set < 64k)`
  - `UTF16BE - UTF-16 Big Endian (multibyte character set < 2M)`
  - `UCS2LE - UCS-2 Little Endian (multibyte character set < 64k)`
  - `UTF16LE - UTF-16 Little Endian (multibyte character set < 2M)`
  - `UCS4BE - UCS-4 Big Endian (multibyte character set < 64k)`
  - `UTF32BE - UTF-32 Big Endian (multibyte character set < 2M)`
  - `UCS4LE - UCS-4 Little Endian (multibyte character set < 64k)`
  - `UTF32LE - UTF-32 Little Endian (multibyte character set < 2M)`
  - `LOCAL - LOCAL (platform specific (on mainframe EBCDIC else ASCII))`
- `NUMBER: DELIM/RECDLM=HOST/BIN/TXT/NL/USS/LF/UNIX/CR/OLDMAC/CRLF/WINDOWS/DLM/SYSTEM - Line delimiter to use when mode is BLOCK and line>0 [SYSTEM]`
  - `HOST - Adds no delimiter (HOST)`
  - `BIN - 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)`
  - `DLM - Adds the system specific delimiter (DEFAULT)`
  - `SYSTEM - Adds the system specific delimiter (DEFAULT)`
- `STRING: COMMENT='str' - Define comment for ARMOR header [default]`