AFD Products: Pocket BankFinder Manual

AFD Pocket BankFinder Manual: Programming with BankFinder

PROGRAMMING BANKFINDER WITH .NET

The Pocket BankFinder Class (afdbank.vb/afdbank.cs)

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

For VB .NET developers:
The afdbank.vb class is, by default, located in c:\program files\microsoft activesync\pocket bankfinder\examples\vbnet\afdpc.vb. If you open bankfinder.sln in that folder (or bankfinder2002.vbproj for .NET 2002 developers) 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 afdbank.vb class to add - it is now ready to use in your project.

For C# .NET developers:
The afdbank.cs class is, by default, located in c:\program files\microsoft activesync\pocket bankfinder\examples\csharp\afdpc.cs. If you open bankfinder.sln in that folder (or bankfinder2002.csproj for .NET 2002 developers) 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 afdbank.cs class to add - it is now ready to use in your project.

Carrying out a Lookup (for a sort code or other lookup string)

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

VB .NET

Dim bf As afdbank
bf = New afdbank

C# .NET

afdbank bf;
bf = new afdbank();

Next, set the flags value to indicate if you require records in both the UK (BACS) and Irish (IPSO) clearing systems or just one or the other:

VB .NET

Dim flags As Long
flags = 0 ' 0 = Both systems, 1 = UK Only, 2 = Irish Only

C# .NET

long flags = 0; // 0 = Both Systems, 1 = UK Only, 2 = Irish Only

Next, set the SearchLookup property of the afdbank class instance with the string you wish to lookup, e.g. '517032:

VB .NET

bf.SearchLookup = "517032"

C# .NET

bf.SearchLookup = "517032";

The next step is to call the BFGetFirst function to return the first matching result for this lookup:

VB .NET

retVal = bf.BFGetFirst(flags)

C# .NET

retVal = bf.BFGetFirst(ref flags);

Now you can examine the return code for any error and then process the results returned. This is the same for lookup's and searches and is given in the Examining Results section which follows:

Examining Results from a Lookup or Search

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:

afdbank.RETURN_NOT_FOUND - No Records were found matching the lookup or search criteria given.

afdbank.RETURN_ERROR_OPENING_FILES - BankFinder was unable to open it's data files. Please check the software is installed correctly.

afdbank.RETURN_DATA_LICENCE_ERROR - BankFinder was not correctly registered. Please run the Welcome program to register.

afdbank.RETURN_NO_SEARCH_DATA - No lookup or search data was specified, i.e. the SearchLookup property was not set and all the other Search fields were also blank.

If the return value is not negative an error has not occurred.

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(bf.ErrorText(retVal), MsgBoxStyle.Critical, "Error")
    Exit Sub
End If

C# .NET

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

Next you can do something with this result and call off all other results using the GetNext() function:

VB .NET

Do While retVal >= 0
    If retVal <> afdbank.RETURN_RECORD_BREAK Then
         ' Do something with this result
    End If
    retVal = bf.BFGetNext()
Loop

C# .NET

while (retVal >= 0)
{
    if (retVal != afdbank.RETURN_RECORD_BREAK)
    {
        // Do something with this result
    }
    retVal = bf.BFGetNext();
}

BFGetNext could return any of the following:

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

afdbank.RETURN_RECORD_BREAK - This is also a possible return value from BFGetFirst and simply allows you to give the user the chance to cancel during a long lookup or search if desired and prevents it appearing as if your application has frozen waiting for the next result. It cannot occur with single sort code lookup's.

For each result you can read afdbank class instance properties to do something with the data that is returned. These properties are in four groupings, and prior to retrieving details for the members of any group you will need to call the appropriate function to do so. These functions are as follows:

BFGetBankRecord() - Call to reading properties starting with Bank..., these relate to general bank and branch information and the address details.

BFGetBACSRecord() - Call to reading properties starting with BACS..., these relate to information specific to BACS (Bankers Automated Clearing Service) clearing.

BFGetCHAPSRecord() - Call to reading properties starting with CHAPS..., these relate to information specific to CHAPS (Clearing Houses Automated Payment System) clearing.

BFGetCCCCRecord() - Call before reading properties starting with CCCC..., these relate to information specific to C&CCC (Cheque and Credit Clearing Company) clearing.

For example, the following code gets all records and set's a text box on the form to display one of the properties from each group:

VB .NET

bf.BFGetBankRecord()
txtSortCode.Text = bf.BankSortcode
bf.BFGetBACSRecord()
txtBACSSettlement.Text = bf.BACSSettlementBankFullName
bf.BFGetCHAPSRecord()
txtCHAPSPStatus.Text = bf.CHAPSPStatus
bf.BFGetCCCCRecord()
txtCCCCSettlement.Text = bf.CCCCSettlementBankFullName

C# .NET

bf.BFGetBankRecord();
txtSortCode.Text = bf.BankSortcode;
bf.BFGetBACSRecord();
txtBACSSettlement.Text = bf.BACSSettlementBankFullName;
bf.BFGetCHAPSRecord();
txtCHAPSPStatus.Text = bf.CHAPSPStatus;
bf.BFGetCCCCRecord();
txtCCCCSettlement.Text = bf.CCCCSettlementBankFullName;

Please see the properties section for a comprehensive list of all properties for each grouping.

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 of the Listbox. The ListStr method of the afdbank 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(bf.ListStr())

C# .NET

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

If you wish to store a result for later display then you can use the BankRecNo Property which is part of the Bank data grouping and returns a long indicating the bank record number. You can store this and later use the BFJumpToRecord method on an instance of the class to retrieve the full information for the result. The following example show's how this is done:

VB .NET

