Spool Admin Module

CoolSpools is a modular software application for the IBM i (AS/400, iSeries) platform. The CoolSpools Spool Admin module provides powerful automation capabilities for your IBM i spooled file reports. The module allows you to monitor one or more output queues, and automatically run CoolSpools spooled file conversion commands or IBM i system commands whenever a new spooled file matching a set of predefined rules arrives on a monitored output queue.

Spool Admin Module for IBM i

Setting up CoolSpools automation requires three simple steps:

  1. Create Monitors
  2. Create Scripts
  3. Create Rules

All of these can be achieved from the CoolSpools Spool Admin menu. Enter command GO COOLMENU for the CoolSpools main menu and then select 4. Spool Admin Menu.

Step One – Create Monitors

The Monitor attaches a trigger to an output queue, allowing one or more actions to automatically take place when a spooled file is added to the queue (either by creating a new spooled file on the output queue, or by moving an existing spooled file from another queue). There are two ways of creating a Monitor:

  • Spool Admin Wizard (menu option 20 or command CFGSPLMON)
  • Work With Monitors (menu option 21 or command WRKSPLMON)

The Spool Admin Wizard allows you to select an existing spooled file report from which to create both a Monitor and a Rule. The Monitor will be created for the output queue within which the selected spooled file report resides, and the Rule will be based upon the attributes of the selected spooled file (e.g. the spoolfile name). Rules are discussed later in this guide.

Once a Monitor has been created using the Wizard, you can maintain it from the Work With Monitors screen.

You can also create a Monitor directly from the Work With Monitors screen by pressing F6 and entering the name of the output queue to be monitored. This can be seen in the example below, where a Monitor named REPORTS is being created for an output queue also named REPORTS.

Create spooled file monitor (CRTSPLMON)  Type choices, press Enter. 

Spooled file monitor name  . . .   REPORTS       Name
Output queue . . . . . . . . . .   REPORTS       Name, generic*, *ANY
Library  . . . . . . . . . . .     QUSRSYS     Name, *LIBL, *CURLIB, *ANY
+ for more values             
*LIBL     
Data queue . . . . . . . . . . .   REPORTS       Name, *OUTQ, *OUTQNAME
Library  . . . . . . . . . . .     QUSRSYS     Name, *LIBL, *CURLIB…
Change outq/envvar, if needed  .   *YES          *NO, *YES
Create data queue, if needed . .   *YES          *NO, *YES
Text ‘description’ . . . . . . .   Batch Reports                               
       

Bottom
 F3=Exit   F4=Prompt   F5=Refresh   F10=Additional parameters   F12=Cancel
F13=How to use this display        F24=More keys 

Note that when you create a Monitor it will not trigger processing of spooled files that already exist on the output queue. It will only trigger activity for spooled files that are added to the output queue from that point onwards.

Each Monitor runs as a background batch job on your IBM i server. The Monitor jobs are started and ended with commands STRMONSPLF and ENDMONSPLF. These background jobs should be ended and restarted after adding a new Monitor, and you may want to add the STRMONSPLF command to your system start-up program if you want Monitors to be active following a system IPL.

Step Two – Create Scripts

The Work With Spooled File Scripts screen allows you to create and maintain Scripts, and can be accessed using menu option 22 or command WRKSPLSCP.

It is not mandatory to create scripts, but without scripts your automated processing will only be able to execute a single command against each spooled file report. Scripts allow you to sequence multiple commands to be processed as a series of steps.

Create a script by opening the Work With Spooled File Scripts screen and pressing F6. Specify a name for the script as in the example below, which is named STOCKREPORT.

                     Create Spooled File Script (CRTSPLSCP)  Type choices, press Enter. 

Script name  . . . . . . . . . .   STOCKREPORT              
Text ‘description’ . . . . . . .   Send daily stock report as PDF              
      

                                                                         Bottom 
 F3=Exit   F4=Prompt   F5=Refresh   F12=Cancel   F13=How to use this display
F24=More keys 

Once the Script has been created we can add Entries to the Script. Each Entry is a command or action to be processed in sequence when the Script is executed.

The Script Entries are maintained within the same Work With Spooled File Scripts screen. Enter option 8 next to a Script to maintain its Script Entries, then press F6 to add a new Entry. In the example below we are adding an Entry to our newly created STOCKREPORT Script in order to perform a CoolSpools conversion of the spooled file to PDF, with email delivery of the converted document to an address list named WAREHOUSE.

                         Add Spooled File Script Entry Script name  . . . . . . .   STOCKREPORT
