Multics Technical Bulletin                        MTB-592, Rev. 1
DM:  Structure & Initialization

To:       Distribution

From:     John J. Bongiovanni, Lee A. Newcomb

Date:     08/04/83

Subject:  Data Management:  System Structure and Initialization

1 ABSTRACT

     This document describes the  objectives and structure of the
per-system  and per-process  data used  by Data  Management.  The
term structure means the location and relationship of the various
tables which  comprise the per-system and  per-process data.  The
mechanisms for initializing per-system and per-process tables are
discussed  separately.  Subroutine  interfaces required  by other
parts of the Data Management system are described.

Comments should be sent to the author:

via Multics forum:
   >udd>Multics>Spratt>meetings>DMS_Development

via Multics Mail:
   Newcomb.Multics  on  System  M   or  LNewcomb.Multics  on  MIT
   Multics.

via US Mail:
   Lee A. Newcomb
   Honeywell Information Systems, Inc.
   575 Tech Square
   Cambridge, Massachusetts 02139

via telephone:
   (HVN) 261-9332, or (617) 492-9332

_________________________________________________________________

Multics  project  internal  working  documentation.   Not  to  be
reproduced or distributed outside the Multics project without the
consent of the author or the author's management.



                            CONTENTS

                                                         Page

                 1 Abstract . . . . . . . . . . . . . .     i
                 2 Introduction . . . . . . . . . . . .     1
                 3 Objectives . . . . . . . . . . . . .     2
                 4 Per-System Tables  . . . . . . . . .     2
                    4.1 Data Management System
                     Directory  . . . . . . . . . . . .     2
                    4.2 Per-AIM Authorization Directory     2
                    4.3 Per-Bootload Tables . . . . . .     3
                    4.4 System Structure Summary  . . .     3
                 5 Terminology  . . . . . . . . . . . .     4
                 6 Per-Process Tables - Inner Ring  . .     4
                 7 Per-Process Tables - User Ring . . .     4
                 8 Calling method of inner ring
                  subsystems  . . . . . . . . . . . . .     4
                 9 Per-Bootload Initialization  . . . .     5
                    9.1 Overview  . . . . . . . . . . .     5
                    9.2 Initialization Programs . . . .     7
                    9.3 Recovery Programs . . . . . . .     7
                    9.4 Taking over a running DM system     7
                 10 Per-Process Initialization  . . . .     8
                    10.1 Overview . . . . . . . . . . .     8
                    10.2 Per-Process Initialization
                     Routines . . . . . . . . . . . . .     9
                 11 Data Management Shutdown  . . . . .    10
                 12 Independent Data Management Systems    10
                 13 System Initialization Routines  . .    10
                    dm_dir_ . . . . . . . . . . . . . .    11
                       $get_aim_dir . . . . . . . . . .    12
                       $get_bootload_dir  . . . . . . .    13
                       $get_bootload_dir_name . . . . .    14
                       $get_enabled_bootload_dir  . . .    15
                       $get_enabled_bootload_dir_name .    16
                       $get_init_bootload_dir_name  . .    17
                       $get_last_bootload_dir . . . . .    18
                       $get_system_dir  . . . . . . . .    19
                       $set_aim_dir . . . . . . . . . .    20
                       $set_system_dir  . . . . . . . .    21
                    dm_per_system_  . . . . . . . . . .    22
                       $alloc . . . . . . . . . . . . .    23
                       $cleanup . . . . . . . . . . . .    24
                       $create  . . . . . . . . . . . .    25



                         CONTENTS (cont)

                                                         Page

                       $enable  . . . . . . . . . . . .    26
                       $init  . . . . . . . . . . . . .    27
                       $initiate  . . . . . . . . . . .    28


Multics Technical Bulletin                        MTB-592, Rev. 1
DM:  Structure & Initialization

2 INTRODUCTION

     The  Multics  Access   Isolation  Mechanism  (AIM)  presents
several   problems   to   Data   Management.    In   the  initial
implementation,  Data Management  will not support  AIM, since it
will not support multi-authorization  data bases.  Instead, users
of  data bases  at one  AIM authorization  will be  isolated from
users  of data  bases at any  other AIM  authorization.  In this,
Data  Management  will operate  like  most other  subsystems with
respect to AIM.

     Various   Data  Management   subsystems  require  per-system
tables,  writable  from any  process.  Examples  of this  are the
Before Image  Journal buffer and  the table of  active locks.  To
protect  these tables  from accidental or  malicious damage, they
will live  in an inner  ring (currently, ring-2).   However, they
remain  subject  to  AIM,  and hence  are  writable  at  only one
authorization.  As a result,  these Data Management tables cannot
be  per-system at  a site which  uses AIM; instead,  they must be
per-AIM authorization.

     In  effect,  Data Management  at  an AIM  site  is a  set of
