API function reference

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:

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:

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:

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:

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:

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):

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:

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::

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/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.

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:

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:

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:

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:

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/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):

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:

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

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:

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.

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:

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.