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 ();