Verbale Beschreibung

Vorbemerkungen

	Das HIT-Protokoll dient zur Kommunikation zwischen Programmen der Außenstellen (HIT-Clients) mit der Zentralen Datenbank (HIT-Server).
	Hauptzweck des Protokoll ist das Senden und Abrufen von Meldungen mit Datenelemente, analog zu Datensätze mit Datenfeldern
	Es benutzt eine bidirektionale Sockets über eine permanente TCP/IP-Verbindung.
	Zeichensatzkodierung auf dem Socket (Details siehe "Normierung") Standard: ISO 8859-1 ("Latin1"), weitgehend identisch zu ANSI aka Windows Codepage 1251 (aka Cp1251) Alternativ: Unicode-Zeichensatz in der Form UTF-8 ohne "Byte Order Mark" (BOM)
	Die Clients erteilen Befehle der Server gibt Antworten.
	Befehle gliedern sich in 4 Gruppe und dienen zum Execute - Ausführen  von Kommandos, wie z.B. Logon, Logoff, Parameter setzen sowie Ausführen von Meldungen bei denen der Sender nicht weiß, ob Insert oder Update nötig, insbesondere bei Betriebsdaten-Meldungen mit automatischer Historisierung; Insert, Update, Storno, Delete   - Übertragen oder Pflegen von Datensätzen der einzelnen Meldungsarten; Retrieve - Abholen von verschiedenen Daten vom Server. Confirm - Bestätigen bereits abgespeicherter Sätze insbesondere im Konfliktfall (früher XS/S).
	Logon, Logoff und Parameter sind Spezialformen von Meldungen.
	Zu Befehlen existieren Subcodes: zum Beenden, Abbrechen und Bestätigen usw.

	Antworten gliedern sich in 2 Gruppe dienen zum: Mitteilen von Befehlsergebnissen, wie ReturnCodes, Hinweise, Fehlermeldungen (Eine Liste der möglichen konkreten Fehlermeldungen siehe Plausi-Prüfungen im Data-Dictionary) Übertragen von Datensätzen bei Abfragen.
	Befehle und Antworten können aus mehreren zusammengehörigen Teilen bestehen.
	In der Antwort ist Meldung und Feld, auf das sich z.B. eine Fehlermeldung bezieht, erkennbar.
	Befehle und  Antworten bzw. ihre Teile sind zeilenorientiert, d.h. sie beginnen am Zeilenanfang und enden mit Zeilenende (nach Windows-Konvention CR/LF also 0x0d, 0x0A).
	Das 1. Zeichen einer Zeile kennzeichnet Befehle und Antworten, es ist auch erkennbar ob mehrere Teile vorliegen.
	Die Verbindung ist synchron,  zu jedem Client-Befehl erfolgt eine Server-Antwort.
	Optimiert für die verschiedenen Clienttypen (IVR, Online ...) können Datenmeldungen verschieden strukturiert werden: Feldweise - die Datenelemente einer Meldung werden als Folge von mehreren Befehls-Antwort-Sequenzen übertragen, Satzweise - alle Datenelemente einer Meldung werden mit einer Befehls-Antwort-Sequenzen übertragen, Blockweise - mehrere Meldung werden mit einer Befehls-Antwort-Sequenzen übertragen.
	Da ein Kommunikationspartner unvermittelt ausfallen kann, wird mit Timeouts gearbeitet.
	In der Anmeldephase verkürzte Timeouts zur Abwehr von DoS-Attacken (Denial of service).
	Als Codeset ist standardmäßig ISO 8859-1 "Latin-1" vorgesehen, optional kann UTF-8 gewählt werden.
	Als Dezimaltrenner wird nur '.' (Punkt) akzeptiert, Exponentialdarstellung wird nicht unterstützt..
	Beim Datum ist grundsätzlich die Form TT.MM.JJJJ also z.B. 31.01.1999 zu verwenden, siehe Datums-Format, analog siehe Timestamp-Format - hier werden Kurzschreibweisen toleriert etwas der Form 31.2.22.
	Sonderzeichen, insbesondere die Befehls- und Antwort-Trennzeichen ':' (Doppelpunkt) und ';' (Semikolon) sind analog zur Kodierung im HTTP-Protokoll als quoted-hex umzusetzen, siehe Quoted-Hex
	Behandlung von Leerzeichen: Nachfolgende Leerzeichen (trailing Blanks) in Strings werden abgeschnitten (RTrim), Führende und eingebettete Leerzeichen in String sind signifikant und bleiben erhalten, Führende und nachfolgende Leerzeichen (leading and trailing Blanks) bei Zahlen werden abgeschnitten (Trim).

