Age Spool Files Directory

Directory .ZIP

objects?





These items include PRCSPLF, a basic CL program shell that checks spooled file ages to see if any *splfs are older than seven days. Any old *splfs are moved to a different output queue. The *outq chosen is based on the current day-of-week such that the *outq name is the same as the day name, one *outq for each day of the week. This is intended to be used with a CLP that first clears the current day's default *outq. In this way, old *splfs are moved to the *outq after the daily clearing so that it will be a week before the *splf actually leaves the system.

Messages could be sent to users for each *splf moved, giving them warning that they need to move the *splf to avoid automatic deletion. I prefer processing the *outq after all moves have finished because it's easier to summarize many *splfs for a single user into a single message. Naturally, if they move the *splf out from the daily *outq, it's simply going to be moved back the next time PRCSPLF runs. (A *splf's age doesn't change just because it's been moved. Next week it'll be two weeks old instead of one.) This might irritate the users, but it might also promote proper cleanup.

Note:
Without code to prevent it, the program would move *splfs found in the TUESDAY *outq into the WEDNESDAY *outq on Wednesdays if the *splf age was appropriate. Since the ages of the *splfs do not change just because they've been moved to a daily *outq, they're subject to this process the next day as well. The appropriate IF statement could be modified to compensate by checking for a series of *outq names such as 'SUNDAY' *OR 'MONDAY', etc., or a different strategy altogether could be used. The sample strategy is described here.
As written, the PRCSPLF CLP relies on a user index also named PRCSPLF. Entries in this *usridx are used to indicate which *outqs can be ignored. The *usridx has a *char(30) key that allows re-using the *usridx for other purposes such as user profiles to skip.

For an omitted *outq, the key structure is:

Entry type:
*CHAR(10) Value is "*OMITOUTQ" for an *outq to omit
*Outq name
*CHAR(10) for the omitted *outq name
*outq library
*CHAR(10) for the omitted *outq library
The program grabs the *outq name and library from the *splf entry in the *usrspc and builds a key to access the *usridx. If an entry is found, then that *splf resides on an omitted *outq and is skipped. If the number of returned *usridx entries is binary zeroes, then that *splf is processed against the comparison date since there was no key match.

The program could read the complete *usridx during some program initialization code when it starts and place the entries into a table variable. I chose to check for an entry each time, not the most efficient method but it sure works nice.

The commands I used to create the *usridx and to add the entries are as follows:

Create *usridx
CRTUSRIDX USRIDX(QGPL/PRCSPLF) TEXT('Control elements for PRCSPLF') ENTLEN(128) KEYINS(*YES) KEYLEN(30) OPTIMIZE(*SEQUENTIAL) AUT(*USE)
Add an entry
ADDUSRIDXE USRIDX(PRCSPLF) IDXENTRY('*OMITOUTQ SUNDAY QUSRSYS ') ENTLEN(128)
Of course, the ADDUSRIDXE command was repeated for each daily *outq. You can use the User Index APIs directly or check out the command shells in my "User Index" directory.

The program could be generalized by accepting user name, job name, *outq name or another *splf identifier as a parameter. Various user space APIs are used to process the list of *splfs returned from the QUSLSPL API.

Please read the @GENERAL DISCLAIMER document for any items you should be aware of if you download any of these items.


CLPs

PRCSPLF -- Process Spooled Files:

This program uses a number of Print and User Space API command shells to check spooled file ages. The source code given here simply moves a *splf to a different *outq if the age is greater than seven days; no *splfs are deleted. A SNDPGMMSG is also done just to aid in testing; this should be removed before any live execution and possibly replaced with code to generate a kind of audit trail.

CMDs

LUSSPLF -- List Spooled Files (QUSLSPL):

The command definition object source for QUSLSPL. This command accepts parameters defining *splf characteristics and lists *splfs matching those characteristics into a user space. (Note that the Open List of Spooled Files (QGYOLSPL) API might be more appropriate in any given situation. QUSLSPL has a limit on the number of *splfs that can be listed into a *usrspc; QGYOLSPL has no such limit. This is important at one site I'm aware of where as many as 120,000 *splfs might exist at any given time.)

RTVSPLFAST -- Retrieve Spooled File Attributes (QUSRSPLA):

The command definition object source for QUSRSPLA. This command accepts parameters specifying a specific *splf and returns a structure of information about that *splf. Info may be requested by job name, *splf name and *splf number. The structure returned is the first 1142 bytes of the SPLA0100 data structure. That length was chosen simply because every use I've made of the QUSRSPLA API has used only the info in that area. If you need any fields beyond that, either modify the command source or call the API directly.

The name of this command stands for "Retrieve Spooled File Attributes Structure" and was chosen here to avoid conflicts with the common TAATOOL RTVSPLFA command. I also use my own RTVSPLFA command (not included here) in conjunction with an additional RTNSPLFA command. My RTVSPLFA is similar to this RTVSPLFAST and RTNSPLFA returns external values similar to TAATOOL's RTVSPLFA. Those two commands are easy to develop once you have the basics of the QUSRSPLA API.

TRNINTSPLF -- Retrieve Spooled File Attributes (QUSRSPLA):

An additional command definition object source for QUSRSPLA. This command accepts an internal job identifier and internal *splf identifier and returns just the first 80 bytes of the SPLA0100 data structure. Within those 80 bytes is the external fully-qualified job name and the external *splf name and number.

Effectively, this is the "Translate Internal Spoolfile Name" command, translating internal to external forms. The LUSSPLF command (or QUSLSPL API) returns internal identifiers into the resulting *usrspc list.

The RTVSPLFAST command could be modified to accept either internal or external names, but then I wouldn't have a reason to demo TRNINTSPLF. This shows an example of calling an API with radically different parameter values to achieve a specific result. The APIs couldn't care less about which command shell is used, be it TRNINTSPLF, RTVSPLFAST or for that matter CALL (which of course is simply another command shell). Compiling a CLP to IRP and noting the differences when different command shells are used is instructive.

Because the same API is called with TRNINTSPLF and RTVSPLFAST, the API is called twice for each *splf in PRCSPLF. If this is significant at your site, then changing RTVSPLFA or CALLing QUSRSPLA directly is recommended.