... print CLE_DOCTYP_COVER = FLCL Manual :doctype: book = FLCL Manual limes datentechnik(R) gmbh v5.1.28-33135, 2024-03-08: release. This document provides information about using the Frankenstein Limes Command Line (FLCL(R)). It contains guidelines and information about how to run the commands provided by FLAM(R). FLCL is the main utility to use FLAM in batch jobs or scripts. The most interesting part of this documentation for the day-to-day use is probably the <>. Basic topics like installation, environment, filename and directory handling, input to output name mapping, pre- and post-processing, as well as tables are described in the chapter <>. Several APIs are available to use FLAM in own applications written in various languages (e.g. C, C++, Java, PL1 and Cobol). They allow your application to use FLAM for file-to-file, file-to-memory, memory-to-file and in-memory conversions (enterprise service bus). Some of these APIs require additional strings which are described in a <>. On Linux, <> can be used. It is a FUSE filesystem that can be mounted to any directory. Everything written to the mounted folder is transparently converted, encrypted and/or compressed as defined in the configuration. Multiple conversions can be configured for the same mountpoint. On z/OS, the <> (FLUC-sub) is available. It is a subsystem of the z/OS operating system and is activated by the subsystem interface of the command language (JCL). All calls of an application to file operations (e.g. opening, closing a file, reading and writing) are received and processed by FLUC-sub. Thus, FLUC-sub allows data conversions that are transparent to the application. The FLCL is based on the FLAMCLE and FLAMCLP (CLE/P(R)) which is an open source component for parsing, processing and executing command strings. It also handles various other aspects of commands, including configuration management (via property files and environment variables) and documentation. More details can be found in the <> and the <> reference. <> and <>, which comprise the command strings' syntax, as well as <> and <> are addressed in this manual. Copyright (C) limes datentechnik (R) gmbh + All rights reserved ... print CLE_DOCTYP_CHAPTER == Preface [preface] == Preface FLCL is based on the CLE/P library. The CLE/P library was developed by limes datentechnik and released as open source under the ZLIB license. CLE/P is a compiler to provide a platform-independent command line interface for each kind of batch processing environment. The CLE/P library provides a lot of features including the <> used below. For example: We use this library to automatically create this document as part of our build process; If we add a parameter to the CLE/P tables and build the FL5 project, this manual will be regenerated as well in order to be always up to date. This manual can by generated with the built-in functions GENDOCU or HTMLDOC provided by CLE/P library by calling the command below: ----------------------------------------------------------------------- flcl gendocu flclbook.txt flcl htmldoc flclbook.html ----------------------------------------------------------------------- To generate HTML documentation yourself instead of using the pre-built documentation, a service provider DLL must be available. The text file can be fed to Asciidoctor to build a PDF and/or an HTML5 document. ... print CLE_DOCTYP_CHAPTER === Trademarks === Trademarks Below, you can find all trademarks or registered trademarks of limes datentechnik (R) gmbh. These trademarked terms are marked with the appropriate symbol ((R) or (TM)), indicating registered or common law trademarks owned by limes datentechnik (R) gmbh at the time this information was published. The following terms are trademarks of limes datentechnik (R) gmbh in Germany, other countries, or both: * LIMES(R) - Short company name of the owner of this document * limes datentechnik(R) - Company name of the owner of this document * FLCL(R) - Frankenstein Limes Command Line * FLCC(R) - Frankenstein Limes Control Center * FLAM(R) - Frankenstein Limes Access Method * FLUC(R) - Frankenstein Limes Universal Converter * FLIES(R) - Frankenstein Limes Integrated Extended Security * FKMS(R) - Frankenstein Key Management System * FKME(R) - Frankenstein Key Management Extension/Exit * FLAMFILE(R) - A file based on FLAM syntax * CLE/P(R) - Command line Executer/Parser ... print CLE_DOCTYP_CHAPTER === License Terms === License Terms The license terms for all software components owned by limes datentechnik gmbh(R) can be found in LICENSE(.txt) in the installation folder doc/txt or in the partitioned dataset HLQ.FLAM.DOCTXT. Additional license information for external libraries used by this software can be found in ABOUT(.txt). The replacement of external libraries (LGPL) is described following the changelog in the file README(.txt). All license terms of the external libraries are included as files (LICxxxxx(.txt)) in doc/txt folder or in HLQ.FLAM.DOCTXT partitioned dataset. All old FLAM components till version 4 are completely owned by limes datentechnik gmbh (R). Only on Linux systems the glibc is used in unmodified form as prerequisite (part of the operating system, not part of the distribution) based on the LGPL license. The old FLAM4 components don't provide additional about and version commands or functions. The service provider interfaces (exits, extensions) of FLAM are owned completely by limes datantechnik gmbh(R) and provided to our users for individual extension to this software. The driver is conforming to this license terms but LIMES(R) is not responsible for such individual implementations which are not part of our distributen. Our own implementations against these SPIs (e.g. FAVECAV, PKCS#11, IBM-CCA/ICSF) are in sync with the stated license terms here. A lot of this information is generated in the package build process and can be requested over the corresponding built-in commands of our utilities or the corresponding functions of the APIs. To request the current valid state, please use the command or functions below (there are more APIs with analog functions available): ------------------------------------------------------------------------ COMMAND API 1 API 2 ... API n > flcl license fcblic() FCRLIC() ... fliconv_license() > flcl about fcbabo() FCRABO() ... fliconv_about() > flcl version fcbvsn() FCRVSN() ... fliconv_version() ------------------------------------------------------------------------ The about and version information are also added as appendix to the manual's provided by limes datentechnik gmbh(R). The version information contains version, release and revision number of each component followed by the current build number. The versioning of the different components is independent of each other. The build number must be the same for each component and must correspond to the build number of the installation package. If the build number is not identical for all compiled and linked components, then the installation is wrong. ... print CLE_DOCTYP_CHAPTER === About Limes === About Limes Since 1985, limes datentechnik(R) gmbh has been successfully producing quality software that simplifies data exchange across platforms and across borders (formatting, converting), secures data archiving and transmitting (encrypting, signature) while reducing storage use (compressing), and, finally, allows accessing data without depending on particular platforms or data formats (access method). .What do we offer? * Professional management of compressed and encrypted data including strong access control * Secure data storage (archive) and data transfer * Protection of data privacy, integrity, and completeness * Cutting-edge security technologies for handling of sensitive data being outsourced, securing clouds etc. * Meeting safety requirements such as "need-to-know", PCIDSS, etc. * Easy data exchange across borders, platforms, and formats (with regard to internationalization moves, when migrating, etc.) * Saving of time and money through automation options and reduced resource utilization (CPU, memory, external storage) .How do we achieve it? * Converting, compressing, encrypting, and signing of data * Reading and writing methods for various data and file formats * Transforming data into a neutral internal format (FLAMFILE(R)) that allows searching and positioning within encrypted and compressed data * Storage of data in various formats (file, cluster, VSAM, database) * Separating data compression and encryption (client) from data storage (server) * Neutral access to individual data records, data elements, or bytes via various APIs * Connecting solutions to any cryptographic infrastructure with access control via key-management including periodic or adhoc re-keying * Unrestricted extendibility and adaptability through customer-APIs for Cobol/PL1, c/C++ and Java (other programming languages on request) * Transparent integration as I/O subsystem, user space file system, ISP, driver or by incorporating as a subroutine * Scripting, backup, restart and stream capability for switching to automated operation * Programming in ANSI-C and assembler utilizing hardware accelerators and special instructions of the various platforms .What do we stand for? * Beside decades of experience with cross-platform and cross-border data exchange, limes datentechnik(R) stands for protection of your investment and for lasting reliability due to the uncompromising downwards compatibility of its products and the friendly customer care provided as part of its support services. * limes datentechnik(R) not only offers solutions for bulk data handling in the mainframe environment, it also supports all current platforms and systems for migrating and long-term archiving. * For more than 30 years limes datentechnik(R), located in Bad Homburg, Germany, has been providing resilient, error-free, high-quality software meeting professional standards - guaranteed 'Made in Germany'. ... print CLE_DOCTYP_CHAPTER === Overview === Overview This document provides information about using the Frankenstein Limes Command Line (FLCL). It contains advanced guidelines and information to run the commands provided by this batch interface. FLCL is the main utility to run all the different subprograms of the FL5 infrastructure. Beside FLCL, the FL5 infrastructure consists of the components below: * FLCC - Frankenstein Limes Control Center (GUI) ** Graphical user interface to build FLCL commands, property files and more ** It is also useful to construct parameter strings for FLAM's APIs ** Interactive help and documentations, can be used as replacement for this book * FLUC - Subsystem for z/OS and Linux ** Application-transparent conversion, compression and encryption of files ** Can be used to make applications compliant to several security standards ** Implemented on z/OS as I/O-Subsystem and on Unix as user space file system ** Gives you complete control over the encrypted file ** One logical file can be written to multiple (local and/or remote) targets *** Note: Only one of these files can be read via this logical file view ** Supports remote files via SSH and different archives formats * FLUCUP - FLUC Subprogram as C interface (DLL) ** Data source to target conversion as described in this document ** Each command is available as function (flucconv()) ** FLCL command line = parameter string for subprogram ** `ret=flucinfo("get.file=test.txt");` * FLUCUPLB - FLUC Subprogram as load module interface ** All functions of FLUCUP (flucconv) are provided as load modules for simple integration in COBOL, PL1 or assembler programs on mainframes. ** `FCUCONV("read.file=DD:INPUT")` * FLCBYT - Byte interface for original data (C like DLL) ** You can transparently read and write each kind of data source or target as byte stream or records with a C like file-I/O interface using the read or write overlays of the FLCL-CONV/XCNV commands described in this document. ** `f=fcbopen("read.file=text.txt","format.record()");` ** `f=fcbopen("write.text(file=out.txt comp.bzip())","format.text()");` ** Beside file to memory, memory to memory conversion is also supported *** The memory to memory interface makes FLAM an enterprise service bus (ESB) * FLCBYTBF - C++ streambuf class for I/O streams based on FLCBYT ** You can pass an flcbyt_buffer object to an istream or ostream instance in C++ and use the byte interface as a regular stream. ** `flcbyt_buffer buf("read.file=text.txt","format.bin()");` `std::istream in(&buf);` ** `flcbyt_buffer buf("write.text(file=out.txt)","format.text()");` `std::ostream out(&buf);` * FLCBYTJava - Java Native Interface (JNI) library for the FLUC byte interface and corresponding stream classes for Java (like FLCBYTBF for C++) ** This Java-wrapper of the FLCBYT library enables Java developers to use all FLAM byte interface capabilities in any Java application. It contains several classes that make working with the byte interface much more comfortable, for example classes using the stream API or in-memory conversion classes for different access patterns. * FLCRECLB - Record interface for original data (load modules) ** You can transparently read (GET) and write (PUT) each kind of data source or target in a record-I/O-like interface also using the read and write unions of the CONV command or the input and output objects of the XCNV command in the corresponding file open function. All functions are provided as separate load module for simple usage in COBOL, PL1 or assembler programs. ** `FCROPN("read.auto(file=.VASM.KSDS ccsid=1141)")` ** `FCROPN("write.text(method=win, ccsid=1252, comp.gzip(level=9))")` ** Additionally, you can parse XML datasets, or convert variable records containing comma-separated values (CSV) into fixed-length data structures (COPYBOOKs/FB-Records) and use a set of functions to convert integers, floats, strings and binary blobs from various representations (e.g. a number as UTF-8 string in an XML element) into COBOL or PL1 data types (PIC S9(9) COMP). ** In-memory conversion is also supported ** Simple environment, system and JCL variable handling ** Supports Micro Focus EDZ environments ** The interface was designed to work with copybooks (static structures) in COBOL or PL1 and to produce XML, CSV or other (dynamic) data formats in clear, compressed and/or encrypted form. * FLCICV - FLUC character conversion module (ICONV like DLL) ** You can transparently use this libiconv-compatible interface for memory to memory character conversions. It supports all feature of our character conversion component (CNVCHR), including: *** Stop, ignore, substitution and transliteration for invalid characters *** EBCDIC new line to line feed management *** User table, subset support (SEPA, String.Latin(XOEF/NPA), ...) *** Normalization (NFC/NFD) and combined character support *** UTF-8 with 5 and 6 byte long encodings *** Case mapping, BOM management (including byte order change support) *** Comprehensive reporting of error positions (SUB, IGN, XLT, ...) ** `h=fliconv_open("IBM1141//ENL2LF","UTF-16LE//BOM//IGNORE//TRANSLIT(ICONV)//USRTAB(DELA)//REPORT(DD:REPORT)");` ** `fliconv(h,&indat,&inlen,&outdat,&outlen);` ** `fliconv_close(h);` ** Look for FLICONV utility program and the corresponding sample source This document is also useful for users of the stream, byte, record, element or subprogram interfaces of the FL5 infrastructure because all these interfaces use the same syntax as the command line. The format, conversion and state strings for these APIs are documented in Appendix A 'Other CLP strings' at the end of this book. Various C/C++ sample programs for the APIs above can be found in the library SRCLIBC as part of the installation package for mainframe systems. The corresponding compile and link step is in JOBLIB(SBUILD). Additional COBOL, PL1 and Assembler samples can be found in the library SRCLIB. The corresponding compile and link procedures are also located in JOBLIB(SBUILD) as separate steps. For other platforms (Windows, UNIX) the C, C++ and Java sample program sources are located in the 'sample' directory and the compile and link procedures can be found in the Makefile of the same directory. Beside all these new FL5 based components, the following FLAM4 components are still supported: * FLAM4-Utility - The command line program, also available as command FLAM in FLCL or as separated executable FLAM4 with all advantages of the new FL5 architecture. * FLAM4-Subprogram - Integration of file to file compression and decompression in other programs (works like FLUCUP[LB]. For new projects we recommend to use the flucflam() or FCUFLAM() functions, the FL5 project offers also the FLM4UP and flamupc() entries which are backward compatible with FLAM4). * FLAM4-Record interface - Record-wise (length and data) read (GET) and write (PUT) access to compressed FLAMFILES. * FLAM4-Subsystem (only on z/OS) - Application-transparent integration of FLAM at SVC99 file allocation ** `FILE DD DSN=&SYSUID.TEST,DISP=...,...,SUBSYS=FLAM` With FLAM5 new CLIST, PANELS and MESSAGES were added for ISPF on z/OS: * FLINFO - ISPF line command to show determined file attributes * FLVIEW - ISPF line command to show content of different files ** normal host data sets, members of PDS/PDSE, VSAM data sets ** Directory content of PDS/PDSE, FLAMFILES, GZIP/BZIP/XZ files ** binary transfered XML or text files from other platforms ** base encoded, encrypted, compressed files ** and much more * FLTEXT - ISPF line command like FLVIEW, but it produce dumps for binary files * FLVEDIT- ISPF line command to edit content of different files ** works like FLVIEW, but you can edit the data ** the data is then written back in the original format ** for example you can edit UTF-8 XML data in a GZIP file over ISPF * FLVEDITx - Like FLVEDIT but with limited record length and no cut of records * FLDEL - ISPF line command to delete each kind of file (incl. VSAM) * FLGREP - ISPF command to search for a regular expression pattern in any of files using the directory walk (FLGREP pattern dsn) * FLHLP - ISPF command for interactive help of FLCL commands * FLSYN - ISPF command for interactive syntax of FLCL commands * FLMAN - ISPF command for interactive manual pages of FLCL commands * FLDOC - ISPF command for documentation generation of FLCL * FLGRA - ISPF command to show grammar of FLCL commands * FLLEX - ISPF command to show lexems of FLCL commands * FLABO - ISPF command to show about information of FLCL * FLVSN - ISPF command to show version information of FLCL * FLLIC - ISPF command to show license information of FLCL * FLSYS - ISPF command to show system information for FLCL Also with FLAM5, GUI tool flgt -c=info/view/edit/checksum were added for use via the Windows context menu. Registering the Windows context menu is performed during installation. * INFO - shows file properties such as file size, file format, data type, charset, ... * VIEW - displays contents of a file; useful for compressed files or text data files in a wrong charset; This tool decompresses and/or decodes selected files and tries to open the result with the default program for the respective file type. It can also be used for encrypted files, which requires the appropriate key information to be set in your property file. * EDIT - like flview, but can edit files (default if no command defined) * CHECKSUM - easy way to calculate checksum (CRC/SHA/...) On Unix systems, these utilities are also available on command line. The integration in the context menu of the different desktop systems, must be done manually. On z/OS systems, we support zEDC, zIIP, CPACF, ICSF, RACF, SMF logging and a lot of mainframe-exclusive features. Please read the install.txt for z/OS carefully to set FLAM up correctly to allow it to use such features (e.g the FLAM started task (FLAMSTC), authorization and link list concatenation is often required). ... print CLE_DOCTYP_CHAPTER === Use Cases === Use Cases //// The comments in this file are used in FLCC to populate the use cases dialog. For this to work, each example use case documented here must be preceded by a comment section like the example here: example X title=example for an example entry cmd=conv "read.auto() write.dummy() message(erronly)" env=HOME=me env=LANG=de lines starting with a space are considered continuation lines of the previous line. The CLP string must be enclosed in "" when it is containing a quotation character. to work around the automatic content replacement of the file-string format the cmd= string in a comment must use f--string-- instead of: f'string' //// Below are a few common examples for the use of FLCL. This examples can be loaded in link:../../flcc/index.html[FLCC] from the use case dialog. //// example 1 title=Display information about a file cmd=INFO GET.FILE='test.zip' //// .Example 1 Display information for a file on Windows command shell. ------------------------------------------------------------------------ C:> flcl info get.file=test.zip ------------------------------------------------------------------------ //// example 2 title=Show all supported CCSIDs cmd=INFO GET.CCSIDS //// .Example 2 Show all supported CCSIDs on z/OS using a JCL batch job. ------------------------------------------------------------------------ //FLCLINFO EXEC PGM=FLCL,REGION=0M,PARM='INFO GET.CCSIDS' //STEPLIB DD DSN=&SYSUID..FLAM.LOAD,DISP=SHR //SYSOUT DD SYSOUT=* //SYSPRINT DD SYSOUT=* ------------------------------------------------------------------------ //// example 3 title=Read a FLAMFILE and write it as record-oriented dataset cmd=CONV "READ.FLAM4(FILE='DD:INPUT') WRITE.RECORD(FILE='DD:OUTPUT')" //// .Example 3 Read a FLAMFILE and write it as record-oriented dataset on z/OS. This is the same as FLAM DECO of FLAM4. If you use FLAMFILE/FLAMIN and FLAMOUT as DD name, then the FILE specifications are not required. The DD name FLAMIN is the default for input files on z/OS. If FLAMOUT or FLAMFILE (only if it is a FLAMFILE) not allocated the default DSN (original name plus extension) is used if no file specification given. The default on other platforms would be the standard input or output stream, so you can use this to pipe the data streams. ------------------------------------------------------------------------ //FLCLCONV EXEC PGM=FLCL,REGION=0M,PARM='CONV=DD:PARM' //STEPLIB DD DSN=&SYSUID..FLAM.LOAD,DISP=SHR //SYSOUT DD SYSOUT=* //SYSPRINT DD SYSOUT=* //INPUT DD DSN=&SYSUID..TEST.ADC,DISP=SHR //OUTPUT DD SYSOUT=* //PARM DD * READ.FLAM4( FILE='DD:INPUT' ) WRITE.RECORD( FILE='DD:OUTPUT' ) /* ------------------------------------------------------------------------ //// example 4 title=Read a FLAMFILE member and write it character converted as record oriented dataset cmd=CONV "READ.FLAM4(FILE='~.TEST.ADC' MEMBER=MEMBERNAME CCSID=1252) WRITE.RECORD(FILE=STREAM CCSID=IBM-1141)" //// .Example 4 Read a member from a FLAMFILE and write it as record oriented dataset on z/OS with character conversion from CP1252 to IBM1141 (same as the job above but with dynamic allocation). ------------------------------------------------------------------------ //FLCLCONV EXEC PGM=FLCL,REGION=0M,PARM='CONV=DD:PARM' //STEPLIB DD DSN=&SYSUID..FLAM.LOAD,DISP=SHR //SYSOUT DD SYSOUT=* //SYSPRINT DD SYSOUT=* //PARM DD * &1140; READ.FLAM4( FILE='~.TEST.ADC' MEMBER=MEMBERNAME CCSID=1252 ) WRITE.RECORD( FILE=STREAM CCSID=IBM-1141 ) /* ------------------------------------------------------------------------ Be aware that tilde (abbreviation for '') is a character with different code points in EBCDIC. The environment variable LANG or the corresponding system variables must be defined to the CCSID used to build the in line control statements so that CLP can interpret this correctly else you can define the CCSID used for this CLP string like in the example above. //// example 5 title=record-oriented read and write it to two targets at the same time cmd=CONV "READ.RECORD() WRITE.FLAM(pass=f--PASSFILE--) WRITE.RECORD(encr.pgp(pass=f--PASSFILE--) archive.zip())" env=FLAMIN=DD DSN=&SYSUID..TEST.DAT,DISP=SHR env=FLAMFILE=DD DSN=&SYSUID..TEST.ADC,DISP=NEW env=FLAMOUT=DD DSN=&SYSUID..TEST.ZIP,DISP=NEW //// .Example 5 Read a record-oriented dataset on z/OS and write it to two targets at the same time. . As password-encrypted FLAMFILE on z/OS using static allocation with default DD names FLAMIN and FLAMFILE/FLAMOUT. . As password-encrypted PGP file to a ZIP archive (FLAMOUT). The ZIP file is an encrypted backup of the host dataset containing length fields in front of each record and all relevant DCBs in the ZIP member header. The password for both instances is specified in a file (which is written inline for better understanding of the example). There is no parameter file assigned to the CONV command. In this case the default DD name 'FLAMPAR' are used. The next example shows how you can reconstruct the stored host dataset from the ZIP archive. ------------------------------------------------------------------------ //FLCLCONV EXEC PGM=FLCL,REGION=0M,PARM='CONV' //STEPLIB DD DSN=&SYSUID..FLAM.LOAD,DISP=SHR //SYSOUT DD SYSOUT=* //SYSPRINT DD SYSOUT=* //FLAMIN DD DSN=&SYSUID..TEST.DAT,DISP=SHR //FLAMFILE DD DSN=&SYSUID..TEST.ADC,DISP=NEW //FLAMOUT DD DSN=&SYSUID..TEST.ZIP,DISP=NEW //PASSFILE DD * e'Password' /* //FLAMPAR DD * READ.RECORD() WRITE.FLAM(pass=f'DD:PASSFILE') WRITE.RECORD(encr.pgp(pass=f'DD:PASSFILE') archive.zip()) /* ------------------------------------------------------------------------ The password is defined to use EBCDIC encoding as binary interpretation. With an 'a' you can ensure ASCII but normally we recommend to use 'x' for an hexadecimal string. //// example 6 title=Read PGP encrypted ZIP archive and reconstruct it with original name and DCB parameter cmd=CONV "READ.RECORD(decode decr.pgp(pass=f--DD:PASSFILE--)) WRITE.RECORD()" env=FLAMIN=DD DSN=&SYSUID..TEST.ZIP,DISP=SHR //// .Example 6 Read the PGP encrypted host dataset from the ZIP archive and reconstruct it with the original name and DCB parameter. ------------------------------------------------------------------------ //FLCLCONV EXEC PGM=FLCL,REGION=0M,PARM='CONV' //STEPLIB DD DSN=&SYSUID..FLAM.LOAD,DISP=SHR //SYSOUT DD SYSOUT=* //SYSPRINT DD SYSOUT=* //FLAMIN DD DSN=&SYSUID..TEST.ZIP,DISP=SHR //PASSFILE DD * e'Password' /* //FLAMPAR DD * READ.RECORD(decode decr.pgp(pass=f'DD:PASSFILE')) WRITE.RECORD() /* ------------------------------------------------------------------------ //// example 7 title=write a text file as EBCDIC records to a FLAMFILE for a German z/OS. cmd=conv "read.text(file=test.txt) write.flam(file=test.adc ccsid=1141)" //// .Example 7 Read a text file on windows and write EBCDIC records to a FLAMFILE for a German z/OS. ------------------------------------------------------------------------ C:> flcl conv "read.text(file=test.txt) write.flam(file=test.adc ccsid=1141)" ------------------------------------------------------------------------ //// example 8 title=Read a remote text file and write to a record oriented dataset in EBCDIC(1047) cmd=CONV "READ.TEXT(FILE=ssh://@winserver/test.gz CCSID=1252) WRITE.RECORD(FILE=.OUTPUT.DAT CCSID=1047)" //// .Example 8 Read a remote text file from a windows system (its a GZIP stream in the home directory) and write it on z/OS to a record oriented dataset in EBCDIC(1047). ------------------------------------------------------------------------ //FLCLCONV EXEC PGM=FLCL,REGION=0M,PARM='CONV=DD:PARM' //STEPLIB DD DSN=&SYSUID..FLAM.LOAD,DISP=SHR //SYSOUT DD SYSOUT=* //SYSPRINT DD SYSOUT=* //PARM DD * READ.TEXT( FILE=ssh://@winserver/test.gz CCSID=1252 ) WRITE.RECORD( FILE=.OUTPUT.DAT CCSID=1047 ) /* ------------------------------------------------------------------------ //// example 9 title=Write record oriented host dataset as UFT8 text to a remote PGP file in a ZIP archive cmd=CONV "READ.RECORD(FILE=~.TEST.XMIT(MYTEXT) CCSID=1141) WRITE.TEXT(FILE=ssh://@unix.server.com/out.zip CCSID=UTF-8 encrypt.pgp(userid='receiver.name' signid='my.name' armor()) archive.zip(member='[member].txt'))" env=LANG=de_DE.IBM-1141 //// .Example 9 Write a record oriented host dataset as text in UTF-8 to a PGP file (signed and encrypted), which will be stored as ASCII-armor encoded member in a remote ZIP archive on a UNIX system and convert the member name to a path name. ------------------------------------------------------------------------ //FLCLCONV EXEC PGM=FLCL,REGION=0M,PARM='CONV=DD:PARM' //STEPLIB DD DSN=&SYSUID..FLAM.LOAD,DISP=SHR //SYSOUT DD SYSOUT=* //SYSPRINT DD SYSOUT=* //STDENV DD * LANG=de_DE.IBM-1141 HOME=/u/hugo USER=hugo ENVID=T /* //PARM DD * READ.RECORD( FILE=~.TEST.XMIT(MYTEXT) CCSID=1141 ) WRITE.TEXT( FILE=ssh://@unix.server.com/out.zip CCSID=UTF-8 encrypt.pgp(userid='receiver.name' signid='my.name' armor()) archive.zip(member='[member].txt') ) /* ------------------------------------------------------------------------ If the input output name mapping with square brackets used, then the CCSID for the correct interpretation of the CLP string must be defined (same for tilde). The '@' in the URL is also a character with different code points. In this case FLAM supports also the ampersand as separation between the user and the server, to prevent the requirement to know the CCSID used for correct interpretation. In the example above the DD name STDENV are used to define the most important environment variables required to run FLAM commands. //// example 10 title=write XML files from ZIP archive to FLAM archive for z/OS in EBCDIC cmd=conv "read.xml(file=test.zip/?*.xml) write.flam(file=test.adc member=.XMLPDS([base]) ccsid=1141)" //// .Example 10 Read all XML files from ZIP archive on UNIX in UTF-8 and convert it to a FLAM archive for z/OS in EBCDIC. XML in a FLAMFILE is record-oriented and pretty printed by default. ------------------------------------------------------------------------ $ flcl conv "read.xml(file=test.zip/?*.xml) write.flam(file=test.adc member=.XMLPDS([base]) ccsid=1141)" ------------------------------------------------------------------------ //// example 11 title=text compare BZIP file with FLAMFILE cmd=diff "read.text(file=test.bz ccsid=Latin-1 SUPTWS) compare.text(file=test.adc ccsid=1141 SUPTWS)" //// .Example 11 Compare the content of a BZIP file with the content of a FLAMFILE text record by text record with suppression of trailing whitespace on a UNIX system. ------------------------------------------------------------------------ $ flcl diff "read.text(file=test.bz ccsid=Latin-1 SUPTWS) compare.text(file=test.adc ccsid=1141 SUPTWS)" ------------------------------------------------------------------------ //// example 12 title=Write and read a FLAMFILE on UNIX with piping cmd=cat test.txt | flcl flam comp | flcl flam //// .Example 12 Write and read a FLAMFILE on UNIX with piping (DECO is default). ------------------------------------------------------------------------ $ cat test.txt | flcl flam comp | flcl flam ------------------------------------------------------------------------ //// example 13 title=OpenPGP key management and encryption title=define FKM5 parameter as environment variable cmd=setenv "FL_DEFAULT_PGPRNGPARA="pub='~/.pgp/pubrng.pgp',sec='~/.pgp/secrng.pgp',pass=f'~/.pgp/keyring.pwd'"" title=generate OpenPGP key pair cmd=key "gen.pgp(user='')" title=export OpenPGP public key cmd=key "exp.pgp(user='' file=~/mykey.pgp)" title=import OpenPGP public key cmd=key "imp.pgp(file=~/max.pgp kidver=12B738)" title=Write OpenPGP file with encryption and signing cmd=conv "read.binary(file='message.txt') write.binary(file='message.pgp' encrypt.pgp(userid['Max',''] signid=''))" title=Read OpenPGP file with decryption and verification cmd=conv "read.binary(file='message.pgp' deco) write.binary(file='message.out')" //// .Example 13 OpenPGP key management and encryption using the PGP key ring implementation of libfkm5 on a UNIX system (PGPRING is the default function of libfkm5 library on non IBM platforms. For example, on z/OS, PGPCCA is the default function and with z/OSv2r2 no additional FKM5 parameters are required. This means that the same will work on z/OS with ICSF except that SETENV as first step is not required). * First we define the FKM5 parameter via an environment variable using a password file (no FKM5 specification required anymore) ------------------------------------------------------------------------ $ flcl setenv FL_DEFAULT_PGPRNGPARA="pub='~/.pgp/pubrng.pgp',sec='~/.pgp/secrng.pgp',pass=f'~/.pgp/keyring.pwd'" ------------------------------------------------------------------------ * OpenPGP key pair generation for me (use my user id in small letters) ------------------------------------------------------------------------ $ flcl key "gen.pgp(user='')" ------------------------------------------------------------------------ * OpenPGP export of my public key for other users to file mykey.pgp ------------------------------------------------------------------------ $ flcl key "exp.pgp(user='' file=~/mykey.pgp)" ------------------------------------------------------------------------ * OpenPGP import of the public key of user Max from file max.pgp with verification of the first 6 digits of the key id. ------------------------------------------------------------------------ $ flcl key "imp.pgp(file=~/max.pgp kidver=12B738)" ------------------------------------------------------------------------ * Write OpenPGP file with encryption and signing, encrypt file message.txt with Max's and my public key and sign with my private key. ------------------------------------------------------------------------ $ flcl conv "read.binary(file='message.txt') write.binary(file='message.pgp' encrypt.pgp(userid['Max',''] signid=''))" ------------------------------------------------------------------------ * Read OpenPGP file with decryption and verification. The key is found without any user specification. ------------------------------------------------------------------------ $ flcl conv "read.binary(file='message.pgp' deco) write.binary(file='message.out')" ------------------------------------------------------------------------ //// example 14 title=transfer and convert from remote ZIP to remote GZIP file cmd=conv "read.text(net.ssh(hostkeycheck=ask, user='', host='winserver') file='test.zip/?*' remove ccsid=1251) write.text(file=ssh://@unixserver/[name].gz ccsid='UTF-8' comp.gzip())" //// .Example 14 Use SSH in interactive mode to read a remote ZIP file from a Windows server, convert the character set and write all members (/?*) as remote gzip files to a Unix server (not in interactive mode (URL used)) and delete all members from the ZIP archive (remove) and the empty archive itself. The interactive mode (enabled by hostkeycheck=ask) allows FLCL to require user input instead of failing, e.g. if the SSH host is unknown and must be granted trust manually. ------------------------------------------------------------------------ C:> flcl conv read.text(net.ssh(hostkeycheck=ask, user='', host='winserver') file='test.zip/?*' remove ccsid=1251) write.text(file=ssh://@unixserver/[name].gz ccsid='UTF-8' comp.gzip()) ------------------------------------------------------------------------ //// example 15 title=Convert a FB dataset with 2 columns to a CSV text file cmd=XCNV "INPUT(SAV.FIL(FIO.REC(NAME='DD:FBINP') FMT.TAB(FORMAT=FIX ROW='DD:FBROW'))) OUTPUT(SAV.FIL(FMT.TAB(FORMAT=CSV DEFAULTS(NOHDLN)) FIO.REC(NAME='DD:CSVOUT')))" env=FBROW="NAME='my.fb.record' COLUMN(NAME='name' TYPE.STRING(CHRSET(WHITESPACE=COLLAPSE)) MAXLEN=32) COLUMN(NAME='age' TYPE.INTEGER(FORMAT.BCD(TYPE=PACKED)) MAXLEN=4)" //// .Example 15 Convert a FB dataset with 2 columns to a CSV text file without a headline. The first column is a whitespace-padded name in EBCDIC (local character set) with up to 32 bytes. The second column is a 4 byte packed BCD number with the age of the person. The string should be collapsed (remove leading, trailing and repeated whitespace) for the CSV file, which will be written in the local character encoding (EBCDIC). ------------------------------------------------------------------------ //FLCLCONV EXEC PGM=FLCL,REGION=0M,PARM='XCNV=DD:PARM' //STEPLIB DD DSN=&SYSUID..FLAM.LOAD,DISP=SHR //SYSOUT DD SYSOUT=* //SYSPRINT DD SYSOUT=* //PARM DD * INPUT(SAV.FIL(FIO.REC(NAME='DD:FBINP') FMT.TAB(FORMAT=FIX ROW='DD:FBROW'))) OUTPUT(SAV.FIL(FMT.TAB(FORMAT=CSV DEFAULTS(NOHDLN)) FIO.REC(NAME='DD:CSVOUT'))) /* //FBROW DD * NAME='my.fb.record' COLUMN( NAME='name' TYPE.STRING(CHRSET(WHITESPACE=COLLAPSE)) MAXLEN=32 ) COLUMN( NAME='age' TYPE.INTEGER(FORMAT.BCD(TYPE=PACKED)) MAXLEN=4 ) /* ------------------------------------------------------------------------ //// example 16 title=remote copy with pre- and postproccessing cmd=xcnv "input(save.file(fio.blk(file=wrtorg.bin pre(command='sha1sum [copy]' stdout=wrtorg.local.sha1)))) output(save.file(fio.blk(file=ssh://:limes@tests.limes.de/wrtorg.bin post(command='sha1sum [copy]' stdout=wrtorg.remote.sha1)) post(command='diff wrtorg.local.sha1 wrtorg.remote.sha1' stdout=log)))" //// .Example 16 Binary copy of a file per SSH to a remote system, with checksum calculation over the local original file as pre-process and over the copied remote file as post process and a final post-processing which compares the check sums. This could be used for example to realize a receipt for a data transfer. ------------------------------------------------------------------------ flcl xcnv input(save.file( fio.blk(file=wrtorg.bin pre(command='sha1sum [copy]' stdout=wrtorg.local.sha1)) )) output(save.file( fio.blk(file=ssh://:limes@tests.limes.de/wrtorg.bin post(command='sha1sum [copy]' stdout=wrtorg.remote.sha1)) post(command='diff wrtorg.local.sha1 wrtorg.remote.sha1' stdout=log))) ------------------------------------------------------------------------ //// example 17 title=remote copy with post-processing to write MVS data set cmd=xcnv "input(save.file(fio.blk(file=wrtorg.bin))) output(save.file(fio.blk(file=ssh://:limes@zos22/wrtorg.bin postpro(command='cp -B [copy] "//TEST.XMIT([base])"') postpro(command='rm [copy]' on=success))))" //// .Example 17 Binary copy of a file per SSH to an IBM mainframe system with a post-processing which copies the file in a MVS data set and removes the copied file from USS on success. ------------------------------------------------------------------------ flcl xcnv input(save.file(fio.blk(file=wrtorg.bin))) output(save.file( fio.blk(file=ssh://:limes@zos22/wrtorg.bin postpro(command='cp -B [copy] "//TEST.XMIT([base])"') postpro(command='rm [copy]' on=success)))) ------------------------------------------------------------------------ //// example 18 title=copy multiple files, local or remote, into a PDS(E) on MVS cmd=CONV "READ.TEXT(FILE='/u//git/FL5/HASMMAC/*.mac' FILE='/u//git/FL5/HASMMAC/ZOS/*.mac' FILE='/u//git/FL5/HASMMAC/COLUMBUS/*.mac' CCSID=1140) WRITE.RECORD(FILE='.LICORDER.HASMMAC([base])' FALLOC(ORGA=LIB RECF=FB RECL=80 SPACE(PRIMARY=1 SECONDARY=1) RENEW) CCSID=1140) MESSAGE(MINIMAL)" //// .Example 18 Sometimes it is required to copy some directories from USS and/or a remote system to one (or more) PDS(E) on MVS. The following example is a job step that is part of FLAM5 license generation. This step copies assembler macros from three USS directories (IBM1140) to a PDSE on MVS which is required to assemble the license module. The library is newly created every time (RENEW (removes the DSN and re-allocates the library with `DISP=NEW`)). No preceding IEFBR14 step is required to delete the output dataset first. The example does something similar to what OGETX does, but with FLAM the input files could also be in UTF-8 on another system, if you use a URL and/or members in a ZIP archive and/or PGP encrypted. ------------------------------------------------------------------------ //COPYMAC EXEC PGM=FLCL,PARM='CONV=DD:PARM',REGION=0M //STEPLIB DD DSN=LIMES.FLAM.LOAD,DISP=SHR //SYSOUT DD SYSOUT=* //SYSPRINT DD SYSOUT=* //PARM DD * READ.TEXT(FILE='/u//git/FL5/HASMMAC/*.mac' FILE='/u//git/FL5/HASMMAC/ZOS/*.mac' FILE='/u//git/FL5/HASMMAC/COLUMBUS/*.mac' CCSID=1140) WRITE.RECORD(FILE='.LICORDER.HASMMAC([base])' FALLOC(ORGA=LIB RECF=FB RECL=80 SPACE(PRIMARY=1 SECONDARY=1) RENEW) CCSID=1140) MESSAGE(MINIMAL) /* ------------------------------------------------------------------------ //// example 19 title=use SYSOUT allocation to send email from MVS batch job cmd=CONV "read.record(file='.SCLM.FITSTOUT.*' ccsid=1141) write.text(method=unix ccsid='UTF-8' file='[copy].gz' FALLOC(SYSOUT(FORMAT.MAIL(FROM='@zos.limes.de' TO='system@flam.de'))) COMPRESS.GZIP())" //// .Example 19 This example is also used in our build, test and deploy automation and use the SYSOUT allocation of a mail writer on z/OS to send an email if anything is ready with the converted log as attached GZIP file. ------------------------------------------------------------------------ //FLCLMAIL EXEC PGM=FLCL,REGION=0M,PARM='CONV' //STEPLIB DD DSN=&SYSUID..AUTH.LOAD,DISP=SHR //SYSOUT DD SYSOUT=* //SYSPRINT DD SYSOUT=* //FLAMPAR DD * read.record(file='.SCLM.FITSTOUT.*' ccsid=1141) write.text(method=unix ccsid='UTF-8' file='[copy].gz' FALLOC(SYSOUT(FORMAT.MAIL( FROM='@zos.limes.de' TO='system@flam.de'))) COMPRESS.GZIP()) /* ------------------------------------------------------------------------ By default the CLASS='A' and the WRITER='CSSMTP' are used and additional it is possible to redirect the request with a remote workstation specification and a destination user ID to another LPAR. //// example 20 title=encrypt with OpenSSL-ENC cmd=xcnv "input(save.file(fio.blk(file='wrtorg.bin' frcblk))) output(save.file( cnv.edc(KDF=PBKDF2 ALGO=AES MODE=CBC KEYLEN=KL256 PASS=a'123456789012345678901234567890') fio.blk(file='wrtorg.bin.enc')))" //// .Example 20 To encrypt a backup with OpenSSL-ENC. ------------------------------------------------------------------------ flcl xcnv "input(save.file(fio.blk(file='wrtorg.bin' frcblk))) output(save.file( cnv.edc(KDF=PBKDF2 ALGO=AES MODE=CBC KEYLEN=KL256 PASS=a'123456789012345678901234567890') fio.blk(file='wrtorg.bin.enc')))" ------------------------------------------------------------------------ //// example 21 title=decrypt from OpenSSL-ENC cmd=xcnv "input(save.file(fio.blk(file='wrtorg.bin.enc' frcblk) cnv.edc(KDF=PBKDF2 ALGO=AES MODE=CBC KEYLEN=KL256 PASS=a'123456789012345678901234567890'))) output(save.file(fio.blk(file='wrtorg.bin')))" //// .Example 21 To decrypt an OpenSSL-ENC backup ------------------------------------------------------------------------ flcl xcnv "input(save.file(fio.blk(file='wrtorg.bin.enc' frcblk) cnv.edc(KDF=PBKDF2 ALGO=AES MODE=CBC KEYLEN=KL256 PASS=a'123456789012345678901234567890'))) output(save.file(fio.blk(file='wrtorg.bin')))" ------------------------------------------------------------------------ //// example 22 title=find datasets containing a certain pattern cmd=conv "READ.TEXT(FILE='HLQ.**' SUPTWS CCSID=DEFAULT CHRMODE=SUBSTITUTE REGEXP(PATTERN='^find$' NOCASE IGNREC)) WRITE.TEXT(FILE=DUMMY CCSID=LOCAL CHRMODE=SUBSTITUTE) DIR(LINK ALIAS HIDDEN RECURSIVE ARCHIVE) MESSAGE(MATCH,SOURCE)" //// .Example 22 Find datasets containing a certain pattern. ------------------------------------------------------------------------ //FIND EXEC PGM=FLCL,PARM='CONV',REGION=0M //STEPLIB DD DSN=LIMES.FLAM.LOAD,DISP=SHR //SYSOUT DD SYSOUT=* //SYSPRINT DD SYSOUT=* //FLAMPAR DD * READ.TEXT(FILE='HLQ.**' SUPTWS CCSID=DEFAULT CHRMODE=SUBSTITUTE REGEXP(PATTERN='^find$' NOCASE IGNREC)) WRITE.TEXT(FILE=DUMMY CCSID=LOCAL CHRMODE=SUBSTITUTE) DIR(LINK ALIAS HIDDEN RECURSIVE ARCHIVE) MESSAGE(MATCH,SOURCE) /* ------------------------------------------------------------------------ This example searches for the record with content 'find' in all datasets (PS/PO/VSAM) under the high level qualifier 'HLQ' (not case sensitive). A log message with the match count and the filename of each match is written to the log. The datasets can be record-oriented, with length fields in front of each record or with delimiter after each record. The datasets can be encoded, encrypted, compressed and/or in clear form. The search term is specified as regular expression. The output with the records found are written to the trash, but can also be written to SYSPRINT (FILE=STREAM) or to any other dataset (FILE='HLG.MY.FINDS'). ... print CLE_DOCTYP_CHAPTER === Supported Systems === Supported Systems FLAM is available for a variety of operating systems. For example: ------------------------------------------------------------------------ Platform: Operating System: x86 Linux, Windows, Solaris SPARC Solaris pSeries AIX, Linux zSeries z/OS (with a MVS and a USS variant), Linux ------------------------------------------------------------------------ ... print CLE_DOCTYP_CHAPTER === Technical Support === Technical Support FLAM support sites and other useful links: * use the link:../../index.html[start page] of our locally installed FLAM documentation * visit the up to date http://www.flam.de/en/technology/download/documentation[FLAM documentation] on our website * view examples of what you can do with FLAM inside link:../../flcc/index.html[FLCC] * to request support write a mail to * to report an issue go to our https://issues.flam.de[bug tracker] When reporting an issue it will help if the output of the command ------------------------- flcl info get.system ------------------------- is submitted too. This is the same as the *System Information* available in FLCC. ... print CLE_DOCTYP_CHAPTER == Command Line Parser [[clep.main]] == 1. Command Line Parser The COMMAND LINE PROCESSOR (CLE/P(R)) is a user application programming interface for several platforms including Windows, Unix and z/OS that simplifies and standardizes parameter string processing. The CLE/P(R) provides two separate functions: * COMMAND LINE PARSER (CLP) - Compiles a parameter string from a command to a data structure * COMMAND LINE EXECUTOR (CLE) - Supporting execution of different commands with parameter strings The COMMAND LINE EXECUTOR provides a list of commands and some built-in functions, please use <>, <> and <> to get extensive information about these capabilities. Additionally the built-in function <> can generate a complete or a part of the user manual. To read the parameter of a command, a compiler (CLP) is applied. To see the regular expressions (lexemes) and the corresponding grammar, please use the built-in functions <> and <>. The return/condition/exit codes of the executable and the reason codes of the different commands can be reviewed with the built-in function <>. See sections <> and, if available, <> for the meaning of the used return and reason codes. The CLE uses an owner management in order to separate the settings for different clients and a property management for each command. If problems occur, a trace might be activated. For each command execution the owner and environment variables can be defined in the configuration file. To see the current configuration use the built-in function <>. The default trace file is 'stdout'. If the trace is activated before a trace file is defined, the trace will be printed on the screen. To manage the tracing use built-in function <>. Last but not least it is possible to view the license, version and other information about the program. This is the RELEASE build version of the FLAMCLEP. ... print CLE_DOCTYP_CHAPTER === Command Line Considerations === 1.1. Command Line Considerations The command line parser supports abbreviation of keywords depending on the unique first characters. This is only useful if you work in dialog. If the command is specified in a persistent way (e.g. in a script) writing the complete keyword is recommended, to ensure that the script must not be changed to work with a later version of the program. For example: Version X supports only one keyword starting with V (VERSION). Version X+1, supports the keywords VERSION and VERIFY. If you use version X with VER=4711 anything is fine but with with version X+1 it will fail, because one more character is required (VERS=4711) for the keyword to be unique. The same is valid for the required string support. The CLP supports strings without enclosing. These strings depend on the keywords used in a name space. If new key words are added in future version, the string could cause errors and must be enclosed. Concerning this it is recommended to enclose strings if the command is defined in a script. For example: ------------------------------------------------------------------------ Version X: STRING=my/data/Name NUMBER=42 Version X+1 supports the new keyword NAME, this requires: STRING='my/data/Name' NUMBER=42 NAME='Hugo' ------------------------------------------------------------------------ The last item which could result in a damaged command syntax after a program update is the use of implicit array definitions after an assignment, because the end of such an array might change, for example if an array of numbers defined an a switch is the end. In a new version such a switch could be a number with a default value, if only the keyword is defined. In this case the defined number referenced by this keyword is then part of the number array and the parameter is lost. Concerning this it is recommended to use enclosed array definitions. For example: ------------------------------------------------------------------------ instead of: FLOATARRAY=1,2,3,PI use: FLOATARRAY[1,2,3,PI] ------------------------------------------------------------------------ All these capabilities are implemented to be compatible with several existing command lines syntaxes and to limit the effort to port old commands or to simplify the interactive use. But in certain cases, the command interpretation could fail, if not the unique/enclosed variant of keywords, strings and arrays are used. ... print CLE_DOCTYP_USEDENVAR === Used Environment Variables [[clep.main.usedenv]] === 1.2. Used Environment Variables Environment variables can be managed via the operating system or via the FLCL configuration. The latter can be managed with the built-in functions <>, <> and <>. To list the current state of all usable environment variables the built-in function <> can be used. For help messages for each usable environment variable please use <> There are also some platform-specific mechanisms that can be used to set environment variables: ..Linux, Windows, USS and other Unix-like OS Environment variables are read from the file `.stdenv` in the current working directory or the user's home directory. The file in the home directory is only considered if the file does not exist in the working directory or cannot be read. ..Mainframe systems `DD:STDENV` or the data set name `&SYSUID..STDENV` can alternatively be used to set environment variables. The `STDENV` file allows to define the `FLCL_CONFIG_FILE`, `FLCL_DEFAULT_OWNER_ID`, `LANG` and other environment variables in JCL. Example with a z/OS DD name allocation: ----------------------------------------------------------------------- //STDENV DD * FLCL_CONFIG_FILE=GLOBAL.FLCL.CONFIG LANG=de_DE.IBM-1141 HOME=/u/hugo USER=hugo ENVID=T /* ----------------------------------------------------------------------- The definition of the LANG variable outside of the program configuration file is recommended, so that the system character set is defined in each situation. The program configuration filename is used as is. No placeholder substitutions (e.g. ``) are possible. It might be useful to have a dedicated environment per user on mainframes. In such a case, it makes sense to define the environment in a dedicated file for each user. ----------------------------------------------------------------------- //STDENV DD DSN=USER.ENVIR(&SYSUID.), DSP=SHR ----------------------------------------------------------------------- Since z/OSv2r1 you can also use exported JCL symbols like environment variables. The exported JCL symbols have lower priority than the same environment variable. The service CEEGTJS is called dynamically and the language environment must be in the STEPLIB concatenation to use it. Additionally, all z/OS system symbols can be used in the string replacement (<&LDAY>). The environment variables have the highest priority, followed by the exported JCL symbols. System symbols have the lowest priority. If the variable name is not found, then no replacement is done and the angle brackets are kept in place. ------------------------------------------------------------------------ //E0 EXPORT SYMLIST=* //S1 SET BLKSIZE=27886 //S3 SET LRECL=128 ------------------------------------------------------------------------ ...Default record format For z/OS, the default record format and record length for non-existent output files is `recfm=VB, lrecl=516`. An attempt is made to open an existing file with `recfm=*` for overwriting (DISP=OLD). If this fails, another attempt is made with `recfm=VB, lrecl=516` to write a new file (DISP=NEW). The environment variable `CLP_DEFAULT_DCB` can be used to change this default file mode string. See "Keyword Parameters for File Mode" for fopen() in _z/OS XL C/C++ Runtime Library Reference_ for more information and for the correct syntax. Beside `recfm` with a valid record format (not + or *) and `lrecl`, the `space` parameter can be set. All other file mode parameters are managed by CLP. ..Property file vs. environment variables Beside all the environment variables managed by CLE it is possible to set all properties as environment variables to override the hard coded default values with CLP. If a property is defined as environment variable and in a property file, then the value in the property file overrides the setting in the environment. The environment variable name for each property is built by the rules below: * convert all characters to upper case * replace all dots (`.`) by underline (`_`) To get a list and help for all properties please use the built-in function `GENPROP` to generate property files. The properties can be defined per owner, per program and globally. The owner-specific definition overrides the program specific definition and the program-specific definition overrides the global definition. Examples: ----------------------------------------------------------------------- CONV_READ_TEXT_ENL2LF=OFF #in general the 0x15 to 0x25 conversion is off# HUGO_FLCL_CONV_READ_TEXT_ENL2LF=ON # for owner 'hugo' the conversion is on# ----------------------------------------------------------------------- The value string behind the sign (including the comment) will be used as supplement for the command line processor. Aliases are not supported in this case. You can only define properties for the main argument. If a string must be enclosed with apostrophe, please don't use double quotation marks because these are used in addition if a new property file is built based on the environment settings. ----------------------------------------------------------------------- FLCL_ICNV_FROM='IBM-1141' # this is the best solution FLCL_ICNV_TO=UTF-8 # "UTF-8" could result in errors ----------------------------------------------------------------------- See <> for the current property file content. ..Usable environment variables Below you can find the list of static environment variables. * LANG (&FLANGLC_&FLANGCC.&FLANGCS) - The default language and CCSID/encoding string for this platform (Format: de_DE.UTF-8 or de_DE.IBM-1141) * HOME - To determine the home directory on UNIX/WIN * USER - To determine the current user id on UNIX/WIN * CUSER - To determine the current user in upper case * Cuser - To determine the current user in title case * cuser - To determine the current user in lower case * SYSUID - To determine the current user id on z/OS * ENVID (&FLENVID) - The current environment qualifier for key label templates (default value is 'T' or the first valid letter of &SYSCLONE on z/OS) * OWNERID - Used for current owner if not already defined (used in key label templates (can also be used in file names)) * HOSTNAME - Current host name * MAILADDR - The email address used as sender for outgoing emails (only relevant on z/OS with SYSOUT format set to MAIL) * CLE_QUIET - Disables the normal log output of the command line executer (must set to YES or ON) ** YES - Yes, do it (same as ON) ** ON - Activate it (same as YES) ** NO - No, don't do it (same as OFF) ** OFF - Deactivate it (same as NO) * CLE_SILENT - Disables log and errors messages of the command line executer (must set to YES or ON) ** YES - Yes, do it (same as ON) ** ON - Activate it (same as YES) ** NO - No, don't do it (same as OFF) ** OFF - Deactivate it (same as NO) * CLP_NOW - The current point in time used for predefined constants (0tYYYY/MM/DD.HH:MM:SS) * CLP_STRING_CCSID - CCSID used for interpretation of critical punctuation character on EBCDIC systems (default is taken from LANG) * CLP_DEFAULT_DCB - The default record format and record length in C file mode format (default is 'recfm=VB, lrecl=516' only for z/OS) * CLP_SYMTAB_STATISTICS - Print symbol table statistics to STDERR stream at close (must set to YES or ON) ** YES - Yes, do it (same as ON) ** ON - Activate it (same as YES) ** NO - No, don't do it (same as OFF) ** OFF - Deactivate it (same as NO) * CLP_MALLOC_STATISTICS - Print memory allocation statistics to STDERR stream at close (must set to YES or ON) ** YES - Yes, do it (same as ON) ** ON - Activate it (same as YES) ** NO - No, don't do it (same as OFF) ** OFF - Deactivate it (same as NO) * FL_PLATFORM - Platform definition (WIN/UNX/MAC/ZOS/USS/BS2[.B/.L]) for emulation at read or write operations ** WIN - Choose Windows as platform (CRLF) ** UNX - Choose Unix derivative as platform (LF) ** ZOS - Choose ZOS as platform (NL) ** USS - Choose USS of ZOS as platform (NL) ** VSE - Choose VSE as platform (NL) ** BS2 - Choose BS2000-OSD as platform (NL) ** MAC - Choose MAC as platform (CR) * FL_DEFAULT_ASCII_CCSID - Default CCSID for ASCII character sets (if ASCII machine and LANG, then default is taken from LANG else default is 'ISO-8859-1')) * FL_DEFAULT_EBCDIC_CCSID - Default CCSID for EBCDIC character sets (if EBCDIC machine and LANG, then default is taken from LANG else default is 'IBM-1047')) * FL_PGP_PREF_SYMALG_AES128 (&FLPA128) - Invert order of preferred symmetric algorithms from AES256/192/128 to AES128/192/256 in PGP certificates ** YES - Yes, do it (same as ON) ** ON - Activate it (same as YES) ** NO - No, don't do it (same as OFF) ** OFF - Deactivate it (same as NO) * FL_ALLOW_LOW_ENTROPY - If defined and no source of entropy is available, the random number generate is seeded with a low entropy which may result in weak encryption keys * FL_DEFAULT_CHAR_MODE (&FLCHARM) - Default error handling if character not available in target character set [STOP] ** STOP - Stop at the first non-convertible character ** IGNORE - Ignore non-convertible characters ** SUBSTITUTE - Substitute non-convertible characters ** IDENTITY - Copy non-convertible characters (supported only for single byte conversions) ** TRANSLIT - Activate ICONV transliteration and ignore the rest (MODE=IGNORE SYSTAB=ICONV) * FL_DEFAULT_PGPCCAPARA - Default PGP IBM-CCA (ICSF) parameter (normally not required, only profile and pin (if applicable) or trust store name) * FL_DEFAULT_PGPP11PARA - Default PGP PKCS#11 parameter (LIB=/usr/lib/libsofthsm2,PIN=f'pkcs11.pin') * FL_DEFAULT_PGPRNGPARA - Default PGP key ring parameter (pub='pubrng.pgp',sec='secrng.pgp',pass=f'keyring.pwd') * FL_DEFAULT_CCALIB - Default path/name of CCA library (not required for ICSF) * FL_DEFAULT_CCAPKDS - Default path/name of CCA public key data set * FL_DEFAULT_P11LIB - Default path/name of PKCS#11 library * FL_DEFAULT_P11PIN - Default PIN/passphrase for PKCS#11 token (it is not recommended to use this if authentication is required) * FL_DEFAULT_P11SLOT - Default PKCS#11 slot number * FL_DEFAULT_RNGPUBFIL - Default public key file for key ring implementation * FL_DEFAULT_RNGSECFIL - Default secret key file for key ring implementation * FL_DEFAULT_RNGPASSWD - Default password for key ring implementation (it is not recommended to use this if authentication is required) * FL_INFO_BLOCK_SIZE - Set a custom block size for the INFO command (useful mainly for PGP files) * FL_USAGE_SYSLOG_IDENT (&FLOGIDT) - Activate usage logging to SYSLOG on each platform (in addition to the usage log stream on z/OS) * FL_DEACTIVATE_HW_CRYPTO_ACCELERATION - Deactivate hardware acceleration for cryptographic operations (enforce use of software implementation) * FL_PRIMARY_SPACE_TRK (&FLPRISP) - Default primary space in tracks (only relevant on mainframes, default is 600) * FL_SECONDARY_SPACE_TRK (&FLSECSP) - Default secondary space in tracks (only relevant on mainframes, default is 1200) * FL_DIRECTORY_BLOCKS (&FLDIRBL) - Default directory blocks (only relevant on mainframes, default is 45) * FL_ZEDC_SUPPORT (&FLZEDC) - Controls use of RCF1951 (GZIP) compression in FLAM4 ADC modules (ON, OFF, AUTO(default), threshold (nnn) in percent) * FL_SSH_HOME_DIR - Directory containing SSH key files and known_hosts file (/home/user/.ssh) * FL_GZ_EXPANSION_FACTOR (&FLGZEXP) - Expansion factor for GZIP decompression (default is 5) * FL_GZ_COMPRESSION_FACTOR (&FLGZCMP) - Compression factor for GZIP compression (default is 2) * FL_BZ_EXPANSION_FACTOR (&FLBZEXP) - Expansion factor for BZIP2 decompression (default is 6) * FL_BZ_COMPRESSION_FACTOR (&FLBZCMP) - Compression factor for BZIP2 compression (default is 2) * FL_XZ_EXPANSION_FACTOR (&FLXZEXP) - Expansion factor for XZ decompression (default is 10) * FL_XZ_COMPRESSION_FACTOR (&FLXZCMP) - Compression factor for XZ compression (default is 2) * FL_ZS_EXPANSION_FACTOR (&FLZSEXP) - Expansion factor for ZSTD decompression (default is 10) * FL_ZS_COMPRESSION_FACTOR (&FLSZCMP) - Compression factor for ZSTD compression (default is 2) * FL_KEY_EXPIRE_WARN_DAYS (&FLKEYWD) - Amount of days to warn before a key will expire (default is 90 (3 months)) * FL_RETURN_IF_LOG_WARNING (&FLRLOGW) - If set to OFF, the completion code 0 is returned instead of 1 if a relevant warning is written to the log ** YES - Yes, do it (same as ON) ** ON - Activate it (same as YES) ** NO - No, don't do it (same as OFF) ** OFF - Deactivate it (same as NO) * FL_FAVE_LIBRARY - Set default library for anti virus scanning (default is 'libfave') * FL_FAVE_FUNCTION - Set default function for anti virus scanning (default is 'CLAMAVC') * FL_FAVE_PARAMETER - Set default parameter for anti virus scanning (default is 'clamav.daemon:3310') * FL_CLAMAV_DAEMON - Set default communication parameter for ClamAV client (default is 'clamav.daemon:3310:10') * FL_AVSCAN_READ - If defined, anti virus scanning when reading is activated (corresponding default values must be defined) * FL_AVSCAN_WRITE - If defined, anti virus scanning when writing is activated (corresponding default values must be defined) * FL_AVSCAN_COMPRESS - If defined, anti virus scanning is done on a compressed GZIP data stream (must be supported by service provider) * FL_SYSOUT_MAIL_CLASS (&FLSOMC) - Default class for SYSOUT allocation if FORMAT.MAIL() is used (only on z/OS) * FL_SYSOUT_MAIL_WRITER (&FLSOMW) - Default program for SYSOUT allocation if FORMAT.MAIL() is used (only on z/OS) * FL_LITERAL_CACHE_SIZE (&FLITCS) - Size of the hash table used (by power of 2) for the literal cache (8>=x<=20 (256 to 1.048.576 entries)) * FL_RECORD_FORMAT_MAPPING (&FLRECFM) - If this variable is not set to DATATYPE (is the default), records with length field (RECF=VAR) are used ** DATATYPE - Binary data as binary (RECF=BIN), Text as text (RECF=TXT) * FL_IBM_UNICODE_SERVICE (&FLIBMUS) - Define use of z/OS Unicode Services for simple character conversions to lower performance [AUTO] ** AUTO - Use it, if behavior the same and faster ** ON - Activate it (with round trip conversion) ** OFF - Deactivate it (no use of Unicode Services) * FLAM4MF - Enable Microfocus Enterprise Server support for FLAM and FLUC record interfaces (ccsid/yes/no) * FLAM4MF_TRACEFILE - Enable a trace file for the MF-EDZ stubs supporting the record interface (Windows or Linux filename) * FLAM4MF_STATIC_SYSVAR - Static system variables are read from filename into the environment (filename in EBCDIC or ASCII, Syntax: 'SYMBOL=value', also use 'DD:SYSVAR') * FLAM4MF_DYNAMIC_SYSVAR - Dynamic system variables are read from filename into the environment (in conjunction with the JCL User Exit of MF-EDZ to add dynamic variables) * FL4SEPA_SIGFILE_PRIMARY_SPACE_TRK - Primary space of signature file for migration (if not defined the required space is determined from the used space of the old signature file) * FL4SEPA_SIGFILE_SECONDARY_SPACE_TRK - Secondary space of signature file for migration (if not defined the required space is determined from the used space of the old signature file)) * _EDC_ZERO_RECLEN (&FLZRECL) - Used for handling of empty records (see dedicated <> below) on z/OS Beside the static environment variables there a lot of dynamic formed environment variables supported. * FLCL_CONFIG_FILE - the configuration filename (default is '$HOME/.flcl.config' on UNIX/WIN or '&SYSUID..FLCL.CONFIG' on mainframes) * FLCL_DEFAULT_OWNER_ID - the default owner ID (default is 'limes') * owner_FLCL_command_PROPERTY_FILENAME - To override default property file names * path_argument - to override the hard coded default property value ..FLAM specific handling of environment variables On platforms (mainly mainframe systems) where system symbols are available, some of the environment variables can be pre-defined over corresponding system variables. See install.txt or use built-in function <> (in round brackets the corresponding system symbols are listed). Trailing whitespace is removed from variable values before being used. A system symbol must start with `&` or an alphabetic character followed by alphanumeric characters. ...Considerations for the LANG variable The environment variable LANG is also used on EBCDIC systems to interpret several syntax characters correctly, which depend on the codepage. See chapter <> for how the CCSID can be defined. It is important to set this variable to the correct value on EBCDIC systems. If this environment variable is not set, files and literals are interpreted in IBM-1047 on z/OS and USS. If you use another CCSID for entry, you must define the environment variable LANG to enable correct parsing for strings that contain special characters like `~`. We recommend to define the corresponding system variables (&FLANGLC, &FLANGCC and &FLANGCS) via `SYS1.PARMLIB(IEASYMxx)` on z/OS (see also install.txt). These three system symbols are used to build the environment variable LANG based on the string below: ------------------------------------------------------------------------ "&FLANGLC_&FLANGCC.&FLANGCS" ------------------------------------------------------------------------ For example with the definitions below ------------------------------------------------------------------------ SYMDEF(&FLANGLC='de') SYMDEF(&FLANGCC='DE') SYMDEF(&FLANGCS='IBM1141') ------------------------------------------------------------------------ the environment variable below is defined. ------------------------------------------------------------------------ LANG=de_DE.IBM1141 ------------------------------------------------------------------------ The language code (de) is important for correctly selecting the default CCSID if an ASCII code page was detected. ...Considerations for the ENVID variable The `ENVID` variable is normally one character to separate test and production environments. On z/OS the default is simply the first letter of system symbol `&SYSCLONE` or if not defined (on all platforms) 'T' for test. ...Considerations for the FLAM4MF variable family (only Microfocus Enterprise Server) The variable FLAM4MF and (if needed) FLAM4MF_TRACEFILE should be set in the environment of the Microfocus Enterprise Server instance where the FLAM or FLUC record interfaces are used. To define static and dynamic system variables, the FLAM4MF_STATIC/DYNAMIC_SYSVAR environment variable can be used to read the system variables to the environment. The second file was mainly introduce for the MF-EDZ JCL user exit, which can be used to provide the dynamic symbols like JOBNAME as keyword=value pair as the dynamic file. All the files read to build the environment undergo automatic ASCII and EBCDIC detection. A semicolon can be used to mark the end of a keyword-value pair (an inline FB80 encoding in JCL on EDZ does not contain new line characters). To undefine an environment variable, there must be no characters behind the equal sign. To replace a variable with nothing upon use, the environment variable must be set to one or more whitespace character(s). Trailing whitespace is removed from the value string, so a value which contains only whitespace characters will result in an empty string upon substitution. For Micro Focus EDZ environments, the DD name SYSVAR is supported to define system variables. The function used to read the `keyword=value` pairs automatically detects if EBCDIC is used (character > 0x80) and converts the lines automatically to the local character set. ...Other used system symbols on z/OS The LE-less part of FLAM can only use system symbols. Below is a list of available variables: *&FLREUCEE - Activate reuse of language environment in FLAM ZEDC support *&FLOGQL1 - First qualifier to specify the FLAM usage log stream name *&FLOGQL2 - Second qualifier to specify the FLAM usage log stream name *&FLOGQL3 - Third qualifier to specify the FLAM usage log stream name See install.txt for z/OS for more information. ...Other ways to define environment variables On Unix platforms the '/etc/profile' or .bashrc or command line can be used to export environment variables. On windows under system control global or user specific environment variables can be defined. On z/OS additional the DD:CEEOPTS can be used to define environment variables, see example for ZEDC usage below: ------------------------------------------------------------------------ //CEEOPTS DD * ENVAR("_HZC_COMPRESSION_METHOD=software, _HZC_DEFLATE_THRESHOLD=1, _HZC_INFLATE_THRESHOLD=1") /* ------------------------------------------------------------------------ Additional with global relevance the environment variables can also be defined over the PARMLIB member CEEPRMxx on z/OS, see examples for all 3 environments below: ------------------------------------------------------------------------ CEECOPT(ALL31(ON), ENVAR('TZ=EST5EDT') ) CEEDOPT(ALL31(ON), ENVAR('TZ=EST5EDT') ) CELQDOPT(ALL31(ON), ENVAR('TZ=EST5EDT') ) ------------------------------------------------------------------------ from 'Specifying environment variables' of IBM z/OS documentation. ... print CLE_DOCTYP_CHAPTER === Environment Variable Mapping === 1.3. Environment Variable Mapping Each value enclosed with angle brackets (`<>`) are replaced with the corresponding environment variable (``). This feature is available at each starting point of a lexeme and inside of a normal string. If the environment variable not defined the replacements below are still possible: * - Current user id in upper case * - Current user id (case sensitive) * - Current user id in upper case == * - Current user id in title case * - Current user id in lower case * - The current host name of the system * - The environment ID (default is T for test) * - Replaces with the users data directory, if this not available the replacements below are done: ** On UNIX with /home/ ** On USS with /u/ ** On ZOS with Additional few abbreviation are supported for different kind of strings. * '~' for in file strings * '!' for in key labels * '~' for in key labels * '^' for in key labels All these abbreviation character have different code points in EBCDIC code pages and can only be used if the CCSID known be CLP, see chapter <> how the CCSID can be defined for CLP. ... print CLE_DOCTYP_CHAPTER === Filename Mapping [[clep.main.filemap]] === 1.4. Filename Mapping All filenames used by CLE/P(R) are additionally mapped based on the rules below: * The tilde character (`~`) is replaced with the string `` * DD names on mainframes must be prefixed with "DD:" * Data set names on mainframes are always fully qualified * Path names on mainframes must contain at least one slash (`/`) * Data set names on USS must start with `//` ** Fully qualified names with HLQ must be enclosed in apostrophes (`//''`) ** If apostrophes are not used the SYSUID is prefixed as HLQ * Normal file names on other platforms could be relative NOTE: If a requested environment variable is not defined, the replacement is done with the empty string. This can result in unexpected behavior. To use a "<" or "~" as a part of a filename the character must be specified twice. Beside this rules the replacement technologies of your shell can be used, but on some platforms $HOME, $USER or something similar might not be available, for such cases the possibilities above are implemented. This file name mapping is provided by the library CLEPUTL and should also be used for file names managed by the commands supported with this program. ... print CLE_DOCTYP_CHAPTER === Key Label Mapping === 1.5. Key Label Mapping The key label name mapping works like the file name mapping, but you can additional use `^` to replace it with the OWNERID (`^=`), `!` to replace it with the environment identifier (`!=`) and `~` is only replaced with login user id. If the environment ID not defined then `T` for test is used by default. ... print CLE_DOCTYP_CHAPTER === Special EBCDIC Codepage Support [[CLEP.MAIN.EBCDIC]] === 1.6. Special EBCDIC Codepage Support To interpret commands correctly the punctuation characters below are on different code points depending on the EBCDIC CCSID used to enter these values. ------------------------------------------------------------------------ CRITICAL PUNCTUATION CHARACTERS: ! $ # @ [ \\ ] ^ ` { | } ~ ------------------------------------------------------------------------ These critical characters are interpreted normally dependent on the environment variable LANG. If the environment variable LANG is not defined then the default CCSID IBM1047 (Open Systems Latin-1) is used. Below is the current list of supported CCSIDs on EBCDIC systems. ------------------------------------------------------------------------ SUPPORTED EBCDIC CODE PAGES FOR COMMAND ENTRY: "IBM-1140","IBM-1141","IBM-1142","IBM-1143", "IBM-1144","IBM-1145","IBM-1146","IBM-1147", "IBM-1148","IBM-1149","IBM-1153","IBM-1154", "IBM-1156","IBM-1122","IBM-1047","IBM-924", "IBM-500","IBM-273","IBM-037","IBM-875","IBM-424", "IBM-277","IBM-278","IBM-280","IBM-284","IBM-285", "IBM-297","IBM-871","IBM-870","IBM-1025","IBM-1112", "IBM-1157" ------------------------------------------------------------------------ You can define the code page explicitly (LANG=de_DE.IBM-1141) or only the language code (LANG=de_DE, LANG=C). If only the language code defined then the CCSID is derived from the language code (DE=IBM-1141, US=IBM-1140, C=IBM-1047, ...). If possible, these critical characters are also converted for print outs. At output it is not possible to convert anything correctly, because some strings for print out are coming from other sources (like system messages and others). Only all known literals are converted, for unknown variables such a conversion is not possible and CLE/P(R) expects that such strings are encoded in the correct system code page, but there is no guaranty for this. To be independent of the environment escaping of the CLP strings is possible for the critical punctuation characters on EBCDIC systems. See list below: ------------------------------------------------------------------------ ! = &EXC; - Exclamation mark $ = &DLR; - Dollar sign # = &HSH; - Hashtag (number sign) @ = &ATS; - At sign [ = &SBO; - Square bracket open \ = &BSL; - Backslash ] = &SBC; - Square bracket close ^ = &CRT; - Caret (circumflex) ` = &GRV; - Grave accent { = &CBO; - Curly bracket open | = &VBR; - Vertical bar } = &CBC; - Curly bracket close ~ = &TLD; - Tilde ------------------------------------------------------------------------ A escape sequence starts with the ampersand (&) followed be 3 character (not case sensitive) and is terminated with semicolon (;). With an X and 2 hexadecimal digit the definition of a binary byte value are possible. If such a sequence in the string required then the ampersand must be typed twice (&&). To mark a part or the of whole string in a certain CCSID the escape sequence must contain 1 to 6 digits. Few samples can be found below: ------------------------------------------------------------------------ &1047; all in 1047 &0; reset to system code page &1140; no in 1140 ------------------------------------------------------------------------ At the beginning the system code page is active except the environment variable CLP_STRING_CCSID is defined. The defined CCSID is valid till the next CCSID definition. An unsupported CCSID (0) can be used to restore the interpretation to the system code page. NOTE: This is no character set conversion, only the UNICODE code points 0-127 which are on different code points in the different EBCDIC code pages are replaced. All other higher code points (e.g. German Umlauts ('รค','รผ','รถ')) are not touched. The partial CCSID conversion are mainly useful for application programming interfaces. At compile time the CCSID for literals must be defined. This CCSID could be differ from the system CCSID (local character set) of variable parameter. In such a case a application can mark the literal part in the CCSID used for literals at compile time, and the variable part could be conform to the CCSID defined over the LANG variable. See the C example below: ------------------------------------------------------------------------ snprintf(acCmd,sizeof(acCmd),"&1047;get.file='&0;%s&1047'",pcFilename); ------------------------------------------------------------------------ C-Code are normally in 1047 and if no literal conversion defined then the literals also in 1047. The file name is a parameter in local character set. In Cobol the default code page for literals is 1140. To define the CCSID for CLP strings from outside, the environment variable CLP_STRING_CCSID can be defined. This is useful if an application cannot recompile with the correct code page for the literals. On ASCII/UTF-8 platforms a miss-interpretation of punctuation characters smaller than 128 is not possible. On such platforms the LANG variable is not used for command interpretation or printouts. The escape and CCSID sequences are supported but have no effect on these platforms. This helps to develop platform independent code for CLP strings. ... print CLE_DOCTYP_BUILTIN == Built-in Functions [[CLEP.BUILTIN.FUNCTIONS]] == 2. Built-in Functions Numerous built-in functions are available to obtain extensive help about syntax, errors, commands and functions of a program with help messages, manual pages and documentation. Other built-in functions can be used for owner, property, environment and trace management. All built-in functions have the purpose to simplify handling of powerful and sometimes complex commands. [[CLEP.BUILTIN.SYNTAX]] === 2.1. Function 'SYNTAX' .Synopsis ----------------------------------------------------------------------- HELP: Provides the syntax for each command PATH: limes.flcl TYPE: BUILT-IN FUNCTION SYNTAX: > flcl SYNTAX [command[.path] [DEPTH1 | ... | DEPTH9 | ALL]] ----------------------------------------------------------------------- .Description The syntax function shows how the arguments can be set on the command line. Depending on depth the syntax is printed in one line or in structured form. A structured print out means that you have a question or exclamation mark before the argument. * question mark - optional parameter * exclamation mark - required parameter The *path* is a dotted keyword list in accordance with the syntax of the corresponding command. ------------------------------------------------------------------------ command.para1.para2.para3 ------------------------------------------------------------------------ .Options * DEPTH1 / DEPTH2 / ... / DEPTH9 ** Specifies the depth of the output. Default is DEPTH1. If the depth is greater than 1 the structured print out is used. * ALL ** Shows complete syntax for the specified path, not just DEPTH1. Structured print out is used. .Examples ----------------------------------------------------------------------- :> FLCL SYNTAX :> FLCL SYNTAX command :> FLCL SYNTAX command ALL :> FLCL SYNTAX command.para :> FLCL SYNTAX command.para ALL ----------------------------------------------------------------------- [[CLEP.BUILTIN.HELP]] === 2.2. Function 'HELP' .Synopsis ----------------------------------------------------------------------- HELP: Provides quick help for arguments PATH: limes.flcl TYPE: BUILT-IN FUNCTION SYNTAX: > flcl HELP [command[.path] [DEPTH1 | ... | DEPTH9 | ALL]] [MAN] ----------------------------------------------------------------------- .Description The help function can provide extensive information about each parameter which is adjustable on the command line. With the help functionality you get a structured list of arguments: * keyword - the keyword for the argument * (TYPE: ...) - the type of this argument * help message - the short help text * (PROPERTY: [...]) - the current hard coded property value (optional) The keyword can be abbreviated, but it must be unique for this list. The required letters are upper case if case sensitive mode is used. With the case sensitive mode an additional line is required to mark the appropriate letter. The *path* is a dotted keyword list in accordance with the syntax of the corresponding command. ------------------------------------------------------------------------ command.para1.para2.para3 ------------------------------------------------------------------------ Help can also be used to show the corresponding detailed description of the manual pages with keyword *MAN*. .Options * DEPTH1 / DEPTH2 / ... / DEPTH9 ** Specifies the depth of the output. Default is DEPTH1. * ALL ** Shows complete help below specified path, not just DEPTH1 and includes all aliases defined for a certain argument. * MAN ** Shows additionally the detailed description for this program, command or parameter and the next level of arguments including the aliases. .Examples ----------------------------------------------------------------------- :> FLCL HELP :> FLCL HELP MAN :> FLCL HELP command :> FLCL HELP command MAN :> FLCL HELP command ALL :> FLCL HELP command.para :> FLCL HELP command.para MAN :> FLCL HELP command.para ALL ----------------------------------------------------------------------- [[CLEP.BUILTIN.MANPAGE]] === 2.3. Function 'MANPAGE' .Synopsis ----------------------------------------------------------------------- HELP: Provides manual pages (detailed help) PATH: limes.flcl TYPE: BUILT-IN FUNCTION SYNTAX: > flcl MANPAGE [function | command[.path][=filename]] | [filename] ----------------------------------------------------------------------- .Description Shows the manpages of the program, all commands and built-in functions and if available for each argument up to selections/constant definitions. This function prints the corresponding section from the user manual on the screen (doctype: *book*). If a filename is given then the doctype *manpage* of ASCIIDOC is written to the file. Do not use space characters between the key, assignment character (=) and filename. The files in ASCIIDOC format can be used to generate manpages with the tool http://www.methods.co.nz/asciidoc/[ASCIIDOC]. .Examples ----------------------------------------------------------------------- :> FLCL MANPAGE :> FLCL MANPAGE filename :> FLCL MANPAGE command :> FLCL MANPAGE command=filename :> FLCL MANPAGE function :> FLCL MANPAGE function=filename :> FLCL MANPAGE command.para :> FLCL MANPAGE command.para=filename ----------------------------------------------------------------------- [[CLEP.BUILTIN.GENDOCU]] === 2.4. Function 'GENDOCU' .Synopsis ----------------------------------------------------------------------- HELP: Generates auxiliary documentation (ASCIIDOC text format) PATH: limes.flcl TYPE: BUILT-IN FUNCTION SYNTAX: > flcl GENDOCU [command[.path]=]filename [NONBR] [SHORT] ----------------------------------------------------------------------- .Description The complete user manual is generated when only the filename is given. If a command, or command path, is specified the corresponding section of the user manual is written to a file. The generated files are in ASCIIDOC format, to be readable as normal text document on all platforms and easily convertible into HTML, PDF or other formats with http://www.methods.co.nz/asciidoc/[ASCIIDOC]. The example below generates the complete manual and convert it in a second step to a HTML5 document. ------------------------------------------------------------------------ :> flcl gendocu book.txt :> asciidoc -b html5 -f asciidoc-html5.conf -a toc2 -a toclevels=4 -o book.html book.txt ------------------------------------------------------------------------ The numbering will vary in places where the complete manual uses a bullet list for arguments and constants, when no detailed description is available and some of these arguments are required for the path. The numbering can be disabled by setting the optional keyword NONBR. This is useful if numbering is generated by a post processing utility (for example 'pdflatex'). To create a short manual without the CLP parameter description the optional keyword SHORT can be used. This is useful for example, if you deliver a text file and no dictionary can be used. In opposite to the built-in function <> at text file generation the corresponding path string is written to the synopsis but index chapter and index terms are not generated anymore. Do not use space characters between the key, assignment character (=) and filename. .Examples ----------------------------------------------------------------------- :> FLCL GENDOCU flcl.manual.txt NONBR :> FLCL GENDOCU flcl.manual.txt SHORT :> FLCL GENDOCU command=command.manual.txt :> FLCL GENDOCU command.argument=argument.manual.txt ----------------------------------------------------------------------- [[CLEP.BUILTIN.HTMLDOC]] === 2.5. Function 'HTMLDOC' .Synopsis ----------------------------------------------------------------------- HELP: Generates the complete HTML documentation into a folder PATH: limes.flcl TYPE: BUILT-IN FUNCTION SYNTAX: > flcl HTMLDOC [path] [NUMBERS] [TYPES] [SHORT] ----------------------------------------------------------------------- .Description This built-in function generates the complete user manual in HTML format into a folder. The folder can be defined as optional parameter. If no path given, then the current directory is used as default. With the optional keyword `NUMBERS` the numbering of headlines can be activated. The keyword `TYPE` add the type information to each generated headline. The keyword `SHORT` will result in a short version of the document, not containing the parameter of the commands and other CLP strings. In opposite to the built-in function <> at HTML generation no path is written to the synopsis but index terms are generated by default. The built-in function can only be used if a call back function for HTML documentation provided. If not a error will be issued if HTMLDOC is executed. The callback function is called for each prepared page and the unique pointer to the original manual string can be used to determine if this page already created and if so then only a link to this existing page is required. This interface allows to generated more flexible (with dictionary, index, search) and redundancy free HTML documentation. To understand the service provider interface (open, close and callback function) for HTML generation see the DOXYGEN documentation of FLAMCLE/CLP.h .Examples ----------------------------------------------------------------------- :> FLCL HTMLDOC :> FLCL HTMLDOC . SHORT :> FLCL HTMLDOC /user/home/docu/flclbook :> FLCL HTMLDOC NUMBERS SHORT :> FLCL HTMLDOC /user/home/docu/flclbook SHORT ----------------------------------------------------------------------- [[CLEP.BUILTIN.GENPROP]] === 2.6. Function 'GENPROP' .Synopsis ----------------------------------------------------------------------- HELP: Generates a property file PATH: limes.flcl TYPE: BUILT-IN FUNCTION SYNTAX: > flcl GENPROP [command=]filename ----------------------------------------------------------------------- .Description A property file is generated for all commands if only a filename is provided. If a command is specified, a property file for this specific command is created. Property files can be used to define default settings for commands. For each parameter, a property entry is written to a text file. The text file contains comments to help in editing the properties. A property file can be activated with the built-in function SETPROP. Property files will be activated by their owner. A property file overrides hard coded properties and properties defined over environment variables. A specific property file overrides the general property file. At time of generation all current default settings are written to the property file. We recommend to work only with command specific property files, because the built-in function CHGPROP can be used to generate, update and activate a property file for a certain command. Do not use space characters between the key, assignment character (=) and filename. To optimize the program performance, one can remove all unnecessary properties. See <> for the current property file content. .Examples ----------------------------------------------------------------------- :> FLCL GENPROP owner.general.properties :> FLCL GENPROP command=owner.command.properties ----------------------------------------------------------------------- [[CLEP.BUILTIN.SETPROP]] === 2.7. Function 'SETPROP' .Synopsis ----------------------------------------------------------------------- HELP: Activate a property file PATH: limes.flcl TYPE: BUILT-IN FUNCTION SYNTAX: > flcl SETPROP [command=]filename ----------------------------------------------------------------------- .Description The filename is set as current global property file when no command is specified. The file name is set as current local property file when a command is given. The property file can be generated with GENPROP and will be activated for the current owner. After generation you can activate the property file, but there will be no effect until you change the settings inside the property file, because the current default settings are written. The filename can contain replacement/mapping rules (/). Do not use space characters between the key, assignment character (=) and filename. We recommend to work only with command specific property files, because the built-in function CHGPROP can be used to generate, update and activate a property file for a certain command. See <> for the current property file content. .Examples ----------------------------------------------------------------------- :> FLCL SETPROP general.properties :> FLCL SETPROP command=command.properties ----------------------------------------------------------------------- [[CLEP.BUILTIN.CHGPROP]] === 2.8. Function 'CHGPROP' .Synopsis ----------------------------------------------------------------------- HELP: Change a property value in the currently active property file PATH: limes.flcl TYPE: BUILT-IN FUNCTION SYNTAX: > flcl CHGPROP command [path[=value]]* ----------------------------------------------------------------------- .Description The built-in function updates property values in the currently active (see <>) property file for a dedicated command. If no property file is activated, a property file is generated (see <>), updated with the provided property list and activated (see <>). The first argument of CHGPROP is the command name. All other arguments are key-value pairs of properties that should be updated. The key is internally prefixed with the root (owner.program.command.). The values are enclosed in double quotation marks. Multiple properties of a command can be updated at once by separating them with a space character (please do not use spaces between key, assignment character (=) and the value). This set of properties is parsed by the CLP. If no property is provided, the property file for the command is either parsed or generated (if it does not exist) and then activated without updating properties. This behavior can be used to generate and activate command specific property files for the different commands. The built-in function reads and parses the currently active property file. Then it parses the provided property list and writes the updated property file back to disk. The currently active property file could be a global, not command specific property file. In such a case, a new command specific property file is generated and activated. Properties from the global property file are copied into the newly generated one. If no property file is defined (see <>) that corresponds to the owner, program and command, a property file is generated. The filename formats below are used to read or write property files from/to the home directory: On non-mainframe systems (WINDOWS, UNIX, MAC): ------------------------------------------------------------------------ ".owner.program.command.properties" ------------------------------------------------------------------------ On mainframe systems (ZOS, VSE, BS200, ...): ------------------------------------------------------------------------ ".OWNER.PROGRAM.COMMAND.PROPS" ------------------------------------------------------------------------ If the default filenames and/or path are not sufficient, you can change the filename of each property file by setting environment variables using the following naming convention: ------------------------------------------------------------------------ OWNER_PROGRAM_COMMAND_PROPERTY_FILENAME ------------------------------------------------------------------------ If no home directory is defined, then the current working directory is used as default directory to save the property files. On mainframes SYSUID is used for the first level qualifier, to represent the "home directory". Property files are managed per owner: This means that updates are only done for the current owner. To delete a property you can simply specify the path without the root and with out a sign. See <> for the current property file content. .Examples ----------------------------------------------------------------------- :> FLCL CHGPROP command overlay.object.argument=value :> FLCL CHGPROP command overlay.object.argument :> FLCL CHGPROP command object.argument=value1 argument=value2 ----------------------------------------------------------------------- [[CLEP.BUILTIN.DELPROP]] === 2.9. Function 'DELPROP' .Synopsis ----------------------------------------------------------------------- HELP: Remove a property file from configuration PATH: limes.flcl TYPE: BUILT-IN FUNCTION SYNTAX: > flcl DELPROP [command] ----------------------------------------------------------------------- .Description Without a command the current global property file is deleted from the configuration data. A command specific property file can be deleted from the configuration data when the command name is given. Property files are managed per owner, this means that delete is only done for the current owner. We recommend to work only with command specific property files. See <> for the current property file content. .Examples ----------------------------------------------------------------------- :> FLCL DELPROP :> FLCL DELPROP command ----------------------------------------------------------------------- [[CLEP.BUILTIN.GETPROP]] === 2.10. Function 'GETPROP' .Synopsis ----------------------------------------------------------------------- HELP: Show current properties PATH: limes.flcl TYPE: BUILT-IN FUNCTION SYNTAX: > flcl GETPROP [command[.path] [DEPTH1 | ... | DEPTH9 | DEPALL | DEFALL]] ----------------------------------------------------------------------- .Description All or certain properties can be shown for a dedicated path. The *path* is a dotted keyword list according to the syntax of the corresponding command. ------------------------------------------------------------------------ command.para1.para2.para3 ------------------------------------------------------------------------ A help message for a certain parameter will also show the assigned property value. See <> for the current property file content. .Options * `DEPTH1 / DEPTH2 / ... / DEPTH9` ** Specifies the depth of the output. Default is DEPTH1. * `DEPALL` ** Shows all properties to the specified path, not just DEPTH1. * `DEFALL` ** Shows all defined properties to the specified path. .Examples ----------------------------------------------------------------------- :> FLCL GETPROP :> FLCL GETPROP command :> FLCL GETPROP command DEFALL :> FLCL GETPROP command.para :> FLCL GETPROP command.para DEPALL ----------------------------------------------------------------------- [[CLEP.BUILTIN.SETOWNER]] === 2.11. Function 'SETOWNER' .Synopsis ----------------------------------------------------------------------- HELP: Defines the current owner PATH: limes.flcl TYPE: BUILT-IN FUNCTION SYNTAX: > flcl SETOWNER name ----------------------------------------------------------------------- .Description The current owner id (prefix or separation) can be changed. The owner concept is very powerful to separate different property settings. You can run the same command with different properties simply by switching the owner. The owner is a general solution to separate all settings and can be used for environment, client and other purposes. If not already defined, the owner is written to the environment table under the key word OWNERID. This environment variable can for example used as replacement in file names (~/.dat) or to refer a signature key. .Examples ----------------------------------------------------------------------- :> FLCL SETOWNER com.company ----------------------------------------------------------------------- [[CLEP.BUILTIN.GETOWNER]] === 2.12. Function 'GETOWNER' .Synopsis ----------------------------------------------------------------------- HELP: Show current owner setting PATH: limes.flcl TYPE: BUILT-IN FUNCTION SYNTAX: > flcl GETOWNER ----------------------------------------------------------------------- .Description The current owner id (prefix for separation) will be shown. The owner concept allows to manage different configurations as a logical separation of what is done with this id. .Examples ----------------------------------------------------------------------- :> FLCL GETOWNER ----------------------------------------------------------------------- [[CLEP.BUILTIN.SETENV]] === 2.13. Function 'SETENV' .Synopsis ----------------------------------------------------------------------- HELP: Set an environment variable (defined in the config file) PATH: limes.flcl TYPE: BUILT-IN FUNCTION SYNTAX: > flcl SETENV variable=value ----------------------------------------------------------------------- .Description This function allows to set environment variables within the configuration file for a certain owner. All defined environment variables are placed in the current environment table of the process before a command is executed. Do not use space characters between the key, assignment character (=) and value. *Attention:* The environment variables will be temporary overwritten .Examples ----------------------------------------------------------------------- :> FLCL SETENV LANG=DE_DE.IBM-1141 :> FLCL SETENV LANG=DE_DE.UTF-8 :> FLCL SETENV ENVID=T :> FLCL SETENV ENVID=P ----------------------------------------------------------------------- [[CLEP.BUILTIN.GETENV]] === 2.14. Function 'GETENV' .Synopsis ----------------------------------------------------------------------- HELP: Show the environment variables (defined in the config file) PATH: limes.flcl TYPE: BUILT-IN FUNCTION SYNTAX: > flcl GETENV ----------------------------------------------------------------------- .Description This function lists all environment variables which are set within the configuration file for a certain owner. All shown environment variables are placed in the environment table of the process. *Attention:* The environment variables will be temporary overwritten .Examples ----------------------------------------------------------------------- :> FLCL GETENV ----------------------------------------------------------------------- [[CLEP.BUILTIN.DELENV]] === 2.15. Function 'DELENV' .Synopsis ----------------------------------------------------------------------- HELP: Delete an environment variable (defined in the config file) PATH: limes.flcl TYPE: BUILT-IN FUNCTION SYNTAX: > flcl DELENV variable ----------------------------------------------------------------------- .Description This function will delete environment variables from the configuration file for a certain owner. .Examples ----------------------------------------------------------------------- :> FLCL DELENV LANG ----------------------------------------------------------------------- [[CLEP.BUILTIN.LSTENV]] === 2.16. Function 'LSTENV' .Synopsis ----------------------------------------------------------------------- HELP: List status of all possible usable environment variables PATH: limes.flcl TYPE: BUILT-IN FUNCTION SYNTAX: > flcl LSTENV ----------------------------------------------------------------------- .Description This function will list the status of all possible useable environment variables. .Examples ----------------------------------------------------------------------- :> FLCL LSTENV ----------------------------------------------------------------------- [[CLEP.BUILTIN.HLPENV]] === 2.17. Function 'HLPENV' .Synopsis ----------------------------------------------------------------------- HELP: List help message for all possible usable environment variables PATH: limes.flcl TYPE: BUILT-IN FUNCTION SYNTAX: > flcl HLPENV ----------------------------------------------------------------------- .Description This function will print the help message for all possible usable environment variables. .Examples ----------------------------------------------------------------------- :> FLCL LSTENV ----------------------------------------------------------------------- [[CLEP.BUILTIN.TRACE]] === 2.18. Function 'TRACE' .Synopsis ----------------------------------------------------------------------- HELP: Manage trace capabilities PATH: limes.flcl TYPE: BUILT-IN FUNCTION SYNTAX: > flcl TRACE ON | OFF | FILE=filename ----------------------------------------------------------------------- .Description Tracing for command line parser and commands can be enabled or disabled. A trace is only required to diagnose errors. In such a case a trace file must be defined first, then the trace can be activated, the erroneous command executed and the trace file sent to the support team. If no trace file is defined, stdout/stderr is used as default. To prevent tracing on the screen, please define a trace file first before tracing is switched on. Do not use space characters between the key, assignment character (=) and filename. .Examples ----------------------------------------------------------------------- :> FLCL TRACE FILE=filename :> FLCL TRACE ON :> FLCL TRACE OFF ----------------------------------------------------------------------- [[CLEP.BUILTIN.CONFIG]] === 2.19. Function 'CONFIG' .Synopsis ----------------------------------------------------------------------- HELP: Shows or clear all the current configuration settings PATH: limes.flcl TYPE: BUILT-IN FUNCTION SYNTAX: > flcl CONFIG [CLEAR] ----------------------------------------------------------------------- .Description The actual configuration list with owner id, property file names trace setting, environment variables and more is shown. With the option CLEAR the configuration data including the corresponding file will be deleted. The configuration file name can be defined by the environment variable: ------------------------------------------------------------------------ FLCL_CONFIG_FILE=config.file.name ------------------------------------------------------------------------ This can be used to work with a global configuration file. If this location is not defined, the configuration file is stored in the home directory with the name: ------------------------------------------------------------------------ .flcl.config ------------------------------------------------------------------------ If no home directory is defined for the current user (this case is very improbable), the working directory is used. To read the configuration file when the environment variable above is not defined, CLE first looks in the working and then in the home directory. This makes it possible to prefer a property file, by copying it to the current working directory. On mainframes the data set name 'SYSUID.FLCL.CONFIG' is used as default. SYSUID as high level qualifier is a kind of replacement for the current home directory in other operating systems in this way. .Examples ----------------------------------------------------------------------- :> FLCL CONFIG :> FLCL CONFIG CLEAR ----------------------------------------------------------------------- [[CLEP.BUILTIN.GRAMMAR]] === 2.20. Function 'GRAMMAR' .Synopsis ----------------------------------------------------------------------- HELP: Shows the grammar for commands and properties PATH: limes.flcl TYPE: BUILT-IN FUNCTION SYNTAX: > flcl GRAMMAR ----------------------------------------------------------------------- .Description The grammar used for interpreting the command line and property files is shown. This is helpful for understanding how the commands and property files are interpreted by the command line processor. See <> for an explanation and the output of this command. .Examples ----------------------------------------------------------------------- :> FLCL GRAMMAR ----------------------------------------------------------------------- [[CLEP.BUILTIN.LEXEMES]] === 2.21. Function 'LEXEMES' .Synopsis ----------------------------------------------------------------------- HELP: Shows the regular expressions accepted in a command PATH: limes.flcl TYPE: BUILT-IN FUNCTION SYNTAX: > flcl LEXEMES ----------------------------------------------------------------------- .Description The regular expression used for the tokens of the command syntax will be shown. This could be helpful in understanding how the commands and property files are interpreted by the command line processor. Moreover it will be shown how to define a number, a string, a keyword and other values inside a command. See <> for an explanation and the output of this command. .Examples ----------------------------------------------------------------------- :> FLCL LEXEMES ----------------------------------------------------------------------- [[CLEP.BUILTIN.LICENSE]] === 2.22. Function 'LICENSE' .Synopsis ----------------------------------------------------------------------- HELP: List license information for the program PATH: limes.flcl TYPE: BUILT-IN FUNCTION SYNTAX: > flcl LICENSE ----------------------------------------------------------------------- .Description The license string of the software product is shown. This string is provided to the command line executer (CLE) by the calling program and should reflect the current license text for this program. .Examples ----------------------------------------------------------------------- :> FLCL LICENSE ----------------------------------------------------------------------- [[CLEP.BUILTIN.VERSION]] === 2.23. Function 'VERSION' .Synopsis ----------------------------------------------------------------------- HELP: List version information for the program PATH: limes.flcl TYPE: BUILT-IN FUNCTION SYNTAX: > flcl VERSION ----------------------------------------------------------------------- .Description The version of the software product is shown. This string is provided to the command line executer (CLE) by the calling program and should reflect the current version information for this program. See <> for the output of this command. .Examples ----------------------------------------------------------------------- :> FLCL VERSION ----------------------------------------------------------------------- [[CLEP.BUILTIN.ABOUT]] === 2.24. Function 'ABOUT' .Synopsis ----------------------------------------------------------------------- HELP: Show information about the program PATH: limes.flcl TYPE: BUILT-IN FUNCTION SYNTAX: > flcl ABOUT ----------------------------------------------------------------------- .Description Shows information about the software product like version, copyright, external libraries, license and other attributes. This string is provided to the command line executer (CLE) by the calling program and should reflect the current about information for this program (flcl). See <> for the output of this command. .Examples ----------------------------------------------------------------------- :> FLCL ABOUT ----------------------------------------------------------------------- [[CLEP.BUILTIN.ERRORS]] === 2.25. Function 'ERRORS' .Synopsis ----------------------------------------------------------------------- HELP: Show information about return and reason codes of the program PATH: limes.flcl TYPE: BUILT-IN FUNCTION SYNTAX: > flcl ERRORS ----------------------------------------------------------------------- .Description This built-in function prints explanations for the return/condition/exit codes of the executable and, if available, the reason codes of executed commands. The command line executer (CLE) initialized the CLP structure. Calls the command line processor (CLP). Calls the mapping function, which converts the CLP structure in a corresponding command structure. Then it runs the command and as last step it calls the finish function with the command structure, to close all files and free all the allocated memory. If one of these steps fails, then a corresponding return (condition/exit) code is given back from the executable. Only the command execution can result in a error (return code 8) or in a warning (return code 4). The command it self must return a reason code for such a warning or error. This means that the return (condition/exit) code can be used to control the batch processing. The reason code gives more information about the error or warning. See sections <> and <> for an explanation and the output of this command. .Examples ----------------------------------------------------------------------- :> FLCL ERRORS ----------------------------------------------------------------------- ... print CLE_DOCTYP_PROGRAM == FLCL Utility [[flcl.utility]] == 3. FLCL Utility Frankenstein Limes Command Line (FLCL) is a batch utility to execute the following subprograms: * FLUC - Frankenstein Limes Universal Converter (conversion) * FLAM - Frankenstein Limes Access Method (compression and encryption) * FLIES - Frankenstein Limes Integrated Extended Security (management) Each subprogram is also available as DLL/SO or load modules to integrate FLAM into your own applications. The subprogram interface supports each command as dedicated function, which accepts the corresponding command string. For example, this call of FLCL: ------------------------------------------------------------------------ :> flcl info "get.file=test.txt" ------------------------------------------------------------------------ is also available in C programming language as: ------------------------------------------------------------------------ ret=flucinfo("get.file=test.txt"); ------------------------------------------------------------------------ or in COBOL as: ------------------------------------------------------------------------ CALL "FCUINFO" USING rtc 19 "get.file='test.gz'" 0 " " 7 ":STDERR" 0 " " ------------------------------------------------------------------------ The subprograms are called through the commands below: * INFO - a command of the subprogram 'FLUC' -> flucinfo() * CONV - a command of the subprogram 'FLUC' -> flucconv() * XCNV - a command of the subprogram 'FLUC' -> flucxcnv() * XCHK - a command of the subprogram 'FLUC' -> flucxchk() * HASH - a command of the subprogram 'FLUC' -> fluchash() * UTIL - a command of the subprogram 'FLUC' -> flucutil() * COMP - a command of the subprogram 'FLAM' -> flamcomp() * DECO - a command of the subprogram 'FLAM' -> flamdeco() * FIND - a command of the subprogram 'FLIES' -> flisfind() * CHNG - a command of the subprogram 'FLIES' -> flischng() The FLCL can be used in scripts to automate batch processing. The command interpretation is platform independent and optimized for different shells like Windows(R) batch files, Unix bash or z/OS(R) JCL. ... print CLE_DOCTYP_CHAPTER === Installation === 3.1. Installation The product FLAM with all its components (FLCL, FLCC, FLSSRV, ...) is delivered in two parts. The main package contains the whole software and is available as download or via package repository (various Linux distributions). The second part is the license, which determines the features and platforms that can be used, where and for what you can use the software. If only the main package is installed, then a limited DEMO license can be used. ... print CLE_DOCTYP_CHAPTER ==== License ==== 3.1.1. License FLAM is protected against unauthorized use. The authorized usage of FLAM is only possible with a licence module provided by Limes Datentechnik. A licence allows the usage of FLAM on one or multiple computers, capacities, users or per usage. There is a difference between test licences for a limited period and unlimited (or limited) production licences. A test licence allows the testing and benchmarking of FLAM with all functions for a defined period (e.g. 30 days). * Test licenses must not be given to a third party. * During the test period, no backup copies of the test programs are allowed. * After the test period is expired all test programs must be deleted. A production licence allows the limited or unlimited usage of FLAM on any computer for which a licence was obtained. FLAM compresses structure-oriented using an algorithm that is a part of the Frankenstein-Limes method. This method has been patented in the Federal Republic of Germany and the United States of America and at the European Patent Bureau, registered by the inventor on 19th September 1985. ... print CLE_DOCTYP_CHAPTER ==== Download ==== 3.1.2. Download FLAM(R) can be downloaded from our website with the following link: https://flam.de/en/download/flam/ INSTALL and README text files are included as guides for installation. The download area distinguishes several operating systems: [width="50%",cols="2,5",options="header"] |==== |Operating system | Link to installation instructions |AIX | https://flam.de/en/download/flam/latest/aix/install.txt |Linux | https://flam.de/en/download/flam/latest/linux/install.txt |Solaris | https://flam.de/en/download/flam/latest/solaris/install.txt |Windows | https://flam.de/en/download/flam/latest/windows/install.txt |zSeries Linux | https://flam.de/en/download/flam/latest/zSeries/linux/install.txt |zSeries USS | https://flam.de/en/download/flam/latest/zSeries/uss/install.txt |zSeries z/OS | https://flam.de/en/download/flam/latest/zSeries/zos/install.txt |==== Manuals can be found at: https://flam.de/en/technology/download/documentation/ ... print CLE_DOCTYP_CHAPTER ==== Replace External Libraries ==== 3.1.3. Replace External Libraries External libraries under LGPL are linked in dynamic form and can be replaced by another dynamic library which fulfills the corresponding interface. This can be done by deleting the library in the program directory if the replacement library is located in the library path or by overwriting the library in the program directory. The list below contains all LGPL based libraries used by FL5 per platform. glibc on Linux: This library is part of the operating system and a prerequisite to run the FL5 infrastructure on Linux systems. FL5 can be used with different version and distributions of linux. Replacement of glibc will be done by the normal update process of your linux installation. libfuse on Unix: This library is part of the operating system and a prerequisite to run the FL5 file systems on Linux systems. The file systems are delivered for libfuse version 2 and 3. Replacement of libfuse will be done by the normal update process of your Unix installation. libssh: The libssh library can be found in the installation directory. A customized version is used that is not compatible with the official libssh releases. The modified libssh source can be found at: https://github.com/limes-datentechnik-gmbh/libssh NOTE: In all cases we recommend using the tested and supported libraries from this package. If a supplied library is replaced, the license terms and warranty of the new library become valid, replacing the license and warranty of the replaced library. ... print CLE_DOCTYP_CHAPTER === Filename Handling === 3.2. Filename Handling All filenames are mapped by CLE/P, which means that all replacement mechanisms it supports are also valid for each filename used within a command. See <> of <>. All filenames specified in command strings are parsed and handled in a unified way across the different platforms. Standard replacements by shells are usually not usable within the command syntax. There are some special attributes that can be appended to a filename when using paths or the URL-like syntax by using one of the following separators followed by a value string: * `/?` - member name (to access a member in an archive by name) * `/:` or `/#` - member index (to access a member in an archive by position) * `/&` - CCSID that the file's contents are encoded in If the URL-like syntax is used, special characters can be URL-encoded as a percent character followed by two hex digits (%xx). If no schema is provided, but a raw path, URL-encoded characters are not decoded because the string is not a URL. The schema `file://` can be used to access a local file on the system in URL-like syntax. Providing a CCSID is mainly intended to be used for parameter files which are read to memory from a remote location which may require conversion to the local character set. The filename is the only way to specify the CCSID for this type of files. Filenames in archives (ZIP, TAR, FLAM) or certain file headers (GZIP, PGP) are sanitized when reading or writing to prevent directory traversal attacks. This type of attack aims at writing files in arbitrary locations in the filesystem by storing specially crafted paths in the archive or file header. For example, extracting a ZIP file containing paths such as `/etc/passwd` or `../../../../../../etc/passwd` as user root on a Unix-based system could lead to a lock-out of all users. Path sanitization removes all path components that lead to an extraction outside the desired output directory. This includes turning absolute paths into relative ones and removing all `..` directory components. Both example paths above would be transformed to `etc/passwd` which are safe for extraction. The filename handling works as follows: .On mainframe systems (POSIX(OFF)): Usually, a filename has to be specified fully qualified, because a dynamic allocation is done in most cases. The following substitutions can be used, which are automatically replaced by their respective value during execution: ------------------------------------------------------------------------ - to expand an environment variable ------------------------------------------------------------------------ If the environment variables below are not defined, the following defaults are used: ------------------------------------------------------------------------ - The current user id (Example: file='.TEST.DATA') - The current user id (Example: file='DD:') - The current home directory (Example: file='/dat.bin') - The current user id, but normally the default owner 'limes' is defined - The default is simply the first letter of SYSCLONE or if not defined 'T' for test, normally not required for file names ------------------------------------------------------------------------ The syntax to define a DD name is: ------------------------------------------------------------------------ DD:name - a DD-Statement for name (Example: file='DD:INDAT') ------------------------------------------------------------------------ A replacement may also be used in a DD name definition: ------------------------------------------------------------------------ Example: file='DD:' ------------------------------------------------------------------------ Additionally, you can specify member names in a DD name definition if a PDS(E) is allocated. The member name can be fully qualified or contain wildcards. Member names for archives can be specified as part of the URL-like notation or it can be specified separately. ------------------------------------------------------------------------ Example: file='DD:INPUT(*B*)' file='DD:INPUT(EGBERT)' file='DD:INPUT(EGBERT)/?*HOGO*' name='DD:INPUT(*GB*)' member='*HOGO*' ------------------------------------------------------------------------ When using static allocation (DD name) for writing, the DCB parameter must be provided if the file does not exist. Otherwise, the defaults of the runtime environment (often `PS RECFM=UNDEFINED LRECL=0 BLKSIZE=6144`) are used. A static allocation is only useful to write the logical byte stream in a certain physical file format. In all other cases, we recommend to use dynamic allocation when writing new files. Since version 5.1.22-28565 the DD name must not be prefixed with 'DD:' anymore. If only one qualifier given, if it a valid DD name and if a allocation for it found, then the qualifier will be used as DD name. If you use FILE=STREAM when reading the file descriptor STDIN (DD:SYSIN) and when writing STDOUT (DD:SYSPRINT) is used. All other messages are printed by default to STDERR (DD:SYSOUT). For read the default DD name 'FLAMIN' and for write the default DD name 'FLAMOUT' is preferred if no file specification given. If such a allocation not found at write the default dataset name (original name plus extension) is used. For read or write of a FLAMFILE additional the DD name 'FLAMFILE' are supported to be backward compatible with the old FLAM utility. A Unix path name must contain a forward slash (`/`). To use a file in the current directory `./filename` must be used. Paths relative to the home directory may start with a tilde character (`~`) as an abbreviation for for UNIX pathnames or for host dataset names. ------------------------------------------------------------------------ Example: file='~/mydata.txt' file='~.po.dataset(test)' file='DD:~' ------------------------------------------------------------------------ NOTE: Starting with version 5.1.5, the plus sign (`+`) can no longer be used as abbreviation for the user's home directory. The tilde (`~`) remains unaffected and is now the only valid abbreviation. The plus sign (`+`) is now a wildcard character. It was supported as alternative for EBCDIC systems, because tilde is located on different code points depending on the EBCDIC code page. Since version 5.1.5, we support the correct interpretation of diacritical characters on EBCDIC systems based on the CCSID defined in the environment variable LANG. see <> and <> of <> To specify the casing (mainly useful for USS on ZOS) for a user ID, the following definitions can be used (if not defined as environment variable): ------------------------------------------------------------------------ CUSER - The current user ID in upper case (same as ) Cuser - The current user ID in title case cuser - The current user ID in lower case ------------------------------------------------------------------------ .On Unix, Linux, Windows and other non-mainframe systems (including USS) A filename may be an absolute or relative path and may contain any of the substitutions (including ~) mentioned in the previous section. To use a smaller than character (`<`) as part of a filename, the character must be escaped by doubling it. We recommend not to use special or whitespace characters in filenames. The ampersand character (`&`) can be used instead of at sign (`@`) because the letter has different code points in EBCDIC. (the alternative character on EBCDIC, if `@` is not working, is `ยง` (the command line parser converts the `@` corresponding to the environment variable LANG on EBCDIC systems, if the value not set or wrong, then you can use `&` or try `ยง`)). On USS and Micro Focus EDZ, DD names are supported. A UNIX path name is distinguished from a data set name in the same way as it is done in the z/OS runtime environment. Example on USS or EDZ: ------------------------------------------------------------------------ file="//DS:user.test(data)" file="//'user.test(data)'" file="//test(data)" file="//DD:name" file="DD:name" ------------------------------------------------------------------------ .Within Microfocus Enterprise Server (Linux or Windows) If the variable FLAM4MF is set to `yes` or a valid CCSID, a DD name is assumed unless it contains a dot character and is used as the dataset name. Otherwise a DD name must be specified as DD:name and a dataset is given with `//'name'` ------------------------------------------------------------------------ Examples: file="//'user.test(data)'" file=DD:name file=readme.txt ------------------------------------------------------------------------ This corresponds with the syntax for host dataset names on USS of z/OS. With the Microfocus support for Windows and Linux, you can work on x86 Windows and Linux systems with the local MF-EDZ-Enterprise-Server like you work with the catalog access on USS for MVS files. If you work with EBCDIC on the record interface in a EDZ environment then you must set the FLAM4MF environment variable to the used CCSID (e.g. IBM1141). If a CCSID is defined and starts with `IBM`, this will also override the default CCSID in the character conversion component and mark it as z/OS platform. In an error situation, it is possible to enable writing a trace to a file, which can be used to analyze problems. The environment variable `FLAM4MF_TRACEFILE` must contain a valid filename to write the trace output. To set the missing system variables for MF-EDZ, several solutions are implemented including `DD:SYSVAR` and the environment variables `FLAM4MF_STATIC/DYNAMIC_SYSVAR` documented above. .Local and remote file access (via SSH) with URLs (all platforms) Instead of local filenames, complete URLs defining all communication parameters and (if required) the member name or index can be used. Optionally a CCSID for this file can be added. The syntax is: ------------------------------------------------------------------------ schema://userid:authdata@hostname:port/filename/&ccsid schema://userid:authdata@hostname:port/filename/?membername/&ccsid schema://userid:authdata@IPv4:port/filename/:index/&ccsid schema://userid:authdata@[IPv6]:port/filename/#index/&ccsid ------------------------------------------------------------------------ If the URL-like syntax is used, special characters can be URL-encoded as a percent character followed by two hex digits (%xx). If no schema is provided, but a raw filename, URL-encoded characters are not decoded as the string is not a URL. The schema `file://` can be used to access a local file on the system in URL-like syntax. Currently, remote file access via SSH is supported for all file types including FLAM4 archives. The `ssh://` prefix indicates remote access via SSH. The userid is optional, the default is the current login user ID. You can use replacements also in the connection parameter. I.e. `` gets replaced with the lower case login user id, which is useful mainly on mainframes, where the SYSUID is in upper case. The password is optional. If no password is specified, public key authentication is attempted. The hostname/IP is mandatory and the port is optional, defaulting to the SSH standard port 22. The hostname and the remote file path are separated by a slash. An IPv6 address must be put in square brackets (e.g. `[::1]`). An absolute path requires another slash (i.e. // after the hostname). Otherwise, the path is relative to the current directory after login to the SSH server. See examples below: ------------------------------------------------------------------------ file='ssh://user:password@hostname:port//path/file.xxx' name='ssh://:password@hostname/path/file.xxx' name='ssh://[::1]//path/file.*/?*/member.*' ------------------------------------------------------------------------ This URL notation is a simplified form of accessing files via SSH. For even more connection options, you can use the `net.ssh()` object which allows, e.g., the configuration of the public/private key file path or different host key check procedures. See the documentation for the `net.ssh()` object for further details. If both, URL notation and `net.ssh()` object, are used to configure the SSH connection, communication parameters specified in the URL have higher priority. So, if a username is given within the URL as well as the through the object, the username from the URL is used. The file for an inverse command cannot be on a remote system. If a remote report, info or log file is specified, the output data written to the remote system is in the local system's character set. When reading user tables, checksum files, password files or other miscellaneous text files, an automatic character conversion to the local character set is performed. When accessing files via SSH from a mainframe system, the remote file is handled like a file from a non-mainframe platform that does not support datasets since SSH file access is block-oriented and not record-oriented. This means that, if record I/O is used, records are written or expected in one of the open formats on the remote system. For example: ------------------------------------------------------------------------ read.record(file='DATA.SET.PSVBA133') write.record(file='ssh://@server1/[name]') ------------------------------------------------------------------------ This statement for the CONV command of FLCL reads a local physical sequential variable block dataset with a logical record length of 133. A pair of 4 byte length field followed by the record data is written to the remote file for each read record. This is because the default mapping of the host record format (`VB`) to a non-host platform is `OPN_VAR`. .Using file name lists With version 5.1.21 the file name specification was extended to an array. This make it possible to provide a list of files/URLs in the forms below: ------------------------------------------------------------------------ file=hugo.txt file='ssh://user@server/berta.dat file=s*.txt file[hugo.txt,'ssh://user@server/berta.dat,s*.txt] file=hugo.txt,'ssh://user@server/berta.dat,s*.txt file=>list.txt file=>'DD:FLIST' ------------------------------------------------------------------------ In the last case a parameter file containing the list with the URLs can be provided using dynamic or static allocation (DD: only for z/OS). In the case a lot of URLs with several connections can be used. FLAM supports now a connection cache with the result that only the required connections are open. The `NET` overlay provides the default settings for each different URL. In each file specification wildcards are still possible. The feature can be used to combine different files in one archive. ... print CLE_DOCTYP_CHAPTER === Directory Support === 3.3. Directory Support .WHEN READING Multiple input files can be processed at once by using wildcard patterns as input filename and recursion into directories. It is also possible to select only certain members of FLAMFILEs by pattern or index and to specify how directories are traversed. Input file or member names can contain the wildcards below. The wildcards are supported on subprogram level, i.e. wildcards are available in the batch utility and in subprogram calls. Wildcards are not supported on record or byte interface level. ------------------------------------------------------------------------ '*' - zero or more characters '+' - one or more characters '?' - exactly one character '%' - exactly one character (backward compatible with FLAM4 and conform with ISPF (not in URLs)) '#' - exactly one digit (not supported on MVS, because '#' could be part of a qualifier) '=' - exactly one digit (supported on all platforms but mainly for MVS) '^' - escape character (put it before a wildcard character if it is part of the file/member name) ------------------------------------------------------------------------ If one of the wildcard characters is part of the filename itself, you can escape the wildcard character with the caret (`^`). For MVS datasets each qualifier is separated with a period (`.`). If you want to let the asterisk (`*`) or plus sign (`+`) match more than one qualifier, you must put it twice (i.e. `**` or `++`). On non dataset based systems (UNIX, Windows, USS, Linux) this mechanism is not available as there are no qualifiers in filenames and hence periods are handled like any other character. Below you can find some examples: ------------------------------------------------------------------------ file='*.txt' - all files with extension .txt including the file named .txt file='+.txt' - all files with extension .txt and at least one other character file='?.txt' - all files with one character and the extension .txt file='dat^*.txt' - the file "dat*.txt" file='**.G====V==' - all datasets ending with GnnnnVnn (all GDG datasets) file='.**(my*)' - all members starting with "MY" of all PO datasets under current user file='.**(-1)' - all previous generation of all GDG datasets under current user ------------------------------------------------------------------------ The directory support for MVS includes Generation Data Groups (GDG). If you want to read only the previous generation of all GDG's under your SYSUID, you must type as follows: ------------------------------------------------------------------------ file='~.**(-1)' - all GDG's with generation -1 under my SYSUID ------------------------------------------------------------------------ Is a wildcard used at read and the different files should be written into a generation data group as several versions. The file index in minimal amount of digest '[ind0]' could be used the define the next generations '(+[ind0])'. ------------------------------------------------------------------------ infile='/path/to/*.txt' pattern='.GDG(+[ind0])' outfile='USER.GDG(+n)' ------------------------------------------------------------------------ The enclosing quotation marks are required because the file name string contains round brackets. Strings without quotation marks are terminated at the first space character or curved or squared bracket. NOTE: If you use a wildcard in the first/high level qualifier, the catalog search interface (CSI) is used to return each dataset in the catalog. All these datasets are then compared against the corresponding pattern. This can consume a lot of time. Be careful with wildcards in the first/high level qualifier at ZOS dataset names. NOTE: Using wildcards at the beginning of a pattern (for example '**(MEMBER)') could result in opening a dataset which is stored on a tape which is not available immediately. This could result in the process waiting for console input. By default, datasets on tapes are not included in the dataset list retrieved by the wildcard mechanism. If you want to include datasets on tapes, then you must enable the corresponding switch. However, this will not prevent a console request. Files in catalog where the volume is not available, will result in the same behavior. Be careful with wildcards at the beginning of the search pattern. The escape character can be used for datasets, but this is not required. If the match string contains parenthesis `()`, only PO datasets are matched. To match GDG, the first character inside the parenthesis must be `+`, `-` or a number. In all other cases, a PO dataset is assumed. Relative generation numbers are currently not supported for PO datasets. To process only certain members inside archives, a match string for members can be used. A member can be defined as part of the URL with `?` as separator. Alternatively, for FLAMFILEs, a dedicated member specification can be used. In this case a leading question mark (`?`) is ignored. For a question mark as first wildcard, specify two of them. ------------------------------------------------------------------------ file='test*.adc/?*FLAM*' - All members that have "FLAM" in their name in files starting with "test" and ending with ".adc" file='*.adc member=*FLAM' - All members that have "FLAM" at the end of their name in all files ending with ".adc" file='*.adc member=?FLAM*' - All members whose names start with "FLAM" in all files ending with ".adc" file='*.adc member=??FLAM*' - All members whose names start with any character followed by "FLAM" in all files ending with ".adc" ------------------------------------------------------------------------ You can also select members from archives based on the member index. In this case, the member name must start with a hash (`#`) or colon (`:`) and can contain a list of indexes and/or index ranges (two indices separated by minus (`-`), inclusive) separated by comma. For example: ------------------------------------------------------------------------ read.flam(file=*.adc/#3,5,8-10,15) read.flam(file=*.adc/:3,5,8-10,15) read.flam(file=*.adc member=:3,5,8-10,15) read.flam(file=*.adc member=#3,5,8-10,15) ------------------------------------------------------------------------ All four variants read the 3rd, 5th, 8th, 9th, 10th and 15th member from files in the current directory that end with ".adc". To define how wildcard strings are matched, there is an object called 'DIR' that contains some switches. These include recursion into sub-directories, recursion into archives, inclusion of hidden files, symbolic link, etc. See the chapter to the 'DIR' object below for more information. .WHEN WRITING Missing directories are created automatically. To prevent this the switch 'NOMKDAR' must be activated. Overwriting of existing files can be prevented with the 'REMAIN' switch (see below). To convert the file names matched to a certain file name for writing see <>. ... print CLE_DOCTYP_CHAPTER === Input to Output Name Mapping [[flcl.input.output.name.mapping]] === 3.4. Input to Output Name Mapping When creating/extracting an archive, converting files or (more generally) doing batch processing, one might wish to automatically generate new filenames based on a pattern applied to the input filenames. Example: You might want to read a member from a FLAMFILE which was created on a mainframe and contains dataset names. You wish to convert the dataset name into a path-based file name. You can achieve this by defining a pattern for the output file or member name. .Pattern syntax: An output filename pattern can consist of simple text strings and tokens. Text strings are used as-is as output filename. Tokens are enclosed in square brackets (`[]`) and describe processing rules applied to the original file or member name. The pattern can consist of an arbitrary number of text strings and tokens (including none at all). A token can consist of one or more processing rules. Multiple processing rules are separated by a pipe character (`|`). Every processing rule within a token receives the output of the previous rule as its input. This allows chaining of processing rules. Characters inside tokens can be escaped by a preceding caret (`^`) to avoid interpretation as pattern syntax. Outside of tokens, carets are treated literally, except in front of squared brackets to treat a bracket literally and not as token delimiter. The keywords of the tokens below are not case sensitive. This is the list of supported processing rules: * [path] - Extracts the string before the last slash or backslash, i.e. the path without trailing (back)slash * [name] - Extracts the part after the last (back)slash, i.e. the filename * [base] - Extracts the part between the last (back)slash and the last dot, i.e. the filename without extension * [ext] - Extracts the part after the last dot, i.e. the file extension * [member] - Extracts a string enclosed in round brackets from the filename part of the string, e.g. a PDS member name on z/OS * [copy] - Simply copies the input string (useful if you only want to add an extension) * [upper] - Converts all characters to upper case * [lower] - Converts all characters to lower case * [title] - Converts the first character to upper case, all others to lower case * [cutX] - Cuts off the string after the X-th character, where X is a positive or negative number indicating how many characters to keep, counting from the front (positive) or back (negative) * [indN] - Inserts the current index as decimal number of at least length N (padded with preceding zeros) N is any number between 0 and 9, where 0 results in variable length numbers with their shortest possible representation (no preceding zeros) * [rndN] - Inserts random numbers of length N (with preceding zeros) N is any number between 0 and 9, where 0 results in variable length numbers (no preceding zeros) * [AX] - A is a place holder for a single-byte character, X is a positive or negative number; Extracts the string part between the X-th occurrence of the specified character and the next occurrence of that same character. If X is negative, search starts at the back and in reverse. If X is 0, the part before the first occurrence of A is extracted. * [AX-] - A is a placeholder for a single-byte character, X is a positive or negative number; Extracts the string part after the X-th occurrence of the specified character. If X is negative, search starts at the back and in reverse. If X is 0, the input string is copied. * [AX-BY] - A and B are placeholders for a single-byte character, X and Y are positive or negative numbers; Extracts the string part between the X-th occurrence of A and (relative to that occurrence) the Y-th occurrence of B. Like above, negative numbers mean counting from the back. * [search=replace] - Replaces the first occurrence of the string 'search' with the string 'replace' * [search=*replace] - Replaces all occurrences of the string 'search' with the string 'replace' * [regex:/pattern/replace/modifiers] - String replacement with Perl-compatible regular expressions * [table] - Evaluates to the current table name if end of table handling is activated (only when reading tables) .Using regular expressions Regular expressions (short: regex) can be used to apply arbitrarily complex matching rules and substitute these matches using the syntax `[regex:/pattern/replace/modifiers]`. They can be chained like any other processing rules using the pipe character, e.g. `[regex:/pattern/replace/modifiers|upper]` ..Regex delimiters The character immediately following the keyword `regex:` is a delimiter to separate the pattern, replacement string and optional modifiers. The delimiter can be any single-byte character that does not occur in the pattern or replacement string and is expected exactly three times. You can also use pairs of brackets as delimiters in which case the matching closing bracket is expected to follow an opening bracket. A few examples using different delimiters, all performing the same replacement: * `[regex:/pattern/replace/modifiers]` * `[regex:#pattern#replace#modifiers]` * `[regex:{pattern}{replace}modifiers]` The pattern and replacement strings must not be escaped with carets (`^`), even though they are inside a token (`[]`). ..Regex patterns Regular expression patterns in the Perl flavor are matched against the input string to find the substrings that are to be replaced. Writing regular expressions may seem like a daunting task if you never did so before. Understanding the basics is not as complicated as it may seem. You can find a tutorial that will get you started quickly here: + https://www.regular-expressions.info/quickstart.html Countless other tutorials and documentation for regular expressions can be found on the web. We recommend to consult these ressources to familiarize yourself with regular expressions. Advanced users can find the complete syntax documentation for writing regular expression patterns by following this URL: + https://www.pcre.org/current/doc/html/pcre2pattern.html ..Regex replacement strings Replacement strings are mostly string literals, except for the dollar character. A dollar character is an escape character that can specify the insertion of characters from capture groups and names from `(*MARK)` or other control verbs in the pattern. In other words, it can be used to insert parts of the match into the replacement string. Capture groups in a regex pattern are sub-expressions in parentheses. These can be accessed by their numerical index starting at 1 (`$1`, `$2`, ...). The capture group accessed by `$0` always references the whole match. Capture groups can also be referenced by name. A named group in a regex pattern uses the syntax `(?subpattern)`. This group can then be referenced in the replacement with `\$\{name}`. ..Regex modifiers Modifiers change the behavior of regular expression matching and/or replacement. Modifiers are optional and must be placed after the final delimiter. Multiple modifiers can be combined. Currently, these modifiers are supported: * `g`: Enables global matching. The regular expression is applied repeatedly and all matches are replaced. By default, regular expression matching stops after the first match has been replaced. * `E`: Fail with an error if the regular expression does not produce any match. By default, the input string remains unchanged if there is no match. * `R`: Instead of replacing matches in the input string, only the replacement string is returned. * `i`: Enables case insensitive matching. * `m`: Enables multi-line matching. By default `^` and `$` only match at the start/end of the entire input string. With multi-line matching, they also match after/before newlines. Note, however, that unless the `s` modifier is set, the "any character" metacharacter (`.`) does not match at a newline. * `s`: If set, a dot metacharacter in the pattern matches any character, including one that indicates a newline. However, it only ever matches one character, even if newlines are coded as CRLF. By default, a dot does not match at a newline. * `x`: Enables extended matching mode. Most whitespace characters in the pattern are ignored except when escaped or inside a character class. Characters between an unescaped `#` outside a character class and the next newline, inclusive, are also ignored, which makes it possible to include comments inside complicated patterns. * `n`: Disables numbered capturing groups (inside parentheses) in the pattern. Any opening parenthesis that is not followed by `?` behaves as if it were followed by `?:` but named parentheses can still be used for capturing (and they acquire numbers in the usual way). .Examples for using filename patterns: ------------------------------------------------------------------------ infile='/path/to/file.ext' pattern='text_without_tokens' outfile='text_without_tokens' infile='/path/to/file.ext' pattern='text^[path^]' outfile='text[path]' infile='/path/to/file.ext' pattern='[PATH]' outfile='/path/to' infile='/path/to/file.ext' pattern='[Name]' outfile='file.ext' infile='/path/to/file.ext' pattern='[ext]' outfile='ext' infile='/path/to/file.ext' pattern='[UPPER]' outfile='/PATH/TO/FILE.EXT' infile='/path/to/file.ext' pattern='[cut5]' outfile='/path' infile='/path/to/file.ext', pattern='FILE[ind4]' outfile='FILE0001' infile='/path/to/file.ext', pattern='FILE[rnd4]' outfile='FILE0815' infile='/path/to/file.ext' pattern='[/2]' outfile='to' infile='/path/to/file.ext' pattern='[/-1]' outfile='file.ext' infile='/path/to/file.ext' pattern='[/2-]' outfile='to/file.ext' infile='/path/to/file.ext' pattern='[/3-.1]' outfile='file' infile='/path/to/file.ext' pattern='[path=directory]' outfile='/directory/to/file.ext' infile='/path/to/file.ext' pattern='[regex:/\.ext$/.bin/]' outfile='/directory/to/file.bin' infile='/path/to/file.ext' pattern='[regex:#/([^/]+)$#$1#R]' outfile='file.ext' infile='USER.DATA.PDS(MYMEMBER)' pattern='[member]' outfile='MYMEMBER' infile='USER.DATA.PDS(MYMEMBER)' pattern='[.0|lower]/[.1|lower]/[member|lower].[ext|(0|lower]' outfile='user/data/mymember.pds' infile='/verylongpath/to/longfilename.ext' pattern='[path|verylong=|/=*.|.1-|upper].[base|cut-8|upper]' outfile='PATH.TO.FILENAME' infile='/path/to/*.txt' pattern='.GDG(+[ind0])' outfile='USER.GDG(+n)' whereby n starts with 1 and is incremented for each file ------------------------------------------------------------------------ The last example shows a wildcard used at read and the different targets should be written into a generation data group as several versions. The file index in minimal amount of digest '[ind0]' could be used to define the next generations '(+[ind0])'. .More information: Patterns can be used for output file and member names. This mapping mechanism is very powerful. For example, it can be used to compress each directory into a separate FLAMFILE, with each FLAMFILE containing all files of that directory. ------------------------------------------------------------------------ write.flam(file='[path]/?[name]') ------------------------------------------------------------------------ If you define an output filename pattern that results in the same path being generated more than once, the second and further occurrences will append the data to previously written files. If no pattern defined, this means that all matching files on input, will be written to one output file or archive, the append flag is automatically enabled starting with the second file. ... print CLE_DOCTYP_CHAPTER === Key Label Handling === 3.5. Key Label Handling For cryptographic operations (signing, encryption) keys are required. Beside passwords and passphrases FLAM supports professional key management solutions, based on different cryptographic infrastructures and hardware security modules. For example, on z/OS ICSF on other IBM platforms CCA and on distributed platforms PKCS#11 are supported. If a key protected by a shielded hardware module it must be normally referenced by a name called key label. These names or better the convention for these key labels can be different from client to client. To support different key label conventions FLAM supports key label templates. Key label templates using the same replacement mechanismen for environment variables () described in the file name handling above. Only the sepcial characters used as abbrevation are differ. ------------------------------------------------------------------------ '!' = - the environment qualifier (T-TEST or P-PROD) '~' = - current user id (logon name) '^' = - current owner id (defined over the configuration) ------------------------------------------------------------------------ FLAM use hard coded default key label templates for the different encryption solutions. For the OpenPGP support for example: ------------------------------------------------------------------------ '!FLAMPGP.%u.%t' ------------------------------------------------------------------------ Depending on the application several %x replacments can be supported. These qualifier (%u/%t) are replaced with the corresponding variables. In the OpenPGP example above %u are replaced with the USERID or KEYID and %t are replaced with the internal used key type definition. If you provide as USERID for example '~' or '' then the current logon name is used a user id. First the %x is replaced by the variable and then the replacement with the defined environemnt variables is done. Below you can see a few examples with an environment id 'T' for TEST and the internal types 'PUBLIC' or 'PRIVATE': ------------------------------------------------------------------------ TEMPLATE='!FLAMPGP.%u.%t' USERID='FREI' -------->'TFLAMPGP.FREI.PRIVATE TEMPLATE='!FLAMPGP.%u.%t' USERID='' #this makes not realy sense, but it is possible# -------->'TFLAMPGP./home/frei.PUBLIC TEMPLATE='!FLAMPGP.%u.%t' USERID='~' -------->'TFLAMPGP.frei.PRIVATE TEMPLATE='!FLMPGP..%u.T%t' USERID='~' -------->'TFLAMPGP.limes.frei.TPUBLIC TEMPLATE='!FLMPGP.^.%u.TYP.%t.MYKEY' USERID='~' -------->'TFLAMPGP.limes.frei.TYP.PRIVATE.MYKEY ------------------------------------------------------------------------ The internal type is defined by the application (mainly the used FLAM key management extension version 5 (FKM5)). Over the key template only the position of the internal type can be defined, the value is given by FLAM. The key template handling and limitations (how long, which characters, how many qualifiers also) are depending on the FKM5. The underlying cryptographic infrastructure defines what is possible. For example, a key label in PKCS#11 can be free defined and for ICSF/CCA it must conform to host data set names. Have a look at the FKM5BOOK for these details. Since version 5.1.16, the replacement characters are no longer case sensitive. The two templates below are equivalent ------------------------------------------------------------------------ TEMPLATE='!FLAMPGP.%u.%t' TEMPLATE='!FLAMPGP.%U.%tT' ------------------------------------------------------------------------ This change is making it easier to define such templates in JCL (CAPS ON) on z/OS. ... print CLE_DOCTYP_CHAPTER === Password Handling === 3.6. Password Handling Several components allow entering passwords, for example to encrypt files or establish SSH connections. Putting such sensitive information inside a script, a JCL or entering it directly on the command line can be serious security issue. Therefore, any string assingment within a command can be sourced out to a file which is much easier protected against prying eyes. ------------------------------------------------------------------------ password=f'pwdfile.txt' ------------------------------------------------------------------------ The prefix 'f' tells CLE/P that the string must be read from the specified filename. The file itself must contain the CLE/P string value. With SSH you can provide the password as part of the URL: ------------------------------------------------------------------------ ssh://user:password@host:port ------------------------------------------------------------------------ In this case, it may not be very useful to put the whole URL inside a file. Instead, the password can be specified through the corresponding NET object, where the password is a separate parameter. The rest of the connection information can remain in the URL: ------------------------------------------------------------------------ net.ssh(password=f'pwdfile.txt') file=ssh://@server.com/myfile.txt ------------------------------------------------------------------------ If you wish, you could also put all connections parameters inside the NET object, so that the URL form is not needed: ------------------------------------------------------------------------ net.ssh(user=max host=server.com password=f'pwdfile.txt') file=myfile.txt ------------------------------------------------------------------------ If a connection parameter is specified in the URL as well a in the SSH NET object, the values from the URL takes precedence. The special replacement capabilities (~) for file names, however, are only available for the URL. In the NET.SSH object only the simple string replacements () can be used. Sometimes it is convenient to use a parameter file for an object, overlay or command which contains the password. ------------------------------------------------------------------------ net.ssh=sshparm.txt net=netparm.txt conv=convpar.txt ------------------------------------------------------------------------ All these capabilities can be used to protect passphrases, but we recommend to use public key authentication with SSH and the use of our key management extension (FKME/FKM5) for PGP or FLAMFILEs to protect the keys by professional cryptographic infrastructure (e.g. with a HSM (hardware security module)). ... print CLE_DOCTYP_CHAPTER === Handling of Empty Records [[flcl.handling.empty.records]] === 3.7. Handling of Empty Records The handling of empty records is complicated on z/OS. FLAM5 uses the language environment (LE) to read and write records. If the environment variable '_EDC_ZERO_RECLEN' is not defined, it defaults to Y(es) for the record I/O operations. When reading, this results in an empty record being converted to a neutral FLAM5 record element. When writing, however, an empty variable length record is not written at all by the LE. To circumvent this, a padding character (default: 0x00) is written for an empty variable length record. To suppress this added padding character when reading the output file later, a record of length 1 with 0x00 or 0x40 will result in an empty record of length 0 if the environment variable '_EDC_ZERO_RECLEN' is set to 'Y'. In any other case, empty variable length records are converted to a record of length 1 containing the padding character by default on z/OS (binary files: 0x00, text files: whitespace character (0x40)). On platforms which support writing empty variable length records, when writing fixed-length records or when print control characters are used, this kind of dirty padding of empty variable length records is not done. ... print CLE_DOCTYP_CHAPTER === Handling of Spanned Records [[flcl.handling.spanned.records]] === 3.8. Handling of Spanned Records Spanned records are supported by FLAM5 components with a record length of up to 1 MiB. This length can be extended on request. The old FLAM4 components do not support such large records. To write large records to the old FLAMFILE, the matrix with the records must be convert to a block with record length fields in order to write this block into a FLAMFILE. The FLAM4 components will handle such a block as an undefined byte stream. When reading, the conversion from block to records must be requested with the same method to restore the original records. With XCNV, block/record formatting or conversion capabilities can be used. The CONV command offers the LARGER switch when reading and writing FLAMFILEs to activate the this type of conversion. When LARGER is used the block conversion is performed with the B4X method. There is currently no automatic approach implemented for it. The following example uses the XCNV command to read a VBS file and write the large records to a FLAMFILE with block formatting. ------------------------------------------------------------------------ //FLCLXCNV EXEC PGM=FLCL,REGION=0M,PARM='XCNV=DD:PARM' //STEPLIB DD DSN=&SYSUID..FLAM.LOAD,DISP=SHR //SYSOUT DD SYSOUT=* //SYSPRINT DD SYSOUT=* //PARM DD * INPUT( SAVE.FILE( FIO.REC( NAME='.VBS.LR' ) ) ) OUTPUT( SAVE.FILE( FMT.BLK( METHOD=B4X ) FIO.FL4( NAME='.VBS.LR.ADC' ) ) ) /* ------------------------------------------------------------------------ To read the created FLAMFILE back to records and write it as VBS, the job below can be used, using record conversion. ------------------------------------------------------------------------ //FLCLXCNV EXEC PGM=FLCL,REGION=0M,PARM='XCNV=DD:PARM' //STEPLIB DD DSN=&SYSUID..FLAM.LOAD,DISP=SHR //SYSOUT DD SYSOUT=* //SYSPRINT DD SYSOUT=* //PARM DD * INPUT( SAVE.FILE( FIO.FL4( NAME='.VBS.LR.ADC' ) CNV.REC( METHOD=B4X RECLEN=200KiB INICNT=4 ) ) ) INPUT( SAVE.FILE( FIO.REC( NAME='.NEWVBS' FALLOC( RECFORMAT=VBS RENEW ) ) ) ) /* ------------------------------------------------------------------------ The READ/WRITE.FLAM4() objects with the LARGER switch actived will do the same, but without the possibility to change the format of the length field with the METHOD parameter. The FLAM command of FLCL and the new FLAM4 utility will also support the LARGER switch when reading and writing FLAMFILEs. By default, the record length for VS/VBS is 1 MiB. To save memory, this can be reduced with the RECLEN parameter. The FLAM5 I/O will read large V(B)S records by default. This can be deactivated for record I/O by using the switch NOSPAN. This switch is active for the FLAM command of FLCL, or the new FLAM4 utility, if the LARGER switch is not enabled to ensure backwards compatibility. NOTE: Automatic record length detection will not work with large records (>=32768). This requires to set the record formatting method when reading such a FLAMFILE. ... print CLE_DOCTYP_CHAPTER === Use of IBM Unicode Services [[flcl.use.of.unicode.serives]] === 3.9. Use of IBM Unicode Services Since version 5.1.27, FLAM supports the use of IBM Unicode Services on system Z. The Unicode Services are used only if no user table, transliteration, case mapping, subsets, whitespace handling, reporting, normalization or other complex conversion is requested. If a simple conversion is done, in a few cases the implementation of FLAM is faster and FLAM will still use this faster implementation. In all other cases, the IBM Unicode Services will be used by default to reduce CPU and memory utilization. It is important to note the differences in behavior of the IBM Unicode Services: * If an incomplete character is encountered and the error handling is not STOP, the FLAM character conversion module ignores or substitutes this incomplete character. The IBM Unicode Services does return an EINVAL error in this case. * IBM Unicode Services can produce errors for technically valid code points when processing UTF-8 encoded data. The FLAM character conversion module first decodes UTF-8 and verifies the code point afterwards, independent of the encoding. This means you can encode code points in multiple forms (e.g. the character 0 as 0x30 or 0xFC80808080B0). The IBM Unicode Services support only the shortest form (0x30) of an encoding for a code point and all other possible encodings are not accepted and will result in an error (invalid character). * Depending on the Unicode Services version (APAR) a BOM character in the data might remain for UTF character sets or might be replaced by a substitution character for single byte character sets. When calling the Unicode Service FLAM will request the BOM removal, and FLAM will remove a BOM character if it is causing an invalid character error, but both will not work with certain versions of Unicode Services. * No error is caused by a wrong BOM (invalid character) in the middle of the data and a BOM change from LE to BE or vice versa is also not detected. For data with mixed endianness the Unicode Services should be deactivated. To prevent these changes in behavior you must set the system symbol `&FLIBMUS` or the environment variable `FL_IBM_UNICODE_SERVICE` to `OFF`, but this will result in more CPU and memory utilization for simple character conversions (see chapter <>). The environment variable's default is `AUTO` which ensures that only the minimal behavior changes above are in place. To use the Unicode Services also for character conversion mode `STOP` the environment variable has to be set to `ON`. This will cause FLAM to use the round trip conversion technique of the Unicode Services, which results in the behavior changes below: * A lot of non-convertible characters will be converted to a unique character in the target character set without an error using the round trip conversion scheme. * A substitution character is only converted with activated substitution. Without substitution, the substitution character 0x1A in ASCII/UTF or 0x3F in EBCDIC will cause an error. Based on that behavior FLAM will request the substitution if Unicode Services are used. We recommend to set FL_IBM_UNICODE_SERVICE=ON to maximize performance if the limitations described above are acceptable because checking each character if it is valid or not has a significant performance impact. ... print CLE_DOCTYP_CHAPTER === Table Support [[flcl.table.support]] === 3.10. Table Support Since version 5.1.16, FLAM supports conversion of tables in the form of fixed and variable record structures (based on length fields or binary delimiter) and CSV (comma separated values) files. Tables can be encoded, encrypted and compressed like any other file. Tables can be converted easily between FB/VB datasets, CSV, XML and other file formats. Table columns can be re-ordered, removed or written in multiple representations (adds additional columns). The table format must be described as row specification. This is a CLP string which contains an unlimited amount of columns. There can be more than one row specification per file, which means that multiple tables may be present in a source. Support for tables is most useful when used through our stream, byte and record interfaces. For example, a Java or C/C++ application that can process CSV files, can also process tables stored in physical FB or VB datasets by converting back and forth between both formats with FLAM. A COBOL or PL1 application could use the record interface to put or get fixed or veriable structures, but in reality a CVS or XML file is read or written on a local or remote system. When reading, the format of each column must be described, so that FLAM knows how to break up records into cells of the table. For example, a simple method is to cut records into multiple cells based on a fixed length for each column. When writing, columns are written in their original format unless a row specification is provided that describes how the columns are joined together with the other elements in this row to a certain data format. For each column, an unlimited number of pre-processing steps can be specified which are executed before neutralisation of the read element. A pre-processing step could be column decryption or type conversion, e.g. conversion of a BCD number to a neutral FLAM-internal integer representation, or any other supported conversion. When writing, this neutralised number could be written to a column as decimal number string. An unlimited amount of post-processing steps (e.g. encryption) can follow before a table cell is written out. For hierarchical formats an additional format-specific path must be provided for each column. There can be more than one such path to support different hierarchical formats for the same table. This allows to convert the same table, for example, to a CSV file (no path required), to an XML file (XML path required) and to a Swift MT103 message (TVD path required). For more information, please read the table formatting sections. ... print CLE_DOCTYP_CHAPTER === Pre- and Post-processing === 3.11. Pre- and Post-processing Starting with version 5.1.21, custom commands can be executed before and/or after conversions. These pre or post commands can be executed per file and/or per conversion task. Pre and post commands can be executed on the reading and the writing side of a conversion. Per-file commands are executed either before the correspond file is opened or after it is closed. Commands are executed on the machine where the file is read from / written to. So, when writing a file via SSH, associated per-file commands are also executed on the remote host. Executing commands per file is only supported with the FIO objects of the XCNV command at INPUT and OUTPUT. The READ and WRITE overlays of the CONV object currently only support global pre and post commands. Per-file commands can access the filename / path of the associated file through the square bracket syntax known from filenames (see the section <> for details). At write the file post-processing are only done by default in the final close of the I/O component. This results at directory walk in only one post-processing for the final file. This is required for example if you will write all the files to one archive or append anything to one file. If you process n input files to n output files it could be useful to enforce the post processing per file. Since version 5.1.24 of FLAM the switch 'PERFILE' could be activate for this. Below you can find an example using XCNV with pre and post commands: ------------------------------------------------------------------------ flcl xcnv "input(sav.fil(fio.blk(file=ssh://user@in.ssh.server/test.txt prepro(command='touch [name]') postpro(command='rm [name]' #ccsid='ISO8859-15'# stderr=stdout stdout=log on=success) ))) output(sav.fil(fio.blk(file='ssh://user@out.ssh.server/test.gz' comp.gzip() postpro(command='sha1sum [name]' stdout='ssh://user@in.ssh.server/test.sum/&UTF-8' on=success) postpro(command='rm [name] on=failure) )))" ------------------------------------------------------------------------ In the input portion, a pre-processing step makes sure that the input file exists on the remote host. Output written to stdout or stderr by the command is ignored. Only in case of an error, the first bytes of stderr output are written to the error trace. The CCSID parameter can be set to the charset used on the remote system. This converts any command output from this CCSID to the local character set. For commands executed via SSH, this defaults to UTF-8 with automatic fallback to Latin-1. For local commands, the local character set is used by default. In the example above, the correct CCSID for USS on z/OS is included as comment. The post-processing step deletes the input file, but only if the conversion succeeds. This command's standard output (stdout) and standard error (stderr), if any, is written as STDOUT to the log. The default CCSID (UTF-8/Latin-1) normally fit, but if the Euro-Symbol in the data, ISO8859-15 would be the better choice. In the output portion, there are two post processing steps, one is executed on successful conversion, the other when an error occurs. On success, a SHA1 checksum of the written gzip file is calculated and the output is written (in UTF-8) to a file on the SSH host of the input file for verification purposes. The command output is converted to UTF-8 (from 'UTF-8' with 'Latin-1' fallback because no CCSID is specified. On error, it is attempted to delete the possibly partially written file. We recommend to use SAF checks to restrict how this feature can be used because it can execute arbitrary shell commands with the rights of the current user. ... print CLE_DOCTYP_CHAPTER === Use of Built-in Functions === 3.12. Use of Built-in Functions The generated description of the built-in functions are independent of the program, owner and command names. This may make it difficult to use them. Below, you can find some examples for the use of built-in functions of FLCL. ------------------------------------------------------------------------ To get the syntax for command CONV: :> flcl syntax conv To get the syntax for the overlay read of command CONV: :> flcl syntax conv.read To get the syntax for the object text of overlay read of command CONV: :> flcl syntax conv.read.text To get the complete syntax (not only one level) of overlay write of command CONV: :> flcl syntax conv.write all To get the help for command INFO: :> flcl help info To get the complete help for the overlay GET of command INFO: :> flcl help info.get all To get the manual page for the overlay GET of command INFO: :> flcl help info.get man To generate the manpage for command CONV: :> flcl manpage conv=manconv.txt To generate the manual for command CONV: :> flcl gendocu conv=docconv.txt To generate the complete user manual for FLCL: :> flcl gendocu=docflcl.txt To change the properties for command FLAM: :> flcl chgprop flam mode=VR8 inrecformant=undefined cut=ON To generate and activate a property file for command CONV: :> flcl genprop conv=conv.prop :> flcl setprop conv=conv.prop To list all defined properties: :> flcl getprop To list all properties for command INFO: :> flcl getprop info depall To list only the defined properties for command INFO: :> flcl getprop info defall Delete a property file for command CONV from the configuration: :> flcl delprop conv To define "HUGO" as owner: :> flcl setowner HUGO To get the current owner: :> flcl getowner To define a environment variables: :> flcl setenv LANG=DE_DE.CP1252 To list all defined environment variables: :> flcl getenv To delete a environment variable: :> flcl delenv LANG To activate tracing in a file: :> flcl trace file=trace.txt :> flcl trace on To deactivate the trace: :> flcl trace off To list all the defined data in the configuration file: :> flcl config To delete all the configuration settings from the configuration file: :> flcl config clear ------------------------------------------------------------------------ All built-in functions not listed here do not require any parameters. On mainframe systems, using built-in functions in JCL looks like: ------------------------------------------------------------------------ //* SET ENVIROMENT VARIABLE LANG (IMPORTANT FOR AUTO CONVERSIONS) //SETENVL EXEC PGM=FLCL,PARM='setenv LANG=DE_DE.IBM-1141' //STEPLIB DD DSN=&SYSUID..FLAM.LOAD,DISP=SHR //SYSPRINT DD SYSOUT=* //SYSOUT DD SYSOUT=* //* ------------------------------------------------------------------------ For documentation, help and syntax you can also use the ISPF commands FLDOC, FLHLP and FLSYN under menu 6. ------------------------------------------------------------------------ FLDOC CONV FLHLP XCNV.INP FLSYN UTIL ------------------------------------------------------------------------ ... print CLE_DOCTYP_CHAPTER === CONV versus XCNV and ICNVs === 3.13. CONV versus XCNV and ICNVs Sometimes it is difficult to figure out which command is the right one. Especially for the conversion commands (CONV/XCNV/ICNV) understanding the differences is important: .CONV: * simple to use, more automatisms, fewer parameters * the user must not know how the data is formatted or where it came from * the conversion is done on a best-fit basis for platform specific formats * there are no possibilities to do dirty things * converted data can be written to only a single target * the automated detection and conversion can result in more CPU usage * only global pre- and post-processing at read and write is supported .XCNV: * gives access to all capabilities of FLUC (more complex to use) * the user must know how the inout data is formatted and where it came from * the conversion is done as good as possible to the original data * dirty things (e.g. manipulation of file modification time) are possible * conversions are limited to a minimum of CPU usage * output can be written to multiple targets via an array of file I/O specifications * supports global pre- and post-processing and pre- and post-processing per file .ICNV: * provides only character set conversion for block or record-oriented files * is much simpler than CONV and XCNV ... print CLE_DOCTYP_CHAPTER === CONV READ/WRITE Overview === 3.14. CONV READ/WRITE Overview The 'read' part describes how input data should be handled, whereas the 'write' part describes how to write the data which strongly depends on how it was read. .READ * RECORD ** FIX, read records with a fixed length ** VARIABLE, e.g. record starts with length field ** DELIM, record ends with defined delimiter (like READ.TEXT but just one delimiter is defined) ** Character conversion, if CCSID is set, else binary handling ** Records as output * TEXT ** Record length is ignored/lost ** Text is split at delimiters (all usual text delimiters) and separated into a record and a rest portion (trailing whitespace + delimiter) ** Automatic character conversion ** Records as output * CHAR ** Record length is ignored/lost ** Reads all characters, delimiters are also part of the data ** Automatic character conversion ** Blocks as output (block handling) * BIN ** Record length is ignored/lost ** Reads all bytes as is ** Blocks as output (block handling) .WRITE [cols="2h,5,5",options="header",width="100%"] |=== | READ / WRITE | RECORD | TEXT | RECORD | * FIX, write with fixed length * VARIABLE, e.g. write with length fields * Character conversion only if CCSID is set ** If printable characters ** Else binary handling | * Read records are complemented with a delimiter ** Non Host files e.g. USS ** Definition of own delimiter is possible ** Automatic character conversion | TEXT | * Read text records are written (rest portion is dropped) ** Usually VB * Other record formats also possible ** Padding on FIX records * Automatic character conversion | * Read text records are written (rest portion is dropped) * Supplemented with system delimiter ** Definition of own delimiter is allowed * Automatic character conversion |CHAR | * Usually not useful! * Read blocks are cut into records * Default: ** VB with n records and smaller rest at the end * Automatic character conversion | * !!! ERROR !!! |BIN | * Usually not useful! * Read blocks are cut into records * Default: ** VB with n records and smaller rest at the end * Automatic character conversion, if required | * !!! ERROR !!! |=== [cols="2h,5,5",options="header",width="100%"] |=== | READ / WRITE | CHAR | BIN | RECORD | * Records are concatenated * Automatic character conversion * No delimiter supplement | * Records are concatenated * Binary handling | TEXT | * Read text records are written with original delimiters * Automatic character conversion | * Keep internal representation (UTF-8) of text * Read text records are written with original delimiters |CHAR | * Automatic character conversion | * Keep internal representation (UTF-8) of text |BIN | * Read data is assumed to be in local charset * Writes character blocks ** Possibly character conversion | * Read binary blocks will be written |=== ... print CLE_DOCTYP_CHAPTER === Security Considerations === 3.15. Security Considerations Safety is an important issue for FLAM. FLAM can help to fulfill many security requirements (e.g. PCIDSS, ISO27001, ...), using encryption (OpenPGP, SSH), hardware security modules (PKCS#11 and IBM CCA/ICSF for key exchange and signing), strong access control and checksums, antivirus scanning and much more, nevertheless the following points must be observed for the secure operation of FLAM. //// TODO: .SOC support With a maintenance contract you can register in the customer portal for a newsletter about security vulnerabilities. This newsletter will be sent if a security vulnerability for FLAM comes up. This is useful in supporting your secure operating center (SOC). //// .Related software In the `install.txt` for your platform under prerequisites you will find the software on which FLAM is based or depends. If nothing is listed, then only the operating system with the language environment and the corresponding libc is affected. In the `about.txt` you can see all the external libraries and their versions that FLAM integrates. Both pieces of information can be used to determine whether the use of FLAM might be affected by an emerging security vulnerability. .Check coherence With the call `flcl version` a version of each software component is written. The installation of FLAM will be coherent if all build numbers are the same. The build number is the last number of the version behind the minus character. Especially for dynamic linked parts of the software it will be important to check if the installation was well done. We recommend establishing an installation verification process which runs the built-in function `VERSION` and verifies that the build numbers are all the same. .Code signing limes support code signing for modules and installation packages if it is possible on a platform. If not limes provides secure checksums to allow verification of the packages after download. .Environment There are a lot of environment variables or system symbols which are security related. Below you can find some important examples (please note: this list is incomplete): * FL_PGP_PREF_SYMALG_AES128 - Invert order of preferred symmetric algorithms from AES256/192/128 to AES128/192/256 in PGP certificates * FL_ALLOW_LOW_ENTROPY - If defined and no source of entropy is available, the random number generated is seeded with a low entropy which may result in weak encryption keys * FL_DEACTIVATE_HW_CRYPTO_ACCELERATION - Deactivate hardware acceleration for cryptographic operations (enforce use of software implementation) * FL_SSH_HOME_DIR - Directory containing SSH key files and known_hosts file (/home/user/.ssh) * FL_KEY_EXPIRE_WARN_DAYS - Amount of days to warn before a key will expire (default is 90 (3 months)) See <> and verify these settings. To get a list of the current environment please use the command below: ----------------------------------------------------------------------- flcl info get.system ----------------------------------------------------------------------- .SAF support For operating systems implementing a secure access facility (e.G. z/OS) FLAM supports a lot of policies and additional resources for better control about the usage of FLAM. For more information about this see <> and the `install.txt`. Unfortunately, there is no such additional protection of application-specific resources for other operating systems. With the SAF support it is possible to ensure minimal key, password or hash length. Critical operations like input logging, packet capturing, antivirus scanning etc. can be deactivated and more. There are a lot of policies and resources defined for the supported cryptographic features (PGP, EDC, SSH), which will not be explained below in more details. .Credentials Credentials (Passwords, PINs, Keys, ...) entered using the CLP strings are flagged as protected and will not be printed in clear form. Such values are replaced by `****** SECRET ******` unless the input logging is activated. In this case the complete command string is written to the log and might contain critical values. After parsing the command line FLAM knows the critical values and is replacing them. Additionally it is better to provide such sensitive input within parameter files. The file can be better protected. But the best solution in such cases is to use a hardware security module (HSMs). .Support of hardware security modules (HSMs) FLAM supports hardware security modules (HSMs) over a service provider interface for session key procedures and signing (PGP, FLAMFILE, ...). Currently, the use of PKCS#11 and IBM CCA (including ICSF) are supported. We recommend using the HSM support instead of clear passwords for key stores or such critical things. The misuse of the service provider interface can be prevented completely with SAF support. .Verification of cryptographic algorithms All software cryptographic operations are done using a central crypto kernel (CryCore). This singleton determines the optimal implementation depending on the computer used. It supports hardware acceleration if possible. But before the concrete algorithm is used the first time a self test against the NIST test vectors is done, to ensure that the loaded functions do implement the algorithm correctly. For IBM mainframes mainly the CPACF functions are used to implement the cryptographic algorithms. For all other platforms the library libcrypto of the OpenSSL project is used. .Secure randomness To generate keys (mainly for SSH) it is important to have a high entropy. By default, FLAM ensure a high entropy which could result in an error, if only weak randomness is available. The environment variable `FL_ALLOW_LOW_ENTROPY` allows low entropy to prevent such errors and the policy `LOW.ENTROPY` can be used to prevent this. In some cases the quality of randomness is not so important, in such cases it could be useful to allow low entropy and in another context it will be dangerous, and then it will be better to prevent this. .Secure delete of sensitive data FLAM supports secure delete of sensitive data (keys, passwords, pins). This means that erasing the memory is done as early as possible and the overwriting of the memory will not be eliminated by the optimizer for the release code. .Antivirus scanning FLAM supports antivirus scanning over a service provider interface. It will be required by certain security standards to scan the clear content of a file before it is encrypted and stored on a remote system. In such a case the antivirus scanner can be used. Our standard implementation uses clamAV, but the interface can be implemented against each kind of antivirus scanner. Simultanously, this interface is a backdoor to intercept clear data and should be closed for all other cases. FLAM implements a complete set of SAF control mechanism which can be used to ensure this. .Input logging The input logging will write the complete input parameter string to the log (this is not done by default and only important for debugging in a few cases). In this case the content is not known and might contain critical data or credentials. The SAF policy `LOG.INPUT` can be used to prevent the activation of input parameter logging. .Packet capturing Packet capturing is useful to find errors for remote connections (e.g. SSH) but packets might contain critical or sensitive data. With the SAF policy `SSH.PCAP.ALLOWED` you can control the usage of the PCAP feature and prevent this kind of backdoor for normal processing. .Command pre- and post-processing The command pre- and post-processing is a powerful feature of FLAM and can be used in once or per file, locally or remote at read or write. The feature was implemented mainly for process automation but to run commands (often executable code) on remote systems could be dangerous. To prevent misuse FLAM has implemented a set of SAF controls. .FLAM started task (FLAMSTC) The FLAM started task (FLMSTC) on z/OS is an active component running in the background providing services to implement the subsystems, including the LE-less interface for the FLUC record interface. The FLAMSTC provides the scheduling of SRBs in another enclave for the zIIP support and the possibility to run authorized functions. This is realized with three different PC routines. The FLAMSTC does not implement own supervisor calls (SVCs). Functions of the FLAM and FLUC subsystems are called as part I/O SVCs. The QA process is using zACS to penetrate the PC routine and the corresponding recovery routines. The only findings of the zACS scan are regular program terminations of the FLAMSTC with 0C4. //// TODO: .FLUC file system (flucFS) sollte nur under eigenen user laufen //// .Error trace The error trace is an important feature of FLAM which help a lot to analyze errors. For a good cause determination the data involved in the error is often written to the error trace. This means that the error trace could include parts of sensitive data items. In a case of an error this trace might need protection. It is similar to a dump processing in an error situation. Such a dump could contain critical data and must be protected. .Quality assurance limes is using vulnerability scanners and static code analysis for conformance with certain Coding Standards to prevent critical mistakes in our programs. Additional CPPCHECK and ScanBuild are used for static code analyzes. For each platform limes uses the standard memory checker (e.g. valgrind on linux) for dynamic code analysis running over all test cases. But there are a lot of platforms without a tool for runtime analyzes. Therefore, limes has implemented an own resource checker (memory, file handles, stack, ...) in the debug code to detect stack and memory overflows, missing frees(leaks) or unclosed or misused files. Limes is using Coco(r) to determine the code coverage of FLAM and ensure that each part of the code is tested. Squish(r) is used to automate testing of our GUIs. For automated testing of each ISPF panel and limes command we use the API of the x3270 terminal program. For all testing limes is using an own test framework which runs all the unit and regression tests on all platforms. The cross-reference tests nsures that data produced by standard tools (e.g. gzip, openssl enc, gpg) is understood on each platform and produced output of FLAM from each platform can be read with the standard tools. We use continues integration, this means that all the build tests are running after each build, a rebuild must be successful before the code is taken over from the developer repository to the main repository and all the long-running tests (performance, large files, ...) will be started automatically each night and anything will be checked each morning. This allows us to deliver rolling releases, where a customer can request a new parameter on Wednesday, and we can deploy a new revision or release on Monday. For this each weekend is currently used to clean anything, rebuild anything, tests anything, package anything, install the new package to a clean system, test anything again. And if anything was successful then we can publish the new build for our users. Sometimes it takes long to get all tests to run with success, and we cannot release a new version each week. All regression tests must be successful before we publish a new version of FLAM. The publishing include an encrypted code escrow for the complete source used to build this release. All build results, all test results anything will be stored in an archive for this publication. So we can review the complete state if a customer has a problem with a certain build including all tests results, all compile and link lists and so on. We can install from this repository easily each published build, to set up the customer environment to reproduce an error or a behavior. .Methodology limes is using a mixture of SCRUM and team concert with strict coding guidelines where requirement, design, development, build, test, packaging, installation, testing again and the deployment runs in parallel. Version control is done with GIT and anything is integrated in an eclipse workspace under Arch Linux for our developer. The software development process ensures that all described QA measures are adhered to. .Documentation The documentation is generated from the source code and based on that it must be totally in sync with the application and components used. The quality of the description for a parameter or the manual page for an object or overlay could be bad, but any implemented feature is documented and vice versa. We use the FLAMCLEP command string parser and anything what this compiler is accepting is defined in tables and the help message and the manual page must be provided otherwise a table error occurs. The same method is used for interface specifications (API), where each function and each parameter for each function must be documented in form of comments in the code otherwise the docu generation will fail. This process ensures that the documentation is always up-to-date and in sync with the implementation and the user can trust that anything is documented. ... print CLE_DOCTYP_CHAPTER === Performance Considerations === 3.16. Performance Considerations Performance (CPU/memory utilization and throughput) is an important topic when using FLAM. The following points describe some major factors that contribute to the overall performance of FLAM. They should give you a good starting point if you experience performance issues. .Pre-load architecture In order to minimize consumed CPU cycles during mass data processing, FLAM pre-calculates as much as possible before processing any data, which requires memory on the one hand and spends some CPU time on the other. If you process many small files with FLAM, this can have a negative effect on performance. FLAM is not designed and developed to process small amounts of data. .Hardware accelerator support FLAM uses special instructions of the respective hardware platforms to be able to accelerate some algorithms. On IBM's mainframes, for example, this concerns the use of CPACF and zEDC. .Outsourcing of computing power to zIIP For IBM mainframe systems, it is possible to outsource memory-to-memory functions (compression, conversion, formatting) as SRBs to so-called zIIP processors. Although this does not result in a performance advantage, it does save chargeable CPU time (MSU). .Record count and block size FLAM processes data in self-sufficient segments, which represent a block or a certain number of records. The amount of data that is processed in one go determines the throughput performance. It is important to understand that there is an overhead per segment, so the segments should not be too small. However, if too much data is put into a segment, then the processing constantly takes place outside the caches, which also reduces the performance. Here, the block size or the record count must be optimally selected for the respective platform. For historical reasons, FLAM works with a default block size of 64 KiB and a record count of 512. This is a good average value across all platforms, but not always optimal. It should also be noted that such a segment is expanded after decompression, i.e. in this case one should always start with a smaller block size. On many systems, 256 KiB is now a good block size. The optimal record count is the optimal block size divided by the average record length. .Character set conversion Character set conversion can take up a lot of CPU time. By default, FLAM checks each character for validity and stops processing with an error if invalid or unconvertible characters are found (MODE=STOP). This form of error handling is relatively expensive in terms of CPU utilization, but ensures detection of incorrectly encoded text data. Enabling error handling that leads to the replacement of these incorrect characters, processing can be accelerated. The character set conversion is faster if all characters of the input alphabet result in data of the same length in the output alphabet. With the environment variable `FL_DEFAULT_CHAR_MODE` (or the system variable `&FLCHARM` on z/OS), the default mode for error handling during character set conversion can be changed from `STOP` to `SUBSTITUTE`, for example, in order to achieve higher performance here. On z/OS, FLAM uses the IBM Unicode Services as long as it supports the required character set conversion and is known to be faster than FLAM's implementation. This only works for simple conversions without mappings, subsets, reporting or transliterations. The environment variable `FL_IBM_UNICODE_SERVICE` (or the system variable `&FLIBMUS`) can be used to enable/disable the use of IBM Unicode Services. By setting the variable to ON instead of the default AUTO, the IBM Unicode Services will also be used if STOP is selected as the character conversion mode, which saves a lot of CPU cycles, but at the cost of no longer noticing some errors in the character data. .Logging FLAM writes many log messages by default, which also takes up CPU time and I/O. The `QUIET` or `SILENT` keywords and the `MESSAGE` object can be used to control the amount of output and thus limit or increase the amount of work involved. Often, during the transition from test to production, people forget to reduce FLAM's chattiness, which cost both disk space and CPU cycles in production. .Literal cache FLAM uses a global literal cache to save memory and CPU when comparing strings. Here a hashtable is used. Its size can be defined via the environment variable `FL_LITERAL_CACHE_SIZE` (or system variable `&FLITCS`). In the debug log, the appropriate statistics are output, which may help you to make adjustments if necessary. .ZIP archives and PS-VB on Mainframes When creating ZIP archives, offsets and statistics values must eventually be written into the member headers, which requires repositioning (fseek()) within the file. This is possible for host datasets on z/OS via so-called RBA access. In a PS-VB file, this requires a tree in the background where the OS remembers which relative byte address (RBA) is in which block, in which records at which offset in the record. This is extremely time-consuming and if there are many members in the ZIP archive, this can increase the runtime considerably. The maintenance of this tree also costs a lot of CPU, which is not charged to the application. To avoid this, you should use file types for ZIP archives that are suitable for RBA access. Under z/OS, these are primarily never files in the USS. Alternatively, FLAM also supports streamed ZIP archives, as they were developed for piping under Unix systems. With the keyword `STREAM`, you can force a purely sequential write, which then also works with a PS-VB, but you should check whether ZIP tool used for extraction understands this streamed format. With PS-FB datasets, the RBA access is faster because you do not need a tree, but there is padding at the end of the ZIP file. Since ZIP archives have to be read from behind, many other tools cannot cope with this padding because they expect the ZIP directory and not 0 bytes or blanks. With FLAM this is not a problem, but as already mentioned, many other tools then recognize the ZIP file as incomplete or not even as a ZIP file. .z/OS CEEOPTs (from install.txt) For memory allocation, don't use the realloc control feature of CEE. ------------------------------------------------------------------------ _CEE_REALLOC_CONTROL=bound,percentage ------------------------------------------------------------------------ FLAM is only tested with default settings. With some memory allocation strategies out of memory errors can occur. For good performance and enough memory we recommend the IBM default runtime options except for run CEEOPTS below: ------------------------------------------------------------------------ //CEEOPTS DD * ALL31(ON) STACK(1M,1M,ANYWHERE,KEEP,512K,128K) HEAP(1M,1M,ANYWHERE,KEEP,8K,4K) /* ------------------------------------------------------------------------ With `ALL31(OFF)` and `HEAP(,,BELOW,,)` the available memory is too small for the stack in some cases, especially when using the FLUC subsystem, table or large-record support. Since version 5.1.25, FLAM uses application-specific run-time option defaults with the `CEEUOPT` assembly language source program to set these application-specific option defaults. The `CEEUOPT3` member used for 31 bit and the `CEEUOPT6` member used for 64 bits are located in hlq.FLAM.SRCLIB. We recommend building and linking the examples if you are going to write applications that use our APIs (e.g. FLCREC). For batch processing we recommend to create a storage report (RPTSTG(ON)) and define the CEEOPTS like recommended in the report. ... print CLE_DOCTYP_CHAPTER === JCL Considerations === 3.17. JCL Considerations If you use JCL to run FLCL batch programs, it is recommended to use the parameter file feature for inlining commands. Parameter files can also be used for each object and overlay (see example below): .Example ------------------------------------------------------------------------ //FLCLXCNV EXEC PGM=FLCL,REGION=0M,PARM='XCNV=DD:PARM' //STEPLIB DD DSN=&SYSUID..FLAM.LOAD,DISP=SHR //SYSOUT DD SYSOUT=* //SYSPRINT DD SYSOUT=* //PARM DD * INPUT( SAV.FILE ( FIO.REC ( NAME=s'~input.dataset' ) ) ) OUTPUT( SAV.FILE ( FMT.BLK ( METHOD=L4X #conform to PKWARE# ) CNV.ZIP ( ) FIO.ZIP=DD:ZIPARCH ) ) /* //ZIPARCH DD * ( NAME=s'~.output.ziparch' APPEND #add member to archive# ) /* //STDENV DD * LANG=de_DE.IBM1141 /* ------------------------------------------------------------------------ The parameter files (DD:PARM, DD:ZIPARCH) are read by the command line parser and executer (CLE/P). This works only in the expected manner if NUMBER=OFF is specified for this job in the ISPF editor. With NUMBER=ON, the numbering is part of the inline code and will result in a syntax error from the CLE/P. The same is valid for the DD name STDENV. In a parameter file, you can add a semicolon at the end of each line to handle the line number as comment. Since version 5.1.20-23372: On command level if no parameter given and no parameter file assigned, then the DD name 'FLAMPAR' is read. See the example below: ------------------------------------------------------------------------ //FLCLINFO EXEC PGM=FLCL,REGION=0M,PARM='INFO' //STEPLIB DD DSN=&SYSUID..FLAM.LOAD,DISP=SHR //SYSOUT DD SYSOUT=* //SYSPRINT DD SYSOUT=* //FLAMPAR DD * GET.SYSTEM /* ------------------------------------------------------------------------ To execute our commands we recommend the stack and heap definitions for the memory management of the language environment below (the IBM defaults are in comment above). If for example the increments to low (128 bytes), then the run and CPU time could increase significantly. ------------------------------------------------------------------------ //CEEOPTS DD * *RPTSTG(ON) ALL31(ON) *STACK(128K,128K,ANYWHERE,KEEP,512K,128K) LE default STACK(1M,1M,ANYWHERE,KEEP,512K,128K) *HEAP(32K,32K,ANYWHERE,KEEP,8K,4K) LE default HEAP(1M,1M,ANYWHERE,KEEP,8K,4K) /* ------------------------------------------------------------------------ Please use the storage report (above as comment) to determine the best values for your usage. With does a lot of work depending on the parameter given. It could possible depending on what is done with FLAM that better values increase performance and lower CPU utilization. With ALL31(OFF) and HEAP(,,BELOW,,) the available memory is too small for the stack in some cases, especially when using the FLUC subsystem, table or large-record support. Since version 5.1.25, FLAM uses application-specific run-time option defaults with the CEEUOPT assembly language source program to set these application-specific option defaults. The CEEUOPT3 member used for 31 bits and the CEEUOPT6 member used for 64 bits are located in hlq.FLAM.SRCLIB. We recommend to build and link the examples if you are going to write application that uses our APIs (e.g. FLCREC). To interpret commands correctly, some of the punctuation characters are on different code points depending on the EBCDIC CCSID used to enter these values. The environment variable LANG must be set to the correct CCSID to interpret tilde and other characters correctly. see <> of <> Since z/OS 2.1, a new service (CEEGTJS) is available to determine the values for exported JCL symbols in the application. The service is called dynamically and the language environment must be in the steplib concatenation to use it. If the service is not available, the exported JCL symbols cannot be used. If the environment variable replacement fails the exported JCL symbols are tried. This feature allows you to use exported JCL symbols in the control statements of FLCL like environment variables. This is mainly useful to build powerful JCL procedures. ------------------------------------------------------------------------ //E0 EXPORT SYMLIST=(CHAROUT,HASHALGO,HASHLEN) //S1 SET CHAROUT=IBM1141 //S2 SET HASHALGO=SHA512 //S3 SET HASHLEN=128 //CONV EXEC PGM=FLCL,PARM='CONV=DD:PARM' //STEPLIB DD DSN=FLAM.LOAD,DISP=SHR //SYSPRINT DD SYSOUT=* //SYSOUT DD SYSOUT=* //PARM DD *,SYMBOLS=JCLONLY READ.RECORD(FILE=DD:INPUT) WRITE.TEXT(FILE=DD:GZIP COMP.GZIP() HASH(OUTPUT=DD:HASH FORMAT=HEX CUT=/2 # important out-bytes=HASHLEN*2 if hex # CCSID= ALGO=&HASHALGO. ) ) //INPUT ... //GZIP ... //HASH ...DCB=(RECFM=FB,LRECL=&HASHLEN.)... ------------------------------------------------------------------------ The environment variables have a higher priority. If there is an environment variable with the same name as an exported JCL symbol, the value of the environment variable is used. System variables available as JCL symbols (if SYSSYM=ALLOW is specified in the class definition) can be exported and used in the control statements. Since version 5.1.17 of FLAM, the system symbols are generally available for replacment (e.g '...<&LDAY>...') if no environment variable with the same name exists. This means that the system symbols have the lowest priority in the replacement process. To export all JCL symbols for an application, you can use 'SYMLIST=*'. The "&name." replacment of JESS (DD *,SYMBOLS=JCLxxxx) can also be utilized if inline coding is used. For an external parameter file, however, the JCL symbols are only available with "". ... print CLE_DOCTYP_CHAPTER === SAF Consideration [[flcl.saf.considerations]] === 3.18. SAF Consideration Beginning with version 5.1.21 a lot of additional checks against a System authorization facility (SAF) can be activated. These SAF support gives for example an RACF administrator on z/OS the possibility to activate different security policies and control a lot of resources used by FLAM. * Several security policies (disable PCAP, ensure finger prints, minimal key length, ...) * CLE/P parameter strings (complete control about the functionality) * Control access to pre- and post-processing commands (executed on remote or local systems) * To secure all service provider interfaces (FAVE, FCPE, FKME) ** Control to which AV daemon the clear data is transfered * Control access to complete URLs containing connection, path, filename and member ** Allow to protect members of PDS/E, ZIP or FLAM archives * Secure SSH connections (Control user, server and port) * PGP key management (User ID to import, export, generate, delete) * Control access to PGP user and key IDs for signing and key exchange * Control methods, algorithms, modes and a lot more of the en/decryption component * Activate and enforce additional SMF logging (e.g. record type 119 (SSH)) * All feature codes of the FLAM license module The complete SAF setup is documented in the corresponding install.txt and can be simply extended on user request. For z/OS with RACF we recommend at minimum the definitions below (be careful with this example, we are no RACF specialists): ------------------------------------------------------------------------ //S01 EXEC PGM=IKJEFT01,DYNAMNBR=75,TIME=100,REGION=6M //SYSPRINT DD SYSOUT=* //SYSTSPRT DD SYSOUT=* //SYSTERM DD DUMMY //SYSUADS DD DSN=SYS1.UADS,DISP=SHR //SYSLBC DD DSN=SYS1.BRODCAST,DISP=SHR //SYSTSIN DD * RDEFINE CDT + $FLAM + CDTINFO(CASE(ASIS) /* mixed case profile names */ + DEFAULTRC(4) /* default */ + DEFAULTUACC(NONE) /* default */ + FIRST(ALPHA) /* profile name first char */ + GENERIC(ALLOWED) /* default */ + KEYQUALIFIERS(0) /* default */ + MAXLENGTH(246) /* maximum prof name length */ + OPERATIONS(NO) /* default */ + OTHER(ALPHA, /* prof name allows A-Z,a-z */ + NUMERIC, /* 0-9 */ + NATIONAL, /* #,@,$ */ + SPECIAL) /* all except blank ( ) , ; */ + POSIT(202) /* in user range 128-527 */ + RACLIST(ALLOWED) /* setr raclist allowed */ + SECLABELSREQUIRED(NO) /* default */ + SIGNAL(NO) /* default (no ENF signals) */ + ) SETROPTS CLASSACT(CDT) SETROPTS RACLIST(CDT) SETROPTS RACLIST(CDT) REFRESH //S02 EXEC PGM=IKJEFT01,DYNAMNBR=75,TIME=100,REGION=6M //SYSPRINT DD SYSOUT=* //SYSTSPRT DD SYSOUT=* //SYSTERM DD DUMMY //SYSUADS DD DSN=SYS1.UADS,DISP=SHR //SYSLBC DD DSN=SYS1.BRODCAST,DISP=SHR //SYSTSIN DD * PERMIT $FLAM CLASS(CDT) RESET /* clear permit list */ RALTER CDT $FLAM OWNER(SYS1) /* change ownership */ SETROPTS RACLIST(CDT) REFRESH //S03 EXEC PGM=IKJEFT01,DYNAMNBR=75,TIME=100,REGION=6M //SYSPRINT DD SYSOUT=* //SYSTSPRT DD SYSOUT=* //SYSTERM DD DUMMY //SYSUADS DD DSN=SYS1.UADS,DISP=SHR //SYSLBC DD DSN=SYS1.BRODCAST,DISP=SHR //SYSTSIN DD * SETROPTS GENERIC($FLAM) RDEFINE $FLAM + ** /* cover all entities */ + OWNER(SYS1) UACC(NONE) RDEFINE $FLAM GLOBAL.MUSTDEF OWNER(SYS1) UACC(NONE) RDEFINE $FLAM GLOBAL.POLICIES OWNER(SYS1) UACC(NONE) RDEFINE $FLAM GLOBAL.SMF.LOGGING OWNER(SYS1) UACC(NONE) RDEFINE $FLAM GLOBAL.CLP.CONTROL OWNER(SYS1) UACC(NONE) RDEFINE $FLAM GLOBAL.CMD.CONTROL OWNER(SYS1) UACC(NONE) RDEFINE $FLAM GLOBAL.AVE.CONTROL OWNER(SYS1) UACC(NONE) RDEFINE $FLAM GLOBAL.CPE.CONTROL OWNER(SYS1) UACC(NONE) RDEFINE $FLAM GLOBAL.KME.CONTROL OWNER(SYS1) UACC(NONE) RDEFINE $FLAM GLOBAL.EDC.CONTROL OWNER(SYS1) UACC(NONE) RDEFINE $FLAM GLOBAL.FIO.CONTROL OWNER(SYS1) UACC(NONE) RDEFINE $FLAM GLOBAL.FL4.CONTROL OWNER(SYS1) UACC(NONE) RDEFINE $FLAM GLOBAL.SSH.CONNECT OWNER(SYS1) UACC(NONE) RDEFINE $FLAM GLOBAL.PGP.KEYMNGM OWNER(SYS1) UACC(NONE) RDEFINE $FLAM GLOBAL.PGP.USERID OWNER(SYS1) UACC(NONE) RDEFINE $FLAM GLOBAL.PGP.KEYID OWNER(SYS1) UACC(NONE) RDEFINE $FLAM POLICY.LOW.ENTROPY OWNER(SYS1) UACC(NONE) RDEFINE $FLAM POLICY.LOG.INPUT OWNER(SYS1) UACC(NONE) RDEFINE $FLAM POLICY.SSH.AUTH.*.ALLOWED OWNER(SYS1) UACC(NONE) RDEFINE $FLAM POLICY.SSH.PCAP.ALLOWED OWNER(SYS1) UACC(NONE) RDEFINE $FLAM POLICY.SSH.WEAK.HOSTKEY.CHECK.ALLOWED OWNER(SYS1) UACC(NONE) RDEFINE $FLAM POLICY.SSH.CUSTOM.HOSTKEY.ALLOWED OWNER(SYS1) UACC(NONE) RDEFINE $FLAM POLICY.SSH.CUSTOM.KNOWN.HOST.FILE.ALLOWED OWNER(SYS1) UACC(NONE) RDEFINE $FLAM POLICY.SSH.CUSTOM.CONFIG.FILE.ALLOWED OWNER(SYS1) UACC(NONE) RDEFINE $FLAM POLICY.KEY.GENERATE.PGP.EXPIRD.REQIRED OWNER(SYS1) UACC(NONE) RDEFINE $FLAM POLICY.KEY.GENERATE.PGP.ALGO.RSA.KEYLEN OWNER(SYS1) UACC(NONE) RDEFINE $FLAM POLICY.KEY.GENERATE.PGP.ALGO.DSA.ALLOWED OWNER(SYS1) UACC(NONE) RDEFINE $FLAM POLICY.KEY.IMPORT.PGP.KIDVER OWNER(SYS1) UACC(NONE) RDEFINE $FLAM POLICY.KEY.IMPORT.PGP.DOUBLE.KIDS OWNER(SYS1) UACC(NONE) RDEFINE $FLAM POLICY.PGP.PWD OWNER(SYS1) UACC(NONE) RDEFINE $FLAM POLICY.PGP.PWD.LEN.ENC OWNER(SYS1) UACC(NONE) RDEFINE $FLAM POLICY.PGP.PWD.LEN.DEC OWNER(SYS1) UACC(NONE) RDEFINE $FLAM POLICY.PGP.ENFORCE.ENCRYPTION OWNER(SYS1) UACC(NONE) RDEFINE $FLAM POLICY.PGP.ENFORCE.INTEGRITY OWNER(SYS1) UACC(NONE) RDEFINE $FLAM POLICY.PGP.ENFORCE.SIGNING OWNER(SYS1) UACC(NONE) RDEFINE $FLAM POLICY.EDC.PARM.FILE.ALLOWED OWNER(SYS1) UACC(NONE) RDEFINE $FLAM POLICY.EDC.KEY.PRINT.ALLOWED OWNER(SYS1) UACC(NONE) RDEFINE $FLAM POLICY.EDC.KEY.INVERSE.ALLOWED OWNER(SYS1) UACC(NONE) RDEFINE $FLAM POLICY.EDC.NO.HEADER.ALLOWED OWNER(SYS1) UACC(NONE) RDEFINE $FLAM POLICY.EDC.NO.SALT.ALLOWED OWNER(SYS1) UACC(NONE) RDEFINE $FLAM POLICY.SYM.KEY.LEN.ENC OWNER(SYS1) UACC(NONE) RDEFINE $FLAM POLICY.SYM.KEY.LEN.DEC OWNER(SYS1) UACC(NONE) RDEFINE $FLAM POLICY.SYM.PWD.LEN.ENC OWNER(SYS1) UACC(NONE) RDEFINE $FLAM POLICY.SYM.PWD.LEN.DEC OWNER(SYS1) UACC(NONE) RDEFINE $FLAM FAVELIB.libfave OWNER(SYS1) UACC(NONE) RDEFINE $FLAM FAVEFUC.CLAMAVC OWNER(SYS1) UACC(NONE) RDEFINE $FLAM FAVEPAR.clamd.limes.de:3310 OWNER(SYS1) UACC(NONE) RDEFINE $FLAM FAVEIPH.clamd.limes.de OWNER(SYS1) UACC(NONE) RDEFINE $FLAM FAVEIPS.3310 OWNER(SYS1) UACC(NONE) PERMIT ** CLASS($FLAM) RESET /* clear permit list (optional)*/ PERMIT GLOBAL.MUSTDEF CLASS($FLAM) ID(*) ACC(CONTROL) /* PERMIT GLOBAL.POLICIES CLASS($FLAM) ID(*) ACC(NONE) ACTIVE */ PERMIT GLOBAL.SMF.LOGGING CLASS($FLAM) ID(*) ACC(ALTER)/*INACTIV*/ PERMIT GLOBAL.CLP.CONTROL CLASS($FLAM) ID(*) ACC(ALTER)/*INACTIV*/ PERMIT GLOBAL.CMD.CONTROL CLASS($FLAM) ID(*) ACC(ALTER)/*INACTIV*/ /* PERMIT GLOBAL.AVE.CONTROL CLASS($FLAM) ID(*) ACC(NONE) ACTIVE */ PERMIT GLOBAL.CPE.CONTROL CLASS($FLAM) ID(*) ACC(ALTER)/*INACTIV*/ PERMIT GLOBAL.KME.CONTROL CLASS($FLAM) ID(*) ACC(ALTER)/*INACTIV*/ PERMIT GLOBAL.EDC.CONTROL CLASS($FLAM) ID(*) ACC(ALTER)/*INACTIV*/ PERMIT GLOBAL.FIO.CONTROL CLASS($FLAM) ID(*) ACC(ALTER)/*INACTIV*/ /* PERMIT GLOBAL.FL4.CONTROL CLASS($FLAM) ID(*) ACC(ALTER) ACTIVE */ PERMIT GLOBAL.SSH.CONNECT CLASS($FLAM) ID(*) ACC(ALTER)/*INACTIV*/ PERMIT GLOBAL.PGP.KEYMNGM CLASS($FLAM) ID(*) ACC(ALTER)/*INACTIV*/ PERMIT GLOBAL.PGP.USERID CLASS($FLAM) ID(*) ACC(ALTER) /*INACTIV*/ PERMIT GLOBAL.PGP.KEYID CLASS($FLAM) ID(*) ACC(ALTER) /*INACTIV*/ PERMIT POLICY.SSH.AUTH.PUBLICKEY CLASS($FLAM) ID(*) ACC(READ) PERMIT POLICY.SSH.AUTH.PASSWORD CLASS($FLAM) ID(*) ACC(UPDATE) /* PERMIT POLICY.SSH.PCAP.ALLOWED CLASS($FLAM) ID(*) ACC(NONE)*/ PERMIT POLICY.SSH.WEAK.HOSTKEY.CHECK.ALLOWED CLASS($FLAM) ID(*) ACC(UPDATE) PERMIT POLICY.SSH.CUSTOM.HOSTKEY.ALLOWED CLASS($FLAM) ID(*) ACC(UPDATE) PERMIT POLICY.SSH.CUSTOM.KNOWN.HOST.FILE.ALLOWED CLASS($FLAM) ID(*) ACC(CONTRL) PERMIT POLICY.SSH.CUSTOM.CONFIG.FILE.ALLOWED CLASS($FLAM) ID(*) ACC(UPDATE) PERMIT POLICY.KEY.GENERATE.PGP.EXPIRD.REQIRED CLASS($FLAM) ID(*) ACC(UPDATE) PERMIT POLICY.KEY.GENERATE.PGP.ALGO.RSA.KEYLEN CLASS($FLAM) ID(*) ACC(UPDATE) /* PERMIT POLICY.KEY.GENERATE.PGP.ALGO.DSA.ALLOWED CLASS($FLAM) ID(*) ACC(NONE)*/ PERMIT POLICY.KEY.IMPORT.PGP.KIDVER CLASS($FLAM) ID(*) ACC(UPDATE) /* PERMIT POLICY.KEY.IMPORT.PGP.DOUBLE.KIDS CLASS($FLAM) ID(*) ACC(READ)*/ PERMIT POLICY.PGP.PWD CLASS($FLAM) ID(*) ACC(ALTER) PERMIT POLICY.PGP.PWD.LEN.ENC CLASS($FLAM) ID(*) ACC(CONTRL) PERMIT POLICY.PGP.PWD.LEN.DEC CLASS($FLAM) ID(*) ACC(ALTER) /* PERMIT POLICY.PGP.ENFORCE.ENCRYPTION CLASS($FLAM) ID(*) ACC(NONE)*/ /* PERMIT POLICY.PGP.ENFORCE.INTEGRITY CLASS($FLAM) ID(*) ACC(NONE)*/ PERMIT POLICY.PGP.ENFORCE.SIGNING CLASS($FLAM) ID(*) ACC(ALTER) PERMIT POLICY.EDC.PARM.FILE.ALLOWED CLASS($FLAM) ID(*) ACC(UPDATE) PERMIT POLICY.EDC.KEY.PRINT.ALLOWED CLASS($FLAM) ID(*) ACC(UPDATE) /* PERMIT POLICY.EDC.KEY.INVERSE.ALLOWED CLASS($FLAM) ID(*) ACC(NONE)*/ PERMIT POLICY.EDC.NO.HEADER.ALLOWED CLASS($FLAM) ID(*) ACC(UPDATE) PERMIT POLICY.EDC.NO.SALT.ALLOWED CLASS($FLAM) ID(*) ACC(READ) PERMIT POLICY.EDC.STATIC.KEY.ALLOWED CLASS($FLAM) ID(*) ACC(ALTER) PERMIT POLICY.EDC.STATIC.IV.ALLOWED CLASS($FLAM) ID(*) ACC(UPDATE) PERMIT POLICY.SYM.KEY.LEN.ENC CLASS($FLAM) ID(*) ACC(UPDATE) PERMIT POLICY.SYM.KEY.LEN.DEC CLASS($FLAM) ID(*) ACC(UPDATE) PERMIT POLICY.SYM.PWD.LEN.ENC CLASS($FLAM) ID(*) ACC(CONTRL) PERMIT POLICY.SYM.PWD.LEN.DEC CLASS($FLAM) ID(*) ACC(ALTER) PERMIT FAVELIB.libfave CLASS($FLAM) ID(*) ACC(READ) PERMIT FAVEFUC.CLAMAVC CLASS($FLAM) ID(*) ACC(READ) PERMIT FAVEPAR.clamd.limes.de:3310 CLASS($FLAM) ID(*) ACC(READ) PERMIT FAVEIPH.clamd.limes.de CLASS($FLAM) ID(*) ACC(READ) PERMIT FAVEIPS.3310 CLASS($FLAM) ID(*) ACC(READ) SETROPTS CLASSACT($FLAM) SETROPTS RACLIST($FLAM) SETROPTS RACLIST($FLAM) REFRESH ------------------------------------------------------------------------ First (in step 1 and 2) the general resource class $FLAM must be setup. The last step defines the rights for the certain entities. The recommendation defines all the policies and enable anti virus scanning only with the defined ClamAV daemon (DSN must be adjusted). The entities for command execution or parameter string can include whitespace or one of the other 4 invalid characters '(),;'. If such an invalid character is encountered in an entity string, it is replaced by an underscore '_' before the SAF check. For example the PDS(E) 'HLQ.PO(HUGO)' results in the resource name 'FIOURL.HLQ.PO_HUGO_'. The global pre-write pre-processing command 'ls -l' results in the resource name 'CMD.PRE.WRITE.GLOBAL.ls_-l'. ... print CLE_DOCTYP_PGMSYNOPSIS === FLCL Synopsis === 3.19. FLCL Synopsis The synopsis collects the help, syntax and other important information for a program, function or parameter. It is a kind of quick reference and will used over the complete hierarchies in this document. Below you can find for example the synopsis for program FLCL. ----------------------------------------------------------------------- HELP: Frankenstein Limes(R) Command Line for FLUC, FLAM and FLIES PATH: limes TYPE: PROGRAM SYNTAX: > flcl COMMAND/FUNCTION ... ----------------------------------------------------------------------- ... print CLE_DOCTYP_PGMSYNTAX === Syntax of FLCL === 3.20. Syntax of FLCL Below you can see the main syntax for this program. This content is printed on the screen if the built-in function <> is used. Each command can be entered as an argument list on the command line or in a parameter file. To define a parameter file the assignment character (`=`) must be used. For an argument list a blank or if the command (main table) is of type overlay a dot (`.`) or if the command is of type object a round bracket open (`(`) must be given. If the round bracket open is used then the corresponding round bracket close (`)`) at the end of the command is mandatory. The dot and parenthesis are in accordance with the normal syntax. If an argument list is used all parameters (argv[]) are concatenated to one long string and this string is passed to the parser, to allow usage of all features of the shell to build the command line input. To make sure that anything you enter is passed one by one to the parser please use double (WINDOWS(R), UNIX) or single (z/OS(R)) quotation marks at the beginning and end of the argument list. If the dot for overlays or parenthesis for objects are used then the complete command must be included in double quotation marks. The examples below show all possible command entries for the type object: ----------------------------------------------------------------------- :> FLCL command temp() dummy='str' :> FLCL command(temp() dummy='str') :> FLCL command "temp() dummy='str'" :> FLCL "command(temp() dummy='str')" ----------------------------------------------------------------------- For a command of type overlay it looks like: ----------------------------------------------------------------------- :> FLCL command temp() :> FLCL command.temp() :> FLCL command "temp()" :> FLCL "command.temp()" ----------------------------------------------------------------------- In a parameter file you can start with a dot for an overlay or with parenthesis for an object or with the argument (overlay) or argument list (object) directly. ------------------------------------------------------------------------ Syntax for program 'flcl': --| Commands: INFO/CONV/XCNV/ICNV/FLAM/GREP/XCHK/HASH/DIFF/UTIL/KEY --|--| flcl [OWNER=oid] command "... argument list ..." [MAXCC=[max][-min]] [QUIET/SILENT] --|--| flcl [OWNER=oid] command=" parameter file name " [MAXCC=[max][-min]] [QUIET/SILENT] --|--| flcl [OWNER=oid] command=>"parameter file name " [MAXCC=[max][-min]] [QUIET/SILENT] --|--| You can optionally specify: --|--|--| the owner id for this command (to use custom configuration files) --|--|--| the maximum condition code (max) to suppress warnings --|--|--| the minimum condition code (min), zero is returned if the condition code would be smaller --|--|--| QUIET disables the normal log output of the command line executer --|--|--| SILENT disables log and errors messages of the command line executer --| Built-in functions: --|--| flcl SYNTAX [command[.path] [DEPTH1 | ... | DEPTH9 | ALL]] --|--| flcl HELP [command[.path] [DEPTH1 | ... | DEPTH9 | ALL]] [MAN] --|--| flcl MANPAGE [function | command[.path][=filename]] | [filename] --|--| flcl GENDOCU [command[.path]=]filename [NONBR] [SHORT] --|--| flcl HTMLDOC [path] [NUMBERS] [TYPES] [SHORT] --|--| flcl GENPROP [command=]filename --|--| flcl SETPROP [command=]filename --|--| flcl CHGPROP command [path[=value]]* --|--| flcl DELPROP [command] --|--| flcl GETPROP [command[.path] [DEPTH1 | ... | DEPTH9 | DEPALL | DEFALL]] --|--| flcl SETOWNER name --|--| flcl GETOWNER --|--| flcl SETENV variable=value --|--| flcl GETENV --|--| flcl DELENV variable --|--| flcl LSTENV --|--| flcl HLPENV --|--| flcl TRACE ON | OFF | FILE=filename --|--| flcl CONFIG [CLEAR] --|--| flcl GRAMMAR --|--| flcl LEXEMES --|--| flcl LICENSE --|--| flcl VERSION --|--| flcl ABOUT --|--| flcl ERRORS ------------------------------------------------------------------------ ... print CLE_DOCTYP_PGMHELP === Help for FLCL === 3.21. Help for FLCL Here you can see the static main help for this program. This content is printed on the screen if the built-in function <> is used without any further arguments. ------------------------------------------------------------------------ Help for program 'flcl': --| Commands - to execute powerful subprograms --|--| flcl INFO - Provides various information --|--| flcl CONV - Simplified data conversion --|--| flcl XCNV - Extended data conversion --|--| flcl ICNV - Only character conversion --|--| flcl FLAM - Flam4 utility command --|--| flcl GREP - Find pattern in files --|--| flcl XCHK - Extended data validation --|--| flcl HASH - Hash calculation/verification --|--| flcl DIFF - Compares two data sources --|--| flcl UTIL - Executes simply functions --|--| flcl KEY - Several key management functions --| Built-in functions - to give interactive support for the commands above --|--| flcl SYNTAX - Provides the syntax for each command --|--| flcl HELP - Provides quick help for arguments --|--| flcl MANPAGE - Provides manual pages (detailed help) --|--| flcl GENDOCU - Generates auxiliary documentation (ASCIIDOC text format) --|--| flcl HTMLDOC - Generates the complete HTML documentation into a folder --|--| flcl GENPROP - Generates a property file --|--| flcl SETPROP - Activate a property file --|--| flcl CHGPROP - Change a property value in the currently active property file --|--| flcl DELPROP - Remove a property file from configuration --|--| flcl GETPROP - Show current properties --|--| flcl SETOWNER - Defines the current owner --|--| flcl GETOWNER - Show current owner setting --|--| flcl SETENV - Set an environment variable (defined in the config file) --|--| flcl GETENV - Show the environment variables (defined in the config file) --|--| flcl DELENV - Delete an environment variable (defined in the config file) --|--| flcl LSTENV - List status of all possible usable environment variables --|--| flcl HLPENV - List help message for all possible usable environment variables --|--| flcl TRACE - Manage trace capabilities --|--| flcl CONFIG - Shows or clear all the current configuration settings --|--| flcl GRAMMAR - Shows the grammar for commands and properties --|--| flcl LEXEMES - Shows the regular expressions accepted in a command --|--| flcl LICENSE - List license information for the program --|--| flcl VERSION - List version information for the program --|--| flcl ABOUT - Show information about the program --|--| flcl ERRORS - Show information about return and reason codes of the program For more information please use the built-in function 'MANPAGE' ------------------------------------------------------------------------ ... print CLE_DOCTYP_COMMANDS == FLCL Commands [[flcl.commands]] == 4. FLCL Commands Commands are used to run powerful subprograms. The command line processor compiles a table defined syntax in a corresponding preinitialized data structure. This structure will be mapped to the parameter structure of the corresponding subprogram. The subprogram can be executed with the defined arguments/parameters. To support these variable commands several built-in functions are available and described in a separate <>. Each supported command is explained in a separate section in this document. Each section contains a synopsis including the help message, the path, the type and the syntax followed by a detailed description. If an argument of this command is an object or overlay or, if a detailed description is available for this argument, a separate section with synopsis (help, path, type, syntax) and description is written, otherwise a bullet list is printed which contains the keyword, the syntax and the help message. For the syntax of an overlay braces `{}` are used to keep all possible arguments of an overlay logically together. These braces are not part of the real syntax. The braces are only written to demonstrate clearly that one of these arguments must be selected with the DOT operator (optional) for defining the overlay. To be compatible with certain shells, the features below are implemented: * Strings can be enclosed with single '' or double "" quotation marks * Integrated strings (without spaces) can also defined without quotes * Keywords can also start with "-" or "--" in front of the qualifier * If it unique then parenthesis and the dot can be omit for object and overlays Commands can be declared in deep hierarchical depth. In order to simplify their handling the path is a powerful instrument for managing only relevant parts of it. Because of that the path is printed for each synopsis. To run commands under different owners, the owner id can be defined in front of the command. To suppress the outputs of the command line executer you can set QUIET or SILENT as the last parameter. Additional to QUIET, SILENT suppressed also the error messages. These options has no effect of the outputs of the commands and built-in functions. For job control, the maximum (and minimum) condition code (MAXCC=[max][-min]) of the command execution can optionally be set as the last parameter for each command. The value 'max' is the maximum condition code. If the condition code, that would be returned if MAXCC was not specified, would be greater than 'max', it is reduced to the value of 'max'. If the condition code would be smaller than 'min', the actually returned condition code is reduced to 0. Both, 'max' and 'min', values are optional. To only specify the minimum, simply omit the 'max' value, i.e. the MAXCC value starts with a hyphen. Example: The clause `MAXCC=8-4` will set each condition code greater than 8 to 8 and each condition code smaller than 4 to 0, while `MAXCC=-4` only sets condition codes smaller than 4 to 0. ------------------------------------------------------------------------ flcl [OWNER=oid] command "... argument list ..." [MAXCC=[max][-min]] [QUIET] flcl [OWNER=oid] command=" parameter file name " [MAXCC=[max][-min]] [QUIET] ------------------------------------------------------------------------ The parameter for each command can be provided as argument list on the command line or as parameter file. [[CLEP.COMMAND.INFO]] === 4.1. Command 'INFO' .Synopsis ----------------------------------------------------------------------- HELP: Provides various information PATH: limes.flcl TYPE: OBJECT SYNTAX: > flcl INFO(NET.{},GET.{},FMT=LIST/XML,OUT='str'/STDOUT/STDERR,DIR(),LOG()) ----------------------------------------------------------------------- .Description The INFO command provides further information about local or remote files, CCSIDs among others. To use CONV and other commands it is sometimes useful to know which CCSIDs are supported or which members are in a FLAMFILE or how the file attributes are named. The system information (environment, default values, hardware support) may be helpful information to diagnose errors. To get syntax information, please use: ----------------------------------------------------------------------- flcl SYNTAX INFO ----------------------------------------------------------------------- To get help for a parameter, please use: ----------------------------------------------------------------------- flcl HELP INFO.parameter[.parameter[...]] ----------------------------------------------------------------------- To read the manual page for a parameter, please use: ----------------------------------------------------------------------- flcl MANPAGE INFO.parameter[.parameter[...]] or flcl HELP INFO.parameter[.parameter[...]] MAN ----------------------------------------------------------------------- To generate the user manual for a command, please use: ----------------------------------------------------------------------- flcl GENDOCU INFO=filename ----------------------------------------------------------------------- Parameters can be defined by the command line (directly or per file) or by properties read from the corresponding property file. .Examples ----------------------------------------------------------------------- flcl INFO get.system flcl INFO get.ccsids flcl INFO get.file='test.adc' out='list.txt' flcl INFO get.file='ssh://@server1/test.adc' out='list.txt' flcl INFO get.file='~.*' dir(rec) out='list.txt' flcl INFO get.fkme(help) ----------------------------------------------------------------------- .Arguments * `NUMBER: FMT=LIST/XML - Specify formatting of information [LIST]` ** `LIST - Provide information as list` ** `XML - Provide information in XML-structure` [[CLEP.COMMAND.CONV]] === 4.2. Command 'CONV' .Synopsis ----------------------------------------------------------------------- HELP: Simplified data conversion PATH: limes.flcl TYPE: OBJECT SYNTAX: > flcl CONV(READ.{},WRITE[{}...],DIR(),LOGGING.{},MESSAGE(),INVERSE='str'/STDOUT/STDERR,NORUN) ----------------------------------------------------------------------- .Description The CONV command converts data between various formats with an easy to use syntax. It was designed to simplify the use of the powerful Frankenstein Limes Universal Converter (FLUC). It can be used to read local or remote data sources (requires a FLIES or SSH server) of various formats, convert the data (e.g. decrypt, decompress and character conversion) and write the result to an unlimited amount of local or remote targets in different formats. As an example, the CONV command can be used to read an encoded, encrypted and compressed text file in UTF-16 from a Windows system, generate or verify a checksum, write each line as text record into a mainframe dataset with a dedicated record format (FB, VB, ...) in EBCDIC with ASA control characters and write an additional copy of these records in UTF-8 with line delimiters as PGP file to a remote ZIP file. All these conversions are done in one step to reduce CPU and I/O utilization. The following features are supported: * Different kinds of remote access protocols (SSH) * Different kinds of data sources (Files, Streams, Tables) * Different kinds of archive formats (ZIP, FLAMFILE) * Different kinds of I/O methods (Binary, Character, Text, Record, FLAM) * Different data encodings (HEX (Base16), Base32, Base64, ASCII armor) * Different encryption methods (FLAM, PGP) * Different compression methods (GZIP, BZIP2, XZ, ZSTD) * Automatic decoding of data encodings during read operations * Auto-detection and decoding of length fields in data blocks * Auto-detection of character sets and language based conversion * Auto-detection of freely defined table formats * Powerful character conversion based on CCSIDs with ** subset support, reporting, mapping, input assistance ** Unicode support within EBCDIC code pages to work with 3270 * Different logical data formatting (BIN, TEXT, XML, tables (FB-CSV-VB), ...) If the CONV command is not sufficient to meet your requirements, you can use the XCNV command which provides all full conversion capabilities of FLAM in a kind of expert mode with maximum configurability. The CONV command provides an easy to use subset of all conversion capabilities. In contrast to XCNV, the CONV command performs various types of auto detection and automated conversions to get a data representation that fits the current system and "makes sense" in the given context. To use the XCNV command, you must know what kind of data is read and can fully control how the data is written. To get syntax information, please use: ----------------------------------------------------------------------- flcl SYNTAX CONV ----------------------------------------------------------------------- To get help for a parameter, please use: ----------------------------------------------------------------------- flcl HELP CONV.parameter[.parameter[...]] ----------------------------------------------------------------------- To read the manual page for a parameter, please use: ----------------------------------------------------------------------- flcl MANPAGE CONV.parameter[.parameter[...]] or flcl HELP CONV.parameter[.parameter[...]] MAN ----------------------------------------------------------------------- To generate the user manual for the command, please use: ----------------------------------------------------------------------- flcl GENDOCU CONV=filename ----------------------------------------------------------------------- Parameters can be defined via command line (directly or by parameter file) or via properties taken from the corresponding property file .Example ----------------------------------------------------------------------- flcl CONV read.text(file='ssh://@server1/swift.txt.gz' hash(algo=SHA256)) write.record(file='.text(swift)' chrmode=SUB systab=iconv usrtab=DELA report='.report(swift)' format=VBA ccsid='IBM273') ----------------------------------------------------------------------- Reads remote a binary file, calculates a SHA-256 checksum in GNU style, automatically decompresses the data (as text cannot be compressed), performs a character conversion to UTF-8 (no report required), formats the data into text records and rest elements, convert the text records to old German EBCDIC (IBM-273) with transliteration, substitution and a report file (upgrade-proof) and writea the text records to a variable blocked dataset with ASA print control characters. The user table 'DELA' ensures that only the subset of characters are valid which are available in CP1252, IBM-1141 and ISO-8859-15. ----------------------------------------------------------------------- flcl CONV read.record(file='.text(swift)' ccsid='IBM273') write.text(method=CRLF, ccsid='LATIN1', comp.bzib()) ----------------------------------------------------------------------- Reads records from a VBA dataset, does a character conversion to UTF-8, formats the data as text with carriage return and line feed as delimiter, converts the text data to Latin-1 and writes the result to BZIP file. Conversion stopped if a character is not convertible. Assuming the input file is the output of the previous example, this cannot be the case because the user table DELA used to create the file '.text(swift)' prevents characters not available in Latin-1 (a.k.a. ISO-8859-1). The previous example would transliterate the EURO sign (`โ‚ฌ`) to 'EUR' because the CCSID was IBM-273 (does not include the EURO sign). To retain the EURO sign, the CCSID IBM-1141 (=IBM273+EURO) would have to be used in the previous example and ISO-8859-15 (=LATIN1=ISO-8859-1+EURO) in this example. ----------------------------------------------------------------------- flcl CONV read.file='my.data' write.record(file=stream, ccsid='IBM1141' recm=cut,chrm=sub,systab=iconv) ----------------------------------------------------------------------- Reads XML, text or binary data in encoded or clear form and converts the data to records which are printed to STDOUT (STREAM) in EBCDIC (IBM1141) where longer records are truncated (RECMODE=CUT), not convertible characters are transliterated (SYSTAB=ICONV) and if this not possible substituted (CHRMODE=SUB). With this command you can read any kind of file on mainframes and convert it to readable records. This command is used as part of the ISPF line command FLVIEW. It reads normal record oriented host datasets (PS, PDS(E) as VB/FB/UNDEFINED with or without ASA or machine print control character), VSAM-ESDS/RRDS/KSDS, FLAMFILEs, binary transfered text or XML files from other platforms, encoded and/or compressed text or XML files, etc. ------------------------------------------------------------------------ flcl conv read.char(file='~/myfb80.pgp' reclen=80 ccsid=IBM037 decrypt.pgp(fkm5())) write.record(file='~.MY.DATASET' falloc(recf=FB recl=80)) write.text(file='ssh://user@server/my.zip' method=unix ccsid=UTF-8 archive.zip()) ------------------------------------------------------------------------ Reads an encrypted PGP file containing a text file with fixed length records of length 80 with CCSID IBM-037 from another mainframe system and writes the records with the local CCSID (for example IBM-1141) to an FB80 dataset. A copy is written in UTF-8 (with 0x0A as record delimiter) to a ZIP archive on a remote SSH server. This example shows the exchange of fixed-length records through of block-oriented data formats. The CONV command supports the auto detection of 4 byte length fields (read.binary()) or text delimiters (read.text()) in the data to simply exchange variable length record formats. To exchange fixed length records you can use ------------------------------------------------------------------------ read.binary(reclen=80) ------------------------------------------------------------------------ or for text records ------------------------------------------------------------------------ read.char(recl=80) ------------------------------------------------------------------------ READ.CHAR(), in contrast to READ.TEXT(), was designed to read text without delimiters. A fixed length dataset contains no delimiters and the internal record length table must be built after all the decoding steps, but before character conversion. The RECLENGTH parameter in READ.TEXT() is used after character conversion if no delimiters and no internal record length table are found to wrap the data blocks into records. If character conversion is done from EBCDIC to UTF-8 like in the example above, it may happen that some characters are converted to multibyte UTF-8 characters. In this case, the record length is no longer fixed. This means that splitting a block into records after character conversion will result in incorrectly wrapped UTF-8 records. To wrap a block into fixed-length records, READ.BINARY() or READ.CHAR() should be used. ----------------------------------------------------------------------- flcl INFO get.file='my.data' ----------------------------------------------------------------------- Lists all determined file attributes including CCSID, delimiter, possible base encodings and (if appropriate) the member list of (concatenated) FLAMFILEs, GZIP, BZIP2, XZ files or a PGP dump. .Arguments * `SWITCH: NORUN - Don't run the command only show parsed parameter` [[CLEP.COMMAND.XCNV]] === 4.3. Command 'XCNV' .Synopsis ----------------------------------------------------------------------- HELP: Extended data conversion PATH: limes.flcl TYPE: OBJECT SYNTAX: > flcl XCNV(INPUT(),OUTPUT[()...],DIR(),LOG(),NORUN) ----------------------------------------------------------------------- .Description The XCNV command reads and writes various data formats, local or remote, on different platforms. It uses the read and write routines for original data of FLAM. More precisely, it provides all conversion capabilities of FLAM without a FLAM archive in the background. The XCNV command was designed to provide the full capacity of the powerful Frankenstein Limes Universal Converter (FLUC). It can be used to read and write local or remote data of different kinds, performing optional conversion steps in the process. For example, the XCNV command can be used to read an encoded, encrypted, compressed text file in UTF-16 from a PC platform and write the text records into a mainframe data set with a dedicated record format (FB, VB, ...) in EBCDIC with ASA or machine print control characters. You could even write the same data in UTF-8 with line delimiters as PGP file to a remote (SSH) ZIP archive in one step or vice versa. When using XCNV, you must know precisely what kind of data you read, as you can manipulate any kind of attribute and you have the complete control over each conversion step. Some of the formats and conversions that XCNV supports: * Different kinds of remote access protocols (IP-Nativ, MQ-Series, SSH) * Different kinds of data sources (Files, Streams, Tables, Archives) * Different kinds of IO methods (Binary, Character, Text, Record, FLAM) * Various data encoding formats (HEX aka. Base16, Base32, Base64) * Multiple encryption methods (FLAM, PGP) * Different compression methods (GZIP, BZIP2, XZ) * Powerful character conversion (Unicode, subsets, tranlitteration, reporting, mapping, NFD/NFC, input assistance) * Different logical data formatting methods (BIN, TEXT, XML, tables (FB-CSV-VB)) If the XCNV command is too complex or you need auto detection capabilities, you can use the simplified variant called CONV which also provides the full conversion capabilities of FLAM, but with more automatism. The CONV command provides an easy to handle subset of all the supported conversion capabilities. In contrast to XCNV, the CONV command does a lot of auto detection and automated conversions. It tries to guess how the data must be represent on the current system. For XCNV command, the user must know in detail what kind of data is read and can full control how the data is written. To get syntax information, please use: ----------------------------------------------------------------------- flcl SYNTAX XCNV ----------------------------------------------------------------------- To get help for a parameter, please use: ----------------------------------------------------------------------- flcl HELP XCNV.parameter[.parameter[...]] ----------------------------------------------------------------------- To read the manual page for a parameter, please use: ----------------------------------------------------------------------- flcl MANPAGE XCNV.parameter[.parameter[...]] or flcl HELP XCNV.parameter[.parameter[...]] MAN ----------------------------------------------------------------------- To generate the user manual for the command, please use: ----------------------------------------------------------------------- flcl GENDOCU XCNV=filename ----------------------------------------------------------------------- Parameters can be defined via command line (directly or in a file) or by properties taken from the corresponding property file. .Example ----------------------------------------------------------------------- flcl XCNV inp(sav.fil(fio.blk(file='ssh://@server1/my.file') cnv.hsh(format=bsd) cnv.gzp() cnv.chr(from='UTF-8' to='IBM1141') fmt.txt(suptws))) out(sav.fil(fmt.txt(method=HST) cnv.hsh(algo=SHA512) fio.rec(file='my.output' falloc(orga=SEQ,recf=VB,recl=512)) out(sav.fil(fmt.txt(method=UNIX) cnv.chr(to='latin1') cnv.pgp(pass=s'DUMMY') cnv.hsh(algo=SHA256) cnv.bas(armor()) fio.blk(file='~/my.pgp') fio.zip(file='ssh://user@server/my.zip') ----------------------------------------------------------------------- Reads a remote file as binary blocks, generates a SHA1 checksum in BSD style, performs GZIP decompression, converts characters from UTF-8 to IBM1141 and formats the data into text records and rest elements in the read operation. On first write, the text elements are formatted without a delimiter, a SHA-512 checksum is calculated for the result and the data elements are written to a record-oriented PS-VB-512 dataset. A second output specification produce a PGP file containing the text in LATIN1 (ISO-8859-1) encoding with 0x0A (UNIX) as delimiter. The binary PGP file is hashed with SHA256 in BSD style and then an ASCII-ARMOR encoding are done. These result is then written to a local file and in a remote ZIP archive. .Arguments * `SWITCH: NORUN - Don't run the command only show parsed parameter` [[CLEP.COMMAND.ICNV]] === 4.4. Command 'ICNV' .Synopsis ----------------------------------------------------------------------- HELP: Only character conversion PATH: limes.flcl TYPE: OBJECT SYNTAX: > flcl ICNV(IN['str'/STREAM/DUMMY...],OUT='str'/STREAM/DUMMY,FALLOC(),RECORD,METHOD=AUTO/BLOCK/RECORD/KEEP/SKIP,CASE=UPPER/LOWER/FOLD/SUPPER/SLOWER/USRTAB,FROM='str'/DEFAULT/ASCII/EBCDIC/BOMUTF/BOMUCS/SYSTEM/LOCAL,MODE=STOP/IGNORE/SUBSTITUTE/IDENTITY/TRANSLIT,BOM,KEPBOM,TO='str'/DEFAULT/ASCII/EBCDIC/SYSTEM/LOCAL,ENL2LF,ELF2NL,SUBCHR[num/SYSTEM...],SYSTAB=ICONV,USRTAB='str'/NPAS/SEPA/DELA/DLAX,ONEMAP,CMBFRM=NFD/NFC/AUTO/ON/OFF,REPORT='str'/STDOUT/STDERR,REMAIN,NOMKDIR,APPEND,REMOVE,EMPTYF=INFO/WARNING/ERROR/DELETE,DIR(),LOG(),NORUN) ----------------------------------------------------------------------- .Description The ICNV command converts local or remote files from one character encoding to another encoding set. More precisely, it converts the input file from the encoding given for the FROM option to an output file where the encoding is given in the TO option. Both encodings must be defined and supported by the platform you are running on. During this it supports: * Record or block oriented conversion * Stop, ignore or substitution of invalid or incomplete character * A free defined substitution character list * Different system substitution / transliteration tables * A user defined substitution table to change the system tables * Case management (upper, lower, folding and special casing) * Transliteration between subsets (mapping) and normalization * BOM management and automatic detection of char sets * Replacement of EBCDIC new line (0x15) by line feed (0x25) * Reporting of ignored or substituted characters The ICNV command runs the character conversion as part of the read operation of the Frankenstein Limes Universal Converter (FLUC). As default the block oriented binary read and write of files is used. With the keyword RECORD it will be possible to switch to record oriented binary read and write IO operations. Only binary formatting of the data is used. All the other conversion capabilities of FLUC are not available with this command. To get syntax information, please use: ----------------------------------------------------------------------- flcl SYNTAX ICNV ----------------------------------------------------------------------- To get help for a parameter, please use: ----------------------------------------------------------------------- flcl HELP ICNV.parameter[.parameter[...]] ----------------------------------------------------------------------- To read the manual page for a parameter, please use: ----------------------------------------------------------------------- flcl MANPAGE ICNV.parameter[.parameter[...]] ----------------------------------------------------------------------- To generate the user manual for the command, please use: ----------------------------------------------------------------------- flcl GENDOCU ICNV=filename ----------------------------------------------------------------------- Parameters can be defined by the command line (directly or per file) or by properties taken from the corresponding property file .Examples ----------------------------------------------------------------------- flcl ICNV in='input.txt' out='output.txt' from='UTF-8' to='ISO-8859-1' mode=ignore ----------------------------------------------------------------------- converts input from Unicode to the old West-European encoding ISO-8859-1 and discards non convertible characters in the output ----------------------------------------------------------------------- flcl ICNV in='input.txt' out='ssh://@server1/output.txt' from='ISO-8859-1' to='UTF-8' ----------------------------------------------------------------------- converts input from the old West-European encoding ISO-8859-1 to unicode on and write to a remote system. .Arguments * `SWITCH: KEPBOM - Keep byte order mark for faster conversion` * `SWITCH: REMAIN - Remain existing files (don't overwrite) [FALSE]` * `SWITCH: NOMKDIR - Don't create path if path not exists [FALSE]` * `NUMBER: EMPTYF=INFO/WARNING/ERROR/DELETE - Define special handling for empty files [NONE]` ** `INFO - Print info to the log` ** `WARNING - Print warning to the log (completion code 1)` ** `ERROR - Stop procession with error and special completion code` ** `DELETE - Delete the empty file (nothing written)` * `SWITCH: NORUN - Don't run the command only show parsed parameter` [[CLEP.COMMAND.FLAM]] === 4.5. Command 'FLAM' .Synopsis ----------------------------------------------------------------------- HELP: Flam4 utility command PATH: limes.flcl TYPE: OBJECT SYNTAX: > flcl FLAM(NETINP.{},NETOUT.{},COMPRESS/C,DECOMPRESS/UNCOMPRESS/D,REMAIN,APPEND/ADD,FLAMFILE/FL['str'/STREAM/DUMMY...],MEMBER/MEM='str',FLAMIN/FLAMI['str'/STREAM/DUMMY...],FLAMOUT/FLAMO='str'/STREAM/DUMMY,OUTPATH/OPATH='str',MODE/MO/CMPMODE=CX7/CX8/VR8/ADC/NDC/AES/FLAMENC,NDC,CRYPTOMODE/CRYMODE/ENCMODE/CRYPTMODE/CRYPTOM=OFF/AES/FLAMENC,CRYPTOKEY/CRYPTKEY/CRYPTOK='bin',PASSWORD/PASSW='bin',PAASCII='bin-ascii',PAEBCDIC='bin-ebcdic',PAXWORD='bin-hex',PARFILE/PARF/PAFILE/PARAMETER_FILE='str',PARDDN/PADDN/PARD='str',RECDELIM/RECDEL/RECD='bin-hex',RECFORMAT/RECFORM/RECFMT/RECFM/RECF=FIX/F/VAR/V/TEXT/STREAM/UNDEFINED/UNDEF/U/FIXBLK/FB/FIXS/FBS/VARBLK/VB/VARSPAN/VBS,RECSIZE/MAXSIZE/MAXS=num,INRECDELIM/IRECDEL/IRECD/IREC='bin-hex',INRECFORMAT/IRECFORM/IRECFMT/IRECFM/IRECF=EAF/FIX/DTEXT/TEXT/STREAM/VARIABLE/UNDEFINED/U/F/FIXBLK/FB/V/VARBLK/VB/FIXS/FBS/VARSPAN/VBS/VAR_2B/VAR2B_DATA/VAR_4B/VAR_ASCII/VAR_EBCDIC,INRECSIZE/IRECSIZE/IRECS=num,OUTRECDELIM/ORECDEL/ORECD/ORECDELIM/OUTDELIM/ORDELIM='bin-hex',OUTRECFORMAT/ORECFORM/ORECFMT/ORECFM/ORECF=EAF/FIX/DTEXT/TEXT/STREAM/VARIABLE/UNDEFINED/U/F/FIXBLK/FB/V/VARBLK/VB/FIXS/FBS/VARSPAN/VBS/VAR_2B/VAR2B_DATA/VAR_4B/VAR_ASCII/VAR_EBCDIC,OUTRECSIZE/ORECSIZE/ORECS/ORSIZE/OUTSIZE=num,BLKSIZE/BLKS=num,IBLKSIZE/INBLKSIZE/IBLOCKSIZE/INBLOCKSIZE/IBLK=num,OBLKSIZE/OUTBLOCKSIZE/OBLOCKSIZE/OBLK=num,ATTRIBUTES=NONE/COMMON/ALL,OPTION=CUT/NOCUT/SUPPRESS/NOSUPPRESS,CUT/TRUNCATE/TRU[=YES/NO],NOCUT/NOTRUNCATE,SUPPRESS,NOSUPPRESS,PADCHAR/PAD_CHAR/PAD='bin-hex',TRIMCHAR='bin-hex',MAXBUFFER/MAXB=num,MAXRECORDS/MAXR=num,FLAMCODE/FLAMC=SYSTEM/ASCII/EBCDIC,KMDLL/KMLIB/KMELIB='str',KMEXIT/KMEEXIT/KMEFUC/KME/KMFUNC='str',KMPARAMETER/KMEPAR/KMPARM/KMP='bin',HEADER/HE=YES/NO,COMMENT/COMM/LABEL='str',MSGFILE/LOGFILE/MSGF='str',SECUREINFO/SEC=YES/NO/IGNORE/MEMBER,MSGDISP/MSGD=TERMINAL/MSGFILE/SYSTEM,SHOW/SH=ALL/DIR/ATTRIBUTE/ERROR/NONE,INFO/I=YES/NO/HOLD,CHECKALL/CHECKA,CHECKFAST/CHECKF,HELP/LIST,FILEINFO/FI=YES/NO,CODETABLE='str',TRANSLATE/TRA='str'/E/A/A/E/NONE,NOPATH,CLIMIT/CLI=num,IPRCNTRL=DETACH/RETAIN/ERASE/REPLACE,IRPLFFD/IRP=num,OPRCNTRL=DETACH/RETAIN/ERASE/REPLACE,ORPLFFD/ORP=num,NOMKDIR/NOM,EXK10/EXK1='str',EXK20/EXK2='str',EXD10/EXD1='str',EXD20/EXD2='str',SPACE1=num,SPACE2=num,OSPACE1=num,OSPACE2=num,UNIT='str',OUNIT='str',STORCLASS/STORCLAS/STORC='str',OSTORCLASS/OSTORCLAS/OSTORC='str',VOLUME/VOL='str',OVOLUME/OVOL='str',DATACLASS/DATAC='str',ODATACLASS/ODATACLAS/ODATAC='str',MGMTCLASS/MGMTCLAS/MGMTC='str',OMGMTCLASS/OMGMTCLAS/OMGMTC='str',DSORG/DS/FCBTYPE=SEQ/PS/EDS/ESDS/KDS/KSDS/RDS/RRDS/LDS,IDSORG/IFCBTYPE=SEQ/PS/LIB/PDS/USS/EDS/ESDS/KDS/KSDS/RDS/RRDS,ODSORG/ODSO=SEQ/PS/LIB/PDS/USS/EDS/ESDS/KDS/KSDS/RDS/RRDS,ICLOSDISP/ICLO=REWIND/UNLOAD/LEAVE,CLOSDISP/CLO=REWIND/UNLOAD/LEAVE,OCLOSDISP/OCLO=REWIND/UNLOAD/LEAVE,DISPS=NEW/SHR/MOD/OLD,DISPN/DISPNORMAL=CATALOG/CATLG/DELETE/KEEP/UNCATALOG/UNCATLG,DISPA/DISPABNORMAL=CATALOG/CATLG/DELETE/KEEP/UNCATALOG/UNCATLG,ODISPS=NEW/SHR/MOD/OLD,ODISPN/ODISPNORMAL=CATALOG/CATLG/DELETE/KEEP/UNCATALOG/UNCATLG,ODISPA/ODISPABNORMAL=CATALOG/CATLG/DELETE/KEEP/UNCATALOG/UNCATLG,KEYDISP/KEYD=OLD/NEW/DEL,KEYLENGTH/KEYLEN/KEYL=num,OKEYPOSITION/OKEYPOS/OKEYP=num,OKEYLENGTH/OKEYL=num,ORGKEYPOS/ORGKEYPO/ORGKEYP=num,ORGKEYLEN/ORGKEYL=num,IKEYPOSITION/IKEYPOS/IKEYP=num,IKEYLENGTH/IKEYLEN/IKEYL=num,DEVICE/DEV=FILE/DISK/TAPE/FLOPPY/STREAMER/USER,IDEVICE/IDEV=FILE/DISK/TAPE/FLOPPY/STREAMER/USER,ODEVICE/ODEV=FILE/DISK/TAPE/FLOPPY/STREAMER/USER,SPLITMODE/SPLITM=NONE/SERIAL/PARALLEL,SPLITNUMBER/SPLITN=num,SPLITSIZE/SPLITS=num,FLAMDDN/FLAMD='str',IDDN['str'...],ODDN='str',MSGDDN/MSGDD='str',REMOVE/DELETE/INDELETE/IDELETE,FROM='str'/DEFAULT/ASCII/EBCDIC/BOMUTF/BOMUCS/SYSTEM/LOCAL,CHRMODE/SUBMODE=STOP/IGNORE/SUBSTITUTE/IDENTITY/TRANSLIT,TO='str'/DEFAULT/ASCII/EBCDIC/SYSTEM/LOCAL,LARGER,DIR(),LOG(),NORUN) ----------------------------------------------------------------------- .Description 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 on the command line, in a parameter file or as installation-specific default values. The FLAM command is backward-compatible with the FLAM4 utility and designed to work with FLAM4 archives, also called FLAMFILEs. There are a few differences to the old FLAM4 utility: * Completion/Condition codes are defined by CLE/P ** Return code 0, 4 and 8 have the same meaning (OK, WARNING, ERROR) ** Higher return codes are different and correspond to more critical issues ** There are also completion codes between 0 and 4 or 4 and 8, for example 1 if a warning in the log (can be deactivated) ** Special condition codes (>64) are the same ** Please use the built-in function 'ERRORS' or refer to the appendix 'Return Codes' for more information ** The main difference in completion codes are: *** DMS errors result in a return code of 8 and not 12 with FLAM5 *** If directory walk (wildcards) fail for all files FLAM5 returns 8 instead of 4 (it returns 4 like FLAM4 if not all files processed successfully) * The log output is in FLAM5 syntax and looks different to the old FLAM4 utilities but is now the same on each platform * The default value file is replaced by the FLAM5 property management (and much more intelligent default behavior) * The default behavior differs a little bit and if required the property management must be used to adjust it * If squared, curly brackets or other operators are required, the parameters must be enclosed in quotation marks ** This was minimized as much as possible to be compatible with the old syntax * If keywords used insaide a string value in a parameter assignment the string must enclose in quotation marks ** IDDN=FLAMDD will result in a syntax error, because FLAMDD is a valid keyword and CLP try to assign the value of FLAMDD ** IDDN='FLAMDD' will work because 'FLAMDD' is interpreted a string value * The selection of members to read from a FLAMFILE is now made via the member definition of the FLAMIN parameter ** As part of the URL: FLAMIN='FLAM.FILE.ADC/?HUGO.PDS(*)' ** Or by the new parameter MEMBER: MEMBER='HUGO.PDS(*)' ** Instead of: FLAMOUT= * The file name mapping (selection and replacement rules) is different and works like documented below (see INPUT TO OUTPUT NAME MAPPING) * No support of VSAM-LDS as FLAMIN or FLAMOUT (original data) on z/OS (not supported by LE) * The new FL5 system header is not supported by the old FLAM4 components ** VSAM data sets archived with FLAM4 can be reproduced with FLAM5 but not vice versa ** Sizes of original files are only known by FLAM5 (FLAM4 uses hard-coded defaults for primary (2/4MiB) and secondary space (40/50(MiB))) * Recreation of archived PDS load libraries is not yet supported within FLAM5 ** FLAM4 archived PDS load libraries and can be recreated ** FLAM4 does not support this for PDSEs ** FLAM5 does not support it at all till the XMIT support will be available * FLAM5 uses the CEE runtime environment (LE) and FLAM4 works LE-less on z/OS, which may result in different behavior ** Writing KSDS with new key position and length with FLAM5 results in re-ordered records and in a FIOPUT error on FLAM4 if reordering is required ** Empty records are really empty records (length=0) with FLAM4, with FLAM5 (LE) a empty record is written as one padding byte (see <>) * FLAM4 recognizes some errors only after an open of an output file, which may result in an empty file ** FLAM5 detects a lot of such errors before opening to avoid creation of empty files * FLAM5 recognizes from the combination of specified parameters whether compression or decompression is requested ** FLIMIN FLAMFILE (=COMP) and FLAMFILE FLAMOUT (=DECO) ** On z/OS, COMPRESS or DECOMPRESS must be specified for FLAM4 ** On Unix and Windows DECOMPRESS is the default for FLAM4 * The print control character handling is more intelligent in FLAM5 ** To be backward compatible: + In the case you set a certain record format without print control character and the original file contains print control character you must define OPRNCTR=RETAIN to ensure the print control character as part of the record like in FLAM4. If this new parameter not defined to RETAIN the print control character is not part of the record in this case. ** The provided record length in FLAM5 don't include the print control character (is one byte shorter then in FLAM4) * The default padding character is in FLAM4 always x'40' and in FLAM5 x'40' only used if text (ASA/MCC or CCSID defined) else it is x'00' * With FLAM4 for undefined files the record length must be provided by the caller, FLAM5 use the block size instead * The LIST switch on Windows will be the same as HELP. To get the current default values (properties) the built-in function GETPROP must be used. * FLAM4 on z/OS often requires upper case. FLAM5 syntax is not case sensitive,i.e. lower case can often be used * Given IRECFM and IRECSIZE are override by FLAM4 if the file is cataloged, FLAM5 try to allocate and open the file with the given parameter ** This result sometimes in errors with FLAM5 because the read file don't match with the given parameter (file attributes in conflict) ** Sometimes the runtime environment converts the data to the requested record format (original is VBA and requested is VB) * The FLAM4 UserIO is no longer supported for original data (`IDEVICE=USER` and `ODEVICE=USER` is ignored) * FLAM4 don't support large files (`DSNTYPE=LARGE`) at dynamic allocation, a corresponding data class must be used in this case ** FLAM5 supports large files by default if the amount of required tracks above the limit ** With version 5.1.22 the FLAM4 components set the DSNTYPE too large if more than 64K tracks allocated ** Only FLAM5 supports since version 5.1.22 extended attribute datasets (up to 16 TiB) * FLAM4 works with hard-coded defaults for space allocation (primary 2/4MiB secondary 40/50MiB) ** FLAM5 determines the file size and allocates depending on the space used by the original file by default ** This does not work for multi-volume datasets, in this case only the space used of the first volume will be allocated ** If you write a PO and you will extend this dataset later it is recommended to provide custom space values * FLAM5 supports also the default DD name 'FLAMOUT' at compress if 'FLAMFILE' not allocated and the same for 'FLAMIN' at read If the FLAM command is specified with the 'list' parameter, a list of the currently active settings of the default values is displayed; they can be modified by the system manager using the '-defaults' parameter. The FLAM command permits a separate FLAMFILE to be created from each original file (this requires input name mapping, which is differs to FLAM4). It is also possible to compress a group of original files into one FLAMFILE. The input files which are to be (de)compressed can either be specified by their fully qualified name or by patterns with wildcards. Output filenames can be explicit or generated by substitution rules. When decompressing, by default a file is to be restored with its original name and attributes. With the exception of the '-list' and '-defaults' parameters, there are equivalent FLAM parameters for all the elements of the command syntax, so that each setting can be entered either directly in the command line or in a parameter file which is referred to in the command by the parameter parfile=parameter file. Using a parameter file permits complicated keyboard inputs to be avoided, for example if settings which differ from the installed default values are required frequently. The following features are supported: * Different kinds of remote access protocols (SSH) * Different kinds of data sources (Files, Streams, Tables) * Different kinds of I/O methods (Binary, Character, Text, Record, FLAM) * Different compression modes (ADC, CX7, CX8, VR8 and NDC) * Different encryption modes (AES and FLAMENC) * Powerful character conversion based on CCSIDs If the FLAM command is not sufficient, you can use the CONV command which supports FLAMFILEs and other compression formats and provide various conversion and formatting modes. FLAM and CONV parameter are not identical. To get syntax information, please use: ----------------------------------------------------------------------- flcl SYNTAX FLAM ----------------------------------------------------------------------- To get help for a parameter, please use: ----------------------------------------------------------------------- flcl HELP FLAM.parameter[.parameter[...]] ----------------------------------------------------------------------- To read the manual page for a parameter, please use: ----------------------------------------------------------------------- flcl MANPAGE FLAM.parameter[.parameter[...]] or flcl HELP FLAM.parameter[.parameter[...]] MAN ----------------------------------------------------------------------- To generate the user manual for the command, please use: ----------------------------------------------------------------------- flcl GENDOCU FLAM=filename ----------------------------------------------------------------------- Parameters can be defined via command line (directly or through a parameter file) or via properties taken from the corresponding property file. .Example For the FLAM4 utility the command name 'flam' is default and can be omitted. The FLCL utility has no default command, in this case the command name 'FLAM' must be defined. ----------------------------------------------------------------------- flcl FLAM comp flamin=swift.txt flamfile=swift.fla inrecformat=stream ----------------------------------------------------------------------- Reads file in record format stream (usual text), compresses with default compression mode ADC, writes FLAMFILE. ----------------------------------------------------------------------- flcl FLAM deco flamfile=swift.fla flamout=swift.txt outrecformat=stream ----------------------------------------------------------------------- Reads and decompresses FLAMFILE, writes output file in record format stream. .Arguments * `SWITCH: NORUN - Don't run the command only show parsed parameter` [[CLEP.COMMAND.GREP]] === 4.6. Command 'GREP' .Synopsis ----------------------------------------------------------------------- HELP: Find pattern in files PATH: limes.flcl TYPE: OBJECT SYNTAX: > flcl GREP(NETINPUT.{},INPUT['str'/STREAM/DUMMY...],FROM='str'/DEFAULT/ASCII/EBCDIC/BOMUTF/BOMUCS/SYSTEM/LOCAL,PATTERN='str',NOCASE,EXTENDED,FORMAT='str'/LIST/CSV/XML/JSON/GREP,TO='str'/DEFAULT/ASCII/EBCDIC/SYSTEM/LOCAL,OUTPUT='str'/STREAM/DUMMY,NETOUTPUT.{},FALLOC(),DIR(),LOGGING.{},MESSAGE(),NORUN) ----------------------------------------------------------------------- .Description The GREP command searches for patterns in files using a Perl compatible regular expression. Writing regular expressions may seem like a daunting task if you never did so before. You can find a tutorial that will get you started quickly here: https://www.regular-expressions.info/quickstart.html Countless other tutorials and documentation for regular expressions can be found on the web. We recommend consulting these resources to familiarize yourself with regular expressions. Advanced users can find the complete syntax documentation for writing regular expression patterns by following this URL: https://www.pcre.org/current/doc/html/pcre2pattern.html The GREP command support directory walk using file lists with wildcards. Die `DIR` object can be used to control the directory walk. Below is a simple example. The default output will be `STREAM`, but in this case the matches are written to the file `result.txt`. ----------------------------------------------------------------------- flcl GREP input='test/*' pattern='Hugo' output='result.txt' dir(recursive) ----------------------------------------------------------------------- The GREP command is a simplification of the conversion subprogram using READ.AUTO() with default behavior except the parameter to specify the input. For each match a row with 5 columns is created and written with WRITE.TEXT(). The table format is as shown here: ----------------------------------------------------------------------- ROW(NAME='GREP' COLUMN(NAME='PATTERN' TYPE.STRING()) COLUMN(NAME='FILE' TYPE.STRING()) COLUMN(NAME='LINE' TYPE.STRING()) COLUMN(NAME='COLUMN' TYPE.STRING()) COLUMN(NAME='DATA' TYPE.STRING()) ) ----------------------------------------------------------------------- The row name is `GREP`. The column `PATTERN` contains the pattern used. The column `FILE` contains the complete URL with connection parameter, the filename and the optional member name. The column `LINE` contains the line number of the match record. The column `COLUMN` contains the character position in the line of the match record. The column `DATA` contains the matching record. For more information how to define row and column definitions see chapter <>. Compressed files are decompressed and encrypted files are decrypted, member of archives (ZIP, FLAM, ...) are searchable by using the corresponding switches in the `DIR` object. The match is done based on UTF-8 using neutral string format. Trailing whitespace is removed. The delimiter is not part of the data element used for matching. The `NOCASE' and `EXTENDED` switches can be used to control the matching algorithm. With the format parameter the output format can be defined. There are several default formats supported using a key word, but it is also possible to provide a row specification if a special format (other order of the columns or something like this) for the output is needed. The definitions of the default formats are: FORMAT=LIST ----------------------------------------------------------------------- FORMAT=CSV DEFAULT(TYPE=STRING NOHDLN SEPCHR=COLON FLDMTD=NONE NOCHECK) ROW(NAME='GREP' COLUMN(NAME='FILE') COLUMN(NAME='LINE') COLUMN(NAME='COLUMN') COLUMN(NAME='DATA') ) ----------------------------------------------------------------------- FORMAT=CSV ----------------------------------------------------------------------- FORMAT=CSV DEFAULT(TYPE=STRING) ROW(NAME='GREP' COLUMN(NAME='PATTERN') COLUMN(NAME='FILE') COLUMN(NAME='LINE') COLUMN(NAME='COLUMN') COLUMN(NAME='DATA') ) ----------------------------------------------------------------------- FORMAT=XML ----------------------------------------------------------------------- FORMAT=XML DEFAULT(TYPE=STRING COMMENT='') ROW(NAME='GREP' COLUMN(NAME='PATTERN' ROOT='GREP' PATH='&PATTERN') COLUMN(NAME='FILE' ROOT='GREP/FILE' PATH='&NAME' ) COLUMN(NAME='LINE' ROOT='GREP/FILE/MATCH' PATH='&LINE' ) COLUMN(NAME='COLUMN' ROOT='GREP/FILE/MATCH' PATH='&COLUMN' ) COLUMN(NAME='DATA' ROOT='GREP/FILE/MATCH' PATH='&DATA' ) ) ----------------------------------------------------------------------- FORMAT=JSON (currently realized using the TVD support) ----------------------------------------------------------------------- FORMAT=TVD DEFAULT(TYPE=STRING INDSIZE=2) ROW(NAME='GREP' COL(name='PATTERN' root='\W{\N*}\C/!!"grep":\B{\N*}\C' path='"pattern":\B"*"\C') COL(name='FILE' root='\W{\N*}\C/!!"grep":\B{\N*}\C' path='"file":\B"*"\C' ) COL(name='LINE' root='\W{\N*}\C/!!"grep":\B{\N*}\C/!!"match":\B[\N*]\C' path='{\W*}\C/"line":\B"*"\c') COL(name='COLUMN' root='\W{\N*}\C/!!"grep":\B{\N*}\C/!!"match":\B[\N*]\C' path='{\W*}\C/"column":\B"*"\c') COL(name='DATA' root='\W{\N*}\C/!!"grep":\B{\N*}\C/!!"match":\B[\N*]\C' path='{\W*}\C/"data":\B"*"\c') ) ----------------------------------------------------------------------- FORMAT=GREP (like LIST but without the character offset in the line) ----------------------------------------------------------------------- FORMAT=CSV DEFAULT(TYPE=STRING NOHDLN SEPCHR=COLON FLDMTD=NONE NOCHECK) ROW(NAME='GREP' COLUMN(NAME='FILE') COLUMN(NAME='LINE') COLUMN(NAME='DATA') ) ----------------------------------------------------------------------- These default formats can be used as a base for adjustments. In the example below the CSV format without the pattern and no headlines and the line number as first column is used. Here in JCL for z/OS: ----------------------------------------------------------------------- //FLCLGREP EXEC PGM=FLCL,REGION=0M,PARM='GREP=DD:PARM' //STEPLIB DD DSN=&SYSUID..FLAM.LOAD,DISP=SHR //SYSOUT DD SYSOUT=* //SYSPRINT DD SYSOUT=* //OUTPUT DD SYSOUT=* //FORMAT DD * "FORMAT=CSV DEFAULT(TYPE=STRING NOHDLN) ROW(NAME='GREP' COLUMN(NAME='LINE') COLUMN(NAME='FILE') COLUMN(NAME='DATA') )" /* //PARM DD * INPUT='.TEST.**' PATTERN='HUGO' NOCASE FORMAT=f'DD:FORMAT' TO=LOCAL OUTPUT='DD:OUTPUT' DIR( LINK ALIAS RECURSIVE ARCHIVE ) MESSAGE( ERRONLY SOURCE MATCH SUMMARY ) /* ----------------------------------------------------------------------- NOTE: The parameter string for the format must be enclosed in double quotation marks or better backticks (it is also known as backquote, grave, or grave accent) to be interpreted in total as one string. To get syntax information, please use: ----------------------------------------------------------------------- flcl SYNTAX GREP ----------------------------------------------------------------------- To get help for a parameter, please use: ----------------------------------------------------------------------- flcl HELP GREP.parameter[.parameter[...]] ----------------------------------------------------------------------- To read the manual page for a parameter, please use: ----------------------------------------------------------------------- flcl MANPAGE GREP.parameter[.parameter[...]] ----------------------------------------------------------------------- To generate the user manual for the command, please use: ----------------------------------------------------------------------- flcl GENDOCU GREP=filename ----------------------------------------------------------------------- Parameters can be set as arguments in the command line (directly or per file) or as properties taken from the corresponding property file. .Arguments * `STRING: INPUT['str'/STREAM/DUMMY...] - Name/URL of files to read [''==origin.ext]` ** `STREAM - Read from stdin or write to stdout` ** `DUMMY - Read EOF or write nothing` * `STRING: FROM='str'/DEFAULT/ASCII/EBCDIC/BOMUTF/BOMUCS/SYSTEM/LOCAL - Conversion from this CCSID` ** `DEFAULT - Use default CCSID (auto-detect)` ** `ASCII - Use default ASCII CCSID (environment)` ** `EBCDIC - Use default EBCDIC CCSID (environment)` ** `BOMUTF - Determine the correct UTF CCSID from byte order mark (BOM) only when reading` ** `BOMUCS - Determine the correct UCS CCSID from byte order mark (BOM)only when reading` ** `SYSTEM - Use system character set (environment/logical)` ** `LOCAL - Use local character set (auto-detect + system/physical)` * `STRING: PATTERN='str' - Pattern of regular expression for matching` * `SWITCH: NOCASE - Case insensitive matching` * `SWITCH: EXTENDED - Makes parser ignore whitespace and '#' comments within the pattern (can be used for readability)` * `STRING: FORMAT='str'/LIST/CSV/XML/JSON/GREP - Format definition for output (table object with 4 strings (PATTERN, FILE, LINE, DATA)) [LIST]` ** `LIST - Colon separated list (FILE:LINE:COLUMN:DATA)` ** `CSV - CSV format ("PATTERN","FILE","LINE","DATA")` ** `XML - XML format (...` ** `JSON - JSON format ({"GREP": { "PATTERN": "pattern" ...}})` ** `GREP - Colon separated list (FILE:LINE:DATA) without offset (like grep)` * `STRING: TO='str'/DEFAULT/ASCII/EBCDIC/SYSTEM/LOCAL - Conversion to this CCSID` ** `DEFAULT - Use default CCSID (UTF-8)` ** `ASCII - Use default ASCII CCSID (environment)` ** `EBCDIC - Use default EBCDIC CCSID (environment)` ** `SYSTEM - Use system character set (environment/logical)` ** `LOCAL - Use local character set (system/physical)` * `STRING: OUTPUT='str'/STREAM/DUMMY - Name/URL of file to write [''==origin.ext]` ** `STREAM - Read from stdin or write to stdout` ** `DUMMY - Read EOF or write nothing` * `SWITCH: NORUN - Don't run the command only show parsed parameter` [[CLEP.COMMAND.XCHK]] === 4.7. Command 'XCHK' .Synopsis ----------------------------------------------------------------------- HELP: Extended data validation PATH: limes.flcl TYPE: OBJECT SYNTAX: > flcl XCHK(INPUT(),DIR(),LOG()) ----------------------------------------------------------------------- .Description The XCHK command can be used, for example, to analyze local or remote files or members inside local or remote archives of various formats (without unpacking to a temporary file), generate their hash values, etc. For example, you can generate or verify hash values before or after any conversion, i.e. after decoding, decryption, decompression or character conversion. The XCHK command was designed to provide the full capacity of the powerful Frankenstein Limes Universal Converter (FLUC) without the write overhead. It supports all parameters of XCNV INPUT. To get syntax information, please use: ----------------------------------------------------------------------- flcl SYNTAX XCHK ----------------------------------------------------------------------- To get help for the parameters, please use: ----------------------------------------------------------------------- flcl HELP XCHK.parameter[.parameter[...]] ----------------------------------------------------------------------- To read the manual page for a parameter, please use: ----------------------------------------------------------------------- flcl MANPAGE XCHK.parameter[.parameter[...]] or flcl HELP XCHK.parameter[.parameter[...]] MAN ----------------------------------------------------------------------- To generate the user manual for the command, please use: ----------------------------------------------------------------------- flcl GENDOCU XCHK=filename ----------------------------------------------------------------------- Parameters can be defined via command line (directly or per file) or through properties read from the corresponding property file. .Examples Reads remote file "xzfile.xz" and calculates the checksum using the default hash algorithm. ----------------------------------------------------------------------- flcl xchk "input(sav.file(fio.blk(name=ssh://@server1/xzfile.xz) cnv.hsh() ))" ----------------------------------------------------------------------- Reads local file "xzfile.xz", decompresses it and calculates the checksum using the default hash algorithm. ----------------------------------------------------------------------- flcl xchk "input(sav.file(fio.blk(name=xzfile.xz) cnv.lxz() cnv.hsh() ))" ----------------------------------------------------------------------- Reads remote file "xzfile.xz", calculate the checksum using the SHA-1 hash algorithm, decompresses the file and calculates the checksum of the decompressed data using the MD5 hash algorithm. ----------------------------------------------------------------------- flcl xchk "input(sav.file(fio.blk(name=ssh://@server1/xzfile.xz) cnv.hsh(algo=SHA1) cnv.lxz() cnv.hsh(algo=MD5)))" ----------------------------------------------------------------------- A simplified command for hash calculation and verification is available under the name 'HASH'. [[CLEP.COMMAND.HASH]] === 4.8. Command 'HASH' .Synopsis ----------------------------------------------------------------------- HELP: Hash calculation/verification PATH: limes.flcl TYPE: OBJECT SYNTAX: > flcl HASH(FILE['str'/STREAM/DUMMY...],DIR(),LOG(),ALGO=MD5/RIPEMD128/RIPEMD160/SHA1/SHA224/SHA256/SHA384/SHA512/SHA3-224/SHA3-256/SHA3-384/SHA3-512/CRC8/CRC16/CRC24/CRC32/CRC32C/CRC40/CRC64,CHECK.{},FORMAT=GNU/BSD/HEX/BIN,CUT=num,OUTPUT='str'/STDOUT/STDERR,MEMBER='str',CCSID='str'/DEFAULT/ASCII/EBCDIC/SYSTEM/LOCAL,BLKSIZ=num) ----------------------------------------------------------------------- .Description The HASH command calculates or verifies checksums for one or more local or remote input files. Files are read in binary format. Beside hex and binary Checksums in GNU and BSD formats are supported, which are compatible with common tools like 'sha1sum' and 'md5sum' on UNIX systems. This can be useful to verify files transferred between different systems, especially to or from mainframes. If possible, hardware acceleration is used for hash calculation. The HASH command prints only minimal log output. For a more verbose output (e.g. statistics), please use the log object (see examples below). To get syntax information, please use: ----------------------------------------------------------------------- flcl SYNTAX HASH ----------------------------------------------------------------------- To get help for the parameters, please use: ----------------------------------------------------------------------- flcl HELP HASH.parameter[.parameter[...]] ----------------------------------------------------------------------- To read the manual page for a parameter, please use: ----------------------------------------------------------------------- flcl MANPAGE HASH.parameter[.parameter[...]] or flcl HELP XCHK.parameter[.parameter[...]] MAN ----------------------------------------------------------------------- To generate the user manual for the command, please use: ----------------------------------------------------------------------- flcl GENDOCU HASH=filename ----------------------------------------------------------------------- Parameters can be defined via command line (directly or per file) or through properties read from the corresponding property file. .Examples Calculate the checksum using the default hash algorithm (SHA1) for the file "fileToBeHashed.exe" in default format (GNU) to the default output file (LOG). ----------------------------------------------------------------------- flcl hash file=fileToBeHashed.exe ----------------------------------------------------------------------- Calculate the checksum using SHA-512 hash algorithm for the remote file "fileToBeHashed.exe". ----------------------------------------------------------------------- flcl hash file=ssh://@server1/fileToBeHashed.exe algo=sha512 ----------------------------------------------------------------------- Calculate the checksum using SHA-512 hash algorithm for the file "fileToBeHashed.exe" and write the result to the file "outhash.txt". ----------------------------------------------------------------------- flcl hash file=fileToBeHashed.exe algo=sha512 output=outhash.txt ----------------------------------------------------------------------- Calculate the checksum using SHA-512 hash algorithm for the file "fileToBeHashed.exe" and write the result to the file "outhash.txt" in IBM-1141 CCSID. ----------------------------------------------------------------------- flcl hash file=fileToBeHashed.exe algo=sha512 CCSID=IBM-1141 output=outhash1141.txt ----------------------------------------------------------------------- Verify the file "fileToBeHashed.exe" using SHA-512 hash algorithm by comparing to the checksum stored in file "outhash.txt". ----------------------------------------------------------------------- flcl hash file=fileToBeHashed.exe algo=sha512 check.file=outhash.txt ----------------------------------------------------------------------- Calculate the checksum using SHA-512 hash algorithm for the file "fileToBeHashed.exe". Print log output with the default filter (more output information) ----------------------------------------------------------------------- flcl hash "file=fileToBeHashed.exe algo=sha512 log(message(default))" ----------------------------------------------------------------------- If you want to get the hash value of the decompressed content of a file without decompressing it to a temporary file, please take a look at the XCHK command. It is a much more powerful command to analyze input files. .Arguments * `STRING: FILE['str'/STREAM/DUMMY...] - Name/URL of file to hash [''==origin.ext]` ** `STREAM - Read from stdin or write to stdout` ** `DUMMY - Read EOF or write nothing` * `NUMBER: ALGO=MD5/RIPEMD128/RIPEMD160/SHA1/SHA224/SHA256/SHA384/SHA512/SHA3-224/SHA3-256/SHA3-384/SHA3-512/CRC8/CRC16/CRC24/CRC32/CRC32C/CRC40/CRC64 - Hash algorithm [SHA1]` ** `MD5 - Message-Digest Algorithm 5 (128 bit)` ** `RIPEMD128 - RACE Integrity Primitives Evaluation Message Digest (128 bit)` ** `RIPEMD160 - RACE Integrity Primitives Evaluation Message Digest (160 bit)` ** `SHA1 - Secure Hash Algorithm 1 (160 bit)` ** `SHA224 - Secure Hash Algorithm 2 (224 bit)` ** `SHA256 - Secure Hash Algorithm 2 (256 bit)` ** `SHA384 - Secure Hash Algorithm 2 (384 bit)` ** `SHA512 - Secure Hash Algorithm 2 (512 bit)` ** `SHA3-224 - Secure Hash Algorithm 3 (224 bit)` ** `SHA3-256 - Secure Hash Algorithm 3 (256 bit)` ** `SHA3-384 - Secure Hash Algorithm 3 (384 bit)` ** `SHA3-512 - Secure Hash Algorithm 3 (512 bit)` ** `CRC8 - Cyclic Redundancy Check (8 bit)` ** `CRC16 - Cyclic Redundancy Check (16 bit)` ** `CRC24 - Cyclic Redundancy Check (24 bit)` ** `CRC32 - Cyclic Redundancy Check (32 bit)` ** `CRC32C - Cyclic Redundancy Check (32 bit) Castagnoli variant` ** `CRC40 - Cyclic Redundancy Check (40 bit)` ** `CRC64 - Cyclic Redundancy Check (64 bit)` * `NUMBER: FORMAT=GNU/BSD/HEX/BIN - Define printout format [GNU]` ** `GNU - Write output in GNU style` ** `BSD - Write output in BSD style` ** `HEX - Write output as hexadecimal string` ** `BIN - Write output as binary value (only in output file)` * `STRING: OUTPUT='str'/STDOUT/STDERR - Name of the output file [LOG]` ** `STDOUT - Write output to stdout` ** `STDERR - Write output to stderr` * `STRING: MEMBER='str' - Member name in GNU or BSD format [original name at read, target name at write]` * `NUMBER: BLKSIZ=num - Block size for read operations [65536]` [[CLEP.COMMAND.DIFF]] === 4.9. Command 'DIFF' .Synopsis ----------------------------------------------------------------------- HELP: Compares two data sources PATH: limes.flcl TYPE: OBJECT SYNTAX: > flcl DIFF(READ.{},COMPARE.{},LOGGING.{},MESSAGE(),FULLY,OFFSET,REPORT='str'/STDOUT/STDERR) ----------------------------------------------------------------------- .Description The DIFF command uses all reading capabilities of the CONV command to compare the clear net content of two data sources independent of the data format and representation. The comparison takes place on a logical level, based on the neutral FLAM5 elements. The DIFF function does not recognize insertions or deletions to/from either source. If is one byte or element more or less in the data of one of the sources, then the comparison will fail for the whole rest. This command does not support wildcards. As an example, the DIFF command can be used to compare the logical content of two XML files, where one file is in UTF-16LE and GZIP compressed and the other one is a host data set compressed, encrypted and in EBCDIC as FLAMFILE member. The DIFF command builds a neutral element list (UTF-8) and compares the parsed XML elements. The following features are supported: * Different kinds of remote access protocols (SSH) * Different kinds of data sources (Files, Streams, Tables) * Different kinds of archive formats (ZIP, FLAMFILE) * Different kinds of I/O methods (Binary, Character, Text, Record, FLAM) * Different data encodings (HEX (Base16), Base32, Base64, ASCII armor) * Different encryption methods (FLAM, PGP) * Different compression methods (GZIP, BZIP2, XZ, ZSTD) * Automatic decoding of data encodings during read operations * Auto-detection and decoding of length fields in data blocks * Auto-detection of character sets and language based conversion * Auto-detection of freely defined table formats * Powerful character conversion based on CCSIDs with ** subset support, reporting, mapping, input assistance ** Unicode support within EBCDIC code pages to work with 3270 * Different logical data formatting (BIN, TEXT, XML, tables (FB-CSV-VB), ...) Depending on the data formats, a dedicated method is used, to compare the logical data records or streams. If a compare of the data formats makes no sense (XML with records or blocks) then an error is issued. For example: If you use read.file='filename' and compare.file='filename' and the first file is binary and the second file is the compressed version of this binary data, then a list of binary blocks with different length is built. In this case, it makes no sense to compare the elements (they are several blocks of different sizes). Hence, we compare the logical data stream and not the element list. If the first file contains records from a host data set and the second file contains text records with trailing whitespace and line delimiter (=rest element), then only the net record elements are compared. If the first file is block-oriented, then we include the remaining rest element from the text parser in a data stream compare. With the switch 'FULLY' you can activate additional checks depending on the data formats, for example: * TEXT/TEXT: Compare the remaining rest (trailing whitespace and delimiter) * ASA-RECORD/ASA-RECORD: Compare the control character * REL-RECORD/REL-RECORD: Compare the slot numbers * XML/XML: Compare comments, formatting (whitespace) and DTD If you want to verify that two files are identical independent of the platform and representation, then don't use this switch. If you specified a report file and activate the 'OFFSET' switch, then byte offsets and byte values for each difference are written to the report file. NOTE: This can cause a very large report file! To get syntax information, please use: ----------------------------------------------------------------------- flcl SYNTAX DIFF ----------------------------------------------------------------------- To get help for a parameter, please use: ----------------------------------------------------------------------- flcl HELP DIFF.parameter[.parameter[...]] ----------------------------------------------------------------------- To read the manual page for a parameter, please use: ----------------------------------------------------------------------- flcl MANPAGE DIFF.parameter[.parameter[...]] or flcl HELP DIFF.parameter[.parameter[...]] MAN ----------------------------------------------------------------------- To generate the user manual for the command, please use: ----------------------------------------------------------------------- flcl GENDOCU DIFF=filename ----------------------------------------------------------------------- Parameters can be defined via command line (directly or by parameter file) or via properties taken from the corresponding property file .Example ----------------------------------------------------------------------- flcl DIFF read.file='./swift.txt.gz' compare.file='~.swift.fba' report='out.txt' ----------------------------------------------------------------------- This test reads text records and remaining rest elements from a text file which was compressed and for example encoded in ASCII-CP1252 and contains 0x0D0A as record delimiter. On the other side, an FBA host data set in EBCDIC is read and the ASA control characters are detached as attributes and trailing whitespeace is removed. Both files are converted to UTF-8 and only the net record elements are compared. ----------------------------------------------------------------------- flcl DIFF read.xml(file='test.xml.bz') compare.xml(file='test.xml') report='out.txt' fully offset ----------------------------------------------------------------------- This example requires and compares two XML files including comments, DTD and whitespace element by element. The report file contains the byte offsets for each difference. If you don't use the 'FULLY' switch, then a data stream compare is done, i.e. only tags, attributes and data elements are compared. ----------------------------------------------------------------------- flcl DIFF read.text(file='./test.txt.xz' suptws) compare.record(file='~.test.fba' suppad) report='~.test.out' offset ----------------------------------------------------------------------- The example reads a UNIX text from an LZMA compressed file and compares the text records with records from an FBA data set. In order to make this compare work, trailing whitespace must be removed from the UNIX file and padding characters from the fixed-block host file. The ASA control characters are detached by default. Both texts are converted to UTF-8 and only the net record data is compared. To simplify usage of this compare feature, there is a sample utility program SCFCUDIF. This program takes options and a list of filenames from command line for a logical compare of the resulting net data after decoding, decryption, decompression, character conversion and formatting as neutral FLAM elements. It uses the FLUCDIFF subprogram and writes the report to STDOUT. The first file is compared to all remaining files in the list and the program stops at the first error. ----------------------------------------------------------------------- Parameters: :> SCFCUDIF "[-f] [-o] [-m] [-r] [reportfile] filename1 filename2 [filename3 ... filenameN]" Options: -f Make a full compare of data or elements -o Print byte offsets and values to report file -m Minimize protocol output on STDERR -r The first given filename is used for the report file ----------------------------------------------------------------------- You can use this utility program to compare every type of supported file format. It supports comma separated lists, so that it can be used on mainframe system. The example below is taken from the JOBLIB(SCFCUDIF) member of your FLAM installation. ----------------------------------------------------------------------- //SCFCUDIF JOB 'SCFCUDIF',CLASS=A,MSGCLASS=X,NOTIFY=&SYSUID,REGION=0M //* //* SAMPLE JOB TO CALL THE SCFCUDIF SAMPLE PROGRAM //* //* THE SCFCUDIF SAMPLE PROGRAM USES THE FLUC SUB PROGRAM DIFF //* FOR A LOGICAL DATA COMPARE. YOU CAN PROVIDE SOME OPTIONS AND //* YOU MUST SUPPLY TWO OR MORE FILENAMES. TO SEE THE SYNTAX AND ALL //* OPTIONS RUN THE PROGRAM WITHOUT PARAMETERS. THE COMPLETE HELP IS //* WRITTEN TO SYSOUT. //* //SCFCUDIF EXEC PGM=SCFCUDIF,REGION=0M, // PARM=('-o,DD:INPUT,~.odat.psfba.gz') //STEPLIB DD DSN=&SYSUID..FLAM.LOAD,DISP=SHR //SYSOUT DD SYSOUT=* //SYSPRINT DD SYSOUT=* //INPUT DD DSN=TST.IDAT.PSFBA,DISP=SHR //* ----------------------------------------------------------------------- The sample program SCFCUDIF is available on all platforms and the source is part of each FLAM installation (sample or SRCLIBC). You can simply adjust this program and use the provided build instructions (makefile or SBUILD job) to make your own utility. .Arguments * `SWITCH: FULLY - Make a fully compare of data and elements [FALSE]` * `SWITCH: OFFSET - Print byte offsets and values to report file [FALSE]` * `STRING: REPORT='str'/STDOUT/STDERR - Generate a report file [NONE]` ** `STDOUT - Write output to stdout` ** `STDERR - Write output to stderr` [[CLEP.COMMAND.UTIL]] === 4.10. Command 'UTIL' .Synopsis ----------------------------------------------------------------------- HELP: Executes simply functions PATH: limes.flcl TYPE: OBJECT SYNTAX: > flcl UTIL(NET.{},RUN.{},OUT='str'/STDOUT/STDERR/DUMMY,DIR(),LOG()) ----------------------------------------------------------------------- .Description The UTIL command executes a function on a wildcard-based list of files. This command allows to run simple system functions like deleting or listing files that match a provided pattern which may contain wildcards. This is mainly useful on mainframe systems, for example, to find all libraries containing a certain member or to delete any kind of file under a certain qualifier. The UTIL command prints only minimal log output. For a more verbose output (e.g. notices), please use the log object (see examples below). To get syntax information, please use: ----------------------------------------------------------------------- flcl SYNTAX UTIL ----------------------------------------------------------------------- To get help for a parameter, please use: ----------------------------------------------------------------------- flcl HELP UTIL.parameter[.parameter[...]] ----------------------------------------------------------------------- To read the manual page for a parameter, please use: ----------------------------------------------------------------------- flcl MANPAGE UTIL.parameter[.parameter[...]] or flcl HELP UTIL.parameter[.parameter[...]] MAN ----------------------------------------------------------------------- To generate the user manual for a command, please use: ----------------------------------------------------------------------- flcl GENDOCU UTIL=filename ----------------------------------------------------------------------- Parameters can be defined by the command line (directly or per file) or by properties read from the corresponding property file. .Examples ----------------------------------------------------------------------- flcl UTIL run.list='**(CSFMOD01)' # list all libs containing this member flcl UTIL run.remove='~.TEST.**' # deletes all test files under SYSUID flcl UTIL run.remove='*.txt' log(message(default)) # activate default logging ----------------------------------------------------------------------- [[CLEP.COMMAND.KEY]] === 4.11. Command 'KEY' .Synopsis ----------------------------------------------------------------------- HELP: Several key management functions PATH: limes.flcl TYPE: OBJECT SYNTAX: > flcl KEY(NET.{},IMPORT[{}...],GENERATE[{}...],EXPORT[{}...],DELETE[{}...],LIST[{}...],DIR(),LOG()) ----------------------------------------------------------------------- .Description The KEY command can be used to manage keys for several cryptographic systems and infrastructures. With the KEY command, you can, for example, generate, export and import keys for the FLAM PGP support. The KEY command utilizes the FLAM key management extension version 5 to support several hardware security modules (HSM) or crypto interfaces (PKCS#11). Normally, these functions are realized by a key management solution and FLAM supposes the static keys for encryption and signing are in place. But on some platforms, there is no solution readily available to manage PGP or other kinds of keys. In this case, these functions can be used to prepare the crypto environment so that FLAM can be used to protect confidentiality, integrity and completeness of your data. To get syntax information, please use: ----------------------------------------------------------------------- flcl SYNTAX KEY ----------------------------------------------------------------------- To get help for a parameter, please use: ----------------------------------------------------------------------- flcl HELP KEY.parameter[.parameter[...]] ----------------------------------------------------------------------- To read the manual page for a parameter, please use: ----------------------------------------------------------------------- flcl MANPAGE KEY.parameter[.parameter[...]] or flcl HELP KEY.parameter[.parameter[...]] MAN ----------------------------------------------------------------------- To generate the user manual for a command, please use: ----------------------------------------------------------------------- flcl GENDOCU KEY=filename ----------------------------------------------------------------------- Parameters can be defined by the command line (directly or per file) or by properties read from the corresponding property file. .Examples ----------------------------------------------------------------------- flcl KEY import.pgp(file='keyFile.pgp') # import keys from file keyFile.pgp ----------------------------------------------------------------------- ... print CLE_DOCTYP_OTHERCLP == API Strings [[flcl.api.strings]] == Appendix A. API Strings The additional CLP strings below are available in the following APIs: * FLUC byte interface for C (FLCBYT) * FLUC record interface for COBOL/PL1/HLAS (FLCREC) * FLUC stream buffer interface for C++ (FLCBYTBF) * FLUC stream class interface for Java (FLCBYTJS) When opening a file through these APIs, a format string must be passed to describe the format in which data is returned (read mode) or expected (write mode) by the respective interface. A state string containing some additional meta data is returned by (read mode) or can be passed to (write mode) the file open function. To read or write a file through these interfaces, the 'READ' and 'WRITE' overlays of the 'CONV' command or the 'INPUT' and 'OUTPUT' object of the 'XCNV' command can be used in the corresponding file open function (ASM/C/COBOL/PL1) or constructor (C++/Java). ------------------------------------------------------------------------ void* file1=fcbopen("read.file='test.txt.gz.pgp'","format.text(ccsid=DEFAULT)") void* file2=fcbopen("input(sav.fil(fio.rec(name='DD:INPUT')))","format.record()") ------------------------------------------------------------------------ If format.element() is used, some data conversions can be applied on a per-element basis. Conversions are applied when using the read or write functions of the byte/record interface that end with the letter v. These functions require the handle to a previously opened element converter. Multiple different element converters can be open at a time. To open a converter, a conversion string must be supplied. The 'read' conversion string describes how an element data type read from application memory is converted to the internal neutral FLAM5 representation. The 'write' conversion string defines how a neutral FLAM5 element is written to application memory when reading from a file. ------------------------------------------------------------------------ void* conv1=fcbopenv(file1,"write.string(ccsid=DEFAULT whitespace=collapse)") void* conv2=fcbopenv(file2,"conv.integer(from(format.str(chrset=EBCDIC)) to(format.bin(width=w32 endian=big)))") ------------------------------------------------------------------------ A from-to conversion string can be used to convert data types, e.g. numbers, between different representations. This could be used, for example, to convert the string representation of a number that was read from an XML file to a binary or BCD representation or a string of fixed length. ------------------------------------------------------------------------ void* file1=fcbopen("read.xml(file='DD:INPUT'","format.element()") void* kyw1=fcbopenv(file1,"write.string(ccsid=DEFAULT whitespace=collapse nullterm)") void* int2=fcbopenv(file1,"conv.integer(from(format.str(chrset=UTF-8)) to(format.bin()))") void* flt2=fcbopenv(file1,"conv.float(from(format.str(chrset=UTF-8)) to(format.bcd(SIGNED TYPE=ZONED INTDIGITS=8 FRACDIGITS=2)))") ------------------------------------------------------------------------ The format strings are also used to configure the FLUC subsystem on z/OS and the FlucFS on Unix. [[CLEP.OTHERCLP.READ-FORMAT]] === Appendix A.1. String 'READ-FORMAT' .Synopsis ----------------------------------------------------------------------- HELP: Read format string for FLUC byte, stream and record interfaces PATH: limes.flcbyt TYPE: OVERLAY SYNTAX: > flcbyt READ-FORMAT.{BINARY()/CHAR()/TEXT()/XML()/RECORD()/TABLE()/ELEMENT()} ----------------------------------------------------------------------- .Description When reading data via the byte or record interface, you can specify how to format the data (binary, character, text, xml, ...), use different conversions (Base64, OpenPGP, GZIP, CHRSET, ...) executed sequentially and different kinds of I/O methods (block, record, text, FLAM4, ...). This means that you can read compressed, encrypted and encoded files, where you can change the character set and other things as part of the read operation. Through the format string of our application programming interfaces, you specify how the data is transformed into a sequential data stream, records or FLAM5 elements before being stored in application memory. For example, if the data contains text, you can specify which delimiter to add after each line, which character set the output should be in and so on. For stream-oriented data handling, you can choose between binary, character, text and XML formatting. For read operations, you can use the auto detection capabilities. For example: ------------------------------------------------------------------------ fcbopen("read.file='filename'","format.record()") ------------------------------------------------------------------------ This results in any kind of file (encoded, encrypted and/or compressed) being converted to records. If the content is XML, then the XML data is pretty printed into records. If it is text, then the data is parsed based on the containing delimiters. If it is binary and record lengths are detected, then the records are provided one by one. If it is binary and no record lengths are known or detected, then the data is wrapped into records. .Record formatting If you use record formatting, then the read and write functions do not operate like in stream-oriented I/O. Instead, the behavior is more similar to the fread (GET) and fwrite (PUT) operations in z/OS with 'type=record', except that you can define whether records are truncated (size>0) or a length error occurs (size==0) of the provided buffer is too short. With size=-1 (SIZE_MAX), there is also a zero-copy mode for optimized performance (LOC). The record formatting can be useful for normal text files to read the text record-by-record without the delimiter and null termination at the end. .Element formatting FLAM5 elements are parsed data elements with a type, a length, a value and more. If the element data contains printable characters, then these characters are encoded in UTF-8 by default, but can also be converted as needed. With element formatting, you can read and write a serialized form of FLAM5 elements. For example, it can be used to tokenize an XML document and read these tokens (elements) for further processing. .Examples The format string uses the syntax of the 'format' union which was specifically designed for the byte and record interface to format a byte stream based on the FLAM elements. The zero-terminated string must start with 'format.' followed by the corresponding method. ------------------------------------------------------------------------ "format.text(method=CRLF suptws ccsid='UTF-16LE')" "format.bin()" "format.char(ccsid=DEFAULT)" "format.record(ccsid='IBM-1141')" "format.element(ccsid=1047)" ------------------------------------------------------------------------ The file string defines how the FLAM elements are read from or written to the file. The format string defines how the FLAM elements are converted into a byte stream, records or elements. [[CLEP.OTHERCLP.WRITE-FORMAT]] === Appendix A.2. String 'WRITE-FORMAT' .Synopsis ----------------------------------------------------------------------- HELP: Write format string for FLUC byte, stream and record interfaces PATH: limes.flcbyt TYPE: OVERLAY SYNTAX: > flcbyt WRITE-FORMAT.{BINARY()/CHAR()/TEXT()/XML()/RECORD()/TABLE()/ELEMENT()} ----------------------------------------------------------------------- .Description When writing data via the byte or record interface, you can define how to format the data (binary, character, text, xml, ...), use different conversions (Base64, OpenPGP, GZIP, CHRSET, ...) executed sequentially and different kinds of I/O methods (block, record, text, FLAM4, ...). This means that you can write compressed, encrypted and encoded files, where you can change the character set and other things as part of the write operation. Through the format string of our application programming interfaces, you specify in which format your application passes its data to the interface, be it a sequential data stream, records or FLAM5 elements. For example, if you pass text records, you can define which delimiter to add after each line, which character set the output should be in and so on to write a text file correctly formatted for the target platform. For stream-oriented data handling, you can choose between binary, character, text and XML formatting. .Record formatting If you use record formatting, then the read and write functions do not operate like in stream-oriented I/O. Instead, the behavior is more similar to the fread (GET) and fwrite (PUT) operations in z/OS with 'type=record', except that you can define whether records are truncated (size>0) or a length error occurs (size==0) of the provided buffer is too short. With size=-1 (SIZE_MAX), there is also a zero-copy mode for optimized performance (LOC). .Element formatting FLAM5 elements are parsed data elements with a type, a length, a value and more. If the element data contains printable characters, then these characters are encoded in UTF-8 by default, but can also be converted as needed. With element formatting, you can read and write a serialized form of FLAM5 elements. For example, it can be used to produce a well-formed XML document from a sequence of XML tokens. .Examples The format string uses the syntax of the 'format' union which was specifically designed for the byte and record interface to format a byte stream based on the FLAM elements. The zero-terminated string must start with 'format.' followed by the corresponding method. ------------------------------------------------------------------------ "format.text(method=CRLF suptws ccsid='UTF-16LE')" "format.bin()" "format.char(ccsid=DEFAULT)" "format.record(ccsid='IBM-1141')" "format.element(ccsid=1047)" ------------------------------------------------------------------------ The file string defines how the FLAM elements are read from or written to the file. The format string defines how the FLAM elements are converted into a byte stream, records or elements. [[CLEP.OTHERCLP.CONV-READ]] === Appendix A.3. String 'CONV-READ' .Synopsis ----------------------------------------------------------------------- HELP: Read conversion string for FLUC byte, stream and record interfaces PATH: limes.flcbyt TYPE: OVERLAY SYNTAX: > flcbyt CONV-READ.{BINARY()/STRING()/INTEGER()/FLOAT()} ----------------------------------------------------------------------- .Description The READ overlay for an element data conversion allows to choose a type specific conversion when writing. It specifies how the data is read from application memory and converted into a neutral FLAM5 data type. With 'format.element()', you can use a set of functions with names ending with the letter v in the byte and record interface. These functions accept an additional conversion handle as parameter to replace the default conversion (e.g. a simple copy) from or to the application memory by an individual conversion. You can open an unlimited number of converters to apply different conversions to different elements. The currently supported data types and conversions are explained in a dedicated chapter. [[CLEP.OTHERCLP.CONV-WRITE]] === Appendix A.4. String 'CONV-WRITE' .Synopsis ----------------------------------------------------------------------- HELP: Write conversion string for FLUC byte, stream and record interfaces PATH: limes.flcbyt TYPE: OVERLAY SYNTAX: > flcbyt CONV-WRITE.{BINARY()/STRING()/INTEGER()/FLOAT()} ----------------------------------------------------------------------- .Description The WRITE overlay for a element data conversion allows to choose a type specific conversion when reading. It specifies how the data is converted from a neutral read FLAM5 data type and written to application memory. With 'format.element()', you can use a set of functions with names ending with the letter v in the byte and record interface. These functions accept an additional conversion handle as parameter to replace the default conversion (e.g. a simple copy) from or to the application memory by an individual conversion. You can open an unlimited number of converters to apply different conversions to different elements. The currently supported data types and conversions are explained in a dedicated chapter. [[CLEP.OTHERCLP.FROM-TO-CONV]] === Appendix A.5. String 'FROM-TO-CONV' .Synopsis ----------------------------------------------------------------------- HELP: Conversion string for FLUC byte, stream and record interfaces PATH: limes.flcbyt TYPE: OVERLAY SYNTAX: > flcbyt FROM-TO-CONV.{BINARY()/STRING()/INTEGER()/FLOAT()/MEMORY()} ----------------------------------------------------------------------- .Description The CONV overlay for element data conversion allows to choose a type specific conversion. It specifies how the data is read from and written to application memory. With 'format.element()', you can use a set of functions with names ending in the letter v in the byte and record interface. These functions accept an additional conversion handle as parameter to replace the default conversion (e.g. a simple copy) from or to the application memory by an individual conversion. You can open an unlimited number of converters to apply different conversions to different elements. The currently supported data types and conversions are explained in a dedicated chapter. [[CLEP.OTHERCLP.STATE]] === Appendix A.6. String 'STATE' .Synopsis ----------------------------------------------------------------------- HELP: State string for FLUC byte, stream and record interfaces PATH: limes.flcbyt TYPE: OBJECT SYNTAX: > flcbyt STATE(ORGF='str'/STREAM/DUMMY,FILE='str'/STREAM/DUMMY,MEMBER='str',COMMENT='str',CHRSET=NONE/SYSTEM/ASCII/UCS1/UTF8/EBCDIC/UCS2BE/UTF16BE/UCS2LE/UTF16LE/UCS4BE/UTF32BE/UCS4LE/UTF32LE/LOCAL,CCSID='str',SPACE=num,BLKSIZE=num,RECFORMAT=NONE/BIN/TXT/TXT-ASA/TXT-MCC/DLM/DLM-ASA/DLM-MCC/VAR/VAR-ASA/VAR-MCC/FIX/FIX-ASA/FIX-MCC/VAR-REL/VAR-REL-ASA/VAR-REL-MCC/FIX-REL/FIX-REL-ASA/FIX-REL-MCC/F/FA/FM/FS/FSA/FSM/FB/FBA/FBM/FBS/FBSA/FBSM/FE/FEA/FEM/FK/FKA/FKM/FR/FRA/FRM/U/UA/UM/V/VA/VM/VS/VSA/VSM/VB/VBA/VBM/VBS/VBSA/VBSM/VE/VEA/VEM/VK/VKA/VKM/VR/VRA/VRM/ORG,RECLENGTH=num,KEYPOSITION=num,KEYLENGTH=num,DATFMT=NONE/BLOCK/RECORD/ELEMENT,DATTYP=NONE/BINARY/RECORD/RECTXT/CHAR/TEXT/XML/TABLE,MATRIX=NONE/DATBLK/STDREC/STDASAREC/STDMCCREC/RELREC/RELASAREC/RELMCCREC/TXTREC/TXTDLM/TXTRST/XMLELM,REDUNDANT,NOTREDUNDANT,ATTRIB()) ----------------------------------------------------------------------- .Description The state string contains some metadata representing the internal state of FLUC. When opening a file for reading (fcbopen2("read."/"input()")), this state string is returned. It can be passed to a successive file open call for writing (fcbopen2("write."/"output()") or FCROPN("write."/"output()")) to give FLUC additional hints about the data that is to be written. The state string contains mainly file attributes which must be known to fill header information for archives (GZIP, FLAM) correctly, but also some information about elements when working in element formatting mode. On C/C++ interfaces, the parameter is a pointer to a pointer to a string. In read mode, if you pass a non-null pointer, the pointer target will be a pointer to a null-terminated string dynamically allocated in heap memory (i.e. you must free() it!) containing the state string after the opening function returns. In write mode, if you pass a non-null pointer to a pointer to a state string, this state string is used to set the internal state. Otherwise, the state is initialized with default values. On the record interface, the application must provide the memory and a length error is returned if the buffer is too small. .Example: ------------------------------------------------------------------------ "state(member='test.txt' recf=FBA recl=120)" ------------------------------------------------------------------------ The state mainly contains file attributes which describe the source. This information is important for example to store the right values in GZIP or FLAM headers. The status object can be used to pass the source's characteristics to the write operation. .Arguments * `STRING: ORGF='str'/STREAM/DUMMY - Original name of the file (used for defined mappings, if empty then FILE is used)` ** `STREAM - Read from stdin or write to stdout` ** `DUMMY - Read EOF or write nothing` * `STRING: FILE='str'/STREAM/DUMMY - Current name of the file (with appended extensions, if empty then ORGF is used)` ** `STREAM - Read from stdin or write to stdout` ** `DUMMY - Read EOF or write nothing` * `STRING: MEMBER='str' - Name or Index of the member` * `STRING: COMMENT='str' - Comment for headers` * `NUMBER: CHRSET=NONE/SYSTEM/ASCII/UCS1/UTF8/EBCDIC/UCS2BE/UTF16BE/UCS2LE/UTF16LE/UCS4BE/UTF32BE/UCS4LE/UTF32LE/LOCAL - Character set` ** `NONE - No character set defined` ** `SYSTEM - SYSTEM (environment specific (on mainframe EBCDIC else ASCII))` ** `ASCII - ASCII (mainly used in the for open system)` ** `UCS1 - UCS-1 (for text formatting identical to ASCII < 64k)` ** `UTF8 - UTF-8 (for text formatting identical to ASCII < 2M)` ** `EBCDIC - EBCDIC (mainly used on IBM mainframe)` ** `UCS2BE - UCS-2 Big Endian (multibyte character set < 64k)` ** `UTF16BE - UTF-16 Big Endian (multibyte character set < 2M)` ** `UCS2LE - UCS-2 Little Endian (multibyte character set < 64k)` ** `UTF16LE - UTF-16 Little Endian (multibyte character set < 2M)` ** `UCS4BE - UCS-4 Big Endian (multibyte character set < 64k)` ** `UTF32BE - UTF-32 Big Endian (multibyte character set < 2M)` ** `UCS4LE - UCS-4 Little Endian (multibyte character set < 64k)` ** `UTF32LE - UTF-32 Little Endian (multibyte character set < 2M)` ** `LOCAL - LOCAL (platform specific (on mainframe EBCDIC else ASCII))` * `STRING: CCSID='str' - CCSID / Character encoding` * `NUMBER: SPACE=num - Required space for the target in byte` * `NUMBER: BLKSIZE=num - Block size` * `NUMBER: RECFORMAT=NONE/BIN/TXT/TXT-ASA/TXT-MCC/DLM/DLM-ASA/DLM-MCC/VAR/VAR-ASA/VAR-MCC/FIX/FIX-ASA/FIX-MCC/VAR-REL/VAR-REL-ASA/VAR-REL-MCC/FIX-REL/FIX-REL-ASA/FIX-REL-MCC/F/FA/FM/FS/FSA/FSM/FB/FBA/FBM/FBS/FBSA/FBSM/FE/FEA/FEM/FK/FKA/FKM/FR/FRA/FRM/U/UA/UM/V/VA/VM/VS/VSA/VSM/VB/VBA/VBM/VBS/VBSA/VBSM/VE/VEA/VEM/VK/VKA/VKM/VR/VRA/VRM/ORG - Record format` ** `NONE - No format defined` ** `BIN - Open - Binary (undefined) data (only the last record are shorter then record length)` ** `TXT - Open - Text data with standard delimiter (result is a stripped variable length records)` ** `TXT-ASA - Open - Text data with standard delimiter and ASA byte in front (result variable length records with ASA attribute)` ** `TXT-MCC - Open - Text data with standard delimiter and MCC byte in front (result variable length records with MCC attribute)` ** `DLM - Open - Records separated by a special delimiter with the result of variable length records` ** `DLM-ASA - Open - ASA records separated by a special delimiter with the result of variable length records` ** `DLM-MCC - Open - MCC records separated by a special delimiter with the result of variable length records` ** `VAR - Open - Variable length record (if necessary define length format)` ** `VAR-ASA - Open - Variable length record with ASA print control character (if necessary define length format)` ** `VAR-MCC - Open - Variable length record with machine print control codes (if necessary define length format)` ** `FIX - Open - Fixed-length record (file size = N * record length)` ** `FIX-ASA - Open - Fixed-length record with ASA print control character (file size = N * (record length + 1))` ** `FIX-MCC - Open - Fixed-length record with machine print control codes (file size = N * (record length + 1))` ** `VAR-REL - Open - Variable relative record (if necessary define length format)` ** `VAR-REL-ASA - Open - Variable relative record with ASA print control character (if necessary define length format)` ** `VAR-REL-MCC - Open - Variable relative record with machine print control codes (if necessary define length format)` ** `FIX-REL - Open - Fix relative record (file size = N * (record length + 8))` ** `FIX-REL-ASA - Open - Fix relative record with ASA print control character (file size = N * (record length + 9))` ** `FIX-REL-MCC - Open - Fix relative record with machine print control codes (file size = N * (record length + 9))` ** `F - Host - Fixed-length, unblocked` ** `FA - Host - Fixed-length, unblocked, ASA print control characters` ** `FM - Host - Fixed-length, unblocked, machine print control codes` ** `FS - Host - Fixed-length, standard` ** `FSA - Host - Fixed-length, standard, ASA print control characters` ** `FSM - Host - Fixed-length, standard, machine print control codes` ** `FB - Host - Fixed-length, blocked` ** `FBA - Host - Fixed-length, blocked, ASA print control characters` ** `FBM - Host - Fixed-length, blocked, machine print control codes` ** `FBS - Host - Fixed-length, blocked, standard` ** `FBSA - Host - Fixed-length, blocked, standard, ASA print control characters` ** `FBSM - Host - Fixed-length, blocked, standard, machine print control codes` ** `FE - Host - Fixed-length, ESDS` ** `FEA - Host - Fixed-length, ESDS, ASA print control characters` ** `FEM - Host - Fixed-length, ESDS, machine print control codes` ** `FK - Host - Fixed-length, KSDS` ** `FKA - Host - Fixed-length, KSDS, ASA print control characters` ** `FKM - Host - Fixed-length, KSDS, machine print control codes` ** `FR - Host - Fixed-length, RRDS` ** `FRA - Host - Fixed-length, RRDS, ASA print control characters` ** `FRM - Host - Fixed-length, RRDS, machine print control codes` ** `U - Host - Undefined-length` ** `UA - Host - Undefined-length, ASA print control characters` ** `UM - Host - Undefined-length, machine print control codes` ** `V - Host - Variable` ** `VA - Host - Variable, ASA print control characters` ** `VM - Host - Variable, machine print control codes` ** `VS - Host - Variable, spanned` ** `VSA - Host - Variable, spanned, ASA print control characters` ** `VSM - Host - Variable, spanned, machine print control codes` ** `VB - Host - Variable, blocked` ** `VBA - Host - Variable, blocked, ASA print control characters` ** `VBM - Host - Variable, blocked, machine print control codes` ** `VBS - Host - Variable, blocked, spanned` ** `VBSA - Host - Variable, blocked, spanned, ASA print control characters` ** `VBSM - Host - Variable, blocked, spanned, machine print control codes` ** `VE - Host - Variable, ESDS` ** `VEA - Host - Variable, ESDS, ASA print control characters` ** `VEM - Host - Variable, ESDS, machine print control codes` ** `VK - Host - Variable, KSDS` ** `VKA - Host - Variable, KSDS, ASA print control characters` ** `VKM - Host - Variable, KSDS, machine print control codes` ** `VR - Host - Variable, RRDS` ** `VRA - Host - Variable, RRDS, ASA print control characters` ** `VRM - Host - Variable, RRDS, machine print control codes` ** `ORG - Use original record format as default (like none)` * `NUMBER: RECLENGTH=num - Record length` * `NUMBER: KEYPOSITION=num - Key position (>=1)` * `NUMBER: KEYLENGTH=num - Key length (>=1)` * `NUMBER: DATFMT=NONE/BLOCK/RECORD/ELEMENT - Data format (not required at write)` ** `NONE - Unknown data format` ** `BLOCK - Block oriented data` ** `RECORD - Record oriented data` ** `ELEMENT - Element oriented data` * `NUMBER: DATTYP=NONE/BINARY/RECORD/RECTXT/CHAR/TEXT/XML/TABLE - Data type (not required at write)` ** `NONE - Unknown data type` ** `BINARY - Binary data (not printable)` ** `RECORD - Binary record (not printable)` ** `RECTXT - Text record (printable)` ** `CHAR - Character data (no delimiter)` ** `TEXT - Text data (with delimiter)` ** `XML - XML data (like CHAR)` ** `TABLE - Table (various elements per record)` * `NUMBER: MATRIX=NONE/DATBLK/STDREC/STDASAREC/STDMCCREC/RELREC/RELASAREC/RELMCCREC/TXTREC/TXTDLM/TXTRST/XMLELM - Matrix type of the elements list` ** `NONE - Unknown matrix type` ** `DATBLK - Simple data block (no attributes)` ** `STDREC - Simple standard record (no attributes)` ** `STDASAREC - Standard record with ASA control characters (1 byte) as attributes` ** `STDMCCREC - Standard record with machine control characters (1 byte) as attributes` ** `RELREC - Relative record with 8 byte slot number as attribute` ** `RELASAREC - Relative record with slot number (8 byte) and ASA control character (1 byte) as attribute` ** `RELMCCREC - Relative record with slot number (8 byte) and machine control character (1 byte) as attribute` ** `TXTREC - Standard text record (no attributes)` ** `TXTDLM - Record with text delimiter at the end (no attributes)` ** `TXTRST - Text records with data and rest element (no attributes)` ** `XMLELM - XML elements (no attributes)` * `SWITCH: REDUNDANT - Data is known as redundant` * `SWITCH: NOTREDUNDANT - Data is known as not redundant` [[CLEP.OTHERCLP.LOG]] === Appendix A.7. String 'LOG' .Synopsis ----------------------------------------------------------------------- HELP: String to open the memory logging facility PATH: limes.flcbyt TYPE: OBJECT SYNTAX: > flcbyt LOG(IDENT='str',FORMAT=STANDARD/DIALOG/MINIMAL,MESSAGE()) ----------------------------------------------------------------------- .Description The log string can be used to define the log message types to be written to the in-memory log. Additionally, a custom identifier can be set and an output format can be selected. (minimal is default) .Example: ------------------------------------------------------------------------ "log(ident='myProgram' format=dialog message(warn))" ------------------------------------------------------------------------ .Arguments * `STRING: IDENT='str' - Identifier used to identify log entries [owner]` * `NUMBER: FORMAT=STANDARD/DIALOG/MINIMAL - Format of log message [STANDARD]` ** `STANDARD - Standard logging format (timestamp ident *level* message)` ** `DIALOG - For dialog processing (ident *level* message)` ** `MINIMAL - For output processing (message)` ... print CLE_DOCTYP_CHAPTER == FLUC Filesystem for Linux [[flcl.appendix.flucfs]] == Appendix B. FLUC Filesystem for Linux *flucFS* uses https://en.wikipedia.org/wiki/Filesystem_in_Userspace[FUSE] to mount an existing directory in some other folder. Everything written to the mounted folder is transparently converted, encrypted, compressed as defined in the configuration. If no match is found in its configuration, the data is passed through without any change. The configuration is done with the argument strings of the FLUC byte interface API. However, since flucFS is a filesystem and uses only the read and write functions of the API, the element access features of the API are not useable with flucFS. === Dependencies ==== Kernel module The fuse kernel module must be loaded in order to use any fuse filesystem. This kernel module is usually installed with the linux kernel. This can be checked with ------------------------------------------------------------- lsmod | grep fuse ------------------------------------------------------------- To load it, just run ------------------------------------------------------------- modprobe fuse ------------------------------------------------------------- with root permissions. In unusual circumstances, https://en.wikipedia.org/wiki/Filesystem_in_Userspace[FUSE] support might be built into the kernel image. ==== Library *flucFS* depends on the https://en.wikipedia.org/wiki/Filesystem_in_Userspace[FUSE] user space library. This library and the required utilities are installed with ------------------------------------------------------------- yum install fuse fuse-libs ------------------------------------------------------------- on https://www.redhat.com/en/technologies/linux-platforms/enterprise-linux[RedHat Enterprise Linux] or https://www.centos.org[CentOS]. ------------------------------------------------------------- zypper install fuse libfuse2 ------------------------------------------------------------- on https://www.suse.com[SLES] or https://www.opensuse.org[openSUSE] ------------------------------------------------------------- apt-get install fuse ------------------------------------------------------------- on https://www.debian.org[Debian] or https://www.ubuntu.com[Ubuntu] ------------------------------------------------------------- pacman -S fuse3 fuse2 ------------------------------------------------------------- on https://www.archlinux.org[ArchLinux] or https://www.manjaro.org[Manjaro] === Usage The current version of the https://en.wikipedia.org/wiki/Filesystem_in_Userspace[FUSE] library is 3.1.1 and uses a slightly different API than older versions (starting with 2). It is possible to have both versions of the https://en.wikipedia.org/wiki/Filesystem_in_Userspace[FUSE] library installed at the same time. Since some Linux distributions only provide an older version (2) two executables are shipped: *flucFS* and *flucFS2* In case only an older version is available the executable *flucFS* will NOT work. Use *flucFS2* instead when executing any of the following commands. To mount the folder /var/data on the folder /home/hugo/mydata execute this command: ------------------------------------------------------------- flucFS -l logfile /var/data /home/hugo/mydata ------------------------------------------------------------- If this is started from within the folder /home/hugo it can be abbreviated with ------------------------------------------------------------- flucFS -l logfile /var/data mydata ------------------------------------------------------------- If no logfile is specified, *flucFS* will NOT run as daemon and the logging is done to stderr. To unmount the filesystem execute ------------------------------------------------------------- fusermount -u /home/hugo/mydata ------------------------------------------------------------- or, if it was not running as a daemon, just hit -C After it is unmounted, all data was written to the logfile. In case of errors, the contents will help us at limes datentechnik to figure out the cause. For further details of **flucFS** please see the documentation: link:../flucFS.html[flucFS(1)] === Known issues If a mount command fails with this message: ------------------------------------------------------------- fuse: failed to open /dev/fuse: Permission denied ------------------------------------------------------------- Users NOT belonging to the group *fuse* are usally denied access to /dev/fuse **Solution:** The preferred solution is to add the required users to the *fuse* group. This is done by adding them to end of the line starting with *fuse* in /etc/group An alternative solution is to alter the permissions of the device node /dev/fuse to allow read and write for any user in order to mount a https://en.wikipedia.org/wiki/Filesystem_in_Userspace[FUSE] filesystem by a user other than root. This can be done by executing ------------------------------------------------------------- chmod ugo+rw /dev/fuse ------------------------------------------------------------- If a mount command fails with this message: ------------------------------------------------------------- version `FUSE_2.8' not found (required by ./flucFS2) ------------------------------------------------------------- the https://en.wikipedia.org/wiki/Filesystem_in_Userspace[FUSE] library is too old for the shipped flucFS2. **Solution:** * Get a newer version of libfuse.so, at least 2.8 * Contact limes datentechnik to provide you with a version of **flucFS2** that is built for such an old library. 2.8.0 was released on August 18th 2009 (see: https://github.com/libfuse/libfuse/releases[FUSE releases]) ... print CLE_DOCTYP_CHAPTER == FLUC Subsystem for z/OS [[flcl.appendix.flucsub]] == Appendix C. FLUC Subsystem for z/OS This appendix describes the handling of the FLUC subsystem in IBM z/OS environment. FLUC-sub is an interface to FLAM (z/OS), the compression and encryption utility, and may only be used in conjunction with a license for FLAM utility and FLUC subsystem. Further information on FLAM can be found at the beginning of this manual. === FLUC as a subsystem FLUC (FLAM Universal Converter) is part of the FLAM family and converts, compresses and encrypts whole files. While FLAM focuses on FLAMFILES as archive/exchange file, FLUC focuses on processing any file regardless of its origin (original z/OS files, PC files, FLAM, GZIP, OpenPGP, XML, ZIP, ...). Data can be consciously converted and prepared for / by a target system. The data is read/written as z/OS files, USS files or can be sent directly, e.g. via SSH. FLAM and FLUC contain interfaces (APIs) that can be used by custom applications. This allows flexible adaptation to existing tasks that cannot be handled by the utility alone. While a reprogramming of the interface is certainly no problem, an embedding into existing programs is always associated with effort. FLUC-sub is a subsystem of the z/OS operating system and is activated by the subsystem interface of the command language (JCL). All calls of an application program to file operations (e.g. opening, closing a file, reading and writing sentences) are received and processed by FLUC-sub. Changes are usually not necessary in the calling programs, the calling program does not notice any difference to conventional file processing. If necessary, DCB specifications must be specified in the DD statement or utilities (such as IEBGENER, SORT, special assembler routines). Without DCB information, the subsystem makes this data available when DISP=SHR. If the application program opens its file, FLUC-sub opens the file named in the parameters. If a data set is written, compressed, encrypted or converted, FLUC-sub converts it into this file. If a data set is read, FLUC-sub takes it from the file and transfers it to the application program decrypted, decompressed and converted. Closing the original file also causes the named file to be closed. With the parameter inputs, the entire variety of FLUC is available to the application program, i.e. an existing application program (in Cobol, PL/1, Assembler, C, Java) can use FLUC-sub to convert, compress, encrypt each data record during writing and store the data generated in this way directly in the same system, transport it to the target computer using an SSH connection. The file can then be a completely different type, completely independent of the one defined in the program, such as a FLAMFILE, GZIP, OpenPGP,ZIP, ... Likewise, the data can be formatted as required in the program, regardless of the origin of the data (ASCII, EBCDIC, XML, UTF8/16/32, ..., PC format, ...). And here too, the file to be read by FLUC is completely independent of the file defined in the program. The actual processing does not take place in the address space of the application program but in a subtask of the server (started task). Thus the address space is relieved and only small resources are used by the caller. A subtask is used for each file. The number of subtasks thus determines the number of files to be processed simultaneously. === Calling FLUC subsystem FLUC-sub is a subsystem of the z/OS operating system and is activated by the subsystem interface of the command language (JCL). The name of the subsystem is FLUC. ------------------------------------------------------------------------ //ddname DD SUBSYS=(FLUC,['subsys-parameter',]'fluc-parameter') possibly with // DISP=SHR ------------------------------------------------------------------------ This instructs the file with *ddname* to be processed with the FLUC subsystem. A file name is arbitrarily selectable and has no meaning for the processing and can also be omitted (then JES generates a name). This file name is transferred into a FLAMFILE when writing, so flexible use is possible. FLUC parameters have to be given to the process, as you are used to with FLCL in the utility. Parameters for controlling the subsystem are only recognized, if they are specified first. Faulty parameters are rejected by FLAM as JCL errors, so the job does not start at all. The JES check of the DD command remains unchanged. If `DISP=SHR` is specified in the DD command, FLUC-sub inserts the DCB specifications of a file to be read into the JCL, if no specifications have been made and the file name can be recognized in the parameters (`READ.xxxx(FILE=filename)`). The number of files to be processed "simultaneously" by the subsystem depends on the number of generated subtasks of the server, otherwise FLUC does not limit it. With this technique, almost any file can be processed sequentially in read or write mode, which otherwise could not be processed in the application program (see the example collection). If DCB attributes are specified for ddname in the DD command, FLUC interprets them (in addition to the application program) as values for the original data, otherwise the specifications are defined in the program. === Principle of operation Before a batch job is started by JES, all JCL specifications are checked. JES passes the parameters for the subsystem; these are checked by FLUC-sub. If an error occurs, the DD statement is rejected as a JCL error. In addition, a message is displayed in the JCL list (see Example Collection; Messages). The job is therefore only started if there are no errors and is otherwise terminated as usual. The connection to the FLUC subsystem is established by calling the OPEN command in the program. For Open Input only read, decrypted if necessary, decompressed and converted, for Open Output only write, converted if necessary, compressed, encrypted. With OPEN, the file type, file organization, record and block length are taken from the caller's program (or the DCB specifications in the JCL) and used to process the data records. At the open time, the FLUC parameters specified in the JCL are also active and the processing routines are set accordingly. If an error occurs, the error routine remains active in the calling program and is not overlaid by the subsystem. The error return codes returned by the subsystem correspond to those of the file system (see also: https://www-01.ibm.com/servers/resourcelink/svc00100.nsf/pages/zOSV2R3sc236852/$file/idad500_v2r3.pdf[Manual DFSMS/MVS Macro Instructions for Data Sets]) for VSAM error codes, that is, the error routines do not have to be changed. For FLUC errors and subsystem errors, additional messages are output using WTO, Routcde=11 using FLUC-sub (see Messages; Example Collection). They are documented both in the system log and in the JESYSMSG list. With CLOSE on the file, the actually processed file is also closed by FLUC-sub. A new OPEN call is allowed. FLUC-sub requires only small resources in the address space of the user. A possible error or termination of a program, file access or similar has no influence on subsystem accesses of other processes and users. The "actual" processing and thus the utilization of resources takes place in a server (started task FLAMSTC). Sub-tasks are generated in the server at startup. Each OPEN on a file is assigned to such a task. The number of these tasks thus determines the maximum number of files to be processed in parallel. With a CLOSE on the file, the corresponding task is released again. The maximum possible number of tasks is ultimately limited by the size of the memory area required. Errors that are detected in the server are reported to the application program as errors in the I/O system, and processing may not be continued. The associated sub-task is restarted in the server if necessary and is available for the next OPEN call. System errors (such as a classic addressing error 0C4) in the calling program are recognized, the file to be processed in the server is closed, and the server sub-task is terminated. The server sub-task is again available to a new Open. === Preconditions FLAM/FLUC must be installed both as a utility and as a subsystem on the current computer, the associated started task (the server) must be active. Data records can be written or read. The accesses must be logical, i.e. in sequential order. Access via key or pointer is not possible ! If no file attributes are defined in the application program (such as record or block size), these specifications can be defined in the DD statement (see example collection). For example, utilities such as IEBGENER or SORT require these specifications. It is also possible to set the desired format using the FORMAT parameter specification. With DISP=SHR in the DD command, the file attributes recognized in the FLUC are set accordingly. When reading, the record buffers must match the data to be read. If the buffer is too small, the subsystem reports an error (RC=44 (VSAM)). === Restrictions Following restrictions apply: ==== DCB calls (for PS files) * If you omit record and block length specifications in programs (utilities such as IEBGENER or SORT work in this way), you can specify the attributes in the DD command. With DISP=SHR in the allocation, the subsystem sets data in the JFCB (DD command). * Writing in LOCATE mode is rejected. * A temporary Close call for BSAM accesses (CLOSE ...,TYPE=T) is not forwarded to the subsystem and has no effect. * POINT for BSAM accesses is rejected with the error message IEC141I 013-BC .. (is not passed on to the subsystem at all). * Although a file with RECFM=VS or VBS (spanned records) can be written to, it can no longer be read via the subsystem interface (error message IEC141I 013-A8 ...). ==== ACB/RPL calls (for VSAM files) Programming languages with a Runtime System (like COBOL, C, ...) do not allow VSAM files via FLUC subsystem as input/output. Unlike in the FLAM subsystem, FLUC-sub can only support assembler programs that do not (so accurately) check whether a VSAM file really exists. * Accesses with multiple RPLs (RPL list) are not supported (only the first RPL is evaluated). * Asynchronous calls are executed synchronously by FLUC-sub (but the reaction to errors does not occur until CHECK as usual). * CNVTAD returns invalid data or zero. * ENDREQ (Terminate a Request) has no effect. * VERIFY (Synchronize End of Data) has no effect (VSAM control blocks are not updated). * SHOWCB ACB=... + The fields are not changed by the subsystem and retain their previous value. === Used FLUC-sub parameters Parameters for FLUC are transferred in the DD statement with the SUBSYS specification: ------------------------------------------------------------------------ SUBSYS=(FLUC,['subsys-parameter',]'FLUC-parameter1,FLUC-parameter2,...') ------------------------------------------------------------------------ or also ------------------------------------------------------------------------ //...SUBSYS=(FLUC,['subsys-parameter',] // 'FLUC-parameter1', // 'FLUC-parameter2',...') ------------------------------------------------------------------------ ==== Subsystem parameter SUBSYS-parameter is used to control the subsystem itself and must be specified _before_ the FLUC parameters. :TRACE: If the first parameter is entered, the function calls are logged. + Output is logged both in the calling process and in the started task and on the operator console. + Note: The amount of output can be very large. :ANALYSIS: Causes the same behavior as in the FLCL, i.e. the data to be written is analyzed and, if necessary, implemented accordingly. + Without this parameter, the automatic analysis is not used. + Note: Possible OPEN errors are only reported when writing records or in CLOSE! *PARMDD=ddname* Often the bytes allowed for parameters are not sufficient. With the specification ------------------------------------------------------------------------ //ddname DD DSN=filename, // SUBSYS=(FLUC,'PARMDD=ddname2') ------------------------------------------------------------------------ the *ddname* of a parameter file (DSORG=PS,RECFM=V/VB/F/FB) is specified, as is now also common in the EXEC PGM statement. E.G. ------------------------------------------------------------------------ //ddname2 DD * parameter, ... parameter, ... /* ------------------------------------------------------------------------ NOTE: Subsequent parameters are ignored. ==== FLUC parameter The FLUC parameters correspond to those of the FLUC Utilities (see also: https://flam.de/ftp/FL5/flcl/index.html[FLCL manual]). === Subsystem messages FLUC-sub only displays a message at the console in case of an error (via WTO ,ROUTCDE=11). It is also logged in the JCL log. The letter after the message number specifies the time at which the error was detected: * `I` - during initialization * `C` - when analyzing the JCL * `O` - when opening a file * `D` - during the I/O process * `E` - when closing a file Apart from the initialization of the subsystem, errors only affect the specified file of the respective job, i.e. the subsystem remains active for the other files and users. [width="100%",cols="^h,12",align="right",frame="none", grid="none"] |==== |FLM0500I |*INITIALIZATION OF SUBSYSTEM FLUC COMPLETED* + The FLUC subsystem has been initialized correctly and is now available. Response: None |FLM0501I |*SUBSYSTEM FLUC NOT INSTALLED ON THIS SYSTEM* + The subsystem cannot be initialized. It has not been installed on the computer. Response: Define and start the started task in SYS1.PROCLIB. |FLM0502I |*SUBSYSTEM FLUC ALREADY INITIALIZED* + The subsystem is already defined and active, a restart was rejected. The already active subsystem remains active. Response: FLUC-sub need not be restarted. |FLM0503I |*NO MEMORY RECEIVED FOR INITIALIZATION* + The operating system cannot make any memory available for initialization. The subsystem is not active. Response: Increase REGION specification, analysis may be required (system dump). |FLM0504I |*SUBSYSTEM COULD NOT FREE SYSTEM MEMORY* + The memory made available by the operating system cannot be freed. The subsystem has nevertheless been initialized and is now available. Response: An analysis is necessary (system dump). |FLM0505I |*SUBSYSTEM FLUC FUNCTION MODULE NOT FOUND* + The work area received from the operating system could not be released. However, the subsystem has been initialized and is ready. Response: Set the subsystem modules in a library of the master identification (SYS1.) and link them with the LINKLIB. |FLM0510I |*INTERNAL ERROR. RC = no* + An internal error has been detected. The subsystem has not been initialized. Response: Please inform your sales partner. |FLM0515I |*INITIALIZATION OF SUBSYSTEM FLUC FAILED* + The subsystem cannot be initialized due to an error. The error situation was documented in a previous message. |FLM0519I |*FLUC SUBSYSTEM IS NOT LICENSED* + Your license does not allow using the subsystem. Response: Please inform your sales partner. |FLM0520C |*PARAMETER ERROR: ...* + An invalid parameter was entered in the DD statement of the JCL for FLUC-sub. Response: Correct parameters and restart job. |FLM0523C |*NO MEMORY RECEIVED FOR JCL-CONVERTION* + A subsystem module was not allocated any memory by the operating system. Response: An analysis is necessary (system dump). |FLM0530A |*PARAMETER ERROR: ...* + An invalid parameter was entered in the DD statement of the JCL for FLAM-sub. The invalid parameter is displayed. Response: Correct parameters and restart job. |FLM0531A |*NO MEMORY RECEIVED FOR ALLOCATION* + A subsystem module was not allocated any memory by the operating system. Response: Increase REGION specification, analysis may be required (system dump). |FLM0540O |*OPEN ERROR. DDNAME=ddname. RC= no FLUC/VSAM* + An error was detected for the file assigned with ddname in the JCL at open time. FLUC return codes are decimal, VSAM errors are decimal (see also: https://www-01.ibm.com/servers/resourcelink/svc00100.nsf/pages/zOSV2R3sc236852/$file/idad500_v2r3.pdf[manual DFSMS/MVS Macro Instructions for Data Sets]). + This message is followed by the IEC141I 013-C0 message of the data management system, where the DD name used by the program is output. For VSAM accesses, the message IEC161 is output if necessary. The FLUC error codes correspond to the utility. Here are the most important ones: 40 = Error when reading the 1st record of a file + 84 = Parameter error + 135 = Connection could not be established Reaction: + RC = 40 is often used when reading with READ.RECORD a file created in the Openwelt without format specification. It is then assumed to be variable (corresponds to the FILEDATA=RECORD of a DD statement). If necessary, specify READ.BIN (read binary) with recl=nnn. + RC = 84 Errors in a parameter file are not detected until Open is called. + RC = 135 is a general return code that the connection to the server was aborted. Further information is output in the log of the Started Task. |FLM0541O |*OPEN ERROR. MESSAGE FROM FLAM-SERVER:* + The message of the server about the Open error is logged. |FLM0552D |*I/O ERROR. DDNAME = ddname. RC = no (FLUC)/RPLERRCD file-name* + An error was detected by the FLUC subsystem while reading or writing in the specified file ddname. FLUC return codes are specified in decimal format and VSAM errors RPLERRCD in hexadecimal format. All FLUC return codes are described in the https://flam.de/ftp/FL5/flcl/index.html[FLCL manual]. You can find a list of VSAM return codes in the https://www-01.ibm.com/servers/resourcelink/svc00100.nsf/pages/zOSV2R3sc236852/$file/idad500_v2r3.pdf[manual DFSMS/MVS Macro Instructions for Data Sets]). The message is followed by IEC020I 001-Message of the DMS. Some VSAM return codes: + 2C = Record length error, the record to be read is larger than the block buffers created in the calling program. |FLM0553D |*NO MEMORY RECEIVED FOR I/O OPERATIONS* + A subsystem module was not allocated any memory by the operating system. Consequently, no other information is available. Response: Specify a higher value for REGION in the EXEC statement, an analysis may be required (system dump). |FLM0570E |*CLOSE ERROR. DDNAME = ddname. RC = no file-name* + An error was detected when an attempt was made to close the specified file. Since records may still have to be written when closing a file, see message FLUC552D. |==== === Subsystem management The subsystem is administered via a Started Task (Server). The name of the Started Task is freely selectable, the name in the delivery is FLAMSTC. It should be stored in the file SYS1.PROCLIB or correspondingly. When starting the Started Task from the Console ------------------------------------------------------------------------ S FLAMSTC,REUSASID=YES ------------------------------------------------------------------------ both the server and the FLUC subsystem are started. ------------------------------------------------------------------------ P FLAMSTC ------------------------------------------------------------------------ terminates the server and the subsystem. If the command ------------------------------------------------------------------------ COM='S FLAMSTC,REUSASID=YES' ------------------------------------------------------------------------ is inserted into the member COMMNDxx in SYS1.PARMLIB, FLUC-sub is automatically started at the IPL of the operating system and does not have to be entered extra at the console. ------------------------------------------------------------------------ F FLAMSTC,LIST,VERSION ------------------------------------------------------------------------ displays the names and versions of the modules involved in the console: ------------------------------------------------------------------------ FLZS111I FLZ Controller Version 1.0, Date 20180504 16.02 started FLUC517I FLUCSUB V1.00 05/04/18-16.02 FLUC517I FLUCS07 V1.00 05/04/18-16.03 FLUC517I FLUCS16 V1.00 05/04/18-16.03 FLUC517I FLUCS17 V1.00 05/04/18-16.03 FLUC517I FLUCS38 V1.00 05/04/18-16.03 FLUC517I FLUCS39 V1.00 05/04/18-16.03 ------------------------------------------------------------------------ ------------------------------------------------------------------------ F FLAMSTC,LIST,TASKS ------------------------------------------------------------------------ The list of generated tasks is displayed, as well as their status (active/inactive), the last function and the job name: ------------------------------------------------------------------------ FLZS116I Number of server tasks: 10 Index TCB address active request area last function JOB ID 1 008FC320 NO 20C1E160 00000008 2 008C7528 NO 211B2160 00000000 3 008C7378 NO 21746160 00000000 4 008C7048 NO 21CD9160 00000000 5 008BEE88 NO 2226D160 00000000 6 008BEB58 NO 22800160 00000000 7 008BE9A8 NO 22D94160 00000000 8 008BE678 NO 23327160 00000000 9 008BE4C8 NO 238BB160 00000000 10 008BE198 NO 23E4E160 00000000 ------------------------------------------------------------------------ ------------------------------------------------------------------------ F FLAMSTC,REMOVE,TASK,## ------------------------------------------------------------------------ releases the task with index number ## (from the list of the command LIST, TASKS, see above) again. If a task is blocked for any reason, it is terminated and restarted. If it is necessary to start or stop the subsystem independently from the server, the following commands are available: ------------------------------------------------------------------------ F FLAMSTC,FLUC,START zum Starten des Subsystems F FLAMSTC,FLUC,STOP zum Beenden des Subsystems ------------------------------------------------------------------------ After deactivating FLUC-sub, modules of a newer FLUC-sub version could be installed, which could then be activated (after a LLA REFRESH to the library) by a new `F FLAMSTC,FLUC,START`. === Examples ==== General information The subsystem has only a limited ability to output error messages. As a rule, the application program only receives corresponding return codes, and of course it depends on the program how it reacts. Since the parameter entries are identical to those of the utility, we recommend that you first test the specifications with the utility: ------------------------------------------------------------------------ //stepname EXEC PGM=FLCL,PARM='CONV=DD:PARAMS' ------------------------------------------------------------------------ You receive detailed messages on the process. Files are always read and written in the address space of the server (sub)tasks. The rights (RACF) of the caller apply. ===== Parameter file For reasons of simplification, we write all parameters in the examples to a file and assign them to the subsystem: ------------------------------------------------------------------------ //stepname EXEC PGM=FLCL,PARM='CONV=DD:PARAMS' ------------------------------------------------------------------------ and e.g. ------------------------------------------------------------------------ //PARAMS DD * parameter, ... parameter, ... /* ------------------------------------------------------------------------ In the examples only the parameter input is described. ===== DCB specifications When reading and writing via a subsystem, there are basically two different cases: a) At the open time of the file, the program has specified the block and block length in the control block (e.g. in the FD section for COBOL). Then the SUBSYS specification in the DD statement is sufficient: ------------------------------------------------------------------------ //ddname DD SUBSYS=(FLUC,'PARMDD=PARAMS') ------------------------------------------------------------------------ Since the "correct" values are specified in the calling program, the data records are passed/received by the subsystem according to these specifications. If the specifications with the file to be processed are not correct, error codes are set and a message is output (I/O error). Here the "correct" values can be set by the FORMAT specification, the read data records are then converted into the format string according to the statement. b) The calling program has not defined block lengths. The format is also missing. In the "normal case" (without subsystem) this information would be taken from the file catalog and entered into the control block (IEBGENER, SORT and many utility programs work in this way). Additional DCB attributes can be specified in the DD statement: ------------------------------------------------------------------------ //ddname DD SUBSYS=(FLUC,PARMDD='PARAMS'), // DCB=(RECFM=tt,LRECL=nnn,BLKSIZE=mmm), ------------------------------------------------------------------------ If you do not know the record length, we recommend that you specify the following ------------------------------------------------------------------------ DCB=(RECFM=VB,LRECL=32756) ------------------------------------------------------------------------ if possible. When reading and specifying DISP=SHR, the known attributes of the file are set correctly by the subsystem. If, for example, a FLAMFILE is to be read, the attributes of the compressed file are specified. ------------------------------------------------------------------------ //ddname DD SUBSYS=(FLUC,'READ.RECORD(FILE=datei)'), // DISP=SHR ------------------------------------------------------------------------ For unknown file attributes (such as files in USS, Unix, Windows, ...), the ------------------------------------------------------------------------ DCB=(RECFM=VB,LRECL=32756,BLKSIZE=32760) ------------------------------------------------------------------------ is set. It must be possible to recognize the file name in the parameter specification of the subsystem (PARMDD= does not work there). If necessary, a separate parameter file can be specified with the READ command (READ=file name), which contains the file name to be read (see also: https://flam.de/ftp/FL5/flcl/index.html[FLCL manual]). Finally, the attributes can also be specified by the FORMAT specification (FORMAT.RECORD(RECL= ....)). See: https://flam.de/ftp/FL5/flcl/index.html[FLCL manual]. ===== IEF... operating system messages In the JESYSMSG listing you can recognize the subsystem activity by the system messages: ----------------------------------------------------------------------- IEF237I FLUC ALLOCATED TO ddname . . IEF285I data.set.name SUBSYSTEM ----------------------------------------------------------------------- If no file name is specified in the DD statement, the operating system generates a name. This name is visible in the message IEF285I. ===== Differences BIN,CHAR,FLAM,RECORD,TEXT in reading/writing In FLUC the concept of sentence has been extended. The sentence format, length, blocking of a file catalogued in z/OS no longer determines what a "sentence" is. This "physical format" can be used to interpret a "logical" one (see also: https://flam.de/ftp/FL5/flcl/index.html[FLCL manual]). [width="90%",cols="^1,9",align="center"] |==== |*BIN* | * Reads / writes all bytes (delimiter and padding are part of the data). Possible record length fields (e.g. with RECFM=V) are not part of the data and are ignored when reading or inserted when writing. + * The result is binary blocks in length of recl (FLUC parameter). |*CHAR* | * reads all characters (delimiters are part of the data). Possible record length fields are not part of the data and are omitted or inserted when writing. * automatic character set conversion. * The result is text blocks. |*FLAM* | * reads records of the originally compressed file, as they are stored in the FLAMFILE are stored. * Writes each transferred block to a FLAMFILE. |*RECORD* | * FIX, all records have the same length. * VARIABLE, data records have different lengths. * DELIM, data contains a delimiter (like read.text, but only a certain Delimiter). The set ends then (only) with this Delimiter, independent of the possible cataloged record length. * Character set conversion only if CCSID is specified, otherwise binary processing. The result is binary or text sentences. Without DELIM, this corresponds to the conventional sentence term in z/OS (reading/writing a sentence as allocated/cataloged). |*TEXT* | * Reads for (all) delimiters, cutting into sets * Automatic character set conversion. The result are sets (without delimiter) in set length up to the delimiter. The original record length of the physically read records in the file is irrelevant. * When writing, the system delimiters (X'15' for z/OS and USS, X'0A' for Unix, X'0D0A' for Windows) are inserted at the end of the record. The data is written in physical units to a z/OS file as specified by the catalog or parameter in the DD statement. |==== ==== Reading z/OS cataloged file The file USER.EXAMPLE.INPUT is a file cataloged in the z/OS system. This file must be read via FLUC-sub. Parameter: ----------------------------------------------------------------------- READ.RECORD(FILE=USER.EXAMPLE.INPUT) ----------------------------------------------------------------------- as a minimum. For this purpose several conversion, decompression, decryption and formatting instructions could be specified. The file USER.EXAMPLE.INPUT could be a normal sequential PS file with the same record format, length as defined in the program, but also of the type FLAMFILE, GZIP, ZIP, ..., whose original files in the compressed files have these (max.) record lengths. Instead of READ.RECORD you can also specify READ.TEXT, READ.BIN, READ.FLAM, etc. (see: https://flam.de/ftp/FL5/flcl/index.html[FLCL manual]). NOTE: If blocks longer than defined in the program (or specified in the DD statement) are read via FLUC, FLUC reports a block length error. If the cataloged file is one with print control characters (e.g. FBA), a special feature applies: By default, FLUC removes the control character from the record, so that for an FBA file with a cataloged record length of 133 bytes, only 132 are passed (as with FLCL utility). If the control character is to be retained, the following must be entered without further FORMAT specification ----------------------------------------------------------------------- READ.RECORD(FILE=filename PRNCONTROL=RETAIN) ----------------------------------------------------------------------- or ----------------------------------------------------------------------- FORMAT.RECORD(RECF=FBA,LRECL=..., ...) ----------------------------------------------------------------------- must be specified ! ==== Writing a z/OS file The file USER.EXAMPLE.OUTPUT is a file of the z/OS system. It has to be written via FLUC-sub. If the file is not cataloged, it is created again. Parameter: ----------------------------------------------------------------------- WRITE.RECORD(FILE=USER.EXAMPLE.OUTPUT) ----------------------------------------------------------------------- as a minimum. In addition, several conversion, compression, encryption and formatting instructions could be specified. ==== Reading/writing a USS file The file `/srv/ftp/input/sample.txt` is stored in the USS under the UserID of the caller. It is a text file (i.e. it contains printable characters with delimiters). Parameter (reading): ----------------------------------------------------------------------- READ.TEXT(FILE='/srv/ftp/input/sample.txt') ----------------------------------------------------------------------- Parameter (writing): ----------------------------------------------------------------------- WRITE.TEXT(FILE='/srv/ftp/output/sample.txt') ----------------------------------------------------------------------- ==== Reading a Unix file via SSH The file `/srv/ftp/input/beispiel.bin` can be read binary via the SSH protocol in units of 1024 bytes. It is located on a foreign server, the access is protected with a password. Parameter: ----------------------------------------------------------------------- READ.BIN(FILE='/srv/ftp/input/beispiel.bin' RECL=1024 NET.SSH(HOST=tcp/ip-addresse USER=user PASSWORD=password HOSTKEY=ACCEPT)) ----------------------------------------------------------------------- The special feature here is the cutting of the binary data by FLUC in units of 1024 bytes (parameter RECL). The application program must be able to process this length, if necessary RECFM=VB,LRECL=1028 must be specified in the DD statement. Of course, other record lengths, as required by the program, can also be specified here. NOTE: Without RECL specification, blocks of 64 KB are transferred! ==== Creating an OpenPGP file All records are to be written to a password encrypted OpenPGP file in the USS (Zip archive). Parameter: ----------------------------------------------------------------------- WRITE.TEXT(FILE='/tmp/pgpfile.zip') METHOD=UNIX CCSID='ISO8859-1' ENCRYPT.PGP(PASSWORD=password) ARCHIVE.ZIP() ----------------------------------------------------------------------- ==== IEBGENER samples Below two sample job steps using the IEBGENER for a better total understanding: ------------------------------------------------------------------------ //STEPWRIT EXEC PGM=IEBGENER //STEPLIB DD DSN=FLAM.AUTH.LOAD,DISP=SHR //SYSOUT DD SYSOUT=* //SYSDUMP DD SYSOUT=* //SYSPRINT DD SYSOUT=* //SYSIN DD DUMMY //SYSUT1 DD * Test Data Set with two records /* //SYSUT2 DD SUBSYS=(FLUC,'PARMDD=FLUCDD'), // DCB=(DSORG=PS,RECFM=FB,LRECL=80) //FLUCDD DD * FORMAT.RECORD(CCSID=IBM-1141) WRITE.TEXT(FILE='flucFS/physical/gz/test1.txt.gz' NET.SSH(HOST='192.168.80.3' USER='falk') METHOD=UNIX SUPTWS CCSID='UTF-8' COMPRESS.GZIP()) /* //STEPREAD EXEC PGM=IEBGENER //STEPLIB DD DSN=FLAM.AUTH.LOAD,DISP=SHR //SYSOUT DD SYSOUT=* //SYSDUMP DD SYSOUT=* //SYSPRINT DD SYSOUT=* //SYSIN DD DUMMY //SYSUT1 DD SUBSYS=(FLUC,'PARMDD=FLUCDD'),DISP=SHR, // DCB=(DSORG=PS,RECFM=FB,LRECL=80,BLKSIZE=32000) //SYSUT2 DD SYSOUT=* //FLUCDD DD * READ.TEXT(FILE='flucFS/physical/gz/test1.txt.gz' NET.SSH(HOST='192.168.80.3' USER='falk')) FORMAT.RECORD(CCSID=1141 recf=FBA recl=79 padchar='?') /* ------------------------------------------------------------------------ ... print CLE_DOCTYP_LEXEMES == Lexemes [[CLEP.APPENDIX.LEXEMES]] == Appendix D. Lexemes The regular expressions used by the command line compiler are shown below. This content is printed on the screen with the built-in function `LEXEMES`. To describe the regular expression the following character classes are used: * :print: - all printable characters * :space: - all blanks, tabs and new lines * :cntr: - all control characters * :alpha: - all letters ([[a-z]|[A-Z]]) * :alnum: - all letters and digits [0-9] * :digit: - all decimal numbers [0-9] * :xdigit: - all hexadecimal numbers [[0-9]|[a-f||[A-F]] All comments and separators are ignored by the scanner and not passed with the token to the parser. This means that the separators (SEP) are used in the grammar but will never be part of or own tokens. If a binary entry for a string is possible and no classification is done it is taken as a binary string in local character set representation (c) without null termination. This default can be changed. In this case the help message for this argument should be described the default interpretation of the binary string. For binary strings it is still possible to enter a null-terminated string, but then the prefix *s* must be used. If no binary entry is feasible, only a null-terminated string in local character representation (s) can be built and taken by default. ------------------------------------------------------------------------ Lexemes (regular expressions) for argument list or parameter file --| COMMENT '#' [:print:]* '#' (will be ignored) --| LCOMMENT ';' [:print:]* 'nl' (will be ignored) --| SEPARATOR [:space: | :cntr: | ',']* (abbreviated with SEP) --| OPERATOR '=' | '.' | '(' | ')' | '[' | ']' | (SGN, DOT, RBO, RBC, SBO, SBC) --| '=>'| '+' | '-' | '*' | '/' | '{' | '}' (SAB, ADD, SUB, MUL, DIV, CBO,CBC) --| KEYWORD ['-'['-']][:alpha:]+[:alnum: | '_']* (always predefined) --| NUMBER ([+|-] [ :digit:]+) | (decimal (default)) --| num ([+|-]0b[ :digit:]+) | (binary) --| num ([+|-]0o[ :digit:]+) | (octal) --| num ([+|-]0d[ :digit:]+) | (decimal) --| num ([+|-]0x[ :xdigit:]+) | (hexadecimal) --| num ([+|-]0t(yyyy/mm/tt.hh:mm:ss)) | (relativ (+|-) or absolut time) --| FLOAT ([+|-] [ :digit:]+.[:digit:]+e|E[:digit:]+) | (decimal(default)) --| flt ([+|-]0d[ :digit:]+.[:digit:]+e|E[:digit:]+) (decimal) --| STRING ''' [:print:]* ''' | (default (if binary c else s)) --| str [s|S]''' [:print:]* ''' | (null-terminated string) --| str [c|C]''' [:print:]* ''' | (binary string in local character set) --| str [a|A]''' [:print:]* ''' | (binary string in ASCII) --| str [e|E]''' [:print:]* ''' | (binary string in EBCDIC) --| str [x|X]''' [:print:]* ''' | (binary string in hex notation) --| str [f|F]''' [:print:]* ''' | (read string from file (for passwords)) --| Strings can contain two '' to represent one ' --| Strings can also be enclosed in " or ` instead of ' --| Strings can directly start behind a '=' without enclosing ('`") --| In this case the string ends at the next separator or operator --| and keywords are preferred. To use keywords, separators or --| operators in strings, enclosing quotes are required. --| --| The predefined constant keyword below can be used in a value expressions --| NOW NUMBER - current time in seconds since 1970 (+0t0000) --| MINUTE NUMBER - minute in seconds (60) --| HOUR NUMBER - hour in seconds (60*60) --| DAY NUMBER - day in seconds (24*60*60) --| YEAR NUMBER - year in seconds (365*24*60*60) --| KiB NUMBER - kilobyte (1024) --| MiB NUMBER - megabyte (1024*1024) --| GiB NUMBER - gigabyte (1024*1024*1024) --| TiB NUMBER - terrabyte (1024*1024*1024*1024) --| RNDn NUMBER - simple random number with n * 8 bit in length (1,2,4,8) --| PI FLOAT - PI (3.14159265359) --| LCSTAMP STRING - current local stamp in format: YYYYMMDD.HHMMSS --| LCDATE STRING - current local date in format: YYYYMMDD --| LCYEAR STRING - current local year in format: YYYY --| LCYEAR2 STRING - current local year in format: YY --| LCMONTH STRING - current local month in format: MM --| LCDAY STRING - current local day in format: DD --| LCTIME STRING - current local time in format: HHMMSS --| LCHOUR STRING - current local hour in format: HH --| LCMINUTE STRING - current local minute in format: MM --| LCSECOND STRING - current local second in format: SS --| LCOFFSET STRING - difference to Greenwich mean time: +/-HH --| LCOFFABS STRING - difference to GMT (absolute): HH --| GMSTAMP STRING - current Greenwich mean stamp in format: YYYYMMDD.HHMMSS --| GMDATE STRING - current Greenwich mean date in format: YYYYMMDD --| GMYEAR STRING - current Greenwich mean year in format: YYYY --| GMYEAR2 STRING - current Greenwich mean year in format: YY --| GMMONTH STRING - current Greenwich mean month in format: MM --| GMDAY STRING - current Greenwich mean day in format: DD --| GMTIME STRING - current Greenwich mean time in format: HHMMSS --| GMHOUR STRING - current Greenwich mean hour in format: HH --| GMMINUTE STRING - current Greenwich mean minute in format: MM --| GMSECOND STRING - current Greenwich mean second in format: SS --| GMOFFSET STRING - difference to local time: +/-HH --| GMOFFABS STRING - difference to local time (absolute): HH --| SnRND10 STRING - decimal random number of length n (1 to 8) --| SnRND16 STRING - hexadecimal random number of length n (1 to 8) --| --| SUPPLEMENT '"' [:print:]* '"' | (null-terminated string (properties)) --| Supplements can contain two "" to represent one " --| Supplements can also be enclosed in ' or ` instead of " --| Supplements can also be enclosed in ' or ` instead of " --| ENVIRONMENT VARIABLES '<'varnam'>' will replaced by the corresponding value --| Escape sequences for critical punctuation characters on EBCDIC systems --| '!' = '&EXC;' - Exclamation mark --| '$' = '&DLR;' - Dollar sign --| '#' = '&HSH;' - Hashtag (number sign) --| '@' = '&ATS;' - At sign --| '[' = '&SBO;' - Square bracket open --| '\' = '&BSL;' - Backslash --| ']' = '&SBC;' - Square bracket close --| '^' = '&CRT;' - Caret (circumflex) --| '`' = '&GRV;' - Grave accent --| '{' = '&CBO;' - Curly bracket open --| '|' = '&VBR;' - Vertical bar --| '}' = '&CBC;' - Curly bracket close --| '~' = '&TLD;' - Tilde --| Define CCSIDs for certain areas in CLP strings on EBCDIC systems (0-reset) --| '&' [:digit:]+ '; (..."&1047;get.file='&0;%s&1047;'",f) --| Escape sequences for hexadecimal byte values --| '&' ['X''x'] :xdigit: :xdigit: ';' ("&xF5;") ------------------------------------------------------------------------ ... print CLE_DOCTYP_GRAMMAR == Grammar [[CLEP.APPENDIX.GRAMMAR]] == Appendix E. Grammar Below you can see the grammar used by the command line compiler. This content is printed on the screen if the built-in function <> is used. There are two context free grammars, one is used for the command line the other for the parameter file. The parameter file contains mainly the same argument list as the command line. The property file defines the default settings. For this a different grammar is applied. Properties can be set for each argument, i.e. for arguments not used or arguments in overlays. Based on that, properties are set by using the path (dotted keyword list). A property is always a 'SUPPLEMENT' for the argument list on the command line or parameter file. Thus all defined properties have the same effect as arguments on the command line. A property sets this argument to the corresponding value if it is not defined on the command line. ------------------------------------------------------------------------ Grammar for argument list, parameter file or property file --| Command Line Parser --| command -> ['('] parameter_list [')'] (main=object) --| | ['.'] parameter (main=overlay) --| parameter_list -> parameter SEP parameter_list --| | EMPTY --| parameter -> switch | assignment | object | overlay | array --| switch -> KEYWORD --| assignment -> KEYWORD '=' value --| | KEYWORD '=' KEYWORD # SELECTION # --| | KEYWORD '=>' STRING # parameter file # --| object -> KEYWORD ['('] parameter_list [')'] --| | KEYWORD '=' STRING # parameter file # --| | KEYWORD '=>' STRING # parameter file # --| overlay -> KEYWORD ['.'] parameter --| | KEYWORD '=' STRING # parameter file # --| | KEYWORD '=>' STRING # parameter file # --| array -> KEYWORD '[' value_list ']' --| | KEYWORD '[' object_list ']' --| | KEYWORD '[' overlay_list ']' --| | KEYWORD '=' value_list # with certain limitations # --| It is recommended to use only enclosed array lists to know the end --| | KEYWORD '[=' STRING ']' # parameter file # --| | KEYWORD '[=>' STRING ']' # parameter file # --| value_list -> value SEP value_list --| | EMPTY --| object_list -> object SEP object_list --| | EMPTY --| overlay_list -> overlay SEP overlay_list --| | EMPTY --| A list of objects requires parenthesis to enclose the arguments --| --| value -> term '+' value --| | term '-' value --| | term --| term -> factor '*' term --| | factor '/' term --| | factor --| factor -> NUMBER | FLOAT | STRING --| | selection | variable | constant --| | '(' value ')' --| selection -> KEYWORD # value from a selection table # --| variable -> KEYWORD # value from a previous assignment # --| | KEYWORD '{' NUMBER '}' # with index for arrays# --| constant -> KEYWORD # see predefined constants at lexeme # --| For strings only the operator '+' is implemented as concatenation --| Strings without an operator in between are also concatenated --| A number followed by a constant is a multiplication (4KiB=4*1024) --| --| Property File Parser --| properties -> property_list --| property_list -> property SEP property_list --| | EMPTY --| property -> keyword_list '=' SUPPLEMENT --| keyword_list -> KEYWORD '.' keyword_list --| | KEYWORD --| SUPPLEMENT is a string in double quotation marks ("property") ------------------------------------------------------------------------ ... print CLE_DOCTYP_CHAPTER == Properties [[CLEP.APPENDIX.PROPERTIES]] == Appendix F. Properties All properties can be written to a global property file with the built-in function <>: ------------------------------------------------------------------------ 'GENPROP filename'. ------------------------------------------------------------------------ A property file for a certain command can be generated with: ------------------------------------------------------------------------ 'GENPROP command=filename' ------------------------------------------------------------------------ The first command shows the valid root path for the property file. A property file can contain properties for more than one root path. The property file parser will only interpret properties where the root matches, i.e. if the property file is assigned to a certain owner and possibly to a certain command, then only properties for this owner, the program itself and possibly the command will be accepted, all other properties are ignored. The second long comment gives some help for handling a property file. Thereafter the generated properties for this root are listed for all supported commands. The format is: ------------------------------------------------------------------------ path = SUPPLEMENT # Type: tttttt Help: hhh...hhh # ------------------------------------------------------------------------ The path denotes the unique dotted keyword list for one argument. The 'SUPPLEMENT' is a string normally in double quotation marks containing the value list for this argument in accordance with the syntax of the command line parser (strings then normally in single quotation marks, a opposite usage of the quotation marks is possible but not recommended). This means for example that a string that requires apostrophes must be included in apostrophes `("'...'")`. The supplement string is returned by the corresponding command line parser if no value for this argument is entered on the command line or is included in the parameter file. Behind the property definition the type and help message are printed as comment to help in editing the generated property file. The property values can be related to the current default settings at time of generation, what means that if hard coded default values or another property file is already in use, then these values are taken over into the new property file. The property file can contain parameter which are not available on the command line. Such parameter are only documented in the property file. On the other side not all command line parameter are available as property. If a description for a property argument is available which is not a part of the user manual this description is written as comment in front of the corresponding property definition. Below you can see the documentation of all parameter which are only available as property followed by all defined default properties in form of a sample property file for all available commands. ... print CLE_DOCTYP_PROPREMAIN === Remaining Documentation === Appendix F.1. Remaining Documentation Below you can find the documentation for all parameters which are only available over the property definitions. These parameters are not a part of the description for each command above. This list is generated and can be empty. In this case all parameters are available over the command line. If available, the manual page otherwise the help message is printed. .DESCRIPTION FOR limes.flcl.INFO.LOG.DESTINATION.SYSTEM: (TYPE: OBJECT) Use system logging facility The SYSTEM destination allows the log messages to be written to the logging system of the operating system. On Unix and z/OS(R) systems the syslog() call is used. On Windows(R) the event logging facility is used. ----------------------------------------------------------------------- NOTE: On Windows(R) this requires the registry key entry: HKEY_LOCAL_MACHINE SYSTEM CurrentControlSet Services EventLog Application FLM ----------------------------------------------------------------------- This registry key will be created by using the DLL flevent.dll .HELP FOR limes.flcl.INFO.LOG.DESTINATION.SYSTEM: (TYPE: OBJECT) Use system logging facility .DESCRIPTION FOR limes.flcl.CONV.LOGGING.SYSTEM: (TYPE: OBJECT) Use system logging facility The SYSTEM destination allows the log messages to be written to the logging system of the operating system. On Unix and z/OS(R) systems the syslog() call is used. On Windows(R) the event logging facility is used. ----------------------------------------------------------------------- NOTE: On Windows(R) this requires the registry key entry: HKEY_LOCAL_MACHINE SYSTEM CurrentControlSet Services EventLog Application FLM ----------------------------------------------------------------------- This registry key will be created by using the DLL flevent.dll .HELP FOR limes.flcl.CONV.LOGGING.SYSTEM: (TYPE: OBJECT) Use system logging facility .DESCRIPTION FOR limes.flcl.XCNV.LOG.DESTINATION.SYSTEM: (TYPE: OBJECT) Use system logging facility The SYSTEM destination allows the log messages to be written to the logging system of the operating system. On Unix and z/OS(R) systems the syslog() call is used. On Windows(R) the event logging facility is used. ----------------------------------------------------------------------- NOTE: On Windows(R) this requires the registry key entry: HKEY_LOCAL_MACHINE SYSTEM CurrentControlSet Services EventLog Application FLM ----------------------------------------------------------------------- This registry key will be created by using the DLL flevent.dll .HELP FOR limes.flcl.XCNV.LOG.DESTINATION.SYSTEM: (TYPE: OBJECT) Use system logging facility .DESCRIPTION FOR limes.flcl.ICNV.LOG.DESTINATION.SYSTEM: (TYPE: OBJECT) Use system logging facility The SYSTEM destination allows the log messages to be written to the logging system of the operating system. On Unix and z/OS(R) systems the syslog() call is used. On Windows(R) the event logging facility is used. ----------------------------------------------------------------------- NOTE: On Windows(R) this requires the registry key entry: HKEY_LOCAL_MACHINE SYSTEM CurrentControlSet Services EventLog Application FLM ----------------------------------------------------------------------- This registry key will be created by using the DLL flevent.dll .HELP FOR limes.flcl.ICNV.LOG.DESTINATION.SYSTEM: (TYPE: OBJECT) Use system logging facility .DESCRIPTION FOR limes.flcl.FLAM.LOG.DESTINATION.SYSTEM: (TYPE: OBJECT) Use system logging facility The SYSTEM destination allows the log messages to be written to the logging system of the operating system. On Unix and z/OS(R) systems the syslog() call is used. On Windows(R) the event logging facility is used. ----------------------------------------------------------------------- NOTE: On Windows(R) this requires the registry key entry: HKEY_LOCAL_MACHINE SYSTEM CurrentControlSet Services EventLog Application FLM ----------------------------------------------------------------------- This registry key will be created by using the DLL flevent.dll .HELP FOR limes.flcl.FLAM.LOG.DESTINATION.SYSTEM: (TYPE: OBJECT) Use system logging facility .DESCRIPTION FOR limes.flcl.GREP.LOGGING.SYSTEM: (TYPE: OBJECT) Use system logging facility The SYSTEM destination allows the log messages to be written to the logging system of the operating system. On Unix and z/OS(R) systems the syslog() call is used. On Windows(R) the event logging facility is used. ----------------------------------------------------------------------- NOTE: On Windows(R) this requires the registry key entry: HKEY_LOCAL_MACHINE SYSTEM CurrentControlSet Services EventLog Application FLM ----------------------------------------------------------------------- This registry key will be created by using the DLL flevent.dll .HELP FOR limes.flcl.GREP.LOGGING.SYSTEM: (TYPE: OBJECT) Use system logging facility .DESCRIPTION FOR limes.flcl.XCHK.LOG.DESTINATION.SYSTEM: (TYPE: OBJECT) Use system logging facility The SYSTEM destination allows the log messages to be written to the logging system of the operating system. On Unix and z/OS(R) systems the syslog() call is used. On Windows(R) the event logging facility is used. ----------------------------------------------------------------------- NOTE: On Windows(R) this requires the registry key entry: HKEY_LOCAL_MACHINE SYSTEM CurrentControlSet Services EventLog Application FLM ----------------------------------------------------------------------- This registry key will be created by using the DLL flevent.dll .HELP FOR limes.flcl.XCHK.LOG.DESTINATION.SYSTEM: (TYPE: OBJECT) Use system logging facility .DESCRIPTION FOR limes.flcl.HASH.LOG.DESTINATION.SYSTEM: (TYPE: OBJECT) Use system logging facility The SYSTEM destination allows the log messages to be written to the logging system of the operating system. On Unix and z/OS(R) systems the syslog() call is used. On Windows(R) the event logging facility is used. ----------------------------------------------------------------------- NOTE: On Windows(R) this requires the registry key entry: HKEY_LOCAL_MACHINE SYSTEM CurrentControlSet Services EventLog Application FLM ----------------------------------------------------------------------- This registry key will be created by using the DLL flevent.dll .HELP FOR limes.flcl.HASH.LOG.DESTINATION.SYSTEM: (TYPE: OBJECT) Use system logging facility .DESCRIPTION FOR limes.flcl.DIFF.LOGGING.SYSTEM: (TYPE: OBJECT) Use system logging facility The SYSTEM destination allows the log messages to be written to the logging system of the operating system. On Unix and z/OS(R) systems the syslog() call is used. On Windows(R) the event logging facility is used. ----------------------------------------------------------------------- NOTE: On Windows(R) this requires the registry key entry: HKEY_LOCAL_MACHINE SYSTEM CurrentControlSet Services EventLog Application FLM ----------------------------------------------------------------------- This registry key will be created by using the DLL flevent.dll .HELP FOR limes.flcl.DIFF.LOGGING.SYSTEM: (TYPE: OBJECT) Use system logging facility .DESCRIPTION FOR limes.flcl.UTIL.LOG.DESTINATION.SYSTEM: (TYPE: OBJECT) Use system logging facility The SYSTEM destination allows the log messages to be written to the logging system of the operating system. On Unix and z/OS(R) systems the syslog() call is used. On Windows(R) the event logging facility is used. ----------------------------------------------------------------------- NOTE: On Windows(R) this requires the registry key entry: HKEY_LOCAL_MACHINE SYSTEM CurrentControlSet Services EventLog Application FLM ----------------------------------------------------------------------- This registry key will be created by using the DLL flevent.dll .HELP FOR limes.flcl.UTIL.LOG.DESTINATION.SYSTEM: (TYPE: OBJECT) Use system logging facility .DESCRIPTION FOR limes.flcl.KEY.LOG.DESTINATION.SYSTEM: (TYPE: OBJECT) Use system logging facility The SYSTEM destination allows the log messages to be written to the logging system of the operating system. On Unix and z/OS(R) systems the syslog() call is used. On Windows(R) the event logging facility is used. ----------------------------------------------------------------------- NOTE: On Windows(R) this requires the registry key entry: HKEY_LOCAL_MACHINE SYSTEM CurrentControlSet Services EventLog Application FLM ----------------------------------------------------------------------- This registry key will be created by using the DLL flevent.dll .HELP FOR limes.flcl.KEY.LOG.DESTINATION.SYSTEM: (TYPE: OBJECT) Use system logging facility .DESCRIPTION FOR limes.flcl.XCMP.LOG.DESTINATION.SYSTEM: (TYPE: OBJECT) Use system logging facility The SYSTEM destination allows the log messages to be written to the logging system of the operating system. On Unix and z/OS(R) systems the syslog() call is used. On Windows(R) the event logging facility is used. ----------------------------------------------------------------------- NOTE: On Windows(R) this requires the registry key entry: HKEY_LOCAL_MACHINE SYSTEM CurrentControlSet Services EventLog Application FLM ----------------------------------------------------------------------- This registry key will be created by using the DLL flevent.dll .HELP FOR limes.flcl.XCMP.LOG.DESTINATION.SYSTEM: (TYPE: OBJECT) Use system logging facility .DESCRIPTION FOR limes.flcl.XDCO.LOG.DESTINATION.SYSTEM: (TYPE: OBJECT) Use system logging facility The SYSTEM destination allows the log messages to be written to the logging system of the operating system. On Unix and z/OS(R) systems the syslog() call is used. On Windows(R) the event logging facility is used. ----------------------------------------------------------------------- NOTE: On Windows(R) this requires the registry key entry: HKEY_LOCAL_MACHINE SYSTEM CurrentControlSet Services EventLog Application FLM ----------------------------------------------------------------------- This registry key will be created by using the DLL flevent.dll .HELP FOR limes.flcl.XDCO.LOG.DESTINATION.SYSTEM: (TYPE: OBJECT) Use system logging facility ... print CLE_DOCTYP_PROPDEFAULTS === Predefined Defaults === Appendix F.2. Predefined Defaults Below you can find a sample property file which contains all predefined default values for all supported commands when this documentation was created. ------------------------------------------------------------------------ # Property file for: limes.flcl # #------------------------------------------------------------------- # # # # The property file can be used to overwrite the default values # # used if the argument is not defined on the command line. # # # #------------------------------------------------------------------- # # # # The values is assigned between "" conforming to the syntax. # # Example NUMBER array : "4711, 1, 2, 3" # # Example STRING array : "'str1' x'303000''str2',a'abc'" # # Example FLOAT array : "123.34, 1.58, PI" (PI as constant) # # # # The last example shows that one can use key words if a list # # of constants is defined for this argument. # # # # For a SWITCH one can use the special key words ON/OFF to enable or # # disable the SWITCH or define the value as a number # # Examples for a SWITCH : "ON"/"OFF"/"4711" # # # # For an OBJECT only the special key word INIT can be used to ensure # # that this OBJECT will be initialized if it was not set on the # # command line. If INIT is not set, then the elements of the OBJECT # # will be initialized only if you type at least obj() in the command # # line. If you want an object to be initialized when you don't use it# # on the command line then the special key word must be set. # # Examples for an OBJECT: ""/"INIT" # # # # For an OVERLAY it is the same logic as for objects but the keyword # # of the element to initialize must be used if the overlay is not # # set in the command line. # # Example OVERLAY array : "LINE TRIANGLE LINE RECTANGLE" # # Example for a OVERLAY : "RECTANGLE" # # # #------------------------------------------------------------------- # limes.flcl.CONV.READ.BINARY.SUBSYSTEM.NAME="'FLAM'" # TYPE: STRING HELP: Name of the subsystem # limes.flcl.CONV.READ.BINARY.SUBSYSTEM.PARM="''" # TYPE: STRING HELP: Parameter list for the subsystem (comma separated) # limes.flcl.CONV.READ.CHARACTER.DECODE="CMPDEC" # TYPE: NUMBER HELP: Decode encoded data first (remove base encodings) # limes.flcl.CONV.READ.CHARACTER.SUBSYSTEM.NAME="'FLAM'" # TYPE: STRING HELP: Name of the subsystem # limes.flcl.CONV.READ.CHARACTER.SUBSYSTEM.PARM="''" # TYPE: STRING HELP: Parameter list for the subsystem (comma separated) # limes.flcl.CONV.READ.TEXT.DECODE="CMPDEC" # TYPE: NUMBER HELP: Decode encoded data first (remove base encodings) # limes.flcl.CONV.READ.TEXT.SUBSYSTEM.NAME="'FLAM'" # TYPE: STRING HELP: Name of the subsystem # limes.flcl.CONV.READ.TEXT.SUBSYSTEM.PARM="''" # TYPE: STRING HELP: Parameter list for the subsystem (comma separated) # limes.flcl.CONV.READ.XML.SUBSYSTEM.NAME="'FLAM'" # TYPE: STRING HELP: Name of the subsystem # limes.flcl.CONV.READ.XML.SUBSYSTEM.PARM="''" # TYPE: STRING HELP: Parameter list for the subsystem (comma separated) # limes.flcl.CONV.READ.RECORD.SUBSYSTEM.NAME="'FLAM'" # TYPE: STRING HELP: Name of the subsystem # limes.flcl.CONV.READ.RECORD.SUBSYSTEM.PARM="''" # TYPE: STRING HELP: Parameter list for the subsystem (comma separated) # limes.flcl.CONV.WRITE.BINARY.FALLOC.SUBSYSTEM.NAME="'FLAM'" # TYPE: STRING HELP: Name of the subsystem # limes.flcl.CONV.WRITE.BINARY.FALLOC.SUBSYSTEM.PARM="''" # TYPE: STRING HELP: Parameter list for the subsystem (comma separated) # limes.flcl.CONV.WRITE.CHARACTER.FALLOC.SUBSYSTEM.NAME="'FLAM'" # TYPE: STRING HELP: Name of the subsystem # limes.flcl.CONV.WRITE.CHARACTER.FALLOC.SUBSYSTEM.PARM="''" # TYPE: STRING HELP: Parameter list for the subsystem (comma separated) # limes.flcl.CONV.WRITE.TEXT.FALLOC.SUBSYSTEM.NAME="'FLAM'" # TYPE: STRING HELP: Name of the subsystem # limes.flcl.CONV.WRITE.TEXT.FALLOC.SUBSYSTEM.PARM="''" # TYPE: STRING HELP: Parameter list for the subsystem (comma separated) # limes.flcl.CONV.WRITE.XML.FALLOC.SUBSYSTEM.NAME="'FLAM'" # TYPE: STRING HELP: Name of the subsystem # limes.flcl.CONV.WRITE.XML.FALLOC.SUBSYSTEM.PARM="''" # TYPE: STRING HELP: Parameter list for the subsystem (comma separated) # limes.flcl.CONV.WRITE.RECORD.FALLOC.SUBSYSTEM.NAME="'FLAM'" # TYPE: STRING HELP: Name of the subsystem # limes.flcl.CONV.WRITE.RECORD.FALLOC.SUBSYSTEM.PARM="''" # TYPE: STRING HELP: Parameter list for the subsystem (comma separated) # limes.flcl.XCNV.INPUT.SAVE.FILE.FIO.BLK.SUBSYS.NAME="'FLAM'" # TYPE: STRING HELP: Name of the subsystem # limes.flcl.XCNV.INPUT.SAVE.FILE.FIO.BLK.SUBSYS.PARM="''" # TYPE: STRING HELP: Parameter list for the subsystem (comma separated) # limes.flcl.XCNV.INPUT.SAVE.FILE.FIO.REC.SUBSYS.NAME="'FLAM'" # TYPE: STRING HELP: Name of the subsystem # limes.flcl.XCNV.INPUT.SAVE.FILE.FIO.REC.SUBSYS.PARM="''" # TYPE: STRING HELP: Parameter list for the subsystem (comma separated) # limes.flcl.XCNV.INPUT.SAVE.FILE.FIO.TXT.SUBSYS.NAME="'FLAM'" # TYPE: STRING HELP: Name of the subsystem # limes.flcl.XCNV.INPUT.SAVE.FILE.FIO.TXT.SUBSYS.PARM="''" # TYPE: STRING HELP: Parameter list for the subsystem (comma separated) # limes.flcl.XCNV.OUTPUT.SAVE.FILE.FIO.BLK.FALLOC.SUBSYSTEM.NAME="'FLAM'" # TYPE: STRING HELP: Name of the subsystem # limes.flcl.XCNV.OUTPUT.SAVE.FILE.FIO.BLK.FALLOC.SUBSYSTEM.PARM="''" # TYPE: STRING HELP: Parameter list for the subsystem (comma separated) # limes.flcl.XCNV.OUTPUT.SAVE.FILE.FIO.REC.FALLOC.SUBSYSTEM.NAME="'FLAM'" # TYPE: STRING HELP: Name of the subsystem # limes.flcl.XCNV.OUTPUT.SAVE.FILE.FIO.REC.FALLOC.SUBSYSTEM.PARM="''" # TYPE: STRING HELP: Parameter list for the subsystem (comma separated) # limes.flcl.XCNV.OUTPUT.SAVE.FILE.FIO.TXT.FALLOC.SUBSYSTEM.NAME="'FLAM'" # TYPE: STRING HELP: Name of the subsystem # limes.flcl.XCNV.OUTPUT.SAVE.FILE.FIO.TXT.FALLOC.SUBSYSTEM.PARM="''" # TYPE: STRING HELP: Parameter list for the subsystem (comma separated) # limes.flcl.XCNV.OUTPUT.SAVE.FILE.FIO.ZIP.FALLOC.SUBSYSTEM.NAME="'FLAM'" # TYPE: STRING HELP: Name of the subsystem # limes.flcl.XCNV.OUTPUT.SAVE.FILE.FIO.ZIP.FALLOC.SUBSYSTEM.PARM="''" # TYPE: STRING HELP: Parameter list for the subsystem (comma separated) # limes.flcl.ICNV.FALLOC.SUBSYSTEM.NAME="'FLAM'" # TYPE: STRING HELP: Name of the subsystem # limes.flcl.ICNV.FALLOC.SUBSYSTEM.PARM="''" # TYPE: STRING HELP: Parameter list for the subsystem (comma separated) # limes.flcl.GREP.FALLOC.SUBSYSTEM.NAME="'FLAM'" # TYPE: STRING HELP: Name of the subsystem # limes.flcl.GREP.FALLOC.SUBSYSTEM.PARM="''" # TYPE: STRING HELP: Parameter list for the subsystem (comma separated) # limes.flcl.XCHK.INPUT.SAVE.FILE.FIO.BLK.SUBSYS.NAME="'FLAM'" # TYPE: STRING HELP: Name of the subsystem # limes.flcl.XCHK.INPUT.SAVE.FILE.FIO.BLK.SUBSYS.PARM="''" # TYPE: STRING HELP: Parameter list for the subsystem (comma separated) # limes.flcl.XCHK.INPUT.SAVE.FILE.FIO.REC.SUBSYS.NAME="'FLAM'" # TYPE: STRING HELP: Name of the subsystem # limes.flcl.XCHK.INPUT.SAVE.FILE.FIO.REC.SUBSYS.PARM="''" # TYPE: STRING HELP: Parameter list for the subsystem (comma separated) # limes.flcl.XCHK.INPUT.SAVE.FILE.FIO.TXT.SUBSYS.NAME="'FLAM'" # TYPE: STRING HELP: Name of the subsystem # limes.flcl.XCHK.INPUT.SAVE.FILE.FIO.TXT.SUBSYS.PARM="''" # TYPE: STRING HELP: Parameter list for the subsystem (comma separated) # limes.flcl.DIFF.READ.BINARY.SUBSYSTEM.NAME="'FLAM'" # TYPE: STRING HELP: Name of the subsystem # limes.flcl.DIFF.READ.BINARY.SUBSYSTEM.PARM="''" # TYPE: STRING HELP: Parameter list for the subsystem (comma separated) # limes.flcl.DIFF.READ.CHARACTER.DECODE="CMPDEC" # TYPE: NUMBER HELP: Decode encoded data first (remove base encodings) # limes.flcl.DIFF.READ.CHARACTER.SUBSYSTEM.NAME="'FLAM'" # TYPE: STRING HELP: Name of the subsystem # limes.flcl.DIFF.READ.CHARACTER.SUBSYSTEM.PARM="''" # TYPE: STRING HELP: Parameter list for the subsystem (comma separated) # limes.flcl.DIFF.READ.TEXT.DECODE="CMPDEC" # TYPE: NUMBER HELP: Decode encoded data first (remove base encodings) # limes.flcl.DIFF.READ.TEXT.SUBSYSTEM.NAME="'FLAM'" # TYPE: STRING HELP: Name of the subsystem # limes.flcl.DIFF.READ.TEXT.SUBSYSTEM.PARM="''" # TYPE: STRING HELP: Parameter list for the subsystem (comma separated) # limes.flcl.DIFF.READ.XML.SUBSYSTEM.NAME="'FLAM'" # TYPE: STRING HELP: Name of the subsystem # limes.flcl.DIFF.READ.XML.SUBSYSTEM.PARM="''" # TYPE: STRING HELP: Parameter list for the subsystem (comma separated) # limes.flcl.DIFF.READ.RECORD.SUBSYSTEM.NAME="'FLAM'" # TYPE: STRING HELP: Name of the subsystem # limes.flcl.DIFF.READ.RECORD.SUBSYSTEM.PARM="''" # TYPE: STRING HELP: Parameter list for the subsystem (comma separated) # limes.flcl.DIFF.COMPARE.BINARY.SUBSYSTEM.NAME="'FLAM'" # TYPE: STRING HELP: Name of the subsystem # limes.flcl.DIFF.COMPARE.BINARY.SUBSYSTEM.PARM="''" # TYPE: STRING HELP: Parameter list for the subsystem (comma separated) # limes.flcl.DIFF.COMPARE.CHARACTER.DECODE="CMPDEC" # TYPE: NUMBER HELP: Decode encoded data first (remove base encodings) # limes.flcl.DIFF.COMPARE.CHARACTER.SUBSYSTEM.NAME="'FLAM'" # TYPE: STRING HELP: Name of the subsystem # limes.flcl.DIFF.COMPARE.CHARACTER.SUBSYSTEM.PARM="''" # TYPE: STRING HELP: Parameter list for the subsystem (comma separated) # limes.flcl.DIFF.COMPARE.TEXT.DECODE="CMPDEC" # TYPE: NUMBER HELP: Decode encoded data first (remove base encodings) # limes.flcl.DIFF.COMPARE.TEXT.SUBSYSTEM.NAME="'FLAM'" # TYPE: STRING HELP: Name of the subsystem # limes.flcl.DIFF.COMPARE.TEXT.SUBSYSTEM.PARM="''" # TYPE: STRING HELP: Parameter list for the subsystem (comma separated) # limes.flcl.DIFF.COMPARE.XML.SUBSYSTEM.NAME="'FLAM'" # TYPE: STRING HELP: Name of the subsystem # limes.flcl.DIFF.COMPARE.XML.SUBSYSTEM.PARM="''" # TYPE: STRING HELP: Parameter list for the subsystem (comma separated) # limes.flcl.DIFF.COMPARE.RECORD.SUBSYSTEM.NAME="'FLAM'" # TYPE: STRING HELP: Name of the subsystem # limes.flcl.DIFF.COMPARE.RECORD.SUBSYSTEM.PARM="''" # TYPE: STRING HELP: Parameter list for the subsystem (comma separated) # limes.flcl.XCMP.INPUT.SAVE.FILE.FIO.BLK.SUBSYS.NAME="'FLAM'" # TYPE: STRING HELP: Name of the subsystem # limes.flcl.XCMP.INPUT.SAVE.FILE.FIO.BLK.SUBSYS.PARM="''" # TYPE: STRING HELP: Parameter list for the subsystem (comma separated) # limes.flcl.XCMP.INPUT.SAVE.FILE.FIO.REC.SUBSYS.NAME="'FLAM'" # TYPE: STRING HELP: Name of the subsystem # limes.flcl.XCMP.INPUT.SAVE.FILE.FIO.REC.SUBSYS.PARM="''" # TYPE: STRING HELP: Parameter list for the subsystem (comma separated) # limes.flcl.XCMP.INPUT.SAVE.FILE.FIO.TXT.SUBSYS.NAME="'FLAM'" # TYPE: STRING HELP: Name of the subsystem # limes.flcl.XCMP.INPUT.SAVE.FILE.FIO.TXT.SUBSYS.PARM="''" # TYPE: STRING HELP: Parameter list for the subsystem (comma separated) # limes.flcl.XDCO.OUTPUT.SAVE.FILE.FIO.BLK.FALLOC.SUBSYSTEM.NAME="'FLAM'" # TYPE: STRING HELP: Name of the subsystem # limes.flcl.XDCO.OUTPUT.SAVE.FILE.FIO.BLK.FALLOC.SUBSYSTEM.PARM="''" # TYPE: STRING HELP: Parameter list for the subsystem (comma separated) # limes.flcl.XDCO.OUTPUT.SAVE.FILE.FIO.REC.FALLOC.SUBSYSTEM.NAME="'FLAM'" # TYPE: STRING HELP: Name of the subsystem # limes.flcl.XDCO.OUTPUT.SAVE.FILE.FIO.REC.FALLOC.SUBSYSTEM.PARM="''" # TYPE: STRING HELP: Parameter list for the subsystem (comma separated) # limes.flcl.XDCO.OUTPUT.SAVE.FILE.FIO.TXT.FALLOC.SUBSYSTEM.NAME="'FLAM'" # TYPE: STRING HELP: Name of the subsystem # limes.flcl.XDCO.OUTPUT.SAVE.FILE.FIO.TXT.FALLOC.SUBSYSTEM.PARM="''" # TYPE: STRING HELP: Parameter list for the subsystem (comma separated) # limes.flcl.XDCO.OUTPUT.SAVE.FILE.FIO.ZIP.FALLOC.SUBSYSTEM.NAME="'FLAM'" # TYPE: STRING HELP: Name of the subsystem # limes.flcl.XDCO.OUTPUT.SAVE.FILE.FIO.ZIP.FALLOC.SUBSYSTEM.PARM="''" # TYPE: STRING HELP: Parameter list for the subsystem (comma separated) # ------------------------------------------------------------------------ ... print CLE_DOCTYP_CHAPTER == Return Codes [[CLEP.APPENDIX.RETURNCODES]] == Appendix G. Return Codes The return codes of the program are also called completion codes and returned at program termination. This content is printed on the screen with the built-in function <>. :0: command line, command syntax, mapping, execution and finish of the command was successful :1: command line, command syntax, mapping, execution and finish of the command was successful but a warning can be found in the log :2: command line, command syntax, mapping, execution was successful but cleanup of the command failed (may not happened) :4: command line, command syntax and mapping was successful but execution of the command returned with a warning :8: command line, command syntax and mapping was successful but execution of the command returned with an error :12: command line and command syntax was OK but mapping of the parameter for command execution failed :16: command line was OK but command syntax was wrong (error from command line parser) :20: command string was wrong (please use built-in function "SYNTAX" for more information) :24: initialization of the parameter structure for the command failed (may not happened) :28: configuration is wrong (determination of configuration data failed, configuration file might be damaged) :32: table error (something within the predefined tables is wrong (internal error)) :36: system error (e.g. load of environment or open of file failed) :40: access control or license error :44: interface error (e.g. parameter pointer equals NULL (only at call of subprogram interface)) :48: memory allocation failed (e.g. dynamic string handling) :64: fatal error (basic things are damaged) :>64: special condition codes from the command for job control The command line is interpreted by CLE the command string by CLP. For example: ------------------------------------------------------------------------ :> flcl conv "read.file='test.txt' write.flam(file='test.adc')" | | |-- the command string is compiled by CLP | | | and might result in a syntax error | |-- conv is part of the command line |-- flcl is part of the command line :> flcl conv=para.txt | | |-- para.txt is part of the command line, but the content | | of para.txt might contain a CLP syntax error | |-- conv is part of the command line |-- flcl is part of the command line ------------------------------------------------------------------------ A command execution (run) will return 0 or 1 on success, 4 if a warning occurs (only some of the files converted), 8 in case of an error or special condition codes greater then 64 can be returned. If the command execution was successful (return code 0) but a relevant warnings was logged then the return code is 1 (anything was fine, but please have a look in the log (e.g. a key is close to expire)). A return code of 2 indicates that a call to the finish function failed. Such a fail of the finish function is not recognizable if the run function (command execution) returns with a warning or an error. On the other side, if the finish failed then an additional warning in the log cannot determined because the condition code is still 2. All completion codes bigger than 8 and smaller or equal to 64 indicate an error in front of the command execution. A relevant warning is a warning written to the log by a used component. Warnings written by components which are removed from procession because the format does not fit or something else, are still in the log but not relevant for the completion code 1. ... print CLE_DOCTYP_SPECIALCODES === Special Condition Codes === Appendix G.1. Special Condition Codes Special condition codes are issued for a dedicated job/batch control. For error conditions, which must be handled in a special way, the condition codes below are defined. :80: Defined compression limit was not achieved but the requested operation was done (FLMRTC_LIM). :88: During decompression, the input file has not been recognized as being a FLAM compressed file. The very beginning of the file is corrupted to such an extent that the FLAM syntax cannot be recognized or the file is empty (FLMRTC_CFF). :112: On charset detection, a text encoded in UTF-8 may erroneously be detected as an ASCII-based charset if the first block of data contains only ASCII characters (<128). In consequence, character conversion will eventually run into an "malformed encoding" (ENOMSG) error on the first multi-byte character which results in this condition code. In this case, it makes sense to re-run the command with the correct ASCII CCSID, for example Latin-1 (FLMRTC_TAS). :160: The default (64 KiB) or the set block size is too small. Please restart the job with a larger block size. This could happen, for example, if PGP is used with BZIP2 compression and large (900 KiB) blocks. In this case, 1 MiB would be a reasonable block size (FLMRTC_NBS). ... print CLE_DOCTYP_REASONCODES === Reason Codes [[CLEP.APPENDIX.REASONCODES]] === Appendix G.2. Reason Codes Below you can find the list of reason codes returned after command execution. Each command returns a reason code for the corresponding warning (return code 4) or error (return code 8). This content is printed on the screen with the built-in function <>. * 1 - Fatal error (may not happen) * 2 - System error (wrong size of data types) * 3 - Handle error (not in right shape) * 4 - Interface error (parameter incorrect) * 5 - Activity not possible * 6 - Memory allocation failed (not enough memory) * 7 - Length error (need more data at read or more space at write) * 8 - Control code wrong * 9 - Version not supported * 10 - Function not supported * 11 - Mode not supported * 12 - Suite not supported * 13 - Confidentiality mode not supported * 14 - Integrity mode not supported * 15 - Verification mode not supported * 16 - Wrong header checksum * 17 - Wrong pot checksum * 18 - Wrong data checksum * 19 - Wrong checksum * 20 - Wrong message authentication code (MAC) * 21 - Wrong key test value * 22 - Syntax error (file not formatted correctly) * 23 - Count error (supplied or calculated amount wrong) * 24 - End of list (handle points behind last or first element) * 25 - Delete of file failed * 26 - Type error (supplied or calculated type wrong) * 27 - Rebuild required (flush not possible) * 28 - No change (informational) * 29 - Status error (handle not in right state) * 30 - Orientation not supported * 31 - Split method not supported * 32 - Maximum delimiter amount achieved * 33 - Error at compression * 34 - Error at decompression * 35 - Maximum header length achieved * 36 - Maximum data length achieved * 37 - Open of FLAMFILE failed * 38 - Record format not supported * 39 - Writing to file failed * 40 - Reading from file failed * 41 - Get position of file pointer failed * 42 - Set position of file pointer failed * 43 - End of file (informational) * 44 - Rename of FLAMFILE failed * 45 - Delete of FLAMFILE failed * 46 - Close of FLAMFILE failed * 47 - Seek in file does not work * 48 - Set of buffer size for FIO failed * 49 - FLAMFILE format not supported * 50 - No FLAMFILE * 51 - No entry found * 52 - Construct is empty * 53 - Connection error * 54 - Unsupported FLAM-ID * 55 - Remote procedure call failed * 56 - Method not supported * 57 - Open of file failed * 58 - Error from ZLIB (GZIP) * 59 - Character set not supported * 60 - Space too small * 61 - Logging facility not available * 62 - Error from character conversion module * 63 - Open of hash output file failed * 64 - Close of file failed * 65 - Error with FKME * 66 - Error at character conversion * 67 - Info not supported * 68 - Band not supported * 69 - Open of report file failed * 70 - Size error (supplied or calculated size wrong) * 71 - Invalid character encountered * 72 - Incomplete character encountered * 73 - Error with byte order mark (BOM) * 74 - Format wrong or not supported * 75 - Auto conversion not possible * 76 - Error from BZIP2 library * 77 - Environment variable are not or cannot be defined * 78 - Dynamic load of a function failed * 79 - Access control or license violation * 80 - Compression limit not reached * 81 - Error from LZMA/XZ library * 82 - Error from XML parser (EXPAT) * 83 - Whole first block is padding * 84 - Command line parser failed * 85 - Mapping failed * 86 - Open of temporary file failed * 87 - Wrong magic bytes * 88 - Corrupted or no FLAMFILE * 89 - Initialization error * 90 - Parameter not formatted correctly * 91 - Binary data detected * 92 - From and to are equal * 93 - Data is encrypted (key required) * 94 - Key value wrong * 95 - Reallocation required * 96 - Invalid username * 97 - Authentication failed * 98 - Hash calculation failed * 99 - Processing of one or more files failed * 100 - Hash/checksum file is empty * 101 - Read of hash/checksum file failed * 102 - Name of hash/checksum file is not valid * 103 - Hash/checksum file is not formatted correctly * 104 - Open of code table failed * 105 - Code table is not formatted correctly * 106 - Attribute settings not supported * 107 - Option wrong or not supported * 108 - Invalid parameter combination * 109 - Open of info file failed * 110 - Protocol wrong or not supported * 111 - Differences found * 112 - Try again with an ASCII code page (LATIN1) for read * 113 - Data incomplete * 114 - Procedure not supported * 115 - Key not found * 116 - OpenPGP error * 117 - Algorithm not supported * 118 - Key is inactive * 119 - Key is invalid * 120 - Key is expired * 121 - Positioning failed * 122 - Sequence error, incorrect order * 123 - Update not possible * 124 - Regular expression error * 125 - Value out of range * 126 - Usage measurement not possible * 127 - Dummy processing not possible * 128 - Open of inverse file failed * 129 - Internal error (may not happen) * 130 - Micro Focus support failed * 131 - Dynamic string library error * 132 - Open of usage log failed * 133 - Serialization failed * 134 - Deserialization failed * 135 - Program call (PC) failed * 136 - Row specification wrong * 137 - Record delimiter not supported * 138 - End of table (informational) * 139 - End of member (informational) * 140 - Have more data (informational) * 141 - Alignment error * 142 - Not enough space available (internal buffer too small) * 143 - Plausibility error * 144 - Unexpected remaining rest * 145 - Length parameter too small (the resulting space is not sufficient) * 146 - Virus found * 147 - Connection was closed * 148 - Error from anti virus scanner * 149 - Authorization failed * 150 - Command execution failed * 151 - Already exists * 152 - Tell offset in file does not work * 153 - Record too long * 154 - Record too short * 155 - Dynamic allocation of a file failed * 156 - Re-open of file failed * 157 - No such file or directory * 158 - Permission denied * 159 - No space left on device * 160 - Restart with larger block size required * 161 - Close/end encountered (special handling required) * 162 - Missing field definition * 163 - Element already deleted * 164 - Error from ZSTD library * 165 - Crypto error * 166 - Open of side/parameter file failed * 167 - Write of side/parameter file failed * 168 - Length mismatch * 169 - Compile of regular expression failed * 170 - Validation based on regular expression failed * 171 - Replacement based on regular expression failed * 172 - Ignore record * 173 - Provided offset invalid * 174 - Pot not valid * 175 - Reopen failed (possible no space for bigger tables) * 176 - User table fail (possible endless recursion defined * 177 - Maximum expansion achieved * 178 - Invalid argument at open or incomplete byte sequence at processing * 179 - Invalid character encountered * 180 - No message of the desired type or malformed character encoding * 181 - Error during whitespace handling * 182 - Error from IBM Unicode Services * 183 - Error from LZ4 library * 184 - Index not valid * 185 - Make path failed * 186 - Row not found * 187 - Column not found * 188 - Wildcrads found * 189 - Empty file written ... print CLE_DOCTYP_VERSION == Version [[CLEP.APPENDIX.VERSION]] == Appendix H. Version Here you can see the version of the program and its components. This content is printed on the screen if the built-in function <> is used. ------------------------------------------------------------------------ --| FL5-FLCL VERSION: 5.1.28-33135 BUILD: RELEASE Mar 8 2024 20:54:47 --|--| FL5-FLUCRUN VERSION: 5.1.28-33135 BUILD: RELEASE Mar 8 2024 20:53:56 --|--|--| FL5-FLCUPM VERSION: 5.1.28-33135 BUILD: RELEASE Mar 8 2024 20:53:50 --|--|--|--| FL5-ORGLST VERSION: 5.1.28-33135 BUILD: RELEASE Mar 8 2024 20:54:03 --|--|--|--|--| FL5-ORGNET VERSION: 5.1.28-33135 BUILD: RELEASE Mar 8 2024 20:54:03 --|--|--|--|--|--| FL5-ORGIPN VERSION: 5.3.0-33135 BUILD: RELEASE Mar 8 2024 20:54:03 --|--|--|--|--| FL5-ORGSAV VERSION: 5.1.28-33135 BUILD: RELEASE Mar 8 2024 20:54:03 --|--|--|--|--|--| FL5-ORGFIL VERSION: 5.2.0-33135 BUILD: RELEASE Mar 8 2024 20:54:02 --|--|--|--|--|--|--| FL5-ORGFIO VERSION: 5.1.28-33135 BUILD: RELEASE Mar 8 2024 20:54:03 --|--|--|--|--|--|--|--| FL5-FIODAT VERSION: 5.1.15-33135 BUILD: RELEASE Mar 8 2024 20:53:41 --|--|--|--|--|--|--|--| FL5-FIOBLK VERSION: 5.1.58-33135 BUILD: RELEASE Mar 8 2024 20:53:41 --|--|--|--|--|--|--|--|--| FL5-FIO VERSION: 1.1.23-33135 BUILD: RELEASE Mar 8 2024 20:53:31 --|--|--|--|--|--|--|--|--|--| FL5-BIOOPN VERSION: 1.1.20-33135 BUILD: RELEASE Mar 8 2024 20:53:29 --|--|--|--|--|--|--|--|--|--|--| FL5-FLSTDIO VERSION: 1.1.9-33135 BUILD: RELEASE Mar 8 2024 20:54:16 --|--|--|--|--|--|--|--|--|--|--|--| FL5-FILELOCL VERSION: 1.1.0-33135 BUILD: RELEASE Mar 8 2024 20:54:16 --|--|--|--|--|--|--|--|--|--|--|--| FL5-FILESSH VERSION: 1.1.0-33135 BUILD: RELEASE Mar 8 2024 20:54:16 --|--|--|--|--|--|--|--|--|--|--|--|--| libssh VERSION: 0.8.90-33135 BUILD: RELEASE Mar 8 2024 20:54:16 --|--|--|--|--|--|--|--|--|--|--|--|--|--| OpenSSL VERSION: 0x1010109F-33135 BUILD: RELEASE Mar 8 2024 20:54:16 --|--|--|--|--|--|--|--|--|--|--|--| FL5-FLIOLOCL VERSION: 1.1.0-33135 BUILD: RELEASE Mar 8 2024 20:54:16 --|--|--|--|--|--|--|--|--|--|--|--| FL5-FLIOSSH VERSION: 1.1.0-33135 BUILD: RELEASE Mar 8 2024 20:54:17 --|--|--|--|--|--|--|--|--|--|--|--| FL5-DRIOLOCL VERSION: 1.1.0-33135 BUILD: RELEASE Mar 8 2024 20:54:17 --|--|--|--|--|--|--|--|--|--|--|--| FL5-DRIOSSH VERSION: 1.1.0-33135 BUILD: RELEASE Mar 8 2024 20:54:17 --|--|--|--|--|--|--|--|--|--| FL5-RIOOPN VERSION: 1.1.20-33135 BUILD: RELEASE Mar 8 2024 20:54:03 --|--|--|--|--|--|--|--|--|--|--| FL5-RIOEDZ VERSION: 1.1.3-33135 BUILD: RELEASE Mar 8 2024 20:53:40 --|--|--|--|--|--|--|--|--|--| FL5-TIOOPN VERSION: 1.1.19-33135 BUILD: RELEASE Mar 8 2024 20:54:04 --|--|--|--|--|--|--|--|--|--| FL5-YIOOPN VERSION: 1.2.15-33135 BUILD: RELEASE Mar 8 2024 20:54:04 --|--|--|--|--|--|--|--|--| FL5-CMDPRO VERSION: 1.0.0-33135 BUILD: RELEASE Mar 8 2024 20:54:18 --|--|--|--|--|--|--|--|--|--| FL5-FLMSSH VERSION: 1.0.0-33135 BUILD: RELEASE Mar 8 2024 20:54:18 --|--|--|--|--|--|--|--|--|--|--| FL5-CONNSSH VERSION: 1.1.0-33135 BUILD: RELEASE Mar 8 2024 20:54:16 --|--|--|--|--|--|--|--|--|--|--| FL5-FLCRYPTO VERSION: 1.1.0-33135 BUILD: RELEASE Mar 8 2024 20:54:27 --|--|--|--|--|--|--|--|--|--|--| FL5-FLHMAC VERSION: 1.1.0-33135 BUILD: RELEASE Mar 8 2024 20:54:27 --|--|--|--|--|--|--|--|--|--| FL5-EXECCMD VERSION: 1.1.0-33135 BUILD: RELEASE Mar 8 2024 20:54:17 --|--|--|--|--|--|--|--| FL5-FIOREC VERSION: 5.1.64-33135 BUILD: RELEASE Mar 8 2024 20:53:43 --|--|--|--|--|--|--|--| FL5-FIOTXT VERSION: 5.1.42-33135 BUILD: RELEASE Mar 8 2024 20:53:44 --|--|--|--|--|--|--|--| FL5-FIOFL4 VERSION: 5.2.101-33135 BUILD: RELEASE Mar 8 2024 20:53:42 --|--|--|--|--|--|--|--|--| FL5-FL4REC VERSION: 1.0.0-33135 BUILD: RELEASE Mar 8 2024 20:53:21 --|--|--|--|--|--|--|--| FL5-FIOZIP VERSION: 5.1.36-33135 BUILD: RELEASE Mar 8 2024 20:53:44 --|--|--|--|--|--|--|--|--| FL5-ZIP VERSION: 1.1.25-33135 BUILD: RELEASE Mar 8 2024 20:53:39 --|--|--|--|--|--|--|--|--|--| FL5-FLHASH VERSION: 1.1.0-33135 BUILD: RELEASE Mar 8 2024 20:54:27 --|--|--|--|--|--|--| FL5-ORGCNV VERSION: 5.1.28-33135 BUILD: RELEASE Mar 8 2024 20:54:02 --|--|--|--|--|--|--|--| FL5-CNVBLK VERSION: 5.1.7-33135 BUILD: RELEASE Mar 8 2024 20:53:31 --|--|--|--|--|--|--|--|--| FL5-FMTBIN VERSION: 5.1.10-33135 BUILD: RELEASE Mar 8 2024 20:53:57 --|--|--|--|--|--|--|--|--| FL5-FMTBLK VERSION: 5.1.11-33135 BUILD: RELEASE Mar 8 2024 20:53:57 --|--|--|--|--|--|--|--|--| FL5-FMTTXT VERSION: 5.2.45-33135 BUILD: RELEASE Mar 8 2024 20:53:58 --|--|--|--|--|--|--|--|--|--| libpcre2 VERSION: 10.39-33135 BUILD: RELEASE Mar 8 2024 20:53:58 --|--|--|--|--|--|--|--| FL5-CNVREC VERSION: 5.1.11-33135 BUILD: RELEASE Mar 8 2024 20:53:37 --|--|--|--|--|--|--|--|--| FL5-FMTREC VERSION: 5.1.19-33135 BUILD: RELEASE Mar 8 2024 20:53:58 --|--|--|--|--|--|--|--| FL5-CNVBAS VERSION: 5.1.23-33135 BUILD: RELEASE Mar 8 2024 20:53:30 --|--|--|--|--|--|--|--|--| FL5-BAS VERSION: 1.0.0-33135 BUILD: RELEASE Mar 8 2024 20:53:29 --|--|--|--|--|--|--|--| FL5-CNVPGP VERSION: 5.1.26-33135 BUILD: RELEASE Mar 8 2024 20:53:35 --|--|--|--|--|--|--|--|--| FL5-PGP VERSION: 1.1.19-33135 BUILD: RELEASE Mar 8 2024 20:53:37 --|--|--|--|--|--|--|--|--|--| FL5-PGPUTL VERSION: 1.1.0-33135 BUILD: RELEASE Mar 8 2024 20:53:39 --|--|--|--|--|--|--|--|--|--| FL5-PGPPAC VERSION: 1.1.0-33135 BUILD: RELEASE Mar 8 2024 20:53:38 --|--|--|--|--|--|--|--|--|--|--| FL5-SECUTL VERSION: 1.1.0-33135 BUILD: RELEASE Mar 8 2024 20:54:27 --|--|--|--|--|--|--|--|--|--| FL5-PGPKEY VERSION: 1.1.0-33135 BUILD: RELEASE Mar 8 2024 20:53:38 --|--|--|--|--|--|--|--|--|--| FL5-PGPCMP VERSION: 1.1.0-33135 BUILD: RELEASE Mar 8 2024 20:53:37 --|--|--|--|--|--|--|--|--|--|--| zlib VERSION: 1.2.12-33135 BUILD: RELEASE Mar 8 2024 20:53:37 --|--|--|--|--|--|--|--|--|--|--| libbzip2 VERSION: 1.0.8-33135 BUILD: RELEASE Mar 8 2024 20:53:37 --|--|--|--|--|--|--|--| FL5-CNVEDC VERSION: 5.1.0-33135 BUILD: RELEASE Mar 8 2024 20:53:34 --|--|--|--|--|--|--|--| FL5-CNVGZP VERSION: 5.2.43-33135 BUILD: RELEASE Mar 8 2024 20:53:36 --|--|--|--|--|--|--|--| FL5-CNVBZ2 VERSION: 5.2.29-33135 BUILD: RELEASE Mar 8 2024 20:53:31 --|--|--|--|--|--|--|--| FL5-CNVLXZ VERSION: 5.1.26-33135 BUILD: RELEASE Mar 8 2024 20:53:36 --|--|--|--|--|--|--|--|--| liblzma VERSION: 5.2.5-33135 BUILD: RELEASE Mar 8 2024 20:53:36 --|--|--|--|--|--|--|--| FL5-CNVZST VERSION: 5.2.2-33135 BUILD: RELEASE Mar 8 2024 20:53:37 --|--|--|--|--|--|--|--|--| libzstd VERSION: 1.5.2-33135 BUILD: RELEASE Mar 8 2024 20:53:37 --|--|--|--|--|--|--|--| FL5-CNVCHR VERSION: 5.2.11-33135 BUILD: RELEASE Mar 8 2024 20:53:34 --|--|--|--|--|--|--|--|--| FL5-CHR VERSION: 1.1.9-33135 BUILD: RELEASE Mar 8 2024 20:53:29 --|--|--|--|--|--|--|--|--|--| FL5-ICV VERSION: 1.2.8-33135 BUILD: RELEASE Mar 8 2024 20:54:05 --|--|--|--|--|--|--|--| FL5-CNVAVS VERSION: 5.1.0-33135 BUILD: RELEASE Mar 8 2024 20:53:36 --|--|--|--|--|--|--|--| FL5-CNVHSH VERSION: 5.1.13-33135 BUILD: RELEASE Mar 8 2024 20:53:36 --|--|--|--|--|--|--|--| FL5-CNVSIG VERSION: 5.1.1-33135 BUILD: RELEASE Mar 8 2024 20:53:36 --|--|--|--|--|--|--|--| FL5-CNVCMT VERSION: 5.1.0-33135 BUILD: RELEASE Mar 8 2024 20:53:35 --|--|--|--|--|--|--|--| FL5-CNVCPY VERSION: 5.1.3-33135 BUILD: RELEASE Mar 8 2024 20:53:34 --|--|--|--|--|--|--| FL5-ORGFMT VERSION: 5.1.28-33135 BUILD: RELEASE Mar 8 2024 20:54:03 --|--|--|--|--|--|--|--| FL5-FMTXML VERSION: 5.1.40-33135 BUILD: RELEASE Mar 8 2024 20:53:58 --|--|--|--|--|--|--|--|--| libexpat VERSION: expat_2.4.9-33135 BUILD: RELEASE Mar 8 2024 20:53:58 --|--|--|--|--|--|--|--| FL5-FMTTAB VERSION: 5.1.42-33135 BUILD: RELEASE Mar 8 2024 20:53:59 --|--|--|--|--|--|--|--|--| FL5-ELMTAB VERSION: 5.1.28-33135 BUILD: RELEASE Mar 8 2024 20:54:14 --|--|--|--|--|--|--|--|--|--| FL5-TABFIX VERSION: 5.1.6-33135 BUILD: RELEASE Mar 8 2024 20:54:19 --|--|--|--|--|--|--|--|--|--| FL5-TABLFD VERSION: 5.2.8-33135 BUILD: RELEASE Mar 8 2024 20:54:19 --|--|--|--|--|--|--|--|--|--| FL5-TABDLM VERSION: 5.1.9-33135 BUILD: RELEASE Mar 8 2024 20:54:19 --|--|--|--|--|--|--|--|--|--| FL5-TABVAR VERSION: 5.1.1-33135 BUILD: RELEASE Mar 8 2024 20:54:19 --|--|--|--|--|--|--|--|--|--| FL5-TABCSV VERSION: 5.2.11-33135 BUILD: RELEASE Mar 8 2024 20:54:20 --|--|--|--|--|--|--|--|--|--| FL5-TABTVD VERSION: 5.1.0-33135 BUILD: RELEASE Mar 8 2024 20:54:20 --|--|--|--|--|--|--|--|--|--| FL5-TABXML VERSION: 5.2.23-33135 BUILD: RELEASE Mar 8 2024 20:54:25 --|--|--|--|--|--|--|--|--|--| FL5-TABRST VERSION: 5.1.0-33135 BUILD: RELEASE Mar 8 2024 20:54:26 --|--|--|--|--|--|--|--|--| FL5-ELMPRC VERSION: 5.1.28-33135 BUILD: RELEASE Mar 8 2024 20:54:14 --|--|--|--|--|--|--|--|--|--| FL5-CPYPRC VERSION: 5.1.1-33135 BUILD: RELEASE Mar 8 2024 20:54:26 --|--|--|--|--|--|--|--|--|--| FL5-MSKPRC VERSION: 5.1.1-33135 BUILD: RELEASE Mar 8 2024 20:54:26 --|--|--|--|--|--|--|--|--|--| FL5-CNVPRC VERSION: 5.1.1-33135 BUILD: RELEASE Mar 8 2024 20:54:26 --|--|--|--|--|--|--|--|--|--| FL5-EXTPRC VERSION: 5.1.1-33135 BUILD: RELEASE Mar 8 2024 20:54:26 --|--|--|--|--|--|--|--|--| FL5-ELMCNV VERSION: 5.1.28-33135 BUILD: RELEASE Mar 8 2024 20:54:14 --|--|--|--|--|--|--|--|--|--| FL5-BINCNV VERSION: 5.1.6-33135 BUILD: RELEASE Mar 8 2024 20:54:14 --|--|--|--|--|--|--|--|--|--| FL5-STRCNV VERSION: 5.1.11-33135 BUILD: RELEASE Mar 8 2024 20:54:14 --|--|--|--|--|--|--|--|--|--| FL5-INTCNV VERSION: 5.1.8-33135 BUILD: RELEASE Mar 8 2024 20:54:15 --|--|--|--|--|--|--|--|--|--| FL5-FLTCNV VERSION: 5.1.6-33135 BUILD: RELEASE Mar 8 2024 20:54:15 --|--|--| FL5-DIROPN VERSION: 1.1.6-33135 BUILD: RELEASE Mar 8 2024 20:54:28 --|--| FLAM-CLE VERSION: 1.3.87-33135 BUILD: RELEASE Mar 8 2024 20:53:46 --|--|--| FLAM-CLP VERSION: 1.3.135-33135 BUILD: RELEASE Mar 8 2024 20:53:45 ------------------------------------------------------------------------ ... print CLE_DOCTYP_ABOUT == About [[CLEP.APPENDIX.ABOUT]] == Appendix I. About This is the about information for the program (flcl). Its content is printed on the screen if the built-in function <> is used. ------------------------------------------------------------------------ --| Frankenstein Limes Command Line (FLCL(R)) (FL5-FLCL) --| VERSION: 5.1.28-33135 Build: RELEASE Mar 8 2024 20:54:47 --| Copyright (C) limes datentechnik (R) gmbh --| All rights reserved --| The FLCL (R) is a universal command line interface to use the subprograms below: --| Frankenstein Limes Universal Converter (FLUC(R)) --| Frankenstein Limes Access Method (FLAM(R)) --| Frankenstein Limes Integrated Extened Security (FLIES(R)) --| This program uses the libraries below: --|--| FL5-Core (FL5-CORE) --|--| VERSION: 5.1.28-33135 Build: RELEASE Mar 8 2024 20:53:28 --|--| Copyright (C) limes datentechnik (R) gmbh --|--| All rights reserved --|--| This library uses the libraries below: --|--|--| zlib Version 1.2.12 based on zlib license --|--|--| Copyright (C) 1995-2022 Jean-loup Gailly and Mark Adler --|--|--| Thanks to Jean-loup and Mark to provide this software library --|--|--| This library is used in unmodified form. --|--|--| for license and more information see: --|--|--| doc/txt/LICZLIB.txt in the FLAM install folder --|--|--| https://zlib.net/zlib_license.html --|--|--| https://zlib.net/ --|--|--| On IBM SystemZ we link the extended zlib (including zEDC support) of IBM --|--|--| libbzip2 Version 1.0.8, 13-Jul-2019 based on BSD like license --|--|--| Copyright (C) 1996-2010 Julian R Seward. --|--|--| This library is used in unmodified form. --|--|--| for license and more information see: --|--|--| doc/txt/LICBZIP2.txt in the FLAM install folder --|--|--| https://sourceware.org/bzip2/ --|--|--| liblzma Version 5.2.5 of XZ Utils project is placed in public domain --|--|--| Copyright (C) 2013 Igor Pavlov and Lasse Collin --|--|--| Thanks to Igor Pavlov and Lasse Collin to provide this software library --|--|--| This library is used in unmodified form. --|--|--| for license and more information see: --|--|--| doc/txt/LICLLZMA.txt in the FLAM install folder --|--|--| https://tukaani.org/xz/ --|--|--| LZMA SDK Version 21.07 of the 7zip project is placed in public domain --|--|--| Igor Pavlov : Public domain --|--|--| Thanks to Igor Pavlov and Lasse Collin to provide this software library --|--|--| This library is used in unmodified form. --|--|--| for license and more information see: --|--|--| doc/txt/LICLZMAS.txt in the FLAM install folder --|--|--| https://www.7-zip.org/sdk.html --|--|--| FLAM(R) use only the liblzma of the LZMA SDK --|--|--| libzstd Version 1.5.2 based on BSD license --|--|--| Copyright (C) 2016-present, Facebook, Inc. All rights reserved. --|--|--| This library is used in unmodified form. --|--|--| for license and more information see: --|--|--| doc/txt/LICZSTD.txt in the FLAM install folder --|--|--| https://github.com/facebook/zstd/blob/dev/LICENSE --|--|--| https://github.com/facebook/zstd --|--|--| liblz4 Version 1.9.3 based on BSD 2-Clause license --|--|--| Copyright (C) 2011-present, Yann Collet. --|--|--| This library is used in unmodified form. --|--|--| for license and more information see: --|--|--| doc/txt/LICLZ4.txt in the FLAM install folder --|--|--| https://github.com/lz4/lz4/blob/dev/LICENSE --|--|--| http://www.lz4.org --|--|--| Expat Version expat_2.4.9 based on MIT license --|--|--| Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006 Expat maintainers. --|--|--| Copyright (C) 1998, 1999, 2000 Thai Open Source Software Center Ltd and Clark Cooper --|--|--| This library is used in modified form. --|--|--| for license an more information see: --|--|--| doc/txt/LICEXPAT.txt in the FLAM install folder --|--|--| https://github.com/libexpat/libexpat/blob/master/expat/COPYING --|--|--| https://libexpat.github.io/ --|--|--| The modified Expat source can be found at: https://github.com/limes-datentechnik-gmbh/libexpat --|--|--| PCRE2 Version 10.39 based on BSD license --|--|--| Copyright (c) 1997-2021 University of Cambridge. --|--|--| This library is used in unmodified form. --|--|--| for license an more information see: --|--|--| doc/txt/LICPCRE2.txt in the FLAM install folder --|--|--| https://www.pcre.org/licence.txt --|--|--| https://www.pcre.org/ --|--|--| libcrypto Version 0x1010109F-33135 based on SSLeay license --|--|--| This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit. (http://www.openssl.org/) --|--|--| This product includes cryptographic software written by Eric Young (eay@cryptsoft.com) --|--|--| This software is used in unmodified form. --|--|--| for license and more information see: --|--|--| doc/txt/LICOPSSL.txt in the FLAM install folder --|--|--| https://www.openssl.org/source/license.html --|--|--| https://www.openssl.org/ --|--|--| FLAM(R) use the EVP interface (libcrypto) of OpenSSL 1.1.1i 8 Dec 2020 --|--|--| libssh Version 0.8.90 based on LGPL license --|--|--| Copyright (C) 2005-2008 by Aris Adamantiadis --|--|--| Copyright (C) 2008-2018 by Andreas Schneider --|--|--| This library is used in modified form. --|--|--| for license and more information see: --|--|--| doc/txt/LICLSSH.txt in the FLAM install folder --|--|--| http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html --|--|--| https://www.libssh.org/ --|--|--| The modified libssh source can be found at: https://github.com/limes-datentechnik-gmbh/libssh --|--|--| The LGPL conform replacement of the libraries are described at the end of doc/txt/README.txt --|--|--|--| EVP interface (libcrypto) of OpenSSL 1.1.1i 8 Dec 2020 (see above) --|--|--| Lightning memory-mapped database library (liblmdb) --|--|--| Version LMDB 0.9.70: (December 19, 2015) based on OpenLDAP License --|--|--| Copyright 2011-2017 Howard Chu, Symas Corp. --|--|--| This library is used in unmodified form. --|--|--| for license and more information see: --|--|--| doc/txt/LICLMDB.txt in the FLAM install folder --|--|--| http://www.OpenLDAP.org/license.html --|--|--| https://symas.com/lmdb/technical/ --|--|--| The glibc library based on LGPL license for Linux systems --|--|--| Copyright (C) 1991-2012 Free Software Foundation, Inc. --|--|--| This library is used in unmodified form. --|--|--| for license and more information see: --|--|--| doc/txt/LICLGPL.txt in the FLAM install folder or --|--|--| http://www.gnu.org/licenses/gpl-3.0.html --|--|--| http://www.fsf.org/ --|--|--| Part of the operating system (prerequisite, not part of this distribution) --|--| Frankenstein Limes Command Line Execution (FLAM-CLE) --|--| Version: 1.3.87-33135 Build: RELEASE Mar 8 2024 20:53:46 --|--| Copyright (C) limes datentechnik (R) gmbh --|--| This library is open source from the FLAM(R) project: http://www.flam.de --|--| for license see: https://github.com/limes-datentechnik-gmbh/flamclep --|--| This library uses the internal library below: --|--|--| Frankenstein Limes Command Line Parser (FLAM-CLP) --|--|--| Version: 1.3.135-33135 Build: RELEASE Mar 8 2024 20:53:45 --|--|--| Copyright (C) limes datentechnik (R) gmbh --|--|--| This library is open source from the FLAM(R) project: http://www.flam.de --|--|--| for license see: https://github.com/limes-datentechnik-gmbh/flamclep ------------------------------------------------------------------------ ... print CLE_DOCTYP_CHAPTER == Glossary [glossary] == Glossary :ADC: Abbreviation for Advanced Data Compression, which is the default compression algorithm of FLAM4. :AES: The Advanced Encryption Standard (AES) is a symmetric crypto system, the successor of DES and 3DES. It uses the Rijndael algorithm with a fixed block size of 128 bits and a variable key length of 128, 192 or 256 bits, providing a high grade of security. :ASCII: The American Standard Code for Information Interchange (ASCII) is a 7-Bit encoding, which is the source for later character sets based on more bits. :AVS: Anti virus scanning :BAS: Abbreviation for base encoding. :BCS: Banking Communication Standard. + Specification for remote data transmission between customers and credit institutions. The BCS is used, for example, in cash management systems to enable multi-bank capability, i.e. the processing of data from different credit institutions with software. :BIG ENDIAN: Endianness refers to the term byte order. A big-endian machine stores the most significant byte first, i.e. at the lowest byte address. This behavior is most important when two computers with different byte orders communicate with each other. The big-endian format is used by Motorola 6800 and 68k, Xilinx Microblaze, IBM POWER, System/360, System/370, ESA/390, z/Architecture and PDP-10. :BIN: Abbreviation for binary. :BOM: The Byte Order Mark (BOM) characterizes in which order the bytes are interpreted. This is important when exchanging data between different systems. For UTF-16 and UTF-32 a BOM sign at the beginning of the data stream is necessary, as more than one byte is used for the encoding of one character. UTF-8 uses the BOM sign "EF BB BF", which is used to mark a text file as UTF-8, even though byte order is not issue here. :BOMUTF: With this option of the FLCL, you can determine the correct UTF CCSID from the byte order mark (BOM). :BOMUCS: With this option of the FLCL, you can determine the correct UCS CCSID from the byte order mark (BOM). :BYTE ORDER: The byte order is the order in which bytes are interpreted for entities that consist of multiple bytes, e.g. Unicode characters. This is important when exchanging data between different systems. A big-endian machine stores the most significant byte first, i.e. at the lowest byte address. A little-endian machine, however, stores the least significant byte first. :BZ2: Abbreviation for BZIP2. :CANONICAL EQUIVALENCE: Canonical equivalence is a fundamental equivalence between individual Unicode characters and sequences of Unicode characters. :CASEMETHOD: FLCL offers a method for converting unicode characters to uppercase, lowercase or some special representation (CASE=UPPER/LOWER). :CCSID: This is an abbreviation used by IBM for "Coded Character Set Identifier". The encoding of a specific code page is referred to by a 16-bit number. see also: https://en.wikipedia.org/wiki/CCSID[CCSID] :CHAR: Abbreviation for the conversion of character streams. :CHR: Abbreviation for character :CLAMD: Clam Anti Virus Daemon :CNV: Abbreviation for conversion. Collects all conversion components which transform data stream in data stream (e.g. character conversion, compression, de/encryption, de/encoding, ...). :CODEPAGE: IBM introduced a numbering scheme to character encodings (16 bits). This scheme was taken over by other vendors like Microsoft, SAP or Oracle Corporation. The term Codepage is used synonymously for character encoding or character set. :CODE POINT: A code point or code position is a single character in a list of characters represented as numerical values that create the code space. The Unicode code space has a total size of 17 * 65536 code points. The same code space may have several codepages. :COMPATIBILITY EQUIVALENCE: One speaks of compatibility equivalence of two sets of characters if their full compatibility decompositions are identical. :CONV: The sub-program FLUC offers all possible conversion and formatting methods via the CONV command. These are various read and write procedures, many useful conversion tools and some special data formatting features. :CNV: Conversion component :CRY: Abbreviation for crypto(graphy). :CX7: Compression encoding as printable characters in FLAM4 :CX8: Compression encoding as binary data in FLAM4 :DAT: Abbreviation for data. :DIACRITIC: A diacritic is also called diacritical mark, diacritical point or diacritical sign. Typical diacritical marks are the acute (ยด) and grave (`), which are often called accents. Diacritical marks may be a dash, dot or tick above or below a letter, or in some other position such as within the letter or between two letters. :DIR: Abbreviation for directory (walk). :EBCDIC: The Extended Binary Coded Decimals Interchange Code (EBCDIC) was developed by IBM as 8-Bit-encoding, which, however, does not use all code words. EBCDIC originates from the older 4-Bit-Code BCD (Binary Coded Decimals) and is applied solely on Mainframes. The EBCDIC codepages are available in German, US, Swedish, Arabian, Latin-1 and other languages. Moreover, there exists a Unicode set of characters based on EBCDIC and it is called UTF-EBCDIC. :BLK: Abbreviation for block. :ENV: Abbreviation for environment. :FINGERPRINT: In public-key cryptography, a public key fingerprint is a short sequence of bytes used to identify a longer public key. Fingerprints are created by applying a cryptographic hash function to a public key. Since fingerprints are shorter than the keys they refer to, they can be used to simplify certain key management tasks. + see also: https://en.wikipedia.org/wiki/Public_key_fingerprint/[Public key fingerprint] :FIO: Abbreviation for File I/O. All components to read or write files. The C programming language has a general mechanism for reading and writing files abstracting all Input/Output to streams of bytes. The operating system offers redirection which can be very useful. Examples are the standard input stream, standard output stream and standard error stream. :FKME: FLAM Key Management Exit/Extension Service provider interface to connect FLAM till version 4 with different kinds of cryptographic infrastructure, hardware security modules and/or key management systems. :FL4: Abbreviation for FLAM in Version 4 or lower. :FL5: Abbreviation for FLAM in Version 5. :FLAM: Frankenstein Limes Access Method. FLAM is our access method for encrypted and compressed data. In particular, FLAM is a utility for converting, compressing, encrypting (with AES (Advanced Encryption Standard)), signing and formatting of mass data with simple interfaces for integration in all kinds of solutions. All this is done with a minimum of CPU utilization, utilization of co-processors and the use of professional key management solutions. Ordinarily, FLAM provides - when used as sub-program - the commands COMP and DECO and makes use of an element interface for the subsystems/plugins/drivers and also the sub-program. :FLAM4: This component writes a Flamfile record-oriented. You can state the name of a Flamfile or that of a member. :FLAMFILE: The FLAMFILE is composed like a package file, as multiple files can be compressed. It is structured clearly and divided hierarchically in records, segments and members. In this connection a segment is referred to the single matrix of a compressed file and a member to the entity of segments that are part of the compressed file. In order to ensure the universal exchangeability, the FLAMFILE has to be available in a format that is representable on all operating systems (so-called heterogeneous compatibility). Each compressed data segment is unique referring to data content, environment and time. This allows - despite compression/encryption - an access down to the record-level, without decompressing/decrypting. :FLCC: Frankenstein Limes Control Center (GUI).In contrast to FLCL this is the graphical user interface for running FLAM, FLUC and FLIES, quasi a dialogue utility :FLCL: Frankenstein Limes Command Line. FLCL offers a command line for the three sub-programs FLAM, FLUC and FLIES. It is a quasi-batch utility for the sub-programs. Moreover, FLCL is a universal data format and character set converter, which can be included easily in professional internationalization projects. It supports different input and output formats (GZIP, PDF, B64...) and can be integrated into scripts or as sub-program. More than 150 codepages are supported. FLCL can be applied to various commonly used platforms if working with processable data streams or file I/O. :FLIES: Frankenstein Limes Integrated Extended Security. The sub-program FLIES governs the compressed and encrypted segments using commands like FIND and CHNGE. In particular, it is useful for processing Flamfiles, which however cannot be decrypted or decompressed. For instance the data in the file header is managed by FLIES to re-encrypt the file, change the data access, use as backup, archive or as mediator/headend. :FLUC: Frankenstein Limes Universal Converter. FLUC is a universal text converter with special focus on the high requirements in professional internationalization projects, where Mainframes and external applications are used as central backend. :FLUCUP: FLUC Subprogram as C interface (DLL) for Data source to target conversion. :FMT: Abbreviation for formatting. All components to parse a data stream in FLAM5 element list or build a data stream from FLAM5 elements list. :FROM-CODE: The FROM-Code specifies the character encoding of the input data that used as source encoding for character conversion. :GZIP: GZIP is a compression program for nearly every operation system and uses the DEFLATE algorithm from the ZLIB library. GZIP is the short form for GNU zip. The used algorithm is a combination of LZ77 and Huffmann encoding. The source code is licensed under the GPL. The program has 9 compression steps providing either optimal CPU time or compression ratios. The compressed file has the ending ".gz". As GZIP compresses only single files. Several files must first be combined with (for example) "tar" to a tarball which can then be compressed to a ".tar.gz" file. GZIP files have a 10-byte header, containing a magic number, a version number and a timestamp. With FLCL you are able to read and write GZIP files, to mark content as text data in the header, set operating/file system or modified time (seconds since 1970). :GZP: Abbreviation for GZIP. :HOST: see MAINFRAME :HSH: Abbreviation for hash (checksum) :ICNV: Abbreviation for iconv conversion with simplified commands on the command line. :ICONV: With the standard program iconv, characters can be translated between different encodings on UNIX-like systems. As iconv is now part of the GNU C Library, actual Linux systems are equipped with iconv. Under Windows(R), iconv is provided only as DLL or static library, which is under the license of the GPL and can be used via Cygwin or GnuWin32. Iconv is also supported as Dynamic Link Library for PHP. :ID: Abbreviation for identifier. :ISO-8859: The ISO-8859 norm family contains some useful 8-bit character sets (e.g. Latin-1 to Latin-15). The frequently used Latin-1 character set is identical with the first 256 characters of the Unicode character set. These codepages are also called extended Ascii. :LITTLE ENDIAN: A little-endian machine stores the least significant byte first. The endianness of a 16, 32 or 64 bits word or even bits can occur in some Unicode representations. Also mixed forms of endianness are possible, for example when the byte order within a 16 bits word differs from that of a 16 bits word within a 32 bits word. The little-endian format is used by x86 (including x86-64), 6502 (including 65802, 65C816), Z80 (including Z180, eZ80 etc.), MCS-48, 8051, DEC Alpha, Altera Nios II, Atmel AVR, SuperH, VAX, and PDP-11. :LOGGING: In FLCL various messages (warnings, errors, debug information, important information, input data) can be logged. The messages can be redirected from stderr to stdout or a file. :LXZ: Abbreviation for LZMA XZ. :MAINFRAME: A mainframe is a very complex and powerful computer system. Its capacity is far beyond that of a common Personal Computer and that of most servers. They are applied for the highly reliable processing of mass data, mass transactions and company critical data and gain importance again in connection with server consolidation and cloud computing. :MODE: With the keyword MODE in FLCL you can select the mode of operation. :NDC: Abbreviation for No Data Compression, which can be considered as copying data in FLAM4. :NFC: This is Normalization Form C (Canonical Decomposition, followed by Canonical Composition). :NFD: This is Normalization Form D (Canonical Decomposition). :NFKC: This is Normalization Form KC (Compatibility Decomposition, followed by Canonical Composition). :NFKD: This is Normalization Form KD (Compatibility Decomposition). :Normalization: The transformation of a character sequence in one of the four normal forms is called normalization. Normalization is necessary, because there is more than one differing possibility for many characters to be represented as a sequence of Unicode characters. The four normal forms consist of one form for the canonical equivalence, one for the compatible equivalence, and both can be in a "composed" or "decomposed" form. :OS: Abbreviation for operation/file system in the header :PADDING: Padding are bytes inserted to align the data to certain lengths or storage positions. Padding bytes are most commonly appended after the the last data byte. When reading padded data, the padding bytes are discarded. :PDS: Partitioned data set. A PDSE consists of a directory and zero or more members, :PDSE: Partitioned data set extended. Exactly same as PDS in many respects. PDSE data sets can be stored only on DASD, not on tape. Interesting thing is the directory can expand automatically as needed. Additionally it has an index which helps to locate the members inside the PDSE faster. SPACE from deleted members are automatically reused in PDSE . :PGP: Abbreviation for pretty good privacy (OpenPGP). :PLATFORM NEUTRAL: The components of FLAM are platform neutral. This means that they work independently from the used operating system. Operating systems can be for example LINUX, UNIX-like systems, WINDOWS(R) or z/OS(R). :PO: Data set organisation partitioned organized. :PS: Data set physical sequential file. :REC: Abbreviation for record. :SEPA: The Single Euro Payments Area (SEPA) is a project to harmonize the way retail payments are made and processed in Euro. The motivation behind it is to make payments in Euro and across the EU as fast, safe and efficient as national payments are now. SEPA shall enable customers to make cashless Euro payments to anyone in the EU, for instance by credit transfer, direct debit or debit card. + see also: https://en.wikipedia.org/wiki/Single_Euro_Payments_Area/[SEPA] :SIG: Abbreviation for signature :SSH: Secure shell + see also: https://en.wikipedia.org/wiki/Secure_Shell/[SSH] :SUB CHARSET: A Sub Charset is a partial quantity of a character set. For instance the new identity card issued in Germany (nPa) requires that each printed character - even the diacritical characters - is "composed". It means that they remain in their original form and are not "decomposed" into several bytes. For that reason, the Sub Charset "Latin in Unicodes" with some more than 500 letters is used. :SUBCHR: FLCL can substitute characters that are unsupported in their target encoding by system specific characters (e.g. 0x1A for ASCII or 0x3F for EBCDIC pages) or by arbitrary characters. In the first case, you must use SUBCHR=SYSTEM, in the other you can define your own substitution characters. On z/OS(R), the utility iconv is available on the system and replaces all invalid characters by system specific characters, including the BOM sign. Note that it does not stop in contrast to LINUX or WINDOWS(R) but completes conversion. :SUBSTITUTE: If a character exists in the source code but not in the target code, it will be converted to a converter-defined substitute character. :SURROGATE: The Unicode code space is divided into 17 planes of 65536 code points each. Some code points have no character value, some are reserved for private use, and some are permanently reserved as non-characters. UTF-16 with code points beyond these planes is encoded in 16 bit surrogate pairs (High surrogate and low surrogate), which are in fact replacement characters. UTF-16 surrogate values are illegal in UTF-32. Note that the conversion of UTF-16 strings into UTF-8 byte sequences requires that the High and Low surrogate have to be combined correctly before they are transfered into UTF-8. :SYSTEM TABLE: FLCL makes use of a pre-loaded system substitution table for the transliteration of characters. This is comparable to "translit.h" of iconv under LINUX. :TAB: Abbreviation for table. :TAR: Tape Archiver; Short for Tape Archive, and sometimes referred to as tarball, a file that has the TAR file extension is a file in the Consolidated Unix Archive format. A program or command that can open archives is needed to open a TAR file. Because the TAR file format is used to store multiple files in one single file, it's a popular method for both archiving purposes and for sending multiple files over the internet, like for software downloads. The TAR file format is common in Linux and Unix systems, but only for storing data, not compressing it. TAR files are often compressed after being created, but those become TGZ files, using the TGZ, TAR.GZ, or GZ extension. :TARGET: Trans-European Automated Real-time Gross Settlement Express Transfer System. + see also: https://www.ecb.europa.eu/paym/target/target2/html/index.en.html/[TARGET] :TXT: Abbreviation for text. :TO-CODE: With few utilities you can convert text from one encoding to another. The TO-Code specifies the output encoding that characters are converted to. :TRANSCRIPTION: To transcribe the expression of a language means by dictionary, to represent it in another writing system rather in that, in which the language is usually written respectively in which it is available in written form. For the term of transcription it does not matter, in which medium the expression is available. Note that the transliteration of an expression is a particular type of transcription. :TRANSLATION: This is the transfer of a (mostly written) and fixed text from the original language into any target language; the process will be also denoted as "Translating". :TRANSLITERATION: To transliterate an expression represented in writing S1 into a writing system S2 means, that the characters contained in the expression are exchanged from S1 to S2 according to a fixed rule. In the simplest case, this can be a table which assigns each character of S1 a character of S2. Frequently, there are complications for the simple case, if for example a single character is assigned to a digraph or vice versa or if a character is mapped in context A onto a specific character, in context B however onto another character. For example: in a payment order from Germany, the name of the receiver must be written explicitly in Latin letters so that a transliteration of the original text with help of a table is required. :UNICODE: The so-called Unicode is an attempt, started in the 90s, to standardize a single character set that eliminates the need for different and incompatible encodings in different countries and cultures. The text should be always readable with a Unicode-supporting appropriate editor. This allows an error free data exchange (for the purpose of readability) also on a global and international level. For this character set, 8 bits (1 byte) are no longer sufficient to for a representation of every possible character. The length of characters encoded in Unicode can be between 1 and 4 bytes. ISO 10646 is a practically equal notation of the Unicode character set called Universal Character Set (UCS). :URL: Uniform Resource Locator + see also: https://en.wikipedia.org/wiki/URL/[URL] :USER TABLE: For character set conversion in FLCL you can define your own user substitution table to transliterate those characters that are not handled respectively replaced by the system table. :UTF-8: The 8-Bit Unicode Transformation Format is the most commonly used encoding for Unicode characters. The term Unicode is used equivalent to UCS. UTF-8 has a central meaning in the global character conversion for internet protocols. :UTF-16: In UTF-16 an encoded byte sequence with a length of 2 bytes is assigned to each Unicode character. UTF-16 is used in Java for internal character sequence representation. UTF-16 is the eldest format of the Unicodes. :UTF-32: UTF-32 (UCS-4) is encoded with 4 bytes and therefore the most simple Unicode representation, as other formats need variable byte lengths for their representation. One disadvantage of UTF-32 is the greater space requirement compared to UTF-8 and ISO-8859 character sets and the missing backward compatibility to ASCII.# :VSAM: Virtual Storage Access Method + see also: https://www.ibm.com/support/knowledgecenter/zosbasics/com.ibm.zos.zconcepts/zconcepts_169.htm/[VSAM] :VR8: Enhanced compression encoding as binary data in FLAM4 :ZIP: ZIP is an archive file format that supports lossless data compression. ... print CLE_DOCTYP_CHAPTER == Imprint [colophon] == Imprint ----------------------------------------------------------------------- limes datentechnik(R) gmbh Louisenstrasse 101 D-61348 Bad Homburg v.d.H. phone: +49(0)6172-5919-0 fax: +49(0)6172-5919-39 mail: info@flam.de web: www.flam.de or www.limes.de area of jurisdiction: Bad Homburg vor der Hoehe HRB 3288 (gegr. 1985) managing directors: Falk Reichbott, Ute Wiebach limes datentechnik(R): efficiency at the limit of possibility. -----------------------------------------------------------------------