KtoBLZCheck is a library to check account numbers and bank codes of
German banks.

Naming explanation: This library provides a check for "kto" (German
abbreviation for account number) and "blz" (German abbreviation for
bank identification code, A.B.A. code or similar).

Introduction
------------

Both a library for other programs as well as a short command-line tool
is available. It is possible to check pairs of account numbers and
bank codes (BLZ) of German banks, and to map bank codes (BLZ) to the
clear-text name and location of the bank. Python bindings are provided
as well (--enable-python; requires the python module "ctypes").

For compile instructions concerning MS Windows, please see the file
README.WIN32. On the download page a self-installing setup file for
Windows compiled with MinGW/gcc3.2 can be found.


Compile & Install
-----------------

How to compile:

If you got this package from SVN, then type "./autogen.sh" to create
the necessary build tools. Then:

Type 

  ./configure

to calculate some system dependencies. See "./configure --help" for
possible options. Usually you might want to write something like
"./configure --prefix=/your/prefix
--with-bankdata-path=/your/favorite/directory", which installs
KtoBLZCheck under the given prefix and its bank data files (yes, there
are several, see below) at the specified path. The default bank data
path is $prefix/share/ktoblzcheck where the default for $prefix is
/usr/local. 

Now type 

  make
  make install

and you're done.


Running
-------

And then give it a try:

"ktoblzcheck <your-bank-id> <your-account-id>"

Some example BLZ;Account-ids are the following from Bundesbank:
64192220;12345008
20210200;0240334000
56061472;0000191919

The ktoblzcheck command has several optional arguments; use "--help"
to see a summary. The argument --outformat by default is
"multiline". The other choice, "--outformat=oneline", gives you one
line of result with the following tab-delimited fields: "bank name,
bank city, result of check, BLZ, accountId, name of the checking
algorithm"


Bank List Format
----------------

A file with all bank codes (BLZ Datei) can regularly be retrieved from
the Deutsche Bundesbank at bundesbank.de, more specifically from

http://www.bundesbank.de/zahlungsverkehr/zahlungsverkehr_bankleitzahlen_download.php

Since version 1.16, ktoblzcheck installs multiple bankdata files which
are valid at different dates. Each of the bank code files from the
Deutsche Bundesbank is valid for three (3) months.  Ktoblzcheck ships
with the bankdata file from several validity periods: One file is
valid at the date of release; the second file is valid in the three
months after that (i.e. it is newer); and the file from the previous
period (i.e. the old one) is added as well. If even the newest file is
outdated at the day of when libktoblzcheck is used, a warning line
will be printed to stderr and the newest file will be used anyway.

Note: The available files (marked by the first valid day as part of
the filename) and their validity period are hard-coded into
libktoblzcheck.so, src/lib/ktoblzcheck.cc to be more specific.
Updating the files doesn't change that information. So even if you
replace the file with the newest date with an updated file (which is
now up to date again), the warning will still appear because the
hard-coded validity dates inside libktoblzcheck haven't been updated
as well.

Note 2nd: The bank data file "bankdata.txt" with no date in the file
name is not used anymore by default. It is a one-to-one copy of the
file with the newest date, and it is provided solely for backward
compatibility.

Note 3rd: All of the above is ignored if a bankdata file is explicitly
requested by the command line argument --file=... . In that case
the specified file is used and no further date comparisons are made.

Since version 1.3, ktoblzcheck includes a script for automated
download of a new bankdata file in
/usr/share/ktoblzcheck/online_update.pl . Simply run this script with
no arguments. It will first download the information HTML page by
bundesbank and parse this page for BLZ updates. Then, the user will be
asked whether one particular available file should be downloaded. If
the user agrees, the file is downloaded, copied into the correct
BANKDATA_PATH, and converted into ktoblzcheck's format.

However, WATCH OUT: The downloaded file will NOT be used by
libktoblzcheck unless the path to the downloaded file is explicitly
requested by the --file=... command line argument.

The bankdata.txt file used by ktoblzcheck contains less information
than the file provided by the Bundesbank. Namely, it contains only
four tab-delimited columns and only those lines that refer to the main
institutes instead of all branches. The provided sed script
src/bankdata/bundesbank.sed (provided by Daniel Gloeckner
<daniel-gl@gmx.net>) will automatically convert the Bundesbank's ascii
file into the required ktoblzcheck format.

If you got the Bundesbank BLZ file in excel format, the four columns
for bankdata.txt are A, O, G, J, in that order, and it has only those
lines which have a '1' in column B.


Authors
-------

The original author was Fabian Kaiser <fabian@openhbci.de>. The
current maintainer is Christian Stimming <stimming@tuhh.de>.  

For contacting the authors, please write to the mailing list
<aqbanking-general@sourceforge.net>. This list is subscriber-only which
means you need to subscribe if you want to post to the
list. Subscription information can be found on
http://lists.sourceforge.net/lists/listinfo/aqbanking-general


Related projects
----------------

A ruby interface to ktoblzcheck:
http://www.vdp-software.com/Rbktoblzcheck/

A different implementation of this checking algorithms:
http://www.informatik.fh-mannheim.de/konto_check/



PS: Benchmark Notes
-------------------

Some benchmark notes:

Each time tried 10000 BLZs with random first 2 digits so that 66% of
the banks are found, see src/bin/benchmark.cc. All results in seconds
on my 1.3 GHz Duron, compiled with no optimization. Time check simply
by calling "time ./benchmark 10000".

With list<Record*> and manual finding with for(...) loop:  5.3s
With list<Record*> and find_if() from <algorithm>:         4.2s
With vector<Record*> and find_if():                        1.6s 
(the above at a later test: 3.5s)
With hash_map<...> and hash_map::find:                     0.2s (!!)

Gee. This is kind of obvious :-)

Actually, some time later I tested 100000 BLZs between std::map<> and 
__gnu_cxx::hash_map. Results:
__gnu_cxx::hash_hash<...>:                   0.89s
std::map<...>:                               0.91s

Well, it seems that stdc++'s implementation of std::map probably uses
a hash map internally. That, and together with the thought that a
header file dependency on a configuration variable is probably a bad
idea, lead to the decision to throw out <ext/hash_map> completely and
only use std::map<>.

