MULTICS TECHNICAL BULLETIN                                MTB-709

To:       MTB Distribution

From:     Jean Blair

Date:     May 7, 1985

Subject:  The mrds_call command as an active function

This MTB  describes how the  mrds_call command should  work as an
active  function.  Each  operation  of  the command  is explained
under  a separate  heading, as   it might  appear in  the Multics
Relational Data  Store Manual.  Emphasis is on  the data returned
from the  active function, especially in cases  where the command
and the active function produce different output.  Each operation
includes  examples of  what the  active function  returns.  For a
more  detailed description  of  the  mrds_call command,  refer to
AW53, section 9.

Send comments on this MTB via the system M forum:

     >udd>d>dbmt>con>MRDS_Development (mrdsdev)

or by electronic mail to:

     Blair -at System-M

or by telephone to:

     Jean Blair, HVN 249-6863

_________________________________________________________________

Multics  Project  internal  working  documentation.   Not  to  be
reproduced or distributed outside the Multics Project.


MTB-709                                              mrds_call.AF

                             CONTENTS

                                                         Page

    1:  Introduction  . . . . . . . . . . . . . . . . .   1
    2:  Summary of mrds_call Syntax . . . . . . . . . .   1
    3:  Overview of Operations  . . . . . . . . . . . .   1
    4:  Detail of Operations  . . . . . . . . . . . . .   3
    4.1:  close, c  . . . . . . . . . . . . . . . . . .   4
    4.2:  declare, dcl  . . . . . . . . . . . . . . . .   4
    4.3:  define_temp_rel, dtr  . . . . . . . . . . . .   5
    4.4:  delete, dl  . . . . . . . . . . . . . . . . .   6
    4.5:  dl_scope  . . . . . . . . . . . . . . . . . .   7
    4.6:  dl_scope_all, dsa . . . . . . . . . . . . . .   9
    4.7:  display_modes, dm . . . . . . . . . . . . . .   9
    4.8:  get_population, gp  . . . . . . . . . . . . .   10
    4.9:  get_scope, gs . . . . . . . . . . . . . . . .   10
    4.10: list_dbs, ld  . . . . . . . . . . . . . . . .   11
    4.11: modify, m . . . . . . . . . . . . . . . . . .   12
    4.12: open, o . . . . . . . . . . . . . . . . . . .   13
    4.13: retrieve, r . . . . . . . . . . . . . . . . .   14
    4.14: set_modes, sm . . . . . . . . . . . . . . . .   16
    4.15: set_scope, ss . . . . . . . . . . . . . . . .   17
    4.16: set_scope_all, ssa  . . . . . . . . . . . . .   18
    4.17: store, s  . . . . . . . . . . . . . . . . . .   19


mrds_call.AF                                              MTB-709

1:  INTRODUCTION

Some users have expressed a  desire to have the mrds_call command
work  as an  active function.   The most  obvious application for
this is to use the result of the open operation, a database index
value, as input  to a subsequent operation which  takes the index
as an argument.

For some types  of operations, the result of  the active function
will be no more than an indicator of the success of an operation.
For others, error messages normally returned by the command, will
be  interpreted such  that the  active function  will return some
useful information.   In some cases, the  active function returns
less information than the command displays, but in all cases, the
intent is for the active  function to return essentially the same
information as the command would display.

2:  SUMMARY OF MRDS_CALL SYNTAX

SYNTAX AS A COMMAND:
     mrc operation_name {args}

SYNTAX AS AN ACTIVE FUNCTION:
     [mrc operation_name {args}]

Arguments:

     operation_name
          this is  the name of one  of the dsl_ entry  points, or
          one   of  the   three  mrds_call   operations  list_db,
          set_modes,  or list_modes.    See "List  of operations"
          below.  For  a detailed description of  each operation,
          type "help mrc.OPERATION", where  OPERATION is the name
          of the specific operation.

     args these  are  the  individual  arguments  required  by  a
          particular  dsl_  entry  point,  which  depend upon the
          particular operation to be performed.

