Perform a Best Practice Implementation

Advice for
Endevor
administrators on how to set up a complete implementation using the Best Practice Implementation (BPI) method
ce18
This article describes how an
Endevor
administrator can set up a complete implementation of the product using the Best Practice Implementation (BPI) method. The BPI defines a best practices lifecycle for active software development. The BPI process allocates the necessary files and sets up all definitions that are required to let you begin to use the product and is delivered as a set of input tables and jobs that you configure and run. After you complete the BPI, you are ready to load your source code into the
Endevor
inventory structure that supports the software development lifecycle.
As a change manager (
Endevor
administrator), you can use the BPI to set up a complete implementation of
Endevor
that incorporates best practices. This method lets you easily and quickly allocate and populate the libraries that support the software development lifecycle. The BPI is delivered as a set of input tables and jobs that you configure and run.
This diagram outlines the BPI process:
How to Perform a Best Practice Implementation
The BPI, includes the following steps:
  1. Run BPISTART. This job allocates the BPI libraries.
  2. Edit #OPTION. This member defines symbol values that are used to resolve variables defined in the BPI models and REXX members.
  3. Submit the BPI jobs. We recommend that you execute the BPI process in iterations implementing one System or application at a time.
  4. Verify the implementation. Access your implementation and make sure it was created and setup successfully.
  5. Load your software inventory. We recommend that you complete setting up the BPI, before you load any inventory.
We recommend that you execute the BPI process in iterations. For the first iteration, you might implement one System (or application). This lets you become familiar with how to edit the input tables and how the jobs work. After the first iteration, you could execute the BPI to implement an entire application. (An application can consist of multiple Systems and Subsystems.) Then you could do additional iterations, one for each additional application. For the first iteration, you perform all the steps. For subsequent iterations, you re-edit the BPI input tables and then rerun the jobs beginning with job #5ALLOC.
Review Prerequisites
Before attempting this implementation, verify that the following prerequisites are complete:
  • Verify that
    Endevor
    is properly installed at your site. For more information about the installation steps, see Installation Tasks for the Systems Programmer. Proper installation has the following requirements:
    • The
      Common Components and Services
      components
      LMP
      and CAIRIM for product licensing and authorization must be installed and customized.
      The components CAIENF and CAICCI are not required for the BPI. However, these components are required if you want to use
      Endevor
      with the Concurrent Action Processing feature, the Web Services component, or the companion product
      Change Manager Enterprise Workbench
      . CAIENF and CAICCI can be configured after you complete the BPI.
    • NDVRC1 must be authorized.
    • BC1JJB03 must have been executed.
    • The load modules contained in
      iprfx.iqual.
      CSIQAUTH and
      iprfx.iqual.
      CSIQAUTU (and optionally
      iprfx.iqual.
      CSIQLOAD) must reside in an APF-authorized library. You can use one of the following methods to make sure that the load modules are in an APF-authorized library:
      • Copy the members from
        iprfx.iqual
        .CSIQAUTH and
        iprfx.iqual
        .CSIQAUTU libraries to an existing APF-authorized library.
      • APF-authorize
        iprfx.iqual
        .CSIQAUTH and
        iprfx.iqual.
        CSIQAUTU.
      • Copy members from
        iprfx.iqual
        .CSIQAUTH and
        iprfx.iqual
        .CSIQAUTU (and optionally
        iprfx.iqual
        .CSIQLOAD) to an existing LPA library.
      • Define the
        iprfx.iqual
        .CSIQAUTH and
        iprfx.iqual
        .CSIQAUTU (and optionally
        iprfx.iqual
        .CSIQLOAD) data sets as LINKLIST or LPA libraries themselves.
    • Define
      Endevor
      to the ISPF Environment.
    • If your site has multiple CPUs sharing DASD, you must define queue names. If you are using Unicenter
      MIM
      Resource Sharing or IBM Global Resource Serialization (GRS), include the queue names in the appropriate Global Resource Queue Name Table.
    • If
      ACF2
      is the security software used at your site, modify the TSO Command Limiting Facility to allow ISPTLIB commands (ACMQ, BC1PACMI, ESORT, EONLY, EM, QM, and so on).
  • The following BPI installation considerations apply depending on how
    Endevor
    is configured at your site:
    • The BPI assumes your site is licensed for the following product options:
      • Endevor
        Extended Processors
      • Endevor
        Automated Configuration
    • Complete all steps described in Configuring Your Product. The following exceptions apply to the steps in Configuring Your Product:
    • If you use LINKLIST or LPA libraries for the CSIQAUTH/CSIQAUTU data sets, tailor the jobs created by the BPI process prior to submission. Remove, or comment out, the STEPLIB DD statements from the job members created in the BPILIB library before submitting the job.
    • If you use LINKLIST or LPA libraries for the CSIQLOAD data set, tailor the jobs created by the BPI process prior to submission. Remove, or comment out, the STEPLIB and CONLIB DD statements from the job members created in the BPILIB library before submitting the job.
  • The person performing the BPI needs the following general knowledge of the mainframe environment and a basic understanding of the.
    • You need a working knowledge of the mainframe environment, the z/OS mainframe operating system, the Time Sharing Option facility (TSO), and the Interactive System Productivity Facility (ISPF).
    • Become familiar with the basic
      Endevor
      concepts. For more information, see Installing and Administrating.
    • Become familiar with the Best Practice Implementation concepts. For more information about the BPI concepts, see the BPI Software Inventory Lifecycle.
