Nachrichtenformate

Nachrichtenformate und Protokollversionen

Jede Nachricht, die ein berechtigtes Benutzerprogramm sendet, darf höchstens 31 KB lang sein. Längere Nachrichten werden mit REJ1 abgewiesen. Nachrichten, die das Benutzerprogramm empfangen soll, sind damit maximal 31 KB groß plus die Länge des ggfs. hinzugefügten Headers (siehe "Makro NBMHE"), denn von anderen Absendern stammende Nachrichten sind sowieso viel kleiner (so beträgt die maximale Länge einer mit MSG7X ausgegebenen Meldung z.B. 4 KB).

Der Text dieser Nachrichten hat grundsätzlich das gleiche Format wie bei Ein-/Ausgaben an physikalischen Konsolen (siehe voriges Kapitel). Zusätzliche Formate ergeben sich ausschließlich, wenn das berechtigte Benutzerprogramm als Server eines Operator-Spezialkommandos fungiert. Diese Erweiterungen sind in ab "Operator-Spezialkommandos in berechtigten Benutzerprogrammen" beschrieben.
Für die automatische Auswertung der empfangenen Meldungen ist ein reines Textformat jedoch ungünstig, da jede Einzelinformationen – z.B. der Wert eines bestimmten Inserts in einer Meldung – in dem Text erst gesucht werden müsste. Das Format von Ausgabetexten ist aber keine garantierte, bei Versionswechsel unverändert bleibende Schnittstelle.
Das System bietet daher an, mit berechtigten Benutzerprogrammen formatierte Nachrichten auszutauschen, die neben dem Text zusätzliche Informationen enthalten. Gesteuert wird dies durch die Protokollversion, die das berechtigte Benutzerprogramm beim Verbindungsaufbau zu $CONSOLE beantragt. Dieser Vorgang ist für Anschlüsse unter generiertem und unter dynamischem Berechtigungsnamen unterschiedlich und kann den entsprechenden Abschnitten auf "Anschlüsse mit generierten Berechtigungsnamen" entnommen werden.
Die Bedeutung der ausgewählten Protokollversion ist jedoch in allen Fällen gleich.

Protokollversion 0

Hinter dem Begriff Protokollversion 0 verbirgt sich die einfache Vereinbarung, dass sich der Nachrichtenaustausch zwischen System und berechtigtem Benutzerprogramm in beide Richtungen auf den Nachrichtentext beschränkt. Zusätzliche Informationen werden nicht ausgetauscht.

Protokollversion 1

Vereinbart das berechtigte Benutzerprogramm mit der $CONSOLE-Schnittstelle die Protokollversion 1, erwartet das System als Eingabe weiterhin nur Texte der bekannten Formate. Beim Senden von Nachrichten durch das berechtigte Benutzerprogramm bestehen also keinerlei Unterschiede zu Protokollversion 0.
Nachrichten vom System erhält das berechtigte Benutzerprogramm jedoch in erweiterter Form, bestehend aus einem Nachrichtenkopf (Header), dem eigentlichen Text, so wie er bei Protokollversion 0 netto übertragen worden wäre, sowie, falls es sich bei der Nachricht um eine mit MSG7[X] ausgegebene Meldung handelt, ein Füllbyte mit nachfolgender datenorientierten Beschreibung („Mapping-Format“) des Meldungsaufbaus.

Eine DSECT zur Beschreibung des Nachrichtenkopfes kann durch den Makro NBMHE erzeugt werden, der im Anschluss beschrieben ist.
Aufbau und Inhalt der datenorientierten Meldungsbeschreibung sind der Beschreibung des Makros NBMAP auf "Makros NBMAP" zu entnehmen. 

Protokollversion 2

Vereinbart das berechtigte Benutzerprogramm mit der $CONSOLE-Schnittstelle die Protokollversion 2, erhält es alle Nachrichten vom System in erweiterter Form. Bezüglich des Empfangs von Meldungen durch das berechtigte Benutzerprogramm besteht also kein Unterschied zu Protokollversion 1.
Vom berechtigten Benutzerprogramm an das System gesendete Nachrichten müssen hier jedoch die gleiche, erweiterte Form aufweisen; die Übertragung des reinen Nachrichtentextes reicht nicht mehr aus.
Im Regelfall bringt die Erzeugung des Nachrichtenkopfes für das berechtigte Benutzerprogramm lediglich zusätzlichen Aufwand (und Fehlerquellen), aber keinen besonderen Nutzen mit. Notwendig ist die Verwendung der Protokollversion 2 ausschließlich, wenn das berechtigte Benutzerprogramm als Server für ein verwaltbares Operator-Spezialkommando dienen soll. Die dann geltenden Besonderheiten sind ab "Operator-Spezialkommandos in berechtigten Benutzerprogrammen" beschrieben.

