FAQ: Splitting/bursting spooled files

My spooled file contains multiple documents that need to be sent to different people. How can I split/burst the spooled file?

Easy. CoolSpools has some great options for splitting spooled files. Unlike most other products, you don’t need to modify your spooled file to do this either.

The relevant command parameters are:

• SPLIT
• SPLITPAGE
• SPLITPOS
• SPLITKEY

The SPLIT parameter tells CoolSpools to create several stream files from a single spooled file, splitting the spooled file based on criteria that you specify on the SPLITPAGE, SPLITPOS and/or SPLITKEY parameters.

This option can be useful if your program produces a single spooled file which has traditionally been split up into separate pages or groups of pages prior to distribution on paper.

There are a number of different ways in which you can tell CoolSpools when to create a new file. These give an enormous amount of flexibility and we have not yet found an application where one of these options is not able to do the job. Here are just the most commonly found scenarios:

• Every so many pages
  

  This is the simplest situation, where every “logical document” in the spooled file is always exactly the same number of pages in length.For example, if your invoice spooled file contains a batch of invoices, and each invoice is always exactly 3 pages long, you can simply tell CoolSpools to create a new file every 3 pages by specifying the SPLIT(*PAGE) option and the number of pages on the SPLITPAGE parameter, e.g.:

  CVTSPLPDF ... SPLIT(*PAGE) SPLITPAGE(3)

• When a piece of text is found at a fixed position on the page
  

  If your invoices can contain a variable number of pages, you can’t use SPLIT(*PAGE), but it’s likely the start of a new invoice can be identified by the occurrence of a piece of text at a constant position on the page. For example, the first page of the invoice might contain the word “I N V O I C E” on line 3 at column 50. You can tell CoolSpools to check this position on the page for that text string and create a new file every time it is found like this:

  CVTSPLPDF ... SPLIT(*POS) SPLITPOS((3 50 13 *ROWCOL *EQ 'I N V O I C E'))

• When a piece of text at a fixed position on the page changes
  Another way to identify the start of a new document, might be to check for a change in the value of a field at a fixed position on the page, such as an invoice number. If the invoice number appears on line 6 at column position 20 and is 7 characters in length, you can check for a change in that field by specifying:

  CVTSPLPDF ... SPLIT(*POS) SPLITPOS((6 20 7 *ROWCOL *NE *PRV))

  where *PRV is a special value denoting “the value at that position on the previous page”

• Checking for data in a document trailer rather than a header
  Sometimes, it’s more convenient to identify the end of a document rather than the start of a document. For example, there might not be any convenient piece of text marking the start of your invoice, but the end of an invoice might be easy to locate by means of a piece of text such as “END OF INVOICE”.To use a piece of text at a constant position to locate the end of the document, specify:

  CVTSPLPDF ... SPLIT(*POS *AFTER)

  so CoolSpools knows to create a new file after the page on which the text is found, not before it as is the default.

• Every time a piece of text appears, anywhere on the page
  

  If you’re sure the piece of text only ever appears on the page when a new file should be created (either on the first or the last page of the document), you can use SPLIT(*KEY) and the SPLITKEY() parameter to identify the string.

  CVTSPLPDF ... SPLIT(*KEY *BEFORE) SPLITKEY('STRING FOUND ON FIRST PAGE ONLY')

  CVTSPLPDF ... SPLIT(*KEY *AFTER) SPLITKEY('STRING FOUND ON LAST PAGE ONLY')

When creating an Excel file, you can also now tell CoolSpools to split a spooled file and create a new worksheet in the output file rather than a new file.

If you specify several levels of splitting, you can also split to new files and new sheets at the same time.

For example, imagine you have a sales report that contains sales figures organized by region and then by city with region. You might want to create one spreadsheet per region, but have separate worksheets for each city within the region. This might be achieved by telling CoolSpools to split every time the region name changes, and create a new workbook, and also to split every time the city name changes, but create a new worksheet when that happens.

For example, if the region name is on line 3 at position 5 for 10 characters and the city name on line 4 at position 5 for 20 characters:

CVTSPLXLS ...

   SPLIT(*POS *AFTER)

   SPLITPOS((3 5 10 *ROWCOL *NE *PRV *WORKBOOK) (4 5 20 *ROWCOL *NE *PRV *WORKSHEET))