#### FLAMOUT

#### Synopsis

    HELP:   Name/URL of the files to be decompressed [STREAM(STDOUT)]
    TYPE:   STRING
    SYNTAX: FLAMOUT/FLAMO='str'/STREAM/DUMMY

#### Description

Filename for the output file.

With this parameter the names of the decompressed files are specified. During decompression the decompressed data of the FLAMFILE are written into the specified file(s).

#### Important note:

Selection and conversion rules using pointed brackets '<>' are dropped in FLAM5 and cannot be used anymore. So, the rules described in section the old FLAM4 manuals are deprecated and a migration is required. The new rules are explained in the section Input to Output Name Mapping and apply to the parameter FLAMFILE.

Syntax restrictions for FLAMv4 or older:

- z/OS
  - `FLAMOUT=filename`
  - `FLAMO=filename`
- UNIX
  - `-flamout=output specification`
- WINDOWS
  - `flamout=output specification`

Values

- z/OS
  - Filename with max. 54 characters
  - `*DUMMY`
- UNIX
  - output specification
    - Note: With compression, file specification specifies a specific file or a list of files separated by commas. A substitution rule is also permitted.
      With decompression, file specification specifies a specific file, a pattern (with wildcards * or ?), or a list of such elements separated by commas.
- WINDOWS
  - output specification
    - Note: With the output specification one or more files are specified into which the decompressed data is to be written. The following special characters are possible, especially in combination with outpath:
      - `flamout=[]` - original file names are stored in FLAMFILE
      - `flamout=[*]` - just as [], but including path, if outpath not specified
      - `flamout=[#]` - Filenames are generated to FILE#nnn, e.g. File#002 = 2nd file in FLAMFILE
      - `flamout=[#3]` - Only the 3rd file from a FLAMFILE archive is decompressed, using the original name
      - `flamout=[#3=<name>]` - Only the 3rd file is decompressed (with <name>)

Default

- no name

Valid for

- compression

#### File specification on z/OS

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.

#### File specification on other platforms

If the output specification contains more than one file, the following rules described with regard to the syntax and the assignment to the FLAMFILE specifications must be observed.

#### Output Specification rules

The output specification may consist of a filename, a list of filenames (separated by commas), or a substitution rule. A substitution rule has the following format: [string1=string2]. Moreover, one of the output specifications [ ], [`*`], or [filename] may be used (see description below). Output files are created if they do not exist and overwritten if they do. If a substitution rule is defined as an output specification, the name of the FLAMFILE or the decompressed file must be formed by substituting string2 for string1 in the name of the input file. The strings and the equal sign must have no separating spaces in between. The substitution rule applies only to file names and not to path names. Example:

    flam -compress -mode=cx8
    flamin=helptxt1.txt,helptxt2.txt
    flamfile=[.txt=.cmp]

causes the files called helptxt1.txt and helptxt2.txt to be compressed and the compressed data to be saved in the associated FLAMFILEs called helptxt1.cmp and helptxt2.cmp. The substitution rule must be applicable to all the assigned input files, i.e. string1 must be contained in the names of every one of these files, or the flam command will be aborted for the file to which it does not apply and an error message will be output. Only one substitution takes place when the name of the output file is formed, even if string1 occurs more than once in the name of the input file. The output specifications [file name], [ ], and [`*`] have special meanings. Using [file name] as output specification causes the decompression to select one or when file name contains wildcards-, possibly several, matching file(s) from a FLAMFILE archive. Those are decompressed into the current directory unless -outpath=... directs otherwise. If the output specification for the decompression procedure is [*], the names of the decompressed files are derived from the FLAMFILE, provided the FLAMFILE actually contains them. If not, an error message is output. -attributes=all must be specified for the compression procedure, in order to include the names of the original files in the FLAMFILE. If the output specification is [], the effect is similar to the output specification [`*`], i.e. the names of the decompressed files are derived from the FLAMFILE(s), except that only the file name is taken into account. The path name is ignored. All the files are thus created in the current directory if no -outpath specification is given. Once again, -attributes=all must have been set for the compression procedure. The output specifications [file name], [], and [`*`] must not be part of a list of output specifications, i.e. they must stand alone. If the output specification specifies files for processing by FLAM, either the -flamfile parameter or -flamout must be specified for the compression or decompression procedure respectively. If the data is to be output to the special file stdout, the parameter for the output specification must be omitted. FLAM can thus be used as a filter.

man_flam4_assignintooutspec.txt

#### Selections

- `STREAM - Read from stdin or write to stdout`
- `DUMMY - Read EOF or write nothing`