vim:set tw=70; set ft=text; set ai

########################################################################
# PRFZIFFERBERECHNUNG VON DEUTSCHEN UND STERREICHISCHEN KONTONUMMERN #
#                        C-/Perl-Bibliothek                            #
########################################################################
#                                                                      #
# Autor             : Michael Plugge <m.plugge@hs-mannheim.de>         #
# Version           : 2.4 (stabil)                                     #
# Datum             : 13.11.2007                                       #
#                                                                      #
########################################################################

1. Einfhrung
=============

Das Modul Business::KontoCheck besteht aus zwei C-Bibliotheken, die
an sich relativ selbstndig sind, aber auch gemeinsam verwendet werden knnen.
Die Bibliotheken berechnen anhand von Bankleitzahl und Prfziffermethode, ob
eine angegebene Kontonummer plausibel ist. Es kann natrlich nicht ausgesagt
werden, ob eine etsprechende Kontonummer wirklich existiert; allerdings knnen
Fehler bei der bermittlung auf diese Weise oft entdeckt werden und ersparen
so kostspielige Rckbuchungen.

Diese Datei bezieht sich vor allem auf die Perlversion der Bibliothek; in der
C-Version gibt es kleine Unterschiede, besonders in der Paketliste und
Installation. Die eigentliche Funktionalitt ist in beiden Versionen natrlich
identisch.


2. Paketliste von Business::KontoCheck (Perl-Bibliothek)
========================================================

0_history.txt               : Versionsgeschichte
00liesmich.txt              : diese Datei
Changes                     : Versionsgeschichte/Perl
README                      : kurzes README fr CPAN
MANIFEST                    : Dateiliste (von Perl bentigt)
blz.lut                     : LUT-Datei fr die deutsche Version
blz-at.lut                  : LUT-Datei fr die sterreichische Version
konto_check.h               : C Header-Datei fr die deutsche Version
konto_check-at.h            : C Header-Datei fr die sterreichische Version
konto_check.c               : C Quellcode fr die deutsche Version
konto_check-at.c            : C Quellcode fr die sterreichische Version
inpar.dat                   : Testdatei fr das INPAR Datenformat (s.u.)
test.pl                     : kleine Beispielsdatei
KontoCheck.xs               : XSUB-Datei mit C/Perl glue code
lib/Business/KontoCheck.pm  : Perl Interface und Dokumentation
t/Business-KontoCheck.t     : Testdatei fr make test
Makefile.PL                 : Perl Makefile
META.yml                    : (von Perl bentigt)
ppport.h                    : (von Perl bentigt)


3. Installation
===============

Die Bibiliothek wird mit den blichen Kommandos installiert:

   perl makefile.PL
   make
   make test
   make install

(das letzte Kommando mu mit root-Rechten ausgefhrt werden). Danach kann die
Bibliothek mittels "use Business::KontoCheck" eingebunden und verwendet werden.


4. Benutzung
===============

Eine kurze Beschreibung der exportierten Funktionen gibt es in der Datei
lib/Business/KontoCheck.pm. Die Beschreibung wird bei der Installation auch
ins Hilfesystem von Perl integriert, so da die Syntax und Parameter der
einzelnen Funktionen mittels "perldoc Business::KontoCheck" nachgelesen werden
kann.


5. Prfparameter
================

5.1 Deutsche Banken
-------------------

Die aktuelle Bankleitzahltabelle wird verffentlicht von der Deutschen
Bundesbank:

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

Dabei ist die Datei blz_*.zip herunterzuladen und auszupacken (aktuell z.B.
blz_20070604.zip). Die Aktualisierung erfolgt alle 3 Monate. Diese Datei kann
mittels der Funktion generate_lut() in das LUT-Format fr die Bibliothek
konvertiert werden.

Die aktuellen Prfziffermethoden werden ebenfalls von der Deutschen Bundesbank
verffentlicht:

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

Allgemeine Informationen und Links gibt es vom Bundesverband deutscher Banken
unter http://www.bdb.de/verband/Intern.htm


5.2 sterreichische Banken 
--------------------------

Die aktuellen Prfparameter sind nicht frei verfgbar; sie knnen von der
Firma First Data Austria, Wien (http://www.firstdata.at) kuflich bezogen
werden. Das Handbuch zu INPAR (mit der Spezifikation des Dateiformats) ist auf
Anfrage ebenfalls von First Data Austria erhltlich. Interessenten wenden sich
bitte an Andreas.Krickl@firstdata.at. Die Spezifikation findet sich auch unter

http://www.firstdata.at/de/service/downloads.htm

im Abschnitt "Downloads INPAR" -> "Handbuch PDF" (aktuell (11.9.06) ist die
Version 2.1).

Diesem Paket liegt eine Datei inpar.dat bei; sie dient als Referenz fr das
Dateiformat der INPAR-Daten. Die Datei ist ebenfalls unter der oben angegebenen
Adresse verfgbar (als "Testdatei ZIP"). Die Liste ist weder vollstndig noch
aktuell. Sie enthlt nur die Daten von 32 Banken, und auch die Prfparameter
haben sich teilweise gendert


6. BEKANNTE FEHLER
================== 

Momentan sind keine Fehler in den Prfziffermethoden bekannt. Falls Sie einen
Fehler finden, wrde ich mich sehr freuen, davon zu hren ;-))).

Die Bibliothek ist momentan nicht threadfest, da einige globale Variablen
benutzt werden; die nchsten Version wird eine threadfeste Variante enthalten
(der kleine Geschwindigkeitsvorteil macht die Nachteile nicht wett).

Die Funktionen generate_lut() und generate_lut_at() sollte nicht von einem
Programm aufgerufen werden, das zum Testen von Kontoverbindungen benutzt wird,
da teilweise dieselben Variablen benutzt werden, und so falsche Ergebnisse
erzeugt werden knnen. Stattdessen sind diese Funktionen offline aufzurufen.

