AFD Products: Pocket Names & Numbers Manual

PROGRAMMING NAMES & NUMBERS WITH .NET

The Names & Numbers Class (afdnn.vb/afdnn.cs)

For VB and C# .NET developers full compatibility is provided with our core API using the afdnn.vb and afdnn.cs classes provided. These provide direct access to the Pocket Names & Numbers API when using .NET and the classes isolate all the complexities of calling structure based native Windows API's in the .NET environment, while still providing the full efficiency of our fast native address engines.

For VB .NET developers:
The afdnn.vb class is, by default, located in c:\program files\microsoft activesync\Pocket Names and Numbers\examples\vbnet\afdnn.vb. If you open afdpcnn.sln in that folder an example of how to use the class is also provided.

To use this class in your own application copy it to your source code folder for your project. Then with your project open in Visual Studio .NET, click the Project menu, select Add Existing Item, then double click the afdnn.vb class to add - it is now ready to use in your project.

For C# .NET developers:
The afdnn.cs class is, by default, located in your c:\program files\microsoft activesync\Pocket Names and Numbers\examples\csharp\afdnn.cs. If you open afdpcnn.sln in that folder an example of how to use the class is also provided.

To use this class in your own application copy it to your source code folder for your project. Then with your project open in Visual Studio .NET, click the Project menu, select Add Existing Item, then double click the afdnn.cs class to add - it is now ready to use in your project.

Carrying out a Postcode Lookup

To carry out a lookup, first create an instance of the afdnn class if you have not already done so, for example:

VB .NET

Dim nn As afdnn
nn = New afdnn

C# .NET

afdnn nn;
nn = new afdnn();

Next set the Postcode property and call the NNGetPostcode function to return the first matching result for this postcode. For example to lookup the Postcode B11 1AA:

VB .NET

nn.Postcode = "B11 1AA"
nnFlags = afdnn.ALL_RECORDS
retVal = nn.NNGetPostcode(1, nnFlags)

C# .NET

nn.Postcode = "B11 1AA";
nnFlags = afdnn.ALL_RECORDS;
retVal = nn.NNGetPostcode(1, nnFlags);

The first parameter is the record number which for the first call to NNGetPostcode should always be 1 (to retrieve the first record with that postcode).

The final parameter specifies flags to Names & Numbers. When doing a simple Postcode Lookup this should be set to afdnn.ALL_RECORDS.

Before using any of the properties now available following this lookup, you first need to check the return code for any error. If the return value (retVal above) is less than zero an error has occurred. This error could be any of the following:

afdnn.RETURN_INVALID_POSTCODE - The Postcode specified was not valid.

afdnn.RETURN_INVALID_RECORD_NUMBER - Call off index for Address is out of expected range (second parameter)

afdnn.RETURN_POSTCODE_NOT_FOUND - The Postcode specified was not found.

afdnn.RETURN_ERROR_OPENING_FILES - Error opening the Names & Numbers files.

afdnn.RETURN_FILE_READ_ERROR - Names & Numbers encountered an error reading it's data files. Re-install Names & Numbers to replace any corrupted data files.

afdnn.RETURN_DATA_LICENCE_ERROR - Names & Numbers was not correctly registered. Please run the Welcome program to register.

You can retrieve more friendly error text messages by calling the ErrorText function of the object, this takes the return value (retVal in this case) as a parameter and returns a string description of the error. For example code to display this and exit the subroutine to abort the lookup would be as follows:

VB .NET

If retVal < 0 Then
    MsgBox(nn.ErrorText(retVal), MsgBoxStyle.Critical, "Error")
    Exit Sub
End If

C# .NET

if (retVal < 0)
{
    MessageBox.Show(afdnn.ErrorText(retVal));
    return;
}

If the PostcodeFrom property is set after the function returns then a changed postcode (one that has been recoded by Royal Mail) was found. You can inform the user of this change, if desired, by checking the values of the PostcodeFrom and Postcode parameters. For example this could be done as follows:

VB .NET

If nn.PostcodeFrom <> "" Then
    MsgBox("The postcode you entered has changed from " + nn.PostcodeFrom + " to: " + nn.Postcode, MsgBoxStyle.Information, "Changed Postcode")
End If

C# .NET

if (nn.PostcodeFrom != "")
{
    MessageBox.Show("The postcode you entered has changed from " +nn.PostcodeFrom + " to: " + nn.Postcode);
}

If the return value is not negative an error has not occurred, and the return value will indicate the number of addresses on the postcode. You can retrieve all the address records by calling NNGetPostcode with each subsequent value from 2 up to the return value of the function. An example of how to do this is given below:

VB .NET

For addrNo = 1 To retVal
    If addrNo <> 1 Then nn.NNGetPostcode(addrNo, nnFlags)
    ' We now have the address data (afdnn class properties)
    ' Do something with the data
Next locNo

C# .NET

for (addrNo = 1; addrNo <= retVal; addrNo++) {
    if (addrNo != 1) nn.NNGetPostcode(addrNo, nnFlags);
    // We now have the address data (afdnn class properties)
    // Do something with the data
}

After calling the NNGetPostcode function all properties are available for that address in the afdnn class for this instance. Additional properties are also available starting format... which give label formatted versions of some address elements as well as the name and phone number. For a full list of the properties available see the Properties section of this documentation.

If you wish to display the result in a list box you can also retrieve a list box friendly single string by using the ListStr method. The ListStr method of the afdnn class instance simply returns a string. For example the following code would add the result to a list box called lstResults on your form:

VB .NET

lstResults.Items.Add(nn.ListStr())

C# .NET

lstResults.Items.Add(nn.ListStr());

If you wish to store a result for later display then you can store the postcode and address number passed to the NNGetPostcode function that was used to retrieve the address. This is the nn.Postcode property and the addrNo variable in the example code given. To retrieve the result simply call NNGetPostcode again with the same postcode and address number to re-retrieve the data. For example the following code retrieves the record again from a postcode and addrNo which have been previously stored:

VB .NET

' later retrieval of a record
nnFlags = afdnn.ALL_RECORDS
nn.Postcode = postcode
NNGetPostcode(addrNo, nnFlags)
' All properties are now accessible for the retrieved address

C# .NET

// later retrieval of a record
nnFlags = afdnn.ALL_RECORDS;
nn.Postcode = postcode;
PCPGetPostcode(addrNo, nnFlags);
// All properties are now accessible for the retrieved address

