Chapter 22: Configuring Enterprise Servers for JCL

This chapter describes how to create and configure JCL-enabled enterprise servers.

Enabling JCL for an Enterprise Server

You enable JCL on an enterprise server by using Enterprise Server Administration (for an introduction to this tool, see the chapter Introduction to Enterprise Server Administration in your Enterprise Server Configuration and Administration Guide).

Note: You need the appropriate license before you can use an JCL-enabled enterprise server.

How to

SEPs for JCL

Two special types of service execution process are required to run JCL jobs. These are:

Batch initiator SEPs. A batch initiator SEP runs jobs.
Batch printer SEPs. A batch printer SEP handles the sending of output to a printer.

Both types of SEP have a class property. The JOB CLASS of a JCL jobstream must match the class of a batch initiator SEP in order for the SEP to run the job. The MSGCLASS or SYSOUT class must match the class of a batch printer SEP in order for the SEP to print the output.

You can either define permanent batch initiator and printer SEPs or create SEPs during a session that exist only until the end of the session.

How to...

When you define a batch printer SEP, you can specify a printer exit module, which enables you to perform additional formatting of output data before it is printed. For more information see the section Printer Exit Modules in the chapter JCL Support in your MSS Developer's Guide, if you have the development documentation available.

If you want to create a batch printer SEP that uses a printer accessed across a network, you need to have started the enterprise server from the command line or from reUZE Developer; if you start it from ES Admin, it runs as a system service and the network printers defined on your machine are not available.

Shared Memory Area

The shared memory area calculation for a JCL-enabled enterprise server is the same as for a Web services enterprise server, as described in the section Enterprise Servers in the chapter Configuration in your Enterprise Server Configuration and Administration Guide. Note that you must include your batch initiator and batch printer SEPs in the total number of service execution processes.

If you also run CICS applications in the same enterprise server, you will also need to perform the calculations described in the section Shared Memory Area in the chapter Configuring MSS-enabled Enterprise Servers for CICS and add the results to the total.

Environment Validation

When you start an enterprise server, a utility called DFHZJCL2 runs automatically to check for some common set-up errors that might otherwise be hard to spot. For example, it checks that the system catalog and default allocation location are both usable. If a problem is found, it displays a message on the console log.

For example, should the catalog be unusable there will be a message in the log saying: "Catalog Open IVP test failed".

Once it has completed the validation DFHZJCL2 schedules the spool housekeeping by issuing a CICS START for transaction JCL1.

Spooler Housekeeping

When you start an enterprise server, a CICS transaction called JCL1 runs automatically to delete old spool files. You can configure how often this happens and how long spool files are kept for.

The housekeeping process involves the following programs: DFHZJCL1, DFHZJCL3, MVSP0027. The validation program described in the previous section starts the transaction JCL1, which runs the program DFHZJCL1. This program does the following:

LINKS to DFHZJCL3 to get the Housekeeping Frequency (i.e. how often spool housekeeping should be run) and the Housekeeping Retain Period (i.e. how long spool files should be kept prior to automatic deletion).
CALLS MVSP0027 passing the Housekeeping Retain Period. MVSP0027 deletes any spool files older than the retain period.
STARTS JCL1 after the interval specified in Housekeeping Frequency
Displays messages on the console saying that the spool housekeeping has:
- started: SPOOL CLEAN-UP started
  and
- finished (successfully or not ): SPOOL CLEAN-UP ended normally, maximum retain period is 6 days.

Setting the Retain Periods

