800c_ace_lr_en

ACE 8.00c

September 2009

ACELibrary Reference

2 ACE Library Reference

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.

http://service.sap.com

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

http://help.sap.com

http://help.sap.com/

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 ................................................... 7Install ACE Library..........................................................................................8Sample application programs ...........................................................................9Three options for initialization and termination.............................................10ACE function calls for keycodes....................................................................13eim_add_keycode() ........................................................................................13eim_keycode_global_init(), eim_keycode_global_ term() ............................13ACE function calls for address processing ....................................................14Address input and output................................................................................15Error handling ................................................................................................17How to use the Z4Change functions ..............................................................18How to use the GeoCensus functions.............................................................19

Chapter 2:Functions for address processing............................................................... 21

Chapter 3:Suggestion lists............................................................................................. 67How to handle suggestion lists.......................................................................68How to customize suggestion lists .................................................................77

Chapter 4:How to query the postal directories........................................................... 81Introduction to directory queries ....................................................................82How to query the ZIP+4 directory .................................................................83Browse fields for ace_get_query() .................................................................86How to query the City and ZCF directories ...................................................93

Chapter 5:Delivery Point Validation (DPV) ............................................................. 103What is Delivery Point Validation (DPV)?..................................................104USPS requirements ......................................................................................105Installing DPV and its directories ................................................................106Performing DPV processing.........................................................................107DPV output components ..............................................................................108DPV performance.........................................................................................110DPV locking.................................................................................................111DPV false positive log..................................................................................112DPV No Stats indicators ..............................................................................113DPV Vacant indicators.................................................................................114

Chapter 6:Residential Delivery Indicator (RDI) ...................................................... 117What is RDI?................................................................................................118

Contents 5

RDI directories............................................................................................. 119Enable RDI processing ................................................................................ 120

Chapter 7:Mover ID for NCOALink......................................................................... 121ace_mvid_set_contact_info()....................................................................... 126

Chapter 8:LACSLink.................................................................................................. 141Overview...................................................................................................... 142Install LACSLink and its directories ........................................................... 143Performing LACSLink processing .............................................................. 144LACSLink output components .................................................................... 145LACSLink performance .............................................................................. 146LACSLink locking....................................................................................... 147LACSLink false positive log ....................................................................... 148ace_get_lacs_msg()...................................................................................... 149

Chapter 9:SuiteLink.................................................................................................... 151How does SuiteLink work?.......................................................................... 152Set up SuiteLink processing ........................................................................ 153SuiteLink 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:

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 addrtest

To compile addrtest, use the make-file addrtest_mk, which is installed in your acelib directory.

This procedure is similar for the other sample 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.


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.

Option 1: Full use of configuration files and minimal API function calls

This approach is good for fast prototyping and some applications.

1. Call ace_init() to allocate memory and initialize global data used by ACE.

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.

Note: For simplicity, some optional �get information� calls are ignored.


Option 2: Selective use of configuration files and API function calls

This method was developed specifically for client/server applications, where some aspects of configuration are set on the client side, by an end user (style options, choice of input fields) and other aspects (pathnames of auxiliary files) need to be set on the server side, by an administrator.


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.


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.

7. Optional: Call eim_keycode_global_term() to terminate the SAP BusinessObjects keying system and free memory it has used.

8. Your address handle should now be ready to begin processing addresses.



11. Call ace_close() to close the ACE auxiliary files.

12. Call ace_term_addr() to free the address handle.


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.


Option 3: No use of configuration files; do everything with API function calls

This approach gives the application engineer maximum flexibility and control, but requires more coding.


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.


9. Optional: Call eim_keycode_global_term() to terminate the SAP 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.



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_ABORTACE_ERROR

An internal error occurred.

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 addressinto the CADDR_HANDLE and call cace_findf().Otherwise, respond the same as toACE_NOT_FOUND.

ACE_USER_CITYACE_USER_ADDRESSACE_USER_SECONDARY

Invoke your suggestion-list handler. (See �Suggestion lists� on page 67 for information about handling sug-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 symbols

Line and component symbols are defined in ace.h and explained in the Quick 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 error handler

You may set up a callback (or delegate) to your own error-handling function. Call 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 routinePublic 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 handleint extended_ASCII; Input: printer supports extended ASCII?

TRUEFALSE

char* company_name; Input: your company name or blankchar* list_processor; Input: your company namechar* list_name; Input: file or mailing list namechar* mailers_address1; |char* mailers_address2; | Input: your company's namechar* mailers_address3; | and addresschar* mailers_address4; |char* soft_name_vers_date; Input: or blank for defaultint user_lot_cert; Input: end-user LOT certification

TRUEFALSE

int ace_3553_file(twelve parameters);

ADDR_HANDLE ah; Input: address handlechar* report_file; Input: pathname of output fileint extended_ASCII; Input: printer supports extended ASCII?

TRUEFALSE

char* company_name; Input: blank or your company namechar* list_processor; Input: your company namechar* list_name; Input: file or mailing list namechar* mailers_address1; |char* mailers_address2; | Input: your company's namechar* mailers_address3; | and addresschar* mailers_address4; |char* soft_name_vers_date; Input: blank for defaultint user_lot_cert; Input: end-user LOT certification

TRUEFALSE

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 BusinessObjectssoft_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 suggestion lists

Caution: If your application supports suggestion lists, the USPS does not permit 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);

ADDR_HANDLE ah; Input: address handleint extended_ASCII; Input: printer supports extended ASCII?

TRUEFALSE

char* company_name; Input: blank or your company namechar* list_processor; Input: your company namechar* list_name; Input: file or mailing list namechar* mailers_address1; |char* mailers_address2; | Input: your company's namechar* mailers_address3; | and addresschar* mailers_address4; |char* soft_name_vers_date; Input: blank for defaultint user_lot_cert; Input: end-user LOT certification

