Runtime Configurations

This section explains the concept of an ISPW runtime configuration (RTConfig). It also lists the RTConfig definitions provided with ISPW, then discusses the WZZRC and WZZRCCNF allocation modules. Miscellaneous considerations in defining and using RTConfigs are also presented, followed by an annotated sample of WZZRCCNF.

Overview of Runtime Configuration

Many ISPW operations make use of a combination of REXX, CLISTs, programs, panels, and skeletons. Some of these are base code supplied with ISPW, some are customized versions created by the customer, and some are new programs, panels, CLIST/REXX, etc. used to extend the functionality of ISPW.

A good example of this is the Generate operation that compiles a source file and possibly runs a link-edit to create a program load module. In the Generate, there is often a compile options panel and some skeleton JCL used by CLISTs and REXX to build and submit the Generate job. ISPW ships with basic panels, skeleton JCL, and CLIST/REXX routines for the Generate. However, every customer will have a need to customize some or all of these. Additional customization will occur over time as the customer environment and ISPW product usage changes. Since ISPW is an SCM, customers will actually use ISPW to manage the site customization of ISPW. They do this using a pre-defined application called SITE that is created during the ISPW installation process. Panels, skeletons, CLISTs, REXX, and other ISPW component types are checked out to the TEST level in the SITE application, modified, then promoted up through the lifecycle to HOLD and on to PROD. If the customer’s ISPW environment allocates the SITE PROD level datasets ahead of the BASE datasets that ship with ISPW, then ISPW users will get the SITE customized version of panels, REXX, etc.

The challenge is: How can customized versions be tested before they are promoted to the PROD level in the SITE application, thus propagating them to all ISPW users? You could create some CLISTs to set a TSO user’s allocation order to put the SITE TEST or HOLD level ahead of the PROD level and ISPW BASE datasets, but this will not affect operations that are run under a Set Processor (ISPW/SX task).

The solution (introduced in ISPW 4.4) is to enable the customer to create a set of runtime configuration (RTConfig) definitions. Each RTConfig will have a unique name and a set of dataset allocations in a specific order. When an ISPW user specifies an RTConfig, they are selecting a set of runtime dataset allocations. The RTConfig value will be passed through to the Set Processor for any sets they use for operations. Most ISPW users will simply use the default RTConfig for everything they ever do. If, however, they need to test a site customization before it is promoted to the PROD level in the SITE application, they can use an RTConfig name that will be provided by their ISPW administrator.

The RTConfig is also used to define the dataset allocations used for any ISPW test environment that a customer may set up.

Default RTConfig Definitions

The default set of RTConfig definitions that are created during a standard ISPW installation are:

• ISPP – Defines the production ISPW dataset allocations. Most users will always use this.
• ISPPHOLD – Defines the production ISPW with the SITE HOLD datasets ahead of the SITE PROD and ISPW BASE datasets.
• ISPT – Defines the test ISPW dataset allocations.
• ISPTHOLD – Defines the test ISPW with the SITE HOLD datasets ahead of the SITE PROD and ISPW BASE datasets.
• ISPTTEST – Defines the test ISPW with the SITE TEST and HOLD datasets ahead of the SITE PROD and ISPW BASE datasets.

A customer is free to replace or add to these definitions. RTConfig names can be up to eight characters and must be unique within the customer’s site.

Many customers will only make use of this default set of RTConfig definitions. However, larger customers—or those with more complicated environments—will likely add their own RTConfig definitions. There is no limit to the number of definitions that can exist.

ISPW Allocations Modules WZZRC and WZZRCCNF

The allocations definition table WZZRCCNF, introduced in ISPW 4.4, contains the various dataset allocations for different ISPW systems and configurations. Different configuration entries, identified by their name, can be defined, and they can each specify different dataset names. Configurations can be defined for PROD and TEST ISPW systems, allowing test datasets to be concatenated in front of production datasets, fix datasets to be concatenated in front of production datasets, and so on.

