### WRITE-FORMAT

#### Synopsis

    HELP:   Write format string for FLUC byte, stream and record interfaces
    TYPE:   OVERLAY
    SYNTAX: > flcbyt WRITE-FORMAT.{BINARY()/CHAR()/TEXT()/XML()/RECORD()/TABLE()/ELEMENT()}

#### Description

When writing data via the byte or record interface, you can define 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 write compressed, encrypted and encoded files, where you can change the character set and other things as part of the write operation.

Through the format string of our application programming interfaces, you specify in which format your application passes its data to the interface, be it a sequential data stream, records or FLAM5 elements. For example, if you pass text records, you can define which delimiter to add after each line, which character set the output should be in and so on to write a text file correctly formatted for the target platform.

For stream-oriented data handling, you can choose between binary, character, text and XML formatting.

#### Record formatting

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).

#### Element formatting

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 produce a well-formed XML document from a sequence of XML tokens.

#### Examples

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.