***************************************************
* *
* 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
line.
** A method of backing up spooled files, retrieving and
re-printing.
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
days.
-- 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
supported).
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
Commands
--------
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
member.
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
SPLSAVP.
Determines if the existing SPLF should be
deleted.
Prints a report.
SAVSPLCTL Save spool control
Reads SPLSAVP and determines if SAVF has been
saved. If not saved, it is saved with
SAVSAVFDTA.
Determines if any existing SAVFs should be
deleted.
Prints a report.
RTVSPLCTL Retrieve spool control
Retrieves SPLF if on-line version exists,
re-prints.
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
criteria.
Allows detail display or simple use of
RTVSPLCTL.
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
record.
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
restored.
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
queue.
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
specify:
MTNSPLCTL OUTQ(LIB1/ABC) ACTION(*ADD)
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:
STRSPLCTL
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
queues.
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
User
Job number
Spooled file name
Spooled file number
If no parameters are specified, the records will appear in keyed
sequence.
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
specified.
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
file.
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
length.
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,
LPI, FONT, ALIGN, FORMFEED, PRTQLTY, PAGRTT, JUSTIFY, FORMTYPE,
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
evaluated.
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:
MOVSPLF FROMOUTQ(QUEUE1) TOOUTQ(QUEUE2) STATUS(SAV)
** 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
specified.
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
occurs.
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
function.
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
commands:
OVRPRTF FILE(QPRINT) CTLCHAR(*FCFC)
CPYF FROMFILE(Dxxxx) TOFILE(QPRINT) +
FROMMBR(SPLnnnnn)
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
deletion.
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:
CRTTAATOOL TOOL(SPLCTL)
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:
CRTSPLCTL SPLCTLLIB(TMPLIB)
** 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
library:
CRTDUPOBJ OBJ(*ALL) FROMLIB(TMPLIB) OBJTYPE(*ALL)
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
normally.
If an old format is found, you will be asked to run the CVTTAAFMT
command.
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.
Restrictions
------------
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.
Prerequisites
-------------
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
Implementation
--------------
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.
Structure
---------
CRTSPLCTL
TAASPLIC9 CL
STRSPLCTL
TAASPLIC CL
SPLMSTP PF read
TAASPLIR RPGLR
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
MTNSPLCTL
TAASPLIC2 CL
TAASPLIR2 RPG
SPLMSTP PF update, add, delete
TAASPLID DSPF
DSPSPLCTL
TAASPLIC3 CL
TAASPLIR3 RPG
SPLAUDP PF read
SPLAUDL LF read
TAASPLIE DSPF
TAASPLIC7 CL - Does RTVSPLCTL
SAVSPLCTL
TAASPLIC4 CL
TAASPLIR4 RPG
SPLMSTP PF read
SPLSAVP PF update
QPRINT PRT
TAASPLIC6 CL - Save and delete SAVF
TAASPLIC20 CL - Adopts to allow update of SPLCTLRCV2
RTVSPLCTL
TAASPLIC5 CL
TAASPLIR5 RPG
SPLAUDP PF update
|
