### Components and Details

The following sections describe several components of FLAM4.

#### FLAM Utility

FLAM is a utility that is able to compress and encrypt whole files or to expand compressed and to decrypt files.

By using the parameters COMPRESS or UNCOMPRESS/DECOMPRESS, you select the operation mode:

Compression of an uncompressed file or expansion of a compressed file.

#### File compression using FLAM

As FLAM compresses a file it will write the result into a sequential or index sequential file, the FLAMFILE. This file may have a header that will store information about the original file.

FLAM is able to process all PS, PO and VSAM files.

To adapt the compression process to the requirements of the user, it is possible to specify parameters during the program call interactively. It is also possible to define the parameters using a parameter file or while generating the system.

FLAM creates a job protocol for each execution (on screen or into a log file). During compression FLAM processes a set of 1-4095 (logical) records within one block (Matrix). FLAM can process input and output from both disc and magnetic tape or cartridge. This is also true for the compressed file, the FLAMFILE.

FLAM always compresses a set of records in one step. The size of the intermediate buffer can be specified via the parameter `MAXBUFFER`. FLAM will read only as many input records in one step as can be stored within the intermediate buffer.

For compatibility reasons to all FLAM versions the size of the intermediate buffer is restricted by 32 kB. However, if the target computer (i.e., the computer on which the compressed file will be decompressed) is known and the FLAM version installed on this computer allows for it, a bigger buffer size for optimal compression can be defined.

It is also possible to restrict the number of records within one set using the `MAXRECORDS` parameter. If you define `MAXRECORDS=1`, FLAM will use a serial context free compression method that is only useful with long records.

The typical compression ratios are usually achieved with 16-32 records within one set. With a bigger set a slightly better compression ratio can be achieved (which also leads to less CPU utilization!), but the intermediate buffer has to be bigger.

The better the compression ratio is, the less CPU time is needed!

The compression method is always the same - based on the Frankenstein-Limes-Access-Method. Only the treatment of the matrix columns and the representation of the compressed files differs from case to case. This is controlled with the MODE parameter.

With MODE=CX8 FLAM will only compress repeating characters (horizontally and vertically). With MODE=VR8 the remaining data is compressed in addition using the FL-B(4) code. This process first translates the characters into a special 8-bit code and then homogenizes them using specially designed logical operations. The results are bit strings that can be compressed efficiently. One reason for this is that the data resulting from the Frankenstein-Limes-Access-Method can be grouped into partial equalcharacter classes.

In both cases, the compressed file, the FLAMFILE, is a sequence of 8-bit combinations that are written into sequential or index sequential files. Record size, record format, block size can be defined by the user. Each record of a file is in addition protected with a checksum. Code conversions within the FLAMFILE are not allowed. During transmission the file has to be treated as a binary file.

For files that contain only printable characters and shall be transmitted using a 7-bit-line, FLAM offers MODE=CX7. This mode creates a compressed file which will "behave" during transmission in the same way as the uncompressed file. FLAM does not check, if the original file is suitable for transmission, but will create a compressed file using a very restricted character set that is neutral to the different code conversion utilities on the marketplace.

Using this mode one can create compressed files that can be converted from EBCDIC to ASCII and vice versa (e.g., during a file transfer).

However, it is necessary that the code conversion is reversible without any changes. Otherwise FLAM will signal a syntax error in the compressed file due to differences in the byte numbers and will stop decompression. Such cases are possible, if the original file contains printer control characters or tabulator characters, which are not converted 1:1.

Apart from this, code conversion can be performed integrated with the compression step. FLAM offers the possibility of code conversion (before compression, or after decompression). Code conversion is controlled via standard code tables or user defined code tables. For special cases where a 1:1 code conversion is not possible for all characters, user exits are provided.

#### Decompression of files using FLAM

FLAM reads a compressed file (FLAMFILE), decompresses the content and writes the result into a target file. FLAM automatically configures itself according to the parameters (e.g., buffer size or record set size) used during compression. The general layout of the compressed file is described in a separate chapter.

FLAM version 2.7 can decompress all FLAMFILES created with FLAM V1.0 - 2.6 (upward compatibility). FLAM V2.0/ V2.1 can decompress sequential FLAMFILES created with FLAM V2.5 - V2.7 (downward compatibility).

To adapt the decompression process to the requirements of the user, it is possible to specify parameters during the program call interactively. It is also possible to define the parameters using a parameter file or while generating the system. FLAM creates a job protocol for each execution (on screen or into a log file). During decompression the characteristic parameters of the original files are restored depending on the information in the file header.