Plan for Your Production Implementation
To perform the BPI process, decide how to set up your
Endevor
configuration. The BPI automates some of those decisions by incorporating best practices and recommended settings automatically within the process. You must know and understand the sort of implementation created when performing the BPI process. This section describes each of those best practices in more detail.
BPI Software Inventory Lifecycle
The BPI sets up a seven-environment mapping structure, by default. This structure includes the Development (DEV), Quality Assurance (QAS), Production (PRD), Emergency (EMER), Unclaimed (UNCLMED), Archive (ARCHIVE), and Administrator (ADMIN) environments. Your site may not need all seven environments, or you may need more than seven. However, this structure represents an active development lifecycle that is appropriate for most sites.
The lifecycle defines the movement of your software inventory through a set of data set libraries. These lifecycles are defined in the Defaults table (C1DEFLTS). A data set naming convention supports the lifecycle structure. The Best Practice Implementation sets up the following lifecycles or maps:
  • Standard Map
    For regular development activities. The Standard Map is where most activity occurs. The Standard Map starts with the DEV environment, at entry stage, stage 1. From DEV Stage 1, source is promoted to DEV Stage 2, then to QAS stage 2, and finally PRD stage 2. Stage one for the Quality Assurance and Production environments are skipped. DEV stage 2 maps to QAS stage 2, and QAS stage 2 maps to PRD stage 2.
  • Emergency Map
    For emergency fixes. The Emergency environment maps also to PRD stage 2.
  • Unclaimed Map
    For unclaimed or unclassified elements. The Unclaimed environment has an entry stage of 2. This environment does not map to any other environment.
  • Archive Map
    For archived elements. The Archive environment has an entry stage of 2. This environment does not map to any other environment.
  • Administrator Map
    For the
    Endevor
    Administrator activities. The Administrator environment has an entry stage of 1. This environment does not map to any other environment.
The following image shows how the BPI environments are mapped:
How BPI Environments are Mapped
BPI Environment and Stages
Each lifecycle defines the movement of software inventory from environment-stage to environment-stage until the end of the lifecycle. Each environment has two stages and each environment-stage represents a library level. To support this structure, the data set naming convention uses qualifiers to identify each environment and each stage. Details follow about each environment.
  • Development (DEV) environment
    This environment has two stages that let you maintain two versions of an element. You can use Stage 2 as a location for elements that are considered complete or as a temporary holding place for confirmed changes, while you re-edit the element in Stage 1. Stage 2 also provides another location useful for merging changes together with those that have been promoted to QAS or PRD. Another benefit of two development stages is to be able to test with different compiler parameters at Stage 1 versus Stage 2. For example, Stage 1 could be set to test compile options and Stage 2 could be set to production compile options. The last compile, before moving up the lifecycle, is always done at DEV Stage 2.
  • Quality Assurance (QAS) environment
    This environment is used to perform many different types of testing. Stage 1 provides a common integration stage. Although useful, to reduce the number of stages an element must pass during the path to production, Stage 1 of the QAS environment is not used in the BPI delivered lifecycle. Stage 2 would be used to make sure the applications are system tested and ready for production.
  • Production (PRD) environment
    This environment represents the production code. Stage 1 of the PRD environment is not used in the BPI delivered lifecycle. Stage 2 is used for the storage of the production source. The PRD environment should be package protected.
  • Unclaimed (UNCLMED) environment
    This environment is used to store elements that could not be classified in the standard inventory structure (systems, subsystems, and so on.). Only the second stage is used for this environment. This environment is intended to be a holding area for elements whose use and purpose are unknown. This may be common in conversion situations, when converting from a different source control management application to. The UNCLMED environment stores only the source and has only one system and subsystem. Its purpose is a temporary holding position for those elements that are not identified with a system during the implementation (or conversion) process. If an element is found missing after the
    Endevor
    Implementation is complete, you can look in the UNCLMED environment to see if the element is there. You can then transfer that element from UNCLMED to the appropriate system and subsystem. After elements in UNCLMED have been identified and transferred into the correct system-subsystem, the version in UNCLMED should be deleted. The final goal should be to discontinue the UNCLMED environment in time.
  • Administrator (ADMIN) environment
    This environment is separate from the DEV to QAS to PRD lifecycle, and is reserved for the role of the
    Endevor
    administrator. The
    Endevor
    administrator has different security requirements than the development and testing teams. The separate security rules for the administrator role are easier to maintain if in a separate ADMIN environment. The ADMIN environment’s data sets begin with a different high level qualifier, while the remaining environments (DEV, QAS, PRD, EMER, UNCLMED, and ARCHIVE) all use the application high level qualifier. Stage 2 of the ADMIN environment hosts the
    Endevor
    Configuration Tables that are used to define the site’s infrastructure and default options, and the Endevor processors which are used to process all the elements for each system in the standard DEV to QAS to PRD lifecycle. Stage 1 of the ADMIN environment provides an area for the administrator to make changes as needed to any of the tables or processors maintained within the ADMIN environment. Stage 2 only stores the elements specific to
    Endevor
    administrators. Sites can then use packages to promote their changes from Stage 1 to Stage 2, allowing for a back-out if needed.
  • Emergency (EMER) environment
    This environment is also separate from the standard lifecycle. This environment is used for coding fixes that need to be put in immediately. Stage 1 of the EMER environment serves as the place where the code changes are to be made. Stage 2 of EMER is package protected and must be included in the production JCL STEPLIB concatenation. An emergency package needs to be created to promote elements from Stage 1 to Stage 2. An approval needs to be made by those that were assigned in the approver group(s). An emergency approver group must be given the authority to approve emergency packages. This is required to prevent unapproved changes being picked up by production. EMER maps to the PRD environment for ease of making changes to programs and components. It is probable that emergency changes promoted to EMER Stage 2 will afterwards be transferred to the DEV environment (via the TRANSFER action) and then promoted through the typical lifecycle and testing procedures before being permanently moved to production. The EMER environment contains the same types, systems, and subsystems as the PRD environment. The EMER Stage 2 loadlib should be concatenated before the production stage 2 loadlib, to pick up any emergency changes.
  • The Archive (ARCHIVE) environment
    This environment is used to store elements that are deleted from the PRD environment, but a site still wants to maintain a copy of for auditing or history purposes. The ARCHIVE environment utilizes only the second stage of this environment (Stage 2). Elements need to be transferred there via the TRANSFER action or via a PACKAGE with TRANSFER action SCL. It is a stand-alone environment. The ARCHIVE environment contains all the types, systems, and subsystems of the PRD environment.
