User Interface API function reference

Performs a search on the input string.

Pre-call conditions

The API has been started with QAProWV_UIStartup.

Prototype

INTRET QAProWV_UISearch ( STRVAL vsSearch );

Arguments

vsSearch Input string to search on

Return value

Either: Positive value for successful search

Or: 0 if call is successful

Or: Negative error code

Possible error codes

• -3407 qaerr_UIAPINOTSTARTED

Comments

If the specified search returns a single matching property, and the qaattribs_ NOCONFIRMVIEW and qaattribs_MINDISPLAY flags are in effect, it can be retrieved immediately by calling QAProWV_UIResultCount and QAProWV_UIGetResult.

Otherwise, the search results will be displayed in the Pro User Interface for the user to interactively confirm, before this function returns. Note that the final address screen will always be displayed to the user for confirmation if:

• DPV is configured and the address is not DPV confirmed;
• The Verification engine is in use and the address is not Verified.

Returns a count of the number of address lines in a selected address.

Pre-call conditions

The API has been started with QAProWV_UIStartup, and a search has been submitted with QAProWV_UISearch.

Prototype

INTRET QAProWV_UIResultCount ( INTREF riCount );

Arguments

riCount Number of address lines

Return value

Either: 0 if call is successful

Or: Negative error code

Possible error codes

-3407 qaerr_UIAPINOTSTARTED

Comments

This function tells you the number of lines in the final selected address, and hence how many times the function QAProWV_UIGetResult needs to be called in order to retrieve them.

Retrieves one line of a returned address.

Pre-call conditions

The API has been started with QAProWV_UIStartup, and a search has been started with QAProWV_UISearch.

Protoype

INTRET QAProWV_GetResult        (   INTVAL viIndex,
                                     STRREF rsBuffer,
                                     INTVAL viLength );

Arguments

viIndex Number of layout to retrieve (from 0 to QAProWV_UILayoutCount -1)
rsBuffer Buffer to receive search result
viLength Maximum length of rsBuffer

Return value

Either: 0 if call is successful
Or: Negative error code

Possible error codes

-3407 qaerr_UIAPINOTSTARTED
-3803 qaerr_INVALIDADDRESSLINE

Comments

This function returns one formatted address line from a search. You get the total number of address lines from the function QAProWV_UIResultCount.

You should call this function as many times as required to retrieve the full address. For example, if QAProWV_UIResultCount returned a count of 5 address lines, you would call this function five times to retrieve each item.

The parameter viIndex contains the number of the result line which you want to retrieve – for example, inputting 0 retrieves the description of the first line in the layout, 1 returns the second line, and so on. An error will be returned if an invalid line number is specified.

Retrieves the address details for an address selected from a returned picklist. This function also returns information to show the integrator whether or not a selected address has been modified by the user, whether the address is validated as a USPS Delivery Point (US data only), and whether the address has been truncated or whether any address details have been lost.

Pre-call conditions

The API has been started with QAProWV_UIStartup, and a search has been started with QAProWV_UISearch.

Prototype

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

Arguments

viType Type of result detail requested. Please refer to the following table for values for viType
rlDetail Returned integer detail
rsDetail Returned string detail
viDetailLength Length of rsDetail

Return value

Either: 0 if call is successful
Or: Negative error code

Comments

Most of the flags relate to the address that was returned to the final address screen. If the user edits that address, then the validity of the flags will be uncertain.

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 (to the final address screen):

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

Retrieves the number of available layouts in the configuration file.

Pre-call conditions

The API has been started with QAProWV_UIStartup.

Prototype

INTRET QAProWV_UILayoutCount ( INTREF riCount );

Arguments

riCount Number of layouts in the configuration file

Return value

Either: 0 if call is successful
Or: Negative error code

Possible error codes

-3407 qaerr_UIAPINOTSTARTED

Comments

This function tells you how many configuration layouts are available in your qawserve.ini file. The number available to use depends on the active country.

Once you have the number of layouts, you can call QAProWV_UIGetLayout as many times as is necessary to retrieve the name of each layout.

Retrieves the name of a particular configuration layout.

Pre-call conditions

QAProWV_UIStartup has been called to start the API. QAProWV_ UILayoutCount has been called to return a count of the available layouts.

