How it Works
Business objects
Loading...
D
E
F
G
H
I
K
L
M
O
P
Loading...
Loading...
INTERNATIONAL ACE 7.70C
User Manual
24 pgs447.86 Kb0
User Manual
294 pgs2.61 Mb0
User Manual
18 pgs300.53 Kb0
User Manual
1 pgs29.78 Kb0
Table of contents
Loading...

Business objects INTERNATIONAL ACE 7.70C User Manual

Download
International ACE
Library Reference
Version 7.70c May 2006
Instructions for installing, compiling, and linking
Typical sequence of function calls
Detailed reference page for each function
Notices
Published in the United States of America by Firstlogic, Inc., 100 Harborview Plaza, La Crosse, Wisconsin 54601-4071.
Customer Care
What do you think of this guide?
Technical help is free for customers who are current on their ESP. Advisors are available from 8 a.m. to 6 p.m. central time, Monday through Friday. When you call, have at hand the user’s manual and the version number of the product you are using. Call from a location where you can operate your software while speaking on the phone. To save time, fax or e-mail your questions, and an advisor will call or e-mail back with answers prepared. Or visit our Knowledge Base on the Customer Care web site, where you can find answers on your own, right away, at any time of the day or night.
Our Customer Care group also manages our customer database and order processing. Call them for order status, shipment tracking, reporting damaged shipments or flawed media, changes in contact information, and so on.
Phone
888-788-9004 in the U.S. and Canada; elsewhere +1-608-788-9000
Web site
E-mail
Product literature
Corporate receptionist
http://www.firstlogic.com/customer customer@firstlogic.com
888-215-6442, fax 608-788-1188, or
information@firstlogic.com
608-782-5000, or fax 608-788-1188
The Firstlogic Technical Publications group strives to bring you the most useful and accurate publications possible. Please give us your opinion about our documentation by filling out the brief survey at http://www.firstlogic.com/customer/surveys/
default.asp. We appreciate your feedback! Thank you!
Legal notices
2
© 2006 Firstlogic, Inc. All rights reserved. This publication and accompanying software are protected by U.S. copyright law and international treaties. No part of this publication or accompanying software may be copied, transferred, or distributed to any person without the express written permission of Firstlogic, Inc.
National ZIP+4 Directory © 2006 United States Postal Service. Firstlogic Directories © 2006 Firstlogic, Inc. All City, ZCF, state ZIP+4, regional ZIP+4, and supporting directories are also protected under the Firstlogic copyright. Firstlogic, Inc. holds a nonexclusive license to publish and sell ZIP+4 databases on optical and magnetic media. The price of the Firstlogic product is neither established, controlled, nor approved by the U.S. Postal Service.
Firstlogic, Inc., or any authorized dealer distributing this product, makes no warranty, expressed or implied, with respect to this computer software product or with respect to this manual or its contents, its quality, performance, merchantability, or fitness for any particular purpose or use. It is solely the responsibility of the purchaser to determine its suitability for a particular purpose or use. Firstlogic, Inc. will in no event be liable for direct, indirect, incidental, or consequential damages resulting from any defect or omission in this software product, this manual, the program disks, or related items and processes, including, but not limited to, any interruption of service, loss of business or anticipatory profit, even if Firstlogic, Inc. has been advised of the possibility of such damages. This statement of limited liability is in lieu of all other warranties or guarantees, expressed or implied, including warranties of merchantability or fitness for a particular purpose.
1L, IL (ball design), ACE, ACSpeed, DataJet, DocuRight, eDataQuality, Entry Planner, Firstlogic, Firstlogic InfoSource, FirstPrep, FirstSolutions, GeoCensus, i·d·Centric, IQ Insight, Label Studio, MailCoder, Match/Consolidate, PostWare, Postalsoft, Postalsoft Address Dictionary, Postalsoft Business Edition by Firstlogic, Postalsoft DeskTop Mailer, Postalsoft DeskTop PostalCoder, Postalsoft DeskTop Presort, Postalsoft Manifest Reporter, PrintForm, RapidKey, Total Rewards, and TrueName are registered trademarks of Firstlogic, Inc. DataRight, IRVE, iSummit, and TaxIQ are trademarks of Firstlogic, Inc. All other trademarks are the property of their respective owners.

Preface

Purpose and contents of this manual

Qualifications

Related documents

This manual is a reference guide for programmers working with International Address Correction and Encoding library, International ACE.
In writing this manual, we have assumed that you already are familiar with your programming language, your compiling and debugging tools, your operating system, and your database-management system. If you are not familiar with these subjects, your integration of International ACE will be more difficult. If you need assistance in these areas, please contact us for referrals and resources.
Our System Administrator’s Guide contains installation instructions and system requirements.
Convention Description
Bold We use boldface type for file names and paths. When we’re
explaining something that you would type on your computer, bold­face indicates something that you should type exactly as shown; for example, “Type
Italics We use italics for emphasis. When we’re explaining something that
you would type on your computer, italics indicate an item for which you should substitute your own data or values; for example, “Type a name for your job, along with the
cd\dirs
.”
.job
extension (
jobname
.job
).”
Complete documentation set
Menu commands We indicate commands that you choose from menus in the follow-
ing format: Menu Name | Command Name. For example, “Choose File | New.”
We use this symbol to alert you to important information and poten­tial problems.
We use this symbol to point out special cases that you should know about.
The complete International ACE documentation set includes the following:
The complete International ACE documentation set includes the following:
International ACE Library Reference Quick Reference for Library Products System Administrator’s Guide International Address Processing: Install the UNIX Runtime Environment (if
you run International ACE on a UNIX platform)
3

Access the latest documentation

You can access Firstlogic documentation in several places:
On your computer. Release notes, manuals, and other documents for each
Firstlogic product that you’ve installed are available in the Documentation folder. Choose Start > Programs > Firstlogic Applications > Documentation.
On the Firstlogic Customer Portal. Go to www.firstlogic.com/customer,
log on using your username and password, and then click the Documentation link to access all the latest Firstlogic documentation. You can view the PDFs online, save them to your computer, or order professionally printed documents that will be delivered to you. To order printed documents, see the following instructions.

Order printed documents

You can order professionally printed documents and have them delivered to you for a small charge. Your documents will be sent to you as soon as the next business day.
1. Go to www.firstlogic.com/customer
, log on using your username and password, click the Documentation link, and then click the Printed Technical Documentation link.
If this is your first time accessing the Mimeo site, you’ll be prompted to open an account before you can log in. Follow the instructions on screen to open an account.
2. Log in to Mimeo.
3. To access Firstlogic documents, in the Folders area on the left side of the Mimeo web site, choose DocCenter Shared Folders > Firstlogic Inc.
DocCenter > Firstlogic’s Printable Materials > Technical Documentation.
4. Choose the documents that you want printed.
5. Follow the instructions on screen to place your order.
4

Contents

Chapter 1:
Working with International ACE.............................................................. 11
Introducing International ACE.......................................................................12
Compiling and running the International engine............................................13
Header files ....................................................................................................15
Sample programs............................................................................................16
Overview of the object-oriented interface......................................................17
Working with the C interface.........................................................................19
Error and warning handling............................................................................21
Thread safety limits for AIX, HP, and Solaris...............................................23
Tips for working with the International engines ............................................24
Accepted address line formats........................................................................25
Sample formats...............................................................................................26
Certification options.......................................................................................28
Typical sequence of function calls for address processing ............................29
Unicode implementation ................................................................................31
Chapter 2:
Global functions........................................................................................... 33
FlNadFaultCodeEnumToString()...................................................................34
FlNadLineEnumToString() ............................................................................35
FlNadOutputCompEnumToString()...............................................................36
getEng()..........................................................................................................37
getErrorObject() .............................................................................................38
getErrorStatus() ..............................................................................................39
getNad()..........................................................................................................40
getQuery() ......................................................................................................41
iaceGetRevision()...........................................................................................42
iieInit()............................................................................................................43
iieTerm().........................................................................................................44
releaseEng()....................................................................................................45
releaseNad() ...................................................................................................46
releaseQry()....................................................................................................47
usSetZ4cCheckDate().....................................................................................48
usZ4Zip4Changed() .......................................................................................49
usZ4Zip4Changed_u() ...................................................................................50
Chapter 3:
PubEngineClass........................................................................................... 51
close().............................................................................................................52
getEngineInfo() ..............................................................................................53
getEngineInfo_u() ..........................................................................................54
getFile() ..........................................................................................................55
getFile_u() ......................................................................................................56
getOption() .....................................................................................................57
getPathName()................................................................................................58
Contents
5
getPathName_u() ........................................................................................... 59
getStatistic()................................................................................................... 60
getType()........................................................................................................ 62
isLineUsed()...................................................................................................63
open()............................................................................................................. 64
setFile() ..........................................................................................................65
setFile_u() ......................................................................................................66
setOption() ..................................................................................................... 67
setPathName()................................................................................................ 69
setPathName_u()............................................................................................ 70
usGetDpvMessage()....................................................................................... 71
usGetDpvMessage_u()................................................................................... 72
Chapter 4:
PubNaddressClass ...................................................................................... 73
getAddressType()...........................................................................................74
GetAssignType()............................................................................................ 75
clear()............................................................................................................. 76
getComponent() ............................................................................................. 77
getComponent_u() ......................................................................................... 79
getComponentLocation()...............................................................................81
getFaultCode() ............................................................................................... 82
getStandardizeLineData() .............................................................................. 83
getStandardizeLineData_u() .......................................................................... 84
getStandardizeLineLength() .......................................................................... 85
getStatus() ......................................................................................................86
getSupportedCountry() ..................................................................................87
insertLineData().............................................................................................88
insertLineData_u().........................................................................................89
openTuner_u() ............................................................................................... 90
process()......................................................................................................... 91
produceReport().............................................................................................93
produceReport_u().........................................................................................94
setReportInfo()...............................................................................................95
setReportInfo()...............................................................................................96
setReportInfo()...............................................................................................97
setReportInfo()...............................................................................................98
setReportInfo().............................................................................................100
setReportInfo_u().........................................................................................101
setStandardizeLineLength()......................................................................... 102
validateLineFormat() ................................................................................... 103
Chapter 5:
PubQueryClass.......................................................................................... 105
Query guidelines for the U.S. engine...........................................................106
Query guidelines for the Canadian engine...................................................107
Typical sequence of function calls for queries ............................................ 108
clear()........................................................................................................... 110
close()...........................................................................................................111
getElement().................................................................................................112
getElement_u().............................................................................................113
getFile()........................................................................................................114
getFile_u()....................................................................................................115
6
getOption() ...................................................................................................116
getPathName()..............................................................................................117
getPathName_u()..........................................................................................118
getThreshold() ..............................................................................................119
getType() ......................................................................................................120
open() ...........................................................................................................121
process() .......................................................................................................122
setElement() .................................................................................................123
setElement_u() .............................................................................................124
setFile().........................................................................................................125
setFile_u().....................................................................................................126
setOption()....................................................................................................127
setPathName() ..............................................................................................128
setPathName_u() ..........................................................................................129
setThreshold()...............................................................................................130
Chapter 6:
PubErrorClass........................................................................................... 131
clear() ...........................................................................................................132
getErrorInfo() ...............................................................................................133
Chapter 7:
Enumerations and types ........................................................................... 135
AssignEngOptionEnum and AssignEngOptionValueEnum........................136
AssignEngIntOptionEnum ...........................................................................150
DPVMessageEnum ......................................................................................151
EngineDateEnum .........................................................................................152
EngineFileEnum...........................................................................................153
EngineInfoEnum ..........................................................................................155
EnginePathNameTypeEnum ........................................................................155
EngineTypeEnum.........................................................................................156
EngineZ4CEnum..........................................................................................156
FlByteType...................................................................................................157
FlCharType...................................................................................................157
FlCountryIdEnum.........................................................................................158
FlErrorWarningMsgEnum ...........................................................................158
FlLanguageIdEnum......................................................................................158
NadAddrTypeEnum .....................................................................................159
NadAssignTypeEnum ..................................................................................160
NadFaultCodeEnum.....................................................................................161
NadLineEnum ..............................................................................................161
NadLineStateEnum ......................................................................................162
NadOutputCompEnum.................................................................................163
NadOutputCompStatusEnum.......................................................................163
NadOutputCompTypeEnum.........................................................................164
NadStatusEnum............................................................................................165
NadToStringEnum .......................................................................................167
QryEngOptionEnum and QryEngOptionValueEnum..................................168
QueryElementEnum.....................................................................................169
QueryThresholdEnum ..................................................................................174
ReportItemEnum ..........................................................................................175
ReportLotCertEnum.....................................................................................176
ReportTypeEnum .........................................................................................176
Contents
7
SuggTypeEnum ...........................................................................................176
SuggStatusEnum.......................................................................................... 177
SupportedCountriesEnum............................................................................178
VersionDepthEnum .....................................................................................179
Chapter 8:
Suggestion Lists......................................................................................... 181
How to handle suggestion lists ....................................................................182
getOption()...................................................................................................184
setOption() ................................................................................................... 185
suggestionsAvailable().................................................................................186
getSuggListCount()...................................................................................... 187
getSuggEntry()............................................................................................. 188
getSuggComponent()...................................................................................191
setSuggestion().............................................................................................192
setSuggRange()............................................................................................ 193
ignoreSuggestion().......................................................................................194
How to customize suggestion lists...............................................................195
Appendix A:
Countries supported .................................................................................. 197
Appendix B:
EasyIQ Library ..........................................................................................207
Supported countries ..................................................................................... 208
EasyIQ Global Functions............................................................................. 209
getIEQ() ....................................................................................................... 210
getIEQ_u() ................................................................................................... 211
FlRKSMessageEnumToString() .................................................................. 212
FlCountryIdEnumToString()........................................................................ 213
FlStringToCountryIdEnum()........................................................................ 214
releaseIEQ().................................................................................................215
PubIEQClass................................................................................................ 216
addEngine().................................................................................................. 217
backup() ....................................................................................................... 218
getComponent() ........................................................................................... 219
IeqComponentEnum .................................................................................... 220
getComponent_u() ....................................................................................... 222
setComponent()............................................................................................ 223
setComponent_u()........................................................................................ 224
getMessage()................................................................................................ 225
process().......................................................................................................226
IeqStatusEnum............................................................................................. 227
clear()........................................................................................................... 228
postResults() ................................................................................................ 229
pick()............................................................................................................230
pickList()...................................................................................................... 231
PubPickListClass ......................................................................................... 232
atEnd() ......................................................................................................... 233
atStart() ........................................................................................................234
type()............................................................................................................235
forth()........................................................................................................... 236
getComponent() ........................................................................................... 237
8
getComponent_u()........................................................................................238
reset()............................................................................................................239
size().............................................................................................................240
Typical sequence of function calls for address processing through EasyIQ 241
EasyIQ sample programs .............................................................................243
Wildcard usage.............................................................................................244
Appendix C:
Processing Japanese Addresses.................................................................245
Standard Japanese address format................................................................246
Special address formats................................................................................252
Accepted formats..........................................................................................255
Input components .........................................................................................256
Output components ......................................................................................258
Fault and status codes...................................................................................261
Sample address.............................................................................................262
Setting up processing ...................................................................................263
Appendix D:
U.S. Engine: Residential Delivery Indicator (RDI).................................265
What is RDI?................................................................................................266
RDI directories .............................................................................................267
Enable RDI processing.................................................................................268
Appendix E:
U.S. Engine: Delivery Point Validation (DPV)........................................269
What is Delivery Point Validation (DPV)?..................................................270
USPS requirements ......................................................................................271
Installing DPV and its directories ................................................................272
DPV processing modes ................................................................................273
Set up DPV processing.................................................................................276
DPV output components ..............................................................................277
DPV locking.................................................................................................278
DPV performance.........................................................................................280
Appendix F:
Canada Engine: GeoCoding......................................................................283
Set up GeoCoding ........................................................................................285
Glossary.......................................................................................................287
Index ............................................................................................................289
Contents
9
10
Chapter 1: Working with International ACE
This chapter discusses how to compile and run the International engine, as well as how to work with header files, sample programs, the engines.
11

