Multics Technical Bulletin MTB 645
To: MTB Distribution
From: Mike Kubicar
Date: 12/20/83
Subject: The View Manager Facility: Data Dictionary Interface
ABSTRACT
This MTB describes the View Manager's interface to the Data
Dictionary. The Data Dictionary Interface presents to View
Manager a set of system tables which describe the data View
Manager is manipulating.
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>Multics>meetings>End_User_Data_Access (euda)
Via electronic mail:
Kubicar on System M
Via telephone:
(HVN) 357-6647 or (602) 862-6647
_________________________________________________________________
Multics Project internal working documentation. Not to be
reproduced outside the Multics Project.
MTB 645 Multics Technical Bulletin
INTRODUCTION
This mtb describes the prototype version of the view manager data
dictionary interface. The view manager is a complete replacement
of the current database management system on Multics. This
document should not be taken as the final word on what this
product will look like in its final form. It is intended that
only an initial cut will be taken at the design. Hopefully, much
will be learned when this initial cut is implemented as the
prototype. A later document will be issued which will define the
final design of the data dictionary interface and the interim
data dictionary. The final design will be used to build a
product in the MR12.0 time frame.
OVERVIEW
Clearly, in order for a database management system to perform its
function, it must have a great deal of knowledge of the data it
is manipulating. In a relational database, the data is
conceptually stored in a number of tables. These tables can be
viewed in the same way that a person might write a table on a
piece of paper. That is, a table would be a number of rows and
columns. This is exactly what a user would see if he were using
a database management system such as the Multics Relational Data
Store. Of course, the data is not stored this way in the
computer. Usually the database management system must reformat
the data to be stored in the computer's file system.
To perform this transformation, the database management system
must keep track of many details which are invisible to the end
user. The DBMS must know the names of all the tables it has at
its disposal as well as where they are physically stored. It
must know what columns are in the table and the way the data is
stored in the columns. This is just the tip of the iceberg. The
DBMS must remember tens of details about the characteristics of
the data it is manipulating.
These characteristics of the data are commonly referred to as
meta-data. Meta-data means data about the data. Every database
has associated with it a large amount of meta-data which the DBMS
uses to figure out how to manipulate the data contained in the
database. In the case of MRDS, this meta-data is stored in a set
of special segments within the database directory. Accessing
this meta-data is done by getting a pointer to the start of the
segments and using this pointer to reference a set of based
structures. In effect, these segments are the MRDS data
dictionary.
This meta-data is usually interesting to people as well as
database management systems. A person is very apt to want to
know what tables are in the database and what the characteristics
Multics Technical Bulletin MTB 645
of those tables are. With MRDS, the user must invoke a special
set of commands to display this meta-data. These commands have a
completely different syntax from the commands he uses to display
data in his database. The meta-data display commands are also
less flexible than the data display commands.
The method used by MRDS is only one way of storing the meta-data
in the database. It is not difficult to see that this meta-data
is just data and can be stored in the database like any other
data. That is, this meta-data can be arranged into a set of
tables. Given this arrangement, the meta-data could be accessed
with the standard data manipulation commands of the DBMS.
Other database management systems have shown that this method of
storing meta-data is popular with database users. They tend to
be more user friendly than systems that store meta-data as does
MRDS.
The view manager product will store its meta-data in this manner.
In addition to all the tables that a user creates, there will be
a set of system tables which will contain all the information
describing all tables in the table name space. View manager will
be able to access and update the tables through the data
dictionary interface (ddi) module. In addition to the
description of every user created table, the data dictionary will
contain descriptions of all system tables. Thus, system tables
can be accessed in the same manner as user tables.
This mtb does not describe the design of a data dictionary. That
product is not planned as part of the view manager end user
facility. Since Multics currently does not have a data
dictionary, a makeshift one will have to be built as part of the
data dictionary interface. One of the assumptions made during
the design of the data dictionary interface is that Multics will
someday have a real data dictionary product. At that time, view
manager would have to start using the real data dictionary.
Thus, the idea of a DDI was formulated. All knowledge about the
actual data dictionary is hidden in the DDI. When the data
dictionary changes, only the DDI will need to be changed. In
fact, during the implementation of the prototype, it is assumed
that the makeshift data dictionary will change several times.
The makeshift data dictionary will not be described by this mtb.
One of the purposes of the prototype is to be able to experiment
with efficient ways of implementing this makeshift data
dictionary. Since the data dictionary will be at the heart of
the view manager, a poorly designed, slow one will result in an
unusable product. Experimentation is required in order to find
out the best method of implementing a data dictionary.
MTB 645 Multics Technical Bulletin
RELATIONSHIP TO VIEW MANAGER
The data dictionary interface is the sole holder of all meta-data
in the data environment. It is anticipated that higher level
software will call the interface frequently during normal
operation. Because there are two ways in which the view manager
will want to access data in the data dictionary, there are two
interfaces to ddi. The first is through the SQL language
interface when a user requests data from the system tables. This
interface makes the system tables look like any other table known
to view manager. The second is when system software (view
manager) wants to request privileged information about a
particular table or update the information in the dictionary
tables themselves. The second interface is necessary as there is
no way to update the tables via SQL statements. Update via SQL
statements is restricted so that ddi can guarantee internal
consistency of the dictionary tables.
The SQL level of interface will be provided by building a Table
Interface Module (TIM) to the data dictionary. This module will
have an interface which is identical to the TIM's of other table
managers. Since the TIM's interface is standard and the data
dictionary contains all information on data dictionary tables,
system tables can be referenced in the same way that non-system
tables are. The TIM for the ddi will support only the select
operation. No modifications can be done through this interface.
The primary interface to the data dictionary will be the
information retrieval and update subroutine requests. This is
the only means of updating the information in the dictionary
tables. The view manager will, through the subroutine interface
to ddi, request that specific actions be taken. It is the
responsibility of ddi to update the tables in the correct manner
to achieve these actions. Note that this has the desirable side
effect of isolating the view manager from the physical layout of
the data dictionary. In theory, view manager could get all
meta-data it requires through the SQL interface to the system
tables. Since getting information about user tables will be done
frequently, entrypoint are provided to get meta-data easily.
This is also more efficient than passing in SQL requests.
The data dictionary interface will provide the following
entrypoints:
add_audit_entry
This entrypoint will add an entry in the audit table. These
entries can be deleted with the delete_audit_trail
entrypoint.
Multics Technical Bulletin MTB 645
add_comment
This entrypoint adds a comment to the comment table. It
will also replace and delete comments as necessary.
add_synonym
This entrypoint adds synonyms to the data environment.
add_table
This entrypoint will add a table or view to the data
dictionary tables. It takes as one of its parameters an
info structure which describes the table or view.
close_dictionary
This entrypoint will close a data dictionary. After it is
called, the data dictionary cannot be referenced. It is
called when the view manager is finished with a given data
dictionary.
create_index
This entrypoint will create an index in a given table. The
user must have correct permissions to do this.
delete_audit_trail
This is the only entrypoint that can delete information from
the audit trail. The deletion is done on by the date time
of the entries.
drop_index
This entrypoint is used to delete a given index. The user
must have correct privileges to do this.
drop_synonym
This entrypoint will delete a synonym from the synonym
table. The data dictionary interface makes sure that the
use has enough privileges to do this.
drop_table
This entry will delete a table from the data dictionary.
The user must have the correct privilege to do this or the
operation will not succeed. Deleting a table automatically
deletes any other information (e.g. views) that depends on
its existence.
get_table_info
This entrypoint will return all information stored on a
table. No access checking is performed (other than by the
hardware). If view manager wants the info, it will get it.
link
This entrypoint will create a link to an external object.
Ddi allows links to any object in a foreign data dictionary.
MTB 645 Multics Technical Bulletin
lock
This entrypoint will lock the dictionary so that no other
process can access it.
modify_table
The information stored on the given table or view is
replaced by the information given in the call.
open_dictionary
This entrypoint initializes a data dictionary for use. It
must be called before any of the other entrypoints.
reset_column_privilege
This entry revokes a privilege on a column to a user. It
will also revoke any privilege granted by that user.
reset_dd_privilege
This entry revokes a privilege on the ddi to a user. It
will also revoke any privilege granted by that user.
reset_table_privilege
This entry revokes a privilege on a table to a user. It
will also revoke any privilege granted by that user.
reset_tablespace_privilege
This entry revokes a privilege on a tablespace to a user.
It will also revoke any privilege granted by that user.
set_column_privilege
This entry grants a privilege on a given column to a user.
set_dd_privilege
This entry grants a privilege on the ddi to a user.
set_table_privilege
This entry grants a privilege on a given table to a user.
set_tablespace_privilege
This entry grants a privilege on a given tablespace to a
user.
unlink
This entrypoint will remove a link. The user must have
enough privilege to remove that link.
unlock
This entrypoint will unlock a locked database. Until a
database is unlocked, it is not available to be used by
other users.
Multics Technical Bulletin MTB 645
RESPONSIBILITIES OF THE DATA DICTIONARY INTERFACE
The data dictionary interface lies at the heart of the view
manager end user facility. It is the sole repository of all
information describing the data the view manager has access to.
Therefore, whenever view manager needs a new piece of information
to perform an operation, it must access the data dictionary to
get that information. To the end user, the meta-data information
will appear to be stored as a set of tables. If a user wishes to
read the information in the meta-data tables, he will be able to
do so using normal SQL statements. There will also be an
interface available to return information to view manager in a
form more directly suited to its needs.
The tables have been designed so that they are easy to query
using SQL. Hopefully, each table is self contained in that a
user need not enter a complicated SQL statement with many joins
to get useful information about his database. To achieve this
end, it was necessary to put a certain amount of redundant
information in the data dictionary tables. They are not in
standard third normal form.
Since the data dictionary tables are the sole source of
information about the contents of the data environment, it is
very important that the information in them be consistent at all
times. For this to be the case, only the data dictionary
interface should be able to modify the tables. Nobody will be
allowed to use SQL statements to modify or insert data into the
data dictionary. Not even the data administrator will have
privileges to do more than read the system tables. There will be
a set of entrypoints into the data dictionary interface which
will allow system software (view manager) to request that a
consistent set of updates be made to the data dictionary tables
by the data dictionary interface. To make sure that the data
dictionary interface is the only one allowed to update dictionary
tables, all dictionary tables and the interface software will run
in an inner ring. There will not be any gates to enter the ddi
from the user ring. Only system software can access the data
dictionary.
Information for all tables in the data environment is recorded in
the data dictionary tables. The data dictionary is self
referencing. That is, all meta-data concerning the data
dictionary tables is stored in the data dictionary. This makes
it possible, using the SQL interface, to access the data
dictionary in a manner identical to that used to access any other
table. The initial set of system tables is created and
initialized when the data dictionary is created. A blank data
dictionary contains only information about the system tables.
The only user registered in a blank dictionary is the user that
created it. He is registered as an administrator. In addition
to the information needed to completely describe the data
MTB 645 Multics Technical Bulletin
environment, each major table in the data dictionary also
contains creation information. This includes the date/time the
information was added as well as the userid of the person adding
the information. This data can be used for auditing purposes.
The following tables are currently defined to be the system
tables of the data dictionary. All data dictionary tables are
prefixed by the word "system" and must end in an underscore.
Users should not create tables with names like this. This list
of tables is incomplete. As the requirements of higher level
software are further refined, the system tables definition will
be updated to meet its needs. They should evolve significantly
as prototype implementation proceeds.
system_audit_
This table contains the data dictionary audit trail. It is
available to higher level software to keep track of
significant events in the data environment.
system_column_security_
This table contains security information for specific
columns. Anyone with any privileges on any specific column
in any table will have an entry in this table. The only
privilege available on a specific column is update
privilege.
system_columns_
This table contains information which defines the
characteristics of a column. There is one entry in it for
each column of each table in the data environment. This
table contains information which is in human readable form.
system_columns_binary_
This is the companion table for system_columns_. It
contains binary data needed by view manager.
system_comment_
This table contains free text which usually is used to
describe tables and columns.
system_links_
This table contains links to tables in other data
dictionaries. A link is a reference to an object in another
data dictionary.
system_synonym_
This table defines all the synonyms available in the data
dictionary. A synonym is an alternate name for a table.
All synonyms in the table are in effect for anyone using the
data dictionary.
Multics Technical Bulletin MTB 645
system_table_security_
This is the security information table. It defines what
privileges users have on the tables in the data environment.
Privileges defined on tables are select, insert, delete,
update, link, null, alter, and index.
system_tables_
This table contains information which defines the
characteristics of a table. There is one entry in it for
each table in the data environment. This table contains
information which is in human readable form.
system_tables_binary_
This is the companion table for system_tables_. It contains
binary data needed by view manager
SECURITY
Another function of the data dictionary interface is to keep
track of all the security information for the data environment.
Entries in data dictionary tables define what operations are
allowed on data contained in the total environment. The system
security tables are system_dictionary_security_,
system_table_security_, system_tablespace_security_ and
system_column_security_. To access anything in the data
environment, a user must have an entry in one of the system
security tables. Note however, that this is true only if there
are no links from other data dictionaries to objects in the
current environment. If an object is linked to, and anyone has
any grant with grant permission, it is no longer possible to
control external access to the data dictionary. Users external
to the dictionary are not required to have "access" privilege on
the dictionary in order to use tables contained in it.
The data dictionary interface does not have control over the
physical security of a table. In can only inform higher level
software (view manager) of the security state of the table. That
is, it will return in the table information the privileges of the
user making the call. In the case of view manager making a
request to grant or revoke privileges, ddi will check to see if
the operation is permitted and abort it if necessary. The rules
data dictionary interface follows to determine this are those
defined by the SQL language.
Data environment privileges fall into one of four categories:
those defined on a particular table, those defined on a specific
column of a table, those which pertain to tablespaces, and those
which are global to the whole environment. The following
privileges are global to the whole environment:
MTB 645 Multics Technical Bulletin
access
The user is allowed access to information contained in the
data dictionary.
administrator
The user is a data environment administrator. This
privilege implies all other privileges on all objects in the
data environment.
create_synonym
The user may add a synonym to the data dictionary system
tables.
create_tablespace
The user is allowed to add new tablespaces to the data
dictionary.
create_view
The user is allowed to add new views to the data dictionary.
Note that he must have appropriate privileges on any tables
or views used in the new view.
deregister_link
The user may remove a link from the data dictionary. He
must be an administrator or the creator of the link.
deregister_table
The user may remove a foreign table from the data
dictionary. He must be an administrator or the person who
registered the table.
drop_synonym
The user may drop any synonym from the data dictionary which
he has created.
drop_tablespace
The user is allowed to drop tablespaces from the data
dictionary. He must be an administrator or creator of the
tablespace he is dropping.
drop_table
The user may drop an existing table. To drop a table a user
has to be an administrator or the creator of the table.
drop_view
The user may drop a view from the data dictionary. In order
to drop a view, the user must be an administrator or the
creator of the view.
register_link
The user may create a link in the data dictionary. Note
Multics Technical Bulletin MTB 645
that he must have appropriate privilege in the foreign data
dictionary to the table he is adding.
register_table
The user may register a foreign table type into the data
dictionary.
null
The user has no privilege whatsoever on the data dictionary.
The following privileges are defined for tables:
select
The user may perform SQL SELECT statements on the table.
insert
The user may insert rows into the table.
delete
The user may delete rows from the table.
update
The user may update columns in the table.
alter
The user may alter tables.
index
The user may create an index on one or more columns in the
table.
link
The user may link to the table from a foreign data
dictionary.
null
The user has no privilege on the table at all.
The following privileges are permitted on specific columns:
update
The user may update the value of this column.
null
The user may not update the value of this column.
The following privileges are permitted on tablespaces:
MTB 645 Multics Technical Bulletin
alter_tablespace
The user is allowed to change the amount of quota allocated
to a tablespace.
create_table
The user is allowed to create tables in the tablespace.
drop_table
The user is allowed to drop tables from the tablespace.
null
The user has no privileges on the tablespace.
The user may be given grant permission on any of the above
privileges except null. This means that in addition to having
the specified privilege, the user may give this privilege to
other with or without grant. If the user ever loses that
privilege, the data dictionary interface will insure that anyone
who was granted the privilege by that user will have their
privilege revoked too. The sole exception to this revoke rule is
in the case where the user loses privilege to something which he
has created. In that case, only he will lose privilege.
Everyone that he has granted privilege to will retain that
privilege. This feature is present so that people can pass the
control of objects to other administrators without deleting all
access to them. For example, if the creator of an important
database should leave the company, revoking his access would
effectively revoke everyone's access to everything in the
database.
When the data dictionary is created, the default access is that
the creator is an administrator. He will have all privileges on
all user tables in the data environment and select privilege on
all the system tables. Non-administrators using the data
environment will have all table privileges on any tables they
created. Other privileges are as defined in the system privilege
tables. An administrator has all privileges on all tables
irregardless of information in the security system table.
DATA DICTIONARY LINKS
One of the main features provided by the data dictionary will be
the ability to link to objects in other data dictionaries. This
capability is one which is often asked for by people who use MRDS
databases. Like a Multics file system link, a ddi link is an
entry which describes where the physical object can be found.
Ddi links however, strive to maintain complete consistency in the
linked data dictionaries. With a Multics file system link, the
link can point to something which no longer exists or the user no
longer has any acls for. The ddi will guarantee that the link
Multics Technical Bulletin MTB 645
will always reflect the current state of the linked-to object.
This may mean that, if a table is deleted or privileges changed,
that a link in a foreign data dictionary may be deleted or that
privileges in a foreign data dictionary will be updated.
The data dictionary software will implement this linking facility
by keeping a record of external data dictionaries that have
linked to objects in the current one. That is, if data
dictionary A has a link to an object in data dictionary B, then
data dictionary B will have a entry that states that data
dictionary A has linked to it. When an operation is performed on
the object in data dictionary B, ddi will chase backward through
these backward links in order to update information in the linked
dictionaries. It will do so in such a way as to guarantee
consistency among all data dictionaries involved. It will chase
links as far as necessary. Circular links will not be possible.
A circular link is where a link references only other links.
One implication of this feature is that, if there are a large
number of links, any operation on a data dictionary may affect
many data dictionaries. Another is that the physical data
dictionary may be referenced by any Multics user. The physical
Multics acl on the segments which are the data dictionary must be
rw *.*.*. Of course, they will be protect by nature of running
in an inner ring.
The linking feature in effect allows users to connect their
individual data dictionaries together to form a larger, central
data dictionary. If all the data dictionaries on a system were
linked to other data dictionaries, the effect would be identical
to having a single, central, system-wide data dictionary.
Naturally, the choice is left up to the user. In a manner of
speaking, ddi will have to do distributed management of data
dictionaries as they can reside anywhere in the Multics file
system.
MTB 645 Multics Technical Bulletin
Appendix A
This appendix contains all the entrypoint defined in the data
dictionary interface. This does not include the SQL interface to
the system tables. This interface is a standard TIM (Table
Interface Module) which is described in the view manager mtb.
Multics Technical Bulletin MTB 645
Entry: ddi_$add_audit_entry
This entrypoint will add an entry into the system log table.
This table contains a record of events which higher level
software believes is significant. Most of the parameters are
free form text and can be defined by higher level software.
USAGE:
declare ddi_$add_audit_entry (char (32), char (*), char (*), char
(*), char (*), fixed bin (35), char (*));
call ddi_$add_audit_entry (dd_id, object_type, object_name,
operation, comment_text, code, err_msg);
ARGUMENTS
dd_id
The id of the data dictionary to be used. (Input)
object_type
Free form text field describing the type of the object being
manipulated. (Input) This will probably some standard
object that is managed by view manager (e.g. column, table,
index, etc.). Only the first 32 characters of the string
will be stored in the data dictionary.
object_name
The particular instance of the object being logged. (Input)
Only the first 32 characters of the string will be stored in
the data dictionary.
operation
This is the operation that has just been formed. (Input) It
will likely be something like create_index, open_dd,
grant_privilege, etc. Only the first 32 characters of the
string will be stored in the data dictionary.
comment_text
Any arbitrary string of text which further describes the
operation. (Input) Only the first 500 characters of the
string will be stored.
code
Standard error code. (Output)
err_msg
Additional information if error. (Output)
MTB 645 Multics Technical Bulletin
Entry: ddi_$add_comment
This entrypoint will add a comment to a table or column. If a
comment already exists for that table or column, the new comment
will replace the old. A blank comment will delete the comment
entry for the table or column. If the comment string exceed 500
characters, only the first 500 will be stored.
USAGE
declare ddi_$add_comment entry (char (32), char (*), char (*),
char (*), char (10), fixed bin (35), char (*));
call ddi_$add_comment (dd_id, table_name, column_name, comment,
version, code, err_msg);
ARGUMENTS
dd_id
The identifier of the data dictionary to use. (Input)
table_name
The table the comment will be applied to. (Input)
column_name
The column in the table which th comment applies to.
(Input). If blank, the comment is for the table itself.
comment
The comment. (Input). Only the first 500 characters of it
will be stored.
version
The version number of the comment. (Input)
code
Standard error code. (Output)
err_msg
Additional information if error. (Output)
Multics Technical Bulletin MTB 645
Entry: ddi_$add_synonym
This entry will add a synonym to the data dictionary. The user
must have add_synonym privilege. Synonyms must be unique within
a data dictionary.
USAGE
declare ddi_$add_synonym entry (char (32), char (*), char (*),
fixed bin (35), char (*));
call ddi_$add_synonym (dd_id, table_name, synonym_name, code,
err_msg);
ARGUMENTS
dd_id
The identifier of the data dictionary to be used. (Input)
table_name
The name of the table to be synonymed. (Input)
synonym_name
The synonym for that table. (Input)
code
Standard error code. (Output)
err_msg
Additional information if error. (Output)
MTB 645 Multics Technical Bulletin
Entry: ddi_$add_table
This entrypoint adds a table to the data dictionary. A call to
this entrypoint will fail if the user does not have enough
privilege to add a table to the data environment.
USAGE
declare ddi_$add_table (char (*), ptr, fixed bin (35), char (*));
call ddi_$add_table (table_name, table_info_ptr, code, err_msg);
ARGUMENTS
table_name
The table to add to the data dictionary. It must be unique
in the data environment.
table_info_ptr
Pointer to the table info structure describing the table.
See ddi_$get_table_info for the structure definition
code
Standard error code.
err_msg
Additional information if error.
Multics Technical Bulletin MTB 645
Entry: ddi_$close_dictionary
This entrypoint will close the data dictionary, releasing all
temporary structures needed by the ddi. Once the data dictionary
is closed, no further references to it can be made.
USAGE
declare ddi_$close_dictionary (char (32), fixed bin (35), char
(*));
call ddi_$close_dictionary (dd_id, code, err_msg);
ARGUMENTS
dd_id
The identifier of the data dictionary to user. (Input) This
must identify a data dictionary which has previously been
opened.
code
Standard error code. (Output)
err_msg
Additional information if error. (Output)
MTB 645 Multics Technical Bulletin
Entry: ddi_$create_index
This entrypoint will create an index using the given columns.
USAGE: declare ddi_$create_index entry (char (32), ptr, fixed
bin (35), char (*));
call ddi_$create_index (dd_id, create_index_info_ptr, code,
err_msg);
ARGUMENTS
dd_id
The identifier of the data dictionary to use. (Input)
create_index_info_ptr
Pointer to the structure defining the index to be created.
(Input). The create index structure look like this:
1 create_index_info based (create_index_info_ptr),
2 version char (8),
2 index_name char (32),
2 table char (32),
2 number_of_columns fixed bin (35),
2 columns (0 refer
create_index_info.number_of_columns) char (32);
version
The version number of the structure.
index_name
The name of the index to be created.
table
The table the index is to be created on.
number_of_columns
The number of columns in the index.
columns
An array containing the names of the columns making up
the index.
code
Standard error code. (Ouput)
err_msg
Additional information if error. (Output)
Multics Technical Bulletin MTB 645
Entry: ddi_$delete_audit_trail
This entrypoint is used to delete entries from the system audit
trail table. Currently, the only way to delete audit trail
entries is by date-time. All audit entries that were enter on
that date-time or before are removed from the audit table. This
entrypoint is the only way to remove audit trail entries when the
audit table becomes too large. It is anticipated that it will be
used infrequently.
USAGE
declare ddi_$delete_audit_trail (char (32), char (8), char (10),
fixed bin (35), char (*));
call ddi_$delete_audit_trail (dd_id, date, time, code, err_msg);
ARGUMENTS
dd_id
The identifier of the data dictionary to be used. (Input)
date
The date before which entries are to be deleted. (Input).
The date must be a character string in the form "MM/DD/YY".
time
The time before which entries are to be deleted. (Input).
The time must be a character string in the form "HH:MM:SS.T"
code
Standard error code. (Output)
err_msg
Additional information if error. (Output)
MTB 645 Multics Technical Bulletin
Entry: ddi_$drop_index
This entrypoint is used to remove an index from the data
dictionary. The user must have index permission on the table and
the entry must exist in the data dictionary.
USAGE
declare ddi_$drop_index (char (32), char (32), fixed bin (35),
char (*));
call ddi_$drop_index (dd_id, index_name, code, err_msg);
ARGUMENTS
dd_id
The identifier of the data dictionary to use. (Input)
index_name
The name of the index to be dropped. (Input)
code
Standard error code. (Output)
err_msg
Addition information if error. (Output)
Multics Technical Bulletin MTB 645
Entry: ddi_$drop_synonym
This entrypoint removes a synonym from the data dictionary. The
synonym must exist and the user must have the drop synonym
privilege.
USAGE
declare ddi_$drop_synonym (char (32), char (*), fixed bin (35),
char (*));
call ddi_$drop_synonym (dd_id, synonym_name, code, err_msg);
ARGUMENTS
dd_id
The identifier of the data dictionary to use. (Input)
synonym_name
The synonym to drop. (Input)
code
Standard error code. (Output)
err_msg
Additional information if error. (Output)
MTB 645 Multics Technical Bulletin
Entry: ddi_$drop_table
This entrypoint will delete a table from the data dictionary.
The user must have enough privilege to drop the named table.
USAGE declare ddi_$drop_table (char (*), fixed bin (35), char
(*));
call ddi_$drop_table (table_name, code, err_msg);
ARGUMENTS
table_name
The table to be deleted.
code
Standard error code.
err_msg
Additional information if error. (Output).
Multics Technical Bulletin MTB 645
Entry: ddi_$get_table_info
This entrypoint will return information associated with a
particular table.
USAGE
declare ddi_$get_table_info entry (char (32), char (*), ptr,
fixed bin (35), char (*));
call ddi_$get_table_info (dd_id, table_name, table_info_ptr,
code, err_msg);
ARGUMENTS
dd_id
The id of the data dictionary to be used. (Input)
table_name
The name of the table for which information is desired.
(Input)
table_info_ptr
Pointer to the table info structure. (Input). The data
returned depends on whether the table is a base table or a
view. See below for structure definition.
code
Standard error code. (Output)
err_msg
Additional information if error. (Output)
If the object being looked up is a table, the following structure
is returned:
dcl 1 vm_table_desc aligned,
2 version char (8),
2 type fixed bin unaligned,
2 mbz bit (18) unaligned,
2 dd_path char (168) unaligned,
2 unique_table_id char (15),
2 permissions,
3 select bit (1) unaligned,
3 insert bit (1) unaligned,
3 delete bit (1) unaligned,
3 update bit (1) unaligned,
3 alter bit (1) unaligned,
MTB 645 Multics Technical Bulletin
3 index bit (1) unaligned,
3 null bit (1) unaligned,
3 unused bit (30) unaligned,
2 table_path char (168) unaligned,
2 table_man_name char (32) unaligned,
2 reference_name char (32) unaligned,
2 name char (32) unaligned,
2 number_columns fixed bin (17) unaligned,
2 column_info (vtd_number_of_columns refer
(vm_table_desc.number_columns)) aligned,
3 c_name char (32) unaligned,
3 c_descriptor bit (36) aligned,
3 null_values_sw bit (1) unaligned,
3 c_permissions,
4 update bit (1) unaligned,
3 mbz bit (34) unaligned;
Where the fields in the structure are defined as follows:
version
Version number of the structure.
type
The type of the structure. Possible values are 1 for a
table and 2 for a view.
dd_path
The pathname of the data dictionary containing the table.
unique_table_id
Unique table identifier used to determine if the table info
has been modified since cql was generated using this table.
permissions
The permissions the user has to the table. "1"b means that
the user has the privilege. "0"b means that the user does
not have the privilege.
table_path
The absolute pathname where the table resides.
table_man_name
Name of the table manager for this table.
reference_name
Reference name for table.
name
The actual name of the table.
Multics Technical Bulletin MTB 645
number_columns
The number of columns in the table.
c_name
The name of a table column.
c_descriptor
The Multics descriptor of the column's data type.
null_values_sw
On if null values are allowed for the column.
c_permissions.update
On if update privilege is allowed on the column.
If the object is a view, the following structure is returned:
dcl 1 vm_view_desc aligned,
2 version char (8), /* Current version */
2 type fixed bin unaligned, /* 2 = view */
2 mbz bit (18) unaligned, /* Unused */
2 dd_path char (168) unaligned, /* Dictionary path */
2 unique_view_id char (15), /* Unique view identifier used
to
2 permissions, /* ON = Permission allowed
3 select bit (1) unaligned,
3 insert bit (1) unaligned,
3 delete bit (1) unaligned,
3 update bit (1) unaligned,
3 alter bit (1) unaligned,
3 index bit (1) unaligned,
3 null bit (1) unaligned,
3 unused bit (30) unaligned,
2 number_of_columns fixed bin,
2 column_info (vvd_number_of_columns refer
(vm_view_desc.number_columns)) aligned,
3 view_name char (32) unaligned,
3 base_column_name char (32) unaligned,
3 base_name char (32) unaligned,
3 c_permissions,
4 update bit (1) unaligned,
4 pad bit (35) unaligned;
2 select_cql aligned,
3 cql_length fixed bin (35) aligned,
3 cql_data (vvd_cql_length refer
(vm_view_desc.select_cql.cql_length) fixed bin (35));
Where the fields are defined as follows:
MTB 645 Multics Technical Bulletin
version
Version number of the structure.
type
The type of the structure. Possible values are 1 for a
table and 2 for a view.
dd_path
The pathname of the data dictionary containing the view.
unique_view_id
Unique view identifier used to determine if the table info
has been modified since cql was generated using this view.
permissions
the permissions the user has to the view. "1"b means that
the user has the privilege. "0"b means that the user does
not have the privilege.
number_of_columns
The number of columns in the view.
view_name
Name of the column in the view.
base_column_name
Name of the column in the base table or view.
base_name
Name of the base table or view.
c_permissions.update
If on, the user has update permission on the column.
cql_length
The length of the select cql in words.
cql_data
Cql which defines the view.
Multics Technical Bulletin MTB 645
Entry: ddi_$link
This entrypoint is used to link to a object in a foreign data
dictionary. The ddi will check all access on the foreign object
and will not link to it unless the user has proper privileges on
the object and the data dictionary. Any object in the foreign
data dictionary's table namespace may be linked to. A link does
not create an entry for the object in the data dictionary but
merely a pointer to the definition of the foreign object. In
addition to privileges to access the foreign object, the user
must have "link" privilege on the object.
USAGE
declare ddi_$link entry (char (32), char (32), char (*), char
(32), fixed bin (35), char (*));
call ddi_$link (dd_id, link_name, foreign_dd, object_name, code,
err_msg);
ARGUMENTS
dd_id
The identifier of the data dictionary to be used. (Input)
link_name
The link name to be entered in the current data dictionary.
(Input). This name must be unique within the data
dictionary's table namespace.
foreign_dd
The Multics pathname of the foreign data dictionary.
(Input). This is the dictionary which contains the object
being linked to.
object_name
The object in the foreign data dictionary being linked to.
(Input)
code
Standard error code. (Output)
err_msg
Additional information if error. (Output)
MTB 645 Multics Technical Bulletin
Entry: ddi_$lock
This entrypoint will lock the data dictionary so that it cannot
be read or written by other users. Until the dictionary is
unlocked by the user, it will be unavailable. If the data
dictionary is already locked by another user, the entrypoint will
wait lock_wait_time milliseconds before giving up the attempt.
If lock_wait_time is -1, the entrypoint will wait forever if
necessary. If the dictionary is already locked by the user, the
dictionary will remain locked and a non-zero error code will be
returned. If the dictionary is locked by a dead process, the
dictionary will be lock by the user and a non-zero error code
returned.
USAGE
declare ddi_$lock (char (32), fixed bin (35), fixed bin (35),
char (*));
call ddi_$lock (dd_id, lock_wait_time, code, err_msg);
ARGUMENTS
dd_id
The identifier of the data dictionary to use. (Input)
lock_wait_time
The amount of time to wait before the locking operation is
considered to have failed. (Input). Until this amount of
time has passed, the locking operation will wait for the
data dictionary to become unlocked by other processes.
code
Standard error code. (Output)
err_msg
Additional information if error. (Output)
Multics Technical Bulletin MTB 645
Entry: ddi_$modify_table
This entrypoint will modify an existing table definition in the
data dictionary. It will replace the current data with that
contained in the info structure. The user must have enough
privilege to modify the table.
USAGE
declare ddi_$modify_table (char (*), ptr, fixed bin (35), char
(*));
call ddi_$modify_table (table_name, table_info_ptr, code,
err_msg);
ARGUMENTS
table_name
The name of the table to be modified.
table_info_ptr
Pointer to the table information structure. See
ddi_$get_table_info for the structure definition.
code
Standard error code.
err_msg
Additional information if error.
MTB 645 Multics Technical Bulletin
Entry: ddi_$open_dictionary
This entrypoint must be called before any operations are
performed on a data dictionary. The user must have access
permission on the data dictionary in order to open it. This
entrypoint will ready the data dictionary for future use by the
user's process.
USAGE
declare ddi_$open_dictionary entry (char (*), char (32), fixed
bin (35), char (*));
call ddi_$open_dictionary (dd_pathname, dd_id, code, err_msg);
ARGUMENTS
dd_pathname
The Multics pathname of the data dictionary. (Input). The
pathname must describe a valid data dictionary.
dd_id
The identifier that will be used in all future references to
the data dictionary. (Input/Output). It may be any
sequence of ascii characters. It must be unique in the
sense that there must be no other data dictionaries open in
the process with that name. If dd_id is blank, ddi_ will
generate a unique name and return it to the user.
code
Standard error code. (Output)
err_msg
Additional information if error. (Output)
Multics Technical Bulletin MTB 645
Entry: ddi_$reset_column_privilege
This entrypoint will revoke update privilege to a specified user
on a column. The user calling this entrypoint must have enough
privilege to grant update on the column. If the user had grant
with grant permission, any other user who he granted the
permission to will also have the permission revoked.
USAGE
declare ddi_$reset_column_privilege (char (32), char (32), char
(32), char (32), fixed bin (35), char (*));
call ddi_$reset_column_privilege (dd_id, table_name, column_name,
user_name, code, err_msg);
ARGUMENTS
dd_id
The identifier of the data dictionary to use. (Input)
table_name
The name of the table which contains the column. (Input).
This table must be within the table name space of the data
dictionary.
column_name
The column to which privilege is being revoked. (Input).
This must be a valid column within "table_name".
user_name
The user having "update" privilege revoked. (Input). The
name must be a valid Multics user-id of the form
person.project.tag. Starnames are permitted.
code
Standard error code. (Output)
err_msg
Additional information if error. (Output)
MTB 645 Multics Technical Bulletin
Entry: ddi_$reset_dd_privilege
This entrypoint will revoke privileges to a specified user on the
data dictionary. The user calling this entrypoint must have
enough privilege to grant the requested privileges. If the user
had grant with grant privilege, any other user he granted
privilege to will also have it revoked.
USAGE
declare ddi_$reset_dd_privilege (char (32), char (32), bit (36)
aligned, fixed bin (35), char (*));
call ddi_$reset_dd_privilege (dd_id, user_name, privileges, code,
err_msg);
ARGUMENTS
dd_id
The identifier of the data dictionary to use. (Input)
user_name
The user having the privileges revoked. (Input). The name
must be a valid Multics user-id of the form
person.project.tag. Starnames are permitted.
privileges
The privileges to be revoked. (Input). See the "Notes"
section below.
code
Standard error code. (Output)
err_msg
Additional information if error. (Output)
NOTES
The bits in the privileges bit string mean the following:
dcl 1 privileges aligned based,
2 access bit (1) unaligned,
2 administrator bit (1) unaligned,
2 create_synonym bit (1) unaligned,
2 create_tablespace bit (1) unaligned,
2 create_view bit (1) unaligned,
2 deregister_link bit (1) unaligned,
2 deregister_table bit (1) unaligned,
Multics Technical Bulletin MTB 645
2 drop_synonym bit (1) unaligned,
2 drop_tablespace bit (1) unaligned,
2 drop_view bit (1) unaligned,
2 register_link bit (1) unaligned,
2 register_table bit (1) unaligned,
2 null bit (1) unaligned,
2 mbz bit (23) unaligned;
STRUCTURE ELEMENTS
The structure elements correspond to privileges. If the bit is
on, the privilege is being revoked.
access
The user may access the data dictionary.
administrator
The user is a data dictionary administrator.
create_synonym
The user may create a synonym in the data dictionary.
create_tablespace
The user may create a new tablespace in the data dictionary.
create_view
The user may create a view in the data dictionary.
deregister_link
The user may remove a link from the data dictionary.
deregister_table
The user may remove the registration of a foreign table from
the data dictionary.
drop_synonym
The user may drop a synonym from the data dictionary.
drop_tablespace
The user may drop a tablespace from the data dictionary.
drop_view
The user may drop a view from the data dictionary.
register_link
The user may create a link to another data dictionary.
register_table
The user may register a foreign table into the data
dictionary.
MTB 645 Multics Technical Bulletin
null
The user has no permissions to the data dictionary.
Multics Technical Bulletin MTB 645
Entry: ddi_$reset_table_privilege
This entrypoint will revoke privileges to a specified user on a
table in the data dictionary. The user calling this entrypoint
must have enough privilege to revoke the requested privileges.
If the user had grant with grant privilege, any other granted the
privilege by them will also have it revoked.
USAGE
declare ddi_$reset_table_privilege (char (32), char (32), char
(32), bit (36) aligned, fixed bin (35), char (*));
call ddi_$reset_tablespace_privilege (dd_id, table_name,
user_name, privileges, code, err_msg);
ARGUMENTS
dd_id
The identifier of the data dictionary to use. (Input)
table_name
The table to which the privileges are being revoked.
(Input)
user_name
The user having the privileges revoked. (Input). The name
must be a valid Multics user-id of the form
person.project.tag. Starnames are permitted.
privileges
The privileges to be revoked. (Input). See the "Notes"
section below.
code
Standard error code. (Output)
err_msg
Additional information if error. (Output)
NOTES
The bits in the privileges bit string mean the following:
dcl 1 privileges aligned based,
2 select bit (1) unaligned,
2 alter bit (1) unaligned,
2 delete bit (1) unaligned,
MTB 645 Multics Technical Bulletin
2 index bit (1) unaligned,
2 insert bit (1) unaligned,
2 update bit (1) unaligned,
2 null bit (1) unaligned,
2 mbz bit (32) unaligned;
STRUCTURE ELEMENTS
The structure elements correspond to privileges. If the bit is
on, the privilege is revoked.
select
The user is allowed to select rows from the table.
alter
The user is allowed to alter the characteristics of the
table.
delete
The user is allowed to delete rows from the table.
index
The user is allowed to add indices to the table.
insert
The user is allowed to add new rows to the table.
update
The user is allowed to modify columns in the table.
null
The user has no permissions to the tablespace.
Multics Technical Bulletin MTB 645
Entry: ddi_$reset_tablespace_privilege
This entrypoint will revoke privileges to a specified user on a
tablespace in the data dictionary. The user calling this
entrypoint must have enough privilege to revoke the requested
privileges. If the user had grant with grant privilege, any
other user he granted the privilege to will also have it revoked.
USAGE
declare ddi_$reset_tablespace_privilege (char (32), char (32),
char (32), bit (36) aligned, fixed bin (35), char (*));
call ddi_$reset_tablespace_privilege (dd_id, tablespace_name,
user_name, privileges, code, err_msg);
ARGUMENTS
dd_id
The identifier of the data dictionary to use. (Input)
tablespace_name
The tablespace to which the privileges are being revoked.
(Input)
user_name
The user having the privileges revoked. (Input). The name
must be a valid Multics user-id of the form
person.project.tag. Starnames are permitted.
privileges
The privileges to be revoked. (Input). See the "Notes"
section below.
code
Standard error code. (Output)
err_msg
Additional information if error. (Output)
NOTES
The bits in the privileges bit string mean the following:
dcl 1 privileges aligned based,
2 alter_tablespace bit (1) unaligned,
2 create_table bit (1) unaligned,
2 drop_table bit (1) unaligned,
MTB 645 Multics Technical Bulletin
2 null bit (1) unaligned,
2 mbz bit (32) unaligned;
STRUCTURE ELEMENTS
The structure elements correspond to privileges. If the bit is
on, the privilege is revoked.
alter_tablespace
The user may change the quota allowed in the tablespace.
create_table
The user may create tables in the tablespace.
drop_table
The user may drop tables in the tablespace. They must also
have correct privilege on the table they wish to drop.
null
The user has no permissions to the tablespace.
Multics Technical Bulletin MTB 645
Entry: ddi_$set_column_privilege
This entrypoint will grant update privilege to a specified user
on a column. The user calling this entrypoint must have enough
privilege to grant update on the column.
USAGE
declare ddi_$set_column_privilege (char (32), char (32), char
(32), char (32), bit (1), fixed bin (35), char (*));
call ddi_$set_column_privilege (dd_id, table_name, column_name,
user_name, with_grant, code, err_msg);
ARGUMENTS
dd_id
The identifier of the data dictionary to use. (Input)
table_name
The name of the table which contains the column. (Input).
This table must be within the table name space of the data
dictionary.
column_name
The column to which privilege is being granted. (Input).
This must be a valid column within "table_name".
user_name
The user being granted "update" privilege. (Input). The
name must be a valid Multics user-id of the form
person.project.tag. Starnames are permitted.
with_grant
If "1"b, the user is allowed to grant update privilege on
the column to others. (Input)
code
Standard error code. (Output)
err_msg
Additional information if error. (Output)
MTB 645 Multics Technical Bulletin
Entry: ddi_$set_dd_privilege
This entrypoint will grant privileges to a specified user on the
data dictionary. The user calling this entrypoint must have
enough privilege to grant the requested privileges.
USAGE
declare ddi_$set_dd_privilege (char (32), char (32), bit (36)
aligned, bit (1), fixed bin (35), char (*));
call ddi_$set_dd_privilege (dd_id, user_name, privileges,
with_grant, code, err_msg);
ARGUMENTS
dd_id
The identifier of the data dictionary to use. (Input)
user_name
The user being granted the privileges. (Input). The name
must be a valid Multics user-id of the form
person.project.tag. Starnames are permitted.
privileges
The privileges to be granted to user_name. (Input). See
the "Notes" section below.
with_grant
If "1"b, the user is allowed to grant the privileges to
others. (Input)
code
Standard error code. (Output)
err_msg
Additional information if error. (Output)
NOTES
The bits in the privileges bit string mean the following:
dcl 1 privileges aligned based,
2 access bit (1) unaligned,
2 administrator bit (1) unaligned,
2 create_synonym bit (1) unaligned,
2 create_tablespace bit (1) unaligned,
2 create_view bit (1) unaligned,
Multics Technical Bulletin MTB 645
2 deregister_link bit (1) unaligned,
2 deregister_table bit (1) unaligned,
2 drop_synonym bit (1) unaligned,
2 drop_tablespace bit (1) unaligned,
2 drop_view bit (1) unaligned,
2 register_link bit (1) unaligned,
2 register_table bit (1) unaligned,
2 null bit (1) unaligned,
2 mbz bit (23) unaligned;
STRUCTURE ELEMENTS
The structure elements correspond to privileges. If the bit is
on, the user is granting that privilege.
access
The user may access the data dictionary.
administrator
The user is a data dictionary administrator.
create_synonym
The user may create a synonym in the data dictionary.
create_tablespace
The user may create a new tablespace in the data dictionary.
create_view
The user may create a view in the data dictionary.
deregister_link
The user may remove a link from the data dictionary.
deregister_table
The user may remove the registration of a foreign table from
the data dictionary.
drop_synonym
The user may drop a synonym from the data dictionary.
drop_tablespace
The user may drop a tablespace from the data dictionary.
drop_view
The user may drop a view from the data dictionary.
register_link
The user may create a link to another data dictionary.
MTB 645 Multics Technical Bulletin
register_table
The user may register a foreign table into the data
dictionary.
null
The user has no permissions to the data dictionary.
Multics Technical Bulletin MTB 645
Entry: ddi_$set_table_privilege
This entrypoint will grant privileges to a specified user on a
table in the data dictionary. The user calling this entrypoint
must have enough privilege to grant the requested privileges.
USAGE
declare ddi_$set_table_privilege (char (32), char (32), char
(32), bit (36) aligned, bit (1), fixed bin (35), char (*));
call ddi_$set_tablespace_privilege (dd_id, table_name, user_name,
privileges, with_grant, code, err_msg);
ARGUMENTS
dd_id
The identifier of the data dictionary to use. (Input)
table_name
The table to which the privileges are being granted.
(Input)
user_name
The user being granted the privileges. (Input). The name
must be a valid Multics user-id of the form
person.project.tag. Starnames are permitted.
privileges
The privileges to be granted to user_name. (Input). See
the "Notes" section below.
with_grant
If "1"b, the user is allowed to grant the privileges to
others. (Input)
code
Standard error code. (Output)
err_msg
Additional information if error. (Output)
NOTES
The bits in the privileges bit string mean the following:
dcl 1 privileges aligned based,
2 select bit (1) unaligned,
MTB 645 Multics Technical Bulletin
2 alter bit (1) unaligned,
2 delete bit (1) unaligned,
2 index bit (1) unaligned,
2 insert bit (1) unaligned,
2 update bit (1) unaligned,
2 null bit (1) unaligned,
2 mbz bit (32) unaligned;
STRUCTURE ELEMENTS
The structure elements correspond to privileges. If the bit is
on, the user is granting that privilege.
select
The user is allowed to select rows from the table.
alter
The user is allowed to alter the characteristics of the
table.
delete
The user is allowed to delete rows from the table.
index
The user is allowed to add indices to the table.
insert
The user is allowed to add new rows to the table.
update
The user is allowed to modify columns in the table.
null
The user has no permissions to the tablespace.
Multics Technical Bulletin MTB 645
Entry: ddi_$set_tablespace_privilege
This entrypoint will grant privileges to a specified user on a
tablespace in the data dictionary. The user calling this
entrypoint must have enough privilege to grant the requested
privileges.
USAGE
declare ddi_$set_tablespace_privilege (char (32), char (32), char
(32), bit (36) aligned, bit (1), fixed bin (35), char (*));
call ddi_$set_tablespace_privilege (dd_id, tablespace_name,
user_name, privileges, with_grant, code, err_msg);
ARGUMENTS
dd_id
The identifier of the data dictionary to use. (Input)
tablespace_name
The tablespace to which the privileges are being granted.
(Input)
user_name
The user being granted the privileges. (Input). The name
must be a valid Multics user-id of the form
person.project.tag. Starnames are permitted.
privileges
The privileges to be granted to user_name. (Input). See
the "Notes" section below.
with_grant
If "1"b, the user is allowed to grant the privileges to
others. (Input)
code
Standard error code. (Output)
err_msg
Additional information if error. (Output)
NOTES
The bits in the privileges bit string mean the following:
MTB 645 Multics Technical Bulletin
dcl 1 privileges aligned based,
2 alter_tablespace bit (1) unaligned,
2 create_table bit (1) unaligned,
2 drop_table bit (1) unaligned,
2 null bit (1) unaligned,
2 mbz bit (32) unaligned;
STRUCTURE ELEMENTS
The structure elements correspond to privileges. If the bit is
on, the user is granting that privilege.
alter_tablespace
The user may change the quota allowed in the tablespace.
create_table
The user may create tables in the tablespace.
drop_table
The user may drop tables in the tablespace. They must also
have correct privilege on the table they wish to drop.
null
The user has no permissions to the tablespace.
Multics Technical Bulletin MTB 645
Entry: ddi_$unlink
This entrypoint will remove a link from the data dictionary. The
entrypoint cannot be used to drop objects, it only works on
links. To use this entrypoint the user must have
"deregister_link" privilege on the data dictionary. Note that
anything in any data dictionary that uses the link will also be
removed.
USAGE
declare ddi_$unlink entry (char (32), char (32), fixed bin (35),
char (*));
call ddi_$unlink (dd_id, link_name, code, err_msg);
ARGUMENTS
dd_id
The identifier of the data dictionary to use. (Input)
link_name
The name of the link to be removed. (Input)
code
Standard error code. (Output)
err_msg
Additional information if error. (Output)
MTB 645 Multics Technical Bulletin
Entry: ddi_$unlock
This entrypoint is used to unlock a previously locked data
dictionary. Once a data dictionary is unlocked, it is available
for use by other users. If this entrypoint is called on a data
dictionary that is already unlocked, the dictionary will remain
unlocked and an error code returned.
USAGE
declare ddi_$unlock (char (32), fixed bin (35), char (*));
call ddi_$unlock (dd_id, code, err_msg);
ARGUMENTS
dd_id
The identifier of the data dictionary to use. (Input)
code
Standard error code. (Output)
err_msg
Additional information if error. (Output)
Multics Technical Bulletin MTB 645
Appendix B
This appendix describes the system tables available in the data
dictionary. The implementation of these tables will most likely
be done with some form of relational data manager. The
descriptions presented here will be the actual definitions of the
tables. That is, they might map directly into a relation
definition in a cmdb source segment.
MTB 645 Multics Technical Bulletin
Table: Audit trail table
Name: system_audit_
This table contains an audit trail of actions performed by the
view manager software. It is free form in the sense that view
manager can insert an entry any time that it feels a significant
event has occurred. Access to this table should only be done
through system software. This table may be viewed by anyone with
"select" privilege on system_audit_.
Columns:
object_type - char (32)
The type of the object to which the comment applies. This
may include the type view, table, column, data dictionary,
or any other type which higher level software defines.
object_name - char (32)
The name of the object to which the comment applies.
operation - char (32)
The operation applied to the object. This will be defined
by higher level software but may include update, select,
create, etc.
comment - char (500)
Any arbitrary text that higher level software wishes to
apply to the audit entry.
person_id_entering - char (22)
The personid of the user who entered the audit entry into
the table.
project_id_entering - char (9)
The projectid of the user who entered the audit entry into
the table.
tag_entering - char (1)
The tag of the user who entered the audit entry into the
table.
time_entered - char (10)
The time the audit entry was entered into the audit table.
date_entered - char (8)
The date the audit entry was entered into the table.
Multics Technical Bulletin MTB 645
dd_version - char (8)
The version number of the system software putting the entry
into the table.
MTB 645 Multics Technical Bulletin
Table: System security information for columns
Name: system_column_security_
This table contains all the privileges set in the data
environment for columns. This table overrides the more general
information kept in the table security table. Administrator's
privilege is independent of the privileges recorded in this
table. The rules governing additions and deletion to this table
are those of the SQL grant and revoke requests. Whether the
addition or change is permitted depends on the current contents
of the set of security tables. Anyone with "select" privilege on
system_column_security_ can read the table.
Columns:
table_name - char (32) - first field of unique key
The table which the security information applies to. This
must be a valid table or view in the data environment.
column_name - char (32) - second field of unique key
The column which the security information applies to. This
must be a valid column in the named table.
person_id - char (22) - third field of unique key
The personid of the userid the security information applies
to. This can be *.
project_id - char (9) - fourth field of unique key
The projectid of the userid the security information applies
to. This can be *.
tag - char (1) - fifth field of unique key
The tag field of the Multics userid that the security
information applies to. It may be any legal value and *.
update_privilege - char (5)
Defines whether the userid has update privilege on the
column. This is in addition to any privilege the userid may
have on the table. Possible values are "yes", "no", and
"grant". If it is "grant", the userid has update privilege
and can grant this privilege to others.
null_privilege - char (5)
Defines whether the userid has no privilege on the column.
Possible values are "yes" and "no". This overrides more
general privilege in the same way that Multics acls do.
Multics Technical Bulletin MTB 645
person_id_entering - char (22)
The personid of the user who entered the security entry into
the table.
project_id_entering - char (9)
The projectid of the user who entered the security entry
into the table.
tag_entering - char (1)
The tag of the user who entered the security entry into the
table.
time_entered - char (10)
The time the security entry was entered into the table.
date_entered - char (8)
The date the security entry was entered into the table.
dd_version - char (8)
The version number of the system software putting the entry
into the table.
MTB 645 Multics Technical Bulletin
Table: Column definition table
Name: system_columns_
This table contains the definition of all columns known in the
data environment. There is one entry in it for every column in
every table or view in the data environment. Columns residing in
links are not kept in this table. Every column in any given
table or view must be unique. This table may be viewed by any
user with "select" privilege on system_columns_. The table is
modified whenever any user creates or drops a table, adds an
index to a table, or adds a column to a table. There is a
companion table, system_columns_binary_, which contains binary
information about each column.
Columns:
column_name - char (32) - first field of unique key
The name of a column in a table. This name must be
different from every other column in that table.
table_name - char (32) - second field of unique key
The table in which the column is defined. The table name
must be a valid table or view in the data environment.
data_type - char (32)
The data type of the column. This may be any of the valid
data types allowed by the view manager.
data_length - fixed bin (35)
The length of the data field. Note that this column may not
be meaningful if the data type implies a single length.
indexed - char (3)
Defines whether the column is indexed or not. The value of
this column can be either "yes" or "no".
null_allowed - char (3)
Defines whether the column can contain a null value.
Possible values are "yes" or "no".
person_id_entering - char (22)
The personid of the user who entered the column entry into
the table.
project_id_entering - char (9)
The projectid of the user who entered the column entry into
the table.
Multics Technical Bulletin MTB 645
tag_entering - char (1)
The tag of the user who entered the column entry into the
table.
time_entered - char (10)
The time the column entry was entered into the table.
date_entered - char (8)
The date the column entry was entered into the table.
dd_version - char (8)
The version number of the system software putting the entry
into the table.
MTB 645 Multics Technical Bulletin
Table: Column binary data definition table
Name: system_columns_binary_
This is the companion table to system_columns_. It contains
binary information needed by view manager to completely describe
a column. There is one entry in it for every entry in the
system_columns_ table. The contents of this table are driven by
the requirements of view manager. Changing the contents of this
table requires the same privileges as for system_columns_.
Columns:
column_name - char (32) - first field of unique index
The name of a column in a table. This name must be
different from every other column in that table.
table_name - char (32) - second field of unique index
The table in which the column is defined. The table name
must be a valid table or view in the data environment.
column_descriptor - bit (36)
The Multics descriptor of the data type for the defined
column.
null_value_info_offset - fixed bin (35)
Used by view manager.
person_id_entering - char (22)
The personid of the user who entered the column entry into
the table.
project_id_entering - char (9)
The projectid of the user who entered the column entry into
the table.
tag_entering - char (1)
The tag of the user who entered the column entry into the
table.
time_entered - char (10)
The time the column entry was entered into the table.
date_entered - char (8)
The date the column entry was entered into the table.
Multics Technical Bulletin MTB 645
dd_version - char (8)
The version number of the system software putting the entry
into the table.
MTB 645 Multics Technical Bulletin
Table: Comments on data environment objects
Name: system_comment_
This table contains user comments on the objects contained in the
data dictionary. This includes comments on tables, views, and
attributes. The comment can be any textual description. It is
intended that this will be used to describe what data environment
objects are. A comment can be added to an object if the user has
"alter" privilege on the table the comment refers to. If the
object is a column, the user must have "alter" on the containing
table. A user can read the comment if he has "select" privilege
on system_comment_.
Columns:
table_name - char (32) - first column of unique index
The name of the table to which the comment applies. It must
be a valid table or view in the data environment.
column_name - char (32) - second column of unique index
The name of the column to which the comment applies. It
must be a valid column in the table named by "table_name" or
blank if the comment applies to the table as a whole.
comment - char (500)
Any comment supplied by the user.
comment_version - char (10)
The version number of the comment. This column is free text
to be supplied by higher level software (i.e. view
manager).
person_id_entering - char (22)
The personid of the user who entered the comment into the
table.
project_id_entering - char (9)
The projectid of the user who entered the comment into the
table.
tag_entering - char (1)
The tag of the user who entered the comment into the table.
time_entered - char (10)
The time the comment was entered into the comment table.
Multics Technical Bulletin MTB 645
date_entered - char (8)
The date the comment was entered into the table.
dd_version - char (8)
The version number of the system software putting the entry
into the table.
MTB 645 Multics Technical Bulletin
Table: System security information for the data dictionary
interface
Name: system_dictionary_security_
This table contains all the privileges which are independent of
any particular table, view, or column. They, in effect, are
privileges associated with the data dictionary interface. The
rules governing additions and deletions to this table are those
of the SQL grant and revoke requests. Whether the addition or
change is permitted depends on the current contents of the
system_dictionary_security_ table. Anyone with "select"
privilege on system_dictionary_security_ can read the table.
Columns:
person_id - char (22) - first field of unique key
The personid of the userid the security information applies
to. This can be *.
project_id - char (9) - second field of unique key
The projectid of the userid the security information applies
to. This can be *.
tag - char (1) - third field of unique key
The tag field of the Multics userid that the security
information applies to. It may be any legal value and *.
access_privilege - char (5)
Defines whether the userid has access to the data
dictionary. Possible values are "yes", "no", and "grant".
If it is "grant", the userid has administrator privilege and
can grant this privilege to others.
administrator_privilege - char (5)
Defines whether the userid has administrator privilege on
the data dictionary interface. Possible values are "yes",
"no", and "grant". If it is "grant", the userid has
administrator privilege and can grant this privilege to
others.
create_synonym_privilege - char (5)
Defines whether the userid has create_synonym privilege on
the data dictionary interface. Possible values are "yes",
"no", and "grant".
create_tablespace_privilege - char (5)
Defines whether the userid has create_tablespace privilege
Multics Technical Bulletin MTB 645
on the data dictionary interface. Possible values are
"yes", "no", and "grant".
create_view_privilege - char (5)
Defines whether the userid has create_view privilege on the
data dictionary interface. Possible values are "yes", "no",
and "grant".
deregister_link_privilege - char (5)
Defines whether the userid has deregister_link privilege on
the data dictionary interface. Possible values are "yes",
"no", and "grant".
deregister_table_privilege - char (5)
Defines whether the userid has deregister_table_privilege on
the data dictionary interface. Possible values are "yes",
"no", and "grant".
drop_synonym_privilege - char (5)
Defines whether the userid has drop_synonym privilege on the
data dictionary interface. Possible values are "yes", "no",
and "grant".
drop_tablespace_privilege - char (5)
Defines whether the userid has drop_tablespace privilege on
the data dictionary interface. Possible values are "yes",
"no", and "grant".
drop_view_privilege - char (5)
Defines whether the userid has drop view privilege on the
data dictionary interface. Possible values are "yes", "no",
and "grant".
register_link - char (5)
Defines whether the userid has register_link privilege on
the data dictionary interface. Possible values are "yes",
"no", and "grant".
register_table - char (5)
Defines whether the userid has register_table privilege on
the data dictionary interface. Possible values are "yes",
"no", and "grant".
null
Defines whether the user has no privilege on the data
dictionary. This will override a more general privilege in
the same way that Multics acls do. Possible values are
"yes" and "no".
person_id_entering - char (22)
The personid of the user who entered the security entry into
the table.
MTB 645 Multics Technical Bulletin
project_id_entering - char (9)
The projectid of the user who entered the security entry
into the table.
tag_entering - char (1)
The tag of the user who entered the security entry into the
table.
time_entered - char (10)
The time the security entry was entered into the table.
date_entered - char (8)
The date the security entry was entered into the table.
dd_version - char (8)
The version number of the system software putting the entry
into the table.
Multics Technical Bulletin MTB 645
Table: External links
Name: system_links_
This table will define the set of external tables and views. An
external table or view is one which is not defined in the current
data dictionary. The foreign table can also be a link. Much
like a Multics link, it is merely a reference to where the real
table or view can be found. Through a link, a user can reference
data in another data environment. Any operation done to the link
affect only the link itself, not the foreign table. For example,
granting select privilege only allows a user to use the like.
For actual data to be retrieved, the user must have select
privilege in the foreign data dictionary. The link table may be
read by anyone with "select" privilege on system_links_. Adding
a link requires "register" privilege. Dropping a link requires
"unregister" privilege.
Columns:
link_name - char (32) - unique index
The name of the link. There must be no other links, tables,
or views with the same name.
foreign_data_dictionary - char (500)
The data dictionary that contains the foreign table. This
column will contain its Multics pathname.
foreign_table - char (32)
The name of the foreign table or view.
person_id_entering - char (22)
The personid of the user who entered the link into the
table.
project_id_entering - char (9)
The projectid of the user who entered the link into the
table.
tag_entering - char (1)
The tag of the user who entered the link into the table.
time_entered - char (10)
The time the link was entered into the link table.
date_entered - char (8)
The date the link was entered into the table.
MTB 645 Multics Technical Bulletin
dd_version - char (8)
The version number of the system software putting the entry
into the table.
Multics Technical Bulletin MTB 645
Table: User defined synonyms
Name: system_synonym_
This table is used to hold all the synonym definitions that are
valid within the data environment defined by the data dictionary.
A synonym is an alternate name for a table. The synonym table
may be used by anyone with "select" privilege on system_synonym_.
To add a synonym to the synonym table, a user requires the "add
synonym" privilege on the data dictionary. Dropping a synonym
requires "drop synonym" privilege. Each synonym in the table is
available to any user. Each synonym in the table must have a
unique name.
Columns:
synonym - char (32) - unique index
The name of the synonym.
table - char (32)
The name of the table to which the synonym refers. Table
must be a valid table or view name in the data environment.
person_id_entering - char (22)
The personid of the user who entered the synonym into the
table.
project_id_entering - char (9)
The projectid of the user who entered the synonym into the
table.
tag_entering - char (1)
The tag of the user who entered the synonym into the table.
time_entered - char (10)
The time the synonym was entered into the synonym table.
date_entered - char (8)
The date the synonym was entered into the table.
dd_version - char (8)
The version number of the system software putting the entry
into the table.
MTB 645 Multics Technical Bulletin
Table: System security information for tablespaces
Name: system_tablespace_security_
This table contains all the privileges set in the data
environment for tablespaces. Administrator's privilege is
independent of the privileges recorded in this table. The rules
governing additions and deletion to this table are those of the
SQL grant and revoke requests. Whether the addition or change is
permitted depends on the current contents of the set of security
tables. Anyone with "select" privilege on
system_tablespace_security_ can read the table.
Columns:
tablespace_name - char (32) - first field of unique key
The tablespace which the security information applies to.
This must be a valid column in the named table.
person_id - char (22) - second field of unique key
The personid of the userid the security information applies
to. This can be *.
project_id - char (9) - third field of unique key
The projectid of the userid the security information applies
to. This can be *.
tag - char (1) - fourth field of unique key
The tag field of the Multics userid that the security
information applies to. It may be any legal value and *.
alter_tablespace_privilege
Defines whether the userid has alter_tablespace privilege on
the tablespace. Possible values are "yes", "no", and
"grant". If it is "grant", the user has alter_tablespace
privilege and can grant that privilege to others.
create_table
Defines whether the userid has create_table privilege on the
tablespace. Possible values are "yes", "no", and "grant".
drop_table
Defines whether the userid has drop_table privilege on the
tablespace. Possible values are "yes", "no", and "grant".
null_privilege - char (5)
Defines whether the userid has no privilege on the
tablespace. Possible values are "yes" and "no". This
Multics Technical Bulletin MTB 645
overrides more general privilege in the same way that
Multics acls do.
person_id_entering - char (22)
The personid of the user who entered the security entry into
the table.
project_id_entering - char (9)
The projectid of the user who entered the security entry
into the table.
tag_entering - char (1)
The tag of the user who entered the security entry into the
table.
time_entered - char (10)
The time the security entry was entered into the table.
date_entered - char (8)
The date the security entry was entered into the table.
dd_version - char (8)
The version number of the system software putting the entry
into the table.
MTB 645 Multics Technical Bulletin
Table: System security information for tables
Name: system_table_security_
This table contains all the privileges set in the data
environment on tables and views. The only privileges not in this
table are those the Administrator has because he is
Administrator. The rules governing additions and deletion to
this table are those of the SQL grant and revoke requests.
Whether the addition or change is permitted depends on the
current contents of the set of security tables. Anyone with
"select" access on system_table_security_ can read the table.
Columns:
table_name - char (32) - first field of unique key
The table which the security information applies to. This
must be a valid table or view in the data environment.
person_id - char (22) - second field of unique key
The personid of the userid the security information applies
to. This can be *.
project_id - char (9) - third field of unique key
The projectid of the userid the security information applies
to. This can be *.
tag - char (1) - fourth field of unique key
The tag field of the Multics userid that the security
information applies to. It may be any legal value and *.
select_privilege - char (5)
Defines whether the userid has select privilege on the
table. Possible values are "yes", "no", and "grant". If it
is "grant", the userid has select privilege and can grant
this privilege to others.
insert_privilege - char (5)
Defines whether the userid has insert privilege on the
table. Possible values are "yes", "no", and "grant".
delete_privilege - char (5)
Defines whether the userid has delete privilege on the
table. Possible values are "yes", "no", and "grant".
update_privilege - char (5)
Defines whether the userid has update privilege on the
table. Possible values are "yes", "no", and "grant".
Multics Technical Bulletin MTB 645
alter_privilege - char (5)
Defines whether the userid has alter privilege on the table.
Possible values are "yes", "no", and "grant".
index_privilege - char (5)
Defines whether the userid has index privilege on the table.
Possible values are "yes", "no", and "grant".
link_privilege - char (5)
Defines whether the userid has link privilege on the table.
Possible values are "yes", "no", and "grant".
null_privilege - char (5)
Defines whether the userid has no privilege on the table.
This privilege overrides more general privilege in the same
way that a specific Multics null acl overrides a more
general one. Possible values are "yes" and "no".
person_id_entering - char (22)
The personid of the user who entered the security entry into
the table.
project_id_entering - char (9)
The projectid of the user who entered the security entry
into the table.
tag_entering - char (1)
The tag of the user who entered the security entry into the
table.
time_entered - char (10)
The time the security entry was entered into the table.
date_entered - char (8)
The date the security entry was entered into the table.
dd_version - char (8)
The version number of the system software putting the entry
into the table.
MTB 645 Multics Technical Bulletin
Table: Tables defined in data environment
Name: system_tables_
This table contains the definition of every table and view
defined in the current data environment. Excluding links, any
table not defined here is not accessible to the user. This
table, along with its companion table system_tables_binary_
completely defines every table in the data environment. Adding a
table requires "add_table" privilege. Dropping a table requires
"drop_table" privilege. Changing rows in this table requires
appropriate privileges on the table name being modified. The
table can be read by anyone with "select" privilege on
system_table_.
Columns:
table - char (32) - unique index
This is the name of a table in the data environment. There
must be no other tables, views, or links with the same name.
table_type - char (5)
The type of the table. This can be either "table" or
"view".
table_path - char (500)
The Multics pathname of the table. This column defines
where the table is physically stored in the Multics storage
system. This must be a valid Multics pathname.
table_manager - char (32)
The entryname of the module which will be used by view
manager to access the table and the data it contains.
number_of_columns - fixed bin (35)
The number of columns which the table contains.
table_version - char (10)
The version number of the table. This column is free text
to be supplied by higher level software.
person_id_entering - char (22)
The personid of the user who entered the table entry into
the table.
project_id_entering - char (9)
The projectid of the user who entered the table entry into
the table.
Multics Technical Bulletin MTB 645
tag_entering - char (1)
The tag of the user who entered the table entry into the
table.
time_entered - char (10)
The time the table entry was entered into the table.
date_entered - char (8)
The date the table entry was entered into the table.
dd_version - char (8)
The version number of the system software putting the entry
into the table.
MTB 645 Multics Technical Bulletin
Table: Binary information description of tables
Name: system_tables_binary_
This table is the companion table to system_tables_. It contains
binary data needed by the view manager on each table. Data in it
is not in human readable form. The contents of this table are
driven by the requirements of the view manager. Changing the
contents of this table requires the same privileges as for
system_tables_.
Columns:
table - char (32) - unique index
The name of a table in the data environment. There must be
a corresponding entry in system_tables_.
unique_identifier - bit (36)
The Multics unique file identifier.
sel_statement_offset - fixed bin (35)
Used by view manager.
data_space_size - fixed bin (35)
The size of the data space; used by view manager.
data_space - char (4096)
Binary data; used by view manager.
person_id_entering - char (22)
The personid of the user who entered the table entry into
the table.
project_id_entering - char (9)
The projectid of the user who entered the table entry into
the table.
tag_entering - char (1)
The tag of the user who entered the table entry into the
table.
time_entered - char (10)
The time the table entry was entered into the table.
date_entered - char (8)
The date the table entry was entered into the table.
Multics Technical Bulletin MTB 645
dd_version - char (8)
The version number of the system software putting the entry
into the table.