HELP: Activate ARMOR encoding and defines corresponding parameter TYPE: OBJECT SYNTAX: ARMOR(FORMAT=OFF/STD/EXT,HEADER='str',VERSION='str',COMMENT='str')
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:
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.
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]