Introducing International ACE

International ACE parses address components from input records containing international name and address data.
For some countries, International ACE may also correct address data or add postal codes. For a list of the countries covered, see “Countries supported” on page 197.

Discrete, multiline, or hybrid input data

Data you can retrieve from International ACE

Auxiliary data files

International ACE accepts discrete, multiline and hybrid address line formats. For details on supported formats, see “Accepted address line formats” on page 25
For a complete list of input fields, see the Quick Reference for Libraries.
After you process an address, you can retrieve:
Parsed address components, such as locality, region, and postal code.
Corrected address components.
Standardized address lines that correspond to the input lines.
Information about whether any data was changed, added, or deleted in a
corrected component.
For the U.S., Canadian, and Australian processing engines, information about
the level of “agreement” within a corrected address—for example, whether the region and postal code agree. You may use this information to measure address quality.
The level of parsing and correction varies by country. The level of correction also depends upon the amount of address data present in the input record.
International ACE includes a set of data files that contain address and postal code data. International ACE uses these files to guide parsing and address correction. See “EngineFileEnum” on page 153 for details.
12

Compiling and running the International engine

If you install and run the International engine on UNIX, you must manually set up the COBOL runtime environment. Refer to the International Address Processing COBOL Installation Guide for UNIX Platforms. If you install and run the International engine on Windows, you do not need to set up a runtime environment because the runtime environment is already installed on the Windows platform. However, you do need to set environment variables. See “Windows users: configure your system” on page 14 for details.
Note: You no longer need to set the COBPATH and TCGMAPPER environment variables or edit the allmapper.txt file.

UNIX users: Configure your system

The International engine relies on specific environment variables being set in order to run successfully. All examples are shown using the bash shell. Make adjustments for the shell that you are using.
1. To set the COBDIR variable to the location where the system administrator
has installed the MicroFocus COBOL environment, type COBDIR=/opt/lib/ cobol and press Enter. Then type export COBDIR and press Enter.
2. To set the TCGLOG variable, type TCGLOG=/<path>/postware/iacelib/
work/tcglog.txt and press Enter. Then type export TCGLOG and press Enter. If you do not name the file, it defaults to tcglog.txt and places it in the location in which you are running.
3. Set the Shared Library Path environment variable. This command varies
according to your operating system.
HP
AIX
Solaris
Linux
Type
SHLIB_PATH=$COBDIR/lib:
ware/adm
Enter.
Type
adm
Type
postware/adm and press Enter. Then type export LD_LIBRARY_PATH
Type
postware/adm:/usr/local/gcc.3.2.3/lib export LD_LIBRARY_PATH
and press Enter. Then type export SHLIB_PATH
LIBPATH=$COBDIR/lib:
and press Enter. Then type
LD_LIBRARY_PATH=$COBDIR/lib:
and press Enter.
LD_LIBRARY_PATH=$COBDIR/lib:
installation path
installation path
export LIBPATH
installation path
installation path
and press Enter. Then type
and press Enter.
:/disk_n/post-
and press
:/disk_n
/postware/
and press Enter.
:/disk_n
:/disk_n
/
/
4. To increase the number of file handles available, type ulimit –Sn 1024.
5. Library users: Adjust your path variable to include the $COBDIR/bin
directory. Type PATH=$COBDIR/bin:$PATH and press Enter. Then type export PATH and press Enter.
Compiling and running the International engine
13

Adjust your path

Be sure to adjust your path to include the location of the linker (ld) command and the assembler (as) command. For example:
To adjust your path variable to include the location of the linker (ld)
command, type PATH=/usr/ucb/bin:$PATH and press Enter.
To adjust your path variable to include the location of assembler (as)
command, type PATH=/usr/ccs/bin:$PATH and press Enter.

Windows users: configure your system

Set file location

If you install and run the International engine on Windows, you do not need to set up a runtime environment because the runtime environment is automatically installed on the Windows platform. However, you do need to set environment variables.
You must set the TCGLOG to a valid path and file name. You may give this file any name. If you do not name the file, it will default to tcglog.txt. Do one of the following:
At the DOS prompt, type set TCGLOG=\<path>\pw\iacelib\work\
tcglog.txt
In your operating system startup file, add the TCGLOG variable to include a
path of \<path>\pw\iacelib\work\tcglog.txt
If the environment variable for TCGLOG is not valid, International ACE will stop running and bring you back to the prompt soon after processing begins. To correct this, set the TCGLOG to reflect a valid path.
When you are running your compiled application, the keyfile flprods.key must be in the current directory. The files iiemsg.dbf and cppgmsg.dbf must be in your PATH.
14

Header files

International ACE comes with six header files. Include the four appropriate files.
File Description Include
C++
cflsys.h
ciie.h
iiepub.h
cppgpub.h
ciiepub.h
ccppgpub.h
Generic parameter type declarations.
Parameter declarations (enumerations).
Global functions and abstract class declarations for PubEngineClass, PubNaddressClass, and PubQuery­Class.
Abstract class declarations for PubErrorClass.
Function declarations for the C interface.
Declarations for error-handling functions in the C interface.
C
Header files
15

Sample programs

If you would like to see an example of application code calling the C++ interface, refer to our sample source-code files:
C++ C Description
testiace.cpp ctstiace.cpp
testqry.cpp ctstqry.cpp
International ACE does not support dlopen for C++.
testieq.cpp ctestieq.cpp
cstiace_shared.cpp
Demonstrates how to process addresses.
Demonstrates how to query the postal directories.
Demonstrates how to process addresses. This example is written using dlopen and shared libraries on UNIX.
Demonstrates how to process addresses in Easyiq.
We provide make files (.mak) for Windows, and build scripts (_mk) for UNIX. To build one of the sample programs, use the corresponding make file or build script.
When running a sample program, make sure that the file flprods.key is in the current directory, and that iiemsg.dbf, and cppgmsg.dbf, are in the user’s path.
Note: Our C source-code files have .cpp file extensions because you must use a C++ linker. By using the .cpp file extension, you can compile and link in one step rather than in two steps.
The sample programs are for use only as a learning tool. They are not prototypes or products per se. We do not support or authorize any use for commercial purposes, and we disclaim any warranty regarding such use.
16

Overview of the object-oriented interface

The International ACE C++ interface uses global functions and four abstract classes.

Global functions

Public name-and­address class

Public engine class

The global functions provide initialization and termination. Global functions also produce name-and-address, engine, and query objects that conform to the PubNaddressClass, PubEngineClass, and PubQueryClass class definitions, respectively.
A name-and-address object does the following:
Accepts input data from your application
Specifies which output components to produce
Accepts output data from the processing engine
You pass input data into a name-and-address object, then use an engine object to process the data. The engine parses and corrects the data, produces the requested output components, and passes the results back to the name-and-address object. You retrieve the output results from the name-and-address object.
You can create multiple name-and-address objects. For example, suppose you get your input records from two databases that have different record layouts. You can set up two name-and-address objects—one to accept input from each database.
An engine object parses and corrects address data.
Engines are specialized. For example, the U.S. engine processes addresses from the United States only, the Australian engine processes addresses from Australia, and so on. The international engine processes addresses from many countries; see “Countries supported” on page 197.

Public query class

Public error class

Working with objects

