12/01/86  dsl_

This subroutine supplies entry points for the functions required in
opening, manipulating, and closing a data base.


Examples of its use are documented in the MRDS Reference Manual (AW53).


Entry points in dsl_:
    (List is generated by the help command)


:Entry: close: 06/17/86  dsl_$close

Function:  This entry causes the specified data bases to be closed and
made unavailable for processing.


Syntax:
declare dsl_$close entry options (variable);
call dsl_$close (data_base_index1, ..., data_base_indexn, code);


Arguments:
data_base_indexi (Input) (fixed bin(35))
   is the integer returned by dsl_$open that designates the currently
   open data bases that are to be closed.
code (Output) (fixed bin(35))
   is a standard status code.


:Entry: close_all: 06/17/86  dsl_$close_all

Function:  This entry closes all data bases that are currently open in
the user's process.


Syntax:
declare dsl_$close_all entry options (variable);
call dsl_$close_all (code);


Arguments:
code (output) (fixed bin(35))
   is the standard status code and is 0 if all data bases are
   successfully closed or if no data bases are open.


:Entry: compile: 12/01/86  dsl_$compile

Function:  This entry compiles (or pre-translates) a selection
expression for later use in the current process, for retrieval, modify,
delete, and define_temp_rel operations.  A previously compiled
selection expression can be deleted or redefined through this
entrypoint.  A selection expression can be compiled at any time in the
life of an open data base and saved for future use in that opening.