You configure the retain periods by editing and recompiling DFHZJCL3, one of the programs run during the housekeeping process. DFHJCL3 uses a user modifiable copybook which contains the run frequency and retain period values. The copy book is SPOOLHK.CPY a portion of which is reproduced below. Set the values as required (see below) and recompile DFHZJCL3.

      **********************************************************************************
      *  This copy book controls the spool housekeeping.
      **********************************************************************************
      *      ws-run-frequency
      *          this field controls how often the spool clean-up is run
      *          it is stated in days
      *      ws-keep-for
      *          this field contains the default retention period in days for
      *          spooled output
      **********************************************************************************
           03  default-settings.
             05  ws-version                      pic x(8)
                          value 'SPHK 1.0'.
             05  ws-run-frequency                pic 99999 value 1.
             05  ws-keep-for                     pic 99999 value 6.
      **********************************************************************************
      *    The following fields contain the retention periods for spooled output by class
      *    and a flag indicating whether spool files in this class should be archived on
      *    deletion.  There are 36 entries, A through Z and 0 through 9.
      *    If the value is set to 99999 then the default value from ws-keep-for
      *    will be used. A Y indicates that spool files should be archived upon deletion.
      *    These ws-keep-for values are DAYS.
      *    To change the retention period edit the appropriate values and recompile
      *    DFHZJCL1.cbl
      *    e.g.  to change the class A retention period to 1 week and specify that no
      *    archiving is required:
      *    edit the first  filler for class A so that the value is 7
      *    edit the second filler for class A so that the value is N
      *    giving:
      *      class A
      *      05  filler                           pic 99999 value 00007.
      *      05  filler                           pic x     value 'N'  .
      **********************************************************************************
           03 ws-class-settings.
      *      class A
             05  filler                           pic 99999 value 00001.
             05  filler                           pic x     value 'N'  .
      *      class B
             05  filler                           pic 99999 value 00002.
             05  filler                           pic x     value 'N'  .

Setting the Default Retain Period and Run Frequency

The comments in the copybook explain the field values

 05  ws-run-frequency                pic 99999 value 1

Change the value of ws-run-frequency to the number of days that you want to elapse between runs of spool housekeeping.

05  ws-keep-for                         pic 99999 value 6

This is the default retain period and applies to ALL spool output. Change the value of ws-keep-for to the maximum number of days that you wish to keep spool output for. (This includes: i) Any held output for SYSOUT classes with no specific retention period ii) Any output that was scheduled for printing which is still on the spool print queue)

Note: The retain interval is in days. Using one day is not recommended as a run shortly after midnight would delete spool files written the late previous night; that is, files that are only a few minutes or hours old.

Setting the Retain Period and Archive Flag for Specific Held Classes

             05  filler                                 pic 99999 value 99999.
             05  filler                                 pic x     value 'N'  .

For those HELD output classes where the output should be deleted after a SHORTER interval than the above default retain period, edit the first value for the appropriate class.

If you want to archive the contents of the MVS SPOOL spool file prior to deletion, change the second value to ‘Y’. The file will be copied to the location specified in the environment variable MF_SPOOL_ARCHIVE_LOC.

Running the Spool Housekeeping Program from JCL

The spool house keeping program, MVSP0027, can be called in batch from a user-written program run by JCL.

To do this, you must write your program to assign the fields as indicated by the instructions in copyfile, spoolhk.cpy (this can be found in your base/source directory), and call MVSP0027. For example:

Example JCL to call your program

//EXAMP1 JOB 'CPTEST',CLASS=A,MSGCLASS=A
//STEP01 EXEC PGM=MFSPHK01
//SYSOUT DD SYSOUT=*
//OFILE  DD SYSOUT=*

Example program to invoke housekeeping

