FLCBYT-API FLUC Byte Interface

Functions
Functions

All public functions provided by the FLUC byte interface. More...

## Functions
const char * | fcbvsn (void)
| Retrieves version information. More...
const char * | fcbabo (void)
| Retrieves about information. More...
const char * | fcblic (void)
| Retrieves the license text. More...
int | fcbenv (const int sys, const int std, const char *env)
| Load the FLAM environment. More...
char * | fcbsym (const char *name, size_t size, char *string)
| Determines a symbol from environment. More...
int | fcbinfo (const char *infstr, const int format, size_t *bufsiz, char **buffer)
| Provides various information. More...
int | fcbopnlog (const char *logstr)
| Open the logging facility for in-memory logging. More...
int | fcbgetlog (const char **buffer)
| Get log information. More...
int | fcbclrlog (void)
| Clear the log information. More...
int | fcbclslog (void)
| Close the logging facility. More...
void * | fcbopen (const char *filstr, const char *fmtstr)
| Open file (without state management) More...
void * | fcbopen2 (const char *filstr, const char *fmtstr, char **state)
| Open file (with state management) More...
int | fcbclose (void *hdl)
| Close file (without statistics) More...
int | fcbclose2 (void *hdl, const int success, const int stafmt, size_t *stasiz, char **stabuf)
| Close file with return of statistics information. More...
const char * | fcbgtn (void *hdl)
| Returns the current table name. More...
const char * | fcbgfn (void *hdl, const int ind)
| Returns the current file name. More...
const char * | fcbstn (void *hdl, const char *name)
| Sets the current table format. More...
int | fcbflush (void *hdl)
| Flush internal buffers to the file. More...
void * | fcbnewmbr (void *hdl, const char *fmtstr, const char *state)
| Start with a new member in an open file. More...
void * | fcbnewmbr2 (void *hdl, const char *fmtstr, const char *state, const int stafmt, size_t *stasiz, char **stabuf)
| Start with a new member in a open file (with statistics information) More...
void * | fcbopenv (void *hdl, const char *cnvstr)
| Open converter. More...
int | fcbclosev (void *cnv)
| Close a converter. More...
size_t | fcbread (void *ptr, size_t size, size_t count, void *hdl)
| Read file data. More...
size_t | fcbreadv (void *ptr, size_t size, size_t count, void *hdl, void *cnv, const int skip)
| Read file data with conversion. More...
size_t | fcbwrite (const void *ptr, size_t size, size_t count, void *hdl)
| Write data to file. More...
size_t | fcbwritev (const void *ptr, size_t size, size_t count, void *hdl, void *cnv)
| Write data to file with conversion. More...
int | fcbprev (void *hdl)
| Sets the read position to the previous record or element. More...
int | fcbgetc (void *hdl)
| Gets the next character. More...
int | fcbungetc (int chr, void *hdl)
| Push a character back back to the stream. More...
int | fcbputc (int chr, void *hdl)
| Writes a character. More...
char * | fcbgets (char *str, int n, void *hdl)
| Reads a line. More...
int | fcbputs (const char *str, void *hdl)
| Writes a null-terminated string. More...
int | fcbconv (void *cnv, size_t inplen, const void *inp, size_t *outlen, void *out)
| Converts independent data blocks (with copy) More...
int | fcbconp (void *cnv, size_t inplen, const void *inp, size_t *outlen, void **out)
| Converts independent data blocks (with locate) More...
int | fcbrunv (void *cnv, size_t inplen, const void *inp, size_t *outlen, void *out)
| Converts dependent data blocks (with copy) More...
int | fcbrunp (void *cnv, size_t inplen, const void *inp, size_t *outlen, void **out)
| Converts dependent data blocks (with locate) More...
int | fcbfinv (void *cnv, size_t inplen, const void *inp, size_t *outlen, void *out)
| Finish conversion of dependent data blocks (with copy) More...
int | fcbfinp (void *cnv, size_t inplen, const void *inp, size_t *outlen, void **out)
| Finish conversion of dependent data blocks (with locate) More...
int | fcbeof (void *hdl)
| Returns the end-of-file (EOF) flag. More...
int | fcbeot (void *hdl)
| Returns the end-of-table (EOT) flag. More...
int | fcberror (void *hdl)
| Get error code. More...
const char * | fcberrms (int code)
| Get error message. More...
const char * | fcberrtr (void)
| Get error trace. More...
void | fcbclearerr (void *hdl)
| Clear error and EOF indicators. More...
const char * | fcbhelp (const int what, const int depth, const char *path)
| Returns help information about the file and format strings. More...
const char * | fcbsyntax (const int what, const int depth, const char *path)
| Returns syntax information about the file and format strings. More...
const char * | fcbcheck (const int what, const char *string)
| Check syntax for a certain CLP string. More...
long long int | fcbcount (void *hdl, const int direction, const int what, const int kind)
| Determine current amount of processed data. More...
void * | fcbbini (const unsigned int mode, const unsigned int base, const unsigned int chrs)
| Creates a handle for Base16/32/64 encoding or decoding. More...
int | fcbbrun (void *hdl, const int inlen, const unsigned char *in, unsigned char *out)
| En- or Decodes a data buffer. More...
int | fcbbfin (void *hdl, const int inlen, const unsigned char *in, unsigned char *out)
| Finalize en- or decoding. More...
int | fcbbase (const unsigned int mode, const unsigned int base, const unsigned int chrs, const int inlen, const unsigned char *in, unsigned char *out)
| Base encoding or decoding for one message. More...
void * | fcbhini (const unsigned int hmtd, const unsigned int kmtd, const unsigned int keylen, const unsigned char *key, const unsigned int icvlen, const unsigned char *icv)
| Initialize hash calculation. More...
int | fcbhadd (void *hdl, const unsigned int datlen, const unsigned char *dat)
| Adds a buffer of data to the hash calculation. More...
int | fcbhfin (void *hdl, unsigned int *hshlen, unsigned char *hsh)
| Finalize hash calculation. More...
int | fcbhash (const unsigned int hmtd, const unsigned int kmtd, const unsigned int keylen, const unsigned char *key, const unsigned int icvlen, const unsigned char *icv, const unsigned int datlen, const unsigned char *dat, unsigned int *hshlen, unsigned char *hsh)
| Calculate hash for a single buffer. More...

## Detailed Description

All public functions provided by the FLUC byte interface.

## Function Documentation

## ◆ fcbvsn()

const char * fcbvsn | ( | void |  | ) |

Retrieves version information.

This function returns a string with version information for each used component. This should be used in a support case.

Returns
  a pointer to a static area containing the zero-terminated version string

## ◆ fcbabo()

const char * fcbabo | ( | void |  | ) |

Retrieves about information.

This function returns a string with about information for this library on multiple lines and license information for used external libraries.

Returns
  a pointer to a static area containing the zero-terminated about string

## ◆ fcblic()

const char * fcblic | ( | void |  | ) |

Retrieves the license text.

This function can be used to get the current license text on multiple lines. The license text defines the permissible use of this library.

Returns
  a pointer to a static area with a zero-terminated string containing the current license text.

## ◆ fcbenv()

int fcbenv | ( | const int | sys,
|  | const int | std,
|  | const char * | env
| ) |  |

Load the FLAM environment.

This function loads the FLAM system variables (only on z/OS or in EDZ environment), the STDENV definitions ('DD:STDENV' or '<SYSUID>.STDENV' on z/OS or '.stdenv' file in working or home directory on other systems) and a optional list of variables to the environment. This must be called before any other FLAM API function to set the correct environment. This function allows to work with the same environment used by FLAM utilities, subsystems, etc.