The engine processes the data stored on a name-and-address object and passes the results back to the name-and-address object.
The public query class is used to directly query the address and postal code files that International ACE uses for lookups. For example, you might do a query to investigate unexpected output results.
The public error class, PubErrorClass, provides information about International ACE errors.
In your application, you will create and work with objects.
For example, for a simple application, you might create one engine object and one name-and-address object. You would use the engine object to process address
Overview of the object-oriented interface
17
data. You would use the name-and-address object to pass input data into the engine, and to retrieve output data from the engine.
Input data
Output data
Name-and­address object
Engine object
In most applications, you will use multiple objects. For example, suppose you are processing a file that contains addresses from Canada and other countries. You might create a country identification engine, a Canadian engine, and an international engine. You would use the country identification engine to first identify the country. Then, you would send each Canadian address to the Canadian engine, and all other addresses to the international engine.
Input data
If the country is Canada, use the Canadian engine object. Else, use the International engine object.
Output data
Name-and­address object
Country ID engine object
Canadian engine object
International engine object
Bear in mind that when you load input data into a name-and-address object, that input data stays in that name-and-address object until you either clear the data or load different input data into the object. In other words, once you load data into a name-and-address object, you can shuttle the name-and-address object from engine to engine without reloading the input data.
18

Working with the C interface

International ACE is an object-oriented C++ library. However, we also provide a C interface as a cover over our C++ interface, so that C programmers can call the library.

Working with objects

For most International ACE functions, you must tell International ACE which object it should use to perform the function. For example, to open a particular engine object using the C interface, you would pass the engine object into the engOpen() function as an input parameter:
engOpen(engPtr, error);
By comparison, a C++ programmer would use the object to call the open() function, like this:
engPtr --> open();
Working with the C interface
19

Looking up functions

The C functions and C++ functions are named differently. In this manual, we organize the functions into chapters by the classes used in C++, and we use the C++ function name as the title for each reference page.
You can find a C function on the reference page for the equivalent C++ function. To look up a particular C function, follow the guidelines below, or look in the index.

Linking and compiling

Don’t mix C and C++

If the C function starts with...
c Global functions, Chapter 2
Look in this chapter Example
C function C++ function
c
IieInit()
c
or
GetErrorInfo()
iieInit() getErrorInfo()
PubErrorClass, Chapter 6
eng
eng PubEngineClass, Chapter 3
nad PubNaddressClass, Chapter
4
qry PubQueryClass, Chapter 5
GetEngineInfo() getEngineInfo()
nad
GetCompo-
getComponent()
nent()
qry
GetElement() getElement()
release Global functions, Chapter 2 releaseEng() n/a
If you use the C interface, you must use a C++ linker. You may use a C compiler.
For each application that you write, use either the C interface or the C++ interface. Do not mix calls to both interfaces.
20

Error and warning handling

C++ interface

The error handling subsystem uses exceptions to throw and catch errors. All International ACE interface functions, including global and class members, have the potential for throwing errors.
Check for warnings after completing an operation that may generate a warning.
Warning messages do not throw an error. It is not sufficient to see if the error object has data. The error object may just contain warning data. You must instead try to catch an error using the catch() function call. Use the public error class, PubErrorClass, to interrogate any error object that you catch. Call getErrorInfo() to retrieve an error title and error message. For example:
try { // Do some stuff. } catch(const PubErrorClass* errorObject) { FlCharType msg[256]; FlCharType title[256];
errorObject->getErrorInfo( sizeof(title), sizeof(msg), msg, FL_USA, FL_ENGLISH);
cerr << "Error Title: " <<(char*) title << endl; cerr << "Error Description: " << (char*)msg << endl; }
The casting of title and msg to char*is dependent upon FlCharType being an 8-bit type.
In addition, you may check for the existence of warnings by using getErrorStatus():
//You can also check for the existence of a warning if(FL_WARNING == getErrorStatus()) { FlCharType title(256); FlCharType msg(256);
getErrorObject()->getErrorInfo(256, title, 256, msg); cerr << "\nERROR: " << (char *)title << endl << (char *)msg << endl << endl; // Note: After getting the warning it should be cleared getErrorObject()->clear(); }
Error and warning handling
21

C interface

Almost every function in the C interface includes an error output parameter. After you call a function, check the value of the error parameter. If the error parameter contains a 1, call your error handler.
Inside your error handler, call cGetErrorInfo() to get an error title and message. For example:
FlCharType title[FL_MAX_ERROR_TITLE_LENGTH]; FlCharType msg[FL_MAX_ERROR_MSG_LENGTH]; cGetErrorInfo(FL_MAX_ERROR_TITLE_LENGTH, title, FL_MAX_ERROR_MSG_LENGTH, msg, FL_USA, FL_ENGLISH); fprintf(stderr, "ERROR: %s\n%s\n", (char*)title, (char*)msg); exit(1);
For an example showing one possible method of error handling, see the error_tran() macro in our sample programs ctstiace.c and ctstqry.c.
22

Thread safety limits for AIX, HP, and Solaris

International ACE is thread safe on AIX, HP, and Solaris platforms. When you are writing a threaded application, the number of threads you can use depends on the number of file handles that are available on your system. To obtain the maximum number of threads, it is recommended that you raise the ulimit on UNIX to 1024.
Set the ulimit to 1024 by typing ulimit -Sn 1024
The table below lists the approximate number of file handles required for each engine in International ACE. To calculate the number of threads your application can use, determine your system’s limitations and the combination of engines you plan to use. Be sure to account for any other file handles your application may use aside from the file handles used by each engine.

Example

Library and RAPID users

You are creating an application that requires the following engines:
• United States (20 file handles)
• Canadian (20 file handles)
• Australian (20 file handles)
Engine File handles
Australian engine 20 Canadian engine 20 US engine 20 International engine 70
• International (70 file handles)
The total number of file handles required is 130. If your system has 1024 file handles available and your application does not use any additional file handles, then you are able to run your application safely using 7 threads. (1024 / 130 = 7)
Library and RAPID users need to include the -t flag when building an executable. For example, type:
cob -t myprog.o myprog
Thread safety limits for AIX, HP, and Solaris
23

Tips for working with the International engines

Results differ by country

The international engine is a general-purpose engine that must process addresses from many different countries. The goal of the international engine is to assign the correct postal code for an address. The engine recognizes only as much information as it needs to assign the postal code. For example, for some countries, the international engine may require only the locality (town) and region to assign a postal code.
The output component fields reflect the amount of information processed. For example, if only the locality and region are used to assign the postal code, then only the locality, region, and postal code output components would be populated—other components will not be populated. If the engine cannot assign a postal code, then all of the output components may be empty. (Exception: Locality and country components may be populated even if a postal code was not assigned.)
Additionally, the level of postal data varies widely from country to country. For some countries, complete address data is available for most or all of the country. In other countries, only locality, region, and postal code data are available. Also in some countries, complete address data is available for large metropolitan areas, while only locality, region, and postal code are available for smaller towns. The amount of data available in the postal databases will affect the data that is available for output.
When using the international engine, check the output for blank fields. You may prefer to retrieve lines rather than retrieving output components. To retrieve lines, call getStandardizeLineData().

Pass in discrete country data

Although the international engine can often recognize country data within a larger line, the country ID engine is specially designed to identify country data and is therefore the most effective engine to use for this purpose.
The international engine provides best results if you pass in discrete country data through the discrete country data, use the country ID engine to identify the country, then pass that country information to the international engine.
1. When you create the name-and-address object, include the discrete country line, discrete country data. You’ll need this line for the country data that you get from the country ID engine.
2. Pass the input address to the country ID engine. Retrieve the country name from the country ID engine and store it in a buffer.
3. Remove the country data from the original input address by calling getComponentLocation(). Do this so that you don’t send duplicate country data to the international engine (the country embedded in the original address and the country retrieved from the country ID engine). Duplicate address data may sometimes affect results.
4. Reload the data onto the name-and-address object. Load the input address from which you removed the country data, along with the discrete country name that you retrieved from the country ID engine.
NAD_LINE_COUNTRY field. If your input records do not contain
NAD_LINE_COUNTRY, even if your input records do not contain
24
5. Process the address as usual.

Accepted address line formats

The following tables list the line formats currently supported by Interational ACE.
Note: For all multi-line and multi-line hybrid formats listed, you are not required to use all lines for a selected format. You must always start with Line1.
Multi-line and Multi-line Hybrid Formats
Line1 Line1 Line1 Line1 Line1
Line2 Line2 Line2 Line2 Line2
Line3 Line3 Line3 Line3 Line3
Line4 Line4 Line4 Line4 Line4
Line5 Line5 Locality3 Line5 Line5
Line6 Line6 Locality2 Locality2 Line6
Line7 Line7 Locality1 Locality1 Locality1
Line8 Lastline Region Region Region
Country
(Optional)
Country Postcode Postcode Postcode
Country Country Country
Note: We recommend using the Country field if the default Country option is set to None for the International engine.
Discrete Line Formats
Address Address Address Address
Lastline Locality3 Locality2 Locality1
Country Locality2 Locality1 Region
Locality1 Region Postcode
Region Postcode Country
Postcode Country
Country
Note: The discrete line formats are not recommended for processing International databases. They are more appropriate for use in U.S., Canadian, and Australian addresses.
Accepted address line formats
25

Sample formats

International ACE accepts addresses in three formats. The following examples give the description of each accepted address format and three sample addresses for each format.

Multiline

The multiline format is a database record format in which address data is not consistently located in the same arrangement in all records. That is, data items "float" among fields.
Address 1 Address 2 Address 3
Line1 = Line2 = Line3 = Line4 = Line5 = Line6 = Line7 = Line8 =
Country =

Discrete

Lawrence Robinson Information Services Plc Cornwall House 56 Henley Road
London NW2Y 5DM
United Kingdom
Line1 = Line2 = Line3 =
Gran Via de Carles S.A
Ibarra Campillo 16-3-A Line4 = Line5 =
48010 Bilbao Line6 = Line7 = Line8 =
Country =
Spain
The discrete format is a database record format in which pieces of data appear in
Line1 = Line2 = Line3 = Line4 = Line5 = Line6 = Line7 = Line8 =
Country =
exactly the same field arrangement in every record.
Address 1 Address 2 Address 3
Firm =
Addr_Line =
Last_Line =
Country =
Micro Elektronic Ges.m.b.H Baumschulengasse 250 1010 Wein Germany
Addr_line =
Locality1 =
Region =
Postcode =
Country =
Nybrovej 120 Lyngby
2800 Denmark
Firm =
Addr_Line =
Locality1 =
Region =
Postcode =
Country =
Peter Grant
United Car Rental, Ltd
3150 S. Larkin Rd., Suite 10 Etiboke ON M9C4T9 Canada
Dupong S.A. 225 rue de Bragance Luxembourg
1449 Luxembourg
26

Hybrid format

The hybrid format is a database record format which contains “floating” address data as in the multi-line format as well as consistent/discrete last line data. Data such as Locality Region and Postcode are located in the same field or line for every record in the database.
Address 1 Address 2 Address 3
Line1 = Line2 = Line3 = Line4 =
Line5 = Locality2 = Locality1 =
Region =
Postcode =
Country =
Jonas Lancaster Woodworks Ltd. Wetherby House 20 Oakley Road
Harlow
Essex CM19 5AE United Kingdom
Line1 = Line2 = Line3 = Line4 = Line5 = Line6 =
Locality1 =
Region =
Postcode =
Country =
Gran Via de Carles S.A.
Ibarra Cambillo 16-3-A
Bilbao
48010 Spain
Line1 = Line2 = Line3 = Line4 = Line5 = Line6 = Line7 =
Last_Line
Country =
Akzo Chemicals
Moreelsepk 24
3511 EP Utrecht Netherlands
=
Note: When using the International engine and defining the hybrid format, be sure that the total number of Localities + Region + Multilines is less than or equal to eight.
Sample formats
27

