ELEMENT

Synopsis

HELP:   Read FLAM5 element structures from memory
TYPE:   OBJECT
SYNTAX: ELEMENT(MATRIX=NONE/DATBLK/STDREC/STDASAREC/STDMCCREC/RELREC/RELASAREC/RELMCCREC/TXTREC/TXTDLM/TXTRST/XMLELM,ELMCOUNT=num,CCSID='str'/DEFAULT/ASCII/EBCDIC/SYSTEM/LOCAL,CASE=UPPER/LOWER/FOLD/SUPPER/SLOWER/USRTAB,USRTABLE='str'/NPAS/SEPA/DELA/DLAX,ONEMAP,COMBINED=NFD/NFC/AUTO/ON/OFF,ENDIANNESS=SYSTEM/BIG/LITTLE/LOCAL)

Description

FLAM5 elements are parsed data elements with a type, a length, a value and more. The element formatter reads a serialized FLAM5 element from application memory and collects multiple elements to fill a matrix (vector).

One use case is, for example, to read XML elements from memory and write them to an XML file with correct XML syntax.

To write an element, the data passed to the element formatter must 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.

The element count specifies how many elements are collected internally before they are converted to the output format and written to the destination. If this value is not set, a default is used that depends on the matrix type. For data blocks the default element count is 1, for text records with rest element it is 256 and for all other matrix types the limit is 128.

The data fields must be provided in the corresponding neutral form which is expected by the write operation. Some metadata can be passed when opening a file by means of a state string. If you provide elements containing text data fields in another codepage than the local character set, you can define the correct inbound CCSID (e.g. UTF-8) via the state string or in the format.element() clause. If no CCSID is provided, then the inbound CCSID is not defined then the local character set is assumed at write and the string is converted to UTF-8. The default CCSID for text data fields of neutral FLAM5 elements is UTF-8. If no character conversion requested at read, then the UTF-8 strings are returned.

The element formatting object supports character set conversion from a certain CCSID to UTF-8. If the CCSID is set to UTF-8, no character conversion is done on the input data, but the character set is now known to FLAM and all other conversions (e.g. appending of the correct line delimiter) are done in the right manner.

Character conversion is, for example, required for XML elements which are not in UTF-8. So, if you wish to write an XML file based on your XML element that you passed to the element formatter and the element data is EBCDIC encoded, you would use a format string similar to format.element(ccsid=IBM1047) and a file string similar to write.xml(file=output.xml). This results in your element data being converted from IBM1047 to UTF-8 and passed to the XML writer which generates XML documents in UTF-8 by default.

Arguments