Multics Technical Bulletin                                MTB 642

To:       MTB Distribution

From:     Roger Lackey and Ron Harvey

Date:     December 21, 1983

Subject:  The View Manager Facility:
          View Manager Subroutine Interface

ABSTRACT

This paper describes the subroutine interface to the View Manager
Facility.

This MTB is only one of a  group of related documents in the View
Manager series.  These documents are

    MTB-641  The View Manager Facility
    MTB-642  The View Manager Facility:  Subroutine Interfaces
    MTB-643  The View Manager Facility:  The View Master Subsystem
    MTB-644  The View Manager Facility:  SQL Parser
    MTB-645  The View Manager Facility:  Data Dictionary Interface

Comments may be made:

     Via forum:
                  >udd>m>mtgs>End_User_Data_Access (euda)

     Via electronic mail:
                  Lackey.Multics   on   System M
                  Harvey.Multics   on   System M

     Via telephone:
                  Lackey (HVN) 357-6633 or (602) 862-6633
                  Harvey (HVN) 357-6639 or (602) 862-6639

_________________________________________________________________

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


MTB 642                                Multics Technical Bulletin

1.0 INTRODUCTION

     The  purpose of  the View Manager  Facility is  to provide a
general  yet well  defined interface  to support  Canonical Query
Language  (CQL, see  Appendix B) statements  for the manipulation
data that can be "viewed" as a table.

The View Manager Facility consists of six major parts:

       1.  The View Manager Manipulator (VMM) that will
          do  most  of View  Manager Facility  work and
          whose  subroutine  interface is  described in
          this document.

       2.  A set of View Manager Data Dictionaries that
          contain  descriptions  and properties  of the
          tables and  views used by  the Facility.  See
          MTB   645   for   details   about   the  Data
          Dictionary.

       3. A set  of Table Interface  Modules (TIM) that
          provide an interface between the View Manager
          Manipulator  (VMM)  and  each  specific table
          manager (TM).

       4.   An  error  handling utility  to  handle the
          error reporting for  errors encountered while
          using the view  manager.  The error reporting
          for  the  vm_  interface   will  be  done  by
          signaling  the vm_sub_error_  condition.  The
          vm_error_util_   will  be   similiar  to  the
          dm_error_util_ described in MTB-639.

       5. The Application Programmer's Interface (API).

       6. The End User Interface (View Master).


Multics Technical Bulletin                                MTB 642

name:  vm_

     The  vm_ subroutine  is a  set of  programs that  do all the
manipulation  for  the  View   Manager  Facility.   Most  of  the
manipulation  done by  the VMM  is accomplished  by executing the
Canonical Query Language (CQL) that is an internal representation
of SQL statements.  The Canonical  Query Language is described in
Appendix  B.    Other  then  fetching  data   via  a  cursor  and
translating  SQL  to  CQL,  everything  else  is  accomplished by
executing CQL.

The vm_ entry points descriptions follow.

entry:  vm_$translate_sql_statement

     This entry point  is used to translate an  sql statement and
return cql_structure and vm_needed_info structure.

USAGE

      dcl vm_$translate_sql_statement entry options (variable);

      call  vm_$translate_sql_statement  (dd_path, sql_statement,
            return_area_ptr,        replacement_arg_1       ....,
            replacement_arg_N, cql_ptr, vm_needed_info_ptr);

ARGUMENTS

dd_path
      is a  character string char  (*) varying that  contains the
      pathname of  the data dictionary  to be used  while parsing
      the sql.  (input)

sql_string
      is  a  character  string  char (*)  that  contains  the sql
      statement to be parsed.  (input)

return_area_ptr
      is a pointer to an area  where this routine will allocate a
      the returned cql structure.  (input)

replacement_arg_I
      are  a variable  number of arguments  (possibly none), each
      char (*),  that will be used  as substitution arguments for
      &N  in  the sql_str.   The  &N is  associated with  the Nth
      replacement_arg.  (input)


MTB 642                                Multics Technical Bulletin

cql_ptr
      is a pointer to the cql_info structure that is generated by
      the translation process.

