This section contains an alphabetical listing of the API functions. For each function there is a brief explanation of what it does, followed by its prototype, parameters, return value and any comments on its functionality.

The functions can be loosely split into the following groups:

  • General functions: These functions open and close the API and provide program information.
  • System functions: These functions cover the whole library system to handle errors and usage details.
  • Search functions: These functions send the input addresses to the API and optionally provide feedback.
  • Retrieval functions: These functions return the number and contents of formatted and unused address lines.
  • USA-specific DPV functions: These functions are specific to the DPV system.
  • Suppression-specific functions: These functions are specific to the use of Suppression data.

There is also a list of deprecated functions, for reference by users of previous versions of Batch API.

These functions open and close the API and provide program information.

Initialises the API. This function must be called before any other functions can be used.

Pre-call conditions

None.

Prototype

INTRET QABatchWV_Startup
    (LONGVAL vlFlags);

Parameters

Argument Description
vlFlags Allows adjusting the way Batch API operates globally, affecting all API instances.

Return values

Either: 0 if call successful
Or: negative error code

Possible error scenarios

Errors Descriptions
Locale file The API could not find the file qalcl.dat. Ensure the product has been installed correctly and the file qalcl.dat is in the program directory.

Comments

This function initializes the Batch API. Once initialized, you can either call informational functions such as QABatchWV_LayoutCount, or you can open an instance of the API with QABatchWV_Open.

Attribute Description
qabwvflags_NONE This value uses the default settings for Batch API.
qabwvflags_ SESSION This value tells Batch API to work in Session Mode. This affects the way Batch API will treat custom.ini files supplied to QABatchWV_Open.

If this function is called out of turn or encounters an error while initializing, the API will shut down and an appropriate error will be flagged.

Related functions

Closes down all instances of the API and must be called as the final function.

Pre-call conditions

The API is initialized, and no searches are in progress.

Prototype

INTRET QABatchWV_Shutdown
    (VOIDARG);

Return values

Either: 0 if call successful
Or: negative error code

Comments

This function will close down the API completely, and should be called even if QABatchWV_Close has shut down all instances of the API. An error will be returned if one or more instances of the API is in use (for example, a search is in progress).

Related functions

Retrieves the number of available layouts in the specified configuration file.

Pre-call conditions

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

Prototype

INTRET QABatchWV_LayoutCount 
    (STRVAL vsIniFile,
    INTREF riCount);

Parameters

Argument Description
vsIniFile Name of a configuration file if you have created a separate file for layouts. If vsIniFile is not specified, the default configuration file, qaworld.ini, will be used.
riCount Number of layouts in the configuration file.

Return values

Either: 0 if call successful
Or: negative error code

Possible error scenarios

Errors Descriptions
Not running The API has not been started properly. QABatchWV_Startup must be successfully called prior to this function.
Bad parameter One of the API parameters has been passed an invalidvalue.Use the LogErrors configuration setting to determine the cause of the problem.
File error The file specified in vsIniFile could not be opened.

Comments

This function tells you how many configuration layouts are available in the INI file that you specify. See Configuring the Batch API for a detailed description of configuration files and layouts.

You can call this function before QABatchWV_Open, as it does not relate to a specific instance of the API.

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

Related functions

Retrieves the name of one layout in the specified configuration file.

Pre-call conditions

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

Prototype

INTRET QABatchWV_GetLayout
    (STRVAL vsIniFile,
    INTVAL viIndex,
    STRREF rsName,
    INTVAL viLength);

Parameters

Argument Description
vsIniFile Name of a configuration file if you have created a separate file for layouts. If vsIniFile is not specified, the default configuration file, qaworld.ini, will be used.
viIndex Number of layout.
rsName Name of layout.
viLength Maximum length of buffer for rsName.

Return values

Either: 0 if call successful
Or: negative error code

Possible error scenarios

Errors Descriptions
Not running The API has not been started properly. QABatchWV_Startup must be successfully called prior to this function.
Bad parameter One of the API parameters has been passed aninvalid value. Use the LogErrors configuration setting to determine the cause of the problem.
File error The file specified in vsIniFile could not be opened.
Layout out of range The index passed to the viIndex parameter is too large. It should be between 0 and the count from QABatchWV_LayoutCount -1.

Comments

This function, in conjunction with QABatchWV_LayoutCount, is useful if you want to confirm the number and names of available configuration layouts prior to
calling QABatchWV_Open.

You should call this function as many times as required to retrieve layout names from a configuration file. For example, if QABatchWV_LayoutCount returned a count of 6, you would call QABatchWV_GetLayout a maximum of 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.

Related functions

Changes the layout to a custom one, provided as an argument. Also changes the ADS list. The new layout and ADS list are provided by using strings rather than sections in the .ini file. The country of the new layout cannot be changed by this function.

Pre-call conditions

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

Prototype

INTRET QABatchWV_ChangeLayout 
    (INTVAL viHandle,
    STRVAL vsLayout,
    STRVAL vsADSList);

Parameters

Argument Description
viHandle Handle for this instance of the API.
vsLayout String containing new layout (with '/n' at the end of each line). "!" means leave the layout unchanged.
vsADSList List of ADS sets (comma-separated string)."!" means leave the list of ADS sets unchanged.

Return values

Either: 0 if call successful
Or: negative error code

Possible error scenarios

Error Description
Not running The API has not been started properly. QABatchWV_Start-up must be successfully called prior to this function.
Bad handle The handle passed to the parameter viHandle is not valid. QABatchWV_Open must be successfully called prior to this function, and the handle returned in viHandle should be used.
Format error The layout or ADS list was in incorrect format.
Different country The country of the layout was different than the current one.

