Thank you for being a valued client of CM First Group. If you have any technical issues or concerns, please open a ticket on support.cmfirstgroup.com, email CM First technical support at support@cmfirstgroup.com or call us on our 24/7 customer hotline at +1 (512) 623-7586.

Follow

Running JCL Scanner by Hand

 

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.

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments

Powered by Zendesk