  _______     _                                _          _
 |  _____|   | |                 /\           | \        / |
 | |         | |                /  \          |  \      /  |
 | |         | |               / /\ \         |   \    /   |
 | |____     | |              / /  \ \        | |\ \  / /| |
 |  ____|    | |             / /    \ \       | | \ \/ / | |
 | |         | |            / /______\ \      | |  \  /  | |
 | |         | |           / /________\ \     | |   \/   | |
 | |         | |_____     / /          \ \    | |        | |
 |_|         |_______|   /_/            \_\   |_|        |_|


INSTALLATION OF FLAM V5 ON LINUX
--------------------------------

Frankenstein Limes(r) Infrastructure Version 5
Copyright (C) limes datentechnik(R) gmbh
All rights reserved
----
	limes datentechnik gmbh
	Louisenstrasse 101
	61348 Bad Homburg / Germany

	Tel.++49 (0)6172-59190
	Fax ++49 (0)6172-591939

	eMail support@flam.de

	https://www.flam.de
	https://www.limesdatentechnik.de
----

PREREQUISITES
-------------

GLIBC >= 2.17

For commercial usage and compatibility with previous FLAM V4, a separate
package containing a license is required.
Without this, all conversions are limited to files smaller than 1 MiB.


DESCRIPTION:
------------

The most convenient way to install FLAM on Linux is to use the native
package management of your distribution.
If you cannot use this option, please see the MANUAL INSTALLATION below.

The following linux package formats are supported:

* DEB
* RPM
* pacman (ArchLinux)
* TAR


Debian or Debian based distributions
------------------------------------

First, the package signing key from limes datentechnik gmbh must be imported to
the keychain of Debian. This is done with the following command:
----
    wget -O - https://repo.flam.de/linux/apt/conf/limes.gpg.key | apt-key add -
----
The file /etc/apt/sources.list.d/limes.list has to be created with the following
content:
----
    deb https://repo.flam.de/linux/apt wheezy main
----
FLAM can now be installed using the commands:
----
    apt-get update && apt-get install flam
----
to install the license package:
----
    dpkg -i flamlic-X.X-$arch.deb
----
where "X.X" must be replaced with the version number and "$arch" with the name of
the used platform.


RPM
---

First, the package signing key from limes datentechnik gmbh must be imported to
the keychain of the system. This is done with the following command:
----
    rpm --import https://repo.flam.de/linux/apt/conf/limes.gpg.key
----
The file limes.repo has to be created with the following content:
----
    [limes]
    name=RPM Repository of limes datentechnik gmbh
    baseurl=https://repo.flam.de/linux/RPMS
    enabled=1
----
On Fedora, RedHat, or CentOS this file has to be in /etc/yum.repos.d
On S.u.S.e. in /etc/zypp/repos.d

FLAM can now be installed using the commands:

CentOS:
----
    yum update && yum install flam
----
Fedora, RedHat:
----
    yum updateinfo && yum install flam
----
S.u.S.e.:
----
    zypper refresh && zypper install flam
----
to install the license package:
----
    rpm -i flamlic-X.X-$arch.rpm
----
where "X.X" must be replaced with the version number and "$arch" with the name of
the used platform.


pacman
------

First, the package signing key from limes datentechnik gmbh must be imported to
the keychain of ArchLinux. This is done with the following command:
----
    wget -O - https://repo.flam.de/linux/apt/conf/limes.gpg.key | pacman-key --add -
----
In the file /etc/pacman.conf the URL of the limes ArchLinux repository must be
added:
----
    [limes]
    Server = https://repo.flam.de/linux/pac/limes/os/$arch
----
FLAM can now be installed using the commands:
----
    pacman -Sy && pacman -S flam
----
to install the license package:
----
    pacman -U flamlic-X.X-$arch.pkg.xz
----
where "X.X" must be replaced with the version number and "$arch" with the name of
the used platform.


MANUAL INSTALLATION
-------------------

Debian or Debian based distributions
------------------------------------

After downloading the packages matching your platform, you can install the
packages with the following command:
----
    dpkg -i packagename.deb
----
If you wish to use FLAM4, you must install the packages
'flam4_<version>_<platform>.deb' and 'flam_<version>_<platform>.deb'.
Otherwise installing 'flam_<version>_<platform>.deb' is sufficient.

You may optionally install the documentation package 'flamdoc_<version>_all.deb'.


RPM (CentOS, Red Hat, Fedora, SUSE)
-----------------------------------

First, the package signing key from limes datentechnik gmbh must be imported to
the keychain of the system. This is done with the following command:
----
    rpm --import https://repo.flam.de/linux/apt/conf/limes.gpg.key
----
After downloading the packages matching your platform, you can install the
packages with the following command:
----
    rpm -Uvh -i packagename.rpm
----
If you wish to use FLAM4, you must install the packages
'flam4_<version>_<platform>.rpm' and 'flam_<version>_<platform>.rpm'.
Otherwise installing 'flam_<version>_<platform>.deb' is sufficient.

You may optionally install the documentation package 'flamdoc_<version>_all.rpm'.


ArchLinux or ArchLinux based distributions
------------------------------------------

After downloading the packages matching your platform, you can install the
packages with the following command:
----
    pacman -U packagename.pkg.tar.xz
----
If you wish to use FLAM4, you must install the packages
'flam4-<version>-<platform>.pkg.tar.xz' and 'flam-<version>-<platform>.pkg.tar.xz'.
Otherwise installing 'flam-<version>-<platform>.pkg.tar.xz' is sufficient.

