August 1998
Newsletter

IOFTech    Maintenance   Release8G       Newsletters    Doc    FAQ    Contacts    Home    Webmaster

IOF Batch Utilities

Topics

Introduction

IOF can be run under batch TSO to provide the same function that is available to a terminal user. Sophisticated management control functions can be automated when IOF is invoked and controlled via a Rexx exec or clist in TSO batch.

Everything that a terminal user can do with IOF can be done using a Rexx exec or TSO clist. All fields that are displayed on the terminal can be assigned to Rexx or clist variables. Standard Rexx and clist facilities can then be used to process the variables. IOF clists and execs must reside in an exec or clist library that is part of the batch TSO session's SYSEXEC or SYSPROC DD concatenation.

Batch utility functions are most useful for operations and systems staff who have access to all or most jobs in the system. Most functions also can be executed by end users to manage and control their own jobs.

Several batch utility functions are shipped with IOF as members of the CLIST library. A few of the most popular functions are detailed below along with specific examples of optional parms.

IOF Cataloged Procedure

An IOF cataloged procedure makes it easy to run a variety of utility functions, including locally written functions in batch TSO. A working sample procedure is shown below.

//BATCHIOF PROC     OPT=                       
//TMP      EXEC PGM=IKJEFT1B,PARM='&OPT'       
//SYSTSPRT DD   SYSOUT=*                       
//SYSHELP  DD   DISP=SHR,DSN=prefix.IOFT7D0.HELP   <--- your HELP library  
//SYSPROC  DD   DISP=SHR,DSN=prefix.IOFT7D0.CLIST  <--- your CLIST library
//SYSTSIN  DD   DUMMY 
//         PEND

Many batch functions can be run by invoking a Rexx exec or clist with one or more parms. In these cases the BATCHIOF procedure can be invoked by specifying the clist/exec name and any parms in the OPT parm. For example, to invoke the OUTQUE clist with a parm of AGE(14):

//OLDJOBS  EXEC  BATCHIOF,
//         OPT='OUTQUE AGE(14)'
More complicated command streams can be specified by overriding the SYSTSIN DD statement. The example below invokes OUTQUE multiple times in the same batch TSO step.

