Appendix C: External Library Management Systems

This chapter describes the Mainframe Access support for external library management systems and change management systems.

Introduction

Mainframe Access provides seamless access to objects housed in repositories controlled by the following external management systems:

Contact the appropriate vendor for further information about these products.

Panvalet

Overview

Panvalet is a direct access library system marketed by Computer Associates. It's primary use is as a source control system for software development. All source members are managed as fixed length records. The default size is the historical card image of 80 bytes. Panvalet may be used to manage any fixed-length data up to 4096 characters in length.

Panvalet provides licensed users with programmable access to their repository services via the PAM API. This is a read-only interface which permits multiple concurrent access for Mainframe Access threads to browse source members residing in Panvalet repositories. During Server initialization, Mainframe Access will attempt to load this interface into memory. If this API interface is available through the standard search order (STEPLIB, JOBLIB, or SYS1.LINKLIB at the customer site) then Panvalet services will be offered. Startup initialization messages will indicate if Panvalet is available.

It is a customer responsibility to provide a suitable STEPLIB concatenation which will allow selection of the desired release and version of the Panvalet components. At most sites, PANVALET is installed as an MVS Subsystem. Therefore the API will already be available within SYS1.LINKLIB. No override would be necessary unless a new version is being tested.

     //STEPLIB DD DSN=your.MFA30.LOADLIB,DISP=SHR
     //        DD DSN=your.MFA30.SASC.LINKLIB,DISP=SHR
     //        DD DSN=CAI.PANV144.CAILIB,DISP=SHR
 

The following messages are typical of the information written to the SYSLOG during Mainframe Access startup:

       MFM0063I: MFA Direct is active
       MFM0064I: MFA Direct number of processing tasks is 5
       MFMDS051I CA/LIBrarian Ready
       MFMDS052I CA/PanValet Ready
       MFMDS053I CA/ENDEVOR API 39 Ready
       MFMDS055I MCG/RPC feature active
       MFMDS001I DSS Server Ready
       MFM0001I: Mainframe Access V3.01 (bt2) is active
 

For source additions or updates under Panvalet, Mainframe Access must invoke the standard Panvalet batch utility PAN#1. Access to this utility will be serialized, since Panvalet does not support multiple, concurrent access to this service. In some cases, a customer may have renamed the Batch Update utility PAN#1. If this is the case, the new name at this site must be defined to Mainframe Access as a parameter override.

References

• PANVALET System Management Guide
• PANVALET Messages Guide
• PANVALET Installation Guide
• PANVALET User Guide
• PANVALET Extended Features Guide

Panvalet Suffix Table

Panvalet recognizes the following programming language or object types:

• BAL
• COBOL
• DATA
• FORTRAN
• JCL
• PL/1
• RPG

Specification of such a native language type allows Panvalet to format the source files, and automatically add or remove the sequence numbers in the appropriate position for that language. In order to automate this language selection process, Mainframe Access has introduced a Panvalet Suffix Table to specify the language type based upon the file suffix as used on the workstation. In addition, the Suffix Table also specifies the default options to be specified on the ADD command of the PAN#1 batch update utility.

The above table describes the default Suffix Table as provided within Mainframe Access. If no changes are desired, no further customization is necessary.

Suffix Table Override

The built-in Panvalet Suffix Table may be replaced by including a special DD card in the Mainframe Access task JCL as follows:

     //PANSUFX  DD  DSN=your.MFA30.CNTL(PANVALET),DISP=SHR

During initialization, this text file will be analyzed and a new Suffix Table will be created dynamically. The first entry defines a default language type to be used if no match is found in the table. The following extract illustrates the free-form format of the text file:

      *
      * MFA PANVALET CONFIGURATION CONVERSION TOOL
      *      AS ON 06/07/2003 AT 12:40
      *
      * SUFFIX TYPE     ++ADD OPTIONS
      ******** ******** ***********************
      *
      DEFAULT  DATA     LIST,NOFORMAT
      ASM      BAL      LIST,NOFORMAT
      ASSEM    BAL      LIST,NOFORMAT
      BAL      BAL      LIST,NOFORMAT
      BMS      BAL      LIST,NOFORMAT
      DBD      BAL      LIST,NOFORMAT
      MAC      BAL      LIST,NOFORMAT
      MFS      BAL      LIST,NOFORMAT
      MLC      BAL      LIST,NOFORMAT
      PSB      BAL      LIST,NOFORMAT
      CBL      COBOL    LIST,NOFORMAT
      COB      COBOL    LIST,NOFORMAT
      COBOL    COBOL    LIST,NOFORMAT
      COP      COBOL    LIST,NOFORMAT
      COPY     COBOL    LIST,NOFORMAT
      CPY      COBOL    LIST,NOFORMAT
      JCL      JCL      LIST,NOFORMAT
      JOB      JCL      LIST,NOFORMAT
      PLI      PL/I     LIST,NOFORMAT
      PL1      PL/I     LIST,NOFORMAT
 

