ELEMENT

Synopsis

HELP:   Write FLAM5 element structures to memory
TYPE:   OBJECT
SYNTAX: ELEMENT(CCSID='str'/DEFAULT/ASCII/EBCDIC/SYSTEM/LOCAL,CASE=UPPER/LOWER/FOLD/SUPPER/SLOWER/USRTAB,CHRMODE=STOP/IGNORE/SUBSTITUTE/IDENTITY/TRANSLIT,SUBCHAR[num/SYSTEM...],SYSTABLE=ICONV,USRTABLE='str'/NPAS/SEPA/DELA/DLAX,ONEMAP,COMBINED=NFD/NFC/AUTO/ON/OFF,ENDIANNESS=SYSTEM/BIG/LITTLE/LOCAL)

Description

When reading from a file with FLAM, the file's original data is transformed into an internal FLAM5 element list. The type and contents of elements depends on how the original file was read.

With element formatting, you can get a serialized form of those FLAM5 elements. Elements that have been created when reading the file are serialized into a specific structure and written into a given piece of memory.

For example, element formatting can be used to get the XML elements produced by the read.xml() file input method that tokenizes the XML document. These XML elements (tokens) can then be used for further processing.

As mentioned, the serialized elements have a certain structure. The first four bytes (32 bits) are a version field. The version field is always the first field and determines the fields of the rest of the structure.

Currently, there is only one version (0) of the serialized element structure. It consists of the 4 byte integer fields below followed by a concatenation of the corresponding data fields (attributes, data, hash values) in the same order as the length fields.

The presence and contents of attributes, data and hash values depend on the combination of matrix and element type. The available matrix and element types and further details can be found in the API documentation for the FLMDEF.h header (contained for example in the FLCBYT or FLCRECLB documentation). Note that hash values are currently only used with FLAM5 archives and not relevant for other data.

If, for example, records containing ASA control characters are read, the data portion of the structure is the concatenation of the (binary) ASA control character (which is the attribute), followed by the character data of the record (the data portion). Please be aware that the control character is treated as a binary value (EBCDIC) and that the character data is, by default, encoded in UTF-8.

By default and when using one of the read.*() operations for reading, the data fields are encoded in a neutral form which is UTF-8 if the element contains text data.

You can set a different CCSID in the format.element() object to get text data fields encoded in another character set. Please be aware that certain character sets like UTF-16 or UTF-32 result in an expansion of the data. If you choose a single byte character set (EBCDIC or ASCII) then some element may be shorter after conversion. You can specify to ignore, substitute or transliterate characters which a character is not representable in the target character set. If you use DEFAULT keyword for the CCSID, then the local character set is used.

Arguments