SFPURGER

Read syntax diagramSkip visual syntax diagram SFPURGER TESTsysop1TESTTESTSOSRUNFORCESOSsysop12sysop
Notes:
  • 1 For TEST and TESTSOS, sysop defaults to the user ID of the virtual machine running SFPURGER.
  • 2 For RUN, FORCE, and SOS, sysop defaults to OPERATOR.

Authorization

Systems Programmer

Purpose

Use the SFPURGER utility to manage your spool space and spool files. You can purge, ignore, or put one of several kinds of holds on a spool file. You can also handle a spool file as instructed by a user-written action routine. Together, these SFPURGER activities can be described as spool file maintenance.

SFPURGER performs spool file maintenance using instructions you give it ahead of time, at intervals you determine. You provide the instructions to SFPURGER using options and control files. You can use SFPURGER locally, or use it in the distributed environment to manage spool files on unattended systems. SFPURGER is most useful as an automated tool that runs unattended from a dedicated virtual machine.

For information on the virtual machine requirements for running SFPURGER, the SFPRUGER options and control files, and the output files that SFPURGER creates, see SFPURGER: Requirements, Setup, and Use.

Operands

TEST
tests SFPURGER, without actually performing spool file maintenance. SFPURGER processes your SFPURGER OPTIONS file (if you create one) and your SFPURGER CONTROL file, just as in RUN mode. SFPURGER also creates output files as in RUN mode. Using the information in the output files, you can track SFPURGER’s processing, and verify your options and control files work as you intended. This is the default.
TESTSOS
tests SFPURGER the same way TEST mode does, but instead processes the emergency control file, SOS CONTROL. As with TEST mode, you can use SFPURGER’s output file information to verify your options and control files work correctly, without actually performing spool file maintenance.
RUN
executes SFPURGER for normal operation. SFPURGER reads the SFPURGER CONTROL file and does spool file maintenance, unless—
  1. It is invoked during prime shift, or
  2. It is invoked after running successfully in RUN, FORCE, or SOS mode earlier the same day.

If either 1 or 2 occurs, SFPURGER displays a message at the console and ends processing.

FORCE
executes SFPURGER, which reads the SFPURGER CONTROL file and does spool file maintenance, regardless of the time it is invoked or whether it has run successfully earlier the same day.
SOS
executes the same way FORCE mode does, but the control file SFPURGER reads is SOS CONTROL. You can use SOS mode to do emergency spool file maintenance.
sysop
is a 1- to 8-character user ID you assign to receive important SFPURGER progress and error messages. sysop defaults to OPERATOR, unless the mode of operation is TEST or TESTSOS, in which case sysop is forced to the user ID of the virtual machine running SFPURGER. You can specify sysop only if you specify TEST, TESTSOS, RUN, FORCE, or SOS.

The RUN, LOG, and TST files will be assumed to be from 19xx if xx is a year after 70. If xx is 70 or before, they will be assumed to be from 20xx.

Usage Notes

  1. By default, the SFPURGER utility is located on the system tools disk (MAINT 193).
  2. CP user privilege class D, E, and G are required. Optionally, class B is required to issue the MSGNOH command.
    Note: Class E users might want to specify the IGNORE action for named saved system (NSS) files in the SFPURGER CONTROL file to avoid purging them.
  3. If the system is protected by an ESM, the virtual machine running SFPURGER requires UPDATE access to all user's virtual readers.
  4. When specifying the IGNORE action in the SFPURGER CONTROL file, sufficient keywords should be used to fully describe a group of spool files to ensure they will not be affected by a later control file statement.
  5. When specifying the QUEUE keyword in the SFPURGER CONTROL file, the valid queue choices are PRT (printer), PUN (punch), RDR (reader), IMG (image library), NLS (message repository), NSS (named saved system or saved segment), TRF (system trace), and UCR (user class restructure).
  6. When specifying the TYPE keyword in the SFPURGER CONTROL file, the valid spool files choices are CON (console), DMP (dump), PRT, PUN, RDR, IMG, NLS, NSS, TRF, and UCR.
  7. If SFPURGER matches hold-related actions to system data (IMG, NLS, NSS, TRF, and UCR) spool files due to the results from processing the SFPURGER CONTROL file, these actions will be changed to IGNORE; hold-related actions are not supported for system data spool files because of CP limitations.
  8. SFPURGER checks both the opening and closing dates for files and uses the older of the two dates when determining what files to purge. This can cause confusion when dealing with CP dump files. CP dump files are created on the system's dump processor user ID when the system was started or when the last CP dump was taken and will sit in the dump processor's reader until a CP dump (RESTART dump, SNAPDUMP, etc.) is taken. Because a CP dump might not be taken over a long period of time, the opening date on this file can be quite old. If the SFPURGER CONTROL file indicates to purge dump files after a shorter period of time, this dump file will be purged the first time that SFPURGER runs. A way to handle this situation is to use the ORIGINID, USERID, etc. keywords in the SFPURGER CONTROL file. The sample SFPURGER CONTROL file shipped with the product contains sample code of one way to handle this situation: 
    * Ignore dump files that have an origin of SYSTEM. Purge any other