Certification options

If you are interested in what settings are required for certification, here is a table describing each required option and it’s setting.
Library Option Australia (AMAS) Canada (SERP) US (CASS)
ASSIGN_ENG_STND_LAST_LINE N/A YES YES ASSIGN_ENG_STND_ADDR_LINE N/A YES YES ASSIGN_ENG_SUFFIX_STYLE SHORT SHORT SHORT ASSIGN_ENG_DIRECTIONAL_STYLE SHORT SHORT SHORT ASSIGN_ENG_PRIM_NAME_ALTERNATE N/A PRESERVE PRESERVE ASSIGN_ENG_DUAL_ADDR PREFERRED
(POSTAL) ASSIGN_ENG_LOCALITY1 N/A PREFERRED PREFERRED ASSIGN_ENG_POSTCODE_FORMAT N/A LONG LONG ASSIGN_ENG_CAPITALIZATION UPPERCASE UPPERCASE UPPERCASE ASSIGN_ENG_SECONDARY_RANGE_STYLE N/A PRESERVE N/A ASSIGN_ENG_UNIT_STYLE N/A N/A DIRECTORY ASSIGN_ENG_STND_UNASSIGN_ADDR N/A NO NO ASSIGN_ENG_LANGUAGE_STYLE_ADDRESS N/A PRESERVE N/A ASSIGN_ENG_DIACRITICAL_CHARS N/A NO N/A ASSIGN_ENG_MODE_LVR_RULE N/A YES N/A ASSIGN_ENG_MODE_RURAL_RULE N/A YES N/A ASSIGN_ENG_POSTCODE_ONLY N/A YES N/A ASSIGN_ENG_POSTCODE_NO_MATCH_SEARCH N/A YES N/A ASSIGN_ENG_CHANGE_POSTCODE_MATCH N/A (EQUAL) N/A ASSIGN_ENG_EXTRA_DATA (STRICT) N/A (STRICT) ASSIGN_ENG_APPEND_PMB N/A N/A YES ASSIGN_ENG_RESTRICTED_MATCHING YES N/A N/A
PREFERRED
(POSITION)
PREFERRED
(POSTAL)
28

Typical sequence of function calls for address processing

For all International ACE functions, there is the potential for errors to occur. For information about error handling, see “Error and warning handling” on page 21.
Note: This call sequence shows functions from the C++ interface. If you are using the C interface, call the equivalent C functions in the same sequence.

Initializing

Creating name-and­address object(s)

Create engine object(s)

1. Call iieInit() to initialize the library. See “iieInit()” on page 43.
2. Call getNad() to create a name-and-address object. See “getNad()” on page 40.
3. Optional: Call setStandardizeLineLength() to set the maximum length for an output line. Call this function once for each output line whose length you wish to set. See “setStandardizeLineLength()” on page 102.
4. Optional: Call setOption() to set options for this name-and-address object. See “setOption()” on page 67.
Repeat steps 2 through 4 for each name-and-address object.
5. Call getEng() to create an engine object. When created, the engine will be
in the closed state. See “getEng()” on page 37.
6. While the engine is in the closed state, set file names and paths:
Call setPathName() to set paths for the files used by the engine. See
“setPathName()” on page 69.
Call setFile() to set the locations and file names of files whose locations
were not set using setPathName(). See “setFile()” on page 65.
7. Optional: Call setOption() to set options for this engine. You may only call setOption() when the engine is in the closed state. See “setOption()” on page 67.
8. Call open() to move the engine to the open state. See “open()” on page 64.
Repeat steps 5 through 7 for each engine object you want to create.
Typical sequence of function calls for address processing
29

Pass in data

9. Call insertLineData() to insert input data into the name-and-address object. Call this function once for each input field. See “insertLineData()” on page 88..
10. Call validateLineFormat() to verify that the combination of input fields is valid. See “validateLineFormat()” on page 103.

Process data and retrieve results

11. Call process() to use an engine object to process the data stored on the name­and-address object. See “process()” on page 122.
12. Retrieve the results from the name-and-address object:
To retrieve a line that corresponds to an input line, call
getStandardizeLineData(). See “getStandardizeLineData()” on page 83.
To retrieve a parsed or corrected component, call getComponent(). See
“getComponent()” on page 77.
To get information about the address—for example, to learn which
address data was corrected—call getFaultCode() and getStatus(). See “getFaultCode()” on page 82 and “getStatus()” on page 86.
To process the record with another engine object, repeat steps 11 and 12 (You do not have to reload the input data into the name-and-address object.) For example, you might use the Country ID engine to get the country, then pass the record to the appropriate engine for address processing.
Note: The name-and-address object retains the original data that you passed in until you call insertLineData() and load new data. However, the name-and­address object retains the results of only the engine upon which it was most recently processed. So always, retrieve results before processing the name­and-address data with a different engine.

Termination

13. Use the built-in C++ delete operator to deallocate all name-and-address and engine objects.
Note: If you are using the C interface, call the “release” functions to deallocate objects. See “releaseEng()” on page 45 and “releaseQry()” on page 47.
14. Call iieTerm() to terminate the library. See “iieTerm()” on page 44.
30

Unicode implementation

International ACE Library processes Unicode data much the same way as you’ve processed other data in the past. International ACE handles Unicode data by making use of special Unicode functions and methods. All functions and methods are explained fully in this reference.

Accepted data type

Mixing Unicode and non-Unicode calls?

Do I need to convert my entire API to pass Unicode data?

Unicode functions and methods

International ACE will accept Unicode input only if the data uses the UTF-16 encoding.
You can mix calls to Unicode and non-Unicode functions. For example, if you’re passing UTF-16 fields to International ACE from one source, and you also have address lines in ASCII that need to be passed as input, you can use the non­Unicode “set” functions for that ASCII data.
You do not need to convert functions that output messages or revision information, functions that accept input like path names, and so on.
All you need to do is accept Latin-1 characters that have been stored in a UTF-16 encoding or to output the data as UTF-16. You don’t need to convert output such as error messages to Unicode. These messages will always be Latin-1 characters. Besides, they’re only for display or logging purposes.
The following functions are available for processing Unicode data in International ACE Library.
PubEngineClass functions
setFile_u() setPathName_u() getFile_u() getPathName_u() getEngineInfo_u() usGetDpvMessage_u()
PubNaddressClass functions
insertLineData_u() getStandardizeLineData_u() getComponent_u() openTuner_u() setReportInfo_u() produceReport_u()
PubQueryClass functions
getElement_u() setElement_u() getPathName_u() getFile_u() setFile_u() setPathName_u()
PubPickListClass functions
current_u()
Global functions
usZ4Zip4Changed_u() iaceGetRevision_u()
These Unicode functions correlate to previously existing functions. You can tell International ACE’s Unicode functions from their non-Unicode counterparts by the “_u” appended to the name.
Unicode implementation
31
32
Chapter 2: Global functions
The International ACE C++ library uses seven global functions. Two of these functions are used to initialize and terminate the error-management and memory­management subsystems. Two can be used to retrieve user-friendly names for components and lines. The others are object factories that produce objects that conform to the PubEngineClass, PubNaddressClass, and PubQueryClass classes.
The global functions are listed in alphabetical order in this chapter.
33
FlNadFaultCodeEnumToString
()

Synopsis

Arguments

Returns

Description

C function

const FlCharType* (
NadFaultCodeEnum inId, NadToStringEnum outId =
inId Input: The fault code for which to retrieve a printable string.
outId Input: The type of string to retrieve. For this function, the only
valid values are
Returns the requested string.
For a particular fault code, call this function to retrieve a printable fault-code string such as “F101,” or a description string such as “Last line is bad or missing.” You might print this information on a report.
To get the fault code inId that you must pass in, call the PubNaddressClass function getFaultCode().
NAD_VALUE_AS_STRING and NAD_DESCRIPTION.
NAD_VALUE_AS_STRING);
const FlCharType* cFlNadFaultCodeEnumToString(
NadFaultCodeEnum inId, NadToStringEnum outId);
inId See description above. outId See description above. Not optional for C.
34
FlNadLineEnumToString
()

Synopsis

Arguments

Returns

Description

C function

const FlCharType* FlNadLineEnumToString(
NadLineEnum inId, NadToStringEnum outId =
inId Input: Type of line. For a list of values, see NadLineEnum on
page 161.
outId Optional input: Type of string to return. For a list of values, see
NadToStringEnum on page 167.
If successful, returns the string.
Call this function to retrieve a NadLineEnum enumeration as a printable string, such as “ spelling in the header file ciie.h.
NAD_LINE_MULTILINE1.” The spelling will be the same as the
NAD_VALUE_AS_STRING);
const FlCharType* cFlNadLineEnumToString(
NadLineEnum inId, NadToStringEnum outId);
inId See description above. outId See description above. Not optional for C.

FlNadLineEnumToString()

35
FlNadOutputCompEnumToString
()

Synopsis

Arguments

Returns

Description

C function

const FlCharType* FlNadOutputCompEnumToString(
NadOutputCompEnum inId, NadToStringEnum outId =
inId Input: Type of output component. For a list of values, see
NadOutputCompEnum on page 163.
outId Optional input: Type of string to return. For a list of values, see
NadToStringEnum on page 167.
If successful, returns the string.
Call this function to retrieve a NadOutputCompEnum enumeration as a printable string such as “ spelling in the header file ciie.h.
NAD_PRIM_NAME.” The spelling will be the same as the
NAD_VALUE_AS_STRING);
const FlCharType* cFlNadOutputCompEnumToString(
NadOutputCompEnum inId, NadToStringEnum outId);
inId See description above. outId See description above. Not optional for C.
36
getEng
()

Synopsis

Arguments

Returns

Description

C function

PubEngineClass * getEng(EngineTypeEnum engType);
engType Input: The type of engine object to create. For values, see
EngineTypeEnum on page 156.
If successful, returns a pointer to an engine object.
Call this function to create an engine object that conforms to the PubEngineClass class. The function creates the type of engine object specified by the engType parameter. You will use this engine object to parse and correct address data.
When you are done with an engine object, you are responsible for deallocating it. C++ programmers should use the built-in C++ delete operator, and C programmers should call releaseEng().
void* cGetEng(
EngineTypeEnum engType, int* error);
engType See description above. error Output: Contains a 1 if an error occurred.

getEng()

37
getErrorObject
()

Synopsis

Arguments

Returns

Description

PubErrorClass* getErrorObject();
None.
PubErrorClass* If an error occurred, this returns a pointer to an error class object, otherwise it returns FL_NULL.
Call this function to obtain an error object pointer to retrieve information.
Usage example:
if (FL_ {
FlCharType title(256); FlCharType msg(256);
getErrorObject()->getErrorInfo(256, title, 256, msg); cerr << "\nERROR: " << (char *)title << endl << (char *)msg << endl << endl; // Note: After getting the warning it should be cleared getErrorObject()->clear();
WARNING == getErrorStatus())
}
38
getErrorStatus
()

Synopsis

Arguments

Returns

Description

FlErrorWarningMsgEnum getErrorStatus();
None.
FL_STATUS_OK No generated warning or error. FL_WARNING A warning occurred. FL_ERROR An error occurred.
Call this function to see if a warning is generated.

getErrorStatus()

39

getNad()

Synopsis

Returns

Description

C function

PubNaddressClass * getNad( );
If successful, returns a pointer to a name-and-address object.
Call this function to create a name and address object that conforms to the PubNaddressClass class. You will use this name-and-address object to store input data and retrieve output components.
When you are done with a name-and-address object, you are responsible for deallocating it. C++ programmers should use the built-in C++ delete operator, and C programmers should call releaseNad().
void* cGetNad(int* error);
error Output: Contains a 1 if an error occurred.
40
getQuery
()

