Domain: PROCEDURE
Command description
DECLARE-VARIABLE is used to define the attributes of this variable and possibly an initial value as well.
Job variables can be integrated in SDF-P via the CONTAINER operand.
It is possible to make what would normally be a procedure-local S variable in a local procedure accessible for a procedure called with CALL-PROCEDURE. To do this, DECLARE-VARIABLE VARIABLE-NAME=..., SCOPE = CURRENT or
SCOPE = PROCEDURE (IMPORT-ALLOWED=*YES) must be specified in the local procedure and IMPORT-VARIABLE VARIABLE-NAME= ...,
FROM=*SCOPE(SCOPE=*CALLING-PROCEDURES) in the called procedure.
Format
DECLARE-VARIABLE |
VARIABLE-NAME = list-poss(2000): <structured-name 1..20>(...) <structured-name 1..20>(...) INITIAL-VALUE = *NONE / <text 0..1800 with-low expr> ,TYPE = *ANY / *STRING / *INTEGER / *BOOLEAN / *STRUCTURE(...) *STRUCTURE(...) DEFINITION = *DYNAMIC / *BY-SYSCMD / <structured-name 1..20> ,MULTIPLE-ELEMENTS = *NO / *ARRAY(...) / *LIST(...) *ARRAY(...) LOWER-BOUND = 0 / *NONE / <integer -2147483648..2147483647> ,UPPER-BOUND = *NONE / <integer -2147483648..2147483647> *LIST(...) LIMIT = *NONE / <integer 1..2147483647> ,SCOPE= *CURRENT(...) / *PROCEDURE(...) / *TASK(...) *CURRENT(...) IMPORT-ALLOWED = *NO / *YES *PROCEDURE(...) IMPORT-ALLOWED = *NO / *YES *TASK(...) STATE = *ANY / *NEW / *OLD ,CONTAINER= *STD / <composed-name 1..64> / *VARIABLE(...) / *JV(...) *VARIABLE(...) VARIABLE-NAME = <structured-name 1..20> ,SCOPE= *VISIBLE / *TASK *JV(...) JV-NAME= <filename 1..54> ,STATE= *ANY / *NEW / *OLD |
Operands
VARIABLE-NAME = list-poss (2000): <structured-name 1..20>(...)
Declares the variable name, i.e. the name of a simple variable, which is not an element in a complex variable, or the name of a complex variable.
INITIAL-VALUE = *NONE
The variable is not initialized.
For a new variable, this means that the variable does not contain an initial value. A read access would produce an error.
If the variable is already present, its contents remain unchanged; it is not assigned a new initial value.
INITIAL-VALUE = <text 0..1800 with-low expr>
Assigns an initial value to a new variable; the value must match the data type of the variable and can also be specified as an expression.
The entry is ignored for existing variables; they are not assigned a new initial value.Complex variables cannot be initialized in their entirety, i.e. INITIAL-VALUE cannot be used to assign a new initial value to these variables.
TYPE =
Assigns the data type to the variable.
TYPE = *ANY
The variable can be assigned any value of data types STRING, INTEGER and BOOLEAN.
TYPE = *STRING
Assigns the data type STRING to the variable.
Value range: any character string.
TYPE = *INTEGER
Assigns the data type INTEGER to the variable.
Value range: integer between -231 and +231-1.
TYPE = *BOOLEAN
Assigns the data type BOOLEAN to the variable.
Value range: TRUE, FALSE, YES, NO, ON, OFF.
TYPE = *STRUCTURE(...)
Declares a complex variable of type “structure”.
DEFINITION = *DYNAMIC
Dynamically extendable structure.
DEFINITION = *BY-SYSCMD
Static structure whose elements are declared exclusively by commands in the SYSCMD stream.
DEFINITION = <structured-name 1..20>
Name of the structure layout.
MULTIPLE-ELEMENTS = *NO
Determines that the variable is not an array or a list.
MULTIPLE-ELEMENTS = *ARRAY(...)
Declares a complex variable of type “array”.
LOWER-BOUND = 0 / <integer - 2147483648..2147483647>
Lower limit for the array index.
LOWER-BOUND = *NONE
No lower limit is defined for the array index.
UPPER-BOUND = *NONE
No upper limit is defined for the array index.
UPPER-BOUND = <integer -2147483648..2147483647>
Upper limit for the array index. The specified value must be greater than or equal to the value for LOWER-BOUND.
MULTIPLE-ELEMENTS = *LIST(...)
Declares a complex variable of type “list”.
LIMIT = *NONE
The number of list elements is unlimited.
LIMIT = <integer 1..2147483647>
Maximum number of list elements.
SCOPE =
Defines the variable scope.
SCOPE = *CURRENT
The variable is a procedure-local variable.
In call procedures, this corresponds to the entry PROCEDURE.
In include procedures, CURRENT means that the variable is declared in the current include procedure. It is then visible in this include procedure and in all include procedures on lower nesting levels (= scope: include).
IMPORT-ALLOWED =
Specifies whether the variable can be imported with IMPORT-VARIABLE in a called procedure.
IMPORT-ALLOWED = *NO
The variable cannot be imported with IMPORT-VARIABLE in a called procedure.
IMPORT-ALLOWED = *YES
The variable can be imported with IMPORT-VARIABLE in a called procedure.
SCOPE = *PROCEDURE
The variable is a procedure-local variable with the scope procedure.
The variable is declared in the current procedure.
In include procedures, the current procedure is always the superordinate call procedure from which the include procedure was called.
The variable is visible in this procedure and in all include procedures on lower nesting levels.
IMPORT-ALLOWED =
Specifies whether the variable can be imported with IMPORT-VARIABLE in a called procedure.
IMPORT-ALLOWED = *NO
The variable cannot be imported with IMPORT-VARIABLE in a called procedure.
IMPORT-ALLOWED = *YES
The variable can be imported with IMPORT-VARIABLE in a called procedure.
SCOPE = *TASK(...)
The variable is a task-global variable.
If it is declared in an include procedure, it is also visible in the superordinate call procedure from which the include procedure was called and in all include procedures on lower nesting levels.
STATE = *ANY
If a variable with the specified name already exists in the task, this variable is used; otherwise a new variable is declared.
STATE = *NEW
The task should not contain any variables with the specified name.
STATE = *OLD
The task must contain a variable with the specified name. The current variable declaration must then match the declaration of the existing variable.
CONTAINER = *STD
The variable is assigned no variable container. The value of the variable is stored in a class 5 memory.
CONTAINER = <composed-name 1..64>
Links the currently declared variable with the variable container specified here.
This variable container must already be open. “*STD” must not be specified here, because it is not interpreted as a variable container with a permanent existence.
CONTAINER = *VARIABLE(...)
Links the currently declared variable to another variable already defined in this procedure via a link mechanism. This variable is then known as the variable container.
Structure elements cannot be specified as variable containers.
VARIABLE-NAME = <structured-name 1..20>
Name of a variable already defined in the procedure. The variable attributes used as variable containers and the currently declared variable must be compatible with each other.
SCOPE =
Scope of the container variable.
SCOPE = *VISIBLE
The variable is visible.
SCOPE = *TASK
Task variable.
CONTAINER = *JV(...)
Defines a job variable as a variable container: the currently declared variable is linked to a job variable, i.e. the value of the variable is stored in the job variable.
Variable containers having the type JV can be linked only to simple variables declared with TYPE = *STRING, and the string can be no more than 256 bytes long.
Complex variables cannot be linked to variable containers having the type JV.
If a task-global variable (SCOPE = *TASK) is linked to a job variable, the STATE entries in TASK and JV operands must be logically compatible. It must be ensured that the redeclaration of an existing task-global variable does not generate a new job variable.
Job variables are part of the chargeable software product “Job Variables”. They are available only if the JV subsystem is loaded. See the “Job Variables” manual [5] for more information on job variables.
JV-NAME = <filename 1..54>
Name of the job variable.
STATE = *ANY
If a job variable with this name already exists, this job variable is used; otherwise a new job variable is declared.
STATE = *OLD
The job variable must already exist.
STATE = *NEW
A new job variable is declared; the job variable should not already exist.
Command return code
(SC2) | SC1 | Maincode | Meaning/Guaranteed messages |
| 0 | CMD0001 | No error | |
| 1 | 0 | CMD0001 | Nothing executed; element already declared |
| 1 | CMD0202 | Syntax error | |
| 3 | CMD2203 | Incorrect syntax file | |
| 32 | CMD0221 | System error (internal error) | |
| 64 | CMD0216 | Do not have required privilege | |
| 64 | SDP0091 | Semantic error Guaranteed messages: SDP1018, SDP1030 | |
| 130 | SDP0099 | No further address space available |
Example 1
/DECLARE-VARIABLE A, SCOPE = *TASK
Variable A is declared as a task-global variable with TYPE = *ANY.
Example 2
/DECLARE-VARIABLE DATA(C'ANTON',*ANY)
The procedure-local variable DATA having the type *ANY is initialized with the string ’ANTON’.
Example 3
/DECLARE-VARIABLE LOGO(TRUE, *BOOLEAN)
The local Boolean variable LOGO is assigned the Boolean value TRUE.
Example 4
/DECLARE-VARIABLE LEN, SCOPE = *TASK
The variable LEN is declared.
Example 5
/DECLARE-VARIABLE BEG, TYPE = *STRING, SCOPE = *TASK, CONTAINER =
*JV(BEGIN.DAT)
The system searches for the job variable BEGIN.DAT. If it is not located, a job variable with this name is cataloged. The value of BEG is always stored in the job variable BEGIN.DAT.
Example 6
A task-global variable with the name A is declared for the ID:
/DECLARE-VARIABLE A, SCOPE = *TASK
A procedure is created which declares a variable having the name A and SCOPE = *PROCEDURE:
/SET-PROCEDURE-OPTIONS /DECLARE-VARIABLE A, SCOPE = *PROCEDURE ... /A = FILE1 /DELETE-FILE &A ... .... /CREATE-FILE &A, ... /...
Each time &A is used within the procedure, the contents of the local variable are accessed.
Example 7
A task-global variable VAR-A exists for the ID:
/DECLARE-VARIABLE VAR-A, SCOPE = *TASK
/VAR-A = ’TASK VARIABLE OF USER ID’
The procedure PROCEDUR.1 is called:
PROCEDUR.1 /SET-PROCEDURE-OPTIONS /DECLARE-VARIABLE VAR-A, SCOPE = *PROCEDURE /VAR-A = ’LOCAL VARIABLE FROM PROCEDURE 1’ /CALL-PROCEDURE PROCEDUR.2 /SHOW-VARIABLE VAR-A
’LOCAL VARIABLE FROM PROCEDURE 1’ is output; in this procedure, VAR-A is declared as a local variable.
PROCEDUR.2 /SET-PROCEDURE-OPTIONS /DECLARE-VARIABLE VAR-A, SCOPE = *TASK /SHOW-VARIABLE VAR-A
’TASK VARIABLE OF USER ID’ is output, since the global variable is accessed.
Example 8
Example of an extendable structure, even if implicit declarations are forbidden:
/DECLARE-VARIABLE A(TYPE = *STRUCTURE(*DYNAMIC)) /SET-VARIABLE A.B = 7 /SET-VARIABLE A.X = TRUE /SET-VARIABLE A#1 = 0 “Error: array element name”
The structure now contains the elements A.B and A.X.
Example 9
Elements of dynamic structures can also be declared explicitly:
/DECLARE-VARIABLE A(TYPE = *STRUCT(*DYNAMIC)) /DECLARE-ELEMENT A.B(7, *INTEGER) /DECLARE-ELEMENT A.X(TRUE, *BOOLEAN) /SET-VARIABLE A#1 = 0 “Error: array element name”
The structure now contains the elements A.B and A.X.
Example 10
When using variable containers, the structure layouts must be visible before the variable is declared. These layouts must be compatible (in relation to the SET-VARIABLE command) with the structure of the variables which are saved in the variable container.
/BEGIN-STRUCTURE MYSTRUCT / DECLARE-ELEMENT ELEM1 / DECLARE-ELEMENT ELEM2 /END-STRUCTURE /OPEN-VARIABLE-CONTAINER MYCONT,FROM-FILE=*LIB-ELEM(MY-LIBRARY), - / AUTOMATIC-DECLARE=*NONE /DECLARE-VARIABLE MYVAR(TYPE=*STRUCTURE(MYSTRUCT)), CONTAINER=MYCONT - / “MYVAR IS CREATED IN THE VARIABLE CONTAINER” /MYVAR.ELEM1 = 'FIRST VALUE' /MYVAR.ELEM2 = 'SECOND VALUE' /SAVE-VARIABLE-CONTAINER MYCONT / /“THE LAYOUT, MYSTRUCT, IS NOW CHANGED (ONE ELEMENT IS SUPPRESSED,” /“A DIFFERENT ONE IS APPENDED AS A NEW ELEMENT)” / /BEGIN-STRUCTURE MYSTRUCT / DECLARE-ELEMENT ELEM2 / DECLARE-ELEMENT NEW-ELEM /END-STRUCTURE /OPEN-VARIABLE-CONTAINER MYCONT,FROM-FILE=*LIB-ELEM(MY-LIBRARY), - / AUTOMATIC-DECLARE=*NONE /DECLARE-VARIABLE MYVAR(TYPE=*STRUCTURE(MYSTRUCT)), CONTAINER=MYCONT - / “MYVAR IS RETRIEVED FROM THE VARIABLE CONTAINER” /SHOW-VARIABLE MYVAR MYVAR.ELEM2 = SECOND VALUE
Only MYVAR.ELEM2 is output, because MYVAR.ELEM1 has been suppressed and MYVAR.NEW-ELEM has not yet been initialized.
See IMPORT-VARIABLE Import variable for another example.