CoolSpools

User Guide

Version V4R1M0 October 2003

@riadne software ltd, cheltenham, england

Table of Contents

Introduction...........................................................................................6

Applications........................................................................................................... 6

Automated distribution of reports and documents ................................................ 6

Information sharing............................................................................................... 6

Report Enhancement ........................................................................................... 7

Archiving and offline storage ................................................................................ 7

Document Formats................................................................................................ 7

Adobe® PDF (Portable Document Format).......................................................... 7

RTF (Rich Text Format )....................................................................................... 8

HTML (Hypertext Mark-up Language).................................................................. 8

Excel Format ........................................................................................................ 8

Delimited ASCII Text ............................................................................................ 9

Plain ASCII Text ................................................................................................... 9

TIFF format........................................................................................................... 9 Archive format ...................................................................................................... 9

Features ................................................................................................................. 9

Support for AFP, IPDS and SCS spooled files ..................................................... 9

Colorize your reports! ......................................................................................... 10

User-definable Font Mapping ............................................................................. 10

PDF Bookmarks ................................................................................................. 10

PDF Data Compression ..................................................................................... 11

Web-optimized PDF ........................................................................................... 11

Encrypted and password-protected PDF............................................................ 11

Spooled File Splitting.......................................................................................... 11

User-definable Exit Programs............................................................................. 12

Upgrade Notes ....................................................................................12

License Keys ....................................................................................................... 13

Re-testing your applications .............................................................................. 13

Minimum OS/400 Release Level......................................................................... 13

Product Library ................................................................................................... 13

Licensed Program Id .......................................................................................... 14 Changes between V3.1 to V4.1........................................................................... 14

Upgrade Notes for V2.1 Users ...........................................................14

Changes between V2.1 and V3.1........................................................................ 15

Bookmarks, Split keys and Exit Program Parameters ........................................ 15

EXITPGMPOS and EXITPGMKEY parameters ................................................. 15

PAGESIZE parameter ........................................................................................ 16

MARGINS parameter ......................................................................................... 16

What’s new in this release? ...............................................................16

Installation...........................................................................................18

Method 1: Installing CoolSpools using FTP ..................................................... 18

Method 2: Installing CoolSpools using the IFS ................................................ 20

Maintenance........................................................................................23

Method 1: Installing a PTF using FTP................................................................ 23

Method 2: Installing a PTF using the IFS .......................................................... 25

Using CVTSPLSTMF...........................................................................27

Getting Started ................................................................................................... 27

Command Parameters ....................................................................................... 28

FROMFILE ......................................................................................................... 29

TOSTMF............................................................................................................. 30 JOB .................................................................................................................... 31

SPLNBR............................................................................................................. 32

TOFMT............................................................................................................... 33

STMFOPT .......................................................................................................... 35

EMAIL ................................................................................................................ 36

PMTADLPARM .................................................................................................. 37

EMAILOPT ......................................................................................................... 38

EMAILFROM...................................................................................................... 41

EMAILTO............................................................................................................ 42

EMAILMSG ........................................................................................................ 44

TITLE ................................................................................................................. 46

PAGESIZE ......................................................................................................... 47

PASSWORD ...................................................................................................... 50

SPLIT ................................................................................................................. 54

EXITPGM ........................................................................................................... 56

FONT ................................................................................................................. 60

TEXT .................................................................................................................. 63

DBCS ................................................................................................................. 65

MARGINS........................................................................................................... 66

RTFMARGINS.................................................................................................... 67

INCLFILE............................................................................................................ 68

COLOR .............................................................................................................. 70

CVTFONTID....................................................................................................... 72

CVTFNTRSC...................................................................................................... 75

BLANKS ............................................................................................................. 78

DELIMITERS...................................................................................................... 79

PDFVIEWER...................................................................................................... 81

EXCLPAGES...................................................................................................... 84

EXCLLINNBR..................................................................................................... 86

EXCLLINKEY ..................................................................................................... 87

WORKSIZE ........................................................................................................ 88

CUSTOMPAGE.................................................................................................. 89

BMARKPOS....................................................................................................... 90

BMARKKEY ....................................................................................................... 92

SPLITPAGE ....................................................................................................... 94

SPLITKEY .......................................................................................................... 95

SPLITPOS.......................................................................................................... 98

EXITPGMPRM ................................................................................................. 100

EXITPGMPOS.................................................................................................. 101

EXITPGMKEY.................................................................................................. 102

STMFCODPAG................................................................................................ 103

SPLFCCSID ..................................................................................................... 105

AUT .................................................................................................................. 107

INHERITAUT.................................................................................................... 109

DFTFONT......................................................................................................... 110

TODIR .............................................................................................................. 112

Using CVTSTMSPLF.........................................................................114

Using CVTSTMSPLF.........................................................................114

FROMSTMF..................................................................................................... 114

FROMDIR......................................................................................................... 114

NEWOWN ........................................................................................................ 114

OUTPTY........................................................................................................... 115

Specifying coordinates and key strings ............................................................ 116

Appendix A: Sample Exit Programs................................................117

Appendix B: The Integrated File System.........................................123

Appendix C: Acknowlegements ......................................................127

Page: 6

Introduction CoolSpools is a rich set of software tools which enable businesses to adapt their traditional AS/400 reports to the challenges of the new age of e-commerce and the Internet. If you are currently using Version 3.1 of CoolSpools, please see the section “Upgrade Notes for V3.1 Users” before switching to Version 4.1. If you are currently using Version 2.1 of CoolSpools, please see both sections “Upgrade Notes for V3.1 Users” and “Upgrade Notes for V2.1 Users” before switching to either higher version (V3.1 or V4.1). These sections discuss a number of changes between the various versions which you must consider before your upgrade to a later version of CoolSpools. If you’re already familiar with earlier versions of CoolSpools, you may like to go straight to the “What’s new in this release?” section of this document. Let's have a look at what CoolSpools can do for your business.

Applications The CoolSpools product revolves around the CVTSPLSTMF (Convert Spooled File to Stream File) command, which takes almost any AS/400 spooled file and converts it into a PC-style document. This popular utility combines ease of use with a wide range of options and features. CoolSpools can help streamline and modernize many areas of your business without forcing you to re-program existing applications.

Please note that CoolSpools does not currently support *USERASCII spooled files.

Automated distribution of reports and documents Still sending reports out on paper? Maybe you take orders over the Web but still have to send invoices by snail-mail because the invoicing application is an old AS/400 package? Files created by CoolSpools can be e-mailed to users, colleagues and customers, rather than sent out on paper. Not only does this save you money and simplify your business processes, it also makes clear to everyone that your business is responding to the challenges of the Internet era.

Information sharing However many copies of a report you print, it's never enough. There's always someone else who'd like to see it but is in an office on the other side of the country and can't get access to a copy. Files created by CoolSpools can be stored on a central corporate server, such as your AS/400, or a PC server, and shared amongst all your users as a corporate information resource. Alternatively, you could publish them on your Web site for customers worldwide to see, or on a secure Intranet or Extranet.

Page: 7

Report Enhancement CoolSpools doesn’t just convert your reports, it enhances them too. For example, when converting to PDF format, you can add bookmarks that index the pages of your report so your users can find the information they want quickly and easily. When you create a PDF or HTML document from a spooled file, you can add color to improve the presentation as well. Maybe you couldn’t afford an AS/400 color printer: now that’s no longer an issue since you can simply convert your spooled file to PDF and print your document on an inexpensive PC color printer!

Archiving and offline storage The AS/400 provides no built in means of saving and restoring spooled files. Yet for many companies their AS/400 reports are a critical part of the business process, and may not be easy to re-create. Maybe you have to waste large amounts of expensive AS/400 disk just keeping copies of old reports online. Doing this can also impact your system's performance, since jobs which created spooled files remain in the system even when they have ended if they created spooled files which still exist on an output queue, Files created by CoolSpools can be stored on inexpensive storage media such as PC disk or CD-ROM for easy retrieval. Once CVTSPLSTMF has converted your report into a stream file, you can move this file to a PC server, or save it to tape or to CD-ROM, then delete the original spooled file, freeing up precious AS/400 resources. CoolSpools offers several options for archiving spooled files. You can convert the spooled file to a PDF file, in which case you would use Adobe Acrobat reader to re-print the report; you can convert it to an RTF (Rich Text Format) file, in which case you would use a Word Processor such as MS Word or Lotus WordPro; or you can use the TOFMT(*SAV) option, in which case the CVTSTMSPLF (Convert Stream File to Spooled File) command can be used to restore the original spooled file from the stream file archive. Both TOFMT(*PDF) and TOFMT(*SAV) use data compression to minimize the size of the archived spooled file. The data compression algorithm used is an AS/400 implementation of the industry-standard zlib compression library, developed by Jean-loup Gailly and Mark Adler, to whom our thanks are due.

Document Formats Let's have a closer look at how CoolSpools achieves all this.

CVTSPLSTMF takes an AS/400 spooled file and converts it to a PC document stored as a stream file on the AS/400. The stream file can be saved anywhere in the IFS (Integrated File System) and is available for use by any authorized PC user with a suitable Client Access network drive assigned.

You can choose several different formats for your files, depending on your particular requirements. Additional formatting options will be introduced in future versions of the product. For the moment the formats supported are:

Adobe® PDF (Portable Document Format) Adobe® Portable Document Format (PDF) is the de facto standard for electronic document distribution. Adobe PDF is a universal file format that preserves the fonts

Page: 8

and formatting of the source document. PDF files are compact and can be shared, viewed, navigated, and printed exactly as intended by anyone with a copy of the free Adobe Acrobat Reader, which can be downloaded from many places on the Internet, including the Adobe site at http://www.adobe.com/products/acrobat/readstep.html. Adobe PDF is the ideal format for electronic document distribution because it overcomes the problems commonly encountered in electronic file sharing. If you create a document in PDF format and e-mail it to a customer, so long as the recipient has a copy of the Acrobat reader, you can be confident that they will be able to read and print the document and that it will appear to them just as it did to you when you created it. PDF files can be published and distributed anywhere. You can attach them to e-mail, make them available on a corporate server, an Intranet or Extranet, post them on Web sites or circulate them on CD-ROM. If you want to use CoolSpools to distribute and archive your AS/400 reports, PDF is the format to choose.

RTF (Rich Text Format ) RTF (Rich Text Format) is a format understood and handled by most if not all modern Word Processing applications, including MS Word, Lotus WordPro, MS WordPad etc. CoolSpools preserves text formatting and fonts found in your spooled files and reproduces these in the RTF document.

HTML (Hypertext Mark-up Language) However, if for some reason your want to view your reports in a browser, such as Netscape® Navigator or Microsoft ® Internet Explorer, CVTSPLSTMF is there to help you. HTML is the language in which web pages are written. CVTSPLSTMF can convert your spooled files to HTML and in fact supports not one but three HTML styles! Which of these styles you choose depends on various factor such as how up to date your browser software is and whether you want your text to appear laid out on the screen exactly as it was on the original paper report, or whether you are more interested in ensuring that text attributes such as bold type, fonts and underlining are reflected in the HTML version of the report. Please note that HTML is not recommended for distributing and archiving your AS/400 reports. HTML has certain limitations which makes it impossible to guarantee that a report converted to HTML will appear on screen or print exactly like the original report. For example, there is no means of controlling page throws reliably in the version of HTML supported by the main browser programs in use today. In the main, you should choose PDF for distributing and archiving your reports.

Excel Format If you specify TOFMT(*XLS), CVTSPLSTMF will create an Excel (™) spreadsheet from your spooled file. This is most suitable for spooled files containing columns of text and/or numbers. Options allow you to exclude unwanted lines from your report as it is converted to Excel format (for example, report headings not required in the spreadsheet).

Page: 9

Delimited ASCII Text CVTSPLSTMF can also convert your report into a delimited ASCII text file, such as a CSV (comma-separated variable file). This format is ideal for loading reports containing columns of numbers into a spreadsheet, Business Intelligence tool or other application for further manipulation. CVTSPLSTMF can use any field delimiter you like (by default a comma, but also tabs, blanks etc.) and any string separator you specify (by default a double quote “), allowing you to generate files in the precise format required by your PC application.

Plain ASCII Text CVTSPLSTMF will also simply convert your AS/400 spooled file to a basic ASCII text file. This file can then be loaded into virtually any PC application, such as a word processor or spreadsheet. ASCII text versions of your spooled files may also be useful for indexing purposes as part of a document management solution. Please note, however, that when loaded into a spreadsheet, you may need to do additional work to line the text up correctly in columns. You will probably achieve better results using a delimited ASCII text file.

TIFF format When you specify the TOFMT(*TIFF) option, CVTSPLSTMF generates a TIFF (Tagged Image Format File). This is suitable for viewing in an imaging application such as Wang Image Viewer.

Archive format When you specify the TOFMT(*SAV) option, CVTSPLSTMF generates a highly compressed archive file from your spooled file. This facility allows you to save AS/400 resources by removing spooled files from your system. You simply convert the spooled file to a stream file in *SAV format, then delete the original spooled file. If you need to re-print the report, you can restore it from the archive file using the sister command to CVTSPLSTMF, namely CVTSTMSPLF (Convert Spooled File to Stream File). Stream files in *SAV format can also be attached to e-mails and sent to other AS/400 users, who can then restore the spooled file to their own system. Please note that the stream files created using this option still reside on your AS/400 disks, albeit in the IFS rather than as a spooled file. You should use the OS/400 SAV command to back these stream files up to tape, or copy them to CD-ROM or to a PC server, before considering that your spooled files are truly secure. Please note also that these archive files are not viewable in any PC application.

Features CVTSPLSTMF provides a number of useful features available from few if any other similar products on the market.

Support for AFP, IPDS and SCS spooled files Many businesses have moved on from traditional AS/400 line-printer reports and are using AFP (Advanced Function Printing) to improve the presentation of their reports. AFP in particular allows you to incorporate proportional fonts, color and graphics into

Page: 10

your reports to improve their appearance, and to use page segments and overlays to simplify programming. Most other products which convert spooled files are limited to old-fashioned SCS (SNA Character String) spooled files. CVTSPLSTMF supports AFP and IPDS spooled files as well as SCS. This support comprises: color, line graphics, variable fonts, overlays and page segments, raster graphics and most types of compressed IOCA images. Please note that there are some less widely used AFP features that are not supported in this release of CoolSpools. These include:

• The following less commonly used barcodes: EAN2, EAN5, AP4SCC, DUTCHKIX, JPBC

• Images compressed using methods other than IBM’s standard IBM MMR algorithm

Also note that not all features are supported by all output file format. Many more advanced features of your spooled file will only be reproduced in PDF. For example, images and line graphics are only supported when converting your spooled file to PDF format. It is not currently possible for CoolSpools to recreate images and line graphics in HTML, RTF or Excel, and this will never be possible in relation to ASCII text or CSV where these formats are incompatible with these kinds of data.

Colorize your reports! If your AFP report includes color, CVTSPLSTMF will reproduce those colors in your PDF or HTML output. However, if you would like to add color to your reports but can’t afford an AS/400 color printer, CVTSPLSTMF can still help. You simply specify a color for both the text and background of your report and CVTSPLSTMF will use those colors in PDF and HTML. Alternatively, you might want to re-code your report to use colors, but print the PDF output on an affordable PC color printer rather than a mega-bucks AS/400 printer.

User-definable Font Mapping If you do not wish to embed fonts in your PDF file, either because those fonts cannot be embedded or in order to keep the size of the PDF as small as possible, you can ask CoolSpools to map the AS/400 font to an equivalent PC font. However, CoolSpools automatic selection of PC font may not always give acceptable results. No matter: CVTSPLSTMF provides you with the information you need to specify how fonts in the report should be mapped, thus ensuring that the resultant PDF document is as close as possible in appearance to the original report.

PDF Bookmarks This popular feature of CVTSPLSTMF allows you to go further than just creating a copy of your report in PDF: you can actually enhance the content of your report too by creating a set of bookmarks. These help your users navigate around the report on screen and go quickly and easily to the information they require. Bookmarks can be created based on either a piece of text which appears regularly at the same position on each page, or by means of a keyword or phrase (e.g.

Page: 11

"Customer name:") which labels the information you wish to use to create the bookmarks.

PDF Data Compression The data in your PDF files is held in compressed format. This can dramatically reduce the size of the files created, making them quicker and easier to e-mail and load, and making PDF even more attractive as an option for archiving your reports.

Web-optimized PDF PDF files are "linearized", that is they are structured in a way that minimizes the time it takes to open the file over the Web or your Wide Area Network. Please note that the various versions of Acrobat Reader behave differently in relation to web optimization. Some versions of Acrobat may consider a PDF file created by CoolSpools to be optimized while earlier versions consider the same file to be not optimized. If web optimization is important to you, we recommend that you install the latest available version of Acrobat Reader (currently Version 6.0).

Encrypted and password-protected PDF PDF files can now be password protected or have restrictions applied to the operations that can be performed on it. A password-protected PDF file will require you to enter a password before it can be opened in Adobe Acrobat Reader, Adobe Acrobat or any other PDF Viewer application. Moreover, just opening the file in a text editor is to no avail as the textual content of the file is encrypted using a highly secure industry standard encryption algorithm. Alternatively, if you want to limit what can be done to the file (e.g. stopping it from being modified), this can also be achieved without requiring a password to be input.

Spooled File Splitting CVTSPLSTMF has the ability to split a single spooled file into several separate stream files. Perhaps you have an application which creates a single spooled file containing invoices for a number of customers. Maybe at the moment, these invoices are printed, split by hand or machine, and distributed through the mail. Perhaps now you would like to start sending your invoice out by e-mail in PDF format. Unlike other tools, which would require you to make application changes to achieve this, CoolSpools provides a number of options which allow you to define split points in your spooled file. A new stream file will be created every time a split point is identified. In this way, you can easily create separate invoices for each customer from a single invoice spooled file. You can control where splitting occurs in several ways:

• Every so many pages. For example, if each invoice is exactly 4 pages long, you should create a new stream file every 4 pages.

• By checking for the appearance in the spooled file of a given “key string”. For example, if each invoice has the words “Customer name” in the headings at the start of the first page, you could start a new stream file every time the words “Customer name” appear in the spooled file.

• By checking for changes in the text at a specified position on the page. For example, if the customer number appears at column 5 of line 3 on every page,

Page: 12

you might want to create a new stream file every time the value at this position changes, i.e. for each new customer number.

• By comparing text at a particular position on the page against a specified value. For example, if the page number appears on each page at column 120 of line 1, and if the page number is reset to 1 for each new customer in the spooled file, you could create a new stream file every time the text at column 120 of line 1 is equal to “Page: 1”.

User-definable Exit Programs You can instruct CVTSPLSTMF to call a user-written exit program at any of three different points whilst processing your spooled file. These points are:

• every time it finishes processing a page

• every time it finishes creating a PDF file

• at the end of the spooled file. The exit program is passed one of two standard sets of parameters. These parameters can include one or more text strings extracted from the spooled file according to criteria that you define. Coupled with the ability to split spooled files described above, this gives you the power to adapt existing applications without needing to re-program them. For example, you could tell CVTSPLSTMF to split your invoices spooled file into separate PDF files for each customer, and ask it to call an exit program after each PDF file has been created. CVTSPLSTMF could extract the customer number from the spooled file and pass it to the exit program as a parameter. The exit program could then retrieve the customer's e-mail address from the database and invoke a mail application to send the pdf file to the customer.

Upgrade Notes Please read the following notes carefully before upgrading from Version 3.1 to Version 4.1 of CoolSpools. If you are currently running V2.1, please also read the section “Upgrade Notes for V2.1 Users”. To determine which version of CoolSpools you are running, check the name of the library in which the CVTSPLSTMF command object you are using resides, e.g.: DSPOBJD OBJ(CVTSPLSTMF) OBJTYPE(*CMD) The library name corresponds to the version of CoolSpools as shown in the table below:

Library Name Version

CVTSPLSTMF Version 2.1

CVTSPLV3R1 Version 3.1

CVTSPLV4R1 Version 4.1

Page: 13

License Keys

Version V4.1 of CoolSpools is available free of charge to customers who have paid their initial purchase invoice and who are either in their first year since purchase (and therefore in their free maintenance period) or who have paid their latest annual maintenance invoice.

However, in order to run V4.1 you will need a new license key. Simply e-mail sales@ariadnesoftware.co.uk requesting a key for V4.1 of CoolSpools and, so long as your maintenance payments are up to date or not yet due, we will send you a key. Please quote your system serial number(s) and processor group code(s) in your e-mail.

Without a license key, CoolSpools V4.1 will allow you 30-days grace period usage and will then no longer run.

If you have not paid your annual maintenance invoice, and if you need longer than 30-days to test V4.1, we will, on request, send you a temporary license key to extend the trial period.

If you require additional temporary license keys to assist with testing CoolSpools V4.1, or if you run into any problems during your testing, please do not hesitate to contact us at support@ariadnesoftware.co.uk.

Re-testing your applications

We recommend strongly that all production applications are re-tested thoroughly using the new version in your development environment before you switch over to running the new version in your production environment.

CoolSpools V2.1, V3.1 and V4.1 are packages as separate licensed programs and install into different libraries. This means that all three versions of CoolSpools can coexist and run alongside one another on the same machine. You can switch an application from using the one version to using another simply by changing the library list of the job to include the appropriate version library. Hence it is quite a simple matter to test your applications using the new version while continuing to run the older version in production.

Minimum OS/400 Release Level

The minimum OS/400 release level required to run V4.1 of CoolSpools is OS/400 V4R5M0.

If you are running V4R4M0 or an earlier version of OS400, you will not be able to install V4.1 of CoolSpools.

Product Library

The product library for CoolSpools V4.1 is now CVTSPLV4R1. Under V2.1, the library was called CVTSPLSTMF. Under V3.1, the library was CVTSPLV3.1. You

Page: 14

may need to change library lists in job descriptions etc. in order to pick up the new version of the code rather than the old.

This change of library name has the advantage that it allows you to run both V4.1 and the earlier versions on the same machine. You are therefore able to test V4.1 before swapping your production applications over to the new version, as we strongly advise you to do.

Licensed Program Id

The licensed program id for CoolSpools V4R1 is now 4CVTSPL. Under V2.1 it was 2CVTSPL. Under V3.1 it was 3CVTSPL.

Changes between V3.1 to V4.1

• TODIR parameter Under V3.1, a second element of the TODIR parameter allowed you to specify the directory in which work files were created when generating a PDF file. This element is now obsolete as V4.1 creates all work files in the /tmp directory of the IFS root file system and this feature has therefore been removed in V4.1.