' method to store result for later retrieval
Dim recNo As Long
bf.GetBankRecord() ' Get the bank properties if not already done so
recNo = bf.BankRecNo
' later retrieval in new method
Dim bf As afdbank
bf = New afdbank()
bf.BFJumpToRecord(recNo)

C# .NET

// method to store result in a string
bf.GetBankRecord(); ' Get the bank properties if not already done so
long recNo = bf.BankRecNo;
// later retrieval in new method
afdbank bf;
bf = new afdbank();
bf.BFJumpToRecord(recNo);

Carrying out a Search

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

VB .NET

Dim bf As afdbank
bf = New afdbank

C# .NET

afdbank bf;
bf = new afdbank();

Next, set the flags value to indicate if you require records in both the UK (BACS) and Irish (IPSO) clearing systems or just one or the other:

VB .NET

Dim flags As Long
flags = 0 ' 0 = Both systems, 1 = UK Only, 2 = Irish Only

C# .NET

long flags = 0; // 0 = Both Systems, 1 = UK Only, 2 = Irish Only

J# .NET

long[] flags = {0}; // 0 = Both Systems, 1 = UK Only, 2 = Irish Only

Next you need to set one or more of the search properties, you will also need to ensure the SearchLookup property is set to a blank string as any lookup criteria is used in preference to the rest. You should set all properties that you don't use to a blank string, as unless this is a newer created object instance old address elements could exist in some of them. The properties available for searching are as follows:

Property Description

SearchLookup Needs to be set to a blank string as will override search criteria if set

SearchSortcode A sort code or partial sort code to search for

SearchBankBIC The Bank BIC to search for

SearchBranchBIC The Branch BIC to search for

SearchPostcode A Postcode or partial postcode to search for - please note this is for the official bank address and may not be the physical branch postcode.

SearchBranchName The Bank Branch to search for

SearchBankName The Owner Bank Name to search for

SearchTown The Town or Location of the bank to search for (note town may not be the physical branch town)

SearchPhone The Phone number to search for (May be a centralised number and not the branch direct)

SearchSearchText Text to match for each result, will search all fields for this data.

An example of how to set the search criteria to search for NatWest branches in Birmingham is as follows:

VB .NET

bf.SearchLookup = ""
bf.SearchSortcode = ""
bf.SearchPostcode = ""
bf.SearchBranchName = ""
bf.SearchBankName = "Natwest"
bf.SearchTown = "Birmingham"
bf.SearchPhone = ""
bf.SearchBankBIC = ""
bf.SearchBranchBIC = ""
bf.SearchSearchText = ""

C# .NET

bf.SearchLookup = "";
bf.SearchSortcode = "";
bf.SearchPostcode = "";
bf.SearchBranchName = "";
bf.SearchBankName = "Natwest";
bf.SearchTown = "Birmingham";
bf.SearchPhone = "";
bf.SearchBankBIC = "";
bf.SearchBranchBIC = "";
bf.SearchSearchText = "";

The next step is to call the BF GetFirst function to return the first matching result for this search:

VB .NET

retVal = bf.BFGetFirst(flags)

C# .NET

retVal = bf.BFGetFirst(ref flags);

Next you can examine the return code for any error and then process the results returned. This is the same as for the lookup's and you should refer to the Examining Results section for details of how to do this.

Validating an Account Number

To validate an account number, first create an instance of the afdbank class if you have not already done so, for example:

VB .NET

Dim bf As afdbank
bf = New afdbank

C# .NET

afdbank bf;
bf = new afdbank();

Next, set the flags value to indicate if you wish to validate accounts held at branches in both the UK (BACS) and Irish (IPSO) clearing systems or just one or the other:

VB .NET

Dim flags As Long
flags = 0 ' 0 = Both systems, 1 = UK Only, 2 = Irish Only

C# .NET

long flags = 0; // 0 = Both Systems, 1 = UK Only, 2 = Irish Only

To validate an account number the BFValidateAccount function is used. To call this you will first need to supply it with the sortcode and account number to be validated (strings), along with a type of account code parameter. The type of account code parameter is sometimes used in the case of non-standard account numbers to provide an additional field needed for submitting such account numbers to BACS. You should note that the sort code and account number, as well as type of account code, all need to be passed by reference as they may be updated should the number need to be translated. For example:

VB .NET

Dim sortcode As String
Dim accountNo As String
Dim typeOfAccount As Long
Dim retval As Long
sortcode = "401101"
accountNo = "61893939"
retval = bf.BFValidateAccount(flags, sortcode, accountNo, typeOfAccount)

C# .NET

string sortcode;
string accountNo;
long typeOfAccount = 0;
long retVal;
sortcode = txtAccountSortCode.Text;
accountNo = txtAccountNumber.Text;
retVal = bf.BFValidateAccount(ref flags, ref sortcode, ref accountNo, ref typeOfAccount);

If the return value is greater or equal to zero then the account is valid. More specifically:

A return value of afdbank.RETURN_SUCCESS means that the account number has been successfully validated

A return value of afdbank.RETURN_VALIDATION_NOT_AVAILABLE means that the account number could not be validated as no validation method exists for the sort code given, however in that case the account number should still be treated as valid.

If the return value is less than zero then an error has occurred. This error could be any of the following:

afdbank.RETURN_NOT_FOUND - The sort code given does not exist, therefore the sort code and account number combination is not valid.

afdbank.RETURN_ERROR_OPENING_FILES - BankFinder was unable to open it's data files. Please check the software is installed correctly.

afdbank.RETURN_DATA_LICENCE_ERROR - BankFinder was not correctly registered. Please run the Welcome program to register.

afdbank.RETURN_INVALID_SORT_CODE - The sort code supplied is not in a valid format or is too long/short to be a sort code (it should be in the format XXXXX, XX-XX-XX, or XX XX XX, where X is a digit)

