CMDTST Anweisung analysieren

Der Makro CMDTST bewirkt, dass SDF

• eine Programmanweisung, die im Programm selbst abgelegt ist, analysiert und

• das Analyseergebnis an das Programm übergibt.

Bei der Analyse der übergebenen Anweisung können zusätzliche Anweisungen entstehen, indem ein System-Exit die übergebene Anweisung durch mehrere Anweisungen ersetzt. Die Behandlung dieser zusätzlichen Anweisungen liegt in der Verantwortung des Programms.

Voraussetzung ist, dass eine aktivierte Syntaxdatei die Definition des Programms und seiner Anweisungen enthält.

Bild 14: Wirkung des Makros CMDTST

Operation

Operanden

CMDTST

PROGRAM = *NONE / <c-string 1..8> / <var: char:8> ,EXTNAME = *NONE / <c-string 1..8> / <var: char:8> ,INPUT = *NO / <var: pointer> ,OUTPUT = <var: pointer> ,STMT = *ALL / <var: pointer> ,DIALOG = *NO / *YES / *ERROR / <var: enum-of DIALOG_S:1> ,MESSAGE = *NO / <var: pointer> ,PROT = *YES / *NO / <var: bit:1> ,BUFFER = *NO / <var: pointer> ,INVAR = *NO ,DEFAULT = *NO / <var: pointer> ,ERROR = *NO / *YES / <var: bit:1> ,CALLID = *NO / <var: pointer> ,EXECUTE = *NO / *YES / <var: bit:1> ,PROCMOD = *ANY / *NO / *YES / <var: enum-of PROCEDURE_S:1> ,CCSNAME = *NO / *EXTEND / <c-string 1..8> / <var: char:8> ,INPUTSV = *NO / *YES / <var: bit:1> ,OUTFORM = *NEW / *OLD / <var: bit:1> ,DEFDEF = *NO / *YES / <var: bit:1> ,MF = C / D / L / M / E

PROGRAM =
interner Name des Programms, das den Makroaufruf absetzt. In der Syntaxdatei ist dieser Name in der Programmdefinition abgelegt¹⁾ (siehe Anweisung ADD-PROGRAM, Operand INTERNAL-NAME; "ADD-PROGRAM Programm definieren").

*NONE
Der interne Name des Programms wird nicht angegeben. In diesem Fall muss im Operanden EXTNAME der externe Name des Programms angegeben werden.

<c-string 1..8> / <var: char:8>
Der interne Name des Programms wird als C-String-Konstante oder als String-Variable übergeben. Er ist mindestens ein und maximal acht Byte lang.

¹⁾Wird die programmspezifische Syntaxdatei mit CMDTST überhaupt erst zugewiesen, so ist als Programmname CMDEDIT anzugeben.

EXTNAME =

externer Name des Programms, das den Makroaufrauf absetzt. In der Syntaxdatei ist dieser Name in der Programmdefinition abgelegt (siehe Anweisung ADD-PROGRAM,

Operand NAME, "ADD-PROGRAM Programm definieren").

*NONE
Der externe Name des Programms wird nicht angegeben. In diesem Fall muss im Operanden PROGRAM der interne Name des Programms angegeben werden.

<c-string 1..8> / <var: char:8>
Der externe Name des Programms wird als C-String-Konstante oder als String-Variable übergeben. Er ist mindestens ein und maximal acht Byte lang.

INPUT =
bestimmt, welche Anweisung SDF analysieren soll.

*NO
SDF soll keine im Programm abgelegte Anweisung analysieren, sondern eine durch System-Exit zusätzlich bereitgestellte Anweisung.

<var: pointer>
SDF soll die Anweisung analysieren, deren Adresse angegeben ist. Der Bereich mit der angegebenen Adresse muss auf Halbwortgrenze ausgerichtet sein. SDF erwartet die Anweisung in folgendem Format:

2 Byte:	absolute Länge des Bereiches (n+4)
2 Byte:	(reserviert)
n Byte:	Anweisung als Zeichenkette

OUTPUT = <var: pointer>
Adresse des normierten Übergabebereichs, der auf Wortgrenze beginnen muss. Der Übergabebereich wird mit dem Makro CMDTA generiert (oder bei OUTFORM=*OLD mit

CMDSTRUC, siehe Kapitel „Anhang“).