• PMTADLPARM parameter The Prompt Additional Parameters parameter now controls the displaying of many less frequently used options which are also dependent on the value of the TOFMT parameter.

Upgrade Notes for V2.1 Users If you are currently running CoolSpools Version 2.1 in production, you must read the notes below before replacing CoolSpools V2.1 with V4.1. If you are upgrading from V2.1 to V3.1 rather than V4.1, please read the equivalent instructions in the Version 3.1 manual.

Both V4.1 and V3.1 are both significantly better releases than V2.1 in many respects, and fix a number of problems in the earlier release. However, having fixed these problems, we do not and cannot guarantee that the results you obtain with V4.1 or V3.1 with be the same as those with V2.1, with the same parameters. You may therefore need to modify your parameters to obtain the same results.

These comments apply in particular if you are using any of these features:

• Bookmarks • Spooled file splitting • Exit program parameters • Additional page or overlay margins • Page size changes

Page: 15

Changes between V2.1 and V3.1

There were a number of changes made in V3.1 of which you should take account before you can switch over to running either V3.1 or V4.1.

Bookmarks, Split keys and Exit Program Parameters

We have put a lot of effort into improving the accuracy of CoolSpools text selection features, by which we mean the identification of text strings in the spooled file (e.g. for SPLIT(*KEY) processing) and extraction of text strings from the spooled file (e.g. for bookmark purposes or as exit program parameters). These features worked very well in V2.1 in relation to traditional row-and-column based spooled files, but perhaps not quite so well when dealing with complex AFP spooled files, especially those using proportional fonts.

With a proportional font, the positioning of a piece of text on the page is dependent not only on the font itself but also on the text content. For example, the string “WWWWWWWWWW” takes up much more space on the page than the string “iiiiiiiiii”, even though each string contains 10 characters in the same font. Previously CoolSpools did not take account of the text content and estimated the position of text on the page based on the number of characters and the average width of a character in the font being used. In V3.1, CoolSpools now handles proportional fonts much better, and the accuracy with which text string identification and extraction works is much improved.

However, this does have implications for existing applications. If you have production applications which use text functions (bookmarks, splitting or exit program parameters), it is possible that the results you obtain with V3.1 will not be identical to those you obtained previously with V2.1. Although we believe that V3.1 will deliver more accurate results, it may be that you are already running CoolSpools live with parameters which produce the results you desire, arrived at maybe by trial and error. Running V3.1 with the same parameters may not give the same results, which could have undesirable effects on live applications.

We strongly recommend therefore that any applications using text string features (bookmarks, splitting or exit program parameters) are re-tested and, if necessary, the parameters readjusted, before you go live with V3.1.

EXITPGMPOS and EXITPGMKEY parameters

The EXITPGMPOS and EXITPGMKEY parameters now allow multiple exit program parameters to be defined so that more than one string extracted from the spooled file can be passed as parameters to an exit program.

If you have applications which run CVTSPLSTMF and specify an EXITPGMPOS or EXITPGMKEY parameter, please note that it is likely these will need to be modified to take account of this change before V3.1 or V4.1 will run properly. Specifically, an extra set of parentheses is necessary around the elements of the parameter.

For example, if you currently have something like:

Page: 16

CVTSPLSTMF...EXITPGMPOS(1 2 3 4 *INCH)

this needs to be changed to:

CVTSPLSTMF... EXITPGMPOS((1 2 3 4 *INCH))

otherwise your application will report and error when running V3.1 or V4.1 of CVTSPLSTMF.

Our apologies for any inconvenience but we thought the added functionality justified this slight inconvenience.

PAGESIZE parameter

Please note that the operation of the PAGESIZE parameter was changed slightly between V2 and V3 in response to a number of improvements we made in the way CoolSpools handles rotated pages, overlays, images and text.

The third element of this parameter previously allowed you to control whether text rotation was implemented in PDF or not. Text rotation in the spooled file is now always reflected in PDF output. The third element of the PAGESIZE parameter now controls whether or not rotated pages are viewed in rotated mode, or displayed without rotation for easier viewing.

The fourth element of this parameter previously controlled whether CoolSpools took any account of page rotation. CoolSpools now always implements page rotation where it exists. Now this parameter element allows you to instruct CoolSpools to operate as if the spooled file were being directed to a printer which caused an automatic page rotation to occur.

MARGINS parameter

We have added a new element to the MARGINS parameter which allows you to instruct CoolSpools to shift text outside of an overlay by a distance on the page that you specify. This is necessary because some printers automatically shift text which would otherwise encroach on their non-print borders. This often happens when page rotation is in effect. The result of this automatic shifting is that text is printed in the page perhaps ¼ inch below where it would be expected to print from the content of the spooled file alone. Since CoolSpools cannot anticipate whether this kind of shift occurs on your particular printer or not, you will need to instruct it to apply the shift using this new parameter element, in order to achieve proper alignment of text on the page.

Previously you may have handled this kind of text misalignment by applying an additional overlay margin. You may obtain better results now using the text shift option.

What’s new in this release? Version 4.1 of CoolSpools adds many major new features.

Page: 17

Highlights include:

• Improved performance Large parts of CoolSpools have been rewritten to try to improve performance and reduce the time taken to convert your spooled file. Trials suggest that the time taken to convert many spooled files will be cut by 50% or more using Version 4.1 compared with previous versions.

• Email options CoolSpools integrates with @riadne’s new Communique email product to allow output to be emailed as an attachment to one or more email recipients. You can now convert your spooled file and email it as an attachment all by running a single command.

• Improved font functions Font information from iSeries font resource objects can now be embedded in PDF to ensure that text in your PDF reproduces the appearance of text in the original printed document as accurately as possible.

• Improved national language support Non-Latin SBCS scripts such as Greek and Cyrillic as well as DBCS scripts such as Japanese and Chinese are now supported. New options allow improved control over CCSID selection and translation.

• Additional barcode support Virtually all commonly used iSeries barcode formats now supported. The barcode types which are not yet supported are: EAN2, EAN5, AP4SCC, DUTCHKIX and JPBC

• Improved HTML output The new TOFMT(*HTMLCSS) option generates HTML which includes Cascading Style Sheet features and significantly improves the presentation quality of HTML output, especially in relation to spooled files containing AFP features such as different font faces and sizes. However, you will need to use a browser which supports CSS.

Page: 18

Installation If you downloaded CoolSpools from the Internet, or received the product via e-mail, you will have received a zip file called cvtsplV4R1.zip. This zip files contain everything you need to get started with CoolSpools. This section describes two possible procedures for installing CoolSpools on your AS/400. We are hoping to simplify and automate this area in the near future. However, for the moment, please select one of the two methods described below and follow the steps carefully and in the order indicated. Steps to be carried out on the PC are shown in green, steps to be carried out on the AS/400 in blue.

Method 1: Installing CoolSpools using FTP This method uses FTP (File Transfer Protocol) to transfer the CoolSpools product files from your PC to your AS/400. It is assumed that you have stored the cvtsplV4R1.zip file which you downloaded from the Internet or received via e-mail on your PC and that you have enabled an FTP link between your PC and your AS/400. Step 1 On your PC, create an install directory for CoolSpools, either within Windows Explorer, or from the DOS prompt, e.g.:

md c:\cvtspl Save or copy the zip file that you downloaded or received into this directory. Step 2 On your PC, unzip the contents of the zip file into the directory you just created using pkunzip, WinZip, Norton UnZip etc. Step 3 On your AS/400, decide which library you wish to use for the install procedure and create a save file in that library, e.g.

crtsavf lib_name/cvtspl where lib_name is the name of the library you chose to use. Step 4 On your PC, start an FTP session to your AS/400. You may use FTP packages such as CuteFTP or simply go to the DOS prompt and type:

ftp AS400_name where AS400_name is the name of your AS/400. You will be prompted to enter your user id and password. Please ensure that you sign on with a user id that has adequate authority. We recommend that you sign on as the Security Officer QSECOFR. Issue the following FTP commands within the FTP session:

binary This command instructs FTP not to carry out any conversion on the data to be sent to the AS/400.

Page: 19

cd lib_name where lib_name is the name of the library in which you created the save file in Step 3. This command makes lib_name your current library on the AS/400.

lcd dir_name where dir_name is the name of the directory on your PC in which you unzipped the install files earlier. This command makes dir_name your current directory on the PC.

put cvtsplV4R1.sav cvtspl This command transmits the contents of the file cvtsplV4R1.sav, which was earlier unzipped from cvtsplV4R1.zip, and stores them in the save file called cvtspl which you created earlier on your AS/400. Step 5 On your AS/400, ensure that the previous step worked by displaying the contents of save file cvtspl:

dspsavf lib_name/cvtspl If you see the message (No records in save file) then something has gone wrong during the preceding steps. Try following them again. If you still cannot get this procedure to work, contact us at support@ariadnesoftware.co.uk. Step 6 On your AS/400, issue the following command to restore the CoolSpools licensed program to your system:

rstlicpgm licpgm(4CVTSPL) dev(*savf) option(*base) rstobj(*all) lng(*primary) output(*none) rls(*first) replacerls(*only)

savf(lib_name/cvtspl) where lib_name is the name of the library in which you created the save file in Step 3. Step 7 If you have downloaded CoolSpools from the Internet, you can use the product without a license key for up to 30 days. At the end of that period CoolSpools will notify you that it can no longer be used without a license key. To obtain a license key contact @riadne at sales@ariadnesoftware.co.uk. If you have been issued with a license key, proceed as follows. On your AS/400, issue the following command to add a license key to enable you to use the CoolSpools licensed program:

Page: 20

addlickey lickeyinp(*prompt) prdid(4CVTSPL) licterm(V4R1) feature(5001) serial(*local) prcgrp(Ppp) lickey(XXXXXX YYYYYY ZZZZZZ) usglmt(*nomax) expdate(exp_date)

vnddta(*none) where: XXXXXX YYYYYY ZZZZZZ is the license key you received by e-mail

from us exp_date is the expiry date mentioned in the e-mail and: Ppp is the processor group mentioned in the e-mail CoolSpools is now ready for you to use! If you have any trouble at any point in this procedure, please contact us by e-mail at support@ariadnesoftware.co.uk.

Method 2: Installing CoolSpools using the IFS This method uses a Client Access network drive assigned to the IFS of your AS/400 to transfer the CoolSpools product files from your PC to your AS/400. It is assumed that you have stored the cvtsplV4R1.zip file (which your downloaded from the Internet or received via e-mail) on your PC. Step 1 On your PC, create an install directory for CoolSpools, either within Windows Explorer, or from the DOS prompt, e.g.:

md c:\PC_dir where PC_dir is the name of the directory you wish to use for this installation. Save or move the zip file that you downloaded or received into this directory. Step 2 On your PC, unzip the contents of the zip file into the directory you just created using pkunzip, WinZip, Norton UnZip etc. Step 3 On your PC, ensure that you have a network drive assigned to a directory in the root file system of your AS/400’s IFS. This can be done in Windows Explorer by selecting Tools, Map Network Drive. Create a directory in the IFS to receive the CoolSpools files. This can be done in Windows Explorer by selecting File, New, Folder, or at the DOS prompt as follows:

md i:\IFS_dir where I: is the network drive assigned to your AS/400 and IFS_dir is the name of the directory you wish to use for this installation.

Page: 21

Step 4 Copy the contents of your PC’s install directory created in Step 1 above to the IFS directory created in Step 3 above using Windows Explorer, or from the DOS prompt as follows:

copy c:\PC_dir\*.* I:\IFS_dir where PC_dir is the name of the directory on your PC, I: is the network drive assigned to your AS/400 and IFS_dir is the name of the directory you wish to use for this installation. Step 5 On your AS/400, decide which library you wish to use for the install procedure and create a save file in that library, e.g.

crtsavf lib_name/cvtspl where lib_name is the name of the library you chose to use. Step 6 On your AS/400, copy the contents of the cvtsplV4R1.sav file from the IFS directory to the save file just created, by issuing the following command:

cpyfrmstmf fromstmf(‘/IFS_dir/cvtsplV4R1.sav’) tombr(‘/qsys.lib/lib_name.lib/cvtspl.file’) mbropt(*replace) cvtdta(*none) endlinfmt(*fixed) tabexpn(*no)

where IFS_dir is the name of the IFS directory into which you copied the install files in Step 4 above, and lib_name is the name of the library in which you created the save file in Step 5 above. Step 7 On your AS/400, ensure that the previous step worked by displaying the contents of save file cvtspl:

dspsavf lib_name/cvtspl where lib_name is the name of the library in which you created the save file in Step 5. If you see the message (No records in save file) then something has gone wrong during the preceding steps. Try following them again. If you still cannot get this procedure to work, contact us at support@ariadnesoftware.co.uk. Step 8 On your AS/400, issue the following command to restore the CoolSpools licensed program to your system:

rstlicpgm licpgm(4CVTSPL) dev(*savf) option(*base) rstobj(*all)

Page: 22

lng(*primary) output(*none) rls(*first) replacerls(*only)

savf(lib_name/cvtspl) where lib_name is the name of the library in which you created the save file in Step 5. Step 9 If you have downloaded CoolSpools from the Internet, you can use the product without a license key for up to 30 days. At the end of that period CoolSpools will notify you that it can no longer be used without a license key. To obtain a license key contact @riadne at sales@ariadnesoftware.co.uk. If you have been issued with a license key, proceed as follows. On your AS/400, issue the following command to add a license key to enable you to use the CoolSpools licensed program: addlickey lickeyinp(*prompt)

prdid(4CVTSPL) licterm(V4R1) feature(5001) serial(*local) prcgrp(Ppp) lickey(XXXXXX YYYYYY ZZZZZZ) usglmt(*nomax) expdate(exp_date)

vnddta(*none) where: XXXXXX YYYYYY ZZZZZZ is the license key you received by e-mail

from us exp_date is the expiry date mentioned in the e-mail and: Ppp is the processor group mentioned in the e-mail CoolSpools is now ready for you to use! If you have any trouble at any point in this procedure, please contact us by e-mail at support@ariadnesoftware.co.uk.

Page: 23

Maintenance Periodically we will release Program Temporary Fixes (PTFs) in order to add new features or to resolve any problems found with CoolSpools. PTFs are supplied in the form of an AS/400 save file stored within a zip file, and can be downloaded from the Bug Fixes section of the @riadne web site at http://www.ariadnesoftware.co.uk. The procedure for loading and applying a PTF for CoolSpools is as follows. First download the PTF you require from the Internet. The PTF will be held in a file called Q4CVnnnn.zip, where nnnn is the PTF id. This section describes two possible procedures for copying the AS/400 save file held in this zip file to your AS/400. We are hoping to simplify and automate this area in the near future. However, for the moment, please select one of the two methods described below and follow the steps carefully and in the order indicated. Steps to be carried out on the PC are shown in green, steps to be carried out on the AS/400 in blue.

Method 1: Installing a PTF using FTP This method uses FTP (File Transfer Protocol) to transfer the PTF file from your PC to your AS/400. It is assumed that you have stored the zip file which your downloaded from the Internet on your PC and that you have enabled an FTP link between your PC and your AS/400. Step 1 On your PC, create a directory for the PTF installation, either within Windows Explorer, or from the DOS prompt, or re-use the directory you used to install originally, e.g.:

md c:\cvtspl Save or copy the zip file that you downloaded or received into this directory. Step 2 On your PC, unzip the contents of the zip file into the directory you just created using pkunzip, WinZip, Norton UnZip etc. Step 3 On your AS/400, first sign off then sign back on again to ensure that you do to have any CoolSpools objects in your QTEMP library. Then decide which library you wish to use for the PTF install procedure and create a save file in that library. The name of this save file should be Q4CVnnnn, where nnnn is the PTF id, e.g.

crtsavf lib_name/Q4CV0001 where lib_name is the name of the library you chose to use. Step 4 On your PC, start an FTP session to your AS/400. You may use FTP packages such as CuteFTP or simply go to the DOS prompt and type:

Page: 24

ftp AS400_name where AS400_name is the name of your AS/400. You will be prompted to enter your user id and password. Please ensure that you sign on with a user id that has adequate authority. We recommend that you sign on as the Security Officer QSECOFR. Issue the following FTP commands within the FTP session:

binary This command instructs FTP not to carry out any conversion on the data to be sent to the AS/400.

cd lib_name where lib_name is the name of the library in which you created the save file in Step 3. This command makes lib_name your current library on the AS/400.

lcd dir_name where dir_name is the name of the directory on your PC in which you unzipped the install files earlier. This command makes dir_name your current directory on the PC.

put Q4CVnnnn.sav Q4CVnnnn This command transmits the contents of the file Q4CV0001.sav, which was earlier unzipped from Q4CV0001.zip, and stores them in the save file called Q4CVnnnn which you created earlier on your AS/400. Step 5 On your AS/400, ensure that the previous step worked by displaying the contents of save file Q4CVnnnn:

dspsavf lib_name/Q4CVnnnn If you see the message (No records in save file) then something has gone wrong during the preceding steps. Try following them again. If you still cannot get this procedure to work, contact us at support@ariadnesoftware.co.uk. Step 6 On your AS/400, issue the following command to load the PTF on to your system:

lodptf licpgm(4CVTSPL) dev(*savf) select(4CVnnnn)

savf(lib_name/Q4CVnnnn) where lib_name is the name of the library in which you created the save file in Step 3 and nnnn is the PTF id. Step 7 On your AS/400, issue the following command to apply the PTF to your system:

apyptf licpgm(4CVTSPL) select(4CVnnnn)

apy(*temp)

Page: 25

where: nnnn is the PTF If you have any trouble at any point in this procedure, please contact us by e-mail at support@ariadnesoftware.co.uk.

Method 2: Installing a PTF using the IFS This method uses a Client Access network drive assigned to the IFS of your AS/400 to transfer the PTF from your PC to your AS/400. It is assumed that you have stored the PTF zip file (which your downloaded from the Internet or received via e-mail) on your PC. Step 1 On your PC, create an install directory for the PTF, either within Windows Explorer, or from the DOS prompt, or use the directory you created for the original installation, e.g.:

md c:\PC_dir where PC_dir is the name of the directory you wish to use for this installation. Save or move the zip file that you downloaded or received into this directory. Step 2 On your PC, unzip the contents of the zip file into the directory you just created using pkunzip, WinZip, Norton UnZip etc. Step 3 On your PC, ensure that you have a network drive assigned to a directory in the root file system of your AS/400’s IFS. This can be done in Windows Explorer by selecting Tools, Map Network Drive. Create a directory in the IFS to receive the PTF. This can be done in Windows Explorer by selecting File, New, Folder, or at the DOS prompt as follows:

md i:\IFS_dir where I: is the network drive assigned to your AS/400 and IFS_dir is the name of the directory you wish to use for this installation. Step 4 Copy the contents of your PC’s PTF directory created in Step 1 above to the IFS directory created in Step 3 above using Windows Explorer, or from the DOS prompt as follows:

copy c:\PC_dir\*.* I:\IFS_dir where PC_dir is the name of the directory on your PC, I: is the network drive assigned to your AS/400 and IFS_dir is the name of the directory you wish to use for this installation. Step 5 On your AS/400, first sign off then sign back on again to ensure that you do to have any CoolSpools objects in your QTEMP library. Then decide which library you wish to use for the install procedure and create a save file in that library. The save file should be called Q4CVnnnn, where nnnn is the PTF id, e.g.

Page: 26

crtsavf lib_name/Q4CVnnnn where lib_name is the name of the library you chose to use and nnnn is the PTF id. Step 6 On your AS/400, copy the contents of the Q4CVnnnn.sav file (where nnnn is the PTF id) from the IFS directory to the save file just created, by issuing the following command:

cpyfrmstmf fromstmf(‘/IFS_dir/Q4CVnnnn.sav’) tombr(‘/qsys.lib/lib_name.lib/Q4CVnnnn.file’) mbropt(*replace) cvtdta(*none) endlinfmt(*fixed) tabexpn(*no) where IFS_dir is the name of the IFS directory into which you copied the PTF files in Step 4 above, and lib_name is the name of the library in which you created the save file in Step 5 above. Step 7 On your AS/400, ensure that the previous step worked by displaying the contents of save file Q4CVnnnn:

dspsavf lib_name/Q4CVnnnn If you see the message (No records in save file) then something has gone wrong during the preceding steps. Try following them again. If you still cannot get this procedure to work, contact us at support@ariadnesoftware.co.uk. Step 8 On your AS/400, issue the following command to load the PTF on to your system:

lodptf licpgm(4CVTSPL) dev(*savf) select(4CVnnnn)

savf(lib_name/Q4CVnnnn) where lib_name is the name of the library in which you created the save file in Step 3 and nnnn is the PTF id. Step 9 On your AS/400, issue the following command to apply the PTF to your system:

apyptf licpgm(4CVTSPL) select(4CVnnnn)

apy(*temp) where: nnnn is the PTF If you have any trouble at any point in this procedure, please contact us by e-mail at support@ariadnesoftware.co.uk.

Page: 27

Using CVTSPLSTMF Getting Started In order to convert your spooled files, you need to run the CVTSPLSTMF command. After you have installed CoolSpools, this command will exist in a library called CVTSPLV4R1. Before running the CVTSPLSTMF command ensure that this library is in your library list by issuing the following command:

ADDLIBLE CVTSPLV4R1 N.B. On some systems, the CVTSPLF library may restore with PUBLIC(*EXCLUDE) authority. You may need to grant, or ask your system administrator to grant, PUBLIC(*USE) authority to the CVTSPLSTMF library as follows: GRTOBJAUT CVTSPLV4R1 *LIB PUBLIC(*USE) before you can start to use CoolSpools. Also, if your spooled file contains references to any overlay, font resource or page segment objects, these must also be located through your library list. You should also add the library or libraries in which these objects are located to your library list before running CVTSPLSTMF, like this: ADDLIBLE library_name where library_name is the name of the library in which the object is located.

Page: 28

Command Parameters The sections below look at each of the parameters to the CVTSPLSTMF command in turn and explain how they should be used to get the most out of this invaluable utility. In the examples, an ellipsis (…) indicates that a number of required parameters have been omitted for the sake of clarity.

Page: 29

FROMFILE The FROMFILE (From File) parameter specifies the name of the spooled file that is to be converted to a stream file. Example: CVTSPLSTMF FROMFILE(QSYSPRT)… Here the CVTSPLSTMF command is being applied to a spooled file called QSYSPRT. The special value *SLT should only be used in the context of a CVTSPLSTMF command specified on the CMD parameter of the CoolTools WRKSPLFPDM command. It indicates that the spooled file to be processed is that currently selected by WRKSPLFPDM when it is running in batch mode to process a set of selected spooled files.

