TAA Tools
SPLCTL      SPOOL FILE CONTROL                         TAASPLI

        *                                                 *
        *    The SPLCTL tool has been superseded by       *
        *      the SPLARC tool.  The SPLARC tool uses     *
        *      APIs to access and re-print spooled        *
        *      files.  The two tools are not compatible.  *
        *                                                 *

The Spool Control function is designed to provide:

  **   A method of  cleaning up old  spooled files based on  their age.

       If a  spooled file is still  on the system after N  days, it can
       be  automatically  deleted.   You  specify  for  each designated
       output queue how  many days the spooled  file should be kept  on

  **   A   method  of   backing  up   spooled  files,   retrieving  and

       In  some   environments,  the  end  users  will  expect  the  DP
       department to  be  able  to  re-print a  report  that  was  done
       several  days ago.    The  data used  for  the  report may  have
       changed significantly  and it may not  be practical to re-create
       the data.    The  spool  control  function  lets  you  save  the
       spooled file contents  in case re-printing is anticipated.   You
       can  also  use  the technique  for  job  logs  or other  spooled
       output  which  may  only  need  to be  printed  on  request.   A
       maximum  size  of  210  bytes  page  width  is  supported.    To
       re-print  more than  132  with the  RTVSPLCTL  command, see  the
       PRTF parameter on RTVSPLCTL.

       You  specify by output queue whether  you want the spooled files
       saved.   The  spool control  function  then copies  the  spooled
       files to  a physical  file (using  CPYSPLF), saves the  physical
       file  to  an online  save file  and  allows backup  of  the save
       file.   A retrieval  function is  available which  will  reprint
       the file.

       There are essentially  3 levels of  backup to allow  the spooled
       file to be re-printed:

         --   The  original  spooled  file is  kept  online.   You  may
              choose  to keep  the spooled file  on line (e.g.   in the
              SAV status  or  in a  separate output  queue)  for a  few

         --   If  you back  up the  spooled file  to a  save  file, the
              save  file should  be backed up  to off  line media (e.g.
              at night).  The save file  can be kept on line for a  few
              days.   The  data is  kept in  a compressed  format.   To
              re-print,  you   would  specify  the  retrieval  function
              which would automatically  do RSTOBJ from  the save  file
              and then re-print the information.

         --   If the save file  is not on line, you can  retain the off
              line  media  for weeks  or  months.    The spool  control
              function  will  keep track  of the  spooled file  for the
              length of time  you specify.   The audit record  includes
              the  information  about the  spooled  file  and the  save
              information.    To re-print,  you  would  determine which
              media to mount and use  the proper RSTOBJ command.   This
              will bring  the data  base file  back on  line and  allow
              the retrieval function to re-print the data.

The Spool  Control function can require  considerable auxiliary storage
space to hold  a lot of  spooled files on  line.   The command to  save
the spooled  files  (STRSPLCTL) requires  significant system  resources
and should be executed in off hours.

Contrast with DLTOLDSPLF tool

The  Delete Old Spooled  Files tool is  a simpler approach  to cleaning
up   spooled  files.    A  user   specified  retention  date  is  used.
DLTOLDSPLF does not save  any files, but does  allow an option to  move
the  spooled files  that  are past  the  retention date  to a  separate
output  queue  so  that  you  can  review  them  and  manually cause  a
deletion.   DLTOLDSPLF  will  operate  against all  output  queues  (an
exclude capability exists) or a single named queue.

Contrast with CPYFRMOUTQ tool

