800c Ace LR en

ACE
Library Reference
ACE 8.00c
September 2009
Contact information Find contact information on the Web at http://service.sap.com.
Copyright information © 2009 SAP® BusinessObjects™. All rights reserved. SAP BusinessObjects owns
the following United States patents, which may cover products that are offered and
licensed by SAP BusinessObjects and/or affiliated companies: 5,295,243; 5,339,390;
5,555,403; 5,590,250; 5,619,632; 5,632,009; 5,857,205; 5,880,742; 5,883,635;
6,085,202; 6,108,698; 6,247,008; 6,289,352; 6,300,957; 6,377,259; 6,490,593;
6,578,027; 6,581,068; 6,628,312; 6,654,761; 6,768,986; 6,772,409; 6,831,668;
6,882,998; 6,892,189; 6,901,555; 7,089,238; 7,107,266; 7,139,766; 7,178,099;
7,181,435; 7,181,440; 7,194,465; 7,222,130; 7,299,419; 7,320,122; 7,356,779 and
7,475,062. SAP BusinessObjects and its logos, BusinessObjects, Crystal Reports®,
SAP BusinessObjects Rapid Mart™, SAP BusinessObjects Data Insight™, SAP
BusinessObjects Desktop Intelligence, SAP BusinessObjects Rapid Marts®, SAP
BusinessObjects Watchlist Security™, SAP BusinessObjects Web Intelligence®, and
Xcelsius® are trademarks or registered trademarks of Business Objects, an SAP
company and/or affiliated companies in the United States and/or other countries.
SAP® is a registered trademark of SAP AG in Germany and/or other countries. All
other names mentioned herein may be trademarks of their respective owners.
USPS information Business Objects is a non-exclusive Interface Distributor Licensee of the United
States Postal Service. The following trademarks are owned by the United States
Postal Service: USPS, CASS, Standard Mail, First-Class Mail, DPV, LACSLink,
NCOALink, and United States Postal Services.
2 ACE Library Reference

Preface
About ACE Library With ACE Library, you can integrate Address Correction and Encoding
capabilities to gain accurate, complete, and current addresses that ensure that
your mailings move quickly through the U.S. Postal Service (USPS) automated
mail system.
ACE is Coding Accuracy Support System (CASS)-certified by the USPS.
About this guide This manual is a reference for software developers who integrate our ACE
Library. It explains how to make other applications work with the library. It also
contains detailed reference pages about each of the function calls.
In this manual, we assume that you already are familiar with the C programming
language, your operating system, and with basic concepts of database
management, mail processing, and address processing.
ACE documentation You can access product documentation in several places:

! On your computer. User’s Guides and other manuals for each product that
you have installed are available in the Documentation folder. Choose Start >
Programs > Business Objects Applications > Documentation.
! On the SAP Corporate Portal. Go to http://help.sap.com to access all the
latest product documentation.
1. Open the SAP BusinessObjects tab at the top of the page.
1. Select All Products from the list at left.
2. Select Data Quality from the All Products drop list.
3. Select ACE from the All Releases drop list.
In addition, ACE Views comes with a built-in help file that provides descriptions
of options and steps to perform ACE processes. To access the ACE Views help
file, open ACE and choose Help > Help Topics.
For information about ACE features and options and about setting up jobs in
ACE Job-File, Views, Library, and Rapid, see the following documentation:
ACE documentation
! ACE Release Notes
! ACE User’s Guide
! ACE Job-File Reference
! ACE Library Reference
! Mover ID User’s Guide for NCOALink
Preface 3
Other useful documents
! System Administrator’s Guide
! Views Quick Start Guide
! Database Prep
! Quick Reference for Views and Job-File Products
! Quick Reference for Library Products
! RAPID User’s Guide
! Edjob User’s Guide
Conventions This document adheres to the following documentation conventions:
Convention Description
Bold We use bold type for file names and paths. When we’re explaining
something that you would type on your computer, bold indicates
something that you should type exactly as shown; for example,
“Type cd\dirs.”
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 .job extension (jobname.job).”
Menu commands We indicate commands that you choose from menus in the follow-
ing format: Menu > Command. 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.
If you are writing your application in Visual Basic language, please
watch for this symbol in the margins. It will alert you to special tips
and procedures for Visual Basic.

Contents
Preface .............................................................................................................3
Chapter 1:
Install, compile, and set up ACE Library ................................................... 7
Install ACE Library..........................................................................................8
Sample application programs ...........................................................................9
Three options for initialization and termination.............................................10
ACE function calls for keycodes....................................................................13
eim_add_keycode() ........................................................................................13
eim_keycode_global_init(), eim_keycode_global_ term() ............................13
ACE function calls for address processing ....................................................14
Address input and output................................................................................15
Error handling ................................................................................................17
How to use the Z4Change functions ..............................................................18
How to use the GeoCensus functions.............................................................19
Chapter 2:
Functions for address processing............................................................... 21
Chapter 3:
Suggestion lists............................................................................................. 67
How to handle suggestion lists.......................................................................68
How to customize suggestion lists .................................................................77
Chapter 4:
How to query the postal directories........................................................... 81
Introduction to directory queries ....................................................................82
How to query the ZIP+4 directory .................................................................83
Browse fields for ace_get_query() .................................................................86
How to query the City and ZCF directories ...................................................93
Chapter 5:
Delivery Point Validation (DPV) ............................................................. 103
What is Delivery Point Validation (DPV)?..................................................104
USPS requirements ......................................................................................105
Installing DPV and its directories ................................................................106
Performing DPV processing.........................................................................107
DPV output components ..............................................................................108
DPV performance.........................................................................................110
DPV locking.................................................................................................111
DPV false positive log..................................................................................112
DPV No Stats indicators ..............................................................................113
DPV Vacant indicators.................................................................................114
Chapter 6:
Residential Delivery Indicator (RDI) ...................................................... 117
What is RDI?................................................................................................118
Contents 5
RDI directories............................................................................................. 119
Enable RDI processing ................................................................................ 120
Chapter 7:
Mover ID for NCOALink......................................................................... 121
ace_mvid_set_contact_info()....................................................................... 126
Chapter 8:
LACSLink.................................................................................................. 141
Overview...................................................................................................... 142
Install LACSLink and its directories ........................................................... 143
Performing LACSLink processing .............................................................. 144
LACSLink output components .................................................................... 145
LACSLink performance .............................................................................. 146
LACSLink locking....................................................................................... 147
LACSLink false positive log ....................................................................... 148
ace_get_lacs_msg()...................................................................................... 149
Chapter 9:
SuiteLink.................................................................................................... 151
How does SuiteLink work?.......................................................................... 152
Set up SuiteLink processing ........................................................................ 153
SuiteLink output fields................................................................................. 154
Index............................................................................................................ 155

Chapter 1:
Install, compile, and set up ACE Library
Welcome to the ACE Library! This chapter, provides basic installation

information, how to initialize the ACE library, and how to control the way that
ACE processes addresses.
Chapter 1: Install, compile, and set up ACE Library 7

Install ACE Library
Windows We provide a 32-bit DLL that may be used in Windows. See your latest release
notes for more information about supported operating systems and compilers.
Install ACE following the instructions in our System Administrator’s Guide. ACE
will be installed in \pw\acelib.
UNIX Install ACE following the instructions in our System Administrator’s Guide. ACE
will be installed in …/postware/acelib.
For more information about supported compilers, see your latest release notes, or
the System Administrator’s Guide.

Sample application programs
All copies of the ACE Library are shipped compiled and ready to link.
Source code is not available, however, the ACE Library comes with source code
for simple application programs:
Program Description
addrtest.c An interactive program (using the standard I/O) for processing individual
addresses.
showtest.c An interactive program (using the standard I/O) for querying the national
ZIP+4 directory.
shwlltst.c An interactive program (using the standard I/O) for querying the City and
ZCF directories.
acetest.c A batch program for processing the CASS Stage II test file. Modes of
address standardization are set per CASS rules. Useful primarily for those
who seek end-user CASS certification. See the ACE User’s Guide for
details on CASS.
These are examples intended for use only as learning tools. They are not
prototypes or products. We do not support or authorize any use for commercial
purposes, and we disclaim any warranty regarding such use.
How to compile To compile addrtest, use the make-file addrtest_mk, which is installed in your
addrtest acelib directory.
This procedure is similar for the other sample application programs.

Three options for initialization and termination
ACE stores configuration settings, file handles, and input and output data in a
structure called the address handle (diagram on page 16). Most ACE functions
require the address handle as an input parameter. Most of the work of initializing
ACE is about preparing the address handle. If your application is multi-threaded,
you will allocate one address handle per thread. ACE offers three ways to
initialize and terminate the address handle:
! Full use of configuration files, with minimal API function calls.
! Selective use of configuration files and API function calls.
! No use of configuration files; do everything with API function calls.
The sections on the following pages explain the typical function-call sequence for
each method. These sections focus only on initialization and termination. For
Address processing see “ACE function calls for address processing” on page 14.
Note: For simplicity, some optional “get information” calls are ignored.
Option 1: Full use of This approach is good for fast prototyping and some applications.
configuration files and
minimal API function 1. Call ace_init() to allocate memory and initialize global data used by ACE.
calls 2. Recommended: Register your own function for handling errors. Call
ace_init_addr() to allocate and initialize an address handle. Then call
ace_set_error_rtn() to set up your function. Inside your function, you may
call ace_get_error_info() to retrieve information about errors.
3. Optional: Call eim_keycode_global_init() to initialize the SAP
BusinessObjects keying system.
4. Optional: Call eim_add_keycode() once for each keycode owned to add the
keycode to the keycode collection.
5. Call ace_cfg_open() to open the directories and configure the address handle
based on settings in the configuration files. (The function will detect that an
address handle has already been allocated.) An error in a configuration file
will cause this function to return ACE_ERROR, invoking the error handler.
6. Optional: Call eim_keycode_global_term() to terminate the SAP
BusinessObjects keying system and free memory that it has used.
7. Process addresses as explained in “ACE function calls for address
processing” on page 14.
8. Optional: Call ace_3553_file() to generate USPS Form 3553, the CASS
Summary Report.
9. Call ace_cfg_close() to close the ACE auxiliary files and free the address
handle.
10. Optional: Call eim_keycode_global_term() to free global memory used by
the keycode collection
11. Call ace_term() to free global memory used by ACE.

Option 2: Selective This method was developed specifically for client/server applications, where
use of configuration some aspects of configuration are set on the client side, by an end user (style
files and API function options, choice of input fields) and other aspects (pathnames of auxiliary files)
calls need to be set on the server side, by an administrator.
1. Call ace_init() to allocate memory and initialize global data used by ACE.
2. Call ace_init_addr() to allocate and initialize an address handle.
3. Recommended: If you intend to use your own function for handling errors,
call ace_set_error_rtn() to set up your function. Inside your function, you
may call ace_get_error_info() to retrieve information about errors.
Call ace_cfg_read() up to three times, to load settings from three
configuration files. The table below shows the API calls that you can skip if
you use each configuration file—or, viewed the other way, the API calls you
must make if you are not using a particular configuration file.
Config file API calls
Auxiliary Call ace_set_mode() as necessary to set optional modes. See

“ace_set_mode(), ace_get_mode()” on page 56 for details.
Call ace_set_file() to register the pathnames of the auxiliary files.
Options By default, ACE standardizes addresses in a style fully conforming to
the CASS testing regulations of the U.S. Postal Service. You are not
required to process your own data in CASS-conforming style. To set
stylistic options, you may call ace_set_option() as necessary. CASS
rules and the stylistic options are fully explained in the ACE User’s
Guide.
Input fields ACE offers various input fields. These are explained in the Quick Refer-
ence for Library Products. Having selected which fields you will use,
call ace_set_input_length() once per field. Then call ace_evaluate_ah()
to verify that a valid combination of fields is set up.

5. Optional: Call eim_add_keycode() once for each keycode owned to add the
keycode to the keyfile collection.
6. Call ace_open() to open the auxiliary files.
BusinessObjects keying system and free memory it has used.
8. Your address handle should now be ready to begin processing addresses.
Summary Report.
11. Call ace_close() to close the ACE auxiliary files.
12. Call ace_term_addr() to free the address handle.

Option 3: No use of This approach gives the application engineer maximum flexibility and control,
configuration files; do but requires more coding.
everything with API
function calls 1. Call ace_init() to allocate memory and initialize global data used by ACE.
2. Call ace_init_addr() to allocate and initialize an address handle.
3. Recommended: If you intend to use your own function for handling errors,
call ace_set_error_rtn() to set up your function. Inside your function, you
may call ace_get_error_info() to retrieve information about errors.
4. Optional: Call ace_set_mode() as necessary to set optional modes. See
“ace_set_mode(), ace_get_mode()” on page 56 for details.
5. Call ace_set_file() to register the pathnames of the auxiliary files.
7. Optional: Call eim_add_keycode() once for each keycode owned to add
keycode to keycode collection.
BusinessObjects keying system and free memory it used.
10. ACE offers a set of about two dozen input fields. These are explained in the
Quick Reference for Library Products. Having selected which fields you will
use, call ace_set_input_length() once per field. Then call
ace_evaluate_ah() to verify that a valid combination of fields is set up.
11. Optional: By default, ACE standardizes addresses in a style fully conforming
to the CASS testing regulations of the U.S. Postal Service. You are not
required to process your own data in CASS-conforming style. If you wish,
you may call ace_set_option() as necessary to set stylistic options of your
choosing. CASS rules and the stylistic options are fully explained in the ACE
User’s Guide.
12. Optional: If you intend to support suggestion lists, you may need to call some
of those functions to set up handling and options. See “Suggestion lists” on
page 67 for details. Also, if you intend to support consolidated suggestion
lists (“How to customize suggestion lists” on page 77), you may need an
extra call to ace_set_file().
13. Your address handle should now be ready to begin processing addresses.
Summary Report.
16. Call ace_close() to close the ACE auxiliary files.

ACE function calls for keycodes
Library users have the option to use the following functions to enter product
activation keycodes within application code. This is an alternative to using the
License Manager to enter product activation keycodes in the registry. These
function calls are optional.
eim_add_keycode()
Synopses void eim_add_keycode(const char* keycode);
Description The eim_add_keycode() function adds a single key code to the collection of SAP
BusinessObjects key codes used for enabling product functionality. This function
may be called once per key code owned.
All calls to eim_add_keycode() must occur between eim_keycode_global_init()
and eim_keycode_global_term(), and must be called before ace_open().
Returns None
eim_keycode_global_init(), eim_keycode_global_ term()
Synopses void eim_keycode_global_init(void);

void eim_keycode_global_term(void);
Description The eim_keycode_global_init() and eim_keycode_global_term() functions are

only required if eim_add_keycode() is called within the application. The
eim_keycode_global_init() function initializes the SAP BusinessObjects keying
system for use. An eim_keycode_global_init()call must precede any call to
eim_add_keycode(). The eim_keycode_global_term() function releases all
memory allocated by the SAP BusinessObjects keying system functions and
terminates the SAP BusinessObjects keying system. This call must be made at
some point following ace_open(). These functions are meant to be called once per
application, and are not meant to be called once per thread.
Returns None

ACE function calls for address processing
Process addresses 1. Loop through the ACE input fields you chose. Call ace_set_line() to pass
input data one field at a time. If you have no input data for a field, pass an
empty string.
2. Call ace_findf() to perform address parsing and directory look-up and
retrieval.
3. Check the return status of ace_findf() and proceed as explained in the table
below.
Return value Action
ACE_ABORT An internal error occurred.

ACE_ERROR
ACE_FOUND The address was assigned. Go ahead and retrieve the
processed address data from ACE. Most applications
make a combination of calls to ace_get_line() and
ace_get_component(). Read more about this in “ACE
function calls for address processing” on page 14).
ACE_NOT_FOUND The address was not assigned. (To find out why not,
check the ACE_ERROR_CODE component.) ACE has
standardized the address and populated the output lines
and components as best it can. The extent of standard-
ization is very modest, and some components are blank.
Retrieve the processed address data from ACE. Most
applications make a combination of calls to
ace_get_line() and ace_get_component(). Read more
about this in “ACE function calls for address process-
ing” on page 14).
ACE_FOREIGN If you are also using ACE Canada, load this address
into the CADDR_HANDLE and call cace_findf().
Otherwise, respond the same as to
ACE_NOT_FOUND.
ACE_USER_CITY Invoke your suggestion-list handler. (See “Suggestion
ACE_USER_ADDRESS lists” on page 67 for information about handling sug-
ACE_USER_SECONDARY gestion lists.)

Address input and output
You will pass input address data to ACE by calling ace_set_line() once for each
input field to be loaded. Then call ace_findf() to process the address. For output,
ACE offers two methods: ace_get_line() and ace_get_component().
ace_get_line() Choose ace_get_line() when you want to keep output address data in the same
arrangement of fields as were input.
ACE applies intelligent abbreviation, when necessary, to keep the data within the
lengths you specified via ace_set_input_length().
Data is capitalized and standardized according to the way you set the stylistic
options.
ace_get_component() Choose ace_get_component() when you want the output address broken down
into smaller elements than you input (as shown in diagram). Also you can retrieve
additional fields created by ACE, such as the error/status code.
You may retrieve unstandardized or standardized components by setting a flag
with your call. To obtain the best setting for this flag, we recommend that you call
ace_get_source().
The style of standardized components is partially controlled by the stylistic
options.
Stylistic options If you retrieve a component that is part of something larger, the stylistic option
will apply. For example, within ACE_ADDRESS, the abbreviated or spelled-out
style of suffix and directionals is controlled by those options. The same is true for
the place-name conversion of city name within ACE_LASTLINE.
But if you retrieve the suffix, directionals, or city name by itself, then the stylistic
option does not apply. Instead, you make your stylistic choice by selecting from
two or three flavors of components, each with a different symbol. For example,
compare ACE_SUFFIX with ACE_APL_SUFFIX.
No abbreviation No abbreviation is applied. For each component, we provide a defined length

symbol. Simply append the suffix “_LEN” to the component symbol. For
example, when allocating a buffer for ACE_CITY, use ACE_CITY_LEN.
Line and component Line and component symbols are defined in ace.h and explained in the Quick
symbols Reference for Library Products. Line symbols all begin with ACE_I* and
components simply begin with ACE_*

Diagram Think of the address as having four sections or quadrants. When you call
ace_set_line(), you are loading one line in the first quadrant (upper left corner of
diagram). ACE populates the other three quadrants when you call ace_findf()..

Error handling
Many ACE functions return the same data that they output. This makes these
functions easy to use in printf() statements. However, there may be no error
indication other than an empty return.
Some ACE functions return ACE_ERROR when the execution results in an error.
Any ACE_ERROR return indicates a fatal error—with just one exception. There
is only one situation, a directory expiration warning, in which you could process
an error but continue running. See ace_open() on page 49.
Default error handling Some languages do not support function pointers. If you cannot set your own
error handler, ACE will present error messages directly to the end user:
! Most versions will present a printf() message on the standard out.
! Windows DLLs will present a pop-up window (a default MsgBox).
Setting your own You may set up a callback (or delegate) to your own error-handling function. Call
error handler ace_set_error_rtn() with a pointer to your function.
ACE will call your function whenever any ACE function returns ACE_ERROR.
Your function can then process the error as desired. Your function may call
ace_get_error_info() or ace_get_error_info_return() to obtain error information.
These functions give you an error code number, as well as two character strings
that provide additional information about the error or status.
The Visual Basic compiler supports passing function pointers. So if you are
using version 5.0 or later, you can create your own error-handling function.
Your function must be in a .vb file.
When you register your error handler with ACE, be sure to use the AddressOf
operator. Here’s an example function:
'Sample error handling routine
Public Function Error_Routine(ByVal ah As Integer) As Integer
Dim ErrorNbr As Long
Dim title As New String("", ACE_ERR_MAX_MSG_LEN)
Dim msgbody As New String("", ACE_ERR_MAX_MSG_LEN)
ace_get_error_info(ah, ErrorNbr, title, msgbody )
MessageBox.Show(msgbody , "Ace Error")
End Function
To register the error handler with ACE, you may need something like the
following example:
Public Delegate Function MakeDelegate(ByVal ah As Integer) As
Integer
'...set error handling routine
Dim objDelegate As MakeDelegate
objDelegate = AddressOf Error_Routine
retVal = ace_set_error_rtn(ah, objDelegate)

How to use the Z4Change functions
Z4Change is an extra-cost option available to ACE users. For information about

acquiring the Z4Change Option, call your SAP BusinessObjects’ sales
representative.
For more information about Z4Change, see the ACE User’s Guide.
Call sequence 1. Call ace_init() and ace_init_addr() as usual.

2. Call ace_set_mode(ah, ACE_MODE_ENABLE_Z4CHANGE, TRUE). This
tells ACE to open the Z4Change directory in addition to the other postal
directories.
3. Call ace_set_file() as usual. Add a call to set the location of the Z4Change
file.
5. Call ace_set_z4c_check_date() with the month and year that the input records
were most recently ZIP+4 coded (either through a full ACE process or a
previous Z4Change pass). ACE will verify that your date is within the 12-
month period covered by the Z4Change file.
6. Enter a loop, calling ace_z4_zip4_changed() with a string containing the ZIP
and ZIP+4 codes from the input record. The call with return TRUE or FALSE:
! FALSE: The address has not changed within the last 12 months. No
further processing should be necessary.
! TRUE: The address is affected by a change. Z4Change cannot provide
the new data. Put the record through the normal ZIP+4 assignment
process, with the usual call to ace_findf().
7. Call ace_close(), ace_term_addr(), and ace_term() as usual.
There is no special header file for Z4Change; all public defines and prototypes
are in ace.h. Compile as usual.

How to use the GeoCensus functions
GeoCensus is an extra-cost option available to ACE users. If you’d like

information about acquiring the GeoCensus Option, contact your account
representative.
For more information about GeoCensus, see the ACE User’s Guide.
Call sequence 1. Call ace_init() and ace_init_addr() as usual.

2. By default, ACE opens all auxiliary files. This is appropriate if you intend to
perform normal ACE processing and GeoCensus assignment in a single pass.
If your application is intended to perform GeoCensus processing ONLY, call
ace_set_mode(ah, ACE_MODE_GEO_ONLY, TRUE).
3. Call ace_set_mode() with ACE_MODE_GEO and the appropriate value:
ACE_CENTROID_GEO, ACE_ADDRESS_GEO, ACE_BEST_GEO, or
ACE_ALL_GEO. See “ace_set_mode(), ace_get_mode()” on page 56 for
details about these options.
4. Call ace_set_file() function as usual. Add a call to set the location of the
GeoCensus file.
5. Call ace_open() as usual.
6. If you are performing GeoCensus coding during a normal ACE process, call
ace_findf() as usual. Retrieve the GeoCensus codes by calling
ace_get_component(), just as you might retrieve other assigned codes.
7. If your application is intended to perform GeoCensus processing ONLY, call
ace_find_cgeo_data() where you would normally call ace_findf(). Do not call
ace_findf().
There is no special header file for GeoCensus; all public defines and prototypes
are in ace.h. Compile as usual.

Chapter 2:
Functions for address processing
This chapter contains a reference page for each function used in normal address
processing.
Chapter 2: Functions for address processing 21

ace_3553(), ace_3553_file()
Synopses char* ace_3553(eleven parameters);
ADDR_HANDLE ah; Input: address handle

int extended_ASCII; Input: printer supports extended ASCII?
TRUE
FALSE
char* company_name; Input: your company name or blank
char* list_processor; Input: your company name
char* list_name; Input: file or mailing list name
char* mailers_address1; |
char* mailers_address2; | Input: your company's name
char* mailers_address3; | and address
char* soft_name_vers_date; Input: or blank for default
int user_lot_cert; Input: end-user LOT certification
TRUE
FALSE
int ace_3553_file(twelve parameters);

char* report_file; Input: pathname of output file
TRUE
FALSE
char* company_name; Input: blank or your company name
char* soft_name_vers_date; Input: blank for default
TRUE
FALSE
Description The ace_3553() and ace_3553_file() functions generate a facsimile of USPS

Form 3553, the CASS Summary Report. See the ACE User’s Guide for
information about this report and the information that you must provide for it.
The ace_3553() function writes the report into a character array, while
ace_3553_file() writes the report directly into a file.
If you choose ace_3553_file(), ACE will create, open, and close the file for you.
All you have to do is provide the path and file name.
Parameters The extended_ASCII parameter should be set to TRUE if the target printer
supports that extended ASCII character set. If the target printer does not support
extended ASCII, set FALSE.