TRUEFALSE

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 fileADDR_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);

ADDR_HANDLE ah; Input: address handleint config_type; Input: config file type

ACE_CFG_AUXILIARY_FILESACE_CFG_OPTIONSACE_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.

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.

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_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);

ADDR_HANDLE ah; Input: address handle

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 handlechar *zip input: ZIP Codechar *pname input: primary (street) namechar *predir input: predirectionalchar *postdir input: postdirectionalchar *suffix input: suffixchar *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);

ADDR_HANDLE ah; Input: address handlechar* 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_OFFACE_SUGGESTIONS_RETURN

int processing_mode; Input: processing indicator (see next page)ACE_PARSEACE_PARSE + ACE_LOOKUPACE_CITY_RESOLVEDACE_ADDRESS_RESOLVEDACE_RANGE_RESOLVEDACE_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:

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_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.


When you set the processing_mode flag to:

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.

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_LOOKUP

ACE both parses the address and searches for it in the postal data-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_FOUNDACE_FOUND_LASTLINEACE_MLP_BAD_FORMATACE_MLP_SELECT_CITYACE_NO_SDRS_RANKEDACE_NO_SDRS_WITHAT_RNGACE_SELECT_PDESCACE_ZIP_NII_DIR

The address was not assigned. Respond to these return values in the same way that you respond to ACE_NOT_FOUND.Do not use these return values for address-fault diagnosis. Instead, check the ACE_ERROR_CODE component, which is a more accurate and specific indicator.

ACE_FOREIGN The address is foreign (outside the United States, the commonwealth of Puerto Rico, ter-ritories, possessions)

ACE_USER_CITYACE_USER_ADDRESSACE_USER_SECONDARY

The address was not assigned but: ! A last-line suggestion list was generated.! An address-line suggestion list was generated.! 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);

ADDR_HANDLE ah; Input: address handleint component; Input: component name (see Quick Reference)int old_new_flag; Input: original or standardized address

ACE_OLDACE_NEWACE_MVID (Mover ID)

char* comp_data; Output: retrieved data

int ace_get_source(two parameters);

ADDR_HANDLE ah; Input: address handleint 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);

ADDR_HANDLE ah; Input: address handlechar* state; Input: state abbreviationchar* county_code; Input: FIPS county codechar* 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);

ADDR_HANDLE ah; Input: address handleint *err_code; Output: error numberchar *message1; Output: error type messagechar *message2; Output: specific error message

int ace_get_error_info_return(three parameters);

ADDR_HANDLE ah; Input: address handlechar *message1; Output: error type messagechar *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 FOUNDMessage 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);

ADDR_HANDLE ah; Input: address handleint file_ID; Input: file identifier

ACE_DIR_CITYACE_DIR_CGEOACE_DIR_SUITELINKACE_DIR_Z4CHANGEACE_DIR_ZCFACE_DIR_ZIP4_1ACE_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);

ADDR_HANDLE ah; Input: address handlechar* zip; Input: desired ZIP Codechar* 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 handlechar* zip; Input: Desired ZIP Codechar* city; Output: City stringchar* 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_NAMEACE_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 STMILW 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);

ADDR_HANDLE ah; Input: address handleint line_ID; Input: line number (see list below)char* line_name; Output: line name

char* ace_get_error_desc(two parameters);

ADDR_HANDLE ah; Input: address handlechar* error_code; Input: error code numberchar* 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);

ADDR_HANDLE ah; Input: address handleint extended_ASCII; Input: printer supports extended ASCII set?

TRUEFALSE

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 nameint MLNFA_deleted; Input: have MLNFA records been deleted?

TRUEFALSE

int ace_ndi_file(seven parameters);

ADDR_HANDLE ah; Input: address handlechar* report_file; Input: path & name of output fileint extended_ASCII; Input: printer supports extended ASCII set?

TRUEFALSE

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 nameint MLNFA_deleted; Input: have MLNFA records been deleted?

TRUEFALSE

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.


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().

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.

Parameter Description


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);

ADDR_HANDLE ah; Input: address handleint option_ID; Input: option identifier (see table)char* setting; Input: option setting (see table)

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.

To produce the USPS Address Conversion Statistics file, you must set this function.

Returns The USPS Address Conversion Statistics file.

Symbol for option_ID Symbols for setting

Description

ACE_ACS_ENABLE �TRUE��FALSE� (default)

Set this to �TRUE� if you want to 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 ASCIIDBASE3DELIMITEDEBCDIC

Enter the file type of the statistics file.

ACE_ACS_INPFILE n/a Enter the name of the input data-base file. Use of this symbol is optional.

When you process a job using an assignment mode of Geo or Parse, ACE does not produce the USPS address conversion statistics file.


ace_set_error_rtn()

Synopsis int ace_set_error_rtn(two parameters);

ADDR_HANDLE ah; Input: address handleint (*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 error handler

int my_error_handler(one parameter);



ace_set_file(), ace_get_file(), ace_get_z4dirno()

Synopses int ace_set_file(three parameters);ADDR_HANDLE ah; Input: address handleint file_ID; Input: file identifier (list on next page)char* pathname; Input: pathname

char* ace_get_file(three parameters);ADDR_HANDLE ah; Input: address handleint file_ID; Input: file identifier (list on next page)char* pathname; Output: pathname

int ace_get_z4dirno(one parameter);ADDR_HANDLE ah; Input: address handle

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_1ACE_DIR_ZIP4_2

zip4us.dir

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


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_DIR_EWS ew*.dirEnter 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_FILES

Enter the path to the NCOALink or SuitLink supporting files. (NCOALink and 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


ace_set_input_length(), ace_get_input_length()

Synopses int ace_set_input_length(three parameters);

ADDR_HANDLE ah; Input: address handleint line; Input: line symbol (see Quick Reference)int max_length; Input: maximum length

int ace_get_input_length(three parameters);

ADDR_HANDLE ah; Input: address handleint line; Input: line symbolint* 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);

ADDR_HANDLE ah; Input: address handleint line; Input: line numberchar* line_buffer; Input: raw address data

char* ace_get_line(three parameters);

ADDR_HANDLE ah; Input: address handleint 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);