In this way, customers may change the search order, the suffix name, and the Panvalet ADD options to meet their needs. Some customers may have already compiled a custom Suffix Table from Mainframe Access Version 2. A migration tool is provided to convert this configuration back into a text file which may be presented to Mainframe Access Version 3.

 //jobname  JOB (MFA),'PANVALET SUFFIX',CLASS=A,MSGCLASS=X
 //***************************************************************
 //*        EXTRACT PANVALET SUFFIX FROM MFA SERVER V2
 //***************************************************************
 //*
 //PVSUFFX  EXEC PGM=MFAUTL01,REGION=1M
 //STEPLIB   DD  DISP=SHR,DSN=your.MFA.V3.LOADLIB
 //MFALIB    DD  DISP=SHR,DSN=your.MFA.V2.LOADLIB
 //MFAPARM   DD  DISP=SHR,DSN=your.parms.CNTL(PANVALET)
 //
 

Panvalet Security Exit

Librarian

Overview

Librarian is a powerful change management system for source modules and data records. Under Librarian, all source is stored within proprietary Librarian master files in a highly compressed format. Individual source modules may be stored and retrieved by name. Multiple master files may be defined and shared among the user groups.

Librarian provides licensed users with programmable access to source modules via the File Access Interface Routines (FAIR) API. This is a read-only interface which permits multiple concurrent access for Mainframe Access threads to browse source members residing in a Librarian master file. During Server initialization, Mainframe Access will attempt to load this interface into memory. If this API interface is available through the standard search order (STEPLIB, JOBLIB, or SYS1.LINKLIB at the customer site) then Librarian services will be offered. Startup initialization messages will indicate if Librarian is available. It is a customer responsibility to provide a suitable STEPLIB concatenation which will allow selection of the desired release and version of the Librarian components.

        //STEPLIB DD DSN=your.MFA30.LOADLIB,DISP=SHR
        //        DD DSN=your.MFA30.SASC.LINKLIB,DISP=SHR
        //        DD DSN=CAI.LIBR43.CAILIB,DISP=SHR
    

For source additions or updates under Librarian, Mainframe Access will invoke the standard Librarian batch utility AFOLIBR. Access to this utility will be serialized, since Librarian does not support multiple, concurrent access to this service from the same address space. In some cases, a customer may have renamed the Batch Update utility AFOLIBR. If this is the case, the new name at this site must be defined to Mainframe Access as a parameter override.

        MFA_LIBRARIAN_HISTORY=YES           - MFA default
        MFA_LIBRARIAN_UPD_MODULE=LIBRUPD    - site override
    

References

• Librarian Command Reference Guide
• Librarian File Access Interface Routines
• Librarian Messages Guide
• Librarian Installation Guide
• Librarian User Guide
• Librarian Systems Services Guide
• Librarian Security Administration Guide

Librarian Exit Table

Librarian does support user exits under its Batch Update facility. The user exit may be common, or may be assigned to a specific master file. In order to configure this option, MFA references a reserved DD named LIBXIT$. If specified in the JCL, MFA builds a memory table to specify the Output Exit to be used for the given master file.

 

*  Librarian Exit Table (fixed format)
*
*  EXIT columns 1-8 is an exit module name
*       found in the STEPLIB, JOBLIB, LINKLIB concatenation
*  LIBRARIAN MASTER name resides in columns 11-54
*       any master file with this prefix will invoke the exit
*
* EXIT    Librarian Master file prefix or full name
********  ********************************************
LIBREXIT  PROD.LIB
LBXIT02   MY.LIBRARIAN.MASTER

