Inhalt

	Vorab
	Voraussetzung
	Grundsätzliches
	Anmeldung und Abmeldung
	Meldung einer Geburt
	Abfrage der eigenen Betriebsanschrift
	Weitere Informationen

Vorab

Im Folgenden ein paar einfache Beispiele, die man auch sehr leicht in einer telnet-Sitzung nachvollziehen kann. Es werden lediglich Testbetriebe und -daten verwendet.

Beispiel in Eingabeaufforderung:

Microsoft Windows XP [Version 5.1.2600]
(C) Copyright 1985-2001 Microsoft Corp.

C:\>telnet hitbackup.hi-tier.de 2223

Zu beachten ist, dass wir unangekündigt jederzeit die Testinstanzen neu aufsetzen, weil wir dort unsere Entwicklungen testen. Dann ist der gegebene Port kurzzeitig nicht verfügbar.

HINWEIS: Da der HitServer unter Umständen sehr lange Zeilen liefern kann, wird in den Beispielen unten eine lange Zeile umbrochen und durch ein  \ am Zeilenende gekennzeichnet. Diese Kennzeichnung liefert nicht der HitServer zurück!

Voraussetzung

Es muß eine erfolgreiche Socket-Verbindung zu einem unserer Server und Ports bestehen, d.h. der HitServer antwortet mit der "Hello"-Message:

=0:0/103::HitServer bereit. Version 100, 01.01.2009 00-00. Sie sind mit dem Test \
system T1B_H12 verbunden, nur eingeschraenkt verfuegbar da hier entwickelt wird  \
(Server benutzt neue Betriebstabellen/NEWADS) HI-Tierzeit 01.01.2009 12-00-00h C \
hallenge -7318593407631969708

Danach können die Anmeldung und weitere Befehle im HIT-Protokoll gesendet werden. Auf Details zum Protokoll wird weiters nicht eingegangen.

Grundsätzliches

Es muß immer leider wieder darauf hingewiesen werden, daher hier auch nochmal:

Ausnahmslos jede Antwort vom HitServer muss ausgewertet werden!

Man darf nie automatisch davon ausgehen, dass ein gesendeter Befehl erfolgreich ist.
Das schließt die "Hello"-Message und die Anmeldung mit ein!

Beispiel:

=1:3/226:LOGON/BNR15:Betriebsnummer nicht gefunden.

Rot markiert ist der Wert der Fehlerschwere, hier die 3, welche für Fehler steht. Fehlerschweren größer 1 müssen den Programmablauf unterbrechen und ggf. eigene Aktionen seitens des Benutzers erfordern.

Der Antwort-Aufbau ist hier detailliert beschrieben.

Anmeldung und Abmeldung

Anmeldung

*1:XS:LOGON/BNR15;PIN;MELD_WG;TIMEOUT:04 000 000 0001;900001;3;1200

Betriebsnummern können sowohl 15stellig (beginnen mit 276) als auch 12stellig (ohne die 276) angegeben werden.

Als Antwort kommt:

=1:0/223:LOGON/*:Anmeldung erfolgreich.

Ist eine Anmeldung nicht erfolgreich, weil z.B. die Betriebsnummer nicht stimmt, dann kommt beispielsweise:

=1:3/226:LOGON/BNR15:Betriebsnummer nicht gefunden.

Ohne erfolgreiche Anmeldung hat man maximal 4 Versuche, bevor der Server von sich aus die Socket-Verbindung abbricht:

=1:4/190:LOGON:Nach mehreren ungültigen Versuchen wurde die Verbindung abgebrochen.

Abmeldung

*99:XS:LOGOFF:

Antwort:

=99:0/251:LOGOFF/*:Abmeldung erfolgreich.

Anzumerken ist, dass durch die Abmeldung die Socket-Verbindung nicht automatisch beendet wird, sondern man kann sich danach gleich wieder anmelden. Eine selbst programmierte Anwendung sollte daher nach einer Abmeldung ohne weitere Anmeldung von sich aus die Socket-Verbindung beenden, damit auf Serverseite der belegte Socket frei werden kann. Umgekehrt kann eine Anwendung, die mehrere Mandanten nacheinander verarbeitet, auf der ein und derselben Socket-Verbindung arbeiten.

Zudem kann man ohne vorherige Abmeldung eine andere Anmeldung durchführen. Das System meldet den vorherigen Mandanten dann automatisch ab.

Meldung einer Geburt

Grundsätzlich ist zu beachten, dass nicht generell jede Meldung "einfach so" absetzbar ist. Für viele Meldungen müssen bestimmte Randbedingungen erfüllt sein, bevor sie erfolgreich abgesetzt werden können.

Bei einer Geburt muß die Ohrmarkennummer des Muttertieres auf dem Betrieb gemeldet sein, bei dem das Tier auf die Welt kam. Zusätzlich müssen von einer Regionalstelle ausgegebene Ohrmarkenserien für den Betrieb im System vermerkt sein. Es sind evtl. noch weitere Randbedingungen gegeben (zeitl. Abstand zur letzten Kalbung, Muttertier ist weiblich und lebt, etc.).

Die Geburtsmeldung

*2:IS:GEBURT/LOM;BNR15;GEB_DATR;RASSE;GESCHL_R;LOM_MUT:DE 04 000 00051;04 000 00 \
0 0001;13.12.2008;41;1;DE 04 000 00007

liefert folgende Antwort:

%2%1:1/308:GEBURT/GEB_DATR:Die Meldefrist von 7 Tagen ist überschritten, bitte F \
rist künftig beachten.
=2%2:0/130:GEBURT:Die Meldung wurde abgespeichert.

Die erste Antwortzeile weist darauf hin, dass zwischen Ereignisdatum (hier die Geburt am 13.12.2008) und dem Meldedatum (hier der 01.01.2009) mehr als 7 Tage liegen. Da die Meldung die (rot markierte) Fehlerschwere 1 hat, verhindert sie nicht das endgültige Speichern der Meldung, sollte jedoch dem Anwender als Nachricht o.ä. angezeigt werden.

Mit der zweiten Antwortzeile signalisiert der HitServer der Anwendung, dass die Meldung erfolgreich abgespeichert wurde.

Die maximale Fehlerschwere aller Antworten zu einer Meldung zeigt an, ob die Anwendung ihre Verarbeitung fortsetzen kann oder den Anwender auf eine Aktion hinweisen soll: Fehlerschwere < 2 ist in Ordnung, Fehlerschwere = 2 erwartet eine Bestätigung vom Anwender und Fehlerschweren > 2 führen immer zu einer Fehlermeldung. Bestätigte Meldungen müssen lediglich erneut gesendet werden, jedoch mit dem Subcode T (siehe HIT-Protokollbeschreibung).

Setzt man die identische Geburtsmeldung erneut ab, dann erhält man dies:

%2%1:1/308:GEBURT/GEB_DATR:Die Meldefrist von 7 Tagen ist überschritten, bitte F \
rist künftig beachten.
=2%2:1/133:GEBURT:Diese Meldung liegt bereits identisch vor und wurde deshalb ig \
noriert.

Die zweite Antwortzeile ist ein Hinweis, der besagt, dass diese Meldung bereits in identischer Form vorliegt.

Abfrage der eigenen Betriebsanschrift

Abgefragt wird mit Retrieve, kurz R. Daher ist die Anfrage an den HitServer zum Abfragen der eigenen Betriebsanschrift diese:

*2:RS:BTR_D/BNR15;NAME;STR_NR;PLZ;ORT;ORTSTEIL:

Vorab ist wichtig zu wissen, dass sämtliche Angaben im Adreßbereich wie Betriebsanschrift (BTR_D), Postanschrift (BTR_P), Betriebstypen (BTR_T) oder Betriebszuordnungen (BTR_Z) sowohl mit fachlichen Gültigkeiten als auch mit technischen Gültigkeiten arbeiten. Man kann für eine technische Gültigkeit mehrere fachliche Gültigkeiten erhalten, d.h. man darf nicht erwarten, dass man z.B. bei der Betriebsanschrift nur eine Antwort erhält! Es könnte sein, dass der Betrieb früher einmal anders hieß, aber noch die selbe Betriebsnummer besitzt.

Da jede Anfrage an den Server auf seine Kompetenz hin überprüft wird, werden Abfragen automatisch auf den für den Anmeldebetrieb maximal möglichen Betriebsnummernbereich eingeschränkt.
Im obigen Beispiel ist dies ein normaler Rinderhalter (= 04 000 000 0001), so dass er maximal seinen eigenen Betrieb abfragen darf. Daher kann der vierte Anfrageteil leer bleiben (erkennbar am : als letztes Zeichen der Anfrage).

Als Antwort auf die obige Anfrage erhält man:

%2%1:-1/0:BTR_D/BNR15;NAME;STR_NR;PLZ;ORT;ORTSTEIL:276040000000001;Name-04000000 \
0001;Str-0001;10001;Ort-0001;%--
=2%2:1/121:BTR_D:Anzahl Datenzeilen - 1;Select BNR15,NAME,STR_NR,PLZ,ORT,ORTSTEI \
L from HTX.BTR_D WHERE BNR15 =276040000000001 AND SYS_BIS = '2100-12-31-00.00.00 \
.000000' for fetch only;Stand=01.01.2009/00.00.00.000000

Datenzeilen aus Abfragen (nicht Meldungen) als solches haben immer die Plausinummer 0 und besitzen negative Fehlerschweren (hier -1).

Der dritte Antwortteil, der mit dem Namen der abgefragten Entität (hier BTR_D) beginnt, enthält alle Namen der gelieferten Spalten (hier BNR15;NAME;STR_NR;PLZ;ORT;ORTSTEIL) und der vierte Antwortteil enthält in der gleichen Reihenfolge wie die Spaltennamen die Daten (hier 276040000000001;Name-040000000001;Str-0001;10001;Ort-0001;%--). Ein Programm kann also leicht einen Hash der Form

$btr_d = {
   'BNR15'    => '276040000000001',
   'NAME'     => 'Name-040000000001',
   'ORTSTEIL' => '%--',
   'STR_NR'   => 'Str-0001',
   'PLZ'      => '10001',
   'ORT'      => 'Ort-0001',
};

erzeugen (hier in Perl-Syntax).

Der ORTSTEIL lieferte einen Wert %--. Dieser sagt aus, dass dieses Feld keine Daten enthält, was etwas anderes bedeutet als eine leere Zeichenkette! In Java oder PHP würde man null dazu sagen, in Perl undef oder in Visual Basic Nothing.

Weitere Informationen

Als Ausgangspunkt für selbst gestrickte Anfragen dient die Seite aller möglichen Entitäten und Abfragefunktionen. Zu den Abfragefunktionen existieren neben den Antwortspaltenbeschreibungen auch detailierte Parameterbeschreibungen.