ADDR_HANDLE ah; Input: address handleint mode_ID; Input: mode identifier (see table)int mode; Input: desired mode

TRUEFALSE

int ace_get_mode(three parameters);

ADDR_HANDLE ah; Input: address handleint 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 identifier

Description

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

ACE_MODE_GEO ACE_NONE_GEO

You must call ace_set_mode() to set the GeoCensus mode that 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.


ACE_MODE_AL_SHOW_ONLYACE_MODE_LL_SHOW_ONLY

FALSE These modes were developed to reduce the system demands of our 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.


Description


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_SOUNDEX

TRUE Set to FALSE to disable the reverse soundex look-ups through the library.

ACE_MODE_CACHE_DPV_DIRS

FALSE Set this option to TRUE to enable DPV directory caching. Set this option to FALSE to disable DPV directory caching.

ACE_MODE_ABORT_ON_CACHE_ERROR

FALSE If you�re caching the LACSLink directories, you must specify 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_CACHE_ERROR

TRUE Set this option to FALSE if you want to continue DPV processing 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.Note: This option has no effect unless 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.


Description


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_DIRS

FALSE Set this option to TRUE to enable LACSLink directory caching.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_SUITELINK

FALSE To enable SuiteLink processing, set this option to TRUE.To disable SuiteLink processing, set this option to FALSE.

ACE_MODE_CACHE_SUITELINK_DIRS

FALSE If you cache the SuiteLInk directories, you must specify if you 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.

Note: This option has no effect unless ACE_MODE_CACHE_SUITELINK_DIRS is set to TRUE.

ACE_MODE_ABORT_ON_CACHE_ERROR

TRUE Set this option to FALSE if you want to continue processing with-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.


Description


ace_set_option(), ace_get_option()

Synopses int ace_set_option(three parameters);

ADDR_HANDLE ah; Input: address handleint option_ID; Input: option identifier (see table)int setting; Input: option setting (see table)

int ace_get_option(three parameters);

ADDR_HANDLE ah; Input: address handleint option_ID; Input: option identifier (see table)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_ALIASACE_PRESERVE_ALIAS

ACE_CONVERT_ALIAS

ACE_OPT_APPEND_PMB TRUEFALSE

FALSE

ACE_OPT_ASSIGN_CITY_BY_INPUT_LLIDX TRUEFALSE

TRUE

ACE_OPT_CAPITALIZATION ACE_UPPERCASEACE_MIXEDCASEACE_LOWERCASE

ACE_UPPERCASE

ACE_OPT_DIR_STYLE ACE_STYLE_SHORTACE_STYLE_LONGACE_STYLE_PRESERVE

ACE_STYLE_SHORT


ACE_OPT_DUAL_TYPE ACE_DUAL_POSITIONACE_DUAL_MAILINGACE_DUAL_STREET

ACE_DUAL_POSITION

ACE_OPT_EXTRA_DATA ACE_LOOSEACE_STRICT

ACE_STRICT

ACE_OPT_MULTI_COMBINE_ALACE_OPT_MULTI_COMBINE_LL

TRUEFALSE

TRUE

ACE_OPT_MULTI_PRESERVE_DUAL_ORDER TRUEFALSE

FALSE

ACE_OPT_MULTI_SWAP ACE_SWAP_TOPACE_SWAP_BOTTOMACE_SWAP_NONE

ACE_SWAP_NONE

ACE_OPT_MULTI_UPDATE_ZIP ACE_UPDATEACE_DONT_UPDATEACE_ERASE_THEN_UPDATE

ACE_UPDATE

ACE_OPT_MULTI_UPDATE_ZIP4 ACE_UPDATEACE_DONT_UPDATEACE_ERASE_THEN_UPDATE

ACE_ERASE_THEN_UPDATE

ACE_OPT_NON_CASS_ACCEPT_INP_ZIP4 TRUEFALSE

FALSE

ACE_OPT_NON_CASS_INEXACT_ZIPMOVE TRUEFALSE

FALSE

ACE_OPT_PLACENAME ACE_CONVERT_PLACENAMEACE_PRESERVE_PLACENAME

ACE_CONVERT_PLACENAME

ACE_OPT_POUND_TO_SEC_ADDR TRUEFALSE

FALSE

ACE_OPT_STND_ADDR_LINEACE_OPT_STND_LAST_LINE

TRUEFALSE

TRUE

ACE_OPT_STND_CITY_ABBR TRUEFALSE

FALSE

ACE_OPT_STND_STREET_ABBR TRUEFALSE

FALSE

ACE_OPT_STND_UNASSIGNED_ADDR

TRUEFALSE

FALSE

ACE_OPT_SFX_STYLE ACE_STYLE_SHORTACE_STYLE_LONGACE_STYLE_PRESERVE

ACE_STYLE_SHORT

ACE_OPT_UNIT_DESIG ACE_UNIT_PRESERVEACE_UNIT_DIRECTORY

ACE_UNIT_DIRECTORY



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 option

Use the following output components for the ACE_GET_COMPONENT function when you use the Accept Input ZIP+4 if Secondary Match option:

ACE_OPT_NON_CASS_ZIP4_NON_DPV_CONFIRM

FALSE If you choose not to process with DPV, but you want ZIP+4 informa-tion, set the option to True.


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);

ADDR_HANDLE ah; Input: address handlechar* 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);

