Functions
void	FCRVSN (int rtc, int vsnLen, char *vsn)
	Retrieves the version string.

void	FCRABO (int rtc, int aboLen, char *abo)
	Retrieves the about string.

void	FCRLIC (int rtc, int licLen, char *lic)
	Gets the license text.

void	FCRHLP (int rtc, const int what, const int depth, const int pathLen, const char path, int outLen, char *out)
	Returns help information about the file, format, state and info strings.

void	FCRSYN (int rtc, const int what, const int depth, const int pathLen, const char path, int outLen, char *out)
	Returns syntax information about the file, format, state and info strings.

void	FCRMSG (int rtc, const int code, int msgLen, char msg)
	Retrieves an error message.

void	FCRTRC (int rtc, const int code, int trcLen, char trc)
	Error trace.

void	FCRCLR (void **hdl)
	Clear error information.

void	FCRENV (int rtc, const int sys, const int std, const int envLen, const char envStr, int cnt)
	Load the FLAM environment.

void	FCRSYM (int rtc, const int inpLen, const char inpStr, int outLen, char *outStr)
	Determines a symbol from environment.

void	FCROPNL (int rtc, const int strLen, const char *logStr)
	Open global facility for memory logging.

void	FCRGETL (int maxCod, int bufLen, const char **buffer)
	Get log information.

void	FCRCPYL (int maxCod, int bufLen, char *buffer)
	Copies log information to a provided buffer.

void	FCRCLRL (int *maxCod)
	Clear the log information.

void	FCRCLSL (int *maxCod)
	Close the global logging facility.

void	FCRINF (int rtc, const int infoLen, const char infoStr, const int format, int buflen, char buffer)
	Provides various information.

void	FCROPN (void *hdl, int rtc, const int fileLen, const char fileStr, const int formatLen, const char formatStr, int stateLen, char stateStr)
	Opens a file.

void	FCROPNV (void hdl, void cnv, int rtc, const int convLen, const char *convStr)
	Opens a converter.

void	FCRNEWM (void *hdl, int rtc, const int formatLen, const char formatStr, const int stateLen, const char stateStr, const int format, int buflen, char *buffer)
	Start with a new member in an open file.

void	FCRPUT (void *hdl, int rtc, const int recLen, const char rec)
	Writes one record or element.

void	FCRPUTV (void *hdl, int rtc, const int recLen, const char rec, void **cnv)
	Writes one element with conversion.

void	FCRGTN (void *hdl, int rtc, int length, char name)
	Get table name.

void	FCRGFN (void *hdl, int rtc, const int ind, int length, char name)
	Get file name.

void	FCRSTN (void *hdl, int rtc, const int length, const char name)
	Set table name.

void	FCRFLU (void *hdl, int rtc)
	Flush internal buffers.

void	FCRGET (void *hdl, int rtc, int recLen, char rec)
	Reads one record or element.

void	FCRGETV (void *hdl, int rtc, int recLen, char rec, void *cnv, int skip)
	Reads one element with conversion.

void	FCRLOC (void *hdl, int rtc, int recLen, char *rec)
	Locates one record or element (without own buffer)

void	FCRLOCV (void *hdl, int rtc, int recLen, char rec, void cnv, int skip)
	Reads one element with conversion (without own buffer)

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

void	FCRCONV (void *cnv, int rtc, const int inpLen, const char inp, int outLen, char out)
	Converts element data (with copy)

void	FCRCONP (void *cnv, int rtc, const int inpLen, const char inp, int outLen, char *out)
	Converts element data (with locate)

void	FCRRUNV (void *cnv, int rtc, const int inpLen, const char inp, int outLen, char out)
	Converts dependent data blocks (with copy)

void	FCRRUNP (void *cnv, int rtc, const int inpLen, const char inp, int outLen, char *out)
	Converts dependent data blocks (with locate)

void	FCRFINV (void *cnv, int rtc, const int inpLen, const char inp, int outLen, char out)
	Finish conversion of dependent data blocks (with copy)

void	FCRFINP (void *cnv, int rtc, const int inpLen, const char inp, int outLen, char *out)
	Finish conversion of dependent data blocks (with locate)

void	FCRCLS (void *hdl, int rtc, const int success, const int format, int buflen, char buffer)
	Closes a file.

void	FCRCLSV (void *cnv, int rtc)
	Closes a converter.

void	FCRCPY (const int len, const char ptr, char *dat)
	Copy a memory area (MF-EDZ pointer handling workaround)

void	FCRPTR (const char dat, const char *ptr)
	Convert pointer to native format (MF-EDZ pointer handling workaround)

void	FCRCNT (void *hdl, int rtc, const int dir, const int wht, const int knd, long long int val)
	Determine current amount of processed data.

int	FCRBINI (void *hdl, const unsigned int mode, const unsigned int base, const unsigned int chrs)
	Initialize base encoding or decoding.

int	FCRBRUN (void *hdl, const unsigned int datlen, const unsigned char dat, unsigned char out)
	En- or Decode a junk of data.

int	FCRBFIN (void *hdl, const unsigned int datlen, const unsigned char dat, unsigned char out)
	Finalize en- or decoding.

int	FCRBASE (const unsigned int mode, const unsigned int base, const unsigned int chrs, const unsigned int datlen, const unsigned char dat, unsigned char out)
	Base encoding or decoding for one message.