afdbank.RETURN_INVALID_ACCOUNT_NUMBER - The account number passed is not a valid account number for that branch.

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 would be as follows:

VB .NET

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

C# .NET

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

Validating a Card Number

To validate a card number, first create an instance of the afdbank class if you have not already done so, for example:

VB .NET

Dim bf As afdbank
bf = New afdbank

C# .NET

afdbank bf;
bf = new afdbank();

To validate a card number the ValidateCard function is used. This takes two parameters, the card number to validate and the expiry date of that card. These should both be passed as strings. If the expiry date is a blank string it is not checked. An example of how to validate a card number is as follows:

VB .NET

Dim cardNo As String
Dim expiryDate As String
Dim retval As Long
cardNo = "6439401101618939396"
expiryDate = "04/05"
retval = bf.BFValidateCard(cardNo, expiryDate)

C# .NET

string cardNo;
string expiryDate;
cardNo = "6439401101618939396";
expiryDate = "04/05";
retVal = bf.BFValidateCard(cardNo, expiryDate);

If the return value is greater than zero then the card number is valid. More specifically the return value indicates the card type and these are as follows:

1 - Mastercard

2 - Visa

3 - American Express

4 - Switch

5 - Visa Delta

6 - Visa UK Electron

7 - Visa Purchasing

8 - Switch and Maestro

9 - Maestro

10 - Solo and Maestro

11 - JCB

You may well need to filter out cards that you do not accept. You can retrieve the name of the card as a string by calling the CardTypeText function of the object, this takes the return value (retVal in this case) as a parameter and returns the card name. Example code to display this would be as follows:

VB .NET

If retVal < 0 Then
    MsgBox(bf.CardTypeText(retVal), MsgBoxStyle.Information, "Card Valid")
End If

C# .NET

if (retVal < 0)
{
    MessageBox.Show(afdbank.CardTypeText(retVal));
}

If the return value is less than zero then an error has occurred. This error could be any of the following:

afdbank.RETURN_ERROR_OPENING_FILES - BankFinder was unable to open it's data files. Please check the software is installed correctly.

afdbank.RETURN_DATA_LICENCE_ERROR - BankFinder was not correctly registered. Please run the Welcome program to register.

afdbank.RETURN_INVALID_EXPIRY - The expiry date passed is invalid, it should be in the format MM/YY.

afdbank.RETURN_CARD_EXPIRED - The expiry date passed is in the past or too far ahead in the future to be from a presently valid card.

afdbank.RETURN_INVALID_CARD_NUMBER - The card number passed to the function is not valid.

afdbank.RETURN_VISA_ATM_ONLY - The card number passed to the function is a valid Visa Card but it is valid for ATM use only which means it cannot be used for electronic payment.

afdbank.RETURN_UNRECOGNISED_CARD - The card number passed to the function is theoretically valid but it is not one of the recognised types (Mastercard, Visa, American Express, Switch, Visa Delta, Visa UK Electron, Visa Purchasing, Maestro, Solo or JCB). Therefore it should be treated as invalid.

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 would be as follows:

VB .NET

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

C# .NET

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

Getting Redirected Sort Code Information

If the BACSRedirectedFrom flag is set (property returns True) for a sort code then this means that other branches are redirected to that sort code. If you wish to do a reverse lookup for those branches you can use the BFGetFirstRedirect and BFGetNextRedirect functions as follows:

First create an instance of the afdbank class if you have not already done so, for example:

VB .NET

Dim bf As afdbank
bf = New afdbank

C# .NET

afdbank bf;
bf = new afdbank();

To find the first sortcode redirected to the one you specify call GetFirstRedirect as follows:

VB .NET

Dim sortcode As String
sortcode = "086001"
retval = bf.BFGetFirstRedirect(sortcode)

C# .NET

string sortcode;
sortcode = "086001";
retVal = bf.BFGetFirstRedirect(ref sortcode);

The sortcode must be passed by reference as on a successful call to the function it is replaced with the first sort code redirected to the one you specified.

Following the call to BFGetFirstRedirect 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:

afdbank.RETURN_NOT_FOUND - The sort code supplied doesn't exist.

afdbank.RETURN_ERROR_OPENING_FILES - BankFinder was unable to open it's data files. Please check the software is installed correctly.

afdbank.RETURN_END_OF_SEARCH - No records were found that are redirected to the sort code specified.

afdbank.RETURN_DATA_LICENCE_ERROR - BankFinder was not correctly registered. Please run the Welcome program to register.

If the return value is not negative an error has not occurred (the sort code of the first branch redirected to the one supplied has been returned).

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(bf.ErrorText(retVal), MsgBoxStyle.Critical, "Error")
    Exit Sub
End If

C# .NET

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

Next you can do something with this result and call off all other results using the BFGetNextRedirect() function:

VB .NET

Do While retVal >= 0
     ' Do something with this sortcode
    retVal = bf.BFGetNextRedirect()
Loop

C# .NET

while (retVal >= 0)
{
    // Do something with this sortcode
    retVal = bf.BFGetNextRedirect();
}

BFGetNextRedirect could return any of the following:

afdbank.END_OF_SEARCH - This indicates that the redirect listing has completed and there are no further records to return - no new record has been returned by this call.

.Constants Reference

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

Constant Description

Selection Flags for Lookup/Validation DLL calls:

ALL_RECORDS Return records for both the UK (BACS) and Irish (IPSO) clearing systems.

UK_ONLY Only return records for the UK (BACS) clearing system

IRISH_ONLY Only return records for the Irish (IPSO) clearing system

Return Codes:

RETURN_SUCCESS The call to BFGetFirst or BFGetNext has been successful or the Card or Account Number passed to BFValidateAccount or ValidateCard is Valid.