ADDR_HANDLE ah; Input: address handleint month; Input: month of last ZIP+4 codingint 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);

ADDR_HANDLE ah; Input: address handlechar* 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 processing

The process is as follows: 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 ACE_USER_ADDRESS

1. Retrieve the list from ACE. First, call ace_get_suggno() to get the number of 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.


If ace_findf() returns ACE_USER_SECONDARY

1. Retrieve the list from ACE. First, call ace_get_suggno() to get the number of 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():

If ace_findf() returns ACE_USER_CITY

1. Retrieve the list from ACE. First, call ace_get_suggno() to get the number of 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.

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.


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);

ADDR_HANDLE ah; Input: address handleint 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);

ADDR_HANDLE ah; Input: address handleint sugg_num; Input: suggestion numberint component; Input: component to be retrieved; for

defines,see �ace_get_query()� on page 85char* cmpt_buffer; Output: retrieved component

Description The ace_get_sugg_cmpt() function retrieves one component of one address-line, city, or secondary suggestion. Call it inside a nested loop�the inner loop on component, the outer loop on sugg_num. You can obtain the maximum value of sugg_num by calling ace_get_suggno().

For the component parameter, be sure to use the field names of ace_get_query(). Remember, you are retrieving data from a ZIP+4 directory record, not the components of a particular address. Do not use the field names of ace_get_component().

For last-line suggestions, only the following components are valid: ACE_LLQ_CITYNAME, ACE_LLQ_ZIP, and ACE_LLQ_STATE.

Returns Returns a pointer to the cmpt_buffer containing the retrieved component.

Component symbols

ACEQ_RECTYPEACEQ_ODDEVENACEQ_SODDEVENACEQ_SNAMEACEQ_UNIT

ACEQ_LLINDEXACEQ_URB_INDEX

ACEQ_LOWRANGEACEQ_HIGHRANGEACEQ_PREDIRACEQ_PNAMEACEQ_POSTDIRACEQ_SUFFIXACEQ_SNAMEACEQ_UNITACEQ_LOWSRANGEACEQ_HIGHSRANGEACEQ_ZIPACEQ_ZIP4EVENACEQ_ZIP4ODDACEQ_CARTEVENACEQ_CARTODDACEQ_ALSTYPACEQ_LACSINDACEQ_ZIP_MOVEACEQ_CONGRESSACEQ_COUNTYACEQ_ALTERNATE

ACE_LLQ_CITYNAMEACE_LLQ_ZIPACE_LLQ_STATE

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);

ADDR_HANDLE ah; Input: address handlerange_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);

ADDR_HANDLE ah; Input: address handleint sugg_num; Input: suggestion numberint sugg_list_type; Input: type of suggestion list being resolved

ACE_USER_ADDRESSACE_USER_CITYACE_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 ACE has called potential matches for the input address. Normally, each ZIP+4 directory record is returned as a separate suggestion.

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 consolidation is more aggressive. The above suggestion list would be compressed as shown here.

Respect gaps ACE preserves gaps in primary ranges, but overlapping ranges are consolidated. The above suggestion list would be compressed as shown here.

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.

100 - 199 Main St111 - 117 Main St200 - 299 Main St300 - 399 Main St100 - 199 Main St Ext231 - 233 Main St Ext235 - 235 Main St Ext

100 - 399 Main St100 - 235 Main St Ext

100 - 399 Main St100 - 199 Main St Ext231 - 233 Main St Ext235 - 235 Main St Ext


Filter by primary range

Another way to shorten address suggestion lists is to filter them by primary 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, ACE will return only those suggestions that match the 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 get with window set at 200 (100 on each side of the input range). Again, the effect is to limit suggestions to one 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.

100 - 117 Main St100 - 199 Main St Ext

100 - 199 Main St111-117 Main St200 - 299 Main St100 - 199 Main St Ext


ace_set_sugg_filter()

Synopses #include <aceshow.h>

int ace_set_sugg_filter(two parameters);ADDR_HANDLE ah; Input: address handle

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.

2. Call ace_clear_query() to clear the query structure.

3. Call ace_set_query() to write your criteria into the query structure. Query fields are listed on the ace_set_query() reference page (�ace_get_query()� 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.

ACEQ_PREDIRACEQ_POSTDIRACEQ_SUFFIXACEQ_UNITACEQ_ZIP4ACEQ_CARTACEQ_COUNTYACEQ_LOWRANGEACEQ_HIGHRANGE

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);

ADDR_HANDLE ah; Input: address handleint option_ID; Input: option identifier (see table)int setting; Input: option setting (see table)

int ace_get_sugg_option(three parameters);

ADDR_HANDLE ah; Input: address handleint option_ID; Input: option identifier (see table)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

FALSEIf TRUE, ACE returns only those address-line sug-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

ACE_CNSL_SUGG

ACE_CNSL2_SUGG

Suggestions are not consolidated (default).

ACE ignores gaps and overlaps in primary ranges, so consolidation is more aggressive.

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 the ZIP+4 directory

Last-line queries in the City and ZCF directories

Functions ace_init_query()ace_clear_query()ace_set_query()ace_init_show()ace_show()ace_get_query()ace_term_query()ace_term_show()

ace_ll_init_query()ace_ll_clear_query()ace_ll_set_query()ace_ll_init_show()ace_ll_show()ace_ll_get_query()ace_ll_term_query()ace_ll_term_show()

Handles ACE_QUERY_HANDLEACE_BROWSE_HANDLE

ACE_LL_QUERY_HANDLEACE_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 handlefrom 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 handlefrom ace_init_show()

int browse_field; Input: browse fieldchar* 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

ACEQ_SODDEVEN

An E, O, or B to indicate whether the record covers the even-numbered side of the street, odd, or both.

Same indicator for secondary-address records.ACEQ_LLINDEX

