API function reference

The primary Pro API functions are split into the following groups:

Opens an instance of the API allowing you to specify the name of the configuration file to use and the section to use within that file.

The handle returned from riHandle is the one you will pass to all other functions. If the call to QA_Open fails for any reason, then the handle returned will not be valid to pass to other functions, except QA_Close.

There is no inherent limit on the number of instances that can be created with QA_Open and held simultaneously. System resources such as memory can limit the number, although this would never typically be reached for an integration upon a suitable machine.

Prototype

INTRET QA_Open     ( STRVAL vsIniFile,
                     STRVAL vsSection,
                     INTREF riHandle );

Arguments

vsIniFile Name of configuration file to open
vsSection Section of the configuration file to use
riHandle Instance handle returned by the API

Return value

Either: 0 if call is successful

Or: Negative error code

Comments

The layout for the instance will default to an internal layout that will be valid but may not be suitable. However, Experian strongly recommends that you should call QA_SetActiveLayout after QA_Open.

If no configuration file is specified, the standard ini file qaworld.ini will be used. If no section is specified, the default 'QADefault' will be used.

A call to QA_Open must have a corresponding call to QA_Close.

Error scenarios

INI File Error The configuration file specified in parameter vsIniFile cannot be opened.
Open Failure The API was unable to create a new instance. Use the LogErrors configuration setting to determine where the problem lies.

Shuts down an instance of the API that has been opened with QA_Open. Once an instance has been closed, the instance handle will be invalid and cannot be passed to subsequent API functions.

If the call to QA_Open failed, then the returned instance handle will be set to zero, which can be safely used with this function.

If "Asynchronous Searching" is in use, then calling QA_Close will safely cancel it before closing the instance.

Prototype

INTRET QA_Close         ( INTVAL viHandle );

#### Arguments
viHandle Instance handle returned by the API

Return value

Either: 0 if call is successful

Or: Negative error code

Used to translate an error code into a description.

Prototype

INTRET QA_ErrorMessage      ( INTVAL viError,
                              STRREF rsBuffer,
                              INTVAL viBufferLength );

Arguments

viError Error code to translate
rsBuffer Returned error description
viBufferLength Length of rsBuffer

Return value

Either: 0 if call is successful

Or: Negative error code

Closes down the API, and must be called as the final function, after all instances have been closed with QA_Close.

The shutdown function frees all resources associated with the Universal API and must be the last function to be called in the API before the calling program ends or unloads the API from memory.

Prototype

VOIDRET QA_Shutdown     ( VOIDARG );

Changes the current search engine. If the search engine is changed during a search, this will end the current search.

Prototype

INTRET QA_SetEngine         ( INTVAL viHandle,
                              INTVAL viEngine );

Arguments

viHandle Handle for this instance of the API
viEngine Engine to be selected

Return value

Either: 0 if call is successful

Or: Negative error code

Comments

The possible search engines that can be passed to viEngine are:

Symbolic Name Decimal Value Description
qaengine_SINGLELINE 1 Singleline engine
qaengine_TYPEDOWN 2 Typedown engine
qaengine_VERIFICATION 4 Verification engine
qaengine_KEYFINDER 5 Keyfinder engine
qaengine_INTUITIVE 8 Intuitive engine

Error scenarios

Busy Handle: The parameter viHandle has been passed a handle that is already in use in another thread. Each handle can only be used by one thread at any point in time.

Retrieves the current search engine.

Prototype

INTRET QA_GetEngine     ( INTVAL viHandle,
                          INTREF riEngine );

Arguments

viHandle Handle for this instance of the API
riEngine The current active search engine

Return value

Either: 0 if call is successful

Or: Negative error code

Comments

The possible search engines that can be returned from parameter riEngine are as follows:

Symbolic Name Decimal Value Description
qaengine_SINGLELINE 1 Singleline engine
qaengine_TYPEDOWN 2 Typedown engine
qaengine_VERIFICATION 4 Verification engine
qaengine_KEYFINDER 5 Keyfinder engine
qaengine_INTUITIVE 8 Intuitive engine

Error scenarios

Busy Handle: The parameter viHandle has been passed a handle that is already in use in another thread. Each handle can only be used by one thread at any point in time.

Sets engine-related attributes for the given engine. The attributes that can be modified include threshold, timeout, search intensity and asynchronous operation.

Prototype

INTRET QA_SetEngineOption       ( INTVAL viHandle,
                                  INTVAL viEngOption,
                                  LONGVAL vlValue );

Arguments

viHandle Handle to the API
viEngOption The engine option to be set
vlValue Value for this option

Return value

Either: 0 if call is successful

Or: Negative error code

Comments

The possible search engines that can be passed to viEngine are:

Symbolic Name Decimal Value Description
qaengopt_DEFAULT 0 Resets the engine options to the defaults.
qaengopt_ASYNCSEARCH 1 Single line searches will be asynchronous. The default is qavalue_FALSE.
qaengopt_ASYNCSTEPIN 2 Calls to QA_StepIn will be asynchronous. The default is qavalue_FALSE.
qaengopt_ASYNCREFINE 3 Picklist refinement will be asynchronous. The default is qavalue_FALSE.
qaengopt_FLAT 4 Picklist will be flattened. Allowed values are qavalue_TRUE or qavalue_FALSE.
qaengopt_THRESHOLD 6 Allows you to set the result size threshold. The default is 25. The minimum limit is 5 and the maximum limit is 1000.
qaengopt_TIMEOUT 7 Allows you to set the timeout limit (ms). The default is 0 milliseconds (never times out) and the limit is 600000 (10 minutes).
qaengopt_SEARCHINTENSITY 8 Single-line mode edit distance level. The default is qaintensity_ CLOSE.
qaengopt_PICKLISTSIZE 9 The maximum number if items returned in a picklist.
qaengopt_ACTIVEPROMPTSET 11 The prompt set to use.

The engine options that control asynchronous searching are as follows:

  • qaengopt_ASYNCSEARCH
  • qaengopt_AYSNSTEPIN
  • qaengopt_ASYNCREFINE

The type qaengopt_DEFAULT does not use the parameter vlValue.

The types qaengopt_ASYNCSEARCH, qaengopt_ASYNCSTEPIN and qaengopt_ASYNCREFINE can have the following values passed to parameter vlValue:

|Boolean|Values|
|---|---|---|
|qavalue_FALSE|0|False|
|qavalue_TRUE|1|True|

The engine option type qaengopt_SEARCHINTENSITY can have the following values passed to parameter vlValue.

|Search Intensity Values|
|---|---|---|
|qaintensity_EXACT|0|Exact searching|
|qaintensity_CLOSE|1|Close searching|
|qaintensity_EXTENSIVE|2|Extensive searching|

The search intensity setting represents how hard the Singleline search engine will search for an address with respect to the accuracy of matches. If the search intensity is set higher, then searches may take longer to perform, although more inexact matches will be returned.

When using qaengopt_THRESHOLD and qaengopt_TIMEOUT, an integer value should be passed to vlValue

Error scenarios

Busy Handle: The parameter viHandle has been passed a handle that is already in use in another thread. Each handle can only be used by one thread at any point in time.
Bad Value The value passed to parameter vlValue is not valid for the given engine option.

Retrieves the current settings used with a search engine.

Prototype

INTRET QA_GetEngineOption       ( INTVAL viHandle,
                                  INTVAL viEngOption,
                                  LONGREF rlValue );

Arguments

viHandle Handle for this instance of the API
viEngOption Engine option to be returned
rlValue Value for the given engine option

Return value

Either: 0 if call is successful

Or: Negative error code

Comments