Syntax:
declare dsl_$compile entry options (variable);
call dsl_$compile (data_base_index, selection_expression, se_index,
   se_value1, ..., se_valuen, code;


Arguments:
data_base_index (Input) (fixed bin(35))
   is the index returned by dsl_$open to designate the data base.
selection_expression (Input) (char (*))
   is a character string as defined at the beginning of this section.
   It may contain .V.  argument substitution characters in all normal
   places.  These are filled in at the time the selection expression is
   compiled.  Argument substitution characters of the form .X.  may be
   used in all places in the where clause where .V.  is appropriate,
   except functions and expressions, to specify that this value is to
   be filled in at the time that the selection expression is used.


se_index (Input/Output) (fixed bin(35))
   is an integer used to identify a compiled selection expression.  If
   the se_index is 0 (on input), a new compiled selection expression is
   defined and the index for the newly compiled selection expression is
   returned.  If the se_index is greater than zero (on input) and a
   compiled selection expression with that index is found, it is
   redefined to the new selection expression.  If the se_index is less
   than zero (on input) and a compiled selection expression with that
   index is found, it is deleted and the selection expression is
   ignored.
se_value_i (Input)
   is a selection expression value for each control code (designated by
   .V.)  appearing in the selection expression.  These must be
   specified so as to correspond in order and quantity with the control
   codes specified in the selection expression.


code (Output (fixed bin(35))
   is a standard MRDS status code.  A value of 0 indicates that no
   error occurred.


Notes:  Any .V.  argument substitution characters supplied in the
selection expression must have matching arguments supplied in the call
to dsl_$compile.  They are then considered to be constant and cannot be
changed later.  Any .X.  argument substitution characters supplied in
the selection expression must have matching arguments supplied in the
call that references the compiled selection expression, not the call to
dsl_$compile.  The arguments supplied to satisfy a .X.  must have the
same data type as that of the data base attribute it is being compared
to.


:Entry: declare: 06/17/86  dsl_$declare

Function:  This entry makes a user-defined function known to MRDS while
processing the specified data base.  After it is declared, a
user-defined function may be used exactly as a MRDS built-in function.
If a user-defined function has the same name as a built-in function,
the user-defined function is referenced.


Syntax:
declare dsl_$declare entry (fixed bin(35), char(*), fixed bin(35));
call dsl_$declare (db_index, fn_name, code);


Arguments:
db_index (Input)
   is the index returned by dsl_$open that designates the data base.
fn_name (Input)
   is the name of the function being declared.
code (Output)
   is a standard status code.


Notes:  Built-in functions are provided as a standard part of MRDS and
need not be declared.


User-defined functions may be written in PL/I, COBOL, or FORTRAN.  MRDS
generates a call that is equivalent to:

   return_val = fn_name$fn_name (arg1 ...  argn)


Restrictions on arguments to user-defined functions are (1) No star (*)
extents are permitted in the declarations for return_val or argi; (2)
Data types are restricted to those data types permitted in a MRDS data
base (i.e., pointers, entries, labels, structures, offsets, and arrays
are not allowed).


:Entry: define_temp_rel: 06/17/86  dsl_$define_temp_rel

Function:  This entry allows the user to explicitly create, delete, or
redefine a temporary relation that can be used by the current process
for retrieval operations in the same manner as any predefined permanent
data base relations.


The only operations that can be performed on a temporary relation are
the "define_temp_rel", "retrieve", and "get_population".  After a
temporary relation is defined, it is referenced by specifying a ".V."
argument in the range clause and supplying the appropriate rel_index in
the dsl_ call argument list.  A temporary relation cannot be used in
the -select clause except for the dsl_$retrieve call.


Syntax:
declare dsl_$define_temp_rel entry options (variable);
call dsl_$define_temp_rel (data_base_index, selection_expression,
   se_index, se_value1, .., se_index, se_valuen, rel_index, code);


Arguments:
data_base_index (Input) (fixed bin(35))
   is the index returned by dsl_$open that designates the data base.
selection_expression (Input) (char(*))
   is a character string as defined at the beginning of this section,
   with at least one * in the -select clause to define the temporary
   relation key.  The attribute names given in the select clause must
   be unique.  This character string may be a constant or a variable
   declared either character varying or non-varying.
se_index (Input) (fixed bin(35))
   is an integer used to refer to a compiled selection expression.  It
   is required only if the selection expression is "-compiled".


se_valuei (Input)
   is a selection expression value for each argument substitution
   (designated by .V.  or .X.)  appearing in the
   <selection_expression>, including temporary relation (rel_index)
   designations.  These must be specified so as to correspond in order
   and quantity with the argument substitution specified in the
   <selection_expression).  If the selection expression is "-compiled",
   then the selection expression value is substituted for the .X.
   value in the where clause that has to be satisfied.  These values
   are supplied in the order in which they occur in the selection
   expression used in the call to dsl_$compile.  If the specified data
   type does not equal the attribute data type, the value
   mrds_error_$inv_data_type is returned in the code.


rel_index (Input/Output) (fixed binary(35))
   is an integer.  If rel_index is 0 on input, a new temporary relation
   is defined and the index for the newly created temporary relation is
   returned in rel_index.  If rel_index is greater than 0 on input and
   if a temporary relation possessing this index is already in
   existence, that temporary relation is redefined.  If rel_index is
   less than zero and a temporary relation with that rel_index exists,
   then that temporary relation is deleted and the selection expression
   is ignored.
code (Output) (fixed bin(36))
   is a standard status code.  A value of 0 indicates that no error
   occurred.


Notes:  If a duplicate of the temporary relation key is found while
creating the temporary relation, it is ignored (i.e., not stored)
without warning.


If no data satisfied the selection expression, then an unpopulated
temporary relation is created.  The population can be determined by a
call to dsl_$get_population.


For shared openings, relations specified in the range clause must have
read_attr scope set.


For attribute level security, attributes specified in the select and
where clauses must have read_attr access.


:Entry: delete: 06/17/86  dsl_$delete

Function:  This entry allows the user to delete one or more tuples from
the same relation of an opened data base.  The user must have
read-write permission to the relation.  All attributes in the relation
must be specified as being selected and, if the data base is being
referenced by means of a data submodel, all attributes of the relation
must be defined in the submodel.  All selected tuples are deleted.


Syntax:
declare dsl_$delete entry options (variable);
call dsl_$delete (data_base_index, selection_expression, se_index,
   se_value1, ..., se_valuen, code);


Arguments:
data_base_index (Input) (fixed bin(35))
   is the index returned by dsl_$open that designates the data base.
selection_expression (Input) (char(*))
   is a character string as defined at the beginning of this section.
   However, the select clause must specify all attributes in the
   relation.  This character string may be a constant or a variable
   declared character varying or non-varying.
se_index (Input) (fixed bin(35))
   is an integer used to refer to a compiled selection expression.  It
   is required only if the selection expression is "-compiled".


se_valuei (Input)
   is a selection expression value for each argument substitution
   (designated by .V.  or .X.)  appearing in the
   <selection_expression>, including temporary relation (rel_index)
   designations.  These must be specified so as to correspond in order
   and quantity with the argument substitution specified in the
   <selection_expression).  If the selection expression is "-compiled",
   then the selection expression value is substituted for the .X.
   value in the where clause that has to be satisfied.  These values
   are supplied in the order in which they occur in the selection
   expression used in the call to dsl_$compile.  If the specified data
   type does not equal the attribute data type, the value
   mrds_error_$inv_data_type is returned in the code.


code (Output) (fixed bin(35))
   is a standard status code.  A value of 0 indicates that no error
   occurred.  A value corresponding to mrds_error_$tuple_not_found
   indicates that no error occurred and that no data satisfied the
   selection expression.


Notes:  For shared openings, the relation must have delete_tuple permit
scope set.


For attribute level security, the relation must have delete_tuple
access and any attributes specified in the where clause must have
read_attr access.


:Entry: dl_scope: 06/17/86  dsl_$dl_scope

Function:  This entry deletes all or part of a previously specified
scope from the user's current scope.


Syntax:
declare dsl_$dl_scope entry options (variable);
call dsl_$dl_scope (db_index, rel_name1, permit_ops1, prevent_ops1,
   ..., rel_namen, permit_opsn, prevent_opsn, code);


Arguments:
db_index (Input) (fixed bin(35))
   is the index returned by dsl_$open that designates the data base.
rel_namei (Input) (char(*))
   is the name of the relation(s) to be included in the scope.
permit_opsi (Input)(fixed bin)
   the sum of the codes for the operations no longer granted to the
   user's process on the specified relation (as defined in set_scope).
   (See "Note" below for a description of appropriate codes.)
