Allgemeines
Anwendungsgebiet: | Kommando aufrufen; siehe "Makroaufrufe an den Kommandosprachübersetzer", Kommunikation; siehe "Kommunikation (Programm, Anwender, System)" |
Makrotyp: | S-Typ, MF-Format 1: Standardform/L-/D-/C-/E-Form; siehe "S-Typ-Makroaufrufe" |
Makrobeschreibung
Der Makro CMD ermöglicht den Aufruf eines Kommandos bzw. einer Liste von Kommandos im Programmodus. Der Makro CMD ruft den MCLP (Macro Command Language Processor) auf und übergibt an diesen den Kommandonamen und die angegebenen Kommandooperanden bzw. eine Liste von Kommandonamen und die zugehörigen Kommandooperanden. Nach Ausführung des (letzten) Kommandos wird das Programm fortgesetzt.
Der Anwender kann das Protokoll der Kommandobearbeitung (z.B. Systemmeldungen) auf SYSOUT und/oder in einen Bereich seines Programms oder in eine S-Variable übertragen lassen. Der Kommando-Returncode kann ebenfalls in einen Bereich des Programms übertragen werden.
In Tabelle 12 sind die Kommandos aufgeführt, die über den Makro CMD nicht aufgerufen werden können.
Makroaufrufformat und Operandenbeschreibung
CMD |
'kommandoname' [{ ,'oplist1'[, {adr / (r)}] / , , {adr / (r)}}] [,OPART2='oplist2'] [,OPART3='oplist3'] [,OPART4='oplist4'] [,OPART5='oplist5'] [,OPART6='oplist6'] [,OPART7='oplist7'] ,LIST=NO / YES [,CMDRC=adr] ,DIALOG=NO / YES ,SYSOUT=YES / NO ,SUBST=NO / JV / ALL ,ORIGIN=CMD / CURRENT [,DTAVAR@=adr] [,DTAVARL=länge] ,DTAEXT=NO / YES [,MSGVAR@=adr] [,MSGVARL=länge] ,MSGEXT=NO / YES ,VER=1 / 2 / 3 / 4 ,BUFMOD=SHORT / LONG [,PARMOD=24 / 31] [,MF=L / (E,..) / D / C] ,PREFIX=M / p |
Nach der Beschreibung der Stellungsoperanden werden die Schlüsselwortoperanden in alphabetischer Reihenfolge aufgeführt.
'kommandoname'
kommandoname = Name des Kommandos, das über CMD aufgerufen werden soll.
Wird der Operand LIST=YES angegeben, kann die Zeichenkette 'kommandoname' eine Liste mehrerer Kommandos enthalten, die durch Semikolon voneinander getrennt werden. Die Kommandos werden durch ein Leerzeichen von ihrer Kommandooperandenliste getrennt. Tritt bei der Abarbeitung eines Kommandos dieser Liste ein Fehler auf, wird der CMD an dieser Stelle abgebrochen.
Besteht der Operand 'kommandoname' aus einer Liste von Kommandos, entfällt die Angabe der Operanden 'oplist1' und OPARTx.
'oplist1'
oplist1 = op1,op2,op3,..... = Liste der Kommandooperanden.
Länge der Liste <= 248 Zeichen. Die Liste kann an beliebiger Stelle bei den Operanden OPART2, ...., OPART7 fortgesetzt werden. Die nächstfolgende Liste wird immer als Fortsetzung der vorhergehenden betrachtet (ohne Beachtung der Ziffern 2...7).
Der Operand darf nicht zusammen mit LIST=YES angegeben werden.
adr
Adresse des Empfangsfeldes für das SYSOUT-Protokoll. Wenn adr nicht angegeben ist, geht die Ausgabe nur nach SYSOUT. Das ist auch der Fall, wenn die Länge des Empfangsfeldes Null ist. Das Empfangsfeld muss auf Wortgrenze ausgerichtet sein. Aufbau und maximale Länge des Empfangsfeldes hängen vom Wert des Operanden BUFMOD ab.
Jeder Satz des SYSOUT-Protokolls, der in das Empfangfeld übertragen wird, enthält in den ersten vier Byte sein Satzlängenfeld (Byte 0-1 enthält die Satzlänge, Byte 2-3 sind der reservierte Teil). Der eigentliche Ausgabetext beginnt ab Byte 4 jedes Satzes. Die Ausgabesätze werden fortlaufend in den Bereich geschrieben, bis die Bereichsgrenze erreicht ist. Weitere Ausgabesätze, die in dem Bereich nicht mehr Platz haben, werden nur noch nach SYSOUT ausgegeben (wenn SYSOUT=YES angegeben ist). Bei Überschreiten der Bereichsgrenze kann ein Satz abgeschnitten werden (Returncode X'0C').
Hinweis
Das SYSOUT-Ausgabeformat für ein Kommando im Dialogbetrieb kann verschieden sein von dem im Batch-Betrieb. Das muss bei der Definition des Empfangsfeldes beachtet werden.
(r)
r = Register, das die Adresse des Empfangsfeldes enthält.
BUFMOD=
legt den Aufbau und die maximale Größe des Empfangsfeldes für das SYSOUT-Protokoll fest.
SHORT
Das Empfangsfeld kann bis zu 32 KB lang sein und hat folgenden Aufbau:
Byte 0-1: | Länge l (sedezimal) des Empfangsfeldes in Byte ( |
Byte 2-3: | reserviert, kein Eintrag |
Byte 4-n: | SYSOUT-Protokoll |
LONG
darf nur angegeben werden, wenn die 31-Bit-Schnittstelle des Makros generiert wird (PARMOD=31). Dieser Wert darf nur in Verbindung mit VER=2/3/4 angegeben werden. Das Empfangsfeld kann bis zu 2 GB lang sein und hat folgenden Aufbau:
Byte 0-3: | Länge l (sedezimal) des Empfangsfeldes in Byte ( |
Byte 4-7: | Länge (sedezimal) der Nutzinformation im Empfangsfeld in Byte (einschließlich |
Byte 8-11: | reserviert; sie müssen jedoch beim Aufruf des CMD-Makros gelöscht sein (binär |
Byte 12-15: | reserviert; wird vom System verwendet |
Byte 16-n: | SYSOUT-Protokoll |
Hinweise
Ist das Empfangsfeld nicht vollständig zugewiesen, bricht die Makrobearbeitung mit dem Returncode X'08' ab.
Wird die angegebene Länge l überschritten, wird die Ausgabe wie bei BUFMOD= SHORT abgeschnitten. CMD liefert den Returncode X'0C' zurück.
CMDRC=
gibt die symbolische Adresse eines 9 Byte langen Feldes mit folgendem Aufbau an, in das der Kommando-Returncode des vom CMD-Makro bearbeiteten Kommandos geschrieben wird.
Byte 0: | Subcode2 im Assembler-Format X'nn' |
Byte 1: | Subcode1 im Assembler-Format X'nn' |
Byte 2-8: | Maincode im Assembler-Format CL7 |
Wird im Operanden 'kommandoname' eine Liste mehrerer Kommandos übergeben (ist nur zusammen mit LIST=YES möglich), steht im angegeben Feld der Returncode des zuletzt an den MCLP übergebenen Kommandos.
Der Operand darf nur in Verbindung mit VER=3/4 angegeben werden.
adr
symbolische Adresse des Feldes, in das der Returncode geschrieben werden soll. Voreinstellung: 0, es wird kein Returncode übergeben.
DIALOG=
beschreibt, ob ein Fehler- oder Hilfedialog beim Erkennen von Syntaxfehlern geführt werden soll.
NO
Es wird kein Fehlerdialog geführt.
YES
Es soll ein Fehlerdialog geführt werden, wenn der Typ der Datensichtstation dies ermöglicht.
DTAEXT=
bestimmt, ob die bei DTAVAR@ angegebene S-Variable um den Inhalt der von OPS generierten Variablen erweitert werden soll oder nicht.
Die Angabe dieses Operanden ist nur in Verbindung mit VER=4 und den Angaben für DTAVAR@ und DTAVARL erlaubt.
NO
Die S-Variable soll nicht erweitert werden.
Der (alte) Inhalt der S-Variablen wird durch den Inhalt der OPS-Variablen ersetzt.
YES
Die S-Variable wird erweitert, indem der Inhalt der OPS-Variablen angehängt wird. Kann die S-Variable nicht erweitert werden, wird der (alte) Inhalt vor dem Abspeichern gelöscht.
DTAVAR@=
gibt die symbolische Adresse eines Bereiches an, in dem der Name einer zusammengesetzten S-Variable steht. In diese S-Variable sollen die Inhalte aller von OPS generierten Variablen gespeichert werden.
Wurde die S-Variable vor dem Makroaufruf nicht deklariert (siehe Kommando DECLARE-VARIABLE im Handbuch SDF-P [21]), wird die Abarbeitung mit dem Returncode X'10' abgebrochen.
Der Operand darf nur in Verbindung mit VER=4 angegeben werden.
adr
symbolische Adresse des Bereichs mit dem Namen der S-Variablen. Sie kann mit der beim Operanden MSGVAR@ angegebenen Adresse identisch sein, um alle von MIP oder OPS generierten Variablen in einem einzigen Bereich zu sichern.
DTAVARL=
gibt die Länge des bei DTAVAR@ adressierten Bereiches an.
Der Operand darf nur in Verbindung mit VER=4 angegeben werden.
länge
anzugebende Länge des Feldes in Byte
LIST=
ermöglicht für den Operanden 'kommandoname' die Eingabe einer Liste mehrerer Kommandos und ihrer Operanden.
NO
Der Operand 'kommandoname' besteht aus einem einzigen Kommando.
YES
Der Operand 'kommandoname' enthält eine Liste mehrerer Kommandos, die mit Semikolon voneinander getrennt werden.
Dieser Wert darf nur in Verbindung mit VER=3/4 angegeben werden.
MF=
Zur allgemeinen Beschreibung des Operanden MF, der dazugehörenden Operandenwerte und der evtl. nachfolgenden Operanden (z.B. für einen Präfix) sieh Abschnitt „S-Typ-Makroaufrufe“. Die gültigen MF-Werte sind zu Beginn der Makrobeschreibung bei „Makrotyp“ angegeben und aus dem Aufrufformat ersichtlich.
Bei MF=C oder MF=D kann ein Präfix PREFIX (p = 1 Buchstabe), wie im Aufrufformat dargestellt, angegeben werden.
MSGEXT=
bestimmt, ob die bei MSGVAR@ angegebene S-Variable um den Inhalt der von MIP generierten Variablen erweitert werden soll oder nicht.
Die Angabe dieses Operanden ist nur in Verbindung mit VER=4 und den Angaben für MSGVAR@ und MSGVARL erlaubt.
NO
Die S-Variable soll nicht erweitert werden.
Der (alte) Inhalt der S-Variablen wird durch den Inhalt der MIP-Variablen ersetzt.
YES
Die S-Variable wird erweitert, indem der Inhalt der MIP-Variablen angehängt wird. Kann die S-Variable nicht erweitert werden, wird der (alte) Inhalt vor dem Abspeichern gelöscht.
MSGVAR@=
gibt die symbolische Adresse eines Bereiches an, in dem der Name einer zusammengesetzten S-Variable steht. In diese S-Variable sollen die Inhalte aller von MIP generierten Variablen gespeichert werden.
Wurde die S-Variable vor dem Makroaufruf nicht deklariert (siehe Kommando DECLARE-VARIABLE im Handbuch SDF-P [21]), wird die Abarbeitung mit dem Returncode X'10' abgebrochen.
Der Operand darf nur in Verbindung mit VER=4 angegeben werden.
adr
symbolische Adresse des Bereichs mit dem Namen der S-Variablen. Sie kann mit der beim Operanden DTAVAR@ angegebenen Adresse identisch sein, um alle von MIP oder OPS generierten Variablen in einem einzigen Bereich zu sichern.
MSGVARL=
gibt die Länge des bei MSGVAR@ adressierten Bereiches an. Der Operand darf nur in Verbindung mit VER=4 angegeben werden.
länge
anzugebende Länge des Feldes in Byte.
OPARTx=
ermöglicht die Fortsetzung der Operandenliste.
x = Element aus der Menge (2, 3, .., 7).
'oplistx'
oplistx = op,op,opkj,.... = (Fortsetzungs-)Liste der Kommandooperanden; x = Element aus der Menge (2,3,...,7).
Länge: oplistx = 1..248 Zeichen.
Der Operand darf nicht zusammen mit LIST=YES angegeben werden.
ORIGIN=
gibt den Ursprung des Kommandos an, der benutzt werden muss, wenn überprüft wird, ob das Kommando erlaubt ist.
Der Operand darf nur in Verbindung mit VER=4 und MF=D oder MF=C angegeben werden.
CMD
Die Kommandoeingabe muss mit dem CMD-ALLOWED-Attribut aus der Syntax-Datei überprüft werden.
CURRENT
Zusätzlich zum CMD-ALLOWED-Attribut, überprüft SDF auch, ob das Kommando im aktuellen Modus erlaubt ist. Das ist der Modus, in dem das Programm gestartet wurde. Der Modus kann sein: Dialog, Dialog-Prozedur, Batch oder Batch-Prozedur.
PARMOD=
steuert die Makroauflösung. Es wird entweder die 24-Bit- oder die 31-Bit-Schnittstelle generiert.
Wenn PARMOD nicht spezifiziert wird, erfolgt die Makroauflösung entsprechend der Angabe für den Makro GPARMOD oder der Voreinstellung für den Assembler (= 24-Bit-Schnittstelle).
24
Die 24-Bit-Schnittstelle wird generiert. Datenlisten und Befehle benutzen 24-Bit-Adressen (Adressraum <= 16 MB).
Dieser Wert darf nur in Verbindung mit VER=1 angegeben werden.
31
Die 31-Bit-Schnittstelle wird generiert. Datenlisten und Befehle benutzen 31-Bit-Adressen (Adressraum <= 2 GB). Datenlisten beginnen mit dem Standardheader.
SUBST=
bestimmt, welche Substitutionen in der Kommandoeingabe erfolgen sollen.
NO
In der Kommandoeingabe wird keine Substitution durchgeführt.
JV
Alle Jobvariablen der Kommandoeingabe werden durch ihre Inhalte ersetzt.
Dieser Wert darf nur in Verbindung mit VER=4 angegeben werden.
ALL
Die Kommandoeingabe wird, abhängig von der Programmumgebung, vollständig ersetzt, d.h. alle S-Variablen, Jobvariablen und SYSFILE-Prozedurparamter in der Kommandoeingabe werden in der angegebenen Reihenfolge ersetzt. Die Ersetzung von SYSFILE-Prozedurparametern ist nur in Nicht-S-Prozeduren sinnvoll.
S-Variablen werden nur dann ersetzt, wenn sie in der aktuellen Programmumgebung sichtbar (bekannt) sind.
Dieser Wert darf nur in Verbindung mit VER=4 angegeben werden.
SYSOUT=
beschreibt, ob das Protokoll auch nach SYSOUT ausgegeben werden soll.
YES
Die Ausgabe erfolgt auch auf SYSOUT.
NO
Es erfolgt keine Ausgabe nach SYSOUT. In diesem Fall muss das Empfangsfeld adr spezifiziert sein.
VER=1 / 2 / 3 / 4
hat nur Bedeutung für MF ungleich E und wird andernfalls ignoriert. Der Operand legt fest, welche Version des Datenbereichs erzeugt werden soll.
Zur Verträglichkeit mit anderen Operanden siehe folgende Tabelle.
VER=1 | VER=2 | VER=3 | VER=4 | ||
PARMOD | = 24 | x | |||
=31 | x | x | x | x | |
BUFMOD | = SHORT | x | x | x | x |
= LONG | x | x | x | ||
LIST | = NO | x | x | x | x |
= YES | x | x | |||
CMDRC | x | x | |||
SUBST | = NO | x | x | x | x |
= JV | x | ||||
=ALL | x | ||||
ORIGIN | x | ||||
DTA... | x | ||||
MSG... | x | ||||
andere | x | x | x | x |
Tabelle 11: Verträglichkeit des Operanden VER mit anderen Operanden (CMD)
x bedeutet, dass die betreffenden Operanden zusammen angegeben werden können.
Hinweise zum Makroaufruf
Die Angabe DIALOG=YES wird im Expertenmodus (MODIFY-SDF-OPTIONS GUIDANCE=*EXPERT, siehe Handbuch „Kommandos“ [19]) ignoriert. Es wird der Returncode X'10' (statt X'14') zurückgegeben.
Wird DIALOG=NO angegeben, liefert SDF die folgenden Returncodes zurück, wenn die Hilfe-Anforderung im CMD-Input benutzt wird:
"?"
Es wird der Returncode X'10' zurückgegeben.
"<operation?>"
(? als Teil von <operation>) Es wird der Returncode X'14'
zurückgegeben."<operation> ?"
Ist <operation> gültig, dann wird der Returncode X'10' zurückgegeben.
Ist <operation> ungültig, dann wird der Returncode X'14'
zurückgegeben.In beiden Modi (Dialog oder Batch) wird ein unklares Kommando für alle Werte des Operanden DIALOG mit dem Returncode X'14' zurückgewiesen.
Die Abarbeitung der Kommandoliste (bei LIST=YES) wird beendet, wenn eines der gegebenen Kommandos einen Fehler verursacht (Syntaxfehler, Speicherfehler,..). Ein solcher Fehler führt nicht zum SPIN-OFF.
Der mit MF=C/D generierte Datenbereich muss dem mit MF=L genutzten Datenbereich entsprechen.
Wenn der CMD-Datenbereich mit der Standard- oder MF=L-Form initialisiert wurde, können im Feld
<PREFIX>CLPLNTHfolgende Informationen gelesen werden:die Länge des gesamten, vorgegebenen Datenbereichs des CMD-Aufrufs im ersten Halbwort (d.h. ab Byte 0 in der Länge von 2 Byte).
die Länge der abgearbeiteten Kommandoeingabe im zweiten Halbwort (d.h. ab Byte 2 in der Länge von 2 Byte). Wurde die Abarbeitung des CMD-Makros wegen eines Fehlers vorzeitig beendet, zeigt dieses Halbwort die Abbruchstelle an.
Strukturierte Ausgaben des CMD-Makros können nicht (wie beim Kommando EXECUTE-CMD) auf den S-Variablenstrom SYSINF gelenkt werden.
Wenn über die Operanden DTAVAR@ die Ausgabe von OPS-Variablen angefordert wird, dannl
kann das Kommando START-EXECUTABLE-PROGRAM nicht vom CMD-Makro abgesetzt werden
und ist die Verkettung mehrerer Kommandos in einem Eingabesatz
(Operanden 'kommandoname' und LIST=YES) nicht möglich.
Einige BS2000-Kommandos können nicht über den Makro CMD aufgerufen werden, siehe folgende Tabelle:
Kommando
Funktion
Handbuch
ADD-CJC-ACTION
CJC-Kommandofolge einleiten (Jobvariablen)
[19]
BEGIN-BLOCK
leitet einen Kommandoblock ein
[21]
BEGIN-PARAMETER-
DECLARATIONleitet die Deklaration der Prozedurparameter im
Prozedurkopf einBEGIN-PROCEDURE
Prozedurdateimerkmale festlegen
[19]
BREAK
Kommando-Modus anfordern
[33]
CANCEL-PROCEDURE
Prozedur(ablauf) abbrechen
[19]
CANCEL-PROGRAM
Programmlauf abbrechen
[19]
CHANGE-
ACCOUNTING-FILESystemabrechnungsdatei wechseln
[19]
COPY-SYSTEM-FILE
kopiert Systemdateien
[19]
CYCLE
bricht einen Schleifendurchlauf ab
[21]
DELON
ON-Kommando löschen
[33]
ENDON
beendet eine ON-Anweisungsfolge
[33]
ELSE
leitet den ELSE-Zweig im IF-Block ein
ELSE-IF
leitet im IF-Block einen Alternativzweig ein
[21]
END-BLOCK
schließt einen Kommandoblock ab
[21]
END-CJC-ACTION
CJC-Kommandofolge abschließen (Jobvariablen)
[19]
END-FOR
schließt einen FOR-Block ab
[21]
END-IF
schließt einen IF-Block ab
END-PARAMETER-
DECLARATIONschließt eine Prozedurparameterdeklaration ab
END-PROCEDURE
beendet eine Prozedurdatei
[19]
END-WHILE
schließt einen WHILE-Block ab
[21]
ENDP
Prozedurdatei beenden
[33]
EOF
Dateiende für SYSDTA kennzeichnen
[19]
ESCAPE
Prozedurablauf unterbrechen
[33]
EXIT-BLOCK
bricht die Verarbeitung eines Kommandoblockes ab
[21]
FOR
leitet einen FOR-Block ein
[21]
GOTO
springt zu einer Marke
HOLD-PROCEDURE
unterbricht Prozedurablauf und ermöglicht die
Kommandoeingabe vom Datensichtgerät[19]
HOLD-PROGRAM
unterbricht Programmablauf und ermöglicht die
Kommandoeingabe vom Datensichtgerät[19]
IF
leitet einen Block ein
IF-BLOCK-ERROR
leitet eine Block-Fehlerbehandlung ein
IF-CMD-ERROR
leitet eine Kommando-Fehlerbehandlung ein
[21]
LOGON
Auftrag (Job) einleiten
[33]
MODIFY-
ACCOUNTING-
PARAMETERSlegt Abrechnungssätze und Satzerweiterungen für die
Accountingdatei fest[19]
MODIFY-JV-
CONDITIONALLYändert den Wert einer Jobvariablen und verzweigt zum
Sprungziel[19]
ON
bedingte Ausführung einer Kommandofolge
[33]
PROCEDURE
Prozedurdateimerkmale festlegen
[33]
REMOVE-CJC-ACTION
Wirksamkeit von ADD-CJC-ACTION-Kommandos
aufheben (Jobvariablen)[19]
REPEAT
leitet einen REPEAT-Block ein
[21]
RESTART-PROGRAM
startet ein Programm an seinem Fixpunkt
[19]
RESUME-
PROCEDUREunterbrochenen Prozedurablauf fortsetzen
[19]
SELECT-PRODUCT-
VERSIONwählt eine Produktversion aus
[19]
SET-JOB-STEP
beendet SPIN-OFF
[19]
SET-LOGON-
PARAMETERSleitet einen Dialog- oder Batch-Auftrag ein
[19]
SHOW-ACCOUNTING-
STATUSinformiert über das Abrechnungssystem
[19]
SKIP-COMMANDS
bedingt oder unbedingt springen
[19]
SKIPJV
springen in Abhängigkeit von Jobvariablen
[33]
SKIPUS
springen in Abhängigkeit von Benutzerschaltern
[33]
START-ACCOUNTING
Abrechnungssystem einschalten
[19]
STEP
beendet SPIN-OFF
[33]
STOP-ACCOUNTING
Abrechnungssystem ausschalten
[19]
UNTIL
schließt einen REPEAT-Block ab
[21]
WAIT-EVENT
bedingte Wartezeit (Batch-Auftrag) angeben
[19]
WHEN
Batch-Auftrag bedingt (Benutzerschalter) anhalten
[33]
WHILE
leitet einen WHILE-Block ein
[21]
Beim Aufruf folgender Kommandos durch den Makro CMD wird das aufrufende Programm entladen:
Kommando
Funktion
Handbuch
ABEND
laufenden Auftrag abbrechen
[33]
CALL
Prozedur aufrufen
[33]
CALL-PROCEDURE
Prozedur aufrufen
[19]
DO
Prozedur aufrufen
[33]
EXECUTE
Modul laden und starten
[33]
EXIT-JOB
Auftrag (Job) beenden
[19]
HELP-SDF
Anleitung zum Aufruf von SDF-Kommandos
[19]
LOAD
Modul laden
[33]
LOAD-EXECUTABLE-
PROGRAMModul laden
[19]
LOAD-PROGRAM
Modul laden
[19]
LOGOFF
Auftrag (Job) beenden
[33]
START-EXECUTABLE-
PROGRAMModul binden, laden und starten
[19]
START-PROGRAM
Modul binden, laden und starten
[19]
Tabelle 13: Kommandos, bei deren Aufruf das aufrufende Programm entladen wird
Das aufrufende Programm wird ebenfalls entladen, wenn das aufgerufene Kommando durch eine Kommandoprozedur realisiert ist. Dies ist z.B. für alle EDIT-Kommandos der Fall (siehe Handbuch „Kommandos“ [19]). Es kann aber auch mittels SDF-A selbstdefinierte Kommandos dieser Art geben (siehe Handbuch „SDF-A“ [20]).
Um das Entladen zu verhindern, können Kommandos, die über eine Kommandoprozedur realisiert sind, sowie die Kommandos CALL-PROCEDURE, CALL und DO indirekt über das SDF-P-Kommando INCLUDE-CMD aufgerufen werden (siehe Handbuch „SDF-P“ [21]). Das eigentlich auszuführende Kommando wird dabei als Operand von INCLUDE-CMD angegeben.
INCLUDE-CMD unterbricht das aufrufende Programm, führt das als Operand angegebene Kommando (und damit die zugehörige Kommandoprozedur) aus und kehrt dann wieder zum Programm zurück. Die aufgerufene Kommandoprozedur darf aber ihrerseits kein Kommando ausführen, das zum Entladen des Programms führt.Das SYSOUT-Protokoll wird bei Kommandos, die das aufrufende Programm beenden, demzufolge nicht in das Empfangsfeld adr übertragen. Eine ggf. definierte STXIT-Routine für die Ereignisklasse „Programmbeendigung“ wird aktiviert.
Eine den Auftrag überwachende Jobvariable wird auf „$T“ gesetzt.
Rückinformation und Fehleranzeigen
R15:
+---------------+ | | | | | | | | | | | |a|a| +---------------+
Über die Ausführung des Makros CMD wird im Register R15 rechtsbündig ein Returncode übergeben.
X'aa' | Erläuterung |
X'00' | Die Funktion wurde erfolgreich ausgeführt. |
X'04' | Die Funktion wurde abgebrochen: Es ist nicht genügend Speicherbereich vorhanden. |
X'08' | Die Funktion wurde abgebrochen: Fehler im Datenbereich (Adressbereich). |
X'0C' | Die Funktion wurde abgebrochen: Das Empfangsfeld ist zu kurz. |
X'10' | Die Funktion wurde abgebrochen: Makroaufruf-/Kommando-Fehler |
X'14' | Die Funktion wurde abgebrochen: Ungültiges Kommando in der Operandenliste. |
X'24' | Die Funktion wurde abgebrochen: Fehler bei der Substitution der Kommandoeingabe. |
zusätzlich bei PARMOD=31:
Standardheader:
+---------------+ | | | | | |c|c|b|b|a|a|a|a| +---------------+
Über die Ausführung des Makros CMD wird im Standardheader folgender Returncode übergeben (cc=Subcode2, bb=Subcode1, aaaa=Maincode):
cc | bb | aaaa | Erläuterung |
00 | 00 | 0000 | Die Funktion wurde erfolgreich ausgeführt. |
00 | 01 | 0008 | Die Funktion wurde abgebrochen: Operandenfehler. |
00 | 20 | 0004 | Die Funktion wurde abgebrochen: Interner Fehler. |
00 | 40 | 0010 | Die Funktion wurde abgebrochen: Makroaufruf-/Kommandofehler. |
00 | 40 | 0014 | Die Funktion wurde abgebrochen: Ungültiges Kommando in der Operandenliste. |
00 | 40 | 0024 | Die Funktion wurde abgebrochen: Fehler bei der Substitution der |
02 | 00 | 000C | Die Funktion wurde abgebrochen: Das Empfangsfeld ist zu kurz. Der letzte |
Weitere Returncodes, deren Bedeutung durch Konvention makroübergreifend festgelegt ist, können der Tabelle „Standard-Returncodes“ (Standardheader) entnommen werden.
Layout der DSECT für VER=4
CMD MF=D,PARMOD=31,VER=4 1 #INTF REFTYPE=REQUEST,INTNAME=CMD,INTCOMP=4 1 DS 0F 1 MFCHK DMACID=CLP,PREFIX=M,MACID=CLP,MF=D,DNAME=DMCLP 2 MDMCLP DSECT , 2 *,##### PREFIX=M, MACID=CLP ##### 1 MCLPSTRT DS 0F 1 FHDR MF=(C,MCLP) 2 DS 0A 2 MCLPFHE DS 0XL8 0 GENERAL PARAMETER AREA HEADER 2 * 2 MCLPIFID DS 0A 0 INTERFACE IDENTIFIER 2 MCLPFCTU DS AL2 0 FUNCTION UNIT NUMBER 2 * BIT 15 HEADER FLAG BIT, 2 * MUST BE RESET UNTIL FURTHER NOTICE 2 * BIT 14-12 UNUSED, MUST BE RESET 2 * BIT 11-0 REAL FUNCTION UNIT NUMBER 2 MCLPFCT DS AL1 2 FUNCTION NUMBER 2 MCLPFCTV DS AL1 3 FUNCTION INTERFACE VERSION NUMBER 2 * 2 MCLPRET DS 0A 4 GENERAL RETURN CODE 2 * 2 * GENERAL_RETURN_CODE CLEARED (X'00000000') MEANS 2 * REQUEST SUCCESSFUL PROCESSED AND NO ADDITIONAL INFORMATION 2 * 2 MCLPSRET DS 0AL2 4 SUB RETURN CODE 2 MCLPSR2 DS AL1 4 SUB RETURN CODE 2 2 * ALWAYS CLEARED (X'00') IF MAIN_RETURN_CODE IS X'FFFF' 2 * Standard subcode2 values as defined by convention: 2 MCLPR2OK EQU X'00' All correct, no additional info 2 MCLPR2NA EQU X'01' Successful, no action was necessary 2 MCLPR2WA EQU X'02' Warning, particular situation 2 MCLPSR1 DS AL1 5 SUB RETURN CODE 1 2 * 2 * GENERAL INDICATION OF ERROR CLASSES 2 * 2 * CLASS A X'00' FUNCTION WAS SUCCESSFULLY PROCESSED
2 * CLASS B X'01' - X'1F' PARAMETER SYNTAX ERROR 2 * CLASS C X'20' INTERNAL ERROR IN CALLED FUNCTION 2 * CLASS D X'40' - X'7F' NO CLASS SPECIFIC REACTION POSSIBLE 2 * CLASS E X'80' - X'82' WAIT AND RETRY 2 * 2 MCLPRFSP EQU X'00' FUNCTION SUCCESSFULLY PROCESSED 2 MCLPRPER EQU X'01' PARAMETER SYNTAX ERROR 2 * 3 GLOBALLY DEFINED ISL ERROR CODES IN CLASS X'01' - X'1F' 2 MCLPRFNS EQU X'01' CALLED FUNCTION NOT SUPPORTED 2 MCLPRFNA EQU X'02' CALLED FUNCTION NOT AVAILABLE 2 MCLPRVNA EQU X'03' INTERFACE VERSION NOT SUPPORTED 2 * 2 MCLPRAER EQU X'04' ALIGNMENT ERROR 2 MCLPRIER EQU X'20' INTERNAL ERROR 2 MCLPRCAR EQU X'40' CORRECT AND RETRY 2 * 2 GLOBALLY DEFINED ISL ERROR CODES IN CLASS X'40' - X'7F' 2 MCLPRECR EQU X'41' SUBSYSTEM (SS) MUST BE CREATED 2 * EXPLICITELY BY CREATE-SS 2 MCLPRECN EQU X'42' SS MUST BE EXPLICITELY CONNECTED 2 * 2 MCLPRWAR EQU X'80' WAIT FOR A SHORT TIME AND RETRY 2 MCLPRWLR EQU X'81' " LONG " 2 MCLPRWUR EQU X'82' WAIT TIME IS UNCALCULABLY LONG 2 * BUT RETRY IS POSSIBLE 2 * 2 GLOBALLY DEFINED ISL ERROR CODES IN CLASS X'80' - X'82' 2 MCLPRTNA EQU X'81' SS TEMPORARILY NOT AVAILABLE 2 MCLPRDH EQU X'82' SS IN DELETE / HOLD 2 * 2 MCLPMRET DS 0AL2 6 MAIN RETURN CODE 2 MCLPMR2 DS AL1 6 MAIN RETURN CODE 2 2 MCLPMR1 DS AL1 7 MAIN RETURN CODE 1 2 * 2 * SPECIAL LAYOUT OF LINKAGE_MAIN_RETURN_CODE (YYYY IN X'00XXYYYY') 2 * 2 MCLPRLNK EQU X'FFFF' LINKAGE ERROR / REQ. NOT PROCESSED 2 MCLPFHL EQU 8 8 GENERAL OPERAND LIST HEADER LENGTH 2 * 1 MCLPFLAG DS X Flag bits 1 * Flag bits:.0...... : UNUSED 1 * 0....... : reserved for TPR usage 1 MCLPDIA EQU X'20' ..1..... : DIALOG possible (w. SDF only) 1 MCLPNSYS EQU X'10' ...1.... : no SYSOUT logging 1 MCLPLIST EQU X'08' ....1... : LIST of commands 1 MCLPNOUT EQU X'04' .....10. : no output buffer 1 MCLPLONG EQU X'02' .....01. : long output buffer 1 * .....00. : short (old) output buffer 1 MCLPREG EQU X'01' .......1 buffer @ given via a register/ 1 MCLPADDR EQU X'00' .......0 buffer @ given directly
1 MCLPNSRG EQU X'11' ...1...1 no SYSOUT, buff.@ in a reg. 1 MCLPNSAD EQU X'10' ...1...0 no SYSOUT, buff.@ given directly 1 MCLPFLA3 DS XL1 FLAG 3 1 MCLPSJV EQU X'80' 10...... substitute jv only 1 MCLPSALL EQU X'40' 01...... substitute all 1 MCLPDATE EQU X'20' ..1..... data var buf extend 1 MCLPMSGE EQU X'10' ...1.... msg var buf extend 1 MCLPCUOR EQU X'04' .....1.. origin=current 1 MCLPUNUS DS XL1 reserved (unused) 1 MCLPROUT DS XL1 reg.# if buffer @ in reg. 1 MCLPOUT DS A buffer @ or 0 1 MCLPCMD@ DS A @ of command (-> V-field) 1 MCLPRC@ DS A @ return code of command 1 MCLPTPR2 DS A reserved for TPR usage. 1 MCLPDAV@ DS A @ of var name for data 1 MCLPMSV@ DS A @ of var name for message 1 MCLPDAVL DS H length of var name 1 MCLPMSVL DS H length of var name 1 MCLPTPR3 DS A reserved for TPR usage. 1 MCLPHLN EQU *-MCLPSTRT CMD p.l. length 1 MCLPLNTH EQU * command's V-field when CLPCMD@ points here 1 MCLPCMD EQU *+4 cmd start when MCLPCMD@ points to MCLPLNTH
Beispiel
Mit dem Makro CMD wird das Kommando SHOW-JOB-STATUS in zwei Ausprägungen ausgeführt. Die Programmausführung erfolgt im 31-Bit-Adressierungsmodus unterhalb der 16-MB-Grenze.
CMD START
PRINT NOGEN
CMD AMODE ANY
BALR 3,0
USING *,3
CMD MF=(E,LFORMAD1),PARMOD=31 --------------------------------(1)
CMD MF=(E,LFORMAD2),PARMOD=31 --------------------------------(2)
MVC MESSAGE(4),PROTCONT
MVC MESSTXT,PROTCONT+4
WROUT MESSAGE,END,PARMOD=31
END TERM
LFORMAD1 CMD 'SHOW-JOB-STA','INF=(*STD,*PROGRAM)',MF=L,PARMOD=31 ------(3)
LFORMAD2 CMD 'SHOW-JOB-STA','INF=*STD',PROT,SYSOUT=NO,MF=L,PARMOD=31 --(4)
DS 0F
PROT DC Y(PROTEND-PROT) ------------------------------------------(5)
DC X'4040'
PROTCONT DS CL2500
PROTEND EQU *
MESSAGE DC Y(ENDMESS-MESSAGE) Record length
DS CL2 Reserved
DC X'01' Print feed control character
MESSTXT DS CL255 Contents
ENDMESS EQU *
END
(1) | Der Makroaufruf ist in Befehlsteil und Datenbereich aufgespalten (siehe Abschnitt„S-Typ-Makroaufrufe“). Hier steht nur der Befehlsteil (SVC) mit einem Verweis auf den Datenbereich LFORMADR1 im Datenteil des Programms. |
(2) | Der Makro wird mit einem Verweis auf den Datenbereich LFORMADR2 aufgerufen. |
(3) | Das Kommando SHOW-JOB-STATUS wird mit dem Operanden INF=(*STD,*PROGRAM) aufgerufen. Die Ausgabe erfolgt an der Datensichtstation. |
(4) | Das Kommando SHOW-JOB-STATUS wird mit dem Operanden INF=*STD aufgerufen. Die Information wird in den Bereich |
(5) | Der Bereich für die Kommando-Ausgabe beginnt an einer Wortgrenze mit dem Eintrag der Bereichslänge in den beiden ersten Byte. |
Ablaufprotokoll:
/start-assembh
% BLS0500 PROGRAM 'ASSEMBH', VERSION '<ver>' OF '<date>' LOADED
% ASS6010 <ver> OF BS2000 ASSEMBH READY
//compile source=*library-element(macexmp.lib,cmd), -
// compiler-action=module-generation(module-format=llm), -
// module-library=macexmp.lib, -
// listing=parameters(output=*library-element(macexmp.lib,cmd))
% ASS6011 ASSEMBLY TIME: 344 MSEC
% ASS6018 0 FLAGS, 0 PRIVILEGED FLAGS, 0 MNOTES
% ASS6019 HIGHEST ERROR-WEIGHT: NO ERRORS
% ASS6006 LISTING GENERATOR TIME: 80 MSEC
//end
% ASS6012 END OF ASSEMBH
/start-executable-program library=macexmp.lib,element-or-symbol=cmd
% BLS0523 ELEMENT 'CMD', VERSION '@' FROM LIBRARY
':2OSG:$QM212.MACEXMP.LIB' IN PROCESS
% BLS0524 LLM 'CMD', VERSION ' ' OF '<date> <time>' LOADED
NAME TSN TYPE PRI CPU-USED CPU-MAX ACCOUNT# -------------(6)
MACTEST 2QSE 3 DIALOG1 0 210 58.7710 9000 89002
NAME TSN TYPE SIZE CURR-CMD
MACTEST 2QSE 3 DIALOG1 1 START-EXECUTABLE-PROGRAM
PROG::2OSG:$QM212.MACEXMP.LIB(CMD,@,L)
NAME TSN TYPE PRI CPU-USED CPU-MAX ACCOUNT# -------------(7)
MACTEST 2QSE 3 DIALOG1 0 210 58.7856 9000 89002
(6) | Ausgabe des ersten CMD-Aufrufs direkt auf Datensichtstation. |
(7) | Der Ausgabebereich |