RETURN_VALIDATION_NOT_AVAILABLE The account number passed to the BFValidateAccount function cannot be validated as no validation methods exists for the specified sort code. It should be assumed to be valid.

RETURN_RECORD_BREAK The call to BFGetFirst or BFGetNext has been successful but no new result has been returned - this is simply a break to allow the user to cancel a potentially long lookup or search.

RETURN_NOT_FOUND No Records were found matching the lookup or search criteria given or if calling BFValidateAccount the sort code supplied does not exist.

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

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

RETURN_DATA_LICENCE_ERROR BankFinder was not correctly registered or has expired. Please run the Welcome program to register.

RETURN_NO_SEARCH_DATA No lookup or search data was specified, i.e. the Lookup property was not set or the Search criteria was all blank.

RETURN_INVALID_SORT_CODE The sort code passed to the BFValidateAccount function is not in a valid format or is too long/short to be a sort code (it should be in the format XXXXX, XX-XX-XX, or XX XX XX, where X is a digit)

RETURN_INVALID_ACCOUNT_NUMBER The account number passed to the BFValidateAccount function is not a valid account number for that branch.

RETURN_INVALID_EXPIRY The expiry date passed to the BFValidateCard function is invalid, it should be in the format MM/YY.

RETURN_CARD_EXPIRED The expiry date passed to the BFValidateCard function is in the past or too far ahead in the future to be from a presently valid card.

RETURN_INVALID_CARD_NUMBER The card number passed to the BFValidateCard function is not valid.

RETURN_VISA_ATM_ONLY The card number passed to the BFValidateCard function is a valid Visa Card but it is valid for ATM use only which means it cannot be used for electronic payment.

RETURN_UNRECOGNISED_CARD The card number passed to the BFValidateCard function is theoretically valid but it is not one of the recognised types (Mastercard, Visa, American Express, Switch, Visa Delta, Visa UK Electron, Visa Purchasing, Maestro, Solo or JCB). Therefore it should be treated as invalid.

Account Number Return Flags

UK_ACCOUNT The account resides at a branch which is part of the UK (BACS) clearing system.

IRISH_ACCOUNT The account resides at a branch which is part of the Irish (IPSO) clearing system.

DUAL_ACCOUNT The account resides at a branch which is part of both the UK (BACS) and Irish (IPSO) clearing systems.

Card Types: - These are possible return values of the ValidateCard function

CARD_TYPE_MASTERCARD The card number passed is valid for Mastercard

CARD_TYPE_VISA The card number passed is valid for Visa

CARD_TYPE_AMERICAN_EXPRESS The card number passed is valid for American Express

CARD_TYPE_SWITCH The card number passed is valid for Switch

CARD_TYPE_VISA_DELTA The card number passed is valid for Visa Delta

CARD_TYPE_VISA_UK_ELECTRON The card number passed is valid for Visa Electron

CARD_TYPE_VISA_PURCHASING The card number passed is valid for Visa Purchasing

CARD_TYPE_SWITCH_AND_MAESTRO The card number passed is valid for Switch and Maestro

CARD_TYPE_MAESTRO The card number passed is valid for Maestro

CARD_TYPE_SOLO_AND_MAESTRO The card number passed is valid for Solo and Maestro

CARD_TYPE_JCB The card number passed is valid for JCB

Properties Reference

The following is a complete list of all the properties found in the afdbank class, grouped by field type:

Bank Properties

Please note that to retrieve these you need to call BFGetBankRecord() following a call to BFGetFirst() or BFGetNext()

Property Type Description

BankRecNo ReadOnly Long Specifies the record number for the returned record. Useful for storing to retrieve the same record later by calling BFJumpToRecord with this record number as a parameter.

BankSortcode ReadOnly String The sortcode

BankBankBIC ReadOnly String The Bank BIC code (Does not apply to IPSO records)

BankBranchBIC ReadOnly String The Branch BIC code (Does not apply to IPSO records)

BankSubBranchSuffix ReadOnly String The sub-branch suffix which allows a branch to be uniquely identified where there is a cluster of branches sharing the same Sort Code (Does not apply to IPSO records)

BankShortBranchTitle ReadOnly String The official title of the branch

BankCentralCountryCode ReadOnly String The ISO Country code for beneficiary banks in other countries

BankSupervisoryBody ReadOnly String Indicates the supervisory body for an institution that is an agency in any of the clearings. This will be A - Bank Of England, B - Building Society Commission, C - Jersey, Guernsey or Isle of Man authorities or D - Other.

BankDeletedDate ReadOnly String Specifies the date the branch was closed if it is not active

BankBranchTypeIndicator ReadOnly String Shows the branch type (M - Main Branch, S - Sub or NAB Branch, or L - Linked Branch)

BankMainBranchSortcode ReadOnly String Set for linked branches in a cluster. It identifies the main branch for the cluster.

BankMajorLocationName ReadOnly String Optional field used to indent the Branch name or place in the printed directory (Does not apply to IPSO records where the branch name is normally also the location).

BankMinorLocationName ReadOnly String Optional field also used to indent the Branch name or place in the printed directory (Does not apply to IPSO records)

BankBranchName ReadOnly String Defines the actual name or place of the branch

BankBranchName2 ReadOnly String Where applicable contains an alternative name or place for the branch

BankFullBranchTitle ReadOnly String Extended title for the institution (BankShortBranchTitle is the official one)

BankOwnerBankShortName ReadOnly String The short version of the name of the Owning Bank

BankOwnerBankFullName ReadOnly String The full version of the name of the Owning Bank

BankOwnerBankCode ReadOnly String The four digit bank code of the Owning Bank (Does not apply to IPSO records).

BankProperty ReadOnly String Property for the postal address (may not be the same as the physical branch address)

BankStreet ReadOnly String Street for the postal address (may not be the same as the physical branch address)