prevent_opsi (Input) (fixed bin)
   the sum of the codes for the operations no longer denied to other
   processes on the specified relation (as defined in set_scope).  (See
   "Note" below for a description of appropriate codes.)
code (Output) (fixed bin(35))
   is a standard status code.


Notes:  Scope codes for operations to be prevented or permitted are as
follows:


     Scope
     Code      Operation

       0       null
       1       read_attr or read
       2       append_tuple or store
       4       delete_tuple or delete
       8       modify_attr or modify


Current scope settings can be determined by a call to dsl_$get_scope.


:Entry: dl_scope_all:  06/17/86  dsl_$dl_scope_all

Function:  This entry deletes all remaining scope tuples from the
user's current scope.


Syntax:
declare dsl_$dl_scope_all entry (fixed bin(35), fixed bin(35));
call dsl_$dl_scope_all (db_index, code);


Arguments:
db_index (Input)
   is the index returned by dsl_$open that designates the data base.
code (Output)
   is a standard status code.  It is 0 if no scope is set prior to the
   call to dsl_$dl_scope_all.


:Entry: get_attribute_list: 06/17/86  dsl_$get_attribute_list

Function:  This entry returns information on the attributes in the view
of the given relation provided by the user's opening.


Syntax:
declare dsl_$get_attribute_list entry (fixed bin(35),
   char(*), ptr, fixed bin, ptr, fixed bin(35));
call dsl_$get_attribute_list (db_index, relation_name,
   area_ptr, structure_version, mrds_attribute_list_ptr,
   error_code);


Arguments:
db_index (Input) (fixed bin(35))
   is the integer returned by dsl_$open for the opening the user wishes
   to reference.
relation_name (Input) (char(*))
   is the name of the relation in the user's view for which the
   attribute information is desired.
area_ptr (Input) (pointer)
   is a pointer to a user-supplied freeing area, in which the attribute
   information is to be allocated.
structure_version (Input) (fixed bin)
   is the desired version of the attribute information structure to be
   returned.


mrds_attribute_list_ptr (Output) (pointer)
   is a pointer to the attribute information returned in a structure as
   described in the Notes below.


error_code (Output) (fixed bin(35))
   is the standard status code.  It may be one of the following:
   error_table_$area_too_small
      if the supplied area could not hold the attribute information.
   error_table_$badcall
      if the area_ptr was null.
   error_table_$unimplemented_version
      if the structure_version supplied is unknown.
   mrds_error_$invalid_db_index
      if the db_index given does not refer to a data base open in this
      process.
   mrds_error_$not_freeing_area
      if the supplied area does not have the attribute "freeing".


   mrds_error_$unknown_relation_name
      if the given relation name is not known in this opening view of
      the data base.
   mrds_error_$version_not_supported
      if the data base referenced is not version 4.


Notes:  The only structure version currently available is 1.  This
entry only works for version 4 data bases.


:Entry: get_opening_temp_dir: 06/17/86  dsl_$get_opening_temp_dir

Function:  This entry returns the pathname of the directory that is
being used for temporary storage for a particular data base opening.


Syntax:
declare dsl_$get_opening_temp_dir entry
   (fixed bin(35), fixed bin(35)) returns(char(168));
path = dsl_$get_opening_temp_dir(db_index, error_code)


Arguments:
db_index (Input) (fixed bin(35))
   is the integer returned by a call to dsl_$open and refers to the
   opening whose temporary storage directory is desired.
error_code (Output) (fixed bin(35))
   is the standard status code.  If the supplied db_index does not
   refer to a currently open data base in the user's process then it
   will be mrds_error_$invalid_db_index.
path (Output) (char(168))
   is the absolute pathname of the directory being used for temporary
   storage for the opening specified.


Notes:  See dsl_$get_temp_dir for an entry that will return the
directory pathname to be used in the next call to open.  Also see
dsl_$set_temp_dir and the commands display_mrds_temp_dir and
set_mrds_temp_dir.


:Entry: get_path_info: 06/17/86  dsl_$get_path_info

Function:  This entry returns information about a supplied pathname.
It indicates whether or not the path refers to a MRDS data base model
or submodel, and if so, the version number and details about its
creation.  This entry replaces dsl_$get_db_version, which is obsolete.


Syntax:
declare dsl_$get_path_info entry(char(*), ptr,
   fixed bin, ptr, fixed bin(35));
call dsl_$get_path_info(in_path, area_ptr,
   structure_version, mrds_path_info_ptr, error_code);


Arguments:
in_path (Input) (char(*))
   is the relative or absolute pathname about which the user desires
   information.  If it refers to a MRDS data base model or submodel, it
   does not need a suffix, unless ambiguity would result.  A model will
   be found before the submodel if they both have the same name, less
   suffix, in the same directory.
area_ptr (Input) (pointer)
   is a pointer to a user-supplied freeing area in which the path
   information will be allocated.
structure_version (Input) (fixed bin)
   is the desired version of the path information structure to be
   returned.


mrds_path_info_ptr (Output) (pointer)
   is the pointer to the path information structure that is returned,
   which is described in the Notes below.


