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

Functions
const char *	fcbvsn (void)
	Retrieves version information.

const char *	fcbabo (void)
	Retrieves about information.

const char *	fcblic (void)
	Retrieves the license text.

int	fcbenv (const int sys, const int std, const char *env)
	Load the FLAM environment.

char *	fcbsym (const char name, size_t size, char string)
	Determines a symbol from environment.

int	fcbinfo (const char infstr, const int format, size_t bufsiz, char **buffer)
	Provides various information.

int	fcbopnlog (const char *logstr)
	Open the logging facility for in-memory logging.

int	fcbgetlog (const char **buffer)
	Get log information.

int	fcbclrlog (void)
	Clear the log information.

int	fcbclslog (void)
	Close the logging facility.

void *	fcbopen (const char filstr, const char fmtstr)
	Open file (without state management)

void *	fcbopen2 (const char filstr, const char fmtstr, char **state)
	Open file (with state management)

int	fcbclose (void *hdl)
	Close file (without statistics)

int	fcbclose2 (void hdl, const int success, const int stafmt, size_t stasiz, char **stabuf)
	Close file with return of statistics information.

const char *	fcbgtn (void *hdl)
	Returns the current table name.

const char *	fcbgfn (void *hdl, const int ind)
	Returns the current file name.

const char *	fcbstn (void hdl, const char name)
	Sets the current table format.

int	fcbflush (void *hdl)
	Flush internal buffers to the file.

void *	fcbnewmbr (void hdl, const char fmtstr, const char *state)
	Start with a new member in an open file.

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)

void *	fcbopenv (void hdl, const char cnvstr)
	Open converter.

int	fcbclosev (void *cnv)
	Close a converter.

size_t	fcbread (void ptr, size_t size, size_t count, void hdl)
	Read file data.

size_t	fcbreadv (void ptr, size_t size, size_t count, void hdl, void *cnv, const int skip)
	Read file data with conversion.

size_t	fcbwrite (const void ptr, size_t size, size_t count, void hdl)
	Write data to file.

size_t	fcbwritev (const void ptr, size_t size, size_t count, void hdl, void *cnv)
	Write data to file with conversion.

int	fcbprev (void *hdl)
	Sets the read position to the previous record or element.

int	fcbgetc (void *hdl)
	Gets the next character.

int	fcbungetc (int chr, void *hdl)
	Push a character back back to the stream.

int	fcbputc (int chr, void *hdl)
	Writes a character.

char *	fcbgets (char str, int n, void hdl)
	Reads a line.

int	fcbputs (const char str, void hdl)
	Writes a null-terminated string.

int	fcbconv (void cnv, size_t inplen, const void inp, size_t outlen, void out)
	Converts independent data blocks (with copy)

int	fcbconp (void cnv, size_t inplen, const void inp, size_t outlen, void *out)
	Converts independent data blocks (with locate)

int	fcbrunv (void cnv, size_t inplen, const void inp, size_t outlen, void out)
	Converts dependent data blocks (with copy)

int	fcbrunp (void cnv, size_t inplen, const void inp, size_t outlen, void *out)
	Converts dependent data blocks (with locate)

int	fcbfinv (void cnv, size_t inplen, const void inp, size_t outlen, void out)
	Finish conversion of dependent data blocks (with copy)

int	fcbfinp (void cnv, size_t inplen, const void inp, size_t outlen, void *out)
	Finish conversion of dependent data blocks (with locate)

int	fcbeof (void *hdl)
	Returns the end-of-file (EOF) flag.

int	fcbeot (void *hdl)
	Returns the end-of-table (EOT) flag.

int	fcberror (void *hdl)
	Get error code.

const char *	fcberrms (int code)
	Get error message.

const char *	fcberrtr (void)
	Get error trace.

void	fcbclearerr (void *hdl)
	Clear error and EOF indicators.

const char *	fcbhelp (const int what, const int depth, const char *path)
	Returns help information about the file and format strings.

const char *	fcbsyntax (const int what, const int depth, const char *path)
	Returns syntax information about the file and format strings.

const char *	fcbcheck (const int what, const char *string)
	Check syntax for a certain CLP string.

long long int	fcbcount (void *hdl, const int direction, const int what, const int kind)
	Determine current amount of processed data.

void *	fcbbini (const unsigned int mode, const unsigned int base, const unsigned int chrs)
	Creates a handle for Base16/32/64 encoding or decoding.

int	fcbbrun (void hdl, const int inlen, const unsigned char in, unsigned char *out)
	En- or Decodes a data buffer.

int	fcbbfin (void hdl, const int inlen, const unsigned char in, unsigned char *out)
	Finalize en- or decoding.

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.

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.

int	fcbhadd (void hdl, const unsigned int datlen, const unsigned char dat)
	Adds a buffer of data to the hash calculation.

int	fcbhfin (void hdl, unsigned int hshlen, unsigned char *hsh)
	Finalize hash calculation.

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.

Detailed Description

All public functions provided by the FLUC byte interface.

Function Documentation

◆ fcbvsn()

const char * fcbvsn ( void )

extern

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 )

extern

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 )

extern

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 )

extern

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 )

extern

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 )

extern

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 )

extern

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 )

extern

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 )

extern

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 )

extern

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 )

extern

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 )

extern

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:

Write only

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

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 )

extern

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 )

extern

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 )

extern

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 )

extern

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 )

extern

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 )

extern

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 )

extern

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 )

extern

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 )

extern

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 )

extern

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 )

extern

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 )

extern

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 )

extern

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 )

extern

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 )

extern

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 )

extern

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 )

extern

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 )

extern

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 )

extern

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 )

extern

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 )

extern

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 )

extern

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 )

extern

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 )

extern

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 )

extern

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 )

extern

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 )

extern

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 )

extern

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 )

extern

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 )

extern

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 )

extern

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 )

extern

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 )

extern

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 )

extern

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 )

extern

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 )

extern

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 )

extern

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 )

extern

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 )

extern

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 )

extern

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 )

extern

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 )

extern

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 )

extern

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 )

extern

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

Functions

Detailed Description

Function Documentation

◆ fcbvsn()

◆ fcbabo()

◆ fcblic()

◆ fcbenv()

◆ fcbsym()

◆ fcbinfo()

◆ fcbopnlog()

◆ fcbgetlog()

◆ fcbclrlog()

◆ fcbclslog()

◆ fcbopen()

◆ fcbopen2()

◆ fcbclose()

◆ fcbclose2()

◆ fcbgtn()

◆ fcbgfn()

◆ fcbstn()

◆ fcbflush()

◆ fcbnewmbr()

◆ fcbnewmbr2()

◆ fcbopenv()

◆ fcbclosev()

◆ fcbread()

◆ fcbreadv()

◆ fcbwrite()

◆ fcbwritev()

◆ fcbprev()

◆ fcbgetc()

◆ fcbungetc()

◆ fcbputc()

◆ fcbgets()

◆ fcbputs()

◆ fcbconv()

◆ fcbconp()

◆ fcbrunv()

◆ fcbrunp()

◆ fcbfinv()

◆ fcbfinp()

◆ fcbeof()

◆ fcbeot()

◆ fcberror()

◆ fcberrms()

◆ fcberrtr()

◆ fcbclearerr()

◆ fcbhelp()

◆ fcbsyntax()

◆ fcbcheck()

◆ fcbcount()

◆ fcbbini()

◆ fcbbrun()

◆ fcbbfin()

◆ fcbbase()

◆ fcbhini()

◆ fcbhadd()

◆ fcbhfin()

◆ fcbhash()