If you need help with any of the techniques described below, feel free to contact our support team.
How do I write an exit program for CoolSpools to call?
This article just gives an overview of this topic. For full details of how to write an exit program and the CoolSpools APIs that can be called from exit programs, refer to the CoolSpools Programmer’s Guide.
One of CoolSpools’ most powerful features is its ability to call exit programs that can influence its processing during the course of a spooled file conversion. Exit programs allow you to override conversion parameters at run time, setting attributes such as the name of the stream file to be created, the email addresses to which the file should be emailed and even whether particular pages should be included or excluded.
You normally specify exit programs to call on the EXITPGM parameter of one of the CVTSPLPDF, CVTSPLXLS command etc. This parameter allows the definition of up to 100 exit programs at any of the exit points listed below.
If multiple exit programs are defined at the same exit point, CoolSpools will call them in the order in which they are defined.
When you define an exit program to be called, you must specify the exit point at which it is to be called. The following exit points are currently defined.
Exit programs can be written in any language which can be compiled into an system i *PGM object.
However, if you want to use the option structure list APIs to interact with CoolSpools options at run time, you will need to use an ILE language to call them. In order to modify the CoolSpools options, the exit program must run in the same activation group as CoolSpools and this is not possible for an OPM program.
When creating a CoolSpools exit program, if you plan to use any of the Option List APIs to modify CoolSpools variables at run time, you must ensure that you:
CRTPGM … ACTGRP(*CALLER)
CoolSpools Exit Programs are passed a standard parameter list in one of four formats. These parameters typically include a standard set of useful information (e.g. details of the spooled file being converted and the stream file being created), plus, optionally, one or more user-defined parameters containing data extracted from the spooled file at run time.
Please note that *TYPE3 and *TYPE4 programs have an additional feature which does not apply to *TYPE1 or *TYPE2 exit programs. As well as being called at their normal exit point, they are called once again at the end of processing with the exit point parameter set to *END. This is intended to provide a means of notifying the exit program that processing is complete and give it an opportunity to perform housekeeping tasks such as closing files.
The format of the different parameter lists is specified in the CoolSpools Programmer’s Guide.
Copybooks CS_EXTTP1P, CS_EXTTP2P, CS_EXTTP3P and CS_EXTTP4P in source file CS_SRCFILE can be used to define these parameter lists in an exit program written in ILE RPG. In addition, source member CS_EXTTP4D defines the structures used by *TYPE4.
There are two types of user-defined exit program parameters, positional and key parameters.
A positional parameter is extracted from the spooled file and passed to an exit program by specifying the position on the page at which the text to be extracted is located. This is most suitable for those text items which always appear at the same position on each page.
For example, if you know that the customer number always appears at column 3 of line 6 of your page, you can tell CoolSpools to extract the customer number from the spooled file and pass it to your exit program as a parameter by defining it as a positional exit program parameter.
A key parameter is extracted from the spooled file and passed to an exit program by specifying its position in relation to a key string, i.e. an item of text which appears on the page and in relation to which the parameter text always appears at a regular offset.
For example, if you know that the customer number can appear on different lines on your page, it cannot be extracted as a positional exit program parameter. However, if it always appears at a fixed position from the label “Customer number:”, you can use this label as a key string and tell CoolSpools to extract the customer number from the spooled file and pass it to your exit program as a parameter by defining it as a key exit program parameter.
When running the CVTSPLPDF, CVTSPLXLS command etc., you must indicate what type of parameters you wish to extract from the spooled file using the EXITPGMPRM parameter. This ensures that you are prompted for the right command parameters.
Positional exit program parameters are defined using the EXITPGMPOS command parameter.
Key exit program parameters are defined using the EXITPGMKEY command parameter.
CoolSpools provides a set of APIs for managing the option structure list.
The CoolSpools option list is the set of variables that controls the way CoolSpools operates. Typically, the option list is established when a command runs from the command parameters and defines things like the name of the file to be created and the email address of the person or people to whom the file will be emailed.
However, sometimes you will want to change these at run time. For example, using an exit program that calls the option list APIs you could
This can be done by calling the Option List APIs fro m your exit program. The APIs you need to call and the structures you need to set up and pass to those APIs are defined in the CoolSpools Programmer’s Guide.
Constants and prototypes needs to call the option list APIs are provided in copybook AR_OPTFNCP in CS_SRCFILE, which also contains a number of sample programs that demonstrate the use of these APIs.
Exit programs can be used for a variety of purposes. Some of these are explored below.
Exit programs called at the *STMFSTR (Start of Stream File) exit point are ideal for setting various attributes related specifically to the stream file about to be processed.
For example, an exit program might add a CS_STM01 option structure to the option structure list, scoped to the range of pages covered by the stream file, which is available from the exit program parameter list, in order to set the stream file name to be something specific to the contents of the file about to be produced. The name could be based on the value of an exit program parameter extracted from the spooled file containing, say, the customer number or order number.
Note that this could also be achieved through the use of the <:EXITPGMPOSn:> or <:EXITPGMKEYn:> CoolSpools parameters. See this FAQ answer for details.
Similarly, you might want to include a graphic specific to the file in question. You could do this by adding a CS_INC01 option structure to the option structure list specifying the name of a JPEG image appropriate for the customer in question (e.g. their logo), identified by means of a user-definable parameter containing the customer number.
Other attributes you might consider modifying at this exit point include the security settings and passwords of PDF files, (CS_PWD01 option structure), email attributes (CS_EML01) and email recipients (CS_EMT01).
The *STMFEND exit point, on the other hand, is a good place at which to do post-processing operations on the file just created. For example, you might want to move it to a different directory, rename it, email it (if not done by CoolSpools) or interface into a document management system.
All of these things and many more are possible by calling an exit program.
See the sample programs in the CS_SRCFILE source file included with CoolSpools: