Business objects RAPID 2.20C User Manual

RAPID User’s Guide

RAPID 2.20c

November 2008

owns the following U.S. patents, which may cover products that are offered and licensed by Business Objects: 5,295,243; 5,339,390; 5,555,403; 5,590,250; 5,619,632; 5,632,009; 5,857,205; 5,880,742; 5,883,635; 6,085,202; 6,108,698; 6,247,008; 6,289,352; 6,300,957; 6,377,259; 6,490,593; 6,578,027; 6,581,068; 6,628,312; 6,654,761; 6,768,986; 6,772,409; 6,831,668; 6,882,998; 6,892,189; 6,901,555; 7,089,238; 7,107,266; 7,139,766; 7,178,099; 7,181,435; 7,181,440; 7,194,465; 7,222,130; 7,299,419; 7,320,122 and 7,356,779. Business Objects and its logos, BusinessObjects, Business Objects Crystal Vision, Business Process On Demand, BusinessQuery, Cartesis, Crystal Analysis, Crystal Applications, Crystal Decisions, Crystal Enterprise, Crystal Insider, Crystal Reports, Crystal Vision, Desktop Intelligence, Inxight and its logos , LinguistX, Star Tree, Table Lens, ThingFinder, Timewall, Let There Be Light, Metify , NSite, Rapid Marts, RapidMarts, the Spectrum Design, Web Intelligence, Workmail and Xcelsius are trademarks or registered trademarks in the United States and/or other countries of Business Objects and/or affiliated companies. SAP is the trademark or registered trademark of SAP AG in Germany and in several other countries. All other names mentioned herein may be trademarks of their respective owners.

RAPID User’s Guide

Chapter 1:

Introduction to RAPID................................................................................. 9

What is RAPID?.............................................................................................10

About Business Objects’ RAPID products ....................................................14

Components of a RAPID application.............................................................17

Introduction to job files..................................................................................18

Chapter 2:

Creating a RAPID application................................................................... 21

About the C++ interface.................................................................................22

About the Java interface.................................................................................23

About the ActiveX interface ..........................................................................24

Sample programs............................................................................................26

Event handling................................................................................................29

Error handling ................................................................................................31

Using programmable data sources .................................................................32

Using programmable input files.....................................................................33

Using programmable output files...................................................................36

Specifying DEF and FMT settings programmatically ...................................40

Job streaming (piping) overview....................................................................41

Chapter 3:

C++ ............................................................................................................... 43

Comprehensive class list................................................................................44

Inheritance diagram............................................ .... ..... .... ...............................46

AceJobApp ....................................................................................................47

AceJobApp method details.............................................................................48

AceJobAppException ....................................................................................49

AceJobAppException method details ............................................................50

AceTransApp ................................................................................................52

AceTransApp method details.........................................................................53

DiqJobApp ....................................................................................................54

DiqJobApp method details.............................................................................55

DiqJobAppException ....................................................................................56

DiqJobAppException method details.............................................................57

DiqTransApp .................................................................................................59

DiqTransApp method details .........................................................................60

DtrJobApp .....................................................................................................61

DtrJobApp method details..............................................................................62

DtrJobAppException .....................................................................................63

DtrJobAppException method details .............................................................64

DtrTransApp ..................................................................................................66

DtrTransApp method details..........................................................................67

FirstlogicApp .................................................................................................69

FirstlogicApp method details.........................................................................70

FirstlogicAppException ................................................................................75

Contents

FirstlogicAppException method details.........................................................76

FirstlogicDb ..................................................................................................79

FirstlogicDb method details............................................... ............................81

FirstlogicDbPWFields ..................................................................................89

FirstlogicDbPWFields method details...........................................................90

FirstlogicDbRecordFormat ........................................................................... 93

FirstlogicDbRecordFormat method details....................................................95

FirstlogicDbRecordInfo .............................................................................. 100

FirstlogicDbRecordInfo method details.................................................... ...101

FirstlogicDbThreadPipe ..............................................................................105

FirstlogicDbThreadPipe method details ......................................................107

FirstlogicProgPWFields .............................................................................. 113

FirstlogicProgPWFields method details ......................................................114

FirstlogicProgRecordFormat ......................................................................120

FirstlogicProgRecordFormat method details...............................................121

FirstlogicTransApp ..................................................................................... 123

FirstlogicTransApp method details..............................................................125

IAceJobApp ................................................................................................135

IAceJobApp method details.........................................................................136

IAceJobAppException ................................................................................ 137

IAceJobAppException method details.........................................................138

IAceTransApp .............................................................................................140

IAceTransApp method details.....................................................................141

ILDbThreadPipe ..........................................................................................143

ILDbThreadPipe method details..................................................................144

MpgJobApp ................................................................................................145

MpgJobApp method details.........................................................................146

MpgJobAppException ................................................................................ 147

MpgJobAppException method details.........................................................148

MpgTransApp ............................................................................................. 150

MpgTransApp method details .....................................................................151

PstJobApp ................................................................................................... 154

PstJobApp method details............................................................................155

PstJobAppException ................................................................................... 156

PstJobAppException method details ...........................................................157

Chapter 4:

Java ............................................................ ..... ........................................... 159

Additional setup for Java.............................................................................160

Package list..................................................................................................161

Comprehensive class list..............................................................................162

Inheritance diagram .....................................................................................164

AceJobApp...................................................................................................165

AceJobApp method details..........................................................................166

AceJobAppException ..................................................................................167

AceJobAppException method details..........................................................168

AceTransApp...............................................................................................169

AceTransApp method details.......................................................................170

DiqJobApp...................................................................................................171

DiqJobApp method details...........................................................................172

DiqJobAppException ...................................................................................173

DiqJobAppException method details ..........................................................174

DiqTransApp ...............................................................................................175

RAPID User’s Guide

DiqTransApp method details .......................................................................176

DtrJobApp....................................................................................................177

DtrJobApp method details............................................................................178

DtrJobAppException....................................................................................179

DtrJobAppException method details ...........................................................180

DtrTransApp.................................................................................................181

DtrTransApp method details........................................................................182

FirstlogicApp................................................................................................183

FirstlogicApp method details.......................................................................184

FirstlogicAppException ...............................................................................188

FirstlogicAppException method details.......................................................189

FirstlogicDb..................................................................................................191

FirstlogicDb method details.........................................................................193

FirstlogicDbPWFields..................................................................................200

FirstlogicDbPWFields method details .........................................................201

FirstlogicDbRecordFormat...........................................................................204

FirstlogicDbRecordFormat method details..................................................206

FirstlogicDbRecordInfo ...............................................................................210

FirstlogicDbRecordInfo method details.......................................................211

FirstlogicDbThreadPipe...............................................................................215

FirstlogicDbThreadPipe method details.......................................................217

FirstlogicProgPWFields...............................................................................223

FirstlogicProgPWFields method details.......................................................224

FirstlogicProgRecordFormat........................................................................230

FirstlogicProgRecordFormat method details ...............................................231

FirstlogicTransApp.......................................................................................232

FirstlogicTransApp method details..............................................................234

IAceJobApp..................................................................................................242

IAceJobApp method details.........................................................................243

IAceJobAppException .................................................................................244

IAceJobAppException method details.........................................................245

IAceTransApp..............................................................................................246

IAceTransApp method details......................................................................247

MpgJobApp..................................................................................................249

MpgJobApp method details .........................................................................250

MpgJobAppException..................................................................................251

MpgJobAppException method details.........................................................252

MpgTransApp ..............................................................................................253

MpgTransApp method details......................................................................254

PstJobApp.....................................................................................................257

PstJobApp method details........................................................ ..... ...............258

PstJobAppException ....................................................................................259

PstJobAppException method details............................................................260

Chapter 5:

ActiveX......................................................... .............................................. 261

Comprehensive class list..............................................................................262

CAceJobActXCtrl ........................................................................................263

CAceJobActXCtrl method details................................................................265

CAceTransXCtrl...........................................................................................271

CAceTransXCtrl method details..................................................................273

CDiqJobActXCtrl.........................................................................................280

CDiqJobActXCtrl method details ................................................................282

Contents

CDiqTransActXCtrll....................................................................................289

CDiqTransXCtrl method details..................................................................291

CDtrJobActXCtrl.........................................................................................298

CDtrJobActXCtrl method details.................................................................300

CDtrTransXCtrl...........................................................................................306

CDtrTransXCtrl method details...................................................................308

CIAceJobActXCtrl.......................................................................................315

CIAceJobActXCtrl method details........................................................... ...317

CIAceTransXCtrl.........................................................................................324

CIAceTransXCtrl method details ................................................................326

CMpgJobActXCtrl.......................................................................................333

CMpgJobActXCtrl method details ..............................................................335

CMpgTransXCtrl.........................................................................................341

CMpgTransXCtrl method details.................................................................343

CPstJobActXCtrl .........................................................................................350

CPstJobActXCtrl method details.................................................................352

Chapter 6:

Troubleshooting................................................................... ..... .... ............ 359

UNIX errors.................................................................................................360

Java errors....................................................................................................361

Method-specific errors.................................................................................362

Build errors..................................................................................................363

Miscellaneous errors....................................................................................364

Special consideration...................................................................................365

Level of Unicode support in RAPID ...........................................................368

Adding Unicode support to your RAPID application..................................370

Glossary ......................................................................................................371

Index............................................................................................................375

RAPID User’s Guide

Preface

About this guide This guide contains information specific to integrating your RAPID product. It

contains some general introductory information to the various RAPID products. However, it does not include in-depth information about each individual RAPID product. For example, it does not include detailed information about settings in an International ACE job file.

When necessary , this docume nt will point you to another document tha t has more detailed information.

Other documentation Documentation related to this product:

 RAPID Online help  RAPID Release Notes  System Administrator’s Guide  Quick Reference

Conventions This document follows these conventions:

Convention Description

Bold We use bold type for file names, paths, emphasis, and text that you

should type exactly as shown. For example, “Type

Italics We use italics for emphasis and text for which you should substitute

your own data or values. For example, “Type a name for your file, and the

.txt

Menu commands

extension (

We indicate commands that you choose from menus in the following format: Menu Name > Command Name. For example, “Choose File >

testfile

.txt

New.”

We use this symbol to alert you to important information and potential problems.

We use this symbol to point out special cases that you should know about.

We use this symbol to draw your attention to tips that may be useful to you.

).”

cd\dirs

.”

Preface

RAPID User’s Guide

Chapter 1: Introduction to RAPID

W elcome to RAPID! Before you sta rt creating your RAPID application, it may be valuable to learn the basics behind the different RAPID products and what they do.

Additionally, there is more to RAPID than just the API. There are a lso addit ional supporting files, such as job files, that are necessary for RAPID processing.

This section introduces these concepts and, where necessary, points you toward more detail on each subject.

Chapter 1: Introduction to RAPID

What is RAPID?

RAPID stands for Rapid APplication Integration Deployment. RAPID lets you integrate Business Objects’ technology directly into other applications.

How does RAPID work?

RAPID is sort of a “layer” over the top of Business Objects’ job-file technology. Through its API (Application Programming Interface) RAPID pro vides a means for programmers to tie these Business Objects applications (ACE, International ACE, DataRight IQ, Match/Consolidate, and Presort) into your own applications.

For more information, see “How RAPID works” on page 10 and “Setting up your job processes” on page 11.

What interfaces are available?

RAPID is available in C++, Java, and ActiveX interfaces. Thes e interfaces let you handle various events, so that you have complete control over the display of the processing output. RAPID interfaces give you all the power of RAPID-enabled job-file products in a way that is easy to integrate into your own applications.

For more information, see “Available interfaces” on page 12 and “Creating a RAPID application” on page 21.

.NET support All RAPID products can be compiled using the Visual Studio 2003 .NET

compiler. RAPID’s C++ and ActiveX interfaces support .NET, and RAPID applications created on the C++ and ActiveX interfaces can be compiled on the Visual Studio 2003 .NET compiler.

RAPID supports the Visual Studio v. 6 compiler apart from the Visual Studio 2003 .NET compiler. The Visual Studio v. 6 compiler will not be supported in future releases of RAPID.

How RAPID works Below is a brief conceptual overview of a possible RAPID implementation in a

Windows NT environment.

In a Business Objects Views product

First, you use your Business Objects Views product, such as Match/Consolidate or DataRight IQ, to specify business rules, such as creating reports or usi ng match standards in the matching process.

RAPID User’s Guide

In RAPID Second, you use standard programming techniq ues to i nsert a RA PID compone nt

into your application.

In your application Finally, the job is run in your application, creating the desired output.

Setting up your job processes

Each of Business Objects’ RAPID products includes a large number of features and a wide range of flexibility. The purpose of the RAPID interfaces is to allow

Chapter 1: Introduction to RAPID

easy integration of those powerful Business Objects technologies into other applications.

Job files control business rules

Your Business Objects product experts can control virtually every aspect of the ACE, International ACE, DataRight IQ, Match/Consolidate, and Presort processes by making changes to the settings in the job file of each program. In essence, those job files become configuration files for the RAPID product. RAPID then depends on the settings in those job files to process data.

Your RAPID calls focus on simply processing data correctly; someone else with interest in the fine details of data hygiene and data structure needs to set up the job files.

Your Business Objects produc t experts should test those processes by running the appropriate product's jobs independently of RAPID, to make sure they are running correctly before they turn them over to the programmer.

The person setting up the job file should receive all of the prin ted doc umen ta tio n that came with your shipment of RAPID. To implement RAPID , you should nee d only this RAPID User’s Guide.

Available interfaces RAPID is available with the following interfaces:

C++ This inheritance interface lets you inherit from Business Objects classes and

accomplish a lot of programming work automatically . You can integrate a RAPID product into your own application with as little as one method call.

All RAPID products can be compiled using the Visual Studio 2003 .NET compiler. RAPID’s C++ interface supports .NET, and RAPID applications created on the C++ interface can be compiled on the Visual Studio 2003 .NET compiler.

RAPID supports the Visual Studio v. 6 compiler apart from the Visual Studio 2003 .NET compiler. The Visual Studio v. 6 compiler will not be supported in future releases of RAPID.

For more information, see “About the C++ interface” on page 22.

Java RAPID's Java interface uses Java wrapper classes over the C++ classes. These

classes use JNI to communicate with the C++ classes that they encapsulate. For the most part, the Java wrappers have the same object hierarchy (inheritance) and identical methods as C++.

For more information, see “About the Java interface” on page 23.

ActiveX This component interface lets you embed Business Objects techno logy directly

into programming environments that support ActiveX controls like MSVC, VB, J++, web scripts, and so on. For example, you can insert a RAPID component from your control toolbox into a VB application, and call at least one method to process jobs, and handle one event to control progress messages. The RAPID ActiveX controls are invisible at run-time.

All RAPID products can be compiled using the Visual Studio 2003 .NET compiler. RAPID’s ActiveX interfaces support .NET, and RAPID applications created on the ActiveX interfaces can be compiled on the Visual Studio 2003 .NET compiler.

RAPID User’s Guide

RAPID supports the Visual Studio v. 6 compiler apart from the Visual Studio 2003 .NET compiler. The Visual Studio v. 6 compiler will not be supported in future releases of RAPID.

For more information, see “About the ActiveX interface” on page 24.