3:  OVERVIEW OF OPERATIONS

List of operations:

     close, c
          closes  the specified,  currently open  databases.  The
          active  function returns true  if all of  the specified
          databases are able to be  closed, and false is returned
          if any cannot be closed.


MTB-709                                              mrds_call.AF

     declare, dcl
          makes  a  user-defined  function  known  to  MRDS.  The
          active  function  returns  true  if  the  user  defined
          function is made known.   False is returned to indicate
          failure of the declare active function.

     define_temp_rel, dtr
          creates,  redefines, or  deletes a  temporary relation.
          The  command prints  a rel_index  value and  the active
          function  returns the  rel_index.  If  the operation is
          unsuccessful,   the   active   function   will   signal
          active_function_error.

     delete, dl
          specifies that the selected data  is to be deleted from
          the database.  The active  function returns true if the
          data is deleted  or if there is no  tuple which matches
          the selection expression.   The active function returns
          false if there is an error in the selection expression.

     dl_scope, ds
          deletes part or all  of the current concurrency control
          scope modes  on a relation basis.   The active function
          returns  true  if  all  the  specified  scope modes are
          deleted, or false if any are unable to be deleted.

     dl_scope_all, dsa
          deletes all  scope from the user's current  view of the
          database.   The  active  function  returns  true if all
          scope is deleted, or false if all scope is not deleted.

     display_modes, dm
          displays  the values  for the  error and  display modes
          which  are  in  effect  for  the  process.   The active
          function signals an  active_function_error if the modes
          cannot be displayed.

     get_population, gp
          returns the  number of tuples that make  up a temporary
          or permanent  relation.  The command prints  the number
          and the active function returns the number.

     get_scope, gs
          displays  the current  scope settings  on a  particular
          relation.  The  active function returns the  permit and
          prevent scopes as two individual strings.

     list_dbs, ld
          displays the  opening index, opening mode,  and path of
          the  model used for  the opening.  The  active function
          returns the  three pieces of information  for each open
          database as three individual strings.


mrds_call.AF                                              MTB-709

     modify, m
          modifies  the designated   database as  specified.  The
          active  function  returns  true   if  the  database  is
          modified, or false if nothing is modified.

     open, o
          opens  the specified  databases or  data submodels  for
          processing.  The active function returns the indices of
          the opened databases,  or signals active_function_error
          if all the specified databases cannot be opened.

     retrieve, r
          retrieves  and  displays  selected  information  from a
          database.  The active function returns the individually
          quoted attributes  of each tuple selected.   The active
          function  will  signal   active_function_error  if  the
          selection expression is in error  or the data cannot be
          retrieved  for some  reason.   If  no tuples  match the
          selection expression,  as is the case when  there is no
          more data when using -another, the active function will
          signal mrds_no_tuple_found.

     set_modes, sm
          allows  control  of  the  amount  of  error  or display
          information printed.  The  active function returns true
          if  the options are  set, or false  if the options  are
          unable to be set.

     set_scope, ss
          defines  the current  scope  of  access for  a relation
          within a shared database.   The active function returns
          true if the scope is set  as specified, or false if any
          scope cannot be set.

     set_scope_all, ssa
          defines the  current scope of access  for all relations
          within a shared database.   The active function returns
          true if scope is set for all relations as specified, or
          false if all scope is not set.

     store, s
          adds a  new tuple (row) to the  selected relation.  The
          active function returns true if the tuple is stored, or
          false if the store fails.

4:  DETAIL OF OPERATIONS

The  following section  provides a  detailed explanation  of each
operation  including  syntax,   function,  arguments,  notes  and
examples.  The examples are provided to illustrate the command as
an active function only.


MTB-709                                              mrds_call.AF

4.1:  close, c

Syntax as a command:
     mrc c database_indices mrc c -control_arg