Related functions:

Opens an instance of the API, specifying the name of the configuration file to be used, and the layout to use within that file.

Pre-call conditions

The API has been initialized with QABatchWV_Startup.

Prototype

INTRET QABatchWV_Open 
    (STRVAL vsIniFile,
    STRVAL vsLayout,
    LONGVAL vlFlags,
    INTREF riHandle);

Parameters

Argument Description
vsIniFile Name of configuration file to open. If the full path is not specified, Batch API will only check for the configuration file within the program directory. The default configuration file is qaworld.ini, but a separate configuration file can be used to handle layout information.
vsLayout Layout section to open.
vlFlags Included to provide for extra functionality in future versions.
riHandle Handle returned by the API (if there is more than one user accessing the search engine).

Return values

Either: 0 if call successful
Or: negative error code

Possible error scenarios

Errors Descriptions
Not running The API has not been started properly. QABatchWV_Startup must be successfully called prior to this function.
Bad parameter One of the API parameters has been passed an invalid value. Use the LogErrors configuration setting to determine the cause of the problem.
No handles QABatchWV_Open has been called too many times without a call to QABatchWV_Close. There is a limit of 32 open handles that can be created. Ensure that QABatchWV_Close is called when an open instance is not required.
No installed countries No countries were successfully started. Check that all datasets have been installed correctly and ensure that there are countries defined in the InstalledData setting.
INI file error The file specified in vsIniFile could not be opened. For more information about configuration files.
No country file The API could not find the file country.ini. Ensure that the product has been installed correctly, and the file country.ini is present in the program directory.
File error There was an error attempting to open a file. This is most likely to occur when opening a data file. Ensure the datasets have been correctly installed and that the corresponding settings are defined in InstalledData.
Invalid layout An invalid layout is specified in the configuration file passed to vsIniFile. Ensure that a layout is defined within the configuration setting that is passed to the vsLayout parameter. Layout names in the configuration file are enclosed by square brackets. However, when specifying a layout name as a parameter in a function call, the square brackets should not be included. Check that the layout has the correct syntax. See AddressLineCount and AddressLineN.

Comments

When you open an instance of the Batch API, you need to specify the configuration file you are using, and the layout within that configuration file which contains your output address format.

If NULL is passed into either of the above input parameters, the API uses defaults. The default configuration file is qaworld.ini, and the default layout within that file is [QADefault] (without brackets).

You might also get an error if you have chosen (in the configuration file) to create a log file and the Batch API cannot find the specified drive or directory to create it. An error will also be returned if one of the datasets has expired or has been moved from its default location.

When the API instance has initialized, it returns a handle in the form of an integer. This handle is used to distinguish between multiple users of the Batch API search engine and should be passed into all subsequent functions. It should be set to 0 if you do not wish to multithread the Batch API.

There can be 32 instances of the API running at any one time, in other words QABatchWV_Open can be called 32 times. If all instances are already in use when you call this function, the error qaerr_NOHANDLES is returned.

Related functions:

Closes down this instance of the API.

Pre-call conditions

An instance of the API has been initialized and been opened with QABatchWV_ Open, and no searches are in progress.

Prototype

INTRET QABatchWV_Close 
    (INTVAL viHandle);

Parameters

Argument Description
viHandle Handle for this instance of the API.

Return values

Either: 0 if call successful
Or: negative error code

Possible error scenarios

Errors Descriptions
Not running The API has not been started properly. QABatchWV_Startup must be successfully called prior to this function.
Bad handle The handle passed to the parameter viHandle is not valid. QABatchWV_Open must be successfully called prior to this function, and the handle returned in riHandle should be used.
Bad parameter One of the API parameters has been passed an invalid value. Use the LogErrors configuration setting to determine the cause of the problem.

Comments

The error qaerr_CALLPENDING will be returned if this instance of the API has a search in progress.

Related functions:

Retrieves the number of dataset identifiers available to this instance of the API.

Pre-call conditions

The API is initialized, and a specific instance has been started with QABatchWV_ Open.

Prototype

INTRET QABatchWV_CountryCount
    (INTVAL viHandle,
    INTREF riCount);

Parameters

Argument Description
viHandle Handle for this instance of the API. If the handle that is passed to viHandle is 0, all datasets are used. If the handle is passed, all datasets within the section are used.
riCount Number of datasets available.

Return values

Either: 0 if call successful
Or: negative error code

Possible error scenarios

Errors Descriptions
Not running The API has not been started properly. QABatchWV_Startup must be successfully called prior to this function.
Bad handle The handle passed to the parameter viHandle is not valid. QABatchWV_Open must be successfully called prior to this function, and the handle returned in riHandle should be used.
Bad parameter One of the API parameters has been passed an invalid value. Use the LogErrors configuration setting to determine the cause of the problem.

Comments

This function tells you how many datasets are available for this particular thread of the API. The availability of datasets is determined by the configuration file specified in QABatchWV_Open.

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

Related functions:

Returns a description of a dataset available to this instance of the API.

Pre-call conditions

The API must be initialized, with no searches in progress. A specific instance must have been started with QABatchWV_Open.

Prototype

INTRET QABatchWV_GetCountry 
    (INTVAL viHandle,
    INTVAL viIndex,
    STRREF rsIsoCode,
    STRREF rsCountry,
    INTVAL viLength);

Parameters

Argument Description
viHandle Handle for this instance of the API. If the handle that is passed to viHandle is 0, all datasets are used. If the handle is passed, all datasets within the section are used.
viIndex Number of dataset.
rsIsoCode Buffer to receive the dataset identifier.
rsCountry Buffer to receive name of dataset.
viLength Maximum length of rsCountry.