Chapter 1: Introduction to RAPID

About Business Objects’ RAPID products

The following products are available in the RAPID deployment. Here is a brief overview of these products.

ACE and International ACE

The ACE and International ACE processes work very similarly. The ACE process breaks an address down into its components, looks it up in postal databases, corrects and completes the address, and assigns postal-automation codes.

DataRight: Database standardization

RAPID User’s Guide

Your ACE expert can make many changes in the detailed configuration of the ACE process. Your ACE expert can make those configuration changes either by using the ACE Views graphical interface or by directly editing the ACE job file. Regardless of the method of setting the ACE processing options, those settings are recorded in the ACE job file that your RAPID process uses.

DataRight converts messy, poorly formatted, inconsistent, and incomplete databases into a clean, uniform format. This process is particularly useful for converting legacy databases (such as old data from mainframe enterprise systems) to modern, open systems.

As it prepares your data, DataRight can identify and isolate name, job-title, firm, and address data (we call this parsing). It also standa rdiz es record data in various ways, and it can assign a precise gender code to each name in your database.

Your DataRight expert can make many changes in the detailed configuration of the DataRight process. Your DataRight expert can make those configuration changes either by using the DataRight Views graphical interface or directly

editing the DataRight job file. Regardless of the method of setting the DataRight processing options, those settings are recorded in the DataRight job file that your RAPID process uses.

DataRight IQ: beyond name and address standardization

Match/Consolidate: Finding duplicate (matching) records

DataRight IQ, like traditional DataRight, converts messy, poorly formatted, inconsistent, and incomplete databases in to a cle an, unifo rm format. Th is proce ss is particularly useful for converting legacy databases (such as old data from mainframe enterprise systems) to modern, open systems.

DataRight IQ is a key component of Business Objects’ Information Qual ity sui te and can significantly enhance matching results because of the following functionality:

 Identifies non-address data including e-mail addresses, phone numbers,

social security numbers, and dates. (Not available in traditional DataRight.)

 Allows custom dictionaries/tables to be added for parsing and standardiza tion

of other data elements such as part numbers, product codes, purchase orders, SKUs, customer identification numbers, and so on.

 Performs flexible name parsing that handles atypical names, dual names,

hyphenated names, and compound last names.

 Returns dependable name standards (individual and business) for

sophisticated data matching.

Match/Consolidate searches a group of database records to find matches by comparing name, company, address, account, phone, SSN, and so on, according to rules set by the user. The program provides many statistical reports and offers consolidation (when two or more records match, you choose one to keep while scavenging useful data from the others and discarding them).

Your Match/Consolidate expert can make many changes in the detailed configuration of the Match/Consolidate process, including which data is

Chapter 1: Introduction to RAPID

considered important for identifying matches, how closely the data must match, and what to do with the matching records or data.

Your Match/Consolidate expert can make those configuration changes either by using the Match/Consolidate Views graphical interface or directly editing the Match/Consolidate job file. Regardless of the method of setting the Match/ Consolidate processing options, those settings are recorded in the Match/ Consolidate job file that your RAPID process uses.

Presort: sortation and preparation for mailing

Presort arranges your database records into packages and containe rs and produces documentation to go along to the post of fice with the ma il pieces. Presort does not alter your input records; rather, it organizes how your records are presented to Label Studio, or other label-printing software.

The example below shows how an input database with particular fields is presented to Presort. The example also shows some files that are output, and which fields are included in those output files.

RAPID User’s Guide

Components of a RAPID application

The programming calls to RAPID libraries are not the only component of a RAPID application. RAPID applications also make use of job files and other supporting files. This section gives you an overview of the relationship of all the pieces in a RAPID application.

The major pieces A RAPID application is made up of a few major components: calls to RAPID

API methods (your RAPID application itself), a job file, suppo rting DEF files and FMT files, and your data sources and targets.

Your RAPID application

Your RAPID application is the software you build by using RAPID API calls to augment an existing application, or to create a new application from the ground up.

The RAPID API includes a number of methods for a variety of purposes. There are methods for defining data source formats, retrieving information about your processing, launching job processing, and error handling, for example.

One item you do not define via the API, however, is the business rules that explain how to process your data. Business rules are controlled within the job files for each RAPID product.

Job files RAPID applications make use of files that control business rules, and specify

locations to auxiliary files. The files that control th ese o ption s are c all ed job files. Job files are text files that can be edited through a Business Objects Views

program or text editor. There are different job files for ACE (.ace), IACE (.iac), DataRight (.dtr), DataRight IQ (.diq), Match/Consolidate (.mpg), and Presort (.pst).

By using job files, business rule configuration is mainta ined outside of the API. This is advantageous for RAPID users for a few reasons. The application developer doesn’t need to know about the business rule configuration. This shortens and simplifies the code needed for a RAPID application.

Additionally, a business rules experts don’t need to know how to code the RAPID API. They can simply edit the business rules via the job file as needed.

For further details about job files, see “Introduction to job files” on page 18.

Other supporting files Finally , there are two other types of supp orting files that you may encounter when

setting up your RAPID application. Format (.fmt) files explain the format of your data in terms of field name, data type, and field length. This information is necessary for RAPID processing.

Also, definition (.def) files include specifications for how field names from your data source map to Business Objects-recognized field names.

With RAPID, yo u hav e the option of defining these fields via t he appropriate file types or you can instead define these items programmatically. For more information, see “Using programmable input files” on page 33 or “Using programmable output files” on page 36.

Chapter 1: Introduction to RAPID

Introduction to job files

RAPID products use files that control business rules, and specify locations to auxiliary files. The files that control these options are called job files.

Format of job files Job files are text files that can be edited through a Views program or text editor.

Making copies of files before editing

Editing a job file through a text editor

The RAPID products include job file templates that come with default configurations. Before making chan ges directly to these files, make a duplic ate of the file. In this way , you ca n return to the defa ult settings stored in your bac kup, if needed.

The job file is divided into blocks, which are further separated into individual parameters. To change a setting, open the appropriate file in a text editor and change the parameters as desired.

The following example is taken from an International ACE (address cleansing) job file. The paths listed in the example belo w may differ from your paths, depending where you install the RAPID software.

BEGIN US Auxiliary Files ====================================== City Directory (path & city08.dir)... = C:\PW\dirs\US\city08.dir

ZCF Directory (path & zcf08.dir)..... = C:\PW\dirs\US\zcf08.dir

ZIP+4 Directory 1 (path & zip4*.dir). = C:\PW\dirs\US\zip4us.dir ZIP+4 Directory 2 (path & zip4*.dir). = Rev ZIP+4 Dir (path & revzip4.dir)... = C:\PW\dirs\US\revzip4.dir

Firm Line Dct (path & firmln.dct).... = C:\PW\iace\firmln.dct

Addr Line Dct (path & addrln.dct).... = C:\PW\iace\addrln.dct

Last Line Dct (path & lastln.dct).... = C:\PW\iace\lastln.dct

Casing Dct (path & pwcas.dct)........ = C:\PW\iace\pwcas.dct

END

Job-file block: A group of parame-

ters is called a block. This block contains the path locations of the ACE auxiliary files.

Required input: After the parameter name, the

required information for this parameter is listed. To change the setting, change the text after the equals (=) sign.

If the parameter is an option, valid settings are listed in this position.

Job-file parameter: Each parameter controls

one setting or option. For example, the Casing Dct parameter tells the Link stage where to find the dictionary for casing.

RAPID User’s Guide

Editing a job file through Views

Views programs are easy-to-use programs you use to edit your job files. Job files are organized into groups of parameters called blocks. Each Views setup window corresponds to a block in the job file. (A complicated block may be divided into two or more setup windows.) The picture belo w shows the relation ship between a Views window and the job-file block.

Because you have Views, you shouldn’t need to pay much attention to what the job file looks like inside. We show it to you here just so the process won’t seem mysterious.

Views

When you set up a job, Views automatically saves it for you in a job file.

Job file

BEGIN Standardization/Assignment Control ======================

Standardize Lastline (Y/N)........... = N

Non-Mailing Cities (CONVERT/PRESERVE) = PRESERVE

Case (UPPER/lower/Mixed/SAME)........ = MIXED

Use Generated Prenames (Y/N)......... = YES

Female Prenames if Couple (MS/MRS)... = MS

Provide Firm Acronyms (Y/N).......... = N

END

When you open an existing job file, its settings appear in the Views window.

Chapter 1: Introduction to RAPID

RAPID User’s Guide

Chapter 2: Creating a RAPID application

Before you build your RAPID application you have some important decisions to make. Will your application be batch or transactional? Do you want to use piping between multiple RAPID products? Do you want to create supporting DEF and FMT files, or define these items programmatically?

This section explains all of these items in more detail. Additionally, it points you toward sample programs that you can refer to for ideas about coding your RAPID application.

Chapter 2: Creating a RAPID application

About the C++ interface

If you use the C++ interface to implement RAPID, be aware of the following technical details.

Inheritance interface RAPID's C++ interface is an inheritance interface, meaning that it lets you in herit

from Business Objects classes and accomplish a lot of programming work automatically . You can integrate a RAPID produc t into your own appli cation with as little as one method call.

When using the C++ RAPID interface, you can inherit from one or more Business Objects classes. Using the inheritance integration model, much of the work is done for you behind the scenes. For example, you don't have to call Business Objects constructors and destructors. For example:

class MyApp : public AceJobApp { ... some class info ... };

This class declaration shows a user application inheriting from the AceJobApp class. So, when the user creates an object of type MyApp, AceJobApp functionality will automatically be part of MyApp objects.

Virtual methods Several inherited methods are virtual and may be overridden. For example, event

methods, such as FireProgressEvent() are virtual because you will optionally implement them. In this manner, you have control over how all progress events are handled and how and where progress messages should be displayed. You can choose to ignore progress messages, or handle them any way you want: display them in GUI components, write them to files, print them to the screen, and so on.

Dependencies to job file

RAPID interfaces are tied to particular job-file products. To use the programmable data source feature, you will need to change several job file related settings. For more information, see “Using programmable data sources” on page 32.

Unicode support The RAPID C++ interface includes support for Unicode data. For more

information about the level of Unicode support, and how to integrate Unicode support into your RAPID C++ application, see “Processing Unicode data in RAPID” on page 367.

.NET support All RAPID products can be compiled using the Visual Studio 2003 .NET

compiler. RAPID’s C++ interface supports .NET, and RAPID applications created on the C++ interface can be compiled on the Visual Studio 2003 .NET compiler.

RAPID supports the Visual Studio v. 6 compiler apart from the Visual Studio 2003 .NET compiler. The Visual Studio v. 6 compiler will not be supported in future releases of RAPID.

RAPID User’s Guide

About the Java interface

If you use the Java interface to implement RAPID, be aware of the following technical details.

Wrapper classes For its Java interface, RAPID uses Java wrapper classes. These classes use JNI

(Java Native Interface) to communicate with the C++ classes that they encapsulate.