Parameters

  [in] | sys | Non-zero value to load system variables, 0 otherwise
  [in] | std | Non-zero value to load standard environment, 0 otherwise
  [in] | env | Optional list (can be NULL or empty) of environment variables (KEYWORD=VALUE) separated by new line ('\n') or semicolon (';')

Returns
  negative (<0) error else (>=0) amount of environment variable load

## ◆ fcbsym()

char * fcbsym | ( | const char * | name,
|  | size_t | size,
|  | char * | string
| ) |  |

Determines a symbol from environment.

The function can be used to fetch the value of an environment variable, a JCL symbol (z/OS) or a system symbol (z/OS).

Parameters

  [in] | name | Name of the symbol
  [in] | size | Space for the output buffer
  [out] | string | Buffer for the output string

Returns
  a pointer to the symbol string or NULL if error

## ◆ fcbinfo()

int fcbinfo | ( | const char * | infstr,
|  | const int | format,
|  | size_t * | bufsiz,
|  | char ** | buffer
| ) |  |

Provides various information.

This function can be used to retrieve various information about files, supported CCSIDs and other things. You must provide an info string to define which information to request. You can define the format in which the information will be output. The information is written to a buffer which will be dynamically re-allocated by this function so that it fits all requested information.

The buffer can already be allocated before and must be freed by the calling application. If the buffer is allocated by the calling application, the first byte of the allocated buffer must be set to 0x0, as the data is appended to the first zero-terminated string. This can be used for example to include the generated XML into XML of a higher level.

The pointer to the buffer can point to a null pointer. In this case, the whole buffer will be allocated by this function and the output starts at offset 0.

The info definition string uses the same syntax as the get method of the FLCL INFO command. The complete syntax and help can be retrieved with the corresponding functions below. The null-terminated string must start with 'get.' followed by the corresponding method (file/ccsids/...). Leading whitespace is ignored.

Examples:

    "get.file='test.txt'"
    "get.ccsids"

Please use:

    'fcbhelp(FLC_INFO,10,NULL)'
    'fcbsyntax(FLC_INFO,10,NULL)'

for more information.

Parameters

  [in] | infstr | Info string with GET instructions
  [in] | format | Format specification for the output buffer (FLMOUT_FORMAT_*)
  [in,out] | bufsiz | Pre-allocated buffer size on input, is overwritten with final buffer size on output
  [in,out] | buffer | Pointer of pointer to a dynamically allocated buffer

Returns
  -1 if error or length of the data in the buffer

## ◆ fcbopnlog()

int fcbopnlog | ( | const char * | logstr | ) |

Open the logging facility for in-memory logging.

Enables in-memory logging. Messages that would normally printed to the console when using command line tools like FLCL are collected in-memory and can be queried when needed.

A CLP string can be passed to the function to control the identifier, format and messages to log. If no log string is passed, the minimal format and minimal messages are used by default. The logging facility is useful to catch warnings during operation. The functions fcbgetlog() and fcbclrlog() can be used to retrieve or clear the current log buffer contents. The logging facility must be closed with fcbclslog().

Parameters

  logstr | NULL or a CLP string for logging ("LOG(IDENT='str',FORMAT=STANDARD/DIALOG/MINIMAL,MESSAGE(WARN))")

Returns
  FLAM reason code or 0 on success

## ◆ fcbgetlog()

int fcbgetlog | ( | const char ** | buffer | ) |

Get log information.

Returns the maximum error code since the last call to fcbopnlog() or fcbclrlog(). Optionally, a read only buffer can be obtained by passing memory for storing the buffer pointer. The returned buffer contains the log messages separated by new line character and null-termination at the end.

Parameters

  buffer | If not NULL, a pointer to the log buffer is written to the provided memory

Returns
  The maximum error code logged

## ◆ fcbclrlog()

int fcbclrlog | ( | void |  | ) |

Clear the log information.

Clears the log buffer and resets the maximum error code to 0.

Returns
  The maximum error code logged

## ◆ fcbclslog()

int fcbclslog | ( | void |  | ) |

Close the logging facility.

Closes the logging facility, frees all associated resources and returns the maximum error code since the log was opened or cleared.

Returns
  The maximum error code logged

## ◆ fcbopen()

void * fcbopen | ( | const char * | filstr,
|  | const char * | fmtstr
| ) |  |

Open file (without state management)

This function opens a normal file, a member in a FLAM4FILE, a PGP file or a member in a concatenated GZIP-, BZIP- or XZ-File or some other supported file format. It supports base encoding, encryption, compression, character conversion and text, XML and table formatting, among others.

The file definition string uses the same syntax as the read or write method of the FLCL CONV command or the INPUT and OUTPUT specification of the XCNV command. The complete syntax and help can be determined with the corresponding functions below. The string must start with 'read.' or 'write.' followed by the corresponding method (binary/char/text/flam4/xml/...) or with input() or output() object specifications (leading whitespace is ignored).

Examples:

    "read.text(file='test.txt')"
    "write.binary(file='test.gz' comp.gzip(level=BEST))"
    "input(sav.fil(fio.blk(name='~.GZ.TEST') cnv.zip() cnv.chr(from=latin1 to=ibm1141) fmt.txt()))"
    "output(sav.fil(fmt.txt(method=host) fio.fl4(name='~.ADC.TEST')))"
    "write[flam(file='flamfile.adc' ccsid=IBM1141),text(file='testfile.zip' method=windows ccsid=CP1252 archive.zip())]"

The last example shows multiple writes of the same data one as FLAMFILE for IBM mainframes and another one as ZIP file for a Windows system.

Please use:

    'fcbhelp(FLC_READ_FILE,10,NULL)'
    'fcbsyntax(FLC_READ_FILE,10,NULL)'
    'fcbhelp(FLC_INPUT_FILE,10,NULL)'
    'fcbsyntax(FLC_INPUT_FILE,10,NULL)'
    'fcbhelp(FLC_WRITE_FILE,10,NULL)'
    'fcbsyntax(FLC_WRITE_FILE,10,NULL)'
    'fcbhelp(FLC_OUTPUT_FILE,10,NULL)'
    'fcbsyntax(FLC_OUTPUT_FILE,10,NULL)'

for more information.

The format string uses the syntax of the 'format' union which was specifically designed for the byte interface to format a byte stream based on the FLAM elements. The zero-terminated string must start with 'format.' followed by the corresponding method.

Examples:

    "format.text(method=CRLF suptws ccsid='UTF-16LE')"
    "format.bin()"
    "format.char(ccsid=DEFAULT)"
    "format.record(ccsid='IBM-1141')"
    "format.element(ccsid='IBM-1141')"

Please use:

    'fcbhelp(FLC_READ_FORMAT,10,NULL)'
    'fcbhelp(FLC_WRITE_FORMAT,10,NULL)'
    'fcbsyntax(FLC_READ_FORMAT,10,NULL)'
    'fcbsyntax(FLC_WRITE_FORMAT,10,NULL)'

for more information.

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.

Parameters

  [in] | filstr | File string with READ/INPUT/WRITE/OUTPUT instructions
  [in] | fmtstr | Format string with FORMAT instructions

Returns
  a pointer to a handle to manage file I/O, must be passed to subsequent functions or NULL in case of an error

## ◆ fcbopen2()

void * fcbopen2 | ( | const char * | filstr,
|  | const char * | fmtstr,
|  | char ** | state
| ) |  |

