FAQ: Automatic spooled file processing

How do I set up automatic processing of spooled files?

Using the Wizard

The simplest and easiest way to set up CoolSpools Spool Admin to process spooled files automatically is to use the Automatic spooled file processing setup wizard.

The wizard can be accessed in several ways:

1. By taking option 20 from the CoolSpools Spool Admin Menu
2. By running command CFGSPLMON (Configure Spooled File Monitoring)
3. By using WRKSPLFPDM to locate a sample spooled file of the type you want to set up automatic processing for, and taking option 34 against it.

The Wizard simplifies the setting up of automatic processing of spooled files by guiding you through the steps required and prompting for selection of output queues to watch, spooled files to select and actions to perform.

Manual Setup

Alternatively, you can follow these steps.

1. Create spooled file monitors

   Using the WRKSPLMON or CRTSPLMON commands, or CoolSpools Spool Admin menu option 21, define one or more spooled file monitors.

   A spooled file monitor is a job which will “watch” a specified output queue or queues for the arrival of new spooled files or spooled files that have become available for processing as a result of the status of the spooled file changing to “Ready”. This is done by associating a data queue with those output queues and waiting for messages to arrive on the data queue. OS/400 sends a message to the data queue every time a spooled file is created with a status of “Ready” or the status of a spooled file changes to “Ready”.

   It is possible to specify up to 20 output queues to be monitored by a single spooled file monitor (more than 20 is be possible if a generic output queue name or *ANY is specified).

   However, it should be borne in mind that using a single spooled file monitor to detect messages generated for multiple output queues could mean that the spooled file monitor job might become a bottleneck if the volume of spooled files being created is large, since all spooled file messages will be processed by a single monitor job. Better throughput may be achieved by defining a separate monitor for each output queue, unless the number of output queues to be monitored is large, in which case the number of monitor jobs might become excessive. A balance must be struck between having too many messages being processed by each monitor job and having too many monitor jobs.

2. Create spooled file scripts

   It is likely that, for every different type of spooled file that you wish to process, you will want a set of actions to be carried out against that spooled file. The simplest way in which to define a set of actions of this kind is to create a spooled file script.

   Use the WRKSPLSCP (Work with spooled file scripts) or CRTSPLSCP (Create spooled file script) commands, or option 22 from the CoolSpools Spool Admin menu, to define spooled file scripts and their entries.

   If you are going to use spooled file scripts, they must be created prior to trying to refer to them in a spooled file rule.

   A spooled file script consists of a sequence of operations or script entries that will be performed against the spooled file to be processed. each script entry can be any of the following:

   • A command string.You can use CoolSpools Spool Admin substitution variables on most parameters, but, due to restrictions imposed by the OS/400 (IBM i) syntax chcker, you cannot use substitution variables to supply parameter values such as the name of the spooled file, the job details and spooled file number. Instead, if the command you are running is a CoolSpools Spool Converter command, then can use the special values *SLT for the FROMFILE, JOB and SPLNBR parameters to indicate that the spooled file to be processed is the one currently selected by CoolSpools Spool Admin.
   • A standard option.Standard options are those such as 2=Change, 4=Delete and 10=Convert to PDF that are supplied with CoolSpools Spool Admin.It is possible to tailor standard options to your particular needs using WRKSTDOPT (Work with standard options) or option 11 from the Spool Admin Menu.You can use CoolSpools Spool Admin substitution variables to supply parameter values such as the name of the spooled file, the job details and spooled file number.If the command you are running is a CoolSpools Spool Converter command, then you can also use the special values *SLT for the FROMFILE, JOB and SPLNBR parameters to indicate that the spooled file to be processed is the one currently selected by CoolSpools Spool Admin.
   • A user-defined option.User-defined options are similar to PDM user-defined options and let you create your own options that can be used as a convenient way of specifying an operation to be carried out against a spooled file, for example running a command.You can create user-defined options using WRKUSROPT (Work with user-defined options) or option 12 from the Spool Admin menu.You can use CoolSpools Spool Admin substitution variables to supply parameter values such as the name of the spooled file, the job details and spooled file number.If the command you are running is a CoolSpools Spool Converter command, then you can also use the special values *SLT for the FROMFILE, JOB and SPLNBR parameters to indicate that the spooled file to be processed is the one currently selected by CoolSpools Spool Admin.

3. Create spooled file rules

   You must now define the rules which tell CoolSpools Spool Admin what to do for each spooled file that is created.

   Use the WRKSPLRUL (Work with spooled file rules) or CRTSPLRUL (Create spooled file rule) commands, or select option 23 from the CoolSpools Spool Admin menu, to define spooled file rules.

   For each rule you define, you must specify:

   • A set of criteria that will identify the type or types of spooled files to which the rule will apply.If your reports have unique names, for example ABC1234RP1, it is likely that the spooled file name alone will be enough to identify the spooled files to which the rule should apply.On the other hand, if your reports use a system-supplied printer file and are called something like QSYSPRT or QPRINT, or if the report is a query and is called QPQUPRFIL, then you will probably need to specify additional criteria to identify the spooled files to which the rule applies. You might need to specify the user data, the job name, or the name of the program that creates the spooled file, for example.
   • An action to be carried out against the spooled file if it matches the criteria defined above.The action can be to run a command string or to execute a standard or user-defined option, but we recommend that you take the option to call a spooled file script, as this provides the greatest flexibility and maintainability.

4. Start Spooled File Monitoring

   Once you have defined your monitor, scripts and rules, you must start the CoolSpools Spool Admin jobs before spooled file processing will take place. Use the STRMONSPLF command or select option 31 from the CoolSpools Spool Admin menu to start the CoolSpools Spool Admin jobs.

   The CoolSpools Spool Admin jobs run in a subsystem called COOLSPOOLS. You may wish to start this subsystem automatically and run STRMONSPLF to start the jobs, as part of your system startup program (system value QSTRUPPPGM).

5. Checking Spooled File Processing

   In order to check the progress of CoolSpools Spool Admin processing, to ensure that backlogs and bottlenecks and not developing, and to resolve any errors that may have occurred, you should use the WRKTRNSTS (Work with transaction status) and WRKSPLTRN (Work with spooled file transactions) commands, or select options 41-44 from the CoolSpools Spool Admin menu periodically.

6. Resolving errors

   If an error occurs during the processing of a transaction has, and that error is not ignored (because it was included in the list of errors to be ignored on the IGNMSGID parameter of the CRTSPLRUL, ADDSPLSCPE commands etc.), CoolSpools Spool Admin will flag the transaction, and the transaction rule step in relation to which the error occurred, as being “in error”.

   Transactions that are flagged as being “in error” will not be retried until you tell CoolSpools Spool Admin to do so by selecting option 1 against them in the WRKSPLTRN display list. This will remove the error flag and make the transaction available for processing again.

   Processing of the transaction will restart from the first transaction rule step which was not successfully processed already