Set the user_lot_cert parameter to TRUE if either of the following conditions
applies to you:
! You rely on ACE for vendor CASS certification
! You have end-user CASS certification with LOT certification.
The LOT lines on your 3553 forms will be populated.

If you have end-user CASS certification, but did not seek or obtain LOT
certification, set the user_lot_cert parameter to FALSE. The LOT lines on your
3553 forms will be left blank.
The other parameters should not be left blank (""), because USPS clerks will not
accept a 3553 form that is incomplete or has been filled out by hand. There are
two exceptions; the values shown below will be used if you leave the following
parameters blank:
company_name SAP BusinessObjects
soft_name_vers_date PWACE version number date_of_cert
Returns The ace_3553() function returns a pointer to a character array containing the
form. If for some reason the form could not be built (perhaps because memory for
it could not be allocated), then ace_3553() returns NULLP.
The ace_3553_file() function returns ACE_OK if successful. It returns
ACE_ERROR if the file could not be opened and closed, or the report could not
be written. It returns ACE_INVALID_HANDLE if the input address handle was
invalid.
CASS rule for Caution: If your application supports suggestion lists, the USPS does not permit
suggestion lists us to generate a 3553 form when suggestion lists are used in address assignment.
Therefore, if suggestions are turned on, the form will be blank.
Visual Basic applications should use ace_3553_file(), not ace_3553().

ace_3553_hdr ()
Synopsis char * ace_3553_hdr(twelve parameters);

TRUE
FALSE
char* company_name; Input: blank or your company name
char* soft_name_vers_date; Input: blank for default
TRUE
FALSE
char * stage2_header_record; Input: first (header) record of a CASS stage 2 file
Description ace_3553_hdr() is only used when processing a CASS stage 2 file to self certify.
It fills in fields in the header record of the stage 2 CASS file with the PS Form
3553 information as required by the USPS when self certifying.
Parameters The software_name_vers_date cannot be blank and must contain both the
software name and version (date is optional). Company_name, list_name, and
list_processor also cannot be blank.
Returns If successful, ace_3553_hdr() returns a pointer to the header record that was sent
in as the last argument. It returns NULLP if unsuccessful.

ace_cfg_open(), ace_cfg_close(), ace_cfg_read()
Synopses int ace_cfg_open(two parameters);
char* pathname; Input: pathname of overall config file

ADDR_HANDLE* ah; Input or output: address handle
int ace_cfg_close(one parameter);
ADDR_HANDLE* ah; Input: address handle
int ace_cfg_read(three parameters);

int config_type; Input: config file type
ACE_CFG_AUXILIARY_FILES
ACE_CFG_OPTIONS
ACE_CFG_INPUT_FIELDS
char* pathname; Input: pathname of overall config file
Description ACE supports four types of configuration files. The “vanilla” configuration files
(table below) may be found in your acelib subdirectory. You should copy these
files before you edit them, and use your own filenames.
The configuration files are heavily commented. There is no separate or further
documentation for the parameters in these files.
Type of file Original name Description
Overall ace.cfg Pathnames of the other three configuration files.

Auxiliary aceaux.cfg Pathnames of the directories, dictionaries, etc.
Input_Fields aceflds.cfg Selection and lengths of input fields
Options aceopts.cfg Style and suggestion-list options.
The ace_cfg_open() function opens the auxiliary files and initializes one address
handle based on settings in configuration files. It calls ace_init_addr() and
ace_open(). The ace_cfg_close() function calls ace_term_addr() and ace_close().
We recommend that you do not rely on ace_cfg_open() to allocate the address
handle for you—if you do, then any error in the configuration files will probably
not be handled as you would want. Instead, follow the calling procedure in
“ace_cfg_open(), ace_cfg_close(), ace_cfg_read()” on page 25. When you call
ace_cfg_open(), pass your address handle, as input, through the second
parameter.
The ace_cfg_read() function is an alternative to ace_cfg_open(). It is provided for
client/server or other applications where you may need to employ configuration
files selectively. For example, in a client/server environment, the Options and
Input_Fields files might be set on the client side, by the end user, while the
Auxiliary file would be on the server side, and set by an administrator.

The ace_cfg_read() function loads settings into an address handle which you
must provide. This means that you must make your own call to ace_init_addr().
Likewise, ace_cfg_read() does not open the auxiliary files, so you must make
your own call to ace_open().
Returns Returns ACE_OK if successful; otherwise, ACE_ERROR. An error usually

indicates that something is wrong in one of the configuration files. Returns
ACE_INVALID_HANDLE if the input address handle was invalid.
Note: After ace_cfg_open(), make ace_get_*() calls to obtain the settings

that were read from the configuration files. For example, call
ace_get_option() to obtain current settings for address standardization.
When you call ace_cfg_read() with the ACE_AUXILIARY_CONFIG_FILE
symbol, ACE internally calls ace_open().

ace_evaluate_ah()
Synopsis int ace_evaluate_ah(one parameter);
Description The ace_evaluate_ah() function checks the input address structure for validity.
You do not have to call ace_evaluate_ah(). But if you do, call it after all your calls
to ace_set_input_length().
Returns Returns ACE_OK if the input lines structure is valid for parsing. Returns
ACE_INVALID_HANDLE if the input ADDR_HANDLE is invalid. The
following returns indicate a problem in the selection of input fields:
Symbol Description
ACE_2MANYLINES Too many fields were set. For example, you would get this
error if you set up all of the multiline fields (ACE_ILINE1-12)
and also set up ACE_IURB.
ACE_BADDEF No input fields at all were set up.
ACE_BADMLP An invalid combination of input fields was set. For example,
you would get this error if you have not selected any fields for
address-line data. Or if you select any of the multiline fields
while also selecting the discrete address-line, last-line, or city/
state/ZIP fields.
ACE_MULTI1 The multiline fields defined don't start with ACE_ILINE1. If
you have three multiline fields, you must use ACE_ILINE1-3,
not 4-6, for example.
ACE_MULTI2 The multiline fields are not consecutive. For example, you
would get this error if you set up the multiline fields
ACE_ILINE1, ACE_ILINE3, and ACE_ILINE4.
ACE_MULTI3 You have set up all of the multiline fields (ACE_ILINE1-12)
and also set up ACE_IZIP4. ACE does not accept a separate
ZIP+4 field in this configuration.
ACE_NO_LL_FIELDS No last-line fields were set. For example, you would get this
error if you have not selected any fields for last-line data. Or if
you select any of the multiline fields while also selecting the
discrete address-line, last-line, or city/state/ZIP fields.

ace_find_ageo_data()
Synopsis int ace_find_ageo_data(seven parameters);
ADDR_HANDLE ah; input: address handle

char *zip input: ZIP Code
char *pname input: primary (street) name
char *predir input: predirectional
char *postdir input: postdirectional
char *suffix input: suffix
char *prange input: primary range (house number)
Description If your application is intended to perform Address-Level GeoCensus processing

ONLY, call ace_find_ageo_data() where you would normally call ace_findf(). Do
not call ace_findf().
The ace_find_ageo_data() searches for the input address in the Address-Level
GeoCensus directory. If it finds a match, it retrieves GeoCensus data from the
directory and records it in the address handle.
If your call to ace_find_ageo_data() is successful, you may retrieve GeoCensus
components by calling ace_get_component(). GeoCensus components are
described in our Quick Reference for Library Products.
Returns Returns ACE_FOUND if the latitude and longitude of the individual address is
found in the Address-Level GeoCensus directory. Otherwise, returns
ACE_NOT_FOUND. Returns ACE_INVALID_HANDLE if the input
ADDR_HANDLE is invalid. Returns ACE_ERROR if an error occurred during
retrieval.

ace_find_cgeo_data()
Synopsis int ace_find_cgeo_data(two parameters);

char* nine_digit_ZIP; Input: ZIP and ZIP+4 without hyphen
Description If your application is intended to perform Centroid GeoCensus processing ONLY,

call ace_find_cgeo_data() where you would normally call ace_findf(). Do not call
ace_findf().
The ace_find_cgeo_data() searches for the input ZIP and ZIP+4 codes in the
Centroid GeoCensus directory. If it finds a match, it retrieves GeoCensus data
from the directory and records it in the address handle.
If your call to ace_find_cgeo_data() is successful, you may retrieve GeoCensus
components by calling ace_get_component().GeoCensus components are
described in our Quick Reference.
Returns Returns ACE_FOUND if the input nine_digit_ZIP was found in the Centroid
GeoCensus directory. Otherwise, returns ACE_NOT_FOUND. Returns
ACE_INVALID_HANDLE if the input ADDR_HANDLE is invalid. Returns
ACE_ERROR if an error occurred during retrieval.

ace_findf()
Synopsis int ace_findf (three parameters);
int suggestion_mode; Input: suggestion list processing (see below)

ACE_SUGGESTIONS_OFF
ACE_SUGGESTIONS_RETURN
int processing_mode; Input: processing indicator (see next page)

ACE_PARSE
ACE_PARSE + ACE_LOOKUP
ACE_CITY_RESOLVED
ACE_ADDRESS_RESOLVED
ACE_RANGE_RESOLVED
ACE_SRANGE_RESOLVED
Description The ace_findf() function searches for the address in the postal databases, assigns
postal codes, and writes the standardized address into the address handle.
Suggestion mode The suggestion_mode flag may be set as follows:
Symbol Description
ACE_SUGGESTIONS_OFF Suggestion lists will not be generated. An address

that would otherwise cause a suggestion list will
instead be unassigned or assigned to a default
level.
ACE_SUGGESTIONS_RETURN Suggestion lists will be generated when an address
or last-line look-up results in a tie condition.
Processing mode Three of the processing_mode flags are to be used only when processing
suggestion lists. See “How to handle suggestion lists” on page 68 for information
about how to use these flags. Also see ace_set_sugg() and ace_set_range().

Symbol Description
ACE_CITY_RESOLVED A last-line suggestion list was generated from a previ-

ous call to ace_findf(). It has been resolved. ACE
should locate the selected suggestion and reprocess
the address.
ACE_ADDRESS_RESOLVED An address suggestion list was generated from a previ-
ous call to ace_findf(). It has been resolved. ACE
should locate the selected suggestion and reprocess
the address.
ACE_RANGE_RESOLVED A range error was generated from a previous call to
ace_findf(). It has been resolved. ACE should locate
the new range and reprocess the address.
ACE_SRANGE_RESOLVED A range error was generated from a previous call to
ace_findf(). It has been resolved. ACE should locate
the new secondary range and reprocess the address.
When you set the processing_mode flag to:
Symbol Description
ACE_PARSE ACE parses only the input address. The returned address is uncor-
rected, and no postal codes are assigned.
If your application requires parsing only, then it will process much
faster if you specify ACE_PARSE. Normally, address parsing takes
less than ten percent of the time required for both parsing and direc-
tory search.
ACE_PARSE + ACE both parses the address and searches for it in the postal data-
ACE_LOOKUP bases.

Returns Returns either the address status, or ACE_ERROR, if an error occurred during
retrieval. Status returns are listed on the facing page. A better method of
diagnosing address problems is to call ace_get_component() for
ACE_ERRORCODE.
Return value Description
ACE_ERROR An error occurred during retrieval.

ACE_INVALID_HANDLE The input ADDR_HANDLE was invalid.
ACE_ABORT Fatal error, perhaps while accessing one of the postal directories. On DOS, this may be
caused by low memory.
ACE_PARSEONLY_MODE Mode conflict: The national directory is not open so lookups are not possible. But
ace_findf() was called in a mode that requires a directory lookup—either with the
ACE_LOOKUP flag or with suggestions enabled.
ACE_FOUND The address was assigned. ACE has standardized the address and populated the output
lines and components.
ACE_NOT_FOUND The address was not assigned. (To find out why not, check the ACE_ERROR_CODE
component.) ACE has standardized the address and populated the output lines and com-
ponents as best it can. The extent of standardization is very modest, and some compo-
nents are blank.
ACE_CITY_NOT_FOUND The address was not assigned. Respond to these return values in the same way that you
ACE_FOUND_LASTLINE respond to ACE_NOT_FOUND.
ACE_MLP_BAD_FORMAT Do not use these return values for address-fault diagnosis. Instead, check the
ACE_MLP_SELECT_CITY ACE_ERROR_CODE component, which is a more accurate and specific indicator.
ACE_NO_SDRS_RANKED
ACE_NO_SDRS_WITHAT_RNG
ACE_SELECT_PDESC
ACE_ZIP_NII_DIR
ACE_FOREIGN The address is foreign (outside the United States, the commonwealth of Puerto Rico, ter-
ritories, possessions)
The address was not assigned but:
ACE_USER_CITY ! A last-line suggestion list was generated.
ACE_USER_ADDRESS ! An address-line suggestion list was generated.
ACE_USER_SECONDARY ! A secondary suggestion list was generated.
ACE_GEOCODEONLY_MODE ACE was initialized only for lookups in the GeoCensus directory. Ordinary ZIP+4 look-
ups are not available.

ace_get_cert_ver()
Synopses char* ace_get_cert_ver(one parameter);
char* cass_version; Output: version string
Description Call ace_get_cert_ver() to retrieve the product name and version number, as they
appear on the CASS certificate (for example, PWACE 7.60.01.J).
Returns This function returns the same buffer pointer that you passed in.

ace_get_component(), ace_get_source()
Synopses char* ace_get_component(four parameters);

int component; Input: component name (see Quick Reference)
int old_new_flag; Input: original or standardized address
ACE_OLD
ACE_NEW
ACE_MVID (Mover ID)
char* comp_data; Output: retrieved data
int ace_get_source(two parameters);

int component; Input: component name
Description Use ace_get_component() to retrieve data components from ACE. Component

symbols are listed and described in the Quick Reference for Libraries.
Before calling ace_get_component(), call ace_get_source() for advice. The
ace_get_source() function returns the “best” source for the component type
passed in: ACE_OLD, ACE_NEW, or ACE_MVID. To retrieve any component
of the original address, set old_new_flag to ACE_OLD; to get a component of the
standardized address, use ACE_NEW. Note that “old” components are not
necessarily raw, unstandardized data. In some cases (such as abbreviation of
Boulevard to Blvd), the “old” version of a component may be partially
standardized.
If you own the Mover ID option, you can retrieve move-updated components by
using ACE_MVID.
If you own the LACSLink option, you can use the ACE_PRELACS flag to obtain
pre-LACSLink components.
The receiving comp_data buffer should be long enough to contain the longest
possible component being retrieved. Rather than use a fixed number of
characters, you may want to use the ACE_MAXFIELD_LEN constant. We have
also defined a length for each component. You can use this when you establish the
receiving comp_data buffer. Use the component name with a *_LEN suffix. The
defined length includes one extra byte for the null terminator.
The length of components retrieved via ace_get_component() is not affected by
lengths set via ace_set_input_length(). ACE does not apply abbreviation to
components.
Returns The ace_get_component() function returns a pointer to a buffer containing the

requested component. If any of the input parameters are invalid, the buffer will be
empty. There is no error indication.
The ace_get_source() function returns ACE_OLD or ACE_NEW, ACE_MVID,
or ACE_INVALID_HANDLE.

ace_get_county_name()
Synopsis char* ace_get_county_name(four parameters);

char* state; Input: state abbreviation
char* county_code; Input: FIPS county code
char* county_buffer; Output: county name
Description The ace_get_county_name() function may be called at any time. It may be used
apart from address processing.
Given a three-digit FIPS county code and two-letter state abbreviation,
ace_get_county_name() returns the full spelling of the county name.
When you allocate the receiving county_buffer, use our symbol
ACE_COUNTYNAME_LEN (which includes one byte for the null terminator).
A list of FIPS codes appears in our Quick Reference.
Returns Returns a pointer to the county_buffer containing the county name. The
county_buffer will be empty if the input address handle, state, or county_code
was invalid.
Note: By default, ACE does not load the county-name table into dynamic
memory. If you intend to retrieve county names, call ace_set_mode() during
initialization.

ace_get_error_info(), ace_get_error_info_return()
Synopses void ace_get_error_info(four parameters);

int *err_code; Output: error number
char *message1; Output: error type message
char *message2; Output: specific error message
int ace_get_error_info_return(three parameters);

char *message1; Output: error type message
char *message2; Output: specific error message
Description When any ACE function returns ACE_ERROR, you can get information about
the error by calling ace_get_error_info(). It produces an integer error number and
two descriptive strings. The first string provides a short error description and the
second provides additional details. The second string is often the name of the file
that was being processed when the error occurred. For example:
Message 1: FILE NOT FOUND
Message 2: Directory file \pw\dirs\zip4us.dir was not found.
As an alternative, ace_get_error_info_return() returns the error code as an integer,
rather than passing back the err_code by setting a variable.
Processing errors are defined in ace.h.
The error codes discussed here are not the address error codes explained in the
ACE User’s Guide.
The buffers receiving message1 and message2 should be large enough to contain
the descriptive strings. Instead of a fixed number of characters, you may wish to
use the constant ACE_ERRMSG_LEN.
Returns There is no return value from ace_get_error_info(). However,

ace_get_error_info_return() returns the error code as an integer. If the input
address handle was invalid, ace_get_error_info_return() returns
ACE_INVALID_HANDLE.

ace_get_file_date()
Synopsis char* ace_get_file_date(three parameters);

int file_ID; Input: file identifier
ACE_DIR_CITY
ACE_DIR_CGEO
ACE_DIR_SUITELINK
ACE_DIR_Z4CHANGE
ACE_DIR_ZCF
ACE_DIR_ZIP4_1
ACE_DIR_ZIP4_2
char* date_string; Output: date directory was generated
Description This function extracts a date from the file and return it as a date_string in the
format mm/yyyy (for example, 06/1998). This is the date that we processed the
file. It is not the file timestamp.
You must call ace_open() before calling ace_get_file_date(). If the directory has
not been opened, the date_string buffer will be blank.
Returns Returns the same pointer to the date_string buffer that you passed in. The
date_string buffer will be empty if either of the input parameters was invalid.

ace_get_lastline()
Synopsis int ace_get_lastline(three parameters);

char* zip; Input: desired ZIP Code
char* lastline; Output: last-line string
Description The ace_get_lastline() function accepts as input a 5-digit ZIP Code and outputs a
complete, valid last line.
When you allocate the lastline buffer, use our ACE_LAST_LINE_LEN symbol.
Returns Returns TRUE if the input ZIP Code was valid; otherwise, returns FALSE.
Returns ACE_INVALID_HANDLE if the input address handle was invalid.

ace_get_lastline_components()
Synopsis int ace_get_lastline_components(four parameters)

ADDR_HANDLE ah; Input: Address handle
char* zip; Input: Desired ZIP Code
char* city; Output: City string
char* state; Output: State string abbreviated
Description The ace_get_lastline_components() function accepts as input a 5-digit ZIP Code

and outputs a valid city and state.
When you allocate the city buffer, use our ACE_CITY_LEN symbol. When you
allocate the state buffer, use our ACE_STATE_LEN symbol.
Returns Returns TRUE if the input ZIP Code was valid; otherwise, returns FALSE.
Returns ACE_INVALID_HANDLE if the input address handle was invalid.

ace_get_lettermatch(), ace_get_simil()
Synopses int ace_get_lettermatch(two parameters);

int ace_get_simil(two parameters);

ACE_PRIM_NAME
ACE_CITY
Description If your address data has been drastically abbreviated or truncated, this can
occasionally cause a bad match to the postal directories. For example:
Input name: Standardized to: Should be:
RIVERCR ST RIVER ST RIVERCREST ST
MILW RD MILL RD MILWAUKEE RD
If you wish, you can detect such errors by calling ace_get_lettermatch() and/or
ace_get_simil(). Run the test after ace_findf() returns, but before writing the
standardized address into the database file. When you detect a possibly incorrect
standardization, you might set aside the addresses so that it can be processed
manually.
Returns The ace_get_lettermatch() function returns TRUE if, and only if, every letter in
the input component also appears in the name ACE assigned. It is not sensitive to
the order of letters. If the return is FALSE, this means that the letters in the input
name do not all appear in the output name.
The ace_get_simil() function returns an integer percentage between 0 and 100.
This provides a relative measure of the similarity of the original name to the
standardized name. The higher the return value, the greater the before-and-after
similarity. It’s up to you to decide what threshold score you will use; we suggest
70 as a starting point. The similarity level takes into account both the character-
by-character likeness of the names and their length. Case (upper or lower) does
not matter; spaces do.
These functions work only on the primary (street) name and city name fields. If
you pass in any other component number, these functions will return
ACE_ERROR. Returns ACE_INVALID_HANDLE if the input address handle
was invalid.

ace_get_line_name(), ace_get_error_desc()
Synopsis char* ace_get_line_name(two parameters);

int line_ID; Input: line number (see list below)
char* line_name; Output: line name
char* ace_get_error_desc(two parameters);

char* error_code; Input: error code number
char* description; Output: short description
Description Both of these functions are convenient for user-interface support or report
writing.
Line names Given a line_ID, ace_get_line_name() produces an English, user-friendly

field name suitable for use in your user interface. For example, given the input
ACE_ICITY, you get “City”. Use the same line-number defines that you use
with ace_set_line(), in “ace_set_line(), ace_get_line()” on page 55.
Line_ID symbols are listed and described in the Quick Reference. You may
retrieve the name of any line, whether or not it was activated through
ace_set_input_length().
Error-code descriptions Given an error-code string, ace_get_error_desc() produces a brief, descriptive

phrase suitable for on-screen display or printing on a report.
Note that we are referring here to address assignment errors, not software faults
or error handling. See the ACE User’s Guide for details about address error codes.
That discussion includes the same brief descriptions that you will get back from
ace_get_error_desc(). Also in the ACE User’s Guide, you can see how we use
these descriptions on the ACE Error Report.
You may retrieve the description of any error code, whether or not that code was
assigned to a particular address.
Returns The ace_get_line_name() function returns the same line_name buffer pointer that
you passed in. The buffer will be empty if the input line_ID was invalid. There is
no specific error indication.
The function returns ACE_INVALID_HANDLE if the input ADDR_HANDLE
was invalid. The ace_get_error_desc() function behaves similarly.

ace_get_offset()
Synopsis int ace_get_offset(four parameters);

int* line; Output: line number (ACE_ILINE1, etc.)

int* column_offset; Output: starting position (zero-based)
Description The ace_get_offset() function can be used to find the position of a component in
an input multiline address. It sets the line and column_offset within that line,
where the specified component was located.
Component defines are those of ace_get_component(). See the list in the Quick
Reference.
Column_offset values are zero-based. For line, use the same defines that you use
for input fields: ACE_ILINE1, ACE_ILINE2, and so on.
If the component was not present in the input address, then both column_offset
and line are set at -1.
Returns Returns ACE_OK if the request could be fulfilled (even if the component was not
present in the input address). Otherwise, returns ACE_ERROR. Returns
ACE_INVALID_HANDLE if the input address handle is invalid.

ace_get_revision()
Synopsis int ace_get_revision(one parameter);
char* version_string; Output: string identifying ACE and

supporting library versions
Description The ace_get_revision() function produces a string that identifies the version of
ACE being used. It also identifies the version numbers of ACE’s underlying
support libraries.
If you call for ACE Library technical support, you may be asked for this string.
When allocating the version_string buffer, use our defined length,
ACE_MAX_REVISION_STR_LEN.
Returns Returns ACE_OK if successful; otherwise, ACE_ERROR.

ace_get_stats()
Synopsis int ace_get_stats(two parameters);

Description To find out how an address component was standardized, call the function
ace_get_stats() with the component symbol. For a complete list of component
values, refer to our Quick Reference.
The return value from this function does not reflect any capitalization changes.
Although ACE_CASE_CHANGED is defined in ace.h, it is never returned.
Returns Returns one of the integers listed at below. Your program could tally these returns
to generate a statistical report.
! ACE_SAME
! ACE_MODIFIED
! ACE_DELETED
! ACE_ADDED

ace_init(), ace_term()
Synopses int ace_init(void);

int ace_term(void);
Description The ace_init() function initializes global data used internally by the ACE system.
The ace_init() call must precede any other ACE library calls.
The ace_term() function releases all memory allocated by the ACE system
functions. This should be your final ACE call.
Returns The ace_init() function returns ACE_OK if ACE was successfully initialized;
otherwise, ACE_ERROR.
The ace_term() function always returns ACE_OK.
Note: These functions are not to be confused with ace_open() and

ace_close(), which are also paired.