By specifying certain parameters it is possible to generate a target file differing from the original file. All conversions are possible provided that the target system caters for the appropriate access method. That the FLAMFILE eventually was created in a different environment (e.g., different operating system) lacks influence on the operation of FLAM. Data is decompressed into equivalent file formats or in user-defined file formats.

By specifying code conversion tables it is possible to change code systems after compression. To be even more flexible, FLAM provides user exits that allow the user to apply user defined post processing.

#### FLAM Utility synopsis

FLAM is able to compress complete files and to reconstruct complete files from compressed data. For original files all file and record formats of type PS, PO or VSAM for disc or tape are supported. The user interface for file IO (`DEVICE=USER`) allows to support additional access methods.

The user exits allow to pre- and post process original data as well as compressed data. The user exits are implemented as subprograms that are loaded dynamically during execution time from a module library (STEPLIB).

Using predefined or dynamically loaded conversion tables, character conversion can be applied to the original data.

It is possible to change file and record formats during decompression. Conversion from variable to fixed format or from sequential to index sequential organization is possible. The compressed data (FLAMFILE) can be stored in sequential or index sequential format in any record or file format. The record and file format of the compressed data is independent from the record and file format of the original data. An index sequential FLAMFILE provides efficient random access to original data by using the record level interface. At the other hand, sequential organization of the FLAMFILE is better suited for file transfer between computers with different operating systems.

FLAM compressed data is always heterogeneously compatible. This means that compressed data, which was generated under a certain operating system, can be decompressed on all operating systems supported by FLAM. Depending on the available record and file formats on the target systems, record and file conversions may be necessary.

FLAM can be executed online as well as in batch. It can be adapted in a flexible way to the requirements of the users. Several parameters are supplied for this purpose.

These parameters may be entered or may be stored via the `PARM` interface. An additional parameter file is also possible. Default values for the parameters may be created during installation (see: Generation of Default Values). File attributes can be also defined via the DD command.

During processing, parameters are evaluated in the following sequence:

- First the installation parameters are used.
- During decompression this values are substituted by the values from the file header of the FLAMFILE, if available.
- Then the values from the parameter file are used. The input PARM in the EXEC statement overwrites these values.
- File attributes defined in the `DD` or `ALLOCATE` command overwrite again.

According to this hierarchy, a very flexible mode of operation is possible. Please be aware that the sequence is not always chronological:

For example, it is possible to select a parameter file via `PARM` input. This parameter file is read in after the input despite of the fact, that the `PARM` inputs will overwrite the specifications of the parameter file.

#### FLAM Utility Parameters

Independently from the input medium, parameters are evaluated always using the same syntax. Only upper case letters are allowed. Parameters may be passed in one or more lines or records. In each line the parameter interpretation ends with the first blank position. After the blank any type of comment may follow. Single parameters must not be separated by end of line.

Evaluation of the parameters is ended at the keyword `END` or by an empty input line (length = 0) or by `EOF` for the input medium.

There are parameters with or without keywords. Keywords and values can be abbreviated. Within brackets [] alternative keywords are presented as used in other operating systems (z/OS, DOS/VSE, BS2000). Keywords from previous versions are presented within angle brackets. This keywords should not be used any longer.

Because of compatibility reasons all parameters are presented although not all parameters are evaluated under z/OS.

Keyword parameters can be specified in two different modes as usual under z/OS:

    parameter0,parameter1=value1,parameter2=value2,...

or:

    parameter0,parameter1(value1),parameter2(value2),...

A string value (file names, module names, password, ...) may be passed as C'.....' (characters) or X'....' (hexadecimal). All string parameters are assigned with blanks if "(NONE)" or no value is specified:

    parameter=(NONE), or parameter(NONE),...

or:

    parameter=,... or parameter(),...

The sequence of parameters is arbitrary if not otherwise specified. Only parameters that differ from the default values must be specified.

In the following we describe all parameters in alphabetic order: Parameter may be abbreviated as long as they stayunique. Otherwise the first matching entry of the following summary is used.

For more about every parameter see section FLAM COMMAND.

#### FLAM Utility Variables

It is also possible to control FLAM via environment or system variables. An environment variable overwrites a system variable.

Environment variables | are stored in
    //CEEOPTS DD DSN=filename,...