Open file (with state management)

This function works like fcbopen() with the capability to get the internal state after an open for read operation and to pass a previously read internal state for an open for write operation. The internal state can be used to transfer attributes/values/information from an fcbopen2("read."/"input()") to an fcbopen2("write."/"output()") or set these string for an fcbopen2("write."/"output()"). The object contains metadata like file attributes, data types and character set. These values are, among others, important to fill header information of archives like GZIP header or FLAM member headers.

The parameter is a pointer to a pointer to a string. In read mode, if you pass a non-null pointer, the pointer target will be a pointer to a null-terminated string dynamically allocated in heap memory (i.e. you must free() it!) containing the state string after this function returns. On write mode, if you pass a non-null pointer to a pointer to a state string, this state string is used to set the internal state. Otherwise, the state is initialized with default values.

You can look up the state string syntax and help with the corresponding functions below. The zero-terminated string must start with 'state(' followed by the corresponding value definitions and closed with ')'.

Example:

    "state(member='test.txt' recf=FBA recl=120)"

Please use:

    'fcbhelp(FLC_STATE,10,NULL)'
    'fcbsyntax(FLC_STATE,10,NULL)'

for more information.

Below you can find two examples:

1. Write only

       char* state="STATE(file='test.txt')";
       void* wrt=fcbopen2("write.text(comp.gzip())","format.text()",&state);

2. Read and write

       char* state=NULL;
       void* red=fcbopen2("read.text(file='test.txt')","format.text()",&state);
       void* wrt=fcbopen2("write.text(comp.gzip())","format.text()",&state);
       free(state);

In both cases, the member name for the original file in the GZIP header is 'test.txt'.

Parameters

  [in] | filstr | File string with READ/INPUT/WRITE/OUTPUT instructions
  [in] | fmtstr | Format string with FORMAT instructions
  [in,out] | state | Pointer to a pointer to a string with STATE values (You are responsible to free() the string in read mode!)

Returns
  a pointer to a handle to manage file I/O, must be passed to subsequent functions or NULL in case of an error

## ◆ fcbclose()

int fcbclose | ( | void * | hdl | ) |

Close file (without statistics)

Opened files must be closed through this function after read or write operations are completed. All internal buffers are flushed and all allocated resources are released.

Parameters

  [in] | hdl | File handle from fcbopen()

Returns
  Upon successful completion 0 is returned. Otherwise, EOF is returned and fcberrno is set to indicate the error.

## ◆ fcbclose2()

int fcbclose2 | ( | void * | hdl,
|  | const int | success,
|  | const int | stafmt,
|  | size_t * | stasiz,
|  | char ** | stabuf
| ) |  |

Close file with return of statistics information.

This function works like fcbclose() with the capability to define a success flag and get statistical information.

The 'success' flag is relevant in read or write mode. It allows you to indicate whether the operation using the file was successful from the caller's point-of-view. If you set the 'remove' flag in the file string passed to fcbopen() or fcbopen2(), the file is only removed at read if you indicate success, i.e. pass TRUE for the 'success' parameter or at write if you indicate failure, i.e. pass FALSE. In case of an error while processing the read data, it may be more reasonable to keep the file, even though it was flagged for deletion.

For statistics you can define the format in which the information will be output. The information is written to a buffer which will be dynamically re-allocated by this function so that it fits all requested information. The buffer can already be allocated before. In that case, it must contain a (possibly empty) null-terminated string because statistics output is appended. The buffer must be freed by the calling application. The pointer to the buffer can point to a null pointer. In this case, the whole buffer will be allocated by this function.

Parameters

  [in] | hdl | File handle from fcbopen()
  [in] | success | True indicates that the data was processed successfully by the caller
  [in] | stafmt | Format specification for the output buffer (FLMOUT_FORMAT_*)
  [in,out] | stasiz | Pre-allocated buffer size on input, is overwritten with final buffer size on output
  [in,out] | stabuf | Pointer of pointer to a dynamically allocated buffer containing statistics

Returns
  Upon successful completion a value >=0 is returned. Otherwise, EOF is returned and fcberrno is set to indicate the error.

## ◆ fcbgtn()

const char * fcbgtn | ( | void * | hdl | ) |

Returns the current table name.

When using table support while reading with end of table handling (ENDOFT), this function returns the current table name (logical name defined in the row specification). This name changes when the handle is obtained (from fcbopen() or fcbopenv()) or reading returns the EOT error code.

Parameters

  [in] | hdl | File or conversion handle from fcbopen() or fcbopenv()

Returns
  Pointer to the table name or NULL if error

## ◆ fcbgfn()

const char * fcbgfn | ( | void * | hdl,
|  | const int | ind
| ) |  |

Returns the current file name.

If you open a file for write operation and use input output name mapping running or random numbers, dates and times, this function is useful to determine the current file name. To analyze the data read from memory at write, the real open is delayed. To ensure to get the file name you must call this function after a fcbflush() in front of fcbclose(). At read the original file name read will be returned and the index ignored.

Parameters

  [in] | hdl | File handle from fcbopen()
  [in] | ind | Index if multiple writes defined else set to 0

Returns
  Pointer to the file name or NULL if error

## ◆ fcbstn()

const char * fcbstn | ( | void * | hdl,
|  | const char * | name
| ) |  |

Sets the current table format.

When writing more than one table to a file, the current table format can be set with this function. The function only succeeds after complete rows have been written. It fails if there is a remainder in the buffer. By using this function, automatic detection of the table format is deactivated. The provided data must match the defined row specification. You can re-activate auto detection of the table format with a call to fcbgtn(). A call to fcbstn() will start a new table of the same or another format. If ENDOFT is activated in the format string, then FLMRTC_EOT will be returned internally and, when writing, the file handle is re-opened. By using use the filename pattern [table] in the output filename, the data of each table can be written to in different files.

Parameters

  [in] | hdl | File or conversion handle from fcbopen() or fcbopenv()
  [in] | name | Table name to define the new row specification

Returns
  Pointer to the table name or NULL if error

## ◆ fcbflush()

int fcbflush | ( | void * | hdl | ) |

Flush internal buffers to the file.

Flushes all internal buffers, i.e. writes all data that still resides in memory to the file denoted by the handle. (This function also ensures that the real open are done.)

Parameters

  [in] | hdl | File handle from fcbopen()

Returns
  On success 0 is returned, on error EOF is returned

## ◆ fcbnewmbr()

void * fcbnewmbr | ( | void * | hdl,
|  | const char * | fmtstr,
|  | const char * | state
| ) |  |

Start with a new member in an open file.

The function implements a re-open of the current file handle to start with a new member. You must provide a valid handle from fcbopen() for write operation and you can provide a new format string and/or state string. If no format string (NULL) is given, the format of the previous member is used. If no state (NULL) is provided, then the default values are used.

Parameters

  [in] | hdl | Valid handle from fcbopen()
  [in] | fmtstr | Format string with FORMAT instructions
  [in] | state | Pointer to a string with STATE values

Returns
  a pointer to a handle to manage file I/O, must be passed to subsequent functions or NULL in case of an error (the handle is closed in error case)

## ◆ fcbnewmbr2()

void * fcbnewmbr2 | ( | void * | hdl,
|  | const char * | fmtstr,
|  | const char * | state,
|  | const int | stafmt,
|  | size_t * | stasiz,
|  | char ** | stabuf
| ) |  |

Start with a new member in a open file (with statistics information)

This function works like fcbnewmbr() with the capability to get statistical information, since open or last re-open.

