JCL Skeletons

This section describes the use of JCL skeletons.

There is a JCL skeleton for each function in each operating system. The skeleton contains the command statements required for the operating system to call and execute the function. A JCL skeleton consists of JCL lines and parameters, and is identified by a function name and the name of the operating system.

Note:
SMA internally uses the notations OS/MVS, VSE/SP, and BS2000 for designating the operating system and default environment. These notations directly correspond to the operating systems z/OS, z/VSE, and BS2000/OSD, respectively.


JCL Skeletons

Parameters

JCL skeletons consist of JCL text as well as parameters. The parameters are replaced during JCL generation with current values.

Parameters are delimited using the character #.

The following parameters are provided:

Parameter Description
#V-<name># Environment parameters. You can use the function Reports to obtain a list of all environment parameters.
#G-<name># Global parameters. You can supply values for these parameters by using the function Global Parameters in the Administration menu.
#I-......# Include another skeleton. See the section Include Skeleton below.
#D-......# Data set properties. See the section Data Set Properties below.
#N-…..# Natural system variables. See the section Natural System Variables below.
#P-......# SMA internal parameters. These parameters must not be changed.
#S-......# Special parameters. See the section Special Parameters below.
#T-nnn# The position (nnn) where the next character is to be placed in the line. This parameter is needed if characters following other parameters are to appear at fixed positions.

Include Skeleton

The Include parameter can be used within a skeleton to include another JCL skeleton. It must be placed at the beginning of a line.

Option 1

#I-<skeleton-name>#

The named skeleton is to be included at this point in the skeleton.

Includes may be nested; i.e., the included skeleton may also contain an Include parameter.

Within a skeleton name, a product name denoted with the characters &&& may be used instead of the product version number. The characters &&& will be replaced by the installed version of the product. This feature can be used, for example, for the Natural link as shown by the example below:

#I-INCL-NAF&&&#

In the above example, if NAF version 414 is installed or to be installed, then skeleton INCL-NAF414 will be included.

Option 2

 #I-P-<PIPARM-name>#

The Include parameter contains the name of an SMA-internal parameter. The evaluated value of this internal parameter is taken as the name of the skeleton to be included.

Data Set Properties

The D- parameter is used to provide two types of data set information, attributes and dataset.

#D-<attribute> (<dataset>)#

<attribute>

<attribute> Description
D-DSN-D Data set name on disk
D-DSN-T Data set name on tape
D-DSN-U Data set name on disk, delimiter character "." will be replaced by the character "/".
D-VOL-D Volume serial number of the disk the data set is on
D-VOL-T Volume serial number of the tape the data set is on
D-LBL Label number on the tape
D-N-BLK Number of blocks
D-RECFM Record format
D-BLKSZ Block size
D-LRECL Record length
D-DSORG Data set organization
D-D-BLK Number of directory blocks (if the data set is a library)
D-T-C Date and time of creation
D-DEV Device type of the disk, if on disk; or of the tape, if not on disk
D-SPACE Text of the space allocation parameter

<dataset>

The following may be specified with <dataset>:

  • Symbolic data set name (for example, NAT414.LOAD).

  • Symbolic data set name, with the characters &&& instead of the product version number. The characters &&& will be replaced by the installed version of the product.

  • SMA-internal parameter (for example, P-DSN).

Example 1

Library names in link edit steps
//... DD DSN=#D-DSN-D(NAT&&&.LOAD)#,DISP=SHR
//... DD DSN=#D-DSN-D(ADA&&&.LOAD)#,DISP=SHR

Example 2

General copy skeleton tape to disk
//SYSUT1 DD DSN=#D-DSN-T(P-DSN)#,DISP=(OLD,PASS),
//           VOL=SER=#D-VOL-T(P-DSN)#, ....

Example 3 (z/VSE only)

// LIBDEF PHASE,SEARCH=(.............,,                                X
               #D-DSN-D(WCP&&&.LIBR)#,#D-DSN-D(MLC&&&.LIBR)#,          X
               #D-DSN-D(ADA&&&.LIBS)#,PRD2.TCPIPC,                     X
               PRD2.CONFIG,PRD2.SCEEBASE)

Would generate:

// LIBDEF PHASE,SEARCH=(.............,,                                X
               SAGLIB.WCP632,SAGLIB.MLC134,                            X
               SAGLIB.ADA842,PRD2.TCPIPC,                              X
               PRD2.CONFIG,PRD2.SCEEBASE)

