Domain: PROCEDURE
Command description
The OPEN-VARIABLE-CONTAINER command is used to open variable containers, which are stored as PLAM library elements. If such a variable container or element does not yet exist when the command is called, it is automatically created.
This makes it possible to create S variables which are permanently available, i.e. S variables whose existence is not dependent on the current task.
Format
OPEN-VARIABLE-CONTAINER |
CONTAINER-NAME = <composed-name 1..64> ,FROM-FILE = *LIBRARY-ELEMENT (...) *LIBRARY-ELEMENT(...) LIBRARY = <filename 1..54 without-vers> ,ELEMENT = *CONTAINER-NAME / <composed-name 1..64>(...) <composed-name 1..64>(...) VERSION = *HIGHEST-EXISTING / <composed-name 1..24> ,LOCK-ELEMENT = *NO / *YES ,SCOPE = *CURRENT / *PROCEDURE / *TASK(...) *TASK(...) SAVE-AT-TERMINATION = *NO / *YES ,AUTOMATIC-DECLARE = *ALL / *NONE / <structured-name 1..20 with-wild(40)> / list-poss(2000): <structured-name 1..20> |
Operands
CONTAINER-NAME = <composed-name 1..64>
Name of the variable container.
FROM-FILE = *LIBRARY-ELEMENT(...)
The library element which contains the variable container. The data type of this element is SYSVCONT.
LIBRARY = <filename 1..54 without-vers>
Name of the PLAM library. Specification of a list of libraries (S variable SYSPLAMALT-<name>) is permissible.
ELEMENT =
Name of the element.
ELEMENT = *CONTAINER-NAME
The name of the element is identical with that of the variable container.
ELEMENT = <composed-name 1..64>(...)
The name of the element may differ from that of the variable container.
VERSION =
Designates the version number of the element.
VERSION = *HIGHEST-EXISTING
Selects the highest existing version number.
VERSION = <composed-name 1..24>Selects the specified version number.
LOCK-ELEMENT =
Specifies whether or not the element is locked.
LOCK-ELEMENT = *NO
The element is opened in input mode. The container variables are copied into this element. The element is then locked.
LOCK-ELEMENT = *YES
The element is opened in input and output mode. The container variables are copied from this element into the variable container. The element then remains open until the CLOSE-VARIABLE-CONTAINER command is issued. Any subsequent OPEN-VARIABLE-CONTAINER which is issued in the same task or another task is rejected.
SCOPE =
Defines the scope of the variable container. This controls access to the variables held in the variable container.
The scope of the container variable must not be greater than that of the variable container.
SCOPE = *CURRENT
The scope of the variable container is procedure-local (for further details see section“Scope of variables”).
The variable container can only be used in the local procedure and in any lower-level include procedures, but not in the calling procedure. The container is implicitly closed at the end of the current procedure.
SCOPE = *PROCEDURE
The scope of the variable container is procedure-local (for further details see section“Scope of variables”).
The variable container can be used in the local procedure and in any lower-level include procedures. It can also be used in the calling procedures if these were called by INCLUDE-PROCEDURE. It is implicitly closed at the end of the first-called procedure. I.e. it is open across all Include procedures until termination of the highest-level calling procedure.
SCOPE = *TASK(...)
The scope of the variable container is task-global (for further details see section “Scope ofvariables” (Scope of variables )).
The variable container can be used until it is closed or the task is terminated. Unlike the scope of variables, it is not necessary to import the name of the container before it is used.
SAVE-AT-TERMINATION =
Specifies whether the variable container must be saved at EXIT-JOB or LOGOFF.
SAVE-AT-TERMINATION = *NO
The variable container is not saved at EXIT-JOB.
SAVE-AT-TERMINATION = *YES
The variable container is saved at EXIT-JOB. However, it is not saved at an abnormal task termination, as for example with the setting EXIT-JOB MODE = ABNORMAL.
AUTOMATIC-DECLARE =
Specifies whether the container variables are to be automatically declared.
AUTOMATIC-DECLARE = *ALL
The container variables are automatically declared, with the scope of the variable container.
AUTOMATIC-DECLARE = *NONE
Container variables are not automatically declared.
AUTOMATIC-DECLARE = list-poss(2000): <structured-name 1..20>
The specified container variables are automatically declared with the scope of the variable container.
AUTOMATIC-DECLARE = <structured-name 1..20 with-wild(40)>
The container variables which match the specified search pattern are automatically declared with the scope of the variable container.
Notes
Variables in a variable container can be created by means of the CONTAINER operand in the DECLARE-VARIABLE command.
Variables which are declared as static structure layouts are saved with the name of the corresponding structure layout.
A reference to a variable container is not allowed until it has been created using OPEN-VARIABLE-CONTAINER.
If variables are automatically created, using OPEN-VARIABLE-CONTAINER, and the variables already exist with different attributes, the declaration is rejected and error message SDP1018 is returned as a warning. Notwithstanding this, the opening process continues. The user can interrogate the rejected variables by means of the S variable stream SYSMSG.
If container variables are created by AUTOMATIC-DECLARE, and if they relate to static structures, they are converted to structures of type ’*BY-SYSCMD’.
Command return codes
(SC2) | SC1 | Maincode | Meaning |
| 0 | CMD0001 | No error | |
| 2 | 0 | SDP00xx | Warning that the following has occurred: guaranteed messages: SDP1008, SDP1018 |
| 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 | |
| 130 | SDP0099 | No further address space available |
Example
See the SHOW-VARIABLE-CONTAINER-ATTR command, "SHOW-VARIABLE-CONTAINER-ATTR Display open variable containers ".