Parameters

  [in] | hdl | Valid handle from fcbopen()
  [in] | fmtstr | Format string with FORMAT instructions
  [in] | state | Pointer to a string with STATE values
  [in] | stafmt | Format specification for the output buffer (FLMOUT_FORMAT_*)
  [in,out] | stasiz | Pre-allocated buffer size on input, is overwritten with final buffer size on output
  [in,out] | stabuf | Pointer of pointer to a dynamically allocated buffer containing statistics

Returns
  a pointer to a handle to manage file I/O, must be passed to subsequent functions or NULL in case of an error (the handle is closed in error case)

## ◆ fcbopenv()

void * fcbopenv | ( | void * | hdl,
|  | const char * | cnvstr
| ) |  |

Open converter.

This function opens a data conversion module for read or write operations if `format.element()` is used. All functions with 'v' as last character accepts a conversion handle, which is only relevant if `format.element()` done. With this set of 'v' functions, you can define over such an converter how the element data is converted from application memory to a neutral FLAM5 element or vice versa.

The read type specification defines how the data type is read from application memory and converted in the neutral data type at a write operation. The write type specification defines how a neutral data type is written to the application memory at a read operation.

To use the converter in write operations, normally the read type specification is required. If the converter is used for read operation, a write type specification must be specified. The conversion string uses the syntax of the 'type' union which was designed for element conversion. The zero-terminated string must start with 'read.' or 'write.' followed by the corresponding data type specification (binary/string/integer/float/...).

It is also possible to use a read conversion in a read operation. For example, this makes sense to convert a string of an XML element containing a decimal number to the neutral form of a number (64 bit integer) in FLAM. In this case, the 8 byte (64 bit) integer value is given as element data instead of the string with the decimal number.

The function optionally accepts a file or conversion handle. You can provide the file handle for which the converter will be used, so that the system knows, for example, the CCSID of the data. Otherwise, UTF-8 is assumed as neutral character encoding, but with the INPUT() object another internal character set can be set. If you provide the file handle, you can ensure that the correct internal representation of the data is known and the converter is opened in the right manner for that file. The same is valid for memory conversion handles.

You can also use a conversion string (`CONV.type(from() to())` or `CONV.MEMORY(READ.mode() WRITE.mode())`) which describes a complete external representation to external representation conversion. This form can be used with function fcbconv/p for an independent memory to memory conversion. You can use this, for example, for an XML element, which contains a decimal number as UTF-8 string, to build an integer in two's complement representation or to produce a PGP file which contains a CSV table or some other complex in-memory conversions.

Examples:

    "read.string(chrset(ccsid=default))"
    "write.string(chrset(ccsid=default whitespace=collapse))"
    "write.string(chrset(ccsid=default whitespace=number) number(format='%3.2f'))"
    "conv.integer(from.string() to.bin())"
    "conv.memory(read.char() write.char(ccsid=UTF-32))"

Please use:

    'fcbhelp(FLC_CONV_READ,10,NULL)'
    'fcbsyntax(FLC_CONV_READ,10,NULL)'
    'fcbhelp(FLC_CONV_WRITE,10,NULL)'
    'fcbsyntax(FLC_CONV_WRITE,10,NULL)'
    'fcbhelp(FLC_CONV_FROM_TO,10,NULL)'
    'fcbsyntax(FLC_CONV_FROM_TO,10,NULL)'

for more information.

Parameters

  [in] | hdl | File or memory conversion handle from fcbopen or fcbopenv (optional, can be NULL)
  [in] | cnvstr | Conversion string with READ or WRITE instructions

Returns
  a pointer to a handle to manage conversions, can be passed to subsequent v-functions, must be closed with fcbclosev()

## ◆ fcbclosev()

int fcbclosev | ( | void * | cnv | ) |

Close a converter.

Opened conversion handles must be closed through this function after read or write are completed. All allocated resources are released.

Parameters

  [in] | cnv | Conversion handle from fcbopenv()

Returns
  Upon successful completion 0 is returned. Otherwise, EOF is returned and fcberrno is set to indicate the error.

## ◆ fcbread()

size_t fcbread | ( | void * | ptr,
|  | size_t | size,
|  | size_t | count,
|  | void * | hdl
| ) |  |

Read file data.

This function reads `count` items, each `size` bytes long, from the input stream (block/stream-oriented mode).

In record- or element-oriented mode, the function reads at most one record or element structure from the input stream on each call. Therefore, the `count` and `size` parameters have a different meaning, when the file was opened with `format.record()` or `format.element()`.

format.record()
  If you use fcbread() for record I/O, only one record is read at most, regardless of `count`, when using record I/O. There is no inherent limit on record lengths for records produced by `format.record()`. For example, when reading with "read.bin(blksiz=1048576)" and formatting with "format.record()", this function would return records of 1 MiB because every block that was read would be formatted as one record.

  The `size` parameter controls the behavior of the function in record mode:
  - `size = 0`
    - Set `count` to the maximum expected record length in bytes. This is also the minimum size for your buffer passed via `ptr`. If a record is encountered that is longer than `count` bytes, this function returns 0 and the error state returned by fcberror() is set to FLMRTC_LEN. You can allocate a bigger buffer and attempt to re-read the same record by calling this function again with the bigger buffer.
  - `size = 1`
    - Set `count` to the maximum expected record length in bytes. This is also the minimum size for your buffer passed via `ptr`. If a record is encountered that is longer than `count` bytes, `count` bytes are copied to the provided buffer and remaining bytes are discarded.
  - `size = -1` (SIZE_MAX)
    - This is the zero-copy mode for record I/O. Instead of passing your own buffer, you must pass a pointer to a NULL pointer which is set to an internal byte buffer containing the next record if the function succeeds. The function's return value is the number of bytes in this buffer.

Note
  If record I/O is used, the returned number of bytes can be zero because records can contain zero-length data. Check fcberror() and fcbeof() to distinguish between errors, EOF and zero-length records.

format.element()
  This formatting method provides access to the raw elements in a serialized form that all data is split into internally when reading any data. Each call to this functions returns at most one serialized element. The buffer pointed to by `ptr` contains an element matching the structure FlmElmRec0, which can be used for type-casting.

  Each element has a matrix type, which indicates the type of data, and an element type which defines the kind of content. The set of element types depends on the matrix type. Besides the element data, each element can contain hash values (checksums) and additional attributes. The presence of both depends on the element type. There are some convenience macros like FLMELMREC0_DATAPTR(element) which help to get pointers to the various data fields. These macros only work if the choosen byte order matches the system byte order (big or little endian).

  The `size` parameter controls the behavior of the function in element mode:
  - `size = 0`
    - The function reads one element at a time and writes it into the supplied buffer of length `count`. If the buffer is too small, 0 is returned and fcberror() returns FLMRTC_LEN. If the buffer is at least `sizeof(FlmElmRec0)` bytes long, all fields of the structure will have been written to the buffer except for the actual data (FlmElmRec0::buffer). You can use this information to reallocate your buffer to the required size. The required buffer size is the size of thestructure (e.g. FlmElmRec0) plus the sum of all length fields of the structure. There is a convenient C macro for every supported structure, which calculates the correct length, e.g. FLMELMREC0_LENGTH.
  - `size = -1` (SIZE_MAX)
    - Instead of providing your own buffer, you pass a pointer to a NULL pointer via `ptr`. The `count` parameter is ignored and can have any value. If an element has been read successfully, the value of `ptr` is a pointer to a buffer that holds the whole element. The function ensures that the buffer is always large enough. Please note that this buffer should not be written to and that its contents are only valid until the next call to fcbread(), fcbclose() or fcbclose2() on the same handle.