vm_needed_info_ptr
      is a pointer to the vm_needed_info structure.  (output)

entry:  vm_$convert_cql_to_needed_info

     This entry point is used convert cql into the vm_needed_info
structure that contains the  statement name and information about
the input and output arguments required.

USAGE

      dcl vm_$convert_cql_to_needed_info       entry      options
            (variable);

      call vm_$convert_cql_to_needed_info               (cql_ptr,
            return_area_ptr, vm_needed_info_ptr);

            ARGUMENTS

cql_ptr
      is a pointer  to a set of cql_structures  that describe the
      cql for the request.  (input)

return_area_ptr
      is a  pointer to an  area where this  routine will allocate
      the returned vm_needed_info_structure.  (input)

vm_needed_info_ptr
      is a pointer to the vm_needed_info structure.  (output)


Multics Technical Bulletin                                MTB 642

ENTRY INFORMATION

The vm_needed_info_ptr points to the following structure (defined
in the include file vm_needed_info.incl.pl1).

dcl 1 vm_needed_info aligned based (vm_needed_info_ptr),
      2 version char (8),
      2 statement_type fixed bin (17) unaligned,
      2 mbz bit (18) unaligned,
      2 statement_name char (32) varying,
      2 number_of_inputs fixed bin (17) unaligned,
      2 number_of_outputs fixed bin (17) unaligned,
      2 io_arguments (vni_number_argument_infos
                      refer (vm_needed_info.number_of_inputs +
                             vm_needed_info.number_of_outputs)),
        3 name char (32) varying,
        3 class char (32) varying,
        3 descriptor bit (36) aligned,
        3 max_length fixed bin (24);

STRUCTURE ELEMENTS

statement_type
     specifies  the cql  statement_type as  a query,  dml, ddl or
     control statement.   Include file vm_statement_type.incl.pl1
     contains the named constants for the statement types.

mbz
     reserved for future use.

statement_name
     specifies the statement name within the statement type.

number_of_inputs
     specifies the number of input arguments required.

number_of_outputs
     specifies the number of output arguments required.

name
     specifies a name that may  be associated with this argument.
     It  is most  likely to  be used  with an  input argument and
     could  be  used  by  an  end  user  facility  for prompting.
     Situations may exists where name will be blank.

class
     specifies the class of  the argument.  The currently defined
     classes of arguments are:
          cql
          cursor


MTB 642                                Multics Technical Bulletin

     Include  file  vm_class_type.incl.pl1   contains  the  named
     constants for class.

descriptor
     specifies the Multics data descriptor type of the argument.

max_length
     specifies  the maximum  length allowed  for the  argument in
     bits.


Multics Technical Bulletin                                MTB 642

entry:  Entry:  vm_$execute_cql

     This entry point is used to execute CQL statements.

USAGE

      dcl vm_$execute_cql entry options (variable);

      call vm_$execute_cql (cql_ptr, needed_arg_1, needed_arg_N);

ARGUMENTS

cql_ptr
      is  a  pointer  to   the  cql_definition  structure  to  be
      executed.  (input)

needed_arg_I
      are  a variable  number of  arguments (possibly  none), the
      type will  depend on the requirements  of the cql statement
      being executed.  (input/output)


MTB 642                                Multics Technical Bulletin

entry:  vm_$open_cursor

     This entry point is used to open and create a cursor for use
by the vm_$fetch  entry point.  It will execute  the CQL and upon
normal  return have  available the  first set  of returned values
from the CQL select statement.  The user should use the vm_$fetch
to get the returned data value.

USAGE

      dcl vm_$open_cursor entry options (variable);

      call vm_$open_cursor (cursor_name, cql_ptr, input_argN);

ARGUMENTS

cursor_name
      is  the name  char (32)  of the cursor  to be  used for the
      open_cursor.  (input)

cql_ptr
      is the  pointer to the  cql_info structure of  a select CQL
      statement.  (input)

