Chapter 19: Configuring MTO-enabled Enterprise Servers for JCL

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

Enabling JCL for an Enterprise Server

You enable MTO and JCL on an enterprise server in the same way on both Windows and UNIX.

To enable MTO and JCL, you use 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 MTO-enabled enterprise server.

How to

SEPs for JCL

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

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...

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 MTO-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:

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 , 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 $COBDIR/demo/esjcl 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:


Copyright © 2006 Micro Focus (IP) Ltd. All rights reserved.