Return values

Either: 0 if call successful
Or: negative error code

Possible error scenarios

Errors Descriptions
Not running The API has not been started properly. QABatchWV_Startup must be successfully called prior to this function.
Bad handle The handle passed to the parameter viHandle is not valid. QABatchWV_Open must be successfully called prior to this function, and the handle returned in riHandle should be used.
Bad parameter One of the API parameters has been passed aninvalid value. Use the LogErrors configuration setting to determine the cause of the problem.
Country out of range The index passed to the viIndex parameter is too large. The value should be between 0 and the count returned from QABatchWV_CountryCount -1.

Comments

This function, in conjunction with QABatchWV_CountryCount, is useful if you want to confirm the number, names and dataset identifiers of available datasets for a particular instance of the API. You might want to call these two functions prior to the first call of QABatchWV_Clean so that you know which datasets are available to search on. You can also pass the dataset identifier into QABatchWV_DataSetInfo to get further information about thedataset.

You should call this function as many times as required to retrieve dataset details. For example, if QABatchWV_CountryCount returned a count of 4, you would call QABatchWV_GetCountry 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 rsIsoCode and rsCountry contain the dataset identifier and country name respectively of a dataset. A dataset identifier is a three-character descriptor for a dataset, which appears on the data sheet supplied with each dataset. For example, the Australia dataset identifier is AUS.

The rsIsoCode buffer must be at least 4 characters long, in order to accommodate a three-character dataset identifier and a trailing NULL.

Related functions:

Returns information about a particular dataset.

Pre-call conditions

The API must be initialized. A specific instance must have been started with QABatchWV_Open.

Prototype

INTRET QABatchWV_DataSetInfo
    (INTVAL viHandle,
    STRVAL vsIsoCode,  
    INTREF riDaysLeft, 
    INTREF riDataDaysLeft,
    INTREF riLicenceDaysLeft, 
    STRREF rsVersion,
    INTVAL viVerLength, 
    STRREF rsCopyright, 
    INTVAL viCopyrightLength);

Parameters

Argument Description
viHandle Handle for this instance of the API.
vsIsoCode The dataset or additional dataset identifier for which information will be returned.
riDaysLeft The lower of riDataDaysLeft and riLicenceDaysLeft. riDataDaysLeft Number of days left until the first dataset expires.
riLicenceDaysLeft Number of days left until the first license in the dataset expires.
rsVersion Buffer to receive version information for the dataset.
viVerLength Maximum length of rsVersion.
rsCopyright Buffer to receive copyright information. viCopyrightLength Maximum length of rsCopyright.

Return values

Either: 0 if call successful
Or: negative error code

Possible error scenarios

Errors Descriptions
Not running The API has not been started properly. QABatchWV_Startup must be successfully called prior to this function.
Bad handle The handle passed to the parameter viHandle is not valid.QABatchWV_Open must be successfully called prior to this function, and the handle returned in riHandle should be used.
Bad parameter One of the API parameters has been passed an invalid value. Use the LogErrors configuration setting to determine the cause of the problem.
Invalid country The string passed to the vsIsoCode parameter is not valid. The dataset identifier of the dataset has to be specified in the InstalledData configuration setting.

Comments

When you pass a dataset identifier (for example, 'AUS' for Australia) into this function, it returns information about the dataset to which the dataset identifier relates.

The parameter riDaysLeft contains the lower of riDataDaysLeft and riLicenceDaysLeft. For example, if riDataDaysLeft is 60 and riLicenceDaysLeft is 90, the riDaysLeft parameter will contain 60.

The parameter rsCopyright contains copyright information for the dataset in question. For example, the Australia dataset returns a copyright for Australia Post.

If you only want to see some of the information that can be returned from this function, you can set return parameters to NULL. For example, if you only want to see when the dataset is going to expire, you can set rsVersion and rsCopyright to NULL.

Related functions:

Retrieves the number of DataPlus sets, additional datasets and keyfinder sets that are associated with a dataset.

Pre-call conditions

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

Prototype

INTRET QABatchWV_DataSetCount
    (INTVAL viHandle,
    STRVAL vsIsoCode,
    INTREF riCount);

Parameters

Argument Description
viHandle Handle for this instance of the API.
vsIsoCode The identifier of the set for which information will be returned.
riCount Number of sets associated with a dataset.

Return values

Either: 0 if call successful
Or: negative error code

Possible error scenarios

Errors Descriptions
Not running The API has not been started properly. QABatchWV_Startup must be successfully called prior to this function.
Bad parameter One of the API parameters has been passed an invalidvalue. Use the LogErrors configuration setting to determine the cause of the problem.
File error The file specified in vsIniFile could not be opened.

Related functions

Retrieves the DataPlus sets, additional datasets and keyfinder sets for a dataset.

Pre-call conditions

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

Prototype

INTRET QABatchWV_GetDataSet
    (INTVAL viHandle,
    INTVAL viIndex,
    STRVAL vsIsoCode,
    STRREF rsName,
    INTVAL viNameLength,
    STRREF rsDesc,
    INTVAL viDescLength,
    LONGREF rlType);

Parameters

Argument Description
*viHandle *Handle for this instance of the API.
viIndex Set index (between 0 and count).
vsIsoCode The dataset identifier of the dataset for which information will be returned.
rsName Name of dataset.
viNameLength Maximum length of buffer for rsName.
rsDesc Description of the dataset.
viDescLength Maximum length of buffer for rsDesc.
rlType Type of data.

Return values

Either: 0 if call successful
Or: negative error code

Possible values of rlType