STMT =

bestimmt, welche Anweisungen als Eingabe zulässig sind.
Nur die Anweisungen, deren interner Anweisungsname angegeben ist, sind zulässig. Der interne Anweisungsname ist in der Syntaxdatei in der Anweisungsdefinition abgelegt (siehe ADD-STMT). Er ist mindestens ein und maximal acht Byte lang. Die SDF-Standardanweisungen sind unabhängig von der hier getroffenen Festlegung immer zulässig.

*ALL
Alle Anweisungen sind zulässig.

<var: pointer>
Adresse der Liste der zulässigen Anweisungen. Diese Liste kann mit dem Makro

CMDALLW generiert worden sein.

Die Liste muss auf Halbwortgrenze ausgerichtet und wie folgt aufgebaut sein:

2 Byte:	Anzahl der internen Namen in der Liste (n)
8 Byte:	erster interner Anweisungsname . . .
8 Byte:	n-ter interner Anweisungsname

DIALOG =
bestimmt, ob SDF bei der Anweisungsanalyse einen Dialog führen soll. Dieser Operand ist nur relevant, wenn das Programm in einer interaktiven Task abläuft.

*NO
SDF soll keinen Dialog führen.

*YES
SDF soll die vom Programm übergebene Anweisung dem Benutzer im Dialog zu einer eventuellen Änderung anbieten, soweit das mit den geltenden SDF-Festlegungen für den Dialog verträglich ist (siehe MODIFY-SDF-OPTIONS und SET-GLOBALS).

*ERROR
SDF soll nur beim Erkennen von Syntaxfehlern einen Dialog führen. Falls die Anweisung Semantikfehler enthält, kann das Programm mit CMDCST einen Semantikfehlerdialog anstoßen.

<var: enum-of DIALOG_S:1>
Aufzählungs-Variable, die folgende Werte annehmen kann:

0 :       wie *NO 1 :       wie *YES 2 :       wie *ERROR

MESSAGE =
bestimmt, ob SDF eine Meldung ausgeben soll, wenn dem Benutzer die Anweisung zur Überprüfung und ggf. Änderung angeboten wird (nur relevant für DIALOGî*NO). SDF integriert diese Meldung in den Fragebogen.

*NO
SDF soll keine Meldung ausgeben.

<var: pointer>
Adresse des auszugebenden Meldungstextes, auf Halbwortgrenze ausgerichtet. Der Text wird als Satz variabler Länge erwartet:

2 Byte:	absolute Länge des Satzes (n+4)
2 Byte:	(reserviert)
n Byte:	Meldungstext

Der Meldungstext darf maximal 400 Zeichen lang sein. In SDF-formatierten Bildschirmen werden jedoch nur die ersten 280 Zeichen dargestellt. Enthält der Text Bildschirmsteuerzeichen, so kann die Menü-Maske zerstört werden.

PROT =
bestimmt, ob SDF zu protokollierende Eingaben und Meldungen nach SYSOUT schreibt. Falls nicht nach SYSOUT geschrieben wird, sollte der Benutzer des Programms in der Programmdokumentation darüber informiert werden. Ein Protokollpuffer kann bereitgestellt werden (siehe BUFFER).

*NO
SDF soll keine Protokollierung durchführen.

*YES
SDF soll zu protokollierende Eingaben und Meldungen nach SYSOUT schreiben.

<var: bit:1>

Bitvariable:

bit = 0: wie *NO bit = 1: wie *YES

BUFFER =
Das Protokoll der Anweisung und die Fehlermeldungen können in einen vom Benutzer bereitgestellten Bereich geschrieben werden.

*NO
Es wird kein Puffer bereitgestellt.

<var: pointer>
Adresse eines Bereichs, in dem das Protokoll der angegebenen Anweisung und die Meldungen, unabhängig vom Wert, der bei PROT angegeben wurde, abgelegt wird. Der Bereich muss auf Halbwortgrenze ausgerichtet sein und wird wie folgt belegt:

2 Byte:	maximale Länge des Protokollbereiches
2 Byte:	tatsächlich genutzte Länge des Protokollbereiches
n Byte:	Protokollsätze

Jeder einzelne Protokollsatz hat folgendes Format:

