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

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

Retrieves the current search engine.

Prototype

INTRET QA_GetEngine     ( INTVAL viHandle,
                          INTREF riEngine );

Arguments

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

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

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

Retrieves the current settings used with a search engine.

Prototype

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

Arguments

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

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

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

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

Returns status information about the current prompt.

Prototype

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

Arguments

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:

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

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

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

Return value

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

Error scenarios

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

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

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

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

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:

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

Selects a picklist item from a picklist to expand further.

Prototype

INTRET QA_StepIn    ( INTVAL viHandle,
                      INTVAL viResult );

Arguments

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

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 QA_StepOut   ( INTVAL viHandle );

Arguments

Return value

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

Error scenarios

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

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

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

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:

Error scenarios

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

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

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

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

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

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

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

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

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

Prototype

INTRET QA_GetLayoutCount    ( INTVAL viHandle,
                              INTREF riCount );

Arguments

Return value

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

Error scenarios

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

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

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

Return value

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

Error scenarios

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

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

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

Return value

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

Error scenarios

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

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

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

Return value

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

Error scenarios

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

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

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

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

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

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

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

Return value

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

Comments

The following values can be passed to viType:

Error scenarios

Gets a line of the system information produced by QA_GenerateSystemInfo.

Prototype

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

Arguments

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

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

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

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

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

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

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:

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

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

Return value

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

Error scenarios

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

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

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

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

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

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.