Running the MetaAnalytics CAScanner for JCL by hand.
Document Version 0.2
Semantic Designs, Inc.
August 2014
[0] Introduction
This document describes a manual procedure for running the
MetaAnalytics JCL CAScanner tool.
This procedure scanner supports access to externally-defined JCL
procedures used by the JCL file.
Limitations of this version:
[a] Most of this procedure is performed as commands. Later
Windows batch files may be developed to simplify this
procedure.
[1] Procedure for Scanning a single JCL file
[1.1] Summary
The procedure has 5 steps. Each is described in a subsection below
(Sections 1.2 - 1.6).
The basic procedure first sets three environment variables:
JCL_CASCANNER_P0B
RUNNER
DMS_JCL_OS_INPUT_ENCODING
If you need to access external PROCEDURE definitions, you will also
set DMS_JCL~OS_INCLUDE_PATH and possibly DMS_JCL~OS_SYSTEM_LIBRARY.
(See section 1.5)
Then the scanner is executed from the command line, using these
environment variables. (See section 1.6)
If you encounter any problems following the procedure, check the
Trouble-Shooting section at the end of this document.
[1.2] Locate the PARLANSE binary (.P0B) file
Note: The middle letter of the file extention is the digit zero, not the letter "O".
This is pronounced P-zero-B, not P-OH-B.
[1.2.1] Typical file location
The P0B file will usually be under the DMS root as
DMS\Domains\JCL\OS\Analyzers\CAScanner\CAScanner.P0B
[1.2.2] Set the environment variable JCL_CASCANNER_P0B
Set the environment variable JCL_CASCANNER_P0B to the file path
to the P0B file.
Here is an example of setting the environment variable in a
command window. The command prompt is ">> ".
>> set JCL_CASCANNER_P0B=E:\DMS\Domains\JCL\OS\Analyzers\CAScanner\CAScanner.P0B
Warning: Any spaces at the end of the line will be included in the value of the variable!
After setting the environment variable, you can confirm the setting as shown below.
>> set JCL_CASCANNER_P0B
JCL_CASCANNER_P0B=E:\DMS\Domains\JCL\OS\Analyzers\CAScanner\CAScanner.P0B
>> dir %JCL_CASCANNER_P0B%
Volume in drive E is User Data
Volume Serial Number is 846E-C769
Directory of E:\DMS\Domains\JCL\OS\Analyzers\CAScanner
05/28/2014 04:11 PM 17,774,763 CAScanner.P0B
1 File(s) 17,774,763 bytes
0 Dir(s) 185,611,730,944 bytes free
[1.2.3] Using the DEBUG version of the JCL CAScanner
Often a debug version of the scanner is installed in the same
directory as the production version. The two versions have different
file names.
The production version of the scanner will be named:
CAScanner.P0B
The debug version of the scanner will be named:
CAScanner_DEBUG.P0B
If you with to run the DEBUG version, instead of the production
version, set the environment variable JCL_CASCANNER_P0B to the file
path to CAScanner_DEBUG.P0B, instead of to the file path to
CAScanner.P0B.
[1.3] Locate the PARLANSE run-time system.
[1.3.1] Typical file lcoation
It PARLANSE run-time system (executable) will usually be under the DMS root as
DMS\Domains\PARLANSE\Tools\RunTimeSystem\run.exe
[1.3.2] Set the environment variable RUNNER to the file path to run.exe.
Here is an example of setting the environment variable in a
command window. The command prompt is ">> ".
set RUNNER=E:\DMS\Domains\PARLANSE\Tools\RunTimeSystem\run.exe
After setting the environment variable, you can confirm the setting as shown below.
>> set RUNNER
RUNNER=E:\DMS\Domains\PARLANSE\Tools\RunTimeSystem\run.exe
>> dir %RUNNER%
dir %RUNNER%
Volume in drive E is User Data
Volume Serial Number is 846E-C769
Directory of E:\DMS\Domains\PARLANSE\Tools\RunTimeSystem
03/06/2014 10:57 AM 872,448 run.exe
1 File(s) 872,448 bytes
0 Dir(s) 185,611,726,848 bytes free
Test the PARLANSE run-time system via the command
>> %RUNNER% -v
If this succeeds, you should see output something like the
example below. The exact output you see may differ due to
differences in the version of the run-time system you are using.
If this fails with a Windows error message, see the trouble-shooting section below.
PARLANSE RUN Version 19.1.50 Copyright 1998-2013 Semantic Designs, Inc.; All Rights Reserved
run [options] filename[.p0b|.P0B]
where options can be any combination of the following:
-B,-b breaks execution before main is called
-Cn specifies priority class (0 = lowest, 4 = highest)
-d debug mode (disables exception handler to catch h/w exceptions)
-D[options] specifies various kinds of debugging support:
1) s = support for tracking live semaphores
2) m = support for tracking memory in pools
-Fcd Sets flag c to 0 or 1
-L,-l prints address of each instruction that is loaded
-Pn,-pn specifies number of processors = n
-Q[options] specifies various parameters for ready queue:
1) Ln = length of the ready queue is n
2) Wn = wait interval (scans of other queues) when no local work
3) Sn = sleep interval(milliseconds) when no local work
-Tn,-tn specifies the timeslice duration as n milliseconds
-t[option] only do: I=interrupt;, G=garbage-collect; S=time slice;
F=T/S + GC on foreign calls; none=ForeignCall GC
-V,-v prints details of runtime parameters and total computation time
-Yn,-yn specifies the maximum backtrace size.
-Z,-z Turn off console output buffering.
[System Identification: 3e9b1066]
[1.4] Set the INPUT ENCODING appropriately.
The JCL scanner can process input files using different input
encodings. In particular, the scanner can process input files using
these character set encodings:
-- EBCDIC character set (with a fixed-length records of 80 characters)
-- ASCII (with variable-length records using CR/LF as line delimiters)
You should set the environment variable DMS_JCL_OS_INPUT_ENCODING as
shown below according to the character-set encoding used in the JCL
file to be scanned.
If you need to scan a file using a different character-set encoding,
contact support at CMFirst or Semantic Designs.
[1.4.1] If the file is ASCII:
>> set DMS_JCL_OS_INPUT_ENCODING=ISO-8859-1
[1.4.2] If the file is EBCDIC:
>> set DMS_JCL_OS_INPUT_ENCODING=CP-037+R80
[1.5] Set up PDS includes
[1.5.1] Summary
The JCL CAScanner can mirror JCL accesses to some PDS members. This
mechanism is enabled by the following steps:
* set DMS_JCL~OS_INCLUDE_PATH to the root of the include path
* set DMS_JCL~OS_SYSTEM_LIBRARY if necessary (this is rare)
* export the PDS members to directories of the same name under the include path
These steps are detailed below.
The JCL CAScanner uses a unified PDS lookup system for:
* Cataloged Procedures (for EXEC statements)
* Include Groups (for the INCLUDE statement)
* PDS member lookup (for resolving DSNs in DD statements)
[1.5.2] DMS_JCL~OS_INCLUDE_PATH
The lookup system uses the value set in the environment variable
DMS_JCL~OS_INCLUDE_PATH
as the root of its search, e.g.
set DMS_JCL~OS_INCLUDE_PATH=C:\Input\include_directory
The scanner searches the include path through directories using the
PDS name and member name. For example,
//SYSTSIN DD DSN=A.B(CALL1)
would match a file in
include_path\A.B\CALL1
Note there is no file-name extension on the file standing in for the PDS member.
[1.5.3] Move PDS member files to the include path
Move the PDS member files to the appropriate directory under the
include path.
Be sure that the member files are encoded with the same character
encoding as the JCL file. (See the setting of
DMS_JCL_OS_INPUT_ENCODING in section 1.4.)
[1.5.4] Default location for unqualified PDS members
The default PDS to search (when no PDS path is specified) is
SYS1.PROCLIB
This is usually appropriate (e.g., for standard cataloged
procedures). In the rare cases where this is not correct, set the
environment variable
DMS_JCL~OS_SYSTEM_LIBRARY
to name the desired PDS. Use the PDS name which will be the same as
the directory name under the DMS_JCL~OS_INCLUDE_PATH. The default behavior is as if
you set the environment variable via
set DMS_JCL~OS_SYSTEM_LIBRARY=SYS1.PROCLIB
and the PDS members would be put into the SYS1.PROCLIB directory
under the include path.
[1.6] Running the scanner
[1.6.1] Change the current directory to be the directory containing the JCL input file.
[1.6.2] Execute the scanner.
Below we will assume the input file is named "example.jcl".
The following command will run the JCL scanner on the input file "example.jcl"
and write the XML output file to "example.jcl.xml"
>> %RUNNER% %JCL_CASCANNER_P0B% example.jcl example.jcl.xml >example.jcl.log
This command should run the JCL scanner, producing an XML output file
and capturing the console output in a log file.
If this fails with a Windows error message, see the trouble-shooting section below.
The log file should look something like the example below. The exact
output may vary due to which version of the scanner is being run and
whether the scan produces any warning messages or error messages.
JCL~OS CAScanner Version 1.2.13P
Copyright (C) 2010 - 2014 Semantic Designs, Inc; All Rights Reserved; SD Confidential
Powered by DMS (R) Software Reengineering Toolkit
.-
-Issue NR2W in line 20 column 1 of file "E:/TESTS/CASCANNER/JCL/input/example.jcl":
Could not locate EXEC PROC target named PROC123.
Exiting with final status 0.
[2] Trouble Shooting
[2.1] Execution fails for the PARLANSE run-time system or accessing the .P0B file.
A typical symptom of this problem is that the Windows' command shell
will print an error message something like this:
'run.exe' is not recognized as an internal or external command,
operable program or batch file.
If the DMS tree is installed under the standard Windows directory
"\Program Files (x86)", Windows' User Access Controls (UAC) may
prevent standard commands from accessing the files. In this case
copying the run-time system (run.exe) and the PARLANSE binary file
(.P0B file) to another directory usually resolves the issue.
[3] Suggestions and Support
If you have any suggestions for improves to this document, or any
problems using this procedure, contact support at CMFirst or Semantic
Designs.
[4] Change Log
Version 0.2: Updated to support external PROCEDURE definitions.