2 Byte:	absolute Länge des Protokollsatzes (m+4)
2 Byte:	(reserviert)
m Byte:	Inhalt des Protokollsatzes

Wenn der Puffer nicht leer ist, ist der erste Datensatz normalerweise das Protokoll des Eingabe-Kommandos. Die weiteren Datensätze enthalten Meldungen. Wenn kein Eingabeprotokoll zur Verfügung steht oder ausgegeben werden kann, wird ein doppelter Schrägstrich („//“) in den Ausgabebereich geschrieben.
Die Ausrichtung der Protokollsätze ist nicht garantiert.

INVAR =
legt fest, ob die INVARIANT-INPUT-Form der Anweisung abgespeichert wird. Das heißt, dass die Anweisung mit allen eingegebenen Operanden, allen durch Default-Werte vorbelegten Operanden und mit allen Operandenwerten abgelegt wird, die für die Task zu dieser Zeit erlaubt sind. Die INVARIANT-INPUT-Form ist damit die größtmögliche Eingabeform für eine Anweisung, die für einen Benutzer mit bestimmten Privilegien und im gewählten Dialogmodus zulässig ist. Im Gegensatz zur Protokollierungsform LOGGING=*INVARIANT-FORM (Anweisung MODIFY-SDF-OPTIONS) werden Kennwörter und geheime Operanden jedoch nicht ausgeblendet.

*NO
Die INVARIANT-INPUT-Form der Anweisung wird nicht abgespeichert.

<var: pointer>
gibt die Adresse eines Puffers an, in den SDF die INVARIANT-INPUT-Form der Anweisung schreibt. Der Puffer muss auf Wortgrenze ausgerichtet sein und das erste Halbwort muss die Länge des Puffers enthalten. SDF legt die INVARIANT-INPUT-Form ab dem zweiten Halbwort als Satz mit variabler Satzlänge ab.
Der Puffer hat dann folgenden Inhalt:

2 Byte:	maximale Länge des Puffers
2 Byte:	Ausgabelänge, die SDF schreibt (n+4)
2 Byte:	(reserviert)
n Byte:	INVARIANT-INPUT-Form der Anweisung, ab 7. Byte

DEFAULT =
bestimmt, ob SDF folgende Werte durch vom Programm dynamisch erzeugte Werte ersetzt:

• eingegebene Operandenwerte oder

• Default-Werte der Operanden

In der Syntaxdatei müssen die Operanden bzw. Operandenwerte entsprechend definiert sein (siehe ADD-OPERAND...,OVERWRITE-POSSIBLE=*YES),... bzw. ADD-VALUE..., VALUE=<c-string> (OVERWRITE-POSSIBLE=*YES),...). Der vom Programm erzeugte Default-Wert muss gültiger Operandenwert sein.
Im geführten Dialog zeigt SDF die vom Programm erzeugten Werte im Fragebogen.

Beispiel:

SDF ersetzt in den eingegebenen MODIFY-Anweisungen den Wert *UNCHANGED durch den aktuellen Wert.

*NO
SDF soll die eingegebenen Operandenwerte nicht durch vom Programm dynamisch erzeugte Werte ersetzen.

<var: pointer>
Adresse einer auf Wortgrenze ausgerichteten Liste, die Adressen von Umsetzbeschreibungen für Anweisungen enthält. Als Umsetzbeschreibung wird ein formatierter Übergabebereich mit dem Typ 'Struktur' verwendet (siehe Abschnitt „Aufbau des normiertenÜbergabebereichs“). Je Anweisung kann nur eine Umsetzbeschreibung angegeben werden. Eine Umsetzbeschreibung enthält u.a. den internen Anweisungsnamen und die Information, welche Operanden mit welchen Werten zu belegen sind. Die Liste der Adressen von Umsetzbeschreibungen ist wie folgt aufgebaut:

2 Byte:	Anzahl der Umsetzbeschreibungen in der Liste (n)
2 Byte:	(reserviert)
4 Byte:	Adresse der ersten Umsetzbeschreibung . . .
4 Byte:	Adresse der n-ten Umsetzbeschreibung

Die Bereiche für die Umsetzbeschreibungen, die für die Default-Werte des Programms übergeben werden, müssen auf Wortgrenze ausgerichtet sein. Dies gilt ebenso für den Ausgabebereich der Makros (OUTPUT-Operand).