Value Description
datasettype_BASE 1 Dataset type is base dataset.
datasettype_DATAPLUS 2 Dataset type is DataPlus set.
datasettype_ADDITIONAL 4 Dataset type is additional dataset.
datasettype_KEYFINDER 32 Dataset type is keyfinder (i.e. the dataset contains a logical reverse search key).

Note

Some sets have one and the same name, for ex. aprudp.dap (dataplus set) and aprudp.kfx (keyfinder set). You should make difference between them by the type.

Possible error scenarios

Errors Descriptions
Not running The API has not been started properly. QABatchWV_Startup must be successfully called prior to this function.
Function called out of sequence The function has been called out of sequence. QABatchWV_DataSetCount must be successfully called prior to this function.
Bad parameter One of the API parameters has been passed aninvalid value. Use the LogErrors configuration setting to determine the cause of the problem.
File error The file specified in vsIniFile could not be opened
Dataset out of range The index passed to the viIndex parameter is too large. It should be between 0 and the count from QABatchWV_DataSetCount -1.

Related functions:

Returns the number of lines of licensing information available for a specified dataset.

Pre-call conditions

The API must be initialized. A specific instance must have been started with QABatchWV_Open.

Prototype

INTRET QABatchWV_LicenceInfoCount
    (INTVAL viHandle,
    STRVAL vsIsoCode,
    INTREF riLicenceInfoCount);

Parameters

Argument Description
viHandle Handle for this instance of the API.
vsIsoCode The dataset identifier of the dataset for which information will be returned.
vsLicenceInfoCount The number of license information lines available.

Return values

Either: 0 if call successful
Or: negative error code

Possible error scenarios

Errors Descriptions
Not running The API has not been started properly. QABatchWV_Startup must be successfully called prior to this function.
Bad handle The handle passed to the parameter viHandle is not valid. QABatchWV_Open must be successfully called prior to this function, and the handle returned in *riHandle *should be used.
Bad parameter One of the API parameters has been passed an invalidvalue. Use the LogErrors configuration setting to determine the cause of the problem.
Invalid country The string passed to the vsIsoCode parameter is not valid. The dataset identifier has to be specified in the InstalledData configuration setting.

Comments

One line of licensing information is available for each data file in the specified dataset. A single data file might be core data, an additional dataset (e.g. Names data), or a DataPlus set.

For example, if you have the GBR Mosaic DataPlus set configured in the qawserve.ini file, but there is no license information present in the qalicn.ini file, a count of 1 is returned. In addition, QABatchWV_GetLicenceInfo returns the string "Data Licence not found".

Returns a specified line of licensing information.

Pre-call conditions

The API must be initialized. A specific instance must have been started with QABatchWV_Open.

Prototype

INTRET QABatchWV_GetLicenceInfo
    (INTVAL viHandle,
    STRVAL vsIsoCode,
    INTVAL viLine,
    STRREF rsLicenceInfo,
    INTVAL viLicenceInfoLength);

Parameters

Argument Description
viHandle Handle for this instance of the API.
vsIsoCode The dataset identifier of the dataset for which information will be returned.
viLine The line number of the licensing information to get.
rsLicenceInfo The licensing information string returned.
viLicenceInfoLength The size of the buffer passed into rsLicenceInfo.

Return values

Either: 0 if call successful
Or: negative error code

Possible error scenarios

Errors Descriptions
Not running The API has not been started properly. QABatchWV_Startup must be successfully called prior to this function.
Bad handle The handle passed to the parameter viHandle is not valid. QABatchWV_Open must be successfully called prior to this function, and the handle returned in riHandle should be used.
Bad parameter One of the API parameters has been passed an invalid value. Use the LogErrors configuration setting to determine the cause of the problem.
Invalid country The string passed to the vsIsoCode parameter is not valid. The dataset identifier has to be specified in the InstalledData configuration setting.
Out of range The parameter passed to viLine is too large. This should be a value between 0 and the count from QABatchWV_ LicenceInfoCount -1.

Comments

The licensing information string returned will contain the license information for one data file in the dataset.

Retrieves the number of DataPlus fields that are associated with a given DataPlus or Additional dataset. A list of suitable datasets can be obtained from QABatchWV_DataSetCount and QABatchWV_GetDataSet.

Datasets that can contain DataPlus fields are those of the types datasettype_ DATAPLUS or datasettype_ADDITIONAL. See QABatchWV_GetDataSet for more information about dataset types.

Note that not all datasets listed by QABatchWV_DataSetCount and QABatchWV_GetDataSet will be accessible due to layout and licensing restrictions.

Pre-call conditions

The API must be initialized with QABatchWV_Open.

Prototype

INTRET QABatchWV_GetDPFieldCount
    (INTVAL viHandle,
    STRVAL vsDPSet,
    LONGREF rlCount);

Parameters

Argument Description
viHandle Handle for this instance of the API.
vsDPSet The identifier of the dataset for which information will be returned.
rlCount Number of DataPlus fields associated with a dataset.

Return values

Either: 0 if call successful
Or: negative error code

Possible error scenarios

Errors Descriptions
Not running The API has not been started properly. QABatchWV_Startup must be successfully called prior to this function.
Bad parameter One of the API parameters has been passed an invalid value. Use the LogErrors configuration setting to determine the cause of the problem.
No DataPlus The requested DataPlus is not available for the current layout.

Related functions

Retrieves the code and name for a specific DataPlus field for a dataset. DataPlus fields are indexed from zero to QABatchWV_GetDPFieldCount -1.

The DataPlus field code is suitable for addresses format specification. The DataPlus field name is a human-readable description of the field. Use QABatchWV_GetDPFieldInfo for more information about the DataPlus field.

