FLM4UP differs from FLAM utility in that respect, that it can be called as a subprogram out of an application. All accesses to data are performed via FLM4UP. All parameters can be passed to FLM4UP using the CALL interface or methods as provided by FLAM4 (interactive parameter definition or parameter files) can be used. Using FLM4UP within a driver program allows for example to select a certain set of files and to compress/decompress all the selected files in one step. A typical example is, to select only files that were modified after a certain date (archiving).

The FLM4UP subprogram interface enables the use of FLAM4 command syntax in custom applications. It is provided as DLL with entry name 'flamup' for distributed platforms and as separate load module with entry name 'FLM4UP' on z/OS (the old FLAMUP is still available on z/OS). Additional the DLL contains the entry 'flamupc' for a simply use in C applications.

For implementation the FLUCFLAM routine of the FLUCUP is used in the background but the interface is identical with the old FLAMUP. The property, output and trace file handling is automated and describe below.

It supports all options of the FLAM4 executable (see FLM4BOOK). FLAM4 parameters are used to specify these options. These parameters are specified successively in a single string, which must be passed as argument. This parameter string can also be read from a parameter file by using the parameter parfile=somefile or by simply using an equal sign followed by the parameter filename (_=somefile_).

Interface standards

There are 4 types of parameters:

POINTER:   pointer to an address (usually 32 (PIC S9(9) COMP) or 64 bit)
INTEGER:   pointer to a 32 bit number in two's complement (PIC S9(9) COMP)
STRING[x]: pointer to a byte (8 bit) array of length x (PIC X(x))
STRING:    pointer to a variable length byte (8 bit) array (PIC X(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.

Property/default-value file

The flm4up subprogram uses a property file in place of the old FLAM4 default value file. The property file is a simple text file with lines in a "key=value" format. A property file with the default values set is generated upon first execution and is read from the location below in subsequent calls. It is also possible to generate such a file with the FLAM4 utility flam4 genprop flam=HOME/.flam4.properties.

Upon execution, it is attempted to read the property file containing FLAM4 default values from the following locations in this order:

Environment variable: FLAM4_PROPERTY_FILE
Working directory: .flam4.properties (Host: SYSUID.FLAM4.PROPS)
Home directory: HOME/.flam4.properties (Host: SYSUID.FLAM4.PROPS)

On first execution, the property file containing the FLAM4 default values is generated at the first possible of the following locations:

Environment variable: FLAM4_PROPERTY_FILE
Home directory: HOME/.flam4.properties (Host: SYSUID.FLAM4.PROPS)
Working directory: .flam4.properties (Host: SYSUID.FLAM4.PROPS)

So, to use a property file different from the one stored in the HOME directory (where available), you can override it by putting a property file in the working directory.

If you wish to use the same property file for flm4up and the FLAM4 executable, we recommend to set the executable's property file as follows:

FLAM4 SETPROP FLAM=HOME/.flam4.properties

The property file name differs from the default property file names of the FLAM4 utility to ensure that property file changes for the executable don't affect the applications using this interface, except this behavior is explicitly enabled using the above command.

For any unspecified option, the program uses the same default settings as the flam4 executable. This includes the load of system and standard environment variables ('DD:STDENV' and 'SYSUID.STDENV' or '.STDENV').

Return codes

After the subprogram finishes execution, the invoking program receives a return code indicating success or failure.

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

The these values are identical with the FLCL completion codes and differs a little bit from the return codes known form the old FLAMUP.

Output and trace files

To activate a output or trace file the environment variables below can be used:

 FLM4UP_OUTPUT_FILE
 FLM4UP_TRACE_FILE

Samples

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