input_argN
      is a variable number of  arguments (may be none), depending
      on  the requirements  of the  CQL select  statement.  It is
      determined from the input_arguments  returned from the call
      to vm_$get_needed_arguments  for the CQL  select statement.
      (input).


Multics Technical Bulletin                                MTB 642

entry:  vm_$fetch

     This  entry  point  is used  to  fetch data  using  a cursor
created by the vm_$open_cursor entry point.

USAGE

      dcl vm_$fetch entry options (variable);

      call vm_$fetch (cursor_name, output_argN);

ARGUMENTS

cursor_name
      is  the name  char (32)  of the cursor  to be  used for the
      fetch.  (input)

output_argN
      is a variable number of arguments (at least one), where the
      data is to be returned to  the caller.  The number and data
      type  are  dependent  on  the  CQL  used  in  the  call  to
      vm_$open_cursor.  (input)

entry:  vm_$close_cursor

     This entry point is used to  close and destroy a cursor that
was created by a call to the vm_$open_cursor entry point.

USAGE

      dcl vm_$close_cursor entry (char (32));

      call vm_$close_cursor (cursor_name);

ARGUMENTS

cursor_name
      is the name of the cursor to be closed.  (input)


MTB 642                                Multics Technical Bulletin

entry:  vm_$set_temp_dir

     This entry point is used to set the temporary directory used
by the View Manager for temporary segment and directory creation.
If  not  used, the  default  temporary directory  is  the process
directory.  If the specified does not exists it will be created.

USAGE

      dcl vm_$set_temp_dir entry (char (*));

      call vm_$set_temp_dir (directory_pathname);

ARGUMENTS

directory_pathname
      is a relative  or absolute pathname of the  directory to be
      used for temporary space.


Multics Technical Bulletin                                MTB 642

entry:  vm_$terminate

     This  entry  point is  used  to terminate  the  view manager
facility.  Its  purpose is to  cause any open table  to be closed
and to cleanup  temporary space created by the  view manager.  It
should be used in epilogue handlers.

USAGE

      dcl vm_$terminate entry ();

      call vm_$terminate ();


MTB 642                                Multics Technical Bulletin

                           APPENDIX A

                   CQL STATEMENT DESCRIPTIONS

ALTER TABLE

Assure  that  the  user  has alter  permission  on  the  table by
querying the  DD.  Pass the  CQL down to  the TIM along  with the
current  table description.   Upon a  successful return  from the
TIM,  update the  DD with the  table description  returned by the
TIM.

Some kind of  `locking' may be necessary while  this operation is
going on.  Also, the ripple effect described in DROP TABLE should
be looked at here as well.

Ripples will have consequences on views  which have a SELECT * on
the table being  altered.  The select will turn  into a select of
each column that was previously in the view.

ALTER TABLESPACE

Check to make sure that the user has alter tablespace permission.
Call the file system to  make the necessary quota change.  Update
the quota information in the DD.

The tablespace  operations (create, alter, and  drop) are where a
user's permission  according to the DD  and the actual permission
according to  the file system  may be different.   These are such
low-use operations, as well as such a powerful ones, that this is
probably a good thing.

ASSERT

Check the DD to assure that  the user has alter permission on the
tables.  Call the TIMs to lock  the tables.  Call the TIMs to run
the assertion (how the assertion  is transformed into a selection
expression  as  yet  undetermined).   If  successful,  assign the
assertion to the tables by registering  it with the DD.  Call the
TIMs to unlock the tables.


Multics Technical Bulletin                                MTB 642

COMMENT

Assure that the user has alter  privilege on the table.  Give the
comment to the DD and have it associated with the proper table or
table/column.

COMMIT WORK

Call all TIMs invoked since the  last work was committed and pass
on  the  commit work  order.   There may  be some  DD interaction
necessary here if locking records are kept there.

Given  the  possible  differences  in  transaction  environments,
transaction management could get to be a very complex task.

CREATE INDEX

Check the DD  to make sure that the user  has index privileges on
the table.  Make sure that the  index name does not already exist
in the DD.  Pass the CQL on to  the TIM.  Add the index to the DD
when the TIM returns a good status.

Some table managers may not have  place to `put' an index.  It is
possible  that  something might  want  to be  invented  to handle
REALLY indexing, say,  a lister file.  Of course,  the lister TIM
would  be  responsible  for  keeping  the  index  up-to-date when
modifications occur to the lister  file (assuming that the lister
file was only referenced through the TIM...)