Pre-call conditions

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

Prototype

INTRET QABatchWV_GetDPFieldName
    (INTVAL viHandle,
    STRVAL vsDPSet,
    INTVAL viIndex,
    STRREF rsCode,
    INTVAL viCodeLength,
    STRREF rsName,
    INTVAL viNameLength);

Parameters

Argument Description
viHandle Handle for this instance of the API.
vsDPSet The dataset identifier of the dataset for which information will be returned.
viIndex Field index (between 0 and count).
rsCode DataPlus field code.
viCodeLength Maximum length of buffer for rsCode.
rsName DataPlus field name.
viNameLength Maximum length of buffer for rsName.

Return values

Either: 0 if call successful
Or: negative error code

Possible error scenarios

Errors Descriptions
Not running The API has not been started properly. QABatchWV_Startup must be successfully called prior to this function.
Function called out of sequence The function has been called out of sequence. QABatchWV_GetDPFieldCount must be successfully called prior to this function.
Bad parameter One of the API parameters has been passed as an invalid value. Use the LogErrors configuration setting to determine the cause of the problem.
No DataPlus The requested DataPlus is not available for the current layout.
Field out of range The index passed to the viIndex parameter is too large. It should be between 0 and the count from QABatchWV_ GetDPFieldCount -1.

Related functions

Retrieves information for a specific DataPlus field for a dataset. DataPlus fields are indexed from zero to QABatchWV_GetDPFieldCount -1.

Pre-call conditions

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

Prototype

INTRET QABatchWV_GetDPFieldInfo
    (INTVAL viHandle,
    STRVAL vsDPSet,
    INTVAL viIndex,
    INTVAL viInfoType,
    STRREF rsStringInfo,
    INTVAL viStringInfoLength,
    LONGREF rlLongInfo);

Parameters

Argument Description
viHandle Handle for this instance of the API.
vsDPSet The dataset identifier of the dataset for which information will be returned.
viIndex Field index (between 0 and count).
viInfoType Field info type.
rsStringInfo Receives the string information for string info types.
viStringInfoLength Maximum length of buffer for rsStringInfo.
rlLongInfo Receives the long information for long info types.

Return values

Either: 0 if call successful
Or: negative error code

Possible values of vsInfoType are:

|Value|Type|Description|
|dpfieldinfotype_CODE|String|Field Code, also returned by QABatchWV_GetDPFieldName.|
|dpfieldinfotype_NAME|String|Field Name, also returned by QABatchWV_GetDPFieldName.|
|dpfieldinfotype_ FORMATSTRING|String|Format String, mainly for date fields.|
|dpfieldinfotype_ATTR|Long|Attributes, bitfield, see the dpfieldatr_values below.|
|dpfieldinfotype_MAXLEN|Long|Maximum possible length for the value when formatting with this field.|

Possible attribute flags returned in rILongInfo for dpfieldinfotype_ ATTR

Value Description
dpfieldattr_DATE Field is a date.
dpfieldattr_BARCODE Field is a barcode.
dpfieldattr_SUPPRESSION Field is part of suppression data.
dpfieldattr_DATERANG Field is a date range.

Possible error scenarios

Errors Descriptions
Not running The API has not been started properly. QABatchWV_Startup must be successfully called prior to this function.
Function called out of sequence The function has been called out of sequence. QABatchWV_GetDPFieldCount must be successfully called prior to this function.
Bad parameter One of the API parameters has been passed an invalid value. Use the LogErrors configuration setting to determine the cause of the problem.
No DataPlus The requested DataPlus is not available for the current layout.
Field out of range The index passed to the viIndex parameter is too large. It should be between 0 and the count from QABatchWV_ GetDPFieldCount -1.
Invalid info type The info type passed to the viInfoType parameter is not valid. See the table above for the list of valid info types.

Related functions

The Batch API also includes four low-level system functions, which cover the whole library system and are common across all product APIs.

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