Stehen die zu defaultierenden Operanden in einer Struktur, deren Einleiter mit LIST-ALLOWED=*YES definiert ist (siehe ADD-VALUE), so kann folgender Fall eintreten: Die Umsetzbeschreibung enthält mehrere Listenelemente, an denen eine Struktur mit zu defaultierenden Operanden hängt. Auf der anderen Seite gibt der Anwender ebenfalls mehrere Listenelemente ein, an denen eine Struktur mit zu defaultierenden Operanden hängt. SDF versucht zunächst, die vom Benutzer eingegebenen und die in der Umsetzbeschreibung angegebenen Strukturen einander über den Wert des Struktureinleiters zuzuordnen. Ist über den struktureinleitenden Wert keine eindeutige

Zuordnung möglich, weil keiner der eingegebenen Werte mit denen in der Umsetzbeschreibung übereinstimmt oder weil der Benutzer den übereinstimmenden Wert mehrfach eingegeben hat, so erfolgt die Zuordnung über die Position des Struktureinleiters in der Liste.

ERROR =
bestimmt, wie der beim Operanden MESSAGE angegebene Meldungstext ausgegeben wird.

*NO
SDF soll den Meldungstext als Meldung ausgeben.

*YES
SDF soll den Meldungstext als Fehlermeldung ausgeben.

<var: bit:1>

Bitvariable:

bit = 0: wie *NO bit = 1: wie *YES

CALLID =
bestimmt, welcher Kontext von SDF benutzt wird, um das Kommando zu analysieren. CALLID benennt den Programmkontext (= Syntaxdateihierarchie, durch einen OPNCALL-Makro eröffnet), in dem die Anweisung analysiert werden muss.

*NO
Die gegenwärtig aktivierte Syntaxdateihierarchie wird verwendet.

<var: pointer>
Adresse eines 4 Byte langen Feldes, das auf Wortgrenze ausgerichtet ist. Der Aufrufende übermittelt darin die CALLID des Kontextes, den er verwenden will.

EXECUTE = *NO / *YES / <var: bit:1>
bestimmt, ob SDF-Standardanweisungen ausgeführt werden. EXECUTE ist ohne Bedeutung, wenn der CMDTST-Makro keinen Bezug auf eine neue Syntaxdateihierarchie nimmt (CALLID=*NO), z.B. wenn die aktuelle Syntaxdateihierarchie verwendet wird. Dann werden die SDF-Standardanweisungen immer von CMDTST ausgeführt (vorausgesetzt, sie sind in der aktuellen Syntaxdateihierarchie vorhanden). Der Operand gehört zum multihierarchischen Merkmal, das mit dem vorangehenden Operanden CALLID eingeleitet wird. Bezieht sich CMDTST auf eine parallel eröffnete Syntaxdateihierarchie (CALLID=<var: pointer>), werden die SDF-Standardanweisungen bei EXECUTE=*YES ausgeführt.

<var: bit:1>

Bitvariable:

bit = 0: wie *NO bit = 1: wie *YES

PROCMOD =
bestimmt, in welcher Umgebung der Benutzer arbeitet. SDF führt eine Prüfung durch: Anweisungen, die in der angegebenen Umgebung nicht erlaubt sind, werden von SDF nicht akzeptiert. Der Operand nimmt Bezug auf die Möglichkeit, mehrerere Syntaxdateihierarchien zu eröffnen. Er ist nur von Bedeutung, wenn der Makro-Aufruf sich auf eine neue Syntaxdateihierarchie bezieht, die zusätzlich zur aktuellen eröffnet wurde.
Ist keine CALLID bestimmt (CALLID=*NO), dann hat PROCMOD keine Bedeutung, d.h der Wert *ANY wird automatisch gesetzt und auf den aktuellen Prozedurmodus Bezug genommen.

*ANY
Es wird keine Überprüfung vorgenommen. Die Anweisungen werden immer analysiert.

*YES
Anweisungen werden so behandelt, als würden sie aus einer Prozedurdatei gelesen. Sie werden analysiert, wenn sie in der Syntaxdatei mit DIALOG-PROC-ALLOWED= *YES definiert sind und wenn das Programm im Dialog arbeitet, oder bei BATCH-PROC-ALLOWED=*YES in Stapelaufträgen.