CREATE SYNONYM

Assure that the user can add  synonyms to the DD.  Make sure that
the synonym is not already in the DD and that the table/view/link
name is.  Add the synonym to the DD.

Since there is  not a `central data dictionary',  the concept and
effect   of   synonyms   is   slightly   different   from   other
implementations.  Synonyms should be full-blown names, subject to
rippling, linking, etc.

In order to support the  'test' and 'operational' modes that some
people find useful,  it may be useful to  NOT have synonyms cause
ripples.  In this way, if  ONLY synonyms are referenced, then all
of  the   base  tables  can   change  out  from   underneath  the
applications without difficulty.


MTB 642                                Multics Technical Bulletin

CREATE TABLE

Check the  DD to assure that  the user can add a  table to it and
that  the name  does not  already exist  in the  table namespace.
Take the CQL and call the native  TIM to get the table (as a real
Multics  file   system  object  of  some   sort)  created.   Upon
successful return  from the TIM, the  table description (plus any
data  tacked  on  by  the  TIM)  will  be  appended  to  the data
dictionary.

The creator of the table will  have full privileges on the table.
For anyone else to have  permissions, the GRANT statement must be
used.

There are no plans to support the creation of non-native tables.

CREATE TABLESPACE

Check  the  DD  to  see  if the  user  has  permission  to create
tablespaces.   Call  the file  system and  attempt to  create the
tablespace in the directory specified.   Set the initial quota if
specified (and possible).  Set  appropriate ring brackets and acl
entries.  Tell the DD about the tablespace.

Initially, only  the creator of  the tablespace has  CREATE TABLE
and DROP TABLE permissions (with GRANT) on it.

The  current plan  is that  tablespaces will  be directories with
ring brackets of 2,2 and will have an `sma *.*.*' acl entry.

CREATE TRIGGER

Assure that the trigger name is unique.  Assure that the user has
the appropriate  access on all  of the columns  referenced by the
trigger as well as alter permissions on the tables.  Register the
trigger with the DD.

CREATE VIEW

Access  will  be checked  to assure  that the  user has  at least
select  permission on  every column  selected or  compared in the
view definition.  The user's  permission on each column mentioned
will  be  copied  as  the  user's  permissions  on  the  view.  A
`pointer'  will  be attached  to  each table  so  that permission
changing (or table deletion) can be rippled to the view.  This is
also  how  table  dropping will  be  able  to cause  views  to be
dropped.


Multics Technical Bulletin                                MTB 642

A  view  to  which  the   creator  has  no  `with  grant  access'
permissions on  the built-upon tables  cannot be shared  with any
other users.  This keeps the base tables secure.

DELETE

Check the DD to make sure  the user has delete permissions on the
table.  Run  the selection expression  as necessary and  call the
TIM to delete the appropriate rows.

A delete operation may only affect one table.

DEREGISTER LINK

Check that  the name is a  link and that the  user has deregister
link  permission.   Remove  the  link from  the  DD.   The ripple
effects described for DROP TABLE would occur.

DEREGISTER TABLE

Check  that  the  table  is  registered  and  that  the  user has
deregister  table  permission.   Call the  TIM.   Upon successful
return, remove the registration from  the DD.  The ripple effects
described for DROP TABLE will occur.

DROP INDEX

Using the DD,  locate the index and the  table/column.  Make sure
that the user  has index permissions on the  table.  Call the TIM
to drop the index.  Remove the index from the DD.

DROP SYNONYM

Verify that the  user has permission to drop  synonyms in the DD.
Verify the existence of and remove the synonym from the DD.

Ripple effects here are discussed under CREATE SYNONYM.

DROP TABLE

