OPEN-VARIABLE-CONTAINER

Open variable container

Component:	SDF-P-BASYS
Functional area:	Procedures
Domain:	PROCEDURE
Privileges:	STD-PROCESSING OPERATING HARDWARE-MAINTENANCE SECURITY-ADMINISTRATION SAT-FILE-MANAGEMENT SAT-FILE-EVALUATION

Function

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.

Restrictions

If the chargeable SDF-P subsystem is not available, the following restrictions apply:

• The scope can be defined with SCOPE=*CURRENT only.

• If AUTOMATIC-DECLARE=*ALL is specified, only simple S variables can be declared (TYPE=*ANY and MULTIPLE-ELEMENTS=*NO). All other declarations are rejected. 

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 element type is SYSVCONT.

LIBRARY = <filename 1..54 without-vers>
Name of the PLAM library.

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 of the element.

VERSION = *HIGHEST-EXISTING
Selects the highest existing version.

VERSION = <composed-name1..24>
Selects the specified version.

LOCK-ELEMENT =
Specifies whether the element is locked or not.

LOCK-ELEMENT = *NO
The element is opened in input mode. The container variables are copied into the variable container from 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 command which is issued in the same task or another task is rejected.

SCOPE = *CURRENT / *PROCEDURE / *TASK(...)
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 “Scope of variables” in the “SDF-P” manual [34]). 

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.

The operand values *PROCEDURE and *TASK(...) can only be specified if the chargeable SDF-P subsystem is loaded. The operand values are completely described in the “SDF-P” manual [34].

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 whose names match the specified pattern string 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.

• 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 the variable container includes any variables that cannot be processed using SDF-P-BASYS, any declaration of such variables by means of AUTOMATIC-DECLARE will be rejected.

Return codes

(SC2)	SC1	Maincode	Meaning
	0	CMD0001	No error
2	0	SDP00xx	Warning: Variable does not exist or is already declared with other attributes. 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 more address space available

Example

See the DECLARE-VARIABLE command.