Table of Contents. Creating multiple instances of the RAT Object's 'Dtx' Class... 10

(1)

- 1 -

About Method ... 13 AmasDetails Property ... 14 AllocateRequiredInstances Method ... 16 Close Method ... 18 ControlVersion Property ... 19 ConvertErrorCode Method ... 20 ConvertNzErrorCode Method ... 22 CreateProcess Method ... 24 DisposeOfProcess Method ... 26 EngineVersion Property ... 28 ExtractResultField Property ... 29 GenerateBarcode37 Method ... 32 GenerateBarcode52 Method ... 33 GenerateBarcode67 Method ... 35 NzPafVersion Property ... 37 Open Method ... 38 PafVersion Property ... 39 ReturnLastCriticalErrorMessage Property ... 40 RolloutMangment_InstallUpdate Method ... 41 RolloutManagement_NewerVersionAvailable Property ... 42 SearchAddressLine Method ... 44 SearchAddressLineAMAS Method ... 46 SearchFirstName Method ... 49 SearchLastName Method ... 51 SearchLocality Method ... 53 SearchNzAddressLine Method ... 55 SearchNzPlace Method ... 57 SearchNzStreetName Method ... 59 SearchNzStreetNumber Method ... 61 SearchNzUnitNumber Method ... 63 SearchPostcode Method ... 65 SearchRat Method ... 67 SearchRatLoaded Method ... 69 SearchRatPromptCompanyName Property ... 71 SearchRatPromptPersonName Property ... 73 SearchShortKey Method ... 75 SearchStreetName Method... 77 SearchStreetNumber Method ... 79 SearchTitle Method ... 81

(2)

- 2 -

SearchUnitNumber Method... 83

Sample VB Code ...85

Sample Description ... 85

Sample code ... 85

Sample ASP code ...86

Sample code ... 86

Address Entry Page ... 86

Process and Display Page ... 87

Sample Server Side VB.Net code ...92

Sample code ... 92

Sample Server Side C#.Net code ...94

Sample code ... 94

Client Side VB Script Example ...96

Sample Code ... 96

Intelli-Search API Extension Control Description ...99

Intelli-Search API Extension Properties & Method ...100

IntelliSearchAddressLine Method ... 100

SearchAddressLineAdvanced Method ... 102

Twins Pro API Extension Control Description...104

Twins Pro API Extension Properties & Method ...105

CreateMatchMethods Method ... 105

EraseDataFields Method ... 107

ExtractMatchMethods Property ... 109

LoadDataField Property ... 111

OptionSetting Property ... 113

Twins Pro API Extension Sample VB Code ...115

Sample code ... 115

Twins Pro API Extension Sample Query Code ...117

Sample Description 1 ... 117

Sample SQL code ... 117

Sample Microsoft Access query ... 117

Sample code ... 118

Sample code ... 119

Proximity API Extension Control Description ...120

Proximity API Extension Properties & Method ...121

CalculateDistance Method ... 121

Appendix 1- Return Codes and Descriptions ...123

Data Changes ... 123

(3)

- 3 -

DataTools Development Suite

Introduction

DataTools technology can be integrated into your business systems in many different ways, one of these ways is by using the DataTools programmers API to easily build the technology into your system exactly how and where you need it.

This book covers most of the development tools available and their respective functions, it also includes overviews for non-programmer project managers who need to understand the concept of how this technology would fit into their business systems.

The DataTools development suite provides your application with tried and tested industrial strength data quality, saving you the thousands of hours of specialist programming in complex computer languages such as C and C++, and allowing you to complete your project on time.

Technology Interface

All programming interfaces are provided via ActiveX control technology. ActiveX controls adhere to the Component Object Model (COM) and are recognised as an industry standard and a superior way of integrating third party technologies.

ActiveX components are Microsoft WIN32 applications and will run on Windows 95/98/ME/2000/NT/XP/Vista and other compatible Windows 32 bit & 64 bit platforms.

Licensing System

Basic licensing is handled using two different methods; PC Seat based, intranet named user based or Public Website Licensing.

To extend the functionality of the API for a site with PC Seat based, intranet named user based or Public Website Licensing to include additional technologies available, an API extension license is provided per site. The number of PC seats, named intranet users or Public Website licenses available for that site are still governed by the Base API licensing.

Technologies Available

Base Rapid API included with PC Seat based, intranet named user based or Public Website Licensing.

- Includes the Rapid API with either: Australia Address validation

(AMAS approved for both Rapid & Batch DPID allocation) and/or

New Zealand Address Validation

(Using the New Zealand Postal Address File including postcode appending). - Also includes actual Rapid Addressing Tool Application licenses.

- Includes name type assist API.

Intelli-Search API Extension

(Only available for the Australian version of the Base API).

- Extends address matching functionality of existing PC Seat based, intranet named user based or Public Website License.

(4)

- 4 -

Twins III Corporate and Pro Record Matching API Extensions.

- Extends functionality existing PC Seat based, intranet named user based or Public Website License.

- Includes Twins III Corporate or Pro and custom matching methods key generation.

Proximity API Extension

(Only available for the Australian version of the Base API).

- Extends the functionality of existing PC Seat based, intranet named user based or Public Website License.

- Allows you to compare two Australian locations and determine the distance between them.

Base Rapid API Overview

The Base Rapid API allows programmers to easily build sophisticated rapid address capture into their applications.

Just like the Rapid Addressing Tool Application, which can be integrated into business systems in many different ways without programming, the Base Rapid API can be programmed into your software in a variety of ways that suits the cosmetic and functional goals of your application.

Generally there are two main options to achieving integration, these are:

Use the API to call up and control the Rapid Addressing Tool Application

interface:

Simply call a function to open the Rapid Addressing Tool Application interface, and when the user has finished entering an address, focus will be returned to the developers application and all captured data is made available.

The main advantages of this are:

 Minimal programming requirements.

 Using the tried and tested Rapid Addressing Tool interface requires no testing.

 Access to results via functions gives greater control over scripted results transfer.

Build your own rapid interface using the easy prompt by prompt function

calls:

(5)

- 5 - Prompt by prompt function calls are available for all three address capture methods found in the Rapid Addressing Tool Application, use or combine these to provide your own unique rapid capture system tailored for your users.