Prototype

INTRET QAProWV_GetLayout ( INTVAL viIndex,
STRREF rsBuffer,
INTVAL viLength );

Arguments

viIndex Number of layout to retrieve (from 0 to QAProWV_ UILayoutCount -1)
rsBuffer Buffer to receive layout name
viLength Maximum length of rsBuffer

Return value

Either: 0 if call is successful
Or: Negative error code

Possible error codes

-3401 qaerr_INVALIDLAYOUTINDEX
-3407 qaerr_UIAPINOTSTARTED

Comments

This function, in conjunction with QAProWV_ UILayoutCount, is useful if you want to confirm the number and names of available configuration layouts prior to searching.

You should call this function as many times as required to retrieve layout names from a configuration file. For example, if QAProWV_ UILayoutCount returned a count of 6, you would call QAProWV_ UILayoutCount six times to retrieve each layout name.

The parameter viIndex contains the number of the layout whose name you want to retrieve – for example, inputting 0 retrieves the name of the first layout in the configuration file, 1 returns the name of the second layout, and so on. An error will be returned if an invalid number is passed into this parameter.

Retrieves the name of the current configuration layout.

Pre-call conditions

The API has been started with QAProWV_UIStartup.

Prototype

INTRET QAProWV_UIGetActiveLayout ( STRREF rsBuffer,
INTVAL viLength );

Arguments

rsBuffer Buffer to receive country identifier
viLength Length of rsBuffer

Return value

Either: 0 if call is successful
Or: Negative error code

Possible error codes

-3407 qaerr_UIAPINOTSTARTED

Comments

The layout name returned by this function is that of the configuration layout currently in use. Any address returned from a search submitted to the API at this point with QAProWV_UISearch will be formatted according to this layout.

The layout is the one specified in your call to QAProWV_UIStartup, unless it has been changed since with QAProWV_UISetActiveLayout or via the user interface.

Changes the configuration layout.

Pre-call conditions

The API has been started with QAProWV_UIStartup.

Prototype

INTRET QAProWV_UISetActiveLayout ( STRVAL vsLayout );

Arguments

vsLayout Layout name to change to

Possible error codes

-3402 qaerr_UNKNOWNLAYOUTNAME
-3407 qaerr_UIAPINOTSTARTED

Comments

This function allows you to switch between configuration layouts within an instance of the API. The layout was originally set with your call to QAProWV_ UIStartup.

You can find out which layouts are available in the configuration file with the functions QAProWV_ UILayoutCount and QAProWV_ UILayoutCount.

The text in vsLayout must match one of the layout names returned from QAProWV_ UILayoutCount, or an error will be returned. Note that the function is case-sensitive – for example, to select the layout QADefault, you cannot enter 'qadefault', as the API will not recognise it.

Returns a description of the element fixed to a particular line of the currently selected address layout.

Pre-call conditions

The API has been started with QAProWV_UIStartup and a layout has been selected.

Prototype

INTRET QAProWV_UILayoutLineElements ( INTVAL viIndex,
STRREF rsBuffer,
INTVAL viLength,
LONGREF rlType );

Arguments

viIndex Address line to retrieve
rsBuffer Buffer to receive line elements
viLength Maximum length of rsBuffer
rlType Line type description

Return value

Either: 0 if call is successful
Or: Negative error code

Possible error codes

-3411 qaerr_INVALIDLINEINDEX

Comments

This function tells you which address elements, if any, have been fixed to certain lines of the address layout. This function returns the name of an address element when there is only one element fixed to a line. If there is more than one element fixed to a line, a blank string will be returned.

If you want to retrieve descriptions of each address line from the current layout, you should call this function as many times as required. For example, if your address layout contains 6 address lines (as indicated by a call to QAProWV_ UIResultCount), you could call this function six times to retrieve each layout line.

The parameter viIndex contains the number of the address line whose description you want to retrieve. This is zero-based – for example, inputting 0 retrieves the description of the first line in the layout, 1 returns the second line, and so on.

The parameter rsBuffer contains the results of the function call. For example, if the town was fixed to line 4 of an address layout, you would set the value of viIndex as 3, and rsBuffer would return 'Town'. If there are no elements fixed to the line that you have specified, the buffer will be empty.