or set by an LE-Routine (like a C-program). They are used only in the actual step.
`FL_ZEDC_SUPPORT` | controls how to use a zEDC-Hardware. Possible values: OFF do not use the hardware, even if one is found. `MODE=ADC` is in effect. ON use it always Default: no value. Use it, if found. Valid for: compression decompression. When a hardware is not found and the algorithm is required for decompression, a software routine is used.
System variables | are stored in `SYS1.PARMLIB(IEASYMxx)`. When for the same function an environment variable is found, the environment variable is used.
`&FLZEDC` | Controls how to use a zEDC-Hardware system wide. This is same as the environment variable `FL_ZEDC_SUPPORT`. Possible values: OFF don't use the hardware, even if one is found. `MODE=ADC` is in effect. ON use it always Default: no value. Use it, if found. Valid for: compression decompression. When a hardware is not found and the algorithm is required for decompression, a software routine is used.
`&FLOGQL1` | First qualifier in logstream name of LOGR. Possible values: 1-8 characters as with IXCMIAPU defined. Activates FLAM logging.
`&FLOGQL2` | Second qualifier in logstream name of LOGR. Possible values: 1-8 characters as with IXCMIAPU defined
`&FLOGQL3` | Third qualifier in logstream name of LOGR. Possible values: 1-8 characters as with IXCMIAPU defined Valid for: compression* decompression. Example: IXCMIAU defines the logstream name FLAM.USAGE
    (DEFINE LOGSTREAM NAME(FLAM.USAGE) ...).
Then in Parmlib-Member must be stored:
    SYMDEF(&FLOGQL1='FLAM')
    SYMDEF(&FLOGQL2='USAGE')
Without any system variable FLAM cannot log any data. Look for some examples to define a logstream in FLAM.JOBLIB.

#### JCL for FLAM

This description is valid for batch processing. Appropriate commands must be used for dialogue processing (TSO).

FLAM is started via the EXEC command:

    //stepname EXEC PGM=FLAM,PARM= ...

Parameter specification must be made according to the JCL conventions (max. 100 characters, inclusion in quotes in case of special characters, like '=', '(', etc. ).

FLAM parameters specified via `PARM=` will overwrite FLAM parameters stored in the FLAM parameter file.

If the FLAM modules are not stored within a system library a FLAM load library must be specified:

    //STEPLIB DD DSN=user.FLAM.LOAD,DISP=SHR

The input and output files can be assigned to FLAM via DD cards. The DD names used are predefined default names. Other DD names can be chosen via parameters.

The following file types are supported by FLAM:

- Physical sequential PS (also members of a PO library)
- PDS / PDSE libraries (but no PDSE-LOADs)
- VSAM ESDS / KSDS / RRDS / LDS

The following record formats are supported:

- V / VB / VS / VBS / F / FB / FS / FBS / U

Print files (A or M) are also supported.

The specification of a parameter file is possible but not mandatory (usually the PARM= instruction is sufficient):

    //FLAMPAR DD DSN=parameter_file,DISP=OLD