The main advantages of this are:

 Complete step-by-step control over the entire data capturing process.

 Integration transparency and cosmetic control.

 Ability to develop hybrid address capturing systems.

Batch Address Validation

Now included in the Australia version of the base Rapid API are functions allowing you to access the batch address validation functions that are AMAS approved specifically for batch validation, giving you complete access to the same engine as used within Twins.

Data Passed to API Data Returned from API

Address Line Suburb State Post

code Dt Address Line Dt Locality Dt State Dt Post code Dt Sort Plan No Dt DPID Dt Match Type 27 Hunter St HARRIS PARK NSW 2150 27 Hunter St PARRAMATTA NSW 2150 006 44304924 Correct 102 Elisabeth Str MELBOURNE VIC 3000 102 Elizabeth St MELBOURNE VIC 3000 022 95215696 Correct 1/3 Hassal Street HAMILTON SOUTH N.S.W 2303 1/3 Hassall St HAMILTON SOUTH NSW 2303 017 43965806 Correct 15B Glenalvon Dr SA 5159 15B Glenalvon Dr FLAGSTAFF HILL SA 5159 047 39815841 Correct 47 Wellington Road Unit 2 BRISBANE QLD 4000 Unit 2 47 Wellington St BRISBANE QLD 4000 035 61298771 Correct

(6)

- 6 -

Intelli-Search API Extension Overview

The Intelli-Search API Extension adds functions to the Australia version of the Base Rapid API that allows programmers to easily get access to the important DataTools Intelli-Search technology.

Intelli-Search

Intelli-search is the technology that has set the height bar for other repair assist tools to beat by providing super intelligent suggestions that will increase your DPID hit rate and provide your application with a state-of-the-art user-assisted address correction system.

This Intelli-Search engine is used in the Rapid Addressing Tool Application and also in the Interactive Address Repair Wizard that is part of the Twins Advanced Address Repair Toolkit component.

(7)

- 7 -

Twins Pro API Extension Overview

The Twins API Extension adds functions to the Base API that allows programmers to easily get access to the sophisticated matching technology found in Twins.

This amazing technology makes it easy to facilitate important business advantages such as:

 Intelligent data entry screens.

 Faster and more efficient client look-up.

 On-line duplicate validation to avoid and prevent duplicate records before they occur.

 Automated intelligent data warehousing where multiple databases are continually merged to provide a single view of customers for CRM.

Through a few lines of code a programmer simply passes the name and address and a binary string known as a Match Key is then returned. This key when grouped or sorted together in the programmers application will identify duplicate records as show below:

Title First Name Last

Name Address Line 1 Suburb State

Post

code Dt Person and Address Matches

