QuickAddress Pro API - QAS.com

QuickAddress ProAPIQAS Ltd.

Spain: Claritas CustomersSpain: Non-Claritas CustomersRTA Claritas España, S.AQAS LtdRosa de Lima 1 bisGeorge West HouseEdificio Alba2-3 Clapham Common North Side28290 Las Matas (Madrid) LONDONESPAÑASW4 0QLUNITED KINGDOMTechnical SupportTechnical SupportTel: +34 91 630 71 31 Tel: +44 (0) 20 7498 7788Fax: +34 91 630 17 78 Fax: +44 (0) 20 7498 0303E-mail: soporte.qas@claritas.es E-mail: es.support@qas.comSingaporeFor all other countries80 Raffles Place QAS Ltd#35-00 UOB Plaza 1 George West HouseSingapore2-3 Clapham Common North Side04862 LONDONSW4 0QLUNITED KINGDOMTechnical SupportTechnical SupportTel: +65 6248 4771 Tel: +44 (0) 20 7498 7788Fax: +65 6248 4531 Fax: +44 (0) 20 7498 0303Email: sg.support@qas.comE-mail: support@qas.comQAS Websitewww.qas.comVersion 4, Revision 10

Which Search Method Should I Use? ............................................................ 20Typedown Searching...................................................................................... 20Searching for a Residential Address .................................................. 21Searching for an Organisation Address.............................................. 21Searching for a PO Box Address........................................................ 21Typedown Troubleshooting ............................................................... 22Single Line Searching .................................................................................... 22Wildcard Searching ............................................................................ 23Searching with Partial Addresses....................................................... 24Identifying Address Elements ............................................................ 25Retrieving DataPlus Information ................................................................... 26Names and Business DataPlus ........................................................... 26Barcodes ............................................................................................. 27Alias Matching ............................................................................................... 27Recode Messages ............................................................................... 28Pro User Interface.................................................................... 29Pro Dialog ...................................................................................................... 29Menu Bar............................................................................................ 30Toolbar ............................................................................................... 31Search Area ........................................................................................ 32Results Area ....................................................................................... 33Partial Address Bar............................................................................. 33Status Bar ........................................................................................... 34Picklists of Returned Addresses..................................................................... 35Picklist Symbols................................................................................. 36Typedown Search Results .................................................................. 37Single Line Search Results................................................................. 38Returning an Unrecognised Address.............................................................. 39Address Edit Screen ....................................................................................... 40Setting Pro Options ........................................................................................ 41Selecting a Search Method................................................................. 41Setting Search Options ....................................................................... 42Selecting a Country Database ............................................................ 43Selecting an Address Layout.............................................................. 44Data Types ............................................................................... 47Main Data Types ............................................................................................ 47Function Return Values...................................................................... 47Parameters (Input) .............................................................................. 48Parameters (output) ............................................................................ 48Calling Functions from Languages Other Than C ......................................... 48NULL Termination ............................................................................ 49ii • ContentsQuickAddress Pro API

Padding .............................................................................................. 49Passing by Value or by Reference ..................................................... 50Returned Strings ................................................................................ 50Example of Data Types.................................................................................. 51Primary API Function Reference ........................................... 53Pseudocode Example of Pro API................................................................... 53Main Function.................................................................................... 53Display Error Function ...................................................................... 56User Action Function......................................................................... 56Display Results Function ................................................................... 56Select Result Function ....................................................................... 57Return Address Function ................................................................... 57Handling Errors.............................................................................................. 58API Instances ................................................................................................. 59Flags Returned ............................................................................................... 60Automatic Stepping and Formatting.............................................................. 61Asynchronous Searching ............................................................................... 63Primary API Function Reference................................................................... 65General Error Scenarios (All Functions) ........................................... 69QA_CancelSearch.............................................................................. 70QA_Close........................................................................................... 71QA_EndSearch .................................................................................. 72QA_ErrorMessage ............................................................................. 73QA_FormatExample.......................................................................... 74QA_FormatResult.............................................................................. 76QA_GenerateSystemInfo................................................................... 78QA_GetActiveData............................................................................ 79QA_GetActiveLayout........................................................................ 80QA_GetData ...................................................................................... 81QA_GetDataCount............................................................................. 83QA_GetEngine................................................................................... 84QA_GetEngineOption ....................................................................... 85QA_GetExampleCount...................................................................... 88QA_GetFormattedLine ...................................................................... 90QA_GetLayout................................................................................... 93QA_GetLayoutCount......................................................................... 95QA_GetLicensingCount .................................................................... 96QA_GetLicensingDetail .................................................................... 98QA_GetPrompt ................................................................................ 101QA_GetPromptStatus ...................................................................... 103QA_GetResult.................................................................................. 105QA_GetResultDetail........................................................................ 109QuickAddress Pro APIContents • iii

QA_GetSearchStatus........................................................................ 114QA_GetSearchStatusDetail.............................................................. 117QA_GetSystemInfo.......................................................................... 122QA_Open ......................................................................................... 124QA_Search ....................................................................................... 126QA_SetActiveData........................................................................... 128QA_SetActiveLayout ....................................................................... 129QA_SetEngine.................................................................................. 131QA_SetEngineOption....................................................................... 133QA_Shutdown.................................................................................. 136QA_StepIn........................................................................................ 137QA_StepOut ..................................................................................... 139User Interface API Function Reference ............................... 141Handling Client/Server Errors...................................................................... 141UI API Function Reference.......................................................................... 142QAProWV_UICountryCount........................................................... 144QAProWV_UIGetActiveCountry .................................................... 146QAProWV_UIGetActiveLayout...................................................... 148QAProWV_UIGetCountry............................................................... 150QAProWV_UIGetFlags ................................................................... 152QAProWV_UIGetLayout................................................................. 153QAProWV_UIGetResult.................................................................. 155QAProWV_UILayoutCount............................................................. 157QAProWV_UILayoutLineElements ................................................ 158QAProWV_UIResultCount.............................................................. 161QAProWV_UISearch....................................................................... 162QAProWV_UISetActiveCountry..................................................... 163QAProWV_UISetActiveLayout....................................................... 165QAProWV_UISetFlags.................................................................... 167QAProWV_UIShutdown ................................................................. 168QAProWV_UIStartup ...................................................................... 169Low-Level System Functions ...................................................................... 173QAErrorMessage.............................................................................. 174QAErrorLevel................................................................................... 175QASystemInfo.................................................................................. 176API Configuration .................................................................. 181Configuring the API..................................................................................... 181Format of a Configuration File .................................................................... 182Licensing ...................................................................................................... 183Element Codes ............................................................................................. 183Configuration Settings ................................................................................. 184iv • ContentsQuickAddress Pro API

Qawserve Settings............................................................................ 184Qaworld Settings.............................................................................. 193User Interface Configuration................................................ 197Configuration Editor.................................................................................... 197Layout Manager........................................................................................... 199Creating and Naming Layouts ......................................................... 201Copying, Deleting and Renaming Layouts...................................... 202Editing an Address Layout .............................................................. 202DataPlus Formatting ........................................................................ 209User Interface Options................................................................................. 210Database Manager........................................................................................ 212Country Database Information......................................................... 214Qaworld Settings.......................................................................................... 214Prompts ............................................................................................ 214Appendix A ............................................................................ 217Error Code Listing ....................................................................................... 217Index....................................................................................... 239QuickAddress Pro APIContents • v

IntroductionWhat is the Pro API?The QuickAddress Pro API is a suite of functions that you integrate into yourown applications. Once successfully integrated, Pro takes partial addressinformation that you type in and returns a full, valid address.You have been supplied with two versions of the API: the Primary (low-level)API and the User Interface API. This manual deals with everything whichrelates to the Pro Primary API and the User Interface API functions, testharness, front-end screens and Configuration Editor.If you are using the Pro API as a client with the QuickAddress server, pleaseread the accompanying QuickAddress Pro Client/Server Guide first.Pro API uses a separate database of address information for each country – youcan switch between these databases to retrieve address information fromseveral different countries. You can also make use of two different searchtechniques to find the address that you want.The remainder of this chapter helps you get started with installing andintegrating Pro API and country databases. The other chapters in this guidedeal with verifying your installation, methods of searching with Pro API,details of the QuickAddress data types, low-level system functions, and ProAPI functions, how to use the User Interface, and how to configure Pro API toreturn addresses in the way that you want.QuickAddress Pro API Introduction • 1

ConventionsThe table below defines the style conventions used to distinguish features ofPro API in this manual.Exampleint QAProWV_OpenConventionSample code, function prototypes andpseudocode look like this.Notes and warnings appear next to thisicon.viHandlePress EnterPress Cursor upQAProWV_UIStartupParameter names are shown in italics(when not part of sample code).Key presses are shown in bold (Enter isthe same as Return or Carriagereturn).API functions appear in bold type (whennot part of sample code).Accompanying DocumentationThis section provides a comprehensive list of the documentation supplied withPro, and where it can be located.Country Information GuideA Country Information guide is supplied with each country data set that youpurchase. This guide provides country specific information and search tips foreach country database, and should be used in conjunction with the otherdocumentation supplied with Pro.Under Windows, you have the option to install the Country Information guideduring data installation. The guide is installed to C:\ProgramFiles\QAS\Country Information Guides by default. If you choose not to installthe guide, it can be accessed from the Docs folder on the data CD.2 • Introduction QuickAddress Pro API

Under UNIX, you should copy across the Docs folder to a location of yourchoice.API HelpWindows users have access to comprehensive assistance on the Pro API,contained within a Help file. This file can be accessed from the QuickAddressPro API 4.00 program group in the Start menu.Configuration Editor HelpFor Windows users, the Configuration Editor Help file is supplied with yourcopy of Pro. This file can be accessed by:• pressing F1 when using the Configuration Editor;• selecting Contents and Index from the Help menu when using theConfiguration Editor.Client/Server DocumentationIf you have purchased the Client/Server version of Pro API, you are suppliedwith a Client/Server manual and an Administrator Console Help file.An electronic copy of the Client/Server manual can be accessed via theindex.html file, which is located in the Docs folder on the Pro installation CD.The Administrator Console Help file can be accessed by:• pressing F1 when using Pro;• selecting Contents and Index from the Help menu on theAdministrator Console User Interface.New Features DocumentThis document is stored in electronic format and details the new features in thisversion of Pro. It also highlights key integration and compatibility issues ofwhich you should be aware.The New Features document can be accessed via the index.html file, which islocated in the Docs folder on the Pro Installation CD.QuickAddress Pro API Introduction • 3

Technical Upgrade GuideThis document provides a step-by-step guide to upgrading an existinginstallation of Pro. It is aimed at technical personnel responsible for installingand administrating the product.The Technical Upgrade guide can be accessed via the index.html file, which islocated in the Docs folder on the Pro Installation CD.Readme FileThis file contains a section on the utilities supplied with Pro, a revision historyof Pro, and product related information that did not make it into the printed oronline documentation.By default the readme.txt file is installed to C:\ProgramFiles\QAS\QuickAddress Pro API.InstallationIf you are installing Pro API as a client, please follow the setup instructions inthe QuickAddress Pro Client/Server manual.WindowsPro API has been supplied to you on a CD-ROM, and comes with aninstallation program called setup.exe. When you run setup.exe, the Pro APIlibraries, configuration files and Help files are installed to the location of yourchoice (default C:\Program Files\QAS\QuickAddress Pro API), and thedatabases you have purchased are installed to a separate data directory (defaultC:\Program Files\QAS\Data)QuickAddress Pro is available for Windows 95, 98, ME, NT4, 2000 and XP,and UNIX. The disk space required is country-dependent, and the installationprogram will tell you how much space you need.4 • Introduction QuickAddress Pro API

To run the setup program, follow these steps:1. Insert the QuickAddress Pro API CD into your CD-ROM drive.2. Select Run… from the Start menu.3. In the dialog box that appears, type d:\setup, where d is the drive letterfor your CD-ROM drive, and press Enter.Once the installation program starts, follow the on-screen instructionsto install the API.For a full list of the files installed, see the file readme.txt.UNIXThe QuickAddress Pro API CD contains both shared object and static libraryversions of Pro. Copy the contents of the relevant folder to the location of yourchoice. The readme.txt file on the CD lists the files required for eachinstallation.Data Files and Country IdentifiersYou have been supplied with at least one country database. Each countrydatabase that you have purchased is comprised of three or four files.The files you get for each database are:.dts.tpx.zlb (only present for some data sets).zlxIf you have purchased DataPlus information, an additional file will also beincluded with your data. DataPlus files have the following naming convention. dap.The base filenames are three characters long. The UK base filename is ‘gbr’,The American is ‘usa’, the Dutch is ‘nld’ and the Australia one is ‘aus’. Thebase filenames are derived from unique three-letter country identifiers forcountry datasets, which are used throughout the API and its documentation.QuickAddress Pro API Introduction • 5

Data UpdatesQAS provides periodic updates of country databases as and when updated datais available. These updates are supplied to you on CD-ROM; follow theinstructions in the installation program to replace your existing countrydatabases.Country databases expire after a certain period of time, at which point you mustinstall an update. The low level API function QA_GetLicensingDetail (seepage 98) tells you how many days are left before a country database expires.By default, a dialog will be displayed when you start Pro, which lists all thedatasets that are due to expire soon. You can disable this dialog using theqaattribs_NOLICENSINGDLG flag (see page 172).Getting Started with Pro APIThis section provides a few hints on how to start integrating Pro API with yourown application.The basic steps you should go through to aid a successful integration are asfollows:1. How Pro API WorksThe section of the manual which starts on page 19 describes how ProAPI searches on your addresses. Reading this should clarify the valuesthat are returned by some of the API functions.2. The Test HarnessRunning one of the test harnesses supplied with the API should verifythat you have installed the API correctly. It will also give you an idea ofwhat Pro API can do, and the type of results it can produce.3. Pseudocode and Sample CodeThe pseudocode example for the Primary API on page 53 demonstratesa possible interpretation of the API functions. Samples are available inC and Visual Basic; see the readme.txt file for the locations of this code.6 • Introduction QuickAddress Pro API

4. Using the API FunctionsThe listing of Pro API functions starts on page 51. You should choosewhether the Primary API or the User Interface API is best suited to yourrequirements.It is recommended that you integrate the API in stages, beginning withthe QA_Open, QA_Close and QA_Shutdown functions, followed byaddress search and retrieval facilities. Any other functions can be addedin the appropriate places.You should also make use of the system functions, especiallyQAErrorMessage and QAErrorLevel or QA_ErrorMessage. Thesefunctions enable you to see the description and severity of any errorsthat occur, and as such should be called after any function that hasreturned an error. A full list of error codes starts on page 217.When you wish to run your integrated application, you should ensurethat the following QAS files are in the same directory as the applicationexecutable:Primary APIqaworld.iniPro API configuration fileqawserve.iniData file locations and otherapplication configurationsettingsqaupied.dllPro API DLLqaupied.revPro API DLL revision fileqaupied.0xxPro API DLL languageresource file (where ‘xx’represents the language code)UI APIqaworld.iniPro API configuration fileqawserve.iniData file locations and otherapplication configuration settingsqauwved.dllPro API DLLqauwved.revPro API DLL revision fileqauwved.0xxPro API DLL language resourcefile (where ‘xx’ represents thelanguage code)QuickAddress Pro API Introduction • 7

Primary APIUI APIqauwv001.dllPro API (UI) language GUIresource file (English-UnitedStates)qalcl.datLocale information fileqalicn.iniLicence information fileqalcl.datLocale information fileqalicn.iniLicence information file5. Configuring your APIBefore running your integrated API, you need to give Pro API thefollowing information:• The format of your output addresses.• The whereabouts of your country database(s).This information should be specified in the configuration file or in theConfiguration Editor. Details of how to do this start on page 181 for thePrimary API, and page 197 for the User Interface API.You can test your integration by trying some of the searches on the Search Tipssheet supplied with each country database.Which Version of the API Should I Use?If you are running Windows, and the Pro front-end meets your input and outputrequirements, it is recommended that you integrate the User Interface API.This is the easiest method of gaining maximum functionality with theminimum of effort, as programming with these functions is simpler.8 • Introduction QuickAddress Pro API

Pro User Interface API can be integrated with a minimum of five functions:• QAProWV_UIStartup (page 169)• QAProWV_UISearch (page 162)• QAProWV_UIResultCount (page 161)• QAProWV_UIGetResult (page 155)• QAProWV_UIShutdown (page 168)These functions start up and shut down the Pro API, perform searches andreturn full addresses. If you wish to provide additional functionality, such asviewing and selecting address layouts and country databases, the appropriatefunctions can be added to your program.The User Interface API is available for Windows 95, 98, ME, NT4, 2000 andXP.If, however, you need to use your own front-end screens, or you are runningUNIX, you should integrate the Pro Primary API.The Pro Primary API provides you with the functionality you need to integratePro seamlessly into your application. It is up to you how searches areperformed and results are returned, and you are responsible for any userinterface that is required. Although these functions require more programmingon your part, they also give you great flexibility in integrating the API.Even if you choose to integrate the Pro Primary API, you might find it usefulto look at the sample code provided for the User Interface API, to get an ideaof the available functionality.The Pro Primary API is available for Windows 95, 98, ME, NT4, 2000 and XP,and UNIX.QuickAddress Pro API Introduction • 9

Primary API SampleCodeTesting your Primary API InstallationThe Primary API is supplied with a simple text-based application, calledqs_sl.exe (qs_sl on UNIX), and with sample code. Together these can be usedto verify that you have installed Pro API correctly, and to demonstrate some ofthe API’s key functionality.The test harness is not intended to be used as a commercial application.The test harness enables you to obtain matching addresses and picklists frominput address information that you type in on the command line.The examples in this section use the C version of the test harness. See thereadme.txt file for details of other test harnesses and sample code. OnWindows, the VB test harness is available either as qs_vb.exe in the directorywhere the Pro program is installed, or as a shortcut from the Start > Programsmenu. If the VB test harness is used, you must first enter a search and pressSearch to make the UI dialog pop up.Sample CodeThe sample code should be seen as the starting point for integration, and shouldbe tailored according to the type of integration that you are performing.Sample code is used to demonstrate best practice and includes the features thatare likely to be required by the majority of users.QuickAddress Pro API Primary API Sample Code • 11

The single-line sample code is applicable for environments where it is notpossible to detect and act upon characters as you type. This means that thepicklist is not automatically updated as you enter refinement text, and allprocessing (searching, stepping in etc.) is performed once you have pressedEnter.If you are running the Primary API test harness in client/server mode, any lossof connection between client and server results in the active search beingcleanly aborted. The next search attempt triggers a reconnect, switching to anydefined backup servers if available. Refer to the Client / Server documentationfor more information.Searching with the Test HarnessIf you are using Windows, run the test harness from the shortcut in the ProgramGroup which was created when you installed Pro API.The test harness appears, looking similar to this:To perform a Single Line search, follow these steps:1. Press Enter to select the default country. In the example above, this isGBR.Alternatively, type ? and press Enter to display a list of all countrieswith their identifiers. Type the relevant code (for example, DEU forGermany, AUS for Australia) and press Enter to select the relatedcountry database.12 • Primary API Sample Code QuickAddress Pro API

2. Once you have selected the country data you want to work with, thescreen will look like this:3. Enter a search string, separating each part from the next with a comma,and press Enter. For example (if you are using the GBR countrydatabase):linden gardens, londonFor examples of searches from other country databases, see the Search Tipssheet supplied with each database.This is what the test harness returns:There are 199 possible matches, as shown by the Match Count.4. Type "30" and press Enter to refine the picklist and to therefore reducethe number of matches. Press Enter at any prompt to remove the refineand return the list to the way it was.QuickAddress Pro API Primary API Sample Code • 13

There are now three matches displayed. Note that they are numberedfrom 1 to 3 in the picklist.5. Type #1 and press Enter to select the first picklist entry.The full address is returned:If your text appears odd, this may be because any diacritics in the text (forexample, accents and umlauts) are not displaying correctly in the DOSConsole. Refer to “OemCharacterSet={text string}” on page 195 forinformation about how to resolve this.14 • Primary API Sample Code QuickAddress Pro API

User Interface APISample CodeTesting Your UI API InstallationThe Pro User Interface API is supplied with a very simple application calledqs_ui.exe, and with sample code. Together these can be used to verify that youhave installed Pro API correctly, and to demonstrate some of the API’s keyfunctionality.The test harness enables you to obtain matching addresses and picklists frominput address information that you type in.See “Sample Code” on page 11 for more information about the purpose of thesample code. The UI integration scenario is the preferred solution on Windowsas it uses the standard Pro dialog, therefore minimising the size and complexityof the integration, and meaning that you have access to both Single Line andTypedown engines, as well as the standard User Interface functionality(selection of layouts and databases; menus; toolbars etc.).If you are running the UI API test harness in client/server mode, any loss ofconnection between client and server results in the display of appropriatewarnings. Refer to the Client / Server documentation for more information.The examples in this section use the C version of the test harness. See thereadme.txt file for details of other test harnesses and sample code. The VB testharness is available either as qs_uivb.exe in the directory where the Proprogram is installed, or as a shortcut from the Start > Programs menu. If theVB test harness is used, you must first enter a search and press Search to makethe UI dialog pop up.QuickAddress Pro API User Interface API Sample Code • 15

Running the Test HarnessRun the test harness from the shortcut in the Program Group which was createdwhen you installed Pro API.The test harness appears, looking similar to example shown below:This is the Pro User Interface. For a comprehensive description of all of itsaspects and options, see the chapter “Pro User Interface” which starts onpage 29.The next two sections describe undertaking a Typedown search andundertaking a Single Line search with the test harness.A Typedown SearchIn the example below, you are searching for 7 Sand Lake Road in Orlando, FL,USA.For examples of searches from other country databases, see the Search Tipssheet supplied with each database.1. Select the Typedown search button on the toolbar or press Ctrl+T.2. Enter this search string:16 • User Interface API Sample Code QuickAddress Pro API

orlandoThe test harness starts searching as soon as you type the first character.After typing ‘orlando’, this is what the test harness returns:There is only one match for this search string.3. Click the Select button (or press Enter) to step into the picklist item.4. Type ‘sandl’.In this example it is the second match in the list that you want.5. Use the ↓ cursor key to move the focus to Sand Lake Rd Orlando FL.Click the Select button (or press Enter) to step into Sand Lake Rd.There are too many matches to display in a picklist.6. Type ‘7’.This picklist is returned:The match you want is at the top of the picklist.Pro also returns several other matches, and, where appropriate, hassplit the matches into odd and even number ranges.7. Click on the Select button or press Enter.The full address is returned to the address edit screen.8. Accept the search to return the result from the API.QuickAddress Pro API User Interface API Sample Code • 17

A Single Line Search1. Click on the Single Line search button on the toolbar, or press Ctrl+S.2. Enter a search string, separating each part from the next with a comma,and select the Search button (or press Enter). For example (if you areusing the Australia country database):65 Rushton St, Carnarvon, WAFor examples of searches from other country databases, see the Search Tipssheet supplied with each database.This is what the test harness returns:As the test harness has only found one address which precisely matchesyour search criteria, it returns it directly to the address edit screen (seepage 40).3. Accept the search to return the result from the API.18 • User Interface API Sample Code QuickAddress Pro API

Searching with ProSearching MethodsPro has two search modes. These are:• Typedown searching• Single Line searchingTypedown searching starts with the most general address element and, oncethat has been found, moves on to more specific parts of the address. Forexample, with UK and Sweden data, this involves typing in the first few lettersof a place or postal code, then selecting the matching item from the picklist thatis returned and typing the first characters of a street or building number, PObox or organisation name within the place or postal code that you select.Typedown is the more useful search option when you are sure of the addressinformation. For example, if you are taking address details over the phone, youcan enter the caller’s postal code and then, if required, you can search for thecorrect street and building number.Single Line searching requires you to type in two or three address elements,each separated by a comma, in the order that they would appear on an envelope(for example, the street name followed by the town).Single Line searches can use a variety of techniques to return the correctaddress from incomplete or misspelled information. (See the examples in“Single Line Searching” on page 22 for details of these). For example, if youwere using Pro to verify addresses sent to your company on coupons, where thehandwriting might be illegible, it would be better to use Single Line searching.Either of these methods allow you to capture a full address with just a fewkeystrokes.QuickAddress Pro API Searching with Pro • 19

Which Search Method Should I Use?It is strongly recommended that you integrate Typedown searching as theprimary searching method, and use Single Line searching as a secondaryoption, especially if you have multiple country databases. This is becauseTypedown provides a consistent method of entering search information acrossall countries (for example, a postal/ZIP code followed by a street name), andreduces the likelihood of errors by verifying data as it is entered.While Single Line searching allows you to enter any combination of addresselements, you need some knowledge of each country’s address information inorder to decide which part of the address will return the most search results, andhence provide optimum performance. For example, entering a postal code fora UK address will return an average of fifteen possible full address matches.However, an Australian postal code could cover several localities (whichcorresponds to thousands of addresses).Typedown SearchingIn Typedown searching, you start by typing the most general address element(which can be a postcode, county, town or locality in the United Kingdom) and,once that has been found, you move on to more specific parts of the address.Pro API searches on the string that you enter, which can be as little as onecharacter. When you use Typedown searching, Pro will always look for anexact match first. If an exact match is found, and other close matches are belowthe match threshold, all of the matches are returned. However, if the closematches exceed the match threshold, only exact matches are returned.With both Typedown and Single Line searching, there is no need to use capitalletters when you type. Nor do you need to include spaces, as Typedownsearching ignores them.Refer to the Primary API Test Harness chapter on page 11 for specificexamples of Typedown searching.20 • Searching with Pro QuickAddress Pro API

If you know the postal code or ZIP code for an address, it is usually faster andmore efficient to type this in, than it is to use other address elements, such as atown name. There is no need to insert the hyphen between the ZIP code andZIP+4.The following sections describe the types of search you can perform using theTypedown mode.Searching for a Residential AddressThis type of search usually involves three stages.Typically, after an initial search on a place or postal/ZIP code, Pro will look forstreet names. Once you have selected the street name that you want, you canenter a property number to return the full address.You cannot type in the property number followed by the street name, as youcan with Single Line searching (see page 20), because typedown searchescannot match on numbers until you have selected a street name.Searching for an Organisation AddressThis type of search usually involves two stages. After the first stage ofsearching on a place name or postal/ZIP code, Pro API will look fororganisation and street names. Once you have found the organisation that youare looking for, Pro API returns the name and full address.Searching for a PO Box AddressThis type of search usually involves three stages. After the first stage ofsearching on a place name or postal/ZIP code, Pro will look for the PO Boxtype. Once you have stepped into this, you can enter a PO Box number to returnthe final address.Typedown searching for PO Box addresses is not recommended for searchinglarge address databases; for example, searching United States data for a POBox address can be slow, if your first stage search contains a large number ofmatches (for example, a state).QuickAddress Pro API Searching with Pro • 21

Typedown TroubleshootingIf you misspell any address element in Typedown searching, Pro API will notbe able to find it. If you are uncertain of the spelling of an address, it is betterto use the Single Line searching method.Single Line SearchingSingle Line searching works in the opposite way to Typedown searching: youtype in address elements in the order that they would appear on an envelope,starting with the most specific (for example, a house number and / or streetname) and move onto more general elements (for example, a town or postalcode).Pro allows you to search on any address element or combination of addresselements that are separated by a comma. Refer to the Primary API Test Harnesschapter on page 11 for specific examples of Typedown searching.For example:church st,abermain,nsw (Australian address)You can use any mixture of upper and lower case characters, as Pro does notdifferentiate between upper and lower case text.When you send your search to the API, each component of the information youhave typed in becomes a subject of the search.Single Line searching is also useful if your address information contains one ormore spelling mistakes. There is still a high likelihood that Pro will retrieve theaddress that you want. For example, when you typePartley Stwhich doesn’t exist in the Australia database, Pro still returns Bartley St,Hartley St and a number of other possibilities.The results from this example may vary depending on the “Searching options”that you have specified in Pro. See page 42 for further details.22 • Searching with Pro QuickAddress Pro API

Wildcard SearchingPro API Single Line searching supports two wildcards. Wildcards are specificcharacters that can be inserted in the search string to signify one or moreunknown characters.The two types of wildcard are:• the question mark wildcard (?)• the asterisk wildcard (*)The difference between the two is that the question mark represents a singlecharacter, and the asterisk can stand for any number of characters.If you use several wildcards in a search, you run the risk of making the searchtoo broad. This may result in a considerably extended search time, or possiblyno returned matches.Question Mark WildcardWhen you search with a question mark wildcard, Pro API produces a list of allmatching streets and postal/ZIP codes. For example:If you enter:Pro API retrieves:?146? A list of all US streets with ZIPcodes beginning 114, 214, 314etc. Similarly, all ZIP codesending with 461, 462 and so on.13 Clarke St, 3?67 Two matching premises at: “13Clarke Street, Abbotsford, VIC3067”, in Australia.You can use the question mark wildcard on any type of address elementincluding, postal/ZIP codes, street names, towns and localities.QuickAddress Pro API Searching with Pro • 23