Arguement Description
outPath Path to the output PS3553 form text file
count Total Records Submitted
dpv ZIP+4/DPV Confirmed
zip5 5-Digit Coded
crt CRRT Coded
elot eLOT Assigned
hdef High Rise Default
hexact High Rise Exact
rrdef RR Default
hexact RR Exact
llk LACSlink(tm)
ews EWS
slk SuiteLink(tm

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

Argument Description
viStatus Error code.
rsBuffer Buffer to receive error text message.
viBuffLen Maximum length of the buffer (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.

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

Argument Description
viAll Specifies the level of errors returned. Set viAll to 0 to access the errors directly associated with the most recent error code, or 1 to access Batch API's entire error history (which is likely to include messages corresponding to unrelated non-fatal internal errors). It is recommended that viAll is set to 0.
viLineNo Line number being accessed (or negative if resetting).
rsBuffer Buffer to receive error text message.
viBuffLen Maximum length of the buffer (including room for NULL terminator).

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

Argument Description
viStatus Error code.

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

Argument Description
viLineNo Line number being accessed (or negative if resetting).
rsBuffer Buffer to receive text line.
viBuffLen Buffer length (including room for NULL terminator).

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)

These functions send the input addresses to the API and return results, and free resources used in the search.

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

Argument Description
viHandle Handle for this instance of the API.
vsSearch Search string.
riSearchHandle Handle returned by search.
rsPostcode Postal code returned from search.
viPostcodeLength Maximum length of buffer to receive returned postal code.
rsIsoCode Dataset identifier.
rsReturnCode Match code brought back for the input address.
viReturnLength Maximum length of buffer to receive match code.

Return values

Either: 0 if call successful
Or: negative error code

Possible error scenarios

Errors Description
Not running The API has not been started properly. QABatchWV_ Startup must be successfully called prior to this function.
Bad handle The handle passed to the parameter viHandle is not valid. QABatchWV_Open must be successfully called prior to this function, and the handle returned in riHandle should be used.
Bad parameter One of the API parameters has been passed an invalid value. Use the LogErrors configuration setting to determine the cause of the problem.
Call pending QABatchWV_Clean has been called too many times with the specified handle. Ensure that QABatchWV_EndSearch is called at the end of each search once the results have been returned.
Invalid input item There is a mistake in the input specification passed to QABatchWV_Open (see InputLineCount and InputLineN).

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:

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

Argument Description
viSearchHandle Handle for this search. If a NULL search handle was passed to QABatchWV_Clean this should be set to 0.

Return values

Either: 0 if call successful
Or: negative error code

Possible error scenarios

Errors Descriptions
Not running The API has not been started properly. QABatchWV_Startup must be successfully called prior to this function.
Bad handle The handle passed to the parameter viSearchHandle is not valid. QABatchWV_Clean must be successfully called prior to this function, and the handle returned from riSearchHandle should be used.
Bad parameter One of the API parameters has been passed an invalidvalue. Use the LogErrors configuration setting to determine the cause of the problem.

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:

These functions return the number and contents of formatted and unused address lines.

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

Argument Description
viHandle Handle for this instance of the API.
vsCountry The dataset identifier for the layout to be returned.
riCount Number of lines in layout.

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

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

Argument Description
viHandle Handle for this instance of the API.
vsCountry The dataset identifier for the layout to be returned.
viLine Address line to retrieve (from 0 to QABatchWV_LayoutLineCount -1).
rsBuffer Buffer to receive line elements.
viLength Maximum length of rsBuffer.
rlFlags Line description.

Return values

Either: 0 if call successful
Or: negative error code

Possible error scenarios

Errors Descriptions
Not running The API has not been started properly. QABatchWV_ Startup must be successfully called prior to this function.
Bad handle The handle passed to the parameter viHandle is not valid. QABatchWV_Open must be successfully called prior to this function, and the handle returned in riHandle should be used.
Bad parameter One of the API parameters has been passed an invalid value. Use the LogErrors configuration setting to determine the cause of the problem.
Invalid country The string passed to the vsCountry parameter is not valid.The dataset identifier has to be specified in the InstalledData configuration setting.
Out of range The parameter passed to viLine is too large. This should be a value between 0 and the count from QABatchWV_ LayoutLineCount -1.

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:

Flag name Value
element_ADDRESS 0x00000000
element_NAME 0x00000001
element_DATAPLUS 0x00000002
element_ANCILLARY 0x00000003
format_TRUNCATED 0x00000010
format_OVERFLOW 0x00000020
format_DATAPLUSSYNTAX 0x00000040
format_DATAPLUSEXPIRED 0x00000080
format_DATAPLUSBLANK 0x00000100

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

Argument Description
viSearchHandle Handle for this search. If a NULL search handle was passed to QABatchWV_Clean this should be set to 0.
riCount Count of formatted lines.

Return values

Either: 0 if call successful
Or: negative error code

Possible error scenarios

Errors Descriptions
Not running The API has not been started properly. QABatchWV_Startup must be successfully called prior to this function.
Bad handle The handle passed to the parameter viSearchHandle is not valid. QABatchWV_Clean must be successfully called prior to this function, and the handle returned from riSearchHandle should be used.
Bad parameter One of the API parameters has been passed an invalid value. Use the LogErrors configuration setting to determine the cause of the problem.

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

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

Argument Description
viSearchHandle Handle for this search. If a NULL search handle was passed to QABatchWV_Clean this should be set to 0.
viLine Number of the line to be retrieved.
rsBuffer Buffer to return the formatted address line.
viBuffLen Maximum length of the address line buffer.

Return values

Either: 0 if call successful
Or: negative error code

Possible error scenarios

Errors Descriptions
Not running The API has not been started properly. QABatchWV_Startup must be successfully called prior to this function.
Bad handle The handle passed to the parameter viSearchHandle is not valid. QABatchWV_Clean must be successfully called prior to this function, and the handle returned from riSearchHandle should be used.
Bad parameter One of the API parameters has been passed an invalid value. Use the LogErrors configuration setting to determine the cause of the problem.
Out of range The parameter passed to viLine is too large. This should be a value between 0 and the count from QABatchWV_ FormattedLineCount -1.

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:

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

Argument Description
viSearchHandle Handle for this search thread.
riCount Number of unused lines.

Return values

Either: 0 if call successful
Or: negative error code

Possible error scenarios

Errors Descriptions
Not running The API has not been started properly. QABatchWV_Startup must be successfully called prior to this function.
Bad handle The handle passed to the parameter viSearchHandle is not valid. QABatchWV_Clean must be successfully called prior to this function, and the handle returned from riSearchHandle should be used.
Bad parameter One of the API parameters has been passed an invalid value. Use the LogErrors configuration setting to determine the cause of the problem.

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

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

Argument Description
viSearchHandle Handle for this search thread. If a NULL search handle was passed to QABatchWV_Clean this should be set to 0.
viLine Number of the line to be retrieved.
rsBuffer Buffer to return the unused line.
viLength Maximum length of the unused line buffer.
rlLineCompleteness Describes how much of the line is unused.
rlLineType Describes what type of information is on the line.
rlLinePosition Describes the position of the line, relative to the street.
riCareOf Boolean denoting whether the line is a 'care of' premises prefix.
riPremSuffix Boolean denoting whether the line is an alphabetic premises suffix.

Return values

Either: 0 if call successful
Or: negative error code

Possible values of rlLineCompleteness

Value Descriptions
unusedcompleteness_COMPLETE Complete line (i.e. as supplied)
unusedcompleteness_PARTIAL Incomplete line (i.e. part matched)

Possible values of rlLineType are:

Value Descriptions
unusedtype_ADDRESS Unused address data
unusedtype_NAME Unused name data

Possible values of rlLinePosition are:

Value Descriptions
unusedstreet_PRESTREET Appeared before matched street
unusedstreet_POSTSTREET Appeared after matched street

Possible error scenarios

Errors Descriptions
Not running The API has not been started properly. QABatchWV_Startup must be successfully called prior to this function.
Bad handle The handle passed to the parameter viSearchHandle is not valid. QABatchWV_Clean must be successfully called prior to this function, and the handle returned from riSearchHandle should be used.
Bad parameter One of the API parameters has been passed an invalid value. Use the LogErrors configuration setting to determine the cause of the problem.
Out of range The parameter passed to viLine is too large. This should be a value between 0 and the count from QABatchWV_ UnusedLineCount -1.

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:

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

Argument Description
viSearchHandle Handle for this search thread.
rsIsoCode Dataset identifier.
rsMatchType Match type (zero-terminated single letter).
riConfidence Confidence of match (0-9).
riPostcodeAction Action performed on postal code (0-3).
riAddressAction Action performed on address (0-3).
rlGenericInfo Generic information (32 bit values).
rlCountryInfo Dataset-specific information (32 bit values).
rlCountryInfo2 Additional Dataset-specific information (32 bit values).

Return values

Either: 0 if call successful
Or: negative error code

Possible error scenarios

Errors Descriptions
Not running The API has not been started properly. QABatchWV_Startup must be successfully called prior to this function.
Bad handle The handle passed to the parameter viSearchHandle is not valid. QABatchWV_Clean must be successfully called prior to this function, and the handle returned from riSearchHandle should be used.
Bad parameter One of the API parameters has been passed an invalid value. Use the LogErrors configuration setting to determine the cause of the problem.

Related functions

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

Argument Description
handle An opened batch handle from previously called QABatchWV_Open.
index Index (zero based) of the OLT from the group, retrieved by the last call of QABatchWV_GetOlts
code Output – the code of the OLT (e.g. L11)
maxCodeLen Maximum number of characters, that can be returned in code.
name Output – the name of the OLT (e.g. County)
maxNameLen Maximum number of characters, that can be returned in name.

Return values

Either: 0 if call successful
Or: negative error code

Possible error scenarios

Errors Descriptions
No such index The index supplied is equal or greater than the oltCount, returned by QABatchWV_Open.

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

Argument Description
handle An opened batch handle from previously called QABatchWV_Open.
identifier Identifier of the OLT group. Giving a name of a base dataset (like GBR) will get all the OLTs for the base dataset. Giving a name of an ADS (like GBRELC) will get all the OLTs from the base dataset plus the OLTs from the ADS
isSupression Output parameter that is set to non-zero if the identifier identifies a suppression ADS. Otherwise this is set to 0. If the identifier identifies a base dataset, it is also set to 0.
oltCount Output parameter that is set to the number of the OLTs, in the group identified by identifier.

Return values

Either: 0 if call successful
Or: negative error code

Possible error scenarios

Errors Descriptions
No OLT group with such identifier identifier does not identify base dataset or an ADS. Dataset containing the desired identifier is not in qaserve.ini. ADS file needed is not available.

Comments

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

This information is only relevant when using USA data.

The Batch 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 Batch API:

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

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

Return values

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

Possible error scenarios

Errors Descriptions
Not running The API has not been started properly. QABatchWV_ Startup must be successfully called prior to this function.

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

Argument Description
riLockCodeLength Length of the lock code.

Return values

Either: 0 if call successful
Or: negative error code

Possible error scenarios

Errors Descriptions
Not running The API has not been started properly. QABatchWV_ Startup must be successfully called prior to this function.

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

Argument Description
viDPVInfoType Type of lock information to be returned.
rsDPVInfo Buffer to receive lock information.
viLength Length of provided buffer rsDPVInfo.

Return values

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

Possible values of viDPVInfoType

Values Descriptions
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

Errors Descriptions
Not running The API has not been started properly. QABatchWV_ Startup must be successfully called prior to this function.
Bad parameter One of the API parameters has been passed an invalid value. Use the LogErrors configuration setting 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 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

Argument Description
vsUnlockKey Buffer containing the unlock key.

Return values

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

Possible error scenarios

Errors Descriptions
Not running The API has not been started properly. QABatchWV_Startup 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 Data Quality.

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

Argument Description
riDPVState Returned state of the DPV system.

Return values

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

Possible error scenarios

Errors Descriptions
Not running The API has not been started properly. QABatchWV_Startup must be successfully called prior to this function.

Comments

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

State Macro Descriptions
-1 DPVstate_Unknown Returned by the function in the event of an error.
0 DPVstate_NotInUse The DPV system is not in use.
1 DPVstate_Enabled The DPV system is enabled.
2 DPVstate_Disabled The DPV system has been disabled following a seed address search.

The Batch API includes eight functions that are specific to the use of Suppression data. If you are using Batch API with Suppression data for the first time, Experian Data Quality recommends that you integrate these functions:

Extracts a text-based audit code from the counters file on the disk where Batch API With Suppression is installed.

Pre-call conditions

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

Prototype

INTRET QABatchWV_GetAuditCode 
    STRREF rsAuditCode, INTVAL viAuditCodeLength);