Endevor

Overview

Endevor is a full function change control system with signout controls and extensive user customization. Through the use of Exits and Processor Groups, it is possible to automatically re-compile the changed objects, and re-link any components which require those objects. Endevor also has several optional system features such as External Security, and alternate RACF user ID support.

Starting with Release 39, Endevor provides licensed users a powerful Endevor Services API (ENA$NDVR). This interface permits full-function access to read or update source objects residing in an Endevor repository. During Server initialization, Mainframe Access will attempt to load this interface into memory. If this API interface is available through the standard search order (STEPLIB, JOBLIB, or SYS1.LINKLIB at the customer site) then Endevor services will be offered. Startup messages will indicate if Endevor is available. It is a customer responsibility to provide a suitable STEPLIB concatenation for selection of the desired release and version of the Endevor components. Mainframe Access will examine the Endevor C1DEFLTS table to determine the version of Endevor being used. This is necessary because the control structures used by the Endevor API versions are not fully downward-compatible. Mainframe Access must build the API request using the format demanded by the version in effect at your site. If no C1DEFLTS table is found, then ENDEVOR support will not be enabled.

        //STEPLIB DD DSN=your.MFA30.LOADLIB,DISP=SHR
        //        DD DSN=your.MFA30.SASC.LINKLIB,DISP=SHR
        //        DD DSN=CAI.NDVR40.AUTHLIB,DISP=SHR
        //        DD DSN=CAI.NDVR40.CONLIB,DISP=SHR
    

Note that the Endevor API was designed to be a batch-oriented service. It is a file-based interface, not a record-based interface. That is, an object is moved from an Endevor-managed repository, to a specified work file; or vice-versa. Mainframe Access will dynamically create the necessary files as required. A transaction history log is likewise written to a log file. Mainframe Access may optionally be configured to retain a full Endevor transaction log to be used as an audit trail. Access to the Endevor interface is serialized since Endevor does not support concurrent accesses from the same address space. At the same time, all Endevor user exits and packages are operational. This means that site customization will affect the response time for an end-user accessing Endevor data under Mainframe Access. This may require adjustments to the timeout parameters on the Mainframe Express clients.

Mainframe Access does maintain the user ID security context for each active thread using the standard IBM security environment and standard SAF calls. Mainframe Access will always invoke the Endevor API interface using the security credentials of the end-user as provided during client logon. To minimize some administrative overhead, Micro Focus recommends the adoption of an Alternate RACF user ID to simplify the administration of RACF access rights for the user population. Access security remains a SITE responsibility. This is no different than standard BATCH or TSO access under Endevor. Mainframe Access will not schedule any Endevor access using the Mainframe Access started-task profile. Also be mindful that some change control "processors" might better be managed by specialist personnel using the Endevor ISPF panels rather than being triggered repeatedly by online Mainframe Access users.

References

• Endevor Administration Guide
• Endevor API Guide
• Endevor Error Codes and Messages
• Endevor Exits Guide
• Endevor Footprints Guide
• Endevor Installation Guide
• Endevor Packages Guide
• Endevor Security Guide
• Endevor User Guide
• Endevor Utilities Guide

Endevor Dependent Regions

In order to isolate the Endevor run-time environment from the Mainframe Access address space, and improve the concurrency (and hence scalability) of Endevor accesses, Mainframe Access will schedule the execution of the Endevor API in an independent processing region referred to as an Endevor Dependent Region. This is a special purpose address space that Mainframe Access creates dynamically and shares with all Mainframe Access/Endevor users. It is serially assigned to whatever thread is in need of Endevor API services.

Multiple Endevor dependent regions may be started to meet your throughput requirements. The sample SERVERS member contains a definition for an Endevor address space group that allows a maximum of 2 address spaces to be started for Endevor processing. This value can be increased if the demands of your Endevor usage will benefit from greater concurrency.

You will need to update the started task JCL for dependent regions before you can use the Endevor support. Review the sample JCL member MFAAS and follow the instructions in that member to add your Endevor AUTHLIB and CONLIB program libraries to the STEPLIB concatenation. If you use Processor Groups to compile and relink automatically, specify DYNAMNBR=300 on the EXEC statement and eliminate the pre-allocation of SYSPRINT and SYSTERM which conflict with Endevor procedures to allocate compile and link output files.