BankLocality ReadOnly String Locality for the postal address (may not be the same as the physical branch address)

BankTown ReadOnly String Town for the postal address (may not be the same as the physical branch address)

BankCounty ReadOnly String County for the postal address (may not be the same as the physical branch address)

BankPostcode ReadOnly String Postcode for the postal address (may not be the same as the physical branch address)

BankStdCode ReadOnly String STD Code for contacting the branch (may not be a direct number for the branch itself).

BankPhone ReadOnly String Phone Number for contacting the branch (may not be a direct number for the branch itself).

BankFaxStdCode ReadOnly String STD Code for sending faxes to the branch (Only applies to IPSO records)

BankFax ReadOnly String Fax Number for the branch (Only applies to IPSO records)

CountryIndicator ReadOnly String Set to 'U' if the record is on the BACS clearing system, or 'I' if it is on the IPSO clearing system. Branches on both will have an entry for each clearing system.

BACS Properties - Not relevant to IPSO records

Please note that to retrieve these you need to call BFGetBACSRecord() following a call to BFGetFirst() or BFGetNext()

Property Type Description

BACSStatus ReadOnly String BACS Clearing Status (M - Branch of a BACS Member, A - Branch of an Agency Bank, N - Does not accept BACS Payments)

BACSLastChange ReadOnly String Effective date on which this data group was last amended

BACSClosedClearing ReadOnly String Where a branch is closed in BACS clearing this date will be set at the same time that the Status field is changed to 'N'.

BACSRedirectedFromFlag ReadOnly Boolean If true other branches are redirected to this Sort Code. (See the BFGetFirstRedirect function to get a list of those redirected to this code)

BACSRedirectedToSortCode ReadOnly String This specifies the Sort Code to which BACS should redirect payments addressed to this Sort Code if applicable.

BACSSettlementBankCode ReadOnly String The BACS generated Bank Code of the Bank that will settle payments for this branch.

BACSSettlementBankShortName ReadOnly String The Short form of the name of the bank corresponding to the BACSSettlementBankCode field.

BACSSettlementBankFullName ReadOnly String The Full form of the name of the bank corresponding to the BACSSettlementBankCode field.

BACSSettlementSection ReadOnly String Numeric data required for BACS to perform it's settlement

BACSSettlementSubSection ReadOnly String Numeric data required for BACS to perform it's settlement

BACSHandlingBankCode ReadOnly String BACS Generated Bank Code that defines the member that will take BACS output for this branch.

BACSHandlingBankShortName ReadOnly String The Short form of the name of the bank corresponding to the BACSHandlingBankCode field

BACSHandlingBankFullName ReadOnly String The Full form of the name of the bank corresponding to the BACSHandlingBankCode field

BACSHandlingBankStream ReadOnly String Numeric code defining the stream of output within the Handling Bank that will be used for payments to this branch

BACSAccountNumberedFlag ReadOnly Boolean Set to True if numbered bank accounts are used by this branch

BACSDDIVoucherFlag ReadOnly Boolean Set to True if Paper vouchers have to be printed for Direct Debit Instructions

BACSAllowedDirectDebits ReadOnly Boolean Set to True if this branch accepts Direct Debits

BACSAllowedBankGiroCredits ReadOnly Boolean Set to True if this branch accepts Bank Giro Credits

BACSAllowedBuildingSocietyCredits ReadOnly Boolean Set to True if this branch accepts Building Society Credits

BACSAllowedDividendInterestPayments ReadOnly Boolean Set to True if this branch accepts Dividend Interest Payments

BACSAllowedDirectDebitInstructions ReadOnly Boolean Set to True if this branch accepts Direct Debit Instructions

BACSAllowedUnpaidChequeClaims ReadOnly Boolean Set to True if this branch accepts UnpaidChequeClaims

CHAPS Properties - Not relevant to IPSO records

Please note that to retrieve these you need to call BFGetCHAPSRecord() following a call to BFGetFirst() or BFGetNext()

Property Type Description

CHAPSPStatus ReadOnly String Shows if the branch can accept CHAPS sterling payments and if it is an agency (M - Branch of a CHAPS £ member, A - Branch of an agency bank, N- Does not accept CHAPS £ payments).

CHAPSPLastChange ReadOnly String Effective date on which this CHAPS sterling data group was last amended.

CHAPSPClosedClearing ReadOnly String Where a branch is closed in CHAPS sterling clearing this will be set at the same time that the CHAPSPStatus field is changed to 'N'.

CHAPSPSettlementBankCode ReadOnly String CHAPS ID of the bank that will settle payments for this branch (not the same as the BACS bank code present elsewhere).

CHAPSPSettlementBankShortName ReadOnly String The short form of the name of the bank corresponding to the CHAPSPSettlementBankCode field.

CHAPSPSettlementBankFullName ReadOnly String The Full form of the name of the bank corresponding to the CHAPSPSettlementBankCode field.

CHAPSEStatus ReadOnly String Shows if the branch can accept CHAPS Euro payments and if it is a direct branch (one of the member BICs which are part of the SWIFT closed user group). (D - Direct Branch, I - Indirect Branch, N - Does not accept CHAPS Euro payments).

CHAPSELastChange ReadOnly String Effective date on which this CHAPS Euro data group was last amended.

CHAPSEClosedClearing ReadOnly String Where a branch is closed in CHAPS Euro clearing this will be set at the same time that the CHAPSEStatus field is changed to 'N'.

CHAPSEEuroRoutingBICBank ReadOnly String Specifies the SWIFT closed user group Bank BIC to which CHAPS Euro payments for this branch should be routed.

CHAPSEEuroRoutingBICBranch ReadOnly String Specifies the SWIFT closed user group Branch BIC to which CHAPS Euro payments for this branch should be routed.