Syntax as an active function:
     [mrc c database_indices] [mrc c -control_arg]

Function:
     closes  the specified  databases and  makes them unavailable
     for  further processing.  The  databases need not  have been
     opened  by  the  mrds_call  command.   The  active  function
     returns true  if all databases  are closed, or  false if any
     are unable to be closed.

Arguments:

     database_indices
          are  the database index  values returned or  printed by
          the open operation for the databases to be closed.

Control Arguments:
     -all, -a

     specifies that all of the user's open databases are to
          be closed.  This argument  is incompatible with the use
          of database_indices.

Examples
     !  mrds_call open >udd>m>jkb>Pers_Info.db update
        1
     !  string [mrds_call close 1]
        true

     !  string [mrc o Pers_Info r Pers_Info u]
        1 2
     !  string [mrc c -all]
        true

4.2:  declare, dcl

Syntax as a command:
     mrc dcl database_index function_name

Syntax as an active function:
     [mrc dcl database_index function_name]

Function:
     makes a user  defined function known to MRDS for  use with a
     specific open database.  The active function returns true if


mrds_call.AF                                              MTB-709

     the  user defined function  is made known,  or false if  the
     function is unable to be made known.

Arguments:

     database_index
          is the index of the database for which the user defined
          function applies.

     function_name
          is  the  name  of  the  function  being  declared.  The
          function_name can be expressed as a pathname.

Examples
     !  string [mrds_call declare 1 average]
        true

     !  string [mrds_call declare 1 >udd>Multics>jkb>trim]
        true

4.3:  define_temp_rel, dtr

Syntax as a command:
     mrc dtr database_index {selection_expression} {se_values}
        rel_index {-control_arg}

Syntax as an active function:
     [mrc dtr database_index {selection_expression} {se_values}
        rel_index {-control_arg}]

Function:
     creates,  redefines, or  deletes a  temporary relation  in a
     given  open database.   The rel_index  corresponding to  the
     temporary relation is printed when  the operation is used as
     a command, or  returned when the operation is  invoked as an
     active  function.   When  a  temporary  relation  is  to  be
     deleted,  the selection_expression may  be null, and  if the
     operation  is successful,  the value  zero is  returned.  An
     active_function_error    will    be    signalled    if   the
     selection_expression is in error.

Arguments:

     database_index
          is the index returned or  printed by the open operation
          of the database for which  the temporary relation is to
          be created.

     selection_expression
          is a character string specifiying the data items in the


MTB-709                                              mrds_call.AF

          user's  view of  the database.   This argument  must be
          omitted if the -segment control argument is specified.

     se_values
          is  a selection expression  value (none, one,  or more)
          for each control code (designated by .V.)  appearing in
          the <selection_expression>.

     rel_index
          is  an integer.  If  equal to zero,  a new temp_rel  is
          created.  If greater than  zero, the temp_rel with that
          index  is redefined.  If  less than zero,  the temp_rel
          with the absolute value of the index is deleted.

Control arguments:

     -segment path, -sm path
          specifies that the selection  expression is to be taken
          from  the  designated  segment.   If  the  -sm  control
          argument  is used,  it must  be the  last thing  on the
          command line, following the rel-index.

Notes
     The  temporary  relation  is  defined  only  for  the  given
     database  opening.  Unpopulated  temporary relations  can be
     created  if the  selection  expression  does not  select any
     tuples.