Synopsis

Arguments

Returns

Description

C function

PubQueryClass * getQuery(EngineTypeEnum engType);
engType Input: The type of query engine. For values, see
EngineTypeEnum on page 156.
If successful, returns a pointer to a query class object.
Call getQuery() to create a query class object that conforms to the PubQueryClass class. To perform simultaneous queries, you must have multiple instances of the PubQueryClass.
When you are done using a query engine object, you are responsible for deallocating it. C++ programmers should use the built-in C++ delete operator, and C programmers should call releaseQry().
void* cGetQuery(
EngineTypeEnum engType, int* error);
engType See description above. error Output: Contains a 1 if an error occurred.

getQuery()

41
iaceGetRevision
()

Synopsis

Arguments

Returns

Description

C function

bool iaceGetRevision(
FlCharType* buffer, int bufferLen, VersionDepthEnum versionDepth =
buffer Output: Version string. bufferLen Input: Length of the buffer allocated to hold the
output string.
versionDepth Optional input: Depth of version information to get.
For values, see VersionDepthEnum on page 179.
If the buffer is long enough to hold the output string, the function returns true. If the buffer is not long enough, the function returns truncated.
Call this function to get a version string for International ACE. You must provide a buffer to store the output string (which includes a
LONG_VERSION_STRING);
false and the version string is
NULL terminator).
int cIaceGetRevision(
FlCharType* buffer, int bufferLen, VersionDepthEnum versionDepth, int* error);
buffer See description above. bufferLen See description above. versionDepth See description above. Not optional for C. error Output: Contains a 1 if an error occurred.
42
iieInit
()

Synopsis

Description

C function

void iieInit( );
Call this function to initialize the library. This function initializes the memory management system and error handling system. You must call iieInit() before calling any other International ACE functions.
To initialize the library, the key file iacelib.key must be in current directory. If
!
this file is not found, the library will not initialize.
void cIieInit(int* error);
error Output: Contains a 1 if an error occurred.

iieInit()

43
iieTerm
()

Synopsis

Description

C function

void iieTerm( );
Call iieTerm() to terminate the library. This function terminates the memory
!
management system and error handling system.
Before calling iieTerm(), you must deallocate all name-and-address, engine, and query engine objects.
Do not call any other International ACE functions after calling iieTerm().
void cIieTerm(int* error);
error Output: Contains a 1 if an error occurred.
44
releaseEng
()
Note: This is a C function. If you are using the C++ interface, do not call this function—instead, use the built-in C++ delete operator to deallocate an object.

Synopsis

Arguments

Description

void releaseEng(
void* engPtr, int* error);
engPtr Input: Pointer to an engine object.. error Output: Contains a 1 if an error occurred.
If you are using the C interface, call releaseEng() to deallocate an engine object.

releaseEng()

45
releaseNad
()
Note: This is a C function. If you are using the C++ interface, do not call this function—instead, use the built-in C++ delete operator to deallocate an object.

Synopsis

Arguments

Description

void releaseNad(
void* nadPtr, int* error);
nadPtr Input: Pointer to a name-and-address object. error Output: Contains a 1 if an error occurred.
If you are using the C interface, call releaseNad() to deallocate a name-and­address object.
46
releaseQry
()
Note: This is a C function. If you are using the C++ interface, do not call this function—instead, use the built-in C++ delete operator to deallocate an object.

Synopsis

Arguments

Description

void releaseQry(
void* qryPtr, int* error);
qryPtr Input: Pointer to a query engine object. error Output: Contains a 1 if an error occurred.
If you are using the C interface, call releaseQry() to deallocate a query engine object.

releaseQry()

47
usSetZ4cCheckDate
()

Synopsis

Arguments

Returns

Description

C function

EngineDateEnum usSetZ4cCheckDate(
PubEngineClass* usEngPtr, int month, int year);
usEngPtr Input: Pointer to a U.S. engine. month Input: Month of last ZIP+4 coding. year Input: Four-digit year of last ZIP+4 coding.
Returns EngineDateEnum. For a list of possible values for EngineDateEnum, see page 152.
Call this function with the month and year that the input records were most recently ZIP+4 coded. This function will verify that your date is within the 12­month period covered by the current Z4Change file.
Before calling this function, make sure the ASSIGN_ENG_PROC_MODE_
DELPT_CHANGE
are using.
processing option is set to YES for the engine object that you
EngineDateEnum cUsSetZ4cCheckDate(
void* engPtr, int month, int year, int* error);
engPtr Input: U.S. engine object month See description above. year See description above. error Output: Contains a 1 if an error occurred.
48
usZ4Zip4Changed
()

Synopsis

Arguments

Returns

Description

EngineZ4CEnum usZ4Zip4Changed(
PubEngineClass* usEngPtr, const FlCharType* zip9);
usEngPtr Input: Pointer to a U.S. engine. zip9 Input: Nine-digit ZIP+4 code (no hyphen).
Returns a value indicating whether this ZIP+4 code is affected by a change, or a value indicating that the input ZIP+4 code was not valid. For a list of values, see EngineZ4CEnum on page 156.
Call this function to see whether a particular ZIP+4 code has changed within the past twelve months. The change may be to a postal code (ZIP Code, ZIP4 code, or carrier route) or a change in the standardized form of the address line or city name.
Before calling this function:
Call usSetZ4cCheckDate().
Make sure the ASSIGN_ENG_PROC_MODE_DELPT_CHANGE processing
option is set to
YES for the engine object that you are using.

C function

Note: The Z4Change process does not assign new postal codes.
EngineZ4CEnum cUsZ4Zip4Changed(
void* engPtr, const FlCharType* zip9, int* error);
engPtr Input: U.S. engine object zip9 See description above. error Output: Contains a 1 if an error occurred.

usZ4Zip4Changed()

49

usZ4Zip4Changed_u()

Synopsis EngineZ4CEnum usZ4Zip4Changed_u(

PubEngineClass* usEngPtr, const FlUChar* zip9);

Arguments usEngPtr Input: Pointer to a U.S. engine.

zip9 Input: Nine-digit ZIP+4 code (no hyphen).

Returns Returns a value indicating whether this ZIP+4 code is affected by a change, or

a value indicating that the input ZIP+4 code was not valid. For a list of values, see EngineZ4CEnum on page 156.

Description Call this function to see whether a particular ZIP+4 code has changed within the

past twelve months. The change may be to a postal code (ZIP Code, ZIP4 code, or carrier route) or a change in the standardized form of the address line or city name.
Before calling this function:
Call usSetZ4cCheckDate().
Make sure the ASSIGN_ENG_MODE_DELPT_CHANGE processing option
is set to
YES for the engine object that you are using.
Note: The Z4Change process does not assign new postal codes.

C function EngineZ4CEnum FL_API cUsZ4Zip4Changed_u(

void* engPtr, const FlUChar * zip9, int* error);
engPtr Input: U.S. engine object zip9 See description above. error Output: Contains a 1 if an error occurred.
50
Chapter 3: PubEngineClass
The PubEngineClass is an abstract class that defines the engine interface.
An engine object parses and corrects address data stored on a name-and-address object. The output results are stored on the name-and-address object and retrieved through the PubNaddressClass interface.
An engine object is always in one of two states: open or closed.
In the closed state, you can set file paths and processing options.
In the open state, the engine object can process data. File paths and
processing options cannot be changed in the open state.
In either state (open or closed), you can query the engine type, the current set
of files, and current directory path. You can also change options.
51
close
()

Synopsis

Description

C function

void close( );
Call this function to close files, deallocate internal structures, and move the engine object to the closed state.
void engClose(
void* engPtr, int* error);
engPtr Input: Pointer to an engine object. error Output: Contains a 1 if an error occurred.
52
getEngineInfo
()

Synopsis

Arguments

Returns

Description

C function

bool getEngineInfo(
EngineInfoEnum selection, FlCharType* buffer, int bufferLen)const;
selection Input: The engine information to retrieve. For a list of possible
values, see “EngineInfoEnum” on page 155.
buffer Output: The requested information.
bufferLen Input: Length of the buffer allocated to hold the output string.
The output string will be no longer than
NAD_MAX_STD_LINE_LENGTH (plus a NULL terminator).
If the buffer is long enough to hold the output string, the function returns true. If the buffer is not long enough, the function returns false and the output string is truncated.
Call this function to retrieve information about the engine.
int engGetEngineInfo(
void* engPtr, EngineInfoEnum selection, FlCharType* buffer, int bufferLen, int* error);
engPtr Input: Pointer to an engine object. selection See description above. buffer See description above. bufferLen See description above. error Output: Contains a 1 if an error occurred.

getEngineInfo()

53

getEngineInfo_u()

Synopsis bool getEngineInfo_u(

EngineInfoEnum selection, FlUChar* buffer, int bufferLen) const;

Arguments selection Input: The engine information to retrieve. For a list of possible

values, see “EngineInfoEnum” on page 155.
buffer Output: The requested information.
bufferLen Input: Length of the buffer allocated to hold the output string in
Unicode code-units. The output string will be no longer than
NAD_MAX_STD_LINE_LENGTH (plus a NULL terminator).

Returns If the buffer is long enough to hold the output string, the function returns true. If

the buffer is not long enough, the function returns false and the output string is truncated.

Description Call this function to retrieve information about the engine.

C function int FL_API engGetEngineInfo_u(

void* engPtr, EngineInfoEnum selection, FlUChar* buffer, int bufferLen, int* error);
engPtr Input: Pointer to an engine object. selection See description above. buffer See description above. bufferLen See description above. error Output: Contains a 1 if an error occurred.
54
getFile
()

Synopsis

Arguments

Returns

Description

C function

const FlCharType* getFile(EngineFileEnum fileId)const;
fileId Input: The type of file whose path and file name to retrieve. For
a list of file types, see “EngineFileEnum” on page 153.
If successful, returns the path and file name of the file. Returns an empty string if the file has not been set.
Call this function to retrieve the path and file name of a specific type of file stored on the engine object. You may call this function when the engine is in either state (open or closed).
const FlCharType* engGetFile(
void* engPtr, EngineFileEnum fileId, int* error);
engPtr Input: Pointer to an engine object. fileId See description above. error Output: Contains a 1 if an error occurred.

getFile()

55

getFile_u()

Synopsis const FlUChar* getFile_u(

EngineFileEnum fileId ) const;

Arguments fileId Input: The type of file whose path and file name to retrieve. For

a list of file types, see “EngineFileEnum” on page 153.

Returns If successful, returns the path and file name of the file. Returns an empty

string if the file has not been set

Description Call this function to retrieve the path and file name of a specific type of file

stored on the engine object. You may call this function when the engine is in either state (open or closed).
Make sure the input file and path name is in Unicode encoded ASCII data. International ACE can not process non-ASCII file or path names.

C function const FlUChar* FL_API engGetFile_u (

void* engPtr, EngineFileEnum fileId, int* error);
engPtr Input: Pointer to an engine object. fileId See description above. error Output: Contains a 1 if an error occurred.
56
getOption
()

Synopsis

Arguments

Returns

Description

AssignEngOptionValueEnum getOption(
AssignEngOptionEnum selection FlCountryIdEnum country) const;
selection Input: The type of option whose value to retrieve. For a list of
options, see “AssignEngOptionEnum and AssignEngOptionValueEnum” on page 136.
Country The country identifier for International engine countries only.
This is an optional parameter that is defaulted to FL_COUNTRY_UNDEFINED. The countries that support each option are listed with the values in “AssignEngOptionEnum and AssignEngOptionValueEnum” on page 136.
Returns the current value of the option. For a list of possible values, see “AssignEngOptionEnum and AssignEngOptionValueEnum” on page 136.
Returns which case the setting from the name-and-address object is used.
Call this function to retrieve the current setting of a particular option on this engine.
OPTION_NOT_SET if the option has not been set on this engine, in