Parameters

Argument Description
rsAuditCode Buffer to receive audit code string.
viAuditCodeLength Maximum length of audit code.

Return values

Either: 0 if call successful
Or: negative error code

Possible error scenarios

Errors Descriptions
Not running The API has not been started properly. QABatchWV_Startup must be successfully called prior to this function.
Bad parameter One of the API parameters has been passed an invalidvalue. Use the LogErrors configuration setting to determine the cause of the problem.

Related functions:

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

Argument Description
viHandle Handle for this instance of the API.
vsAudit1 An audit code created by QABatchWV_GetAuditCode
vsAudit2 An audit code created by QABatchWV_GetAuditCode
rsXmlReport Returns the XML report into the specified buffer.
viXmlReportLength Maximum length of buffer to receive returned XML report.

Return values

Either: 0 if call successful
Or: negative error code

Possible error scenarios

Errors Descriptions
Not running The API has not been started properly. QABatchWV_ Startup must be successfully called prior to this function.
Bad handle The handle passed to the parameter viHandle is not valid. QABatchWV_Open must be successfully called prior to this function, and the handle returned in riHandle should be used
Bad parameter One of the API parameters has been passed an invalid value. Use the LogErrors configuration setting to determine the cause of the problem.
More Clicks Needed If less than 10 clicks have been deducted since the first audit code was generated, the error qaerr_ MORECLICKSNEEDED will be returned. See Error Code Listing for more information.

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:

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