For the most part, the Java wrappers ha ve the same objec t hierarchy (inheritance) and identical methods as C++. The only exceptions are:

 Enumerations (Java doesn't support them)  FirstlogicDbRecordInfo (which in Java is an interface)

Requirements RAPID requires Java 1.4. RAPID needs weak global references to resolve

memory deallocation issues.

Enumerations Java does not support enumerations. Methods that have a C++ counterpart that

returns enumerations will instead return integers in Java, and the enumerated values will be represented by constants.

Packages T o avoid namespace collisions, Java cla sses are organized into pac kages. Package

names are roughly defined in the Java language standard. For RAPID, the package layout is as follows:

Package Contains

com.firstlogic.products.rapid.common Classes shared by multiple RAPID products. com.firstlogic.products.rapid.ace Classes specific to ACE. com.firstlogic.products.rapid.iace Classes specific to International ACE. com.firstlogic.products.rapid.diq Classes specific to DataRight IQ. com.firstlogic.products.rapid.dtr Classes specific to DataRight. com.firstlogic.products.rapid.mpg Classes specific to Match/Consolidate. com.firstlogic.products.rapid.pst Classes specific to Presort.

Unicode support The RAPID Java interface does not support Unicode at this time. If you need

Unicode support, you must use the C++ interface. For more information about the Unicode support, see “Processing Unicode data in RAPID” on pa ge 367.

Chapter 2: Creating a RAPID application

About the ActiveX interface

If you use the ActiveX interface to implement RAPID, be aware of the following technical details.

RAPID ActiveX controls

Integrating RAPID ActiveX objects in MSVC

RAPID's ActiveX interface is a component interface that lets you embed Business Objects technology directly into programming environments (MSVC++, VB, J++, web scripts, and so on) that support ActiveX controls.

For example, you can insert a RAPID component from your control toolbox into a VB application, and call at least one method to process jobs, and handle one event to control progress messages. The Rapid ActiveX controls are invisible at run-time.

RAPID ActiveX

controls can be used on any Windows platforms that support ActiveX controls. Use these controls in any Windows development environments (Visual Basic, MSVC++, Visual J++, Visual InterDev, Microsoft Access, and so on) that supports ActiveX controls.

To use a RAPID ActiveX control in MSVC, follow the directions below.

1. Insert the ActiveX Control in your dialog by right-clicking the dialog and

selecting the Insert ActiveX Control option.

2. Choose the appropriate RAPID control from the list of registered ActiveX

controls.

3. After you select the desired RAPID control and place it in your dialog, you

need to assign a member variable to the control before you can access methods, properties, and events of the control.

Integrating ActiveX objects in Visual Basic

4. Go into Class Wizard.

5. Select the Member Variables tab.

6. Select the control ID of the RAPID control that you added.

7. Click the Add Variable button.

8. Assign a member variable to the RAPID control.

9. Immediately after you select Add Variable, the Class Wizard wi ll tell you that

a C++ wrapper class is being generated for the control and that it will be inserted into the project. Click OK. You can now access the RAPID control through its associated member variable.

10. Set your RAPID control's methods, properties, and events

To use a RAPID ActiveXTM control in Visual Basic, follow the directions below.

1. Right-click your Toolbox window.

2. Select Components from the menu.

3. Select the RAPID ActiveX component.

When you've added the component, it appears in your Toolbox window as another component that can be selected for your application.

RAPID User’s Guide

4. Add a RAPID component to your form by selecting the RAPID component and dragging the component button onto your form.

5. Set your RAPID control's methods and properties. You access the RAPID control's methods and properties through the control's

ID, which is specified in the Property Window when the control is selected, as the Name property.

You can use the GetRevision() method to troubleshoot and ensure that job file versions are correct.

Unicode support The RAPID ActiveX interface does not support Unicode at this time. If you need

Unicode support, you must use the C++ interface. For more information about the Unicode support, see “Processing Unicode data in RAPID” on pa ge 367.

.NET support All RAPID products can be compiled using the Visual Studio 2003 .NET

compiler. RAPID’s ActiveX interfaces support .NET, and RAPID applications created on the ActiveX interfaces can be compiled on the Visual Studio 2003 .NET compiler.

RAPID supports the Visual Studio v. 6 compiler apart from the Visual Studio 2003 .NET compiler. The Visual Studio v. 6 compiler will not be supported in future releases of RAPID.

Chapter 2: Creating a RAPID application

Sample programs

RAPID comes with numerous sample files you can refer to for ideas about how to integrate your own RAPID application.

All samples are included in all shipments of any RAPID-enabled product (th at is, even if you only purchase DataRight RAPID, for example, you receive sampl es designed for other RAPID products, like ACE RAPID. However, the concepts demonstrated still apply).

C++ and Java

RAPID includes several samples for C++ and Java implementations.

samples

Purpose of the sample RAPID product File name

C++ Java

A sample for each RAPID-enabled product demonstrating:



Reading an input file



Overriding progress messages and errors/warnings



Overriding write event using objects and FMT API

A single sample demonstrating piping:

ACE International ACE DataRight DataRight IQ Match/Consolidate Presort

ACE and DataRight

simple_ace.cpp simple_iace.cpp simple_dtr.cpp

simple_diq.cpp

simple_mpg.cpp simple_pst.cpp

pipe.cpp pipe.java

(From input file to ACE, DataRight, and an output file) A set of samples demonstrating the use of the transac-

tional API including:



Using hard coded input data



Programmable DEF & FMT API



Done for ACE and M/C

A set of samples demonstrating how to process Unicode data in a batch, piping, or transactional application.

ACE Match/Consolidate

DataRight IQ DataRight IQ International ACE

trans_ace.cpp trans_mpg.cpp

unicode_diq.cpp utrans_diq.cpp unicode_pipe.cpp

and DataRight IQ

simple_ace.java simple_iace.java simple_dtr.java

simple_diq.java

simple_mpg.java simple_pst.java

trans_ace.java trans_mpg.java

N/A N/A N/A

RAPID User’s Guide

ActiveX samples There are two ActiveX samples for RAPID. The ActiveX samples are written in

Visual Basic.

Purpose of the sample RAPID product File name

A single sample demonstrating:



The reading of an input file



Overriding progress messages and errors/

ACE

simple_ace.vbp

warnings



Overriding write event using objects and FMT API

A single sample demonstrating the use of the

ACE

trans_ace.vbp

Transactional API with ACE

Samples on .NET The following two VB samples are built on Visual Studio 2003 .NET compiler.

Purpose of the sample RAPID product File name

A single sample demonstrating:



The reading of an input file



Overriding progress messages and errors/

ACE

simple_ace.vbproj

warnings



Overriding write event using objects and FMT API

A single sample demonstrating the use of the

ACE

trans_ace.vbproj

Transactional API with ACE

Where are the RAPID samples?

On Windows

On UNIX

Using the samples with another product

The RAPID samples are installed to a subdirectory beneath the RAPID installation location.

Language Default installation path

C++ Java ActiveX (Visual Basic) ActiveX (.NET)

Language Default installation path

C++ Java

\pw\rapid\Samples\cpp\ \pw\rapid\Samples\java\ \pw\rapid\Samples\vb\ \pw\rapid\Samples\vb.net\

/postware/RAPID/Samples/cpp/ /postware/RAPID/Samples/java/

Some samples, such as the transactional samples, do not have a separate version for each RAPID product. What if you want to change the trans_ace.cpp sample to work with DataRight IQ, for example? You should need to change only the

Chapter 2: Creating a RAPID application

application object type to refer to the product you want to use. For example, in the sample, change AceJobApp to DiqJobApp.

RAPID User’s Guide

Event handling

You can override progress events in each of RAPID's interfaces. The following sections explain how.

Overriding event handlers in C++

Overriding event handlers in Visual Basic

Below is an example of how to override the progress event in C++.

// This is what the skeleton implementation for your progress // message event handler might look like.

FirstlogicApp::EventResult MyAppClass::FireProgressEvent(FirstlogicApp::ProgressType prog_type, const char *msg1, const char *msg2)

{ ... // Your code to display progress messages, when progress events are // fired. ... }

Follow these steps to override event handlers in Visual Basic for RAPID ActiveX controls.

1. Go to the Source Code View.

2. Select the ID for your RAPID ActiveX object from the list of available objects in the Source Code View window . VB automatically crea tes an event handler subroutine skeleton.

T o display revisio n information in a message bo x using VB, with an ACE RAPID control ID of AceJobActX1, access the method like this:

MsgBox AceJobActX1.GetRevision

Available objects You can see which available events your application can "handle." On the Source

Code View window, the drop-box in the upper right-hand corner contains the available events. If an event is not handled, its n ame appears in regular text. If the event is currently being handled in your application, the event name appears as bold text.

Chapter 2: Creating a RAPID application

Event handler subroutine skeleton

When you select an event to handle, an event handler subrout ine skeleton is created for you automatically by VB.

For example, the graphic below shows the skeletons created for the FireDbWriteEvent and for the FireErrorMsgEvent. You can enter your event handlers into these skeletons.

RAPID User’s Guide

Error handling

The RAPID interfaces use exception handling to indica te that v arious errors have occurred to applications using RAPID. The exception objects that are thrown by various methods are all listed in the documentation for each method, under the “Exceptions” section.

The exception objects Generally, it is sufficient to catch only FirstlogicAppException objects.

However, if you wa nt to just catc h a certain pr oduc t's excep tions wi thin th e same try block, you may catch a specific product exception object, such as an AceJobAppException object.

Error handling with C++

Example

Error handling with ActiveX

Example for VB

To handle exceptions using the C++ interface you need to catch exceptions objects that may be thrown. You can then use several API method s to retrieve error information.

try { MyApp.ProcessJob("somejob.ace"); } catch (FirstlogicAppException& e) { cout << "Error Number: "" << e.GetErrorNumber(); }

To handle exceptions using the ActiveX interface, you can let exceptions go to your environment's default except ion handler , or yo u can access error in formation in your own error handler. Below is an example in VB.

... On Error Goto ErrHandler ' Call the method to process an ACE job AceJobActX1.ProcessJob("someJob.ace") ...

' If an exception occurs, here's how to handle it ErrHandler: MsgBox "Error Number: "Str(err.Number) + +vbCrLf + "ErrMsg: " + err.Description

Note that the err.Number and err.Descriptions have been filled in with RAPID product error information.

Chapter 2: Creating a RAPID application

Using programmable data sources

One method to process transactions one at a time is to use the programmable data source feature.

Transactional API. Instead of the process explained in this section, you can also use an API to perform true transactional processing. For more information, see Transactional processing.

Integrating a programmable data source

There are a couple of ways to integrate the prog rammable data source feature into your application.

You can use the default FirstlogicDb object, which requires no extra method calls for it to be attached to a Business Objects application. This model requires the special database access line in your DEF files (see below).

You can also create your own FirstlogicDb objects and attach them to a Business Objects application. You can use their names in the Inpu t and Output parameters of job-file blocks.

Supported database operations. The only database operations supported by programmable files are Read and Append. For an example, see “Using programmable output files” on page 36.

For further details, see:

 “Using programmable input files” on page 33  “Using programmable output files” on page 36

RAPID User’s Guide

Using programmable input files

Define via the API. Instead of the process explained below, you can also use an API to specify your DEF and FMT settings. For more information, see “Specifying DEF and FMT settings programmatically” on page 40.

To use programmable input files, you need to include special settings in th ese places:

 DEF file  FMT file  Input file block of the job file

DEF file You need a DEF (definition) file that corresponds to your input file (myfile.txt

and myfile.def, for example). Your DEF file defines the fields in the input file. Use only a database type of ASCII. This setting limits the field types to binary, character, date, logical, numeric, and packed numeric.

Include a second line of "Database Access = Prog". If you do not want to use a programmable data source, either remove the

"Database Access" line, or set "Database Access = File".

Example definition file

Database Type = ASCII Database Access = Prog PW.First_Name = First_Name PW.Mid_Name = Mid_Init PW.Last_Name = Last_Name PW.Address = Address PW.Last_Line = City_State & ZIP

FMT file A FMT (format) file outlines the physical format of a database (field names,

lengths, types, and formats). With programmable databases, you're actually defining the format that you want to send records in as.

Example format file

Date, 10, d, yyyy-mm-dd Name, 25, c Address, 25, c City, 15, c State, 2, c ZIP, 5, c ZIP4, 4, c

Place the format file in the same directory as the database. For example, for the database c:\data\myfile.txt, the format file would be c:\data\myfile.fmt.

If all the databases you process are in the same format, you can make one format file and use it with all your databases—a default ASCII FMT file (Auxiliary Files block in your job file).

Chapter 2: Creating a RAPID application

Input file block In the job file used to set your processing options, you need to specify an Input

File in the Input File block. It doesn't matter what is in this file—you won't be retrieving records from it (this is a job file limitation). It is a “dummy” file.

In reality, your input file data may be coming from a dialog, a database, or anywhere else you can get data from while in your DbRead event handler.

Below is an Input File block for an ACE job file.

BEGIN Input File ========================================== Input File Name (path & filename) = myfile.txt + Input Filter (to 512 chars) = Starting Record Number = Ending Record Number = Process Deleted Records (Y/N) = Y Unverified Postal Code(ERASE/PRESERVE) = preserve END

RAPID API calls After you include these special settings, you can make your RAPID calls. Here is

an example:

Name, 25, c Address, 25, c City, 15, c State, 2, c ZIP, 5, c ZIP4, 4, c DPBC, 2, c Date, 10, d, yyyy-mm-dd

The sample format file shown here would indicate that the user-supplied record layout in the DbReadEvent handler will include three character fields named "Name", "Address", and "City", with lengths of 25, 25, and 15 (among other fields not mentioned, like ZIP4).

Inside your DbReadEvent handler, you would supply records by calling the SetRecord() method.

An appropriate VB ActiveX code fragment example is shown below.

Private Sub AceJobActX1_FireDbReadEvent(userAbort As Boolean) ... ' Build a record to pass in Dim recStr As String

' The variables below each will hold text corresponding to the .fmt files input fields (Name, Address, and City) Dim NameStr As String Dim AddressStr As String Dim CityStr As String

' In this example, assume that user input is coming from simple GUI text boxes named txtLine1, txtLine2, and txtLine3. The code below shows data being retrieved from txtLine1 only. This code would be repeated for txtLine2 and txtLine3 as well.

NameStr = txtLine1.Text

' Pad each field with spaces if not long enough, otherwise the record length of recStr won't be correct. If (Len(fieldStr1) < 25) Then NameStr = NameStr + Space(25 - Len(NameStr)) End If

RAPID User’s Guide

... ' Code for the other fields is not shown. ...

' Build the record string in recStr. An assumption being made here is that all fields have been space padded correctly and the record length will be correct.

recStr = NameStr + AddressStr + CityStr '(+ other fields not shown)

' Set the record as input. AceJobActX1.SetRecord (recStr) ...

End Sub

Chapter 2: Creating a RAPID application

Using programmable output files

To use programmable output files, you need to include special settings in these places:

 DEF file  FMT file  Input file block of the job file

DEF file You need a DEF (definition) file that corresponds to your output file (myfile.txt

and myfile.def, for example). Your DEF file defines the fields in the output file. Only use a database type of ASCII. This setting limits the field types to binary, character, date, logical, numeric, and packed numeric.

Include a second line of "Database Access = Prog". If you do not want to use a programmable data source, either remove the

"Database Access" line, or set "Database Access = File".

Example definition file

Database Type = ASCII Database Access = Prog PW.First_Name = First_Name PW.Mid_Name = Mid_Init PW.Last_Name = Last_Name PW.Address = Address PW.Last_Line = City_State & ZIP

FMT file A FMT (format) file outlines the physical format of a database (field names,

lengths, types, and formats). With programmable databases, you're actually defining the format you want the data posted in.

Example format file

predir, 2, c range, 25, c stname, 25, c postdir, 2, c city, 13, c state, 2, c zip, 5, c zip4, 4, c DPBC, 2, c

Place the format file in the same directory as the database. For example, for the database c:\data\myfile.txt, the format file would be c:\data\myfile.fmt.

RAPID User’s Guide

If all the databases you process are in the same format, you can make one format file and use it with all your databases—a default ASCII FMT file (Auxiliary Files block in your job file).

Output file block In the job file used to set your processing options, you also need to specify an

Output File Name in the Post to Output File block (ACE, IACE, DataRight, DataRight IQ, and Match/Consolidate have different output file block names. Just stick to the Post to blocks). As your records are processed, you are presented the records in the DbWrite event handler. You can display or write the records to wherever you want.

The records you are presented with are populated with wh atever in forma tion yo u posted in your Output File block and set aside space for in y our output file's FMT file.

Output block notes. Make sure that you specify Append (not Replace) for the Existing File parameter of the Output block because programmable files only support Read and Append operati ons. If you don't speci fy Append, you'll receive a verification error stating that the Truncate operation is not supported.

When using programmable output files, the Create Output File block of your job-file is not used. Be sure to remove or comment this block out of your jobfile.

BEGIN Post to Output file ================================= Output File Name (path & filename) = output.txt Existing File (APPEND/REPLACE) = append + Output Filter = Copy Input Data to Output File (Y/N) = Y Copy (source, destination) = ap.predir, predir Copy (source, destination) = ap.prim_range, range Copy (source, destination) = ap.prim_name, stname Copy (source, destination) = ap.postdir, postdir Copy (source, destination) = ap.city, city Copy (source, destination) = ap.state, state Copy (source, destination) = ap.zip, zip Copy (source, destination) = ap.zip4, zip4 END

RAPID API calls After you include these special settings, you need to make your RAPID calls.

Here is an example:

predir, 2, c range, 10, c stname, 20, c postdir, 2, c city, 13, c state, 2, c zip, 5, c zip4, 4, c

The sample format file shown here indicates that the user-supplied record layout in the DbWriteEvent handler will be 8 fields of name, length, and types as specified in the format file.

Inside your DbWriteEvent handler, you would retrieve records by calling the GetRecord() method.

Chapter 2: Creating a RAPID application

An appropriate VB ActiveX code fragment example is shown below:

Private Sub AceJobActX1_FireDbWriteEvent(userAbort As Boolean) ... Dim numFields As Long Dim recStr As String Dim i As Integer Dim preDir As String Dim stRange As String Dim stName As String Dim postDir As String Dim city As String Dim state As String Dim zip As String Dim zip4 As String Dim fieldLen As Long Dim fieldPos As Long Dim fieldStr As String Dim recNum As Long

' Get the number of fields numFields = AceJobActX1.GetNumFields()

' Get the entire record recStr = AceJobActX1.GetRecord()

' Get the current output record number recNum = AceJobActX1.GetRecordNumber()

' Walk through each field in the record and assign the values to various textbox variables For i = 1 To numFields Step 1

' Get the field length of the current field within the record. fieldLen = AceJobActX1.GetFieldLen(i)

' Get the field starting position of the current field within the record. fieldPos = AceJobActX1.GetFieldPos(i)

' Pull out the string for the current field fieldStr = Mid(recStr, fieldPos + 1, fieldLen)

' Based on the number of the current field, assign the text to the appropriate textbox variable. Select Case (i) Case 1: txtPreDir.Text = fieldStr Case 2: txtRange.Text = fieldStr Case 3: txtStName.Text = fieldStr Case 4: txtPostDir.Text = fieldStr Case 5: txtCity.Text = fieldStr Case 6: txtState.Text = fieldStr Case 7: txtZip.Text = fieldStr Case 8: txtZip4.Text = fieldStr End Select Next i

RAPID User’s Guide

...

End Sub

Chapter 2: Creating a RAPID application

Specifying DEF and FMT settings programmatically

Previously you had to specify record formats and field mappings by using .def and .fmt files. Now RAPID provides you with an API by which your code can specify the record formats and field mappings.

Record formats You can specify record formats by using the FirstlogicProgRecordFormat() class.

This class provides the API for specifying record formats. For details, see:

 “FirstlogicProgRecordFormat” on page 120 (for C++).  “FirstlogicProgRecordFormat” on page 230 (for Java).

Class usage for field mappings (DEF)

The following sample demonstrates mapping input fields (address, city, state and zip) to their equivalent output fields.

Example:

// define the input field mappings FirstlogicProgPWFields oInputFields(oInputFormat); oInputFields.AddPWField("pw.address", "address"); oInputFields.AddPWField("pw.city", "city"); oInputFields.AddPWField("pw.state", "state"); oInputFields.AddPWField("pw.zip", "zip");

Field mappings You can specify field mappings by using the FirstlogicProgPWFields class This

class provides the API for specifying field mappings. For details, see:

 “FirstlogicProgPWFields” on page 113 (for C++).  “FirstlogicProgPWFields” on page 223 (for Java).

Class usage for record formats (FMT)

The following sample demonstrates specifying the record format of a file containing nine fields (gender, first name, middle name, last name, address, city, state, zip, and end of record.)

Example:

// define the input record format FirstlogicProgRecordFormat oInputFormat; oInputFormat.AddField("gender", 2, FirstlogicDbRecordInfo::Character); oInputFormat.AddField("firstname", 20, FirstlogicDbRecordInfo::Character); oInputFormat.AddField("midname", 10, FirstlogicDbRecordInfo::Character); oInputFormat.AddField("lastname", 20, FirstlogicDbRecordInfo::Character); oInputFormat.AddField("address", 30, FirstlogicDbRecordInfo::Character); oInputFormat.AddField("city", 20, FirstlogicDbRecordInfo::Character); oInputFormat.AddField("state", 2, FirstlogicDbRecordInfo::Character); oInputFormat.AddField("zip", 5, FirstlogicDbRecordInfo::Character); oInputFormat.AddField("eor", 2, FirstlogicDbRecordInfo::Binary);

RAPID User’s Guide

Job streaming (piping) overview

Job streaming (also referred to as “piping”) is the ability to connect two or more Business Objects applications together and pass records between them without the records waiting for the first application to finish processing completely. You can also create job streams that optimize your performance by having multiple threads of one Business Objects application type feeding records into another Business Objects application type.

Job-streaming example

You may want to have three ACE jobs each processing one-third of your data file (see diagram below). With job streaming, you could have each ACE job running in its own thread and have each job writing its records to a FirstlogicDbThreadPipe object. At the same time, a Match/Consolidate job in its own thread can be reading its records from the same FirstlogicDbThreadPipe object that the ACE jobs are writing to. You give the FirstlogicDbThreadPipe object a name that is used in the inpu t/out put file p arameters of the Firstlog icApp applications.

Job streaming saves processing time because records can be sent to another Business Objects application as soon as possible. Job streaming is also a more convenient way of running Business Objects applications together that are all part of the same "job process" because it requires less manual intervention between Business Objects applications. For example, you don't have to manually start a Match/Consolidate application after waitin g for an ACE job to complete. Instead, you could start ACE and Match/Consolidate in separate threads and use job streaming, so Match/Consolidate would receive and store records as ACE processed them. Match/Consolidate would then find duplicates and perform other processing steps after ACE had sent all of its records.

Language and platform requirements. Job streaming is avail able o nly with the C++ and Java interfaces.

Chapter 2: Creating a RAPID application

RAPID User’s Guide

Chapter 3: C++

The following section includes information about the C++ API for RAPID. This includes additional setup steps specifically for C++ coding, as well as an API reference for your C++ classes, functions, and methods.

RAPID supports the Visual Studio v. 6 compiler apart from the Visual Studio 2003 .NET compiler. The Visual Studio v. 6 compiler will not be supported in future releases of RAPID.

Chapter 3: C++

Comprehensive class list

The following list shows all of the classes avail abl e for C++ including a brief description of the class.

C++ classes

Class and page number Description

“AceJobApp” on page 47 The

ate ACE job-file applications, through inheriting from this class.

“AceJobAppException” on page 49 The

for exceptions that may be thrown when ACE errors occur.

“AceTransApp” on page 52 The

form transactional processing in ACE.

“DiqJobApp” on page 54 The

ate DataRight IQ job-file applications, through inheriting from this class.

“DiqJobAppException” on page 56 The

for exceptions that may be thrown when DataRight IQ errors occur.

“DiqTransApp” on page 59 The

form transactional processing in DataRight IQ.

“DtrJobApp” on page 61 The

ate DataRight job-file applications, through inheriting from this class.

“DtrJobAppException” on page 63 The

for exceptions that may be thrown when DataRight errors occur.

“DtrTransApp” on page 66 The

form transactional processing in DataRight.

“FirstlogicApp” on page 69 The

needed to create

AceJobApp

AceJobAppException

AceTransApp

DiqJobApp

DiqJobAppException

DiqTransApp

DtrJobApp

DtrJobAppException

DtrTransApp

FirstlogicApp

class defines all the properties, methods, and events needed to cre-

class is used to define the types and methods necessary to per-

class defines all the properties, methods, and events needed to cre-

class is used to define the types and methods necessary to per-

class defines all the properties, methods, and events needed to cre-

class is used to define the types and methods necessary to per-

class defines the minimum properties, methods, and events

Business Objects

class defines what the error exception object looks like

applications.

“FirstlogicAppException” on page 75 The

calls to product-unspecific RAPID methods.

“FirstlogicDb” on page 79 The

reads them and to receive database records from a RAPID job file as it writes them.

“FirstlogicDbPWFields” on page 89 The

Objects

operator.

“FirstlogicDbRecordFormat” on page 93

“FirstlogicDbRecordInfo” on page 100 The

“FirstlogicDbThreadPipe” on page 105 The

“FirstlogicProgPWFields” on page 113 The

RAPID User’s Guide

The

sary to describe the record layout of a programmable data source.

logicApp object to another FirstlogicApp object (job streaming). The two

icApp

source via method calls.

FirstlogicAppExcpetion

FirstlogicDb

FirstlogicDbPWFields

application. This class supports a copy constructor and the assignment

FirstlogicDbRecordFormat

FirstlogicDbRecordInfo

FirstlogicDbThreadPipe

objects would run simultaneously in separate threads.

FirstlogicProgPWFields

class is used to pass database records to a RAPID job file as it

defines the exceptions that can be thrown during

class is used to define the PW fields for a

class defines a database record layout.

class is used to define the types and methods neces-

class is used to pass database records from one First-

class defines the PW fields for a programmable data

Business

Firstlog-

Class and page number Description

“FirstlogicProgRecordFormat” on page 120

The ble data source by means of method calls.

“FirstlogicTransApp” on page 123 The

perform transactional processing.

“IAceJobApp” on page 135 The

create IACE job-file applications, through inheriting from this class.

“IAceJobAppException” on page 137 The

like for exceptions that may be thrown when IACE errors occur.

“IAceTransApp” on page 140 The

form transactional processing in IACE.

“ILDbThreadPipe” on page 143 The

Pipe

“MpgJobApp” on page 145 The

create Match/Consolidate job-file applications, through inheriting from this class.

“MpgJobAppException” on page 147 The

like for exceptions that may be thrown when Match/Consolidate errors occur.

“MpgTransApp” on page 150 The

form transactional processing in Match/Consolidate.

“PstJobApp” on page 154 The

ate Presort job-file applications, through inheriting from this class.

FirstlogicProgRecordFormat

FirstlogicTransApp

IAceJobApp

IAceJobAppException

IAceTransApp

ILDbThreadPipe

class is used to define the types and methods necessary to

class defines all the properties, methods, and events needed to

class defines what the error exception object looks

class is used to define the types and methods necessary to per-

class is an interface class from which

is derived.

MpgJobApp

MpgJobAppException

MpgTransApp

PstJobApp

class defines all the properties, methods, and events needed to

class defines what the error exception object looks

class is used to define the types and methods necessary to per-

class defines all the properties, methods, and events needed to cre-

class defines a record layout for a programma-

FirstlogicDbThread-

“PstJobAppException” on page 156 The

for exceptions that may be thrown when Presort errors occur.

PstJobAppException

class defines what the error exception object looks like

Chapter 3: C++

Inheritance diagram

This section contains a flowchart showing the hierarchy of all the RAPID classes for C++.

Inheritance

RAPID User’s Guide

AceJobApp

Inheritance

The AceJobApp class provides the minimum implementation necessary to process an ACE job file.

FirstlogicDbRecordInfo

FirstlogicDb

|__

FirstlogicApp

|__

|__ AceJobApp

Detailed description

Method list

The AceJobApp class defines all the properties, methods, and events needed to create ACE job-file applications, through inheriting from this class. The

AceJobApp class provides actual implementations of several of the FirstlogicApp class methods.

You would handle the events for this class to do tasks like getting progress messages or using the programmable data source feature, and so on.

AceJobApp methods may throw AceJobAppException exceptions.

#include <acejob.h>

Method Description

AceJobApp() Constructor. ~AceJobApp() Destructor. GetProcessState() Returns the current processing state. GetRevision() Returns the revision string of the ACE product including its

constituent libraries.

ProcessJob() Processes the specified ACE job file.

Chapter 3: C++

AceJobApp method details

AceJobApp()

AceJobApp::AceJobApp() throw(AceJobAppException)

Constructor.

Exceptions This method can throw AceJobAppException objects.

~AceJobApp()

AceJobApp::~AceJobApp() [virtual]

Destructor.

GetProcessState()

ProcessState AceJobApp::GetProcessState (void) [virtual]

Call this method to retrieve the current state of the job. If called be fore the job has started processing, the current state will be “done.”

Returns Returns the current processing state in the ProcessState enumeration.

GetRevision()

const char * AceJobApp::GetRevision() throw (AceJobAppException) [virtual]

Call this method to retrieve the revision string of ACE, including its constituent libraries. This string cannot be modified or deleted.

Returns Returns the revision string of the Business Objects product, including its

constituent libraries. The revision string contains the product's version number, which is often useful to compare with the job file's version.

Exceptions This method can throw AceJobAppException objects.

ProcessJob()

void AceJobApp::ProcessJob(const char * jobFileName)throw (AceJobAppException) [virtual]

Processes the specified ACE job file. Call this method to process an ACE job file. The file you specify must exist and

not open by another process. ProcessJob() may be called multiple times per instance.

Parameters

Parameter Description

jobFileName

A string that contains the name of the job file you want to process.

Exceptions

This method can throw AceJobAppException objects.

RAPID User’s Guide

AceJobAppException

Inheritance

FirstlogicAppException |__ AceJobAppException

Detailed description

Method List

The AceJobAppException class is thrown in response to errors that can occur within the AceJobApp or AceTransApp classes.

This class is defined in acejobex.h. However, you do not need to directly include or inherit from this class. It is merely used by the AceJobApp class.

Method Description

AceJobAppException() Constructor. ~AceJobApp Exception() Destructor. GetExceptionClass Name() Retrieves the name of the exception class. operator=() Assigns the values of an AceJobAppException object

instance to the values of another AceJobAppException object instance.

Chapter 3: C++

AceJobAppException method details

AceJobAppException( )

Parameters

AceJobAppException::AceJobAppException(int errorNumber, const char * standardMessage = (char *) 0, const char * detailMessage = (char *) 0)

Constructs a new instance of AceJobAppException with the specified error, standard and detailed messages.

AceJobAppException::AceJobAppException(const AceJobAppException &)

Constructs a new instance of AceJobAppExceptio n that is a copy of the specifi ed exception.

Parameter Description

errorNumber

One of the ErrorNumber enumerated values. An integer indicating the type of exception. See

AceJobAppException

enu-

meration for “ErrorNumber” on page 51.

standardMessage detailMessage

A pointer to a string containing the concise error message. A pointer to a string containing more detail about the excep-

tion in a detailed error message.

AceJobAppException

The exception to copy.

~AceJobApp

AceJobAppException::~AceJobAppException() [virtual]

Exception()

Destructor.

GetExceptionClass

const char * AceJobAppException::GetExceptionClassName() [virtual]

Name()

Call this method to retrieve the name of the exception class.

Return values Returns “AceJobAppException.”

operator=()

AceJobAppException & AceJobAppException::operator= (const aObject & e)

Assigns the values of an AceJobAppException object instance to the values of another AceJobAppException object instance.

Parameters

Parameter Description

aObject

The exception whose values are to be copied.

RAPID User’s Guide

Enumerations

ErrorNumber These error numbers are generated by the ACE processing engine and interpreted

by RAPID.

enum AceJobAppException::ErrorNumber

Available values:

Error Description

none No error. noMemory Insufficient memory. ignored Method called out of sequence. jobFailed Job did not complete successfully . internal Internal application error. system System error.

Chapter 3: C++

AceTransApp

Inheritance

FirstlogicTransApp |__ AceTransApp

Detailed description

Method List

The AceTransApp class is used to define the types and methods necessary to perform transactional processing in ACE.

#include <acetrans.h>

Method Description

AceTransApp() Constructor. ~AceTransApp() Destructor. GetRevision() Returns the revision string of the ACE product includ-

ing its constituent libraries.

StartJob() Initializes the job. Reimplemented from the

TransApp

class.

Firstlogic-

RAPID User’s Guide

AceTransApp method details

AceTransApp()

AceTransApp::AceTransApp()

Constructor.

~AceTransApp()

AceTransApp::~AceTransApp() [virtual]

Destructor.

GetRevision()

const char * AceTransApp::GetRevision() throw (AceJobAppException) [virtual]

Call this method to retrieve the revision string of ACE, including its constituent libraries. This string cannot be modified or deleted.

Return values Returns the revision string of ACE, including its constituent libraries. The

revision string contains the ACE’s version number, which is often useful to compare with the job file's version.

Exceptions This method can throw AceJobAppException objects.

StartJob()

bool AceTransApp::StartJob(const char * aJobName, const char * aInputPipe, const char * aOutputPipe) throw

(FirstlogicAppException)

Parameters

Exceptions

Call this method to initialize the transaction object before you process records. Before you call StartJob(), you must have the input/output fields and the input

PW fields already set up or else an error will occur.

Parameter Description

aJobName aInputPipe aOutputPipe

The name of the job file to use for processing. The name of the input programmable data source. The name of the output programmable data source.

This method can throw FirstlogicAppException objects.

Exception Description

invalidValue The job name, input pipe, and/or output pipe parameter is null or missing. inUse The transaction application is already in use (that is,

StartJob()

has

already been called).

system An internal error has occurred. Typically this is the result of an invalid

PW field being specified. For more information, see the detailed message.

noMemory Out of memory .

Chapter 3: C++

DiqJobApp

Inheritance

The DiqJobApp class provides the minimum implementation necessary to process a DataRight IQ job file.

FirstlogicDbRecordInfo

FirstlogicDb

|__

FirstlogicApp

|__

|__ DiqJobApp

Detailed description

Method list

The DiqJobApp class defines all the properties, methods, and events needed to create DataRight IQ job-file applications, through inheriting from this class. The

DiqJobApp class provides actual implementations of several of the FirstlogicApp class methods.

You would handle the events for this class to do tasks like getting progress messages or using the programmable data source feature, and so on.

DiqJobApp methods can throw DiqJobAppException exception objects.

#include <diqjob.h>

Method Description

DiqJobApp() Constructor . ~DiqJobApp() Destructor. GetProcessState() Returns the current processing state. GetRevision() Returns the revision string of the DataRight IQ product

including its constituent libraries.

ProcessJob() Processes the specified DataRight IQ job file.

RAPID User’s Guide

DiqJobApp method details

DiqJobApp()

DiqJobApp::DiqJobApp() throw(DiqJobAppException)

Constructor.

Exceptions This method can throw DiqJobAppException objects.

~DiqJobApp()

DiqJobApp::~DiqJobApp() [virtual]

Destructor.

GetProcessState()

ProcessState DiqJobApp::GetProcessState (void) [virtual]

Call this method to retrieve the current state of the job. If called befo re the job has started processing, the current state will be “done.”

Return values Returns the current processing state in the ProcessState enumeration.

GetRevision()

const char * DiqJobApp::GetRevision() throw (DiqJobAppException) [virtual]

Call this method to retrieve the revision string of DataRight IQ, including its constituent libraries. This string cannot be modified or deleted.

Return values Returns the revision string of the Business Objects product, including its

constituent libraries. The revision string contains the product's version number, which is often useful to compare with the job file's version.

Exceptions This method can throw DiqJobAppException objects.

ProcessJob()

void DiqJobApp::ProcessJob(const char * jobFileName)throw (DiqJobAppException) [virtual]

Processes the specified DataRight IQ job file. Call this method to process an DataRight IQ job file. The file you specify must

exist and not open by another process. ProcessJob() may be called multiple times per instance.

Parameters

Parameter Description

jobFileName

A string that contains the name of the job file you want to process.

Exceptions

This method can throw DiqJobAppException objects.

Chapter 3: C++

DiqJobAppException

Inheritance

FirstlogicAppException |__ DiqJobAppException

Detailed description

Method List

The DiqJobAppException class is thrown in response to errors that can occur within the DiqJobApp and DiqTransApp classes.

This class is defined in diqjobex.h. However , you do not need to directly include or inherit from this class. It is merely used by the DiqJobApp class.

Method Description

DiqJobAppException() Constructor. ~DiqJobApp Exception() Destructor. GetExceptionClass Name() Retrieves the name of the exception class. operator=() Assigns the values of a DiqJobAppException object

instance to the values of another DiqJobAppException object instance.

RAPID User’s Guide

DiqJobAppException method details

DiqJobAppException()

Parameters

DiqJobAppException::DiqJobAppException(int errorNumber, const char * standardMessage = (char *) 0, const char * detailMessage = (char *) 0)

Constructs a new instance of DiqJobAppException with the specified error, standard and detailed messages.

DiqJobAppException::DiqJobAppException(const DiqJobAppException &)

Constructs a new instance of DiqJobAppException that is a copy of the specified exception.

Parameter Description

aErrorNumber

aStandardMessage aDetailMessage

One of the ErrorNumber enumerated values. An integer indicating the type of exception. See

Number

enumeration.

DiqJobAppException Error-

A pointer to a string containing the concise error message. A pointer to a string containing more detail about the exception

in a detailed error message.

DiqJobAppException

The exception to copy.

~DiqJobApp

DiqJobAppException::~DiqJobAppException() [virtual]

Exception()

Destructor.

GetExceptionClass

const char * DiqJobAppException::GetExceptionClassName() [virtual]

Name()

Call this method to retrieve the name of the exception class.

Return values DiqJobAppException.

operator=()

DiqJobAppException & DiqJobAppException::operator= (const aObject & e)

Assigns the values of a DiqJobAppException object instance to the values of another DiqJobAppException object instance.

Parameters

Parameter Description

aObject

The exception whose values are to be copied.

Chapter 3: C++

Enumerations

ErrorNumber These error numbers are generated by the DataRight IQ processing engine and

interpreted by RAPID.

enum DiqJobAppException::ErrorNumber

Available values

Error Description

none No error. noMemory Insufficient memory. ignored Method called out of sequence. jobFailed Job did not complete successfully. internal Internal application error . system System error.

RAPID User’s Guide

DiqTransApp

Inheritance

FirstlogicTransApp |__ DiqTransApp

Detailed description

Method List

The DiqTransApp class is used to define the types and me thods necessary to perform transactional processing in DataRight IQ.

#include <diqtrans.h>

Method Description

DiqTransApp() Constructor. ~DiqTransApp() Destructor. GetRevision() Returns the revision string of the DataRight IQ product

including its constituent libraries.

StartJob() Initializes the job. Reimplemented from the

TransApp

class.

Firstlogic-

Chapter 3: C++

DiqTransApp method details

DiqTransApp()

DiqTransApp::DiqTransApp()

Constructor.

~DiqTransApp()

DiqTransApp::~DiqTransApp() [virtual]

Destructor.

GetRevision()

const char * DiqTransApp::GetRevision() throw (DiqJobAppException) [virtual]

Call this method to retrieve the revision string of DataRight IQ, including its constituent libraries. This string cannot be modified or delete d.

Return values Returns the revision string of DataRight IQ, including its constituent libraries.

The revision string contains DataRight IQ’s version number, which is often useful to compare with the job file's version.

Exceptions This method can throw DiqJobAppException objects.

StartJob()

bool DiqTransApp::StartJob(const char * aJobName, const char * aInputPipe, const char * aOutputPipe) throw

(FirstlogicAppException)

Parameters

Exceptions

Call this method to initialize the transaction object before you process records. Before you call StartJob(), you must have the input/output fields and the input

PW fields already set up or else an error will occur.

Parameter Description

aJobName aInputPipe aOutputPipe

The name of the job file to use for processing. The name of the input programmable data source. The name of the output programmable data source.

This method can throw FirstlogicAppException objects.

Exception Description

invalidValue The job name, input pipe, and/or output pipe parameter is null or missing. inUse The transaction application is already in use (that is,

StartJob()

has

already been called).

system An internal error has occurred. Typically this is the result of an invalid

PW field being specified. For more information, see the detailed message.

noMemory Out of memory .

RAPID User’s Guide

DtrJobApp

Inheritance

The DtrJobApp class provides the minimum implementation necessary to process an DataRight job file.

FirstlogicDbRecordInfo

FirstlogicDb

|__

FirstlogicApp

|__

|__ DtrJobApp

Detailed description

Method list

The DtrJobApp class defines all the properties, methods, and events needed to create DataRight job-file applications, through inheriting from this class. The

DtrJobApp class provides actual implementations of several of the FirstlogicApp class methods.

You would handle the events for this class to do tasks like getting progress messages or using the programmable data source feature, and so on.

DtrJobApp methods can throw DtrJobAppException exception objects.

#include <dtrjob.h>

Method Description

DtrJobApp() Constructor. ~DtrJobApp() Destructor. GetProcessState() Returns the current processing state. GetRevision() Returns the revision string of the DataRight product includ-

ing its constituent libraries.

ProcessJob() Processes the specified DataRight job file.

Chapter 3: C++

DtrJobApp method details

DtrJobApp()

DtrJobApp::DtrJobApp() throw(DtrJobAppException)

Constructor.

Exceptions This method can throw DtrJobAppException objects.

~DtrJobApp()

DtrJobApp::~DtrJobApp() [virtual]

Destructor.

GetProcessState()

ProcessState DtrJobApp::GetProcessState (void) [virtual]

Call this method to retrieve the current state of the job. If called be fore the job has started processing, the current state will be “done.”

Return values Returns the current processing state in the ProcessState enumeration.

GetRevision()

const char * DtrJobApp::GetRevision() throw (DtrJobAppException) [virtual]

Call this method to retrieve the revision string of DataRight, including its constituent libraries. This string cannot be modified or delete d.

Returns Returns the revision string of the Business Objects product, including its

constituent libraries. The revision string contains the product's version number, which is often useful to compare with the job file's version.

Exceptions This method can throw DtrJobAppException objects.

ProcessJob()

void DtrJobApp::ProcessJob(const char * jobFileName)throw (DtrJobAppException) [virtual]

Processes the specified DataRight job file. Call this method to process an DataRight job file . Th e file you specify must exist

and not open by another process. ProcessJob() may be called multiple times per instance.

Parameters

Parameter Description

Exceptions

jobFileName

This method can throw DtrJobAppException objects.

A string that contains the name of the job file you want to process.

RAPID User’s Guide

DtrJobAppException

Inheritance

FirstlogicAppException |__ DtrJobAppException

Detailed description

Method List

The DtrJobAppException class is thrown in response to errors that can occur within the DtrJobApp and DtrTransApp classes.

This class is defined in dtrjobex.h. However, you do not need to directly include or inherit from this class. It is merely used by the DtrJobApp class.

Method Description

DtrJobAppException() Constructor. ~DtrJobApp Exception() Destructor. GetExceptionClass Name() Retrieves the name of the exception class. operator=() Assigns the values of a DtrJobAppException object

instance to the values of another DtrJobAppExc e p tio n object instance.

Chapter 3: C++

DtrJobAppException method details

DtrJobAppException()

Parameters

DtrJobAppException::DtrJobAppException(int errorNumber, const char * standardMessage = (char *) 0, const char * detailMessage = (char *) 0)

Constructs a new instance of DtrJobAppException with the specified error, standard and detailed messages.

DtrJobAppException::DtrJobAppException(const DtrJobAppException &)

Constructs a new instance of DtrJobAppException that is a copy of the specified exception.

Parameter Description

errorNumber

standardMessage detailMessage

One of the ErrorNumber enumerated values. An integer indicating the type of exception. See DtrJobAppException

ber

enumeration.

ErrorNum-

A pointer to a string containing the concise error message. A pointer to a string containing more detail about the exception

in a detailed error message.

DtrJobAppException

The exception to copy.

~DtrJobApp

DtrJobAppException::~DtrJobAppException() [virtual]

Exception()

Destructor.

GetExceptionClass

const char * DtrJobAppException::GetExceptionClassName() [virtual]

Name()

Call this method to retrieve the name of the exception class.

Return values DtrJobAppException.

operator=()

DtrJobAppException & DtrJobAppException::operator= (const aObject & e)

Assigns the values of a DtrJobAppException object instance to the values of another DtrJobAppException object instance.

Parameters

Parameter Description

aObject

GetStandardMessage(

const char * DtrJobAppException::GetStandardMessage() [virtual]

)

Call this method to retrieve the abbreviated error message information when an exception occurs.

The exception whose values are to be copied.

RAPID User’s Guide

Return values The return value is a string, which contains the standard error message

information of the error issued.

Enumerations

ErrorNumber These error numbers are generated by the DataRight processing engine and

interpreted by RAPID.

enum DtrJobAppException::ErrorNumber

Available values

Error Description

none No error. noMemory Insufficient memory. ignored Method called out of sequence. jobFailed Job did not complete successfully . internal Internal application error . system System error.

Chapter 3: C++

DtrTransApp

Inheritance

FirstlogicTransApp |__ DtrTransApp

Detailed description

Method List

The DtrTransApp class is used to define the types and methods necessary to perform transactional processing in DataRight.

#include <dtrtrans.h>

Method Description

DtrTransApp() Constructor. ~DtrTransApp() Destructor. GetRevision() Returns the revision string of the DataRight product

including its constituent libraries.

StartJob() Initializes the job. Reimplemented from the

TransApp

class.

Firstlogic-

RAPID User’s Guide

DtrTransApp method details

DtrTransApp()

DtrTransApp::DtrTransApp()

Constructor.

~DtrTransApp()

DtrTransApp::~DtrTransApp() [virtual]

Destructor.

GetRevision()

const char * DtrTransApp::GetRevision() throw (DtrJobAppException) [virtual]

Call this method to retrieve the revision string of DataRight, including its constituent libraries. This string cannot be modified or deleted.

Return values Returns the revision string of DataRight, including its constituent libraries. The

revision string contains DataRight’s version number, which is often useful to compare with the job file's version.

Exceptions This method can throw DtrJobAppException objects.

StartJob()

bool DtrTransApp::StartJob(const char * aJobName, const char * aInputPipe, const char * aOutputPipe) throw

(FirstlogicAppException)

Parameters

Exceptions

Call this method to initialize the transaction object before you process records. Before you call StartJob(), you must have the input/output fields and the input

PW fields already set up or else an error will occur.

Parameter Description

aJobName aInputPipe aOutputPipe

The name of the job file to use for processing. The name of the input programmable data source. The name of the output programmable data source.

This method can throw FirstlogicAppException objects.

Exception Description

FirstlogicAppException::invalidValue The job name, input pipe, and/or output pipe

parameter is null or missing.

FirstlogicAppException::inUse The transaction application is already in use

(that is,

StartJob()

has already been called).

Chapter 3: C++

Exception Description

FirstlogicAppException::system An internal error has occurred. Typically this

is the result of an invalid PW field being specified. For more information, see the detailed message.

FirstlogicAppException::noMemory Out of memory.

RAPID User’s Guide

FirstlogicApp

Inheritance

FirstlogicDbRecordInfo

FirstlogicDb

|__

FirstlogicApp

|__

The FirstlogicApp class is inherited by other classes, which provide actual implementations of several of the FirstlogicApp class methods. You would not inherit from or use this class directly. Instead, you would inherit from

AceJobApp, DtrJobApp, DiqJobApp, IAceJobApp, MpgJobApp, or PstJobApp classes depending on whether you wanted to build an ACE,

DataRight, DataRight IQ, IACE, Match/Consolidate, or Presort application.

Detailed description The FirstlogicApp class defines the minimum properties, methods, and events

needed to create Firstlogic applications.

#include <flapp.h>

Method List

Method Description

FirstlogicApp() Constructor. ~FirstlogicApp() Destructor. AddFirstlogicDb() Attaches a FireCancelEvent() Captures possible cancel events that will be fired after call-

ing the

FireErrorMsgEvent() Captures error message events that may be fired after call-

ing the

FireProgressEvent() Captures progress message events that will be fired after

calling the GetProcessState() Call this method to retrieve the current state of the job. GetRevision() Returns version numbers of all libraries used (RAPID

included). ProcessJob() Processes the specified job file. RemoveFirstlogicDb() Detaches a

object.

FirstlogicDb

ProcessJob()

FirstlogicDb

object to a

method.

object from a

FirstlogicApp

object.

Chapter 3: C++

FirstlogicApp method details

FirstlogicApp()

FirstlogicApp() (alternate method)

Parameters

~FirstlogicApp()

AddFirstlogicDb()

FirstlogicApp::FirstlogicApp()

Constructor.

FirstlogicApp::FirstlogicApp (const char * aName, const FirstlogicDbPWFields & aFields)

Constructor for programmable data source objects.

Parameter Description

aName aFields

FirstlogicApp::~FirstlogicApp() [virtual]

Name of the data source. Information about programmable fields.

Destructor.

void FirstlogicApp::AddFirstlogicDb(FirstlogicDb & aDb) throw (FirstlogicAppException)

Parameters

Exceptions

FireCancelEvent()

Use this method to attach a FirstlogicDb object to a FirstlogicApp object. This method is useful for both transaction processing and job streaming. A FirstlogicDb object can be used to read and write records for a FirstlogicApp object.

The FirstlogicDb object should not be deleted or removed until the object being attached to completes processing. The objec t receiving the FirstlogicDb objec t as an attachment does not make a copy.

Parameter Description

aDb

FirstlogicDb

object reference obtained after creating a

object or a

FirstlogicDbThreadPipe

object and calling the method FirstlogicDbThreadPipe::GetFirstlogicDb(), which returns a

FirstlogicDb

object.

This method can throw FirstlogicAppException objects.

EventResult FirstlogicApp::FireCancelEvent() [virtual]

Call this method to capture cancel events that may be fired after calling the ProcessJob() method.

Return values Returns an EventResult enumeration.

RAPID User’s Guide

FireErrorMsgEvent()

EventResult FirstlogicApp::FireErrorMsgEvent(ErrorMsgType amsgType, const char *msg1, const char *msg2);

Call this method to capture error message events that may be fired after calling the ProcessJob() method.

Return values Returns an EventResult enumeration.

Parameters

Parameter Description

Example

aMsgType

Type of message indicating if the event is a warning or an error. A parameter of type ErrorMsgType.

msg1

String containing the warning or error message. A parameter that holds abbreviated error message information (when a job error occurs).

msg2

String containing additional information about the event. A parameter that holds extended error message information (when a job error occurs).

// This is what the skeleton implementation for your error message event handler might look like.

FirstlogicApp::EventResult MyAppClass::FireErrorMsgEvent (FirstlogicApp::ErrorMsgType msg_type, const char *msg1, const char *msg2)

{

...

// Your code to display error messages, when error message events are fired.

...

FireProgressEvent()

}

EventResult FirstlogicApp::FireProgressEvent(ProgressType aMsgType, const char *msg1, const char *msg2) [virtual]

Call this method to capture progress message events that may be fired after calling the ProcessJob() method.

Progress messages are divided into three types: title, progress data, and percentage. Title messages indicate the stage of processing, such as verifying, beginning job execution, and so on. The parameter msg1 will contain text indicating the stage and msg2 will be an empty string.

Progress data messages contain more detaile d information about p rocessing, such as the number of records read, number of records filtered, and so on. The exact contents of the message will vary based upon the product, and the frequency in which the messages are sent is specified in the job file. The parameter msg1 will contain text indicating the type of data and msg2 will contain the data.

Chapter 3: C++

Percentage messages contain the percentage of processing that has been completed. The parameter msg1 will contain text indicating the percentage and msg2 will be an empty string.

Return values Returns an EventResult enumeration.

Parameters

Parameter Description

Example

aMsgType msg1

A parameter of type ProgressType. String containing the warning or error message. A parameter that

holds abbreviated error message information (when a job error occurs).

msg2

A parameter that holds progress message information (when some new job progress is made).

// This is what the skeleton implementation for your progress message event handler might look like.

FirstlogicApp::EventResult MyAppClass::FireProgressEvent(FirstlogicApp::ProgressType prog_type, const char *msg1, const char *msg2)

{

...

// Your code to display progress messages, when progress events are fired.

...

}

GetProcessState()

ProcessState FirstlogicApp::GetProcessState(void) [pure virtual]

Call this method to retrieve the current state of the job. If called be fore the job has started processing, the current state will be “done.”

Return values Returns the current processing state in the ProcessState enumeration.

GetRevision()

const char * FirstlogicApp::GetRevision() [pure virtual]

Call this method to retrieve the revision string of the Business Objects product, including its constituent libraries. This string cannot be modified or deleted This is a pure virtual function that is overridden by product-specific classes. This function is reimplemented in AceJobApp, DiqJobApp, DtrJobApp, IAceJobApp, MpgJobApp, and PstJobApp.

Return values Returns the revision string of the Business Objects product, including its

constituent libraries. The revision string contains the product's version number, which is often useful to compare with the job file's version.

RAPID User’s Guide

ProcessJob()

Parameters

void FirstlogicApp::ProcessJob(const char * jobFileName) [pure virtual]

Call this method to cause a specified job file to b e processed. This is a pure virtua l function that is overridden by product-specific classes to process a job. This function is reimplemented in AceJobApp, DiqJobApp, DtrJobApp, IAceJobApp, MpgJobApp, and PstJobApp.

Parameter Description

RemoveFirstlogicDb()

Parameters

Exceptions

jobFileName

void Firstlogic::RemoveFirstlogicDb(FirstlogicDb & aDb) throw (FirstlogicAppException)

String containing the name of the job file you want to process.

Use this method to detach a FirstlogicDb object from a FirstlogicApp object. If a FirstlogicDb object was added to a FirstlogicApp object, the FirstlogicDb

object should not be deleted or removed from the FirstlogicApp object until the FirstlogicApp object completes processing. The FirstlogicApp object to which the FirstlogicDb object was added does not make a copy.

Parameter Description

aDb A

FirstlogicDb

object reference obtained after creating a

object or a

FirstlogicDbThreadPipe

object and calling the method FirstlogicDbThreadPipe::GetFirstlogicDb(), which returns a

FirstlogicDb

object.

This method can throw FirstlogicAppException objects.

Enumerations

AnswerMode

enum FirstlogicApp::AnswerMode

The AnswerMode enum lists the possible values for the m_answerMode property.

Available values:

Value Description

None No warnings/errors are answered automatically. Warning Warnings are answered automatically. All Both errors and warnings are answered automatically.

Chapter 3: C++

ErrorMsgType

enum FirstlogicApp::ErrorMsgType

The ErrorMsgType enum lists the possible types of messages that are passed to the FireErrorMsgEvent() method.

Available values:

Value Description

ErrorMsg The message is an error message. WarningMsg The message is a warning message.

EventResult

ProcessState

enum FirstlogicDb::EventResult

Available values:

Value Description

Error Application event method encountered an error. OK Application event method succeeded.

enum FirstlogicApp::ProcessState

The ProcessState enum lists the possible return types for the GetProcessState() method.

Available values:

Value Description

Verifying Verifying job file. PreProcessing Verification of other settings and initialization of job. Processing Processing job. Done Either job has not started, or processing has completed.

ProgressType

RAPID User’s Guide

enum FirstlogicApp::ProcessState

The ProgressT ype enum lists the possible types of messages that are passed to the FireProgressEvent() method.

Available values:

Value Description

Title Title indicating what stage processing is in. Data General progress data. PctDone Percent of processing complete.

FirstlogicAppException

Inheritance The FirstlogicAppException class does not have a base class.

Detailed description The FirstlogicAppException class defines what the error exception object looks

like for exceptions that may be thrown when errors occur. The FirstlogicAppException class is inherited by other Firstlogic Exception

classes. You don't inherit from this class directly; it is merely used by other classes. Classes that inherit FirstlogicAppException include:

AceJobAppException, DiqJobAppException, DtrJobAppException, MpgJobAppException, and PstJobAppException.

FirstlogicAppException is part of the FirstlogicApp class.

RAPID applications may throw exceptions if a job does not complete successfully. In that case, you may need to handle the FireErrorMsgEvent() generated by the RAPID application in order to see the error number and messages that resulted from the unsuccessful job. Exception objects will be generated for you automatically (as necessary).

#include <flappexc.h>

Method List

Method Description

FirstlogicApp Exception() Constructor. ~FirstlogicApp Exception() Destructor. GetDetailMessage() Retrieves the extended error message information when

an exception occurs. GetErrorNumber() Retrieves the error number when an exception occurs. GetExceptionClass Name() Retrieves the name of the exception class. GetStandardMessage() Retrieves the abbreviated error message information

when an exception occurs. operator=() Call this method to assign the values of an Firstlogi-

cAppException object instance to the values of another

FirstlogicAppException object instance.

Chapter 3: C++

FirstlogicAppException method details

FirstlogicApp Exception()

Parameters

To construct a new exception with th e g i ven error number, message, and detailed message:

FirstlogicAppException::FirstlogicAppException (int aErrorNumber, const char*aStandardMessage=(char*)0, const char*aDetailMessage=(char*)0, bool aRecord=false)

To construct a duplicate copy of an existing object:

FirstlogicAppException::FirstlogicAppException (const FirstlogicAppException & aObject)

Parameter Description

aErrorNumber

An integer indicating the type of exception. See FirstlogicAppException error numbers.

aStandardMessage aDetailMessage aObject

A pointer to a string containing the message. A pointer to a string containing more detail about the exception. The object to copy.

~FirstlogicApp

FirstlogicAppException::~FirstlogicAppException() [virtual]

Exception()

Destructor.

GetDetailMessage()

const char * FirstlogicAppException::GetDetailMessage() [virtual]

Call this method to retrieve the extended error message information when an exception occurs.

Return values The return value is a string, which contains the detailed error message of the error

issued.

GetErrorNumber()

int FirstlogicAppException::GetErrorNumber() [virtual]

Call this method to retrieve the error number when an exception occurs.

Return values This method returns an ErrorNumber enumeration.

GetExceptionClass Name()

const char * FirstlogicAppException::GetExceptionClassName() [virtual]

Call this method to retrieve the name of the exception class.

Return values Returns a string containing the name of this class, such as

FirstlogicAppException.

RAPID User’s Guide

GetStandardMessage(

const char * FirstlogicAppException::GetStandardMessage() [virtual]

)

Call this method to retrieve the abbreviated error message information when an exception occurs.

Return values The return value is a string, which contains the standard error message

information of the error issued.

operator=()

Parameters

Exceptions

Enumerations

ErrorNumber

FirstlogicAppException & FirstlogicAppException::operator= (const FirstlogicAppException & aObject)

Call this method to assign the values of an FirstlogicAppException object instance to the values of another FirstlogicAppException object instance.

Parameter Description

aObject

The exception whose values are to be copied.

FirstlogicAppException::noMemory means that you have run out of memory.

enum FirstlogicAppException::ErrorNumber

These error numbers are generated by the system engine and interpreted by RAPID.

Available values:

Error Description

none No error. noMemory Insufficient memory. noDbOpen No programmable data source is open. invalidFieldNum Invalid field number used while calling a programmable

data source method. invalidValue Invalid value. noFile The file does not exist. invalidFormatFile An error occurred while loading the format file. inUse The

FirstlogicDb

object is already in use. system System error. invalidPWFieldNum The value used to retrieve a PW field was out of range. For

example, requesting the 10th PW field when only five PW

fields exist. timeout Processing timeout period was reached. undefined An undefined error occurred.

Chapter 3: C++

For more information about the specific error(s) thrown by a method, see that method's documentation.

Reimplemented in AceJobAppException, DiqJobAppException,

DtrJobAppException, IAceJobAppException, MpgJobAppException, and PstJobAppException.

RAPID User’s Guide

FirstlogicDb

Inheritance

FirstlogicDbRecordInfo |__ FirstlogicDb

Detailed description

The FirstlogicDb class is used to pass database records to a RAPID job file as it reads them and to receive database records from a RAPID job file as it writes them.

The FirstlogicDb class does not support a copy constructor and the assignment operator.

The FirstlogicDb class has four virtual methods that the application may implement:

Method Description

FireDbOpenEvent() Called when the RAPID application wants to

base.

FireDbCloseEvent() Called when the RAPID application wants to

base.

FireDbReadEvent() Called when the RAPID application wants to

from

the database.

FireDbWriteEvent() Called when the RAPID application wants to

the database.

open

the data-

read a record

write a record

The RAPID application has two ways to initialize a FirstlogicDb object: either with a FirstlogicProgRecordFormat object or with a FirstlogicDbPWFields object. If the FirstlogicDb object is initialized with

FirstlogicProgRecordFormat, no PW fields will be defined for that FirstlogicDb object unless a default definition (.def) file is specified in the

application’s job-file settings. After a FirstlogicDb object is created, the application may query the record

format by using the FirstlogicDbRecordInfo methods.

#include <fldb.h>

Method List You can call these methods only when in your FireDbReadEvent() or

FireDbWriteEvent() event handlers.

Method Description

FirstlogicDb() A FirstlogicDb object passes database records to a RAPID

application as it reads them and receives database records from a RAPID application as it writes them.

~FirstlogicDb() Destructor.

Chapter 3: C++

Method Description

FireDbCloseEvent() Fired when a programmable data source can be closed. FireDbOpenEvent() Fired when a programmable data source should be opened. FireDbReadEvent() Inputs records for processing when using programmable

input files.

FireDbWriteEvent() Outputs processed records when using programmable output

files.

GetDbName() Retrieves the name of the current programmable data source

(from the input and output blocks in your job file); or it retrieves the name passed to the FirstlogicDb constructor.

GetFieldByteLen()

Retrieves the length of the specified field in bytes.

GetFieldDepInfo() Retrieves the field dependent information for a particular

field of your programmable data source.

GetFieldLen() Retrieves the field length for a particular field of the current

programmable data source.

GetFieldName() Retrieves the field name for a particular field of the current

programmable data source.

GetFieldPos() Retrieves the field position for a particular field of the current

programmable data source.

GetFieldType() Retrieves the field type for a particular field of the current

programmable data source.

GetMinEncodingSize()

Retrieves the value of the member variable that contains the minimum encoding width.

GetNumFields() Retrieves the number of fields in the current record, as speci-

fied in your

.fmt

file for a particular programmable data

source.

GetNumRecords() Retrieves the number of records that has been set for a First-

logicDb object.

GetRecord() Retrieves the record data for the current record number in

your FireDbWriteEvent event handler.

RAPID User’s Guide

GetRecordByteLen()

Retrieves the record length in bytes.

GetRecordLen() Retrieves the length of the current record, as specified in your

.fmt

file for a particular programmable data source.

GetRecordNumber() Retrieves the record number of the current record for a par-

ticular programmable data source.

SetNumRecords() S ets the num ber of records you will be selecting from your

programmable data source.

SetRecord() Sets the record data for the current record number in your

FireDbReadEvent event handler.

FirstlogicDb method details

FirstlogicDb() To construct a new programmable data source with the given name and format.

FirstlogicDb::FirstlogicDb (const char* aName, const FirstlogicDbRecordFormat & aFormat) throw (FirstlogicAppException)

To construct a new programmable data source with the given name and PW fields.

FirstlogicDb::FirstlogicDb (const char* aName, const FirstlogicDbPWFields & aFields) throw (FirstlogicAppException)

Two constructors are available for creating FirstlogicDb objects.

If the programmable data source is for output

The first constructor accepts a name for your programmable data source and FirstlogicDbRecordFormat object reference as parameters. Use this constructor if you will be using a default definition (.def) file in your RAPID application’s job-file settings. (If the data source will be used for input, call the constructor with a FirstlogicDbPWFields parameter instead.)

If the programmable data source is for either input or output

The second constructor accepts a name for your programmable data source and FirstlogicDbPWFields object reference as parameters. Use this constructor if you will be defining the PW fields for this object, and not be using a default definition (.def) file in your RAPID application’s job-file settings.

Parameters

A FirstlogicDb object passes database records to a RAPID application as it reads them and receives database records from a RAPID application as it writes them.

FirstlogicDb objects are derived from the FirstlogicDbRecordInfo class. FirstlogicDb objects do not support a copy constructor or the assignment

operator. A FirstlogicDb object is made available to a FirstlogicApp object by passing the

FirstlogicDb object to the FirstlogicApp object's AddFirstlogicDb() method. The name of a programmable data source must match the name as seen in the

corresponding block of the job file, including any path information (if present). For input data sources this is typically the Create Input File bloc k. For output data sources it is typically the Post to Output File block (Note: In Presort jobs it will be one of the XXXX Output File blocks).

Parameter Description

aFields aFormat aName

PW Fields to use. Record format to use. Name of the programmable data source.

Exceptions

This method can throw FirstlogicAppException objects.

Chapter 3: C++

~FirstlogicDb()

FirstlogicDb::~FirstlogicDb() [virtual]

Destructor.

FireDbOpenEvent()

EventResult FirstlogicDb::FireDbOpenEvent() [virtual]

This event is fired to open a programmable data source. It is typically called several times by the application's ProcessJob() function. For example, it may be called initially during the verification stage to make sure that the programmable data source exists. Later, during the processing stage, it will be called again prior to the read/write events. Unless an error is returned, FireDbCloseEvent() will be called to close the programmable data source. You need to open/close your programmable data source only once, so be aware that the event is actually fired twice.

Override this function if you want to perform custom processing during the opening of a programmable data source, such as opening an input file. Lengthy tasks, such as establishing a connection to a database server, should be done in a derived class’s constructor, in which case FireDbOpenEvent() should be overridden to return OK if the connection was established.

Return values EventResult is an enumerated return type for the FirstlogicDb event methods.

FireDbCloseEvent()

EventResult FirstlogicDb::FireDbCloseEvent() [virtual]

This event is fired to close a programmable data source. It is typically called several times by the application’s ProcessJob() function. For example, it may be called initially during the verification stage to make sure that the programmable data source exists. Later, during the processing stage, it will be called again after the read/write events have completed. You need to open/close your programmable data source only once, so be aware that the event is actually fired twice.

FireDbReadEvent()

RAPID User’s Guide

You can use this method to know when to close your programmable data source without waiting until the job is finished processing.

Override this function if you want to perform custom processing during the closing of a programmable data source, such as closing an input file. Lengthy tasks, such as closing a connection to a database server, should be done in a derived class’s destructor.

FireDbCloseEvent() should return EventResult::OK if the programmable data source was successfully closed.

Return values: EventResult is an enumerated return type for the FirstlogicDb event methods.

EventResult FirstlogicDb::FireDbReadEvent() [virtual]

Call this method to input records for processing when using programmable input files.

This function is called by the framework to read a record of input from a programmable data source.

This function will be called repeatedly from within a loop until all records have been read. If the programmable data source is being used exclusively for output this function will not be called.

SetRecord() should be called from within FireDbReadEvent() to indicate that a record is available for processing. If SetRecord() is not called, the framework will assume that the programmable data source is empty and processing will end.

The default implementation returns EventResult::OK without calli ng SetRecord(), which indicates that all records have been read and processing should end. Override this method to perform custom pro cessing such as retrieving a record from a result set.

Return values EventResult is an enumerated return type for the FirstlogicDb event methods.

FireDbWriteEvent()

EventResult FirstlogicDb::FireDbWriteEvent() [virtual]

Call this method to output processed records when using programmable output files.

This function will be called repeatedly from within a loop until all records have been written. If the programmable data source is being used exclusively for input, this function will not be called.

GetRecord() should be called from within FireDbWriteEvent() to retrieve the processed record. GetNumFields(), GetFieldPos(), and GetFieldLen() can be used to parse the individual fields out of the buffer returned by GetRecord().

The default implementation returns EventResult::OK. Override this method to perform custom processing, such as inserting a record into a relational table.

Return values EventResult is an enumerated return type for the FirstlogicDb event methods.

GetDbName()

const char * FirstlogicDb::GetDbName() const throw (FirstlogicAppException)

Call this method to retrieve the name of the current programmable data source (from the corresponding input and output file block in your job file). This method may be called only from within the read and write event handlers.

Return values The return value is a string, which contains a programmable data source name.

Exceptions This method can throw FirstlogicAppException objects.

GetFieldByteLen() int FirstlogicDb::GetFieldByteLen (int aField) throw

(FirstlogicAppException)

Call this method to retrieve the length of aField in bytes.

Return values The return value is an integer, whose value is the length of the field in bytes.

In a non-Unicode database, this value will be the same as the value returned by GetFieldLen(). In a Unicode database, this is the value returned by

Chapter 3: C++

Parameters

GetFieldLen() multiplied by the minimum encoding size , which is retrieved with GetMinEncodingSize().

If the minimum encoding size has not been calculated yet, -1 is returned.

Parameter Description

Exceptions

GetFieldDepInfo()

aField

This method can throw FirstlogicAppException objects.

const char * FirstlogicDb::GetFieldDepInfo(int fieldNum) const throw (FirstlogicAppException) [virtual]

The field number of a programmable data source you want to retrieve information for, as listed in the

.fmt

file.

Call this method to retrieve field dependent information for a particular field. Field dependant information varies upon the fi eld type. For example, you could use GetFieldDepInfo() to retrieve the date format of a given date field.

Return values The return value is a string, which contains the field dependent information for

the specified programmable data source field. (If no dependant information exists, this call returns an empty string.) The returned value should not be modified by the caller.

Parameters

Parameter Description

fieldNum

An integer value that is greater than or equal to 1 and less than or equal to the value returned by

GetNumFields()

The field number of the current programmable data source you want to retrieve information for, as listed in the

.fmt

file. This method may only be called from within your read and write event handlers.

Exceptions

GetFieldLen()

This method can throw FirstlogicAppException objects.

int FirstlogicDb::GetFieldLen(int fieldNum) const throw (FirstlogicAppException) [virtual]

Call this method to retrieve the field length for a particular field of the current programmable data source. This method may only be called from within your read and write event handlers.

Return values The return value is a numeric value, which contains the field length of the

specified field in a programmable data source.

RAPID User’s Guide

Parameters

Parameter Description

fieldNum

Exceptions This method can throw FirstlogicAppException objects.

GetFieldName()

const char *FirstlogicDb::GetFieldName(int aFieldNum) const throw (FirstlogicAppException) [virtual]

The field number of a programmable data source you want to retrieve information for, as listed in the

.fmt

file.

Call this method to retrieve the field name for a particular field of the current programmable data source. This method may be called only from within your read and write event handlers.

Return values The return value is a string, which contains the field name information of the

specified field for a programmable data source.

Parameters

Parameter Description

aFieldNum

An integer value that is greater than or equal to 1 and less than or equal to the value returned by

GetNumFields()

The field number of a programmable data source you want to retrieve information for, as listed in the

.fmt

file.

Exceptions

GetFieldPos()

This method can throw FirstlogicAppException objects.

int FirstlogicDb::GetFieldPos(int aFieldNum) const throw (FirstlogicAppException) [virtual]

Call this method to retrieve the field position for a particular field of the current programmable data source. This method may be called only from within your the FireDbReadEvent() and FireDbWriteEvent() functions.

Return values The return value is a numeric value, which contains the starting location of the

specified field in a programmable data source. The value will be greater than or equal to 0 and less than the value returned by GetRecordLen().

Parameters

Parameter Description

aFieldNum

The field number of a programmable data source you want to retrieve information for, as listed in the

.fmt

file. It is an integer value that is greater than or equal to 1 and less than or equal to the value returned by GetNumFields().

Exceptions

This method can throw FirstlogicAppException objects.

Chapter 3: C++

GetFieldType()

FieldType FirstlogicDb::GetFieldType (int aFieldNum) const throw (FirstlogicAppException) [virtual]

Call this method to retrieve the field type for a particular field of the current programmable data source. This method may be called only from within your read and write event handlers.

Return values FieldType is an enumerated return type for this method.

Parameters

Parameter Description

aFieldNum

An integer value that is greater than or equal to 1 and less than or equal to the value returned by

GetNumFields()

The field number of a programmable data source you want to get

Exceptions

information for, as listed in the

This method can throw FirstlogicAppException objects.

.fmt

file.

GetMinEncodingSize() int FirstlogicDb::GetMinEncodingSize (void)

Call this method to retrieve the value of the member variable that contains the minimum encoding width.

Return values Returns the value of m_nEncSize member variable. If this value has not been

calculated yet, -1 is returned.

GetNumFields()

int FirstlogicDb::GetNumFields() const throw (FirstlogicAppException) [virtual]

Call this method to retrieve the nu mber of fields in the current record , as specified in your .fmt file for the current programmable data source. This method may be called only from within your read and write event handlers.

Return values The return value is a numeric value, which contains the number of fields in a

programmable data source.

Exceptions This method can throw FirstlogicAppException objects.

GetNumRecords()

long FirstlogicDb::GetNumRecords() const

Call this method to retrieve the number of records that has been set for a FirstlogicDb object.

The number returned here will be 0 unless SetNumRecords() has been called with a different value.

Return values The number of records that was originally set for a FirstlogicDb object by a prior

call to SetNumRecords() is returned as a long.

RAPID User’s Guide

GetRecord()

const char * FirstlogicDb::GetRecord() const throw (FirstlogicAppException)

Call this method to retrieve the record data for the current record number in your FireDbWriteEvent() event handler. This method can be called only from inside your write event handler.

GetNumFields(), GetFieldPos(), and GetFieldLen() can be used to parse the individual fields out of the buffer returned by GetRecord().

Return values The return value is a string, which contains the record data for the current record

while in your FireDbWriteEvent() event handler.

Exceptions This method can throw FirstlogicAppException objects.

GetRecordByteLen() int FirstlogicDb::GetRecordByteLen (void) throw

(FirstlogicAppException)

Call this method to retrieve the record length in bytes.

Return values The return value is an integer that represents the length of the record in bytes.

In a non-Unicode database, this value will be the same as the value returned by

GetRecordLen(). In a Unicode database, this is the value returned by GetRecordLen() multiplied by the minimum encoding size.

If the minimum encoding size has not been calculated yet, -1 is returned.

Exceptions This method can throw FirstlogicAppException objects.

GetRecordLen()

int FirstlogicDb::GetRecordLen() const throw (FirstlogicAppException) [virtual]

Call this method to retrieve the length of the current record, as specified in your .fmt file for the current programmable data source. This method may be called only from within your read and write event handlers.

Return values The return value is a numeric value, which contains the record length of the

current programmable data source, as specified in the .fmt file.

Exceptions This method can throw FirstlogicAppException objects.

GetRecordNumber()

long FirstlogicDb::GetRecordNumber() const throw (FirstlogicAppException)

Call this method to retrieve the record number of the current record for the current programmable data source. This method may only be called from within your read and write event handlers—that is, FireDbReadEvent() and FireDbWriteEvent().

Return values The return value is an long value, which contains the record number of the current

record for the current programmable data source.

Chapter 3: C++

Exceptions This method can throw FirstlogicAppException objects.

SetNumRecords()

SetRecord()

Parameters

void FirstlogicDb::SetNumRecords(long aNumRecords) throw (FirstlogicAppException)

Call this method if you know ahead of time how many records you will be selecting from your programmable data source. This number is then used in progress messages in cases where the progress message needs to know the number of records. Otherwise, N/A is used if the number of records for a programmable data source is not known, and the number was needed for a progress message. This method is optional.

A call to a FirstlogicDb object's SetNumRecords() method mu st be made b efore the FirstlogicDb object is added to a FirstlogicApp.

void FirstlogicDb::SetRecord(const char * record) throw (FirstlogicAppException)

Call this method to set the record data for the current record number in your DbRead event handler. This method can be called only from inside your read event handler.

Parameter Description

record

A string which contains the record data for the current record in the current programmable data source.

Exceptions This method can throw FirstlogicAppException objects.

Enumerations

EventResult

FirstlogicDb::EventResult

Available values:

Value Description

Error Application event method encountered an error. OK Application event method succeeded.

RAPID User’s Guide

FirstlogicDbPWFields

Inheritance The FirstlogicDbPWFields class does not have a base class.

Detailed description The Database PW Fields class (FirstlogicDbPWFields) is used to define the PW

fields for a Business Objects application. This class supports a copy constructor and the assignment operator.

Once a FirstlogicDbPWFields object is created, the application may query the PW fields by using the methods of this class. After a FirstlogicDbPWFields object is used in the constructor of another obj ect, such a s FirstlogicDb objec t, it can be destroyed because the receiving object makes a copy.

#include <fldbpw.h>

Method List

Method Description

FirstlogicDbPWFields() The Database PW Fields class (

is used to describe a set of PW fields to be used later by a database.

Constructs a new object, loading the PW fields from a

definition ( ~FirstlogicDbPW Fields() Destructor. AllocCopy() Get a new copy of an existing object. GetDbRecordFormat() Retrieves the record layout that was used in the construc-

tion of a particular GetDefFile() Retrieves the definition file that will be used during pro-

cessing. GetPWFieldBuffer() Retrieves the PW field buffer. operator=() Sets an object equal to another object (that is, copy object

A to object B). SetDbRecordFormat() Sets the record format to associate with the PW fields. SetDefFile() Sets the definition file that will be used during process-

ing.

.def

) file.

FirstlogicDbPWFields

object.

)

Chapter 3: C++

FirstlogicDbPWFields method details

FirstlogicDbPWFields( )

Parameters

To construct a new object, loading the PW fields from a definition (.def) file.

FirstlogicDbPWFields::FirstlogicDbPWFields (const FirstlogicDbRecordFormat & recFmt, const char* defFile) throw (FirstlogicAppException)

To construct a duplicate copy of an existing object.

FirstlogicDbPWFields::FirstlogicDbPWFields (const FirstlogicDbPWFields & pwFields)throw (FirstlogicAppException)

You use the Database PW Fields class (FirstlogicDbPWFields) to describe a set of PW fields to be used later by a database. The FirstlogicDbPWFields class supports a copy constructor and the assignment operator.

The FirstlogicDbPWFields constructor takes a FirstlogicDbRecordFormat object as an argument to its constructor as well as a definition (.def) file.

Parameter Description

recFmt The record format to associate with the PW fields.

FirstlogicDbRecordFormat

an object of this type before creating a The

FirstlogicDbRecordFormat

PWFields

object's constructor.

object reference. Y ou must first create

FirstlogicDbPWFields

object is passed into the

object.

FirstlogicDb-

Exceptions

~FirstlogicDbPW Fields()

AllocCopy()

defFile The name of the definition file to load.

A parameter of constant character string pointer that should reference a string that contains the path and file name of a definition (

.def

) file. The definition file used should describe the desired Postware (PW) fields of a programmable data source that you want to use.

pwFields The object to copy.

This method can throw FirstlogicAppException objects.

Exception Description

FirstlogicAppException::noMemory Out of memory. FirstlogicAppException::noFile The specified file does not exist.

FirstlogicDbPWFields::~FirstlogicDbPWFields() [virtual]

Destructor.

FirstlogicDbPWFields * FirstlogicDbPWFields::AllocCopy() const throw (FirstlogicAppException) [virtual]

Call this method to get a new copy of an existing object. The returned object may or may not be of the same type as the class you called it

from. It could, for example, be a derived class.

RAPID User’s Guide

Exceptions

The caller is responsible for freeing the returned copy when they've finished with it.

Exception Description

FirstlogicAppException::noMemory Out of memory.

GetDbRecordFormat()

const FirstlogicDbRecordFormat & FirstlogicDbPWFields::GetDbRecordFormat() const

Call this method to obtain the record layo ut t hat was used in the co nstr uctio n of a particular FirstlogicDbPWFields object. A constant

FirstlogicDbRecordFormat object reference is returned. You may use the FirstlogicDbRecordFormat class's methods to query the FirstlogicDbRecordFormat object's properties.

Return values A constant FirstlogicDbRecordFormat object reference i s returned. You can use

the FirstlogicDbRecordFormat class's methods to query the FirstlogicDbRecordFormat object's properties to obtain the record layout that was used in the construction of the FirstlogicDbPWFields object.

GetDefFile()

const char * FirstlogicDbPWFields::GetDefFile() const

Call this method to retrieve the definition file that will be used during processing.

Return values Returns the file to use during processing. If the file has not been set, an empty

string will be returned.

GetPWFieldBuffer()

const char * FirstlogicDbPWFields::GetPWFieldBuffer() [virtual]

This method is called by the framework to retrieve a pointer t o a string con taining the PW field associations.

The string will be formatted the same as the contents of a .def file. If no PW fields were added, the buffer will contain only the database type and name format lines.

Return values Returns a buffer that contains the definitions of the fields, the database type, and

the names of the fields (similar to the contents of a .def file).

operator=()

FirstlogicDbPWFields & FirstlogicDbPWFields::operator= (const FirstlogicDbPWFields & pwFields)

Set an object equal to another object (copy object A to object B).

Parameters

Parameter Description

pwFields The object to copy.

Chapter 3: C++

Exceptions

Exception Description

FirstlogicAppException::noMemory Out of memory.

SetDbRecordFormat()

Parameters

Exceptions

SetDefFile()

Parameters

void FirstlogicDbPWFields::SetDbRecordFormat (const FirstlogicDbRecordFormat & recFmt) throw (FirstlogicAppException)

Call this method to set the record format to associate with the PW fields.

Parameter Description

recFmt

Exception Description

The record format to associate with the PW fields.

FirstlogicAppException::noMemory Out of memory.

void FirstlogicDbPWFields::SetDefFile(const char * defFile) throw (FirstlogicAppException)

Call this method to set the definition file that will be used during processing.

Parameter Description

Exceptions

defFile

The name of the definition file to use.

This method can throw FirstlogicAppException objects.

Exception Description

noMemory Out of memory. noFile The specified file does not exist.

RAPID User’s Guide

FirstlogicDbRecordFormat

Inheritance

FirstlogicDbRecordInfo |__ FirstlogicDbRecordFormat

Detailed description

Method List

The purpose of the Database Record Format class (FirstlogicDbRecordFormat) is to define a database record layout.

The FirstlogicDbRecordFormat class is derived from the FirstlogicDbRecordInfo class, and it supports a copy constructor and the assignment operator.

Once a FirstlogicDbRecordFormat object is created, the application may query the record format by using the methods of this class. After a FirstlogicDbRecordFormat object is used in the constructor of another object, such as FirstlogicProgPWFields object, it can be destroyed because the receiving object makes a copy.

#include <fldbrec.h>

Method Description

FirstlogicDbRecord Format() Constructs a FirstlogicDbRecordFormat object using a

format ( ~FirstlogicDbRecord Format() Destructor. AllocCopy() G et a new copy of an existing object. FieldExists() Call this method to test whether a field exists.

.fmt

) file.

GetFieldDepInfo() Retrieves the field dependent information for a particu-

lar field of your programmable data source. GetFieldLen() Retrieves the field length for a particular field of the

current programmable data source. GetFieldName() Retrieves the field name for a particular field of the

current programmable data source. GetFieldPos() Retrieves the field position for a particular field of the

current programmable data source. GetFieldType() Retrieves the field type for a particular field of the cur-

rent programmable data source. GetNumFields() Retrieves the number of fields in the current record, as

specified in your

ble data source. GetRecordLen() Retrieves the length of the current record, as specified

in your

.fmt

source.

.fmt

file for a particular programma-

file for a particular programmable data

Chapter 3: C++

Method Description

operator=() Call this method to assign the values of an FirstlogicD-

bRecordFormat object instance to the values of another FirstlogicDbRecordFormat object instance.

RAPID User’s Guide

FirstlogicDbRecordFormat method details

FirstlogicDbRecord Format()

Parameters

To construct a new object, loadi ng the record layout from a format (.fmt) file.

FirstlogicDbRecordFormat::FirstlogicDbRecordFormat (const char* formatFile) throw (FirstlogicAppException)

To construct a duplicate copy of an existing object.

FirstlogicDbRecordFormat::FirstlogicDbRecordFormat (const FirstlogicDbRecordFormat & aFormat) throw (FirstlogicAppException)

Default constructor. Descendant classes may use this constructor to construct a new, uninitialized object.

FirstlogicDbRecordFormat::FirstlogicDbRecordFormat() throw(FirstlogicAppException)

Call this method to construct a FirstlogicDbRecordFormat object using a format (.fmt) file. Set the record layout of a FirstlogicDbRecordFormat through a format file (.fmt) passed in as a parameter to this constructor. You can then use the created FirstlogicDbRecordFormat object to create other objects that use this object in their constructors.

The format file used should describe the record layout of a programmable data source that you want to use.

Exceptions

~FirstlogicDbRecord Format()

AllocCopy()

Parameter Description

formatFile

The name of the format file to load. A parameter of constant character string pointer that should reference a string that contains the path and file name of a format (

aFormat

Exception Description

The object to copy.

.fmt

) file.

FirstlogicAppException::noMemory Out of memory. FirstlogicAppException::noFile The specified file does not exist. FirstlogicAppException::invalidFormatFile The file exists but is not a valid format

file.

FirstlogicDbRecordFormat::~FirstlogicDbRecordFormat() [virtual]

Destructor.

FirstlogicDbRecordFormat * FirstlogicDbRecordFormat::AllocCopy() const throw (FirstlogicAppException) [virtual]

Call this method to retrieve a new copy of an existing object.

Chapter 3: C++

Exceptions

The returned object may or may not be of the same type as the class you called it from. It could, for example, be a derived class.

The caller is responsible for freeing the returned copy when they've finished with it.

Exception Description

FirstlogicAppException::noMemory Out of memory.

FieldExists()

bool FirstlogicDbRecordFormat::FieldExists(const char * afieldName)

Call this method to test whether a field exists.

Parameters

Parameter Description

GetFieldDepInfo()

aFieldName

const char * FirstlogicDbRecordFormat::GetFieldDepInfo(int fieldNum) const throw (FirstlogicAppException) [virtual]

The name of a field.

Return values The return value is a string, which contains the field dependent information for

the specified programmable data source field. (If no dependant information exists, this call returns an empty string.) The returned value should not be modified by the caller.

Parameters

Exceptions

GetFieldLen()

RAPID User’s Guide

Parameter Description

fieldNum

An integer value that is greater than or equal to 1 and less than or equal to the value returned by

GetNumFields()

The field number of the current programmable data source you want to retrieve information for, as listed in the

.fmt

file. This method may only

be called from within your read and write event handlers.

This method can throw FirstlogicAppException objects.

int FirstlogicDbRecordFormat::GetFieldLen(int fieldNum) const throw (FirstlogicAppException) [virtual]

Call this method to retrieve the field length for a particular field of the current programmable data source. This method may be called only from within your read and write event handlers.

Return values The return value is a numeric value, which contains the field length of the

specified field in a programmable data source.

Parameters

Parameter Description

fieldNum

Exceptions This method can throw FirstlogicAppException objects.

GetFieldName()

const char *FirstlogicDbRecordFormat::GetFieldName (int fieldNum) const throw (FirstlogicAppException) [virtual]

The field number of a programmable data source you want to retrieve

.fmt

information for, as listed in the

file.

Call this method to retrieve the field name for a particular field of the current programmable data source. This method may be called only from within your read and write event handlers.

Return values The return value is a string, which contains the field name information of the

specified field for a programmable data source.

Parameters

Parameter Description

fieldNum

An integer value that is greater than or equal to 1 and less than or equal to the value returned by

GetNumFields()

The field number of a programmable data source you want to retrieve information for, as listed in the

.fmt

file.

Exceptions

GetFieldPos()

This method can throw FirstlogicAppException objects.

int FirstlogicDbRecordFormat::GetFieldPos(int fieldNum) const throw (FirstlogicAppException) [virtual]

Call this method to retrieve the field position for a particular field of the current programmable data source. This method may be called only from within your read and write event handlers.

Return values The return value is a numeric value, which contains the field position of the

specified field in a programmable data source.

Parameters

Parameter Description

Exceptions

fieldNum

This method can throw FirstlogicAppException objects.

The field number of a programmable data source you want to retrieve information for, as listed in the

.fmt

file.

Chapter 3: C++

GetFieldType()

FieldType FirstlogicDbRecordFormat::GetFieldType (int fieldNum) const throw (FirstlogicAppException) [virtual]

Call this method to retrieve the field type for a particular field of the current programmable data source. This method may be called only from within your read and write event handlers.

Return values FieldType is an enumerated return type for this method.

Parameters

Parameter Description

Exceptions

GetNumFields()

fieldNum

This method can throw FirstlogicAppException objects.

int FirstlogicDbRecordFormat::GetNumFields() const [virtual]

The field number of a programmable data source you want to retrieve information for, as listed in the

.fmt

file.

Return values The return value is a numeric value, which contains the number of fields in a

programmable data source.

Exceptions This method can throw FirstlogicAppException objects.

GetRecordLen()

int FirstlogicDbRecordFormat::GetRecordLen() const [virtual]

Return values The return value is a numeric value, which contains the record length of the

current programmable data source, as specified in the .fmt file.

Exceptions This method can throw FirstlogicAppException objects.

operator=()

FirstlogicDbRecordFormat & FirstlogicDbRecordFormat::operator= (const FirstlogicDbRecordFormat & aFormat)

Call this method to assign the values of an FirstlogicDbRecordFormat object instance to the values of another FirstlogicDbRecordFormat object instance.

Parameters

Parameter Description

aFormat

RAPID User’s Guide

The object to copy.

Exceptions This method throws FirstlogicAppException objects:

Parameter Description

noMemory Out of memory.

Chapter 3: C++

FirstlogicDbRecordInfo

Inheritance This class—a pure virtual class—is the base class for the

FirstlogicDbRecordFormat, FirstlogicProgRecordFormat, and FirstlogicDb classes.

Don't create objects of this type. Instead, use either FirstlogicDbRecordFormat or FirstlogicProgRecordFormat to specify the record format for a programmable data source.

Detailed description The Database Record Information class (FirstlogicDbRecordInfo) is used to

define the types and methods necessary to describe the record layout of a programmable data source.

#include <fldbrec.h>

Method List You can only call these methods when in your FireDbReadEvent or

FireDbWriteEvent event handlers.

Method Description

GetFieldDepInfo() Retrieves the field dependent information for a particu-

lar field of your programmable data source.

GetFieldLen() Retrieves the field length for a particular field of the

current programmable data source.

GetFieldName() Retrieves the field name for a particular field of the

current programmable data source.

GetFieldPos() Retrieves the field position for a particular field of the

current programmable data source.

GetFieldType() Retrieves the field type for a particular field of the cur-

rent programmable data source.

GetNumFields() Retrieves the number of fields in the current record, as

specified in your ble data source.

GetRecordLen() Retrieves the length of the current record, as specified

in your

.fmt

source.

.fmt

file for a particular programma-

file for a particular programmable data

100

RAPID User’s Guide

Business objects RAPID 2.20C User Manual

Specifications and Main Features

Frequently Asked Questions

User Manual

Contents

Preface

What is RAPID?

How does RAPID work?

What interfaces are available?

.NET support All RAPID products can be compiled using the Visual Studio 2003 .NET

How RAPID works Below is a brief conceptual overview of a possible RAPID implementation in a

Setting up your job processes

Available interfaces RAPID is available with the following interfaces:

About Business Objects’ RAPID products

ACE and International ACE

DataRight: Database standardization

DataRight IQ: beyond name and address standardization

Match/Consolidate: Finding duplicate (matching) records

Presort: sortation and preparation for mailing

Components of a RAPID application

The major pieces A RAPID application is made up of a few major components: calls to RAPID

Your RAPID application

Job files RAPID applications make use of files that control business rules, and specify

Other supporting files Finally , there are two other types of supp orting files that you may encounter when

Introduction to job files

Format of job files Job files are text files that can be edited through a Views program or text editor.

Making copies of files before editing

Editing a job file through a text editor

Editing a job file through Views

About the C++ interface

Inheritance interface RAPID's C++ interface is an inheritance interface, meaning that it lets you in herit

Virtual methods Several inherited methods are virtual and may be overridden. For example, event

Dependencies to job file

Unicode support The RAPID C++ interface includes support for Unicode data. For more

.NET support All RAPID products can be compiled using the Visual Studio 2003 .NET

About the Java interface

Wrapper classes For its Java interface, RAPID uses Java wrapper classes. These classes use JNI

Requirements RAPID requires Java 1.4. RAPID needs weak global references to resolve

Enumerations Java does not support enumerations. Methods that have a C++ counterpart that

Packages T o avoid namespace collisions, Java cla sses are organized into pac kages. Package

Unicode support The RAPID Java interface does not support Unicode at this time. If you need

About the ActiveX interface

RAPID ActiveX controls

Integrating RAPID ActiveX objects in MSVC

Integrating ActiveX objects in Visual Basic

Unicode support The RAPID ActiveX interface does not support Unicode at this time. If you need

.NET support All RAPID products can be compiled using the Visual Studio 2003 .NET

Sample programs

ActiveX samples There are two ActiveX samples for RAPID. The ActiveX samples are written in

Where are the RAPID samples?

Using the samples with another product

Event handling

Overriding event handlers in C++

Overriding event handlers in Visual Basic

Error handling

The exception objects Generally, it is sufficient to catch only FirstlogicAppException objects.

Error handling with C++

Error handling with ActiveX

Using programmable data sources

Integrating a programmable data source

Using programmable input files

DEF file You need a DEF (definition) file that corresponds to your input file (myfile.txt

FMT file A FMT (format) file outlines the physical format of a database (field names,

Input file block In the job file used to set your processing options, you need to specify an Input

RAPID API calls After you include these special settings, you can make your RAPID calls. Here is

Using programmable output files

DEF file You need a DEF (definition) file that corresponds to your output file (myfile.txt

FMT file A FMT (format) file outlines the physical format of a database (field names,

Output file block In the job file used to set your processing options, you also need to specify an

RAPID API calls After you include these special settings, you need to make your RAPID calls.

Specifying DEF and FMT settings programmatically

Record formats You can specify record formats by using the FirstlogicProgRecordFormat() class.

Field mappings You can specify field mappings by using the FirstlogicProgPWFields class This

Job streaming (piping) overview

Job-streaming example

Comprehensive class list

C++ classes

Inheritance diagram

Inheritance

AceJobApp