home/Address validation/Pro API/Integration/User Interface API function reference

User Interface API function reference

The User Interface API functions can be split into the following groups:

  • General Functions: Starting up and shutting down the API.
  • Search Functions: Performing a search, and retrieving picklists of results and formatted addresses.
  • Housekeeping Functions: Viewing and selecting available datasets, address formats and functionality flags.
  • USA-Specific DPV Functions: 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.

Below is a full list of the Pro User Interface API functions:

Opens an instance of the API, specifying the name of the configuration file to be used, the layout to format addresses with, and the available functionality.

Pre-call conditions

None.

Prototype

INTRET QAProWV_UIStartup    ( STRVAL vsTitle,
                               STRVAL vsIniFile,
                               STRVAL vsCountry,
                               STRVAL vsLayout,
                              STRVAL vsLanguage,
                               LONGVAL vlFlags );

Arguments

vsTitle Text to display in title bar
vsIniFile Name of configuration file to open
vsCountry Name of dataset to open
vsLayout Name of configuration layout to use
vsLanguage Reserved for future use (should be set to NULL)
vlFlags Search functionality

Return value

Either: 0 if call is successful

Or: Negative error code

Possible error codes

  • -1031 qaerr_BADINIFILE
  • -3405 qaerr_CANTCHANGEDATABASE
  • -3406 qaerr_UIAPIALREADYSTARTED
  • -3413 qaerr_NOLIVESERVER
  • -3414 qaerr_BADCONFIGFLAGS

Comments

When you open an instance of the Pro API, you need to specify five things:

  • The title which appears at the top of the dialog together with the active dataset (defaults to blank) in vsTitle.
  • A configuration file (default qaworld.ini) in vsIniFile.
  • A layout within the configuration file (default QADefault) in vsLayout.
  • The dataset to open for searching (defaults to the alphabetically first installed dataset) in vsCountry.
  • The initial functionality to use in vlFlags.
  • If NULL or an empty string is passed into any of the above STRVAL input parameters, the API uses the defaults listed.

The flags that can be passed into vlFlags are as follows:

Symbolic Name Decimal Value Description
qaattribs_NONE (Default) 0 All options set from Configuration Editor. You do not need to specify any other flags.
qaattribs_NOCONFIRMVIEW 4 When a full address is found, it is returned directly to your application rather than to Pro's address edit screen.
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.
qaattribs_NOLAYOUTCHANGE 8 Disables ability to change layout. In order to enable this ability, the flag and the .ini setting must be set.
qaattribs_NOHELP 16 Disables Help facility. Note that the UIShowHelp INI setting has similar functionality, and that there is no Help provided for the UI API.
qaattribs_NOCHANGEMODE 32 Disables ability to change searching mode. This needs to be set in conjunction with either qaattribs_SINGLELINESEARCH or qaattribs_TYPEDOWNSEARCH.
qaattribs_ NOCHANGECOUNTRY 128 Disables ability to switch between datasets. In order to enable this ability, the flag and the .ini setting must be set.
qaattribs_SINGLELINESEARCH 256 Starts API in Singleline search mode.
qaattribs_TYPEDOWNSEARCH 512 Starts API in Typedown search mode.
qaattribs_KEYFINDERSEARCH 262144 Starts API in Keyfinder search mode.
VERIFICATIONSEARCH 524288 Starts API in Verification search mode.
qaattribs_NOPROBITMAP 8192 Displays the User Interface without the Pro bitmap.
qaattribs_MINDISPLAY 16384 Only displays the Pro User Interface if necessary - i.e. all searches are done from your application and the User Interface only appears if there is a picklist of results or an address to be confirmed/edited.
qaattribs_READONLY 65536 If this flag is set, users will be unable to edit addresses returned to the address edit screen. This overrides the Allow Address Editing option in Configuration Editor.
qaattribs_NOLICENSINGDLG 31072 Disables the 'Dataset Due to Expire' dialog, which is displayed by default when Pro is started up. This lists all the datasets that are due to expire soon.

The value given with each flag represents that flag's hexadecimal value. If you want to specify more than one of these flags, the values should be ORed together. For example, Singleline searching and no Pro bitmap.

If you attempt to set more than one search mode flag, the search engine will default to Typedown. For example, if you set qaattribs_SINGLELINESEARCH and qaattribs_TYPEDOWNSEARCH (by setting the vlFlags parameter to 0x00000300), the API will default to Typedown mode. To change the search engine, call QAProWV_UISetFlags with only one of the search flags set.

You will get an error if Pro API cannot find the specified configuration file, or if one of the datasets has expired or has been moved from its default location.

Fail-over logic is included so that QAProWV_UIStartup will loop through all of the defined servers until a successful connection can be established.

Closes down the API.

Pre-call conditions

The API is initialised.

Prototype

VOIDRET QAProWV_UIShutdown ( INTVAL viStatus );

Arguments

viStatus Last returned status code to be reported by the API prior to full shutdown.

Return value

Either: 0 if call is successful

Or: Negative error code

Comments

This function will close down the API completely, and must be called as the final function.

If another function has returned an error, you can specify this as the input parameter in the call to QAProWV_UIShutdown. Then, when the API shuts down, a dialog box will appear with a description of the error. If you have received an error which you wish to handle yourself, or are shutting down without errors, pass 0 (zero) into the function.

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

Detail type Description
qaresultint_ ISDPVVALID Returns whether the given address is a valid USPS Delivery Point. This value only applies for US address data.
qaresultint_ ISDPVLOCKED Returns whether the Delivery Point Validation (DPV) functionality is locked, meaning the address cannot be assessed regardless of whether or not it is a valid Delivery Point. This value only applies for US address data.
qaresultint_ISEDITED Returns whether that the user has manually edited the selected address, so any DPV assessment (returned on the original address) may no longer be valid.
qaresultint_ ISOVERFLOW Returns whether there are insufficient address lines in the selected layout to accommodate all of the address details.
qaresultint_ ISTRUNCATED Returns whether any address information has been truncated.
qaresultint_ ISUNVERIFIED Returns whether the user has selected an unverified address (by pressing Ctrl+Enter prior to arriving at the final address screen).
qaresultint_ ISDPVConfirmed Returns whether the address was DPV confirmed. This applies to USA data only.
qaresultint- ISDPVDATAUPDATING Returns whether the data is currently being updated. If so, it results cannot be returned at this time. The process of updating the data should not take more than 30 seconds.
qaresultint_ISDPVSeed Returns whether the address was a DPV seed address. If so, DPV functionality will be locked. This applies only to USA data.

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

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:

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.

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

Low-level system functions

The User Interface API also includes three low-level system functions:

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