Stage Name, Number, ID
When defining Stage names, numbers, and IDs, establish a simple pattern. Each Environment contains two Stages, regardless of whether you use both Stages, and the Stage numbers are 1 and 2. With the BPI, the Stage ID is the same as the Stage number, and Stage names are built using a simple naming convention. As long as the Environment name is fewer than eight characters, the Stage name can be a combination of the Environment name and the Stage ID or number.
Data Set Naming Conventions
Having standard naming conventions within various components of
Endevor
makes the product easier to support. The Best Practices Implementation (BPI) method includes standard data set naming conventions.
Previously if you were not using the BPI method,
Endevor
used two sets of high and second level qualifiers for data set naming (iprfx.iqual and uprfx.uqual). The first set was reserved for the
Endevor
installation runtime data sets. These data sets were prompted for during the installation process (job BC1JJB03). The second set was used as the prefix for
all
the
Endevor
data sets that were created (element catalog, MCFs, package file, base and delta files, processor output libraries, and so on).
When you configure
Endevor
using the BPI, you must specify four high level qualifiers for the
Endevor
data sets. The installation runtime qualifier (iprfx.iqual) remains the same. The remaining three high level qualifiers are specified in the BPI Option member. Having these multiple high level qualifiers makes it easier for administrators to establish and maintain security rules, as well as provide a visual distinction between the data sets. The three prefixes are as follows:
  • SiteHighLevelQual for all
    Endevor
    site-wide data sets. This includes element catalog and index, ACM root and cross reference files, package file and Master Control files.
  • AdminHighLevelQual for all
    Endevor
    ADMIN environment data sets. This includes all allocations for the ADMIN environment.
  • ApplHighLevelQual for all
    Endevor
    application data sets. This includes the base and delta files for each of the standard application system, subsystem, and type combinations.
The maximum size for a data set name cannot exceed 44 characters, thus the maximum sizes allowed for the three high-level qualifiers will depend on the system and subsystem names. You can use multiple nodes within each high-level qualifier. The number of nodes is not important. However, the
Endevor
data set names use a standard format consisting of the following, where the maximum number of characters allowed are shown in parenthesis: system (8), subsystem (8), subset of the environment name (3), stage number (1) and type (8). Using this standard, if you use the maximum amount of characters for system, subsystem, and so on, then only 12 characters are left for the high-level qualifier nodes. We recommend that the prefix nodes be 12 characters or fewer, if possible. This is to avoid data set length problems in the future if additional systems, subsystems, and types are created.
Data Set Rules
When allocating data sets for the BPI method, follow these rules:
  • One base library per environment, system, subsystem, stage, type.
  • Type name is the last node of the data set name and reflects the language.
  • Base libraries are defined as PDSEs.
  • One delta library per environment, system, subsystem.
  • Provide High-Level Qualifier only, the BPI provides an ending qualifier. Processors also use this naming convention.
  • Reverse delta format is used for most types. Some types are better suited for full image or log delta format.
Centralized Processors
The Best Practice Implementation establishes a single repository location for processors instead of having unique or custom processors that are defined and stored for each system. It is simpler to maintain one set of processors and ensures consistency across systems.
The BPI process stores all processors in the administrator (ADMIN) environment.
Inventory Structure
The
Endevor
inventory structure allows you to do the following:
  • Work with program modules without having to know where they are physically located, or how they are compiled.
  • List all the program components that make up an application, regardless of type.
  • Determine the locations of an element simply by entering the element name on a display screen.
  • Act on a cross section of your program inventory. For example,
    Endevor
    allows you to list all COBOL code in your shop, or promote an entire new release of the payroll application with a single command.
With the BPI, a predefined inventory structure is included. The structure (environments, systems, subsystems, types, and so on) is outlined in rows within table file members.
The BPI provides the following default definitions for the inventory structure components.
Environments
The default environment names are delivered in the BPI input table, T#ENVMTS. Each data row consists of the environment name and stage information.
BPI REXX member, O#ENVMTS located in BPILIB must remain in sync with T#ENVMTS.
The rows in these tables are used to build the software change lifecycle (established within the C1DEFLTS table), the
Endevor
configuration tables, and to build SCL members. You specify what environments you want to create, the environment stage names, and the entry stage for that environment. Also, you specify how these are mapped -- the next environment to map to and the next stage of that environment to map to.
Systems
The default system names are delivered in members T#ADMSYS and T#SYSTMS. Each data row consists of a system name and a description. T#ADMSYS is used solely for the ADMIN environment. The ADMIN environment, as delivered, contains one system and subsystem. It is required that you keep the administrative environment. The BPI defaults to creating the first ADMIN system specified in T#ADMSUB as the main repository of all the
Endevor
processors and configuration tables that the remaining application systems use. The system name for the Processor Output Libraries defaults to the first system specified in T#ADMSYS. You can add additional systems to the ADMIN environment, by adding additional rows to the T#ADMSYS table.
T#SYSTMS table is used by all the environments defined in the T#ENVMTS table except for Administrator and Unclaimed environments. That includes the Development, Quality Assurance, Production, Emergency, and Archive environments in the delivered table.
This T#SYSTMS table is related to the T#SUBSYS table. If you add or remove a system row from the T#SYSTMS table, add or remove the associated rows in the T#SUBSYS table.
The system definition defaults delivered with the BPI are as follows:
  • Next System - defaults to the current system
  • Comments Required
  • CCID Required
  • Duplicate Element Check is Not Active
  • Duplicate Processor Output Check is Active -- Severity Level is ‘E’
  • Element Jump Acknowledgment Required
  • Signout is Active
  • Signout Dataset Validation is Not Active
