This interface provides all FLCL commands (CONV, XCNV, ...) based on the Frankenstein Limes Universal Converter (FLUC) as simple to use and programming language independent load modules. It is mainly meant to be used for Assembler, COBOL and PL1 on mainframe systems. It can also be used in C through the fetch() function, but the C like FLUCUP native interface is easier to use in this case.

For each command, there is a function that accepts a command line and property file string that follows the FLCL syntax and produces the same condition code as FLCL. The property file string is parsed before the command line string. The property string may contain command properties in the property file syntax of FLCL based on the default owner "limes". You can read an FLCL property file programmatically and provide its content as this string. To generate a property file please use:

    FLCL GENPROP command=filename

It is currently not possible to change the owner id or program name. In case this is required, please use the native FLUCUP interface.

To manage a property file per command the function FCUPRO() is provided.

The interface accepts the content of such a file as string, not the filename itself! This allows to store properties in other formats such as JSON, XML or binary and use it with the UP interface.

The programming interface can be used to integrate the source (file) to target (file) data conversion capabilities provided by FLUC into a program.

The interface also provides the interactive help, documentation and syntax information to assist in understanding all commands.

Interface standards

Each function is provided as a separate load module. All parameters are call-by-reference and have no return value. All parameters must be specified. There is no support to determine a variable amount of parameter. There are 3 types of parameters:

INTEGER:   pointer to a 32 bit number in two's complement   (Cobol: PIC S9(9) COMP  or  PL/1: BIN FIXED(31,0))
STRING[x]: pointer to a byte (8 bit) array of length x      (Cobol: PIC X(x)        or  PL/1: CHAR(x))
STRING:    pointer to a variable length byte (8 bit) array  (Cobol: PIC X(n)        or  PL/1: CHAR(n))

The type INTEGER has local endianness. On mainframes, this is usually big endian. This means that the most significant byte is stored first (i.e. at the lowest memory address) and the least significant byte is stored last. On x86 platforms, the byte order is little endian. This means that the byte order is reversed.

Input strings may be 0-terminated in which case the corresponding length pointer may be NULL. All output strings are 0-terminated.

For variable length byte arrays, the length will be determined based on an additional INTEGER parameter. On input, this parameter must contain the length of the string. On output, this parameter must be loaded with the available size for the byte array and will be set to the actually used size. If the size is too small, the string will be cut and the length will be set to the respective value. This case will be marked with the special condition code 10.

For output files you can define ":STDERR" or ":STDOUT" to assign the corresponding streams.

Environment variables

For all default character conversions, it is useful to set the environment variable LANG. Other used environment variables of FLAM can be found in the FLCL manual. With version 5.1.19 a new function (FCUENV()) to load the FLAM environment was introduced. This function can be used in front of the first API call to establish the same environment used by FLAM utilities, subsystems and so on. This give the application developer the possibility to adjust the environment before the first real call is done. Till 5.1.18 each function has read the system variables on z/OS. This is now part of the FCUENV() function to give complete control about the environment to the user of the API.

Condition codes

The return codes of the subprogram are also called condition codes and returned at subprogram termination.

0 - command line, command syntax, mapping, execution and finish of the command was successful
1 - command line, command syntax, mapping, execution and finish of the command was successful but a warning can be found in the log
2 - command line, command syntax, mapping, execution was successful but cleanup of the command failed (may not happened)
4 - command line, command syntax and mapping was successful but execution of the command returns with a warning
8 - command line, command syntax and mapping was successful but execution of the command returns with an error
10 - Provided buffer for about, version or license string is too small
12 - command line and command syntax was OK but mapping failed
16 - command line was OK but command syntax was wrong
20 - command line was wrong (user error)
24 - initialization of the parameter structure of command failed (may not happened)
28 - configuration is wrong (user error)
32 - table error (something within the predefined tables is wrong)
36 - system error (e.g. load of environment or open of file failed)
40 - access control or license error
44 - interface error (e.g. parameter pointer equals NULL)
48 - memory allocation failed (e.g. dynamic string handling)
64 - fatal error (basic things are damaged)
>64 - for few special conditions codes (see FLCLBOOK)

The return code parameter can be a null pointer, then no return value is set. Special condition codes can be found in FLCL manual (FLCLBOOK).

Reason codes

The reason code (internal FLAM return code) can be determined together with a corresponding message using the function FCURSN. All FLAM reason codes are listed in FLCL manual (FLCLBOOK).

Help and Syntax

For the help, syntax and documentation functions, the command must be specified as a constant number called 'what':

1 - to get information about the INFO command string
2 - to get information about the CONV command string
3 - to get information about the XCNV command string
4 - to get information about the ICNV command string
5 - to get information about the FLAM command string
6 - to get information about the XCHK command string
7 - to get information about the HASH command string
8 - to get information about the UTIL command string
9 - to get information about the DIFF command string
10 - to get information about the KEY command string
11 - to get information about the GREP command string

The help, syntax and documentation can be used to determine the complete context sensitive help, which is identical to the content of the FLCL user manual section for the respective command.

Compile and Link

On mainframes (z/OS, BS2000, ...):

The interface is provided as DLL and each function of the DLL is also available as separate load module.

For dynamic linking of the load module (fetch) the hlq.FLAM.LOAD library must be part of the STEPLIB concatenation.

If you link one of the load modules statically to your application (each load module contains all required entries of the interface), you must include the DLL import files below to resolve the missing external references:

    hlq.FLAM.IMPORT(FLUCUP)
    hlq.FLAM.IMPORT(FL5CORE)

To link dynamically against the DLL you must include the import DLL file form the IMPORT library below:

    hlq.FLAM.IMPORT(FLUCUPLB)

We recommend to use application-specific runtime option defaults with the CEEUOPT assembler language source program to establish application default options. You can find the recommended runtime options as member CEEUOPTx (x=3 for 31 bit and x=6 for 64 bit applications) in the hlq.FLAM.SRCLIB partitioned dataset.

On other platforms (Unix, Windows, ...):

The interface is only available as dynamic link library (DLL) or shared object (SO). You can link it dynamically, statically or load the library at runtime (dlopen(), LoadLibrary()) with the common DLL/SO mechanism of your operating system.

Sample programs

Sample programs in C with name SCFCUCNV/GZP can be found as part of the installation package for mainframe systems in the library SRCLIBC(SCFCUxxx), with the corresponding compile and link step in JOBLIB(SBUILD). For other platforms (Windows, UNIX) the sample program source of SCFCUCNV/GZP is located in the 'sample' directory and the compile and link procedures can be found in the Makefile of the same directory.

Additional COBOL samples with name SOFCUCNV/KME can be found in SRCLIB(SOFCUxxx). The corresponding PL1 sample is named SPFCUCNV. The corresponding compile and link procedures is also located as separate step in JOBLIB(SBUILD).