JCL Advanced Configuration via XML file
It is possible to configure the Mainframe Analyzer - specifically for JCL - via an XML file. This file indicates to the Mainframe Analyzer any specific links that need to be created or any special utilities called by the JCL cards.
CAST provides a default XML configuration file called AdvancedJCL.xml which is located at the root of the CAST installation folder - this contains various generic configuration settings that may be useful. You can:
- use this file "as is" if it contains the items you require
- modify this file and add in the configuration settings you require
- create a brand new file and use this in stead.
Whatever configuration you decide, you must specify the XML file in the Mainframe Technology options editor (Platform Settings tab) before it will be taken into account during an analysis.
See the sections below for more information about what this file can do for you.
Examples of the roles that the XML file can play
Configuring the analyzer to take into account a utility stored in the "Utility" directory
A program utility
<PROGRAM> <NAME>SORT</NAME> <COMMENT>Sorting Utility for VSAM Files</COMMENT></PROGRAM>
Example JCL File:
//S100 EXEC PGM=SORT//SYSSIN DD DSN=PG00109.DB2CNTL.LP0XXXX(IAQB08),DISP=SHR//IARPREE DD DSN=PG00019.IAQRPRE.JS8XXXX,DISP=SHR
A Procedure Utility
<PROCEDURE> <NAME>PROCSORT</NAME> <COMMENT>Sorting Utility for VSAM Files</COMMENT></PROCEDURE>
Example JCL File:
//S100 EXEC PROCSORT//SYSSIN DD DSN=PG00099.DB2CNTL.LP0XXXX(IAQB08),DISP=SHR//IARPREE DD DSN=PG00009.IAQRPRE.JS8XXXX,DISP=SHR
Modifying a link to be generated on a data set
- Declared after the key words DSN or DSNAME in a utility's DD card.
Example 1
JCL file:
//S030 EXEC PGM=SORT//SYSOUT DD SYSOUT=*//SORTIN DD DSN=PG00008.MAMEXLI.JS2XXXX,DISP=SHR
XML file:
<PROGRAM> <NAME>SORT</NAME> <COMMENT>Sorting Utility for VSAM Files</COMMENT> <DDCARD> <NAME>SORTIN</NAME> <Link>READ</Link> </DDCARD></PROGRAM>
> Creation of an ACCESS + READ type link between step S030 and the file PG00008.MAMEXLI.JS2XXXX
Example 2
JCL file:
//S100 EXEC PGM=IKJEFT1B//SYSTSIN DD DSN=PG00097.DB2CNTL.LP0XXXX(IAQB08),DISP=SHR//IAQRPREE DD DSN=PG00008.IAQRPRE.JS8XXXX,DISP=SHR
XML file:
<PROGRAM> <NAME>IKJEFT%</NAME> <COMMENT>DB2 Utility for executing Programs with SQL Requests</COMMENT> <DDCARD> <NAME>SYSTSIN</NAME> <Link>CALL</Link> </DDCARD></PROGRAM>
>> Creation of an ACCESS + EXECUTE link type between step S100 and the file PG00097.DB2CNTL.LP0XXXX(IAQBO8). Creation of a CALL type link between the step and the program IAQB08. Creation of a PROTOTYPE type link between the file and the program.
- Declared after a configurable key word situated within a DD card
JCL file:
//S040D EXEC PGM=IDCAMS//SYSPRINT DD SYSOUT=*//SYSIN DD *DELETE PG00004.BPRFEME.JS4XXXXDELETE PG00004.BPRFEME.JS5XXXXIF MAXCC LE 8 THEN SET MAXCC = 0
XML file:
<DDCARD> <NAME>SYSIN</NAME> <KeyWord>DELETE</KeyWordD> <Link>WRITE</Link></DDCARD>
>> Creation of an ACCESS + WRITE link type between the step S040D and the files PG00004MAMEXLI.JS4XXXX and PG00004MAMEXLI.JS4XXXX. Please note that in this example, several data sets (in-stream type) are defined in the DD card SYSIN.
Identifying the data sets called as parameters in a JCL procedure
JCL file:
//STEP0100 EXEC DSNUPROC,SYSTEM=DSN,LNK='PG00001.LOADDTA',UTPROC=''//********************************************************************//* UTILITY LOAD FOR EMPL TABLE - NON RESTARTABLE *//********************************************************************//DSNUPROC.SORTWK01 DD DSN=&&SORTWK01,// UNIT=SYSDA,SPACE=(CYL,(2,1))//SYSPRINT DD SYSOUT=*
XML file:
<PROCEDURE> <NAME>DSNUPROC</NAME> <COMMENT>Exemple of Procedure for tests</COMMENT> <PARAMETER> <NAME>LNK</NAME> <Link>READ</Link> </PARAMETER> <DDCARD> <NAME>SYSPRINT></NAME> </DDCARD></PROCEDURE>
>> Generation of an ACCESS + READ type link between STEP0100 and the file PG00001.LOADDTA.
Warning, CAST does not support the reading of tables passed as parameters. Only the first element in the table will be read. For example:
//STEP0100 EXEC DSNUPROC,PARM=(MYPROG,'PG00001.LOADDTA'),UTPROC=''TOTO"
In the above example, CAST can read the name "MYPROG" in the parameter PARM, however, the dataset "PG00001.LOADDTA" cannot be read.
Calling the called program via a utility
- Declared after the key words DSN or DSNAME or after the key words RUN PROGRAM in a utility's DD card:
XML File :
<PROGRAM> <NAME>IKJEFT01</NAME> <COMMENT>Utility for executing DB2 Programs with SQL Requests</COMMENT> <DDCARD> <NAME>SYSTSIN</NAME> <LINK> CALL</LINK> </DDCARD> </PROGRAM>
JCL File:
//S100 EXEC PGM=IKJEFT01//SYSTSIN DD DSN=PG00097.DB2CNTL.LP0XXXX(MY_PROG),DISP=SHR//IAQRPREE DD DSN=PG00008.IAQRPRE.JS8XXXX,DISP=SHR
or
//S100 EXEC PGM=IKJEFT01//SYSTSIN DD * RUN PROGRAM(MY_PROG)//*//IAQRPREE DD DSN=PG00008.IAQRPRE.JS8XXXX,DISP=SHR
- Declared as a parameter:
XML File:
<PROGRAM> <NAME>IKJEFT01</NAME> <COMMENT>Utility for executing DB2 Programs with SQL Requests</COMMENT> <PARAMETER> <NAME>PROG</NAME> <LINK> CALL</LINK> </PARAMETER> </PROGRAM>
JCL File:
//S100 EXEC PGM=IKJEFT01,PROG=MY_PROG//SYSTSIN DD DSN=PG00097.DB2CNTL.LP0XXXX(TOTO),DISP=SHR//IAQRPREE DD DSN=PG00008.IAQRPRE.JS8XXXX,DISP=SHR
Warning, CAST does not support the reading of tables passed as parameters. Only the first element in the table will be read.
Using the called PSB via a utility and association of a PSB to a program
- On the utility, a CALL type link must be declared to the program and a PSB type link must be declared to an IMS PSB.
XML File:
<PROGRAM> <NAME>DFSRRC%</NAME> <COMMENT>IMS Utility for JCL</COMMENT> <PARAMETER> <NAME>DLI</NAME> <Link>CALL</Link> </PARAMETER> <PARAMETER> <NAME>DL1</NAME> <Link>CALL</Link> </PARAMETER> <PARAMETER> <NAME>PSB</NAME> <Link>PSB</Link> </PARAMETER></PROGRAM>
Writing the XML configuration file
Organization of rules
- All rules must be placed between the <CALL_LIST> and </CALL_LIST> tags.
- The program utilities must be placed between the <PROGRAM> and </PROGRAM> tags.
- The Procedure utilities must be placed between the <PROCEDURE> and </PROCEDURE> tags.
- The Parameter declaration between the <PARAMETER> and </PARAMETER> tags ( Warning, CAST does not support the reading of tables passed as parameters - only the first element in the table will be read).
- The DD Card declaration between the <DDCARD> and </DDCARD> tags. If you want to define a key word for a dd card, the declaration must be global. For example:
<DDCARD>
<NAME>SYSIN</NAME>
<KeyWord>DELETE</KeyWorD>
<Link>WRITE</Link>
</DDCARD>
There is one exception: a key word is not necessary for the RUN PROGRAM(...) instruction in a DD card.
Link creation
You can define the type of link that the Mainframe Analyzer will create by entering it between the <link> tags in the XML configuration file. Enter any of the following to create the required link:
- ACCESS > accessing a dataset
- WRITE > writing a dataset
- READ > reading a dataset
- READ-WRITE > accessing a dataset read/write
- CALL > calling a program
- PSB > using an IMS PSB
You can write in either capital letters or in lower case. By default, if no <link> tag is defined, an ACCESS link will be created.
The following code shows how to create a READ link:
<PROGRAM> <NAME>SORT</NAME> <COMMENT>Sorting Utility for VSAM Files</COMMENT> <DDCARD> <NAME>SORTIN</NAME><Link>READ</Link> </DDCARD> </PROGRAM>
Names of programs or procedures
The characters "." and "%" can be used to generalize rules for several objects at a time:
- "." indicates any type of character, e.g.: "hello" and "hallo" will both function with "h.llo"
- "%" placed at the end of a word indicates that any characters that follow are valid, e.g.: "IKJEFT%" corresponds with "IKJEFTB1" or "IKJEFT 01".
<KeyWord> tags
This tag only works with global <DDCARD> tags that are situated just behind the <CALL_LIST> tag.
DDCARD tags
When these tags are global, name/keyword pair must be unique.
When these tags are in a program or in a procedure and if several have the same name, only the first will be taken into account by the Mainframe Analyzer.
Errors in the XML file
Any errors in the XML file will not cause the JCL analysis to fail, but no advanced link types will be created.
See Also
Cobol Advanced Configuration via XML file