Note
  You should always check the version field (first 32 bits, currently always 0) to determine the structure of the element. A version of 0 indicates that, FlmElmRec0 is the structure of the data and may be used to cast the buffer. In future versions, additional structures might be added. Checking the version field avoids misinterpreting the data by casting to the wrong structure.

Parameters

  [out] | ptr | Pointer to the data buffer that read data is written to
  [in] | size | Size of one data element to be read If you opened the file with record or element formatting, this parameter controls the behavior of this function. See the function description above for details.
  [in] | count | Number of data elements to read
  [in] | hdl | File handle from fcbopen()

Returns
  Number of bytes actually read or 0 if end-of-file (EOF) is reached, an error occurs or an empty record is encountered.
  If you opened the file with record or element formatting, are zero return value can also mean that the supplied buffer is too small (see function description above).
  If you require the same behavior as fread(), i.e. the return value is the number of elements read of size `size`, the following macro can be used:

      #define FREAD(p,s,c,h) ((s)?(fcbread(p,s,c,h)/(s)):0)

See also
  fcberror(), fcbeof()

## ◆ fcbreadv()

size_t fcbreadv | ( | void * | ptr,
|  | size_t | size,
|  | size_t | count,
|  | void * | hdl,
|  | void * | cnv,
|  | const int | skip
| ) |  |

Read file data with conversion.

This function works like fcbread() but accepts two additional parameter. The argument `cnv` point to a conversion handle and `skip` is a element type which will be ignored at this read request. These parameters are only relevant with `format.element()` and can be used to overwrite the element data conversion and skip an unexpected element type. You can open such an handle by calling fcbopenv() and request a individual conversion for that element.

In XML data between a FLMELM_TYPXML_ENDSTRTELM and the next FLMELM_TYPXML_STARTELM data elements (FLMELM_TYPXML_DATA) could be exist and the parameter `skip` can be used to ignore for example these data elements. With FLMELM_NOSKIP the next element is given.

Parameters

  [out] | ptr | Pointer to the data buffer that read data is written to
  [in] | size | Size of one data element to be read If you opened the file with record or element formatting, this parameter controls the behavior of this function. See the function description above for details.
  [in] | count | Number of data elements to read
  [in] | hdl | File handle from fcbopen()
  [in] | cnv | Conversion handle from fcbopenv()
  [in] | skip | Skip this element type

Returns
  Number of bytes actually read or 0 if end-of-file (EOF) is reached, an error occurs or an empty record is encountered.
  If you opened the file with record or element formatting, a zero return value can also mean that the supplied buffer is too small (see function description above).
  If you require the same behavior as fread(), i.e. the return value is the number of elements read of size `size`, the following macro can be used:

      #define FREAD(p,s,c,h,v,k) ((s)?(fcbreadv(p,s,c,h,v,k)/(s)):0)

See also
  fcberror(), fcbeof()

## ◆ fcbwrite()

size_t fcbwrite | ( | const void * | ptr,
|  | size_t | size,
|  | size_t | count,
|  | void * | hdl
| ) |  |

Write data to file.

This function writes size × count bytes to the output file (block/stream-oriented mode).

If the file was opened for record- or element formatting, only one record or element can be written per call.

format.record()
  The `size` parameter is ignored when record formatting. The record length in bytes must be passed via parameter `count`. The record length is not limited when formatting record elements in memory. However, when writing records to a dataset or a FLAMFILE, respective limits apply. Therefore, you can specify how too long records are handled via the file string passed to fcbopen().

format.element()
  To write elements, the buffer pointed to by `ptr` must contain one of the serialized element structures defined in FLMDEF.h (e.g. FlmElmRec0). The structure is expected to start at offset 0 in the buffer. All members of the structure must be set to valid values. The `size` parameter is ignored when element formatting. The length in bytes of the serialized element structure must be passed via parameter `count`. The length of an element is calculated as sum of all length fields in the structure + the length of the structure itself without the last field (i.e. buffer). You can use macros like FLMELMREC0_LENGTH(element) to conveniently calculate the correct length of the structure.

  All elements written to one file handle must have the same matrix type. If an element of an element type is written which contains text data, the data field must be provided in UTF-8 unless character conversion was activated by setting the `ccsid` in the `format.element()` clause to the character set of your data. If the matrix and/or element type requires attributes, then the attribute length and values must be set as described by the element type.

Note
  Unlike fwrite(), fcbwrite() does not return the number of elements written, but the number of bytes written. If you require the same behavior as fwrite(), the following macro can be used:

      #define FWRITE(p,s,c,h) ((s)?(fcbwrite(p,s,c,h)/(s)):0)

Parameters

  [in] | ptr | Pointer to the data to be written
  [in] | size | Size of one data element to be written
  [in] | count | Number of data elements to write
  [in] | hdl | File handle from fcbopen()

Returns
  Number of bytes (not elements) written or 0 on error

## ◆ fcbwritev()

size_t fcbwritev | ( | const void * | ptr,
|  | size_t | size,
|  | size_t | count,
|  | void * | hdl,
|  | void * | cnv
| ) |  |

Write data to file with conversion.

This function works like fcbwrite() but accepts one additional parameter `cnv` which point the a conversion handle. This parameter is only relevant with `format.element()` and can be used to overwrite the element data conversion. You can open such an handle by calling fcbopenv() and request a individual conversion for that element.

Parameters

  [in] | ptr | Pointer to the data to be written
  [in] | size | Size of one data element to be written
  [in] | count | Number of data elements to write
  [in] | hdl | File handle from fcbopen()
  [in] | cnv | Conversion handle from fcbopen()

Returns
  Number of bytes (not elements) written or 0 on error

## ◆ fcbprev()

int fcbprev | ( | void * | hdl | ) |

Sets the read position to the previous record or element.

If the file handle has been opened for reading with element formatting (`format.element()`) or record formatting `format.record()`, the internal position is set to the previously read element or record. I.e. the next call to fcbread() will return the same element as the last one.

The function is guaranteed to decrement the file position at least once after fcbread() has been called. Multiple successive calls to this function may or not be successful.

Note
  Calls to this function on a handle opened without record or element formatting may result in undefined behavior.

Parameters

  [in] | hdl | File handle from fcbopen()

Returns
  A non-zero value (errno) in case of an error, zero on success

## ◆ fcbgetc()

int fcbgetc | ( | void * | hdl | ) |

Gets the next character.

The function gets the next character (an unsigned char) from the specified stream and advances the position indicator by one. This function does not work with `format.record()` or `format.element()`. Use fcbread() instead.

Parameters

  [in] | hdl | File handle from fcbopen()

Returns
  Returns the character read as an unsigned char cast to an int or EOF(-1) on end of file or error.

## ◆ fcbungetc()

int fcbungetc | ( | int | chr,
|  | void * | hdl
| ) |  |

Push a character back back to the stream.

Pushes a character (unsigned char) back onto the specified stream. Pushed-back characters will be returned in reverse order by subsequent calls to fcbgetc(). Only one pushback is guaranteed to work (after at least one character has been read previously).

Note
  This function does not work with `format.record()` and `format.element()`.

Parameters

  [in] | chr | Character value to push back
  [in] | hdl | File handle from fcbopen()

Returns
  If successful, returns the character that was pushed back. Otherwise, EOF(-1) is returned and the stream remains unchanged.

## ◆ fcbputc()