ACEQ_URB_INDEX

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.

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 components

ACEQ_LOWRANGEACEQ_HIGHRANGE

Primary range; comparable to ACE_PRIM_RANGE.

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_LOWSRANGEACEQ_HIGHSRANGE

Secondary range (apartment or suite number); comparable to ACE_SEC_RANGE.

Postal codes ACEQ_ZIP Five-digit ZIP Code; similar to ACE_ZIP.ACEQ_ZIP4EVENACEQ_ZIP4ODD

ZIP+4 add-on code; comparable to ACE_ZIP4.

ACEQ_CARTEVENACEQ_CARTODD

Carrier-route number; comparable to ACE_CART.

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);

ADDR_HANDLE ah; Input: address handleACE_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_LOWRANGEACEQ_HIGHRANGE

To search for a certain house number, load it into ACEQ_LOWRANGE and set 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_PREDIRACEQ_POSTDIR

N, NE, E, SE, S, SW, W, or NW

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_ZIPLOWACEQ_ZIPHIGH

To search a range of ZIP Codes, load both ACEQ_ZIPLOW and 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 handlefrom ace_init_show()

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:

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.

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.


ace_term_query(), ace_term_show()

Synopses #include <aceshow.h>

int ace_term_query(one parameter);

ACE_QUERY_HANDLE* query_id; Input: query handlefrom ace_init_query()

int ace_term_show(one parameter);

ACE_BROWSE_HANDLE* browse_id; Input: browse handlefrom ace_init_show()

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 handlefrom 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 handlefrom ace_ll_init_show()

int browse_field; Input: browse fieldchar* 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 FacilityB Branch Post OfficeC Community Post OfficeD Area Distribution CenterE Sectional Center FacilityF Delivery DistributionG General Mail FacilityK Bulk Mail CenterM Money Order UnitP Post OfficeS StationU 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);

ADDR_HANDLE ah; Input: address handleACE_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 fieldchar* 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)

Fields for setting query data (ZCF 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.

Name Description

ACE_LLQ_ZIPHIGHACE_LLQ_ZIPLOW

To search a range of ZIP Codes, load the low end of the 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.


Fields for setting query 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 handlefrom ace_ll_init_show()

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:

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.

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.


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 handlefrom ace_ll_init_query()

#include <aceshwll.h>

int ace_ll_term_show(one parameter);

ACE_LL_BROWSE_HANDLE* ll_browse_id; Input: browse handlefrom ace_ll_init_show()

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 updates

DPV directories are shipped monthly with the U.S. directories in accordance with 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: Location and names of DPV directories

The DPV directories must reside on a hard drive. Do not rename any of the files. DPV will not run if the file names are changed.

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.

! Set the required Customer & USPS Licensee Information parameters.

Required Customer & USPS Licensee Information parameters

Set the following required customer information fields using ace_set_mailer_info():

ACE_MAILER_CUST_COACE_MAILER_CUST_ADDRESSACE_MAILER_CUST_CITYACE_MAILER_CUST_STATEACE_MAILER_CUST_ZIPACE_MAILER_CUST_ZIP4ACE_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.

Value Description

ACE_MODE_ENABLE_DPV Use this value to enable DPV processing.


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.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_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.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_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 processing on the AIX platform

ACE now uses the Object Data Manager (ODM) to process DPV records. If you are running ACE on the AIX platform, you need to make sure that the ODMDIR 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 directories

To load DPV directories into system memory, set the following options for the 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.

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.

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.


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.

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 information

If you are not an NCOALink L/FSP, and you encounter a false-positive address 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.

!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.


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.

No Stats output fields Use the No Stats output fields to post No Stat indicator information to an output file.

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.

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.

DPV address-attribute output fields

Address attributes for the assigned address are available in ACE fields.

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.

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);

ADDR_HANDLE ah; Input: address handle 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:

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);

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_STARTACE_DPV_LOCK_ADDR_MSG_NO_END

69

The lock address.

ACE_DPV_USPS_MSG_NO_STARTACE_DPV_USPS_MSG_NO_END

1122

The USPS lock 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 configuration file?

If you use ACE Library�s configuration file, you can also benefit from RDI functionality. Through AceAux.cfg you can control both the ACE_MODE_ENABLE_RDI and ACE_DIR_RDI components.

RDI output component

For RDI, ACE uses a single output component, whose value is always one character in length. The RDI component is populated only when the option within the execution block is enabled.

Library component

Length Description

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)

ADDR_HANDLE ah; Input: address handleint 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 setting

Length Description

ACE_MID_MATCH_LOGIC BICSR

n/a Choose the types of moves that you want to pro-cess:! B means business moves only. This ignores fam-

ily and individual moves. ! 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 COASTATSRETCODE

n/a ! COA. You�re processing this job to update it with the latest address data.

! 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.


ACE_MID_PROCESSING_CAT EMP TRAININT DB TSTMKTG TESTPROD RUNSTAGE ISTAGE IISYS TEST

n/a Specify your reason for using NCOALink:! Emp Train. You�re processing this file as part of

employee training.! Int Db Tst. You�re testing with a licensee-owned

database.! Mktg Test. You�re testing with external customer

lists.! Prod Run. You�re processing the mailing list to

update it before a mailing.! 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_CLASSACE_MID_PROC_PER_MAILACE_MID_PROC_STD_MAILACE_MID_PKG_SRV_MAIL

YN

Indicate the mail classes that you�re processing by entering Y for those you�re processing and N for those you�re not.

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.


Length Description


ACE_MID_PREPROC_PERFORMED N YDP B

1 Indicate whether you processed or will process this data before performing NCOALink processing.N No pre-processingY Yes, but with no data changesD Yes, with non-postal data changesP Yes, with postal data changes onlyB Yes, with postal and non-postal data changes

