NAME
Business::KontoCheck - Perl extension for checking German and Austrian Bank Account Numbers
NOTE
Because the module is for use mainly in Germany, the following documentation language is german too.
SYNOPSIS
use Business::KontoCheck;
use Business::KontoCheck qw( kto_check lut_name lut_blz lut_ort %kto_retval [...] );
$retval=lut_init([$lut_name[,$required[,$set]]);
$retval=kto_check_init($lut_name[,$required[,$set[,$incremental]]]);
$retval=kto_check($blz,$kto,$lut_name);
$retval=kto_check_str($blz,$kto,$lut_name);
$retval=kto_check_blz($blz,$kto)
$retval=kto_check_pz($pz,$blz,$kto)
$retval=generate_lut($inputname,$outputname,$user_info,$lut_version);
$retval=generate_lut2($inputname,$outputname[,$user_info[,$gueltigkeit[,$felder[,$filialen[,$slots[,$lut_version[,$set]]]]]]]);
$retval=lut_valid()
[$@]retval=lut_info($lut_name)
[$@]retval=lut_filialen($blz[,$offset])
[$@]retval=lut_name($blz[,$offset])
[$@]retval=lut_name_kurz($blz[,$offset])
[$@]retval=lut_plz($blz[,$offset])
[$@]retval=lut_ort($blz[,$offset])
[$@]retval=lut_pan($blz[,$offset])
[$@]retval=lut_bic($blz[,$offset])
[$@]retval=lut_pz($blz[,$offset])
[$@]retval=lut_aenderung($blz[,$offset])
[$@]retval=lut_loeschung($blz[,$offset])
[$@]retval=lut_nachfolge_blz($blz[,$offset])
[$@]bic=lut_suche_bic($bic[,$retval[,$zweigstelle[,$blz]]])
[$@]namen=lut_suche_namen($namen[,$retval[,$zweigstelle[,$blz]]])
[$@]namen_kurz=lut_suche_namen_kurz($namen_kurz[,$retval[,$zweigstelle[,$blz]]])
[$@]ort=lut_suche_ort($ort[,$retval[,$zweigstelle[,$blz]]])
[$@]blz=lut_suche_blz($blz1[,$blz2[,$retval[,$zweigstelle[,$blz]]]])
[$@]pz=lut_suche_pz($pz1[,$pz2[,$retval[,$zweigstelle[,$blz]]]])
[$@]plz=lut_suche_plz($plz1[,$plz2[,$retval[,$zweigstelle[,$blz]]]])
$retval=copy_lutfile($old_name,$new_name,$new_slots)
$retval=dump_lutfile($outputname,$felder)
$retval=lut_cleanup()
$retval=iban_check(iban)
$retval=iban2bic(iban)
$retval=iban_gen(blz,kto)
$retval=retval2txt($retval)
$retval=retval2txt_short($retval)
$retval=retval2html($retval)
$retval=retval2utf8($retval)
$retval=retval2dos($retval)
$retval_txt=$kto_retval{$retval};
$retval=kto_check_at($blz,$kto,$lut_name);
$retval=kto_check_at_str($blz,$kto,$lut_name);
$retval=generate_lut_at($inputname,$outputname,$plain_name,$plain_format);DESCRIPTION
Dies ist Business::KontoCheck, ein Programm zum Testen der Prüfziffern von deutschen und österreichischen Bankkonten. Es war ursprünglich für die Benutzung mit dem dtaus-Paket von Martin Schulze <joey@infodrom.org> und dem lx2l Präprozessor gedacht; es läßt sich jedoch auch mit beliebigen anderen Programmen verwenden. Dies ist die Perl-Version der C-Library (als XSUB Modul).
EXPORT
Es werden defaultmäßig die Funkionen kto_check und kto_check_str, (aus dem deutschen Modul), kto_check_at, kto_check_at_str (aus dem österreichischen Modul) sowie die Variable %kto_retval (für beide Module) exportiert.
Optional können auch eine Reihe weiterer Funktionen exportiert werden; diese müssen dann in der use Klausel anzugeben werden.
DESCRIPTION
Funktion: kto_check()
kto_check_str()
Aufgabe: Testen eines Kontos
Aufruf: $retval=kto_check($blz,$kto,$lut_name);
$retval=kto_check_str($blz,$kto,$lut_name);
Parameter:
$blz: falls 2- oder 3-stellig: Prüfziffermethode
(evl. mit Untermethode a, b, c... oder 1, 2, 3)
falls 8-stellig: Bankleitzahl
$kto: Kontonummer (wird vor der Berechnung
linksbündig mit Nullen auf 10 Stellen
aufgefüllt)
$lut_name: Dateiname der Lookup-Tabelle mit Bankleitzahlen.
Falls NULL oder ein leerer String übergeben wird,
wird der Dateiname blz.lut benutzt.
Diese Datei enthält die Prüfziffermethoden für die
einzelnen Bankleitzahlen; sie kann mit der Funktion
generate_lut() aus der Bundesbanktabelle generiert
werden.
Rückgabewerte:
Die Funktion kto_check gibt einen numerischen Wert zurück, während die
Funktion kto_check_str einen kurzen String zurückgibt.
Werte sind definiert3
Mittels des assoziativen Arrays %kto_retval lassen sich die numerischen
und kurzen Rückgabewerte in einen etwas ausführlicheren Rückgabetext
umwandeln:
$retval_txt=$kto_retval{$retval};-------------------------------------------------------------------------
Funktion: generate_lut() (LUT-Version 1.0 oder 1.1)
generate_lut2() (LUT-Version 1.0, 1.1 oder 2.0)
Aufgabe: LUT-Datei generieren
Aufruf: $retval=generate_lut($inputname,$outputname,$user_info,$lut_version);
$retval=generate_lut2($inputname,$outputname[,$user_info[,$gueltigkeit
[,$felder[,$filialen[,$slots[,$lut_version[,$set]]]]]]]);
Parameter:
inputname: Name der Bankleitzahlendatei der Deutschen
Bundesbank (z.B. blz0303pc.txt)
outputname: Name der Zieldatei (z.B. blz.lut)
user_info: Info-Zeile, die zusätzlich in die LUT-Datei
geschrieben wird. Diese Zeile wird von der
Funktion get_lut_info() in zurückgegeben,
aber ansonsten nicht ausgewertet.
lut_version: Format der LUT-Datei. Mögliche Werte:
1: altes Format (1.0)
2: altes Format (1.1) mit Infozeile
3: (nur für generate_lut2()) neues Format (2.0)
Die folgenden Parameter gelten nur für generate_lut2():
gueltigkeit: Gültigkeitsbereich der LUT-Datei, im Format
JJJJMMTT-JJJJMMTT, z.B. 20071203-20080302
felder: (Integer, 0-9) Felder, die in die LUT-Datei
aufgenommen werden sollen.
filialen: Flag (0 oder 1), ob die Filialdaten ebenfalls
aufgenommen werden sollen.
slots: Anzahl Slots (mögliche Verzeichniseinträge) der LUT-Datei
set: (Integer, 0, 1 oder 2) Angabe, ob das primäre Set (0
bzw. 1) oder sekundäre Datensatz (2) geschrieben
werden soll. Falls für set 0 angegeben wird, wird
eine neue Datei angelegt, bei 1 und 2 wird der
Datensatz an eine vorhandene LUT-Datei angehängt.
Das setzt natürlich voraus, daß noch genügend
Verzeichnisslots vorhanden sind, um alle Blocks
schreiben zu können. Bei Bedarf kann mittels
copy_lutfile() die Anzahl der Verzeichnisslots auch
erhöht werden.-------------------------------------------------------------------------
Funktion: lut_filialen()
lut_name()
lut_name_kurz()
lut_plz()
lut_ort()
lut_pan()
lut_bic()
lut_pz()
lut_aenderung()
lut_loeschung()
lut_nachfolge_blz()
Aufgabe: Bestimmung von Feldern der BLZ-Datei
Aufruf: [$@]ret=lut_name($blz[,$filiale])
[$@]ret=lut_name_kurz($blz[,$filiale])
[$@]ret=lut_plz($blz[,$filiale])
[$@]ret=lut_ort($blz[,$filiale])
[$@]ret=lut_pan($blz[,$filiale])
[$@]ret=lut_bic($blz[,$filiale])
[$@]ret=lut_pz($blz[,$filiale])
[$@]ret=lut_aenderung($blz[,$filiale])
[$@]ret=lut_loeschung($blz[,$filiale])
[$@]ret=lut_nachfolge_blz($blz[,$filiale])
Die Funktionen bestimmen die diversen Felder der BLZ-Datei zu einer
gegebenen BLZ. Falls der optionale Parameter $filiale angegeben
wird, wird der Wert für eine Filiale bestimmt, ansonsten (und bei
$filiale==0) der Wert der Hauptstelle. Die Anzahl der Filialen zu
einer BLZ läßt sich mittels der Funktion $cnt=lut_filialen($blz)
bestimmen.
Alle Funktionen lassen sich sowohl im skalaren als auch im Array-
Kontext aufrufen. Bei Aufruf in skalarem Kontext wird der jeweilige
Wert zurückgegeben; bei Aufruf im Array-Kontext wird außerdem noch
der Rückgabestatus der Funktion als Zahl, String (lang) und String
(kurz) zurückgegeben. Beispiel:
$ret=lut_name("66090800") liefert für $ret den Wert "BBBank",
@ret=lut_name("66090800") liefert ein Array mit den Werten
@ret=("BBBank",1,"ok","OK")
der Aufruf
@ret=lut_name("660908") liefert ein Array mit den Werten
@ret=("",-5,"die Bankleitzahl ist nicht achtstellig","INVALID_BLZ_LENGTH")-------------------------------------------------------------------------
Funktion: lut_suche_bic()
lut_suche_namen()
lut_suche_namen_kurz()
lut_suche_ort()
lut_suche_blz()
lut_suche_pz()
lut_suche_plz()
Aufgabe: Suche von Banken (nach Feldern der BLZ-Datei)
Aufruf: [$@]ret=lut_suche_bic($bic[,$retval[,$zweigstelle[,$blz]]])
[$@]ret=lut_suche_namen($namen[,$retval[,$zweigstelle[,$blz]]])
[$@]ret=lut_suche_namen_kurz($namen_kurz[,$retval[,$zweigstelle[,$blz]]])
[$@]ret=lut_suche_ort($ort[,$retval[,$zweigstelle[,$blz]]])
[$@]ret=lut_suche_blz($blz1[,$blz2[,$retval[,$zweigstelle[,$blz]]]])
[$@]ret=lut_suche_pz($pz1[,$pz2[,$retval[,$zweigstelle[,$blz]]]])
[$@]ret=lut_suche_plz($plz1[,$plz2[,$retval[,$zweigstelle[,$blz]]]])
Mit diesen Funktionen lassen sich Banken suchen, die bestimmte Kriterien
erfüllen. Bei alphanumerischer Suche (BIC, Name, Kurzname, Ort) kann ein
vollständiger Name oder Namensanfang angegeben werden. So findet z.B. eine
Suche lut_suche_ort("aa") die Banken in in Aach, Aachen, Aalen und Aarbergen,
während eine Suche wie lut_suche_ort("aac") nur die Banken in Aach und Aachen
findet.
Bei numerischer Suche (BLZ, Prüfziffer oder PLZ) kann ein Bereich
spezifiziert werden. Falls der zweite Suchparameter nicht angegeben wird
(oder 0 ist), werden Banken gesucht, die genau auf den Parameter passen.
Diese Funktionen können sowohl in skalarem als auch im Listenkontext
aufgerufen werden. Bei Aufruf in skalarem Kontext geben sie die Anzahl Banken
zurück, die die spezifizierte Bedingung erfüllen; bei Aufruf in Listenkontext
wird ein Array zurückgegeben, das die jeweils gesuchten Felder enthält.
Die Funktionen haben eine Reihe optionaler Parameter:
$retval: numerischer Rückgabewert der Funktion (1 bei Erfolg, oder
negative Statusmeldung). Mittels des assoziativen Arrays
%kto_retval{$retval} können diese Rückgabewerte in Klartext
konvertiert werden.
$zweigstelle: Referenz auf ein Array, in dem zu jeder Bank der Index der
jeweiligen Zweigstelle enthalten ist; die Hauptstelle wird
mit 0 gekennzeichnet.
$blz: Referenz auf ein Array, das die Bankleitzahen der
gefundenen Banken enthält.-------------------------------------------------------------------------
Funktion: kto_check_at()
kto_check_at_str()
Aufgabe: Testen eines österreichischen Kontos
Aufruf: $retval=kto_check_at($blz,$kto,$lut_name);
$retval=kto_check_at_str($blz,$kto,$lut_name);
Parameter:
$blz: BLZ (5-stellig) oder Prüfparameter (mit vorangestelltem p)
Falls der BLZ ein - vorausgestellt wird, werden auch gelöschte
Bankleitzahlen geprüft.
Falls der BLZ ein p vorausgestellt wird, wird der folgende
Teil (bis zum Blank/Tab) als Prüfparameter angesehen.
$kto: Kontonummer
$lut_name: Name der Lookup-Datei oder Leerstring
Falls für $lut_name ein Leerstring angegeben wird, versucht
die Funktion, die Datei blz-at.lut zu lesen.-------------------------------------------------------------------------
Funktion: generate_lut_at()
Aufgabe: LUT-Datei für das österreichische Modul generieren
Aufruf: $retval=generate_lut_at($inputname,$outputname,$plain_name,$plain_format);
Parameter:
$inputname: Name der INPAR-Datei (nur komplett, nicht inkrementell!)
$outputname: Name der Zieldatei (z.B. blz-at.lut)
$plain_name: (optional) Name einer Ausgabedatei für die Klartextausgabe.
$plain_format: Format der Klartextausgabe (s.u.)
Bugs:
Diese Funktion 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 können.
Die Funktion generate_lut_at() generiert aus der Institutsparameter-
Datenbankdatei (5,3 MB) eine kleine Datei (8,3 KB), in der nur die
Bankleitzahlen und Prüfziffermethoden gespeichert sind. Um die Datei
klein zu halten, wird der größte Teil der Datei binär gespeichert.
Falls der Parameter plain_name angegeben wird, wird zu jeder INPAR-
Eintrag außerdem (in einem frei wählbaren Format) noch in eine Klartext-
datei geschrieben. Das Format der Datei wird durch den 4. Parameter
($plain_format) bestimmt. Es sind die folgenden Felder und Escape-
Sequenzen definiert (der Sortierparameter muß als erstes Zeichen
kommen!):
@i Sortierung nach Identnummern
@b Sortierung nach Bankleitzahlen (default)
%b Bankleitzahl
%B Bankleitzahl (5-stellig, links mit Nullen aufgefüllt)
%f Kennzeichen fiktive Bankleitzahl
%h Kennzeichen Hauptstelle/Zweigstelle
%i Identnummer der Österreichischen Nationalbank
%I Identnummer der Österreichischen Nationalbank (7-stellig)
%l Löschdatum (DD.MM.YYYY falls vorhanden, sonst nichts)
%L Löschdatum (DD.MM.YYYY falls vorhanden, sonst 10 Blanks)
%n1 Erster Teil des Banknamens
%n2 Zweiter Teil des Banknamens
%n3 Dritter Teil des Banknamens
%N kompletter Bankname (alle drei Teile zusammengesetzt)
%p Kontoprüfparameter
%t Name der Prüftabelle
%z zugeordnete BLZ (nur bei fiktiver BLZ, sonst nichts)
%Z zugeordnete BLZ (5-stellig bei fiktiver BLZ, sonst 5 Blanks)
%% das % Zeichen selbst
\n Zeilenvorschub
\r CR (für M$DOS)
\t Tabulatorzeichen
\\ ein \
@i (bzw. @b) muß am Anfang des Formatstrings stehen; falls keine
Sortierung angegeben wird, wird @b benutzt.
Nicht definierte Felder und Escape-Sequenzen werden (zumindest momentan
noch) direkt in die Ausgabedatei übernommen. D.h., wenn man %x schreibt,
erscheint in der Ausgabedatei auch ein %x, ohne daß ein Fehler gemeldet
wird. Ob dies ein Bug oder Feature ist, sei dahingestellt; momentan
scheint es eher ein Feature zu sein ;-))).
Falls kein plain_format angegeben wird, wird "@B%I %B %t %N"
benutzt. Die Datei ist (anders als die INPAR-Datei) nach
Bankleitzahlen sortiert. Nähres zur Sortierung findet sich in der
Einleitung zur Funktion cmp_blz().
Die Funktion ist **nicht** threadfest, da dies aufgrund der gewählten
Implementierung nur schwer zu machen wäre, und auch nicht sehr sinnvoll
ist (sie wird nur benötigt, um die blz-at.lut Datei zu erstellen).-------------------------------------------------------------------------
BUGS der Version 2.x:
Die alten Problemfälle aus Version 2.x sind ab Version 3.0 behoben:
- Die Funktion generate_lut() benutzt einen eigenen Variablensatz, so
daß keine Interferenzen mit den Testroutinen auftreten (das git noch
nicht für generate_lut_at()!).
- Die Bibliothek ist jetzt threadfest
- Es ist möglich, die Initialisierung mehrfach aufzurufen; der vorher
allokierte Speicher wird dabei automatisch freigegeben. Auch eine
inkrementelle Initialisierung (bei der nur einige Blocks der
LUT-Datei nachgeladen werden) ist möglich. Falls in der LUT-Datei
zwei Datensätze enthalten sind (und nicht ein bestimmter
ausgewählt wird), erfolgt die (Neu-)Initialisierung in
Abhängigkeit vom aktuellen Datum.SEE ALSO
Eine ausführliche Beschreibung der Prüfziffermethoden und das Format der LUT-Datei findet sich im C-Quellcode.
Eine Mailingliste zu konto_check findet sich auf SourceForge.net unter http://sourceforge.net/mail/?group_id=199719
Die aktuelle Version findet sich unter http://www.informatik.hs-mannheim.de/konto_check
AUTHOR
Michael Plugge, <m.plugge@hs-mannheim.de>
COPYRIGHT AND LICENSE
Copyright (C) 2007-2008 by Michael Plugge
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available (perl and glue code).
The C library is covered by the GNU Lesser General Public License:
This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
1 POD Error
The following errors were encountered while parsing the POD:
- Around line 944:
Non-ASCII character seen before =encoding in 'Prüfziffern'. Assuming CP1252