ace_init_addr(), ace_term_addr()
Synopses int ace_init_addr(one parameter);
ADDR_HANDLE* ah; Output: address handle
int ace_term_addr(one parameter);
ADDR_HANDLE* ah; Input: address handle
Description The ace_init_addr() function creates and initializes the address handle. The
ace_term_addr() function frees all dynamic memory allocated for the address
handle.
An “address handle” identifies an ACE session. Many ACE functions require the
address handle as an input parameter.
Important: When you allocate your ADDR_HANDLE, use our type-define and
initialize it to NULLP.
Returns Both functions can return ACE_OK, ACE_ERROR, or

ACE_INVALID_HANDLE.
Note: Each call to ace_init_addr() should be paired with a call to

ace_term_addr(). Do not rely on ace_term() to free the address handle(s).
If you use configuration files—see ace_cfg_open()—then you do not need to
call ace_init_addr(). Your address handle will be freed when you call
ace_cfg_close().

ace_ndi(), ace_ndi_file()
Synopses char* ace_ndi(six parameters);

int extended_ASCII; Input: printer supports extended ASCII set?
TRUE
FALSE
char* company_name; Input: your company name (max 40 chars)
char* company_id; Input: NDI certification ID (max 20 chars)
char* list_name; Input: database or mailing list name
int MLNFA_deleted; Input: have MLNFA records been deleted?
TRUE
FALSE
int ace_ndi_file(seven parameters);

char* report_file; Input: path & name of output file
int extended_ASCII; Input: printer supports extended ASCII set?
TRUE
FALSE
char* company_name; Input: your company name (max 40 chars)
char* company_id; Input: NDI certification ID (max 20 chars)
char* list_name; Input: database or mailing list name
int MLNFA_deleted; Input: have MLNFA records been deleted?
TRUE
FALSE
Description The ace_ndi() and ace_ndi_file() functions generate an NDI (National

Deliverability Index) report. For background information about NDI, and a
sample of the report, refer to the ACE User’s Guide.
The ace_ndi() function writes the report into a character array; ace_ndi_file()
writes the report to a file. If you choose ace_ndi_file(), ACE will create, open,
and close the file for you. You simply provide the path and file name.
Parameters Most of the input parameters are obvious, except these:
Parameter Description
extended_ASCII If your printer supports the extended ASCII character set, set TRUE.
ACE will produce smooth lines when it prints the NDI report. If you
set FALSE, dashed lines will be printed within the form.
company_id Pass in the identification number that was assigned to you by the
USPS National Customer Support Center.
list_name Pass in the path and file name of the database you are processing.
ACE will interrogate the timestamp of this file and include the date
on the NDI report.

Parameter Description
MLNFA_deleted MLNFA stands for “Moved Left No Forwarding Address.” When

records are processed through the National Change of Address sys-
tem, some MLNFA records are bound to result. If you’ve deleted all
MLNFA records, set TRUE.
Returns The ace_ndi() function returns a pointer to a character array containing the form.
If for some reason the NDI form could not be built (perhaps because memory for
it could not be allocated), then ace_ndi() returns NULLP.
The ace_ndi_file() function returns ACE_OK if successful. It returns

ACE_ERROR if the file could not be opened and closed, or the report could not
be written. Returns ACE_INVALID_HANDLE if the input address handle was
invalid.
Visual Basic applications should use ace_ndi_file(), not ace_ndi().

ace_open(), ace_close()
Synopses int ace_open(one parameter);
int ace_close(one parameter);
Description During initialization, call ace_open() to open all auxiliary files used by the ACE
system. During termination, call ace_close() to close them.
By default, ace_open() expects to find the supporting files in the current directory.
If the files have been renamed or are located in another directory, you must call
the appropriate “set pathname” functions before ace_open(). ACE does not rely
on operating-system resources such as registries or PATH variables.
Returns Both functions can return ACE_OK, ACE_INVALID_HANDLE, or

ACE_ERROR.
If one of the pathnames set is incorrect, your first call to ace_open() will fail and
return ACE_ERROR. Once you obtain a corrected pathname, follow these steps:
1. Call ace_close(), which closes all the auxiliary files.
2. Call the appropriate “set pathname” functions to reset the pathnames.
Remember to set all the pathnames, not just the one you're changing.
3. Call ace_open() again.
Expired directories If your postal directories have expired, ace_open() will return ACE_ERROR and
you cannot run ACE. Thirty days before your directories expire, ACE will begin
to issue a warning.
Here is how the warning works: ace_open() returns ACE_OK (so you can run),
but the error-handling function is called anyway. The error message obtained
from ace_get_error_info() will explain that the postal directories are within 30
days of expiration.
Note: These functions are not to be confused with ace_init() and ace_term(),
which are also paired.

ace_set_acs_info()
Synopsis int ace_set_acs_info(three parameters);

int option_ID; Input: option identifier (see table)
char* setting; Input: option setting (see table)
Symbol for option_ID Symbols for Description

setting
ACE_ACS_ENABLE “TRUE” Set this to “TRUE” if you want to

“FALSE” (default) produce the address conversion
statistics file.
ACE_ACS_FILE_NAME n/a Enter the path and name of the sta-
tistics file.
ACE_ACS_FILE_TYPE ASCII Enter the file type of the statistics
DBASE3 file.
DELIMITED
EBCDIC
ACE_ACS_INPFILE n/a Enter the name of the input data-
base file. Use of this symbol is
optional.
Description The NCOALink-required customer service log (CSL) contains a record for each
run of address conversion processes, such as NCOALink, LACSLink, ANKLink
and DPV. The USPS requires this information in this single-file format. However,
because of the large file size, it can be difficult to find specific information
contained in the CSL.
You can use ACE to create a statistics file that contains all the same information
that’s in the CSL, plus additional information (such as licensee name, input
database name, and Mover ID “00” matches). Unlike the CSL, the statistics file
contains information about only the last run. You can name the file whatever you
like, choose its format, and easily find information about your most recently
processed data.
When you process a job using an assignment mode of Geo or Parse, ACE
does not produce the USPS address conversion statistics file.
To produce the USPS Address Conversion Statistics file, you must set this
function.
Returns The USPS Address Conversion Statistics file.

ace_set_error_rtn()
Synopsis int ace_set_error_rtn(two parameters);

int (*routine)(ADDR_HANDLE); Input: pointer to handling function
Description Your application program should include a function to handle error returns from
ACE. Use ace_set_error_rtn() to give ACE a pointer to your error-handling
function. ACE will call your function whenever any ACE function returns
ACE_ERROR. Also see the ace_open() page for one other condition in which
your error handler will be called.
ACE will pass one parameter to your exit function: the address handle. Your
function should return an integer (we suggest TRUE), which ACE will ignore.
Your function may, in turn, call ace_get_error_info() to retrieve error information
from ACE. If you would like to see an example of an error-handling function,
examine the source code in addrtest.c.
In multi-threading applications, you should allocate one address handle and
register one error-handling function per thread. Do not re-use a single error-
handling function across multiple threads. When it calls your error handlers, ACE
will not perform the necessary locking to prevent conflict between your
functions.
Returns Returns ACE_OK if the function was successfully registered, or

ACE_INVALID_HANDLE if the input ADDR_HANDLE was invalid.
Synopsis for your int my_error_handler(one parameter);

error handler

ace_set_file(), ace_get_file(), ace_get_z4dirno()
Synopses int ace_set_file(three parameters);

int file_ID; Input: file identifier (list on next page)
char* pathname; Input: pathname
char* ace_get_file(three parameters);

int file_ID; Input: file identifier (list on next page)
char* pathname; Output: pathname
int ace_get_z4dirno(one parameter);

Description By default, ACE expects to find its auxiliary files in the current directory. Call
ace_set_file(), once per file, to register each pathname with ACE.
Make these calls before ace_open(). When you allocate space for pathname
strings, use our PATH_MAX define.
When called with the ACE_PATH_WORKFILES symbol, the pathname should
point to a directory, not an individual file. The ace_set_file() function tests
whether the specified directory exists, and the user has read/write permission. If
not, ACE_ERROR is returned.
As an alternative, you may use the ACE_AUX_CFG_FILE configuration file.
When you call ace_cfg_open() or ace_cfg_read(), pathnames will be registered
from the configuration file.
File_ID symbols File name
ACE_DCT_FIRMLN firmln.dct
ACE_DCT_ADDRLN addrln.dct
ACE_DCT_LASTLN lastln.dct
ACE_DCT_CAP pwcas.dct
ACE_DIR_CITY city**.dir
ACE_DIR_ZCF zcfx.dir
ACE_DIR_ZIP4_1 zip4us.dir
ACE_DIR_ZIP4_2
ACE_DIR_ZIP4_REV_SNDX zip4us.rev
ACE_DIR_ZIP4_SHS zip4us.shs
ACE_DIR_REVZIP4 revzip4.dir
ACE_DIR_CGEO cgeo.dir
ACE_DIR_AGEO ageo*.dir
ACE_DIR_Z4CHANGE z4change.dir
ACE_PATH_WORKFILES
ACE_KEYFILE flprods.key

ACE_DIR_EWS ew*.dir
Enter the path and file name for the EWS directory (c:\pw\dirs\ew*.dir). If you plan
to access the most current directory, type the path and ew*.dir.
Note: You may name the directory file any name you choose. If you use a file
naming format other than the user recommended format, be sure to type the
exact path and file name.
ACE_DIR_ELOT elot.dir
ACE_DIR_DPV Enter the directory path only. For example, type c:\pw\dpv\ for Windows or
/postware/dpv/ for UNIX.
ACE_DIR_RDI Indicates the location of the RDI directories. Enter the directory path only.
ACE_DIR_NCOALINK Enter the path to the NCOALink directory.
ACE_DIR_NAME_PARSING_ Enter the path to the NCOALink or SuitLink supporting files. (NCOALink and
FILES SuiteLink use the same supporting files.)
ACE_DIR_LACSLINK Enter the path to the LACSLink directories.
ACE_DIR_SUITELINK Enter the path to the SuiteLink directory.
ACE_FRM_3553 ace3553.frm
ACE_FRM_NDI acendi.frm
Returns The get function returns a pointer to the pathname string. The set function can
return ACE_OK, ACE_INVALID_HANDLE, or ACE_ERROR. This function
does not test whether the file actually exists at the specified pathname. That test
occurs when you call ace_open().
The ace_get_z4dirno() function returns 1 or 2, the number of ZIP+4 directories
currently in use—that is, registered via ace_set_file().

ace_set_input_length(), ace_get_input_length()
Synopses int ace_set_input_length(three parameters);

int line; Input: line symbol (see Quick Reference)
int max_length; Input: maximum length
int ace_get_input_length(three parameters);

int line; Input: line symbol
int* length; Output: current length
Description Use ace_set_input_length() to set up an input address layout. Call it once for each
ACE input field that you want to use, setting an appropriate max_length. ACE
will make the standardized data fit into this length by abbreviating and/or
truncating as necessary.
When you set max_length, do not add an extra byte for the null terminator. ACE
will take care of that.
To verify that your structure is a valid combination of components, you can call
ace_evaluate_ah(). Refer to the Quick Reference for discussion of the ACE input
fields and appropriate lengths.
If you wish, you may call ace_set_input_length() on fields that you do not intend
to use. Be sure to set a length of zero.
To find out which input fields are currently being used, you may call
ace_get_input_length(). It produces the registered length of one line. Any line
with a length of zero is not being used.
Returns The set function can return ACE_OK, ACE_INVALID_HANDLE, or

ACE_ERROR. An error return can be caused by a shortage of available memory,
because this function allocates memory.
The get function returns the field length if the call was successful; otherwise,
ACE_INVALID_HANDLE or ACE_ERROR.

ace_set_line(), ace_get_line()
Synopses int ace_set_line(three parameters);

int line; Input: line number
char* line_buffer; Input: raw address data
char* ace_get_line(three parameters);

int line; Input: line number
char* line_buffer; Output: standardized address data
Description Call ace_set_line() to load data into one ACE input field. After the call to
ace_findf(), call ace_get_line() to retrieve processed data in the same
arrangement of fields. For details, see “ace_set_line(), ace_get_line()” on
page 55.
Both functions operate on one field at a time, so you should call them inside a
loop. For example, to pass in a multiline address (ACE_ILINE*), call
ace_set_line() up to 12 times.
Refer to the Quick Reference for information about ACE input fields.
Caution: Even if you have no data to load, be sure to clear unused lines by
calling ace_set_line() with the empty string (""). ACE never clears the input lines.
Returns The set function can return ACE_OK, ACE_INVALID_HANDLE, or

ACE_ERROR.
The get function returns the same line_buffer pointer that you passed in. If either
of the input parameters was invalid, this buffer will be empty; there is no specific
error indication.
The get function does not check the size of the receiving buffer. It is your
responsibility to provide adequate space. Generally, your line_buffer should
match the field length that you set when you called ace_set_input_length().
Note: You can set and retrieve only those lines which were activated through
ace_set_input_length(). See “ace_get_line_name(), ace_get_error_desc()”
on page 41 for a comparison of ace_get_line() with ace_get_component().

ace_set_mode(), ace_get_mode()
Synopses int ace_set_mode(three parameters);

int mode_ID; Input: mode identifier (see table)
int mode; Input: desired mode
TRUE
FALSE
int ace_get_mode(three parameters);

int mode_ID; Input: mode identifier (see table)
int* mode; Output: current mode
Description Call ace_set_mode() to control which files ace_open() will open. Make any
ace_set_mode() calls before you call ace_open(); otherwise your settings will
have no effect. As an alternative, you may use the ACE_AUX_CFG_FILE
configuration file. When you call ace_cfg_open() or ace_cfg_read(), mode
settings will be registered from the configuration file.
Call ace_get_mode() to get the currently registered modes.
Returns Returns ACE_OK, ACE_INVALID_HANDLE, or ACE_ERROR.
Symbol for mode_ID Default mode Description

identifier
ACE_MODE_CASS_SELF_CERT FALSE Indicates that the job is for CASS self-certification.

ACE_MODE_GEO ACE_NONE_ You must call ace_set_mode() to set the GeoCensus mode that
GEO you want.
If you intend to use the Centroid option, set
ACE_CENTROID_GEO. To perform GeoCensus assignment at
the individual address level, set ACE_ADDRESS_GEO. To
attempt Address-Level first and use Centroid as a if there is no
address-level information, set ACE_BEST_GEO. To perform both
Address-Level and Centroid, set ACE_ALL_GEO.
ACE_MODE_GEO_ONLY FALSE If your application is intended to perform GeoCensus processing
ONLY, set TRUE. When you call ace_open(), ACE will open only
the appropriate GeoCensus file(s). ACE will not open the ZIP+4
directory or other auxiliary files. This conserves a lot of system
resources. It may also increase throughput, because in this mode,
ACE performs only a minimum of address parsing. However, it
also means that in GeoCensus-only mode, ACE does not support
postal coding or standardization. You may process records by call-
ing ace_find_geo_data(), but any call to ace_findf() will fail.
If you intend to perform normal ACE processing and GeoCensus
assignment in a single pass, set FALSE.

identifier
ACE_MODE_AL_SHOW_ONLY FALSE These modes were developed to reduce the system demands of our
ACE_MODE_LL_SHOW_ONLY Show utility and other programs for directory queries
! If your application is intended only to retrieve ZIP+4 records—
and not to assign addresses or perform last-line queries—set
AL_MODE_ONLY to TRUE. Then ace_open() will open only
the ZIP+4 directory and the address-line parsing dictionary.
! If your application is meant to only retrieve City/ZCF
records—and not to assign addresses or perform address-line
queries—set LL_MODE_ONLY to TRUE. Then ace_open()
will open only the City and ZCF directories and the last-line
parsing dictionary.
If your application will make both ZIP+4 and City/ZCF queries,
you need to open all the files. So set FALSE for both modes.
To restore normal ACE processing, you must close the auxiliary
files, change your mode settings, and reopen the files.
ACE_MODE_ENABLE_Z4CHANGE FALSE If your application is intended to perform Z4Change processing,
set TRUE. When you call ace_open(), ACE will open the
Z4Change file, as well as all the other auxiliary files.
Note: ACE does not support a “Z4Change Only” mode. We
expect that most ACE applications will be designed to perform
Z4Change and normal ZIP+4 assignment in one pass. You may
perform Z4Change processing without ZIP+4 assignment—just
don’t make any ace_findf() calls. But ace_open() still will open all
auxiliary files, including the national ZIP+4 directory.
ACE_MODE_PARSE_ONLY FALSE Parse-only mode is provided for applications that require address
parsing but not directory lookup or address standardization. An
example would be a record-matching application that needs to
parse addresses in order to compare addresses on individual com-
ponents.
The purpose of parse-only mode is to reduce the resource demands
of ACE, by eliminating the need to open the national ZIP+4 direc-
tory. Set parse-only mode TRUE before calling ace_open(). When
you call ace_findf(), remember to use the ACE_PARSE flag, but
do not use the ACE_LOOKUP flag.
ACE_MODE_DIR_EXPIR_WARN TRUE By default, 30 days before directory expiration, ACE begins to
produce a warning message—see the ace_open() page for details.
Some users find that this warning causes unnecessary support
calls. To suppress it, set the warning mode FALSE. Be aware, an
end user might run into a problem if directories expire without
warning.
Note: There is a fundamental incompatibility between setting the
expiration-warning mode—that is, setting it either way, on or
off—and registering your own error-handling function. If you
have registered your own error handler, then call ace_set_mode()
with the ACE_MODE_DIR_EXPIR_WARN symbol, then
ace_set_mode() will return ACE_ERROR.

identifier
ACE_MODE_NON_CASS FALSE The non-CASS mode enables non-mailing users to process

addresses using expired directories.
When this option is set to TRUE, the USPS 3553 report is auto-
matically disabled. If you decide to reset this option to FALSE,
you may receive a message stating that the directories are out of
date and the USPS report is disabled.
ACE_MODE_ENABLE_EWS FALSE Early Warning System (EWS) detects delivery points that are
not yet listed in the current ZIP+4 directories.
To enable EWS processing, set this option to TRUE. To dis-
able EWS processing, set this option to FALSE.
ACE_MODE_ENABLE_ELOT TRUE To disable eLOT processing, set this option to FALSE.
ACE_MODE_ENABLE_DPV TRUE To disable DPV processing, set this option to FALSE.
ACE_MODE_ENABLE_REVERSE_ TRUE Set to FALSE to disable the reverse soundex look-ups through the
SOUNDEX library.
ACE_MODE_CACHE_DPV_ FALSE Set this option to TRUE to enable DPV directory caching.
DIRS Set this option to FALSE to disable DPV directory caching.
ACE_MODE_ABORT_ON_CACHE_ FALSE If you’re caching the LACSLink directories, you must specify
ERROR whether or not you want to stop processing if insufficient memory
is available.
Set this option to FALSE if you want to continue LACSLink pro-
cessing without caching. Set this option to TRUE to discontinue
processing.
When this option is set to TRUE and there is not enough system
memory available to load the LACSLink directories, the function
call ace_open() will fail.
Note: This option has no effect unless
ACE_MODE_CACHE_LACSLINK_DIRS is set to TRUE.
ACE_MODE_ABORT_ON_DPV_ TRUE Set this option to FALSE if you want to continue DPV processing
CACHE_ERROR without caching. Set this option to TRUE to discontinue process-
ing.
When this option is set to TRUE and there is not enough system
memory available to load the DPV directories, the function call
ace_open() will fail.
ACE_MODE_CACHE_DPV_DIRS is set to TRUE.
ACE_MODE_ENABLE_MOVER_ID ACE_MID_OFF To enable NCOALink processing, set this option to
ACE_MID_NCOALINK. To disable NCOALink processing, set
this option to ACE_MID_OFF (the default setting). For details
about Mover ID, see “ace_mvid_set_info()” on page 122 and the
Mover ID User’s Guide for
NCOALink.
ACE_MODE_ENABLE_RDI FALSE The Residential Delivery Indicator (RDI) lets you determine if a
given address is for a residence or not. For more information about
RDI processing, see “What is RDI?” on page 118.
To enable RDI processing, set this option to TRUE. To disable
RDI processing, set this option to FALSE.

identifier
ACE_MODE_CACHE_RDI_DIRS FALSE Set this option to TRUE to enable RDI directory caching.
Set this option to FALSE to disable RDI directory caching.
ACE_MODE_ENABLE_LACSLINK TRUE To enable LACSLink processing, set this option to TRUE. To dis-
able LACSLink processing, set this option to FALSE. For details
about LACSLink, see “What is LACSLink?” on page 141.
ACE_MODE_CACHE_LACSLINK_ FALSE Set this option to TRUE to enable LACSLink directory caching.
DIRS Set this option to FALSE to disable LACSLink directory caching.
ACE_MODE_CACHE_ZIP_ORDER FALSE By default, this is set to random order processing (FALSE).
To improve NCOALink processing speed when your input data is
in ZIP Code order, set this mode to TRUE.
When you cache in ZIP order, one or more segments of NCOALink
data are cached on your computer. A segment of data is tempo-
rarily saved in the computer’s RAM until that segment of data has
been processed. Then the next segment is loaded into RAM and
the previous segment is removed from RAM.
Cache in ZIP order only when processing your data in ZIP Code
order. Turning this option on when processing data that is not in
ZIP Code order will slow performance.
When you cache in ZIP order, you’ll see the greatest speed
improvements in the following situations:
! Your data is concentrated geographically. For example, a
100,000-record file that contains only Wisconsin addresses is
processed much faster than a 100,000-record file that contains
addresses for all 50 states.
! Your data file is large. The speed improves in proportion to the
size of the data file.
Caching in ZIP order doesn’t improve speed in every situation.
Take some time to analyze how it affects your processing speeds.
ACE_MODE_ENABLE_ FALSE To enable SuiteLink processing, set this option to TRUE.
SUITELINK To disable SuiteLink processing, set this option to FALSE.
ACE_MODE_CACHE_ FALSE If you cache the SuiteLInk directories, you must specify if you
SUITELINK_DIRS want to stop processing if insufficient memory is available.
! Set this option to FALSE to continue SuiteLink processing
without caching.
! Set this option to TRUE to discontinue processing. When this
option is set to TRUE and there is not enough system memory
available to load the SuiteLink directories, the function
callace_open() will fail.
ACE_MODE_CACHE_SUITELINK_DIRS is set to TRUE.
ACE_MODE_ABORT_ON_CACHE_ TRUE Set this option to FALSE if you want to continue processing with-
ERROR out caching. Set this option to TRUE to discontinue processing, if
there is not enough system memory available to load the directo-
ries.
Note: This option has no effect on RDI directories caching unless
ACE_MODE_CACHE_RDI_DIRS is set to TRUE.

ace_set_option(), ace_get_option()
Synopses int ace_set_option(three parameters);

int setting; Input: option setting (see table)
int ace_get_option(three parameters);

int* setting; Input: option setting (see table)
Description By default, ACE standardizes addresses in a style fully conforming to the CASS
testing regulations of the U.S. Postal Service.
You are not required to process your own data in CASS-conforming style. If you
wish, you may call ace_set_option() as necessary to set stylistic options of your
choosing.
CASS rules and the stylistic options are fully explained in the ACE User’s Guide.
As an alternative, you may use the ACE_OPTS_CFG_FILE configuration file.
When you call ace_cfg_open() or ace_cfg_read(), options settings will be
registered from the configuration file.
Call ace_get_option() to get the currently registered setting.
See the list of symbols below.
To assign properly according to the USPS requirements, leave

ACE_OPT_MULTI_PRESERVE_DUAL_ORDER set to FALSE. If its set
to TRUE, ACE allows the deliverable address to not be directly above the
last line. USPS requires the deliverable address to be just above the last line.
Symbol for option_ID Symbols for setting Default setting
ACE_OPT_ALIAS ACE_CONVERT_ALIAS ACE_CONVERT_ALIAS

ACE_PRESERVE_ALIAS
ACE_OPT_APPEND_PMB TRUE FALSE
FALSE
ACE_OPT_ASSIGN_CITY_BY_INPUT_LLIDX TRUE TRUE
FALSE
ACE_OPT_CAPITALIZATION ACE_UPPERCASE ACE_UPPERCASE
ACE_MIXEDCASE
ACE_LOWERCASE
ACE_OPT_DIR_STYLE ACE_STYLE_SHORT ACE_STYLE_SHORT
ACE_STYLE_LONG
ACE_STYLE_PRESERVE

ACE_OPT_DUAL_TYPE ACE_DUAL_POSITION ACE_DUAL_POSITION

