A.17 The Package Environment_Variables
1/2
{
AI95-00370-01}
{environment variable}
The package Environment_Variables allows a program
to read or modify environment variables. Environment variables are name-value
pairs, where both the name and value are strings. The definition of what
constitutes an environment variable, and the meaning of the name
and value, are implementation defined. 1.a/2
Implementation defined:
The definition and meaning of an environment
variable.
Static Semantics
2/2
{
AI95-00370-01}
The library package Environment_Variables has the
following declaration: 3/2
package Ada.Environment_Variables is
pragma Preelaborate(Environment_Variables);
4/2
function Value (Name : in String) return String;
5/2
function Exists (Name : in String) return Boolean;
6/2
procedure Set (Name : in String; Value : in String);
7/2
procedure Clear (Name : in String);
procedure Clear;
8/2
procedure Iterate (
Process : not null access procedure (Name, Value : in String));
9/2
end Ada.Environment_Variables;
10/2
function Value (Name : in String) return String;
11/2
{
AI95-00370-01}
If the external execution environment supports
environment variables, then Value returns the value of the environment
variable with the given name. If no environment variable with the given
name exists, then Constraint_Error is propagated. If the execution environment
does not support environment variables, then Program_Error is propagated.12/2
function Exists (Name : in String) return Boolean;
13/2
{
AI95-00370-01}
If the external execution environment supports
environment variables and an environment variable with the given name
currently exists, then Exists returns True; otherwise it returns False.14/2
procedure Set (Name : in String; Value : in String);
15/2
{
AI95-00370-01}
If the external execution environment supports
environment variables, then Set first clears any existing environment
variable with the given name, and then defines a single new environment
variable with the given name and value. Otherwise Program_Error is propagated.16/2
If implementation-defined
circumstances prohibit the definition of an environment variable with
the given name and value, then Constraint_Error is propagated.
16.a/2
Implementation defined:
The circumstances where an environment
variable cannot be defined.
17/2
It
is implementation defined whether there exist values for which the call
Set(Name, Value) has the same effect as Clear (Name).
17.a/2
Implementation defined:
Environment names for which Set has
the effect of Clear.
18/2
procedure Clear (Name : in String);
19/2
{
AI95-00370-01}
If the external execution environment supports
environment variables, then Clear deletes all existing environment variable
with the given name. Otherwise Program_Error is propagated.20/2
procedure Clear;
21/2
{
AI95-00370-01}
If the external execution environment supports
environment variables, then Clear deletes all existing environment variables.
Otherwise Program_Error is propagated.22/2
procedure Iterate (
Process : not null access procedure (Name, Value : in String));
23/2
{
AI95-00370-01}
If the external execution environment supports
environment variables, then Iterate calls the subprogram designated by
Process for each existing environment variable, passing the name and
value of that environment variable. Otherwise Program_Error is propagated.24/2
If several environment
variables exist that have the same name, Process is called once for each
such variable.
Bounded (Run-Time) Errors
25/2
{
AI95-00370-01}
{bounded error
(cause) [partial]} It is a bounded error
to call Value if more than one environment variable exists with the given
name; the possible outcomes are that: 26/2
- one of the values
is returned, and that same value is returned in subsequent calls in the
absence of changes to the environment; or
27/2
- Program_Error
is propagated.
Erroneous Execution
28/2
{
AI95-00370-01}
{erroneous execution
(cause) [partial]} Making calls to the
procedures Set or Clear concurrently with calls to any subprogram of
package Environment_Variables, or to any instantiation of Iterate, results
in erroneous execution.29/2
Making calls to the procedures
Set or Clear in the actual subprogram corresponding to the Process parameter
of Iterate results in erroneous execution.
Documentation Requirements
30/2
{
AI95-00370-01}
An implementation shall document how the operations
of this package behave if environment variables are changed by external
mechanisms (for instance, calling operating system services).
30.a/2
Documentation Requirement:
The behavior of package Environment_Variables
when environment variables are changed by external mechanisms.
Implementation Permissions
31/2
{
AI95-00370-01}
An implementation running on a system that does
not support environment variables is permitted to define the operations
of package Environment_Variables with the semantics corresponding to
the case where the external execution environment does support environment
variables. In this case, it shall provide a mechanism to initialize a
nonempty set of environment variables prior to the execution of a partition.
Implementation Advice
32/2
{
AI95-00370-01}
If the execution environment supports subprocesses,
the currently defined environment variables should be used to initialize
the environment variables of a subprocess. 32.a/2
Implementation Advice:
If the execution environment supports
subprocesses, the current environment variables should be used to initialize
the environment variables of a subprocess.
33/2
Changes to the environment
variables made outside the control of this package should be reflected
immediately in the effect of the operations of this package. Changes
to the environment variables made using this package should be reflected
immediately in the external execution environment. This package should
not perform any buffering of the environment variables.
33.a/2
Implementation Advice:
Changes to the environment variables
made outside the control of Environment_Variables should be reflected
immediately.
Extensions to Ada 95
33.b/2
{
AI95-00370-01}
{extensions to Ada 95} Package
Environment_Variables is new.
Sponsored by Ada-Europe