error_code (Output) (fixed bin(35))
   is the standard status code.  It may be one of the following:
   error_table_$area_too_small
      if the supplied area could not hold the path information.
   error_table_$badcall
      if the area_ptr was null.
   error_table_$unimplemented_version
      if the supplied structure version is unknown.
   mrds_error_$no_model_access
      if the user does not have "r" access to the db_model segment
      under the data base.
   mrds_error_$no_model_submodel
      if the path does not refer to a MRDS data base model or submodel.
   mrds_error_$not_freeing_area
      if the supplied area does not have the attribute "freeing".


Notes:  The only structure version currently available is 1.  The
variables mrds_path_info_ptr and mrds_path_info_structure_version are
also declared in the mrds_path_info include file.


:Entry: get_population: 06/17/86  dsl_$get_population

Function:  This entry returns the current number of tuples in either a
permanent or temporary relation.


Syntax:
declare dsl_$get_population entry () options (variable);
call dsl_$get_population (db_index, relation_identifier,
   tuple_count, error_code);


Arguments:
db_index (Input) (fixed bin(35))
   is the integer returned from a call to dsl_$open, which refers to
   the opening for which population statistics are desired.
relation_identifier (Input)
   is the identification for the relation whose tuple count is to be
   returned.  If it is declared as character and starts with a letter,
   then it is interpreted as a permanent relation name.  If the string
   does not start with a letter and it can be converted to a number,
   then it will be interpreted as a temporary relation index.  If the
   relation identifier is declared as fixed bin (35), then it is
   interpreted as a temporary relation index.
tuple_count (Output) (fixed bin(35))
   is the current tuple count for the specified relation in this
   opening view.


error_code (Output) (fixed bin(35))
   is the standard status code.  It may be one of the following:
   mrds_error_$invalid_db_index
      if the given db_index does not refer to a model or submodel
      opening of a data base in the user's process.
   mrds_error_$undef_temp_rel
      if the temporary relation index given does not refer to a
      temporary relation currently defined in this opening.
   mrds_error_$unknown_relation_name
      if the permanent relation name given is not known in this opening
      view of the data base.


Notes:  This entry can be used to determine the number of tuples
selected by a selection expression by defining a temporary relation
using that selection expression and calling dsl_$get_population for
that temporary relation.


:Entry: get_relation_list: 06/17/86  dsl_$get_relation_list

Function:  This entry returns information about all the relations in
the specified opening view.


Syntax:
declare dsl_$get_relation_list entry (fixed bin(35), ptr,
   fixed bin, ptr, fixed bin(35));
call dsl_$get_relation_list (db_index, area_ptr,
   structure_version, mrds_relation_list_ptr,
   error_code);


Arguments:
db_index (Input) (fixed bin(35))
   is the integer returned from a call to dsl_$open, referring to the
   opening for which relation information is to be returned.
area_ptr (Input) (pointer)
   is a pointer to a user-supplied freeing area in which the relation
   information is to be allocated.
structure_version (Input) (fixed bin)
   is the desired version of the relation information structure to be
   returned.
mrds_relation_list_ptr (Output) (pointer)
   is a pointer to the relation information structure that has been
   allocated and is described in the Notes below.


error_code (Output) (fixed bin(35))
   is the standard status code.  It may be one of the following:
   error_table_$area_too_small
      if the supplied area could not hold the relation information.
   error_table_$badcall
      if the area_ptr was null.
   error_table_$unimplmented_version
      if the supplied structure version is unknown.
   mrds_error_$invalid_db_index
      if the db_index given does not refer to a data base open in this
      process.
   mrds_error_$not_freeing_area
      if the supplied area does not have the attribute "freeing".
   mrds_error_$version_not_supported
      if the data base referenced is not version 4.


Notes:  Currently, the only structure version available is 1.  The
variables mrds_relation_list_num_rels_init, mrds_relation_list_ptr, and
mrds_relation_list_structure_version are also declared in the
mrds_relation_list include file.


:Entry: get_scope: 06/17/86  dsl_$get_scope

Function:  This entry returns the scope currently set on a given
relation for the specified opening of the data base.


Syntax:
declare dsl_$get_scope entry(fixed bin(35), char(*),
   fixed bin, fixed bin, fixed bin, fixed bin(35));
call dsl_$get_scope(db_index, relation_name,
   permits, prevents, scope_version, error_code);


Arguments:
db_index (Input) (fixed bin(35))
   is the integer returned from a call to dsl_$open which refers to the
   opening for which scope information is desired.
relation_name (Input) (char(*))
   is the name of the relation for which scope information is desired
   in this opening.
permits (Output) (fixed bin)
   is the sum of the scope modes, representing operations that are to
   be permitted the caller for this relation in this opening.  See the
   table of scope mode encodings in the Notes below.
prevents (Output) (fixed bin)
   is the sum of the scope modes representing operations that are to be
   denied other users of this data base for this relation.  See the
   table of scope mode encodings in the Notes below.


scope_version (Output) (fixed bin)
   if this value is less than five, then the scope mode encoding for
   the scope represents the old operations of read - store - delete -
   modify.  Otherwise, the scope mode encoding represents the new
   operations of read_attr, append_tuple, delete_tuple, modify_attr
   used for attribute level security.