Makro NBMHE

Der Makro NBMHE beschreibt das Format des Nachrichtenheaders. Die Assembler-Schnittstelle hat folgendes Aufrufformat:

Makro	Operanden
NBMHE	MF=D/C, PREFIX=prefix, MACID=macid, VER=1/2/3

Für den Benutzer ist die Angabe VER=1 nicht erlaubt!

Der Header hat folgenden Aufbau:

Parameter	V	DS	AT	LH	L2	L1	D	AK	SP	BC	RC2	RC1	FL	UID
gültig für Version	123	123	123	123	123	123	123	23	23	23	23	23	3	3

Parameter	Bedeutung
V	Versionsnummer des Makros NBMHE, der diese Struktur generiert; 1 Byte
DS	Dialogstatusbyte; 1 Byte X'80'   Anmeldungsdialog läuft X'40'  Verbindung vorläufig akzeptiert X'10'  endgültige Akzeptierung der Anmeldung X'08'  Anmeldung abgewiesen X'04'  Operator-Logon angefordert X'02'  Kennwort angefordert
AT	Auftragstyp; 1 Byte Werte bei Makro V01: %  ?  /  .  *  ; zusätzliche Werte ab Makro V02: +  !  &  :
LH	Länge des Headers; 2 Byte
L2	Distanz zum datenorientierten Teil; 2 Byte (L2=0000, falls kein datenorientierter Teil (mit NBMAP beschrieben) vorhanden ist)
L1	Länge des textorientierten Teils; 2 Byte
D	Ziel einer Meldung; 4 Byte
Erweiterung für NBMHE Version 02 und 03:
AK	Auftragskennzeichen abhängig vom Auftragstyp; 4 Byte
SP	Indikator für Senderprofil; 1 Byte
BC	Berechtigungscodemenge; 5 Byte
RC2	Kommandoreturncode Subcode2 zum Verschicken an bzw. beim Empfang von Kommandogeber; 1 Byte
RC1	Kommandoreturncode Subcode1 zum Verschicken an bzw. beim Empfang von Kommandogeber; 1 Byte
Erweiterung für NBMHE Version 03:
FL	Flag-Byte, das den Typ des Kommandogebers ausgibt; 1 Byte
	X'80' X'40' X'20'
UID	Benutzerkennung des Kommandogebers; 8 Byte

Hinweise zu den einzelnen Feldern

Die meisten Felder des NBMHE sind nur in bestimmten Zusammenhängen relevant, die in der Tabelle aufgeführt sind. Sollte der jeweilige Zusammenhang nicht gegeben sein, so bedeutet dies bei vom System empfangenen Nachrichten einheitlich, dass der Feldinhalt undefiniert ist, und bei an das System gesendeten Nachrichten, dass der Feldinhalt vom System nicht ausgewertet wird, also beliebig gewählt werden kann.
Ferner ist der von der Art des verwendeten Berechtigungsnamens anhängige Anmeldedialog des berechtigten Benutzerprogrammes aus Gründen der Übersichtlichkeit separat beschrieben, siehe "Anschlüsse mit generierten Berechtigungsnamen". Die Tabelle bezieht sich auf den – von der Berechtigungsnamensart unabhängigen – Nachrichtenaustausch nach erfolgreichem Verbindungsaufbau (Dialogstatusbyte = 0).