Allgemeiner Ablauf

Verbindungsaufbau (mandatory)

	Öffnen einer Socketverbindung auf dem definierten Port 2222, mit dem HIT-Server hitserver.hi-tier.de, oder falls der nicht verfügbar ist, auf dem selben Port 2222 mit dem Backup-Server hitbackup.hi-tier.de, für Testzwecke steht auf den selben Servern der Test-Port 2223 allgemein zur Verfügung gestellt.
	Namensauflösung und Erreichbarkeit die Namen sind über Standard-DNS-Dienste aufzulösen. Im Internet sind unter diesen Namen Proxyserver zu erreichen. Die Proxyserver leiten automatisch zu den internen Server weiter. Im geschlossenen Intranet sind unter den angegeben Namen die Server direkt zu erreichen.
	Die jeweils aktuellen Internet-Adressen, -Namen und Ports zu HI-Tier finden Sie hier.

Anmeldung (mandatory)

	Logon mit Betriebsnummer als Userid
	und PIN als Paßwort
	nach 3 fehlerhaften PIN-Eingaben wird die Verbindung getrennt und für eine definierte Zeit gesperrt
	die Angabe des Meldeweges ist verpflichtend, insbesondere ob Daten von einer RS kommen

	AktionsCode ist "X" für Execute
	Partitionierung (Stückelung) ist "S" (satzweise) oder "F" (feldweise)
	der Ablauf ist analog zu Meldungen mit Meldeart "LOGON"
	Beispiel:    *1:XS:LOGON/BNR15;PIN;MELD_WG:276091234567890;123456;1     (Erklärung siehe Befehlsaufbau)

Parameter festlegen (optional) , Erweiterung zum LOGON

	eine Reihe von Parametern können festgelegt werden, Liste siehe Parameter-Liste
	erfolgt keine explizite Festlegung, so werden sinnvolle Defaultwerte angenommen
	Parameter-Festlegung erfolgen mit der LOGON-Meldung
	die Einstellungen gelten nur für den aktuell angemeldeten Benutzer
	die Einstellungen können nur durch erneutes LOGON geändert werden
	bei einem erneuten LOGON werden nicht angegebene Parameter wieder auf Default zurück gesetzt
	Partitionierung (Stückelung) ist i.d.R "S" (satzweise) aber auch "F" (feldweise) ist möglich
	es wird empfohlen die eigene benutzte Protokoll-Version anzugeben
	die Parameteränderungen werden mit dem erfolgreichen Abschluß der LOGON-Meldung wirksam
	Beispiel:    *1:XS:LOGON/BNR15;PIN;MELD_WG;VERSION;VERBOSE;TIMEOUT:276091234567890;123456;1;1;1;120

Daten senden (optional)

	Daten für die verschiedenen Meldungsarten, z.Zt. definierte Arten siehe HIT-Meldungen
	AktionsCode ist "X" für Execute (Ausführen einer Datenmeldung) oder in definierten Situationen "I" für Insert (Einfügen neuer Sätze) oder "U" für Update, "S" für Storno oder "D" für Delete (eine genauere Erläuterung, wann welche Aktion zu verwenden siehe HIT-Aktionen und Melden und Korrigieren)
	Partitionierung (Stückelung) ist "F" (feldweise), "S" (satzweise) oder "B" (blockweise)
	Antwort in Form von OK-Meldung, Hinweisen, Nachfragen, Fehlermeldungen oder Abbruch

Daten abrufen (optional)

	Daten für die verschiedenen Meldungsarten oder variable Definitionen
	gespeicherte Abfragen
	geänderte Daten ab Timestamp
	Fehlermeldungen aus früheren Sendungen
	i.d.R. Satzweise
	Antwort beinhalten Daten, Hinweise und Meldungen

Abmeldung (recommened)

	LOGOFF-Befehl beendet die Sitzung und Benutzeridentifikation
	die geänderten Parameter werden nicht zurück gesetzt
	LOGON-Befehl für neuen Benutzer bewirkt implizites LOGOFF des angemeldeten Benutzers

Verbindungsabbau (mandatory)

