API functions

Returns a CASS report file with the corresponding required information.

Prototype

int QABatchWV_CreatePS3553(
    const char * outPath,
    int count,
    int dpv,
    int zip5,
    int crt,
    int elot,
    int hdef,
    int hexact,
    int rrdef,
    int rrexact,
    int llk,
    int ews,
    int slk)

Parameters

Usage example

    QABatchWV_Startup(qabwvflags_NONE);
    QABatchWV_CreatePS3553("ps3553.txt", 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12);
    QABatchWV_Shutdown();

This function converts an error code to a text explanation.

Pre-call conditions

The API must be initialized, and a specific instance should have been started with QABatchWV_Open.

Prototype

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

Parameters

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.

This function provides detailed error information for single threaded integrations. QAErrorHistory should not be used as a diagnostic tool in a multithreaded integration.

Pre-call conditions

The API has been shut down with QABatchWV_Shutdown.

Prototype

INTRET QAErrorHistory
    (INTVAL viAll,
    INTVAL viLineNo,
    STRREF rsBuffer,
    INTVAL viBuffLen);

Parameters

Return values

Either: 0 if call successful
Or: negative error code

Comments

This function is used for accessing more detailed error information than that returned by QAErrorMessage. For example, QAErrorMessage may return 'file not found' whereas QAErrorHistory can highlight the specific file(s) that was not found.

Resetting frees up memory allocated by the function. For more information, see QASystemInfo.

Returns the severity of an error.

Prototype

INTRET QAErrorLevel
    (INTVAL viStatus);

Parameters

Return values

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 the API shut down. 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 the Batch API library.

Prototype

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

Parameters

Return values

Either: 0 if call successful

Or: negative for an invalid line number

Comments

You can only call this function once the API has been started.

The system information text contains detailed information about the Batch API library, how it is configured, and the resources that it has grabbed 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. Below is a C example that prints the system information text.

C example that prints out QASystemInfo text

void PrintSystemInfo(VOIDARG)
{
    char sBuffer[80];
    int iLineNo;
    /* read each line in turn */
    for (iLineNo = 0;
        QASystemInfo(iLineNo, sBuffer, sizeof(sBuffer)) == 0; iLineNo++)
    {
        puts(sBuffer);
    }
    /* reset in order to free memory */ QASystemInfo(-1, NULL, 0);
}

If you run the example above, you get a result similar to this:

