Generate System Customization
This section provides information on the various aspects to do with customization of the Generate processes. The following aspects are discussed:
- Components of the generation system
- Reference Data aspects
- Parts Registration
- Customizing Panels and Skeletons
- Customizing the Generate Parms
- Generate Jobs
- Other Considerations.
Components of the Generation System
Generate System Components
The Generate system consists of routines, assembler programs and sample generate panels, and skeletons. Since this system is part of the standard ISPW, the base routines required are already in the ISPW system datasets. The following table describes the components:
Generate System Components
Component Type | Component Name | Component Description |
|---|---|---|
CLST | WZZPSG# | Standard G routine |
CLST | WZXGEN | Main generate routine |
CLST | WZXGENR | Main generate routine for batch generates |
CLST | WZXGEN1U | User generate exit routine |
CLST | WZXGENT | Create generate information table routine |
PANL | WZUG* | Components starting with WZUG, WZUC and WZU@ in the SAMPLIB dataset are models/samples for the generate |
SKEL | WZUG* | |
SKEL | WZUC* | |
SKEL | WZU@* | |
ASM | WZZA005 | Copies from one PDS to another |
ASM | WZZAD08 | Deletes from a PDS |
ASM | WZZA034 | Scans LKED cards for aliases |
Reference Data Aspects
This section describes which Reference data is required to be specified for the generation processes.
Specifying Different Component Types
Component Types that need to be generated need to be specified in the Maintenance Data option CT with the Generate Flag set to “Y”.
It is suggested that different flavors of the same Component Type be handled within Generate processing for that type, rather than having a proliferation of types for each flavor.
Different types of COBOL programs may exist:
- Batch COBOL
- Batch COBOL with Db2
- CICS COBOL
- CICS COBOL with Db2.
Rather than have a different Component Type for each flavor (for example. CCOB, DCOB, COB, etc.), it is better to have the single component type (for example, COB) and manage differences in processing via generate options.
Different Target Environments
Sometimes the generated objects may need to end up in different libraries, depending on the Target Environment. This can be done by the following example definitions in the Reference data:
- Define different classes of the target Component Type which will correspond to the different Target Environments. (For example, have a Component Type of LOAD with a CLASS of <spaces> refer to the target libraries for a batch generate, and have another Component Type of LOAD but with a CLASS of CICS to refer to the target libraries for a CICS generate.)
- In the Associations definition, specify 2 “G” Associations for the LOAD Type, but identify one with a Target environment of “B” pointing to the Batch Load type and the other with a Target Environment of “C” pointing to the CICS Load type.
- In the Generate panel, allow the user to specify what the Target Environment is for the generate and set the variable WTTENV to this value.
See Maintenance-Functions for a fuller description of all the attributes around Associations.
Specifying Generate Attributes in M.CT and M.AD
It is better to rely on the defined values for the generate panel, skeleton, and table values in M.CT rather than define them in M.AD, unless there is a definite requirement for different versions for a particular application. This makes maintenance easier.
Specifying Flags in M.AD
See AD-F-Flags for a complete description on what flag values to set to initiate generates.
Customizing Generate Panels and Skeletons
This section mentions issues to be considered when customizing the Panels and Skeletons.
Generate Panels and Skeletons
The TEST and HOLD panels and skeletons are tailored at each site. Model and sample panels/skeletons are supplied in the SAMPLIB dataset. Basic generate panels and skeletons will be tailored when going through the ISPW install process. Further site modifications are often made to these panels and skeletons to customize them to site requirements.
Separate panels are required for TEST and HOLD level processing because in TEST variables are modified, while the HOLD environment is “frozen” and the HOLD panel is mainly a “display only” panel, except for some fields such as job class, sysout destination, etc.
Help Panels
Basic help panels for the generate are supplied in the ISPW base. It is important that each site update these panels to reflect the site options available and how they are used, since generate panels are frequently used and often require the most explanation.
Processing Variables Available
In general, the variables available for use in the generate panels and skeletons and the Generate User Exit are those variables found on the Generate Tables and those variables described in Exit-Processing.
Using Skeletons to Generate JCL
The supplied sample skeletons code the generate JCL into separate skeletons and then embed them as needed into a “mainline” skeleton. This allows all generate functions (compiler, pre-processor, linkage editor, etc.) to be coded separately in a modular way. It is useful to study the structure of these supplied skeletons, since it is a structure that works and requires minimal maintenance when changes are required.
Useful Tips
- Change the default skeleton symbol for the “&” to a character not normally in JCL, for example “~”. Use the skeleton command “)DEFAULT” to change the character.
- Put a minimum amount of JCL in the “mainline” skeletons. Use the processing to embed lower level skeletons using “)IM” skeleton commands.
- Use a variable to hold the name of the dataset or temporary file that is to be used as input, then each embedded skeleton uses and (optionally) modifies the variable as required. See the example below.
- Use “(OLD,PASS)” DISP parameters for temporary files. This allows the temporary files to be reused in a later step, if necessary.
- Use a variable to hold the value for COND=JCL statements. This allows a condition code to be set in the “mainline” skeleton rather than hard coded in the JCL. The sample generate skeletons supplied with ISPW are good examples of this method of writing skeletons. They should be carefully studied and understood before the task of writing skeletons is started.
- Use “DBFT” in the Command line of the ISPW Generate Panel to help with the debugging of ISPF Skeletons.
Parts Registration
This section discusses the concept of Parts and the requirement for their Registration. A Part represents a component that belongs exclusively to a source component. Examples of Parts include DBRM, LOAD, LIST, etc.
Parts are usually created during the Generate Process, and it is necessary for ISPW to be told what Part is created and when. ISPW stores information in its repository about these parts (for example, the warehouse key if it is in the warehouse).
For Parts created during a batch generate job, there must be a step at the end of the job that registers these Parts to ISPW. There is also a way for Parts to be registered in REXX.
File Tailoring JCL to Register Parts
ISPW provides sample skeletons that are embedded to correctly register the parts that are created. As the JCL is tailored, each step that creates parts also sets variables that are used in the final Part Register step to create the correct ISPW calls to Register the Parts. For example, the step that does the Linkedit also has an embed to another skeleton as shown in the following figure.
Skeleton Embed
The WZU@BLDL skeleton is shown in the following figure.
WZU@BLDL Skeleton
Note that these embeds are used for controlling the file tailoring only; no JCL is output at this point. Output JCL is tailored for the Parts Register step in the skeleton WZU@PART as shown in the following figure.
WZU@PART Skeleton
The sample skeletons can register up to 9 parts within a single job. If more are required, the samples will need to be changed.
Part Register Step – Tailored
The tailored part register step for a typical compile is shown in the following figure.
Tailored Part Register Step
Gen Processes
The parts are grouped into Generate Processes. The above example has two processes: CMPL and LINK. Parts must be registered within a Gen Process, and each Gen Process must have one input registration and 1 to 8 output registrations. In the above example, the CMPL process has an input part with the special name of “SOURCE”, which represents the source component. The LINK process has the input part of GMT1LNAM, which in this example corresponds to the Object that was created in the compile. There is one output part for the CMPL process (GMT1LNAM – object) and two output parts for the LINK (LOADNAME – load, and GMT3NAME – listing).
Part Register Input Variables
The input variables to the Part Register are described in the following table.
Part Register Input Variables
Variable | Description |
|---|---|
WTASCVAR | This is the Associated Varname, and can be one of the following:
|
WTGENPRC | Identifies the Generate Process. |
WTPNAME | Specifies the Part Name. |
WTINOUT | Specifies whether this is registering the input part or an output part. Valid values are I or O. |
TASKIDX and | Internal IDs that ISPW requires. |
Using One Process When Not Keeping the Object
If the customer site is not keeping the Object, it is preferable to change the skeletons such that a single process is used to cover both the compile and the link. The WZU@BLDC and WZU@BLDL skels would need to be changed slightly to both use the same value for WZUGENPn. WZUBLDL would need to be changed as shown in the following figure to remove the registration variables for the input (because there is now no separate process for LINK).
Remove Registration Variables
Register Additional Generated Parts
Support has been added for the registration of additional parts during the generate process, using the SIMP collection for parts not defined to use the regular GMT or LOAD name variables and datasets. This feature allows the customer to define additional generated parts beyond the standard LOAD and GMT modules. For example, if a COBOL program needs to linked into batch, IMS, and CICS load libraries in the same generate execution, the IMS and CICS load modules can be registered into the SIMP collection with LOD_IMS and LOD_CIC values, respectively, in the WTASCVAR variables during the part registration phase of the generate process.
In order to support the extra parts in the Generate Process, the dataset names defined for those parts need to be made available as variables to the generate skeletons. Any such variables can be initialized by a Compile Exit. A sample Compile Exit is provided via function WZTSIMG#, which is available in the base CLIST library. The choice of variable names is left to individual sites to customize as needed.
The sample WZTSIMG# Compile Exit defines the values listed in the following table for variable WTASCVAR and library name variables to be used in skeleton processing to support additional parts.
Register Additional Generated Parts
WTASCVAR | Library Variable |
|---|---|
LOD_CIC | W$LODCIC (CICS load library) |
LOD_IMS | W$LODIMS (IMS load library) |
LOD_BAT | W$LODBAT (Batch load library) |
LST_CIC | W$LSTCIC (CICS listing PDS) |
LST_IMS | W$LSTIMS (IMS listing PDS) |
LST_BAT | W$LSTBAT (Batch listing PDS) |
Installation Considerations
Changes to support the extra parts at part register time are available as sample skeletons WZU@BLD and WZU@PART. These samples should be checked out into the SITE application and used to replace the existing versions. As provided, these samples add 7 extra parts (A through G).
Define pre-exits for the P, X, and D operations for any type such as COB that may generate extra parts. The pre-exits should be defined in the M.EX table for each operation as listed in the following table.
P, X, and D Operation Pre-Exits
Operation | Pre-Exit |
|---|---|
P | ISPEXEC SELECT CMD(%WZTSIMP# &DEBUG) |
X | ISPEXEC SELECT CMD(%WZTSIMX# &DEBUG) |
D | ISPEXEC SELECT CMD(%WZTSIMD# &DEBUG) |
The entries in the following figure define a Pre-Exit for Operation P for COB types.
Operation P Pre-Exit for COB Types
Create a Compile Exit to define the dataset names used by the extra parts. Modify the provided sample WZTSIMG# as needed. The Compile Exit is enabled by defining the name of the exit in variable CMPLEXIT in the generate panels (WZUGD and WZUGH if using the standard panels). The following figure shows an example of a panel change to define compile exit WZTSIMG#.
Change to Define Compile Exit WZTSIMG#
Change the generate skeletons to create the required objects in the libraries defined by the Compile Exit variables and to define the required variables for Part Register. Reference the example skeleton WZU@SIMP# as provided in the base SAMPLIB.
Customizing Generate Parms
New, site-specific generate variables may be added directly to the Extension Class WZGPARMS by using option M.EC, selecting the class, and adding new entries to it. See EC – Extension Classes for more details.
Generate Jobs
The standard Generate process invariably uses ISPF File Tailoring to create a job and then needs to submit it for processing. This section describes the different methods of job submission, their uses, and how to indicate the preferred method.
Generate Process
The Generation process consists of the three steps listed in the following table.
Generate Process
Steps | Description | |
|---|---|---|
1 | Client requests a G (or P) | During this step, the ISPW Master Address space validates the request and puts the task(s) in process for a Generate. In the case of a Promote that requires a Generate, the task(s) will be put in process for a P, and once the P has completed, they will then be put in process for a G. |
2 | Generate Dialog | The Generate process begins, and any defined Generate Panels are displayed. |
3 | File Tailor and | The Batch job is file tailored and submitted for execution. |
Depending upon how ISPW is set up with regard to Job Submission, steps 2 and 3 can occur completely, partly, or not at all within the client address space.
Job Submission Methods
There are three possible methods of generate job submission:
- Foreground processing and submit (that is, steps 1, 2, and 3 performed in foreground).
- Foreground processing and Demand of job that does the file tailoring and submission of generates in the background (that is, steps 1 and 2 in foreground and step 3 in background).
- Set Execution processor does processing and submits the job (that is, step 1 in foreground and steps 2 and 3 in background).
The method to use depends on security access considerations. If a single or special UserID is needed to access TEST or HOLD level datasets, the second or third method is used. A single or special UserID would be needed in the event that only that UserID has been given access to the datasets. Because the job is submitted under the demanded job’s UserID, dataset access can be restricted to only that UserID.
Foreground Processing
Jobs submitted in this way mean that the UserID tailoring and submitting the JCL need update access to any target datasets (for example, load libraries). This is generally acceptable for the TEST environment, but after the components are “checked in” to a HOLD level, it is generally considered poor security to allow the user direct update access to those datasets.
Demanded Job Processing
This is where a job which runs under a special UserID is able to be “demanded” to be submitted by the normal user. (ISPW submits it on the user’s behalf.) This job does the File Tailoring and submits the job, meaning that even though the ISPW user can have a generate submitted, it is not running under their UserID and therefore is secure.
Set Processing
Sets can be used for generates. When a Set does the generate, it is running under the UserID of the Set, so this is another secure way by which anISPW user can request a generate yet not have access to the physical datasets. The important difference between this method and the Demanded Job method is that the generates come under ISPW’s Approval mechanism.
Foreground or Demanded?
For this discussion, having a Set submit the job falls under the arguments for Demanded. Typically, only three configurations are used:
Foreground in Both TEST and HOLD
In this configuration, developers will be performing the generate and updates to the source and load datasets. They will require full update access to TEST and HOLD datasets. This configuration is used most often for non-critical applications or applications where the HOLD environment does not need to be “frozen” during the QA or acceptance testing stage.
Foreground in TEST, Demanded in HOLD
In this configuration, the developers will move the source from TEST to HOLD, but the generates (updates to the load libraries) will be done under the demanded job’s UserID. This configuration is used for critical applications where the HOLD environment is not to be tampered with during QA or acceptance testing. Most sites choose this option because it closes the security exposure of allowing a developer to change a load module after it has been signed off, but before it moves to production. The developer can only update the HOLD environment via ISPW and the demanded batch job, thus ensuring that all actions are recorded by ISPW and nothing can slip by.
Using a single batch UserID to access HOLD ensures that the HOLD environment is not tampered with, and therefore what was tested in HOLD will be moved into production.
Demanded in Both TEST and HOLD
This configuration is used mainly for special technologies that require batch processing under a single UserID.
Typical Scenario
Typically, the ISPW user will do a foreground generate at a TEST level, and a demanded job will be used for all HOLD levels. Demanding a job via ISPW as opposed to using a Set is still useful for those situations where an individual job needs to be submitted or a special generate variable is required for a HOLD Generate. (The HOLD Generate panel is not displayed for Set Generates, and so this is not possible in Sets.)
Setting the RTYP Variable to Control Job Submission
The variable RTYP is used to indicate what type of generate job submission is required. It may be set in the TEST/HOLD panels if overriding the default processing for the MEMBENV value.
The following table shows the values that can be set for RTYP.
Setting the RTYP Variable
Environment | RTYP | Job Submission |
|---|---|---|
TEST | CL (default) | Foreground submit. |
TG | Demanded generate. | |
HOLD | RR (default) | Demanded generate. |
RO | Foreground submit. |
Considerations for Setting Up Demanded Processing
The Demanded Jobname is defined in M.CT for the component type or overridden by the application value in M.AD. A value must be specified in M.CT (or overridden in M.AD) for the Generate Table. (This table is used to pass the generate parameters from the client to the demanded job.)