Page: 30

TOSTMF The TOSTMF (To Stream File) parameter specifies the name of the stream file you wish to create. You may specify the name of the stream file in either of two ways. The first option is to enter a full path name on this parameter, that is the complete directory path and the name of the file to be created or replaced. The second option is to enter just the name of the file itself. You will then need to specify the directory path in which that file will be saved on the TODIR (To Directory) parameter. The name you enter here may be up to 128 characters long. However, the name that you choose must be a valid name for the IFS file system into which the stream file is to be created. For example, the shared folders (QDLS) file system only supports file names in the 8.3 format, i.e. a file name up to 8 characters long followed by an optional extension of up to 3 characters. If you choose an invalid file name, an error will occur and the file will not be saved. You should choose a file name which is suitable for the type of file being created. For example, PDF files should be given the extension .pdf so that they are recognized as PDF files by applications such as Adobe ® Acrobat. HTML files are normally given as extension of .htm or .html. ASCII text files often have an extension such as .txt, .asc, .prn or .dat. Example: CVTSPLSTMF FROMFILE(QSYSPRT) TOSTMF(/invoices/sales.pdf)

TODIR(*TOSTMF)… Here the CVTSPLSTMF command is being applied to a spooled file called QSYSPRT in order to create a stream file called sales.pdf in the invoices directory. Example: CVTSPLSTMF FROMFILE(QSYSPRT) TOSTMF(sales.pdf)

TODIR(/invoices)… Here again the CVTSPLSTMF command is being applied to a spooled file called QSYSPRT in order to create a stream file called sales.pdf in the invoices directory.

Page: 31

JOB The JOB parameter specifies the name of the job that created the spooled file you wish to convert. You can use one of the following special values for this parameter: You can use the special value * to indicate that the job that created the spooled file was the current job, i.e. the job in which the CVTSPLSTMF command is running.

* (Default) The job that created the spooled file was the current job, i.e. the job in which the CVTSPLSTMF command is running.

*SBMJOB The job that created the spooled file was the job that submitted the job in which the CVTSPLSTMF command is running.

*SLT The special value *SLT should only be used in the context of a CVTSPLSTMF command specified on the CMD parameter of the CoolTools WRKSPLFPDM command. It indicates that the spooled file to be processed is that currently selected by WRKSPLFPDM when it is running in batch mode to process a set of selected spooled files.

Alternatively, you may specify a fully qualified job name, consisting of the:

Job name The name of the job User name The user profile under which the job ran Job number The system job number of the job

You can determine which job created a spooled file by using the WRKSPLF (Work with Spooled Files) command and pressing F11 twice to view the job details. Example: CVTSPLSTMF FROMFILE(QSYSPRT) TOSTMF(sales.pdf) TODIR(‘/sales/2001/april’) JOB(*) Here the CVTSPLSTMF command is being applied to a spooled file called QSYSPRT in order to create a stream file called sales.pdf in an IFS root directory called sales/2001/april. The spooled file was created by the current job. Example: CVTSPLSTMF FROMFILE(INVOICES) TOSTMF(invoices.pdf) TODIR(‘/invoices/2001/april’) JOB(123456/QSYSOPR/INVOICES) Here the CVTSPLSTMF command is being applied to a spooled file called INVOICES in order to create a stream file called invoices.pdf in an IFS root directory called invoices/2001/april. The spooled file was created by a job called INVOICES, run by the System Operator QSYSOPR, with job number 123456.

Page: 32

SPLNBR The SPLNBR (Spooled File Number) parameter specifies the number of the spooled file which you wish to convert. You can use one of the special values:

*ONLY The job created only one spooled file of the name specified on the FROMFILE parameter.

*LAST The spooled file to be converted is the latest spooled file of that name created by the job.

*SLT The special value *SLT should only be used in the context of a CVTSPLSTMF command specified on the CMD parameter of the CoolTools WRKSPLFPDM command. It indicates that the spooled file to be processed is that currently selected by WRKSPLFPDM when it is running in batch mode to process a set of selected spooled files.

Alternatively, specify the actual spooled file number of the spooled file that you wish to convert. You can determine the spooled file number by using the WRKSPLF (Work with Spooled Files) command to display the spooled file and pressing F11 twice to view spooled file number. Example: CVTSPLSTMF FROMFILE(INVOICES) TOSTMF(invoices.pdf) TODIR(‘/invoices/2001/april’) JOB(123456/QSYSOPR/INVOICES) SPLNBR(3) Here the CVTSPLSTMF command is being applied to a spooled file called INVOICES in order to create a stream file called invoices.pdf in an IFS root directory called invoices/2001/april. The spooled file was created by a job called INVOICES, run by the System Operator QSYSOPR, with job number 123456. The spooled file to be converted was the third spooled file open by the job.

Page: 33

TOFMT The TOFMT (To Format) parameter allows you to select the format to which the spooled file should be converted. The benefits and relative merits of the different formats are discussed in the Document Formats section of the Introduction to this User Guide. The options are

*TEXT (Default) Plain ASCII text. The textual content of the spooled file is converted to ASCII text records terminated by carriage return/line feed pairs.

*HTXT HTML Text Textual data in the spooled file is converted to HTML format, viewable in a browser. However, no attempt is made to represent variable fonts, highlighting or other text attributes. Use this format if you wish to view traditional, simple AS/400 reports in a browser, and column alignment and text positioning are more important to you than the precise appearance of the report text.

*HTML Simple HTML The contents and attributes of the spooled file are converted to HTML format, viewable in a browser. Text attributes such as variable font sizes and typefaces, highlighting and underlining are reflected in the stream file, but text positioning may vary from the original report. Use this format if you wish to view more sophisticated AS/400 reports in a browser, and column alignment and text positioning are less important to you than the style and attributes of the report text

*HTMLCSS HTML with Cascading Style Sheet features The contents and attributes of the spooled file are converted to HTML including Cascading Style Sheet (CSS) features, viewable in a browser that supports CSS. Text attributes such as variable font sizes and typefaces, highlighting and underlining are reflected in the stream file, and text positioning will reproduce the position of text in the original report as closely as HTML allows.

*PDF Portable Document Format (PDF) The contents and attributes of the spooled file are converted to PDF format. PDF files can be viewed and printed using the free Adobe Acrobat Reader program.

Page: 34

Every effort is made to ensure that the report will appear in the Acrobat Reader exactly the same as the original paper report.

*RTF Rich Text Format (RTF) The contents and attributes of the spooled file are converted to RTF format. RTF files can be viewed and printed using most commonly used Word Processing applications, such as MS Word, Lotus WordPro or MS WordPad.

*XLS Excel © (BIFF) format The textual content of the spooled file is converted to columns and rows in an Excel spreadsheet.

*CSV Delimited ASCII text The textual content of the spooled file is converted to delimited ASCII text records terminated by carriage return/line feed pairs. The delimiters used to separate fields and enclose strings are defined on the DELIMITERS parameters. This option enables you to create files in CSV (comma-separated variable) format and other similar formats for loading into spreadsheets and other PC applications.

*SAV Archive The spooled file is saved into a compressed archive format. The spooled file can later be restored using the CVTSTMSPLF (Convert Stream File to Spooled File) command.

Example: CVTSPLSTMF FROMFILE(INVOICES)… TOFMT(*PDF) Here the CVTSPLSTMF command is being applied to a spooled file called INVOICES in order to create a stream file in PDF format.

Page: 35

STMFOPT The STMFOPT (Stream File Option) parameter allows you to select the action CVTSPLSTMF should take if the stream file you have specified on the TOSTMF and TODIR parameters already exists. This parameter is ignored if the stream file does not already exist. The options are:

*NONE The command reports an error and the existing file is not changed. For safety’s sake, this is the default value.

*REPLACE The existing file is replaced. *ADD The contents of the spooled file are appended to

the end of the existing file. Please note that this option is only allowed in conjunction with TOFMT(*TEXT) or TOFMT(*CSV), as all other output file formats cannot be appended to without making the file unusable.

*UNIQUE CoolSpools generates a unique file name for the output file or files by appending a numeric suffix to the name specified on the TOSTMF parameter (before any extension). The numeric suffix will be one higher than the highest suffix associated with any existing file of this name in the directory.

Example: CVTSPLSTMF FROMFILE(INVOICES)…

TOFMT(*TEXT) STMFOPT(*ADD)

Here the CVTSPLSTMF command is being applied to a spooled file called INVOICES. The spooled file is being converted to ASCII text form and the contents of the spooled file will be appended to the end of the existing file. Example: CVTSPLSTMF FROMFILE(INVOICES)

TOSTMF(‘/invoices/invoice.pdf)… TOFMT(*PDF) STMFOPT(*UNIQUE)

Again, in this example the CVTSPLSTMF command is being applied to a spooled file called INVOICES. The spooled file is being converted to PDF. The STMFOPT(*UNIQUE) option has been selected and CoolSpools will create an output file in directory invoices named invoice?.pdf, where ? represents a numeric suffix (e.g. invoice1.pdf, invoice2.pdf, …). The suffix selected depends on which other files with names of this type already exist in directory invoices. CoolSpools will identify the highest currently existing suffix for a file called invoice?.pdf in directory invoices and will add 1 to it to get the next suffix to use.

Page: 36

EMAIL The EMAIL (Email the output) parameter enables you to specify that the stream file created by CoolSpools should be emailed as an attachment. Please note that this facility is only available if you have @riadne’s Communique email product installed and licensed or on trial. Options are:

*NO (The default). The output is not emailed automatically as part of running this command. You are still able to email the output separately, either by running a subsequent command or program or from a CoolSpools exit program.

*YES The output from this command will be emailed as an attachment according to the information you specify on the other email-related parameters.

Page: 37

PMTADLPARM The PMTADLPARM (Prompt Additional Parameters?) parameter has no effect on the way CVTSPLSTMF runs or the output it produces. Its sole purpose is to control the prompting of additional parameters which are dependent on the TOFMT parameter when the command is prompted using F4. The CVTSPLSTMF command provides a rich variety of options and features, some of which are infrequently used and many of which are relevant only to certain types of stream file format (as specified on the TOFMT parameter). This parameter enables the infrequently used parameters to be hidden unless the user asks to see them. Unlike the use of F10=Additional parameters, however, it also allows only those parameters which are relevant to the TOFMT option selected to be prompted. For example, the TITLE parameter is relevant only to PDF and HTML output. If this were controlled by F10=Additional parameters, it would be displayed whenever the user pressed F10 during command prompting irrespective of the value of the TOFMT parameter. If you specify PMTADLPARM(*YES) before pressing F4 or during command prompting, you will see additional, less frequently used parameters, but only those relevant to the value of the TOFMT parameters you have input. If you want to see all parameters, irrespective of the value of the TOFMT or any other parameter, press F9 during command prompting. Options are:

*NO (The default). Additional, less frequently used parameters that are dependent on the TOFMT parameter are not displayed during command prompting.

*YES Additional, less frequently used parameters that are dependent on the TOFMT parameter are displayed during command prompting.

Page: 38

EMAILOPT The EMAILOPT (Email options) parameter allows you to specify various options relating to the sending of the output from the command as an email attachment. It is only displayed during command prompting if EMAIL(*YES) was specified. These options apply only to the sending of the output using Communique and have no effect on the sending of the output using subsequent calls to SNDDST and other email facilities. The parameter consists of 6 elements: Delete after sending?, Subject, Attach or embed?, Priority, Confirm delivery and Send Multiple Messages? Delete after sending This option allows you to indicate whether the output from the command should be deleted as soon as it has been sent as an attachment. Use this option with caution: if the email fails to arrive for whatever reason, you may lose your data. Possible values are:

*NO (The default). The output is not deleted. *YES Once the email has been created, and the stream

file attached to it, the stream file is deleted. Please note that CoolSpools can only tell if the email has been successfully created. It cannot tell if the email was successfully sent or delivered to its recipient.

Subject This element allows you to define a subject line for the message. You can enter up to 50 characters of free-format text. When the email message is received, the text that you enter on this parameter element will appear in the subject line of the email. Attach or embed? This is where you specify the method by which the file is sent. Options are:

*ATTACH (Default) The file is sent as an attachment. It will appear as an attached file separate from the text of the email.

*EMBED The contents of the file are embedded in the text of the email and will follow the text of any message entered on the EMAILMSG parameter. Please note that your client email software is likely only to support the embedding of certain types of file, e.g. text and HTML.

Priority The priority option controls whether the email message is flagged as a high-priority or low-priority in your email client software. Values are:

*NORMAL (Default) The message is sent specifying normal priority. When the message arrives, the client

Page: 39

email software will not mark it as high or low priority.

*HIGH High priority. When the message arrives, the client email software will mark it as high priority.

*LOW Low priority. When the message arrives, the client email software will mark it as low priority.

Confirm Delivery This option controls whether confirmation of delivery is requested from the receiver of the email. Values are:

*NO (Default) No confirmation of delivery if requested. *YES The message is sent with an indication that you

have requested that the recipient return confirmation of delivery. When the message is opened, if you have not switched off this feature, the client software will either send a confirmation message back to the sender of the email or ask you whether you wish to send such a confirmation.

Send Multiple Messages This option controls whether a single message is sent to all recipient at once or multiple separate messages to each recipient in turn. Options are:

*NO (Default) If you are sending an email to more than one recipient, a single message will be created with multiple recipients. When the message is received, the reader will be able to see the names of all people to whom the message was sent.

*YES If you are sending an email to more than one recipient, multiple separate messages will be sent, one to each recipient. When the message is received, the reader will see only their own name and will not be able to see the names of all people to whom the message was sent.

Page: 40

Page: 41

EMAILFROM The EMAILFROM (Email sender information) parameter allows you to specify the sender of the email and the email address to which a response should be sent. It is only displaying during command prompting if EMAIL(*YES) was specified. The default value is *CURRENT, which means that Communiqué will try to retrieve the email address of the user sending the email from the System Distribution Directory. If no email address is defined for the user in the System Distribution Directory, you will need to enter the values you wish to use manually. There are 2 elements to this parameter: Email address and Name. Email address This is where you enter the email address of the sender. Note that while Communiqué will check that the email address that you enter conforms to the rules for valid email addresses, it is not possible to validate that the email address that you enter is correct or that any reply sent to the message will be deliverable. For example, sales.ariadnesoftware.co.uk is not a valid email address (since it does not contain an @ sign), and Communiqué will reject it. However, sales@ariadnesoftware.org.uk is a valid email address and Communiqué will allow it, but it is not @riadne’s correct email address (it should be sales@ariadnesoftware.co.uk) and any reply sent to this email address will not be received. Name If you would like you email message to display a sender’s name rather than the sender email address when it is delivered, enter the name here. The default value is *NONE, i.e. no name is provided and the email address will appear as the sender instead. For example, if you specify: EMAILFROM((Sales@ariadnesoftware.co.uk *NONE)) when the message is received, the From: attribute will be shown as: From: Sales@ariadnesoftware.co.uk However, if you specify: EMAILFROM((Sales@ariadnesoftware.co.uk ‘@riadne Sales’)) when the message is received, the From: attribute will be shown as: From: @riadne Sales

Page: 42

EMAILTO The EMAILTO (Recipients) parameter allows you to specify the email addresses to which the email message should be sent. It is only displaying during command prompting if EMAIL(*YES) was specified. You can define up to 32 recipients for the message on this command parameter. If you need to send the same email address to more than 32 recipients simultaneously, you can do this by defining an address list and specifying the address list name on this parameter. There are 3 elements to this parameter: Email address, Name and Type. Email address This is where you enter the email address to which the message is to be sent. Note that while Communiqué will check that the email address that you enter conforms to the rules for valid email addresses, it is not possible to validate that the email address that you enter is correct or that the message will be deliverable. For example, sales.ariadnesoftware.co.uk is not a valid email address (since it does not contain an @ sign), and Communiqué will reject it. However, sales@ariadnesoftware.org.uk is a valid email address and Communiqué will allow it, but it is not @riadne’s correct email address (it should be sales@ariadnesoftware.co.uk) and the message will not be received. Name If you would like your email message to display the recipient’s name rather than the email address when it is delivered, enter the name here. The default value is *NONE, i.e. no name is provided and the email address will appear as the recipient instead. For example, if you specify: EMAILTO((Sales@ariadnesoftware.co.uk *NONE)) when the message is received, the To: attribute will be shown as: To: Sales@ariadnesoftware.co.uk However, if you specify: EMAILTO((Sales@ariadnesoftware.co.uk ‘@riadne Sales’)) when the message is received, the To: attribute will be shown as: To: @riadne Sales Type Specify the type of recipient here. Options are:

*PRI (Default) Primary recipient. *CC Carbon copy recipient. An *CC recipient receives a

copy of the message, and is identified to the primary recipient, but is not the primary recipient.

Page: 43

*BCC Blind carbon copy recipient. An *BCC recipient receives a copy of the message, but is not identified to the primary recipient or *CC recipients.

*ADRL Communique Address list. If you wish to send to an address list, this is the value that must be entered. Refer to the Communique manual for details of how to create, manage and use email address lists.

Example: Sending to @riadne Sales as a primary recipient with a copy to @riadne Marketing: CVTSPLSTMF EMAIL(*YES) EMAILTO( (Sales@ariadnesoftware.co.uk ‘Sales’ *PRI) (Marketing@ariadnesoftware.co.uk ‘Marketing’ *CC)) Example: Sending to an email address list called “Sales”: EMAILTO((Sales *ADRL *ADRL))

Page: 44

EMAILMSG The EMAILMSG (Message) parameter allows you to enter the text of an email message directly on the command line. It is only displaying during command prompting if EMAIL(*YES) was specified. Up to 512 characters of free-format text can be entered here. The message can be sent in either plain text, HTML or alternative plain text/HTML formats. There are 2 elements to this parameter: Message text and Message format. Message text You can enter the text of a short message to accompany the email and its attachment here. Up to 512 characters can be entered. When received, the message will be displayed exactly as it is entered, with the following exceptions:

• If you want to force a line break, enter <br>. Even if the message is sent in plain text format, this HTML control will be interpreted and converted to a hard line break (carriage return-line feed sequence).

• Other HTML controls may be entered, but will only be interpreted as HTML controls if the message is sent and delivered in HTML format.

Message format This is where you specify the format in which the message is sent. Options are:

*BOTH (Default) The message is sent in alternative plain text/HTML format. This means that two copies of the message text will be sent: a plain text copy and an HTML copy. If the email client software used to receive the message can handle HTML messages, the HTML copy will be used, otherwise the plain text copy will be used.

*TEXT The message is sent in plain text format. The only HTML control which is interpreted is <br>, which Communiqué will convert to a hard line break.

*HTML The message is sent in HTML format. You can include HTML formatting (e.g. <b> </b> or <u> </u> to control bold text and underlining). Communiqué will take the text that you enter and wrap it with some basic HTML header and footer controls (<HTML> <HEAD> <BODY>). These controls should not therefore be included in the text of the message.

Example: CVTSPLSTMF… EMAIL(*YES) EMAILMSG('Here''s a message <br>with<br>line <br>breaks.' *TEXT) When this message is received, it will show as:

Page: 45

Here's a message with line breaks.

Example: CVTSPLSTMF… EMAIL(*YES) EMAILMSG( 'Here''s a message with HTML controls.<br> <b>This line is in bold, </b><br> <u>While this line is underlined.</u>') When this message is received, it will show as: Here's a message with HTML controls. This line is in bold, While this line is underlined.

Page: 46

TITLE The TITLE parameter allows you to define a title for the report. This parameter is displayed during command prompting only if you specified PMTADLPARM(*YES) to prompt additional parameters and if one of the following options is specified for the TOFMT parameter: *PDF, *HTML, *HTXT, *HTMLCSS. If you specify TOFMT(*HTML), TOFMT(*HTMLCSS) or TOFMT(*HTXT), the text you key in the TITLE parameter will appear in your browser's title bar. If you specify TOFMT(*PDF), the text in the TITLE parameter appears in Adobe Acrobat Reader by selecting: File, Document Info & General from the Reader menu. Alternatively, you may select one of the special values:

*NONE (The default). The report has no title. *STMFILE The report title is the same as the stream file name

specified on the TOSTMF parameter. Example: CVTSPLSTMF FROMFILE(SALES)… TOFMT(*PDF)

TITLE(‘Sales Statistics April 2001’) The sales report is converted to PDF format. Users can check the Document Information panel in Adobe Acrobat to see the title ‘Sales Statistics April 2001’ to confirm the nature of the report.

Page: 47

PAGESIZE The PAGESIZE parameter allows you to specify the page size that should be used when displaying or printing a PDF file using Adobe Acrobat. This parameter is displayed during command prompting only if you specified PMTADLPARM(*YES) to prompt additional parameters and if one of the following options is specified for the TOFMT parameter: *PDF, *HTML, *HTXT, *HTMLCSS, *RTF, *TEXT. This parameter consists of four elements: the page size, the orientation, whether to present rotated pages unrotated, and whether to apply auto-rotation. Options for the page size are:

*SPLF (The default). CVTSPLSTMF will reproduce the dimensions of the original spooled file. These normally correspond to the page width and length specified on the CRTPRTF command when the printer file was created. In the case of an AFP or IPDS spooled file containing several different page sizes or orientations, these will all be reflected on the corresponding pages of the PDF or RTF document.

*CUSTOM You will specify the precise page size on the CUSTOMPAGE parameter discussed later. This option is useful if you want to use a paper size not provided as one of the standard options listed below.

*A4 297 x 210 mm. *A5 210 x 148 mm. *LEGAL 14 x 8.5 in. *LETTER 11 x 8.5 in. *EXEC 10.5 x 7.25 in.

The second element of this parameter controls the orientation of the page as reproduced in the stream file. Options are:

*SPLF (The default). The orientation is derived from the dimensions of the spooled file. If the width of the spooled file exceeds the lengths of the spooled file, the page will appear in landscape mode, otherwise it will be in portrait mode. This is the only value permitted if the page size element is *SPLF or *CUSTOM.

*LANDSCAPE Landscape mode. *PORTRAIT Portrait mode.

Please note that when specifying the orientation for a page which will be rotated, you should specify the orientation of the unrotated page. For example, if your report is printed in landscape mode on an A4 printer by means of page rotation, you should specify PAGESIZE(*A4 *PORTRAIT), not PAGESIZE(*A4 *LANDSCAPE). This is because, in reality, the spooled file orientation is portrait, but text is printed rotated through 90 degrees to give the effect of landscape printing. The third element controls whether rotated pages should be presented unrotated.