Program: QABWVED
Copyright: Experian Ltd
Release: 4.00(07)
Platform: Windows 32-bit
Libraries: QAKRNXF 2.23(213)
QATOKXD 1.00(3)
QAUFWXF 4.00(208)
QACOMXD 1.01(152
QASLGXD 1.00(3)
QASLHXD 1.00(2)
QASLUXD 1.00(2)
QAHSGXD 3.00(89)
QAGENXD 1.00(4)
QAHSVXD 3.20(84)
QALICXD 1.00(10)
QAHCLXD 3.00(60)
QACDIXD 4.00(317)
QADC2XD 2.40(47)
QADS2XD 2.00(14)
QAWD2XD 2.40(66)
QAUSGXD 4.00(109)
QALL2XD 2.40(81)
QAUTDXD 4.00(129)
QASLCXD 1.00(2)
QATIXXD 4.00(110)
QAZLSXD 1.01(41)

Config: qaworld.ini
Section: ALL
Licensed to:
Serial No:
Days: No limit
Users: No limit Dongle:
Prog Dir: C:/Experian/QAS Batch API
Home Dir: C:/Experian/QAS Batch API
Data Dir: C:/Experian/QAS Batch API
Temp Dir: C:/DOCUME~1/chrisr/LOCALS~1/Temp
Log File:
Memory: 69451515 (allocs=2592)
Data: 69323428 (free=760)
Blocks: 4816 (free=68)

Performs a search on the specified input address.

Pre-call conditions

The API must be initialized, and a specific instance should have been started with QABatchWV_Open.

Prototype

INTRET QABatchWV_Clean
    (INTVAL viHandle,
    STRVAL vsSearch,
    INTREF riSearchHandle,
    STRREF rsPostcode,
    INTVAL viPostcodeLength,
    STRREF rsIsoCode,
    STRREF rsReturnCode,
    INTVAL viReturnLength);

Parameters

Return values

Either: 0 if call successful
Or: negative error code

Possible error scenarios

Comments

When you call QABatchWV_Clean with an input address, the search string should be comma-separated so that Batch API can distinguish between address elements. For example:

15 Stoke Way, Edgbaston, Birmingham
25 Tattersalls Lane, Melbourne 3000

This function call passes back four values:

• Search handle - This is used to retrieve results pertaining to this search, with the functions QABatchWV_GetFormattedLine, and QABatchWV_ GetUnusedInput. This parameter should be set to NULL if you do not want to use search handles.
• The Match code - This indicates how successfully Batch API has matched your input address.
• Postal code. If Batch API has found a valid postal code in your input address, or has added a postal code to the address, it is returned in this field.
• Dataset identifier - This is the three-character alpha-numeric code that identifies a particular dataset. The code will be that of your default dataset, unless Batch API has detected a different country name in the input address. Batch API will return the dataset identifier for that country name even if the dataset is unavailable. Batch API will only return a country name for unmatched addresses if you set a default dataset.

A maximum of eight searches can be submitted at a time to each handle of the API. If any more than eight are submitted simultaneously, an error will be returned.

Related functions:

• QABatchWV_GetFormattedLine
• QABatchWV_GetUnusedInput
• QABatchWV_EndSearch

Deallocates resources and the search handle used by a call to QABatchWV_ Clean.

Pre-call conditions

An instance of the API has been initialized and opened with QABatchWV_Open. QABatchWV_Clean has been called, and all results have been retrieved.

Prototype

INTRET QABatchWV_EndSearch
    (INTVAL viSearchHandle);

Parameters

Return values

Either: 0 if call successful
Or: negative error code

Possible error scenarios

Comments

This function should be called after results have been retrieved from QABatchWV_Clean, in order to free the search handle for use in further searches.

Related functions:

• QABatchWV_Clean

This function returns the number of address lines available in the configuration layout that you specified in your call to QABatchWV_Open.

Pre-call conditions

The API must be initialized, and a specific instance should have been started with QABatchWV_Open.

Prototype

INTRET QABatchWV_LayoutLineCount
    (INTVAL viHandle,
    STRVAL vsCountry,
    INTREF riCount);

Parameters

Return values

Either: 0 if call successful
Or: negative error code

Comments

This function tells you how many times the function QABatchWV_LayoutLineElements needs to be called in order to retrieve a full address layout.

The value of this function is constant for a dataset within a session, as its value is set in the configuration file.

Related functions

• QABatchWV_GetFormattedLine
• QABatchWV_LayoutLineElements

Returns a description of the elements fixed to a particular line of the address layout.

Pre-call conditions

The API must be initialized, and a specific instance should have been started with QABatchWV_Open.

Prototype

INTRET QABatchWV_LayoutLineElements
    (INTVAL viHandle,
    STRVAL vsCountry,
    INTVAL viLine,
    STRREF rsBuffer, 
    NTVAL viLength,
    LONGREF rlFlags);

Parameters

Return values

Either: 0 if call successful
Or: negative error code

Possible error scenarios

Comments

This function tells you whether a specific address / DataPlus element, if any, has been fixed to a line of an address layout. When an element is fixed to a line, it cannot appear anywhere else in the address. See the AddressLineN setting for details of how to fix an element to a line.

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 QABatchWV_LayoutLineCount returned a count of 6 address lines, you could call this function a maximum of six times to retrieve a description of each line.

The parameter viLine contains the number of the address line whose description 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.

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 viLine as 3, and rsBuffer would return 'Town'. If there are no elements (or more than one element) fixed to the line that you have specified, the buffer will be empty.

The rlFlags parameter contains the type of line that is being retrieved. The 'flags' that can be returned are as follows:

A return of 0 (element_ADDRESS) essentially indicates the absence of any flags, which means that the standard line type has been received, i.e. a line containing address elements.

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 flag are symbolic constants defined by the API and appear in the prototyped header files for each language.

Related functions

• QABatchWV_LayoutLineCount

Returns the number of formatted lines that a search has resulted in.

Pre-call conditions

The API must be initialized, and started with QABatchWV_Open, and a call to QABatchWV_Clean should have been completed successfully.

Prototype

INTRET QABatchWV_FormattedLineCount
    (INTVAL viSearchHandle,
    INTREF riCount);

Parameters

Return values

Either: 0 if call successful
Or: negative error code

Possible error scenarios

Comments

This function tells you how many times QABatchWV_GetFormattedLine needs to be called in order to retrieve a full address.

For the standard address and enhanced cleaning modes, the value of this function is constant for a dataset within a session as its value is set in the configuration file.

For the Postal code update mode, the value is determined by the number of clean lines passed into QABatchWV_Clean.

Related functions

• QABatchWV_GetFormattedLine
• QABatchWV_LayoutLineElements

This function gets one formatted address line from the latest retrieved address.

Pre-call conditions

The API must be initialized and started with QABatchWV_Open, and a call to QABatchWV_Clean should have been completed successfully.

Prototype

INTRET QABatchWV_GetFormattedLine
    (INTVAL viSearchHandle,
    INTVAL viLine,
    STRREF rsBuffer,
    INTVAL viBuffLen);

Parameters

Return values

Either: 0 if call successful
Or: negative error code

Possible error scenarios

Comments

This function should be called as many times as necessary to retrieve a full address. If this function is called during a Postal code only clean, it will return the same number of lines as contained in the input address.

Related functions:

• QABatchWV_FormattedLineCount

This function returns the number of lines that have not been used from the input address.

Pre-call conditions

The API must be initialized, a specific instance started with QABatchWV_Open, and QABatchWV_Clean called.

Prototype

INTRET QABatchWV_UnusedLineCount
    (INTVAL viSearchHandle,
    INTREF riCount);

Parameters

Return values

Either: 0 if call successful
Or: negative error code

Possible error scenarios

Comments

The value returned by this function tells you how many times you need to call QABatchWV_GetUnusedInput. Its value will depend on the input address, and therefore varies within a session.

A call to this function will produce a zero value if all lines from the input address also appear in the output.

Related functions

• QABatchWV_GetUnusedInput

This function gets one unused line from the latest input address.

Pre-call conditions

The API must be initialized with QABatchWV_Open, and a call to QABatchWV_ Clean should have been completed successfully.

Prototype

INTRET QABatchWV_GetUnusedInput
    (INTVAL viSearchHandle,
    INTVAL viLine,
    STRREF rsBuffer,
    INTVAL viLength,
    LONGREF rlLineCompleteness,
    LONGREF rlLineType,
    LONGREF rlLinePosition,
    INTREF riCareOf,
    INTREF riPremSuffix);

Parameters

Return values

Either: 0 if call successful
Or: negative error code

Possible values of rlLineCompleteness

Possible values of rlLineType are:

Possible values of rlLinePosition are:

Possible error scenarios

Comments

This function is optional; call it in conjunction with QABatchWV_ UnusedLineCount if you want to see which parts of the input address, if any, were not included in the output address.

Unused lines will include any leading non-matching elements from the input address. For example, say this is the input address:

John Smith, Suite 1, Level 9, 60 Miller St, North Sydney, 2060

The dataset (Australia, in this case) does not contain names, so although the rest of the address is correct, Batch API cannot match the leading element (i.e. 'John Smith') to anything and returns it as unused.

If the CleaningAction keyword is set to 'Enhanced', then 'John Smith' would be prefixed to the output address. If this is the case, it would not be returned as an unused line.

The function should be called as many times as necessary to retrieve any unused lines from the input address. If the function is called out of place (for example, before QABatchWV_Clean), it will fail with an error.

Related functions:

• QABatchWV_UnusedLineCount

This function provides access to detailed match information. Most values are returned as integers to ease processing. Each parameter provides a discrete component of the full match code.

Pre-call conditions

The API must be initialized and started with QABatchWV_Open, and a call to QABatchWV_Clean should have been completed successfully.

Prototype

INTRET QABatchWV_GetMatchInfo
    (INTVAL viSearchHandle,
    STRREF rsIsoCode,
    STRREF rsMatchType,
    INTREF riConfidence,
    INTREF riPostcodeAction,
    INTREF riAddressAction,
    LONGREF rlGenericInfo,
    LONGREF rlCountryInfo,
    LONGREF rlCountryInfo2)

Parameters

Return values

Either: 0 if call successful
Or: negative error code

Possible error scenarios

Related functions

• QABatchWV_Clean
• QABatchWV_Open

This function gets one unused line from the latest input address.

Pre-call conditions

The API must be initialized with QABatchWV_Open, QABatchWV_GetOlts is called before.

Prototype

INTRET QABatchWV_GetOltItem
    (INTVAL handle,
    UINTVAL index,
    STRREF code,
    UINTVAL maxCodeLen,
    STRREF name,
    UINTVAL maxNameLen);

Parameters

Return values

Either: 0 if call successful
Or: negative error code

Possible error scenarios

Comments

This function is expected to be called after calling QABatchWV_Open. The standard approach is to call QABatchWV_Open an then call this function with each index from 0 to oltCount, returned by QABatchWV_Open.

This function gets OLT list for a specific identifier. The identifier can identify either a base dataset (like GBR) or an ADS (GBRELC). The function itself retrieves the OLT list and returns the number of OLTs Information about individual OLT can be retrieved by using the GetOltItem function.

Pre-call conditions

The API must be initialized with QABatchWV_Open.

Prototype

INTRET QABatchWV_GetOlts 
    (INTVAL handle,
    STRVAL identifier,
    INTREF isSupression,
    UINTREF oltCount);

Parameters

Return values

Either: 0 if call successful
Or: negative error code

Possible error scenarios

Comments

This function is expected to be called before calling QABatchWV_GetOltItem. The returned oltCount is used to iterate through all the OLTs.

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

Prototype

INTRET QABatchWV_DPVGetCode
    (STRREF rsLockCode, 
    INTVAL viLockCodeLength);

Parameters

Return values

Either: 0 if call successful (lock code has been stored in the supplied buffer)
Or: negative error code

Possible error scenarios

Comments

When DPV is disabled by a seed address, Batch API generates a variable- length alphanumeric code which is required to unlock DPV. If you do not call QABatchWV_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 signaled 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 QABatchWV_DPVGetCode in order to ensure an adequate buffer is supplied to that function to obtain the lock code.

Prototype

INTRET QABatchWV_DPVGetCodeLength
    (INTREF riLockCodeLength);

Parameters

Return values

Either: 0 if call successful
Or: negative error code

Possible error scenarios

Comments

Batch API generates an alphanumeric lock code when DPV is disabled. The code can vary in length, so this function should be called before QABatchWV_ DPVGetCode 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 QABatchWV_DPVGetInfo
    (INTVAL viDPVInfoType,
    STRREF rsDPVInfo,
    INTVAL viLength);

Parameters

Return values

Either: 0 if call successful (lock information has been stored in the supplied buffer)
Or: negative error code

Possible values of viDPVInfoType

Possible error scenarios

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 signaled 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 Data Quality following the reporting of the corresponding lock code).

