Global Address Object:Interface Use

← Global Address Object Reference

Creating an Instance

1. Create an instance of the Global Address Object’s GlobalAddr Interface.

Set addPtr = new instance of GlobalAddr

The first set of steps is to initialize the instance of the GlobalAddr Interface.

2. If necessary, call SetLicenseString and pass the License Key as mentioned in Licensing. Again, this is not necessary if the License Key is provided as the recommended environment variable.
3. Call the SetPathToGlobalAddrFiles function with file a path as a parameter pointing to the location of the Global Address Object reference data files.
4. Call the InitializeDataFiles function. If it returns anything other than 0, then initialization has failed. Check the return value of the GetInitializeErrorString function to find out why this happened.

CALL InitializeDataFiles RETURNING result

If result <> 0 THEN
	Call GetInitializeErrorString RETURN ErrorMessage
	Display ErrorMessage
Else
	Process Addresses
End If

5. At this point, we are ready to load the GlobalAddr with address input data for verification correction etc.

Setting Parameters for Input

Setting input address data is the first step in global address validation. Before any verification or correction can be completed, the originating input address data must be set into the Global Address Object’s input parameters. Parameters are set into the Global Address Object as name/value pairs. The complete list of name/value pairs for input and output can be found in Parameters.

So, using our Global Address Object addPtr defined previously, we will set the following sample address into the input parameters:

Sample Address

Carretera Rioseco 2

34170 Villamartín De Campos Palencia

SPAIN

Result =  addPtr.SetInputParameter(“inputCountry”, “Spain”)
Result =  addPtr.SetInputParameter(“inputAddressLine1”, “Carretera Rioseco 2”)
Result =  addPtr.SetInputParameter(“inputAddressLine2”, “34170 Villamartín De Campos Palencia”)

Notice that the input in this case is in an address line format. Global Address Object will attempt to field and parse these address lines before processing the verification and correction of the address data.

Setting the outputPreference parameter tells the Global Address Object to return the results based on the language/alphabet parameter specified. This is accomplished via either translation, transliteration, or a combination of both.

Once we have our parameters set, we are ready to make the processing call to do some work on the input address data.

Functions for Processing Input

There are 3 functions that process data provided to the Global Address Object, but only VerifyAddress utilizes the input parameters set in Setting Parameters for Input. TranslateText and TransliterateText are utilized to map or move any input value and language combination to another output value and language combination.

VerifyAddress

The VerifyAddress function takes in no parameters, but reads from the values set in the SetInputParameter call(s) to attempt to process the input data for fielding, parsing, verification/correction and return formatting. The results from calling VerifyAddress are accessible by utilizing the functions defined in Getting Results and Output.

The call is very straightforward, but again, dependent on input parameters being defined.

Intval = VerifyAddress()

The return integer intval from this call has no determination or value related to the results of the call. The return only defined a 0 or 1 for the success or failure of the function call itself. Getting to the results of the VerifyAddress call itself, is the job of GetOutputParameter and GetOutputParameterNames.

Getting Results and Output

There are three functions available for getting return values and results from the Global Address Object: GetInputParameterNames, GetOutputParameterNames and GetOutputParameter.

GetInputParameterNames

GetInputParameterNames returns the application an array/list of input parameter names like the input values referenced in Setting Parameters for Input.

GetOutputParameterNames

GetOutputParameterNames functions in the same manner as GetInputParameterNames, but is specifically for getting outputted results from the address verification/correction process initialized with verifyAddress.

For a complete list of input and output parameter names with definitions, see Parameters.

GetOutputParameter

The GetOutputParameter function is the counterpart to SetOutputParameter. This function takes in a parameter name, such as administrativeArea and returns the value “Queensland” for an address such as the one below.

Sample Address

91 Queen Street, Brisbane QLD 4000 Australia

In this example, QLD is the administrative area (US terms State/Province) abbreviation for Queensland.

House number = 91
Street = Queen Street
Postal Code = 4000 
Administrative Area = QLD 
City/Locality = Brisbane
Country Name = Australia

To pass this fielded address data to the object as parameters the following calls would be coded:

Result =  addPtr.SetInputParameter(“inputCountry”, “Australia”)
Result =  addPtr.SetInputParameter(“premiseNumber”, “91”)
Result =  addPtr.SetInputParameter(“PostalCode”, “4000”)
Result =  addPtr.SetInputParameter(“AdministrativeArea”, “QLD”)
Result =  addPtr.SetInputParameter(“Locality”, “Brisbane”)
Result =  addPtr.SetInputParameter(“thoroughfareName”, “Queen Street”)
// Now that all input values are set, call verifyAddress to attempt to process input
Intval = VerifyAddress()
// Now get values if intval is successful
If intval = true
		outputResult1 = addPtr.GetOutputParameter(“administrativeArea”)
		outputResult2 = addPtr.GetOutputParameter(“inputAdministrativeArea”)
End if

The variable outputResult1 contains the resulting administrative area, as already mentioned: Queensland. It important to note that outputResult2 also contains a value which is the original input value of QLD as administrative area.