Validate  that the  user can drop  the table  from the tablespace
(drop table privilege).  Lock the table (to make sure no one else
is using  it).  Call the  TIM to delete  the table from  the file
system.  Upon  successful return from  the TIM, the  DD entry for
the table is removed.


MTB 642                                Multics Technical Bulletin

It has  been suggested that  a user should  be able to  remove an
entry from his DD even if he cannot delete the file system object
with  which it  is associated.   This DEREGISTER  TABLE statement
will do this, but probably will not do it for native files.  This
leads to the `orphaned table'  problem mentioned in the `REGISTER
TABLE' description.  This can be particularly bad if the creation
of non-native tables ever gets supported.

It would be very nice if any views upon which this table is based
would disappear  when the table is  dropped.  Likewise, any links
to the table in any other DD could be removed as well (as well as
any views in that DD that happen to be based on that link).  This
`ripple  effect'  could  cause  table  dropping  to  take  years.
Nonetheless, it is probably a good idea.

DROP TABLESPACE

Check  that the  user has drop  tablespace permission  in the DD.
(Check  that  the  user  has `sma'  permission  on  the directory
containing  the  tablespace.)   Get  the list  of  tables  in the
tablespace  from  the  DD,  then drop  them  all  (with necessary
ripples).   Delete  the  tablespace  from the  file  system, then
inform the DD that it is gone.

DROP TRIGGER

Look up the trigger in the DD.  Make sure that the user has alter
permission  on the  table referenced  by the  trigger.  Remove it
from the DD.

DROP VIEW

Wait for the view  to not be in use (!).  Ask  the DD to drop the
view.   The DD  will check  to make  sure the  user has  the drop
permission.

The same  `ripple effect' as  described for DROP  TABLE will take
place here.

GRANT

Check  to make  sure that the  user has grant  permission for the
permission being  granted.  Call the  data dictionary to  set the
permission.

A data dictionary administrator is  actually able to force access
to any  table or tablespace defined  (read CREATEd or REGISTERed)


Multics Technical Bulletin                                MTB 642

in the data dictionary.  A DDA cannot force access to views which
reference links  to other data  dictionaries, as this  would be a
violation of the security defined by the other data dictionaries.

INSERT

Check permission on the table or view specified and make sure the
user has  insert permission.  If data  values are specified, then
just  pass  the CQL  on to  the  TIM.  If  a select  statement is
specified, run  the select statement  and generate an  insert CQL
for each data row returned.

LOCK

Make sure that the user has any of insert, select, update, delete
privilege on  the table.  Pass the  CQL on to the  TIM and notify
the DD.

REGISTER LINK

Make sure the  user has register_link permission in  the DD.  Ask
the DD to  verify the existence of (and  link permission for) the
table name  in the `source' data  dictionary.  Then, register the
link  in  the DD  with  the name  of  the target  or  the synonym
specified, as  appropriate.  The name  to be registered  must not
already be in the table namespace.

The  table description  will not  be copied  into this  DD.  This
causes  nightmarish consistency  problems.  However,  a `pointer'
must be left in the source DD that this link exists so that table
altering/dropping/permission changing  will be able  to ripple to
the appropriate data dictionaries.

Permissions  on  the  table/view  that  has  been  linked  to are
determined by checking the target of the link.

REGISTER TABLE

Check  the  DD to  make  sure that  the  user has  register table
permission and that the name does  not already exist in the table
namespace.  Determine and invoke  appropriate TIM with CQL.  Upon
successful  return,  add  the  table description  (plus  any data
tacked on by  the TIM) to the data dictionary.   The user will be
given full privileges to the table.

The native TIM will reject REGISTER TABLE statements.  The reason
is  to enforce  the idea that  there is a  single data dictionary
which reflects the description/current access mechanisms/whatever


MTB 642                                Multics Technical Bulletin

of that table.  Deletion or damage  of a DD could cause tables to
be `orphaned'.   Since it is  conceivable that much  of the table
info (such as attribute names/types  and indexes) COULD be stored
only in the  DD, this could cause real  problems.  However, since
FAMIS  relation_manager_ objects  are planned as  the native file
types, this will  not be that much of a  problem.  It is possible
that a  `super administrator' of  some sort may be  able to force
the  registration  of  a  native table.   This  could  get around
`disasters' which might  cause the file system and  the DD to get
out of sync.