for an installation of Entire Net-Work (WCP) Version 6.3.2, License Processing (MLC) Version 1.3.4, and Adabas Version 8.4.2.

Note:
The parameter for D-DSN-D on z/VSE for a sublibrary is <prdvrs>.LIBR except for the Adabas sublibrary, which is ADAvrs.LIBS but NOT for associate Adabas sublibraries such as ADAvrsTZ.LIBR or WALvrs.LIBR, where <prdvrs> is the Product Code and Version Number.

Natural System Variables

The parameter is replaced by the value of the specified Natural system variable.

For example, #N-USER# will be replaced by the value of the Natural system variable *USER.

Note:
In order to ensure that SMA remains downwards compatible to the Natural version, not all Natural system variables are supported by SMA.

Special Parameters

The following special parameters can be specified:

#S-<keyword>#
Special Parameter Description
S-DATE Date of job generation
S-DBID DBID for current SMA dialog
S-DESC Job description for this Job ID
S-ENV Name of environment for which JCL is currently being generated
S-FDIC FDIC for current SMA dialog
S-FNAT FNAT for current SMA dialog
S-FSPOOL FSPOOL for current SMA job generation
S-JOB Job ID from the PIN entry
S-PINISN ISN of the control record of this step
S-PROD Name of the product to which this step belongs
S-PRODNAM First three characters of S-PROD
S-PRODVER Last three characters of S-PROD
S-SEQ Sequence number of the step
S-SMALIB SMA library
S-SMA-LFILE LFILE specification for SMA data
S-TIME Time of job generation

Conditional Selection of JCL Steps and Lines

The generation of a JCL line can be made dependent on the evaluation of simple or complex conditions. Press PF11 during editing of the JCL skeleton to modify these conditional parameters.

Elementary Conditions

The elements which can be used in these conditions are:

Element Description
BATCH Use this JCL line only when writing the generated JCL to a work file (only valid in batch mode). The statements used to separate the work file should be marked with this condition.
DISK Use this JCL line only when the data set which was last used in a #D-...# parameter is on disk.
ONLINE Use this JCL line only when writing the JCL to the SMA system file (only valid in online mode).
SECU Use this JCL line only if Natural Security is installed.
TAPE Use this JCL line only when the data set which was last used in a #D-...# parameter is on tape.
<pppnnn> Use this JCL line only if the product pppnnn is marked as installed or to be installed. ppp is the product name and nnn is the version number. The version number can be truncated or omitted (for example, ADA743, ADA73, ADA7 or ADA are all acceptable).
=<pppnnn> Use this JCL line only if the product pppnnn is marked as to be installed or is installed; but do not use it, if it is marked as installed and another version of the same product is marked as to be installed.
><pppnnn> Use this JCL line only if the product pppnnn or a higher version is marked as to be installed or is installed; but do not use it, if it is marked as is installed and a lower version of the same product is marked to be installed.
<<pppnnn> Use this JCL line only if the product pppnnn or a lower version is marked as to be installed or is installed; but do not use it, if it is marked is installed and a higher version of the same product is marked to be installed.
$<pppnnn> Use this JCL line only if the product pppnnn is marked as to be installed and is not already installed.
#<parm> Use this JCL line only if the parameter specified by parm has a value other than NO, N or blank in the current environment.

Complex Conditions

Product and variable names can be combined to form complex conditions using opening and closing brackets, and the following operators.

The rules for combining the elementary conditions using these operators follow the usual conventions. No blanks are allowed within the condition. Maximum nesting of expressions is 6.

Operator Description
+ OR condition. Use the JCL line if at least one of the conditions is true.

Example: Use this JCL line if either product ADA or NAT is installed:

ADA+NAT

* AND condition. Use the JCL line if all conditions are true.

Example: Use this JCL line only if the products ADA and NAT are installed:

ADA*NAT

^ NOT condition. Use the JCL line if the condition is not true.

Example: Use this JCL line only if the product CNT is not installed:

^CNT

Modifying or Replacing JCL Skeletons

JCL Skeletons may be modified or replaced by the user or by Software AG. A JCL skeleton will be replaced by Software AG when the tables on a new product installation medium contain a revised version of an existing skeleton. This may be necessary in order to satisfy new requirements for a new product.