int	FCRHINI (void *hdl, 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	FCRHADD (void *hdl, const unsigned int datlen, const unsigned char *dat)
	Add a junk of data to the hash calculation buffer.

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

int	FCRHASH (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 one message.

Detailed Description

Function Documentation

◆ FCRVSN()

void FCRVSN	(	int *	rtc,
		int *	vsnLen,
		char *	vsn )

extern

Retrieves the version string.

This function writes a string containing version information for every used component into the vsn parameter. This should be used in a support case.

Parameters

[out]	rtc	INTEGER Return code
[in,out]	vsnLen	INTEGER Size/length of version string (16KiB required)
[out]	vsn	STRING Version string (is null-terminated)

◆ FCRABO()

void FCRABO	(	int *	rtc,
		int *	aboLen,
		char *	abo )

extern

Retrieves the about string.

This function writes a string with about information for this library on multiple lines and license information for used external libraries into the abo parameter.

Parameters

[out]	rtc	INTEGER Return code
[in,out]	aboLen	INTEGER Size/length of about string (16KiB required)
[out]	abo	STRING About string (is null-terminated)

◆ FCRLIC()

void FCRLIC	(	int *	rtc,
		int *	licLen,
		char *	lic )

extern

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

Parameters

[out]	rtc	INTEGER Return code
[in,out]	licLen	INTEGER Size/length of license string
[out]	lic	STRING Current license text (is null-terminated)

◆ FCRHLP()

void FCRHLP	(	int *	rtc,
		const int *	what,
		const int *	depth,
		const int *	pathLen,
		const char *	path,
		int *	outLen,
		char *	out )

extern

Returns help information about the file, format, state and info strings.

This function can be used to get all help messages or man pages for each parameter in the file, format, state and info strings.

To select the parameter string for which to request help information, the parameter what must be set to one of the following values:

1 - to get information about the READ FILE STRING
2 - to get information about the READ FORMAT STRING
3 - to get information about the WRITE FILE STRING
4 - to get information about the WRITE FORMAT STRING
5 - to get information about the READ CONVERSION STRING
6 - to get information about the WRITE CONVERSION STRING
8 - to get information about the INPUT FILE STRING
9 - to get information about the OUTPUT FILE STRING
10 - to get information about the INFO STRING
11 - to get information about the STATE STRING

The output of this function is identical to the content of the FLCL user manual section for the respective parameter string.

Parameters

[out]	rtc	INTEGER Return code
[in]	what	INTEGER Constant number for the corresponding parameter string
[in]	depth	INTEGER Number of levels to display (0-Man page, 1-One Level, 2-Two Level, ..., <9-All)
[in]	pathLen	INTEGER Length of path string (0 to start at root)
[in]	path	STRING Path (e.g. conv.read.text.ccsid) to limit help to the (sub)tree of a certain object
[in,out]	outLen	INTEGER Size/length of output buffer
[out]	out	STRING Buffer for help information (is null-terminated)

◆ FCRSYN()

void FCRSYN	(	int *	rtc,
		const int *	what,
		const int *	depth,
		const int *	pathLen,
		const char *	path,
		int *	outLen,
		char *	out )

extern

Returns syntax information about the file, format, state and info strings.

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

To select the parameter string for which to request syntax information, the parameter what must be set to one of the following values:

1 - to get information about the READ FILE STRING
2 - to get information about the READ FORMAT STRING
3 - to get information about the WRITE FILE STRING
4 - to get information about the WRITE FORMAT STRING
5 - to get information about the READ CONVERSION STRING
6 - to get information about the WRITE CONVERSION STRING
8 - to get information about the INPUT FILE STRING
9 - to get information about the OUTPUT FILE STRING
10 - to get information about the INFO STRING
11 - to get information about the STATE STRING

The output of this function is identical to the content of the FLCL user manual section for the respective parameter string.

Parameters

[out]	rtc	INTEGER Return code
[in]	what	INTEGER Constant number for the corresponding parameter string
[in]	depth	INTEGER Number of levels to display (0-Man page, 1-One Level, 2-Two Level, ..., <9-All)
[in]	pathLen	INTEGER Length of path string (0 to start at root)
[in]	path	STRING Path (e.g. conv.read.text.ccsid) to limit syntax to the (sub)tree of a certain object
[in,out]	outLen	INTEGER Size/length of output buffer
[out]	out	STRING Buffer for syntax information (is null-terminated)

◆ FCRMSG()

void FCRMSG	(	int *	rtc,
		const int *	code,
		int *	msgLen,
		char *	msg )

extern

Retrieves an error message.

This function can be used to retrieve a human-readable error message using the return code. Sample call in COBOL:

    02  MSGRC     PIC S9(8) COMP.
    02  MSGLEN    PIC S9(8) COMP VALUE 800.
    02  MSGBUFF   PIC X(800) VALUE SPACES.
    02  F-RETCO  PIC S9(8)  COMP.
        88 FLUC-OK           VALUE  0.
        88 FLUC-EOF          VALUE  43.
CALL 'FCRMSG' USING MSGRC, F-RETCO, MSGLEN, MSGBUFF.

Sample call in PL1:

DCL FCRMSG ENTRY EXTERNAL OPTIONS (ASM, FETCHABLE);
    2   MSGRC           BIN FIXED(31,0) INIT (0),
    2   MSGLEN          BIN FIXED(31,0) INIT (800),
    2   MSGBUFF         CHAR(800)       INIT ('40'X),
    2   F_RETCO         BIN FIXED(31,0) INIT (0)  ALIGNED,
CALL FCRMSG ( MSGRC,
              F_RETCO,
              MSGLEN,
              MSGBUFF );

Parameters

[out]	rtc	INTEGER Return code for this function
[in]	code	INTEGER A valid error code from another call
[in,out]	msgLen	INTEGER Size/length of message buffer
[out]	msg	STRING Buffer for error message (is null-terminated)

◆ FCRTRC()

void FCRTRC	(	int *	rtc,
		const int *	code,
		int *	trcLen,
		char *	trc )

extern

Error trace.

This function can be used to get an error trace after a call to FCRINF, FCROPN, FCRGET, FCRPUT, FCRFLU, FCRPRV, FCRCLS, FCRHLP or FCRSYN. 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).

Parameters

[out]	rtc	INTEGER Return code for this function
[in]	code	INTEGER reserved (not used yet)
[in,out]	trcLen	INTEGER Size/length of trace buffer
[out]	trc	STRING Buffer for error trace (is null-terminated)

◆ FCRCLR()

void FCRCLR ( void ** hdl )

extern

Clear error information.

This function clears all error information (global errno and trace as well as if a handle provided the reason codes in the handle). This is useful before an open or an atomic function to not get the error trace of the previous call.

Parameters

[in] hdl POINTER File handle from FCROPN() or NULL

◆ FCRENV()

void FCRENV	(	int *	rtc,
		const int *	sys,
		const int *	std,
		const int *	envLen,
		const char *	envStr,
		int *	cnt )

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.

Sample call in COBOL:

WORKING-STORAGE SECTION.
01  F-RETCO         PIC S9(8) COMP VALUE 0.
01  F-SYSENV        PIC S9(8) COMP VALUE 1.
01  F-STDENV        PIC S9(8) COMP VALUE 1.
01  F-ENVLEN        PIC S9(8) COMP VALUE 200.
01  F-ENVAR         PIC X(200)
    VALUE 'KEYWORD1=VALUE1;KEYWORD2=VALUE2'
01  F-ENVCNT        PIC S9(8) COMP VALUE 0.
PROCEDURE DIVISION.
CALL  'FCRENV' USING F-RETCO,F-SYSENV,F-STDENV,
                     F-ENVLEN,F-ENVAR,F-ENVCNT.

Parameters

[out]	rtc	INTEGER Return code
[in]	sys	INTEGER Non-zero value to load system variables, 0 otherwise
[in]	std	INTEGER Non-zero value to load standard environment, 0 otherwise
[in]	envLen	INTEGER Length of the optional environment string (NULL if not provided or if the string is null-temrinated)
[in]	envStr	STRING Optional list (can be NULL or empty) of environment variables (KEYWORD=VALUE) separated by new line ('\n') or semicolon (';')
[out]	cnt	INTEGER Number of environment variables set (optional, can be NULL)

◆ FCRSYM()

void FCRSYM	(	int *	rtc,
		const int *	inpLen,
		const char *	inpStr,
		int *	outLen,
		char *	outStr )

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). If the replacement string is not found (FLMRTC_FND), the symbol string is copied to the output. The output string length is limited to 1024 bytes. The input buffer can be the output buffer (replacement).

Parameters

[out]	rtc	INTEGER Return code
[in]	inpLen	INTEGER Length of the symbol
[in]	inpStr	STRING Name of the symbol
[in,out]	outLen	INTEGER At input the space for the output string, on output the length of the output string
[out]	outStr	STRING Buffer for the output string

◆ FCROPNL()

void FCROPNL	(	int *	rtc,
		const int *	strLen,
		const char *	logStr )

extern