Argument Description
viHandle Handle for this instance of the API.
riCounterHandle Handle for this instance of the counter.

Return values

Either: 0 if call successful
Or: negative error code

Possible error scenarios

Errors Descriptions
Not running The API has not been started properly. QABatchWV_Startup must be successfully called prior to this function.
Bad handle The handle passed to the parameter viHandle is not valid. QABatchWV_Open must be successfully called prior to this function, and the handle returned in riHandle should be used.
Bad parameter One of the API parameters has been passed an invalid value. Use the LogErrors configuration setting to determine the cause of the problem.
Invalid input item There is a mistake in the input specification passed to QABatchWV_Open (see InputLineCount and InputLineN).

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

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

Argument Description
viCounterHandle Handle for this instance of the counter.
rsXmlReport Returns the XML report into a specified buffer.
viXmlReportLength Maximum length of buffer to receive returned XML report.

Return values

Either: 0 if call successful
Or: negative error code

Possible error scenarios

Errors Descriptions
Not running The API has not been started properly. QABatchWV_Startup must be successfully called prior to this function.
Bad handle The handle passed to the parameter viHandle is not valid. QABatchWV_Open must be successfully called prior to this function, and the handle returned in riHandle should be used.
Bad parameter One of the API parameters has been passed an invalid value. Use the LogErrors configuration setting to determine the cause of the problem.

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

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

Argument Description
viCounterHandle Handle for this instance of the counter.
riXmlReportLength Returns an integer of the report length in bytes.

Return values

Either: 0 if call successful
Or: negative error code

Possible error scenarios

Errors Descriptions
Not running The API has not been started properly. QABatchWV_Startup must be successfully called prior to this function.
Bad handle The handle passed to the parameter viHandle is not valid. QABatchWV_Open must be successfully called prior to this function, and the handle returned in riHandle should be used.
Bad parameter One of the API parameters has been passed an invalid value. Use the LogErrors configuration setting to determine the cause of the problem.

Related functions

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

Argument Description
viCounterHandle Handle for this instance of the counter.

Return values

Either: 0 if call successful
Or: negative error code

Possible error scenarios

Errors Descriptions
Not running The API has not been started properly. QABatchWV_Startup must be successfully called prior to this function.
Bad handle The handle passed to the parameter viCounterHandle is not valid. QABatchWV_CounterOpen* must be successfully called prior to this function, and the handle returned in riCounterHandle should be used.
Bad parameter One of the API parameters has been passed an invalid value. Use the LogErrors configuration setting to determine the cause of the problem.

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

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

Argument Description
vsUpdateCode String containing counter update code.

Return values

Either: 0 if call successful
Or: negative error code

Possible error scenarios

Errors Descriptions
Not running The API has not been started properly. QABatchWV_Startup must be successfully called prior to this function.
Bad parameter One of the API parameters has been passed an invalid value. Use the LogErrors configuration setting to determine the cause of the problem.
Invalid copy control code The update code that has been entered is incorrect. Check that the code you entered is identical to the one that you were supplied with by Experian Data Quality, and re-enter if necessary. If the error persists, contact Customer Support.

Related functions:

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

Argument Description
viHandle Handle for this instance of the API.
viEstimateMode To activate Estimate Mode, pass a non-zero value into this parameter. To disable Estimate Mode, pass a zero into this parameter.

Return values

Either: 0 if call successful
Or: negative error code

Possible error scenarios

Errors Descriptions
Not running The API has not been started properly. QABatchWV_Startup must be successfully called prior to this function.
Bad handle The handle passed to the parameter viHandle is not valid. QABatchWV_Open must be successfully called prior to this function, and the handle returned in riHandle should be used.
Bad parameter One of the API parameters has been passed an invalid value. Use the LogErrors configuration setting to determine the cause of the problem.

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

Suppression data is only compatible with Batch API version 6.10 (UK) and later or 7.05 (AUS) and later.

These functions should no longer be used by your application, although Batch API retains them for backwards compatibility.

Deprecated function Superseded by
QABatchWV_Search QABatchWV_Clean
QABatchWV_GetUnusedLine QABatchWV_GetUnusedInput
QABatchWV_DataInfo QABatchWV_DataSetInfo
QABatchWV_GetLayoutLine QABatchWV_LayoutLineElements
Batch API

API reference (SOAP)