This section provides a conceptual overview of how a program using the Batch API works. The pseudocode used is programming language independent.
The example below uses many of the Batch API functions, so that you can see how they work together. In practice, however, you will not need to use every function.
The pseudocode does not include all of the system functions. When using the API within your application, you will probably want to use the function QAErrorMessage after every function call in case an error occurs.
The conventions within the pseudocode are as follows:
| Convention | Description |
|---|---|
| /* Comment */ | Italic text between asterisks and forward slashes denotes a comment. |
| [QABatchWV_DataSetInfo] | The functions which relate to each part of the pseudocode appear in bold type on the right-hand side of the page. |
| [QABatchWV_Open (Close)] | Some API functions are 'paired', i.e. when a function is called, its pair must also be called at some point. When a paired function is used in the pseudocode, its pair appears in brackets directly after the function name. |
/* Before calling any function in the Batch API, you must initialize it with QABatchWV_Startup. If this function is called successfully, you can move on to other functions. */
Initialise API [QABatchWV_Startup (Shutdown)]
If initialisation failed
get textual description of error [QAErrorMessage]
display error
shut down API [QABatchWV_Shutdown]
exit procedure
end if
/* Once the API is initialized, you can either call the non-search related functions, or open a search session. In this case, the program gets a list of available layouts and asks the user to select one. */
Get number of available layouts [QABatchWV_LayoutCount]
for each layout
retrieve layout name [QABatchWV_GetLayout]
display layout name
end for
Ask user to select one of displayed layouts
/* A layout contains information such as the available datasets, the default dataset, and the output address format. Now that the user has chosen a layout, the program moves on to open an instance of the API, in order to perform searches. */
Open an instance of the API [QABatchWV_Open (Close)]
/* The open might fail for various reasons. The most common reason is that a specified dataset is not installed. */
If open failed
get textual description of error [QAErrorMessage] display error
close API instance [QABatchWV_Close]
shut down API [QABatchWV_ShutDown] exit procedure
end if
/* You can open multiple Batch API instances as required, but you must ensure that each instance is closed with QABatchWV_Close before calling QABatchWV_Shutdown. */
Repeat while there are more searches to perform
/* The following section is only required where USA specific Delivery Point Validation functionality is active. */
If USA DPV component is locked [QABatchWV_DPVState]
get DPV lock code length [QABatchWV_DPVGetCodeLength]
get DPV lock code [QABatchWV_DPVGetCode]
display lock code
Ask user for DPV unlock key
submit DPV unlock key [QABatchWV_DPVSetKey]
end if
/* End of USA-specific pseudocode. */
/* The program is now ready to perform address searches. The address must be supplied to the search function, preferably with each address element separated by a comma. Where the address comes from is up to the user: it could be typed in manually, read from a database, or supplied by another program. */
get input address
perform a search [QABatchWV_Clean (EndSearch)]
/* On completion of a search, the following information is returned: a 28- character match code, a postal code (if successfully matched), and a dataset identifier indicating which dataset the address was matched against. What happens next depends on how you want to use this information. You could accept just the postal code, the complete matched postal address or nothing. The decision you make will almost certainly be based on the match code. For this example, the program assumes you wish to have the full matched postal addresses returned for 'R' and 'Q' match types with a confidence level of 9. In addition, for 'P' and 'N' match types that have a confidence level of 5 or 9, you wish to accept just the postal code. */
if match success letter = 'R' or 'Q' and confidence level = 9
/* With an R or Q match code, you are happy to take the full address. Therefore, you find out how many lines are in this address and read each line one at a time. */
count lines in matched address [QABatchWV_FormattedLineCount]
for each line in the matched address
retrieve address line [QABatchWV_ GetFormattedLine]
end for
/* Now you do something with this matched address. This could be storing it in a database or just displaying it on screen. This program does the latter. */
Display retrieved address
Else if match success letter = 'P' or 'N' and confidence level = 9 or 5
/* In this case, you are only happy to accept the postal code returned by the search function. */
display returned postcode
Else
display message "No acceptable match"
end if
/* You have done the search and processed the results. You now need to clear the search results, ready for the next search. */
free resources used by search [QABatchWV_EndSearch]
/* The following section is only required where USA-specific Delivery Point Validation functionality is active. */
If USA additional dataset-specific information bits 0x00000002 (DPV Disabled) or 0x00000004 (DPV seed address) set for match
get DPV lock code length [QABatchWV_ DPVGetCodeLength]
get DPV lock code [QABatchWV_DPVGetCode]
display lock code
Ask user for DPV unlock key
submit DPV unlock key [QABatchWV_DPVSetKey]
end if
/* End of USA-specific pseudocode. /*
/* When you require no more searches, you need to close this instance of the API and shut down in order to exit cleanly. */
end repeat
Close instance of API [QABatchWV_Close]
Shut down API [QABatchWV_Shutdown]