Open global facility for 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 FCRGETL(), FCRCPYL() and FCRCLRL() can be used to retrieve or clear the current log buffer contents. The logging facility must be closed with FCRCLSL().

An example log string to log only warnings:

"LOG(MESSAGE(WARN))"

Please use:

'FCRHLP(NULL,12,10,NULL,NULL,&buflen,buffer)'
'FCRSYN(NULL,12,10,NULL,NULL,&buflen,buffer)'

for more information.

Parameters

[out]	rtc	INTEGER Return code
[in]	strLen	INTEGER Length of log string (optional, can be NULL)
[in]	logStr	STRING Log string (optional, can be NULL))

◆ FCRGETL()

void FCRGETL	(	int *	maxCod,
		int *	bufLen,
		const char **	buffer )

extern

Get log information.

Returns the maximum error code since the last call to FCROPNL() or FCRCLRL(). 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

[out]	maxCod	INTEGER Maximum error code since last initialization (optional, can be NULL)
[out]	bufLen	INTEGER Length of the string in the log buffer (optional, can be NULL)
[out]	buffer	POINTER Pointer to the log buffer (optional, can be NULL)

◆ FCRCPYL()

void FCRCPYL	(	int *	maxCod,
		int *	bufLen,
		char *	buffer )

extern

Copies log information to a provided buffer.

Works like FCRGETL() but instead of returning a pointer to the log, the log is copied to the provided buffer. If the provided buffer is too small, the output is truncated. The output is always null-terminated. The parameter bufLen is set to the number of bytes written to buffer, excluding the null-termination. Hence, on truncation the returned length is one less than the buffer size.

Parameters

[out]	maxCod	INTEGER Maximum error code since last initialization (optional, can be NULL)
[in,out]	bufLen	INTEGER Size of `buffer` (input), length of written log data (output)
[out]	buffer	STRING Output buffer for log data

◆ FCRCLRL()

void FCRCLRL ( int * maxCod )

extern

Clear the log information.

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

Parameters

[out] maxCod INTEGER Returns maximum error code since last initialization (optional, can be NULL)

◆ FCRCLSL()

void FCRCLSL ( int * maxCod )

extern

Close the global logging facility.

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

Parameters

[out] maxCod INTEGER Maximum error code since last initialization (optional, can be NULL)

◆ FCRINF()

void FCRINF	(	int *	rtc,
		const int *	infoLen,
		const char *	infoStr,
		const int *	format,
		int *	buflen,
		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 an output buffer. If the buffer is too small, a FMLRTC_LEN error is returned, the buflen is set to the required length and the buffer is filled with the data up to the maximum.

The format parameter can be set to one of the following output formats:

1 - Simple list of strings with each line separated by \n and the whole text terminated by 0x00
2 - As XML string (in local charset) of strings with each line separated by \n and the whole text terminated by 0x00

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 string must start with GET. followed by the corresponding method (FILE/CCSIDS/...). Leading whitespace is ignored.

Examples:

"GET.FILE='~.TEXT.TEST'"
"GET.CCSIDS"

Please use:

'FCRHLP(NULL,11,10,NULL,NULL,&buflen,buffer)'
'FCRSYN(NULL,11,10,NULL,NULL,&buflen,buffer)'

for more information.

Parameters

[out]	rtc	INTEGER Return code
[in]	infoLen	INTEGER Length of info string
[in]	infoStr	STRING Info string with GET instructions
[in]	format	INTEGER Format specification for the output buffer
[in,out]	buflen	INTEGER Size/length of the output buffer
[out]	buffer	STRING Output buffer (data format depends on format parameter)

◆ FCROPN()

void FCROPN	(	void **	hdl,
		int *	rtc,
		const int *	fileLen,
		const char *	fileStr,
		const int *	formatLen,
		const char *	formatStr,
		int *	stateLen,
		char *	stateStr )

extern

Opens a file.

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 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 above shows writing the output to two different files in parallel: as FLAMFILE for IBM mainframes and as ZIP file for a Windows system.

Please use:

'FCRHLP/FCRSYN(NULL,1,10,NULL,NULL,buflen,buffer)'
'FCRHLP/FCRSYN(NULL,3,10,NULL,NULL,buflen,buffer)'
'FCRHLP/FCRSYN(NULL,8,10,NULL,NULL,buflen,buffer)'
'FCRHLP/FCRSYN(NULL,9,10,NULL,NULL,buflen,buffer)'

for more information.

The format string uses the syntax of the format.record() union which was specifically designed for the record interface to format the data elements into records. The string can contain all parameters supported by format.record(). Currently, the format parameter can be used to specify the character conversion. If no format string is passed, then the default CCSID is used to provide the records.

If the format string starts with format. then one of the corresponding objects (binary/char/text/record/element/...) can be used. This is mainly useful to read FLAM5 elements as records. If you choose one of the byte stream formatting methods (binary/char/text/xml) the data element could be a whole block of data with (almost) arbitrary length.

Examples:

"ccsid='UTF-8'"
"format.record(ccsid='UTF-8'")
"format.element(ccsid='IBM1141' attributes)"

Please use:

'FCRHLP/FCRSYN(NULL,2,10,NULL,NULL,buflen,buffer)'
'FCRHLP/FCRSYN(NULL,4,10,NULL,NULL,buflen,buffer)'

for more information.

With element formatting, you can read and write a serialized form of FLAM5 elements. For example, it can be used to tokenize an XML document and read these tokens (elements) for further processing. The serialized element format (version 0) is described by the structure FlmElmRec0 in the FLMDEF.h header. For COBOL, a corresponding copy book (SOFLMDEF) can be found in the SRCLIB folder.

The state string uses the syntax of the state() object which was specifically designed for the byte and record interface to manage the internal state information of FLAM. This object contains the current state of the data and is useful to transfer it from an FCROPN call for reading to an FCBOPN call for writing or to set a custom state when writing. 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. If you provide a NULL pinter or zero length for the state at read, no state is given. If a length for space and pointer to the buffers provided, then a length error is returned if the buffer too small. In this case the length field contains the required size. We recommend to use at least 1024 byte for the state string.

Examples: "state(member='MY.ORIGINAL.DATASET',RECF=FBA,RECL=120 CCSID=1141)"

Please use:

'FCRHLP(NULL,11,10,NULL,buflen,buffer)'
'FCRSYN(NULL,11,10,NULL,buflen,buffer)'

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 records. When opening a file for reading, the state string is returned via the stateStr parameter. When opening for writing, it is an input parameter that contains the state information for the data.

Sample call in COBOL:

01  FLUC-PARAMETER.
    02 F-ID     PIC S9(8)  COMP.
    02 F-RETCO  PIC S9(8)  COMP.
       88 FLUC-OK           VALUE  0.
       88 FLUC-EOF          VALUE  43.
    02  F-FILELEN  PIC S9(8)  COMP VALUE 60.
    02  F-FILE     PIC X(60)  VALUE
        'READ.TEXT(FILE=''DD:INPUT'' RECLEN=2040)'.
    02  F-FORMLEN  PIC S9(8)  COMP SYNC VALUE 20.
    02  F-FORM     PIC X(20)  VALUE
        'CCSID=''1141'''.
    02  F-STATLEN  PIC S9(8)  COMP SYNC VALUE 512.
    02  F-STAT     PIC X(512) VALUE ' '.
