_______ _ _ _ | _____| | | /\ | \ / | | | | | / \ | \ / | | | | | / /\ \ | \ / / | | |____ | | / / \ \ | |\ \ / /| | | ____| | | / / \ \ | | \ \/ / | | | | | | / /______\ \ | | \ / | | | | | | / /________\ \ | | \/ | | | | | |_____ / / \ \ | | | | |_| |_______| /_/ \_\ |_| |_| 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 ------------------------------------------------------------------------ Minimum operating system: z/OSv2r2 (earlier versions on request) Minimum architecture: 2827/8-xxx (IBM z12, lower on request) Optimized for architecture: 3906/7-xxx (IBM z14) ------------------------------------------------------------------------ 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. 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 will 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 to make 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 CHARTERS ! $ # @ [ \ ] ^ ` { | } ~ 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 ------------------------------------------------------------------------ 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 does 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. 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') ------------------------------------------------------------------------ This will result in the environment variables below: ------------------------------------------------------------------------ LANG=de_DE.IBM1141 ENVID=T FL_ZEDC_SUPPORT=OFF ------------------------------------------------------------------------ These vales 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). 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 an 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: '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: '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 finger print (KEYID) at import Attribute: 'NONE' enforced the policy (complete finger print (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.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 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 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 then the record length. FLAMSTC ------- To use the subsystems, LE-less interfaces or zIIP support, FLAMSTC must be running. To encapsulate the using applications from authorization, the FLAM.LOAD must be authorized and in the link list concatenation. Then you can start the FLAMSTC. A sample procedure with all required information can be found in FLAM.JOBLIB(FLAMSTC). The FLAM started task (FLAMSTC) are required to run our I/O subsystems, the zIIP-Support, the SMF-Logging, the FLUC LE-less interface, 64 bit support and other solutions where another address space or authorization are required. Below you can find more dedicated chapters about this different solutions. Since version 5.1.23 of FLAM you can run more than one started task in parallel by setting different token IDs in the startup script. To define per JOB step which FLAMSTC should be used the JCL variable &FLTOKID must be defined to the corresponding 2 digits and exported. This could be used for example to run a new version of FLAM other a new authorized LOAD in parallel to the old version in the link list concatenation. If no JCL variable (&FLTOKID) defined, then '00' will be used by default. 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 SCV99. To set the FLAM or FLUC subsystem up, the corresponding feature code must be available, the FLAM.LOAD must be authorized in the LINKLIST and the FLAMSTC must be running. For more information read this chapter. The use of the subsystems is described in the FLCL and FLAM4 user manuals. I.) LINKLST and authorization The programs of the FLAMSTC and subsystems must be stored in an APF-authorized load library. This library must be linked to the system library SYS1.LINKLIB. The subsystem also reloads modules belonging to the FLAM utility at the time of the OPEN. The library of the FLAM and FLUC utility must therefore be APF-authorized as well. We recommend simply to authorize the complete FLAM.LOAD The following entries are necessary in the SYS1.PARMLIB library for this purpose (see also z/OS Initialization and Tuning Reference). xx is the serial number of your active system generation. There is more than one method, to link a LOAD library to LINKLST. a) To generate a link to the system library, insert the following line in the member LNKLSTxx: SYS1.FLAMLIB, Libraries which are concatenated in this way are normally APF-authorized as default. If not, they can be authorized by inserting the following line: SYS1.FLAMLIB volume, in the member IEAAPFxx, where volume is the name of the disk on which the SYS1.FLAMLIB library is stored (if this entry is the last in the member, the comma must be omitted). b) Insert some lines into the PROGxx member: LINKLST ADD NAME(LINKLSTxx) DSNAME(flamlib) VOLUME(volume) and APF ADD DSNAME(flamlib) VOLUME(volume) Many variants exist for this member, this is only one example. II.) Subsystem Start A started task to activate the FLAM and FLUC subsystem is supplied in FLAM.JOBLIB(FLAMSTC) containing detailed information. You must copy it to your STC library. The operator starts the FLAM-STC entering S FLAMSTC from the console. If you insert the line COM='S FLAMSTC' into the member COMMNDxx, the FLAM-STC starts automatically without an operator interaction during the next IPL. You can stop the FLAM-STC with P FLAMSTC. Stopping the started task, changing the FLAM-modules in the library (don't forget the LLA REFRESH!) and starting the subsystem again enables an easy way to update the subsystems. zIIP Support ~~~~~~~~~~~~ Since version 5.1.20 FLAM supports zIIP. To use it, the corresponding feature code must be available, the FLAM.LOAD must be authorized in the LINKLIST and the FLAMSTC must be running. If all 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, ...). 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: ------------------------------------------------------------------------ 00 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.