Anwendungsgebiet: PROCEDURE
Kommandobeschreibung
Mit dem Kommando DECLARE-PARAMETER werden die Prozedurparameter deklariert, die während des Prozedurablaufs eine (konkreten) Wert benötigen. Des Weiteren wird die Art und Weise der Übergabe der Parameterwerte an die Prozedur vereinbart (Anfangswert, Prompting, ...). Die Deklaration von Prozedurparametern ist nur im Prozedurkopf erlaubt.
Prozedurparameter sind in SDF-P prozedurlokale Variablen: Bei der Definition im Prozedurkopf erhalten sie implizit den Geltungsbereich SCOPE = *CURRENT.
Die Namen der Prozedurparameter sind gleichzeitig die Schlüsselwörter der Prozedurparameter im Operanden PROCEDURE-PARAMETERS der Kommandos CALL-, ENTER- und INCLUDE-PROCEDURE.
Format
DECLARE-PARAMETER |
NAME = list-poss(2000): <structured-name 1..20>(...) <structured-name 1..20>(...) INITIAL-VALUE = *NONE / *PROMPT(...) / <text 0..1800 with-low expr> *PROMPT(...) PROMPT-STRING = *STD / <text 0..1800 with-low string-expr> ,DEFAULT-VALUE = *NONE / <text 0..1800 with-low expr> ,SECRET-INPUT = *NO / *YES ,TYPE = *ANY / *STRING / *INTEGER / *BOOLEAN ,TRANSFER-TYPE = *BY-VALUE / *BY-REFERENCE |
Operandenbeschreibung
NAME = list-poss (2000): <structured-name 1..20>(...)
Bestimmt den Namen des Prozedurparameters.
INITIAL-VALUE =
Bestimmt den Anfangswert des Prozedurparameters.
INITIAL-VALUE = *NONE
Der Prozedurparameter wird nicht initialisiert; es wird kein Anfangswert vereinbart. Dem Prozedurparameter muss beim Prozeduraufruf ein Wert zugewiesen werden (siehe „Prozedurparameter übergeben“).
INITIAL-VALUE = *PROMPT(...)
Falls der Prozedurparameter beim ersten lesenden Zugriff noch keinen Wert enthält, wird der Wert im Dialog abgefragt. Ist das der Fall, wird der Wert stets in Großbuchstaben konvertiert. Wenn der Wert in Hochkommata eingeschlossen ist, werden diese entfernt. Ist keine Dialogabfrage möglich, wird die Fehlermeldung SDP0219 ausgegeben.
PROMPT-STRING =
Definiert eine Zeichenfolge, die als Prompt-String (Eingabeaufforderung) ausgegeben wird. Der Prompt-String wird durch den bei DEFAULT-VALUE = ... angegebenen Text ergänzt. Die Eingabeaufforderung endet immer mit einem Doppelpunkt. Als Eingabeaufforderung erscheint dann:
<prompt-string>' '(DEFAULT = <default-value>)'BLANK':
PROMPT-STRING = *STD
Als Voreinstellung wird der bei NAME=... angegebene Parametername (Variablenname) ausgegeben.
PROMPT-STRING = <text 0..1800 with-low string-expr>
Definiert die Zeichenfolge, die als Prompt-String ausgegeben wird.
DEFAULT-VALUE =
Definiert einen Anfangswert für den Fall, dass im Dialog keine Eingabe (d.h. nur 
) erfolgt oder die Prozedur im Hintergrund abläuft. Der Wert wird (zur Information) als Teil der Eingabeaufforderung mit ausgegeben.
DEFAULT-VALUE = *NONE
Es wird keine (Default-)Zeichenfolge vereinbart.
DEFAULT-VALUE = <text 0..1800 with-low expr>
Ausdruck, der als Default für den Anfangswert benutzt wird. Der angegebene Ausdruck muss zum Typ des Parameters passen.
SECRET-INPUT = *NO / *YES
Es kann vereinbart werden, ob die Eingabe im Dialog geschützt über ein dunkelgesteuertes Feld erfolgt; die Eingabe wird in diesem Fall auch nicht protokolliert.
INITIAL-VALUE = <text 0..1800 with-low expr>
Bestimmt einen Anfangswert. Der angegebene Ausdruck muss zum Datentyp des Prozedurparameters passen (Hochkommas bei String-Literalen!). Der Anfangswert gilt, wenn beim Aufruf kein anderer Wert übergeben wird.
TYPE =
Bestimmt den Datentyp des Prozedurparameters.
TYPE = *ANY
Bestimmt, dass dem Prozedurparameter beliebig wechselnde Werte vom Typ STRING, INTEGER oder BOOLEAN zugewiesen werden können.
TYPE = *STRING
Weist dem Prozedurparameter den Datentyp STRING zu.
Wertebereich: beliebige Zeichenkette
TYPE = *INTEGER
Weist dem Prozedurparameter den Datentyp INTEGER zu.
Wertebereich: Ganzzahl zwischen -231 und +231-1
TYPE = *BOOLEAN
Weist dem Prozedurparameter den Datentyp BOOLEAN zu.
Wertebereich: TRUE, FALSE, YES, NO, ON, OFF
TRANSFER-TYPE =
Vereinbart, ob die übergebene Zeichenkette als Wert oder als Variablenname interpretiert werden soll.
TRANSFER-TYPE = *BY-VALUE
Die angegebene Zeichenkette ist ein Wert.
Es wird eine prozedurlokale Variable angelegt, die diesen Wert übernimmt. An die aufrufende Prozedur wird nichts zurückgegeben. Der Prozedurparameter dient lediglich als Eingabeparameter.
Dies gleicht dem Übergabemechanismus in Nicht-S-Prozeduren. Der Wert des übergebenen Argumentes überschreibt den Anfangswert aus dem DECLARE-PARAMETER-Kommando. Wird dem Prozedurparameter kein Wert übergeben, gilt der Anfangswert aus dem DECLARE-PARAMETER-Kommando. Falls INITIAL-VALUE = *NONE definiert ist, muss für diesen Prozedurparameter ein Wert übergeben werden.
Der übergebene String muss in den Typ des formalen Prozedurparameters konvertierbar sein. Ein formaler Prozedurparameter vom TYPE = *ANY erhält dann immer den aktuellen Typ STRING.
Da die Prozedurparameter Variablen im Sinne von SDF-P sind, können ihre Werte während des Prozedurablaufes geändert werden.
TRANSFER-TYPE = *BY-REFERENCE
Die angegebene Zeichenkette ist der Name einer Variablen, die den Wert des Prozedurparameters enthält. Jeder Zugriff auf den Prozedurparameter in der aufgerufenen Prozedur ist ein Zugriff auf diese Variable in der rufenden Prozedur.
Kommando-Returncode
Wenn DECLARE-PARAMETER im Prozedurkopf einer S-Prozedur benutzt wird, wird es während der Prozeduranalyse vollständig ausgewertet. Jeder Fehler ist also ein Fehler während der Prozedurvorbereitung; die Prozedur wurde zu diesem Zeitpunkt noch nicht ausgeführt. (Siehe dazu den Kommando-Returncode von CALL-PROCEDURE oder INCLUDE-PROCEDURE.) Nur wenn DECLARE-PARAMETER in einem anderen (d.h. falschen) Kontext benutzt wird, erscheinen die folgenden Returncodes.
(SC2) | SC1 | Maincode | Bedeutung |
| 0 | CMD0001 | Ohne Fehler | |
| 1 | CMD0202 | Syntaxfehler | |
| 1 | SDP0118 | Kommando im falschen Kontext | |
| 3 | CMD2203 | Falsche Syntaxdatei | |
| 32 | CMD0221 | Systemfehler (interner Fehler) | |
| 130 | SDP0099 | Kein Adressraum mehr verfügbar |
Beispiel 1: Veranschaulichung des Prompting
In der Prozedur PROC.PROMPT wird ein Prozedurparameter deklariert, der erst bei Aufruf der Prozedur im Dialog abgefragt bzw. „gepromptet“ wird. Es handelt sich dabei um eine deutsche Farbenbezeichnung, die durch die Prozedur ins Englische übersetzt wird.
/SET-PROCEDURE-OPTIONS /DECLARE-PARAMETER NAME(INITIAL-VALUE=*PROMPT- / (PROMPT-STRING='NAME DER ZU UEBERSETZENDEN FARBE EINGEBEN',- / DEFAULT-VALUE='ROT')) /COLOR=TRANSLATE(STRING=NAME-, /,WHEN1='ROT', THEN1='RED'-, /,WHEN2='GRUEN', THEN2='GREEN'-, /,WHEN3='BLAU', THEN3='BLUE'-, /,WHEN4='GELB', THEN4='YELLOW'-, /,WHEN5='SCHWARZ',THEN5='BLACK'-, /,WHEN6='WEISS', THEN6='WHITE'-, /,ELSE='UNKNOWN') /SHOW-VAR NAME /SHOW-VAR COLOR
Nach dem Aufruf der Prozedur erfolgt mit dem ersten Auftreten des zu „promptenden“ Prozedurparameters NAME die Eingabeaufforderung für die zu übersetzende Farbe. Gibt man diese ein, wird sie im Anschluss daran übersetzt.
(IN) /CALL-PROC PROC.PROMPT (OUT) %BITTE NAME DER ZU UEBERSETZENDEN FARBE EINGEBEN (DEFAULT = ROT): (IN) ROT (OUT) NAME = ROT (OUT) COLOR = RED
Beispiel 2: Wirkung von TRANSFER-TYPE
In der Prozedur P wird der Prozedurparameter PAR1 deklariert mit TRANSFER-TYPE = *BY-VALUE.
/DECLARE-PARAMETER PAR1(TYPE = *STRING,TRANSFER-TYPE = *BY-VALUE)
Die Art der Parameterübergabe an eine S-Prozedur beim Prozeduraufruf unterscheidet sich dann nicht von der Art der Parameterübergabe bei Nicht-S-Prozeduren.
Die Prozedur könnte folgendermaßen aufgerufen werden:
/CALL-PROCEDURE P, PROCEDURE-PARAMETER = (PAR1 = ABC) /CALL-PROCEDURE P, PROCEDURE-PARAMETER = (PAR1 = 'ABC')
In beiden Fällen wird der String 'ABC' übergeben. Zu beachten ist, dass innerhalb von P auf PAR1 auch schreibend zugegriffen werden kann; dies hat aber auf die Umgebung des Aufrufers keine Wirkung. Soll an PAR1 der Wert einer Variablen X übergeben werden, muss Ausdrucksersetzung verwendet werden:
/CALL-PROCEDURE P, PROCEDURE-PARAMETER = (PAR1 = &X)
&X bedeutet, dass der Wert der Variablen X übergeben wird. Veränderungen von PAR1 haben für die rufende Prozedur keine Wirkung.
Der Prozedurparameter PAR2 wird in der Prozedur P deklariert mit TRANSFER-TYPE =*BY-REFERENCE
/DECLARE-PARAMETER PAR2(TYPE = *STRING, TRANSFER-TYPE = *BY-REFERENCE)
Die Prozedur P könnte folgendermaßen aufgerufen werden:
/CALL-PROCEDURE P, PROCEDURE-PARAMETER = (PAR2 = ABC) /CALL-PROCEDURE P, PROCEDURE-PARAMETER = (PAR2 = 'ABC')
In beiden Fällen gilt, dass jeder Zugriff auf die Variable PAR2 in Wirklichkeit ein Zugriff auf die Variable ABC in der rufenden Prozedur ist.
Beispiel 3
Im Dialog wird eine Variable ABC deklariert und ihr der Wert LEVEL0 zugewiesen.Anschließend wird die Prozedur P aufgerufen.
/ABC = 'LEVEL0' /CALL-PROCEDURE P,(ABC)
In der Prozedur P ist der Prozedurparameter PAR3 deklariert:
/DECLARE-PARAMETER PAR3(TYPE = *STRING, TRANSFER-TYPE = *BY-REFERENCE)
Die Prozedur P enthält folgende Kommandofolge:
/ABC = PAR3 /PAR3 = 'LEVEL1' /SHOW-VARIABLE ABC /EXIT-PROCEDURE
Die Zuweisung ABC = PAR3 bewirkt, dass in der Prozedur P implizit eine Variable ABC angelegt wird, der der Inhalt des Prozedurparameters PAR3 zugewiesen wird, das heißt der Inhalt der Variablen ABC, die im Dialog initialisiert wurde ('LEVEL0').
Anschließend wird dem Prozedurparameter PAR3 der Wert 'LEVEL1' zugewiesen, und damit gleichzeitig der Variablen ABC der Dialogebene.
Mit dem Kommando SHOW-VARIABLE wird der Inhalt der Variablen ABC ausgegeben, die in der Prozedur P sichtbar ist, also der Variablen, die implizit bei der ersten Zuweisung in der Prozedur P angelegt wurde (Inhalt: LEVEL0).
Mit EXIT-PROCEDURE wird die Prozedur P beendet.
Im Dialog wird jetzt folgendes Kommando aufgerufen:
/SHOW-VARIABLE ABC
Dieses Kommando greift jetzt auf die im Dialog angelegte Variable ABC zu. Da der Inhalt dieser Variablen über den Prozedurparameter PAR3 in der Prozedur P beeinflusst wird, zeigt SHOW-VARIABLE als Variableninhalt LEVEL1 (in der Prozedur P wurde dem Prozedurparameter PAR3 dieser Wert zugewiesen).
Beispiel 4
PROC.1
/SET-PROCEDURE-OPTIONS
/DECLARE-VARIABLE GARTEN(TYPE = *STRUCTURE(DEFINITION=*DYNAMIC))
/GARTEN.STUHL = 4
/GARTEN.TISCH = 1
/GARTEN.MOEBEL = 0
/CALL-PROCEDURE PROC.2, (,&(GARTEN.TISCH),-
/&(GARTEN.STUHL), GARTEN.MOEBEL)
/SHOW-VARIABLE GARTEN.MOEBEL
GARTEN.MOEBEL = 5
PROC.2
/SET-PROCEDURE-OPTIONS
/BEGIN-PARAMETER-DECLARATION
/DECLARE-PARAMETER ART('WINTERGARTEN',TRANSFER-TYPE=*BY-VALUE)
/DECLARE-PARAMETER TISCH(*NONE,TYPE=*INTEGER,TRANSFER-TYPE=*BY-VALUE)
/DECLARE-PARAMETER STUEHLE(0,TYPE=*INTEGER,TRANSFER-TYPE=*BY-VALUE)
/DECLARE-PARAMETER GESAMT(0,TRANSFER-TYPE=*BY-REFERENCE)
/END-PARAMETER-DECLARATION
/GESAMT=(TISCH)+(STUEHLE)
/SHOW-VARIABLE ART
/SHOW-VARIABLE TISCH
/SHOW-VARIABLE STUEHLE
/SHOW-VARIABLE GESAMT
ART = WINTERGARTEN
TISCH = 1
STUEHLE = 4
GESAMT = 5
Der formale Prozedurparameter ART wird dem ersten aktuellen Prozedurparameter zugeordnet, der ein leerer Prozedurparameter ist. ART wird mit 'WINTERGARTEN' initialisiert.Der zweite aktuelle Prozedurparameter darf kein leerer Prozedurparameter sein. Dies wird mit INIT-VALUE = *NONE erzwungen. Der Wert von GARTEN.TISCH wird dem formalen Prozedurparameter TISCH übergeben.
STUEHLE erhält den Wert von GARTEN.STUHL. Der Anfangswert 0 wird mit 4 überschrieben.