Asterisk WildcardThis wildcard replaces any number of characters at the end of an addresselement. For example:If you enter:Rose *, WickenburgHighland Ave, Trent*Pro API retrieves:Any address starting with“Rose” in a place calledWickenburg, including RoseRd, Rose St, Rose Ave and soon.Places beginning with “Trent”.This could include Trentbridge,Trentworth, etc.Keyword SearchingYou can also use the asterisk to look for certain key words. To do this, precedethe first address element with the asterisk wildcard. For example, the search“*park, victoria” returns all addresses in the state of Victoria containing theword “park”.This type of search is especially useful if you are looking for a particular typeof organisation or institution; for example, banks, colleges, hospitals etc. Forexample, the search “*university,qld” looks for any university in Queensland.Searching with Partial AddressesA partial address consists of one or more address elements, separated bycommas. One such partial address element might be sufficient to identify thecomplete address if the organisation, house or street name is unusual.You should never need to enter a full address as Pro is designed to identifyaddresses even when you only enter certain elements of an address, or useabbreviated forms of elements, such as “St” and “Rd” and so on.The address elements available for the databases that you have purchased areexplained in the country-specific documentation supplied with your data.24 • Searching with Pro QuickAddress Pro API

You can use any combination of address elements in any order. If there arediscrepancies between the spelling of the entry and the spelling as recorded inthe country database, Pro usually manages to find the required address.If your definition is not specific enough, the search for matching addresses cantake too long or can result in too many addresses to be useful. For exampleGreen*followed by a town name would retrieve:• all matching organisations (Greenwood Motors, Green Acres HealthFarm, etc.);• all matching building names (Greenford Towers, Greendale Heights,etc.);• all matching street names (Green Lane, Greenfield Street, etc.);• all matching place names (Greenslopes, Greenwich, etc.).Identifying Address ElementsYou can limit your search to make it more efficient, by identifying whichaddress elements one or more parts of your address represents.Thus you can identify a part of an address as, for example, a street name or anorganisation name. If you tag part of the address as a post town, Pro API onlylooks through its list of post towns when it endeavours to match that part of theaddress.The address elements that can be tagged in the databases that you havepurchased are explained in the country-specific documentation supplied withyour data.QuickAddress Pro API Searching with Pro • 25

Retrieving DataPlus InformationQuickAddress DataPlus can provide a wide range of information relating to anaddress, as a supplement to the Pro API. Currently, DataPlus information isonly supplied with certain country databases; if you do not have DataPlus, youcan skip this entire section.DataPlus information is contained in data sets. Each piece of informationrelates to a general area, such as a locality or postal/ZIP code, or, when the datarequires higher resolution, it can be related to the delivery point (letter box).)DataPlus handles the information in terms of a code and its related description(if there is one). For example, a data set containing grid references would onlyinclude codes.DataPlus details can only be viewed once you have selected and displayed afull address from Pro API, and configured your layout to display DataPlusitems. For example, if you have the Australia country database with theassociated latitude and longitude DataPlus set, and you perform a Typedownsearch on “north sydney”, followed by “miller” and then “314”, Pro finds thisaddress:314 Miller Street,NORTH SYDNEY NSW 2060-33.8313 151.208If you want to retrieve DataPlus information with your addresses, you shouldconfigure your address layout so that it contains lines specifically for DataPlus.See the AddressLineN keyword on page 187 for further details of setting upDataPlus for the Primary API. For the User Interface API, see “DataPlusFormatting” on page 209.Names and Business DataPlusThis functionality is currently available for United Kingdom data only.You can configure a number of Names and Business DataPlus sets. See“DataPlus Formatting” on page 209 for further details about how to do this.Refer to the relevant Country Information Guide for a complete listing ofDataPlus sets.26 • Searching with Pro QuickAddress Pro API

BarcodesIf you have the Australian, American, Netherlands or United Kingdom countrydatabases installed and you wish to add barcodes to your addresses, thisfunctionality is available as a DataPlus set.The font used for the barcodes is installed with QuickAddress Pro. If thebarcode appears as a list of numbers, ensure that the relevant font from thefollowing list is in your standard Windows font directory:• the 'QuickAddress 4State Barcode' (for Australia);• the 'USPS POSTNET Barcode' (for the USA);• the CustomerCode Plain (True Type)' (for the Netherlands and theUnited Kingdom).For the Primary API, you will see the barcode as a list of numbers.Alias MatchingThis term indicates an alias match or a recode message. It may be that anaddress will be returned with a different postcode from the one that youentered. This means that although Pro has recognised the information enteredby the user as a possible version of the name or address, it has replaced it withthe official (postally-correct) version from the country database.An alias match would occur, for example, if you entered a street and locality,where the locality is not necessary to the address and has been replaced by thetown.There are several other reasons why someone might not enter an addressaccurately according to the postal data:QuickAddress Pro API Searching with Pro • 27

TypoChanged Postal CodeStreet / Town / NameChangesNew or Unofficial NameAddressDisputed AddressCounty ConfusionName AbbreviationThe user may make a mistake typing in their name oraddress. In this case, they may require help to enterthe correct address.The Post Office may change the postal code of anexisting address. See “Recode Messages” onpage 28.The town council and the post office may be out ofsynchronisation about changes to the name of astreet or town, or to the names of residents.The address may have been created after the last dataupdate you received, or the tenant may have put anumber on their door without telling the post office(for example, when splitting up a house into flats).The tenant may have changed their name withouttelling the post office. In this case, the user needs tobe able to specify their name and address even if itmay not be on the official list (no list is continually100 per cent accurate).For example, someone living in Londonderry mightsay that they live in Derry. In this case, the address ismatched exactly since Derry is stored as an alias, butthe returned formatted address will be inLondonderry.For example, United Kingdom addresses will ofteninclude the postal county (not necessarily the ancientcounty) of the post office town (rather than thedelivery point). However, the post office does notrequire county names.For example, Michael Smith may prefer to be knownas Mike Smith, and may use this name incorrespondence. In cases like this, “Mike” would bestored as an alias for “Michael”.Recode MessagesWhen an alias match results in the recoding of a postcode, locality or street, thischange is highlighted. An alias match would also occur if the postal code,locality or street has recently been changed and Pro is aware of this; forexample, if you enter the old postal code, it will automatically be replaced bythe new one.28 • Searching with Pro QuickAddress Pro API

Pro User InterfacePro DialogThis chapter is relevant for Windows users working with the User InterfaceAPI only.The top-level interface of the User Interface API is the Pro Dialog. This dialogis responsible for accepting a search string from the user and displaying theaddress that Pro finds.If there are two or more results that match with your search string, Pro displaysa picklist from which you can make a selection.If you are in Single Line mode, the search string you enter in the Pro Dialogcan consist of any combination of address elements. The address elements youcan use are listed in the country-specific documentation supplied with eachcountry database that you have purchased.You also have the options of selecting which searching facility you want to useand selecting an address layout to work with.This section covers the ways in which you can set up the user interface, anddetails every option available to you.The full Pro Dialog looks similar to this:QuickAddress Pro API Pro User Interface • 29

Some of the options on the user interface might not be available to you. Theoptions available depend on what has been specified in the vlFlags parameterof QAProWV_UIStartup (see page 169), or what has been specified in theConfiguration Editor (see page 197).There are six parts to the Pro Dialog, which are all described in this section.Menu BarThe menu bar consists of five drop-down menus, from which you can selectevery option available with Pro (when full functionality is enabled). The menuoptions can be summarised as follows:ProSearchDatabaseViewMinimise or exit from Pro.Start a new search, step back to the previous searchlevel, select the searching method and specify advancedsearch options.Select the country database you wish to use. This menuoption only appears if you have installed more than onecountry database.Select an address layout to work with, change thedisplay language, show or hide the menu bar, toolbarpartial address bar and informational prompts.30 • Pro User Interface QuickAddress Pro API

HelpThis feature is disabled. You can access the API manualfrom the QuickAddress Pro API 4.00 program group(accessible through the Start menu).To view the options on a menu, either click on the menu name, or hold downthe Alt key and press the key of the underlined letter in the menu name. Forexample, to select the Search menu, press Alt+S.To hide the menu bar, click the View menu and select Menu. To make the barvisible again, click on the envelope on the title bar and select Show menu fromthe resulting menu.ToolbarThe toolbar contains the following options (from left to right):New searchBackTypedownsearchSingle LinesearchSelect layoutDatabaseClear the existing search and start a newone.Step back to the previous search level.Select Typedown searching.Select Single Line searching.Choose the address layout that you want touse.If you have more than one countrydatabase installed, you can select thedatabase you want to search with from thisdrop-down list.QuickAddress Pro API Pro User Interface • 31

You can find out the function of a button on the toolbar by placing the cursorover it and holding it there for a few seconds. A short description of the buttonappears.To hide the toolbar, click the View menu and select Toolbar. Repeat thisaction to make the toolbar visible again.Search AreaUse the search area to type in the address elements that you know inpreparation for a search.The search area has two views. The view you see depends on the search methodthat is selected.Search area for Single Line searching:Search area for Typedown searching:The Typedown refinement prompts above the Search field provide specificpointers to the type of information that should be entered at each stage; forexample, Enter postcode or place.With Single Line searching, you type in as much of the address as you knowand then click on the Search button or press Enter. The search results are thendisplayed in the results area (see page 33), at which point the Search buttonbecomes a Select button.With Typedown searching, you must start by typing in a place name or postal/ZIP code. Pro starts searching from the moment you begin to type. As you workthrough the stages of Typedown, the refinement prompts above the Search fieldprovide specific pointers to the type of information that should be entered ateach stage.32 • Pro User Interface QuickAddress Pro API

When you use Typedown searching, Pro will always look for an exact matchfirst. If an exact match is found, and other partial matches are below the matchthreshold, all of the matches are displayed. However, if the partial matchesexceed the match threshold, only exact matches are displayed.Results AreaThe results area displays the matches returned in response to your search. Ifthere are several alternatives, this area displays a picklist. If there is only onematch, or you have worked through a number of picklists to reach a finalselection, you will see a full address on the results area.The results area also displays informational prompts to clarify the current stateof the search (for example, ’Continue typing (or select to show all matches)’).See page 35 for further details of picklists.Partial Address BarThe partial address bar displays the information that is currently selected in theresults picklist as the most complete address possible. For example, the screenshot above shows a partial address from the Netherlands Typedown shownbelow:Pressing Ctrl+Enter returns the address that you last stepped into. However,you should be aware that this will not produce a fully postally correct addressfrom a country database.QuickAddress Pro API Pro User Interface • 33

To hide the partial address bar, select ‘Partial Address’ from the View menu.Repeat this action to make the bar visible again.Status BarThe status bar indicates the current action and status of the Pro Dialog. Whenyou first run Pro, the status bar displays the name of the current layout in theleft corner.Other information that you might see on the status bar is described below:Stop buttonNumber ofmatchesSearch inprogressElementshaveoverflowedThis allows you to abort a search. TheStop button is displayed when Proconducts either a Typedown or SingleLine search.Displayed during a Single Line orTypedown search, and once a picklist hasbeen returned.During a Typedown search, you might see“Too many” on the status bar. This meansthat the number of matches found so farexceeds Pro’s match threshold, and youneed to enter more information.During a search, a blue bar travels fromside to side on the status bar, indicatingthat the search is in progress. This linedisappears when Pro has found allpossible matches, or when you choose tostop the search.Displayed when an address has beenreturned to the results area, but one ormore address elements is not visible dueto lack of space.You can add more addresslines or widen existing lines with theConfiguration Editor.34 • Pro User Interface QuickAddress Pro API

Elements aretruncatedSelect backfor closematchesAlias matchWarning –address notverifiedExact matchesshown -continuetyping formoreDisplayed when an address has beenreturned to the results area, but theinformation on an address line is too longfor the line.You can widen address lineswith the Configuration Editor.Displayed when Pro has found one 100%match in Single Line searching, andreturned a full address to the results area.Click the Back button to see a picklist ofevery other possible match found by Pro.Displayed when the current selection onthe picklist is an alias match – i.e. Pro hasrecognised the information that you typedin, but returned a different, postallycorrect version.Displayed when you have chosen toreturn an incomplete address to theaddress edit screen.Displayed when there is one exact match,and a higher number of close matchesthan the limit of the threshold allows.Click on the informational prompt or typein a “*” to view the complete list ofmatches.Picklists of Returned AddressesOn completion of a search, Pro returns the matches it has found in a picklist.Each line of the picklist contains one item which you can select.The picklist for Single Line search results differs slightly from that forTypedown results.QuickAddress Pro API Pro User Interface • 35

Picklist SymbolsThe symbol of a letter and a magnifyingglass in the grey box at the top of a picklistin Single Line searching shows what Pro iscurrently searching on.The symbol of a single white envelope tothe left of an item indicates that the item isa full address, and selecting it will return itdirectly to the address edit screen.A + sign and a symbol of multiple whiteenvelopes next to the item signifies anexpandable item. If you select anexpandable item, you will see a furtherpicklist containing every component of thatitem. For example, if the item is a road andyou expand it, Pro will display all thepremises in that road.Multiple white envelopes without a + signnext to the item signifies an unexpandableitem, such as a property number range inthe US. In this case, you will need to typein a property number within the range toretrieve a match.This symbol indicates a name entry. If youselect a name entry, both name and fulladdress are returned to the address editscreen.You will only see this symbol if the countrydatabase you are using includes name data.36 • Pro User Interface QuickAddress Pro API

A symbol of single or multiple greyenvelopes indicates an alias match. Thismeans that although Pro has recognised theaddress information that you have enteredas a possible version of the address, it hasreplaced it with the official version fromthe country database.An alias match would occur, for example, ifyou entered a street and locality, where thelocality is not necessary to the address andhas been replaced by the town. It wouldalso occur if the postal/ZIP code hasrecently been changed and Pro is aware ofthis: if you enter the old postal/ZIP code, itwill automatically be replaced by the newone.Typedown Search ResultsThe results of a Typedown search (in this case looking for a place in the USAbeginning with “wap”) are returned in a picklist similar to this:As this is the first stage of a Typedown search, every match is an expandableitem.Every item in a Typedown picklist precisely matches what you have typed inso far.QuickAddress Pro API Pro User Interface • 37

Informational promptsTo clarify the current state of a Typedown search, Pro provides informationalprompts in the results area. For example, at the beginning of a search the resultsarea will contain an informational prompt similar to:Using United Kingdom data, type the letters “fr” into the search box. Theinformational prompt will change to:You can either continue typing to narrow down the search or click the Selectbutton, press Enter, or double click on the informational prompt to show all ofthe matches.Depending on the status of a search, Pro may display other intuitiveinformational prompts.Single Line Search ResultsThe results for a Single Line search (in this case, on a United Kingdom streetand city) are returned in a picklist similar to this:38 • Pro User Interface QuickAddress Pro API

Selecting a Picklist ItemThere are a number of ways to select a picklist item:• Double-click the item.• Highlight the item and click the Select button.• Highlight the item and press Enter.• Type enough letters in the Select item box (which replaces the entersearch box) to identify the item you want, then click Select or pressEnter.When you select your item, Pro either returns another picklist or a full address,depending on whether it is an expandable item or a single address.Order of Picklist ItemsIn Single Line, picklist items are displayed in match percentage order, with thehighest at the top of the list, then sorted by address.Displayed Postal/ZIP CodesIf there is only one postal/ZIP code which covers the whole of a picklist item,it is displayed in the picklist. However, if a street or other expandable itemcontains more than one postal/ZIP code, the postal/ZIP codes are not displayed.Select the item to see the postal/ZIP codes available.Returning an Unrecognised AddressWhen entering property information it is possible to return an unrecognisedaddress by pressing Ctrl+Enter. For example, using GBR data:1. Click the Typedown button to use the Typedown search facility.Alternatively you can select Typedown from the Search menu, or pressCtrl+T.2. Type 'PA16 9LZ' into the Enter place or postcode search box.3. After the postcode is returned in the picklist area press Enter or clickSelect.Pro returns two matches, and has identified the second match as an evenrange.QuickAddress Pro API Pro User Interface • 39

4. Type ’28’ into the Enter selection box.The picklist area displays the following informational prompt:This prompt informs you that although the address is not valid, you canpress Crtl+Enter to return the full address.5. For the purpose of this example you are confident that the input addressis correct. Press Ctrl+Enter to return the address to the address editscreen.Pro will not display the Ctrl+Enter prompt if it has been disabled. Seepage 214 for details on how to disable this functionality.Address Edit ScreenWhen you select the address that you want from a picklist (which is a picklistitem with no + to the left of it), it is returned to the address edit screen, whichreplaces the picklist in the results area.The format of the address edit screen depends on the layout you select (seepage 199 for more on selecting layouts).Once you have a full address, you can edit it directly on this screen if you wishby clicking in the boxes or using the cursor keys. However, this is notrecommended as the address that you have retrieved is postally correct.40 • Pro User Interface QuickAddress Pro API

If you have configured Pro to return DataPlus information, two tabs marked‘Address’ and ‘DataPlus’ appear below the address. Click on the ‘DataPlus’ tabto see information pertaining to the returned address, and click on the‘Address’ tab to see the address itself.Setting Pro OptionsThere are a number of options that you can specify on the Pro user interface.As well as choosing whether to view or hide the menu bar, toolbar, partialaddress bar and informational prompts, you can:• choose a search method;• change the searching options;• specify the country database you want to search with (if you have morethan one database installed);• select the address layout that you want to work with;It is possible to control the options that a user can change with the functionalityflags used in the call to QAProWV_UIStartup (see page 169), and also in theUser Interface Options on the Configuration Editor (see page 197). Therefore,you might not be able to change some of these options from the Pro UserInterface.Selecting a Search MethodThere are two search methods in Pro: Single Line and Typedown. If both areenabled, you can easily switch between them as necessary.To select Single Line searching:Either select “Single Line” from the Search menu, press Ctrl+S orclick the Single Line search button.Single Line search buttonThis calls the function QAProWV_UISetFlags (see page 167) with theqaattribs_SINGLELINESEARCH flag.To select Typedown searching:Either select “Typedown” from the Search menu, press Ctrl+T or clickthe Typedown search button.QuickAddress Pro API Pro User Interface • 41

Typedown search buttonThis calls the function QAProWV_UISetFlags (see page 167) with theqaattribs_TYPEDOWNSEARCH flag.When you start the Pro API, the search method will default to whatever wasused last, or the flag that has been set with QAProWV_UIStartup (seepage 169). If the flag qaattribs_NOCHANGEMODE has been set, you cannotchange the search mode from the front-end screen.Setting Search OptionsSelect Options from the Search menu to see a dialog similar to this:Using this dialog, you can change the match threshold and Single Linesearching options.On the Threshold tab, you can change choose to bring back between 5 and 999matches. For example, if you set the threshold to ten, Pro will return amaximum of ten matches. By default, the match threshold is set to 25 for theUI API. (The Primary API uses a default of 40.)In Single Line searching, you can define the extent to which you want Pro tosearch a database. You can set the search distance to two levels: Standard orIntensive.If you set the search tolerance to Standard, Pro initially looks for exactmatches, and returns them to the preview area. However, if no exact matchesare found, Pro looks for close matches and returns them to the preview area.Pro will stop searching if no close or exact matches are found.42 • Pro User Interface QuickAddress Pro API

If you change the search distance to Intensive, Pro carries out a more extensivesearch to retrieve matches. This search is particularly useful if you haveaddress details which may have errors. For example, if you were using Pro toverify addresses sent to your company on reply paid forms, where thehandwriting might be illegible, it would be better to use Intensive searching.Note that setting the search distance to Intensive will increase the length oftime it takes to conduct searches.When you first launch Pro the searching distance is set to Standard.Selecting a Country DatabaseIf you have more than one country database installed, you can select which oneto search on from the Database list.Click on the arrow to the right of the Database list to see the list of availablecountry databases.This action performs the equivalent of calling the following functions:• QAProWV_UICountryCount (page 144) / QA_GetDataCount(page 83);• QAProWV_UIGetCountry (page 150) / QA_GetData (page 81);• QAProWV_UIGetActiveCountry (page 146) / QA_GetActiveData(page 79).To select a database, either click on it or use the cursor keys to highlight it andpress Enter. This performs the equivalent of calling the functionQAProWV_UISetActiveCountry (page 163) / QA_SetActiveData(page 128).QuickAddress Pro API Pro User Interface • 43

Databases can also be selected by pressing Ctrl+Shift and typing in the firstletter, or couple of letters of the country identifier. For example,Ctrl+Shift+DN selects the Denmark database (if the Denmark database isinstalled).If you select a different country database in the middle of a search, the currentsearch is stopped and a blank search screen appears in readiness for a newsearch.Selecting an Address LayoutAn address layout is a collection of settings that determine how the finaladdress is formatted when you complete a search in Pro.For example, a layout could specify that the address will be on five lines, eachof width 50 characters, with the town and postal/ZIP code always on the fourthand fifth lines respectively.Address layouts are country-specific, because each country has differentstandard address elements. However, you can have several layouts set up foreach country database. See the Configuration Editor (page 197) for full detailsof creating and setting up new layouts.Each country database has a default layout associated with it. This comes toyou pre-configured with an address format following appropriate nationalstandards. When you start Pro, it automatically uses the default layout for thedatabase that is selected, unless you specify otherwise withQAProWV_UIStartup.Select layout buttonClick on the Select layout button or choose Select layout… from the Viewmenu to see a list of available layouts for the currently selected countrydatabase:44 • Pro User Interface QuickAddress Pro API

This action performs the equivalent of calling the following functions:• QAProWV_UILayoutCount (page 157) / QA_GetLayoutCount(page 95);• QAProWV_UIGetLayout (page 153) / QA_GetLayout (page 93);• QAProWV_UIGetActiveLayout (page 148) / QA_GetActiveLayout(page 80)Select another layout, either click on the layout name to highlight it and clickOK, or double-click on the layout name, or use the cursor keys to move to thelayout name and press Enter. This performs the equivalent of callingQAProWV_UISetActiveLayout (page 165) / QA_SetActiveLayout(page 129).The Preview area at the bottom of the Select layout dialog shows the addressformat of any layout that you highlight.When you create a layout, you can set the layout comment that appears at thebottom of the Select Layout dialog. See “[Country Identifier]Comment={textstring}” on page 186 or “Creating and Naming Layouts” on page 201.QuickAddress Pro API Pro User Interface • 45

Data TypesMain Data TypesThere are a few QuickAddress-specific data types which appear in thedocumentation and need some explanation. These types define the parametersthat the functions take and values they return.These can be split into three categories: the values that are returned by thefunctions, the parameters that go into the functions, and the parameters you getout of the functions.Function Return ValuesQuickAddress datatypeDescriptionEquivalent ‘C’data typeINTRET integer intLONGRET long integer longVOIDRETno returnvaluevoidQuickAddress Pro API Data Types • 47

Parameters (Input)QuickAddress datatypeDescriptionEquivalent ‘C’data typeSTRVAL string char *INTVAL integer intLONGVAL long integer longVOIDARG no arguments voidParameters (output)QuickAddressdata typeDescriptionEquivalent ‘C’data typeSTRREF string char *INTREF integer int *LONGREF long integer long *Calling Functions from Languages Other ThanCWhilst C is the language most commonly used when working with these APIfunctions, it is possible to integrate the API with other programmingenvironments. There are, however, a few points which you should note. Theseare:• NULL Termination• Padding• Passing by Value or by Reference48 • Data Types QuickAddress Pro API

NULL TerminationPro API is written in the ‘C’ programming language. In C, all strings areexpected to end with the NULL character (i.e. NULL terminated), which hasthe absolute value 0 (zero), not ASCII ‘0’.For all functions in the API that accept paramaters of the type STRVAL, theseparameters must be NULL terminated. Furthermore, all return parameters oftype STRREF will be NULL terminated.In BASIC, for instance, string termination can be achieved by appending theNULL characters to all the strings, as shown in the following example:MyString$ = “Hello” + Chr$(0)In the majority of cases, Visual BASIC for Windows automatically ends allstrings with a NULL character, so performing this termination might not benecessary.PaddingAPI functions that return a string (STRREF) into a buffer will automaticallyNULL terminate the result. However, you should create this buffer and ensurethat it is large enough to hold any string which the function is likely to return.Consider, for example, the programming language BASIC. In BASIC, stringsare not normally stored in fixed length memory blocks. Rather, they occupyonly the minimum amount of memory needed to store their value – whichchanges as the string changes.Therefore, before you pass a string into a function you must first ‘pad’ it out.This means adding extra characters to the string in order to force the systeminto allocating enough memory to hold any possible return string.In BASIC you might pad a string with two hundred ‘+’ characters, like this:retBuffer$ = STRING$(200, “+”)Alternatively, you could create a string with two hundred space characters likethis:QuickAddress Pro API Data Types • 49

etBuffer$ = SPACE$(200)After an API function has returned a string, it might be necessary to strip offthe NULL character if it cannot be handled by the calling language.In BASIC this can be achieved as follows:nullOffset=INSTR(retBuffer$, CHR$(0))IF nullOffset>0 THEN retBuffer$=LEFT$(retBuffer$, nullOffset –1)Passing by Value or by ReferenceIn general C programming, function parameters may be passed either by valueor by reference.You must pass a parameter in the way the function expects you to pass it. Ifyou pass a parameter by value when the function is expecting it to be passed byreference then this might crash your program and will certainly produceincorrect results.• Strings are always passed by reference, whether they are input or outputparameters.• Numbers are passed by value when they are inputs to the function. Theyare passed by reference when they are outputs from the function.Returned StringsWhen passing a buffer to an API function parameter that returns a string, thenext parameter is commonly where the size of the buffer passed is defined. Thefollowing example demonstrates this type of function:INTRET QA_GetActiveData ( INTVAL viHandle,STRREFrsDataID,INTVAL viDataIDLength) ;where the parameter viDataIDLength is passed the length of the buffer passedto rsDataID.50 • Data Types QuickAddress Pro API

If the buffer length parameter is passed zero, then the API function will notattempt to populate the buffer with the return string. The parameter thatreceives the buffer can optionally be passed NULL in combination with a zerobuffer length, if the integration language supports this.If the buffer length parameter is greater than zero, then the integrator shouldensure that the buffer size and associated length parameter is large enough toreceive the returned string. If this is not the case, then truncation will occur, andwill be logged in the error log file. See “Error Logging” on page 193.Example of Data TypesThe example below uses the function QA_GetData, which is described in fullon page 81.This is how the function prototype looks in the documentation:INTRET QA_GetData(INTVAL viHandle,INTVAL viDataOffset,STRREF rsDataID,INTVAL viDataIDLength,STRREF rsName,INTVAL viNameLength );The parameters viHandle and viVersionLength are inputs to the function (in theform of integers) and thus are passed by value. The parameter rsVersion is anoutput parameter (in the form of a string), and consequently it is passed byreference. Similarly, the parameter riDaysLeft is also passed by reference as itis an output to the function in the form of an integer.In addition, QA_GetData returns a status value indicating either the successfulexecution of the function, or whether an error has occurred (in the form of anerror code).QuickAddress Pro API Data Types • 51

This function can be written in native C as:int QA_GetData (int viHandle,char *vsIsoCode,int *riDaysLeft,char *rsVersion,int viVersionLength,char *rsCopyright,int viCopyrightLength);Visual BASIC for Windows would declare this function as:Declare Function QAProWV_DataInfo Lib “QAPWVED.DLL”(ByVal viHandle As Long,ByVal vsIsoCode As String, riDaysLeft As Long,ByVal rsVersion As String,ByVal viVersionLength As Long,ByVal rsCopyright As String,ByVal viCopyrightLength As Long)As LongFor examples of functions in other programming languages, see the technicalnotes in readme.txt.52 • Data Types QuickAddress Pro API

Primary API FunctionReferencePseudocode Example of Pro APIThis section provides an overview of how a program using the Pro API workson a conceptual level. The pseudocode used is programming languageindependent.The example below uses many of the Pro API functions, so that you can seehow they work together. In practice, however, you might not want or need touse every function.The pseudocode does not include all of the available functions.Six functions are described in the pseudocode. The main function starts aninstance of the API, and gives the user a choice of performing a Single Line orTypedown search. It then frees resources after each result has been retrieved.Each search recursively calls five further functions: Display Error, whichretrieves and displays the message associated with the returned error code;User Action, which displays prompts (commonly an instruction as to whatshould be entered by the user); Display Results, which retrieves picklists ofresults from the search; Select Results, which allows the user to step intopicklist items; and Return Address, which formats and returns the final address,using the rules specified in the active layout.Main FunctionThe Primary API is instance based, where each instance is referenced with ahandle. To create a new instance of the API, the function QA_Open must becalled and the unique handle that it returns used with subsequent API calls. Ifmultiple instances of the API are required, such as for use with multithreading,then QA_Open needs to be called multiple times.QuickAddress Pro API Primary API Function Reference • 53