int fcbputc | ( | int | chr,
|  | void * | hdl
| ) |  |

Writes a character.

Writes a character (unsigned char) to the stream specified by the given handle and advances the position indicator by one.

Note
  This function does not work with `format.element()`. It works with `format.record()`, but each character will be turned into one record.

Parameters

  [in] | chr | Chracter value
  [in] | hdl | File handle from fcbopen()

Returns
  On success, `chr` is returned. If an error occurs, EOF(-1) is returned and the error indicator is set.

## ◆ fcbgets()

char * fcbgets | ( | char * | str,
|  | int | n,
|  | void * | hdl
| ) |  |

Reads a line.

Reads a line from the specified stream and stores it as null-terminated string into the buffer pointed to by `str`.

If `format.record()` is used, each call returns one null-terminated line with up to n-1 characters (no new line characters at the end). The remainder of the record is discarded.

Otherwise, reading stops when either (n-1) characters are read, the newline character is encountered, or the end-of-file is reached, whichever comes first. If a newline is read, it is stored into the buffer. The character data must be in a local character encoding (i.e. an EBCDIC charset on EBCDIC machines and an ASCII charset on ASCII machines) for correct splitting on newlines (i.e. specify a ccsid in the format string to convert to a local charset).

Null-termination of the returned string is guaranteed.

Note
  This function does not work with `format.element()`.

Parameters

  [out] | str | Pointer to a character array where the string is stored
  [in] | n | The maximum number of characters to be read (size of str).
  [in] | hdl | File handle from fcbopen()

Returns
  On success, the function returns `str`. If the end-of-file is encountered and no characters have been read, the contents of `str` remain unchanged and a null pointer is returned.

## ◆ fcbputs()

int fcbputs | ( | const char * | str,
|  | void * | hdl
| ) |  |

Writes a null-terminated string.

The function writes a null-terminated string to the specified stream up to but not including the null character.

If `format.record()` is used, each null-terminated string passed to this function is treated as one record.

Note
  This function does not work with `format.element()`.

Parameters

  [in] | str | A null-terminated string
  [in] | hdl | File handle from fcbopen()

Returns
  A non-negative value (amount of bytes written) on success, EOF (-1) if an error occurred.

## ◆ fcbconv()

int fcbconv | ( | void * | cnv,
|  | size_t | inplen,
|  | const void * | inp,
|  | size_t * | outlen,
|  | void * | out
| ) |  |

Converts independent data blocks (with copy)

The function converts data between formats as specified by the conversion string passed to fcbopenv().

It provides memory to memory conversion between external data representations of different data types using a conversion handle from function fcbopenv() which was called with a conversion string of the form from-to or read-write.

Please note that this function always converts the whole input data independent of previous calls. This implies that data elements must be passed as a whole. For example, passing a block of UTF-8 text as input where the data in the input buffer ends in the middle of a multi-byte character, will result in an error or unexpected output. To convert multiple buffers of dependent data (e.g. whole files), use the functions fcbrunv() and fcbfinv().

The return code FLMRTC_LEN tells that the output buffer is too small. In this case, the function must be called again with the same input buffer and an output buffer of the size returned by the `outlen` parameter (or larger).

If EOT (end of table) handling is activated, the return code FLMRTC_EOT can occur if the input buffer contains the data for more than one table or if the order of tables in the input buffer does not match the order of the row specifications. Only one table can be written to the output buffer per call of this function. Hence, it must be called repeatedly with the same input buffer as long as FLMRTC_EOT is returned. Note that if the data in the input buffer does not match the first row specification, FLMRTC_EOT is returned without writing any data to the output buffer. Please be aware that FLMRTC_LEN may also be returned for any of your repeated calls if the output buffer is not large enough for the currently processed table.

Below is an example on handling the return codes if EOT handling is activated and length errors are expected:

    hdl=fcbopenv(NULL,"...");
    if (hdl==NULL) return(fcberrno);
    do {
       do {
          fcbgtn(hdl,...);
          outlen=0; // ensure a length error
          err=flcconv(hdl,inplen,input,&outlen,output);
          if (err==FLMRTC_LEN) {
             output=realloc(output,outlen);
             err=flcconv(hdl,inplen,input,&outlen,output);
          }
          if (err && err!=FLMRTC_EOT) {
             fcbclosev(hdl);
             return(err);
          }
          if (outlen>0) {
            // process output
          }
       } while(err==FLMRTC_EOT);
       input+=inplen;
    } while (input<end && err==FLMRTC_OK);
    fcbclosev(hdl);
    return(err);

To simplify the EOT handling and to increase performance, you can use the corresponding p(ointer) function (fcbconp()) which returns a pointer to the data, where no length error can occur.

Parameters

  [in] | cnv | Conversion handle from fcbopenv()
  [in] | inplen | Length of the input buffer
  [in] | inp | Pointer to the input buffer
  [in,out] | outlen | On input: Available space for the output buffer At output: If return code 0: length of the output buffer If return code FLMRTC_LEN: required minimum length for `out`
  [out] | out | Pointer to the output buffer

Returns
  A FLAM return code or 0 if successful

## ◆ fcbconp()

int fcbconp | ( | void * | cnv,
|  | size_t | inplen,
|  | const void * | inp,
|  | size_t * | outlen,
|  | void ** | out
| ) |  |

Converts independent data blocks (with locate)

This function is identical to fcbconv(), except that the output buffer is not user-provided. When the function returns, the buffer pointer pointed to by the `out` parameter is set to a buffer that is large enough to store the output data. As a result, the return code can never be FLMRTC_LEN.

Parameters

  [in] | cnv | Conversion handle from fcbopenv()
  [in] | inplen | Length of the input buffer
  [in] | inp | Pointer to the input buffer
  [out] | outlen | Length of the output buffer out
  [out] | out | Pointer to the output buffer pointer

Returns
  A FLAM return code or 0 if successful

## ◆ fcbrunv()

int fcbrunv | ( | void * | cnv,
|  | size_t | inplen,
|  | const void * | inp,
|  | size_t * | outlen,
|  | void * | out
| ) |  |

Converts dependent data blocks (with copy)

The function converts data between formats as specified by the conversion string passed to fcbopenv().

It provides memory to memory conversion between external data representations of different data types using a conversion handle from function fcbopenv() which was called with a conversion string of the form from-to or read-write.

This function must be used instead of fcbconv() if processing consecutive blocks of data, e.g. whole files. If no sufficient amount of input data is available, the output length (outlen) might be shorter than the input or even zero. When the last input block is processed, the function fcbfinv() must be called to force any pending data to be processed and written to the output buffer. Failing to call fcbfinv() might result in truncated output!

The return code FLMRTC_LEN tells that the output buffer is too small. In this case you can provide a larger buffer to get the conversion done. The required length for the output buffer is provided in the `outlen` parameter.

Parameters

  [in] | cnv | Conversion handle from fcbopenv()
  [in] | inplen | Length of the input buffer
  [in] | inp | Pointer to the input buffer
  [in,out] | outlen | Length of the output field
  [out] | out | Pointer to the output buffer

Returns
  The fcberrno containing the FLAM return code or 0 if success

## ◆ fcbrunp()

int fcbrunp | ( | void * | cnv,
|  | size_t | inplen,
|  | const void * | inp,
|  | size_t * | outlen,
|  | void ** | out
| ) |  |

Converts dependent data blocks (with locate)

This function is identical to fcbrunv(), except that the output buffer is not user-provided. When the function returns, the buffer pointer pointed to by the `out` parameter is set to a buffer that is large enough to store the output data. As a result, the return code can never be FLMRTC_LEN.