It is also possible to define the parameter file directly embedded into the JCL:

    //FLAMPAR DD *
      parameter0,parameter1
      parameter2
    /*

For compression, an input file must be specified:

    //FLAMIN DD DSN=uncompressed_input_file,
    //          DISP=SHR

This file must already exist and must be catalogued. It is allowed to be "logically empty", which means that it does not contain a data record.

For the creation of a compressed file (FLAMFILE) it is sufficient to write:

    //FLAMFILE DD DSN=compressed_file,
    //            DISP=(NEW,CATLG),
    //            UNIT=....,
    //            SPACE=....

With this card a sequential data set with a fixed record length of 512 and a system determined block length will be created. However, this may depend on the default parameters specified or on additional parameters supplied with the job.

    //FLAMFILE DD DSN=compressed_file,
    //            DISP=(NEW,CATLG),
    //            UNIT=...,SPACE=...,
    //            DCB=(LRECL=1024,BLKSIZE=26624)

Using DCB attributes this assignment overwrites the `MAXSIZE` or `BLKSIZE` parameters for the FLAMFILE. The file is created according to the specifications in the DD statement.

One example for using flexible configurations with the FLAMFILE comes from the area JES / NJE:

    //FLAMFILE DD SYSOUT=F,DEST=(node,userid),
    //            DCB=(LRECL=80,BLKSIZE=3120),...

If the FLAMFILE is already catalogued (`DISP=OLD`) FLAM will use the configuration details from the catalogue entry (even, if it is a VSAM file).

For decompression an output file must be assigned.

    //FLAMOUT DD DSN=decompressed_file,
    //           DISP=(NEW,CATLG),
    //           UNIT=...,SPACE=...

With this specification a decompressed file will be created that has identical characteristics regarding file format, record and block length with the original file.

If a PO library has been compressed and a new PO file is to be defined for decompression by JCL, the selection rule `FLAMOUT=PO-file-name(*)` must always be specified. Otherwise member names are not known.

    //..      EXEC PGM=FLAM,PARM='D,FLAMOUT=PO-file-name(*)'
    //FLAMOUT DD DSN=po_file,DISP=OLD

If the original file came from a foreign system (VM, VSE, UNIX, Windows,

###### ), FLAM will choose a format closest to the original file.

If the FLAMFILE does not contain information about the original file, e.g. caused by parameter `HEADER=NO` during compression, the output file is created as variable blocked (VB) and with a maximum record length of 32756 bytes and a block length of 32760 bytes.

Each DCB specification within a DD statement will overwrite the values automatically chosen by FLAM or specified as FLAM parameter.

If the output file is already catalogued the catalogue entry will specify the file characteristics:

    //FLAMOUT DD DSN=output_file,DISP=OLD

All messages are written into a message file by default:

    //FLPRINT DD DSN=list_file,DISP= ...

or

    //FLPRINT DD SYSOUT=*

If no file is specified despite the fact that the parameter `MSGDISP=MSGFILE` is set, a message is written to the console via `WTO, ROUTCDE=11` and the program is terminated with a condition code.

If messages shall be suppressed, `SHOW=NONE` must be specified in the `PARM=` entry within the EXEC card.

Each file can be assigned as:

    //ddname DD DUMMY

This will suppress file output or inhibit file input. Since this does not affect the general processing of FLAM, it can be used conveniently for testing purposes:

- evaluation of compression ratio
- general testing of control flow
- using own read and write routines from user exits

(we recommend the USERIO interface instead, but in principle the possibility mentioned above can be used, too).

The DUMMY assignments are not suitable for benchmarks. Because all physical disc or tape I/O is suppressed, this leads to a much shorter elapsed time, especially in case of later tape assignments or VSAM I/Os.

The record length in the DD statement must always include the length of the record length field in case of variable length records.

Opposite to that, FLAM requires the actual length of the data (without length field) in it's own parameters and displays also only the actual length of the data in the protocol. To make this difference clear the parameter name `LRECL` has been changed to `MAXSIZE` for the FLAMFILE parameter printout. `IRECSIZE` and `ORECSIZE` are equivalent notations for the input file and the output file.

The FLAM user interface for TSO users removes the task of writing JCL tatements from the user (including creation of VSAM files). All specifications can be made interactively. Also batch job streams can be generated with this facility.

#### Dynamic file allocation

The specified files are allocated automatically by FLAM (dynamic allocation, SVC 99) by means of parameter input (`FLAMIN=filename`, `FLAMFILE=filename`, `FLAMOUT=filename`, ...), as long as a DD statement has not been specified.

If the files are already catalogued, FLAM will use the configuration details from the catalogue entry. For reading the file is assigned with `DISP=SHR`, for writing with `DISP=OLD`. If the file is not already catalogued, it is created (`DISP=(NEW,CATLG)`).

For decompression (`FLAMOUT=...`) data such as file organization, record length, block length, format and file size are taken from the FLAM file header, which means that the output file essentially corresponds to the original file. Parameter inputs, however, take priority over the stored data. When the parameter `FLAMOUT=<*>` is set, the file names stored in the file header are used (see section "File names in FLAMOUT").

The storage assignment contains the file size as primary specification, 1/4 of the file size being the secondary specification. In the case of PO libraries, the number of directory entries is also known. The file is thus stored in one extent on the disk.

If the file size is not known, because e.g. a FLAMFILE is assigned or the compressed data has not been generated under MVS (and therefore does not contain the file size), default values are used (TRK,(30,900),RLSE).

If the default values are inadequate, a DD statement specifying other values must be made or the file can be created before the job is run (e.g. with function 3.2 in ISPF).

All file types supported by FLAM (PS, PO, and VSAM) can also be created dynamically again. However, since important information required for creating new files is missing (such as UNIT and VOLUME), SMS must be used. The fact that this information is missing is on the one hand due to data protection reasons (data exchange via file transfer!); on the other hand, they would usually not be useable due to transferral of the compressed data to other computers. After all, compressed data from foreign operating systems (VMS, VSE, UNIX, etc.) cannot even contain these specifications.

If parameters are specified and FLAM finds a DD statement via the DD-NAME, all the specifications in this statement take priority over the parameters specified or values stored in the file header.

#### Condition Codes

For job control FLAM returns the following condition codes:

Condition code | Description
--- | ---
0 | Normal termination (no error)
4 | Not all I/O files were processed during processing of group files
8 | Less severe error occurred (e.g. parameter error)
12 | Usually a data management error
16 | Severe error during compression or decompressi on
80 | Compression ratio was less than the specified limit (see CLIMIT parameter)
88 | The file assigned was not a FLAMFILE

Only for condition code 0 and 80 compression was done properly. In all other cases no or a faulty compressed file was created. We recommend to rename this file in order to avoid using it for processing at a later time.

If a condition code greater 0 was returned an error message was already displayed by FLAM.

Condition code 16 could be caused by a FLAM system error.

The library `FLAM.SRCLIB` contains the call module FLAM. This can be customized as required, allowing other condition codes to be returned.

#### FLAM Utility File names

Specifying a filename is an alternative to assigning the file by means of a DD statement. The specification can contain a conversion rule for filenames. The name can be specified in wildcard syntax for decompression. The character `>` in front of the filename means that the flamfile contains a list of filenames to be decompressed. `DUMMY` acts like the DD-statement `//.. DD DUMMY`

#### Filename

In principle, FLAM is able to process all filenames via JCL valid in z/OS. FLAM stores the name of the compressed file into the FLAMFILE, if required. To avoid any conflicts with national character sets or naming conventions in other systems, all filenames stored in ASCII character set are translated for message and selection in the following way:

All national characters are translated to 'X', a backslash '\' to slash '/', and whitespace ' ' to underline '_'. So it is easier to enter foreign filenames that are unsupported in the z/OS environment. The filename itself remains unchanged in the FLAMFILE. Entering `DUMMY` as a filename causes FLAM to use this file as dummy like the JCL command `//ddname DD DUMMY`. I.e. reading an input file leads to EOF (end of file), writing to an output file has no effect. So, DD-statements are not necessary for DUMMY files.

#### Filename list

By prefixing the '>' character (greater than) to the filename or DD-NAME, the FLAM parameters `FLAMIN` and `IDDN` are able to specify a list of files for compression instead of one single file. It is also possible to specify a file list for decompression by means of the `FLAMFILE` or `FLAMDD` parameter. In this list, each filename must be contained in a separate record; leading or trailing space characters (X'40') are ignored. A comment can be inserted after the first space character following the filename. Empty records or records with an asterisk '*' in the first column are regarded as comment lines. All filenames usable in z/OS are legal. Wildcard syntax is allowed.

Example: If the records in the file USER.DAT.LIST contain the following filenames:

    USER.DAT.PS
    USER.VSAM.ESDS
    USER.POLIB.*
    USER.PO(MEMBER)

the specification

    //... EXEC PGM=FLAM,
    // PARM=´C,FLAMIN=>USER.DAT.LIST´

leads to all the files specified being compressed into one FLAMFILE (group file).

The file that contains the list of filenames can have any format supported by FLAM and be of any type.

For 'in-stream files', i.e. input files temporarily created by JES, it is advisable to assign the filenames by means of DD names:

    //... EXEC PGM=FLAM,PARM=´C,IDDN=>DDNAME´
    //DDNAME DD *
    USER.DAT.PS
    USER.VSAM.ESDS
    USER.POLIB.*
    USER.PO(MEMBER)
    /*

This allows the filename list to be specified directly in the job.

#### Wildcard syntax

Filenames can be specified in FLAM by means of parameters written with wildcard syntax. Correspondingly, the entry `FLAMIN=USER.*.DATA.%BC` leads to the compression of all files with the 1st qualifier USER, any 2nd qualifier, DATA as the third part of their name, and a three-digit 4th qualifier which ends with BC and begins with any character. The asterisk "*" stands for any (even an empty) character string. The percent character "%" stands for any character. These special characters are also allowed within members of one or more PO libraries:

    USER.POLIB(FL*)

specifies all members of the library USER.POLIB, that begin with FL;

    USER.*D.LIB(A%%B)

specifies all members whose 4-digit names begin with A and end with B and whose libraries have the identification USER, LIB as their final qualifier, and D as the last character of the second to the last part of their name. All input files are stored in this way in one compressed file (group file). Correspondingly, the wildcard entry in the selection rule for decompression

    FLAMOUT=USER.DAT.*LIB

leads to the decompression of only those items of compressed data whose original names conform to the syntax specified. (Comment: this procedure requires a FLAM file header (`HEADER=YES`) and the file information `FILEINFO=YES`) for compression).

Example:

    C,FLAMFILE=USER.DAT.CMP,FLAMIN=USER.*B.*LIB,...

All files with names that conforming to the FLAMIN specification are to be compressed into the file USER.DAT.CMP.

If the files

       USER.DATA.ALIB
       USER.DATAB.BLIB
       USER.DATCB.CLIB
       USER.DATCB.DLIB

are catalogued, the 1st file does not conform to the wildcard syntax and is ignored during compression.

If

    $$D,FLAMFILE=USER.DAT.CMP,FLAMOUT=USER.DATCB.*LIB$$

is now specified for decompression, only the files `USER.DATCB.CLIB` and `USER.DATCB.DLIB` will be decompressed. Correspondingly, it is also possible to select a number of FLAMFILEs for decompression:

    ..D,FLAMFILE=USER.CMP.*.VR8,...

means all FLAMFILEs with the identification USER, CMP as their 2nd qualifier, any character string as the 3rd part of their name and VR8 as their last qualifier are to be decompressed.

#### Selection rule for decompression (!! deprecated !!)

Pointed brackets '<>' explained blow are dropped in FLAM 5, because this conversion rules cause too much data transfer in case of remote processing. If pointed brackets '<>' are used, a migration for FLAM 5 is necessary.

See section Input to Output Name Mapping.

During decompression, the files can be created and cataloged by FLAM automatically. This requires the existence of a valid filename in the file header of the FLAMFILE (i.e. the parameters `HEADER` and `FILEINFO` must not be set to `NO` for compression).

In addition, a FLAMFILE can contain several files (i.e. it is a group file) and it is possible to decompress specific files from such a group FLAMFILE on a targeted basis by specifying a selection rule.

In order to distinguish it from a 'genuine' filename, a selection rule s written between angle brackets '<>' (!! deprecated !!).

    FLAMOUT=<USER.FILE.ORG>  (!! deprecated !!)

With the above rule set, the file `USER.FILE.ORG` is decompressed from the FLAMFILE. (Comment: if thepointed brackets were left out, the entire FLAMFILE would be decompressed and written into the file `USER.FILE.ORG`). This name must be contained in a file header of the FLAMFILE.

If the FLAMFILE contains other compressed files, they are ignored due to the unique selection rule set.

If several files are to be decompressed from a group file, a wildcard syntax can be specified. The simplest entry possible is a lone asterisk:

    FLAMOUT=<*>

This decompresses all of the files from the FLAMFILE and locates them on the disk under their original names.

A selection rule is implicitly regarded by FLAM as having an asterisk at the beginning and at its end, i.e.:

    $$<DAT*ABC > corresponds to <*DAT*ABC*>$$

When analyzing the file names, FLAM synchronizes itself to the character string specified.

Example:

The FLAMFILE contains the data `USER.DAT1.PS` and `USER.DAT2.PO`. The specification

    D,FLAMOUT=<DAT1>,...

decompresses only the file `USER.DAT1.PS`.

Since there is no asterisk specified in the name, decompression is termimated after the first hit.

If, in addition to the selection rule, a file is assigned by means of JCL, the JCL specification takes priority. I.e., the above specification together with the DD statement

    //FLAMOUT DD DSN=USER2.POLIB(MEMBER),DISP=...

leads to decompression of the USER.DAT1.PS file from the FLAMFILE and it is written into the PO library `USER2.POLIB` as the member `MEMBER`.

This, then, allows the changing of file names during decompression by means of JCL specifications.

#### Conversion rule (!! deprecated !!)

Angle brackets '<>' explained below are dropped in FLAM 5, because this conversion rules cause too much data transfer in case of remote processing. If pointed brackets '<>' are used, a migration for FLAM 5 is necessary.

See section Input to Output Name Mapping.

This simple method of selecting files for decompression by means of a selection rule can, however, not normally be used for compressed data that has been generated under a different operating system (heterogeneous exchange of compressed data). The file names do not normally conform to the rules of the MVS operating system and can therefore not be used without being modified.

For this purpose, it is possible to specify a conversion rule as the parameter for the output file. This character string describes how a new name is to be generated from a file name selected. At the same time, precisely those files that conform to the rule (selection rule) are selected.

A conversion rule is a selection rule that is extended by an equals sign '=' and a second character string. In order to distinguish it from a 'genuine' filename, it must be written between pointed brackets '<>'. The rule comprises a character string that may contain an asterisk '*' as a substitute character for any number of characters or a percent sign '%' as a substitute for precisely one character. An ignore character (apostrophe ') is also defined.

Each asterisk '*' or percent sign '%' in the selection rule must be assigned an asterisk or percent sign or an apostrophe in the conversion rule.

The asterisk means that the character string in the input file is to be transferred unchanged to the output file. Correspondingly, the '%' transfers precisely that character located in this position.

The apostrophe sees to it that the character string or character represented in the input file by an asterisk or percent sign respectively, is not transferred to the output file. The remaining characters from the input file are translated into the corresponding characters from the conversion rule. The length of the character string an be changed as desired.

    $$<USER.*=USER2.*>$$

With this rule, all file names beginning with `USER` are converted to the new identification `USER2`. The rest of the name is retained.

    $$<USER.DAT%B.*=USER.DEC.DAT%C.*>$$

With this rule, all files with the identification `USER` are given the prefix `DEC` before their old name. In the process, only those files are affected whose second part of their name begins with `DAT`, is followed by any character and ends with `B`. This `B` is converted to `C` in the name of the output file.

Above all, empty character strings are also allowed in the conversion rule, so that characters can be deleted. E.g.:

    $$<USER*UP*=USER.CMP*>$$

Old name: `USER.FLAMUP00`
New name: `USER.CMPFLAM00`

The UP part of the name is not mentioned in the output name and is therefore left out.

A conversion rule is implicitly supplemented by FLAM, e.g.:

    $$<ASM.=CMP.> corresponds to <*ASM.*='CMP.*>$$

This can be particularly useful when converting the filenames from other systems.

Example:

The FLAMFILE created under DEC/VMS contains the following filenames:

    DUA1:[ABC]DE0051.;7
    DUA1:[ABC]DE0052.;4
    DUA1:[ABC]DE0080.;2
    DUA1:[ABC]DE0152.;4

This corresponds to specification of the file versions of the user ABC on disk volume `DUA1`, with the version number stated after the semicolon.

In order to be able to create these files in MVS, the following conversion rule could be specified:

    $$FLAMOUT=<DE*.;*=USER.DE*>$$

This implicitly deletes the name prefix `DUA1:[ABC]`, takes over the part of the name beginning with DE and supplements it with the identification, and deletes the rest of name:

    USER.DE0051
    USER.DE0052
    USER.DE0080
    USER.DE0152

The conversion rule is also important with respect to generating members of a PO library:

    $$FLAMOUT=<USER.*.LIST=USER.POLIB(*)>$$

This rule means that the 2nd name qualifiers of the original file are used as member names of the PO library.

So far, the conversion rule has only been described for decompression from a (group) FLAMFILE.

It can, however, also be used for compression with simultaneous generation of several items of compressed data in different files. In this respect, the conversion rule relates to the FLAMFILEs whose names are generated from the file names of the input files (FLAMIN).

This is how all compressed data could be given a prefix:

    $$C,FLAMIN=USER.*.LIST,FLAMFILE=<USER.*.LIST=USER.CMP.*.LIST>$$

It is, however, also possible to store each item of compressed data as a member of a library by means of the following specification:

    $$C,FLAMIN=USER.*.LIST,FLAMFILE=<USER.*.LIST=USER.POLIB(*)>$$

The member name is, in this case, the 2nd qualifier of the input file.

Also valid here: if a library is specified for the FLAMFILE by the JCL, the name of the library as specified in the rule is ignored and only the members in the specified PO file are generated.

The reverse also applies: file names of the FLAMFILEs are used to generate file names for the decompressed files:

    $$D,FLAMFILE=USER.CMP.*,FLAMOUT=<USER.CMP.*=USER.*.LIST>$$

If a group file has been created with `HEADER=YES` but `FILEINFO=NO`, no filename has been stored for this file.

The individual files can then be accessed for decompression via the internal file name: the name is in the range from `FILE0001` (for the first file) to `FILE9999` (for the 9999th file).

    $$D,FLAMOUT=<FILE0003=USER.DAT.THREE>,..$$

is for the third file in the group file; or

    $$D,FLAMOUT=<FILE*=USER.DAT*>,..$$

is for decompressing all files according to the conversion rule.

Comment: As a "final rescue option" for automatic generation of the decompressed data with "impossible" filenames from foreign operating systems, the parameter `FILEINFO=NO` can be specified for the decompression process. With this parameter, the stored filenames are ignored and the internal names `FILE0001` to `FILE9999` are generated. These must then be converted to valid filenames by means of a conversion rule.

#### Subprogram FLAMUP

FLAMUP differs from FLAM in that respect, that it can be called as a subprogram out of an application. All accesses to data are performed via FLAMUP.

All parameters can be passed to FLAMUP using the CALL interface or methods as provided by FLAM (interactive parameter definition or parameter file) can be used.

Using FLAMUP 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).

#### I/O User Interface

This interface allows the user to integrate own access methods into FLAM.

One possibility is to pass the compressed records immediately to post-processing routines without creating a compressed file. Vice versa, during decompression the compressed records may be received from a preprocess instead of reading them from a file.

A direct application could be the integration of FLAM with a file transfer application avoiding the creation of intermediate files.

Generally this interface allows to intercept all input and output data of both FLAM and FLAMUP. This allows the user to adapt FLAM easily to specific access methods.

#### User exits

#### Original data input EXK10

This user exit interfaces the record passed to FLAM for compression.

Special processing can be defined for: Start of file, record level, end of file. Records can be passed on, modified, deleted or inserted. This exit can be used to modify records in a structure dependent way.

EXK10 is only available in FLAM and FLAMUP and corresponds with EXD10 during decompression.

#### Compressed data output EXK20

This exit interfaces the compressed data before it is written into the FLAMFILE.

Special processing can be defined for: Start of file, record level, end of file. This exit can be used to modify records in a structure-independent way.

With this exit it is possible, to modify the data with an own encryption routine, or a special code translation can be applied if a non-transparent file transmission method shall be used.It is possible to insert own records in front of the compressed records, for example archiving control records or origin information.

Another possibility is the extension of records to append specific revision information.

EXK20 is available in FLAM, FLAMUP and FLAMREC and corresponds with EXD20 during decompression.

#### Original data output EXD10

This exit interface the decompressed record immediately before it is written into the target file.

Special processing can be defined for: Start of file, record level, end of file. Records can be passed on, modified, deleted or inserted. This exit can be used to modify records in a structure dependent way.

EXD10 is only available in FLAM and FLAMUP and corresponds with EXK10 during compression.

#### Compressed data input EXD20

This user exit interfaces the compressed data immediately after it is read from the FLAMFILE.

Special processing can be defined for: Start of file, record level, end of file. This exit can be used to modify records in a structure-independent way.

With this exit it is possible, to decrypt the data with an own decryption routine or to apply the reverse code translation as used during compression.

For a proper operation of FLAM it is indispensable that all changes applied to the compressed data are reversible. User exit EXD20 must deliver exactly the same data as user exit EXK20 received. All modifications applied to compressed data with EXK20 must be undone with EXD20.

EXD20 is available in FLAM, FLAMUP and FLAMREC and corresponds with EXK20 during decompression.

#### Key management KMEXIT

This user exit returns a key to the FLAM utility for en/decryption of a FLAMFILE.

So it is possible to enter any PASWORD/CRYPTOKEY in a secure way without notice to the JCL or the protocol.

This exit is implemented as an interface to special key management systems, without influence to the FLAM utility programs.

#### Utilities

Some utilities are released that improves support form FLAM and FLAMFILEs for z/OS only.

#### FLAMCKV

FLAMCKV analyses a cataloged VSAM-KSDS FLAMFILE. It displays the procentual distribution of record lengths and the number of records needed for one FLAM matrix (in FLPRINT, RECFM=VB,LRECL=124).

This is very important for direct access to a VSAM-KSDS FLAMFILE.

Please remember: FLAM needs a complete matrix (i.e. a block of self-contained compressed records) for decompression.

Even for direct access to a single record this complete matrix is requirerd. So performance is best when this matrix is stored in one VSAM record.

If the VSAM record is too small to fit a complete matrix, FLAM has to read or write mutiple records. This decreases perfomance.

These requirements are not so important for a small amount of data. But if thousands or millions of records are stored it becomes more and more relevant.

Example:

    $$//CKV EXEC PGM=FLAMCKV$$
    $$//STEPLIB DD DSN=FLAM.LOAD,DISP=SHR$$
    $$//FLPRINT DD SYSOUT=*$$
    $$//FLAMFILE DD DSN=USER.XMLDAT1.ADC,DISP=SHR$$

#### FLAMCTAB (!! deprecated !!)

Utility FLAMCTAB should not be used anymore in order to create translation table modules.

All common translation table modules are provided and can be downloaded from our website under: FLAM4 Translation Tables.

Please use further information described there and the precompiled load modules for the most common convertions you can find under download.

Another alternative under FLAM5/FLCL is usage of command 'FLAM' with keyword 'FROM' (conversation from CCSID) and 'TO' (conversation to CCSID [UTF-8]).

#### FLAMDIR

FLAMDIR reads a FLAMFILE (DD-name FLAMFILE) and logs the directory of the compressed/encrypted files. The output (DD-name FLPRINT) looks like an ISPF panel 3.4 or option 'I' in FLAM start panel or FLTOC clist.

Using the FLAM-parameter `D,SHOW=DIR` you still get a full protocol of the directory of the FLAMFILE.

But using FLAMDIR the protocol is a conveniently laid out short summary of the directory of a Group FLAMFILE.

Example:

    //DIR EXEC PGM=FLAMDIR
    //STEPLIB DD DSN=FLAM.LOAD,DISP=SHR
    //FLPRINT DD SYSOUT=*
    //FLAMFILE DD DSN=USER.ARCHIV.ADC,DISP=SHR