This interface provides all FLCL commands (CONV, XCNV, ...) as simple to use programming interface. It is based on the Frankenstein Limes Universal Converter (FLUC).

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

Additionally, it provides interactive help, documentation, syntax and other information to support the use of the commands.

This interface is also provided as load module interface for COBOL, PL1 and other languages. The corresponding load module interface is called FLUCUPLB.

Interface standards

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 return/condition code as the FLCL. If the command string starts with an = sign, then a parameter filename must follow. The file is expected to contain the actual command string:

r=flucconv("=para.txt",NULL,":STDERR",NULL);

corresponds to:

FLCL CONV=para.txt

As second parameter you can provide a property file (NULL means no properties). The third parameter controls the print outs. If you define for a command, then no printouts are done. Normally ":STDERR" is used for printouts, but you can also define ":STDOUT" or a file name. The last parameter is optional and activates the trace output.

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

Properties

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. You can provide the contents of a property file from an arbitrary source via the property string. To generate a property file you can use:

FLCL GENPROP CONV=filename
(works for any command by replacing CONV with the right command)

You can also provide the filename of a property file by passing an = sign followed by the filename. Properties are then read from that file:

r=flucconv("=para.txt","=prop.txt",NULL,NULL);

To use FLCL property files, the program name must still be the default "flcl". If you write a program which is not compatible to FLCL, please set another program name (see next section). To manage the contents of a property file, the function flucpro() is provided.

Program and owner names

The program and owner name can be managed by the corresponding functions. The default program name is "flcl". The default owner name is "limes". The default values are used, if a NULL pointer or an empty string is passed. The owner id and program name are limited to 64 bytes, including the null termination. Longer names are ignored.

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 (flucenv()) 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 flucenv() function to give complete control about the environment to the user of the API.

Condition codes

The return codes of the subprogram are called condition codes and are returned on 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
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 parameter structure of the 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)

Special condition codes can be found in the FLCL manual (FLCLBOOK).

Reason codes

The reason code (internal FLAM return code) can be determined by calling the function flucrsn(). A corresponding text message is returned by the function flucmsg(). All FLAM reason codes are listed in FLCL manual (FLCLBOOK).

Sample programs

Sample programs in C with name SCFCUCNV/GZP/LST/REM 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/LST/REM is located in the sample directory. The compile and link procedures can be found in the Makefile of the same directory.