Component Reference
This section describes the Component Reference features within ISPW.
Component Reference Concepts
The Component Reference feature in ISPW encompasses all of the functionality required to gather and store relationships between components. This information is used by:
- Users for documentation, training, and impact analysis
- ISPW as a basis for configuration management.
Note that the Component Reference contains relationships between components.
How is the relationship information gathered?
The Component Reference information is populated either automatically by ISPW or manually by the customer.
Automatically Maintained Reference Information
ISPW provides parsers to gather this information. When promoting a component to the first controlled level, an appropriate parser for the component is executed to gather relationship information. Execution of the parsers is site configurable. New parsers can be added for special technologies, and user exits to cater for site-specific parser complications are supported. DuringISPW installation, it is possible to parse component in bulk to enable the initial data to be stored.
If the ISPW External Function Processor Enhancement is fully enabled, when an ISPW/Eclipse user saves a source or include member, or a source or include member is uploaded (for example. as part of a Git Commit), the source file will be parsed. See “ISPW-External-Function-Process-Enhancement” for more information.
If the ISPW DNA Facility is in use, source members will be parsed when they are generated, and include files will be parsed when they are promoted.
Manually Maintained Reference Information
By use of ISPW’s External Call Interface, component reference information can be added manually. See the ISPW Interfaces Guide for more information. It is possible to add relationship information once for a component version and have it inherited by all subsequent versions of that component. Alternatively, the user-added relationships could be inserted by the ECI for each component version. (Or it is possible to have a combination of the two.)
What information is gathered?
As well as identifying the specific component referred to,ISPW will determine and store the following:
- Component Category of the referenced component (for example, PGM, INCL, etc.)
- Relationship Type (for example, Static, Dynamic, or Weak)
- Impact Type (text that further defines the relationship)
- Inheritance information (for manually-added relationships).
Data Model
The diagram in the following figure depicts the entities surrounding the Component Reference.
Data Model
Short descriptions of the entities are provided in the following table.
Component Reference Entities
Entity | Description |
|---|---|
Component | Depicts a Component (for example, COBOL program PROG01 in Application PAYR of Stream MAIN). |
Component Version | Depicts a Version of a Component (for example, Version 2 of the above Component). |
Component Version External Name | Any name that this Component can be referenced by. Normally this is the name of the Component itself, but it does not necessarily have to be (for example, aliases may be used). |
Component Version Reference | A list of Components referenced by the Component Version (for example, copybooks, other programs, etc.). |
Component Type | Defines the type of Component and can therefore be used to drive a process specific to that type (for example, COB, ASM, CLST, etc.). |
Application Component Type | Further defines the Component Type’s behavior down to specific Applications. |
Base Component Type | Provides a way of grouping Component Types together for parsing. This is the level at which the parsing routines and exits are defined. |
Component Category | Used to specify the category of the reference. (for example, COB, ASM, and PLI Base Component Types all have a category of PGM). |
Using the Component Reference Information
The Component Reference information can be accessed in the following ways:
- Option A on ISPW’s Main menu
- Operation XR against an ISPW Task.
See the ISPW User Guide for information on how to use these functions.
Installation Considerations
Overview
Making the Component Reference functional involves the following:
- Install the ISPF skeleton for batch parsing
- Define Component Categories
- Define Base Component Types
- Update Component Type reference data
- Turn on Component Reference for Applications.
Install ISPF Skeleton
Option M.CR file tailors the ISPF skeleton WZZMCR#. This skeleton is found in the base ISPW Samplib dataset and should be installed into the SITE application with any changes being made to it.
Define Component Categories
Component Categories provide the high level definition of Component References. Component Categories that are to be installed as part of theISPW installation process include those listed in the following table.
Define Component Categories
Component | Description |
|---|---|
INCL | Copybooks, macros, header files, etc. |
JOB | JCL |
PGM | Any program (for example, COBOL, Assembler, PL/I, etc.) |
PROC | JCL Procs |
This supplied set of Component Categories supports the standard 3GL relationships most customers need. New categories can be added as necessary.
Define Base Component Types
This is the level at which the parsers are defined. Base Component Types provide a way of keeping separate the different Component Types that a customer may wish to define in M.CT with the information required for parsing. It is quite possible that a customer may need to define several different Component Types to manage JCL for instance, and all of these can be related to a single Base Component Type of JOB.
The M.BC definition screen appears as shown in the following figure.
M.BC Definition Screen
The Type column indicates the Base Component Type (not the Component Type). Note that this is where the Base Component Types are related to Component Categories.
The value in the Scanner column is the physical load module that will be called to scan a component related to this Base Component Type. The scanner names listed in M.BC Definition Screen are supplied as standard with ISPW.
See CT-Component-Type-Definition for more details on this option.
Update Component Type Reference Data
For each main source component type that is to be parsed, the entry in M.CT must include a reference to a valid Base Component Type. Ensure that the field “Base Component Type” for the component type has a valid value in it.
Turn on Component Reference for Applications
For parsing to be enabled for an Application, the Application’s entry in M.AP needs to be updated so that the field “Component Reference” is set to “Y” (as shown in the following figure).
M.AP Screen
See AP-Applications for more details on this option.
Parser User Exits
The User Exits provide a mechanism to extend ISPW-supplied parsers so that component references found by ISPW can be altered or ignored, and additional references found by the User Exit can be added.
How are the User Exits called?
User Exits are called from within ISPW and passed the parameters listed in the following table.
Parser User Exits
Parameter | Description |
|---|---|
Control block address | An internal ISPW control block. This contains all of the component reference information for the component being parsed. By using calls to special ISPW functions, the reference information can be manipulated. Reference information consists of:
|
Record area length | Length of the record area that ISPW is passing to the user exit for parsing. |
Record area address | The record area containing the line of code. |
In what language can the User Exits be written?
The User Exits can be written in any LE language, including Assembler, C, and COBOL (390 and COBOL 2)—but not OS/VS COBOL.
Samples
The sample members listed in the following table can be found in the Base Samplib dataset.
Sample Base Samplib Dataset Members
Sample | Description |
|---|---|
WZZPP | COBOL copybook for both the user parser and user parser exit. This is used when writing a parser or parser exit in COBOL. |
$WZZPP | Assembler Macro for both the user parser and user parser exit. This is used when writing a parser or parser exit in Assembler. |
#WZZPP | C Header file for both the user parser and user parser exit. This is used when writing a parser or parser exit in C. |
WZPEXTCO | An example User Exit written in COBOL. |
WZPEXTCL | Linkage statements to link the COBOL example. |
WZPEXTAA | An example User Exit written in Assembler. |
WZPEXTAL | Linkage statements to link the Assembler example. |
How User Exits Function
The User Exit is called from ISPW and is passed parameters allowing it to interrogate the record containing the source code. It is also passed the current list of External Names for the component and the list of External References to other components. The User Exit is coded to analyze the line of code passed and can then add to the list of Names and References using specific ISPW calls. The calls to ISPW functions listed in the following table are available.
Available ISPW Function Calls
Function | Description |
|---|---|
WZZPPEXN | As part of the parsing process, the list of External Names can be added to. This function gets a new External Name list element. The new element is added to the front of the list, pointed to by |
WZZPPXRF | As part of the parsing process, the list of External References can be added to. This function gets a new External Reference list element. The new element is added to the front of the list, pointed to by |
WZZPPMSG | This function writes a message to the ISPW debug output stream. |
WZZPPMER | This function writes an error message to the ISPW log output stream. |