Non-native  TIMs will  be responsible for  determining whether or
not the  user should be  able to register the  table in question.
It  has been  proposed that `rw'  access to the  object and `sma'
permissions  on  the  containing  directory  of  the  object  are
appropriate for defining `ownership'.   A TIM support routine may
be provided  to do this  kind of determination.  A  MRDS TIM will
probably ensure  that the user  is a MRDS  database administrator
for  the  database in  question.   This can  prevent a  user from
registering a table and ignoring submodel restrictions.

RESTORE

This operation  will restore a transaction  to a given checkpoint
(made by SAVE).

REVOKE

Check to make sure that the user is either the person who granted
the permission  or is a  dda.  Rippling will occur  such that any
permissions  granted  by  the  person whose  permission  is being
revoked will be revoked.

It may be  necessary at this point to also  go out and drop views
that were created by this person.  This is an area for study.

ROLLBACK WORK

Call the appropriate TIMs to get work rolled back.

Note that not  all TIMs will be able to  support this.  It should
be  determined what  should be  reported to  the user  when a TIM
claims ignorance of the proper procedure.


Multics Technical Bulletin                                MTB 642

SAVE

This  operation  will  `checkpoint'  a  transaction.   Details of
transactions are as yet unspecified, but the TIMs may need to get
into the act.

SELECT

Make  sure  the  user  has   select  permission  on  all  of  the
tables/views specified.  Run the select and return data.

UPDATE

Make  sure the  user has  update permission  on the  column names
specified.   Run  the  select  and call  the  TIM  to  modify the
appropriate row/column values to the appropriate values.

Updating through a view can only occur  if the view is based on a
single  base  table,  none  of   the  columns  in  the  view  are
aggregates,  and  the column  to  be modified  is a  single field
selected from the base table.


MTB 642                                Multics Technical Bulletin

                           APPENDIX B

              CANONICAL QUERY LANGUAGE DESCRIPTION

The Canonical Query Language  (CQL) is an internal representation
of an SQL statement.  In general  it will be generated by parsing
SQL  with  the   convert_sql_to_cql_  subroutine.   However,  any
subroutine that can generate the CQL can be used.

The  CQL is  a set  of operations  that will  be executed  by the
vm_$execute_cql  subroutine.    The  complete  CQL   for  an  SQL
statement is  described by a vm_cql_info  structure, and must all
exist in the same segment because it contains relative offsets to
other parts of  the CQL.  Offsets are necessary  because the same
vm_cql_info structure may be used in different Multics process.

The  sequence  in  which the  operations  are to  be  executed is
established by  a stack.  It  consists of a linked  list of stack
entries.  Each stack entry contains an op_code that specifies the
type and function of the stack entry.  If the function of a stack
entry  is   a  definition,  then  the   operands  constitute  the
definition.   If  the  stack  entry  function  is  an  executable
operation,  the  operands  are  offsets  to  other  operations or
definitions required for the execution.  Essentially, the entries
in the stack  are executed in an interpreted  manner.  Each stack
entry contains a  result pointer that is only  valid at execution
time and usually  points to the results of  the execution of that
operation.  A pointer  is used here instead of  an offset because
the resultant data may exist in a different segment.


Multics Technical Bulletin                                MTB 642

STRUCTURE INFORMATION

The  vm_cql_info structure  is a  based structure  defined in the
vm_cql_info.incl.pl1.

