Domain: PROCEDURE
Command description
The procedure parameters needing an actual value during the procedure run are declared with the DECLARE-PARAMETER command. Furthermore, the way the parameter values are passed to the procedure is defined (initial value, prompting, ...). Procedure parameters may only be declared in the procedure header.
Procedure parameters are variables local to the procedure in SDF-P: When defined in the procedure header, they implicitly have SCOPE = *CURRENT.
The names of the procedure parameters are also keywords for the procedure parameters in the PROCEDURE-PARAMETERS operand of the CALL-PROCEDURE, ENTER-PROCEDURE and INCLUDE-PROCEDURE commands.
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 |
Operands
NAME = list-poss (2000): <structured-name 1..20>(...)
Determines the name of the procedure parameter.
INITIAL-VALUE =
Determines the initial value of the procedure parameter.
INITIAL-VALUE = *NONE
No initial value is declared; the procedure parameter is not initialized. A value must be assigned to the procedure parameter when the procedure is called (see section “Passing procedure parameters”).
INITIAL-VALUE = *PROMPT(...)
If the procedure parameter does not yet contain a value the first time a read access is carried out, the value is requested in dialog. If this happens, the value is always converted into uppercase letters. If the value is enclosed between apostrophes, these are removed. If a dialog request is not possible, error message SDP0219 is output.
PROMPT-STRING =
Defines a string to be output as the prompt string (to prompt for input). The text specified in DEFAULT-VALUE = ... is added to the prompt string. The prompt always ends with a colon. The following then appears as the prompt:<prompt-string> (DEFAULT = <default-value>) :
PROMPT-STRING = *STD
The parameter name (variable name) specified in NAME=... is output by default.
PROMPT-STRING = <text 0..1800 with-low string-expr>Defines the string to be output as the prompt string.
DEFAULT-VALUE =
Defines an initial value in case nothing was input in the dialog (i.e. only 
) or when the procedure runs in the background. The value is output as part of the prompt (for informational purposes).
DEFAULT-VALUE = *NONE
No (default) string is defined.
DEFAULT-VALUE = <text 0..1800 with-low expr>
Expression to be used as the default for the initial value. The expression specified must match the type of the parameter.
SECRET-INPUT = *NO / *YES
You can define if the input is to be entered secretly (i.e. will not be displayed) in the dialog. The input is also not logged in this case.
INITIAL-VALUE = <text 0..1800 with-low expr>
Determines an initial value. The specified expression must match the data type of the procedure parameter. This initial value applies unless some other value is passed when the procedure is called.
TYPE =
Determines the data type of the procedure parameter.
TYPE = *ANY
Stipulates that the procedure parameter can be assigned any STRING, INTEGER or BOOLEAN value.
TYPE = *STRING
Assigns the data type STRING to the procedure parameter.
Value range: any character string.
TYPE = *INTEGER
Assigns the data type INTEGER to the procedure parameter.
Value range: Integer between -231 and -231-1
TYPE = *BOOLEAN
Assigns the data type BOOLEAN to the procedure parameter.
Value range: TRUE, FALSE, YES, NO, ON, OFF
TRANSFER-TYPE =
Declares whether the entered character string is to be interpreted as a value or a variable name.
TRANSFER-TYPE = *BY-VALUE
The specified character string is a value.
A procedure-local variable which accepts this value is declared. Nothing is returned to the calling procedure. The procedure parameter is used only as an input parameter. This is the same as the transfer mechanism in non-S procedures. The value of the entered argument overwrites the initial value in the DECLARE-PARAMETER command. If a value is not transferred to the procedure parameter, the initial value in the DECLARE-PARAMETER command applies. If INITIAL-VALUE = *NONE is defined, a value must be entered for this procedure parameter.
The entered string must be convertible to the type of the formal procedure parameter. A formal procedure parameter with TYPE = *ANY is always assigned the current type STRING.
Since procedure parameters are variables for the purposes of SDF-P, their values can be changed during procedure execution.
TRANSFER-TYPE = *BY-REFERENCE
The specified character string is the name of a variable containing the value of the procedure parameter. Each access to the procedure parameter in the called procedure is an access to the same variable in the calling procedure.
Command return codes
If DECLARE-PARAMETER is used in the procedure head of an S procedure, it is completely evaluated during procedure analysis. Any error is thus an error during procedure preparation; the procedure has not been executed when the error occurs. (For further details, see the command return codes for CALL-PROCEDURE or INCLUDE-PROCEDURE.) The following return codes can thus appear only if DECLARE-PARAMETER is used in another (i.e. wrong) context.
(SC2) | SC1 | Maincode | Meaning |
| 0 | CMD0001 | No error | |
| 1 | CMD0202 | Syntax error | |
| 1 | SDP0118 | Command in false context | |
| 3 | CMD2203 | Incorrect syntax file | |
| 32 | CMD0221 | System error (internal error) | |
| 130 | SDP0099 | No further address space available |
Example 1: Demonstration of prompting
In the procedure PROC.PROMPT, a procedure parameter is declared such that the system prompts the user for a value when the procedure is called. In this example, the parameter is the German name of a color, which is then translated into English.
/SET-PROCEDURE-OPTIONS /DECLARE-PARAMETER NAME(INITIAL-VALUE=*PROMPT- / (PROMPT-STRING='ENTER THE NAME OF THE COLOR TO BE TRANSLATED',- / 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
When the procedure is called, the first occurrence of the procedure parameter NAME, for which the system is to prompt the user for a value, causes the prompt message to be displayed. When the user enters a color (in German), this color is then translated into English.
(IN) /CALL-PROC PROC.PROMPT (OUT) %PLEASE ENTER THE NAME OF THE COLOR TO BE TRANSLATED (DEFAULT = ROT): (IN) ROT (OUT) NAME = ROT (OUT) COLOR = RED
Example 2: Effect of TRANSFER-TYPE
In Procedure P, procedure parameter PAR1 is declared with TRANSFER-TYPE = *BY-VALUE.
/DECLARE-PARAMETER PAR1(TYPE = *STRING,TRANSFER-TYPE = *BY-VALUE)
The type of parameter passing to an S procedure during the procedure call is the same as the type of the procedure transfer for non-S procedures.
The procedure could be called as follows:
/CALL-PROCEDURE P,PROCEDURE-PARAMETER=(PAR1 = ABC)
/CALL-PROCEDURE P,PROCEDURE-PARAMETER=(PAR1 = 'ABC')
In both instances, the string ’ABC’ is entered. Note that a write access to PAR1 can also be carried out within P; however, this has no effect on the environment of the caller. If the value of variable X is transferred to PAR1, an expression replacement operation must be used (with the valid escape character):
/CALL-PROCEDURE P,PROCEDURE-PARAMETER=(PAR1 = &X)
&X means that the value of variable X is entered. Changes to PAR1 have no effect for the calling procedure.
Procedure parameter PAR2 is declared in procedure P with TRANSFER-TYPE =
*BY-REFERENCE
/DECLARE-PARAMETER PAR2(TYPE = *STRING, TRANSFER-TYPE = *BY-REFERENCE)
Procedure P could be called as follows:
/CALL-PROCEDURE P,PROCEDURE-PARAMETER=(PAR2 = ABC)
/CALL-PROCEDURE P,PROCEDURE-PARAMETER=(PAR2 = 'ABC')
In both instances, each access to variable PAR2 is actually an access to variable ABC in the calling procedure.
Example 3
In dialog, variable ABC is declared and assigned the value LEVEL0.Procedure P is subsequently called.
/ABC = 'LEVEL0'
/CALL-PROCEDURE P,(ABC)
Procedure parameter PAR3 is declared in procedure P:
/DECLARE-PARAMETER PAR3(TYPE = *STRING, TRANSFER-TYPE = *BY-REFERENCE)
Procedure P contains the following command sequence:
/ABC = PAR3 /PAR3 = 'LEVEL1' /SHOW-VARIABLE ABC /EXIT-PROCEDURE
The assignment ABC = PAR3 means that variable ABC is implicitly declared in procedure P and is assigned the contents of procedure parameter PAR3, i.e. the contents of the variable ABC initialized in dialog (’LEVEL0’).
Procedure parameter PAR3 is then assigned the value ’LEVEL1’ and thus simultaneously assigned the variable ABC on the interactive level.
The SHOW-VARIABLE command is used to output the contents of variable ABC, which is visible in procedure P, i.e. the variable implicitly declared in procedure P during the first assignment (contents: LEVEL0).
Procedure P is terminated with EXIT-PROCEDURE.
The following command is now called in dialog:
/SHOW-VARIABLE ABC
This command then accesses the variable ABC declared in dialog. Since the contents of this variable are influenced by procedure parameter PAR3 in procedure P, SHOW-VARIABLE shows LEVEL1 as the variable contents (in procedure P, procedure parameter PAR3 was assigned this value).
Example 4
PROC.1
/SET-PROCEDURE-OPTIONS
/DECLARE-VARIABLE GARDEN(TYPE = *STRUCTURE(DEFINITION=*DYNAMIC))
/ GARDEN.CHAIR = 4
/ GARDEN.TABLE = 1
/ GARDEN.FURNIT = 0
/CALL-PROCEDURE PROC.2,(,&(GARDEN.TABLE),-
/ &(GARDEN.CHAIR),GARDEN.FURNIT)
/SHOW-VARIABLE GARDEN.FURNIT
GARDEN.FURNIT = 5
PROC.2
/SET-PROCEDURE-OPTIONS
/BEGIN-PARAMETER-DECLARATION
/DECLARE-PARAMETER ART('WINTERGARDEN',TRANSFER-TYPE=*BY-VALUE)
/DECLARE-PARAMETER TABLE(*NONE,TYPE=*INTEGER,TRANSFER-TYPE=*BY-VALUE)
/DECLARE-PARAMETER CHAIRS(0,TYPE=*INTEGER,TRANSFER-TYPE=*BY-VALUE)
/DECLARE-PARAMETER TOTAL(0,TRANSFER-TYPE=*BY-REFERENCE)
/END-PARAMETER-DECLARATION
/TOTAL=(TABLE)+(CHAIRS)
/SHOW-VARIABLE ART
/SHOW-VARIABLE TABLE
/SHOW-VARIABLE CHAIRS
/SHOW-VARIABLE TOTAL
ART = WINTERGARDEN
TABLE = 1
CHAIRS = 4
TOTAL = 5
The formal procedure parameter ART is assigned the current procedure parameter, which is an empty procedure parameter. ART is initialized with ’WINTERGARDEN’.
The second current procedure parameter cannot be a blank procedure parameter. This is made mandatory by INIT-VALUE = *NONE. The value of GARDEN.TABLE is transferred to the formal procedure parameter TABLE.
CHAIRS is assigned the value of GARDEN.CHAIR. The initial value 0 is overwritten by 4.