schließen der Socketverbindung

Zustände und Ereignisse

Zustände

1. NC (=NOT-CONN)
2. NA (=NOT-AUTH)
3. RE (=READY)
4. FM (=FIELD-MODE)
5. RM (=ROW-MODE)
6. BM (=BLOCK-MODE)

Ereignisse

1. open-Socket
2. Logon
3. Logoff
4. Aktion-Feld
5. Input-Feld
6. Aktion-Satz

Grobstruktur

Das HIT-Protokoll kennt verschiedene Zustände und Ereignisse. Zustands-Ereignis-Diagramme können in verschiedene Detailgenauigkeit betrachtet werden.

(Diagramm fehlt nocht)

Befehls- und Antwortsyntax

Vorbemerkungen und Definitionen

Pflicht- und Nichtpflicht-Bestandteile Mandatory - bestimmte Elemente von Befehlen oder Befehle in einer Dialogsequenz werden unbedingt benötigt Recommended  - bestimmte Teile sind empfohlen, wie z.B. explizites LOGOFF um Resourcen wieder freizugeben Optional - Teile können fehlen und werden ggf. sinnvoll ergänzt, z.B. Feldliste einer satzweisen Meldung muß nur beim 1.Satz übertragen werden. fehlende Betriebsnummern in Meldungen werden durch BNR der Anmeldung ergänzt, wenn BNR aber als Datenfeld in der Meldung angegeben wird, darf sie nicht leer sein.

Die Protokoll-Beispiele haben folgende Darstellung: S:   <Server-Output>           // Kommentar C:   <Client-Output>           // Kommentar

Befehlsaufbau

Ein Befehl besitzt eine fortlaufende BefehlsNummer. Der 1.Befehl der Connection hat die Nummer 1. Ein Befehl kann aus einer oder mehreren Teilbefehlen bestehen. Jeder Teilbefehl ist eine eigene Zeile. Wenn weitere Teilbefehle folgen ist die Zeile mit dem Befehlskennzeichen "+" zu beginnen, beim letzten Befehlsteil oder wenn der Befehl nur aus einem Teil besteht ist die Zeile mit dem Befehlskennzeichen "*" zu beginnen. Jeder Teilbefehl hat die gleiche BefehlsNummer. Teilbefehle werden ohne dazwischen liegende Antworten versendet. Befehlsteile dienen zur blockorientierten Übertragung.

Neue Befehle dürfen erst gesendet werden, wenn die Antwort für den letzten Befehl vollständig empfangen wurde. Die Teile eines Befehles werden ebenfalls beginnend mit 1 durchnummeriert.

Syntax und Bestandteile

Schematische Darstellung

*<Nr>:<AktionsCode><Partitionierung>/<SubCode>:<Meldung>/<Feldliste>:<Datenliste>

AktionsCodes

SubCodes

SubCodes bei Übertragung feldweise

SubCodes bei Übertragung satzweise

SubCodes bei Übertragung blockweise

Durch Angabe der SubCodes K oder L im letzten Befehl des Blocks kann dieses Standardverhalten geändert und der Transaktionsabschluss gesteuert werden.

SubCodes (speziell für Aktion RS "RETRIEVE"), Details zu RS siehe HIT-QL

Spezialfälle

Hinweise zu SubCodes

Die SubCodes /T und /S können

	zur Bestätigung der zuvor übermittelten Daten dienen nachdem der HIT-Server einen Fehler der Schwere 2 gemeldet hat und zur Bestätigung oder Korrektur aufgefordert hat
	oder sie können präventiv verwendet werden, d.h. daß die Daten im aktuellen Befehl oder Meldung keiner Bestätigungsabfrage für Fehler der Schwere 2 bedürfen und stattdessen Schwere 0 als OK geantwortet wird.
	Wenn /T oder /S angegeben sind, wird kein Hinweis mehr ausgegeben und Schwere ist 0, d.h. OK

Der SubCodes /U0 für Aktion X "Execute"

übernehmen der Datenwerte aus dem vorhandenen Datensatz für nicht angegebene Felder

Beispiel

C:  *1:XF/T:LOGON/BNR15:276091234567890            

C:  *87:IS:ABGANG/LOM;BNR15;ABGA_DAT:276123456789012;091234567890;01.04.1999            

C:  *88:IS::276111156789012;091234567890;01.05.1999            

