FLAM provides a set of interfaces that allow the use of the product within different environments and for different applications.
The simplest application is the execution of FLAM via the EXEC command. This allows to compress or decompress complete files.
In addition, FLAM provides a set of subprogram interfaces for integration with other programs and products. This also allows to develop tailored applications where FLAM is embedded in dedicated control programs.
User exits provide the pre- and postprocessing of the original data as well as of the compressed data without the additional step via intermediate files. All interfaces are designed in regard to higher level programming languages like COBOL. Only in cases where the usage of address pointers is a conditio sine qua non, assembler (or equivalent, e.g. C) interfaces must be used.
FLAM can be embedded in user-defined applications or vice versa by means of calls at different levels. The available interfaces are listed in the table below:
Interface |
Call level |
Purpose |
|---|---|---|
| FLAM utility via EXEC command | System |
Compress/decompress entire files interactively or in procedures |
| flamup subprogram | Application programs |
Compress/decompress entire files in user-defined applications |
| flamrec record interface | Application programs |
Transfer and recall individual records in user-defined applications |
| User-defined input/output | FLAM |
Replace FLAM input/output routines |
| User exits and File access exits | FLAM |
User-defined file and record pre-processing and post-processing for compressed and non-compressed data Key management |
These interfaces have a hierarchical order, which defines which interface can be used or invoked from where. The interfaces are subdivided into two categories: active and passive.
Active interface calls are initiated either by the user or by his application program; they activate the FLAM routines which support them. These routines include the command and the subprogram and record interfaces. FLAM uses passive interfaces to activate user routines which are required to perform a particular range of functions, but whose calls are not synchronized with the logic of the application program. This category includes the user-defined input/output and the user exits.
The next few sections contain a brief description of the ways in which the different interfaces can be used, without covering every single detail. Each of the following chapters contains a detailed description of one of the interfaces and can be used as a reference document. All the program interfaces, i.e. all interfaces other than the command, are represented in C notation in the reference chapters. However, these interfaces do not support C programs only. Rather, they can be used with any programming language, since all arguments are also referenced by addresses instead of the typical C referencing by values. Addtional beside the C calling interface and the load module interface (COBOL, PLI, ASSEMBLER) Java and other object oriented class library interfaces are available.
Even though, in a strict C context, a name without an "*" operator still identifies the argument address with this form of transfer, all references to such arguments in the descriptions below in fact relate to the argument values.
FLAM as a utility can be started on job control level via a job control command. Parameters define the mode of operation. Depending on the operating system, parameters may be supplied as a part of the command or may be entered via the screen. In addition can be parameters read from a parameter file. This file can be assigned to the process using job control commands or command parameters.
The FLAM command can be used to compress or decompress individual files or groups of files either interactively or by means of procedures. The compress or decompress parameter specifies which operation is to be performed. All the information necessary to execute the command can be specified in the form of inputs made directly in the command line, in a parameter file or as property values.
The FLAM command permits a separate FLAMFILE to be created from each original file. It is also possible to compress a group of original files into one FLAMFILE.
The attributes of the decompressed file, such as its organization and record format, may otherwise differ from those of the original file.
FLAM can thus also be used for file conversions.
The FLAM command and all its parameter is described in detail in this manual below.
The interface to the FLAMUP subprogram permits roughly the same operations as with the FLAM Utility to be initiated in an application program.
This interface makes the same range of functions available to the application programmer as to the user, with the exception of the built-in functions. FLAM parameters are used to specify these settings, similar to the procedure for the parameter file. These parameters are specified consecutively in an character string, which is transferred to the subprogram in the form of an argument. Once again, it is possible to refer to a parameter file using the parameter parfile=parameter file. If any information is omitted, the same default settings and properties are used as for the FLAM Utility command.
When flamup has been executed in its entirety, the invoking program receives a return code indicating either the success of the call or the cause of the error.
The FLAMUP load module interface and the flamupc interface is described in detail in the FLMUP interface spezification.
See also: FLMUP
The FLAMREC record interface permits file processing and compression to be integrated in an application program. Decompressed records can be read sequentially from a FLAMFILE. A new FLAMFILE is created when the compressed data is output. A FLAMFILE can thus be opened either for read accesses only (decompression) or for write accesses only (compression).
FLAM's record interface consists of a class of functions, which allow the application program to access and process compressed data in the same way as is possible with ordinary input/output instructions in the case of non-compressed data. The use of these functions is governed by rules similar to those which apply to the standard input/output. After the file has been opened, records can be read or written; the file is closed again when all processing has been completed.
The compression or decompression that takes place during processing is completely transparent to the programmer, so that compared to programs using conventional input/output operations, there are almost no differences in the program logic.
By using the record interface, compressing (or decom-pressing) the processed data no longer requires an extra step after (or before) running the application. In addition, it is no longer necessary to provide sufficient temporary storage space for both the compressed and the uncompressed copy of a file.
The FLAMREC load module interface is described in detail in the FLMREC interface spezification.
See also: FLAMREC
FLAM supports all inputs and outputs to and from disk files using standard input/output instructions. However, it also allows the user to replace these standard input/output routines with routines of his own. This may be a good idea, for example, if there is a possibility of an input/output device other than a hard disk being used or if the file contains a record format which is not supported.
It is not possible to describe every single aspect of every function of the user-defined input/output in detail, since these vary according to the device and to the nature of the data. Data which is received via a modem line, for example, requires different actions from data supplied by measuring instruments. FLAM considers the origin of the data to be "file", even though in a particular instance other objects may be involved.
The functions of the user-defined input/output are as follows:
Function |
Purpose |
Corresponding I-O calls |
|---|---|---|
usrcls |
Terminating processing of file |
fclose |
usrget |
Reading one record |
fgets |
usropn |
Opening file |
fopen |
usrpos |
Positioning to record |
fseek |
usrput |
Writing one record |
fputs |
FLAM specifies a range of functions based on the file processing requirements for this interface, in accordance with the above point of view. It is up to the user of the interface to optimize the design of the functions, to ensure that the desired results are achieved with them.
In order to be able to use a user-defined input/output, the routines concerned must be linked to the application program. This option is therefore only supported by the program interfaces, i.e. by the subprogram and record interfaces.
The support by the record interface of course only applies to accesses to the FLAMFILE, since these are the only types of access which take place via it.
A user-defined input/output is initiated by invoking flmopd with device=7. This input/output can be activated at the subprogram interface for all the files which are concerned by the compression or decompression procedure, by means of the FLAM parameters user_io, inuser_io and outuser_io.
Whereas, with the functions of the record interface, the programmer is obliged to observe a series of rules regarding the order and consistency of the calls, the correct interaction of the functions of the user-defined input/output is the responsibility of FLAM, which also takes the initiative for the calls.
The programmer of the user-defined input/output routines is merely required to make sure that the actions and behavior of the individual functions are correct. The description in this chapter is therefore restricted to these aspects.
usropn is invoked first of all once, and once only, for each assigned file. The workio argument causes a work area of 1024 bytes to be made available as file-specific memory. This area is adopted automatically for all subsequent calls until the usrcls.
The openmode argument specifies the desired access type (input, output). The record_format, record_size, etc. arguments specify the file and record attributes, which can be adapted to each particular file if necessary.
The successful termination of the function and any special states or errors can be reported by means of predefined and freely assignable return codes. Each return code is evaluated by FLAM, and passed on to the invoking programs if an error is established.
A record is transferred for writing with usrput. If the record cannot be written with the specified size, the return code must include the information that it has been either shortened or padded with the characters specified by padchar in the usropn.
FLAM requests the next record with usrget. The maximum number of characters which can be transferred is specified in the buffer_length parameter. If the record needs to be shortened as a result, this must be indicated by the return code.
The return code must also indicate when the end of the file is reached. The record size must be returned for each record which is read (even if the record format is fixed).
usrcls causes the file to be closed. The work area for this file is released again by FLAM after control has been handed back.
User exits allow pre- and post processing of records before compression and after decompression under FLAM as utility as well as pre- and post processing of compressed records under both FLAM as utility and FLAM record level interface. E.g., this user exits can be used for encryption purposes or for selective processing of original data.
A user exit is a user-provided program that is invoked by FLAM at specific events during the processing via the defined interface. These user-provided program has to be linked statically.
FLAM supports two catagories of user exits: file access exits and an exit for automatic key management.
These exits permit the user to postprocess the records output by FLAM (both those contained in the FLAMFILE and those in the decompressed file) before they are finally saved, i.e. they can be modified, deleted or given additional records. The records which are read by FLAM can be prepared for processing by FLAM in the same way.
The term "access" refers in this context either to an input/output instruction or to a corresponding call of the user-defined input/output, and not to a call of a record interface function. Thus - at least as far as the FLAMFILE is concerned - the user exits are not synchronized with the application program, since the latter is not able to establish, for example, whether or not a flmget call actually does initiate one or more read operations.
These user exits can be activated via the subprogram interface or the record interface, the latter being able to activate the user exits for FLAMFILE accesses only. The programs invoked through these interfaces must be staticly linked to the application.
A user exit is invoked each time the file is opened, read, written or closed. The functioncode argument indicates to the user exit the access type, to permit it to respond in the appropriate manner to each particular situation.
FLAM supports the following user exits for file accesses:
User exit |
Invoked for accesses to |
|---|---|
EXK10 |
Original file (compress) |
EXK20 |
FLAMFILE (compress) |
EXD10 |
Decompressed file (decompress) |
EXD20 |
FLAMFILE (decompress) |
User exits exk10 and exk20 can be used during the compression procedure for accesses to the original file or to the FLAMFILE, whereas exd10 and exd20 can be used during the decompression procedure to access the decompressed file or the FLAMFILE. If records contained in the FLAMFILE were modified by user exit exk20 when they were compressed, they can only be decompressed if the modifications are undone again by the complementary user exit exd20, i.e. if every FLAM record is reset by exd20 to the state in which it was originally transferred by FLAM at user exit exk20.
Automatic key management facilitates handling encrypted files by relieving the user from duties like generating, exchanging and storing passwords, in whatever way.
When invoking the key management exit routine for encryption, FLAM also passes an optionally user-supplied character string via the interface. The exit returns a key value which is used by FLAM for encryption. In addition, the exit may also return a byte string that FLAM attaches to the encrypted FLAMFILE. When decrypting, FLAM passes this string back to the exit for the retrieval of corresponding decryption key.
This exit can be activated by the flam command or the subprogram interface. It is also available via the record interface. Programs invoked through these interfaces must be created as shareable objects and are linked dynamically.
IMPORTANT: Throughout this manual the terms "password" and "(encryption) key" are used synonymously.
An exapmle for a professinal solution which use the FLAM Key Management Extension (FKME) together with Hardware/High Security Modules (HSM) for PCI DSS conform handling of card holder data in paymant systems can be found on the link below (in german only): FKME
The interface specification for FLAM4 FKME can be found at: FKME