Open an instance of the API [QA_Open]As with all API calls, the open could fail for various reasons. The mostcommon reasons for this to occur are that the product is not installed orconfigured properly. If open fails, address matching will not be available.When writing integrations of the primary API, it will be useful to enable errorlogging (see “Error Logging” on page 193).For brevity in the pseudo code we will leave out the error checking for eachAPI function call. However in an integration all API calls should check theerror returned (see page 58).If open failedCall Display errorclose API instance [QA_Close]shutdown API [QA_Shutdown]exit procedureend ifOnce an open has been performed, the settings that are going to be used shouldbe applied to the instance. The user may or may not be able to control whichdataset and search engine to use. Both of these should be set before searchingbegins. The active dataset and search engine can be changed between searchesif required.set active data set to search upon [QA_SetActiveData]set engine to use for searching [QA_SetEngine]The layout to be used for formatting will need to be set, although this defaultsto an internal layout that will be valid but probably not suitable. It is wise to setthe active data set before choosing the layout to use with formatting, as somelayouts may only be defined for individual data sets. Any engine options, suchas search timeouts or picklist thresholds should also be set at this point if thedefault values are not desired. See “QA_SetEngineOption” on page 133.set layout to use for formatting [QA_SetActiveLayout]set engine options [QA_SetEngineOption]54 • Primary API Function Reference QuickAddress Pro API

The recommended method for handling searching with the API is torecursively display any picklist results, and then allow the user to either searchupon the results further, or to step into a result until the user has the address thatthey require. Formatting can then be applied, and the address returned.RepeatThe results should be displayed before the search is performed, as theremay be some information returned to the user by the API beforesearching. This is commonly done by the typedown search engine.Call Display resultsThere are two essential requests that a user can make that need to behandled. The first is giving some text to search upon. The second is toselect an item to either step into or format. Other actions can be codedat the integrators discretion, such as stepping out of a result to go back,or to exit the address searching.Call User actionIf action was search textsearch with text [QA_Search]Else If action was to select an itemCall Select ResultEnd IfUntil user has obtained addressAfter a search has been completed, it is essential to call the end search functionbefore starting another in the instance.end the search [QA_EndSearch]Once all address searching has been performed with the instance, the instanceshould be closed.close the instance [QA_Close]QuickAddress Pro API Primary API Function Reference • 55

If no more instances are required, the API needs to be shutdown, which willclose all instances anyway.shutdown the API [QA_Shutdown]Display Error FunctionAlmost every primary API function call returns an error code which should bechecked. If an error occurs then the message associated with the returned errorcode can be retrieved and displayed to the user. See “Handling Errors” onpage 58.retrieve error message [QA_ErrorMessage]display error message to userReturn to calling functionUser Action FunctionIn order to aid the user when they are interacting with the integration, thePrimary API can return prompts to display to the user. These will commonlybe an instruction of what should be entered, such as “Enter postcode or place”when using the typedown engine at the beginning of a search. The promptshould be displayed to the user in some manner before requesting input.retrieve prompt text [QA_GetPrompt]display prompt to userobtain action from userReturn to calling functionDisplay Results FunctionTo display results, first obtain a count of the available results and then retrieveand display each one. The integration may choose to display different type ofresults in different ways. For example it is common to indicate to the userwhich results can be stepped into, or which results are full addresses that willbe used if selected.get a count of available results [QA_GetSearchStatus]56 • Primary API Function Reference QuickAddress Pro API

For Each resultretrieve the result [QA_GetResult]display the result to the userEnd ForReturn to calling functionSelect Result FunctionWhen a user selects a result the action that the integration should take isdetermined by the attributes associated with the result in question. The twomost important attributes are whether the result can be stepped into, andwhether it is a final address. Other result attributes may be handled at theintegrators discretion.get the attributes of the result [QA_GetResult]If result can be stepped intostep into result [QA_StepIn]Else If result is a final addressCall Return addressEnd IfReturn to calling functionReturn Address FunctionWhen a user has selected a final address, it should be formatted and returned inthe appropriate manner. The address will be formatted using the rules specifiedin the active layout.format result and retrieve line count[QA_FormatResult]For Each formatted lineretrieve the line text [QA_GetFormattedLine]return text to the userEnd ForReturn to calling functionQuickAddress Pro API Primary API Function Reference • 57

Handling ErrorsEvery Primary API function except for QA_Shutdown () returns an integererror code value. This value will be within the following ranges:0 Function succeededless than 0 Function encountered errorsQAS strongly recommend that every function call is checked for errors.Although the majority of errors are generated by mistakes in an integrationwhich would be picked up through testing, some are unpredictable. Forexample, the failure of a client-server link, running out of memory, or a datafile expiry.All Primary API functions will set their output parameters to defined values ifan error occurs. Integer output variables will be set to zero, and string outputvariables will be set to blank.The LogErrors configuration setting is a useful way of locating the cause of anerror. QAS recommend that you enable error logging while writing anddebugging an integration. See page 193 for more information.The QA_ErrorMessage () function provides a textual description of errorcodes returned from the API. See page 73 for more information.The handling of errors should typically be split into two categories. These aredescribed below.1. An error returned from a call to QA_Open (). This means that addresscapture is unavailable.This could be caused by many things, such as configuration oradministration errors. QAS recommend that you call QA_Shutdown ()and locate the source of the problem using the LogErrors setting (seepage 193).2. An error returned after a call to QA_Open () because, although addresscapture is available, the current search has failed for some reason. Thiscould be due to a lack of resource, or to an administration error. QASrecommend that you call QA_EndSearch () to end the current search.58 • Primary API Function Reference QuickAddress Pro API

Note that you do not have to shut down the system, and that addresscapture may still be available. For example, a client-server link mayhave failed, losing the current search. However, attempting a newsearch could reconnect and function correctly.If you are writing a client-server integration of Pro, it is very important to reactto errors after QA_Open () as described above. An error will be returned froman API function if a connection to the server in use is lost, as the search resultswill not be retrievable.API InstancesThe Primary API is based on the concept of instances. An instance of the APIis created through calling QA_Open (), and is destroyed by callingQA_Close (). Once an instance is created, it is referenced through an integerhandle that is returned from QA_Open (). All subsequent functions that use theinstance must be passed through this handle. Once all instances have beenclosed using QA_Close (), the API should be shut down usingQA_Shutdown ().Each instance of the API that is created is independent from other instances.Any action that is performed upon one instance will not affect that state ofanother instance. Actions can be performed upon separate instancessimultaneously.If you want to have a multithreading integration that performs multiplesearches concurrently, you should create multiple instances of the API. Eachthread will typically perform the following actions:• Create an instance using QA_Open ()• Perform one or more searches• Close the instance using QA_Close ()Once all threads have finished, call QA_Shutdown (). It would be uncommonfor a single-threaded integration to require multiple instances of the API.QuickAddress Pro API Primary API Function Reference • 59

Flags ReturnedMany API functions, such as QA_GetSearchStatus (), pass information backusing ‘flags’.Flags are a means of communicating multiple pieces of information back to thecaller using a single parameter.The value returned consists of multiple values ORed together.Example:QA_GetResult () returns information about a picklist item. If a picklist item isinformational and can be stepped into, the following flags are returned:qaresult_CANSTEP 4qaresult_INFORMATION 1024The value of rlFlags will be:4 OR 1024 = 1028.To check for a specific flag the integrator should AND the returned set of flagswith the flag they wish to test for. If the result is zero, the flag was not present.If the result is non-zero, the flag was present.Example:Testing for qaresult_CANSTEP (4) in 1028.1028 AND 4 = 4 (non-zero)Therefore the picklist item can be stepped into.Example:Testing for qaresult_ALIASMATCH (8) in 1028.1028 AND 8 = 0 (zero)Therefore the picklist item is not an alias match.60 • Primary API Function Reference QuickAddress Pro API

In C: if (rlFlags & 1024){…}In VB:If (rlFlags And 1024) Then…EndIfSome functions have accompanying ‘Detail’ functions; for example,QA_GetResult () has the accompanying function QA_GetResultDetail ().These allow the caller to inquire about a single specific attribute and is usefulfor languages that cannot perform bitwise operations such as AND, or forintegrations that require extra information.If rsDetail or rlDetail is not used in a particular call to a ‘Detail’ function, it willreturn a blank string or zero appropriately.Example:QA_GetResultDetail (iHandle,iResult,qaresultint_ISINFORMATION,&lDetail,NULL,0);This will return qavalue_TRUE or qavalue_FALSE in parameter lDetail,depending on whether the given picklist item is informational or not.Automatic Stepping and FormattingTo help you locate addresses faster and more effectively, the Primary APIsupports automatic stepping into and formatting of picklist items generatedfrom an initial search. For example, if you were to perform a search thatgenerated only a single exact result, the integration can automatically step intothat item instead of prompting you to do it manually, which speeds up theaddress capture process.QuickAddress Pro API Primary API Function Reference • 61

Automatic stepping in and/or formatting is not required for a successfulintegration, and it is therefore at your discretion whether you act upon thereturned flags.The Primary API will output one of the following four flags from the functionQA_GetSearchStatus () (see page 114).The flag qastate_AUTOSTEPINSAFE is returned when a search or step inhas produced a picklist containing only one match that itself can be steppedinto. QAS recommends that the integration should call QA_StepIn () upon thefirst item in the picklist when this flag is returned, as it will speed up the addresscapture process.The flag qastate_AUTOSTEPINPASTCLOSE is returned when a search orstep in has produced a picklist containing only one exact match, and alsomultiple non-exact matches. You may choose to call QA_StepIn () on the firstitem in the picklist when this flag is returned, as it may speed up the addresscapture process.The flag qastate_AUTOFORMATSAFE is returned when a search or step inhas produced a picklist containing only a single match that is a final addressitem. If the integration allows you to go back to the picklist after selecting afinal address, then QAS recommend that QA_FormatResult () should becalled upon the first picklist item and the address returned.The flag qastate_AUTOFORMATPASTCLOSE is returned when a searchor a step in has produced a picklist containing only one exact match that is afinal address item, and also multiple non-exact matches. If the integrationallows you to go back to the picklist after selecting a final address, then you canchoose to call QA_FormatResult () on the first item in the picklist and on theaddress returned.62 • Primary API Function Reference QuickAddress Pro API

Asynchronous SearchingThe Primary API supports two different threading models for performingsearches: synchronous and asynchronous.Synchronous searching is the default threading model, and is used by themajority of integrations. Using synchronous searching, the functionsQA_Search () and/or QA_StepIn () return to the caller once the search hasbeen completed. You can then immediately access the results.Asynchronous searching is an alternative threading model where the calls tothe searching functions are returned as soon as the search has begun. Thesearch is performed using a background thread.Asynchronous searching is not available for single threaded versions of thePrimary API, as supplied for UNIX platforms without the required POSIXmultithreading standard.There are three engine options that control asynchronous searching:1. The qaengopt_ASYNCSEARCH engine option allows the integrator tocontrol whether the initial search using QA_Search () on the single lineengine is asynchronous. This is the most commonly used option forasynchronous searching.2. The qaengopt_ASYNCSTEPIN engine option allows the integrator tocontrol whether stepping into picklist items using QA_StepIn () isasynchronous.3. The qaengopt_ASYNCREFINE engine option allows the integrator tocontrol whether picklist refinement using QA_Search () after the firstresult for the single line engine, and all searches using the typedownengine, are asynchronous. This will be used less frequently, as picklistrefinement is a fast process.The search must be complete before you can retrieve the results. The callerneeds to check periodically whether the search has been completed by callingQA_GetSearchStatus () (see page 114), and checking whether the flagqastate_STILLSEARCHING is present. Typically, you should check every100ms to see whether the search has completed.QuickAddress Pro API Primary API Function Reference • 63

The following diagram demonstrates polling:Asynchronous searching is useful, although not essential, for graphical userinterface integrations where the caller wants to be able to perform tasks whilethe search is in progress, and does not want to use multithreaded code. Forexample, this could be used to react to search cancel requests.64 • Primary API Function Reference QuickAddress Pro API

Primary API Function ReferenceThe Pro Primary API functions are split into five groups. A full list of thePrimary API functions is provided below, along with details of where you canfind each one:General FunctionsQA_OpenOpens an instance of the API.QA_CloseCloses an instance of the API.QA_ErrorMessageTranslates error codes into descriptions.QA_ShutdownCloses down the API.page 124page 71page 73page 136Common Search FunctionsQA_SetEngineSets the current search engine toTypedown or Single Line.QA_GetEngineRetrieves the current search engine.QA_SetEngineOptionSets search engine-related attributes forthe current engine.QA_GetEngineOptionRetrieves the value for a particularengine-related attribute.QA_GetPromptReturns the prompt text to direct the useraction.page 131page 84page 133page 85page 101QuickAddress Pro API Primary API Function Reference • 65

QA_GetPromptStatusReturns status information about thecurrent prompt.QA_SearchPerforms a search.QA_CancelCancels a search in progress.QA_EndSearchEnds the current search, and resets allresults.QA_GetSearchStatusProvides information about the state of asearch. Can be called at any time.QA_GetSearchStatusDetailProvides detailed information about thestate of a search. Can be called at anytime.QA_StepInSteps into a picklist item.QA_StepOutSteps out of a picklist item.page 103page 126page 70page 72page 114page 117page 137page 139Result FunctionsQA_GetResultObtains limited information regarding apicklist item.QA_GetResultDetailObtains detailed information regarding apicklist item.QA_FormatResultSelects a picklist item and appliesformatting.page 105page 109page 7666 • Primary API Function Reference QuickAddress Pro API

QA_GetFormattedLineReturns a given formatted line.QA_GetExampleCountReturns the number of example addressesfor the given data set.QA_FormatExampleSelects an example address and appliesformatting.page 90page 88page 74Layout FunctionsQA_GetLayoutCountRetrieves the number of available layoutsthat can be used for formatting.QA_GetLayoutReturns information about a givenlayout.QA_GetActiveLayoutReturns the name of the layout currentlyin use for formatting returned addresses.QA_SetActiveLayoutSets the layout that will be used forformatting.page 95page 93page 80page 129Data Set FunctionsQA_GetDataCountProvides a count of the available datasets.QA_GetDataProvides information about a given dataset.QA_GetActiveDataReturns the data ID of the data setcurrently in use.page 83page 81page 79QuickAddress Pro API Primary API Function Reference • 67

QA_SetActiveDataSets the data set to be searched on.QA_GetLicensingCountProvides a count of the total availabledata and dataplus sets.QA_GetLicensingDetailProvides detailed information about agiven data set.page 128page 96page 98System FunctionsQA_GenerateSystemInfoGenerates information regarding the stateof the system.QA_GetSystemInfoInterrogates the system informationprovided by QA_GenerateSystemInfo.page 78page 12268 • Primary API Function Reference QuickAddress Pro API

General Error Scenarios (All Functions)See also “Handling Errors” on page 58 for information about what to do inresponse to an error.Bad ParameterOne of the API parameters has been passed an invalid value. Use theLogErrors configuration setting (see page 194) to determine where theproblem lies.Bad HandleThe parameter viHandle has been passed an invalid handle. This should onlybe passed values returned from QA_Open () that have not since been closed.See “QA_Close” on page 71 and “QA_Open” on page 124.Server ErrorAn error has occurred on the server. This may be due to the server running outof resource, or to connection issues. This error may be returned in a non clientserverintegration if the ‘server’ side of the application runs out of resource,such as memory.Licensing ErrorThe active data set you are attempting to use may not be licensed properly andwill return an error. Check that data is the data is correctly installed andlicensed, and use the LogErrors configuration setting (see page 194) todetermine where the problem lies.QuickAddress Pro API Primary API Function Reference • 69

QA_CancelSearchCancels a search that is still in progress. This can be called if using eitherasynchronous or synchronous searching, although it is more common to use itwith asynchronous searching. See “Asynchronous Searching” on page 63 formore information.If cancelling a synchronous search, then this function will have to be calledusing a separate thread created by the integration. If the search has finishedbefore this function is called, then nothing will happen.PrototypeINTRET QA_CancelSearch (INTVAL viHandle,LONGVAL vlFlags );ArgumentsviHandlevlFlagsHandle for this instance of the APIFlags to control function behaviourReturn ValuesEither: 0 if call is successfulOr: Negative error codeCommentsThe following flags, passed into vlFlags, can be used to specify how to stop asearch in progress (either to return immediately or to wait until the search hasbeen cancelled):Symbolic NameDecimalValueDescriptionqacancelflag_NONE 0 Returns immediately aftercancellingqacancelflag_BLOCKING 1 Does not complete functionuntil the search has beensuccessfully cancelled70 • Primary API Function Reference QuickAddress Pro API

QA_CloseShuts down an instance of the API that has been opened with QA_Open ().Once an instance has been closed, the instance handle will be invalid andcannot be passed to subsequent API functions.If the call to QA_Open () failed, then the returned instance handle will be setto zero, which can be safely used with this function. See “API Instances” onpage 59.If an asynchronous search is in progress, then calling QA_Close () will safelycancel it before closing the instance. See “Asynchronous Searching” onpage 63.PrototypeINTRET QA_Close ( INTVAL viHandle );ArgumentsviHandleHandle to be closedReturn ValuesEither: 0 if call is successfulOr: Negative error codeQuickAddress Pro API Primary API Function Reference • 71

QA_EndSearchEnds the search. This function is called once all search information has beenreturned. It must be called before a new search is started.If an asynchronous search is in progress, then calling QA_EndSearch () willsafely cancel it before ending the search. See “Asynchronous Searching” onpage 63.PrototypeINTRET QA_EndSearch ( INTVAL viHandle );ArgumentsviHandleHandle for this instance of the APIReturn ValuesEither: 0 if call is successfulOr: Negative error code72 • Primary API Function Reference QuickAddress Pro API

QA_ErrorMessageUsed to translate an error code into a description.PrototypeINTRET QA_ErrorMessage (INTVAL viError,STRREF rsBuffer,INTVAL viBufferLength );ArgumentsviErrorrsBufferviBufferLengthError code to translateReturned error descriptionLength of rsBufferReturn ValuesEither: 0 if call is successfulOr: Negative error codeQuickAddress Pro API Primary API Function Reference • 73

QA_FormatExampleEach data set has example addresses, which can be used to preview layouts.See “QA_GetExampleCount” on page 88 for more information about exampleaddresses.QA_FormatExample formats an example in the current active layout. Sampleaddress lines can be retrieved by calling QA_GetFormattedLine.PrototypeINTRET QA_FormatExample (INTVAL viHandle,INTVAL viExample,STRREF rsComment,INTVAL viCommentLength,INTREF riLineCount,LONGREF rlInfo );ArgumentsviHandleviExamplersCommentviCommentLengthriLineCountrlInfoHandle for this instance of the APIThe index of the example to formatA comment describing the example addressThe size of the rsComment bufferThe number of lines that have been formattedInformation about the formatted exampleReturn ValuesEither: 0 if call is successfulOr: Negative error codeThe “Zero” example number always exists and is a blank example address,useful for getting the number of layout lines.74 • Primary API Function Reference QuickAddress Pro API

CommentsThe parameter viExample should be passed an index into the count of exampleaddress from QA_GetExampleCount (), between 0 and the count – 1.The parameter rlInfo can return the following flags ORed together (see “FlagsReturned” on page 60):Symbolic NameDecimalValueDescriptionqaformat_OVERFLOW 1 There are not enough addresslines configured to display thefull addressqaformat_TRUNCATED 2 Truncation has occurred onone or more address lines in thefinal addressError ScenariosBusy HandleBad IndexBad LayoutThe parameter viHandle has beenpassed a handle that is already in use inanother thread. Each handle can only beused by one thread at any point in time.The value passed to parameterviExample was not a valid exampleaddress offset. The range should bebetween 0 and the count of exampleaddresses - 1 fromQA_GetExampleCount ().The active layout that is set for theinstance is invalid. The list of validlayouts can be obtained by using theQA_GetLayoutCount () andQA_GetLayout () functions. A layoutmay be defined for a specific data setonly, and so changing the active data setmay invalidate the active layout.QuickAddress Pro API Primary API Function Reference • 75

QA_FormatResultSelects a picklist item and applies the formatting routines to it. This is doneaccording to the current active layout.PrototypeINTRET QA_FormatResult (INTVAL viHandle,INTVAL viResult,STRVAL vsExtra,INTREF riLineCount,LONGREF rlInfo );ArgumentsviHandleviResultvsExtrariLineCountrlInfoHandle for this instance of the APIThe picklist item to be formattedExtra text to add to the formattedaddressThe number of lines that have beenformattedInformation about the formatted resultReturn ValuesEither: 0 if call is successfulOr: Negative error codeCommentsThe parameter viResult should be passed an index into the count of availablepicklist items from QA_GetSearchStatus (), between 0 and the count – 1.The parameter rlInfo can return the following flags ORed together (see “FlagsReturned” on page 60):76 • Primary API Function Reference QuickAddress Pro API

Symbolic NameDecimalValueDescriptionqaformat_OVERFLOW 1 There are not enough address linesconfigured to display the fulladdressqaformat_TRUNCATED 2 Truncation has occurred on one ormore address lines in the finaladdressThe parameter vsExtra allows you to pass through text that you want to add tothe formatted address. This is typically used when you have refined on text thatis not in the data, but that you wish to use in the final address.Error ScenariosBusy HandleOut ofSequenceBad IndexBad LayoutThe parameter viHandle has beenpassed a handle that is already in use inanother thread. Each handle can only beused by one thread at any point in time.The API cannot format a result of apicklist if a search has not yet beenperformed.The value passed to parameter viResultwas not a valid picklist item offset. Therange should be between 0 and thepicklist result count – 1.The active layout that is set for theinstance is invalid. The list of validlayouts can be obtained by using theQA_GetLayoutCount () andQA_GetLayout () functions. A layoutmay be defined for a specific data setonly, and so changing the active data setmay invalidate the active layout.QuickAddress Pro API Primary API Function Reference • 77

QA_GenerateSystemInfoGenerates information regarding the state of the system. You can theninterrogate this with the function QA_GetSystemInfo ().PrototypeINTRET QA_GenerateSystemInfo (INTVAL viHandle,INTVAL viType,INTREF riCount );ArgumentsviHandleviTyperiCountHandle for this instance of the APIType of information to generateCount of lines generatedReturn ValuesEither: 0 if call is successfulOr: Negative error codeCommentsThe following values can be passed to viType:Symbolic NameDecimalValueDescriptionqasysinfo_SYSTEM 1 Generate the current state of thesystemError ScenariosBusy HandleThe parameter viHandle has beenpassed a handle that is already in use inanother thread. Each handle can only beused by one thread at any point in time.78 • Primary API Function Reference QuickAddress Pro API

QA_GetActiveDataObtains the data ID of the active data set. This is the data set that will be usedto search on.The data ID is a short string that uniquely identifies the data set. The availabledata IDs for all installed data sets can be returned using QA_GetDataCount ()and QA_GetData ().PrototypeINTRET QA_GetActiveData ( INTVAL viHandle,STRREF rsDataID,INTVAL viDataIDLength );ArgumentsviHandlersDataIDviDataIDLengthHandle for this instance of the APIBuffer returning data ID of active data setLength of rsDataIDReturn ValuesEither: 0 if call is successfulOr: Negative error codeError ScenariosBusy HandleThe parameter viHandle has beenpassed a handle that is already in use inanother thread. Each handle can only beused by one thread at any point in time.QuickAddress Pro API Primary API Function Reference • 79

QA_GetActiveLayoutRetrieves the layout that is currently active. This will be used for formatting thereturned address.PrototypeINTRET QA_GetActiveLayout ( INTVAL viHandle,STRREF rsName,INTVAL viNameLength);ArgumentsviHandlersNameviNameLengthHandle for this instance of the APIName of layoutLength of rsNameReturn ValuesEither: 0 if call is successfulOr: Negative error codeError ScenariosBusy HandleThe parameter viHandle has beenpassed a handle that is already in use inanother thread. Each handle can only beused by one thread at any point in time.80 • Primary API Function Reference QuickAddress Pro API

QA_GetDataReturns information about a given data set. You can call this multiple times toget information about all installed data sets.The function QA_GetDataCount () must be called before this function.PrototypeINTRET QA_GetData(INTVAL viHandle,INTVAL viDataOffset,STRREF rsDataID,INTVAL viDataIDLength,STRREF rsName,INTVAL viNameLength );ArgumentsviHandleviDataOffsetrsDataIDviDataIDLengthrsNameviNameLengthHandle for this instance of the APIIndex into data set countBuffer returning the ID of the data setLength of rsDataIDBuffer returning data setLength of rsNameReturn ValuesEither: 0 if call is successfulOr: Negative error codeQuickAddress Pro API Primary API Function Reference • 81

CommentsThe parameter viDataOffset should be passed an index into the available datacount from QA_GetDataCount (), between 0 to the count – 1.The data ID returned from the parameter rsDataID is a short string identifyingthe data set. This can be passed to QA_SetActiveData () in order to change thecurrent data set being searched upon.Error ScenariosBusy HandleOut ofSequenceBad IndexThe parameter viHandle has beenpassed a handle that is already in use inanother thread. Each handle can only beused by one thread at any point in time.The function QA_GetDataCount ()must have been called prior to thisfunction.The value passed to parameterviDataOffset was not a valid data offset.The range should be between 0 and thecount of data - 1 fromQA_GetDataCount ().82 • Primary API Function Reference QuickAddress Pro API

QA_GetDataCountReturns a count of the data sets that are available. This must be called beforethe data accessor function QA_GetData () is used. This provides a count of thenumber of separate data sets that can be passed to QA_SetActiveData (),which sets the active data set to be searched upon.PrototypeINTRET QA_GetDataCount (INTVAL viHandle,INTREF riCount );ArgumentsviHandleriCountHandle for this instance of the APICount of data setsReturn ValuesEither: 0 if call is successfulOr: Negative error codeError ScenariosBusy HandleThe parameter viHandle has beenpassed a handle that is already in use inanother thread. Each handle can only beused by one thread at any point in time.QuickAddress Pro API Primary API Function Reference • 83

QA_GetEngineRetrieves the current search engine. Refer to “Searching Methods” on page 19for information about the differences between the two search engines and howto use them.PrototypeINTRET QA_GetEngine (INTVAL viHandle,INTREF riEngine );ArgumentsviHandleriEngineHandle to the APIThe current active search engineCommentsThe possible search engines that can be returned from parameter riEngine areas follows:Symbolic NameDecimalValueDescriptionqaengine_SINGLELINE 1 Single line engineqaengine_TYPEDOWN 2 Typedown engineError ScenariosBusy HandleThe parameter viHandle has beenpassed a handle that is already in use inanother thread. Each handle can only beused by one thread at any point in time.84 • Primary API Function Reference QuickAddress Pro API

QA_GetEngineOptionRetrieves the current settings used with a search engine.PrototypeINTRET QA_GetEngineOption (INTVAL viHandle,INTVAL viEngOption,LONGREF rlValue );ArgumentsviHandleviEngOptionrlValueHandle for this instance of the APIEngine option to be returnedValue for the given engine optionReturn ValuesEither: 0 if call is successfulOr: Negative error codeCommentsThe possible engine options that can be returned are listed below:Symbolic NameDecimalValueDescriptionqaengopt_ASYNCSEARCH 1 Single line searches will beasynchronous.qaengopt_ASYNCSTEPIN 2 Calls to QA_StepIn () will beasynchronousqaengopt_ASYNCREFINE 3 Picklist refinement will beasynchronousqaengopt_THRESHOLD 6 Get the current picklist size thresholdqaengopt_TIMEOUT 7 Get the current search timeout (ms)qaengopt_SEARCHINTENSITY 8 Get the current search intensityQuickAddress Pro API Primary API Function Reference • 85

The engine option types qaengopt_ASYNCSEARCH,qaengopt_ASYNCSTEPIN and qaengopt_ASYNCREFINE will return one ofthe following values in parameter rlValue:Boolean Valuesqavalue_FALSE 0 Falseqavalue_TRUE 1 TrueFor more information, see “Asynchronous Searching” on page 63.The engine option type qaengopt_SEARCHINTENSITY will be return one ofthe following values in parameter rlValue.Search Intensity Valuesqaintensity_EXACT 0 Exact searchingqaintensity_CLOSE 1 Close searchingqaintensity_EXTENSIVE 2 Extensive searchingSee “QA_SetEngineOption” on page 133 for more information aboutqaengopt_SEARCHINTENSITY.The other engine option types will return an integer value.The engine options that control asynchronous searching (see “AsynchronousSearching” on page 63) are as follows:• qaengopt_ASYNCSEARCH• qaengopt_ASYNCSTEPIN• qaengopt_ASYNCREFINEThese can only be used for multithreaded versions of the library: the singlethreaded version of the library will not accept them. This is because theyrequire the API to create threads if the options are enabled.86 • Primary API Function Reference QuickAddress Pro API