ACE_DUAL_MAILING
ACE_DUAL_STREET
ACE_OPT_EXTRA_DATA ACE_LOOSE ACE_STRICT
ACE_STRICT
ACE_OPT_MULTI_COMBINE_AL TRUE TRUE
ACE_OPT_MULTI_COMBINE_LL FALSE
ACE_OPT_MULTI_PRESERVE_DUAL_ORDER TRUE FALSE
FALSE
ACE_OPT_MULTI_SWAP ACE_SWAP_TOP ACE_SWAP_NONE
ACE_SWAP_BOTTOM
ACE_SWAP_NONE
ACE_OPT_MULTI_UPDATE_ZIP ACE_UPDATE ACE_UPDATE
ACE_DONT_UPDATE
ACE_ERASE_THEN_UPD
ATE
ACE_OPT_MULTI_UPDATE_ZIP4 ACE_UPDATE ACE_ERASE_THEN_UPDATE
ACE_DONT_UPDATE
ACE_ERASE_THEN_UPD
ATE
ACE_OPT_NON_CASS_ACCEPT_INP_ZIP4 TRUE FALSE
FALSE
ACE_OPT_NON_CASS_INEXACT_ZIPMOVE TRUE FALSE
FALSE
ACE_OPT_PLACENAME ACE_CONVERT_PLACEN ACE_CONVERT_PLACENAME
AME
ACE_PRESERVE_PLACE
NAME
ACE_OPT_POUND_TO_SEC_ADDR TRUE FALSE
FALSE
ACE_OPT_STND_ADDR_LINE TRUE TRUE
ACE_OPT_STND_LAST_LINE FALSE
ACE_OPT_STND_CITY_ABBR TRUE FALSE
FALSE
ACE_OPT_STND_STREET_ABBR TRUE FALSE
FALSE
ACE_OPT_STND_UNASSIGNED_ TRUE FALSE
ADDR FALSE
ACE_OPT_SFX_STYLE ACE_STYLE_SHORT ACE_STYLE_SHORT
ACE_STYLE_LONG
ACE_STYLE_PRESERVE
ACE_OPT_UNIT_DESIG ACE_UNIT_PRESERVE ACE_UNIT_DIRECTORY
ACE_UNIT_DIRECTORY

ACE_OPT_NON_CASS_ FALSE If you choose not to process with

ZIP4_NON_DPV_CONFIRM DPV, but you want ZIP+4 informa-
tion, set the option to True.
With a preferred alias, the conversion is from the base record to the preferred
alias. With a non-preferred alias, the conversion is from the non-preferred alias to
the base record.
Secondary Match Use the following output components for the ACE_GET_COMPONENT
option function when you use the Accept Input ZIP+4 if Secondary Match option:
Library symbol Description
ACE_CASS_MATCH Use this field to indicate the non-CASS option that was
used in making the assignment.
0 The non-CASS option was not chosen (the job was run
using CASS rules) or the Enable non-CASS Features
option was not enabled.
1 Inexact ZIP move assignment.
2 Input ZIP+4 assignment.
ACE_NC_FIRM The firm match that was made using the input ZIP+4 for
missing or invalid firm information.
ACE_NC_UNIT The unit designator match that was made using the input
ZIP+4 for missing or invalid unit designator information.
ACE_NC_SRANGE The secondary range match that was made using the input
ZIP+4 for missing or invalid secondary range information.
ACE_NC_SECADDR The secondary address match that was made using the input
ZIP+4 for missing or invalid secondary address informa-
tion.

ace_set_password()
Synopsis int ace_set_password(two parameters);

char* password; Input: password
Description The ace_set_password() function may be called by users who have received a
password from customer support. To get the password, you must apply for, and
receive, an exemption from the USPS rule on directory expiration.
Call ace_set_password() before calling ace_open().
If you call ace_set_password() with a valid password, ACE will skip the usual
directory-date checking.
Whether your directories are current or expired, ACE runs in a mode that is not
CASS certified. Therefore ACE does not generate the CASS Report (USPS Form
3553). Subsequent calls to ace3553() or ace3553_file() will not fail, but the
resulting buffer or file will be empty. In other respects, ACE will behave
normally, including calls to ace_get_cert_ver().
If you do not call ace_set_password() at all, ACE will check directory dates as
usual. If your directories are expired, ace_open() will fail.
Be sure to spell the password correctly. Passwords are case-sensitive. If you call
ace_set_password() with an invalid password, and your directories are expired,
there is no specific error indication. The call to ace_open() will not fail. Instead,
ACE will partially disable itself. It will perform at a fraction of its normal pace,
and it will not accept multiline input. If you attempt to configure for multiline
input, ace_evaluate_ah() will report an error.

ace_set_z4c_check_date()
Synopsis int ace_set_z4c_check_date(three parameters);

int month; Input: month of last ZIP+4 coding
int year; Input: year of last ZIP+4 coding
Description Call ace_set_z4c_check_date() with the month and year that the input records
were most recently ZIP+4 coded (either through a full ACE process or a previous
Z4Change pass). ACE will verify that your date is within the 12-month period
covered by the current Z4Change file.
When you call ace_z4_zip4_changed(), ACE will flag only those addresses that
are affected by a ZIP or ZIP+4 change that occurred after the date you set here.
The input year parameter must be a four-digit year. If you pass in a two-digit year,
the check-date will not be set, and you will get the return value
ACE_Z4C_INVALID_DATE. This is required for Year 2000 compliance.
Returns Returns ACE_OK if the check date was successfully set—that is, if the check
date is within the 12-month period covered by the current Z4Change file.
Otherwise, returns one of the error indications below. The error handler is not
invoked. Returns ACE_INVALID_HANDLE if the input address handle is
invalid.
Symbol Description
ACE_Z4C_INVALID_DATE The input date was bad; for example, month = 13, or the
year was less than four significant digits.
ACE_Z4C_NEWER_DATE The check date is more recent than the Z4Change direc-
tory—in other words, the directory is too old to cover
the check date. The solution is to install a more recent
Z4C directory.
ACE_Z4C_DATE_DIST The Z4Change directory is more recent than the check
date—in other words, the directory doesn't cover far
enough back in time to cover the check date. The solu-
tion is to run a regular ACE process.

ace_z4_zip4_changed()
Synopsis int ace_z4_zip4_changed(two parameters);

char* zip_zip4_string Input: 9-digit ZIP
Description The only parameter is a pointer to a character buffer containing the ZIP and
ZIP+4 code to be checked. In this buffer, ACE will expect to find a nine-digit
number without hyphen.
Returns
Symbol Description
ACE_Z4C_NO_CHECK_DATE Z4Change was not properly initialized. Check

return values from Z4Change initialization func-
tions to make sure it is properly initialized.
ACE_INVALID_HANDLE The input address handle is invalid.
ACE_Z4C_CHANGED This ZIP+4 code is affected by a change. That
change might be in the ZIP Code, ZIP+4, CART, or
in the form of standardization. Put this record
through the normal ZIP+4 assignment process, with
the usual call to ace_findf(). The Z4Change func-
tions will not assign the new postal codes.
ACE_Z4C_INVALID_ZIP The input ZIP Code (first five digits of nine-digit
ZIP+4) is not valid: Either it was empty, it included
non-numeric characters, or it was not found in the
Z4Change directory.
ACE_Z4C_INVALID_ZIP4 The input ZIP4 code (last four digits of nine-digit
ZIP+4) is not valid: Either it was empty, or it
included non-numeric characters.
ACE_Z4C_NOTCHANGED This ZIP+4 code has not been affected by any
changes in the past 12 months. No further process-
ing of this record is necessary.

Chapter 3:
Suggestion lists
This chapter explains how your application may process suggestion lists. For
background information about suggestion lists, refer to the ACE User’s Guide.
Chapter 3: Suggestion lists 67

How to handle suggestion lists
Set up suggestion list The process is as follows:

processing
1. Call ace_set_sugg_option() set up suggestion list options.
2. Call ace_set_sugg_filter() to make the address suggestion lists more focused.
3. Call ace_findf() with the ACE_SUGGESTIONS_RETURN flag. If address
processing results in a suggestion list, ace_findf() exits, returning a special
code (ACE_USER_CITY, ACE_USER_ADDRESS, or
ACE_USER_SECONDARY). You detect this return code and step in to
process the suggestion list.
Your next step depends on the return from ace_findf().
If ace_findf() returns 1. Retrieve the list from ACE. First, call ace_get_suggno() to get the number of
ACE_USER_ADDRESS suggestions available. For an address suggestion list, call either
ace_get_sugg() or ace_get_sugg_cmpt() to retrieve suggestion text.
2. Display the suggestion list to the user. The user may choose one suggestion,
or either reject the list, and abandon the assignment. Capture the user’s
choice, and pass it to ACE by calling ace_set_sugg(). Pass either a suggestion
number or, to indicate rejection, pass -1. ace_set_sugg() will return
ACE_OK, ACE_USER_RANGE, ACE_INVALID_HANDLE, or
ACE_ERROR.
The user might choose an address suggestion that does not match the primary
range of the input record. For example, suppose the input address is 3310
Main, and the suggestion list shows Main extends only to the 800 block. The
user might decide that the first digit of the input range typed twice, and the
true range should be 310. So the user selects the address suggestion 300-399
Main. In this case, ace_set_sugg() would return ACE_USER_RANGE.
Your next step depends on the return from ace_set_sugg():
Return Your next step
ACE_USER_RANGE Prompt the user to enter a new range. Then call

ace_set_range() to pass the user’s range into ACE.
ace_set_range() will return either ACE_OK,
ACE_INVALID_HANDLE, ACE_INVALID_RANGE, or
ACE_ERROR.
! If ace_set_range() returns ACE_INVALID_RANGE, con-
tinue to prompt the user to enter a new range. Then call
ace_set_range() to pass the user’s range into ACE. Con-
tinue to loop through until the user enters a valid range for
the suggestion list selection
! If ace_set_range() returns ACE_OK, call ace_findf() a sec-
ond time, with a flag that a new range has been set
(ACE_RANGE_RESOLVED). Then ace_findf() attempts
assignment based on the new range.
ACE_OK Call ace_findf() a second time, with the flag
ACE_ADDRESS_RESOLVED. Then ace_findf() attempts
assignment based on the suggestion list selection.

ACE_USER_SECONDARY suggestions available. For a secondary suggestion list, call ace_get_sugg().
2. Display the suggestion list to the user. The user may choose one suggestion
or reject the list and abandon the assignment. Capture the user’s choice, and
pass it to ACE by calling ace_set_sugg(). Pass either a suggestion number or,
to indicate rejection, pass -1. ace_set_sugg() will return ACE_OK,
ACE_USER_SRANGE, ACE_INVALID_HANDLE, or ACE_ERROR.
The user might choose a secondary range or firm suggestion that does not
match the input secondary range or firm. For example, suppose the input
secondary range was APT 110, and the suggestion list shows a secondary
between 1 and 10. The user might decide that the first digit of the input
secondary range was typed twice, and the true range should be 10. So the
user selects the address suggestion APT 1 - 10. In this case, ace_set_sugg()
would return ACE_USER_SRANGE.
Your next step will depend on the return from ace_set_sugg():
Return Your next step
ACE_USER_SRANGE Prompt the user to enter a new secondary range. Then call
ace_set_range() to pass the user’s range into ACE.
ace_set_range() will return either ACE_OK,
ACE_INVALID_HANDLE, ACE_INVALID_SRANGE, or
ACE_ERROR.
! If ace_set_range() returns ACE_INVALID_SRANGE,
continue to prompt the user to enter a new secondary
range. Then call ace_set_range() to pass the user’s range
into ACE. Continue to loop through until the user enters a
valid secondary range for the suggestion list selection.
! If ace_set_range() returns ACE_OK, call ace_findf() a sec-
ond time, with a flag that a new secondary range has been
set (ACE_SRANGE_RESOLVED). Then ace_findf()
attempts assignment based on the new range.
ACE_OK Call ace_findf() a second time, with the flag
ACE_SRANGE_RESOLVED. Then ace_findf() attempts
assignment based on the suggestion list selection.
ACE_USER_CITY suggestions available. Then if it’s a city suggestion list, call ace_get_sugg() to
retrieve suggestion text.
2. Display the suggestion list to the user. The user may choose one suggestion
or reject the list and abandon the assignment. Capture the user’s choice, and
pass it to ACE by calling ace_set_sugg(). Pass either a suggestion number or,
to indicate rejection, pass -1. ace_set_sugg() will return ACE_OK,
ACE_INVALID_HANDLE, or ACE_ERROR.
3. When ace_set_sugg() returns ACE_OK, call ace_findf() a second time, with
the flag (ACE_CITY_RESOLVED). Then ace_findf() attempts assignment
based on the suggestion list selection.

CASS rule The USPS does not permit us to generate a 3553 form when suggestion lists are
used in address assignment. The USPS suspects that users may be tempted to
guess. Misrouted mail is expensive for the USPS to handle.
Therefore, if you process even one address with suggestions turned on, ACE will
prevent generation of the 3553 form. This is true whether or not a suggestion list
is actually generated or used.

ace_get_sugg()
Synopsis int ace_get_sugg(three parameters);

int sugg_num; Input: suggestion number (zero-based)
char* sugg_buffer; Output: suggestion string
Description The ace_get_sugg() function returns one suggestion string at a time. Call it from
inside a loop.
The sugg_num argument may range from zero to the number of suggestions
available, minus one. You can get that number from ace_get_suggno().
Make sure that your receiving sugg_buffer is long enough. Each suggestion is a
variable-length string delimited by vertical bars (|). Of course, when you display
suggestions to the user, you will probably want to align fields in orderly columns,
so your display may be wider than the ACE suggestion string.
Last-line suggestions Last-line suggestions are up to 39 characters long,

including the NULL terminator.
Address-line suggestions Address suggestions are up to 70 characters long, including the NULL.
In most address suggestions, the low-range and high-range numbers each occupy
10 bytes and are left-padded with spaces. With one space in between, that’s a total
of 21 bytes.
Secondary suggestions Secondary and firm suggestions are up to 75 characters.

Format example:
Returns Returns ACE_OK if successful. Returns ACE_ERROR if an error occurred while

retrieving the suggestion, or if the input sugg_num was out of the valid range

(e.g., greater than the number of suggestions available.) Returns
ACE_INVALID_HANDLE if the input address handle is invalid.
Note: You can find the number of suggestions available by calling

ace_get_suggno(). As an alternative to ace_get_sugg(), you may retrieve
components—rather than delimited strings—by calling
ace_get_sugg_cmpt().

ace_get_sugg_cmpt()
Synopsis char* ace_get_sugg_cmpt(four parameters);

int sugg_num; Input: suggestion number
int component; Input: component to be retrieved; for
defines,see “ace_get_query()” on page 85
char* cmpt_buffer; Output: retrieved component
Description The ace_get_sugg_cmpt() function retrieves one Component symbols

component of one address-line, city, or secondary
ACEQ_RECTYPE
suggestion. Call it inside a nested loop—the inner loop ACEQ_ODDEVEN
on component, the outer loop on sugg_num. You can ACEQ_SODDEVEN
ACEQ_SNAME
obtain the maximum value of sugg_num by calling ACEQ_UNIT
ace_get_suggno().
ACEQ_LLINDEX
ACEQ_URB_INDEX
For the component parameter, be sure to use the field
names of ace_get_query(). Remember, you are ACEQ_LOWRANGE
ACEQ_HIGHRANGE
retrieving data from a ZIP+4 directory record, not the ACEQ_PREDIR
ACEQ_PNAME
components of a particular address. Do not use the field ACEQ_POSTDIR
names of ace_get_component(). ACEQ_SUFFIX
ACEQ_SNAME
ACEQ_UNIT
For last-line suggestions, only the following ACEQ_LOWSRANGE
components are valid: ACE_LLQ_CITYNAME, ACEQ_HIGHSRANGE
ACEQ_ZIP
ACE_LLQ_ZIP, and ACE_LLQ_STATE. ACEQ_ZIP4EVEN
ACEQ_ZIP4ODD
ACEQ_CARTEVEN
ACEQ_CARTODD
ACEQ_ALSTYP
ACEQ_LACSIND
ACEQ_ZIP_MOVE
ACEQ_CONGRESS
ACEQ_COUNTY
ACEQ_ALTERNATE
ACE_LLQ_CITYNAME
ACE_LLQ_ZIP
ACE_LLQ_STATE
Returns Returns a pointer to the cmpt_buffer containing the retrieved component.
Note: As an alternative to ace_get_sugg_cmpt(), you may retrieve an entire

suggestion—as one delimited string—by calling ace_get_sugg().

ace_get_suggno()
Synopsis int ace_get_suggno(one parameter);

Description Call ace_get_suggno() to determine the number of suggestions on the current list.
We use this function to control looping through suggestions. You might call it
before drawing a suggestion list window to determine how large to make the
window.
Returns Returns the number of suggestions in the current suggestion list.
Note: Call ace_get_suggno() before calling ace_set_sugg() or

ace_get_sugg_cmpt().

ace_set_range()
Synopses int ace_set_range(three parameters);

range_type Input: Type of range:
ACE_PRIM_RANGE (primary)
ACE_SEC_RANGE (secondary)
char* range; Input: new range
Description This function comes into play when a user is viewing an address suggestion list.
The user may choose a suggestion that does not match the primary or secondary
range of the input record. If the user can enter a new, correct range, then ACE can
assign the address.
In this situation, ACE needs the user to set a new primary or secondary range that
falls within the range of the chosen suggestion. This function provides a way for
the user to set a new range.
If your call to ace_set_sugg() returns ACE_USER_RANGE, prompt the user to
enter a new range. Call ace_set_range() to pass the user's range into ACE, then
call ace_findf(). See “How to handle suggestion lists” on page 68 to see how to
use ace_set_range() in context.
Returns Returns ACE_OK, ACE_INVALID_HANDLE, ACE_INVALID_RANGE,

ACE_INVALID_SRANGE, or ACE_ERROR.

ace_set_sugg()
Synopsis int ace_set_sugg(three parameters);

int sugg_num; Input: suggestion number
int sugg_list_type; Input: type of suggestion list being resolved
ACE_USER_ADDRESS
ACE_USER_CITY
ACE_USER_SECONDARY
Description Call the ace_set_sugg() function to select a particular suggestion line from an
array of suggestions produced by ace_findf().
Note: If the suggestion number that you set is negative or greater than the list size,
then ACE will assume that the suggestion list was rejected. The address will not
be assigned.
The function ace_set_sugg() returns whether or not the user needs to input a
primary or secondary range. A range is required if the input range is invalid. A
secondary range is required if the input secondary range is missing or invalid and
a secondary match is available.
Returns Returns ACE_OK, ACE_USER_RANGE, ACE_USER_SRANGE,

ACE_INVALID_HANDLE, or ACE_ERROR. Returns ACE_ERROR when the
suggestion number is greater than the total number on the list.

How to customize suggestion lists
ACE offers several options for customizing suggestion lists. These options affect
only the style of suggestion lists, not procedures for handling suggestions.
If you decide to call the customizing functions, you will probably make those
calls during initialization, before the first ace_findf() call. However, you may
change suggestion modes at any time. Your new choices will take effect upon the
next ace_findf() call.
Consolidate ranges Address suggestions are ZIP+4 directory records that 100 - 199 Main St
111 - 117 Main St
ACE has called potential matches for the input 200 - 299 Main St
address. Normally, each ZIP+4 directory record is 300 - 399 Main St
100 - 199 Main St Ext
returned as a separate suggestion. 231 - 233 Main St Ext
For example, given the input data 114 Main, ACE
might produce the suggestions shown at right.
If you wish, ACE can consolidate these suggestions. The result is a more compact
list that is easier and faster for you to display, and perhaps easier for your end
users to grasp. The function to call is ace_set_sugg_option(), which offers two
styles of consolidation. The two styles differ in their treatment of primary ranges:
Ignore gaps ACE ignores gaps and overlaps in primary ranges, so 100 - 399 Main St
consolidation is more aggressive. The above suggestion 100 - 235 Main St Ext
list would be compressed as shown here.
Respect gaps ACE preserves gaps in primary ranges, but overlapping 100 - 399 Main St
ranges are consolidated. The above suggestion list would 100 - 199 Main St Ext
be compressed as shown here. 235 - 235 Main St Ext
Some details to know When ACE consolidates, it produces only one suggestion for each unique
combination of predirectional, primary name, postdirectional, suffix, and ZIP.
The ZIP4, CART, and county-code fields are ignored and they are not available
for browsing. (By definition, a consolidated suggestion covers two or more ZIP+4
records.) However, once a user selects a suggestion, normal assignment can
proceed.
Adjust simil level A simil score is a number between zero and 100; the higher the number, the
greater the similarity between two strings. ACE uses simil scores when
comparing input street names with streets in the ZIP+4 directory. The same is true
when ACE compares an input city name with cities in the City directory.
During the normal assignment process, ACE requires a simil score in the upper
70s to determine a match. A looser standard applies when generating suggestion
lists; a simil score of 60 or higher is close enough to earn a directory record a
place on the suggestion list.
You can raise or lower the threshold simil score for suggestions lists. The function
accepts one threshold, which will be applied both to address and last-line
suggestions. If you raise the threshold, expect shorter suggestion lists, and vice
versa.

Filter by primary Another way to shorten address suggestion lists is to filter them by primary range.
range This approach is different from simply consolidating ranges. ACE offers two
ways to filter suggestions by range:
Range match The first approach is an on/off switch. If you turn it on, 100 - 117 Main St
ACE will return only those suggestions that match the 100 - 199 Main St Ext
input primary range.
Range window The other approach is a little more liberal. You set a span around the input
range—in effect, limiting suggestions to an area a few blocks on either side of the
input address.
The example at right shows the suggestions we would 100 - 199 Main St
get with window set at 200 (100 on each side of the input 111-117 Main St
200 - 299 Main St
range). Again, the effect is to limit suggestions to one 100 - 199 Main St Ext
block on either side of the primary range that was input
(114).
ACE includes in the suggestion list any ZIP+4 record whose range completely or
partially overlaps your window. Note that the window covers both sides of the
input primary range. For example, if you want to limit suggestions to one block
on either side of the input address, set a range window of 200. To see suggestions
within two blocks on either side, set a range window of 400, and so on.
Filter by query You can filter address suggestions more generally. This method may be useful in
situations where you know something more about your addresses than is stored in
your records. For example, if you know in which county your addresses lie, you
could limit suggestions by county code.
The mechanism for creating filters is the same ACE_QUERY structure that you
may have used to query the ZIP+4 directory (as described in Appendix B). Then
you attach the ACE_QUERY structure to the suggestion-building process by
calling ace_set_sugg_filter(). Not all ACE_QUERY fields are available; see the
ace_set_sugg_filter() page for details.

ace_set_sugg_filter()
Synopses #include <aceshow.h>

int ace_set_sugg_filter(two parameters);
from ace_init_addr()
ACE_QUERY_HANDLE aq;Input: ZIP+4 query structure
from ace_set_query()
Description To make address suggestion lists more focused, you can filter suggestions. The
mechanism for creating filters is the same ACE_QUERY structure that is used to
query the ZIP+4 directory (as described in Appendix B).
Filters are managed using the same functions as in ZIP+4 queries. We suggest
that you make the calls listed below before you process addresses. However, you
may change your filter setting at any time. Your new filter will take effect upon
your next call to ace_findf().
1. Call ace_init_query() to allocate a query structure. ACEQ_PREDIR
ACEQ_POSTDIR
2. Call ace_clear_query() to clear the query structure. ACEQ_SUFFIX
ACEQ_UNIT
ACEQ_ZIP4
3. Call ace_set_query() to write your criteria into the ACEQ_CART
query structure. Query fields are listed on the ACEQ_COUNTY
ACEQ_LOWRANGE
ace_set_query() reference page (“ace_get_query()” ACEQ_HIGHRANGE
on page 85). Note, you may use only the query fields
listed below. Other query fields are invalid for
suggestion filtering.
4. Call ace_set_sugg_filter() to attach the query structure to the suggestion-
building process.
5. During termination, call ace_term_query() to free the query structure.
Returns Returns ACE_OK if the input parameters are valid; ACE_INVALID_HANDLE

if the input address handle is invalid; or ACE_ERROR if there was a problem
setting the filter.
Note: If you are also consolidating with ace_set_sugg_option(), note that

your filter will be applied to suggestions before they are consolidated.

ace_set_sugg_option(), ace_get_sugg_option()
Synopses int ace_get_sugg_option(three parameters);

int setting; Input: option setting (see table)
int ace_get_sugg_option(three parameters);

int* setting; Input: option setting (see table)
Description Call ace_set_sugg_option() to control the behavior of suggestion lists, including

maximum suggestions and consolidation. Consolidation options are explained on
“How to customize suggestion lists” on page 77). Typically, you would call
ace_set_sugg_option() during program initialization. However, you can call it at
any time. Your new setting will take effect the next time that a suggestion list is
generated.
Returns Returns ACE_OK if successful; otherwise, returns ACE_ERROR if any of the