V	Immer relevant Die Versionsnummer wird durch den Parameter VER des NBMHE-Makros bestimmt. Das System verwendet für seine Nachrichten stets die neueste Version. Das Benutzerprogramm ist jedoch nicht verpflichtet, beim Senden von Nachrichten die gleiche Version zu verwenden; mit Ausnahme von Version 1 akzeptiert das System alle kleineren Versionen kompatibel und eventuelle größere Versionen mit der Einschränkung, dass neu hinzugekommene Felder natürlich nicht berücksichtigt werden können.
DS	Immer relevant Das Dialogstatusbyte zeigt an, in welcher Phase des Anmeldungsdialogs sich das berechtigte Benutzerprogramm befindet. Von Null verschiedene Werte können ausschließlich während des Anmeldedialogs vorkommen. Nach erfolgreichem Verbindungsaufbau ist das Byte immer 0.
AT	Immer relevant Typkennzeichen der Nachricht (siehe "Nachrichtenaustausch der Operator").
LH	Länge des Headers, gleichzeitig – da der Nachrichtentext unmittelbar hinter dem Header folgt – die Distanz vom Anfang der Nachricht zum Text. Das Feld muss mit der angegebenen NBMHE-Version übereinstimmen (d.h. 25 Byte für Version 2, 34 Byte für Version 3). Um auch für künftige Versionen korrekt arbeiten zu können, muss die Länge trotzdem immer dem Längenfeld entnommen werden.
L2	(DLL2) Immer relevant Distanz vom Anfang der Nachricht zum datenorientierten Teil (NBMAP). Ist kein datenorientierter Teil vorhanden, ist die Distanz 0. Wichtig: Ist ein datenorientierter Teil vorhanden, darf er nicht unmittelbar hinter dem Nachrichtentext liegen, sondern muss durch mindestens ein Füllbyte von ihm getrennt sein. L2 ist also zwangsläufig größer als LH + L1.
L1 D AK	(DLL1) Immer relevant Nur relevant bei empfangenen Nachrichten Nur relevant beim Empfang von Kommandos (AT = „ / “) und Kommandozusatzinformationen (AT = „ : “) sowie beim Senden von Nachrichten im Rahmen der Kommandobehandlung (näheres siehe „Operator-Spezialkommandos“, ab "Operator-Spezialkommandos in berechtigten Benutzerprogrammen").
SP	Nur relevant beim Senden von Nachrichten Dieses Byte muss immer auf Null gesetzt werden. Andere Werte sind für Systemanwendungen reserviert.
BC RC2 RC1	Nur relevant, wenn SP ungleich Null ist (also ausschließlich für Systemanwendungen). Nur bei Nachrichten vom Typ „Kommandoende“ (AT = „ ! “) relevant Nur bei Nachrichten vom Typ „Kommandoende“ (AT = „ ! “) relevant
FL	Der Begriff „SCI-Task“ bezeichnet hier eine Benutzertask mit dem zur Eingabe des Kommandos notwendigen Privileg (bei selbstdefinierten Operator-Spezialkommandos muss dies nicht das OPERATING-Privileg sein).
UID	Nur beim Empfang von Kommandos (AT = „ / “) relevant

Die Versionsnummer des Headers ist nicht mit der Protokollversionsnummer der Verbindung zu verwechseln.

Das Feld LH befindet sich in allen Versionen auf Distanz X'03' im Header. Ihm ist die Distanz zum Beginn des Folgetextes zu entnehmen, da der Folgetext unmittelbar hinter NBMHE beginnt.

Makro NBMAP

Der Makro NBMAP beschreibt den Nachspann der Nachricht. Die Assembler-Schnittstelle hat folgendes Aufrufformat:

Makro	Operanden
NBMAP	MF=D/C/L,PREFIX=chars 1, MACID=macid 1..3, VERSION=1 ,MSGKEY=chars 7..7,MSGRC=chars 1..1 ,MSGWEIGHT=msgweight,MSGINSNUM=integer 0..15 ,INSERTS=((length1,distance1),...,(length,distancex))

Die Struktur hat folgenden Aufbau:

IL

ID

IL

ID

...

IL

ID

V

MK

RC

WC

NI

INS0

INS1

INSn

Parameter	Bedeutung
V	Versionsnummer des Makros NBMAP, der diese Struktur generiert; 1 Byte
MK	Meldungsschlüssel; 7 Byte
RC	Routing-Code; 4 Byte (linksbündig, restliche Stellen mit 0 aufgefüllt)
WC	Gewicht der Meldung; 1 Byte
NI	Anzahl der Inserts; 1 Byte
IL	Länge des aktuellen Inserts; 2 Byte
ID	Distanz des aktuellen Inserts ab Anfang des Meldungstextes; 2 Byte
INS0 ....INSn	0...n Inserts der Meldung

Beispiel mit Nutzung des Nachrichten-Headers V02