Prototype

INTRET QABatchWV_DPVSetKey
    (STRVAL vsUnlockKey);

Parameters

Return values

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

Possible 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 Batch API's return code.

Prototype

INTRET QABatchWV_DPVState
    (INTREF riDPVState);

Parameters

Return values

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

Possible error scenarios

Comments

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

Compares two previously returned audit codes generated using QABatchWV_ GetAuditCode. An XML report is returned into the specified buffer.

Pre-call conditions

The API must be initialized, and as specific instance should have been started with QABatchWV_Open.

Prototype

INTRET QABatchWV_CompareAuditCode
    (INTVAL viHandle,
    STRVAL vsAudit1,
    STRVAL vsAudit2,
    STRREF rsXmlReport,
    INTVAL viXmlReportLength);

Parameters

Return values

Either: 0 if call successful
Or: negative error code

Possible error scenarios

Comments

The two audit codes being compared must have both been created using the Batch installation that this function is being called from.

Related functions:

• QABatchWV_GetAuditCode

Opens a new counter instance tied to the Batch API instance supplied in viHandle.

Pre-call conditions

The API must be initialized, and a specific instance should have been started with QABatchWV_Open.

Prototype

INTRET QABatchWV_CounterOpen
    (INTVAL viHandle,
    INTREF riCounterHandle);