CHAPSESettlementBankCode ReadOnly String CHAPS ID of the bank that will settle payments for this branch.

CHAPSESettlementBankShortName ReadOnly String The Short form of the name of the bank corresponding to the CHAPSESettlementBankCode field.

CHAPSESettlementBankFullName ReadOnly String The Full form of the name of the bank corresponding to the CHAPSESettlementBankCode field.

CHAPSEReturnIndicator ReadOnly Boolean Set to True if this is the branch to which CHAPS Euro payments should be sent.

C&CCC Properties - Not relevant to IPSO records

Please note that to retrieve these you need to call BFGetCCCCRecord() following a call to BFGetFirst() or BFGetNext()

Property Type Description

CCCCStatus ReadOnly String Shows if the branch is part of Cheque and Credit Clearing and if it is an agency. (M - Branch of a C&CCC Member, F - Full agency bank branch, D - Debit agency branch only, N - Not part of C&CCC Clearing)

CCCCLastChange ReadOnly String Effective date on which this C&CCC data group was last amended.

CCCCClosedClearing ReadOnly String Where a branch is closed in C&CCC clearing this will be set at the same time that the Status field is changed to 'N'.

CCCCSettlementBankCode ReadOnly String BACS generated code of the bank that will settle payments for this branch.

CCCCSettlementBankShortName ReadOnly String The short form of the name of the bank corresponding to the CCCCSettlementBankCode field.

CCCCSettlementBankFullName ReadOnly String The Full form of the name of the bank corresponding to the CCCCSettlementBankCode field.

CCCCDebitAgencySortcode ReadOnly String When the Status field is set to 'D' this specifies where cheque clearing is handled for this branch.

CCCCReturnIndicator ReadOnly String Set if this is the branch that other banks should return paper to. It will only be set for a sort code of a Member.

Search Properties

These are the properties that can be specified for a lookup or search, un-used fields must be blank (set to an empty string) for searches.

Property Type Description

SearchLookup WriteOnly String Set to string, e.g. sortcode, to lookup. If set overrides the other search fields which will not be used, Set to blank if wanting to carry out a specific search.

SearchSortcode WriteOnly String A sort code or partial sort code to search for

SearchBankBIC WriteOnly String The Bank BIC to search for

SearchBranchBIC WriteOnly String The Branch BIC to search for

SearchPostcode WriteOnly String A Postcode or partial postcode to search for - please note this is for the official bank address and may not be the physical branch postcode.

SearchBranchName WriteOnly String The Bank Branch to search for

SearchBankName WriteOnly String The Owner Bank Name to search for

SearchTown WriteOnly String The Town or Location of the bank to search for (note town may not be the physical branch town)

SearchPhone WriteOnly String The Phone number to search for (May be a centralised number and not the branch direct)

SearchSearchText WriteOnly String Text to match for each result, will search all fields for this data.

Function Reference

The following is a complete list of all the functions found in the afdbank 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).

ErrorText Long String Takes a negative return value of a call to the BFGetFirst, BFGetNext, BFValidateAccount, BFValidateCard, BFGetFirstRedirect or BFGetNextRedirect functions and returns a string representation of the error number. Static in C#.

CardTypeText Long String Takes a positive return value of a call to the BFValidateCard, function 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.

BFGetFirst Long Long Providing that the Lookup Property or Search properties (as appropriate) have been set this will return the first result for the specified lookup or search. Otherwise an appropriate error number (negative) will be returned.

BFGetNext - Long This returns subsequent results following a call to BFGetFirst. This should be called in a loop until the return value RETURN_END_OF_SEARCH is returned indicating the end of the search.

BFGetBankRecord - Long This returns the bank record data for the current record following a call to BFGetFirst or BFGetNext. Following this any of the bank... properties can be read.

BFGetBACSRecord - Long This returns the BACS record data for the current record following a call to BFGetFirst or BFGetNext. Following this any of the BACS... properties can be read.

BFGetCHAPSRecord - Long This returns the CHAPS record data for the current record following a call to BFGetFirst or BFGetNext. Following this any of the CHAPS... properties can be read.

BFGetCCCCRecord - Long This returns the C&CCC record data for the current record following a call to BFGetFirst or BFGetNext. Following this any of the CCCC... properties can be read.

BFGetFirstRedirect ref String Long When supplied with a sort code this replaces the parameter passed with the first sort code that is redirected to supplied sort code. The function returns 0 if successful.

BFGetNextRedirect ref String Long This is called after BFGetFirstRedirect to get subsequent redirected sort codes. When RETURN_END_OF_SEARCH all sort codes have been returned.

BFJumpToRecord Long Long This can be called with the record number of a BankFinder record to retrieve a previously searched for record (the record number can be found by checking the BankRecNo property of the class instance). It returns RETURN_SUCCESS if successful (i.e. the record number exists).

BFValidateAccount ref Long, ref String, ref String, ref Long Long This function is used to verify that an Account Number is valid and therefore can be used to help eliminate errors in capturing an account number. It takes four parameters passed by reference, the first, flags indicating if records should be returned from both clearing systems (0), UK - BACS only (1), or Irish -IPSO only (2). The others are the sortcode, account number and type of account code. The sortcode and accountNo parameters will be updated with the translated numbers for BACS processing if applicable, so you should use the values returned by the function in any subsequent processing. The TypeOfAccountCode parameter is normally zero but for some account translations will be set and is necessary for BACS submission. On return the flags parameter will be updated to (1) account is held at a branch in the UK (BACS) clearing system, (2) held at a branch in the Irish (IPSO) clearing system, (3) held at a branch in both systems.

BFValidateCard String, String Long This function is used to verify that a Debit / Credit Card Number and expiry date is valid and to determine what the card type is. The card number and expiry date are passed. It can be used to help eliminate errors in capturing debit or credit card details. The expiry date can be left blank if you do not want it to be checked. A value > 0 indicates a valid card - see Card Types under constants for a list of possible card types and corresponding values.