input parameters was invalid
Symbol for option_ID Setting values Description

ACE_SUGG_OPT_AL_SIZE 1 to _, default is 100 Maximum number of address-line suggestions.
ACE_SUGG_OPT_LL_SIZE 1 to _, default is 15 Maximum number of last-line suggestions.
ACE_SUGG_OPT_RANGEMATCH TRUE or FALSE, default is If TRUE, ACE returns only those address-line sug-
FALSE gestions that match the primary range of the input
address.
ACE_SUGG_OPT_RANGEWINDOW 0 to _, default is 0 A span around the input range, limiting address-line
suggestions to an area a few blocks on either side of
the input address.
ACE_SUGG_OPT_AL_SIMIL 0 to 100, default is 60 Threshold simil score for address suggestions.
ACE_SUGG_OPT_LL_SIMIL 0 to 100, default is 60 Threshold simil score for last-line suggestions.
ACE_SUGG_OPT_STYLE ACE_NORMAL_SUGG Suggestions are not consolidated (default).
ACE_CNSL_SUGG ACE ignores gaps and overlaps in primary ranges, so

consolidation is more aggressive.
ACE_CNSL2_SUGG ACE preserves gaps in primary ranges, but overlap-

ping ranges are consolidated.
Note: To consolidate suggestions, ACE may create
temporary work files. By default, they are placed in
the user’s current working directory. During initial-
ization, verify that the user has read/write permission
in the current directory. To use another location, call
ace_set_file().

Chapter 4:
How to query the postal directories
You can use ACE to extract records from the postal directories. There are many
reasons why you might want to do this. For example, when ACE does not assign
an address, the reasons why might become clearer if you compare the faulty
address with entries in the directories. This chapter explains how to use ACE to
extract records from the USPS directories.
Chapter 4: How to query the postal directories 81

Introduction to directory queries
Overview ACE offers two separate, but similar, sets of functions for directory queries. The
first set is used for querying the ZIP+4 directory about address-line data. The
second set is for querying the City and ZCF directories about last-line data.
When you perform queries, two ACE handles are involved: An input query
handle, and an output browse handle. There are separate init and term functions
for each handle. Again, there are separate handles for ZIP+4 and City/ZCF
queries.
FYI: ACE matches your query fields to directory records using the same match
rules that ACE follows when you process addresses normally.
Address-line queries in Last-line queries in the City and ZCF

the ZIP+4 directory directories
Functions ace_init_query() ace_ll_init_query()

ace_clear_query() ace_ll_clear_query()
ace_set_query() ace_ll_set_query()
ace_init_show() ace_ll_init_show()
ace_show() ace_ll_show()
ace_get_query() ace_ll_get_query()
ace_term_query() ace_ll_term_query()
ace_term_show() ace_ll_term_show()
Handles ACE_QUERY_HANDLE ACE_LL_QUERY_HANDLE
ACE_BROWSE_HANDLE ACE_LL_BROWSE_HANDLE
Header file aceshow.h aceshwll.h

How to query the ZIP+4 directory
1. Include the header file aceshow.h.

2. Call ace_init(), ace_init_addr(), and ace_set_error_rtn() as usual.
3. Call ace_init_query() to allocate a query handle.
4. If you intend only to retrieve ZIP+4 records—and not to assign or
standardize any addresses—call ace_set_mode(ah,
ACE_MODE_AL_SHOW_ONLY, TRUE).
5. Call ace_set_file() to set the location and name of the ZIP+4 directory and
the address-line parsing dictionary.
6. Call ace_open() to open ACE’s auxiliary files.
7. Call ace_clear_query() to clear the query handle.
8. Call ace_set_query() to write your criteria into the query handle. Query fields
are listed on the ace_set_query() reference page.
9. Call ace_init_show() to verify that the query is valid. If the query is valid,
ace_init_show() returns a browse handle. This handle is where retrieved
ZIP+4 records will be written by ace_show().
10. Enter a loop:
! Call ace_show() to perform the query and write the next record into the
browse structure. If there is at least one more qualifying record,
ace_show() returns TRUE.
! Call ace_get_query() to retrieve individual fields (one per call) from the
current ZIP+4 record. Retrieved fields are listed and described on the
ace_get_query() reference page.
! Exit the loop when ace_show() returns FALSE, indicating that no more
records meet the search criteria. To limit the maximum number of
records extracted, you might set your own counter.
! When you are finished with the browse handle, call ace_term_show() to
free it.
11. If you want to make additional queries, repeat steps 7 through 10.
12. Call ace_term_query() to free the query handle.

ace_clear_query()
Synopsis #include <aceshow.h>
int ace_clear_query(one parameter);
ACE_QUERY_HANDLE query_id; Input: query handle

from ace_init_query()
Description Call ace_clear_query() between queries against the ZIP+4 directory. This
function clears the query handle.
If you do not call this function between queries, data may remain in the handle
that would corrupt the next query.

ace_get_query()
int ace_get_query(three parameters);
ACE_BROWSE_HANDLE browse_id; Input: browse handle

from ace_init_show()
int browse_field; Input: browse field
char* buffer; Output: retrieved string
Description The ace_get_query() function retrieves one field from the current ZIP+4 record of
the current query. Valid browse_field names are listed on the next page.
Note: ACE does not check the size of the receiving buffer. It is your
responsibility to provide adequate space for the data you retrieve.
Browse fields You will be retrieving components from a ZIP+4 directory record. Many of the
components available here are similar to components that you get during normal
address processing, through ace_get_component(). If you need descriptions of
these components, please refer to the Quick Reference for Library Products.
However, there are two major differences to keep in mind:
! Many ZIP+4 records cover a whole city block. That is why you can get
ACEQ_LOWRANGE and ACEQ_HIGHRANGE, but not a single, specific
primary range.
! Many ZIP+4 records cover two block faces, one on the even side of the
street, the other odd. So some of the components you can retrieve here come
in two flavors—for example, ACEQ_CARTEVEN and ACEQ_CARTODD.
When you are doing normal address processing, you can get a component
named ACE_CART. ACE figures out whether to give you the CART for the
even or odd side.

Browse fields for ace_get_query()
Field type Field name Notes

Record info ACEQ_RECTYPE Record type (10=street, 14=PO box, 18=rural route, 20=high-
rise, 21=firm, 26=general delivery).
ACEQ_ODDEVEN An E, O, or B to indicate whether the record covers the even-
numbered side of the street, odd, or both.
ACEQ_SODDEVEN Same indicator for secondary-address records.

ACEQ_LLINDEX Last-line index is a 3-digit number that links each ZIP+4 direc-
tory record to a particular combination of city, state, and ZIP.
ACEQ_URB_INDEX Urbanization index is a number that links a record to an urban-

ization name. (It is not the name itself.) The Urb_Index will be
zero for PR records that do not have an urbanization, and for
records outside Puerto Rico.
Address-line ACEQ_LOWRANGE Primary range; comparable to ACE_PRIM_RANGE.
components ACEQ_HIGHRANGE
ACEQ_PREDIR Predirectional; similar to ACE_PREDIR.
ACEQ_PNAME Primary (street) name; similar to ACE_PRIM_NAME.
ACEQ_POSTDIR Postdirectional; similar to ACE_POSTDIR.
ACEQ_SUFFIX Street suffix; similar to ACE_SUFFIX.
ACEQ_SNAME Secondary name, usually a firm name.
ACEQ_UNIT Unit designator; similar to ACE_USPS_UNIT.
ACEQ_LOWSRANGE Secondary range (apartment or suite number); comparable to
ACEQ_HIGHSRANGE ACE_SEC_RANGE.
Postal codes ACEQ_ZIP Five-digit ZIP Code; similar to ACE_ZIP.
ACEQ_ZIP4EVEN ZIP+4 add-on code; comparable to ACE_ZIP4.
ACEQ_ZIP4ODD
ACEQ_CARTEVEN Carrier-route number; comparable to ACE_CART.
ACEQ_CARTODD
ACEQ_ALSTYP Alias type; similar to ACE_APA_TYPE.
ACEQ_LACSIND LACS (9-1-1) indicator; similar to ACE_LACSCODE.
ACEQ_ZIP_MOVE ZIP Move indicator; similar to ACE_ZIP_MOVE.
ACEQ_CONGRESS Congressional district; similar to ACE_CONGRESS.
ACEQ_COUNTY FIPS county number; similar to ACE_COUNTY.
ACEQ_ALTERNATE ZIP+ 4 directory alternate address indicator. Returns a value of T
if the address is an Alternate and a value of F if the Address is
not an Alternate.

ace_init_query()
int ace_init_query(two parameters);

ACE_QUERY_HANDLE* query_id; Output: query handle
Description Call ace_init_query() to initialize an ACE query handle. That handle will contain
fields for the ZIP+4 query.
Note: Each call to ace_init_query() should be paired with a call to

ace_term_query(). Do not rely on ace_term() to free the query handle(s).

ace_init_show()
int ace_init_show(two parameters);

ACE_BROWSE_HANDLE* browse_id; Output: browse handle
Description The ace_init_show() function evaluates the ACE_QUERY_HANDLE. If the

query is valid, it creates an ACE_BROWSE_HANDLE. This second handle will
be used as input to ace_show(), which actually performs the query.

Most of the remaining return values (table below) indicate an error in the query
date. Previously, these conditions were reported through a query_status integer.
Now they are return values.
Return Description
ACESHOW_BAD_CART The input ACEQ_CART is invalid.

ACESHOW_BAD_HIGH_ZIP The input ACEQ_ZIPHIGH is invalid.
ACESHOW_BAD_LOW_ZIP The input ACEQ_ZIPLOW is invalid.
ACESHOW_BAD_POSTDIR The input ACEQ_POSTDIR is invalid.
ACESHOW_BAD_PREDIR The input ACEQ_PREDIR is invalid.
ACESHOW_BAD_RANGES There is conflict between the input
ACEQ_LOWRANGE and ACEQ_HIGHRANGE.
ACESHOW_BAD_SUFFIX The input ACEQ_SUFFIX is invalid.
ACESHOW_BAD_ZIP_RANGE There is conflict between the input
ACEQ_ZIPLOW and ACEQ_ZIPHIGH.
ACESHOW_BAD_ZIP4 The input ACEQ_ZIP4 is invalid.
ACESHOW_NOMEM The browse structure could not be created because
memory was exhausted.
Note: Each call to ace_init_show() should be paired with a call to

ace_term_show(). Do not rely on ace_term() to free the browse handle(s).

ace_set_query()
int ace_set_query(three parameters);

int query_field; Input: query field (table below)
char* query_data; Input: data to be matched
Description Call ace_set_query() function to load one component into the ACE_QUERY
handle.
You may query on any combination of fields listed on the next page.
Fields for setting yes/no options
Symbol for query_field Description
ACEQ_FINANCE Set either of the strings “YES” or “NO”. Finance Areas are USPS districts that often extend
over regional or metropolitan areas. If you want to broaden a search beyond a particular ZIP
Code—but not so far as a 3-digit area—set ACEQ_ZIPLOW and also set ACEQ_FINANCE
to YES. This might be helpful if you aren’t certain of the correct ZIP Code.
ACEQ_SHOW_SDRONLY Set either of the strings “YES” or “NO”. Set NO for normal queries. If you set YES, ACE
will retrieve only Street Descriptor Records. (These records contain only the primary name
and ZIP—no ranges, suffix, directionals, etc.). By setting ACEQ_PNAME and
ACEQ_SDRONLY=YES, you can verify that a primary name exists somewhere in the
mother ZIP. To see all primary names in the mother ZIP, set ACEQ_SDRONLY=YES and
do not set ACEQ_PNAME. An SDR-only search is much faster.
ACEQ_SHOWALIAS Set “YES” if you want ACE to include alias records in the retrieval; otherwise, set “NO”.

Fields for setting query data
Symbol for query_field Description
ACEQ_CART You may restrict your query to a particular carrier route number; for example: C103, R001,
H002, and so on.
ACEQ_LOWRANGE To search for a certain house number, load it into ACEQ_LOWRANGE and set
ACEQ_HIGHRANGE ACEQ_HIGHRANGE empty. To retrieve a range of house numbers, load
ACEQ_LOWRANGE and ACEQ_HIGHRANGE. ACE will extract all records that overlap
this range, even partially.
ACEQ_PNAME You must spell the street primary name correctly for ACE to find it in the directory. Wild-
cards are supported—for example, MA* finds Main and Maynard. To find rural addresses,
enter “rural route,” not RR.
ACEQ_PREDIR N, NE, E, SE, S, SW, W, or NW
ACEQ_POSTDIR
ACEQ_SUFFIX Street suffix such as AVE, ST, BLVD, RD, MALL, etc.
ACEQ_UNIT Unit designator such as STE, APT, RM, FLR, etc.
ACEQ_ZIP4 ZIP+4 code.
ACEQ_ZIPLOW To search a range of ZIP Codes, load both ACEQ_ZIPLOW and ACEQ_ZIPHIGH.
ACEQ_ZIPHIGH
To search in just one ZIP, load ACEQ_ZIPLOW and set ACEQ_ZIPHIGH empty.
To cover a 3-digit ZIP area, express the range as: xxxØØ to xxx99.

ace_show()
int ace_show(two parameters);
ACE_BROWSE_HANDLE browse_id; Input: browse handle

int* status; Output: status of current query
Description The ace_show() function retrieves a record from the ZIP+4 directory, following
search criteria stored in the ACE_BROWSE_HANDLE.
The a status integer indicates the status of the current query:
Symbol for status Description
ACESHOW_GOTLINE A line was returned.

ACESHOW_DONE The query is completed (all ZIP+4 records matching the
query have been returned).
ACE_INVALID_HANDLE The input ACE_BROWSE_HANDLE was invalid.
ACE_ERROR An internal error occurred.
Returns Returns TRUE if an additional record was retrieved. Returns FALSE if the query
is now complete.
Unlike other functions in this chapter, if ace_show() receives an invalid browse
handle, it signals the error by passing ACE_INVALID_HANDLE as the value of
the status parameter. Most other functions pass ACE_INVALID_HANDLE
through the return value.

ace_term_query(), ace_term_show()
Synopses #include <aceshow.h>
int ace_term_query(one parameter);
ACE_QUERY_HANDLE* query_id; Input: query handle

int ace_term_show(one parameter);
ACE_BROWSE_HANDLE* browse_id; Input: browse handle

Description The ace_term_query() function frees all dynamic memory that was allocated the
ACE query handle by ace_init_query().
The ace_term_show() function frees all dynamic memory that was allocated for
the ACE browse handle by ace_init_show().
Note: Each call to ace_init_query() should be paired with a call to

ace_term_query(). Each call to ace_init_show() should be paired with a call
to ace_term_show(). Do not rely on ace_term() to free the query or browse
handle(s).

How to query the City and ZCF directories
1. Include the header file aceshwll.h.

2. Call ace_init(), ace_init_addr(), and ace_set_error_rtn() as usual.
3. Call ace_ll_init_query() to allocate a query handle.
4. If you intend only to retrieve last-line information—and not to assign or
standardize any addresses—call ace_set_mode(ah,
ACE_MODE_LL_SHOW_ONLY, TRUE).
5. Call ace_set_file() to set the location and name of the City directory, ZCF
directory, and last-line parsing dictionary.
7. Call ace_ll_clear_query() to clear the query handle.
8. Call ace_ll_set_query() to write your criteria into the query handle. Query
fields are listed on the ace_ll_set_query() reference page. The only query
field that you must set is ACE_LLQ_TYPE.
9. Call ace_ll_init_show() to verify that the query is valid. If the query is valid,
ace_ll_init_show() returns an ACE_LL_BROWSE_HANDLE. This is where
retrieved records will be written by ace_ll_show().
10. Enter a loop:
! Call ace_ll_show() to perform the query and write the next record into
the browse handle. If there is one more qualifying record, ace_ll_show()
returns TRUE.
! Call ace_ll_get_query() to retrieve individual fields (one per call) from
the current ZIP+4 record. Retrieved fields are listed and described on the
ace_ll_get_query() reference page.
! Exit the loop when ace_ll_show() returns FALSE, indicating that no
more records meet the search criteria. To limit the maximum number of
records extracted, you might set your own counter.
! When you are finished with the browse handle, call ace_ll_term_show()
to free it.
11. If you wish to make additional queries, repeat steps 7 through 10.
12. Call ace_ll_term_query() to free the query handle.
14. Call ace_term() to free global memory and shut down ACE.

ace_ll_clear_query()
Synopsis #include <aceshwll.h>
int ace_ll_clear_query(one parameter);
ACE_LL_QUERY_HANDLE ll_query_id; Input: query handle

from ace_ll_init_query()
Description Call ace_ll_clear_query() between queries against the City and ZCF directories.
This function clears the query handle.
If you do not call this function between queries, data may remain in the handle
that would corrupt the next query.
For background information on City and ZCF queries, see Chapter 6.

ace_ll_get_query()
int ace_ll_get_query(three parameters);
ACE_LL_BROWSE_HANDLE ll_browse_id; Input: browse handle

from ace_ll_init_show()
int browse_field; Input: browse field
char* buffer; Output: retrieved string
Description The ace_ll_get_query() function retrieves one field from the current record of the
current last-line query. Browse fields are listed below.
ACE does not check the size of the receiving buffer. It is your responsibility to
provide adequate space for the data you retrieve.

Browse fields for ace_ll_get_query()
Name Description
ACE_LLQ_ABBR Contains “Y” or “N” to indicate whether the city name is

an abbreviation.
ACE_LLQ_CITYNAME City name. Remember that this is the city name associated
with a postal facility (except when
ACE_LLQ_FACTYPE=N). It is not necessarily a geo-
graphical city name.
ACE_LLQ_COUNTY Three-digit FIPS county number.
ACE_LLQ_CR_SORT_ZN Contains “Y” or “N” to indicate:
Y Within an automated letter mailing, sortation at the

carrier-route level is permitted for this ZIP Code.
N Within an automated letter mailing, sortation at the

carrier-route level is not permitted for this ZIP Code.
ACE_LLQ_FAC9 Contains “Y” or “N” to indicate:
Y The city name is a place name, not valid for mailing.
N The city name is valid for mailing.

Name Description
ACE_LLQ_FACTYPE A single letter indicating the type of postal facility:
A Airport Mail Facility

B Branch Post Office
C Community Post Office
D Area Distribution Center
E Sectional Center Facility
F Delivery Distribution
G General Mail Facility
K Bulk Mail Center
M Money Order Unit
P Post Office
S Station
U Puerto Rican Urbanization
N Non-postal city name—under CASS rules, not suit-

able for use on mail pieces
ACE_LLQ_LLINDEX Last-line index is a three-digit number that identifies a
particular combination of city, state, and ZIP.
ACE_LLQ_MILITARY Contains “Y” or “N” to indicate whether the record is a
military ZIP Code.
ACE_LLQ_MZONE Contains “Y” or “N” to indicate whether the record is
multi-ZIP city.
ACE_LLQ_STATE Two-letter state abbreviation.
ACE_LLQ_UNIQUE Contains “Y” or “N” to indicate whether the record is a
unique ZIP Code. A unique ZIP is dedicated to a large
company or institution.
ACE_LLQ_URBINDEX Urbanization index is a number that links a ZIP+4 record
to an urbanization name. (It is not the name itself.) The
Urb_Index will be zero for PR records that do not have an
urbanization, and for records outside Puerto Rico.
ACE_LLQ_ZIP Five-digit ZIP Code.

ace_ll_init_query()
int ace_ll_init_query(two parameters);

ACE_LL_QUERY_HANDLE* ll_query_id; Output: query handle
Description Call ace_ll_init_query() to initialize an ACE last-line query handle. That handle
will contain fields for last-line queries.
Note: Each call to ace_ll_init_query() should be paired with a call to

ace_ll_term_query(). Do not rely on ace_term() to free the query handle(s).

ace_ll_init_show()
ace_ll_init_show(two parameters);

ACE_LL_BROWSE_HANDLE* ll_browse_id; Output: browse handle
Description The ace_ll_init_show() function validates the search criteria and creates an
ACE_LL_BROWSE_HANDLE. This handle will be used as input to
ace_ll_show(), which actually performs the query.

Most of the remaining return values (table below) indicate an error in the query
date. Previously, these conditions were reported through a query_status integer.
Now they are return values.
Return Description
ACESHOW_BAD_ZIP_RANGE There is an error in ACE_LLQ_ZIPLOW or

ACE_LLQ_ZIPHIGH, or both.
ACESHOW_BAD_STATE The input ACE_LLQ_STATE is invalid.
ACESHOW_NOMEM The browse structure could not be created because
memory was exhausted.
Note: Each call to ace_ll_init_show() should be paired with a call to

ace_ll_term_show(). Do not rely on ace_term() to free the browse
structure(s).

ace_ll_set_query()
int ace_ll_set_query(three parameters);

int query_field; Input: query field
char* query_data; Input: data to be matched
Description The ace_ll_set_query() function loads one component into the

ACE_LL_QUERY_HANDLE.
Query fields are listed below. The only mandatory query field is
ACE_LLQ_TYPE.
You must set that field so that ACE can determine which file to query.
Fields for setting query

data (City queries only)
Name Description
ACE_LLQ_CITYNAME You must spell the city name correctly in order for ACE to
find it in the directory. Wildcards are supported—for exam-
ple, MA* finds Mansfield and Marblehead.
ACE_LLQ_STATE Set the postal, two-letter abbreviation.

data (ZCF queries only)
Name Description
ACE_LLQ_ZIPHIGH To search a range of ZIP Codes, load the low end of the
ACE_LLQ_ZIPLOW range into ACE_LLQ_ZIPLOW and the high end into
ACE_LLQ_ZIPHIGH. If you need to search in just one
ZIP, load the ZIPLOW field and leave ZIPHIGH blank. To
search a 3-digit ZIP area, express the range as: xxxØØ to
xxx99.

options
Name Description
ACE_LLQ_TYPE This field tells ACE which postal directory to search—it

will not search both. Set either of the strings “CITY” or
“ZCF”. When querying by city and state to find ZIPs, use
CITY. When querying by ZIP to find cities, set ZCF.
ACE_LLQ_ABBR Set any of three strings:
“YES” Retrieve only those records marked as abbrevia-
tions.
“NO” Exclude any records marked as abbreviations.
“” Ignore the abbreviation indicator.
ACE_LLQ_FAC9 Set any of three strings:
“YES” Retrieve only those records marked as place names.
“NO” Exclude any records marked as place names.
“” Ignore the place-name indicator.
ACE_LLQ_MILITARY Set any of three strings:
“YES” Retrieve only those records marked as military.
“NO” Exclude any records marked as military.
“” Ignore the military indicator.
ACE_LLQ_MZONE Set any of three strings:
“YES” Retrieve only those records marked as multi-ZIP.
“NO” Exclude any records marked as multi-ZIP.
“” Ignore the multi-ZIP indicator.
ACE_LLQ_UNIQUE Set any of three strings:
“YES” Retrieve only those records marked as unique ZIP.
“NO” Exclude any records marked as unique ZIP.
“” Ignore the unique-ZIP indicator.

ace_ll_show()
int ace_ll_show(two parameters);
ACE_LL_BROWSE_HANDLE ll_browse_id; Input: browse handle

int* status; Output: status of query
Description The ace_ll_show() function retrieves one record from the City or ZCF directory
and writes to the ACE last-line browse handle.
The status integer indicates the status of the current query:
Symbol for status Description
ACE_LLSHOW_GOTLINE A line was returned.

ACE_LLSHOW_DONE The query is completed (all ZIP+4 records matching the
query have been returned).
ACE_INVALID_HANDLE The input ACE_LL_BROWSE_HANDLE was invalid.
ACE_ERROR An internal error occurred.
Returns Returns TRUE if an additional record was retrieved. Returns FALSE if the query
is now complete, or if the input browse handle was invalid.
Unlike other functions in this chapter, if ace_ll_show() receives an invalid browse
handle, it signals the error by passing ACE_INVALID_HANDLE as the value of
the status parameter. Most other functions pass ACE_INVALID_HANDLE
through the return value.

ace_ll_term_query(), ace_ll_term_show()
Synopses #include <aceshwll.h>
int ace_ll_term_query(one parameter);
ACE_LL_QUERY_HANDLE* ll_query_id; Input: query handle

#include <aceshwll.h>
int ace_ll_term_show(one parameter);
ACE_LL_BROWSE_HANDLE* ll_browse_id; Input: browse handle