Parameters

Return values

Either: 0 if call successful
Or: negative error code

Possible error scenarios

Comments

If viHandle is set to -1, the counter will count transactions from all open instances of the Batch API. A counter tied to an instance of the Batch API will be closed automatically if the instance is closed.

Related functions

• QABatchWV_CounterClose
• QABatchWV_CounterReport
• QABatchWV_CounterReportLength

Returns an XML report of the records cleaned, and clicks used since the counter was opened (see QABatchWV_CounterOpen*)

Pre-call conditions

The API must be initialized, and a specific instance should have been started with QABatchWV_Open. A counter should also have been opened using QABatchWV_CounterOpen*.

Prototype

INTRET QABatchWV_CounterReport
    (INTVAL viCounterHandle,
    STRREF rsXmlReport,
    INTVAL viXmlReportLength);

Parameters

Return values

Either: 0 if call successful
Or: negative error code

Possible error scenarios

Comments

Though click information will not be returned if less than ten clicks have been used since the counter was created (or since the last counter report was run), match information will always be returned.

The XML report will be returned into the specified buffer.

Related functions

• QABatchWV_CounterOpen
• QABatchWV_CounterReportLength
• QABatchWV_CounterClose

Returns the length of the XML counter report that would be returned. This length is given in bytes.

Pre-call conditions