The  CPYFRMOUTQ  tool  provides  a  simple  solution  for  placing  all
spooled files  from a single output  queue into a data  base file.  The
file can  then  be  saved or  restored  to  a different  system.    The
CPYTOOUTQ  reprints   the  data  (no   special  printer   graphics  are

CPYTOOUTQ  does not provide  any assistance  in terms of  which spooled
file  to reprint, where  the backup is,  nor does it  delete any of the
spooled files.

CPYFRMOUTQ  is intended  for  simple or  one  time  usage.   SPLCTL  is
intended as a permanent solution.

   Daily operation

                        SPLCTLD Library            SPLCTLS library
                     **********************      ********************
                     *                    *      *                  *
                     *                    *      *                  *
    OUTQs            *                    *      *                  *
  ******** STRSPLCTL *                    *      *                  *
  *      *  command  * *****************  *      * ***************  *
  *      * ------------> PF per OUTQ   * --------->* SAVF per PF *  *
  *      *           * *  MBR per SPLF *  *      * ***************  *
  ********           * *****************  *      *                  *
                     *                    *      *                  *
                     **********************      ********************

                       PFs are automatically        Save with
                         deleted when the             SAVSPLCTL
                         SAVF is written              command

  Spooled files                                    SAVFs automatically
  automatically                                    deleted after N days
  deleted after
  N days


   To re-print use RTVSPLCTL command

                        SPLCTLD Library            SPLCTLS library
                     **********************      ********************
                     *                    *      *                  *
                     *                    *      *                  *
    OUTQs            *                    *      *                  *
  ******** RTVSPLCTL *                    *      *                  *
  *      *  command  * *****************  *      * ***************  *
  *    <---------------* PF per OUTQ  <------------* SAVF per PF *  *
  *      *           * *  MBR per SPLF *  *      * ***************  *
  ********           * *****************  *      *                  *
                     *                    *      *                  *
                     **********************      ********************

RTVSPLCTL function:

  **   If PF is on-line, use PF to re-print from.

  **   If  PF is  not on-line,  but SAVF  is on-line,  automatically do
       RSTOBJ to PF and use PF to re-print from.

  **   If  neither PF nor SAVF  are on-line, user must  do RSTOBJ of PF
       from offline media and then use RTVSPLCTL command.

Major files used by Spool Control

           SPLMSTP           SPLAUDP            SPLSAVP
          *********         *********          *********
          *       *         *       *          *       *
          *       *         *       *          *       *
          *********         *********          *********

        One record per    One record per      One record
         OUTQ to be        SPLF being          per SAVF
         controlled        controlled          written


   CRTSPLCTL     Creates spool control.

                      Creates the files used by spool control.

   MTNSPLCTL     Maintain spool control.

                      Adds, deletes, changes the SPLMSTP records.

   STRSPLCTL     Start spool control.

                      Reads SPLMSTP,  and  uses the  TAA  Tool  CVTOUTQ
                      for each OUTQ.

                      Determines  if   a  record   already  exists   in
                      SPLAUDP.  If not, it adds it.

                      If the  spooled file should be  backed up and has
                      not been,  a member  is added  to the  PF in  the
                      SPLCTLD  library  and  CPYSPLF  is  used  to  the

                      When  all spooled  files have  been  processed in
                      the  OUTQ,  a  SAVF  is  created  in  the SPLCTLS
                      library, SAVOBJ is  used to the  SAVF and the  PF
                      is deleted.

                      If  a  SAVF is  written,  a  record  is added  to

                      Determines   if  the  existing   SPLF  should  be

                      Prints a report.

   SAVSPLCTL     Save spool control

                      Reads SPLSAVP  and determines  if SAVF  has  been
                      saved.     If  not   saved,  it  is   saved  with

                      Determines  if   any  existing  SAVFs  should  be

                      Prints a report.

   RTVSPLCTL     Retrieve spool control

                      Retrieves  SPLF   if  on-line   version   exists,

                      If no on-line  version exists, user  must restore
                      from media and then use RTVSPLCTL.

   DSPSPLCTL     Display spool control

                      Displays   records  in  SPLAUDP   with  selection

                      Allows   detail   display   or   simple   use  of

How to use Spool Control

The files  used by spool  control must  be created  in a named  library
with the CRTSPLCTL command.

The  libraries  SPLCTLD   and  SPLCTLS  must  be  created.     See  the
implementation instructions.

You  begin with  the MTNSPLCTL  command to  describe each  output queue
which should  be controlled.    For each  output queue  described,  you
specify options for such things as:

      - The number of days to keep the SPLFs on line
      - If an audit trail record is desired
      - If the SPLF should be backed up (saved to a SAVF)
      - The number of days to keep the SAVF on line
      - The number of days to keep the audit record
      - A unique 2 character abbreviation code per output queue

The  STRSPLCTL command  can  then be  used.   This  is  a long  running
command  and should  be submitted to  batch during  the off hours.   It
will use the information  from MTNSPLCTL to determine  what to do  with
any spooled files found  in the specified output queues.   The TAA tool
CVTOUTQ is used to build a data base file of the SPLFs.

When  a Print Writer  is in  operation, it  will print the  files which
are  in a RDY status.  Unless you  specify SAVE(*YES) on the print file
or  by  OVRPRTF,  the  file  will  be  deleted  after  it  is  printed.
Assuming  you run  the STRSPLCTL  function at  night, it  will normally
find  spooled files  that were either  never printed  or were specified
with SAVE(*YES).

The STRSPLCTL  function  checks if  an  audit  trail record  should  be
written for  the spooled file  (an audit  trail record is  required for
any  spooled files  to be  backed up).    If an  audit trail  record is
requested, a check is  made to see  if it already exists.   If so,  the
file has already been  processed (e.g.  the spooled file  may have been
online for  several days).   If not, the  audit record is  written.  If
the  spooled file is  to be backed up,  it is copied  with CPYSPLF to a
data base  file.   The attributes  of  the file  (e.g.   LPI, CPI)  are
extracted  from  the  WRKSPLFA  information  and stored  in  the  audit

A  unique data base file  is used for each  output queue when STRSPLCTL
is run.  A separate member is  added to the file for each spooled  file
backed  up.   When all  spooled files  in  the output  queue have  been
processed, STRSPLCTL  checks to see if any  data base members have been
written and if so it does a SAVOBJ  to a unique SAVF.  Thus there  is a
unique SAVF used for each data base file created.

All the data  base files are created  in the library SPLCTLD.   All the
save files  are created in  the library SPLCTLS.   After the  save file
has been created and SAVOBJ run, the data base file is deleted.

The  STRSPLCTL function  then checks each  of the spooled  files to see
if  they  should  be  deleted  from  the  output  queue  based  on  the
information you specified with MTNSPLCTL.

After  STRSPLCTL or  the  next  morning, you  would  run the  SAVSPLCTL
command.   This  will backup offline  any of  the save  files that have
not already been saved.   After this is complete, SAVSPLCTL checks  all
of the  existing SAVFs and  determines if  any should be  deleted based
on the information you specified on MTNSPLCTL.

Printed  output occurs from  both the STRSPLCTL  and SAVSPLCTL commands
to assist  you in  determining what  functions occurred,  the names  of
the files used and summary information.

Naming conventions

The files in the SPLCTLD library follow the naming convention of:

     D aa YYMMDD b

                 D = Constant for all files

                 aa =  The unique abbreviation  assigned to  the output
                 queue by MTNSPLCTL.

                 YYMMDD = Year, month and day

                 b  = Consecutive  letter beginning  with 'A'  for each
                 date.    This allows  multiple STRSPLCTL  functions to
                 occur on each day for the same output queue.

The save  files are  in the  SPLCTLS library  and use  the same  naming
convention, but all start with the letter 'S'.

The members in each file are named MBR00001, MBR00002 etc.

The  text  description  for the  data  base  file  and save  file  will
describe  the output queue and the date  written.  The text description
for the members will include  the qualified job name, the spooled  file
name and the user data information.

Displaying the audit records

The DSPSPLCTL  command allows  you to  display any  of the audit  trail
records  that  are  kept  by  the  spool  control  function.    Various
selection criteria are supported so you  can view only the records  for
a date (a range of  dates), an output queue, a user, a  job, by spooled
file name or combinations of these attributes.

A subfile is displayed and two options are allowed:

  **   Display  the detail information  about the spooled  file record.
       This   includes   the   information   from   WRKSPLFA   and  the
       information about  the  name  of the  file  and member  used  to
       backup the spooled file.

  **   Retrieve the  spooled file data  and re-print it.   This invokes
       the  RTVSPLCTL command.    For RTVSPLCTL  to be  successful, the
       backup data base file must  be online or the corresponding  save
       file.  If not,  you must restore it based  on the information in
       the audit record.

Re-printing a Spooled File

Because  of the  way STRSPLCTL  operates, the data  base files  used to
contain the CPYSPLF  output are  deleted as soon  as the  save file  is
written.  The assumption  is that the information will  normally not be
used and  it is better  to save space on  the system (The  save file is
kept  in compressed  format).  The  RTVSPLCTL command  first checks for
the data  base file and  member and if  they exist,  it will cause  the
re-print.   If the  file/member is  not online, the  save file  name is
checked.   If the save  file exists, RSTOBJ for  a single member occurs
automatically and then the re-print occurs.

Re-printing occurs with  the same  options that were  specified on  the
original file  (e.g.   LPI, CPI,  USRDTA etc.).   The  CPYF command  is
used for  re-printing.  This is effective for  most DP output (the same
skipping and  spacing  will occur),  but  cannot be  used  to  re-print
special printing functions such as bar codes, graphics etc.

If  the RTVSPLCTL  command  is  attempted when  the  save file  is  not
online, it  will fail.   You must do a  restore of the  data base file.
The  information  stored  in  the  audit  record  will  assist  you  in
determining what media  to mount and  what file and  member need to  be

For  example, assume  you run  STRSPLCTL each  night and  the SAVSPLCTL
the next  day.  The data base file  name assigned by STRSPLCTL for June
15, 2009 would  be Daa090615A.  When  the SAVSPLCTL command  completes,
you would  normally label the external  media with the 090615  date and
the fact that it belongs to the SPLCTL function.

Assume now  that it is July  1st and a user wants  to reprint a spooled
file that occurred a few weeks  prior.  Using DSPSPLCTL you would  need
to determine the exact  spooled file to be re-printed  and then request
the RTVSPLCTL option.

Assuming you  did not want to  keep the spooled file nor  the save file
online  for two  weeks, the  RTVSPLCTL request  would be rejected.   If
neither the  spooled file, the  data base  file nor  the save file  are
online, you will need to restore from media.

Using  DSPSPLCTL to  find  the  exact spooled  file  audit record,  you
would  determine the  data base  file/member that  was assigned  to the
spooled file.   For  example,  it might  say Daa090615A  and  MBR00012.
You would  then have  the operator  mount the  SPLCTL media for  090615
and issue the command:

       RSTOBJ   OBJ(Daa090615A) SAVLIB(SPLCTLD) DEV(xxx)
                  FILEMBR(MBR00012) MBROPT(*ALL)

This  will restore the file  and the member requested  (the entire file
does not  need to  be restored).   You  can now  request the  RTVSPLCTL
function and it will  re-print the spooled file to  the original output

CRTSPLCTL parameters                                  *CMD

The  CRTSPLCTL command  creates the files  used by  spool control  in a
named library.

   LIB           The library to create the files in.

   SRCLIB        The  source library to use for  the QATTDDS file.  The
                 default is *TAAARC  which means to  use the source  in
                 the TAA Archive.

MTNSPLCTL parameters                                  *CMD

The  MTNSPLCTL  command maintains  the  records  in  the SPLMSTP  file.
There  is one record per output  queue.  An output  queue and an action
to be performed must be specified.   A prompt screen then appears  with
the  values from  the SPLMSTP  file (defaults  are used  when 'add'  is
requested).    See the  later  section  on a  discussion  of  the field
values to be entered.

To add  a new  record  for the  ABC output  queue  in LIB1,  you  would


The command parameters are:

   OUTQ          The qualified  output queue  record to be  maintained.
                 A library name must be specified.

   ACTION        The  type of  action  to  be performed  on  the output
                 queue  record.  The  entries are *ADD,  *CHG, *DLT and
                 *DSP.  *CHG is the default.

   SPLMSTPLIB    The library where the  SPLMSTP file exists.   *LIBL is
                 the default.  *CURLIB may also be specified.

STRSPLCTL parameters                                  *CMD

The  STRSPLCTL command  is used  when it  is time  to check  the output
queues  specified.  This  is a slow  running command and  should be run
in batch during the off hours.

A typical command would be entered as:


The command supports a single parameter:

   OUTQ          The qualified  output queue  name or  *ALL.   *ALL  is
                 the default.   If *ALL is  entered, all of  the output
                 queues  described in  the SPLMSTP  file will  be used.
                 If a single output queue  is named, only the  specific
                 queue will be used.

                 The intent of a  single output queue name is  to allow
                 certain output  queues to be  processed multiple times
                 per day or for specific requests.

                 See  the  later  discussion  on  using  unique  output

                 When *ALL is  specified, the  SPLAUDP file is  checked
                 to see  if records should be deleted  and file cleanup
                 will occur.  See the later discussion.

   SPLMSTPLIB    The  library where the SPLMSTP file  exists.  *LIBL is
                 the default.  *CURLIB may also be specified.

DSPSPLCTL parameters                                  *CMD

The command  displays a  subfile of  the SPLAUDP  audit  records.   The
keyed access path to the file is made up of:

      Output queue
      Output queue library
      Job number
      Spooled file name
      Spooled file number

If  no parameters  are  specified, the  records  will  appear in  keyed

If one  or more of the high order key  fields are specified, the access
path will be used to start the search.   This will act as a 'set  lower
limit'  function   (more  records  than   meet  the  criteria   may  be
displayed).   A consecutive  set of high  order keys must  be specified
to use the 'set lower limit' function.

