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.

Defining an Exit Program to call

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.

Exit Points

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.

• *SPLFSTR

  Start of Spooled File. This exit point is processed before any data is output, i.e. before the first stream file is opened. This might be a convenient place to do startup and initialization tasks prior to the conversion starting.

• *STMFSTR

  Start of Stream File. This exit point is processed after *SPLFSTR for the first stream file and before each stream file is opened. This is typically where you will set attributes for the stream file about to be created, e.g. the stream file name.

• *SHEETSTR

  Start of a new worksheet. This exit point is processed just before a new worksheet is created when converting to Excel format.

• *PAGECTL

  Page Control. This exit point is intended solely to provide an opportunity to generate a CS_FBK01 option structure to indicate whether a particular page should be included or excluded. It is processed for each page in the stream file before the first *PAGESTR exit point is processed to give the application an opportunity to select the pages to be output before any of the pages is output.

• *PAGESTR

  Start of Page. This exit point is processed before any data is output for each page. In relation to the first page of the stream file, it will be processed after *STMFSTR and after *PAGECTL has been processed for each page in the stream file. Please note however that pages may not be processed in page number order. In particular, when creating a PDF file, the first page in the file is processed last, for reasons related to the structure of a web-optimized PDF file.

• *PAGEEND

  End of Page. This exit point is processed after all data has been output for each page. Please note however that pages may not be processed in page number order. In particular, when creating a PDF file, the first page in the file is processed last, for reasons related to the structure of a web-optimized PDF file.

• *STMFEND

  End of Stream File. This exit point is processed after *PAGEEND for the last page in each stream file and before *SPLFSTR for the last stream file.

• *SPLFEND

  End of Spooled File. This exit point is processed after *STMFEND for the last stream file. This may be a convenient place in which to do housekeeping at the end of the conversion run.

• *SHEETEND

  End of a worksheet. This exit point is processed just after a worksheet is finished when converting to Excel format.

Writing an Exit Program

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:

• Bind in the CoolSpools service programs CP_SRVPGM and CS_SRVPGM when creating your program, e.g.:

  CRTPGM … 

  BNDSRVPGM(COOLSPV6R1/CP_SRVPGM

  COOLSPV6R1/CS_SRVPGM)

• Specify that the program should run in the same activation group as the caller, to ensure that the exit program runs in the same activation group as CoolSpools and can therefore modify CoolSpools variables at run time, e.g.:

  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.

• *TYPE1

  Type 1 parameter list. This is the original parameter list format used by exit programs when the exit program function was introduced in Version 2. It is provided for reasons of backwards compatibility. You are recommended to use *TYPE3 or *TYPE4 for future applications.

• *TYPE2

  Type 2 parameter list. This is the parameter list format introduced by Version 3 when the ability to pass more than one user-definable exit program parameter to exit programs was introduced. It is provided for reasons of backwards compatibility. You are recommended to use *TYPE3 for future applications.

• *TYPE3

  Type 3 parameter list. This is a new parameter list format introduced by Version 6. You are recommended to use *TYPE3 for future applications. It is very similar to *TYPE2 but includes some additional features which can be useful when developing applications that use exit programs.

• *TYPE4

  Type 4 parameter list. *TYPE4 is recommended for applications that need to process a large number of user-defined parameters since there is no practical limit to the number of user-defined parameters the *TYPE4 method can handle (the limit for *TYPE3 is 242 user-defined parameters because of the OS/400 limit of 256 parameters passed to a program by the CALL command).

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.

User-defined Exit Program Parameters

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.

APIs for managing the option structure list

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

• Override the name of the stream file to be created based on a piece of data extracted from the stream file at run time, such as an invoice number

• Set up the list of email addresses to which the stream file should be sent, or the password to be applied to a PDF file, based on a customer number extracted from the spooled file

• and so on...

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.

Uses of Exit Programs

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.

Sample Programs

See the sample programs in the CS_SRCFILE source file included with CoolSpools:

• EXITTYPE1

  A sample exit program using an *TYPE1 parameter list. Use of this type of parameter list is no longer recommended and is provided for reasons of backwards compatibility only.

• EXITTYPE2

  A sample exit program using an *TYPE2 parameter list. Use of this type of parameter list is no longer recommended and is provided for reasons of backwards compatibility only.

• EXITTYPE3

  A sample exit program using an *TYPE3 parameter list. *TYPE3 parameter lists are simple to use but are limited to no more than 242 user-defined parameters.

  This program demonstrates how to set up the name of the stream file to be created and the email addresses of the people to receive the stream file. It is intended to be called at the *STMFSTR exit point.

• EXITTYPE4

  A sample exit program using an *TYPE4 parameter list. *TYPE4 parameter lists are more complex to use but support a practically unlimited number of user-defined parameters.

  This program demonstrates how to set up the name of the stream file to be created and the email addresses of the people to receive the stream file. It is intended to be called at the *STMFSTR exit point.

• EXITTYPE4B

  A sample exit program using an *TYPE4 parameter list using the alterative CS_UDP02 format for he user-defined parameters. *TYPE4 parameter lists are more complex to use but support a practically unlimited number of user-defined parameters. CS_UDP02 includes additional information about the position on the page of the data that was extracted.

  This program demonstrates how to set up the name of the stream file to be created and the email addresses of the people to receive the stream file. It is intended to be called at the *STMFSTR exit point.