//OLDJOBS  EXEC  BATCHIOF
//SYSTSIN  DD    *
OUTQUE  JOBNAME(RMF*)
OUTQUE  JOBNAME(SLAMRUN) CANCEL
OUTQUE  EXCL1('JOBNAME BG PR') AGE(14) SORT(OWNER) CTLBRK
/*

Managing Output Jobs

The OUTQUE clist performs several management functions on the JES2 output job queue. The primary function is to cancel old output jobs. Job selection is controlled by clist parameters. Selected jobs are always listed, and can optionally be canceled or modified. Output listings can be sorted on several criteria, and control breaks can be produced whenever the sort field changes. The default parms cause all jobs (that the user is permitted to see) to be listed. The full list of parms along with default values is shown below.

OUTQUE Command Parms
ParmDescription
AGE( ) Job age in days old. If specified, only jobs at least this number of days old are processed.
DEST( ) Destination. If specified, only jobs with a matching job print route code will be processed.
JOBNAME( ) Jobname. Any value that can be entered in the IOF jobname selection field, including generic jobnames ending in *. If specified only matching jobs will be selected. 1 to 8 jobnames can be entered if enclosed by single quotes (').
Examples:
 JOBNAME(SMFD*)
 JOBNAME( ' TEST*   ++TST   +++TST  ++++TST ' )
 JOBNAME( ' HR*  PR*  PD*  ZD*  RR19297 ' )
SCOPE( ) Any value that can be entered in the option menu SCOPE field. If specified then only groups owned by the specified user or group will be selected.
SORT( ) Output sort field name. If specified, output will be sorted on this field name. The default sort is JOBNAME. Other valid sorts include JOBID, DAYSOLD, ACCOUNT, DEST, USERNAME, ALLOC, INPNODE, NOTIFY, ROOM, LINES, INPUTDEV, and DATETIME. Any field that appears on the extended IOF Job List Menu can be used.
CTLBRK If specified, control break sub-totals for number of jobs and number of track groups will be generated whenever the SORT field changes. CTLBRK is ignored if there is no SORT field.
CANCEL Cancel all selected output if specified. If CANCEL is not specified, selected jobs will only be listed in the report sysout data set.
LNEPGE(55) Lines per page of output in the REPORT sysout data set. The default is 55.
EXCL1( ) Exclude statements. One to four exclude statements can be specified. If any are specified, then the operands are used in IOF exclude statement(s) to exclude jobs with matching characteristics from processing. EXCL2, EXCL3 and EXCL4 are executed in the same way as EXCL1 when multiple exclude statements are needed.
Examples:
 EXCL1('INPUTDEV EQ INTRDR')
 EXCL2('JOBNAME BG PROD')
 EXCL3('USERNAME EQ BOSS')
 EXCL4('ACCOUNT GT 970')
Any field name in the extended IOF Job List Panel can be used.
EXCL2( )
EXCL3( )
EXCL4( )
SYSOUT(X) Sysout class for the report data set.

The cataloged procedure examples shown above demonstrate using these parms.

Any combination of the selection parms described above can be used to control and limit the jobs that are processed by OUTQUE.

The REPORT file produced by OUTQUE lists several useful columns of information about each selected job. The first page of an example REPORT which lists all jobs at least 365 days old is shown below. The REPORT is sorted by OWNER and a control break is generated whenever the OWNER field changes.

Output Job Queue Utility Listing           Run at 10:27:45 on 08/07/98                              PAGE 1
Run parameters are SYSOUT(X) ACTION(LIST) AGE(365) SORT(OWNER) CTLBRK


Jobname  Jobid  Acct Destination        User name           Time run      Date  Notify  Inputdev Alloc

BILDT7Z  J08318      TRISYS             Adams                19:34   6/25/1997          INTRDR       2
*** 1 Jobs for OWNER SYSBEA                                                                        2 ***

ATTACHXM J00981 ISI1 TRISYS.U200        J.PRESTWOOD           9:52   2/27/1997  ISIJFP  OFF1.SR      3
CICSDMPS J00979 ISI1 TRISYS.U200        SCHUBERT              9:52   2/27/1997          OFF1.SR     37
HASPDOCH J08084 1    TRISYS.ESA430      WALKER               15:35   2/20/1997          OFF1.SR     47
ATTACHXM J08205 ISI1 TRISYS.U200        J.PRESTWOOD          12:32   2/20/1997  ISIJFP  OFF1.SR      3
CICSDMPS J09265 ISI1 TRIANGLE           SCHUBERT             12:32   2/20/1997          OFF1.SR     37
*** 5 Jobs for OWNER SYSCOPR                                                                     127 ***

TESTTIME J00476      TRISYS                                  15:57   7/31/1997          INTRDR       1
TESTREXX J00475      TRISYS                                  14:48   7/31/1997          INTRDR       1
COPYIOF  J00472 1    TRISYS             SCHUBERT             14:20   7/31/1997          INTRDR       2
SCANACC  J00242 1    FETCH              SCHUBERT             16:33   7/28/1997          INTRDR       6
SESSRACF J00127 1    FETCH              SCHUBERT             17:59   7/25/1997          INTRDR       4
COPYIOFT J09995 5    TRIANGLE           FRANK                11:09   7/24/1997          INTRDR       1
JOBLIST  J09864 1    FETCH              SCHUBERT             16:24   7/21/1997          INTRDR       6
PROFIO2  J09852 1    FETCH              SCHUBERT             14:54   7/21/1997          INTRDR       3
ENVTSBAT J09780 1    FETCH              SCHUBERT             10:45   7/17/1997          INTRDR       3
SNAPINIT J09772 1    FETCH              SCHUBERT             10:21   7/17/1997          INTRDR       3
IPCSANAL J09515 1    FETCH              SCHUBERT             15:51   7/10/1997          INTRDR       4
IPCSANAL J09513 1    FETCH              SCHUBERT             15:39   7/10/1997          INTRDR       3
COPYDUMP J09511 ISI1 TRISYS             FVS                  15:37   7/10/1997          INTRDR       1
IPCSANAL J09491 1    FETCH              SCHUBERT             15:08   7/10/1997          INTRDR       4
COPYDUMP J09490 ISI1 TRISYS             FVS                  14:22   7/10/1997          INTRDR       1
M21RETRV J09366 FVS  FETCH              SCHUBERT             14:49   7/09/1997          INTRDR       1
M21RETRV J09365 FVS  FETCH              SCHUBERT             14:48   7/09/1997          INTRDR       1
IPCSANAL J09062 1    FETCH              SCHUBERT             15:42   7/07/1997          INTRDR       4
IPCSANAL J09055 1    FETCH              SCHUBERT             15:07   7/07/1997          INTRDR       4
IPCSANAL J09050 1    FETCH              SCHUBERT             14:48   7/07/1997          INTRDR       4
IPCSANAL J08878 1    FETCH              SCHUBERT             13:52   7/03/1997          INTRDR       4
MAPTAXE  J08802 1    TRISYS.MAPCB       SCHUBERT             20:30   7/02/1997          INTRDR       2
MAPRCTD  J08800 1    TRISYS.MAPCB       SCHUBERT             20:26   7/02/1997          INTRDR       2
IPCSANAL J08796 1    FETCH              SCHUBERT             18:40   7/02/1997          INTRDR       4
COPYDUMP J08792 ISI1 TRISYS             FVS                  17:52   7/02/1997          INTRDR       1
MAPSPQE  J08790 1    TRISYS.MAPCB       SCHUBERT             17:32   7/02/1997          INTRDR       2
IPCSANAL J08787 1    FETCH              SCHUBERT             16:52   7/02/1997          INTRDR      27
COPYDUMP J08778 ISI1 TRISYS             FVS                  16:22   7/02/1997          INTRDR       1
MAPASSB  J08736 1    TRISYS.MAPCB       SCHUBERT             11:46   7/02/1997          INTRDR       2
MAPPSA   J08676 1    TRISYS.MAPCB       SCHUBERT             19:34   6/30/1997          INTRDR       3
IPCSANAL J08667 1    FETCH              SCHUBERT             17:34   6/30/1997          INTRDR       3
COPYDUMP J08666 ISI1 TRISYS             FVS                  17:33   6/30/1997          INTRDR       1
IPCSANAL J08657 1    FETCH              SCHUBERT             17:09   6/30/1997          INTRDR       3
COPYDUMP J08658 ISI1 TRISYS             FVS                  17:01   6/30/1997          INTRDR       1
COPYDUMP J08655 ISI1 TRISYS             FVS                  16:52   6/30/1997          INTRDR       1
CDFAPPC  J08623 1    FETCH              SCHUBERT             12:55   6/30/1997          INTRDR       4
MAPASVT  J08497 1    TRISYS.MAPCB       SCHUBERT             10:44   6/27/1997          INTRDR       2
IOFX10A  J08221 1    FETCH              SCHUBERT             12:13   6/25/1997          INTRDR       3
*** 38 Jobs for OWNER SYSFVS                                                                     123 ***

Managing Output Groups

The IOFLISTG clist performs management functions on held and non-held output groups. IOFLISTG differs from OUTQUE in that it operates on output groups rather than output jobs. The selection parms allow selection by group parms such as sysout class, writer, destination and forms.

IOFLISTG Command Parms
ParmDescription
WTRID( ) Writer id. If specified, only output groups with a matching WTRID will be selected.
CLASS( ) 1 to 16 sysout classes. If specified only groups queued to one of the classes will be will be selected.
Example:
CLASS(AJKS)
FORMS( ) 1 to 4 forms. If specified, only output groups queued to one of the specified forms will be selected. Multiple forms must be enclosed in quotes and separated by blanks.
Example:
FORMS( 'C991 C744 FF22' )
DEST( ) Destination. 1 to 8 route codes. If specified only output routed to one of the route codes will be selected.
Example:
DEST( 'BOSTON NEWYORK DENVER' )
JOBNAME( ) Jobname. Any value that can be entered in the IOF jobname selection field, including generic jobnames ending in *. If specified only matching jobs will be selected. 1 to 8 jobnames can be entered if enclosed by single quotes(').
Example:
JOBNAME( 'TH14* ++TST' )
JOBID( ) Job id. If specified, only groups with the matching job id (job number) will be selected.
SYSID( ) System id. If specified, only jobs that ran on the specified system id will be selected.
SCOPE( ) Any value that can be entered in the option menu SCOPE field. If specified, only groups owned by the specified user or group will be selected.
AGE( ) Group age in days old. If specified, only output groups belonging to jobs at least this number of days old are selected.
SIZE( ) Size of group. If a value is specified then only groups with more records than the value specified will be selected.
HARDCOPY Select output on the HARDCOPY queue only if HARDCOPY is specified. Held groups and groups queued to another node will not be selected.
HELD(NO) NO means do not process held groups. ONLY means process held groups only. YES means process held and non-held groups. The default value is NO.
USIDDEST Select only groups that have a USERID destination specified.
APPC If specified, APPC transaction output will be listed instead of normal output.
CANCEL Cancel all selected output if specified.
SORT( ) Output sort field name. If specified, output will be sorted on this field name. Any field name that is displayed on the extended output group display can be specified.
EXCL1( ) Exclude statement 1. If specified, then the operands are used in an IOF exclude statement to exclude groups with the matching characteristics from processing. EXCL2, EXCL3 and EXCL4 are executed in the same way.
Examples:
 EXCL1('CLASS EQ J')
 EXCL2('WRITER BG PR')
 EXCL3('USERNAME EQ BOSS')
 EXCL4('FORMS NC AB')
Any field name in the extended IOF Group Menu may be used.
EXCL2( )
EXCL3( )
EXCL4( )
SYSOUT(X) Sysout class for the report data set.
LNEPGE(55) Print lines per page of output.

The following example job CANCELS all held output groups on sysout class H that are more than 3 days old unless the USERNAME contains the characters ARCHIVE. Note that standard TSO command continuation rules are used in this example.

//CANOLDH  JOB  SYSC,OPERATOR
//CANH     EXEC BATCHIOF
//SYSTSIN  DD   *
IOFLISTG CLASS(H)       +
   HELD(ONLY) AGE(3)    +
   EXCL1('USERNAME CT ARCHIVE')  +
   CANCEL

IOFLISTG produces a REPORT sysout data set similar to the OUTQUE REPORT. A sample of the first page of the REPORT generated by the job above is shown below.


IOF General Output Group Management Utility          Run at 11:09:20 on 08/07/98                                         Page 1
Selection parameters:  CLASS(H) AGE(3) HELD(ONLY)
Exclusions:   EXCL1(USERNAME CT ARCHIVE)

Jobname  Jobid   Owner       Size Cls Destination       Forms    Wtrid  Disposition Time run Date

$DUMP    J00074 SYSOPRT      1278  H  TRIANGLE           STD               HOLD     1998.050  15:57:46
AFPDOC   J01426 SYSFVS         37  H  TRISYS             STD               HOLD     1997.063  14:43:30
AFPDOC   J01428 SYSFVS         37  H  TRISYS             STD               HOLD     1997.063  15:23:05
AFPDOC   J00318 SYSWER        117  H  TRISYS             STD               HOLD     1997.210  15:22:05
AFPDOC   J00319 SYSWER        117  H  TRISYS             STD               HOLD     1997.210  15:22:45
AFPDOC   J00320 SYSWER        117  H  TRISYS             STD               HOLD     1997.210  15:24:39
AFPDOC   J00321 SYSWER        117  H  TRISYS             STD               HOLD     1997.210  15:25:24
A17Q     J03263 SYSWER      17944  H  TRISYS             STD               HOLD     1997.269  10:41:25
A17Q     J03269 SYSWER      18201  H  TRISYS             STD               HOLD     1997.269  11:47:59
A17Q     J03274 SYSWER      18158  H  TRISYS             STD               HOLD     1997.269  14:04:49

Intelligent External Writer

The generalized IOF Writer command, IOFWTR, performs a variety of functions on output groups. Everything from producing output group status reports, to making archival copies can be accomplished by running IOFWTR with the appropriate input parameters.

Four independent functions are provided:

IOFWTR Command Parms
ParmDescription
WTRID( ) Writer id. If specified, only output groups with a matching WTRID will be selected.
CLASS( ) 1 to 16 sysout classes. If specified, only groups queued to one of the classes will be selected.
Example:
CLASS(AJKS)
FORMS( ) 1 to 4 forms. If specified, only output groups queued to one of the specified forms will be selected. Multiple forms must be enclosed in quotes and separated by blanks.
Example:
FORMS('C991 C744 FF22')
DEST( ) Destination. 1 to 8 route codes. If specified only output routed to one of the route codes will be selected.
Example:
DEST('BOSTON NEWYORK DENVER')
JOBNAME( ) 1 to 8 generic jobnames. + is a 1 character wildcard, and * is a wildcard terminator.
Example:
JOBNAME('PR++++99 TES* ++N9*')
JOBID( ) Job id. If specified, only groups with the matching job id (job number) will be selected.
SYSID( ) System id. If specified, only jobs that ran on the specified system id will be selected.
AGE( ) Job age in days old. If specified, only output groups belonging to jobs at least this many days old will be selected.
SIZE( ) Size of group. If a value is specified then only groups with more records than the value specified will be selected.
HARDCOPY Select output on the HARDCOPY queue only. Held groups and groups queued to another node will not be selected.
HELD(NO) NO means do not process held groups. NO is the default.

ONLY means process held groups only.

YES means process held and non-held groups.

USIDDEST Select only groups that are routed to a USERID destination.
SCOPE( ) Any value that can be entered in the option menu SCOPE field. If specified then only groups owned by the specified user or group will be selected.
APPC If specified, only output generated by APPC transactions will be processed.
DDNAME( ) Output DDNAME. If specified, selected output groups will be copied to the data set defined by the DD statement named. Any type of MVS data set may be defined in the DD statement. The DD statement can be included in the JOB or in the cataloged procedure, or can be allocated dynamically before IOFWTR is invoked.
HEADER(IOF$SL1) The name of a clist or Rexx exec to produce a header between output groups. Specify HEADER( ) if headers are not desired. The default HEADER(IOF$SL1) adds a block header for JOBNAME, JOBID and GROUPID. Use the IOF$SL1 exec as an example of writing your own header exec if you have special header requirements. Specify the name of your exec for the HEADER parm.
GENDSN(NO) If YES is specified, an output DSNAME will be generated for each output group selected. The DSNAME is generated by the rules defined in the DSNFMT parm. Default dsn format is: SYSIOF.jobname.Dyyddd.Thhmm.IOFWTR
PACK(NO) Specify PACK(YES) to have the output copy compressed using the ISPF edit PACK format. ISPF browse or edit are required to display packed output. Significant space savings are realized with some types of data.
PREFIX(SYSIOF) Generated DSN Prefix. May be used as the high level data set name if specified in &DSNFMT.
SUFFIX(IOFWTR) Generated DSN Suffix. May be used as the low level data set name if specified in &DSNFMT.
DSNFMT ('&PREFIX.. &JNAME.. D&JDATERUN.. T&TIMERUN.. &SUFFIX') Generated DSN format. If GENDSN(YES) is specified, the output data set names will be generated for each group selected according to this format. Constants may be used in DSNFMT, as well as the following variables:
 &PREFIX - as defined above
 &SUFFIX - as defined above
 &JNAME - jobname of selected groups
 &JID - job id of selected groups
 &DATERUN - date jobs were run (mmddyy)
 &JDATERUN - julian date run (yyddd)
 &TIMERUN - time jobs were run (hhmm)
 &FRM - forms of selected group
 &CLS - sysout class of group
 &WTR - writerid of selected group
 &DST - destination of sel group
DUPDSN(FAIL) Duplicate data set action. What to do if the data set already exists.

DUPDSN(FAIL) means to HOLD the output group, but do not copy it to an existing data set. Flag the failed data set in the report listing. FAIL is the default.

DUPDSN(MOD) means to write on the end of the existing data set.

DUPDSN(OVERWRITE) means to overwrite the existing data set.

UNIT(SYSALLDA) Output data set unit type.
HMIGRATE(NO) HMIGRATE(YES) with GENDSN(YES) means that generated data sets should be migrated immediately offline by HSM. A HMIGRATE command is automatically issued to force migration when both HMIGRATE(YES) and GENDSN(YES) are specified.
DISP(LIST) Disposition. After selected output groups are totally processed, this disposition is taken. The default LIST simply lists selected output groups. CANCEL can be used to cancel groups after processing. An IOF MODIFY command can also be used to modify any overtypeable group characteristics.
Example:
to set class A and standard forms:
DISP('MOD CLASS(A) FORMS(STD)')
PAUSE(0) Pause time in seconds. If PAUSE is zero, the clist terminates when all output groups meeting the specified input criteria have been processed.

If non-zero PAUSE is specified, the clist waits for &PAUSE seconds after all output groups are processed. Then it restarts from the beginning to create a permanent external writer. The operator can interrupt this loop by entering the MVS STOP command 'P jobname' where jobname is the name of the job.

SORT( ) Output sort field name. If specified, output will be sorted on this field name. Any field that appears on the extended output group display can be used as a sort field.
EXCL1( ) Exclude statement 1. If specified, the operands are used in an IOF exclude statement to exclude groups with the matching characteristics from processing. EXCL2, EXCL3 and EXCL4 are executed in the same way.
Examples:
 EXCL1('CLASS EQ J')
 EXCL2('WRITER BG PR')
 EXCL3('USERNAME EQ BOSS')
 EXCL4('FORMS NC AB')
Any field name in the extended IOF Group Menu may be used.
EXCL2( )
EXCL3( )
EXCL4( )
SYSOUT(X) Sysout class for the report data set.
LNEPGE(55) Print lines per page.

The following example runs IOFWTR to copy all SYSOUT class W output to the data set defined by the CLASW DD statement, and to delete the output after it is successfully copied. The job terminates when all class W output has been copied. Standard block separator pages are generated between each captured output group.
//CAPTCLW JOB ....
//WTR     EXEC BATCHIOF,
//        OPT='IOFWTR CLASS(W) DDNAME(CLASW) DISP(CANCEL)'
//CLASW   DD  DSNAME=...  your dd statement

A second example captures held class H output. Captured output is released after it has been captured. Each output group is copied to a different output dataset. The data set name is generated by IOFWTR and follows the pattern:

HRA.jobname.Ddaterun.Ttimerun.ARCH
Generated data sets are queued to HSM for migration immediately. No block header separator pages are generated. The output copy is packed to save space so ISPF edit or browse is required to read it.

The writer is non-terminating. After all class H output has been processed, IOFWTR pauses for 60 seconds and then searches for more class H output to process.

//ARCHCLH JOB ...
//WTR     EXEC BATCHIOF
//SYSTSIN DD   *
IOFWTR   CLASS(H)           +
  DISP(RELEASE)             +
  GENDSN(YES)               +
  PREFIX(HRA) SUFFIX(ARCH)  +
  HEADER()                  +
  HELD(ONLY)                +
  PACK(YES)                 +
  HMIGRATE(YES)             +
  PAUSE(60)
IOFWTR produces an output REPORT much like the one produced by IOFLISTG.

Writing Your Own IOF Batch Execs/Clists

Special requirements can be solved by writing your own IOF batch execs or clists.
IOF User Guide Chapter 18 describes exec and clist features, commands and techniques. The clists and execs in the IOF Clist library can be used as examples. The September, 1997 Newsletter is an example of a simple job history system implemented as an IOF Rexx exec.

Triangle Systems, Inc. PO Box 12752, Research Triangle Park, NC 27709
Email IOFTech@Triangle-Systems.Com

[an error occurred while processing this directive]