For  example, if OUTQ and JOB  are described as selection criteria (but
not OUTQLIB), the 'set lower limit' technique cannot be used.

If the  'set  lower  limit' technique  cannot  be used,  the  selection
criteria  specified  is  used  on  an OPNQRYF  command  to  select  the
records that will appear in the subfile.

To  specify that all spooled  files output for user  JONES on 890615 be
displayed, you would specify:

       DSPSPLCTL    USER(JONES) DATE(890615)

The command parameters are:

   OUTQ          The output queue name to be searched for.

   OUTQLIB       The output queue library to be searched for.

   DATE          The date to be  searched for in YYMMDD  format.  If  a
                 range  of  dates  is  desired,   you  should  use  the
                 BGNDATE and ENDDATE parameters.

   JOB           The job  name to be searched for.   A generic name may
                 be specified.

   USER          The user  name to  be searched  for.   A generic  name
                 may be specified.

   JOBNBR        The job number to be searched for.

   SPLF          The spooled file name  to be searched for.   A generic
                 name may be specified.

   BGNDATE       Specifies  a beginning date  for a  range of  dates in
                 YYMMDD format.

   ENDDATE       Specifies  an  ending date  for  a range  of  dates in
                 YYMMDD format.

   SPLMSTPLIB    The library where the  SPLMSTP file exists.  *LIBL  is
                 the default.  *CURLIB may also be specified.

