Giving your files meaningful names

Giving your files meaningful names

If you need help with any of the techniques described below, feel free to contact our support team.

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:

Variable name Description
<:FROMFILE:> Spooled file name
<:SPLNBR:> Spooled file number
<:SPLJOB:> Spooled file job name
<:SPLUSER:> Spooled file user name
<:SPLJOBNBR:> Spooled file job number
<:SPLDATE*xxx:> The date the spooled file was created (opened) in the format indicated by *xxx, where *xxx is any one of: *YMD, *MDY, *DMY, *YYMD, *MDYY, *DMYY, *CYMD, *CMDY, *CDMY, *ISO, *EUR, *JIS, *JUL, *LONGJUL, *JOB or *SYSVAL.
<:SPLTIME:> The time the spooled file was created (opened) in hhmmss format.
<:SPLUSRDTA:> The user data attribute of the spooled file.
<:SPLUSRDFNDTA:> The user-defined data attribute of the spooled file.

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.

Variable name Description

<:EXITPGMPOSn:>

where n is a number from 1 to 99

The value of the exit program user-defined parameter selected by the nth element of the EXITPGMPOS command parameter.

If you wish to select text items from the spooled file and use them as variables, but do not wish to call any exit programs, specify EXITPGM(*VAR).

You can assign as name of your own choosing to this item of data by means of the "Variable name" element of the EXITPGMPOS parameter. For example, if you were to specify the variable name "Invoice_number" on the first element of EXITPGMPOS, the CoolSpools variables <:EXITPGMPOS1:> and <:Invoice_number:> could then be used interchangeably.

<:EXITPGMKEYn:>

where n is a number from 1 to 99

The value of the exit program user-defined parameter selected by the nth element of the EXITPGMKEY command parameter.

If you wish to select text items from the spooled file and use them as variables, but do not wish to call any exit programs, specify EXITPGM(*VAR).

You can assign as name of your own choosing to this item of data by means of the "Variable name" element of the EXITPGMKEY parameter. For example, if you were to specify the variable name "Customer_number" on the first element of EXITPGMKEY, the CoolSpools variables <:EXITPGMKEY1:> and <:Customer_number:> could then be used interchangeably.

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:

Function name

$$TRIM

Description

Trim characters from the left and right sides of the data.

Similar to the ILE RPG %trim() builtin function.

Parameters

1

Data to trim (typically a CoolSpools variable).

2

Characters to remove (optional, default = blank).

Example 1

$$TRIM(<::>)

Trims blanks from the start of the value returned by CoolSpools variable <:EXITPGMPOS1:>.

For example, the value

"   000123.45-  "

becomes

"000123.45-"

Example 2

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

Trims zeros from the start of the value returned by CoolSpools variable <:EXITPGMPOS1:>.

For example, the value

"000123.4500 "

becomes

"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.

Function name

$$PADL

Description

Pads a string to a given length by adding a specified character at the start.

Parameters

1

Data to pad (typically a CoolSpools variable).

2

Length to pad to.

3

Characters to pad with (optional, default = blank).

Example 1

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

Pads the value returned by CoolSpools variable <:EXITPGMPOS1:> to a length of 10 characters by adding blanks at the start.

For example, the value

"123.45- "

becomes

"    123.45-"

Example 2

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

Pads the value returned by CoolSpools variable <:EXITPGMPOS1:> to a length of 10 characters by adding zeros at the start.

For example, the value

"123.45- "

becomes

"0000123.45-"

Similarly, $$PADR pads the variable on the right.

Function name

$$REPLACE

Description

Replaces each occurrence of a string in the data with a replacement string.

Similar to a combination of the ILE RPG %scan and %replace functions.

Parameters

1

String to replace.

2

String to replace the string specified in the previous parameter with.

May be an empty string if you wish to delete the string specified in the previous parameter.

3

Data to translate (typically a CoolSpools variable).

Example 1

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

Replaces each occurrence of the character / with a null string (i.e. removes all / characters) e.g. 01/05/2011 becomes 01052011.

Example 2

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

Replaces each occurrence of the string "Facture" with "Invoice".

Function name

$$SUBST

Description

Returns a substring.

Similar to ILE RPG’s %subst.

Parameters

1

Data to substring (typically a CoolSpools variable).

2

Start position.

3

Length (optional, default = to end of string).

Example 1

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

Returns the substring of the value returned by CoolSpools variable <:EXITPGMPOS1:> starting at character position 5 and extending to the end of the string.

For example, the value

"0000123456"

becomes

"123456"

Example 2

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

Returns the substring of the value returned by CoolSpools variable <:EXITPGMPOS1:> starting at character position 5 and extending for 3 characters.

For example, the value

"0000123456"

becomes

"123"

Function name

$$UPPER

Description

Converts a string to upper case, assuming the CCSID of the job.

Parameters

1

Data to convert (typically a CoolSpools variable).

Example1

$$UPPER(<:EXITPGMPOS1:>)

Converts the value returned by CoolSpools variable <:EXITPGMPOS1:> to upper case.

For example, the value "New York" becomes "NEW YORK".

Function name

$$XLATE

Description

Translates characters in the data.

Similar to the ILE RPG %xlate function.

Parameters

1

List of characters to translate from.

2

List of characters to translate to.

3

Data to translate (typically a CoolSpools variable).

4

Start position (optional, default = first).

Example

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

Translates spaces in the value returned by CoolSpools variable <:EXITPGMPOS1:> to underscores, starting at the first character.

For example, the value "New York" becomes "New_York".

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.