Carrying out a Search

To carry out a search, first create an instance of the afdnn class if you have not already done so, for example:

VB .NET

Dim nn As afdnn
nn = New afdnn

C# .NET

afdnn nn;
nn = new afdnn();

Next you should call the Clear method as unless this is a newly created object instance old address elements could exist in some of the class instance properties which would affect this search:

VB .NET

nn.Clear()

C# .NET

nn.Clear();

Then you should set the properties for the criteria that you wish to search on. All Names & Numbers properties are searchable (other than the formatted ones). The full list is given in the Properties section.

An example of how to set the search criteria to search for addresses on Stratford Road in Birmingham is as follows:

VB .NET

nn.Street = "Stratford Road"
nn.Town = "Birmingham"

C# .NET

nn.Street = "Stratford Road";
nn.Town = "Birmingham";

The next step is to call the NNInitiateSearch function to initiate the search for matching addresses:

VB .NET

nnFlags = afdnn.MATCHING_RECORDS + afdnn.SECTOR_BREAKS + afdnn.ABSOLUTE_RECORD
retVal = nn.NNInitiateSearch(nnFlags)

C# .NET

nnFlags = afdnn.MATCHING_RECORDS + afdnn.SECTOR_BREAKS + afdnn.ABSOLUTE_RECORD;
retVal = nn.NNInitiateSearch(nnFlags);

The NNInitiateSearch parameter allows search options to be specified. The afdnn.MATCHING_RECORDS constant is usually used with a search as it specifies that only address records that match will be returned (otherwise all records on a postcode that has one or more matching records would be returned). The afdnn.SECTOR_BREAKS constant is also usually desirable as it means that the function will return as it finishes searching each sector which allows the user to cancel the process if required during a long search. The afdnn.ABSOLUTE_RECORD constant is useful if you wish to store records for later retrieval as the address number on the postcode is returned which can be passed back to GetPostcode for later retrieval.