Text ‘description’ . . . .   Send daily stock report as PDF
Sequence number  . . . . .       10
Text ‘description’ . . . .   Convert to PDF and send to Warehouse Team         
Option . . . . . . . . . .   20      Email spooled file as a PDF
Option parameters  . . . .   FROMFILE(&F) TOSTMF(‘Daily Stock Report.pdf’) JOB(
&N/&U/&J) SPLNBR(&S) STMFOPT(*REPLACE) EMAIL(*YES) EMAILOPT(*NO ‘Daily Stock Rep
ort’) EMAILTO((WAREHOUSE *ADRL *ADRL)) EMAILMSG(‘Please see attached the daily s
tock report’)                                                                   
                                                                                
                                                                                
                                                                                
                                                                                
                                                                                
                                                                                
                                                                                
                                                                                
                                                                                                                                                        More…
 F3=Exit   F4=Prompt   F8=Select option   F12=Cancel   F22=Expand cmd 

In the above example the action to perform was identified by an Option Code of 20, which indicates that the command CVTSPLPDF should be run to convert the spooled file report to PDF and deliver it by email.

The different Option Codes supplied with CoolSpools are listed below, although these are customisable and you can add your own site-specific Option Codes to perform any IBM i command (e.g. to run the IBM Content Manager OnDemand command ADDRPTOND to archive a spooled file).

  • 01 Send spooled file using SNADS
  • 02 Change Spooled File
  • 03 Hold spooled file
  • 04 Delete spooled file
  • 05 Display spooled file
  • 06 Release spooled file
  • 07 Display spooled file messages
  • 08 Work with spooled file attributes
  • 09 Work with printing status
  • 10 Convert spooled file to PDF
  • 11 Convert spooled file to Excel
  • 12 Convert spooled file to HTML
  • 13 Convert spooled file to CSV
  • 14 Convert spooled file to Text
  • 15 Convert spooled file to RTF
  • 16 Convert spooled file to TIFF
  • 17 Convert spooled file to spooled file
  • 18 Convert to XML
  • 19 Convert to Excel using a map
  • 20 Email spooled file as a PDF
  • 21 Email spooled file as Excel
  • 22 Email spooled file as HTML
  • 23 Email spooled file as CSV
  • 24 Email spooled file as Text
  • 25 Email spooled file as RTF
  • 26 Email spooled file as TIFF
  • 28 Email spooled file as XML
  • 29 Email spooled file as Excel using a map
  • 30 Save spooled file
  • 31 Send spooled file using TCP/IP (LPR)
  • 32 View spooled file text
  • 33 Design report definition
  • 34 Configure automatic spooled file processing
  • 35 Configure splf conversion default parameters
  • 36 View spooled file as PDF
  • 37 Print spooled file as PDF
  • 50 Run script

In the example below we are adding a second Entry to our script. The sequence number of 20 indicates that this is to be performed after our previous Entry, which had a sequence number of 10. This time the Entry is using Option Code 02 to change the spooled file attributes. The spooled file report is being moved to a different output queue named PROCESSED in order to mark processing of the spooled file report as complete.

                         Add Spooled File Script Entry Script name  . . . . . . .   STOCKREPORT
Text ‘description’ . . . .   Send daily stock report as PDF
Sequence number  . . . . .       20
Text ‘description’ . . . .   Move Stock Report to PROCESSED output queue       
Option . . . . . . . . . .   02      Change Spooled File
Option parameters  . . . .   FILE(&F) JOB(&N/&U/&J) SPLNBR(&S) OUTQ(PROCESSED) 
                                                                                
                                                                                
                                                                                
                                                                                
                                                                                
                                                                                
                                                                                
                                                                                
                                                                                
                                                                                
                                                                                
                                                                                                                                                        More…
 F3=Exit   F4=Prompt   F8=Select option   F12=Cancel   F22=Expand cmd 

The previous two Entries used Option Codes to identify the action to be performed, but you can also specify *CMD and enter an IBM i command string, as in the example below. This third Entry in our Script runs the IBM i command SNDMSG to deliver a message to the message queue named OVERNIGHT with confirmation that the stock report has been delivered.

                         Add Spooled File Script Entry Script name  . . . . . . .   STOCKREPORT
Text ‘description’ . . . .   Send daily stock report as PDF
Sequence number  . . . . .       30
Text ‘description’ . . . .   Send message to confirm delivery of Stock Report  
Option . . . . . . . . . .   *CMD   
Command string . . . . . .   SNDMSG MSG(‘The Daily Stock Report has been delive
red’) TOMSGQ(OVERNIGHT)                                                         
                                                                                
                                                                                
                                                                                
                                                                                
                                                                                
                                                                                
                                                                                
                                                                                
                                                                                
                                                                                
                                                                                                                                                        More…
 F3=Exit   F4=Prompt   F8=Select option   F12=Cancel   F22=Expand cmd 