*YES (The default) If the page is rotated, or if auto-rotation is applied (see next element), the page will be

Page: 48

automatically rotated back into the standard orientation for easier viewing.

*NO The page, if rotated, is view in the rotated orientation.

The fourth element of this parameter dictates whether an automatic rotation, and/or Computer Output Reduction (COR) are applied, simulating the effects of the PAGRTT(*AUTO), PAGRTT(*COR) or PAGRTT(*DEVD) attribute on certain printers. If your spooled file has the attribute PAGRTT(*AUTO), PAGRTT(*COR) or PAGRTT(*DEVD), automatic page rotation will occur when the spooled file is printed on a printer and the spooled file does not fit on the page in its standard orientation. For example, if you have a spooled file which is in landscape mode, and you print it to a printer which prints in A4 portrait mode normally, the spooled file will be rotated automatically through 90 degrees and printed in landscape mode on the A4 portrait printer. In addition, if PAGRTT(*COR) is specified, or if the spooled file still does not fit on the page even after rotation, Computer Output Reduction (COR) may be applied, subject to the type and attributes of the spooled file fulfilling certain conditions. COR involves scaling the contents of the spooled file horizontally and vertically to fit on an 8.5 x 11 inch sheet of paper. By default, CoolSpools does not currently implement an automatic page rotation when a spooled file has PAGRTT(*AUTO), PAGRTT(*COR) or PAGRTT(*DEVD), as this may or may not be appropriate depending on the printer for which the spooled file was intended, which CoolSpools cannot know. However, if you are relying on a page rotation, it is possible that page segments and images contained in the spooled file will appear misplaced and rotated in the PDF files you create using the default CoolSpools parameters. In order to replicate the effects of an automatic page rotation in your spooled file, you need to specify *YES on the "Auto-rotation in effect?" element of this parameter. This will ensure that images and page segments are handled as if the page had rotated. If you are not sure if rotation and COR are appropriate, you can specify *SPLF, in which case CoolSpools will attempt to predict the behavior of the most modern printers, and will itself decide whether to rotate the page or apply COR. CoolSpools will assume that the paper size specified on the first two elements of this parameter indicate the paper size on which the document is normally printed, and will decide whether rotation and/or COR are required based on this paper size. It is likely that *SPLF will become the default in a future release. Please note that the paper size specified on the first two elements of this parameter is interpreted as the shape and format of the paper prior to rotation. For example, if you document prints on letter cur sheet paper (11 x 8.5 inches), you should specify PAGESIZE(*LETTER *PORTRAIT) even if the document prints in landscape mode, since the paper is physically printed in portrait mode and the document contents rotated to fit on it.

*NO (The default) Auto-rotation is not applied.

Page: 49

*YES Auto-rotation is applied But NOT COR. *SPLF CoolSpools will itself decide whether to apply auto-

rotation and/or COR. This is probably be the default in the next release.

*COR Auto-rotation and COR will both be applied. *PAGESIZE Auto-rotation is applied if the spooled file attributes

suggest a landscape orientation (i.e. if the calculated page width in millimetres is larger than the calculated page length in millimetres), but not if the attributes suggest a portrait orientation (width less than height).

Example: CVTSPLSTMF FROMFILE(SALES)… TOFMT(*PDF)

PAGESIZE(*A4 *PORTRAIT) The sales report is converted to PDF format. It will appear in Acrobat in A4 portrait format.

Page: 50

PASSWORD

The PASSWORD (PDF passwords) parameter only appears during command prompting if you specified PMTADLPARM(*YES) to prompt additional parameters and TOFMT(*PDF). This parameter allows you to password-protect your PDF files and/or restrict the operations that can be performed on them.

Password protecting a PDF file allows you to e-mail it safe in the knowledge that, if the e-mail goes astray or is intercepted, it will not be possible to open the PDF file without the necessary password. Similarly, sensitive business documents can be stored safely on your company server and will not be accessible by anyone who has not been given the passwords to open them.

Restricting access rights to a file allows you to control what operations can be performed on it (e.g. whether it can be modified or printed or text copied from it). This can either be done in conjunction with a password or without one.

PDF passwords are implemented using Adobe's standard encryption method. This highly secure encryption technique employs the RSA Data Security, Inc. MD5 Message-Digest algorithm (described in Internet RFC 1321, The MD5 Message-Digest Algorithm) and the public-domain ArcFour encryption algorithm.

PDF's standard encryption handler limits the encryption key to 5 bytes (40 bits) in length, in accordance with U.S. cryptographic export requirements.

A PDF file may be allocated a "owner" password and an "user" password.

The "owner" password gives full access to all features of the document, i.e. entering the "owner" password in Adobe Acrobat (as opposed to Acrobat Reader) will enable you to modify, copy, print and annotate the document.

The "user" password gives either full access or limited access to the document, depending on the user privileges that were granted when the file was created.

The privileges that can be granted are:

• whether the document may be printed • whether text in the document may be copied • whether the document can be modified • whether notes can be added to the document

It is also possible to restrict any or all of the above functions without requiring a password to be entered. When that is done, no one can perform any of the above functions on the file, even the owner.

PLEASE NOTE THAT PASSWORDS ARE CASE-SENSITIVE.

If you forget your password, you will not be able to open your document.

Page: 51

The supplier of this software takes no responsibility for documents that cannot be opened as a result of a lost of forgotten password and has no means to recover documents that have become unusable as a result.

There are 7 elements to this parameter.

The first element indicates whether you wish to password protect the document.

Options are: *NO The PDF file will not be password protected (default) *YES At least a user password is needed to open the file *EXITPGM A pre-file creation exit program will be used to supply the

password(s). *RESTRICT Do not require a password to open the file, but prevent

one or more operations from being applied to the file (printing, modification, annotation or copying of text).

The second element is the user password. If *YES is specified for the previous element, a user password must be entered (cannot be left blank). If *RESTRICT is specified for the previous element, a user password may not be entered (as *RESTRICT indicates that the file should have restricted access rights without a password).

The password can be any string of characters and numbers. The minimum length is 1 character and the maximum is 32.

The third element is the owner password. If no owner password is entered (i.e. it is left blank), the document will not have an owner password. This means that it will not be possible for anyone to perform any actions not permitted according to the user rights defined in the following parameters.

If *RESTRICT is specified for the first element, an owner password may not be entered (as *RESTRICT indicates that the file should have restricted access rights without a password).

The owner password can be any string of characters and numbers. The minimum length is 1 character and the maximum is 32.

Please note that if *EXITPGM is specified on the first element of this parameter, any value typed for the user or owner password in the second and third elements of this parameter are only used if the exit program returns blanks for the corresponding password.

The remaining four elements to this parameter control the rights granted when the document is opened by entering the "user" password.

These are:

• Allow printing?

Page: 52

• Allow modifications? • Allow copying of text? • Allow annotation?

All of these parameters take the following form:

*YES The action is permitted (default) *NO The action is not permitted

If *RESTRICT is specified for the first parameter element, at least one of the above four elements must be specified as *YES.

Page: 53

BOOKMARK

The BOOKMARK parameter only appears during command prompting if you specified PMTADLPARM(*YES) to prompt additional parameters and TOFMT(*PDF) is selected. This parameter allows you to define whether PDF bookmarks (outlines) will be created, and, if so, on what basis. Bookmarks index a PDF file so readers can go directly to a particular section of a document. By creating bookmarks, you make it quicker and easier for users to navigate the document that CVTSPLSTMF generates. The possible values are:

*PAGNBR CVTSPLSTMF creates bookmarks based on the

page numbers in the document. This is the default. *NONE No bookmarks are created. *POS CVSTPLSTMF creates bookmarks based on a piece

of text that appears at a particular position on each page of the report.

*KEY CVTSPLSTMF creates bookmarks based on a text associated with a key word or phrase found in the report.

Example: CVTSPLSTMF FROMFILE(SALES)…

TOFMT(*PDF) BOOKMARK(*PAGNBR)

The sales report is converted to PDF format and bookmarks are generated for each page of the report, labeled ‘Page 1’, ‘Page 2’ etc.

Page: 54

SPLIT The SPLIT (Split Spooled File) parameter allows you to request that CVTSPLSTMF create several stream files from a single spooled file, splitting the spooled file based on criteria that you specify on the SPLITPAGE, SPLITPOS and SPLITKEY parameters. It only appears during command prompting if you specified PMTADLPARM(*YES) to prompt additional parameters and a value other than *SAV or *TIFF is input for the TOFMT parameter. 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. You can ask CVTSPLSTMF to split the spooled file every so many pages, or when a specified key string appears in the spooled file. CVTSPLSTMF generates names for the stream files it creates by appending a sequential number to the part of the stream file name specified on the TOSTMF parameter preceding any file extension. For example, if you specify: TOSTMF(spool.pdf)… SPLIT(*PAGNBR) or … SPLIT(*KEY) or … SPLIT(*POS) CVTSPLSTMF will create stream files called spool1.pdf, spool2.pdf, spool3.pdf etc. If you wish to give each stream file a name more appropriate to its contents (e.g. naming it after the customer to whom it relates), this can be achieved by means of an exit program. The customer number or name should be extracted from the spooled file and passed to the exit program as a parameter. The exit program should then rename the stream file as required. See Appendix A for an example. There are three elements to this parameter. The first element indicates the method you wish to use for identifying split points in your spooled files. Options are:

*NONE Do not split the spooled file. A single stream file is created.

*PAGE Split the spooled file into separate stream files every so many pages. This option is useful if, for example, you want to create separate stream files for each customer in the report, and the report starts each customer on a new page.

*KEY Split the spooled file into separate stream files every time a given key string appears in the spooled file. This option can be useful if, for example, you wish to split the report every time a piece of text (e.g. a field label such as ‘Customer number:’) appears in the report.

Alternatively, this method can also be used to

identify split points by checking the value of the text at a particular area of the spooled file, where the text is located by means of its offset position from a specified key string. For example, if the customer number in your spooled file is preceded by the string ‘Customer number’, you can use ‘Customer number’ as the key string to locate the customer number on

Page: 55

the page, then use changes to the customer number as the trigger for the creation of a new PDF file.

*POS Split the spooled file into separate stream files based

on checking the value of the text in the spooled file at a specified position on the page. The position is identified by means of coordinates down the page from top to bottom or line numbers and coordinates across the age from left to right or columns numbers.

The second element of the SPLIT parameter indicates whether splitting should occur before the split point or after it. Options are:

*BEFORE The spooled file is split before the split point. The page on which the split point occurs will become the first page of the new PDF file. This is the default value.

*AFTER The spooled file is split after the split point. The page on which the split point occurs will be the last page prior to the start of a new PDF file.

Note that each stream file must consist of at least one complete page. CVTSPLSTMF cannot split a single page between stream files. The third element of the SPLIT parameter determines the separator character, if any, that is inserted between the file name you specify on the TOSTMF parameter (minus the extension) and the numeric suffix which CVTSPLSTMF appends to that name (minus the extension) to create a file name for each stream file generated. Options are:

*NONE (The default). No separator is used. *UNDERSCORE An underscore character (_). Any other character Any other character allowed in a file name.

Example: CVTSPLSTMF FROMFILE(INVOICES)

TOSTMF(invoice.pdf)… TOFMT(*PDF)

SPLIT(*PAGE *BEFORE *NONE) SPLITPAGE(1)

Here CVTSPLSTMF will create stream files called invoice1.pdf, invoice2.pdf, invoice3.pdf etc. since you have specified *NONE for the separator character. However, if you specify: CVTSPLSTMF FROMFILE(INVOICES)

TOSTMF(invoice.pdf)… TOFMT(*PDF)

SPLIT(*PAGE *BEFORE *UNDERSCORE) SPLITPAGE(1)

CVTSPLSTMF will create stream files called invoice_1.pdf, invoice_2.pdf, invoice_3.pdf etc. as you have requested that an underscore be used for the separator character.

Page: 56

EXITPGM The EXITPGM (Exit Programs) parameter only appears during command prompting if you specified PMTADLPARM(*YES) to prompt additional parameters and a value other than *SAV or *TIFF is input for the TOFMT parameter. It allows you to specify the fully qualified names of one or more user-written exit programs which CVTSPLSTMF will call at one of the four specified exit points within the CoolSpools processing cycle. These exit points are:

• After creating each stream file generated by CVTSPLSTMF. Where splitting options have been used, and multiple stream files are being created, this program will be called immediately after each stream file has been completed.

• After processing each page of the report. This program will be called once for each page in the spooled file, except for pages excluded using the EXCLPAGES parameter.

• After processing the entire spooled file. This program is called once only, at the end of processing.

• Before CoolSpools start to create each stream file. This exit point gives you an opportunity to override the passwords specified on the PASSWORD parameter and provide separate passwords for each stream file.

The default is the single value *NO, which indicates that no exit programs are to be called. For each of the 4 exit points, specify the program name and the library in which the program is located or *NONE if no program is required to be called at that exit point. The following special values may be specified for the library name:

*LIBL The program is located using the library list of the job.

*CURLIB The program is located in the current library. As well as specifying the name of the exit program to be called and the library in which it is located, you must also tell CoolSpools what type of parameters to pass to it. There are currently two forms in which parameters may be passed, known as Type 1 (*TYPE1) and Type 2 (*TYPE2). Type 1 parameter list A type 1 parameter list consists of the following:

1 Spooled file name Input Char(10)

2 Name of the job that created the spooled file Input Char(10)

3 User id that created the spooled file Input Char(10)

4 Number of the job that created the spooled file Input Char(6)

5 Spooled file number Input Binary(4)

6 Spooled file user data Input Char(10)

Page: 57

7 Name of the stream file just created Input Char(128)

8 Directory name in which stream file was created Input Char(256)

9 User-definable exit program parameter Input Char(1024)

Note that parameter 9 is a 1024-byte fixed length character variable which will be padded with trailing blanks if the parameter extracted from the spooled file is less than 1024 bytes long. If more than one parameter is extracted from the spooled file, only the first parameter will be passed to an exit program defined as having *TYPE1 parameters. It is therefore recommended that you use *TYPE2 parameters if you wish to extract more than one parameter string from the spooled file. Type 2 parameter list A type 2 parameter list consists of the following:

1 Spooled file name Input Char(10)

2 Name of the job that created the spooled file Input Char(10)

3 User id that created the spooled file Input Char(10)

4 Number of the job that created the spooled file Input Char(6)

5 Spooled file number Input Binary(4)

6 Spooled file user data Input Char(10)

7 Name of the stream file just created Input Char(128)

8 Directory name in which stream file was created Input Char(256)

9 First page processed Input Binary(4)

10 Last page processed Input Binary(4)

11 Number of following user-definable parameters Input Binary(4)

12 User definable parameter 1 Input Char(*)

13 User definable parameter 2 Input Char(*)

…

User definable parameter 150 Input Char(*)

The number of user definable parameters that is passed on the call is indicated by the value of parameter 11. This is followed by between 0 and 150 are variable-length strings, the length of which ranges from 0 to 1024 bytes. These are equivalent to ILE RPG character

Page: 58

variables with the VARYING attribute specified, i.e. they consist of a two-byte binary length followed by up to 1024 bytes of text. The number of user definable parameters passed is always equal to the number of user definable parameters specified on the EXITPGMPOS and EXITPGMKEY command parameters. If no text is selected for one of these parameters (e.g. the key value specified does not appear), a zero-length parameter is passed. Parameters are always passed in the order in which they are defined on the EXITPGMPOS and EXITPGMKEY parameters. Parameters defined on EXITPGMPOS precede those defined on EXITPGMKEY. The “first page processed” and “last page processed” parameters indicate the first and last page processed since the last exit point of this type in question was reached. For an exit program called at the end-of-page exit point, these will both be equal to the page number in the original spooled file just processed. For a stream-file-creation exit point, these will be the page numbers in the original spooled file of the first and last pages that appear in the stream file just created. For an end-of-file exit program, these will be the first and last pages in the spooled file. The pre-file creation exit program can return the passwords to be used for the file about to be created. This information must be passed back to CoolSpools in a 2000-byte character data area call CS_FEEDBCK. CoolSpools creates this data area in QTEMP for you every time the pre-file creation exit program is called, and deletes it after the call. The user password to be applied to the file about to be created should be passed back in positions 1-32 of the data area, and the owner password in positions 33-64. If blanks are passed for either of these parameters, the value of the corresponding password on the PASSWORD command will be used instead. For example, if you want each file to have a different user password, but the same owner password, write the exit program so that it returns the user password required in positions 1-32 of the data area, but return blanks in positions 33-64. The owner password will then be taken from the value typed on the PASSWORD parameter. Exit programs can be used for a variety of purposes. Some of these are explored below. Firstly, you might split your invoices spooled file into separate files for each invoice using the SPLIT(*PAGE) option, like this: Example: CVTSPLSTMF FROMFILE(INVOICES)

TOSTMF(invoice.pdf)… TOFMT(*PDF)

SPLIT(*PAGE) SPLITPAGE(1)

CVTSPLSTMF will create stream files called invoice1.pdf, invoice2.pdf, invoice3.pdf etc. You could use the exit program to rename these files to something more meaningful. For example, using the parameter information passed to the exit program you might rename these files to something based on your customer number or the customer name. Secondly, the exit program could be used to perform further processing on the stream file. For example, the exit program could use the parameter information it is passed to identify the customer to whom the invoice relates, retrieve the customer’s e-mail address from the database, and invoke a mail application to send the invoice to the customer.

Page: 59

See the EXITPGMPRM, EXITPGMPOS and EXITPGMKEY parameters for further information about how to specify what parameter information should be passed to your exit program. See Appendix A for an example of an exit program which renames the stream file just created based on the parameter data it is passed.

Page: 60

FONT This parameter allows you to specify the way CoolSpools handles fonts when creating a stream file from your spooled file. This parameter is displayed during command prompting only if you specified PMTADLPARM(*YES) to prompt additional parameters and if one of the following options is specified for the TOFMT parameter: *PDF, *HTML, *HTXT, *HTMLCSS, *RTF. It consists of 3 elements. The first element is the Font Face. Options are:

*MAP (Default) In relation to PDF, CoolSpools maps AS/400 fonts to an equivalent PC font from the PDF basic font set (listed below). This option will minimize the size of the PDF file created, but the appearance of the text in the PDF file may not necessarily exactly reproduce the appearance of the text in the AS/400 spooled file when printed.

In relation to HTML and RTF, CoolSpools will likewise select a standard PC font equivalent to the font used in the iSeries spooled file. Typically this will be Courier for fixed-pitch fonts, Arial for sans-serif proportional fonts and Times for other proportional fonts.

*EMBED This option is only allowed with TOFMT(*PDF). Where possible, CoolSpools will embed the font in the PDF file. This guarantees that the font will be available when the PDF file is viewed in Acrobat, and will reproduce the appearance of the AS/400 font on the printed page as closely as possible. However, it may also significantly increase the size of the resultant PDF.

*CONVERT Same as *MAP, which has replaced it. This value continues to be supported for reasons of backwards compatibility.

The following options correspond to the basic PDF font set. These fonts are guaranteed by Adobe Acrobat to be always available when you view a PDF file that uses them. *COURIER Courier. All text will appear in Courier font. *COURIERB Courier Bold *COURIERO Courier Oblique *COURIERBO Courier Bold Oblique *HELVETICA Helvetica *HELVB Helvetica Bold *HELVO Helvetica Oblique *HELVB Helvetica Bold *HELVBO Helvetica Bold Oblique *TIMES Times Roman *TIMESB Times Roman Bold *TIMESI Times Roman Italic *TIMESBI Times Roman Bold Italic

Page: 61

*SYMBOL Symbol *DINGBATS Zapf Dingbats

The second element is the Font Size. Options are: *CALC (Default) CoolSpools selects an appropriate font size

based on the font and CPI information in the spooled file. Font_Size Specify a font size to be applied to all text.

The third element is only relevant when *EMBED is selected. It allows you to control which types of AS/400 font are embedded in the resultant PDF. Single options are:

*NONE (Default) No fonts are embedded. This value is not allowed if *EMBED is specified for the first element of the FONT parameter.

*ALL CoolSpools will embed all font types which can currently be embedded.

Other options are:

*PSTYPE1 Postscript Type 1 fonts (also called outline fonts on

iSeries) will be embedded. *CIDKEYED CID-keyed fonts (PostScript Type 0 fonts) will be

embedded. These are DBCS fonts. *RASTER Raster (bitmap) fonts are embedded. *FONTID Fonts specified by font identifier (e.g. by means of the

DDS FONT keyword) are embedded. This is dependent on a suitable font resource object being available for embedding.

Please note that AS/400 raster (bitmap) fonts are relatively low resolution (typically 240 or 300 pels per inch) and are imported into PDF in the form of bitmap images. When displayed on screen in Adobe Acrobat, these bitmaps can appear jagged and uneven and the presentation quality is generally rather poor. This is a feature of the font technology, not a deficiency on the part of CoolSpools. When printed, the PDF accurately reproduces the print quality of the AS/400 font on the page. Example: CVTSPLSTMF FROMFILE(SALES)… TOFMT(*PDF)

FONT(*MAP) Here the sales report is converted to PDF format and CVTSPLSTMF will attempt to select suitable replacement fonts for those used in the spooled file. Example: CVTSPLSTMF FROMFILE(SALES)… TOFMT(*PDF)

FONT(*EMBED) The same report is converted, but where possible CVTSPLSTMF will embed a copy of each AS/400 font in the resultant PDF.

Page: 62

Example: CVTSPLSTMF FROMFILE(SALES)… TOFMT(*PDF)

FONT(*HELVETICA 12) Here the same report is converted, but Helvetica 12-point font will be used throughout. CVTSPLSTMF will also assist you in improving the appearance of your reports in PDF, RTF and HTML format by providing messages in the job log to inform you about the font mappings it has made. If you are not satisfied with the appearance of your report in PDF, RTF or HTML, you should examine the job log of the job in which the CVTSPLSTMF command was executed, and locate any messages of the form: Courier 10 substituted for font id 11 or Courier Bold 10 substituted for font resource C0S0CB10 These messages are intended to help you identify which font is and font resource names need to be mapped. You can try alternative font mappings through the user-definable font mapping facility, implemented via the CVTFONTID and CVTFNTRSC parameters described below.

Page: 63

