Global Address Object:Interface Use
|Global Address Object Navigation|
Creating an Instance
- Create an instance of the Global Address Object’s GlobalAddr Interface.
- 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.
- Call the SetPathToGlobalAddrFiles function with file a path as a parameter pointing to the location of the Global Address Object reference data files.
- 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.
- At this point, we are ready to load the GlobalAddr with address input data for verification correction etc.
Set addPtr = new instance of GlobalAddr
The first set of steps is to initialize the instance of the GlobalAddr Interface.
CALL InitializeDataFiles RETURNING result If result <> 0 THEN Call GetInitializeErrorString RETURN ErrorMessage Display ErrorMessage Else Process Addresses End If
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
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 Paramters for Input. TranslateText and TransliterateText are utilized to map or move any input value and language combination to another output value and language combination.
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 returns the application an array/list of input parameter names like the input values referenced in Setting Parameters for Input.
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.
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.