CALL  'FCROPN' USING F-ID, F-RETCO,
                     F-FILELEN, F-FILE,
                     F-FORMLEN, F-FORM,
                     F-STATLEN, F-STAT.

Sample call in PL1:

DCL FCROPN ENTRY EXTERNAL OPTIONS (ASM, FETCHABLE);
2 F_ID       BIN FIXED(31,0) INIT (0)  ALIGNED,
2 F_RETCO    BIN FIXED(31,0) INIT (0)  ALIGNED,
2 F_FILELEN  BIN FIXED(31,0) INIT (60) ALIGNED,
2 F_FILE     CHAR(60)        INIT ('READ.TEXT(FILE=''DD:INPUT'' RECLEN=2040)'),
2 F_FORMLEN  BIN FIXED(31,0) INIT (20) ALIGNED,
2 F_FORM     CHAR(20)        INIT ('CCSID=''1141'''),
2 F_STATLEN  BIN FIXED(31,0) INIT (512) ALIGNED,
2 F_STAT     CHAR(512)       INIT ('40'X),
 CALL FCROPN (F_ID,      F_RETCO,
              F_FILELEN, F_FILE,
              F_FORMLEN, F_FORM,
              F_STATLEN, F_STAT );

Parameters

[out]	hdl	POINTER File handle
[out]	rtc	INTEGER Return code
[in]	fileLen	INTEGER Length of file string (must be provided)
[in]	fileStr	STRING File string with READ/WRITE instructions
[in]	formatLen	INTEGER Length of format string (0 to use defaults)
[in]	formatStr	STRING Format string or NULL
[in,out]	stateLen	INTEGER Length of state string (NULL or 0 no state, minimum 1024)
[in,out]	stateStr	STRING State string (output at read, input for write)

◆ FCROPNV()

void FCROPNV	(	void **	hdl,
		void **	cnv,
		int *	rtc,
		const int *	convLen,
		const char *	convStr )

extern

Opens a converter.

This function opens an element data conversion module for read or write operations if format.element() is used. All functions ending with 'V' accept an additional conversion handle, which is only relevant if format.element() is done. With this set of 'V' functions, it is possible to define 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 the read type specification is required. If the converter is used for read operation a write type specification must be defined. The conversion string uses the syntax of the 'type' union designed for element conversion. The string must start with 'read.' or 'write.' followed by the corresponding data type specification (binary/string/integer/float/...). Leading whitespace is ignored.

You can also use a read conversion in a read operation. It makes sense, for example, to convert a string of an XML element containing a decimal number at read 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 memory conversion handle. You can provide the file handle for which the converter will be used, so that the system knows e.g. the CCSID of the data. Otherwise, UTF-8 is assumed as neutral character encoding, but with the INPUT() object it is possible to use another internal character set. By providing the file or memory conversion handle it can be made sure that the correct internal representation of the data is known and the converter is opened in the right manner for that file.

You can also use a conversion string (CONV.type(from() to())) which describe a complete external representation to external representation conversion. This form can be used with the functions FCRCONV / FCRCONP for an independent memory to memory conversion. One use case woud be 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())"

Please use:

'FCRHLP/FCRSYN(NULL,5,10,NULL,NULL,buflen,buffer)'
'FCRHLP/FCRSYN(NULL,6,10,NULL,NULL,buflen,buffer)'
'FCRHLP/FCRSYN(NULL,7,10,NULL,NULL,buflen,buffer)'

for more information.

Sample call in COBOL:

CALL  'FCROPNV' USING F-ID, F-CNV, F-RETCO,
                      F-CONVLEN, F-CONV.

Parameters

[in]	hdl	POINTER File or memory conversion handle from FCROPN or FCROPNV (optional)
[out]	cnv	POINTER Conversion handle
[out]	rtc	INTEGER Return code
[in]	convLen	INTEGER Length of conversion string (must be provided)
[in]	convStr	STRING Conversion string with READ/WRITE instructions

◆ FCRNEWM()

void FCRNEWM	(	void **	hdl,
		int *	rtc,
		const int *	formatLen,
		const char *	formatStr,
		const int *	stateLen,
		const char *	stateStr,
		const int *	format,
		int *	buflen,
		char *	buffer )

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 FCROPN() 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. Additionally you have the ability to get statistical information, since open or last re-open. This works like FCRCLS().

Sample call in COBOL:

CALL  'FCRNEWM' USING N-ID, N-RETCO,
                      N-FORMATLEN, N-FORMAT,
                      N-STATELEN, N-STATE,
                      N-STATISTICFMT, N-BUFLEN, N-BUFFER.

Parameters

[in,out]	hdl	POINTER File handle
[out]	rtc	INTEGER Return code
[in]	formatLen	INTEGER Length of format string (0 to use defaults)
[in]	formatStr	STRING Format string or NULL (to use previous formatting)
[in]	stateLen	INTEGER Length of state string (NULL or 0 no state, minimum 1024)
[in]	stateStr	STRING State string
[in]	format	INTEGER Format specification for the output buffer
[in,out]	buflen	INTEGER Size/length of the output buffer (0 = no statistics)
[out]	buffer	STRING Output buffer (data format depends on the `format` parameter)

◆ FCRPUT()

void FCRPUT	(	void **	hdl,
		int *	rtc,
		const int *	recLen,
		const char *	rec )

extern

Writes one record or element.

This function writes records to the output stream. The behavior depends on the formatting that has been selected when opening the file.

format.record(): Depending on the record formatting method, the length of the data is either recorded, discarded or replaced by a delimiter or length field.

: Each call to FCRPUT is transformed into one record. Only one record can be written per call when using record I/O. The record length is not limited when formatting the elements in memory. However, when writing records to a dataset or a FLAMFILE, respective limits apply. Therefore, in the file string, you can specify how longer records are handled (cut, wrap or error).

format.element(): To write elements, the buffer pointed to by rec 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 length in bytes of the serialized element structure must be passed via parameter recLen. 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 in C.

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

Depending on the file and format strings passed to FCROPN(), you can, for example, write EBCDIC records in IBM1141 and the result will be an ASCII-armored, compressed and encrypted PGP file in CP1252 where each record is delimited with 0x0D0A for a Windows system.

Sample call in COBOL:

CALL 'FCRPUT' USING F-ID, F-RETCO,
                    F-RECLEN, F-RECORD.

Parameters

[in]	hdl	POINTER File handle from FCROPN()
[out]	rtc	INTEGER Return code
[in]	recLen	INTEGER Length of the record
[in]	rec	STRING Record (binary data)

◆ FCRPUTV()

void FCRPUTV	(	void **	hdl,
		int *	rtc,
		const int *	recLen,
		const char *	rec,
		void **	cnv )

extern

Writes one element with conversion.

This function works like FCRPUT but accepts one additional parameter cnv which point to 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 a handle by calling FCROPNV and request an individual conversion for that element.

Sample call in COBOL:

CALL 'FCRPUTV' USING F-ID, F-RETCO,
                     F-RECLEN, F-RECORD,
                     F-CNV.

Parameters

