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:

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