Parameters

  [in] | cnv | Conversion handle from fcbopenv()
  [in] | inplen | Length of the input buffer
  [in] | inp | Pointer to the input buffer
  [out] | outlen | Length of the output field
  [out] | out | Pointer to the output buffer pointer

Returns

## ◆ fcbfinv()

int fcbfinv | ( | void * | cnv,
|  | size_t | inplen,
|  | const void * | inp,
|  | size_t * | outlen,
|  | void * | out
| ) |  |

Finish conversion of dependent data blocks (with copy)

This function must be called to finish data conversion when fcbrunv() is used. It forces all internally buffered, but unprocessed data to be converted and written to the ouput buffer.

A final block of input data may be passed. Calling with a zero length is also valid.

The return code FLMRTC_LEN tells that the output buffer is too small. In this case you can provide a larger buffer to get the conversion done. The required length for the output buffer is provided in the `outlen` parameter.

Parameters

  [in] | cnv | Conversion handle from fcbopenv()
  [in] | inplen | Length of the input buffer
  [in] | inp | Pointer to the input buffer
  [in,out] | outlen | Length of the output field
  [out] | out | Pointer to the output buffer

Returns
  The fcberrno containing the FLAM return code or 0 if success

## ◆ fcbfinp()

int fcbfinp | ( | void * | cnv,
|  | size_t | inplen,
|  | const void * | inp,
|  | size_t * | outlen,
|  | void ** | out
| ) |  |

Finish conversion of dependent data blocks (with locate)

This function is identical to fcbfinv(), except that the output buffer is not user-provided. When the function returns, the buffer pointer pointed to by the `out` parameter is set to a buffer that is large enough to store the output data. As a result, the return code can never be FLMRTC_LEN.

Parameters

  [in] | cnv | Conversion handle from fcbopenv()
  [in] | inplen | Length of the input buffer
  [in] | inp | Pointer to the input buffer
  [out] | outlen | Length of the output field
  [out] | out | Pointer to the output buffer pointer

Returns
  The fcberrno containing the FLAM return code or 0 if success

## ◆ fcbeof()

int fcbeof | ( | void * | hdl | ) |

Returns the end-of-file (EOF) flag.

Checks whether the end-of-file indicator associated with the handle is set, returning a value different from zero if it is.

Parameters

  [in] | hdl | File or conversion handle from fcbopen() or fcbopenv()

Returns
  A non-zero value is returned in the case that the end-of-file indicator associated with the handle is set. Otherwise, zero is returned.

## ◆ fcbeot()

int fcbeot | ( | void * | hdl | ) |

Returns the end-of-table (EOT) flag.

Checks whether the end-of-table indicator associated with the handle is set, returning a value different from zero if it is.

Parameters

  [in] | hdl | File or conversion handle from fcbopen() or fcbopenv()

Returns
  A non-zero value is returned in the case that the end-of-table indicator associated with the handle is set. Otherwise, zero is returned.

## ◆ fcberror()

int fcberror | ( | void * | hdl | ) |

Get error code.

Returns the error code for the last FLUC byte interface operation on the provided handle. If the handle is null, the error code of the last overall byte interface operation is returned (i.e. to get the error code after a call to fcbopen() failed).

Parameters

  [in] | hdl | File or conversion handle from fcbopen() or fcbopenv()

Returns
  A non-zero value if the last operation resulted in an error, zero otherwise.

## ◆ fcberrms()

const char * fcberrms | ( | int | code | ) |

Get error message.

This function can be used to retrieve a human-readable error message using the error code returned by fcberror().

Parameters

  [in] | code | A valid error code

Returns
  A pointer to a static area with a zero-terminated string containing a FLAM error message matching the passed error code as one line. (no LF)

## ◆ fcberrtr()

const char * fcberrtr | ( | void |  | ) |

Get error trace.

This function can be used to get an error trace after a call to fcbopen(), fcbopen2(),fcbread(), fcbwrite(), fcbclose(), fcbclose2(), fcbhelp() or fcbsyntax(). The error trace contains the FLAM error stack. If parsing the file or format string failed, the error trace also contains the complete error stack of the Command-Line-Parser (FLAMCLP).

Returns
  a pointer to a static area with a zero-terminated string containing the current FLAM error trace on several lines.

## ◆ fcbclearerr()

void fcbclearerr | ( | void * | hdl | ) |

Clear error and EOF indicators.

This functions clears the end-of-file and error indicators for the given stream.

Parameters

  [in] | hdl | File or convesion handle from fcbopen() or fcbopenv()

## ◆ fcbhelp()

const char * fcbhelp | ( | const int | what,
|  | const int | depth,
|  | const char * | path
| ) |  |

Returns help information about the file and format strings.

This function can be used to get all help messages or man pages for each parameter in the file and format strings. If depth 0 or greater then 9 aliases are provided. In all other cases aliases are suppressed. Please use fcbsyntax() to see possible aliases for the same argument.

Parameters

  [in] | what | Integer constant for the corresponding file or format string (one of FLC_READ_* or FLC_WRITE_*)
  [in] | depth | Number of levels to display (0-Man page, 1-One Level, 2-Two Level, ..., <9-All)
  [in] | path | Path (e.g. read.text.ccsid) to limit help to the (sub)tree of a certain object

Returns
  a pointer to a static area with a zero-terminated string containing the help information on several lines, in case of an error the string is empty.

## ◆ fcbsyntax()

const char * fcbsyntax | ( | const int | what,
|  | const int | depth,
|  | const char * | path
| ) |  |

Returns syntax information about the file and format strings.

This function can be used to determine the complete syntax of the file and format strings.

Parameters

  [in] | what | Integer constant for the corresponding file or format string (one of FLC_READ_* or FLC_WRITE_*)
  [in] | depth | Number of levels to display (0-Man page, 1-One Level, 2-Two Level, ..., <9-All)
  [in] | path | Path (e.g. read.text.ccsid) to limit syntax to the (sub)tree of a certain object

Returns
  a pointer to a static area with a zero-terminated string containing the syntax information in one (level == 1) or several lines (level > 1), in case of an error the string is empty.

## ◆ fcbcheck()

const char * fcbcheck | ( | const int | what,
|  | const char * | string
| ) |  |

Check syntax for a certain CLP string.

This function can be used to check if a CLP string is correct.

Parameters

  [in] | what | Integer constant for the corresponding file or format string (one of FLC_READ_* or FLC_WRITE_*)
  [in] | string | The CLP string to check

Returns
  a pointer to a static area with a zero-terminated string containing the error or NULL if CLP string is correct.

## ◆ fcbcount()

long long int fcbcount | ( | void * | hdl,
|  | const int | direction,
|  | const int | what,
|  | const int | kind
| ) |  |

Determine current amount of processed data.

This function can be used to determine different statistical values from a file or memory conversion handle. This can be used to control the size of the output or how many records are read.

The value returned is the current value from the corresponding component. This value is normally calculated at the end of the processing of one chunk of data. This means, that the data which is currently collected to a chunk of data is not included. At write for example you can control how many bytes are processed by the formatting component (XML written). If a certain limit is achieved you can close the file or start a new member, but the resulting size of the file or member will be increased by the remaining rest of the data which are not yet processed but collected in the buffers.

Parameters

  [in] | hdl | File or conversion handle from fcbopen() or fcbopenv()
  [in] | direction | Input (1) or output (2)
  [in] | what | File I/O (1) or Formating (2)
  [in] | kind | Bytes (1) or Units (2)