Error ScenariosBusy HandleThe parameter viHandle has beenpassed a handle that is already in use inanother thread. Each handle can only beused by one thread at any point in time.QuickAddress Pro API Primary API Function Reference • 87

QA_GetExampleCountReturns the number of available example addresses for the current data set. Theexample addresses can be formatted and retrieved using QA_FormatExampleand QA_GetFormattedLine.PrototypeINTRET QA_GetExampleCount ( INTVAL viHandle,INTREF riExampleCount );ArgumentsviHandleriExampleCountHandle for this instance of the APIThe count of example addresses that existfor the given data setReturn ValuesEither: 0 if call is successfulOr: Negative error codeCommentsThe Zero example number always exists and is a blank example address, usefulfor obtaining the number of layout lines.Error ScenariosBusy HandleThe parameter viHandle has beenpassed a handle that is already in use inanother thread. Each handle can only beused by one thread at any point in time.88 • Primary API Function Reference QuickAddress Pro API

Bad LayoutThe active layout that is set for theinstance is invalid. The list of validlayouts can be obtained by using theQA_GetLayoutCount () andQA_GetLayout () functions. A layoutmay be defined for a specific data setonly, and so changing the active data setmay invalidate the active layout.QuickAddress Pro API Primary API Function Reference • 89

QA_GetFormattedLineReturns the given formatted address line.Pre-call ConditionsEither QA_FormatResult () or QA_FormatExample () must have beencalled for the current search.PrototypeINTRET QA_GetFormattedLine (INTVAL viHandle,INTVAL viLine,STRREF rsFormattedLine,INTVAL viFormattedLineLength,STRREF rsLabel,INTVAL viLabelLength,LONGREF rlContents );ArgumentsviHandleviLinersFormattedLineviFormattedLineLengthrsLabelviLabelLengthrlContentsHandle for this instance of the APIThe layout line to returnThe buffer to receive the formattedlineThe size of rsFormattedLineLabel for the lineThe size of rsLabelFlags describing the contents of thelineReturn ValuesEither: 0 if call is successfulOr: Negative error code90 • Primary API Function Reference QuickAddress Pro API

CommentsThe parameter viLine should be passed an index into the count of formattedlines from QA_FormatResult () or QA_FormatExample (), between 0 andthe count – 1.The parameter rsLabel will return the name of any individual address elementfixed to the line. If there are no elements (or more than one element) fixed tothe line, this will be blank.The parameter rlContents can return the following flags ORed together (see“Flags Returned” on page 60):Symbolic NameDecimalValueDescriptionqaformatted_NAME 1 There are name elements fixed tothis line.qaformatted_ADDRESS 2 There are address elements fixedto this line.qaformatted_ANCILLARY 4 There are ancillary elements fixedto this line.qaformatted_DATAPLUS 8 There are dataplus elements fixedto this line.qaformatted_TRUNCATED 16 Truncation occurred on this line,due to the width being too small.qaformatted_OVERFLOW 32 Some elements were lost from thisline, due to the width being toosmall and not enough lines beingdefined.qaformatted_DATAPLUSSYNTAX 64 Dataplus is badly configured uponthis line due to invalid syntax.qaformatted_DATAPLUSEXPIRED 128 Dataplus is badly configured uponthis line as it has expired.qaformatted_DATAPLUSBLANK 256 Dataplus is blank upon this line asthere was no appropriate value inthe data to return.QuickAddress Pro API Primary API Function Reference • 91

Error ScenariosBusy HandleBad IndexThe parameter viHandle has beenpassed a handle that is already in use inanother thread. Each handle can only beused by one thread at any point in time.The value passed to parameter viLinewas not a valid formatted line offset.The range should be between 0 and thecount of formatted lines - 1 fromQA_FormatResult () orQA_FormatExample ().92 • Primary API Function Reference QuickAddress Pro API

QA_GetLayoutReturns information about the given layout. You can call this multiple times toget a list of all layouts for the currently active data set.Pre-call ConditionsThe function QA_GetLayoutCount () should be called prior to this.PrototypeINTRET QA_GetLayout (INTVAL viHandle,INTVAL viLayout,STRREF rsName,INTVAL viNameLength,STRREF rsComment,INTVAL viCommentLength);ArgumentsviHandleviLayoutrsNameviNameLengthrsCommentviCommentLengthHandle for this instance of the APILayout to returnName of layoutLength of rsNameLayout commentLength of rsCommentReturn ValuesEither: 0 if call is successfulOr: Negative error codeQuickAddress Pro API Primary API Function Reference • 93

CommentsThe parameter viLayout should be passed an index into the count of availablelayouts from QA_GetLayoutCount (), between 0 and the count - 1.You can set the layout comment when you create a layout. See “[CountryIdentifier]Comment={text string}” on page 186. You may choose to displaythis comment to users when they change layout.Error ScenariosBusy HandleBad IndexThe parameter viHandle has beenpassed a handle that is already in use inanother thread. Each handle can only beused by one thread at any point in time.The value passed to parameter viLayoutwas not a valid layout offset. The rangeshould be between 0 and the count oflayouts - 1 from QA_GetLayoutCount().94 • Primary API Function Reference QuickAddress Pro API

QA_GetLayoutCountRetrieves the number of available layouts in the configuration file for the activedataset.PrototypeINTRET QA_GetLayoutCount (INTVAL viHandle,INTREF riCount );ArgumentsviHandleriCountHandle for this instance of the APINumber of available layouts in theconfiguration fileReturn ValuesEither: 0 if call is successfulOr: Negative error codeError ScenariosBusy HandleThe parameter viHandle has beenpassed a handle that is already in use inanother thread. Each handle can only beused by one thread at any point in time.QuickAddress Pro API Primary API Function Reference • 95

QA_GetLicensingCountReturns the total number of licensed data sets, including DataPlus sets, that areavailable. This total includes all servers that the API is using. Data duplicatedacross servers will be reported multiple times. This function can be used toreport the most serious warning that applies to the set of licensed data. This isuseful to check that there are no immediate or impending issues with theinstalled data, without interrogating each set individually usingQA_GetLicensingDetail (). See “QA_GetLicensingDetail” on page 98 formore information.If a count of data sets available to search with is required, use theQA_GetDataCount () function instead. See “QA_GetDataCount” on page 83.PrototypeINTRET QA_GetLicensingCount (INTVAL viHandle,INTREF riCount,LONGREF rlWarningLevel );ArgumentsviHandleriCountrlWarningLevelHandle for this instance of the APIThe count of licensed data setsWarning level for the set of licensed dataReturn ValuesEither: 0 if call is successfulOr: Negative error code96 • Primary API Function Reference QuickAddress Pro API

CommentsThe parameter rlWarningLevel will return one of the following values (sortedin increasing order of urgency and importance):Symbolic NameDecimalValueDescriptionqalicwarn_NONE 0 No licence warningqalicwarn_DATAEXPIRING 10 A data set is about to expireqalicwarn_LICENCEEXPIRING 20 A licence is about to expireqalicwarn_EVALUATION 30 Data is on an evaluation licenceqalicwarn_DATAEXPIRED 40 A data set has expiredqalicwarn_EVALLICENCEEXPIRED 50 An evaluation licence hasexpiredqalicwarn_FULLLICENCEEXPIRED 60 A full licence has expiredqalicwarn_LICENCENOTFOUND 70 Licence information cannot befound for a data setqalicwarn_DATAUNREADABLE 80 A data set is not readableError ScenariosBusy HandleThe parameter viHandle has beenpassed a handle that is already in use inanother thread. Each handle can only beused by one thread at any point in time.QuickAddress Pro API Primary API Function Reference • 97

QA_GetLicensingDetailReturns detailed information about a given licensed data set. The count oflicensed data sets can be obtained from the function QA_GetLicensingCount(). See “QA_GetLicensingCount” on page 96.PrototypeINTRET QA_GetLicensingDetail (INTVAL viHandle,INTVAL viLicence,INTVAL viType,LONGREF rlDetail,STRREF rsDetail,INTVAL viDetailLength );ArgumentsviHandleviLicenceviTyperlDetailrsDetailviDetailLengthHandle for this instance of the APIIndex into count of licensed data setsType of information detail to returnInteger detailString detailLength of rsDetailReturn ValuesEither: 0 if call is successfulOr: Negative error codeCommentsThe parameter viLicence should be passed an index into the count of licenseddata sets from QA_GetLicensingCount (), between 0 and the count – 1.If the symbolic name of the result detail type passed to viType is prefixed withqalicencestr_ then a string will be returned through the rsDetail parameter. Ifthe symbolic name is prefixed with qalicenceint_ then an integer will bereturned through the rlDetail parameter.98 • Primary API Function Reference QuickAddress Pro API

The parameter viType is used to specify what piece of information you want tobe returned. It can take one of the following values:Symbolic NameTypesDecimalValueDescriptionqalicencestr_ID 1 Returns the data set nameqalicencestr_DESCRIPTION 2 Returns a brief description of whatthe data set representsqalicencestr_COPYRIGHT 3 Returns the copyright informationfor the data setqalicencestr_VERSION 4 Returns the version of the dataqalicencestr_BASECOUNTRY 5 Returns the data ID of the countryto which the data set is an extensionqalicencestr_STATUS 6 Returns the string describing thestate of the data; for example if it isabout to expire.qalicencestr_SERVER 7 Returns the server name of wherethe data set is being usedqalicenceint_WARNINGLEVEL 8 Returns the warning level for thedata set This can take one of thevalues referred to on page 97qalicenceint_DAYSLEFT 9 Returns the number of days leftbefore the data set is unusableqalicenceint_DATADAYSLEFT 10 Return the number of days leftbefore the data expiresqalicenceint_LICENCEDAYSLEFT 11 Return the number of days left untilthe data set licence expiresThe following warning levels can be returned for theqalicenceint_WARNINGLEVEL detail type:QuickAddress Pro API Primary API Function Reference • 99

Symbolic NameDecimalValueDescriptionqalicwarn_NONE 0 No licence warningqalicwarn_DATAEXPIRING 10 The data set is about to expireqalicwarn_LICENCEEXPIRING 20 The licence for the data set isabout to expireqalicwarn_EVALUATION 30 The data is on an evaluationlicenceqalicwarn_DATAEXPIRED 40 The data set has expiredqalicwarn_EVALLICENCEEXPIRED 50 The evaluation licence for thedata set has expiredqalicwarn_FULLLICENCEEXPIRED 60 The full licence for the data sethas expiredqalicwarn_LICENCENOTFOUND 70 Licence information cannot befound for the data setqalicwarn_DATAUNREADABLE 80 The data set is not readableError ScenariosBusy HandleThe parameter viHandle has beenpassed a handle that is already in use inanother thread. Each handle can only beused by one thread at any point in time.100 • Primary API Function Reference QuickAddress Pro API

QA_GetPromptReturns the prompt text. This is a short sentence that can be displayed toprompt the user to search using the appropriate address items. For examplewhen beginning a search using the typedown engine the prompt may be “Enterplace or postcode”.PrototypeINTRET QA_GetPrompt (INTVAL viHandle,INTVAL viLine,STRREF rsPrompt,INTVAL viPromptLength,INTREF riSuggestedInputLengthSTRREF rsExample,INTVAL viExampleLength );ArgumentsviHandleviLinersPromptviPromptLengthriSuggestedInputLengthrsExampleviExampleLengthHandle for this instance of theAPIThe prompt line to be returned.Always pass 0.Buffer to receive a prompt lineThe length of the receive bufferFor future expansionFor future expansionFor future expansionReturn ValuesEither: 0 if call is successfulOr: Negative error codeQuickAddress Pro API Primary API Function Reference • 101

CommentsThe riSuggestedInputLength, rsExample and viExampleLength parametersshould be treated as any other parameter, except that any returned valuesshould be ignored for this release of the Pro API.Error ScenariosBusy HandleThe parameter viHandle has beenpassed a handle that is already in use inanother thread. Each handle can only beused by one thread at any point in time.102 • Primary API Function Reference QuickAddress Pro API

QA_GetPromptStatusReturns status information about the current prompt.PrototypeINTRET QA_GetPromptStatus (INTVAL viHandle,INTVAL viType,INTREF riStatus,STRREF rsStatus,INTVAL viStatusLength );ArgumentsviHandleviTyperiStatusrsStatusviStatusLengthHandle for this instance of the APIType of status information to receiveInteger status informationString status informationLength of rsStatusReturn ValuesEither: 0 if call is successfulOr: Negative error codeCommentsIf the symbolic name of the result detail type passed to viType is prefixed withqapromptstr_ then a string will be returned through the rsStatusl parameter.If the symbolic name is prefixed with qapromptint_ then an integer will bereturned through the rlStatus parameter.QuickAddress Pro API Primary API Function Reference • 103

The parameter viType is used to specify what piece of information you want tobe returned. It can take one of the following values:Symbolic NameTypesDecimalValueDescriptionqapromptint_DYNAMIC 2 Returns whether or not thecurrent prompt is dynamic. Seecomments below.The prompt status type qapromptint_DYNAMIC will return one of thefollowing values in parameter rlStatus.Boolean Valuesqavalue_FALSE 0 Falseqavalue_TRUE 1 TrueThe prompt status affects the way in which a GUI should display the text boxin which the user enters the search string. A non-dynamic prompt should beblanked after every call to QA_Search () and QA_StepIn () as the search textshould not be retained for the next stage. A dynamic prompt should only beblanked when QA_StepIn () is called, and should retain the text after a call toQA_Search ().The prompt status is designed to be obtained before the call to QA_Search (),not afterwards.Error ScenariosBusy HandleThe parameter viHandle has beenpassed a handle that is already in use inanother thread. Each handle can only beused by one thread at any point in time.104 • Primary API Function Reference QuickAddress Pro API

QA_GetResultObtains limited information about a given picklist item. The result count comesfrom QA_GetSearchStatus (see “QA_GetSearchStatus” on page 114).The flags that are returned for a given picklist item indicate what actions canbe performed upon it; for example, you can only step into a result usingQA_StepIn () if it has a qaresult_CANSTEP flag: otherwise anerror will be returned.PrototypeINTRET QA_GetResult (INTVAL viHandle,INTVAL viResult,STRREF rsDescription,INTVAL viDescriptionLength,INTREF riConfidence,LONGREF rlFlags );ArgumentsviHandleviResultrsDescriptionviDescriptionLengthriConfidencerlFlagsHandle for this instance of the APIIndex into available resultsResult text that will be displayed inthe picklistSize of rsDescriptionConfidence score of matchFlags describing the type of the givenpicklist itemReturn ValuesEither: 0 if call is successfulOr: Negative error codeQuickAddress Pro API Primary API Function Reference • 105

CommentsThe parameter viResult should be passed an index into the count of availablepicklist items from QA_GetSearchStatus (), between 0 and the count – 1.The value returned in riConfidence is an indication of how good a match is.The maximum value is 100%.The parameter rsDescription returns the text of each result item. The resultshows only enough information for your users to be able to distinguish betweendifferent matches. This element should be shown in a picklist to your users toallow them to chose the result to step in to.The parameter rlFlags can return the following flags ORed together. See“Flags Returned” on page 60:Symbolic NameDecimalValueDescriptionqaresult_FULLADDRESS 1 You have reached the fulldeliverable address and you cannow call QA_FormatResult ().See page 76 for moreinformation.qaresult_MULTIPLES 2 This item represents multipleaddress lines.qaresult_CANSTEP 4 This item can be stepped into,using QA_StepIn ().qaresult_ALIASMATCH 8 The match is an alias. See “AliasMatching” on page 27 for moreinformation.qaresult_POSTCODERECODED 16 The picklist item has a recodedpostcode. This is currently onlyavailable with GBR data; pleaserefer to your CountryInformation guide for moreinformation.106 • Primary API Function Reference QuickAddress Pro API

qaresult_CROSSBORDERMATCH 32 The picklist item represents anearby area outside the strictboundaries of the initial search.This applies to borderinglocalities, which are onlyrelevant to AUS data. If you areusing AUS data, refer to yourAustralia Getting Started guide.qaresult_DUMMYPOBOX 64 The item is the dummy PO Boxitem. See comments below thistable.qaresult_NAME 256 The picklist item is a Namesresult.qaresult_INFORMATION 1024 The result item is aninformational prompt (seecomments below).qaresult_WARNINFORMATION 2048 Warning informational promptitem (see comments below).qaresult_INCOMPLETEADDR 4096 The dummy item in premise-lesscountries (see commentsbelow).qaresult_UNRESOLVABLERANGE 8192 A static range item that cannotbe expanded. This applies toUSA data and some Europeandata sets only (see commentsbelow).A dummy PO Box picklist item is one that can be stepped into and contains POBox type addresses beneath. This should not be handled as a special case in anintegration, but a GUI may choose to use a different icon to display.An informational picklist item is one that does not correspond to an address,but instead conveys useful information to the user. Some informationalprompts can be stepped into, and so must never be filtered by the integration.The item itself should not be handled as a special case in an integration, but aGUI may choose to use a different icon to display.QuickAddress Pro API Primary API Function Reference • 107

A dummy item in a premise-less country will be returned for data sets wherepremise-level detail is not available. When you step into a picklist item thatcorresponds to a street, then this item may be returned in the resulting picklist.The result description of this item will prompt the user to enter the buildingdetails. This can then be used to refine the picklist and generate the desiredaddress. The item itself should not be handled as a special case in anintegration, but a GUI may choose to use a different icon to display.An unresolvable range item will be returned for a premise range that cannot bestepped into using QA_StepIn (). Instead, you must type text to refine thepicklist further to generate the desired complete address. The item itself shouldnot be handled as a special case, but a GUI integration may choose a differenticon to display.Error ScenariosBusy HandleBad IndexThe parameter viHandle has beenpassed a handle that is already in use inanother thread. Each handle can only beused by one thread at any point in time.The value passed to parameter viResultwas not a valid picklist item offset. Therange should be between 0 and thepicklist result count – 1.108 • Primary API Function Reference QuickAddress Pro API

QA_GetResultDetailObtains limited information about a picklist item. The result count comes fromQA_GetSearchStatus () (see “QA_GetSearchStatus” on page 114).PrototypeINTRET QA_GetResultDetail(INTVAL viHandle,INTVAL viResult,INTVAL viType,LONGREF rlDetail,STRREF rsDetail,INTVAL viDetailLength );ArgumentsviHandleviResultviTyperlDetailrsDetailviDetailLengthHandle for this instance of the APIIndex into available resultsType of result detail requestedReturned detail integerReturned detail stringLength of rsDetailReturn ValuesEither: 0 if call is successfulOr: Negative error codeCommentsThe parameter viResult should be passed an index into the count of availablepicklist items from QA_GetSearchStatus (), between 0 and the count – 1.If the symbolic name of the result detail type passed to viType is prefixed withqaresultstr_ then a string will be returned through the rsDetail parameter. Ifthe symbolic name is prefixed with qaresultint_ then an integer will bereturned through the rlDetail parameter.QuickAddress Pro API Primary API Function Reference • 109

The parameter viType is used to specify what piece of information you want tobe returned. It can take one of the following values:Symbolic NameTypesDecimalValueDescriptionqaresultstr_DESCRIPTION 2 Return the text descriptionfor the given item, suitablefor displaying in a picklistqaresultstr_PARTIALADDRESS 3 Return the partial addressfor the given result,formatted in a single line.See comments below.qaresultint_ISFULLADDRESS 13 Return whether the givenitem is a full deliverableaddress and you can nowcall QA_FormatResult ().See page 76 for moreinformation.qaresultint_ISMULTIPLES 14 Return whether the givenitem represents multipleaddress lines.qaresultint_ISCANSTEP 15 Return whether the givenitem can be stepped into,using QA_StepIn ().qaresultint_ISALIASMATCH 16 Return whether the givenitem is an alias. See “AliasMatching” on page 27 formore information.qaresultint_ISPOSTCODERECODED 17 The picklist item has arecoded postcode. This iscurrently only availablewith GBR data; please referto your CountryInformation guide for moreinformation.110 • Primary API Function Reference QuickAddress Pro API

qaresultint_ISCROSSBORDERMATCH 18 Return whether the givenitem represents a nearbyarea outside the strictboundaries of the initialsearch. This applies tobordering localities, whichare only relevant to AUSdata. If you are using AUSdata, refer to your AustraliaGetting Started guide.qaresultint_ISDUMMYPOBOX 19 Return whether the givenitem is the dummy PO Boxitem (see comments below).qaresultint_ISNAME 20 Return whether the givenitem is a Names result.qaresultint_ISINFORMATION 21 Return whether the givenitem is an informationalprompt (see commentsbelow).qaresultint_ISWARNINFORMATION 22 Return whether the givenitem is a warninginformational prompt (seecomments below).qaresultint_ISINCOMPLETESADDR 23 Return whether the givenitem is a dummy item inpremise-less countries (seecomments below).qaresultint_ISUNRESOLVABLERANGE 24 Return whether the givenitem is a static range itemthat cannot be expanded.This applies to USA dataonly (see comments below).QuickAddress Pro API Primary API Function Reference • 111

For the types that are prefixed qaresultint_IS, the following values can bereturned from the parameter rlDetail:Boolean Valuesqavalue_FALSE 0 Falseqavalue_TRUE 1 TrueA dummy PO Box picklist item is one that can be stepped into and contains PoBox type addresses beneath. This should not be handled as a special case in anintegration, but a GUI may choose to use a different icon to display.An informational picklist item is one that does not correspond to an address,but instead conveys useful information to the user. Some informationalprompts can be stepped into, and so must never be filtered by the integration.The item itself should not be handled as a special case in an integration, but aGUI may choose to use a different icon to display.A dummy item in a premise-less country will be returned for data sets wherepremise-level detail is not available. When you step into a picklist item thatcorresponds to a street, then this item may be returned in the resulting picklist.The result description will prompt you to enter the building detail which willrefine the picklist and generate the desired complete address. The item itselfshould not be handled as a special case in an integration, but a GUI may chooseto use a different icon to display.An unresolvable range item will be returned for a premise range that cannot bestepped into using QA_StepIn (). Instead, you must type text to refine thepicklist further to generate the desired complete address. The item itself shouldnot be handled as a special case, but a GUI integration may choose a differenticon to display.The partial address for a given result is a single line showing the most completeaddress information that can be returned at that stage of the search. Forexample, if the user has typed down to street level, and the street has a uniquepostcode and locality, the partial address would consist of the street name,locality and postcode, without a premise name or number.112 • Primary API Function Reference QuickAddress Pro API

Error ScenariosBusy HandleBad IndexThe parameter viHandle has beenpassed a handle that is already in use inanother thread. Each handle can only beused by one thread at any point in time.The value passed to parameter viResultwas not a valid picklist item offset. Therange should be between 0 and thepicklist result count – 1.QuickAddress Pro API Primary API Function Reference • 113

QA_GetSearchStatusObtains the status of a search. This function is an alternative toQA_GetSearchStatusDetail (). Using this function, all of the search status isreturned together through flags. See“Flags Returned” on page 60.This function is used to retrieve the number of results matched by the engine;and also if anything unexpected has occurred, such as if the search times out orif there are too many matches to display.This function can be called while a search is still in progress. This situationcould occur if you use asynchronous searching, or if the integration uses adifferent thread to call the function. See “Asynchronous Searching” on page 63for more information.PrototypeINTRET QA_GetSearchStatus ( INTVAL viHandle,INTREF riPicklistSize,INTREF riPotential,LONGREF rlSearchState );ArgumentsviHandleriPicklistSizeriPotentialrlSearchStateHandle for this instance of the APISize of the picklist used for the indexNumber of total potential itemsThe state after a searchReturn ValuesEither: 0 if call is successfulOr: Negative error code114 • Primary API Function Reference QuickAddress Pro API

CommentsThe flags with the prefix qastate_AUTO are related to auto stepping andformatting. For more information see “Automatic Stepping and Formatting” onpage 61.The parameter riPotential can be useful when the search has returned a numberof matches over the threshold, so riPicklistSize is 1. riPotential then gives anidea of how far the results exceed the threshold. The value that is returned fromriPotential is only an approximate estimate of the number of potential matches,which may indicate the extent of the refinement that should be performed inorder to return a single result. This estimate should only be used as a guide tothe user, and not relied upon in the integration.The returnable flags in the rlSearchState parameter are ORed together, and areas follows (see “Flags Returned” on page 60):Symbolic NameDecimalValueDescriptionqastate_NOSEARCH 1 No search has been started.qastate_STILLSEARCHING 2 The search is still in progress.qastate_TIMEOUT 4 The search has timed out.qastate_SEARCHCANCELLED 8 The search has been cancelledusing QA_CancelSearch ().qastate_MAXMATCHES 16 The maximum number of resultshas been reached, and there aretoo many to return: therefore, noresults are returned. The searchis finished and you must callQA_EndSearch () beforebeginning a new one.qastate_OVERTHRESHOLD 32 There are too many matches todisplay, as there are morepicklist items than the thresholdvalue. The threshold value is setin QA_SetEngineOption (): see“QA_SetEngineOption” onpage 133.QuickAddress Pro API Primary API Function Reference • 115

qastate_LARGEPOTENTIAL 64 Potentially, there are too manyresults to display, so you mustkeep typing (i.e., search with alarger string) in order to refinethe search.qastate_MOREOTHERMATCHES 128 There are additional othermatches that can be displayed.qastate_REFINING 256 Any text passed intoQA_Search () will be used torefine the current picklist ratherthan search.qastate_AUTOSTEPINSAFE 512 The current picklist is trivial,therefore it is suggested that youimmediately step into the firstpicklist item.qastate_AUTOSTEPINPASTCLOSE 1024 There are other close matchespresent, but only one exactmatch. Integrators may chooseto step immediately into the firstpicklist item with QA_StepIn().qastate_CANSTEPOUT 2048 Can step out of the picklist bycalling QA_StepOut ().qastate_AUTOFORMATSAFE 4096 The current picklist is trivial,therefore it is suggested that youimmediately format the firstpicklist item withQA_FormatResult ().qastate_AUTOFORMATPASTCLOSE 8192 There are other close matchespresent, but only one exactmatch. Integrators may chooseto format immediately the firstpicklist item withQA_FormatResult ().116 • Primary API Function Reference QuickAddress Pro API

QA_GetSearchStatusDetailObtains detailed information about the status of a search. This function is analternative to QA_GetSearchStatus (). Using this function you can inquireabout individual aspects of the search status separately, instead of obtaining allthe information through the use of flags.This function can be called while a search is still in progress. This situationcould occur if you use asynchronous searching, or if the integration uses adifferent thread to call the function. See “Asynchronous Searching” on page 63for more information.PrototypeINTRET QA_GetSearchStateDetail (INTVAL viHandle,INTVAL viType,LONGREF rlDetail,STRREF rsDetail,INTVAL viDetailLength );ArgumentsviHandleviTyperlDetailrsDetailviDetailLengthHandle for this instance of the APIType of detail requestedReturned detail integerReturned detail stringLength of rsDetailReturn ValuesEither: 0 if call is successfulOr: Negative error codeQuickAddress Pro API Primary API Function Reference • 117

CommentsIf the symbolic name of the result detail type passed to viType is prefixed withqassstr_ then a string will be returned through the rsDetail parameter. If thesymbolic name is prefixed with qassint_ then an integer will be returnedthrough the rlDetail parameter.The detail types with the prefix qassint_ISAUTO are related to auto steppingand formatting. For more information see “Automatic Stepping andFormatting” on page 61.The parameter viType is used to specify the information that you want to bereturned. It can take one of the following values:Symbolic NameTypesDecimalValueDescriptionqassint_PICKLISTSIZE 1 Returns the size of picklist.qassint_POTENTIALMATCHES 2 Returns the number ofpotential matches.qassint_SEARCHSTATE 3 Returns the search stateflags (as returned byQA_GetSearchStatus ()).See page 114.qassint_ISNOSEARCH 4 Returns whether a searchhas not yet been started.qassint_ISSTILLSEARCHING 5 Returns whether a search iscurrently in progress (see“Asynchronous Searching” onpage 63).qassint_ISTIMEOUT 6 Returns whether the searchtimed out. The timeoutlimit is set inQA_SetEngineOption ():see page 133.118 • Primary API Function Reference QuickAddress Pro API