[in]	hdl	POINTER File handle from FCROPN()
[out]	rtc	INTEGER Return code
[in]	recLen	INTEGER Length of the record
[in]	rec	STRING Record (binary data)
[in]	cnv	POINTER Conversion handle from FCROPNV()

◆ FCRGTN()

void FCRGTN	(	void **	hdl,
		int *	rtc,
		int *	length,
		char *	name )

extern

Get table name.

If you use the table support at read with end of table handling (ENDOFT) then you can determine the current table name (logical name defined in the row specification) after open and EOT using this function.

The function truncates the table name if the provided buffer is too small. Using such a shorted table name in FCRSTN will cause a "table name does not fit" error.

Sample call in COBOL:

CALL 'FCRGTN' USING F-ID, F-RETCO, F-LENGTH, F-NAME.

Parameters

[in]	hdl	POINTER File handle from FCROPN()
[out]	rtc	INTEGER Return code
[in,out]	length	INTEGER Buffer size for `name` (input), Length of the table name (output)
[out]	name	STRING Buffer that the table name is written to (ATTENTION: truncated if provided buffer too small)

◆ FCRGFN()

void FCRGFN	(	void **	hdl,
		int *	rtc,
		const int	ind,
		int *	length,
		char *	name )

extern

Get 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 FCRFLU() in front of FCRCLS(). At read the original file name read will be returned and the index ignored.

The function truncates the file name if the provided buffer is too small.

Sample call in COBOL:

CALL 'FCRGFN' USING F-ID, F-RETCO, F-INDEX, F-LENGTH, F-NAME.

Parameters

[in]	hdl	POINTER File handle from FCROPN()
[out]	rtc	INTEGER Return code
[in]	ind	INTEGER Index if multiple writes defined else set to 0
[in,out]	length	INTEGER Buffer size for `name` (input), Length of the file name (output)
[out]	name	STRING Buffer that the file name is written to (ATTENTION: truncated if provided buffer too small)

◆ FCRSTN()

void FCRSTN	(	void **	hdl,
		int *	rtc,
		const int *	length,
		const char *	name )

extern

Set table name.

If you write more than one table to a file, the current table format can be set with this function. The function only succeeds at the end of a complete row. It fails if there is a remainder in the buffer. The automatic detection of the table format is deactivated. The provided data must match with the defined row specification. Auto detection of the table format can be reactivated with a call to FCRGTN(). A call to FCRSTN() will start a new table of the same or another format. If ENDOFT is activated in the format string while writing, then FLMRTC_EOT is handled internally and the file handle will be re-opened. By using the [table] in your output file name, you can split the data and write it to different files.

Sample call in COBOL:

CALL 'FCRSTN' USING F-ID, F-RETCO, F-LENGTH, F-NAME.

Parameters

[in]	hdl	POINTER File handle from FCROPN()
[out]	rtc	INTEGER Return code
[in]	length	INTEGER Length of the table name
[in]	name	STRING Table name in provide length

◆ FCRFLU()

void FCRFLU	(	void **	hdl,
		int *	rtc )

extern

Flush internal buffers.

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

Sample call in COBOL:

CALL 'FCRFLU' USING F-ID, F-RETCO.

Parameters

[in]	hdl	POINTER File handle from FCROPN()
[out]	rtc	INTEGER Return code

◆ FCRGET()

void FCRGET	(	void **	hdl,
		int *	rtc,
		int *	recLen,
		char *	rec )

extern

Reads one record or element.

Reads one record per function call from the input file. The behavior depends on the formatting that has been selected when opening the file.

format.record(): In record formatting mode, set recLen to the maximum expected length of the record, to obtain the number of bytes. If the record attempted to read is longer than recLen, the function will fail with the return code rtc set to FLMRTC_LEN. In this case, you can allocate more space and try to read the same record again. The required space is returned in reclen. There is no limit on record length, but the record length may be limited by the underlying data management system (DMS). Most record-oriented DMS are limited to a maximum record length of 32760 bytes. The record I/O of FLAM has currently a limit of 1 MiB for the maximum record length.

Note: If record I/O is used, then the returned number of bytes can be zero because records can contain zero-length data.

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 record buffer pointed to by rec contains an element matching the structure FlmElmRec0. Anything else works like record I/O.

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