000100 IDENTIFICATION DIVISION.
000300 PROGRAM-ID. MFSPHK01.
003100***************************************************************
004600 ENVIRONMENT DIVISION.
004700 input-output section.
       file-control.
           select infile assign to ifile organization is sequential
                  file status is status-codei.
           select outfile assign to ofile organization is sequential
                  file status is status-codeo.
       DATA DIVISION.
       file section.
       fd  infile.
       01  inrec                         pic x(80).
       fd  outfile.
       01  outrec                        pic x(120).
       WORKING-STORAGE SECTION.
       01 status-codei                   pic xx.
       01 status-codeo                   pic xx.
       01 ws-message                     pic x(120).
       01  spool-hk-settings.
           copy spoolhk.cpy.
       01  ws-mvsp0027-rc                pic xx comp-5.
       01  ws-mvsp0027-reason            pic xx.
       01  disp-num                      pic 99.
       PROCEDURE DIVISION.

      *****************************************************************
      *                                                               *
      *****************************************************************
       0000-MAINLINE-MODULE.
           move 0 to ws-mvsp0027-rc 
           call 'mvsp0027' using spool-hk-settings
                                ws-mvsp0027-rc
                                ws-mvsp0027-reason
           move spaces to ws-message
           evaluate ws-mvsp0027-rc
             when 0
               string
                    'SPOOL CLEAN-UP ENDED NORMALLY' delimited by size
                    ' maximum retain period is '    delimited by size
                     ws-keep-for                    delimited by size
                     ' days. '                      delimited by size
               into ws-message
             when 4
               string
                    'SPOOL CLEAN-UP ENDED, '        delimited by size
                    ' empty CASSPOOL/MVSSPOOL  '    delimited by size
                    ' maximum retain period is '    delimited by size
                     ws-keep-for                    delimited by size
                     ' days. '                      delimited by size
               into ws-message
           when other
               move  ws-mvsp0027-rc  to disp-num
               string
                    'SPOOL clean-up failed RC = '  delimited by size
                     disp-num                      delimited by size
                    ' reason code = '              delimited by size
                     ws-mvsp0027-reason            delimited by size
               into ws-message
           end-evaluate
           display ws-message upon console
           goback.

       FILE-INPUT SECTION.
           perform open-infile
           perform read-infile
           PERFORM UNTIL status-codei NOT = '00'
              *> populate mvsp0027 parms
              perform read-infile
           end-perform
           .

       open-infile section.
           open input infile
           if status-codei = '00'
               continue
           else
               move 12 to return-code
               goback
           end-if
           .
       read-infile section.
           read infile
           evaluate status-codei
               when '00'
               when '10'
                   continue
               when other
                   move 16 to return-code
                   goback
           end-evaluate
           .

Controlling where Datasets are Created

To override the default location used during the creation of datasets, you can configure Enterprise Server to consult a file containing rules that determine where new datasets are created.

You do this by setting the ES_ALLOC_OVERRIDE environment variable to the location of the "rules" file. Each rule in the file specifies: an offset from the beginning of the catalog record, a value that will be found at the offset in records for datasets that match the rule, and a directory in which the files for those datasets will be created.

For example, the following rule:

OFFSET(n) VALUE (MYSTRING) SUBDIR (C:\MYDIR\MYSUBDIR)

will allocate to C:\MYDIR\MYSUBDIR all files that contain the string "MYSTRING" at position n of the catalog record. The catalog structure is defined in the copyfile: mvscatlg.cpy. This is located in your install-dir/base/source directory.

Each rule must occupy only 1 line and all keywords must be in uppercase. Rules are processed in the order that they appear in the file, and the first one that matches is the one that is used; that is, no further rules are consulted for that dataset.

Example rules file

#  Key off of the spool indicator
OFFSET(313) VALUE(S) SUBDIR(C:\MVSP0030\SPOOL)
#  Key off of the VOLUME value.
OFFSET(314) VALUE(CSIWRK) SUBDIR(C:\MVSP0030\VOLUME) 
#  Key off of the DSORG
OFFSET(324) VALUE(VSAM) SUBDIR(C:\MVSP0030\VSAM)
#  Key off of the LRECL
OFFSET(469) HEXVALUE(0063) SUBDIR(C:\MVSP0030\LRECL99)
#  Key off of the first 6 bytes of the dataset name
OFFSET(1) VALUE(MFIDMF) SUBDIR(C:\MVSP0030\MFIDMF) 
#  Key off of the DATACLAS value.
OFFSET(449) VALUE(MFIDMFY) SUBDIR(C:\MVSP0030\DATACLAS)

Note:

If you want your catalogs to be portable it is a good practice to have the "Subdir" directories at the same level in the directory structure or in directories that are children of the directory containing the catalog.dat file. In the example below we recommend that the catalog.dat be located in C:\MVSP0030\ This is not an absolute requirement, but will help your maintenance.
When you are specifying the name of the subdirectory to which files should be allocated, you can specify the string <CatalogFolder> to indicate the directory in which the catalog is stored. For example:
```
OFFSET(313) VALUE(S) SUBDIR(<CatalogFolder>\SPOOL)
```
You can also use environment variables when specifying the subdirectory to which files should be allocated. For example:
```
OFFSET(313) VALUE(S) SUBDIR($APPROOT\SPOOL)
```
where APPROOT is the environment variable. The environment variable will be expanded before it is used in the pc dataset name field in the system catalog.

