_______ _ _ _ | _____| | | /\ | \ / | | | | | / \ | \ / | | | | | / /\ \ | \ / / | | |____ | | / / \ \ | |\ \ / /| | | ____| | | / / \ \ | | \ \/ / | | | | | | / /______\ \ | | \ / | | | | | | / /________\ \ | | \/ | | | | | |_____ / / \ \ | | | | |_| |_______| /_/ \_\ |_| |_| INSTALLATION OF FLAM V5 ON z/OS ------------------------------- Frankenstein Limes(r) Access Method and Infrastructure Version 5 Copyright (C) limes datentechnik gmbh All rights reserved ------------------------------------------------------------------------ limes datentechnik gmbh Louisenstrasse 101 61348 Bad Homburg / Germany Tel. ++49 (0)6172-59190 Fax ++49 (0)6172-591939 eMail support@flam.de https://www.flam.de https://www.limes.de ------------------------------------------------------------------------ PREREQUISITES ------------- Operating system, architecture and tune level as well as components of the z/OS used ------------------------------------------------------------------------ Minimum operating system: z/OSv2r2 (earlier versions on request) Minimum architecture: IBM z12 (lower on request) Optimized for architecture: IBM z15 Used components: LE none POSIX for MVS (using libc) I/O Subsystem (assembler source) IBM zlib (for zEDC support) Workload manager to schedule SRB (zIIP) ------------------------------------------------------------------------ For commercial usage and compatibility with previous FLAM V4, a separate package containing a license is required. Without this, all conversions are limited to files smaller than 1 MiB. The environment variable LANG or the system variables for LANG (see below) must be set to the local character set, so that FLAM can interpret the parameter strings correctly or convert the data from or to a readable form by default. If the environment variable is not set, then IBM-1047 (Open Systems Latin-1) for EBCDIC and ISO-8859-1 (Latin-1) for ASCII is used as default. To run our COBOL sample programs the PTF below is required: ------------------------------------------------------------------------ PH15595: Add support for Enterprise COBOL v6.3 ------------------------------------------------------------------------ Otherwise, you can run the SBUILD job (JOBLIB(SBUILD)) to rebuild all the sample programs on your system with an older version of the compiler. 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 bits 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 an storage report (RPTSTG(ON)) and define the CEEOPTS like recommended in the report. In order to generate high quality random numbers, ICSF must be active. If ICSF is not active, FLAM tries to generate some entropy since version 5.1.19. If this is not sufficient, a warning is written in the log, which leads to a completion code of 1. In earlier versions of FLAM, a fatal error with the message 'Initialization of crypto-core failed' occurred. For crypto operations that require high quality random numbers (e.g. SSH) FLAM would fail, if the CSF started task (ICSF) is not running. ATTENTION: Since version 5.1.16-19018, the runtime environment of FLCL is reused for ZLIB calls in ZEDC support for FLAM4FILEs. This could cause a user abend 4088 reason code X'63' if the NAB back chain is used. Starting with version 5.1.17-20572, the system variable &FLREUCEE can be set to OFF to disable the reuse of the language environment, but in this case the environment variables defined via FLCL are not known to the IBM-provided zlib for FLAM4FILEs. As a result, the variables must be set via DD:CEEOPTS(ENVARS(...)) to make them visible to the other enclave used by FLAM4 components for zlib processing. Since version 5.1.21 of FLAM the logic was changed. The system variable must be set to ON to activate this performance feature. By default, it will be disabled to avoid the corresponding ABENDs. PREFACE: -------- FLAM for z/OS is provided in 2 package formats: * SMPE - FMID FLAM5xx (++FUNCTION) RELFILE format to receive FROMNTS - PTF FLIC5xx (++PTF) to install the license package * XMIT - XMIT file for the load library and a FLAMFILE for the rest The XMIT installation results in only one PDSE for the load library and a PDS for all other libraries. The SMPE installation always uses PDSE libraries. Installation procedures for both are described in dedicated chapters below. After the installation procedures, you can find some optional but recommended configuration steps and documentation hints. SMPE INSTALLATION OF FLAM ON z/OS --------------------------------- Installation tips and hints to install using SMP/E. Since z/OS hosts are usually not directly connected to the internet, there is a tarball available which can be downloaded and unwrapped on any PC or directly under USS. Inside the tarball you will find the FLAM V5 FOR Z/OS product FMID=FLAM5xx as a ++FUNCTION in RELFILE format. All files (including the XML files) must be transfered as binary, because these files are already EBCDIC-encoded. Additionally, there is a FLAM5xx.XMIT file which provides a couple of install job samples. The files are ------------------------------------------------------------------------ FLAM5xx.tar FLAM5xx.xmit ------------------------------------------------------------------------ In the download area, you can also find the FLAM5xx directory containing the extracted binary package with all the RELFILES for USS. After ------------------------------------------------------------------------ tar -xf ./FLAM5xx.tar . ------------------------------------------------------------------------ there will be ------------------------------------------------------------------------ - FLAM5xx - an SMPNTS directory containing file GIMPAF.XML (binary) file GIMPAF.XSL (binary) dir SMPPTFIN (binary) dir SMPRELF (binray) ------------------------------------------------------------------------ Please upload the FLAM5xx directory in binary format somewhere into your z/OS USS file system, e.g. into '/u/user/' or into '/tmp', according to your conventions. It is important that you preserve the above SMPNTS directory structure. You should also upload FLAM5xx.xmit in binary to a data set, e.g. to userid.FLAM.SMPE.XMIT. After ------------------------------------------------------------------------ RECEIVE INDSN(FLAM.SMPE.XMIT) DSN('userid.FLAM.SMPE.CNTL') ------------------------------------------------------------------------ you will have seven jobs in userid.FLAM.SMPE.CNTL: ------------------------------------------------------------------------ - SMPGBL1 - A sample job which creates and initializes GLOBAL, TARGET (TGT1), and DLIB (DLB1) CSIs. There is no need for a specific FLAM GLOBAL. You can very well decide to share a common GLOBAL zone. Also, the zone names might be chosen to be more telling, e.g. FLAMT1 for TGT1 and FLAMD1 for DLB1. This job should finish with RC=00. - SMPDZN2 - A sample job which sets up SMP/E ZONEs, UTILITIES, OPTIONS and standard DDDEFs for GLOBAL, TGT1, and DLB1. This job should finish with RC=00. - SMPREC3 - This job does the RECEIVE FROMNTS from the SMPNTS directory designated above and basically, should run as given. Of course, if zone and other names have been changed, please adjust. Due to the REJECT which is inserted to make the job repeatable, RC=12 might be seen. The RECEIVE command should end with RC=00. - SMPDDF4 - This job allocates TARGET and DLIB data sets for the FLAM V5 on z/OS. In addition, the according DDDEFs are defined to TARGET and DLIB. There are two small naming conventions imposed: TARGET data set names contain a "T1" qualifier. Similarly, DLIB data set names contain "D1". This is to support different TARGET and DLIB environments if you are running different versions of FLAM concurrently. And secondly, TARGET DSN low level qualifiers start with "F", DLIB DSN LLQs begin with "A". As usual in SMP/E, these must not be changed. If zone and other names have been changed, please adjust. RC=00 is expected from this job. - SMPAPL5 - The APPLY job basically should run unchanged. You might see RC=04 from this job due to message GIM44402W srcname WAS NOT ASSEMBLED . . . This is acceptable since we do not want SMP/E to initiate any assemblies outside the official development cycle. - SMPACP6 - The ACCEPT job which again should run basically unchanged. This job should finish with RC=00. - SMPALI7 - A sample job which defines data set aliases to the FLAM TARGET data sets. The alias names should be used in production job control. So, when you are migrating to a new version of FLAM, you just switch the aliases and the production job control remains unchanged. This job should finish with RC=00 on first run. If an alias already exists, RC=08 is expected. ------------------------------------------------------------------------ For the demo package, the installation is now finished. You can test any conversion function using the program FLCL on files of up to 1MiB. The complete software package containing the demo license can be downloaded from the URLs below: ------------------------------------------------------------------------ German: https://www.flam.de/de/technology/download/software/ English: https://www.flam.de/en/technology/download/software/ ------------------------------------------------------------------------ To re-install the SMPE main package (new revision or build), simply run the jobs SMPREC3, SMPAPL5, SMPACP6 again. The function is packaged with a REWORK subentry which replaces a previously installed version. For this the REJECT at RECEIVE and the REDO subparameter at APPLY and ACCEPT are defined. Customers with a commercial license are provided with the following files (++PTF(FLICxx) for FMID(FLAM5xx): ------------------------------------------------------------------------ FLIC5xx.tar FLIC5xx.xmit ------------------------------------------------------------------------ In the customer specific download area (login required), you can also find the directory FLIC5xx containing the extracted package with all the RELFILES. FLIC5xx.tar contains the licensing ++PTF also in RELFILE format, and again, the .xmit file will provide install jobs. After ------------------------------------------------------------------------ tar -xf ./FLIC5xx.tar . ------------------------------------------------------------------------ there will be ------------------------------------------------------------------------ - FLIC5xx - an SMPNTS directory containing file GIMPAF.XML (binary) file GIMPAF.XSL (binary) dir SMPPTFIN (binary) dir SMPRELF (binary) ------------------------------------------------------------------------ As before, please upload the FLIC5xx directory in binary format somewhere into your z/OS USS file system or extract the tarball on USS, e.g. into '/u/user/' or into '/tmp', according to your conventions. Again, it is important that you preserve the above SMPNTS directory structure. You should also upload FLIC5xx.xmit in binary to a data set, e.g. to userid.FLIC.SMPE.XMIT. After ------------------------------------------------------------------------ RECEIVE INDSN(FLIC.SMPE.XMIT) DSN('userid.FLIC.SMPE.CNTL') ------------------------------------------------------------------------ you will have three jobs in userid.FLIC.SMPE.CNTL: ------------------------------------------------------------------------ - SMPREC3L - This job does the RECEIVE FROMNTS from the SMPNTS directory designated above and basically, should run as given. The RECEIVE command should end with RC=00. - SMPAPL5L - The APPLY job which basically should run unchanged. This job should finish with RC=00. - SMPACP6L - The ACCEPT job which again should run basically unchanged. This job should finish with RC=00. ------------------------------------------------------------------------ This license module is required to use the old FLAM4 components (utility, subprogram, record interface, FLAM-subsystem, FKME). The new FLAM5 components (FLCL utility, FLUC byte and record interface, FLUC subprogram, FLUC-subsystem, ...) on files greater than 1 MiB and for productive purposes. To download the commercial license module, login on the page below with the account information that is provided to you by email: ------------------------------------------------------------------------ German: https://www.flam.de/de/license English: https://www.flam.de/en/license ------------------------------------------------------------------------ After installation, you should see at minimum the data sets below: ------------------------------------------------------------------------ SMPE.FLAM.[D1/T1.][A/F]CLIST CLIST Procedures SMPE.FLAM.[D1/T1.][A/F]DOCHTM Documents as HTML-files (binary) SMPE.FLAM.[D1/T1.][A/F]DOCZIP Documents as ZIP-files (binary) SMPE.FLAM.[D1/T1.][A/F]DOCPDF Documents as PDF-files (binary) SMPE.FLAM.[D1/T1.][A/F]DOCTXT Documents as text-files (EBCDIC) SMPE.FLAM.[D1/T1.][A/F]IMPORT Import file for linking with DLLs SMPE.FLAM.[D1/T1.][A/F]INCLUDE Include file for C-compiling SMPE.FLAM.[D1/T1.][A/F]JOBLIB Sample Batch-Jobs SMPE.FLAM.[D1/T1.][A/F]LOAD Programs, load modules and DLLs SMPE.FLAM.[D1/T1.][A/F]MSGS Messages for FLAM panels SMPE.FLAM.[D1/T1.][A/F]OBJ Object modules (for linking) SMPE.FLAM.[D1/T1.][A/F]PANELS ISPF Panels SMPE.FLAM.[D1/T1.][A/F]SKELS Skeletons for FLAM panels SMPE.FLAM.[D1/T1.][A/F]SRCLIB Examples as source (ASM, PLI, COBOL) SMPE.FLAM.[D1/T1.][A/F]SRCLIBC Examples as source (C, C++, JAVA) SMPE.FLAM.[D1/T1.][A/F]SAMPLE Several resources useful with FLAM ------------------------------------------------------------------------ XMIT INSTALLATION OF FLAM ON z/OS --------------------------------- You need to transmit at least the binary file ------------------------------------------------------------------------ flam-5.n.m.b-zos31.xmit ------------------------------------------------------------------------ with ------------------------------------------------------------------------ n = release no. m = revision no. b = build no. ------------------------------------------------------------------------ for example as FLAMLOAD.XMIT to your host system. This file is an XMIT dataset (PS,FB,80). To install the PDSE FLAM LOAD library on your system, please use the following TSO command: ------------------------------------------------------------------------ RECEIVE INDSN(FLAMLOAD.XMIT) DSN('HLQ.FLAMV5nm.LOAD') ------------------------------------------------------------------------ The filenames may be chosen to meet your requirements. You may choose to use the version for testing purposes. However, we recommend to work with dataset name 'FLAM.LOAD' in production. For the demo package, the installation is now finished. You can test any conversion function using the program FLCL on files of up to 1MiB. The complete software package containing the demo license can be downloaded from the URL below: ------------------------------------------------------------------------ German: https://www.flam.de/de/technology/download/software/ English: https://www.flam.de/en/technology/download/software/ ------------------------------------------------------------------------ Customers with a commercial license are provided with the XMIT file ------------------------------------------------------------------------ flam-5.n-zos31.licload.xmit. ------------------------------------------------------------------------ This file can be binary uploaded to z/OS for example as ------------------------------------------------------------------------ FLAMLOAD.LICENSE.XMIT ------------------------------------------------------------------------ and a corresponding TSO RECEIVE must be done: ------------------------------------------------------------------------ RECEIVE INDSN(FLAMLOAD.LICENSE.XMIT) DSN('HLQ.FLAMV5nm.LOAD') ------------------------------------------------------------------------ We strongly recommend to use the same LOADlib filename as above. This license module is required to use the old FLAM4 components (utility, subprogram, record interface, subsystem, FKME), the new FLAM5 components (FLCL utility, FLUC byte and record interface, FLUC subprogram, ...) on files greater than 1 MiB and for productive purposes. To download the commercial license module, login to the page below with the account information that is provided to you by email: ------------------------------------------------------------------------ German: https://www.flam.de/de/license English: https://www.flam.de/en/license ------------------------------------------------------------------------ When a commercial license is installed, you can use FLAM to decompress the remaining files. For installation, the additional file ------------------------------------------------------------------------ flam-5.n.m.b-zos31.adc ------------------------------------------------------------------------ is provided. This FLAMFILE contains the data sets below: ------------------------------------------------------------------------ FLAM.FLAM.CLIST CLIST Procedures (including ISPF line commands) FLAM.FLAM.DOCHTM Documents as HTML-files (binary) FLAM.FLAM.DOCPDF Documents as PDF-files (binary) FLAM.FLAM.DOCTXT Documents as text-files (EBCDIC) FLAM.FLAM.DOCZIP Documents as ZIP-files (binary) FLAM.FLAM.IMPORT Import file for linking with DLLs FLAM.FLAM.INCLUDE Include file for C/C++-compiling FLAM.FLAM.JOBLIB Sample Batch-Jobs FLAM.FLAM.MSGS Messages for FLAM panels FLAM.FLAM.OBJ Object modules (for linking) FLAM.FLAM.PANELS ISPF Panels FLAM.FLAM.SAMPLE Several resources useful with FLAM FLAM.FLAM.SKELS Skeletons for FLAM panels FLAM.FLAM.SRCLIB Examples as source (ASM, PLI, COBOL) FLAM.FLAM.SRCLIBC Examples as source (C, C++, JAVA) ------------------------------------------------------------------------ Please transfer the file as FLAMFILE.ADC to your host system (binary, record size 512 bytes and any block size). The file requires about 160 tracks of storage on a 3390 disk. You can decompress the file in TSO with the command: ------------------------------------------------------------------------ ALLOC DD(FLPRINT) DSN(*) CALL FLAMV5nm(FLAM) 'D,FLAMF='FLAM.FLAMFILE.ADC,FLAMO=,OVOL=TEST01,OUNIT=SYSDA' ------------------------------------------------------------------------ You can use a batch job, if required: ------------------------------------------------------------------------ //DEC EXEC PGM=FLAM, // PARM='D,FLAMO=,OVOL=TEST01,OUNIT=SYSDA' //STEPLIB DD DSN=user.FLAMV5nm.LOAD,DISP=SHR //FLAMFILE DD DSN=user.FLAMFILE.ADC,DISP=SHR //FLPRINT DD SYSOUT=* ------------------------------------------------------------------------ Using the FLAMOUT parameter ------------------------------------------------------------------------ FLAMO= ------------------------------------------------------------------------ all filenames starting with 'FLAM.FLAM.' will be changed to 'user' as the 1st qualifier (HLQ) and 'pref' as 2nd qalifier (FLAMV5nm). The rest (*) remains unchanged. The output files are stored on volume TEST01 with unit SYSDA. As a last step, you can adjust your license text. Upload the binary file flam-5.n-zos31.lictext.xmit as FLAMDOCU.LICTEXT.XMIT and receive it using the command: ------------------------------------------------------------------------ RECEIVE INDSN(FLAMDOCU.LICTEXT.XMIT) DSN('HLQ.FLAMV5nm.DOCTXT') ------------------------------------------------------------------------ Below, you can find a sample batch job for a complete XMIT installation: ------------------------------------------------------------------------ //INSFLAM JOB (ACCOUNT),'INSFLAM',CLASS=D,MSGCLASS=X,NOTIFY=&SYSUID //********************************************************************* //* //* THIS SAMPLE JOB INSTALLS FLAM FROM AN XMIT LIBRARY: //* //* THE FILES BELOW ARE UPLOADED IN BINARY FORM TO THE XMIT.PDS FILE //* (DSORG=PO,RECFM=FB,LRECL=80,SPACE=(TRK,(700,70,4))) //* //* flam-5.n.m.b-zos31.xmit --> XMIT.PDS(FLAMXMIT) //* flam-5.n-zos31.licload.xmit --> XMIT.PDS(LICLOAD) //* flam-5.n-zos31.lictext.xmit --> XMIT.PDS(LICTEXT) //* flam-5.n.m.b-zos31.adc --> XMIT.PDS(FLAMADC) //* //********************************************************************* //*-------------------------------------------------------------------- //* INSTALL FLAM LOAD LIB WITH DEMO LICENSE //INSTALL1 EXEC PGM=IKJEFT01 //SYSPRINT DD SYSOUT=* //SYSTSPRT DD SYSOUT=* //SYSTSIN DD * RECEIVE INDSNAME(XMIT.PDS(FLAMXMIT)) DSNAME(FLAM.LOAD) /* //*-------------------------------------------------------------------- //* INSTALL COMMERCIAL LICENSE MODULE //INSTALL2 EXEC PGM=IKJEFT01 //SYSPRINT DD SYSOUT=* //SYSTSPRT DD SYSOUT=* //SYSTSIN DD * RECEIVE INDSNAME(XMIT.PDS(LICLOAD)) DSNAME(FLAM.LOAD) /* //*-------------------------------------------------------------------- //* INSTALL REST OF FLAM PACKAGE //INSTALL3 EXEC PGM=FLAM, // PARM='D,FLAMO=' //STEPLIB DD DSN=&SYSUID..FLAM.LOAD,DISP=SHR //FLAMFILE DD DSN=&SYSUID..XMIT.PDS(FLAMADC),DISP=SHR //FLPRINT DD SYSOUT=* //*-------------------------------------------------------------------- //* INSTALL THE LICENSE TEXT //INSTALL4 EXEC PGM=IKJEFT01 //SYSPRINT DD SYSOUT=* //SYSTSPRT DD SYSOUT=* //SYSTSIN DD * RECEIVE INDSNAME(XMIT.PDS(LICTEXT)) DSNAME(FLAM.DOCTXT) /* //*-------------------------------------------------------------------- //* SET ENVIRONMENT VARIABLE LANG //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=* //* //********************************************************************* ------------------------------------------------------------------------ Additional steps: ----------------- At this point, the XMIT or SMPE installation is finished, but we recommend making at least the following configuration settings: ------------------------------------------------------------------------ //* SET DEFAULT OWNER ID (REQUIRED FOR PERSONALISATION) //* IF THIS IS NOT DEFINED, THE DEFAULT OWNER WILL BE 'LIMES' //* THE OWNER ID IS MAINLY USED IN LOG MESSAGES AND FOR CLIENT //* SEPARATION (DIFFERENT FLCL CONFIGURATIONS CAN BE MANAGED PER OWNER //* (FLCL OWNER=clientname CONV)) //* THE OWNERID WILL DEFINED AS ENVIRONMENT VARIABLE AND CAN BE USED IN //* DATASET NAMES () OR KEY LABEL TEMPLATES '^'. IN THIS CASE //* THE OWNERID SHOULD NOT LONGER THEN 8 CHARACTERS. //SETDOID EXEC PGM=FLCL, // PARM='SETENV FLCL_DEFAULT_OWNER_ID=HLQ' //STEPLIB DD DSN=HLQ.FLAMV5nm.LOAD,DISP=SHR //SYSPRINT DD SYSOUT=* //SYSOUT DD SYSOUT=* //STDENV DD * FLCL_CONFIG_FILE=HLQ.FLAMV5nm.CONFIG /* //* SET ENVIRONMENT ID (MAINLY REQUIRED FOR KEY MANAGMENT) //* IN KEY LABEL TEMPLATES THE ('!') IS USED TO DETERMINE THE //* ENVIRONMENT (DEVELOPMENT, TEST, INTEGRATION, PRODUCTION). //SETENVID EXEC PGM=FLCL, // PARM='SETENV ENVID=T' //STEPLIB DD DSN=HLQ.FLAMV5nm.LOAD,DISP=SHR //SYSPRINT DD SYSOUT=* //SYSOUT DD SYSOUT=* //STDENV DD * FLCL_CONFIG_FILE=HLQ.FLAMV5nm.CONFIG /* //* SET ENVIRONMENT VARIABLE LANG //** IMPORTANT FOR AUTO CONVERSIONS //** AND COMMAND INTERPRETATION //* THIS IS VERY IMPORTANT FOR ALL CHARACTER CONVERSIONS //* BASED ON THIS VALUE FLAM CHOOSES THE DEFAULT CCSID AND USE IT TO //* INTERPRETE THE CHARACTERS ! $ # @ [ \ ] ^ ` { | } ~ CORRECTLY //SETLANG EXEC PGM=FLCL, // PARM='SETENV LANG=DE_DE.IBM-1141' //STEPLIB DD DSN=HLQ.FLAMV5nm.LOAD,DISP=SHR //SYSPRINT DD SYSOUT=* //SYSOUT DD SYSOUT=* //STDENV DD * FLCL_CONFIG_FILE=HLQ.FLAMV5nm.CONFIG /* ------------------------------------------------------------------------ System variables ~~~~~~~~~~~~~~~~ With FLAM >5.1.13-15352 the environment variables below (right side) can also be defined through system variables (left side) in SYS1.PARMLIB(IEASYM00). ------------------------------------------------------------------------ &FLANGLC - Language code (de) - LANG &FLANGCC - Country code (DE) - LANG &FLANGCS - Code set (IBM1141) - LANG &FLENVID - Environment ID (&SYSCLONE or T) - ENVID &FLPRISP - Default primary space in tracks - FL_PRIMARY_SPACE_TRK &FLSECSP - Default secondary space in tracks - FL_SECONDARY_SPACE_TRK &FLDIRBL - Default directory blocks - FL_DIRECTORY_BLOCKS &FLZEDC - Controls ZEDC usage for FLAM4 ADC - FL_ZEDC_SUPPORT &FLSOMC - Default SYSOUT mail class - FL_SYSOUT_MAIL_CLASS &FLSOMW - Default SYSOUT mail writer - FL_SYSOUT_MAIL_WRITER &FLKEYWD - Days to warn before a key expires - FL_KEY_EXPIRE_WARN_DAYS &FLOGIDT - Activate usage logging to SYSLOG - FL_USAGE_SYSLOG_IDENT &FLRLOGW - Deactivate return if warning in log - FL_RETURN_IF_LOG_WARNING=OFF ------------------------------------------------------------------------ Since version 5.1.26 you can list all usable system symbols for environment variables over the built-in function HLPENV of FLCL. Since then, the list above has no longer been maintained. The first three system variables are used to build the environment variable LANG like this: ------------------------------------------------------------------------ LANG=&FLANGLC[_&FLANGCC[.&FLANGCS]] (e.g. LANG=de_DE.IBM1141) ------------------------------------------------------------------------ The environment variable ENVID is set to the value of &FLENVID. Since version 5.1.11, the environment variable FL_ZEDC_SUPPORT is used to control the use of IBM zlib (RFC1951=GZIP) for MODE=ADC compression. Now, you can also use the system variable &FLZEDC to manage ZEDC usage within FLAM4 components on z/OS if the corresponding access control point of your license is set. ------------------------------------------------------------------------ ON - Always use GZIP (RFC1951) compression if MODE=ADC (if others have a ZEDC) OFF - Don't use GZIP (RFC1951) compression if MODE=ADC (to be compatible with FLAM <5.1.11) AUTO - Use RFC1951 compression for MODE=ADC if ZEDC available (default) nnn - Since version 5.1.16, a threshold with the maximum expansion of ZEDC in percent in comparison to the ADC compression result can be set to limit disk/tape usage. Attention: Only the first segment of a FLAMFILE is analyzed. Please ensure that the data characteristics do not change afterwards to profit from this automatism. ------------------------------------------------------------------------ Defined system variables do not override environment variables, i.e. if an environment variable is already set, it will not be replaced by the contents of its corresponding system variable. Since version 5.1.20 you can deactivate FLAM feature codes by defining a corresponding system variable in the form: ------------------------------------------------------------------------ &FFcode=OFF e.g. &FFZIIP=OFF - Deactivates the zIIP support ------------------------------------------------------------------------ Use 'FLCL LICENSE' to see which features are available. Only the key word 'OFF' in upper letters will deactivate the feature. This kind of feature control was implemented in the license module, to use it, a new license module must be requested. Since version 5.1.27 FLAM will use the IBM Unicode Services if possible and if it is faster. This can be controlled with the system symbols below. ------------------------------------------------------------------------ &FLIBMUS=AUTO/ON/OFF (FL_IBM_UNICODE_SERVICE) &FLCHARM=STOP/IGNORE/SUBSTIT/IDENTITY/TRANSLIT (FL_DEFAULT_CHAR_MODE) ------------------------------------------------------------------------ The first keyword (AUTO, STOP) is the default if nothing is defined. The use of the Unicode Services will change behavior in a few instances. To prevent this you can deactivate the use of the Unicode Services (OFF). If the Unicode Services are explicitly activated (ON) then conversion to character sets with fewer characters (UTF-8/16/32 to ASCII/EBCDIC) with STOP will also use the Unicode Services. The character conversion mode STOP is very expensive in terms of CPU utilization. This could result in factor 10 or more MSU for the same conversion. To not change each job step and for the best performance we recommend the settings below. ------------------------------------------------------------------------ SYMDEF(&FLIBMUS='ON') or SYMDEF(&FLCHARM='SUBSTIT') ------------------------------------------------------------------------ Below, you can find example PARMLIB definitions for a German test system where ZEDC is not used for MODE=ADC: ------------------------------------------------------------------------ SYMDEF(&FLANGLC='de') SYMDEF(&FLANGCC='DE') SYMDEF(&FLANGCS='IBM1141') SYMDEF(&FLENVID='T') SYMDEF(&FLZEDC='OFF') SYMDEF(&FLIBMUS='ON') SYMDEF(&FLCHARM='SUBSTIT') ------------------------------------------------------------------------ This will result in the environment variables below: ------------------------------------------------------------------------ LANG=de_DE.IBM1141 ENVID=T FL_ZEDC_SUPPORT=OFF ------------------------------------------------------------------------ These values are ignored if an environment variable with the same name is defined. For example, you can use the system variable &FLZEDC to change the default handling of ZEDC support from AUTO to OFF to be backwards compatible with older FLAM versions. Additionally, you can set the environment variable FL_ZEDC_SUPPORT to AUTO for all applications, which use FLAMFILEs for archiving purposes, where only you read and write the data, to have the advantages of ZEDC only internally without an impact on communication with your partners. Additional system variables (FLLOGQLx) can be set to activate usage reporting to a central log stream (see chapter 'Configure usage reporting' below). The system variable (FLREUCEE) is not available as environment variable because it controls whether FL5 environment variables are known to FLAM4 components or not (OFF). It must be OFF if NAB back chain tracking is active to prevent abend 4088 with reason code X'63' for zEDC usage (mainly happens in test environments). Since version 5.1.26 the new built-in functions LSTENV and HLPENV are available. The built-in function HLPENV shows the current system variable names for each environment variable. All system variables used can also be listed with FLCL INFO GET.SYSTEM. SAF configuration ~~~~~~~~~~~~~~~~~ Since version 5.1.21 FLAM supports additional SAF checks for the several entities below. The FLAM general resource class for this is '$FLAM'. Each resource is a concatenation of a group prefix and the entity string. 'groupfx.entity' To be backward compatible with previous releases, an undefined resource (return code 4) will be accepted by default. This also forces that the general resource class and group prefix cannot be changed. Only a return code greater or equal 8 will result in an authorization or license error, except the entity 'MUSTDEF' of group 'GLOBAL.' is defined to support strong SAF checking. With the first group prefix the 6-byte long feature code can be controlled. GROUP: 'FEATURE.' - Feature de/activation Entities: Are equal to FLAM feature names (shown in your license) Attribute: 'NONE' deactivates the feature Attribute: 'READ' activates the feature This support will fail with a license error. The group prefix is global and is only available if a new license module requested. All checks below are part of the FL5 components, can be controlled over a global group prefix and will result in an authorization error. The GOBAL group can be used by the administrator to activate the certain additional SAF checks and SMF logging. GROUP: 'GLOBAL.' - Global group to activate several SAF checks and different other activities Entity: 'MUSTDEF' - Don't accept return code 4 anything must be defined Attribute: 'NONE' activate very very strong SAF checking (return code must be >=1 to fail) Attribute: 'READ' activate very strong SAF checking (return code must >=2 to fail) Attribute: 'UPDATE' activate strong SAF checking (return code must >=4 to fail) Attribute: 'CONTROL' only simple SAF checking active (return code must >=8 to fail) Attribute: 'ALTER' No SAF checking at all (the next entities are not checked) Entity: 'POLICIES' - General policies (POLICY.) Entity: 'SMF.LOGGING' - Activate SMF-Logging (BPX.SMF checking): Requires additional READ access for the FLAM user for the entities below: BPX.SMF.119.94 SSH client connection started record BPX.SMF.119.98 SSH client transfer completion record Entity: 'CLP.CONTROL' - Parameter string (CLPAR.) Entity: 'CMD.CONTROL' - Pre- and post-processing (CMD.*.) Entity: 'AVE.CONTROL' - Anti virus exit (FAVE*.) Entity: 'CPE.CONTROL' - Column processing exit (FCPE*.) Entity: 'KME.CONTROL' - Key management exit (FKME*.) Entity: 'EDC.CONTROL' - Encryption/decryption component (EDC.*) Entity: 'FIO.CONTROL' - Source and target I/O URLs incl, member names (FIOURL.) Entity: 'FL4.CONTROL' - Control usage of FLAM4 user I/O and user access routines (FLAM4.*) Entity: 'SSH.CONNECT' - SSH connections (SSH*.) Entity: 'PGP.KEYMNGM' - PGP key management (PGPKEYM.) Entity: 'PGP.USERID' - Access to PGP user ids (PGPUID.EXCH/SIGN.) Entity: 'PGP.KEYID' - Access to PGP key ids (PGPKID.EXCH/SIGN.) Attribute: 'NONE' activate the SAF checking for the corresponding classes Attribute: 'ALTER' allow to do this without SAF The classes below are control by the global group above. These switches are required to minimize the performance impacts if no SAF checking required (don't call RACROUTE if not requested). GROUP: 'POLICY.' - Several policies Entity: 'LOW.ENTROPY' - Logging of input parameter strings (could contain credentials) Attribute: 'NONE' a low entropy is not permitted Attribute: 'ALTER' a low entropy is possible Entity: 'LOG.INPUT' - Logging of input parameter strings (could contain credentials) Attribute: 'NONE' logging of input parameter strings not possible Attribute: 'ALTER' allow logging of input parameter strings Entity: 'SSH.PCAP.ALLOWED' - SSH packet capturing is not allowed Attribute: 'NONE' PCAP not possible Attribute: 'ALTER' allow PCAP Entity: 'SSH.WEAK.HOSTKEY.CHECK.ALLOWED' - WARN and ACCEPTANY is not allowed for SSH host keys Attribute: 'NONE' only STRICT allowed (enforced the policy) Attribute: 'READ' allow ASK Attribute: 'UPDATE' allow custom key (equal to SSH.CUSTOM.HOSTKEY.ALLOWED) Attribute: 'CONTROL' allow WARN Attribute: 'ALTER' allow ACCEPTANY Entity: 'SSH.CUSTOM.HOSTKEY.ALLOWED' - A custom host key is not allowed Entity: 'SSH.CUSTOM.KNOWN.HOST.FILE.ALLOWED' - A custom known host key file is not allowed Attribute: 'NONE' enforced the policy Attribute: 'UPDATE' allow to do this Entity: 'KEY.GENERATE.PGP.EXPIRD.REQIRED' - Expiration date required Attribute: 'NONE' enforced the policy Attribute: 'UPDATE' allow to do this Entity: 'KEY.GENERATE.PGP.ALGO.RSA.KEYLEN' - Minimum required RSA key length Attribute: 'NONE' longer or equal to 4096 Attribute: 'READ' shorter than 4096 Attribute: 'UPDATE' shorter than 3072 Attribute: 'CONTRL' shorter than 2048 Attribute: 'ALTER' shorter than 1024 Entity: 'KEY.GENERATE.PGP.ALGO.DSA.ALLOWED' - DSA algorithm is not allowed Attribute: 'NONE' enforced the policy Attribute: 'READ' allow to do this Entity: 'KEY.GENERATE.PGP.ALGO.DSA.KEYLEN' - Minimum 1024 bit required Attribute: 'NONE' longer or equal to 4096 Attribute: 'READ' shorter than 4096 Attribute: 'UPDATE' shorter than 3072 Attribute: 'CONTRL' shorter than 2048 Attribute: 'ALTER' shorter than 1024 Entity: 'KEY.IMPORT.PGP.KIDVER' - Require fingerprint (KEYID) at import Attribute: 'NONE' enforced the policy (complete fingerprint (64 bit) required) Attribute: 'READ' at minimum 6 byte (48 bit) required Attribute: 'UPDATE' at minimum 4 byte (32 bit) required Attribute: 'CONTROL' at minimum 2 byte (16 bit) required Attribute: 'ALTER' allow less than 2 byte (16 bit) Entity: 'KEY.IMPORT.PGP.DOUBLE.KIDS' - Allow top key and subkey to have the key identifier Attribute: 'NONE' identical key identifier not allowed (keys must be unique) Attribute: 'READ' allow identical key identifier Entity: 'PGP.PWD' - Passwords are not allowed (enforce PKA) Attribute: 'NONE' enforced the policy Attribute: 'READ' Allow passwords at read Attribute: 'UPDATE' Allow passwords at write Attribute: 'CONTROL' Allow passwords at re-encryption Attribute: 'ALTER' allow passwords Entity: 'PGP.PWD.LEN.DEC' - Minimum required passphrase length at read (decryption) Attribute: 'NONE' longer or equal to 20 Attribute: 'READ' shorter than 20 Attribute: 'UPDATE' shorter than 16 Attribute: 'CONTRL' shorter than 12 Attribute: 'ALTER' shorter than 8 Entity: 'PGP.PWD.LEN.ENC' - Minimum required passphrase length at write (encryption) Attribute: 'NONE' longer or equal to 20 Attribute: 'READ' shorter than 20 Attribute: 'UPDATE' shorter than 16 Attribute: 'CONTRL' shorter than 12 Attribute: 'ALTER' shorter than 8 Entity: 'PGP.ENFORCE.ENCRYPTION' - Enforce encryption of PGP files Entity: 'PGP.ENFORCE.INTEGRITY' - Enforce integrity protection of PGP files Entity: 'PGP.ENFORCE.SIGNING' - Enforce signing at PGP files Attribute: 'NONE' enforced the policy Attribute: 'READ' Allow it at read Attribute: 'UPDATE' Allow it at write Attribute: 'ALTER' Allow it at all Entity: 'SYM.KEY.LEN.DEC' - Minimum required symmetric key length at read (decryption) Attribute: 'NONE' longer or equal to 256 Attribute: 'READ' shorter than 256 Attribute: 'UPDATE' shorter than 192 Attribute: 'CONTRL' shorter than 128 Attribute: 'ALTER' shorter than 64 Entity: 'SYM.KEY.LEN.ENC' - Minimum required symmetric key length at write (encryption) Attribute: 'NONE' longer or equal to 256 Attribute: 'READ' shorter than 256 Attribute: 'UPDATE' shorter than 192 Attribute: 'CONTRL' shorter than 128 Attribute: 'ALTER' shorter than 64 Entity: 'SYM.PWD.LEN.DEC' - Minimum required passphrase length at read (decryption) Attribute: 'NONE' longer or equal to 20 Attribute: 'READ' shorter than 20 Attribute: 'UPDATE' shorter than 16 Attribute: 'CONTRL' shorter than 12 Attribute: 'ALTER' shorter than 8 Entity: 'SYM.PWD.LEN.ENC' - Minimum required passphrase length at write (encryption) Attribute: 'NONE' longer or equal to 20 Attribute: 'READ' shorter than 20 Attribute: 'UPDATE' shorter than 16 Attribute: 'CONTRL' shorter than 12 Attribute: 'ALTER' shorter than 8 Entity: 'EDC.PARM.FILE.ALLOWED' - Side file is not allowed Attribute: 'NONE' No print required Attribute: 'UPDATE' Allow creation of side file at write (encryption) Attribute: 'ALTER' Allow write of side file at read (decryption) Entity: 'EDC.KEY.PRINT.ALLOWED' - Print of clear key values to side file is not allowed Attribute: 'NONE' Prevent printing of clear key values Attribute: 'UPDATE' Allow print only if it is random (data lost if not) Attribute: 'ALTER' Allow print at all (important for test environments) Entity: 'EDC.KEY.INVERSE.ALLOWED' - Print of clear key values for inverse command is not allowed Attribute: 'NONE' Prevent printing of clear key values Attribute: 'UPDATE' Allow print only if it is random (limitation nor really useful) Attribute: 'ALTER' Allow print at all (required to use inverse commands) Entity: 'EDC.NO.HEADER.ALLOWED' - Write of a salted passphrase encrypted file without header is not allowed Attribute: 'NONE' Enforce header Attribute: 'UPDATE' Allow no header Entity: 'EDC.NO.SALT.ALLOWED' - Support passphrase encrypted files without salt is not allowed Attribute: 'NONE' Enforce salt Attribute: 'READ' Allow no salt at read Attribute: 'UPDATE' Allow no salt at write Attribute: 'CONTRL' Allow no salt at read and write Entity: 'EDC.STATIC.KEY.ALLOWED' - Static keys are not allowed at write Attribute: 'NONE' Enforce only random keys at write Attribute: 'UPDATE' Allow static keys at write for labels Attribute: 'CONTROL' Allow static keys at write for passphrases Attribute: 'ALTER' Allow static keys at write for clear key values Entity: 'EDC.STATIC.IV.ALLOWED' - Static IV are not allowed at write Attribute: 'NONE' Enforce only random IVs at write Attribute: 'UPDATE' Allow static IV's at write GROUP: 'CLPAR.' - Command line parser Entities: Path to this parameter Attribute: 'NONE' not allowed Attribute: 'READ' can be used GROUP: 'CMD.PRE.READ.FILE.' - Pre-processing before read per file Entities: Command string to be executed Attribute: 'NONE' not allowed Attribute: 'CONTROL' can be done GROUP: 'CMD.POST.READ.FILE.' - Post-processing after read per file Entities: Command string to be executed Attribute: 'NONE' not allowed Attribute: 'CONTROL' can be done GROUP: 'CMD.PRE.WRITE.FILE.' - Pre-processing before write per file Entities: Command string to be executed Attribute: 'NONE' not allowed Attribute: 'CONTROL' can be done GROUP: 'CMD.POST.WRITE.FILE.' - Post-processing after write per file Entities: Command string to be executed Attribute: 'NONE' not allowed Attribute: 'CONTROL' can be done GROUP: 'CMD.PRE.READ.GLOBAL.' - Global pre-processing before read Entities: Command string to be executed Attribute: 'NONE' not allowed Attribute: 'CONTROL' can be done GROUP: 'CMD.POST.READ.GLOBAL.' - Global post-processing after read Entities: Command string to be executed Attribute: 'NONE' not allowed Attribute: 'CONTROL' can be done GROUP: 'CMD.PRE.WRITE.GLOBAL.' - Global pre-processing before write Entities: Command string to be executed Attribute: 'NONE' not allowed Attribute: 'CONTROL' can be done GROUP: 'CMD.POST.WRITE.GLOBAL.' - Global post-processing after write Entities: Command string to be executed Attribute: 'NONE' not allowed Attribute: 'CONTROL' can be done GROUP: 'FIOURL.' - File I/O control Entities: Complete file I/O URLs (connection, file name, member name) Attribute: 'READ' at read Attribute: 'UPDATE' at write GROUP: 'SSHCONN.' - SSH connection string (after parsing config files and params) Entities: Connection string in the form user@host:port Attribute: 'NONE' not allowed Attribute: 'CONTROL' can be used GROUP: 'SSHUSER.' - SSH user Entities: SSH effective user id (after parsing config files and params) Attribute: 'NONE' not allowed Attribute: 'CONTROL' can be used GROUP: 'SSHHOST.' - SSH host Entities: Effective IP or hostname remote SSH host (after parsing config files and params) Attribute: 'NONE' not allowed Attribute: 'CONTROL' can be used GROUP: 'SSHPORT.' - SSH port Entities: Port number of SSH host (after parsing config files and params) Attribute: 'NONE' not allowed Attribute: 'CONTROL' can be used GROUP: 'FAVELIB.' - FAVE library Entities: Library name name Attribute: 'NONE' not usable Attribute: 'READ' can be used GROUP: 'FAVEFUC.' - FAVE Function Entities: Function name used Attribute: 'NONE' not usable Attribute: 'READ' can be used GROUP: 'FAVEPAR.' - FAVE Parameter Entities: Parameter string used Attribute: 'NONE' not usable Attribute: 'READ' can be used GROUP: 'FAVEIPH.' - FAVE IP host Entities: IP address of AV daemon Attribute: 'NONE' not usable Attribute: 'ALTER' can be used GROUP: 'FAVEIPS.' - FAVE IP service/port Entities: IP service/port of AV daemon Attribute: 'NONE' not usable Attribute: 'ALTER' can be used GROUP: 'FCPELIB.' - FCPE library Entities: Library name name Attribute: 'NONE' not usable Attribute: 'READ' can be used GROUP: 'FCPEFUC.' - FCPE Function Entities: Function name used Attribute: 'NONE' not usable Attribute: 'READ' can be used GROUP: 'FCPEPAR.' - FCPE Parameter Entities: Parameter string used Attribute: 'NONE' not usable Attribute: 'READ' can be used GROUP: 'FKMELIB.' - FKME library Entities: Library name name Attribute: 'NONE' not usable Attribute: 'READ' can be used GROUP: 'FKMEFUC.' - FKME Function Entities: Function name used Attribute: 'NONE' not usable Attribute: 'READ' can be used GROUP: 'FKMEPAR.' - FKME Parameter Entities: Parameter string used Attribute: 'NONE' not usable Attribute: 'READ' can be used GROUP: 'FLAM4.EXK10' - User access routine at compression to original records Entities: Load module or DLL name Attribute: 'NONE' not usable Attribute: 'READ' can be used GROUP: 'FLAM4.EXK20' - User access routine at compression to FLAMFILE records Entities: Load module or DLL name Attribute: 'NONE' not usable Attribute: 'READ' can be used GROUP: 'FLAM4.EXD20' - User access routine at decompression to FLAMFILE records Entities: Load module or DLL name Attribute: 'NONE' not usable Attribute: 'READ' can be used GROUP: 'FLAM4.EXD10' - User access routine at decompression to original records Entities: Load module or DLL name Attribute: 'NONE' not usable Attribute: 'READ' can be used GROUP: 'FLAM4.DEVICE' - Controls the user I/O extension Entities: 'USER' Attribute: 'NONE' not usable Attribute: 'READ' can be used GROUP: 'PGPKEYM.' - PGP key management Entities: User ID to be managed Attribute: 'NONE' nothing allowed Attribute: 'READ' can be exported Attribute: 'UPDATE' can be imported Attribute: 'CONTROL' can be generated Attribute: 'ALTER' can be deleted GROUP: 'PGPUID.EXCH.' - Operational PGP user for key exchange Entities: User ID mainly at write Attribute: 'NONE' not allowed Attribute: 'READ' allowed at read Attribute: 'UPDATE' allowed at write GROUP: 'PGPUID.SIGN.' - Operational PGP user for signing Entities: User ID mainly at write Attribute: 'NONE' not allowed Attribute: 'READ' allowed at read Attribute: 'UPDATE' allowed at write GROUP: 'PGPKID.EXCH.' - Operational PGP key ID for key exchange Entities: Key ID at read and write Attribute: 'NONE' not allowed Attribute: 'READ' allowed at read Attribute: 'UPDATE' allowed at write GROUP: 'PGPKID.SIGN.' - Operational PGP key ID for signing Entities: Key ID at read and write Attribute: 'NONE' not allowed Attribute: 'READ' allowed at read Attribute: 'UPDATE' allowed at write GROUP: 'EDC.METHOD.' - Encryption/decryption methods Entities: CLEAR, OLDSSL, PBKDF2, LABEL Attribute: 'NONE' not allowed Attribute: 'READ' allowed at read Attribute: 'UPDATE' allowed at write GROUP: 'EDC.FORMAT.' - Encryption/decryption file formats * NOHDR if no header read or written * Write with no salt will be NOHDR Entities: NOHDR, OPENSSL, FLAM Attribute: 'NONE' not allowed Attribute: 'READ' allowed at read Attribute: 'UPDATE' allowed at write GROUP: 'EDC.ALGO.' - Encryption/decryption algorithms Entities: TDES, AES, CAST5, IDEA, BLOWFISH, CAMELLIA Attribute: 'NONE' not allowed Attribute: 'READ' allowed at read Attribute: 'UPDATE' allowed at write GROUP: 'EDC.MODE.' - Encryption/decryption modes Entities: EDC, CBC, OFB, CFB, CTR, GCM Attribute: 'NONE' not allowed Attribute: 'READ' allowed at read Attribute: 'UPDATE' allowed at write GROUP: 'EDC.PADDING.' - Adding/stripping of padding bytes (only for ECB and CBC mode) Entities: NOPAD, PKCS Attribute: 'NONE' not allowed Attribute: 'READ' allowed at read Attribute: 'UPDATE' allowed at write GROUP: 'EDC.KDF.' - Key derivation function for password-based encryption/decryption Entities: OLDSSL, PBKDF2, SCRYPT Attribute: 'NONE' not allowed Attribute: 'READ' allowed at read Attribute: 'UPDATE' allowed at write GROUP: 'EDC.HASH.' - Hash functions for key derivation Entities: MD5, SHA1, SHA224, SHA256, SHA384, SHA512, SHA3-224, SHA3-256, SHA3-384, SHA3-512 Attribute: 'NONE' not allowed Attribute: 'READ' allowed at read Attribute: 'UPDATE' allowed at write GROUP: 'EDC.ITER.' - Iteration count for key derivation Entities: number of iterations (1, ..., 10000, ...) Attribute: 'NONE' not allowed Attribute: 'READ' allowed at read Attribute: 'UPDATE' allowed at write GROUP: 'EDC.KLEN.' - Key length selection Entities: KL064, KL128, KL192, KL256 Attribute: 'NONE' not allowed Attribute: 'READ' allowed at read Attribute: 'UPDATE' allowed at write GROUP: 'EDC.OFFSET.' - Encryption/decryption offset (not encrypted part at the beginning of file) Entities: limit offset to the right values (0, ..., 32, ..., 100, ...) Attribute: 'NONE' not allowed Attribute: 'READ' allowed at read Attribute: 'UPDATE' allowed at write 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 ('HLQ.PO(HUGO)' is resource 'HLQ.PO_HUGO_'). If any other checks are required, please open an issue on www.flam.de. Each requested resource will be protected. ISPF configuration ~~~~~~~~~~~~~~~~~~ To use the ISPF interface for FLAM components, you can find the setup instructions in the dataset below: ------------------------------------------------------------------------ HLQ.FLAMV5nm.CLIST($ABOUT) ------------------------------------------------------------------------ There are 5 new line commands for ISPF 3.4: ------------------------------------------------------------------------ FLINFO - Displays detected file information FLVIEW - Displays the clear content of a file FLTEXT - Like FLVIEW, but binary data is displayed as hex dump FLVEDIT - Editing of encoded, encrypted, compressed XML or text files FLDEL - Delete each kind of file (incl. VSAM) ------------------------------------------------------------------------ FLINFO provides the normal file attributes (organization, record format, record length, block size), the file format (GZIP, XML, text, ...), the character set (CCSID), the delimiter (CRLF, LF, NL, ...) and if appropriate the member list of concatenated GZIP, BZIP2, XZ or FLAM files. FLVIEW can be used, for example, to display the content of a GZIP file containing XML in UTF-8 as well-formatted records in EBCDIC or to display the content of FLAMFILEs, VSAM datasets or binary transfered files from other platforms (text file in ASCII with 0D0A as delimiter). FLTEXT works like FLVIEW, but binary data is displayed as text dump in a table with offsets, hex values and the corresponding printable characters. FLVEDIT works like FLVIEW, but additionally allow to EDIT for example a UTF-8 XML file inside GZIP file using the normal ISPF editor. FLAM converts the data to EBCDIC records which can handled by ISPF. After editing, the changed EBCDIC records are converted back to UTF-8 with delimiter and GZIP compression. To better support larger files there are few more versions of FLVEDIT. ------------------------------------------------------------------------ FLVEDIT1- Same as FLVEDIT but with limited record length to 1024 FLVEDIT2- Same as FLVEDIT but with limited record length to 2048 FLVEDIT4- Same as FLVEDIT but with limited record length to 4096 FLVEDIT8- Same as FLVEDIT but with limited record length to 8172 ------------------------------------------------------------------------ These variants have a limited record length and the record mode result in an error (no cut) if the record is longer than the record length. FLAMSTC ------- To use the subsystems, LE-less interfaces, or zIIP support, FLAMSTC must be active. To encapsulate the utilizing applications from authorization, only FLAM.LOAD must be made APF-authorized. You do so by specifying a PARMLIB concatenation member PROGxx, e.g. PROGLI with APF ADD DSNAME(FLAM.LOAD) VOLUME(MYVOL1) <== if not SMS-managed or APF ADD DSNAME(FLAM.LOAD) SMS <== if SMS-managed Activate with "SET PROG=LI". You are now ready to MVS-START the STC. Following is a sample started job to start FLAMSTC: //FLAMSTC JOB 'FLAMSTC',CLASS=D,JESLOG=(SPIN,'18:00'), // MSGLEVEL=(1,1),MSGCLASS=X //********************************************************************* //* * //* This is the started task for FLAM-/FLUC-subsystem, * //* FLAM-server, zIIP, LE-less, SMF, IDCAMS, XMIT and * //* 64 bit functions * //* * //* The jobname must be unique in the system, it is used * //* as the name of the started task. * //* Please choose latch timeout and number of subtasks * //* to suit your needs. The subtasks are required for the * //* FLUC subsystem and the number of subtask limits the * //* amount of applications which can use the subsystem in * //* parallel. * //* * //* Commands from the console: * //* * //* S FLAMSTC,REUSASID=YES starts the started task * //* and FLAM-/FLUC-subsystems * //* P FLAMSTC stops the started task * //* and FLAM-/FLUC-subsystems * //* * //* F FLAMSTC,LIST,VER displays actual version * //* F FLAMSTC,LIST,TASKS displays actual list of subtasks * //* * //* for special situations: * //* F FLAMSTC,REMOVE,TASK,nn removes subtask no. nn * //* * //* for subsystem management * //* F FLAMSTC,FLAM,STOP stops FLAM subsystem * //* F FLAMSTC,FLAM,START starts FLAM subsystem * //* F FLAMSTC,FLUC,STOP stops FLUC subsystem * //* F FLAMSTC,FLUC,START starts FLUC subsystem * //* * //* in error situations * //* F FLAMSTC,DEBUG,1 log at open and close * //* F FLAMSTC,DEBUG,2 log and wto at open and close * //* F FLAMSTC,DEBUG,3 log and wto also at run * //* F FLAMSTC,DEBUG,0 deactivate debug logging * //* * //********************************************************************* // SET G=FLZGRP,T=1,N=10,S=00,SU=FLUC,SA=FLAM //*-------------------------------------------------------------------- //* +------------------> FLZ XCF GROUP //* | +---------------> LATCH TIMEOUT SEC //* | | +------------> NUM FLZSRV TASKS //* | | | +---------> N/T-NAME-SUFFIX //* | | | | +------> FLUC SUBSYSTEM //* | | | | | +--> FLAM SUBSYSTEM //* | | | | | | //FLAMSTC EXEC PGM=FLZSTC,PARM='&G,&T,&N,&S,&SU,&SA' //STEPLIB DD DISP=SHR,DSN=FLAM.AUTH.LOAD //SYSOUT DD SYSOUT=* //SYSPRINT DD SYSOUT=* //STDENV DD * /* FLAMSTC takes up to six start parameters: - an 8-byte XCF group name (future use), - a latch set timeout, the least possible value, '1' is recommended, - the number of FLUC service tasks, 0..99, - a 2-digit name/token suffix (see below) - the 4-character FLUC subsystem name (optional, dependent on licence) - the 4-character FLAM subsystem name (optional, dependent on licence). FLAMSTC should be STARTed with REUSASID=YES to avoid latent binds of clients utilizing FLAMSTC's cross memory services, it can be STOPped ordinarily, and it supports a set of MODIFY verbs to display and set additional processing conditions. See the manual for details. The sample started job uses JCL symbols for the start parameters allowing you to override defaults at START, e.g. S FLAMSTC,REUSASID=YES,N=20,S=FK,SU=FKUC,SA=FKAM Since version 5.1.23 of FLAM you can run more than one started task in parallel by setting a different token suffix in the startup JCL. To define per JOB step which FLAMSTC should be used by clients the JCL variable &FLTOKID must be set and exported to define the 2-character identifier. This could be used for example, to run a separate version of FLAM from another authorized LOAD in parallel. The default for &FLTOKID is '00' (zoned zeros). The old FLSSTSK (FLAM4 subsystem) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If you still use the old FLSSTSK from FLAMv4 to establish only the old FLAM subsystem, in certain error cases the SSVT are still active and a restart of FLAMSUB failed, with the error message below. FLM0502I * SUBSYSTEM FLAM ALREADY INITIALIZED In this case the command below deletes the remaining rest of the old FLAM subsystem: SETSSI DELETE,SUBNAME=FLAM,FORCE After this an restart should work. We strongly recommend the use of the FLZSTC. The old FLSSTSK is no longer supported but is still being delivered so that existing customers have a smooth transition and are not forced to change. Subsystems ~~~~~~~~~~ The subsystems can be used to convert, compress, encrypt and transfer any kind of dataset transparent to the application by allocating the FLAM or FLUC subsystem through a DD statement or SVC 99. To use them, the corresponding feature code must be available and the the pertaining start parameters for FLAMSTC must be specified. The subsystems are then built dynamically. The use of the subsystems is described in the FLCL and FLAM4 user manuals. zIIP Support ~~~~~~~~~~~~ Since version 5.1.20 FLAM supports zIIPs. To use them, the corresponding feature code must be available and FLAMSTC must be up and running. If these prerequisites are met, the CX8 and VR8 loads are executed on zIIP if a free zIIP is available. More zIIP offloading is planned for future releases (e.g. ADC, character conversion, table formatting, ...). Performance Recommendation -------------------------- FLCL, FLAMSTC and the subsystems do a lot of STEPLIB I/O due to the fact that FLAM utility modules are reloaded at the time of OPEN. We therefore strongly recommend that you put the FLAM.LOAD(s) under LLA/VLF control. First, check with your system programmer that VLF class CSVLLA is active, see your PARMLIB concatenation member COFVLFxx, and that the IBM Health Check (IBMVLF,VLF_MAXVIRT) is successful. Then, second, add the FLAM.LOAD(s) to an existing or newly to build CSVLLAxx PARMLIB concatenation member, e.g. CSVLLALA (LA = Limes Add) LIBRARIES( . . . . SMPE.FLAM.T1.LOAD SMPE.FLAM.T2.LOAD . . . . ) FREEZE( . . . . SMPE.FLAM.T1.LOAD SMPE.FLAM.T2.LOAD . . . . ) Activate with "F LLA,UPDATE=LA". Of course, this implies that the FLAM.LOAD(s) are now allocated to LLA. To allow FLAM maintenance this allocation must be interrupted. To do so, create a second CSVLLAxx PARMLIB concatenation member, e.g. CSVLLALR (LR = Limes Remove) REMOVE( . . . . SMPE.FLAM.T1.LOAD SMPE.FLAM.T2.LOAD . . . . ) and activate again using "F LLA,UPDATE=LR" this time. Installation verification process --------------------------------- To verify the installation, please check if the version and license is correctly installed. ------------------------------------------------------------------------ //* RETURN VERSION INFORMATION //VERSION EXEC PGM=FLCL, PARM='VERSION' //STEPLIB DD DSN=HLQ.FLAMV5nm.LOAD,DISP=SHR //SYSPRINT DD SYSOUT=* //SYSOUT DD SYSOUT=* /* ------------------------------------------------------------------------ To verify the version and whether all components are installed correctly, the first line containing "FLCL VERSION" must match your installed version. For example: ------------------------------------------------------------------------ --| FL5-FLCL VERSION: 5.1.6.9857 ------------------------------------------------------------------------ The build number "9857" must be identical for each component in the list. Each component has its own version numbering, but the build numbers must be identical. If there are different build numbers, not all components have been replaced and the installation is inconsistent. Before you use FLAM in a commercial or productive environment, you must verify if the corresponding license is installed. ------------------------------------------------------------------------ //* RETURN LICENSE INFORMATION //VERSION EXEC PGM=FLCL, PARM='LICENSE' //STEPLIB DD DSN=HLQ.FLAMV5nm.LOAD,DISP=SHR //SYSPRINT DD SYSOUT=* //SYSOUT DD SYSOUT=* /* ------------------------------------------------------------------------ Ensure that you don't work with the DEMO license. The license ID must contain the right customer name and contract number. ICSF and CPACF support ---------------------- To use CPACF for encryption and hashing with FLAM, it must be activated. Contact your IBM representive for more information. CPACF is available on all real Z systems, without additional cost, but it must be enabled because of export regulations. If CPACF is available, FLAM uses it automatically. We strongly recommend to enable CPACF if cryptographic operations (PGP, SSH, ...) are used with FLAM. The ICSF started task (CSF) must be available to produce good random numbers, which is a prerequisite for strong cryptography (e.g for SSH connections). Besides standard encryption algorithms, FLAM uses the ICSF as hardware security module via the FKME or FKM5 service provider interfaces. This can be used for strong data protection and key management. Configure usage reporting ------------------------- Since FLAM 5.1.13, usage reporting is available. The CPU usage for each component is measured and logged together with the eligible offload time (SRB), the used offload time (SRB) and the number of bytes processed. The usage reporting can be used to determine cost savings using ZEDC, ZIIP, CPACF or other co-processors with FLAM. This feature was implemented for all customers using our programming interfaces to determine the CPU usage for each FLAM component used within an application. To activate the usage reporting, you must define the system variables (in SYS1.PARMLIB(IEASYM00)) below and setup a corresponding log stream (LDS) for your SYSPLEX (JOBLIB(CREALOGS)) or LPAR (JOBLIB(CREALOG)). The started task LOGR must be running and the required RACF settings must be configured: * &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 You must specify at least the first qualifier. You can additionally specify a second and a third qualifier. FLAM uses these qualifiers to build the log stream name. ------------------------------------------------------------------------ FLMUSGLOG='&FLOGQL1[.&FLOGQL2[.&FLOGQL3]]' ------------------------------------------------------------------------ If connecting to the log stream failed, then FLAM will still work. Please look for log messages of RACF or the LOGR system if no usage logging is done. For the log stream name (FLAM.USAGE) in the provided sample jobs (CREALOG(S)) the definitions below are required in the PARMLIB member IEASYM00 to activate the usage logging: ------------------------------------------------------------------------ SYMDEF(&FLOGQL1='FLAM') SYMDEF(&FLOGQL2='USAGE') ------------------------------------------------------------------------ With the program SCFLMUSG (LOAD) using the sample JOB SCFLMUSG (JOBLIB) you can generate reports using the LOGR subsystem. ------------------------------------------------------------------------ //SCFLMUSG EXEC PGM=SCFLMUSG,REGION=0M, // PARM='DURATION=(8,HOURS),VIEW=ACTIVE' //STEPLIB DD DSN=FLAM.LOAD,DISP=SHR //SYSOUT DD SYSOUT=* //SYSPRINT DD SYSOUT=* ------------------------------------------------------------------------ This sample program (SRCLIBC) uses the FLAM byte interface and takes optional parameters containing the SUBSYS-options of SUBSYS-LOGR: * [FROM={({[yyyy/ddd][,hh:mm[:ss]]}) | OLDEST}] * [TO={({[yyyy/ddd][,hh:mm[:ss]]}) | YOUNGEST}] * [,DURATION=(nnnn,HOURS)] * [,VIEW={ACTIVE|ALL|INACTIVE}] * [,GMT|LOCAL]. It calculates a summary of all corresponding usage log entries per component and prints the summary to STDOUT (DD:SYSPRINT). All other messages are printed to STDERR (DD:SYSOUT). Since FLAM 5.1.14 you can use the more powerful FLCL INFO command with GET.USAGE() documented in the FLCL user manual. Since 5.1.15 PEAKHOUR analysis is supported with the info command. Since 5.1.16 you can determine the usage per job name on z/OS. See JOBLIB(FLUSAGE) for a sample producing a usage report for the last quarter. The MATSEG (deprecated), FL4CX7/CX8/VR8/ADC/NDC and all PGPxxx, CNVxx and FMTxxx efforts can be implemented as ZIIP-SRB routine (offload time) on request. If the LOGR started task and the log stream are not available or RACF definitions are missing, no usage logging is done. Since FLAM 5.1.14 usage logging is implemented for all platforms using the SYSLOG. This can be activated by defining the environment variable below: ------------------------------------------------------------------------ FL_USAGE_SYSLOG_IDENT=ident ------------------------------------------------------------------------ The SYSLOG and the log stream can be used individually or in combination. If you use FLAM only on z/OS or you need usage reporting for FLAM4, we recommend to use the log stream. If you use FLAM5 on different platforms, then the SYSLOG daemons can be used to collect the FLAM usage data for all your different platforms. With the corresponding system variable below, you can also define the SYSLOG identifier and activate SYSLOG usage reporting. ------------------------------------------------------------------------ SYMDEF(&FLOGIDT='ident') ------------------------------------------------------------------------ The SYSLOG identifier is limited to 8 characters. FLAM4 components do not support usage reporting via SYSLOG (LE less). Only the usage data of FLAM5 components can be written to the SYSLOG. However, the FLAM4 efforts are accounted for in the FIO.FL4 component. The matrix segment serialization and de-serialization (MATSEG (deprecated), FL4CX7/CX8/VR8/ ADC/NDC) are not visible in the SYSLOG report. If your license requires usage logging, then the use of FLAM will fail if logging is not possible (currently there is no access control point available). Next steps after installation ----------------------------- To use the FLCL utility, please refer to FLCLBOOK document in HTML, PDF or TEXT form. The FLCL batch utility also contains the complete syntax, help and manual pages. You can use the TSO CALLs below: ------------------------------------------------------------------------ CALL FLAM.LOAD(FLCL) 'SYNTAX INFO ALL' CALL FLAM.LOAD(FLCL) 'HELP CONV.READ DEPTH2' CALL FLAM.LOAD(FLCL) 'HELP CONV.READ MAN' ------------------------------------------------------------------------ If you have installed and added the CLIST to your ISPFPROC, then the interactive help can simply be used on each IPSF command line like the example below: ------------------------------------------------------------------------ FLMAN INFO * shows the manual page for the INFO command FLHLP CONV.READ * shows help for READ overlay of CONV command FLSYN CONV.WRITE.REC * shows syntax for record object at write FLDOC XCNV * provides user manual of the XCNV command FLGRA * provides grammar for FLCL FLLEX * provides regular expressions for FLCL FLLIC * provides the current license text FLABO * shows about information FLVSN * shows version information ------------------------------------------------------------------------ The FLUC subprogram interface is described in FLUCUP (DLL) or FLUCUPLB (load module) as PDF or ZIP file containing generated HTML. The FLUC subprogram can be used to integrate the FLUC commands (INFO/CONV/...) of FLCL into a program. The FLUC record interface is described in FLCRECLB (only load modules) as PDF or ZIP file containing generated HTML. With the record interface for original data, you can read each kind of file and get the data formatted as records. With this access method, you can, for example, read a member of a concatenated GZIP file from an FB80 XMIT PDS which is encoded in UTF-16LE and delimited with CRLF. Each text record will be returned with length and data in EBCDIC (IBM-1141). The FLUC byte interface is described in FLCBYT (only DLL) as PDF or ZIP file containing generated HTML. It provides byte and record oriented sequential read and write access to record files (PS/PO/VSAM), USS files, binary transferred text files from other platforms, compressed files, FLAM4FILEs, XML files or other kinds of datasets and formats. FLCBYTBF is the corresponding C\++ stream buffer class library. The stream buffer instances can be passed to istream or ostream objects in order to use the byte interface like regular C++ streams. Additional Java stream classes are also provided with the USS installation package. The documentation for the JAVA class library and stream classes can be found in FLAM.DOCZIP(FLCBYTJS). The FLUC ICONV interface is described in FLCICV (only DLL) as PDF or ZIP file containing generated HTML. It provides an ICONV-like interface for character conversion with all features (including subset support, transliteration and reporting) of the FLAM character conversion module. You can find some source samples for all APIs in SRCLIB (COBOL, ASSEMBLER, PL1) or SCRLIBC (C/C++). There is a job SBUILD in the JOBLIB library for compiling and linking the sample programs. All sample programs are already included in the FLAM load library. Sample jobs that use it are also provided in the JOBLIB. The FLICONV sample program implements the functionality of the ICONV utility known from Linux with all features of our character conversion module. The samples SCFCULST/REM can be used to find and remove datasets. To use the FLAM4 utility and/or record interface, you should read the book FLAMZOSx in DOCPDF. Binary download the PDF file to a workstation to read it. Subsystems FLAM and FLUC are described in own manuals. Copying FLAM.JOBLIB(FLAMSTC) to your system.PROCLIB allows starting the FLAM-server (S FLAMSTC,REUSASID=YES from the console) including the starting of FLAM and FLUC subsystem. The old started task FLAM to start the FLAM-subsystem only is still provided but not used any more. Please use FLAMSTC instead.