TEXT The TEXT (Text options) parameter allows you to control various options relating to the processing of text. It is displayed during command prompting only if you specified PMTADLPARM(*YES) to prompt additional parameters and if one of the following options is specified for the TOFMT parameter: *PDF, *HTML, *HTXT, *HTMLCSS, *RTF. It consists of 2 elements. Include overlay text? The first element determines whether textual content derived from an overlay or page segment object is included in the output. Overlays often contain constants, labels and heading text while the spooled file itself contains the variable data associated with those constants, labels and headings. For example, you might have an invoicing application where your overlay contains text such as “Customer name”, “Invoice number” and “Invoice date” and your spooled file supplies the actual customer name, invoice number and invoice date information to be printed alongside those labels. In some circumstances, for example when creating PDF versions of your spooled file, it may be appropriate to include the overlay text for the sake of clarity. However, in other circumstances, for example when converting the data to ASCII text format for indexing purposes, it might be more appropriate to exclude the overlay text and just process the variable data from the spooled file itself. This parameter allows you to indicate which option you wish to choose. Values are:

*TOFMT (Default) CoolSpools determines whether to include overlay text based on the format of the stream file being created. Overlay text is included if the spooled file is being converted to *PDF or *HTMLCSS, otherwise it is excluded.

*SPLF CoolSpools determines whether to include overlay text based on the format of the spooled file being converted. Overlay text is excluded if the spooled file is being converted is *SCS, otherwise it is included.

*YES Overlay text is included. *NO Overlay text is excluded.

Text column calculation method The second element is the Text Column Calculation Method. This parameter controls the way in which CoolSpools calculates columns in the report, for the purposes of text selection (e.g. bookmarks, split keys, exit program parameters). Where the spooled file contains text with different font sizes, especially proportional fonts, it is not obvious how to calculate the text “column” for a piece of text when text is being selected using the *ROWCOL method. Values are:

*FONT (Default) CoolSpools calculates text columns using the different font sizes in the spooled file.

Page: 64

*CPI CoolSpools calculates text columns using the CPI attribute of the spooled file. This is the method used by DSPSPLF.

Page: 65

DBCS The DBCS (DBCS conversion options) parameter allows you to control various options relating to the processing of DBCS (Double-Byte Character Set) data, i.e. data in languages such as Japanese, Chinese and Korean. It is displayed during command prompting only if you specified PMTADLPARM(*YES) to prompt additional parameters and if one of the following options is specified for the TOFMT parameter: *PDF, *HTML, *HTXT, *HTMLCSS, *RTF. It consists of 2 elements. DBCS Coded Font The first element specifies the qualified name of the DBCS coded font to be used to implement DBCS text in the spooled file. It is not normally necessary to specify a value on this parameter since the names of DBCS fonts to be used will be derived from the spooled file contents. If a DBCS spooled file has been created using a printer file which specifies IGCCDEFNT(*SYSVAL), the name of the coded font will be obtained from the QIGCCDEFNT system value. However, if the spooled file has been transferred to a system (e.g. a non-DBCS system) which has the system value QIGCCDEFNT set to *NONE, CoolSpools will be unable to identify the appropriate coded font to use. In those circumstances, you can use this parameter to specify the name of the font resource object (coded font) that should be used to display DBCS text in the spooled file. Values are:

*SPLF (Default) CoolSpools determines the DBCS coded font name from the spooled file attributes. Where the spooled file refers to the QIGCCDEFNT system value, the coded font is taken from the system value. If QIGCCDEFNT is set to *NONE, an error will be reported and you should specify a coded font name on this parameter.

*IGNORE Tells CoolSpools to ignore the fact that the spooled file attributes indicates that the spooled file contains DBCS data and process it as if it were an SBCS spooled file. This can be useful where processing SBCS spooled files created on SBCS systems.

Coded font Specify the qualified name of the font resource object to be used. The object specified must be of object type *FNTRSC with object attributes CDEFNT.

DBCS font size The second element specifies the DBCS font size. Similarly, it is not normally necessary to specify a value on this parameter since the font size of DBCS fonts to be used will be derived from the spooled file contents. However, the font size can be overridden using this parameter. Values are:

*SPLF (Default) CoolSpools determines the DBCS font size from the spooled file attributes.

Font size Specify the font size you wish to use.

Page: 66

MARGINS The MARGINS (Additional margins) parameter only appears during command prompting only if you specified PMTADLPARM(*YES) to prompt additional parameters and if TOFMT(*PDF) is selected. This parameter allows you to specify an additional left and/or top margin to be applied to the report. This can be useful where the report when printed appears too close to the left or top edge of the paper. AS/400 reports are frequently designed to fit snug to the left or top edge of the page, whereas many PC printers are unable to print close to the edges of the page. If no value is specified on this parameter, CVTSPLSTMF will reproduce the margins defined in the spooled file. There are eight elements to this parameter:

• the left margin • the top margin • the left overlay margin • the top overlay margin • the amount to shift text down the page when rotating • the unit of measurement • whether to increase the page size to accommodate the margins • the amount to shift text across the page when rotating

Options for the unit of measurement are: *MM Millimeters *INCH Inches

You can reduce the margin by specifying a negative number.

Example: CVTSPLSTMF FROMFILE(SALES)

TOSTMF('/sales/2001/april/sales.pdf') TOFMT(*PDF) MARGINS(1 0 *INCH)

The spooled file is converted to PDF format with an additional 1 inch left margin but no additional top margin. When your document prints in landscape mode as a result of a rotation, especially an automatic rotation triggered by the spooled file attribute PAGRTT(*AUTO), PAGRTT(*COR) or PAGRTT(*DEVD), you may find that text in your spooled file appears slightly out of alignment with overlays and graphics. This is the result of your printer applying a margin to the document as it rotates it. We recommend that you try adjusting the values of the 5th and 8th elements of this parameter until you document alignment is correct. These two elements (Auto-rotation top margin and Auto-rotation left margin) have a special value *CALC. If you specify *CALC, CoolSpools will attempt to calculate and predict this additional margin. *CALC is likely to become the default in the next release.

Page: 67

RTFMARGINS The RTFMARGINS (Rich Text Format margins) parameter only appears during command prompting only if you specified PMTADLPARM(*YES) to prompt additional parameters and TOFMT(*RTF) is selected. This parameter allows you to specify the margins to be used when creating a Rich Text Format (RTF) document. There are five elements to this parameter: the left margin; the right margin; the top margin; the bottom margin; and the unit of measurement. Defaults are 10, 13, 10, 10 and millimeters respectively. Options for the unit of measurement are:

*MM Millimeters *INCH Inches

Page: 68

INCLFILE The INCLFILE parameter only appears only appears during command prompting only if you specified PMTADLPARM(*YES) to prompt additional parameters and TOFMT(*PDF) is selected. This parameter allows you to specify up to 20 stream files, located on the AS/400 on which the command is being run, which are to be combined with the spooled files data when generating a PDF file. This option can be used, for example, to incorporate a scanned image of your pre-printed stationery into the PDF file so that it reproduces the appearance of the printed form exactly. Alternatively, you might wish to include your company logo in a PDF file created from an *SCS spooled file, which cannot use graphics. At present the included image files(s) MUST be an image in JPEG format (.JPG, .JPEG). CVTSPLSTMF must be able to locate the image file in the IFS at the time when the command is run. The default value is the single value *NONE, which indicates that no such files are to be included. There are nine elements that must be specified for each included file:

• The IFS path name identifying the file to be included. CVTSPLSTMF will use this path to locate the file at the time the command is executed. If it cannot be located, or if the file is not in JPEG format, an error will be reported.

• The method of inclusion. There are two possibilities: *EMBEDDED and *EXTERNAL. The *EMBEDDED option actual embeds or combines the JPEG file in the PDF file being created. This has the advantage of leaving you with just a single file to manage or distribute, but will increase the size of the resulting PDF file. With the other option (*EXTERNAL), the PDF just contains a link or reference to the JPEG file, which is then brought in by the PDF viewer application when the PDF file is opened. This minimizes the size of your PDF file, but means that you must also manage and distribute the JPEG file with the PDF file.