Examples
     !  string [mrds_call define_temp_rel 1 "-range (E Employee)
     !    -select E.name* E.dept" 0]
        1

     !  string [mrds_call define_temp_rel 1 "-range (E Employee)
     !    -select E.name* E.emp_no" 1]
        1

     !  string [mrds_call define_temp_rel 1 "-range (E Employee)
     !    -select E.name* E.emp_no" -1]
        0

     These  three examples  show the  creation, modification  and
     deletion of a temporary relation, and the resultant relation
     index value.

4.4:  delete, dl

Syntax as a command:
     mrc dl database_index {selection_expression} {se_values}
        {-control_arg}


mrds_call.AF                                              MTB-709

Syntax as an active function:
     [mrc dl database_index {selection_expression} {se_values}
        {-control_arg}]

Function:
     deletes  selected tuples  from the  designated database.  If
     any tuples are deleted or if there are no tuples which match
     the selection expression, the  active function returns true.
     Otherwise, if the deletion fails  for any reason, the active
     function returns false.

Arguments:

     database_index
          is the index returned or  printed by the open operation
          of the database from which the tuple is to be deleted.

     selection_expression
          is a character string specifying  the data items in the
          user's  view of  the database.   This argument  must be
          omitted if the -segment control argument is specified.

     se_values
          is  a selection expression  value (none, one,  or more)
          for each control code (designated by .V.)  appearing in
          the <selection_expression>.

Control arguments:

     -segment path, -sm path
          specifies that the selection  expression is to be taken
          from the designated segment.   If this control argument
          is used, it must be in the last position on the command
          line.

Examples
     !  string [mrds_call delete 1 "range (E Employee) -select E
     !    -where E.name = ""Blair"" "]
        true

     !  string [mrds_call delete 1 "range (E Employee) -select E
     !    -where E.name = ""Blair"" "]
        true

     The  first  example  shows  the  deletion  of  a tuple which
     matched the selection expression.   The second example shows
     the result when no matching tuple is found.


MTB-709                                              mrds_call.AF

4.5:  dl_scope

Syntax as a command:
     mrc ds database_index relation_name_1 permit_scope_1
        prevent_scope_1 {...  relation_name_N permit_scope_N
        prevent_scope_N}

Syntax as an active function:
     [mrc ds database_index relation_name_1 permit_scope_1
        prevent_scope_1 {...  relation_name_N permit_scope_N
        prevent_scope_N}

Function:
     deletes part or all of the current concurrency control scope
     modes on a relation basis.  This operation is used only with
     shared openings which are not set for exclusion.  The active
     function returns  true if scope is deleted  as specified, or
     false if scope is unable to be deleted.

Arguments:

     database_index
          is the index returned or  printed by the open operation
          of the database from which scope is to be deleted.

     relation_name
          is the  name of the relation for  which the concurrency
          control  permit  and  prevent  scope  modes  are  to be
          deleted.

     permit_scope
          is the set of operations that the user wishes to delete
          from the current permit scope for this relation.

     prevent_scope
          is the set of operations that the user wishes to delete
          from the current prevent scope for this operation.

Notes
     The abbreviations to be used  for the scope modes for either
     permits or prevents are as follows:
        a (or s) append_tuple
        d        delete_tuple
        m        modify_attr
        n        null
        r        read_attr
        u        update
     The permit and prevent scopes are made up of a concatenation
     of the desired operation abbreviations.

Examples
     !  mrds_call open Pers_Info.db update


mrds_call.AF                                              MTB-709

        Open data base is:
        1         >udd>m>Blair>Pers_Info.db
                  update

     !  mrds_call set_scope 1 Employee ramd n Dept r amd

     !  string [mrds_call dl_scope 1 Employee amd n Dept n amd]
        true

4.6:  dl_scope_all, dsa

Syntax  as a command:
     mrc dsa database_index

Syntax as an active function:
     [mrc dsa database_index]

Function:
     deletes  all  scope  from  the  user's  current  view of the
     database.  The active function returns  true if all scope is
     deleted, or false if any scope is not deleted.

Arguments:

     database_index
          is the index returned or  printed by the open operation
          of the database from which all scope is to be deleted.

Notes
     No  error will  be issued  if  scope  is not  set when  this
     operation is used.

Examples
     !  string [mrds_call dl_scope_all 1]
        true

4.7:  display_modes, dm

Syntax as a command:
     mrc dm

Syntax as an active function:
     [mrc dm]

Function:
     displays the mrds_call modes in effect for the process.  The
     modes  are returned  as a  character string  with the  modes
     separated   by   commas.    The   active   function  signals
     active_function_error if the modes cannot be displayed.


MTB-709                                              mrds_call.AF

Examples
     !  string [mrc dm]
        error=long,^list

4.8:  get_population, gp

Syntax as a command:
     mrc gp database_index relation_identifier

Syntax as an active function:
     [mrc gp database_index relation_identifier]

Function:
     prints or returns the number of tuples that make up either a
     temporary or permanent relation.

Arguments:

     database_index
          is the index returned or  printed by the open operation
          on the  database from which the  relation population is
          to be obtained.

     relation_identifier
          is  the identification  of the  relation for  which the
          population is to be obtained.  For temporary relations,
          it is the temporary relation index returned from a call
          to   the  define_temp_rel   function.   For   permanent
          relations, it is the view relation name.

Notes
     Since temporary relations do not store duplicates, it is not
     possible to get a true count of a selection expression tuple
     population  where  the  -dup   option  is  involved,  unless
     temp_rel   keys  are   defined  over   uniquely  identifying
     attributes.

Examples
     !  string [mrds_call get_population 1 Employee]
        4

     !  mrds_call dtr 1 "range (E Employee) select E.name E.dept"
     !    0
        Temporary relation index is:  1.
     !  string [mrc gp 1 1]
        4


mrds_call.AF                                              MTB-709

4.9:  get_scope, gs

Syntax as a command:
     mrc gs database_index relation_name

Syntax as an active function:
     [mrc gs database_index relation_name]

Function:
     prints the current scope  settings on a particular relation.
     The  active  function  returns  the  string  of concatenated
     permit scopes followed by the string of concatenated prevent
     scopes.   If  the  scopes  cannot  be  returned,  the active
     fuinction signals active_function_error.

Arguments:

     database_index
          is the index returned or  printed by the open operation
          of the database for which  the relation's scopes are to
          be displayed.

     relation_name
          is the name of the relation whose scope settings are to
          be displayed.

Notes
     If the concurrency control version  is less than 5, then "s"
     (store)  will be displayed;  otherwise "a" (append)  will be
     used.

Examples
     !  mrds_call set_modes no_list
     !  mrds_call open Pers_Info exclusive_update

     !  string [mrds_call get_scope 1 Employee]
        ramd ramd

4.10: list_dbs, ld

Syntax as a command:
     mrc ld

Syntax as an active function:
     [mrc ld]

Function:
     displays the  opening index, opening  mode, and path  of the
     model or submodel for all  openings of MRDS databases in the
     user's  process.  The  active function  returns each  of the


MTB-709                                              mrds_call.AF

     three values as separate strings, or if the operation fails,
     active_function_error will be signalled.

Examples
     !  mrds_call set_modes no_list
     !  mrds_call open Pers_Info eu employee r

     !  format_line "^(^a:^a:^a^/^)" [list_dbs]
        1:>udd>Multics>Blair>Pers_Info.db:exclusive_update
        2:>udd>Multics>Blair>employee.db:retrieval

4.11: modify, m

Syntax as a command:
     mrc m database_index {selection_expression} {se_value}
        modified_values {-control_arg}

Syntax as an active function:
     [mrc m database_index {selection_expression} {se_value}
        modified_values {-control_arg}]

Function:
     modifies the  designated database as specified.   The active
     function returns true if any attributes are modified.  If no
     tuples are found which match the selection expression, or if
     an error occurs the active function returns false.

Arguments:

     database_index
          is the index returned or  printed by the open operation
          of the database which is to be modified.

     selection_expression
          is a character string specifying  the data items in the
          user's  view of  the database.   This argument  must be
          omitted if the -segment control argument is specified.

     se_values
          is  a selection expression  value (none, one,  or more)
          for each control code (designated by .V.)  appearing in
          the <selection_expression>.

     modified_values
          is one or more values  that are to replace the selected
          tuple attribute values in the database.

Control arguments:

     -segment path, -sm path
          specifies that the selection  expression is to be taken


mrds_call.AF                                              MTB-709

          from the designated segment.   If this argument is used
          it must be in the last position on the command line.

Examples
     !  string [mrds_call modify 1 "-range (E Employee) -select
     !     E.dept -where E.name = ""Adams"" " Accounting]
        true
     !  mrc r 3 1 "-range (E Employee) -select E -where E.name =
     !     ""Adams"" "

        Adams
        11111
        Accounting

     The next example shows the result when no tuple matching the
     selection expression can be found.

     !  string [mrc m 1 "-range (E Employee) -select E.dept
     !     -where E.name = ""Adams"" & E.dept ^= ""Accounting"" "
     !     Finance]
        false

4.12: open, o

Syntax as a command:
     mrc o view_path_1 open_mode_1 {...  view_path_N open_mode_N}

Syntax as an active function:
     [mrc o view_path_1 open_mode_1 {...  view_path_N
        open_mode_N}]

Function:
     opens  a  database  and  readies  it  for  use.  The default
     display  mode prints the  database index, the  opening mode,
     and the pathname of the  model or submodel for each opening.
     The  active function returns  only the database  indices for
     the   models  and   submodels  opened   during  the  current
     invocation.  If any of the specified databases are unable to
     be  opened, none  of them   will be  opened, and  the active
     function will signal active_function_error.

Arguments:

     view_path
          is the pathname of the desired  view to be used for the
          opening.  If  an absolute pathname is not  given, and a
          model and  submodel of the same pathname  reside in the
          same   directory,  and   no  suffix   is  supplied   to
          distinguish  between  them,  the  model  will  be found
          before the submodel.


MTB-709                                              mrds_call.AF

     open_mode
          is the desired opening  mode for this database opening.
          The following opening modes are available:
             r retrieval
             u update
             er exclusive_retrieval
             eu exclusive_update

Examples
     !  string [mrds_call open Pers_Info r]
        1

     !  mrds_call set_modes no_list
     !  string [mrc o Pers_Info u employee.db er]
        2 3

     The second example illustrates that  the no_list mode has no
     affect  on the  open command  when it  is used  as an active
     function.

4.13: retrieve, r

Syntax as a command:
     mrc r nvals database_index {selection_expression}
        {se_values} {control_args}

Syntax as an active function:
     [mrc r nvals database_index {selection_expression}
        {se_values} {control_args}]

Function:
     retrieves  and prints  or returns  selected information from
     the database.   The command displays tuples  which match the
     selection  expression and  the active  function returns each
     attribute of  the tuple as  a separately quoted  string.  If
     the  active function  results in  no tuples  which match the
     selection expression mrds_no_tuples_found will be signalled.
     If the  operation cannot be completed for  any other reason,
     the active function will signal active_function_error.

Arguments:

     nvals
          is a  decimal integer greater than  zero specifying the
          number of attributes to  be retrieved from the selected
          tuple.

     database_index
          is the index returned or  printed by the open operation
          of  the  database  from  which  the  tuples  are  to be
          retrieved.


mrds_call.AF                                              MTB-709

     selection_expression
          is a character string specifying  the data items in the
          user's  view of  the database.   This argument  must be
          omitted if the -segment control argument is specified.

     se_values
          is  a selection expression  value (none, one,  or more)
          for each control code (designated by .V.)  appearing in
          the <selection_expression>.

Control arguments:

     -all, -a
          specifies  that  all  selected  tuples  be  printed  or
          returned.   If not  specified, only  the first selected
          tuple  is printed  and  any  subsequent tuples  must be
          explicitly retrieved by a  new retrieve operation using
          "-another" for the selection expression.

     -segment path, -sm path
          specifies that the selection  expression is to be taken
          from the designated segment.

Notes
     The selection  expression and the -segment  control argument
     are mutually exclusive.

     For  the  active  function,  if  the  summed  lengths of the
     requoted values returned by the operation exceed the size of
     a segment, an error will be signaled.

     At present, any attribute with  a length greater than 256 is
     truncated  without  warning.   The  new  implementation will
     return the entire value  as a character string.  Descriptors
     will be  built for each  attribute to be  retrieved from the
     database, taking into account the data-type and the possible
     need  for conversion  from numeric  to character  data.  The
     data will be  returned to the user with  blanks trimmed from
     the  right.  In  addition,  the  active function  will ltrim
     blanks that may have been  inserted during the conversion to
     characters from  the internal data_type.  In  the case where
     the the  sum of the  lengths of the  attributes would exceed
     one segment, an error condition will be signaled.

Examples
     !  fl "^a:^a:^a^/^"  [mrds_call retrieve 3 1 "-range
     !    (E Employee) -select E" -all]

        Hamilton 48277 Manufacturing
        Morton 48350 Engineering
        Whiting 49189 Finance
        Adams 11111 Accounting


MTB-709                                              mrds_call.AF

     !  on mrds_no_tuple_found "" "string [mrc r 3 1 ""-range
     !    (E Employee) -select E -where E.name = """"Blair"""" ""]"

        on: Condition "mrds_no_tuple_found" raised. Mrds_call: No tuple was
        found which satisfied the selection expression. (From dsl_$retrieve)

     The second example  shows the result when no  tuple is found
     which matches the selection expression.

4.14: set_modes, sm

Syntax as a command:
     mrc sm -control_arg

Syntax as an active function:
     [mrc sm -control_arg]

Function:
     sets the  options which control  how much error  and display
     information  will be  printed for  various operations.   The
     active function returns  true if the option is  set or false
     if an error occurs.

Control arguments:

     -modes STR
          allows  the  user  to  select  the  initial  values  of
          mrds_call's modes according to STR which is a string of
          mode names  separated by commas.   For a list  of valid
          mode  names,  see  "List  of  modes"  below.  Modes not
          specified in STR are left unchanged.

List of modes:

     list, ^list
          enables/disables    listing    of    database   opening
          information (Default is on).

     error=short
          suppress output from the sub_error_ condition

     error=long
          allow output from the sub_error_ condition (Default).

Notes
     If  both  list  and  ^list,  or  long  and  short  error are
     specified in the same command  line, the last mode to appear
     will prevail.   The open command as an  active function will
     always  return a  database index,  regardless of  which list
     option is specified.


mrds_call.AF                                              MTB-709

Examples
     !  string [mrds_call set_modes -modes error=long,^list]
        true

4.15: set_scope, ss

Syntax as a command:
     mrc ss database_index relation_name_1 permit_scope_1
        prevent_scope_1 {...  relation_name_N permit_scope_N
        prevent_scope_N} {wait_seconds}

Syntax as an active function:
     [mrc ss database_index relation_name_1 permit_scope_1
        prevent_scope_1 {...  relation_name_N permit_scope_N
        prevent_scope_N} {wait_seconds}]

Function:
     sets the operations that are to be permitted to the user and
     the operations  that are to be  simultaneously prevented for
     other  openers of the  same database.  Scopes  are set on  a
     relation  basis.  This  operation is  used only  with shared
     databases  opened in  the  retrieval  or update  modes.  The
     active function returns true if scopes are set as specified.
     If an error  occurs during the setting of  scopes the active
     function will return false.

Arguments:

     database_index
          is the index returned or  printed by the open operation
          of the database for which scopes are to be set.

     relation_name
          is the  name of the relation for  which the concurrency
          control permit and prevent scope modes are to be set.

     permit_scope
          is the set of operations that the user wishes to permit
          himself to be allowed for this relation.

     prevent_scope
          is the set  of operations that the user  wishes to deny
          other openers of the same database for this relation.

     wait_seconds
          is the  amount of time, in seconds,  the user's process
          will  wait before  failing in  an attempt  to set scope
          modes  that  conflict  with  another  user's permit and
          prevent scope.  The full wait  time is only used if the
          conflict  remains  in  effect  for  the  entire period;


MTB-709                                              mrds_call.AF

          otherwise scope  will be granted.  If  this argument is
          not given, the default wait period is 30 seconds.

Notes
     All scope  must be deleted  from all relations  before scope
     can be  set on any  relation.  Abbreviations to  be used for
     the  scope  modes  for  either  permits  or  prevents are as
     follows:
        a (or s) append_tuple
        d delete_tuple
        m modify_attr
        n null
        r read_attr
        u update

Examples
     !  mrds_call set_modes no_list
     !  mrds_call open Pers_Info u

     !  string [mrds_call set_scope 1 Employee ramd ramd]
        true

4.16: set_scope_all, ssa

Syntax as a command:
     mrc ssa database_index permit_scope prevent_scope
        {wait_seconds}

Syntax as an active function:
     [mrc ssa database_index permit_scope prevent_scope
        {wait_seconds}]

Function:
     sets the  operations that are  to be permitted  the user and
     the operations  that are to be  simultaneously prevented for
     other openers of the same database.  The scope modes are set
     on all relations at once.   The active function returns true
     if scope is set for  all relations.  If the specified scopes
     cannot be set, the active function returns false.

Arguments:

     database_index
          is the index returned or  printed by the open operation
          of the  database for which scope  is to be set  for all
          relations.

     relation_name
          is the  name of the relation for  which the concurrency
          control  permit  and  prevent  scope  modes  are  to be
          deleted.


mrds_call.AF                                              MTB-709

     permit_scope
          is the set of operations that the user wishes to permit
          himself to be allowed for all relations.

     prevent_scope
          is the set  of operations that the user  wishes to deny
          other openers of the same database for all relations.

     wait_seconds
          is the  amount of time, in seconds,  the user's process
          will  wait before  failing in  an attempt  to set scope
          modes  that  conflict  with  another  user's permit and
          prevent scope.  The full wait  time is only used if the
          conflict  remains  in  effect  for  the  entire period;
          otherwise scope  will be granted.  If  this argument is
          not given, the default wait period is 30 seconds.

Notes
     All scope  must be deleted  from all relations  before scope
     can be  set on any  relation.  Abbreviations to  be used for
     the  scope  modes  for  either  permits  or  prevents  as as
     follows:
        a (or s) append_tuple
        d delete_tuple
        m modify_attr
        n null
        r read_attr
        u update

Examples
     !  mrds_call set_modes no_list
     !  mrds_call open Pers_Info u

     !  string [mrds_call set_scope_all 1 ramd ramd 90]
        true

4.17: store, s

Syntax as a command:
     mrc s database_index relation_expression new_values

Syntax as an active function:
     [mrc s database_index relation_expression new_values]

Function:
     adds a specified tuple to the database.  The active function
     returns true  if a tuple  is stored.  If  too few attributes
     are given, or if the tuple cannot be stored in the database,
     the active function returns false.

Arguments:


MTB-709                                              mrds_call.AF

     database_index
          is the index returned or printed by the open operation.

     relation_expression
          indicates the relation to which a tuple is to be added.
          It   may   be   the   name   of   a   relation  or  the
          control_argument -another.

     new_values
          are the attribute values to be added to the new tuple.

Notes
     If an incomplete  tuple is being stored (i.e.,  a tuple with
     one or more unknown attribute  values), the user must select
     null values  for inclusion in the tuple  to prevent shifting
     of attributes within domains/attributes.

Examples
     !  string [mrds_call store 1 Employee Blair 22990 Sys]
        true