PREIS_BB.dll - pro-SOFT Datennetze GmbH

PREIS_BB.dll
Entfernungsberechnung
und Preisermittlung
bei festgeschalteten Verbindungen
pro-SOFT
Dokumentation
PREIS_BB.dll (dynamic-link-library)
(Entfernungsberechnung und Preisermittlung
bei festgeschalteten Verbindungen)
1
Einleitung
Kosten für Mietleitungen (LeasedLines) der Deutschen Telekom zu ermitteln, ist oftmals ein recht
schwieriges Unterfangen, da diese wesentlich von Tarifentfernungen bestimmt sind, die zwischen
Entfernungsmesspunkten ermittelt werden müssen. Leider sind diese Entfernungsmesspunkte je
nach gewünschter Leistung anders anzusetzen, was den Kalkulationsvorgang erschwert. Hinzu
kommt die Notwendigkeit, bei Berechnungen nach der Preissystematik ab 01.04.2005
Alternativen über Basisnetz und Backbone-Netz mit Zubringerleitungen zu vergleichen.
Die hier vorliegende Dynamic Link Library <PREIS_BB.dll> ist in der Lage, die häufigst
verwendeten Übertragungswege absolut korrekt zu berechnen, wobei auch die erforderliche
Tarifentfernung nach den Regeln der Telekom ermittelt wird. Dazu müssen der DLL eine Reihe
von Parametern übergeben werden, die die gewünschte Leistung genau beschreiben. Immer
dann, wenn zwingend erforderliche Angaben nicht oder falsch übergeben werden, ersetzt die DLL
diese durch andere, mögliche Parameter oder durch Defaultwerte. So ist auch in automatischen
Prozessen
mit
größtmöglicher
Sicherheit
eine Bepreisung
der
verschiedensten
Übertragungswege gegeben.
Je Version der DLL (dynamic-link-library) und ihrer Datenfiles sind alle Änderungen der
Bezugspunkte berücksichtigt, die bis zum jeweiligen Ausgabe-Stichtag wirksam werden. Bei einer
Aktualisierung der zugehörigen Entfernungs- und Preisdateien müssen grundsätzlich alle Dateien
ausgetauscht werden, um eine einwandfreie Funktion zu gewährleisten.
Die vorliegende Ausgabe der <...\PREIS_BB.dll> wurde für 32-bit Windows1 NT 4.0, 2000 und
XP als Bibliothek zur Verwendung in eigenen Programmen entwickelt. Sie kann von Programmen
zur Laufzeit dynamisch in den Adressraum eines Prozesses geladen werden. In den Dateien
<datKM*.dat> und <f-pre*.dat> sind die zur Funktion notwendigen Daten hinterlegt. Die Dateien
<PREIS_BB.ini> und <Art_BB.ini> enthalten Informationen, mit denen die DLL eingestellt bzw.
deren Funktion beeinflusst werden kann.
1
Windows ist ein eingetragenes Warenzeichen der Microsoft Corp., USA
Seite 2
Für die Ausführung des 32Bit -Dateiensystems sind folgende Dateien mindestens erforderlich:
im Verzeichnis <...\PREIS_BB\...>:
<PREIS_BB.dll>
eigentliche DLL
<PREIS_BB.ini>
Pfade
<Art_BB.ini>
unterstützte LeasedLinks
im Verzeichnis <...\DATEN\...>:
<datKM0a.dat>
<datKM0f.dat>
<datKM0g.dat>
<datKM0q.dat>
<datKM6a.dat>
<datKM6a0.dat>
<datKM6c.dat>
<datKM6c0.dat>
<datKM6d.dat>
<f-pre4.dat>
<f-pre6.dat>
<f-pre25.dat>
<f-pre26.dat>
<f-pre27.dat>
<f-pre28.dat>
Datendatei
Datendatei
Datendatei
Datendatei
Datendatei
Datendatei
Datendatei
Datendatei
Datendatei
Preisdatei
Preisdatei
Preisdatei
Preisdatei
Preisdatei
Preisdatei
Die Steuerdateien <*.ini> und die ausführbaren Dateien müssen sich im aktuellen Verzeichnis,
den Systemverzeichnissen oder in einem durch PATH bezeichneten Verzeichnis befinden. Zur
Ausführung der DLL ist es notwendig, dass sich alle Datendateien im Nachbarverzeichnis
<...\PRO\DATEIEN\...> der DLL, im Systemverzeichnis, in einem in der Enviromentvariablen
PATH enthaltenen Verzeichnis oder in dem durch die Datei <...\PREIS_BB.ini> bezeichneten
Verzeichnis befinden.
2
Verwendung der <PREIS_BB.dll>
Die <PREIS_BB.dll> kann durch Prozesse/Anwendungen auf 32bit Windowssystemen explizit
durch Aufruf der Win32-Funktion LoadLibrary( ) oder implizit durch den Aufruf einer ihrer
Funktionen geladen werden. Dabei ist es möglich, die Bibliothek durch mehrere Prozesse
gleichzeitig zu nutzen. Die DLL unterstützt sowohl single- als auch multithreaded Anwendungen
(s. auch Ressourcenbedarf).
© Copyright:
pro-SOFT (Datennetze) GmbH, Rollefstr.61, 52078 Aachen
Seite 3
pro-SOFT
2.1 Installation
Zur Installation aller ausführbaren Programmteile wie auch der erforderlichen Datendateien
braucht lediglich das Installationsprogramm <setup.exe> gestartet zu werden, das sich ebenfalls
auf der ausgelieferten CD befindet. Menügeführt kann hier der Zielpfad vorgegeben werden, in
dem das Dateiensystem erzeugt werden soll. Die Pfadangaben sollten der 8.3 Notation
entsprechen. Ist auf dem gleichen Rechner auch unser Programm "pro-PREIS mit eDB2"
installiert, empfiehlt es sich, auch die DLL in dieses System zu integrieren. Befindet sich z.B. proPREIS im Pfad: <C:\PRO\PREIS>, sollte bei der Installation als Zielpfad <C:\> vorgegeben
werden. So wird bei einem späteren Update des Programms pro-PREIS hinsichtlich Preise und
Entfernungsmesspunkte die Datenbasis der DLL automatisch mit aktualisiert. Ein gesondertes
Update erübrigt sich dann.
2.2 Initialisierung
Wird die DLL durch einen Prozess geladen, so werden die notwendigen Initialisierungen
automatisch durchgeführt. Dazu sucht die DLL im aktuellen Verzeichnis, in den durch den PATH
bezeichneten Unterverzeichnissen, im Systemverzeichnis und dem im File <PREIS_BB.ini>
angegebenen Verzeichnis nach den Dateien <datKM*.dat>, öffnet diese und belegt den
benötigten Speicher.
Tritt während der Initialisierungsphase ein Fehler auf, wird ein entsprechender Fehlerstatus
vermerkt und die Initialisierung abgebrochen. Der Fehlerstatus wird beim Aufruf der
Abfragefunktion als Codezahl und durch die Rückgabe eines Textes signalisiert.
2.3 Funktionen der PREIS_BB.dll
Die Programmschnittstelle der DLL wird durch einen Übergabestring gesteuert, der alle erforderlichen Parameter enthalten muss. Die einzelnen Übergabewerte müssen nur in so fern
eingetragen werden, wie sie für das zu kalkulierende Produkt erforderlich sind. Alle Einträge, auch
Leereinträge, müssen durch Semikolon getrennt werden.
Auf Grund der vorgegebenen Ortsnetzkennzahlen ermittelt die DLL die kostenrelevanten
Verkehrsbeziehungen (Backbone Netz, Zubringernetz und Basisnetz) des Produkts und ermittelt
unter Berücksichtigung der Mindestmietzeit dessen Kosten. Bei Carrier Festverbindungen (CFV)
sind auch die Anschlussleitungslängen Kosten bestimmend. Deshalb sind hier weitere
geografische Daten der Endstellen erforderlich. Wurden z.B. die Hoch- und Rechtswerte der
Endstelle übergeben, ermittelt die DLL automatisch die Entfernung zur angegebenen
Teilnehmervermittlungsstelle (AsB). Fehlen die Hoch- /Rechtswerte, wird stattdessen der
mitgegebene Kilometerwert (KMa und KMb) in die Kalkulation übernommen. Ist auch einer dieser
Wert 0 oder leer, unterstellt die DLL an der betroffenen Endstelle eine „Kollokationszuführung“
(Abschluss der Verbindung auf dem Grundstück der Telekom).
Seite 4
© Copyright:
pro-SOFT (Datennetze) GmbH, Rollefstr.61, 52078 Aachen
Seite 5
pro-SOFT
2.4
Die Steuerdatei <Art_BB.ini>
Die Steuerdatei <Art_BB.ini> enthält alle Übertragungswegtypen, die mit der DLL berechnet
werden können. Zur Identifikation des gewünschten Typs muss beim Aufruf der DLL der
Parameter “Art“ des Übergabestrings entweder eine der untenstehenden dreistelligen "ID" oder
die Kurzbeschreibung "Artikel" enthalten.
ID
Artikel
Langbeschreibung
101
102
103
104
105
106
108
109
110
111
112
113
114
DDV 1200
DDV 2400
DDV 4800
DDV 9600
DDV 19,2K
DDV 64K oE
DDV 128K
DDV 1,92M oE
DDV-M 9600
DDV-M 19,2K
DDV-M 64K
DDV-M 128K
DDV-M 1,92M
DDV
DDV
DDV
DDV
DDV
DDV
DDV
DDV
DDV
DDV
DDV
DDV
DDV
201
202
203
204
205
206
207
SFV
SFV
SFV
SFV
SFV
SFV
SFV
Analog
Analog
Analog
Analog
Analog
Analog
Analog
anal.
anal.
anal.
anal.
anal.
anal.
anal.
301
302
303
304
305
306
307
308
309
310
311
312
314
SFV
SFV
SFV
SFV
SFV
SFV
SFV
SFV
SFV
SFV
SFV
SFV
SFV
Digital
Digital
Digital
Digital
Digital
Digital
Digital
Digital
Digital
Digital
Digital
Digital
Digital
Seite 6
Var1/2dr
Var1/4dr
Var2/2dr
Var2/4dr
Var3/2dr
Var3/4dr
Var3/6dr
64S
64U
64S 1xdAS
64S 2xdAS
64S2
S01
S02
TS02
2MS
2MU
T2MS
34M
155M
1200
2400
4800
9600
19,2
64
128
1,92
9600
19,2
64
128
1,92
bit/sek
bit/sek
bit/sek
bit/sek
kbit/sek
kbit/sek
kbit/sek
Mbit/sek
bit/sek
kbit/sek
kbit/sek
kbit/sek
Mbit/sek
SFV
SFV
SFV
SFV
SFV
SFV
SFV
digitale
digitale
digitale
digitale
digitale
digitale
digitale
digitale
digitale
digitale
digitale
digitale
digitale
Variante
Variante
Variante
Variante
Variante
Variante
Variante
SFV
SFV
SFV
SFV
SFV
SFV
SFV
SFV
SFV
SFV
SFV
SFV
SFV
Typ
Typ
Typ
Typ
Typ
Typ
Typ
Typ
Typ
Typ
Typ
Typ
Typ
(alt)
(alt)
(alt)
(alt)
(alt)
(alt)
(alt)
(alt)
(alt)
(alt)
mit managebaren DNAE
mit managebaren DNAE
mit managebaren DNAE
1
1
2
2
3
3
3
64S
64U
64S
64S
64S2
S01
S02
TS02
2MS
2MU
T2MS
34M
155M
in
in
in
in
in
in
in
2-draht
4-draht
2-draht
4-draht
2-draht
4-draht
6-draht
Ausführung
Ausführung
Ausführung
Ausführung
Ausführung
Ausführung
Ausführung
1x64 kbit strukt.
1x64 kbit unstrukt.
Doppelansch.(1Ende)
Doppelansch.(2Enden)
2x64 kbit ohne DK
1x64 kbit mit DK
2x64 kbit mit DK
2x54 kbit mit DK
1x 2 Mbit strukt.
1x 2 Mbit unstrukt.
1x 2 Mbit strukt.
1x34 Mbit strukt.
1x155 Mbit strukt.
401
402
405
406
407
408
409
410
411
412
413
414
415
416
417
418
CFV
CFV
CFV
CFV
CFV
CFV
CFV
CFV
CFV
CFV
CFV
CFV
CFV
CFV
CFV
CFV
Digital
Digital
Digital
Digital
Digital
Digital
Digital
Digital
Digital
Digital
Digital
Digital
Digital
Digital
Digital
Digital
64S
64U
64S2
S01
S02
TS02
2MS
2MU
T2MS
34M
155M
622M
2G5
16x2MU
21x2MU
63x2MU
Carrier-FV
Carrier-FV
Carrier-FV
Carrier-FV
Carrier-FV
Carrier-FV
Carrier-FV
Carrier-FV
Carrier-FV
Carrier-FV
Carrier-FV
Carrier-FV
Carrier-FV
Carrier-FV
Carrier-FV
Carrier-FV
Typ
Typ
Typ
Typ
Typ
Typ
Typ
Typ
Typ
Typ
Typ
Typ
Typ
Typ
Typ
Typ
64K
64U
64S2
S01
S02
TS02
2MS
2MU
T2MS
34M
155M
622M
2,5G
64K
64K
64K
1x64 kbit strukt.
1x64 kbit unstrukt.
2x64 kbit ohne DK
1x64 kbit mit DK
2x64 kbit mit DK
2x64 kbit mit DK
1x 2 Mbit strukt.
1x 2 Mbit unstrukt.
1x 2 Mbit strukt.
1x34 Mbit strukt.
1x155 Mbit strukt.
1x622 Mbit strukt.
1x2,5 Gbit strukt.
16x2 Mbit unstrukt.
21x2 Mbit unstrukt.
63x2 Mbit unstrukt.
(Diese Liste erhebt keinen Anspruch auf Vollständigkeit und wird der Produktverfügbarkeit am
Markt entsprechend angepasst)
2.5 Die Steuerdatei <PREIS_BB.ini>
Die Steuerdatei <PREIS_BB.ini> gibt an, wo die DLL nach ihren erforderlichen Daten- und Preisdateien suchen soll. Der Eintrag muss aus einer vollständigen Laufwerks- und Pfadangabe
bestehen (z.B. <C:\PRO\DATEIEN>). Findet die DLL die Dateien dort nicht, sucht sie zunächst im
aktuellen Verzeichnis, dann in den durch den PATH bezeichneten Unterverzeichnissen und
letztendlich im Systemverzeichnis. Sind die Dateien auch hier nicht zu finden, wird der Fehlercode
PREIS_BB_FILE ausgegeben.
© Copyright:
pro-SOFT (Datennetze) GmbH, Rollefstr.61, 52078 Aachen
Seite 7
pro-SOFT
2.6 Funktionsaufruf1: Ermittlung der Entfernung und Kosten
SHORT PREIS_BB (LPSTR lpSteuerung1,LPSTR lpSteuerung2)
Beispiel:
Resultat = PREIS_BB("241; ; ; ; ;69; ; ; ; ;DDV 9600 bit/s;36;“vollständig“)
Dies ist die zentrale Funktion der Bibliothek. Sie ermittelt aufgrund der Eingangsparameter die
Kosten des Übertragungswegs.
2.6.1
Eingangsparameter: (LPSTR lpSteuerung)
lpSteuerung ist ein String, der alle 14 durch Semikolon getrennte Parameter aufnimmt.
lpSteuerung =
2.6.2
"ONKZa; AsBa; H_WERTa; R_WERTa; Kma; ONKZb; AsBb; H_WERTb;
R_WERTb; KMa; UE_Weg_Art; Mietzeit; Darstellung"
Parameter:
Beschreibung
Beispiel-Werte
'ONKZa':
'AsBa':
'H-WERTa':
'R-WERTa':
'KMa':
Ortsnetzkennzahl A
Anschlussbereichsnummer A
Gauss-Krüger Hochwert A
Gauss-Krüger Rechtswert A
vorgegebene Entfernung in A
241,
xx,
xxxxxxx,
xxxxxxx,
xx,
'ONKZb':
'AsBb':
'H-WERTb':
'R-WERTb':
'KMb':
'Ü-Weg-Art'
'Mietzeit'
’Darstellung’
Ortsnetzkennzahl B
Anschlussbereichsnummer B
Gauss-Krüger Hochwert B
Gauss-Krüger Rechtswert B
vorgegebene Entfernung in B
siehe Datei <Artikel.dat>
in 'Monaten' oder 'Jahren'
Ausgabemodus
69,
069,
xx,
-,
xxxxxxx,
-,
xxxxxxx,
-,
xx,
0,
DDV 9600, 104
xx,
-,
vollständig, kurz, leer
0241,
-,
-,
-,
0,
24100
leer
leer
leer
leer
69000
leer
leer
leer
leer
leer
Ausgangsparameter: (LPSTR lpErgebnis)
lpErgebnis ist ein String, der die Antwortparameter aufnimmt. Wie viele Antwortparameter
übergeben werden, hängt von dem Steuerwort ’Darstellung’ ab.
lpErgebnis =
(bei Steuerwort
“vollständig“)
Seite 8
"Installationskosten:
“monatliche Kosten:
“
“Anschlussnetz <A>:
“Basisnetz:
“Anschlussnetz <B>:
“
“SUMME:
“
“Anschlussnetz <A>:
“Zubringernetz <A>:
“Backbone-Netz:
“Zubringernetz <B>
“Anschlussnetz <B>:
“
“SUMME:
x.xx EUR
x.xx EUR
x km
x km
x km
x.xx EUR yyyy/y
x.xx EUR yyyy/y yyyy/y
x.xx EUR yyyy/y
-----------------x.xx EUR
x
x
x
x
x
x.xx EUR
x.xx EUR
x.xx EUR
x.xx EUR
x.xx EUR
-----------------x.xx EUR
km
km
km
km
km
yyyy/y
yyyy/y yyyy/y
yyyy/y yyyy/y
yyyy/y yyyy/y
yyyy/y
“
“
“
“
“
“
“
“
“
“
“
“
“
“
“
“
lpErgebnis =
"km;Installationskosten;mon/jährl.Kosten:“
(bei beliebigem anderen
Steuerwort
Ist lpErgebnis ein gültiger Zeiger auf einen Speicherbereich, so wird in diesen das
Ergebnis der Abfrage als nullterminierter String geschrieben. Der Speicherbereich muss
mindestens Platz für LEN_Ergebnis Zeichen bieten und durch das aufrufende Programm
bereitgestellt werden. Wird ein NULL-Zeiger übergeben, so bleibt lpErgebnis unverändert.
3
Ressourcenbedarf
Neben dem Speicherplatz für den Code der DLL werden weitere Ressourcen zur Laufzeit der DLL
belegt. Dabei werden Ressourcen prozessglobal für die Anwendung wie auch für jeden einzelnen
thread von multi-threaded Applikationen belegt:
je Prozess, der die DLL lädt bzw. in seinen Speicherbereich einblendet:
max. vier Filehandle
einen Indexplatz für threadlokalen Speicher (TLS)
je Thread (nur wenn dieser Thread Funktionen der DLL aufruft):
ca. 1 kByte Speicher auf dem Heap
4
Rückgabewert /Fehlercodes
Bei Aufruf der DLL wird ein Zahlenwert als Ergebniscode zurückgegeben :
ErgebnisCode = PREIS_BB(lpSteuerung, lpErgebnis)
War eine Kalkulation mit den vorgegebenen Parameter erfolgreich, ist dieser Wert 0. Wird ein
negativer Wert zurückgemeldet, kann aus der Zahl die Fehlerursache abgeleitet werden.
Ergebniscode = 0
Ergebniscode = -1
Ergebniscode = -2
Ergebniscode = -3
Ergebniscode = -4
Ergebniscode = -101
Ergebniscode = -102
Ergebniscode = -103
Ergebniscode = -104
Ergebniscode = -999
© Copyright:
Berechnung ok
Fehler bei der Initialisierung (z.B. fehlende Dateien, falscher Pfad)
falsche Anzahl der übergebenen Parameter
angegebener Artikel in der Datei <Art_BB.ini> nicht enthalten
eine der Datendateien ist defekt /fehlerhaft oder fehlt
die Angaben zur Berechnung des ausgewählten Produkts in der
Fernebene sind unvollständig oder fehlerhaft.
die Angaben zur Berechnung des ausgewählten Produkts an Endstelle <A> sind unvollständig oder fehlerhaft.
die Angaben zur Berechnung des ausgewählten Produkts an Endstelle <B> sind unvollständig oder fehlerhaft.
Die Angaben zur Mietzeit sind unvollständig oder falsch
nicht definierter Fehler
pro-SOFT (Datennetze) GmbH, Rollefstr.61, 52078 Aachen
Seite 9
pro-SOFT
5
Demoprogramme
Am Beispiel des Excelprogramms <testdemo.xls> wird eine praktische Einbindung der DLL unter
VBA demonstriert. Der Quellcode ist voll zugänglich und kann für eigene Anwendungen
nachvollzogen werden.
Excelsheet 1: Beispiel einer Einzelkalkulation
Seite 10
Excelsheet
Listenkalkulation
© Copyright:
2:
pro-SOFT (Datennetze) GmbH, Rollefstr.61, 52078 Aachen
Beispiel
einer
Seite 11
pro-SOFT
6
Beispiel für die Definition einer C/C++ und VB/VBA-Schnittstelle
Die Definitionen der Konstanten und Aufrufe für C/C++ -Programme finden Sie in der Datei
<PREIS_BB.H>, deren Inhalt nachfolgend aufgelistet ist:
/*----------------------------------------------------------------------------/
/
/
/
/
/ File: PREIS_BB.H
/
/
/
/
Headerdatei mit den Prototypen der PREIS_BB.DLL
/
/
wie in der Dokumentation beschrieben.
/
/
/
/
/
/----------------------------------------------------------------------------*/
//------------------------------------------------------------------------// Definitionen
// Stringlängen für Ein- und Ausgabe
#define LEN_STEUERWORT
255
#define LEN_ERGEBNIS
2048
// Rückgabecode-Konstanten
#define PREIS_BB_OK
#define PREIS_BB_ERRINIT
#define PREIS_BB_PARAMETER
#define PREIS_BB_ARTIKEL
#define PREIS_BB_FILE
#define
#define
#define
#define
PREIS_BB_ENTFERNUNG
PREIS_BB_ORTA
PREIS_BB_ORTB
PREIS_BB_MIET
#define PREIS_BB_SONST
0
-1
-2
-3
-4
-101
-102
-103
-104
-999
// die folgenden Definitionen für PREIS_BBDLLAPI und PREIS_BBCALLDEF müssen für
Ihren C-Compiler evtl. angepasst werden
#if !defined(PREIS_BBDLLAPI)
// Definition für den Import von Funktionen aus der DLL durch ClientApplikationen
#define PREIS_BBDLLAPI __declspec(dllimport)
#define PREIS_BBCALLDEF __stdcall // Aufruf Win32-Standard
#endif
// die Funktion der PREIS_BB-DLL
#if defined(__cplusplus)
extern "C" {
#endif
PREIS_BBDLLAPI SHORT PREIS_BBCALLDEF PREIS_BB(LPSTR lpSteuerung1, LPSTR lpSteuerung2);
#if defined(__cplusplus)
}
#endif
Seite 12
Die Definitionen der Konstanten und Aufrufe für VB /VBA -Programme finden Sie in der Datei
<kmPR-api.bas>, deren Inhalt nachfolgend aufgelistet ist:
Option Explicit
' Stringlängen für Ein- und Ausgabe
Public Const LEN_STEUERWORT = 255
Public Const LEN_ERGEBNIS = 2048
' Rückgabecode-Konstanten
Public Const PREIS_BB_OK = 0
Public Const PREIS_BB_ERRINIT = -1
Public Const PREIS_BB_PARAMETER = -2
Public Const PREIS_BB_ARTIKEL = -3
Public Const PREIS_BB_FILE = -4
Public
Public
Public
Public
Const
Const
Const
Const
PREIS_BB_ENTFERNUNG = -101
PREIS_BB_ORTA = -102
PREIS_BB_ORTB = -103
PREIS_BB_MIET = -104
Public Const PREIS_BB_SONST = -999
' die Funktion der PREIS_BB-DLL
Declare Function PREIS_BB Lib "PREIS_BB.dll" (ByVal lpSteuerung1 As String, ByVal
lpSteuerung1 As String) As Integer
© Copyright:
pro-SOFT (Datennetze) GmbH, Rollefstr.61, 52078 Aachen
Seite 13