*NO
Anweisungen werden so behandelt, als würden sie von einer Hauptebene (primary level) gelesen, z.B. von der Bildschirmeingabe oder aus einem Stapelauftrag. Sie werden analysiert, wenn sie in der Syntaxdatei mit DIALOG-ALLOWED=*YES definiert wurden und wenn das Programm im Dialog läuft, oder bei BATCH-ALLOWED=*YES in Stapelaufträgen.

<var: enum-of PROCEDURE_S:1>
Aufzählungs-Variable, die folgende Werte annehmen kann:

0 :       wie *ANY 1 :       wie *YES 2 :       wie *NO

CCSNAME =
Gibt den Namen des Zeichensatzes an, der für den Korrekturdialog auf 8-bit-Terminals und für die Konvertierung von Klein- in Großbuchstaben verwendet wird. Jedes Terminal arbeitet mit einem bestimmten Zeichensatz. Ein codierter Zeichensatz (CCS, Coded Character Set) ist die eindeutige Darstellung der Zeichen eines Zeichensatzes in binärer Form. Jeder codierte Zeichensatz wird durch seinen Namen (Coded Character Set Name, CCSN) bestimmt (siehe Handbuch „XHCS“ [11]). Die Ausgabe von Meldungen wird durch diesen Parameter nicht beeinflusst.

*NO
Der 7-bit-Standard-Code wird für Ein-/Ausgabeoperationen verwendet.

*EXTEND
Der 8-bit-Standard-Code wird für Ein-/Ausgabeoperationen verwendet.

<c-string 1..8> / <var: char:8>
Gibt den Namen eines speziellen 8-bit-Code an, der für Ein-/Ausgabeoperationen verwendet wird. Der Name muss 8 Byte lang sein und kann als C-String-Konstante oder als String-Variable übergeben werden.

INPUTSV =
gibt an, ob die letzten Eingaben in einer Liste gespeichert werden. Auf diese Liste kann mit Hilfe eines RESTORE-Mechanimus erneut zugegriffen werden (Anweisungen MODIFY-SDF-OPTIONS und RESTORE-SDF-INPUT).

*NO
Die Eingaben werden nicht gespeichert.

*YES
Die Eingaben werden in einem Puffer gespeichert.

<var: bit:1>

Bitvariable:

bit = 0: wie *NO bit = 1: wie *YES

OUTFORM =
Legt fest, welches Format des normierten Übergabebereiches SDF ausgibt. Bei der Angabe von Default-Werten (siehe Parameter DEFAULT) identifiziert SDF das Format des Übergabebereiches selbst.

*NEW

Der normierte Übergabebereich hat das neue Format (siehe Aufbau des normierten Übergabebereichs).

*OLD
Der Übergabebereich hat das bis SDF V4.0 verwendete Format (siehe Kapitel„Anhang“).

<var: bit:1>

Bitvariable:

bit = 0: wie *NEW bit = 1: wie *OLD

DEFDEF =
legt fest, ob Anweisungen zum Setzen taskspezifischer Default-Werte eingegeben werden

dürfen (siehe Benutzerhandbuch „Einführung in die Dialogschnittstelle SDF“ [1]).

*NO
Anweisungen zum Setzen taskspezifischer Default-Werte werden nicht akzeptiert.

*YES
Anweisungen zum Setzen taskspezifischer Default-Werte werden akzeptiert.

<var: bit:1>

Bitvariable:

bit = 0: wie *NO bit = 1: wie *YES

Beschreibung der Parameter MF, PARAM, MACID und PREFIX siehe Benutzerhandbuch „Makroaufrufe an den Ablaufteil“ [8].

Rückinformation und Fehleranzeigen

Der Aufbau des Übergabebereichs ist auf denAufbau des normierten Übergabebereichs beschrieben. Das bis SDF V4.0 verwendete Format des Übergabebereiches finden Sie im Kapitel „Anhang“.

Mehr zur INVARIANT-INPUT-Form der Ausgabe finden Sie beim Makro CMDRST auf "CMDRST Anweisung lesen und analysieren".

Der Returncode wird im Standardheader der Parameterliste übergeben.

Standardheader

cc: Subcode 2 (SC2) bb: Subcode 1 (SC1) aaaa: Maincode