qassint_ISSEARCHCANCELLED 7 Returns whether the searchhas been cancelled usingQA_CancelSearch ().qassint_ISMAXMATCHES 8 Returns whether themaximum number ofresults has been reachedand there are too many toreturn. See“QA_GetSearchStatus” onpage 114 for moreinformation aboutqastate_MAXMATCHES.qassint_ISOVERTHRESHOLD 9 Returns whether there aremore picklist items than thethreshold value, andtherefore too manymatches to display. See“QA_GetSearchStatus” onpage 114 for moreinformation aboutqastate_OVERTHRESHOLD.qassint_ISLARGEPOTENTIAL 10 Returns whether there arepotentially too manyresults to display and thesearch must be furtherrefined. See“QA_GetSearchStatus” onpage 114 for moreinformation aboutqastate_LARGEPOTENTIAL.QuickAddress Pro API Primary API Function Reference • 119

qassint_ISMOREOTHERMATCHES 11 Returns whether there areadditional other matchesthat can be displayed. See“QA_GetSearchStatus” onpage 114 for moreinformation aboutqastate_MOREOTHERMATCHES.qassint_ISREFINING 12 Returns whether any textpassed into QA_Searchwill be used to refine apicklist rather than tosearch. See“QA_GetSearchStatus” onpage 114 for moreinformation aboutqastate_REFINING.qassint_ISAUTOSTEPINSAFE 17 Returns whether thecurrent picklist is trivialand you should step intothe first item. See“QA_GetSearchStatus” onpage 114 for moreinformation aboutqastate_AUTOSTEPINSAFE.qassint_ISAUTOSTEPINPASTCLOSE 18 Returns whether there aresome close matches in thepicklist but only one exactmatch that could beautomatically stepped intousing QA_StepIn (). See“QA_GetSearchStatus” onpage 114 for moreinformation aboutqastate_ISAUTOSTEPINPASTCLOSE.120 • Primary API Function Reference QuickAddress Pro API

qassint_CANSTEPOUT 19 Returns whether thecurrent picklist can bestepped out of usingQA_StepOut ().qassint_ISAUTOFORMATSAFE 20 Returns whether thecurrent picklist is trivialand you should format thefirst item. See“QA_GetSearchStatus” onpage 114 for moreinformation aboutqastate_AUTOFORMATSAFE.qassint_ISAUTOFORMATPASTCLOSE 21 Returns whether there aresome close matches in thepicklist but only one exactmatch that could beautomatically formatted.See “QA_GetSearchStatus”on page 114 for moreinformation aboutqastate_AUTOFORMATPASTCLOSEFor the types that are prefixed qassint_IS and for qassint_CANSTEPOUT,the following values can be returned from the parameter rlDetail:Boolean Valuesqavalue_FALSE 0 Falseqavalue_TRUE 1 TrueQuickAddress Pro API Primary API Function Reference • 121

QA_GetSystemInfoGets a line of the system information produced by QA_GenerateSystemInfo.PrototypeINTRET QA_GetSystemInfo (INTVAL viHandle,INTVAL viLine,STRREF rsBuffer,INTVAL viBufferLength );ArgumentsviHandleviLinersBufferviBufferLengthHandle for this instance of the APILine number to extractReturned system information lineSize of rsBufferReturn ValuesEither: 0 if call is successfulOr: Negative error codeCommentsThe parameter viLine should be passed an index into the count of generatedsystem information lines from QA_GenerateSystemInfo (), between 0 andthe count – 1.Error ScenariosBusy HandleThe parameter viHandle has beenpassed a handle that is already in use inanother thread. Each handle can only beused by one thread at any point in time.122 • Primary API Function Reference QuickAddress Pro API

Bad IndexThe value passed to parameter viLinetwas not a valid line of generated systeminformation. The range should bebetween 0 and the count of lines - 1 fromQA_GenerateSystemInfo ().QuickAddress Pro API Primary API Function Reference • 123

QA_OpenOpens an instance of the API allowing you to specify the name of theconfiguration file to use and the section to use within that file.The handle returned from riHandle is the one you will pass to all otherfunctions. If the call to QA_Open () fails for any reason, then the handlereturned will not be valid to pass to other functions, except QA_Close ().There is no inherent limit on the number of instances that can be created withQA_Open () and held simultaneously. System resources as much as memorycan limit the number, although this would never typically be reached for anintegration upon a suitable machine.For more information on handles and instances, refer to “API Instances” onpage 59.PrototypeINTRET QA_Open (STRVAL vsIniFile,STRVAL vsSection,INTREF riHandle );ArgumentsvsIniFilevsSectionriHandleName of configuration file to openSection of the configuration file to useInstance handle returned by the APIReturn ValuesEither: 0 if call is successfulOr: Negative error codeCommentsThe layout for the instance will default to an internal layout that will be validbut may not be suitable. However, QAS strongly recommend that you shouldcall QA_SetActiveLayout () after QA_Open (). See “QA_SetActiveLayout”on page 129.124 • Primary API Function Reference QuickAddress Pro API

If no configuration file is specified, the standard ini file "qaworld.ini" will beused. If no section is specified, the default “QADefault” will be used.A call to QA_Open () must have a corresponding call to QA_Close ().Error ScenariosINI File ErrorOpen FailureThe configuration file specified inparameter viIniFile cannot be opened.The API was unable to create a newinstance. Use the LogErrorsconfiguration setting to determinewhere the problem lies. See page 194.QuickAddress Pro API Primary API Function Reference • 125

QA_SearchPerforms a search using the current active data set. See “QA_SetActiveData”on page 128.This function should be called when you have entered text to be searched upon.This will be in two cases:• You are entering the initial search using the single line engine.• You are entering text to refine the picklist further.To finish an old search and perform a new one, you must first callQA_EndSearch ().See “Searching with Pro” on page 19 for more information about how to searchand refine addresses.PrototypeINTRET QA_Search (INTVAL viHandleSTRREF rsSearch );ArgumentsviHandlersSearchHandle for this instance of the APIThe search stringReturn ValuesEither: 0 if call is successfulOr: Negative error codeError ScenariosBusy HandleThe parameter viHandle has beenpassed a handle that is already in use inanother thread. Each handle can only beused by one thread at any point in time.126 • Primary API Function Reference QuickAddress Pro API

Bad LayoutThe active layout that is set for theinstance is invalid. The list of validlayouts can be obtained by using theQA_GetLayoutCount () andQA_GetLayout () functions. A layoutmay be defined for a specific data setonly, and so changing the active data setmay invalidate the active layout.QuickAddress Pro API Primary API Function Reference • 127

QA_SetActiveDataSets the active data set to be searched upon. Data IDs for data sets are retrievedusing QA_GetData () which can be used to list all available data sets.If the active data set is changed once a search has begun, this will end thecurrent search and reset all results.Some layouts are defined only for specific data sets, and so changing the activedata set may invalidate the active layout. See “QA_SetActiveLayout” onpage 129 for more information.PrototypeINTRET QA_SetActiveData (INTVAL viHandle,STRVAL vsDataID );ArgumentsviHandlevsDataIDHandle for this instance of the APIData ID of the data set to useReturn ValuesEither: 0 if call is successfulOr: Negative error codeCommentsIf you pass a blank string to vsDataID, the active data will be set to the firstusable data set found by the system.Error ScenariosData NotAvailableThe data set specified in parametervsDataID is unavailable. This should bepassed data set IDs as returned byQA_GetDataCount () andQA_GetData ().128 • Primary API Function Reference QuickAddress Pro API

QA_SetActiveLayoutThis sets the layout that is used to format a final address. Layout names areretrieved using QA_GetLayout () which can be used to get all availablelayouts.Some layouts are defined only for specific data sets and so changing the activedata set (see “QA_SetActiveData” on page 128) may invalidate the activelayout. The integration must ensure that either:• All layout names are defined for all available data sets (advised).or• The integration checks that the active layout is still valid when theactive data set is changed by calling QA_GetLayoutCount () andQA_GetLayout ().You can call this function once a search has begun, although it will not affectan address that has already been formatted using QA_FormatResult () orQA_FormatExample (). If you wish to reformat an address using a differentlayout then you must recall the appropriate formatting function after changingthe active layout.PrototypeINTRET QA_SetActiveLayout (INTVAL viHandle,STRVAL vsLayout );ArgumentsviHandlevsLayoutHandle for this instance of the APILayout name as retrieved byQA_GetLayoutCommentsThe parameter vsLayout can optionally be passed a blank string instead of avalid layout name. This will set the layout to the default layout as specified inthe [QADefault] section of the configuration file, or to an internal layout if thisdoes not exist. This allows the integrator to specify a layout that is guaranteedto be valid for the active data set.QuickAddress Pro API Primary API Function Reference • 129

Return ValuesEither: 0 if call is successfulOr: Negative error codeError ScenariosBusy HandleBad LayoutThe parameter viHandle has beenpassed a handle that is already in use inanother thread. Each handle can only beused by one thread at any point in time.The layout that is being set for theinstance is invalid. The list of validlayouts can be obtained by using theQA_GetLayoutCount () andQA_GetLayout () functions.130 • Primary API Function Reference QuickAddress Pro API

QA_SetEngineChanges the current search engine to Single Line or Typedown.If the search engine is changed during a search, this will end the current search.Refer to “Searching Methods” on page 19 for information about the differencesbetween the two search engines and how to use them.PrototypeINTRET QA_SetEngine ( INTVAL viHandleINTVAL viEngine);ArgumentsviHandleviEngineHandle for this instance of the APIEngine to be selectedReturn ValuesEither: 0 if call is successfulOr: Negative error codeCommentsThe possible search engines that can be passed to viEngine are:Symbolic NameDecimalValueDescriptionqaengine_SINGLELINE 1 Single line engineqaengine_TYPEDOWN 2 Typedown engineQuickAddress Pro API Primary API Function Reference • 131

Error ScenariosBusy HandleThe parameter viHandle has beenpassed a handle that is already in use inanother thread. Each handle can only beused by one thread at any point in time.132 • Primary API Function Reference QuickAddress Pro API

QA_SetEngineOptionSets engine-related attributes for the given engine. The attributes that can bemodified include threshold, timeout, search intensity and asynchronousoperation.PrototypeINTRET QA_SetEngineOption (INTVAL viHandle,INTVAL viEngOption,LONGVAL vlValue );ArgumentsviHandleviEngOptionvlValueHandle to the APIThe engine option to be setValue for this optionReturn ValuesEither: 0 if call is successfulOr: Negative error codeCommentsThe possible engine options that can passed to viEngOption are as follows:Symbolic NameOptionsDecimalValueDescriptionqaengopt_DEFAULT 0 Resets the engine optionsto the defaults.qaengopt_ASYNCSEARCH 1 Single line searches will beasynchronous. The defaultis qavalue_FALSE.qaengopt_ASYNCSTEPIN 2 Calls to QA_StepIn will beasynchronous. The defaultis qavalue_FALSE.QuickAddress Pro API Primary API Function Reference • 133

qaengopt_ASYNCREFINE 3 Picklist refinement will beasynchronous. The defaultis qavalue_FALSE.qaengopt_THRESHOLD 6 Allows you to set the resultsize threshold. The defaultis 25. The minimum limit is5 and the maximum limit is1000.qaengopt_TIMEOUT 7 Allows you to set thetimeout limit (ms). Thedefault is 0 milliseconds(never times out) and thelimit is 600000 (10minutes).qaengopt_SEARCHINTENSITY 8 Single-line mode editdistance level. The defaultis qaintensity_CLOSE.The engine options that control asynchronous searching (see “AsynchronousSearching” on page 63) are as follows:• qaengopt_ASYNCSEARCH• qaengopt_ASYNCSTEPIN• qaengopt_ASYNCREFINEThese can only be used for multithreaded versions of the library: the singlethreaded version of the library will not accept them. This is because theyrequire the API to create threads if the options are enabled.The type qaengopt_DEFAULT does not use the parameter vlValue.134 • Primary API Function Reference QuickAddress Pro API

The types qaengopt_ASYNCSEARCH, qaengopt_ASYNCSTEPIN andqaengopt_ASYNCREFINE can have the following values passed to parametervlValue:Boolean Valuesqavalue_FALSE 0 Falseqavalue_TRUE 1 TrueThe engine option type qaengopt_SEARCHINTENSITY can have thefollowing values passed to parameter vlValue:Valuesqaintensity_EXACT 0 Exact searchingqaintensity_CLOSE 1 Close searchingqaintensity_EXTENSIVE 2 Extensive searchingThe search intensity setting represents how hard the Single Line search enginewill search for an address with respect to the accuracy of matches. If the searchintensity is set higher, then searches may take longer to perform, although moreinexact matches will be returned.When using qaengopt_THRESHOLD and qaengopt_TIMEOUT, an integervalue should be passed to vlValue.Error ScenariosBusy HandleBad ValueThe parameter viHandle has beenpassed a handle that is already in use inanother thread. Each handle can only beused by one thread at any point in time.The value passed to parameter vlValueis not valid for the given engine option.QuickAddress Pro API Primary API Function Reference • 135

QA_ShutdownCloses down the API, and must be called as the final function, after allinstances have been closed with QA_Close ().The shutdown function frees all resources associated with the Universal APIand must be the last function to be called in the API before the calling programends or unloads the API from memory.See “API Instances” on page 59.PrototypeVOIDRET QA_Shutdown (VOIDARG);136 • Primary API Function Reference QuickAddress Pro API

QA_StepInSelects a picklist item from a picklist to expand further.You can only step into a result if it has a qaresult_CANSTEP flag: otherwisean error will be returned. See “QA_GetResult” on page 105 and“QA_GetResultDetail” on page 109 for more information.PrototypeINTRET QA_StepIn (INTVAL viHandle,INTVAL viResult );ArgumentsviHandleviResultHandle for this instance of the APIIndex of picklist itemReturn ValuesEither: 0 if call is successfulOr: Negative error codeCommentsThe parameter viResult should be passed an index into the count of availablepicklist items from QA_GetSearchStatus (), between 0 and the count – 1.Error ScenariosBusy HandleBad IndexThe parameter viHandle has beenpassed a handle that is already in use inanother thread. Each handle can only beused by one thread at any point in time.The value passed to parameter viResultwas not a valid picklist item offset. Therange should be between 0 and thepicklist result count – 1.QuickAddress Pro API Primary API Function Reference • 137

Bad StepThe picklist result item that was passedinto viResult is not an item that can bestepped into. Only picklist items thathave the flag qaresult_CANSTEPfrom QA_GetResult () can be steppedinto.138 • Primary API Function Reference QuickAddress Pro API

QA_StepOutSteps back a stage in a search, returning to the previous list of items.This is not possible if a step in has not been performed. If QA_StepOut () iscalled before QA_StepIn (), an error will be returned. The search stateqastate_CANSTEPOUT can be used to determine whether QA_StepOut () canbe called.See “QA_GetSearchStatus” on page 114 and “QA_GetSearchStatusDetail” onpage 117.PrototypeINTRET QA_StepOut ( INTVAL viHandle );ArgumentsviHandleHandle for this instance of the API.Return ValuesEither: 0 if call is successfulOr: Negative error codeError ScenariosBusy HandleOut ofSequenceBad StepThe parameter viHandle has beenpassed a handle that is already in use inanother thread. Each handle can only beused by one thread at any point in time.The API cannot ‘step out’ of a picklist ifa search has not been yet performed.The picklist cannot be stepped out from,as it is at the top level. This can bechecked through the API by callingQA_GetSearchStatus () and checkingfor the flag qastate_CANSTEPOUT.QuickAddress Pro API Primary API Function Reference • 139

User Interface APIFunction ReferenceHandling Client/Server ErrorsThis section is only applicable if you have configured the Pro client to use thePro server.There are some network communication errors from which it is not alwayspossible to recover. These error conditions are listed below:• Server connection fullWhilst connecting to a server, the server’s maximum connection counthas been reached.• Connection cancelledThis occurs when there is a failure to find a server, or when theconnection to the server is lost.• Connection timeoutThe server has failed to respond within the timeout period.If any of the above error conditions occur, the Pro API will returnqaerr_NOLIVESERVER. This error is fatal - you must therefore close the APIby calling QAProWV_UIShutdown. (Any other operations will continue toreturn the error.)You may continue operation by attempting to open the API withQAProWV_UIStartup.If you have multiple servers configured, you will only need to callQAProWV_UIStartup once, as it will attempt to connect to each server inturn before returning qaerr_NOLIVESERVER.QuickAddress Pro API User Interface API Function Reference • 141

UI API Function ReferenceThe User Interface API functions can be split into three groups:• General FunctionsStarting up and shutting down the API.• Search FunctionsPerforming a search, and retrieving picklists of results and formattedaddresses.• Housekeeping FunctionsViewing and selecting available country databases, address formats andfunctionality flags.Below is a full list of the Pro User Interface API functions and where you canfind them:General FunctionsQAProWV_UIStartupInitialises the APIQAProWV_UIShutdownCloses down the APIpage 169page 168Search FunctionsQAProWV_UISearchPerforms a search on an input stringQAProWV_UIResultCountReturns a count of the number of lines ina selected addressQAProWV_UIGetResultRetrieves a full matched addresspage 162page 161page 155142 • User Interface API Function Reference QuickAddress Pro API

Housekeeping FunctionsQAProWV_UILayoutCountReturns a count of available layoutsQAProWV_UIGetLayoutRetrieves the name of one layoutQAProWV_UIGetActiveLayoutRetrieves the name of the currentlyselected layoutQAProWV_UISetActiveLayoutSelects a new layout to useQAProWV_UILayoutLineElementsRetrieves the element fixed to a specificlayout lineQAProWV_UICountryCountReturns a count of available countrydatabasesQAProWV_UIGetCountryRetrieves the name of one countrydatabaseQAProWV_UIGetActiveCountryRetrieves the name of the currentlyselected country databaseQAProWV_UISetActiveCountrySelects a new country database to useQAProWV_UIGetFlagsRetrieves the currently-set functionalityflagsQAProWV_UISetFlagsSets new functionality flagspage 157page 153page 148page 165page 158page 144page 150page 146page 163page 152page 167QuickAddress Pro API User Interface API Function Reference • 143

QAProWV_UICountryCountRetrieves the number of installed country databases available to the API.Pre-call ConditionsThe API has been started with QAProWV_UIStartup.PrototypeINTRET QAProWV_UICountryCount (INTREF riCount);Input ParametersArgumentriCountExplanationNumber of country databasesavailableReturn ValuesEither: 0 if call is successfulOr: negative error codePossible Error Codes:–3407 qaerr_UIAPINOTSTARTEDCommentsThis function tells you how many country databases are configured for the API.The availability of country databases is determined by your qawserve.ini file.Once you have the number of databases, you can callQAProWV_UIGetCountry as many times as is necessary to retrieve adescription of each country database.144 • User Interface API Function Reference QuickAddress Pro API

See AlsoQAProWV_UIStartupQAProWV_UIGetCountryQuickAddress Pro API User Interface API Function Reference • 145

QAProWV_UIGetActiveCountryRetrieves the country identifier of the currently active country database.Pre-call ConditionsThe API has been started with QAProWV_UIStartup.PrototypeINTRET QAProWV_UIGetActiveCountry (STRREF rsBuffer,INTVAL viLength );Input ParametersArgumentrsBufferviLengthExplanationBuffer to receive country identifierLength of rsBufferReturn ValuesEither: 0 if call is successfulOr: negative error codePossible Error Codes:–3407 qaerr_UIAPINOTSTARTEDCommentsThe country identifier returned by this function is that of the country databasecurrently open for searching. Any search submitted to the API at this point withQAProWV_UISearch will be checked against this database.This country database is the one specified in your call toQAProWV_UIStartup, unless it has been changed since withQAProWV_UISetActiveCountry or via the user interface.As a country identifier is three characters long, you should use a minimumbuffer of size of 4 to allow for a null terminating character.146 • User Interface API Function Reference QuickAddress Pro API

See AlsoQAProWV_UIStartupQAProWV_UISetActiveCountryQuickAddress Pro API User Interface API Function Reference • 147

QAProWV_UIGetActiveLayoutRetrieves the name of the current configuration layout.Pre-call ConditionsThe API has been started with QAProWV_UIStartup.PrototypeINTRET QAProWV_UIGetActiveLayout (STRREF rsBuffer,INTVAL viLength );Input ParametersArgumentrsBufferviLengthExplanationBuffer to receive layout nameLength of rsBufferReturn ValuesEither: 0 if call is successfulOr: negative error codePossible Error Codes:–3407 qaerr_UIAPINOTSTARTEDCommentsThe layout name returned by this function is that of the configuration layoutcurrently in use. Any address returned from a search submitted to the API atthis point with QAProWV_UISearch will be formatted according to thislayout.The layout is the one specified in your call to QAProWV_UIStartup, unlessit has been changed since with QAProWV_UISetActiveLayout or via theuser interface.148 • User Interface API Function Reference QuickAddress Pro API

See AlsoQAProWV_UIStartupQAProWV_UISetActiveLayoutQuickAddress Pro API User Interface API Function Reference • 149

QAProWV_UIGetCountryRetrieves one country database name and country identifier, in conjunctionwith QAProWV_UICountryCount.Pre-call ConditionsQAProWV_UIStartup has been called to start the API.QAProWV_UICountryCount has been called to return a count of theavailable country databases.PrototypeINTRET QAProWV_UIGetCountry (INTREF riCount,INTVAL viIndex,STRREF rsIsoBuffer,STRREF rsNameBuffer,INTVAL viNameLength );Input ParametersArgumentviIndexrsIsoBufferrsNameBufferviNameLengthExplanationNumber of country database (from0 to QAProWV_UICountryCount–1)Buffer to receive country identifierof country databaseBuffer to receive name of countrydatabaseMaximum length of rsIsoBuffer andrsNameBufferReturn ValuesEither: 0 if call is successfulOr: negative error code150 • User Interface API Function Reference QuickAddress Pro API

Possible Error Codes:–3400 qaerr_INVALIDCOUNTRYINDEX–3407 qaerr_UIAPINOTSTARTEDCommentsThis function, in conjunction with QAProWV_UICountryCount, is useful ifyou want to confirm the number, names and country identifiers of availablecountry databases for a particular instance of the API. For example, you mightwant to use this functionality prior to the first call of QAProWV_UISearch,so that you know which countries are available to search on.You should call this function as many times as required to retrieve countrydatabase details. For example, if QAProWV_UICountryCount returned acount of 4, you would call this function a maximum of four times to retrievedetails of each database, setting viIndex to 0, 1, 2 and 3.The parameter viIndex contains the number of the country database whosedetails you want to retrieve – for example, inputting 0 retrieves the name of thefirst installed database, 1 returns the name of the second database, and so on.The output parameters rsIsoBuffer and rsNameBuffer contain the countryidentifier and country name respectively of a country database. A countryidentifier is a unique three-letter descriptor for a country, which appears on thedata sheet supplied with each country database. For example, the Australiacountry database has the identifier AUS. The rsIsoBuffer parameter shouldalways have at least a four-character buffer.See AlsoQAProWV_UICountryCountQuickAddress Pro API User Interface API Function Reference • 151

QAProWV_UIGetFlagsReturns the current configuration flags.Pre-call ConditionsThe API has been started with QAProWV_UIStartup.PrototypeINTRET QAProWV_UIGetFlags (LONGREF rlFlags );Input ParametersArgumentrlFlagsExplanationLine description flagsReturn ValuesEither: 0 if call is successfulOr: negative error codePossible Error Codes:–3407 qaerr_UIAPINOTSTARTEDCommentsThis function tells you which functionality flags are currently set. The flags areoriginally set with QAProWV_UIStartup; see page 170 for a full list ofavailable flags.To add or remove flags, call QAProWV_UISetFlags.See AlsoQAProWV_UISetFlagsQAProWV_UIStartup152 • User Interface API Function Reference QuickAddress Pro API

QAProWV_UIGetLayoutRetrieves the name of a particular configuration layout.Pre-call ConditionsQAProWV_UIStartup has been called to start the API.QAProWV_UILayoutCount has been called to return a count of the availablelayouts.PrototypeINTRET QAProWV_UIGetLayout INTVAL viIndex,STRREF rsBuffer,INTVAL viLength );Input ParametersArgumentviIndexrsBufferviLengthExplanationNumber of layout to retrieve (from0 to QAProWV_UILayoutCount–1)Buffer to receive layout nameMaximum length of rsBufferReturn ValuesEither: 0 if call is successfulOr: negative error codePossible Error Codes:–3401 qaerr_INVALIDLAYOUTINDEX–3407 qaerr_UIAPINOTSTARTEDQuickAddress Pro API User Interface API Function Reference • 153

CommentsThis function, in conjunction with QAProWV_UILayoutCount, is useful ifyou want to confirm the number and names of available configuration layoutsprior to searching.You should call this function as many times as required to retrieve layoutnames from a configuration file. For example, if QAProWV_UILayoutCountreturned a count of 6, you would call QAProWV_UIGetLayout six times toretrieve each layout name.The parameter viIndex contains the number of the layout whose name you wantto retrieve – for example, inputting 0 retrieves the name of the first layout inthe configuration file, 1 returns the name of the second layout, and so on. Anerror will be returned if an invalid number is passed into this parameter.See AlsoQAProWV_UILayoutCount154 • User Interface API Function Reference QuickAddress Pro API

QAProWV_UIGetResultRetrieves one line of a returned address.Pre-call ConditionsThe API has been started with QAProWV_UIStartup, and a search has beenstarted with QAProWV_UISearch.PrototypeINTRET QAProWV_UIGetResult (INTVAL viIndex,STRREF rsBuffer,INTVAL viLength );Input ParametersArgumentviIndexrsBufferviLengthExplanationNumber of the line to retrieve (from0 to QAProWV_UIResultCount –1)Buffer to receive search resultMaximum length of rsBufferReturn ValuesEither: 0 if call is successfulOr: negative error codePossible Error Codes:–3407 qaerr_UIAPINOTSTARTED–3803 qaerr_INVALIDADDRESSLINEQuickAddress Pro API User Interface API Function Reference • 155

CommentsThis function returns one formatted address line from a search. You get thetotal number of address lines from the function QAProWV_UIResultCount.You should call this function as many times as required to retrieve the fulladdress. For example, if QAProWV_UIResultCount returned a count of 5address lines, you would call this function five times to retrieve each item.The parameter viIndex contains the number of the result line which you wantto retrieve – for example, inputting 0 retrieves the description of the first linein the layout, 1 returns the second line, and so on. An error will be returned ifan invalid line number is specified.See AlsoQAProWV_UIResultCount156 • User Interface API Function Reference QuickAddress Pro API

QAProWV_UILayoutCountRetrieves the number of available layouts in the configuration file.Pre-call ConditionsThe API has been started with QAProWV_UIStartup.PrototypeINTRET QAProWV_UILayoutCount (INTREF riCount);Input ParametersArgumentriCountExplanationNumber of layouts in theconfiguration fileReturn ValuesEither: 0 if call is successfulOr: negative error codePossible Error Codes:–3407 qaerr_UIAPINOTSTARTEDCommentsThis function tells you how many configuration layouts are available in yourqawserve.ini file. The number available to use depends on the active country.See page 197 for a detailed description of configuration files and layouts.Once you have the number of layouts, you can call QAProWV_UIGetLayoutas many times as is necessary to retrieve the name of each layout.See AlsoQAProWV_UIGetLayoutQuickAddress Pro API User Interface API Function Reference • 157

QAProWV_UILayoutLineElementsReturns a description of the element fixed to a particular line of the currentlyselected address layout.Pre-call ConditionsThe API has been started with QAProWV_UIStartup and a layout has beenselected.PrototypeINTRET QAProWV_UILayoutLineElements (INTVAL viIndex,STRREF rsBuffer,INTVAL viLength,LONGREF rlType );Input ParametersArgumentviIndexrsBufferviLengthrlTypeExplanationAddress line to retrieveBuffer to receive line elementsMaximum length of rsBufferLine type descriptionReturn ValuesEither: 0 if call is successfulOr: negative error codePossible Error Codes:–3411 qaerr_INVALIDLINEINDEX158 • User Interface API Function Reference QuickAddress Pro API

CommentsThis function tells you which address elements, if any, have been fixed tocertain lines of the address layout. This function returns the name of an addresselement when there is only one element fixed to a line. If there is more than oneelement fixed to a line, a blank string will be returned. See page 202 for detailsof how to fix an element to a line.If you want to retrieve descriptions of each address line from the current layout,you should call this function as many times as required. For example, if youraddress layout contains 6 address lines (as indicated by a call toQAProWV_UIResultCount), you could call this function six times to retrieveeach layout line.The parameter viIndex contains the number of the address line whosedescription you want to retrieve. This is zero-based – for example, inputting 0retrieves the description of the first line in the layout, 1 returns the second line,and so on.The parameter rsBuffer contains the results of the function call. For example,if the town was fixed to line 4 of an address layout, you would set the value ofviIndex as 3, and rsBuffer would return “Town”. If there are no elements fixedto the line that you have specified, the buffer will be empty.The rlType parameter contains the type of line that is being retrieved. The typesthat can be returned are as follows:Type NameDecimal Valueelement_ADDRESS 0element_NAME 1element_DATAPLUS 2element_ANCILLARY 3QuickAddress Pro API User Interface API Function Reference • 159