The full set of flag options available are as follows (AND the one's you wish to use and use the same value to pass to each function during your search to ensure consistency and avoid confusion as to where they need to be specified):

Bits 0-3 specify skipping:

afdnn.NO_SKIP - Return all matching records

afdnn.SKIP_TO_NEXT_SECTOR - Only return the first matching record per postcode sector (a sector is the first part of the postcode before the space along with the digit after the space, e.g. 'B11 1').

afdnn.SKIP_TO_NEXT_OUTCODE - Only return the first matching record per outcode (an outcode is the first part of the postcode before the space, e.g. 'B11').

afdnn.SKIP_TO_NEXT_POSTTOWN - Only return the first matching record per post town (The Post Town is a town in the Town field, e.g. Birmingham is a Post Town).

afdnn.SKIP_TO_NEXT_POSTCODE_AREA - Only return the first matching record per postcode area (an area is the letters at the start of the postcode before the first digit, e.g. 'B' or another example is 'AB').

Bits 4-6 specify data subsets to use (currently only USE_ALL_SUBSETS is available):

afdnn.USE_ALL_SUBSETS

Bit 8 specifies if GetPostcode should return all records or only those matching the search:

afdnn.ALL_RECORDS - Return all address records on a matching postcode even if the individual address does not match the search criteria

afdnn.MATCHING_RECORDS - Return only those records on the postcode that match the search criteria.

Bit 9 specifies if sector breaks should be provided or not

afdnn.NO_SECTOR_BREAKS - Specifies that sector breaks should not be returned (these are recommended to allow long searches to be cancelled if desired).

afdnn.SECTOR_BREAKS - Specifies that sector breaks will be returned. A sector is the first part of the postcode before the space along with the digit after the space, e.g. 'B11 1'. This means that as Names & Numbers starts searching a new sector NNGetMatch will return a zero indicating no new record has been returned but giving the opportunity to update progress and for a user to cancel the search.

Bit 10 specifies if the absolute record number should be returned from a search

afdnn.NO_ABSOLUTE_RECORD - The record number corresponds to the number of addresses matching the search and isn't a record number that can be used in a subsequent call to NNGetPostcode to re-retrieve a particular result.

afdnn.ABSOLUTE_RECORD - The record number is an absolute record number for the postcode that can be used for subsequently re-retrieving the record.

Next you can examine the return code for any error. If the return value (retVal above) is less than zero an error has occurred. This error could be any of the following:

afdpcp.RETURN_INVALID_POSTCODE - If the SearchPCFrom and/or SearchPCTo fields were specified but the Postcode specified in the SearchPCFrom and/or SearchPCTo field is not in a valid format.

afdpcp.RETURN_POSTCODE_NOT_FOUND - If no matching records were found.

afdpcp.RETURN_ERROR_OPENING_FILES - Error opening the Names & Numbers files.

afdpcp.RETURN_FILE_READ_ERROR - Names & Numbers encountered an error reading it's data files. Re-install Names & Numbers to replace any corrupted data files.

afdpcp.RETURN_DATA_LICENCE_ERROR - Names & Numbers was not correctly registered. Please run the Welcome program to register.

afdpcp.RETURN_CONFLICTING_SEARCH_PARAMETERS - Name (Surname, Firstname and/or Initial2) properties and the Organisation property were both set. Search for one or the other (no records contain both).

You can retrieve more friendly error text messages by calling the ErrorText function of the object, this takes the return value (retVal in this case) as a parameter and returns a string description of the error. Example code to display this and exit the subroutine to abort the search would be as follows:

VB .NET

If retVal < 0 Then
    MsgBox(nn.ErrorText(retVal), MsgBoxStyle.Critical, "Error")
    Exit Sub
End If

C# .NET

if (retVal < 0)
{
    MessageBox.Show(afdnn.ErrorText(retVal));
    return;
}

If the return value is not negative an error has not occurred, and the return value will indicate the number of sectors which contain the data specified by the search - though these sectors may subsequently be found not to contain addresses which match the exact search criteria when examined by NNGetMatch.

You can now retrieve all the locality records by calling NNGetMatch until it returns afdnn.RETURN_END_OF_SEARCH to indicate that the search has come to an end. The nnFlags parameter is described with InitiateSearch and the same value should be used for both. Where NNGetMatch returns 0 this indicates a sector break and a new postcode with matching records has not been returned. Otherwise NNGetMatch returns the number of matching addresses on that postcode. An example of how to do this is given below:

VB .NET

Do
    noOfAddresses = nn.NNGetMatch(nnFlags)
    If noOfAddresses > 0 Then ' 0 = Sector Break - used to allow cancel
        ' Get the address records for this sector
        For recNo = 1 To noOfAddresses
            addrNo = nn.NNGetPostcode(recNo, nnFlags)
            If addrNo > 0 Then
                ' afdnn class instance properties now available
                ' Do something with the data
            End If
        Next
    End If
    Application.DoEvents() ' Allow user to cancel
Loop Until noOfAddresses < 0 Or CancelFlag ' End of search or user cancels

C# .NET

do
{
    noOfAddresses = nn.NNGetMatch(nnFlags);
    if (noOfAddresses > 0) // 0 = Sector Break - used to allow cancel
    {
        // Get the address records for this sector
        for (recNo = 1; recNo <= noOfAddresses; recNo++)
        {
            addrNo = nn.NNGetPostcode(recNo, nnFlags);
            if (addrNo > 0) {
            {
                // afdnn class instance properties now available
                // Do something with the data
            }
        }
    }
    Application.DoEvents(); // Allow user to cancel
} while ((locNo >= 0) && (!CancelFlag)); // End of search of user cancels

After calling the NNGetPostcode function all the afdnn class instance properties are available for the record. This includes additional properties starting format... which give label formatted versions of some address elements, the name and phone number. For a full list of the properties available see the Properties section of this documentation.

If you wish to display the result in a list box you can also retrieve a list box friendly single string by using the ListStr method. The ListStr method of the afdnn class instance simply returns a string. For example the following code would add the result to a list box called lstResults on your form:

VB .NET

lstResults.Items.Add(nn.ListStr())

C# .NET

lstResults.Items.Add(nn.ListStr());

If you wish to store a result for later display then you can store the postcode for the record and the return value of nn.NNGetPostcode that was used to retrieve the address (the nn.Postcode and addrNo variables in the example code given). To retrieve the result simply call NNGetPostcode, after setting the postcode property, with the address number to re-retrieve the data. Please note that you must have specified the afdnn.NO_ABSOLUTE_RECORD in the nnFlags property during your search for this to work correctly.   For example the following code retrieves the record again from a postcode and addrNo which have been previously stored:

VB .NET

' later retrieval of a record
nn.Postcode = postcode;
nnFlags = afdnn.ALL_RECORDS
NNGetPostcode(addrNo, nnFlags)
' All properties are now accessible for the retrieved address

C# .NET

// later retrieval of a record
nn.Postcode = postcode;
nnFlags = afdnn.ALL_RECORDS;
PCPGetPostcode(addrNo, nnFlags);
// All properties are now accessible for the retrieved address

Carrying out a FastFind

To carry out a fastfind, first create an instance of the afdnn class if you have not already done so, for example:

VB .NET

Dim nn As afdnn
nn = New afdnn

C# .NET

afdnn nn;
nn = new afdnn();

The next step is to call the NNFastFind function to initiate the search for matching addresses with the fast-find string that you wish to use:

VB .NET

searchStr = "Commercial Street, Birmingham" + Space(512)
nnFlags = afdnn.MATCHING_RECORDS + afdnn.SECTOR_BREAKS + afdnn.ABSOLUTE_RECORD
retVal = nn.NNFastFind(searchStr, 2048 + nnFlags)

C# .NET

searchStr = "Commercial Street, Birmingham" + new string(' ', 512);
nnFlags = afdnn.MATCHING_RECORDS + afdnn.SECTOR_BREAKS + afdnn.ABSOLUTE_RECORD;
retVal = nn.NNInitiateSearch(searchStr, nnFlags);

The NNFastFind nnFlags parameter allows search options to be specified. The afdnn.MATCHING_RECORDS constant is usually used with a search as it specifies that only address records that match will be returned (otherwise all records on a postcode that has one or more matching records would be returned). The afdnn.SECTOR_BREAKS constant is also usually desirable as it means that the function will return as it finishes searching each sector which allows the user to cancel the process if required during a long search. The afdnn.ABSOLUTE_RECORD constant is useful if you wish to store records for later retrieval as the address number on the postcode is returned which can be passed back to GetPostcode for later retrieval.

The full set of flag options available are as follows (AND the one's you wish to use and use the same value to pass to each function during your search to ensure consistency and avoid confusion as to where they need to be specified):

Bits 0-3 specify skipping:

afdnn.NO_SKIP - Return all matching records

afdnn.SKIP_TO_NEXT_SECTOR - Only return the first matching record per postcode sector (a sector is the first part of the postcode before the space along with the digit after the space, e.g. 'B11 1').

afdnn.SKIP_TO_NEXT_OUTCODE - Only return the first matching record per outcode (an outcode is the first part of the postcode before the space, e.g. 'B11').

afdnn.SKIP_TO_NEXT_POSTTOWN - Only return the first matching record per post town (The Post Town is a town in the Town field, e.g. Birmingham is a Post Town).

afdnn.SKIP_TO_NEXT_POSTCODE_AREA - Only return the first matching record per postcode area (an area is the letters at the start of the postcode before the first digit, e.g. 'B' or another example is 'AB').

Bits 4-6 specify data subsets to use (currently only USE_ALL_SUBSETS is available):

afdnn.USE_ALL_SUBSETS

Bit 8 specifies if GetPostcode should return all records or only those matching the search:

afdnn.ALL_RECORDS - Return all address records on a matching postcode even if the individual address does not match the search criteria

afdnn.MATCHING_RECORDS - Return only those records on the postcode that match the search criteria.

Bit 9 specifies if sector breaks should be provided or not

afdnn.NO_SECTOR_BREAKS - Specifies that sector breaks should not be returned (these are recommended to allow long searches to be cancelled if desired).

afdnn.SECTOR_BREAKS - Specifies that sector breaks will be returned. A sector is the first part of the postcode before the space along with the digit after the space, e.g. 'B11 1'. This means that as Names & Numbers starts searching a new sector NNGetMatch will return a zero indicating no new record has been returned but giving the opportunity to update progress and for a user to cancel the search.

Bit 10 specifies if the absolute record number should be returned from a search

afdnn.NO_ABSOLUTE_RECORD - The record number corresponds to the number of addresses matching the search and isn't a record number that can be used in a subsequent call to NNGetPostcode to re-retrieve a particular result.

afdnn.ABSOLUTE_RECORD - The record number is an absolute record number for the postcode that can be used for subsequently re-retrieving the record.

Next you can examine the return code for any error. If the return value (retVal above) is less than zero an error has occurred. This error could be any of the following:

afdpcp.RETURN_INVALID_POSTCODE - If the SearchPCFrom and/or SearchPCTo fields were specified but the Postcode specified in the SearchPCFrom and/or SearchPCTo field is not in a valid format.

afdpcp.RETURN_POSTCODE_NOT_FOUND - If no matching records were found.

afdpcp.RETURN_ERROR_OPENING_FILES - Error opening the Names & Numbers files.

afdpcp.RETURN_FILE_READ_ERROR - Names & Numbers encountered an error reading it's data files. Re-install Names & Numbers to replace any corrupted data files.

afdpcp.RETURN_DATA_LICENCE_ERROR - Names & Numbers was not correctly registered. Please run the Welcome program to register.

afdpcp.RETURN_CONFLICTING_SEARCH_PARAMETERS - Name (Surname, Firstname and/or Initial2) properties and the Organisation property were both set. Search for one or the other (no records contain both).

You can retrieve more friendly error text messages by calling the ErrorText function of the object, this takes the return value (retVal in this case) as a parameter and returns a string description of the error. Example code to display this and exit the subroutine to abort the search would be as follows:

VB .NET

If retVal < 0 Then
    MsgBox(nn.ErrorText(retVal), MsgBoxStyle.Critical, "Error")
    Exit Sub
End If

C# .NET

if (retVal < 0)
{
    MessageBox.Show(afdnn.ErrorText(retVal));
    return;
}

If the return value is not negative an error has not occurred, and the return value will indicate the number of sectors which contain the data specified by the search - though these sectors may subsequently be found not to contain addresses which match the exact search criteria when examined by NNGetMatch.

You can now retrieve all the locality records by calling NNGetMatch until it returns afdnn.RETURN_END_OF_SEARCH to indicate that the search has come to an end. The nnFlags parameter is described with InitiateSearch and the same value should be used for both. Where NNGetMatch returns 0 this indicates a sector break and a new postcode with matching records has not been returned. Otherwise NNGetMatch returns the number of matching addresses on that postcode. An example of how to do this is given below:

VB .NET

Do
    noOfAddresses = nn.NNGetMatch(nnFlags)
    If noOfAddresses > 0 Then ' 0 = Sector Break - used to allow cancel
        ' Get the address records for this sector
        For recNo = 1 To noOfAddresses
            addrNo = nn.NNGetPostcode(recNo, nnFlags)
            If addrNo > 0 Then
                ' afdnn class instance properties now available
                ' Do something with the data
            End If
        Next
    End If
    Application.DoEvents() ' Allow user to cancel
Loop Until noOfAddresses < 0 Or CancelFlag ' End of search or user cancels

C# .NET

do
{
    noOfAddresses = nn.NNGetMatch(nnFlags);
    if (noOfAddresses > 0) // 0 = Sector Break - used to allow cancel
    {
        // Get the address records for this sector
        for (recNo = 1; recNo <= noOfAddresses; recNo++)
        {
            addrNo = nn.NNGetPostcode(recNo, nnFlags);
            if (addrNo > 0) {
            {
                // afdnn class instance properties now available
                // Do something with the data
            }
        }
    }
    Application.DoEvents(); // Allow user to cancel
} while ((locNo >= 0) && (!CancelFlag)); // End of search of user cancels

After calling the NNGetPostcode function all the afdnn class instance properties are available for the record. This includes additional properties starting format... which give label formatted versions of some address elements, the name and phone number. For a full list of the properties available see the Properties section of this documentation.

If you wish to display the result in a list box you can also retrieve a list box friendly single string by using the ListStr method. The ListStr method of the afdnn class instance simply returns a string. For example the following code would add the result to a list box called lstResults on your form:

VB .NET

lstResults.Items.Add(nn.ListStr())

C# .NET

lstResults.Items.Add(nn.ListStr());

If you wish to store a result for later display then you can store the postcode for the record and the return value of nn.NNGetPostcode that was used to retrieve the address (the nn.Postcode and addrNo variables in the example code given). To retrieve the result simply call NNGetPostcode, after setting the Postcode property, with the address number to re-retrieve the data. Please note that you must have specified the afdnn.NO_ABSOLUTE_RECORD in the nnFlags property during your search for this to work correctly.   For example the following code retrieves the record again from a postcode and addrNo which have been previously stored:

VB .NET

' later retrieval of a record
nnFlags = afdnn.ALL_RECORDS
nn.Postcode = postcode
nn.NNGetPostcode(addrNo, nnFlags)
' All properties are now accessible for the retrieved address

C# .NET

// later retrieval of a record
nnFlags = afdnn.ALL_RECORDS;
nn.Postcode = postcode;
nn.PCPGetPostcode(addrNo, nnFlags);
// All properties are now accessible for the retrieved address

Field Lists

NNListFirst and NNListNext can be used together to provide the first & subsequent entries for a list of available values within the Names & Numbers data for any given field. The initial request is made with NNListFirst and subsequent list values are called off using NNListNext. A field value can also be supplied to shorten the list to only those starting with the specified value.

To use this functionality, first create an instance of the afdnn class if you have not already done so, for example:

VB .NET

Dim nn As afdnn
nn = New afdnn

C# .NET

afdnn nn;
nn = new afdnn();

Next call NNListFirst passing a string by reference as the first parameter. This can either be blank or contain the text that you want any matching fields to start with. This will be where the first matching field is returned. The second parameter should be the name of the field to obtain a list for, e.g. "street", "locality", "town", etc. The final parameter is the flags which should be set to afdnn.ALL_RECORDS, for example, to lookup towns starting 'Bi':

VB .NET

nnFlags = afdnn.ALL_RECORDS
listRec = "Bi"
fieldName = "town"
retVal = nn.NNListFirst(listRec, fieldName, nnFlags)
If retVal > 0 Then
   ' Success so add value of listRec to a list box etc.
   ' Call NNListNext (see below) repeatedly to obtain subsequent records.
End If

C# .NET

nnFlags = afdnn.ALL_RECORDS;
listRec = "Bi";
fieldName = "town";
retVal = nn.NNListFirst(ref listRec, fieldName, nnFlags);
if (retVal > 0) {
   // Success so add value of listRec to a list box etc.
   // Call NNListNext (see below) repeatedly to obtain subsequent records.
}

If the return value (retVal in this case) is > 0 then the function call has been successfully. A return value of < 0 indicates that no matching items have been found.

To call off subsequent records call the NNListNext function repeatedly until a non-positive return value (<= 0) is returned. It takes the same parameters as NNListNext and returns each subsequent item in the first parameter:

VB .NET

counter = 1 ' Count returned fields to implement an upper limit for speed
Do
retVal = nn.NNListNext(listRec, fieldName, nnFlags)
If retVal > 0 Then
     ' Success so add value of listRec to a list box etc.
     counter = counter + 1
End If
Loop Until retVal <= 0 Or Counter >= 1000 ' Use 1000 as an upper limit

C# .NET

counter = 1; // Count returned fields to implement an upper limit
do
{
retVal = nn.NNListNext(ref listRec, fieldName, nnFlags);
if (retVal > 0)
{
     // Success so add value of listRec to a list box etc.
     counter = counter + 1;
}
} while ((retVal > 0) && (counter < 1000));

Constants Reference

The following is a complete list of all the constants found in the afdnn class.

Constant Description

Return Codes:

RETURN_INVALID_POSTCODE Postcode supplied is not valid

RETURN_POSTCODE_NOT_FOUND Requested Postcode Lookup or Search unsuccessful

RETURN_INVALID_RECORD_NUMBER Call off index for Address is out of expected range

RETURN_ERROR_OPENING_FILES Names & Numbers was unable to open it's data files. Please check the software is installed correctly.

RETURN_FILE_READ_ERROR Error reading Names & Numbers files

RETURN_END_OF_SEARCH This indicates that the search has completed and there are no further records to return - no new record has been returned by this call.

RETURN_DATA_LICENCE_ERROR Names & Numbers was not correctly registered. Please run the Welcome program to register.

RETURN_CONFLICTING_SEARCH_PARAMETERS You have specified both name properties (firstname, initial2 and/or surname) and the Organisation property. You can only specify one or the other (no records have both).

Search Control Flags (For passing as the nnFlags parameter to functions):

NO_SKIP Return all matching records

SKIP_TO_NEXT_SECTOR Only return the first matching record per postcode sector (a sector is the first part of the postcode before the space along with the digit after the space, e.g. 'B11 1').

SKIP_TO_NEXT_OUTCODE Only return the first matching record per outcode (an outcode is the first part of the postcode before the space, e.g. 'B11').

SKIP_TO_NEXT_POSTTOWN Only return the first matching record per post town (The Post Town is a town in the Town field, e.g. Birmingham is a Post Town).

SKIP_TO_NEXT_POSTCODE_AREA Only return the first matching record per postcode area (an area is the letters at the start of the postcode before the first digit, e.g. 'B' or another example is 'AB').

afdnn.USE_ALL_SUBSETS Specifies to use all data subsets (only option available)

afdnn.ALL_RECORDS Return all address records on the given postcode

afdnn.MATCHING_RECORDS Return only those records on the postcode that match the search criteria.

afdnn.NO_SECTOR_BREAKS Specifies that sector breaks should not be returned (these are recommended to allow long searches to be cancelled if desired).

afdnn.SECTOR_BREAKS Specifies that sector breaks will be returned. A sector is the first part of the postcode before the space along with the digit after the space, e.g. 'B11 1'. This means that as Names & Numbers starts searching a new sector NNGetMatch will return a zero indicating no new record has been returned but giving the opportunity to update progress and for a user to cancel the search.

afdnn.NO_ABSOLUTE_RECORD The record number corresponds to the number of addresses matching the search and isn't a record number that can be used in a subsequent call to NNGetPostcode to re-retrieve a particular result if carrying out a search.

afdnn.ABSOLUTE_RECORD The record number is an absolute record number for the postcode that can be used for subsequently re-retrieving the record.

Properties Reference

The following is a complete list of all the properties found in the afdnn class. All these properties are searchable.

Property Type Description

Postcode ReadWrite String Postcode (& used as 'Postcode To' in range searches)

PostcodeFrom ReadWrite String Postcode From (used where a range of postcodes is required in a search and also returns the OLD postcode if a changed postcode is detected)

DPS ReadWrite String Delivery Point Suffix (Uniquely identifies a 'delivery point' or letterbox).

Mailsort ReadWrite String Royal Mail Mailsort Code

STDCode ReadWrite String Predicted STD Code for the Postal Sector

WardCode ReadWrite String Local Authority Ward Code

WardName ReadWrite String Local Authority Ward Name

NHSAreaCode ReadWrite String NHS Area - Code

NHSAreaName ReadWrite String NHS Area - Name

NHSRegionCode ReadWrite String NHS Region - Code

NHSRegionName ReadWrite String NHS Region - Name

PostcodeType ReadWrite String L=Large User, S=Small User, N=Non PAF

GridE ReadWrite String Grid Reference Easting

GridN ReadWrite String Grid Reference Northing

Distance ReadWrite String Distance from Grid Reference specified in the search - in 10ths of a Kilometre

PostalCounty ReadWrite String County Name according to Postal Authority

AdministrativeCounty ReadWrite String County Name for Local Authority purposes

TraditionalCounty ReadWrite String Traditional County Name

Town ReadWrite String Post Town

Locality ReadWrite String Locality (includes Double Dependant Locality)

Street ReadWrite String Street or Thoroughfare (includes Dependent Thoroughfare)

HouseNo ReadWrite String Building Number

Building ReadWrite String Building Name

SubBuilding ReadWrite String Sub-Building Name

Phone ReadWrite String Telephone No where known, incl STD Code

Surname ReadWrite String Surname

FirstName ReadWrite String First Name

Initial2 ReadWrite String Initial of Second Forename

Residency ReadWrite String Length of time resident at this address

Gender ReadWrite String M=Male; F=Female; X=Ambiguous; Blank=Not Known

Organisation ReadWrite String Organisation Name (includes Department, if any)

Business ReadWrite String Business Description - eg 'Solicitors'

Size ReadWrite String Size of company indicated by employee number bands eg A=1-9 employees

SIC ReadWrite String Standard Industry Classification

TVRegion ReadWrite String TV Region

Constituency ReadWrite String Parliamentary Constituency

Authority ReadWrite String Local Authority / Unitary Authority

CameoUKCategory ReadWrite String UK Category (Optional CAMEO dataset must be purchased and installed)

CameoIncomeCategory ReadWrite String Income Category (Optional CAMEO dataset must be purchased and installed)

CameoInvesterCategory ReadWrite String Investor Category (Optional CAMEO dataset must be purchased and installed)

CameoFinancialCategory ReadWrite String Financial Category (Optional CAMEO dataset must be purchased and installed)

CameoUnEmploymentCategory ReadWrite String Unemployment Category (Optional CAMEO dataset must be purchased and installed)

CameoPropertyCategory ReadWrite String Property Category (Optional CAMEO dataset must be purchased and installed)

OnEditedRoll ReadWrite String Indicates if record is on the edited Electoral Roll

HouseholdComposition ReadWrite String Household Composition Type

DOB ReadWrite String Date of Birth

CensusCode ReadWrite String The Censation Census Code

Affluence ReadWrite String The Affluence Description

LifeStage ReadWrite String The LifeStage Description

AdditionalCenusInfo ReadWrite String Additional Census Information

Occupancy ReadWrite String Indicates if postcode likely contains residential, business addresses, or both.
The following possible values are returned:
1. Large User Organisation
2. Small User Organisation
3. Mostly Organisations
4. Mixed
5. Mostly Residential
6. Residential

AddressType ReadWrite String Indicates the type of property data needed to be captured for addresses on this postcode.
The following possible values are returned:
1. Numbered
2. Numbered and Named
3. Numbered and Named, Likelihood of Multiple Occupancy
4. Named
5. Non-Standard Address Format
6. PO Box
7. No Property Information (Capture Organisation or Resident Name)

CouncilTaxBand ReadWrite String Additional Dataset: Provides the Council Tax Band that the selected residential property resides in (Bands A-H)

PCTCode ReadWrite String NHS Primary Care Trust Code in England (Local Heath Board Code in Wales).

PCTName ReadWrite String NHS Primary Care Trust Name in England (Local Heath Board Name in Wales).

Udprn ReadWrite String Royal Mail Unique Delivery Point Reference Number (where applies)

EERCode ReadWrite String European Electoral Region Code

EERName ReadWrite String European Electoral Region Name

UrbanRuralCode ReadWrite String Indicates if an area is mostly urban or rural

UrbanRuralName ReadWrite String Indicates if an area is mostly urban or rural

LEACode ReadWrite String Local Education Authority Code

LEAName ReadWrite String Local Education Authority Name

AFDJustBuilt ReadWrite String Contains the date a building became live on PAF if it is likely to have been a new build.

Latitude ReadWrite String Provides the latitude value for the postcode.

Longitude ReadWrite String Provides the longitude value for the postcode.

Formatted Record
These additional properties, provide formatted address elements which have been formatted to appear on a label. Organisation, Town, etc. are not provided as these are the same as the main Properties. The aim of these is to include the building number with the correct field (e.g. street or locality) and combine property information (including placing a flat number with the street if appropriate). A formatted Name (combining Gender, Firstname, Initial2 and Surname), Phone field, and Distance properties are also included:

Property Type Description

FormattedProp ReadOnly String This gives the Building and SuBuilding concatenated together as appropriate to provide a complete property field. It should be used alongside FormattedStreet as a property such as 61b would be moved to the street line as would be expected on a label.

FormattedStreet ReadOnly String This provides the Street fields concatenated together as appropriate to provide a complete street field. Any building number will also be with the street as would appear on a label.

FormattedLocality ReadOnly String This provides the Locality field. The building number may also be with this if there is no street as is appropriate for display on an address label.

FormattedPhone ReadOnly String This provides the Phone Number with spaces inserted to provide it in a more user presentable format.

FormattedName ReadOnly String This concatenates the Gender (Converted to Mr or Ms), Firstname, Initial2 and Surname together (if given) to provide a name formatted for an address label etc.

FormattedDistanceMiles ReadOnly String Where a radial search has been carried out this returns the distance as miles (the Distance Property is in 10ths of a Kilometre).

FormattedDistanceKm ReadOnly String Where a radial search has been carried out this returns the distance as kilometres (the Distance Property is in 10ths of a Kilometre).

Function Reference

The following is a complete list of all the functions found in the afdnn class.

Function Parameters Returns Description

New - - Default constructor for this class - creates a new instance with all properties initialised to be blank.

New String - Creates a new instance of the class from a stored string representation of a previous instance of the class (use ToString function to retrieve this).

Clear - - This function clears all the class properties. Should be called prior to setting search criteria so that data from a previous result doesn't interfere with the new search.

ErrorText Long String Takes a negative return value of any of the afdnn class functions and returns a string representation of the error number. Static in C#.

ListStr - String Returns a formatted string representation of the address optimised for displaying in a list box for end-user display.

ToString - String Returns a string representation of this class, allowing the instance to easily be saved in minimal memory or on disk for later retrieval of the address. Note this does not save the state of any lookup or search in progress.

NNGetPostcode String, Long, Long Long Takes the postcode to lookup, record number (start by supplying a value of 1), and any required flags (see constants). If successful it returns the number of records on the postcode, otherwise it returns an error code (negative value).

NNInitiateSearch Long Long This takes flags as it's parameter (see nnFlags parameters in the constants section above). It searches using the search properties specified prior to calling this function (see the properties section above). It returns the number of sectors which may contain records matching the data specified by the search or if the search fails it returns a negative error value instead.

NNFastFind String, Long Long This takes the fast-find string to search for and flags as it's parameter (see nnFlags parameters in the constants section above). It returns the number of sectors which may contain records matching the data specified by the search or if the search fails it returns a negative error value instead.

NNGetMatch Long Long Following a call to NNInitiateSearch this function is used to retrieve each postcode that contains results that match the search criteria. It should be repeatedly called until it returns nn.RETURN_END_OF_SEARCH indicating that all potentially matching postcodes have already been returned. It takes a single parameter which is used to indicate if all matching records are returned or only the first per sector. It returns the number of addresses found if a postcode with matching records has been found, or 0 as it finishes each sector searched to provide the opportunity to cancel long searches (no new record has been returned in that case).

NNListFirst ref String, String, Long Long This function is used along with NNListNext to get lists of fields. The first parameter should be the start of the item to match, e.g. 'Bi', and the second parameter the field to list, e.g. 'town'. The last parameter is nnFlags which should be set to ALL_RECORDS. This function will return in the first parameter the first matching field. If the function does not return a positive value no matching list has been found.

NNListNext ref String, String, Long Long This function retrieves subsquent fields in a list. The first parameter will return the next matching item, and the second parameter should be the field to list which should be the same as that passed to NNListFirst. The last parameter is nnFlags which should be set to ALL_RECORDS. This function will return in the first parameter the next matching field. This function should be called repeatedly until a certain upper limit of fields has been returned or it returns a non-positive value (end of the list).

NNGetChange String String This function takes a postcode and will return the new postcode if it has changed. It will return a blank string if there is no change to the supplied postcode or it does not exist.

NNGetAliasLocality ref String, Long Long This function takes a reference to a string (to receive the alias locality name) and a long indicating the number of the alias locality to retrieve. It is used to retrieve the alias localities for a record so should be called following a call to NNGetPostcode if alias localities are desired. Call it with a record number of 1 the first time to get the first locality. It returns the number of alias localities for the locality record, or a negative value if there is an error.

Constant	Description
Return Codes:
RETURN_INVALID_POSTCODE	Postcode supplied is not valid
RETURN_POSTCODE_NOT_FOUND	Requested Postcode Lookup or Search unsuccessful
RETURN_INVALID_RECORD_NUMBER	Call off index for Address is out of expected range
RETURN_ERROR_OPENING_FILES	Names & Numbers was unable to open it's data files. Please check the software is installed correctly.
RETURN_FILE_READ_ERROR	Error reading Names & Numbers files
RETURN_END_OF_SEARCH	This indicates that the search has completed and there are no further records to return - no new record has been returned by this call.
RETURN_DATA_LICENCE_ERROR	Names & Numbers was not correctly registered. Please run the Welcome program to register.
RETURN_CONFLICTING_SEARCH_PARAMETERS	You have specified both name properties (firstname, initial2 and/or surname) and the Organisation property. You can only specify one or the other (no records have both).
Search Control Flags (For passing as the nnFlags parameter to functions):
NO_SKIP	Return all matching records
SKIP_TO_NEXT_SECTOR	Only return the first matching record per postcode sector (a sector is the first part of the postcode before the space along with the digit after the space, e.g. 'B11 1').
SKIP_TO_NEXT_OUTCODE	Only return the first matching record per outcode (an outcode is the first part of the postcode before the space, e.g. 'B11').
SKIP_TO_NEXT_POSTTOWN	Only return the first matching record per post town (The Post Town is a town in the Town field, e.g. Birmingham is a Post Town).
SKIP_TO_NEXT_POSTCODE_AREA	Only return the first matching record per postcode area (an area is the letters at the start of the postcode before the first digit, e.g. 'B' or another example is 'AB').
afdnn.USE_ALL_SUBSETS	Specifies to use all data subsets (only option available)
afdnn.ALL_RECORDS	Return all address records on the given postcode
afdnn.MATCHING_RECORDS	Return only those records on the postcode that match the search criteria.
afdnn.NO_SECTOR_BREAKS	Specifies that sector breaks should not be returned (these are recommended to allow long searches to be cancelled if desired).
afdnn.SECTOR_BREAKS	Specifies that sector breaks will be returned. A sector is the first part of the postcode before the space along with the digit after the space, e.g. 'B11 1'. This means that as Names & Numbers starts searching a new sector NNGetMatch will return a zero indicating no new record has been returned but giving the opportunity to update progress and for a user to cancel the search.
afdnn.NO_ABSOLUTE_RECORD	The record number corresponds to the number of addresses matching the search and isn't a record number that can be used in a subsequent call to NNGetPostcode to re-retrieve a particular result if carrying out a search.
afdnn.ABSOLUTE_RECORD	The record number is an absolute record number for the postcode that can be used for subsequently re-retrieving the record.

Property	Type	Description
Postcode	ReadWrite String	Postcode (& used as 'Postcode To' in range searches)
PostcodeFrom	ReadWrite String	Postcode From (used where a range of postcodes is required in a search and also returns the OLD postcode if a changed postcode is detected)
DPS	ReadWrite String	Delivery Point Suffix (Uniquely identifies a 'delivery point' or letterbox).
Mailsort	ReadWrite String	Royal Mail Mailsort Code
STDCode	ReadWrite String	Predicted STD Code for the Postal Sector
WardCode	ReadWrite String	Local Authority Ward Code
WardName	ReadWrite String	Local Authority Ward Name
NHSAreaCode	ReadWrite String	NHS Area - Code
NHSAreaName	ReadWrite String	NHS Area - Name
NHSRegionCode	ReadWrite String	NHS Region - Code
NHSRegionName	ReadWrite String	NHS Region - Name
PostcodeType	ReadWrite String	L=Large User, S=Small User, N=Non PAF
GridE	ReadWrite String	Grid Reference Easting
GridN	ReadWrite String	Grid Reference Northing
Distance	ReadWrite String	Distance from Grid Reference specified in the search - in 10ths of a Kilometre
PostalCounty	ReadWrite String	County Name according to Postal Authority
AdministrativeCounty	ReadWrite String	County Name for Local Authority purposes
TraditionalCounty	ReadWrite String	Traditional County Name
Town	ReadWrite String	Post Town
Locality	ReadWrite String	Locality (includes Double Dependant Locality)
Street	ReadWrite String	Street or Thoroughfare (includes Dependent Thoroughfare)
HouseNo	ReadWrite String	Building Number
Building	ReadWrite String	Building Name
SubBuilding	ReadWrite String	Sub-Building Name
Phone	ReadWrite String	Telephone No where known, incl STD Code
Surname	ReadWrite String	Surname
FirstName	ReadWrite String	First Name
Initial2	ReadWrite String	Initial of Second Forename
Residency	ReadWrite String	Length of time resident at this address
Gender	ReadWrite String	M=Male; F=Female; X=Ambiguous; Blank=Not Known
Organisation	ReadWrite String	Organisation Name (includes Department, if any)
Business	ReadWrite String	Business Description - eg 'Solicitors'
Size	ReadWrite String	Size of company indicated by employee number bands eg A=1-9 employees
SIC	ReadWrite String	Standard Industry Classification
TVRegion	ReadWrite String	TV Region
Constituency	ReadWrite String	Parliamentary Constituency
Authority	ReadWrite String	Local Authority / Unitary Authority
CameoUKCategory	ReadWrite String	UK Category (Optional CAMEO dataset must be purchased and installed)
CameoIncomeCategory	ReadWrite String	Income Category (Optional CAMEO dataset must be purchased and installed)
CameoInvesterCategory	ReadWrite String	Investor Category (Optional CAMEO dataset must be purchased and installed)
CameoFinancialCategory	ReadWrite String	Financial Category (Optional CAMEO dataset must be purchased and installed)
CameoUnEmploymentCategory	ReadWrite String	Unemployment Category (Optional CAMEO dataset must be purchased and installed)
CameoPropertyCategory	ReadWrite String	Property Category (Optional CAMEO dataset must be purchased and installed)
OnEditedRoll	ReadWrite String	Indicates if record is on the edited Electoral Roll
HouseholdComposition	ReadWrite String	Household Composition Type
DOB	ReadWrite String	Date of Birth
CensusCode	ReadWrite String	The Censation Census Code
Affluence	ReadWrite String	The Affluence Description
LifeStage	ReadWrite String	The LifeStage Description
AdditionalCenusInfo	ReadWrite String	Additional Census Information
Occupancy	ReadWrite String	Indicates if postcode likely contains residential, business addresses, or both. The following possible values are returned: 1. Large User Organisation 2. Small User Organisation 3. Mostly Organisations 4. Mixed 5. Mostly Residential 6. Residential
AddressType	ReadWrite String	Indicates the type of property data needed to be captured for addresses on this postcode. The following possible values are returned: 1. Numbered 2. Numbered and Named 3. Numbered and Named, Likelihood of Multiple Occupancy 4. Named 5. Non-Standard Address Format 6. PO Box 7. No Property Information (Capture Organisation or Resident Name)
CouncilTaxBand	ReadWrite String	Additional Dataset: Provides the Council Tax Band that the selected residential property resides in (Bands A-H)
PCTCode	ReadWrite String	NHS Primary Care Trust Code in England (Local Heath Board Code in Wales).
PCTName	ReadWrite String	NHS Primary Care Trust Name in England (Local Heath Board Name in Wales).
Udprn	ReadWrite String	Royal Mail Unique Delivery Point Reference Number (where applies)
EERCode	ReadWrite String	European Electoral Region Code
EERName	ReadWrite String	European Electoral Region Name
UrbanRuralCode	ReadWrite String	Indicates if an area is mostly urban or rural
UrbanRuralName	ReadWrite String	Indicates if an area is mostly urban or rural
LEACode	ReadWrite String	Local Education Authority Code
LEAName	ReadWrite String	Local Education Authority Name
AFDJustBuilt	ReadWrite String	Contains the date a building became live on PAF if it is likely to have been a new build.
Latitude	ReadWrite String	Provides the latitude value for the postcode.
Longitude	ReadWrite String	Provides the longitude value for the postcode.

Function	Parameters	Returns	Description
New	-	-	Default constructor for this class - creates a new instance with all properties initialised to be blank.
New	String	-	Creates a new instance of the class from a stored string representation of a previous instance of the class (use ToString function to retrieve this).
Clear	-	-	This function clears all the class properties. Should be called prior to setting search criteria so that data from a previous result doesn't interfere with the new search.
ErrorText	Long	String	Takes a negative return value of any of the afdnn class functions and returns a string representation of the error number. Static in C#.
ListStr	-	String	Returns a formatted string representation of the address optimised for displaying in a list box for end-user display.
ToString	-	String	Returns a string representation of this class, allowing the instance to easily be saved in minimal memory or on disk for later retrieval of the address. Note this does not save the state of any lookup or search in progress.
NNGetPostcode	String, Long, Long	Long	Takes the postcode to lookup, record number (start by supplying a value of 1), and any required flags (see constants). If successful it returns the number of records on the postcode, otherwise it returns an error code (negative value).
NNInitiateSearch	Long	Long	This takes flags as it's parameter (see nnFlags parameters in the constants section above). It searches using the search properties specified prior to calling this function (see the properties section above). It returns the number of sectors which may contain records matching the data specified by the search or if the search fails it returns a negative error value instead.
NNFastFind	String, Long	Long	This takes the fast-find string to search for and flags as it's parameter (see nnFlags parameters in the constants section above). It returns the number of sectors which may contain records matching the data specified by the search or if the search fails it returns a negative error value instead.
NNGetMatch	Long	Long	Following a call to NNInitiateSearch this function is used to retrieve each postcode that contains results that match the search criteria. It should be repeatedly called until it returns nn.RETURN_END_OF_SEARCH indicating that all potentially matching postcodes have already been returned. It takes a single parameter which is used to indicate if all matching records are returned or only the first per sector. It returns the number of addresses found if a postcode with matching records has been found, or 0 as it finishes each sector searched to provide the opportunity to cancel long searches (no new record has been returned in that case).
NNListFirst	ref String, String, Long	Long	This function is used along with NNListNext to get lists of fields. The first parameter should be the start of the item to match, e.g. 'Bi', and the second parameter the field to list, e.g. 'town'. The last parameter is nnFlags which should be set to ALL_RECORDS. This function will return in the first parameter the first matching field. If the function does not return a positive value no matching list has been found.
NNListNext	ref String, String, Long	Long	This function retrieves subsquent fields in a list. The first parameter will return the next matching item, and the second parameter should be the field to list which should be the same as that passed to NNListFirst. The last parameter is nnFlags which should be set to ALL_RECORDS. This function will return in the first parameter the next matching field. This function should be called repeatedly until a certain upper limit of fields has been returned or it returns a non-positive value (end of the list).
NNGetChange	String	String	This function takes a postcode and will return the new postcode if it has changed. It will return a blank string if there is no change to the supplied postcode or it does not exist.
NNGetAliasLocality	ref String, Long	Long	This function takes a reference to a string (to receive the alias locality name) and a long indicating the number of the alias locality to retrieve. It is used to retrieve the alias localities for a record so should be called following a call to NNGetPostcode if alias localities are desired. Call it with a record number of 1 the first time to get the first locality. It returns the number of alias localities for the locality record, or a negative value if there is an error.

Address, Postcode and Bank solutions