DSNQUALIFIER_ENDEVOR=prefix         --- OVERRIDE FOR ENDEVOR ACCESS

Endevor C1DEFLTS File

It may be necessary to modify the C1DEFLTS table to facilitate the Endevor support in a multi-user environment. If you do modify the C1DEFLTS table, the resulting C1DEFLTS load module should be stored in the STEPLIB of the MFA server start-up JCL to allow for a custom usage. Your Endevor administrator will have the current C1DEFLTS source and corresponding JCL.

The following C1DEFLTS table change is required:

• The BATCHID= parameter must be 1. This permits signout and security accesses to be based on the security profile of the user, not the MFA Server started task.

C1DEFLTS TYPE=MAIN,
         ACCSTBL=,       ACCESS SECURITY TABLE           X
         APRVFLG=N,      APPROVAL PROCESSING (Y/N)       X
         ASCM=0,         ASCM CONTROL PASSWORD           X
         BATCHID=1,      BATCH UID FROM JOBNAME/USER=    X
         CIPODSN=,       CCID VALIDATION DSNAME          X
          .
          .
          .
          .
C1DEFLTS TYPE=END
END

Endevor Setup Errors

Several environmental conditions are validated when the first transaction is processed on an Endevor Dependent Region. Failure to provide a consistent run-time environment will result in the following abends:

ChangeMan ZMF

Overview

Serena's ChangeMan ZMF is a comprehensive mainframe specific solution that provides reliable, streamlined implementation of changes in z/OS environments. Its version, build and release management functions can be used to manage system changes from development to deployment.

ChangeMan ZMF 5.3 introduced the Serena XML Services, an open interface for interoperability and data interchange with ChangeMan ZMF. This new interface is intended to replace the RPC and API interfaces that were used with earlier releases of ChangeMan. Mainframe Access Server implements the ChangeMan functions using the XML Services interface.

Mainframe Access requires ChangeMan Version 5.3.6 or later.

Customization

The customizations required in Mainframe Access Server are simple and deal primarily with defining the interface to the ChangeMan ZMF subsystem. There are four MFA Server startup parameters for defining this interface and they are described in detail below. The parameters are also documented in the section Editing Mainframe Access Parameters in the chapter Configuration.

The Server's ChangeMan interface uses Mainframe Access Application Server address spaces (also known as dependent regions) to provide isolation for the ChangeMan processing. Separating the processing from the MFA Server control region avoids potential interference with other client requests being processed in the control region.

Both the control region and the dependent region(s) have startup parameter requirements for the ChangeMan interface definition. The sample control region parameters are found in member PARMS and the sample dependent region parameters are found in member PARMSAS. Review the startup parameter information in the sections that follow and update your parameter definitions with values appropriate for your installation.

Control Region Startup Parameters

Control Region Started Task JCL

You can customize the sample JCL procedure for the MFA Server started task with required and optional DD statements for the ChangeMan interface.

CMNOPTS

Include and customize this DD to provide MFA with your site-dependent user options and your default build options. MFA reads the XML file you specify, using only the options defined for field names that correspond to build and user options. These options enable MFA to properly check out and stage ChangeMan components. See your Serena documentation for ZDD Build Options for more information.

//CMNOPTS DD  DSN=youroptions.xml,DISP=SHR

Where youroptions represents a filename prefix of your choice.

<?xml version="1.0"?>
<options name="BUILD">
 <profile application="*" language="*" procname="*" libtype="*">
  <field name="Language"       editable="Y" default="CBL"/>
  <field name="BuildProc"      editable="Y" default="CMNCOB2/>
  <field name="Db2PreCompile"  editable="Y" default="N" />
  <field name="Db2Subsystem"   editable="Y" default="DSN7" />
  <field name="CompileOptions" editable="Y" default="RENT,LIST,XREF(SHORT)" />
  <field name="LinkOptions"    editable="Y" default="RENT,MAP,XREF" />
  <field name="UserOption01"   editable="Y" default="N"
     tag="Compile only"  required="Y"  validation="YN"   />
  <field name="UserOption02"   editable="Y" default="N"
     tag="IMS DLIT entry"  required="N"  validation="YN"   />
  <field name="UserOption03"   editable="Y" default="N"
     tag="CICS precompile"  required="N"  validation="YN"   />
  <field name="UserOption04"   editable="Y" default="N"
     tag="Drop INCLUDEs"  required="Y"  validation="YN"   />
  <field name="UserOption05"   editable="Y" default="N"
     tag="Easytrieve"  required="Y"  validation="YN"   />
  <field name="UserOption06"   editable="Y" default="N"
     tag="AMB Generation"  required="Y"  validation="YN"   />
 </profile>