SAVSPLCTL parameters                                  *CMD

The SAVSPLCTL  command saves the save  files in the  SPLCTLS library to
tape.   It issues a SAVSAVFDTA  command for any of  the save files that
have not already been saved.

A typical command would be entered as:

       SAVSPLCTL    DEV(TAP01)

some  of   the  command   parameters  default   differently  than   the
corresponding SAVSAVFDTA command.  These are noted.

The command parameters are:

   DEV           The device name  to be save to.  Only  a single device
                 can be specified.

   VOL           The  volume IDs to be  used.  The  default is mounted.
                 Only a  4 character  ID  may be  specified and  all  4
                 characters must  be entered.   This  differs from  the
                 SAVSAVFDTA command.

                 If  you enter  a  value  like ABCD,  the  command will
                 expand  the parameter  to ABCD01, ABCD02,  ...  ABCD50
                 and specify  them  on the  SAVSAVFDTA  command.   This
                 allows  you  to easily  use  a  naming convention  and
                 allows multiple tapes to be used.

   SEQNBR        The  sequence  number  to  start  the  save  at.   The
                 default is  1  meaning the  first  file on  the  tape.
                 This differs from  the normal save commands  where the
                 default  is *END.   Specifying *END allows  you to use
                 the  same  tape   for  multiple   SAVSPLCTL  or   Save
                 commands.   For  most  cases, the  default  of 1  will
                 allow  you to associate  unique media with  a specific
                 SAVSPLCTL  command  and  prevent  you  from  using the
                 same tape twice until  the expiration date is  passed.

   EXPDATE       The  file  expiration date.    The  default is  *DAY30
                 meaning  the  file will  be considered  active  for 30
                 days.   This  differs  from the  normal  SAV  commands
                 which  default to  *PERM.   The  special values  *DAY1
                 ...   *DAY60  may be  used  to specify  a date  in the
                 future  (The  TAA   tool  CVTDAYN   command  is   used
                 internally).     An  entry  of   *PERM  may   also  be

                 Normally,  you will  want to  set the  expiration date
                 to your tape retention cycle.

   ENDOPT        The   positioning  of   the  tape   when  the  command
                 completes.    The  default  is  *REWIND.    *LEAVE  or
                 *UNLOAD may also be specified.

   CLEAR         Whether to  clear unexpired  volumes.  The  default is
                 *NONE.  *ALL may be specified.

   SPLMSTPLIB    The  library where the SPLMSTP file  exists.  *LIBL is
                 the default.  *CURLIB may also be specified.

RTVSPLCTL parameters                                  *CMD

The  Retrieve   Spool  Control   command  allows   the  retrieval   and
re-printing of a saved spooled file.

You would  normally not issue  this command directly,  but rather  as a
selection  option  from  the  DSPSPLCTL  subfile  display.    Once  you
identify the  spooled file  to be  re-printed, the  DSPSPLCTL  function
will fill in the  critical parameters and prompt for  the command (Only
the PRTOUTQ parameter may be entered).

