#### ARMOR

#### Synopsis

    HELP:   Activate ARMOR encoding and defines corresponding parameter
    TYPE:   OBJECT
    SYNTAX: ARMOR(FORMAT=OFF/STD/EXT,HEADER='str',VERSION='str',COMMENT='str')

#### Description

The ARMOR object activates ASCII armor encoding. Depending on the specified CHRSET, it may also use EBCDIC encoding. ASCII armored data is Base64 encoded binary data followed by an optional checksum, surrounded by a header and trailer. For this you can set the header, version and comment strings illustrated in the example below:

    -----BEGIN header string-----
    Version: version string
    Comment: comment string

    yDgBO22WxBHv7O8X7O/jygAEzol56iUKiXmV+XmpCtmpqQUKiQrFqclFqUDBovzS
    vBSFjNSiVHsuAA==
    =njUN
    -----END header string-----

The header data is usually set by the previous component in a meaningful way. Therefore, we recommend not to overwrite these values, especially when using the PGP converter. But sometimes it could be required that not all private extensions are written. In this case you can set the FORMAT parameter to OFF to prevent such key value pairs or to STD to include only the version, comment and if available the charset.

In general, it only makes sense to set the header data if none is set by another component (e.g. after reading binary). In this case, the default header is the current data type BINARY/RECORD/TEXT/..., the version is the current FLAM version and the comment the current default comment.

Applying ASCII armor on an XML file would yield a result similar to the example below:

    -----BEGIN XML DATA-----
    Version: FLAM: 5.1.8.10219
    Comment: created with FLUCv5.1.8.10219 (www.flam.de)
    Charset: UTF-8

    PD94bWwgdmVyc2lvbj0iMS4wIj8+CjwhRE9DVFlQRSB0ZXN0IFsKPCFFTEVNRU5UIHRlc3Qg
    KCNQQ0RBVEEpPgo8IUVOVElUWSBhYSAiJiMzNzt6ejsmYW1wO2FhOyI+CjwhRU5USVRZICUg
    eHggIiYjMzc7eno7Ij4KPCFFTlRJVFkgJSB6eiAiPCFFTlRJVFkgdHJpY2t5ICYjMzQ7ZXJy
    b3ItcHJvbmUmIzM0OyA+Ij4KPCFOT1RBVElPTiBub3RhdGlvbk5hbWUgU1lTVEVNICJzeXN0
    ZW1JZCV6ejsmYW1wOyYjMzQ7Ij4KPCFOT1RBVElPTiBub3RhdGlvbk5hbWUgUFVCTElDICJw
    dWJsaWNJZCIgInN5c3RlbUlkJiMzNDsiPgoleHg7CiV4eDsKXT4KPHRlc3Q+VGhpcyBzYW1w
    bGUgc2hvd3MgYSAmdHJpY2t5OyBtZXRob2QuPC90ZXN0Pg==
    -----END XML DATA-----

If you activate the ARMOR object and no line length is specified, then a default of 72 is used. ASCII armor can be applied to block- or record- oriented data.

When reading, header and trailer are stripped away and the decoded data is passed to the next component. If no header is found, only the decoding is done. To verify that trailer contains the same string used in the header, you must enable a switch.

The base encoding component also supports the optional CRC24 checksum for Base64 defined in RFC4880. For the other base encoding schemas, CRC checksum lengths are used that match the respective block size.

The same XML example as above, but with a CRC24 checksum, looks like this:

    -----BEGIN XML DATA-----
    Version: FLAM: 5.1.8.10233
    Comment: created with FLUCv5.1.8.10233 (www.flam.de)
    Charset: UTF-8

    PD94bWwgdmVyc2lvbj0iMS4wIj8+CjwhRE9DVFlQRSB0ZXN0IFsKPCFFTEVNRU5UIHRlc3Qg
    KCNQQ0RBVEEpPgo8IUVOVElUWSBhYSAiJiMzNzt6ejsmYW1wO2FhOyI+CjwhRU5USVRZICUg
    eHggIiYjMzc7eno7Ij4KPCFFTlRJVFkgJSB6eiAiPCFFTlRJVFkgdHJpY2t5ICYjMzQ7ZXJy
    b3ItcHJvbmUmIzM0OyA+Ij4KPCFOT1RBVElPTiBub3RhdGlvbk5hbWUgU1lTVEVNICJzeXN0
    ZW1JZCV6ejsmYW1wOyYjMzQ7Ij4KPCFOT1RBVElPTiBub3RhdGlvbk5hbWUgUFVCTElDICJw
    dWJsaWNJZCIgInN5c3RlbUlkJiMzNDsiPgoleHg7CiV4eDsKXT4KPHRlc3Q+VGhpcyBzYW1w
    bGUgc2hvd3MgYSAmdHJpY2t5OyBtZXRob2QuPC90ZXN0Pg==
    =3m94
    -----END XML DATA-----

