Mit dem Makro TRCMD übergibt der Aufrufer ein Kommando als Zeichenkette an SDF. SDF analysiert dieses Kommando und generiert daraus ein Protokoll, die INVARIANT-INPUT-Form oder ACCEPTED-INPUT-Form sowie die interne Form.
Die interne Form (auch „konvertierte Form“ genannt) ist genau die Information, die zum Aufruf des Kommando-Servers und damit zur Ausführung des Kommandos notwendig ist. Die interne Form ist entweder eine Zeichenkette oder ein normierter Übergabebereich, abhängig davon, wie das Kommando in der Syntaxdatei definiert ist.
SDF übergibt an das Programm auch das Ergebnis der Syntaxanalyse.
In Dialogaufträgen kann ein Fehlerdialog zur Korrektur des Kommandos geführt werden.
Die INVARIANT-INPUT-Form der Anweisung enthält alle eingegebenen Operanden, alle durch Default-Werte vorbelegten Operanden und alle Operandenwerte, die für die Task zu dieser Zeit erlaubt sind (siehe auch CMDRST, "CMDRST Anweisung lesen und analysieren").
Die ACCEPTED-INPUT-Form enthält alle Namen in ihrer Langform, jeden eingegebenen Operanden mit seinem Namen und seinem Wert sowie ggf. Korrekturen. Da in der ACCEPTED-INPUT-Form keine Abkürzungen vorkommen, ist deren Eindeutigkeit auch für spätere BS2000-Versionen gewährleistet. Kennwörter und geheime Operanden sind nicht ausgeblendet.
Operation | Operanden | |||||||
TRCMD | INPUT = *NO / addr / (r) ,OUTPUT = *NO / addr / (r) ,CMD = *ALL / (name,...) ,DIALOG = NO / YES / ERROR ,MESSAGE = *NO / addr / (r) ,ERROR = NO / YES ,PROT = *YES / *NO / addr / (r) ,MEMORY = ACTUAL / BASIC ,CALLINF = *NO / addr / (r) ,EXIT = YES / NO ,CALLID = *NO / addr / (r) ,EXECUTE = NO / YES ,PROCMOD = ANY / YES / NO / ALL ,CHKPRV = *YES / *NO / addr ,DUMESC = NO / YES ,OVERLNG = NO / YES ,SETVAR = NO / YES ,INVAR = *NO / addr / (r) ,ACCEPT = *NO / addr / (r) ,DEFDEF = NO / YES
|
INPUT =
bestimmt, welches Kommando SDF analysieren soll.
Die Angabe des Parameters ist Pflicht.
*NO
SDF soll kein im Programm abgelegtes Kommando analysieren, sondern das erste der durch System-Exit generierten Kommandos. Alle weiteren durch System-Exit generierten Kommandos können durch wiederholten Aufruf von TRCMD mit INPUT=*NO angefordert werden.
addr / (r)
SDF soll das Kommando analysieren, dessen Adresse angegeben ist bzw. in dem angegebenen Register steht. SDF erwartet die Kommandozeichenkette als Satz variabler Länge im üblichen BS2000-Format. Der Satzbereich muss auf Halbwortgrenze ausgerichtet sein.
OUTPUT =
bestimmt, ob die interne Form des Kommandos erzeugt wird.
Die Angabe des Parameters ist Pflicht.
*NO
Die interne Form des Kommandos wird nicht generiert. Die Syntax des bei INPUT angegebenen Kommandos wird geprüft.
addr / (r)
Adresse eines Bereiches, in dem SDF die interne Form ablegt, bzw. Register, das diese Adresse enthält. Die interne Form kann vom Kommando-Server verarbeitet werden. In Abhängigkeit von der Kommandodefinition in der Syntaxdatei ist die interne Form entweder:
eine Zeichenkette (siehe Anweisung ADD-CMD ...,IMPLEMENTOR=*STRING/*PROCEDURE...) oder
ein normierter Übergabebereich (siehe Anweisung ADD-CMD ...,IMPLEMENTOR= *NEW/*TRANSFER-AREA...).
Der Bereich muss auf Wortgrenze beginnen. Das Programm muss vor dem Aufruf von TRCMD dafür sorgen, dass im ersten Halbwort des Bereichs die maximal mögliche Bereichslänge steht.
CMD =
bestimmt, welche Kommandos als Eingabe erlaubt sind.
*ALL
Alle Kommandos der aktuellen Syntaxdatei-Hierarchie sind erlaubt.
(name,...)
Nur die Kommandos sind erlaubt, deren RESULT-INTERNAL-NAMEs angegeben sind. Der RESULT-INTERNAL-NAME ist in der Syntaxdatei in der Kommandodefinition abgelegt (siehe Anweisung ADD-CMD). Die hier angegebenen Namen müssen vom Datentyp <alphanum-name 1..8> sein.
DIALOG =
bestimmt, ob SDF bei der Kommandoanalyse 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 das vom Programm übergebene Kommando 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.
MESSAGE =
bestimmt, ob SDF eine Meldung auf SYSOUT ausgeben soll, wenn dem Benutzer das Kommando 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.
addr / (r)
Adresse des auszugebenden Meldungstextes (auf Halbwortgrenze ausgerichtet) bzw. Register, das diese Adresse enthält. Der Text wird als Satz variabler Länge erwartet, die maximale Länge beträgt 400 Zeichen. Im geführten Dialog werden jedoch nur die ersten 280 Zeichen dargestellt. Das erste Byte des Meldungstextes interpretiert SDF als Druckersteuerzeichen. Enthält der Text Bildschirmsteuerzeichen, so kann die Menü-Maske zerstört werden.
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.
PROT =
Steuert die Protokollausgabe für das eingegebene Kommando.
*YES
SDF soll die Protokoll-Form nach SYSOUT schreiben.
*NO
SDF soll keine Protokoll-Form ausgeben.
addr / (r)
Adresse eines Protokollpuffers (auf Halbwortgrenze ausgerichtet) oder Register, das die Adresse enthält. SDF soll die Protokoll-Form des Kommandos und Meldungen nur in diesen Puffer schreiben, nicht nach SYSOUT. Die Länge des Puffers steht im ersten Halbwort des Puffers. Im zweiten Halbwort steht die tatsächlich belegte Pufferlänge. Danach folgen die Protokollsätze mit variabler Satzlänge.
Wenn der Puffer nicht leer ist, ist der erste Satz normalerweise das Protokoll des Ein-gabe-Kommandos. Die weiteren Sätze enthalten Meldungen aller Art. Wenn kein Eingabeprotokoll zur Verfügung steht oder ausgegeben werden kann, wird ein Schrägstrich (’/’) in den Ausgabebereich geschrieben.
MEMORY =
Legt fest, ob die Definition des Kommandos aus der aktuellen Syntaxdatei-Hierarchie oder nur aus der Basis-Systemsyntaxdatei gelesen werden soll.
ACTUAL
Das Kommando wird in der aktuellen Syntaxdatei-Hierarchie analysiert.
BASIC
Nur die Kommandodefinition in der Basis-Systemsyntaxdatei wird zur Analyse herangezogen. Definitionen aus einer Gruppen- oder Benutzersyntaxdatei werden nicht beachtet.
CALLINF =
Bestimmt, ob eine Aufruf-Information für den Kommando-Server generiert wird. Wenn SDF die Kommandos MODIFY-SDF-OPTIONS und SHOW-SDF-OPTIONS ausführen soll, muss diese Aufruf-Information vom Programm übergeben werden.
CALLINF = *NO
Die Aufruf-Information wird nicht generiert. Es wird kein SDF-Kommando ausgeführt.
CALLINF = addr / (r)
Adresse eines Bereiches, der 102 Byte lang und auf Halbwortgrenze ausgerichtet ist, bzw. Register, das diese Adresse enthält. SDF legt darin die Aufruf-Information zum eingegebenen Kommando ab.
EXIT = YES / NO
Bestimmt, ob System-Exits (80/81) zur Analyse des Eingabe-Kommandos aufgerufen werden.
CALLID =
bestimmt, in welchem Kontext SDF das Kommando analysiert.
*NO
Die gegenwärtig aktivierte Syntaxdateihierarchie wird verwendet (der Systemkontext).
addr / (r)
Adresse eines 4 Byte langen Feldes (auf Wortgrenze ausgerichtet) oder Register, das diese Adresse enthält. Der Aufrufer übermittelt darin die CALLID des Programmkontextes, den er verwenden will.
Die CALLID des Programmkontextes wird von einem vorangegangenen OPNCALL-Aufruf geliefert. Bei OPNCALL kann auch der Eingabemodus der Task festgelegt werden (Parameter TASKTYP).
EXECUTE = NO / YES
bestimmt, ob die Kommandos SHOW-SDF-OPTIONS und MODIFY-SDF-OPTIONS ausgeführt werden. Voraussetzung dafür ist, dass bei CALLINF die Aufruf-Information für das Kommando übergeben wird. EXECUTE ist ohne Bedeutung, wenn sich TRCMD nicht auf den Programmkontext, sondern auf den Systemkontext bezieht (d.h. bei CALLID=*NO). Die Kommandos werden dann immer von TRCMD ausgeführt.
PROCMOD =
bestimmt, in welcher Umgebung der Benutzer arbeitet. SDF führt eine Prüfung durch: Kommandos, die in der angegebenen Umgebung nicht erlaubt sind, werden von SDF nicht akzeptiert. Der Operand nimmt Bezug auf die Möglichkeit, mehrere 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. Bei CALLID=*NO hat PROCMOD keine Bedeutung, d.h. der Wert ANY wird automatisch gesetzt und es gilt der aktuelle Prozedurmodus. Weitere Hinweise zum PROCMOD-Parameter siehe Makro
OPNCALL, Parameter TASKTYP=ALL ("OPNCALL Programmkontext erstellen").
ANY
Es wird keine Überprüfung vorgenommen.
YES
Kommandos werden so behandelt, als würden sie aus einer Prozedurdatei gelesen. D.h. 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
Kommandos 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.
ALL
Kommandos werden auf alle Prozedurmodi geprüft. In Abhängigkeit des Parameters TASKTYP beim Makro OPNCALL ergibt sich daraus folgendes Verhalten:
bei TASKTYP=ANY:
Jedes Kommando wird als nicht zulässig betrachtet und abgelehnt (unzulässige Parameterkombination)bei TASKTYP=BATCH:
Das Kommando wird analysiert, wenn es in der Syntaxdatei mit BATCH-ALLOWED=*YES oder BATCH-PROC-ALLOWED=*YES definiert ist.bei TASKTYP=TERMINAL:
Das Kommando wird analysiert, wenn es in der Syntaxdatei mit DIALOG-ALLOWED=*YES oder DIALOG-PROC-ALLOWED=*YES definiert ist.
CHKPRV =
Bestimmt, ob SDF die Privilegien des Kommandos prüft. Der Parameter ist nur im Programmkontext von Bedeutung (d.h. bei CALLIDî*NO).
*YES
Die Privilegien werden in Abhängigkeit vom erlaubten Eingabemodus geprüft (TRCMD PROCMOD=..., OPNCALL TASKTYP=...).
*NO
Die Privilegien des Kommandos werden nicht geprüft. Das Kommando wird nicht ausgeführt, d.h. es gilt immer EXECUTE=NO.
addr
Adresse eines 8 Byte langen Bereiches, in dem eine 64-Bit-Privilegienmaske abgelegt ist. Gegen diese Privilegienmaske wird geprüft, ob das Kommando in einem bestimmten Eingabemodus erlaubt ist. Die Reihenfolge der Privilegien in der Bitmaske entspricht der Reihenfolge, in der die Privilegien aktuell im System definiert sind. Diese Privilegienmasken werden u.a. auch mit der SDF-I-Anweisung SHOW-SYNTAX-FILE
ausgegeben (siehe Handbuch „SDF-Verwaltung“ [2]).
DUMESC =
Legt fest, ob Ausdrucksersetzungen, die mit einem Escape-Zeichen beginnen, als Teil des Kommandos betrachtet oder ignoriert werden. Ausdrucksersetzungen werden üblicherweise in der Form '&proc-parameter' bzw. '&(ausdruck)' angegeben.
NO
Ausdrucksersetzungen werden von SDF als Teil des Kommandos betrachtet und syntaktisch auch so analysiert. In den meisten Fällen (außer bei <text> und <cmd-rest>) wird SDF deshalb Syntaxfehler melden.
YES
Ausdrucksersetzungen, die mit dem Escape-Zeichen beginnen, werden von SDF nicht syntaktisch analysiert. Das Schüsselwort BY-AND wird ebenfalls ignoriert.
OVERLNG =
Bestimmt, ob SDF das Längenfeld des bei OUTPUT angegebenen Bereiches (erstes Halbwort) mit der tatsächlichen Länge der internen Form (ISP-Zeichenkette oder normierter Übergabebereich) überschreiben soll. Das geschieht jedoch nur bei erfolgreichem Funktionsaufruf und wenn der OUTPUT-Bereich nicht zu kurz ist.
NO
Das Längenfeld des OUTPUT-Bereiches wird nicht überschrieben.
YES
Das Längenfeld wird bei erfolgreichem Funktionsaufruf mit der tatsächlichen Länge (einschließlich Längenfeld) der internen Kommando-Form überschrieben.
SETVAR =
Legt fest, ob das Kommando eine Zuweisung der Form '<variable-name>=wert' sein kann, wenn es in einer S-Prozedur eingegeben wurde. In Nicht-S-Prozeduren kann es dabei zu Konflikten mit zulässigen ISP-Eingaben für /REMARK, /TYPE, /PAUSE usw. kommen.
NO
Gleichheitsszeichen werden als Teil der Operandenliste des Kommandos betrachtet. Aus Kompatibilitätsgründen ist NO Voreinstellung.
YES
Gleichungen werden als Variablenzuweisung interpretiert. Als Kommandoname wird standardmäßig /SET-VARIABLE verwendet. Wenn dieses Kommando in der Syntax-datei-Hierarchie nicht definiert ist, wird das eingegebene Kommando mit einer entsprechenden Fehlermeldung abgewiesen. Wenn SDF die Variablenzuweisung erfolgreich identifizieren konnte, werden die geforderten Ausgaben anhand der Kommandodefinition von SET-VARIABLE gebildet.
INVAR =
Legt fest, ob die INVARIANT-INPUT-Form des Kommandos 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 in Abhängigkeit vom Eingabemodus und von den Privilegien erlaubt sind:
Der Eingabemodus (Parameter PROCMOD) wird nur geprüft, wenn auch CALLID angegeben wurde. Die Abhängigkeiten zwischen CALLID und PROCMOD sind beim Parameter PROCMOD beschrieben.
Die Privilegien bei CHKPRV werden nur beachtet, wenn auch CALLID angegeben wird. Ohne die Angabe einer CALLID verwendet TRCMD die aktuellen Task-Privilegien.
Kennwörter und geheime Operanden werden nicht ausgeblendet.
INVAR darf nicht zusammen mit ACCEPT angegeben werden.
*NO
Die INVARIANT-INPUT-Form der Anweisung wird nicht abgespeichert.
INVAR = addr / (r)
Gibt die Adresse eines auf Wortgrenze ausgerichteten Puffers an, in den SDF die INVARIANT-INPUT-Form des Kommandos schreibt. Das erste Halbwort muss die Länge des Puffers enthalten. Falls der Puffer zu kurz ist, wird ein entsprechender Makro-Returncode zurückgegeben. 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 2 Byte 2 Byte
buflen | reclen | filler | invariant-input |
buflen: Länge des Puffers
reclen: Länge des Satzes, den SDF schreibt
filler: Füllzeichen
invariant-input: INVARIANT-INPUT-Form des Kommandos, beginnt beim 7. Byte.
ACCEPT =
Legt fest, ob die ACCEPTED-INPUT-Form des Kommandos abgespeichert wird. Die ACCEPTED-INPUT-Form enthält alle Namen in ihrer Langform und alle eingegebenen Operanden mit ihren Namen und Werten, die für die Task in Abhängigkeit vom Eingabemodus und von den Privilegien erlaubt sind:
Der Eingabemodus (Parameter PROCMOD) wird nur geprüft, wenn auch CALLID angegeben wurde. Die Abhängigkeiten zwischen CALLID und PROCMOD sind beim Parameter PROCMOD beschrieben.
Die Privilegien bei CHKPRV werden nur beachtet, wenn auch CALLID angegeben wird. Ohne die Angabe einer CALLID verwendet TRCMD die aktuellen Task-Privilegien.
Kennwörter und geheime Operanden werden nicht ausgeblendet.
ACCEPT darf nicht zusammen mit INVAR angegeben werden.
ACCEPT = *NO
Die ACCEPTED-INPUT-Form der Anweisung wird nicht abgespeichert.
ACCEPT = addr / (r)
Gibt die Adresse eines auf Wortgrenze ausgerichteten Puffers an, in den SDF die ACCEPTED-INPUT-Form des Kommandos schreibt. Das erste Halbwort muss die Länge des Puffers enthalten. Falls der Puffer zu kurz ist, wird ein entsprechender Makro-Returncode zurückgegeben. SDF legt die ACCEPTED-INPUT-Form ab dem zweiten Halbwort als Satz mit variabler Satzlänge ab.
Der Puffer hat dann folgenden Inhalt:
2 Byte 2 Byte 2 Byte 7Byte
buflen | reclen | filler | accepted-input |
| buflen: | Länge des Puffers |
| reclen: | Länge des Satzes, den SDF schreibt |
| filler: | Füllzeichen |
| accepted-input: | ACCEPTED-INPUT-Form des Kommandos, beginnt beim 7. Byte. |
DEFDEF =
legt fest, ob Kommandos zum Setzen taskspezifischer Default-Werte eingegeben werden
dürfen (siehe Benutzerhandbuch „Einführung in die Dialogschnittstelle SDF“ [1]).
NO
Kommandos zum Setzen taskspezifischer Default-Werte werden nicht akzeptiert.
YES
Kommandos zum Setzen taskspezifischer Default-Werte werden akzeptiert. Die gesetzten Default-Werte sind solange gültig, bis sie explizit zurückgesetzt werden. SDF übergibt einen speziellen Returncode, wenn es eine Default-Wert-Definition erkennt, und ignoriert in diesem Fall die Ausgabe-Parameter. Bei Syntaxfehlern wird der dafür übliche Returncode zurückgegeben.
MF =
definiert besondere Anforderungen an die Makroauflösung (siehe Benutzerhandbuch
„Makroaufrufe an den Ablaufteil“ [8]).
L
Es wird nur der Datenteil der Makroauflösung (Operandenliste) generiert. Das erfordert, dass im Makroaufruf keine Operandentypen mit ausführbarem Code auftreten. Der generierte Datenteil hat die im Namensfeld des Makroaufrufs angegebene Adresse.
(E,(1)) / (E,opadr)
Es wird nur der Befehlsteil der Makroauflösung generiert. Auf den zugehörigen Datenteil (Operandenliste) wird mit der Adresse „opadr“ verwiesen. Diese steht entweder in Register 1 oder wird direkt angegeben.
Rückinformation und Fehleranzeigen
Der Aufbau des Übergabebereichs ist auf den Aufbau des normierten Übergabebereichs beschrieben.
Register 15 enthält im rechtsbündigen Byte einen Returncode:
X’00’ X’04’ X’08’ X’0C’ X’10’ X’1C’ X’20’ X’24’ X’28’ X’30’ X’38’ X’44’ X’48’ X’5C’ X’6C’ X’70’ | normale Beendigung; das Kommando ist syntaktisch korrekt nicht behebbarer Systemfehler Operandenfehler im Makroaufruf Übergabebereich zu klein EOF erkannt Kommando fehlerhaft oder unbekannt Fehlerdialog nicht möglich Fehlerdialog wurde abgelehnt Fehler- oder Protokollbereich zu klein Timeout SDF ist nicht verfügbar Syntaxdatei nicht gefunden SDF-Kommando ausgeführt INVAR-Puffer zu klein, INVARIANT-INPUT abgeschnitten Kommando zum Setzen taskspezifischer Default-Werte erkannt übergebene Zeichenkette ist leer |
Indikator für zusätzliche Kommandos (durch System-Exit):
Wenn durch System-Exit eine 1:n-Umsetzung des eingegebenen Kommandos stattgefunden hat, zeigt das Flag FURTH in der Aufruf-Information (CALLINF) an, dass weitere Kommandos mit TRCMD INPUT=*NO angefordert werden können.