C:  +89+1:IB:ABGANG/LOM;BNR15;ABGA_DAT:276123456789012;091234567890;01.04.1999
C:  +89+2:::276123456789012;091234567890;01.04.1999
C:    ...
C:  *89+413:::276123456789012;091234567890;01.04.1999            

Antwortaufbau

Eine Antwort wird vom HIT-Server generiert und bezieht sich, über die Befehlsnummer erkennbar, auf den letzten vom HIT-Client gesendeten Befehl.

Eine Antwort kann aus einer oder mehreren Teilantworten bestehen. Jede Teilantwort ist eine eigene Zeile. Wenn weitere Teilantworten folgen ist die Zeile mit dem Antwortkennzeichen "%" zu beginnen, beim letzten Antwortteil oder wenn die Antwort nur aus einem Teil besteht ist die Zeile mit dem Antwortkennzeichen "=" zu beginnen.

Eine Antwort resultiert aus den Ergebnissen von Plausibilitätsprüfungen der Datenelemente und Meldungen oder als positive Bestätigung wenn ein Befehl erfolgreich ausgeführt wurde.

Syntax und Bestandteile

Schematische Darstellung

=<Nr>:<Schwere>/<AntwortCode>:<Meldung>/<Feldliste>:<Textliste>
%<Nr>:<Schwere-1>/<AntwortCode-1>:<Meldung>/<Feldliste>:<Text-1>
%...
=<Nr>:<Schwere-N>/<AntwortCode-N>:<Meldung>/<Feldliste>:<Text-N>

Beispiele

Einfache Antwort, Kurzform

S:  =87:0/0::            

Einfache Antwort, Langform

S:  =117:1/1013:LOGON/PIN:Hinweis - PIN von Erstinstallation, bitte bald ändern            

Antwort mit 2 Teilen auf einen Befehl