To verify the checksum, a switch must be enabled as it is not verified by default. Since the checksum is optional, it is useless to calculate the CRC just to find out that there is no CRC appended to the data that can be compared against.

An empty file that has been ASCII-armored consists of a header and trailer plus optional CRC checksum (00...00), only. Such a file is not detected automatically as ASCII-armored when trying to read it. It will be handled as normal text file with delimiters. To read such a file as base encoded without any data, you must set the correct decoding method.

    -----BEGIN EMPTY FILE-----
    Version: TEST VERSION
    Comment: TEST COMMENT

    =00000000
    -----END EMPTY FILE-----

From the perspective of auto detection, such a file is a simple text file. Files are only detected as ASCII-armored if they contain some actual data.

Example for activating ASCII-armor encoding with CRC checksum:

     CONV: encode.base64(chrset=ASCII crcchk armor())
     XCNV: cnv.bas(method=base64 chrset=ASCII crcchk armor())

When using the ASCII armor feature together with a binary and block- oriented format (PGP, GZIP, BZIP2, ...), then, by default, several file attributes are added. This allows FLAM to restore host datasets from an ASCII armored file. The keywords below are supported:

- Format: BINARY/RECORD/RECTXT/CHAR/TEXT/XML
- Charset: Encoding string (IBM-1141/UTF-8/...)
- Platform: free text (e.g. Linux on x86 with 64 bit (linx64d0))
- BinaryDelimiter: Hex-value for a binary record delimiter (DLM)
- LengthField: L4X/L4I/B4X/B4I/HBX/HBI/HLX/HLI (see FMT.REC(METHOD))
- TextDelimiter: Hex value for a text record delimiter (TXT)
- FileOrganization: SEQ/RDS/KDS/EDS/... (see FIO.REC(FILORG))
- BlockSize: decimal value for the block size
- RecordFormat: (see FIO.REC(RECFMT))
- RecordLength: decimal value for the record length
- KeyLength: key length of VSAM KSDS
- KeyPosition: key position of VSAM KSDS
- SlotNumbers: Yes (8 byte slot number of an RRDS in front of the record)
- PrintControl: Yes (1 byte print control character in front of the record)

The printed values are decimal numbers or keywords used by FLCL. You can find a detailed description for each keyword if you search for it in this document. Below you can see an example for a PS-VBA dataset archived in a BZIP2 file using L4X length field for record separation:

    flcl conv
       read.record(file='TST.IDAT.PSVBA')
       write.record(file='.ODAT.BZ2ARMOR.PSVBA'
                 prnc=retain comp.bzip()
                 encode.armor(delim=host))

    -----BEGIN BZIP2 FILE-----
    Version: FL-CNVBZ2 5.1.16.13587
    Comment: created with FLUCv5.1.12.13587 (www.flam.de)
    Format: RECTXT
    Platform: z/OS on SystemZ with 31 bit (zosz31d0)
    LengthField: L4X
    FileOrganization: SEQ
    BlockSize: 27998
    RecordFormat: VBA
    RecordLength: 132
    PrintControl: Yes

    QlpoMTFBWSZTWYtmr+UAA1P/9//w1hSpv5ACTDurJ2qOwlP/4A/gHsA/4D/gH+B/4FAErwAVVNsw
    hIDUCT1MozQ1DR6mEaGh6NQ09TQyZAaBoAAAGQ0AaA0aBqaaKeKn6aMhMQkeUAAAaGhoA0AAAAAD
    QyNDQaHAAAAAAAAAAAAAAAAAAAAMg4AAAAAAAAAAAAAAAAAAABkCRJMSZNATQmmpvU0m0gANNMgD
    ...
    ...
    ...
    bbJcqpYVaUMnpoO1hiyaT2Pg73d73s/aqL4FT6+NwTmyE9asiTfw8G0t1fcqQoVhyjaJrodG+xbx
    HNmorJ8tWdG2262H95oz3Xjd2Crd0lF3yq2irWmlSyTvyNbykpygJrCs9lbeS4bscRmWL/xdyRTh
    QkItmr+U
    =XcB6
    -----END BZIP2 FILE-----

With the FORMAT parameter you can deactivate these extensions.

#### 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)`
- `STRING: HEADER='str' - String for the header [AUTO]`
- `STRING: VERSION='str' - Version string as key value [AUTO]`
- `STRING: COMMENT='str' - Comment string as key value [AUTO]`