ACE_MID_CONC_PROC_PERFORMED N YDP B

1 Indicate whether you processed or will process this data in some other way while performing NCOAL-ink processing.N No concurrent processingY Yes, but with no data changesD Yes, with non-postal data changesP Yes, with postal data changes onlyB Yes, with postal and non-postal data changes

ACE_MID_POSTPROC_PERFORMED N YDP B

1 Indicate whether you will process this data after performing NCOALink processing.N No post-processingY Yes, but with no data changesD Yes, with non-postal data changesP Yes, with postal data changes onlyB Yes, with postal and non-postal data changes

ACE_MID_STD_OUTPUT_RETURNED YNB

1 Y All required NCOALink output was returned to the client.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 IMR

n/a Specify the reason for completing your current PAF:I Initial. This is the first PAF you�re completing to

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.


Length Description


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_PAF

n/a n/a Enter the date that the licensee signed the PAF. Use the yyyy/mm/dd date format.

ACE_MID_CACHE_MB AUTOor a number as a text string

n/a AUTO. ACE loads your NCOALink files into system memory. ACE determines the amount of memory to use based on the available memory, the size of the 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 ASR

1 The USPS wants to distinguish between files that have a legitimate reason for a high percentage of NCOALink matches and files that are fraudulently used to create mover lists. Legitimate reasons for high match rate:! A. An ANKLink-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 YN

1 Y = Alternate PAF usedN = No alternate PAF was used

ACE_MAILER_PAF_SIGNEE_COMPANY_WEBSITE

n/a 40 Company website address of the person signing the PAF.

ACE_MAILER_PAF_SIGNEE_EMAIL n/a 64 Email address of person signing the PAF.

ACE_MID_CONTACT_COMPANY_WEBSITE

n/a 40 Website address of broker or list administrator. Set this with ace_mvid_set_contact_info( ).


Length Description


ace_mvid_set_contact_info()

Synopsis char ace_mvid_set_contact_info(three parameters)

ADDR_HANDLE ah; Input: address handleint contact_index Input: number 1-100. int setting_ID Input: setting identifier. See table below.char* setting Input: desired setting

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.



Length Description

ACE_MID_CONTACT_TYPE BROKERLISTADMIN

n/a Indicate whose contact information you are pro-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_NAMEACE_MID_CONTACT_ADDRESSACE_MID_CONTACT_CITYACE_MID_CONTACT_STATEACE_MID_CONTACT_ZIPACE_MID_CONTACT_ZIP4ACE_MID_CONTACT_PHONE

n/a 5012502825410

Enter the broker�s or list administrator�s:! name! complete address! phone number

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_PAF

n/a n/a Enter the date when this contact signed the PAF. Use the yyyymmdd date format.You must set the date signed for every contact involved.


http://www.census.gov/epcd/www/sic.html

ace_set_mailer_info()

Synopsis char ace_set_mailer_info(three parameters)

ADDR_HANDLE ah; Input: address handleint setting_ID Input setting identifier. See table below.char* setting Input: desired setting

Description Call ace_mvid_set_info() to set up NCOALink processing.



Length Description

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_COACE_MAILER_CUST_ADDRESSACE_MAILER_CUST_CITYACE_MAILER_CUST_STATEACE_MAILER_CUST_ZIPACE_MAILER_CUST_ZIP4ACE_MAILER_CUST_PHONE

n/a 5050282541012

The customer is the person or company for whom you are per-forming NCOALink processing.If you�re a limited or full service provider, or an end user, enter the customer�s address and telephone number. End users may leave these fields blank.The customer information appears in the Mover ID Summary and log files.

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.


http://www.census.gov/epcd/www/sic.html

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.


Length Description


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).


Overwriting address handle values

The following fields are defaulted based on values from the address handle, and don�t need to be set with ace_mvid_report_init() unless you need to overwrite those values:

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.

Setting Description

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).


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.

Setting Description


Settings for multiple output files

If your application produced multiple output files, the report can produce a 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 LACSLink processing

Addresses are passed into LACSLink processing when:

! 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:

RR 2 BOX 204 DU BOIS PA 15801

After LACSLink conversion:

463 SHOWERS RDDU 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

Directory expiration and updates

LACSLink directories expire in 105 days. LACSLink directories must have the same date as the other directories that you are using from the National Directories CD.

!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.


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 & USPS Licensee Information parameters

Set the following required customer information fields using ace_set_mailer_info():

ACE_MAILER_CUST_COACE_MAILER_CUST_ADDRESSACE_MAILER_CUST_CITYACE_MAILER_CUST_STATEACE_MAILER_CUST_ZIPACE_MAILER_CUST_ZIP4ACE_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.

Blank No LACSLink lookup attempted.

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.Blank No LACSLink lookup attempted.


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.

ACE does not load the LACSLink directories into your system memory if LACSLinkprocessing is turned off.

Load into system memory

To load LACSLink directories into system memory, call ace_set_mode() as 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);

If you use 150 MB of your system memory to cache the LACSLink directories, the performance of ACE improves considerably.


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.

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.

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.


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.

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 information

If you are not an NCOALink L/FSP, and you encounter a false-positive address 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.

!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.


ace_get_lacs_msg()

Synopsis int ace_get_lacs_msg(three parameters);

ADDR_HANDLE ah; Input: address handleint line_number; Input: number of message lineschar *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_STARTthrough ACE_LACS_USPS_MSG_NO_END


You can retrieve specific parts of the alert text by calling line numbers separately:

Returns This function returns ACE_OK or ACE_ERROR.

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_STARTACE_LACS_LOCK_ADDR_MSG_NO_END

69

The lock address.

ACE_LACS_USPS_MSG_NO_STARTACE_LACS_USPS_MSG_NO_END

1122

The USPS lock text.


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..

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

SuiteLink directory files