dcl 1 vm_cql_info aligned based (vm_cql_info_ptr),
      2 version char (8),
      2 generator like generator_info,
      2 statement_type fixed bin,
      2 statement_sub_type fixed bin,
      2 associated_info_ptr ptr,
      2 sql_offset fixed bin (18) unsigned,
      2 sql_length fixed bin,
      2 next_avaliable_word_offset fixed bin (18) unsigned,
      2 first_stack_offset fixed bin (18) unsigned,
      2 current_stack_offset fixed bin (18) unsigned,
      2 data_space_size fixed bin,
      2 data_space (vci_data_space_size
                   refer (vm_cql_info .data_space_size)
                   fixed bin (35) aligned,

dcl 1 generator_info based (generator_info_ptr),
       2 name char (32),
       2 version char (8),
       2 date_time_created fixed bin (71),
       2 user,
          3 person_id char (20) unal,
          3 pad_1 char (1) unal,
          3 project_id char (9) unal,
          3 pad_2 char (1) unal,
          3 tag char (1) unal,
       2 option bit (36) unal;

STRUCTURE ELEMENTS

version
     specifies the version of the vm_cql_info structure.

name
     specifies the name of the cql generator program.

version
     specifies  the version  of the generator  that generated the
     CQL.

date_time_created
     specifies the date and time that the CQL was generated.


MTB 642                                Multics Technical Bulletin

person_id
     specifies the  person identifier of the  user that generated
     the CQL.

pad_1
     is unused space in this structure.

project_id
     is  the project  identifier of  the user  that generated the
     CQL.

pad_2
     is unused space in this structure.

tag
     is the instances identifying tag  of the user that generated
     the CQL.

options
     are the generator options used when generating the CQL.

statement_type
     is  the statement  type of  the CQL.   Currently the defined
     statement types are:

          1  query
          2  dml
          3  ddl
          4  control
     Include  file vm_statement_type.incl.pl1  contains the named
     constants for the statement types.

statement_sub_type
     is  the  CQL  statement   subtype.   The  currently  defined
     subtypes are:

          1  create
          2  drop
          3  insert
          4  alter
          5  register
          6  grant
     Include  file  vm_sub_statement_type.incl.pl1  contains  the
     named constants for the sub_statement types.

associated_info_ptr
     is  a pointer  that points  to an  associated structure used
     during CQL generation or execution.  This pointer is invalid
     across Multics process.  It may be null.

sql_offset
     is  an  offset  to a  the  beginning of  a  character string


Multics Technical Bulletin                                MTB 642

     representation of the CQL.  This  character string is in SQL
     text format.

sql_length
     is the length of the SQL character string in characters.

next_avaliable_word_offset
     is  the  offset to  the  next available  unused word  in the
     data_space.

first_stack_offset
     is the offset to the first stack entry in the stack list.

last_stack_offset
     is the offset to the last stack entry in the stack list.

current_stack_offset
     is the offset to the current stack entry in the stack list.

data_space_size
     is the size of the data space in words.

data_space
     is  the space  where the  stack list  and other  CQL related
     information reside.


MTB 642                                Multics Technical Bulletin

STACK ENTRY STRUCTURE

dcl 1 cql_stack_entry aligned based (cql_stack_entry_ptr),
      2 op_code fixed bin (18) unsigned unaligned,
      2 op_modifier fixed bin (18) unsigned unaligned,
      2 previous_offset fixed bin (18) unsigned unaligned,
      2 next_offset fixed bin (18) unsigned unaligned,
      2 result_ptr pointer,
      2 execution_use fixed bin (18) unsigned  unaligned,
      2 number_operands fixed bin unaligned,
      2 operand (0 refer cql_stack_entry.number_operands)
                   fixed bin (18) unsigned unaligned;

STRUCTURE ELEMENTS

op_code
     is  the encoded  operation specifier  for this  stack entry.
     The current list of op_codes are:  TO BE SUPPLIED

op_modifier
     is  a op_code  modifier to  further define  the operation of
     this stack entry.

previous_offset
     is the offset to the previous  stack entry.  If the value is
     zero then this is the first entry in the stack list.

next_offset
     is the offset to the next stack entry.  If the value is zero
     then this is last entry in the stack list.

result_ptr
     is the pointer to the results of this operation.  It is only
     valid during the execution of the CQL.

execution_use
     is used during execution of the CQL.

number_operands
     is the number of operands in this stack entry.

operand
     is  the operand  value.  Generally  it is  an offset  to the
     another  stack  entry  that  is the  contain  the  result or
     definition of a previously executed stack entry.


Multics Technical Bulletin                                MTB 642

                           APPENDIX C

               TABLE INTERFACE MODULE DESCRIPTION

     The  Table  Interface Modules  (TIMs) provide  the interface
between the VMM and a  specific table manager.  A Table Interface
Module must  be written for  each table manager used  by the View
Manager.  The primary function of the  TIM is to execute CQL, for
a specific  table, passed to  it from the  VMM.  The TIM  must be
able to execute any CQL supported  by the View Manager.  If a TIM
underlying  file  manager does  not  provide a  function  that is
support  by  the View  Manager,  then the  TIM must  provide that
function.

All TIMs must be written to support the following entry points.

entry:  Entry:  TIM_$execute_cql

     This entry point is used to execute CQL statements.

USAGE

      dcl TIM_$execute_cql entry options (variable);

      call TIM_$execute_cql (cql_ptr,  vm_info_ptr, needed_arg_1,
            needed_arg_N);

ARGUMENTS

vm_info_ptr
      is  a  pointer  to  the  vm_info  structure  thast contains
      information  about  the current  View  Manager environment.
      (input)

cql_ptr
      is  a  pointer  to   the  cql_definition  structure  to  be
      executed.  (input)

needed_arg_I
      are  a variable  number of  arguments (possibly  none), the
      type will  depend on the requirements  of the cql statement
      being executed.  (input/output)


MTB 642                                Multics Technical Bulletin

entry:  TIM_$open_cursor

     This entry point is used to create and open a cursor for use
by  the TIM_$fetch  entry point.  This  entry point  will be call
from  the  VMM when  the  CQL to  be  executed is  a  select type
statement.  The TIM  will execute the CQL and  upon normal return
have  available the  first set  of returned  values from  the CQL
select  statement.   VMM  will  use  the  TIM_$fetch  to  get the
returned data values.

USAGE

      dcl TIM_$open_cursor entry options (variable);

      call TIM_$open_cursor  (cursor_name,  vm_info_ptr, cql_ptr,
            input_argN);

ARGUMENTS

cursor_name
      is  the name  char (32)  of the cursor  to be  used for the
      open_cursor.  (input)

vm_info_ptr
      is  a  pointer  to  the  vm_info  structure  thast contains
      information  about  the current  View  Manager environment.
      (input)

cql_ptr
      is the  pointer to the  cql_info structure of  a select CQL
      statement.  (input)

input_argN
      is a variable number of  arguments (may be none), depending
      on  the requirements  of the  CQL select  statement.  It is
      determined from the input_arguments  returned from the call
      to TIM_$get_needed_arguments for  the CQL select statement.
      (input).


Multics Technical Bulletin                                MTB 642

entry:  TIM_$fetch

     This  entry  point  is used  to  fetch data  using  a cursor
created by the TIM_$open_cursor entry point.

USAGE

      dcl TIM_$fetch entry options (variable);

      call TIM_$fetch (cursor_name, output_argN);

ARGUMENTS

cursor_name
      is  the name  char (32)  of the cursor  to be  used for the
      fetch.  (input)

output_argN
      is a variable number of arguments (at least one), where the
      data is to be returned to  the caller.  The number and data
      type  are  dependent  on  the  CQL  used  in  the  call  to
      TIM_$open_cursor.  (input)


MTB 642                                Multics Technical Bulletin

entry:  TIM_$close_cursor

     This entry point is used to  close and destroy a cursor that
was created by a call to the TIM_$open_cursor entry point.

USAGE

      dcl TIM_$close_cursor entry (char (32));

      call TIM_$close_cursor (cursor_name);

ARGUMENTS

cursor_name
      is the name of the cursor to be closed.  (input)


Multics Technical Bulletin                                MTB 642

entry:  TIM_$terminate_vm

     This entry  point is used  to terminate the  Table Interface
module.  Its purpose  is to cause an open table  to be closed and
to cleanup temporary space created by the TIM.

USAGE

      dcl TIM_$terminate entry ();

      call TIM_$terminate ();