C functions

AssignEngOptionValueEnum engGetOption(
void* engPtr, AssignEngOptionEnum selection, int* error);
engPtr Input: Pointer to an engine object. selection See description above. error Output: Contains a 1 if an error occurred.
AssignEngOptionValueEnum engGetCountryOption(
void* engPtr, AssignEngOptionEnum optionID, FlCountryIdEnum country, int* error);
engPtr Input: Pointer to an engine object.
optionID Input: The type of option whose value to retrieve. For a list of
options, “AssignEngOptionEnum and AssignEngOptionValueEnum” on page 136.
Country Input: The country identifier for International engine countries
only. The countries that support each option are listed with the values in “AssignEngOptionEnum and AssignEngOptionValueEnum” on page 136.
error Output: Contains a 1 if an error occurred.

getOption()

57
getPathName
()

Synopsis

Arguments

Returns

Description

C function

const FlCharType* getPathName(
EnginePathNameTypeEnum pathType)const;
pathType Input: The type of path to retrieve. For a list of values, see
“EnginePathNameTypeEnum” on page 155.
Returns the current path. If no path has been set, the function returns an empty string.
Call this function to get the path that was set using setPathName().
const FlCharType* engGetPathName(
void* engPtr, EnginePathNameTypeEnum pathType, int* error);
engPtr Input: Pointer to an engine object. pathType See description above. error Output: Contains a 1 if an error occurred.
58

getPathName_u()

Synopsis const FlUChar* getPathName_u(

EnginePathNameTypeEnum pathType) const;

Arguments pathType Input: The type of path to retrieve. For a list of values, see

“EnginePathNameTypeEnum” on page 155.

Returns Returns the current path name. An empty string is returned if no path name

has been set.

Description Call this function to get the path that was set using setPathName_u().

Make sure the input file and path name is in Unicode encoded ASCII data. International ACE can not process non-ASCII file or path names.

C function const FlUChar* FL_API engGetPathName_u(

void* engPtr, EnginePathNameTypeEnum pathType, int* error);
engPtr Input: Pointer to an engine object. pathType See description above. error Output: Contains a 1 if an error occurred.
getPathName_u()
59

getStatistic()

Synopsis

long getStatistic(
EngineStatisticEnum statId, SupportedCountriesEnum country) const;
long getStatistic(
NadFaultCodeEnum statEngineError, SupportedCountriesEnum country) const;
long getStatistic(
NadAddrTypeEnum statEngineAddrType, SupportedCountriesEnum country) const;
long getStatistic(
NadAssignTypeEnum statAssignTypeId, SupportedCountriesEnum country) const;
Arguments
statID Input: Statistic wanted. StatEngineError Input: Statistic wanted. StatEngineAddrType Input: Statistic wanted. country Input: Country statistic wanted.

Description

Returns

Call this function to retrieve the value of the given statistic. The second parameter is an optional parameter. It is defaulted to COUNTRY_SUPPORTED_MAX, which will give you a total of all the statistics kept for all the international countries. If an individual country enumeration is passed in, it gives the total for that country only. You may call this function when the engine is in the open state.
Returns the value associated with the passed in parameter. Either EngineStatisticEnum, NadFaultCodeEnum, NadAddrTypeEnum, or NadAssignTypeEnum.
60

C functions

long engGetEngineStatistic(
void* engPtr, EngineStatisticEnum statId, SupportedCountriesEnum country, int* error);
engPtr Input: Pointer to an engine object. statId See description above. country See description above. error Output: Contains a 1 if an error occurred.
long engGetFaultStatistic (
void* engPtr, NadFaultCodeEnum statId, SupportedCountriesEnum country, int* error);
engPtr Input: Pointer to an engine object. statId See description above. country See description above. error Output: Contains a 1 if an error occurred.
long engGetAddressStatistic (
void* engPtr, NadAddrTypeEnum statId, SupportedCountriesEnum country, int* error);
engPtr Input: Pointer to an engine object. statId See description above. country See description above. error Output: Contains a 1 if an error occurred.
long engGetAssignmentType (
void* engPtr, NadAssignTypeEnum statId, SupportedCountriesEnum country, int* error);
engPtr Input: Pointer to an engine object. statId See description above. country See description above. error Output: Contains a 1 if an error occurred.
getStatistic()
61
getType
()

Synopsis

Description

Returns

C function

EngineTypeEnum getType( ) const;
Call this function to retrieve the engine type. You may call this function when the engine either is in the open state or closed state.
Returns the engine type. For a list of possible values, see “EngineTypeEnum” on page 156.
EngineTypeEnum engGetType(
void* engPtr, int* error);
engPtr Input: Pointer to an engine object. error Output: Contains a 1 if an error occurred.
62
isLineUsed
()

Synopsis

Arguments

Returns

Description

C function

bool isLineUsed(NadLineEnum line)const;
line Input line. For a list of values, see NadLineEnum on
“NadLineEnum” on page 161.
Returns true if the input line is processed by this engine; otherwise, returns false.
Call this function to query whether a particular input line is processed by this engine.
If the input line is not processed by this engine, any data passed in on that line
!
will not be available as an output component (NadOutputCompEnum). For the U.S. and Canadian engines, you can retrieve such lines by calling getStandardizeLineData(). For other engines, if you want to carry such lines to the output, you are responsible for retrieving the data from the input record and copying it to the output record.
int engIsLineUsed(
void* engPtr, NadLineEnum line, int* error);
engPtr Input: Pointer to an engine object. line See description above. error Output: Contains a 1 if an error occurred.

isLineUsed()

63
open
()

Synopsis

Description

C function

void open( );
Call this function to move an engine object to the open state. This function opens all files associated with the engine and allocates internal data structures.
void engOpen(
void* engPtr, int* error);
engPtr Input: Pointer to an engine object. error Output: Contains a 1 if an error occurred.
64
setFile
()

Synopsis

Arguments

Description

C function

void setFile(
EngineFileEnum fileId, const FlCharType* fileName);
fileId Input: Type of file. For a list of possible values, see
“EngineFileEnum” on page 153.
fileName Input: Path and file name.
Call this function to set the path and file name of one of the files that International ACE uses for lookups. Call this function only when the engine object is in the closed state.
Tip: You can make just a few calls to setPathName() rather than calling setFile() for each file. See “setPathName()” on page 69.
void engSetFile(
void* engPtr, EngineFileEnum fileId, const FlCharType* fileName, int* error);
engPtr Input: Pointer to an engine object. fileId See description above. fileName See description above. error Output: Contains a 1 if an error occurred.

setFile()

65

setFile_u()

Synopsis void setFile_u(

EngineFileEnum fileId, const FlUChar* fileName);

Arguments fileId Input: Type of file. For a list of possible values, see

“EngineFileEnum” on page 153.
fileName Input: Path and file name.

Returns None

Description Call this function to set the path and file name of one of the files that International

ACE uses for lookups. Call this function only when the engine object is in the closed state.
Make sure the input file and path name is in Unicode encoded ASCII data. International ACE can not process non-ASCII file or path names.
Tip: You can make just a few calls to setPathName_u() rather than calling setFile_u() for each file.

C function void FL_API engSetFile_u(

void* engPtr, EngineFileEnum fileId, const FlUChar* fileName, int* error);
engPtr Input: Pointer to an engine object. fileId See description above. fileName See description above. error Output: Contains a 1 if an error occurred.
66
setOption
()

Synopsis

Arguments

Description

bool setOption(
AssignEngOptionEnum selection, AssignEngOptionValueEnum newValue FlCountryIdEnum country);
selection The option to set. For a list of options, see
“AssignEngOptionEnum and AssignEngOptionValueEnum” on page 136.
newValue Value to set for the option. For a list of valid settings for each
option, see “AssignEngOptionEnum and AssignEngOptionValueEnum” on page 136.
country The country identifier for International engine countries only.
This is an optional parameter that is defaulted to FL_COUNTRY_UNDEFINED. The countries that support each option are listed with the values in “AssignEngOptionEnum and AssignEngOptionValueEnum” on page 136.
Call this function to set options for an engine object.
Note: If you set the same option on the engine object and the name-and­address object, the engine setting overrides the setting on the name-and­address object.

Returns

C functions

Returns true if the option is valid for this engine; otherwise, returns false.
int engSetOption(
void* engPtr, AssignEngOptionEnum selection, AssignEngOptionValueEnum newValue, int* error);
engPtr Input: Pointer to an engine object. selection Input: See description above. newValue Input: See description above. error Output: Contains a 1 if an error occurred.
int engSetCountryOption(
void* engPtr, AssignEngOptionEnum optionID, AssignEngOptionValueEnum optionValue, FlCountryIdEnum country, int* error);
engPtr Input: Pointer to an engine object.
optionID Input: Value to set for the option. For a list of valid settings for
each option, see “AssignEngOptionEnum and AssignEngOptionValueEnum” on page 136.

setOption()

67
optionValue Input: Value to set for the option. For a list of valid settings for
each option, see “AssignEngOptionEnum and AssignEngOptionValueEnum” on page 136.
Country Input: The country identifier for International engine countries
only. The countries that support each option are listed with the values in “AssignEngOptionEnum and AssignEngOptionValueEnum” on page 136.
error Output: Contains a 1 if an error occurred.
68
setPathName
()

Synopsis

Arguments

Description

C function