The SuiteLink directory is distributed monthly by the USPS. You must use the 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.

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.

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.

ACE input record SuiteLink directory ACE output

Poplar Auto987 Main St12345-6789

Poplar Medical Sales Ste212Poplar Auto Sales Ste 214Poplar Computers Ste216Wilson Law Firm Ste 218Boyce�s Kayaks Ste 220

Poplar Auto987 Main St Ste 21412345-6789

!Non-CASS mode: SuiteLink is disabled if you are running your job in non-CASS mode.


Set up SuiteLink processing

Enable SuiteLink and cache directory

Use these ACE_Mode file identifiers to enable SuiteLink and to set up caching.

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).

Locations for SuiteLink directory files

SuiteLink and NCOALink use the same support files. Use these directory file 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 mode_ID Default modes

Description

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.

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_RETCODE

2 The result of SuiteLink processing.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

Aace_3553(), 22ace_3553_file(), 22ace_3553_hdr, 24ace_browse_ptr structure, 82, 85ace_cfg_close(), 25ace_cfg_open(), 25ace_cfg_read(), 25ace_clear_query(), 84ace_close(), 49ACE_DIR_NAME_PARSING_FILES, 153ACE_DIR_SUITELINK, 153ACE_DPV_NO_STATS, 113ACE_DPV_VACANT, 114ace_evaluate_ah(), 27ace_find_geo_data(), 19, 28, 29ace_findf(), 30

return codes, 32ace_get_cert_ver(), 33ace_get_component(), 15, 34ace_get_county_name(), 35ace_get_error_desc(), 41ace_get_error_info(), 17, 36ace_get_error_info_return(), 36ace_get_file(), 52ace_get_file_date(), 37ace_get_geodir(), 19ace_get_geodirdate(), 19ace_get_input_length(), 54ace_get_lastline_components(), 39ace_get_lettermatch(), 40ace_get_line(), 15, 55ace_get_line_name(), 41ace_get_mode(), 56, 153ace_get_offset(), 42ace_get_option(), 60ace_get_query(), 85ace_get_revision(), 43ace_get_simil(), 40ace_get_source(), 15, 34ace_get_stats(), 44ace_get_sugg(), 71ace_get_sugg_cmpt(), 68, 73ace_get_sugg_option(), 80ace_get_suggno(), 68, 74ace_get_z4cdir(), 18ace_get_z4cdirdate(), 18ace_get_z4dirno(), 52ace_getll(), 38ace_init(), 45ace_init_addr(), 46ace_init_query(), 87ace_init_show(), 88

ACE_INPUT_FIRM, 154ace_ll_browse_ptr structure, 82, 95ace_ll_clear_query(), 94ace_ll_get_query(), 95ace_ll_init_query(), 97ace_ll_init_show(), 98ace_ll_query_ptr structure, 82ace_ll_set_query(), 99ace_ll_show(), 101ace_ll_term_query(), 102ace_ll_term_show(), 102ACE_MODE_CACHE_SUITELINK_DIRS, 153ACE_MODE_ENABLE_SUITELINK, 153ace_mvid_ncoal_header, 129ace_mvid_report_file_section, 138ace_mvid_report_init, 130ace_mvid_report_job_section, 137ace_mvid_report_open, 136ace_mvid_report_set_data, 131ace_mvid_report_set_retcode_count, 135ace_mvid_report_term, 139ace_mvid_set_contact_info, 126ace_mvid_set_info, 122ace_ndi(), 47ace_ndi_file(), 47ace_open(), 49ACE_PRESL_DPBC, 154ACE_PRESL_SEC_RANGE, 154ACE_PRESL_ZIP, 154ACE_PRESL_ZIP4, 154ace_query structure, 82, 89ace_set_acs_info(), 50ace_set_error_rtn(), 17, 51ace_set_file(), 52ace_set_geo_mode(), 19ace_set_geodir(), 19ace_set_input_length(), 15, 54ace_set_line(), 15, 55ace_set_mailer_info, 127ace_set_mode, 153ace_set_mode(), 56ace_set_option(), 60ace_set_password(), 63ace_set_query(), 89ace_set_range(), 68, 75ace_set_sugg(), 68, 76ace_set_sugg_filter(), 78, 79ace_set_sugg_option(), 80ace_set_sugg_rangematch(), 78ace_set_sugg_rangewindow(), 78ace_set_sugg_simil(), 78ace_set_sugg_style(), 77ace_set_z4c_check_date(), 18, 64ace_set_z4c_dir(), 18

Index 155

ace_set_z4c_mode(), 18ace_show(), 91ACE_SUITELINK_RETCODE, 154ace_term(), 45ace_term_addr(), 46ace_term_query(), 92ace_term_show(), 92ace_z4_zip4_changed(), 18, 65acetest.c, 9acs_ll_query_ptr structure, 99addr_handle structure

ace_cfg_open(), 25ace_evaluate_ah(), 27ace_get_input_length(), 54ace_init_addr(), 46ace_set_input_length(), 54ace_term_addr(), 46

addressfalse positive, 111, 147

Address Conversion Statistics file, 50address format

ace_get_input_length(), 54ace_set_input_length(), 15, 54

address handlesace_cfg_open(), 25ace_evaluate_ah(), 27ace_get_input_length(), 54ace_init_addr(), 46ace_set_input_length(), 54ace_term_addr(), 46

address processing, 15, 28, 29, 30function call sequence, 10, 14

address standardization checks, 40ace_get_stats(), 44

addrln.dctopen and close, 49set pathname, 52

addrtest.c, 9alias addresses, 60

Ccapitalization

set dictionary pathname, 52carrier route (CART)

query field, 85, 89CASS mode

DPV processing, 113CASS suggestion lists, 68CASS Summary Report

ace_3553(), 22ace_3553_file(), 22set form-template file(), 52