The command parameters are:

   OUTQ          The  qualified  name   of  the  output  queue.    This
                 identifies  where the  spooled file  was found  and is
                 the default for where it will be re-printed to.

   JOB           The qualified  job name  that  identifies the  spooled

   SPLF          The spooled file name.

   SPLFNBR       The spooled file number.

   PRTOUTQ       The qualified  name of the  output queue to  print to.
                 The  default is *OUTQ meaning to  re-print to the same
                 output queue  the  spooled was  backed  up from.    If
                 used  via  DSPSPLCTL,  the output  queue  and  library
                 originally saved from will be the defaults.

   PRTF          The  qualified name  of the  printer file  to re-print
                 to.    The  default  is  QSYSPRT  which  will  operate
                 correctly  for  most  spooled files  of  132  or  less

                 If  your spooled file  is wider  than 132,  you should
                 name  a printer  file that  has been  created with the
                 length you  need.   The  maximum  length supported  is
                 211  bytes  which allows  for  a  print  width of  210
                 bytes plus one byte for space/skip information.

Most  of the attributes  for the spooled  file to be  written come from
the spooled  file as it  was originally  written.   This includes  CPI,
FILESEP,  USRDTA, and SPLFNAME.   The output queue comes  from the OUTQ
parameter on  the  command.    Other  attributes  are  taken  from  the
printer file.

   SPLMSTPLIB    The library where  the SPLMSTP file exists.   *LIBL is
                 the default.  *CURLIB may also be specified.

Field descriptions for the MTNSPLCTL command

When the  MTNSPLCTL command is executed,  you will be asked  to fill in
values for the following fields:

   SMOUTQ        The  output  queue  entered  from  the  command.    It
                 cannot be changed on the display.

   SMQLIB        The output  queue library  entered  from the  command.
                 It cannot be changed on the display.

   SMABRV        A  unique two  character abbreviation  for the  output
                 queue.   This entry  is used in  the naming convention
                 to provide unique  names for the  data base files  and
                 the corresponding  save files.  Neither  character can
                 be a blank.

   SMSPON        The number  of days to keep the  spooled file on line.
                 It is a 3  digit entry with  a default of  1.  If  you
                 want  to  delete   the  spooled  file  any   time  the
                 STRSPLCTL  function is  used, enter  0.   If  you have
                 requested  the  spooled  file  to  be  backed  up, the
                 backup will occur before  the number of days  value is

                 The open  date of  the file is  used as  the beginning
                 date.     If  the  STRSPLCTL  function  is  run  after
                 midnight, it will count as the next day.

   SMAUDT        A Y/N entry for whether  to add an audit record.   The
                 default is  Y.  Y  must be specified  if you  want the
                 spooled  file backed  up.   You  can request  an audit
                 record without  asking  for  the spooled  file  to  be
                 backed  up.   This  would provide  a  history of  what
                 spooled files existed.

   SMSPSV        A Y/N  entry for whether to backup  (save) the spooled
                 file.  The default is Y.

   SMSVON        The  number of  days to  keep the  save file  on line.
                 This is  a 3 digit  value with  a default of  3.   The
                 check  is made  based on  the date  the save  file was
                 written  and  not  on the  open  date  of  the spooled
                 files in the save file.

                 The SMSVON days must be less than the SMSVOF days.

   SMSVOF        The number of days to  keep track of the audit  record
                 (how long to  track the save file off line).   This is
                 a  3 digit  field with  a  default of  30.   This date
                 should be set  to your retention  cycle of the  media.
                 If you  intend to  keep the  media for  60 days,  then
                 this  value should  be 60  and  you should  change the
                 EXPDATE default on SAVSPLCTL.

Assume  you  took  the defaults  for  adding  an output  queue  and are
running the STRSPLCTL  command at 1:00 AM  in the morning.   Assume all
your spooled output occurred the prior day.

When the  STRSPLCTL is run on  Tuesday morning at 1:00  AM, any spooled
files found  in the queue (in a SAV or  RDY status) would be saved to a
save file and the spooled  files would be deleted (because the  default
for SMSPON is 1).   The SAVSPLCTL command should be used  to backup the
save  files offline either after  the STRSPLCTL command  is complete or
when the daytime  shift arrives on  Tuesday.  Because  the default  for
SMSVON is  3, the  save file  would remain online  until the  SAVSPLCTL
command was run on Friday.

If  a request occurred  on Thursday to  re-print the spooled  file, the
RTVSPLCTL  command could  be used  without restoring  any media because
the save file is still online.

If a request for re-print  occurred after Friday, the media  would have
to be  mounted and  RSTOBJ used.   A request could  be made  anytime in
the  first 30 days after the  file was open and  a re-print would still
be achievable.  After  30 days, the audit  record would be deleted  and
your media should be re-cycled.

It is  important to set  the SMSPON value (number  of days to  keep the
spooled  file online)  based  on when  you run  the  STRSPLCTL command.
Assume you take  the default of  1, but run the  STRSPLCTL command  the
same day  the file was  opened.   The spooled file  will be backed  up,
but  will  remain  online  until  the  STRSPLCTL  command  is  run  the
following day.

If  you use MTNSPLCTL and  change the values after  the spooled file is
saved,  the new  values  will be  honored  by  both the  STRSPLCTL  and
SAVSPLCTL commands.   For example, if you decide to  keep the media for
45  days instead of  30, an existing  audit record will  not be deleted
until it is 45 days old.

Spooled file status which are saved

The following spooled file status codes are eligible to be saved:

        RDY, HLD, SAV, CLO

The following are not eligible:

        OPN, WTR, PND, PRT, MSGW

Unique output queues

The MTNSPLCTL  command operates the  same on  all spooled  files for  a
specific output queue.