By following the examples above we have now created a Script named STOCKREPORT with three Entries, to convert the spooled file report to PDF and send it by email, to move the spooled file report to a different output queue, and to send a system message confirming delivery of the report.

At the moment there is nothing to tell the Script when to run – this is where we need a Rule.

Step Three – Create Rules

Rules are the link between the Monitors and the Scripts. When a spooled file report arrives on a monitored output queue, the spooled file attributes are checked against the Rules to see what action is required. The Rules can be used to check any combination of following spooled file attributes:

  • User
  • Spooled file name
  • Print device
  • Output queue
  • Form type
  • User data
  • Job name
  • Created by program
  • Printer device type
  • Number of pages
  • Spooled file size (Kb)

Rules can be maintained by using menu option 23 or command WRKSPLRUL – use F6 to add a new Rule. See below an example Rule that checks whether a spooled file is on output queue REPORTS and named QSYSPRT with a user data value of STKRPT. When a spooled file matches all of these conditions the Script STOCKREPORT will be executed to process the spooled file.

                      Create spooled file rule (CRTSPLRUL)  Type choices, press Enter. 

Rule name  . . . . . . . . . . . > STOCKREPORT              
User . . . . . . . . . . . . . .   *ALL          Name, generic*, *ALL
Spooled file name  . . . . . . . > QSYSPRT       Name, generic*, *ALL
Print device . . . . . . . . . .   *ALL          Name, generic*, *ALL
Output queue . . . . . . . . . . > REPORTS       Name, generic*, *ALL, *ANY
Library  . . . . . . . . . . . >   QUSRSYS     Name, generic*, *LIBL…
Form type  . . . . . . . . . . .   *ALL          *ALL, *STD, formtype, *generic
User data  . . . . . . . . . . . > STKRPT        *ALL, usrdta, *generic*…
Job name . . . . . . . . . . . .   *ALL          Name, generic*, *ALL
Created by program . . . . . . .   *ALL          Name, generic*, *ALL, *ANY
Library  . . . . . . . . . . .                 Name, generic*, *ANY
Printer device type  . . . . . .   *ALL          *ALL, *SCS, *IPDS, *LINE…
Number of pages:
From . . . . . . . . . . . . .   *ALL          1-999999999, *ALL
To . . . . . . . . . . . . . .                 1-999999999, *MAX

More… 
 F3=Exit   F4=Prompt   F5=Refresh   F10=Additional parameters   F12=Cancel
F13=How to use this display        F24=More keys 

                      Create spooled file rule (CRTSPLRUL)  Type choices, press Enter. 

Spooled file size (Kb):
From . . . . . . . . . . . . .   *ALL          0-999999999, *ALL
To . . . . . . . . . . . . . .                 1-999999999, *MAX
Rule priority  . . . . . . . . .   5000          1-9999
Option . . . . . . . . . . . . . > *SCRIPT       Character value, *SELECT…
Script name  . . . . . . . . . . > STOCKREPORT              
Text ‘description’ . . . . . . .   *BLANK                                      
      

Bottom 
 F3=Exit   F4=Prompt   F5=Refresh   F10=Additional parameters   F12=Cancel
F13=How to use this display        F24=More keys 

Thanks to the Monitor, Rule and Script created in the examples above, when a spooled file named QSYSPRT with user data STKRPT arrives on the output queue REPORTS, it will be automatically converted to PDF and moved to a different output queue named PROCESSED, with a system message being sent to a message queue named OVERNIGHT. Other spooled files created on the REPORTS output queue that do not satisfy the Rule’s conditions will not be selected for processing.

Spooled File Transactions

You can view the history of transactions with menu options 41-44 or commands WRKSPLTRN and WRKTRNSTS. A transaction should be created for each spooled file that arrives on a monitored output queue. The transaction log will show whether the spooled file matched any Rules, and the outcome of any commands executed as part of the transaction. If you do not see the expected transactions in the log, it could be that the Monitor batch jobs are not running. Use command STRMONSPLF to start the Monitor jobs. Batch jobs named ST_CTLSPLR and ST_PRCSPLR should be running in a subsystem named COOLSPOOLS, as well as a separate job for each Monitor.

The command DLTSPLTRN allows you to perform housekeeping on the transaction history, selecting transactions to delete based on spooled file age, name and user.

Further Reading

You can find more information on all of the commands mentioned here in the CoolSpools Spool Admin User Guide.