Subsystems
The default subsystem names are delivered in members T#ADMSUB and T#SUBSYS. Each row consists of a system name, subsystem name and a description. Any system specified in T#SUBSYS must match a system specified in T#SYSTMS. Any system specified in T#ADMSUB must match a system specified in T#ADMSYS
The delivered subsystem definition specifies that the Next Subsystem defaults to the current subsystem.
Types
The default type names are delivered in members T#ADMTYP and T#TYPES. The T#ADMTYP member is used to define types for the Administrator environment and the T#TYPES member is used to define types for the Development, Quality Assurance, Production, Emergency, Unclaimed, and Archive environments. The length of the data in each row of these members is 200 characters. Each row consists of a type name, processor group name, generate, move and delete processor names, foreground allowed flag, language, Panvalet and Librarian source languages, compare from and compare to columns, element delta format, and type and processor group descriptions. When a type is defined during the BPI process, the first processor group listed for each type is the default processor group.
If the BPI process is executed and your site did not purchase the Extended Processor option, the implementation fails at the point when the DEFINE TYPE PROCESS action is executed. The execution of this action results in a return code of 12 when
Endevor
performs a check against the PROC parameter value in the C1DEFLTS configuration table and determines this option is not activated.
Type definition defaults delivered with the BPI:
  • Do Not Expand Includes
  • Element Delta Format is Reverse
  • Do Not Compress Base
  • Regression Threshold is 80
  • Regression Severity is Caution
  • Do Not Consolidate Element Levels
  • Consolidate Elements at Level 96
  • Number of Element Levels to Consolidate 0
  • Do Not Consolidate Components Levels
  • Consolidate Components at Level 96
  • Component Delta Format Reverse
  • Number of Component Levels to Consolidate 0
  • USS Recfm NL
The Regression Percentage Threshold is automatically set to 80, except for LOG or IMAGE delta formats, where it is set to 0.
Processor Groups
The processor group and processor names are included in members T#ADMTYP and T#TYPES with the type attributes.
One exception to the naming standard is for the special Endevor processor group used by the type PROCESS. The name of this processor group is PROCESS.
The processor group definition defaults delivered with the BPI are listed below:
  • Move Action Uses Move Processor
    • If the entry stage of the environment is stage 1, it uses the Generate processor. The production environment always uses the Move processor
  • Transfer Action Uses Move Processor
  • Allow or Do Not Allow Foreground Execution
    • The Allow or Do Not Allow is specified in the T#ADMTYP and T#TYPES table. The Unclaimed and Archive environments uses Allow for all types
  • Processor Output Type
  • Generate/Move/Delete Processors
    • The processor names are be taken from the T#TYPES table, except for type PROCESS, which always uses the Endevor processor names. The Unclaimed and Archive environments set all processor values to *NOPROC* for all types
Processor Symbols
Processor group symbol overrides are created in #3ADMIN and #9DEFGRP, to coincide with the delivered BPI processors in CSIQSAMP. There are two tables within the #3ADMIN JCL that define what symbols need to be created for the administrator environment. The standard environments use the T#SYMBLS table. Processor symbols can be a length of eight characters and the override values can be up to 65 characters. As delivered, processor symbol overrides are required, because a single processor is shared across multiple processor groups. You have the flexibility to change or add to the delivered processor symbol definitions by editing #3ADMIN or T#SYMBLS.
The processor symbols definition defaults delivered with the BPI are listed below:
Processor Symbols Definition Defaults
The processor symbols definition defaults delivered with the BPI are listed below:
Symbol
Override
Location
Table
HLQ
&#HLQADM
Administrator Environment, all systems and processor groups, for GEN and MOVE
#3ADMIN
XSYSLIB1
&C1MACLIB
Administrator Environment, all systems, type TABLE, procgrp ASMTBL, stage 1 & 2, for GEN only
#3ADMIN
LOADLIB
&CSIQAUTU
Administrator Environment, all systems, type TABLE, procgrp ASMTBL, stage 2, for GEN only
#3ADMIN
LOADLIB
&CSIQAUTU
Administrator Environment, all systems, types ASMPGM and COBOL, procgrp USEREXIT, stage 2, for GEN only
#3ADMIN
LANGVER
COBII
Administrator Environment, all systems, type COBOL, procgrp BATCHCII, stage 1 & 2, for GEN only
#3ADMIN
LANGVER
COBII
All environments except Administrator, Archive, and Unclaimed, all systems, type COBOL, procgrp BATCHCII, CICSCII, DB2CII, and IDMSCII, stage 1 & 2, for GEN only
T#SYMBLS
IDMSDBN
SYSTEM
All environments except Administrator, Archive, and Unclaimed, all systems, type COBOL, procgrp IDMSCII and IDMSCLE, stage 1 & 2, for GEN only
T#SYMBLS
IDMSDICT
SYSDICT
All environments except Administrator, Archive, and Unclaimed, all systems, type COBOL, procgrp IDMSCII and IDMSCLE, stage 1 & 2, for GEN only
T#SYMBLS
IDMSDMCL
USERDB
All environments except Administrator, Archive, and Unclaimed, all systems, type COBOL, procgrp IDMSCII and IDMSCLE, stage 1 & 2, for GEN only
T#SYMBLS
DDLDML
DBLOADLIB
All environments except Administrator, Archive, and Unclaimed, all systems, type COBOL, procgrp IDMSCII and IDMSCLE, stage 1 & 2, for GEN only
T#SYMBLS
DDLDCLOD
DBLOADDSN
All environments except Admin, Archive, and Unclaimed, all systems, type COBOL, procgrp IDMSCII and IDMSCLE, stage 1 & 2, for GEN only
T#SYMBLS
DDLDCMSG
DBMSGDSN
All environments except Admin, Archive, and Unclaimed, all systems, type COBOL, procgrp IDMSCII and IDMSCLE, stage 1 & 2, for GEN only
T#SYMBLS
Configuration Tables
Endevor
configuration table source is delivered in the
iprfx.iqual
.CSIQSRC deployment library. New C1DEFLTS and ESYMBOLS configuration table source is built by the BPI process, based on information specified in the table input members located in the BPIDATA data set and information specified in the #OPTION member located in the BPILIB data set. None of the other configuration table source is altered by the BPI process.
  • BPI job #1TABLES builds the two new tables and creates load modules for the C1DEFLTS, ENCOPTBL, ENDICNFG and ESYMBOLS tables.
  • BPI job #3ADMIN builds an inventory location for the tables (ADMIN/ADMIN/ENDEVOR/TABLE/2) and adds and promotes all the configuration tables to that location.