mutually isolated Data Management systems, each with its own data
bases and what it views as  per-system tables.  A given user data
base  belongs to  one and  only one  of these  isolated systems -
namely, the system corresponding  to its AIM authorization.  Note
that  this  precludes  the  use  of   a  data  base  of  one  AIM
authorization  as   a  read-only  data  base   at  a  higher  AIM
authorization.   Although  read-only  access   by  a  higher  AIM
authorization is allowed  by AIM, it could not  be implemented in
Data Management without some  form of multi-authorization support
(minimally, for the shared writable system tables).

     Aside from  AIM, there is some  utility in mutually isolated
Data  Management  systems.   It  is  useful  to  Data  Management
developers,  for example,  to have  a production  version of Data
Management on  the same machine as  several different development
versions.   Each  version would  operate on  its own  data bases,
using its own per-system tables.

3 OBJECTIVES

     The structure presented in this document is designed to meet
the following objectives:

    o  Allow  the  Data Management  system to  operate at  a site
       which uses AIM.  At such  a site, Data Management operates
       as a set of mutually isolated Data Management systems, one
       for each active AIM authorization.


MTB-592, Rev. 1                        Multics Technical Bulletin
                                  DM:  Structure & Initialization

    o  Allow the operation of independent Data Management systems
       on  the  same Multics  system, with  some or  all software
       shared among the different  systems.  This is intended for
       development, and it will not be visible to sites.

    o  Package  the  various  tables   used  by  Data  Management
       efficiently  (avoiding  the  proverbial  "Tax  on  Segment
       Numbers" where reasonable to do so).

4 PER-SYSTEM TABLES

4.1 Data Management System Directory

     The  location   of  all  per-AIM   Authorization  tables  is
determined,  ultimately, from  a control segment  in a per-system
directory  which is  named canonically  (>site>dm).  However, the
control segment is accessed only via a subroutine, and the naming
convention  (i.e., the  exact location of  the segment, currently
>site>dm>dm_aim_control)  is known  only to  the subroutine.  The
control segment contains an entry  for each AIM authorization for
which Data Management has been enabled by the Site Administrator.
This  entry  defines the  location  of the  per-AIM authorization
directory.

4.2 Per-AIM Authorization Directory

     There is  a directory for  each AIM authorization  for which
Data Management has been enabled.  This directory is created (and
assigned quota)  at the time the  corresponding AIM authorization
is enabled  by a system  administrator.  It contains  all per-AIM
Authorization  Data  Management  tables   that  exist  across  DM
bootloads, such as the per-AIM configuration table.  The location
of  this  directory  is  determined from  the  per-system control
segment.

4.3 Per-Bootload Tables

     All per-bootload tables for an invocation of Data Management
are really  per-AIM authorization tables.  That  is, these tables
are  initialized  for  each  bootload  when  Data  Management  is
started.  Tables  from the previous  bootload are used  for crash
recovery (e.g.,  to back out transactions  which were in progress
at   the  time   of  the   crash).   Following   crash  recovery,
per-bootload tables from a previous bootload are no longer of any
use and are either deleted or held for later inspection.


Multics Technical Bulletin                        MTB-592, Rev. 1
DM:  Structure & Initialization

     The  per-bootload tables  for an  single invocation  of a DM
system  are  contained in  a per-bootload  directory, immediately
subordinate to the per-AIM Authorization directory, with the name

     dm_dir.[substr [request_id |[system date_time_last_up]] 1 10]

These directories will  be abbreviated in the rest  of the MTB as
dm_dir.{system_boot_time}.   The  existence   of  this  directory
implies  that  all  tables  located in  the  directory  have been
initialized and  are available to users  of data management.  The
Multics system  time up is  used for convenience  in locating the
current  bootload  directory  at  any time  for  all  users.  The
mechanism to effect this is:  the directory is first created with
the  above name  with an  added ".init"  suffix; all per-bootload
tables for  the current AIM authorization  are created within the
directory and initialized; and  finally, the directory is renamed
to the above by removing the ".init" suffix.

     The  segment dm_system_data_  is immediately  subordinate to
the per-bootload directory.  It contains a small amount of static
per-bootload data  of general use to  Data Management subsystems.
Static  data  is  accessible  externally  in  the  inner-ring (as
dm_system_data_$symbol_name).   Dm_system_data_  also  contains a
non-extendable  area   for  those  Data   Management  tables  not
sufficiently  large  to  warrant  separate  segments.   Any other
tables  implemented as  independent segments  reside as immediate
subordinates  to  the  per-bootload  directory.   Subroutines are
provided  to  support  both  methods of  packaging  system tables
(allocation  within  the  non-extendable  area  and  creation  of
separate segments).

4.4 System Structure Summary

     The structure of per-system and per-AIM Authorization tables
is depicted in Attachment 1.

5 TERMINOLOGY

     For  the remainder  of this MTB,  the term  "DM system" will
refer  to  an  invocation  (bootload)  of  Data  Management  at a
particular  AIM  authorization   unless  noted  otherwise.   This
implies  an initializing/caretaker  process (a  DM Daemon  in the
normal   case),   and  per-system,   per-AIM,   and  per-bootload
directories  (with  the per-bootload  tables in  the per-bootload
directory).  It is the per-bootload  direcotry that the user sees
as the DM system in use.


MTB-592, Rev. 1                        Multics Technical Bulletin
                                  DM:  Structure & Initialization

6 PER-PROCESS TABLES - INNER RING

     There are no special segments or files created for a process
running  Data Management  in the  inner ring  (currently ring-2).
The  linkage section  of the  inner ring  program dm_data_ stores
data of use to the  various Data Management inner ring subsystems
(e.g.,  dm_data_$inner_ring_areap  and  dm_data_$current_txn_id).
The  other   inner  ring  DM  subsystems   also  have  their  own
per-process  data   segments,  constructed  like   dm_data_,  for
per-process   data   specific   to  them   (e.g.    fm_data_  for
file_manager_ and  lm_data_ for lock_manager_).   All per-process
tables are allocated in the inner-ring system free area.

     Externally   available   pointers  and   the  initialization
mechanism to be discussed eliminate  the need for Data Management
subsystems  to  understand the  DM directory  structure discussed
earlier.   All of  the various  tables are  accessed via pointers
accessible externally in dm_data_, fm_data_, and lm_data_.

7 PER-PROCESS TABLES - USER RING

     Any   per-process   tables  required   by   Data  Management
subsystems in the user ring are allocated in the system free area
for the user ring.

8 CALLING METHOD OF INNER RING SUBSYSTEMS

     Some of the initialization will be understood better knowing
the method of calling inner ring subsystem programs (currently in
ring-2).   All programs  outside of a  subsystem are  to call the
subsystem's main transfer vector.

     There are  subsystem programs meant  to be called  only from
within the inner  ring.  An example of this  is the file_manager_
calling  before_journal_manager_  to  write a  before  image.  To
satisfy the  requirement that a subsystem  call the main transfer
vector of another subsystem, file_manager_  must call an entry in
before_journal_manager_.  However, only  the file_manager_ should
be  able  to  do this,  not  any  program in  any  ring.  Entries
callable only in  the inner ring are NOT put  in the gate segment
for the  subsystem; the main  transfer vector directly  calls the
inner ring transfer vector.


Multics Technical Bulletin                        MTB-592, Rev. 1
DM:  Structure & Initialization

     Any operation allowed for normal  use must go through a gate
for the subsystem  to get to the inner ring.   The gate calls the
inner ring  transfer vector which  actually calls the  inner ring
target  program.   Thus,  a  program in  the  inner  ring  is not
hindered from calling  an entry available to the  outer ring, but
there is  extra cost in  sometimes going through  an extra object
segment to get to the target program.

     Note the  inner ring transfer  vectors amd gates  contain no
per-system initialization references that must be called before a
running  Data   Management  system  is   operational.   The  main
subsystem transfer vector calls straight into the required target
subsystem program (it  is assumed the caller is  in the DM ring).
The reason for this will be more evident when the first reference
trap on the inner ring transfer  vector is discussed fully in the
section on per-process initialization.

     The following  is a diagram of  the different paths possible
when a program calls an entry in an inner ring subsystem:

            {caller outside of a DM subystem}
                           v|
            {subsystem main transfer vector}
                           v|
 -----------------------------------------------
v|(sys. init.)           v|(R2 only)              v|(normal)
|                       |                       |
|                       v|          (normal)     v|
| {ring-2 subsys. transfer vector} <------- {ring-2 subsys. gate}
v|                       v|
|                       |
|(sys. init.)           |(R2 only or normal)
v|                       v|
 ----------> {ring-2 subsys. program}

9 PER-BOOTLOAD INITIALIZATION

9.1 Overview

     Data  Management  is initialized  for  each bootload  in the
following  manner.   A  Daemon   process  is  logged  in  (either
automatically  by  system_start_up.ec  or  by  explicit  operator
command).    The   Daemon   calls    an   inner   ring   program,
dm_initializer_, through a privileged Data Management gate.


MTB-592, Rev. 1                        Multics Technical Bulletin
                                  DM:  Structure & Initialization

     The  program  dm_initializer_  is  similar  to  the  program
initializer in  Multics ring-0 initialization.   Specifically, it
is a set of ordered calls to other Data Management initialization
and  recovery   programs.   Conceptually,  the   processing  flow
implemented by dm_initializer_ is the following:

    o  Find  the  per-AIM  configuration   file  in  the  per-AIM
       directory and lock it against administrative modification.
       This lock also guarantees only  one process can be running
       a DM system at a time for the current AIM authorization.

    o  Check if a DM system is running for current Multics system
       (i.e.   the  directory  dm_dir.{system_boot_time} exists).
       If so, try to take over the DM Daemon responsibilities and
       ignore the remaining steps.

    o  Create  a dm_dir.{system_boot_time}.init  directory, which
       will  become   the  per-bootload  directory   for  per-AIM
       Authorization tables.

    o  Create   and  initialize   dm_system_data_  in   this  new
       directory,   and  make   it  known   with  reference  name
       "dm_system_data_".

    o  Call a  set of initialization programs,  one for each Data
       Management   subsystem  requiring   per-AIM  Authorization
       tables.   These  programs assume  a valid  Data Management
       system is not  yet running.  This step is  called part one
       initialization.

    o  Find  all  instances of  dm_dir.{system_boot_time}  in the
       per-AIM  directory.   If  there  are any,  call  a  set of
       recovery programs.

    o  Call a  set of initialization programs,  one for each Data
       Management subsystem requiring some initialization AFTER a
       valid  Data Management  system is  running.  This  step is
       called part two initialization.

    o  Delete or rename all dm_dir.{system_boot_time} directories
       remaining in the per-AIM directory.

    o  Rename     the     current    bootload     directory    to
       dm_dir.{system_boot_time} by removing the ".init" suffix.


Multics Technical Bulletin                        MTB-592, Rev. 1
DM:  Structure & Initialization

9.2 Initialization Programs

     All part one and two  system initialization programs for the
various  DM subsystems  are called  by dm_initializer_  using the
following sequence:

     call initialization_program ();

If the  program returns, the initialization  was successful.  The
sub_err_  program is  called to  report errors  by signalling the
sub_error  condition.  In  order to  create segments  or allocate
space for per-bootload tables, initialization_program should call
the appropriate entry in dm_per_system_, documented later in this
MTB.

     When invoked,  a part one initialization  program can assume
only  that the  reference name "dm_system_data_"  is available to
it.  Part two initialization programs can assume they are running
on a valid system to which  users have not yet been given access;
these programs fill in information  that was not available before
all of  the part one  initialization was finished.   The contract
between  an  initialization  program  and other  programs  in its
subsystem  is as  follows:  it  returns a  zero code  only if all
per-bootload  tables  and  dm_system_data_  values  used  by  the
subsystem have been initialized.

9.3 Recovery Programs

     The  interface  between  dm_initializer_  and  the  recovery
programs is defined in MTB 603, Data Management:  Crash Recovery.

9.4 Taking over a running DM system

     Occasionally the DM Daemon process  dies, leaving a valid DM
system, but no process to periodically cleanup the DM tables.  It
is possible  for a different  process of sufficient  privilege to
take over this running DM system.

     Takeover of  a running DM system  has several benefits.  The
system tables  are valid, so no  time need be used  in creating a
completely  new DM  system (a  per-bootload directory  and tables
under the per-AIM directory).  Users  of the current DM system do
not lose their  current work.  Recovery does not  have to be run.
Some transactions  may be left unfinished  by dead user processes
until  a  new Daemon  can be  logged in  to perform  the cartaker
functions, but this  is a minor cost compared  with shutting down
and re-initializing; and the tables will  be tidied when a new DM
Daemon takes over control.


MTB-592, Rev. 1                        Multics Technical Bulletin
                                  DM:  Structure & Initialization

     Before  the  new  DM   Daemon  tries  creating  the  ".init"
directory, it must find and  lock the per-AIM configuration file.
Once this is done, the Daemon tries to find a bootload directory.
If one is found, the DM  Daemon process ID in the dm_system_data_
segment  is checked  for validity.  If  the ID is  valid, the new
Daemon's  initialization fails;  the current  DM system  has a DM
Daemon  overseeing it.   If the ID  is not valid,  the new Daemon
writes  its  process  ID  in  dm_system_data_,  does  per-process
initialization, and  takes charge of the  current DM system.  The
new  Daemon  will  then  do  any  cleanup  in  the  system tables
necessary.

10 PER-PROCESS INITIALIZATION

10.1 Overview

     Data Management is initialized for  a process the first time
that  process invokes  a ring-2 Data  Management subsystem.  Each
inner  ring  subsystem has  an  inner ring  transfer  vector (see
above).  This  vector has a first  reference trap associated with
it.  The trap  causes the values for the  subsystem being invoked
to be initialized in the user's  process in the static section of
the  object  segment  dm_data_.   This  data  is  only  valid  if
referenced from the inner ring.

     Each inner ring subsystem conceptually does the following:

    o  Find dm_system_data_ for the current bootload for this AIM
       authorization.  Make this segment known with the reference
       name "dm_system_data_", if not already done.

    o  Initialize  any  static variables  in dm_data_  of general
       usage to Data Management, if not already done.

    o  Call  the  per-process   initialization  program  for  the
       subsystem being called.

    o  Return  to the  inner ring  transfer vector  to resume its
       processing.


Multics Technical Bulletin                        MTB-592, Rev. 1
DM:  Structure & Initialization

10.2 Per-Process Initialization Routines

     Each  inner  ring  subsystem  transfer  vector  has  a first
reference trap associated  with it.  This is the  main reason the
part one per-system initialization programs have to be referenced
straight from the subystem gate.   The first reference trap calls
the initialization program for the subsystem referenced using the
following call sequence:

     call per_process_init_routine ();

An  error  is  indicated  by the  initialization  program calling
sub_err_ to signal the sub_error condition.

     Each initialization program must  locate the per-system data
for  its  Data  Management  subsystem and  fill  in  the relevant
pointers,  etc.,  in dm_data_.   It  may be  necessary for  it to
initiate  per-system segments.   When invoked,  an initialization
program can assume only the following:

    o  The  reference name  "dm_system_data_" is  available to it
       and the data in this segment have been initialized.

    o  The reference  name "dm_data_" is available  to it and all
       global   data  elements   have  been   initialized  (e.g.,
       dm_data_$area_ptr).

     The  contract between  a per-process  initialization program
and  its  subsystem is  the  following.  It  returns only  if all
per-process tables needed by  the subsystem have been initialized
and  all  data  items in  dm_data_  external static  used  by the
subsystem have been established  (and fm_data_ in file_manager_'s
case and lm_data_ for lock_manager_'s).

     Each  initialization  routine  must allocate  space  for its
per-process tables using the standard area package.  A pointer to
the  area is  located in dm_data_$area_ptr.   After a per-process
table has been initialized,  the initialization routine must fill
in     the     relevant     pointer     in     dm_data_    (e.g.,
dm_data_$lock_table_ptr).

11 DATA MANAGEMENT SHUTDOWN

     The  shutdown of  a running  Data Management  system will be
covered in a separate MTB.


MTB-592, Rev. 1                        Multics Technical Bulletin
                                  DM:  Structure & Initialization

12 INDEPENDENT DATA MANAGEMENT SYSTEMS

     Independent  Data  Management  systems  are  implemented  by
allowing a suitably privileged process  to change the location of
the per-system  Data Management directory to  any directory name.
As   a  result,   the  per-AIM  directory   will  be  immediately
subordinate  to  the  specified directory,  and  the per-bootload
directory  immediately  subordinate  to  that.   Again,  this  is
intended   to   facilitate   Data   Management   development  and
maintenance.  It will not be documented for customer use.

13 SYSTEM INITIALIZATION ROUTINES

     The  following  routines  are  used  by  the  per-system and
per-process initialization mechanisms.

_______                                                   _______

dm_dir_                                                   dm_dir_
_______                                                   _______

Name:  dm_dir_

     The dm_dir_ subroutine manages  all handling of DM directory
pathnames   and  some   entrynames.   Its  main   use  is  during
per-process initialization when a process must find the directory
containing the  current DM system's  tables.  It is  also used in
per-system  initialization  by  the   DM  Daemon  and  some  test
entrypoints exist for privileged processes.

     All  of  the entries  to get  the  path or  entry name  of a
directory  are called  as functions  for ease  of use  (i.e.  the
dm_dir_$get* entries).   All error reporting for  dm_dir_ is done
by  calling  the  sub_err_  subroutine  to  signal  the sub_error
condition.

_______                                                   _______

dm_dir_                                                   dm_dir_
_______                                                   _______

Entry:  dm_dir_$get_aim_dir

          This  entry is  used to  determine the  pathname of the
current per-AIM authorization directory for the AIM authorization
of  the calling  process.  This program  signals an  error if the
current  AIM  authorization has  not been  registered in  the AIM
control file in the per-system directory.

Usage

     dcl dm_dir_$get_aim_dir entry () returns (char (*));

     dm_aim_dir = dm_dir_$get_aim_dir ();

where:

       dm_aim_dir                   (Output)
            is   the  pathname   of  the   per-AIM  authorization
            directory.

_______                                                   _______

dm_dir_                                                   dm_dir_
_______                                                   _______

Entry:  dm_dir_$get_bootload_dir

          This entry is  used to obtain the full  pathname of the
per-bootload directory for the  AIM authorization of the invoking
process.   If  it  is  called  before  Data  Management  has been
initialized (that is, before a call to dm_per_system_$enable), it
signals an  error.  An exception  is made for  the Daemon process
initializing   Data   Management.     This   process   may   call
dm_dir_$get_bootload during per-system  initialization opened for
users (dm_per_system_$enable).  In this  case, it is returned the
full pathname  of the per-bootload  directory at that  time (that
is, its temporary name, dm_dir.{system_boot_time}.init).

Usage

     dcl dm_dir_$get_bootload_dir entry () returns (char (*));

     dm_bootload_dir = dm_dir_$get_bootload_dir ();

where:

       dm_bootload_dir              (Output)
            is the current name of the bootload directory.

_______                                                   _______

dm_dir_                                                   dm_dir_
_______                                                   _______

Entry:  dm_dir_$get_bootload_dir_name

          This  entry  returns  the   entryname  of  the  current
bootload  directory  for  the  AIM authorization  of  the calling
process.   If  it  is  called  before  Data  Management  has been
initialized, it signals  an error.  An exception is  made for the
Daemon  process  initializing  a  Data  Management  system;  this
process  may  use  this  entry  during  per-system initialization
before dm_per_system_$enable  has been called to  get the current
name  of  the  bootload  directory  (i.e.,  the  temporary  name,
dm_dir.{system_boot_time}.init).

Usage

     dcl dm_dir_$get_bootload_dir_name entry () returns (char
          (*));

     dm_bootload_dir_ename = dm_dir_$get_bootload_dir_name ();

where:

       dm_bootload_dir_ename        (Output)
            is   the  entryname   of  the   current  per-bootload
            directory.

_______                                                   _______

dm_dir_                                                   dm_dir_
_______                                                   _______

Entry:  dm_dir_$get_enabled_bootload_dir

          This  entry returns  the full, enabled  pathname of the
Data Management  per-bootload directory for  the calling process'
AIM  authorization.  It  does not  matter if  the Data Management
system for the AIM authorization is actually enabled; but failure
will occur  if the AIM  authorization is not recorded  in the AIM
control segment in the per-system directory.

Usage

     dcl dm_dir_$get_enabled_bootload_dir entry () returns (char
          (*));

     dm_enabled_bootload_dir = dm_dir_$get_enabled_bootload_dir
          ();

where:

       dm_enabled_bootload_dir      (Output)
            is  the  absolute  pathname  of  the  Data Management
            per-bootload  directory when  the system  is enabled,
            regardless if it is enabled or not.

_______                                                   _______

dm_dir_                                                   dm_dir_
_______                                                   _______

Entry:  dm_dir_$get_enabled_bootload_dir_name

          This  entry returns  the enabled entryname  of the Data
Management  per-bootload directory  for the  calling process' AIM
authorization.  It does not matter  if the Data Management system
for the  AIM authorization is actually  enabled; but failure will
occur if the AIM authorization is not recorded in the AIM control
segment in the per-system directory.

Usage

     dcl dm_dir_$get_enabled_bootload_dir_name entry () returns
          (char (*));

     dm_enabled_bootload_dir_ename =
          dm_dir_$get_enabled_bootload_dir_name ();

where:

       dm_enabled_bootload_dir_ename (Output)
            is the entryname of  the Data Management per-bootload
            directory when  the system is  enabled, regardless if
            it is enabled or not.

_______                                                   _______

dm_dir_                                                   dm_dir_
_______                                                   _______

Entry:  dm_dir_$get_init_bootload_dir_name

          Returns the entryname of  the per-bootload directory as
it should appear during per-system initialization.  This entry is
designed for use by the DM  Daemon and is only available trough a
privileged gate.

Usage

     dcl dm_dir_$get_init_bootload_dir_name entry () returns
          (char (*));

     dm_init_bootload_dir_ename =
          dm_dir_$get_init_bootload_dir_name ();

where:

       dm_init_bootload_dir_ename   (Output)
            is  the  entryname  of  the  initialization  bootload
            directory.

_______                                                   _______

dm_dir_                                                   dm_dir_
_______                                                   _______

Entry:  dm_dir_$get_last_bootload_dir

          Returns pathname of the  per-bootload directory for the
last active  Data Management system.  This  entry is designed for
crash recovery and is only available through a privileged gate.

Usage

     dcl dm_dir_$get_last_bootload_dir entry () returns (char
          (*));

     dm_last_bootload_dir = dm_dir_$get_last_bootload_dir ();

where:

       dm_last_bootload_dir         (Output)
            is  the  pathname  of  the  last  active per-bootload
            directory.

_______                                                   _______

dm_dir_                                                   dm_dir_
_______                                                   _______

Entry:  dm_dir_$get_system_dir

          Returns  the pathname  of the  per-system directory for
Data Management.  This is usually  >site>dm unless changed in the
program or a privileged process is doing testing and has used the
dm_dir_$set_system_dir entry.

Usage

     dcl dm_dir_$get_system_dir entry () returns (char (*));

     dm_system_dir = dm_dir_$get_system_dir ();

where:

       dm_system_dir                (Output)
            is the absolute pathname  of the per-system directory
            for Data Management.

_______                                                   _______

dm_dir_                                                   dm_dir_
_______                                                   _______

Entry:  dm_dir_$set_aim_dir

          This  entry is  used to  set the  per-AIM authorization
directory in the control segment  of the per-system directory for
the AIM authorization specified.  If the AIM authorization has no
entry  in the  control segment,  one is  created.  Otherwise, the
directory name in  the entry is replaced by  the one specified in
the call to this entry.  This  entry is only available through an
administrative or privileged gate.

Usage

     dcl dm_dir_$set_aim_dir entry (fixed bin (71), char (*));

     call dm_dir_$set_aim_dir (authorization, dm_aim_dir_ename);

where:

       authorization                (Input)
            is the binary form of the AIM authorization.

       dm_aim_dir_ename             (Input)
            is  the  entryname  of  the  directory  for  the  AIM
            authorization  specified.   The directory  must exist
            before using this entry.

_______                                                   _______

dm_dir_                                                   dm_dir_
_______                                                   _______

Entry:  dm_dir_$set_system_dir

          This  entry   is  used  to  set   the  per-system  Data
Management directory for the invoking process.  A control segment
in  this  directory is  used  to find  all  per-AIM authorization
directories.   This entry  is only callable  through a privileged
gate for testing and debugging.

Usage

     dcl dm_dir_$set_system_dir entry (char (*));

     call dm_dir_$set_system_dir (dm_system_dir);

where:

       dm_system_dir                (Input)
            is the name of the per-system directory to be used by
            Data Management for the privileged process taking the
            place of the normal DM Daemon.

______________                                     ______________

dm_per_system_                                     dm_per_system_
______________                                     ______________

Name:  dm_per_system_

     The  dm_per_system_  subroutine  manages all  handling  of a
per-bootload  directory  and  its  contents.   This  includes the
creation  of  the  dm_system_data_ segment,  calling  the various
per-system initalization  programs of the DM  subsystems, and the
creation and  allocation of tables  for a DM  system.  Errors are
indicated by  the sub_error condition being  signalled (by a call
to sub_err_), not by a status code argument.

______________                                     ______________

dm_per_system_                                     dm_per_system_
______________                                     ______________

Entry:  dm_per_system_$alloc

          Allocates storage in the non-entendable area within the
dm_system_data_  segment   in  the  per-bootload   directory  for
per-system  initializaton programs.   A pointer  to the allocated
storage block is returned.

Usage

     dcl dm_per_system_$alloc entry (fixed bin (18), ptr);

     call dm_per_system_$alloc (n_words, block_ptr);

where:

       n_words                      (Input)
            is the number of words to be allocated.

       block_ptr                    (Output)
            is the  location of the  allocated block, or  null if
            the block could not be allocated.

______________                                     ______________

dm_per_system_                                     dm_per_system_
______________                                     ______________

Entry:  dm_per_system_$cleanup

          Cleans up after dm_per_system_$init  if that entry does
not   complete.   This   is  the   normal  cleanup   handler  for
dm_initializer_.

Usage

     dcl dm_per_system_$cleanup entry ();

     call dm_per_system_$cleanup ();

______________                                     ______________

dm_per_system_                                     dm_per_system_
______________                                     ______________

Entry:  dm_per_system_$create

          Creates a named segment in the per-bootload directory,
initiating it, and returning a pointer to the base of the
segment.

Usage

     dcl dm_per_system_$create entry (char (*), ptr, fixed
          bin(35));

     call dm_per_system_$create (seg_name, seg_ptr);

where:

       seg_name                     (Input)
            is  the  name  of  the  segment  to  be  created  and
            initiated.

       seg_ptr                      (Output)
            is a pointer to the newly created segment, or null if
            the segment could not be created.

______________                                     ______________

dm_per_system_                                     dm_per_system_
______________                                     ______________

Entry:  dm_per_system_$enable

          Enables  the use  of a  Data Management  system for the
curr  AIM  authorization by  general  use.  All  other per-system
initialization should be done by  the DM Daemon before this entry
is used.  The initialization per-bootload directory is renamed so
other DM subsystems can find  it.  Normally, this entry is called
only by dm_initializer_.

Usage

     dcl dm_per_system_$enable entry (fixed bin (71));

     call dm_per_system_$enable (initializer_event_channel);

where:

       initializer_event_channel    (Input)
            is the event channel used  to communicate with the DM
            Daemon process initializing the current DM system.

______________                                     ______________

dm_per_system_                                     dm_per_system_
______________                                     ______________

Entry:  dm_per_system_$init

          Creates   the  per-bootload   directory  for   the  AIM
authorization   of   the  invoking   process   with  a   name  of
dm_dir.[substr   [request_id   |[system   date_time_last_up]]   1
10].init   so   it  is   only   accessible  to   Data  Management
initialization programs.  This entry also creates and initializes
dm_system_data_.   If  a   valid  per-bootload  directory  exists
without  an owning  DM Daemon,  the current  Daemon process takes
over the running DM system.   Normally, this entry is called only
by dm_initializer_ from a DM Daemon process.

Usage

     dcl dm_per_system_$init entry (fixed bin (71)) returns (char
          (4) aligned);

     current_dm_status = dm_per_system_$init
          (initializer_event_channel);

where:

       initializer_event_channel    (Input)
            is  the ipc_  event channel used  to communicate with
            the DM Daemon.  This is only used if the initializing
            process takes  over a running,  valid Data Management
            system.

       current_dm_status            (Output)
            is  the  status of  the  Data Management  system upon
            return  of  the  call.    It  may  be  the  following
            constants    (defined    in    dm_statuses.incl.pl1):
            DM_STATUS_RUNNING,  indicating  that  a  running Data
            Management     system    was     taken    over;    or
            DM_STATUS_INITIALIZING,  indicating that  the rest of
            per-system initialization must be done.

______________                                     ______________

dm_per_system_                                     dm_per_system_
______________                                     ______________

Entry:  dm_per_system_$initiate

          Initiates  a segment  in the  per-bootload directory of
the current DM system.  Normally, such  a segment is created by a
call to dm_per_system_$create.

Usage

     dcl dm_per_system_$initiate entry (char (*), char (*), ptr);

     call dm_per_system_$initiate (seg_name, ref_name, seg_ptr);

where:

       seg_name                     (Input)
            is the name of the segment to be initiated.

       ref_name                     (Input)
            is the reference name desired.  It may be null.

       seg_ptr                      (Output)
            is a pointer to the initiated segment, or is the null
            pointer if the segment could not be initiated.



                          ATTACHMENT 1

           PER-SYSTEM AND PER-AIM AUTHORIZATION TABLES

                  (in per-system DM Directory)

                 +-----------------------------+
System           |          . . . . .          |
                 +-----------------------------+
Control          | AIM Auth  |  Directory Name | ------>-----
                 +-----------------------------+            |
Segment          |          . . . . .          |            |
                 +-----------------------------+            |
                                                            |v
                                                            |
                                                            |
                 +-----------------------------+            |
                 | Per-Authorization Directory | <----------
                 +-----------------------------+
                  |v      |      |      |      |v
+--------------------+   |      |      |   +--------------------+
| Configuration file |   |      |      |   | System & Lock Logs |
+--------------------+   |      |      |   +--------------------+
                         |v      |      |v
     +----------------------+   |   +----------------------+
     | Command Msg. Segment |   |   | Def. Before Journal* |
     +----------------------+   |   +----------------------+
                                |v
                 +-----------------------------+
        ----<---- |  dm_dir.{system_boot_time}  | -->--
       |         +-----------------------------+     |
       |              |             |                |
       |v              |v             |v                |v
 +-----------+   +---------+   +--------+   +------------------+
 | Protected |   | Before  |   |  Lock  |   | dm_system_data_  |
 |   File    |   | Journal |   | Tables |   |    (with non-    |
 |  Tables   |   | Tables  |   |        |   | extensible area) |
 +-----------+   +---------+   +--------+   +------------------+

*    Note the Default Before Journal may be placed anywhere on the system
as long as it does not violate the rules of AIM.  The location shown is
the default location.