Property	Description
SearchLookup	Needs to be set to a blank string as will override search criteria if set
SearchSortcode	A sort code or partial sort code to search for
SearchBankBIC	The Bank BIC to search for
SearchBranchBIC	The Branch BIC to search for
SearchPostcode	A Postcode or partial postcode to search for - please note this is for the official bank address and may not be the physical branch postcode.
SearchBranchName	The Bank Branch to search for
SearchBankName	The Owner Bank Name to search for
SearchTown	The Town or Location of the bank to search for (note town may not be the physical branch town)
SearchPhone	The Phone number to search for (May be a centralised number and not the branch direct)
SearchSearchText	Text to match for each result, will search all fields for this data.

Constant	Description
Selection Flags for Lookup/Validation DLL calls:
ALL_RECORDS	Return records for both the UK (BACS) and Irish (IPSO) clearing systems.
UK_ONLY	Only return records for the UK (BACS) clearing system
IRISH_ONLY	Only return records for the Irish (IPSO) clearing system
Return Codes:
RETURN_SUCCESS	The call to BFGetFirst or BFGetNext has been successful or the Card or Account Number passed to BFValidateAccount or ValidateCard is Valid.
RETURN_VALIDATION_NOT_AVAILABLE	The account number passed to the BFValidateAccount function cannot be validated as no validation methods exists for the specified sort code. It should be assumed to be valid.
RETURN_RECORD_BREAK	The call to BFGetFirst or BFGetNext has been successful but no new result has been returned - this is simply a break to allow the user to cancel a potentially long lookup or search.
RETURN_NOT_FOUND	No Records were found matching the lookup or search criteria given or if calling BFValidateAccount the sort code supplied does not exist.
RETURN_ERROR_OPENING_FILES	BankFinder was unable to open it's data files. Please check the software is installed correctly.
RETURN_END_OF_SEARCH	This indicates that the lookup or search has completed and there are no further records to return - no new record has been returned by this call.
RETURN_DATA_LICENCE_ERROR	BankFinder was not correctly registered or has expired. Please run the Welcome program to register.
RETURN_NO_SEARCH_DATA	No lookup or search data was specified, i.e. the Lookup property was not set or the Search criteria was all blank.
RETURN_INVALID_SORT_CODE	The sort code passed to the BFValidateAccount function is not in a valid format or is too long/short to be a sort code (it should be in the format XXXXX, XX-XX-XX, or XX XX XX, where X is a digit)
RETURN_INVALID_ACCOUNT_NUMBER	The account number passed to the BFValidateAccount function is not a valid account number for that branch.
RETURN_INVALID_EXPIRY	The expiry date passed to the BFValidateCard function is invalid, it should be in the format MM/YY.
RETURN_CARD_EXPIRED	The expiry date passed to the BFValidateCard function is in the past or too far ahead in the future to be from a presently valid card.
RETURN_INVALID_CARD_NUMBER	The card number passed to the BFValidateCard function is not valid.
RETURN_VISA_ATM_ONLY	The card number passed to the BFValidateCard function is a valid Visa Card but it is valid for ATM use only which means it cannot be used for electronic payment.
RETURN_UNRECOGNISED_CARD	The card number passed to the BFValidateCard function is theoretically valid but it is not one of the recognised types (Mastercard, Visa, American Express, Switch, Visa Delta, Visa UK Electron, Visa Purchasing, Maestro, Solo or JCB). Therefore it should be treated as invalid.
Account Number Return Flags
UK_ACCOUNT	The account resides at a branch which is part of the UK (BACS) clearing system.
IRISH_ACCOUNT	The account resides at a branch which is part of the Irish (IPSO) clearing system.
DUAL_ACCOUNT	The account resides at a branch which is part of both the UK (BACS) and Irish (IPSO) clearing systems.
Card Types: - These are possible return values of the ValidateCard function
CARD_TYPE_MASTERCARD	The card number passed is valid for Mastercard
CARD_TYPE_VISA	The card number passed is valid for Visa
CARD_TYPE_AMERICAN_EXPRESS	The card number passed is valid for American Express
CARD_TYPE_SWITCH	The card number passed is valid for Switch
CARD_TYPE_VISA_DELTA	The card number passed is valid for Visa Delta
CARD_TYPE_VISA_UK_ELECTRON	The card number passed is valid for Visa Electron
CARD_TYPE_VISA_PURCHASING	The card number passed is valid for Visa Purchasing
CARD_TYPE_SWITCH_AND_MAESTRO	The card number passed is valid for Switch and Maestro
CARD_TYPE_MAESTRO	The card number passed is valid for Maestro
CARD_TYPE_SOLO_AND_MAESTRO	The card number passed is valid for Solo and Maestro
CARD_TYPE_JCB	The card number passed is valid for JCB