You can modify the source as required after the implementation is complete.
When performing the Best Practice Implementation, we recommend that you set the WARN parameter to YES in the
Endevor
configuration table, BC1TNEQU. When WARN=YES, the ESI warning mode is in effect. Warning mode allows access to resources even if your site security package (RACF,
ACF2
, or
Top Secret
) indicates that access should be denied. You should use ESI Warning Mode when running the Best Practice Implementation. System Management Facility (SMF) messages will indicate any authorization issues with data sets, but will not halt the BPI implementation process. After running the implementation process, you can adjust your security rules and change the WARN parameter to NO, if you prefer not to run
Endevor
in warning mode. For more information about the WARN parameter, see The ESI Warning Mode in Securing.
Type Sequencing
By default, the BPI enables Type Sequencing. When this feature is enabled, API element actions (if wildcarded or masked) and SCL element actions are processed by a single Type sequence defined at the site level in the Type Sequence member created by the administrator.
To enable Type Sequencing during the BPI process, you define the type sequence order in the table T#GLBSEQ. Types and System names need to match those you specify in the T#TYPES and T#SYSTMS tables.
Best Practice Implementation Source Files
The
Endevor
BPI is delivered as part of the base product. All the BPI components reside in the following deployment libraries with other
Endevor
base members;
  • iprfx.iqual
    .CSIQSAMP
    Skeleton, model, and BPI processor members
  • iprfx.iqual
    .CSIQCLS0
    REXX procedures and REXX options statement members
  • iprfx.iqual
    .CSIQJCL
    Job control statement members
  • iprfx.iqual
    .CSIQDATA
    BPI input table members
The iprfx.iqual set of libraries is referred to as the deployment or runtime libraries. These are the libraries that contain the product software that is executed. These members are edited by the BC1JJB03 installation job as part of the installation process.
Run BPISTART
To start the BPI, you edit and submit the job, BPISTART.
Follow these steps:
  1. Set the WARN parameter to YES in the
    Endevor
    configuration table, BC1TNEQU.
    When performing the Best Practice Implementation, we recommend that you set the WARN parameter to YES in the
    Endevor
    configuration table, BC1TNEQU. When WARN=YES, the ESI warning mode is in effect. Warning mode allows access to resources even if your site security package (RACF,
    ACF2
    , or
    Top Secret
    ) indicates that access should be denied. You should use ESI Warning Mode when running the Best Practice Implementation. System Management Facility (SMF) messages will indicate any authorization issues with data sets, but will not halt the BPI implementation process. After running the implementation process, you can adjust your security rules and change the WARN parameter to NO, if you prefer not to run
    Endevor
    in warning mode. For more information about the WARN parameter, see The ESI Warning Mode in Securing.
  2. Locate BPISTART in the
    iprfx.iqual
    .CSIQJCL library.
  3. (Optional) Edit the SET LBPRFX=u
    prfx.uqual
    statement in BPISTART to override the uprfx and uqual values specified in the BC1JJB03 installation job.
  4. If a disk management utility such as DFSMS or
    Disk
    is not installed, edit the JCL to insert UNIT and/or VOL=SER parameters in the data set allocation statements to avoid a JCL error.
  5. Add a valid job card statement and submit the BPISTART job for execution.
    This job does the following:
    • Allocates the BPI libraries: uprfx.uqual.BPIDATA, uprfx.uqual.BPILIB, uprfx.uqual.BPIPRCR, and uprfx.uqual.BPIWRK.
      These libraries are modified during the BPI process. The delivered libraries is not be modified and thus is available for backup if the BPI process needs to be restarted for any reason.
    • Copies delivered and tailored members into the BPIDATA, BPILIB and BPIPRCR libraries.
    The following libraries are created with the uprfx.uqual values specified in the BPISTART job:
    • uprfx.uqual
      .BPIDATA
      Contains all the default input table members. This is a copy of the iprfx.iqual.CSIQDATA library. These tables are used to define the inventory structure (environments, systems, subsystems, types, processor groups, and so on.) to the BPI process jobs.
    • uprfx.uqual
      .BPILIB
      Contains several members copied from other installation libraries, JCL members built by the BPI process such as job #1TABLES - #9DEFTYP and several other files that are built by the BPI process, including the C1DEFLTS and ESYMBOLS configuration table source. This is the library the user works from to execute the BPI process jobs.
    • uprfx.uqual
      .BPIPRCR
      Contains the source for the delivered BPI
      Endevor
      processors. They are added into the Administrator environment by the #3ADMIN BPI job.
    • uprfx.uqual
      .BPIWRK
      Contains temporary and intermediate members built by one of the BPI jobs or steps and passed to another job or step later in the process. Examples include the SCL built by the process to DEFINE SYSTEMs and SUBSYSTEMs. Other members are placed into this library for support purposes in case any issues arise.
Customize the BPI Input Tables
A default set of BPI tables is copied into the BPIDATA library. These files determine the configuration using predefined best practice values. However, you must edit these tables as appropriate for your site.
Edit each member in the BPIDATA library depending on how you decide to configure your implementation. You can use conversion utilities, the ISPF Editor, upload from a word document, or other methods may be used to modify or create these required tables.
  • When editing tables, make sure that all changes conform to the table format rules
  • How you customize the input tables depends on how many times you plan to execute the BPI process
Input Table Format Rules
When you edit an input table, make sure to conform to the following rules.
  • Heading row
    • One heading row (single asterisk in column 1) must exist in each table.
    • The heading row must be coded prior to any data rows.
    • The format of the delivered heading rows must not be changed in any way.
  • Data rows
    • All values in the data rows must be entered in upper case mode unless otherwise stated.
    • All values are required unless otherwise stated.
    • The data in the data rows must be placed in the same columns as the field literal in the heading row.
  • Comment rows
    • Comment rows can be added anywhere within the table source by placing asterisks in columns 1-2 of a row. When detected the row is ignored.
T ADMALL--Allocations for Admin Environment
The T#ADMALL table allocates data sets for the ADMIN environment. This table enables the creation of the following data sets for each element type listed in the table.
  • One DELTA, LISTLIB, LLISTLIB, LOADLIB, and OBJLIB library for each element type for the ADMIN environment.
  • One base library for each element type for each system, subsystem, environment, stage. Each base library has the following name format:
    adminprfx..&C1SY..&C1SU..&C1EN(1,3)&C1S#.
    typename
    • typename
      Specifies a language version.
