Ausgabe von Meldungen in S-Variablen

Meldungen können in die Systemdateien SYSOUT bzw. SYSLST ausgegeben werden. Das Softwareprodukt SDF-P bietet ergänzend hierzu die Möglichkeit, garantierte Meldungen in strukturierte S-Variablen auszugeben (siehe auch Abschnitt „Garantierte Meldungen").
SDF-P übernimmt dabei die Steuerung des S-Variablenstroms SYSMSG, über den die garantierten Meldungen in S-Variablen umgelenkt werden. Nähere Informationen zum Konzept der strukturierten S-Variablenströmen siehe Handbuch „SDF-P“ [45].
Die Systemkomponente MIP erzeugt die S-Variablen, deren Werte als Eingabedaten in S-Prozeduren weiterverwendet werden können.

Das Bild unten zeigt sowohl die Ausgabe nach SYSOUT durch den Systemdateien-Manager als auch die Umlenkung der Ausgabeinformation in die S-Variablenströme SYSMSG (und SYSINF), welche durch SDF-P gesteuert wird. Weitere Informationen zu SYSINF siehe Handbuch „Kommandos“ [27].

Bild 25: Ausgabe von Meldungen in den S-Variablenstrom SYSMSG und nach SYSOUT

Dem Benutzer erwachsen aus der Verwendung von S-Variablen entscheidende Vorteile:

• Die S-Variablen erlauben einen einfachen Zugriff auf eine garantierte Meldung, da die Information strukturiert abgespeichert ist. Der Anwender ist unabhängig vom Ausgabelayout der Meldung.

• Die Namen der S-Variablen und ihre inhaltliche Zuordnung sind auch in kommenden Subsystemversionen bzw. Versionen von BS2000 OSD/BC garantiert.

• Der Inhalt der S-Variablen kann als Eingabe in S-Prozeduren weiterverwendet werden.

Folgende Angaben sind erforderlich, um garantierte Meldungen in eine strukturierte S-Variable auszugeben:

1. Der Anwender muss eine Listenvariable vom Typ „Struktur“ deklarieren.

   /DECLARE-VARIABLE <var-name>(TYPE=*STRUCTURE),MULTIPLE-ELEMENT=*LIST

2. Der Anwender muss den S-Variablenstrom SYSMSG für die strukturierte Ausgabe in S-Variablen zuweisen. Eine der folgenden Vereinbarungen muss getroffen werden:

   Auf Kommandoebene:

   • Kommando EXECUTE-CMD vereinbart die strukturierte Ausgabe in S-Variablen für ein Kommando.

     /EXEC-CMD (<cmd-name>),MSG-STRUCTURE-OUTPUT=<var-name>

   • Kommando ASSIGN-STREAM; die Zuweisung des S-Variablenstroms ist für alle nachfolgenden Kommandos gültig, solange bis die Vereinbarung wieder zurückgenommen wird (ASSIGN-STREAM SYSMSG,TO=*STD).

     /ASSIGN-STREAM STREAM-NAME=SYSMSG,TO=*VARIABLE(<var-name>)

   Auf Programmebene:

   Der Makro CMD vereinbart die strukturierte Ausgabe in S-Variablen für mehrere Kommandos.

   CMD '<cmd-name>',...,VER=4,MSGVAR@=<adr>,MSGVARL=<len>,[,MSGEXT=YES]

   <adr> ist die symbolische Adresse, die den Namen der S-Variablen enthält. Makro CMD, siehe Handbuch „Makroaufrufe an den Ablaufteil“ [30].

3. Im Makro MSG7X muss das Ziel der Meldungsausgabe vereinbart werden.
   Wird DESTINATION=SYSOUT vereinbart, werden garantierte Meldungen immer in S-Variablen ausgegeben, vorausgesetzt der Benutzer hat eine S-Variable deklariert. Darüber hinaus kann dem Operanden BUFFER ein benutzereigener Speicher und BUFFUSE=EXTERNAL zugewiesen werden.
   Makro MSG7X, siehe Handbuch „Makroaufrufe an den Ablaufteil“ [30].

4. Mit MSGMAKER muss die Meldung folgendermaßen ausgezeichnet werden:

   1. Die auszugebende Meldung muss als garantiert ausgezeichnet sein (//ADD-MSG MSG-ID=...,WARRANTY=YES). Für garantierte Meldungen erzeugt MIP folgende S-Variablen:

      • MSG-ID:
        enthält den Meldungsschlüssel.

      • REPLY:
        enthält die Antwort auf die Meldung, sofern diese vom Benutzer eine Stellungnahme fordert.

      • I0 bis I29:
        Standard-Namen der Inserts; I0 bis I29 werden standardmäßig von MIP als S-Variablennamen vergeben, wenn der Benutzer mit MSGMAKER keine Insertnamen (siehe b)) vereinbart hat.

      • MSG-TEXT:
        enthält den Meldungstext inklusive aller ersetzten Inserts.

   2. Für die Inserts der auszugebenden Meldung werden Namen vereinbart
      (//ADD-MSG MSG-ID=...,INSERT-ATTRIBUTES=...(NAME=...)).
      Ist die Meldung nicht garantiert, wird jedoch mindestens einem Insert der auszugebenden Meldung ein Name zugewiesen, so werden folgende S-Variablen erzeugt:

      • <insert-name>:
        Mit MSGMAKER vereinbarter Name wird in Großbuchstaben umgewandelt und von MIP als S-Variablenname verwendet.

      • MSG-ID:
        enthält den Meldungsschlüssel.

      • REPLY:
        enthält die Antwort auf eine Meldung.

      • MSG-TEXT:
        enthält den Meldungstext inklusive aller ersetzten Inserts.

   Die von MIP erzeugten S-Variablen sind vom Datentyp STRING.

Die endgültige, von MIP ausgegebene S-Variable setzt sich aus zwei Teilnamen zusammen:

• Name der vom Benutzer deklarierten S-Variablen: <var-name>
  (<var-name> ist der erste Teilname der S-Variablen)

• MIP liefert den zweiten Teilnamen (MSG-ID, I0 bis I29, <insert-name>, REPLY, MSG-TEXT)

Die beiden Teilnamen bilden, durch einen Punkt voneinander getrennt, die Namen der S-Variablen

• <var-name>.MSG-ID

• <var-name>.I0 ... <var-name>.I29

• <var-name>.<insert-name>

• <var-name>.REPLY

• <var-name>.MSG-TEXT

Alle Variablen (MSG-ID, I0, ...), die es zu einer garantierten Meldung gibt, gehören einem Listenelement an. Jede weitere Meldung wird als neues Listenelement aufgenommen. Dies ist der Fall, wenn zu einem Kommando mehrere garantierte Meldungen existieren (Aufruf des Kommandos mit /EXECUTE-CMD) oder wenn mit dem Kommando /ASSIGN-STREAM allgemein die Ausgabe garantierter Meldungen in eine S-Variable umgelenkt wird.

Beispiel

Das folgende Beispiel zeigt die Umlenkung der Meldungsausgabe in eine S-Variable.
Die Attribute der nicht existierenden Datei „TEST“ sollen ausgegeben werden. Die dadurch verursachte Fehlermeldung DMS0533, eine garantierte Meldung, wird in die S-Variable MSG ausgegeben:

/DECLARE-VARIABLE NAME=MSG(TYPE=*STRUCTURE(DEFINITION=*DYNAMIC)), 
   MULTIPLE-ELEMENTS=*LIST                                                 1.
/EXECUTE-CMD CMD=(SHOW-FILE-ATTRIBUTES FILE-NAME=TEST),TEXT-OUTPUT=*NONE, 
   MSG-STRUCTURE-OUTPUT=MSG(WRITE-MODE=*EXTEND)                            2.
/SHOW-VAR MSG                                                              3.
MSG(*LIST).MSG-TEXT = %  DMS0533 REQUESTED FILE NOT CATALOGED IN 
   PUBSET '1SBZ'. COMMAND TERMINATED
MSG(*LIST).MSG-ID = DMS0533
MSG(*LIST).I0 = 1SBZ                                                       4.

1. Die S-Variable MSG wird als dynamisch erweiterbare Listenvariable deklariert.

2. Mit dem Kommando /EXECUTE-CMD wird die Ausgabe des Kommandos /SHOW-FILE-ATTRIBUTES in die S-Variable MSG umgelenkt. Die Ausgabe nach SYSOUT wird unterdrückt.

3. Mit SHOW-VAR MSG wird die Listenvariable MSG ausgegeben.

4. MIP erzeugt für diese garantierte Meldung die S-Variablen MSG-TEXT, MSG-ID und I0; die Werte dieser S-Variablen bilden das erste Listenelement der S-Variablen MSG. Wird das Kommando /EXECUTE-CMD wiederholt abgesetzt, wird jede weitere Meldung als neues Listenelement angefügt, da WRITE-MODE=*EXTEND angegeben ist (siehe 2.).