QuickAddress
Pro for the Web
User Guide
Disclaimer
E&OE. Information in this document is subject to change without notice. QAS
Limited reserves the right to revise and improve its products as it sees fit. This
document describes the state of this product at the time of its publication, and
may not reflect the product at all times in the future.
The use of this documentation is governed by the terms of a software licence
agreement made between QAS Limited and the Licensee. The liability of QAS
Limited in respect of the documentation and the licensed programs referred,
are set out in that software licence agreement. QAS Limited accepts no liability
whatsoever for any use of the documentation or the licensed programs by any
person other than a permitted user under the software licence agreement.
Copyright
All rights reserved. All copyright and other rights in this manual and the
licensed programs described in this manual are the property of QAS Limited,
save for copyright in data belonging to the Post Office, including the Postcode
Address File, Postzon and all extracts, derivatives and updates. No part of this
manual may be copied, reproduced, translated or reduced to any electronic
medium or machine readable form without the written consent of QAS
Limited.
© QAS Ltd 2002
QAS Ltd
George West House
2-3 Clapham Common North Side
LONDON
SW4 0QL
UNITED KINGDOM
Technical Support
Tel: +44 (0) 20 7498 7788
E-mail: [email protected]
Tel: +44 (0) 20 7498 7777
Fax: +44 (0) 20 7498 0303
QAS Website
www.qas.com
Update Codes
Tel:020 7819 5500
E-mail:[email protected]
Version 3.3, revision 1
Contents
Introduction ................................................................................................ 1
Where to Look in this Manual ......................................................... 3
Installing Pro for the Web ........................................................................... 7
System Requirements ...................................................................... 7
The Installation Program .................................................................. 7
Running the Server as an NT Service .................................. 8
Files Installed ................................................................................ 10
Server-side Files................................................................ 10
Data Files ......................................................................... 10
Client-side Files ................................................................ 11
ASP Sample Code............................................................. 12
Java Sample Code ............................................................ 12
Address Capture on the Web..................................................................... 15
Searching with Pro for the Web ................................................................ 17
Fuzzy Searching ............................................................................ 17
Wildcard Searching ....................................................................... 18
The Question Mark Wildcard ........................................... 18
The Asterisk Wildcard ...................................................... 19
Both Wildcards Combined ............................................... 19
Property Keyword Searching ......................................................... 20
Intelligent Postcode Parsing ........................................................... 20
Search Results ............................................................................... 22
The Pre-Payment Counter ......................................................................... 25
Setting Up the Counter .................................................................. 25
Monitoring the Counter ................................................................. 26
Topping Up the Counter ............................................................... 26
Data Updates and the Administration Utility ............................................ 27
Administration .............................................................................. 27
Performing Data Updates .............................................................. 28
ActiveX Function Reference ...................................................................... 29
Multithreading .............................................................................. 29
Pseudocode .................................................................................. 29
Function Listing ............................................................................. 30
Open................................................................................ 31
Close................................................................................ 33
Counter ............................................................................ 34
QuickAddress Pro for the Web
Contents • i
Search ..............................................................................
ResultsCount ....................................................................
Preview ............................................................................
AddressCount ...................................................................
Address ............................................................................
DataPlusCount..................................................................
DataPlus ...........................................................................
ErrorMessage ....................................................................
ErrorLevel .........................................................................
ExpiryNotify .....................................................................
35
37
38
39
40
41
42
43
44
45
ActiveX Sample Code................................................................................. 47
Integrating Pro into your own Website ...........................................47
In Process Sample Code.................................................... 47
Address Popup Sample Code ............................................ 48
How the ASP Sample code works ..................................................49
Java Function Reference ............................................................................ 51
Multithreading ...............................................................................51
Pseudocode ...................................................................................51
Function Listing .............................................................................52
Open ................................................................................ 54
Close ................................................................................ 56
GetCounter....................................................................... 57
Search .............................................................................. 58
GetResultCount ................................................................ 60
GetPreview....................................................................... 61
GetAddressCount ............................................................. 62
GetAddressLine ................................................................ 63
GetDataPlusCount ............................................................ 64
GetDataPlusLine............................................................... 65
ErrorMessage .................................................................... 66
ErrorLevel ......................................................................... 67
ExpiryNotify ..................................................................... 68
Java Sample Code ...................................................................................... 69
Configuration............................................................................................. 71
Format of a Configuration File .......................................................71
Server Configuration Settings .........................................................72
Client Configuration Settings .........................................................75
Configuration settings for address formatting..................... 75
General configuration settings .......................................... 80
Appendix A: Error Codes ........................................................................... 85
ii • Contents
QuickAddress Pro for the Web
Client API Errors ............................................................................ 85
Client/Server Communication Errors .............................................. 92
Appendix B: DataPlus Sets ...................................................................... 101
GIS – Grid Reference Data .......................................................... 101
Geodemographic Data ................................................................ 101
Government/Administration Data ................................................ 102
PAF Related Data ........................................................................ 102
Names Data ................................................................................ 103
Media Data ................................................................................. 103
Utility Management Data ............................................................ 103
Appendix C: Pro for the Web Test Utility................................................ 105
Index ....................................................................................................... 107
QuickAddress Pro for the Web
Contents • iii
INTRODUCTION
QuickAddress Pro for the Web enables you to provide address capture
functionality on your website. This guarantees that your customers always enter
an approved Royal Mail address, thus minimising the chance of undelivered
mail. It also ensures that each address is captured in a consistent format suitable
for your underlying database.
Customers need only enter their house number or building name and their
postcode to return their full address. Alternatively, if they do not know their
postcode, they can enter their street and town. Where there is more than one
matching address, a picklist containing all possible matches is displayed, from
which your customer can select an address.
As well as address details, Pro can return a wide variety of supplemental
information from DataPlus data sets. DataPlus information includes
Parliamentary constituencies, local Health Authorities, MOSAIC information
and grid references; a full list of data sets is available in Appendix B which starts
on page 101.
Pro can be integrated using any method you require. Sample code has been
supplied for two interfaces: JSP pages for the Java interface, and ASP pages for
the ActiveX interface.
Pro is a multi-component product. In the sample implementations, the ActiveX
or Java component communicates with the underlying Web interface. This
interface sends the search to the Pro Client DLL, which communicates with the
data files held on the Pro Server. The Pro Client then formats the search results
before returning them to the browser, and also keeps track of threading issues.
The diagram over the page shows how the various components of Pro fit
together.
The Client DLL and Server executable can reside on the same machine, or on
different ones.
QuickAddress Pro for the Web
Introduction • 1
Browser
JSP Pages
Sample code
has been
provided for
these pages
ASP Pages
ActiveX
Interface
Java Interface
Web Interface
QAPWBEA.DLL
Pro Client
(QAPUIEK.DLL)
Client side
TCP/IP
Network
Server side
QuickAddress Server
(QANSRVMN.EXE)
Data files
2 • Introduction
QuickAddress Pro for the Web
Pro is supplied with a secure payment mechanism, which can be used on a
‘pre-pay’ basis. The mechanism takes the form of a counter that is reduced by
one every time a customer makes a successful address look-up. When the
counter reaches zero, the address look-up functionality is disabled. It is highly
recommended that you incorporate a blank address entry template in your
integration, which will appear if the counter should run out.
Note that it is your responsibility to monitor the number of address lookups
remaining and to credit the secure payment mechanism when necessary.
When the counter is getting low or has run out, you can top it up by e-mailing
or calling QAS and quoting the update key that is generated by the software
(“The Pre-Payment Counter” on page 25).
If you have chosen to use an unmetered version of Pro, you have been
provided with a Product Registration password, which should be entered as
part of the installation process.
Where to Look in this Manual
This section outlines the main areas covered in this manual and provides a brief
description of each.
1.
Installation
Installation instructions start on page 7. Running the setup
program installs the QuickAddress databases, configuration
files, sample code and DLLs to the directory of your choice.
2.
Searching and Address Capture with Pro
The section which starts on page 17 describes the various
methods that can be used to search for addresses, and the type
of results that come back. Before that, on page 15, are some
guidelines for capturing addresses with Pro.
3.
Available Functions for Integration
It is recommended that you integrate the API in stages,
beginning with the open and close functions, then adding the
address searching functions, followed by the address retrieval
facilities. Any other functions can be added in the appropriate
places.
QuickAddress Pro for the Web
Introduction • 3
The list of ActiveX functions starts on page 29, and the Java
listing starts on page 51.
You should also make use of the system functions ErrorMessage
and ErrorLevel. These functions enable you to see the
description and severity of any errors that occur, and as such
should be called after any function that has returned an error. A
full list of error codes starts on page 85.
4.
Sample Code
Sample code is provided for integration into ASP pages using the
ActiveX interface, or JSP pages using a Java Interface, which you
can use as a basis for your own integration. Alternatively you
can integrate Pro directly, for example into Java or Visual Basic.
Details of the ASP Interface start on page 47, and details of the
Java code start on page 69.
5.
The Counter
The Pro counter is the secure mechanism which enables you to
support address searches on a ‘pre-pay’ basis. Details of how to
configure and update the counter start on page 71.
Note:
If you have purchased this product with an Annual Licence, you do not
need to read the chapter entitled “The Pre-Payment Counter”. Any
further references to this can also be ignored.
6.
Configuring Pro for the Web
Before running your integrated API, you need to ensure that Pro
has the following information:
•
•
•
the format of returned addresses;
the locations of data files;
the location and port number of the server component.
This information should be specified in the configuration files.
All QuickAddress applications make use of configuration files –
also known as ‘.INI’ files. The API functions include parameters
which specify the location of the configuration file in order to
initialise Pro successfully.
Unless otherwise specified, Pro looks for the default
configuration file QAPROWEB.INI (located in
4 • Introduction
QuickAddress Pro for the Web
WINNT\SYSTEM32). Details of how to edit the configuration file
start on page 71.
QuickAddress Pro for the Web
Introduction • 5
INSTALLING PRO FOR THE WEB
This section tells you how to install QuickAddress Pro, and lists the files that
are installed.
System Requirements
•
•
•
Windows NT4 or Windows 2000 running IIS4 or IIS5 (Internet
Information Server)
CD-ROM drive
A minimum of 160Mb of hard disk space for the data files
You must log in with administrator privileges to install Pro and start the server
as an NT Service.
The Installation Program
1.
Insert the QuickAddress Pro for the Web CD in your CD-ROM
drive.
2.
The CD should run automatically. If it doesn’t:
Select Run... from the Start button.
In the dialog box that pops up, type e:\setup (where e is
the drive letter for your CD-ROM drive) and press ENTER.
3.
Note:
After a short initialisation, the QuickAddress Pro for the Web
Installation dialog appears. Follow the on screen instructions,
and enter the Serial Number and Password when requested.
If you are installing an Evaluation copy of QuickAddress Pro, type
“Eval” (without quotes) in the Serial Number box, but leave the
password blank.
QuickAddress Pro for the Web
Installing Pro for the Web • 7
Running the Server as an NT Service
Once you have installed the QuickAddress Network Server, you must set it up
as a Windows NT ‘service’. By doing this, you enable the Server to start up as
soon as its host machine has initialised (rather than waiting for a user to log onto
the machine and then run the QuickAddress Server). Also, as an NT service the
QuickAddress Server will not need to be shut down each time a user logs out.
You must log in with administrator privileges to install your QuickAddress
product as an NT Service, and you must first install the Server using the setup
program.
1.
Select Start>Programs>QuickAddress Pro for the Web for
Windows NT.
2.
Click the "Install QuickAddress Service" option.
3.
Click the "Shortcut to Control Panel Services" option.
A list appears which details the services that are available on the
host machine.
4.
Find the "QuickAddress Network Server" entry and select it.
5.
Select the Startup... button.
6.
Select the “Automatic” startup type.
This step instructs the QuickAddress Server service to start as
soon as the machine is switched on.
7.
Select OK.
8.
Select the Start button.
If the Server does not Start
•
Ensure that the data files are in the directory pointed to by the
DataDir configuration setting in the QANSRV.INI configuration
file.
8 • Installing Pro for the Web
QuickAddress Pro for the Web
•
Ensure that the server has permission to access the directory
which holds the data files. This might not be the case, since
directories on NTFS volumes can have a variety of different
access permissions.
•
By default, the server is set up as a standard system account. If
this account does not have sufficient access privileges then you
must either create a new account for the server, or else change
the server’s login account to an existing user account which
does have suitable rights. To change the account, select the
Startup... button as described in the previous section, select the
This account radio button in the ‘Log on as’ area and then set
the required account name and password in the fields provided.
•
If a numeric error code is returned, this can be converted into a
QAS error code by prefixing it with a ‘-’. An explanation of the
cause of the error can be found in Appendix A, which starts on
page 85.
Stopping the Server
To stop the server:
1.
Follow steps 1, 3 and 4 on the previous page.
2.
Select the Stop button.
Removing the Server from the NT Services List
If you want to remove the Pro server from the NT service list:
1.
Stop the server as described above.
2.
Select Start>Programs>QuickAddress Pro for the Web for
Windows NT.
3.
Click on the “Remove QuickAddress Service” option.
QuickAddress Pro for the Web
Installing Pro for the Web • 9
If you wish to uninstall Pro, you must stop the server and remove it from the
services list first. Failure to remove it from the list means that any subsequent
installations of the server on the same machine will not work.
Files Installed
Server-side Files
The QuickAddress Server files are installed in your C:\WINNT\SYSTEM32
directory by default:
File
Description
qansrvmn.exe
QuickAddress Server
qansrv.ini
Server configuration file
Data Files
The data is installed in C:\QADDRESS\PAFDATA by default as part of the
Server installation.
File
Description
qastrt.all
PAF streets data file
qaprmx.dat
PAF premises file
qaindx.all
PAF index file
If you have purchased DataPlus data sets, you will have a number of additional
data files. Each data set is made up of two files:
•
a DAT file
•
an INF file.
You must have both files to retrieve data from a particular data set. You will
already have a number of DAT files on the distribution CD, many of which will
10 • Installing Pro for the Web
QuickAddress Pro for the Web
be for data sets you haven’t actually bought. On buying DataPlus you will be
supplied with INF files for the data sets you have purchased.
QAS gives DAT and INF files appropriate names, which you can change if you
want to, but which we recommend that you keep. The default name is created
by taking the data set name (such as WARD or PARL), prefixing 'QA' (e.g.
QAWARD or QAPARL), and adding the DAT or INF extensions.
For instance, if you have the NHSC data set, which lists District Health
Authorities, the two files that comprise the data set are these:
QANHSC.DAT
QANHSC.INF
As there is a uniform naming convention for data sets, you don't have to specify
DAT and INF files in the configuration file (see the DataPlusLines keyword on
page 80). You can simply identify the data set name (such as NHSC), and the
function will work out the DAT and INF file names.
Client-side Files
The Pro client-side files are installed in the C:\QADDRESS\PROWEB.330
directory by default. They are listed and described below.
File
Description
qapuiek.dll
Client API
qapwbea.dll
Pro DLL
ccsetn.exe
Counter maintenance utility
ccsetn.ini
Configuration file for the above utility
The following file is installed in the system directory:
File
Description
qaproweb.ini
Client configuration file
QuickAddress Pro for the Web
Installing Pro for the Web • 11
Note:
If you experience problems when using the Java interface, copy
qapwbea.dll to the system directory.
ASP Sample Code
Sample code is installed to the directory of your choice. The default directory
is C:\INETPUB\WWWROOT\QADDRESS.
The sample code directory contains the following:
File
Description
index.htm
header.gif
footer.gif
Sample code index page
ASP sample code
asp
form
Form implementation search samples
popup
Popup implementation search samples
XML
XML Sample code
The index page in the main directory enables you to access the samples in the
sub-directories.
Java Sample Code
The Java sample code is installed to the directory of your choice. The default
directory is C:\QADDRESS\PROWEB.330\JAVA.
The Java folder contains the following files:
File
Description
QAProWeb.jar
This file should be added to the
CLASSPATH to provide access to
the classes
12 • Installing Pro for the Web
QuickAddress Pro for the Web
File
Description
QAProWeb.war
Web application containing JSP
sample code for use with the
Tomcat webserver http://
jakarta.apache.org/
QAProWebTestHarn.java
Console based test harness
The files in this directory are not intended for use via the web.
QuickAddress Pro for the Web
Installing Pro for the Web • 13
Display
address entry
template
Counter
expired? Y
N
Open
Unsuccessful
Close
Successful
Close
Display
search dialog
Search
Multiple matches
Show
picklist
1 match
No match/error
Full address
in required
format
Close
14 • Installing Pro for the Web
QuickAddress Pro for the Web
ADDRESS CAPTURE ON THE WEB
Your customers need only enter their house name or number and postcode,
and Pro will return a full and accurate address in the format you require.
This is the preferred method of address entry, since it requires the smallest
number of keypresses. For customers who do not know their postcode, it is
recommended that you provide an alternative screen, requesting house
number or name, street, and town or county.
The whole process is shown in the flow diagram over the page.
First, the Open function is called. If there are no remaining clicks, a blank
manual entry dialog should be displayed. Otherwise, a search entry dialog
should be displayed.
Once a search has been submitted, there are three possible outcomes:
1.
More than one matching address is found. If this happens, you
should display a picklist of matches using the Preview function.
You should also call the Address function and store the fully
formatted version of each matching address in your Web pages.
Thus, when the customer selects the correct address from the
picklist, it can be returned without the need to call the Search
function a second time.
2.
A single matching address is found. This can be returned, fully
formatted, using the Address function.
3.
No matching address is found, or an error occurs. In this event,
the Close function must be called and the process restarted from
the call to the Open function.
In the event of the call to the Open function failing, you should provide a blank
address entry template as a fall-back mechanism.
QuickAddress Pro for the Web
Address Capture on the Web • 15
SEARCHING WITH PRO FOR THE WEB
The fastest method to search with Pro is with the house number or name, and
the postcode. In the majority of cases, this combination returns a single full
address. The postcode can be entered in upper or lower case, and spaces are
not required. For example, a search on the postcode SW4 0QL could be typed
in any of the following ways:
sw40ql
SW4 0ql
SW40QL
If you do not know the postcode, you can search on the elements of the address
that you do know, such as the street name and town.
Address elements should be entered in the natural order that you would expect
to see on an envelope, and separated by commas. For example, you could type
this:
77 Popes Grove, Twickenham
There are two facilities available to make searching more efficient. These are:
1.
Fuzzy searching
2.
Wildcard searching
These are described in the following sections.
Fuzzy Searching
Pro carries out fuzzy searches on address details that you type in. A fuzzy
search makes matches on the basis of how a word sounds. Some spelling
mistakes are automatically corrected as a result.
For instance, if you enter this address:
58 layland rd, se
which doesn’t exist, Pro returns the closest match it can find, which is:
QuickAddress Pro for the Web
Searching with Pro for the Web • 17
58 Leyland Road, SE
Consequently the mis-spelling of “Leyland” is not crucial.
Wildcard Searching
Note:
Wildcard searching is disabled by default. This is due to the large
amount of processing time Wildcard searching uses on a web server.
Therefore, Wildcard searching is only available if the configuration
setting AllowWildcardSearches is set to Yes.
QuickAddress Pro supports two wildcards, specific characters that can be
inserted in the search to signify one or more characters that you don’t know.
The two types of wildcard are:
•
•
the question mark wildcard
the asterisk wildcard
The Question Mark Wildcard
The question mark wildcard represents a single unknown character. It can only
be used within a postcode.
If you enter:
Pro retrieves:
tw119?j
A list of all streets with postcodes
TW11 9AJ, TW11 9BJ, TW11 9DJ
and so on.
?n72d?
A list of all streets with postcodes
AN7 2DA, BN7 2DA, CN7 2DA and
so on. Similarly, all streets for AN7
2DB, AN7 2DD, and so on.
33 back hill, cb7??a
The full address: “33 Back Hill, Ely,
CB7 4DA”.
When you search with a question mark wildcard, Pro produces a list of
addresses with matching postcodes.
18 • Searching with Pro for the Web
QuickAddress Pro for the Web
The Asterisk Wildcard
The asterisk wildcard represents any number of characters. It can be used in any
part of the address except the postcode.
If you enter:
Pro retrieves:
2 elgin*,sussex
All instances of 2 Elgin Road, 2 Elgin
Gardens, etc., in East or West Sussex.
lloyds*,ec1
All instances of Lloyds Bank Plc,
Lloyds Investment Managers, etc., in
London EC1 district.
king*,victoria*,london
Addresses such as King’s Fish Bar, 27
Pier Road, Victoria Docks and King
Charles Street, Victoria. This is an
example of a multiple wildcard
search.
33 back*,ely
The full address: “33 Back Hill, Ely,
CB7 4DA”.
Notice that none of these examples has the asterisk at the beginning or in the
middle of an address component. This is because Pro ignores anything that
comes after the asterisk (up to the next comma, if there is one). The exception
to this is the keyword search (see page 20).
Both Wildcards Combined
If you enter:
Pro retrieves:
33 back*, cb?4?a
The full address: “33 Back Hill, Ely,
CB7 4DA”.
oak*,threemile*,tr?6??
The full address: “Oak House,
Threemilestone, Truro, TR3 6GU”.
QuickAddress Pro for the Web
Searching with Pro for the Web • 19
Property Keyword Searching
You can search for an address based on one or more words you know to be in
that address. This type of search, known as a keyword search, is implemented
with the asterisk wildcard. The examples below illustrate how:
If you enter:
Pro retrieves:
*station, huddersfield
All occurrences of “Station” in
Huddersfield.
*bank, warwick
All banks in Warwick.
*hospital, sussex
All hospitals in Sussex.
*thorn, de43j?
The full address: “The Thorn Tree
Inn, Jackson Road, Matlock, DE4
3JQ”.
Keyword searches do not search through all the address elements. The ones
that they do search through are Organisation name and property name. This
makes the search more efficient because less searching is required.
Intelligent Postcode Parsing
One useful feature of Pro is its ability to spot some of the common typing
mistakes that can occur when entering a postcode search string. Because Pro
knows the underlying structure of the postcode it can, to an extent, replace an
incorrect character with the correct character. It does require the postcode area
to be valid however, and does not make corrections on the area segment of the
postcode.
For example, if you search on the postcode ‘SES 9QN’, Pro realises that the ‘S’
is incorrect and replaces it with ‘5’ which is a similar character in appearance.
It then searches on the postcode ‘SE5 9QN’.
The following rules define how Pro parses and corrects postcodes:
20 • Searching with Pro for the Web
QuickAddress Pro for the Web
Corrections when Pro expects a letter
Pro finds...
and corrects it to...
0
O
1
I
2
Z
5
S
6
G
8
B
Corrections when Pro expects a number
Pro finds...
and corrects it to...
O
0
o
0
I
1
i
1
L
1
l
1
Z
2
z
2
S
5
s
5
B
8
b
6
G
6
g
9
QuickAddress Pro for the Web
Searching with Pro for the Web • 21
Search Results
QuickAddress Pro returns possible matches for your address search in the
format of your choice. The sample code supplied uses a drop-down list. If there
is more than one match, you can scroll up and down the list to select the
address that you want.
For example, if you submit this search:
Pro returns this result:
In this case, the house number and postcode have produced only one match.
If, however, you entered just a postcode, as in this example:
22 • Searching with Pro for the Web
QuickAddress Pro for the Web
Pro brings back a complete address for every house within this postcode:
QuickAddress Pro for the Web
Searching with Pro for the Web • 23
THE PRE-PAYMENT COUNTER
Note:
If you have purchased this product with an Annual Licence, you do not
need to read this chapter. Any further references to this can also be
ignored.
The pre-payment counter supplied with Pro enables you to pay for address
searches on a 'per-click' basis. Each time a user performs a search, the value
of the counter is reduced by one. The counter takes the form of a secure data
file. By default, this file is held in the product registration directory,
QAPWBEA.REG, which is directly beneath the directory to which you installed
Pro. This directory is created the first time an Update Key is generated.
Do not modify, move, or copy this directory, or any of its contents, as this will
cause corruption. If the counter does become corrupted, contact QAS
Technical Support on 020 7498 7788. Note that you are liable for any losses
incurred as a result of tampering with the pre-payment counter.
Setting Up the Counter
QuickAddress Pro uses a counter to keep track of the number of address look
ups remaining. After installation, the counter will need to be initialised. To
generate an Update Key:
1.
Run the Counter Maintenance Utility (Ccsetn.exe). A shortcut is
included in the QuickAddress Pro for the Web program group.
This displays your Update Key.
2.
E-mail this Update Key to QAS at [email protected]. Please
include your company name, reference and your contact
details. Alternatively, call 020 7819 5500 with your Update
Key.
3.
QAS will supply you with an update code. This can either be
entered into the Counter Maintenance Utility or into the Pro
search engine using the System Prefix keyword.
The Administration Form supplied with the sample code
provides an example of code that can be integrated directly into
your application.
QuickAddress Pro for the Web
The Pre-Payment Counter • 25
Monitoring the Counter
Should the counter reach zero, all address look-up functionality is disabled. It
is, therefore, very important that you monitor the counter on a regular basis and
keep a record of the number of look-ups remaining. You can do this in one of
three ways:
1.
Run the Counter Maintenance Utility (Ccsetn.exe). A shortcut is
included in the QuickAddress Pro for the Web program group.
This displays the current counter value.
2.
Type the system prefix string into Pro's search dialog instead of
the usual postcode or address elements. For example, if the
system prefix string is 'xxx', entering 'xxx:' returns the counter
value. Details of how to define and use the system prefix string
are given on page 80.
3.
From the client, the Administration Form supplied with the
sample code referred to in “Setting Up the Counter” on page 25
provides an example of code that can be integrated directly into
your application.
Alternatively, you can use the Counter or GetCounter functions (pages 34 and
57 respectively) to implement your own administration process.
Topping Up the Counter
When the counter is running low, or has run out of clicks, you can top it up by
following the same procedure as outlined in “Setting Up the Counter” on
page 25.
Since 'clicks' are added to the existing counter value, you can top up the
counter at any time without losing the existing clicks.
26 • The Pre-Payment Counter
QuickAddress Pro for the Web
DATA UPDATES AND THE ADMINISTRATION
UTILITY
Addresses are continually changing: new ones come into being, old ones
disappear and postcodes are recoded by the Royal Mail. Because of this, it is
vital that the address data used by QuickAddress Pro is kept up to date.
QAS will supply you with quarterly data updates on CD. In order to update
your data without taking your web server offline, use the Pro Administration
Utility described below.
Administration
This administration utility regularly polls QuickAddress Pro to check its status.
Normally this will be ‘Active’, meaning that Pro is running and accepting
address searches.
To perform a data update, Quick Address Pro needs to be set to ‘Disabled’.
This prevents Pro from accepting any new address searches while the update is
performed. Instead, your customers will be shown a blank address entry
template as described in the section “Address Capture on the Web” on
page 15. Any current address searches will continue to be processed as
QuickAddress Pro for the Web
Data Updates and the Administration Utility • 27
normal. When the Disable button is clicked the status becomes ‘Disabled’ and
the Disable button changes to Activate.
Following a data update (see below), restart Pro by clicking on the Activate
button.
Pro Administration also shows a number of search counters. These are set to
zero when Pro Administration is first started and are updated each time
QuickAddress Pro is polled. There are four counters:
1.
Successful. The number of successful search requests which
have been made. (Note that this does not necessarily mean that
the search itself was successful; it includes searches that failed
to return a matching address.)
2.
Disabled. The number of search requests made while Pro is
disabled.
3.
Expired. The number of search requests made while the secure
payment counter has expired or has become corrupted.
4.
Failed. The number of search requests which have returned an
error.
Clicking the Reset button sets all counters to zero.
Performing Data Updates
To perform a data update, follow these steps:
1.
Disable QuickAddress Pro by using the Administration Utility as
described above.
2.
Stop the QuickAddress Network Server as described on page 9.
3.
Replace the old data files with the new ones. Detailed
instructions for doing this will be supplied with the update CD.
4.
Restart the QuickAddress Network Server as described on
page 8.
5.
Activate QuickAddress Pro by using the Administration Utility.
28 • Data Updates and the Administration Utility
QuickAddress Pro for the Web
ACTIVEX FUNCTION REFERENCE
This section lists the ActiveX methods available for use in ASP.
Multithreading
QuickAddress Pro supports multithreading, meaning that searches can be
performed at the same time on different threads.
For each thread, the Open function (see page 31) must be called to initialise the
search engine. After the search, a corresponding call to the Close function (see
page 33) must be made to end the search and clean up resources.
Only one search can be done between the open and close calls. Results can
only be retrieved in the same thread as the search which was done.
Pseudocode
Below is a pseudocode example of performing a single search with the Pro API
functions.
Open thread
Open
If successful then
Perform address search
Search
If search successful or postcode recoded then
Get number of address lines
Get number of results
AddressLines
ResultsCount
Loop through each result
Retrieve preview to display in picklist
Preview
Retrieve each address so that the relevant one
can be selected
Address
If DataPlus information available
Count DataPlus lines
DataPlusLines
Retrieve DataPlus details
DataPlus
End if
QuickAddress Pro for the Web
ActiveX Function Reference • 29
End loop
End if
End if
Close thread
Close
Select address from picklist.
Return to customer screen.
The open call will fail if the search engine cannot be initialised or if the counter
has reached zero. If the open call is successful, then the subsequent call to the
search function is guaranteed to succeed, even if another thread manages to
reduce the counter to 0 in the meantime.
Function Listing
The API functions can be split into three groups: those that open and close the
Pro search engine; those that search for address items; and those that retrieve
the address. For each function there is a brief explanation of what it does,
followed by its prototype, parameters, return value and further comments on
its functionality.
Open .................................................................... page 31
Close .................................................................... page 33
Counter................................................................. page 34
Search................................................................... page 35
ResultsCount......................................................... page 37
Preview................................................................. page 38
AddressCount ....................................................... page 39
Address ................................................................. page 40
DataPlusCount ...................................................... page 41
DataPlus ............................................................... page 42
Note:
VBA prototypes are used for these functions, due to the similarity
between VBA and the VBScript used for ASP.
30 • ActiveX Function Reference
QuickAddress Pro for the Web
Open
Opens the Pro database and reads configuration information.
Prototype
Function Open (ByVal sIniFile as String, ByVal sSection as
String) as Integer
Parameters
sIniFile
configuration file
sSection
configuration file section
Return Value
status code
0
= success
-ve
= QA Error Message
Most likely errors
-1031
-9298
-11200
-11203
-11204
Can't find configuration file
Couldn’t open TCP/IP connection
Search library failed to load
Counter maintenance only available
Searching disabled
Comments
When this function is called, it checks the name of the library and the threading
model to be used.
The sIniFile parameter specifies the configuration (.INI) file from which the API
is to obtain configuration information, such as the address format and search
QuickAddress Pro for the Web
ActiveX Function Reference • 31
options. If an empty string or null is passed, the default INI file is taken
(QAPROWEB.INI on most platforms).
The sSection parameter specifies the section of the INI file from which the API
gathers address formatting information. If an empty string is passed QAProWeb
is used.
There are various groups of errors that can be returned from this function. Error
-1031 signifies that Pro cannot locate the configuration file. Error -11203
signifies that only searches using the system prefix (see page 80) are available.
This will happen if the counter has run out or become corrupted – see
“Configuration” on page 71.
In the event of the counter being less than 0, it is recommended that you
provide a blank template to the user, so that they can enter their address
manually. The sample code supplied provides an example of this.
When you have finished capturing an address, call the Close function (see
page 33) even if the Open function failed. An error will be returned if Close has
not been called after a previous Open in the current thread.
32 • ActiveX Function Reference
QuickAddress Pro for the Web
Close
Closes the QuickAddress search engine on the current thread, and releases any
resources associated with it.
Prototype
Sub Close
Comments
Close must be called to clean up resources after every call to Open (see
page 31).
QuickAddress Pro for the Web
ActiveX Function Reference • 33
Counter
Returns the value of the counter.
Prototype
Function Counter() as Long
Return Value
status code
+ve
= number of clicks left on counter
-10 000
= counter corrupt or no clicks
available
Comments
This function returns the available number of clicks on the counter. If the
counter is corrupt, -10 000, will be returned. (For more information about the
counter, see page 25.)
The value of the counter can also be obtained by searching with the
SystemPrefix setting – see page 80 for further details.
34 • ActiveX Function Reference
QuickAddress Pro for the Web
Search
Executes an address search using the specified search string.
Prototype
Function Search (ByVal
ByVal
ByVal
ByVal
ByVal
sSearch1
sSearch2
sSearch3
sSearch4
sSearch5
as
as
as
as
as
String,
String,
String,
String,
String) as Integer
Parameters
sSearch<n>
address element forming part of the search
string
Return Value
status code
0
= success
-ve
= QA Error Message
Most likely errors
-9811
-9978
-9982
-10000
-11201
-11202
-11205
Postcode has been recoded
No match
Operation cancelled
Bad search expression
API not initialised
Function call out of phase
Incorrect or incomplete postcode
Comments
Each sSearch<n> parameter in this function represents a single address
element, which makes up part of the address search. A maximum of five
QuickAddress Pro for the Web
ActiveX Function Reference • 35
elements can be entered. These elements are then concatenated into a single
string before being passed to the underlying search engine. If an sSearch<n>
parameter is empty or null, it will be ignored in the search.
Question mark and asterisk wildcards can be used in the search if the
AllowWildcardSearches configuration keyword is enabled.
The SearchElementType<n> configuration setting can be used to constrain
the element passed in a sSearch<n> parameter. See page 81 for further
information on this setting. The search can also be limited by setting a timeout
period (see the SearchTimeout keyword and by specifying the maximum
number of postcodes to be returned (see MaxPostcodes on page 74).
A single picklist of results will be returned from the search, via the ResultsCount
and Preview functions (see page 37 and page 38 respectively). If only one
result is returned, there is no need to use the Preview function. The prepayment counter is decremented each time a successful search is performed.
Lastly, the Address function (see page 40) will return a full address formatted as
specified in the configuration file (see page 75).
Error -9811 occurs when a user searches using a postcode that has been
recoded by the Royal Mail. The out of date postcode is replaced by the new
one, which is returned via the standard functions. The recommended course of
action is to pass a message to the user informing them that the postcode has
changed.
The Search function can also be used to update the counter, by using the prefix
defined by the SystemPrefix setting (see page 80). The use of this prefix, which
must be set to a combination of characters which would not be found in an
address, tells the search engine that a system search is being performed. The
function only checks for the specified prefix in the sSearch1 parameter.
The Search function will return an ‘out of phase’ error unless the Open function
has already been called in the current thread (see page 31).
36 • ActiveX Function Reference
QuickAddress Pro for the Web
ResultsCount
Returns the number of search results.
Prototype
Function ResultsCount () as Long
Return Value
status code
0
= success
-ve
= QA Error Message
Most likely errors
-11201
-11202
API not initialised
Function call out of phase
Comments
If only one result has been returned, there is no need to use the Preview
function (see page 38) to offer a picklist. The matched address and any
DataPlus information can be returned to the user immediately.
This function will return an error if the Open function (see page 31) or Search
function (see page 35) have not been called in the current thread.
QuickAddress Pro for the Web
ActiveX Function Reference • 37
Preview
Retrieves a single string that can be used to display an address in a picklist of
matches.
Prototype
Function Preview (ByVal lIndex as Long) as String
Parameters
lIndex
identifying number of the item you require
the address line for – between 0 and
ResultsCount -1, where ResultsCount is the
number of items in a list as returned by the
ResultsCount function (see page 37).
Return Value
String containing preview or null.
Comments
You should call Preview with iIndex equal to each of the values 0 to
ResultsCount -1 to ensure that you display strings for each item that the Search
function has found (see page 35).
Each returned string contains a single full address, with elements separated by
commas. For example, a string could look like this:
110 Rosslyn Avenue, Coventry, CV6 1GN
38 • ActiveX Function Reference
QuickAddress Pro for the Web
AddressCount
Returns the number of configured address lines.
Prototype
Function AddressLines() As Integer
Return Value
count
+ve
= count of the address lines
or status code
-ve
= QA Error Message
Most likely errors
-11201 API not initialised
-11202 Function call out of phase
Comments
This function returns the number of lines that have been set up for the returned
address (see the AddressLines keyword on page 76). The returned value
dictates the size of the array used in the Address function (see page 40).
This function will return an error if the Open function (see page 31) or Search
function (see page 35) have not been called in the current thread.
If you have configured Pro to use a pre-determined number of address lines,
there is no need to call this function.
QuickAddress Pro for the Web
ActiveX Function Reference • 39
Address
Retrieves a full address in an array.
Prototype
Function Address (ByVal lIndex as Long) as Variant
Parameters
lIndex
identifying number of the full address that
you require – between 0 and ResultsCount 1, where ResultsCount is the number of items
in a list as returned by the ResultsCount
function (see page 37).
Return Value
This function returns a whole address in an array of size AddressLines strings
(see page 39).
40 • ActiveX Function Reference
QuickAddress Pro for the Web
DataPlusCount
Returns the number of configured DataPlus lines.
Prototype
Function DataPlusLines() As Integer
Return Value
count
+ve
= count of the DataPlus lines
or status code
-ve
= QA Error Message
Most likely errors
-11201
-11202
API not initialised
Function call out of phase
Comments
This function, which is only available if you have purchased and configured
one or more DataPlus sets, returns the number of lines that have been set up
for DataPlus information. See the DataPlusLines keyword on page 80 for
information on configuring DataPlus sets.
The returned value dictates the size of the array used in the DataPlus function
(see page 42).
This function will return an error if the Open function (see page 31) or Search
function (see page 35) have not been called in the current thread.
If you have configured Pro to use a pre-determined number of DataPlus lines,
there is no need to call this function.
QuickAddress Pro for the Web
ActiveX Function Reference • 41
DataPlus
Retrieves a single DataPlus line.
Prototype
Function DataPlus (ByVal lIndex as Long) as Variant
Parameters
lIndex
identifying number of the DataPlus item you
require – between 0 and ResultsCount -1,
where ResultsCount is the number of items in
a list as returned by the ResultsCount function
(see page 37).
Return Value
This function returns DataPlus information for the selected address in an array
of size DataPlusLines strings (see page 41).
The function will return an error if the Open function (see page 31) or Search
function (see page 35) have not been called in the current thread.
42 • ActiveX Function Reference
QuickAddress Pro for the Web
ErrorMessage
Converts an error code to a text message.
Prototype
Function ErrorMessage (ByVal iCode as Integer) as String
Parameters
iCode
error code
Comments
This function is useful for converting a QuickAddress error code to a short text
message that can be displayed to the user for informational purposes. For
example, error -11203 returns the text message “Counter maintenance only
available”.
QuickAddress Pro for the Web
ActiveX Function Reference • 43
ErrorLevel
Returns the severity of an error.
Prototype
Function ErrorLevel (ByVal iCode as Integer) as Integer
Parameters
iCode
error code
Return Value
status code
0
= fatal or serious error
1
= warning only
Comments
This function indicates the severity of an error returned by Pro. A fatal or
serious error should be flagged to the user and dealt with appropriately – for
example, some serious errors might require Pro to be shut down, whereas
others, such as “No match”, simply require new search information from the
user. A warning should be handled in a manner appropriate to the condition
and can, if desired, be ignored.
44 • ActiveX Function Reference
QuickAddress Pro for the Web
ExpiryNotify
Can be used to provide a warning that the counter is about to expire. It reads
the ExpiryNotify= ini setting for counter values and returns the corresponding
message if the counter value has fallen below the one of the values since the
last call to the function.
Prototype
Function ExpiryNotify() as String
Return Value
String containing warning message if a message level has been passed since the
previous call to ExpiryNotify, NULL if not.
Comments
For example, if you include the following in QAPROWEB.INI:
[QAProWeb]
ExpiryNotify=Yes
+1000 Warning - fewer than 1000 searches left
+500 Warning - fewer than 500 searches left
+50 Product expiry imminent
Calling ExpiryNotify when the counter value has fallen below 500, since the
last call to the function, would return the string "Fewer than 500 searches left".
This message could then be sent as part of a warning email, for example.
QuickAddress Pro for the Web
ActiveX Function Reference • 45
ACTIVEX SAMPLE CODE
This section describes the sample code supplied for an ActiveX implementation
of Pro.
Integrating Pro into your own Website
Pro is intended for integration into your web based data entry process. The
sample code illustrates two alternative approaches:
•
'In process' Sample Code
The address lookup is presented as one of the stages in the data
entry process. This approach is recommended when designing
new data entry processes.
•
'Address Popup' Sample Code
The address lookup is an aside from the data entry process. This
is the simplest approach when you wish to add address lookup
functionality to an existing data entry process.
In Process Sample Code
This is intended for use when the data entry process consists of a series of
forms. The address lookup form becomes part of this series.
The sample code can be found in the 'form' sample code directory and consists
of the following file:
frontend.asp
Provides a front end to the proweb.inc code
To use this, you will need to:
1.
Choose where to insert it into your data entry process.
2.
Make the page before point to frontend.asp.
QuickAddress Pro for the Web
ActiveX Sample Code • 47
3.
Update the 'someother.asp' form submission entry in
frontend.asp to point to the next page in the sequence.
4.
Modify the look and feel of frontend.asp as you wish.
Address Popup Sample Code
This is intended to allow the addition of Address capture to a previously written
web page with minimal changes to the overall data entry process.
The data entry form can be left unchanged apart from the addition of a button
or hyperlink to activate the popup dialog. Once the correct address has been
retrieved, this will be transferred to the data entry form, and the popup dialog
will be deactivated.
This can be found in the 'popup' sample code directory, and consists of the
following files:
order_form.asp
An example order form
popup.asp
ASP script used inside the popped up
dialog
popupsrv.js
JavaScript for the HTML page that pops
up everything
popupclt.js
JavaScript to be included by the popped
up dialog
To integrate this you will need to:
1.
Choose the form to integrate it into – this must be an ASP page
(or converted to one).
2.
Change this form to <!-- #include file="popupsrv.js">.
3.
Create the code to activate the popup dialogs (or copy the code
used inside order_form.asp)
4.
Make sure that the code to activate the popup dialogs will only
be available if Pro has clicks on the counter. If Pro is unavailable
a plain text entry dialog should be provided.
48 • ActiveX Sample Code
QuickAddress Pro for the Web
5.
Modify the look and feel of popup.asp as you wish.
How the ASP Sample code works
The sample code is written to be stateless. This means that the only information
available to a page is the information from a previous page passed over in the
URL. The result of a Pro search cannot be accessed from the next page unless
the details are passed over. For instance, the picklist passes the final address
through to the last page in a ‘|’ delimited format.
'************************************************************
If not on final address page
Check Counter
If > 0
If have search string
0pen
If successful
Search
If successful or recoded
If results > 1
display picklist
end if
end if
end if
Close
end if
If results = 0 then
display search entry form
end if
end if
else if have selected picklist entry
build results for final address
end if
if nothing has been displayed
display final address page with or without selected
address
end if
QuickAddress Pro for the Web
ActiveX Sample Code • 49
JAVA FUNCTION REFERENCE
This section lists the Java functions available for use in Pro.
Multithreading
QuickAddress Pro supports multithreading, meaning that searches can be
performed at the same time on different threads.
For each thread, the Open function (see page 31) must be called to initialise the
search engine. After the search, a corresponding call to the Close function (see
page 33) must be made to end the thread and clean up resources.
Only one search can be done between the open and close calls. Results can
only be retrieved in the same thread as the search which was done.
Pseudocode
Below is a pseudocode example of performing a single search with the Pro API
functions.
Open thread
Open
If successful then
Perform address search
Search
If search successful or postcode recoded then
Get number of address lines
Get number of results
GetAddressCount
GetResultCount
Loop through each result
Retrieve preview to display in picklist
GetPreview
Retrieve each address to that the relevant one
can be selected
GetAddressLine
If DataPlus information available
Count DataPlus lines
GetDataPlusCount
QuickAddress Pro for the Web
Java Function Reference • 51
Retrieve DataPlus details
GetDataPlusLine
End if
End loop
End if
End if
Close thread
Close
Select address from picklist.
Return to customer screen.
Function Listing
The API functions can be split into three groups: those that open and close the
Pro search engine; those that search for address items; and those that retrieve
the address. For each function there is a brief explanation of what it does,
followed by its prototype, parameters, return value and further comments on
its functionality.
Open .................................................................... page 54
Close .................................................................... page 56
GetCounter ........................................................... page 57
Search................................................................... page 58
GetResultCount..................................................... page 60
GetPreview ........................................................... page 61
GetAddressCount.................................................. page 62
GetAddressLine..................................................... page 63
GetDataPlusCount ................................................ page 64
GetDataPlusLine ................................................... page 65
Note that these functions are all members of the
COM.qas.QAProWeb.QAProWeb class, and due to the JNI interface are only
accessible as such. The definition of the class is as follows:
class COM.qas.QAProWeb.QAProWeb
{
// native methods
public static native int
Open
public static native void
public static native int
52 • Java Function Reference
Close
Search
(String sIniFile,
String sSection);
();
(String sElement1,
String sElement2,
String sElement3,
QuickAddress Pro for the Web
String sElement4,
String sElement5);
public
public
public
public
static
static
static
static
native
native
native
native
int
int
int
int
GetResultCount
();
GetAddressCount
();
GetDataPlusCount
();
GetCounter
();
public static native String GetPreview(int iIndex);
public static native String GetAddressLine
(int iIndex,
int iLine);
public static native String GetDataPlusLine
(int iIndex,
int iLine);
public static native String ErrorMessage
(int iCode);
public static native int
ErrorLevel
(int iCode);
public static native String ExpiryNotify ();
static
{
System.loadLibrary("qapwbea");
}
}
QuickAddress Pro for the Web
Java Function Reference • 53
Open
Opens the Pro database for a single thread, and reads configuration
information.
Prototype
public static native int Open (String sIniFile, String
sSection);
Parameters
sIniFile
configuration file
sSection
configuration file section
Return Value
status code
0
= success
-ve
= QA Error Message
Most likely errors
-1031
-9298
-11200
-11203
-11204
Can't find configuration file
Couldn’t open TCP/IP connection
Search library failed to load
Counter maintenance only available
Searching disabled
Comments
When this function is called, it checks the name of the library and the threading
model to be used.
54 • Java Function Reference
QuickAddress Pro for the Web
The sIniFile parameter specifies the configuration (.INI) file from which the API
is to obtain configuration information, such as the address format and search
options. If an empty string or null is passed, the default INI file is taken
(QAPROWEB.INI on most platforms).
The sSection parameter specifies the section of the INI file from which the API
gathers address formatting information. If an empty string is passed, the default
section, QADefault, is used.
There are various groups of errors that can be returned from this function. Error
-1031 signifies that Pro cannot locate the configuration file. Error -11203
signifies that only searches using the system prefix (see page 80) are available.
This will happen if the counter has run out or become corrupted – see
“Configuration” on page 71.
In the event of the counter being less than 0, it is recommended that you
provide a blank template to the user, so that they can enter their address
manually. The sample code supplied provides an example of this.
When you have finished capturing an address, call the Close function (see
page 56) even if the Open function failed. An error will be returned if Close has
not been called after a previous Open in the current thread.
QuickAddress Pro for the Web
Java Function Reference • 55
Close
Closes the QuickAddress search engine on the current thread, and releases any
resources associated with it.
Prototype
public static native void Close ();
Comments
Close must be called to clean up resources after every call to Open (see
page 54).
56 • Java Function Reference
QuickAddress Pro for the Web
GetCounter
Returns the value of the counter.
Prototype
public static native int GetCounter();
Return Value
status code
+ve
= number of clicks left on counter
-10 000
= counter corrupt or no clicks
available
Comments
This function returns the available number of clicks on the counter. If the
counter is corrupt, -10 000, will be returned. (For more information about the
counter, see page 25.)
The value of the counter can also be obtained by searching with the
SystemPrefix setting – see page 80 for further details.
QuickAddress Pro for the Web
Java Function Reference • 57
Search
Executes an address search using the specified search string.
Prototype
public static native int Search (String
String
String
String
String
sElement1,
sElement2,
sElement3,
sElement4,
sElement5);
Parameters
sElement<n>
address element forming part of the search
string
Return Value
status code
0
= success
-ve
= QA Error Message
Most likely errors
-9811
-9978
-9982
-10000
-11201
-11202
-11205
Postcode has been recoded
No match
Operation cancelled
Bad search expression
API not initialised
Function call out of phase
Incorrect or incomplete postcode
Comments
Each sElement<n> parameter in this function represents a single address
element, which makes up part of the address search. A maximum of five
58 • Java Function Reference
QuickAddress Pro for the Web
elements can be entered. These elements are then concatenated into a single
string before being passed to the underlying search engine. If an sElement<n>
parameter is empty or null, it will be ignored in the search.
Question mark and asterisk wildcards can be used in the search if the
AllowWildcardSearches configuration keyword is enabled.
The SearchElementType<n> configuration setting can be used to constrain
the element passed in a sElement<n> parameter. See page 81 for further
information on this setting. The search can also be limited by setting a timeout
period (see the SearchTimeout keyword by specifying the maximum number
of postcodes to be returned (see MaxPostcodes on page 74).
A single picklist of results will be returned from the search, via the
GetResultCount and GetPreview functions (see pages 60 and 61 respectively).
If only one result is returned, there is no need to use the GetPreview function.
The pre-payment counter is decremented each time a successful search is
performed. Lastly, the GetAddressLine function (see page 63) returns a full
address formatted as specified in the configuration file (see page 75).
Error -9811 occurs when a user searches using a postcode that has been
recoded by the Royal Mail. The out of date postcode is replaced by the new
one, which is returned via the standard functions. The recommended course of
action is to pass a message to the user informing them that the postcode has
changed.
The Search function can also be used to update the counter, by using the prefix
defined by the SystemPrefix setting (see page 80). The use of this prefix, which
must be set to a combination of characters which would not be found in an
address, tells the search engine that a system search is being performed. The
function only checks for the specified prefix in the sElement1 parameter.
The Search function will return an ‘out of phase’ error unless the Open function
has already been called in the current thread (see page 54).
QuickAddress Pro for the Web
Java Function Reference • 59
GetResultCount
Returns the number of search results.
Prototype
public static native int GetResultCount ();
Return Value
status code
0
= success
-ve
= QA Error Message
Most likely errors
-11201
-11202
API not initialised
Function call out of phase
Comments
If only one result has been returned, there is no need to set the GetPreview
function (see page 61) to offer a picklist. The matched address and any
DataPlus information can be returned to the user immediately.
This function will return an error if the Open function (see page 54) or Search
function (see page 58) have not been called in the current thread.
60 • Java Function Reference
QuickAddress Pro for the Web
GetPreview
Retrieves a single string that can be used to display an address in a picklist of
matches.
Prototype
public static native String GetPreview (int iIndex);
Parameters
iIndex
identifying number of the item you require
the address line for – between 0 and
GetResultCount -1, where GetResultCount is
the number of items in a list as returned by
the GetResultCount function (see page 60).
Return Value
preview string
=
success
empty string
=
invalid index number
Comments
You should call GetPreview with iIndex equal to each of the values 0 to
GetResultCount -1 to ensure that you display strings for each item that the
Search function has found (see page 58).
Each returned string contains a single full address, with elements separated by
commas. For example, a string could look like this:
110 Rosslyn Avenue, Coventry, CV6 1GN
QuickAddress Pro for the Web
Java Function Reference • 61
GetAddressCount
Returns the number of configured address lines.
Prototype
public static native int GetAddressCount();
Return Value
count
+ve
= count of the address lines
or status code
-ve
= QA Error Message
Most likely errors
-11201
-11202
API not initialised
Function call out of phase
Comments
This function returns the number of lines that have been set up for the returned
address (see the AddressLines keyword on page 76). The returned value
dictates the number of times you need to call the GetAddressLine function (see
page 63).
This function will return an error if the Open function (see page 54) or Search
function (see page 58) have not been called in the current thread.
If you have configured Pro to use a pre-determined number of address lines,
there is no need to call this function.
62 • Java Function Reference
QuickAddress Pro for the Web
GetAddressLine
Retrieves a full address.
Prototype
public static native String GetAddressLine (int iIndex, int
iLine);
Parameters
iIndex
identifying number of the full address that
you require – between 0 and GetResultCount
-1, where GetResultCount is the number of
items in a list as returned by the
GetResultCount function (see page 60).
iLine
Number of the address line to retrieve
Return Value
address line
=
success
empty string
=
invalid index number/error
Comments
You can obtain the number of lines in a formatted address from
GetAddressCount (see page 62). You should call GetAddressLine with iLine set
to each value from 0 to GetAddressCount -1 to ensure that you obtain strings
for each line of the selected address.
This function will return an error if the Open function (see page 54) or Search
function (see page 58) have not been called in the current thread.
QuickAddress Pro for the Web
Java Function Reference • 63
GetDataPlusCount
Returns the number of configured DataPlus lines. Negative values are error
codes.
Prototype
public static native int GetDataPlusCount ();
Return Value
count
+ve
= count of the DataPlus lines
or status code
-ve
= QA Error Message
Most likely errors
-11201
-11202
API not initialised
Function call out of phase
Comments
This function, which is only available if you have purchased and configured
one or more DataPlus sets, returns the number of lines that have been set up
for DataPlus information. See the DataPlusLines keyword on page 80 for
information on configuring DataPlus sets.
The returned value dictates the number of times you need to call the
GetDataPlusLine function (see page 65).
This function will return an error if the Open function (see page 54) or Search
function (see page 58) have not been called in the current thread.
If you have configured Pro to use a pre-determined number of DataPlus lines,
there is no need to call this function.
64 • Java Function Reference
QuickAddress Pro for the Web
GetDataPlusLine
Retrieves a single DataPlus line.
Prototype
public static native String GetDataPlusLine (int iIndex, int
iLine);
Parameters
iIndex
identifying number of the DataPlus item you
require – between 0 and GetResultCount -1,
where GetResultCount is the number of items
in a list as returned by the GetResultCount
function (see page 60).
iLine
Number of the DataPlus line to retrieve
Return Value
DataPlus line
= success
Empty string
= QA Error Message
Most likely errors
-11201
-11202
API not initialised
Function call out of phase
Comments
This function returns a single DataPlus line for the address you select. Call it as
many times as required to return all available DataPlus lines; the total number
of lines can be obtained from GetDataPlusCount (see page 64).
The function will return an error if the Open function (see page 54) or Search
function (see page 58) have not been called in the current thread.
QuickAddress Pro for the Web
Java Function Reference • 65
ErrorMessage
Converts an error code to a text message.
Prototype
public static native String ErrorMessage (int iCode);
Parameters
iCode
error code
Comments
This function is useful for converting a QuickAddress error code to a short text
message that can be displayed to the user for informational purposes. For
example, error -11203 returns the text message “Counter maintenance only
available”.
66 • Java Function Reference
QuickAddress Pro for the Web
ErrorLevel
Returns the severity of an error.
Prototype
public static native int ErrorLevel (int iCode);
Parameters
iCode
error code
Return Value
status code
0
= fatal or serious error
1
= warning only
Comments
This function indicates the severity of an error returned by the API. A fatal or
serious error should be flagged to the user dealt with appropriately – for
example, some serious errors might require the API to be shut down, whereas
others, such as “No match”, simply require new search information from the
user. A warning should be handled in a manner appropriate to the condition
and can, if desired, be ignored.
QuickAddress Pro for the Web
Java Function Reference • 67
ExpiryNotify
Can be used to provide a warning that the counter is about to expire. It reads
the ExpiryNotify= ini setting for counter values and returns the corresponding
message if the counter value has fallen below the one of the values since the
last call to the function.
Prototype
public static native String ExpiryNotify ();
Return Value
String containing warning message if a message level has been passed since the
previous call to ExpiryNotify, null if not.
Comments
For example, if you include the following in the .ini file, QAPROWEB.INI:
[QAProWeb]
ExpiryNotify=Yes
+1000 Warning - fewer than 1000 searches left
+500 Warning - fewer than 500 searches left
+50 Product expiry imminent
Calling ExpiryNotify when the counter value has fallen below 500, since the
last call to the function, would return the string "Fewer than 500 searches left".
This message could then be sent as part of a warning email, for example.
68 • Java Function Reference
QuickAddress Pro for the Web
JAVA SAMPLE CODE
The sample code has two parts: a test harness for verifying each function
individually (QAProWebTestHarn.java), and a JSP version provided in it its
own web application (QAProWeb.war). The web application is intended for
use with Tomcat (the reference implementation for servlets recommended by
Sun).
The pseudocode for the JSP is as follows:
If not on final address page
Check Counter
If > 0
If have search string
0pen
If successful
Search
If successful or recoded
If results > 1
display picklist
end if
end if
end if
Close
end if
If results = 0 then
display search entry form
end if
end if
else if have selected picklist entry
build results for final address
end if
if nothing has been displayed
display final address page with or without selected
address
end if
QuickAddress Pro for the Web
Java Sample Code • 69
CONFIGURATION
This section describes the way in which you define the layout of each address
that Pro returns to your application or applications and any extra text or
formatting instructions you want to go with each address. Pro supports multiple
address layouts, and different threads can use different layouts.
All this address formatting information is contained in configuration files,
which are easily identifiable with their .INI extensions. A single configuration
file is made up of at least one section. A section, in this context, is a simple
sub-division of a configuration file which can hold specific address layout
instructions.
Pro uses two main configuration files: one on the server side, and one on the
client side.
The following section describes the two main configuration files and how you
add new sections or edit existing ones, such as those contained in the default
configuration file, QAPROWEB.INI (located in WINNT\SYSTEM32).
Format of a Configuration File
A configuration file can contain several sections, each comprising a set of
address format instructions. To view a configuration file, use a text editor such
as Notepad. Do not use a formatting editor such as Microsoft Write because it
is likely to corrupt the configuration file with its own formatting codes if you
save it.
The sections within the configuration file have their title in square brackets like
so:
[QADefault]
QADefault is, as the name suggests, the default section. You can add other
sections if you want, which you can keep for specific uses, but any settings not
indicated in an added section are taken from QADefault.
The square brackets of the section name define the beginning of the next
section, but only if the beginning bracket is left justified, with no spaces before
QuickAddress Pro for the Web
Configuration • 71
it on its particular line. The square brackets also define the end of the previous
section.
Each section comprises a set of instructions in the form of keyword
assignments, like this:
keyword=value
A keyword is the name of a setting. It can consist of a combination of letters
and digits in uppercase or lowercase, and it must be followed immediately by
an equals sign (=), which introduces the value assigned to the keyword. The
value can be an integer, a string, or a boolean, depending on the type of setting.
Not all entries have to be keyword assignments. You can add comments by
prefixing the comment with a semi-colon (;).
A typical set of address formatting keyword settings in a configuration section
might look like this:
Abbreviate=
Capitalise=TOWN
Line 1=W35
Line 2=W35
Line 3=W35
Line 4=W35 TOWN
Line 5=W8 POST
The instructions here are to allow no abbreviations in the address, to put the
post town in capital letters, and to give lines 1 to 4 of the address a width of 35
characters and line 5 a width of eight characters. In addition, line 4 is to
contain the post town and line 5 the full postcode.
Server Configuration Settings
The configuration file on the server side, QANSRV.INI, contains basic setup
details. The available keywords are listed and described below.
72 • Configuration
QuickAddress Pro for the Web
DataDir
DataDir=<directory path>
If the Pro data files are not in C:\QADDRESS\DATA, you can
specify the new directory with this keyword assignment.
For example: DataDir=C:\PRO\DATA prompts Pro to look in
this directory for the database files.
Ensure that you place this keyword in QADefault rather than any
other configuration section.
ServerPort
ServerPort=<number>
This keyword identifies which port is to receive requests from
the client API. This is configured through the setup program
when you first install Pro; the default is 2001.
Note that if error -9294 (see page 93) is returned when you try
to start the server, the ServerPort keyword should be checked in
both QANSRV.INI and QAPROWEB.INI. Both keywords must
point to the same port number (see page 75).
ServerAddress
ServerAddress=<IP address> or Any
This keyword defines the IP address of the server machine. The
default is Any, meaning that the server can bind to multiple IP
addresses. You can change this to a specific hostname or ‘dotted
quad’ IP address if required.
DataSets
DataSets=Yes or No
The Server configuration file should contain details of every
available DataPlus set. The Client configuration file can then
specify a selection of these available data sets from which to
request information. Thus the Client only requests the DataPlus
QuickAddress Pro for the Web
Configuration • 73
results for those sets which are configured on the Client, not all
available data sets.
The DataSets keyword is set to No by default. Change it to Yes
to choose to have DataPlus information returned. After the
DataSets=Yes line, add details of the DataPlus information that
you want.
For example, to have the MP Names data set (PCMP) and the
100m Grid Reference data set (GRID), you would type this:
DataSets=Yes
+DataSet:PCMP
+DataSet:GRID
This means that the Server can return data for both data sets. The
Client can request information from either or both.
MaxPostcodes
MaxPostcodes=<no. of postcodes>
This keyword sets a limit to the number of postcodes that Pro
can generate during the index lookup stage of searching.
For example: MaxPostcodes=300 tells Pro to abort a search
once 300 postcodes have been found
When the maximum postcode figure is exceeded, Pro returns
the error qaerr_TOOMANYCODES (-9979) for a wildcard
search, or qaerr_TOOMANYMATCHES (-9980) for an address
element search (for example street and town). No search results
are returned.
The default setting is zero, which imposes no restriction on the
number of postcodes Pro can generate.
You might want to set a figure for MaxPostcodes in order to limit
the time spent during searching, and to reduce the amount of
memory consumed by a search.
74 • Configuration
QuickAddress Pro for the Web
Client Configuration Settings
The configuration file on the client side, QAPROWEB.INI, contains address
formatting and search details. It also contains ServerPort and ServerAddress
keywords, which must point to the port number in the server configuration file
and the server’s IP address respectively.
Note:
As Pro is designed to be installed on a single machine, the
ServerAddress keyword in QAPROWEB.INI is set to Localhost by
default. You only need to change this if the server program is installed
on a different machine.
All the keywords that enable you to tailor Pro to your requirements are shown
in the next sections, along with an explanation of what values each assignment
can take. First are the settings that specify what the output addresses are to look
like. After that are some general settings that affect the Pro environment.
Configuration settings for address formatting
Among the most important assignments are those that specify which address
elements are to go on which line, which elements are to be abbreviated, and
which ones are to go in capital letters. Each address element is identified in the
keyword assignments by a code of up to four characters. Below and continuing
over the page is the full list of these codes (in the default ordering in which they
come in a returned address):
Code
Description
ORGA
Organisation name
POBO
PO Box
SUBP
Sub-premises
NAME
building name
NUMB
building number
DEPT
Dependent thoroughfare
THOR
Thoroughfare
DDPL
Double dependent locality
QuickAddress Pro for the Web
Configuration • 75
Note:
DEPL
Dependent locality
TOWN
Post town
COUN
County
POST
Postcode as a whole (space separated)
OUTP
Outbound postcode only
INPO
Inbound postcode only
...
Placed after any component, indicates that
unspecified fields may follow on the line if
space allows
If a component is prefixed by an X then it will not appear in any other
part of the address unless explicitly referred to. For example, the setting
Line1= W35 X ORGA means that the organisation can only appear on
the first line.
These are the keyword assignments you can create or edit in the client
configuration file:
AddressLines
AddressLines=<number>
This specifies how many lines are to appear in the formatted
address, where <number> is the number of address lines. The
default is 6.
LineN
Line1=W<number><element 1>...<element n>
Line2=W<number><element 1>...<element n>
...
LineN=W<number><element 1>...<element n>
This specifies which address element is to appear on which line,
where W signifies that the number that follows it is the width of
the line in characters, and <element 1>...<element n> are
the address elements in the order that they are to go on the line.
76 • Configuration
QuickAddress Pro for the Web
For example: Line4=W30 TOWN instructs Pro to put the post
town on line 4 and give it a width of 30 characters.
You can also use three dots after the address elements to
indicate that further fields can follow on the line if space allows.
For example: Line1=W35 ORGA ... specifies that line 1 is to
be 35 characters long, starting with the organisation name, and
that the elements that come next in the address can also go on
line 1 so long as they fit there.
Abbreviate
Abbreviate=<element 1>...<element n>
This specifies that the address elements indicated by
<element 1>...<element n> will be abbreviated. The
possible values are THOR, DEPT, COUN and ALL (that is, all
address elements are to be abbreviated).
For example: Abbreviate=THOR COUN means abbreviate
thoroughfares and counties.
Capitalise
Capitalise=<element 1>...<element n>
This specifies that the address elements listed in
<element 1>...<element n> will be put in capital letters.
Any address elements can be specified; ALL instructs Pro Web
to put all address elements in upper case.
For example: Capitalise=TOWN COUN means that just the
post town and the county will go into capitals.
PostcodeFormat
PostcodeFormat=S-or-4-or-S4-or-blank
This specifies how you want the returned postcode to appear.
The choice of setting is as follows:
QuickAddress Pro for the Web
Configuration • 77
Parameter
Explanation
Examples
S
Insert a space between
outcode and incode
SW11 2AZ
L1 1AA
4
Justifies the outcode to four
characters
SW112AZ
L1 1AA
S4
Inserts a space and justifies
outcode to four characters
SW11 2AZ
L1 1AA
blank
No spaces to occur in the
postcode
SW112AZ
L11AA
The default is S, which is the usual format of a postcode with a
single space between the two parts.
For example: PostcodeFormat= specifies no gap in the
postcode.
FieldEnd
FieldEnd=<character>
This specifies which character is to come between address
elements on the same line. It defaults to no separator. A
separator will not be placed before a postcode and will not
appear after a property or sub-property number (unless a
number is followed by another number).
If you want to type in the actual character that Pro will use, then
you must specify that it is a literal by prefixing it with the single
quote character ('). You can define an ASCII character by simply
typing in the number without the single quote prefix.
For example: FieldEnd=', defines the field separator to be a
comma.
78 • Configuration
QuickAddress Pro for the Web
LineEnd
LineEnd=<character>
This specifies which character is to appear at the end of each
address line (except directly preceding a postcode). The default
is no separator.
As for FieldEnd, if you want to type in the actual character that
will be used, you must prefix it with the single quote character
('). You can define an ASCII character by simply typing in the
number without the single quote prefix.
For example: LineEnd=', defines the line separator to be a
comma.
LinePad
LinePad=<character>
This instructs Pro to pad out each address line to its specified
width (or to the default width of 30 characters) with the
character you specify in <character>.
As with FieldEnd and LineEnd, if you want to type in the actual
character that will be used, prefix it with the single quote
character ('). You can define an ASCII character by simply
typing in the number without the single quote.
For example: LinePad='x defines the padding character to be
the letter "x".
NoCounty
NoCounty=<string>
This specifies whether the county should be shown always,
never or only when postally required. The three possible
assignments are these:
NoCounty=Always
Do not display the county
NoCounty=Never
Always display the county
QuickAddress Pro for the Web
Configuration • 79
NoCounty=IfOptional
Display the county only if
it is postally necessary
DataPlusLines
DataPlusLines=<number>
This specifies the type of DataPlus data, if any, that is returned
with the name and address.
Each data set occupies one line of information. If you have
DataPlus data sets, change this setting to the number of data sets
that you wish to use. You can specify any or all of the DataPlus
sets defined with the DataSets keyword (see page 73).
You follow this setting by specifying the format of each line,
setting the width of the line and the parts of the DataPlus data
set you want (the code, the description or both).
For example, to have two lines of 40 characters containing both
parts of the 100m grid references data set (GRID) and the
description part of the MOSAIC data set (MOSC), you would
type in this:
DataPlusLines=2
DataPlusLine1=W40 GRID.Easting GRID.Northing
DataPlusLine2=W40 MOSC.Description
General configuration settings
SystemPrefix
SystemPrefix=<string>
This keyword enables you to specify the prefix required for
system information searches.
You can retrieve system information, such as version numbers,
file names and counter statistics, by typing the system prefix
string into Pro’s search dialog instead of the usual postcode or
address elements. It is important that the prefix is a combination
of characters which would never appear at the beginning of an
80 • Configuration
QuickAddress Pro for the Web
address search. This must be set in the [QAProWeb] section of
the QAPROWEB.INI (located in WINNT\SYSTEM32).
If this keyword is left blank, system information retrieval will not
be available.
For example, setting SystemPrefix=xxx would mean that typing
‘xxx’ as the beginning of a search would retrieve the information
you require. There are then three variations of system searches
that you can employ:
xxx:
This returns the counter
information.
xxx:SystemInfo
This returns general system
information.
xxx:<update code>
This applies an update code (as
provided by QAS) to top up the
counter.
Note that the colon is required in system prefix searches.
SearchElementType
SearchElementType<line number> = <comma separated types>
This enables you to constrain the element passed in a
sSearch<n> parameter. Types that you can restrict on are:
Element Type
Constraint
Organisation
Organisation
Premises
Premise
Street
Street
Locality
Locality
Town
Town
County
County
QuickAddress Pro for the Web
Configuration • 81
For example, the following setting would restrict the first line to
contain only an organisation and/or postcode.
SearchElementType1 = Organisation,Premise
Note:
It is not possible to restrict on the postcode.
LogFile / LogErrors
LogFile=<name of log file>
LogErrors=true or false
LogFile enables you to specify a log file to which any errors that
occur when you call API functions are written. These errors are
only written if you set LogErrors=true as well as specifying the
name of the file you want to write to with LogFile.
It is recommended that you create a log file when integrating the
API.
LogTrace
LogTrace=0 or 1
This setting determines whether files which are opened and
closed are logged in the log file. Set LogTrace=1 to enable this
file logging facility.
ExpiryNotify
ExpiryNotify= Yes or No
Can be used to provide a warning that the counter is about to
expire. It reads the ExpiryNotify= ini setting for counter values
and returns the corresponding message if the counter value has
fallen below the one of the values since the last call to the
function.
For example, if you include the following in QAPROWEB.INI:
[QAProWeb]
ExpiryNotify=Yes
82 • Configuration
QuickAddress Pro for the Web
+1000 Warning - fewer than 1000 searches left
+500 Warning - fewer than 500 searches left
+50 Product expiry imminent
Calling ExpiryNotify when the counter value has fallen below 500, since the
last call to the function, would return the string "Fewer than 500 searches left".
This message could then be sent as part of a warning email, for example.
OverFlow
OverFlow=<number>
Can be used to set the overdraft limit to between 0 -1000 clicks.
This is set to 50 by default, and This must be set in the
[QAProWeb] section of the QAPROWEB.INI (located in
WINNT\SYSTEM32).
AllowWildcardSearches
AllowWildcardSearches= Yes or No
Wildcard searching is only available if the configuration setting
AllowWildcardSearches is set to Yes. This must be set in the
[QAProWeb] section of the QAPROWEB.INI (located in
WINNT\SYSTEM32). Wildcard searching is disabled by default.
This is due to the large amount of processing time Wildcard
searching uses on a web server.
QuickAddress Pro for the Web
Configuration • 83
APPENDIX A: ERROR CODES
Client API Errors
This section shows all the possible error message constants that can be returned
from various functions in the client API. In the listing of API functions (which
starts on page 29), the most likely errors are shown under the Return Value
heading.
Note:
You can get the API to convert a numeric error code into a simple
textual description by calling QAErrorMessage (see page 43).
The API header files contain constant definitions for a number of data types
used by the library. The constants that signify a QA Error Message are listed
below. Each constant is given its value and a description. Those marked with
an asterisk are warnings rather than errors.
Error message
Constant
Description of error
qaerr_NOMEMORY
-1001
Insufficient memory
qaerr_BADDRIVE
-1027
Invalid drive
qaerr_BADDIR
-1028
Invalid directory
qaerr_BADINIFILE
-1031
Can't find configuration
file
qaerr_BADDATADIR
-1037
Invalid data directory
qaerr_BADTEMPDIR
-1038
Could not create
temporary directory
qaerr_NOTDEFINED
-1040
Item number is too big
qaerr_CCFAILURE
-1050
Copy control failure
qaerr_CCBADCODE
-1051
Invalid copy control code
qaerr_CCACCESS
-1052
Access denied
qaerr_CCNODONGLE
-1053
Dongle not configured
qaerr_CCNOUNITS
-1054
No units left on meter
QuickAddress Pro for the Web
Appendix A: Error Codes • 85
qaerr_CCNOMETER
-1055
Meter not initialised
qaerr_CCNOFEATURE
-1056
Feature not supported
qaerr_CCINVALID
-1057
SoftKey integrity failure
qaerr_CCINSTALL
-1060
Product must be installed
qaerr_CCEXPIRED
-1061
Product has expired
qaerr_CCDATETIME
-1062
Date/time gone
backwards
qaerr_CCUSERLIMIT
-1063
Number of users
exceeded
qaerr_CCACTIVATE
-1064
Product must be
activated
qaerr_CCBADDRIVE
-1065
Permission not allowed
for this drive type
qaerr_CCREGISTER
-1066
Product must be
registered
qaerr_UNAUTHORISED
-1070
Unauthorised access
qaerr_NOTHREAD
-1080
Could not create thread
qaerr_NOTLSMEMORY
-1081
Out of thread-localstorage
qaerr_NOSPEC
-1301
Bad formatting
specification
qaerr_CANTOPENDATAFILE
-1712
Data set specified does
not exist
qaerr_NOTASK
-1090
Could not create task
qaerr_NONRAPIDFILE
-9801
File QASTRT.ALL in
wrong format
qaerr_INVALIDAREA
-9802
Postcode area is invalid
qaerr_AREALEVEL
-9803
Correct to area level
* qaerr_DISTRICTLEVEL
-9804
Correct to district level
86 • Appendix A: Error Codes
QuickAddress Pro for the Web
* qaerr_SECTORLEVEL
-9805
Correct to sector level
* qaerr_HALFSECTORLEVEL
-9806
Correct to half sector
level
qaerr_NOCODES
-9807
No postcodes found
qaerr_NOAREADATA
-9809
Area data unavailable
* qaerr_POSTCODERECODED
-9811
Warning that postcode
has been recoded
qaerr_INVALIDAREA
-9802
Postcode area is invalid
qaerr_PRODATAEXPIRED
-9966
PAF data is more than 18
months old
qaerr_STREETSVERSION
-9967
Streets file date different
from already opened data
files
qaerr_TOOSHORT
-9968
Buffer specified is too
short (less than 35
characters)
qaerr_PREMISESVERSION
-9969
Premises file date
different from streets file
qaerr_INDEXVERSION
-9970
Index file date different
from streets and premises
file
qaerr_TOOLONG
-9971
Buffer specified is too
large (greater than 512
characters)
qaerr_BADPHASE
-9974
Operation performed out
of turn
qaerr_STREETSOPEN
-9975
Could not open streets
file
qaerr_PREMISESOPEN
-9976
Could not open premises
file
qaerr_INDEXOPEN
-9977
Could not open index file
QuickAddress Pro for the Web
Appendix A: Error Codes • 87
qaerr_NOMATCH
-9978
No match
qaerr_TOOMANYCODES
-9979
Number of postcodes
returned from the index
exceeded number set in
MaxPostcodes (see
page 74)
qaerr_TOOMANYMATCHES
-9980
Exceeded the specified
maximum no. of
postcodes
qaerr_NOSUCHAREA
-9981
Area code of postcode
does not exist
qaerr_CANCELLED
-9982
A long operation was
interrupted
qaerr_NODP
-9983
Not a delivery point
qaerr_NONUMBER
-9984
property number
specified but not
matched
qaerr_CANTSTEP
-9987
Nothing to step into
qaerr_SYNTAX
-9988
Bad selection string
qaerr_BADFILEFORMAT
-9989
File discarded with
incorrect format
qaerr_BADSEARCHDESC
-10000
Bad search expression
qaerr_TIMEDOUT
-10001
Search timed out
qaerr_LIBRARYFAILED
-11200
Search library failed to
load
qaerr_NOTINITIALISED
-11201
API not initialised
qaerr_OUTOFPHASE
-11202
Function call out of
phase
qaerr_SYSTEMONLY
-11203
Counter maintenance
only available
qaerr_OPENDISABLED
-11204
Searching disabled
88 • Appendix A: Error Codes
QuickAddress Pro for the Web
qaerr_INCORRECTPOSTCODE
-11205
Incorrect or incomplete
postcode
Not all of these error messages represent a failure of the function to return
successfully. Some are warning messages which give you more information on
the address returned. The following pages cover the more important errors in
more detail.
qaerr_NOMEMORY
Error Code -1001
Pro has run out of memory. This happens if Pro begins a task
and subsequently discovers that there isn’t enough memory
available to complete it.
Example
Memory may run out during a complicated wildcard search (see
page 18).
If your application receives this error, a possible course of action
is to produce a message dialog asking the user to close down
one or more applications in an attempt to free enough memory
for Pro.
qaerr_BADDRIVE
Error Code -1027
An invalid drive has been specified.
Examples
You will encounter this error if a path name specified in the
configuration file – say the location of DataDir – includes a
drive which does not exist. Similarly, this mistake might be
made in a call to the Open function (see page 31 and page 54).
This is the general case that will produce the error
qaerr_BADDRIVE:
“X:\some_path...”
where X is an invalid drive.
QuickAddress Pro for the Web
Appendix A: Error Codes • 89
qaerr_BADDIR
Error Code -1028
The directory Pro attempted to access is invalid. This happens
if an incorrect directory is specified in the configuration file.
This error most often occurs when the incorrect directory is
DataDir but it could apply to any of the directories which are set
in the configuration file.
qaerr_BADINIFILE
Error Code -1031
Pro cannot open the configuration file. This happens if Pro fails
to find the configuration file in any of the designated search
paths. The default configuration file is QAWEBPRO.INI unless
you specify otherwise in your call to the Open function (see
page 31 and page 54). Pro looks for the configuration file in the
following manner:
If a directory and filename was specified in your call to the API
initialisation function, then Pro looks in this directory for the
configuration file. Should Pro be unable to find the file, it
returns the error qaerr_BADINIFILE.
Otherwise Pro looks for the configuration file in the current
directory and then, if necessary, it searches for it along the path.
If it has still not found a configuration file, then it returns
qaerr_BADINIFILE.
Failure to open the configuration file will prevent the API
initialising.
qaerr_NOTDEFINED
Error Code -1040
You will get this error if you attempt to retrieve a list entry that
does not exist. This happens if you attempt to reference a list
item which is beyond the range of possible entries.
Note that items in a list are numbered from 0 to n-1 (where n is
the total number of items in the list).
90 • Appendix A: Error Codes
QuickAddress Pro for the Web
Example
You attempt to retrieve item number ten from a list of ten items.
qaerr_NOSPEC
Error Code -1301
You will not normally encounter this error, which is the result of
erroneous programming, and indicates an incorrect program
flow.
Example
If you call the Address or GetAddressLine function (see page 40
and page 63) before calling Open (see page 31 and page
page 54) you might cause the error qaerr_NOSPEC.
You can best uncover this error by carefully examining your
code for program flow errors.
This error can also arise because of an incorrect address
formatting specification. See page 75 for the full range of
address formatting configuration settings.
qaerr_NONRAPIDFILE
Error Code -9801
This code indicates that the QASTRT.ALL data file that Pro has
attempted to open is not valid for your version of Pro.
qaerr_INVALIDAREA
Error Code -9802
This code is returned when the area specified in the postcode is
not valid.
Example
If you pass the Search function (see page 35 and page 58) a
string such as JB3 9DT, which includes the invalid area JB, the
functions returns the qaerr_INVALIDAREA.
QuickAddress Pro for the Web
Appendix A: Error Codes • 91
Client/Server Communication Errors
There are two types of errors which you might encounter when running the
QuickAddress server:
•
errors generated by the Server and sent to the Client;
•
errors arising in the network communication between the Server
and Client, stopping these programs from initialising or
communicating.
You will find explanations of the search engine errors in the section above.
Below are listed some of the network communication difficulties that you might
meet.
Note:
If the Server is running under Windows NT, error codes may be
displayed as positive values instead of the corresponding negative
values.
“Bad IP number format”
Error Code -9291
This error occurs if the IP number specified when installing Pro
is incorrectly formatted. This number should be in 'dotted quad'
format – i.e. four numbers separated by dots (for example:
150.150.100.50).
Correct the formatting in the configuration file.
Amend the ServerAddress= setting in the client configuration
file to the correct IP number. Alternatively, you can specify a
hostname in this setting instead of an IP address.
“TCP/IP accept failure”
Error Code -9292
You get this error if the connection between Client and Server
has not been made. This might be due to a network problem.
Check the Server is running.
Ensure that the Server is loaded and running before trying to
connect to it. Check that it hasn't stopped or terminated due to
92 • Appendix A: Error Codes
QuickAddress Pro for the Web
a serious error, and that there are no broken network
connections.
Check the Client configuration file
If the Server is running, then ensure that the ServerAddress=
setting in the Client configuration file is correct, and that the
ServerPort= setting corresponds with the equivalent setting in
the Server configuration file.
“Couldn't listen to TCP/IP socket”
Error Code -9293
This means that the port you have specified is already in use by
another application.
Check the ServerPort setting
The ServerPort= setting in the Server's configuration file
contains the port number which the Server is using to receive
requests. Check that this setting is correct, and corresponds with
the ServerPort= setting in the Client's configuration file.
“Couldn't bind TCP/IP socket”
Error Code -9294
This error can occur when you try to start the Server. The system
believes that the port you specified with the ServerPort
configuration setting is unavailable or is already in use.
You might encounter this error if you already have a copy of the
Server running, or if a different program running on the Server
machine has already claimed the port that the Server is looking
for.
If you were running the Server, but you shut it down:
Some Clients may still be connected to the Server port. This can
happen if you shut down the Server in the middle of an address
search, leaving a Client connected to the port, waiting for the
search results. Generally the Client will time out, freeing up the
port.
QuickAddress Pro for the Web
Appendix A: Error Codes • 93
If the Client doesn’t time out, perhaps because you have set a
long timeout period, then you will need to locate the offending
Client and either cancel the current search or close the Client
down.
“TCP/IP Hostname lookup failed”
Error Code -9295
This error can occur if you have specified a host name rather
than a numerical IP address in the ServerAddress= setting of the
Client's configuration file. The Client cannot connect to the
Server because it cannot find the configured host name.
Check the Server is running
Ensure that the Server is loaded and running before trying to
connect to it. Check that it hasn't been stopped or terminated
due to a serious error and that there are no broken network
connections.
Check the Client configuration file
If the Server is running, then ensure that the ServerAddress=
setting in the Client configuration file is correct.
“TCP/IP timeout”
Error Code -9296
You get this error if data transfer between Server and Client is
not completed within the connection timeout period. This
might be due to a broken connection or a high volume of
network traffic.
Provide more address information
Large amounts of data are transmitted if search results have
many picklist items. If you specify more name and address
information, the search will be narrower, meaning less data to
return.
94 • Appendix A: Error Codes
QuickAddress Pro for the Web
“TCP/IP socket error”
Error Code -9297
This error appears when the Client has difficulty sending to a
port, possibly because the Server has crashed or because you do
not have authorisation to use the specified port number.
If you think that the Server is running:
Check that the Server hasn’t been stopped or terminated due to
a serious error. Check that there are no broken network
connections. Most importantly, ensure that the Server’s name
and port settings in the configuration file have been correctly
specified.
“Couldn't open TCP/IP connection”
Error Code -9298
You get this error when starting a Client which cannot establish
contact with the Server, either because the Server is not running
or because the Server address and port number have been
incorrectly specified.
If you know that the Server IS NOT running
To prevent this error, you must ensure that the Server is loaded
and running before any Client attempts to connect to it.
If you think that the Server IS running
Check that the Server hasn’t been stopped or terminated due to
a serious error. Check that there are no broken network
connections. Most importantly, ensure that the Server’s name
and port settings in the configuration file have been correctly
specified.
“Couldn't create TCP/IP socket”
Error Code -9299
This error occurs if the TCP/IP port you have specified is already
in use or you don't have permission to use it.
Check if the requested port is available
QuickAddress Pro for the Web
Appendix A: Error Codes • 95
Confirm that the port you have specified is available; if it isn’t,
alter the ServerPort setting in both configuration files to a port
number that is available.
“Data set not present on Server”
Error Code -9300
This error occurs if a DataPlus data set specified in the Client
configuration file is not in the Server configuration file.
Compare the Client and Server configuration files
Make sure that the DataPlus data sets specified in the Client's
configuration file are also in the Server's configuration file. The
Client does not have to use every DataPlus set that is configured
on the Server, but a data set must be on the Server before a
Client can retrieve information from it.
“Unsupported Client/Server protocol version”Error Code -9301
You might get this error if the Client and Server have different
release numbers (i.e. one has been upgraded and the other has
not). You should ring QAS Technical Support on the number at
the front of this manual, quoting the version numbers.
“Server termination requested”
Error Code -9302
The Client has sent a request for the Server to terminate. The
Server will shut down.
“Server address not specified”
Error Code -9303
No ServerAddress setting was found in the Client configuration
file.
Check the setting
Ensure that the ServerAddress= setting in the Client
configuration file exists and is correct.
96 • Appendix A: Error Codes
QuickAddress Pro for the Web
“Server port not specified”
Error Code -9304
No ServerPort setting was found in the Client configuration file.
Check the setting
Ensure that the ServerPort= setting in the Client configuration
file exists and is correct.
“Too much network data for buffer”
Error Code -9305
The Server has attempted to send too much data to the Client, or
vice versa.
“Not an IP address”
Error Code -9306
The IP address is not in the correct 'dotted quad' format – i.e.
four numbers separated by dots (for example: 150.150.100.50).
Correct the formatting in the configuration file
Amend the ServerAddress= setting in the Client's configuration
file to the correct IP number. Alternatively, you can specify a
hostname in this setting instead of an IP address.
“Incorrect client/server protocol”
Error Code -9307
The Client has attempted to communicate with an application
which is not a QuickAddress Server. This might occur if the
Server address and/or port number have been incorrectly
specified.
Check the Client configuration file
Ensure that the ServerAddress= and ServerPort= settings in the
Client configuration file are correct.
QuickAddress Pro for the Web
Appendix A: Error Codes • 97
“Failed to start Network Server as a Windows NT Service”
Error Code -9500
This error indicates that the Server has failed to start. This can
be because there is already a Server running as an NT service.
Alternatively, the Server could fail due to an incorrect
configuration setting, or a missing PAF data file.
Check the Server configuration file
Ensure that the DataDir, ServerPort and ServerAddress settings
are correct. See page 72 for further details of the settings in this
configuration file.
Check the location of the data files
Ensure that the QuickAddress data files are in the location
specified in the DataDir setting.
“Request not recognised by Network Server”Error Code -9501
A Client has sent a request to the Server which was not
recognised.
“Request refused by Network Server”
Error Code -9502
A Client has sent a request to the Server that it refused to service.
This might happen if a server module is not enabled, and a client
attempts to use that module.
Check the ServerModules section in the Server configuration
file
Ensure that the correct modules are enabled. For example, if a
Client configuration file contains settings for DataPlus data sets,
and the DataPlus setting in the Server configuration file is set to
No, this error would be returned.
98 • Appendix A: Error Codes
QuickAddress Pro for the Web
“Network Server failed to perform request”Error Code -9503
The Server failed to service a request from a Client. This might
be due to resource problems with the Server.
QuickAddress Pro for the Web
Appendix A: Error Codes • 99
APPENDIX B: DATAPLUS SETS
This appendix lists the QuickAddress DataPlus data sets available for use with
QuickAddress Pro. The DataPlus sets have been categorised, and are listed by
their four-letter code and a brief description.
GIS – Grid Reference Data
ADDP
Ordnance Survey Address-Point grid reference accurate to
property level
G10M
Grid reference accurate to postcode level, resolution of
10m in Scotland
GRID
Grid reference accurate to postcode level, resolution of
100m
CDPT
Ordnance Survey Code-Point, which provides a National
Grid co-ordinate (a grid reference comprising an Easting and
a Northing value) for a point within each postcode in Great
Britain
Geodemographic Data
ACOR
CACI’s Acorn profiling data
FMOS
Experian’s Mosaic classification by financial status and
behaviour
MOSC
Experian’s Mosaic profiling data
NMOS
Northern Ireland Mosaic codes
SMOS
Scottish Mosaic codes
QuickAddress Pro for the Web
Appendix B: DataPlus Sets • 101
Government/Administration Data
ECPC
European Electoral Regions for each postcode
PCMP
Westminster MP and the political party they represent
PARL
Westminster parliamentary constituency name
LACD
Tier of local government above Ward level– ie. County,
metropolitan or unitary council
CNTY
Local Authority (Shire) County name and code
LEAC
Local Education Authority Codes
NHSC
District Health Authority
WARD
Local Authority Electoral Wards
PAF Related Data
AKEY
Unique Address Key number for each delivery point on PAF
CTRY
UK country
DELV
Number and types of delivery points within a postcode
DPSX
Delivery point suffix codes
HCNT
Number of households sharing a delivery point
MSRT
Mailsort codes
PNRL
All postally non-required localities for each postcode
RCDR
Recoder data of postcode changes
TYPE
Delivery point type - whether address is residential,
organisational or a large user
UDTR
Updater data of PAF changes
WALK
Walksort codes
102 • Appendix B: DataPlus Sets
QuickAddress Pro for the Web
Names Data
DTOB
Attainer’s date of birth
IATT
Any attainers present
IRES
Length of residency data
Media Data
CHN4
Codes and names for Channel 4 broadcasting regions
BARB
British Audience Research Board ITV regions
ISBA
Incorporated Society for British Advertisers (ISBA) ITV
regions
TVCO
ISBA TV company names
RAST
Local radio stations
NEWS
Local newspapers and whether daily, weekly etc.
Utility Management Data
MNUM
M Numbers – gas meter numbers
MNAD
M Addresses – addresses that relate to M Numbers
MPAN
M-Pan Numbers – electricity meter numbers
MPAD
M-Pan Addresses – addresses that relate to M-Pan Numbers
QuickAddress Pro for the Web
Appendix B: DataPlus Sets • 103
APPENDIX C: PRO FOR THE WEB TEST UTILITY
The Pro Test Utility is intended to aid QAS Technical Support in diagnosing any
problems with the Pro installation, without the complications of the Web
Server/Java Virtual Machine environment.
Examples of use include:
If your SystemPrefix= configuration setting is set to “Update”,
searching on “Update:” to verify the counter status.
Searching on a postcode of your choice to verify successful
address retrieval.
Each search will attempt to Open, Search and Close Pro in the same way as it
will be used from inside a Web Server/Java Virtual Machine environment.
Note:
Using this utility will decrement your counter.
QuickAddress Pro for the Web
Appendix C: Pro for the Web Test Utility • 105
INDEX
A
Abbreviate keyword • 77
ActiveX code • 47
ActiveX functions
Address • 40
AddressCount • 39
Close • 33
Counter • 34
DataPlus • 42
DataPlusCount • 41
ErrorLevel • 44
ErrorMessage • 43
Open • 31
Preview • 38
ResultsCount • 37
Search • 35
Address elements • 35, 58
constraining • 36, 59, 81
keyword assignment codes • 75
natural order • 17
searching for specific • 20
Address formatting keywords • 75
Address function • 40
Address popup sample code • 48
AddressCount function • 39
AddressLines keyword • 76
Administration Utility • 27
Asterisk wildcard • 19
C
Capitalise keyword • 77
Client API error codes • 85
Client configuration settings • 75
Client/Server communications error
codes • 92
Close function • 33, 56
QuickAddress Pro for the Web
Configuration files • 31, 54
format • 71
QANSRV.INI • 8, 72
QAPROWEB.INI • 4, 32, 71, 75,
81, 83
Configuration settings
client side • 75
for address formatting • 75
general • 80
server-side • 72
Converting an error code to a text message • 43, 66
Counter
Update Key • 25
updating • 36, 59
Counter function • 34
D
DAT files • 10
Data updates • 27
DataDir keyword • 73
DataPlus • 1, 41
file format • 10
DataPlus function • 42
DataPlus sets
Geodemographic data • 101
Government/Administration data •
102
Grid reference data • 101
Media data • 103
Names data • 103
PAF-related data • 102
Utility management data • 103
DataPlusCount function • 41
DataPlusLines keyword • 80
Datasets keyword • 73
Index • 107
E
I
Error codes • 43
Client API • 85
client/server communications • 92
qaerr_BADDIR • 90
qaerr_BADDRIVE • 89
qaerr_BADINIFILE • 90
qaerr_INVALIDAREA • 91
qaerr_NOMEMORY • 89
qaerr_NONRAPIDFILE • 91
qaerr_NOSPEC • 91
qaerr_NOTDEFINED • 90
severity • 44
ErrorLevel function • 44, 67
ErrorMessage function • 43, 66
Eval • 7
In process sample code • 47
INF files • 10
INI files • 31, 54, 71
Installation
files installed • 10
system requirements • 7
Intelligent postcode parsing • 20
Introduction • 1
F
FieldEnd keyword • 78
File
Configuration (.ini) • 31, 54, 71
DAT • 10
INF • 10
Files installed
client-side • 11
data • 10
sample code • 12
server-side • 10
Finding the severity of an error • 44, 67
Format of search results • 22
Fuzzy searching • 17
G
GetAddressCount function • 62
GetAddressLine function • 63
GetCounter function • 57
GetDataPlusCount function • 64
GetDataPlusLine function • 65
GetPreview function • 61
GetResultCount function • 60
Getting started • 3
108 • Index
J
Java class
COM.qas.QAProWeb.QAProWeb
• 52
Java functions
Close • 56
ErrorLevel • 67
ErrorMessage • 66
GetAddressCount • 62
GetAddressLine • 63
GetCounter • 57
GetDataPlusCount • 64
GetDataPlusLine • 65
GetPreview • 61
GetResultCount • 60
Open • 54
Search • 58
K
Keyword
Abbreviate • 77
AddressLines • 76
Capitalise • 77
DataDir • 73
DataPlusLines • 80
Datasets • 73
FieldEnd • 78
LineEnd • 79
LineN • 76
LinePad • 79
LogErrors • 82
QuickAddress Pro for the Web
LogFile • 82
LogTrace • 82
MaxPostcodes • 74
NoCounty • 79
PostcodeFormat • 77
ServerAddress • 73, 75
ServerPort • 73, 75
Keyword searching • 20
L
Limiting searches • 59
LineEnd keyword • 79
LineN keyword • 76
LinePad keyword • 79
LogErrors keyword • 82
LogFile keyword • 82
LogTrace keyword • 82
M
MaxPostcodes keyword • 74
Multithreading • 51
N
Network communication errors • 92
Bad IP number format • 92
Couldn’t bind TCP/IP socket • 93
Couldn’t create TCP/IP socket • 95
Couldn’t listen to TCP/IP socket •
93
Couldn’t open TCP/IP connection •
95
Data set not present on Server • 96
Failed to start server as an NT service • 98
Incorrect client/server protocol • 97
Network server failed to perform
request • 99
Not an IP address • 97
Request not recognised by server •
98
QuickAddress Pro for the Web
Request refused by server • 98
Server address not specified • 96
Server port not specified • 97
Server termination requested • 96
TCP/IP accept failure • 92
TCP/IP Hostname lookup failed •
94
TCP/IP socket error • 95
TCP/IP timeout • 94
Too much network data for buffer •
97
Unsupported protocol version • 96
NoCounty keyword • 79
O
Open function • 31, 54
P
Password • 7
Picklists • 36, 59
PostcodeFormat keyword • 77
Preview function • 38
Pseudocode
ActiveX functions • 29
Java functions • 51
Java Servlet • 69
Q
QADefault • 32, 71
qaerr_*
BADDIR • 90
BADDRIVE • 89
BADINIFILE • 90
INVALIDAREA • 91
NOMEMORY • 89
NONRAPIDFILE • 91
NOSPEC • 91
NOTDEFINED • 90
QANSRV.INI • 8, 72
QAProWeb class
Index • 109
definition • 52
QAPROWEB.INI • 4, 32, 71, 75, 81, 83
Question mark wildcard • 18
R
Results
format • 22
ResultsCount function • 37
S
Sample code • 1
ActiveX • 47
address popup • 48
in process • 47
installation of • 12
Search function • 35, 58
Searching
fastest method • 17
for address text • 19
for postcodes • 18
format of results • 22
fuzzy • 17
intelligent postcode parsing • 20
keyword • 20
wildcard • 18
Serial Number • 7
110 • Index
Server as NT Service
removing • 9
stopping • 9
troubleshooting • 8
Server configuration settings • 72
ServerAddress keyword • 73, 75
ServerPort keyword • 73, 75
Servlet
pseudocode • 69
Stopping the server • 9
System searches • 36
T
Timeout • 36
U
Update Key • 25
Updating your data • 27
Utility
Pro for the Web Administration •
27
W
Wildcard searching • 18, 36, 59
QuickAddress Pro for the Web