The possible engine option values that can be requested are listed below:

Symbolic Name Decimal Value Description
Options
qaengopt_ASYNCSEARCH 1 Single line searches will be asynchronous. The default is qavalue_FALSE.
qaengopt_ASYNCSTEPIN 2 Calls to QA_StepIn](/address-validation/pro-api/7.98/integration/api-function-reference/#qa-step-in-steps-into-a-picklist-item) will be asynchronous. The default is qavalue_FALSE.
qaengopt_ASYNCREFINE 3 Picklist refinement will be asynchronous. The default is qavalue_FALSE.
qaengopt_FLAT 4 Picklist will be flattened.
qaengopt_THRESHOLD 6 Allows you to set the result size threshold. The default is 25. The minimum limit is 5 and the maximum limit is 1000.
qaengopt_TIMEOUT 7 Allows you to set the timeout limit (ms). The default is 0 milliseconds (never times out) and the limit is 600000 (10 minutes).
qaengopt_SEARCHINTENSITY 8 Single-line mode edit distance level. The default is qaintensity_ CLOSE.
qaengopt_PICKLISTSIZE 9 The maximum number if items returned in a picklist.
qaengopt_ACTIVEPROMPTSET 11 The prompt set currently in use.
qaengopt_PROMPTSETCOUNT 12 The number of prompt sets available.

The engine option types qaengopt_ASYNCSEARCH, qaengopt_ASYNCSTEPIN and qaengopt_ASYNCREFINE can have the following values passed to parameter rlValue:

|Boolean Values|
|---|---|---|
|qavalue_FALSE|0|False|
|qavalue_TRUE|1|True|

The engine option type qaengopt_SEARCHINTENSITY can have the following values passed to parameter rlValue.

|Search Intensity Values|
|---|---|---|
|qaintensity_EXACT|0|Exact searching|
|qaintensity_CLOSE|1|Close searching|
|qaintensity_EXTENSIVE|2|Extensive searching|

The other engine option types will return an integer value.

The engine options that control asynchronous searching are as follows:

  • qaengopt_ASYNCSEARCH
  • qaengopt_AYSNSTEPIN
  • qaengopt_ASYNCREFINE

Error scenarios

Busy Handle The parameter viHandle has been passed a handle that is already in use in another thread. Each handle can only be used by one thread at any point in time.

Retrieves the current status of a search engine. This allows you to check whether a particular engine is available for the data mapping you have selected.

Prototype

INTRET QA_GetEngineStatus       ( INTVAL viHandle,
                                  INTVAL viEngine,
                                  LONGRET riAvailable );

Arguments

viHandle Handle for this instance of the API
viEngine Engine to be selected
riAvailable Availability of the engine

Return value

Either: 0 if call is successful

Or: Negative error code

Comments

The possible search engines that can be passed to viEngine are:

Symbolic Name Decimal Value Description
qaengine_SINGLELINE 1 Single line engine
qaengine_TYPEDOWN 2 Typedown engine
qaengine_VERIFICATION 4 Verification engine
qaengine_KEYFINDER 5 Keyfinder engine
qaengine_INTUITIVE 8 Intuitive engine

The parameter riAvailable will return one of the following values:

|Boolean Values|
|---|---|---|
|qavalue_FALSE|0|False|
|qavalue_TRUE|1|True|

Returns the prompt text. This is a short sentence that can be displayed to prompt the user to search using the appropriate address items. For example when beginning a search using the Typedown engine the prompt may be 'Enter place or postcode'.

Prototype

INTRET QA_GetPrompt     ( INTVAL viHandle,
                          INTVAL viLine,
                          STRREF rsPrompt,
                          INTVAL viPromptLength,
                          INTREF riSuggestedInputLength,
                          STRREF rsExample,
                          INTVAL viExampleLength );

Arguments

viHandle Handle for this instance of the API
viLine The prompt line to be returned. Always pass 0.
rsPrompt Buffer to receive a prompt line
viPromptLength The length of the receive buffer
riSuggestedInputLength For future expansion
rsExample For future expansion
viExampleLength For future expansion

Return value

Either: 0 if call is successful

Or: Negative error code

Comments

The riSuggestedInputLength, rsExample and viExampleLength parameters should be treated as any other parameter, except that any returned values should be ignored for this release of Pro.

Error scenarios

Busy Handle The parameter viHandle has been passed a handle that is already in use in another thread. Each handle can only be used by one thread at any point in time.

Returns status information about the current prompt.

Prototype

INTRET QA_GetPromptStatus       ( INTVAL viHandle,
                                  INTVAL viType,
                                  INTREF riStatus,
                                  STRREF rsStatus,
                                  INTVAL viStatusLength );

Arguments

viHandle Handle for this instance of the API
viType Type of status information to receive
riStatus Integer status information
rsStatus String status information
viStatusLength Length of rsStatus

Return value

Either: 0 if call is successful

Or: Negative error code

Comments

If the symbolic name of the result detail type passed to viType is prefixed with qapromptstr_ then a string will be returned through the rsStatus parameter. If the symbolic name is prefixed with qapromptint_ then an integer will be returned through the riStatus parameter.

The parameter viType is used to specify what piece of information you want to be returned. It can take one of the following values:

|Symbolic Name|Decimal Value|Description|
|qapromptint_LINECOUNT|1|The number of input lines prompted by the prompt set.|
|qapromptint_DYNAMIC|2|Returns whether or not the current prompt is dynamic.|

The prompt status type qapromptint_DYNAMIC will return one of the following values in parameter riStatus.

|Boolean Values|
|---|---|---|
|qavalue_FALSE|0|False|
|qavalue_TRUE|1|True|

The prompt status affects the way in which a GUI should display the text box in which the user enters the search string. A non-dynamic prompt should be blanked after every call to QA_Search and QA_StepIn as the search text should not be retained for the next stage. A dynamic prompt should only be blanked when QA_StepIn is called, and should retain the text after a call to QA_Search.

The prompt status is designed to be obtained before the call to QA_Search, not afterwards.

Error scenarios

Busy Handle: The parameter viHandle has been passed a handle that is already in use in another thread. Each handle can only be used by one thread at any point in time.

Performs a search using the current active dataset.

This function should be called when you have entered text to be searched upon. This will be in two cases:

  • You are entering the initial search using the Singleline engine.
  • You are entering text to refine the picklist further.

To finish an old search and perform a new one, you must first call QA_EndSearch.

Prototype

INTRET QA_Search        ( INTVAL viHandle,
                          STRVAL vsSearch );

Arguments

viHandle Handle for this instance of the API
vsSearch The search string

Return value

Either: 0 if call is successful

Or: Negative error code

Error scenarios

Busy Handle: The parameter viHandle has been passed a handle that is already in use in another thread. Each handle can only be used by one thread at any point in time.
Bad Layout: The active layout that is set for the instance is invalid. The list of valid layouts can be obtained by using the QA_GetLayoutCount and QA_GetLayout functions. A layout may be defined for a specific dataset only, and so changing the active dataset may invalidate the active layout.

Cancels a search that is still in progress. This can be called if using either asynchronous or synchronous searching, although it is more common to use it with asynchronous searching.

Prototype

INTRET QA_CancelSearch      ( INTVAL viHandle,
                              LONGVAL vlFlags );

Arguments

viHandle Handle for this instance of the API
vlFlags Flags to control function behavior

Return value

Either: 0 if call is successful

Or: Negative error code

Comments

The following flags, passed into vlFlags, can be used to specify how to stop a search in progress (either to return immediately or to wait until the search has been cancelled):

Symbolic Name Decimal Value Description
qacancelflag_NONE 0 Returns immediately after cancelling
qacancelflag_BLOCKING 1 Does not complete function until the search has been successfully cancelled

Ends the search. This function is called once all search information has been returned. It must be called before a new search is started.

If an asynchronous search is in progress, then calling QA_EndSearch will safely cancel it before ending the search.

Prototype

INTRET QA_EndSearch     ( INTVAL viHandle );

Arguments

viHandle Handle for this instance of the API

Return value

Either: 0 if call is successful

Or: Negative error code

Obtains the status of a search. This function is an alternative to QA_GetSearchStatusDetail. Using this function, all of the search status is returned together through flags.

This function is used to retrieve the number of results matched by the engine; and also if anything unexpected has occurred, such as if the search times out or if there are too many matches to display.

This function can be called while a search is still in progress. This situation could occur if "asynchronous searching" was active, or if the integration uses a different thread to call the function.

Prototype

INTRET QA_GetSearchStatus       ( INTVAL viHandle,
                                  INTREF riPicklistSize,
                                  INTREF riPotential,
                                  LONGREF rlSearchState );

Arguments

viHandle Handle for this instance of the API
riPicklistSize Size of the picklist used for the index
riPotential Number of total potential items
rlSearchState The state after a search

Return value

Either: 0 if call is successful

Or: Negative error code

Comments

The flags with the prefix qastate_AUTO are related to auto stepping and formatting.

The parameter riPotential can be useful when the search has returned a number of matches over the threshold, so riPicklistSize is 1. riPotential then gives an idea of how far the results exceed the threshold. The value that is returned from riPotential is only an approximate estimate of the number of potential matches, which may indicate the extent of the refinement that should be performed in order to return a single result. If there are no matches riPicklistSize will be 1 as the single result "No matches" will be returned. This estimate should only be used as a guide to the user, and not relied upon in the integration.

The returnable flags in the rlSearchState parameter are ORed together, and are as follows:

Symbolic Name Decimal Value Description
qastate_NOSEARCH 1 No search has been started.
qastate_STILLSEARCHING 2 The search is still in progress.
qastate_TIMEOUT 4 The search has timed out.
qastate_SEARCHCANCELLED 8 The search has been cancelled using QA_CancelSearch.
qastate_MAXMATCHES 16 The maximum number of results has been reached, and there are too many to return: therefore, no results are returned. The search is finished and you must call QA_EndSearch before beginning a new one.
qastate_OVERTHRESHOLD 32 There are too many matches to display, as there are more picklist items than the threshold value. The threshold value is set in QA_SetEngineOption.
qastate_LARGEPOTENTIAL 64 Potentially, there are too many results to display, so you must keep typing (i.e., search with a larger string) in order to refine the search.
qastate_MOREOTHERMATCHES 128 There are additional other matches that can be displayed.
qastate_REFINING 256 Any text passed into QA_Search will be used to refine the current picklist rather than search.
qastate_AUTOSTEPINSAFE 512 The current picklist is trivial, therefore it is suggested that you immediately step into the first picklist item.
qastate_AUTOSTEPINPASTCLOSE 1024 There are other close matches present, but only one exact match. Integrators may choose to step immediately into the first picklist item with QA_StepIn.
qastate_CANSTEPOUT 2048 Can step out of the picklist by calling QA_StepOut.
qastate_AUTOFORMATSAFE 4096 The current picklist is trivial, therefore it is suggested that you immediately format the first picklist item with QA_FormatResult.
qastate_AUTOFORMATPASTCLOSE 8192 There are other close matches present, but only one exact match. Integrators may choose to format immediately the first picklist item with QA_FormatResult.

Obtains detailed information about the status of a search. This function is an alternative to QA_GetSearchStatus. Using this function you can inquire about individual aspects of the search status separately, instead of obtaining all the information through the use of flags.

This function can be called while a search is still in progress. This situation could occur if you use asynchronous searching, or if the integration uses a different thread to call the function.

Prototype

INTRET QA_GetSearchStatusDetail     ( INTVAL viHandle,
                                      INTVAL viType
                                      LONGREF rlDetail,
                                      STRREF rsDetail,
                                      INTVAL viDetailLength );

Arguments

viHandle Handle for this instance of the API
viType Type of detail requested
rlDetail Returned detail integer
rsDetail Returned detail string
viDetailLength Length of rsDetail

Return value

Either: 0 if call is successful

Or: Negative error code

Comments

If the symbolic name of the result detail type passed to viType is prefixed with qasstr_ then a string will be returned through the rsDetail parameter.

The detail types with the prefix qassint_ISAUTO are related to auto stepping and formatting.

The parameter viType is used to specify the information that you want to be returned. It can take one of the following values::

Symbolic Name Decimal Value Description
qassint_PICKLISTSIZE 1 Returns the size of picklist.
qassint_POTENTIALMATCHES 2 Returns the number of potential matches.
qassint_SEARCHSTATE 3 Returns the search state flags (as returned by QA_GetSearchStatus).
qassint_ISNOSEARCH 4 Returns whether a search has not yet been started.
qassint_ISSTILLSEARCHING 5 Returns whether a search is currently in progress.
qassint_ISTIMEOUT 6 Returns whether the search timed out. The timeout limit is set in QA_ SetEngineOption.
qassint_ISSEARCHCANCELLED 7 Returns whether the search has been cancelled using QA_ CancelSearch.
qassint_ISMAXMATCHES 8 Returns whether the maximum number of results has been reached and there are too many to return.
qassint_ISOVERTHRESHOLD 9 Returns whether there are more picklist items than the threshold value, and therefore too many matches to display.
qassint_ISLARGEPOTENTIAL 10 Returns whether there are potentially too many results to display and the search must be further refined.
qassint_ISMOREOTHERMATCHES 11 Returns whether there are additional other matches that can be displayed.
qassint_ISREFINING 12 Returns whether any text passed into QA_Search will be used to refine a picklist rather than to search.
qassint_ISAUTOSTEPINSAFE 17 Returns whether the current picklist is trivial and you should step into the first item.
qassint_ISAUTOSTEPINPASTCLOSE 18 Returns whether there are some close matches in the picklist but only one exact match that could be automatically stepped into using QA_StepIn.
qassint_CANSTEPOUT 19 Returns whether the current picklist can be stepped out of using QA_StepOut.
qassint_ISAUTOFORMATSAFE 20 Returns whether the current picklist is trivial and you should format the first item.
qassint_ISAUTOFORMATPASTCLOSE 21 Returns whether there are some close matches in the picklist but only one exact match that could be automatically formatted.
qassint_VERIFYLEVEL 22 Returns details of the search results for Verification searches.

For the types that are prefixed qassint_IS and for qassint_CANSTEPOUT, the following boolean values can be returned from the parameter rlDetail:

|Boolean Values|
|---|---|---|
|qavalue_FALSE|0|False|
|qavalue_TRUE|1|True|

For the qassint_VERIFYLEVEL the following values can be returned from the parameter rlDetail.

|Verification Level Values|Decimal Value|Verification Level|
|qaverify_NONE|1|None (no matches)|
|qaverify_VERIFIED|2|Verified|
|qaverify_INTERACTIONREQUIRED|3|Interaction required|
|qaverify_PREMISEPARTIAL|4|Premises partial|
|qaverify_STREETPARTIAL|5|Street partial|
|qaverify_MULTIPLE|6|Multiple matches|

Selects a picklist item from a picklist to expand further.

Prototype

INTRET QA_StepIn    ( INTVAL viHandle,
                      INTVAL viResult );

Arguments

viHandle Handle for this instance of the API
viResult Index of a picklist item

Return value

Either: 0 if call is successful

Or: Negative error code

Comments

The parameter viResult should be passed an index into the count of available picklist items from QA_GetSearchStatus, between 0 and the count - 1.

Error scenarios

Busy Handle : The parameter viHandle has been passed a handle that is already in use in another thread. Each handle can only be used by one thread at any point in time.
Bad Index The value passed to parameter viResult was not a valid picklist item offset. The range should be between 0 and the picklist result count - 1.
Bad Step The picklist result item that was passed into viResult is not an item that can be stepped into. Only picklist items that have the flag qaresult_CANSTEP from QA_GetResult can be stepped into.

Steps back a stage in a search, returning to the previous list of items.

This is not possible if a step in has not been performed. If QA_StepOut is called before QA_StepIn, an error will be returned. The search state qastate_ CANSTEPOUT can be used to determine whether QA_StepOut can be called.

Prototype

INTRET <a href="/address-validation/pro-api/7.98/integration/api-function-reference/#qa-step-out-steps-out-of-a-picklist-item" target="_self" title="">QA_StepOut</a>   ( INTVAL viHandle );

Arguments

viHandle Handle for this instance of the API

Return value

Either: 0 if call is successful

Or: Negative error code

Error scenarios

Busy Handle : The parameter viHandle has been passed a handle that is already in use in another thread. Each handle can only be used by one thread at any point in time.
Out of Sequence The API cannot 'step out' of a picklist if a search has not been yet performed.
Bad Step The picklist cannot be stepped out from, as it is at the top level. This can be checked through the API by calling QA_GetSearchStatus and checking for the flag qastate_ CANSTEPOUT.

Obtains limited information about a given picklist item. The result count comes from QA_GetSearchStatus.

The flags that are returned for a given picklist item indicate what actions can be performed upon it; for example, you can only step into a result using QA_StepIn if it has a qaresult_CANSTEP flag: otherwise an error will be returned.

Prototype

INTRET QA_GetResult     ( INTVAL viHandle,
                          INTVAL viResult,
                          STRREF rsDescription,
                          INTVAL viDescriptionLength,
                          INTREF riConfidence,
                          LONGREF rlFlags );

Arguments

viHandle Handle for this instance of the API
viResult Index into available results
rsDescription Result text that will be displayed in the picklist
viDescriptionLength Size of rsDescription
riConfidence Confidence score of match
rlFlags Flags describing the type of the given picklist item

Return value

Either: 0 if call is successful

Or: Negative error code

Comments

The parameter viResult should be passed an index into the count of available picklist items from QA_GetSearchStatus, between 0 and the count - 1.

The value returned in riConfidence is an indication of how good a match is. The maximum value is 100%.

The parameter rsDescription returns the text of each result item. The result shows only enough information for your users to be able to distinguish between different matches. This element should be shown in a picklist to your users to allow them to choose the result to step in to.

The parameter rlFlags can return the following flags ORed together.

Symbolic Name Decimal Value Description
qaresult_FULLADDRESS 1 You have reached the full deliverable address and you can now call QA_FormatResult.
qaresult_MULTIPLES 2 This item represents multiple address lines.
qaresult_CANSTEP 4 This item can be stepped into, using QA_StepIn.
qaresult_ALIASMATCH 8 The match is an alias.
qaresult_ POSTCODERECODED 16 The picklist item has a recoded postcode. This is currently only available with GBR data; please refer to your Data Guide for more information.
qaresult_ CROSSBORDERMATCH 32 The picklist item represents a nearby area outside the strict boundaries of the initial search. This applies to bordering localities, which are only relevant to AUS data.
qaresult_DUMMYPOBOX 64 The item is the dummy PO Box item.
qaresult_NAME 256 The picklist item is a Names result.
qaresult_INFORMATION 1024 The result item is an informational prompt.
qaresult_WARNINFORMATION 2048 Warning informational prompt item.
qaresult_INCOMPLETEADDR 4096 The dummy item in premise-less countries.
qaresult_ UNRESOLVABLERANGE 8192 QA_StepIn. Instead, you must type text to refine the picklist further to generate the desired complete address. The item itself should not be handled as a special case, but a GUI integration may choose a different icon to display.">A static range item that cannot be expanded. This applies to USA data and some European datasets only.
qaresult_PHANTOMPRIMARYPOINT 32768 The picklist item is a phantom primary point.

Error scenarios

Busy Handle: The parameter viHandle has been passed a handle that is already in use in another thread. Each handle can only be used by one thread at any point in time.
Bad Index: The value passed to parameter viResult was not a valid picklist item offset. The range should be between 0 and the picklist result count - 1.

Obtains limited information about a picklist item. The result count comes from QA_GetSearchStatus.

Prototype

INTRET QA_GetResultDetail   ( INTVAL viHandle,
                              INTVAL viResult,
                              INTVAL viType,
                              LONGREF rlDetail,
                              STRREF rsDetail,
                              INTVAL viDetailLength );

Arguments

viHandle Handle for this instance of the API
viResult Index into available results
viType Type of result detail requested
rlDetail Returned detail integer
rsDetail Returned detail string
viDetailLength Length of rsDetail

Return value

Either: 0 if call is successful

Or: Negative error code

Comments

The parameter viResult should be passed an index into the count of available picklist items from QA_GetSearchStatus, between 0 and the count - 1.

If the symbolic name of the result detail type passed to viType is prefixed with qaresultstr_ then a string will be returned through the rsDetail parameter. If the symbolic name is prefixed with qaresultint_ then an integer will be returned through the rlDetail parameter.

The parameter viType is used to specify what piece of information you want to be returned. It can take one of the following values:

Symbolic Name Decimal Value Description
qaresultstr_DESCRIPTION 2 Return the text description for the given item, suitable for displaying in a picklist.
qaresultstr_PARTIALADDRESS 3 Return the partial address for the given result, formatted in a single line.
qaresultint_ISFULLADDRESS 13 Return whether the given item is a full deliverable address and you can now call QA_FormatResult.
qaresultint_ISMULTIPLES 14 Return whether the given item represents multiple address lines.
qaresultint_ISCANSTEP 15 Return whether the given item can be stepped into, using QA_StepIn.
qaresultint_ISALIASMATCH 16 Return whether the given item is an alias.
qaresultint_ ISPOSTCODERECODED 17 The picklist item has a recoded postcode. This is currently only available with GBR data; please refer to your Data Guide for more information.
qaresultint_ ISCROSSBORDERMATCH 18 Return whether the given item represents a nearby area outside the strict boundaries of the initial search. This applies to bordering localities, which are only relevant to AUS data.
qaresultint_ISDUMMYPOBOX 19 Return whether the given item is the dummy PO Box item.
qaresultint_ISNAME 20 Return whether the given item is a Names result.
qaresultint_ISINFORMATION 21 Return whether the given item is an informational prompt.
qaresultint_ ISWARNINFORMATION 22 Return whether the given item is a warning informational prompt.
qaresultint_ ISINCOMPLETESADDR 23 Return whether the given item is a dummy item in premise-less countries.
qaresultint_ ISUNRESOLVABLERANGE 24 QA_StepIn. Instead, you must type text to refine the picklist further to generate the desired complete address. The item itself should not be handled as a special case, but a GUI integration may choose a different icon to display.">Return whether the given item is a static range item that cannot be expanded. This applies to USA data only.
qaresultint_ISPHANTOMPRIMARYPOINT 28 Returns whether the address is a phantom primary point. This applies to AUS data only.

For the types that are prefixed qaresultint_IS, the following values can be returned from the parameter rlDetail:

|Boolean Values|
|---|---|---|
|qavalue_FALSE|0|False|
|qavalue_TRUE|1|True|

Error scenarios

Busy Handle: The parameter viHandle has been passed a handle that is already in use in another thread. Each handle can only be used by one thread at any point in time.
Bad Index: The value passed to parameter viResult was not a valid picklist item offset. The range should be between 0 and the picklist result count - 1.

Selects a picklist item and applies the formatting routines to it. This is done according to the current active layout.

Prototype

INTRET QA_FormatResult  ( INTVAL viHandle,
                          INTVAL viResult,
                          STRVAL vsExtra,
                          INTREF riLineCount,
                          LONGREF rlInfo );

Arguments

viHandle Handle for this instance of the API
viResult The picklist item to be formatted
vsExtra Extra text to add to the formatted address
riLineCount The number of lines that have been formatted
rlInfo Information about the formatted result

Return value

Either: 0 if call is successful

Or: Negative error code

Comments

The parameter viResult should be passed an index into the count of available picklist items from QA_GetSearchStatus or QA_GetSearchStatusDetail, between 0 and count - 1.

The parameter rlInfo can return the following flags ORed together:

Symbolic Name Decimal Value Description
qaformat_OVERFLOW 1 There are not enough address lines configured to display the full address.
qaformat_TRUNCATED 2 Truncation has occurred on one or more address lines in the final address.
qaformat_DPV_CONFIGURED 4 DPV is available and appropriate.
qaformat_DPV_CONFIRMED 16 DPV-confirmed.
qaformat_DPV_SEED 32 A DPV seed address.
qaformat_DPV_LOCKED 64 DPV functionality is locked.
qaformat_DPV_DATAUPDATING 128 DPV data is updating.
qaformat_DPV_UNCONFIRMEDSEC 256 DPV is confirmed but the secondary number is missing or incorrect.
qaformat_POSS_MISSINGSEC 512 This is currently only relevant when using Canada data. This attribute indicates that the address is a large volume receiver and may be missing subpremises information.
qaformat_DPV_CMRA 1024 DPV confirmed but the address is a Commercial Mailing Receiving Agency (CMRA).

The parameter vsExtra allows you to pass through text that you want to add to the formatted address. This is typically used when you have refined on text that is not in the data, but that you wish to use in the final address.

Error scenarios

Busy Handle: The parameter viHandle has been passed a handle that is already in use in another thread. Each handle can only be used by one thread at any point in time.
Out of Sequence The API cannot format a result of a picklist if a search has not yet been performed.
Bad Index: The value passed to parameter viResult was not a valid picklist item offset. The range should be between 0 and the picklist result count - 1.
Bad Layout: The active layout that is set for the instance is invalid. The list of valid layouts can be obtained by using the QA_GetLayoutCount and QA_GetLayout functions. A layout may be defined for a specific dataset only, and so changing the active data set may invalidate the active layout.

Returns the given formatted address line.

Prototype

INTRET QA_GetFormattedLine      ( INTVAL viHandle,
                                  INTVAL viLine,
                                  STRREF rsFormattedLine,
                                  INTVAL viFormattedLineLength,
                                  STRREF rsLabel,
                                  INTVAL viLabelLength,
                                  LONGREF rlContents );

Arguments

viHandle Handle for this instance of the API
viLine The layout line to return
rsFormattedLine The buffer to receive the formatted line
viFormattedLineLength The size of rsFormattedLine
rsLabel Label for the line
viLabelLength The size of rsLabel
rlContents Flags describing the contents of the line

Return value

Either: 0 if call is successful

Or: Negative error code

Comments

The parameter viLine should be passed an index into the count of formatted lines from QA_FormatResult or QA_FormatExample, between 0 and the count - 1.

The parameter rsLabel will return the name of any individual address element fixed to the line. If there are no elements (or more than one element) fixed to the line, this will be blank.

The parameter rlContents can return the following flags ORed together:

Symbolic Name Decimal Value Description
qaformatted_NAME 1 There are name elements fixed to this line.
qaformatted_ADDRESS 2 There are address elements fixed to this line.
qaformatted_ANCILLARY 4 There are ancillary elements fixed to this line.
qaformatted_DATAPLUS 8 There are dataplus elements fixed to this line.
qaformatted_TRUNCATED 16 Truncation occurred on this line, due to the width being too small.
qaformatted_OVERFLOW 32 Some elements were lost from this line, due to the width being too small and not enough lines being defined.
qaformatted_DATAPLUSSYNTAX 64 Dataplus is badly configured upon this line due to invalid syntax.
qaformatted_DATAPLUSEXPIRED 128 Dataplus is badly configured upon this line as it has expired.
qaformatted_DATAPLUSBLANK 256 Dataplus is blank on this line as there was no appropriate value in the data to return.
qaformatted_UNMATCHED 512 Line contains retained unmatched text.

Error scenarios

Busy Handle : The parameter viHandle has been passed a handle that is already in use in another thread. Each handle can only be used by one thread at any point in time.
Bad Index The value passed to parameter viLine was not a valid data offset. The range should be between 0 and the count of data - 1 from QA_FormatResult or QA_FormatExample.

Returns the number of available example addresses for the current data set. The example addresses can be formatted and retrieved using QA_FormatExample and QA_GetFormattedLine.

Prototype

INTRET QA_GetExampleCount   ( INTVAL viHandle,
                              INTREF riExampleCount );

Arguments

viHandle Handle for this instance of the API
riExampleCount The count of example addresses that exist for the given dataset

Return value

Either: 0 if call is successful

Or: Negative error code

Comments

The Zero example number always exists and is a blank example address, useful for obtaining the number of layout lines.

Error scenarios

Busy Handle: The parameter viHandle has been passed a handle that is already in use in another thread. Each handle can only be used by one thread at any point in time.
Bad Layout: The active layout that is set for the instance is invalid. The list of valid layouts can be obtained by using the QA_GetLayoutCount and QA_GetLayout functions. A layout may be defined for a specific dataset only, and so changing the active data set may invalidate the active layout.

Each dataset has example addresses, which can be used to preview layouts.

QA_FormatExample formats an example in the current active layout. Sample address lines can be retrieved by calling QA_GetFormattedLine.

Prototype

INTRET QA_FormatExample      ( INTVAL viHandle,
                               INTVAL viExample,
                               STRREF rsComment,
                               INTVAL viCommentLength,
                               INTREF riLineCount,
                               LONGREF rlInfo );

Arguments

viHandle Handle for this instance of the API
viExample The index of the example to format
rsComment A comment describing the example address
viCommentLength The size of the rsComment buffer
riLineCount The number of lines that have been formatted
rlInfo Information about the formatted example

Return value

Either: 0 if call is successful

Or: Negative error code

The 'Zero' example number always exists and is a blank example address, useful for getting the number of layout lines.

Comments

The parameter viExample should be passed an index into the count of example address from QA_GetExampleCount, between 0 and the count - 1.

The parameter rlInfo can return the following flags ORed together:

Symbolic Name Decimal Value Description
qaformat_OVERFLOW 1 There are not enough address lines configured to display the full address.
qaformat_TRUNCATED 2 Truncation has occurred on one or more address lines in the final address.
qaformat_DPV_CONFIGURED 4 DPV is available and appropriate.
qaformat_DPV_CONFIRMED 16 DPV-confirmed.
qaformat_DPV_SEED 32 A DPV seed address.
qaformat_DPV_LOCKED 64 DPV functionality is locked.
qaformat_DPV_DATAUPDATING 128 DPV data is updating.
qaformat_DPV_UNCONFIRMEDSEC 256 DPV is confirmed but the secondary number is missing or incorrect.
qaformat_POSS_MISSINGSEC 512 Currently only relevant when using Canada data. This attribute indicates that the address is a large volume receiver and may be missing subpremises information.
qaformat_DPV_CMRA 1024 DPV confirmed but the address is a Commercial Mailing Receiving Agency (CMRA).

Error scenarios

Busy Handle: The parameter viHandle has been passed a handle that is already in use in another thread. Each handle can only be used by one thread at any point in time.
Bad Index: The value passed to parameter viExample was not a valid example address offset. The range should be between 0 and the count of example addresses - 1 from [QA_GetExampleCount](/address-validation/pro-api/7.98/integration/api-function-reference/#qa-get-example-count-returns-the-number-of-example-addresses-for-the-given-dataset.
Bad Layout: The active layout that is set for the instance is invalid. The list of valid layouts can be obtained by using the QA_GetLayoutCount and QA_GetLayout functions. A layout may be defined for a specific dataset only, and so changing the active data set may invalidate the active layout.

Retrieves the number of available layouts in the configuration file for the active dataset.

Prototype

INTRET QA_GetLayoutCount    ( INTVAL viHandle,
                              INTREF riCount );

Arguments

viHandle Handle for this instance of the API
riCount Number of available layouts in the configuration file

Return value

Either: 0 if call is successful

Or: Negative error code

Error scenarios

Busy Handle: The parameter viHandle has been passed a handle that is already in use in another thread. Each handle can only be used by one thread at any point in time.

Returns information about the given layout. You can call this multiple times to get a list of all layouts for the currently active dataset.

Pre-call Conditions

The function QA_GetLayoutCount should be called prior to this.

Prototype

INTRET QA_GetLayout     ( INTVAL viHandle,
                          INTVAL viLayout,
                          STRREF rsName,
                          INTVAL viNameLength,
                          STRREF rsComment,
                          INTVAL viCommentLength );

Arguments

viHandle Handle for this instance of the API
viLayout Layout to return
rsName Name of layout
viNameLength Length of rsName
rsComment Layout comment
viCommentLength Length of rsComment

Return value

Either: 0 if call is successful

Or: Negative error code

Comments

The parameter viLayout should be passed an index into the count of available layouts from QA_GetLayoutCount, between 0 and the count - 1.

You can set the layout comment when you create a layout. You may choose to display this comment to users when they change layout.

Error scenarios

Busy Handle: The parameter viHandle has been passed a handle that is already in use in another thread. Each handle can only be used by one thread at any point in time.
Bad Index: The value passed to parameter viLayout was not a valid data offset. The range should be between 0 and the count of data - 1 from QA_GetLayoutCount.

Retrieves the layout that is currently active. This will be used for formatting the returned address.

Prototype

INTRET QA_GetActiveLayout   ( INTVAL viHandle,
                              STRREF rsName );
                              INTVAL viNameLength );

Arguments

viHandle Handle for this instance of the API
rsName Number of available layouts in the configuration file
viNameLength Length of rsName

Return value

Either: 0 if call is successful

Or: Negative error code

Error scenarios

Busy Handle: The parameter viHandle has been passed a handle that is already in use in another thread. Each handle can only be used by one thread at any point in time.

This sets the layout that is used to format a final address. Layout names are retrieved using QA_GetLayout which can be used to get all available layouts.

Some layouts are defined only for specific datasets and so changing the active dataset may invalidate the active layout. The integration must ensure that either:

  • All layout names are defined for all available datasets (advised)

    or

  • The integration checks that the active layout is still valid when the active dataset is changed by calling QA_GetLayoutCount and QA_GetLayout.

You can call this function once a search has begun, although it will not affect an address that has already been formatted using QA_FormatResult or QA_FormatExample. If you wish to reformat an address using a different layout then you must recall the appropriate formatting function after changing the active layout.

Prototype

INTRET QA_SetActiveLayout   ( INTVAL viHandle,
                              STRVAL vsLayout );

Arguments

viHandle Handle for this instance of the API
vsLayout Layout name as retrieved by QA_GetLayout

Return value

Either: 0 if call is successful

Or: Negative error code

Comments

The parameter vsLayout can optionally be passed a blank string instead of a valid layout name. This will set the layout to the default layout as specified in the [QADefault] section of the configuration file, or to an internal layout if this does not exist. This allows the integrator to specify a layout that is guaranteed to be valid for the active dataset.

Error scenarios
Busy Handle: The parameter viHandle has been passed a handle that is already in use in another thread. Each handle can only be used by one thread at any point in time.
Bad Layout: The active layout that is set for the instance is invalid. The list of valid layouts can be obtained by using the QA_GetLayoutCount and QA_GetLayout functions. A layout may be defined for a specific dataset only, and so changing the active dataset may invalidate the active layout.

Returns a count of the available datasets, which can be manually specified using the DataMappings setting in the qawserve.ini file.

This must be called before the data accessor function QA_GetData is used.

The count returned by this method is the number of separate datasets that can be passed to QA_SetActiveData, which sets the active dataset to be searched on.

Prototype

INTRET QA_GetDataCount  ( INTVAL viHandle,
                          INTREF riCount );

Arguments

viHandle Handle for this instance of the API
riCount Count of datasets

Return value

Either: 0 if call is successful

Or: Negative error code

Error scenarios

Busy Handle: The parameter viHandle has been passed a handle that is already in use in another thread. Each handle can only be used by one thread at any point in time.

Returns information about a given dataset. You can call this multiple times to get information about all available datasets, which can be manually specified using the DataMappings setting in the qawserve.ini file

Pre-call Conditions

The function QA_GetDataCount must be called before this function.

Prototype

INTRET QA_GetData   ( INTVAL viHandle,
                      INTVAL viDataOffset,
                      STRREF rsDataID,
                      INTVAL viDataIDLength,
                      STRREF rsName,
                      INTVAL viNameLength );

Arguments

viHandle Handle for this instance of the API
viDataOffset Index into dataset count
rsDataID Buffer returning the ID of the dataset
viDataIDLength Length of rsDataID
rsName Buffer returning dataset
viNameLength Length of rsName

Return value

Either: 0 if call is successful

Or: Negative error code

Comments

The parameter viDataOffset should be passed an index into the available data count from QA_GetDataCount, between 0 to the count - 1.

The data ID returned from the parameter rsDataID is a short string identifying the dataset. This can be passed to QA_SetActiveData in order to change the current dataset being searched upon.

Error scenarios

Busy Handle: The parameter viHandle has been passed a handle that is already in use in another thread. Each handle can only be used by one thread at any point in time.
Out of Sequence The function QA_GetDataCount must have been called prior to this function.
Bad Index: The value passed to parameter viDataOffset was not a valid data offset. The range should be between 0 and the count of data - 1 from QA_GetDataCount.

Obtains the data ID of the active dataset. This is the dataset that will be used to search on.

The data ID is a short string that uniquely identifies the dataset. The available data IDs for all installed datasets can be returned using QA_GetDataCount and QA_GetData.

Prototype

INTRET QA_GetActiveData     ( INTVAL viHandle,
                              STRREF rsDataID,
                              INTVAL viDataIDLength );

Arguments

viHandle Handle for this instance of the API
rsDataID Buffer returning data ID of active dataset
viDataIDLength Length of rsDataID

Return value

Either: 0 if call is successful

Or: Negative error code

Error scenarios

Busy Handle: The parameter viHandle has been passed a handle that is already in use in another thread. Each handle can only be used by one thread at any point in time.

Sets the active dataset to be searched upon. Data IDs for datasets are retrieved using QA_GetData which can be used to list all available datasets.

If the active dataset is changed once a search has begun, this will end the current search and reset all results.

Some layouts are defined only for specific datasets, and so changing the active dataset may invalidate the active layout.

Prototype

INTRET QA_SetActiveData     ( INTVAL viHandle,
                              STRVAL vsDataID );

Arguments

viHandle Handle for this instance of the API
vsDataID Data ID of the dataset to use

Return value

Either: 0 if call is successful

Or: Negative error code

Comments

If you pass a blank string to vsDataID, the active data will be set to the first usable dataset found by the system.

Error scenarios

Data Not Available: The dataset specified in parameter vsDataID is unavailable. This should be passed dataset IDs as returned by QA_GetDataCount and QA_GetData.

Returns the total number of licensed datasets, including DataPlus sets, that are available. This total includes all servers that the API is using. Data duplicated across servers will be reported multiple times. This function can be used to report the most serious warning that applies to the set of licensed data. This is useful to check that there are no immediate or impending issues with the installed data, without interrogating each set individually using QA_GetLicensingDetail.

If a count of datasets available to search with is required, use the QA_GetDataCount function instead.

Prototype

INTRET QA_GetLicensingCount     ( INTVAL viHandle,
                                  INTREF riCount,
                                  LONGREF rlWarningLevel );

Arguments

viHandle Handle for this instance of the API
riCount The count of licensed datasets
rlWarningLevel Warning level for the set of licensed data

Return value

Either: 0 if call is successful

Or: Negative error code

Comments

The parameter rlWarningLevel will return one of the following values (sorted in increasing order of urgency and importance):

Symbolic Name Decimal Value Description
qalicwarn_NONE 0 No license warning
qalicwarn_DATAEXPIRING 10 A dataset is about to expire
qalicwarn_LICENCEEXPIRING 20 A license is about to expire
qalicwarn_EVALUATION 30 Data is on an evaluation license
qalicwarn_DATAEXPIRED 40 A dataset has expired
qalicwarn_ EVALLICENCEEXPIRED 50 An evaluation license has expired
qalicwarn_ FULLLICENCEEXPIRED 60 A full license has expired
qalicwarn_LICENCENOTFOUND 70 Licence information cannot be found for a dataset
qalicwarn_DATAUNREADABLE 80 A dataset is not readable

Error scenarios

Busy Handle: The parameter viHandle has been passed a handle that is already in use in another thread. Each handle can only be used by one thread at any point in time.

Returns detailed information about a given licensed dataset. The count of licensed datasets can be obtained from the function QA_GetLicensingCount.

Prototype

INTRET QA_GetLicensingDetail    ( INTVAL viHandle,
                                  INTVAL viLicence,
                                  INTVAL viType,
                                  LONGREF rlDetail,
                                  STRREF rsDetail,
                                  INTVAL viDetailLength );

Arguments

viHandle Handle for this instance of the API
viLicence Index into count of licensed datasets
viType Type of information detail to return
rlDetail Integer detail
rsDetail String detail
viDetailLength Length of rsDetail

Return value

Either: 0 if call is successful

Or: Negative error code

Comments

The parameter viLicence should be passed an index into the count of licensed datasets from QA_GetLicensingCount, between 0 and the count - 1.

If the symbolic name of the result detail type passed to viType is prefixed with qalicensestr_ then a string will be returned through the rsDetail parameter. If the symbolic name is prefixed with qalicenseint_ then an integer will be returned through the rlDetail parameter.

The parameter viType is used to specify what piece of information you want to be returned. It can take one of the following values:

Symbolic Name Decimal Value Description
qalicensestr_ID 1 Returns the dataset name
qalicensestr_DESCRIPTION 2 Returns a brief description of what the dataset represents
qalicensestr_COPYRIGHT 3 Returns the copyright information for the dataset
qalicensestr_VERSION 4 Returns the version of the data
qalicensestr_BASECOUNTRY 5 Returns the data ID of the country to which the dataset is an extension
qalicensestr_STATUS 6 Returns the string describing the state of the data; for example if it is about to expire.
qalicensestr_SERVER 7 Returns the server name of where the dataset is being used
qalicenseint_WARNINGLEVEL 8 Returns the warning level for the dataset. This can take one of the values listed in the following table.
qalicenseint_DAYSLEFT 9 Returns the number of days left before the dataset is unusable
qalicenseint_DATADAYSLEFT 10 Return the number of days left before the data expires
qalicenseint_ LICENCEDAYSLEFT 11 Return the number of days left until the dataset license expires

The following warning levels can be returned for the qalicenseint_ WARNINGLEVEL detail type:

Symbolic Name Decimal Value Description
qalicwarn_LICENCEEXPIRING 20 A license is about to expire
qalicwarn_EVALUATION 30 Data is on an evaluation license
qalicwarn_DATAEXPIRED 40 A dataset has expired
qalicwarn_ EVALLICENCEEXPIRED 50 An evaluation license has expired
qalicwarn_ FULLLICENCEEXPIRED 60 A full license has expired
qalicwarn_LICENCENOTFOUND 70 Licence information cannot be found for a dataset
qalicwarn_DATAUNREADABLE 80 A dataset is not readable

Error scenarios

Busy Handle: The parameter viHandle has been passed a handle that is already in use in another thread. Each handle can only be used by one thread at any point in time.

Generates information regarding the state of the system. You can then interrogate this with the function QA_GetSystemInfo.

Prototype

INTRET QA_GenerateSystemInfo    ( INTVAL viHandle,
                                  INTVAL viType,
                                  INTREF riCount );

Arguments

viHandle Handle for this instance of the API
viType Type of information to generate
riCount Count of lines generated

Return value

Either: 0 if call is successful

Or: Negative error code

Comments

The following values can be passed to viType:

Symbolic Name Decimal Value Description
qasysinfo_SYSTEM 1 Generate the current state of the system

Error scenarios

Busy Handle: The parameter viHandle has been passed a handle that is already in use in another thread. Each handle can only be used by one thread at any point in time.

Gets a line of the system information produced by QA_GenerateSystemInfo.

Prototype

INTRET QA_GetSystemInfo     ( INTVAL viHandle,
                              INTVAL viLine,
                              STRREF rsBuffer,
                              INTVAL viBufferLength );

Arguments

viHandle Handle for this instance of the API
viLine Line number to extract
rsBuffer Returned system information line
viBufferLength Size of rsBuffer

Return value

Either: 0 if call is successful

Or: Negative error code

Comments

The parameter viLine should be passed an index into the count of generated system information lines from QA_GenerateSystemInfo, between 0 and the count - 1.

Error scenarios

Busy Handle: The parameter viHandle has been passed a handle that is already in use in another thread. Each handle can only be used by one thread at any point in time.
Bad Index: The value passed to parameter viLine was not a valid line of generated system information. The range should be between 0 and the count of lines - 1 from QA_GenerateSystemInfo.

The Pro API includes various functions that are specific to the DPV system. You only need to integrate these functions if you do not intend to use the DPV Unlock Utility supplied with Pro API.

Used to query the lock code generated by the product where DPV is disabled in the event of a seed address being searched upon. It is this code that must be reported back to Experian, in order for Experian to generate a corresponding unlock key. Since the lock code varies in length, QA_DPVGetCodeLength should be called in order to make sure the buffer provided is large enough for the lock code.

Prototype

INTRET QA_DPVGetCode    ( INTVAL viHandle,
                          STRREF rsLockCode,
                          INTVAL viLockCodeLength );

Arguments

viHandle Handle for this instance of the API
rsLockCode Buffer to receive lock code
viLockCodeLength Length of provided buffer rsLockCode

Return value

Either: 0 if call is successful (lock code has been stored in the supplied buffer).

Or: Negative error code

Comments

When DPV is disabled by a seed address, Pro API generates a variable length alphanumeric code which is required to unlock DPV. If you do not call QA_DPVGetCodeLength to determine the length of the lock code then the supplied buffer may not be large enough. If truncation occurs while populating the buffer rsLockCode, this will be signalled in the error log. If an error occurs and it is possible to populate the buffer rsLockCode, then this will be zero terminated.

Error scenarios

Not running: The API has not been started properly. QA_Open must be successfully called prior to this function.

Returns the length of the lock code generated by the product where DPV is disabled in the event of a seed address being searched upon. This function should be called before QA_DPVGetCodeLength in order to ensure an adequate buffer is supplied to that function to obtain the lock code.

Prototype

INTRET QA_DPVGetCodeLength      ( INTVAL viHandle,
                                  INTREF riCodeLength );

Arguments

viHandle Handle for this instance of the API
riCodeLength Length of the lock code

Return value

Either: 0 if call is successful

Or: Negative error code

Comments

Pro API generates an alphanumeric lock code when DPV is disabled. The code can vary in length, so this function should be called before QA_DPVGetCode in order to ensure an adequate buffer is supplied to that function when obtaining the lock code.

Error scenarios

Not running The API has not been started properly. QA_Open must be successfully called prior to this function.

Returns information about the DPV seed address which caused DPV to be disabled. The USPS require this information to be submitted before an unlock key can be issued.

Prototype

INTRET QA_DPVGetInfo    ( INTVAL viHandle,
                          INTVAL viDPVInfoType,
                          STRREF rsDPVInfo,
                          INTVAL viLength );

Arguments

viHandle Handle for this instance of the API
viDPVInfoType Type of lock information to be returned
rsDPVInfo Buffer to receive lock information
viLength Length of provided buffer rsDPVInfo

Return value

Either: 0 if call is successful (lock information has been stored in the supplied buffer).

Or: Negative error code

Comments

The possible values of viDPVInfoType are:

|Value|Description|
|-|-|
|dpvlockinfo_DATE|Returns the date the seed address was encountered.|
|dpvlockinfo_TIME|Returns the time the seed address was encountered.|
|dpvlockinfo_SEED|Returns the seed address that was searched upon.|
|dpvlockinfo_SESSION|Returns the name of the session in use when the seed address was encountered.|

If the DPV has not been disabled by a seed address, or if the status of the DPV system cannot be determined, this function will return blank strings.

If truncation occurs while populating the buffer rsDPVInfo, this will be signalled in the error log. If an error occurs and it is possible to populate the buffer rsDPVInfo, then this will be zero terminated.

Error scenarios

Not running: The API has not been started properly. QA_Open must be successfully called prior to this function.
Bad parameter One of the API parameters has been passed an invalid value.

Sets an unlock key to re-enable DPV functionality where the DPV functionality is disabled (i.e. key supplied by Experian following the reporting of the corresponding lock code).

Prototype

INTRET QA_DPVSetKey     ( INTVAL viHandle,
                          STRVAL vsUnlockKey );

Arguments

viHandle Handle for this instance of the API
vsUnlockKey Buffer containing the unlock key

Return value

Either: 0 if call is successful (the unlock code has re-enabled the DPV system)

Or: Negative error code

Error scenarios

Not running: The API has not been started properly. QA_Open must be successfully called prior to this function.
Invalid key The key specified in parameter vsUnlockKey is not the valid key required to unlock the DPV system. The DPV unlock key should be as provided by Experian.

Determines whether DPV functionality is enabled, disabled, or not in use. This information can also be determined on a per-search basis through the use of the additional dataset-specific information component of Pro's return code.

Prototype

INTRET QA_DPVState      ( INTVAL viHandle,
                          INTREF riDPVState );

Arguments

viHandle Handle for this instance of the API
riDPVState Returned state of the DPV system

Return value

Either: 0 if call is successful (DPV state has been determined)

Or: Negative error code

Comments

The argument riDPVState will be populated with one of the following values:

State Macro Explanation
-1 DPVstate_Unknown Returned by the function in the event of an error.
0 DPVstate_NotInUse The DPV system is not in use (Configuration setting DPV=False).
1 DPVstate_Enabled The DPV system is enabled.
2 DPVstate_Disabled The DPV system has been disabled following a seed address search.

Error scenarios

Not running: The API has not been started properly. QA_Open must be successfully called prior to this function.

This function performs а post code search and returns the search' status code. To retrieve the results from a successful post code search you need to call the QA_PostcodeLookupGetRecord API function. Currently the post code lookup is supported for USA and Australian post codes.

Prototype

INTRET QA_PostcodeLookup    ( INTVAL viHandle,
                              STRVAL rsCountryCode,
                              STRVAL rsPostcode,
                              INTREF riMatchesNumber
                              VOIDREFREF rpHandle );

Arguments

viHandle Handle for this instance of the API
rsCountryCode 3-length country code. Examples: USA, AUS
rsPostcode The searched post code
riMatchesNumber Number of returned matches
rpHandle Handle to the result matches

Return value

Either: 0 if call is successful

Or: Negative error code

Possible Error Codes

-4558 qaerr_BADPARAM
-4552 qaerr_APIHANDLE
-4575 qaerr_NOCOUNTRYFOUND
-4570 qaerr_DATASETNOTAVAILABLE

This function can be called after a successful call to QA_PostcodeLookup to retrieve the different result records of the post code lookup.

Prototype

INTRET QA_PostcodeLookupGetRecord ( INTVAL viHandle,
                                    INTVAL viRecordIndex,
                                    VOIDREF vpHandle
                                    STRREF rsRegion,
                                    INTVAL  viRegionLength,
                                    STRREF rsTown,
                                    INTVAL  viTownLength,
                                    STRREF rsSubregion,
                                    INTVAL viSubregionLength);

Arguments

viHandle Handle for this instance of the API
viRecordIndex Index of the matching record to be returned
vpHandle Handle to the post code lookup matches
rsRegion Matched record's region/state
viRegionLength Region's buffer's length
rsTown Matched record's town/city
viTownLength Towns buffers length
rsSubregion Matched records subregion/county
viSubregionLength Subregion's buffers length

Return value

Either: 0 if call is successful

Or: Negative error code

Possible Error Codes

-4558 qaerr_BADPARAM
-4552 qaerr_APIHANDLE

Frees previously allocated memory for storing post code lookup matches. Should be called on each successful call of QA_PostcodeLookup.

Prototype

INTRET QA_PostcodeLookupClose   (INTVAL iHandle
                                 VOIDREF vpHandle);

Arguments

iHandle Handle for this instance of the API
vpHandle Handle to the post code lookup matches

Return value

Either: 0 if call is successful

Or: Negative error code

Possible Error Codes

-4558 qaerr_BADPARAM
-4552 qaerr_APIHANDLE

Comments

Not calling this API function when there is a previous successful call to QA_PostcodeLookup will cause a memory leak in your program.

General Error scenarios (all functions)

Bad Parameter

One of the API parameters has been passed an invalid value. Use the LogErrors configuration setting to determine where the problem lies

Bad Handle

The parameter viHandle has been passed an invalid handle. This should only be passed values returned from QA_Open that have not since been closed.

Server Error

An error has occurred on the server. This may be due to the server running out of resource, or to connection issues. This error may be returned in a non client-server integration if the 'server' side of the application runs out of resource, such as memory.

Licensing Error

The active dataset you are attempting to use may not be licensed properly and will return an error. Check that the data is correctly installed and licensed, and use the LogErrors configuration setting to determine where the problem lies.

Pro API

Integration