The parameter rsBuffer contains the results of the function call. For example, if the town was fixed to line 4 of an address layout, you would set the value of viIndex as 3, and rsBuffer would return 'Town'. If there are no elements fixed to the line that you have specified, the buffer will be empty.

The rlType parameter contains the type of line that is being retrieved. The types that can be returned are as follows:

|Type Name|Decimal Value|
|element_ADDRESS|0|
|element_NAME|1|
|element_DATAPLUS|2|
|element_ANCILLARY|3|

For example, you might have a seven-line address layout, where the first line contains name information, the second to sixth lines contain the address, and the final line is reserved for DataPlus data. In this case, the first line of the returned address would return element_NAME, the last line would return element_ DATAPLUS, and the lines in between would return element_ADDRESS.

The values assigned to each type are symbolic constants defined by the API, and appear in the prototyped header files for each language.

This function will fail safely with an error if the viIndex parameter is out of range (for example, if you specify line 6 in a five line layout).

Retrieves the number of installed datasets available to the API.

Pre-call conditions

The API has been started with QAProWV_UIStartup.

Prototype

INTRET QAProWV_UICountryCount ( INTREF riCount );

Arguments

riCount Number of datasets available

Return value

Either: 0 if call is successful
Or: Negative error code

Possible error codes

-3407 qaerr_UIAPINOTSTARTED

Comments

This function tells you how many datasets are configured for the API. The availability of datasets is determined by your qawserve.ini file.

Once you have the number of datasets, you can call QAProWV_UIGetCountry as many times as is necessary to retrieve a description of each dataset.

Retrieves one dataset name and identifier, in conjunction with QAProWV_UICountryCount.

Pre-call conditions

QAProWV_UIStartup has been called to start the API. QAProWV_UICountryCount has been called to return a count of the available datasets.

Prototype

INTRET QAProWV_UIGetGetCountry ( INTVAL viIndex,
STRREF rsIsoBuffer,
STRREF rsNameBuffer,
INTVAL viNameLength );

Arguments