For example, you might have a seven-line address layout, where the first linecontains name information, the second to sixth lines contain the address, andthe final line is reserved for DataPlus data. In this case, the first line of thereturned address would return element_NAME, the last line would returnelement_DATAPLUS, and the lines in between would returnelement_ADDRESS.The values assigned to each type are symbolic constants defined by the API,and appear in the prototyped header files for each language.This function will fail safely with an error if the viIndex parameter is out ofrange (for example, if you specify line 6 in a five line layout);See AlsoQAProWV_UISetActiveLayout160 • User Interface API Function Reference QuickAddress Pro API

QAProWV_UIResultCountReturns a count of the number of address lines in a selected address.Pre-call ConditionsThe API has been started with QAProWV_UIStartup, and a search has beensubmitted with QAProWV_UISearch.PrototypeINTRET QAProWV_UIResultCount (INTREFriCount);Input ParametersArgumentriCountExplanationNumber of address linesReturn ValuesEither: 0 if call is successfulOr: negative error codePossible Error Codes:–3407 qaerr_UIAPINOTSTARTEDCommentsThis function tells you the number of lines in the final selected address, andhence how many times the function QAProWV_UIGetResult needs to becalled in order to retrieve them.See AlsoQAProWV_UIGetResultQuickAddress Pro API User Interface API Function Reference • 161

QAProWV_UISearchPerforms a search on the input string.Pre-call ConditionsThe API has been started with QAProWV_UIStartup.PrototypeINTRET QAProWV_UISearch (STRVAL vsSearch );Input ParametersArgumentvsSearchExplanationInput string to search onReturn ValuesEither: positive value for successful searchOr: 0 if search cancelledOr: negative error codePossible Error Codes:–3407 qaerr_UIAPINOTSTARTEDCommentsIf the specified search returns a single matching property, and theqaattribs_NOCONFIRMVIEW and qaattribs_MINDISPLAY flags are ineffect, it can be retrieved immediately by calling QAProWV_UIResultCountand QAProWV_UIGetResult. Otherwise, the search results will be displayedin the Pro User Interface for the user to interactively confirm, before thisfunction returns.See AlsoQAProWV_UIResultCount162 • User Interface API Function Reference QuickAddress Pro API

QAProWV_UISetActiveCountryChanges the active country database.Pre-call ConditionsThe API has been started with QAProWV_UIStartup.PrototypeINTRET QAProWV_UISetActiveCountry (STRVAL vsIsoCode);Input ParametersArgumentvsIsoCodeExplanationIdentifier of the country database tochange toReturn ValuesEither: 0 if call is successfulOr: negative error codePossible Error Codes:–3407 qaerr_UIAPINOTSTARTED–3405 qaerr_CANTCHANGEDATABASECommentsThis function allows you to switch between country databases without closingdown the API. The country database is originally set in the call toQAProWV_UIStartup.For example, passing AUS in the vsIsoCode parameter changes the activecountry database to Australia (if you have Australian data installed).You can find out which country databases are available with the functionsQAProWV_UICountryCount and QAProWV_UIGetCountry. An errorwill be returned if you specify the code of a database that is not installed.QuickAddress Pro API User Interface API Function Reference • 163

See AlsoQAProWV_UICountryCountQAProWV_UIGetCountryQAProWV_UIGetActiveCountry164 • User Interface API Function Reference QuickAddress Pro API

QAProWV_UISetActiveLayoutChanges the configuration layout.Pre-call ConditionsThe API has been started with QAProWV_UIStartup.PrototypeINTRET QAProWV_UISetActiveLayout (STRVAL vsLayout);Input ParametersArgumentvsLayoutExplanationLayout name to change toReturn ValuesEither: 0 if call is successfulOr: negative error codePossible Error Codes:–3402 qaerr_UNKNOWNLAYOUTNAME–3407 qaerr_UIAPINOTSTARTEDCommentsThis function allows you to switch between configuration layouts within aninstance of the API. The layout was originally set with your call toQAProWV_UIStartup.You can find out which layouts are available in the configuration file with thefunctions QAProWV_UILayoutCount and QAProWV_UIGetLayout.The text in vsLayout must match one of the layout names returned fromQAProWV_UIGetLayout, or an error will be returned. Note that the functionis case-sensitive – for example, to select the layout QADefault, you cannotenter ‘qadefault’, as the API will not recognise it.QuickAddress Pro API User Interface API Function Reference • 165

See AlsoQAProWV_UIGetLayoutQAProWV_UILayoutCountQAProWV_UIGetActiveLayout166 • User Interface API Function Reference QuickAddress Pro API

QAProWV_UISetFlagsAdds and removes configuration flags.Pre-call ConditionsThe API has been started with QAProWV_UIStartup.PrototypeINTRET QAProWV_UISetFlags (LONGVAL vlRemove,LONGVAL vlAdd );Input ParametersArgumentvlRemovevlAddExplanationFlags to removeFlags to addReturn ValuesEither: 0 if call is successfulOr: negative error codePossible Error Codes:–3407 qaerr_UIAPINOTSTARTED–3414 qaerr_BADCONFIGFLAGSCommentsThis function allows you to change the flags that were set withQAProWV_UIStartup. See page 170 for a list of the available flags.Call the function QAProWV_UIGetFlags for a list of the currently set flags.See AlsoQAProWV_UIGetFlagsQAProWV_UIStartupQuickAddress Pro API User Interface API Function Reference • 167

QAProWV_UIShutdownCloses down the API.Pre-call ConditionsThe API is initialised.PrototypeVOIDRET QAProWV_UIShutdown (INTVAL viStatus );Input ParametersArgumentviStatusExplanationLast returned status code to bereported by the API prior to fullshutdown.CommentsThis function will close down the API completely, and must be called as thefinal function.If another function has returned an error, you can specify this as the inputparameter in the call to QAProWV_UIShutdown. Then, when the API shutsdown, a dialog box will appear with a description of the error. If you havereceived an error which you wish to handle yourself, or are shutting downwithout errors, pass 0 (zero) into the function.See AlsoQAProWV_UIStartup168 • User Interface API Function Reference QuickAddress Pro API

QAProWV_UIStartupOpens an instance of the API, specifying the name of the configuration file tobe used, the layout to format addresses with, and the available functionality.Pre-call ConditionsNone.PrototypeINTRET QAProWV_UIStartup (STRVAL vsTitle,STRVAL vsIniFile,STRVAL vsCountry,STRVAL vsLayout,STRVAL vsLanguage,LONGVAL vlFlags );Input ParametersArgumentvsTitlevsIniFilevsCountryvsLayoutvsLanguagevlFlagsExplanationText to display in title barName of configuration file to openName of country database to openName of configuration layout to useReserved for future use (should beset to NULL)Search functionalityReturn ValuesEither: 0 if call is successfulOr: negative error codeQuickAddress Pro API User Interface API Function Reference • 169

Possible Error Codes:–1031 qaerr_BADINIFILE–3405 qaerr_CANTCHANGEDATABASE–3406 qaerr_UIAPIALREADYSTARTED–3413 qaerr_NOLIVESERVER–3414 qaerr_BADCONFIGFLAGSCommentsWhen you open an instance of the Pro API, you need to specify five things:• The title which appears at the top of the dialog together with the activecountry (defaults to blank) in vsTitle.• A configuration file (default qaworld.ini) in vsIniFile.• A layout within the configuration file (default QADefault) in vsLayout.• The country database to open for searching (defaults to thealphabetically first installed country) in vsCountry.• The initial functionality to use in vlFlags.If NULL or an empty string is passed into any of the above STRVAL inputparameters, the API uses the defaults listed.The flags that can be passed into vlFlags are as follows:qaattribs_NONE0(Default)qaattribs_NOCONFIRMVIEW4qaattribs_NOLAYOUTCHANGE8All options set from ConfigurationEditor (see page 197). You do notneed to specify any other flags.When a full address is found, it isreturned directly to yourapplication rather than to Pro’saddress edit screen (see page 40).Disables ability to change layout.In order to enable this ability, theflag and the .ini setting must beset.170 • User Interface API Function Reference QuickAddress Pro API

qaattribs_NOHELP16qaattribs_NOCHANGEMODE32qaattribs_NOCHANGECOUNTRY128qaattribs_SINGLELINESEARCH256qaattribs_TYPEDOWNSEARCH512qaattribs_NOPROBITMAP8192qaattribs_MINDISPLAY16384qaattribs_READONLY65536Disables Help facility. Note thatthe UIShowHelp INI setting hassimilar functionality, and that thereis no Help provided for the UIAPI.Disables ability to changesearching mode. This needs to beset in conjunction with eitherqaattribs_SINGLELINESEARCHorqaattribs_TYPEDOWNSEARCHDisables ability to switch betweencountry databases. In order toenable this ability, the flag and the.ini setting must be set.Starts API in Single Line searchmode.Starts API in Typedown searchmode.Displays the User Interfacewithout the QuickAddress Probitmap.Only displays the Pro UserInterface if necessary – i.e. allsearches are done from yourapplication and the User Interfaceonly appears if there is a picklist ofresults or an address to beconfirmed/edited.If this flag is set, users will beunable to edit addresses returnedto the address edit screen. Thisoverrides the Allow AddressEditing option in ConfigurationEditorQuickAddress Pro API User Interface API Function Reference • 171

qaattribs_NOLICENSINGDLG131072Disables ‘Dataset Due to Expire’dialog, which is displayed bydefault when Pro is started up.This lists all the datasets that aredue to expire soon.The value beneath each flag represents that flag’s hexadecimal value. If youwant to specify more than one of these flags (for example, Single Linesearching and no Pro bitmap), the values should be ORed together.If you set qaattribs_SINGLELINESEARCH andqaattribs_TYPEDOWNSEARCH (setting the vlFlags parameter to0x00000300), the search engine will default to Typedown. To change thesearch engine, call QAProWV_UISetFlags with only one of the search flagsset.You will get an error if Pro API cannot find the specified configuration file, orif one of the country databases has expired or has been moved from its defaultlocation.Fail-over logic is included so that QAProWV_UIStartup will loop through allof the defined servers until a successful connection can be established. See theClient/Server Guide or Client/Server Help for more information on fail-overlogic.See AlsoQAProWV_UIShutdown172 • User Interface API Function Reference QuickAddress Pro API

Low-Level System FunctionsThe User Interface API also includes three low-level system functions.The first of these is QAErrorMessage. This function translates a numericQuickAddress error code into a simple textual explanation of that error. For afull list of error codes see Appendix A, which starts on page 217.Next is QAErrorLevel, which indicates the severity of an error and whetheryou should take action on it.Finally comes QASystemInfo, which lists system usage details, such as whatresources the API has taken from your operating system.These functions are described on the following pages.QuickAddress Pro API User Interface API Function Reference • 173

QAErrorMessageThis function translates an error code to a text messagePrototypeVOIDRET QAErrorMessage (INTVAL viStatus,STRREF rsBuffer,INTVAL viBuffLen );Input ParametersArgumentviStatusrsBufferviBuffLenExplanationError codeBuffer to receive error text messageMaximum length of the buffer(including room for NULLterminator)CommentsThis function is useful for converting a QuickAddress error code to a short textmessage that can be displayed to the user for informational purposes.It is advised that QAErrorMessage is called after any function which returnsan error code, as the text message might help you identify the cause of the error.174 • User Interface API Function Reference QuickAddress Pro API

QAErrorLevelReturns the severity of an errorPrototypeINTRET QAErrorLevel ( INTVAL viStatus );Input ParametersArgumentviStatusExplanationError codeReturn ValuesEither: 0 for a fatal or serious errorOr: 1 for a warningCommentsThis function indicates the severity of an error returned by the API. A fatal orserious error should be flagged to the user and must be dealt with. A warningshould be handled in a manner appropriate to the condition and can, if desired,be ignored.QuickAddress Pro API User Interface API Function Reference • 175

QASystemInfoReturns detailed information about the system usage of the QuickAddresslibraryPrototypeINTRET QASystemInfo (INTVAL viLineNo,STRREF rsBuffer,INTVAL viBuffLen );Input ParametersArgumentviLineNorsBufferviBuffLenExplanationLine number being accessed (ornegative if resetting)Buffer to receive text lineBuffer length (including room forNULL terminator)Return ValuesEither: 0 if call is successfulOr: negative error code for an invalid line numberCommentsYou must call QAProwv_UIStartup (see page 169) before calling thisfunction in the UI API.The system information text contains detailed information about theQuickAddress library, how it is configured, and the resources that it has takenfrom the operating system. The text is split over several lines and so has to beread one line at a time. A buffer size of 80 bytes will be sufficient to guaranteethat no lines are truncated.176 • User Interface API Function Reference QuickAddress Pro API

When the first line is read, the library generates an internal copy of the systeminformation text. It is important that this copy is reset once all the lines havebeen read otherwise the allocated memory will not be freed. This is done bycalling this function with the first parameter, viLineNo as -1 i.e. QASystemInfo(-1, NULL, 0).Below is a C example that prints out QASystemInfo text:void PrintSystemInfo(VOIDARG){char sBuffer[80];int iLineNo;/* read each line in turn */for (iLineNo = 0;QASystemInfo(iLineNo, sBuffer,sizeof(sBuffer))== 0;iLineNo++){puts(sBuffer);}/* reset in order to free memory */QASystemInfo(-1, NULL, 0);}If you run the above example, you get a result similar to this:Program:QAUPIEDCopyright:QAS LtdRelease: 4.00(16)Platform:Windows 32-bitLibraries: QAKRNXF 2.23(215)QAUFWXD 4.00(215)QACOMXD 1.01(156)QAHSGXD 3.00(98)QAGENXD 1.00(10)QAHSVXD 3.20(94)QALICXD 1.00(13)QuickAddress Pro API User Interface API Function Reference • 177

QAHCLXD 3.00(68)QACDIXD 4.00(335)QADC2XD 2.40(55)QADS2XD 2.00(16)QAWD2XD 2.40(74)QAUSGXD 4.00(114)QALL2XD 2.40(106)QAUTDXD 4.00(136)QAZLCXD 1.01(34)QAZLGXD 1.02(60)QAZLSXD 1.01(45)QATIGXD 4.00(119)QATIXXD 4.00(116)Config:Section:Licensed to:Serial No:Days:Users:ongle:Prog Dir:Home Dir:Data Dir:Temp Dir:Log File:Memory:Data:Blocks:Server-side INI file:Data ID:t:\pro\qaworld.iniQADefaultNo limitNo limitt:\prot:\prot:\proc:\winnt\tempt:\pro\Error.txt1127772 (allocs=41)730804 (free=314652)888 (free=1812)t:\pro\qawserve.iniAUS178 • User Interface API Function Reference QuickAddress Pro API

Country Name:Copyright:Version:Data Expiry:File path:AustraliaAustralia Post22 October 2003 (PAF v2004.0)57 daysQ:\pafdata\AUS.dtsData ID:DEUCountry Name:GermanyCopyright:Deutsche Post DirektVersion: 14 April 2003Data Expiry:192 daysFile path:Q:\pafdata\DEU.dtsData ID:DNKCountry Name:DenmarkCopyright:Postcode data supplied by Post DanmarkVersion: 10 March 2003Data Expiry:158 daysFile path:Q:\pafdata\DNK.dtsData ID:ESPCountry Name:SpainCopyright:ClaritasVersion: 08 September 2003Data Expiry:125 daysFile path:Q:\pafdata\esp.dtsData ID:FRACountry Name:FranceCopyright:LA POSTEVersion: 08 August 2003Data Expiry:309 daysFile path:Q:\pafdata\FRA.dtsData ID:Country Name:Copyright:GBRUnited KingdomThe Post OfficeQuickAddress Pro API User Interface API Function Reference • 179

Version: 10 July 2003Data Expiry:280 daysFile path:Q:\pafdata\GBR.dtsData ID:NLDCountry Name:The NetherlandsCustom Name:NetherlandsCopyright:PTT PostVersion: 02 September 2003Data Expiry:333 daysFile path:Q:\pafdata\NLD.dtsData ID:SGPCountry Name:SingaporeCopyright:Singapore PostVersion: 01 July 2003Data Expiry:271 daysFile path:Q:\pafdata\sgp.dtsData ID:USACountry Name:United States of AmericaCustom Name:United StatesCopyright:United States Postal ServiceVersion: 24 October 2003Data Expiry:124 daysFile path:Q:\pafdata\usa.dts180 • User Interface API Function Reference QuickAddress Pro API

API ConfigurationIf you are running Windows, you can also configure Pro using theConfiguration Editor. Refer to the Configuration Editor help for moreinformation.Configuring the APIBefore you can perform any searches with the Pro API, you need to specifywhere Pro will search for addresses, and the format in which output addressesare returned.Pro bases processing decisions on configuration (INI) files. INI files containmany default settings which govern the basic processing of Pro. There are twoconfiguration files supplied with Pro: qaworld.ini and qawserve.ini.The default configuration file is qawserve.ini. The configuration information isstored in layouts within this file. You can create multiple layouts within thisconfiguration file, to encapsulate several different processing options andaddress formats. In addition, the file qawserve.ini contains settings pertainingto the installed country databases.This file is automatically used when the API is initialised. You should notrename it, move it or attempt to call it with any of the API functions: when APIfunctions call an ini file, the qaworld.ini file is always passed, never theqawserve.ini file.In Client/Server mode, the qawserve.ini file will be held by the Server, and isnot required at the Client. Please see the Client/Server documentation forfurther information on editing this file.QuickAddress Pro API API Configuration • 181

Format of a Configuration FileA configuration file can contain several layouts, each comprising a set ofinstructions. To view a configuration file, such as the standard qawserve.inifile, use a plain text editor. Do not use a formatting editor such as MicrosoftWord because it will corrupt the configuration file with its own formattingcodes. Instead, use something like Notepad (under Windows) or vi (underUNIX).The layouts within the configuration file have their titles in square brackets:[layout name]In qawserve.ini, this layout will be included:[QADefault]QADefault is, as its name suggests, the default layout. You should not alteranything within this layout; to create alternative settings, copy QADefault intoa new layout and then edit the copy. Any settings that are not indicated insubsequent layouts are taken from QADefault.Within the qawserve.ini file, layout names define the beginning of each layout.Layout names must be enclosed within square brackets and left-justified. Alayout ends when a new layout name is declared. The final layout is terminatedby the end of the file.Each layout comprises a set of instructions in the form of keywordassignments, like this:keyword=value182 • API Configuration QuickAddress Pro API

A keyword is the name of a setting. It can consist of any combination of lettersand digits in uppercase or lowercase, and it must be followed immediately byan equals sign (=), which introduces the value assigned to the keyword. Thevalue can be an integer, a string, or a quoted string, depending on the type ofsetting. Note that there should be no space between the ‘=’ and value.You must not alter any keyword assignments in qawserve.ini apart from thosedocumented in this manual.Not all entries have to be keyword assignments. You can add comments byprefixing the comment with a semi-colon (;).The keyword assignments can come in any order. A typical keywordassignment looks like this:USAAddressLineCount=4This tells Pro API to create an output address consisting of four lines for theUSA database.LicensingIf you need to manually install your UNIX licence key, enter it in the qalicn.inifile.The primary API files qaupicd.a / libqaupicd.so and qaupicd.h are located inthe lib directory.The compatibility API files are in a subdirectory: qapwvcd.a / libqapwvcd.soand qapwvcd.h in the lib\compatibility api directory.Element CodesAddress elements are specified in the Pro API INI file using element codes.Element codes are specific to (and only meaningful for) a particular country. Alist of element codes for each country can be found in the relevant CountryInformation guide; for example, the street element code in the US is S11, andthe street name element code is S112.QuickAddress Pro API API Configuration • 183

It is not necessary to specify every element in order for them to be visiblewithin the returned and formatted address. All standard elements will bereturned in a suitable place between any elements which have been fixed.Configuration SettingsWhen setting up Pro API for the first time, it is recommended that you followthe steps listed below:1. Ensure that one (or more) country database has been copied to a knownlocation.2. Configure an output format for the API to return a matched address.(Optional).3. Specify whether error logging is enabled.The first step involves checking settings in qawserve.ini. The second requiresyou to specify keyword values in qawserve.ini, and the third step involvesspecifying keywords in qaworld.ini. Qaworld.ini is the client INI file andcontains settings for controlling Pro clients, including the name and location ofthe server.The server is only specified in qaworld.ini when you are using Pro Client /Server. Refer to your Client / Server manual for more information.Qawserve SettingsChecking Country Database InstallationThe file qawserve.ini is used to specify which country databases are availableto Pro, and where they are installed. To modify these settings, open the fileqawserve.ini in a plain text editor. For Windows, this file can be found in thesame directory as the library files; for UNIX, this file can be found in the appsdirectory.The configuration keyword used to configure country installations is‘InstalledCountries’, located in the default layout section [QADefault] of theqawserve.ini file.184 • API Configuration QuickAddress Pro API

