Domain: PROCEDURE
Command description
SET-VARIABLE can be used to assign values to simple as well as complex variables.
When assigning simple variables or variable elements, the data types must match. The structure of the variables must also match when assigning complex variables globally.
Note the following when complex variables are positioned on both sides of the assignment:
Are variable elements overwritten?
Is the complex variable extended?
Are variable elements of the right-hand complex variable ignored?
If the assignment affects complex variables having the type “array”, note that the order in which the contents of array elements are assigned to other elements is determined by the order of the array elements on the right-hand side of the assignment. The beginning and end of a section of list elements can be defined with list variables.
When entering the command, it is sufficient to enter
/<variable1 > = <variable2 > / <text>
instead of
/SET-VARIABLE <variable1 > = <variable2 > / <text>
Entering the command without using the command name is recommended for performance reasons (see "SDF syntax analysis ").
Note
The operands of the SET-VARIABLE command are evaluated only by SDF-P and must be entered as shown below. The command name may be omitted. The SDF abbreviation rules apply to the operands. SDF functions such as information about possible operand values or a correction dialog are not available at the operand level. In guided dialog, SDF provides only an input field with “# =”.
Format
SET-VARIABLE |
| <composed-name1 1..255> = <text 0..1800 with-low expr> / <composed-name2 1..255> / *STRING-TO-VARIABLE(...) / *LIST(...) *STRING-TO-VARIABLE(...) STRING = <text 0..1800 with-low expr> *LIST(...) LIST-NAME = <composed-name 1..255> ,FROM-INDEX = *FIRST / *LAST / <integer 1..2147483647> |
Operands
<composed-name1 1..255> =
Designates the variable whose value or contents are to be assigned to a different variable.The variable <composed-name1> can be a simple or a complex variable.
A simple variable is assigned a value that is determined by an expression. The expression must return a result whose type matches the data type used to declare the variable.
The rules for assigning values to complex variables are summarized in the table at the end of this command description.
If the variable is linked to another job variable through the container mechanism, then the result of the expression must fulfill the following conditions: data type = STRING, maximum length = 255 bytes.
<composed-name1 1..255> = <text 0..1800 with-low expr>
The variable composed-name1 is assigned a value determined by an expression.
<composed-name1 1..255> = <composed-name2 1..255>
The variable composed-name1 is assigned the contents of the variable composed-name2. The variable composed-name2 is a simple or a complex variable.
If composed-name1 is a list element, then this element must already exist, it cannot be created implicitly, even when implicit declarations are permitted. (Exception: The list header can be created with /list# = <value>). The rules for assigning complex variables are presented in the table at the end of this operand description.
<composed-name1 1..255> = *STRING-TO-VARIABLE(...)
Specifies that a string will be converted to an S variable of type Structure in accordance with the conversion rules (see section “Converting SDF command strings to S variables and viceversa” (Converting SDF command strings to S variables and vice versa )).
STRING = <text 0..1800 with-low expr>
Input string to be converted to an S variable.
VALUE-TYPE =
Specifies if the input string is to be converted to a variable of type string all the time or depending on its value. See conversion rule 4 (Converting SDF command strings to S variables and vice versa ) for more information.
VALUE-TYPE = *STD
The input string will be converted depending on its value (string/integer/Boolean). For empty list elements or list elements consisting of spaces, the corresponding elements of list variables are not created.
VALUE-TYPE = *STRING
The input string will always be converted to a variable of type string. For empty list elements or list elements consisting of spaces, the corresponding elements of list variables are created.
<composed-name1 1..255> = *LIST(...)
The variable <composed-name1> is assigned elements from a list variable.The variable <composed-name1> must be a simple or complex variable depending on the number of list elements assigned.
LIST-NAME = <composed-name 1..255>
Name of the list variable.
FROM-INDEX = *FIRST / *LAST / <integer 1..2147483647>
Index of the element of the list variable beginning with which a specified number of list elements will be assigned to the variable <composed-name1>.
*FIRST: The first assignment is made with the first element of the list (default setting).*LAST assigns precisely the last element if the list. In this case the NUMBER-OF-ELEMENTS operand is ignored.
NUMBER-OF-ELEMENTS = 1 / *REST / <integer 1..2147483647>
Number of list elements to be assigned. Default: One element will be assigned.
*REST assigns all elements from the start element specified (FROM-INDEX operand) to the last element of the list.
WRITE-MODE =
Specifies where the new variable contents are to be put by the assignment.
The table at the end of this operand description indicates which variables and values can be combined during the assignment, using the operand values of WRITE-MODE =.
WRITE-MODE = *REPLACE
The variable name on the left-hand side of the assignment must designate a simple or complex variable.
It must be possible to overwrite the variable or the elements of complex variables. (As a rule, a variable can be overwritten only if it is a container for a job variable with a write password and this password is not in the current password list.)
The contents of variables positioned to the left of the equals sign are deleted implicitly with FREE-VARIABLE; the variable is then overwritten by the value resulting from the entry to the right of the equals sign.
Arrays
An array must be positioned on both sides of the equals sign.
The elements in the left-hand array are overwritten by the elements on the right in the order in which they occur. If the right-hand array contains more elements, the left-hand array is extended. If the right-hand array contains fewer elements, the excess elements in the lefthand array are deleted (implicit FREE-VARIABLE).
Lists
A list must be positioned on both sides of the equals sign.
The elements in the left-hand list are overwritten by the elements on the right in the order in which they occur. If the right-hand list contains more elements, the left-hand list is extended. If the right-hand list contains fewer elements, the excess elements in the lefthand list are deleted (implicit FREE-VARIABLE).
Structures
A structure must be positioned on both sides of the equals sign.
Assignment to a static structure: elements in the left-hand structure are overwritten by the contents of elements on the right-hand side of the equals sign if the elements have the same element names. If the right-hand structure contains elements for which there is no counterpart in the left-hand structure, these elements are ignored.
Assignment to a dynamic structure: all elements in the right-hand structure are declared implicitly as elements in the left-hand structure.
WRITE-MODE = *MERGE
The variable name on the left-hand side of the assignment must designate a complex variable having the type “array” or “structure”.
The contents of the right-hand complex variable are assigned to the complex variable to the left of the equals sign.
If the complex variables to the left and right of the equals sign are identical,
WRITE-MODE = *MERGE has the same effect as WRITE-MODE = *REPLACE.
Arrays
An array must be positioned on both sides of the equals sign. The following applies if the arrays contain elements with the same array index:
The element in the left-hand array is assigned the contents of the right-hand array element, which has the same array index. Array elements for which there is no counterpart with the same array index on the left-hand side of the assignment are declared.
Structures
A structure must be specified on both sides of the equals sign.
Assignment to a static structure: elements in the left-hand structure are assigned the contents of elements on the right-hand side of the equals sign if the elements have the same element names. If the right-hand structure contains elements for where there is no counterpart in the left-hand structure, the elements in the left-hand structure are ignored. If the left-hand structure contains elements for which there is no counterpart in the right-hand structure, these elements remain unaffected.
Assignment to a dynamic structure: all elements in the right-hand structure are declared implicitly as elements in the left-hand structure.
WRITE-MODE = *EXTEND
Only for variables having the type “list”.
The right-hand side of the assignment must be an expression or designate a complex variable having the type “list”.
The list on the left-hand side of the assignment is extended:
If the assignment on the right-hand side contains an expression, one element is added to the list; the result of the expression is assigned to this element.
If the assignment on the right-hand side contains the variable name of a list, this list (right) is appended to the list (left): the corresponding number of elements is added to the original list; the contents of the elements in the right-hand list are assigned to these elements in the order in which they occur.
WRITE-MODE = *PREFIX
Only for variables having the type “list”.
The right-hand side of the assignment must be an expression or designate a complex variable having the type “list”.
The list on the left-hand side of the assignment is extended:
If the assignment on the right-hand side contains an expression, a new element is inserted in front of what was previously the first element in the list; the result of the expression is assigned to this element.
If the assignment on the right-hand side contains the variable name of a list, this (righthand) list is inserted into the (left-hand) list in front of what was previously the first element. The (left-hand) list is extended forward to include the same number of elements present in the (right-hand) list. The contents of the elements in the right-hand list are assigned to the new elements in the order in which they occur.
Command return codes
During the assignment of structures, arrays or lists, it is possible that part of the command has been processed and executed when the error occurs. In this case, the result of the command is not guaranteed.
(SC2) | SC1 | Maincode | Meaning/Guaranteed messages |
| 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) | |
| 64 | SDP0091 | Semantic error Guaranteed messages: SDP1030 | |
| 130 | SDP0099 | No further address space available |
Permissible combinations of variable types and operands
Variable (left) | Value/variable (right) | WRITE-MODE = | |||
*REPLACE | *MERGE | *EXTEND | *PREFIX | ||
Simple | Expression | x | - | - | - |
Array | Expression | - | - | - | - |
List | Expression | - | - | x | x |
Structure | Expression | - | - | - | - |
Key
x Combination permitted; see the description of the relevant operand for effects
- Combination produces an error.
Example
/SET-VARIABLE A = B
/A = B
The two assignments are equivalent: the contents of variable B are assigned to variable A.
/SET-VARIABLE PERSON = 'HUGO'
/PERSON = 'HUGO'
In both assignments the string ’HUGO’ is assigned to the variable PERSON.
/DECLARE-VARIABLE TOTAL /SET-VARIABLE TOTAL = -(1 + 3) * 4 /TOTAL = -(1 + 3) * 4
DECLARE-VARIABLE is used to declare a variable TOTAL, with the data type ANY being the default. The following two assignments are equivalent: The integer value -16 is assigned to the variable TOTAL.
Example: Arrays
/DECLARE-VARIABLE A, MULTIPLE-ELEMENTS = *ARRAY /DECLARE-VARIABLE B, MULTIPLE-ELEMENTS = *ARRAY /SET-VARIABLE A#1 = 5 /SET-VARIABLE A#3 = 3 /SET-VARIABLE B#5 = 1 /SET-VARIABLE B = A /SHOW-VARIABLE B
Output
B#1 = 5
B#3 = 3
Variant
/SET-VARIABLE A#4 = 5 /SET-VARIABLE B#5 = 1 /SET-VARIABLE A#6 = 3 /SET-VARIABLE B = A, MODE = *MERGE /SHOW-VARIABLE B
Output
B#4 = 5 B#5 = 1 B#6 = 3
Example: Structures
/DECLARE-VARIABLE S1(TYPE = *STRUCTURE(*BY-SYSCMD))
/ BEGIN-STRUCTURE
/ DECLARE-ELEMENT X(INITIAL-VALUE = 11)
/ DECLARE-ELEMENT Y(INITIAL-VALUE = 12)
/ DECLARE-ELEMENT Z(INITIAL-VALUE = 13)
/ END-STRUCTURE
/DECLARE-VARIABLE S2(TYPE = *STRUCTURE(*DYNAMIC))
/ DECLARE-ELEMENT S2.X('AB')
/ DECLARE-ELEMENT S2.Y('CD')
/ SET-VARIABLE S1 = S2
/SHOW-VARIABLE S1, SELECT=*BY-ATTRIBUTES(INITIALIZATION=*ANY)
Output
S1.X = AB S1.Y = CD S1.Z = *NO-INIT
Variant
/DECLARE-VARIABLE S1(TYPE = *STRUCTURE(*BY-SYSCMD))
/ BEGIN-STRUCTURE
/ DECLARE-ELEMENT X(INIT = 11)
/ DECLARE-ELEMENT Y(INIT = 12)
/ DECLARE-ELEMENT Z(INIT = 13)
/ END-STRUCTURE
/DECLARE-VARIABLE S2(TYPE = *STRUCTURE(*DYNAMIC))
/ DECLARE-ELEMENT S2.X('AB')
/ DECLARE-ELEMENT S2.Y('CD')
/ SET-VARIABLE S2 = S1
/SHOW-VARIABLE S2
Output
S2.X = 11 S2.Y = 12 S2.Z = 13
Example: managing lists of structures
The following example shows how lists of structures can be managed. A list of structures is created, containing the name and telephone number of every user. When the list is complete, it is copied into a file.
/BEGIN-STRUCTURE MYLAYOUT
/ DECLARE-ELEMENT NAME(TYPE=*STRING)
/ DECLARE-ELEMENT TELEPHONENUMBER(TYPE=*STRING)
/END-STRUCTURE
/DECLARE-VARIABLE LIST-OF-STRUCT(TYPE=*STRUCTURE(MYLAYOUT))/
,MULTIPLE-ELEMENTS=*LIST
/DECLARE-VARIABLE STRUCT(TYPE=*STRUCTURE(MYLAYOUT))
/READ-VARIABLE VARIABLE-NAME = STRUCT.NAME,INPUT=*TERMINAL-
/ (PROMPT-STRING = 'ENTER A USER NAME (END WITH '''')')
/WHILE (STRUCT.NAME <>'')
/ READ-VARIABLE VARIABLE-NAME = STRUCT.TELEPHONENUMBER,INPUT=*TERMINAL-
/ (PROMPT-STRING = 'ENTER A USER TELEPHONE#')
/ LIST-OF-STRUCT=STRUCT,WRITE-MODE=*EXTEND
/ READ-VARIABLE VARIABLE-NAME = STRUCT.NAME,INPUT=*TERMINAL-
/ (PROMPT-STRING = 'ENTER A USER NAME (END WITH '''')')
/END-WHILE
/
/SHOW-VARIABLE LIST-OF-STRUCT
Examples: converting an SDF command string
Example 1
/DECLARE-VARIABLE MYSTRUCT(TYPE=*STRUCTURE(*DYNAMIC))
/SET-VARIABLE MYSTRUCT = *STRING-TO-VARIABLE -
/('OPERAND1=VALUE1(OPERAND2=VALUE2)')
/SHOW-VARIABLE MYSTRUCT
Output
MYSTRUCT.OPERAND1.SYSSTRUC = VALUE1 MYSTRUCT.OPERAND1.OPERAND2 = VALUE2
Example 2
/DCV V1(TYPE=*ANY),MULT-ELEM=*LIST /DCV V2(TYPE=*ANY),MULT-ELEM=*LIST /S = '(A,B,1, ,,F)' /V1 = *STR-TO-VAR(S) /V2 = *STR-TO-VAR(S,VAL-TYPE=*STR) /SHV V1,VAL=*C-LIT,LIST-INDEX=YES V1#1 = 'A' V1#2 = 'B' V1#3 = 1 V1#4 = 'F' /SHV V2,VAL=*C-LIT,LIST-INDEX=YES V2#1 = 'A' V2#2 = 'B' V2#3 = '1' V2#4 = ' ' V2#5 = '' V2#6 = 'F'