The API must be initialized, and a specific instance should have been started with QABatchWV_Open. A counter should also have been opened using QABatchWV_CounterOpen.

Prototype

INTRET QABatchWV_CounterReportLength
    (INTVAL viCounterHandle,
    INTREF riXmlReportLength);

Parameters

Return values

Either: 0 if call successful
Or: negative error code

Possible error scenarios

Related functions

• QABatchWV_CounterOpen
• QABatchWV_CounterReport
• QABatchWV_CounterClose

Closes an active counter handle, removing any stored statistics.

Pre-call conditions

The API must be initialized, and a specific instance should have been started with QABatchWV_Open. A counter must have been initialized using QABatchWV_ CounterOpen.

Prototype

INTRET QABatchWV_CounterClose
    (INTVAL viCounterHandle);

Parameters

Return values

Either: 0 if call successful
Or: negative error code

Possible error scenarios

Comments

Any counter report that is required must be retrieved before the counter is closed as all recorded statistics are deleted upon closure.

Related functions

• QABatchWV_CounterOpen
• QABatchWV_CounterReport
• QABatchWV_CounterReportLength

Populates a counters file with post-pay meters for each supported Suppression set. May also be used if the existing counters file has become corrupted or to add extra Suppression DataPlus sets.

Pre-call conditions

The API must be initialized. No specific instances of the API need to be running.

Prototype

INTRET  QABatchWV_ApplyUpdateCode
    (STRVAL vsUpdateCode);

Parameters

Return values

Either: 0 if call successful
Or: negative error code

Possible error scenarios

Related functions:

• QABatchWV_GetAuditCode

This function switches an instance of Batch into or out of Estimate Mode. Whilst in Estimate Mode, counter statistics can be returned, allowing a user to estimate the cost of a suppression without committing to purchasing the clicks. Upon calling this function, all open counter instances will be reset.

Pre-call conditions

The API must be initialized, and a specific instance should have been started with QABatchWV_Open.

Prototype

INTRET QABatchWV_RunMode
    (INTVAL viHandle,
    INTVAL viEstimateMode);

Parameters

Return values

Either: 0 if call successful
Or: negative error code

Possible error scenarios

Comments

Whilst in Estimate Mode, all items will return the matchcode A0000000000000000000 and the formatted line count will be zero. The Batch statistics will however be populated with the aggregate match detail as if the run had actually taken place.

When in Estimate Mode, it is not possible to extract the match and suppression details for an address without switching out of Estimate Mode and running the address again.

After a run is complete, any counter(s) should be read and a report produced before closing the instance or changing the mode, as the information will be cleared.

Related functions

• QABatchWV_CounterOpen
• QABatchWV_CounterReport
• QABatchWV_CounterClose