Description The ace_ll_term_query() function frees all dynamic memory that was allocated
by ace_ll_init_query().
The ace_ll_term_show() function frees all dynamic memory that was allocated by
ace_ll_init_show().
Note: Each call to ace_ll_init_query() should be paired with a call to

ace_ll_term_query(). Each call to ace_ll_init_show() should be paired with a
call to ace_ll_term_show(). Do not rely on ace_term() to free the query or
browse structure(s).

Chapter 5:
Delivery Point Validation (DPV)
Delivery Point Validation (DPV) is a technology developed to assist you in

validating the accuracy of your address information. With DPV, you can identify
addresses that are undeliverable as addressed and whether or not an address is a
Commercial Mail Receiving Agency (CMRA, a private business that acts as a
mail receiving agent).
Chapter 5: Delivery Point Validation (DPV) 103

What is Delivery Point Validation (DPV)?
Description The USPS developed Delivery Point Validation (DPV) to assist you in validating
the accuracy of your address information. With DPV, you can identify addresses
that are undeliverable as addressed and whether or not an address is a
Commercial Mail Receiving Agency (CMRA).
DPV can be useful in the following areas:
! Mailing: DPV assists in screening out undeliverable-as-addressed (UAA)
mail and cuts down on mailing costs.
! Information quality: DPV’s ability to verify an address down to the
individual house, suite, or apartment rather than block face increases the
data’s level of accuracy.
! Increased assignment rate: Using DPV tiebreak mode to resolve a tie when
other tie-breaking methods are not conclusive may increase assignment rates.
! Preventing mail-order-fraud: DPV can assist merchants by verifying valid
delivery addresses and Commercial Mail Receiving Agencies (CMRA). This
can eliminate shipping of merchandise to individuals placing fraudulent
orders.
Performance Due to additional time required to perform DPV processing, you may see a
difference in processing time. Processing time may vary with the DPV feature
based on operating system, system configuration, and other variables that may be
unique to your operating environment.
You can decrease the time required for DPV processing by loading DPV
directories into system memory before processing. See “DPV performance” on
page 110.
Memory usage Performing ACE processing with DPV requires approximately 42 MB of

memory for processing. The USPS requires ACE to buffer 35 MB of data to read
the DPV directories. Make sure that your computer has enough memory available
before performing DPV processing.

USPS requirements
DPV security ACE has added security to prevent DPV abuse. If ACE detects attempted DPV
abuse, the software locks and must be unlocked by either SAP BusinessObjects
Customer Support or the USPS National Customer Support Center (NCSC)
depending on the lock situation. For more information see, “DPV locking” on
page 111.
Each company that purchases the DPV functionality is required to sign a legal
agreement stating that it will not attempt to abuse the DPV product. If a user
abuses the DPV product, the USPS has the right to prohibit the user from using
DPV in the future.
Monthly directory DPV directories are shipped monthly with the U.S. directories in accordance with
updates USPS guidelines. The DPV directories also include information for the U.S.
Territories.

Installing DPV and its directories
The DPV product is included in the ACE installation as a separate component.

Refer to the System Administrator’s Guide for installation instructions. DPV by
default is installed in pw\dpv\ in Windows and postware/dpv/ in UNIX.
DPV directory files The DPV directory files require approximately 600 MB of additional hard drive
space. Copy the following directory files from the Delivery Point Validation
Directories CD to the pw\dpv\ or postware/dpv/ directory:
! dpva.dir
! dpvb.dir
! dpvc.dir
! dpvd.dir
! dpv_no_stats.dir
! dpv_vacant.dir
Important: The DPV directories must reside on a hard drive. Do not rename any of the files.
Location and names of DPV will not run if the file names are changed.
DPV directories
Directory updates The DPV directories are shipped monthly with the U.S. national directory update.
The DPV directories expire in 105 days and must be of the same month as the
national directory. Users that currently receive bi-monthly ZIP+4 directory
updates will need to upgrade to receive monthly updates.

Performing DPV processing
You must set the following functions to perform DPV processing:

! Set the DPV directory path by calling ace_set_file() with the value of
ACE_DIR_DPV. Enter the DPV directory path only. ACE accesses multiple
DPV directory files during DPV processing. ACE generates a verification
error if a specific file name is entered. For details, see “ace_set_file(),
ace_get_file(), ace_get_z4dirno()” on page 52.
! Set the DPV processing mode by calling ace_get_mode() and
ace_set_mode() with the value below. For more information, see
“ace_set_mode(), ace_get_mode()” on page 56.
Value Description
ACE_MODE_ENABLE_DPV Use this value to enable DPV processing.
! Set the required Customer & USPS Licensee Information parameters.
Required Customer & Set the following required customer information fields using
USPS Licensee ace_set_mailer_info():
Information
parameters ACE_MAILER_CUST_CO
ACE_MAILER_CUST_ADDRESS
ACE_MAILER_CUST_CITY
ACE_MAILER_CUST_STATE
ACE_MAILER_CUST_ZIP
ACE_MAILER_CUST_ZIP4
ACE_MAILER_LOG_FILE_PATH
For more information about the ace_set_mailer_info() function, see
“ace_set_mailer_info()” on page 127.
Verification error If your job setup does not contain the required USPS information, ACE issues a
verification error. Use ace_get_error_info() or ace_get_error_info_return() to
obtain more information about the verification error.
ACE issues one error per run based on the first parameter it finds that is required
but not supplied.

DPV output components
DPV output components are available for reporting DPV processing results. For a
complete list of these output components, see the Quick Reference for Library
Products. ACE_MODE_ENABLE_DPV must be set to TRUE in order to post
information to these output components.
Output component Length Description
ACE_DPV_CMRA 1 Y The address is a valid Commercial Mail Receiving Agency.

N The address is not a Commercial Mail Receiving Agency.
L The address triggered DPV locking.
Blank This component is blank when the DPV Validation option is set to FALSE, DPV
processing is currently locked, or ACE cannot assign the input address.
ACE_DPV_STATUS 1 The DPV status is determined during DPV validation. The following values are available
for DPV Status.
Y The address is a confirmed delivery point. The primary range and secondary range (if
present) are valid.
N The address is not a valid delivery point.
S The primary range is a valid delivery point but, the parsed secondary range is not valid
in the DPV directory.
D The primary range is a valid delivery point but the secondary range data is not avail-
able on input.
L This address triggered DPV Locking. Call ace_get_dpv_msg() to retrieve the DPV
lock message.
ACE_CASS_MATCH 1 Use this field to indicate which option was used to make the assignment.
0 The Non-CASS and DPV tiebreak options are disabled or were not used to make an
assignment.
1 Inexact ZIP move assignment.
2 Input ZIP+4 assignment.
3 DPV tie-breaking was used to make this assignment.
ACE_DPV_FTNOTE 12 DPV footers are required for end-user self CASS certification. The footers contain the
following information:
AA Input address matches to the ZIP+4 file.
A1 Input address does not match to the ZIP+4 file.
BB All input address components match to DPV.
CC Input address primary number matches to DPV but the secondary number does not
match (the secondary is present but invalid).
M1 Input address primary number is missing.
M3 Input address primary number is invalid.
N1 Input address primary number matches to DPV but the high-rise address is missing
the secondary number.
P1 Input address is missing the PO, RR, or HC Box number.
RR Input address matches to CMRA.
R1 Input address matches to CMRA but the secondary number is not present.
Note: ACE always posts the DPV footers in the same order and this field will not always
be 12 characters in length.

ACE_DPV_CMRA 1 Y The address is a valid Commercial Mail Receiving Agency.

N The address is not a Commercial Mail Receiving Agency.
L The address triggered DPV locking.
ACE_DPV_VACANT 1 Vacant address indicator.
Y Address is vacant.
N Address is not vacant.
Blank Address was not looked up.

DPV performance
You can decrease the time required for DPV processing by loading DPV
directories into system memory before processing.
You may want to disable this feature when processing smaller files. It takes time
(up to two minutes) to load the DPV directories into memory.
Memory usage You may need to install additional memory on your system. We recommend a
minimum of 768MB. To determine the amount of memory required, check the
size of the DPV directories (currently 560MB) and add that to the amount of
memory required to run ACE (currently 42MB for each thread/instance). The size
of the DPV directories will vary depending on the amount of new data in each
directory release.
Performing DPV ACE now uses the Object Data Manager (ODM) to process DPV records. If you
processing on the AIX are running ACE on the AIX platform, you need to make sure that the ODMDIR
platform variable is set before processing. Type the following command to display the path
to the ODM directory (for example, /usr/lib/objrepos):
echo $ODMDIR
If the path does not exist, contact your system administrator.
AIX 32 bit users AIX 32 bit users need to link with the -bmaxadata:0x30000000 flag to load DPV
directories into system memory.
Loading DPV To load DPV directories into system memory, set the following options for the
directories ace_set_mode() and ace_get_mode() functions: For more information, see
“ace_set_mode(), ace_get_mode()” on page 56.
Option Description
ACE_MODE_CACHE_DPV_DIRS Set this option to TRUE to enable DPV directory caching.

Set this option to FALSE to disable DPV directory caching.
The default setting is FALSE.
ACE_MODE_ABORT_ON_CACHE_ERROR Set this option to FALSE if you want to continue DPV processing
without caching. Set this option to TRUE to discontinue processing.
The default setting is TRUE.
When this option is set to TRUE, ACE generates a verification mes-
sage if there is not enough system memory available to load the DPV
directories.
This option is only valid when ACE_MODE_CACHE_DPV_DIRS is
set to TRUE.

DPV locking
False-positive addresses are included in the DPV directories as a security

precaution. If ACE detects a false-positive address during processing, it marks
the record as a false-positive and discontinues DPV processing.
Note: Unlike ACE Views and Job-File, ACE Library does not check whether
or not you are a limited or full service provider and locks anytime a false
positive is encountered.
If you perform batch processing and encounter a false-positive address, call

ace_get_dpv_msg() to retrieve the locking information required by customer
support to unlock DPV.
For information about ace_get_dpv_msg( ), see page 115.

DPV false positive log
ACE generate a false-positive log file anytime it encounters a false positive,

regardless of how your job is set up. For each mailing list that contains a false
positive record, ACE creates a log file. If multiple false positives exist within one
mailing list, ACE writes them all to the same log file.
When ACE generates the log file, NCOALink limited and full service providers
(L/FSP) are required to send that log file to the USPS. This does not apply to end
users who have DSF2 disabled in their jobs.
Important: L/FSPs must not process additional lists for a customer that has
!
encountered a false-positive record. The mailing list cannot be released until
the USPS approves it.
Location for log files You set the location for this log file using ACE_MAILER_LOG_FILE_PATH in
ace_set_mailer_info.
Retrieve locking If you are not an NCOALink L/FSP, and you encounter a false-positive address
information during processing, contact SAP BusinessObjects Customer Support with locking
information. To obtain this information, call ace_get_dpv_msg(). For details see
“ace_get_dpv_msg()” on page 115. Find instructions for DPV unlocking in the
ACE Job-File Reference.
If you perfom batch processing and encounter a false-positive address, ACE
continues to process without DPV until the next ace initialization sequence or an
ace_open() call is made after the lock. At that point ace_open() fails.

DPV No Stats indicators
The USPS uses No Stats indicators to mark addresses that fall under the No Stats
category. ACE uses the No Stats table when you have DPV turned on in your job.
The USPS classifies No Stats addresses as those that:
! do not have established delivery yet
! receive mail as part of a drop
! have been vacant for a certain period of time
No Stats table ACE performs DPV processing based on the install status of the DPV No Stats
table (dpv_no_stats.dir). The No Stats table is supplied by SAP BusinessObjects
on the DPV directory install CD.
ACE automatically checks for the No Stats table in the directory folder that you
indicate in your job setup. ACE performs DPV processing based on the install
status of the directory.
dpv_no_stats.dir Results
Installed ACE automatically performs DPV processing and outputs No

Stats indicators when you include the No Stats output fields in
your job.
Not installed ACE automatically skips the No Stats processing and does not
issue an error message. ACE will perform DPV processing but
won’t populate the AP.DPV_NoStat and APM.DPV_NoStat out-
put fields.
CASS mode: In all of these instances, ACE does not perform DPV
!
processing when you are not running ACE in CASS mode.
No Stats output fields Use the No Stats output fields to post No Stat indicator information to an output
file.
ACE Library Length Description
ACE_DPV_NO_STATS 1 No Stat indicator. No Stat means that the address

is a vacant property, it receives mail as a part of
a drop, or it does not have an established deliv-
ery yet.
Y Address is flagged as No Stat in DPV
data.
N Address is not No Stat.
blank Address was not looked up.
To indicate the maximum length of this compo-
nent in ACE Library, use
ACE_DPV_NO_STATS_LEN.

DPV Vacant indicators
ACE provides vacant information in output fields and reports using DPV Vacant
counts. The USPS DPV Vacant lookup table is included with the DPV Directory
installation (dpv_vacant.dir).
The USPS uses DPV Vacant indicators to mark addresses that fall under the
Vacant category. ACE uses the Vacant table when you have DPV or DSF2 turned
on in your job.
The USPS defines ”vacant” as any delivery point that was active in the past,
but is currently not occupied (usually over 90 days) and is not currently
receiving mail delivery. The address could receive delivery again in the
future. “Vacant” does not apply to seasonal addresses.
DPV address-attribute Address attributes for the assigned address are available in ACE fields.
output fields
ACE_DPV_VACANT 1 Vacant address indicator.

Y Address is vacant.
N Address is not vacant.
blank Address was not looked up.

ace_get_dpv_msg()
Synopsis int ace_get_dpv_msg (three parameters);

int line_number; Input: number of message lines
char *message_text; Output: retrieved data
Description Use ace_get_dpv_msg() to retrieve the message describing the current DPV lock
incident. This message includes the text that the USPS requires DPV-enabled
software to present to users when DPV locks.
After calling ace_get_component() to retrieve the component
ACE_DPV_STATUS, check to see if the result is L, which indicates that the
current record caused DPV to lock. In this situation, call ace_get_dpv_msg() to
retrieve each line of the DPV lock message and display them to the user and/or
include that message in a report.
We recommend using a FOR loop to call ace_get_dpv_msg() with line_number
values from 1 to ACE_DPV_MSG_LINES to receive the entire message.
Sample message:
1. ACE_DPV_ALERT_MSG_NO
2. ACE_DPV_LOCK_CODE_MSG_NO
3. ACE_DPV_LOCK_ADDR_MSG_NO_START through
ACE_DPV_LOCK_ADDR_MSG_NO_END
4. ACE_DPV_USPS_MSG_NO_START through
ACE_DPV_USPS_MSG_NO_END

You can retrieve specific parts of the above text by calling line numbers
separately:
Symbol for line_number values Length Message section
ACE_DPV_MSG_LINES 21 Total number of lines

of the entire message.
ACE_DPV_MSG_LEN 81 Width of message, in
characters.
ACE_DPV_ALERT_MSG_NO 1 The alert message.
ACE_DPV_LOCK_CODE_MSG_NO 3 The lock code.
ACE_DPV_LOCK_ADDR_MSG_NO_START 6 The lock address.
ACE_DPV_LOCK_ADDR_MSG_NO_END 9
ACE_DPV_USPS_MSG_NO_START 11 The USPS lock text.
ACE_DPV_USPS_MSG_NO_END 22
Returns This function returns ACE_OK or ACE_ERROR.
Sample code Here is an example of code used to retrieve all the lines of the DPV lock message.
/* The variables used in the following code would be declared as
follows: */
int line_num;
ADDR_HANDLE ah;
char dpv_message_text[ACE_DPV_MSG_LEN];
/* Assert:
*/
/* Calling ace_get_component() for ACE_DPV_STATS with
address_handle resulted */
/* in a value of 'L'. No additional addresses have been processed.
We need to */
/* display information about the DPV lock incident.
*/
/* Loop through all the lines in the DPV lock message: */

