FLCREC-API FLUC Record Interface

Functions
Functions

## Functions
void | FCRVSN (int *rtc, int *vsnLen, char *vsn)
| Retrieves the version string. More...
void | FCRABO (int *rtc, int *aboLen, char *abo)
| Retrieves the about string. More...
void | FCRLIC (int *rtc, int *licLen, char *lic)
| Gets the license text. More...
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. More...
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. More...
void | FCRMSG (int *rtc, const int *code, int *msgLen, char *msg)
| Retrieves an error message. More...
void | FCRTRC (int *rtc, const int *code, int *trcLen, char *trc)
| Error trace. More...
void | FCRCLR (void **hdl)
| Clear error information. More...
void | FCRENV (int *rtc, const int *sys, const int *std, const int *envLen, const char *envStr, int *cnt)
| Load the FLAM environment. More...
void | FCRSYM (int *rtc, const int *inpLen, const char *inpStr, int *outLen, char *outStr)
| Determines a symbol from environment. More...
void | FCROPNL (int *rtc, const int *strLen, const char *logStr)
| Open global facility for memory logging. More...
void | FCRGETL (int *maxCod, int *bufLen, const char **buffer)
| Get log information. More...
void | FCRCPYL (int *maxCod, int *bufLen, char *buffer)
| Copies log information to a provided buffer. More...
void | FCRCLRL (int *maxCod)
| Clear the log information. More...
void | FCRCLSL (int *maxCod)
| Close the global logging facility. More...
void | FCRINF (int *rtc, const int *infoLen, const char *infoStr, const int *format, int *buflen, char *buffer)
| Provides various information. More...
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. More...
void | FCROPNV (void **hdl, void **cnv, int *rtc, const int *convLen, const char *convStr)
| Opens a converter. More...
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. More...
void | FCRPUT (void **hdl, int *rtc, const int *recLen, const char *rec)
| Writes one record or element. More...
void | FCRPUTV (void **hdl, int *rtc, const int *recLen, const char *rec, void **cnv)
| Writes one element with conversion. More...
void | FCRGTN (void **hdl, int *rtc, int *length, char *name)
| Get table name. More...
void | FCRGFN (void **hdl, int *rtc, const int ind, int *length, char *name)
| Get file name. More...
void | FCRSTN (void **hdl, int *rtc, const int *length, const char *name)
| Set table name. More...
void | FCRFLU (void **hdl, int *rtc)
| Flush internal buffers. More...
void | FCRGET (void **hdl, int *rtc, int *recLen, char *rec)
| Reads one record or element. More...
void | FCRGETV (void **hdl, int *rtc, int *recLen, char *rec, void **cnv, int *skip)
| Reads one element with conversion. More...
void | FCRLOC (void **hdl, int *rtc, int *recLen, char **rec)
| Locates one record or element (without own buffer) More...
void | FCRLOCV (void **hdl, int *rtc, int *recLen, char **rec, void **cnv, int *skip)
| Reads one element with conversion (without own buffer) More...
void | FCRPRV (void **hdl, int *rtc)
| Sets the read position to the previous record or element. More...
void | FCRCONV (void **cnv, int *rtc, const int *inpLen, const char *inp, int *outLen, char *out)
| Converts element data (with copy) More...
void | FCRCONP (void **cnv, int *rtc, const int *inpLen, const char *inp, int *outLen, char **out)
| Converts element data (with locate) More...
void | FCRRUNV (void **cnv, int *rtc, const int *inpLen, const char *inp, int *outLen, char *out)
| Converts dependent data blocks (with copy) More...
void | FCRRUNP (void **cnv, int *rtc, const int *inpLen, const char *inp, int *outLen, char **out)
| Converts dependent data blocks (with locate) More...
void | FCRFINV (void **cnv, int *rtc, const int *inpLen, const char *inp, int *outLen, char *out)
| Finish conversion of dependent data blocks (with copy) More...
void | FCRFINP (void **cnv, int *rtc, const int *inpLen, const char *inp, int *outLen, char **out)
| Finish conversion of dependent data blocks (with locate) More...
void | FCRCLS (void **hdl, int *rtc, const int *success, const int *format, int *buflen, char *buffer)
| Closes a file. More...
void | FCRCLSV (void **cnv, int *rtc)
| Closes a converter. More...
void | FCRCPY (const int *len, const char *ptr, char *dat)
| Copy a memory area (MF-EDZ pointer handling workaround) More...
void | FCRPTR (const char *dat, const char **ptr)
| Convert pointer to native format (MF-EDZ pointer handling workaround) More...
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. More...
int | FCRBINI (void **hdl, const unsigned int *mode, const unsigned int *base, const unsigned int *chrs)
| Initialize base encoding or decoding. More...
int | FCRBRUN (void **hdl, const unsigned int *datlen, const unsigned char *dat, unsigned char *out)
| En- or Decode a junk of data. More...
int | FCRBFIN (void **hdl, const unsigned int *datlen, const unsigned char *dat, unsigned char *out)
| Finalize en- or decoding. More...
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. More...
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. More...
int | FCRHADD (void **hdl, const unsigned int *datlen, const unsigned char *dat)
| Add a junk of data to the hash calculation buffer. More...
int | FCRHFIN (void **hdl, unsigned int *hshlen, unsigned char *hsh)
| Finalize hash calculation. More...
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. More...

## Detailed Description

## Function Documentation

## ◆ FCRVSN()

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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