I want to give my files a meaningful name. How can I do that?

CoolSpools has some really flexible and powerful features to help with this. You can use some attribute or combination of attributes of the spooled file, or you can extract data (e.g. invoice number, customer name) from inside the spooled file and use it to build the name.

Let's take a look at some of the features you can use.

CoolSpools Variables

Certain command parameters, including the TOSTMF ("To Stream File") parameter on which you specify the path name of the output file to create, support the use of CoolSpools variables.

CoolSpools variables consist of a pre-defined variable name enclosed in the special marker characters <: … :> (start of variable marker = left-hand angle bracket followed by a colon, end of variable marker = colon followed by a right-hand angle bracket).

These variable names, including the markers, are replaced at run time by the corresponding data value.

Variable names are not case-sensitive.

For example, if you wanted to give your file a name derived from the user data attribute of the spooled file, you can use the <:SPLUSRDTA:> CoolSpools variable like this:

CVTSPLPDF ... TOSTMF('This name includes the user data <:SPLUSRDTA:>.pdf')

If the user data attribute of the spooled file being converted was "SALESFEB10", the actual name of the file created would be:

This name includes the user data SALESFEB10.pdf

Be careful when using this feature that you do not generate invalid file names. For example, if the user data above had been "SALES10/02", this would have resulted in the file name:

This name includes the user data SALES10/02.pdf

which contains a /. OS/400 (IBM i) will interpret this / as a directory separator and attempt to create a file called "02.pdf" in a directory called "This name includes the user data SALES10", which will probably result in a run-time error.

You can avoid issues of this kind by using CoolSpools Functions to fix up the data, e.g. convert invalid characters such as /, \ and ' to something else using the $$XLATE function.

If the default variable markers <:...:> are not convenient for whatever reason, you can define a different pair of markers from by adding/changing the environment variables CS_VAR_LEFT_MARKER and CS_VAR_RIGHT_MARKER. For example, if you have CS_VAR_LEFT_MARKER set to $% and CS_VAR_IGHT_MARKER set to %$, you would use $%PAGSETNBR%$ rather than <:PAGSETNBR:> etc.

A full list of the CoolSpools variables that can be used can be found in the CoolSpools Spool Converter User Guide and CoolSpools Database User Guide.

Here are just a few of the more commonly used ones:

Extracting data from the spooled file at run time

Perhaps the most powerful CoolSpools variables are <:EXITPGMPOSn:> and <:EXITPGMKEYn:>.

Originally, the purpose of the EXITPGMPOS and EXITPGMKEY command parameters was to allow you define areas of the page from which data was to be extracted at run time and passed to an exit program as parameters, and you can still use them for that purpose (see below for further information on the use of exit programs).

However, you can now achieve a lot of what you used to have to with an exit program simply by using these parameters in conjunction with the special CoolSpools variables <:EXITPGMPOSn:> and <:EXITPGMKEYn:>.

If you don't want to actually call an exit program, but want to be able to use the EXITPGMPOS and/or EXITPGMKEY parameters, specify the special value *VAR for the EXITPGM parameter, e.g.:

CVTSPLPDF ... EXITPGM(*VAR)

These allow you to include data extracted from the spooled file at run time in things like the name of the file to be created. This might be an invoice number, customer number, customer name, date or anything else you might like to use that is available somewhere on the page.

Use the EXITPGMPOS parameter to identify the data to be extracted if it occurs at a fixed position on the page and you can specify its coordinates in terms of a page number, line number, column position and length.

Use the EXITPGMKEY parameter if that's not possible, e.g. if the line number can vary, but if the data always appears at a fixed offset from a "key string" such as a field label. For example, you might pick up a customer number by defining it as appearing 25 characters to the right of the text "Customer number . . . :"

In Version 6 of CoolSpools, you can now define a name by which you will refer to the data item you have identified with EXITPGMPOS or EXITPGMKEY. For example, of the data item you're defining is an invoice number, you might call the item "INVOICE" and then you can refer to it using the variable name <:INVOICE:>

Examples 1:

CVTSPLPDF ...

TOSTMF('invoice_<:EXITPGMPOS1:>.pdf')

EXITPGM(*VAR)

EXITPGMPRM(*POS)

EXITPGMPOS((1 5 10 7))

Assuming the invoice number has the value 2134567 and that it appears on page 1, line 5, column position 10 and is 7 characters in length, this will pick up the value of the invoice number at run time and create a PDF file called invoice_1234567.pdf

Examples 2:

CVTSPLPDF ...

TOSTMF('invoice_<:INVOICE:>.pdf')

EXITPGM(*VAR)

EXITPGMPRM(*POS)

EXITPGMPOS((1 5 10 7 'INVOICE'))

Here, the same results are achieved, but this time the data item being extracted is given the name INVOICE in order to allow the use of a more meaningful variable name <:INVOICE:>.

These variables are further documented in the table below.

CoolSpools Functions

As described above, there are occasions when it might be necessary to make adjustments to the data returned by a CoolSpools variable before it can be used. For example, if you want to use the variable to create a file name, and the data returned by the variable contains a character not permitted in a file name such as /, you will run into trouble if you don't fix up the data before use.

You can fix up your data by using CoolSpools functions. A CoolSpools function has a name which, by default, starts with the marker $$, and will require one or more parameters, normally a CoolSpools variable to serve as the input to the function and possible some other parameters telling the function precisely what you want to do with the value of that CoolSpools variable.

CoolSpools functions are often similar to builtin functions in ILE RPG. For example, the CoolSpools functions $$SUBST, $$TRIM and $$XLATE carry out much the same tasks as RPG's %subst, %trim and %xlate.

Function parameters are enclosed in parentheses () and separated by commas. Character values used as parameters are case-sensitive and can be either enclosed in single quotes ' ' (doubled up where required by OS/400), double quotes " ", or not enclosed by anything.

Function names are not case-sensitive.

A full list of the CoolSpools functions that can be used can be found in the CoolSpools Spool Converter User Guide and CoolSpools Database User Guide.

Here are just a few of the more commonly used ones:

$$TRIM(<::>)

"   000123.45-  "

"000123.45-"

$$TRIM(<:EXITPGMPOS1:>,’0’)

"000123.4500 "

"123.45 "

Similarly $$TRIML trims characters just from the left (start) of the data and $$TRIMR trims characters just from the right (end) of the data.

$$PADL(<:EXITPGMPOS1:>,10)

"123.45- "

"    123.45-"

$$PADL(<:EXITPGMPOS1:>,10,"0")

"123.45- "

"0000123.45-"

$$REPLACE("/","",<:EXITPGMPOS1:>)

$$REPLACE("Facture","Invoice",<:EXITPGMPOS1:>)

$$SUBST(<:EXITPGMPOS1:>,5)

"0000123456"

"123456"

$$SUBST(<:EXITPGMPOS1:>,5,3)

"0000123456"

"123"

$$UPPER(<:EXITPGMPOS1:>)

$$XLATE(" ","_",<:EXITPGMPOS1:>,1)

Exit Programs

If none of the techniques described above will give you what you want, you can achieve total control over naming your files, the directory path in which they are created, and many other aspects of processing, through the use of exit programs.

An exit program will be passed a standard set of program parameters containing useful information such as the details of the spooled file being converted and the range of pages currently being processed, but can also receive as parameters data items extracted from the spooled file at run time by means of the EXITPGMPOS and EXITPGMKEY command parameters, for example an invoice or customer number.

For further details of how to write an exit program, see the FAQ on that topic.