error_code (Output) (fixed bin(35))
   is the standard status code.  It may be one of the following:
   mrds_error_$scope_not_set
      if no scope is currently set on the specified relation.
   mrds_error_$unknown_relation_name
      if the supplied relation name is not in the opening view
      specified by db_index.


Notes:  The scope modes are encoded using the integer values given
below:


    Scope
    Code      Operation

    0         null
    1         read_attr or read
    2         append_tuple or store
    4         delete_tuple or delete
    8         modify_attr or modify


:Entry: get_temp_dir: 06/17/86  dsl_$get_temp_dir

Function:  This entry returns the pathname of the directory that is
used for temporary storage upon the next call to dsl_$open.


Syntax:
declare dsl_$get_temp_dir entry () returns (char(168));
path = dsl_$get_temp_dir ()


Arguments:
path (Output) (char(168))
   is the absolute pathname of the directory to be used for temporary
   storage on the next call to open.


Notes:  See dsl_$set_temp_dir and the commands display_mrds_temp_dir
and set_mrds_temp_dir.


To obtain the temporary storage directory for a particular opening,
call dsl_$get_opening_temp_dir.


:Entry: list_openings: 06/17/86  dsl_$list_openings

Function:  This entry returns information about all openings of MRDS
data bases in the user's process.  This entry replaces dsl_$list_dbs,
which is obsolete.


Syntax:
declare dsl_$list_openings entry (ptr, fixed bin, ptr, fixed bin(35);
call dsl_$list_openings (area_ptr, structure_version,
   mrds_database_openings_ptr, error_code);


Arguments:
area_ptr (Input) (pointer)
   is a pointer to a user-supplied freeing area in which the opening
   information will be allocated.
structure_version (Input) (fixed bin)
   is the desired version of the structure that is to return opening
   information.
mrds_data base_opening_ptr (Output) (pointer)
   is a pointer to an allocated structure containing the opening
   information which is described in the Notes below.


error_code (Output) (fixed bin(35))
   is a standard status code.  It may be one of the following:
   error_table_$area_too_small
      if the supplied area could not hold the opening information.
   error_table_$badcall
      if the area_ptr was null.
   error_table_$unimplemented_version
      if the given structure_version is unknown.
   mrds_error_$not_freeing_area
      if the supplied area does not have the attribute "freeing".


Notes:  Note that the structure is still allocated and a 0 error code
returned even if the total number of open data bases is 0.


:Entry: modify: 06/17/86  dsl_$modify

Function:  This entry allows the user to modify attribute values
contained in the tuples of one relation in the data base.  The
modification of a key attribute is not allowed.  The user must have
read_write permission to the relation.  All selected tuples are
modified.


Syntax:
declare dsl_$modify entry options (variable);
call dsl_$modify (data_base_index, selection_expression, se_index,
   se_value1, ...  , se_valuen, modified_value1 ...  , modified_valuen,
   code);


Arguments:
data_base_index (Input) (fixed bin(35))
   is the index returned by dsl_$open that designates the data base.
selection_expression (Input) (char(*))
   is a character string (see "Examples of Selection Mechanisms") as
   defined at the beginning of this section.  The select clause can
   only specify attributes from one relation.  This character string
   may be a constant or a variable declared character varying or
   non-varying.
se_index (Input) (fixed bin(35))
   is an integer used to refer to a compiled selection expression.  It
   is required only if the selection expression is "-compiled".


se_valuei (Input)
   is a selection expression value for each argument substitution
   (designated by .V.  or .X.)  appearing in the
   <selection_expression>, including temporary relation (rel_index)
   designations.  These must be specified so as to correspond in order
   and quantity with the argument substitution specified in the
   <selection_expression).  If the selection expression is "-compiled",
   then the selection expression value is substituted for the .X.
   value in the where clause that has to be satisfied.  These values
   are supplied in the order in which they occur in the selection
   expression used in the call to dsl_$compile.  If the specified data
   type does not equal the attribute data type, the value
   mrds_error_$inv_data_type is returned in the code.


modified_valuei (Input)
   is a modified tuple attribute value that is to replace the current
   such value in the data base.  There must be a one-to-one
   correspondence between these values and the tuple items specified in
   the selection expression.  If a structure is used for modified tuple
   attribute values, only one structure may be used.  Only data types
   supported by assign_ may be used for modified tuple attribute
   values.
code (Output) (fixed bin(35))
   is a standard status code.  A value of 0 indicates that no error
   occurred.  A value of mrds_error_$tuple_not_found indicates that no
   error occurred and that no data satisfied the selection expression.


Notes:  For shared openings, the relation must have modify_attr permit
scope set.


For attribute level security, the attributes specified in the select
and where clauses must have read_attr access.  In addition, the
attributes specified in the select clause must have modify_attr access.


:Entry: open: 06/17/86  dsl_$open

Function:  This entry causes the specified data bases to be opened for
processing in the designated modes.  For each opened data base, an
index that is to be used to specify that data base in future MRDS calls
is returned.  If one or more of the data bases specified cannot be
opened for any reason, none of the others are opened.