You may optionally install the documentation package
'flamdoc-<version>-all.pkg.tar.xz'.

TAR - distribution independent
------------------------------

If you don't want to or cannot use one of the packages you can use the
tarball. Just extract it with a command like this:
----
    tar xzf flam-<version>.tar.gz
----
After extracting the tarball with root permissions in the root directory "/"
you will find everything in the directory '/opt/limes/flam'

This is the same directory layout as if installed from one the packages.

In case you need to put the flam directory somewhere else, extract the
tarball to where you want it to be.

to install the license package:
----
    cd /
    tar -xavf <path-to-tarfile>/flamlic-X.X-$arch.pkg.xz
----
where "X.X" must be replaced with the version number and "$arch" with the name of
the used platform.

ENVIRONMENT Variables:
----------------------

Make sure /opt/limes/flam/bin is in your PATH variable and
/opt/limes/flam/lib is in your LD_LIBRARY_PATH in order to start using flam.

To be able to use the provided man pages with the man utility, set the variable
MANPATH to contain the path /opt/limes/flam/doc/man
----
    export MANPATH=/opt/limes/flam/doc/man:
----
The position of the colon determines if this directory is searched before or after
the standard manpath. See manpath(5)

For Micro Focus Enterprise Server support you might want to set
----
    FLAM4MF=yes
----
within the ES instance. See FL4REC documentation.

If automatic character conversion is needed the encoding should be set, e.g.
----
    FLAM4MF=IBM-1047
----
to use the US EBCDIC encoding. If the encoding string begins with 'IBM',
big endian is assumed and binary values will be byte swapped.

In case of an error a trace file can be activated with
----
    FLAM4MF_TRACEFILE=flam4mf_trace.txt
----

To support static and dynamic system variables, the two filenames below
are read to the environment. The second file name can be used in
conjunction with the JCL User Exit to provide the dynamic system
variables.
----
    FLAM4MF_STATIC_SYSVAR=~/.sysvar.txt
    FLAM4MF_DYNAMIC_SYSVAR=.sysvar.txt
----

An additional alternative to define system variables in the MF EDZ
environment is the DD name SYSVAR. For example, this job card can be
used to define the JOBNAME as inline encoding.

Known Micro Focus issue:
~~~~~~~~~~~~~~~~~~~~~~~~
Functions passing pointer adresses, for example flmloc(), only work if the Cobol
compiler directive AMODE is NOT used. With AMODE, mainframe pointers are used in the
Cobol program which cannot be converted.

In case of an error a trace can be activated with
----
    FLAM4MF_TRACEFILE=flam4mf_trace.txt
----

Note:
~~~~~
An ES instance which already used FLAM4MF must be restarted before a new version
is used after installation.

Known install issues:
---------------------

The signature check of the RPM package currently fails on SUSE Linux Enterprise Server 11.
The workaround here is to NOT check the signature during installation.
This is done by NOT importing the public key into the rpm keyring.
During installation the a warning will be shown, but the package is installed.


First steps after installation:
-------------------------------

The config file of FLCL is managed with its builtin functions. It is read
from FLCL at the beginning and if it was changed during its execution it is
overwritten. Without changes, nothing is written. Therefore a config file
will only exist if an FLCL command was executed which changed a default
setting. The first line of output of FLCL shows the used config file.
If the environment variable FLCL_CONFIG_FILE is not set, FLCL looks for
a file with the name .flcl.config in the current directory. If it is not
found there, it looks in the user home directory.
If the environment variable FLCL_CONFIG_FILE is set, it uses its value as
the filename.

It is advisable to at least set the environment variable LANG appropriately
to get the correct character conversions. For example:
----
    flcl setenv LANG=de_DE.CP1252
----
To get information about the active license execute
----
    flcl license
----
FLCL has a lot of documentation builtin. First of all, when called without
any arguments a list of all commands and buitin functions is given. To view
a list of all possible LEXEM and GRAMMAR on can execute
----
    flcl lexem
    flcl grammar
----
To get help for an individual command e.g. CONV
----
    flcl help conv
----
To get help for the READ overlay of the CONV command
----
    flcl help conv.read
----
To get a part of the manual, e.g. for the input object of the XCNV command
----
    flcl help xcnv.input man
----
or for the syntax, here with all levels
----
    flcl syntax conv.read all
----
The dot notation allows to get specific help for each object, overlay and
single parameter of FLCL. All condition and reason codes are shown with
----
    flcl errors
----
Further buitin functions allow e.g. to activate TRACE messages, manage
properties and environment variables, generate the complete documentation, ...

With "flcl manpage" it is possible to view the manpage of each command or
builtin function.
----
    flcl manpage setprop
----
All config settings are done for a specific owner (default owner is "LIMES").
This might be used for separation of clients.

The GUI FLCC allows to create and edit property files and FLCL command lines
and provides access to all documentation.

Examples:
---------

To decompress a FLAMFILE:
----
    flcl conv "read.flam(file='flamfile.adc') write.binary/text/record(file='output.dat')"
----
To compress a file with ADC:
----
    flcl conv "read.record/text/binary(file='input.dat') write.flam(file='flamfile.adc')"
----

Compatibility with Version 4.3:
-------------------------------

To be compatible with the older flam4 utility the default record format
can be adjusted by setting the properties:

----
    flam4 CHGPROP flam outrecformat=stream inrecformat=stream
----