for (line_num = 1; line_num <= ACE_DPV_MSG_LINES; line_num++)
{
/* Get the next line of the DPV lock message into the string
dpv_message_text: */
ace_get_dpv_msg(ah, line_num, dpv_message_text);
/* Add your code to display the message in dpv_message_text to

the user in place */
/* of the following line: */
printf("%s\n", dpv_message_text);

Chapter 6:
Residential Delivery Indicator (RDI)
The Residential Delivery Indicator (RDI) lets you determine if a given address is
for a residence or not.
For more information about RDI, see the ACE User’s Guide.
Chapter 6: Residential Delivery Indicator (RDI) 117

What is RDI?
Description The Residential Delivery Indicator (RDI) lets you determine if a given address is
for a residence or not.
Parcel shippers can find RDI information to be very valuable. Why? Some
delivery services charge higher rates to deliver to residential addresses. The
USPS, on the other hand, does not add surcharges for residential deliveries. So
when a parcel mailer can recognize an address as a residence, they have increased
incentive to ship the parcel with the USPS instead of with a competitor that
applies a residential surcharge.
According to the USPS, 91 percent of American addresses are residential.
Naturally, the USPS is motivated to encourage the use of RDI by parcel mailers.
How does RDI work? With RDI, ACE can determine if the address represented by an 11-digit ZIP Code
(ZIP+4 and delivery point barcode) is a residential address or not. (ACE can
sometimes do the same with a 9-digit ZIP Code.)
ACE indicates that an address is for a residence or not by means of an output
component—a Residential Delivery Indicator, or RDI.
Using the RDI feature involves only a few steps:
1. Install USPS-supplied directories. See “Obtain RDI directories” on page 119.
2. Specify where these directories are located.
3. Enable RDI processing in ACE. See “Enable RDI processing” on page 120.
4. Run.
Compatibility RDI has the following compatibility with other options in ACE:
! To perform RDI processing, the assignment mode must be set to Assign.
! RDI is allowed in both CASS and non-CASS processing modes.
! RDI is allowed with or without DPV processing.

RDI directories
Obtain RDI directories RDI directories are available through the USPS. You must purchase these
directories directly from the USPS, and install them according to USPS
instructions. Otherwise, these directories are inaccessible to ACE.
If the files are corrupt or not found in the specified locations when RDI is turned
on, ACE reports an error. To replace corrupt files, contact the USPS.
RDI directories RDI requires a pair of directory files (see below). Store these RDI files in the
same directory location. ACE handles RDI functionality without you having to do
anything more than specify where these files are.
File name Description
rts.hs11 For 11-digit ZIP Code lookups (ZIP+4 plus DPBC). This file is used
when an address contains an 11-digit ZIP Code. Determination is
based on the delivery point.
rts.hs9 For 9-digit ZIP Code lookups (ZIP+4). This file is based on a ZIP+4.
This is possible only when the addresses for that ZIP+4 are for all res-
idences or for no residences.
Chapter 6: Residential Delivery Indicator (RDI) 119

Enable RDI processing
The RDI implementation doesn’t require any new functions in the ACE Library
API. The only change to the library is the addition of values in ace.h.
To perform RDI processing in ACE Library, set the following options:
1. Include the new value ACE_MODE_ENABLE_RDI, when calling
ace_get_mode() and ace_set_mode().
2. Include the path and file name for the values ACE_DIR_RDI when calling
ace_set_file() and ace_get_file().
3. Include the new component ACE_RDI, when calling ace_get_component()
What about ACE’s If you use ACE Library’s configuration file, you can also benefit from RDI
configuration file? functionality. Through AceAux.cfg you can control both the
ACE_MODE_ENABLE_RDI and ACE_DIR_RDI components.
RDI output For RDI, ACE uses a single output component, whose value is always one
component character in length. The RDI component is populated only when the option within
the execution block is enabled.
Library Length Description

component
ACE_RDI 1 This field contains the RDI value that consists of one of
the following values:
Y The address is for a residence.
N The address is not for a residence.

Chapter 7:
Mover ID for NCOALink
This section contains details about the Mover ID-specific functions you’ll use to
set up Mover ID processing.
In addition to the Mover ID-specific functions described in this appendix, you
also need to call ace_get_component, ace_set_mode(), and ace_set_file() when
setting up Mover ID processing. See “ace_get_component(), ace_get_source()”
on page 34, “ace_set_file(), ace_get_file(), ace_get_z4dirno()” on page 52, and
“ace_set_mode(), ace_get_mode()” on page 56 for details about those functions.
About Mover ID With ACE Library’s Mover ID functionality, you can perform move-updating by
accessing the USPS NCOALink directories. For more information about Mover
ID and NCOALink, see your Mover ID User’s Guide for NCOALink.
Contact the USPS’s NCOA department about obtaining an exception to their 100-
record rule. The USPS requires that your list have a minimum of 100 unique
records when performing NCOALink processing. You are responsible for
meeting this requirement, according to your agreement with the USPS.
Chapter 7: Mover ID for NCOALink 121

ace_mvid_set_info()
Synopsis char ace_mvid_set_info(three parameters)

int setting_ID Input setting identifier. See table below.
char* setting Input: desired setting
Description Call ace_mvid_set_info() to set up NCOALink processing.
Symbol for setting_ID Symbol for Length Description

setting
ACE_MID_MATCH_LOGIC B n/a Choose the types of moves that you want to pro-
I cess:
C ! B means business moves only. This ignores fam-
S ily and individual moves.

R ! I means individual moves only. This ignores
family and business moves.
! C means individual and business only. This
ignores family moves.
! S means “standard,” or all types of moves will
be processed.
! R means residential, or all family and individual
moves. This ignores business moves.
ACE_MID_MODE COA n/a ! COA. You’re processing this job to update it with
STATS the latest address data.
RETCODE ! STATS. You’re processing this job to analyze sta-
tistics, such as the number of records in your list
that have updated addresses and the number of
moves of each type. When you choose Stats, you
do not get move-updated addresses.
! RETCODE. You’re processing this job for infor-
mational purposes. When you choose Retcode
(return code), and you post to the
ACE_APM_RET_CODE output component, you
can see the return codes, which further explain if
matching records were found in the NCOALink
directories, and why or why not. With this option,
you do not get move-updated addresses.

setting
ACE_MID_PROCESSING_CAT EMP n/a Specify your reason for using NCOALink:

TRAIN ! Emp Train. You’re processing this file as part of
INT DB employee training.
TST ! Int Db Tst. You’re testing with a licensee-owned
MKTG database.
TEST ! Mktg Test. You’re testing with external customer
PROD RUN lists.
STAGE I ! Prod Run. You’re processing the mailing list to
STAGE II update it before a mailing.
SYS TEST ! Stage I and Stage II. You’re testing the matching
performance against a USPS test file. The USPS
scores the Stage II test file. Choose Stage I or Stage
II only if you are processing a USPS test file. See
your Mover ID User’s Guide for more information.
! Sys Test. You’re processing this file as part of sys-
tem testing, such as loading of USPS file updates.
ACE_MID_NUM_DATA_MONTHS n/a 1 or 2 Use this setting to make ACE ignore change-of-
address data older than the specified number of
months. For example, enter 12 to use change-of-
address data that has a move-effective date within the
last 12 months.
If you are an end user or limited service provider,
enter a value from 6 to 18. If you’re a full service pro-
vider, enter a value from 6 to 48.
ACE_MID_PROC_FIRST_CLASS Y Indicate the mail classes that you’re processing by
ACE_MID_PROC_PER_MAIL N entering Y for those you’re processing and N for those
ACE_MID_PROC_STD_MAIL you’re not.
ACE_MID_PKG_SRV_MAIL
ACE_MID_LIST_NAME n/a 30 Enter the name of this list. You can name the list what-
ever you like, up to 30 characters. If this list is a mas-
ter house list or your only mailing list, you might
consider entering your company name here.
The name you enter here appears in the log files.
ACE_MID_PROCESSES_LIST n/a 512 The USPS requires information about all processes
used in obtaining your final data results. In particular,
the USPS wants to know if you performed any USPS
processes, such as CASS, DPV, RDI, and NCOALink
processing. If you’ve performed these processes
through ACE, ACE keeps track of this information for
you in the Mover ID Summary. If you’ve performed
any additional process on this data, using software
other than ACE, enter it by using this symbol.
ACE_MID_BUYER_CO n/a 30 If the list was processed for rent, sale, or lease,
enter the name of the company or individual who
bought the list.
ACE_MID_MAILING_ZIP n/a 5 Enter the ZIP Code of the Business Mail Entry Unit
(BMEU) or post office where the mail will be sub-
mitted for mailing.

setting
ACE_MID_PREPROC_PERFORMED N 1 Indicate whether you processed or will process this

Y data before performing NCOALink processing.
D N No pre-processing
P Y Yes, but with no data changes
B D Yes, with non-postal data changes
P Yes, with postal data changes only
B Yes, with postal and non-postal data changes
ACE_MID_CONC_PROC_PERFORMED N 1 Indicate whether you processed or will process this
Y data in some other way while performing NCOAL-
D ink processing.
P N No concurrent processing
B Y Yes, but with no data changes
D Yes, with non-postal data changes
ACE_MID_POSTPROC_PERFORMED N 1 Indicate whether you will process this data after
Y performing NCOALink processing.
D N No post-processing
P Y Yes, but with no data changes
B D Yes, with non-postal data changes
ACE_MID_STD_OUTPUT_RETURNED Y 1 Y All required NCOALink output was returned to
N the client.
B N The NCOALink output was returned to the cli-
ent after other changes.
B The NCOALink output was returned to the cli-
ent unchanged, and the required output data was
also returned.
ACE_MID_ADDITIONAL_NOTES A 1 Indicate if the customer submitted a written request
for an extension. If there was no request for exten-
sion, don’t set this.
ACE_MID_PAF_SIGNER_NAME n/a 50 Enter the name of the person signing this PAF.
ACE_MID_PAF_SIGNER_TITLE n/a 50 Enter the job title of the person signing this PAF.
ACE_MID_DATE_CUST_SIGNED_PAF n/a n/a Enter the date that the customer signed the PAF. Use
the yyyy/mm/dd date format.
ACE_MID_PAF_TYPE I n/a Specify the reason for completing your current PAF:
M I Initial. This is the first PAF you’re completing to
R become authorized to process addresses for this
particular customer.
M Modified. You’re completing a new PAF because
some information on your old one changed.
R Renewal. You’re completing a new PAF because
your old one is expiring.

setting
ACE_MID_PAF_PARENT_CO n/a 50 If the list owner’s company is owned by another com-

pany (a “parent company”), enter the parent com-
pany’s name here.
ACE_MID_PAF_ALT_CO_NAME n/a 50 If the list owner’s company is also known by another
name, enter that alternate name here.
ACE_MID_DATE_LICENSEE_SIGNED_ n/a n/a Enter the date that the licensee signed the PAF. Use
PAF the yyyy/mm/dd date format.
ACE_MID_CACHE_MB AUTO n/a AUTO. ACE loads your NCOALink files into system
or a number memory. ACE determines the amount of memory to
as a text use based on the available memory, the size of the
string files, and the extent to which caching the files will
improve processing time.
Number. ACE loads your NCOALink files into system
memory based on the number of megabytes (MB) you
specify in this string.
ACE_MID_LIC_ID n/a 4 The licensee performs NCOALink processing.
The licensee ID is the NCOALink licensee’s identifi-
cation number, assigned by the USPS. It’s exactly
four characters long.
The licensee information will appear in the PAF log
and Mover ID Summary report.
Both the licensee ID and name are available on the
license agreement from the USPS.
ACE_MID_HIGH_MATCH_RATE_DESC A 1 The USPS wants to distinguish between files that have
S a legitimate reason for a high percentage of
R NCOALink matches and files that are fraudulently
used to create mover lists.
Legitimate reasons for high match rate:
Link
! A. An ANK -processed file contains records for
people who have moved, but you don’t yet have
their new address. This option is available only to
full service providers.
! S. If you’re performing Stage I or Stage II testing,
be sure that the processing category is set to Stage
also.
! R. A “return mail file” contains records for mail
that was returned to sender.
ACE_MID_ALT_PAF_INDICATOR Y 1 Y= Alternate PAF used
N N= No alternate PAF was used
ACE_MAILER_PAF_SIGNEE_COMPANY n/a 40 Company website address of the person signing the
_WEBSITE PAF.
ACE_MAILER_PAF_SIGNEE_EMAIL n/a 64 Email address of person signing the PAF.
ACE_MID_CONTACT_COMPANY_ n/a 40 Website address of broker or list administrator. Set
WEBSITE this with ace_mvid_set_contact_info( ).

ace_mvid_set_contact_info()
Synopsis char ace_mvid_set_contact_info(three parameters)

int contact_index Input: number 1-100.
int setting_ID Input: setting identifier. See table below.
Description Call ace_mvid_set_contact_info() to enter contact information for any brokers

or list administrators involved in your NCOALink processing.
The contact_index is a unique identifier about which contact is included.
Information associated with the first contact should use contact_index 1, the
second contact should use contact_index 2, and so on.

setting
ACE_MID_CONTACT_TYPE BROKER n/a Indicate whose contact information you are pro-
LISTADMIN viding.
A broker directs business to the service provider;
a list administrator stores and maintains address
lists.
ACE_MID_CONTACT_ID n/a 6 Enter a unique ID number for the broker or list
administrator. You assign the ID number.
ACE_MID_CONTACT_SIC n/a 6 Enter the broker’s or list administrator’s numeric
Standard Industrial Classification (SIC) code,
which identifies the business that they engage in.
For more information, see:
http://www.census.gov/epcd/www/sic.html
ACE_MID_CONTACT_NAME n/a 50 Enter the broker’s or list administrator’s:
ACE_MID_CONTACT_ADDRESS 12 ! name
ACE_MID_CONTACT_CITY 50 ! complete address
ACE_MID_CONTACT_STATE 28
! phone number
ACE_MID_CONTACT_ZIP 2
ACE_MID_CONTACT_ZIP4 5
ACE_MID_CONTACT_PHONE 4
10
ACE_MID_CONTACT_LEVEL n/a 1-2 Indicate your degree of separation from this contact.
For example, the contact from whom you received
the list would have a contact level of 1. If your con-
tact received the list from a different broker, then
that broker would have a contact level of 2. You can
have up to 99 contacts.
ACE_MID_CONTACT_DATE_SIGNED n/a n/a Enter the date when this contact signed the PAF. Use
_PAF the yyyymmdd date format.
You must set the date signed for every contact
involved.

ace_set_mailer_info()
Synopsis char ace_set_mailer_info(three parameters)

int setting_ID Input setting identifier. See table below.
Description Call ace_mvid_set_info() to set up NCOALink processing.
Symbol for setting_ID Symbol Length Description

for
setting
ACE_MAILER_IMB_ID n/a 6 or 9 A unique 6 or 9-digit numeric code assigned by the USPS based
on the licensee’s mail volumes.
ACE_MAILER_LIC_NAME n/a 30 Enter the name of the NCOALink licensee. The licensee performs
NCOALink processing. The licensee information appears in the
PAF log and Mover ID Summary report. Both the licensee ID and
name are available on the license agreement from the USPS.
ACE_MAILER_LIST_OWNER_SIC n/a 6 Enter the numeric Standard Industrial Classification (SIC), which
identifies what business the list owner engages in. For more infor-
mation, see http://www.census.gov/epcd/www/sic.html.
ACE_MAILER_LIST_OWNER_ID n/a 6 Customer/List ID is a unique ID assigned by the licensee to iden-
tify the list owner (customer).
If the licensee does not have a naming scheme in place for cus-
tomer/lists, the 6 digits could be made up of:
- First 3 digits: Customer name/identifier
- Last 3 digits: List name/identifier
The Customer/List ID is required for limited and full service pro-

viders. End users may leave it blank.
ACE_MAILER_CUST_CO n/a 50 The customer is the person or company for whom you are per-
ACE_MAILER_CUST_ADDRESS 50 forming NCOALink processing.
ACE_MAILER_CUST_CITY 28 If you’re a limited or full service provider, or an end user, enter
ACE_MAILER_CUST_STATE 2 the customer’s address and telephone number. End users may
ACE_MAILER_CUST_ZIP 5 leave these fields blank.
ACE_MAILER_CUST_ZIP4 4 The customer information appears in the Mover ID Summary and
ACE_MAILER_CUST_PHONE 10 log files.
12
ACE_MAILER_PROC_FREQ n/a 2 This 2-digit number (from 1 to 52) indicates how many times per
year the list is processed with NCOALink.
If the list owner has other lists processed by the NCOALink lic-
ensee at different frequencies, enter 99.
ACE_MAILER_DATE_RECEIVED n/a n/a Enter the date when you received the list. Use the yyyy/mm/dd
format. If you’re an end user, you may leave this blank.
ACE_MAILER_DATE_RETURNED n/a n/a Enter the date when the list will be returned to the customer. Use
the yyyy/mm/dd format. If you’re an end user, leave this blank.

Symbol for setting_ID Symbol Length Description
for
setting
ACE_MAILER_LOG_FILE_PATH n/a n/a Indicate where the NCOALink log files should be produced. ACE
determines the file names during processing, as the USPS
requires. This directory must exist and must be writable.
It’s very important that you use the same path for all jobs. If you
have multiple clients, use the same log file directory for all clients
so that the log files are combined.

ace_mvid_ncoal_header()
Synopsis char ace_mvid_ncoal_header(three parameters)

ADDR_HANDLE ah;Input: address handle
char *input Input: A pointer to an array of at least 1001 characters.
It should contain the header record of a Stage I or Stage
II NCOALink Test Client Input File.
char *output Input: A pointer to an array of at least 1001 characters.
It will be populated with the completed header record
of a Stage I or Stage II NCOALink Test Client Output
File.
Description This function adds some information to the input header record to create the
output header record.
Call ace_mvid_ncoal_header() to build your header record, which is needed for
the stage 1 or stage 2 output file. Call ace_mvid_ncoal_header() after you’ve
processed all the data records. Read the input header record (300 bytes) into a
string and pass it in as the input_buffer. It will copy over the input record data and
add the output fields, putting the completed header record in output_buffer (1000
bytes).
Save the header record when you first read it, write it as-is to the output file, and
then do the data loop. Allocate a 1,000-byte buffer, call the function to populate
it, seek back to the beginning of the output file, and overwrite the header record.

ace_mvid_report_init()
Synopsis int ace_mvid_report_init(three parameters);

ADDR_HANDLEah_id, Input: The address handle used to do
Mover ID processing.
char *filename, Input: The path and file name where the
report is to be created.
int existing_report, Input: Whether an existing report should
be appended to (ACERPT_APPEND) or
replaced (ACERPT_REPLACE).
Description Call ace_mvid_report_init() to initialize the Mover ID Summary report. Report

data will be copied from the address handle where possible. This includes all
move-update statistics. Call this function after using the address handle to
perform Mover ID processing.

ace_mvid_report_set_data()
Synopsis int ace_mvid_report_set_data(three parameters);

ADDR_HANDLE ah_id, Input: The address handle used to do Mover ID
processing.
int setting_id, Input: An ID specifying what data is being set.
See the tables starting in “Setting ID values for
ace_mvid_report_set_data()” on page 131.
char *setting, Input: The data to be set, presented as an
ASCII string.
Description Call ace_mvid_report_set_data() to provide data for the report. This can include
data not available from the address handle (such as the job-file name if
applicable) or values to overwrite such data. Call this function after
ace_mvid_report_init().
Setting ID values for ace_mvid_report_set_data()

The following values are not available from the address handle, so these should
be set through ace_mvid_report_init():
Setting Description
ACE_RPT_SETTING_LONG_PAGE_WIDTH Width of page in columns.

ACE_RPT_SETTING_LONG_PAGE_LENGTH Length of page in rows.
ACE_RPT_SETTING_LONG_LEFT_MARGIN Left margin in columns.
ACE_RPT_SETTING_LONG_RIGHT_MARGIN Right margin in columns.
ACE_RPT_SETTING_LONG_BOTTOM_MARGIN Bottom margin in rows.
ACE_RPT_SETTING_LONG_TOP_MARGIN Top margin in rows.
ACE_RPT_SETTING_STRING_CASE Case. U for upper, L for lower, M for mixed. Default is M.
ACE_RPT_SETTING_STRING_REPORT_INIT Printer init sequence.
ACE_RPT_SETTING_STRING_REPORT_RESET Printer reset sequence.
ACE_RPT_DATA_STRING_HEADER_LINE_1 Header line 1.
ACE_RPT_FIELD_STRING_JOB_FILE Name of the job file.
ACE_RPT_FIELD_STRING_JOB_DESC Job description.
ACE_RPT_FIELD_STRING_JOB_OWNER Job owner.
ACE_RPT_FIELD_STRING_MID_AUTO Auto-update on? (Y/N).

Setting Description
ACE_RPT_FIELD_STRING_SUPPRESS_PRODUCT Suppress ACE name from report (Y/N).

ACE_RPT_FIELD_STRING_INPUT_FILE Name of input file processed.
ACE_RPT_FIELD_LONG_INPUT_RECORDS Number of records in input file.
ACE_RPT_FIELD_LONG_DELETED_RECORDS Number of records flagged as deleted.
ACE_RPT_FIELD_LONG_RECORDS_PASSED_FILTER Number of records that passed an input filter.
ACE_RPT_FIELD_LONG_Z4CHANGE_RECORDS Number of records effected by z4change.
Overwriting address The following fields are defaulted based on values from the address handle, and
handle values don’t need to be set with ace_mvid_report_init() unless you need to overwrite
those values:
Setting Description
ACE_RPT_FIELD_LONG_DPV_CONFIRMED Number of records confirmed by DPV.

ACE_RPT_FIELD_LONG_DPV_NOT_CONFIRMED Number of records not confirmed by DPV.
ACE_RPT_FIELD_LONG_CMRA_CONFIRMED Number of records identified as CMRA by DPV.
ACE_RPT_FIELD_LONG_DPV_SEC_NOT_CONFIRMED Number of records validated by DPV but with
invalid secondary.
ACE_RPT_FIELD_LONG_DPV_SEC_MISSING Number of records validated by DPV but missing
secondary.
ACE_RPT_FIELD_LONG_MVID_IND_MATCHES Number of individual matches made by Mover ID.
ACE_RPT_FIELD_LONG_MVID_FAM_MATCHES Number of family matches made by Mover ID.
ACE_RPT_FIELD_LONG_MVID_BUS_MATCHES Number of business matches made by Mover ID.
ACE_RPT_FIELD_LONG_MOVE_SUM_ZIP4_ST Number of moves to ZIP4 street addresses.
ACE_RPT_FIELD_LONG_MOVE_SUM_LACS_ADDRS Number of moves to LACS addresses.
ACE_RPT_FIELD_LONG_MOVE_SUM_ZIP4_PB Number of moves to postal boxes addresses.
ACE_RPT_FIELD_LONG_MOVE_SUM_ADDR_GEO_MATCH Number of moves address-level GEO matched.
ACE_RPT_FIELD_LONG_MOVE_SUM_ZIP4_HR Number of moves to ZIP4 highrises.
ACE_RPT_FIELD_LONG_MOVE_SUM_CENT_GEO_MATCH Number of moves centroid GEO matched.
ACE_RPT_FIELD_LONG_MOVE_SUM_ZIP4_RR Number of moves to ZIP4 rural route addresses.
ACE_RPT_FIELD_LONG_MOVE_SUM_ZIP4_FM Number of moves to firm addresses.
ACE_RPT_FIELD_LONG_MOVE_SUM_RDI_RESIDENCES Number of moves to residential addresses.
ACE_RPT_FIELD_LONG_MOVE_SUM_ZIP4_GD Number of moves to general delivery addresses.
ACE_RPT_FIELD_LONG_MOVE_SUM_ZIP4_ML Number of moves to military addresses.
ACE_RPT_FIELD_LONG_MOVE_SUM_ZIP4_UN Number of moves to unique ZIP codes.
ACE_RPT_FIELD_LONG_MOVE_SUM_QSS_HRD Number of moves to highrise defaults (for QSS sec-
tion).

Setting Description
ACE_RPT_FIELD_LONG_MOVE_SUM_QSS_RRD Number of moves to rural route defaults (for QSS

section).
ACE_RPT_FIELD_LONG_MOVE_SUM_QSS_HR Number of moves to highrises (for QSS section).
ACE_RPT_FIELD_LONG_MOVE_SUM_QSS_RR Number of moves to rural routes (for QSS section).
ACE_RPT_FIELD_LONG_MOVE_SUM_EWS_MATCH_COUNT Number of moves to addresses flagged by Early
Warning System.
ACE_RPT_FIELD_LONG_MOVE_SUM_QSS_LACS Number of moves to LACS addresses (for QSS sec-
tion).
ACE_RPT_FIELD_LONG_MOVE_SUM_DPV_CONFIRMED Number of moves to DPV confirmed addresses.
ACE_RPT_FIELD_LONG_MOVE_SUM_CMRA_CONFIRMED Number of moves to CMRA confirmed addresses.
ACE_RPT_FIELD_LONG_MOVE_SUM_DPV_NOT_CONFIRMED Number of moves to addresses unconfirmed.
ACE_RPT_FIELD_LONG_MOVE_SUM_SEC_NOT_CONFIRMED Number of moves to addresses confirmed but with
invalid secondaries.
ACE_RPT_FIELD_LONG_MOVE_SUM_SEC_MISSING Number of moves to addresses confirmed but miss-
ing secondaries.
ACE_RPT_FIELD_LONG_MVID_MATCHES Total number of Mover ID matches.
ACE_RPT_FIELD_LONG_NOSTAT_CONFIRMED
ACE_RPT_FIELD_LONG_NOSTAT_SEC_MISSING
ACE_RPT_FIELD_LONG_NOSTAT_SEC_NOT_CONFIRMED
ACE_RPT_FIELD_LONG_VACANT_CONFIRMED
ACE_RPT_FIELD_LONG_VACANT_SEC_MISSING
ACE_RPT_FIELD_LONG_VACANT_SEC_NOT_CONFIRMED
ACE_RPT_FIELD_LONG_ZIP4_ST Total number of addresses moved from ZIP+4 street
addresses.
ACE_RPT_FIELD_LONG_ZIP4_PB Total number of addresses moved from postal box
addresses.
ACE_RPT_FIELD_LONG_ZIP4_HR Total number of addresses moved from highrise
addresses.
ACE_RPT_FIELD_LONG_ZIP4_RR Total number of addresses moved from rural route
addresses.
ACE_RPT_FIELD_LONG_ZIP4_FM Total number of addresses moved from firm
addresses.
ACE_RPT_FIELD_LONG_ZIP4_GD Total number of addresses moved from general
delivery addresses.
ACE_RPT_FIELD_LONG_ZIP4_ML Total number of addresses moved from military
addresses.
ACE_RPT_FIELD_LONG_ZIP4_UN Total number of addresses moved from unique
addresses.

Settings for multiple If your application produced multiple output files, the report can produce a
output files separate section for each output file. For each output file, use the following
setting IDs to specify the output file that was created:
Setting Description
ACE_RPT_FIELD_STRING_OUTPUT_FILE Name of output file produced during processing (not the report file).
ACE_RPT_FIELD_STRING_OUTPUT_FILTER Filter used in producing output file.

ace_mvid_report_set_retcode_count()
Synopsis int ace_mvid_report_set_retcode_count(three parameters);

ADDR_HANDLE ah_id, Input: The address handle used to do Mover ID
processing.
int index, Input: An ID specifying what data is being set.
Values: 0 to
(NCOA_RETURN_CODE_MAX-1).
long setting, Input: The number of records resulting in the
NCOA/Link return code specified.
Description Call ace_mvid_report_set_retcode_count after calling ace_mvid_report_init()

to overwrite the counts on the address handle. This is only necessary when
passing in data for a per-output-file section.

ace_mvid_report_open()
Synopsis int ace_mvid_report_open(one parameter);

ADDR_HANDLE ah_id Input: The address handle used to do
Mover ID processing.
Description Call ace_mvid_report_open() to open the report after calling

ace_mvid_report_init(), optionally after calling ace_mvid_report_set_data().

ace_mvid_report_job_section()
Synopsis int ace_mvid_report_job_section(one parameter);

ADDR_HANDLE ah_id Input: The address handle that has been used to
do Mover ID processing.
Description Call ace_mvid_report_job_section() to produce the overall level section of the

report. If your application doesn’t need per-file sections, this will do all the
reporting you need.

ace_mvid_report_file_section()
Synopsis int ace_mvid_report_file_section(one parameter);

ADDR_HANDLE ah_idInput: The address handle used to do Mover ID
processing.
Description Call ace_mvid_report_file_section() to produce the per-output-file level section

of the report. This is optional.

ace_mvid_report_term()
Synopsis int ace_mvid_report_term(one parameter);

ADDR_HANDLE ah_id Input: The address handle used to do Mover ID
processing.
Description Call ace_mvid_report_term() to close and terminate the report. Call this
function after calling ace_mvid_report_job_section(), optionally after calling
ace_mvid_report_file_section().

Chapter 8:
LACSLink
What is LACSLink? The USPS requires LACSLink processing for CASS-certification. LACSLink
updates rural-route addresses to street-name addresses. These “911” conversions
make it easier for police, fire, ambulance, and postal personnel to locate a rural
address. LACSLink also converts addresses when streets are renamed or post
office boxes renumbered.
LACSLink uses the same USPS “Link” technology that NCOALink uses. This
technology ensures that the data remains private and secure, and at the same time
gives you easy access to the data.
Like NCOALink, LACSLink is an integrated part of address processing; it is not an
extra step. To obtain the new addresses, you must already have the old address
data.
LACSLink replaces the USPS’s Locatable Address Conversion System (LACS).
Find more information about ACE’s LACSLink option, see the ACE User’s
Guide.
Chapter 8: LACSLink 141

Overview
Who needs LACSLink The USPS requires all NCOALink full service providers to offer LACSLink
processing, but full service providers do not have to run LACSLink at all times.
LACSLink is optional for other users, including NCOALink limited service
providers and NCOALink end users.
How LACSLink works LACSLink provides a new address when one is available. The basic process that
ACE follows for LACSLink processing is:
1. ACE standardizes the input address.
2. ACE looks for a matching address in the LACSLink data.
3. If a match is found, ACE outputs the LACSLink converted address and other
LACSLink information. See “LACSLink output components” on page 145 for
more information.
Conditions for Addresses are passed into LACSLink processing when:

LACSLink processing
! The address is found in the ZIP+4 directory. The address was flagged as a
LACS convertible record within the ZIP+4 directory.
! The address is found in the ZIP+4 directory. Rural route or highway contract
default assignment was made, but the record wasn’t flagged as LACS
convertible.
! The address is not found in the ZIP+4 directory, but the record contains
enough information to be sent into LACSLink.
Example Here is an example of a rural address that is converted through LACSLink.
Original address: After LACSLink conversion:
RR 2 BOX 204 463 SHOWERS RD

DU BOIS PA 15801 DU BOIS PA 15801-6667

Install LACSLink and its directories
For information about installing LACSLink, refer to the System Administrator’s

Guide. As part of the ACE installation, LACSLink and the supporting files are
installed in c:\pw\lacslink (Windows) or /postware/lacslink (UNIX).
LACSLink directory files The LACSLink directory files require about 600 MB of additional hard drive
space. Copy the following directory files from the directory CD to the pw\
lacslink\ or postware/lacslink/ directory:
! lacsw.txt
! lacsx.txt
! lacsy.ll
! lacsz.ll
Important: The LACSLink directories must reside on the hard drive in the
!
same directory as the LACSLink supporting files. Do not rename any of the
files. LACSLink will not run if the file names are changed.
Directory expiration LACSLink directories expire in 105 days. LACSLink directories must have the
and updates same date as the other directories that you are using from the National Directories
CD.

Performing LACSLink processing
You must set the following functions to perform LACSLink processing:

! Specify the LACSLink directory location by calling ace_set_file() with the
value of ACE_DIR_LACSLINK.
! Enable LACSLink processing by calling ace_set_mode() with
ACE_MODE_ENABLE_LACSLINK.
! Set the required Customer & USPS Licensee Information parameters (listed
below in “Required Customer & USPS Licensee Information parameters” on
page 144).
Required Customer & Set the following required customer information fields using
USPS Licensee ace_set_mailer_info():
Information
parameters ACE_MAILER_CUST_CO
ACE_MAILER_CUST_ADDRESS
ACE_MAILER_CUST_CITY
ACE_MAILER_CUST_STATE
ACE_MAILER_CUST_ZIP
ACE_MAILER_CUST_ZIP4
ACE_MAILER_LOG_FILE_PATH
For more information about the ace_set_mailer_info() function, see
“ace_set_mailer_info()” on page 127.
Verification Error If your job setup does not contain the required USPS information, ACE issues a
verification error. Use ace_get_error_info() or ace_get_error_info_return() to
obtain more information about the verification error.
ACE issues one error per run based on the first parameter it finds that is required
but not supplied.

LACSLink output components
LACSLink converted addresses will be output to standard output components

when you use ace_get_component() with ACE_NEW. In addition, you can view
LACSLink information by using the following output components.
The following output fields are available for reporting LACSLink processing
results. To post information to these fields, you must activate LACSLink
processing by calling ace_set_mode() with the
ACE_MODE_ENABLE_LACSLINK setting.
ACE_LACSLINK_QUERY 50 This field returns the pre-conversion address, populated only when LACSLink is
turned on and a LACSLink lookup was attempted. This address will be in the
standard Pub. 28 format, except that when both a unit designator and secondary
unit are present the unit designator will be replaced by the character “#”.
Blank No LACSLink lookup attempted.
ACE_LACSLINK_RETCODE 2 The following values are available as the return codes for the matches in
LACSLink processing:
A LACSLink record match, and a converted address is provided in the
address data fields.
00 No match, and no converted address.
14 Found LACSLink record, but couldn’t convert the data to a deliverable
address.
92 LACSLink record matched after dropping the secondary number from input
address. A converted address is provided in the address data fields. Note:
If you want to flter on records that are assigned a new address from
LACSLink, you should use the AP.LACSL_Ret codes A and 92.
ACE_LACSLINK_IND 1 This field indicates the status of addresses processed by LACSLink. The follow-
ing values are returned:
Y Address found in LACSLink directories..
N Address looked up with LACSLink but not converted.
F The address was a false-positive.
S A LACSLink conversion was made, but it was necessary to drop the sec-
ondary information.

LACSLink performance
Memory usage Caching LACSLink directories requires approximately 150 MB of memory. Make
sure that your computer has adequate memory available before performing
LACSLink processing.
If you use 150 MB of your system memory to cache the LACSLink

directories, the performance of ACE improves considerably.
ACE does not load the LACSLink directories into your system memory if
LACSLinkprocessing is turned off.
Load into system To load LACSLink directories into system memory, call ace_set_mode() as
memory follows:
ace_set_mode(ah, ACE_MODE_CACHE_LACSLINK_DIRS, TRUE);
If you’re caching the LACSLink directories, you must also specify whether or not
you want to stop processing if insufficient memory is available. To stop
processing when insufficient memory is available, call ace_set_mode() as
follows:
ace_set_mode(ah, ACE_MODE_ABORT_ON_CACHE_ERROR, TRUE);

LACSLink locking
False-positive addresses are included with the LACSLink directories as a security

precaution. If ACE detects one of these false-positive addresses during
processing, it generates a false-positive log file, and discontinues LACSLink
processing.
Note: Unlike ACE Views and Job File, ACE Library does not check whether
or not you are a limited or full service provider and locks anytime a false
positive is encountered.
If you perform batch processing and encounter a false-positive address, call
ace_get_lacs_msg() to retrieve the locking information required by customer
support to unlock LACSLink. For information about ace_get_lacs_msg( ), see
page 149.

LACSLink false positive log
ACE generate a false-positive log file anytime it encounters a false positive,

regardless of how your job is set up. For each mailing list that contains a false
positive record, ACE creates a log file. If multiple false positives exist within one
mailing list, ACE writes them all to the same log file.
When ACE generates the log file, NCOALink L/FS providers are required to send
that log file to the USPS. This does not apply to end users who have DSF2
disabled in their jobs.
Important: L/FSPs must not process additional lists for a customer that has
!
encountered a false-positive record. The mailing list cannot be released until
the USPS approves it.
Location for log files You set the location for this log file using ACE_MAILER_LOG_FILE_PATH in
ace_set_mailer_info.
Retrieve locking If you are not an NCOALink L/FSP, and you encounter a false-positive address
information during processing, contact SAP BusinessObjects Customer Support with locking
information. To obtain this information, call ace_get_lacs_msg(). For details see
“ace_get_lacs_msg()” on page 149. Find instructions for LACSLink unlocking in
the ACE User’s Guide.
If you perfom batch processing and encounter a false-positive address, ACE
continues to process without LACSLink until the next ace initialization sequence
or an ace_open() call is made after the lock. At that point ace_open() fails.

ace_get_lacs_msg()
Synopsis int ace_get_lacs_msg(three parameters);

int line_number; Input: number of message lines
char *message_text; Output: retrieved data
Description Use ace_get_lacs_msg() to retrieve the message describing the current LACSLink
locking incident. This message includes the text that the USPS requires
LACSLink-enabled software to present to users when LACSLink locks.
After calling ace_get_component() to retrieve the component
ACE_LACSLINK_IND, check to see if the result is F, which indicates that the
current record caused a lock. In this situation, call ace_get_lacs_msg() to retrieve
each line of the lock message.
We recommend using a FOR loop to call ace_get_lacs_msg() with line_number
values from 1 to ACE_LACS_MSG_LINES to receive the entire message. The
constant ACE_LACS_MSG_LINES defines the number of lines in the error
message.
1. ACE_LACS_ALERT_MSG_NO
2. ACE_LACS_LOCK_CODE_MSG_NO
3. ACE_LACS_LOCK_ADDR_MSG_NO_START
through
ACE_LACS_LOCK_ADDR_MSG_NO_END
4. ACE_LACS_USPS_MSG_NO_START
through
ACE_LACS_USPS_MSG_NO_END

You can retrieve specific parts of the alert text by calling line numbers separately:
Symbol for line_number values Length Message section
ACE_LACS_MSG_LINES 21 Total number of lines

of the entire message.
ACE_LACS_MSG_LEN 81 Width of message, in
characters.
ACE_LACS_ALERT_MSG_NO 1 The alert message.
ACE_LACS_LOCK_CODE_MSG_NO 3 The lock code.
ACE_LACS_LOCK_ADDR_MSG_NO_START 6 The lock address.
ACE_LACS_LOCK_ADDR_MSG_NO_END 9
ACE_LACS_USPS_MSG_NO_START 11 The USPS lock text.
ACE_LACS_USPS_MSG_NO_END 22
Returns This function returns ACE_OK or ACE_ERROR.

Chapter 9:
SuiteLink
About SuiteLink With SuiteLink you can build accurate and complete addresses by adding suite
numbers to high-rise business addresses. With the secondary address information
added to your addresses, more of your pieces are sorted by delivery sequence and
delivered with accuracy and speed.
Chapter 9: SuiteLink 151

How does SuiteLink work?
SuiteLink is a USPS directory that contains addresses, company names, ZIP+4

information and secondary address designators (suite numbers) for high-rise
buildings. ACE can use the data in SuiteLink to add suite numbers to an address.
ACE matches a company name, a known high-rise address, and the CASS-
certified ZIP+4 in your database to data in SuiteLink. When there is a match, ACE
creates a complete business address that includes the suite number..
Note: ACE uses the firm information from the PW.FIRM field. If there is
nothing in the ACE_FIRM field, ACE checks any multiline input fields that
are present (for example, ACE_ILINE1-ILINE12). This information is
generally found in the output fields ACE_EXTRA9 and ACE_EXTRA10
fields.
Look at the ACE_IFIRM field to see what firm ACE used.
Example This example shows a record that is processed through SuiteLink, and the output
record with the assigned suite number.
! The input record contains:
! Firm name
! Known high-rise address
! CASS-certified ZIP+4
! SuiteLink directory contains:
! Firm names within the highrise
! Suite numbers within the highrise
! Output record contains:
! Correct suite number
ACE input record SuiteLink directory ACE output
Poplar Auto Poplar Medical Sales Ste212 Poplar Auto

987 Main St Poplar Auto Sales Ste 214 987 Main St Ste 214
12345-6789 Poplar Computers Ste216 12345-6789
Wilson Law Firm Ste 218
Boyce’s Kayaks Ste 220
SuiteLink directory The SuiteLink directory is distributed monthly by the USPS. You must use the
files SuiteLink directory with a ZIP+4 directory labeled for the same month. For
example, the December 2008 SuiteLink directory can be used with only the
December 2008 ZIP+4 directory.
Non-CASS mode: SuiteLink is disabled if you are running your job in non-
!
CASS mode.
You cannot use a SuiteLink directory that is older than 60 days based on its release
date. ACE warns you 15 days before the directory expires. As with all directories,
ACE won’t process your records with an expired SuiteLink directory.

Set up SuiteLink processing
Enable SuiteLink and Use these ACE_Mode file identifiers to enable SuiteLink and to set up caching.
cache directory
Use these with the ace_set_mode() and ace_get_mode() functions. (For complete
information about these functions, see page “ace_set_mode(), ace_get_mode()”
on page 56).
Symbol for mode_ID Default Description

modes
ACE_MODE_ENABLE_SUITELINK FALSE Enables SuiteLink in ACE

Library.
ACE_MODE_CACHE_SUITELINK_DIRS FALSE Enables caching of the
SuiteLink directories to the
ACE Library.
Locations for SuiteLink SuiteLink and NCOALink use the same support files. Use these directory file
directory files identifiers to set up the the directories for both NCOALink and SuiteLink.
Use these with the ace_set_file(), ace_get_file(), and ace_get_file_date()
functions. (For complete information about these functions, see page
“ace_set_file(), ace_get_file(), ace_get_z4dirno()” on page 52.)
Symbol for directory_ID Description
ACE_DIR_SUITELINK The SuiteLink directory location (path only).

ACE_DIR_NAME_PARSING_FILES The NCOALink and SuiteLink directory
locations (path only).
Chapter 9: SuiteLink 153

SuiteLink output fields
The following SuiteLink output fields are available.
Library field Length Description
ACE_SUITELINK_ 2 The result of SuiteLink processing.

RETCODE A SuiteLink match—secondary information exists and was assigned to
this record as a result of SuiteLink processing.
00 SuiteLink no match—lookup was attempted but no matching record
could be found.
blank A SuiteLink lookup was not attempted because one of the following
was true:
! The address was not a highrise default according to CASS.
! The address did not contain a firm.
ACE_PRESL_ZIP 5 The ZIP Code that was assigned by ACE before SuiteLink processing.
5-digit ZIP Code The AP.SteLink_RC value is A.
blank No ZIP Code assigned.
ACE_PRESL_ZIP4 4 The ZIP+4 that was assigned by ACE before SuiteLink processing. The ZIP+4
is either for a high-rise default or street default record.
ACE_PRESL_DPBC 2 The numeric 2-digit code for the delivery point barcode that was generated
before SuiteLink processing.
ACE_PRESL_SEC_RANGE up to 8 The secondary range information that existed before SuiteLink processing. If
this is blank, ACE did not assign any secondary information.
ACE_INPUT_FIRM 60 The firm name from your input file that is used only for SuiteLink processing.
ACE matches the contents of this field to SuiteLink data. To see what firm
name SuiteLink used for processing, look at the contents of this field.

Index
A ACE_INPUT_FIRM, 154
ace_ll_browse_ptr structure, 82, 95
ace_3553(), 22
ace_ll_clear_query(), 94
ace_3553_file(), 22
ace_ll_get_query(), 95
ace_3553_hdr, 24
ace_ll_init_query(), 97
ace_browse_ptr structure, 82, 85
ace_ll_init_show(), 98
ace_cfg_close(), 25
ace_ll_query_ptr structure, 82
ace_cfg_open(), 25
ace_ll_set_query(), 99
ace_cfg_read(), 25
ace_ll_show(), 101
ace_clear_query(), 84
ace_ll_term_query(), 102
ace_close(), 49
ace_ll_term_show(), 102
ACE_DIR_NAME_PARSING_FILES, 153
ACE_MODE_CACHE_SUITELINK_DIRS, 153
ACE_DIR_SUITELINK, 153
ACE_MODE_ENABLE_SUITELINK, 153
ACE_DPV_NO_STATS, 113
ace_mvid_ncoal_header, 129
ACE_DPV_VACANT, 114
ace_mvid_report_file_section, 138
ace_evaluate_ah(), 27
ace_mvid_report_init, 130
ace_find_geo_data(), 19, 28, 29
ace_mvid_report_job_section, 137
ace_findf(), 30
ace_mvid_report_open, 136
return codes, 32
ace_mvid_report_set_data, 131
ace_get_cert_ver(), 33
ace_mvid_report_set_retcode_count, 135
ace_get_component(), 15, 34
ace_mvid_report_term, 139
ace_get_county_name(), 35
ace_mvid_set_contact_info, 126
ace_get_error_desc(), 41
ace_mvid_set_info, 122
ace_get_error_info(), 17, 36
ace_ndi(), 47
ace_get_error_info_return(), 36
ace_ndi_file(), 47
ace_get_file(), 52
ace_open(), 49
ace_get_file_date(), 37
ACE_PRESL_DPBC, 154
ace_get_geodir(), 19
ACE_PRESL_SEC_RANGE, 154
ace_get_geodirdate(), 19
ACE_PRESL_ZIP, 154
ace_get_input_length(), 54
ACE_PRESL_ZIP4, 154
ace_get_lastline_components(), 39
ace_query structure, 82, 89
ace_get_lettermatch(), 40
ace_set_acs_info(), 50
ace_get_line(), 15, 55
ace_set_error_rtn(), 17, 51
ace_get_line_name(), 41
ace_set_file(), 52
ace_get_mode(), 56, 153
ace_set_geo_mode(), 19
ace_get_offset(), 42
ace_set_geodir(), 19
ace_get_option(), 60
ace_set_input_length(), 15, 54
ace_get_query(), 85
ace_set_line(), 15, 55
ace_get_revision(), 43
ace_set_mailer_info, 127
ace_get_simil(), 40
ace_set_mode, 153
ace_get_source(), 15, 34
ace_set_mode(), 56
ace_get_stats(), 44
ace_set_option(), 60
ace_get_sugg(), 71
ace_set_password(), 63
ace_get_sugg_cmpt(), 68, 73
ace_set_query(), 89
ace_get_sugg_option(), 80
ace_set_range(), 68, 75
ace_get_suggno(), 68, 74
ace_set_sugg(), 68, 76
ace_get_z4cdir(), 18
ace_set_sugg_filter(), 78, 79
ace_get_z4cdirdate(), 18
ace_set_sugg_option(), 80
ace_get_z4dirno(), 52
ace_set_sugg_rangematch(), 78
ace_getll(), 38
ace_set_sugg_rangewindow(), 78
ace_init(), 45
ace_set_sugg_simil(), 78
ace_init_addr(), 46
ace_set_sugg_style(), 77
ace_init_query(), 87
ace_set_z4c_check_date(), 18, 64
ace_init_show(), 88
ace_set_z4c_dir(), 18
Index 155
ace_set_z4c_mode(), 18 lettermatch test, 40
ace_show(), 91 simil test, 40
ACE_SUITELINK_RETCODE, 154 compilers, 8
ace_term(), 45 components, output, 15, 34
ace_term_addr(), 46 county names
ace_term_query(), 92 ace_get_county_name(), 35
ace_term_show(), 92
ace_z4_zip4_changed(), 18, 65 D
acetest.c, 9 Delivery Point Validation alse-positive log, 112
acs_ll_query_ptr structure, 99 directionals
addr_handle structure query fields, 85, 89
ace_cfg_open(), 25 directories
ace_evaluate_ah(), 27 DPV, 106
ace_get_input_length(), 54 get date, 37
ace_init_addr(), 46 open and close, 49
ace_set_input_length(), 54 set pathname, 52
ace_term_addr(), 46 set working directory, 52
address directory expiration warnings
false positive, 111, 147 set mode, 56
Address Conversion Statistics file, 50 directory files
address format LACSLink, 143
ace_get_input_length(), 54 SuiteLink, 152
ace_set_input_length(), 15, 54 DPV
address handles directories, 106
ace_cfg_open(), 25 directory path, 53
ace_evaluate_ah(), 27 false positive, 111
ace_get_input_length(), 54 false-positive log, 112
ace_init_addr(), 46 locking, 111
ace_set_input_length(), 54 No Stats indicators, 113
ace_term_addr(), 46 output components, 108
address processing, 15, 28, 29, 30 vacant indicators, 114
function call sequence, 10, 14 DPV Vacant indicators, 114
address standardization checks, 40 dpv_no_stats.dir, 106, 113
ace_get_stats(), 44 dpv_vacant.dir, 106
addrln.dct dpva.dir, 106
open and close, 49 dpvb.dir, 106
set pathname, 52 dpvc.dir, 106
addrtest.c, 9 dpvd.dir, 106
alias addresses, 60
E
C
eim_add_keycode, 13
capitalization eim_keycode_global_ term, 13
set dictionary pathname, 52 eim_keycode_global_init, 13
carrier route (CART) eLOT
query field, 85, 89 ace_get_mode, 58
CASS mode ace_set_mode, 58
DPV processing, 113 directory pathname, 52
CASS suggestion lists, 68 Emp Train processing category, 123
CASS Summary Report Enable
ace_3553(), 22 SuiteLink, 153
ace_3553_file(), 22 error
set form-template file(), 52 code, get description, 41
CASS version, 33 handling, 17, 36, 51
city directory EWS
get date, 37 ace_get_mode, 58
open and close, 49 ace_set_mode, 58
queries, 82 directory pathname, 52
set pathname, 52 example
city get_lastline, 39 SuiteLink, 152
city name exemption from directory expiration, 63
abbreviations, how to find, 99 expiration, directories, 49, 51, 63
last-line query field, 99

extension request, 124 header files, 82
query fields, 99
F structure pointers, 82
false positive, 147 lastln.dct
false-positive addresses, 111 open and close, 49
fields,input, 27 set pathname, 52
FIPS codes, 35 Locatable Address Conversion
function call sequence false-positive log, 148
basic address processing, 10, 14 lock
GeoCensus Option, 19 LACSLink, 147
suggestion lists, 68 locking
Z4Change Option, 18 DPV, 111
function calls log files
keycodes, 13 false positive, 112, 148
G M
GeoCensus Microsoft Windows DLL
set mode, 56 compile and link, 8
GeoCensus Option call sequence, 19 error handling, 17
GeoCensus Option directory Mktg Test processing category, 123
get date, 37 Mover ID, 121
set pathname, 52 move-updating, 121
GeoCensus Option look-up, 28, 29 multiline address
update components, 42
H
N
header files, 82
high-rise buildings, 152 National Deliverability Index
ace_ndi(), 47
I ace_ndi_file(), 47
NCOALink, 121
initialization, 45 No Stats indicators, 113
ace_cfg_open(), 25 Normal processing category, 123
ace_get_input_length(), 54
ace_init_addr(), 46 O
ace_set_input_length(), 54
open auxiliary files, 49 output, 15
input ace_get_component(), 34
ace_get_line_name(), 41 ace_get_line(), 55
ace_set_line(), 55 ace_get_line_name(), 41
fields, 15, 27 output address handles
input address handles ace_get_input_length(), 54
ace_set_input_length(), 54 output field
Int Db Tst processing category, 123 No Stats, 113
K P
keycodes parse-only mode, 30, 56
function calls, 13 primary
name
L query field, 89
primary name
LACSLink, 53, 58, 59, 141 lettermatch test, 40
false-positive log, 148 query field, 85
locking, 147 simil test, 40
LACSlink primary range
false-positive log, 148 query field, 85, 89
last line processing
get,_based on ZIP, 38 SuiteLink, 153
last-line queries, 82 PW.FIRM, 152
ace_ll_set_query(), 99 pwcas.dct
browse fields, 95 open and close, 49
create query structure, 98 set pathname, 52
function calls, 82, 102
Index 157
R ace_ll_term_query(), 102
ace_ll_term_show(), 102
ranlib (Sun/OS), 8
ace_term_addr(), 46
RDI
ace_term_query(), 92
ace_get_file, 53
ace_term_show(), 92
ace_get_mode, 58
close auxiliary files, 49
ace_set_file, 53
ace_set_mode, 58
description, 118
U
directories, 119 unit designator
output component, 120 query field, 85, 89
request for extension, 124 Unix compile and link, 8
USPS
S finance areas, query field, 89
USPS Address Conversion Statistics file, 50
sample application programs, 9
secondary address designators, 152
sequence of function calls
V
basic address processing, 10, 14 vacant address indicator
GeoCensus Option, 19 DSF2 output field, 114
suggestion lists, 68 vacant indicators, 114
Z4Change Option, 18 Visual Basic, 8, 17, 22, 47
show Visual C++, 8
showtest.c, 9
shwlltst.c, 9 W
shutdown, 45 Windows, 8
ace_term_addr(), 46 working directory, 52
SIC, 126
Solaris, 8 Z
Stage I processing category, 123
Stage II processing category, 123 Z4Change, 18
Standard Industrial Classification, 126 ace_set_z4c_check_date(), 64
standardization checks, 40 ace_z4_zip4_changed(), 65
ace_get_stats(), 44 call sequence, 18
state get date, 37
get_lastline, 39 set mode, 56
suffix set pathname, 52
query field, 85, 89 ZCF directory
suggestion lists, 78 get date, 37
ace_findf() parameters, 30 open and close, 49
consolidation, 77 queries, 82
filtering, 78, 79 set pathname, 52
get components, 73 ZIP Code
get number of suggestions, 74 get city and state, 38
get one suggestion, 71 get_lastline, 39
how to customize, 78 ZIP+4
how to process, 68 query field, 89
range entry, 75 ZIP+4 directory
set chosen suggestion, 76 get date, 37
set options, 80 open and close, 49
SuiteLink, 151, 152 set pathname, 52
Sun Microsystems ZIP+4 directory retrieval
Sun/OS, 8 browse fields, 85
Sys Test processing category, 123 create query structure, 88
get next query, 91
T get one field, 85
load query structure, 89
table search criteria, 89
No Stats, 113 shutdown, 92
termination, 45
ace_cfg_close(), 25

800c Ace LR en

Transféré par

Informations du document

Description originale:

Titre original

Copyright

Formats disponibles

Partager ce document

Partager ou intégrer le document

Options de partage

Avez-vous trouvé ce document utile ?

Ce contenu est-il inapproprié ?

Droits d'auteur :

Formats disponibles

800c Ace LR en

Transféré par

Droits d'auteur :

Formats disponibles

ACE

2 ACE Library Reference

ACE documentation You can access product documentation in several places:

Conventions This document adheres to the following documentation conventions:

4 ACE Library Reference

6 ACE Library Reference

Welcome to the ACE Library! This chapter, provides basic installation

Chapter 1: Install, compile, and set up ACE Library 7

8 ACE Library Reference

Chapter 1: Install, compile, and set up ACE Library 9

10 ACE Library Reference

Config file API calls

Auxiliary Call ace_set_mode() as necessary to set optional modes. See

4. Optional: Call eim_keycode_global_init() to initialize the SAP

Chapter 1: Install, compile, and set up ACE Library 11

12 ACE Library Reference

Synopses void eim_add_keycode(const char* keycode);

eim_keycode_global_init(), eim_keycode_global_ term()

Synopses void eim_keycode_global_init(void);

Description The eim_keycode_global_init() and eim_keycode_global_term() functions are

Chapter 1: Install, compile, and set up ACE Library 13

Return value Action

ACE_ABORT An internal error occurred.

14 ACE Library Reference

No abbreviation No abbreviation is applied. For each component, we provide a defined length

Chapter 1: Install, compile, and set up ACE Library 15

16 ACE Library Reference

ace_get_error_info(ah, ErrorNbr, title, msgbody )

MessageBox.Show(msgbody , "Ace Error")

Chapter 1: Install, compile, and set up ACE Library 17

Z4Change is an extra-cost option available to ACE users. For information about

Call sequence 1. Call ace_init() and ace_init_addr() as usual.

18 ACE Library Reference

GeoCensus is an extra-cost option available to ACE users. If you’d like

Call sequence 1. Call ace_init() and ace_init_addr() as usual.

Chapter 1: Install, compile, and set up ACE Library 19

Chapter 2: Functions for address processing 21

Synopses char* ace_3553(eleven parameters);

ADDR_HANDLE ah; Input: address handle

int ace_3553_file(twelve parameters);

ADDR_HANDLE ah; Input: address handle

Description The ace_3553() and ace_3553_file() functions generate a facsimile of USPS

22 ACE Library Reference

The LOT lines on your 3553 forms will be populated.

Chapter 2: Functions for address processing 23

Synopsis char * ace_3553_hdr(twelve parameters);

24 ACE Library Reference

Synopses int ace_cfg_open(two parameters);

char* pathname; Input: pathname of overall config file

int ace_cfg_close(one parameter);

ADDR_HANDLE* ah; Input: address handle

int ace_cfg_read(three parameters);

ADDR_HANDLE ah; Input: address handle

Type of file Original name Description

Overall ace.cfg Pathnames of the other three configuration files.

Chapter 2: Functions for address processing 25

Returns Returns ACE_OK if successful; otherwise, ACE_ERROR. An error usually

Note: After ace_cfg_open(), make ace_get_*() calls to obtain the settings

26 ACE Library Reference

Synopsis int ace_evaluate_ah(one parameter);

ADDR_HANDLE ah; Input: address handle

Chapter 2: Functions for address processing 27