(SC2)	SC1	Maincode	Bedeutung
	00	0000	erfolgreiche Beendigung:
00			keine Besonderheiten
01			Programm lieferte Default-Werte
00	20	0004	nicht behebbarer Systemfehler
	01	0008	Parameterfehler:
00			falsche Parameterliste
01			OUTPUT
02			STMT-liste
03			DEFAULT
04			MESSAGE
05			PROT
06			INVAR
07			CALLID
09			INPUT
00	40	000C	Übergabebereich zu klein
00	40	0018	Anweisung ist zwar in Ordnung, die vom Programm übergebenen Default-Werte sind jedoch fehlerhaft
00	40	001C	Anweisung fehlerhaft
00	40	0020	Fehlerdialog nicht möglich
00	40	0024	Fehlerdialog vom Benutzer abgelehnt
00	40	0028	Puffer zu klein, Protokoll abgeschnitten
00	40	002C	END-Anweisung wurde gelesen
00	40	003C	Programm nicht in Syntaxdatei bekannt
00	40	0040	angegebene CALLID nicht gefunden
00	40	0044	im DSSM-Katalog eingetragene Syntaxdatei nicht gefunden
00	40	005C	INVAR-Puffer zu klein, INVARIANT-INPUT abgeschnitten
00	40	0064	XHCS-Fehler bei Anweisungseingabe
00	40	006C	Anweisung zum Setzen taskspezifischer Defaults wurde an Stelle normaler Anweisung eingegeben

Indikator für zusätzliche Anweisungen (durch System-Exit):

Bei fehlerfreier Parameterliste wird ein Indikator für zusätzlich generierte Anweisungen im Feld <prefix><macid>EXIT_ACTIVE der Parameterliste abgelegt.

Folgende Werte können auftreten:

Wert	Bedeutung
X’00’ X’01’	es existieren keine weiteren Anweisungen es existieren weitere Anweisungen

Migration von TRSTMT zu CMDTST

Die Migration von TRSTMT nach CMDTST ist nur dann notwendig, wenn Sie die neue Funktionalität von CMDTST nutzen wollen. Dabei sind dieselben Punkte wie bei CMDRST zu beachten (siehe „Migration von RDSTMT zu CMDRST“ (CMDRST Anweisung lesen und analysieren)). Zusätzlich dazu gibt es folgende Änderungen:

TRSTMT                                                    CMDTST

PROT  = YES/NO/addr/(r)            PROT = *YES/*NO 
                                   BUFFER = *NO/identifier 
INPUTSAV = NO/YES                  INPUTSV = *NO/*YES  (umbenannt!)

Der Makro-Returncode wird im Standardheader der Parameterliste übergeben. Der Maincode von CMDTST entspricht den Werten, die bei TRSTMT im rechtsbündigen Byte im Register 15 übergeben wurden. Die Erzeugung von EQUATES für Returncodes mit dem Makro CMDANALY ist nicht mehr notwendig, da diese mit CMDTST MF=D automatisch erzeugt werden. Im Folgenden finden Sie eine Gegenüberstellung der alten (TRSTMT-) und

neuen (CMDTST-)Feldnamen:

TRSTMT

CMDTST

&P.NOERR &P.SYERR &P.PAERR &P.TRUNC &P.CERR &P.DFLT &P.DIMP &P.DREJ &P.PTRC &P.END &P.NOPRG &P.INCID &P.NOFND &P.ITRC &P.XHCS

&PREFIX.MDTSUCCESSFUL &PREFIX.MDTSYSTEM_ERROR &PREFIX.MDTPARAMETER_ERROR &PREFIX.MDTAREA_TOO_SMALL &PREFIX.MDTERROR_IN_STMT &PREFIX.MDTWRONG_DEFAULTS &PREFIX.MDTDIALOG_IMPOSSIBLE &PREFIX.MDTDIALOG_REJECTED &PREFIX.MDTPROTOCOL_TRUNCATION &PREFIX.MDTEND_STMT &PREFIX.MDTPROGRAM_NOT_IN_SYNTAX_FILE &PREFIX.MDTINVALID_CALLID &PREFIX.MDTSYNTAX_FILE_NOT_FOUND &PREFIX.MDTINVARIANT_INPUT_TRUNCATED &PREFIX.MDTXHCS_ERROR