HELP: Read format string for FLUC byte, stream and record interfaces
TYPE: OVERLAY
SYNTAX: > flcbyt READ-FORMAT.{BINARY()/CHAR()/TEXT()/XML()/RECORD()/TABLE()/ELEMENT()}
When reading data via the byte or record interface, you can specify how to format the data (binary, character, text, xml, ...), use different conversions (Base64, OpenPGP, GZIP, CHRSET, ...) executed sequentially and different kinds of I/O methods (block, record, text, FLAM4, ...). This means that you can read compressed, encrypted and encoded files, where you can change the character set and other things as part of the read operation.
Through the format string of our application programming interfaces, you specify how the data is transformed into a sequential data stream, records or FLAM5 elements before being stored in application memory. For example, if the data contains text, you can specify which delimiter to add after each line, which character set the output should be in and so on.
For stream-oriented data handling, you can choose between binary, character, text and XML formatting. For read operations, you can use the auto detection capabilities. For example:
fcbopen("read.file='filename'","format.record()")
This results in any kind of file (encoded, encrypted and/or compressed) being converted to records. If the content is XML, then the XML data is pretty printed into records. If it is text, then the data is parsed based on the containing delimiters. If it is binary and record lengths are detected, then the records are provided one by one. If it is binary and no record lengths are known or detected, then the data is wrapped into records.
If you use record formatting, then the read and write functions do not operate like in stream-oriented I/O. Instead, the behavior is more similar to the fread (GET) and fwrite (PUT) operations in z/OS with 'type=record', except that you can define whether records are truncated (size>0) or a length error occurs (size==0) of the provided buffer is too short. With size=-1 (SIZE_MAX), there is also a zero-copy mode for optimized performance (LOC).
The record formatting can be useful for normal text files to read the text record-by-record without the delimiter and null termination at the end.
FLAM5 elements are parsed data elements with a type, a length, a value and more. If the element data contains printable characters, then these characters are encoded in UTF-8 by default, but can also be converted as needed.
With element formatting, you can read and write a serialized form of FLAM5 elements. For example, it can be used to tokenize an XML document and read these tokens (elements) for further processing.
The format string uses the syntax of the 'format' union which was specifically designed for the byte and record interface to format a byte stream based on the FLAM elements. The zero-terminated string must start with 'format.' followed by the corresponding method.
"format.text(method=CRLF suptws ccsid='UTF-16LE')" "format.bin()" "format.char(ccsid=DEFAULT)" "format.record(ccsid='IBM-1141')" "format.element(ccsid=1047)"
The file string defines how the FLAM elements are read from or written to the file. The format string defines how the FLAM elements are converted into a byte stream, records or elements.