Edit this table as follows:
  1. Add or remove element type rows to include the language types that are used at your site. The type names appear in the table Node column.
  2. Do not change the type names for PROCESS, TABLE, DELTA, LISTLIB, LLISTLIB, LOADLIB or OBJLIB, because these have a specific meaning to
    Endevor
    and must not be altered. For these types, unless you are changing the format of the DELTA, LISTLIB, or LLISTLIB libraries, limit your changes to the Sizeunit, Primary, Secondary, and Directory.
  3. (Optional.) To define ELIB BDAM data sets for DELTA, LISTING, and LLISTING data sets, specify the following values:
    The #OPTION member DELTA and LISTLIB data set format must be the same as the format specified in the T#ADMALL member. By default, the DELTA, LISTLIB and LLISTLIB are created as ELIB BDAM. You can leave them as is, or can change them to PDS or PDSE by editing the table.
    For more information about ELIB BDAM data sets, see Administrating.
    PrimPages -- Specifies the number of primary pages for the ELIB initialization program to allocate. The value of this parameter is placed into the ALLOCATE PAGES parameter;
    ALLOCATE PAGES = (&PrimPages,&SecdryPages)
    SecdryPages -- Specifies the number of secondary pages for the ELIB initialization program to allocate. The value of this parameter is placed into the ALLOCATE PAGES parameter;
    ALLOCATE PAGES = (&PrimPages,&SecdryPages)
    ResrvePages -- Specifies the number of pages for the ELIB initialization program to reserve. The value of this parameter is placed into the RESERVE PAGES parameter;
    RESERVE PAGES = &ResrvePages
    DirPages -- Specifies the number of directory pages for the ELIB initialization program to allocate. The value of this parameter is placed into the DIRECTORY PAGES parameter;
    DIRECTORY PAGES = &DirPages
    The same types must be listed in the T#ADMALL andT#ADMTYP tables. If you add or remove type rows from any of these tables, you must make a corresponding change to the other tables.
T ADMSUB--SubSystem Names for ADMIN Environment
The T#ADMSUB table specifies the name of the subsystems for the ADMIN environment. The delivered table specifies the following:
  • System: ADMIN.
  • Subsystem: ENDEVOR.
  • Description:
    Endevor
    tables and processors.
Usually, no change is needed to this table.
The system names must be the same in each of these tables: T#ADMSYS and T#ADMSUB. If you add or remove a system row from the T#ADMSYS table, you must add or remove the associated rows in the T#ADMSUB table.
T ADMSYS--System Names for ADMIN Environment
This table specifies the ADMIN environment systems to be implemented. The delivered table specifies the following:
  • System: ADMIN.
  • Description:
    Endevor
    administration.
The system name is used to build the following processor output libraries.
The first system that is referenced in the table is used to build the processor output library names.
As delivered, the following tables are built:
adminprfx.ADMIN
.PROCESS.ADM1.LOADLIB
adminprfx.ADMIN
.PROCESS.ADM1.LISTLIB
adminprfx.ADMIN
.PROCESS.ADM2.LOADLIB
adminprfx.ADMIN
.PROCESS.ADM2.LISTLIB
  • system_name
    Specifies the name of the system in the ADMIN environment.
Usually, no change is needed to this table.
The system names must be the same in these tables: T#ADMSYS and T#ADMSUB. If you add or remove a system row from the T#ADMSYS table, add or remove the associated rows in the T#ADMSUB table.
T ADMTYP--Types for the ADMIN Environment
This T#ADMTYP table specifies the type definitions to be created in the ADMIN environment.
Edit this table as follows:
  1. Add or remove element type rows to include the language types that are used at your site.
  2. Do not change the type names for PROCESS or TABLE, because
    Endevor
    uses these to hold the
    Endevor
    processors and configuration tables and these must be set to the values provided.
The first processor group listed for each type is used as the default processor group for that type.
The same types must be listed in the T#ADMALL andT#ADMTYP tables. If you add or remove type rows from any of these tables, you must make a corresponding change to the other tables.
T ALLOC--Allocations for Non-ADMIN Environments
The T#ALLOC table allocates data sets for all environments except the ADMIN environment. The UNCLMED environment and the PRD environments apply an allocation factor specified in #OPTION to the values specified in this table.
This table enables the creation of the following data sets for each element type that is defined in the T#TYPES table.
  • One DELTA, LISTLIB, LLISTLIB, LOADLIB, and OBJLIB library for each element type for the application or standard environment.
  • One base library for each element type for each system, subsystem, environment, stage. Each base library has the following name format:
aprfx..&C1SY..&C1SU..&C1EN(1,3)&C1S#.typename
  • typename
    Specifies a language version.
Edit this table as follows:
  1. Add or remove element type rows to include the language types used at your site. The type names appear in the table Node column.
  2. Do not change the type names for PROCESS, TABLE, DELTA, LISTLIB, LLISTLIB, LOADLIB or OBJLIB, because these have a specific meaning to
    Endevor
    and must not be altered. For these types, unless you are changing the format of the DELTA, LISTLIB, or LLISTLIB libraries, limit your changes to the Sizeunit, Primary, Secondary and Directory.
  3. (Optional.) Specify the following values to define ELIB BDAM data sets for DELTA, LISTING, and LLISTING data sets: (ELIB BDAM is the default.)
    • PrimPages
      Specifies the number of primary pages for the ELIB initialization program to allocate. The value of this parameter is placed into the ALLOCATE PAGES parameter;
      ALLOCATE PAGES = (&PrimPages,&SecdryPages)
    • SecdryPages
      Specifies the number of secondary pages for the ELIB initialization program to allocate. The value of this parameter is placed into the ALLOCATE PAGES parameter;
      ALLOCATE PAGES = (&PrimPages,&SecdryPages)
    • ResrvePages
      Specifies the number of pages for the ELIB initialization program to reserve. The value of this parameter is placed into the RESERVE PAGES parameter;
      RESERVE PAGES = &ResrvePages
    • DirPages
      Specifies the number of directory pages for the ELIB initialization program to allocate.. The value of this parameter is placed into the DIRECTORY PAGES parameter;
      DIRECTORY PAGES = &DirPages