Miss Alexandra Pierson 20 Southern Cross Arc Unit 10 RUNDLE MALL SA ®µ´´·‹Š‰ˆ‡†µµ²©¯•~Œ‰{zyx‰ƒ‚Ÿ© Ms A Pearson 20 Southern Cross Arcade ADELADE S.A. ®µ´´·‹Š‰ˆ‡†µµ²©¯•~Œ‰{zyx‰ƒ‚Ÿ© Ms Alex Peirsun Darling Park 20 Southern Cross Arc ADELAIDE SA ®µ´´·‹Š‰ˆ‡†µµ²-©¯•~Œ‰{zyx‰ƒ‚Ÿ© Miss Alexandra Pierson 20 Southern Cross Arc (next To Darling Park) RUNDLE MALL SA 5000 ®µ´´·‹Š‰ˆ‡†µµ²©¯•~Œ‰{zyx‰ƒ‚Ÿ©

A David Attention: Andrew 92 Crimea Street PARRAMATTA NSW 2150 ®°±¶Œ‹Š‰ˆ‡†³‚€•~“‹{zyx†„‡Ÿ© Mr Andrew David 92 Krimea Street PARRAMATTA NSW 2150 ®°±¶Œ‹Š‰ˆ‡†³‚€•~“‹{zyx†„‡Ÿ©

This makes it easy to identify duplicates when and where ever you need simply by adding a field to your database and using the Twins III API.

A Match Key is available for each of the super intelligent matching methods found in Twins III Pro, or any of the specialised custom match methods that you have been supplied with. The Match Keys provided by the Twins Pro API extension are compatible with the keys provided in the Twins III Pro Application and Rapid Addressing Tool Applications, and can be used interchangeably to match records.

The next page contains overview diagrams, for further information on the Twins III Matching Methods see "Twins Benefits and Features Guide; Matching Methods".

Pass all available details to the Twins API .

Miss Alexandra Pierson, 20 Southern Cross Arc Unit 1, RUNDLE MALL SA

Receive back Match Keys from the Twins API . ®¼½½·‹Š‰ˆ‡†µµ²©¯•~Œ‰{z yx‰ƒ‚Ÿ©

(8)

- 8 - The first flow chart that shows one example of how the Twins API can be placed within a typical contact database system to facilitate fast, intelligent matching across a large volume of records.

The flow chart below shows how the Twins API can be used to provide automated upon import duplicate maintenance of a central CRM / Marketing / Data Warehouse.

A record is entered via your application

Display suspect duplicate records for the user to select

the appropriate record if it already exists. Match key for each of the methods required. Name, Address and

other details. These details are passed to

the Twins Active-X control with the Match

Keys being returned.

Add the new record to your database.

Save the match keys for this record...

Has a match key been found in the existing database?

No

Go to the existing record. Did the user find

that the record already exists.

No Yes

Yes

Active-X Control/DLL

Process records from different databases using the Twins Active X control and compare keys against

a central database .

A

B

C

(9)

- 9 -

Proximity API Extension Overview

The Proximity extension allows you to compare two Australian locations and determine the distance between them.

Identifying the nearest outlets and the approximate distance of the closest outlets for any given customer upon inquiring is the obvious use of this.

This tool acts in a similar way to the Twins III Proximity Wizard extension, but allows you to incorporate the technology into your own systems.

Another example of using the proximity extension is finding the nearest outlets or sites for each record in a list, and transferring details such as their contact number, sales managers name and other details for a personalised mail merge invite to the store.

Another is having a one record list such as a conference event address, and then use the proximity wizard on a prospect list to learn the approximate distance to the event for each prospect. These examples are just a few of the ways this extension add-on can be applied. The Proximity extension uses the centroid (the centre points) of localities to determine approximate distance at a sub-postcode locality level. This means that the same locality may be given a distance of 0 where as a neighbouring suburb in the same postcode may have a distance of 1.5km.

This level of accuracy is very practical for the purposes outlined, if however you are seeking street and street number level accuracy then take a look at the Geo-Coding extension.

In the diagram below graphically shows the effect of the proximity extension when run through two lists.

(10)

- 10 -

DataTools API

and Instancing

When do you need to worry about instancing?

It is necessary to take instancing into consideration where you have an application that requires the processing of multiple transactions simultaneously, for example a web based application.

The RAT Active-X control comes with two methods for handling instancing.

Creating multiple instances of the RAT Object's 'Dt' Class

When you create an instance of the RAT Dt class you are creating a single instance of the object.

Dim obRat As Object

Set obRat = CreateObject("DataTools_DtRat.Dt")

You are able to create multiple instances of the RAT Active-X object by defining multiple objects.

Dim obRat1 As Object Dim obRat2 As Object

Set obRat1 = CreateObject("DataTools_DtRat.Dt") Set obRat2 = CreateObject("DataTools_DtRat.Dt")

In this example obRat1 and obRat2 are two seprate instances. Any searches processed within one instance will not affect the results stored in the other instance.

Another version of this instancing would be were you have the object dimension locally

within a procedure / web page and two users call the procedure simultaneously. Because the object is dimensioned locally within the procedure / web page multiple instances of the object would be created. However if the object was dimensioned globally both calls of the

procedure / web page would be sharing the same instance, this would result in one call overwriting the results of a previous call.

Problems with creating multiple instances of the 'Dt' Class

It was found that with some development environments .Net being one of them that even if you defined and created multiple instances of the Active-X control all instances shared the same allocation of memory meaning results of one call were overwriting the results of a previous call.

To overcome this problem DataTools introduced another version of the object that would control multiple instancing within the object, this version of the object is know as the 'Dtx' class.

Creating multiple instances of the RAT Object's 'Dtx' Class

With the 'Dtx' class instead of dimensioning and creating multiple objects within your development environment as you would with the 'Dt' class with 'Dtx' class you only create one instance within your development environment and request instances from the object.

(11)

- 11 - The object would be defined globally and the creating, opening and allocation of required instances would occur once at the application startup.

Public RatApiDtx As Object

Set RatApiDtx = CreateObject("DataTools_DtRat.Dtx") Status = RatApiDtx.DtxOpen()

Status = RatApiDtx.DtxAllocateRequiredInstances(2)

When an instance of the object is required you would simply create the instance using the object's Create Process method and pass the Instance ID through all other methods you would like to process for that instance. After you are done with that instance you would dispose of it making it available for another call.

InstanceOne = RatApiDtx.DtxCreateProcess() RatApiDtx.DtxSearchPostcode(InstanceOne, "2196") . . Status = RatApiDtx.DtxDisposeOfProcess(InstanceOne) Remarks

(12)

- 12 -

Base Rapid API

Control Description

The RAT Active-X control allows the use of the DataTools rapid addressing technology within third party applications.

File Name

DtRatApi.exe or DtRatApi.dll

Remarks

The RAT Active-X control supports properties & methods that you can use to send name and address data to the control and in return retrieve matching records from the Postal Address File (PAF).

The RAT Active-X control comes as an in-process component (DLL) or an out-of-process component (EXE). The functionality of both controls are similar and choice depends on the use and development environments. For example Microsoft Access allows you to integrate the DtRatApi.exe but has a limitation that does not allow you to integrate the DtRatApi.dll.

Australia Version of the Base API

Note: Under the guidelines of Australia Post the 'DtSearchAddressLineAMAS' method is the

only method that should be used for automatic batch allocation of DPIDs, all other functions of the Australia Base API are classified under Australia Post's „Rapid‟ guidelines and should only be used for user interactive address validation.

Rapid Product Information

AMAS Company Name: DataTools Pty Ltd

AMAS Product Name: DataTools Rapid Addressing Engine

Batch Product Information

AMAS Company Name: DataTools Pty Ltd

AMAS Product Name: DataTools Batch Addressing Engine

"DataTools Batch Addressing Engine and the DataTools Rapid Addressing Engine incorporating the Acxiom PAFlink has been approved by Australia Post in accordance with the Address Matching Approval System (AMAS)."

Australia Post‟s Rapid software definition: “Process of manually entering addresses to obtain an automatic match with the PAF and returning a standardised address and associated DPID in accordance with the AMAS rules”

Australia Post‟s Batch software definition: "The automatic matching of a given target address and returning the one corresponding DPID and its correctly presented address in accordance with the AMAS rules without any manual intervention or selection within the AMAS process."

(13)

- 13 -

Base Rapid API

Control Properties & Method

About Method

You can use the DtAbout method to display an information dialog box about the RAT Active-X control, including its version and copyright information.

Available

 Dt  Dtx  Australian version  New Zealand version

Syntax

controlname.DtAbout

Setting

The DtAbout method uses the following settings.

Argument Description

controlname The name of the RAT Active-X control object.

Visual Basic Example (Code available on CD at “\Sample Code\DtAbout.bas”)

Public Sub main()

Dim obRat As Object Dim Status As Boolean

Set obRat = CreateObject("DataTools_DtRat.Dt") Status = obRat.DtOpen

If Status Then

MsgBox "Engine Opened Successfully", vbInformation Else

MsgBox "Error Opening Engine", vbCritical End If

obRat.DtAbout End Sub

(14)

- 14 -

AmasDetails Property

You can use the DtAmasDetails property to retrieve AMAS certificate details required for mail lodgements

Available

 Dt  Dtx  Australian version  New Zealand version

Syntax

AmasDetail = controlname.DtAmasDetails(DetailType)

Equivalent Dtx method

AmasDetail = controlname.DtxAmasDetails(DetailType)

Setting

The AmasDetails property uses the following settings.

AmasDetail Returns a string expression from the requested detail type. „INCORRECT DETAIL TYPE‟ will be returned for an invalid detail type. (Note: String of “9999” is returned if not

available on installed version) DetailType Required. A valid detail type name.

The DetailType argument has these settings:

Value Description

Company_Name The licensed AMAS company name eg. 'DataTools Pty Ltd'

Product_Name The licensed AMAS product name

eg. 'DataTools Batch Addressing Engine and DataTools Rapid Addressing Engine'

Ticket_Number The AMAS certificate ticket number eg. '2003-A0479 and 2003-A0478'

Remarks

The AMAS certificate details will change from year to year. By using this property you can be sure that you are providing the correct AMAS license and certificate details to the end-user. These details are required by the end-user for mail lodgment.

Visual Basic Example

(Code available on CD at “\Sample Code\DtAmasDetails.bas”) Public Sub main()

(15)

- 15 - Dim obRat As Object

Dim strAmasCompanyName As String Dim strAmasProductName As String Dim strAmasTicketNumber As String

strAmasCompanyName = obRat.DtAmasDetails("Company_Name") strAmasProductName = obRat.DtAmasDetails("Product_Name") strAmasTicketNumber = obRat.DtAmasDetails("Ticket_Number")

Debug.Print "AMAS Licensed Company Name : " & strAmasCompanyName Debug.Print "AMAS Licensed Product Name : " & strAmasProductName Debug.Print "AMAS Certificate Ticket Number : " & strAmasTicketNumber

(16)

- 16 -

AllocateRequiredInstances Method

When using the multi-instance Dtx object you can use the DtxAllocateRequiredInstances method to set the maximum number of instances you would like to run simultaneously. If you are using the Dtx object and you don't set the maximum instances required 250 simultaneous instances is set by default.

Available

 Dt  Dtx  Australian version  New Zealand version

Syntax

Status = controlname.DtxAllocateRequiredInstances(NumberOfInstancesRequired)

Setting

The DtxAllocateRequiredInstances method uses the following settings.

NumberOfInstancesRequired Required. A Long value which is the maximum number of instances you would like to run simultaneously.

Status Returns a Boolean expression of the status.

True means successfully, False means an error has occurred.

Remarks

The Open method sets the number of instances required to 250 by default. Use the

DtxAllocateRequiredInstances method directly after the Open method to change the number of instance required from the default. Calling the DtxAllocateRequiredInstances method will dispose of any previously create instances.

Visual Basic Example

(Code available on CD at “\Sample Code\DtxAllocateRequiredInstances.bas”) Public Sub main()

Dim InstanceOne As Long Dim InstanceTwo As Long

Dim MatchesOne As Long Dim MatchesTwo As Long

Dim ErrorMessage As String

Dim RatApiDtx As Object

(17)

- 17 - If Not RatApiDtx.DtxOpen() Then

ErrorMessage = RatApiDtx.DtxReturnLastCriticalErrorMessage Exit Sub

End If

If Not RatApiDtx.DtxAllocateRequiredInstances(2) Then

End If

InstanceOne = RatApiDtx.DtxCreateProcess() InstanceTwo = RatApiDtx.DtxCreateProcess()

MatchesOne = RatApiDtx.DtxSearchAddressLineAMAS(InstanceOne, "7 King St", "PAKENHAM VIC 3810")

MatchesTwo = RatApiDtx.DtxSearchAddressLineAMAS(InstanceTwo, "1 Ulster Ct", "BRAY PARK QLD 4500")

If Not RatApiDtx.DtxDisposeOfProcess(InstanceOne) Then

End If

If Not RatApiDtx.DtxDisposeOfProcess(InstanceTwo) Then

End If

If Not RatApiDtx.DtxClose() Then

End If End Sub

(18)

- 18 -

Close Method

You will need to use the DtClose method to close the RAT Engine after you have finished using the RAT Active-X control.

Available

 Dt  Dtx  Australian version  New Zealand version

Syntax

Status = controlname.DtClose

Status = controlname.DtxClose

Setting

The DtClose method uses the following settings.

Status Returns a Boolean expression of the engine's close status. True means engine closed successfully, False means error in closing engine.

Visual Basic Example

(Code available on CD at “\Sample Code\DtClose.bas”) Public Sub main()

'Open Engine

Status = obRat.DtOpen If Not Status Then

MsgBox "Error Opening Engine", vbCritical Exit Sub End If 'Close Engine Status = obRat.DtClose If Status Then

MsgBox "Engine Closed Successfully", vbInformation Else

MsgBox "Error Closing Engine", vbCritical End If

(19)

- 19 -

ControlVersion Property

You can use the DtControlVersion property to retrieve the RAT Active-X control version number.

Available

Syntax

ControlVersionNumber = controlname.DtControlVersion

ControlVersionNumber = controlname.DtxControlVersion

Setting

The DtControlVersion property uses the following settings.

controlname The name of the RAT Active-X control object. ControlVersionNumber Returns a string expression which is the RAT

Active-X control version number

Visual Basic Example (Code available on CD at “\Sample Code\DtControlVersion.bas”)

Public Sub main()

Dim obRat As Object Dim strVersion As String

Set obRat = CreateObject("DataTools_DtRat.Dt") strVersion = obRat.DtControlVersion

MsgBox "RAT control version :" & strVersion, vbInformation End Sub

(20)

- 20 -

ConvertErrorCode Method

You can use the DtConvertErrorCode method to retrieve error description or error codes returned by the ' DtSearchAddressLineAMAS' function.

Available

Syntax

ErrorDescription = controlname.DtConvertErrorCode(ErrorCode)

ErrorDescription = controlname.DtxConvertErrorCode(ErrorCode)

Setting

The DtConvertErrorCode method uses the following settings.

ErrorCode Required. An Integer value of the error code for why an address didn‟t match.

ErrorDescription Returns a string value which is a meaningful description of the error code. (Note: String of “9999” is returned if not available on installed version)

Visual Basic Example (Code available on CD at “\Sample

Code\DtConvertErrorCode.bas”)

Public Sub main()

Dim obRat As Object

Dim strAddressLine As String Dim strLocality As String Dim strState As String Dim strPostcode As String

Dim strErrorDescription As String Dim intErrorCode As Integer

'Open Engine

MsgBox "Error Opening Engine", vbCritical Exit Sub

End If

(21)

- 21 - "Church St", "HARRIS PARK NSW 2150")

If intErrorCode = 0 Then strAddressLine = obRat.DtExtractResultField("Address_Line", 1) strLocality = obRat.DtExtractResultField("Locality", 1) strState = obRat.DtExtractResultField("State", 1) strPostcode = obRat.DtExtractResultField("Postcode", 1) Debug.Print strAddressLine

Debug.Print strLocality & " " & strState & " " & strPostcode Else strErrorDescription = obRat.DtConvertErrorCode(intErrorCode) Debug.Print strErrorDescription End If 'Close Engine Status = obRat.DtClose If Not Status Then

(22)

- 22 -

ConvertNzErrorCode Method

You can use the DtConvertNzErrorCode method to retrieve error description or error codes returned by the „DtSearchNzAddressLine‟ function.

Available

 Dt  Dtx  Australian version  New Zealand version

Syntax

ErrorDescription = controlname.DtConvertNzErrorCode(ErrorCode)

Setting

The DtConvertNzErrorCode method uses the following settings.

ErrorCode Required. An Integer value of the error code for why an address didn‟t match.

ErrorDescription Returns a string value which is a meaningful description of the error code. (Note: String of “9999” is returned if not available on installed version)

Visual Basic Example (Code available on CD at “\Sample

Code\DtConvertErrorCode.bas”)

Public Sub main()

Dim strAddressLine1 As String Dim strAddressLine2 As String Dim strSuburb As String

Dim strCity As String Dim strPostcode As String Dim intResultCode As Integer Dim intResultDescription As String Dim i As Integer

'Open Engine

(23)

- 23 - End If

intResultCode = obRat.DtSearchNzAddressLine("Unit 100 216 Queens Rd", "Panmure Auckland 1072") If intResultCode = 40 Then strAddressLine1 = obRat.DtExtractResultField("Building_Name", 1) strAddressLine2 = obRat.DtExtractResultField("Address_Line", 1) strSuburb = obRat.DtExtractResultField("Locality", 1) strCity = obRat.DtExtractResultField("State", 1) strPostcode = obRat.DtExtractResultField("Postcode", 1)

Debug.Print strAddressLine1 & ", " & strAddressLine2 & ", " & strSuburb & ", " & strCity & " , " & strPostcode

End If

Debug.Print "Result Code : " & intResultCode

intResultDescription = obRat.DtConvertNzErrorCode(intResultCode) Debug.Print "Result Description : " & intResultDescription

'Close Engine

Status = obRat.DtClose If Not Status Then

(24)

- 24 -

CreateProcess Method

When using the multi-instance Dtx object you will need to use the DtxCreateProcess method to create a new instance.

Available

Syntax

InstanceID = controlname.DtxCreateProcess()

Setting

The DtxCreateProcess method uses the following settings.

InstanceID Returns a Long value that is the ID given to the process that was created.

If 0 is returned there are no more instances available.

Visual Basic Example

(Code available on CD at “\Sample Code\DtxCreateProcess.bas”) Public Sub main()

Set RatApiDtx = CreateObject("DataTools_DtRat.Dtx") If Not RatApiDtx.DtxOpen() Then

End If

(25)

- 25 - InstanceOne = RatApiDtx.DtxCreateProcess()

InstanceTwo = RatApiDtx.DtxCreateProcess()

If Not RatApiDtx.DtxDisposeOfProcess(InstanceOne) Then

End If

If Not RatApiDtx.DtxDisposeOfProcess(InstanceTwo) Then

End If

End If End Sub

(26)

- 26 -

DisposeOfProcess Method

When using the multi-instance Dtx object you will need to use the DtxDisposeOfProcess method to dispose of an instance that is no longer necessary making it available to be used later on.

Available

Syntax

Status = controlname.DtxDisposeOfProcess(InstanceID)

Setting

The DtxDisposeOfProcess method uses the following settings.

InstanceID Required. A Long value that is the ID of the instance you wish to dispose of.

Status Returns a Boolean expression of the status.

True means successfully, False means an error has occurred.

Visual Basic Example

(Code available on CD at “\Sample Code\DtxDisposeOfProcess.bas”) Public Sub main()

End If

(27)

- 27 - Exit Sub

End If

InstanceOne = RatApiDtx.DtxCreateProcess() InstanceTwo = RatApiDtx.DtxCreateProcess()

If Not RatApiDtx.DtxDisposeOfProcess(InstanceOne) Then ErrorMessage = RatApiDtx.DtxReturnLastCriticalErrorMessage Exit Sub

End If

If Not RatApiDtx.DtxDisposeOfProcess(InstanceTwo) Then ErrorMessage = RatApiDtx.DtxReturnLastCriticalErrorMessage Exit Sub

End If

End If End Sub

(28)

- 28 -

EngineVersion Property

You can use the DtEngineVersion property to retrieve the Australia PAF Engine version number.

Available

Syntax

EngineVersionNumber = controlname.DtEngineVersion

EngineVersionNumber = controlname.DtxEngineVersion

Setting

The DtEngineVersion property uses the following settings.

controlname The name of the RAT Active-X control object. EngineVersionNumber Returns a string expression which is the parser

engine version number. (Note: String of “9999” is returned if not available on installed version)

Visual Basic Example (Code available on CD at “\Sample Code\DtEngineVersion.bas”)

Public Sub main()

Set obRat = CreateObject("DataTools_DtRat.Dt") strVersion = obRat.DtEngineVersion

MsgBox "Parser engine version :" & strVersion, vbInformation End Sub

(29)

- 29 -

ExtractResultField Property

You can use the DtExtractResultField property to retrieve results from the last search.

Available

Syntax

FieldData = controlname.DtExtractResultField(ExtractFieldName, ResultNumber)

FieldData = controlname.DtxExtractResultField(Instance, ExtractFieldName,

ResultNumber)

Setting

The DtExtractResultField property uses the following settings.

FieldData Returns a string expression from the requested field name and result number. „INCORRECT FIELD NAME‟ will be returned for an invalid extract field name.

ExtractFieldName Required. A valid field name.

ResultNumber Required. An integer value from 1 to the number of results found from the last search.

The ExtractFieldName argument has these settings:

Address_Line Address Line eg. 'Level 5 200 Smith St'

Actual_Keystrokes Actual key strokes used by the user entering the address into the SearchRat screen.

Barcode Australia Post's 4-State barcode

Building_Name Building or property name for Australian Addresses / Pre-Address Line for New Zealand Addresses which included unit details aswell as property name

DPID Delivery Point ID

First_Name Person's first name Last_Name Person's last name

Company_Name Company or business name Level_Number Level number eg. '1' in Level 1 Level_Type Level type eg. Level, Floor

Locality Locality, Suburb or Town for Australian Addresses / Suburb, Lobby or RD for New Zealand Addresses

Lot_Number Property's allotment number

(30)

- 30 - Post_Box_Number_Prefix Post box number prefix eg. 'R' in PO Box R192

Post_Box_Number_Suffix Post box number suffix eg. 'SS' in GPO Box 3702SS Post_Box_Type Post box type eg. 'PO Box'

Postcode Postcode

Sort_Plan Barcode Sort Plan Number

State State eg. NSW, VIC for Australia Addresses / Town, City or Mailtown for New Zealand Addresses

Street_Name Street name

Street_Number_1 Property's street number 1

Street_Number_Suffix_1 Street number suffix for street number 1 eg. 'B' in 1B Street_Number_2 Property's street number 2

Street_Number_Suffix_2 Street number suffix for street number 2 eg. 'B' in 1B Street_Type Street type eg. 'St', 'Rd'

Street_Type_Suffix Street type suffix eg. Smith St 'N' Title Person's title eg. Mr, Mrs..

Unit_Number Unit number

Unit_Number_Suffix Unit number suffix eg. 'B' in Unit 1B Unit_Type Unit type eg. Shop, Apt

Would_Be_Keystrokes Would be key strokes used by the user entering the address into the SearchRat screen.

Field_Changes Returns 3 character codes of those fields that address matching has changed from source data to result data.

Group_DID Returns either a Yes or No. Yes means the record could not be matched against a DPID but instead it was matched against a DID, an identifier to a higher level eg. street level or locality level. Only available for Australia Addresses.

Alt_Postcode Alternative Postcode

Alt_Locality Alternative Locality/Suburb/Town Alt_Street_Name Alternative Street name

Alt_Street_Type Alternative Street type eg. 'St', 'Rd' Alt_Street_Type_Suffix Alternative Street type suffix Alt_Street_Name_line Alternative Street name line

Remarks

When building an application that searches for addresses using a drill-down search such as the one demonstrated in the RAT application results extracted from each level search are then used for each of the searches performed at the next level.

For example, if the first level search was a postcode search you would then have to extract the resultant locality, state and postcode to load into the next level street name search. After you have found the correct street name you would then have to extract the resultant street name, street type, street type suffix, postal box type, locality, state and postcode to load into the next level street number search.

Visual Basic Example

(Code available on CD at “\Sample Code\DtExtractResultField.bas”)

Public Sub main() Dim obRat As Object

(31)

- 31 - Dim strAddressLine As String

Dim strLocality As String Dim strState As String Dim strPostcode As String

Dim intNumberOfResultsFound As Integer Dim intCurrentResult As Integer

Dim i As Integer

'Open Engine

End If

'Search for address line

intNumberOfResultsFound = obRat.DtSearchAddressLine( _ "1 Hilda Ave", " NEWTON SA 5074")

For i = 1 To intNumberOfResultsFound strAddressLine = obRat.DtExtractResultField("Address_Line", i) strLocality = obRat.DtExtractResultField("Locality", i) strState = obRat.DtExtractResultField("State", i) strPostcode = obRat.DtExtractResultField("Postcode", i) Debug.Print "Result number " & i

Debug.Print strAddressLine

Debug.Print strLocality & " " & strState & " " & strPostcode Next

'Close Engine

(32)

- 32 -

GenerateBarcode37

Method

You can use the DtGenerateBarcode37 method to generate a 37 bar barcode number for an existing DPID.

Available

Syntax

Barcode = controlname.DtGenerateBarcode37(DPID)

Barcode = controlname.DtxGenerateBarcode37(DPID)

Setting

The DtGenerateBarcode37 method uses the following settings.

DPID Required. A string value of the 8 digit DPID number used to create the barcode.

Barcode Returns a string value which is a numeric representation of the barcode. eg. '1301011201101010121111330302013223013'. Use the 'DataTools 4-State Barcode' font to print or display the numeric barcode value as graphical barcode.

Visual Basic Example

(Code available on CD at “\Sample Code\DtGenerateBarcode37.bas”)

Public Sub main() Dim obRat As Object Dim strDPID As String Dim strBarcode As String

Set obRat = CreateObject("DataTools_DtRat.Dt") strDPID = "56234121" strBarcode = obRat.DtGenerateBarcode37(strDPID) Debug.Print strBarcode End Sub

(33)

- 33 -

GenerateBarcode52

Method

You can use the DtGenerateBarcode52 method to generate an extended 52 bar barcode number for customer info.

Available

Syntax

Barcode = controlname.DtGenerateBarcode52(DPID, CustomerInfo, EncodingMethod)

Barcode = controlname.DtxGenerateBarcode52(DPID, CustomerInfo, EncodingMethod)

Setting

The DtGenerateBarcode52 method uses the following settings.

CustomerInfo Required. A string value of up to 8 digits or 5 characters in length dependant on the Encoding Method used.

EncodingMethod Required. A string value of either 'N' or 'C'.

Barcode Returns a string value which is a numeric representation of the barcode. Use the 'DataTools 4-State Barcode' font to print or display the numeric barcode value as graphical barcode.

The EncodingMethod argument has these settings:

N Numeric encoding method which allows up to 8 digits of customer to be embedded into the barcode.

C Character encoding method which allows up to 5 characters of customer to be embedded into the barcode.

Visual Basic Example

Public Sub main() Dim obRat As Object Dim strDPID As String Dim strBarcode As String Dim strCustomerInfo As String

(34)

- 34 - strDPID = "56234121"

strCustomerInfo = "John"

strBarcode = obRat.DtGenerateBarcode52(strDPID, strCustomerInfo, "C")

Debug.Print strBarcode End Sub

(35)

- 35 -

GenerateBarcode67

Method

You can use the DtGenerateBarcode67 method to generate an extended 67 bar barcode number for customer info.

Available

Syntax

Barcode = controlname.DtGenerateBarcode67(DPID, CustomerInfo, EncodingMethod) Equivalent Dtx method

Barcode = controlname.DtxGenerateBarcode67(DPID, CustomerInfo, EncodingMethod)

Setting

The DtGenerateBarcode67 method uses the following settings.

CustomerInfo Required. A string value of up to 15 digits or 10 characters in length dependant on the Encoding Method used.

EncodingMethod Required. A string value of either 'N' or 'C'.

Barcode Returns a string value which is a numeric representation of the barcode. Use the 'DataTools 4-State Barcode' font to print or display the numeric barcode value as graphical barcode.

The EncodingMethod argument has these settings:

N Numeric encoding method which allows up to 15 digits of customer to be embedded into the barcode.

C Character encoding method which allows up to 10 characters of customer to be embedded into the barcode.

Visual Basic Example

Public Sub main() Dim obRat As Object Dim strDPID As String Dim strBarcode As String Dim strCustomerInfo As String

(36)

- 36 -

strDPID = "56234121"

strCustomerInfo = "John Brown"

strBarcode = obRat.DtGenerateBarcode67(strDPID, strCustomerInfo, "C")

Debug.Print strBarcode End Sub

(37)

- 37 -

NzPafVersion Property

You can use the DtPafVersion property to retrieve New Zealand Postal Address File version.

Available

 Dt  Dtx  Australian version  New Zealand version

Syntax

PafVersionNumber = controlname.DtNzPafVersion

PafVersionNumber = controlname.DtxNzPafVersion

Setting

The DtPafVersion property uses the following settings.

PafVersionNumber Returns a string expression which is the PAF version number. (Note: String of “9999” is returned if not available on installed version)

Visual Basic Example

(Code available on CD at “\Sample Code\DtNzPafVersion.bas”) Public Sub main()

Set obRat = CreateObject("DataTools_DtRat.Dt") strVersion = obRat.DtNzPafVersion

MsgBox "PAF version :" & strVersion, vbInformation End Sub

(38)

- 38 -

Open Method

You will need to use the DtOpen method to open the RAT Engine before proceeding with any other RAT Active-X methods or properties.

Available

Syntax

Status = controlname.DtOpen

Status = controlname.DtxOpen

Setting

The DtOpen method uses the following settings.

Status Returns a Boolean expression of the engine's open status. True means engine opened successfully, False means error in

opening engine.

Visual Basic Example

(Code available on CD at “\Sample Code\DtOpen.bas”) Public Sub main()

Set obRat = CreateObject("DataTools_DtRat.Dt") Status = obRat.DtOpen

If Status Then

MsgBox "Engine Opened Successfully", vbInformation Else

MsgBox "Error Opening Engine", vbCritical End If

(39)

- 39 -

PafVersion Property

You can use the DtPafVersion property to retrieve Australia Postal Address File version.

Available

Syntax

PafVersionNumber = controlname.DtPafVersion

PafVersionNumber = controlname.DtxPafVersion

Setting

The DtPafVersion property uses the following settings.

PafVersionNumber Returns a string expression which is the PAF version number. (Note: String of “9999” is returned if not available on installed version)

Visual Basic Example

(Code available on CD at “\Sample Code\DtPafVersion.bas”) Public Sub main()

Set obRat = CreateObject("DataTools_DtRat.Dt") strVersion = obRat.DtPafVersion

MsgBox "PAF version :" & strVersion, vbInformation End Sub

(40)

- 40 -

ReturnLastCriticalErrorMessage Property

When using the multi-instance Dtx object you will need to use the DtxReturnLastCriticalErrorMessage property to return any errors that may have occurred.

Available

Syntax

ErrorMessage = controlname.DtxReturnLastCriticalErrorMessage

Setting

The DtxReturnLastCriticalErrorMessage method uses the following settings.

ErrorMessage Returns a String expression which is a details error message of the last critical error that occurred.

Visual Basic Example

(Code available on CD at “\Sample Code\DtxReturnLastCriticalErrorMessage.bas”) Public Sub main()

End If

End If End Sub

(41)

- 41 -

RolloutMangment_InstallUpdate Method

You can use the DtRolloutMangment_InstallUpdate method to launch the Setup,exe from the update server in update mode. For more details on the working of network update rollout refer to the Network Installation section of the RAT User Guide.

Available

Syntax

TaskID = controlname.DtRolloutMangment_InstallUpdate()

Setting

The DtRolloutMangment_InstallUpdate method uses the following settings.

TaskID The task ID of the setup program. The task ID is a unique number that identifies the running program. 0 is returned when an error occurs.

Note: The DtRolloutMangment_InstallUpdate method runs the setup program

asynchronously. This means that the setup program will not finish executing before the statements following the DtRolloutMangment_InstallUpdate method are executed. The returned task ID can be monitored to determine when the setup program has finished execution.

Visual Basic Example

(Code available on CD at “\Sample Code\DtRolloutManagement_InstallUpdate.bas”) Public Sub main()

Dim obRat As Object

'Check to see if newer version available

If obRat.DtRolloutManagement_NewerVersionAvailable = 1 Then '1 - Newer version available for install

If MsgBox("A newer version of the Rapid Address Tool has been detected and is ready for install. Do you wish to install the latest version now?", vbQuestion + vbYesNo, "DataTools Software Rollout") = vbYes Then

obRat.DtRolloutManagement_InstallUpdate End If

End If End Sub

(42)

- 42 -

RolloutManagement_NewerVersionAvailable Property

You can use the DtRolloutManagement_NewerVersionAvailable property to determine if a newer version of Rapid Addressing Tool is available for install from the server. For more details on the working of network update rollout refer to the Network Installation section of the RAT User Guide.

Available

Syntax

StatusCode = controlname.DtRolloutManagement_NewerVersionAvailable ()

Setting

The DtRolloutManagement_NewerVersionAvailable property uses the following settings.

StatusCode Returns an Integer value that is the status code for available updates.

Return Values

The DtRolloutManagement_NewerVersionAvailableproperty can return any of these

values:

0 Version is still current with server 1 Newer version available for install 2 Setup server not currently available

3 Managed rollout option not selected at install time

9 Error

Visual Basic Example

(Code available on CD at “\Sample Code\

DtRolloutManagement_NewerVersionAvailable.bas”) Public Sub main()

Dim obRat As Object

(43)

- 43 - Select Case obRat.DtRolloutManagement_NewerVersionAvailable

Case 0

MsgBox "Version is still current with server" Case 1

MsgBox "Newer version available for install" Case 2

MsgBox "Setup server not currently available" Case 3

MsgBox "Managed rollout option not selected at install time" Case 9

MsgBox "Error" End Select

End Sub

(44)

- 44 -

SearchAddressLine Method

You can use the DtSearchAddressLine method when you have a full address you wish to search against the Australian PAF.

Available

Syntax

ResultCount = controlname.DtSearchAddressLine(AddressLine, LocalityLine)

ResultCount = controlname.DtxSearchAddressLine(Instance, AddressLine, LocalityLine)

Setting

The DtSearchAddressLine method uses the following settings.

ResultCount Returns an Integer value that is the number of matching results found from the PAF. (Note: Number of 9999 is returned if not available on installed version)

AddressLine Required. A full address line eg. 'Level 5 200 Smith St' LocalityLine Required. A full locality line eg. 'SYDNEY NSW 2000'

Visual Basic Example

(Code available on CD at “\Sample Code\DtSearchAddressLine.bas”)

Public Sub main() Dim obRat As Object

Dim intNumberOfResultsFound As Integer

'Open Engine

End If

'Search for address line

intNumberOfResultsFound = obRat.DtSearchAddressLine("1 Hilda Ave", " NEWTON SA 5074")

(45)

- 45 - MsgBox intNumberOfResultsFound & _

" matching records found in the PAF.", vbInformation Else

MsgBox "No matching records were found.", vbExclamation End If

'Close Engine

(46)

- 46 -

SearchAddressLineAMAS Method

You can use the DtSearchAddressLineAMAS method when you have a full Australian address you wish to search against the PAF using the batch AMAS rules.

Available

Syntax

ErrorCode = controlname.DtSearchAddressLineAMAS(AddressLine, LocalityLine)

ErrorCode = controlname.DtxSearchAddressLineAMAS(Instance, AddressLine,

LocalityLine)

Setting

The DtSearchAddressLineAMAS method uses the following settings.

ErrorCode Returns an Integer value that is the error code for why an address didn‟t match. (Note: Number of 9999 is returned if not available on installed version)

AddressLine Required. A full address line eg. 'Level 5 200 Smith St' LocalityLine Required. A full locality line eg. 'SYDNEY NSW 2000'

Return Values

The DtSearchAddressLineAMASfunction can return any of these values:

See DtConvertErrorCode methods for further details.

0 Correct

1 Postcode couldn't be matched 2 State couldn't be matched 3 Locality couldn't be matched 4 Street Name couldn't be matched

5 Ambiguous

6 Street Number couldn't be matched 7 Postal Type couldn't be matched 8 Postal Number couldn't be matched 9 Phantom Primary Point

10 Unit Number couldn't be matched 11 The code is not currently in use 12 Level Type couldn't be matched 13 The code is not currently in use

(47)

- 47 - 14 Lot Number couldn't be matched

15 The code is not currently in use 16 The code is not currently in use 17 The code is not currently in use 18 Primary Point

20 Parser Warning

9999 Not available on installed version

Remarks

A single resultant address is only available for searches that result in the error codes 0 (Correct) or 18 (Primary Point) or 20 (Parser Warning). The resultant address can then be extracted using the DtExtractResultField property with the ResultNumber argument set to 1. The Primary Address code indicates that a flat, unit or floor (or combination) couldn't be found, but the street address could. Australia Post calls this the 'Primary Point'. The address returned is largely from the PAF, but the floor or unit information comes from the input record.

Visual Basic Example

(Code available on CD at “\Sample Code\DtSearchAddressLineAMAS.bas”) Public Sub main()

Dim obRat As Object

Dim strAddressLine As String Dim strLocality As String Dim strState As String Dim strPostcode As String Dim intErrorCode As Integer

'Open Engine

End If

intErrorCode = obRat.DtSearchAddressLineAMAS("40 Church St", "HARRIS PARK NSW 2150") If intErrorCode = 0 Then strAddressLine = obRat.DtExtractResultField("Address_Line", 1) strLocality = obRat.DtExtractResultField("Locality", 1) strState = obRat.DtExtractResultField("State", 1) strPostcode = obRat.DtExtractResultField("Postcode", 1) Debug.Print strAddressLine

Debug.Print strLocality & " " & strState & " " & strPostcode End If

(48)

- 48 - Status = obRat.DtClose

If Not Status Then

(49)

- 49 -

SearchFirstName Method

You can use the DtSearchFirstName method when you have a first name you wish to search against DataTools' first name database.

Available

Syntax

ResultCount = controlname.DtSearchFirstName(FirstName)

ResultCount = controlname.DtxSearchFirstName(Instance, FirstName)

Setting

The DtSearchFirstName method uses the following settings.

ResultCount Returns an Integer value that is the number of matching results found from the first name database.

FirstName Required. Whole or part of first name.

Visual Basic Example

(Code available on CD at “\Sample Code\DtSearchFirstName.bas”) Public Sub main()

Dim obRat As Object Dim strFirstName As String

Dim intNumberOfResultsFound As Integer Dim i As Integer

'Open Engine

MsgBox "Error Opening Engine", vbCritical Exit Sub End If intNumberOfResultsFound = obRat.DtSearchFirstName("John") For i = 1 To intNumberOfResultsFound strFirstName = obRat.DtExtractResultField("First_Name", i) Debug.Print "Result number " & i