JCL Relationship Functionality

Expand the types of JCL-CONTROLCARD relationships which can be automatically detected and generated.

BatchProgs Support

The BatchProgs support for JCL relationship generation is provided in the Legacy.xml file. There are a number of different structures that have different purposes, the most significant one being BatchProgs. The following is an example BatchProgs specification:

<BatchProgs>
      <item> IKJEFT01,DD*,SYSTSIN,RUN PROGRAM(%P) </item>
      <item> IKJEFT01,DSN,SYSTSIN,RUNCARDS(%P) </item>
      <item> IKJEFT01,PARM,3,PGM(%P) </item>
</BatchProgs>

There are three types of patterns you can use:

The first one attempts to match an EXEC with a PGM of "IKJEFT01", and a DD named "SYSTSIN" which has data that matches the pattern "RUN PROGRAM(%P)".
The second one attempts to match an EXEC with a PGM of "IKJEFT01" and a DD named "SYSTSIN" which has a DSN that matches the pattern "RUNCARDS(%P)".
The third one attempts to match an EXEC with a PGM of "IKJEFT01" and a PARM attribute whose third field matches the pattern "PGM(%P)".

In each case, if there is a successful match, then a "Runs Program Entry" relationship is generated from the current JOB entity to a PROGRAMENTRY entity with the name matched by "%P" in the pattern.

Note: The following limitations exist in this implementation:

Only the "Runs Program Entry" relationship is generated. It is not possible with this mechanism to generate other relationships from JOB. For example, to table names or data store names.
Only one match is made on a given statement. It is possible in some cases to have multiple target names appearing in a single DD data statement, but the current implementation will only find one.
Only one DD statement in an EXEC can be matched by a given rule. Some use cases require matching part of a pattern in one DD and the rest of the pattern in another DD, but this is not possible in the current implementation.
The syntax is obscure and not readable unless you are familiar with the format.

NewBatchProgs Functionality

The NewBatchProgs structure under the JCL tag in the Legacy.xml file addresses the listed limitations. The previous functionality is still present and can be used if required.

Instead of individual items it uses structured XML elements. The following is the specification that is identical to the previous specification:

<NewBatchProgs>
  <add relationship="Runs" type="PROGRAMENTRY" name="%P">
    <exec pgm="IKJEFT01">
      <dd name="SYSTSIN" data="RUN PROGRAM(%P)" />
    </exec>
    <exec pgm="IKJEFT01">
      <dd name="SYSTSIN" dsn="RUNCARDS(%P)" />
    </exec>
    <exec pgm="IKJEFT01">
      <parm number="3" value="PGM(%P)" />
    </exec>
  </add>
</NewBatchProgs>

The NewBatchProgs tag contains one or more elements named "add". Each "add" element specifies a particular relationship type to generate if there is a successful match of any rule within it. These relationships are made from the current JOB, and so the relationship attribute must be the name of a relationship endpoint from JOB in the Enterprise Analyzer model.

Note: New relationship types are not supported, only existing relationships.

The target of the new relationship is provided by the entity type and name. The name attribute will typically be a variable, which is a single letter prefixed by a percent (%) sign.

Within each "add" element are a series of "exec" elements. Each "exec" element specifies a rule that is matched against each of the EXEC statements in the JCL file. Each "exec" element can include the following attributes:

pgm: The PGM parameter of the EXEC.
name: The name field of the EXEC.
stepnum: The step number of the EXEC within the JOB. The first EXEC is numbered 1.

At least one of these attributes must be specified; if more than one is specified, then all of them must succeed for the rule to match. For example, it could match an EXEC of "IKJEFT1A" if it is the 2nd step in the JOB.

If the attributes of the "exec" element match, then the rules inside the "exec" are checked. There are two types of elements that can appear inside "exec" - "dd" and "parm".

A "dd" element is used to match against a DD statement within the EXEC. It can include the following attributes:

name: The name field of the DD.
dsn: The DSN parameter of the DD.
data: The data value of the DD, either read in from a control card or given as instream data in the JCL file directly.

Typically, the "name" attribute is specified along with either one of "dsn" or "data"; if all are specified, then all must succeed for the rule to match.

A "parm" element is used to match against the PARM parameter of the EXEC. This parameter usually consists of a comma-separated series of input fields. Each "parm" element is used to match against one of these input fields. It contains the following attributes:

number: The field number. The first field is numbered 1.
value: The field value.

For example, given the following PARM parameter:

PARM='DLI,CTD11S20,ICIRTVIC'

This rule would match correctly:

<parm number="1" value="DLI" />

Both "number" and "value" must be specified.

Each of the attributes can optionally contain variables, which are a percent sign followed by a single letter. Typically this is used to match against a single "token" or word in the JCL file. For example, given the following DD statement:

//SYSTSIN   DD   DSN=RUNCARDS(USDCU005),DISP=SH

If you use the following rule:

<dd name="SYSTSIN" dsn="RUNCARDS(%P)" />

Then the rule matches and gives the variable %P the value "USDCU005".

Once a variable has been given a value, it can then appear in a later rule and will have that same value. This can be used in two ways:

As shown above, a variable can appear in the "add" element. For example, if you have a rule that looks like the following:
```
<add relationship="Runs" type="PROGRAMENTRY" name="%P">
  <exec pgm="IKJEFT01">
    <dd name="SYSTSIN" data="RUN PROGRAM(%P)" />
  </exec>
</add>
```
Then if the "dd" rule matches and gives %P the value "USDCU005", it will generate a "Runs" relationship to a PROGRAMENTRY named "USDCU005".
Variables can be used to pass information from one rule to another within a single "exec". There is a use-case where the data of one DD statement has text that must be used to match another DD statement:
```
//STEP040   EXEC PGM=IDCAMS
//INDD      DD   DSN=US.DSN1
//OUTDD     DD   DSN=US.DSN2
//SYSIN     DD   *
  REPRO INFILE(INDD) OUTFILE(OUTDD)
```
Here, the INFILE token in the IDCAMS input data gives the name of the DD that specifies the input to the REPRO command. To find the dataset that will be referenced, we need to first match the DD name from the input data, then look up the DSN in that DD, as follows:
```
<exec pgm='IDCAMS'>
  <dd name='SYSIN' data='REPRO INFILE(%D)' />
  <dd name='%D' dsn='%T' />
</exec>
```
The first "dd" rule causes %D to get the value "INDD". The second "dd" rule then uses that value to match against the DD named "INDD", and then assigns to variable %T the value of the DSN, "US.DSN1". The %T variable can then be used in the surrounding "add" element to generate a relationship.

Note: The "data" attribute can match multiple times against a single DD data value.

Consider the following EXEC statement:

//STEP5 EXEC PGM=IDCAMS
//SYSPRINT DD  SYSOUT=*
//SYSIN    DD  *
   DELETE (OFFICE.ACCTMORT.GC138) PURGE
   DELETE (OFFICE.ACCTMORT.GC810) PURGE

This statement uses IDCAMS to clear two datasets. If you want to generate relationships to both of them in the repository you can use the following rule to achieve this:

<add relationship='RefersTo' type='DATASTORE' name='%D'>
  <exec pgm='IDCAMS'>
    <dd name='SYSIN' data='DELETE (%D)' />
  </exec>
</add>

Since there are two places where the word "DELETE" is followed by a word in parentheses, then the variable %D will be assigned two different values, "OFFICE.ACCTMORT.GC138" and "OFFICE.ACCTMORT.GC810". This results in two relationships being generated, one for each of the two values of %D.