Returns
  >=0 the requested amount, <0 error (FLAM reason code * -1)

## ◆ fcbbini()

void * fcbbini | ( | const unsigned int | mode,
|  | const unsigned int | base,
|  | const unsigned int | chrs
| ) |  |

Creates a handle for Base16/32/64 encoding or decoding.

fcbbini() creates and returns a handle for Base16/32/64 conversion that can be passed to fcbbrun() (to convert data) and fcbbfin() (to release the handle). May return NULL on error.

To convert data to or from Base16/32/64 that does not fit in a single buffer, the following sequence of function calls can be used:

       fcbbini()
       fcbbrun()
       fcbbrun()
       ...
       fcbbfin()

Parameters

  [in] | mode | Mode: 1 is Encode and 0 is Decode
  [in] | base | Base: possible values 16, 32 or 64
  [in] | chrs | Character set: 1 is ASCII and 2 is EBCDIC, otherwise the system character set is used

Returns
  hdl A valid handle or NULL on error

## ◆ fcbbrun()

int fcbbrun | ( | void * | hdl,
|  | const int | inlen,
|  | const unsigned char * | in,
|  | unsigned char * | out
| ) |  |

En- or Decodes a data buffer.

fcbbrun() converts the provided binary data buffer. The `hdl` must be initialized by fcbbini() first. The output buffer must be big enough to write the encoded or decoded data in order to avoid buffer overflows. When decoding, incomplete encoded bytes may occur at the end of the input buffer, which are buffered internally until more input is provided with the next call of this function. You must account for this in the size of the ouput buffer.

Parameters

  [in] | hdl | Handle created by fcbbini()
  [in] | inlen | Number of bytes in `in`
  [in] | in | Input data buffer
  [out] | out | Output data buffer

Returns
  Number of bytes written to `out`, negative number on error

## ◆ fcbbfin()

int fcbbfin | ( | void * | hdl,
|  | const int | inlen,
|  | const unsigned char * | in,
|  | unsigned char * | out
| ) |  |

Finalize en- or decoding.

fcbbfin() converts the provided binary data buffer. The `hdl` must be initialized by fcbbini() first. The output buffer must be big enough to write the encoded or decoded data in order to avoid buffer overflows. When decoding, incomplete encoded bytes at the end of the input buffer lead to an error. However, this function may process incomplete encoded bytes from previous calls to fcbbrun(), which are buffered internally. You must account for this in the size of the ouput buffer.

Parameters

  [in] | hdl | Handle created by fcbbini()
  [in] | inlen | Number of bytes in `in`
  [in] | in | Input data buffer
  [out] | out | Output data buffer

Returns
  Number of bytes written to `out`, negative number on error

## ◆ fcbbase()

int fcbbase | ( | const unsigned int | mode,
|  | const unsigned int | base,
|  | const unsigned int | chrs,
|  | const int | inlen,
|  | const unsigned char * | in,
|  | unsigned char * | out
| ) |  |

Base encoding or decoding for one message.

The fcbbase() function does the same as fcbbini() and fcbbfin() It is a shortcut if the input data is not scattered.

Parameters

  [in] | mode | Mode: 1 is Encode and 0 is Decode
  [in] | base | Base: possible values 16, 32 or 64
  [in] | chrs | Character set: 1 is ASCII and 2 is EBCDIC otherwise system character set is used
  [in] | inlen | Length of `in`
  [in] | in | Input data for en- or decoding
  [out] | out | Output data

Returns
  >=0 produced output length else error

## ◆ fcbhini()

void * fcbhini | ( | const unsigned int | hmtd,
|  | const unsigned int | kmtd,
|  | const unsigned int | keylen,
|  | const unsigned char * | key,
|  | const unsigned int | icvlen,
|  | const unsigned char * | icv
| ) |  |

Initialize hash calculation.

fcbbini() creates and returns a handle for hash calculation that can be passed to fcbhadd() (to add more data to hash) and fcbbfin() (returns the hash result). May return NULL on error.

To calculate a hash for data that does not fit in a single buffer, the following sequence of function calls can be used:

       fcbhini()
       fcbhadd()
       fcbhadd()
       ...
       fcbhfin()

Parameters

  [in] | hmtd | Hash method to use, for example FLCHSH_ALGO_SHA1 see header FLMDEF.h
  [in] | kmtd | MAC method to use (if any), for example FLCMAC_ALGO_HMAC see header file FLMDEF.h
  [in] | keylen | Length of `key` in bytes
  [in] | key | Key to use in hash calculation (only for keyed MAC or HMAC calculations)
  [in] | icvlen | Length of `icv`
  [in] | icv | Initial chaining vector (only for certain MAC calculations)

Returns
  hdl A valid handle or NULL on error

## ◆ fcbhadd()

int fcbhadd | ( | void * | hdl,
|  | const unsigned int | datlen,
|  | const unsigned char * | dat
| ) |  |

Adds a buffer of data to the hash calculation.

fcbhadd() adds a buffer of binary data to the hash calculation. The `hdl` must be initialized by fcbhini() first.

Parameters

  [in] | hdl | Handle initialized with fcbhini()
  [in] | datlen | Length of `dat`
  [in] | dat | Input data chunk to add to hash calculation

Returns
  0 on success, non-zero on error

## ◆ fcbhfin()

int fcbhfin | ( | void * | hdl,
|  | unsigned int * | hshlen,
|  | unsigned char * | hsh
| ) |  |

Finalize hash calculation.

fcbhfin() stores the calculated hash to the buffer pointer to by the `hsh` parameter. The handle `hdl` must be initialized by fcbhini() and is released by this function. The parameter `hshlen` must point to an unsigned integer containing the size of the `hsh` buffer and will be set to the length of the hash in bytes when this function return successfully. If the output buffer is shorter than the hash length, the hash will be truncated.

Parameters

  [in] | hdl | Handle initialized with fcbhini()
  [in,out] | hshlen | Input: size of `hsh` ; output: length of `hsh` result
  [out] | hsh | Buffer where calculated hash is written to

Returns
  0 on success, non-zero on error

## ◆ fcbhash()

int fcbhash | ( | const unsigned int | hmtd,
|  | const unsigned int | kmtd,
|  | const unsigned int | keylen,
|  | const unsigned char * | key,
|  | const unsigned int | icvlen,
|  | const unsigned char * | icv,
|  | const unsigned int | datlen,
|  | const unsigned char * | dat,
|  | unsigned int * | hshlen,
|  | unsigned char * | hsh
| ) |  |

Calculate hash for a single buffer.

The fcbhash() function does the same as fcbhini(), fcbhadd(), fcbhfin(). Refer to the documentation of these functions for details. It is a shortcut for calculating the hash for a single buffer of data.

Parameters

  [in] | hmtd | Hash method to use, for example FLCHSH_ALGO_SHA1 see header FLMDEF.h
  [in] | kmtd | MAC method to use, for example FLCMAC_ALGO_HMAC see header file FLMDEF.h
  [in] | keylen | Length of `key`
  [in] | key | Key to use in hash calculation
  [in] | icvlen | Length of `icv`
  [in] | icv | Initial chaining vector (only for certain MAC calculation)
  [in] | datlen | Length of `dat`
  [in] | dat | Input data chunk to add to hash calculation
  [in,out] | hshlen | On input size of `hsh` on output length of `hsh`
  [out] | hsh | Buffer where calculated hash is written to

Returns
  0 on success, non-zero on error