void setPathName(
EnginePathNameTypeEnum pathType, const FlCharType* pathName);
pathType Input: The type of file(s) for which you want to set the path. For
a list of values, see “EnginePathNameTypeEnum” on page 155.
pathName Input: The path to the directory containing the files of type
pathType. For details, see the description below.
If a required file has not been set using setFile(), the engine searches for the default file in the path that was set by setPathName(). The default file name varies by engine—see “EngineFileEnum” on page 153.
For the international engine, you must call setPathName() to set a directory-type
ENGINE_DIRECTORY_PATH) for the postal-code files, which must all be
path ( stored in the same location.
Call this function only when the engine object is in the closed state.
void engSetPathName(
void* engPtr, EnginePathNameTypeEnum pathType, const FlCharType* pathName, int* error);
engPtr Input: Pointer to an engine object. pathType See description above. pathName See description above. error Output: Contains a 1 if an error occurred.

setPathName()

69

setPathName_u()

Synopsis void setPathName_u(

EnginePathNameTypeEnum pathType, const FlUChar* pathName);

Arguments pathType Input: The type of file(s) for which you want to set the path. For

a list of values, see “EnginePathNameTypeEnum” on page 155.
pathName Input: The path to the directory containing the files of type
pathType. For details, see the description below.

Returns None

Description If a required file has not been set using setFile_u(), the engine searches for the

default file in the path that was set by setPathName_u(). The default file name varies by engine—see “EngineFileEnum” on page 153.
For the international engine, you must call setPathName_u() to set a directory­type path ( all be stored in the same location.
ENGINE_DIRECTORY_PATH) for the postal-code files, which must
Call this function only when the engine object is in the closed state.
Make sure the input file and path name is in Unicode encoded ASCII data. International ACE can not process non-ASCII file or path names.

C function void FL_API engSetPathName_u(

void* engPtr, EnginePathNameTypeEnum pathType, const FlUChar* pathName, int* error);
engPtr Input: Pointer to an engine object. pathType See description above. pathName See description above. error Output: Contains a 1 if an error occurred.
70

usGetDpvMessage()

Synopsis bool usGetDpvMessage(

PubEngineClass*usEngPtr, DpvMessageEnumlineNumber, FlCharType*buffer)

Arguments usEngPtr Input: Pointer to a US Engine object.

lineNumber Input: The line number to retrieve.
buffer Output: The retrieved data. The recommended buffer length
is NAD_MAX_COMPONENT_LENGTH.

Returns This function returns True if the message is retrieved successfully and the output

buffer is populated, otherwise False.

Description Call this function to retrieve the needed information when DPV locks. See “DPV

message functions” on page 278 for details on retrieving the DPV lock message.

C function FL_API_SCM int FL_API cUsGetDpvMessage(

void* eng, DpvMessageEnum lineNumber, FlCharType* buffer, int* error);
eng Input: Pointer to a US Engine object. lineNumber Input: The line number to retrieve. buffer Output: The retrieved data. The recommended buffer length
is NAD_MAX_COMPONENT_LENGTH.
error Output: Contains a 1 if an error occurred.
usGetDpvMessage()
71

usGetDpvMessage_u()

Synopsis bool usGetDpvMessage_u(

PubEngineClass* usEngPtr, DpvMessageEnum lineNumber, FlUChar* buffer);

Arguments usEngPtr Input: Pointer to a US Engine object.

lineNumber Input: The line number to retrieve.
buffer Output: The retrieved data. The recommended buffer length
is NAD_MAX_COMPONENT_LENGTH.

Returns This function returns True if the message is retrieved successfully and the output

buffer is populated, otherwise False.

Description Call this unicode function to retrieve the needed information when DPV locks.

See “DPV message functions” on page 278 for details on retrieving the DPV lock message.

C function FL_API_SCM int FL_API cUsGetDpvMessage_u(

void* eng, DpvMessageEnum lineNumber, FlCharType* buffer, int* error);
eng Input: Pointer to a US Engine object. lineNumber Input: The line number to retrieve. buffer Output: The retrieved data. The recommended buffer length
is NAD_MAX_COMPONENT_LENGTH.
error Output: Contains a 1 if an error occurred.
72
Chapter 4: PubNaddressClass
The PubNaddressClass class is an abstract class that defines the name-and­address interface.
Name-and-address objects are used to store input data, define which output components to produce, and retrieve processing results. A name-and-address object uses one or more engine objects to process its input data.
73

getAddressType()

Synopsis

Arguments

Returns

Description

C function

NadAddrTypeEnum getAddressType() const;
None.
Returns the address-type code for the address that was most recently processed using this name-and-address object. For a list of values see “NadAddrTypeEnum” on page 159.
After processing an address, call this function to get the address type.
NadAddrTypeEnum nadGetAddressType (
void* nadPtr, int* error);
nadPtr Input: Pointer to a name-and-address object. error Output: Contains a 1 if an error occurred.
74

GetAssignType()

Synopsis

Arguments

Returns

Description

C function

NadAssignTypeEnum getAssignType() const;
None.
Returns the assignment-type for the address that was most recently processed using this name-and-address object. For a list of values see “NadAssignTypeEnum” on page 160.
After processing an address, call this function to get the assignment-type.
NadAssignTypeEnum nadGetAssignType(
Vo i d * nadPtr, int* error);
NadPtr Input: Pointer to a name-and-address object. Error Output: Contains a 1 if an error occurred.
GetAssignType()
75

clear()

Synopsis

Description

C function

void clear( );
Call this function to clear the following from the name-and-address object:
Status flags (NadStatusEnum)
Input data inserted by calling insertLineData()
Output component data and status
You might use this function if you pass input data to a name-and-address object and then check it for completeness before processing. If you decide that the address is not complete enough to process, call clear() to clear the data from the name-and-address object before passing in the next address.
Note: You are not required to call this function every time you pass in new address data. International ACE automatically clears data from the name­and-address object when you insert new data after calling process().
void nadClear(
void* nadPtr, int* error);
nadPtr Input: Pointer to a name-and-address object error Output: Contains a 1 if an error occurred.
76
getComponent
()

Synopsis

Arguments

Returns

bool getComponent(
NadOutputCompEnum component, FlCharType* compDataBuffer, int bufferLen, NadOutputCompStatusEnum& status, NadOutputCompTypeEnum type)const;
component Input: Output component to retrieve. For values, see
“NadOutputCompEnum” on page 163.
compDataBuffer Output: The output string.
bufferLen Input: Length of the compDataBuffer buffer allocated to hold
the output string.
status Output: Retrieval status. For a list of possible values, see
“NadOutputCompStatusEnum” on page 163.
type Optional input: Type of data. For a list of values, see
“NadOutputCompTypeEnum” on page 164.
Returns true if the component request is valid. Returns false if the component request is not valid—for example, if the requested component is not available for the country, or if the requested type is not available for this component.

Description

Call getComponent() to retrieve a specific address component.
International ACE places the component string (which includes a terminator) into your output buffer, compDataBuffer. The data is truncated to fit within the length specified by the bufferLen parameter. The status parameter indicates whether the data was truncated.
The maximum component length is defined in ciie.h.
NAD_MAX_COMPONENT_LENGTH, as
NULL

getComponent()

77

C function

int nadGetComponent(
void* nadPtr, NadOutputCompEnum component, FlCharType* compDataBuffer, int bufferLen, NadOutputCompStatusEnum* status, NadOutputCompTypeEnum type, int* error);
nadPtr Input: Pointer to a name-and-address object component See description on previous page. compDataBuffer See description on previous page. bufferLen See description on previous page. status See description on previous page. type See description on previous page. error Output: Contains a 1 if an error occurred.
78

getComponent_u()

Synopsis bool getComponent_u(

NadOutputCompEnum component, FlUChar* compDataBuffer, int bufferLen, NadOutputCompStatusEnum& status, NadOutputCompTypeEnum type ) const;

Arguments component Input: Output component to retrieve. For values, see

“NadOutputCompEnum” on page 163.
compDataBuffer Output: The output string.
bufferLen Input: Length of the compDataBuffer buffer allocated to
hold the output string in Unicode code-units.
status Output: Retrieval status. For a list of possible values, see
“NadOutputCompStatusEnum” on page 163.
type Input: Type of data. For a list of values, see
“NadOutputCompTypeEnum” on page 164.

Returns Returns true if the component requested is valid. Returns false if the component

request is not valid—for example, if the requested component is not available for the country, or if the requested type is not available for this component.

Description Call getComponent_u() to retrieve a specific address component.

International ACE places the component string (which includes a terminator) into your output buffer, compDataBuffer. The data is truncated to fit within the length specified by the bufferLen parameter. The status parameter indicates whether the data was truncated.
NULL
The maximum component length is NAD_MAX_COMPONENT_LENGTH, as defined in ciie.h.
getComponent_u()
79

C function int nadGetComponent_u(

void* nadPtr, NadOutputCompEnum component, FlUChar* compDataBuffer, int bufferLen, NadOutputCompStatusEnum* status, NadOutputCompTypeEnum type, int* error);
nadPtr Input: Pointer to a name-and-address object component See description on previous page. compDataBuffer See description on previous page. bufferLen See description on previous page. status See description on previous page. type See description on previous page. error Output: Contains a 1 if an error occurred.
80
getComponentLocation
()

Synopsis

Arguments

Description

C function

void getComponentLocation(
NadOutputCompEnum component, NadLineEnum& line, int& offset, int& length)const;
component Input: Type of component. For a list of values, see
“NadOutputCompEnum” on page 163.
line Output: Line where component is located. For a list of values,
see “NadLineEnum” on page 161.
offset Output: Character offset of component in the line; starts at zero.
length Output: Length of component.
Call this function to find the location of a particular component in the original input data. If the component was found in the original data, the output parameters contain the line, character offset, and length of the component, respectively. If the component was not found, line is set to –1, and length is set to 0 (zero).
NAD_LINE_UNDEFINED, offset is set to
void nadGetComponentLocation(
void* nadPtr, NadOutputCompEnum component, NadLineEnum* line, int* offset, int* length, int* error);
nadPtr Input: Pointer to a name-and-address object component See description above. line See description above. offset See description above. length See description above. error Output: Contains a 1 if an error occurred.

getComponentLocation()

81
getFaultCode
()

Synopsis

Arguments

Returns

Description

C function

NadFaultCodeEnum getFaultCode();
None.
Returns the address-fault code for the address that was most recently processed using this name-and-address object. For a list of values, see “NadFaultCodeEnum” on page 161.
After processing an address, call this function to get the address-fault code. The address-fault code indicates why an address could not be assigned, if applicable.
To get a fault-code string such as “F101” or a description string such as “Last line is bad or missing,” call FlNadFaultCodeEnumToString().
NadFaultCodeEnum nadGetFaultCode(
void* nadPtr, int* error);
nadPtr Input: Pointer to a name-and-address object error Output: Contains a 1 if an error occurred.
82
getStandardizeLineData
()

Synopsis

Arguments

Description

C function

void getStandardizeLineData(
NadLineEnum line, FlCharType* dataBuffer);
line Input: Line to retrieve. For a list of values, see “NadLineEnum”
on page 161.
dataBuffer Output: The standardized data.
Call this function to retrieve a line of corrected data. The output line corresponds to the input line, but may contain corrected data. You must provide a buffer long enough to hold the result. The maximum data copied to the buffer is the length returned from getStandardizeLineLength().
For U.S. and Canadian engines, if corrected data is not available, dataBuffer contains the original data. For the international engine, if corrected data is not available, dataBuffer is blank.
void nadGetStandardizeLineData(
void* nadPtr, NadLineEnum line, FlCharType* dataBuffer, int* error);
nadPtr Input: Pointer to a name-and-address object line See description above. dataBuffer See description above. error Output: Contains a 1 if an error occurred.

getStandardizeLineData()

83

getStandardizeLineData_u()

Synopsis void getStandardizeLineData_u(

NadLineEnum line, FlUChar* dataBuffer );

Arguments line Input: Line to retrieve. For a list of values,

see “NadLineEnum” on page 161.
dataBuffer Output: The standardized data.

Returns None.

Description Call this function to retrieve a line of corrected data. The output line corresponds

to the input line, but may contain corrected data. You must provide a buffer long enough to hold the result. The maximum data copied to the buffer is the length returned from getStandardizeLineLength(). The length is the number of Unicode code-units (UTF-16 entities).
For U.S. and Canadian engines, if corrected data is not available, dataBuffer contains the original data. For the international and Japan engine, if corrected data is not available, dataBuffer is blank

C function void nadGetStandardizeLineData_u(

void* nadPtr, NadLineEnum line, FlUChar* dataBuffer, int* error);
nadPtr Input: Pointer to a name-and-address object line See description above. dataBuffer See description above. error Output: Contains a 1 if an error occurred.
84
getStandardizeLineLength
()

Synopsis

Arguments

Returns

Description

C function

int getStandardizeLineLength(NadLineEnum line)const;
line Input: Type of line. For a list of values, see NadLineEnum on
“NadLineEnum” on page 161.
Returns the current maximum line length.
Call this function to get the maximum length of a particular type of standardized output line.
int nadGetStandardizeLineLength(
void* nadPtr, NadLineEnum line, int* error);
nadPtr Input: Pointer to a name-and-address object line See description above. error Output: Contains a 1 if an error occurred.

getStandardizeLineLength()

85
getStatus
()

Synopsis

Arguments

Returns

Description

C function

bool getStatus(NadStatusEnum statusFlag)const;
statusFlag Input: Type of status flag to query. For a list of values, see
“NadStatusEnum” on page 165.
Returns the boolean value of the status flag: true or false.
Call this function to query a status flag. Status flags provide information about the address.
int nadGetStatus(
void* nadPtr, NadStatusEnum statusFlag, int* error);
nadPtr Input: Pointer to a name-and-address object statusFlag See description above. error Output: Contains a 1 if an error occurred.
86

getSupportedCountry()

Synopsis

Arguments

Returns

Description

C function

SupportedCountriesEnum getSupportedCountry() const;
None.
Returns the SupportedCountriesEnum value for the address that was most recently processed using this name-and-address object. For a list of values see “SupportedCountriesEnum” on page 178.
After processing an address, call this function to get the supported country enumerated value.
SupportedCountriesEnum nadGetSupportedCountry (
void* nadPtr, int* error);
nadPtr Input: Pointer to a name-and-address object. error Output: Contains a 1 if an error occurred.
getSupportedCountry()
87
insertLineData
()

Synopsis

Arguments

Description

void insertLineData(
NadLineEnum line, const FlCharType* newData, int tunerIndex = –1);
line Input: Input field to insert data into (see “NadLineEnum” on
page 161).
newData Input: Input data.
tunerIndex Optional input: Tuner index. Use the value –1.
Call this function to insert input data into a specific input field on the name-and­address object. The input data must be a
The function ignores any extra words in a field or extra characters in a word. The maximums are defined in ciie.h as
NAD_MAX_CHARS_PER_WORD, respectively.
For information about which field combinations are not valid, see “NadLineStateEnum” on page 162.
Note: If you are using the International engine, for last-line data (locality, region, postal code), we recommend that you use either the
NAD_LINE_LASTLINE input field or the NAD_LOCALITY1, NAD_LINE_REGION, and NAD_LINE_POSTCODE fields (rather than NAD_LINE_MULTILINE).
NULL terminated string.
NAD_MAX_WORDS_PER_LINE and

C function

void nadInsertLineData(
void* nadPtr, NadLineEnum line, const FlCharType* newData, int tunerIndex, int* error);
nadPtr Input: Pointer to a name-and-address object line See description above. newData See description above. tunerIndex See description above. Not optional for C. error Output: Contains a 1 if an error occurred.
88

insertLineData_u()

Synopsis void insertLineData_u(

NadLineEnum line, const FlUChar* newData, int tunerIndex = -1);

Arguments line Input: Input field to insert data into

(see “NadLineEnum” on page 161).
newData Input: Input data. tunerIndex Optional input: Tuner index. Use the value –1.

Returns None.

Description Call this function to insert input data into a specific input field on the name-and-

address object. The input data must be a
For information about which field combinations are not valid, see “NadLineStateEnum” on page 162.
Note: If you are using the International engine, for last-line data (locality, region, postal code), we recommend that you use either the
NAD_LINE_LASTLINE input field or the NAD_LINE_LOCALITY1, NAD_LINE_REGION, and NAD_LINE_POSTCODE fields (rather than NAD_LINE_MULTILINE).
NULL terminated string.

C function void nadInsertLineData_u (

void * nadPtr, NadLineEnum line, const FlUChar* newData, int tunerIndex, int* error);
nadPtr Input: Pointer to a name-and-address object line See description above. newData See description above. tunerIndex See description above. Not optional for C. error Output: Contains a 1 if an error occurred.
insertLineData_u()
89

openTuner_u()

Synopsis int openTuner_u(

const FlUChar* tunerFilename );

Arguments tunerFilename Input: name of the file with the tuning parameters.

Returns Returns the tuning index.

Description Call this function to open the tuning file.

Make sure the input file and path name is in Unicode encoded ASCII data. International ACE can not process non-ASCII file or path names.

C function int nadOpenTuner_u(

void* nadPtr, const FlUChar* tunerFilename, int* error);
nadPtr Input and output: naddress object. tunerFilename Input: name of the file with the tuning parameters. error Output: indicates whether an error occurred.
90
process
()

Synopsis

Arguments

Returns

bool process(PubEngineClass* engine);
engine Input: Pointer to the engine object that should be used to process
the data stored on the name-and-address object.
The meaning of the return value varies by engine:
Australian engine: Returns true if a delivery-point identifier was assigned. Otherwise, returns false. A return of false does not necessarily mean that no output was produced, or that no data was corrected. It means only that a delivery­point identifier could not be assigned for the address, which may indicate a problem with the address.
Country ID engine: Returns true if the country was identified. Otherwise, returns false.
International engine: Returns true if International ACE verified or generated the postal code. Otherwise, returns false.
U.S. and Canadian engines: Returns true if the address was corrected to the finest depth. Otherwise, returns false. A return of false does not necessarily mean that no output was produced, but rather that the output was produced without complete confirmation from the lookup process. For example, perhaps the locality, region, and postal code were verified, but the address-line data could not be verified.

Description

Call this function to use a particular engine object to process the data stored on the name-and-address object.
After processing, the engine passes the results back to the name-and-address object. If you use more than one engine to process a record, the name-and-address object retains results only for the last engine it was processed on. (However, that the name-and-address object retains the original input data until you insert new data.)

process()

91

C function

int nadProcess(
void* nadPtr, void* engPtr, int* error);
nadPtr Input: Pointer to a name-and-address engine object.
engPtr Input: Pointer to the engine object that should be used to process
the data stored on the name-and-address object.
error Output: Contains a 1 if an error occurred.
92
produceReport
()

Synopsis

Arguments

Returns

Description

bool produceReport(
const PubEngineClass* engine const FlCharType* rptBuf) const;
engine Input: A pointer to the appropriate engine object to produce the
certification report for that country.
rptBuf Output: Buffer where the report will be written. You are
responsible for allocating and deallocating the memory for this buffer. It should be created with a size of NAD_REPORT_LENGTH, which is defined in ciie.h.
If you want the report to write directly to a file, call setReportInfo (RPT_TYPE,RPT_TYPE_FILE). See “setReportInfo()” on page 96.
Returns true if a report was produced successfully, false otherwise.
Call produceReport() after the file is processed to create a country specific certification report.
Note: The default names of the report files are CAcrtrpt.txt for Canada, UScrtrpt.txt for US, and AUcrtrpt.txt for Australia. You may set the path to the location of these files, or change their name by calling setFile(ENGINE_FILE_CERT_RPT, path and file name).

C function

void nadProduceReport(
void* nadPtr,
const void* engine, FlCharType* rptBuf, int* error);
nadPtr Input: Pointer to a name-and-address object engine See description above. rptBuf See description above. error Output: Contains a 1a 1 if an error occurred.

produceReport()

93

produceReport_u()

Synopsis bool produceReport_u(

const PubEngineClass* engine, FlUChar* rptBuf ) const;

Arguments engine Input: A pointer to the appropriate engine object to produce the

certification report for that country.
rptBuf Output: Buffer where the report will be written. You are
responsible for allocating and deallocating the memory for this buffer. It should be created with a size of NAD_REPORT_LENGTH, which is defined in ciie.h. If you want the report to write directly to a file, make this pointer NULL.

Returns Returns true if a report was produced successfully, false otherwise.

Description Call produceReport_u() after the file is processed to create a country specific

certification report.

C function int nadProduceReport_u(

void* nadPtr, const void* engine, FlUChar* rptBuf, int* error);
nadPtr Input: Pointer to a name-and-address object engine See description above. rptBuf See description above. error Output: Contains a 1 if an error occurred.
94
setReportInfo
()
There are five different options for setReportInfo(). This option allows you to set the item to double. Use this method for U.S. or Canadian reports.

Synopsis

Arguments

Returns

Description

C function

void setReportInfo(
ReportItemEnum item const double value);
item Input: The item to be set.
value Input: Set the item to a value.
void
Call setReportInfo() to set information used to create certification reports.
void nadSetDoubleReportInfo(
void* nadPtr, ReportItemEnum item, const double* value, int* error);
nadPtr Input: Pointer to a name-and-address object item See description above. value See description above. error Output: Contains a 1 if an error occurred.

setReportInfo()

95
setReportInfo
()
There are five different options for setReportInfo(). This option allows you to set the item to init*. Use this method for U.S. or Canadian reports.

Synopsis

Arguments

Returns

Description

C function

void setReportInfo(
ReportItemEnum item, For a list of values, see
“ReportItemEnum” on page 175
const int value);
item Input: The item to set.
value Input: Set the item to a value.
void
Call setReportInfo() to set the information used to create certification reports.
void nadSetIntReportInfo(
void* nadPtr, ReportItemEnum item, For a list of values, see
“ReportItemEnum” on page 175
const int value); int* error);
nadPtr Input: Pointer to a name-and-address object selection See description above. value See description above. error Output: Contains a 1 if an error occurred.
96
setReportInfo
()
There are five different options for setReportInfo(). This option allows you to set the item to long. Use this method for U.S. or Canadian reports.

