One S variable can be a container variable for another S variable. However, both of them (variable container and variable) must be declared with the same variable type and data type, and the container’s lifetime must be the same as or longer than the variable’s (the life span is determined by the scope).
There are two possible ways of defining S variables as variable containers, depending on how long the variables are to be saved for. Thus, variables can be stored temporarily or permanently by means of variable containers.
Note
Variable names are often preset in command modules or system output routines. These reserved variable names can be inserted in the CONTAINER operand as the name of the container variable. This saves the user the trouble of storing the information returned by the system in other variables that are valid in the procedure. Reserved words and variable names are listed in section 6.2.2, “Variable names”.
Variable containers for temporary variables
If a variable container is to be used for temporary storage of a variable (i.e. it is available until the task end, at the latest), the variable container need only be a variable declared in the standard manner. In this case, the contents of the variables to be stored are held by the variable container in class 5 memory.
The container mechanism can in the same way be used to make task-global variables accessible under another name, thus making it easier to avoid possible naming conflicts.
Variable containers for permanent variables
Permanent variable containers are saved in PLAM libraries.
These containers are opened (or, if they do not yet exist, they are also created) by an OPEN-VARIABLE-CONTAINER command. They are closed either explicitly by a CLOSE-VARIABLE-CONTAINER command, or implicitly by the procedure or task end (EXIT-PROCEDURE or EXIT-JOB respectively). These variable containers are saved into PLAM library elements by the SAVE-VARIABLE-CONTAINER command. In addition, SHOW-VAR-CONTAINER-ATTRIBUTES can be used to route any open variable containers into structured outputs.
When a variable container is open, the S variables which it contains can be accessed.
One way of using permanent variables is to initialize procedure parameters. This is because OPEN-VARIABLE-CONTAINER can be specified in the procedure head between BEGIN-PARAMETER-DECLARATION and the first DECLARE-PARAMETER; i.e. a variable container can be opened before the first declaration of a parameter, and hence the variables declared in the container can be used to initialize any required parameters. (The preset value “*ALL” for the AUTOMATIC-DECLARE operand in OPEN-VARIABLE-CONTAINER also ensures that by default all the variables contained in the variable container are already (pre-)declared. The scope of the variables is then that of the variable container.)
If any parameter has the same name as a variable declared by the opening of the variable container, the parameter will be rejected and the procedure call aborted.
Notes
At the time of the OPEN-VARIABLE-CONTAINER, the library element is either locked after being read (LOCK-ELEMENT = *NO) or not (LOCK-ELEMENT= *YES); i.e. library elements can correspondingly be used either for several tasks or for one only (exclusive access).
If a variable container is opened with LOCK-ELEMENT = *YES, all subsequent attempts to open it, in the same task or others, will be rejected.
All variable attributes except for the scope are saved in the variable container. Specifically, these are: the type, name of the structure, array and list limits.
The variable container is automatically closed at procedure end, with no need to specify CLOSE-VARIABLE-CONTAINER, if SCOPE=*CURRENT was set, or if SCOPE = *PROCEDURE is specified for a subordinate call. The variable container is also closed automatically at task end if SCOPE=*TASK was specified.
However, in every case except the last the variable container is not saved when it is closed; and in the last case it will only be saved if SAVE-AT-TERMINATION=*YES was set.
PLAM library elements which are used for storing variable containers are handled as follows (see also the manual “LMS” [11] (LMS = Library Maintenance System)):
Variable containers are held in LMS as PLAM library elements with TYPE=SYSVCONT. They can thus be used by SDF-P and FHS.
If the specified library element does not exist at the time it is opened, then it is created at opening time if LOCK-ELEMENT=*YES is set, and when it is saved if the setting is LOCK-ELEMENT=*NO.
If the element is locked when it is opened, it cannot be saved with SAVE-VARIABLE-CONTAINER CONTAINER-NAME=<composed-name 1..64>(ELEMENT-VERSION= *INCREMENT).
If the element version is not specified when it is opened, and if the element does not yet exist, it is created in the highest possible version, X'FF'.
If the element version is not specified when it is opened, but it does already exist, its highest version is opened.
If an element version other than *UPPER-LIMIT (in LMS) is set when the element is opened, and if it does not yet exist, then after its opening and creation it can be saved with SAVE-VARIABLE-CONTAINER CONTAINER-NAME=<composed-name 1..64>(ELEMENT-VERSION=*INCREMENT).
If an element is saved with SAVE-VARIABLE-CONTAINER CONTAINER-NAME=<composed-name 1..64>(ELEMENT-VERSION=*SAME), then if the opening setting is LOCK-ELEMENT = *YES the element will be written back into the same version, if the opening setting is LOCK-ELEMENT = *NO into the highest version.
If an element is saved with SAVE-VARIABLE-CONTAINER CONTAINER-NAME=<composed-name 1..64>(ELEMENT-VERSION=*INCREMENT), the increment will be appended when the element is saved, and not the next time that it is opened.
Example
Input
/OPEN-VARIABLE-CONTAINER CONT, *LIBRARY-ELEMENT(#MY-CONT-LIB) /SHOW-VAR-CONTAINER-ATTRIBUTES CONT
Output
CONTAINER-NAME = CONT
FROM-FILE = *LIBRARY-ELEMENT
LIBRARY = :10SC:$QM123.S.152.OCG6.MY-CONT-LIB
ELEMENT = CONT
VERSION = *HIGHEST-EXISTING
LOCK = *NO
SCOPE = *PROCEDURE
Input
SAVE-VARIABLE-CONTAINER CONT CLOSE-VARIABLE-CONTAINER CONT
For further notes on “permanent variables” see chapter “SDF-P commands”, particularly the description of the command OPEN-VARIABLE-CONTAINER on "OPEN-VARIABLE-CONTAINER Open variable container ".