+PUVCNNGF%QWPVTKGU]%QWPVT[KFGPVKHKGT_]%QWPVT[ PCOG_]&CVCFKTGEVQT[RCVJ_Default:Set with Configuration Editor or the Data Installation programPurpose:This keyword lists the installed country databases by identifier,associated country name, and location with base filename. Thesedatabases are the ones installed by the setup program or copied acrossfrom the supplied data CDs/tapes. If you wish to change or add to them,you should run the setup program again or copy them from the suppliedmedium.If you have more than one country database installed, the first databaseappears directly after the = sign, and each subsequent database appearson a new line preceded by a + sign.The keyword “AllInstalledCountries” also appears in the qawserve.inifile. This is used to work out which old databases can be deleted andshould have the same value as “InstalledCountries” if you are installingdata manually.Example:If you have installed the UK, Australia and Netherlands countrydatabases in C:\Program Files\QAS\Data, this setting would appear asfollows (note that the last part includes the directory and base filename):InstalledCountries=GBR,United Kingdom,C:\ProgramFiles\QAS\Data\gbr+AUS,Australia,C:\Program Files\QAS\Data\aus+NLD,Netherlands,C:\Program Files\QAS\Data\nldIf you need to move one or more of your country databases, you shouldupdate this setting accordingly.QuickAddress Pro API API Configuration • 185

Setting the Output Address FormatThese settings appear in the qawserve.ini file, which is the default server-sideconfiguration file.Each country database has its own default address format, which conforms tolocal standards. For example, the default American address contains the housenumber followed by the street name, town name, state and ZIP code. Thedefault German address, on the other hand, contains the street name followedby house number, postal code and town name. It is strongly recommended thatyou do not edit the default address format; if you wish to create a differentformat to fit your application, you should do so within a new configurationlayout.The settings in this section are all prefixed by [country identifier]. This isbecause it is possible to define address formats for more than one countrydatabase within a single configuration layout. Therefore, each of the settings inthis section must be directly prefixed with the identifier of the relevant countrydatabase, and an address format must be set up for each country database thatyou have installed. For example, the setting CapitaliseItem for the Australiadatabase would become AUSCapitaliseItem.=%QWPVT[+FGPVKHKGT?%QOOGPV]VGZVUVTKPI_Default:CDF for countryPurpose:This allows you to add a comment to a layout, which is displayed at thebottom of the Select Layout dialog. See “QA_GetLayout” on page 93.Example:GBRComment=CDF for the United Kingdom186 • API Configuration QuickAddress Pro API

=%QWPVT[+FGPVKHKGT?#FFTGUU.KPG%QWPV]KPVGIGT_Default:0Purpose:This defines the number of lines in the formatted output address. Theformat of each individual address line is specified with theAddressLineN setting (see below).The number of lines you specify should take into account any namesand DataPlus information that might be returned.Example:USAAddressLineCount=4This tells Pro API to produce formatted output addresses of four linesfor the USA.=%QWPVT[+FGPVKHKGT?#FFTGUU.KPG9YKFVJ GNGOGPVNKUV%QWPVT[+FGPVKHKGT?#FFTGUU.KPG9YKFVJ GNGOGPVNKUV%QWPVT[+FGPVKHKGT?#FFTGUU.KPG9YKFVJ GNGOGPVNKUVDefault:BlankPurpose:This specifies which address element is to appear on which line. Wsignifies that the number that follows it is the maximum width of theline in characters, and is a comma-separated list ofcountry-specific element codes. By specifying an element code, youforce Pro API to place that element on that line (if the element exists inthe matched address).See page 183 for further details of country-specific element codes.QuickAddress Pro API API Configuration • 187

DataPlus element names are formed from the DataPlus identifier,followed by ‘.’ and the item name. If the DataPlus set has no item name,the base name is used; for example, AUSMOS.Code or AUSCCD.You can allow Pro API to insert other suitable elements before, after orbetween fixed elements by using the format specifier “…”Example 1:NLDAddressLine1=W40,S11,…This instructs Pro API to give line 1 of a Netherlands output address amaximum width of 40 characters. The street name is fixed to the line,and any subsequent elements can also appear on the line if they fit there.Example 2:AUSAddressLine6=W40,AUSMOS.DescThis tells Pro API to give line 6 of a Australian output address amaximum width of 40 characters, and fix the description part of theMOSAIC DataPlus set to it.Certain DataPlus elements contain imputed information by default. Theproduct can be configured to return or suppress this information.An imputed field is one where data does not exist for all addresses. In thisscenario, the gaps in the data are filled in (imputed) using neighbouring data.Alternatively you can specify that you do not want the data to be imputed.For example:GBRWPT.PartyGBRWPT.Party.NotImputedStandard DataPlus item.If there is no available value in the rawdata for this DataPlus set for thispostcode, the element will be blank.188 • API Configuration QuickAddress Pro API

GBRWPT.Party.IsImputedThe value of this item is always Yes orNo.If this item has been imputed by QAS,the value is Yes.If this value has been taken straight fromthe raw data, then the value will be Noand there will be no available value forthis DataPlus set for this postcode.=%QWPVT[+FGPVKHKGT?%CRKVCNKUG+VGO]GNGOGPVNKUV_Default:BlankPurpose:This keyword defines which address elements should appear in uppercase in the formatted address. The value of the keyword is a list ofelement codes separated by spaces.See page 183 for further details of country-specific element codes.Example:CapitaliseItem=P12 X11means that the town/city and country name will be capitalised.QuickAddress Pro API API Configuration • 189

=%QWPVT[+FGPVKHKGT?#DDTGXKCVG+VGO]GNGOGPVNKUV_Default:BlankPurpose:The value of this keyword is a list of element codes, which differbetween countries, separated by spaces. Depending on the country, thekeyword has one of two functions:• It defines which address elements should be abbreviated in theformatted address.Or:• For the USA, CAN and AUS, it prevents the abbreviation of certainelements that are abbreviated by default for some countries.See page 183 for further details of country-specific element codes.Example:AUSAbbreviateItem=S11means that the Australian street name will be abbreviated.=%QWPVT[+FGPVKHKGT?5GRCTCVG'NGOGPVU]DQQNGCP_Default:YESPurpose:This keyword specifies whether or not address elements on a single lineare separated by commas. Set this keyword to NO if you do not want tocomma-separate address elements.Example:GBRSeparateElements=YESmeans that a UK street and locality on the same line would look likethis:Chester Road, Warrington190 • API Configuration QuickAddress Pro API

If the keyword was set to NO, it would look like this:Chester Road Warrington=%QWPVT[+FGPVKHKGT?6GTOKPCVG.KPGU]DQQNGCP_Default:NOPurpose:This keyword defines whether or not certain address lines are endedwith a comma.Example:GBRTerminateLines=YESmeans that a five-line UK address could look like this:6 Cedar Grove,Bisley,WOKING,Surrey,GU24 9EFIf the keyword was set to NO, the commas would not appear.=%QWPVT[+FGPVKHKGT?(NCVVGP&KCETKVKEU]DQQNGCP_Default:NOPurpose:The Flatten Diacritics option allows you to replace all diacriticcharacters in a formatted address, such as accents and umlauts, withtheir non-diacritic equivalents. See “OemCharacterSet={text string}”on page 195 for information about removing diacritics from all APIcalls. For example, the Danish addressDegnsgårdvej 17840 HøjslevQuickAddress Pro API API Configuration • 191

would change toDegnsgardvej 17840 Hojslevif the Flatten Diacritics setting is on.Example:ESPFlattenDiacritics=YesThis means that all diacritic characters will be suppressed by Pro.%QPFKVKQPCN(QTOCV]VGZVUVTKPI_Default:D&BOrgPrefPurpose:This enables conditional formatting rules that allow the user to specify whetherto display the PAF or D&B organisation data, or a combination of both.The default is to look for the D&B data first, then to use the PAF data if theD&B organisation field is empty for the selected address.Example:GBBConditionalFormat=D&BOrgOnlyThis means that only D&B organisation names will be returned, andthat PAF organisation names will be suppressed if there is no D&Bequivalent for the relevant address.The other possible values are as follows:GBBConditionalFormat=PostOrgPrefThis means that the PAF organisation name takes priority, but that theD&B organisation name will be used if there is no PAF equivalent forthe relevant address.GBBConditionalFormat=PostOrgOnly192 • API Configuration QuickAddress Pro API

This means that only PAF organisation names will be returned, and thatD&B organisation names will be suppressed if there is no PAFequivalent for the relevant address.Qaworld SettingsError LoggingError logging can be used to help diagnose any problems preventing normaloperation of the Pro API. Problems such as failure to start up the API can besolved from observing the output to the log file.Logging can be activated by modifying configuration settings in the sectioncontained within the [QADefault] layout of the qaworld.ini file. These settingsinclude LogFile and LogErrors..QI(KNG]HKNGPCOG_Default:NonePurpose:LogFile enables you to specify a log file to which any errors that occurwhen you call API functions are written. These errors are only writtenif you set LogErrors=YES (see below) as well as specifying the nameof the file you want to write to with LogFile.It is recommended that you create a log file when integrating the API.Example:LogFile=error.logThis creates a log file called error.log in the same directory as theprogram files. You can also specify the full path of the file to writelogging to.QuickAddress Pro API API Configuration • 193

.QI'TTQTU]DQQNGCP_Default:NOPurpose:This keyword specifies whether or not error logging is enabled. IfLogErrors is set to TRUE, the LogFile keyword (see previous page)must contain a valid file path and name.Example:LogErrors=NOThis means that no errors are logged, even if a file name has beenspecified in LogFile.Search Settings(QTEG#EEGRV]EJCTCEVGT_Default:!Purpose:The Primary API uses this setting to define the character that the usercan type at the end of the premises/sub-premises information, to forcethe data to be accepted as a match. If you do not define a character, thefeature is disabled.Alternatively you can use the vsExtra parameter of QA_FormatResult(see page 76).Example:ForceAccept=$194 • API Configuration QuickAddress Pro API

1GO%JCTCEVGT5GV]VGZVUVTKPI_Default:ANSIPurpose:The Pro API includes support for character sets that contain nonstandardcharacters, such as diacritics (for example, accents andumlauts). The API also provides the ability to remove diacriticcharacters on address output.The API needs to know which (OEM) character set the callingapplication is using. The character set can be configured using thefollowing keywords in the qaworld.ini file:OemCharacterSet={sFamily}[NoDiacritics]sFamily is a string to indicate the generic character family. The defaultvalue is ANSI code page 1252 (Latin 1).The following character set families are supported by Pro. They are 8-bit character sets and can support diacritics and multiple code pages:FamilyANSIASCIIDescriptionThe character sets as defined by theAmerican National StandardsInstitute.As above but without diacritics.DOS DOS code page 850.Example:OemCharacterSet=ANSI NoDiacriticsQuickAddress Pro API API Configuration • 195

Informational Prompts0Q/CVEJGU/GUUCIG]VGZVUVTKPI_Default:Address not recognised (type ’!’ to accept). This character is set byForceAccept. See “ForceAccept={character}” on page 194.Purpose:The Primary API uses this setting to define the prompt to display whenreturning property level information that cannot be matched against anaddress. If this setting is left blank, then the feature is disabled.If you are using the UI API, see page 214 for details of theNoMatchesMessage setting.Example:NoMatchesMessage=Unrecognised address (key ‘$’to accept)196 • API Configuration QuickAddress Pro API

User InterfaceConfigurationConfiguration EditorThe Pro API is supplied with a Win32 Configuration Editor. This enables youto do the following:• create, edit and manage formatted address layouts for Pro;• install and manage Pro country databases;• set Pro configuration options;• control user access options in Pro.Although the Configuration Editor contains the ability to specify PastingOptions, these have no effect on the Pro API, and are therefore not documentedhere.You can find the Pro Configuration Editor in the Program Group which wascreated when you installed Pro API. When you run it, it will look similar to thescreen shown below.QuickAddress Pro API User Interface Configuration • 197

The Configuration Editor is split into several management functions, eachcontaining one or more panes. The main functions are as follows:• Layout ManagerCreate, edit and manage address layouts for use in Pro.• User Interface OptionsSpecify details of Pro’s user interface.• Database ManagerInstall or uninstall country databases or inspect their identificationinformation, including the number of days left until data expiry.To switch between functions, use either the View menu, or the buttons on thetoolbar:198 • User Interface Configuration QuickAddress Pro API

Layout ManagerUser Interface OptionsDatabase ManagerIn each function there is an outline control (like Windows Explorer) on the leftand a pane, or sub-view, area on the right. You can choose a particular pane fordisplay on the right by clicking on its name or icon on the left in the outline.Pro can be configured by editing settings in the various panes; for example, toalter a particular layout or to set some aspect of the Pro interface.When you make changes in the Configuration Editor, you should save yoursettings to make sure they are written to Pro’s configuration files.The Layout Manager has several different panes, while the other two views,Database Manager and User Interface Options, have only a single pane each.Layout ManagerThe Layout Manager view contains a list of all the installed country databases,similar to this:QuickAddress Pro API User Interface Configuration • 199

Double clicking on one of the layouts jumps directly to the Layout Propertiespane, which looks similar to this:This pane contains a summary of the currently selected address layout.The format of addresses found by Pro is contained in an address layout. Forexample, a layout could specify that the address will be on five lines, each ofwidth 50 characters, with the post town and postal/ZIP code always on thefourth and fifth lines respectively.Each country database is structured with a specific set of address elements.These differ from country to country, reflecting varying national standards andcultural conventions. For this reason, a single address layout can be used withonly one country database. This means that the current choice of countrydatabase in Pro determines which layouts are available for use.Each country database comes pre-configured with a standard address layoutthat follows appropriate national standards. The standard layout is described,with some explanatory notes, in the relevant Country Information guide.200 • User Interface Configuration QuickAddress Pro API

This standard layout is not visible in the Configuration Editor, is read-only andso cannot be modified. Every time you create a new layout, the ConfigurationEditor creates it as a copy of the standard layout for the current countrydatabase.You can revert to the standard layout by selecting Restore Defaults from theLayout menu.Standard and default layouts cannot be deleted or renamed.Creating and Naming LayoutsTo create a new layout, follow these steps:1. Open the Layout Manager and click on any existing layout under thecountry database where you want to create the new one.2. Go to the Layout menu and select the New option.Your new layout appears with an automatically generated name in aneditable text box. Edit the name and press Enter. You can include anyalphanumeric character, and the space and asterisk characters, in thenames of layouts. The asterisk has a special significance as a wildcardcharacter used in layout names designed for dynamically configuringPro.In the Layout Properties pane on the right, under Comment you canenter a short text description of the layout for reference purposes. Thelarger Summary textbox below shows a summary of all the currentsettings in the layout. Initially these correspond to those of the Defaultlayout (for the current country), copied to create the new layout.QuickAddress Pro API User Interface Configuration • 201

Copying, Deleting and Renaming LayoutsTo copy a layout, open the Layout Manager and select the layout you want tocopy. Now select the Copy option on the Layout menu. Configuration Editorimmediately creates a copy of the layout, with a default name highlighted readyfor you to change it. (See “Creating and Naming Layouts” on page 201.)You can only copy a layout within a particular address database, not from onedatabase to another.To delete a layout, select it in the Layout Manager and then choose the Deleteoption on the Layout menu.To rename a layout, click on it in the Layout Manager and select the Renameoption on the Layout menu. Edit the layout name directly in the textbox, andpress Enter when you have finished. Press Esc to cancel the edit withoutsaving your changes.You can also carry out any of these operations using the context menu – clickon the layout name with the secondary mouse button and select the menuoption you need.Editing an Address LayoutYou can specify exactly how you want your addresses to look in the AddressFormat section of the Configuration Editor. To do this, open the LayoutManager and select an address layout to work with.Setting Lines and ElementsYou define the number of lines in an address layout, and whether addresselements are fixed to those lines, on the Address Format pane. To view thispane, expand a layout by clicking on the + next to the layout name on the lefthand pane, and select ‘Address format’ from the list that appears.The Address Format pane contains the current settings for this layout.202 • User Interface Configuration QuickAddress Pro API

Default Element OrderWhen formatting an address according to the current layout, Pro tries to includeall address elements (except optional elements), whether or not they are fixedto a line. To decide where to place unfixed elements, Pro looks at the positionof fixed elements and "flows" the unfixed elements around them, using thedefault element order, a standard order defined for each country database.Regardless of how much information must be fitted before / after them, thefixed elements will always appear in the position in which they have beenfixed.Elements in the Fix Elements drop-down menu (which is accessed by clickingthe Fix element button at the right-hand side of the dialog) are listed in thedefault element order, except those in the Additional Elements sub-menu (theoptional elements). The default order is also shown in the country specificinformation supplied with the relevant database. If you place fixed elements inan order different from the default order, you may get unexpected results, suchas repetition or omission of address elements. The repetition of addresselements can be fixed on the Auto Formatting screen (see “Auto Formatting”on page 208).• To add another line, click on Insert line, and a new line is addedimmediately above the position of the cursor.QuickAddress Pro API User Interface Configuration • 203

• To delete a line, move the cursor to it and click on Delete line.• To change the width of a line, click on the line whose width you wantto change and click the Edit width button. Alternatively you candouble-click directly on the number you want to change. Edit the valuein the text box that appears on the line you want to change. Note thatyou cannot make a line wider than 120 characters.• You can fix an address element so that it always appears on the sameline in the formatted address. To ‘fix’ an element to a line, right-click inthe Elements section next to the line you want to change to display acontext menu. Click the Fix element option from the menu that appears,and choose the relevant element from the drop-down list of availableelements. Alternatively, click the Fix Element button and choose therelevant element from the drop-down list that appears.Once an element has been ‘fixed’, the Unfix element button will beactivated. To unfix an element, select it and press Unfix element.• When you have one or more elements fixed on a line, you can specifythat Pro should include following elements from the Default Order onthe same line, when the line width allows. If you want to allow elementsto follow in this way, fix the Allow elements to follow symbol [...] atthe end of the line. (The symbol is at the bottom of Fix Element menu).You can also use [...] at the beginning of a line, with similar effects. Prowill fit unfixed elements before the fixed element, if this is possiblegiven the line width.Conversely, any line containing one or more fixed elements and noAllow elements to follow symbol will contain only the fixed elements.If none of these occur in a particular address, the line will be blank inthe returned address.• You can also move an address element around the address layout byselecting it with the mouse, and dragging it to its new position.For example, you might want an Australian address to have three lines,with the street name in the second line, and the locality, state code andpostal code in the third. To set up this format, follow these steps:1. Move the cursor to Line 2 and right-click.A menu appears, containing editing options.2. Move to the Fix Element option. A menu appears, containing a list ofaddress elements.204 • User Interface Configuration QuickAddress Pro API

Elements marked with a * will only appear in the returned address if youspecifically fix them to a line. The element list that is displayed is specific to thecountry database that you have selected.Some elements have sub-menus.In this example, you can select three specific types of street elements.3. Click on ‘Street’, and then select ‘Whole Street’ from the new list thatappears.The menu disappears and ‘Street’ appears in Line 2 of the addresslayout.4. Use the cursor key to move down to line 3.5. Select the Delete line button.The current line 3, which contains no fixed elements, is deleted, and theline containing locality, state code and postal code becomes line 3.6. Click on the arrow buttons beneath Preview to see some exampleaddresses in the address format that you have specified.Format OptionsYou can change the punctuation, abbreviations and padding within a returnedaddress on the Format Options pane.QuickAddress Pro API User Interface Configuration • 205

You can specify whether parts of certain address elements should beabbreviated (where applicable) using the Abbreviate address elements listbox, similar to the one below:For example, with UK data if you want the words Street and Road to beabbreviated (to St and Rd respectively), check the Dependent Thoroughfareand Thoroughfare check boxes inside the list box.For each country database, Pro uses a set of national standard abbreviations forparts of address elements.The Punctuate end of address lines check box allows you to add punctuationto the end of each address line. The punctuation character and rules used aredetermined by the country database for which the current layout is defined.206 • User Interface Configuration QuickAddress Pro API

Using the Pad address lines check box on the Format Options pane, you canspecify that where a line in a formatted address has fewer characters than theline width you have chosen, it should be made up to the full width usingpadding spaces at the end. For example, Line 3 of your layout may be set to amaximum width of 25 characters. If you check the Pad Address Lines box, areturned Line 3 of 15 characters, such as “57 Macquarie St” will be padded upto 25 characters by the addition of 10 spaces at the right-hand end of the line.The Flatten Diacritics option allows you to replace all diacritic characters,such as accents and umlauts, with their non-diacritic equivalents. For example,the Danish addressDegnsgårdvej 17840 Højslevwould change toDegnsgaardvej 17840 Hoejslevif the Flatten Diacritics box is checked. This box is unchecked by default.The Separate address elements check box on the Format Options pane allowsyou to indicate that address elements on the same line should be separated bycommas. If you are using the United Kingdom with Names dataset, this checkbox becomes a drop-down box. This allows you to specify that certain nameaddress elements on the same line should be separated by punctuationcharacters. The default is that no punctuation separators are used.The Allow address editing box on the Format Options pane defines whetheryou can make additions or amendments to your selected address prior topasting. This is enabled by default. You should be aware, however, thatchanging any part of an address might make it postally invalid.The Allow partial addresses box is also enabled by default. This means thatthe user can select a partial address at any stage of the search process – forexample, a street name, town and postal/ZIP code without a premise name ornumber. Again, you should be aware that this could lead to incomplete detailsbeing returned. See the Help program supplied with the Pro User Interface forfurther details.QuickAddress Pro API User Interface Configuration • 207

The Invalidate ancillary if edited check box is enabled by default. Thisoption, if enabled, means that any editing of a full returned address willinvalidate premises-specific information, such as the DPID in Australia, theDelivery Point Suffix in the UK and DataPlus.The Form of organisation to return drop-down box is only available if youhave the United Kingdom with Businesses dataset installed. Business data isprovided in the standard Post Office PAF file, and also by Dun and Bradstreet.Additional Data Stores (ADS) add address data which is not in the PAF file,but which is in the D&B file; for example, extra street and premises data. Thisfield allows you to specify whether to display the PAF or D&B organisationdata, or a combination of both. The default is to look for the D&B data first,then to use the PAF data if the D&B organisation field is empty for the selectedaddress.Element CapitalisationYou can specify that one or more address elements should be capitalised by Prowhen it returns an address.To do this, go to the Element Capitalisation pane, and highlight the elementyou want to capitalise. Then click the Change case button. (Alternatively youcan double-click on any element whose case you want to change.)One or two address elements may be missing from the list – these are elementswhose case cannot be changed. Examples include Postal code in the UK andNetherlands, and Delivery Point ID in Australia.Auto FormattingIt is possible to prevent individual elements from automatically appearing inthe default element order. See “Default Element Order” on page 203.To do this, go to the Auto Formatting pane, and uncheck the element(s) youwant to exclude from the default element order.To undo this and include an element in the default element order, re-check theitem.You can use this option to exclude manually fixed elements from beingrepeated in any automatic lines.208 • User Interface Configuration QuickAddress Pro API

DataPlus FormattingIf you have purchased one or more DataPlus data sets, you can configure themto return information with addresses on the DataPlus Format pane. To view thispane, expand your address layout in the outline view, and click on ‘DataPlus’:The right hand pane looks similar to this:To add a line for DataPlus information, click the Insert line button. Theinserted line is 40 characters wide by default; to change this, click the Editwidth button and type a new value in the Width field.QuickAddress Pro API User Interface Configuration • 209

To fix a DataPlus item to a line, click in the Elements field and then click theAdd item button. Select the item you require from the drop-down list thatappears. Alternatively, right-click in the Elements section next to the line youwant to change, to display a context menu. Click the Add item option from thismenu and choose the relevant item from the drop-down list.The majority of DataPlus sets contain more than one item. For example, if youhave a data set containing latitude/longitude data, there will be at least twoitems in the list: one for the latitude, and one for the longitude. You have theoption of selecting either or both items. You can fix more than one item to asingle line, provided that the line is wide enough to contain the information.To remove an item from a line, highlight it and click Remove item. To deletea line, click the Delete line button – you can delete lines without first removingDataPlus items.Certain DataPlus sets can be configured to return imputed information.Imputation is only available in Advanced mode. For more information aboutimputation, see “Element Codes” on page 183.User Interface OptionsYou can configure the look and properties of the Pro User Interface from theUser Interface Options screen. These check boxes allow you to specify whethercertain options can be controlled from the Pro UI.You can choose to specify some of these options, such as being able to selectcountry databases, address layouts, or the searching mode, with thefunctionality flags in your call to QAProWV_UIStartup (see page 169).However, this interface provides a quick way to select options withoutrebuilding your program.Open the User Interface Options screen to see these options. To open it, clickthe relevant option on the left-hand pane:210 • User Interface Configuration QuickAddress Pro API

The User Interface Options screen will open:The main options are described below:Initial usersettingsSelect layoutCheck the relevant boxes if you want the menu bar,toolbar and partial address bar to be visible the firsttime that a user launches Pro. After the first time,Pro will always default to the settings that the userspecifies. You can override this in the Userpermissions area, so that Pro will always use theInitial user settings.Check this if you want the user to be able to changethe choice of address layout from within Pro.QuickAddress Pro API User Interface Configuration • 211

Select databaseSelect languageAllow Typedownsearching /Allow Single LinesearchingShow/hide menu /Show/hide toolbarShow/hide partialaddressCheck this if you want the user to be able to changethe country database selected in Pro.Check this box if you want the user to be able tochange display language.Check these for the searching modes you want to beavailable in Pro.Check these if you want the user to be free to showor hide the menu or toolbar as they choose.Check this box if you want the user to be able toshow or hide the partial address bar (see page 33) asthey choose.Database ManagerThe Database Manager view looks similar to this:212 • User Interface Configuration QuickAddress Pro API

If you are running the Client/Server version of Pro, this pane will be read-only.See the QuickAddress Pro Client/Server Guide for details of data installationin the Client/Server environment.The information box in the Database Manager function shows the name of eachinstalled country database, its release date, the number of days left until itsexpiry and its location.To activate a manually copied country database, go to the Database Managerand click on the Activate button. Highlight the database (.dts file) in the filebrowser. Details will then appear in the data window below:The data window shows the database file name, its release date and the numberof days left until its expiry.In exceptional circumstances, more than one item will be listed in the Contentsbox, and you should select the one you want to work with. For example, theGBR .dts file contains three database file names: GBR, GBB (United Kingdomwith Businesses) and GBN (United Kingdom with Names).Click the Activate button to enable the database.To deactivate a database, click on the country name on the Database Managerpane, and press Deactivate (or press the Delete key).Deactivating a database removes Pro's link to it – the database file itselfremains untouched in your file system.If you wish to completely delete a country database from your file system, clickon the Tidy Up button and follow the instructions. This button is only availableafter you have “deactivated” a database.Click DataPlus to view currently installed DataPlus sets for the selectedcountry database.QuickAddress Pro API User Interface Configuration • 213

Click Licences to open the Licence Manager dialog, which displays a list of allcurrently installed licence keys. From this dialog you can add, delete and viewlicence keys. See the Configuration Editor help for more information about theLicence Manager.Country Database InformationEach Pro country database contains all the address information for that country.Examples of the type of information contained include:• List of the address elements in the data• Default layout• Default element order• Abbreviations applied by Pro to address elements (see page 205)• Contractions recognized by Pro in search terms• Version/release information (see above)• Characters used for element separation and line end punctuation (seepage 205)Qaworld SettingsSee “Format of a Configuration File” on page 182 for information on thestructure and purpose of qaworld.ini.Prompts0Q/CVEJGU/GUUCIG]VGZVUVTKPI_Default:Address not recognised (press Ctrl+Enter to accept)Purpose:The UI API uses this setting to define the prompt to display whenreturning property level information that cannot be matched against anaddress.214 • User Interface Configuration QuickAddress Pro API

To suppress the Ctrl+Enter prompt, set this to blank. The prompt willdefault to "No matches".Example:NoMatchesMessage=Unrecognised address (key Ctrl+Enter to accept)QuickAddress Pro API User Interface Configuration • 215

Appendix AError Code ListingBelow is a full list of error codes and their descriptions. Call the systemfunction QAErrorMessage (see page 156) to retrieve the message associatedwith the returned error code, and QAErrorLevel (see page 157) to ascertainwhether the error is serious or a warning.Some of these error codes are documented in more detail later in this chapter.Code Message Explanation–1000 qaerr_FATAL Fatal error–1001 qaerr_NOMEMORY Out of memory–1002 qaerr_INITINSTANCE Invalid multi-threadinginstance–1005 qaerr_INITOOLARGE INI file too large–1006 qaerr_ININOEXTEND Cannot extend INI file–1009 qaerr_FILECHGDETECT Cannot detect file changes–1010 qaerr_FILEOPEN File not found–1011 qaerr_FILEEXIST File already exists–1012 qaerr_FILEREAD File read failure–1013 qaerr_FILEWRITE File write failure–1014 qaerr_FILEDELETE Could not delete file–1015 qaerr_FILERESV Reserved device–1016 qaerr_FILEACCESS File access deniedQuickAddress Pro API Appendix A: Error Code Listings• 217

–1017 qaerr_FILEVERSION Incorrect version of data file–1018 qaerr_FILEHANDLE Maximum number of filesopen–1019 qaerr_FILECREATE Could not create file–1020 qaerr_FILERENAME Could not rename file–1021 qaerr_FILEEXPIRED Data file has expired–1022 qaerr_FILENOTDEMO Can only accessdemonstration data–1023 qaerr_FILETIMEGET Failed to obtain filetimestamp–1024 qaerr_FILETIMESET Failed to modify filetimestamp–1025 qaerr_READFAIL Disk read failure–1026 qaerr_WRITEFAIL Disk write failure–1027 qaerr_BADDRIVE Invalid drive–1028 qaerr_BADDIR Invalid directory–1029 qaerr_DIRCREATE Could not create directory–1030 qaerr_BADOPTION Invalid command line option–1031 qaerr_BADINIFILE Could not locate INI file–1032 qaerr_BADLOGFILE Could not create log file–1033 qaerr_BADMEMORY Invalid memoryconfiguration–1034 qaerr_BADHOTKEY Invalid hot key–1035 qaerr_HOTKEYUSED Hot key already in use–1036 qaerr_BADRESOURCE Could not locate languagefile–1038 qaerr_BADTEMPDIR Bad temporary directory–1040 qaerr_NOTDEFINED Entry not defined–1041 qaerr_DUPLICATE Entry duplicated–1042 qaerr_BADACTION Invalid (list) action218 • Appendix A: Error Code Listings QuickAddress Pro API

–1050 qaerr_CCFAILURE Copy control failure–1051 qaerr_BADCODE Invalid copy control code–1052 qaerr_CCACCESS Copy control access denied–1053 qaerr_CCNODONGLE Dongle not configured–1054 qaerr_CCNOUNITS No units left on meter–1055 qaerr_CCNOMETER Meter not initialised–1056 qaerr_CCNOFEATURE Feature not supported–1057 qaerr_CCINVALID Softkey integrity failure–1060 qaerr_CCINSTALL Copy control not installed–1061 qaerr_CCEXPIRED Allowable time expired–1062 qaerr_CCDATETIME Date / time is invalid–1063 qaerr_CCUSERLIMIT Number of concurrent usersexceeded–1064 qaerr_CCACTIVATE Copy control installed butnot activated–1065 qaerr_CCBADDRIVE Invalid copy control drive–1066 qaerr_CCREGISTER Product must be registered–1070 qaerr_UNAUTHORISED Not authorised–1074 qaerr_NOLOCALEFILE Locale file not found–1075 qaerr_BADLOCALEFILE Invalid locale file–1076 qaerr_BADLOCALE Unknown language / country–1077 qaerr_BADCODEPAGE Unknown code page–1078 qaerr_RESOURCEFAIL Resource lookup failure–1080 qaerr_NOTHREAD Invalid thread handle–1081 qaerr_NOTLSMEMORY Out of thread-local-storage–1090 qaerr_NOTASK Could not create task–2300 qawdperr_BADFUNCTION Bad function code to library–2301 qawdperr_NOKERNEL Kernel must be preinitialisedQuickAddress Pro API Appendix A: Error Code Listings• 219

–2302 qawdperr_NOTFOUND One or more DataPlus itemsnot found–2303 qawdperr_BADLEADIN Internal or data error–2304 qawdperr_NOPLUGIN Plug-in not found for thisDataPlus set–2305 qawdperr_ISOPEN DataPlus file already openby this DataPlus handle–2306 qawdperr_BADENTRY Bad DataPlus entry detected(data error)–2307 qawdperr_NOTOPEN DataPlus set is not open–2308 qawdperr_NOCOUNTRY No country code specified–2309 qawdperr_PLUGINIT Problem initialising plug-in–2310 qawdperr_PLUGBADARG Bad argument to plug-in - noresult returned–2311 qawdperr_NEWFORMAT New file format detected–2400 qallderr_BADFUNCTION Bad function code–2401 qallderr_NOKERNEL Kernel is not initialised–2402 qallderr_BADHEADER Bad object header detected–2403 qallderr_NOOBJSIZE No object size (internalerror)–2404 qallderr_NOMOREOBJECTS No more objects (result ofattempted move)–2405 qallderr_BADDICT Bad dictionary entrydetected–2406 qallderr_BADDATA Bad compressed datadetected in rds–2407 qallderr_INTDPPROB More than one DataPlus itemreturned from lookup–2408 qallderr_MAXDPLITEMS Too many DataPlusreferences–2409 qallderr_NONAMES Can’t open Names DataPlusset220 • Appendix A: Error Code Listings QuickAddress Pro API

–2410 qallderr_BEYONDEOF Offset is beyond end of file–2411 qallderr_BADOBJCHAIN Invalid object chain fromthis object position–2412 qallderr_BADRANGETYPE Invalid range type detected–2413 qallderr_BADRANGESTART Bad range start valuedetected–2414 qallderr_ADSALREADYOPEN Requested ADS is alreadyopen–2415 qallderr_DELTADELTACOMP Error decompressing deltadeltaindex–2416 qallderr_NOADSFORDTS DTS reference not found indelta-delta index for thisADS–2417 qallderr_NOADSFORADS ADS reference invalid forthis ADS–2450 qacerr_BADFUNCTION Bad function code–2451 qacerr_BADCCLASS Comms class not found–2452 qacerr_NOLISFUNC Listen function not specifiedin listen request–2453 qacerr_CCNOTIMP Specified comms class is notyet implemented–2454 qacerr_ALRDYLIST Already listening on thespecified port–2455 qacerr_BADTFUNC Bad transport function called(internal error)–2456 qacerr_NOLISTENER Destination is not listening–2457 qacerr_BADHANDLE Invalid handle specified–2458 qacerr_CANCELLED Connection was cancelledremotely–2459 qacerr_NOBUFFER Attempted to take a size ofan uninitialised buffer–2460 qacerr_GETINSCHAR Get called but there areinsufficient charactersQuickAddress Pro API Appendix A: Error Code Listings• 221

–2461 qacerr_NOKERNEL Kernel is not initialised–2462 qacerr_NOTXN Can’t call send or receiveunless a txn is in progress–2463 qacerr_NOTXNNUM A transaction must have anon-zero transaction number–2464 qacerr_TERMINATED Talk was cancelled in thetransaction callback–2465 qacerr_NOREGFUNCTION No registered function wasfound for this transactionnumber–2466 qacerr_NOTXNMESSAGE Receive called but nomessage waiting–2467 qacerr_NOSERVERMEMORY No server memory duringtransaction processing–2468 qacerr_ATMAXBUFFER Maximum transaction buffersize reached–2469 qacerr_NOTLISTENHAND Comms handle specified isnot a listen handle!–2470 qacerr_SERVERFULL Maximum server connectioncount exceeded–2471 qacerr_DELETESELF Can't delete own connection–2472 qacerr_TIMEDOUT A connection's transactionhas timed out–2473 qacerr_SCANLOCK Scan already in progress onanother instance–2474 qacerr_VSNNOTSUPPORTED This version not supported atserver–2507 TCPIP_CONNECTFAIL The connect attempt failed–2508 TCPIP_TRANSTHREADFAIL Transmission thread failure–2511 TCPIP_INSTANCENOTFOUND Using invalid connectioninstance–2514 TCPIP_TRANSTHREADFULL Transmission threadmessage queue full222 • Appendix A: Error Code Listings QuickAddress Pro API

–2517 TCPIP_LISTENTHREADNOTINIT The expected listen threadwas not found–2519 TCPIP_INVALIDMSGTYPE Received invalid messagetype–2520 TCPIP_MSGCORRUPTED Received corrupted message–2521 TCPIP_MSGQUEUEFULL Outgoing message queue full–2524 TCPIP_GETMOREDATA Retrieving more data–2526 TCPIP_CANCELLED Connection cancelledremotely–2549 TCPIP_LISTENSTRUCT Failed to create listen data oradministrator–2900 qadcperr_BADFUNCTION Bad function code–2901 qadcperr_NOKERNEL Kernel is not initialised–2902 qadcperr_NOREGFUNCTION Function number notrecognised by server glue–2903 qadcperr_CANTCREATEINSTANCE Can't create server instance–2904 qadcperr_REINITIALISE No initialisation instancefound for this client–2905 qadcperr_BADHANDLE Bad client dataplus handlespecified–2906 qadcperr_SERVERPROBLEM Error at server–2907 qadcperr_INVALIDHANDLE Dataplus handle invalid–2908 qadcperr_BADCODE Bad format for dataplus setcode–2909 qadcperr_SETNOTOPEN Dataplus set is not open–2910 qadcperr_CLIENTPLUGINERR Error at client plugin–3400 qaerr_INVALIDCOUNTRYINDEX Invalid index intoUIGetCountry–3401 qaerr_INVALIDLAYOUTINDEX Invalid index intoUIGetLayout–3402 qaerr_UNKNOWNLAYOUTNAME Unknown layout name inUISetActiveLayoutQuickAddress Pro API Appendix A: Error Code Listings• 223

–3403 qaerr_UNKNOWNCOUNTRYCODE UI Startup with unknownISO code–3404 qaerr_NOSEARCHENGINESAVAILABLE Fatal case of the UFreporting no enginesavailable–3405 qaerr_CANTCHANGEDATABASE The more common invalid/unknown ISO code error–3406 qaerr_UIAPIALREADYSTARTED Multiple calls to UIStartup–3407 qaerr_UIAPINOTSTARTED UIStartup not called–3408 qaerr_UIBADSEARCHSTRING No longer used–3409 qaerr_UIBADCDFFORMAT No longer used–3411 qaerr_INVALIDLINEINDEX Invalid index intoUIGetLayoutLineElements–3412 qaerr_NOSELECTEDLAYOUT No layout in use during calltoUIGetLayoutLineElements–3413 qaerr_NOLIVESERVER Fatal comms error–3414 qaerr_BADCONFIGFLAGS Bad combination of configflags–3415 qaerr_CANTCHANGEENGINE Failed to change searchengine–3416 qaerr_NOUFACTIVE Internal error–3417 qaerr_UFINVALIDSTATE Internal sequence error–3418 qaerr_UILICENSINGERROR Licensing failure hasoccurred with one or moredata sets–3450 qaerr_BADFUNCTION Bad function number–3451 qaerr_NOKERNEL No kernel initialised atlibrary call–3452 qaerr_NOTPRESENT Shared entity not present–3600 qaerr_INITFAILURE QuickAddress TCP/IPfailure224 • Appendix A: Error Code Listings QuickAddress Pro API

–3601 qaerr_CLEANUPFAIL Sockets failed to clean upproperly–3602 qaerr_ACCEPTFAIL Error accepting remoteconnection–3603 qaerr_SOCKETBIND Failed to bind socket–3604 qaerr_LISTENFAIL Failed to initialise the listen–3605 qaerr_TALKFAIL Failed to initialise the talk–3606 qaerr_SOCKETFAIL Failed to create socket–3607 qaerr_CONNECTFAIL (TCP/IP talk socket) failedto connect to target–3608 qaerr_ADDRESSERROR Error looking up remotehostname or address–3609 qaerr_SENDERROR Error sending data–3610 qaerr_RECVERROR Error receiving data–3611 qaerr_SELECTERROR Error during processing ofsocket select for pendingdata–3612 qaerr_TOOLARGE Message is too large to betransmitted by protocol–3613 qaerr_PORTINUSE Specified port numberalready in use / Non-reusable–3614 qaerr_CONNECTREFUSED Could not connect to remotehost–3615 qaerr_CONNECTIONCLOSED Connection has been lost–3616 qaerr_SOCKOPTERROR Error setting socket option–3617 qaerr_WAITTIMEDOUT Wait timed out–3618 qaerr_HOSTNOTFOUND Host not found–3622 qaerr_WOULDBLOCK Socket would block–3623 qaerr_UNEXPECTED Unhandled error: pleaseinform QAS TechnicalSupportQuickAddress Pro API Appendix A: Error Code Listings• 225

–3625 qaerr_WSAEINVAL Invalid function or argumentfor socket–3627 qaerr_NOSOCKETS (The listen thread has) nosockets attached–3701 qaerr_CDFSYNTAX Invalid CDF syntax–3702 qaerr_BADCDFORDER Inaccurate item order inCDF–3703 qaerr_BADCDFITEM Item in CDF is invalid–3704 qaerr_INVALIDADDRESSEXAMPLE Invalid address example–3705 qaerr_INVALIDCDFOBJECT Invalid CDF object–3706 qaerr_INVALIDABBREV Invalid abbreviation–3708 qaerr_NOSUCHVARIATION CDF does not have thismany variations–3709 qaerr_OBJECTDEFINITION Objects incorrectly defined–3710 qaerr_UNKNOWNOFFSET Offset supplied was out ofrange–3711 qaerr_INVPARSEERR Push invalid parse has failed–3801 qaerr_FORMATSYNTAX Incorrect formatting syntax–3802 qaerr_TOOMANYADDRLINES Too many address linesrequested–3803 qaerr_INVALIDADDRESSLINE Address line out of range–3804 qaerr_NOFORMATSPEC No format spec in INI file–3805 qaerr_FORMATOVERFLOW Format(s) have overflowed–3806 qaerr_FORMATTRUNCATED Format(s) are truncated–3807 qaerr_BADCDFVERSION CDF version incompatiblewith format–3808 qaerr_UNKNOWNDPITEM Incorrect DataPlus itemname–3809 qaerr_DPFAILURE One or more DataPlus setsfailed to open–3810 qaerr_PREMISENEEDED Enter premise details226 • Appendix A: Error Code Listings QuickAddress Pro API

–3811 qaerr_NEEDRANGEOFFSET You need to enter numberdetails within a range–4300 qaerr_UFHANDLING Engine would like UF totake over–4301 qaerr_UFNOTHANDLING UF would like engine tohandle again–4302 qaerr_NOUFGLUEINSTANCE Glue not initialised–4303 qaerr_UFNOHK Housekeeping unavailable–4304 qaerr_UFNOFUNC Requested functionunavailable–4306 qaerr_UFCANTSTEP Can't step in–4307 qaerr_UFITEMRANGE Chosen picklist item out ofrange–4308 qaerr_UFLAYOUTRANGE Invalid layout handle given–4309 qaerr_NOUF NULL handle given–4310 qaerr_NOUFSEARCH No search in progress–4311 qaerr_ENGINEUNAVAILABLE Engine cannot be selected–4312 qaerr_UFCANCELLED An action has been cancelled–4313 qaerr_UFNOLAYOUT No layout matched thatsupplied–4314 qaerr_INEXACTUNAVAILABLE Inexact matches go beyondthreshold–4315 qaerr_NODATAAVAILABLE Data unavailable at this level–4316 qaerr_MOREINEXACT Data unavailable at this level–4317 qaerr_CANTSTEPIN Can’t step in–4318 qaerr_CANTSTEPOUT Can’t step out–4319 qaerr_BADOPTIONS Options value(s) wrong–4320 qaerr_NOENGINESUPPORT Underlying engine doesn'tprovide this function–4321 qaerr_BADSEQUENCE Functions called out ofsequenceQuickAddress Pro API Appendix A: Error Code Listings• 227

–4322 qaerr_MONIKER_BADVERSION UF does not recognise thismoniker's version number–4323 qaerr_MONIKER_BADMESSAGE UF does not recognise thismoniker's message number–4324 qaerr_MONIKER_WRONGENGINE Current UF instance is notusing this moniker's engine–4325 qaerr_MONIKER_WRONGCOUNTRY Current UF instance is notusing this moniker's country–4326 qaerr_MONIKER_WRONGDATAVERSION Current UF instance is notusing this moniker's dataversion–4327 qaerr_MONIKER_BADOFFSET This moniker has a zerooffset–4328 qaerr_BADCOUNTRYBASEPATH The option for the countrybasepath is bad–4329 qaerr_BADPROMPTSETINDEX The prompt set parameterwas invalid (not 0..2)–4330 qaerr_MONIKER_BADFORMAT UF does not recognise thismoniker's format–4331 qaerr_MONIKER_BADEXAMPLE The example number in thismoniker is out of range–4501 qaerr_TOOMANYINSTANCES Maximum number of openhandles have been created–4503 qaerr_MAXRESOURCES Maximum resource limitreached for resource store–4551 qaerr_OPENFAILURE Failed to create an APIinstance–4552 qaerr_APIHANDLE Instance handle invalid–4553 qaerr_OUTOFSEQUENCE Function called out ofsequence–4554 qaerr_INSTANCEBUSY Instance handle alreadybeing used–4556 qaerr_BADINDEX Index not within valid range228 • Appendix A: Error Code Listings QuickAddress Pro API

–4557 qaerr_BADVALUE A value passed was not valid–4558 qaerr_BADPARAM Invalid parameter passed toAPI–4559 qaerr_PARAMTRUNCATED API output truncated–4560 qaerr_NOENGINE Search engine is unavailablefor this dataset–4561 qaerr_BADLAYOUT The active layout is invalid–4562 qaerr_BADSTEP Step-in/Step-out not allowedon item–4570 qaerr_DATASETNOTAVAILABLE Data set cannot be used–4571 qaerr_LICENSINGFAILURE Licensing failure hasoccurred with one or moredata sets–4580 qaerr_SERVERCONNLOST Lost connection to theserver. Transaction timed outor server error–4581 qaerr_SERVERFULL The maximum number ofserver connections has beenreached–8300 qaerr_CTDIFUNC Unknown client function–8301 qaerr_CTDINOKERNEL No kernel instance on client–8304 qaerr_CTDIBOTTOM Item is not steppable–8305 qaerr_CTDISERVERERR Typedown server error(reported by client)–8400 qaerr_NOTDGLUEINSTANCE No Typedown glue instance–8401 qaerr_TDIFUNC Unknown server function–8402 qaerr_TDINOKERNEL No kernel instance on server–8403 qaerr_TDINOMATCH No match–8404 qaerr_TDIINDEXERROR Error in typedown index–8405 qaerr_THRESHOLDTOOLLOW Threshold was belowminimumQuickAddress Pro API Appendix A: Error Code Listings• 229

–8406 qaerr_TDINOHK Housekeeping is notinitialised–8407 qaerr_TDINONAMES Names cannot be opened–8408 qaerr_TDCANCELLED Typedown search wascancelled–8409 qaerr_TDDISCONNECT Typedown search wasdisconnected–8410 qaerr_TDSSWOPFAIL Typedown swap failed–8411 qaerr_NORESULTS Results unexpectedly notpresent–8412 qaerr_EMPTYBITMAP Bitmap was empty–8413 qaerr_TOOMUCHDATA Comms exceeded–8500 qaerr_HOUSEFUNC Bad function code–8501 qaerr_HOUSENOKERNEL Kernel is not initialised–8502 qaerr_REMOTEINLOCK Remote INI file is locked–8650 qaerr_ZLCFUNC Function unavailable–8651 qaerr_ZLCNOKERNEL Kernel not initialised–8652 qaerr_ZLCDISTANCE Maximum search rangecannot be less than minimum–8653 qaerr_ZLCBADTERM Search term must contain atleast one letter or number–8654 qaerr_ZLCNOMEMORY Client out of memory–8655 qaerr_ZLCTOOMANYMATCHES Too many matches found–8660 qaerr_ZLCABORT Search cancelled–8661 qaerr_ZLCTIMEOUT Search timed out–8750 qaerr_ZLSFUNC Unknown function–8751 qaerr_ZLSNOKERNEL Kernel not initialised–8752 qaerr_ZLSABORT Search aborted–8753 qaerr_ZLSTOOMANYMATCHES Too many matches found–8754 qaerr_ZLSTIMEOUT Search timed out230 • Appendix A: Error Code Listings QuickAddress Pro API

–11500 qaerr_LICFILENOTFOUND Licence File not found–11501 qaerr_INVALIDLICENCEKEY Invalid licence key–11502 qaerr_LICENCECONFLICT Conflicting licences found inlicence file–11510 qaerr_LICENCENOTFOUND Licence not found–11511 qaerr_LICENCEEXPIRED Licence expired–11512 qaerr_EVALUATIONEXPIRED Evaluation licence expired–11520 qaerr_BADINPUTPARAM Invalid input parameter–11521 qaerr_INVALIDDATE Invalid dateQuickAddress Pro API Appendix A: Error Code Listings• 231

General Errors: –1000 to –1001qaerr_FATALThis should not occur unless your application encounters anunexpected condition. The API will abort.qaerr_NOMEMORYYou will encounter this if Pro API begins a task and subsequentlydiscovers that there isn’t enough memory available to complete it. Forexample, memory may run out during a complicated search, or ifinsufficient system resources are available.If your application receives this error, a possible course of action is toproduce a message asking the user to close down one or moreapplications in an attempt to free enough memory for Pro API.File Errors: –1010 to –1021qaerr_FILEVERSIONThis occurs if the data files that comprise a country database havedifferent version numbers. Reinstall your data to ensure that you havethe latest versions of all files.qaerr_FILEEXPIREDThis occurs if a country database has expired. You can check how manydays are left before expiry with the function QA_LicensingDetail (seepage 98). If this error occurs, contact QAS for a data update.Startup Errors: –1030 to –1074qaerr_BADOPTIONThis indicates that an invalid command line parameter has been used.Enter the correct parameter to continue.qaerr_BADINIFILEThis means that Pro API cannot open the configuration file. Thishappens when the API fails to find the configuration file in any of thedesignated search paths. The default configuration file is qaworld.iniunless you specify otherwise in your call to QA_Open (see page 124).Pro looks for the configuration file in the following manner:232 • Appendix A: Error Code Listings QuickAddress Pro API

If a full path or filename was specified in your call to QA_Open, thenthe API looks along this path for the configuration file. Should it beunable to find the file, it returns the error qaerr_BADINIFILE.Otherwise the API looks for the configuration file in the currentdirectory and then, if necessary, it searches for it along the path. If ithas still not found a configuration file, then it returns this error.Failure to open the configuration file will prevent Pro from initialising.qaerr_BADLOGFILEIf you get this error, the API has been unable to create the log file thatyou specified. Check the LogFile setting in the configuration file toensure that the path and filename are valid.qaerr_BADRESOURCEThe API cannot locate the language resource files, or the languageresource files are corrupt. Check that they are in the correct location andthat they are the correct version for your application. A missingconfiguration file may also cause this error to be returned. If the INI fileis available, ensure that it is in the correct location, and that theLanguage setting is a correct value for this version of the API.qaerr_BADDATADIRThis appears when an invalid data directory has been specified. Youwill encounter this error if the keyword InstalledCountries includes adirectory which does not exist or does not contain a country database. Ifyour application receives this error, ensure that all directory and filenames for the configuration setting InstalledCountries, located inqawserve.ini, (see page 184) are correct.qaerr_NOLOCALE FILEThis appears if you attempt to start Pro without the localisation fileqalcl.dat in the program directory. Locate this file on your computer, orcopy the file across from the CD.QuickAddress Pro API Appendix A: Error Code Listings• 233

Pro UI API Errors: –3400 to –3412qaerr_INVALIDCOUNTRYINDEXThis error occurs if the viIndex parameter in a call toQAProWV_UIGetCountry (see page 150) is out of range. Ensure thatthe index number is valid, remembering that all indexes in the API arezero-based (i.e. the first country in a list should be retrieved by settingviIndex to 0, the second by setting it to 1, etc.).qaerr_INVALIDLAYOUTINDEXThis error occurs if the viIndex parameter in a call toQAProWV_UIGetLayout (see page 153) is out of range. Ensure thatthe index number is valid, remembering that all indexes in the API arezero-based (i.e. the first layout in a list should be retrieved by settingviIndex to 0, the second by setting it to 1, etc.).qaerr_UNKNOWNLAYOUTNAMEThe layout name specified in a call to QAProWV_UISetActiveLayout(see page 165) is not available in the current configuration file. You cancheck which layouts are available with the functionQAProWV_UIGetLayout (page 153).qaerr_CANTCHANGEDATABASEThe country identifier specified in a call toQAProWV_UISetActiveCountry (see page 163) is not valid, eitherbecause it does not exist or the relevant country database is notavailable. Ensure that you have installed the database that you want, andthat the country identifier is correct.qaerr_UIAPIALREADYSTARTEDThe API is already running. This error is returned fromQAProWV_UIStartup (see page 169) if it has been called previouslyand not yet shut down.qaerr_UIAPINOTSTARTEDThe API has not been started. Call QAProWV_UIStartup (seepage 169) to start the API before calling any other functions.234 • Appendix A: Error Code Listings QuickAddress Pro API

qaerr_UIBADCDFFORMATThis error is returned from QAProWV_UIStartup (see page 169) ifnone of the country databases can be initialised properly, due to aninvalid file. Ensure that your country databaseshave been installed correctly, and that each file has the same date.qaerr_UINOCOUNTRIESNo valid country databases have been installed. Use the DatabaseManager in the Configuration Editor (see page 197) to install countrydatabases.qaerr_INVALIDLINEINDEXThis error is returned from QAProWV_UILayoutLineElements (seepage 158) if the viIndex parameter is out of range. Ensure that the indexnumber is valid, remembering that all indexes in the API are zero-based(i.e. the first line in a layout should be retrieved by setting viIndex to 0,the second by setting it to 1, etc.).qaerr_NOSELECTEDLAYOUTThis error is returned from QAProWV_UILayoutLineElements (seepage 158) if you have not selected a layout to use. You can select alayout with QAProWV_UISetActiveLayout (see page 165).qaerr_NOLIVESERVERCould not find a valid configuration (or active server in Client Serverinstallation). Can be returned during QAProWV_UIStartup (seepage 169) or immediately after any Client / Server breakdown.qaerr_BADCONFIGFLAGSA non-sensical combination of flags was specified (e.g. Deny change tosearch engine, and not specify an engine explicitly) Can be returnedduring QAProWV_UIStartup (see page 169), orQAProWV_UISetFlags (see page 167).qaerr_CANTCHANGEENGINEAn error possible when unable to change to a specified engine, or keepexisting search engine when changing country. Can be returned duringQAProWV_UIStartup (see page 169), QAProWV_UISetFlags (seepage 167), or QAProWV_UISetActiveCountry (see page 163).QuickAddress Pro API Appendix A: Error Code Listings• 235

CDF Errors: –3701 to –3809If you encounter an error starting with –37…, you should contact TechnicalSupport for further assistance.qaerr_FORMATSYNTAX,qaerr_TOOMANYADDRLINESqaerr_NOFORMATSPECThese errors all signify a problem with the address format specified inthe configuration file. Check that the configuration settingAddressLineN (see page 187) contains a suitable format for returningaddresses, and that the number in the setting AddressLineCount (seepage 187) is the same as the number of lines defined in AddressLineN.qaerr_INVALIDADDRESSLINEThis error means that you are trying to retrieve an address line which isout of range. This might occur if, for example, your address formatcontains five lines and you call QA_GetFormattedLine (see page 90)with the viLine parameter set to 5. The range for an address with fivelines would be 0 to 4.qaerr_FORMATOVERFLOWqaerr_FORMATTRUNCATEDIf you encounter either of these errors, the retrieved address does not fitinto the address format you have specified in the configuration file. Forexample, the returned address might be seven lines long whereas youhave configured a five-line format, or one line might have 45 charactersand cannot fit onto a line configured as 40 characters wide.If you get several addresses that are truncated in this manner, youshould review the address format settings AddressLineCount andAddressLineN (see page 187) in the configuration file to ensure thatthey meet your needs.qaerr_UNKNOWNDPITEMThis error means that you are trying to retrieve a DataPlus item whichdoes not exist. Check the DataPlus lines in your AddressLineN setting(see page 187) are correct.236 • Appendix A: Error Code Listings QuickAddress Pro API

qaerr_DPFAILUREThis is a warning that one or more DataPlus items has not been returned.This usually occurs if there is no information relating to the address thatyou have selected, and does not affect the returned address or any otherDataPlus details.qaerr_BADSEQUENCEThis error is sent back when the programmer calls functions in thewrong order.QuickAddress Pro API Appendix A: Error Code Listings• 237

IndexNumerics4State Barcode • 27AAbbreviateItem keyword • 190Abbreviating address elements • 206Address edit screen • 40Address elements • 24abbreviating • 206capitalising • 208identifying • 25Address formatsElement codes • 183Address formatting • 202deleting lines • 204inserting lines • 203preview examples • 205Address layoutsand country databases • 200comment • 201copying • 202creating • 201default • 44deleting • 202description • 201editing • 202naming • 201renaming • 202selecting • 44summary • 201Address linescapitalising • 208AddressLineCount keyword • 187AddressLineN keyword • 187Alias matchmessage on status bar • 35picklist symbol • 37ANSI • 195API Instances • 59API test harness • 11, 15ASCII • 195Asterisk wildcard • 24asynchronous searching • 63BBarcodes • 27CCalling from languages other than C • 48CapitaliseItem keyword • 189Capitalising address elements • 208Comment keyword • 186Configuration EditorLayout Manager • 199Configuration files • 95, 157format • 182Keywords • 182Layouts • 182QAWSERVE.INI • 181, 182, 184,186, 193Configuration settingsSee Keywords •184Context menus • 202Conventions in this guide • 2QuickAddress Pro API Index • 239

Converting an error code to a text message• 174Copying address layouts • 202Counting country databases • 144Country databases • 5, 144Updates • 6Creating address layouts • 201Ctrl+Enter • 39CustomerCode Plain Barcode • 27DData expiry • 213Data files • 5Data Set FunctionsQA_GetActiveData • 67QA_GetData • 67QA_GetDataCount • 67QA_GetLicensingCount • 68QA_GetLicensingDetail • 68QA_SetActiveData • 68Data typesExample • 51Input parameters • 48NULL termination • 49Output parameters • 48Padding • 49Passing by value or reference • 50Return values • 47Data updates • 6Database manager • 212Databasesselecting • 43DataPlus • 41DataPlus information • 26Default address layout • 44Deletingaddress layouts • 202Deleting address lines • 204Delivery points • 26Diacritics • 195Display Error Function • 56Display Results Function • 56DOScode page 850 • 195EEdit button • 205Editing address layouts • 202setting lines and elements • 202Editing an address • 40Element codes • 183Elements have overflowed message • 34Error codes • 217CDF errors • 236File errors • 232General errors • 232Pro UI API Errors • 234Startup errors • 232Example of data types • 51Expandable itempicklist symbol • 36FFiles needed to run your integrated application• 7Finding the severity of an error • 175Flags Returned • 60FlattenDiacritics keyword • 191ForceAccept keyword • 194Format of a configuration file • 182Format options • 205Formatted addressSee address layouts •200Full addressespicklist symbol • 36FunctionsDisplay Error • 56Display Results • 56Return Address • 57Select Result • 57User Action • 56240 • Index QuickAddress Pro API

GGeneral FunctionsQA_Close • 65QA_ErrorMessage • 65QA_Open • 65QA_Shutdown • 65Getting Started • 6HHelp Program • 19Hidingtoolbar • 32Housekeeping functionsQAProWV_UICountryCount • 144QAProWV_UIGetActiveCountry •146QAProWV_UIGetActiveLayout •148QAProWV_UIGetCountry • 150QAProWV_UIGetFlags • 152QAProWV_UIGetLayout • 153QAProWV_UILayoutCount • 157QAProWV_UILayoutLineElements• 158QAProWV_UISetActiveCountry •163QAProWV_UISetActiveLayout •165QAProWV_UISetFlags • 167IIdentifying address elements • 25Informational prompts • 30, 33, 38Initialising the API • 169Input parameter data types • 48Inserting address lines • 203InstalledCountries keyword • 185Installing the Pro APIWindows • 4KKeywords • 182AbbreviateItem • 190AddressLineCount • 187AddressLineN • 187CapitaliseItem • 189Comment • 186FlattenDiacritics • 191ForceAccept • 194InstalledCountries • 185LogErrors • 194LogFile • 193SeparateElements • 190TerminateLines • 191LLanguagesnon-C languages and the API • 48Layout FunctionsQA_GetActiveLayout • 67QA_GetLayout • 67QA_GetLayoutCount • 67QA_SetActiveLayout • 67Layout Manager • 199Layouts • 95, 157, 158, 182QADefault • 182LogErrors keyword • 194LogFile keyword • 193MMenu bar • 30MenusPro • 30Search • 30View • 30NName entrypicklist symbol • 36Naming address layouts • 201QuickAddress Pro API Index • 241

NoMatchesMessage • 196, 214NULL termination and data types • 49Number of matches • 34OOemCharacterSet • 195Opening an instance of the API • 124Output parameter data types • 48PPadding • 49Partial Address Bar • 33Passing by value or by reference • 50Pattern matching • 22Picklist symbolsalias match • 37expandable item • 36full address • 36name entry • 36Picklists • 35displayed postcodes • 39order of items • 39selecting items • 39single line results • 38typedown results • 37Postal codes in a picklist • 39Printing out QASystemInfo text • 177Pro APIData files • 5Data updates • 6Error codes • 217Getting started • 6Installation • 4Pseudocode example • 53Test harness • 11, 15with DataPlus information • 26Pro menu • 30Pro UI API Errors • 234Promptsinformational • 30, 33, 196NoMatchesMessage • 214Pseudocode • 53QQA_CancelSearch • 70QA_Close • 71QA_EndSearch • 72QA_ErrorMessage • 73QA_FormatExample • 74QA_FormatResult • 76QA_GenerateSystemInfo • 78QA_GetActiveData • 79QA_GetActiveLayout • 80QA_GetData • 81QA_GetDataCount • 83QA_GetEngine • 84QA_GetEngineOption • 85QA_GetExampleCount • 88QA_GetFormattedLine • 90QA_GetLayout • 93QA_GetLayoutCount • 95QA_GetLicensingCount • 96QA_GetLicensingDetail • 98QA_GetPrompt • 101QA_GetPromptStatus • 103QA_GetResult • 105QA_GetResultDetail • 109QA_GetSearchStateDetail • 117QA_GetSearchStatus • 114QA_GetSystemInfo • 122QA_Open • 124QA_Search • 126QA_SetActiveData • 128QA_SetActiveLayout • 129QA_SetEngine • 131QA_SetEngineOption • 133QA_Shutdown • 136QA_StepIn • 137QA_StepOut • 139QADefault • 182QAErrorLevel • 175QAErrorMessage • 174QASystemInfo • 176242 • Index QuickAddress Pro API

Qaworld Settings • 193Qawserve.ini • 181, 182, 184, 186, 193Question mark wildcard • 23RRenaming address layouts • 202Result FunctionsQA_FormatExample • 67QA_FormatResult • 66QA_GetExampleCount • 67QA_GetFormattedLine • 67QA_GetResult • 66QA_GetResultDetail • 66Results area • 33RetrievingDataPlus information • 26Return Address Function • 57Return value data types • 47Returned Flags • 60Returning an address • 40SSearch area • 32Search button • 32Search FunctionsQA_Cancel • 66QA_EndSearch • 66QA_GetEngine • 65QA_GetEngineOption • 65QA_GetPrompt • 65QA_GetPromptStatus • 66QA_GetSearchStatus • 66QA_GetSearchStatusDetail • 66QA_Search • 66QA_SetEngine • 65QA_SetEngineOption • 65QA_StepIn • 66Search menu • 30Search methodsselecting • 41Searching with ProRetrieving additional data • 26single line searching • 22Select Back for other close matches message• 35Select button • 32Select Result Function • 57Selectinga country database • 43a picklist item • 39a search method • 41an address layout • 44SeparateElements keyword • 190Setting Pro options • 41Shutting down the API • 168Single line search button • 41Single line searching • 19, 22identifying address elements • 25pattern matching • 22picklist of results • 38wildcards • 23with partial addresses • 24Status barAlias match • 35elements have overflowed • 34number of matches • 34search in progress • 34Select Back for close matches • 35Stop button • 34Stop button • 34System FunctionsQA_GenerateSystemInfo • 68QA_GetSystemInfo • 68QAErrorLevel • 175QAErrorMessage • 174QASystemInfo • 176TTerminateLines keyword • 191Test harness • 11, 15Running • 12, 16Single line search • 12ToolbarQuickAddress Pro API Index • 243

hiding • 32options • 31tooltips • 32Typedown searching • 19picklist of results • 37troubleshooting • 22UUnrecognised Addressesreturning • 39User Action Function • 56User interfacecomponents • 29menu bar • 30results area • 33Search area • 32User permissions • 210USPS POSTNET Barcode • 27VView menu • 30WWildcardsasterisk • 24overview • 23question mark • 23244 • Index QuickAddress Pro API