## API Strings

The additional CLP strings below are available in the following APIs:

- FLUC byte interface for C (FLCBYT)
- FLUC record interface for COBOL/PL1/HLAS (FLCREC)
- FLUC stream buffer interface for C++ (FLCBYTBF)
- FLUC stream class interface for Java (FLCBYTJS)

When opening a file through these APIs, a format string must be passed to describe the format in which data is returned (read mode) or expected (write mode) by the respective interface. A state string containing some additional meta data is returned by (read mode) or can be passed to (write mode) the file open function. To read or write a file through these interfaces, the 'READ' and 'WRITE' overlays of the 'CONV' command or the 'INPUT' and 'OUTPUT' object of the 'XCNV' command can be used in the corresponding file open function (ASM/C/COBOL/PL1) or constructor (C++/Java).

    void* file1=fcbopen("read.file='test.txt.gz.pgp'","format.text(ccsid=DEFAULT)")
    void* file2=fcbopen("input(sav.fil(fio.rec(name='DD:INPUT')))","format.record()")

If format.element() is used, some data conversions can be applied on a per-element basis. Conversions are applied when using the read or write functions of the byte/record interface that end with the letter v. These functions require the handle to a previously opened element converter. Multiple different element converters can be open at a time. To open a converter, a conversion string must be supplied. The 'read' conversion string describes how an element data type read from application memory is converted to the internal neutral FLAM5 representation. The 'write' conversion string defines how a neutral FLAM5 element is written to application memory when reading from a file.

    void* conv1=fcbopenv(file1,"write.string(ccsid=DEFAULT whitespace=collapse)")
    void* conv2=fcbopenv(file2,"conv.integer(from(format.str(chrset=EBCDIC)) to(format.bin(width=w32 endian=big)))")

A from-to conversion string can be used to convert data types, e.g. numbers, between different representations. This could be used, for example, to convert the string representation of a number that was read from an XML file to a binary or BCD representation or a string of fixed length.

    void* file1=fcbopen("read.xml(file='DD:INPUT'","format.element()")
    void* kyw1=fcbopenv(file1,"write.string(ccsid=DEFAULT whitespace=collapse nullterm)")
    void* int2=fcbopenv(file1,"conv.integer(from(format.str(chrset=UTF-8)) to(format.bin()))")
    void* flt2=fcbopenv(file1,"conv.float(from(format.str(chrset=UTF-8)) to(format.bcd(SIGNED TYPE=ZONED INTDIGITS=8 FRACDIGITS=2)))")

The format strings are also used to configure the FLUC subsystem on z/OS and the FlucFS on Unix.