Momentan gibt es fr langlaufende Serveranwendungen noch keine elegante
Methode, eine neue LUT-Datei zu aktivieren; das wird auch im Zusammenhang mit
der Threadfestigkeit in Angriff genommen werden. Es wre mglich dafr die
Funktion cleanup_kto() zu benutzen; diese enthlt allerdings keine locking
Funktionalitt, um einen Zugriff von anderen Threads zu verhindern; daher
wurde die Funktion nicht exportiert. Momentan scheint der beste Weg zu sein,
den entsprechenden Server neu zu starten :-( - nicht schn, aber sauber.


Die Arbeit an der neuen Version (3.0) ist schon ziemlig weit; da aber zum
Dezember eine neue Prfmethode Gltigkeit bekommt, wurde noch eine Version der
2.x Reihe herausgegeben. Die Version 3.0.Beta-1 drfte bis Ende November/Anfang
Dezember fertig werden. In der Version sind die LUT2 Routinen integriert,
etliche Altlasten beseitigt, und alle globalen R/W Variablen entfernt;
die Prfziffertabelle kann durch eine neue Version ersetzt werden; auerdem
lassen sich zu einer gegebenen Bankleitzahl alle Felder der Bundesbankdatei
bestimmen. Die Daten werden komprimiert gespeichert; die vollstndige Datei ist
256KB gro, eine Datei mit Bankleitzahl, Bankname, PLZ, Ort und Prfziffer der
Hauptstellen bentigt 53KB.

Es ist auerdem geplant, da man auch zwei Versionen der Bankleitzahlendatei
in derselben LUT-Datei unterbringen kann; das vereinfacht die Umstellung der
LUT-Datei am Aktualisierungsdatum (kann automatisch erfolgen). 


7. Technische Informationen 
============================

7.1. Deutsches Modul
--------------------

Die Bankleitzahl ist immer 8-stellig.

Die Lnge der Kontonummer ist variabel und wird auf 10 Stellen gesetzt,
indem fhrenden Nullen ergnzt werden.

Die Datei testkonten.txt ist eine Testdatei mit knapp 600 Kontonummern
und Bankleitzahlen Einige sind reale Kontonummern, andere sind Testkonten,
die von der Deutschen Bundesbank zur Verfgung gestellt werden.

Feld 1	-> Bankleitzahl oder Prfziffer
Feld 2	-> Kontonummer.

Die Bibliothek wurde mit allen Testkontonummern  der Dokumentation der
Prfziffernberechnungmethoden der Deutschen Bundesbank (Stand Mai 2007)
erfolgreich getestet. Auerdem wurden etliche Millionen Testkontonummern (fr
jede Methode bzw. Teilmethode ca. 50000...100000) mit dem Modul konto122.pl
von Andreas Butzko und anderen Programmen verglichen.


7.2. sterreichisches Modul
---------------------------

Die Bankleitzahl ist immer 5-stellig.

Die Lnge der Kontonummer ist variabel und wird auf 11 Stellen gesetzt,
indem fhrenden Nullen ergnzt werden.

In der INPAR-Datei sind einige Banken als gelscht angegeben, jedoch sind die
jeweiligen Testparameter angegeben. In diesem Fall besteht die Mglichkeit,
die Bankleitzahl mit einem vorgestellten - zu versehen; das Konto wird dann
getestet, und ein entsprechender Wert zurckgegeben (ob es sinnvoll ist, ist
fraglich; es war allerdings auch kein Aufwand ;-) ). Auerdem lassen sich mit
einem vorangestellten p direkt die Prfparameter eingeben. Einige Beispiele
dazu finden sich in der Datei testkonten-at.txt.

Fr die sterreichische Version gab es leider keine Vergleichsprogramme;
allerdings sind die Prfmethoden des sterreichischen Moduls nicht so
divergent wie die der deutschen Version. In der C Bibliothek gibt es noch eine
Trace-Version, die alle Berechnungen genau protokolliert und so eine
Fehlersuche ermglicht. Zum Test wurden (neben der Trace-Version) einige
hundert Kontonummern aus dem Internet benutzt.


8. COPYRIGHT
============

Copyright (C) 2002-2007 Michael Plugge.

Diese Bibliothek ist freie Software; Sie drfen sie unter den Bedingungen der GNU
Lesser General Public License, wie von der Free Software Foundation
verffentlicht, weiterverteilen und/oder modifizieren; entweder gem Version
2.1 der Lizenz oder (nach Ihrer Option) jeder spteren Version.

Die GNU LGPL ist weniger infektis als die normale GPL; Code, der von Ihnen
hinzugefgt wird, unterliegt nicht der Offenlegungspflicht (wie bei der
normalen GPL); auerdem mssen Programme, die diese Bibliothek benutzen, nicht
(L)GPL lizensiert sein, sondern knnen beliebig kommerziell verwertet werden.
Die Offenlegung des Sourcecodes bezieht sich bei der LGPL *nur* auf genderten
Bibliothekscode.

Diese Bibliothek wird in der Hoffnung weiterverbreitet, da sie ntzlich sein
wird, jedoch OHNE IRGENDEINE GARANTIE, auch ohne die implizierte Garantie der
MARKTREIFE oder der VERWENDBARKEIT FR EINEN BESTIMMTEN ZWECK. Mehr Details
finden Sie in der GNU Lesser General Public License.

Sie sollten eine Kopie der GNU Lesser General Public License zusammen mit
dieser Bibliothek erhalten haben; falls nicht, knnen Sie sie von
http://www.gnu.org/licenses/lgpl.html im Internet herunterladen.