Syntax:
declare dsl_$open entry options (variable);
call dsl_$open (path1, data_base_index1, mode1, ...,
   pathn, data_base_indexn, moden, code);


Arguments:
pathi (Input) (char(*))
   is a character string containing the absolute or relative pathname
   of the data submodel (or the data base) with or without a suffix
   defining the relevant portion of the data base.  If the path of the
   data base itself is specified, the data model is used in place of
   the data submodel.
data_base_indexi (Output) (fixed bin(35))
   is an integer that is to be used in subsequent MRDS calls to specify
   the corresponding data base designated in this opening.


modei (Input) (fixed bin(35))
   is an integer (1,2,3,or 4) indicating the usage mode for which the
   data base is to be opened.
   1 specifies that this is a shared opening, requiring the setting of
     concurrency control protection via scope requests by the set_scope
     function.  The maximum permit scope that can be set with this
     opening mode is read_attr.
   2 specifies that this is a shared opening, requiring the setting of
     concurrency control protection via scope requests by the set_scope
     function.  Any scope can be set with this opening mode.


   3 specifies that this is an unshared opening in the sense that all
     update operations are prevented against any relations in this view
     of the data base.  No scope setting is necessary with this opening
     mode.  This mode is the equivalent of opening with a retrieval
     mode and doing a set_scope_all with permit of read_attr and
     prevents of modify_attr, append_tuple, and delete_tuple on these
     relations.  Other data base openers are allowed to set read_attr
     scope and to do retrievals in these relations.


   4 specifies that this is an unshared opening.  No scope setting is
     necessary with this opening mode.  No other data base openers are
     allowed to set any scope or any relation in this view of the data
     base.  This mode is the equivalent of opening with an update mode
     and doing a set_scope_all with permits and prevents of read_attr,
     modify_attr, append_tuple, and delete_tuple on these relations.
     Only one opening with this mode is allowed if the set of relations
     in this view overlaps the relations in another opener's view.
code (Output) (fixed bin(35))
   is a standard status code.


Notes:  Open modes 1 and 2 require subsequent calls to the dsl_ entry
set_scope.  Also see Appendix F for the include file
mrds_open_modes_.incl.pl1.


If a data model and submodel of the same name are in the same
directory, the model is found if no suffix is given.


If the data base being opened has been secured, then the view_path must
refer to a submodel that resides in the "secure.submodels" directory
under the data base directory if the user is not a DBA.  These must be
version 5 submodels if attribute level security is to be provided.  See
secure_mrds_db.


If the data base being opened uses a version 4 concurrency control,
then adjust_mrds_db with the -reset option must be run against it to
update it to version 5 concurrency control before it can be opened.
This changes the scope modes from r-u, to read_attr, modify_attr,
append_tuple, delete_tuple.


Application programs calling dsl_$set_scope, dsl_$set_scope_all, or
dsl_$dl_scope making use of r-s-m-d encodings will not be impacted.
Those programs using the r-u encodings will have to be changed to the
encodings given in this manual.


A maximum of 128 openings of the same or different data bases is
allowed.  Only 64 of these openings can be version 3 or earlier data
bases.


Access requirements for all opening modes includes "r" ACL on the
db_model segment and relation model segments (these segments have a
".m" suffix) for any relations appearing in the given view, plus "rw"
ACL on the data base concurrency control segment.  Unshared openings
require that, for any relation appearing in the view, the multisegment
file containing the data must have "r" ACL for exclusive_retrieval or
"rw" ACL for exclusive_update opening mode.  For attribute level
security, exclusive_retrieval mode requires read_attr on some attribute
in each relation in the opening view and exclusive_update mode requires
one of append_tuple on the relation, delete_tuple on the relation, or
modify_attr on some attribute in the relation, for each of the
relations in the opening view.


:Entry: retrieve: 06/17/86  dsl_$retrieve

Function:  This entry allows the user to retrieve selected attribute
values from the data base.  The user must have read permission to the
referenced relations.  One tuple per call is returned.


Syntax:
declare dsl_$retrieve entry options (variable);
call dsl_$retrieve (data_base_index, selection_expression, se_index,
   se_value1, ... , se_valuen, value1, ... , valuen, code);


Arguments:
data_base_index (Input) (fixed bin(35))
   is the index returned by dsl_$open that designates the data base.