If you  have some specific requirements,  a good solution is  to create
a  unique output  queue and  use the  TAA tool  MOVSPLF command.   This
will allow  you to  select which  files you  want to  move  (e.g.   all
those with a status of SAV) such as:


  **   Assume you  have a  production output  queue where you  normally
       send  most of  your printed  output.   You  may want  to specify
       SAVE(*YES)  for some  of the files.   This means  that after the
       file is  printed,  it  should not  be  removed from  the  output
       queue.   Rather than waiting  for the offshift use  of STRSPLCTL
       to  remove these  files from  the queue, you  could periodically
       use MOVSPLF  to move the  SAV status  files to  a unique  queue.
       The unique  queue would be specified  by MTNSPLCTL and  not your
       production queue.

  **   This  would remove excessive  clutter from  the production queue
       and you would not be exposed  to the problems of when  STRSPLCTL
       is actually run.   For example,  if spooled files have  not been
       printed  when STRSPLCTL  is run,  it is  possible that  the file
       would be saved or deleted without ever having been printed.

  **   Assume  that you have  an output queue  which is rarely printed,
       but you want to backup  files of a specific name, by  a specific
       user etc.   You could use MOVSPLF to  select these spooled files
       and  move them  to  a unique  queue or  just process  the entire
       output queue.  MTNSPLCTL would  be used on the unique queue  and
       not the normal queue.

If you  use a unique  queue and  need to re-print  a spooled  file, you
may not  want the spooled file  to be placed in the  unique queue.  The
RTVSPLCTL command will let you specify  which output queue to be  used.
The default is to use the output queue it was saved from.

Security considerations

The  job running  the  various  functions  must be  authorized  to  the
appropriate  sub functions.   The  following are  the major  items that
may need to be considered:

  **   The  STRSPLCTL command  will create  physical files,  save files
       and must have job control  rights in order to be able  to delete
       spooled  files owned  by other  users (in  operator controllable
       queues).   If  the  queues are  not operator  controllable, then
       the job must have the special SPLCTL authority.

       The job must also have  object management rights to the  SPLAUDP
       file in  order to  perform cleanup  activities.   Note that  the
       user  of the command must  be authorized to create  a save file.
       You can consider using program adopt for this function.

  **   The user running  the SAVSPLCTL function  must be authorized  to
       SAVSAVFDTA.   The job  must also  have object management  rights
       to the SPLSAVP file to perform cleanup activities.

Cleanup activities

The  spooled  files  are   automatically  deleted  based  on  the  date

Records  in the  SPLAUDP file  will be  deleted based on  the retention
period.    This  cleanup  occurs  automatically  at  the   end  of  the
STRSPLCTL command (if OUTQ(*ALL) is specified).

Records in  the SPLSAVP  files will  be deleted based  on the  date the
SAVF  should be deleted.  This cleanup  occurs automatically at the end
of the SAVSPLCTL command.

The  data base  files  that  are  created  as  part  of  the  STRSPLCTL
function are  automatically deleted  when the  corresponding save  file
is written.

The  save  files  are automatically  deleted  when  the specified  date

The SPLCTLD library will require some cleanup activity:

  **   If you do  a RTVSPLCTL from  an on-line save  file, a data  base
       file will be created and will not be deleted.

  **   If you restore  a saved physical  file, it will not  be deleted.

The SAVSPLCTL  command will produce  a final message  regarding whether
any  cleanup  activity  should  take  place  in  the  SPLCTLD  library.
Normally, any files could be cleared on a daily basis.

Normally, you  will not  need any cleanup  to SPLCTLS.   The  SAVSPLCTL
printout  will provide  information when  there is  a  mismatch between
the  save  files that  exist  in the  library  and the  records  in the
SPLSAVP file.  You should not place any objects in this library.

Timing considerations

The STRSPLCTL  function uses  the TAA  tool CVTOUTQ  command  to get  a
list of  spooled files  per output queue,  extracts the  attributes and
then  does CPYSPLF.  Because  of timing considerations,  it is possible
for a  spooled  file to  exist  at the  time  of CVTOUTQ  and  then  be
deleted before the other  functions are performed.  This  will generate
an  audit  record,  but  the  spooled  file  will  not  have  an  entry
specifying that the file was saved.

A  similar  timing  consideration  can  occur  prior  to  deleting  the
spooled file.   CVTOUTQ  is used  and a later  point the  file will  be
deleted by  DLTSPLF.   Because of the  difference in time,  DLTSPLF may
not  find anything  to delete.   In  this case the  code is  assumed to
have performed  the  delete  (the  timestamp for  the  delete  will  be
updated)  even  though the  actual  delete  was  caused by  some  other

Recovery during STRSPLCTL

The  STRSPLCTL  function is  designed  to be  recoverable  if  an error
occurs which will  end the command.   Recovery data  areas exist  which
are  set at  various  points  during  processing.   When  STRSPLCTL  or
SAVSPLCTL are  started again, the  recovery data areas  are checked and
the processing is continued at the appropriate point.

For  example, the  data base  audit record  is not updated  until after
the data base  file is  written and the  save file  is written.   After
the record  is updated, the  spooled file is  deleted if needed.   If a
failure  occurs  before the  record is  updated,  the worst  that would
happen is the  spooled file would  be saved twice  (only the last  save
would be posted to the audit record).

To delete records from  the files, CPYF is used to a  separate file and
X'd records  are not copied.   The net file is then  copied back to the
original file.   The data area  is set multiple times  during the  copy
steps to ensure a valid recovery.

Libraries used

   SPLCTLD       Contains the physical  files created by  the STRSPLCTL
                 function.   These are  automatically deleted  when the
                 save file is written.

                 The  library also  contains the files  restored by the
                 RTVSPLCTL  function  and should  be  used  for  RSTOBJ
                 when the spooled file is not on line.

                 The  SAVSPLCTL printed  output  will  describe if  any
                 objects  exist in this library.   You should clear any
                 objects in this library that you are not using.

   SPLCTLS       Contains the  save  files.    The  save  files  should
                 correspond  to  the  records in  SPLSAVP.    Automatic
                 cleanup  is  made  by  the  SAVSPLCTL  command.    You
                 should not place  any other objects  in this  library.

   TAATOOL       Contains the program objects and recovery data areas

   xxxx          Your library named  on the CRTSPLCTL  command contains
                 the files  which have the  data for the  spool control
                 function  such  as  SPLMSTP,  SPLAUDP  etc.    See the
                 following section.

