Kommandofolge aus Datei oder Listenvariable starten
Komponente: | SYSFILE |
Funktionsbereich: | Prozeduren |
Anwendungsbereich: | PROCEDURE |
Privilegierung: | STD-PROCESSING |
Funktionsbeschreibung
Das Kommando CALL-PROCEDURE startet eine gespeicherte Kommandofolge (Prozedur). Bei Abarbeitung werden darin enthaltene symbolische Parameter durch die im Kommandoaufruf angegebenen Werte (Operand PROCEDURE-PARAMETERS) ersetzt. Eine Prozedur kann folgende Teile enthalten:
Kommandos (beginnen mit führendem Schrägstrich)
SDF-Anweisungen, d.h. Anweisungen an ein Programm, die in einer Syntaxdatei definiert sind (beginnen mit führendem Doppelschrägstrich)
Eingabedaten, d.h. Daten, Parameter und Anweisungen, die ein Programm einliest
Bei Prozeduraufruf wird die Prozedur der Systemdatei SYSCMD als Eingabequelle für Kommandos zugeordnet. Enthält die Prozedur auch SDF-Anweisungen und/oder Eingabedaten, so muss die Systemdatei SYSDTA der Systemdatei SYSCMD zugeordnet sein (siehe ASSIGN-SYSDTA bzw. auch SET-PROCEDURE-OPTIONS für S-Prozedur).
Prozeduren können gespeichert werden als:
katalogisierte (auch temporäre) SAM- oder ISAM-Datei mit Sätzen variabler Länge
Element vom Typ J oder SYSJ einer PLAM-Bibliothek
S-Variable vom Typ Liste
Es gibt zwei Arten von Prozeduren, die sich im formalen Aufbau und Ablauf unterscheiden:
Nicht-S-Prozedur
S-Prozedur
Einschränkungen
Benutzer mit den Privilegien SECURITY-ADMINISTRATION, SAT-FILE-EVALUATION und SAT-FILE-MANAGEMENT können das Kommando nur in Prozeduren nutzen.
Das Starten einer Prozedur aus einer S-Variablen mit der Angabe FROM=*VARIABLE(...) ist nur möglich, wenn das kostenpflichtige Subsystem SDF-P geladen ist.
Nicht-S-Prozedur
Die Nicht-S-Prozedur muss als ersten Datensatz das Kommando BEGIN-PROCEDURE enthalten. Darin können symbolische Parameter, die Protokollierung und die Unterbrechbarkeit der Prozedur vereinbart werden. Danach folgen die Kommandos, SDF-Anweisungen und Eingabedaten, die abgearbeitet werden sollen. Die Abarbeitung endet mit dem Kommando END-, CANCEL- oder EXIT-PROCEDURE bzw. mit dem letzten Datensatz. Tritt ein Fehler auf, wird Spin-Off ausgelöst. Die Fehlerbehandlung ist beim Kommando SET-JOB-STEP beschrieben.
S-Prozedur
Der erste Datensatz einer S-Prozedur muss ein Kommando sein. Die Kommandos BEGIN-PROCEDURE bzw. PROCEDURE (ISP-Kommando) und SET-LOGON-PARAMETERS bzw. LOGON (ISP-Kommando) sind nicht zulässig. Die Prozedureigenschaften können mit dem Kommando SET-PROCEDURE-OPTIONS als erstes Kommando explizit vereinbart werden. Ohne explizite Vereinbarung gelten implizit die Voreinstellungen von SDF-P (siehe SET-PROCEDURE-OPTIONS). Nach den Prozedureigenschaften können mit dem Kommando DECLARE-PARAMETER symbolische Parameter vereinbart werden, die bei Ablauf durch den Inhalt der gleichnamigen S-Variablen ersetzt werden.
S-Prozeduren sind nur ablauffähig, wenn S-Variablen zur Verfügung stehen, d.h. wenn mindestens das Subsystem SDFPBASY (siehe Abschnitt „SDF-P-BASYS"] bzw. auch Handbuch „SDF-P“ [34]) geladen ist.
Die Abarbeitung der Kommandos, SDF-Anweisungen und Eingabedaten endet mit dem Kommando CANCEL- oder EXIT-PROCEDURE bzw. mit dem letzten Datensatz. Tritt ein Fehler auf, wird die SDF-P-Fehlerbehandlung ausgelöst. Die Fehlerbehandlung ist bei dem Kommando IF-BLOCK-ERROR beschrieben.
Es sind zwei verschiedene Prozedur-Formate möglich:
Text-Prozedur
Die S-Prozedur liegt im ursprünglichen Textformat vor. Volle SDF-P-Funktionalität kann nur verwendet werden, wenn bei Aufruf der Prozedur das kostenpflichtige Subsystem SDF-P geladen ist. In Bibliotheken sollte für Text-Prozeduren der Elementtyp J verwendet werden.Objekt-Prozedur
Die S-Prozedur im Textformat wurde mit dem Kommando COMPILE-PROCEDURE in ein Zwischenformat kompiliert. Das Kommando COMPILE-PROCEDURE ist Bestandteil des kostenpflichtigen Subsystems SDF-P. Die Objekt-Prozedur kann, unabhängig von der Verfügbarkeit des Subsystems SDF-P, die volle SDF-P-Funktionalität nutzen (mit Ausnahme des Kommandos COMPILE-PROCEDURE). In Bibliotheken sollte für Objekt-Prozeduren der Elementtyp SYSJ verwendet werden (Default-Wert bei COMPILE-PROCEDURE).
Automatischer Prozedurstart
LOGON-Prozedur
Nach erfolgter LOGON-Verarbeitung startet SDF automatisch die System- und danach die Benutzer-LOGON-Prozedur. Eine System-LOGON-Prozedur wird gestartet, wenn die Systembetreuung eine zur Verfügung stellt. Eine Benutzer-LOGON-Prozedur wird als Call-Prozedur gestartet, wenn sie in der jeweiligen Benutzerkennung unter dem Namen SYS.SDF.LOGON.USERPROC katalogisiert ist (unter SYS.SDF.LOGON.USERINCL erfolgt der Aufruf als Include-Prozedur). LOGON-Prozeduren werden in folgenden Fällen ohne Warnung ignoriert:
Die Prozedurdatei ist nur katalogisiert, belegt aber keinen Speicherplatz.
Die Task ist eine RFA-Task.
Die Task besitzt außer HARDWARE-MAINTENANCE, SECURITY-ADMINISTRATION, SAT-FILE-MANAGEMENT und SAT-FILE-EVALUATION kein anderes Privileg.
Eingaben sind erst nach Ablauf der LOGON-Prozeduren möglich.
LOGOFF-Prozedur
Bei der LOGOFF-Verarbeitung startet SDF automatisch die Benutzer- und danach die System-LOGOFF-Prozedur. Eine Benutzer-LOGOFF-Prozedur wird als Call-Prozedur gestartet, wenn sie in der jeweiligen Benutzerkennung unter dem Namen SYS.SDF.LOGOFF.USERPROC katalogisiert ist (unter SYS.SDF.LOGOFF.USERINCL erfolgt der Aufruf als Include-Prozedur). Eine System-LOGOFF-Prozedur wird gestartet, wenn die Systembetreuung eine zur Verfügung stellt (Eintrag in SDF-Parameterdatei).
LOGOFF-Prozeduren werden in folgenden Fällen ohne Warnung ignoriert:
Die Prozedurdatei ist nur katalogisiert, belegt aber keinen Speicherplatz.
Die Task wurde mit CANCEL-JOB bzw. FORCE-JOB-CANCEL abgebrochen.
Die Task ist eine RFA-Task.
Die Task besitzt außer HARDWARE-MAINTENANCE, SECURITY-ADMINISTRATION, SAT-FILE-MANAGEMENT und SAT-FILE-EVALUATION kein anderes Privileg.
Implementierte Prozedur
Sind in einer aktivierten Syntaxdatei Kommandos als Prozeduren implementiert (siehe Handbuch „SDF-A“ [33]), so wird bei Aufruf eines solchen Kommandos die festgelegte Prozedur gestartet.
Prozedurschachtelung
Prozeduren können beliebig geschachtelt werden:
Enthält die Kommandofolge einer Prozedurdatei ein CALL-PROCEDURE-Kommando, so wird der Ablauf unterbrochen und die nächste Prozedur gestartet usw.
Bei Prozedurende (END-PROCEDURE, EXIT-PROCEDURE oder EOF-Bedingung) wird zur Unterbrechungsstelle der zuletzt verlassenen Prozedur verzweigt. Das folgende Bild zeigt ein Beispiel für Prozedur-Schachtelung mit CALL-PROCEDURE für eine Nicht-S-Prozedur.
Format
CALL-PROCEDURE | Kurzname: CL / CLP | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Operandenbeschreibung
FROM-FILE = <filename 1..54 without-gen> / *LIBRARY-ELEMENT(...) / *VARIABLE(...)
Name der Prozedurdatei.
FROM-FILE = *LIBRARY-ELEMENT(...)
Die Prozedur ist in einem PLAM-Bibliothekselement abgelegt.
LIBRARY = <filename 1..54 without-gen>
Name der PLAM-Bibliothek, die die Prozedur als Element (Typ J oder SYSJ; siehe Operand TYPE) enthält.
ELEMENT = <composed-name 1..64>(...)
Name des Elements.
VERSION = *HIGHEST-EXISTING / <composed-name 1..24>
Version des Bibliothekelements. Voreingestellt ist HIGHEST-EXISTING, d.h. die Prozedur wird dem Element mit der höchsten Version entnommen.
TYPE = *STD / *BY-LATEST-MODIFICATION / <alphanum-name 1..8>
Bestimmt den Elementtyp, unter dem die Prozedur in der PLAM-Bibliothek abgelegt ist.
TYPE = *STD
Die Prozedur kann als Element des Typs SYSJ oder J abgelegt sein.
Das angegebene Element wird zuerst unter den Elementen vom Typ SYSJ gesucht. Falls es dort nicht existiert, wird unter den Elementen vom Typ J weitergesucht.
Eine Nicht-S-Prozedur kann nur als Element vom Typ J vorliegen.
Eine S-Prozedur kann sowohl als Text-Prozedur (ursprüngliches Textformat) als auch als Objekt-Prozedur (kompiliertes Zwischenformat) vorliegen. Zur Vereinfachung der Verwaltung beider Formate in einer Bibliothek sollten Text-Prozeduren als Element vom Typ J und Objekt-Prozeduren als Element vom Typ SYSJ ablegt sein. Mit dem Kommando COMPILE-PROCEDURE (Bestandteil des kostenpflichtigen Subsystems SDF-P) wird aus einer Text-Prozedur vom Typ J standardmäßig eine Objekt-Prozedur vom Typ SYSJ erzeugt.
Die Angabe von TYPE=*STD (Default-Wert) stellt sicher, dass bei Einhaltung dieser Konvention Objekt-Prozeduren bevorzugt aufgerufen werden.
TYPE = *BY-LATEST-MODIFICATION
Die Prozedur kann als Element des Typs SYSJ oder J abgelegt sein.
Existiert das angegebene Element sowohl als Typ SYSJ als auch J, wird das zuletzt geänderte Element aufgerufen. Bei gleichem Zeitstempel wird das Element vom Typ SYSJ aufgerufen.
Die Angabe von TYPE=*BY-LATEST-MODIFICATION stellt sicher, dass z.B. während der Testphase bei der Erstellung bzw. Erweiterung einer Prozedur das aktuellste Element aufgerufen wird.
TYPE = <alphanum-name 1..8>
Die Prozedur wird ausschließlich unter den Elementen des angegebenen Typs gesucht.
FROM-FILE = *VARIABLE(...)
nur möglich, wenn das kostenpflichtige Software-Produkt SDF-P geladen ist
Die Prozedur ist in einer S-Variablen vom Typ Liste abgelegt.
VARIABLE-NAME = <composed-name 1..255>
Name der S-Variablen.
PROCEDURE-PARAMETERS = *NO / <text 0..1800 with-low>
Parameterwerte, die an Stelle der entsprechenden symbolischen Parameter in die Prozedurdatei zu setzen sind. Für <text> gilt folgendes Format:
( { sympar= / paramwert / sympar=paramwert }[,...] )
sympar ist der Name eines symbolischen Schlüsselwortparameters, der im BEGIN-PROCEDURE-Kommando (Angabe ohne führendes Zeichen „&“) in der Nicht-S-Prozedurdatei bzw. im DECLARE-PARAMETER-Kommando der S-Prozedurdatei vereinbart worden ist.
paramwert ist der aktuelle Wert eines im BEGIN-PROCEDURE-Kommandos vereinbarten Schlüsselwort- oder Stellungsparameter (maximale Länge 254 Zeichen) bzw. eines im DECLARE-PARAMETER-Kommando vereinbarten
Prozedurparameters.
Als aktuelle Parameterwerte sind auch von Hochkommas eingeschlossene Zeichenfolgen (Strings) erlaubt. Der Wert muss in Hochkommas eingeschlossen werden, wenn er Leerzeichen oder Sonderzeichen enthalten soll. Hochkommas innerhalb von Strings sind zu verdoppeln. Kleinbuchstaben innerhalb von Strings bleiben erhalten.
Die leere Zeichenkette (Nullstring) wird als fehlender Parameterwert interpretiert und führt im Dialogbetrieb zur Anforderung während des Prozedurablaufs.
Während des Prozedurlaufs eingegebene Werte (Prompting) werden auch innerhalb von Strings in Großbuchstaben umgesetzt! Wird der aktuelle Wert eines Parameters während des Prozedurablaufs angefordert und der Benutzer drückt die K2-Taste, fragt das System mit der Meldung SSM2060, ob der Benutzer die Prozedur abbrechen will. Bei Fortsetzung der Prozedur wird der Wert erneut abgefragt.
Die aktuellen Parameterwerte „paramwert“ aus dem CALL-PROCEDURE-Kommando ersetzen die symbolischen Parameter wie folgt:
Für S-Prozeduren können die Parameter als Schlüsselwort- oder Stellungsparameter übergeben werden, da im DECLARE-PARAMETER-Kommando keine diesbezügliche Festlegung erfolgt. Auf einen Schlüsselwortparameters darf jedoch kein Stellungsparameter folgen. Prompting ist nur möglich, wenn dies vereinbart wurde (INITIAL-VALUE=*PROMPT).
Für Nicht-S-Prozeduren können die Parameter nur so übergeben werden, wie sie auch im BEGIN-PROCEDURE-Kommando vereinbart wurden, d.h. Stellungsparameter, wenn als solcher vereinbart, und Schlüsselwortparameter ebenfalls, wenn als solcher vereinbart.
Schlüsselwortparameter erhalten den aktuellen Wert aus der Parameterliste des CALL-PROCEDURE-Kommandos. Falls kein Wert angegeben wurde, wird der in der Prozedur vereinbarte Wert eingesetzt. Wurde dort auch kein Wert vereinbart, so wird dieser Wert im Dialogbetrieb erst bei Prozedurablauf angefordert. Letzteres wird als Prompting bezeichnet.
Den Zusammenhang der Parameterangaben in BEGIN-PROCEDURE und in CALL-PROCEDURE zeigt folgende Tabelle:
Angabe in BEGIN-PROCEDURE
&X=ABC
&X=
Angabe in
CALL-PROCEDUREX=
Prompting
Prompting
X=DEF
DEF
DEF
ohne
ABC
Prompting
Stellungsparameter erhalten der Reihe nach die aktuellen Parameterwerte aus dem CALL-PROCEDURE-Kommando zugeordnet, die ohne Schlüsselwort „sympar=“ angegeben sind. Wird im CALL-PROCEDURE-Kommando kein Wert angegeben (statt des Werts steht ein Komma), so wird er im Dialogbetrieb bei Prozedurablauf angefordert (Prompting) - sofern der Wert überhaupt benötigt wird.
LOGGING = *PARAMETERS(...) / *YES / *NO
Steuert die Protokollierung des Prozedurablaufs.
Der Operand LOGGING wird bei Aufruf von Nicht-S-Prozeduren ignoriert, da die Protokollierung dort nur im Prozedurkopf vereinbart werden kann (siehe BEGIN-PROCEDURE, Operand LOGGING).
Bei Protokollierung einer S-Prozedur wird jede abgearbeitete Prozedurzeile mit vorangestellter Zeilennummer und Prozedurstufe ausgegeben.
LOGGING = *PARAMETERS(...)
Die Protokollierung kann getrennt eingestellt werden für Kommando-/Anweisungszeilen und Datenzeilen.
CMD = *BY-PROC-TEST-OPTION / *YES / *NO
Gibt an, ob Kommandos protokolliert werden sollen. Voreingestellt ist BY-PROC-TEST-OPTION, d.h. keine Protokollierung (entspricht *NO) bzw. der Wert, den der Benutzer mit dem Kommando MODIFY-PROC-TEST-OPTIONS als Voreinstellung gewählt hat (Bestandteil des kostenpflichtigen Subsystems SDF-P).
DATA = *BY-PROC-TEST-OPTION / *YES / *NO
Gibt an, ob Datenzeilen protokolliert werden sollen. Voreingestellt ist BY-PROC-TEST-OPTION, d.h. keine Protokollierung (entspricht NO) bzw. der Wert, den der Benutzer mit dem Kommando MODIFY-PROC-TEST-OPTIONS als Voreinstellung gewählt hat (Bestandteil des kostenpflichtigen Subsystems SDF-P).
UNLOAD-ALLOWED = *YES / *NO
Legt fest, ob ein Programm, das zum Zeitpunkt des Prozeduraufrufs geladen ist, entladen werden darf. Der Schutz vor Programmentladung ist nur für das Entladen mit den Kommandos START-(EXECUTABLE-)PROGRAM, LOAD-(EXECUTABLE-)PROGRAM und CANCEL-PROGRAM gewährleistet.
Die Angabe YES wird ignoriert, wenn der Prozeduraufruf aus einer Prozedur erfolgt, für die UNLOAD-ALLOWED=*NO vereinbart wurde.
EXECUTION = *YES / *NO
Legt fest, ob die Prozedur nur zu Testzwecken analysiert werden oder auch ausgeführt werden soll.
Für Nicht-S-Prozeduren kann nur EXECUTION=*YES vereinbart werden.
Der Test ist mit MODIFY-SDF-OPTIONS (Operand MODE) möglich.
Kommando-Returncode
Die nachfolgenden Kommando-Returncodes können nur zurückgegeben werden, wenn die aufgerufene Prozedur selbst keinen Kommando-Returncode liefert (z.B. EXIT-PROCEDURE wegen Fehlers nicht ausgeführt).
Kommando-Returncodes, deren Maincode mit „SSM“ beginnt, können nur bei Aufruf einer Nicht-S-Prozedur zurückgegeben werden.
Kommando-Returncodes, deren Maincode mit „SDP“ beginnt, können nur bei Aufruf einer S-Prozedur zurückgegeben werden.
(SC2) | SC1 | Maincode | Bedeutung |
|---|---|---|---|
0 | CMD0001 | Ohne Fehler | |
2 | 0 | SSM2058 | Protokoll-Typ-Fehler |
2 | 0 | SSM2065 | EOF auf Prozedurdatei, /END-PROC simuliert |
1 | SSM2036 | Unvollständiger Operand | |
1 | SSM2054 | Symbolischer Operandenfehler | |
1 | SSM2055 | Symbolischer Operandenfehler in /BEGIN-PROC | |
1 | SDP0138 | Fehler bei Voranalyse der Text-Prozedur oder Objekt-Prozedur fehlerhaft | |
1 | CMD0202 | Syntaxfehler | |
3 | CMD2203 | Falsche Syntaxdatei | |
32 | CMD0221 | Systemfehler (interner Fehler) | |
64 | SDP0093 | Nicht-S-Prozedur kann nur Element vom Typ J sein | |
64 | SDP0144 | Fehler bei Parameterübertragung | |
64 | SSM2052 | DVS-Fehler (Open-Fehler) | |
64 | SSM2053 | keine SAM/ISAM-Datei oder Datei beginnt nicht mit /BEGIN-PROC bzw. /PROC | |
64 | SSM2056 | Parameter von /CALL-PROC und /BEGIN-PROC passen nicht zusammen | |
64 | SSM2061 | Fehler bei Zugriff auf Bibilothekselement | |
64 | SSM2064 | Prozedurdatei kann nicht von entferntem Rechner geholt werden | |
130 | SDP0099 | Kein Adressraum mehr verfügbar | |
xx | xx | xxxxxxx | sonstige Returncodes der aufgerufenen Prozedur |
Hinweise
Symbolische Operanden können an beliebiger Stelle in allen Kommandos der Prozedurdatei verwendet werden. Sie können jedoch nicht den führenden Schrägstrich eines Kommandos ersetzen.
Bei der Protokollierung der bearbeiteten Prozedursätze nach SYSOUT werden symbolische Operanden durch die aktuellen Operandenwerte ersetzt.
Prozedurdateien können mit Kennwörtern gegen Lesen, Überschreiben und Ausführen geschützt werden, z.B. im MODIFY-FILE-ATTRIBUTES-Kommando. Das Ausführungs-Kennwort oder ein höherwertiges Kennwort muss in einem ADD-PASSWORD-Kommando angegeben werden, bevor ein CALL-PROCEDURE-Kommando gegeben wird.
Bei Verwendung eines Bibliothekelements wird eine temporäre SAM-Datei mit dem Namen S.IN.bibliothek.element.tsn.hhmmss.nnnn erstellt (nur für Nicht-S-Prozeduren), die das Element enthält. Es bedeuten:
bibliothek
Bibliotheksname (maximal 20 Zeichen werden gedruckt)
tsn
Auftragsnummer
hhmmss
Uhrzeit in Stunden-Minuten-Sekunden
nnnn
Laufnummer
Diese temporäre Datei wird bei folgenden Kommandos automatisch gelöscht:
/EXIT-JOB bzw. /LOGOFF in der ENTER-Datei
/END-PROCEDURE in der Prozedur
Wird das CALL-PROCEDURE-Kommando über den CMD-Makro aufgerufen, so wird das aufrufende Programm entladen. Eine im Programm definierte ABEND-STXIT-Routine wird nicht aktiviert. (CMD-Makro, ABEND-STXIT-Routine, siehe Handbuch „Makroaufrufe an den Ablaufteil“ [22].)
Enthält eine Nicht-S-Prozedur außer Kommandosätzen auch Anweisungs- oder Datensätze, so muss in der Prozedurdatei vor diese Sätze folgender Kommandosatz geschrieben werden:
/ASSIGN-SYSDTA TO=*SYSCMDDiese Zuordnung muss innerhalb einer Schachtelung nicht wiederholt werden. In S-Prozeduren ist dies abhängig von der Einstellung im Kommando SET-PROCEDURE-OPTIONS.