All ISPW clients now use the load module resulting from the assembly and link of this table for their dataset allocations. This allows any Set or Deploy process—as well as an ISPW step in a submitted batch job—to use the same allocations that the ISPW client is using.

The allocations are actually performed by the load module WZZRC, which has six aliases/entry points. Never execute WZZRC directly, but always use the appropriate entry point. The descriptions in this appendix will refer to WZZRCxxx. The entry points are described in detail later in this appendix. WZZRC and its six alias names must be copied to a LINKLIST dataset that is APF authorized. This is because it can be used to invoke IKJEFT01, which must run APF authorized.

The WZZRCCNF table source must be updated to match your ISPW configuration dataset structure and must include the appropriate DD names and dataset names. The table must be assembled and linked, and the resulting load module must be placed in a LINKLIST dataset. This can be the authorized LINKLIST dataset which contains WZZRC.

WZZRCxxx is passed a configuration name. It loads WZZRCCNF, looks up the configuration, and allocates the appropriate datasets. It then passes control to the appropriate program, CLIST, or REXX EXEC.

Module WZZRCCNF

WZZRCCNF contains a series of connected tables used to define datasets to be allocated. The following eight Assembler macros described in this section are used to create the tables:

• WZZRCCON
• WZZRCSEQ
• WZZRCLVL
• WZZRCDD
• WZZRCDSN
• WZZRCSYS
• WZZRCTMP
• WZZRCTRC

WZZRCCON

WZZRCCON is the starting point for a configuration entry. The parameters are:

NAME=Name of the configuration entry.

WZZRCTMP

WZZRCTMP identifies a set of temporary dataset allocation settings. The label (in columns 1 to 8) of the statement is the name of the set (see TEMPDS under WZZRCDSN).

UNIT=

Unit name to be used (for example, UNIT=SYSDA).

STORCLAS=

SMS storage class (for example, STORCLAS=SMS).

SPACE=