Synopsis

Arguments

Returns

Description

C function

void setLongReportInfo(
ReportItemEnum item, const long value);
item Input: The item to set.
value Input: Set the item to a value.
void
Call setReportInfo() to set the information used to create certification reports.
void nadSetLongReportInfo(
void* nadPtr, ReportItemEnum item, const long value); int* error);
nadPtr Input: Pointer to a name-and-address object selection See description above. value See description above. error Output: Contains a 1 if an error occurred.

setReportInfo()

97

setReportInfo()

There are five different options for setReportInfo(). This option allows you to set a variety of items. Use this method for U.S. or Canadian reports.

Synopsis

Arguments

void setReportInfo(
bool extendedASCII, const FlCharType* certifiedCompanyName, const FlCharType* processingCompanyName, const FlCharType* processFileName, const FlCharType* IDNumber, const FlCharType* processingCompanyAddress[ ], int numAddressLines, const FlCharType* softwareVersion );
extendedASCII Input: true if your printer supports the extended ASCII set, false
if your printer does not support the extended ASCII set.
certifiedCompanyName
Input: If your company self-certifies, list the name of your company. If not, leave blank, and Firstlogic’s name will appear on the report.
processingCompanyName
Input: the name of the company preparing the report.
processFileName Input: the input file name for the report.
IDNumber Input: U.S. engine: leave blank.
Canadian engine: the Canada Post Customer (CPC) number.
Australian engine: leave blank.

Returns

Description

98
processingCompanyAddress
Input: the address of the company preparing the report. The maximum is 12 lines. Only the first four lines are used in U.S., Canada, and Australia.
numAddressLines Input: the number of address lines.
SoftwareVersion Input: U.S. engine: If your company self-certifies, put
the version of your software here. Otherwise, leave this blank. Other engines: leave this blank.
void
Call setReportInfo() to set the information used to create a certification report.

C functions

void nadSetReportInfo(
int* extendedASCII const FlCharType* certifiedCompanyName, const FlCharType* processingCompanyName, const FlCharType* processFileName, const FlCharType* IDNumber, const FlCharType* processingCompanyAddress[ ], int* numAddressLines, const FlCharType* softwareVersion, int* error);
nadPtr Input: Pointer to a name-and-address object extendedASCII See description above. certifiedCompanyName See description above. processingCompanyName See description above. processFileName See description above. IDNumber See description above. processingCompanyAddress[ ] See description above. numAddressLines See description above. softwareVersion See description above.errorOutput: Contains a
1 if an error occurred.
setReportInfo()
99
setReportInfo
()
There are five different options for setReportInfo(). This option allows you to set the item to long. Use this method for Australian reports.

Synopsis

Arguments

Returns

Description

C function

void setReportInfo(
ReportItemEnum item, const FlCharType* str);
item Input: The item to set.
value Input: Set the item to a value.
void
Call setReportInfo() to set the information used to create certification reports.
void nadSetStringReportInfo(
void* nadPtr, ReportItemEnum item, const FlCharType* value); int* error);
nadPtr Input: Pointer to a name-and-address object item See description above. value See description above. error Output: Contains a 1 if an error occurred.
100
Loading...
Buy Points How it Works FAQ Contact Us Questions and Suggestions Privacy Policy Cookie Policy Terms of Use