: With element formatting, the function reads one element at a time and writes it into the supplied record buffer of length recLen. If the buffer is too small, the return code rtc is set to 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 the structure (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.

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. In future versions, additional structures might be added. Checking the version field avoids misinterpreting the data by using the wrong structure.

format.binary/char/text/xml(): In this case reclen bytes are read and copy to rec.

Sample call in COBOL:

01  FLUC-PARAMETER.
    02 F-ID     PIC S9(8)  COMP.
    02 F-RETCO  PIC S9(8)  COMP.
       88 FLUC-OK           VALUE  0.
       88 FLUC-EOF          VALUE  43.
    02  F-INLEN   PIC S9(8) COMP.
01  OUTDAT-RECORD.
    02 FILLER   PIC X(2040).
CALL 'FCRGET' USING F-ID, F-RETCO,
                    F-INLEN, OUTDAT-RECORD

Sample call in PL1:

DCL FCRGET ENTRY EXTERNAL OPTIONS (ASM, FETCHABLE);
2 F_ID       BIN FIXED(31,0) INIT (0)  ALIGNED,
2 F_RETCO    BIN FIXED(31,0) INIT (0)  ALIGNED,
2 F_INLEN    BIN FIXED(31,0),
DCL  1  OUTREC   CHAR(2040);
CALL FCRGET ( F_ID,
              F_RETCO,
              F_INLEN,
              OUTREC  );

The function sets the return code to FLMRTC_EOF (43) if the end of file is encountered. To read a whole file you have to call FCRGET() in a loop until the return code is 43.

Parameters

[in]	hdl	POINTER File handle from FCROPN()
[out]	rtc	INTEGER Return code
[in,out]	recLen	INTEGER Size/length of the record buffer
[out]	rec	STRING Record buffer (binary data)

◆ FCRGETV()

void FCRGETV	(	void **	hdl,
		int *	rtc,
		int *	recLen,
		char *	rec,
		void **	cnv,
		int *	skip )

extern

Reads one element with conversion.

This function works like FCRGET but accepts two additional parameter cnv which 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 FCROPNV 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 for example to ignore these data elements. With FLMELM_NOSKIP the next element is given.

Sample call in COBOL:

CALL 'FCRGETV' USING F-ID, F-RETCO,
                     F-RECLEN, F-RECORD,
                     F-CNV F-SKIP.

The function sets the return code to FLMRTC_EOF (43) if the end of file is encountered. To read a whole file you have to call FCRGET() in a loop until the return code is 43.

Parameters

[in]	hdl	POINTER File handle from FCROPN()
[out]	rtc	INTEGER Return code
[in,out]	recLen	INTEGER Size/length of the record buffer
[out]	rec	STRING Record buffer (binary data)
[in]	cnv	POINTER Conversion handle from FCROPNV()
[in]	skip	INTEGER Skip this element type (NULL no skip)

◆ FCRLOC()

void FCRLOC	(	void **	hdl,
		int *	rtc,
		int *	recLen,
		char **	rec )

extern

Locates one record or element (without own buffer)

The function works like FCRGET(), but it returns a memory address to a buffer containing the record instead of copying the data into the memory provided by the caller. (no length error can occur)

If you use FCRLOC() for record I/O, recLen is an output parameter that contains the length of the record. The pointer to the record buffer rec is only valid up to the next function call on this handle.

Be careful with the returned record pointer because it breaks the isolation and if you manipulate the data area behind this pointer, you can destroy internal structures.

Sample call in COBOL:

CALL 'FCRLOC' USING F-ID, F-RETCO,
                    F-RECLEN, P-RECORD.

The function sets the return code to FLMRTC_EOF (43) if the end of file is encountered. To read a whole file you have to call FCRLOC() in a loop until the return code is 43.

Parameters

[in]	hdl	POINTER File handle from FCROPN()
[out]	rtc	INTEGER Return code
[out]	recLen	INTEGER Length of the record buffer
[out]	rec	POINTER Pointer to the record buffer

◆ FCRLOCV()

void FCRLOCV	(	void **	hdl,
		int *	rtc,
		int *	recLen,
		char **	rec,
		void **	cnv,
		int *	skip )

extern

Reads one element with conversion (without own buffer)

This function works like FCRLOC but accepts two additional parameter cnv which 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 FCROPNV 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 for example to ignore these data elements. With FLMELM_NOSKIP the next element is given.

Sample call in COBOL:

CALL 'FCRLOCV' USING F-ID, F-RETCO,
                     F-RECLEN, P-RECORD,
                     F-CNV F-SKIP.

Parameters

[in]	hdl	POINTER File handle from FCROPN()
[out]	rtc	INTEGER Return code
[out]	recLen	INTEGER Length of the record buffer
[out]	rec	POINTER Pointer to the record buffer
[in]	cnv	POINTER Conversion handle from FCROPNV()
[in]	skip	INTEGER Skip this element type (NULL no skip)

◆ FCRPRV()

void FCRPRV	(	void **	hdl,
		int *	rtc )

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 FCRGET() will return the same element or record as the last one.

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

Sample call in COBOL:

CALL 'FCRPRV' USING F-ID, F-RETCO.

Parameters

[in]	hdl	POINTER File handle from FCROPN()
[out]	rtc	INTEGER Return code

◆ FCRCONV()

void FCRCONV	(	void **	cnv,
		int *	rtc,
		const int *	inpLen,
		const char *	inp,
		int *	outLen,
		char *	out )

extern

Converts element data (with copy)

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

It provides memory to memory conversion between external data representations of different data types using a conversion handle from function FCROPNV() 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 FCRRUNV() and FCRFINV().

Sample call in COBOL:

CALL 'FCRCONV' USING C-ID, C-RETCO.
                     C-INPLEN, C-INP,
                     C-OUTLEN, C-OUT.

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:

FCROPNV(hdl,rtc,"...");
if (rtc) then return(rtc);
do {
   do {
      FCRGTN(hdl,...);
      outlen=0; // ensure a length error
      FCRCONV(hdl,rtc,inplen,input,outlen,output);
      if (rtc==FLMRTC_LEN) then {
         output=realloc(output,outlen);
         FCRCONV(hdl,rtc,inplen,input,outlen,output);
      }
      if (rtc && rtc!=FLMRTC_EOT) then {
         FCRCLSV(hdl,NULL);
         return(rtc);
      }
      if (outlen>0) then {
        // process output
      }
   } while(rtc==FLMRTC_EOT);
   input+=inplen; // goto next input
} while (input<end && rtc==FLMRTC_OK);
FCRCLSV(hdl,NULL);
return(rtc);

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

Parameters

[in]	cnv	POINTER Conversion handle from FCROPNV()
[out]	rtc	INTEGER Return code
[in]	inpLen	INTEGER Length of the input buffer
[in]	inp	POINTER Pointer to the input buffer
[in,out]	outLen	INTEGER 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 Pointer to the output buffer

◆ FCRCONP()

void FCRCONP	(	void **	cnv,
		int *	rtc,
		const int *	inpLen,
		const char *	inp,
		int *	outLen,
		char **	out )

extern

Converts element data (with locate)

This function is identical to FCRCONV(), 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	POINTER Conversion handle from FCROPNV()
[out]	rtc	INTEGER Return code
[in]	inpLen	INTEGER Length of the input buffer
[in]	inp	POINTER Pointer to the input buffer
[out]	outLen	INTEGER Length of the output buffer
[out]	out	POINTER Pointer to the output buffer pointer

◆ FCRRUNV()

void FCRRUNV	(	void **	cnv,
		int *	rtc,
		const int *	inpLen,
		const char *	inp,
		int *	outLen,
		char *	out )

extern

Converts dependent data blocks (with copy)

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

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

This function must be used instead of FCRCONV() 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 FCRFINV() must be called to force any pending data to be processed and written to the output buffer. Failing to call FCRFINV() might result 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.

Sample call in COBOL:

CALL 'FCRRUNV' USING C-ID, C-RETCO.
                     C-INPLEN, C-INP,
                     C-OUTLEN, C-OUT.

Parameters

[in]	cnv	POINTER Conversion handle from FCROPNV()
[out]	rtc	INTEGER Return code
[in]	inpLen	INTEGER Length of the input buffer
[in]	inp	POINTER Pointer to the input buffer
[in,out]	outLen	INTEGER 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 Pointer to the output buffer

◆ FCRRUNP()

void FCRRUNP	(	void **	cnv,
		int *	rtc,
		const int *	inpLen,
		const char *	inp,
		int *	outLen,
		char **	out )

extern

Converts dependent data blocks (with locate)

This function is identical to FCRRUNV(), 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	POINTER Conversion handle from FCROPNV()
[out]	rtc	INTEGER Return code
[in]	inpLen	INTEGER Length of the input buffer
[in]	inp	POINTER Pointer to the input buffer
[out]	outLen	INTEGER Length of the output buffer
[out]	out	POINTER Pointer to the output buffer pointer

◆ FCRFINV()

void FCRFINV	(	void **	cnv,
		int *	rtc,
		const int *	inpLen,
		const char *	inp,
		int *	outLen,
		char *	out )

extern

Finish conversion of dependent data blocks (with copy)

This function must be called to finish data conversion when FCRRUNV() is used. It forces all internally buffered, but unprocessed data to be converted and written to the output 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.

Sample call in COBOL:

CALL 'FCRFINV' USING C-ID, C-RETCO.
                     C-INPLEN, C-INP,
                     C-OUTLEN, C-OUT.

Parameters

[in]	cnv	POINTER Conversion handle from FCROPNV()
[out]	rtc	INTEGER Return code
[in]	inpLen	INTEGER Length of the input buffer
[in]	inp	POINTER Pointer to the input buffer
[in,out]	outLen	INTEGER 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 Pointer to the output buffer

◆ FCRFINP()

void FCRFINP	(	void **	cnv,
		int *	rtc,
		const int *	inpLen,
		const char *	inp,
		int *	outLen,
		char **	out )

extern

Finish conversion of dependent data blocks (with locate)

This function is identical to FCRFINV(), 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	POINTER Conversion handle from FCROPNV()
[out]	rtc	INTEGER Return code
[in]	inpLen	INTEGER Length of the input buffer
[in]	inp	POINTER Pointer to the input buffer
[out]	outLen	INTEGER Length of the output buffer
[out]	out	POINTER Pointer to the output buffer pointer

◆ FCRCLS()

void FCRCLS	(	void **	hdl,
		int *	rtc,
		const int *	success,
		const int *	format,
		int *	buflen,
		char *	buffer )

extern

Closes a file.

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.

The success flag, if set, allows the removal of the input file after closing if the remove after close flag was set at read when opening the file. In case of an error, it is usually not desirable to delete the original file, but only if processing was successful. This flag tells the close function whether processing was successful (success=1) or not (success=0). At write the opposite behavior are implemented. If a write fails and the remove switch is defined, then the file will be deleted.

Statistics information can be requested by providing an output buffer. The buffer is filled up to its maximum length. There is no second chance to collect the missing statistics information if the buffer too small. The format parameter specifies the output format and can be set to one of the following output formats:

1 - Simple list of strings with each line separated by \n and the whole text terminated by 0x00
2 - As XML string (in local charset) of strings with each line separated by \n and the whole text terminated by 0x00

Sample call in COBOL:

01  FLUC-PARAMETER.
    02 F-ID     PIC S9(8)  COMP.
    02 F-RETCO  PIC S9(8)  COMP.
       88 FLUC-OK           VALUE  0.
       88 FLUC-EOF          VALUE  43.
    02  C-DELETE  PIC S9(8) COMP VALUE 0.
    02  C-STATFMT PIC S9(8) COMP VALUE 1.
    02  C-STATLEN PIC S9(8) COMP VALUE 4096.
    02  C-STATBUF PIC X(4096) VALUE SPACES.
CALL 'FCRCLS' USING F-ID, F-RETCO, C-DELETE
                    C-STATFMT, C-STATLEN, C-STATBUF.

Sample call in PL1:

DCL FCRCLS ENTRY EXTERNAL OPTIONS (ASM, FETCHABLE);
2 F_ID       BIN FIXED(31,0) INIT (0)  ALIGNED,
2 F_RETCO    BIN FIXED(31,0) INIT (0)  ALIGNED,
2 C_DELETE   BIN FIXED(31,0) INIT (0)  ALIGNED,
2 C_STATFMT  BIN FIXED(31,0) INIT (1)  ALIGNED,
2 C_STATLEN  BIN FIXED(31,0) INIT (4096)
                                       ALIGNED,
2  C_STATBUF CHAR(4096)      INIT ('40'X),
CALL FCRCLS ( F_ID,
              F_RETCO,
              C_DELETE,
              C_STATFMT,
              C_STATLEN,
              C_STATBUF );

Parameters

[in]	hdl	POINTER File handle from FCROPN()
[out]	rtc	INTEGER Return code
[in]	success	INTEGER True (not 0) if success else false (0) to manage remove of files if requested
[in]	format	INTEGER Format specification for the output buffer
[in,out]	buflen	INTEGER Size/length of the output buffer (0 = no statistics)
[out]	buffer	STRING Output buffer (data format depends on format parameter)

◆ FCRCLSV()

void FCRCLSV	(	void **	cnv,
		int *	rtc )

extern

Closes a converter.

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

Sample call in COBOL:

CALL 'FCRCLSV' USING F-CNV, F-RETCO.

Parameters

[in]	cnv	POINTER Conversion handle from FCROPNV()
[out]	rtc	INTEGER Return code

◆ FCRCPY()

void FCRCPY	(	const int *	len,
		const char *	ptr,
		char *	dat )

extern

Copy a memory area (MF-EDZ pointer handling workaround)

The function FCRCPY() was mainly implemented to copy memory pointed to by a native pointer, which was provided by our locate functions, to local memory of the using application as a workaround for the MF-EDZ pointer handling bug, if AMODE=31 is used.

Sample call in COBOL:

CALL 'FCRCPY' USING
      BY REFERENCE F-LEN,
      BY VALUE     F-PTR,
      BY REFERENCE F-DAT.

Parameters

[in]	len	INTEGER Length of the data
[in]	ptr	POINTER Data pointer from locate functions (FCRLOC(), FCRCONP(), ...)
[out]	dat	POINTER Pointer to local buffer with enough space to copy full length

◆ FCRPTR()

void FCRPTR	(	const char *	dat,
		const char **	ptr )

extern

Convert pointer to native format (MF-EDZ pointer handling workaround)

The function below was mainly implemented to convert a local EDZ pointer to a native pointer usable with external libraries as workaround for the MF-EDZ pointer handling bug, if AMODE=31 is used.

Sample call in COBOL:

CALL 'FCRPTR' USING
      BY REFERENCE F-DAT,
      BY REFERENCE F-PTR.

Parameters

[in]	dat	POINTER Pointer to local data item
[out]	ptr	POINTER Pointer to native pointer value

◆ FCRCNT()

void FCRCNT	(	void **	hdl,
		int *	rtc,
		const int *	dir,
		const int *	wht,
		const int *	knd,
		long long int *	val )

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.

Sample call in COBOL:

CALL  'FCRCNT' USING F-HDL, F-RTC, F-DIR, F-WHT, F-KND, F-VAL.

ATTENTION: The processed amount of data can be bigger than 4 GiB, the value parameter is a 64 bit integer (must point to a 8 byte field).

Parameters

[in]	hdl	POINTER File or memory conversion handle from FCROPN() or FCROPNV()
[out]	rtc	INTEGER Return code
[in]	dir	INTEGER Input (1) or output (2), if NULL then output
[in]	wht	INTEGER File I/O (1) or Formating (2), if NULL the formatting
[in]	knd	INTEGER Bytes (1) or Units (2), if NULL then bytes
[out]	val	INTEGER The requested amount in 64 Bit (8 Byte)

◆ FCRBINI()

int FCRBINI	(	void **	hdl,
		const unsigned int *	mode,
		const unsigned int *	base,
		const unsigned int *	chrs )

extern

Initialize base encoding or decoding.

If base encoding needs to be run over several scattered junks of data it can be done with the following calling sequence:

   FCRBINI()
   FCRBRUN()
   FCRBRUN()
   ...
   FCRBFIN()

FCRBINI() will return an initialized handle for use in FCRBRUN() and FCRBFIN().

Sample call in COBOL:

CALL  'FCRBINI' USING F-HDL, F-MODE, F-BASE, F-CHRS
                RETURNING INTO F-RES.

Parameters

[out]	hdl	POINTER Handle to this encoding
[in]	mode	INTEGER Mode: 1 is Encode and 0 is Decode (if NULL it defaults to Encode)
[in]	base	INTEGER Base: possible values 16, 32 or 64 (if NULL it defaults to 16)
[in]	chrs	INTEGER Character set: 1 is ASCII and 2 is EBCDIC otherwise the system character set is used

Returns: INTEGER 0 if success else error

◆ FCRBRUN()

int FCRBRUN	(	void **	hdl,
		const unsigned int *	datlen,
		const unsigned char *	dat,
		unsigned char *	out )

extern

En- or Decode a junk of data.

FCRBRUN() will process a piece of binary data. The hdl must be initialized by FCRBINI() first. The output buffer must be big enough to write the encoding. If it is too small the areas behind it will be overwritten.

Sample call in COBOL:

CALL  'FCRBRUN' USING F-HDL, F-DATLEN, F-DAT, F-OUT
                RETURNING INTO F-RES.

Parameters

[in]	hdl	POINTER Handle to this encoding initialized before with FCRBINI()
[in]	datlen	INTEGER Length of `dat` (if NULL it defaults to 0)
[in]	dat	STRING Input data chunk for en- or decoding
[out]	out	STRING Output data chunk

Returns: INTEGER >=0 produced output length else error

◆ FCRBFIN()

int FCRBFIN	(	void **	hdl,
		const unsigned int *	datlen,
		const unsigned char *	dat,
		unsigned char *	out )

extern

Finalize en- or decoding.

FCRBFIN() will process the last piece of data and write all buffered data to out. The hdl must be initialized by FCRBINI() first and is released afterwards. The output buffer must be big enough to write the encoding. If it is too small the areas behind it will be overwritten.

Sample call in COBOL:

CALL  'FCRBFIN' USING F-HDL, F-DATLEN, F-DAT, F-OUT
                RETURNING INTO F-RES.

Parameters

[in,out]	hdl	POINTER Handle to this encoding initialized before with FCRBINI()
[in]	datlen	INTEGER Length of `dat` (if NULL it defaults to 0)
[in]	dat	STRING Input data chunk for en- or decoding
[out]	out	STRING Output data chunk

Returns: INTEGER >=0 produced output length else error

◆ FCRBASE()

int FCRBASE	(	const unsigned int *	mode,
		const unsigned int *	base,
		const unsigned int *	chrs,
		const unsigned int *	datlen,
		const unsigned char *	dat,
		unsigned char *	out )

extern

Base encoding or decoding for one message.

The FCRBASE() function does the same as FCRBINI() and FCRBFIN() It is a shortcut if the input data is not scattered.

Sample call in COBOL:

CALL  'FCRBASE' USING F-MODE, F-BASE, F-CHRS,
                      F-DATLEN, F-DAT, F-OUT
                RETURNING INTO F-RES.

Parameters

[in]	mode	INTEGER Mode: 1 is Encode and 0 is Decode (if NULL it defaults to Encode)
[in]	base	INTEGER Base: possible values 16, 32 or 64 (if NULL it defaults to 16)
[in]	chrs	INTEGER Character set: 1 is ASCII and 2 is EBCDIC otherwise the system character set is used
[in]	datlen	INTEGER Length of `dat` (if NULL it defaults to 0)
[in]	dat	STRING Input data for en- or decoding
[out]	out	STRING Output data

Returns: INTEGER >=0 produced output length else error

◆ FCRHINI()

int FCRHINI	(	void **	hdl,
		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.

If a hash needs to be calculated over several scattered junks of data it can be done with the following calling sequence:

   FCRHINI()
   FCRHADD()
   FCRHADD()
   ...
   FCRHFIN()

FCRHINI will initialize the hdl parameter for use in FCRHADD() and FCRHFIN().

Sample call in COBOL:

CALL  'FCRHINI' USING F-HDL, F-HMTD, F-KMTD,
                     F-KEYLEN, F-KEY,
                     F-ICVLEN, F-ICV
                RETURNING INTO F-RES.

Parameters

[out]	hdl	POINTER Handle to this hash
[in]	hmtd	INTEGER Hash method to use, for example FLCHSH_ALGO_SHA1 see header FLMDEF.h
[in]	kmtd	INTEGER MAC method to use, for example FLCMAC_ALGO_HMAC see header file FLMDEF.h
[in]	keylen	INTEGER length of `key`
[in]	key	STRING key to use in hash calculation
[in]	icvlen	INTEGER Length of `icv`
[in]	icv	STRING Initial chaining vector (only for certain MAC calculation)

Returns: INTEGER 0 if success else error

◆ FCRHADD()

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

extern

Add a junk of data to the hash calculation buffer.

FCRHADD() will add a piece of binary data to the hash calculation. The hdl must be initialized by FCRHINI() first.

Sample call in COBOL:

CALL  'FCRHADD' USING F-HDL, F-DATLEN, F-DAT
                RETURNING INTO F-RES.

Parameters

[in]	hdl	POINTER Handle to this hash initialized before with FCRHINI()
[in]	datlen	INTEGER length of `dat`
[in]	dat	STRING input data chunk to add to hash calculation

Returns: INTEGER 0 if success else error

◆ FCRHFIN()

int FCRHFIN	(	void **	hdl,
		unsigned int *	hshlen,
		unsigned char *	hsh )

extern

Finalize hash calculation.

FCRHFIN() will store the calculated hash to the hsh parameter. The hdl must be initialized by FCRHINI() first and is released afterwards. The parameter @ hshlen must contain on input the size of the hash buffer and will contain on output the length of the hash. If the output buffer shorter then the hash length, the hash will be truncated.

Sample call in COBOL:

CALL  'FCRHFIN' USING F-HDL, F-HSHLEN, F-HSH
                RETURNING INTO F-RES.

Parameters

[in,out]	hdl	POINTER Handle to this hash initialized before with FCRHINI()
[in,out]	hshlen	INTEGER On input size of `hsh` on output length of p@ hsh
[out]	hsh	STRING Buffer where calculated hash is written to

Returns: INTEGER 0 if success else error

◆ FCRHASH()

int FCRHASH	(	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 one message.

The FCRHASH() function does the same as FCRHINI(), FCRHADD(), FCRHFIN() It is a shortcut if the input data is not scattered.

Sample call in COBOL:

CALL  'FCRHASH' USING F-HMTD, F-KMTD,
                     F-KEYLEN, F-KEY,
                     F-ICVLEN, F-ICV,
                     F-DATLEN, F-DAT,
                     F-HSHLEN, F-HSH
                RETURNING INTO F-RES.

Parameters

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

Returns: INTEGER 0 if success else error

Functions

Detailed Description

Function Documentation

◆ FCRVSN()

◆ FCRABO()

◆ FCRLIC()

◆ FCRHLP()

◆ FCRSYN()

◆ FCRMSG()

◆ FCRTRC()

◆ FCRCLR()

◆ FCRENV()

◆ FCRSYM()

◆ FCROPNL()

◆ FCRGETL()

◆ FCRCPYL()

◆ FCRCLRL()

◆ FCRCLSL()

◆ FCRINF()

◆ FCROPN()

◆ FCROPNV()

◆ FCRNEWM()

◆ FCRPUT()

◆ FCRPUTV()

◆ FCRGTN()

◆ FCRGFN()

◆ FCRSTN()

◆ FCRFLU()

◆ FCRGET()

◆ FCRGETV()

◆ FCRLOC()

◆ FCRLOCV()

◆ FCRPRV()

◆ FCRCONV()

◆ FCRCONP()

◆ FCRRUNV()

◆ FCRRUNP()

◆ FCRFINV()

◆ FCRFINP()

◆ FCRCLS()

◆ FCRCLSV()

◆ FCRCPY()

◆ FCRPTR()

◆ FCRCNT()

◆ FCRBINI()

◆ FCRBRUN()

◆ FCRBFIN()

◆ FCRBASE()

◆ FCRHINI()

◆ FCRHADD()

◆ FCRHFIN()

◆ FCRHASH()