S:  %87%1:1/1002:ABGANG/*:Abgang vor Zugang
S:  =87%2:1/1003:ABGANG/*:Abgang 10 Tage verspätet            

Antwort mit 2 und 1 Teilen auf Befehl mit 9 Unterbefehlen

S:  %87+1%1:1/1002:ABGANG/*:Abgang vor Zugang
S:  %87+1%2:1/1003:ABGANG/*:Abgang 10 Tage verspätet
S:  =87+9:1/1003:ABGANG/*:Abgang 10 Tage verspätet            

Besondere Hinweise

Mehrere Antwortteile

Die Plausibilitätsprüfung eines einzelnen Feldes oder einer gesamten Meldung kann zu mehreren Antwortteilen führen, denn Hinweise (Schwere 1) und Fehler der Schwere 2 führen nicht zum Abbruch der Feldprüfung, d.h. die restlichen Prüfungen für das Feld werden fortgesetzt. Fehler der Schwere 3 dagegen brechen die Prüfung des Feldes ab und Fehler der Schwere 4 brechen sogar den gesamten Prüfprozess und die Dialogsitzung ab.

Beim Befehl zum Beenden und Speichern einer feldweise übertragenen Meldung ("*nr:IF/E::") werden weitere Plausibilitätsprüfungen für die Meldung als ganzes (Querchecks) durchgeführt. Auch diese werden erst bei einem Fehler der Schwere 3 abgebrochen, d.h. es können mehrere Antwortteile mit Schwere 1 und Schwere 2 sowie maximal ein Antwortteil mit Schwere 3 oder 4 entstehen.

Bei der satzweisen Übertragung werden alle Felder nacheinander geprüft, bricht die Prüfung eines einzelnen Feldes mit Schwere 3 ab, werden dennoch die Prüfungen aller anderen Felder weiter durchgeführt. Somit können in beliebiger Reihenfolge mehrere Antwortteile mit Schwere 1 , 2 oder 3 sowie maximal ein Antwortteil mit Schwere 4 entstehen.

Bei der satzweisen Übertragung werden diese Querchecks nach den Prüfungen aller Einzelfelder durchgeführt wenn diese Feldprüfungen Antworten maximal bis zu Schwere 2 erzeugt haben. Bei max. Schwere 3 werden die Querchecks nicht mehr durchgeführt. Bei max. Schwere 2 werden die Querchecks zwar durchgeführt um ggf. noch weitere Hinweise oder Nachfragen für die Gesamt-Meldung zu erzeugen, ein Abspeicher erfolgt aber nicht ! Sinn dieser Vorgehensweise ist, dass alle Fehler der Schwere 2 die nach Bestätigung durch den Client akzeptiert werden könnten gemeinsam und nur einmal bestätigt werden müssen, ein /T (=TROTZDEM, FORCE) für einzelne Feld ist bei der satzweisen Meldung nicht möglich. Stattdessen muß der Client bei max. Schwere 2 den ganzen Satz mit /S (=SICHER) bestätigen oder mit /A (=ABBRUCH) verwerfen.

Der HIT-Client muß aus allen Antwortteilen die maximale Schwere ermitteln und daraus erkennen ob die Meldung nun tatsächlich gespeichert wurde (maximale Schwere 1) oder nicht (Schwere 2,3,4)

Positive Antwort: Schwere 0

Antworten der Schwere 0, d.h. dass ein bestimmter Befehl fehlerfrei ist, z.B. die Übertragung eines einzelnen Feldes oder die Abspeicherung des Satzes werden nicht mehr genauer spezifiziert. Der Antwortcode ist immer 0, Objekt- und Textteil sind leer, Beispiel: "=<nr>:0/0::" .

Bei satzweisen Übertragung werden zwar alle Felder nachinander geprüft und ggf. mehrere Hinweise und Fehlerantworten ausgegeben, aber fehlerfreie Felder werden nicht einzeln mit Antwortsätzen der Schwere 0 bestätigt.

Befehls - Antwort Abfolge

Feldweise Übertragung

F/A - Einleitung der Übertragung

C:  *87:IF:ABGANG/LOM:276123456789012                              

F/B/0 - Fortsetzung der Übertragung, wenn Feld OK

S:  =87:0/0::                              

C:  *88:IF:/BNR15:091234567890                              

F/B/1 - Fortsetzung der Übertragung, wenn Feld mit Hinweis

S:  =87:1/2234:ABGANG/LOM:Alte LOM-Serie, bitte nicht weiter verwenden                              

C:  *88:IF:/BNR15:091234567890                              

F/B/2 - Wiederholen oder korrigieren, wenn Nachfrage

S:  =87:2/2234:ABGANG/LOM:Alte LOM-Serie, wirklich verwendet?                              

F/B/2a - Wenn der Benutzer den Wert unverändert bestätigt

C:  *88:IF/T:ABGANG/LOM:276123456789012                              

F/B/2b - Wenn der Benutzer den Wert korrigiert

C:  *88:IF:ABGANG/LOM:276111111119012                              

F/B/3 - Korrigieren, wenn nicht akzeptierbarer Fehler

S:  =87:3/2234:ABGANG/LOM:LOM nicht an Betrieb gegeben,korrigieren..                              

C:  *88:IF:ABGANG/LOM:276111111119012                              

F/B/4 - Abbrechen der Verbindung, wenn kritischer Fehler

S:  =87:4/2299:ABGANG/LOM:LOM gestohlen, Verbindung beendet
S:  <DISCONNECT>                              

F/C - Ende mit Speichern oder Abbruch der Meldung

C:  *88:IF/E::	(ENDE, mit Speichern zurück in Ready-Status)
C:  *88:IF/S::	(SICHER, mit Speichern, Schwere 2 akzeptieren)                              

C:  *88:IF/A::	(ABBRUCH, ohne Speichern zurück in Ready-Status)
C:  *88:IF/P::	(PANIK, ohne Speichern Verbindung unterbrechen)                              

F/D/0 - Status Ready, wenn Meldung OK

S:  =88:0/0::                              

F/D/1 - Status Ready, wenn Meldung mit Hinweis

S:  %88%1:1/2234:ABGANG/*:Abgang gespeichert, Hinweis der _
		Käufer hat den Zugang bereits vor 10 gemeldet
S:  =88%2:1/2237:ABGANG/*:Abgang gespeichert, es liegen _
		mehrere Zugänge bei anderen Betrieben vor                              

F/D/2 - Wiederholen oder korrigieren, wenn Nachfrage

S:  =88:2/2277:ABGANG/*:Abgang 2 Monate her, ist das OK ?                              

F/D/2a - Wenn der Benutzer die Meldung unverändert bestätigt

C:  *89:IF/S::                              

F/D/2b - Wenn der Benutzer die Meldung korrigieren möchte

C:  *89:IF:/LOM:276111144449012                              

oder            

C:  *89:IF/A::                              

F/D/3 - Korrigieren, wenn nicht akzeptierbarer Fehler

S:  =89:3/3299:ABGANG/*:Abgang über 1 Jahr her                              

F/D/4 - Abbrechen der Verbindung, wenn kritischer Fehler

S:  =89:4/2299:ABGANG/*:Abgangsdatum läßt schweren Unterschleif _
		vermuten, das System bendet die Verbindung
S:  <DISCONNECT>                              

Satzweise Übertragung

S/A - Einleitung der Übertragung

C:  *87:XS:ABGANG/LOM;BNR15;ABGA_DAT:27789012;0912890;01.04.1999                              

S/B/0 - Status Ready, wenn Meldung OK, weitere Meldungen der selben Art verkürzt möglich

S:  =87:0/0::                              

C:  *88:XS::276123456789012;0914444;07.06.1999                              

S/B/1 - Status Ready, wenn Meldung mit Hinweis, weitere Meldungen der selben Art verkürzt möglich

S:  %87%1:1/2234:ABGANG/*:Der Käufer hat _
		den Zugang bereits vor 10 gemeldet
S:  =87%2:1/2237:ABGANG/*:Es liegen mehrere Zugänge _
		bei anderen Betrieben vor                              

C:  *88:XS::276123012;091234444;07.06.1999                              

S/B/2 - Wiederholen oder korrigieren, wenn Nachfrage

S:  =87:2/2277:ABGANG/*:Abgang 2 Monate her, sicher ?                              

S/B/2a - Wenn der Benutzer die Meldung unverändert bestätigt

C:  *88:IS/S::2761289012;091267890;01.04.1999                              

S/B/2b - Wenn der Benutzer die Meldung korrigieren möchte

C:  *88:XS::2761239012;09124444;07.05.1999                              

S/B/3 - Korrigieren, wenn nicht akzeptierbarer Fehler

S:  =87:3/3299:ABGANG/*:Abgang 1 Jahr her, korrigieren                              

S/B/4 - Abbrechen der Verbindung, wenn kritischer Fehler

S:  =87:4/2299:ABGANG/*:Abgangsdatum läßt schweren Unterschleif _
		 vermuten,das System bendet die Verbindung
S:  <DISCONNECT>                              

Blockweise Übertragung

B/A - Übertragung von mehreren Aktionen als Befehl mit Unterbefehlen

C:  +87+1:XB:ABGANG/LOM;BNR15;ABGA_DAT:27789012;0912890;01.04.1999
C:  +87+2:XB::27789014;0923456;31.01.1999
C:  +87+3:XB::27789017;0911111;11.11.1999
C:  *87+4:XB:ZUGANG/LOM;BNR15;ZUGA_DAT:27789012;0888888;01.04.1999                              

B/B/0 - Alle Teilbefehle werden abgearbeitet

B/B/1 - Wegen schwerer Fehler "Panik" wird Verarbeitung abgebrochen

Weitere Beispiele

Fehlerhafte Befehle

C:  *1:AF:LOGON:27609123456789
S:  =1:3/3001:LOGON/*:Syntax - Falscher Befehl	// Nicht akzeptierbarer Fehler            

C:  *1:XF:LOGON:27609123456789
S:  =1:3/3002:LOGON/*:Syntax - Feld feht            

Logon feldweise

C:  *1:XF:LOGON/BNR15:27609123456789		// feldweises Logon mit 1.Feld
S:  =1:3/1001:LOGON/BNR15:NR nicht vorhanden	// Antwort:  Fehler ..
C:  *2:XF:LOGON/BNR15:276099100010001
S:  =2:0/0::
C:  *3:XF:/PIN:123				// Meldung darf fehlen
S:  =3:1/104:LOGON/PIN:Nur 3 Stellen riskant	// OK aber Hinweis
C:  *4:XF/E::					// Ende der feldweisen Meldung
S:  =4:0/123:LOGON/*:Anmeldung ausgeführt	// Antwort 0/1 als Schwere            

oder - bei Nachfrage in Feld            

C:  *3:XF:/PIN:123456				// Meldung darf fehlen
S:  =3:2/105:LOGON/PIN:Noch Start-PIN,sicher ?	// Nachfrage
C:  *4:XF/T:/PIN:123456				// Wert mit FORCE erneut senden
S:  =4:0/0::
C:  *5:XF/E::					// Ende der feldweisen Meldung
S:  =5:0/123:LOGON/*:Anmeldung ausgeführt	// Antwort 0/1 als Schwere            

Logon satzweise

C:  *1:XS:LOGON/BNR15;PIN:123456789;123456	// satzweises LOGON mit Daten
S:  =1:3/1001:LOGON/BNR15:Nr nicht vorhanden	// Antwort:  Fehler ..
C:  *2:XS:LOGON/BNR15;PIN:9100010001;123456
S:  =2:0/0::            

Logoff satzweise

Spezialfall der satzweisen Übertragung, keine Datenfelder nötig

C:  *89:XS:LOGOFF:  				// Client LOGOFF
S:  =89:0/999:LOGOFF/*:Abmeldung OK  		// Server akzeptiert LOGOFF
						// geht in Status NOT-AUTH
						// bleibt aber connected            

Abgänge satzweise

C:  *87:XS:ABGANG/LOM;BNR15;ABGA_DAT:2761234012;091234890;01.04.1999
S:  =87:0/100:ABGANG/*:ABGANG OK            

C:  *88:XS::276123456789012;091234567890;01.04.1999
S:  %88%1:1/1235:ABGANG/LOM:Tier ist beim Abgang erst 1 Tag alt
S:  =88%2:1/1456:ABGANG/*:Weitere Hinweise zum Abgang ...            

C:  *89:XS::276123456789012;091234567890;01.04.1999
S:  =89:2/2123:ABGANG/ABGA_DAT:Abgangsdatum gleich Geburtsdatum, sicher?
C:  *90:XS/S::276123456789012;091234567890;01.04.1999
S:  =90:0/0::            

Abgänge blockweise

C:  +87+1:XB:ABGANG/LOM;BNR15;ABGA_DAT:27789012;0912890;01.04.1999
C:  +87+2:XB::27789014;0923456;31.01.1999
C:  +87+3:XB::27789017;0911111;11.11.1999
C:  *87+4:XB:ZUGANG/LOM;BNR15;ZUGA_DAT:27789012;0888888;01.04.1999
S:  %87+2:3/3299:ABGANG/*:Abgang 1 Jahr her, korrigieren
S:  %87+2%1:1/234:ABGANG/ABGA_DAT:Meldefrist überschritten
S:  %87+2%2:1/333:ABGANG/*:Hinweis ...            

Parameter-Liste

siehe auch HIT-Meld-Elemente zu LOGON

Quoted-Hex

Sonderzeichen, insbesondere die Befehls- und Antwort-Trennzeichen ':' (Doppelpunkt) und ';' (Semikolon) sowie der Quoting-Charakter '%' (Prozent) sind analog zur Kodierung im HTTP-Protokoll als quoted-hex umzusetzen. Die Hex-Codierung des jeweiligen Zeichens ist der Codetabelle ISO 8859-1 zu entnehmen. Im Folgenden werden die wichtigsten Zeichen aufgelistet. Die Substitution ist nur auf die einzelnen Befehls- und Antwort-Token anzuwenden, d.h. die Befehls-  ('+' und '*') und Antwortkenner ('%' und '=') sowie die Tokentrenner  (':' und ';') selbst werden nicht umgesetzt.

Zeichen die umgesetzt werden müssen

Zeichen die umgesetzt werden können (Umlaute, Sonderzeichen)

Zeichen die nicht umgesetzt werden müssen

Übermittlung von NULL-Values

Erklärung: Es gibt Datenfelder, die optional sind, d.h. keine Werte enthalten müssen, aber falls sie vorhanden sind keinen Leerstring enthalten düfen (NULLABLE = TRUE and EMPTY = FALSE). Bei der feldweisen Übertragung kann das Feld einfach nicht übertragen werden. Bei der satzweisen oder blockweisen Übertragung wenn einzelne Sätze (z.B. LKV-Betriebe) Werte übertragen sollen andere aber Sätze keinen Wert für dieses Feld haben und eine Plausiprüfung einen Leertring nicht zulassen würde, kann das fehlen des Wertes, sprich der NULL-Value mittels Angabe von "%--" übertragen werden. Weitere Hinweise siehe Darlegung der NULL-Semantik (Hier erfolgt ggf. noch eine Änderung ??)

Was wird umgesetzt

Von der Umsetzung betroffen sind alle Datenelemente in der Datenliste eines Befehls und alle Textelemente im Textteil einer Antwort. Jedes Element wird einzeln behandelt und kann daher auch individuelle NULL-Werte oder Separatoren als Inhalt transportieren.

Wann wird umgesetzt

Beim Bilden der Datenliste eines Befehls, aus externen Quellen wie Benutzereingaben oder Input-Dateien, wird jedes Datenelement separat mit "QuoteHex" umgesetzt und durch Semikolon getrennt in der Liste angehängt.

Bei Empfangen eines Befehls wird jedes Datenelement separat mit "UnquoteHex" wieder zurück in den Originalwert oder einen NULL-Value umgesetzt, vor es dann in der Datenabnk gespeichert wird.

Beim Verpacken der Textelemente des Textteils in der Antwortstruktur wird ebenfalls mit "QuoteHex" umgesetzt, so dass auch die Sonderzeichen transportiert werden können. Insbesondere beim Ausgeben von Datenabfragen wird im Textteil der Antwort jeder Datenwert als eigenes Textelement behandelt und separat "hex-quoted".

Erst wenn die Antwort wieder in die Einzelbestandteile getrennt werden soll erfolgt die Rückumsetzung mit "UnquoteHex". Wenn die Antwort insgesamt weiterübermittelt wird, wie z.B. beim HIT-Batchclient in der LOG-Datei darf noch nicht zurückumgesetzt werden, da der Empfänger sonst beim Parsen des Antwortstrings Probleme hat.

NULL-Semantik

Bei der Ausgabe von Werten im HIT-Protokoll werden NULL-Values, d.h. Feldern in denen in der Datenbank nichts gespeichert ist als Quoted-Hex Darstellung "%--" ausgegeben. Bei alle Textstrings werden rechts alle nachfolgenden Leerzeichen ("trailing blanks") abgeschnitten, so daß eine Stringvariable, die nicht NULL ist aber nur Blanks enthält, als leerer String, also i.d.R. ";;" dargestellt wird. (Hier erfolgt ggf. noch eine Änderung ??)

Beim Senden von Daten im HIT-Protokoll ist nach der restriktiven HIT-CSV Festlegung vorzugehen. Einzelheiten siehe Klarstellungen zum CSV-Format

NULL vs. Leerstring

Wie Stringsvariablen ohne Inhalt nun tatsächlich zu behandeln sind, als Leerstring oder NULL, wird separat festgelegt, siehe NULL/Leerstring.

Semantische Feinheiten

Folgende Anmerkungen sind besondere Feinheiten und i.d.R. nicht von Bedeutung. Bei der Entwicklung eigener HIT-Clients können sie aber zur Klarstellung dienen.

1. Da nach dem letzten Element einer CSV-Auflistung kein Separator folgt, ist eine CSV-Auflistung ohne Elemente nicht von einer Auflistung mit einem Leerstring zu unterscheiden => es gibt keine Auflistung ohne Elemente.
2. Der Befehl RETRIEVE mit einem einzelnen leeren Element in der Datenliste "*n:RS:<entity>/*:" wird akzeptiert.
3. Da die Anzahl der Feldelemente gleich der Anzahl der Datenelemente sein muss (außer bei RETRIEVE), gibt es keine Entität ohne Elemente. Die Entität LOGOFF wird mit "*n:XS:LOGOFF:" ausgeführt, dabei wird intern ein Dummy-Feld mit leerem Feldnamen und ein leeres Datenelement angenommen.
4. Wenn in aufeinander folgenden Meldungen die Objekt-Teile (Meldung/Feldliste) identisch sind, können sie entfallen um Daten auf der Leitung zu sparen. Der Server benutzt dann automatisch die letzte Objekt-Liste erneut, z.B:
   1. Meldung "*n:RS:ABGANG/LOM;BNR15;ABGA_DAT:27600..;27609..;1.1.99".
   2. Meldung "*n:RS::27600..;27609..;2.2.99".
5. Eine Verkürzung des Objektteils auf nur die Meldung ohne Schrägstrich ist genauso zulässig und eindeutig, z.B:"*n:RS:ABGANG:27600..;27609..;3.3.99".
6. Nur Meldungsteil und Schrägstrich, z.B. "*n:RS:ABGANG/:27600..;27609..;4.4.99" heißt eigentlich Feldliste hat ein leeres Element und sollte daher nicht verwendet werden.

Zum Seitenanfang