Property	Type	Description
BankRecNo	ReadOnly Long	Specifies the record number for the returned record. Useful for storing to retrieve the same record later by calling BFJumpToRecord with this record number as a parameter.
BankSortcode	ReadOnly String	The sortcode
BankBankBIC	ReadOnly String	The Bank BIC code (Does not apply to IPSO records)
BankBranchBIC	ReadOnly String	The Branch BIC code (Does not apply to IPSO records)
BankSubBranchSuffix	ReadOnly String	The sub-branch suffix which allows a branch to be uniquely identified where there is a cluster of branches sharing the same Sort Code (Does not apply to IPSO records)
BankShortBranchTitle	ReadOnly String	The official title of the branch
BankCentralCountryCode	ReadOnly String	The ISO Country code for beneficiary banks in other countries
BankSupervisoryBody	ReadOnly String	Indicates the supervisory body for an institution that is an agency in any of the clearings. This will be A - Bank Of England, B - Building Society Commission, C - Jersey, Guernsey or Isle of Man authorities or D - Other.
BankDeletedDate	ReadOnly String	Specifies the date the branch was closed if it is not active
BankBranchTypeIndicator	ReadOnly String	Shows the branch type (M - Main Branch, S - Sub or NAB Branch, or L - Linked Branch)
BankMainBranchSortcode	ReadOnly String	Set for linked branches in a cluster. It identifies the main branch for the cluster.
BankMajorLocationName	ReadOnly String	Optional field used to indent the Branch name or place in the printed directory (Does not apply to IPSO records where the branch name is normally also the location).
BankMinorLocationName	ReadOnly String	Optional field also used to indent the Branch name or place in the printed directory (Does not apply to IPSO records)
BankBranchName	ReadOnly String	Defines the actual name or place of the branch
BankBranchName2	ReadOnly String	Where applicable contains an alternative name or place for the branch
BankFullBranchTitle	ReadOnly String	Extended title for the institution (BankShortBranchTitle is the official one)
BankOwnerBankShortName	ReadOnly String	The short version of the name of the Owning Bank
BankOwnerBankFullName	ReadOnly String	The full version of the name of the Owning Bank
BankOwnerBankCode	ReadOnly String	The four digit bank code of the Owning Bank (Does not apply to IPSO records).
BankProperty	ReadOnly String	Property for the postal address (may not be the same as the physical branch address)
BankStreet	ReadOnly String	Street for the postal address (may not be the same as the physical branch address)
BankLocality	ReadOnly String	Locality for the postal address (may not be the same as the physical branch address)
BankTown	ReadOnly String	Town for the postal address (may not be the same as the physical branch address)
BankCounty	ReadOnly String	County for the postal address (may not be the same as the physical branch address)
BankPostcode	ReadOnly String	Postcode for the postal address (may not be the same as the physical branch address)
BankStdCode	ReadOnly String	STD Code for contacting the branch (may not be a direct number for the branch itself).
BankPhone	ReadOnly String	Phone Number for contacting the branch (may not be a direct number for the branch itself).
BankFaxStdCode	ReadOnly String	STD Code for sending faxes to the branch (Only applies to IPSO records)
BankFax	ReadOnly String	Fax Number for the branch (Only applies to IPSO records)
CountryIndicator	ReadOnly String	Set to 'U' if the record is on the BACS clearing system, or 'I' if it is on the IPSO clearing system. Branches on both will have an entry for each clearing system.

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).
ErrorText	Long	String	Takes a negative return value of a call to the BFGetFirst, BFGetNext, BFValidateAccount, BFValidateCard, BFGetFirstRedirect or BFGetNextRedirect functions and returns a string representation of the error number. Static in C#.
CardTypeText	Long	String	Takes a positive return value of a call to the BFValidateCard, function 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.
BFGetFirst	Long	Long	Providing that the Lookup Property or Search properties (as appropriate) have been set this will return the first result for the specified lookup or search. Otherwise an appropriate error number (negative) will be returned.
BFGetNext	-	Long	This returns subsequent results following a call to BFGetFirst. This should be called in a loop until the return value RETURN_END_OF_SEARCH is returned indicating the end of the search.
BFGetBankRecord	-	Long	This returns the bank record data for the current record following a call to BFGetFirst or BFGetNext. Following this any of the bank... properties can be read.
BFGetBACSRecord	-	Long	This returns the BACS record data for the current record following a call to BFGetFirst or BFGetNext. Following this any of the BACS... properties can be read.
BFGetCHAPSRecord	-	Long	This returns the CHAPS record data for the current record following a call to BFGetFirst or BFGetNext. Following this any of the CHAPS... properties can be read.
BFGetCCCCRecord	-	Long	This returns the C&CCC record data for the current record following a call to BFGetFirst or BFGetNext. Following this any of the CCCC... properties can be read.
BFGetFirstRedirect	ref String	Long	When supplied with a sort code this replaces the parameter passed with the first sort code that is redirected to supplied sort code. The function returns 0 if successful.
BFGetNextRedirect	ref String	Long	This is called after BFGetFirstRedirect to get subsequent redirected sort codes. When RETURN_END_OF_SEARCH all sort codes have been returned.
BFJumpToRecord	Long	Long	This can be called with the record number of a BankFinder record to retrieve a previously searched for record (the record number can be found by checking the BankRecNo property of the class instance). It returns RETURN_SUCCESS if successful (i.e. the record number exists).
BFValidateAccount	ref Long, ref String, ref String, ref Long	Long	This function is used to verify that an Account Number is valid and therefore can be used to help eliminate errors in capturing an account number. It takes four parameters passed by reference, the first, flags indicating if records should be returned from both clearing systems (0), UK - BACS only (1), or Irish -IPSO only (2). The others are the sortcode, account number and type of account code. The sortcode and accountNo parameters will be updated with the translated numbers for BACS processing if applicable, so you should use the values returned by the function in any subsequent processing. The TypeOfAccountCode parameter is normally zero but for some account translations will be set and is necessary for BACS submission. On return the flags parameter will be updated to (1) account is held at a branch in the UK (BACS) clearing system, (2) held at a branch in the Irish (IPSO) clearing system, (3) held at a branch in both systems.
BFValidateCard	String, String	Long	This function is used to verify that a Debit / Credit Card Number and expiry date is valid and to determine what the card type is. The card number and expiry date are passed. It can be used to help eliminate errors in capturing debit or credit card details. The expiry date can be left blank if you do not want it to be checked. A value > 0 indicates a valid card - see Card Types under constants for a list of possible card types and corresponding values.

Address, Postcode and Bank solutions