selection_expression (Input) (char(*))
   is a character string (see "Formal Definition of the Selection
   Expression" in this section).  This character string may be a
   constant or a variable declared character varying or nonvarying.  If
   the expression results in the selection of identical tuples, only
   one copy is returned unless the -dup option is specified.  However,
   all tuples selected remain available for retrieval with additional
   calls to dsl_$retrieve with a <selection_expression> consisting of
   "-another".  They cease to be available whenever any dsl_ entry is
   called with a <selection_expression> consisting of an
   <alpha_expression>.  The selection expression "-another" does not
   return duplicate tuples unless the -dup option was specified in the
   original <alpha_expression>.  The -dup option cannot be used with
   set operations.  The range clause may have a ".V."  for substitution
   of a temporary relation's rel_index.


se_index (Input) (fixed bin(35))
   is an integer used to refer to a compiled selection expression.  It
   is required only if the selection expression is "-compiled".


se_valuei (Input)
   is a selection expression value for each argument substitution
   (designated by .V.  or .X.)  appearing in the
   <selection_expression>, including temporary relation (rel_index)
   designations.  These must be specified so as to correspond in order
   and quantity with the argument substitution specified in the
   <selection_expression).  If the selection expression is "-compiled",
   then the selection expression value is substituted for the .X.
   value in the where clause that has to be satisfied.  These values
   are supplied in the order in which they occur in the selection
   expression used in the call to dsl_$compile.  If the specified data
   type does not equal the attribute data type, the value
   mrds_error_$inv_data_type is returned in the code.


valuei (Output)
   is a retrieved attribute value.  The value may be a structure (only
   one regardless of the number of relations) or a list of individual
   values, the items of which must correspond in order and quantity
   with the tuple items specified in the <selection_expression>.  If an
   entire tuple is retrieved by specifying only the tuple_value in the
   select clause, then a value must be specified for every attribute of
   the corresponding relation as defined in the data submodel or in the
   data model, whichever is being used.  If data conversion is
   required, only data types supported by assign_ may be used.


code (Output) (fixed bin(35))
   is a standard status code.  A value of 0 indicates that no error
   occurred and that one occurrence of the specified data has been
   successfully retrieved.  A value of mrds_error_$tuple_not_found
   indicates that no error occurred and that no data satisfied the
   selection expression.


Notes:  For shared openings, the referenced relations must have
read_attr permit scope set.


For attribute level security, attributes referenced in the select and
where clauses must have read_attr access.


:Entry: set_scope: 12/01/86  dsl_$set_scope

Function:  This entry defines the user's current scope of access to the
data base for shared modes of openings.


Syntax:
declare dsl_$set_scope entry options (variable);
call dsl_$set_scope (db_index, rel_name1, permit_ops1, prevent_ops1,
   ..., rel_namen, permit_opsn, prevent_opsn, wait_sec, code);


Arguments:
db_index (Input) (fixed bin(35))
   is the index returned by dsl_$open that designates the data base.
rel_namei (Input) (char(*))
   is the name of the relation to be included in the scope.
permit_opsi (Input) (fixed bin)
   is an integer consisting of the scope code which indicates the
   operations the user may perform on the relation.
prevent_opsi (Input) (fixed bin)
   is an integer consisting of the scope code which indicates the
   operations that other users may not perform on the relation.


wait_sec (Input) (fixed bin(35))
   specifies the maximum number of seconds to wait for the scope
   request to be honored (there is no anticipated maximum).  This
   argument is optional and if not provided by the user, the default is
   30 seconds.
code (Output) (fixed bin(35))
   is a standard status code.  The code is 0 if set_scope is successful
   or is mrds_error_$db_busy if the data base is busy.


Notes:  Before a user can access the data base in shared mode, a scope
of access must be declared, consisting of a set of scope tuples.  If
this scope does not conflict with any other currently existing scope
(of other processes), it is accepted.  Otherwise, the user's request is
placed in a queue and is processed as soon as the requested resources
become available.  If the specified wait time is exceeded before the
request can be processed, an error code is returned.  Once the scope
has been accepted, only operations permitted by the scope may be
performed.  As time progresses in the current process, individual scope
tuples may be removed as they are no longer needed by invoking
dsl_$dl_scope.  However, new tuples may not be added to the current
scope until all current scope has been deleted.  This rule avoids
potential deadlock problems within the data base manager.


Codes for operations to be prevented or permitted are;

     Scope
     Code           Operation

       0            null
       1            read_attr or read
       2            append_tuple or store
       4            delete_tuple or delete
       8            modify_attr or modify


:Entry: set_scope_all: 12/01/86  dsl_$set_scope_all

Function:  This entry provides a means of setting a scope on all
relations defined in the user's view without the need to name each
relation.  Identical permit operations and prevent operations are
applied to all the relations in the user's view.


Syntax:
declare dsl_$set_scope_all entry options (variable);
call dsl_$set_scope_all (db_index, permit_ops, prevent_ops, wait_sec,
   code);


Arguments:
db_index (Input) (fixed bin(35))
   is the index returned by dsl_$open that designates the data base.
permit_ops (Input) (fixed bin)
   is the scope code which indicates the operations the user may
   perform on the relation.
prevent_ops (Input) (fixed bin)
   is the scope code which indicates the operations that other users
   may not perform on the relation.
wait_sec (Input) (fixed bin(35))
   specifies the maximum number of seconds to wait for the scope
   request to be honored (there is no anticipated maximum).  This
   argument is optional and, if not provided by the user, the default
   is 30 seconds.


code (Output) (fixed bin(35))
   is a standard status code.


Notes:  Scope codes for operations to be prevented or permitted are:

     Scope
     Code          Operation

       0            null
       1            read_attr or read
       2            append_tuple or store
       4            delete_tuple or delete
       8            modify_attr or modify