The LOAD program will replace skeletons in the default environment, but will not replace skeletons which have been modified by the user in a user environment. In both cases, the user will be informed by a warning message.

For more information on modifying JCL skeletons for a particular user environment, see the following sections:

Creating Additional JCL Skeletons and Environment Parameters

If SMA is used intensively, it may be desirable to add additional parameters or JCL skeletons.

Start of instruction setto add parameters or JCL skeletons:

  1. Create a work file (a member) containing input in SMA LOAD format which contains the new parameters and skeletons. This file must consist of 80-byte records, and can be created using any standard source editor. The last record must be a comment line.

  2. Run the SMA LOAD function using the file created in Step 1 as Work file 1.

Comment Lines

Comment lines can be entered in the format:

##*** ... comments ... 

Comment lines should be used frequently for better readability of the table input members.

Creating JCL Skeletons

Syntax:

##JCL,<function>,<environment>,<change-allowed>[,<version>]
 
[,<description>]
JCL lines…
Parameter Format Length Description
<function> A 1-20 Name of the JCL skeleton, as used in the Include parameter #I-... #. The maximum length is 18 characters.

Note:
The name of the skeleton should always start with CUSTOMER-... in order to avoid conflict with names of skeletons supplied by Software AG.

<environment> A 1-8 Environment name
<change-allowed> A 1 Always Y
<version> N 6 A version date of this skeleton, as a 8-digit number in the form yyyymmdd, is optional. If a version is present, the loader will load the skeleton only if it was created later than the existing skeleton.
<description> A 0-40 Explanatory text for the skeleton

Creating Environment Parameters

Syntax:

##PRPARM,<opsys>,<parameter-group>,<parameter-name>,<change-allowed>,
<Alpha or Numeric>,<Min.Value>,<Max.Value>
<Default value> [,<Possible values>]...
<Description line>
[<Description line>] …
Parameter Format Length Description
<operating-system> A 8 Valid values for operating-system are: BS2000, OS/MVS, VSE/SP
<parameter-group> A 6 The name of the parameter group (should be CUSTOM in order to avoid conflict with parameters supplied by Software AG)
<parameter-name> A 1-20 The name of this parameter (should always start with CUSTOMER-... in order to avoid conflict with parameters supplied by Software AG)
<change-allowed> A 1 Always Y
<Alpha or Numeric> A 1 A: parameter is alphanumeric, N: parameter is numeric
<Min.Value> N * Minimum possible value (for numerical fields only)
<Max.Value> N * Maximum possible value (for numerical fields only)
<Default value> A/N 0-72 Default value for this parameter (alpha or numeric).
<Description Line> A 1-72 Explanatory text for the parameter. The maximum length is 72 characters per line (max. of 20 lines).

The definition of an environment parameter requires 2 to 26 lines. The first line contains the parameter definition. The second line contains possible values for this parameter separated by a comma. The following 24 lines contain explanatory text for this parameter.

The SMA loader takes the first of the possible values and includes it as a default value in all environments where no value is already present. If a value already exists for this parameter, then this value remains unchanged.

Parameters created in this way can be used in any JCL skeleton.

Example

The following is an example for defining an environment parameter and the related JCL skeleton:

Start of instruction setto define an environment parameter and related JCL skeleton:

  1. Define parameter CUSTOMER-DEPT and JCL skeleton CUSTOMER-JC:

    Create the input file for SMA LOAD using any source editor:

       ##PRPARM,OS/MVS,CUSTOM,CUSTOMER-DEPT,Y,A,1,32 
       F-OD
    
       DATA CENTER OWNING THIS SMA ENVIRONMENT
       ##*** --------------------------------------------------------------- 
       ##JCL,CUSTOMER-JC,OS/MVS,Y,,ADDITIONAL JOB-CARD LINES
       //* -------------------------------------------------
       //* SOFTWARE AG INSTALLATION JOB.
       //* OWNER: #V-CUSTOMER-DEPT#
       //* -------------------------------------------------
      ##*** COMMENT LINE: MUST BE THE LAST LINE
  2. Load the definition created in Step 1 into an SMA file.

  3. Using the definition in an existing skeleton JOB-CARD, add the line #I-CUSTOMER-JC# at the end of the skeleton in order to include the new skeleton.

The JCL Generator will extend the job cards using the skeleton CUSTOMER-JC in all subsequent JCL generations.