viIndex Number of datasets (from 0 to QAProWV_UICountryCount
rsIsoBuffer Buffer to receive identifier of dataset
rsNameBuffer Buffer to receive name of dataset
viNameLength Maximum length of rsIsoBuffer and rsNameBuffer

Return value

Either: 0 if call is successful
Or: Negative error code

Possible error codes

-3400 qerr_INVALIDCOUNTRYINDEX
-3407 qaerr_UIAPINOTSTARTED

Comments

This function, in conjunction with QAProWV_UICountryCount, is useful if you want to confirm the number, names and identifiers of available datasets for a particular instance of the API. For example, you might want to use this functionality prior to the first call of QAProWV_UISearch, so that you know which datasets are available to search on.

You should call this function as many times as required to retrieve dataset details. For example, if QAProWV_UICountryCount returned a count of 4, you would call this function a maximum of four times to retrieve details of each dataset, setting viIndex to 0, 1, 2 and 3.

The parameter viIndex contains the number of the dataset whose details you want to retrieve – for example, inputting 0 retrieves the name of the first installed dataset, 1 returns the name of the second dataset, and so on.

The output parameters rsIsoBuffer and rsNameBuffer contain the identifier and name respectively of a dataset. An identifier is a unique three-letter descriptor for a dataset, which appears in the Data Guide supplied with your data. For example, the Australia dataset has the identifier AUS. The rsIsoBuffer parameter should always have at least a four-character buffer.

Retrieves the identifier of the currently active dataset.

Pre-call conditions

The API has been started with QAProWV_UIStartup.

Prototype

INTRET QAProWV_UIGetActiveCountry ( STRREF rsBuffer,
INTVAL viLength );

Arguments

rsBuffer Buffer to receive country identifier
viLength Length of rsBuffer

Return value

Either: 0 if call is successful
Or: Negative error code

Possible error codes

-3407 qaerr_UIAPINOTSTARTED

Comments

The identifier returned by this function is that of the dataset currently open for searching. Any search submitted to the API at this point with QAProWV_UISearch will be checked against this dataset.

This dataset is the one specified in your call to QAProWV_UIStartup, unless it has been changed since with QAProWV_UISetActiveCountry or via the user interface.

As an identifier is three characters long, you should use a minimum buffer of size 4 to allow for a null terminating character.

Changes the active dataset.

Pre-call conditions

The API has been started with QAProWV_UIStartup.

Prototype

INTRET QAProWV_UISetActiveCountry ( STRVAL vsIsoCode );

Arguments

vsIsoCode Identifier of the dataset to change to

Return value

Either: 0 if call is successful
Or: Negative error code

Possible error codes

-3407 qaerr_UIAPINOTSTARTED
-3405 qaerr_CANTCHANGEDATABASE

Comments

This function allows you to switch between datasets without closing down the API. The dataset is originally set in the call to QAProWV_UIStartup.

For example, passing AUS in the vsIsoCode parameter changes the active dataset to Australia (if you have Australian data installed).

You can find out which datasets are available with the functions QAProWV_UICountryCount and QAProWV_UIGetCountry. An error will be returned if you specify the code of a database that is not installed.

Returns the current configuration flags.

Pre-call conditions

The API has been started with QAProWV_UIStartup.

Prototype

INTRET QAProWV_UIGetFlags ( LONGREF rlFlags );

Arguments

rlFlags Line description flags

Return value

Either: 0 if call is successful
Or: Negative error code

Possible error codes

-3407 qaerr_UIAPINOTSTARTED

Comments

This function tells you which functionality flags are currently set. The flags are originally set with QAProWV_UIStartup.

To add or remove flags, call QAProWV_UISetFlags.

Adds and removes configuration flags.

Pre-call conditions

The API has been started with QAProWV_UIStartup.

Prototype

INTRET QAProWV_UISetFlags ( LONGVAL vlRemove,
LONGVAL vlAdd );

Arguments

vlRemove Buffer to receive country identifier
vlAdd Length of rsBuffer

Return value

Either: 0 if call is successful
Or: Negative error code

Possible error codes

-3407 qaerr_UIAPINOTSTARTED
-3414 qaerr_BADCONFIGFLAGS

Comments

This function allows you to change the flags that were set with QAProWV_ UIStartup.

Call the function QAProWV_UIGetFlags for a list of the currently set flags.

Provides a count of the raw address elements which are available to be retrieved.

This must be called before the function QAProWV_UIGetRawElement is used to retrieve each element.

Pre-call conditions

The API has been started with QAProWV_UIStartup, a search has been started with QAProWV_UISearch, and a final address has been selected with QAProWV_UIGetResult.

Prototype

INTRET QAProWV_UIGetRawElementCount ( INTREF riElementCount );

Arguments

riElementCount Number of address elements available.

Return value

Either: 0 if call is successful
Or: Negative error code

Possible error codes

-4553 qaerr_OUTOFSEQUENCE
-4556 qaerr_BADINDEX

Comments

This function tells you how many raw address elements are available to be returned for the active dataset. Once you have the number of raw address elements, you can call QAProWV_UIGetRawElement as many times as is necessary to retrieve the name of each element.

In the event of an error, riElementCount will be 0.

Retrieves one raw address element for a returned address.

Pre-call conditions

QAProWV_UIGetRawElementCount has been called to get the number of available elements for the active dataset.

Prototype

INTRET QAProWV_UIGetActiveCountry ( INTVAL viElement,
STRREF rsTag,
INTVAL viTagLen,
STRREF rsElement,
INTVAL viElementLen );

Arguments

viElement Number of the element to retrieve (from 0 to QAProWV_UIGetRawElementCount -1).
rsTag Buffer to receive the label for the retrieved address element.
viTagLen Length of rsTag (maximum 128 characters).
rsElement Buffer to receive the retrieved address element.
viElementLen Length of rsElement (maximum 1024 characters).

Return value

Either: 0 if call is successful
Or: Negative error code

Possible error codes

-4553 qaerr_OUTOFSEQUENCE
-4556 qaerr_BADINDEX

Comments

This function returns one raw address element available for the active dataset. The total number of address elements available can be returned with the function QAProWV_UIGetRawElementCount.

All available address elements for the active dataset are returned, regardless of whether they have been configured or contain a value for the current address. If you retrieve an element which contains no value for the current address, rsElement will be blank – only rsTag will contain a value.

You should call this function as many times as required to retrieve all the raw address elements you need. For example, if QAProWV_UIGetRawElementCount returned a count of 26 address lines, you would call this function 26 times to retrieve each of them.

In the event of an error, rsTag and rsElement will both be NULL terminated.

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, QAProWV_UIDPVGetCodeLength should be called in order to make sure the buffer provided is large enough for the lock code.

Prototype

INTRET QAProWV_UIDPVGetCode ( STRREF rsLockCode,
INTVAL viLockCodeLength );

Arguments

rsLockCode Buffer to receive lock code
viLockCodeLength Length of provided buffer rsLockCode.

Return value

Either: 0 if call is successful
Or: Negative error code

Possible Error scenarios

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

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

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 QAProWV_UIDPVGetCode in order to ensure an adequate buffer is supplied to that function to obtain the lock code.

Prototype

INTRET QAProWV_UICountryCount ( INTREF riCount );

Parameters

riCount Number of datasets available

Return value

Either: 0 if call is successful
Or: Negative error code

Possible Error scenarios

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

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 QAProWV_UIDPVGetCode in order to ensure an adequate buffer is supplied to that function when obtaining the lock code.

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 QAProWV_UIDPVGetInfo ( INTVAL viDPVInfoType,
STRREF rsDPVInfo,
INTVAL viLength );

Arguments

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

Possible values of viDPVInfoType are:

Possible Error scenarios

Not running: The API has not been started properly. QAProWV_UIStartup must be successfully called prior to this function.
Bad Parameter: One of the API parameters has been passed an invalid value. Use the Error Logging Settings to determine the cause of the problem.

Comments

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.

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 QAProWV_UIDPVSetKey ( STRVAL vsUnlockKey );

Parameters

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

Possible Error scenarios

Not running: The API has not been started properly. QAProWV_UIStartup 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 QAProWV_UIDPVState ( INTREF riDPVState );

Parameters

riDPVState Returned state of the DPV system.

Return value

Either: 0 if call is successful (DPV state has been determined)
Or: Negative error code

Possible Error scenarios

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

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

This function translates an error code to a text message.

Prototype

VOIDRET QAErrorMessage ( INTVAL viStatus,
STRREF rsBuffer,
INTVAL viBuffLen );

Arguments

viStatus Error code
rsBuffer Buffer to receive error text message
viBuffLen Maximum buffer length (including room for NULL terminator)

Comments

This function is useful for converting an error code to a short text message that can be displayed to the user for informational purposes.

It is advised that QAErrorMessage is called after any function which returns an error code, as the text message might help you identify the cause of the error.

Returns the severity of an error.

Prototype

INTRET QAErrorLevel ( INTVAL viStatus );

Arguments

viStatus Error code

Return value

Either: 0 for a fatal or serious error
Or: 1 for a warning

Comments

This function indicates the severity of an error returned by the API. A fatal or serious error should be flagged to the user and must be dealt with. A warning should be handled in a manner appropriate to the condition and can, if desired, be ignored.

Returns detailed information about the system usage of Pro.

Prototype

INTRET QASystemInfo ( INTVAL viLineNo,
STRREF rsBuffer,
INTVAL viBuffLen );

Arguments

viLineNo Line number being accessed (or negative if resetting)
rsBuffer Buffer to receive error text message
viBuffLen Maximum buffer length (including room for NULL terminator)

Return value

Either: 0 if call is successful
Or: negative error code for an invalid line number

Comments

You must call QAProWV_UIStartup before calling this function in the UI API.

The system information text contains detailed information about Pro, how it is configured, and the resources that it has taken from the operating system. The text is split over several lines and so has to be read one line at a time. A buffer size of 80 bytes will be sufficient to guarantee that no lines are truncated.

When the first line is read, the library generates an internal copy of the system information text. It is important that this copy is reset once all the lines have been read otherwise the allocated memory will not be freed. This is done by calling this function with the first parameter, viLineNo as -1 i.e. QASystemInfo (-1, NULL, 0).