Same as SPACE= in JCL (for example, SPACE=(TRK,(1,1,1)).

DCB=

Same as DCB= in JCL (for example, DCB=(RECFM=FB,LRECL=80,BLKSIZE=3120)).

WZZRCTRC

WZZRCTRC identifies a set of trace control statements. The label (in columns 1 to 8) of the first statement in a set is the name of the set (see TRCDEF under WZZRCCON). The label field of the second and subsequent trace statements in a set should be left blank. Multiple sets can be specified. You should include a label on the first statement in any additional sets.

The parameter to the statement is a quoted string containing a standard ISPW trace control statement.

Module WZZRC

Module WZZRC has multiple aliases and corresponding entry points. All aliases expect a parameter of the configuration name. WZZRCSPF expects only the configuration name. All of the others except WZZRCJCL expect the configuration name to be followed by a slash, and then a program, TSO command, CLIST member name, or REXX EXEC name that is to be executed, followed by any parameters that are to be passed to it.

WZZRCSPF

WZZRCSPF is used in foreground TSO when already in ISPF. It does not allocate the TEMP level or SYSTEM level datasets. It starts ISPW as a new ISPF application by executing:

SELECT CMD(WZZRCSPF xxxxxxxx) NEWAPPL(yyyy) NOCHECK PASSLIBwhere xxxxxxxx is the name of the appropriate runtime configuration entry and yyyy is the new APPL within ISPF to be used to run WZZRCSPF.

WZZRCSPF can be used to invoke a standalone REXX exec outside of ISPW. For example, this could be for situations where Deploy Packages need to be released by operations.

Execute the following command to allocate the libraries for the configname and execute the REXX exec.

On exit from the REXX exec, the libraries will be freed.

WZZRCBAT

WZZRCBAT is used in background tasks (batch jobs, started tasks) where ISPW will be run in batch ISPF (for example, ISPWSX and ISPWRX). It allocates all datasets.

WZZRCTSO

WZZRCTSO is used in background tasks (batch jobs, started tasks) where TSO commands will be run. It only allocates SYSEXEC, SYSPROC, and ISPLLIB datasets (using DD name TASKLIB).

WZZRCJOB

WZZRCJOB is used in background tasks (batch jobs, started tasks) where a program needs to execute (for example, WZZBP). It only allocates ISPLLIB datasets (using DD name TASKLIB).

WZZRCCMD

WZZRCCMD is used in foreground TSO where a batch utility program is being run in the foreground (for example, REXX EXEC WZZA### running WZZRLB). No allocations are performed. It starts ISPW as a new ISPF application by executing:

SELECT CMD(WZZTS) NEWAPPL(xxxx) PASSLIBwhere xxxx is the new APPL within ISPF to be used to run WZZRCCMD.

WZZRCJCL

WZZRCJCL is used in test mode. Pseudo JCL is written to DD WZZALLOC. If the configuration name is followed by a slash, what follows the slash identifies the entry point it is to simulate (for example, WZZRCSPF or WZZRCBAT, etc.).

Additional Considerations

This section contains miscellaneous information about defining and using RTConfigs.

Removing Hardcoded DDNAMES

If any skeletons or PROCLIB members are updated to use WZZRCxxx, any hardcoded DDNAMEs that will be allocated (STEPLIB, SYSPROC, SYSEXEC, etc.) should be removed. Skeletons processed by ISPF file tailoring get access to the client’s current configuration name using the ISPF variable WRTCONF (see skeleton WZU@TSO in SAMPLIB). Started tasks, such as SX and RX, are passed the client’s current configuration name in the start command using the parameter RTCONF (see PROCLIB member WZISPWSX in SAMPLIB).

Executing WZZRCBAT or WZZRCTSO and IKJEFT01

When executing WZZRCBAT or WZZRCTSO and IKJEFT01, there are multiple techniques you can use. The following examples all run WZZRCBAT and the LISTALC command with a parameter of STATUS (list all allocations showing DDNAME and disposition).

It is important to note that if IKJEFT01 is passed a parameter, it will attempt to execute it, treating it as a command, CLIST, or REXX EXEC.

WZZALLOC and Pseudo JCL

If a DD card //WZZALLOC is included when executing WZZRCSPF, WZZRCBAT, WZZRCTSO, or WZZRCJOB, pseudo JCL will be generated that reflects the allocations performed.

WZZDEBUG and Debugging Information

If a DD card //WZZDEBUG is included, debugging information is generated. It is displayed on the terminal in ISPF using TPUT, and is displayed in the JOBLOG for started tasks and batch jobs using WTO. You can see each dataset being allocated, then the DDNAMEs being concatenated. This DD card can be a DUMMY DD because nothing is written to it.

WZZRCTMP and Temporary Datasets

If the same WZZRCTMP definition is used in multiple WZZRCDD statements (for example, ISPTLIB and ISPTABL), the same temporary dataset will be used in the second and subsequent allocations, as long as it is allocated to real DASD and not VIO.

Enqueues and Table Updates

ISPF serializes updates to tables (ISPTABL DD) by issuing an exclusive enqueue for the first DSNAME in the ISPTLIB concatenation. If the first dataset is a permanent dataset, problems can occur. For example, if two users attempt to update a table at the same time, the second enqueue will fail and the update will be rejected, causing the job to fail. In ISPF, the user’s profile is supposed to be the first dataset in the ISPTLIB concatenation, and therefore no enqueues should collide. In batch and started tasks, BMC Software suggests that a temporary dataset be allocated as the first dataset in the ISPTLIB concatenation. ISPW guarantees that the temporary dataset is unique (it includes the job number in hexadecimal). The best way to ensure a temporary dataset is on the front of the ISPTLIB concatenation is to use the new level TEMP. The level only needs one DD name, ISPTLIB, and one dataset, TEMPDS=TABLES. This level is not used by WZZRCSPF.

WZZRCDSN and Real DDNAMEs

When using the DD= parameter on the WZZRCDSN macro, complications can arise if the DDNAME is the real DDNAME we need to use (for example, ISPLLIB). To do this, you must have SITE datasets. Because the required DDNAME is already in use, it must be concatenated onto something (for example, the BASE datasets), at which point it “disappears”. Then, when allocating the SITE datasets, we can use the real DDNAME for the SITE dataset(s) and concatenate the temp DDNAME that holds all the datasets previously allocated (for example, BASE and SYSTEM) after it.

SYSNAME Restriction of z/OS Images

If you use SYSNAME lists to restrict configurations to certain z/OS images, you can define multiple configurations with the same name, but use different datasets on the different z/OS images. This means you can share the one copy of WZZRCCNF. This would allow a user on ZOS1 to trigger a task on ZOS2 which uses the same configuration name but uses different datasets (different naming conventions on the different z/OS images). Note that this does require that each z/OS image have a unique &SYSNAME value.

SYSNAME and Multiple Configurations

When defining multiple configurations with the same name, if some are restricted by SYSNAME= while one is not, the configuration without the SYSNAME= should be positioned after the others. That ensures it will be selected only when the others have been rejected (current &SYSNAME is not on the list(s)).

DD Name Allocation Requirement

Currently, WZZRCxxx requires that at least one dataset is defined to be allocated to the following DD names:

• SYSPROC
• ISPLLIB
• ISPMLIB
• ISPPLIB
• ISPSLIB
• ISPTLIB
• ISPPROF
• ISPTABL
• WZ@RW
• WZ@WW

There is an exception to this requirement: If no datasets are defined to be allocated, but the DD name is already allocated, ISPW will use the existing allocation.

This allocation requirement can cause problems at some sites. If tasks are being initiated on multiple systems (for example, for Deploy), and you know that some DDs are not going to be used (for example, WZ@RW and WZ@WW)—or maybe the datasets do not even exist on the remote systems—there are several ways to deal with this situation:

• You can define two configurations with the same name, limit the first configuration to the main system(s) where ISPW is running using the SYSNAME= parameter, and not specify SYSNAME= on the second configuration. In the first configuration, include normal definitions for WZ@RW and WZ@WW. In the second configuration, you can specify temporary datasets instead, using a WZZRCTMP definition created specifically for this purpose.
• You can define two configurations with the same name, limit the first configuration to the main system(s) where ISPW is running using the SYSNAME= parameter, and not specify SYSNAME= on the second configuration. In the first configuration, include normal definitions for WZ@RW and WZ@WW. In the second configuration, you can specify a dataset name of NULLFILE, in which case a dummy dataset will be allocated.
• You can create multiple WZZRCCNF tables which allocate the appropriate different datasets and use the different tables on the various z/OS images. This is an effective solution, but it does require that multiple table sources be updated if any changes are required.

Merging Multiple Sequences

It is possible to define multiple sequences that merge at a level. The first sequence should include all the levels. The second and subsequent sequences should only list the unique levels and the level where they merge. For example, if two sequences are A1 ® B ® C and A2 ® B ® C, you would specify WZZRCSEQ LIST=(A1,B,C) and WZZRCSEQ LIST=(A2,B). A warning message will be issued at assembly time for the second sequence stating “this sequence shares entries with a prior sequence.”

VIO Datasets

Some of ISPW’s REXX EXECs have trouble working with VIO datasets (for example, LISTDSI does not support VIO datasets). All temporary datasets allocated by WZZRCxxx should be allocated on real DASD. If VIO is allocated, a warning message is issued and execution continues. Temporary VIO datasets cannot be shared between multiple DD names because ISPW needs a VOLSER to reuse the same dataset, and VIO datasets do not have a VOLSER.

Testing WZZRCCNF and WZZRCxxx Updates

To test updates to WZZRCCNF and/or WZZRCxxx, you can create special JCL which includes a //JOBLIB DD or //STEPLIB DD pointing to a load library containing the appropriate version of WZZRC, its six aliases, and the appropriate version of WZZRCCNF. This load library must include WZZRC, even if you are only testing an updated version of WZZRCCNF. If z/OS loads WZZRCxxx from the LINKLIST, it will also load WZZRCCNF from the LINKLIST (if your JOBLIB/STEPLIB is not APF-authorized), thus ignoring your updated WZZRCCNF in your JOBLIB or STEPLIB. This situation is related to the way z/OS handles multiple load modules when some are APF-authorized (WZZRC and its aliases) and some are not (WZZRCCNF).

Annotated Sample WZZRCCNF

The following series of figures presents a sample WZZRCCNF with each figure followed by an explanation.

WZZRCCNF – Prologue

The following figure depicts a standard Assembler prologue.

WZZRCCNF – Production Configuration Definitions

In the preceding figure, two production ISPW configurations are defined:

• ISPP is the default configuration and uses the following levels:
  • SITEPROD – production site datasets
  • BASEPROD – production base datasets
  • SYSTEM – standard system datasets
  • WZ@TBLS1 – ISPW .M and .O tables datasets
  • TEMPTLIB – temporary ISPTLIB dataset.
• ISPPHOLD uses the following levels:
  • SITEHOLD – hold site (production site datasets too)
  • BASEPROD – production base datasets
  • SYSTEM – standard system datasets
  • WZ@TBLS1 – ISPW .M and .O tables datasets
  • TEMPTLIB – temporary ISPTLIB dataset.

WZZRCCNF – Test Configuration Definitions

In the preceding figure, the following six test ISPW configurations are defined:

• ISPT uses the following levels:
  • SITEPROD – production site datasets
  • BASETEST – test base datasets
  • SYSTEM – standard system datasets
  • WZ@TBLS1 – ISPW .M and .O tables datasets
  • TEMPTLIB – temporary ISPTLIB dataset.
• ISPTFIX uses the following levels:
  • SITEPROD – production site datasets
  • BASETESTFIX – test base fix datasets (test base datasets too)
  • SYSTEM – standard system datasets
  • WZ@TBLS1 – ISPW .M and .O tables datasets
  • TEMPTLIB – temporary ISPTLIB dataset.
• ISPTHOLD uses the following levels:
  • SITEHOLD – hold site (production site datasets too)
  • BASETEST – test base datasets
  • SYSTEM – standard system datasets
  • WZ@TBLS1 – ISPW .M and .O tables datasets
  • TEMPTLIB – temporary ISPTLIB dataset.
• ISPTTEST uses the following levels and definitions (applicable to z/OS images on list SYSLIST, namely ZOS1, ZOS2, and ZOS3):
  • SITETEST – test site (hold and production site datasets too)
  • BASETEST – test base datasets
  • SYSTEM – standard system datasets
  • WZ@TBLS1 – ISPW .M and .O tables datasets
  • TEMPTLIB – temporary ISPTLIB dataset
  • SYSLIST – List of z/OS &SYSNAME values.
• ISPTTEST uses the following levels and definitions (applicable to all other z/OS images):
  • SITETEST – test site (hold and production site datasets too)
  • BASETEST – test base datasets
  • SYSTEM – standard system datasets
  • WZ@TBLS2 – ISPW .M and .O tables datasets
  • TEMPTLIB – temporary ISPTLIB dataset
• ISPTTRC uses the following levels and definitions:
  • SITETEST – test site (hold and production site datasets too)
  • BASETEST – test base datasets
  • SYSTEM – standard system datasets
  • WZ@TBLS1 – ISPW .M and .O tables datasets
  • TEMPTLIB – temporary ISPTLIB dataset
  • TRACEDEF – ISPW trace definitions

WZZRCCNF – Temporary Dataset Level Sequence

Define the sequence of one temporary dataset level, TEMPTLIB, to be used when allocating ISPTLIB. The definition shown in the preceding figure specifies just one DDNAME, ISPTLIB, and just one dataset, which uses the TABLES temporary dataset definition. This dataset will be allocated in front of any ISPTLIB dataset(s) defined at the SITE, BASE, and SYSTEM levels.

WZZRCCNF – Site Sequence Level Definitions

Define the sequence of three site levels as shown in the preceding figure: SITETEST followed by SITEHOLD followed by SITEPROD. When SITETEST is used, SITEHOLD and SITEPROD will also be used. When SITEHOLD is used, SITEPROD will also be used. Define the levels as follows:

• Define the SITETEST level, specifying the DDNAMEs and DSNAMEs.
• Define the SITEHOLD level, specifying the DDNAMEs and DSNAMEs.
• Define the SITEPROD level, specifying the DDNAMEs and DSNAMEs.

WZZRCCNF – Tables Sequences

In the preceding figure, four separate sequences of tables levels are defined for the ISPW .M and .O tables. WZ@TBLS1 and WZ@TBLS2 are used in some configurations, but WZ@TBLS3 and WZ@TBLS4 are not used in any configurations and are included for demonstration purposes only. Define the table sequences as follows:

• Define the WZ@TBLS1 level, specifying the two DDNAMEs and corresponding DSNAMEs. Configuration ISPTTEST uses this level on z/OS images ZOS1, ZOS2, and ZOS3.
• Define the WZ@TBLS2 level, specifying the two DDNAMEs and corresponding DSNAMEs. Configuration ISPTTEST uses this level on z/OS images other than ZOS1, ZOS2, and ZOS3.
• Define the WZ@TBLS3 level, specifying the two DDNAMEs and corresponding temporary datasets. No configurations use this level. It is included for demonstration purposes only.
• Define the WZ@TBLS4 level, specifying the two DDNAMEs and corresponding dummy datasets. No configurations use this level. It is included for demonstration purposes only.

WZZRCCNF – Production Base Level Sequence

The sequence of one production base level, BASEPROD, for the production ISPW  base datasets is defined in the preceding figure. The BASEPROD level is defined here by specifying the DDNAMEs and corresponding DSNAMEs.

WZZRCCNF – Test Base Level Sequence

The sequence of two test base levels, BASETESTFIX and BASETEST, for the test ISPW base datasets is defined in the preceding figure. Define the levels as follows:

• Define the BASETESTFIX level, specifying the DDNAMEs and corresponding DSNAMEs.
• Define the BASETEST level, specifying the DDNAMEs and corresponding DSNAMEs.

WZZRCCNF – System Level Sequence

In the preceding figure, the sequence of one system level called SYSTEM (for the standard ISPF system datasets) is defined. To define the SYSTEM level, specify the DDNAMEs and corresponding DSNAMEs. These are the standard ISPF datasets that are typically allocated in a TSO logon proc or in a CLIST run immediately after logon.

WZZRCCNF – Temporary Dataset Allocation Settings

The preceding figure illustrates how to define the following three sets of temporary dataset allocation settings:

• TABLES is used for the temporary ISPTABL dataset and the temporary ISPTLIB dataset that is concatenated in front of any other ISPTLIB datasets. If multiple WZZRCDSN macros use the same WZZRCTMP settings, then they use the same dataset, which is the desired behavior for ISPTABL and ISPTLIB.
• PROFILE is used for the temporary ISPPROF dataset.
• TEMPTABL is used for the temporary dataset allocated to WZZ@RW and WZZ@WW, if level WZ@TBLS3 was used. (No configuration in this sample uses it.)

These definitions should only be referenced in the TEMP and SYSTEM levels, so that they are not allocated in foreground ISPF, when WZZRCSPF is being used. UNIT and STORCLASS values can be updated to meet your system requirements.

WZZRCCNF – System Names Lists

The preceding figure shows how to define one list of system names (z/OS system variable &SYSNAME). Any configurations referencing this list will only be selected if the &SYSNAME variable of the z/OS image where the task is running is included in the list.

WZZRCCNF – Trace Statement Definitions

One set of trace definitions are defined in the preceding figure, and WZZRCCNF is terminated with an END statement.