The #OPTION member affects the UNCLMED environment and the PRD environments as follows:
  • The ProductionSizeFactor specified in the #OPTION member in the uprfx.uqual.BPILIB library is applied to the
    production environment
    allocations, by the #5ALLOC job, when building the allocation statements. For example, if you specify a Primary value of 50 for the ASMPGM base library and the ProductionSizeFactor value is 3, the data set is allocated with 150 primary cylinders. This factor is also applied to the Secondary and Directory columns when processing the production environment. The ProductionSizeFactor is skipped when allocating ELIB DELTAs or LISTINGs.
  • The UnclaimedSizeFactor specified in the #OPTION member in the uprfx.uqual.BPILIB library is applied to the
    unclaimed environment
    allocations, by the #4UNCLM job, when building the allocation statements. For example, if you specify a Primary value of 40 for the ASMPGM base library and the UnclaimedSizeFactor value is 3, the data set is allocated with 120 primary cylinders. This factor is also applied to the Secondary and Directory columns when processing the unclaimed environment. The UnclaimedSizeFactor is skipped when allocating ELIB DELTAs or LISTINGs.
T ENVMTS--Environment and Stage Names
The T#ENVMTS table specifies the environments and stages to be created.
As delivered the implementation creates the following environments and stages:
Envname
Stg1ID
Stg1nme
Stg2ID
Stg2nme
Entrystg#
NextEnv
NextStgID
ADMIN
1
ADMIN1
2
ADMIN2
1
DEV
1
DEV1
2
DEV2
1
QAS
2
QAS
1
QAS1
2
QAS2
1
PRD
2
PRD
1
PRD1
2
PRD2
1
UNCLMED
1
UNCLMED1
2
UNCLMED2
2
ARCHIVE
1
ARCHIVE1
2
ARCHIVE2
2
EMER
1
EMER1
2
EMER2
1
PRD
2
Edit this table as follows:
  1. Add or remove environment rows to include the environments used at your site. All values in the data rows must be entered in upper case character mode. The first three characters of the environment name are used to build data set names. Therefore, the first three characters of the names must be unique across environments. If the environment names do not contain three characters, a pad character ($) is added to the environment name when allocating the data sets for that environment.
  2. Do not change the environments names for ADMIN, PRD, UNCLMED, or ARCHIVE, unless you have business reason to do so. If you change these, you must also change the name in the O#ENVMTS REXX member, located in the uprfx.uqual.BPILIB data set. The purpose of this member is to identify which of the environments is the administrator, production, unclaimed element and archive element environments.
  3. If you decide you do not need the UNCLMED environment, comment out the UNCLMED row in this table prior to executing the #1TABLES job. Job #1TABLES builds the C1DEFLTS table.
    Also skip the execution of the #4UNCLM job.
T GLBSEQ--Type Sequence Member
The T#GLBSEQ table contains the information required to create the type sequence member, GLBLTYPE in the uprfx.uqual.PARMLIB.
Endevor
uses this PARMLIB member to determine the order of type processing. This table is used with the T#ADMTYP and T#TYPES tables. If data rows are added or removed from these tables, the T#GLBSEQ should also be reviewed to see if changes are required.
Only types that must be executed in a specific sequence should be included in this table. Do not include types such as JCL and PROCS in this table. Following this rule results in more efficient throughput from the current action processing feature.
T LIBRYS--Allocations for Site-Wide Data Sets
The T#LIBRYS table allocates
Endevor
data sets that are used site-wide. The purpose of this model is to identify the fully qualified names of these data sets. The values in the Node column are used as the last qualifier of the fully qualified data set name as shown next:
  • ACMROOT
    ACM root and data sets.
  • ACMXREF
    Cross-reference data sets.
  • ELMCATL
    Element catalog data sets.
  • ELMCATL.EINDEX
    Element catalog index data sets.
  • PACKAGE
    Package file.
  • PARMLIB
    Parameter library.
  • MCF
    Master Control File for each environment-stage combination.
Do not add or remove any rows from this table, however, you should review the type of data set specified in the MODEL column and the data set size attributes.
It is highly recommended that you do not change the Node, MODEL or TBLOUT values in this table. DO NOT change the MCF name. If you have a business reason to change one of the other node names, you must also change the name in the O#LIBRYS REXX model, located in the iprfx.iqual.CSIQCLS0 data set.
T SUBSYS--Subsystem Names for All Environments Except All Standard or Application Environments
The T#SUBSYS table names the Subsystems for each System and provides a description of each Subsystem for all environments except the ADMIN and UNCLMED environments.
Edit this table as follows:
  1. Change the default to the Systems and Subsystems appropriate for your business model.
  2. Add or remove corresponding rows in the T#SYSTMS table, if you changed the T#SUBSYS table in step 1.