</options>

CMNLIB$

//CMNLIB$ DD  DSN=your.MFA30.CNTL(CMNLIB$),DISP=SHR

Where your is a dataset qualifier representing the location of the dataset.

The following is the default data:

*  ChangeMan Library Table (fixed format)
*          Like Source only
* L
* I BLDPROC  LANGUAGE
* B  NAME     Name
*** ******** ********
ASM CMNASM   ASM
COB CMNCOB2  COBOL
APS DGSAPCOM COBOL
ASC DGSAPSCR COBOL

CMNJOB$

Optionally include and customize this DD to define up to four job cards ChangeMan can submit for a build request, which is scheduled as an independent job by SERNET as part of the staging process.

//CMNJOB$ DD DSN=your.MFA30.CNTL(CMNJOB$),DISP=SHR

Where your is a dataset qualifier representing the location of the dataset.

The default job card contains:

//useridB  JOB (MFA),'CMN-BUILD',CLASS=A,MSGCLASS=X
//*
//*         
//*

Dependent Region Startup Parameters

MFA supports the following dependent region startup parameters for ChangeMan:

• CHANGEMAN_INTERFACE
• CHANGEMAN_SSID

Both of these parameters are also control region parameters. When you specify the same parameter for both the control and dependent startup regions, their values must match.

Dependent Region Started Task JCL

The MFAAS sample JCL procedure contains JCL statements you must customize and enable for the ChangeMan interface. The preceding discussion of the CHANGEMAN_ASGROUP parameter highlights the required changes. If you update sample JCL in the MFA Server samples data set, be sure to copy it to the system procedure library.

References

• Serena XML Services User Guide
• ZMF Administrator Guide
• ZMF Messages Guide

AppMaster Builder Support using APS Components

--------------------- WAC4 - LIBRARY TYPES PART 1 OF 2 ----------- Row 1 of 65
 COMMAND ===>                                                  SCROLL ===> PAGE

 Enter END command to save changes or CANCEL to exit.
 Enter * in line command field for global staging libraries selection list.

      LIB                                               LIKE  DEFER TARGET SEL.
      TYPE DESCRIPTION                               (S/C/L/P)(Y/N)  TYPE  OPT.
 '''' COB  Cobol_______________________________________  S     Y     LOD   __
 '''' CPY  Copy Books__________________________________  C     Y     ___   __
 '''' JCL  Job Control Language________________________  P     Y     ___   __
 '''' CTC  Control cards_______________________________  P     Y     ___   __
 '''' LOD  Load Library________________________________  L     Y     ___   __
 '''' ACI  APS COBCICS_________________________________  S     Y     LCI   __
 '''' ACN  APS APSCNTL_________________________________  P     Y     ___   __
 '''' ADA  APS APSDATA_________________________________  P     Y     ___   __
 '''' ADE  APS APSDE___________________________________  P     Y     ___   __
 '''' ADG  APS COBDLG__________________________________  S     Y     LDG   __
 '''' AEX  APS APSEXPS_________________________________  P     Y     ___   __
 '''' AFE  APS APSSCFE_________________________________  P     Y     ___   __
 '''' AID  APS COBIDMS_________________________________  S     Y     LOD   __
 '''' AIM  APS COBIMS__________________________________  S     Y     LIM   __
 '''' AIO  APS APSCNIO_________________________________  P     Y     LOD   __
 '''' AIS  APS COBISPF_________________________________  S     Y     LOD   __
 '''' AMA  APS APSMACS_________________________________  C     N     ___   __
 '''' AMS  APS AMSERV__________________________________  P     Y     ___   __
 '''' AMV  APS COBMVS__________________________________  S     Y     LOD   

Copyright © 2007 Micro Focus (IP) Ltd. All rights reserved.