Address, Postcode and Bank solutions
PROGRAMMING POCKET POSTCODE
The Pocket Postcode Dynamic Link Library provides a powerful and simple way for programmers to integrate the power of Pocket Postcode directly into their database or application running on a Pocket PC. Making use of these powerful facilities has been made as straight-forward as possible, but the API is designed for advanced users who have an understanding of programming.
Developers for the Pocket PC 2003 and higher and Windows CE .NET devices, or those targeting other devices where the .NET Compact Framework is to be installed, may require or prefer to use the Visual Studio .NET environment. Documentation on our classes for using Pocket Postcode with VB .NET and C# .NET is provided in the 'Programming with .NET and Pocket Postcode' section of this manual.
Postcode lookups and
searches are done using only two functions from our standard DLL. The programming involved will vary with the language you are
using, but examples are provided which make it very easy for most popular languages and
illustrate the principles that will guide developers in other environments. If you are using
one of the example languages, you can simply paste the bits of program into your own code,
for immediate use!
The Pocket Postcode API is provided in two DLL files, "postcode.dll" and
"changes.dll". These files are installed into the Windows
folder during installation.
- Define the Data Types or Structures used to communicate with the library: examples of definitions are provided in the example programs for popular languages like eMbedded Visual Basic and eMbedded C++. If your language does not support Types, but can handle long strings, you may still be able to communicate with the DLL by using long strings, as all the structure 'fields' are of string type.
- Declare the DLL Functions. Examples and prototypes of these are also provided, but the syntax may vary.
- Incorporate all the power of Pocket Postcode right within your application! All the data lookups and searches from the main Pocket Postcode program can be carried out by the routines detailed below!
Implementing the use of the Pocket Postcode API typically requires the following steps:
The best place to find the format of Data Type and Structure, or DLL function declarations for your own programming language is within the examples supplied. This discussion uses examples from the Visual Basic language, but the principles apply to all. The file postcode.h contains definitions and declarations for the 'C' or 'C++' languages.
The Postcode Data Type or Structure
Pocket Postcode lookups and searches are
all done from one easy to use data type:
| Type PostcodeData | Field Details |
| lookup As String * 60 | Place a query string to be looked up by the DLL here |
| Postcode As String * 8 | The Postcode to search on / the street for the returned address |
| PostcodeType As String * 2 | LU = Large User SU = Small User |
| Organisation As String * 30 | Postcode contains no Organisation data, but this field is provided for convenience, the DLL will place any Organisation found in the lookup query string here. |
| Property As String * 30 | Postcode contains no Property data, but this field is provided for convenience, the DLL will place any Property found in the lookup query string here. |
| Street As String * 60 | The street to search on / the street for the returned address |
| Locality As String * 60 | The locality to search on / the locality for the returned address |
| Town As String * 30 | The town to search on / the town for the returned address |
| County As String * 30 | The county to search on / the county for the returned address |
| CountyOption As String * 1 | Although
Royal Mail no longer require the County for correct addressing, this specifies
the county type to return in the County field if required: 0 = Omit Counties, 1 = Postal Counties, 2 = Abbreviated Postal Counties, 3 = Postal Including Optional Counties, 4 = Abbreviated Postal Including Optional Counties, 5 = Traditional Counties, 6 = Administrative Counties |
| Mailsort As String * 5 | The Mailsort code for the returned address |
| StdCode As String * 8 | The STD Code to search on / the street for the returned address |
| GridN As String * 6 | The Grid Reference Northing for the returned address - blank for non-Plotter users. |
| GridE As String * 5 | The Grid Reference Easting for the returned address - blank for non-Plotter users. |
| CensusCode As String * 4 | Census Code for this postcode. (Note needs optional pc5.dll data file - no extra cost, otherwise will always be blank) |
| Affluence As String * 30 | Census Affluence Description for this postcode. (Note needs optional pc5.dll data file - no extra cost, otherwise will always be blank) |
| LifeStage As String * 100 | Census LifeStage Description for this postcode. (Note needs optional pc5.dll data file - no extra cost, otherwise will always be blank) |
| AdditionalCensusInfo As String * 200 | Additional Census Information for this postcode. (Note needs optional pc5.dll data file - no extra cost, otherwise will always be blank) |
| Reserved As String * 50 | Reserved for future use |
| End Type |
Changes Data Type or Structure
This is used by the GetChanges function - which can test a postcode to see if it has been replaced and return the replacement postcode.
| Type ChangesType | Field Details |
| Postcode As String * 8 | Postcode Data |
| End Type |
Although it is not essential, you may find it useful to declare the following constants - which are used by the Pocket Postcode DLL functions to return error conditions etc.
| Return Code Constants | ||
| Global Const SUCCESS = 0 | Successful, full postcode returned with no changes. | |
| Global Const CHANGED_POSTCODE = 1 | Successful, full postcode returned with changed postcode. | |
| Global Const OUTCODE_ONLY = 4 | Successful but Outcode only match (not full Postcode) | |
| Global Const OUTCODE_BREAK = 5 | You requested outcode breaks to be provided and one has been encountered, no search data has been returned from this call. | |
| Global Const NOT_FOUND = -2 | No records matching your criteria were found | |
| Global Const ERROR_OPENING_FILES = -4 | Error opening Postcode files | |
| Global Const END_OF_SEARCH = -6 | GetNext has reached the end of a search, no new address data returned. | |
| Global Const DATA_LICENSE_ERROR = -7 | Registration error - run the Welcome program to register your copy of Postcode. | |
| Global Const MAX_LIMIT_REACHED = -9 | To prevent complete data extraction, Postcode does not return more than 300 records at a time, constrain your search. | |
| Global Const NO_SEARCH_DATA = -10 | No data was found to search on | |
| Global Const INVALID_LOOKUP_TYPE = -11 | You passed an invalid lookup type to the GetFirst DLL function. | |
The following constants are used for passing options to the GetFirst API function:
| Return Code Constants | ||
| Global Const LOOKUP = 128 | Specifies a standard lookup on the lookup field | |
| Global Const SEARCH = 129 | Reverse search on postcode data fields | |
| Global Const OUTCODE_BREAKS = 2 | Return sector breaks - recommended to make cancelling easier | |
| Global Const OUTCODE_SKIP = 8 | Specifies that only one record per postcode outcode with the same town should be returned | |
There are two principle functions provided by the Pocket Postcode Dynamic Link Library. There are Unicode and ASCII forms of each of these functions, the Unicode forms are generally easier to work with in the CE environment. The Unicode versions have the prefix 'w'. The String type used in PostcodeData in each of these examples is assumed to be an array of TChars (2 bytes per character) if the Unicode function is used, or an array of Chars (1 byte per character) if the ASCII version is used.
Used to initiate a Postcode Lookup or Search and to return the
first matching address record.
Unicode Declaration
Declare Function GetFirst Lib "postcode.dll"
alias "wGetFirst"
_
(details As PostcodeData, reverse As Long) As Long
ASCII Declaration
Declare Function GetFirst Lib "postcode.dll"
_
(details As PostcodeData, reverse As Integer) As Long
Used to call of subsequent records from a Postcode Lookup
or Search, returns END_OF_SEARCH (-6) when you attempt to call off another
record after all records have been returned.
Unicode Declaration
Declare Function GetNext Lib "postcode.dll"
alias "wGetNext"
_
(details As PostcodeData) As Long
ASCII Declaration
Declare Function GetNext Lib "postcode.dll"
_
(details As PostcodeData) As Long
Usage
To carry out a postcode lookup:
- Initialise your PostcodeData structure to null or zero length strings.
- Set lookup in your PostcodeData structure to the query string you wish to use (e.g. a Postcode - see Find Box & Lookup for full details on what you can specify for a lookup).
- Set CountyOption in your PostcodeData structure to the county type you wish to use (check the data type documentation above for available options).
- Call GetFirst with your PostcodeData structure and with the reverse parameter of GetFirst set to 0 (lookup) or 2 if you require outcode breaks (recommended to give plenty of opportunity to cancel a long lookup at any time). You can also add 8 to this if you only want the first record per outcode to be returned when the lookup becomes a search (e.g. when you enter street, town).
- If GetFirst returns success (return value >=0) call GetNext repeatedly and process the returned record until it returns END_OF_SEARCH (-6) or another error (<0) to call off subsequent records.
To carry out a postcode search:
- Initialise your PostcodeData structure to null or zero length strings.
- Set the fields you wish to search on in your PostcodeData structure to your search criteria. You can search on any combination of town, county, STD Code, postcode, with a street and/or locality (searches including a town are the fastest).
- Set CountyOption in your PostcodeData structure to the county type you wish to use (check the data type documentation above for available options).
- Call GetFirst with your PostcodeData structure and with the reverse parameter of GetFirst set to 0 (lookup) or 3 if you require outcode breaks (recommended to give plenty of opportunity to cancel a long search at any time). You can also add 8 to this if you only want the first record per outcode to be returned.
- If GetFirst returns success (return value >=0) call GetNext repeatedly and process the returned record until it returns END_OF_SEARCH (-6) or another error (<0) to call off subsequent records.
Examples
Postcode Lookup:
| ' Set Lookup Data |
| PostcodeData.Lookup = "B1 1AA" |
| PostcodeData.CountyOption = 0 |
| ' Call Get First to get the first record |
| RetVal = GetFirst(PostcodeData, LOOKUP + OUTCODE_BREAKS) |
| ' If success process and call of subsequent records |
| Do While RetVal >= 0 Then |
| ' Do Something with the data |
| RetVal = GetNext(PostcodeData) |
| Loop |
Postcode Search:
| ' Set Search Data |
| PostcodeData.Street = "Commercial Street" |
| PostcodeData.Town = "Birmingham" |
| PostcodeData.CountyOption = 0 |
| ' Call Get First to get the first record |
| RetVal = GetFirst(PostcodeData, SEARCH + OUTCODE_BREAKS) |
| ' If success process and call of subsequent records |
| Do While RetVal >= 0 Then |
| ' Do Something with the data |
| RetVal = GetNext(PostcodeData) |
| Loop |
GetFirst Return Type
Returns >= 0 if success:
- Returns 0 if success with full postcode returned
- Returns 1 if success with full postcode returned but the postcode was changed
- Returns 4 if success but the outcode only was returned
- Returns 5 if a outcode break was encountered.
Returns <0 if fails:
- Returns -2 if no matching addresses where found
- Returns -4 if there was an error opening the postcode files
- Returns -7 if there was a registration error - run the AFD Welcome program to register Postcode
- Returns -10 if no search data was specified
- Returns -11 if the reverse parameter supplied was not valid.
GetNext Return Type
Returns >= 0 if success:
- Returns 0 - 4 as with GetFirst (all records will have the same value for a particular lookup/search)
- Returns 5 if a outcode break was encountered
Returns <0 if fails:
- Returns -6 if the end of a search was reached or GetFirst has not been called first
- Returns -9 if 300 records have already been called off (lookup/search limit is 300 records).
This function is used to check and return the replacement
postcode for any Postcodes which have been recoded. Although built into the
GetFirst and GetNext routines, it may be useful to use the GetChange
function independently.
Unicode Declaration
Declare Function GetChange Lib
"changes.dll" alias "wGetChange" _
(OldPC as Changes, NewPC as Changes) as Long
ASCII Declaration
Declare Function GetChange Lib
"changes.dll" _
(OldPC As Changes, NewPC As Changes) As Long
Usage
| Dim OldPC as Changes, NewPC as Changes |
| ' Set OldPC to the postcode Typed in |
| OldPC.postcode = PostcodeData.postcode |
| 'Call the changed postcode function |
| Result& = GetChange(OldPC, NewPC) |
| If Result& = 1 Then |
| MsgBox "Postcode: " + OldPC.postcode + " has changed to " + NewPC.postcode, 64, "Postcode Change" |
| ' if the postcode has changed put it into the Postcode Structure |
| PostcodeData.Postcode = NewPC.postcode |
| End If |
Return Type
- Returns 0 Not covered by changes
- Returns 1 Postcode FOUND
- Returns -1 INVALID_POSTCODE
- Returns -2 POSTCODE_NOT_FOUND
- Returns -4 ERROR_OPENING_FILES
If FOUND, then the replacement postcode is returned in NewPC
| Pocket Postcode | ||||||||||||||||||||||||||||
| ||||||||||||||||||||||||||||
 |
| Manual Contents | ||||||||||||||||||
| ||||||||||||||||||
|
| Appendix | ||||||||||
| ||||||||||
|
