USER GUIDE

Software Version 8.4.3. User Guide Build 1.

For IBM i and Windows.

TM

Catapult
The #1 Rated Automated IBM i Report and Document Distribution Tool

Automatically deliver reports to the people who need them

in the format they want.

Fresche Solutions
995 Wellington, Suite #200
Montreal, Quebec
Canada, H3C 1V3

Phone: (514) 747.7007

(toll-free in US and Canada): 1.800.361.6782
(toll-free in Belgium, France, Germany, UK): 00 800 361
67 82 0
(toll-free in Australia): 0011 800 361 6782 0
E-Mail: commercial.support@freschesolutions.com
Web: www.freschesolutions.com

Technical Support:
Phone: (250) 655-1766, (800) 258-3399
Fax: 508-339-8380
E-Mail: support@freschesolutions.com
Web: www.myfreschesolutions.com/catapult
Customer Portal: myfreschesolutions.com

-1-
Copyright Notice
Catapult program © 1997- 2022 Fresche Solutions.
Catapult 8.4.3 User Guide written. Copyright © 1997- 2022. All rights reserved. This document may not, in whole or part, be copied,
photocopied, reproduced, translated, or reduced to any electronic medium or machine readable form without written consent from
Fresche Solutions.

Catapult System Requirements

Poller: OS/400 V6R1M0 or higher. TCP/IP networking and an operational SMTP mail server. Operating Systems: any currently
supported Windows version. Consult the Microsoft web site for minimum system requirements for each operating system (e.g.
https://support.microsoft.com/en-us/windows/system-requirements-2f327e5a-2bae-4011-8848-58180a4353a7). If you are
processing exceptionally large spool files you may need more hard drive space.
Console: TCP/IP networking, SMTP mail server, 1024x768 screen resolution or better and a supported Windows version.

Acknowledgments
Throughout this manual reference is made to several trademarks: Catapult, WebSmart, Spool-Explorer/400, Spool-Explorer,
POLCMD, Nexus and Exodus are trademarks of Fresche Solutions Inc. IBM, AS/400, IBM i and OS/400 are trademarks of International
Business Machines. Microsoft®, Windows®, Excel® and Word® are either registered trademarks or trademarks of Microsoft
Corporation in the United States and/or other countries. Adobe®, Acrobat®, Flash® and Macromedia® are either registered
trademarks or trademarks of Adobe Systems Incorporated in the United States and/or other countries. All other trademarks are
acknowledged as the properties of their respective owners.
Blowfish implementation copyright 1997 by Paul Kocher, and used under LGPL 2.1.

-2-
About This Guide
This is the Catapult 8.4.3 User Guide. This document includes instructions for getting
started with Catapult as quickly as possible as well as reference nformation for using
Catapult on a daily basis.
Below is an overview of the contents of this guide and recommendations on how to use it
effectively.

Catapult Overviews (Short and Long Versions)

If you are new to Catapult, Chapter 1 provides a brief, introductory overview that you can
read in just a few minutes. Chapter 1 includes many screen shots and brief descriptions
of the most important features. Start here to get a quick idea of what Catapult is and how
it works before you install and configure the software.
Chapter 3, Implementing Catapult, provides a detailed overview of how the different
Catapult components work together. You should read this chapter to fully understand the
relationship between the Catapult Poller and Console. If you just want to start using
Catapult as quickly as possible, you can skip this chapter and come back to it later.

Installation Instructions
Chapter 2 includes installation instructions. You’ll need to review the instructions in this
chapter to help you configure the various Catapult components so they can
communicate with your IBM i and email server.
Chapter 19 of this guide, Catapult PC Component Configuration Options, includes
detailed descriptions of the many options you can tweak to make Catapult run as
efficiently as possible in your environment.

The Catapult Tutorial

In the next few chapters of the guide you’ll find a tutorial that walks you through creating
several Catapult grab rules. These chapters highlight the most important features in the
software and also include numerous tips for using the software efficiently.
If you learn best by working through something in a systematic way, then we encourage
you to use this tutorial. If you learn best by experimentation, then you should at least
review the first section in Chapter 4 to help you avoid any initial frustration that can come
from missing a key step right at the outset.

Troubleshooting Instructions
This guide includes two main sets of troubleshooting instructions: a basic set of steps at
the end of the first tutorial chapter and a more detailed set of instructions in Appendix C.

Catapult Reference
Following the tutorial, the guide includes reference information for all the features
available in Catapult. Use this section as you work with Catapult on a daily basis.

Catapult and Nexus

-3-
Many organizations initially purchase Catapult to fulfill a specific, narrow objective in their
operations. But in our experience, that tends to quickly change, and within a few months
of installing everyone seems to have a reason why an IBM i report (or network
document) needs to be automatically processed, converted, downloaded, saved and so
on.
If you get to this stage, you may find that Catapult is generating a dizzying amount of
material, and you may start to have concerns about how that material is organized,
secured and indexed. This need was part of the driving force behind Fresche Solutions
creation of Nexus, and particularly the Nexus component called the Enterprise Content
Manager (ECM).
The Nexus ECM provides a secure environment in which you can save, organize and
search the documents that Catapult is generating for you on a regular basis. If you
haven’t yet tried out Nexus, we recommend that you visit
https://www.bcdsoftware.com/downloads/ibm-i-solutions/?software=3 to request a free
trial.
This guide includes a reference section that describes all the options in detail.

Administrator Functions and Configuration Options

The last few chapters of the reference section include descriptions of functions that will
most likely be handled by the Catapult administrator, including configuration options,
IBM i commands, and distribution tracking tools.

Appendices
In the Appendices you’ll find further technical information about your communications
settings, as well as the more comprehensive troubleshooting guide.

Getting Help
If you have any questions about Catapult itself or how to best use this guide, please call
the Fresche Solutions Technical Support team at (800) 258-3399, or (508) 594-2700.
You can also reach us by email at support@freschesolutions.com.

-4-
Table of Contents
17
Chapter 1 - Introduction to Catapult 19
Powerful Console to Create and Maintain ’Grab’ Rules 21
Flexible Spool File Selection From Your IBM i or Network 22
Network File Distribution 22
Report Splitting 24
Extracting Report Values 25
Distribution of Files in PDF, RTF, HTML and TIF Formats 26
Hypertext Bookmarks 26
PDF File Password Protection 26
Overlay Images 27
Standard Report Title and Footer Pages 27
Automatic Email Distribution 28
Using Catapult to Archive Reports 29
Archive IBM i Reports to the Nexus Enterprise Content Manager 30
Report Printing & Faxing 31
Create Spreadsheets with Catapult and Data Extraction tool 32
Monitor the Poller Progress From Any PC 33
History List 33
Requests and Errors 33
Poller Status 33
Flexible Poller Configuration 34
On-Demand Distribution From Your IBM i 35
Chapter 2 - Installation and Configuration 36
Installation Instructions 37

-5-
 Step 1: Download Catapult and Transfer the IBM i Install Files 38
Step 2: Install the Catapult IBM i Components 41
Step 3: Start the EXODUS55 Subsystem 42
Step 4: Install the Catapult PC Components 43
Step 5: Configure Communications on Each PC and Log In 45
Log In to Catapult 47
Step 6: Configure the Catapult Poller 49
General Polling Options 49
Set the Queues to Poll 50
Configure the Email Server Information 51
Notifying the Administrator of Errors 52
Translation Options for Non-English Language Systems 53
Define a Default Printer 53
Step 7: Configure the Catapult Poller Service 55
Step 8: Install Additional Applications on the Poller PC 57
Moving On 58
Getting Help 59
Chapter 3 - Implementing Catapult 60
Overview 61
Summary List of Steps Required to Run Catapult 61
Catapult Security Considerations 61
The Catapult IBM i Component 63
The EXODUS55 Subsystem 63
Catapult and IBM i System Usage 64
Limiting the Number of Queues Polled 64
Limiting/Minimizing the Number of Spool Files Catapult Checks 65

-6-
 Polling Less Frequently 66
Using ZRUNRULE and ZDSTSPLF 66
Running the Catapult PC Components 67
The Catapult Poller 67
The Catapult Console 69
Monitoring Spool File Distribution Status 71
Chapter 4 - Creating Your First Grab Rule 75
What is the Catapult Console? 76
Starting the Catapult Console 76
The Catapult Console Window 76
Building Your First Grab Rule 78
Creating the Example Report 78
Using the Preview Window to Locate the Spool File 78
Editing the Rule 79
Reviewing the Spool File Acquisition Criteria 80
The Locate Button 82
Setting the Transformation Options 82
Distributing the Report by Email 84
Archiving a Copy as a Backup 88
Starting the Catapult Poller 91
Basic Troubleshooting Techniques 97
Checklist 97
Authority Issues 99
Checking the Error Logs 99
Chapter 5 - Adding Report Formatting and Overlays 101
Copying our Rule to Add Formatting 102

-7-
 Converting Reports to PDF Files 104
Enhancing your Adobe PDF Document 105
PDF Document Setup 105
Overriding the PDF Document Setup Defaults 107
PDF Bookmarks 109
PDF Options 113
Adding Overlay Images 115
Chapter 6 - Splitting Documents and Reports 117
How Splitting Works 118
Exercise Overview 118
Creating a New Distribution Group 119
Adding the Group Entries 119
Creating a Split Rule 122
Preliminary Changes 122
Turning on the Split Options 122
Setting Where Each Split Section Begins and Ends 123
Using the Preview Window to Set up Split Criteria 124
Identifying the Section Key Value & Location 127
Choosing a Split Section Distribution Group 128
Action for Unassigned Split Sections 129
Setting the Split Section Email Options 132
Setting the Target Address for Each Split Section 132
Setting the Split Subject 133
Setting the Email From Address 134
Attachment Options 135
Finishing Up and Testing the Rule 136

-8-
 Monitoring the Catapult Poller 138
Reviewing the Request List 138
Reviewing the History List 139
The Emails Created by the Split Rule 140
The Reports 141
Other Grab Rule Options 143
Chapter 7 - Creating Spreadsheets with Catapult & a Data Extraction tool 144
Chapter 8 - Using Catapult with Nexus 145
Downloading and Installing Nexus 146
Tutorial Instructions 146
Setting up the Nexus ECM to Receive Catapult Files 147
Logging in to Nexus 147
Creating a Catapult ECM Folder 148
ECM Administration Options 149
ECM Distribution Rules 150
Adding Nexus Options to a Catapult Grab Rule 154
Setting the Grab Rule Nexus Options 155
Checking the Distribution 156
Verifying the Existence of the Report in the Nexus ECM 157
Advanced Search Options 159
Chapter 9 - Using the Catapult Console 161
Using the Catapult Console 162
The Poller Status, Request and History Lists 163
Adjusting the List Columns 164
Working with Grab Rules 166
Grab Rule Toolbar Options 166

-9-
 Working with Grab Rule Folders 169
Working with Email Header/Footer Text 171
Working with Title and Footer Page Text 173
Designing the Pages 174
Importing & Exporting Grab Rules 175
Exporting Grab Rules 175
Importing Grab Rules 176
Chapter 10 - Working with Catapult Distribution Groups 179
The Group Summary Window 180
Creating or Changing Group Information 181
Exporting Group Entries 181
Working with Group Entries 183
Adding or Editing a Group Entry 183
Distribution Group ‘Where Used’ Information 187
Chapter 11 - Creating a New Grab Rule 189
Starting a New Rule 190
The Spool File Selection Window 190
Selecting a Sample Spool File 191
The Grab Rule Maintenance Window 192
The General Grab Rule Settings 192
Rule Expiration Options 193
Options for Securing Grab Rules 194
Chapter 12 - Setting the Grab Rule Acquisition Criteria 195
The File Acquisition Category 196
IBM i Spool File Acquisition Options 197
How the Spool File Attributes are Interpreted 197

- 10 -
 Spool File Selection Criteria 198
Page Range 198
Download Formatting 199
Spool File Translation 199
Post-Processing Actions 199
Spool File Selection Preview 201
Viewing the Selected Spool File as you Define the Grab Rule 203
Network File Acquisition Options 206
Chapter 13 - Document Splitting Options 209
Split Definition Components 210
Reviewing Split Summary Details 211
Defining the Segment Options 212
Splitting Option 212
Segment Start/End Selection 213
Using the Preview Window to Define the Values 214
Segment Anchor and Key Selection 218
Using the Preview Window to Identify the Key and Anchor Text 219
Unassigned Split Segments 222
Using &K (Current Key Value) with Report Splitting 224
Report Splitting Examples 226
Chapter 14 - Data Extraction 228
Extracting and Using Report Data Values 229
Creating Extracted Data Values 229
Using Extracted Data Values 231
Calling External Programs to Get Replacement Values 233
Examples 233

- 11 -
 Setting up your Grab Rule 234
Using the External Data Values 235
Example Program to Retrieve Database Values 235
Chapter 15 - Report Transformation Options 238
Supported File Types for Report Transformation 239
Using Your Own Extensions 239
Using the *RICH Download Format 239
Setting the Generated Document Name & Format 240
Target File Name 240
Inserting Replacement Values 241
Document Format 242
Document Setup Options 244
PDF Document Setup Options 244
Bookmarks 248
Using the Preview Window to Define Bookmarks 249
PDF File Options 251
Encryption 252
Overlay Images 254
Building Overlay Images into your Grab Rules 254
Using Overlay Images with Report Splitting 256
Example: Using a Pre-existing 8.5 x 11 Form 257
Using an Image on a Web Page 260
Using Catapult Rich Format Tags in Your Reports 261
Creating TIF Files 262
Using Title and Footer Pages in your Grab Rules 263
Creating Spreadsheets with Dat Extraction’s Batch Files 265

- 12 -
 Data Extraction’s Batch File Processing Options Reference 267
Formtastic 269
Defining Compression Options 270
Chapter 16 - Report Distribution 272
Including Additional Files 273
Emailing your Report(s) 275
Email Address Options 275
Email Subject 278
General Email Options 279
Email Body Header and Footer Text 281
Using Groups with Report Distribution and Splitting 283
Using Distribution Groups 283
Adding Key Values to Group Entries 284
Formatting Documents for Printing and Faxing 287
Printing Plain Text Documents 287
Printing PDF and RTF Documents 287
Printing Downloaded Reports 288
Important Printing Considerations 288
Printing Options 288
Printing Split Sections 290
Faxing Documents 291
Faxing Split Sections 292
Adding Fax Services to the Poller PC 293
Configuring the Fax Services 293
Distributing Reports to Nexus Portal 298
Setting the Grab Rule Nexus Options 298

- 13 -
 How the Search is Processed 300
Archiving Downloaded Documents 301
Chapter 17 - Report Distribution and Tracking Options 305
The Console’s Poller Status Tab 306
Browsing Pending Requests and Request Errors 308
Browsing the History List of Successful Downloads 313
Triggering an Immediate Poll 315
Establishing a New IBM i Connection 316
Using the Catapult Launchpad 317
Catapult Launchpad Configuration Options 317
Chapter 18 - Controlling the Poller from IBM i Jobs 319
Using the ZDSTSPLF (Distribute Spool File) Command 320
ZDSTSPLF Parameter Reference 320
How the ZDSTSPLF Distribution Process Works 325
Using the ZRUNRULE (Run Rule) Command 326
ZRUNRULE Parameter Reference 326
How the ZRUNRULE Distribution Process Works 329
Using the ZRUNNETRUL (Run Net Rule) Command 330
ZRUNNETRUL Parameter Reference 330
Initiating a Poller Cycle with ZPOLLNOW 332
Using the ZPOLLEND (Poller End) Command 332
Chapter 19 - Catapult PC Component Configuration Options 333
Catapult Communications Configuration 334
Adding and Configuring Connections 335
Logging In to Catapult 336
Catapult Console Configuration Options 337

- 14 -
 General Console Options 337
Rule Editor Defaults 338
Console Columns 340
Console Messages 341
Email Options 342
Configuring the Catapult Poller 345
General Polling Settings 345
Selecting Queues to Poll 347
Configuring the Email Server Information 348
Email Administration Options: Error Notification 350
Other Miscellaneous Email Options 351
Advanced Poller Configuration Options 354
Document Generation Settings 356
Printer Configuration Options 358
Cache Directories 360
Poller Diagnostic Settings 361
Appendix A Communications Considerations 366
Installing TCP/IP Protocol Support 367
Manually Configuring the IBM i for TCP/IP Support 367
How the EXODUS55 Subsystem Works 367
Configuration Options for TCP/IP 369
The ZCFGTCP (Configure TCP/IP) Command 369
The ZDSPERRLOG (Display Error Log) Command 370
Security Considerations 371
Appendix B - Rich Text Formatting Options Reference 372
An Example Using Rich Text Formatting Tags 374

- 15 -
 Using Bar Code Fonts in Rich Text Format Tags 381
Example Report Implementing a RTF Barcode Font Tag 381
Appendix C - Catapult Troubleshooting Guide 384
Checking the Error Logs 385
General PC Connection Errors 387
When Catapult won’t Connect to the IBM i 388
Detailed Communications Troubleshooting Process 389
Troubleshooting Fatal Catapult Poller Errors 391
General IBM i Connection Errors: 392
What to Do When a Grab Rule Doesn't Grab 393
What to Do When a Split Doesn't Split 395
Troubleshooting Printing Issues 398
Troubleshooting Batch File Processing 400
General Troubleshooting Issues 402
Sending Spool Files (Primarily to Tech Support) 406
Importing Spool Files 407

- 16 -
- 17 -
 SECTION I
Introduction & Installation
In this Section:
Chapter 1 - Introduction to Catapult
Chapter 2 - Installation and Configuration
Chapter 3 - Implementing Catapult

- 18 -
 - Introduction to Catapult

CHAPTER 1

Chapter 1 - Introduction to Catapult

Catapult is a PC and IBM i automated report distribution tool. You can use Catapult to
perform the following functions within your organization:
□ Automatically Distribute IBM i (and other) Reports. Catapult periodically
scans selected IBM i output queues and other network directories looking for
spool files or documents matching the selection criteria you define in your ‘grab’
(distribution) rules.
□ Improve the Quality of your IBM i Reports. Use Catapult to automatically
rebuild your IBM i reports as feature-rich PDF, RTF and HTML documents. With
Catapult you can override the standard report attributes as well as add
bookmarks, form overlays, password protection, additional header and footer
files, and more.
□ Parse or Split Spool Files Before Distribution. With Catapult’s flexible parsing
and splitting capabilities you can easily break long complex reports into sections,
based on key values you identify in the report body. You can then link the key
values to users in your distribution lists, to automatically send each person just
the section of the report that is relevant to them.
□ Combine Catapult with a Data Extraction tool to Extract Report Data. With a
Data Extraction tool you can easily extract data from your reports. You can then
distribute that data as a comma delimited file (CSV), or in any of several popular
spreadsheet formats including Microsoft Excel®. Your report models can be very
simple (grabbing just data fields), or you can also add calculations, graphs and
summary views.
□ Distribute Reports by Email, Print and Fax–Or Save to a Server. Once you
have applied all your formatting options to the spool files you selected, Catapult
can automatically distribute your reports by email, fax or print, or you can have
Catapult archive the reports on a file server. Additionally, Catapult integrates
with the Nexus Enterprise Content Manager (ECM) so you can easily provide
secure, on-line access to your documents in a browser.
All of these features, and many more, can be combined together in a single distribution
rule, to provide a total Executive Information System solution.

- 19 -
The following sections of this chapter provide an overview of the most important areas
you should be familiar with.

- 20 -
Powerful Console to Create and Maintain ’Grab’ Rules
The Catapult Console is the PC application you use to preview spool files, define grab
rules and create distribution lists. From the console you can also track the activity of the
Catapult Poller, which handles processing and distributing the selected spool files. There
are also options for setting up standardized email headers and footers, and creating
default document title and footer pages.
Below is an illustration of the Catapult Console after creating several grab rules in a
number of folders:

Figure 1-1. The Catapult Console, displaying several folders and grab rules.

Because your grab rules are stored on the IBM i you can install the console on any PC
with a connection to your server. The console is secure, requiring an IBM i user profile
sign in. To supplement this standard security you can also add additional layers of
security to individual grab rules, restricting access to particular IBM i users or user
groups.
Your grab rules are organized into folders, and each user can include the columns of
grab rule information they find most useful.

- 21 -
Flexible Spool File Selection From Your IBM i or Network
When you use Catapult you begin by creating ‘grab rules’ in which you define your
acquisition criteria. This criteria determines which IBM i spool files qualify for distribution.
The grab rules allow you to define spool file selection criteria based on User ID, Job
Name, Spool File Name, Forms Type, User Data value and Output Queue name; or any
combination of these attributes.
Below is an illustration of the window presented for defining your selection criteria:

Figure 1-2. Selection and basic formatting options.

The Catapult Poller runs continually on a server PC scanning your output queues for new
entries that qualify for selection based on the grab rules you have defined. Figure 1-2
shows a grab rule called 'Monthly Invoice Distribution' that selects reports based on the
spool file user data in a particular queue.
Your selection criteria can include as few or many values as necessary to uniquely
identify the correct spool file(s) to be selected. You can also use wildcard values for the
spool file attributes.

Network File Distribution

You can also take advantage of Catapult’s automated distribution options to scan folders
on your network, using these options:

- 22 -
Figure 1-3. Catapult network polling options.

These ‘network’ files can be of any type, and if they are in plain text format with a
consistent layout you can also take advantage of all of Catapult’s report formatting
options.
This feature requires that the network folder(s) be accessible via their UNC name.

- 23 -
Report Splitting
With Catapult you can set breakpoints in your downloaded reports to split them into
sections which can then be individually distributed.
Here is an illustration where we are setting up the split criteria in a grab rule:

Figure 1-4. Setting up report splitting in your grab rule.

To define the criteria that your grab rule will use to split your report you’ll use the preview
window shown below in Figure 1-5. In the preview window you can locate and select text
constants and key values that the Catapult Poller will search for as it processes your
report.
In addition, the key values in each split section can be cross-referenced to a distribution
group or extracted directly from the report itself. This means, for example, that you can
split a report by sales area and then use your distribution group link to an individual
responsible for that area. You can also use your split criteria to save portions of the
report in different folders on your server.

- 24 -
Extracting Report Values
Catapult also allows you to extract values from your reports which you can then use in
other areas of your grab rule definition. For example, you can set up your distribution
rules to pick up email addresses or subjects from the body of the report section that
recipient needs to get.
To define extracted values you’ll first download a sample of your report into this preview
window:

Figure 1-5. The spool file preview window.

From this window you will define your extracted values by identifying their location and
dimensions on the report, and then assign them a value name and replacement token.
You can then use that replacement token in other areas of your grab rule definition.

- 25 -
Distribution of Files in PDF, RTF, HTML and TIF Formats
Just because most of your IBM i reports are plain, unformatted data doesn’t mean you
have to distribute them that way. Catapult allows you to convert spool files to PDF, RTF
and HTML documents before distribution. When you do this you can add custom font
and printer settings and other attributes related to the format you choose. If you have
any AFPDS IBM i reports you can retain their appearance by distributing them as TIF
files.
Here is an illustration of some of the options that become available when you choose to
distribute spool files using one of the alternate formats, such as PDF:

Figure 1-6. Document setup options when generating report PDFs.

When you generate PDF, RTF and HTML documents Catapult retains any embedded
bolding, underlining or overprint attributes in your reports, and for these document
formats even includes a font to correctly render bar codes.

Hypertext Bookmarks
Your PDF and HTML files can be made more accessible with the creation of bookmark
links to the headings and key values in your report.

PDF File Password Protection

When you generate PDF files, you can add security to them by requiring a password to
open the file. You can even set individual passwords for each section of a document you
send, based on variables in the report body.

- 26 -
Overlay Images
As you can see in one of the categories in the area indicated in Figure 1-6 above,
Catapult allows you to download reports and merge them with your existing forms, such
as letterhead, invoices, etc. To do this, all you have to do is select the background image
(s) you want to use for each section of your report. This feature can be used in
conjunction with report splitting to easily distribute your invoices by email as PDF files, for
example.
The report formatting and overlay features are particularly useful when you intend to
distribute your reports by fax or printer, as they allow you to take plain IBM i data and
automatically create great looking hard copy documents.

Standard Report Title and Footer Pages

Most of the distribution formats also support the ability to attach extra text to the
beginning or end of the report. You can use these options to add extra explanations to
your email, or standard disclaimers that are pulled from an external file.

- 27 -
Automatic Email Distribution
When you build a Catapult grab rule to select a report you can email it to a single email
address or many. Depending on the distribution format you choose, you can include the
generated document in either the email body or as an attached file. For example, you
could set up Catapult to look for new spool files every 10 minutes, select qualifying
entries, then email them as PDF files. To simplify sending reports to many recipients you
can define Distribution Groups with any number of members.
Here is an illustration of the email options:

Figure 1-7. Email options in a Catapult grab rule that splits a report.

From here you can specify your email subject. The subject can be a static text string or
use replacement values extracted from the spool file attributes or the body of the report
itself. You can also select groups and individuals to be copied and blind copied on the
report. Catapult also allows you to control how multiple attachments are handled,
optionally combining multiple attachments to the same recipient.

- 28 -
Using Catapult to Archive Reports
You can also use Catapult as an archiving facility and download your reports as PC files
to a server. Grab rules allow you to generate new PC file names and supports several
different ways of ensuring your file names are all unique.
Here is an illustration of the options available for archiving split sections:

Figure 1-8. Using Catapult to archive reports to a server.

You can even use the replacement values to create new, uniquely named folders on
your server for each iteration of the report that you download.

- 29 -
Archive IBM i Reports to the Nexus Enterprise Content Manager
Another archiving alternative with Catapult is to set up your grab rules to distribute
documents to the Nexus ECM. Nexus is Fresche Solutions Award Winning knowledge
management tool. Nexus is designed to make maintaining and managing corporate
Intranet or Internet sites easy. It allows you to implement site-wide security, determine
an overall look and feel for all pages, provide a 'portal' or common launching pad for all
pages and applications, and to provide value-added features such as calendars,
navigation menu trees, etc.
Catapult supports the ability to create grab rules that automatically populate the Nexus
ECM, instantly making reports available to all authorized users in a secure environment.
Here is an example of some reports that Catapult has created in the Nexus demo site’s
ECM:

Figure 1-9. Some Catapult reports in the Nexus ECM.

In this illustration, all the reports in the box came from Catapult, and the user has clicked
on the first PDF link indicated by the arrow.

- 30 -
Report Printing & Faxing
You can also define grab rule options to print your entire report, or selected sections.
Just as you can use distribution group entries to email selected report sections, you can
also associate a group with your printing options to print only particular report sections.
Here is an illustration of the grab rule print options:

Figure 1-10. Catapult grab rule print options.

From here you can choose a particular printer on your network (using the dropdown list)
or print to a distribution group, where the target printer can be retrieved from your
recipient’s profiles.

Faxing
Using options similar to those available for printing, Catapult also allows you to fax your
spool files to one or more recipients. You can extract the fax numbers from the
distribution lists or from the report itself. In addition, you can also leverage the report
parsing and splitting functions to break your spool file into sections that can be faxed to
different people.

- 31 -
Create Spreadsheets with Catapult and Data Extraction tool
Using a Data Extraction tool you can filter out any set of data from a report and format it
for use in other PC applications, such as Excel. You can also create new reports, charts
or graphs.
Here is an illustration of an Excel® spreadsheet created using Catapult a Data Extraction
tool:

Figure 1-11. Using Catapult with a Data Extraction tool to create spreadsheets.

Chapter 7 of the tutorial section of this guide, Creating Spreadsheets with Catapult & a
Data Extraction tool, includes a detailed guide to setting up automated processes for
extracting report data and exporting to Excel® (and many other popular spreadsheet
formats).

- 32 -
Monitor the Poller Progress From Any PC
While the Catapult Poller is installed on a single PC on your network, you can install the
console on any number of PCs. From the console you have access to several different
tools to control and monitor the progress of your polling cycles, including the status of
individual distribution records.

History List
From the Catapult Console you can display a history list of all distribution records. You
can expand individual records to verify that all the necessary steps were taken for each
distribution request.

Requests and Errors

The requests and errors list is similar to the history list. Here is where you can see a log of
the main actions performed for each distribution request as they happen, as well as
monitor for any errors. You can correct errors and re-initiate processes to ensure a
successful distribution of all reports.

Poller Status
From the console you can also display the poller status, where you’ll see a running log of
messages as the poller processes the distribution list.

- 33 -
Flexible Poller Configuration
The Catapult Poller supports numerous options that allow you to fine-tune its
performance on your system. Even if you have many thousands or millions of spool files
on your system, you can easily choose which queues to process, and after processing,
move processed spool files to archival queues.
Here is an illustration of the Catapult Poller’s configuration screens, where we have
selected just a few of our queues to poll:

Figure 1-12. Configuring the queues to poll.

While Catapult’s default settings usually work fine ‘out of the box’, so to speak, the poller
does support a wide array of configuration options to give you control of almost every
facet of the spool file processing and distribution process.

- 34 -
On-Demand Distribution From Your IBM i
Finally, Catapult includes IBM i commands that allow you to select a spool file to
distribute immediately. This provides on-demand capabilities for archiving or emailing
reports. You can run these commands from a command line, or directly embed them in
CL programs.

- 35 -
 i agree - Installation and Configuration

CHAPTER 2

Chapter 2 - Installation and Configuration

Note: These instructions are for Catapult 8.4.3 and higher. This chapter describes
how to install and configure Catapult. In addition to the required settings described here
there are many other PC and IBM i configuration options you can use to fine-tune
Catapult’s performance. These are described in Catapult PC Component Configuration
Options.
These instructions are for new installations only. If you are upgrading from a previous
release, or plan to install Catapult 8.4.3 alongside an older version, use the installation
instructions in the Upgrader’s Guide.

- 36 -
Installation Instructions
Catapult includes several components:
1. An IBM i component, consisting of these libraries:
● XL_CATAPLT. This is the Catapult product library.
● XL_EX55. The Client/Server communications library.
● XL_CATINST. This is the Catapult installation library. You can delete this
library after installing the software.
2. A PC component called the Catapult Console. This is a Windows application
for creating and maintaining your grab rules, and working with report
distribution records.
3. A second PC component, the Catapult Poller, which periodically polls your
IBM i for spool files matching the grab rule criteria, to distribute them.
The Catapult Launchpad is also included on every PC to provide access to the poller
status window and other PC options and components.

- 37 -
Step 1: Download Catapult and Transfer the IBM i Install Files
Follow these steps to download the installation files and transfer the server component to
your IBM i:
All product downloads and documentation can be accessed from the Fresche Solutions
Customer Portal. If you do not have an account you can Request an Account from the
login page: https://www.myfreschesolutions.com.
For Documentation:
Select Documentation and then Catapult.
For Downloads:
Select Downloads, Current Downloads, Under Business Intelligence select Catapult.
At the bottom Select Go to Software Download
When the Fresche Solutions Software Downloads window appears select Download IBM
i Component or Download PC Component
The files to use will be in the downloads folder.
When the downloads finish double-click the IBM i install executable file cat+spx8.4.0-
ibmi.exe [the version may vary]. This will unpack the files and begin transferring them to
your IBM i.
When the window below appears, enter your IBM i IP address or domain and user
profile/password:

Figure 2-1. The upload utility presented when you execute the IBM i install file.

Click the Upload button. When the upload finishes the activity log displays the
message ‘File upload complete’. You can then close the Fresche Upload
Express window shown above.

- 38 -
 If the window above doesn’t appear automatically execute the
file install.exe from the folder to which you unpacked the
Catapult download. If you get an FTP transfer error, please visit
our Knowledge base and search for the error you encountered.
You may need to adjust the FTP settings on your IBM i.

When the file transfer finishes you can close the Fresche Upload Express window shown
above.

Step 1: End the Exodus51 Subsystem

Catapult uses a communications middleware component to transfer data between the
IBM i and PCs at different times while you are working with the application. This
component is also used by Fresche Solutions WebSmart, Presto and Spool-
Explorer/400.
□ Until Catapult 8.1.0 the communications middleware component was called
EXODUS51 (in library XL_EX51).
□ At release 8.1.0 and higher, the communication middleware component is called
EXODUS55 (in library XL_EX55).

Check for Active Exodus Jobs

The new installation of EXODUS55 should automatically end EXODUS51 if it’s currently
running. However, before installing Catapult 8.4.3, you need to make sure that there are
no EXODUS51 jobs running, to avoid locks on objects that need to be updated or replaced:
□ At an IBM i session, run the WRKACTJOB command and check whether there’s an
active subsystem called EXODUS51. If the subsystem is not active, continue with
the next install step.
□ If the EXODUS51 subsystem is active, someone may be working with an application
using them. To see a list of these jobs, check for object locks with the command
WRKOBJLCK on the libraries XL_EX51. Contact the owners of these jobs to request
that they end their connections, or you can end them yourself.
After ending all EXODUS51 jobs, you can run the following command to end the subsystem:
ENDSBS EXODUS51

Then continue with the next step.

The Catapult communications jobs are started as user

EXODUS55, and then changed to the user logging in. As a
result, the poller job runs with the job description for
EXODUS55.

This may be relevant to you if any of your Catapult rules use

external call out programs in specific libraries in a particular
user’s initial library list.

- 39 -
Changes to EXODUS51 Port
The default EXODUS55 port is 4015. The install changes the
EXODUS51 port to 4016 to prevent a port conflict if EXODUS51 is
started.

- 40 -
Step 2: Install the Catapult IBM i Components
Follow the instructions below to install the Catapult IBM i components.
1. Log on to an IBM i session and execute the command XL_CATINST/CATINSTALL.
2. The process will begin by creating the Exodus subsystem.
3. Then the IBM i install will prompt you for a library to install to:

Figure 2-2. Selecting your Catapult library (note that the release may vary).

4. For your first install accept the default option of XL_CATAPLT.

If you are upgrading from a previous release or want to run

multiple versions of Catapult concurrently, refer to the
instructions in the Upgrader’s Guide.

5. As the last step in the install you can enter the license key provided to you by
Fresche Solutions. If you have not yet received your license key, phone
Fresche Solutions at (630) 986-0800 or email sales@freschesolutions.com.
You can enter your license key after finishing the install by adding XL_CATAPLT to the library
list and running the UNLOCKCAT command.
Continue with the next step.

- 41 -
Step 3: Start the EXODUS55 Subsystem
Catapult uses a subsystem named EXODUS55 to manage transferring data between the PC
and IBM i components.
When the server side installation finishes run the WRKACTJOB command to check if the
EXODUS55 subsystem is running. If this is a new install, it should be started automatically.

If this is a second install, or you already have another Fresche Solutions tool installed on
your system that uses EXODUS55, the install will not start the subsystem automatically. You
can start the subsystem at this point using this command:
STRSBS XL_EX55/EXODUS55

Once the subsystem has started continue to the next step.

Port 4015. The default EXODUS55 port is 4015. If you’re using

a different port, you can change the default port of incoming
connections using the XL_EX55/ZCFGTCP command (press F4
to prompt the command, and press Enter).
If you change this port number, restart the EXODUS55
subsystem.

Starting the EXODUS55 Subsystem After an IPL

If you IPL your IBM i nightly or on the weekends, you need to

also restart TCP/IP services and the EXODUS55 subsystem.
While you probably already have processes in place to
restart TCP/IP, you can add the command STRSBS XL_
EX55/EXODUS55 as part of that process (while you are
evaluating the software you may elect to just run it
manually). The EXODUS55 subsystem contains an auto-start
job that runs constantly to monitor and dispatch EXODUS55
conversations to the appropriate server programs.

- 42 -
Step 4: Install the Catapult PC Components
Catapult has two main PC components:
□ The Catapult Poller is responsible for polling the IBM i at regular time intervals to
determine whether any spool files are found which match your grab rule criteria.
Ultimately, we recommend that you install the poller on a dedicated PC. But while
you are evaluating the software and workloads are low you can run it on your
own PC. Keep in mind that report distribution is delayed if you turn your PC off.
□ The second PC component is the Catapult Console, which you will use to create
and maintain your spool file selection rules as well as to monitor the status of
your requests. Catapult selection rules are stored on the IBM i so you can install
the console on any number of PCs.
The Catapult Launchpad is a small utility installed on every PC, from which you can
launch the other Catapult components and tools installed on the PC.
You have to configure the PC-side communications for each machine on which you
install any PC component.

Catapult 8 requires that the Microsoft .NET Framework

4.0 be installed on your PC. If you do not have this version
on your PC you need to complete the steps to install it on
your PC before the Catapult 8 install can be completed.
Follow the Microsoft prompts to complete this process.
Because the .NET Framework 4.0 is considered by Microsoft
to be an optional update it’s possible that you won’t yet have
it on your PC. This is a large file and may take some time
both to download and install the first time. Subsequent
Catapult installs and updates should only take a few
seconds.
For more information, please visit http://www.microsoft.com
and search for “.NET Framework 4.0”.

Installing the PC Components

Follow the steps below to install Catapult on your PC:
All product downloads and documentation can be accessed from the Fresche Solutions
Customer Portal. If you do not have an account you can Request an Account from the
login page: https://www.myfreschesolutions.com.
For Documentation:
Select Documentation and then Catapult.
For Downloads:
Select Downloads, Current Downloads, Under Business Intelligence select Catapult.
At the bottom Select Go to Software Download

- 43 -
When the Fresche Solutions Software Downloads window appears select Download IBM
i Component or Download PC Component
The files to use will be in the downloads folder.
When the download finishes double-click the downloaded file to unpack the install files
and initiate the install. The PC install file is named catapult8xx-pc.exe [the version
number may vary].
Follow the on-screen instructions. During the install, you are prompted to select the
components you need:

Figure 2-3. Selecting the PC Catapult PC components to install.

You must install at least one instance of each component. Use the following
guidelines in selecting the components to install:
● While evaluating the software, the simple option is to initially install both
components on your PC.
● If you are setting up a dedicated PC on which to run the Catapult Poller,
make sure you select the Poller (as shown above).
● If you have already installed the Catapult Poller on another machine then
you probably only need the Console.
Click Next to continue.
6. During this part of the installation you may be prompted to install the .NET
Framework 4.0.
Follow the instructions from the prompt. See the alert box at the beginning of
these instructions for additional details.
7. When the installation is complete, you may be prompted to either reboot your
PC (if you had to install the .NET Framework) or to run the software (if your PC
already had the .NET Framework installed).
8. If you are prompted to reboot, after rebooting launch Catapult from your Start
menu (search for Catapult Launchpad).
Then continue with the instructions in the next step.

- 44 -
Step 5: Configure Communications on Each PC and Log In
After installing any Catapult PC component you need to configure communications
between the PC and IBM i components. On completion of the steps on the previous
page, when you attempt to run Catapult for the first time the software will display this
message:

Figure 2-4. Prompt to define a connection from your PC to your IBM i.

Click OK to define the settings for your IBM i.

f you don't see this window, start the Catapult Console from the
Catapult Launchpad. The Console checks whether you have a
valid connection, and if not, prompts you to add one.

This window appears next:

Figure 2-5. The Catapult Connection options (Communications Configuration).

Enter the following values:

□ Name. Catapult displays this description at the various locations from which you
can establish connections.
□ Environment Library. The default value is XL_CATAPLT.
□ Target IP/Domain. Enter your IBM i IP address or domain name.
□ Port. Unless by some remote coincidence you already have an application
listening on port 4015, the default value of 4015 will work for you.

- 45 -
 □ Local IP to Use. In some situations (such as connecting via a VPN), your PC
may have two separate local IP addresses. Select the one you need to use. See
the help box below for details.
□ IBM i Profile. Enter your IBM i User ID and password here so you don’t have to
enter them every time you connect. You also need values here to run the polling
instances on the system.
Use the Test Connection button to confirm your settings, and you should get a positive
confirmation message.

Here are a couple of things to check if you don’t get a successful

connection:
□ EXODUS55 subsystem is not active. The most
common connection error (10061) is caused by the
EXODUS55 subsystem not being active. If you get this error,
run the WRKACTJOB command and check whether the
EXODUS55 subsystem is running and contains a job called
EXSERVER. If the subsystem isn’t started, run the command
STRSBS XL_EX55/EXODUS55. If the subsystem is running but
EXSERVER is not, end and restart the subsystem and confirm
the job is added. Then try connecting again.
□ Other connection errors. If the subsystem is up but you
can’t connect, add XL_EX55 to the library list of your IBM i
session and run the command ZDSPERRLOG to display a list
of your connection attempts. Check for error messages
(such as invalid User IDs, etc.).
□ V6R1 and Port 4015. If you are at V6R1 or higher use
port 4015 or another of your choosing. If you need to
change the port number, you must also run the XL_
EX55/ZCFGTCP command to change your IBM i-side
communication (press F4 to prompt the command). After
making this change, end and restart the EXODUS55
subsystem.
□ Multiple Local IP addresses. If your PC has multiple
local IP addresses (e.g. you have two NICs, or are
connecting via a VPN) you need to select the local IP that
is on the same subnet as your IBM i. It also needs to be a
static IP address. The connection won’t work using the
wrong local IP.
If you can’t spot the problem immediately please call the
Fresche Solutions Technical Support team at (800) 258-3399, or
(508) 594-2700. You can also reach us by email at
support@freschesolutions.com.

After testing your connection, click OK (Figure 2-5) to save your connection and present
the Communications Configuration window:

- 46 -
 Figure 2-6. Catapult Communications Configuration window.

You can also launch the Communications Configuration from

your Start menu - just search for it.

Security and Messaging Options

Click the Remember Session Password option (shown above) so that Catapult does not
prompt you to sign in every time it establishes a connection to the IBM i. Click the Apply
button afterwards.

The options above are described in more detail in the

section “Catapult Communications Configuration” on
page 334 

Log In to Catapult
Click OK once more from Communications Configuration to present the Catapult
Console login (this will depend on how you set up your connection):

Figure 2-7. The Catapult Login window, presented when you launch any component.

- 47 -
Enter your IBM i profile and password to launch the console. If you successfully log in, it
means your license key was current and valid.
If this is a new install, the Catapult Console should initially look like this:

Figure 2-8. The Catapult Console, with no grab rules defined.

Now you’re ready to continue with the next section, to set up the Catapult Poller.

- 48 -
Step 6: Configure the Catapult Poller
This step is only required on the PC where you have installed the Catapult Poller.
The Catapult Poller is the PC-based application used to download and distribute your
reports. You need to configure and start the poller before Catapult can distribute any
reports. This section includes instructions on how to set basic poller configuration options
to get you up and running. For further details on configuring the Catapult Poller, please
refer to the section “Configuring the Catapult Poller” on page 345 . There are many
options available to fine-tune the poller’s performance.

You can also follow the instructions in the Catapult

Upgrader’s Guide to install multiple versions.

Start the Poller Configuration from the Catapult Launchpad, or by searching for it at your
Start menu.
This is the Poller Configuration:

Figure 2-9. The Catapult Poller Configuration utility, showing the default options.

General Polling Options

When you first install it, the Catapult Poller is configured as follows:
□ To be started manually. The poller will wait for you to start it.

- 49 -
 □ To poll periodically, every 10 minutes. You may adjust your polling cycle
intervals according to your PC and IBM i resource usage.
If you are installing Catapult for the first time, and have only a few simple rules looking at
a test queue with just a few spool files, you can set it to poll every minute or two. If you
have many complex rules processing hundreds or thousands of reports, and queues
with many thousands of spool files in them, you may want to poll less frequently.

Network Acquisition Default Profile

You will need to fill out these options if you plan to create grab rules to retrieve network
files from a location that the main Windows profile running the poller doesn’t have access
to.
For example, the main profile might not have access to financial information on a
network share, but a superuser who has created rules to grab that file may enter their
login information either here or in an individual grab rule.

Set the Queues to Poll

When you first install the software Catapult by default polls every queue on your system.
To make the software run most efficiently you should specify a subset of queues to poll:

Figure 2-10. Configuring the polled and omitted queues.

Select and move (using the arrows between the lists) to the Selected Out Queues list any
queues containing spool files that you will process and distribute with Catapult.

- 50 -
 When you are first getting started make double sure you are polling
all the necessary queues. In our experience in Technical Support,
over-enthusiastic queue culling is one of the main reasons for
otherwise correct grab rules not producing any results. But if you do
have queues with thousands of old, archived spool files, you can
leave those in the list of omitted queues.

Configure the Email Server Information

One of Catapult's primary functions is to distribute spool files by email. To do this you
must provide Catapult with the IP address for your organization's email server. You also
need to specify the email server information so you can be notified of any errors
encountered when processing your spool files.
To configure the email server information, click on the Email menu entry. These are the
main options:

Figure 2-11. The Email Server settings in the Catapult Poller configuration.

Distribution Email ‘From’ Details

These are default values used by Catapult. You can override these in your individual
grab rules.

Server Information

- 51 -
 Type the IP address and port to use to connect to your email server. If you don’t know
these values, contact your network administrator. The default port number of 25 is
standard and generally works.

SMTP Authentication
Some SMTP servers require that a valid User ID and password be provided by any
application attempting to send an email. In many cases, this type of validation is only in
effect for external email. If your email server is rejecting the email you are sending with
Catapult, or not sending any messages outside your network, you should check whether
this option is required. If so, enter the appropriate values above.

Notifying the Administrator of Errors

You should initially set the poller to notify you any time it runs into an error of any kind.
Keep this setting while you are first getting started and until you have created at least a
few working grab rules and are familiar with how the software works. This will help you
identify any initial problems in your grab rule definitions or poller configuration.
These are a few typical situations where you may encounter errors:
□ During attempts to distribute email, usually due to email server configuration
issues.
□ When the poller is trying to create PDF/RTF/HTML documents, usually due to
formatting conflicts.
□ When the poller is trying to save documents to network drives, usually due to
user profile authority issues.
Go to the Administrator Email options and select the ‘Notify on any error’ option, shown
below. Then type your name and email address below that:

- 52 -
 Figure 2-12. The Catapult Poller error notification (administration) settings.

If you like you can also change the default email subjects, though the defaults will work
fine.

Translation Options for Non-English Language Systems

If your IBM i is configured for any language other than English, you should set up the
translation options accordingly, in the Advanced Configuration options:

Figure 2-13. Catapult Poller translation options, for non-English language systems.

You can find the necessary CCSID values on your IBM i using the command DSPSYSVAL
(QCHRID).

Define a Default Printer

If you plan to use your grab rules to automatically print spool files you should also
establish a default printer. If you will not use Catapult to automatically print hardcopy
reports you can skip this option.
To set a default printer begin by clicking the Printing Options, shown below:

- 53 -
Figure 2-14. Poller configuration printing options.

Use the dropdown list to select a default printer to use in your grab rules. The option to
load the network printers at startup is not initially selected when you first install Catapult,
so if you want to select a network printer as your default, click on the Get Network
Printers button.
Once the list of printers has been populated, click on the ‘Update Printers’ button to save
the list to your IBM i. This list is used by the poller and also by other console jobs when
defining grab rules.

Additional Poller Configuration Options

There are many other poller configuration options, but the ones described above should
be enough to get you up and running.
For details on all the remaining options, please refer to the reference section of this
guide. There are a number of other options you may find useful.

- 54 -
Step 7: Configure the Catapult Poller Service
These steps are required to avoid problems with the following types of grab rules:
□ Grab rules configured to automatically print reports.
□ Grab rules designed to access network resources, such as files to attach to
emails, or graphical overlays.
□ Grab rules designed to archive reports to network directories.
In summary, configuring the Catapult Poller service according to the following
instructions will give you predictable network access to supporting resources.
Step 1: Launch the Start/Run window.
On the Catapult Poller PC, go to your Start menu and open the Run... window. Type
‘services.msc’:

Figure 2-15. Launching the Windows services configuration tool

Click the OK button.

Step 2: Find and double-click the Catapult 8 Service option.
In the list of services running on the PC, find the service named ‘Catapult 8 Service’:

Figure 2-16. Finding the Catapult 8 Service on your PC.

- 55 -
When you find the entry shown above, double-click it.
Step 3: Add a Log On profile.
In the Catapult 8 Service Properties window, go to the Log On tab and enter your
network ID and password (this is for your network, NOT the IBM i):

Figure 2-17. Entering the service Log On ID and password.

The account name needs to be entered according to the following criteria:

□ If you are using a non-domain machine with an operating system such as XP
Home, enter the account in the format “.\PROFILE” (for example, .\jsmith).
□ If you are using a machine (such as a Windows 2003 or XP Pro box) that is part
of an existing domain and you wish to use a domain profile for authority use this
format: “DOMAIN\PROFILE” (e.g. ALPHA\jsmith).
Use a network profile that will have authority to all the folders and printers Catapult would
normally need to access, including authority to create and delete files and directories.
When you finish this step, click Apply, then OK.
Step 4: Verify your change.
When you click OK above, you should return to your list of services, where the profile you
entered above should be shown in the ‘Log On As’ column.
Then close the Services window.

- 56 -
Step 8: Install Additional Applications on the Poller PC
This step is only required if you create rules that automatically create, then print or
fax, PDF or RTF documents.
Among Catapult’s features is the ability to convert spool files to various other formats.
These formats include:
□ PDF (Portable Document Format). This is intended to be opened with either
the free Adobe® Reader® which is now found on most PCs, or Adobe Acrobat®.
Note that in many cases, our customers have had better results from using the
Foxit Reader than with Adobe’s.
□ RTF (Rich Text Format). This format can be opened with WordPad and a
number of other applications, but in practice is mainly used to generate
documents intended to be opened or printed with Microsoft Word®. Some
features of the RTF files created by Catapult (such as form overlays) are
supported only in Word.
If you anticipate creating grab rules to automatically download and print or fax
documents in RTF or PDF format, the appropriate supporting applications have to be
installed on the Catapult Poller PC and the file associations defined.
See the section “Troubleshooting Printing Issues” on page 398 for further details.

- 57 -
Moving On
You have now finished installing and configuring Catapult.
To continue, we recommend that you go through the tutorial section of the User Guide.

In the tutorials, the one critical step you will need to complete
is starting the Catapult Poller. This is described in the section
“Starting the Catapult Poller” on page 91 .

Ideally, you should work through the tutorial, creating your own grab rules as you go.
However, even browsing through it quickly will be helpful.

Live and Recorded Web Demos

The Fresche Solutions Technical Support team also conducts free Live Web Demos and
has Getting Started Webinars for all our software products available at our web site.
If you would like an interactive demo of how to use Catapult please contact your sales
representative at Fresche Solutions to schedule a convenient time, or visit our website to
view a pre-recorded webinar.

- 58 -
Getting Help
If you have any questions about the install or run into difficulties during any part of the
process please call the Fresche Solutions Technical Support team at (800) 258-3399, or
(508) 594-2700. You can also reach us by email at support@freschesolutions.com.
You can also search the extensive Knowledge Base on the Customer Portal at
myfreschesolutions.com.
We aim to have the best technical support in any business. If you phone us, your call will
be immediately picked up by a member of our technical team who can assist you on the
spot.

- 59 -
 - Implementing Catapult

CHAPTER 3

Chapter 3 - Implementing Catapult

In the previous chapter you installed and configured Catapult on your PC(s) and IBM i.
This chapter presents an overview of how the various Catapult components work
individually and together. It also discusses a number of issues that arise in the daily
usage and administration of Catapult. There is some overlap between this chapter and
the following ones where all the features are described in detail, so other sections of the
guide are referenced wherever pertinent.
If you want to immediately start building grab rules and distributing files you can skip to
and revisit this section later.

Catapult also includes a number of IBM i commands which

allow you to initiate the distribution of a report directly from the
IBM i. For many applications this is actually the most efficient
way to use the software: embed commands directly into your
CL programs to instantly trigger distribution rules and
processes for individual reports without the overhead of
initiating a complete polling cycle.
These commands are discussed in the section “Using
ZRUNRULE and ZDSTSPLF” on page 66.

- 60 -
Overview
Catapult has three main components:
□ The IBM i server component stores grab rules, distribution requests, history
entries, distribution lists and other data.
□ The Catapult Poller controls when the IBM i is scanned for spool files matching
the selection criteria. The poller also handles the formatting and distribution of
the downloaded files by email, print or fax, or to directories on your network.
□ The Catapult Console, which you use to create and maintain your ‘grab rules’.
Grab rules define the criteria used to select the spool files and the action taken
with those files. Grab rules are stored on your IBM i, so everyone using the
console is working with the same set of rules. From the console you can also
monitor your active rules as they download and process your reports.
Catapult also includes a Launchpad from which you can start the various components
and check your poller status.

Summary List of Steps Required to Run Catapult

After installing the software, here is a list of the critical steps that you must perform in
order to run Catapult:
1. You need to configure and start the EXODUS55 subsystem on the IBM i (see the
section “Step 3: Start the EXODUS55 Subsystem” on page 42 ).
2. Install, configure and launch the Catapult Poller on your PC. Normally, the
poller is running continually in the background. In the poller configuration you
need to enter your email server configuration details and set the action to be
taken for errors (see the section “Step 6: Configure the Catapult Poller” on
page 49 ).
3. Install, configure and launch the Catapult Console on your PC. Create a new
grab rule, then define the criteria for the file selection and the actions to be
taken for that file (see the sections “Step 4: Install the Catapult PC
Components” on page 43 , and “Step 5: Configure Communications on Each
PC and Log In” on page 45 ). Save your grab rule.
At this point, the software should be running, and you can sit back and wait for the first
spool file to be processed and distributed.
The next sections explain in more detail the available options and potential issues
associated with running each of the Catapult components.

Catapult Security Considerations

In the following sections you’ll read more about how the Catapult Console and Poller
access your IBM i and the options available to the people who use them. But it is
important to understand at the outset that Catapult potentially introduces a new way for
your users to access your IBM i.

- 61 -
The Catapult Poller needs to be able to run at a very high level of security in order to
access the full range of reports that may be requested by any grab rule. When the poller
runs, it can therefore access any spool file in any of the queues you specify in the poller
configuration. This entails a certain level of trade-offs between convenience and
risk/trust.

For a technical discussion of this topic, please refer to the

section “Security Considerations” on page 371, in the
appendix discussing Communications Considerations .

For example, if you revoke a user’s authority to a queue, an existing rule could continue
to run and distribute reports to them from that queue.
In practice, the individuals who administer Catapult tend to already have very high levels
authority and thus these issues have rarely been a concern with our customers. But if
your organization is particularly security conscious or you work with data that is
particularly sensitive you may want to take steps to increase the levels of security
required to access Catapult. For instance, some clients run two separate versions of
Catapult, one running at a higher level of authority than the other. You can also just
exclude your user(s) from the Catapult libraries, blocking them from being able to do
anything with the tool. But if you want to allow some users limited access to the Catapult
Console to create grab rules but also want to restrict their access to certain queues, this
can take more care.
If you have any questions about this please contact Technical Support to discuss your
concerns with our technical team.

- 62 -
The Catapult IBM i Component
You must install the IBM i component of Catapult to run the software. You can set up
Catapult to find and distribute spool files from more than one IBM i. If you are doing this
each IBM i must have the server component installed. You will also need a separate
license for each box.

The EXODUS55 Subsystem

Catapult uses a middleware component called Exodus55 to handle communication
between the server and client sides of the tool. Exodus55 is automatically configured and
started when you install Catapult. If the Exodus55 subsystem does not start
automatically, review the instructions in the section “Manually Configuring the IBM i for
TCP/IP Support ” on page 367.
Catapult requires that the EXODUS55 subsystem be running on the IBM i. You can check this
by executing the WRKACTJOB command and reviewing the active subsystems. There must
be at least one additional job called EXSERV51 running under the EXODUS55 subsystem. This
job should be in TIMW status.

If the EXSERV55 job is not running, end and restart the subsystem.
Then check whether that job is created. If it isn't, run the WRKSPLF
EXODUS55 command and check for a joblog that indicates why the
EXSERV55 job either didn't start successfully or was ended
immediately after starting. The most likely cause is that the port
configured in the ZCFGTCP command is already in use. You may
need to run the command again, choosing a different port.

While Catapult is active there may be any number of additional jobs under the EXODUS55
subsystem. The Catapult Poller creates two jobs named EXWORK. If anyone is working with
the Catapult Console that will also show up as a job with the same name.
To determine whether an EXWORK job is the Catapult Poller or the Console, execute an
option 10 next to that job to view the call stack. The poller jobs will have the programs SP_
PSRV and SP_QSRV in the call stack while the console will have SP_MSRV in the call stack.

Restarting the EXODUS55 subsystem after an IPL

You must restart the EXODUS5 subsystem whenever you IPL your IBM i. We recommend
that you start this subsystem as one of the last steps after an IPL to ensure all other
required services are already running.
You can also synchronize this with the PC jobs that run the poller.

- 63 -
Catapult and IBM i System Usage
After starting Catapult you may find that it uses an unacceptable level of system
resources. This is almost invariably related to having a very large number of queues to
be polled, or huge numbers of spool files in some queues.
When Catapult is first installed the software by default polls every queue on your IBM i,
checking every single spool file against the grab rules defined. If you have a large
number of queues and/or spool files, this polling process can take some time. If you also
have the spool polling program configured to poll frequently (such as every few minutes)
it might seem like the polling program is always active.
You can reduce Catapult’s resource usage in the following ways:
1. By polling only selected queues, and particularly by omitting queues with a
many spool files that will never be distributed.
2. By limiting or reducing the number of spool files on your system, in the queues
that are getting polled.
3. By moving spool files to queues that aren’t polled. Catapult has a feature to
move a spool file to another queue after is has been processed. We
recommend you take advantage of this feature to improve Catapult’s
performance.
4. By changing spool file attributes for processed spool files so they no longer
match any grab rule’s selection criteria. Catapult also has a feature to do this;
this technique is less effective than moving the spool file to a queue that isn’t
polled at all.
5. By increasing the time between the polling intervals.
Below are additional details about each of these options.

Limiting the Number of Queues Polled

To limit the number of queues polled launch to the Poller Configuration and select the
Queues configuration options. When you do this Catapult loads a list of all the queues on
your IBM i. You can then include only selected queues in the list to be processed. This
option is described in the install instructions, as well as in the section “Selecting Queues
to Poll” on page 347 .

When you first install the software, be careful with limiting the
out queues polled until Catapult has successfully emailed at
least a few spool files. Unexpectedly omitted queues is the
most frequent cause for otherwise correctly defined grab rules
not producing any results.

This technique (which you should use in conjunction with the other options describe
below) is normally the most important factor affecting performance.

- 64 -
Limiting/Minimizing the Number of Spool Files Catapult Checks
If you don’t regularly clean up the spool files on your system or you have queues that
contain thousands of archival spool files, this can significantly slow Catapult down.
Each polling cycle Catapult begins by checking each and every spool file in your selected
queues to determine whether it matches the selection criteria of any active grab rule. If
you have thousands of spool files in your queues, and over time create dozens or
hundreds of grab rules, this can result in quite a few checks that have to be performed
each polling cycle.
You can dramatically improve Catapult’s performance by moving processed spool files
to a queue that is not checked by Catapult, deleting processed spool files outright, or
combining both options. You can perform these operations automatically as part of your
grab rule processing. This is described at the end of the section “Post-Processing
Actions” on page 199 .

In order to fully check a spool file Catapult must pull up its

entire list of attributes. This has a significant processing cost
associated with it.
In an idle or lightly used system this isn't a huge concern as
the information will get pulled up into memory and probably
sit there (especially if you have a short polling cycle).
However, if your system is very active, the data will get
pulled into memory and then get pushed out with new data.
As a result, the poller must repeatedly retrieve information
from disk each polling cycle.

The History Listing as an Indicator of Keeping Too Many Old Spool Files
Every time Catapult processes a spool file it creates a history record so that on
subsequent polling cycles it doesn’t re-distribute the same report again.
The poller configuration includes an option to periodically clear this history listing. The
default setting is to clear the history list every 10 days (see the section “Selecting
Queues to Poll” on page 347  for details). If you find that after 10 days your users start to
receive duplicate copies of old reports, it probably means that the reports were
processed once 10 days ago but are still sitting in their original queue, unchanged. Their
continued presence in that queue means that every time Catapult has polled during that
10 day interval it has had to check that spool file, compare it to all existing grab rules,
then further compare it to the history list. If you are polling every few minutes to ensure
that generated reports are delivered in a timely manner, this represents many wasted
cycles.
One way to stop users from getting duplicate copies of old reports is to never clear your
history listing. If you take this approach Catapult will consume more and more resources
over time as it deals with an ever-growing number of spool files and history records.

- 65 -
 A better approach is to set up your grab rules to always delete, move or change your
spool files when they are processed, and clear your history listing regularly. Then, if
users complain of getting duplicate reports within a short time-span (2-3 days), you can
immediately identify this as a grab rule problem.

Polling Less Frequently

You can also reduce Catapult’s resource usage by polling less frequently.
However, if you are relying on Catapult to immediately distribute reports as they are
created on the IBM i we recommend that you first work with the other options described
above. You can also use the technique described in the next section below. But if you are
using Catapult solely to distribute reports that are not especially time sensitive you can
set the poller to run anywhere from hourly to daily at a time when system usage is low.
Of course, you probably wouldn’t be using Catapult if none of your reports were
particularly time-sensitive! But you can still work with your polling cycle to strike a balance
between performance and distribution timeliness.
To change the polling interval, launch the Catapult Poller Configuration and select the
Polling category. These options are described in the section “Selecting Queues to Poll”
on page 347 .

Using ZRUNRULE and ZDSTSPLF

You can also use the ZRUNRULE and ZDSTSPLF commands to improve performance.
Each executed polling cycle Catapult goes through all your spool files and grab rules to
build a list of files to distribute. This process is resource intensive and it can take some
time to build the distribution list - even when none of the spool files currently on the
system match one of your grab rules.
If you have access to the programs that create your spool files, or have the ability to wrap
these programs in CL programs, you can add ZRUNRULE or ZDSTSPLF calls right into the
report processing cycle. This creates immediate requests where Catapult just does a
quick check to make sure the spool file exists then generates a request and sends it up to
the PC to be processed.
In a perfect world the most efficient way to set up Catapult would be to have a single daily
polling cycle, at a time when most users were off the system, to process all your non-time
sensitive reports, and have all your other reports processed directly using the IBM i
commands. This would eliminate the need to have the poller running a full cycle every
few minutes, and in general result in critical reports being processed more quickly.
If you use the ZRUNRULE command you can create and maintain your rules via the Catapult
Console. If you use the ZDSTSPLF command (where all the distribution parameters are
included in the command string, and no rule is required), you will need to carefully
document your distribution rules, as they will not appear in the console’s listing.

- 66 -
Running the Catapult PC Components
The Catapult installation process will create Start menu shortcuts to as many PC
components as you install. You can also start any of the components from the Catapult
Launchpad. If you wish to create other shortcuts to run one or more of the components
you need to add them with a target path like this:
"C:\Program Files\ESDI\Catapult 7\CatapultConsole.exe" Console

The executable CatapultConsole.exe is a wrapper for all the other components, so you
need to append the actual application name at the end. The application names are
Console, CommConfig, ConsoleConfig, PollerMngr and PollerConfig.

The Catapult Poller

The Catapult Poller is the PC component that periodically 'wakes up' and polls your
queues for spool files to process. It also handles downloading and formatting spool files,
any additional actions that are performed on them (such as converting to PDF), and their
subsequent distribution.

Where Should I Install the Catapult Poller?

You can only run one poller instance at a time so you will normally install it on a single
machine. In normal usage the poller is always running (though of course not always
executing polling cycles).
While you are evaluating Catapult you may choose to install the poller on your own PC.
This will work fine. Once you are using the product on a permanent basis you should
install it on a server machine that is always on. This will ensure that there are not
distribution delays caused by the poller PC being shut down.
As your Catapult usage grows, we recommend that you install the poller on a dedicated
PC. There is a significant workload involved in downloading and processing spool files,
particularly if you are converting large spool files with many thousands of pages to PDF
(as one example of a particular resource intensive process). If you have other
applications running on the same PC they may experience some performance
degradation when large reports are being processed.
describes how to install and configure the poller.

Running the Catapult Poller

To run the Catapult Poller, start by running the Poller Manager (Start/Programs/Catapult
8/Poller/Manage Pollers). Here is an illustration of the Poller Manager utility, with two
systems defined:

- 67 -
Figure 3-1. Managing the poller instances installed on your system.

From here you can start, stop and configure your poller instances.
When you click on a poller instance and select the Start option, Catapult asks you to
confirm whether you want to start the Poller Service. Click Yes to start it.

You need to also make sure that the profile configured for
that system (in the connection details) has sufficient
authority to access all the queues and spool files that you
intend to process.

When the poller starts, the manager will show it like this:

Figure 3-2. Two pollers, with the second one currently active.

In the illustration above, the second poller instance shows as Active on the far right, and
when you click on it, the Stop and Poll New buttons become active.
To view the poller status, start the Catapult Launchpad (Start/Catapult 7/). You’ll see the
launchpad as an icon running in your tray. Right click this icon to see an option that
allows you to check the poller status as well as review any error messages.
Generally, the Catapult Poller will poll your IBM i once when you first start it up, and
afterwards at the interval you select at the Polling/Purge Time Settings option (from the
Polling category in the Catapult Poller Configuration). If the polling interval is set to run
once daily, the poller will not perform a poll at start up, it will wait for the specified time.

Saving Your Spool Files on the PC

- 68 -
 If you are using Catapult to save files on a PC, the directory that you save your files in
must be on your network and accessible from the poller PC. This directory is specified in
the Distribution/Archive category of your grab rule options.

When you use Catapult to save and archive spool files on

network drives, Catapult first attempt to access the required
drives using the network profile used to start the poller
service. If that doesn’t work, it then attempts to connect to
the folder using the Network Acquisition Default Profile set in
the poller configuration. Finally, it will check whether another
profile has been added specifically in the specific grab rule
currently running. You must ensure that one of these profiles
has sufficient authority to create folders, as well as create
and delete files, in the target directories.

The Catapult Poller and Printing/Faxing

If you set up your grab rules to convert spool files to a PC document format to then print
or fax them, Catapult uses the default application associated with a file extension. For
example, if you are planning on printing or faxing RTF documents, you would need a
copy of Microsoft Word® or another word processor that supports RTF files installed on
the poller PC. Additionally, if you are planning to print to network printers, the appropriate
printer drivers must be installed on the poller PC so that it can access those printers.

The Catapult Poller and Nexus Enterprise Content Manager (ECM)

Catapult can integrate with the Nexus Enterprise Content Manager to automatically
populate the ECM, instantly making reports available to all authorized users.
To take advantage of this functionality with Catapult 8, you need to ensure you have
Nexus 3.0 or higher installed.

The Catapult Console

The second important PC component is the Catapult Console. You will use the console to
create and maintain grab rules, track the status of distribution requests and monitor the
status of the Catapult Poller. The tutorial section of this guide, beginning in , describes
the most important options.
Here is an illustration of the Catapult Console:

- 69 -
Figure 3-3. The Catapult Console, illustrating folders, grab rules and admin tabs.

While you create and maintain your grab rules from a PC, they are actually stored on
your IBM i. This means that the console can be installed on any number of PCs, and that
every PC on which you install the console has access to all grab rules (though some
limited security options can be defined in your grab rules, to limit who can edit them).

Each console PC needs to be configured to connect to the IBM

i using EXODUS55. When you install the Catapult Console,
another utility called Communications Configuration is also
installed. This allows you to set up the link between the PC and
the IBM i. For details, review the section “Step 5: Configure
Communications on Each PC and Log In” on page 45.

Each time you start the console a new EXODUS55 job is started on the IBM i. Usually this job
will be under the EXODUS55 subsystem, but sometimes it may appear under QCMN. The
section titled “The Catapult IBM i Component” on page 63 describes how to identify
these jobs.

Creating and Maintaining Grab Rules

The Catapult Console is the tool you use to create and maintain grab rules. When you
launch the console, it establishes a connection to your IBM i and displays a list of all the
current grab rules. When you add new rules or change existing ones, your changes are
written back to the IBM i when you click on the OK button.
describes how to create and work with your grab rules.

The Catapult Console and the Poller

There is no direct relationship between where you install and run the console and where
the Catapult Poller is installed. While the poller runs on only one PC at a time (and would

- 70 -
 normally be installed on a single PC), you can install the console on as many PCs as you
like. Catapult is licensed from the IBM i, so there are no licensing issues with console
installations.
You need to be aware that if you are using a Data Extraction tool in your grab rules,
printing files, or saving downloaded files to a network directory, the paths specified in the
grab rule need to be relative to the Catapult Poller PC rather than the Catapult Console.
For this reason, UNC paths are recommended, and are automatically returned
whenever you use the Browse (...) button while defining a grab rule.

Monitoring Spool File Distribution Status

The Catapult Console also includes several tools for monitoring and working with
distribution requests.
To use these tools, it is important that you understand the steps that Catapult goes
through to distribute a file. Below is a summary of the process:
1. Each time the Catapult Poller runs, it scans the queues on your IBM i, building
a list of requests for all the spool files that both satisfy any grab rule selection
criteria and have not previously been processed by Catapult.
2. After building the entire list of spool files that are valid for distribution, the IBM i
component notifies the Catapult Poller PC that requests have been generated
and are pending. The poller then processes each request, logging its actions
to the request file.
3. After each file is processed, an entry is written to the distribution history files,
as either a successful distribution or as an error entry.
This summary assumes you have already created one or more valid grab rules, and no
fatal errors are encountered.

Using the Download History List

From the Catapult Console you can open the History tab to view a history list of
downloaded files (if the tab isn’t visible, you can enable via the View menu). When you
select this option, Catapult displays an informative list of all the spool files that have been
distributed.
Here is an illustration of the download history listing window:

- 71 -
Figure 3-4. A set of Catapult distribution history records.

During Step 1 of the Polling process, the Catapult Poller checks the history file to verify if
a given spool file has been processed by a previous cycle.

An unofficial benefit of this feature is that if there is a spool file

on your system that has already been processed by the
referenced grab rule, you can trick Catapult into processing it
again by deleting the appropriate history record.

If you have spool files that exist unchanged on your system for a long time you will find
that these spool files are re-sent if you delete the history list or after the list is periodically
purged. You can check your purge settings in the advanced configuration settings for the
poller. Enter a value for how often you want to clear your history list.
Another (better) alternative is to have your grab rule either delete processed spool files,
move them to a queue that isn’t polled, or change their attributes such that they no
longer match any grab rule selection criteria You can select which queues to poll and
which to skip in the poller configuration.

Using the Request & Request Errors List

From the Console you can use the Requests/Errors List option to work with the status of
pending and/or error requests. The list includes information such as the grab rule
number, the current status of the request processing, and if there was an error, a
message indicating the cause of the failure.
Check this list if the poller has run through a cycle and you have a spool file that matches
your grab rule criteria but did not seem to get processed. If you correct the error
identified in the message, you can right-click the request entries to delete or re-enable
them so that Catapult processes the spool file again in the next polling cycle.

- 72 -
The pending requests are mainly available to satisfy your curiosity about what step of the
way the processing is in. Also, on rare occasions a request entry may become corrupted
and cause the poller to fail. When this happens, you can disable the offending request
entry, restart the poller to allow it to continue processing other rules, then review the grab
rule for errors and correct it. Finally, you can re-enable the troublesome request.
Generally, in a situation where the Catapult Poller has ended abnormally due to a
corrupted request, the entry flagged as active in the Pending Requests List is the one
that has caused the problem.
The section “Browsing Pending Requests and Request Errors” on page 308  discusses
these options in detail.

- 73 -
 SECTION II
Catapult Tutorial
In this Section:
Chapter 4 - Creating Your First Grab Rule
Chapter 5 - Adding Report Formatting and
Overlays
Chapter 6 - Splitting Documents and Reports
Chapter 7 - Creating Spreadsheets with
Catapult & Data Extraction tool
Chapter 8 - Using Catpult with Nexus

- 74 -
 - Creating Your First Grab Rule

CHAPTER 4

Chapter 4 - Creating Your First Grab Rule

This section of the guide will teach you how to use Catapult’s most important features.
You will begin by creating a simple grab rule to email yourself a report. After you have
had Catapult work for you a few times using its most basic options, you can continue in
the following chapters by adding more features to your grab rules.

Location of the Demo Files and Reports

The Catapult library XL_CATAPLT contains the sample files and reports you will use in these
exercises.
In Case of Doubt
If at any time during these exercises you have any difficulties, please contact our support
team - we’ll be happy to give you a hand. Please call the Fresche Solutions Technical
Support team at (800) 258-3399, or (508) 594-2700. You can also reach us by email at
support@freschesolutions.com.

In this tutorial the steps that require action are sometimes

separated by detailed explanations about particular features.
To help you move more quickly to the next actual tutorial step,
these are tagged Action Item:
If you just want to zip through the tutorial to see how Catapult
works, you can skip the explanations. But if you’re really trying
to learn to use the software you should take a few extra
minutes to read through the details.

Catapult Live Web Demos

The Fresche Solutions Technical Support team conducts personalized Live Web Demos
and group Webinars for all our software products. For further information speak with
your sales representative at Fresche Solutions.
You can also view pre-recorded Getting Started webinars at our web site.

- 75 -
What is the Catapult Console?
Whenever you work with Catapult, you’ll use the console to create and work with your
‘grab rules’. Grab rules contain your spool file selection criteria as well as the actions you
wish Catapult to perform for the selected reports. You’ll also use the console as a starting
point for launching other utilities to monitor the status of your grab rules as they are
processed, to check for any errors that may have been encountered, and to work with
your distribution address lists.

Starting the Catapult Console

Action Item: If you just followed the installation instructions the Catapult Console should
now be running on your desktop. Otherwise start it now from the Windows Start menu, at
All Programs/Catapult 8/Console/ Console.
On launch, the console attempts to establish a connection to the IBM i where all your
grab rules are stored. Here is an illustration of the login window:

Figure 4-1. Logging on to your IBM i (your exact Catapult version may vary)

Action Item: Enter your User ID and password to log on to your IBM i.

If the connection information you set up when you installed

the software doesn’t look right, click the Communications
button to review or edit the details. Then try connecting.
If you get a 10061 or 10057 error when you attempt to
launch the console it usually means that either the EXODUS55
subsystem isn’t running on the IBM i or you haven’t correctly
configured the connection information for your PC. To verify
that the EXODUS55 subsystem is up and running, run the
WRKACTJOB command from an IBM i session. If the subsystem
isn’t active, execute the command STRSBS XL_EX55/EXODUS55. If
the subsystem is already active, then you may not have
configured your communications correctly. Review the
section “Step 5: Configure Communications on Each PC
and Log In” on page 45  for guidance.

The Catapult Console Window

When you successfully log on, the main console window is presented. Here is an
illustration of how it initially appears:

- 76 -
Figure 4-2. The Catapult Console, as first launched.

When you first install the software you’ll only see the empty General folder. If you are
upgrading from an earlier release or you aren’t the first person to install the console,
there may be other folders and rules shown above.

Your Catapult rules are stored entirely on the server - you

can set up a Console on as many machines as you want.

You can hover your mouse pointer over the toolbar icons to see what each of them does.
These are described in detail in Chapter 9. Each icon also has a corresponding menu
option under the File, Edit or Tools menus.
Confirming the Poller is Running
In order to actually distribute any spool files, you’ll need to have the Catapult Poller
running. If you click the Poller Status tab you should see a message that confirms that no
active pollers have been detected. We’ll start the poller later in this chapter.

- 77 -
Building Your First Grab Rule
In this exercise we’ll begin by building a very simple rule with the most basic options.
Along the way we’ll also point out other features you will commonly use.

Creating the Example Report

Action Item: To get started with this exercise, first go to an IBM i session and add the
library XL_CATAPLT to your library list.
Then run the command CALL CATITEMS to execute the first Catapult demo report program.
The program CATITEMS produces a report (on the default queue associated with your user
profile) with a spool file name of QSYSPRT and CATITEMS as the user data.
Use the WRKSPLF command to confirm that the report was successfully created.

Using the Preview Window to Locate the Spool File

Action Item: To create a rule for our sample report, begin by clicking the Preview Spool
Files button in the console toolbar– . When you click this button, Catapult asks you if
you want to automatically load the spool file list; click No. Then Catapult presents a
window similar to this one:

Figure 4-3. The spool files in the default queue.

Action Item: In the User Data file field, type CATITEMS, then click the Search button on
the right.
Catapult should load your report in the window, as shown here:

- 78 -
 Figure 4-4. The preview window, showing a subsetted list of reports matching our filter.

In the illustration above Catapult has found the report we just ran.
Action Item: Click the report once to select it.

If you double-click the report Catapult starts downloading a

preview of the spool file. If you do this by mistake, just close
the window that opens and come back to this list.

Action Item: After selecting the file, click the toolbar icon indicated above to create a
quick rule (as shown in Figure 4-4).
Continue with the steps below to edit your rule.

Editing the Rule

After you click the Create Quick Rule button the Catapult Console jumps directly into the
General category of a new rule:

- 79 -
 Figure 4-5. Starting work on a new rule.

In the left pane of the window are the main grab rule definition categories. You can click
on the + symbols to review the options in each category. The General category (shown
here) includes your rule description and a few other items worth noting:
□ Status/Folder/Processing Order. Within the General Information category, by
default new rules are inactive, added to the General folder, and processed in the
order in which they were created.
□ Rule Expiration. New rules also have no expiry date. But you don’t have to
worry about the same file getting sent to you over and over again – each time the
poller runs it checks a history listing to see whether this rule has already picked
up a particular instance of a spool file.
□ Grab Rule Security. You’ll find this feature useful as you start using Catapult for
increasingly mission-critical tasks. You can use this option to set an authorized
user or user group who can modify this rule. This means that when you allow
users of all types to use Catapult for various purposes, you can also set some
basic limits to ensure that key rules aren’t accidentally altered or damaged.
□ Post Rule Notification. You can use this option to notify a specific user when the
rule has an error.
Action Item: For now, just type a rule description of ‘Catapult Items Report’ (and perhaps
add your name, to make it unique). Then click Next>> 2 times and continue reading the
next section below.

Reviewing the Spool File Acquisition Criteria

Below is the grab rule acquisition information. In this rule, this information was derived
from the sample file you selected:

- 80 -
Figure 4-6. The grab rule acquisition criteria, from the sample spool file.

Notice that the criteria is quite specific. As this rule stands, it will download that single
spool file, once, and no others. The selection works on an ‘AND’ basis; the more options
you select, the more particular the rule. To make the selection more general you could
eliminate some of the criteria shown above or use wildcard values.
Here is an overview of the most important areas in this window:
□ Selection Criteria. As stated above, you can make your selection very broad
(every spool file in a queue) or very specific (a single instance of one report). If
you didn’t start creating a rule from the preview option (as we have done), you
would enter your criteria manually.
□ Download Formatting. This option allows you to set the report format (primarily
whether to include blank lines to match the original file format, or just download
the raw data).
□ Post-Processing Actions. These are actions that can be taken with the spool
file after it has been processed.
Action Item: For this example, check the ‘Update user data with:’ option and type
‘CATAPULTED’ in the box beside it.
By doing this you are providing yourself with a quick visual confirmation from the WRKSPLF
listing (on the IBM i) that the file has been processed. You are also changing the spool
file so that it no longer meets the selection criteria of this rule (which references the User
Data), and doubly ensuring that the report is not accidentally distributed again (the
history list is also used for this purpose).

- 81 -
The Locate Button
At the right of the Spool File Attributes you’ll see a button labeled ‘Locate’.
Action Item: Try clicking the Locate button now. If prompted, accept the option to
automatically load the spool file list.
This window is presented:

Figure 4-7. The results of pressing the Locate button with the acquisition date filled out.

From this window you can also preview the spool files to make sure you’re grabbing the
right one(s). The list confirms that the report we initially selected is the only one that
meets our selection criteria.
Action Item: Click the Close button to return to your grab rule definition.

Setting the Transformation Options

After selecting your acquisition criteria, we will advance to the Transformation options.
Action Item: Click the Next>> button a few times until the grab rule editor gets to the
Transformation category, shown here:

- 82 -
Figure 4-8. The default document file name and download format and file name.

The name of the downloaded file defaults to the simplest value: &n.txt. This tells you that
your downloaded file will be in plain text format, with the same name as the spool file.
Catapult supports a wide range of replacement values that you can use in many different
grab rule options. For example, if you have a report that is generated several times a day
and you want to make sure that each version processed by Catapult has a unique name
you can add the replacement values &y and &t (PC date and time) to the name. You can
also combine replacement values with constant text, or define your own replacement
values mapped to data extracted from your reports. Replacement values are described
in the section “Target File Name” on page 240 .

The grab rule categories are listed in approximately the

same order in which the options are actually processed at
runtime. So in the Grab Rule Editor you’ll notice that the
Document Splitting and Data Extraction options are shown
before the Transformation options.
These options, however, are not critical, and in this first pass
we won’t add any splitting or data extraction criteria.

Action Item: Change the File Name to “&u - &d - &n.txt”. These replacement values
correspond to your User ID, the spool file user data and the spool file name. Then click
Next>> until you get to the Email Distribution options.

- 83 -
Distributing the Report by Email
Below are the Email Distribution options. For this first rule we’ll keep things simple by
sending the report by email to your own address. We’ll add just one minor twist, by
putting your address into a distribution group, instead of entering [hard-coding...] it
directly into this rule.
Here are the email options for this rule, after making the changes described next (the
instructions are below the window):

Figure 4-9. Adjusting the emailing options for this rule.

Action Item: In the window above, start by clicking the Enable Base Document Emailing
option. Then type an email subject, such as ‘Catapult Item Report for &y’.
As stated above, the simplest emailing option is to just type a single email address in the
space provided. But let’s try using a distribution group.
Action Item: For the ‘Target Address’ value, click the ‘Group’ radio button, and then click
the button to the right of the field to select a group:

Figure 4-10. Selecting a Catapult Distribution Group to email the report to.

If you have just installed Catapult and are the first person to try it out, your group list will
initially be empty:

- 84 -
Figure 4-11. Working with Catapult Distribution Groups, on a new install.

Action Item: Click on the Create Group icon at the top left to create a new group:

Figure 4-12. Adding a new distribution group.

Action Item: Type a group name (for example, ‘MyCompany’) and description. Click OK
to create the group.
When you click OK to add the group, Catapult presents the window below, where you
can create and work with your group members:

Figure 4-13. Working with group members (for a new group - no members exist yet).

- 85 -
Action Item: Start by typing your group description in the field above the list. Then click
the Add Group Entry icon (at the top left) to create your first entry.

Like your grab rules, your group entries are records in files
on the server. If you want to import group entries from other
lists, contact Technical Support to discuss your options.

Creating a Group Entry

Distribution groups support many options that we’ll look at during the course of these
tutorial exercises, but for now all we need is a name and email address:

Figure 4-14. Creating a new group entry.

Action Item: In the area of the window indicated above, enter your own email address
and name. Click OK to add the entry, then OK again at the group list window to return to
the main Distribution Group window:

- 86 -
Figure 4-15. The new group showing in the list of distribution groups.

Action Item: Click the group and then the Select button, to pull it back into your grab rule.
Back at the Email category of your grab rule, you should see your new group as the Send
To value:

Figure 4-16. The grab rule email options, showing the report(s) will be sent to a group.

Action Item (Optional): If you like you can also add your address at the CC and BCC
options, and choose a Return address (this is optional), to customize who the email will
appear to be sent by, and who the replies will go to by default.
General Options (Handling Attachments, Status, etc.)
Now that we have decided to distribute this report by email and set who will get it, we can
adjust some other options related to how the report will be handled in the email.
Continue with these features on the next page.
Action Item: Click the General Options tab to display these options:

- 87 -
 Figure 4-17. Reviewing some of the additional options for emailing reports.

From here you can select whether to include the report in the body of your message or
as an attachment.
If you have chosen a relatively simple, narrow report, it can sometimes work to include it
in the email body, but if the report is wider or you are downloading it in a non-text format,
you should send the file as an attachment – this is the default option.
Action Item (Optional): If you are feeling particularly ill-disposed towards your intended
recipients, you can check the ‘Request Read Receipt’ option at the bottom of the page,
and further exacerbate that gesture by setting the priority to High. Of course, for this
exercise you’re only sending the report to yourself, so your ill intentions may be
misspent.

Archiving a Copy as a Backup

Action Item: Click the Next>> button until you get to the Archive options, shown here:

- 88 -
Figure 4-18. Reviewing the report archiving options.

Notice that there is a checkbox here, Enable Archiving for Base Document, allowing you
to save the file to your PC. You can save to any network directory.
In this rule, our main objective will be to email the spool file, but we’ll use this option as a
backup in case you have any initial email server configuration problems.
Action Item: Click the button to the right of the Folder Path option, to pop up a window
similar to this one:

Figure 4-19. Browsing for a network directory in which to save

Action Item: Navigate your network to find the poller PC (easily done, if you installed
everything on your own machine) and save the report on the Catapult Poller PC’s local
drive, at Program Files (x86)\ESDI\Catapult 8\Documentation (or another easily
accessible location).

- 89 -
 By saving the file on the poller PC’s local drive you are avoiding
the potential hazards of network authority or email server
issues. If you don’t have the poller installed on your PC you
may need to share a folder on the poller PC (right-click the
folder and select the Sharing and Security option) in order to
see it in the list displayed in the window above.

Action Item: After selecting the path, click OK to save your rule and return to the
console.

If you have the poller on your local machine, you may get a
warning about selecting a valid UNC path. For now, just click
Yes to accept the value as entered.

You should see your new rule listed in the General folder.

- 90 -
Starting the Catapult Poller
The Catapult Poller is the component that periodically scans your IBM i out queues to
check for spool files that match the selection criteria in any of your grab rules. Then it
takes care of processing and distributing the files according to the instructions you define
in your rule.
Before you can distribute any reports, you need to start the poller.
Action Item: Confirm that the Catapult Poller is not running by clicking the Poller Status
tab in the console:

Figure 4-20. The Poller Status tab, showing no active pollers.

If you just installed the software, you probably don’t have the poller running, and the
Poller Status tab will display the message ‘No active pollers found’.
Action Item: Let’s start the Catapult Poller via the Launchpad. You can start the
launchpad from Start/Programs/Catapult 7/Catapult Launchpad.
When the launchpad starts, you’ll see that it adds an icon to your system tray:

Figure 4-21. Using the Catapult Launchpad to run the Poller Manager.

- 91 -
Action Item: As shown in the illustration above, right-click the Catapult Launchpad icon
and select the Manage Pollers option.

This step assumes that you have installed the Catapult Poller
on your PC. If you don’t have the poller on your PC, you’ll need
to start it on the system where it has been installed. If you
aren’t sure what action to take here, contact your system
administrator, or call Fresche Solutions Technical Support.

This is the Poller Manager:

Figure 4-22. The Poller Manager, showing a single system that can be polled.

In this window you should see a single system, which is currently not being polled.

In the illustration above, we are running out of a

development environment (library XL_CAT70U). In your own
case, you will probably see library XL_CATAPLT.

Before starting the poller, let’s review its configuration settings.

Action Item: Right-click the system shown in your list and select the Configure Poller...
option. This window is presented:

- 92 -
Figure 4-23. The Poller Configuration window, showing the default settings.

On install, the poller is configured to be started and ended manually. While running, it will
poll your system(s) every 10 minutes.

You can review the critical poller settings in the section “Step
6: Configure the Catapult Poller” on page 49  (the installation
instructions).

Action Item: Click the OK button to close the Poller Configuration window.
Action Item: Then, back at the Poller Manager, right-click your system and select the
Start Poller option. Catapult will display a confirmation message to alert you that the
Catapult Poller service will be started. Click OK to continue.
Once the poller instance is running, the manager will show this:

Figure 4-24. The Poller Manager, showing one active poller instance.

- 93 -
Action Item: Go back to the Catapult Console, from which you can further verify that the
poller is running by clicking the Poller Status tab:

Figure 4-25. The Poller Status tab, showing the messages for an active poller instance.

Because we haven’t yet activated our rule, there still isn’t much to see.

And if there’s still *nothing* to see, check the troubleshooting

instructions at the end of this chapter for instructions on how to
confirm the poller is actually running, and other possibilities.

Action Item: Click your grab rule (single click) and press F2 to toggle the status. Then
press the Trigger Immediate Poll button (the green arrow) to run a polling cycle. If
everything is configured and working right, within a few seconds you should get an email
with the report as a text attachment.
Action Item: Check your email to see if you have received your report yet.
For example, in Mozilla Thunderbird, the received email looks like this:

- 94 -
Figure 4-26. The Catapulted report, shown inline and included as an attachment.

Thunderbird has detected that the attached file is plain text, and included the content in
the email body, as well as attaching as a separate file.
Once you get your first report you are ready to proceed with building more sophisticated
grab rules. The next chapters of this guide describe the grab rule options in more detail,
as well as how to define rules for parsing and splitting spool files.

If you didn’t get your report, now is a good time to start learning
how to troubleshoot problems with Catapult.
The first thing to check is the folder you chose on the Catapult
Poller PC (probably C:\Program Files\ESDI\Catapult
7\Documentation) to see whether the spool file was downloaded
and saved there. If it was, then your email server is probably not
letting the Catapult email through. If the report wasn’t even
saved in the poller PC folder, then review the troubleshooting
suggestions on the next page.
The next section lists some simple troubleshooting techniques
with which you can begin to familiarize yourself. Or you can just
call Technical Support! During our hours of operation support
calls are picked up immediately by a real person who can help

- 95 -
you immediately. No fake human voices, no holding.
We are open from 7:30 AM to 5:00 PM PST.

- 96 -
Basic Troubleshooting Techniques
Below are a few things you can check to help you determine why you did not get a spool
file as you expected. describes all the available tools for tracking the status of
distribution requests, and includes a much more detailed troubleshooting checklist for
more complex issues.
If you aren’t able to easily determine why your grab rules aren’t working as they should,
please us at (800) 258-3399, or (508) 594-2700. You can also reach us by email at
support@freschesolutions.com. We’ll be happy to give you a hand!

Checklist
Is the Catapult Poller Running?
The first and most important thing to check is that the Catapult Poller is running. You can
verify this by clicking the Poller Status tab in the console, or by running the Poller
Manager from the Catapult Launchpad.
If the poller isn’t running, start it from Poller Manager. If the poller does not appear to
start, review the installation instructions in Chapter 2 to ensure it is configured correctly.
Is the Catapult Poller Running, but the Catapult Console can’t see it?
In some rare situations the standard Windows firewall may block the console’s ability to
see the poller. This is rare because normally firewalls don’t block internal traffic, but you
could run into this if you’re trying to access the poller from a console instance running
outside your intranet.
If you have this problem you will see a message in the poller status window to the effect
that there was a connection problem. In the log files you will find additional details stating
that the connection to the poller machine was denied.
Is your Grab Rule Selection Criteria Correct?
If you followed the steps in this chapter your selection criteria should be right, but you
should still double-check it.
If you are downloading spool files, go to the Spool File Acquisition category and click the
Locate button in the Spool File Attributes area. Verify an entry is found. You can also
review the steps in the section “Reviewing the Spool File Acquisition Criteria” on
page 80.
Was the Report Saved but Not Emailed?
If your first grab rule succeeded in saving the report to the local drive of the Catapult
Poller PC, but it wasn’t emailed, it may be because the IP address of the Catapult Poller
PC is not recognized as a trusted IP address by your email server. Check with your
network administrator to confirm this.
Are you Polling Only a Subset of your Queues?
Catapult includes a feature to make the poller run more efficiently by polling a limited set
of queues. If Catapult is already being used at your site, this might be the case. You can
review this list in the Queues category of the poller configuration. Launch the Poller
Manager from the Catapult Launchpad. Then right-click the active entry and select the

- 97 -
Configure Poller option. When it loads, go to the Queues category and check that the
queue with your spool file is currently being polled.
Was there a Distribution Error?
At the bottom of the console you should have a Request List tab. Click this and check
whether you have any pending requests, and if so, what their status is. If there are any
errors there, attempt to correct them, based on the cause of the error stated in the
message. Then delete the error record(s) so that Catapult re-processes your rule and
the selected files.
If you have errors but aren’t sure what they mean, contact Technical Support.
Has the Spool File Already Been Processed?
Check to ensure that the spool file has not already been picked up by your rule on a
previous polling cycle.
Check the History List tab at the bottom of the console window for a completion message
for the rule you created, and the time in which you executed the polling cycle. If for some
reason there’s an entry corresponding to your rule and spool file from a previous
iteration, delete the entry and re-run the polling cycle.
Did the Poller Run Into an Error With Your Rule?
Sometimes the Catapult Poller runs into an error when attempting to distribute a file. For
example, this could happen if have entered the wrong address for your Email Server in
the poller configuration, or if the SMTP server isn’t active.
To see whether the poller ran into any errors, right-click the Catapult Launchpad icon
and select ‘Log and Configuration Files’. In the directory that opens, check the Logs
folder for any .err files from the date and time at which you executed your polling cycle.
You can also check for errors logged in the file perror.log in the same folder.
Is Your Email Being Held Up?
And finally, it’s possible that Catapult processed your rule and sent off the file, but it’s
being held up in cyberspace somewhere. To check this, open the History List and check
if there is a recent record there for your grab rule. If there is, it means the report has been
sent but you just haven’t received it yet.
Also click on the ‘+’ symbol to the left of the History List entry to check what actions were
taken for that grab rule. This will show you whether you perhaps entered an invalid email
address in your rule, or whether there are any other unexpected issues.
Does the Poller appear to be active, but in fact is not responding?
When you’ve exhausted all other options and you are certain your spool file matches the
criteria in your grab rule, and other components look good, restart the Catapult Poller.
You can restart the Catapult Poller from the Poller Manager. If this doesn’t work, go to
your IBM i and run the WRKACTJOB command and look for jobs named EXODUS55.
Then attempt to end the Catapult 8 Service. You can do this by running the
‘services.msc’ command from your Start/Run command prompt. In the list of services,
right-click Catapult 8 Service and select the Stop option. If the service is frozen and does

- 98 -
 not respond here, you can open your Task Manager and end the Catapult Poller job from
there.
Then restart the poller from the Poller Manager.

Authority Issues
Because Catapult works at the crossroads of your organization’s network, requiring
access to printers, remote drives, IBM i queues and other areas, you may experience
some initial hiccups related to authorities. Typical messages you might see in the error
logs include:
□ “A printer path could not be derived for this request.”
□ “Bad user name or password.”
□ “Failure to connect with network resource.”
Also, if the Catapult Service profile (typically your network profile) is different than your
IBM i user profile, you may have trouble connecting to files and folders on your IFS.
Unfortunately, there isn’t a simple, catch-all way to bypass your intricately established
network authorities, and because Catapult overlaps so many different areas, you may
find it highlights certain inconsistencies in how things have been set up. But here are
some sections of the guide you may find helpful if you’re having authority issues with
your reports:
□ “Step 5: Configure Communications on Each PC and Log In” on page 45 .
□ “Step 7: Configure the Catapult Poller Service” on page 55 .
□ “Network Acquisition Default Profile” on page 347  (as part of the default poller
configuration).
□ “Network Acquisition Profile” on page 207  (as related to network file acquisition
for specific rules).
Our Technical Support staff does have some experience with these types of issues, so if
you get stuck, please give us a call.

Checking the Error Logs

All Catapult log files are stored in the same location. You can get to them via the
Launchpad option Log and Configuration Files or the Catapult Console Help menu. You
can also get to this folder manually at these locations:
□ Windows XP. C:\Documents and Settings\All Users\Application
Data\ESDI\Catapult\Logs
□ Windows Vista & Windows 7. C:\ProgramData\ESDI\Catapult\Logs
By default the log files only include errors encountered while communicating with the IBM
i. If you need additional detail in the log files, go to the Communications Configuration
and turn on "Include informational messages in Log" for that connection.
The file perror.log includes a record of the errors in your connection attempts. If you
need to see additional detail in this file, you need to enable Debug Mode in the Poller

- 99 -
Configuration (see the section “Poller Diagnostic Settings” on page 361 ). New records
are added at the bottom of the file.
You can find additional information about the error logs in the section “Checking the
Error Logs” on page 385.
Summary
In summary, if you are unable to easily determine why your rule doesn’t appear to be
working, please contact our Technical Support team. Or, if you are really ambitious, you
can try working through the more advanced troubleshooting techniques in Appendix C.

- 100 -
 - Adding Report Formatting and Overlays

CHAPTER 5

Chapter 5 - Adding Report Formatting and Overlays

In the first chapter of this tutorial we reviewed the steps required to create a new grab
rule that simply selects, saves and emails a report. Now we’ll look at how to enhance the
appearance of your report by converting it to a PDF.
Creating PDF files is just one of the many transformation options available for enriching
the quality of the files you distribute. Other options include:
□ Adding standard header and footer files.
□ Making your PDF (or HTML) files easier to navigate by adding bookmarks.
□ Attaching additional documents to the beginning or end of the distributed report.
□ Adding overlay images as backgrounds to one or more pages of your report.
□ Compressing the report (or reports) and distributing them as self-extracting zip
files.
In this chapter we’ll take a quick look at these features and few others.
Catapult also supports other formats, including HTML and RTF. The options available
when you create HTML or RTF documents are similar to the ones we’ll use to build our
PDF file. We’ll point out the differences as we go along.

When you create grab rules to convert spool files to RTF and
PDF formats for printing, you must install the appropriate
supporting software applications (such as Foxit’s Reader and
Microsoft Word®) on the poller PC.
For further information, review the section “Step 8: Install
Additional Applications on the Poller PC” on page 57 .

- 101 -
Copying our Rule to Add Formatting
If you get this far, you were presumably able to successfully distribute the report you
created in the first tutorial chapter. So rather than re-defining new selection and email
options let’s just create a copy of that rule as our starting point for this exercise.
Action Item: At the main Catapult Console window right-click your rule and click the
Copy Rule option:

Figure 5-1. Copying our working rule as a starting point.

Action Item: Confirm that you wish to copy the rule (and optionally, dismiss the message
from appearing in the future). When you do this, Catapult creates a new rule below the
original, adding the text ‘Copy of’ in front of the rule description.
Action Item: Double-click the new rule to edit it. Then make these changes:
□ General Options. In this category change the rule description to ‘Distribute
Formatted Item Listing’.
□ Spool File Acquisition. Go to the acquisition options and in the Selection
Criteria remove everything except the Out Queue and the User Data value of
CATITEMS.
□ Download Formatting. Change the Spool File Format to *RICH, to include the
original spool file’s overprinting and underlining.

When you save a file as PDF it’s important that you download
your report in *RPT or *RICH formats, to ensure that the page
breaks are included. If your PDF shows only a single page, the
format is probably set to *FILE.

□ Post-Processing Actions. In the post-processing options change the Update

User Data value from ‘CATAPULTED’ to ‘FORMATTED’.

- 102 -
When you finish, this area should look like this:

Figure 5-2. Making the acquisition options more general.

- 103 -
Converting Reports to PDF Files
Adobe’s PDF is one of the most useful and popular formats for distributing documents of
any kind. By saving your reports in PDF format you can ensure that it is delivered in a
consistent format to every recipient. When you create a PDF document you can also
control many additional report formatting options that plain text (the default) doesn’t
allow you to do anything with.
Action Item: Click on the Transformation category and select PDF as your target file
type:

Figure 5-3. Setting the rule to generate a PDF file.

Notice that when you do this Catapult changes your file extension in the Target File
Name field.
In the illustration above you can see that several other formats are supported. Each of
these has particular characteristics. For a discussion of these, please refer to the
reference section of the guide. Other than PDF, Catapult’s most commonly used formats
are RTF (to open the file in Microsoft Word®) and HTML (to open the file in a Web
browser).

- 104 -
Enhancing your Adobe PDF Document
After selecting Adobe (PDF) as our download format, the Catapult Console enables
several additional categories: Document Setup, Bookmarks, PDF Options and Overlay.
Let’s look at what each of these will do for us.

PDF Document Setup

Action Item: Click the Document Setup option to work with these settings:

Figure 5-4. Working with the document setup options.

When you use these options in your own reports, keep in mind
that as a general rule, the software defaults for setting up a
PDF file will work.
So before you override the default page properties, first
download a sample report without overrides and use that as
the basis of any adjustments you then make at the window
above.

Let’s start by evaluating the PDF version of our report with no overrides.
Action Item: Without making any more changes to your grab rule, make it active
(General category) and click OK to save your rule. At the Console, inactivate any of your
previous tutorial rules. Then rerun the report CATITEMS from your IBM i session
(remember that in our previous rule we were changing the User Data, so our initial
iteration of that report no longer matches our selection). Finally, in the Catapult Console

- 105 -
click the ‘Trigger an Immediate Poll’ button (the green arrow near the right of your
toolbar).
After a few seconds you should get your email with the report.
Action Item: Open the PDF that was emailed to you. It will look something like this:

Figure 5-5. A PDF report generated by Catapult.

If the file won’t open, you may not have a PDF reader installed
on your system. You can try Adobe’s Reader, Foxit Software’s
(recommended), or any other free, downloadable PDF reader.

While our report doesn’t look terrible, we could at least use a larger font to make it more
readable.

The report above didn’t fit the page well because (for the
purposes of this exercise) we deliberately set up the IBM i
report to use a non-standard page size. If the IBM i report was
set up better, the default PDF settings would have worked fine.
If you do get some reports that Catapult by default formats
somewhat oddly it’s worth taking a look at the layout of the
original IBM i report. When changing the original report is

- 106 -
 difficult or impossible (because it’s a canned report shipped
with a software package, for example) then you can use the
page layout overrides in Catapult to compensate.

So let’s go back into our rule and modify the PDF page layout defaults to see if we can
improve this somewhat.

Overriding the PDF Document Setup Defaults

If after downloading your default PDF report you find that it does in fact need some
adjustment, begin by clicking on the ‘Override Default Values’ option. Once you have
done this, you can choose the Paper, Margin and Font Control options that are best
suited for your report.
Action Item: For this exercise, go back into the Document Setup options of your grab
rule and start by clicking the Override Default Values option. Then make the following
changes:
□ Change the page orientation from Portrait to Landscape.
□ Change the font and leading to 12 point.

Leading (pronounced ‘ledding’) is the vertical space allocated

to each line of text in the report. You should usually set it the
same as the font size (or greater). If your leading value is too
small the text may be unreadable. If you set the leading to zero
your report will display one very dense line at the top of each
page.

□ Change the font to Courier New, if it isn’t already.

□ Set the right and left page margins to .50 inches.
The next page includes an illustration of this window with the completed changes.
Your finished options should look like this:

- 107 -
Figure 5-6. Adjusting the default file settings.

Action Item: Click OK to save your rule. Then re-run your report (CALL XL_
CATAPLT/CATITEMS) on the IBM i and manually trigger a polling cycle.
When you get your report this time it should look something like this:

Figure 5-7. The adjusted Catapult report, showing the font and layout changes.

- 108 -
 Using the tools available in Catapult you should be able to fix most report formatting
problems that arise as a result of converting to a different file type.

PDF Bookmarks
Another useful feature that you can add to your PDF files is bookmarks. Let’s quickly walk
through an example.
Action Item: To begin, inactivate your grab rule by clicking it once and pressing F2.
Then re-run your report once more on the IBM i, so we have a matching report that we
can work with in the Console.
Now open your rule and go to the Bookmarks section of your Transformation options.
This is how this section looks before making any changes:

Figure 5-8. The default PDF bookmarking options.

For PDF documents bookmarks are automatically defined for each page in the
document. However, you can also manually add bookmarks to key values that you select
in your report.
Action Item: Select the second option shown above, to add bookmarks in order of their
appearance within the document.
When you do this, Catapult enables Bookmark Anchor and Key Selection options.
The easiest way to set up your bookmark key and anchor values is from a preview of
your actual report. You need to identify the key value to use as a bookmark, and a
constant text string that the poller can use to locate the iterations of the variable key
value within the report body.
Action Item: Click the View Document option to have Catapult locate and load a preview
version of your report.

If you have multiple versions of a report on your system, the

Grab Rule Editor will prompt you choose one of them before
loading the window illustrated below.

- 109 -
Here is an illustration of our document preview:

Figure 5-9. Using a report preview to define the bookmark key and anchor values.

The preview window has loaded the first few pages of the report, which should normally
be enough for you to find the values for your bookmarks.
In this report we want to create bookmarks for the Inventory Categories. For each
bookmark we need to identify the changing key value, as well as a constant text string
that Catapult will use to find it.
Here’s how we select the key anchor:

- 110 -
Figure 5-10. Adding the bookmark anchor.

Action Item: Highlight the text string ‘Inventory Category’ (item 1 above) and then click
on the key anchor button (item 2 above).

You can also highlight the text string and then right-click to pop
up a menu of options, including the option to mark the text as
your Anchor Text.

When you click the icon, you should see the results shown in the Anchor Text field at the
bottom of the screen (item 3, above).
Now you need to also select the key.

Remember that the page of text shown above is just a preview

of the first few pages of your report, so you need to make sure
you select a large enough area to include the full length of the
actual key field.

Action Item: Highlight the area occupied by the key field in our report, and then right-
click and select the Set Bookmark Key Location option:

- 111 -
Figure 5-11. Selecting the Bookmark Key Location.

Action Item: In the Status Bar you can see the current cursor position. For this example,
the field starts in position 21. Knowing that the database key field is 10 characters long,
mark an area that extends to position 32.
Once you have selected both values, the areas should be highlighted, as well as both the
toolbar buttons:

Figure 5-12. Confirming that both required values have been set.

Action Item: Click the OK button (Figure 5-11, bottom right corner) to save your changes
and return to your grab rule.
In your grab rule, you should see something like this:

Figure 5-13. The bookmark data, back in the grab rule editor.

Now you’re done with this and ready to test this feature.

- 112 -
 Action Item: Save your rule. If necessary, activate it from the list. Trigger an immediate
poll, and check your email again.
Now your PDF should look something like this:

Figure 5-14. Report showing the generated bookmarks for our selected key.

PDF bookmarks are a very useful tool, particularly for navigating lengthy reports. The
section “Bookmarks” on page 248  includes another example of how to use the Preview
window to set up bookmarks in your generated document.

PDF Options
PDF files also support a number of options that allow you control access to the file, and
whether different types of changes are allowed for the file. In addition, there are a few
informational document properties you can set.
Action Item: Open your rule once more and go to the PDF Options:

- 113 -
Figure 5-15. Reviewing the PDF file generation options.

Compress Text and Graphics

The first option here is set by default; you should always compress your PDFs. For
additional details, please see the section “PDF File Options” on page 251 .
Encryption and Document Fields
We won’t bother setting any of these values in the tutorial, but if you’re familiar with PDF
documents, you can experiment with these. The encryption options allow you to
password-protect the PDF and control whether the file can be edited or copied.

One technique for creating passwords is to include a

replacement value with a string extracted from the report
itself. This way you can automatically set unique passwords
for various versions of a report. This example is described in
the section “Extracting and Using Report Data Values” on
page 229 

Remember that here and most places where you can insert text in
your grab rules you can right-click to insert any of the supported
replacement values!

For detailed descriptions of what each of the encryption options do, please refer to the
section “PDF File Options” on page 251 .

- 114 -
Adding Overlay Images
A further option available when you distribute a document in one of the enhanced
formats is the ability to add an overlay image. For example, if you are converting invoices
to PDFs for distribution by email, you can overlay your standard invoice form and
headings onto the report data. Let’s try that next.
Action Item: Click on the Overlay menu entry, to present the options below:

Figure 5-16. Adding overlay images to a grab rule.

Action Item: There are many different overlay options, but for this exercise choose one
of the most commonly used: “First image for page one. Second image for subsequent
pages”.
Action Item: When you install the software two sample images are included in the
Catapult Poller directory. Enter the following values for the two paths (you can browse for
these instead of typing in the path):
□ Image 1: C:\ESDI\Catapult 7\Documentation\OverlayPage1.jpg
□ Image 2: C:\ESDI\Catapult 7\Documentation\OverlayPage2.jpg
You may need to add \Program Files\ or \Program Files (x86)\ before ESDI\.
This is a fairly typical setup, where on the first page of a report you may include some
standard information on a particular page layout, while the remainder of your report is
just a data listing.
Testing the Overlay Images
Action Item: Once again, save your grab rule and re-run your report. Then trigger an
immediate poll and wait for your updated PDF.
When you get it, it should look something like this:

- 115 -
Figure 5-17. A sample PDF with overlay images used.

In this illustration you can see the first page of the report, with our first overlay, and the
next two pages with the second image.
Using PDF Page Setup Options with Overlay Images
The use of overlay images is another example of where the page setup options can
come in handy. Sometimes your reports may be designed by one group of people while
your company logos and forms may be designed by someone else. And if these two
groups can’t get together to make things line up perfectly, you may be able to fine-tune
the fit, layout and alignment using the page setup options.
Form overlays are discussed in more detail in the section “Overlay Images” on
page 254 , Report Transformation Options.
Now you can continue with the next chapter.

- 116 -
 - Splitting Documents and Reports

CHAPTER 6

Chapter 6 - Splitting Documents and Reports

In the previous chapters we first looked at how you can set up a basic grab rule, and then
we added a number of formatting enhancements to the catapulted report. In this chapter
we will split our report into sections so we can send each section to a different person.
Before we begin, here are brief explanations of two terms we will be using in this chapter:
□ Document Splitting allows you to also break downloaded spool files into
sections, either for saving or distribution. The extracted portions can also be
grouped together when a recipient has several associated key values, and/or
processed individually before distribution by the PDF writer..
□ Data Extraction allows you to select values out of your report to be used in
either the distribution criteria for the report, or in the attributes of the reports
themselves. Common examples of this feature are extracting the intended
recipient’s fax number or email address from the report body.
This chapter walks you through the basic steps for splitting a report and using parsed
values in the grab rule.

- 117 -
How Splitting Works
When you set up a report for splitting there are a few fundamental concepts to
assimilate:
□ You need to define where you want each report section to begin and end. If you
consider a typical example of splitting invoices, each invoice will include similar
headings and footers. You need to create your grab rule to include the exact
spot in your reports where one section ends and another begins.
□ And when you are splitting a report into sections, you also need to identify when
a report should be split. Catapult determines when the report should be split by
identifying a changing value in the content. This value may be a key field such as
department number or customer number, an email address included on the
report, or another text string.
□ Finally, you need to determine who each section should be sent to. Catapult
provides the flexibility to determine the distribution details (email address,
printer, fax, etc.) for each report section by either extracting it directly from the
report or using a key value cross-reference table. Similar options are available
for setting several grab rule distribution options.
Beyond these basic options, there are also a number of other related options you can
take advantage of. Some of these are described in the following pages and the rest are
discussed in , Document Splitting Options.

Exercise Overview
If you look at an example of the sample report we have been distributing you can see that
includes several different inventory categories: AMPS, BANJO, BASS, GUITAR and so
on. In this exercise we will first create a new distribution group with several entries for the
different sales people at our company, and then we will send different sections of the
report to each sales rep. Along the way we will also look at a few other features that we
haven’t tried out yet.

- 118 -
Creating a New Distribution Group
Our first task is to create a new group that will represent our sales staff. We will have a
sales staff of three people, each with a different specialty. When the inventory status
report is run, each of our sales team members will get the sections pertaining to the
areas they are responsible for.
Action Item: To begin, go to the Catapult Console and click on the Work with Distribution
Groups button in the toolbar (the first in this set: ). At the list of groups, click the
Add Group button, and add this group:

Figure 6-1. Creating a new distribution group for the split rule.

Action Item: Our group is called ‘Sales’, and the description is ‘Wholesale Harmonics
Sales Staff’. Click the OK button to create the group.

If someone else at your site has already gone through these

exercises and the group ‘Sales’ already exists, use any other
unique name.

Action Item: After you create the group, Catapult presents an (initially blank) list of
entries. Click the Add Group Entry button.

Adding the Group Entries

Action Item: For this exercise we will stretch the limits of our imagination in asking you to
name your Sales representatives as follows:
□ Aldo Amps
□ Betty Banjo
□ Oliver Other
Aldo will get the AMPS section of the report, Betty the BANJO, MANDOLIN and VIOLIN
sections, and Oliver will get the rest.
While you could find other people in your organization to participate in this exercise with
you, the simplest option is to use your own email address for all three entries. Then it will
be easy for you to check the contents of each section. What is important is that each
entry have unique key values.
Let’s take a look at those key values now. Here is an illustration of the group entry
window:

- 119 -
Figure 6-2. Adding a new group entry.

Action Item: Enter the data above (substituting your own address for the email address).
Use the Add button to create a key value of ‘AMPS’ (upper case, no quotes).
When we later set up the split criteria we’ll identify the location of this key value in the
report. When the splitting engine encounters it, it will break the report from that point until
a new key value is encountered.
Action Item: Finish adding the entry above. Remember to use your own email address.
That and the key value are the only critical values at this point. Click OK to create the
entry.
Action Item: Then add two more entries as follows:
□ Betty Banjo, with these key values: BANJO, MANDOLIN and VIOLIN.
□ Oliver Other with these key values: BASS, GUITAR and STRINGS.
While much of the data in these group entries is different, you can save yourself re-typing
your email address by copying the entries.
When you finish all these steps you should have a distribution group called Sales with
three members:

- 120 -
Figure 6-3. The completed distribution group, showing the three entries.

Action Item: Click OK at the window above to return to the list of groups. Then close that
window to return to the console.

- 121 -
Creating a Split Rule
We’ll begin creating our split rule by copying our previous rule so we can leverage all the
formatting options we’ve already set up.
Action Item: At the Catapult Console right-click the rule you created in the last chapter
(description Distribute Formatted Item Listing) and select the Copy Rule option.

Preliminary Changes
Before going ahead with setting up the split options, let’s remove some of the extra
formatting options we had added, so we can more clearly see the effects of our report
splitting.
Action Item: After the copy is added to the list, open the new rule and make the changes
below. Then continue with the instructions that follow:
□ Change the Rule Description. Change the Rule Description to ‘Split and
Distribute Formatted Item Listing’.
□ Confirm the Rule is Inactive. Just below the Rule Description is the Rule
Status: confirm it is inactive.
□ Change the Rule Selection. We’ll be running this exercise over a slightly
different version of the report (with page breaks before each inventory category
change), so at the Spool File Acquisition settings, change your selection criteria
from ‘CATITEMS’ to ‘CATITEMS2’.
□ Change the Updated User Data. Still at the Acquisition options, change the
updated user data value from ‘FORMATTED’ to ‘SPLIT’.
□ Turn off Normal Emailing. Go to the Email Distribution category and uncheck
the Enable Base Document Emailing option.
□ Save your Changes. When you’ve made the last change above, click OK in your
grab rule to save these changes.
After completing the steps above, go to an IBM i session and run the command CALL
CATITEMS2. Then make one more change to your rule:

□ Rebuild your Bookmarks. In the previous tutorial chapter you created

bookmarks based on the Inventory Category. This grab rule will split the report
along those lines, so re-create your bookmarks to list the Category Group. If you
need help with the steps, check back to the section “PDF Bookmarks” on
page 109 . Save the rule.

Turning on the Split Options

Action Item: Once more open your new rule and this time go to the Document Splitting
category:

- 122 -
 Figure 6-4. Enabling the report splitting option for your grab rule.

Action Item: Click the checkbox indicated above, to enable splitting in this rule.
When you do this, Catapult enables the two subcategories.

Setting Where Each Split Section Begins and Ends

Action Item: After you enable the report splitting features in this rule, click Next to work
with your Segments Options. These options control where your report(s) will be split:

- 123 -
 Figure 6-5. Beginning to establish the segment start and end specs.

For our example we’ll be using the Custom Splitting features. The other options here are
described in the section “Splitting Option” on page 212 .
To begin defining a split rule you need to set the beginning and ending points for each
section. If split sections may span multiple pages, you could choose part of the page
header as the start segment, and a total line as the end. Or, for the Segment End Text
you can also choose *STARTTEXT and Catapult is smart enough to ensure that it doesn’t
break until the key value associated with that section changes, even if the section runs
for several pages and the key value is repeated on each new page.
If you are using a form overlay with your split section, you can also use the special value
*STARTOFPAGE to ensure that each section begins right at the top of the page. When
you select this value, Catapult also checks whether a key value has changed before
ending the split section.
If each split section is only going to be a portion of a page you should choose a snippet of
text that is repeated for each entry.
To fill out the values here, you need to load up a copy of your report and select sample
lines from it. Let’s do that next.

Using the Preview Window to Set up Split Criteria

Recall that you ran your report once at the start of this chapter, so a copy should exist
that matches our acquisition criteria.

- 124 -
Actions Item: In the Catapult Grab Rule Editor click the View Document button near the
top of the Segment Options tab (see Figure 6-5). If you only have a single iteration of this
report the wizard should pick it up automatically and load the preview (if you have several
versions of the report on your system Catapult will first prompt you to pick which one you
want to use):

Figure 6-6. The Catapult Preview window, showing the first few pages of the sample report.

Setting the Segment Start

One of the differences between CATITEMS2 and the previous version is that in this report
each Inventory Category begins on a new page. We’ve made this change so that our
overlays work as expected, and so we don’t send any of our sales people page
fragments.
What this means is that for the Segment Start, we could do either of two things:
□ choose the special value *STARTOFPAGE, to indicate that each section will
begin at the top of the page, or
□ choose a constant value that appears in our page headings as the start location.
For this example let’s try using constant values to familiarize ourselves with how this
works.
Action Item: Select a portion of the page header that won’t occur on any other report
lines, as shown here:

- 125 -
Figure 6-7. Selecting a unique text string to find the top of every new segment.

The segment start text is identified using the text content and column values. So if you
select just a single letter, for example, you run the risk that that letter occur in that column
at report locations other than the header.
Action Item: [These instructions are also illustrated in the image above.] Highlight the
first instance of a unique text block that will appear at the top of every report section, then
right-click the selected area and choose the first option (as shown above) - Set Segment
Start Text.
When you do this, you’ll see Catapult change the highlighting to a different color. You
may also notice that one of the toolbar buttons (corresponding to this option) is now
outlined.
The text we selected for this tutorial is ‘Catapult Demo Report’ beginning at column 24.
Setting the Segment End
For the report in our example there are two ways we can select our segment end text:
□ The easy option is to select the special value *STARTTEXT. This means that it will
end a section once the key value has changed AND the splitter hits the start text
again.
□ The other way to do this is to find a unique piece of text that appears at the end of
our report. In our example, there are Inventory Category totals on page 3 of the
report, so we could use those as our end text.
Action Item: This time let’s go with the simpler option: Click OK to close the Preview
window and once you’re back in your grab rule change the Segment End Text option to
the special value *STARTTEXT.

- 126 -
 One important consideration when defining the split start
and end values is that the key values for each section must
occur within the section delimited by the start and end
segments. Catapult cannot use a key value or email address
that is outside the section of the report being sent.

Identifying the Section Key Value & Location

The next step is to identify the key value for each section of the report, and tell Catapult
how to reliably find that value. These options are found in the second area of the
Segment Options, the Segment Anchor and Key Selection (see Figure 6-5).
Action Item: Again, the best way to populate the options here is via the document
preview. From the Segment Options category, click the View Document button once
more. This is our report:

Figure 6-8. Taking another look at the preview to define the key anchor and key values.

Notice that our Segment Start Text value is already shown as selected.
In our report the unique key value for each section is the Inventory Category. And
because this value is a variable (AMPS, on page 1 above), we need to find an
unchanging piece of text that occupies a constant location with regards to this value.

We call this text constant the ‘Key Field Anchor’.

Fortunately, that’s easily done.

- 127 -
 Action Item: In our report the text string ‘Inventory Category:’ is always immediately to
the left of the key. Highlight that text now and click the third button in the report splitting
toolbar, as shown here:

Figure 6-9. Selecting the key anchor text.

Action Item: After selecting the key anchor, we need to highlight and select the key value
itself. Do this as shown here:

Figure 6-10. Selecting the Segment Key Location, and using the right-click menu option.

Notice that because we know the key value can be up to 10 characters long, we’ve
selected that many spaces in our report.

The information above is critical: if you don’t select the

correct, complete length of any possible key value, you may
get incomplete or incorrect key value matching in your
results. Make sure you’re familiar with the possible range of
values before setting this up and saving your rule.

Action Item: When you finish with setting the field above, click OK to exit the Preview
window.

Choosing a Split Section Distribution Group

The final step is to select a Distribution Group.
Recall that at the start of this chapter we created a new distribution list with three sales
people. The reason we need that group is because the report itself doesn’t include the

- 128 -
 email address of the sales person responsible for each inventory category. If that
information was on the report we could have created an extracted data value for that
field.
By adding distribution list entries with key values corresponding to the report keys, we’ve
can create a cross reference between our sales team and the contents of this particular
report.

Your distribution list entries can include key values from

several different reports. Just add the key values to the list and
Catapult will scan through all the values to find one that
matches the value extracted from the report it is currently
processing. So the same list of sales people could be used with
a report sorted by Inventory Category and another sorted by
Customer Type.

Action Item: Select the group Sales as your Key Group:

Figure 6-11. Attaching a distribution group with key values corresponding to this report.

The easiest way to select the group is to browse for it in your list.

Action for Unassigned Split Sections

Action Item: After picking the distribution group, click the Next>> button to advance to
the Unassigned Segments section of your rule, shown here:

- 129 -
Figure 6-12. Setting an action for unassigned report split sections.

Here is where we can instruct Catapult what to do with unassigned report sections (that
don’t match any key values we have defined).
Action Item: Select the third option and type your own email address.
A rule will generate unassigned sections if Catapult can’t connect the key value for a
report section with a matching recipient. This could happen for a couple of reasons:
□ You didn’t set up the key location correctly. Common issues with setting up
the keys for split sections include using a key anchor text string that isn’t
constant, specifying an incorrect line offset between the key and the anchor text
(when they’re on different lines) or basing your key value length on a sample key
that isn’t typical of the actual range of key values.
For instance, as an example of this last situation, in this report the first section’s
key value was ‘AMPS’. If we had only designated 4 characters for our key length
then most other extracted keys wouldn’t match the values set up in our
distribution group.
□ Missing recipients or key values in the distribution group. We would also get
orphaned sections if we didn’t add all the necessary group entries, or there were
key values in the report that we didn’t assign to any group entry.
Your choice for what to do with unassigned segments depends largely on how critical it is
that your report sections be distributed:
□ If every report section should have a recipient you can use any of the three
notification options (emailing someone, or printing a list).

- 130 -
 □ In some cases, however, a number of mismatched sections on each iteration of
a report isn’t unexpected, and if the information isn’t critical, you can choose the
first option (“Don’t process”) to just drop them.

When you first set up and test a new split rule you should always
initially set the rule to send you the unassigned segments.
This will help you troubleshoot any initial problems with your grab
rule or distribution list setup, until you have confirmed the rule is
working as expected.

- 131 -
Setting the Split Section Email Options
Now that we have set up the options to handle the splitting itself, we need to choose our
distribution options for the split sections.
Action Item: Go to the Email Distribution options and click the Split Document(s) tab.
Then check the Enable Split Document Emailing option:

Figure 6-13. Enabling the email distribution method for report split sections.

Now you can set the rest of the options.

Setting the Target Address for Each Split Section

The Addresses and Subject tab (shown above) allows you to set the various email
addresses associated with the distribution. The Target Address is of course the most
important.
Action Item: We are sending the split sections to the email addresses in our distribution
group. All you have to do here is select the Group option:

Figure 6-14. Selecting the group for report distribution.

- 132 -
 This option instructs the splitting engine to
1. Identify the key value in the report.
2. Scan the distribution group until it finds an entry with a matching key value.
3. Send the appropriate portion of the report to that address.

Setting the Split Subject

Just below the Target Address field is the email subject. Your choices for the split subject
are:
□ To enter a user defined subject here. This can be a static value or include
replacement and extracted data values.
□ To use a value extracted from the report text. If you select this option you can
use the Preview window to select your value. When you use this option each of
your split sections can have a subject that includes the current key as well as
some other variable text from the report.
For now just enter a user-defined value that incorporates a replacement value.
Action Item: Type “Item Listing: Inventory Category ” in the subject field. Then right-click
in the field and select the Insert Replacement Value menu option:

Figure 6-15. Building an email subject by combining static text and replacement values.

- 133 -
 This right-click option is available wherever replacement values are
valid.

When you select the option illustrated above Catapult presents this window:

Figure 6-16. The list of available replacement values.

Action Item: Scroll to the bottom of the window and select the first Split Segment Value,
&K, and click the Select button at the bottom of the window.
Your resulting subject should look like this:
Item Listing: Inventory Category &K

You can also add other values if you like. Then continue with the next section.

Setting the Email From Address

Your Catapult Poller Configuration has a default return address for all distributed email.
You can also set up a custom return address for each grab rule, or even for each split
section.
Your distribution From email address is just below the email subject.
Action Item: Click the User Defined option and type your email address:

- 134 -
 Figure 6-17. Adding a From address to the reports that will be sent.

When you feel that the Catapult Poller default (specified in the poller configuration) it too
general, the easiest alternative is to enter a user defined address.
You can also use extracted data values to pull a From address directly from a report. Or
you can create another distribution group for this purpose. For example, if each
inventory category also had a product line manager associated with it, you could define a
distribution group for those people, and reference that group in your grab rule. Then
each sales person would appear to get their inventory listing from their direct supervisor,
and when they replied to the message, it would automatically go to that person.
Once you finish with your address and subject option, continue with the section below.

Attachment Options
Action Item: Click the General Options tab (within the Split Documents tab). There are a
number of useful features you can access from the Split Documents General Options
tab, illustrated here:

- 135 -
 Figure 6-18. Setting the options to control how attachments are processed.

All these options are described in detail in the section “General Email Options” on
page 279 . For now we’ll just use the first couple of options.
The default distribution option (suitable for most rules) is to include the report as an
attachment. When you distribute reports as attachments, Catapult enables the Text field
so you can type what the attachment description should be in the listing in the email
body.
Action Item: Copy your email subject into the Attachment Text field. Then, for the
Attachment Control , select the third option - to send each attachment in an individual
email.
If you’re wondering why we’re not using the more efficient option, which is to combine
attachments in a single email, recall that in your mock distribution group (Sales) you
actually just used your own email address for all three group members. Catapult is smart
enough to notice that, and as a result, by default will combine all these report sections
into a single email. If in your Sales distribution group you did in fact use three different
email addresses for your entries, then you can go ahead and select the option to
combine attachments.

Finishing Up and Testing the Rule

Now we’re ready to save our rule.

- 136 -
Action Item: Click the Apply button to validate and check whether you’ve accidentally
missed any critical values. If not, go up to the General category in your rule and change
your Rule Status to Active. Then click OK to save your grab rule and close the editor.
Now we’re ready to test the rule!
Action Item: Confirm that you still have a spool file in your queue with user data of
CATITEMS2. If not, add XL_CATAPLT to
your library list and re-run your report with this
command: CALL CATITEMS2. Then trigger an instant poll using the console’s button.

- 137 -
Monitoring the Catapult Poller
Because this rule is actually performing a few different functions, we can learn something
about how Catapult works by monitoring its status as it’s processed.

Reviewing the Request List

Action Item: To start, put your cursor over the Request List tab at the bottom of the
Console’s list of rules. Within a second or two Catapult pops up the Request List:

Figure 6-19. Reviewing the Request List.

Click the pin icon in the top right corner to pin the window open while you work with it for a
few minutes.If you don’t pin it open, it will close when you mouse away from the window
area.
In the example above, our rule processing was stopped because of an error. To display
the error(s), you can click on the + symbol to the left of the message.
Here is what is shown:

Figure 6-20. Displaying the details for a request error.

- 138 -
 Whoops! It looks like in our zest to take accurate screen shots for this guide, we left the
sample email address in our distribution list. It turns out that
larry.finklestein@finklebert.co.uk is not in fact a valid email address, so our grab rule was
unable to send the reports.
In this case, the solution is to correct the distribution group and re-submit the rule. To re-
submit a rule in error, you can right-click on it and select that option.
In your own case, if you have followed the instructions in this tutorial and entered
everything correctly, you may not see anything at all in the Request List window because
the rule has already been processed. What you may have to do to see any messages
above is:
1. CALL CATITEMS2 again.
2. Trigger a polling cycle (by clicking the green arrow button in the console).
3. Click the Reload button in the Request List area repeatedly until you see the
messages starting to accumulate.
If your PC and IBM i are very fast, you may have trouble catching the process in mid-flow.
In the illustration above you can see that for our grab rule we do have several other
messages showing the status of the different processes in the grab rule, and you can
see that the spool file split sections are being created.
When the process concludes, the records are removed, and a history record is written.
Let’s check that next.
In our own case above, after correcting the distribution list, we re-submitted the request
(which sets the entry above to Pending status) and then triggered another polling cycle.

Reviewing the History List

The History List tab allows you to review all the requests that have been successfully
processed.
Action Item: If you pinned the Request List window in the console, unpin that now and let
it disappear. Then click the History List tab and pin it open.
Our history list (after a few test runs of our rule) looks like this:

- 139 -
 Figure 6-21. Reviewing the Catapult distribution history list.

In the illustration above you can see three header records similar to those we saw
previously in the request list. The third record has been opened (by clicking the + symbol
on the left) to display the details of that distribution.
We won’t review this interface in detail now, but the most important things for you to know
are the following:
□ The existence of a record in your history listing tells you that the spool file has
been processed. In the example above, we can see from the entry how many
sub-sections were processed and who they were sent to.
□ Catapult uses this history list as a means of verifying whether a particular spool
file has been processed already or not. So deleting history records is a quick way
to get Catapult to re-process a report. Note that in this case, that wouldn’t work,
because we’re selecting based on the User Data, and we’re changing that value
within the rule processing (as indicated by the last message above - Change
User Data to Split.).
On the next page we’ll take a look at the email sent out by our rule.

The Emails Created by the Split Rule

When you get your email, they should look something like this:

- 140 -
 Figure 6-22. Reviewing the email sent by our split rule (sending to a single address).

We received 7 separate emails, one for each report section. Note the following (either in
the illustration above, or in the email you receive yourself):
□ The email subject includes our variable key value.
□ The report has been sent as an attachment, with the name we selected. Note
that the attachment count and body text vary depending on your Poller settings.
□ Based on the varying sizes of the attached files (the column on the right), it would
appear that our split rule has been successfully, and the report has been broken
up into sections by key.
□ Because we rule’s settings were correct, we didn’t get any Unassigned Segment
emails.
Next let’s look at the actual generated reports.

The Reports
The last step is to check our reports. Here is the first report, for the category AMPS:

- 141 -
Figure 6-23. An illustration of the PDF file generated for this report.

You can see that this particular PDF file is three pages long, and includes just the section
for the category AMPS. In addition, our overlays were correctly applied (you may or may
not have the overlays, depending on your starting point for building this rule).
Action Item: Open a few of your own reports and confirm the contents.
This concludes the main portion of our tutorial. There are many other options you can try
out with the report splitting; if you like, you can experiment with this rule, or a copy of it.

- 142 -
Other Grab Rule Options
In the first three tutorial exercises you have learned about most of the basic features in
Catapult. The remaining tutorial chapters discuss how to set up Catapult grab rules to
use a Data Extraction tool to extract the data elements from your report and create a
Microsoft Excel spreadsheet, and how to export reports to the Nexus ECM. Even if you
don’t have Nexus right now, it’s worth spending a few minutes reviewing these features.
In the case of Nexus, many of our Catapult customers end up looking for a secure way to
make downloaded files available in a web browsers, and Nexus provides that.
But here are some recommendations on other important areas of the tool you can
familiarize yourself with, and features you can try out. As you try these, you can use them
with your own, new grab rules, or add them as features to the existing rules you’ve been
creating in this tutorial.
□ Report Compression. In the Transformation options is an entry where you can
set your compression options.
□ Data Extraction. You can also set up rules to extract information from anywhere
in your report body, and assign replacement values for these variable strings.
Then you can use these values anywhere in the report. This feature is described
in the section “Extracting and Using Report Data Values” on page 229 .
□ Printing Reports. You can also set up grab rules to distribute reports to a printer.
Try doing this with a report converted to RTF format.
□ Converting Reports to HTML. Use the grab rule in which you defined some
PDF bookmarks as a starting point to create and HTML version of the same.
□ Console Configuration Options. In the console, check the
Tools/Options/Configuration window. From here you can adjust the columns in
your spool file list, and many other options.
□ Poller Configuration Options. If you have gotten this far in the tutorial, then your
poller Configuration is working just fine. But there may be options you can select
to fine-tune performance. Spend a few minutes reviewing the configuration
options, and experiment with changing them.
By now you should be familiar with the core features of the software. If you continue with
the next tutorial chapters, you’ll gain a more in-depth knowledge of other useful features.
If you have any further questions about the software and its capabilities, please call our
Technical Support team. You can find contact information inside the cover of this book.

- 143 -
 - Creating Spreadsheets with Catapult & a Data Extraction tool

CHAPTER 7

Chapter 7 - Creating Spreadsheets with Catapult & a

Data Extraction tool

The “My Data is on the IBM i, But My Users Only Speak Excel®”
Conundrum
Here are some scenarios that might resonate with you:
□ Despite the existence of many adequate IBM i reports, your management and
end users refuse to work with anything but a PC file, and preferably Excel®
spreadsheets.
□ Your users submit frequent ‘variation on a theme’ report requests, and your
programming staff doesn’t have time to get to them all.
□ Even when you do produce the requested reports, a few days later you’re asked
to deliver something just a little different.
By using Catapult and a Data Extraction tool to produce a variety of broad, solid
spreadsheets, you can provide your end users with all the critical data they need and
allow them the flexibility of working with that data to produce the particular report they
require at the time.

Spreadsheets can be for Microsoft Excel® or Lotus, or created

as PDF or CSV files (among other formats).

From the Data Extraction tool select data to be exported to the spreadsheet.
Action Item: Once you have created your reports, go back to the Catapult Console and
trigger an immediate poll – . When you do this, you can also monitor the progress of
your requests using the Request and History list windows (as you learned in the earlier
tutorial chapters).

- 144 -
 - Using Catapult with Nexus

CHAPTER 8

Chapter 8 - Using Catapult with Nexus

When you first start using Catapult, you will likely be using it to meet a particular need
within your organization. You may need to get status reports to your managers by email,
or you may need to archive a certain kind of report to a file server, or just to cut down on
printing paper reports. But over time the uses for Catapult within an organization seem to
multiply and expand, as more and more people realize what it can do.
It is usually a good thing to have information delivered into your hands in a timely
manner. However, if you are getting too much information, then managing it starts to
become an issue.
This is where Nexus comes in.
What is Nexus?
Nexus is Fresche Solutions Award Winning web portal. Nexus is designed to make
maintaining and managing corporate Intranet or Internet sites easy. It allows you to
implement site-wide security, determine an overall look and feel for all pages, and
provide a 'portal' or common launching pad for all pages and applications. Nexus also
includes value-added features such as calendars, navigation menu trees, etc.
Nexus runs entirely within a web browser, meaning that you can access Nexus from any
PC at any time, anywhere. You don’t have to install any software or download any
utilities. You just type in the web address and log in.
The central feature in Nexus is the Enterprise Content Manager (ECM). The ECM allows
you to archive documents to a directory in your IFS and then build a structure around the
files to control who has access to them and the way in which they are viewed.
The Nexus ECM supports two types of interface:
□ A Windows Explorer-like interface where users can work with documents within
folders.
□ A search-based interface, where the Nexus administrator can pre-set search
criteria controlling what files are shown, and grant users appropriate authorities
to the documents they need to work with.
Catapult supports the ability to create grab rules that automatically populate specified
Nexus Enterprise Content Manager document sets. All you have to do is build your initial
selection criteria and authorities in Nexus, and then create a Catapult grab rule that

- 145 -
 matches a set of IBM i spool files with that criteria. Then your Nexus users will
automatically and instantly have web access to reports created on the IBM i as soon as
they are processed by Catapult.
Nexus complements the functionality of your existing Catapult grab rules. If you use
Nexus, your users can receive their reports instantly, and also access them later at any
time in a web browser, behind a secure login.

Downloading and Installing Nexus

For a complete overview of Nexus, and the Enterprise Content Manager, please review
the Nexus User Guide. You can request a free trial from
https://www.bcdsoftware.com/downloads/ibm-i-solutions/?software=3. After
downloading the software, review the Read Me file in the install utility for instructions on
how to install and configure Nexus. Once you have installed the product and confirmed
that it is up and running, continue with this section.
This chapter begins by describing and illustrating the processes required in Nexus to set
up the ECM for a user. The next chapter describes the Catapult grab rule features that
link to Nexus.

Tutorial Instructions
The remainder of this chapter follows the tutorial format of the previous chapters. Action
items are again identified with appropriate headings.

- 146 -
Setting up the Nexus ECM to Receive Catapult Files
The process of integrating Catapult and Nexus begins with building a home in Nexus for
the reports you will be selecting and processing with Catapult.

Logging in to Nexus
Action Item: After installing Nexus open a browser window and type in the following
URL, where the x’s represent the IP address or domain name of your IBM i:
http://xxx.xxx.xxx.xxx:8010/nexuspublic/nxlogin.pgm

For further details on the login process please refer to the first
chapter of the tutorial in the Nexus User Guide.

Log in as the Nexus Administrator (nexusadmin/NEXUSADMIN). When you log in Nexus

presents a Welcome page similar to this one:

Figure 8-1. The Nexus Welcome page.

This is a page from the Nexus Enterprise Content Manager (ECM). The window on the
left is an ECM Navigator portlet, listing the files you can access. The ECM Viewer window
on the right is displaying the contents of the first folder in the list.

- 147 -
 To get started, we’ll create an area in the ECM where we’ll add our Catapult reports, and
then we’ll define a search window that presents a subsetted list of them.

Creating a Catapult ECM Folder

Once you have logged into Nexus as a site administrator look at the icons in the upper
right of the ‘Welcome to Nexus’ window. If you are at the current release of Nexus, the
icons should include a wrench which will show ‘Edit Document’ when you mouse over it:

Figure 8-2.

Action Item: Click the button. When you do this, this window (or tab) opens:

Figure 8-3. Maintaining an ECM folder or file.

When the window first appears, it displays the ECM record for the Welcome folder you
were just looking at. Now we want to create a new folder where we’ll put our Catapult
reports.
Action Item: To create the new folder, select the Create Folder option from the drop
down menu on the left and click Go. Create your new folder as shown here:

- 148 -
 Figure 8-4. Selecting the location for the new folder.

Action Item: For the folder name and description you can type ‘Catapult Reports’.
Action Item: To select the folder’s location click the Browse button to the right of the
‘Place in folder’ option and select the Top of Tree option (as shown). You can ignore the
rest of the options. Click the Add button to create the folder, and then you can close the
ECM Maintenance window by clicking the Close button at the bottom (this automatically
reloads the main portal page when you exit).
You should now see a Catapult folder at the top of your ECM Navigator:

Figure 8-5. The Catapult Reports folder is now shown at the top of the ECM structure.

Next we’ll adjust the ECM Administrator options so Catapult can add the files to the right
folder on your IFS.

ECM Administration Options

Action Item: Still logged in as the Nexus administrator, click the Manage Site link at the
top of your page. At the Site Management page scroll to the bottom and click the ECM
Default Settings link.
When you do this, Nexus presents a window with these options:

- 149 -
 Figure 8-6. Reviewing the default ECM settings that affect Nexus.

The first two options establish the link between Catapult and Nexus. When you install
Nexus, the first option should be set as /esdi/nexus/nexus/ecmArchive/. You don’t need
to change this.
Action Item: The second option, IFS Network Share Name, you do need to add yourself.
The value here should generally match your mapping to the IFS in Windows Explorer. In
the illustration above (for our system), it’s set to:
\\192.168.0.100\IFS\

If you aren’t sure what to type here, check with your network administrator.
Action Item: After confirming that these two values are correct, click the Update button
to apply your changes.

ECM Distribution Rules

The next configuration step is to create an ECM ‘distribution rule’. In its most basic form,
a distribution rule tells Catapult what to do with the spool files sent to Nexus. As we’ll see
later on, you can also add advanced search options to these rules that allow you to
create multiple, subsetted lists of files that you can present to your users.
To work with your distribution rules, you need to add the ECM Distribution Rules portlet to
one of your Nexus pages.
Action Item: To add the distribution rules portlet to one of your pages, click the ‘My
Pages’ menu item in the top right of the Site Management page.
Back at your Nexus content pages, click the Main Page menu option (from the My Page
menu):

- 150 -
Figure 8-7. Navigating to your main personal page.

Action Item: At the new page, click the Edit Mode link in the top right. At the page
presented, click on the Add Portlet link, shown at left below:

Figure 8-8. Adding an ECM Distribution Rules portlet to your personal page.

Action Item: In the Add Portlet window that appears, select the ECM Distribution Rules
portlet from the list available.
After selecting this item click the Add Portlet button at the bottom of the window.
Then click the Display Mode link (in the top right) to return to the normal viewing mode.
Your new portlet is below the calendar, on the right. You can minimize the calendar if you
like, to just view the ECM Distribution Rules portlet:

- 151 -
Figure 8-9. The ECM Distribution Rules portlet, before creating any rules.

Action Item: Now click the Add Rule option in the top left of the ECM Distribution Rules
portlet, to present the options shown here:

Figure 8-10. Selecting the folder where the reports will be archived to.

Action Item: Type a description for the rule. Then browse to find the Catapult Reports
folder you created. Select this folder.
Leave this window open and continue with the next page.
Defining the Rule Logic
In the distribution rule characteristics, notice that there is an option to define a rule. This
is where you specify the criteria that Nexus will look for in the files you send to the IFS, to
decide whether they match this distribution rule, and should be added to the folder you
selected.
Action Item: Click the Browse button to the right of the Rule box, and select the User
Data attribute at the bottom of the list:

- 152 -
Figure 8-11. Selecting the User Data as the starting point for our distribution rule.

When you click the User data search key Nexus will add ‘USRDTA=’ to your rule.

By default, this list includes a subset of the possible spool file

attributes on the IBM i. In a later section below we’ll look at
how to create and use your own search keys.

Action Item: To complete your rule, add the value CATITEMS to your rule. The completed
rule should look like this: USRDTA=CATITEMS. Then click the Add button to finish creating your
rule.
When you click the Add button Nexus immediately prompts you to define the authorities
for this rule:

Figure 8-12. Adding authority entries to the rule.

Click the ‘Write’ link indicated above to assign *WRITE authority to the group Everyone.
This will be adequate for our exercise.
Action Item: After you add the rule, click the Return to List button at the bottom of the
window. Your entry should now be in the list of distribution rules.

- 153 -
Adding Nexus Options to a Catapult Grab Rule
Now that we’ve set up the basic components in Nexus to receive our file from Catapult,
let’s go back to the Catapult Console and add the Nexus options to a grab rule.
For this exercise we will create a new, very simple grab rule that just selects the first
report we created in our tutorial. We could just as easily add the Nexus options to the
existing rules, but by doing it this way you can see exactly what the Nexus options do,
without being bombarded with email as well.
Follow the instructions below to create a new grab rule to use with Nexus:
Action Item: First of all, inactivate the rules you have created during the tutorial. To
inactivate a rule, click it and press F2.
Action Item: From the main console window click the Preview Spool Files button and limit
the list to show matches for the report CATITEMS:

Figure 8-13. Loading a list of report matching our selection criteria.

Action Item: In the list of spool files, find the report where the User Data is CATITEMS,
and select it by clicking it once. Then click the Instant Rule option (the light bulb in the
upper left).
Here is an illustration of this step:

- 154 -
 Figure 8-14. Creating a new rule over the latest iteration of our CATITEMS report.

When you do this, Catapult opens the grab rule definition wizard.
Action Item: In the grab rule options, add the following:
1. General Category. Type ‘Nexus ECM Item Listing’ for your description, and
verify that your rule status is ‘Active’.
2. Spool File Acquisition. Remove the Job Name from the selection options.
Near the bottom of the options, select the ‘Update user data with’ option and
change the value to SNT_TO_NEX.
3. Transformation. Add this target file name: Item Listing for &z at &v.txt (these
are replacement values corresponding to the system date and time).
Now continue with the instructions in the next section below.

Setting the Grab Rule Nexus Options

Action Item: After adding the options described above go to the Nexus distribution
options. Below is an illustration of the options available, after clicking the ‘Enable Nexus
Processing’ option and working through the instructions below:

- 155 -
 Figure 8-15. Creating the link to the Nexus site.

Action Item: Click the Enable Nexus Processing for Base Document option, and make
the following additional changes:
1. For your document description you can use the same text as you did for the
name: “Item Listing for &z at &v.txt”.
2. Select the Nexus product library and site. You will probably have a single
library and site available (usually XL_NEXUS/Nexus Default Site). These options
are presented as lists because Nexus supports the ability to run multiple,
independent sites out of different libraries.
We’ll look at the extracted values later in this chapter.
Action Item: Now click OK to save your grab rule. Then re-run the Catapult report (CALL
XL_CATAPLT/CATITEMS) a few times.

Checking the Distribution

Now is a good time to check the distribution tracking options available in Catapult.
Action Item: In the Catapult Console, open the poller Status window, the History listing
and the Request Errors listing.
Here is an illustration of these windows:

- 156 -
 Figure 8-16. Reviewing the poller status, as well as the status of our pending requests.

Action Item: As you monitor these windows, you can do the following:
□ You can start by clicking the Console’s Poll Now button.
□ Then you can follow the messages in the window as Catapult searches for your
spool file and attempts to process it. During this process you may also see a
message come up momentarily in your Request and Errors list (if you are
reloading it regularly).
□ Finally, you should see a message in your History list, indicating that the spool
file has been processed.
In the illustration above, we have intercepted an error: the profile we used to launch the
poller doesn’t have the right authority to access the IBM i IFS. So we’ll need to fix that.
Once you do see a History request, you can go back to Nexus and check for the arrival of
the report.

Verifying the Existence of the Report in the Nexus ECM

Action Item: Go back to the browser session where you are running Nexus and select
the Catapult folder (if you are no longer logged in, review the instructions at the
beginning of this chapter).
Your new report should now show in the list, in a format similar to this:

- 157 -
Figure 8-17. Reviewing the list of Catapulted files in Nexus (after several test runs).

Action Item: Now click on the link in the main window on the right.
And when you click on the report, Nexus loads it in the window:

Figure 8-18. Opening the uploaded report in the Nexus ECM.

In this view we have maximized the right column of our window, by clicking the little grey
bar between the columns (indicated by the arrow above).
Also notice the breadcrumbs constructed at the top of the page. These make it easy for
your users to always see exactly where they are in the ECM structure. Also, Nexus uses

- 158 -
 a unique URL to access every document, so your users can also bookmark a page
containing a report, and come back to it later.

Advanced Search Options

In addition to the features we have looked at in this tutorial section, Nexus and Catapult
also support the ability to filter based on key values extracted from the body of your
reports. These values can be linked with Nexus distribution rules that allow you to set up
customized views of generated reports.
For a detailed discussion of these features, please review the Advanced Document
Management section of the Nexus User Guide, and the “Distributing Reports to Nexus
Portal” on page 362.

- 159 -
 SECTION III
Console & Grab Rule Reference
In this Section:
Chapter 9 - Using the Catapult Console
Chapter 10 - Working with Catapult Console
Distribution Groups
Chapter 11 - Creating a New Grab Rule
Chapter 12 - Setting the Grab Rule
Acquisition Criteria
Chapter 13 - Document Splitting Options
Chapter 14 - Data Extraction
Chapter 15 - Report Transformation Options
Chapter 16 - Report Distribution

- 160 -
 - Using the Catapult Console

CHAPTER 9

Chapter 9 - Using the Catapult Console

This chapter describes the Catapult Console features available for working with grab
rules and their associated objects. The Catapult Console is a Client/Server program with
a Windows UI accessing IBM i data. You will use the console to perform the following
tasks:
□ Preview spool files that you would like to process and distribute.
□ Create and work with grab rules for selecting spool files.
□ Create and work with distribution groups (i.e. address book entries) for emailing,
printing, faxing and archiving.
□ Create and work with email header and footer text, to construct email messages
that have a consistent look.
□ Create and work with default title and footer pages, to attach standardized
content to your distributed files.
□ Browse the distribution request, error and history lists.
□ Check the poller status.
Almost all the data you work with in the console actually resides on your IBM i. If you have
more than one system you can select which one to connect to when you launch the
console. You can define a different set of grab rules for each IBM i on which you install
Catapult.
The next chapter describes how to work with distribution groups, and the following
chapters discuss all the options available when you create grab rules.
, Report Distribution and Tracking Options, describes the console features you can use
to work with the status of your distribution requests.

- 161 -
Using the Catapult Console
To start the console, go to the Windows Start menu and select Programs/Catapult
7.7/Console/Console.

It’s a good idea to get into the habit of starting the Console
from the Catapult Launchpad. From the launchpad you can
access many other Catapult features, including configuration
options and log files. Please see the section “Using the
Catapult Launchpad” on page 317  for further details.

When you do this, you are first prompted to connect to the IBM i, and then the console
presents a list of your current grab rules in a window similar to this one:

Figure 9-1. The Catapult Console, showing folders, grab rules and admin tabs.

Double-click folders to open or close them. Within the folders, the console displays the
description and status of each rule, as well as a subset of the selection criteria. Click on
the list column headings to sort the grab rule list by the contents of that column. All
Catapult lists support this type of sorting.
The console identifies grab rules with the following tags:
□ A green check mark indicates that a rule is active.
□ A gold lock indicates the rule has additional group or user security attached to it.
These tags provide an easy visual indicator of the status of your rules.
Keyboard Hotkeys
The console supports several keyboard hotkeys:
□ Press F1 to present the Catapult help.
□ If you click a rule you can press F2 to toggle it active/inactive.

- 162 -
 □ F5 refreshes the list of grab rules.
□ Use F6 to trigger an immediate poll on the connected poller (if one is running).
□ You can also use the Delete key to delete folders or rules you select from the list.
These hotkeys work in most Catapult interfaces. If you have any suggestions for further
hot keys to add, please let us know, we’ll be happy to add them!

The Poller Status, Request and History Lists

If you look at the Catapult Console in Figure 9-1 you can see there are two tabs along the
bottom left-hand side of the grab rule list and another near the top right.
Catapult 8 initially has the poller status, request and history list windows available as tabs
and dockable windows. From the console configuration you can also set a preference for
them be loaded as standalone windows.
Opening and Closing the Windows
Hover over the tabs to open the server status, pending request and history lists. To close
a tab, just move your mouse cursor off of it. You can also click to open a tab (which
focuses on it automatically) and click on the tab of an open window to minimize it.
Here is how the console window looks when you open the history list:

Figure 9-2. The History List tab expanded.

In this illustration you can see several records in our list, and the mouse cursor at the
bottom of the screen is hovering over the History List tab. When you move the cursor off
the tab, the window closes. Also, when you open one tab, the other non-pinned ones
close.
Re-displaying Tabs You have Removed
When you first install Catapult 8 the tabs for the server status, pending request and
history lists are visible in the console. However, because they are dockable windows, you
can also make them go away.

- 163 -
 If one of the tabs is not displayed, you can re-enable it from the View menu.
Setting the Default Tabs to Display on Startup
To choose which of these three tabs you want to include in the console on startup, go to
the console configuration options (Tools/Configuration). Check the box next to the tabs
you want to display in the console on startup. Click OK to apply your changes.
‘Pinning’ Windows
You can also "pin" a window open (which removes the tab). If you look at Figure 9-2, you
can see that in the top right corner of the History List window there’s a small pin icon.
When you click this icon you can then drag the window elsewhere in your screen, by
grabbing it by the heading bar:

Figure 9-3. Moving the History List window (unpinned).

In this illustration there are 4 small boxes on the edges of the screen that tell you the
positions into which you can drag the history list. The large shaded area in the middle
shows us where the window currently is–here we’re in the process of dragging it. As long
as you don’t drag the window onto any of the 4 arrows, it remains as a separate window.
But if you want to dock it against one of the sides of the console, drag it on top of one of
the 4 images in the small boxes above.

Adjusting the List Columns

By default, the console displays your grab rule number, description, creator and status.
The list also displays some elemental information about the spool file(s) that the rule will
process, including the spool file name, job name, user, user data, out queue and status.
You can adjust the columns displayed to include different information. To do this, go to
the Configuration option from the Tools/Options menu. In the configuration window,
select the Columns option, as shown here:

- 164 -
Figure 9-4. The list of columns displayed in the Catapult Console (Tools/Configuration).

From here you can check the columns you wish to display in the main list. Click OK to
apply your changes.
Other Console Configuration Options
There is a broad range of options you can set for your view of the Catapult Console. For a
complete descriptions of all the console configurations options, please review , Catapult
PC Component Configuration Options.

- 165 -
Working with Grab Rules
You can edit, view, delete, copy, print, resequence or switch a grab rule to a different
folder by:
□ clicking on the toolbar button corresponding to that operation
□ selecting that operation from the Edit menu
□ selecting the appropriate operation from the right-click popup menu
□ typing the key sequence corresponding to the menu option (Ctl+C, etc.)
There are also some additional shortcuts for creating, editing and displaying your rules.
These are described below.
Creating New Rules
To create a new grab rule, click on the New Grab Rule icon shown above (the leftmost
icon), type Ctrl+Insert, or select the option from the File menu.
Editing Rules
In addition, you can also edit a grab rule by double clicking an entry in the list, or selecting
the rule with Ctrl+Enter.
Displaying Rules
You can display a rule by selecting it and pressing Enter.
Inactivating All Grab Rules
The console Edit menu includes an option to inactivate all grab rules. This is primarily
intended to be used when you install a Catapult test environment. For additional
information, refer to the instructions in the Catapult Upgrader’s Guide.

Grab Rule Toolbar Options

Most of the console toolbar buttons are for working with your grab rules and folders.
Hover over the icons to display their functions.
Besides the standard Create, Edit, Display and Delete functions there are several others,
described below:
Copying Grab Rules
The Copy function creates a duplicate of the selected grab rule in the same folder. The
copy process appends the text ‘Copy of’ to the beginning of the rule description, and then
truncates the resulting text to 50 characters.
Copying allows you to use existing rules as a starting point for creating new ones, or
make back ups of rules before changing them. When copying a grab rule, the new rule is
automatically inactive.
Resequencing Grab Rules
Over time as you work with Catapult you may end up with many related grab rules that
when organized by sequence number are spread out all over your list. To allow you to
group related grab rules together in your list the console allows you to re-sequence
existing grab rule.

- 166 -
 To avoid any unexpected results, you need to end the
Catapult Poller before resequencing your rules, and then
restart it afterwards.

To resequence a grab rule you can:

□ right-click the rule and select the re-sequence rule option; or
□ click on a rule and type Ctrl+U; or
□ click on a rule and select the Re-sequence Rule option from the Edit menu.
When you perform any of these actions your grab rule list is refreshed and then a window
similar to this one is presented:

Figure 9-5. Resequencing a grab rule (console right-click option).

On the right is a drop-down list of all your existing rules. You can insert the selected rule
before or after any other existing rule.
You can also choose the ‘at’ option to insert the selected rule at a vacant location. When
you choose ‘at’, the list on the right shows your vacant sequence numbers (from rules
that were previously created then deleted) rather than existing rules.
Moving Grab Rules to Different Folders
You can use the Move to Folder... option to switch a grab rule from one folder to another.
When you select this option, this window is shown:

Figure 9-6. Moving a grab rule to a new folder.

Select a folder from the dropdown list. Click OK to complete the move. When you return
to the list of grab rules, your rule will show as modified, and you can reload the grab rule
list to display the rule in its new location.
Exporting Grab Rules
If you would like to keep a record of your grab rules, share rules between sites, or send
them to the Tech Support group for trouble shooting you can email your grab rule
definitions (either a selected one, or many).
Below is the window presented when you select the Export option:

- 167 -
Figure 9-7. Options for exporting grab rules.

You can also get to the window above by selecting the File/Export Rule option.
In order to email rules you need to set up your console email options
(Tools/Configuration/Email). The information presented when you do this is a subset of
the settings you defined when configuring the Catapult Poller, at the end of Chapter 2 (so
keep in mind that any changes you make will affect the poller, if it’s running on this PC).
Refer to the section “Configure the Email Server Information” on page 51  for details.
Refreshing the Grab Rule List
The Refresh List button refreshes the list to reflect any grab rules that have been added
or deleted by other users and presents the rules in their unique sequence number order.
Distribution Groups
Distribution groups are described in Chapter 10. You will use these as a convenient way
to distribute a report to multiple recipients, either by email, print or fax. Groups also
provide a way for you to control the actions taken with split sections in a report.
Email Text Headings and Footers
This options allows you to set default headings and footers for your email messages.
This is described in detail in the section “Working with Email Header/Footer Text” on
page 171.
Work with Title Page or Footer Page Text
Catapult allows you to create standard title and footer pages to append to your email.
This feature is described in the section “Working with Title and Footer Page Text” on
page 173.
Preview Spool Files
The option to preview spool files is useful for downloading the spool files to your PC to
verify their content, your selection criteria, etc. The windows presented by this option are
described in the section “The Grab Rule Maintenance Window” on page 192 .
You can also use the Preview window as a starting point for creating instant rules. This is
described in the section “Using the Preview Window to Locate the Spool File” on
page 78 , in the tutorial section of this guide.

- 168 -
Working with Grab Rule Folders
As Catapult becomes ensconced in your organization it is likely that the number of rules
you have will grow quickly. A useful feature for organizing your rules is to separate them
into folders by category. In order to view your folders, select the View/Folder View menu
option. Figure 9-1 shows the Catapult Console with this view selected.
Creating Grab Rule Folders
To create a new folder for your grab rules, select the New Folder option from the File
menu, or type Shift+Insert. This window is presented:

Figure 9-8. Creating a new grab rule folder.

Type a folder description and click the OK button. When you do this, the new folder is
displayed in the console.
Adding Rules to Your Folders
After creating a new folder, you can move rules to that folder by right-clicking on a rule
and selecting the Switch Folder option. Note that you can Shift+Click to select multiple
rules before performing the operation. You can also drag rules between folders using
drag-and-drop.
Deleting Grab Rule Folders
To delete a grab rule folder, right-click the folder and select the Delete option. You can
also select the Delete Folder option from the Edit menu.

When you delete a folder, all grab rules are also deleted.

Renaming Grab Rule Folders

To rename a grab rule folder, right-click the folder and select the Modify Folder option.
You can also select this option from the Edit menu.
Copying Folders
Catapult also allows you to copy an entire set of grab rules by copying their folder. To do
this, select the folder and then choose the Copy Folder... option from the Edit or right-
click menus.
When you choose the copy option the window shown above in Figure 9-8 is displayed
with the text ‘Copy of...’ added at the beginning of the folder description. You can change
the text to anything you like.

- 169 -
Moving Grab Rules to Different Folders
To move a grab rule to a different folder right-click the rule and select the Move to
Folder... option. Drag and drop it. You can also change the grab rule folder from the
General tab.

- 170 -
Working with Email Header/Footer Text
Sometimes you may find that you need to include some standard header or footer
information in an email - information that is not part of the report that you are distributing.
While you can do this from the email section of your grab rule, you first need to define the
set of text to be added as a stand alone object. To do this, select the Work with Email
Header/Footer Text option from the Tools menu of the Catapult Console (or click the
console toolbar icon).
When you select this option, a window similar to this one is presented:

Figure 9-9. Catapult email header/footer documents.

This window lists all the email headers currently defined. Use the buttons (or
corresponding menu options) to add, change, delete or copy existing entries. You can
also reload the list from the server.
Here is an example of the window that appears when you add or change an entry:

Figure 9-10. Sample email header/footer docs.

- 171 -
Description
Type a description for your email header/footer. This description is displayed in your grab
rule when you select an entry.
Type
This option sets the content-type of the email itself. If you intend to include text formatted
as HTML into your headers and footers, you need to also set the option to Format as
HTML. Otherwise, the recipient would just see the HTML tags in the email.

If you format an email as HTML you can include many extras in

your message, such as links, images, web pages, etc.
If this option is selected, you need to include HTML tags such
as <br> in your text to ensure that the header/footer text is
rendered correctly by the browser or email client.
If you select this option but the report type is set to .txt (on the
Download tab), use the <pre> tag at the end of your header
and </pre> at the start of your footer. This will ensure that your
report text is rendered correctly. Alternately, choose .html as
your download format.

Header Text
This text is included in the distributed email above any contents that would be otherwise
included as a result of your grab rule logic (i.e. the report data).
Footer Text
This text is included in the distributed email below any contents that would be otherwise
included as a result of your grab rule logic (i.e. the report data).
If you are distributing the report as an attachment, and not including any other
information in the email body, the header and footer text are included immediately after
one another.

- 172 -
Working with Title and Footer Page Text
In addition to creating standard email header and footer sections, you can also attach
standardized header and footer pages to your documents. These pages are different
from email headers and footers in that they are attached to the generated document
regardless of format. This is useful in situations where you legally need to include an
additional, embedded chunk of text or and image with a document every time it’s
distributed, or if you had a generic cover sheet you wanted at the start of every report.
To append a section of text, you first need to build the content for the page to append.
Start by pressing the Work with Title Page/Footer Page Text button in the Catapult
Console, or by selecting this option from the Tools menu.
When you do this, the window below is presented:

Figure 9-11. The Title/Footer pages you can attach to your distributed emails.

This window lists all the title and footer pages that you have defined. Use the buttons (or
corresponding menu options) to add, change, delete or copy existing entries. You can
also reload the list from the server if you think someone else may have added or deleted
an entry since the time when you first presented the window.
When you create a new text entry, or modify an existing one, the window presented is
similar to this one:

- 173 -
 Figure 9-12. A sample of a Title/Footer page that can be attached to an email.

Description
Type a description for this page.
Page Text
Enter the text that you wish to append to the top or bottom of your distributed file.
Click OK to save your changes, or Cancel to exit without saving.

Designing the Pages

Within the text you can include the Rich Text Formatting tags described in , Rich Text
Formatting Options Reference (page 372). This gives you considerable flexibility in the
formatting of the content, and helping to align text with images (for instance). See also
the section “Using Title and Footer Pages in your Grab Rules” on page 263  for more
info.
From within your grab rule, you can also add background images to the Title and Footer
pages. You cannot, however, save these separately as part of the actual Title and Footer
page text. So depending on your particular needs & skills, you may find it easier to create
an 8.5 x 11 image, with the text on it that you need, and attach that to your report, without
using the text at all.

- 174 -
Importing & Exporting Grab Rules
You can import and export your grab rules to/from other systems or Catapult instances.
This is mainly intended as a resource for working with Technical Support to resolve grab
rule configuration issues. However, it can also be useful for copying rules between
Catapult instances running on your own system(s), or if you archive rules and want to re-
use them later.

The import and export options are primarily designed to help

our Technical Support troubleshoot an issue. In some cases,
they are useful for moving a rule to a new Catapult
environment or archiving a rule for later use.
These options are not intended for upgrading Catapult.
If you are upgrading from a previous release or want to run
multiple versions of Catapult concurrently, refer to the
instructions in the Upgrader’s Guide.

Exporting Grab Rules

You can export one or more of your grab rules to disk or by email, using the File/Export
Rule(s) menu option.
When you select this option, this window is presented:

Figure 9-13. Exporting your grab rules.

Selected/All Grab Rules

If you need to copy a rule to another system running Catapult or send it to Technical
Support to troubleshoot a problem, you can export single (or selected) rules. If you want
to save an archive of all your rules, select the second option.
Export Target
You can save the grab rule to disk, or if you have configured the console’s email options,
email it directly to someone.

- 175 -
 Save Target Folder
Specify the directory to which you want to save your grab rule.
Email Details
These options are enabled when you choose the option to export your grab rule(s) by
email. Enter a target email address and choose whether Catapult should populate the
email’s From information from the Catapult Console Email defaults
(Tools/Configuration/Email).

Importing Grab Rules

To start importing one or more rules, select the Import Rule option from the console’s File
menu. Catapult presents a window similar to this one:

Figure 9-14. Importing a Catapult grab rule from an archived version or file.

Click the Browse button to find the rule to import.

The default location for your target grab rule is: C:\Documents and Settings\All
Users\Application Data\ESDI\Catapult\Exports\, or in Windows 7,
C:\ProgramData\ESDI\Catapult\Exports. The import feature is looking for an XML file in
that directory. These XML files are produced by the Export option.

Every grab rule you create is automatically stored in a directory

similar to this one:
C:\Documents and Settings\All Users\Application
Data\ESDI\Catapult\Rules\192.168.1.111\XL_CATAPLT

These rules are mirrored on every machine running any of the

Catapult components (Poller or Console), but will be most
current on the Poller PC. If you accidentally delete or otherwise
lose a rule a for any reason, you can recover it from this location,
by importing the xml file.
The challenge is that the xml files are just numbered
sequentially. You may need to use a utility such as Agent
Ransack to search the xml files for particular keywords to help
you identify the rule you need to recover.

- 176 -
Browse
When you click the Browse button, you can select from the export files (in XML format)
which may look something like this:

Figure 9-15. Selecting a previously exported Catapult grab rule, saved as an XML file.

Select one or more rules to import and click Open.

Preview Rule
After selecting an XML file from the list, you can click this button to open a limited, read-
only version of the grab rule editor displaying the selected rule. In this view, some rule
options that would normally be retrieved from the IBM i aren’t loaded.
This option is only available when you are importing a single rule at a time.
Attempt to Import Distribution Groups (If they don’t Already Exist)
When you check this option Catapult will attempt to also import any distribution groups
that are referenced, if these aren’t found in your current configuration. If your current
Catapult version already has a group with the same name and description, it won't try to
import it. In this case, it will also not attempt to import any missing distribution list
members.
Attempt to Import Title/Footer Pages
Check this option to instruct Catapult to attempt to import any Title/Footer pages used in
the rule.
Attempt to Import Email Header/Footer Pages
Check this option to instruct Catapult to also attempt to import any email Header/Footer
pages from the base and split reports.

- 177 -
The reason these options are labeled ‘Attempt...’ is that if
Catapult is for any reason NOT able to import these additional
object, the process isn’t halted. If the import of the other
objects fails, the import process will modify the rule to exclude
those elements that failed to be imported.

- 178 -
 - Working with Catapult Distribution Groups

CHAPTER 10

Chapter 10 - Working with Catapult Distribution Groups

A Catapult Distribution Group is primarily a set of individuals and/or distribution details

(fax, email or printer) used for sending your reports. You can use groups as target
recipients when you want to repeatedly send a report to the same set of people (for
example, weekly sales figures to the management team). The grab rule locations where
you can use groups are described in the next few chapters of this section, and include
emailing, printing and faxing.
You can also use distribution groups when you are splitting a report to email or save
selected portions. This section describes how to define and work with groups in general;
the section “Using Groups with Report Distribution and Splitting” on page 283  discusses
these options in more detail.

- 179 -
The Group Summary Window
Use a group of email addresses, fax numbers or printers when you want to set up a grab
rule to distribute a report to more than one person. To display and work with your
distribution groups, choose one of the following options:
1. Click the console’s Work with Distribution Groups button.
2. Select the option from the Tools menu.
3. Use the Browse buttons you’ll find at various locations within the Grab Rule
Maintenance options to select and work with groups.
And finally, you can access and work with your distribution groups from the Document
Splitting Segment Options when defining a split rule. From here you can select an
optional group to tie into your split criteria.
The same window is presented in every case.
Below is an illustration of the group maintenance window:

Figure 10-1. The Catapult distribution groups maintenance window.

This window initially displays the name and description for each group. You can edit,
delete or copy groups using the Edit or right-click menu options, or via the toolbar icons.
You can also edit the group descriptions and group entries in the window above by
simply clicking on them and typing your changes (don’t forget to press the Apply button
afterwards).
There is also a useful Group Usage option available from the toolbar options and Edit
menu. This is described below.
Creating Group Entries
When you first create a group it has no associated entries. Use the Add Group Entry
option to add them. The window presented when you do this is illustrated in a later
section below.

- 180 -
 Deleting and Copying Groups and Group Entries
Deleting a group also deletes all its entries. When you copy a group, the entries are
copied and a window is displayed prompting you for a new group name and description.
This window is illustrated in the next section.
Exporting Group Entries
You can use the export option to either create a file or email a list of group entries.

Creating or Changing Group Information

When you create or copy a distribution group Catapult prompts you for a group
description:

Figure 10-2. Creating a new distribution group.

Then you can edit the group from a window similar to this one:

Figure 10-3. The distribution group attributes window.

When you change a group you can only edit the description.

Exporting Group Entries

If you want to review, share or print a list of the entries in a distribution group (as XML
files), select the Export option from the toolbar or File menu. When you select this option,
Catapult presents a window similar to this one:

- 181 -
Figure 10-4. Exporting group entries.

Selected/All Groups
To export only selected groups, you must choose these before clicking the Export option.
Alternately, you can click the All Groups option.
Export Target
You can export the group member list to disk, or email it to an individual.
Save Target Folder
This option is enabled if you select the Save to Disk option. Browse your PC or network to
select a folder into which Catapult should create the distribution group report.
Email Details
These options are enabled when you choose the option to export your reports by email.
Enter a target email address and choose whether Catapult should populate the email’s
From information from the Catapult Console Email defaults (Tools/Configuration/Email)
or from the information you enter below.
If you haven’t yet configured the console’s email options, the Use Default option isn’t
available.

- 182 -
Working with Group Entries
Your group entries are typically the people receiving your reports. To work with the
entries in a group double-click the entry to load the Edit Group window, shown here:

Figure 10-5. Editing a distribution group and its entries.

Editing Group Entries

To change an entry you can double-click it, or use the right-click and Edit menu options.
The edit window is discussed in the next section.
Adding Group Entries
Use the first toolbar icon to add new entries, or the right-click and File menu options.
Copying Group Entries
To copy an entry use the toolbar option, or corresponding right-click or Edit menu
options.

Adding or Editing a Group Entry

This is the window presented for creating or editing group entries:

- 183 -
Figure 10-6. Editing distribution group entries.

Key Value(s)
If you are using this group for emailing, faxing or printing, where the email, fax or printer
information is not on the report, then you need to enter one or more key values. Multiple
values must be separated by semi-colons. This is discussed further in the section
“Unassigned Split Segments” on page 222 . Group entries also support the special value
"*ALL" (all caps, in quotes). This means that a particular person can get all split sections
emailed, without having to set up specific keys.
Email Address(es)
This value is required if you are using groups to distribute reports by email. You can enter
one or more email addresses in this field.

Separate multiple addresses with blank spaces or semi-

colons, but this part isn’t so much up to Catapult as much as
your mail server. Some email servers also allow separating
addresses with commas, for instance.

Using Replacement Values in your Email Addresses

Catapult email address processing also supports the use of replacement values (i.e.
&D@finklebert.co.uk, or &EmpID@finklebert.co.uk). This means, for example, that you
can set up a distribution group with a single entry, using a replacement value for the first
part of the email address. That portion of the email can then be extracted from the report.
You could achieve the same result by using replacement values for the email address in
the main Email options of your grab rule.
First/Last Name
Enter the group member’s first and last names.

- 184 -
Printer
Select a printer to be assigned to this group member. The *DEFAULT value corresponds
to the printer selected in the poller configuration as the default. If you aren’t using this
group for printing, or this member doesn’t have a printer near them, you can also select
*NONE.
Fax
If you are using this group to distribute reports by fax, enter a fax number here. Use
commas in the fax number to add pauses to the dial string.
Additional Values
You can also associate Additional Data Values with each distribution group entry. You
can then use these values in other parts of your grab rules, wherever replacement
values are supported. For example, you might customize the saved path using one or
more additional data values. Or you might create an additional data value for each
member of a group to use as the PDF password. This means that each PDF generated
by the grab rule could have a customized password known only to the recipient.
Use the buttons at the right of the list to work with the additional values:

Figure 10-7. Working with additional values for a distribution group entry.

In this example, we have set up the following values for this group entry:
□ The first additional value, Betty Banjo, is her complete employee name. This is
associated with the replacement value &EmpName.
□ The second additional value, BETTYB, is Betty’s IBM i User Profile. This is
associated with the replacement value &UsrPrf.
□ The third value, betty.banjo, is Betty’s network login and email address. The
replacement value here is &NtwkLog.
□ The fourth and final value is one we intend to use as a password.

- 185 -
Choose unique replacement values for each additional value. These should also be
consistent with other distribution group entries. You may wish to establish standards for
setting these up consistently across lists and grab rules.
Using Additional Group Values in your Grab Rule
The last additional value we created above was intended to be used as a password. Here
is how we would use that value to password-protect the PDF files that Betty will receive:

Figure 10-8. Using a replacement value from a group entry.

In this example we have entered ‘&PDFPswd’ for both the Open File Password and
Confirmation values. This instructs Catapult to retrieve the password for this particular
file from the group entry.
This option is useful if you are splitting a report into multiple sections and want to
associate a different password with each section. In the grab rule shown above, we are
taking a large report on our IBM i which includes all our invoices for the month, and are
splitting that report using the customer’s initials. Those initials are then associated with a
unique password, saved in that individuals catapult group entry.

- 186 -
Distribution Group ‘Where Used’ Information
As your Catapult usage increases and the number of supporting elements multiplies,
one of the challenges you face is knowing which components reference each other. One
instance where this information is particularly important is the relationship between grab
rules and distribution groups.
The Group Summary window of the Catapult Console includes a quick and easy cross
reference facility to display which grab rules reference a particular group, and how it is
used.
To display this information, go to the Group Summary window and click the Find “Where
Used” toolbar icon, as shown here:

Figure 10-9. Selecting the Distribution Group Where Used option.

In this example we have selected the group MyCompany. This option is also available
from the right-click and Edit menus.
When you select this option, Catapult presents a window similar to this one:

- 187 -
Figure 10-10. A list of rules using the selected distribution group.

This list displays the grab rules that reference the selected distribution group and
includes details on how the group is used in each rule. In this example, you can see that
the group MyCompany is used in several rules.

- 188 -
 - Creating a New Grab Rule

CHAPTER 11

Chapter 11 - Creating a New Grab Rule

The heart of Catapult is your grab rules. Your grab rules contain the criteria that defines
which file(s) will be selected, how and to whom they will be distributed, and the additional
actions that Catapult will perform on the files. For a quick walkthrough of the essential
steps required to build a basic grab rule, please read first.
This chapter describes how to start creating a new grab rule and the options you will set
in the General category of your grab rule definition. The remaining chapters in this part of
the guide describe the options in each of the main sections of your grab rule definition.

- 189 -
Starting a New Rule
describes all of the Catapult Console options for creating and editing rules, along with
the relevant menu and toolbar options. In practice, however, you’ll most often start
creating new rules from the View Spool Files window, which you can launch from last icon
on the right in the console toolbar:

Figure 11-1. The View Spool File button, a good spot to start creating your rule.

When you click this button Catapult asks whether you want to load a spool file list, and
then presents the Spool File Selection window.

The Spool File Selection Window

From the Spool File Selection window you can review your spool files and select one as a
sample of what you need. This window is described in more detail in the next chapter,
Setting the Grab Rule Acquisition Criteria. When you access this window directly from
the console, it’s a useful starting point for creating new rules.
Here is the window as it first appears:

Figure 11-2. The Spool File Selection window, presented from the console.

When the window is first presented, the filtering criteria is blank, and a list of you IBM i
queues is loaded to the dropdown list on the far left.
To load a complete list of spool files in a given queue, select the queue from the
dropdown list and click the Search button.

- 190 -
 While you may often specify a specific queue, you can also filter your results based on
the Out Queue *ALL/*ALL. This will display all matching spool files, based on the rest of
your filtering criteria, from all queues.

Selecting a Sample Spool File

Here is an illustration of a list of spool files in QPRINT, with no additional filtering criteria
filled out:

Figure 11-3. A list of spool files to choose from.

In this illustration we have gone ahead and located a spool file that we want to distribute
and clicked it in the list. When you select an entry in the list Catapult enables the Create
Quick Rule button on the top left.
Click this button to start creating a new grab rule, with the attributes of this spool file
preloaded into your acquisition options.
Filtering the List
In the example above we aren’t filtering the list by anything other than the queue, and our
list includes a wide assortment of spool files of different types. To narrow your search,
add a File Name, Job Name, Form Type or User Data value to your filter and reload the
list. You can also filter on the spool file Status.

You can click on the column headings of the file or queues lists
to re-sort the list.

This window is described in more detail in the next chapter. The next section describes
the general grab rules options, where both the console New Rule... and Create Quick
Rule options will take you.

- 191 -
The Grab Rule Maintenance Window
When you start creating a new rule Catapult starts by presenting the Grab Rule
Maintenance window, at the General category, shown here:

Figure 11-4. The General options in a new grab rule.

The left margin lists the sections of your grab rule, and when you click on each section,
the right pane displays the options associated with that category. In the example above
we are looking at the General category.
Notice that most categories have a small + sign next to them that you can click to show
additional options. The Next button allows you to advance to the next relevant set of
options. The OK, Apply, Cancel and Help buttons are always available.
Remember that your grab rules exist on the IBM i. This means that when you click OK in
the Grab Rule Maintenance window, the grab rule is added or updated on the server,
and the new or updated rule is immediately available to any other user who has the
console installed.

The General Grab Rule Settings

Here are descriptions of the options available from the General category.
Rule Description
Type a description for your rule (up to 50 characters). This is also displayed in the grab
rule window title bar.

- 192 -
 Rule Status
New rules are by default inactive. This protects you from inadvertently processing a set
of reports before you have finished setting all your options. Use this option to activate
your rule when it’s ready to run.
Also use this option to inactivate rules that you need to temporarily stop using. If the
Catapult Poller is running on the IBM i when you inactivate a rule, the change will go into
effect at the next polling cycle, when inactive rules will be ignored. Likewise, changing a
rule back to active status does not take effect until the next polling cycle, or when the
poller is re-started.
You can also toggle the rule status from the console list’s right-click menu.

Note that just because a rule is inactive doesn’t mean it isn’t

used. Catapult includes a server side command called
ZRUNRULE that allows you to execute a rule from a command
line or CL program. The ZRUNRULE requires as parameters the
spool file selection values, and the number of an existing
grab rule where it will find the actions you want to execute for
that file.
Inactive rules can be used in this way, as part of IBM i
programs. The ZRUNRULE command is described in more detail
in Chapter 18.

Rule Folder
Use this option to specify the folder where you want to store your rule.
Catapult grab rules are by default organized into folders. When you initially install the
product there is one folder, General. To create new folders, use the option under the
console File or right-click menu.
Processing Order
Grab rules are normally processed in the order in which they are created and in most
cases you shouldn’t have to change the value automatically set here when you create
your rule. However, there may be instances when you need to change the processing
order to ensure that grab rule requests are created in a specific order. For example, if
you have two or more rules processing the same spool file, you need to make sure the
spool file isn’t deleted by one rule before the other(s) gets it.

Rule Expiration Options

You may often find yourself creating one-of rules as a quick way to download and
reformat a spool file or two. To help avoid the problem of obsolete rules hanging around
until you’ve forgotten what they are for and are afraid to delete them, your grab rules
support a couple of automatic deletion options.
Delete Rule After Date
The rule will be deleted on the first polling cycle *after* the date added here.

- 193 -
 Delete After Use
Check this box to use this rule once and then delete it. You can easily create quick,
temporary rules by copying others or using the Quick Grab rule feature.

Options for Securing Grab Rules

As Catapult becomes an important element of your business applications, you may feel
yourself becoming increasingly exposed to having a crisis if someone unwittingly edits an
existing rule into malfunction.

These grab rule security options are primarily designed to

help you avoid someone accidentally changing a rule they
didn’t create or do not likely understand. These options are
not intended to fully protect your grab rules from someone
with a malicious intent to damage them.

The options available to you depend on whether you have *SECADM special authority. If
you do, you can secure this rule to any user or group profile. If you don’t have *SECADM
special authority you can only secure the rule to yourself or your user’s group profile.
Secured rules cannot be change, deleted or displayed. Users with *SECADM special
authority can always access and edit any grab rule.
Choose from these options:
□ None. This option allows anyone to view, change or delete this rule.
□ IBM i User. This option secures this rule to your own user profile.
□ IBM i Group. This option allows you to secure this rule to users who belong to a
particular group profile.
The default option is None.
Rule Creation Information
This area shows when and by who the rule was created and last changed.
Post-Rule Notification Options
This option allows you to email a specific user when the grab-rule request has an error or
completes.
□ None. This option doesn’t send any notifications for the rule.
□ Errors Only. This option sends a notification if the grab-rule request has an
error.
□ All. This option sends a nofication if the grab-rule request has an error or
completes.
The default option is None.

- 194 -
 - Setting the Grab Rule Acquisition Criteria

CHAPTER 12

Chapter 12 - Setting the Grab Rule Acquisition Criteria

Every grab rule must include acquisition or selection criteria to identify the files that you
want Catapult to process. The type of criteria required depends on whether your rule will
be monitoring an IBM i queue or a network directory.

- 195 -
The File Acquisition Category
When you click the Acquisition category or click the Next>> button from the General
category, Catapult brings you to this window:

Figure 12-1. Selecting the grab rule selection type, prior to setting the acquisition criteria.

You need to select between the two Selection Types available:

□ IBM i Spool file. The most commonly used option, to download and process an
IBM i spool file.
□ Network File. You can also use Catapult to poll selected directories on your
network.
The option you pick here enables the appropriate set of selection options, that Catapult
will also take you to when you click Next>>.

- 196 -
IBM i Spool File Acquisition Options
These are the spool file acquisition options:

Figure 12-2. Acquisition options when grabbing IBM i spool files.

In addition to your selection criteria, from here you can also set a number of other
general options relating to the way in which your spool files are downloaded.

How the Spool File Attributes are Interpreted

The information you type into these selection fields serves to narrow the search. If you
leave a field blank, for example "Job Name", the rule will match all job names. Similarly, if
you leave the "Queue Name" field blank, Catapult searches in all active queues.
When you enter more than one criteria, Catapult always applies an AND relationship
between the values you enter. For example, if you specify both a Queue Name and a
Form Type, in order to be selected for distribution the spool file will have to exist on the
matching output queue and have a matching Form Type.
If you need an 'OR' relationship (e.g. 'the spool file can be found on queue x or have a
forms type of y') you can create two grab rules. The easiest way to do this is to create one
rule, then copy it and change the selection criteria in the copied rule. Remember that
Catapult caches spool files efficiently, so even though you have more than one rule that
applies to the same spool file, it will only be downloaded once.

- 197 -
 In the illustration above, a search based on this grab rule will match all spool files in
QGPL/QPRINT2 with User Data of EZPDEMO.
All spool file selection attributes support a generic values. For example, in our illustration
above, instead of typing EZPDEMO, we could enter a value of EZP* for the User Data to
download all files with a user data starting with EZP.

Spool File Selection Criteria

Below are the criteria you can use in setting up your selection. You can populate these
values from the preview window or by entering them manually.
The section “Selecting a Sample Spool File” on page 191 describes how to populate all
these values from the preview window. You can also do that from this window, using the
Locate button (as described below on page 201).
Out Queue Name and Library
Select a queue to poll. If you select *ALL/*ALL Catapult will search for a match in all
queues that the poller is scanning, using the other attributes you specify.

When you click the arrow to display the list of available

queues, Catapult will display all the queues in the libraries to
which your user profile is authorized. Queues not currently
polled show, but are greyed out.

Spool File Name

This is the name of the spool file to select. On the IBM i WRKSPLF list, this name appears
under the File column heading.
Form Type
This is the name of the Form Type associated with the spool file. The usual value for most
IBM i spool files is *STD (standard).
User ID
This is the User ID of the person who ran the job that produced the spool file. It appears
under the User heading of the IBM i command WRKSPLF list.
Job Name
This is the name of the Job that produced the spool file. To see the job name, run the
WRKSPLF command, then press F10 to find the value under the Job heading in view 3.

User Data
This is the value for the User Data field associated with a spool file. It appears under the
User Data heading of the IBM i command WRKSPLF list.

Page Range
This option allows you to set which pages of a spool file should be downloaded. ‘All’ is the
default. The ‘Range’ radio button enables the from-page and to-page fields so that the

- 198 -
 starting and ending pages can be entered. These two fields will accept a number in the
range 1-99999.

Download Formatting
Choose from the following spool file formats:
□ *RPT - Include blank lines and page breaks. Use this option to download the
spool file with embedded blank lines and page breaks. The value of *RPT results
in a more accurate on-screen representation of the report. Because blank lines
are included, the report appears on the screen as it would appear when printed
on hard copy. *RPT is required for PDF files, as otherwise the page breaks don’t
come down with the file and the PDF file cannot be correctly formatted.
□ *FILE - Remove blank lines and page breaks. Use this option to remove blank
lines from the downloaded spool file. The value of *FILE corresponds to the file
format you see on the IBM i with the WRKSPLF command.
□ *RICH - Include rich text formatting. Select this option if you are including any
special formatting in your report by way of Catapult *RICH formatting tags, or if
you want underlines and bolding to be handled exactly like the native printing
process. See the section “Using Catapult Rich Format Tags in Your Reports” on
page 261  for more information on this option.
If your grab rule is splitting your report, you should note that the choice you make for this
option may affect any line offsets specified between your key and key anchor locations.

Spool File Translation

Catapult also supports options to allow you to set the CCSIDs used by this rule.
Use Default Poller CCSIDs
The Advanced Configuration Options section of your poller configuration includes default
CCSIDs you can specify to control how Catapult handles your language’s character set.
Select this option to apply the values used in your poller configuration to the reports
processed by this grab rule.
See the section “Advanced Poller Configuration Options” on page 354  for further
details.
Use Custom CCSIDs
Select this option if you want to specify alternate CCSIDs to be applied to the reports
processed by this particular grab rule. This option is useful in cases where you operate
Catapult in a multi-lingual environment, and may be processing reports that use
characters from different languages.

Post-Processing Actions
There are also a number of things you can do with your spool files after the grab rule has
finished processing them.

- 199 -
Action
Choose an action to take with the original spool file on the IBM i after it has been
downloaded for processing. Options are:
□ *NONE. Select this option to leave the spool file untouched.
□ *SAVE. Sets the spool file attribute Save File after Written to *YES.
□ *HOLD/*RELEASE. These options change the spool file status.
□ *DELETE. Use this option to delete the IBM i spool file after processing.
The default option is *NONE.
Cache Spool Files
A situation can arise where the acquisition criteria in two or more grab rules matches the
same spool file(s). In this case it would be inefficient to transfer that same file from the
IBM i to the PC Server each time there was a match. For this reason spool files can be
stored in a cache directory on the PC Server.
Before a file is downloaded from the IBM i, Catapult checks whether the spool file has
previously been cached. If it has been, the cached copy is used and no download takes
place.
Check this box to cache spool files selected by this rule. The length of time a spool file will
remain in the cache, and the maximum size of the cache, are set in the Catapult Poller
Configuration. See the section titled “Cache Directories” on page 360  for additional
information.
Update User Data With:
If your rule isn’t deleting the spool file, you can check this option to update the ‘User Data’
value for the selected spool file with the text you enter.
This option is useful for two main reasons:
□ When you scan spool files from IBM i commands such as WRKSPLF, it gives you a
quick visual cue that the spool file has been grabbed and distributed with
Catapult
□ If the User Data is one of your spool file selection criteria, this change will ensure
that the spool file will not be re-selected.
We recommend you use this option, it’s a good practice.
Move Spool File to Queue
Use this option to move a spool file to another queue after processing. When you check
this option the drop down box is enabled so you can select a queue on your system.

- 200 -
Spool File Selection Preview
While Catapult supports the ability to also poll network directories for files to distribution,
most users start by creating rules over IBM i spool files. In most cases, the easiest way to
build your spool file selection information is to start by locating a sample of the file you
want to download and selecting it. You can do this both from the console directly (as
described in the section “Selecting a Sample Spool File” on page 191 ) or by pressing
the Locate button in the spool file acquisition options (see Figure 12-2).
When you click the Locate button Catapult displays this window:

Figure 12-3. The Spool File Selection window, as it is first presented.

When the window is loaded from within a grab rule, Catapult limits the list to show reports
that match your selection criteria. When you go to the preview window from the console
directly the filtering criteria is blank, and a list of your IBM i queues is loaded to the
dropdown list on the far left.
To load a complete list of spool files in a given queue, select the queue from the
dropdown list and click the Search button.
Here is an illustration of a list of spool files in QPRINT, and no additional filtering criteria:

Figure 12-4. A list of spool files to choose from.

- 201 -
If you want to set up your grab rule to download all the spool files in a selected queue,
just click on the queue, then click on the Select Queue button (in the top left tool bar) or
use the right-click menu. The name and library of the selected queue are copied to your
grab rule selection criteria.
Filtering the List
In the example above we aren’t filtering the list by anything other than the queue, and our
list includes a wide assortment of spool files of different types. To narrow your search,
add a File Name, Job Name, Form Type or User Data value to your filter and reload the
list. You can also filter on the spool file Status.

You can click on the column headings of the file or queues lists
to re-sort the list.

Select Filter
When you open this window from within a grab rule, using the Locate button, the window
displays a Select Filter button at the bottom. If the list of spool files shown in the window
matches the set of spool files you want to process in your grab rule, click this button to
import your current filter criteria to your rule.
In the example above, our only filtering criteria is the queue name, so by clicking Select
Filter now, our rule would be set up to process every spool file in QPRINT (which wouldn’t
be likely).
Select File
To add selection criteria to your grab rule that matches a single file, click the spool file in
the list and then press the Select File button. When you do this, Catapult returns to the
grab rule maintenance window and loads the attributes of the selected spool file into your
acquisition criteria.
To select a specific file, download the list of files from a specific queue (as in the
illustration above). Then find an instance of the spool file you want in the list.
Viewing a Spool File
You can also double-click on a file in the list to download a preview in a window similar to
this one:

- 202 -
 Figure 12-5. Previewing a spool file from the Selection window.

In this window you can use the options in the top left to load the full document (rather
than just the first few pages), refresh the report, change your font size or find a text
string.
If you click OK on this window you’ll return to your grab rule. Click Cancel to return to the
main selection list window.

Viewing the Selected Spool File as you Define the Grab Rule
In addition to the Locate option available from the Spool File Acquisition category of your
rule, you can also work with a sample of your selected file(s) from many other locations
within the grab rule maintenance window.
For example, here is the grab rule section from which you can define bookmarks in your
PDF files. In this illustration we have clicked the ‘View’ button to display a preview of the
report we’ll be distributing. In the preview window we have further selected the constant
text string we’ll use as our key anchor:

- 203 -
Figure 12-6. Using the preview window to help build our grab rule.

Because our selection criteria currently corresponds to a single spool file on our system,
that file is loaded immediately. Otherwise Catapult would display a list of spool files
matching your acquisition criteria (as in Figure 12-4) so you could choose which one you
wanted to use to set up your bookmarks.
The buttons shown in this window are described in the relevant sections below.
Spool File Preview Right-Click Options
The preview window above illustrates how you can highlight text and then use the toolbar
icons to select that text. In this example, we are adding bookmarks to our generated PDF
file, so Catapult displays only those toolbar icons.
You can also use the preview window right-click options to select values from your spool
file, as shown here:

- 204 -
Figure 12-7. Selecting the Bookmark Key Text from the preview window.

As mentioned previously, the preview window is smart enough to know where you came
to it from, and enables only the options that are relevant to the feature you are currently
setting up.

- 205 -
Network File Acquisition Options
You can also use Catapult to poll for files available in network folders. This feature
requires that the network folder(s) be accessible via their UNC name.
These are the Network File Acquisition options:

Figure 12-8. Options for selecting network files.

In this example we have selected a shared network drive where staff meeting summaries
are stored, and instructed the rule to check that directory for any documents with an
extension of DOC.
Below are descriptions of all the available options.
Path and File
Use the Browse button to locate an instance of the file you need to download.
After selecting a base file to determine the location, you can optionally change the file
name to be searched for to be generic, according to the following examples:
□ DOC*.txt will match any file in the folder that starts with DOC and a .txt extension.
□ *.txt will match any file in the folder with a .txt extension.
□ * will match any file in the folder.
Search Subfolders
Check this box to instruct Catapult to search the specified folder and all subfolders.

- 206 -
Treat all Files as Text
Use this option to indicate to Catapult that all the files retrieved, regardless of their actual
extension, should be treated as text files. You can use this feature to take advantage of
other file processing options. Below is an explanation of how this works.
Once you have defined which file(s) you want Catapult to grab, the additional actions you
can add to your rule depend on the file type specified. Certain grab rule options only work
with certain types of files, according to these guidelines:
1. If you are looking for a .txt file (including wild cards such as *.txt) Catapult
provides the full functionality available, just as if you were processing a spool
file. In this case you can split and parse the report, extract values from the
content, and so on.
2. If you are selecting a file of the types .rtf, .pdf, .html, .tif or .pcl, Catapult
enables the options normally available for formatting and distributing those
file types (such as faxing, printing, emailing, etc.). You won’t, however, be
able to parse the files, or extract values from them.
3. If you are retrieving any other file type (including the * wildcard) you will only
be able to attach the file to an email, save it to a network location or submit it
to the ECM.
If you have a report with an unrecognized extension or are using the wildcard option, you
can check the option Treat all Files as Text to enable the grab rule options related to
extracting or parsing text from the report.

Unless the report actually is in text format, the data elements

won’t occupy consistent locations within the page, and
therefore the parsing engine will not be able to consistently
locate key values and anchoring strings.

Network Acquisition Profile

Enter the Network Profile details required for Catapult to log in to your network to poll the
specified directories. Catapult will log in each time it polls the folder(s) you specify. Select
from these values:
□ None. If you leave this option to the default of None, Catapult will attempt to
connect to the target folder and files using the profile that started the poller
service.
□ Use Poller Default. When you select this option, Catapult will still initially attempt
to access the required folder using the network ID that started the poller service.
However, if the folders is NOT accessible using that profile, Catapult will further
attempt to connect to it using the Network Acquisition Default Profile in the poller
configuration.
□ User Defined. Select this option to enter a network profile that Catapult will use
to access the folders and files needed by this particular rule.

- 207 -
Cache PC Files
If you check this option Catapult saves the PC file to the cache so that if this file is used
again with another rule, it doesn’t have to be copied a second time.
Move File/Path
Check this option to move the polled file to the selected location after processing.

- 208 -
 - Document Splitting Options

CHAPTER 13

Chapter 13 - Document Splitting Options

Report splitting allows you to break downloaded spool files into sections, using a key
value you identify in the report body. The extracted portions can then be processed
individually (if you use a unique key) or grouped together (by using a non-unique key
value) before distribution.

Splitting a spool file is entirely optional, and if you don’t need

this feature in your grab rule you can bypass the category.

For step-by-step instructions on how to build parsing or splitting criteria into your grab
rule, please read through . This chapter goes through each available option in detail; use
it as a general reference of this feature.

- 209 -
Split Definition Components
When you set up your splitting/parsing criteria, there are some critical values that you
need to specify. Below is a brief summary of these values, and how they are used.
Defining Where the Split Occurs
Catapult needs to know where you want each report section to begin and end. A typical
example of this is to start each section with a high level heading line, and end each
section with a line which includes your section totals (such as when you are distributing
invoices).
You always need a constant way to identify the start and end locations for your split
sections.
Defining When the Parse/Split Occurs
Catapult determines when the report should be split by identifying a changing value on
the report. This value may be a key field such as a department number or customer
number, an email address included on the report, or a text string that you will use as the
grab rule’s email subject.
Defining Who Receives the Report and/or Where the Section is Saved
Catapult provides the flexibility to determine the destination of a report section by either
extracting the information directly from the report, or using a cross-reference table with a
key from your report. You can use your distribution lists and key values to populate a
wide range of grab rule options.
This means your report sections can be:
□ saved to unique directories on your network
□ sent to unique recipients (as well as CC’d and BCC’d)
□ sent with custom email subjects
□ printed at different locations
□ faxed to different numbers
among other features. You can also group and process several reports together by
choosing a shared key value, and defining appropriate entries in your distribution lists.
All of these options are described in the following sections, as well as in the chapters
corresponding to each feature.

- 210 -
Reviewing Split Summary Details
When creating or modifying a grab rule, click the Document Splitting category to see the
window below. From here you can toggle whether the report should be split:

Figure 13-1. Enabling the document splitting options.

Enable Document Splitting

Check this option to enable the splitting options for this rule. If you have defined split
options, you can turn them off temporarily by unchecking this option. Your criteria will still
be retained.

- 211 -
Defining the Segment Options
Click the Next>> button from the Document Splitting category to start setting up your
options. Here is what this section looks like when you first arrive:

Figure 13-2. The split section segment options.

Splitting Option
There are a two types of splitting you can choose from, depending on your needs and the
layout of your report:
□ Custom Splitting. Choose this option if you plan to identify unique key values in
your report, to use as the basis of your split sections.
□ Split by Page. Use this option to split your document into a section for each
page.
The Full Document option is present to retain compatibility with grab rules created in old
releases but isn’t particularly useful in Catapult 8. If you are still using it in an old grab
rule, there are easier ways to configure your rules now.

- 212 -
Segment Start/End Selection
Use these options to specify where each split section should start and end. While it’s
possible to enter these values by hand, the easiest way to populate them is via the spool
file preview. Click the View button to have Catapult locate and load a preview of a spool
file that matches your current selection criteria.
Segment Start Text and Column
The segment start text identifies a text string on the report that will be used by Catapult to
determine the start line of a new section of your report. In addition to the actual text, you
need to specify the column it starts on.
Note that this text is just the delimiter, not the key value used to determine whether a split
should happen (which is described later on below).

The section “Using the Preview Window to Define the Values”

on page 214 describes the easiest way to populate the
required split parameters.

You can use the special value *STARTOFREPORT if you want to split a single section
from the top of your report, that includes everything up until the End Text value. An
example of this might be if you wanted to send someone the header info for a specific
report, where a description of the range and selection criteria used to generate the
report was detailed.
The special value *STARTOFPAGE is useful when your key value may exist anywhere
within a page, but you always want to start your split section at the very top of that page.
An example of when you might do this is if you are using overlay images with invoices. In
this situation, the text on the page might not start until several lines down the page, even
though the background image may be designed to overlay the upper blank area of the
page with some company header logos, for example. If you didn’t start your section at
the top of the page, you would lose the blank lines that you have added to the report to
allow for your letterhead at the top of the page.
Segment End Text and Column
The segment end text and text starting column identifies a text string on the report that
determines the last line to be included in a report section. The default for this option is
*STARTTEXT, which means that the segment start text will also be used to identify the
end of each segment. When defined as *STARTTEXT, every line up to but not including
the next segment start text line will be included in the segment.
For the Segment End Text you can use the special value *ENDOFREPORT to include
everything from the split start text up until the end of the report. An example of when you
might select this value is if you just wanted to send someone the summary information
from the bottom of a report, beginning at a particular spot.
The special value *ENDOFPAGE is useful when you want to continue including blank
lines from your report right up until the end of the page. This is most commonly used in

- 213 -
 conjunction with the overlay image features, where you may have a standard letterhead
or footer that occupies the space at the bottom of a page, and if you don’t include the
entire page in the section your split, the form might not be correctly overlaid on the
downloaded file.
How the Start and End Text are Used
As report lines are processed by the Catapult report splitting engine each line is scanned
to determine if it contains the report start segment text or the report end segment text.
The engine also checks if the key field value has changed (as described on the following
pages). Depending on the report, and how the report segment end text is defined, one of
the following will occur:
□ Segment End Text is *STARTTEXT. If the segment end text is defined as
*STARTTEXT the report segment will not be split when the start segment is
detected unless a change in the key field is also detected. This is because your
section start text might be a value that is repeated across several pages, like a
page heading, and you only want to split your section when the actual key value
changes.
□ Segment End Text is *ENDOFPAGE. Like *STARTTEXT, *ENDOFPAGE
checks whether the key value or email address has changed since the beginning
of the split section, and if it hasn’t, then it will not end the split. For example, if you
are sending out invoices, and some invoices span more than one page: you can
still use the *ENDOFPAGE value to ensure that your overlay image aligns
correctly on the page, and the split section isn’t ended before the next invoice
number (assuming invoice number is your key value).
□ Segment End Text is a unique text string. If the end segment text is specified
as a unique string, when this string is encountered the report will be split after the
ending segment has been included. This means that report lines could be
explicitly excluded from the report (the lines between the end point you specified,
and the marker for the beginning of the next segment).
See “Report Splitting Examples” on page 226, later in this chapter, for further
information.

Using the Preview Window to Define the Values

The easiest way to define your segment options is selecting the values directly from a
sample of your report. To do this, begin by clicking the View Document option at the top
right of the window (Figure 13-2).
When you do this, Catapult uses your acquisition settings to locate and load a spool file
that matches your selection criteria, in this window:

- 214 -
Figure 13-3. The spool file preview window, presented from the Segment Options category.

If Catapult finds more than one match, it first prompts you to choose an entry from a list.
While this same preview window is available from many locations within your grab rule
definition, only options corresponding to the feature you’re working on are shown. So in
this case, these four options are available:
□ The segment start and end text.
□ The segment anchor and key text.
These are shown in the right-click and Edit menus, as well as the toolbar.
Locating the Required Split Definition Elements
After you load a sample of your report, you need to locate the required split definition
elements.
Selecting the Segment Start Text
The example report above shows a long report listing customer orders. Because of this,
the report page header includes generic information (the date range, report title,
date/time, page number) that isn’t particularly relevant to each of our customers, and we
don’t need to include it in the email we send them. So to specify the start location for our
split, we’ll find the first bit of information that is unique to each order, in this case, the line
starting with the text ‘Customer Name:’.
We’ll select this as our Segment Start Text by highlighting the string and clicking the
appropriate toolbar button:

- 215 -
Figure 13-4. Selecting the segment start text for a split rule.

When you click the toolbar button, both the text and toolbar button remain highlighted. To
unselect the text, place your cursor on it and re-click the toolbar button (or use the right-
click menu).
Selecting the Segment End Text
The next step would be to find another text string to mark the end of the segment, which
we could do as follows:

Figure 13-5. Selecting the grab rule’s segment end text.

In this illustration we scrolled down in our report to find the total line at the bottom, and
highlighted a portion of constant text on that line previous to clicking the toolbar button
that identifies that string as our segment end text.
The segment end text is highlighted in yellow, and the toolbar icon also remains
highlighted.
Reviewing the Results
If you click OK at the preview window to return to your rule, you’ll see the options have
been populated with our choices:

- 216 -
Figure 13-6. The segment start and end text values and start columns.

You can see that our two text strings are listed, along with their starting column locations.
The next step is to define the key value and key anchor text.

- 217 -
Segment Anchor and Key Selection
Once you have defined the boundaries of the sections into which you want to split your
report, you need to identify the values Catapult will use to determine when to split the
report.
These are the values we need to populate:

Figure 13-7. The segment key and anchor text.

Segment Anchor Text and Starting Column

The key anchor text is an unchanging string in your report, occupying a constant location
relative to the key field value. Catapult uses this constant to locate and identify your key
value.
The column and length specify where on the report the key anchor text is located.
Catapult scans every report line for the key anchor text at the column specified.
Key Location Column, Length and Line Offset from Key Anchor
The column and length specify where on the report the email address or key value is
located.

You can specify a key length because the sample you choose
from your report may not be representative of the actual field
length in the database.
For example, in the preview window you could choose ‘Joe

- 218 -
 Smith’ as a sample customer name, but your database will
include many other customers with longer names.

The line offset indicates whether the key value is on the same line as the key anchor text,
or above/below it. If the key is below the key anchor, this should be a positive value; if the
key is above the key anchor, this number should be negative-Catapult always locates the
anchor first, and counts up or down from that point to find the key.

Using the Preview Window to Identify the Key and Anchor Text
Once again, the easiest way to populate these values is using the preview window. If you
have closed the window after setting your segment start and end text, you can open it
again by clicking the View button. When you open the report, the two values you
previously selected are still highlighted:

Figure 13-8. Opening the preview window to define the key and key anchor text.

For this report we’ll use the Account Number as our key, which is just below the segment
start text.
To select the key we need to highlight the area it can occupy, and then we can either click
the toolbar icon or use the right-click menu option:

- 219 -
Figure 13-9. Selecting the report key value.

In case you’re wondering why we use an envelope in this icon,

it’s because historically we used this technique to extract the
split section’s distribution email address from the report body.
In Catapult 7 and higher, we would normally recommend
defining a separate extracted data value to do this.

You also need to find and select the key anchor:

Figure 13-10. Split segment key anchor.

As you recall, the key anchor is a static piece of text that occupies a constant location
relative to the actual key value (which changes throughout the body of the report).
When you click OK to return to your grab rule definition, you’ll see the values you
selected:

Figure 13-11. The selected key and key anchor text.

In this case, the line offset is zero because both values are on the same line.

- 220 -
Distribution Group (Optional)
If you intend to email, print of fax your split sections to a group of users, use the browse
button to select a distribution group.
When you set up the split rule distribution options you can choose whether every
member of the group will get every split section, or whether you will use key values
extracted from your report to send individual sections to their appropriate recipients.

- 221 -
Unassigned Split Segments
Some reports may have segments for which distribution details (an email address, fax or
printer) are not found in the matching group entry. There are a few choices available for
how you handle these unassigned sections.
Here is an illustration of the options available:

Figure 13-12. Selecting the action to take for unassigned report segments.

Don’t Process
The default option is to drop unassigned sections. Use this option on reports where you
would NOT necessarily expect each split section to have a valid recipient. If every section
of the report SHOULD have a matching target destination in the associated distribution
group, then use one of the other options.
Email to Default Admin Address
Select this option to email any orphaned sections to the administrator email address
specified in the poller configuration.
Email Unassigned Segments To:
As stated above, if the content of your report is such that all report segment should have
a recipient, you can select this option to email unassigned sections to the address you
enter here. Use this option when the Catapult administrator may not know enough about
a report and its split criteria to know whether the mismatched section is important, or who
it should go to.

- 222 -
 Note that sending unaddressed segments is not the same
as notifying an individual when mail is undeliverable.
If an email address is found in the group entry for a section,
an attempt is made to send the message. If an email
address is invalid and your mail server rejects it on send
(e.g. the mail is undeliverable), it will most likely get bounced
back to the address defined as the Return Address. See the
sections “Email Address Options” on page 275 and “Using
Groups with Report Distribution and Splitting” on page 283 
for further details.

When you are first creating and testing a split rule, you should always enable this option
for your first few runs, to help you troubleshoot any teething problems with your key
values or groups.
Print Unassigned Sections
Select this option to print a hardcopy of any unassigned sections of your report. Then
choose a printer from the dropdown list.

- 223 -
Using &K (Current Key Value) with Report Splitting
When defining a split rule, Catapult supports the ability to name files using the key value
derived from the report and/or save the split report into a directory of that name. (The
Key Value is just one of many supported replacement values available. For a complete
list, please refer to the section “Target File Name” on page 240 .) For example, if you
have a grab rule to capture a sales report you may want the report segment split by
territory and emailed to the appropriate territory manager. In addition to (or instead of)
emailing you could also have each section of the report archived in a directory that
identifies the territory.
Here is an example of a the Download category settings in a grab rule set up like this:

Figure 13-13. Using &K as part of your target distribution file name.

File Name
In this example we have specified that the name of the file downloaded from the IBM i
and saved on the server will be the IBM i spool file name (&n), followed by " - " and the
poller PC date (&y), followed by the key value extracted from the split rule (&k). If the IBM
i spool file name is SALESINFO, then the saved file name will be as follows:
For the report as a whole:
SALESINFO - 20000526.html

For Split segments, the saved file names would be as follows, for each city:
SALESINFO - 20000826 Sunbury.html
SALESINFO - 20000826 Manchester.html
SALESINFO - 20000826 Newcastle.html

In this example, the report is also being converted to html for access from the server via
a web browser.
Directory Name
The directory name in the example above is identified as \\mywebserver\invoice
reports\&k\. When the files are saved they will be saved as described below.
For the report as a whole:
\\mywebserver\invoice reports\SALESINFO - 20000526.html

For split segments:

Sunbury:
\\mywebserver\sales\Sunbury\SALESINFO - 20000526 Sunbury.html

- 224 -
 Manchester:
\\mywebserver\sales\Manchester\SALESINFO - 20000526 Manchester.html

Newcastle:
\\mywebserver\sales\Newcastle\SALESINFO - 20000526 Newcastle.html

Each directory is created automatically if it is not found. The characters extracted for the
key value in the split must be valid directory name characters for this facility to function
properly. Catapult is not able to validate this, and the grab rule will end in error if reserved
characters are included in the replacement values.

The following characters are not allowed in file names: / \ : * ?

“ < > | If any of these values are generated, Catapult
replaces them with underscores (_).

- 225 -
Report Splitting Examples
Example - Splitting a detail report by Company
The following split criteria has been specified:
□ Start Segment Text - "Customer Account Balances"
□ End Segment Text - *STARTTEXT
□ Key Anchor Text - "Company number:"
□ Key Value - Company Number, 3 characters long
And here is a sample of the report

This report contains a listing of Customers within Companies; however there is no unique
text to specify when each segment should end. This split rule will split by company, but a
company can stretch across more than one page, and there is nothing unique to signify
the end of a company. However, each company does start on a new page.
Therefore, the segment start text will be from the page heading:
Customer Account Balances Listing

The segment end text has been defined to be *STARTTEXT, meaning that when the text
defined by the segment start is encountered, a potential break has occurred.
As the Catapult Poller processes each line of the report, it scans to determine if the start
segment text has been encountered or if the key value has changed. If the start segment
text is encountered, and the key value changes on that page, a split occurs immediately
before the line containing the start segment text. This means that simply encountering

- 226 -
the segment start text doesn't mean that a break will occur. The split engine also reads
forward to see if the key value (in this case the company number) has changed. The end
of the section will only occur if the company number changes, or at the end of the report.
Example - Processing Customer Statements
In this example, the following split criteria has been specified:
□ Start Segment Text - "Invoice" (or *STARTOFPAGE if invoices always begin at
the top of a page, and you want to use an overlay image, as described in the
section “Finally, press F11 twice to display the 'Product Option' column, and
ensure that Option 8 is there. ” on page 262 , Report Transformation Options.
□ End Segment Text - "Please pay this amount"
□ Key Anchor Text - "Order Item"
□ Key Value - Customer Number 3 long (4 lines above the key anchor text)
Here is an illustration of the report:

In this report the spool file may contain 1 or more pages per customer.
As the Catapult Poller processes each line of the report, it scans to determine if the start
segment text or the end segment text has been encountered. If the end segment text is
encountered, the current segment will include the end segment text as the last line. The
next segment will then begin at the start segment text specified. In this example the split
is triggered by the end segment text not by the change in the key value.

- 227 -
 - Data Extraction

CHAPTER 14

Chapter 14 - Data Extraction

The Catapult data extraction features allow you to create and define values that you
intend to use elsewhere in your actual grab rule. There are two types of values: those
extracted from your current report’s body, and values retrieved via calls to external
programs.
A common example of where you may use an extracted value is if the email of the
intended recipient of a report split section appears in the actual report body. In this case
you could define an extracted data value identifying the location and dimensions of the
field, and then use that value in your distribution settings. You can also use extracted
values to retrieve addresses from external files by cross-referencing with key values in
your report, or even to build custom email subjects for each recipient.

Catapult also supports various standard replacement values

you can use in your reports, including a couple of special ones
that you can use in your split rules. For further information,
please refer to the sections “Target File Name” on page 240 
and “Using &K (Current Key Value) with Report Splitting” on
page 224 .

The following sections of this chapter describe both types of data extraction and how to
use the values in your grab rules.

- 228 -
Extracting and Using Report Data Values
From the grab rule Extracted Values options you can get data values directly out of the
reports and use these elsewhere in your grab rule definition.
The values you extract from the report are assigned to replacement values that you can
name (for instance, OrdNbr). Once you have defined these values you can use the
replacement values (i.e. &OrdNbr) in any field in your grab rule that supports
replacement values. For example, these values can be used to create a file path, to
customize the email address or subject, or to create passwords for PDF documents.

Creating Extracted Data Values

When you initially go to the Extracted Data Values category of your report you’ll see an
empty list. Click the Add button to create your first value. When you do this, Catapult
starts by displaying a copy of you report in the Preview window.

You need to use the Preview window to define your extracted

values, so in order to do this, your acquisition criteria must
match at least one spool file on your IBM i.

Consider this example report:

Figure 14-1. Defining extracted data values using a preview of your report.

Notice the three areas indicated above.

- 229 -
The Extracted Data and Anchor Text
The second box in the illustration above encloses both the actual extracted data value
and its anchor. In this example we want to trap the customer name (e.g. OER Music),
and we are using the text string next to it (Customer Name:) as the static text anchor (the
consistent marker to identify the location of the variable key value throughout the report).
The Toolbar Icons
The top box encircles the toolbar icons you can use to select the extracted value and
anchoring text. You can also use the right-click menu options to select or unselect the
strings.
The Extracted Data Value Name, Replacement Token and Attributes
In the bottom box you can see several fields that identify the extracted data value you are
defining. The attributes include:
□ Name. This descriptive value is used
□ Replacement Token. Enter a unique name to correspond to this value. This is
the insertion value you will use elsewhere in this rule, where you want to
incorporate the string you are identifying here. In the example above, the
replacement token is CustName, and using &CustName elsewhere in the grab
rule will include the Customer Name, as extracted from the report.

Make sure you use unique replacement tokens for each value.
It’s a good idea to establish a naming convention for these
within your rule, to ensure they are unique. You may also wish
to establish standards for setting these up consistently across
grab rules.

□ Anchor Text and Position. This is a constant text value in your report, which
occupies a consistent position with regards to the text you want to extract. To
right of this are the starting locations and lengths of both the Anchor Text and
actual value.
Steps to Identify the Value
To identify the value you need to follow these steps:
1. First find an instance of your target value in your report. This is usually a
variable field.
2. Highlight the area of your report occupied by that field, making sure to use a
length that matches the longest value your report may include. Then click the
Set Extracted Value Key Location button (or use the right-click option).
3. Then find a piece of static, unchanging text that occupies a consistent location
in your report with relation to that value. Highlight this text and use the right
click option (or toolbar button) to select it.
Finally, type a name and replacement token for the selected value at the bottom of the
screen and click OK to return to your rule.
When you return to the main grab rule definition, you will see your new value in the list:

- 230 -
 Figure 14-2. A new replacement value.

From here you can add new entries or delete ones you no longer use. Use the Properties
button, or double-click an entry, to review the value definition in the preview window.

Using Extracted Data Values

You can use the variables (&CustName, etc.) corresponding to your extracted values
anywhere in your grab rule definition where replacement values are supported.
Here is an illustration of how to use an extraction value:

- 231 -
Figure 14-3. Using the replacement token of an extracted data value.

Here we have used the replacement value in the path for the location in which to archive
the downloaded file. This way the documents will be placed in an appropriate directory
for that company.

- 232 -
Calling External Programs to Get Replacement Values
It’s possible that as you begin to use Catapult you already have IBM i files that include all
your users with their names and profiles and email addresses, and programs that return
these values. So you may not want to take the time to duplicate this information into your
Catapult distribution groups, nor subsequently maintain this information in two places.
For this type of situation (and others) Catapult allows you to call your own programs that
return replacement values you can use in your grab rules.
Your program can be as simple or complex as you need. In most cases you will only
need a simple program that does a lookup to a master file and returns one or more
values, such as email addresses or fax numbers.
The call-out program must have the following parameter structure:
□ Input: 2000 bytes (passed from Catapult Poller and received into your program).
This will contain the key values for the record retrieval.
□ Output: 2000 bytes (passed from your program back to Catapult Poller).
The Output parameter must be in ‘double quoted string’ format. This means that each
entry returned to Catapult must be enclosed in double quotation marks and there must
be at least one blank space between each value. For example:
“larryf@finklestein.co.uk” “secretpassword” “myownfolderpath”

The first value returned is associated with the replacement parameter &B0. The second
value is &B1, the third is &B2, and so on.

There is a hidden feature in Catapult, almost a curiosity

really, that can be used in conjunction with your returned
email parameter value to selectively drop certain report
sections rather than distributing them by email.
The is an internal Catapult distribution process that assigns
a distribution value of **D-O-N-T-S-E-N-D** to report
sections that for whatever reason (as established by the
grab rule’s logic) shouldn’t be emailed. If you have particular
report sections you determine in your external program logic
that you do NOT want to distribute, you can set your
program up to return this special value in place of the email
address, and Catapult will drop the report section.

Examples
Here are a couple of examples of how to use this feature.
Though you can make these programs as simple or complex as you require, this concept
gets exciting when you consider that the input parameter could be a combination of
extracted data values retrieved from the report (&CustName, &OrdNbr, etc.), alternate
data values (from your distribution groups), as well as any standard replacement values.

- 233 -
 Example 1:
Here are examples of two parameters:
Parameter One (input): "&U&EmpNbr" --> "BOB 10456"
Parameter Two (output): bobm@here.com --> &B0=bobm@here.com
Example 2:
Here are two more parameter values:
Parameter One (input): "CompID=&D ID=&EmpNbr" --> "CompId=SD63 ID=10456"
Parameter Two (output): "Active" "#1 First Street, Sidney BC" "mypassword"
In this example, &B0=Active (customer status, and maybe used in the email header for
additional information), &B1=#1 First Street, Sidney BC (mailing address, maybe used in
the email footer), &B2=mypassword (a password that you will use to encrypt the PDF
version of this person’s report).

Setting up your Grab Rule

In the example below, a program is being called that expects a three character company
number. The company number is the key value identified by the report splitting
procedure:

Figure 14-4. Setting up a call to an external program to retrieve additional values.

The call-out program returns the following string:

"larry.finklestein@finklebert.co.uk" "myspecialpassword"

- 234 -
 This is the contact email for the company and a password that would be used to encrypt
their reports.

Note that it is your responsibility to ensure that your program

exists, is correctly written, is accessible to the user profile
logged into Catapult, and has access to all required libraries
and other objects. Catapult doesn’t monitor the calls, so if
your program doesn’t run correctly and returns incorrect,
blank or no parameters, Catapult doesn’t currently have a
way of detecting the problem.

Using the External Data Values

&B0 is associated with the first quoted string, and in this case would be used as the email
address, as shown here:

Figure 14-5. A distribution group entry, where the email is loaded from an external program.

In this illustration, the first value returned by our program is associated with &B0. So a
company number occurring in the report is used to retrieve a contact email address from
a file, and using a distribution group, that email address is set as the target recipient for a
split section.

Example Program to Retrieve Database Values

Here is the code for an example call-out program:
01.00 * Place your files here (notice that they are defined with
01.01 * 'user open' so that we can control when
02.00 * the files are opened: i.e.: after the ovrdbf)

- 235 -
03.00 FCOFILE IF E K DISK USROPN
04.00
05.00 * Input and Output parameter. Do not change these. The
06.00 * Catapult Poller requires the parameters to be 2000 bytes.
07.00 D inParm S 2000
08.00 D OutParm S 2000
09.00
10.00 * A structured version of the input parameter.
11.00 D inParmDS DS
12.00 D iCONUM 3S 0
13.00
14.00 * Standalone variables to hold key values.
15.00 D DCONUM S 3P 0
16.00
17.00 * Variable to track whether the file is opened or not.
18.00 D opened S 1a
19.00
20.00 * variables to adjust the library list
21.00 D ADLLE S 500A
22.00 D CMDLTH S 15P 5 INZ(500)
23.00 *
24.00 *call entry parameter list must not be changed.
25.00 C *ENTRY PList
26.00 C Parm inParm
27.00 C Parm outParm
28.00
29.00 * Check if the file is open. If not override to the library
30.00 * required for data files, and then open the file.
31.00 C if opened <> 'Y'
32.00
33.00 * add the database file library
34.00 C eval ADLLE = 'ADDLIBLE LIB(callout)'
35.00 C call 'QCMDEXC' 80
36.00 C parm ADLLE
36.01 * add l
37.00 C parm CMDLTH
37.01 * comma
38.00
39.00 * open the file!
40.00 C open cofile
41.00 C eval opened = 'Y'
42.00 C endif
43.00
44.00 * A key list!
45.00 C @KLST KList
46.00 C KFld DCONUM
47.00
48.00 * Populate the key fields
49.00 C movel inParm inParmDS
50.00 C eval DCONUM = iCONUM
51.00
52.00 * Chain the record (don't lock it)
53.00 C @KLST chain(n) rCOFILE 21
54.00
55.00 * Populate the return value. Ensure each value returned is
56.00 * enclosed in double quotes and has at least one blank
57.00 * space separating it from the next value. This example
58.00 * will return the email address and a password.
59.00 * The email address will be &B0 in the grab rule, the
60.00 * password value will be &B1.
61.00 C eval outParm = '"' + coeml + '" ' +
62.00 C '"' + copass + '"'
63.00
64.00 * Use a return to close this program and leave the file
65.00 * open to help improve performance on subsequent calls.
66.00 C return

- 236 -
If you want to use this source as a starting point, you can open the PDF version of this
guide and copy it out using the Text Selection tool.

- 237 -
 - Report Transformation Options

CHAPTER 15

Chapter 15 - Report Transformation Options

Catapult’s default file format for downloaded files is plain text (files with an extension of
.txt). If you are using a data extraction tool you can also select the .prn format for your
report. When you do this, the file itself is not reformatted in any way.

- 238 -
Supported File Types for Report Transformation
There are, however, several formats you can use to add functionality to your
downloaded reports. For example, by saving your reports in PDF format you can ensure
that they are presented in a consistent format to every recipient, and also override file
printing and saving options. RTF is useful for situations where you need to override the
page size or font of your report, perhaps to have more control over how the document
prints. To post your documents online, HTML may be the best solution. And if you have
an AFP report that you need to distribute, you can send it as a TIF file. You can also
download *SCS spool files in TIF format; this may be useful or archival purposes where
retaining the exact formatting is critical.

If you intend to convert spool files to RTF and PDF formats to

be printed from the poller PC, you need to ensure that
appropriate supporting software (a PDF Reader such as
Adobe or Foxit’s, Microsoft Word®) is installed on that PC. For
details, review the section “Step 8: Install Additional
Applications on the Poller PC” on page 57 .

Using Your Own Extensions

In addition to the supported formats shown in Catapult you can also type any extension
you want after the report name. Though the generated file will be a plain text file, by
overriding the extension and adjusting your file associations on the poller PC, you can
control what application is used to open the file.
For example, suppose you knew that all your intended recipients used OpenOffice. In
that case, you could set the file extension of the distributed files to .svw, so when
recipients clicked on their attachments they automatically open in the Writer.

Keep in mind that word processing applications often apply

overrides when opening unformatted files, so if you plan to
make use of this feature you should test the results
beforehand.

Using the *RICH Download Format

PDF, RTF and HTML documents allow you to retain embedded bolding, underlining and
overprinting attributes from the printer data stream. To do this, simply select the *RICH
download format (on the Spool File properties of the Acquisition category), in conjunction
with any of these three document types - no additional formatting is required.

- 239 -
Setting the Generated Document Name & Format
To change the default name or format of the document(s) that Catapult will generate,
start by going to the Transformation category of your grab rule, shown here:

Figure 15-1. Beginning to work with the grab rule transformation options.

In this illustration we are switching the target document format to Adobe.

Target File Name

This value represents the name of the downloaded spool file on the Server PC. You can
enter a constant name or use the replacement values shown below. You can also use
combinations of constant text and one or more replacement values. These are the
supported replacement values (in alphabetical order):
Replacement
Description
Value
&d or &D User Data
&f or &F Spool file number (within the job)
&g or &G Grab rule number
Increment value of a split section. If used for a
&i or &I
base report, this is dropped.
&j or &J IBM i job name of selected spool file
Current key value of a split section. If used for a
&k or &K
base report, this is dropped.
&l or &L Grab rule description

- 240 -
 Replacement
Description
Value
Job number (the IBM i job that created the spool
&m or &M
file)
&n or &N IBM i Spool file name of selected spool file
&r or &R Request Number
Current poller PC time (when value is replaced) in
&t or &T
HHMMSS format.
&u or &U IBM i User ID of selected spool file
&v or &V Spool file time (as opposed to the system time).
Current poller PC date (when value is replaced) in
&y or &Y
YYYYMMDD format.
&z or &Z Spool file date

Note that these replacement values can also be included at many other locations within
your rules, such as the PC path and the email subject.

Inserting Replacement Values

To insert these replacement values in this or any other field that supports them you can
right-click in the field and select the Insert Replacement Value option from the menu.
When you do this, Catapult displays this nifty list from which you can select the token you
need:

Figure 15-2. Using the Replacement Value insertion tool.

Click the value you need to use and then the Select button.

- 241 -
 The list will include all the replacement values that have been created in the report, and
which may be used elsewhere in your grab rule criteria.

The exception to this is the Additional Data Values that can

be associated with distribution list entries.

Document Format
Supported document formats include plain text, Dat Extraction's PRN, Adobe PDF, Rich
Text Format, HTML, TIF (an image, to include *AFPDS attributes) and PCL (Printer
Control Language).

If you intend to convert spool files to RTF and PDF formats to

be printed from the poller PC, you need to ensure that
appropriate supporting software (a PDF reader such as Adobe
or Foxit’s, Microsoft Word®) is installed on that PC. For details,
review the section “Step 8: Install Additional Applications on
the Poller PC” on page 57 .

Adobe (PDF) Files

Adobe PDF is one of the handiest and most popular formats available for distributing
documents of any kind. By saving your reports in PDF format you can ensure that the
report is presented in a consistent format to every recipient. When you create a PDF
document, you can also control many report formatting options that plain text (the
default) doesn’t allow you to change.
Internet (HTML) Files
You can use Catapult to download IBM i reports and convert them to HTML files on your
PC. As with generating PDF files, you can also build your grab rule such that Catapult
extracts key values from your report and builds a hyperlink table of bookmarks at the
beginning of your HTML file.
HTML documents only support a subset of the setup options available when generating
PDFs.
RTF Files
Converting your downloaded IBM i report to RTF format allows you to override several
different print settings and have more control over how the report fits on a printed page.
As with PDF and HTML, you can also customize your RTF files to include bookmarks for
selected key values in your report.
PCL Files
The PCL (Printer Control Language) format is designed to be used for downloading
spool files of type *USRASCI, to print on certain HP printers. It includes extra command
characters to control formatting that those printers can understand. Catapult performs

- 242 -
no additional formatting on the data coming from the IBM i, which is downloaded using
an IBM API and saved as a .pcl file in raw form.

- 243 -
Document Setup Options
The options available to customize the appearance of your generated documents
depend on the target form you select. Converting your spool files to Adobe PDF gives
you the widest range of formatting options available, while RTF and HTML files support a
smaller set of options. Catapult enables only the options supported by the target format
you pick.

If you plan to generate PDFs from your spool files you need to
also use the *RPT or *RICH (not *FILE) formats at the spool file
acquisition options. This ensure that page breaks are included
in the generated file; otherwise the your PDF reader will only
display a single page.

PDF Document Setup Options

These are the page setup options available when you create a PDF file:

Figure 15-3. Document setup options available when generating PDF files.

Overriding the Defaults

Click the Override Defaults checkbox to enable the rest of the options.

When deciding whether to override the PDF file settings in

Catapult keep in mind that the software defaults will in most
cases work for you. You should only have to override the
default settings if you are downloading a report with a non-

- 244 -
 standard page size or character settings. So before you
change these settings, we recommend that you first test a
download without overrides to check what changes, if any, are
required.

If you are having to always override the defaults, contact Technical Support and we can
look at your report and how Catapult is handling it by default.
Paper Size and Orientation
By default, reports are printed to a standard 8.5 x 11 inch sheet of paper, oriented in
portrait mode. You may also choose landscape for your page orientation, and/or use
these paper sizes:
□ Legal (8.5 x 14 inches)
□ A3 (297 x 420 mm)
□ A4 (210 x 297 mm)
□ A5 (148 x 210 mm)
In addition, you can choose to generate a custom paper size and specify the dimensions
(in millimeters) using the width and height options.

Keep in mind that WordPad does not handle all RTF formatting
commands. For example, WordPad prints all documents in
portrait mode, and does not support overlay images. You
should use Microsoft Word® or another full-featured word
processor to open and print RTF documents.

When you choose your paper size, always take into account what you expect your
recipients to do with the files. For instance, if most people will be printing the reports this
grab rule sends them, then you need to confirm that they have access to printer that
supports the page size you pick.
Margins
When you override the layout the page margins are initially set to zero.
Use these values to adjust the amount of space left on each edge of the printed page.
These settings are particularly useful when you need to align report content in a form
overlay.
Max Lines Per Page
If your downloaded report doesn’t include page breaks, you can use this value to insert
page breaks in the PDF files you generate. This option is only supported in PDF files.
If you enter a value here, Catapult will add a page break regardless of whether it finds an
actual page break formatting character in the source document.

- 245 -
 This option exists mainly to be used when polling network
directories for text file to distribute; IBM i spool files normally
contain appropriate page breaks.

Leave this option set to 0 to not perform any page break overrides.
Font & Font Size
Specify the base font and point size for your printed report. Catapult will by default use a
monospaced font such as Courier for your reports, but you can choose other fonts if you
prefer.

Sometimes when you open a PDF document created by

Catapult in the Adobe Reader (and possibly other PDF
readers) you may find that the font is hard to read, due to the
lightness of the color. The reason for this is that the readers
attempt to make your reading experience as comfortable as
possible by smoothing the edges of fonts, creating several
transitional shades of grey between the font's black color
and the white background. This grey border is always about
the same width regardless of font size. With large fonts it's
almost unnoticeable as the border is a small portion
character width/height. With small fonts, the grey border on
one side of a character can merge with the other border so
no black pixels remain between. This is why the font color
appears to be grey when the PDF is zoomed out, but it
becomes black when zoomed in. Although the zoomed out
document may be hard to read, the document as a whole is
MUCH more readable than if only black pixels were used.
The display depends partly on your screen resolution, as the
lower it is the more readable everything becomes. If you are
convinced that you would prefer text with no smooth edges
you can select this by going to the Edit>Preferences>Page
Display option (Adobe Reader 7.0) and unchecking the
Smooth Text option.

Font & Font Size for HTML Files

When you set these options for HTML files Catapult adds a <font> tag at the beginning of
your HTML, with a ‘size’ attribute matching what you select. A typical value is a size of 2
or 3. The range of values supported is from 1 to 7, where 1 is smallest.
Leading
This value allows you to control the amount of space between lines of text in the
outputted file. This is useful for ensuring that the number of lines per page of your PDF
file matches that of your IBM i report. Generally, the leading value should be the same
as, or greater, than your font size.

- 246 -
 Leading is pronounced ‘ledding’ and has its roots in early
typesetting times when strips of lead were placed between
lines of text to create space.

Character Spacing
This value specifies an amount of additional space for each character. You may need to
adjust the spacing when your IBM i report is using a non-standard CPI value, which can
result in extraordinarily wide or narrow reports when they are rendered in PC fonts.
Embed TrueType Fonts?
Select this option to embed the necessary fonts in the PDF document so your recipients
don’t need to have the font you choose installed on their PC.

Embedding the TrueType fonts will ensure the document

renders in the viewer’s PC exactly as you intend; however, the
size of the PDF file will increase by the size of the font(s)
embedded.

Encoding
This option is available for a subset of European languages with extra characters. It
changes the font encoding to replace those characters not used in a specific language
with ones that are used. For example, English uses the MS 1252 – Latin 1 encoding, but
Polish has a number of extra characters not used in English. In that case, Polish clients
would use the MS 1250 – Central European encoding, in order for PDF and RTF files to
be created correctly.
You can change the default value for this option in the Rule Editor section of the console
configuration.
Style Sheet Web Path
This option is available when you convert your report to HTML.
These days, almost all web sites with any degree of sophistication use external style
sheets to enable designers to make sweeping, site-level changes by modifying a single
referenced file. If you are using Catapult to distribute your reports as HTML, the Catapult
Poller HTML generator supports the ability to include a link to an external style sheet
within the generated HTML document.
The style sheet itself is external to Catapult; you need to create it yourself, or your
organization may already have files they use. There are several programs that you can
use to edit style sheets, including mainstays such as Notepad or TopStyle Lite.
The web path to the style sheet should be as fully qualified as necessary, to allow the
web server serving your document to find the style sheet.

- 247 -
Bookmarks
When you convert an IBM i report to Adobe PDF, HTML or RTF files Catapult allows you
to define bookmarks that identify key locations within your report. In a PDF file the
bookmarks appear as a list of hyperlinks to the left of the main report window, while in
HTML and RTF documents the bookmarks are added at the top. Figure 5-14, on page
113 of the tutorial section of this guide, is an example of a PDF with generated
bookmarks.
Here is an illustration of the bookmark options:

Figure 15-4. Adding bookmarks to a generated PDF, HTML or RTF file.

Add Bookmarks for Each Page (PDF Only)

When you generate a PDF document, the document will by default have bookmarks for
each page in the document.
Order Bookmarks in Order of Appearance (Within the Document)
Select this option to create bookmarks in your generated report, where the entries are
listed in the same order as the values you extract from your report.
Order Bookmarks Alphabetically
This option allows you to sort your list of bookmarks alphabetically by key. The report
itself is not affected by this option.
Bookmark Anchor & Starting Column
The bookmark anchor text is a constant text string in your report that occupies a
consistent location in relation to the bookmark key value. For example, if the key value
you want to build bookmarks for is a salesperson number, the anchor text could be a text
string 'Sales Person:', which is always found immediately to the left of the actual key
value.

- 248 -
 In Figure 15-5 we are distributing order reports, and using the string ‘Customer Name’
(starting in column 2) as the basis for identifying the adjacent key value which starts in
position 17.
The easiest way to load these options is from a preview of your report.
Key Location Column, Length & Line Offset from Anchor
These values are used to specify the location of the key value on the report, in relation to
the anchor text. Enter the line position of the key, and the length of the value (you can
either type these values in directly, or use the Preview Window, illustrated below).
If the key is above or below the anchor text you must also enter a value for the Line
Offset. The offset value is calculated by starting at the line where the key anchor value is
found and counting either forwards or backwards, one line at a time, up to and including
the line containing the actual key value. For example:
□ If the key is 2 lines above the key anchor text, type a value of -2.
□ If the key is 1 line below the key anchor text, type a value of 1.
Note that the line offset value may be affected by whether you download your report in
*RPT or *FILE format (with or without embedded blank lines).

Using the Preview Window to Define Bookmarks

To avoid the challenge of counting out the columns and string lengths for your bookmark
key and anchor, use the spool file preview option to define these values.

In order to use the preview functionality from here you need to

have previously defined your selection criteria, and the criteria
must match at least one existing spool or network file. For
more information on this option, you can also review the
section “Spool File Selection Preview” on page 201 .

Click the View button to load a copy of your spool file. Here is an example of the window
presented:

- 249 -
Figure 15-5. The bookmark key and key anchor text definitions in the report.

In this report we want to build bookmarks using the customer name. A constant text
string that identifies the location of this key value is ‘Company Name’ (to the left of the
key, in the second box shown above).
Setting the Bookmark and Anchor Text
To set the required values, highlight the constant text string and use the right-click
options or toolbar icons to select the Bookmark Anchor Text option. This populates the
key anchor text, column and length values.
Then repeat this for the actual key value. In the example above, this would involve
highlighting the text ‘OER Music’ (and some extra spaces to the right, to account for
longer company names) and then clicking the Bookmark Key Text button to select the
segment as the bookmark key location.
The Bookmark Summary
The bottom box in the illustration above encloses a summary of your bookmark details,
which you can also see back in the main grab rule window.

- 250 -
PDF File Options
PDF files support a number of options that allow you control access to the file, and
whether different types of changes are allowed for the file.
Below is an illustration of the PDF options:

Figure 15-6. Additional options available when generating PDF files.

Compress Text and Graphics

Check this box to significantly reduce the size of your generated PDF file.

Under normal circumstances, there shouldn’t be any reason

to not select this option. There are, however, a couple of
troubleshooting scenarios in which it can be useful to
uncheck it. For instance, if you run into any problems
generating a PDF file (such as incorrect characters, for
example), our development team can use an unencrypted,
uncompressed version of that PDF to start tracking down the
source of the problem.
In addition, we have found out over time that Adobe’s
Reader doesn’t always interpret PDFs consistently across
releases. If you are having trouble with a particular version
of Catapult generating PDFs that a particular version of
Adobe can’t open, an unencrypted, uncompressed version
of the PDF can also be useful in identifying the problem area
in the report.

- 251 -
 Both text and images are compressed. Because most reports downloaded with Catapult
are almost entirely made up of text, they compress very efficiently. Images (used in form
overlays, for example) don't compress as much since JPG is already a compressed
format.

Encryption
The PDF encryption is done to Adobe Acrobat specs using non-proprietary compression.
It works similar to compression where tags are left unencrypted, but string and image
data are encrypted.
The following additional options are available when you check the Encrypt Text and
Images option.
Security Settings and Open File Passwords
There are two passwords you can use with PDF files. The Security Settings password is
used to secure the file Security Settings (for the ‘owner’, in Adobe terminology). The
Open File password determines whether you are allowed to open the document (the
‘user’, in Adobe terminology).
If an Open File password is created, Adobe’s Reader or Acrobat display a password
prompt before opening the document. If a user password is not set then everyone can
open the document for viewing, and are only restricted by the allowed operations
(print/select copy/modify/modify annotations).
If the PDF file is opened in Adobe Acrobat (the PDF reader/writer) and the Security
Settings password is also supplied by the user when the document is opened, the user
can then perform any security related function including changing the passwords,
changing the allowed operations, and re-encrypting the file.
Password Usage Considerations
If the generated Adobe PDF file is encrypted with only a Security Settings password, it is
possible that a programmer could write a program that reads the file and decrypts it. This
is because the file is actually encrypted by the user password, which being blank, is
defaulted to a known standard value.
If the file is encrypted with both a user and owner password, the file will have to be brute
force attacked because the Open File password is encrypted with the RC4 algorithm
using the MD5 hashed Security Settings password as part of the encryption key.
Passwords and Replacement Values
When you specify a password you can take advantage of Catapult’s support for
replacement values. You can use any valid replacement value (including extracted data
values, additional values in distribution list entries, and the external data values &B0 -
&B9) to customize the password generated for a file.
Allow...
These check boxes allow you to enable or disable a variety of options for working with
PDF files. By default all options are unchecked, so if you wish to allow the viewers the
ability to print the document, copy and paste from it, or make changes to it, you need to
check the corresponding options.

- 252 -
Document Title, Subject and Keywords
These values are PDF file attributes that you can set. To see these options in a PDF file
go to the File/Document Properties interface. You can also use replacement values in
these fields.

- 253 -
Overlay Images
A useful feature when distributing certain types of reports is to combine your IBM i report
data with company letterhead or other preprinted forms. For example, Catapult is
frequently used to automate the distribution of invoices by email. If you switch to
distributing invoices by email, you probably want your customers to receive something
that:
□ includes the relevant data,
□ looks like the printed invoices they have been receiving in hardcopy,
□ is not subject to being changed,
□ and can be printed by the customer for hard copy/audit purposes.
By creating a grab rule that uses overlay images to produce a secured (or encrypted)
PDF document, you can meet all these criteria.

One potential issue that you should be aware of when using

Form or Overlay Images is that when the generated PDF or
RTF files are printed from the poller PC as part of your grab
rule’s instructions, the JPG overlay image is transmitted to
the printer as an uncompressed BMP file.
Normally, this isn’t a significant concern. However, it can
become an issue in the following situations:
□ You are printing either large or many documents, or
both.
□ The poller PC is printing the document to a network
printer.
□ The network printer is remote (at another site, or even
in another state or province).
In these situations, you may end up transmitting many large
files across your network, which can negatively impact both
Catapult’s ability to print documents, as well as the speed of
other network connections.

Building Overlay Images into your Grab Rules

Overlay images are supported with PDF, RTF and HTML files. Select one of these file
types from the Transformation category. When you choose one of these three formats,
the Overlay options become available.
If you use overlay images you will likely also need to become familiar with the document
setup options, so you can fine-tune your report spacing and fonts to work with the
background image(s) you select. The document setup options are discussed earlier in
this chapter, on page 244.
Here is an illustration of the Overlay options:

- 254 -
Figure 15-7. Document overlay options for PDF, HTML and RTF files.

Overlay Options
Besides the default of No Background Images, there are five choices you can select
from:
□ First image for every page. Select this option to use the first (and only)
specified image as a background for every page in your report.
□ First image for page one. Second image for subsequent pages. If you select
this option, image one is used on the first page of your report, image two on all
other pages. This is analogous to ‘letterhead’ vs. ‘second sheets’.
□ Alternate images. First image on odd pages, second image on even pages.
If you select this option, image one is used on the first page of your report and all
odd numbered pages, and image two on the second page of your report and all
other even numbered pages. Analogous to book printing.
□ First image on first page only. Select this option to use an overlay image on the
first page your report only, and nothing on the remaining pages.
□ Named image by page number (imagename[x].jpg). Use this option if you
want to specify a unique background image for every page of your report. Do this
by embedding a unique replacement value in your image name that
corresponds to the generated file name. Use the special replacement value of
&p to append the current page number.
If you use the first or last two options, you only need to select one image. The second and
third options require that you select two images.
Network UNC Path for Image One/Image Two
These are the background images to be used in your PDF, HTML or RTF overlay. The
path corresponds to the UNC path to the image. Note that there may be significant

- 255 -
 performance degradation during the generation of your document if your image or
images are located on a network drive rather than on the local poller drive.

Using Replacement Characters in PC Paths and File

Names
You need to be careful using replacement values in any PC
Path, as Catapult cannot determine a valid windows
directory name. The following characters are also not
allowed in file names: / \ : * ? “ < > |
If any of these values are generated, Catapult replaces them
with underscores.

Using Replacement Values in your Image Names

Note that the image names you add here support the inclusion of replacement values.
For example, if you were splitting your report on a key value relating to a location code,
you could use a different overlay image for each location by embedding an &k in the
image name (or path, if you had identically named images in different folders). For a list
of the supported replacement values, see the section “Target File Name” on page 240 .
Web Image URL
The web image URL is required only for HTML, and needs to be a location accessible to
your recipients when they receive the HTML file. For example, if you are using Catapult
only locally, the image could reside somewhere on your intranet. The reason for this
extra value is that unlike PDF and RTF, the background images in HTML files aren’t
embedded in the actual file but rather retrieved when the file is loaded by the browser or
email client.
If you are using title and/or footer pages with your reports (using the options in the Title &
Footer Pages category of your grab rule), you can also set those up to reference the
same image you specify here.
Specifying *NONE for the Image
*NONE is supported for the image filename. This was implemented to allow leaving the
first page image blank, but to have an overlay for all following sheets.

Using Overlay Images with Report Splitting

If you are using overlays for distributing monthly invoices, or another report of that
nature, it’s likely that you don’t have individual spool files generated for every invoice.
Rather, you probably have a single report with all the invoices, which needs to be split
before distribution.
The splitting engine has two options designed to be used particularly for overlay images
with your reports. If you go to the report splitting definitions and click on the Start/End
options, you can see that there are a couple of special values supported for where you
want to start and end each split section. The two values designed to be used with
overlays are *STARTOFPAGE and *ENDOFPAGE, illustrated below:

- 256 -
 Figure 15-8. Using the special values *STARTOFPAGE and *ENDOFPAGE.

The reason these special values are needed is that the split engine normally uses a
specific line of text to tell it where to start and end a split section. However, if your form
requires a certain amount of blank space at the top of the page, before the report data
starts, then you need to include that blank space in your split section. For example, if
your company invoices have a logo across the top and bottom inch or two of the page,
your split needs to take that account, and not just start a split section when actual data is
encountered.

If your split section spans more than one page the split engine
doesn’t end the split until the key value changes. So even if
you select the value *ENDOFPAGE for the Segment End, the
split section isn’t actually ended until the end of the page just
prior to the next key value.

Example: Using a Pre-existing 8.5 x 11 Form

This section and the following ones will summarize the steps that you might typically have
to perform to take advantage of the overlay image features. Keep in mind that these
scenarios may not exactly match your own situation; they are intended as general
guidelines, rather than specific step by step instructions.
The first situation we’ll look at is where you have an existing form printed on an 8.5 x 11
page, and want to match that up with an existing IBM i report.
Creating the JPG Image
The first step is to get your form into JPG format. You can do this by scanning an existing
printed form, or better yet, finding the actual electronic source document, and trying to

- 257 -
export it to an image in JPG format. Check your options with the person or firm
responsible for creating your images. The JPG image may be color or grey scale.
After you have the background image you need to put it where it will be available to the
Catapult Poller, so it can construct the PDF, RTF or HTML document. Usually this just
means saving it somewhere on your network, though putting it on the local drive of your
Catapult Poller system is a good idea. Performance during document generation is
better if the image is on a local drive, since the poller does not have to connect to a
network drive to retrieve the image.
Creating the Grab Rule
In addition to the normal information you need in a grab rule, such as the selection
criteria and email address, you need to also determine the target format you want to use.
In this first example we will use PDF. Once you select this as your download format, the
‘Overlay’ tab (illustrated in Figure 15-7) appears in your grab rule definition, from which
you can select the overlay image.
For your first attempt, select the option to use only one background image on every page
of your report. Refer to the previous sections of this chapter for specific instructions on
how to add an image to your rule.
Next you need to decide if your rule is going to require a split. Again, for simplicity’s sake,
we suggest you try your first rule without a split, and once you get the page layout set up
correctly you can add the splitting logic.
After selecting the image to use in your rule save the grab rule and trigger the poller. You
should get an email shortly after that.
Adjusting the Format
The first time you get the report you will likely have problems with alignment, font sizes
and field locations. Here is an illustration of what might be a typical first attempt:

Figure 15-9. First attempt to line up a standard form with an IBM i report.

- 258 -
Notice some of the problems here: the font is too small, the headings are too far from the
top of the page, and everything is too far to the left. These issues are easily adjusted by
overriding the PDF attributes in your grab rule. In this example, after checking the results
of our first attempt, we returned to the Document Setup section, where we selected the
Override defaults option and made the following adjustments:
□ We increased the font size to Courier 13 point.
□ We decreased the top margin width by half an inch.
□ We increased the left margin width by about an inch and a half.
Then we deleted the Catapult history record for this rule (or reran the report) to try it
again.
This process of fine-tuning the appearance of the report via the Catapult attributes may
take a few iterations as you make minor adjustments to your margins and fonts until you
get everything lined up just right. And if you are also able to adjust the spacing or content
on the actual IBM i report itself, then you can use that as an additional means to match
your report to your image.
Here are our results after we made the changes described above:

Figure 15-10. Second attempt to generate a PDF report with a form overlay.

Even here there may be a few more changes that could be made, but for a second
attempt this is not too bad.
Here are some other scenarios that we might run into with this form, and how we would
address them:
□ On orders that have many more items, we might find that they run below the
bottom of the page. To address these we could either make the font a little

- 259 -
 smaller again, or play with the character leading. This override attribute lets you
adjust the spacing between the lines of your report.
□ If the order ran to multiple pages, and the subsequent pages of the IBM i report
didn’t have the same layout as the first page, we might run into trouble with the
form above. To address this, you would need to have a second version of your
image, for orders running over the first page, and attach the second image at the
Overlay tab in your grab rule.
As become more familiar with these options, you will be able to adjust your settings more
quickly.

Using an Image on a Web Page

Due to the limitations of HTML, when you use a pre-existing image on a web page you
don’t have as much flexibility as when you are creating an RTF or PDF document. With
PDF and RTF there is a wide range of report attributes that you can override, while with
HTML documents, the only thing you can adjust is the font size.
This means that to successfully set up an overlay image on a web page you will be more
reliant on being able to change the layout of either the image itself, or the IBM i report.
You also have the option to use a style sheet to try and exert more control over how the
image is handled.

- 260 -
Using Catapult Rich Format Tags in Your Reports
Catapult has the ability to retain bolding, underlining and overprinting encountered in
your downloaded reports when generating PDF, RTF and HTML documents. To do this,
select the *RICH Format option in the Spool File Acquisition options, as shown here:

Figure 15-11. Setting the spool file download format to support *RICH format tags.

If all you need to do is preserve bolding, underlining and overprinting that already exists
in your IBM i report, this is all you have to do.
However, Catapult also allows you to embed special Rich Text Format tags in your actual
report to add underlining, bolding and alternate fonts, including a bar code font. These
features are described in , Rich Text Formatting Options Reference.

- 261 -
Creating TIF Files
TIF (Tagged Image Format) files are designed to be used for reports that include AFPDS
attributes, though you can also download *SCS spool files into TIF format. When you
build a grab rule to select an AFPDS spool file, you must use TIF as the format of
generated the PC file.
Note that a TIF file is an image, and the recipients of the file will need to have installed on
their PCs a utility that is able to display it correctly. This generally shouldn't be a problem,
as .tif is the standard format for most faxing software and the default image editors on
most PCs support this format. However, certain image editors do not support multi-page
images. If you see only the first page of your report, then this is probably the case.
Because a TIF file is downloaded as an image, report splitting and batch file processing is
not supported for these. Also note that the TIF file is created on the IBM i, and the
Licensed Program 5722SS1 Option 8 (AFP compatibility fonts) is required in order to
generate TIF files. You can confirm that you have this by doing the following:
□ At an IBM i command line type: GO LICPGM and press <Enter>.
□ Select menu option 10 (Display installed licensed programs) and press <Enter>.
□ After a few moments, a list is displayed. There may be a number of 5722SS1 items.
Finally, press F11 twice to display the 'Product Option' column, and ensure that Option 8
is there.

- 262 -
Using Title and Footer Pages in your Grab Rules
To add title and/or footer pages to your messages, click on the Title & Footer Pages
section of the Transformation category. Here is an illustration of the options presented:

Figure 15-12. The Title and/or Footer page(s) attached to a generated report.

Title and footer *text* is supported for all types of distributed files. When you generate
HTML or PDF files, you also have the option of adding background images. You can
create the text pages from the console. This is described in the section “Working with
Title and Footer Page Text” on page 173 .
The following options refer to both Title and Footer page settings.
Text
Click this checkbox to enable the Title and/or Footer page options for this rule.
When you click this option, you can then use the *NEW option to create a new entry here,
or select an existing one from the list, as a starting point for the text to be added to this
grab rule.
Description
This is the description of the text section of your title and/or footer page.
Text Box
The text box is enabled when you select an entry. For instructions on how to create text
pages, as well as some design tips, review the section “Working with Title and Footer
Page Text” on page 173 , and particularly the section titled Designing the Pages.
From here you can further edit the text file for this particular grab rule.

- 263 -
Image
If you are generating a PDF or HTML document, you can click this checkbox to also
include a background image behind the title or footer text.
Network UNC Path
If you are generating PDF versions of your reports, Catapult requires this local path in
order to build the image into the PDF of the document. If you are generating HTML
documents, then Catapult needs to know where the image is in order to create the right
<img> tag attributes.
If you are using the same image for your title and footer pages as for your overlay, you
can copy the path from that option. Otherwise, click the browse button to locate the
image. Keep in mind that this path (and all paths in your grab rule like this one) must be
accessible to the poller at run time.

Using Replacement Characters in PC Paths and File

Names
Catapult cannot accurately validate the windows directory
name, so you must be careful using the replacement values
in the File Path. The following characters are also not
allowed in file names: / \ : * ? “ < > |
If found, Catapult automatically replaces these characters
with underscores.

Web URL
This option is required if you are distributing a report in HTML format and using a
background image. With HTML files the image cannot be embedded in the document
itself (as when you build a PDF file); rather, it must be retrieved from the web (or a
network drive, in the case of internal distribution) at the time the recipient opens the
document.
This file must be in a location that is available to your recipients, however they receive
your report (i.e. whether they are looking at online, or in an email).
You can type this value in here by hand, or if you are also using one of your overlay
images, you can copy the path from those options.

- 264 -
Creating Spreadsheets with Dat Extraction’s Batch Files
Data Extraction is capable of extracting and reformatting data from existing reports to
create spreadsheets, charts and graphs, as well as build files that can be exported to
many other PC applications such as Excel, Lotus 1-2-3, various database programs, etc.
Catapult allows you to leverage all these features in your grab rules via the use of the
Data Extraction’s batch file processing.
Below is an illustration of the Data Extraction’s category and the options available:

Figure 15-13. Data Extraction’s batch file processing options.

Step 1: Download a sample of the file to be processed.

Before you attempt to add batch file processing to your rule, you should use your grab
rule to simply download a copy of the file that you want to process with your batch file. To
do this, execute the following steps:
1. Create a grab rule, downloading the report as a PRN file, in *FILE format. Both
of these options are set from the Download category of your grab rule.
2. Also at the Download category, select the option to Save the report. Select a
valid folder on the machine where the Catapult Poller is installed. Save your
grab rule.
3. Verify that a copy of the report you are trying to download exists on the IBM i,
and if so, trigger an immediate poll.
4. Confirm that the file is downloaded to the correct folder.
If your file is saved correctly go to the next step. If not, review Chapter 4, and especially
the troubleshooting options at the end of that chapter, until the basic rule is working.
Step 2: Build a Data Extraction’s model of your report.

- 265 -
You may have done this already, but if not, now is the time to create a Data Extraction’s
model of your report. Define a model to extract the data you need, include those fields in
your table. Save the model on the PC where the Catapult Poller is running.
Step 3: Define your Batch File.
Now that you have a report and a model, you are ready to start working on your actual
batch file. A batch file (in most cases) opens a file using Data Extraction’s, applies a
model, then exports the data to a spreadsheet.
Batch files are PC executables, and can be defined using Notepad or any other text
editor. When you create a batch file, save the file you create with an extension of .bat.

Unlike the example illustrated below, you cannot have line

breaks in your script. Space on the page doesn’t allow this to
be shown as it should appear in your .bat file, but remember
not to include any breaks in your file.

Below is an example of a batch file (remember that your actual file should not have any
line breaks):
"c:\Program Files\Sample for Data Extraction\program\DataExt.exe"

"c:\Downloads\saleshistory.prn" "c:\Downloads\historysummary.mod"

"c:\Downloads\saleshistory.xls"

When executed, does the following:

1. Opens the file "c:\Downloads\saleshistory.prn".
2. Applies the Data Extraction's model file "c:\Downloads\historysummary.mod"
to that report, which builds a table of data from the report.
3. Finally, the last section "c:\Downloads\saleshistory.xls" tells Data Extraction’s
to convert the table to a Microsoft Excel® file called saleshistory.xls. Data
Extraction’s automatically ends once these tasks are complete, and returns
control to the .bat file so that other processes in the file can run.
If this works, use Notepad to create a file with an extension of .bat that contains that final
string, just as it is (no line breaks). For example, you could create the file here:
c:\Program Files\Sample for Data Extraction\program\saleshistory.bat

Then, in Windows Explorer, delete the existing Excel® spreadsheet and double-click the
.bat file to execute it. It should produce the same results as the last step, above.
If each of these steps worked, then your batch file should also work when executed from
Catapult. If any of the steps above didn’t perform as expected, your should check that
the required components for that step are all in place before trying to use the script in
Catapult.
Step 4: Add your Data Extraction’s batch file to your Catapult Grab Rule.
Go back to your grab rule and find the Data Extraction’s category in the Transformation
options. Click the ‘Enable Data Extraction’s Processing’ checkbox.

- 266 -
 For the Batch File Path type the complete name and path to the batch file you ended up
with when you finished Step 3.

Using Replacement Characters in PC Paths and File

Names
You need to be careful using the replacement values in a PC
Path, as Catapult cannot determine a valid windows
directory name. The following characters are also not
allowed in file names: / \ : * ? “ < > |
If any of these values are generated, Catapult replaces them
with underscores.

Step 5: Add the Input and Output file values to your Grab Rule.
The batch file you define has no access to the other options you define in your Catapult
grab rule. It will always look for the same input file name, and export it to the same
specified output file name. This means that Catapult needs to rename the file
downloaded from the IBM i to a constant name (which will be picked up by the batch file),
and in turn know what file name it will receive back from the batch file (the output file
name).
The ‘Input file’ value in your grab rule needs to exactly match the first file specified in your
batch file. If the second to last step includes the full text of the batch file, the Input file
name should be ‘c:\Downloads\saleshistory.prn’ and the Output file
‘c:\Downloads\saleshistory.xls’.

Data Extraction’s Batch File Processing Options Reference

Enable Data Extraction’s Processing
This check box allows you to turn Data Extraction’s processing on or off.
Batch File Path
This field must include the full path name of the batch file to be used in processing the
spool files selected by this grab rule.
The BAT file can be in any folder available to the Catapult Poller.
You can use the browse button to the right of the ‘Batch File Path’ field to present a
standard Windows ‘File Open’ dialog. The path of the batch file can be entered manually
on any machine running the Catapult Console; however it must correspond to a valid
path name on the Catapult PC Server.
Expected Input File
The Expected Input File is the name of the file to be processed by the batch file you
create.
In the Download category you may have specified a name for your downloaded report
that included replacement values. However, the batch file must always process a file with
the same name – this is the name that you specify in the Input File value. If you are using

- 267 -
replacement values in the download file name, enter a value here to which Catapult can
rename the downloaded file, so the batch program can execute correctly.
Expected Output File Name
The Output File is the name of the file that will receive the output from the Data
Extraction's batch file (or be created by it), and which will then be distributed. For
example, many people use batch files to convert IBM i reports to Excel® spreadsheets.
In this case, you would have a simple batch file that applies a Data Extraction’s model to
a report, and converts the generated table to XLS format. The output file will be the same
as the full qualified name of the XLS file in your batch file.

Output file names cannot include replacement values. If you

merely need to have unique names for your downloaded files,
you can check the option described below. If you need a
particular naming convention, you should compress your files
after processing. Compressed file names accept replacement
values. You may also convert your files to PDF if the output file
remains a TXT or PRN file; it won’t work for an Excel file.

Rename Output File to Unique Name After Processing

Check this option to cause Catapult to immediately rename the Output File to a unique
name. This allows the same script to be used for many spool files or poller runs without
the danger of overwriting previously created files.

- 268 -
Formtastic
Catapult will poll looking for a specified spool file. Once found it will run the merge
applying the defined parameters for the Formtastic MRGFRMSPL or MRGCHK2
command. Once the merge is complete the finished Formtastic file will be distributed
using Catapults existing options.
This will only work for Formtastic documents that include a FILE command.

Formtastic configuration:
1. Create a Form or Check document that includes the FILE cmd.
2. You must use the *SYSTEM File name. Index labels are not supported.
3. You must select the *Overwrite *YES from the FILE cmd.
4. Optional module, PDF Module, if installed needs to be disabled.
Please contact Technical Support for more information - support@freschesolutions.com
or 800-258-3399

- 269 -
Defining Compression Options
As the last transformation executed before distributing a file, you can select from these
file compression options:

Figure 15-14. Document compression options.

Compressing your files in standard ZIP format before distributing them reduces their
size. This means the file(s) will take less time to email and occupy less disk space if
archived. For your recipients, most current PC operating systems include options to
quickly and easily open compressed files.
No Compression
By default no compression is performed on the distributed file(s).
Compress Into a Simple Zip Archive
Check this option to compress your generated file into an archive with a .zip extension.
Once the box has been checked, information can be entered into the other fields.
Compress Into a Self-Extracting Executable
If you use this option your generated file will be of type .exe (an executable), rather than
.zip. Note that this will increase the size of your compressed file, so if you are
compressing small text files, you may not end up with a smaller file. You may still elect to
use this option for convenience.

This option was added to Catapult at time when email

servers were more forgiving and PC operating systems less
powerful. Currently you’ll find that most email servers and
anti-virus software packages are configured to reject .exe

- 270 -
 files out of hand, and most recent PC operating systems can
also open zip files without additional software. So this option
is less useful than it once was, and we don’t recommend
using it in new rules.

Compress Into a Self-Extracting Executable and Include an Autorun

Program
Use this option to create an association between the zip file that you send out and an
additional program that you include inside it (using the options below).
Compressed File Name
This is the name of the file into which the spool files received will be compressed, and the
file that will be emailed to the intended recipient(s). You must use an extension of .zip on
this file name, unless this is a self-extracting compressed file, in which case you need to
use .exe.
As illustrated above, you can include replacement values in the zip file name. If you are
compressing report split sections, you need to include a unique value in the name, such
as the key value. Replacement values are described in the section “Target File Name”
on page 240.

Remember that here and most places where you can insert text in
your grab rules you can right-click to insert any of the supported
replacement values!

Password & Confirmation

Enter a password if you want Catapult to encrypt your compressed file. If you enter a
password here the recipient of the file will be prompted for it before being allowed to
extract the .zip file.

Passwords and Replacement Values

Password fields in Catapult grab rules support the use of
replacement values. You can use any valid replacement value
(including extracted data values such as &CustName or
&OrdNbr, additional data values from distribution lists, external
data values such as &B0 - &B9) to customize the password
generated for a file.

Autorun Program Path

If you are including an additional file within your zip file, select it here.
As noted in the warning above, we now live in a less trusting world with regards to email
and executables, and it isn’t that likely that you’ll find that many of your recipient’s
actually get these emails.

- 271 -
 - Report Distribution

CHAPTER 16

Chapter 16 - Report Distribution

Ultimately, Catapult is all about report distribution. The primary function of the software is
to find, grab and distribute reports from your IBM i or network drives. So whether or not
you choose to add any of the other bells and whistles supported by the software, you do
need to have a distribution method for every report.
Catapult supports these distribution methods for your entire report, individual split
sections, or both:
□ Email
□ Print
□ Fax
□ Nexus (Fresche Solutions Web portal product)
□ Archive
You can select just a single distribution method, or combine methods as required.
This chapter discusses each of these methods with their features and requirements.

Remember that in most places where you can insert text in your
grab rules you can right-click to insert any of the supported
replacement values! This includes fields like the email subject, etc.

- 272 -
Including Additional Files
Catapult allows you to attach additional files to each document immediately before
distribution. Attaching additional files is supported regardless of the final format of the
document you are distributing and does not affect the format of the document you are
actually grabbing from the IBM i or network. Because additional files are separate from
the main document you are processing, they are supported only for email, print and fax
distribution.
Here is an illustration of the Additional Files category:

Figure 16-1. Attaching additional files to your distributed reports and documents.

Adding Additional Files(s)

Click the Add button to locate the additional file(s) to include with each distributed
document. For example, you could attach a flyer of next month’s specials with this
month’s invoice, or updated product listings.
If you are zipping your output, the additional file(s) are included in the zip file. If you are
also emailing the additional files are not attached as separate documents as they are
already included in the zip file.
File Path
When you click the Add button Catapult presents a standard ‘Open File’ window from you
which can select an instance of the document you want to attach. When you select the
file, Catapult attempts to convert it to UNC notation, so that it can be successfully located
by the poller PC.

- 273 -
Changing the File Path and Using Replacement Values
Once you have selected a file to attach using the Add button, you can double-click the
document name in the list to either edit it or optionally include replacement values in the
name.
This means, for example, that you can set this up in conjunction with your parse/split
operations to attach a different document for each customer based on key value (&k)
extracted from the report. Right-click anywhere in the field and select the Insert
Replacement Value to select from a list of valid values.

Using Replacement Characters in PC Paths and File

Names
You need to be careful using the replacement values in a PC
Path, as Catapult cannot determine a valid windows
directory name. The following characters are also not
allowed in file names: / \ : * ? “ < > |
If any of these values are generated, Catapult replaces them
with underscores.

In cases where an email may include multiple spool files, the attached file is included only
once. However, if you use generic or replacement values in the file name specified
above, you may attach multiple files; for example, the files "Dept 001 disclaimer.txt" and
"Dept 002 disclaimer.txt" could be both attached using the string "Dept ???
disclaimer.txt" in your File name.
Another example of this might be if you had some additional files for a special sales
promotion, by month. You could name the files c:\sales\jan\leaflet1.pdf,
c:\sales\jan\leaflet2.pdf, and c:\sales\jan\leaflet3.pdf, and then, for the file path, specify
the file to include as c:\sales\jan\leaflet*.pdf to include all of the leaflets.
Document Location for Printing and Faxing
The last option shown in Figure 16-1 allows you to select whether to append the selected
document to the beginning or end of reports that you print or fax.

- 274 -
Emailing your Report(s)
Catapult initially came into existence as a solution for automatically emailing IBM i spool
files, and this continues to be one of the most frequently used features. Here is an
illustration of the grab rule email distribution options:

Figure 16-2. Email distribution options.

This category consolidates base and split document emailing in two tabs of almost
identical options. You can only use the split document emailing if you have already set up
your grab rule to split the report (in the Document Splitting category).
The sections below describe the options common to both tabs (base and split document
emailing).
Enable Base/Split Document Emailing
Click on the Enable Base (or Split) Document Emailing checkbox to distribute your files
by email.

Email Address Options

For each report or report section you distribute with Catapult you can specify Target,
From, CC and BCC addresses. The options are described below.
User Defined Address
Use this option if the report(s) processed by this grab rule will always be sent (target
address, CC or BCC) to the same individual. When you select this option, Catapult

- 275 -
prompts you for the address, as shown here:

Figure 16-3. Entering hard-coded target, return, CC and BCC email addresses.

In the illustration above we have selected the ‘User Defined’ option for all four fields, and
entered single email addresses in each.
Using Multiple Addresses
You can enter multiple semi-colon delimited addresses (up to a maximum of 256
characters).
Incorporating Replacement Values
The email address value field supports the use of replacement values (i.e.
&D@finklebert.co.uk or &U@finklebert.co.uk). Using replacement values means that
you can set up a grab rule where any report generated by a specific user will be
processed and emailed to themselves, without having to have a separate grab rule for
each person running the report. Replacement values are also supported in email
addresses in group entries.
Adding Names to Emails
Many modern email clients only display an addressee’s name rather than their full email
address. For these clients you can format your user defined email addresses as:
John Doe <john.doe@domain.com>

The name needs to be at the front, followed by the address in between < and > brackets.
You can also use replacement values for any and all of these building blocks (e.g. the
names or email addresses).
Using the Poller Default for the Return Address
The Email Server options of the Catapult Poller configuration includes a default From
name and address that you can default to in your rules. Select Poller Default for the

- 276 -
Return Address to use this.
Getting Email Address(es) from a Group
You can use a group for your target, return, CC or BCC addresses in the following
scenarios:
□ To send your report(s) to more than one person.
□ If the target email address isn’t found in the report itself, and you need to use an
extracted value (the Keyed by field) from your report to identify the recipient.
When you have a report that needs to go to just three or four recipients, the choice of
using a group vs. just typing the addresses in the rule is a toss-up. Groups are easier to
identify and change, and you can reuse them. However, you don’t want to end up with
too many groups either.
When you use a Group, the grab rule editor prompts you to choose the group and key
value, as shown here:

Figure 16-4. Getting your email address(es) from a group.

In the illustration above you can see that we have selected the Group option, and already
chosen the group named InvoiceDis. We are now about to select the extended value
&X1 as the key value to identify the appropriate group entry.
If you just want to send the report to everyone in the group, select *ALL for the Keyed by
value.
Using groups for report distribution is an important Catapult feature; please review the
section “Using Groups with Report Distribution and Splitting” on page 283 below for a
detailed description of this feature.
Use an Extracted Value
If the email address of the report recipient is in the body of the report, you can define an
extracted value that includes the address, and select it here.
In this illustration, we are about to select a value:

- 277 -
 Figure 16-5. Using an extracted value for the target email address.

In the illustration above we have followed these steps (from top to bottom):
1. First we selected the Extracted Value button.
2. Then we clicked the button to browse for a value.
3. In the list of extracted values defined for our report, we clicked the one named
‘Email’.
4. Finally, we are about to click the Select button to pass this value back to our
report.
Your grab rule will show the replacement value &X1, which corresponds to the field
shown in the Extracted Data Values window.

You can extract multiple addresses from a report for a single

section by just separating the addresses on your report with
semi-colons, up to the length of a full report line.

Email Subject
Your email subject can be user-defined (and optionally include some replacement
values, including extracted values), or an extracted value.
User Defined
Type a text string to use as the subject for your email(s). This value can also include
replacement values, such as &k (the key value for the current split section) or extracted
values, such as &CustName, &X1 or &OrdNbr.

- 278 -
 Extracted Values
If your report contains a text string that matches your intended email subject, you can
define and use an extracted data value here.

Using User Defined Subjects with Values from Report Text

You can set the subject for your email by combining extracted data
values with text strings. To do this, just include the extracted data
value replacement token (&CustName, &X1, &OrdNbr, etc.) in the
subject line.
This means that you could break a purchase order report by
customer number and extract a value from the report that is the
invoice number so that the subject would be 'Invoice # xxxx'. To do
this, you would set the subject as 'Invoice # &X1', and retrieve the
invoice number from the report.

General Email Options

Click the General Options tab of your email distribution options to work with the options
shown below:

Figure 16-6. Email Attachment and Status/Receipt options.

Distributing the Document as an Attachment or In Email Body

When you distribute a report in .txt, .prn or .html format, you include it in the email body
directly or as an attachment. If you are converting your report to any of the other
supported formats, it is always distributed as an attachment.

- 279 -
Text Link
In addition, if you are saving the generated files to a network or web server directory, you
can chose to include a link to the file in your email, and format the link in the email as
either text or HTML.

This option allows you to specify the name/description, included in the email body, for the
attached file. This value supports all the file name replacement values described in the
section “Target File Name” on page 240 .

If you are distributing a file as an attachment AND you have

your poller set up to include a list of attachments in the body
of the email, it’ll either use what you have in the Text field, or
use the file name if you haven’t included anything.
If you are distributing a document by archiving it and
providing a URL in the email, the URL is the URL and the
Text field is either the visual part of the link, or if you choose
a text link it’s a label beside the URL.

Link URL
This field is enabled if you are distributing your report as a an HTML link. Enter the URL at
which the user can find the report. Note that the actual report name is appended to the
web path. This option supports all the file name replacement values described in the
section “Target File Name” on page 240 .
Link Type
There are two link types supported:
□ Text. This means that the link is included as text in your document, but to use it,
you would need to copy and paste it into your browser.
□ HTML. Use this option to make the link an active hyperlink, which the user can
click to open the document in a browser window.
You can use HTML link in document formats that support them (.pdf, .html), and for other
document types you should use Text.
Email Attachment Control
There are three options available for controlling how attached files should be handled:
□ Use poller default. Uses the value specified in the poller configuration.
□ Combine attachments for this report. Sends all the portions of this report
destined to the same user as a single attached file.
□ Send individual attachments for this report. Attaches each individual section
destined to this user as a separate file.
Select one of these options. As a general rule, combining attachments into one email
makes sending the email faster and uses less email server resources. However, if you
have reports where the title of the email distributed is dependant on the name of the

- 280 -
 attached report, you need to send them individually. Otherwise the email title will reflect
only the contents of the first attached file.
For example, if you have a report that is being split into 10 sections, each going to the
same person, you can use this option to control whether they will get 10 email, or a single
email with 10 attachments.
Request Read Receipt
Use this option cause your recipient’s email client to present an annoying box that
informs them that the sender has requested confirmation that they have received the
email.

This option doesn’t make the delivery guaranteed, nor does it

guarantee that the recipient will read the email - they can
simply refuse to acknowledge. Also not all email clients
support this option. In addition, certain firewalls block this,
particularly the firewall included with Windows XP (the Internet
Connection Firewall).

Priority
Use this option to set the email priority to Low, Normal or High. Setting an email to High
Priority while also requesting a read receipt is almost certain to earn you the enmity of
the most staid person out there.

Email Body Header and Footer Text

The third tab in your email options allows you to add header and/or footer text to the
generated message. Here is an illustration of a rule where we are using this option:

- 281 -
Figure 16-7. Enabling a Disclaimer footer for our emails.

Check the Enable box to use a header and/or footer. When you check the box, you can
also select an entry from the dropdown list, or select the special option *NEW to create a
new entry now.

When you select an existing header/footer entry, you can also

further edit it from the window above. Note that the changes
you make here will apply back to the original document.

For further details on email header and footer text, please review the section “Working
with Email Header/Footer Text” on page 171 .

- 282 -
Using Groups with Report Distribution and Splitting
A very powerful feature in Catapult is the ability to use distribution groups for emailing,
printing and faxing. You can use groups when distributing both the base report and your
split sections, and the special characteristics of each are described here.

Using Distribution Groups

In their most elementary sense, Catapult groups exist so that you can easily distribute a
downloaded report to more than one destination (where the destination can be an email
address, printer or fax number). If this is all you want, then you just need to create a
group with entries for each recipient, and the appropriate field(s) filled in.
An additional feature of groups is that you can add key values to your group entries
which Catapult can then cross reference with key values extracted from your reports.
Using these cross references, Catapult can find the intended destination for a report
section in the distribution list using any type of unique value found in your report. This
feature is useful in cases where the address information of the recipient doesn’t appear
in each split section of a report, or is not in the report at all.
As an example of this, suppose your sales analysis package creates a sales summary by
department and you want to send each department head their portion of the report. Their
email address does not appear on the report. In your rule you can create an extracted
data value over the department number, and then reference that extracted value as your
key for accessing the group. Catapult then sends the report or report portion to the
correct addresses defined in the group.
Catapult groups are described in detail in Chapter 10, Working with Catapult Distribution
Groups. The sections below include explanations of the features that specifically relate to
report splitting. In the examples used below, we refer to email as our distribution method,
but the explanations apply equally to printing or faxing.
Using a Group for Report Distribution
To use a group for report distribution, select that option in your grab rule definition:

Figure 16-8. Getting your email address(es) from a group.

In the illustration above you can see that we have selected the Group option, and already
chosen the group named InvoiceDis.

- 283 -
 When you click the Browse button to select a group, you can
also create and work with groups and group entries.

We are now about to select the extended value &X1 as the key value to identify the
appropriate group entry.
To send the report to everyone in the group, select *ALL for the Keyed by value. In this
case Catapult won’t attempt to use a key value to specifically identify particular
individuals in a group as the recipients. Using key values is described next.
Considerations when Using Groups for Distributing Split Sections
One option that isn’t identical for base and split section distribution is the Group option.
For split section, it looks like this:

Figure 16-9. Selecting a group for split section distribution.

With split rules, both the group and key value are specified in your document splitting
segment options, and just referenced here.

Adding Key Values to Group Entries

As mentioned above, the simplest usage of distribution groups is as a method to send a
report or reports to multiple recipients. For this, your distribution group entries do not
need to include cross reference key values.
However, if you are trying to use report data to identify and use specific group entries,
these need to include at least one (and optionally, several) key values.
To edit the entries in a group, right click on the group, and select the option to edit the
address list. Then double-click on an entry to change it. Here is an illustration of the
window presented:

- 284 -
Figure 16-10. A group entry, showing three key values and three additional values.

When you are using an group entry for distribution by email, the two critical values are
the email address and the associated key value. The key value here must correspond to
the value contained in the extracted data value you select as your key in the grab rule
email options (see Figure 16-8, where we are selecting &X1).
If you are faxing or printing, you must also specify a fax number or printer.
Group entries also support the special value "*ALL" (in quotes, and must be in all caps)
for the key value. This means that a particular person can get all split sections emailed,
without having to set up specific keys. It also means you could do something like have all
the split sections printed to a main printer, then have specific keys printed to specific
printers.
Sending Multiple Report Sections to a Single Email, Fax or Printer
There are two ways to use groups to send more than one section of a report to the same
email address, fax or printer:
□ By specifying multiple key values in the group entry.
□ By creating multiple entries in a group for the same person.
The first way is generally the easiest. For example, if a sales representative was
responsible for three different areas, and the area ID is a two position field on the report,
the key value for their distribution group entry could be (entries are semi-colon delimited
with no spaces):
“  1”;“  2”;“  3”
An advantage to doing it this way is that if a report does in fact have more than one
section for that recipient, they can be grouped together into a single email before being
sent off. You can set the default for this functionality in the Catapult Poller Configuration;

- 285 -
it’s described in the section “Attachment Options” on page 352 , and you can also
override how this is handled in your rule.
The second way to send multiple report sections to a single person is by just defining
more than one entry for that person in your group, with each entry having a different,
unique key value.
Using the Same Group for Different Reports
In the section above we showed you how to add multiple key values to a group entry. A
useful ramification of this feature is that it means you can also share groups between
reports that have different key values. For example, if you had some reports that were
keyed by the sales area, and others that instead included the salesman ID, you could
create an address entry for that individual that included the following as they key values:
1; 2; 3; JMALLONEY
When Catapult processes any report that includes any of these keys, it scans the group
for any matching key value (ignoring any invalid ones), and sends the section to the
person whose set of key values included a match.
You can also use a group to send reports by different means. For example, you might
have a report that included the email address in the report body, and which you are using
to distribute each section. However, if you also wanted to print or fax some or all of the
sections, you could add the recipients email address to the key values, and use that
same group for printing or faxing. So your key values for that person could look like this:
1; 2; 3; JMALLONEY; james.malloney@finklebert.co.uk
The email address on the report would then be cross-referenced with the group entry, to
extract a printer or fax number.
Sending One Report Section to Multiple Recipients by Email or Fax
If you have a report split section that you need to send to multiple recipients by email or
fax, type the additional email addresses or fax numbers into the group entry. Each entry
should be semi-colon delimited (no spaces). You can use up to 256 characters. An
example of this might be if someone had an company email address as well as one they
used while they were on the road or at home.
Another more effective way to do this is to repeat the same key value in more than one
group entry. For example, if you have a report that you want to send to both your
salesperson and their direct supervisor, you can include the key value for that sales area
in both their mail group entries.
Sending all the Split Sections to the Same Email(s)
Finally, if you are splitting a report and need to send all the split sections to the same
person, just select the User Defined address option in your rule.
If the email address for a specific section is not found on the report, the segment can be
delivered to an administrator email address or simply dropped. See the section titled
“Unassigned Split Segments” on page 222  for further information.

- 286 -
Formatting Documents for Printing and Faxing
When a report that you have downloaded (and potentially converted to a different
format) with Catapult is printed, the printing is handled by the windows default application
for the file type you have selected. For instance, .txt files will most likely be handled by
Notepad, .pdf will probably be handled by the Adobe Reader® (or the PDF reader you
have installed), .rtf is normally handled by Microsoft Word®, and so on.

Printing Plain Text Documents

If you are printing or faxing using a .txt document (and Notepad is your default
application for printing .txt files), you will get better results by clearing the header and
footer entries in the Page Setup dialog of Notepad. Otherwise, the first line printed will
(typically) be the file name, and the last line will (typically) be the page number.

Printing PDF and RTF Documents

Because of the very limited formatting capabilities of plain text documents, we
recommend that if you intend to print a downloaded report you also use the File Type
option from the Download tab to convert your downloaded report to either PDF or RTF
format. Catapult provides several options for customizing the appearance of PDF and
RTF documents. If you don’t choose one of these formats, you will have little control over
the final appearance of the downloaded.
If you intend to create grab rules to convert spool files to RTF and PDF formats and then
be printed, you need to ensure that the appropriate supporting software (the Adobe or
Foxit PDF readers, Microsoft Word® for RTF) is installed on the Catapult Poller PC. For
further information, review the section “Step 8: Install Additional Applications on the
Poller PC” on page 57 .

You should be aware that a number of customers have

reported erratic behavior when using Adobe Acrobat or the
Acrobat Reader for printing documents. Under some
circumstances, these applications will not exit properly after
a print operation, which will cause Catapult to report a
printing timeout. When faxing, this same behavior will result
in your first report or report section being faxed correctly,
however, because Acrobat doesn’t close, no other
documents will be faxed. So if you experience any problems
while using PDF as your document format for printing or
faxing, you should use RTF instead.

The options available for formatting reports for PDF or RTF are described in Chapter 15,
Report Transformation Options.

- 287 -
Printing Downloaded Reports
Catapult can print your reports instead of, or in addition to, using other distribution
methods. For example, you could distribute your sales figures by email to the sales
manager and also print them off for archival purposes. Or by taking advantage of the
report parsing features, you could email portions of sales reports to people who work off
site while printing off sections for those working out of your Head Office.

Important Printing Considerations

There are a number of considerations that need to be taken into account before printing
documents with Catapult:
□ You need to ensure your Catapult Poller PC has a default application defined for
any file types you decide to print, i.e. the Adobe or Foxit Reader for PDF, or
Microsoft Word® for RTF.
□ If you have not installed a word processor on that machine, it’s possible that
WordPad may be the default application for RTF. WordPad has a number of
limitations; one of these is that it does not correctly interpret orientation settings
in RTF documents (so documents set to print in Landscape would still be printed
in Portrait) nor include overlays.
□ HTML is not recommended for printing due to the limited formatting options
available. Also, many browser versions always prompt for a printer when starting
to print, which makes automation of the printing impossible.
□ Certain versions of Adobe Reader and Adobe Acrobat do not close correctly
after printing, causing Catapult to issue ‘printer timed out’ warning messages.
This can be addressed by generating RTF documents, and printing them via
Microsoft Word®. We have also more recently begun using Foxit’s Reader 3 as
an alternative to Adobe’s Reader, with good success.
The next sections describe the windows presented for setting your print options.

Printing Options
To use Catapult to print reports, click the Print category, shown here:

- 288 -
Figure 16-11. Report printing options.

The default setting is None - no printer is selected, no documents are printed.

Print to User Defined Printer
When you select this option you can choose the *DEFAULT printer to use the printer
established as the default in poller configuration. This option is discussed in the section
“Define a Default Printer” on page 53 . You can also click on the arrow on the right of the
box to show a list of printers currently available to the Catapult Poller.
If you don’t see the printer that you need in the list because it hasn’t been added to the
poller PC, you need to do the following:
1. Save your rule and close the console.
2. Go to the poller PC and open the poller configuration.
3. If the poller configuration is set to automatically update the printer list, it will do
that now. Otherwise go to the print tab and click the button.
4. After the list is loaded and you’ve confirmed the printer you want is in the list,
click the update button.
5. Restart the poller.
6. Re-launch the console and go back into your rule.
7. Choose the printer you want.
Finally, go back into your grab rule and select the required printer.

- 289 -
 Print to Group/Key Value
If you need to print the report or its split sections to different locations, select a group as
your printer source. Use the browse button to locate the group you need.
If you are printing only selected sections based on an extracted key value, then select
the extracted key value that you want Catapult to use to match with the key values in your
distribution group entries.
Printing to an Extracted Value
If your report body includes the printer path, you can create an extracted data value over
that section and reference it here. If you use this option, your report would have to
include the exact equivalent of what you would normally see here in your grab rule when
you selected the ‘User Defined’ printer option. This is typically the UNC name for the
printer as it would look on the Poller PC.

This is important because when you install a network printer

on a specific PC it doesn’t always have the same value, and
the value from the document you are extracting the printer
from would need to match exactly what the Poller PC sees
the printer as. For example, a printer may be installed as
“Dell Laser Printer 1710” on one machine, but named
something else on another PC.

Copies
Select the number of copies to print. If you are printing to a group, each group member
will have as many copies printed as you specify here.

Printing Split Sections

As with emailing, base report and split section printing is handled independently. This
means that you can email split sections while printing the base report, or vice versa. You
can also set up the keys in your report so that some sections are distributed by email,
some by fax, and some sent to printers, and using the special value *NONE in the group
entries for section that shouldn’t be printed.
If you print your split section to a group, the group and group key values are taken from
the Document Splitting category of your grab rule.

- 290 -
Faxing Documents
As with printing, you can use faxing in conjunction with other actions or as the sole
distribution method for a report. So if your customers are accustomed to receiving
periodic fax updates on your products you can continue to distribute that newsletter by
fax, and as more of them move to using email, you can use the same grab rule to email
them the flyer or price list by updating the information in their group entry.
The actual faxing process is handled by the operating system on the Catapult Poller PC
using the Faxing Console built into Windows Operating Systems as of Windows 2000.
We have included sample instructions for enabling faxing on your poller PC later in this
chapter.
Here is an illustration of the base document faxing options:

Figure 16-12. Grab rule faxing options.

The default action is None, to not attempt to fax the report.

Fax To a User Defined Number
If every report will go to a single fax number, select the User Defined option and type the
fax number. Do not include spaces or parenthesis, though you can use commas to add
pauses (i.e. after an initial ‘9’ to get an outside line).
Fax to a Group/Key Value
Select this option to distribute your report to multiple recipients using a group. Use the
browse button to locate the group you need.

- 291 -
 If you are faxing only certain reports or report sections based on an extracted key value,
select the extracted key value that Catapult should use to match with the key values in
your distribution group entries.
Faxing to an Extracted Value
If your report body includes a fax number you can create an extracted data value over
that section and reference it here.

Faxing Split Sections

Base report and split section faxing is handled independently. This means that you can
fax split sections to your customers, while emailing yourself the whole report, or vice
versa. You can also set up the keys in your report so that some sections are distributed
by email, some printed and others faxed.
If you fax your split section to a group, the group and group key values are taken from the
Document Splitting category of your grab rule.

- 292 -
Adding Fax Services to the Poller PC
If you intend to take advantage of Catapult’s ability to distribute reports by fax you need
to first ensure that faxing services have been added and configured on the PC that the
Catapult Poller is installed on.

The actual faxing process is handled by the operating system

on the Catapult Poller PC using the Faxing Console built into
Windows Operating Systems as of Windows 2000. If you
intend to use Catapult faxing, you need to install the poller on
a system running Windows 2000 or later.

Here are the steps that you need to go through to add fax services to your Windows XP
system:
1. Go to the Control Panel and select the Add or Remove programs option.
2. Select the option to Add/Remove Windows components:

Figure 16-13. Adding fax services to your PC.

3. In the window shown above, select Fax Services (indicated by the arrow) and
press Next.
4. If prompted, insert your Windows CD.
These steps complete the process of installing the fax services themselves.

Configuring the Fax Services

After you have successfully added the fax services to your PC you can use the
instructions below to configure them. If you are already using the poller PC for faxing
from other applications, these steps may be unnecessary.

- 293 -
In the example below, the PC did not previously have a modem installed or configured,
so depending on the current hardware configuration of your poller PC, you may not get
all the screens shown here.
1. From the Start menu, open Programs/Accessories/Communication/Fax/Fax
Console. If you haven’t used your modem before, Windows may initially
present the window below:

Figure 16-14. Configuring the faxing location.

In the window above, fill in your location information and press OK.
2. At the dialing rules (below), click OK.

Figure 16-15. Setting the dialing rules.

3. After you click OK above, the Fax Configuration Wizard opens automatically.
Click the Next button to continue.

- 294 -
 Figure 16-16. Beginning the fax configuration.

4. At the window below fill in your sender information. While Catapult doesn’t use
this information, it’s a good idea to fill this in, in case you later use the fax for
other reasons. Click Next when you are finished.

Figure 16-17. Defining your configuration.

5. Select the fax modem that you wish to use:

- 295 -
 Figure 16-18. Choose the fax to use.

6. Next, the configuration wizard asks for the Transmitting Subscriber

Identification. Enter a name for your company or faxing PC. Click Next to
continue, and finish.

Figure 16-19. Adding the subscriber identification.

In the United States it is illegal to send a fax that does not

have the sender’s name and fax number in the top margin.
The TSID is used for this purpose.

7. The last window presented displays is entitled ‘Completing the Fax

Configuration Wizard’, and displays a summary of your configuration settings.
Click Finish to conclude your fax configuration.

- 296 -
To test the faxing configuration, try setting up a very simple grab rule faxing a single page
report to your own machine.

- 297 -
Distributing Reports to Nexus Portal
In the tutorial section of this guide, Chapter 4 walks you through the process of creating a
basic rule that exports a downloaded spool file to the Nexus ECM. You can combine
Catapult and Nexus features to create sophisticated distribution rules that automate the
process of moving Catapult-generated documents to the Nexus ECM, where you can
make them available to selected users in a secure environment.
This chapter describes the grab rule options you will use to set up the links between
Catapult and the Nexus ECM.
For a detailed overview of what Nexus is and what it can do for you, please visit the
Nexus page at https://www.bcdsoftware.com/iseries400solutions/nexusportal/

Setting the Grab Rule Nexus Options

Here is an illustration of the Nexus distribution options:

Figure 16-20. Nexus distribution options in your grab rule.

Enable Nexus Processing for Base/Split Document(s)

The interface again includes two tabs from which you can set your Nexus distribution
options for both your base document and split sections.
Check this option to enable ECM processing for the report(s) you are processing with
this rule.

- 298 -
Document Description
Type the document description you want to show in the Nexus ECM. This string supports
replacement values.
Library
Because you can install multiple, independent copies of Nexus on your IBM i, you need
to select the Nexus product library to work with. The default value is XL_NEXUS. The set
of sites available in the next option depends on the library selected.
Site
This drop down displays a list of sites configured within the Nexus instance specified in
the previous option.
Data Search Values
This section shows a list of the extracted data values you have defined in your rule, with a
checkbox you can use to indicate which of these should also be used as data search
values in Nexus.
Data search values allow you to have Catapult look into the document contents itself to
determine whether the document is a match for your Nexus selection criteria.
In the illustration above you can see that we have checked a single value, the Account
Number.
Data Value Name
This is a data value name defined from within Nexus. This data value name allows you to
group 'like' data values that might have different names/titles.
For example, it allows you to search on 'department' from within the ECM and know that
you are picking up data values that were found using 'dpt', 'dept', 'department', etc. It
means that your search results are going to be more complete, since you don't need to
know the details about how the report is formatted, only that it contains 'department
related' data.
The values available to you here are derived from the key values you define in Nexus (in
the same Nexus site that you selected on the Archive tab). Within Catapult you need to
match the Nexus key values with actual data elements in your report.
Entry
Now you can see the entry listed on the left, W0. This is a unique sequence number that
you can then make part of your file name (on the archive tab). By doing this, every
section of this report could include a unique name, based on the extracted key value,
and be associated with it’s own distribution rule in Nexus.
Up to 10 values can be extracted from a report and used in file names, descriptions, etc.
The variable names are &W0 - &W9, and correspond with the Nexus Search Criteria
number. &W0 will contain the first value retrieved by the first Nexus Search criteria, and
so on.
These can be used anywhere replacement values are supported in your grab rules.

- 299 -
How the Search is Processed
When the Catapult Poller runs, if the ‘Enable Nexus Processing’ checkbox is checked,
the data values (if any) are parsed out of the report. These values, in addition to the
description you supplied, and standard spool file attributes are all submitted to the Nexus
ECM.
The standard spool file attributes submitted are: OUTQ, OUTQLIB, SPLFILE (spool file name),
JOBNAME, FORMTYPE, JOBUSER, USRDTA, SPLFDATE, SPLFTIME, PAGES, SPLNBR (spool file number within
the job number) and GRABNBR (grab rule that caused the document to be submitted).
When the spool file is submitted to Nexus, the ECM API parses the Nexus Enterprise
Content Manager Distribution rules to attempt to assign authorities based on the
attributes of the spool file and the data values extracted from the report.

- 300 -
Archiving Downloaded Documents
The final distribution method Catapult supports is archiving, which allows you to specify a
network location where the processed spool file can be saved.
Here is an illustration of this section of the grab rule:

Figure 16-21. Enabling the grab rule archive options.

Enable Archiving for Base/Split Document(s)

Click this option to enable the Server Path input box, where you can specify a location
anywhere in your network to which you want to save a copy of the reports downloaded by
this rule.
Server Path
If you type in a path, it must be valid for the system on which the Catapult Poller is
installed. The path can be entered on any other system where the console is installed,
but it must correspond to a valid path for the poller, not the system on which the grab rule
is being maintained. The best option is to use the Browse (...) button to retrieve the UNC
name of the directory.
When you click on the button browse your network drives, you can select a target folder
by double clicking on it. Below is an illustration of the window presented:

- 301 -
Figure 16-22. Browsing for a folder to which Catapult will archive the documents.

The directory name returned by the Browse option is UNC format. It is not specific to how
a shared directory was defined on a particular console’s PC.

Using Replacement Characters in PC Paths and File

Names
You need to be careful using the replacement values in the
Folder Path, as Catapult cannot determine a valid windows
directory name. If a directory doesn’t exist, the Catapult
Poller will attempt to create it, regardless of whether the
name you have built is a valid PC directory name.
The following characters are also not allowed in file names: /
\ : * ? “ < > |
If any of these values are generated, Catapult replaces them
with underscores.

If File Already Exists...

These options are useful if you are using Catapult to archive many spool files with the
same name. Using these options you have the choice of overwriting older versions,
assigning unique sequence numbers to each downloaded file, or, if you are creating
unformatted .txt files, of appending content to an existing file.
As Catapult is saving each downloaded file to the selected directory it checks to see if
there is already a file there of the same name. If a file is found and you have chosen the
first option (overwrite existing files) then the existing file is replaced. If you select the
option to append a unique sequence number it appends a new, unique sequence
number to the new file.
Archive All Split Segments
Choose this option to save every split section created.

- 302 -
Archive Distributed Segments
If this grab rule is processing a report that you are also distributing by some other means
(and not just saving), you can select this option to only save the sections that were
emailed, printed or faxed. This means that any split sections for which a valid email
address, fax number or printer were not found, either in the report body or the selected
group, would not be saved.
Archive Split Segments Based on Group
You can also save split segments based on a particular group’s distribution list.
The group you use here doesn’t have to include any of the distribution information
normally included in group entries, such as the person’s name, email or fax number. If
this group is used purely to determine which sections to save, all you need to do is
include key values for each group entry. And if you don’t anticipate ever using this group
for anything other than that, you can even specify multiple key values (semi-colon
delimited, and enclosed in double quotes) in each entry.
The key value could be email addresses (if you are using an email address as the key
value to your split section), or any kind of unique key such as a customer number, item
number, etc.
Click on the Browse button to select an existing group. From the window presented, you
can also create a new group, if you don’t already have one for this rule.

- 303 -
 SECTION IV
Administrator Functions and
Configuration Options
In this Section:
Chapter 17 - Report Distribution and
Tracking Options
Chapter 18 - Controlling the Poller from IBM i
Jobs
Chapter 19 - Catapult PC Component
Configuration Options

- 304 -
 - Report Distribution and Tracking Options

CHAPTER 17

Chapter 17 - Report Distribution and Tracking Options

Catapult includes several tools to help you monitor the document distribution process,
from the moment a request is issued for a specific report to the time a history log is
written after the processing is complete. This chapter discusses the available tools,
including the server status window, the Catapult Launchpad tools, and the Error and
History lists.

- 305 -
The Console’s Poller Status Tab
From the Catapult Console you can access the Poller Status by opening the tab (usually
found on the right of the display). Here is an illustration:

Figure 17-1. The Poller Status tab, and informational window.

From this tab you can view a real time listing of the actions performed by the Catapult
Poller. If you have the Catapult Poller installed and running on your system, you can also
right-click the Catapult Launchpad icon to present the Poller Status, displaying this tab in
a standalone window.
The top area of the tab provides some information about the status of the various
controllers (Email, Print, Fax and Nexus). You will also find:
□ Various details related to the PC Server.
□ The time for the next scheduled polling cycle.
□ The time and date of the last time the poller cycle started and ended.
□ The number of rules currently being processed.
□ The number of outqueues processed.
□ The number of spool files evaluated, selected and rejected (for various reasons,
such as existing in the History list).
□ The number of network files evaluated, selected and rejected.
□ The number of requests processed or in error.
□ The number of history records purged.
This information is particularly useful if you find that your polling cycles are taking too
long or some spool files have not been successfully processed.

- 306 -
The bottom section shows what action has been (or is being) executed. When you first
launch the status window, it displays a historical list of the last 10 messages. After that,
the window is updated dynamically, and is reset each time you open the server status
window. The list of actions is cleared periodically (after 500 lines) to keep the size
manageable.

- 307 -
Browsing Pending Requests and Request Errors
From the Catapult Console you can browse the Request List by clicking on the tab along
the bottom of the window. Below is an illustration of the list presented:

Figure 17-2. Displaying the pending (or error) request entries.

This illustration includes a few errors related to the PDF generation engine, and no active
requests.
Filter
The Filter option above the list allows you to subset the list to display the different types of
pending requests. The different types are color-coded for quick recognition. The options
include:
List Contents Description
All Displays all the categories below.
Includes all reports that have been flagged for
Pending Only distribution, but not yet acted upon (cream
colored).
Includes reports that have been downloaded,
Email Pending zipped, formatted, etc. and are now submitted to
the email thread (sky blue).
Includes reports that have been downloaded,
Print Pending zipped, formatted, etc. and are now submitted to
the print thread.
Includes reports that have been downloaded,
Fax Pending
zipped, formatted, etc. and are now submitted to

- 308 -
List Contents Description
the fax thread (sky blue).
Includes reports for which all processing has been
completed. These records are removed from this
list at the beginning of the next polling cycle (they
Completed Only have already been added to the history list).
Completed entries provide you with an easy way to
review which reports were processed by the last
poller cycle (no color).
Errors Only Includes distribution errors (Yellow).

In addition deleted requests are displayed in the list until the next time you load it, and
are colored silver. Note that deactivated and reactivated requests are also color coded.
Editing Rules Being Processed
From the window above you can right-click any of the requests to edit the grab rule being
processed. This option is also available from the Edit menu. This option is especially
useful for requests created by the ZDSTSPLF and ZRUNRULE command, since the underlying
grab rules are hidden, and not accessible from the grab rule list.
Expand/Collapse Request Details
To enhance Catapult’s auditability, request records include details to track exactly what
steps of a distribution process have been completed. These records are updated on the
fly, as each step is completed.
Currently Catapult tracks where a spool file is saved, emailed, printed or faxed. The
details also include the spool file action, what (if anything) the user data was changed to,
what queue (if any) the spool file was moved to, and whether the grab rule was deleted
after use. Each record has a 'status' indicator which is 'error', 'complete' or 'warning'.
This means that if any step of the distribution process encounters a problem, you can
pinpoint what exactly has been done. You can also refresh the listing as the rule is
processed, to monitor each step.
Use the Expand/Collapse Details button to display or hide these details.
Exporting Request Entries
You can export your request entries to a file or email. If you want to print just a subset,
first highlight and select those that you need then click the Email Request List button.
Here is the Export window that pops up:

- 309 -
Figure 17-3. Exporting error and pending request entries.

In this example we haven’t selected a particular set of the entries, so the ‘Selected’
option is grayed out. You can choose to print an actual hard copy record of your
requests, or email the listing to a specified address, or both. Choose the methods you
want to use, then choose your printer and/or email address.
In order for the email option above to work, you need to have configured your Console’s
email settings (Tools/Configuration/Email). See the section “Email Options” on page 342 
for details.
Working with Pending Requests
To understand where the pending requests fit in the scheme of Catapult’s processing,
you need to understand a little about how Catapult works. When a polling cycle is
initiated, Catapult first runs through all your queues looking for spool files that match any
of your grab rule criteria that have not already been processed by that grab rule. As it
does this, it builds a 'request' list of spool files that need to be distributed. Once Catapult
has finished scanning all your selected queues, it returns to the request list to process
and distribute the selected files. The list shown in Figure 17-2 displays all these entries,
until their processing has been concluded and the records have been moved to the
history list.
By using the Request List window along with the History List, you can view and work with
your spool file distribution records during every step of the polling cycle. In particular, the
Request list is useful for checking which reports have been held up if there has been an
error in the poller. This is discussed in the next section.
An example of when you may want to work with the pending requests is if you mistakenly
create a grab rule with the wrong criteria (for example, a very broad selection, such as all
files in QPRINT, or with a name of QPJOBLOG). After the polling cycle starts, you may realize
what has happened, but by then Catapult has already selected several thousand files,
and is beginning to distribute them. You can interrupt this process by presenting the list
of pending requests, and deleting the entries from it. Note that this technique will result in
the generation of request errors for each deleted entry.

- 310 -
Another example of when you may want to view the pending requests file is if the
Catapult Poller is mistakenly ended or runs into an error part way through its cycle, and
you want to see what the status of a specific file is at that time.
Request Errors
One of the most important distribution tracking options is the ability to view a list of
download request errors. To view and work with this list, click on the Requests List button
in the console and select the Errors only filter. Error requests are shown in yellow.
When the Catapult Poller executes a polling cycle, as it finds qualifying spool files it adds
a record to the Request List. After it completes this step, it starts processing the
requests. At this point, if an error occurs during the distribution attempt, the Catapult
Poller sets an error flag on that request entry and sets the message field of the request to
describe the error that occurred.
The download request error listing above includes the error text along with a subset of
the grab rule information for each error. The number in the "Rule" column indicates the
grab rule used to select the spool file in question. This number corresponds to the "Nbr"
column in the grab rule list main window. The sequence number uniquely identifies each
Download Request.
Working with Download Request Errors
From the list shown in Figure 17-2 you can disable, delete or restart entries. Disabling a
request has the effect of pausing it, so that the processing on other requests can
continue while you trouble-shoot what the problem was with a particular entry. This is
something you would typically do when you have a misconfigured rule that has caused
the Catapult Poller to crash (and therefore, was the ‘Active’ request in the Pending
Requests entries), and you want to restart the poller again to let it continue processing
other requests without having to disable the rule that created the request that triggered
the crash.
When you delete or re-enable an entry, it causes the Catapult Poller to re-evaluate the
spool file that caused the error and attempt to process it on the next polling cycle.
Each of these options can also be accessed from the main menu and the popup menu.
You can perform multiple selections on this list, so any number of errors can be disabled,
deleted or reactivated in a single operation. To change multiple entries, use the standard
Windows method of pressing the Shift or Ctrl keys while clicking on items in the list.
During the Polling Cycle, when spool files are being evaluated and requests created, it
checks the request list to see if there is already a request pending
(error/disabled/pending) for that spool file and rule. This is to avoid the generation of the
same error each time the Catapult Poller is executed. The Catapult administrator is
responsible for the diagnosis and correction of such problems. This can be
accomplished by following these steps:
1. Use the Request List tool to determine the cause of the problem.
2. Remove the problem by correcting the definition of the grab rule.
3. Clear the error from the Request List.
Step 3 can be accomplished by either deleting the error records or reactivating them. If a
request generated an error, and you fix the grab rule to download the file correctly, you

- 311 -
should reactivate the error entry. If a request generates an error, and you decide to
delete the grab rule and not download the file, then you should delete the request and
Catapult will not attempt re-process the file.

Right-click and select ‘Edit Rule’ to go directly to the underlying

rule.

- 312 -
Browsing the History List of Successful Downloads
Use the History Listing to work with a historical list of distributed spool files. To see this list
click on the button in the toolbar, or select the Tools/History List option. As the list loads,
the number of entries is displayed in the status bar.

Figure 17-4. Displaying a few records from the console’s history list.

Each time a spool file is successfully distributed to the location(s) defined in the grab rule,
a corresponding entry is created in the History List. The next time the poller executes, it
compares existing spool files to those whose distribution is recorded in the history list to
ensure that a file isn’t sent multiple times. This means that by deleting entries from this
list you can cause Catapult to re-process a file. Multiple selections can be performed on
this list, so any number of entries can be deleted in a single operation. When you delete
an entry, it displays the word ‘Deleted’ in the list until the next time you reload the entries.
History records are deleted automatically when they have reached an age defined in the
Poll/Purge Time Settings window, described in the section “Advanced Poller
Configuration Options” on page 354 .
Expand/Collapse All History Entries
To enhance Catapult auditability, request records include details to track exactly what
steps of a distribution process have been completed. Currently Catapult tracks where a
spool file is saved, emailed, printed and/or faxed. Each record has a 'status' indicator
which is 'error', 'complete' or 'warning'. This means that if any step of the distribution
process encounters a problem, you can pinpoint what exactly has been done.
Use the Expand/Collapse Details button to display or hide these details.

- 313 -
Exporting History Entries
To print your history entries, click on the Print button. If you want to print just a subset,
first highlight and select those that you need. The print window presented is the same as
the one described in the section “Exporting Request Entries” on page 309.
Filter
The Filter option above the list allows you to subset the list to display history records from
today, the last week, the last month, or all the records in the file.

- 314 -
Triggering an Immediate Poll
Another useful option, particularly when you are working on setting up new rules, is the
ability to trigger an immediate poll cycle. You can execute this by clicking the button in the
toolbar or by selecting the Tools/Poll Immediately option. This option is also useful if you
have a long polling interval and you have just run a report that you want to distribute
immediately.

- 315 -
Establishing a New IBM i Connection
When the Catapult Console is first executed, it establishes a connection with the default
system as defined in the Exodus Communications Configuration tool. This connection
can be changed by choosing the File/Connect to System menu option, or by clicking on
the toolbar button of a PC, to present this window:

Figure 17-5. Catapult connection prompt.

The Connection drop down list shows a list of the servers that you have configured in
your Communications Configuration. You can click on the Communications... button in
the lower left to verify or update your connection settings. When you select a system to
connect to, you can key in your user ID and password (if they aren’t defaulted in), and
click OK or press Enter to establish a connection. If the connection fails, a message is
displayed and the dialog remains open so that a new system can be selected.
If the "Make Default" checkbox is selected, and a successful connection is made with the
system named in the text box, that system name is recorded as the default system for
the Catapult Console.

You do not need to check the ‘Make Default’ each time you
start up the console. It only needs to be checked if you want to
change which system shows up as the ‘Connect To’ system.

This is distinct from the TCP/IP default systems mentioned above. Once you set a default
system in this way, changes made to the TCP/IP defaults do not affect the console.

- 316 -
Using the Catapult Launchpad
You can use the Catapult Launchpad to load all the other components, as well as
monitor the poller status. Once started, the launchpad lurks quietly in the corner of your
screen:

Figure 17-6. The Catapult Launchpad, in your system tray.

Double-click the Catapult Launchpad to fire up the Catapult Console, or right-click the
icon to choose from the following options:

Figure 17-7. The Catapult Launchpad options.

You can configure the Launchpad to start up when you log in to your PC by selecting the
Load on startup option shown above.
The following options are also available:
□ View Poller Status. Select this option to display the Poller Status window, which
will include information similar to what you’d see in the Poller Status tab in the
Console.
□ Launch Console. Use this option to launch the Catapult Console. This is the
default option, also executed if you double-click the launchpad icon.
□ Manage Pollers. Select this option to manage the Catapult Poller(s).
□ Log and Configuration Files. Review any error log files.
□ Configuration. From here you can work with the configuration options for your
connections, the console and the poller.
□ Documentation. From here you can load the User Guide.
Select the Exit option to close the Launchpad.
The Catapult Poller options are only available if the poller is installed on your PC.

Catapult Launchpad Configuration Options

To configure the launchpad, right-click the icon and select Configuration/Launchpad.
These options are available:

- 317 -
Figure 17-8. Catapult launchpad configuration options.

Start Launchpad when Windows Starts

Select this option to have the Catapult Launchpad start automatically the next time you
start Windows. Because the launchpad is the easiest way to access many other Catapult
links, it’s useful to have it easily available.
Start Console when Launchpad is Opened
Check this option to automatically start the Catapult Console when the launchpad is
started.
In conjunction with the previous option, it will have the effect of launching both the
Launchpad and Console on startup.
Display Message when a Polling Instance Starts/Ends
When the launchpad is running, you can also have it display a message on your PC
when a Catapult Poller instance starts and/or ends.
Send an Email when a Polling Instance Starts/Ends
The Catapult Poller configuration (Email/Administration) allows you to notify the
administrator by email whenever a poller instance starts and/or ends. If you want to also
send an additional email to another address (normally your own) you can add that here.
This only works when the launchpad is running.
When you select one of these options Catapult enables the Email Address option.

- 318 -
 - Controlling the Poller from IBM i Jobs

CHAPTER 18

Chapter 18 - Controlling the Poller from IBM i Jobs

In addition to its PC-side tools, Catapult includes IBM i commands that allow you to
initiate spool file distribution directly from an IBM i program or command line. There are
three commands you can choose to distribute files:
□ ZDSTSPLF -
This is a stand-alone command that does not require that a grab rule
be defined. However, this command has comparatively limited options.
□ ZRUNRULE -This command allows you to specify the spool file selection criteria, as
well as override a few settings, but is dependent on a pre-existing grab rule for
most of the distribution criteria. ZRUNRULE allows you to take advantage of all the
grab rule features, including formatting, splitting, overlays and more.
□ ZRUNNETRUL - This command allows you to initiate the distribution of a network file
from the IBM i command line or CL program. As with the ZRUNRULE command, it
also requires that you have pre-existing grab rule specifying most of the
distribution criteria.
□ ZPOLLNOW -
Allows you to initiate a polling cycle from the server, which means that
you can run a report, and then ensure it is processed immediately, or
programmatically schedule when the poller needs to run.
□ ZPOLLEND -Immediately end the poller instance. If the poller is in the middle of a
polling cycle, it is ended when processing is complete.
You can execute any of these commands from an interactive session, or embed them in
a CL program to distribute spool files each time you run a report.
The sections below describe these commands and their parameters.

- 319 -
Using the ZDSTSPLF (Distribute Spool File) Command
Use the ZDSTSPLF command to distribute a specific spool file. The command includes
many of the basic options available when you define a grab rule, but not all of them. The
advantage of the ZDSTSPLF command is that it doesn’t require that you first create a grab
rule; its disadvantage is the limited set of options it allows you.

The ZDSTSPLF command triggers immediate processing to

occur. If the poller is already in the middle of a polling cycle, the
request is added to the list of pending requests.

If you need to take advantage of some of the more sophisticated grab rule features, you
should build a grab rule using the Catapult Console, set its status to Inactive, and then
use the ZRUNRULE command to execute it.
The options available when you use the ZDSTSPLF command include:
□ Send to a single email addresses.
□ Send to a group of email addresses.
□ Save as a PC file on the Catapult PC Server.
□ Send all pages or a range of pages.
□ Specify the PC format to which to convert the downloaded spool file.
□ Send in Print format (with embedded blank lines and page breaks) or File format
(with blank lines and page breaks removed).
□ Specify an email subject.
□ Run the spool file through a Data Extraction's batch file and email the resulting
output file.
□ Zip the file.
□ Encrypt the zipped file.
□ Set the status of the spool file to ‘Delete’, ‘Hold’, ‘Release’ or ‘Save after Printing’
after running the command.
□ Update the user data attribute of the spool file after running the command.
These are described in detail on the following pages.

ZDSTSPLF Parameter Reference

Parameter Attributes Description Valid Values
The name of the spool file whose
FILE 10 A Spooled file name.
contents are to be downloaded.
Job: 10 A
Name of the job that created the Qualified Job name or
JOB User: 10 A
spool file. *.
Nbr: 6,0 N
Number of the spooled file to Spooled file number,
SPLNBR 6,0 N
download within the job with the *ONLY or *LAST.

- 320 -
 same name.
Format of downloaded spool file
FORMAT 5A *RPT or *FILE.
contents.
Starting point of range of report to
STARTPAGE 5,0 N *ALL, Page Number.
distribute.
End point of range of report to
ENDPAGE 5,0 N Page Number.
distribute.
Name of PC file to create (up to 32 Valid PC file name, or
PCFILE 32 A
characters). *SPLF.
PCPATH 128 A Valid PC path name. Path name or blank.
Valid email address to mail report
EMAILADDR 256 A Email address.
to.
EMGROUP 10 A Name of email group. Email group.
SUBJECT 80 A Subject for email message. Text.
INCLUDE 4A Include report in email body. *NO, *YES.
CRTUNIQ 4A Create a unique PC File Name. *NO, *YES.
Path and name of a file to run with
Data Extraction's batch file feature Valid path and file
AUTOSCRIPT 128 A
(called ‘autoscript’ in earlier name, *NONE
releases).
Value to rename downloaded file to Valid PC file name,
EZINFILE 128 A
for Data Extraction’s batch file. *NONE
Valid PC file name,
EZOUTFILE 128 A Name of output file from batch file.
*NONE
Valid PC file name,
ZIPFILE 32 A Zipped file name.
*NONE
ZIPPWD 10 A Password to encrypt zipped file. Password, *NONE
*NONE, *DELETE,
Action to perform on IBM i spool file
ACTION 10 A *HOLD, *SAVE,
after distribution.
*RELEASE
Value to update User Data attribute
USRDTAVAL 10 A Value, *NONE
of spool file with.
Set the timeout value for how long
the server program will wait for a
TIMEOUT 5,0 N completion message to be returned Value in seconds
by the PC for the spool file
distribution.
Select where to send messages to
NOTIFY 7A *SYSOPR, *PGM
in case of error.
Here are detailed descriptions of the parameters.
FILE
This is the name of the Spooled file to distribute, for example: QSYSPRT. You can find this
information by working with spool file entries (WRKSPLF command).

- 321 -
JOB
This is the qualified job name that contains the spooled file. The format of the complete
qualified name is: job-number/user-name/job-name
Note that when you prompt the command with F4, the order of these parameters is job-
name/user-name/job-number. You can specify * to reference the current job.
SPLNBR
This is the number associated with the spool file. Special values are *ONLY, which
means there is only one spool file in the current job with the name specified in the FILE
parameter (for example, QSYSPRT), or *LAST, which means reference the last spool file in
the current job with that name.
FORMAT
This specifies whether the spooled file is to be saved on the PC with embedded blank
lines and page breaks (*RPT) or just as it appears when displayed on a green-screen
terminal (*FILE) using WRKSPLF.
The *RPT option is useful when you plan to work with the downloaded report using a Data
Extraction's tool, because you will see the report with spacing exactly as it would appear
on a hard-copy printed report.
The *FILE option is useful if you are not concerned about the exact spacing, and don't
want to have to scroll through blank lines when viewing or working with the data.
STARTPAGE & ENDPAGE
These options allow you distribute only a specific page range of a file. Enter *ALL or a
page number for the start page value. If you entered *ALL for the start page, the end
page should be blank; otherwise enter a page number.
PCFILE
This is the name of the PC file to create on the PC that will contain the downloaded Spool
file data. The default value is *SPLF, which means the PC file name will use up to the first
8 characters of the IBM i file name. For example, if the IBM i name is QSYSPRT, the PC file
name will be QSYSPRT.PRN. If the IBM i name is CUSTREPORT, the PC file name will be
CUSTREPO.PRN.
To convert the downloaded spool file to one of the several formats supported by Catapult
(PDF, RTF, PRN, TXT, HTML or TIF), append the appropriate extension to the end of the
file name. When you do this, you can use the replacement values described the section
“Target File Name” on page 240 ; for example, you could specify &n.pdf for this value.
PCPATH
This is the name of a valid path on a target PC, to point to the directory in which the PC
file will be created. You can type a path name up to 256 characters in length. Remember
that this path is relative to the Catapult Poller.
EMAILADDR
This is the email address of the intended recipient of the report. You can specify any valid
address on your network or on the Internet. For example, fbloggs@192.168.0.1 and
fbloggs@acme.com are examples of possible valid addresses.

- 322 -
EMGROUP
This is the name of a valid distribution group. Groups are defined using the Catapult
Console. See Chapter 9 for more information. If you specify a single email address using
the EMAILADDR parameter, this parameter must be *NONE.

IBM i commands convert parameters to upper case, so

ensure that your group name is defined with upper case
characters.

SUBJECT
Any text you type here will appear in the Subject field of the email message sent with the
spool file.
INCLUDE
Use this option to indicate whether the report should be included in the email body, or as
an attachment. Include *YES means the report will be included in the body of the email.
CRTUNIQ
This option allows you to control whether, if a file with the same name is found in the
target directory, it should be overwritten, or a new unique name generated for the latest
file. Use *NO to overwrite existing files, *YES to create a new, unique file name.
AUTOSCRIPT
This is to specify the name and path of a Data Extraction's batch file that you can execute
for the report being distributed. The default for this parameter is *NONE.
EZINFILE
Before a file can be processed by a Data Extraction’s batch file, it must be renamed to
the name expected by the batch file itself. Enter that name here. If the batch file input file
name is the same as the name you are initially giving to the downloaded file, you can
leave this value blank.
EZOUTFILE
This is the name of the PC file you want to create as the output from running a Data
Extraction's batch file for the spool file. This file name will be included as an attachment in
the email message sent to the intended recipients.
ZIPFILE
You can specify a PC file name to have the report zipped to. The default is *NONE. The
name must be a valid Windows long file name, up to 32 characters.
ZIPPWD
This value only applies if you specify a value other than *NONE for the ZIPFILE
parameter. Specify a password (using upper case characters only) to encrypt the zipped
file. The recipient of the email will need to know this password in order to unzip the file.
The default is *NONE, meaning the zipped file will not be encrypted.

- 323 -
ACTION
This parameter controls what happens to the spool file after it has been selected for
distribution. If it is a temporary report that does not need to be printed in hard-copy, you
may want to delete it. Or, if you want to ensure that other IBM i users can still view the
report, you may want to hold or save it. The possible values for this parameter are:
□ *DELETE - Delete the spool file after distribution.
□ *HOLD - Set the spool file status to Hold after distribution.
□ *SAVE - Set the spool file status to ‘Save After Print’.
□ *RELEASE - Release the spool file from the ‘HELD’ status to ‘RLS’ after
distribution.
You can also use, *NONE, the default, to do nothing to the spool file.
USRDTAVAL
Specify a value to update the User Data attribute of the spool file with. This value can be
viewed from the WRKSPLF command, making it convenient for you or other users to see
which spool files have been distributed using Catapult.
An example value you might choose could be 'CATAPULT', and then any time a user
sees this value for the User Data column on the WRKSPLF command, it is readily apparent
that the spool file had been distributed using Catapult. Some spool files on your system
may already contain values for this field. In those cases, you may want to check with the
appropriate individuals in your organization before you change its value. *NONE, the
default value, will not change it.

The USRDTAVAL parameter is independent of the ACTION

parameter, so it is possible to change the user data attribute of
the spool file even if you specify *NONE for the ACTION parameter.
And, since DELETE will delete the spool file, specifying any other
value than *NONE for the USRDTAVAL parameter in conjunction with
an ACTION parameter value of *DELETE will produce no visible
results.

TIMEOUT
Set the timeout value for how long the server program will wait for a completion message
to be returned by the Catapult Poller. If the specified time elapses an error message is
generated and sent to the message queue specified by the Notify parameter.
NOTIFY
Select where to send messages to in case of error. Possible values are *SYSOPR and
*PGM. Using *SYSOPR sends a message to the current message queue. *PGM sends a
break message to the program’s message queue. This means that the ZDSTSPLF
command can be ‘mon-messaged’ for CPF0000 and your job stream can react
accordingly.

- 324 -
How the ZDSTSPLF Distribution Process Works
When you run the ZDSTSPLF command, the distribution process you initiate works as
follows:

The Catapult Poller application must be running on the

Catapult Poller PC. See Chapter 3 for details on configuring
this application.

1. The command creates a download request entry and a temporary (invisible)

grab rule.
2. The distribute command (ZDSTSPLF) immediately wakes up the IBM i program if
it ‘sleeping’ (waiting for the next polling cycle). The Catapult Poller receives
this download request and processes it, distributing the spool file according to
the parameters entered on the command.
3. If there are any errors with the process, the appropriate error notification
options are taken, as defined in the grab rule.
4. The Catapult Poller returns to a ‘sleep’ state and updates the sleep time to
take into account the time spent on the ZDSTSPLF command.

- 325 -
Using the ZRUNRULE (Run Rule) Command
The ZRUNRULE command allows you to execute a the logic of a particular grab rule over a
selected spool file. Like the ZDSTSPLF command, this means that you can initiate the
distribution of a spool file from an IBM i command line or CL program. However, the
ZRUNRULE command does require that you have already created a valid grab rule via the
console. The advantage to using this command is that you can take advantage of all
distribution features available from the console.
If you have a simple distribution request to issue, you can use the ZDSTSPLF command,
which has a more limited number of options, but doesn’t require that you first create a
grab rule.

The ZRUNRULE command triggers immediate processing to

occur. If the poller is already in the middle of a polling cycle, the
request is added to the list of pending requests.

The options available when you use the ZRUNRULE command include:
□ You can specify the spool file selection attributes (file name, job, number, etc.)
□ The number of an existing, valid grab rule.
□ A single email address or a mail group to send the file to (overrides grab rule
default).
□ The return address.
□ The email subject.
□ The PC file name and download path (again, to override the grab rule defaults).
□ Printer name/groups.
□ Fax number/groups.
In addition, the command allows you to specify a timeout value. Using this, you can tell
when the request is completed, or if the poller didn't get to it before the timeout value
expired. It is also MONMSG'able for CPF0000, similar to the ZDSTSPLF command.
These are described in detail below.

ZRUNRULE Parameter Reference

Parameter Attributes Description Valid Values
The name of the spool file whose
FILE 10 A Spooled file name
contents are to be downloaded.
Job: 10 A
Name of the job containing the spool
JOB User 10 A Qualified Job name or *
file
Nbr 6,0 N
Number of the spooled file to Spooled file number,
SPLNBR 6,0 N
download *ONLY or *LAST
RULENBR 7,0 N Number of the grab rule from which Valid grab rule number.

- 326 -
 to extract attributes.
Set the timeout value for how long
the server program will wait for a
TIMEOUT 5,0 N Value in seconds
completion message to be returned
by the PC for a file.
Select where to send messages to in
NOTIFY 7A *SYSOPR, *PGM
case of error.
Valid email address on network to
EMAILADDR 256 A Email address
mail report to
EMGROUP 10 A Name of email group Email group
SUBJECT 80 A Subject for email message Text
Name of PC file to create (up to 32 Valid PC file name, or
PCFILE 32 A
characters) *SPLF
PCPATH 128 A Valid PC path name Path name or blank
One or more semi-
Email return address(es). See note
RTNADDR 256 A colon delimited email
below!
addresses.
One or more semi-
Fax number to which to send the
FAXNBR 128 A colon delimited fax
document.
numbers.
Previously defined
FAXGRP 10 A Group name.
Catapult group.
One or more semi-
Printer to which to send the
PRINTER 128, A colon delimited
document.
printers.
Previously defined
PRNTGRP 10 A Group name.
Catapult group.
Below are more detailed descriptions of the parameters.
FILE
This is the name of the Spooled file to distribute, for example: QSYSPRT. You can find this
information by working with spool file entries (WRKSPLF command).
JOB
This is the qualified job name that contains the spooled file. The format of the complete
qualified name is: job-number/user-name/job-name.
Note that when you prompt the command with F4, the order of these parameters is job-
name/user-name/job-number. You can specify * to reference the current job.
SPLNBR
This is the number associated with the spool file. Special values are *ONLY, which
means there is only one spool file in the current job with the name specified in the FILE
parameter (for example, QSYSPRT), or *LAST, which means reference the last spool file in
the current job with that file name.

- 327 -
RULENBR
The ZRUNRULE command assumes that the majority of the distribution criteria will be
extracted from an existing grab rule. Enter the appropriate grab rule number here.
EMAILADDR
This is the email address of the intended recipient of the report. You can specify any valid
address on your network or on the Internet. For example, fbloggs@192.168.0.1 or
fbloggs@acme.com are examples of possible valid addresses. If this is left as *RULE
then the value specified in the grab rule is used.
EMGROUP
This is the name of a valid distribution group. Groups are defined using the Catapult
Console. See Chapter 9 for more information. If you specify a single email address using
the EMAILADDR parameter, this parameter must be *NONE.
Use *RULE to default to the grab rule value.
SUBJECT
Any text you type here will appear in the Subject field of the email message sent with the
spool file.
Leave this option as *RULE to default to the grab rule value.
PCFILE
This is the name of the PC file to create on the PC that will contain the downloaded Spool
file data. The default value is *SPLF, which means the PC file name will use up to the first
8 characters of the IBM i file name. For example, if the IBM i name is QSYSPRT, the PC file
name will be QSYSPRT.PRN. If the IBM i name is CUSTREPORT, the PC file name will be
CUSTREPO.PRN.
If you want to take advantage of the more advanced file attributes, such as saving the file
as a PDF, you should set that up in your grab rule, and set this value blank to *RULE so
that the grab rule value is used.
PCPATH
This is the name of a valid path on the target PC, to point to the directory in which the PC
file will be created. You can type a path name up to 256 characters in length.
Leave this option as *RULE to default to the grab rule value.
RTNADDR
Specify an email return address. If you specify multiple addresses, they need to be semi-
colon delimited.

Note that this option only works if in the rule definition, the
From Address Source option is set to User Defined. If you
leave the default setting of using the Poller defaults, then the
value you specify here will not take effect.

- 328 -
 FAXNBR and FAXGRP
A fax number, or several semi-colon delimited numbers to distribute the report to. You
can alternatively select a previously defined Catapult group to distribute to.
PRINTER and PRNTGRP
A printer number, or several semi-colon delimited printers (UNC format) to distribute the
report to. You can alternatively select a previously defined Catapult group to distribute to.

How the ZRUNRULE Distribution Process Works

Like the ZDSTSPLF command, ZRUNRULE requires that the Catapult Poller already be running
on the PC before it can process a rule. Here is what ZRUNRULE does when you submit it:
1. Creates a download request using the information submitted from the
command parameters and the existing, referenced grab rule. A temporary,
hidden grab rule is created.
2. The Run Rule command (ZRUNRULE) immediately wakes up the IBM i program if
it ‘sleeping’ (waiting for the next polling cycle). The Catapult Poller receives
this download request and processes it, distributing the spool file according to
the parameters entered on the command and in the specified grab rule.
3. If there are any errors with the process, the appropriate error notification
options are taken, as defined in the grab rule.
4. The Catapult Poller returns to a ‘sleep’ state and updates the sleep time to
reflect the time spent on the ZRUNRULE.

- 329 -
Using the ZRUNNETRUL (Run Net Rule) Command
The ZRUNNETRUL command allows you to execute the logic of a particular grab rule over a
selected network file, such as a file on a Windows file server or a stream file on the IBM i
IFS. Like the ZDSTSPLF command, this means you can initiate the distribution of a network
file from the IBM i command line or CL program. But the ZRUNNETRUL command requires
that you have already created a valid grab rule via the console.

The ZRUNNETRUL command triggers immediate processing to

occur. If the poller is already in the middle of a polling cycle, the
request is added to the list of pending requests.

The options available when you use the ZRUNNETRUL command include:
□ You can specify the full path to the network file that will be distributed.
□ The number of an existing grab rule.
□ A single email address or a mail group as the recipient of the report.
□ The return email address.
□ The email subject.
□ The PC file name and download path.
□ Printer name/group.
□ Fax number/group
In addition, you can set a timeout value for how long the poller will wait for the network file
to be available. You can use this feature if there could be a delay in creating the file on
the network.
These options are described in detail below:

ZRUNNETRUL Parameter Reference

Parameter Attributes Description Valid Values
The full path to the network file that
PATH 512 A Network file path
is to be distributed.
Number of the grab rule from which
RULENBR 7,0 N Valid grab rule number.
to extract attributes.
Set the timeout value for how long
the server program will wait for a
TIMEOUT 5,0 N Value in seconds
completion message to be returned
by the PC for a file.
Select where to send messages to in
NOTIFY 7A *SYSOPR, *PGM
case of error.
Valid email address on network to
EMAILADDR 256 A Email address
mail report to

- 330 -
EMGROUP 10 A Name of email group Email group
SUBJECT 80 A Subject for email message Text
Name of PC file to create (up to 32 Valid PC file name, or
PCFILE 32 A
characters) *SPLF
PCPATH 128 A Valid PC path name Path name or blank
One or more semi-
Email return address(es). See note
RTNADDR 256 A colon delimited email
below!
addresses.
One or more semi-
Fax number to which to send the
FAXNBR 128 A colon delimited fax
document.
numbers.
Previously defined
FAXGRP 10 A Group name.
Catapult group.
One or more semi-
Printer to which to send the
PRINTER 128, A colon delimited
document.
printers.
Previously defined
PRNTGRP 10 A Group name.
Catapult group.
Below are more detailed descriptions of the parameters.
PATH
This is the full path to the network file that will be distributed. For example:
\\fileserver.company.com\SHARE\update.txt.
Paths starting with drive letters may sometimes work. However, we recommend that you
use a fully qualified UNC path (starting with a double backslash and the server name) for
the network file.
RULENBR
The ZRUNNETRUL command assumes that the majority of the distribution criteria will be
extracted from an existing grab rule. Enter the appropriate grab rule number here.
EMAILADDR
This is the email address of the intended recipient of the report. You can specify any valid
address on your network or on the Internet. For example, fbloggs@192.168.0.1 or
fbloggs@acme.com are examples of possible valid addresses. If this is left as *RULE
then the value specified in the grab rule is used.
EMGROUP
This is the name of a valid distribution group. Groups are defined using the Catapult
Console. See Chapter 9 for more information. If you specify a single email address using
the EMAILADDR parameter, this parameter must be *NONE.
Use *RULE to default to the grab rule value.
SUBJECT
Any text you type here will appear in the Subject field of the email message sent with the
spool file.
Leave this option as *RULE to default to the grab rule value.

- 331 -
 PCFILE
This is the name of a valid path on the target
PCPATH
This is the name of a valid path on the target PC, to point to the directory in which the PC
file will be created. You can type a path name up to 256 characters in length.
Leave this option as *RULE to default to the grab rule value.
RTNADDR
Specify an email return address. If you specify multiple addresses, they need to be semi-
colon delimited.

Note that this option only works if in the rule definition, the
From Address Source option is set to User Defined. If you
leave the default setting of using the Poller defaults, then the
value you specify here will not take effect.

FAXNBR and FAXGRP

A fax number, or several semi-colon delimited numbers to distribute the report to. You
can alternatively select a previously defined Catapult group to distribute to.
PRINTER and PRNTGRP
A printer number, or several semi-colon delimited printers (UNC format) to distribute the
report to. You can alternatively select a previously defined Catapult group to distribute to.

Initiating a Poller Cycle with ZPOLLNOW

Use the ZPOLLNOW command to programmatically trigger a poll cycle. This may be useful if
you have a long polling interval and lots of spool files being generated by a particular
report, and you want to initiate the polling during periods of low activity on your IBM i
(such as during lunch breaks, or after a backup).

Using the ZPOLLEND (Poller End) Command

The ZPOLLEND command can be used to end the Catapult Poller from an IBM i job. This is
particularly useful for monthly backup jobs or other unscheduled down time.
The ZPOLLEND command does not require any parameters; it sends a message to the
Catapult Poller that will cause it to end immediately if it’s in a ‘sleep’ state (not in the
middle of a polling cycle), or directly at the end of the currently polling cycle, if the poller is
currently processing.

- 332 -
 - Catapult PC Component Configuration Options

CHAPTER 19

Chapter 19 - Catapult PC Component Configuration

Options

Chapter 2 of this guide includes instructions for installing Catapult as well as descriptions
of the basic configuration options. This chapter includes detailed descriptions of all the
available options. These range from communication options and features to adjust the
user interface to others designed to help make Catapult run as efficiently as possible in
your environment.

- 333 -
Catapult Communications Configuration
Use the Communications Configuration utility to create connections between your PC
and IBM i. You can launch this utility from the Catapult Launchpad or via the Start menu,
at All Programs/Catapult 7.7/Tools and Documentation/Communication Configuration.
Here is an illustration of this window:

Figure 19-1. The Catapult Communications Configuration window.

This shows the TCP/IP details for your system(s). The example above shows one IBM i
system configured. To configure communications, you need to add your IBM i to the list
above.
Remember Session Password
Check this option to have Catapult remember your user profile and password for 24
hours, no matter how many connections you establish to the IBM i. As a general rule, the
only reason you wouldn’t check this is if the PC is being shared by multiple users with
different PC/network IDs.
Conversation Timeout
The conversation timeout value is the default amount of time that EXODUS55 will wait,
when contacting the host IBM i and during normal conversations, before issuing a
timeout message. The default is usually acceptable, but if your IBM i is subject to
inordinately heavy workloads, you may consider increasing this to 60 or 90 seconds.
Display Warning/Error Messages
When you check this option, Catapult will pop up boxes alerting you to any
communication errors.
Log Warning/Error Messages
When you check these options, any communications errors or warnings are written to
the file EXODUS55Trace.log.
These options generally only need to be turned on at the advice of Technical Support.

- 334 -
Adding and Configuring Connections
Click on the Add button to present the window below for adding new system connections:

Figure 19-2. Catapult’s EXODUS55 Connection settings.

System Name
Catapult displays this description at the various locations from which you can establish
connections.
Environment Library
The default value is XL_CATAPLT, but you can specify a different environment here if
you need to. The process for establishing test environments is described in the separate
Upgrader’s Guide. You may want to run Catapult in a test environment if you have a
number of mission-critical operations being executed by Catapult, and you want to test
new releases in a controlled environment before performing a definitive upgrade.
Target IP/Domain
Enter your IBM i IP address. This is the same value you entered during the IBM i install,
when you were prompted to configure EXODUS55 for TCP/IP.
Port
The Port field is used to define a port number on the host to attach to. This must
correspond to the port number specified when configuring TCP/IP on the IBM i (which
you most likely did during the install). The default value of 2015 is usually acceptable.
We provide the option to configure this value in case you already have a TCP/IP service
(such as FTP, Telnet, Ping etc.) that coincidentally uses the EXODUS55 default port
number.
Local IP to Use
If your PC has multiple local IP addresses (e.g. you have two NICs, or are connecting via
a VPN) your PC may have two separate local IP addresses. You need to select the local
IP that is on the same subnet as your IBM i.
If your network or system are in any way configured to allocate IP addresses
dynamically, for example using DHCP, you’ll need to make sure the Catapult system has

- 335 -
 a STATIC IP address. If not, there is a chance that it may use the wrong one and fail to
connect.
IBM i Profile
If you enter your IBM i User ID and password here, you don’t have to type them every
time you connect. You also need values here to run the poller.
Test Connection
Use this button to confirm your settings. You should get this message:

Figure 19-3. Successful connection message.

Click OK to save your connection and return to the Communications Configuration

window. If you need to connect to more than one IBM i, add your other systems to the list.

Logging In to Catapult
The first time you attempt to log in to one of the Catapult components, you will be
prompted to log in, with a window similar to this one:

Figure 19-4. The Catapult Login window, presented when you launch any component.

Connection
This dropdown list displays the system connections you have created. Click the arrow to
select a different one from the default shown, or click the Communications... button to
either work with the existing connection or create a new one.
User Name/Password
Type your IBM i User ID and password to connect to your server and launch the
requested Catapult component.

- 336 -
Catapult Console Configuration Options
There are a number of configuration options that you can access via the console, most of
which relate to your grab rules, and controlling and tracking their execution. These are
described elsewhere in this guide, particularly in , Using the Catapult Console and ,
Report Distribution and Tracking Options.
There are, however, a few options that relate particularly to the console. These are
available from the Tools/Configuration menu option, or via the Start menu, at All
Programs/Catapult 7.7/Console/Console Configuration.

General Console Options

Here is an illustration of the general console configuration options:

Figure 19-5. The first set of console configuration options.

Check for Product Updates on Connect

Because you can install the Catapult Console on any number of PCs, PC side (client)
software updates are included in the IBM i (server) updates. When you apply a new IBM i
side update a new PC version may also be included and will be instantly available.
Use this option to instruct the console to check for updates on the server each time you
fire it up. If there is a newer version of the console available, it will display a message
prompting you to download and install the latest version.
This mechanism helps prevent level checks that can be caused by the server side being
updated without client updates having been rolled out to all users. If you unselect this
option, your first indication that someone has upgraded the server side of software will
be a level check error on the PC. If you do uncheck this option and want to verify whether

- 337 -
 there is a newer version of the software available on the server, you can select the
‘Check for Update’ option from the Tools/Options menu.
Restore Console Defaults
Use this option to re-set the Console settings to their newly-installed state.
Default Queue
Use this option to set the default queue shown in the preview windows used to locate
spool files for selection.
Automatically Load Spool File List
Select this option to automatically load a list of spool files in the selector list when you first
launch it.
Automatically Refresh Request and Errors List Entries on Display
Check this box to automatically update the Request Errors list window every time you
open it.
Automatically Refresh History List Entries on Display
Check this box to automatically update the History list window every time you open it.
Document Viewer Translation: EBCDIC & ASCII CCSIDs
Catapult uses these values for translating spool file documents from EBCDIC on the IBM
i to ASCII on the PC. You should specify the default CCSID for spool files on their IBM i ( 
the default in North America is 37), and the default CCSID for text documents on the
poller PC (Windows: Western is CCSID 819).
Application Data Path
Enter the location to which you want Catapult to save application data.

Rule Editor Defaults

Use these options to set defaults for your new rules. Here is an illustration of the options
available:

- 338 -
Figure 19-6. Default options for new rules.

Default Rule Status

If you usually want new rules to be active as soon as you save them the first time, then
you should set your default status to Active. If most of the rules you create are complex,
and require testing to make sure you don’t spam hundreds of customers with an
incomplete file, then you should make your new rules inactive by default.
Default Acquisition Type
Catapult can poll both IBM i out queues and network directories. Set the default for the
type of files that you most often look for.
Default Document Format
There are several different document types you can select when downloading and
distributing your reports. Use this option to set your default format to the one you most
often use.
Default Font Encoding
This option is intended for European languages that have extra characters. It changes
the font encoding to replace those characters not used in a specific language with ones
that are used. For example, English uses the MS 1252 – Latin 1 encoding, but Polish has
a number of extra characters not used in English. In that case, Polish clients would use
the MS 1250 – Central European encoding in order for PDF and RTF files to be created
correctly.
Catapult also allows you to configure a default Nexus site from the console configuration.
Default Nexus Library
You can run multiple copies of Nexus in separate libraries. If you are taking advantage of
this feature, set a default library to use with Catapult.

- 339 -
 Default Nexus Site
This value is used to populate the Site value of the Nexus category in new rules defined
from the console. The value is set here mainly to ensure that when you set up a link to
Nexus, there is a correct site value specified. It is important to initially set a site value, as
the 'Data Name' values are site specific, and if you do not have a site selected, no Data
Names are presented in the list.
Catapult and Nexus are described in the section “Distributing Reports to Nexus Portal”
on page 298 .
Network Path Resolution
Use this option to have Catapult automatically attempt to derive correct UNC paths when
you select a network directory in the grab rule editor.
Performance Optimization
This option allows you to disable the auto refreshing of the rule list after each rule edit.

Console Columns
By default, the console displays your grab rule number, description, creator and status.
The list also displays some elemental information about the spool file(s) that the rule will
process, including the spool file name, job name, user, user data, out queue and status.
You can adjust the columns displayed to include different information. To do this, go
Column category of the Console Configuration:

Figure 19-7. Selecting the columns to display in the console’s list of grab rules.

- 340 -
 Select Columns
From here you can check the columns you wish to display in the main list. Use the Up and
Down buttons to move items around in the list, where moving an item up moves it further
to the left in the grab rule list.
Click OK to apply your changes.

Console Messages
If you find yourself talking out loud as you work with the console, and saying “Yes, yes, I
*know* I want to do that...” then it may be time to turn off some of the tool’s warning and
confirmation messages:

Figure 19-8. Warning and confirmation messages that can be toggled on/off.

Confirm Before Toggling Rule Status

Check this option if you want Catapult to make you confirm each time you toggle a rule to
be active or inactive from the console (not from within the grab rule editor).
Confirm Before Copying a Rule
Copying a rule may seem like a relatively innocuous process until you consider what a
rule may be doing. If you have a rule that processes a report and then distributes it to
hundreds or thousands of recipients, by copying that rule and leaving it active, you run
the risk of re-sending everyone the identical report(s), one time for each grab rule.
Check this option if you want to be reminded of this each time you copy a rule.
Display a Warning When Filtering Over a Queue That Has Been Omitted
If you build your spool file selection using the spool file list and preview windows, you’ll
see that the queues you’ve instructed the poller to skip are greyed out in the list.
However, you can also enter a queue directly in the grab rule editor, and if that queue
isn’t being polled, you will wait a long time to see any results from your rule.

- 341 -
 Check this option to have Catapult warn you when you build a rule over a spool file in a
queue that isn’t being polled.
Display the Spool File List Autoload Message
Whenever you use the preview window from within your grab rule you can choose to
have Catapult automatically load a list of spool files matching your selection criteria. If
you want to be prompted for whether to load a list each time you open the preview
window, check this box.
Confirm Before Creating/Updating Pages
The Title/Footer and Header/Footer pages you use in your grab rule can be edited
externally from their respective editors, or direction within your grab rule. Check these
options if you want to be warned about changes you make in your grab rule affecting
objects that may be used by other rules.
Display a Warning when Specifying Custom Page Sizes
Check this option if you want Catapult to alert you when you select oddball pages sizes
that don’t conform to normal standards.
Display a Warning when Using a Non UNC Path
Check this option if you want the Catapult Grab Rule Editor to alert you to any non UNC
paths you add for objects used in the rules (overlay images, etc.). Using non UNC paths
can create problems if your network configuration changes or you move the poller to a
different box.

Email Options
The console allows you to email grab rules as one of the export options (File/Export
Rule...). You may want to email the rule to yourself for documentation purposes or to
Technical Support so we can help you troubleshoot it. Because the mechanism for
emailing directly from the console is different from what the poller does when it
downloads the spool files, you need to configure the console for this feature separately
from the poller.
Below is an illustration of the Catapult Console Email options:

- 342 -
Figure 19-9. Configuration options to allow emailing grab rules from the console.

From Name
This is the default name to appear on grab rules emailed by you from the Catapult
Console. This appears in the 'From' value of the recipient's email message.
From Address
This is a default email address that a grab rule will appear to have been sent by, when
you send a rule from console. This would normally be your own email address.

Most email servers reject email if the From Address is invalid

or unknown.

Server Domain/IP Address and Port Number

Specify the IP address and port number for the email server. Catapult will attempt to
contact this server whenever you email a grab rule. If you are not sure what value to use
here, find the value currently used by the Catapult Poller, or the IP address or server
name currently used by your email software (Outlook, Netscape, Eudora, etc.).
Connection Timeout
Set the time that the console should wait for a response from the email server before
issuing a timeout message.
User Validation
Some SMTP servers require that a valid User ID and password be provided by any
application attempting to send an email. In many cases, this type of validation may only
be in effect for external email. If your email server is rejecting the grab rules you are

- 343 -
sending with the Catapult Console, or not sending any messages outside your network,
you should check whether this option is required.

- 344 -
Configuring the Catapult Poller
The Catapult Poller is the PC-based application used to control the distribution of your
reports. You need to configure and start the Catapult Poller before Catapult can
distribute any files.
The Catapult Poller Configuration tool lets you set which IBM i is (or are) polled to find
new eligible spool files for distribution. It also lets you define the address for your
organization's email server, properties for the administrator of Catapult, the default
reply-to address for your distributed email, and other miscellaneous information.
You can open the poller configuration from the Catapult Launchpad (using the right-click
menu) or from All Programs/Catapult 7.7/Poller/Poller Configuration.
Any changes you make to the configuration do not take effect until the Catapult Poller is
restarted.

General Polling Settings

Here is an illustration of the Poller Configuration window:

Figure 19-10. Catapult Poller Configuration.

The first set of options shown above allows you to control when the poller starts and
shuts down, and how frequently it polls.
Start Up
The Catapult Poller runs as a service on your PC. Use this option to control when the
poller starts up:
□ Automatic. Select this option to start the poller as soon as the poller service
starts. When you select this option, the scheduled shutdown option is not

- 345 -
 available. If you select this option and the polling instance is ended manually (via
the Poller Manager, or by using the ZPOLLEND command on the IBM i), the poller
will not start again automatically until the poller service is ended and restarted.
You can, however, still start the poller instance manually.
□ Manual. Choose this option if you always want to start the poller manually.
□ Scheduled. Use this option if you want the poller to start up and run at a specific
time each day. If during a 24-hour period, you manually start the poller service
after the start time, the poller will execute a cycle immediately, and then at the
scheduled time for all subsequent days. [For instance, if you schedule it to run at
2:00 AM, but start it at 9:00 AM when you get in to work.] If the scheduled time is
still in the future from the startup time, the poller will wait until the scheduled time
to run for the first time. If the polling instance is ended manually or via a
scheduled shutdown, it won’t restart until the time of the next scheduled startup.
The key thing to remember is that the poller initiates a polling cycle as soon as it is
started. So if over the course of the day your organization builds up potentially huge
volumes of spool files to be processed, then you may want to run Catapult just at night.
Or if you are generating smaller volumes of documents to process, and want them send
out immediately as they are created, then you can have the poller running all the time,
with relatively short polling intervals.
Shut Down
Use this option to set whether you will shut down the poller manually or have it shut down
automatically at a specified time.
Polling Cycle
The poller runs continually on the IBM i. Some of the time it is ‘asleep’ (the time between
polls). When it wakes up it looks at spool file entries for all selected output queues and
compares them to the active grab rules to see if any new spool files qualify for
distribution. Use the following options to set when the poller should wake up and execute
a cycle.
Polling at Regular Intervals. Use this option to set a number of minutes the process
waits between the end of one execution cycle and the beginning of the next. At the end of
the wait period, the Catapult Poller program wakes up and examines all output queues
for newly arrived spool files that qualify for downloading.
If you find that the polling process itself is taking too long but you don’t want to increase
your polling interval, you should consider limiting the number of queues polled on each
cycle. This feature is described in the section “Selecting Queues to Poll” on page 347.
Implementing Catapult , also outlines some other strategies you can employ to make
Catapult run more efficiently.
Polling Once Daily. Use this option to set the time at which Catapult will poll (once every
24 hours). When the specified time of day arrives the Catapult Poller program wakes up
and executes a single polling cycle.
If you find that the polling process itself is taking too long but you don’t want to increase
your polling interval, you should consider limiting the number of queues polled on each
cycle. This feature is described in the section “Selecting Queues to Poll” on page 347.

- 346 -
 Network Acquisition Default Profile
This is a separate profile you can add if you have grab rules attempting to access and
distribute network files in a location that the main Windows profile running the poller
doesn’t have access to. You can also set this value in individual grab rules, so if you have
specific rules accessing sensitive information, you should enter the profile in those rules
only, and not here. This profile, set in the poller defaults, should be used for general
network access rather than to permit any Catapult user to create grab rules over any
network directory.

Selecting Queues to Poll

When you first install Catapult the software is configured to poll all queues. During the
install you selected the queues you wished to poll, and if you are finding that Catapult’s
resource usage is higher than expected, you’ve probably selected either very many
queues, or queues with large numbers of old, archived spool files.
With the queues you select, Catapult compares every file in every queue to the current
list of grab rules, as well as checking every request to the entries in your history list. If you
also set an interval of just a few minutes between polls, it may seem like the Catapult
Poller is almost perpetually running.
The most effective way to improve performance is to limit the set of queues that Catapult
polls. You can do this from the Out Queues category in the poller Configuration, shown
below:

Figure 19-11. Selecting the queues to poll, in the Catapult Poller Configuration.

Use the buttons between the two lists to move your queue(s) between the selected and
omitted lists.

- 347 -
 We suggest that you not exclude any queues from the list
until you have received at least one email from Catapult.
Overzealous queue exclusion is a frequent cause of
otherwise correct grab rules not producing the expected
results (i.e. not finding any matches).

Queue Authorities
In this window, the queues selected to be polled are checked. In addition, the queues
you are not authorized to are also grayed out. This gives you a visual indication of which
queues will not be processed by the Catapult Poller, if it uses the same user profile as the
one with which you are currently logged in.

Configuring the Email Server Information

One of Catapult's primary functions is to distribute spool files by email. In order to do this,
you must have an operational email server that supports the SMTP protocol, and provide
Catapult with its IP address. There are also a few other options for which you can set
defaults.
To set the email server information click on the Email Server category:

Figure 19-12. Catapult Poller email server configuration options.

From Name
This name will appear in the 'From' value of email messages sent by Catapult.
From Address
This is a default for email messages where the grab rule doesn’t explicitly set a from
address. You can override this value in your individual grab rules or extract it from your

- 348 -
reports. This is normally set to the administrator’s address.

Most email servers will reject email if the From Address is

invalid or unknown.

Server IP Address & Port Number

Your email server can run on any platform, such as Windows XP, OS/400 or Unix, and be
located on an Intranet or through the Internet.
The default Server IP address when Catapult is installed is 127.0.0.1. Specify your own
server’s IP address in place of this value. If you are not sure what value to use here, find
the IP address or server name currently used by your email software (Outlook,
Thunderbird, etc.); it should be the same as this. If your mail server is named with a DNS
entry (such a mail.my400.com), you can use this name in place of an IP address.
Catapult will attempt to contact this server whenever an eligible spool file is ready to be
emailed.
The default port number of 25 is generally acceptable.
Connect Time Out
This is the time that Catapult will wait to establish a conversation with your email server.
Each time Catapult sends an email it must connect to and ‘handshake’ with your mail
server. If your mail server experiences very high volumes you may need to adjust this
value.
Connection Attempts (Retries)
This is the number of times Catapult will attempt to connect to your mail server. If your
mail server is on a WAN you may want to increase this number to help cope with network
glitches and lost TCP/IP packets.
SMTP Authentication
Some SMTP servers require that a valid User ID and password be provided by any
application attempting to send an email. In many cases, this type of validation is only in
effect for external email. So if your email server is rejecting the email you are sending
with Catapult, or not sending any messages outside your network, you should check
whether this option is required.
Use Separate SMTP Conversations
This option forces the email thread to recreate the SMTP conversation between each
email (instead of sharing a connection by sending emails in batches). This option is
relevant if your email server is running into trouble sending large volumes of email all at
once.
Validate Email Addresses Before Distribution
This option allows you to remove Catapult’s check of email validity, just before the email
is sent. This is relevant to you if your email server allows non-standard email addresses
(for instance, with no domain; e.g. ‘fredsmith’ rather than ‘fredsmith@company.com’).

- 349 -
Email Administration Options: Error Notification
From the Email Administration category you can define information for the Catapult
Administrator. Mainly this information relates to when errors are encountered during
attempts to distribute email, create PDF/RTF/HTML documents, or saving to network
drives.
We recommend that you initially set the poller to notify you on any error. Doing this will
help you pinpoint any problems in your grab rule definitions or polling configuration. Also,
this will help you stay on top of the status of the poller. To do so, select the ‘Notify on any
error’ option and then type your name and email address.
Here is an illustration of the options available at this window:

Figure 19-13. Catapult administrator notification options.

Notification Options
When an error occurs in the spool file distribution process the Catapult Poller can inform
the administrator by sending an email message. From the poller’s perspective there are
two types of error: non-fatal errors (including warning messages) and fatal errors.
□ A fatal error is one which prevents any further processing of spool files by the
poller. This may occur if the poller terminates prematurely due to mail server or
network conditions.
□ A non-fatal error prevents only a particular spool file from being distributed. This
may occur if the connection to the mail server times out or if the poller is unable
to find the spool file corresponding to a Download Request because the spool file
has been deleted on the IBM i between the time when it was flagged for
distribution and when the poller actually attempted to retrieve it.
□ A warning is issued when spool file processing can continue, but an operation
cannot be applied to a particular spool file.

- 350 -
 Select ‘Do not notify’ to disable the notification of distribution errors.
Notify on Startup/End
Check these options to send the Catapult administrator an email when the poller starts
and/or ends.

The Catapult Launchpad can also be configured to display

messages or send emails that poller instances have started or
ended. These options are described in the section “Using the
Catapult Launchpad” on page 317 .

Name & Email Address

This is the name and email address of the Administrator. Email is sent to this address
based on the notification option selected.
Non-Fatal Error Subject
This is the text that will appear in the subject field of email received by the administrator
when they are notified of a non-fatal error. These types of errors occur when an attempt
to distribute a report failed, yet subsequent processing can continue.
Fatal Error Subject
This is the text that will appear in the subject field of email received by the administrator
when they are notified of a fatal error.

If there are problems with your email server, no email can be

sent to the Administrator. At that point, you can work with the
Catapult Console and view the download request error list (see
“Request Errors” on page 311), or review the error logs that
Catapult creates. The easiest way to get to the error logs is via
the Catapult Launchpad, by right-clicking and selecting the
option Documentation/Error Logs. You can also find the error
logs at C:\Documents and Settings\All Users\Application
Data\ESDI\Catapult.

Warning Subject
This is the subject of any email issued when a spool file processing error occurs.
Startup/End Subject
Type the subject for the emails the administrator will receive when the poller starts and
ends.

Other Miscellaneous Email Options

Click the Miscellaneous category to work with these options:

- 351 -
Figure 19-14. Email options for handling multiple recipients and attachments.

Create Separate Email for Grouped Emails

Use this feature to keep distribution email addresses private by sending each group
member an individual email message, rather than distributing a single message to
multiple users (i.e. with all the recipients shown in the To: field).
For example, if you have a group with three members and you do NOT check this option,
the messages to the group are sent to an address like this:
bob@here.com;joe@there.com;bill@elsewhere.com

If you check this option, then Bob, Joe, and Bill will each get an individual email,
addressed only to them.
Include List of Recipients In Email Body
Alternately, you can use the Separate Email for Grouped Emails option to simplify your
send information in the email header (everyone hates getting email with hundreds of
recipients in the header), but by checking this option you can still include a list of all the
recipients in the email body.
Attachment Options
In cases where a recipient matches multiple key values in the report, Catapult will
attempt to intelligently group multiple spool files into a single email. By grouping the
processing requests by the grab rule number they are based on, Catapult can ‘look
forward’ for other requests being sent to the same email address. This means that within
a polling cycle an email address can receive a single email per grab rule, rather than one
email for each separate request generated by that grab rule.
You can choose from the following options for handling attachments:

- 352 -
□ Include multiple attachments per email. Check this box if you are distributing
split sections as attachments and you want to collect all split sections directed to
a particular recipient into a single email.
□ Include multiple body entries per email. Check this box if you have rules that
distribute split sections in the email body (in plain text format or as HTML) and
you want to group all split sections to a particular recipient into a single email.
□ Include multiple links per email. Check this box if you have rules that create
links to files in an email, and want to combine these links into a single message.
● Maximum attachments/entries per email. Set a value for the maximum
number of split sections to include in a single message (either as
attachments or in the body of the email). Beware of making this value to
large, as email can easily become large and unwieldy, and most email
servers reject mail that exceeds a certain size.
□ Include a list of attachments in email body. Check this box if in addition to the
standard method for displaying attachments used by the recipient’s email client
you also want to create a list of attachments in the actual body of the email. This
can be useful to identify each attachment. For further details, refer to the section
“Distributing the Document as an Attachment or In Email Body” on page 279 .
□ Include attachment count in email subject. Check this box to append the
number of attachments to the end of your email subject. For example: ‘January
Invoices [13]’.

- 353 -
Advanced Poller Configuration Options
This section includes various options that usually work fine as shipped, don’t often need
to be changed, or have been required by clients with unique situations.
This is the first set of advanced options:

Figure 19-15. Catapult Poller advanced configuration options.

Clear History Entries Every X Days

Catapult generates history records for every report it processes, and unless these are
deleted, they can accumulate quickly.
Use this option to automatically delete history records after the specified time interval,
from 1 to 100 days). The default value is 10, to purge any entries older than ten days
from the system. Records older than the purge date are removed each time the Catapult
Poller program runs through its cycle.

If you have many grab rules, a bloated history listing can

result in a significant degradation of performance in the
polling cycle. In a situation where you have hundreds of grab
rules and many thousands of history entries, each time the
poller runs it not only evaluates every spool file against the
grab rule file, it also has to compare each request against
the thousands of existing history records.
The other side of the coin is that if a spool file still exists in the
same queue unchanged when a history record is deleted,
Catapult will send it again. So while you don’t want to

- 354 -
 distribute files more than once, instead of keeping your
history records for a long time you should move your
Catapulted files to a different queue (which is not polled), or
in your grab rule change the user data of the processed
spool files so they no longer match the grab rule selection
criteria.

Clear Error Entries Every X Days

Error Entries are download requests that are pending due to an error. Use this option to
periodically clear these records. This works in exactly the same manner as purging
history entries.
EBCDIC CCSID
Catapult uses this value and the one below for translating spool file documents from
EBCDIC on the IBM i to ASCII on the PC. You should specify the default CCSID for spool
files on their IBM i (the default in North America is 37).
ASCII CCSID
Catapult uses this value and the one above to for translating spool file documents from
EBCDIC on the IBM i to ASCII on the PC. You should specify the default CCSID for text
documents on the poller PC (Windows: Western is CCSID 819).
Remove Extra Whitespace
Check this option to strip all the extra white space from the spool file when the translation
takes place. This includes any trailing blank characters as well as blank lines of text.

This option is mainly present to retain compatibility with older

releases. Under normal circumstances, there shouldn’t be
any reason for you to uncheck this option, as it greatly
improves performance for many other areas of the software.

Unknown Characters
Use this option to instruct Catapult on how to handle byte values that it doesn’t
recognize. You can drop the character, replace it with the special value **unknwn**, or
replace it with a blank character.

The rather odd **unknwn** option is primarily useful for

debugging purposes, to help you find any particular characters
that aren’t being handled correctly. Otherwise, the character
might just be dropped, and it would be difficult to identify the
locations where this is happening.

Check for Software Updates

Click here to check whether there is a more current version of the Catapult Poller
available for download from the IBM i. Catapult PC updates are included with the IBM i
updates.

- 355 -
 Restore Default Configuration
Click here to restore all the poller settings to their shipped defaults.

Document Generation Settings

The options available here allow you to fine-tune certain aspects of how the poller
generates certain types of documents. Here is an illustration of this section:

Figure 19-16. Catapult Poller options for generating different document types.

Maximum File Sizes

There can come a point where no matter how much memory you have on your Catapult
Poller PC, someone creates a report so large that processing it with Catapult (for
instance, converting it to a PDF) could bring your machine to its knees. This can be a
particular concern if you have Catapult processing most reports during hours when your
office is closed, and a crash might delay the distribution of other urgent reports.
To help you avoid this situation the Catapult Poller includes an option to split reports
exceeding a particular size into smaller sections. The poller will divide up large files after
the Split/Parse process, but before the file is formatted into PDF/RTF/HTML. Dividing up
the file after the split process allows Catapult to assign extracted data values, key values,
Nexus data values, etc. to each of the divided sections, even if that section did not
contain the actual data.
Dividing up these large spool files into smaller sections can dramatically increase the
performance of PDF/RTF/HTML creation, since less memory is required to create each
section.

- 356 -
To enable this feature, check the ‘Fragment documents exceeding this page limit into
smaller pieces’ option. Then specify the page interval at which to split the document.
Each portion is then processed separately and distributed.
Document Splitting: Split Segments with Identical Keys
This option allows you to control how the Catapult splitting engine will handle sections
with identical keys. In this situation you can combine all such segments from the entire
report, or you can combine them only if they are adjacent to each other.
Document Splitting: Split Segments with no Anchor
When the Catapult splitting engine extracts a report section that doesn’t contain an
anchor, you can combine that section with either the previous or the following sections.
As an example consider a multi-page invoice. In most cases you will want to combine the
second and third pages (which may not include the anchor) with the first page.

The option to combine these sections with the next section is

available to maintain compatibility with an option available in
earlier releases.

Align RTF Overlay With Margins or Page

When you generate RTF files to use with overlays, you can have the poller line up the
overlay image with the page dimensions, or the margin size.
Combine Split Segments with matching key values
If you check this option, Catapult will combine split segments and key values in one
document so the recipient only receives one attachment with only relevant information,
rather than several attachments.
Automatically Determine Leading for RTF/PDF Files
If you check this option, Catapult will attempt to automatically determine how far apart
each line should be so that the lines on the page are evenly distributed based on font
size. If you do not check this option, Catapult uses a static leading for each line
regardless of the size of the font.
Automatically Determine Character Spacing for RTF/PDF Files
Check this option to have Catapult attempt to automatically determine how far apart
each character on a line should be so that it takes up the entire width of the page. If you
do not check this option, Catapult will use a character spacing of zeros.
Batch File Processing TimeOut
This is the time that the Data Extraction’s thread will wait for an batch file to finish
processing a document before issuing an error message and continuing on to the next
request. This value is required so that Catapult doesn’t wait indefinitely for batch file
processing to finish. Enter a value in minutes.
Zip Compression Factor
This value indicates the level of compression that is to be applied to spool files before
they are distributed. The value itself is an abstract figure indicating the ratio between the

- 357 -
 level of compression and the amount of time taken. Files can be made smaller by the
application of more intensive compression techniques, but this takes more time.
The zip compression factor can have a value of 0, 1, 6 and 9:
□ Use 0 to simply store the file.
□ A value of 1 results in the quick creation of a file with a minimum compression
level.
□ A value of 9 takes more time to create a very compressed file.
□ A value of 6 is a midpoint between the two.
You should choose a value based on the processing load experienced by the PC server
machine.

Printer Configuration Options

Click the Printing Options category to work with these options:

Figure 19-17. Default printing options used by the Catapult Poller.

If you intend to use Catapult to print documents, you need to ensure that the printer
driver is installed on the poller PC. You can confirm that the driver is installed by using
WordPad on the poller PC and printing a document to the printer.
Default Printer
Select the default printer that Catapult will use when the value *DEFAULT is selected for
the printer, in either you grab rules or group entries.
Printer Time Out
Set the length of time that Catapult will wait for a document to finish printing before
creating an error message and moving on to the next document.

- 358 -
 The way the print process works is by launching the default
application for the file type you are printing (for example,
Notepad for .txt documents) and using a Windows API to tell
it to print. The time out value is most relevant to getting
around a documented problem with certain versions of
Adobe Reader® that open and print, but don't close. This
means that after the designated time the request is flagged
as a 'warning'. To avoid problems with Adobe and time outs,
we recommend you install Foxit’s Reader 3 on the Catapult
Poller system to handle PDF files, or use RTF as your
printing format, with Microsoft Word® (rather than
WordPad).
The Print function operates on a different thread from other
Catapult functions so it doesn't slow down general grab rule
processing.

Wait for Print Process, Terminate Print Program After Timeout

Choose this option so Catapult, at the specified time interval, terminates the printing
application (Microsoft Word®, etc.), and continues with the next step of the polling
process.
Essentially, this option is assuming that if a document doesn’t print in the specified time
interval it’s because there was a problem, and therefore the application should be
terminated and an error issued.
Wait for Specified Time
This option instructs Catapult to wait for the specified interval, and then continue with the
next step of the polling process. If there is print application that is in the middle of its
process, it will remain open, and will have to be closed manually.
This option assumes that if the timeout is exceeded, it’s probably merely due to a printer
backlog, and therefore you wish to leave the print application alone to finish its process.
Update Printer List when Poller Instance Starts
Because the process of loading all the network printers can be very lengthy on some
networks the Catapult Poller is not set to automatically load a list of all the network
printers on startup. If you have a smaller network, and do wish to load a list on startup,
check this option.
When this option is selected, the buttons to get and update the list of printers are
disabled.
If you do NOT automatically retrieve a printer list on startup you need to click the Get
Network Printers button (described below) to do so manually. Otherwise the poller will
only have available the printer defined as the default printer.
Get Network Printers
If you have not selected the option to load the list of network printers at startup you need
to click this button to retrieve and list your network printers. Until you do this, you will have

- 359 -
 access only to the default printer on the PC.
Update Printers
Use this button if you have added a new printer to your server, and you want to make this
printer available to individuals who are creating grab rules. This button updates the list of
printers known to Catapult on the IBM i, and ensures that all individuals editing grab rules
are working with the same list of printers.

The list of printers known to the poller is only loaded when it

first launches, so if you update your printers you also need to
restart the poller for that change to be visible to your users.
You also need to use this option AFTER you have retrieved
the available printers by using the ‘Get Network Printers’
button.

Cache Directories
Use these options to override how Catapult handles cached and temporary files. Here is
an illustration of this category:

Figure 19-18. Options for overriding how cached and temporary files are handled.

Application Data Path

Select the location to which Catapult should save application data while running. As
noted above, when the console and poller are installed on the same PC, they will share
this location.

- 360 -
 Document Cache Management
Sometimes the selection criteria in two or more grab rules can match the same spool file.
In these cases it is inefficient to transfer that same file from the IBM i to the PC Server
each time there was a match. For this reason spool files can be stored in a cache
directory on the PC Server, and before a spool file is downloaded from the IBM i, the
cache is checked to see whether that spool file is there. If it is, the cached copy is used
for distribution.
Cache Directory
The Cache Directory field allows the administrator to choose the directory on the PC
Server machine where these cached files are stored. Click the Browse (...) button to
select a directory.
Approximate Max Size
This field controls the maximum amount of disk space allocated to the storage of cached
spool files. If this amount of space is exceeded, the oldest files are removed to make
space for new files.

Because the cache is purged at the end of the polling cycle,

the cache size can be temporarily exceeded. So if there are
space issues on your poller PC you should account for this
possibility when you set the cache size.

Temporary Files Management

When Catapult is in the process of downloading files in preparation for distribution, it
needs to store the files somewhere on the poller PC until they are ready for distribution.
This is particularly the case when the grab rule involves processing each file (for example
when splitting, or converting to PDF) before sending it off.
Use this option to clear the temporary Catapult files on your PC.

Poller Diagnostic Settings

This includes the option to enable debug mode:

- 361 -
Figure 19-19. The Poller Configuration diagnostic options.

Do not use this option unless instructed to do so by Technical Support, as it very quickly
creates very large log files.

- 362 -
 SECTION V
Appendices
In this Section:
Appendix A - Communications
Considerations
Appendix B - Rich Text Formatting Options
Reference
Appendix C - Catapult Troubleshooting
Guide

- 363 -
- 364 -
- Communications Considerations

APPENDIX A

- 365 -
APPENDIX A COMMUNICATIONS CONSIDERATIONS

In order to communicate between clients and the host IBM i, Catapult uses a middleware
component named EXODUS55. EXODUS55 is used to conduct conversations between
Clients and the Server (PCs and IBM i). This appendix describes how EXODUS55 is
used. It also describes the EXODUS55 IBM i subsystem: why it is necessary, what it does
and a description of all the OS/400 supporting objects that are required to make it run.
Another section below discusses security issues.
EXODUS55 uses TCP/IP sockets to maintain a link between clients and the host. This
technique requires what is commonly referred to as a 'daemon', which is a program that
is constantly running (but uses very little system resources). The EXODUS55 daemon
looks for any conversation requests from other IP addresses on the network (i.e., Client
PCs). Once it receives a request, it spawns a new job that conducts the conversation.

Why the EXODUS55 Subsystem is Needed for TCP/IP

The EXODUS55 subsystem is needed for the TCP/IP communications implementation
because it is used to run the daemon that spawns a job for each requested conversation.
The subsystem contains an autostart job entry so that when a STRSBS EXODUS55 command
is run, a job called EXSERVER is immediately initiated. This job sits in a timed-wait state
(WRKACTJOB will show it in TIMW status) most of the time, as the program it runs is waiting to
receive requests for new TCP/IP sockets (conversations). That program is the daemon,
and it is called EXSERV.
We could have chosen to use the standard communications subsystem to implement
this technique. However, this has the following drawbacks:
□ We would have had to modify your subsystem description to add an auto-start
job entry.
□ Any characteristics of the QCMN subsystem would also apply to EXODUS55 jobs.
This would make it difficult to control things such as job priority, timeslice, and
memory allocation.
□ EXODUS55 jobs would be intermingled with other communications jobs.
By having a separate subsystem, you can easily control when the subsystem is active, in
addition to setting job priorities, etc.

- 366 -
Installing TCP/IP Protocol Support
Catapult uses TCP/IP to connect to the IBM i. In order to use a TCP/IP connection, you
must have TCP/IP configured on your host IBM i. You will also need to know the IP
address for each IBM i you are going to connect to.
Catapult uses a middleware component called EXODUS55 for communications between the
server and client components of the software. EXODUS55 is normally configured
automatically during the install, but you can also configure it afterwards using the
instructions in this appendix. Before configuring Catapult you must have already
configured TCP/IP support for your IBM i using the commands provided by IBM. Contact
your system administrator to determine if TCP/IP services are already active.

If you already have EXODUS55 installed and are using

TCP/IP, then you don’t need to do this.

Manually Configuring the IBM i for TCP/IP Support

If EXODUS55 was not automatically configured correctly during the install you can follow the
steps below to do this. Please refer to the section “Security Considerations” on page 371
for a thorough discussion of how EXODUS55 works with IBM i security.
Here are the steps to configure EXODUS55:
1. Sign on as QSECOFR
2. Determine your current IBM i Local IP address. To do this, type the command
CFGTCP, press Enter. When the menu appears, type option 1= Work With
TCP/IP Interfaces. This will present a list of IP addresses for the system. Write
down the IP address you want to use with EXODUS55. You will need to enter
it in step 5 below.
3. Add XL_EX55 to your library list.
4. Type the command name ZCFGTCP, and press F4.
5. Type the local IP address, determined using step 2, for the Host IBM i for the
parameter IP. You can leave the other parameters at their default values.
The ZCFGTCP command will configure EXODUS55 for using TCP/IP on your system, and
also start the EXODUS55 subsystem.

How the EXODUS55 Subsystem Works

Once TCP/IP is running (using the STRTCP command), you must start the EXODUS55
subsystem, using the STRSBS XL_EX55/EXODUS55 command. Starting the subsystem initiates
an autostart job which causes the daemon EXSERV to run. Once a request for a
conversation is received, EXSERV takes the request and evokes another program, called
EXSPAWN, thus creating a new job. A request for a conversation happens when the user

- 367 -
runs Catapult on the PC and clicks on the IBM i icon to connect. If you run a WRKACTJOB or
WRKSBSJOB EXODUS55 command at this point you will see 2 jobs on the list: the daemon job
(EXSERVER) and the spawned job (EXSPAWN). Once the user ends the conversation (for
example, by exiting the Catapult Console or Catapult Poller), the EXSPAWN job will end. This
frees up the TCP/IP socket used by this job, so that other jobs can use the socket.

EXODUS55 Subsystem OS/400 Objects

The EXODUS55 subsystem uses the objects created by the following commands:
CRTUSRPRF USRPRF(EXODUS55) PASSWORD(*NONE) PWDEXP(*NO) INLMNU(*SIGNOFF) TEXT('EXODUS
TCP/IP DAEMON USER PROFILE') JOBD(QGPL/QDFTJOBD)

CRTJOBQ JOBQ(&LIB/EXODUS) TEXT('Exodus Job queue') AUTCHK(*DTAAUT)

CRTJOBD JOBD(&LIB/EXODUS) JOBQ(&LIB/EXODUS) TEXT('Exodus Job description') USER

(EXODUS55) RTGDTA(EXODUS55) RQSDTA('call exserv')

CRTCLS CLS(&LIB/EXSERVER) RUNPTY(20) PURGE(*NO) TEXT('Exodus TCP/IP Server Class')

CRTSBSD SBSD(&LIB/EXODUS55) POOLS((1 *BASE)) TEXT('Exodus TCP/IP Server Subsystem')

ADDRTGE SBSD(&LIB/EXODUS55) SEQNBR(1) CMPVAL('EXODUS55') PGM(&LIB/EXSERV) CLS

(&LIB/EXSERVER)

ADDAJE SBSD(&LIB/EXODUS55) JOB(EXSERV) JOBD(&LIB/EXODUS)

ADDJOBQE SBSD(&LIB/EXODUS55) JOBQ(&LIB/EXODUS)

If you are unsure of how the relationship between these objects works, please refer to
the IBM Manual, OS/400 Work Management, SC41-4306-01.

- 368 -
Configuration Options for TCP/IP
There are IBM i commands included in the EXODUS55 library for additional configuration
options when using TCP/IP. There is the command ZCFGTCP, used to configure TCP/IP
communications. Additionally, the command ZDSPERRLOG can be used to review connection
requests. Refer to the section “Security Considerations” on page 371 for details about
the Default User ID and security considerations.

The ZCFGTCP (Configure TCP/IP) Command

The ZCFGTCP command has parameters for defining the Local IP address, the socket
number (port) for incoming connections, the number of allowed pending connections,
and an option to log those connection attempts to a log file. Here is an example of the
parameters on this command:
Local IP Address . . . . . . . . IP '192.168.0.128'
Port for incoming connections . PORT 04015
Allowed pending connections . . PENDLIM 0100
Log Incoming Connections . . . . LOGCONN *YES
Create Exodus TCP/IP Objects . . CRTTCPOBJS *NO

Local IP Address
The Local IP address should already have been specified, as described in the Installation
Instructions.

Port for Incoming Connections

The Port for incoming connections is used to specify the socket number that incoming
connections will connect to. Generally, you should not have to change the default value
of 2015.

Allowed Pending Connections

The Allowed pending connections parameter is used to specify the maximum number of
pending (not active) connections that can be accepted by the EXODUS55 TCP/IP
daemon program. Note that the number specified here applies only to pending
connections. Since a pending connection quickly becomes active once it is transferred to
a spawned job, a limit of 100 should be more than enough for most installations.

Log Incoming Connections

The Log Incoming Connections parameter, when set to *YES, causes all attempts to
connect to the EXODUS55 TCP/IP daemon to be logged to a database file called EXLOGF in
XL_EX55. This file logs the User, date, time and evoked program of connection attempts. It
also logs run-time connection errors, including an error code and text. Use a value of
*NO for this parameter to generate no log entries.
You can review connection attempts using the command ZDSPERRLOG.

Create EXODUS55 TCP/IP Objects

- 369 -
 Set this option to *YES to create the EXODUS55 user profile, device description,
subsystem, and other EXODUS55 TCP/IP objects. You shouldn't have to run this
command with *YES for this option after your initial configuration.

The ZDSPERRLOG (Display Error Log) Command

Use ZDSPERRLOG to display information about connection requests (whether in error or not).
This is useful if you have a particular user that is not able to connect to the IBM i, or you
may also be asked by the Support Team to run this command to verify connections.

- 370 -
Security Considerations
We have designed the EXODUS55 TCP/IP implementation to be as secure as possible,
by taking advantage of the standard security features of OS/400. This section explains
steps we have taken to secure all the components to prevent unauthorized access to
your IBM i.
The daemon job runs under the EXODUS55 user profile, which is created with INLMNU
(*SIGNOFF), which prevents any interactive jobs being run with this user profile. It has
*ALLOBJ authority, which is required by OS/400 for sharing sockets between jobs. The
spawned jobs adopt the User Profile specified on the User name and Password prompt
on the sign-on window on the PC. This sign-on window appears once per client session.
For example, if the user runs either the console or the poller, this box appears. The User
Profile and password must match a valid OS/400 user profile (and password). This
information is encrypted on the PC prior to being sent across the network to the host IBM
i, thus minimizing the likelihood that anyone could steal a password with a sniffer
program.
The User ID and password are stored, unencrypted, in a User Space called EXODUS55_U.
Only QSECOFR and EXODUS55 user profiles are authorized to access this User Space. Since
user profile EXODUS55 cannot be used by any job other than those invoked via a
communications job, there is no security exposure here.
You can also specify that EXODUS55 will log all connection attempts, by running the
configuration command ZCFGTCP, specifying LOG(*YES). This causes EXODUS55 to record
the User ID, date and time of the connection request in addition to which IBM i program
was invoked by the request. The data is stored in a file called EXLOGF in XL_EX55. It also
contains error messages, which are recorded as they occur.

- 371 -
 - Rich Text Formatting Options Reference

APPENDIX B

Appendix B - Rich Text Formatting

Options Reference
Catapult’s Rich Text Formatting tags are provided as a technique that you can use to
make report text bold or underlined, or change the font of a particular report section. In
order to use these features, your Catapult grab rule must be set to download the report
in *RICH format. These tags are then applied irrespective of whether or not you add
further formatting overrides to your report via the Page Setup tab of your grab rule.

About the Rich Text Formatting Tags

To support these features, Catapult uses a tag syntax similar to Rich Text Format and
HTML. The syntax is specific and case sensitive. We have tried to create the tags using
character combinations that should not conflict with report data.

Tag Syntax
A Rich Format Tag always begins with an open parenthesis followed by a single quote.
Similarly, a tag always ends with a single quote followed by closing parenthesis.
Here are the Catapult Rich Format Tags:
Tag Description
{'Us'} Underline start
{'Ue'} Underline end
{'Bs'} Bold start
{'Be'} Bold end
{'Fs"font name" "font size" "char spacing
Font start
[optional]" "leading[optional]"'}
{'Fe'} Font end

Due to the use of the single quotes in these tags, when you add them to your A or O
specs, you need to add an additional ‘escape’ single quote before each of them. In
addition, because these tags are added to the body of your report as text strings, you will
need an additional set of single quotes surrounding your tag.
Thus, the following raw font tag, to convert a text string to Arial 12 point text:
{'Fs"Arial" "12"'}

- 372 -
in your DDS will look like this:
0007.00 A 10'{''Fs"Arial" "12"''}'

Your source member may be set to allow only upper case characters. If this is the case,
press F13 to adjust your editing options to allow lower case entry.

Font Tag Parameters

Here are descriptions of the font name parameters:
Font Name is the exact Windows name of the font that you would like to use. This name
can be found using the font dropdown box within Catapult when defining a rule, from
within a word processor, or by retrieving the name from the properties of the font itself
using the Windows Control Panel/Fonts application. The font name must be enclosed in
double quotation marks, since it may be multiple words.

The Catapult Font start tag supports any TrueType font

(including bar code fonts) installed on the poller PC at the
time when the poller is first launched [if you install fonts while
the poller is running, you should restart it]. If you aren’t
certain whether your recipients will have the font you use,
then you can take advantage of the Embed TrueType fonts
option, in your grab rule Page Setup options.

Font Size is the size to create the font. This value must be enclosed in double quotation
marks, and separated from the font name value by one or more spaces. Be aware that
the larger your font size, the greater the impact on the format of the rest of your report.
Char Spacing is the spacing between characters. Normally this will be zero (0). If you
need to add space between characters, use a positive number. If you need to remove
space between characters use a negative number. This value is optional and defaults to
zero (0) if not specified.
Leading is the vertical distance between lines of text. Normally this value would be
equivalent to "font size". Set it to a value larger than "font size" to increase the vertical
spacing, and smaller to decrease vertical spacing. This value is optional, but can only be
included if "char spacing" is also included (which may be zero (0) if not required).
Also note the ending single quote for the font start tag.

Considerations
There are a few things you need to take into consideration when using these tags in your
reports:
1. Rich Format Tags can be placed anywhere in your report. A Rich Format Tag
does not take up physical space in your finished report, when converted to
PDF, RTF or HTML. However if you view the report from Work with Spool Files
(WRKSPLF) the tags are visible.
2. In order to use the Font Start tag, you may need to adjust the width of your
report and also Override Printer File (OVRPRTF) to create a report wide enough

- 373 -
 to contain the Rich Format Tags in addition to your report data. This should
not cause any problems, since the finished width of the report is not changing.
Additionally you may need to adjust your grab rule to set the page size,
margins and orientation.
3. A Rich Format Tag must be completely contained on a single line. This does
not mean that a font attribute cannot span multiple lines, rather that the tag
itself must not be broken across lines.
For additional considerations, review the examples on the following pages.

An Example Using Rich Text Formatting Tags

To illustrate how this feature works, let’s work through an example.

Step 1: Choose a Report

Here is an illustration of the spool file for a simple inventory items report:

Figure B-1. An IBM i report to be distributed with Catapult.

We are using an external printer file with this report, but there is no additional formatting
associated with it on the IBM i.

Step 2: Create a Catapult Grab Rule to Download the Report

To begin, we will create a simple rule that merely emails the report in *RTF format. The
first time this rule is executed, it creates a report similar to this one:

- 374 -
Figure B-2. The IBM i report distributed as a simple RTF file, as displayed in Word®.
This report has been downloaded in *FILE format (to include blank lines), but with no
additional conversion or formatting options.
For this example, we will add some Rich Text formatting elements to the heading and
subtotal lines.

Step 3: Open the report source file and set it to allow lower case entry.
In this example we will make the changes to the DDS for this report’s external printer file.
You may also have your report output in O specs within an RPG program. But in both
cases, you need to press F13 to confirm that the option ‘Uppercase input only’ is set to
‘N’. The RTF formatting tags include lower case characters, and are case sensitive.
Once you have confirmed that this option is set correctly, you are ready to begin making
your changes.

Step 4: Locate the text string to format.

- 375 -
In our report, the first element we want to format is the report heading. In our particular
report, the heading is a text string (as opposed to a field):

The text heading begins in position 29 (see line 7). However, notice that this line also has
a 6-position system date field beginning in column 1 (line 10), with an edit code of Y.
The reason this is relevant is that when we insert the RTF tags into our reports, as far as
the IBM i is concerned, the tags are actual report text, occupying space on our report. If
we are simply underlining or bolding a field, we only need about 8 spaces in which to
insert the tag, but a typical font override can occupy up to 20 spaces on the report.

Step 5: Add the opening RTF tag to the left of the text string.
If you are familiar with HTML, these RTF tags work in a similar way: you need to have
start and end tags delimiting the text to be formatted.
For this example, we are going to change the program title to Arial 12 point. To do this,
we need to insert a line above line 7:

A later section below lists the available tags and their requirements. The core tag itself is
this: {'Fs"Arial" "12"'}, but we have to add extra single quotes at the beginning and end
of the string (because this is a text string added to the report), and before the single
quotes (to escape them). We are placing this text on column 10, after the date field.
The starting position of the printed output is the starting position of the {'Fs'} tag.

Step 6: Add the closing RTF tag after the text string.
Now we also need to add a tag to end the font change. Our program title starts at column
29, and is 22 characters long, so by placing the tag in column 55 we can avoid overlaps:

- 376 -
Here we have added line 7.01 where the base tag is {'Fe'}, and with the same extra
single quotes as we needed on line 6.01.

Step 7: Save and compile your changes.

Exit the member and save your changes. Then recompile your program or printer file.
Now when you run your report the top of the spool file looks like this on the IBM i:

Figure B-3. The IBM i report with embedded RTF tags, as seen via WRKSPLF.
Step 8: Adjust your rule to download in *RICH format.
Open your grab rule and go to the Spool File Acquisition options. In the Download
Formatting section, change the Spool File Format option to *RICH - Include rich text
formatting. Save your rule.

Step 9: Run your report again.

Run your report again, and wait for Catapult to download it. This time, the heading looks
something like this:

- 377 -
Figure B-4. The RTF tags reflected in the final report layout.
As you can see, the formatting change worked, but has introduced a couple of new
problems:
□ Because the word processor interprets the inserted tags, rather than just
including them in the document as text, the 20 spaces occupied by the tag have
disappeared from our report. To address this issue we can move our title further
to the right to compensate for the vanished spaces. Another alternative would be
to reformat the report a little more extensively, such as moving the title to a line of
it’s own.
□ And because RTF files don’t handle mid-line formatting changes all that
gracefully, the page number has skipped down to the next line. As you’ll see in
an illustration below, if we create a grab rule that generates a PDF file instead of
an RTF, this doesn’t happen.
In any case, both of these issues can be handled by tweaking our report source.

Step 10: Adding bolding and underlining.

To further enhance this report we will make the Category Group subtotal line bold, and
underline the Inventory Category subtotal line.
The changes we made are on lines 51.01, 52.01, 58.01 and 59.01, below:

- 378 -
After adding the bold and underline start and end tags at appropriate locations, we also
adjusted the locations of the subtotal line’s text and fields to accommodate the insertion.
When we save these changes and recompile, the results look like this (this time using a
generated PDF to illustrate the results):

- 379 -
Figure B-5. The final report, with RTF tags and additional formatting adjustments.
In this illustration we have also made a few more adjustments to the process, both to the
Catapult grab rule and the report source on the IBM i.
The main formatting issues revolve around addressing the vacuum created by having
some of our report text interpreted rather than rendered. To addresses this, in this report
we moved our text and fields quite far to the right, apparently beyond the actual report
width.
For example, here is how we set up the subtotal lines:

Notice that the subtotal fields (lines 55 and 64) are in column 76, and that the end tags
(lines 53 and 62) are in column 90. Though our actual report is only 80 characters wide,
this still works because the space occupied by the tags isn’t counted.
In addition to the changes to the source, we also took advantage of features in our
Catapult grab rule to override the report page attributes, by adjusting our margins and
font sizes to make the report fit the page better.

Summary
Because every report is different, there is no single solution to the layout issues created
by adding formatting tags to your report body. In general, you will need to first adjust your
report to fit your tags in where you need them, and afterwards do some additional
tweaking to make everything line up again once you have gauged the results in the
generated PDF, RTF or HTML file.
Based on this example, here are some recommendations, and items to take note of:
1. Formatting start and end tags can be on different lines. This means that if you
are intending to change the font for an entire line or section of your report, the
easiest way to do this may be to add new lines to your report source, above
and below the section to be formatted, and put your formatting tags on those
lines.
2. If the formatting tags are included in the text of your PDF, RTF or HTML
report, rather than applied to the text, check that you have the right number of

- 380 -
 quotes, that you are using the right case for the tags, and that the tags aren’t
partially overlapping fields or text strings.
3. You can convert text to any True Type font available on the poller machine.
4. Whether or not you override the page layout in your Catapult grab rule does
NOT affect how the formatting tags are processed.
The next section describes each of the formatting options in detail, and includes some
additional considerations.

Using Bar Code Fonts in Rich Text Format Tags

If you intend to use bar codes in your reports, here is an example of how you could
format the font tag:
{'Fs"Abri Barcode39a" "14" "1" "20"'}*23434*{'Fe'}

The example above includes the Font Start tag and the font name, followed by the font
size, character spacing and leading. The bar code value itself is enclosed in asterisks, as
this is required by some bar code scanners. Finally, a Font End tag is added.
Several bar code fonts are included with the Catapult Poller for embedding in the PDF,
RTF and HTML documents you create. The fonts included are:
□ Abri Barcode39
□ Abri Barcode39a - a version with alpha letters below the code.
□ Abri Barcode39N - this is a narrow version of the font.
□ Abri Barcode39Na - narrow version with alpha letters below the code.
□ Abri Barcode39W - wide version.
□ Abri Barcode39Wa - wide with alpha letters below.
You can use any of these fonts in your documents, using the format illustrated above.

Example Report Implementing a RTF Barcode Font Tag

The following example assumes that you have reviewed the first example of using Rich
Text Format tags, beginning on page 374 above.
Here is the DDS for the Detail format of a customer listing report, where we are going to
display the customer telephone number as a barcode:

- 381 -
In this example, the detail line includes the customer number, a shortened customer
name, and the phone number.
The first challenge is to arrange the report line so the required formatting text can be
inserted into the spooled report. We have done this by shortening the customer name
field and moving the phone number field towards the right. In the intervening space, we
inserted the bar code font tag, ending in an asterisk (some bar code readers require the
value to start and end with an asterisk).
Immediately following the phone number field we included another asterisk and ended
the Font tag.
When we run this report and view it on the IBM i, the spool file looks like this:

Figure B-6. A report with bar codes embedded via RTF tags.
Notice how the required tags and asterisks fit exactly around the phone number field.

- 382 -
After creating a Catapult grab rule to download this report (and remembering to specify
*RICH as the download format), the generated PDF looks like this:

Figure B-7. The report produced by Catapult, using embedded bar code font tags.
As with our other example, the next step here is to further adjust the formatting, both in
the report DDS and in the Catapult grab rule. For example, the column headings can be
re-aligned with the data (in the DDS), and the space on the page could be used more
effectively (by overriding the PDF page layout options in the grab rule).

- 383 -
 - Catapult Troubleshooting Guide

APPENDIX C

Appendix C - Catapult Troubleshooting Guide

This section includes a trouble-shooting guide for determining why different aspects of
your Catapult processes aren’t working. A summary list of things to check is included in
the section “Basic Troubleshooting Techniques” on page 97. That section also includes
an overview of some of the authority ‘teething’ issues that you may run into as you’re first
setting up Catapult, with links to other useful sections of the guide.

This chapter hasn’t been completely revised for Catapult 7. If

are having trouble with any of the instructions, for areas of the
product that may have changed, please call Technical
Support.

The first section below includes some of the most commonly encountered errors, and the
rest of this section systematically works through other areas where you can run into
difficulties.

- 384 -
Checking the Error Logs
All Catapult log files are stored in the same location. You can get to them via the
Launchpad option Log and Configuration Files or via the Console’s Help menu.
You can also get to this location manually. These files live at:
□ Windows XP. C:\Documents and Settings\All Users\Application
Data\ESDI\Catapult\Logs
□ Windows Vista/7. C:\ProgramData\ESDI\Catapult\Logs
Below is a summary of what you’ll find in the log files.

EXODUS55 Logs
These are the files in the subfolder named Logs. Within this folder, each EXODUS55
connection" will have its own set of log files.
They are structured based on the Domain/IP of the IBM i box, then the Library. Here is an
illustration of how this could look:

Figure C-1. EXODUS55 log files.

By default the log files only include errors encountered while communicating with the IBM
i. If you need additional detail in the log files, go to the Communications Configuration
and turn on "Include informational messages in Log" for that connection. If you change
this setting, you need to end and restart the Catapult Poller for that environment.
The file perror.log is a trace log that by default includes details about when requests are
created and finished, as well as any errors. If you need to see additional detail about the
errors you are running into, you need to enable Debug Mode in the Poller Configuration
(see the section “Poller Diagnostic Settings” on page 361 ). If you make this change,
you’ll also need to end and restart the poller for this environment.

Exception Reports

- 385 -
When one of the Catapult PC components crashes, you’ll typically get an Exception
window that pops up, informing you that the software has died, with a somewhat cryptic
message as to the cause.
When this happens, you’ll be able to find a report of this error in the Logs folder, with a
datetime stamp and an extension of .err. You can forward these files to Technical
Support. Ideally, you should clear the files after doing this, so they don’t build up over
time, and it’s easier to find the most recent ones.

- 386 -
General PC Connection Errors
Some common errors that occur when you attempt to connect with a PC job are:
□ ‘Connection Refused’ Errors. These generally indicate in invalid or incorrect
user name and password.
□ 10061 or 10057 Errors. These usually refer to a slow or unexpected response
from the IBM i. Verify that the EXODUS55 subsystem is up and running, and that
the IP address and Port numbers in your PC communications configuration
match what is set on the ZCFGTCP command on the IBM i.
□ 10035 errors. This is a generic timeout message that can occur for any number
of reasons. Check the IBM i jobs for messages.
□ 10053 error. Software caused connection abort. An established connection was
aborted by the software in your host machine, possibly due to a data
transmission timeout or protocol error. This error message is usually
accompanied by the text: Mailer: Error connecting to mail server. Socket Error #
10053. If you are running security software like McAfee's VirusScan Enterprise
8.0 on your poller PC you may receive this error in Catapult's request and errors
list when the poller tries to email your spool files. Once this is turned off or added
as a trusted source this will correct the error. The specific portion of VirusScan
Enterprise 8.0 is a rule meant to prevent worms from mass emailing from this
location. You can turn off that rule and leave the rest alone.
Here is a Link to a web page that includes information on this problem:
http://www.networkassociates.com/common/media/mcafeeb2b
/support/VSE/VSE80i_ProductGuide_EN.pdf.

Rebooting the PC and restarting EXODUS55 is also known to have worked in

certain situations.
□ 10051 Network is Unreachable Error. A socket operation was attempted to an
unreachable network.This usually means the local software knows no route to
reach the remote host. This is either the network path to the IBM i or to the mail
Server. Check that your mail server is up and running and that it can relay e-
mails as a trusted e-mail source.
The following sections discuss other errors off the PC.

- 387 -
When Catapult won’t Connect to the IBM i
Below are some general instructions on what to do if you run into problems with any of
the Catapult components when you attempt to connect to the IBM i. The next section
below describes a detailed, step by step process for isolating and addressing
communications problems.
In order for the Catapult Poller or Console to connect to the IBM i (to poll the IBM i or
maintain grab rules), the EXODUS55 subsystem needs to be running on the IBM i. In the
subsystem there should also be at least one job running called EXSERVER, in TIMW status.
If the EXSERVER job is not running, do the following:
□ End and restart the EXODUS55 subsystem.
□ Then check whether EXSERVER is there when the subsystem starts up again.
□ If it isn't, run the WRKSPLF EXODUS55 command and see if there is a joblog under that
user profile that indicates why the EXSERVER job didn't start successfully or was
ended abnormally. The most likely causes for this are:
● That the ZCFGTCP command has not been executed to configure Catapult for
TCP/IP.
● TCP/IP services are not running on the IBM i.
● EXODUS55 was unable to allocate the port for incoming communications.
If the Catapult Console connects fine, but the poller will not, the most likely causes are:
□ The security code for Catapult is invalid, or has expired.
If you need a new code, you can call Fresche Solutions at (630) 986-0800, or the
Technical Support team at (800) 258-3399, or (508) 594-2700. You can also
reach us by email at support@freschesolutions.com. You can confirm this by
checking the poller Log entry in the file perror.log, stored in the Catapult Poller
directory on the poller PC. Look for an entry referencing either an invalid or
expired security code.
□ Also check for Administrator email from Catapult. This is how Catapult
communicates all non-email related problems.
□ The poller has been ended abnormally on the PC and orphaned a job on the IBM
i. If this is the case, go the section below on troubleshooting fatal poller errors.
Look for entries saying the poller is locked. An administrator mail will also be
issued in this case.
If you continue to have problems with the Catapult Poller, check the file PERROR.LOG
on the poller PC. You can find this by right-clicking the Catapult Launchpad and selecting
the Documentation/Log and Configuration files option. In the window that opens, select
the Logs folder.
When the IBM i portion of Catapult encounters an error it generates a spool file under the
profile of the user that starts the console or poller. You can identify these spool files
based on user data: they will have SP_MSRVx (for console errors, SP_PSRVx/SP_
QSRVx (for poller errors), or SP_CSRV (for errors in the poller configuration utility).

- 388 -
 You shouldn’t normally have any of these spool files, but something you can do to
monitor for issues is create grab rules that email any of these files to the Catapult admin
(if they get created).

Detailed Communications Troubleshooting Process

Below is a detailed set of instructions that should allow you to isolate and identify the
nature of any communications problems you may be having, with getting the Catapult
Console or poller connected to the IBM i.
The typical errors you may get when attempting to connect are a 'Connection refused'
error, or a '10061' error, or some other communications error. These errors can be
caused by many different factors.
Here is a suggested pathway for getting to the bottom of your communications errors:

Have you Just Upgraded to a New Release?

If you have recently upgraded to a current release from any earlier version, and you
have one or more PCs where the console or poller won’t connect and just returns a
timeout, you should verify that you have upgraded all components to the latest release,
and aren’t running an older version, either on the IBM i or one of the PCs. The PC release
can be checked at the Help/About screen for the console, and you can display the
current server side release by running this command on the IBM i: DSPDTAARA XL_
CATAPLT/SP_CATAPLT.

Check your Basic Communications Configuration

Start by verifying that the basic communications configuration for the software has been
set up correctly. This is described in detail in Chapter 2, but you can do a quick check of
the basics as follows:
□ On your PC, right-click the Launchpad and select the
Configuration/Communications option. Check that your connections have the
right IBM i IP address listed. If not, review the configuration instructions in the
section “Step 5: Configure Communications on Each PC and Log In” on
page 45 
□ Make sure that you verify the IP address and Port you have selected, and that it
is the same IP that you used when configuring the Catapult IBM i component. We
recommend that you leave the default port setting of 2015 (unless you are at
V6R1 or higher, in which case we recommend 4015), but any port number above
1024 that is not currently in use should work.
□ If the IP address and Port match in the above step do not match, run the CFGTCP
command on the IBM i, then take an Option 1.
If your basic communications configuration looks good, continue below.

Check the Status of the Critical Jobs on the IBM i.

Sign on to an IBM i session, if possible as QSECOFR, and run the WRKACTJOB command.
1. Is the EXODUS55 subsystem running?

- 389 -
 ● If not, you need to run the STRSBS XL_EX55/EXODUS55 command to start the
subsystem.
● However, if you have just finished installing, the subsystem should have
been started automatically on completion of the install, so you may have run
into a problem there (check the joblog of your interactive session to see if
there are any relevant messages there).
● If the subsystem starts when you run the command, try connecting with
Catapult again.
● If the subsystem doesn’t start, or you get a message that it isn’t found, then
you may not have installed the server component of Catapult. Review the
installation instructions and check for the libraries XL_CATAPLT and XL_EX55
using the WRKLIB command.
● If the libraries exist, try running the XL_EX55/ZCFGTCP command (with QSECOFR),
and select *YES for the option to Create EXODUS55 TCP/IP objects, then
try starting the subsystem again.
● If on starting the subsystem, you got a different error (other than the
necessary objects not being found), then try and find as many details of the
error as possible, and if you’re not sure what the error means, contact
Technical Support.
2. If (and when) the subsystem has started, is there a job in the subsystem
called EXSERVER, in TIMW status?
● If not, try ending and restarting the subsystem. When you restart it, monitor
WRKACTJOB to see if EXSERVER starts and then ends, or if it never starts at all.
Make a note of this to relay to Tech Support.
● In either case, do a WRKSPLF EXODUS55 to see if there are any EXODUS55 joblogs
with a user data of EXSERVER job ending. You may also find messages listed
from the WRKACTJOB screen by taking an option 5, then 10, on the EXODUS55
subsystem, and check the joblog for relevant messages.
● If you aren’t sure how to interpret the joblog or the messages you find, make
a note of them and contact Tech Support.
3. If the subsystem is started, and the EXSERVER job is in TIMW status, are there any
other jobs named EXODUS55 under either the EXODUS55 or QCMN subsystems?
● If there are, what is their status? Are they in message wait state (MSGW)?
● If an EXODUS55 job is in MSGW, take an option 7 beside the job to display the
message, and press F9 for message details.
Record the last few message IDs and contact Fresche Solutions Technical Support.

Check the Error Log File

If there are no jobs in QCMN that are in MSGW, you can check the error log file for connection
attempt details. Each connection to the IBM i will log a record with the following
information:
□ The connection date and time.
□ The user who made the connection.

- 390 -
 □ The program that made the connection (several Fresche Solutions products
share EXODUS55).
□ The message text.
This information should point you towards a solution to your problem.

Obtaining and Using the Error Log

Use the command ZDSPERRLOG in XL_EX55 will display the log file.
□ Run this command and check for recent messages. The records will show the
user, so you should be able to determine if they are relevant.
□ Record the error information and contact Fresche Solutions Technical Support.
Some errors are relatively obvious; for example, the most common is an 83 1A
error, which indicates that an incorrect user profile or password was used.
□ If you see a message with a text of ‘connection request’, but no errors, then
check the spool files for the job. For the user profile making the connection, see if
there is an EXODUS55 joblog. If no joblog exists, check to see that the user profile
has messaging set to *SECLVL, and try connecting again.

Troubleshooting Fatal Catapult Poller Errors

If you are experiencing errors that cause the PC-side poller job to fail, the most likely
cause of your errors is a problem with how one of your rules is configured. To test to see
if a grab rule is causing the poller to end abnormally:
□ Set all your rules to be inactive (if this is practical). If the poller has been running
fine for a long time, and you have lots of rules, you can start by inactivating any
recently created or modified ones.
□ From the console click on the Tools menu, select ‘Request Browsing’, and delete
any entries in this list. Make special note of any entry flagged as ‘Active’, as this
entry in the list is usually the last one that was being processed at the time the
error occurred, and therefore the likely cause of the problem. Make a note of the
grab rule number for this request.
□ Verify that the poller job is not still running on the IBM i. To verify if the poller is
running, do this:
● Run the WRKACTJOB command.
● Check the EXODUS55 and QCMN subsystems for jobs called EXODUS55.
● Check the Call Stack of all these jobs for a job called SP_PSRV (you can get to
the call stack via option 5, then 11).
● If you find a job that has this, end it *IMMED.
● Also look for a job with SP_QSRV in the call stack, and end this one also.
□ Start the Catapult Poller.
□ If the poller starts with no errors, activate a rule and trigger an immediate poll.
Continue activating rules and triggering polling cycles until the error recurs.
□ Once you have identified the grab rule causing the error, print the rule, and
contact Fresche Solutions Technical Support for assistance.

- 391 -
General IBM i Connection Errors:
Some common IBM i connection errors that can occur are:
□ RNQ0202 errors. These may be related to Catapult attempting to add a library to
your library list that is already there. If you have added XL_EX55 or XL_CATAPLT to
your system library list, it’s possible that you may encounter this problem. This is
addressed by Catapult in later releases of the software.
□ The RNQ0202 error may also occur if your library list is full, and Catapult isn’t able to
add its libraries to your library list.

- 392 -
What to Do When a Grab Rule Doesn't Grab
You've created a Grab rule which should email a report to a specific person, but the user
doesn't receive any email. Some possible reasons are described below.

1. The selection criteria is incorrect.

Sometimes the selection criteria is incorrect by being too specific - for example including
the User ID, but having a different user run the report. In order to determine whether
your selection criteria is correct do the following:
□ Open your Grab rule, go to the Acquisition settings and click the Locate... button
(for spool files).
□ In the Preview Spool Files window check whether there are any spool files that
match your selection.
□ When the list of spool files is loaded click on the entry that you want selected by
Catapult. Check it carefully against the selection criteria on the Selection tab. If
there is any doubt, you can click on the Select Filter and/or the Select File buttons
in the preview window. This will fill in the selection values of your grab rule.

If you click the Select File button, it fills in all the selection
criteria fields in the Spool File Attributes box on the Selection
tab. Potentially this could be too specific, especially with regard
to User Id and Job Name.

2. The queue is not selected for polling.

To check this, launch the poller Configuration and check the queues tab to see whether
the required queue has been deselected.

3. The email address is incorrect.

In order to determine whether the email address will work, try the following:
□ Go to the poller configuration and on the Admin tab, check the option to ‘notify on
any error’, and enter your email address.
□ Send an email to that person using an email client such as Outlook Express or
Eudora. Send the email from the Catapult Poller PC.
□ If the email client can send email, check that the IP address and port that
Catapult Poller is configured to use match the settings for the email client.
□ Check your email server. There will probably be logs that tell you information
about activity.
□ Sometimes email servers will 'swallow' misaddressed email, depending on the
settings on the email server. Often times, however, mail with the correct domain
name, but unknown address will be forwarded to a postmaster account. Check
this email account, or consult your network administrator.
□ Look for messages that show an email as being rejected, and why. Some email
servers validate that the originating IP address is allowed to send email through

- 393 -
 it. Some email servers validate on User ID. Some email servers validate on the
From Address. Catapult Poller defaults the From Address to be
catapult@127.0.0.1 - you can change this in the poller Configuration.
□ If you have a firewall Catapult Poller may be able to send Intranet mail, but not
Internet mail. This is commonly an issue with the IP address or Port that Catapult
Poller is configured to use. Check your email server and your firewall for the
correct settings.
□ You may have more than one email server. For example, one for internal and
one for external email. Consult your network administrator for the proper
configuration settings.
Catapult works with SMTP email servers. There are many brands and versions of email
servers. We will try to help you with configuration issues, but our technical people will not
know everything relevant about your specific email server or network configuration, and
you may need to consult with your network administrator regarding configuration issues.

4. When some recipients are not receiving their files.

I have been using a grab rule successfully for some time, but for some reason one (or
more) email recipients are not receiving the file.
If this happens, check your grab rule to see whether you are compressing the spool file
and creating a self-extracting zip file (with an .exe extension). Many email servers
automatically reject email with executable attachments. You may be able to determine
this by checking the audit logs of the recipients email server to determine whether this is
the case. Or you can turn off the self-extract option.
The .exe files may be rejected by your SMTP server, the receiving persons SMTP server,
or even the anti-virus software installed on the client PC.
Another cause of email not getting through is because it exceeds a maximum size limit
set by the recipient. If this may be the case, try the following options:
□ Set the number of attachments to a lower number in the poller Config.
□ Compress the attachments, to reduce their overall size.

- 394 -
What to Do When a Split Doesn't Split
You've created a Grab rule that should split a report, but it doesn't seem to split the
report.
The first thing to confirm is that the spool file was downloaded from the IBM i. To check
this, do the following:
1. Turn off the splitting. Go to the Split tab and check off the Split Report check
box.
2. Go to the Download tab and check on the Archive check box. Specify a
directory in the Server Path. Use the browse button to ensure that your
directory structure is correct.
3. Go to the Email tab, and check on the Email report check box. Specify 'Email
Address', and type in your email address.
This will confirm three things:
□ The spool file selection criteria is correct.
□ The spool file is downloaded and saved correctly.
□ Your email configuration is correct and, Catapult is able to use your mail server
to send email.
Once the correct spool file is downloaded to the directory you specified and emailed to
you, move on to the next step. Use the History List to confirm that your spool file was
processed. Otherwise use the Error Request listing to determine why the report was not
download/emailed.
There are a number of reasons the split process wouldn't work. Here are some of the
common reasons:
□ It did split, but didn't email (if it was supposed to email the split sections).
□ It did split but the file name created was not unique (in the case of saving and not
emailing), so each new split section overwrote the last.
□ It didn't split at all, because the split criteria was not specified correctly (however,
a message will be issued to the Catapult Administrator in this case if the Notify
Administrator option is activated in the poller Configuration. See the section
“Email Administration Options: Error Notification” on page 350 .
To determine which of these scenarios might fit your situation, do the following:
1. Turn your Split back on. Go to the Split tab and check on the Split Report
check box.
2. Change the file name on the Download tab to be &n-&i-&k.txt. The &i will give
you an incrementing number so that any files will be uniquely named. The &k
will give you the key extracted from the report.
3. Run your report, to let Catapult process it. Use the History List to confirm that
your new spool file was processed. Also check the Request Errors listing to
determine if an error occurred.

A. If only one file was created, carefully check the following quick hit items:

- 395 -
Most of the time, if there has been a problem, one of the following has been specified
incorrectly. Verify each of the following settings:
Start Text, End Text and Key Anchor:
□ The text value is typed correctly. The text is case sensitive, and must match the
report text exactly.
□ The column and length are correct. The length must be the exact length of the
character text typed in; note that blanks count.
Key Location / Email Address Location:
□ Ensure that the Column, Length and Line offset are correct. Don’t let the line
offset fool you if you are downloading the report in *RPT format, but viewing the
file using WRKSPLF (where blank lines are stripped from the display). The safest
option is to download a preview in Catapult, and use that for counting offset lines.
Take note of the following:
□ If *STARTTEXT is used for End Text, the report will split when the Key value
changes. This allows multiple sections (i.e. pages) to belong to one split.
□ Key anchor text must be within the Start and End text. The splitting algorithm
looks for the Start text first, and once found, begins looking for the Key Anchor
and End text.
□ If the Start text specified is never encountered, no sections of the report will be
sent as unaddressed (because there were no split sections). This is a side effect
of the idea that the splits may not encompass the entire report. An example of
this would be to email the department summary pages to each department, but
not do anything with the department details that precede these sections.
□ Depending on the Format setting on the Download tab, the line offset for the
email address/key value could be incorrect. The *FILE option behaves like the
display option in WRKSPLF. If you download as *FILE, all blank lines are stripped
out, so what may be three lines down on the printed report will only be one line
down on the downloaded report. Alternately, what may appear to be on the next
line in WRKSPLF could be several lines down if you download with *RPT.
□ The minimum length of a split section is two lines. The key anchor can reside on
either the start or end line.

B. If more than one file was created it means that the split at least partially
worked.
Check the file names of the files created. The &k replacement value should contain either
the key value or the email address extracted from the report (depending on whether you
chose Report Text or Email Group for the Email Address Source).
If the &k value is blank, revisit the Key Location/Email Address location and correct as
required. Chances are pretty good that either the Column or Line Offset is incorrect.
If the &k is supposed to be an email address, but looks invalid, revisit the Email Address
Location on the Key Anchor/Location tab. Correct as necessary.

- 396 -
If the &k is a key to the distribution group, look carefully at the key extracted, and
compare this to the value in the group entry:
□ If the &k is not blank, but nothing got emailed it probably means that the key
value extracted did not match the key values specified in the group. In this case,
the administrator address for unassigned sections should be turned on, and that
address will probably receive the questionable sections. For example: if the key
value can range between 1 and 999 and is right justified, the key value in the
group entry must also be right justified: “  1”, “ 88”, “234”. For the sake of clarity in
your email entries, it is recommended that enclose values in double quotes.
□ Alternatively if the &k is not blank, and nothing got emailed, check that the email
address itself is correct. Sometimes email servers will 'swallow' mis-addressed
email, depending on the settings on the email server. Often times, however, mail
with the correct domain name, but unknown address will be forwarded to a
postmaster account. Check this email account.
If there are still questions about whether an email is being sent, watch the Polling Status
(View Polling Server Status button). It will show clearly the address and port that the split
is being sent to.

On occasion problems have been reported where local

email addresses work OK, but external email addresses do
not. This is invariably an email server setting. Sometimes the
email server is validating on IP address of the sending
machine, sometimes it is validating on the From address. In
other instances, there is more than one email server, and
you are connected to the wrong one. Check your email
server to determine the cause, or consult your network
administrator.

- 397 -
Troubleshooting Printing Issues
Catapult supports the ability to automatically print documents as part of your grab rule
processing. There are a number of unique situations that can arise when using this
functionality.

Confirming the Default Files Associations for RTF & PDF

If you are using Catapult to print documents which you are also converting to RTF or PDF
format, you may need to confirm that file associations exist on the poller PC for
documents with extensions of PDF and RTF.
To check this, select the Folder Options entry of the Tools menu in Windows Explorer. In
that window, select the File Types tab, shown here:

Figure C-2. Confirming the file associations for printed document formats.
Confirm the existence of a file association similar to the one shown above, and another
for RTF files (typically linked to Microsoft Word®).

Printing from Other Applications

In order to fully support printing from other applications, you need to confirm that the file
types you’ll be generating have a defined PRINTTO action (on the Catapult Poller PC).
To check this, click the Advanced button (shown near the bottom of ) and verify that the
action is included in this list:

- 398 -
Figure C-3. The printto action, shown for Adobe Acrobat (PDF) documents.
If the entry doesn’t exist, use the New... button to create it. Here is an illustration of the
printto action defined above:

Figure C-4. The printto action definition for Adobe PDF files.
If you have any trouble printing from Catapult or questions about how this needs to be
set up, please call Technical Support.

- 399 -
Troubleshooting Batch File Processing
Data Extraction’s batch files provide a powerful way for you to extract only specific
information from a report prior to distributing it. However, using a batch file introduces a
third party into an already complex process, so it can cause additional problems. Here
are some of the situations you might run into.

I'm trying to use a batch file, but it doesn't work.

Solution 1: Check the path to the batch file (.bat) file. Generally it should look something
like this:
C:\Program Files\ESDI\Catapult 7\autoscripts\myscript.bat

Solution 2: Confirm that the Input file is what the batch file is expecting the file to be.
Open up your batch file and check.
Solution 3: Confirm that the Output file that Catapult Poller expects to receive (the third
field on the screen) is what the batch file actually creates.

I'm trying to use batch files, but I keep getting errors that 'batch file processing
timed out.'
Solution 1: Increase the time out value. Use the poller Configuration/Data Extraction’s
tab to set this to a higher value. Catapult will wait for 10 minutes as a default, so put in a
value greater than 10.

I'm trying to use Batch Files, but I get an error that 'Batch File did not produce
expected output file.'
Solution 1: Check the Output file field on the Data Extraction's category. This should
match the value specified with in the actual batch file. Edit the batch file to confirm this.
Solution 2: The batch file actually did not create a file. Debug your batch file before you
attempt to use it in Catapult.

I'm trying to use a batch file, but I get an error 'Unable to rename file to A-S
input file name.'
Solution: Check that the path you have specified in the Input file field on the Data
Extraction’s tab is valid. Chances are good that the directory or filename is misspelled.
Another possibility is that you’re also saving the file to that location in your grab rule, and
then the poller can’t re-save when it tries to set things up for the batch file to run.

My rule is set up to split and run and Data Extraction’s batch file, but all my
users are getting the same attachment.
Solution: Turn on the check box ‘Rename Output File to Unique Name After Processing’.
Batch file processing does not support parameters for input and output file names.
Consequently the output file name of the batch file will always be identical. In earlier
versions of Catapult, this worked because each split section was mailed immediately.
Catapult 3.30 introduced threaded emailing, where the file is temporarily cached until the

- 400 -
email process catches up. Potentially the batch file process could run multiple times
before the email process catches up, and the file would be overwritten each time.

I’m getting the message “Error Starting Autoscript: the system cannot find the
path specified”.
Solution: This message it typically triggered by a change in the Catapult or Data
Extraction’s directory structure on your poller PC. If you have re-installed the Catapult
Poller, moved it to a new directory or machine, upgraded to a new release, or any other
change of this nature, then you should double-check the paths to the batch file, as well
as the input & output files in your Data Extraction's transformation options.

- 401 -
General Troubleshooting Issues
Here are some general gotchas that plague people on a regular basis.

I had a grab rule with an error, which I corrected. However, I still don’t get my
report.
When you run into a report distribution error, Catapult logs the error in the request listing.
If you correct the cause of the error, you need to re-activate that request, or delete the
error entry (both are right-click menu options on the request listings).
Otherwise, Catapult won’t look at that request again, because it doesn’t know that the
cause of the error has been corrected, so it assumes that there’s no point in re-
processing the report.

Catapult Poller was up and running successfully. Today when I started it up it

ended abnormally with a GPF type message and info about a Socket error in the
message box. I still can connect with the console program.
Solution: Has new software been installed on this pc? If the new software uses Port
8812 you will need to change the new software, or change the Catapult Poller. The
registry setting used to maintain which port is used is:
HKey_Local_Machine\Software\ESDI\Catapult\poller\ServerStatus\SocketPort.
Add or change this value to a different value. Generally you can choose a port greater
than 1024, but less than or equal to 65536.

Catapult Poller was up and running successfully. Today when I started it up it

ended abnormally with a GPF type message. I can still connect with the console
program.
Solution: Check whether any rules have changed or been added. If rules have been
added Inactivate them. Also go to the Requests List and remove any requests for that
rule. Restart your Catapult Poller. If the poller runs successfully the problem is related to
your new rule. Check your rule for invalid information. If you’re not sure which rule might
be causing the problem, inactivate all rules, then activate them one by one, over the
course of some time.
If the poller does ab end before completing processing for a request, the offending
request will be the entry flagged as ‘Active’ in the pending requests list. Use this entry to
determine which rule is causing the problem, and start by inactivating the rule, then
modifying it as required.

I'm getting a 'Download error:' with a CPF message in my Request Errors.

Solution: Check the CPF message for details, but generally it is caused by the spool file
being removed in the time between when the request was created and when the
requests get executed. Check for rules that get processed earlier than the rule in error
that might delete or move that spool file.

- 402 -
The console Server Status window shows ‘connected’ for a moment, then
changes to a poller not connected status.
This normally indicates that the PC side of the poller has crashed, leaving behind an
orphaned IBM i job. You will normally find this job in the EXODUS55 subsystem, with a
name of EXODUS55.

I have defined my Grab Rule to create a .PDF, .RTF or .HTML file but I get a
message in the Request Errors listing.
Solution: Check the error number here. You will need to contact Fresche Solutions
Technical Support for further help.
Error
Description
Code
1 Problem opening the input spool file
2 Problem opening the temporary file (output) for pass 1
3 Problem opening the temporary file (input) for pass 2
4 Problem opening the output PDF/RTF/HTML file
44 Image file 1 does not exist (for overlay)
45 Image file 2 does not exist (for overlay)
5 Problem automatically displaying the PDF/RTF/HTML file
6 Unable to allocate memory for RptLines structure
Unable to reallocate additional memory for RptLines
61
structure
69 Unable to deallocate memory used by RptLines structure
7 Unable to allocate memory for Objects structure
79 Unable to deallocate memory used by Objects structure
8 Unable to allocate memory for BookMarks structure
Unable to reallocate additional memory for BookMarks
81
structure
Unable to reallocate additional memory for BookMarks
82
structure
Unable to deallocate memory used by BookMarks
89
structure

My TIF files aren’t generating correctly.

If when you attempt to download a file in TIF format, you get an error on the IBM i. This
may be because you don’t have the requisite licenced programs installed. This is
described in more detail in the section “Creating TIF Files” on page 262.

I’m splitting a report and emailing the segments, and all of the recipients are get-
ting the same attachment (often, this is the entire report).

- 403 -
Solution: Usually this is caused by saving the split sections, but specifying ‘Overwrite
existing file(s)’ on the Save tab within the Parse/Split section of the grab rule.

My email process is running more slowly than I expect.

Solution: When Catapult connects to your mail server it defaults to waiting indefinitely for
the mail server to respond. If you mail server is some distance away, or on a WAN,
occasionally your network can drop TCP/IP packets. Use the poller Configuration/Email
tab to define a timeout value, and the number of times to attempt to contact the mail
server. Usually a 30 second timeout with three retries is a good setting to start with. If the
Catapult Poller cannot connect to the mail server the request is flagged in error and
processing continues.

My email doesn’t seem to be getting processed. I have lots of requests with a

status of ‘Email Pending’. When I end and restart the poller, one or more is pro-
cessed, then it just seems to hang again.
Solution: Check for message in the poller Error Log file relating to emailing. If there
doesn’t seem to be anything related, check the Email Settings in the poller Configuration.
If the Connection Timeout is set to ‘-1’, the poller will wait indefinitely for a response from
your email server. Set the timeout to 30 seconds and restart the poller.

When generating PDF's, Catapult Poller doesn't seem to autosense very well for
wide reports. Text lines run off of the right edge on wide reports.
Solution: Your PC is probably set to run at something other than the Windows default of
96dpi. You can confirm this by clicking Control Panel/Display (or right clicking on your
desktop and choosing Properties from the pop-up menu). Click on the Settings Tab, then
on the Advanced button. Check the General tab for DPI setting. If it is something other
than the default of 96 dpi, try setting it back to 96 dpi, then rebooting.

When viewing the Grab Rule wizard panels, I can't see the 'Show Spool file'
checkbox.
Solution: Your PC is probably set to run at something other than the Windows default of
96dpi. You can confirm this by clicking Control Panel/Display (or right clicking on your
desktop and choosing Properties from the pop-up menu). Click on the Settings Tab, then
on the Advanced button. Check the General tab for DPI setting. If it is something other
than the default of 96 dpi, try setting it back to 96 dpi, then rebooting.

When generating PDF files, you get this warning message: PDF Generator
returned Error Code: 44
This usually occurs when you are using an overlay. The error is caused because the
overlay cannot be found. Some possibilities are that the path specified for overlay is
incorrect, the user who started the poller does not have authority to the directory where
the jpg is, or that the overlay is not a jpg. Remember when specifying a path the path

- 404 -
must be a valid path from the polling PC. If you specify C:| as the path that means the
image must reside on the polling machines C drive.
In my Request Errors I see CPF3344 or CPF3342 error messages for my spool
file.
Each poller cycle involves two passes: a first pass to identify spool files to be processed,
and a second pass to process them. These errors are usually caused by the spool file
being removed from the IBM i between the time when Catapult generates an internal
record to process the spool file, and when it goes back to actually execute that process.
This can happen because someone deleted the spool file, but more often it happens
because you have two rules that process the same spool file, and one of the rules is set
to delete the spool file after processing it.

- 405 -
Sending Spool Files (Primarily to Tech Support)
On occasion you may run into errors with Catapult where a specific grab rule causes the
poller to crash, or issue an error, and after reviewing all the standard troubleshooting
criteria, you may reach the conclusion that what is causing the problem is the nature of
the particular spool file you’re sending out.
If this is the case, you can send that spool file (or a set of files) to Technical Support so
our team can attempt to replicate the behavior you were encountering, and either
suggest some changes to the file, or build a software fix for the problem.
To send us a spool file you can use the functionality built into the Catapult Console.
Here’s how to do it:
1. Open the grab rule that is designed to select the spool file in question.
2. Go to the Acquisition options for the spool file and click the Locate button. In
the Preview window that opens, find your spool file and click on it.
3. From the File menu, select the Export Spool File(s) option. This window is
presented:

Figure C-5. Exporting a spool file to technical support.

Enter the following options:
● Spool File Stream(s). Use this option to select which spool file(s) to email.
● Export Target. You can save the spool file as a PC file, or you can email it
directly to someone else.
● Save Target Folder. This option is enabled if you selected the option to
save the spool file to disk. The default export location is: C:\Documents and
Settings\All Users\Application Data\ESDI\Catapult\Exports\.
● Email Details. If you selected the option to email the spool file, fill out the To
and From email address information.
4. When you finish entering the required information, click OK.
IBM has also added the ability to save spool files in a SAVOBJ command (as of V5R4) so
if this method doesn’t work, you can create a save file with your spool file, use FTP123 to

- 406 -
 download it to your PC, and then email that to us. This requires a little bit of coordination
on IBM i release levels, and how you create the save file.

Importing Spool Files

To import a spool file, use the Import option from the File menu in the Preview window.
You can open the Preview window directly from the Catapult Console to do this.
The import process will prompt you for a file with an extension of .splf.

When importing the spool file to the target system, if when

you exported you filtered to a specific queue, when you
import the spool file it will be imported to the same queue.

- 407 -
Index

&
&K with Report Splitting 224
&N and other replacement values 241
nifty insertion tool 241
&W0, etc. replacement values 299

*
*ALL
out queue selection option 198
special group key value 184
*ENDOFPAGE
splitting & overlays 257
*ENDOFREPORT 213
*FILE, *RPT & *RICH Download Formats 199
*NONE overlay image option 256
*RICH
download format, using with transformations 239
*SAVE, *HOLD, *RELEASE and *DELETE Actions 200
*SCS Spool files 262
*STARTOFPAGE 213
splitting & overlays 257
*STARTOFREPORT 213
*STARTTEXT
tutorial section 124
*USRASCI
spool file download options 242

- 408 -
 .
.NET Framework 3.5 43

1
10061
EXODUS error code 46
10061 or 10057 errors
resolving 76
10061, 10057, 10035 and 10053 errors
troubleshooting guide 387

5
5722SS1
TIF file generation, required program 262

A
A3, A4, A5
paper size support 245
Acquisition
network files 206
reference section 196
selection type 196
spool file options 197
type, default for new rules 339
Additional Values
group entries 185
using in grab rules 186

- 409 -
Address Book
See Groups 179
Administrator
notifying of email errors 52
AFP 262
saving as TIF 239
Allowed Pending Connections 369
Anchor
split segment anchor text 218
Anchors
split segments with none 357
Append
appending content to existing files 302
Application Data Path
default for console 338
poller default 360
Archiving
distribution method 301
documents (tutorial) 88
split report section options 303
troubleshooting the poller service config 55
AS/400
See IBM i 319
Attaching Additional Files 273
Attachments
attaching additional files 273

- 410 -
 emailing options 280
grouping multiple into a single email 285
poller default handling 352
splitting and emailing options (tutorial) 135
Authority Issues
troubleshooting grab rules (tutorial) 99
Automatically Load Spool File List
default setting 338
Autorun Program Path
compressed file options 271

B
Backup Grab Rules
restoring from saved versions 176
Bar Codes
example 381
example *RICH font tag 381
list of bar code fonts 381
Batch File Processing
attaching to the grab rule 266
batch file path 267
example 266
timeout option 357
troubleshooting 400
Bolding
retaining in generated reports 261

- 411 -
Bookmarks 248
adding (tutorial) 109
key position 249
using the preview window to define 249

C
Cache Options 360
cacheing network files after processing 208
spool file cache 200
Catapult
installation components 37
Catapult Console
See Console 70
Catapult Poller
See Poller 70
catapult.exe
See Console 43
CCSID
configuring (installation) 53
grab rule translation options 199
poller defaults 355
See also Translation 53
Character Spacing
automatic settings in the poller 357
overriding 247
PDF defaults 247

- 412 -
CL Programs
executing ZRUNRULE command 326, 330
Clearing
error entries 355
history record clearing options 354
Columns
displayed in the console 164, 340
CommConfig
target path shortcut 67
Communications
troubleshooting tips 389
Communications Configuration
environment library 335
IBM i profile 336
local IP to use 335
options reference 334
port number 335
system name 335
target IP address or domain 335
Compression
default compression factor 357
file autorun program path 271
options reference 270
password protecting files 271
PDF option to compress text & graphics 251

- 413 -
Configuration Options
launchpad, accessing from 317
Configuring TCP/IP 369
Connect Time Out 349
Connection Attempts
displaying log file of 391
poller configuration 349
troubleshooting refused errors 389
Connection Refused
troubleshooting 387
Connections
adding 335
connecting to another IBM i 316
Console
application data path 338
columns displayed 164, 340
configuration options reference 337
email configuration 342
email server user validation 343
folders, working with 169
general configuration options 337
general implementation considerations 69
grab rules, options to work with 166
launching (tutorial) 76
launchpad, starting from 317
messaging options 341

- 414 -
 pinning tab windows 164
reference 161
relationship to the poller 70
resetting configuration defaults 338
tab display defaults 164
tabs & dockable windows 163
tabs, unhiding 163
using 162
ConsoleConfig
target path shortcut 67
Copying
disabling copying from PDF files 252
folders 169
grab rules 166
grab rules (tutorial) 102
grab rules to another system 175
CPF3344/3342
missing spool file error 405
Create Exodus TCP/IP Objects 369
CSS
using with HTML files 247

D
Data Extraction 228
Data Search Values
Nexus distribution 299

- 415 -
Database Values
example program to retrieve 235
Date
replacement value, poller PC 241
spool file, replacement value 241
Debug Mode
putting poller into 361
Default Configuration
poller 356
Default Printer
poller config setting 358
Default Values
for new rules 339
Delete After Use
grab rule option 194
Deleted Grab Rules
recovering 176
Deleting
grab rule folders 169
grab rules 166
network files after processing 208
Demo Files and Reports
location 75
Distributing Spool Files from IBM i Jobs 319
Distribution
archiving options 301

- 416 -
 email options (tutorial) 84
faxing 291
Nexus ECM 298
printing options 288
reference section 272
tracking options 305
verifying Nexus results (tutorial) 156
Distribution Errors
clearing entries 355
troubleshooting (tutorial) 98
Distribution Groups
See Groups[Distribution Groups
aaa] 179
Distribution History
listing history records 313
Distribution Tracking
poller status tab 306
Document Distribution Status 305
Document Format
default for new rules 339
TIF files 262
transformation option 242
Document Setup
PDF options (tutorial) 105
testing the defaults (tutorial) 105
transformation options 244

- 417 -
Download Formatting Options 199
Download History List 313

E
ECM
See Nexus [ECM
aaa] 149
ECM Folder
creating (tutorial) 148
Email
addresses from distribution groups 277
attaching a header/footer 281
attachment control options (grab rule level) 280
attachment control options (poller defaults) 352
combining split segments 357
console, enabling email from 342
default poller From name & address 348
distribution options 275
extracted value implementations 277
from address, user defined (tutorial) 134
grouping options 352
listing recipients in email body 352
recipient address options 275
return address options 276
subject options 278
Email Address
validation (turning off) 349

- 418 -
Email Pending
troubleshooting suggestion 404
Email Server
configuring the poller (installation) 51
configuring the poller (poller config) 348
IP address (for emailing from console) 343
IP address (poller config) 349
Emailing
split report sections (tutorial) 132
Emailing Grab Rules
See Exporting Grab Rules 167
Encoding
font encoding 247
Encryption
PDF documents 252
Environment Library
connection configuration (reference) 335
connection configuration (installation) 45
Error Logs
locating and reviewing 385
troubleshooting (tutorial) 99
Error Notification Options
poller 350
Errors
10061 or 10057 errors 76
administrator error notification options 52

- 419 -
 clearing error entries 355
troubleshooting Catapult errors 384
when connecting to the IBM i 388
Examples
barcode implementation via rich text formatting 381
batch file 266
external data file value retrieval 235
external data value usage 233
overlay image implementation 257
report splitting 226
rich text formatting tags 374
Excel
exporting data to a spreadsheet 265
EXLOGF
displaying the connection log file 391
Exodus
communication errors 46
connection configuration 45
default port change at V6R1 46
how the subsystem works 367
restarting after an IPL 63
starting the subsystem (tutorial) 76
starting the subsystem after an IPL 42
subsystem OS/400 objects 368
technical info 367
why the subsystem is required for TCP/IP 366

- 420 -
Expiry Date
for grab rules 193
Exporting
data to Excel 265
grab rules 167, 175
group entries 181
request entries 309
spool files (to support) 406
EXSERVER
required job in the Exodus subsystem 63
troubleshooting problems with starting 390
External Data Values
grab rule usage 235
Extracted Data Values
email address applications 277
preview window definition of 229
using in your grab rule 231

F
F1,F2, etc.
See Keyboard Hotkeys 162
Fatal Errors
poller notification 350
Faxing
adding fax services to the Poller PC 293
distribution groups for report splitting 283
don’t use PDF to fax! 287

- 421 -
 faxing to a group 291
formatting documents to fax 287
group entries fax # 185
report faxing reference 291
report splitting 292
sending multiple report sections to one fax 285
sending one report section to multiple faxes 286
File Extensions
custom extensions for report transformation 239
File Name
downloaded file 240
gotchas with using replacement values 256
making unique with ZDSTSPLF 323
network acquisition file name options 206
File Type
grab rule option 242
network acquisition handling of 207
Files
attaching additional 273
Filter
spool file selection window option 191, 202
Folders
copying 169
creating 169
deleting 169
folder for new rules 193

- 422 -
 moving rules between 167, 170
renaming 169
working with console folders 169
Font & Font Size
overriding in PDF, RTF and HTML 246
Font Color in Adobe PDFs 246
Font Encoding
default for new rules 339
Footer
attaching to email 281
Footer Pages 173
Foreign Language Systems
See Translation 53
Form Overlays
aligning with report content 245
See Overlay Images 254
Form Type
selection criteria 198
Formatting
using Catapult rich format tags 261
Formtastic 269
Fragment Documents
maximum document size settings 356
From Name and Address
console email defaults 343
poller default 348

- 423 -
 G
Grab Rules
additional values, using 186
console options 166
copying 166
copying (tutorial) 102
copying folders 169
copying to another system 175
creating 189
creating (tutorial) 78
creating quick rules (tutorial) 79
deleting 166
deleting after 1 use 194
description 192
description, replacement value 240
email distribution options 275
exporting 175
exporting and emailing 167
external data value usage 235
extracted data value usage 231
extracting report data 229
file type selection 242
folders 169
importing 175
inactivating all 166
moving between folders 170

- 424 -
 network acquisition profile 207
number, replacement value 240
organizing into folders 169
previewing spool files 203
processing order 193
resequencing 166
securing 194
selection via the preview window 201
switching folders 167
title and footer pages 263
troubleshooting 393
Grey Fonts in Adobe PDFs 246
Group Entries
adding for splitting (tutorial) 119
additional values 185
creating (tutorial) 86
email address options 184
fax number selection 185
key values (tutorial) 120
key values for splitting and distribution 284
populating from IBM i files 233
printer selection 185
replacement values in email addresses 184
using *ALL special key value 184
Grouping Email
options 352

- 425 -
Groups
creating for a split rule (tutorial) 119
email addresses 277
exporting & emailing group details 181
faxing to 291
group entries, working with 183
group summary window 180
key values in group entries 184
name & description 181
reference section 179
retrieving values from external programs 233
See also Group Entries [Groups
aaa] 119
split rules 221, 283
split rules (tutorial) 128
tutorial section 84
where used information 187

H
Headers & Footers
attaching to email 281
working with defaults 171
High Priority
setting email to 281
History List 313
clearing records 354
opening 163

- 426 -
 refreshing list on startup 338
using (tutorial) 139
HTML Documents
overlay images as watermarks 260
style sheet web path 247
web path for form overlays 256
HTML Link
including report as 279

I
IBM i
connecting to another system 316
connection error troubleshooting 388
distributing spool files directly from 319
ending poller from 332
executing grab rules from CL pgms 326, 330
system usage 64
TCP/IP configuration 367
IBM i Component
implementation considerations 63
IBM i Job Name
replacement value 240
IBM i Profile
communications configuration 336
Exodus connection configuration 46
Images
adding to email body 172

- 427 -
 overlays for web pages 260
See also Overlay Images [Images
aaa] 172
title & footer pages 264
title and footer page web path 264
Importing
grab rules 175
spool files 407
Inactivating All Grab Rules 166
Include Options
attachment, inline, link, etc. 279
Increment Value
replacement value for split sections 240
Inserting
replacement values 241
Installation
configuring communications 45
configuring the poller 49
IBM i components 41
installing supporting applications on the poller PC 57
logging in for the first time 45
overview 36
PC components 43
Introduction
to WebSmart 19

- 428 -
IPDS
saving as TIF 239
IPL
restarting the EXODUS subsystem after 63

J
Job Name
selection criteria 198
Job Number
replacement value 241

K
Key Location
for bookmarks 249
identifying for split report sections (tutorial) 127
reference section details 218
Key Values
&k replacement value 240
*ALL special group entry value 184
group entries (tutorial) 120
group entry values 184
in group entries 285
smart splitting with overlays 257
using with PDF bookmarks 248
Keyboard Hotkeys 162
Keys
handling duplicates in splitting 357

- 429 -
Keywords
for PDF documents 253

L
Language Issues
grab rule CCSID options 199
See also Translation 355
Launchpad
configuration options 317
poller status 317
starting & using 317
starting automatically 318
starting the console 317
starting the poller from (tutorial) 91
Leading 107
automatic settings in the poller 357
overriding 246
Letterhead
using with Catapult 254
Library
Nexus library 299
License Key 41
Licensed Programs Required for TIF file Generation 262
Limiting the Out Queues Polled 347
Lines per Inch
See Leading 246
Link Type 280

- 430 -
Link URL 280
Links
adding to email body 172
Local IP Address
ZCFGTCP option 369
Local IP to Use
communications configuration 335
configuration issues and troubleshooting 46
Exodus connection configuration 46
Locate Button
using 82
Log In Prompt
options reference 336
Log Incoming Connections 369
LPI
See Leading 246

M
Mail Merge
See Image Overlays 254
Margins
overriding 245
Max Lines Per Page 245
Maximum File Size Settings 356
Messaging
communications messages logging 334
console options 341

- 431 -
 Console options 334
Microsoft .NET Framework 3.5 43
Moving
network files after processing 208
MSGW
troubleshooting jobs in message wait 390

N
Name
Exodus connection name 45
Native Process
emulating on printing processes 199
Network Access Problems
configuring the Catapult Poller service 55
Network Acquisition Default Profile
poller configuration 347
poller configuration (installation) 50
Network Acquisition Profile
in grab rules 207
Network Files
acquisition options 206
cache options 208
file type handling by poller 207
post-processing actions 208
Network Printers
retrieving a current list for the Poller 359

- 432 -
Network UNC Path
overlay images 255
Nexus
&W0, etc. replacement values 299
distributing documents to 298
downloading & installing 146
ECM administration options (tutorial) 149
ECM distribution rules (tutorial) 150
grab rule options (tutorial) 154-155
library name default for new rules 339
library to save to 299
logging in (tutorial) 147
setting up ECM (tutorial) 147
site to save to 299
using with Catapult (tutorial) 145
Nexus Site
default for new rules 340
Non-English Language Systems
See Translation 53
Non-Fatal Errors
poller notification 350

O
Order
in which rules are processed 193
Organizing
grab rules 166

- 433 -
Out Queue
default for preview window 338
Out Queues
authority issues when setting polling options 348
moving spool files after processing 200
selecting a subset to poll 347
selection by name 198
Out Queues to Poll
configuring on installation 50
managing system resource usage discussion 64
selecting a subset 347
Overlay Images
*NONE option 256
adding to documents (tutorial) 115
alignment default for RTF files 357
example 257
grab rule options 254
network UNC path(s) 255
overview 254
PDF error code 44 404
replacement values in file names 256
with report splitting 256
Overprinting
retaining in generated reports 261

- 434 -
 P
Page Breaks
inserting manually 245
Page Range to Download 198
Paper Sizes and Orientation
overriding 245
supported paper sizes 245
Passwords
considerations with PDF 252
for compressed files 271
remembering, communications setting 334
replacement values with 252
Paths
use UNC? default 340
PCL Files 242
PDF
*RPT download requirement 102, 244
allowing annotation and form field changes 252
allowing changes 252
allowing text and image selection 252
automatically determining character spacing in the poller 357
bookmarks (tutorial) 109
compress text & graphics 251
disabling printing 252
document setup overrides (tutorial) 107
don’t use for faxing! 287

- 435 -
 embedding true type fonts 247
encryption 252
enhancing attributes (tutorial) 105
font color 246
image overlays (tutorial) 115
PDF options (tutorial) 113
printing considerations 287
security & password settings 252
title, subject & keywords 253
transformation options 251
transforming reports into (tutorial) 104
troubleshooting generation problems 251
wide report problems 404
Performance
See Resource Usage 64
Pinning Windows 164
Plain Text Documents
printing 287
Poller
application data path default 360
configuring (tutorial) 92
configuring [Poller
aaa] 345
configuring PC for faxing 293
configuring the out queues to poll (installation) 50
debug mode 361

- 436 -
 default email From name & address 348
email server configuration 348
ending via an IBM i command 332
error notification options 350
file cache options 360
general implementation guidelines 67
initiating cycle from IBM i CL pgm 332
monitoring (tutorial) 138
network acquisition default profile 347
out queue authority issues 348
printer configuration options 358
setting out queues to poll 347
shut down options 346
SMTP authentication for email distribution 349
starting (tutorial) 91
startup options 345
temporary files directory 361
triggering an immediate poll 315
troubleshooting (tutorial) 97
troubleshooting, diagnostic tools 361
Poller Manager
using (tutorial) 92
Poller Status
checking (tutorial) 94
distribution tracking 306
launchpad, checking from 317

- 437 -
PollerConfig
target path shortcut 67
PollerMngr
target path shortcut 67
Polling
interval, setting 346
once daily 346
Port
2015 change at V6R1 46
connection configuration 335
connection configuration (installation) 45
Port for Incoming Connections 369
Pre-printed Forms
using with Catapult 254
Preview Window
CCSID for data translation 338
default out queue 338
default to automatically load list setting 338
extracted value definitions 229
right-click options 204
selecting a spool file 202
split key and anchor text definition 219
spool file selection 201
using to define bookmarks 249
using to define split criteria 214
using to locate spool files (tutorial) 78

- 438 -
 using to set up split criteria (tutorial) 124
Printer
poller configuration options 358
setting poller default 53
specifying in group entries 185
Printer Time Out
poller config setting 358
Printing
considerations 288
disabling printing ability in PDF files 252
emulating the native process 199
options 288
PDF & RTF documents 287
plain text documents 287
poller options for waiting for processes to complete 359
printing to groups 289
specifying a printer in group entries 185
split sections 290
troubleshooting 398
troubleshooting, configuring the Catapult Poller service 55
using the *DEFAULT printer 289
Priority
setting email priority 281
Process Order
new rule order 193

- 439 -
Purging
error entries 355

Q
Queues
See Out Queues [Queues
aaa] 200
Quick Rules
creating (tutorial) 79

R
Read Receipt
requesting 281
Recovering Grab Rules 176
Remember Session Password
communications option 334
Repeating a File Distribution 313
Replacement Characters
gotchas with using in PC paths & file names 256
Replacement Token
extracted data values 230
Replacement Values 240
in PDF passwords 252
inserting 241
inserting (tutorial) 133
overlay image names 256
use in group entry email addresses 184

- 440 -
 using (tutorial) 83
Report Data
extracting to use in the grab rule 229
Report Splitting
See Splitting. 209
Request Entries
exporting 309
Request List
browsing pending/error requests 308
refreshing list on startup 338
using (tutorial) 138
Request Number
replacement value 241
Resending Files 313
Resequencing Grab Rules 166
Resetting Defaults
console configuration 338
poller configuration 356
Resource Usage
IBM i components 64
out queue polling limitations 347
Using ZRUNRULE and ZDSTSPLF 66
Restoring Grab Rules 176
Return Address
for email 276
Rich Format Tags 261

- 441 -
Rich Text Formatting
options reference 372
RNQ0202 errors 392
RTF
automatically determining character spacing in the poller 357
overlay alignment default 357
printing considerations 287
RTF Files
using to pre-format faxes 287
Rule Status 193
default for new rules 339

S
Scheduled
poller startup option 346
SCS Spool Files 262
Search Subfolders
network acquisition option 206
Security
overview of considerations 61
securing grab rules 194
security considerations 371
settings for PDF documents 252
Segment
end text 213
start text 213

- 442 -
Segment Anchor
text 218
Segment Anchor and Key Selection
splitting 218
Segment Options
document splitting 212
Segments
split sections with no anchor 357
split segments with identical keys 357
Selection
locate button, using to build selection 82
preview window usage 201
relationship between spool file selection criteria 197
Selection Types
acquisition 196
Self-Extracting Executables
compression options 270
Sending Files Again 313
Server Path
download option 301
Service
configuring the Catapult service 55
Show Spool File Checkbox
not visible 404
Site
Nexus site to save to 299

- 443 -
SMTP
using separate conversations 349
SMTP Authentication
poller configuration 349
poller configuration (installation) 52
Software Updates
poller 355
Sorting
grab rules 166
SP_MSRV & SP_PSRV 63
Splitting
archiving options 303
combining split segments in email 357
distribution group attached 221
duplicate key handling 357
email options (tutorial) 132
email subject options (tutorial) 133
email/fax/print groups 283
enabling 211
examples 226
faxing split sections 292
how splitting works 210
how splitting works (tutorial) 118
increment value replacement token 240
overlays, special values for 257
preview window usage for setup 214

- 444 -
 printing split sections 290
sections with no anchor 357
segment anchor and key selection 218
sending multiple section to one recipient 285
sending one section to multiple recipients 286
troubleshooting 395
tutorial section 117
unassigned segments 222
unassigned segments (tutorial) 129
using the &K key value variable 224
using the preview window (tutorial) 124
using with form overlays 256
Spool File Action 199
Spool File Name
selection criteria 198
Spool File Number
replacement value 240
Spool File Selection Window 190
filtering options 191, 202
Spool Files
acquisition options 197
exporting to another system (usually support) 406
importing from another system 407
moving to another out queue 200
previewing 202

- 445 -
Spreadsheets
exporting data to 265
Startup
starting the launchpad 318
Status
grab rule status 193
ZRUNRULE considerations 193
Style Sheet Web Path 247
Subject
email 278
for PDF documents 253
System Name
communication configuration 335
System Resource Usage
See Resource Usage 347

T
Tabs
pinning the tab windows open 164
setting display defaults 164
unhiding 163
Target IP/Domain
communication configuration 335
Exodus connection configuration 45
Target Path
launching specific Catapult components 67

- 446 -
TCP/IP
Communications Considerations 366
configuration options 369
configuring the IBM i to support 367
why subsystem is required 366
Technical Support
sending spool files to 406
Temporary Files Directory
for downloaded files 361
Test Connection
communications configuration 336
Text Link
including report as 279
Text to PDF Conversion
inserting page breaks manually 245
TIF Files
document format 262
Time
poller PC, replacement value 241
spool file, replacement value 241
Timeout
setting Console connection timeout 334
Title
for PDF documents 253
Title and Footer Pages 173
adding to grab rules 263

- 447 -
 design options 174
images, incorporating 264
Tracking
distribution history 313
Options 305
Transformation
bookmarks 248
document setup options 244
document type selection 242
file types 239
PDF file options 251
reference section 238
setting the name and format 240
tutorial section 82
Translation
grab rule options 199
options 53
poller CCSID defaults 355
preview window CCSID 338
unknown character handling 355
whitespace removal option 355
Triggering Immediate Polls 315
Troubleshooting
authority issues (network and files) 99
basic techniques (tutorial) 97
batch file processing 400

- 448 -
 communications 389
comprehensive guide 384
connection refused errors 389
CPF3344/3342 errors 405
displaying a log of connection attempts 391
error log files 385
error logs (tutorial) 99
Exodus jobs in MSGW status 390
grab rule processing 393
logging communications status messages 334
overlays in PDF files 404
PDF generation problems 251
printing issues 398
report splitting 395
starting EXSERVER 390
testing your communications and connections 336
verifying Nexus distribution (tutorial) 156
TrueType Fonts
embedding 247
Tutorial 75, 101

U
Unassigned Segments 222
in splitting rules (tutorial) 129
UNC Paths
option to use by default 340
to save files 301

- 449 -
Underlining
retaining in generated reports 261
Unique File Names
creating with ZDSTSPLF 323
Unknown Characters
translation option 355
Updates
automatic download 337
Updating PDF Files
disabling ability to 252
Use Expiry Date
for grab rules 193
User Data
replacement value 240
selection by 198
updating after processing 200
User ID
replacement value 241
selection criteria 198
User Validation
console email server option 343

V
V6R1
default port changes 46

- 450 -
 W
Web Pages
including in email body 172
Web Path
title & footer page images 264
using form overlays with HTML 256
Whitespace
poller default, language issues 355

X
XL_CATAPLT
product library 37
tutorial files & reports 75
XL_CATINST
installation library 37
XL_EXODUS
communications middleware library 37

Z
ZCFGTCP 367
TCP/IP config command 369
ZDSPERRLOG 370, 391
ZDSTSPLF
how it works 325
making unique file names 323
parameter reference 320
performance recommendations 66

- 451 -
 spool file distribution 320
Zip Files
compression factor default 357
creating 270
ZPOLLEND
command reference 332
ZPOLLNOW 332
ZRUNRULE
executing grab rules from server jobs 326, 330
grab rule status considerations 193
how it works 329
parameter reference 326, 330
performance recommendations 66

- 452 -