User Manual of JCL-Drawer v1.04r01

1 General information

JCL-Drawer is a software that makes the flowchart of a Job from its JCL source code (Job Control Language : a scripting language used to run batch jobs on IBM mainframes). It implements a great number of rules to produce smart and elegant flowcharts

JCL-Drawer is a portable software written in VBA code and runs as an Excel application. The JCL code to process is required as a text file that can be accessed by Excel.

JCL-Drawer can process several JOBS at the same time and generates their flowcharts in one or several Excel workbooks. These flowcharts can be automatically printed or exported in SVG format, or simply kept in Excel.

JCL-Drawer parameters can set up both JCL flowcharts rendering (display of steps, file names, fonts, icone sizes, colors...) and contents (choice of handling rules for remarks, OPC scheduler directives, JCL cards that should be handled in a special way, detection of input or output files...).

In order to automate the production of flowcharts, JCL-Drawer can be used as Batch process interpreting a script file that describes all the actions to do

Excel and VBA are trademarks of Microsoft Corporation. IBM is a trademark of International Business Machines Corporation. OPC is an IBM product.

2 Utilization principles

JCL-Drawer analyses the JCL file in an analysis workbook and draws the flowchart of each job on a worksheet of one or several flowchart workbooks. At the opening, JCL-Drawer searches an analysis sheet among opened workbooks. The workbook containing the first found analysis sheet will be the analysis workbook until JCL-Drawer is closed. This workbook can hold several analysis sheets.

Customized parameters have to be downloaded into a parameters sheet, in an Excel workbook, in order to be saved. At its opening, JCL-Drawer loads the parameters sheet associated to the analysis worksheet. If none, default parameters are used. Users can edit the parameters or manually upload a parameters sheet already present in the workbook.

2.1 Importing JCL code

JCL-Drawer does not process jobs present on the Mainframe computer straight away. Users need to have these jobs in text files on their workstations or on their local network. Same constrain for the JCL code which is called by INCLUDE or FETCH directives (OPC scheduler), as long as you want this code to appear in the flowcharts.

The download of JCL code from Mainframe into local text files is usually easily made via an 3270 emulator (This operation is not described here).

Several jobs to draw can be placed into the same file, with the following restrictions :