Recovery of a tape no longer known to SPLCTL

The save  files saved  by SAVSPLCTL, can  be restored  beyond the  date
controlled  by   MTNSPLCTL.    For  example,  if   you  specified  that
MTNSPLCTL  should track the  save file  for 500 days,  the spooled file
information is  deleted after  500 days.   You  may  still restore  the
tape with a normal RSTOBJ command and re-print a spooled file.

If you  use the DSPSAVTAP  TAA Tool, you  can determine the  Dxxxx file
name  that should  be restored.    The member  information will  not be
meaningful because  the members  will  be labeled  SPL00001,  SPL00002,
etc.  You should restore  the file to one of your  own libraries (avoid
mixing with the SPLCTLD library).

After  the file  is  restored, the  file  will contain  one  member per
spooled  file.    Use  the  TAA  Tool  command  DSPMBRS  to  review the
members.  The text for each member will include the:

        - Qualified job name
        - Spooled file name
        - USRDTA value (such as a command name or blanks)

From this information you  should be able to determine the  member that
should  be re-printed.   You  may also  use an  option such  as  PFM to
display the data in the member.

The  data contains a forms  control character in position  1.  You must
use an OVRPRTF command to specify CTLCHAR(*FCFC) for forms control.

Typical DP  spooled  output  may be  printed  from the  file  with  the

            CPYF          FROMFILE(Dxxxx) TOFILE(QPRINT) +

If the spooled  output is incorrect, you may need  a specific parameter
on the  OVRPRTF command.  This is the information  that was in the file
retained by SPLCTL  until the  retention date  of the  SAVF caused  the

Damage Recovery

In  the event  a  message  directs you  to  this  section or  you  have
experienced  some form  of damage,  the following  is recommended  as a
means of recovery.

If  you suspect damage to the programs  or display files (not data base
files), try re-creating the tool:


If you have  or suspect  some form of  data damage  (such as a  missing
logical  file or  RPLPF was  unable to  complete successfully  during a
reformat function), try the following:

  **   Create  a unique  library to  be used  for a  temporary function
       (termed TMPLIB in the sample code):

           CRTLIB      LIB(TMPLIB)

  **   Create the SPLCTL files in the unique library:


  **   Copy the physical file data from your current library.

           CPYF        FROMFILE(xxx/SPLAUDP) +
                         TOFILE(TMPLIB/SPLAUDP) MBROPT(*ADD)

           CPYF        FROMFILE(xxx/SPLAUDP2) +
                         TOFILE(TMPLIB/SPLAUDP2) MBROPT(*ADD)

           CPYF        FROMFILE(xxx/SPLMSTP) +
                         TOFILE(TMPLIB/SPLMSTP) MBROPT(*ADD)

           CPYF        FROMFILE(xxx/SPLSAVP) +
                         TOFILE(TMPLIB/SPLSAVP) MBROPT(*ADD)

       If you are unable  to copy the data,  you will probably need  to
       restore from your backup.

  **   Delete the spool control files in your current library:

           DLTF        FILE(xxx/SPLAUD*)
           DLTF        FILE(xxx/SPLMST*)
           DLTF        FILE(xxx/SPLSAV*)

  **   Use  CRTDUPOBJ to  duplicate  the  objects from  your  temporary

                       TOLIB(xxx) DATA(*YES)

  **   Delete the temporary library:

           DLTLIB      LIB(TMPLIB)

Try the DSP command:

           DSPSPLCTL   SPLMSTPLIB(xxx)

If  the  command   is  successful,  you  should  be  able  to  continue

If an old  format is  found, you  will be  asked to  run the  CVTTAAFMT

Files used (these are created by the CRTSPLCTL command)

   SPLMSTP       One record per  output queue.  The file  is maintained
                 by  the MTNSPLCTL  command.   It contains  the options
                 described  earlier  such  as the  number  of  days the
                 spooled files should be kept online.

   SPLAUDP       One record per spooled  file.  This is the  audit file
                 which contains  the information from  WRKSPLFA and the
                 data base file/member used for backup.

   SPLSAVP       One  record per  save file  that exists in  the SPLCTL
                 library.  This  is an internal file  to keep track  of
                 what  save files  exist  and  whether they  have  been
                 saved by the SAVSPLCTL command.

   SPLAUDP2      This  is  an  internal  file  used  to delete  expired
                 records from  SPLAUDP.   It is  created  automatically
                 by STRSPLCTL.

   SPLSAVP2      This  is  an  internal file  used  to  delete  expired
                 records  from SPLSAVP.   It  is  created automatically
                 by SAVSPLCTL.

   SPLAUDL       A  logical file built over SPLAUDP.   The file is used
                 by DSPSPLCTL.

   SPLMSTL       A logical file  built over  SPLMSTP to enforce  unique
                 keys on  the abbreviation  ID.  The  file is  not used
                 in any program.


Not  all  of  the  spooled  file  functions  can  be  handled.    Those
functions which  are not  external  attributes of  the file  cannot  be
saved.  This includes functions such as bar codes and logos.

The handling  of LPI allows  for only a single  character.  A  value of
7.5 is returned  as 6 as 7 is invalid.  A  value GT 9 is returned as 0.