See dsl_$set_scope for access requirements.


:Entry: set_temp_dir: 12/01/86  dsl_$set_temp_dir

Function:  This entry sets the directory that is used for temporary
storage on the next call to dsl_$open.


Syntax:
declare dsl_$set_temp_dir entry (char(*), fixed bin(35));
call dsl_$set_temp_dir (path, code);


Arguments:
path (Input) (char(*))
   is the relative or absolute pathname of the directory to be used for
   temporary storage on the next call to open.
code (Output) (fixed bin(35))
   is the standard status code and is 0 unless an error occurs.


Notes:  This temporary directory has a default of process directory.
Therefore, this entry need never be called unless a record quota
overflow occurs on the process directory, as might happen in opening a
data base with a large number of relations, or during a large retrieve
or define_temp_rel operation.


See dsl_$set_temp_dir, dsl_$get_temp_dir, dsl_$get_opening_temp_dir,
and the commands display_mrds_temp_dir and set_mrds_temp_dir.


:Entry: store: 06/17/86  dsl_$store

Function:  This entry allows the user to add a tuple to a designated
relation in the data base.


Syntax:
declare dsl_$store entry options (variable);
call dsl_$store (data_base_index, relation_expression,
   new_value1, ... , new_valuen, code);


Arguments:
data_base_index (Input) (fixed bin(35))
   is the index returned by dsl_$open that designates the data base.
relation_expression (Input) (char(*))
   indicates the relation to which the tuple is to be added, as it
   appears in the user's view of the data base (the data model or the
   data submodel).  It may be the name of the relation or it may be
   "-another".
new_valuei (Input)
   is the new tuple value to be added to the relation.  The entire
   tuple, as defined in the user's view, may be specified with one
   structure or a list of variables, the items of which must correspond
   in order and quantity with the attributes defined in the user's
   view.


code (Output) (fixed bin(35))
   is a standard status code.  The value is 0 if the store was
   successful.  If a duplicate of the primary key already exists in the
   data base, the code value mrds_error_$dup_store is returned and the
   tuple is not stored.  (The name mrds_error_$duplicate_key may also
   be used.)  If a -check_proc option exists on a domain of one of the
   attributes in the relation for which a tuple is being added and the
   check procedure returns false, then the error code,
   mrds_error_$dom_integ, is returned.


Notes:  The placement of the new tuple within the relation is
determined by MRDS, based upon data model/data submodel descriptions of
the data base and the value of the primary key in the new tuple.  The
primary key of the new tuple must be unique within the designated
relation.  The caller must have read-write permission to the relation.
If storing through a submodel view, all attributes of the relation must
be defined in the submodel.


If the relation_expression is the name of a relation, the new tuple is
added to the named relation.  If the relation_expression is "-another",
the new tuple is added to the relation specified in the most recent
call to the dsl_$store in which the relation_expression argument
consisted of a relation name.  Any call to a dsl entry requiring a
<selection_expression> causes the previously specified relation name to
become unavailable for subsequent reference using "-another", until it
is again established via a call to dsl_$store with a
relation_expression consisting of the relation name.


The use of "-another" provides an efficient means to store several
tuples into a single relation via consecutive dsl_$store calls.


For shared openings, the relation must have append_tuple permit scope
set.


For attribute level security, the relation must have append_tuple
access and the key attributes must have read_attr access.


                                          -----------------------------------------------------------


Historical Background

This edition of the Multics software materials and documentation is provided and donated
to Massachusetts Institute of Technology by Group BULL including BULL HN Information Systems Inc. 
as a contribution to computer science knowledge.  
This donation is made also to give evidence of the common contributions of Massachusetts Institute of Technology,
Bell Laboratories, General Electric, Honeywell Information Systems Inc., Honeywell BULL Inc., Groupe BULL
and BULL HN Information Systems Inc. to the development of this operating system. 
Multics development was initiated by Massachusetts Institute of Technology Project MAC (1963-1970),
renamed the MIT Laboratory for Computer Science and Artificial Intelligence in the mid 1970s, under the leadership
of Professor Fernando Jose Corbato. Users consider that Multics provided the best software architecture 
for managing computer hardware properly and for executing programs. Many subsequent operating systems 
incorporated Multics principles.
Multics was distributed in 1975 to 2000 by Group Bull in Europe , and in the U.S. by Bull HN Information Systems Inc., 
as successor in interest by change in name only to Honeywell Bull Inc. and Honeywell Information Systems Inc. .

                                          -----------------------------------------------------------

Permission to use, copy, modify, and distribute these programs and their documentation for any purpose and without
fee is hereby granted,provided that the below copyright notice and historical background appear in all copies
and that both the copyright notice and historical background and this permission notice appear in supporting
documentation, and that the names of MIT, HIS, BULL or BULL HN not be used in advertising or publicity pertaining
to distribution of the programs without specific prior written permission.
    Copyright 1972 by Massachusetts Institute of Technology and Honeywell Information Systems Inc.
    Copyright 2006 by BULL HN Information Systems Inc.
    Copyright 2006 by Bull SAS
    All Rights Reserved