• If several jobs have the same JOBNAME, only one will be processed
• Comments or JCL code lines placed between an End-Of-Job card (//) of a job and the JOB card that starts the next one will be omitted (an alert message will be shown)
• Only the last job of the file can contain DATA without end delimiter (parameter DLM=)

To be drawn by JCL-Drawer, the code of members called by INCLUDE and FETCH in the job have to be imported into a text file (.txt), each member in a different file, located in the folder registered in the parameters.

2.2 Setting up JCL-Drawer

JCL-Drawer reviews a number of rules in order to tear the files that are read apart from those that are written. Very often, JCL allocates empty files at the beginning of the job, these files being output of the next step that uses them. A major point of JCL-Drawer setting up is therefore to declare the names (or patterns of names) of steps, procedures or programs that are making file allocations, and if the names of the allocated files have to be searched in sysin or in DSN. The I/O use of some DD cards and DISP parameter can also be forced by parameters.

The comments present in the JCL can be included in the flowchart of the job. JCL-Drawer links the comments to the preceding or following JCL card, according to the specified rule. Exceptions : always linked to the preceding card are the comments at the end of JCL lines, as well as lines of JCL being turned into comments (i.e. detected by JCL-Drawer as lines of JCL). The first block of comments is always associated to the JOB card.

Some schedulers add directives onto comment lines. JCL-Drawer can be set up to consider these directives as comments or to remove them, and to compute those that insert JCL code.

The user registers into special cards the values of parameters for which a special behavior of JCL-Drawer is needed : DD cards to be left out (not to burden the flowchart), INCLUDE or FETCH to be developped (import of the JCL code in place of the directive), those to be drawn as PGM, parameters of PROC that sould not appear on the flowchart...

An option tells JCL-Drawer not to draw DD cards at DUMMY.

The values of JCL-Drawer parameters can be modified on the 'parameters' tab of the interface, but also on the Excel worksheet where they have been downloaded -worksheet that will have to be reloaded afterwards.

2.2.1 List of special cards

These cards are available on the Parameters tab of the JCL-Drawer window.

• PGM/PROC.DD to leave out : For theses PGM or PROC, names of the DD cards that will not appear on flowcharts (1)
• PGM/PROC.DD in input : For this PGM or PROC, name of the DD card that will always be placed in input (1)
• PGM/PROC.DD as parameter : For this PGM or PROC, name of the DD card that will be placed as parameter if possible (1)
• PGM/PROC.DD in output : For this PGM or PROC, name of the DD card that will always be placed in output (1)
• DISP where input : Values of the DISP parameter of files that should be placed in input of a PGM or a PROC
• DISP where output : Values of the DISP parameter of files that should be placed in output of a PGM or a PROC
• EXEC alloc in DSN : Steps where allocations are made, the allocated file being declared in a DSN= parameter
• EXEC alloc in SYSIN : Same as above, except that the file is declared in sysin
• EXEC to leave out : Steps that will not appear on flowcharts
• FETCH to develop : JCL Members (called by a scheduler) which will be inserted in place of the FETCH directive
• FETCH equivalent to PGM : JCL Members (called by a scheduler) that will appear on flowcharts like calls of PROC
• INCLUDE to develop : Includes of JCL whose code should be inserted in place of the INCLUDE directives
• INCLUDE equivalent to PGM : Includes of JCL that will appear on flowcharts like calls of PROC
• PARM to leave out : Parameters of called PROCs that will not appear on flowcharts
• PGM/PROC alloc in DSN : PGMs or PROCs that make allocations, the allocated file being declared in a DSN= parameter
• PGM/PROC alloc in SYSIN : Same as above, except that the file is declared in sysin
• PGM/PROC sort : PGMs or PROCs that will appear on flowcharts as sortings (diamond-shaped icon)
• PROC.parameter PGM : For this PROC, name of the parameter that gives the name of the PGM runned by the PROC, in order to display it in the same icon (1).

The values entered can be patterns of names and can contain special characters handled by operator 'Like' of VBA : * for any character or string, # for a digit, [A-Z] for an upcase letter...

Syntax of special cards annoted (1) is '[Name of the PGM or PROC].[Name of the parameter]' where patterns of names are also accepted.

--> See the description of the 'Parameters' tab

2.2.2 List of extra parameters

These parameters called extra parameters influence JCL-Drawer behavior. They are classified according to their utilization :

Extra parameters used during the loading and analysing stages :

• PGM that executes DB2 progs : PGM that runs DB2 programs (default value : 'IKJEFT1B'). If this parameter is filled in, JCL-Drawer searches the name of the DB2 program executed and displays it instead of the one set-up here, when it appears in the JCL.
• PGM that executes IMS progs : PGM that runs IMS programs (default value : 'DFSRRC00'). Same functioning as the previous parameter.
• Chars start/end comments : List of the characters retained for the start and the end of the significant part of comments. Theses characters make a string between brakets (default value : '[A-Z,0-9,(,),é,è,ê,ù,à]'). The syntax of the string must match the VBA 'Like' operator.
• Nb of characters per square : Number of characters per square of the virtual grid of the flowchart. It is used to save the space required for drawing sysins and comments.
• Nb of lines per square : Number of lines per square of the virtual grid of the flowchart. Same use as above.
• Nb of icons per line : Maximum number of icons that will be placed on a single line of input or output of a step.
• Systsin DB2 analysis : Replaces SYSTSIN by a DSN called DB2 with the plan name as DDname. Reload the JCL file after this parameter has been changed.
• Sort Sysin analysis : Hides sort SYSIN in PDS but shows the name of the member in the icon of the sort step.

Extra parameters used during the positioning, drawing and export stages :

• Number of DSN qualifiers per line : Sets the number of qualifiers before line feed while writing DSN names on the flowcharts.
• SVG export horiz. scale : Horizontal scale factor of shapes (does not apply to texts) for the SVG export of flowcharts.
• SVG export verti. scale : Vertical scale factor of shapes (Same as above).

--> See the description of the 'Parameters' tab

2.3 Processing JCL

The processing of the JCL code is completed in several successive stages. The user selects those to be carried out, fills in mandatory information for each one, before starting the execution :

• Loading (path of the JCL file, name of the analysis worksheet) : Feeds the analysis sheet with the JCL data.
• Detection () : Refreshes the window list of jobs from the analysis sheet.

For each selected job in the list :

• Analysis () : Works out I/O of files, sysin sizes, JCL cards to process/hide out...
• Positioning () : Positioning of elements within a step, and of steps relatively to each others
• Optimization () : Works out simple following steps having one file in common (output of the first step and input of the next one), in order to draw this file only once (optional stage)
• Drawing (name of a flowchart workbook -optional) : Produces the flowchart of the job from the data of the analysis worksheet, on a sheet of the flowchart workbook (1 job / worksheet option) or on a single flowchart workbook (1 job / workbook option)
• Saving (path of the flowchart workbook) : Saves flowchart workbook(s)
• SVG Export (path of the export folder) : Produces an .svg file from the flowchart of the job
• Print (printer) : Prints the flowchart of the job
• Close (name of the flowcharts workbook -optional) : Closes the flowchart workbook(s) after the job is processed (1 job / workbook option) or after all selected jobs are processed (1 job / worksheet option)

JCL code does not always hold enough informations to be correctly interpreted. If the setting up turns out to be unsufficient to get the expected result, it is possible to modify the loaded or calculated data on the analysis worksheet, between the stages of the process.

3 Generated flowchart

JCL-Drawer designs a virtual grid and places icons according to this grid. Sizes, positions relative to the grid and colors of the flowchart elements can be set-up. The type of shapes of icons cannot be chosen.

JCL-Drawer keeps the sequential order of the steps of the job.

Each step is built around the PROC and/or the PGM that is executed. Above it, come DD and DSN that detected as input, and below come those detected as output. To the left and right of the PROC/PGM are placed the 2 largest sysins of the step or the DD card parametered in 'PGM/PROC.DD as parameter' -the other parameters being thrown above as input.

Conditions (IF THEN...), assignments (SET) and declarations of instream PROC are handled as text inserted between steps.

Parameters of PROC -except those declared in special cards 'PARM to leave out', are gathered in a sysin-like card named 'parm'.

The comments found in the JCL code are placed on the right of the flowchart. The name of the card or DSN to which they relate (according to the set-up comments rule) is echoed above each block of comments.

4 Interface

The JCL-Drawer interface consists of 2 specific dialogs windows.

4.1 'JCL-Drawer' window

It is the main window, opened by the user at the start of JCL-Drawer, by the macro AfficheJCLDrawer. Depending on the installation, this macro can be executed from the File menu, on the standard tool bar, or through the Tools menu -> Macro item -> Execute (keyboard shortcut = Alt+F8).

The 'Commands' tab of the window constitutes a panel board of JCL-Drawer processes. The user checks actions to be done, selects jobs and starts the treatment -which he can interrupt at the end of the stages.

The 'Parameters' tab is used to set up the rules that manage the interpretation of JCL, depending on the coding conventions of the company. Here are also displayed the drawing parameters (color, size, position...) of various icons, texts and arrows that will constitute the flowchart of the job.

The 'Manual' tab presents the embedded help file of JCL-Drawer, that can be exported in .txt or .html format.

The 'About' tab describes the license (on the evaluation version) and useful links. A button allows the user to switch language from French to English.

4.1.1 'Commands' tab

The data from all the frames are used when the user clicks on the 'Start' button. Clicking on the 'Stop' button interrupts the processing at the end of the current stage.

• 'Input' frame

To load JCL code to draw : Check the 'Loading' box, fill in the name of the file containing the JCL code or click on the 'JCL File...' button to get the choose box.

To display in the 'Analysis' frame the list of the jobs loaded into the analysis worksheet : Check the 'Detection' box.

• 'Analysis' frame

To select all the jobs of the list after the 'Detection' stage, check the 'All' box. Else select the job(s) in the list (control + clic to add a job to the selection; shift + click to select all jobs between the active job and the one with the cursor focus).

To calculate the data of the flowcharts of the selected jobs, check the 'Analysis', 'Positioning' and 'Optimization' (optional) boxes.

• 'Flowchart' frame

To draw the jobs selected in the list of the 'Analysis' frame, check the 'Drawing' box.

If option '1 JOB/Workbook' (on the 'Parameters' tab) is selected, each flowchart workbook will be named after the job.

If option '1 JOB/Worksheet' is selected, each sheet of the flowchart workbook will be named after the job. Fill in the name of the workbook (that has to be already opened) where to draw the jobs, or leave empty the 'Flowchart workbook' textbox to create a new one.

• 'Outputs' frame

To save the flowchart workbook(s), check the 'Save' box and fill in the path of the workbook or click on the 'Workbook...' button to choose it.

To export flowcharts in SVG format, check the 'SVG export' box and fill in the path of the folder where the SVG files will be created, or click on the 'SVG Folder...' button to get the choose box.

To print flowcharts : Check the 'Print' box. Click on the 'Printer...' button to change the default printer.

In order to automatically close the workbook(s) at the end of the processing : Check the 'Close' box.

4.1.2 'Parameters' tab

This tab gives access to the information that adapts JCL-Drawer behaviour to the coding conventions of each company, and to the needs and tastes of the users. See also 'Setting up JCL-Drawer' and 'Limitations'

• 'Loading & Analysis' tab

Select the 'Scheduler' ('OPC' or 'none') to interpret some directives (ex : OPC FETCH MEMBER) and not to get directives in comments.

Select the 'Comments' insertion rule in the JCL ('Before card', 'After card' ou 'No comment') -JCL-Drawer can associate a line of comments to the next JCL card or to the previous one.

Check the 'Hide DD DUMMY' box for the DD cards associated to DUMMY not appearing on the flowchart. During the analysis stage, DUMMY DD cards for which no I/O use determination rule applies (frequent event) lead to the opening of the window 'Choose I/O for a DSN'.

Fill in the 'Includes Folder' box the path of the folder that contains all the job JCL members to expand during their loading in JCL-Drawer (member names must be set-up as special cards). Click on the 'Includes Folder...' button to choose it in a dialog box.

JCL-Drawer handles special cards of predefined types (ex : PROC/PGM.DD to leave out). Select an entry in the 'Special Cards' listbox to display the list of cards of this type to the right. To add a card, fill in its value (it is possible to use patterns) to the left of the 'Add ->' button and click on this one. To remove one or several cards from the list, select them and click on the 'Remove <-' button.

'Extra parameters 1/2' frame : Select a parameter in the list at the left, and modify its value at the right. The spin button applies only to numerical values of the parameters.

• 'Positioning & Drawing' tab

Select the desired option whether to get all job flowcharts in the same workbook on different worksheets (1 Job/WorkSheet) or on different workbooks (1 Job/WorkBook).

JCL-Drawer allows the user to set the drawing parameters of each element (position, size, stroke and fill color... of the shape and/or of the text-box) and for some of them to set if they should be included on the flowchart and how (Yes, No, Shorten).

To display the drawing parameters of an element, select it in the 'Card - Param' list. Parameters that are not used by JCL-Drawer for this element are grey-colored. The others are available for edition.

External DSN background color : A special background color can be set up here for the icons of DSN placed in input of a step and that have never been met beforein the same job as output.

'Extra parameters 2/2' frame : Same functioning as the '1/2' frame.

• 'Parameters Workbook Management' frame

This frame shows the names of the current parameters workbook and worksheet, with whom exchange the parameter values in memory.

The 'Actions' menu list gives access to :

- Create a new parameters workbook

- Open an existing workbook

- Use the JCL-Drawer workbook as the parameters workbook

- Save the parameters workbook

- Save the parameters workbook with another name

- Close the parameters workbook

Click on the 'Write' button to download the current parameters on the worksheet chosen to the left (the sheet is created if it does not exist).

Click on the 'Read' button to set the current parameters with the data from the worksheet chosen to the left.

'Default' button : Click here to set parameters back to the installation values of JCL-Drawer

--> See the special cards list

--> See the list of extra parameters.

4.1.3 'Manual' tab

The user takes advantage of an embedded manual describing the interface and the use of JCL-Drawer.

The row of buttons enables navigation through the manual. Respectively : Previous page, next page (this is not an historical navigation), upper page and table of contents.

The user can fill in a string to look for in the manual. Click on the 'Search' button to begin or to continue the research (loops).

In the displayed text, some zones are sensitive and behave like hyper-text links. On the table of contents in particular, click on the wanted page to have direct access to it.

Down at the right, the 'Export...' button allows the user to choose a file name where to export the manual in text or html format. A potentially updated version of this manual with screenshots can be found on the Internet website of JCL-Drawer.

4.1.4 'About' tab

This tab presents information on the currently used version of JCL-Drawer (first frame), on copyrights, and allows the user to switch languages.

In the case of the evaluation license, its terms are displayed in the second frame. Terms of the licence must be approved by checking the box 'I agree with terms of the license'. As long as this is not done, the other tabs are unavailable.

In the case of the end-user license, the logo of JCL-Drawer is shown.

The last frame named 'Links' contains the address of the Internet website of JCL-Drawer where documentations and form to contact the editor can be found.

The button down at the right allows the user to switch languages used by JCL-Drawer between French and English.

4.2 'Choose I/O for a DSN' window

This window appears during the JCL analysis stage, when JCL-Drawer finds no rule to decide the I/O use of a file, or when a DSN has been detected with a different use from the previous DSN on the same DD card.

JCL-Drawer then asks the user to decide if the file should be placed in input, in output or as a parameter of the step. The user can also decide to interrupt the analysis, e.g. to adapt parameters to issues.

5 Batch mode

A mode for batch processing has been implemented in JCL-Drawer. All the main actions that are available in the user interface have a corresponding command in the script language of JCL-Drawer.

For a satisfying rendering, a consistent set-up must have previously been established and stored in a parameter workbook.

When a user opens JCL-Drawer, Excel is setting up a security alert about the presence of VBA code in the workbook. JCL-Drawer can only be used once the activation of the content has been allowed by the user.

In the batch mode, we need to overcome this alert which would prevent the execution of the script. For this, once JCL-Drawer has been installed, the user has to sign the workbook by a self-signed certificate, which can be created with the Microsoft's certificate creation tool that comes along Office Suite.

5.1 Execution in batch mode

JCL-Drawer is executed in batch mode by a .bat script that runs Excel with the JCL-Drawer workbook and the script to interpret in arguments.

"%Excel%" /e /jcld/%Script% /p "%WorkingFolder%" "%JCLDrawer%" >> %logFileName%

• /e : No screen and no creation of an empty workbook at launch
• %Excel% : Full path of program EXCEL.EXE
• %Script% : Name of the .jcld script to interpret
• %WorkingFolder% : Working folder of Excel
• %JCLDrawer% : Full path of JCL-Drawer
• %logFileName% : Full path of the log file of the processing

The log file contains the trace of all executed commands, the errors that have been encountered and the DSNs whose positioning (I/O) has been forced during the processing.

5.2 Scripting language

LANG EN|FR	Choice of the language. All commands sent afterwards must be in the chosen language.
INIT_PARAMETERS	Initialization of the parameters to the default values of JCL-Drawer.
OPEN_PARAMETERS_WORKBOOK parametersWorkbookName	Open the parameters workbook in argument.
LOAD_PARAMETERS parametersSheetName	Loads the parameters from the whorksheet in argument
CLOSE_PARAMETERS_WORKBOOK	Close the parameters workbook
CONTINUE_ON_ERROR Y|N|""	By default, JCL-Drawer stops when an error is encountered. That command can change this behavior.
INIT_PROCESS	Initialize the data of the process (apart from parameters)
JCL_FILE jclFileName	The name of the file containing the JCL code to flowchart is the argument of this command.
ANALYSIS_SHEET analysisSheetName	The analysis worksheet used for the process will be the argument of this command.
DSN_USE_UNKNOWN INPUT|OUTPUT|PARAMETER|STOP	In TP mode, JCL-Drawer opens a pop-up window to let the user choose the position of a DSN when no rule could be applied. In batch mode, a standard behavior must be set : Force the position (back in Input, in Output or as a Parameter) or stop the process.
START_PROCESSING	Start the processing.
CLOSE_JCLDRAWER	Close the JCL-Drawer workbook. No auto-save or alert message is triggered.
INIT_JOB_SELECTION	Empty the list of the selected jobs.
SELECT_ALL_JOBS Y|N|""	Select all the detected jobs.
SELECT_JOB jobName	Select the job whose name is the argument. This command can only be used after the loading and detection stages.
INIT_ACTION_SELECTION	Unselect all actions.
SELECT_LOADING Y|N|""	Select the action : Loading.
SELECT_DETECTION Y|N|""	Select the action : Detection.
SELECT_ANALYSIS Y|N|""	Select the action : Analysis.
SELECT_POSITIONING Y|N|""	Select the action : Positioning.
SELECT_OPTIMIZATION Y|N|""	Select the action : Optimization.
SELECT_DRAWING Y|N|""	Select the action : Drawing.
SELECT_SAVE Y|N|""	Select the action : Save the generated flowcharts.
SELECT_SVG_EXPORT Y|N|""	Select the action : Svg export.
SELECT_PRINT Y|N|""	Select the action : Print of flowcharts.
SELECT_CLOSE_FLOWCHART Y|N|""	Select the action : Close of flowchart workbook(s).
FLOWCHART_FOLDER flowchartFolderName	The flowchart workbooks will be saved in the folder in argument (for the '1 JOB/Workbook' option).
FLOWCHART_WORKBOOK flowchartWorkbookName	The flowchart workbook will be saved with the name in argument (for the '1 JOB/Worksheet' option).
SVG_EXPORT_FOLDER exportFolderName	The svg files will be saved in the folder in argument.
PRINTER printerName	The print will take place on the printer in argument.

The default value for all arguments noted Y|N|"" is Y.

6 Limitations

Jobs using Skeleton cannot be properly flowcharted, in general. JCL-Drawer is not handling this technology.

JCL-Drawer makes no semantic interpretation of IF-THEN-ELSE encountered in the JCL code.

In certain cases, the determination of the I/O use of files by the allocation rule can be inadequate.

The following actions may be needed to solve problems :

• Set the I/O use of DDnames by parametering special cards.
• If the DISP parameter is distinctive of an input file (or output) according to the coding conventions of the company, add the DISP value in special cards.
• On the contrary, the user can try to deplete the settings to avoid automatic determination of I/O use, so JCL-Drawer shows the 'Choose I/O for a DSN' window.
• Hand editing in the analysis worksheet between two stages of the process.
• Hand editing in the generated flowchart.

Another option can be to split the job into several ones (e.g. each one equivalent to the original in the case of a specific value of a condition), before loading JCL in the analysis sheet.

Use of the IF-THEN-ELSE conditions to build complex JCL processes remains unusual.

The number of comment lines is limited to 256 per card. The next comments will be ignored.

In a developed FETCH, beyond 256 EXEC cards, COMP parameter of FETCH will not be carried forward on each step.

On the 'Parameters' tab, the number of special cards is limited to 256 of each type.

In the end, JCL-Drawer is subject to Excel limitations (for example in terms of size of worksheets or size of calculation formulas), to Windows limitations, to hardware limitations... (non-exhaustive list).