/**
 * @file FLM4UP.h
 * @brief Specification for the FLAM4 subprogram interface
 * @author limes datentechnik gmbh
 * @date 18.02.2015\n
 * @copyright (c) 2014 limes datentechnik gmbh
 *
 * @mainpage FLAM4 Subprogram Interface
 *
 * 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_).
 *
 * @section ITFSTD Interface standards
 * There are 4 types of parameters:
 *
 * <pre>
 * 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))
 * </pre>
 *
 * 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.
 *
 * @section PRODEFFIL 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').
 *
 * @section RETCODES 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\n
 * 1  - command line, command syntax, mapping, execution and finish of the command was successful but a warning can be found in the log\n
 * 2  - command line, command syntax, mapping, execution was successful but cleanup of the command failed (may not happened)\n
 * 4  - command line, command syntax and mapping was successful but execution of the command returns with a warning\n
 * 8  - command line, command syntax and mapping was successful but execution of the command returns with an error\n
 * 12 - command line and command syntax was OK but mapping failed\n
 * 16 - command line was OK but command syntax was wrong\n
 * 20 - command line was wrong (user error)\n
 * 24 - initialization of parameter structure of the command failed (may not happened)\n
 * 28 - configuration is wrong (user error)\n
 * 32 - table error (something within the predefined tables is wrong)\n
 * 36 - system error (e.g. load of environment or open of file failed)\n
 * 40 - access control or license error\n
 * 44 - interface error (e.g. parameter pointer equals NULL)\n
 * 48 - memory allocation failed (e.g. dynamic string handling)\n
 * 64 - fatal error (basic things are damaged)\n
 * >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.
 *
 * @section OUTTRC Output and trace files
 * To activate a output or trace file the environment variables below
 * can be used:
 *
 *      FLM4UP_OUTPUT_FILE
 *      FLM4UP_TRACE_FILE
 *
 * @section SAMPLE 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.
 *
 **********************************************************************/

/*! @cond PRIVATE */
#ifdef __cplusplus
   extern "C" {
#endif

#ifndef INC_FLM4UP_H
#define INC_FLM4UP_H

#ifdef __ZOS__
#  pragma linkage (FLM4UP,OS)
#  pragma linkage (FLM4UPV,OS)
#  pragma linkage (FLM4UPA,OS)
#  pragma linkage (FLM4UPL,OS)
#  define flamup           FLM4UP
#  define flamup_version   FLM4UPV
#  define flamup_about     FLM4UPA
#  define flamup_license   FLM4UPL
#endif
/*! @endcond */

/**********************************************************************/
/**
 * @defgroup FUNC Functions
 * @brief Functions provided by this interface.
 * @{
 */

 /**
  *  @brief Version
  *
  * This function returns a string with version information for each
  * used component. This should be used in a support case.
  *
  * @return a pointer to a static area containing the zero-terminated
  *         version string
  */
 extern const char*   flamup_version(void);

 /**
  *  @brief About
  *
  * This function returns a string with about information for this
  * library on multiple lines and license information for used external
  * libraries.
  *
  * @return a pointer to a static area containing the zero-terminated
  *         about string
  */
 extern const char*   flamup_about(void);

 /**
  *  @brief Get license text
  *
  * This function can be used to get the current license text on multiple
  * lines. The license text defines the permissible use of this library.
  *
  * @return a pointer to a static area with a zero-terminated string
  *         containing the current license text.
  */
 extern const char*   flamup_license(void);

/**
 * @brief Runs the old FLAM command line (load module interface (COBOL, PL1))
 *
 * Compress/decompress entire files in user-defined applications. Supports
 * the FLAM4 command string syntax. For more information see FLM4BOOK or
 * FLCL FLAM Command.
 *
 * @param [inout] flamid   POINTER  Pointer to the workarea; parameter unused for backward compatibility, simply pass NULL
 * @param [out]   rtc      INTEGER  Pointer to a signed long that will contain the condition code of the command after it returns\n
 * @param [in]    param    STRING   FLAM4 parameter string (see FLM5BOOK)
 * @param [in]    paramLen INTEGER  The length of parameter string of NULL if the parameter sting zero-terminatied.
 */
extern void flamup(
   void**               flamid,
   long*                rtc,
   char*                param,
   long*                paramLen);


/*! @cond PRIVATE */
typedef void (TfFlamUp)(void** flamid, long* rtc, char* param, long* paramLen);
/*! @endcond */

/**********************************************************************/

/**
 * @brief Runs the old FLAM command line (C like interface)
 *
 * Compress/decompress entire files in user-defined applications. Supports
 * the FLAM4 command string syntax. For more information see FLM4BOOK or
 * FLCL FLAM Command.
 *
 * @param [in]   param  STRING   A null-terminated string containing the FLAM4 command string to be used.
 * @return [out] signed INTEGER  Condition code of the FLAM4 command\n
 */
extern long flamupc(const char* param);

/** @} */
/**********************************************************************/

/*! @cond PRIVATE */
#endif /* INC_FLM4UP_H */

#ifdef __cplusplus
   }
#endif
/*! @endcond */

/**********************************************************************/
