Primary API reference

Pseudocode example of Pro API

This section provides an overview of how a program using the Pro API works on a conceptual level. The pseudocode used is programming language independent.

The example below uses many of the Pro API functions, so that you can see how they work together. In practice, however, you might not want or need to use every function.

The pseudocode does not include all the available functions.

Six functions are described in the pseudocode. The main function starts an instance of the API, and gives the user a choice of performing a Singleline or Typedown search. It then frees resources after each result has been retrieved. Each search recursively calls five further functions: Display Error, which retrieves and displays the message associated with the returned error code; User Action, which displays prompts (commonly an instruction as to what should be entered by the user); Display results, which retrieves picklists of results from the search; SelectResults, which allows the user to step into picklist items; and ReturnAddress, which formats and returns the final address, using the rules specified in the active layout. These functions are:

• Main
• Display error
• User action
• Display results
• Select results
• Return address

Open an instance of the API [QA_Open]

If open failed
    Call Display error
    close API instance [QA_Close]
    shutdown API [QA_Shutdown]
    exit procedure
End If

set active dataset to search upon [QA_SetActiveData]
set engine to use for searching [QA_SetEngine]

set layout to use for formatting [QA_SetActiveLayout]
set engine options [QA_SetEngineOption]

Repeat

Call Display results

Call User action
If action was search text
    search with text [QA_Search]
Else If action was to select an item
    Call Select Result
End If

end the search [QA_EndSearch]

close the instance [QA_Close]

shutdown the API [QA_Shutdown]

retrieve error message [QA_ErrorMessage]
display error message to user
Return to calling function

retrieve prompt text [QA_GetPrompt]
display prompt to user
obtain action from user
Return to calling function

get a count of available [QA_GetSearchStatus]
For Each result
    retrieve the result [QA_GetResult]
    display the result to the user
End For
Return to calling function

get the attributes of the result [QA_GetResult]
If result can be stepped into
    step into result [QA_StepIn]
Else If result is a final address
    Call Return address
End If
Return to calling function

format result and retrieve line count [QA_FormatResult]
For Each formatted line
    retrieve the line text [QA_GetFormattedLine]
    return text to the user
End For
Return to calling function

Handling errors

Every Primary API function except for QA_Shutdown returns an integer error code value. This value will be within the following ranges:

Experian strongly recommends that every function call is checked for errors. Although the majority of errors are generated by mistakes in an integration which would be picked up through testing, some are unpredictable. For example, the failure of a client-server link, running out of memory, or a data file expiry.

All Primary API functions will set their output parameters to defined values if an error occurs. Integer output variables will be set to zero, and string output variables will be set to blank.

The LogErrors configuration setting is a useful way of locating the cause of an error. Experian recommends that you enable error logging while writing and debugging an integration.

The QA_ErrorMessage function provides a textual description of error codes returned from the API.

The handling of errors should typically be split into two categories. These are described below.

1. An error returned from a call to QA_Open. This means that address capture is unavailable.

   This could be caused by many things, such as configuration or administration errors. Experian recommends that you call QA_Shutdown and locate the source of the problem using the LogErrors setting.

2. An error returned from a call to QA_Open because, although address capture is available, the current search has failed for some reason. This could be due to a lack of resources, or to an administration error. Experian recommends that you call QA_EndSearch to end the current search.

   Note that you do not have to shut down the system, and that address capture may still be available. For example a client-server link may have failed, losing the current search. In that case attempting a new search would reestablish the connection and your integration would continue functioning correctly.

If you are writing a client-server integration of Pro, it is very important to react to errors after QA_Open as described above. An error will be returned from an API function if a connection to the server in use is lost, as the search results will not be retrievable.

API instances

The Primary API is based on the concept of instances. An instance of the API is created through calling QA_Open, and is destroyed by calling QA_Close. Once an instance is created, it is referenced through an integer handle that is returned from QA_Open. All subsequent functions that use the instance must be passed through this handle. Once all instances have been closed using QA_Close, the API should be shut down using QA_Shutdown.

Each instance of the API that is created is independent from other instances. Any action that is performed upon one instance will not affect the state of another instance. Actions can be performed upon separate instances simultaneously.

If you want to have a multithreading integration that performs multiple searches concurrently, you should create multiple instances of the API. Each thread will typically perform the following actions:

• Create an instance using QA_Open
• Perform one or more searches
• Close the instance using QA_Close

Once all threads have finished, call QA_Shutdown.

Flags returned

Many API functions, such as QA_GetSearchStatus, pass information back using 'flags'.

Flags are a means of communicating multiple pieces of information back to the caller using a single parameter.

The value returned consists of multiple values ORed together.

qaresult_CANSTEP                    4
qaresult_INFORMATION               1024

if (rlFlags & 1024)
{
...
}

In VB:

If (rlFlags And 1024) Then
    ...
EndIf

Some functions have accompanying 'Detail' functions; for example, QA_GetResult has the accompanying function QA_GetResultDetail. These allow the caller to inquire about a single specific attribute and is useful for languages that cannot perform bitwise operations such as AND, or for integration that require extra information.

If rsDetail or rlDetail are not used in a particular call to a 'Detail' function, it will return a blank string or zero as appropriate.

Example:

QA_GetResultDetail        ( iHandle,
                             iResult,
                             qaresultint_ISINFORMATION,
                             &lDetail,
                             NULL,
                             0 );

This will return qavalue_True or qavalue_False in parameter lDetail, depending on whether the given picklist item is informational or not.

Automatic stepping and formatting

To help you locate addresses faster and more effectively, the Primary API supports automatic stepping into and formatting of picklist items generated from an initial search. For example, if you were to perform a search that generated only a single exact result, the integration can automatically step into that item instead of prompting you to do it manually, which speeds up the address capture process.

Automatic stepping in and formatting is not required for a successful integration, and it is therefore at your discretion whether you act upon the returned flags.

The Primary API will output one of the following four flags from the function QA_GetSearchStatus.

The flag qastate_AUTOSTEPINSAFE is returned when a search or step in has produced a picklist containing only one match that itself can be stepped into. Experian recommends that the integration should call QA_StepIn upon the first item in the picklist when this flag is returned, as it will speed up the address capture process.

The flag qastate_AUTOSTEPINPASTCLOSE is returned when a search or step in has produced a picklist containing only one exact match, and also multiple non-exact matches. You may choose to call QA_StepIn on the first item in the picklist when this flag is returned, as it may speed up the address capture process.

The flag qastate_AUTOFORMATSAFE is returned when a search or step in has produced a picklist containing only a single match that is a final address item. If the integration allows you to go back to the picklist after selecting a final address, then Experian recommend that QA_FormatResult should be called upon the first picklist item and the address returned.

The flag qastate_AUTOFORMATPASTCLOSE is returned when a search or a step in has produced a picklist containing only one exact match that is a final address item, and also multiple non-exact matches. If the integration allows you to go back to the picklist after selecting a final address, then you can choose to call QA_FormatResult on the first item in the picklist and on the address returned.

Asynchronous searching

The Primary API supports two different threading models for performing searches: synchronous and asynchronous.

Synchronous searching is the default threading model, and is used by the majority of integrations. Using synchronous searching, the function QA_Search and/or QA_StepIn return to the caller once the search has been completed. You can then immediately access the results.

Asynchronous searching is an alternative threading model where the calls to the searching functions are returned as soon as the search has begun. The search is performed using a background thread.

There are three engine options that control asynchronous searching:

1. The qaengopt_ASYNCSEARCH engine option allows the integrator to control whether an initial search using QA_Search on the Singleline engine is asynchronous. This is the most commonly used option for asynchronous searching.
2. The qaengopt_ASYNCSTEPIN engine option allows the integrator to control whether stepping into picklist items using QA_StepIn is asynchronous.
3. The qaengopt_ASYNCREFINE engine option allows the integrator to control whether picklist refinement using QA_Search after the first result for the Singleline engine, and all searches using the Typedown engine, are asynchronous. This will be used less frequently, as picklist refinement is a fast process.

The search must be complete before you can retrieve the results. The caller needs to check periodically whether the search has been completed by calling QA_GetSearchStatus, and checking whether the flag qastate_STILLSEARCHING is present. Typically, you should check every 100ms to see whether the search has completed.

The following diagram demonstrates polling:

Asynchronous searching is useful, although not essential, for graphical user interface integrations where the caller wants to be able to perform tasks while the search is in progress, and does not want to use multithreaded code. For example, this could be used to react to search cancel requests.