• On which pages to include the image. Options are: *ALL (all pages), *ODD (odd-numbered pages only), *EVEN (even-numbered pages only, *FIRST (the first page only), *LAST (the last page only), *BFRLAST (all pages before the last page) amd *AFTERFST (all pages after the first page). Please note that when determining whether a page is odd- or even-numbered, CVTSPLSTMF uses the natural order of pages in the spooled file and takes no account of any internal page numbering. For example, if your spooled file has an unnumbered batch header sheet, and your page numbering starts at 1 on page 2 of the spooled file, CVTSPLSTMF will take no account of this and will count the first page odd, the second page even etc.

• The X coordinate (distance across from left to right) of the position on the page where the image should appear.

• The Y coordinate (distance down from top to bottom) of the position on the page where the image should appear.

• The unit of measurement used to specify the X- and Y-coordinates. Options are: *MM (millimeters) or *INCH (inches).

Page: 69

• The external reference. This is only relevant if the inclusion method is *EXTERNAL. Here you must specify the directory path to be used to locate the external JPEG image at the time when the PDF file is opened.

• The external reference type. This parameter controls the format and syntax used for the external reference to be included in the PDF file, and is dependent on the platform on which you expect the PDF file to be opened. Options are: *DOS (a DOS/Windows format reference), *UNIX (a UNIX format reference), *MAC (Apple MAC format), *URL (a URL or Internet format reference)

• The scaling factor (default 1.00 i.e. no scaling). This allows you to expand and contract the size of the JPG image as it appears in the PDF file.

Example: CVTSPLSTMF FROMFILE(SALES)… TOFMT(*PDF)

INCLFILE( (‘/images/salesform.jpg’ *EMBDEDDD *ALL 0 0 *INCH)

Here the sales report is converted to PDF format and a scan of the pre-printed form in JPEG format (called salesform.jpg and located in the images directory of the IFS root file system) is embedded in the PDF file and included on all pages at the top-left hand corner of the page. Example: CVTSPLSTMF FROMFILE(SALES)… TOFMT(*PDF)

INCLFILE( (‘/images/salesform.jpg’ *EXTERNAL *ALL 0 0 *INCH form.jpg *DOS)

Here the command achieves exactly the same results, except that the JPG is not embedded in the PDF file. Instead, when the PDF file is opened, the viewer application (which is intended to run on a DOS/Windows platform) will look for a file called form.jpg. Since just a simple file name is specified, the viewer application will look for the form.jpg file in the same directory where the PDF file is located.

Page: 70

COLOR The COLOR parameter is displayed during command prompting only if you specified PMTADLPARM(*YES) to prompt additional parameters and if one of the following options is specified for the TOFMT parameter: *PDF, *HTML, *HTXT, *HTMLCSS, *RTF. There are two elements to this parameter. The first element (Text color) allows you to specify the color to be used for black text in the original spooled file. Any text in the spooled file which is not black will retain its original color. Any black text will assume the color specified here instead. Options are:

*BLACK Black *RED Red *BLUE Blue *GREEN Green *YELLOW Yellow *WHITE White *MAGENTA Magenta *CYAN Cyan *BROWN Brown *GRAY Gray *GRAY Gray *PINK Pink *PALEBLUE Pale blue *PALEGREEN Pale green *PALEYLW Pale yellow *PALEMAG Pale magenta *PALECYAN Pale cyan *PALEBROWN Pale brown *PALEGRAY Pale gray

The second element (Background color) allows you to specify the color to be used for the report background. Options are:

*BLACK Black *RED Red *BLUE Blue *GREEN Green *YELLOW Yellow *WHITE White *MAGENTA Magenta *CYAN Cyan *BROWN Brown *GRAY Gray *GRAY Gray *PINK Pink *PALEBLUE Pale blue *PALEGREEN Pale green *PALEYLW Pale yellow *PALEMAG Pale magenta

Page: 71

*PALECYAN Pale cyan *PALEBROWN Pale brown *PALEGRAY Pale gray

Example: CVTSPLSTMF FROMFILE(SALES)… TOFMT(*PDF)

COLOR(*BLUE *PALEYLW)

The sales report is converted to PDF. Any black text in the report will appear blue in Adobe Acrobat. Other colored text will retain its original color. The text will appear against a pale yellow background.

Page: 72

CVTFONTID The CVTFONTID (Convert Font Id) parameter only appears during command prompting only if you specified PMTADLPARM(*YES) to prompt additional parameters and one of the following values is input for the TOFMT parameter: *PDF, *RTF, *HTML, *HTXT, *HTMLCSS. This parameter allows you to define your own mappings or fonts to be embedded for those fonts used in the spooled file that are identified by a font id number. You may define font mappings and embedded fonts here in order to improve the appearance of your report in PDF, RTF or HTML format where FONT(*MAP) alone does not give satisfactory results. Up to 100 mappings may be defined. Where the specified “from” font id and font size appears in the spooled file, it will be mapped to the font typeface and point size specified here in the resultant PDF or HTML file. CVTSPLSTMF notifies you of the font mappings that it has chosen by sending a message to the job log when you run the command. If you are not satisfied with the appearance of your spooled file in the stream file, consider using this parameter or the CVTFNTRSC parameter to define your own font mappings. Refer to the discussion of the FONT parameter above for further information about how CVTSPLSTMF assists you in identifying the font ids that need to be mapped. The default is *NONE, which indicates that no user-defined font id mappings are specified. Other than *NONE, all other selections for this parameter consist of two pairs of elements: the “from” font id and font point size and the “to” font name and font point size. From Font Id Enter the font number which identifies the font in the font file. This will usually be a font number defined either on the FONT parameter of the CRTPRTF (Create Printer File) command or on the DDS FONT keyword, e.g. 11 = Courier 10 CPI. From Font Size The default for the “from” font point size is *FONTID, which indicates that the font point size implied by the font identifier should be assumed. Some IBM font identifiers (e.g. 11 = Courier 10 CPI) imply a specific font size, while others (e.g. 5707 = Times Roman Bold) do not. This is normally implemented on the iSeries through the use of the printer file DDS keyword FONT with or without the *POINTSIZE option. To Font Face The following built-in typefaces are available for selection:

*COURIER Courier *COURIERB Courier Bold *COURIERO Courier Oblique *COURIERBO Courier Bold Oblique *HELVETICA Helvetica *HELVB Helvetica Bold *HELVO Helvetica Oblique *HELVB Helvetica Bold *HELVBO Helvetica Bold Oblique *TIMES Times Roman

Page: 73

*TIMESB Times Roman Bold *TIMESI Times Roman Italic *TIMESBI Times Roman Bold Italic *SYMBOL Symbol *DINGBATS Zapf Dingbats

Example: CVTSPLSTMF FROMFILE(SALES) TOSTMF(sales.pdf) TODIR(‘/sales/2001/april’) TOFMT(*PDF)

FONT(*MAP) CVTFONTID(11 *COURIER 10)

Here, the sales report is converted to PDF format. CVTSPLSTMF will attempt to map fonts, but font id 11 is explicitly mapped to Courier 10-point. Alternatively, you can specify either a font resource object or a PostScript Type 1 font file. Note that you still need to specify FONT(*EMBED) if you want the font to be embedded in PDF. If you specify FONT(*MAP), CoolSpools will use the font specified on this element of the CVTFONTID parameter to select a suitable standard font to map to, but will still use a mapped standard font not an embedded font. These parameters require an IFS path name. We expect to extend these parameters to support TrueType and OpenType fonts at some point in the future. If you are referencing a font resource object, you must therefore specify the object name in IFS format, i.e. /QSYS.LIB/library_name.LIB/object_name.FNTRSC Example: CVTSPLSTMF… CVTFONTID(((416) ('/QSYS.LIB/QFNTCPL.LIB/ C0S0CR10.FNTRSC))) FONT(*EMBED) Font id 416 will be implemented by embedding font resource object C0S0CR10 in library QFNTCPL Example: CVTSPLSTMF… CVTFONTID(((416) ('/QIBM/PRODDATA/OS400/FONTS/PSFONTS/LATIN/COU.PFB'))) FONT(*EMBED) Font id 416 should be implemented by embedding the Postscript courier font supplied by IBM at the path given. Please note that two files are required in order to successfully embed a PostScript font: i) A PostScript Type 1 font file. This normally has a file extension of .pfb (e.g. /QIBM/PRODDATA/OS400/FONTS/PSFONTS/LATIN/HEL.PFB)

Page: 74

ii) A PostScript Type 1 font metrics file. This normally has a file extension of .afm (e.g. /QIBM/PRODDATA/OS400/FONTS/PSFONTS/LATIN/HEL.AFM) Specify the name of the font file (.pfb extension) on this parameter. CoolSpools will attempt to locate the corresponding font metrics file (.afm extension) in the same location. If either file cannot be found, or if either file is not recognised as the appropriate file type, an error will occur. To Font Size You can also specify a font size in points. The default is *FONTID. This indicates that the size of the font used will be the same as the font size implied or specified by the from-font id or from-font-size part of this parameter. You may also specify a particular font size in points that you want to use.

Page: 75

CVTFNTRSC The CVTFNTRSC (Convert Font Resource) parameter only appears during command prompting only if you specified PMTADLPARM(*YES) to prompt additional parameters and one of the following values is input for the TOFMT parameter: *PDF, *RTF, *HTML, *HTXT, *HTMLCSS. This parameter allows you to define your own mappings those for fonts used in the spooled file that are identified by a font resource name. You may define mappings here in order to improve the appearance of your report in PDF, RTF or HTML format if FONT(*MAP)alone does not give satisfactory results. Up to 100 mappings may be defined. The default is *NONE, which indicates that no user-definable font resource mappings are specified. Other than *NONE, all other selections for this parameter consist of three elements: a font resource name, a typeface name and a font size (in points). Where the specified font resource name appears in the spooled file, it will be mapped to the font typeface and point size specified here in the resultant PDF or HTML file. CVTSPLSTMF notifies you of the font mappings that it has chosen by sending a message to the job log when you run the command. If you are not satisfied with the appearance of your spooled file in the stream file, consider using this parameter or the CVTFONTID parameter to define your own font mappings. Refer to the discussion of the FONT parameter above for further information about how CVTSPLSTMF assists you in identifying the font ids that need to be mapped. From Resource Name Enter the name of a font resource referenced in the spooled file. This will usually be either: a font character set defined on the FNTCHRSET parameter of the CRTPRTF (Create Printer File) command or on the DDS FNTCHRSET keyword; or a coded font defined on the CDEFNT parameter of the CRTPRTF (Create Printer File) command or on the DDS CDEFNT keyword. From Font Size The default for the “from” font point size is *FONTID, which indicates that the font point size implied by the font resource should be assumed. Some font resource objects (typically raster fonts) imply a specific font size, while others (typically outline fonts) do not. This is normally implemented on the iSeries through the use of the printer file DDS keyword FNTCHRSET with or without the *POINTSIZE option. To Font Face The following built-in typefaces are available for selection:

*COURIER Courier *COURIERB Courier Bold *COURIERO Courier Oblique *COURIERBO Courier Bold Oblique *HELVETICA Helvetica *HELVB Helvetica Bold *HELVO Helvetica Oblique *HELVB Helvetica Bold *HELVBO Helvetica Bold Oblique

Page: 76

*TIMES Times Roman *TIMESB Times Roman Bold *TIMESI Times Roman Italic *TIMESBI Times Roman Bold Italic *SYMBOL Symbol *DINGBATS Zapf Dingbats

Example: CVTSPLSTMF FROMFILE(SALES)… TOFMT(*PDF)

FONT(*MAP) CVTFNTRSC(C0S0CR10 *COURIER 12)

Here, the sales report is converted to PDF format. CVTSPLSTMF will attempt to map fonts, but the font named C0S0CR10 is explicitly mapped to Courier 12-point. Alternatively, you can specify either a font resource object or a PostScript Type 1 font file. Note that you still need to specify FONT(*EMBED) if you want the font to be embedded in PDF. If you specify FONT(*MAP), CoolSpools will use the font specified on this element of the CVTFNTRSC parameter to select a suitable standard font to map to, but will still use a mapped standard font not an embedded font. These parameters require an IFS path name. We expect to extend these parameters to support TrueType and OpenType fonts at some point in the future. If you are referencing a font resource object, you must therefore specify the object name in IFS format, i.e. /QSYS.LIB/library_name.LIB/object_name.FNTRSC Example: CVTSPLSTMF… CVTFNTRSC(((C0S0CR10) ('/QSYS.LIB/QFNTCPL.LIB/ C0S0CR10.FNTRSC))) FONT(*EMBED) Font resource C0S0CR10 will be implemented by embedding font resource object C0S0CR10 in library QFNTCPL Example: CVTSPLSTMF… CVTFONTID(((C0S0CR10) ('/QIBM/PRODDATA/OS400/FONTS/PSFONTS/LATIN/COU.PFB'))) FONT(*EMBED) Font resource C0S0CR10 should be implemented by embedding the Postscript courier font supplied by IBM at the path given. Please note that two files are required in order to successfully embed a PostScript font: i) A PostScript Type 1 font file. This normally has a file extension of .pfb (e.g. /QIBM/PRODDATA/OS400/FONTS/PSFONTS/LATIN/HEL.PFB) ii) A PostScript Type 1 font metrics file. This normally has a file extension of .afm (e.g. /QIBM/PRODDATA/OS400/FONTS/PSFONTS/LATIN/HEL.AFM)

Page: 77

Specify the name of the font file (.pfb extension) on this parameter. CoolSpools will attempt to locate the corresponding font metrics file (.afm extension) in the same location. If either file cannot be found, or if either file is not recognised as the appropriate file type, an error will occur. To Font Size You can also specify a font size in points. The default is *FONTID. This indicates that the size of the font used will be the same as the font size implied or specified by the from-font resource or from-font-size part of this parameter. You may also specify a particular font size in points that you want to use.

Page: 78

BLANKS The BLANKS parameter only appears during command prompting only if you specified PMTADLPARM(*YES) to prompt additional parameters and one of the following values is input for the TOFMT parameter: *HTML, *HTXT, *TEXT. This parameter allows you to define whether blank lines in the original report should be duplicated in the output.

*NO No. Blank lines in the original report are not reflected in the output.

*YES Yes. Blank lines in the original report are reflected in the output. Pages are padded out with blank lines to resemble the printed page.

*FF Blank lines with form feeds. Blank lines in the original report are reflected in the output. At the end of each page, a form feed character is embedded in the output to force a page throw. This option is valid only in conjunction with TOFMT(*TEXT).

Page: 79

DELIMITERS The DELIMITERS (Delimiters for CSV or Excel) parameter only appears during command prompting only if you specified PMTADLPARM(*YES) to prompt additional parameters and one of the following values is input for the TOFMT parameter: *CSV, *XLS. This parameter allows you to control several aspects of the process of creating a delimited ASCII file from your spooled file. There are 5 elements to the parameter. Record delimiter This element allows you to specify the characters to be used to indicate the end of a record in the CSV file. Options are:

*CRLF Carriage return and line feed. Both a carriage return (x’0D’) and a line feed (x’0A’) character are used.

*CR Just a carriage return (x’0D’) is used. *LF Just a line feed (x’0A’) is used.

String delimiter This element allows you to define the character that encloses string (alphanumeric) data in the delimited ASCII file that is to be created. Either type the character to be used, or select one of the special values:

*DBLQUOTE A double quote (“) is used *SGLQUOTE A single quote (‘) is used *NONE No delimiter is used. Alphanumeric data is not

enclosed by any special character. Field Delimiter This element allows you to define the character that separates fields in the delimited ASCII file that is to be created. Either type the character to be used, or select one of the special values:

*COMMA A comma (,) is used *TAB A tab (x’09’) is used *BLANK A blank (x’20’) is used *SEMICOLON A semicolon (;) is used.

Example: CVTSPLSTMF FROMFILE(SALESSTATS)… TOFMT(*CSV)

DELIMITERS(*CRLF *DBLQUOTE *COMMA) The Sales Stats report is converted to a delimited file is CSV (Comma-separated variable format). Records are terminated by a carriage return/line feed pair. Alphanumeric data is enclosed in double quotes. Fields are separated by commas. Column Separator The values you select on this parameter control how the spooled file is converted to a delimited ASCII text file (e.g. a comma separated variable file).

Page: 80

There are two elements to this parameter: the column separator character and the number of consecutive separator characters to force a column break. The default for the first element is *SPLF. This tells CVTSPLSTMF to break the spooled file data into columns based on the way in which the data is split up in the spooled file. Where the spooled file is created from an externally described printer file this will probably give the best results, since the data in the spooled file is likely to be organized so that each natural or logical item of data appears as a separately identifiable element. However, if the spooled file is created from an internally described printer file, or from an application such as Query/400, it is likely that the data in the spooled file will be presented to CoolSpools as a single, unstructured data block for each line of the report. If this is the case then better results will probably be achieved by defining a column separator character to control the splitting of the data in the report. The column separator character can be any alphanumeric character. Often the best results will be obtained by selecting *BLANK (blank character) which will split the data in the spooled file every time one or more consecutive blank characters occur. Options are:

*SPLF Split the data in the report based on the organization of the data

*BLANK The separator character is the blank (space) character.

Character The separator character to use to identify column breaks.

Number of column separators The number of consecutive column separator character that must appear before a column break occurs.

Page: 81

PDFVIEWER The PDFVIEWER (PDF Viewer Controls) parameter allows you to define the type of PDF viewer application that will be used to read the PDF file to be created. It only appears during command prompting only if you specified PMTADLPARM(*YES) to prompt additional parameters and TOFMT(*PDF) is input. There are 5 elements to this parameter. PDF viewer type When creating a PDF file, this element controls the way in which fonts are defined. If you intend to use a viewer other than a Microsoft ® Windows viewer application, for example the Linux version of Adobe ® Acrobat, specify VIEWER(*OTHER) on this parameter. Unless VIEWER(*OTHER) is specified, the PDF file may not appear correctly when viewed using the Linux version of Acrobat or any other PDF viewer that does not run under Windows. Options are:

*WINDOWS A Microsoft ® Windows PDF viewer will be used * OTHER A viewer other than a Microsoft ® Windows viewer

will be used. Initial bookmark action This element allows you to specify whether PDF bookmarks should be visible when the report is first opened. Options are:

*SHOW (The default) Show the bookmarks when the document is opened

*HIDE Do not show the bookmarks when the document is opened.

It should be noted that some improvement in the time taken to open a PDF file can be accrued if BMARKACT(*HIDE) is selected. However, your users will need to make the bookmarks visible before they can be used to navigate around the document. Example: CVTSPLSTMF FROMFILE(SALES)…

BOOKMARK(*PAGNBR) BMARKACT(*HIDE)

The sales report is converted to PDF format and bookmarks are generated for each page of the report. However, the bookmarks are not displayed when the PDF file is first opened. Initial zoom when PDF opened This element allows you to define an initial magnification to be used when a PDF file is first opened. This parameter is ignored unless TOFMT(*PDF) is also specified. This parameter controls the appearance of the PDF document when first opened. Specifically, it determines the magnification factor used to display the document in the PDF viewer application.

Page: 82

Options are: *PDFDFT The default magnification defined in your viewer

options is used. *FITWDW Adjust the magnification so that the entire page just

fits in the viewer window. *FITWIDTH Adjust the magnification so that the width of the

page just fits in the viewer window. *FITVIS Adjust the magnification so that the text and

graphics on the page fit in the viewer window. *ACTUAL Adjust the magnification so that the page is viewed

at its actual size. Zoom factor The percentage magnification to apply.

PDF keywords for indexing This element allows you to define a set of keywords to be included in the Document Info section of the PDF file. These can be used by indexing and document management applications. Specify the keywords as a single character string with keywords separated by a comma or semicolon. Data Compression Here you can indicate whether stream data in a PDF files should be compressed, and, if so, what compression level to apply. Data compression is a trade-off between compression ratio and time. The higher the compression ratio that is attempted, the longer the data will take to compress. The options below enable you to select whether you want a high compression ratio (giving the smallest PDF files but taking longer to create) or the fastest conversion time (producing larger PDF files). Options are:

*OPT (Default) Stream data in PDF files is compressed. The level of compression that is applied provides a good degree of data compression while not taking unduly long to compress.

*YES Provided for compatibility with previous releases. Equivalent to *OPT.

*NONE Stream data in PDF files is not compressed. The resultant PDF files will be significantly larger than if data compression was applied, but will take less time to create.

*NO Provided for compatibility with previous releases. Equivalent to *NONE.

*MAX The maximum possible level of data compression is applied. The PDF files will be as small as possible, but will take the longest time to create.

*HIGHER A compression ratio higher than *HIGH but less than *MAX.

*HIGH A compression ratio higher than *OPT but less than *HIGHER.

Page: 83

*FAST A compression ratio less than *OPT but higher than *FASTER.

*FASTER A compression ratio less than *FAST but higher than *FASTEST.

*FASTEST The lowest and therefore fastest level of data compression.

Page: 84

EXCLPAGES The EXCLPAGES (Exclude Pages) parameter allows you to identify pages of the spooled file that should not be included in the resultant file. It only appears during command prompting if you specified PMTADLPARM(*YES) to prompt additional parameters and a value other than *SAV or *TIFF is input for the TOFMT parameter. For example, if your spooled file contains header sheets or batch separator pages, these can be dropped using this parameter. There are six elements to this parameter, each providing a different method of excluding pages from the spooled file 1. The number of pages to exclude at the beginning of the spooled file. If you

specify a number on this parameter element, then that number of pages will be ignored at the start of the spooled file. If your spooled file contains one or more unwanted header sheets at the beginning of the spooled file, these can be dropped by specifying the number of pages to be dropped here.

2. The number of pages to exclude at the end of the spooled file. If you specify a number on this parameter element, then that number of pages will be ignored at the end of the spooled file. If your spooled file contains one or more unwanted trailer sheets at the end of the spooled file, these can be dropped by specifying the number of pages to be dropped here.

3. The number of pages to exclude at the beginning of each stream file created from the spooled file. If your spooled file contains one or more unwanted header sheets at the beginning of each set of required pages, these can be dropped from the stream file by specifying the number of pages to be dropped here.

4. The number of pages to exclude at the end of each file created from the spooled file. If your spooled file contains one or more unwanted trailer sheets at the end of each set of required pages, these can be dropped from the file by specifying the number of pages to be dropped here.

5. A key string identifying pages to be dropped. The way the key string operates is dependent on the value of the sixth element “Exclude option”. Options are:

*CT (Default) “Containing”. Any page which contains the specified key string will be excluded.

*NC “Not containing”. Any page which does not contain the specified key string will be excluded.

For example, if your spooled file contains batch header sheets, and these contain the word “Batch” on them, they can be excluded from the stream file by specifying “Batch” as the key string on this parameter and *CT for the exclude option. Example: CVTSPLSTMF FROMFILE(INVOICES)…

EXCLPAGES(1 0 0 0 ‘Batch’ *CT)

The spooled file being processed here contains an unwanted header sheet at the beginning of the file. This is dropped from the PDF file being created because this parameter indicates that the first page of each file should be excluded. In addition,

Page: 85

the spooled file contains batch header sheets and these are not required in the PDF files. They are dropped because they contain the text string ‘Batch’ and this is specified as the exclude key string here.

Page: 86

EXCLLINNBR The EXCLLINNBR (Exclude Line Numbers) parameter specifies the line numbers of lines on the report which should be excluded from the Excel spreadsheet. This parameter only appears during command prompting if you specified PMTADLPARM(*YES) to prompt additional parameters and TOFMT(*XLS) or TOFMT(*CSV) is also specified. There are two elements to this parameter. ! The starting line number of the set of lines to be excluded ! The number of lines to exclude from this starting line number onwards Up to 20 sets of lines can be specified on this parameter.

Page: 87

EXCLLINKEY The EXCLLINKEY (Exclude Lines by Key) parameter specifies sets of lines on the report which should be excluded from the Excel spreadsheet based on the appearance in the line of a key string. This parameter only appears during command prompting if you specified PMTADLPARM(*YES) to prompt additional parameters and TOFMT(*XLS) or TOFMT(*CSV) is also specified. There are two elements to this parameter. ! The key string which identifies the start of a set of lines to be excluded ! The number of lines to exclude from this starting line onwards Up to 20 sets of lines can be specified on this parameter.

Page: 88

WORKSIZE The WORKSIZE (Initial Work File Member Size) parameter allows you to control the initial and maximum size of the work files used by CVTSPLSTMF. It is now only relevant to the production of Excel format data. This parameter only appears during command prompting if you specified PMTADLPARM(*YES) to prompt additional parameters and TOFMT(*XLS) is also specified. When converting very large spooled files (e.g. in excess of 2,000-3,000 pages), the CVTSPLSTMF work files may reach their default maximum size and require you to respond to increment messages in the QSYSOPR message queue. This can be avoided by specifying a larger maximum size or *NOMAX on this parameter. There are three elements to this parameter. ! The initial number of records that the member can contain before increments are added (*NOMAX may be specified to indicate that there is no maximum) ! The number of records in each increment ! The maximum number of increments allowed

Page: 89

CUSTOMPAGE The CUSTOMPAGE (Custom Page Size) parameter only appears if you have specified *CUSTOM on the PAGESIZE parameter. This parameter allows you to define a non-standard page size to be used. There are three elements to this parameter: the width of the page, the length of the page, and the unit of measurement. Options for the unit of measurement are:

*MM Millimeters *INCH Inches

Please note that the program makes no attempt to shrink or expand the report to fit the specified page size. Example: CVTSPLSTMF FROMFILE(SALES)…

PAGESIZE(*CUSTOM) CUSTOMPAGE(420 297 *MM)

The spooled file is converted to PDF format using a page size of 420 x 297 millimeters (A3).

Page: 90

BMARKPOS The BMARKPOS (Bookmark String Position) parameter only appears if BOOKMARK(*POS) is selected. This parameter allows you to define the position in the report where the text to be used as a bookmark regularly appears. The parameter consists of 4 elements:

I. the line number or y coordinate II. the column number or x coordinate III. the length of the text to be selected IV. the unit of measurement

By specifying BOOKMARK(*POS) with the BMARKPOS parameter, you can create a set of bookmarks based on a piece of text that appears at a particular position on each page of the report. For example, if you know that an item of user interest - such as an order number, a customer name, or a product code - appears regularly at position 3 of line 4 on every page and is up to 20 characters long, you can generate your bookmarks by specifying: Example: CVTSPLSTMF FROMFILE(SALES)…

BOOKMARK(*PAGNBR) BOOKMARK(*POS) BMARKPOS(4 3 20 *ROWCOL)

The BMARKPOS parameter operates slightly differently depending on whether your spooled file is a traditional row/column-based report using fixed-pitch fonts, or a more sophisticated AFP report using proportional fonts. With proportional fonts, row and column positioning is largely meaningless, and the position of text on the page should be specified in terms of x- and y-coordinates. If your report is a simple AS/400 report with just fixed-pitch fonts, select *ROWCOL (Rows and Columns) as the unit of measure method, and specify the line number on which the text appears, the column at which it starts, plus its length. If your report is uses proportional fonts, specify *INCH or *MM as the unit of measure, and specify the number of inches or millimeters down the page (y coordinate) or across the page from left to right (x coordinate) the text appears, plus its length in inches or millimeters. It is also permissible to use *ROWCOL for an AFP spooled file: CVTSPLSTMF will attempt to interpret the data in the AFP spooled file in terms of rows and columns, but be warned that the results may only be approximate. Example: CVTSPLSTMF FROMFILE(SALES)… TOFMT(*PDF)

BOOKMARK(*POS) BMARKPOS(3 20 40 *ROWCOL )

Here the sales report is converted to PDF. Assuming that the spooled file is a simple SCS spooled file using only fixed pitch fonts, and that the salesperson’s name appears at position 20 on line 3 of each page, and is up to 40 characters long, this command will generate PDF bookmarks based on the name of the salesperson whose figures appear on each page.

Page: 91

Example: CVTSPLSTMF FROMFILE(INVOICES)… TOFMT(*PDF)

BOOKMARK(*POS) BMARKPOS(20 30 100 *MM )

In this example, the invoices spooled file is converted to PDF. Assuming that the spooled file is an AFP spooled file using proportional fonts, and that the customer’s name appears at 20 mm down each page and 20 mm across each page, and is up to 100 mm long, this command will generate PDF bookmarks based on the name of the customer whose data appears on each page.

Page: 92

BMARKKEY The BMARKKEY (PDF Bookmark Key String) parameter only appears if BOOKMARK(*KEY) is selected. This parameter allows you to define a key string which will be used to identify the position in the report of the text to be used as a bookmark. The parameter consists of 5 elements: ! the key string ! the occurrence of this string on the page to be used ! the offset from the start of the key string to the start of the bookmark text ! the length of the text to be selected ! the unit of measurement By specifying BOOKMARK(*KEY) with the BMARKKEY parameter, you can create a set of bookmarks based on a piece of text that appears in the report on the same line as another piece of text (i.e. the key string, e.g. a field label) . For example, if you know that an item of user interest - such as an order number, a customer name, or a product code - appears on the same line as a label such as ‘Customer name:’, ‘Order No:’ or ‘Product Id’, then by using these labels as a key string you can generate bookmarks based on the actual customer name, order number or product code, e.g. CVTSPLSTMF … BOOKMARK(*KEY)

BMARKKEY(‘Customer name:’ 1 16 40 *ROWCOL) The BMARKKEY parameter operates slightly differently depending on whether your spooled file is a traditional row/column-based report using fixed-pitch fonts, or a more sophisticated AFP report using proportional fonts. With proportional fonts, row and column positioning is largely meaningless, and the position of text on the page must be specified in terms of x- and y-coordinates. If your report is a simple AS/400 report with fixed-pitch fonts, select *ROWCOL (Rows and Columns) as the unit of measure method, and specify the offset and length in characters. If your report is uses proportional fonts, specify *INCH or *MM as the unit of measure, and specify offset and length in inches or millimeters respectively. It is also permissible to use *ROWCOL for an AFP spooled file: CVTSPLSTMF will attempt to interpret the data in the AFP spooled file in terms of characters, but be warned that the results may only be approximate. Note that the offset value is measured from the start of the key string. A negative offset indicates that the text to be selected occurs to the left of the key string, a positive offset indicates that it appears to the right. The “occurrence” part of this parameter controls which occurrence of the key string on the page causes the bookmark text to be selected. That is, if you specify: CVTSPLSTMF ... BOOKMARK(*KEY)

BMARKKEY(‘Product code:’ 1 30 100 *MM) the bookmark will be generated from the text 30 millimeters to the right of the first occurrence of the string ‘Product code:’ on each page, whereas if you specify:

Page: 93

CVTSPLSTMF ... BOOKMARK(*KEY) BMARKKEY(‘Product code:’ 2 30 100 *MM)

the bookmark will be generated from the text 30 millimeters to the right of the second occurrence of the string ‘Product code:’ on each page. Example: CVTSPLSTMF FROMFILE(SALES)… TOFMT(*PDF)

BOOKMARK(*KEY) BMARKKEY(‘Area:’ 1 7 30 *ROWCOL )

Here the sales report is converted to PDF. Assuming that the spooled file is a simple SCS spooled file using only fixed-pitch fonts, and that the sales area name starts 7 characters to the right of the label ‘Area:’ on each page, and is up to 30 characters long, this command will generate PDF bookmarks based on the first area on each page. Example: CVTSPLSTMF FROMFILE(INVOICES)… TOFMT(*PDF)

BOOKMARK(*POS) BMARKKEY(‘20 30 100 *MM )

Page: 94

SPLITPAGE The SPLITPAGE (Split File Every n Pages) parameter only appears if SPLIT(*PAGE) is selected. This parameter allows you to specify the number of pages after which CVTSPLSTMF will create a new stream file. Example: CVTSPLSTMF FROMFILE(INVOICES)… TOFMT(*PDF)

SPLIT(*PAGE) SPLITPAGE(1)

Here the invoices spooled file is split into separate stream files for each page of the report.

Page: 95

SPLITKEY The SPLITKEY (Split Key String) parameter only appears if SPLIT(*KEY) is selected. This parameter has two related functions. The first function allows you to specify a key string which will trigger the creation of a new stream file every time it appears in the spooled file. Example: CVTSPLSTMF FROMFILE(SALES)… TOFMT(*PDF)

SPLIT(*KEY) SPLITKEY(‘Branch code:’)

Here the sales report is split into separate stream files every time the string ‘Branch code:’ appears in the report. Note that the stream file that is created when the key string is detected in the spooled file will start at the beginning of the page on which the key string first appears and will continue until the page preceding the next occurrence of the key string in the spooled file. However, if the key string appears more than once per page, occurrences following the first occurrence are ignored. In other words, a stream file always consists of at least one complete page, irrespective of how many times the key string appears per page. CVTSPLSTMF cannot create a stream file that represents only a part of a single page of the report. If this limitation is an inconvenience, you should consider adding a page throw prior to each occurrence of the key string in the report. Remember: with CVTSPLSTMF, paper costs are no longer an issue! The second function allows you to locate an area of the spooled file on the page by means of an offset position from the given key string. You can then perform comparisons on the value of the text at the position in the spooled file thus located and use these to control the splitting of the spooled file. Example: CVTSPLSTMF FROMFILE(SALES)… TOFMT(*PDF)

SPLIT(*KEY) SPLITKEY(‘Branch code:’ *IF 12 10 *ROWCOL *NE *PRV)

Here the sales report is split into separate stream files based on the 10 characters of text that appear 12 characters to the right of the string ‘Branch code:’ If this text is not equal to the previous value at this same position, a split will occur. There are seven elements to this parameter. This first element is the key string itself. If SPLIT(*KEY) is specified, a key string must be entered. All the other parts of this parameter are optional. The second element is the method of operation of this parameter Options are:

*ALWAYS Split the spooled file every time the key string appears in the spooled file. This is the default value.

Page: 96

*IF Use the key string to locate an area of the spooled file and then conditionally split the spooled based on performing a comparison on the text at that position.

The remaining elements are relevant only if *IF is specified for the second part of the SPLITKEY parameter. The third element indicates the horizontal offset from the start of the key string to the start of the area of the spooled file to be checked. This value can be either negative (the area to be checked is to the left of the key string) or positive (to the right). It is specified in either columns, inches or millimeters, depending on the value of the measurement method option (see fifth element below) The fourth element indicates the length of the area of the spooled file to be checked. It is specified in either columns, inches or millimeters, depending on the value of the measurement method option (see fifth element below) The fifth element is the measurement method and identifies the units in which the preceding two parameters are measured. Options are:

*ROWCOL The offset and length parameters are specified in characters.

*INCH The offset and length parameters are specified in inches. It is recommended that this option be used only for *AFPDS and *IPDS spooled files.

*MM The offset and length parameters are specified in millimeters. It is recommended that this option be used only for *AFPDS and *IPDS spooled files.

The sixth element is a comparison operator. This allows you to indicate the type of comparison to be performed on the area of the spooled file identified by the preceding parameters. Options are:

*EQ Equal to. *NE Not equal to *GT Greater than *LT Less than *GE Greater than or equal to *LE Less than or equal to *CT “Contained in”, i.e. the comparison string appears

somewhere in the area identified *NC “Not contained in”, i.e. the comparison string does

not appear anywhere in the area identified

The seventh element is the string against which the area of the spooled file should be compared, using the comparison operator specified in the preceding parameter. Any string may be specified, but the default value is the special value *PRV, which denotes the previous value at the same location. See the section of this document entitled “Specifying coordinate and key strings” for further information and advice regarding the use of this parameter.

Page: 97

Example: CVTSPLSTMF FROMFILE(INVOICES)… TOFMT(*PDF)

SPLIT(*KEY) SPLITKEY(‘Page No.:’ *IF 0.5 0.1 *INCH *EQ ’1’)

In this scenario, imagine that the spooled file contains invoices for multiple customers. Every time a new customer invoice is started, the page number is reset to 1. Here, the SPLITKEY parameter is being used to locate the page number in the spooled file: it is the text 0.1 of an inch long 0.5 inch to the right of the words “Page No.’”. A split will occur every time this area of the spooled file is equal to “1”, i.e. every first page of a customer invoice. Example: CVTSPLSTMF FROMFILE(SALES)… TOFMT(*PDF)

SPLIT(*KEY) SPLITKEY(‘Area code:’ *IF 12 5 *ROWCOL *NE *PRV)

Here, the SPLITKEY parameter is being used to locate the area code in the spooled file: it is the 5 characters of text 12 characters to the right of the words “Area code:”. A split will occur every time this area of the spooled file is different from the previous value at the same position, i.e. every time the area code changes.

Page: 98

SPLITPOS The SPLITPOS (Split by position) parameter only appears if TOFMT(*PDF) and SPLIT(*POS) are selected. This parameter allows you to locate an area of the spooled file on the page by means of coordinates down the page from top to bottom and across the page from left to right, or by line number and column position. You can then perform comparisons on the value of the text at the position in the spooled file thus located and use these to control the splitting of the spooled file. Example: CVTSPLSTMF FROMFILE(SALES)… TOFMT(*PDF)

SPLIT(*POS) SPLITPOS(1 3 10 *ROWCOL *NE *PRV)

Here the sales report is split into separate stream files based on the 10 characters of text that appear at column 3 of line 1 of each page. If this text is not equal to the previous value at this same position, a split will occur. There are six elements to this parameter. This first element is the line number or “y coordinate”, i.e. the position down the page from top to bottom where the area of the spooled file to be checked is located. It is specified in either columns, inches or millimeters, depending on the value of the measurement method option (see fourth element below). The second element is the column number or “x coordinate”, i.e. the position across the spooled file from left to right where the area of the spooled file to be checked is located. It is specified in either columns, inches or millimeters, depending on the value of the measurement method option (see fourth element below). The third element is the length of the area to be checked. It is specified in either columns, inches or millimeters, depending on the value of the measurement method option (see fourth element below). The fourth element is the measurement method and identifies the units in which the preceding two parameters are measured. Options are:

*ROWCOL The position down the page is specified in terms of lines of text and the position across the page and length are specified in column (characters). It is recommended that this option be used only for simple text-oriented *SCS spooled files.

*INCH The position down the page, position across the page and length are specified in inches. It is recommended that this option be used only for *AFPDS and *IPDS spooled files.

*MM The position down the page, position across the page and length are specified in millimeters. It is recommended that this option be used only for *AFPDS and *IPDS spooled files.

Page: 99

The fifth element is a comparison operator. This allows you to indicate the type of comparison to be performed on the area of the spooled file identified by the preceding parameters. Options are:

*EQ Equal to. *NE Not equal to *GT Greater than *LT Less than *GE Greater than or equal to *LE Less than or equal to *CT “Contained in”, i.e. the comparison string appears

somewhere in the area identified *NC “Not contained in”, i.e. the comparison string does

not appear anywhere in the area identified

The sixth element is the string against which the area of the spooled file should be compared, using the comparison operator specified in the preceding parameter. Any string may be specified, but the default value is the special value *PRV, which denotes the previous value at the same location. See the section of this document entitled “Specifying coordinate and key strings” for further information and advice regarding the use of this parameter.

Example: CVTSPLSTMF FROMFILE(INVOICES)… TOFMT(*PDF)

SPLIT(*POS) SPLITPOS(1.0 7.0 0.3 *INCH *EQ ’1’)

In this scenario, imagine that the spooled file contains invoices for multiple customers. Every time a new customer invoice is started, the page number is reset to 1. Here, the SPLITPOS parameter is being used to locate the page number in the spooled file: it is the text 0.3 of an inch long which appears 1.0 inches down the page and 7.0 inches across the page. A split will occur every time this area of the spooled file is equal to “1”, i.e. every first page of a customer invoice. Example: CVTSPLSTMF FROMFILE(SALES)… TOFMT(*PDF)

SPLIT(*POS) SPLITPOS(2 12 5 *ROWCOL *NE *PRV)

Here, the SPLITPOS parameter is being used to locate the area code in the spooled file: it is the 5 characters of text at column 12 of line 2 . A split will occur every time this area of the spooled file is different from the previous value at the same position, i.e. every time the area code changes.

Page: 100

EXITPGMPRM This parameter allows you to define whether CVTSPLSTMF should pass any user-definable parameter strings to the exit program or exit programs defined on the EXITPGM parameter, and, if so, on what basis. This parameter only appears during command prompting if you specified at least one program name on the EXITPGM parameter. Refer to the EXITPGM parameter above for further information about the parameters passed to an exit program. Options:

*NONE No text will be extracted from the report. For an exit program with a Type 1 parameter list,the user-definable parameter will consist of all blanks. For an exit program with a Type 2 parameter list, the user-definable parameter count will be zero. *POS CVTSPLSTMF will pass one or more parameters consisting of text extracted from the spooled file as defined by criteria specified on the EXITPGMPOS parameter.

*KEY CVTSPLSTMF will pass one or more parameters consisting of of text extracted from the spooled file as defined by criteria specified on the EXITPGMKEY parameter.

*BOTH CVTSPLSTMF will pass one or more parameters consisting of an item of text extracted from the spooled file as defined by criteria specified on both the EXITPGMPOS and EXITPGMKEY parameters.

Page: 101

EXITPGMPOS The EXITPGMPOS (Exit program parameter string position) parameter only appears if EXITPGMPRM(*POS) or EXITPGMPRM(*BOTH) is selected. This parameter allows you to define positions in the report from which CVTSPLSTMF will items of text and pass them as parameters to the exit program or programs you specified on the EXITPGM parameter. Up to 10 parameters may be selected in this way.Each parameter thus defined consists of 5 elements: ! The page number from which the text should be extracted. Note that this is

the page number from the stream file, not the spooled file. For example, if CVTSPLSTMF splits a 10-page spooled file into two 5-page stream files, then a page number of 1 on this parameter would refer to the first page in the two stream files, i.e. pages 1 and 6 from the original spooled file.

! The line number (for unit of measure *ROWCOL) or y coordinate (i.e. offset from the top edge of the page, for unit of measure *INCH or *MM), at which the required text is found.

! The column number (for unit of measure *ROWCOL) or x coordinate (i.e. offset from the left edge of the page, for unit of measure *INCH or *MM), at which the required text is found.

! The length in characters (unit of measure ROWCOL) or inches (*INCH) or millimeters (*MM) of the text to be selected.

! The unit of measure. If your report is a simple AS/400 report with fixed-pitch fonts, specify *ROWCOL as the measurement method. If your report is uses proportional fonts, specify *INCH or *MM as the measurement method.

Example: CVTSPLSTMF FROMFILE(INVOICES) TOSTMF(invoice.pdf)…

TOFMT(*PDF) SPLIT(*PAGE) SPLITPAGE(1) EXITPGM(Invexit) EXITPGMPRM(*POS) EXITPGMPOS(1 3 20 50 *ROWCOL)

In this example, the invoices spooled file is converted to separate PDF files for each page of the report. Every time a file has been completed, a program called INVEXIT will be called. The program will be passed 50 characters of text extracted starting at position 20 of line 3 of the first page written to each stream file.

Page: 102

EXITPGMKEY The EXITPGMKEY (Exit program parameter string key) parameter only appears if EXITPGMPRM(*KEY) or EXITPGMPRM(*BOTH) is selected. This parameter allows you to define key words or phrases which CVTSPLSTMF will use as triggers for extracting text from the report to pass as parameters to the exit program or programs you specified on the EXITPGM parameter. Up to 10 parameters can be selected in this way. Each parameter thus defined consists of 6 elements: ! The page number from which the text should be extracted. Note that this is

the page number from the stream file, not the spooled file. For example, if CVTSPLSTMF splits a 10-page spooled file into two 5-page stream files, then a page number of 1 on this parameter would refer to the first page in the two stream files, i.e. pages 1 and 6 from the original spooled file.

! The key string itself. This could be a field label, e.g. ‘Customer name:’ ! The occurrence of the key string which will trigger the extraction of parameter

text. For example, a value of 1 on this parameter will extract parameter text the first time the key string is located, a value of 2 on this parameter will extract parameter text the second time the key string is located etc.

! The offset from the start of the key string to the start of the text to extract for use as a parameter. This value can be negative if the text to extract is located to the left of the key string. This offset is measured in characters if unit of measure *ROWCOL is specified, in inches if *INCH is specified or in millimeters if *MM.

! The length of the text to extract. This length is measured in characters if unit of measure *ROWCOL is specified, in inches if *INCH is specified or in millimeters if *MM.

! The unit of measure. If your report is a simple AS/400 report with fixed-pitch fonts, specify *ROWCOL as the measurement method. If your report is uses proportional fonts, specify *INCH or *MM as the measurement method.

Example: CVTSPLSTMF FROMFILE(INVOICES) TOSTMF(invoice.pdf)…

TOFMT(*PDF) SPLIT(*PAGE) SPLITPAGE(1) EXITPGM(Invexit) EXITPGMPRM(*KEY) EXITPGMKEY( 1

‘Customer name:’ 1 15 50 *ROWCOL)

In this example, the invoices spooled file is converted to separate PDF files for each page of the report. Every time a file has been completed, a program called INVEXIT will be called. The program will be passed 50 characters of text extracted starting 15 characters to the right of the first occurrence of the string ‘Customer name:’ on the first page written to each stream file.

Page: 103

STMFCODPAG The STMFCODPAG (Stream File Code Page) parameter allows you to determine the way in which CoolSpools will convert data from the format in which it is held on the iSeries (typically EBCDIC) to an appropriate format in the stream file (typically ASCII). It only displays during command prompting if F10 is pressed. The rules used for deciding how iSeries data should be converted are complex, and depend on numerous factors, including the stream file format being created (as specified on the TOFMT parameter). In particular, PDF implements its own rules with regard to data encoding and these are followed in all instances. The value specified on the STMFCODPAG parameter is therefore ignored in relation to PDF creation and CoolSpools will convert the spooled file contents and all other data (such as the values specified on the TITLE or KEYWORDS parameters) to a format compatible with PDF. You may use one of the special values:

*WINDOWS (Default) Where appropriate, a suitable Windows ASCII encoding scheme is selected. For example, when converting a spooled file to *TEXT on a US iSeries (CCSID 37), code page 1252 (Windows Western ASCII encoding) is selected for the ASCII text, whereas on a Greek iSeries (CCSID 875), code page 1253 (Windows Greek) is selected.

*PCASCII A synonym for *WINDOWS provided for the sake of compatibility with previous releases and consistency with IBM-supplied command such to CPYTOSTMF.

*IBMASCII Where appropriate, a suitable IBM PC encoding scheme is selected. For example, when converting a spooled file to *TEXT on a US iSeries (CCSID 37), code page 437 (IBM PC ASCII) is selected for the ASCII text, whereas on a Greek iSeries (CCSID 875), code page 869 (IBM PC Data Greek) is selected.

*STDASCII A synonym for *IBMASCII provided for the sake of compatibility with previous releases and consistency with IBM-supplied command such to CPYTOSTMF.

*ISOASCII Where appropriate, a suitable ISO ASCII encoding scheme is selected. For example, when converting a spooled file to *TEXT on a US iSeries (CCSID 37), code page 819 (ISO 8859-1) is selected for the ASCII text, whereas on a Greek iSeries (CCSID 875), code page 813 (ISO 8859-7) is selected.

*STMF If the stream file exists, and where appropriate, the code page of the existing stream file is used for data conversion purposes.

*UNICODE Where appropriate, the data is converted to Unicode format. Note that Unicode data produced by CoolSpools is in bigendian format (i.e. the most significant byte is stored first, according to the iSeries convention, as opposed to the PC littleendian

Page: 104

convention, which stores the least significant byte first). When opening a text file created by CoolSpools with STMFCODPAG(*UNICODE) specified in an application such as Windows NotePad, select the Unicode bigendian format option.

Alternatively, you may enter a specific code page number. Example: CVTSPLSTMF FROMFILE(INVOICES) TOFMT(*TEXT)…

STMFCODPAG(1253) Here the CVTSPLSTMF command is being applied to create an ASCII text file from a Greek-language spooled file called INVOICES. Code page 1253, suitable for Greek-language data, will be used to convert the contents of the spooled file.

Page: 105

SPLFCCSID The SPLFCCSID (Spooled File CCSID) parameter allows you to indicate the CCSID (Coded Character Set Identifier) which CoolSpools should assume when converting the data content of the spooled file, in the absence of any other indication of the appropriate CCSID to use. The CCSID specifies the encoding scheme used to represent the data and determines how particular code point values will be interpreted and converted in the stream file that is to be created. It only displays during command prompting if F10 is pressed. Although more sophisticated printer data streams such as AFP and IPDS will include information which indicate the encoding scheme used to represent data in the spooled file, SCS spooled files often contain no explicit information to allow CoolSpools to determine the CCSID of the data. Although the CHRID value of the printer file may, in some cases, make it possible to interpret the CCSID to be used, in many instances the CHRID value will be *DEVD, meaning that the character identifier attribute of the printer device used to print the spooled file will determine the character set. CoolSpools cannot know which printer device was intended to print the spooled file and will assume that the CCSID to use is the CCSID indicated by the QCCSID or QCHRID system values. If the spooled file has CHRID(*DEVD) specified and was intended to be printed on a printer which uses a character set which is different from that implied by the QCCSID or QCHRID system values, it will be necessary to specify the appropriate CCSID on this parameter in order for CoolSpools to interpret the spooled file contents appropriately. You may use one of the special values:

*SPLF (Default) CoolSpools will use the information available from the spooled file to determine the correct CCSID to use. As explained above, if the spooled file does not contain adequate information relating to the encoding of the data it contains, CoolSpools will assume the CCSID implied by the QCCSID or QCHRID system values.

*SYSVAL The value of the QCCSID system value is used, or a CCSID derived from the QCHRID system value is used if QCCSID is 65535.

*JOB The CCSID of the current job is used. If the CCSID of the job is 65535, the default CCSID attribute of the job is used.

CCSID_value Specify the CCSID to be used.

Example: CVTSPLSTMF FROMFILE(GREEK)… SPLFCCSID(875)

Assume we are converting a spooled file received from a Greek customer on an English-language iSeries and that the spooled file is an *SCS spooled file with CHRID(*DEVD) specified. CoolSpools has no way of knowing that the spooled file contains Greek data, and it would be inappropriate to use the local CCSID. CoolSpools must be told to use an appropriate Greek EBCDIC CCSID (875) to convert the data.

Page: 106

Note that this would not be necessary if the Greek customer were running the conversion him or herself, since then the local system’s QCCSID value would indicate the encoding of the data correctly.

Page: 107

AUT The AUT (Public data authorities) parameter allows you to control the public data authorities given to stream files created as part of the CVTSPLSTMF command. It only displays during command prompting if F10 is pressed. There are two elements to this parameter. 1. Public data authority This element allows you to define the public authority for the stream to be created. If the stream file already exists, this parameter has no effect and the existing stream file retains its current authority settings. The owner of the file is always granted full authority. This parameter controls the authority given to other users. The default is *R (read-only authority). Options are:

*R Read only *W Write only *X Execute only *RW Read and write *RX Read and execute *WX Write and execute *RWX Read, write and execute (all) *NONE No authority

CVTSPLSTMF needs to create three temporary work files when it is generating PDF output. These files are normally automatically deleted when the command completes or if any error occurs. The files are named #job_nbrn, where job_nbr is the job number of the job in which the command is run and n is the work file number (1, 2, 3). The default is *TODIR (To Directory), which indicates that the work files will be created in the same directory as the final PDF file (as specified on the TOSTMF or TODIR parameters). This parameter gives you the option to create work files in a different directory from the directory where the final output will be created. For example, you might use a “temp” directory. This can be useful if you wish to avoid users seeing the temporary files while PDF files are being created. 2. Authority for PDF work files The second element of the AUT parameter allows you to define the public authority for the work files used when creating a PDF file. CVTSPLSTMF needs to create three temporary work files when it is generating PDF output. These files are normally automatically deleted when the command completes or if any error occurs. The files are named #job_nbr, where job_nbr is the job number of the job in which the command is run. The owner of the temporary file is always granted full authority. This parameter controls the authority given to other users. The default is *RWX (read, write and execute authority, i.e. full authority). Please note that if a value other than *RWX is specified on this command, it is possible in

Page: 108

certain circumstances for the creator of the file not to be authorized to delete it subsequently, and CVTSPLSTMF may be unable to clear them up after use. Options are:

*R Read only *W Write only *X Execute only *RW Read and write *RX Read and execute *WX Write and execute *RWX Read, write and execute (all) *NONE No authority

Page: 109

INHERITAUT The INHERITAUT (Inherit Authority) parameter allows you to control whether object authorities are inherited from the parent directory in which the stream file is created. It only displays during command prompting if F10 is pressed. Options are:

*NO Authorities are not inherited from the directory *YES Authorities are inherited from the directory.

When you specify INHERITAUT(*NO), the object authorities (*OBJEXIST, *OBJMGT, *OBJALTER, and *OBJREF) assigned to the owner, primary group, and *PUBLIC in respect of the stream file being created are copied from the owner, primary group, and public object authorities of the parent directory in which the stream file is created. This occurs even when the new file has a different owner than the parent directory. The new file does not have any private authorities or authorization list. It only has authorities for the owner, primary group, and public. The owner is assigned full data authorities and *PUBLIC is assigned the data authorities specified on the AUT parameter.

When you specify INHERITAUT(*YES), the object authorities (*OBJEXIST, *OBJMGT, *OBJALTER, and *OBJREF) assigned to the owner, primary group, and *PUBLIC in respect of the stream file being created are copied from the owner, primary group, and public object authorities of the parent directory in which the stream file is created. However, the private authorities (if any) and authorization list (if any) are also copied from the parent directory. If the new file has a different owner than the parent directory and the new file's owner has a private authority in the parent directory, that private authority is not copied from the parent directory. The authority for the owner of the new file is copied from the owner of the parent directory. The owner is assigned full data authorities and *PUBLIC is assigned the data authorities specified on the AUT parameter.

Page: 110

DFTFONT The DFTFONT (Default Font) parameter only appears if TOFMT(*PDF), TOFMT(*RTF) or TOFMT(*HTML) is selected. This parameter allows you to specify a default font to be used where CVTSPLSTMF is unable to identify a suitable font to use. For example, if your report uses a named AS/400 font resource, and the name of that font resource does not conform to IBM's naming standards, and you have not specified a font conversion on the CVTFNTRSC parameter, CVTSPLSTMF will use the default font you specify here as a replacement for the unknown AS/400 font resource. All other possible selections for this parameter consist of a font face name and a font size in points. The possible font typefaces supported are those defined as standard fonts by the PDF specification, namely:

*COURIER Courier *COURIERB Courier Bold *COURIERO Courier Oblique *COURIERBO Courier Bold Oblique *HELVETICA Helvetica *HELVB Helvetica Bold *HELVO Helvetica Oblique *HELVB Helvetica Bold *HELVBO Helvetica Bold Oblique *TIMES Times Roman *TIMESB Times Roman Bold *TIMESI Times Roman Italic *TIMESBI Times Roman Bold Italic *SYMBOL Symbol *DINGBATS Zapf Dingbats

These fonts are guaranteed by Acrobat to be available for use when you view a PDF file. The default is Courier 10-point. When you select one of these standard fonts, you must also indicate the font size you want (measured in points). Example: CVTSPLSTMF FROMFILE(SALES)… TOFMT(*PDF)

FONT(*CONVERT) DFTFONT(*HELVETICA 12)

Here the sales report is converted to PDF format, and CVTSPLSTMF is instructed to map AS/400 fonts to suitable substitute fonts recognized by Acrobat. Where CVTSPLSTMF cannot identify a suitable substitute font, Helvetica 12-point will be used. You must also specify a font size. If you have also selected TOFMT(*HTML), the font size you indicate here has a further significance. HTML font sizes are defined relative to a base font size. The font size defined on the DFTFONT parameter serves as the base font size for HTML (i.e.

Page: 111

it is mapped to Fontsize="3" in the HTML) and all other fonts will appear large or small relative to this font. For example, if you specify a default font size of 12 on this parameter, a font size of 10 in the spooled file will appear as a small font in the resultant html (since 10 < 12). However, if you specify a default font size of 8 on this parameter, a font size of 10 in the spooled file will appear as a large font in the HTML (since 10 > 8). Example: CVTSPLSTMF FROMFILE(SALES)… TOFMT(*HTML)

FONT(*CONVERT) DFTFONT(*HELVETICA 12)

The sales report is converted to HTML format. CVTSPLSTMF attempts to map AS/400 fonts to substitute PC fonts, and where this is not possible, Helvetica is used. 12-point is defined as being the basic HTML font size, and all other fonts in the report will appear large or small relative to this font.

Page: 112

TODIR The TODIR (To Directory) parameter specifies the directory path where the stream file should be saved. This parameter is only displayed during command prompting if F10 is pressed. The default option is *TOSTMF, which indicates that the full directory path to the stream file has been specified on the TOSTMF parameter and that this parameter is unused. Since this is now possible, the TODIR parameter is retained only for reasons of compatibility with previous releases. If you specify a directory name here it must already exist, otherwise an error will occur and the file will not be saved. Think of a path name as being a little like the address on a letter, only in reverse. When you write an address on an envelope, you start with the number or name of the house or building, then the street name, the city, the state, and finally the country, e.g. The White House Pennsylvania Avenue Washington DC U.S.A. Here we are moving from the smallest entity (building) to the biggest (country). However, the postal services will read the address in the reverse order, deciding which country to send the letter to first before looking for the state and so on. Like the Post Office, the AS/400 will examine a path name starting with the top-level entity (e.g. a directory in the root of the IFS) and working down toward lower level entities (sub-directories and individual files), e.g. a Company which has many branches worldwide might organize its sales figures files in a directory structure something like this: /usa/western/ca/sandiego/mainstreet/sales.csv Path names can be either absolute or relative. An absolute path name is one which starts with a slash character (either forward or backward, / or \), e.g. /sales/2000/october/stats/sales.csv Since this path name starts with a slash, the AS/400 will interpret this path name as starting in the root of the IFS (Integrated File System), i.e. at the highest level, and moving down through a directory called sales to a sub-directory called 2000, further sub-directories called october and stats, and finally to a file called sales.csv. This is a little like the full postal address of the file, with sales being equivalent to the country, 2000 to the state, october to the city, stats to the street and sales.csv to the actual building where the letter is eventually delivered. Alternatively, one can use a relative path name. This is like a partial postal address which assumes a starting point. For example, if you’re in London and someone asks you the way to Birmingham, you’re unlikely to enquire “Birmingham, England or Birmingham, Alabama”? You can assume from the context of the question that the Birmingham in England is the one being referred to.

Page: 113

Similarly, if you specify a path name without a starting slash symbol, the AS/400 will assume a starting point for this address, namely your current directory. Each time you sign on to the AS/400, your current directory will be set automatically to the value which your Security Officer specified on the HOMEDIR parameter of the CRTUSRPRF (Create User Profile) command when your user profile was first created. You can change you current directory at any time subsequently by means of the CHGCURDIR (Change Current Directory) command (for which the short form CD exists as an alternative). For example, CHGCURDIR /sales or CD /sales Assuming that your current directory has been set to /sales like this, then the relative path name 2000/october/stats/sales.csv and the absolute path name /sales/2000/october/stats/sales.csv both refer to the same file. If you have users who still use shared folders, you can refer to the shared folder file system by starting you path name with QDLS, e.g. /qdls/sales/2000/october/sales.csv This path name refers to a hierarchy of shared folders starting in a folder called sales. Example: CVTSPLSTMF FROMFILE(QSYSPRT) TOSTMF(sales.pdf) TODIR(‘/sales/2001/april’) Here the CVTSPLSTMF command is being applied to a spooled file called QSYSPRT in order to create a stream file called sales.pdf in an IFS root directory called sales/2001/april. In V3.1, a second element of the TODIR parameter allowed you to specify the directory in which work files were created when generating a PDF file. This element is now obsolete as V4.1 creates all work files in the /tmp directory of the IFS root file system and this feature has therefore been removed in V4.1.

Page: 114

Using CVTSTMSPLF The CVTSTMSPLF (Convert Stream File to Spooled File) command complements the CVTSPLSTMF (Convert Spooled File to Stream File command) and allows spooled files to be restored from stream file archives created using the CVTSPLSTMF…TOFMT(*SAV) option. The command has just three parameters.

FROMSTMF The FROMSTMF (From Stream File) parameter specifies the name of the stream file archive from which you wish to restore a spooled file. You may specify the name of the stream file in either of two ways. The first option is to enter a full path name on this parameter, that is the complete directory path and the name of the file to be created or replaced. The second option is to enter just the name of the file itself. You will then need to specify the directory path in which that file will be saved on the FROMDIR (From Directory) parameter. The name you enter here may be up to 128 characters long. This file MUST be a stream file previously created using the CVTSPLSTMF…TOFMT(*SAV) option.

FROMDIR The FROMDIR (From Directory) parameter may specify the directory path where the stream file to be processed is located. The default option is *FROMSTMF, which indicates that the full directory path to the stream file has been specified on the FROMSTMF parameter and that this parameter is unused. See the documentation of the TODIR parameter of the CVTSPLSTMF command for a discussion of directory and path names. Example: CVTSPLSTMF FROMFILE(QSYSPRT) TOSTMF(sales.pdf) TODIR(‘/sales/2001/april’) Here the CVTSPLSTMF command is being applied to a spooled file called QSYSPRT in order to create a stream file called sales.pdf in an IFS root directory called sales/2001/april . Example: CVTSTMSPLF FROMSTMF(sales.sav) FROMDIR(/spools/2001/june) Here the CVTSTMSPLF command is used to restore a previously saved spooled file from a stream file called sales.sav in a directory called /spools/2001/june.

NEWOWN The NEWOWN (New Owner) parameter specifies the user profile who should be assigned ownership of the spooled file when it is restored. The default is the special value *SPLF, which indicates that the owner of the original spooled file will also be the owner of the restored spooled file. However, if the user

Page: 115

profile which owned the original spooled file does not exist on the system to which the spooled file is being restored, an error will occur. This error can be avoided by specifying a different owning user profile on this parameter. Example: CVTSTMSPLF FROMSTMF(sales.sav) FROMDIR(/spools/2001/june) NEWOWN(PETE) Here the CVTSTMSPLF command is used to restore a previously saved spooled file from a stream file called sales.sav in a directory called /spools/2001/june. The owner of the restored spooled file will be user PETE.

OUTPTY The OUTPTY (Output Priority) parameter allows you to override the output priority attribute of the spooled file when it is restored. The default is the special value *SPLF, which indicates that the output priority of the original spooled file will be used. However, if this output priority exceeds the maximum output priority allowed for the user who is restoring the spooled file, the restore operation will fail. This error can be avoided by specifying a different (lower) output priority on this parameter.

Page: 116

Specifying coordinates and key strings Traditional *SCS spooled files identify the position of text on the page in terms of lines numbers and columns. Since, in the main, *SCS spooled files contain text which have a fixed characters-per-inch and lines-per-inch values, and since a single fixed-pitch font is normally used, calculating the position of text on the page in terms of lines and columns is simple and accurate. It is therefore recommended that *ROWCOL be used as the measurement method for spooled files of this kind. If a measurement method of *INCH or *MM is used with a row-and-column oriented spooled file, the position of the text on the page is calculated by converting the rows and columns into inches or millimeters using the CPI (characters per inch) and LPI (lines per inch) attributes of the spooled file. *AFPDS and *IPDS spooled files identify the position of text on the page in terms of coordinates measured in twips (1440ths of an inch). Even if the spooled file is created from a DDS printer file that defines text positions in rows and columns, these will not appear in spooled files created using the printer file: OS/400 will convert the rows and columns to twips as the spooled file is created. In addition, *AFPDS and *IPDS spooled files often contain multiple fonts, and those fonts are frequently proportional (where different characters have different widths, for example a “i” occupies much less horizontal space on the page than a “W”). The concept of a “row” and a “column” largely breaks down when we are dealing with spooled files of this kind. It is therefore strongly recommended that coordinates are specified in inches or millimeters rather than *ROWCOL when dealing with *AFPDS and *IPDS spooled files, especially those that use multiple fonts and proportional fonts. If *ROWCOL is used with an *AFPDS or *IPDS spooled file, the position of the text on the page is calculated by converting the rows and columns into inches or millimeters using the CPI (characters per inch) and LPI (lines per inch) attributes of the spooled file. Please note that the rows and columns thus calculated may not correspond to those displayed when DSPSPLF is used to view an *AFPDS or *IPDS spooled file (which are somewhat esoteric to say the least). Since this is not an exact science, some trial and error may be required to achieve the result you require. To assist you in this, CoolSpools sends message CVT0007 to the job log each time you SPLIT criteria result in a piece of text being selected and this message indicates the text that was selected. This will often assist you in adjusting your coordinates slightly so the text you intended to select is indeed selected. When specifying a key string to identify text within an *AFPDS or *IPDS spooled file (on the BMARKKEY, SPLITKEY, EXITPRMKEY, EXCLPAGES or EXCLINKEY parameters), the following points should be borne in mind. Text within *AFPDS and *IPDS spooled files is normally presented within as separate text elements (e.g. separate words or phrases), each with its own positioning coordinates controlling where the text appears on the printed page. For example, the words making up a sentence may not appear in the spooled file as a single concatenated string: instead each word may appears separately with its own positioning coordinates determining where it is printed.

Page: 117

When checking for the appearance of key strings within spooled files of this type, CoolSpools needs to be able to construct these separate text elements into a single text string, which can then be scanned for the occurrence of the key string. In doing this, CoolSpools will take account of the blank space between each text element, and will use the current font size to determine how many spaces should be inserted between each text element. If the text on the page is being printed in justified mode, the blank space between each text element (word or phrase) may be more than the width of a single space character in the current font and CoolSpools may decide to insert two or more spaces, Please bear this in mind when specifying key strings. You may need to specify more than a single space between text elements in you key string.

Appendix A: Sample Exit Programs A “Type 1” Exit Program which renames the stream file just created In this first example, exit program EXITPGMRNM uses a “Type 1” (*TYPE1) parameter list. It is intended to be called each time a new stream file is generated in order to rename the stream file just created to something more meaningful. It is defined to CoolSpools using the syntax: EXITPGM(*LIBL/EXITPGMRNM *TYPE1) It is assumed that the EXITPGMPRM(*POS) or EXITPGMPRM(*KEY) option has been used to extract an item of information from the report so that it is passed to this exit program in the ninth parameter position. This could be, for example, a customer number, order number, invoice number etc. The stream file is renamed from the name given it by CVTSPLSTMF to nnnnnnn.pdf, where nnnnnnn is the number extracted from the report and passed as a parameter. ****************************************************************** * * * PROGRAM NAME: EXITPGMRNM * * * * LANGUAGE : ILE RPG * * * * DESCRIPTION : Sample CVTSPLSTMF exit program * * * ****************************************************************** H COPYRIGHT('(C) @riadne software July 2000') ****************************************************************** * PROTOTYPE FOR STANDARD EXIT PROGRAM PARAMETERS * ****************************************************************** D Parameters PR ExtPgm('EXITPGMRNM') * Spooled file name D iaSplFile 10A * Name of the job which created the spooled file D iaSplJob 10A * User id of the job which created the spooled file D iaSplUser 10A

Page: 118

* Job number of the job which created the spooled file D iaSplJobNo 6A * Spooled file number of the spooled file D iiSplNbr 10I 0 * Spooled file user data D iaUsrDta 10A * Name of the stream file created D iaStmFile 128A * IFS directory in which stream file was created D iaDir 256A * Exit program parameter string extracted from spooled file D iaExitParm 1024A ****************************************************************** * PROTOTYPE FOR QCMDEXC * ****************************************************************** D Command PR ExtPgm('QCMDEXC') D iaCommand 32767A CONST OPTIONS(*VARSIZE) D inCmdLen 15P 5 CONST ****************************************************************** * STANDARD EXIT PROGRAM PARAMETERS * ****************************************************************** D Parameters PI D iaSplFile 10A D iaSplJob 10A D iaSplUser 10A D iaSplJobNo 6A D iiSplNbr 10I 0 D iaUsrDta 10A D iaStmFile 128A D iaDir 256A D iaExitParm 1024A D laOldName S 1024A D laNewName S 1024A D QUOTE C '''' * If customer number found and passed as parameter, rename stream file C IF iaExitParm <> *BLANKS * Set up full path name to stream file C IF iaDir = *BLANKS C EVAL laOldName = QUOTE C + %trim(iaStmFile) C + QUOTE C ELSE C EVAL laOldName = QUOTE C + %trim(iaDir) C + '/' C + %trim(iaStmFile) C + QUOTE C ENDIF

Page: 119

* Set up new path name for file using customer number in parameter C EVAL laNewName = QUOTE C + %trim(%subst(iaExitParm:1:7) ) C + '.pdf' C + QUOTE * Rename the stream file C CALLP(E) Command( 'REN ' C + laOldName C + ' ' C + laNewName:2053) C ENDIF C RETURN

A “Type 2” Exit Program which renames the stream file just created In this second example, exit program EXITSNDDST uses a “Type 2” (*TYPE2) parameter list. It is intended to be called each time a new stream file is generated in order to e-mail the stream file just created to the customer to whom the document relates. EXITPGM(*LIBL/EXITSNDDST *TYPE2) It is assumed that the EXITPGMPRM(*POS) or EXITPGMPRM(*KEY) option has been used to extract the customer number from the report. This customer number is used to look up the customer’s e-mail address on the customer database. The OS/400 SNDDST command is then used to e-mail the stream file to the customer concerned. Please note that SNDDST can only e-mail documents stored in the QDLS file system (“shared folders”). However, it would be possible to adapt this program to move the document out of QDLS into the root file system, and assign it a meaningful name, or place it in a customer directory, after it has been e-mailed. ****************************************************************** * * * PROGRAM NAME: EXITSNDDST * * * * APPLICATION : CVTSPLSTMF command * * * * LANGUAGE : ILE RPG * * * * AUTHOR : Peter Clifford * * * * DATE WRITTEN: Sep. 2000 * * * * DESCRIPTION : Sample CVTSPLSTMF exit program for sending a * * stream file via e-mail using SNDDST. * * * ****************************************************************** H COPYRIGHT('(C) @riadne software July 2002') * Customer file FCustFile IF E K DISK ****************************************************************** * PROTOTYPE FOR STANDARD EXIT PROGRAM PARAMETERS * ****************************************************************** D Parameters PR EXTPGM('EXITSNDDST')

Page: 120

* Spooled file name D iaSplFile 10A * Name of the job which created the spooled file D iaSplJob 10A * User id of the job which created the spooled file D iaSplUser 10A * Job number of the job which created the spooled file D iaSplJobNo 6A * Spooled file number of the spooled file D iiSplNbr 10I 0 * Spooled file user data D iaUsrDta 10A * Name of the stream file created D iaStmFile 128A * IFS directory in which stream file was created D iaDir 256A * Page number of the first page in the range processed D iiFirstPage 10I 0 * Page number of the last page in the range processed D iiLastPage 10I 0 * Exit program parameter count D iiParmCount 10I 0 * User-definable exit program parameter strings. Up to 150 of these * may follow. Define as many as you need. D iaUserParam1 999A OPTIONS(*NOPASS) D VARYING D iaUserParam2 999A OPTIONS(*NOPASS) D VARYING D iaUserParam3 999A OPTIONS(*NOPASS) D VARYING ****************************************************************** * PROTOTYPE FOR QCMDEXC * ****************************************************************** D Command PR ExtPgm('QCMDEXC') D iaCommand 32767A CONST OPTIONS(*VARSIZE) D inCmdLen 15P 5 CONST ****************************************************************** * STANDARD EXIT PROGRAM PARAMETERS * ****************************************************************** D Parameters PI

Page: 121

D iaSplFile 10A D iaSplJob 10A D iaSplUser 10A D iaSplJobNo 6A D iiSplNbr 10I 0 D iaUsrDta 10A D iaStmFile 128A D iaDir 256A D iiFirstPage 10I 0 D iiLastPage 10I 0 D iiParmCount 10I 0 D iaUserParam1 999A OPTIONS(*NOPASS) D VARYING D iaUserParam2 999A OPTIONS(*NOPASS) D VARYING D iaUserParam3 999A OPTIONS(*NOPASS) D VARYING D waCustomerNo S 10A D waCommand S 1024A D wnCmdLen S 15P 5 D QUOTE C '''' * This example assumes that the EXITPGMPRM, EXITPGMPOS and EXITPGMKEY * parameters have been used to extract the customer number from the * spooled file, and that the first user-definable parameter contains the * customer number (assumed to be 10 characters for the purposes of * this example). * Make sure at least one parameter was passed and that the parameter * passed is not to short C IF iiParmCount < 1 C or %len(iaUserParam1) < %size(waCustomerNo) * Insert appropriate error handling here C RETURN C ENDIF * Extract the customer number from the parameter string C EVAL waCustomerNo = %subst(iaUserParam1 : C 1 : C %len(waCustomerNo)) * Retrieve the customer's e-mail address from the customer file C waCustomerNo CHAIN CustFile C IF not %found(CustFile) * Insert appropriate error handling here C RETURN C ENDIF * Build the SNDDST command C EVAL waCommand = 'SNDDST TYPE(*DOC) ' C + 'TOINTNET((' * "CustEMail" is assumed to be the customer's email address field * from the customer file C + %trim(CustEMail) C + ')) ' * DSTD parameter below is the "subject" line that will appear for * the e-mail. Substitute your choice of subject line C + 'DSTD(' C + QUOTE C + 'Your invoice from CoolSpools' C + QUOTE C + ') ' * MSG parameter below is a brief message to accompany the attachment. * Substitute your choice of message. C + 'MSG('

Page: 122

C + QUOTE C + 'Your invoice is' C + ' attached. Thank you for your ' C + 'custom.' C + QUOTE C + ') ' * The document name and folder names are passed into this program from * CVTSPLSTMF. The document name if generated from the TOSTMF parameter * with the addition of a numeric suffix for each spooled file created. C + 'DOC(' C + %trim(iaStmFile) C + ') ' C + 'FLR(' C + %trim(iaDir) C + ')' * E-mail the stream file to the customer C CALLP(E) Command(waCommand:wnCmdLen) C IF %error * Insert appropriate error handling here C ELSE * Probably a good idea to log the sending of the e-mail in some way * e.g. for CRM purposes. Also consider requesting confirmation of * delivery for CFMDEL(*YES) C ENDIF C RETURN

Please contact @riadne software by e-mail to support@ariadnesoftware.co.uk if you require further assistance with programming exit programs or if your have any other questions, problems or suggestions relating to CoolSpools. We can provide other sample exit programs explaining, for example, how to copy PDF files to a server using FTP or e-mail them to your customers automatically.

Page: 123

Appendix B: The Integrated File System The iSeries Integrated File System (IFS) provides a coherent, coordinated set of file systems which can used for storing a variety of data physically on the iSeries or for communicating with file systems on other platforms. These files systems include the following that may be of use to you for storing stream files created by CoolSpools locally on your iSeries or remotely on another computer (PC, UNIX server etc.)

"root" The "root" (/) file system. This file system takes full advantage of the stream file support and hierarchical directory structure of the integrated file system. The root file system has the characteristics of the Disk Operating System (DOS) and OS/2 file systems. You should typically use the root file system if you want to store stream files created by CoolSpools locally on the same iSeries where you run the CVTSPLSTMF command.

QNTC Windows NT Server file system. This file system

provides access to data and objects that are stored on a PC running Windows NT 4.0 or higher. It allows iSeries server applications to use the same data as Windows NT clients. If you prefer not to store stream file locally on your iSeries, you can use QNTC to enable CoolSpools to write stream files directly to a PC running NT, Windows 2000, Windows XP etc. instead. This can be an effective way of sharing data created by CoolSpools amongst your users and customers.

NFS Network File System. This file system provides you

with access to data and objects that are stored on a remote NFS server. An NFS server can export a network file system that NFS clients will then mount dynamically. This may be an option for sending stream files to a UNIX server.

QNetWare The QNetWare file system. This file system

provides access to local or remote data and objects that are stored on a server that runs Novell NetWare 4.10 or 4.11 or to standalone PC Servers running Novell Netware 3.12, 4.10 4.11 or 5.0. You can dynamically mount NetWare file systems over existing local file systems.

Page: 124

QOpenSys The open systems file system. This file system is compatible with UNIX-based open system standards, such as POSIX and XPG. Like the root file system, this file system takes advantage of the stream file and directory support that is provided by the integrated file system. In addition, it supports case-sensitive object names.

QDLS The document library services file system

(previously know as “shared folders”). This file system provides access to documents and folders. Use this file system only if you have applications which require it. QDLS is significantly slower and has major limitations (e.g. in relation to naming) compared with the root file system.

QFileSvr.400 This file system provides access to other file

systems that reside on remote iSeries servers. You can use QFileSvr.400 to save output from CoolSpools directly to another iSeries.

See http://publib.boulder.ibm.com/iseries/v5r1/ic2924/info/rzaia/rzaiacon.htm for full details of the Integrated File System. We will now focus a little more closely on the QNTC File System since this is little known area of iSeries functionality which may well be of serious interest to users of CoolSpools. QNTC The QNTC file system is a subdivision of the IFS (Integrated File System) that enables the iSeries to access file and device shares (e.g. printers and CDROM) drives on a remote NT system. Please note that contrary to a commonly held fallacy this is NOT restricted to the Integrated NetFinity Server (aka IPCS or FSIOP). Using the QNTC file system, your iSeries can read and write files that reside physically on a PC running Windows NT 4 or above. This means that CoolSpools can output stream files directly to an NT server if you would prefer to store them there rather than in the root file system of your IFS. To use QNTC, the only software you need other than the base operating system is TCP/IP Connectivity Utilities for iSeries 400 (S722-TCl). However, setting up QNTC can be tricky. For full setup information, refer to the article in the IBM Software Knowledgebase at http://www-912.ibm.com/s_dir/slkbase.nsf/1ac66549a21402188625680b0002037e/aea450153eebf8ff8625670f0072550f?OpenDocument&Highlight=0,QNTC However, here is a quick overview of the steps you need to follow to set up QNTC. This example relates to V5R1.

Page: 125

Domain Names First you must ensure that the domain name defined by your iSeries NetServer configuration matches your PC’s Windows network workgroup name. NetServer is the function on the iSeries that provides support for the Windows Network Neighborhood. You can use Operations Navigator (OpsNav) to set up and manage NetServer. Please note that changing the iSeries domain name in NetServer may affect which PCs will be able to see the iSeries in their Network Neighborhood. From the main OpsNav window, click the name of your machine, select File Systems, and then right-click File Shares. Choose Open AS/400 NetServer from the menu to display the NetServer window. Right-click AS/400 NetServer and choose Properties to display the Properties window, where you can change the domain. Click the General tab and press the Next Start button. A window appears where you can set properties that will be used the next time NetServer is restarted. In the domain name field, enter a name that matches the workgroup of the NT PC that you wish to access. Now, if you are sure that NetServer is not currently in use, end and restart NetServer by clicking the Stop icon followed (once NetServer has fully ended) by the green triangle icon. If you wish to change the Network Id on the PC side, this can be done through the Windows Control Panel. On Windows 2000, select Start, Settings, Control Panel, and System. Then choose the Network Identification tab, click the Properties button, select Workgroup, and set the workgroup to match the domain that NetServer on the iSeries was configured to use. On XP, you’ll find the option on the Computer Name tab. On Windows NT, the option to change the workgroup name can be found if you select Start, Settings, Control Panel, and Network. Note that you may have to reboot the PC for these changes to take effect.

User Id and Password One other thing which must match between the iSeries and the NT PC is the user id and password you’re going to use. It is vital that your iSeries user id be recognised by the NT PC as a valid network logon id, and that the passwords are the same on both the iSeries and the NT machine. It may well be advisable to create a special user id on the two platforms specifically for the purpose of communicating between them using QNTC. You can then ensure that when the password needs to be changed, it is changed on both systems, if this needs to be done manually. Testing the Connection To test your connection, first ensure that you are logged on to the iSeries using a shared user id/password (see above), then run the command WRKLNK '/QNTC/*'

Page: 126

on the iSeries. This could take several minutes to complete the first time it is run. Your NT system should appear on the list. If it doesn't, you may be able to manually establish a connection to the NT system using command CRTDIR /QNTC/ <servername>‘, substituting the name of your NT system for servername. Find your NT system in this list and choose Display (option 5) in WRKLNK (Work with Object Links) to display your file shares on NT. If the file shares don't appear, double-check that your user IDs and passwords match exactly on both systems. You access the QNTC file system by including QNTC and the name of your PC and share name in the path name you specify on TOSTMF (To Stream File) parameter of the CVTSPLSTMF command. For example, let’s imagine you have a company server running Windows NT 4 or above and you have decided that this is a convenient place to save the output from CoolSpools so that all of your users can have shared access to the data. Let’s imagine that this server is called NTServer and that it has a file share name set up called NTFiles. Below the share name, there is a directory called CustData. If you wanted to convert data from your customer file and save it as an Excel spreadsheet in this location under the file name customer_file.xls, you would run a command something like this: CVTSPLSTMF FROMFILE(custfile)

TOSTMF(‘/QNTC/NTServer/NTFiles/CustData/customer_file.xls’) TOFMT(*XLS)

Note that the path name starts with /QNTC. This indicates to the iSeries that you are referring to the QNTC File System. Following /QNTC is the name of the PC to which the data is to be sent: NTServer. Next comes the name of the file share: NTFiles. After that is the name of the directory below the share: CustData. Finally we have the name of the file itself: customer_file.xls.

Page: 127

Appendix C: Acknowlegements PDF data compression is implemented using the “flate” compression algorithm as provided by the zlib compression library, developed by Jean-Loup Gailly and Mark Adler. Greek and Cyrillic text in PDF documents created with the FONT(*MAP) option may use the Monospace and Caslon freeware fonts developed by George Williams (Copyright © 1990-2001 by George Williams). See http://bibliofile.mc.duke.edu/gww/fonts/license.html for conditions and disclaimer.