Restarting Jobs

Enterprise Server provides support for restarting JCL jobs at a specified step and optionally a procstep. A typical sequence of events is as follows:

The job completes and remains on the Output Hold queue.
The user requeues the job for restart using either ESMAC, the casout command, or the callable API, specifying the step and (optionally) the procstep.
The job is put back into the Input queue.
The job is rescheduled and restarts at the specified step/procstep.

Enabling job restart functionality

The restart functionality is governed by two environment variables:

ES_JES_RESTART

Setting this variable to Y has the following effects:

ESMAC will display new fields for a job's details on the Output Hold queue, along with a Restart button. The new fields allow you to specify the step and procstep at which the job is to restart.
When a job is run, the LEX files associated with the job will no longer be cleaned up when the job is completed; instead, these files will be cleaned up when the job is deleted.

MF_UCC11

Setting this environment variable to Y enables:

Automatic reset of the GDG bias to the level of the prior run of the job; that is, the restart will automatically pick up the "correct" GDG Bias.
Restarting a job with DISP=(NEW,CATLG) datasets will not result in job failure due to the dataset already being cataloged.
COND Code Processing and IF/THEN logic that is dependent upon COND codes from prior steps that are skipped by the RESTART will work as expected with no changes to the JCL.

Restarting a Job

You can restart a job through:

the ESMAC Job Details Page for a job on the "Output Hold" queue
the casout command line (e.g. casout -r<Servername> -j<jobnumber:step:procstep> )
driving the casout callable api

CASOUT provides the following return codes:

Code	Description
0	Success
8	The job is not in the "Output Hold" queue
12	There was a failure in moving the job to the input queue. For more detailed diagnostic information on the cause of the failure, you can turn on CTF tracing for the "restart" property of the mf.mvs.casspool component.
16	The job does not exist
32	Restart processing is not turned on. (You must set the ES_JES_RESTART environment variable in order to enable restart processing.)

Non-restartable steps

You cannot restart a job at a step if that step contains:

a //UCC11NR DD DUMMY statement
any temporary datasets that have DISP of SHR or OLD

Processing during restart

On a restart:

The joblog and all other SYSOUTs will be extended with new data unless they have already been printed/deleted.
Any DISP=NEW datasets will cause an already existing dataset to be deleted before allocation.
Any DISP=MOD datasets that already exist will be extended.
Any DISP=OLD datasets will be over-written.

At the conclusion of the restarted job, its new execution state (step condition codes) will be saved for a future restart.

Note:

A non-unique restart step/procstep is resolved to its first occurrence and a message is issued upon restart. This is the same behavior as RESTART= on the JOB statement.
When a job is deleted from the Output Hold queue in ESMAC, from the casout command, or via the automated spool cleanup mechanism, all traces of the job are removed and it can no longer be restarted.

GDG Processing during Restart

When a job that uses GDG bias is restarted, all references to a GDG relative bias (e.g. +1, -3) will cause the DD statement to reference the same physical file as the original job. The only time that this will not be true is where the processing of the original job (or of other jobs that were run after the original job) has caused the GDG Bias to be rolled off, scratched, or deleted.

In the case of most mainframe jobs there will be no issues but you should be aware of the following scenarios:

Where a job runs to successful (non-abend) completion and this results in a GDG Bias being rolled off, that Bias will not be available on the restart and any step which references that bias will fail with a "dataset not found" message.
Where a different job, which references the relevant GDGs and creates new relative biases, runs between the end of the job in question and before the job restart takes place, it is possible that the bias referenced by the restarted job will no longer be present.
Where a job abends prior to completion, the abnormal termination disposition is applied as specified by the DISP= statements in the JCL. In this scenario you will encounter problems if the step at which you restart references a bias that doesn't exist as a result of the prior abnormal termination.