A maximum of 32,766 spooled files may  exist in an output queue.   This
is the  maximum that may be  saved by the  system if all  spooled files
are converted.


The following TAA Tools must be on your system.

      ADDDAT       Add date
      ALCTMPMBR    Allocate temporary member
      CHKDBF       Check data base file
      CHKGENERC    Check generic
      CHKJOBCTL    Check job control
      CVTDAT       Convert date program
      CVTDAYN      Convert *DAYnn
      CVTOUTQ      Convert output queue to a data base file
      DUPFILFMT    Duplicate file format
      RTVDAT       Retrieve date
      RTVSPLFA     Retrieve spooled file attributes
      SNDCOMPMSG   Send completion message
      SNDESCMSG    Send escape message
      SNDSTSMSG    Send status message
      TAAARC       TAA Archive


The tool is ready to use, but you must:

  **   Create the files used by SPLCTL:

      CRTSPLCTL     LIB(xxx)

  **   Create the libraries SPLCTLD and SPLCTLS.

      CRTLIB        LIB(SPLCTLD) TEXT('TAA Tool SPLCTL library for +
                                   converted spooled files')

      CRTLIB        LIB(SPLCTLS) TEXT('TAA Tool SPLCTL library for +
                                   SAVF form of spooled files')

Objects used by the tool

   Object        Type       Attribute      Src member     Src file
   ------        -----      ---------      ----------     -----------

** SPLCTLS       *LIB                            No source
** SPLCTLD       *LIB                            No source
*  SPLMSTP       *FILE         PF          TAASPLIP       QATTDDS
*  SPLAUDP       *FILE         PF          TAASPLIP2      QATTDDS
*  SPLAUDP2      *FILE         PF          No source
*  SPLSAVP       *FILE         PF          TAASPLIP3      QATTDDS
   TAASPLIQ      *FILE         PF          TAASPLIP3      QATTDDS
*  SPLSAVP2      *FILE         PF          No source
*  SPLMSTL       *FILE         LF          TAASPLIL       QATTDDS
*  SPLAUDL       *FILE         LF          TAASPLIL2      QATTDDS
   TAASPLID      *FILE         DSPF        TAASPLID       QATTDDS
   TAASPLIE      *FILE         DSPF        TAASPLIE       QATTDDS
   SPLCTL        *DTAARA                         No source
   SPLCTLRCV     *DTAARA                         No source
   SPLCTLRCV2    *DTAARA                         No source
   STRSPLCTL     *CMD                      TAASPLI        QATTCMD
   MTNSPLCTL     *CMD                      TAASPLI2       QATTCMD
   DSPSPLCTL     *CMD                      TAASPLI3       QATTCMD
   SAVSPLCTL     *CMD                      TAASPLI4       QATTCMD
   RTVSPLCTL     *CMD                      TAASPLI5       QATTCMD
   CRTSPLCTL     *CMD                      TAASPLI9       QATTCMD

Objects used by the tool - Continued

   Object        Type       Attribute      Src member     Src file
   ------        -----      ---------      ----------     -----------

   TAASPLIC      *PGM          CLP         TAASPLIC       QATTCL
   TAASPLIC2     *PGM          CLP         TAASPLIC2      QATTCL
   TAASPLIC3     *PGM          CLP         TAASPLIC3      QATTCL
   TAASPLIC4     *PGM          CLP         TAASPLIC4      QATTCL
   TAASPLIC5     *PGM          CLP         TAASPLIC5      QATTCL
   TAASPLIC6     *PGM          CLP         TAASPLIC6      QATTCL
   TAASPLIC7     *PGM          CLP         TAASPLIC7      QATTCL
   TAASPLIC8     *PGM          CLP         TAASPLIC8      QATTCL
   TAASPLIC9     *PGM          CLP         TAASPLIC9      QATTCL
   TAASPLIC20    *PGM          CLP         TAASPLIC20     QATTCL
   TAASPLIR      *PGM          RPG         TAASPLIR       QATTRPG
   TAASPLIR2     *PGM          RPG         TAASPLIR2      QATTRPG
   TAASPLIR3     *PGM          RPG         TAASPLIR3      QATTRPG
   TAASPLIR4     *PGM          RPG         TAASPLIR4      QATTRPG
   TAASPLIR5     *PGM          RPG         TAASPLIR5      QATTRPG
   TAASPLIR6     *PGM          RPG         TAASPLIR6      QATTRPG
   TAASPLIR7     *PGM          RPG         TAASPLIR7      QATTRPG

*  The objects exist in the library specified on CRTSPLCTL
** Libraries that you must create (see previous section)
The  TAASPLIQ file  is created in  TAATOOL to  allow other  programs to
use the file to create against such as CVTTAAFMT.



        SPLMSTP  PF read
        OUTQP    PF read - CVTOUTQ outfile
        SPLAUDP  PF update and add
        SPLSAVP  PF output
      TAASPLIC8   CLP - Rtv, Cpy, Dlt SPLF
    TAASPLIR6  RPG - Determine next Save file name
    TAASPLIR7  RPG - Print output
        QPRINT   PRT
    TAASPLIC20 CL - Adopts to update SPLCTLRCV

        SPLMSTP  PF update, add, delete

        SPLAUDP  PF read
        SPLAUDL  LF read
        TAASPLIE    DSPF

        SPLMSTP  PF read
        SPLSAVP  PF update
        QPRINT   PRT
      TAASPLIC6   CL  - Save and delete SAVF
    TAASPLIC20 CL - Adopts to allow update of SPLCTLRCV2

        SPLAUDP  PF update

Added to TAA Productivity tools April 1, 1995

Home Page Up to Top