* dump files after 4 weeks.  Ignor the rest
TYPE DMP     ORIGINID SYSTEM                     ACTION IGNORE
TYPE DMP     DAYS 29                             ACTION PURGE
TYPE DMP                                         ACTION IGNORE
    With this coding, SFPURGER will ignore any dump files that have an origin of SYSTEM (which CP dump files do), purge any other dump files older than 29 days, and ignore any other dump files.
    Note: This same situation holds true for any files, not just CP dump files. However, most files are opened and closed in the same day so this situation does not occur.
  9. Support for the user class restructure (UCR) function and the OVERRIDE utility have been removed. If any UCR files exist on the system, they can be queried and manipulated, but the contents of those files will not be processed by CP.

Messages and Return Codes

  • DMS2442E This user lacks the privilege class for MSGTYPE MSGNOH.
  • DMS2443I MSGTYPE has been set to MSG.
  • DMS2444T This user lacks the privilege to display real storage. [RC=36]
  • DMS2445T This user lacks the privilege to handle SYSTEM spool files. [RC=36]
  • DMS2446E The user userid is an invalid destination for console log files. The log file will not be sent.
  • DMS2447T The command MODULE is not accessible to this user. [RC=44]
  • DMS2448T SFPURGER was invoked with invalid parameter parm. [RC=40]
  • DMS2449I No files purged.
  • DMS2450E The SYSOP value value is invalid.
  • DMS2451I SYSOP has been set to OPERATOR.
  • DMS2452I SFPURGER starting at hh:mm:ss on dd/mm/yy.
  • DMS2453I Running in type mode - ft.
  • DMS2454I You cannot invoke SFPURGER RUN in prime shift, hh:mm:ss - hh:mm:ss. [RC=0]
  • DMS2455I You cannot invoke SFPURGER RUN twice in one day. [RC=0]
  • DMS2456I Erasing old output files till yydddd.
  • DMS2457I Output files are not erased in type mode.
  • DMS2458T Error number rc. [RC=4|8|12|16|28|32|>1000]
  • DMS2459I Examining output file …
  • DMS2460E command failed. Return code = rc.
  • DMS2461I type mode - scanning only.
  • DMS2462I Spool file scanning begins …
  • DMS2463I num of the total spool files {HAVE|WOULD have} been purged.
  • DMS2464W Return code rc was received from command.
  • DMS2465I SFPURGER type has ended.
  • DMS2466I Run terminating - Return code rc.
  • DMS2467I No action taken.
  • DMS2468I SFPURGER run ends.
  • DMS2469I SFPURGER OPTIONS file processed …
  • DMS2470I Using command MODULE with fn CONTROL file.
  • DMS2471I Increase virtual storage and try again.
  • DMS2472I Rectify error in control file.
  • DMS2473I Decrease spooling activity.
  • DMS2474I Contact Systems Support for advice.
  • DMS2475I Check parameters and try again.
  • DMS2476I Rectify disk errors and retry.
  • DMS2477T An unknown command failure occurred. Return code = rc.
  • DMS2478T The parm value value in the SFPURGER OPTIONS file is invalid. [RC=20]
  • DMS2479T The option parm in the SFPURGER OPTIONS file is invalid. [RC=20]
  • DMS2480I Rectify error in OPTIONS file and try again.
  • DMS2481E The action parm in the control file is unknown.
  • DMS2482I {Executing|Testing}: command_string
  • DMS2483I Appending fn CONTROL file to fn CONTROL file.
  • DMS2484I The node control file to append, fn CONTROL, does not exist.
  • DMS2485I num of the total spool files {HAVE|WOULD have} been changed.
  • DMS2486I num of the total spool files {HAVE|WOULD have} been handled by user exits.
  • DMS2487I Reason code num record.
  • DMS2488E A control file record must end in an action.
  • DMS2489S SFPURGER is terminating due to previous errors. [RC=8]
  • DMS2490E The fn CONTROL file cannot be found. [RC=28]
  • DMS2491E There is insufficient free storage to run SFPURGER. [RC=4]
  • DMS2492E A control file record cannot start with an action.
  • DMS2493S There is an error in the ACTSECT card logical chaining. [RC=16]
  • DMS2494S An invalid keyword parm was specified in a control file record.
  • DMS2495E Invalid data parm was specified in a control file record.
  • DMS2496I Control card scan complete.
  • DMS2497S SFPURGER cannot run due to changing spool file chains. [RC=12]
  • DMS2498S SFPURGER had a program check. Code is code PSWADDR addr. [RC=32]
  • DMS2499E SFPURGER abend - dumping.

Return codes:

RC
Meaning
0
Normal exit

This includes exits resulting from an unsuccessful invocation either during prime shift or after an earlier run the same day.

4
Unable to allocate storage
8
Error found in control file
12
Spool file chains keep changing
16
Internal logic error
20
Error found in SFPURGER OPTIONS file
28
Control file not found
32
Program check

This error should be accompanied by a VMDUMP, and the dump file should be sent to your system support center for evaluation. Before doing so, check that the abend is not caused by incorrect privilege classes.

36
Missing privilege class
40
Invalid parameter on SFPURGER invocation
44
Missing SFPURGER MODULE
48
Unable to find sort module
100
Explanation complete (when ‘?’ specified)
xxx
Error xxx from SORT MODULE (+100)
1xxx
Return code xxx from FSREAD
2xxx
Return code xxx from FSWRITE