CASS version, 33city directory

get date, 37open and close, 49queries, 82set pathname, 52

city get_lastline, 39city name

abbreviations, how to find, 99last-line query field, 99

lettermatch test, 40simil test, 40

compilers, 8components, output, 15, 34county names

ace_get_county_name(), 35

DDelivery Point Validation alse-positive log, 112directionals

query fields, 85, 89directories

DPV, 106get date, 37open and close, 49set pathname, 52set working directory, 52

directory expiration warningsset mode, 56

directory filesLACSLink, 143SuiteLink, 152

DPVdirectories, 106directory path, 53false positive, 111false-positive log, 112locking, 111No Stats indicators, 113output components, 108vacant indicators, 114

DPV Vacant indicators, 114dpv_no_stats.dir, 106, 113dpv_vacant.dir, 106dpva.dir, 106dpvb.dir, 106dpvc.dir, 106dpvd.dir, 106

Eeim_add_keycode, 13eim_keycode_global_ term, 13eim_keycode_global_init, 13eLOT

ace_get_mode, 58ace_set_mode, 58directory pathname, 52

Emp Train processing category, 123Enable

SuiteLink, 153error

code, get description, 41handling, 17, 36, 51

EWSace_get_mode, 58ace_set_mode, 58directory pathname, 52

exampleSuiteLink, 152

exemption from directory expiration, 63expiration, directories, 49, 51, 63


extension request, 124

Ffalse positive, 147false-positive addresses, 111fields,input, 27FIPS codes, 35function call sequence

basic address processing, 10, 14GeoCensus Option, 19suggestion lists, 68Z4Change Option, 18

function callskeycodes, 13

GGeoCensus

set mode, 56GeoCensus Option call sequence, 19GeoCensus Option directory

get date, 37set pathname, 52

GeoCensus Option look-up, 28, 29

Hheader files, 82high-rise buildings, 152

Iinitialization, 45

ace_cfg_open(), 25ace_get_input_length(), 54ace_init_addr(), 46ace_set_input_length(), 54open auxiliary files, 49

inputace_get_line_name(), 41ace_set_line(), 55fields, 15, 27

input address handlesace_set_input_length(), 54

Int Db Tst processing category, 123

Kkeycodes

function calls, 13

LLACSLink, 53, 58, 59, 141

false-positive log, 148locking, 147

LACSlinkfalse-positive log, 148

last lineget,_based on ZIP, 38

last-line queries, 82ace_ll_set_query(), 99browse fields, 95create query structure, 98function calls, 82, 102

header files, 82query fields, 99structure pointers, 82

lastln.dctopen and close, 49set pathname, 52

Locatable Address Conversionfalse-positive log, 148

lockLACSLink, 147

lockingDPV, 111

log filesfalse positive, 112, 148

MMicrosoft Windows DLL

compile and link, 8error handling, 17

Mktg Test processing category, 123Mover ID, 121move-updating, 121multiline address

update components, 42

NNational Deliverability Index

ace_ndi(), 47ace_ndi_file(), 47

NCOALink, 121No Stats indicators, 113Normal processing category, 123

Ooutput, 15

ace_get_component(), 34ace_get_line(), 55ace_get_line_name(), 41

output address handlesace_get_input_length(), 54

output fieldNo Stats, 113

Pparse-only mode, 30, 56primary

namequery field, 89

primary namelettermatch test, 40query field, 85simil test, 40

primary rangequery field, 85, 89

processingSuiteLink, 153

PW.FIRM, 152pwcas.dct

open and close, 49set pathname, 52

Index 157

Rranlib (Sun/OS), 8RDI

ace_get_file, 53ace_get_mode, 58ace_set_file, 53ace_set_mode, 58description, 118directories, 119output component, 120

request for extension, 124

Ssample application programs, 9secondary address designators, 152sequence of function calls

basic address processing, 10, 14GeoCensus Option, 19suggestion lists, 68Z4Change Option, 18

showshowtest.c, 9shwlltst.c, 9

shutdown, 45ace_term_addr(), 46

SIC, 126Solaris, 8Stage I processing category, 123Stage II processing category, 123Standard Industrial Classification, 126standardization checks, 40

ace_get_stats(), 44state

get_lastline, 39suffix

query field, 85, 89suggestion lists, 78

ace_findf() parameters, 30consolidation, 77filtering, 78, 79get components, 73get number of suggestions, 74get one suggestion, 71how to customize, 78how to process, 68range entry, 75set chosen suggestion, 76set options, 80

SuiteLink, 151, 152Sun Microsystems

Sun/OS, 8Sys Test processing category, 123

Ttable

No Stats, 113termination, 45

ace_cfg_close(), 25

ace_ll_term_query(), 102ace_ll_term_show(), 102ace_term_addr(), 46ace_term_query(), 92ace_term_show(), 92close auxiliary files, 49

Uunit designator

query field, 85, 89Unix compile and link, 8USPS

finance areas, query field, 89USPS Address Conversion Statistics file, 50

Vvacant address indicator

DSF2 output field, 114vacant indicators, 114Visual Basic, 8, 17, 22, 47Visual C++, 8

WWindows, 8working directory, 52

ZZ4Change, 18

ace_set_z4c_check_date(), 64ace_z4_zip4_changed(), 65call sequence, 18get date, 37set mode, 56set pathname, 52

ZCF directoryget date, 37open and close, 49queries, 82set pathname, 52

ZIP Codeget city and state, 38get_lastline, 39

ZIP+4query field, 89

ZIP+4 directoryget date, 37open and close, 49set pathname, 52

ZIP+4 directory retrievalbrowse fields, 85create query structure, 88get next query, 91get one field, 85load query structure, 89search criteria, 89shutdown, 92


Documents

800c_ace_lr_en