The default subsystem names match the sample application.
T SYMBLS--Symbol Names for All Environments Except ADMIN and UNCLMED
The T#SYMBLS table contains all the symbol overrides to be defined for the standard or application environments.
This table contains the symbol overrides to be defined for the standard environments. You must specify the type, processor group, environment, stage, processor type, symbol, and override value for each row in the table. You can wildcard the processor group, environment, and Stg# columns. However, no partial wildcarding is supported for the environment or stage column.
The stage column if wildcarded, creates symbol definitions for stage 1 and stage 2.
The environment column if wildcarded, creates symbol definitions for all environments (DEV, QAS, PRD, EMER) except for ADMIN, UNCLMED, and ARCHIVE. They are excluded because the Administrator environment has symbol creation steps in #3ADMIN, and the Unclaimed and Archive environments set processors to *NOPROC*. However, you may define symbols for any of the environments by creating a unique row for that location in the table, placing the environment name directly in the Envname column. In other words, although the wildcarding feature excludes the Administrator environment, you can still create symbols for that environment using this table, by placing ADMIN in the Envname column.
All symbol definitions with wild carded environments is created first, followed by specific symbol definitions, allowing for additional flexibility when establishing the symbol rows. There are many processor symbolic overrides being created, as delivered. You can delete or add additional rows to the symbol table as needed.
T SYSTMS--System Names for Standard or Application Environments
The T#SYSTMS table contains all the environment systems to be implemented. This table comes preset with values from the Endevor Sample Application. All values in the data rows must be entered in upper case character mode except for the description, which can be entered in mixed mode.
This table is related to the T#SUBSYS table. If you add or remove a system row from the T#SYSTMS table, you must add or remove the associated rows in the T#SUBSYS table.
T TYPES--Types for Non-ADMIN Environments
The T#TYPES table contains the types to be created within the DEV, QAS, PRD, EMER, ARCHIVE and UNCLMED environments.
Do not alter the values in the PROCESS rows. This type is used to hold the
Endevor
processors and must be set to the values provided.
If type definition rows are added or removed from the T#TYPES table, the corresponding row must be added or removed from the T#ALLOC table. The T#GLBSEQ table should also be reviewed to determine if rows must be added or removed from that table.
Prepare the BPI Job Card
Edit the #JOBCARD member in the uprfx.uqual.BPILIB library so the information conforms to your site standards. Do not alter the title. The &TBLOUT symbol resolves to the job name.
//[email protected] JOB (#########),'BPI &TBLOUT ', // CLASS=A,MSGCLASS=X,MSGLEVEL=(1,1), // NOTIFY=&SYSUID
The job card is ready for use by the BPI jobs.
When the #0SETUP job is executed, this job card is automatically placed at the beginning of each of the other BPI jobs.
After the BPISTART job is executed, the remaining BPI process is executed from the BPILIB library.
Define Symbol Values for BPI Jobs
To define values for variables used by the BPI process to complete the configuration, you edit the #OPTION member. These values are used to resolve variables that are defined in BPI models and REXX members.
Edit the uprfx.uqual.BPILIB(#OPTION) member and answer all the questions. The questions are in the format of REXX comments and the answers are in the format of REXX statements. These statements are used as symbol values during the implementation process. For example, many of the C1DEFLTS table site parameter values are derived from the information specified in this member. The literals on the left side of the equal symbols are REXX variables and must remain in mixed character mode. The values you enter on the right side of the equal symbols are data values and must be entered in upper case character mode, unless otherwise stated; for example, comments, descriptions and notes can be entered in mixed character mode.
Submit BPI Jobs
You run the BPI as a set of jobs that use information in the input tables and the #OPTION member. The first job you submit is the #0SETUP job, which builds the other jobs that you must submit. All the jobs are located in the BPILIB library and must be run in the specified order. Some of these jobs build additional jobs. These additional jobs are submitted automatically, if the #OPTION member SubmitJob parameter is Y. Submit the jobs to complete the set up.
Follow these steps:
  1. Submit the setup job, #0SETUP.
    Checks for the existence of data sets and builds and tailors additional jobs. This job builds nine additional jobs and saves them into the uprfx.uqual.BPILIB library. This job checks for the existence of the 
    Endevor
     site-wide data sets it is about to allocate. If any of the data sets exist, the job terminates with a return code of 12 and a report is produced to indicate which of the data sets already exists. The purpose of this check is to ensure the data sets are not accidentally deleted.
    The #0SETUP job also builds additional BPI jobs. Jobs that are built by the setup job are also stored into the BPILIB library. The #JOBCARD you coded is copied to the beginning of each of these jobs.
  2. Submit the #1TABLES job.
    This job builds, assembles and link-edits the C1DEFLTS and ESYMBOLS tables. No additional jobs are created by this job. This job also assembles and link-edits the ENCOPTBL and ENDICNFG configuration tables.
  3. Submit the #2LIBRYS job.
    Allocates Endevor Site-wide Data sets. Builds the type sequence member and saves it into the PARMLIB. This job builds one additional job.
  4. Submit the #3ADMIN job.
    Creates the entire ADMIN Environment. Adds processors and configuration tables. This job builds four or five additional jobs, depending on the allocation specifications.
  5. Submit the #4UNCLM job.
    Creates the entire UNCLMED Environment. This job builds four or five additional jobs, depending on allocation specifications.
  6. Submit the #5ALLOC job.
    Allocates all Endevor Application Data sets. This job builds additional jobs depending on the number of system/subsystem combinations specified in the T#SUBSYS BPI table.
  7. Submit the #6DEFSYS job.
    Defines Systems for the DEV, QAS, PRD, EMER and ARCHIVE Environments. This job builds one additional job.
  8. Submit the #7DEFSUB job.
    Defines Subsystems for the DEV, QAS, PRD, EMER and ARCHIVE Environments. This job builds one additional job.
  9. Submit the #8DEFTYP job.
    Defines Types for the DEV, QAS, PRD, EMER and ARCHIVE Environments. It also defines Processor Symbols for any of the environments specified. This job builds one additional job.
  10. Submit the #9DEFGRP job.
    Defines processor groups for the DEV, QAS, PRD, EMER and ARCHIVE Environments. It also defines processor symbols for any of the environments specified.
  11. Manually delete the
    uprfx.uqual
    .BPIWRK library after every iteration of the BPI process. The BPIWRK data set provides no value once the implementation is complete.
Iterative BPI Process
We recommend that you execute the BPI process in iterations. For the first iteration, you might implement one System (or application). This lets you become familiar with how to edit the input tables and how the jobs work. After the first iteration, you could execute the BPI to implement an entire application (an application can consist of multiple Systems and Subsystems). Then you could do additional iterations for each additional application. For the first iteration, you perform all the steps. For subsequent iterations, you re-edit the BPI input tables and then rerun the jobs beginning with job #5ALLOC.
For the first iteration, do the following:
  1. Submit BPISTART.
  2. Complete all the BPI input tables.
  3. Edit the #JOBCARD.
  4. Edit #OPTION to enable symbolic substitution.
  5. Execute the BPI jobs #0SETUP through #9DEFGRP, and submit the additional jobs that get created.
For the second and subsequent iterations, do the following:
  1. Edit the values in the tables.
  2. Execute BPI jobs #5ALLOC through #9DEFGRP, and submit the additional jobs that get created.
  3. Repeat these steps as many times as needed to add all the Systems you want to put under the control of
    Endevor
    at this time.