Multics Technical Bulletin                                MTB-561
DM: After Journal Spec

To:       Distribution

From:     Jeffrey D. Ives

Date:     02/11/82

Subject:  Data Management: After Journal Manager Specifications

1 ABSTRACT

     This document describes the  functions provided by the After
Journal Manager.   For each of these  functions, a description of
what  the  function  accomplishes,  and what  the  caller  of the
function is  supposed to know  is given.  The  description of how
the function accomplishes  its task is not part  of this document
and  will  be the  purpose  of the  After Journal  Manager design
document (MTB 562).

Comments should be sent to the author:

via Multics Mail:
   Ives.Multics on either MIT Multics or System M.

via US Mail:
   Jeffrey D. Ives
   Honeywell Information Systems, inc.
   575 Tech Square
   Cambridge, Massachusetts 02139

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

_________________________________________________________________

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 Design Decisions . . . . . . . . . .     1
                    3.1 Protected Page Files  . . . . .     1
                    3.2 Data Base Dumping . . . . . . .     2
                    3.3 Relation to Before Journals . .     2
                    3.4 After Journal Structure . . . .     3
                    3.5 Media Supported . . . . . . . .     3
                    3.6 Logical vs Physical . . . . . .     3
                 4 After Journal Manager Primitives . .     4
                    ajmgr_  . . . . . . . . . . . . . .     5
                       $create_aj . . . . . . . . . . .     6
                       $delete_aj . . . . . . . . . . .     8
                       $open_aj . . . . . . . . . . . .     9
                       $close_aj  . . . . . . . . . . .    10
                       $assign_pf . . . . . . . . . . .    11
                       $deassign_pf . . . . . . . . . .    13
                       $list_assigned_files . . . . . .    14
                       $write_after_image . . . . . . .    15
                          The ci_parts structure  . . .    16
                       $write_rollforward_handler . . .    17
                       $write_begin_dump_mark . . . . .    18
                       $write_end_dump_mark . . . . . .    19
                       $flush_transaction . . . . . . .    20
                       $rollforward . . . . . . . . . .    21
                       Notes on Rollforward . . . . . .    22
                       $truncate_aj . . . . . . . . . .    23
                       $synchronize_with_bj . . . . . .    24

Multics Technical Bulletin                                MTB-561
DM: After Journal Spec

2 INTRODUCTION

     The purpose of the after journal  is to keep a record of all
modifications done  to a protected  file, in such a  way that the
modifications  can  be redone  if the  file is  lost and  must be
reloaded  from  the latest  dump.   In the  context of  the after
journal,  redoing  modifications   is  called  "rolling  forward"
because  of  its analogy  with  the before  journal  operation of
rolling back the effects of aborted transactions.

     The  after  journal  is   manipulated  by  a  collection  of
procedures which make up the  After Journal Manager.  Among these
procedures, some are used internally by the After Journal Manager
itself to perform  its job, and are of no  interest in this memo.
Some other procedures  are used by the various  components of the
Data Management Architecture and  represent the primitives of the
After Journal Manager, i.e., the interface presented by the After
Journal Manager to the rest of  the system.  It is the purpose of
this memo to describe these primitives.

     This  document  resembles the  before  journal specification
(MTB-559), written by Andre Bensoussan, because it was created by
extensively  editing  that  document  in order  to  keep  the two
journal managers as similar to each other as possible.

3 DESIGN DECISIONS

     Some   design  decisions   have  been   made  regarding  the
relationships between after journals and  the rest of the system.
It is  useful to describe  these decisions before  going into the
details of the after journal operations.

3.1 Protected Page Files

     The main  philosophy behind the design  of the after journal
(as well as the before journal) is that most modifications can be
represented  as  overwrites  of  specific  areas  of  the control
intervals of which  files are made.  This concept  is very simple
to understand and  has the property that the  modification can be
redone any number of times with the same effect.  Furthermore, if
the modification is interrupted, it  can either be redone by just
starting over, or  undone by restoring all of  the areas to their
original values.   For modifications that can  not be represented
in this way, like file creation, a more general representation is
provided in the form of an arbitrary entry point to be called and
data to be passed to it.


MTB-561                                Multics Technical Bulletin
                                           DM: After Journal Spec

     Protecting  a  file  means  several things.   It  means that
transactions  that  access the  file will  be isolated  from each
other  by locking  at the control  interval level  or higher.  It
means that before modified control intervals are written to disk,
the  information  necessary  to  undo the  modifications  will be
written  to  disk in  the before  image journal  so that,  if the
transaction can not be completed,  its effects can be erased from
the  files  that  it modified.   It  means  that when  a  file is
modified,  the  modification  is  journalized in  an  after image
journal  so  that, if  the  file should  be rendered  unusable by
hardware  failure,  human error,  or  an act  of  God, it  can be
reloaded from the latest dump and reposted with the modifications
recorded in the after image  journal.  The kinds of protection to
be used  for a particular  file are attributes of  the file which
must be specified when it is created and may be changed later.

     The entire system may use  one or several after journals.  A
given  process may  use one or  several after  journals.  A given
transaction may use one or  several after journals.  A given file
may only use one after journal.   The after journal to be used by
a file must be specified when creating the protected file or when
changing the attributes of a file from unprotected to protected.

3.2 Data Base Dumping

     An  after image  journal is  useless without  a dump  of the
files.  The  Multics data management system  data base dumper has
neither   been  specified   nor  designed.   When   it  is,  this
specification  will  be  modified   as  required  to  accommodate
dumping.

     The requirements  of dumping are anticipated  in the current
specification by  providing primitives to record  "dump marks" on
the journal.   A "begin dump  mark" will signal  the beginning of
the dumping of  a set of files.  The mark  will contain a list of
the files that are to be  dumped, and will probably coincide with
a  quiescence of  these files.   It may  also contain identifying
information necessary to locate the dump  when it is needed for a
roll forward.  The "end dump  mark" will signal the completion of
the  dumping  and will  also  be written  only after  the journal
manager has quiesced the files  by obtaining an exclusive lock on
all that were dumped.

3.3 Relation to Before Journals

     When  a transaction  can not  be completed,  its effects are
undone by the Before Journal Manager by writing the before images
back to the control intervals of  the files that were modified by


Multics Technical Bulletin                                MTB-561
DM: After Journal Spec

the  transaction.   These  modifications,  like  all  others, are
journalized  in the  after image journals.   During roll forward,
aborted transactions are  done and undone by the  after images in
the journal  and not by  any explicit action of  the roll forward
mechanism.

     After a  crash, the before journals  and after journals must
be  synchronized to  the extent  that there  are no  after images
without  corresponding  before  images.    This  is  achieved  by
deleting after images  that do not or may  not have before images
that were written to disk before  the crash.  There is no harm in
deleting after images that have before images, but there is great
harm in not deleting after  images that don't have before images.
After  images  associated with  committed transactions  are never
deleted.

3.4 After Journal Structure

     An  after journal  is implemented as  a file  managed by the
standard  File Manager.   It is  accessed through  a special high
performance, low  functionality Record Manager that  is shared by
the  Before  and  After  journal Managers.   The  journal  may be
composed of a number of volumes  of whatever medium it is on.  At
the beginning of each volume there will be a record that contains
a  list  of all  the  files that  are  presently assigned  to the
journal  for protection.   Every time  a file  is assigned  to or
deassigned  from the  journal, a  record will  be written  on the
journal to this effect.  By this method, it is always possible to
determine which  files are assigned  to the journal  at any point
during a roll forward of the journal.

3.5 Media Supported

     Eventually, journals  will be on  either disk or  tape.  The
current File  Manager has no tape  capability.  Nevertheless, the
After  Journal  Manager  is  designed so  that  it  only requires
sequential access to the  medium.  Tape journalization on Multics
requires that multiple processes share a tape.  This will require
an extension to the capabilities of the Multics tape software.

3.6 Logical vs Physical

     When a  component of the data  management architecture calls
upon  the After  Journal Manager  and requests  that a  record be
appended to the journal, the following scenario usually happens:

   o The After Journal Manager logically writes the record in the


MTB-561                                Multics Technical Bulletin
                                           DM: After Journal Spec

     journal but does  not force the new record  to disk or tape.
     This step is referred to as logical journalization.

   o The  After  Journal Manager  returns to  its caller  with no
     guarantee that the new record is on disk or tape yet.

   o Some time later the record  is physically written to disk or
     tape, causing the physical journalization of the record.

The reason for not doing physical journalization before returning
to  the  caller is  to save  I/O's and  waiting time.   There are
cases, however, where the caller needs to wait until the physical
journalization is completed.  The  After Journal Manager provides
for this synchronization function.

4 AFTER JOURNAL MANAGER PRIMITIVES

     All After  Journal Manager primitives are  provided as entry
points in the ajmgr_ module.

______                                                     ______

ajmgr_                                                     ajmgr_
______                                                     ______

Name:  ajmgr_

     The ajmgr_  module provides one  entry point for  each After
Journal  Manager primitive.   The list  of these  entry points is
given  below and  is followed by  a detailed  description of what
each of them does.

     o  create_aj
     o  delete_aj
     o  open_aj
     o  close_aj

     o  assign_pf
     o  deassign_pf
     o  list_assigned_files

     o  write_after_image
     o  write_rollforward_handler
     o  write_begin_dump_mark
     o  write_end_dump_mark

     o  flush_transaction
     o  rollforward
     o  truncate_aj
     o  synchronize_with_bj

______                                                     ______

ajmgr_                                                     ajmgr_
______                                                     ______

Entry:  ajmgr_$create_aj

     This function  creates an after journal  as specified by the
input arguments.

Usage

dcl ajmgr_$create_aj entry (char(), char(), fixed bin(35), fixed
     bin(35), fixed bin(35));

call ajmgr_$create_aj (aj_path, aj_medium, maximum_size,
     control_interval_size, code);

where:

aj_path                      (Input)
   is the  path name of the  journal to be created.   This is the
   name  given to  the File Manager  in order to  create the file
   that is the journal.

aj_medium                    (Input)
   is  the kind  of recording medium  to be used  by the journal.
   During   phase   I   the   only  medium   supported   will  be
   "disk_page_file".   Tape  journaling  will  be  specified  and
   implemented  during  phase II.   The  other arguments  to this
   command will then be documented  and interpreted in a way that
   is appropriate for tape.

maximum_size                 (Input)
   is the maximum size of the journal expressed in 1K (1024 word)
   units.  This  limits the size  of the journal  file.  Space in
   the journal can be reused when the files that it protects have
   been dumped.  In evaluating the maximum size of a journal, the
   creator must take  into account the number of  files that will
   be  using the  journal, as  well as  the frequency  with which
   these page files are dumped.

control_interval_size        (Input)
   is the size  of the control interval in  one-word sized units.
   The  size  is important  for  tuning purposes.   If it  is too
   small, it may cause the number  of I/O's for the journal to be
   too high.  If it is too large,  it may cause too much space in
   the  journal to  be wasted when  control intervals  need to be
   physically written while they are  not full.  The "right" size
   for the control interval depends on the number of transactions
   using  the journal,  on the rate  at which  they produce after
   images and on the rate at which they commit.  There is no good
   size a priori, and metering  will be available to determine if
   the size is adequate.  If no  size is specified by the caller,

______                                                     ______

ajmgr_                                                     ajmgr_
______                                                     ______

   1K will be chosen by default.

code                         (Output)
   is a standard system error code.

______                                                     ______

ajmgr_                                                     ajmgr_
______                                                     ______

Entry:  ajmgr_$delete_aj

     This function deletes an after journal specified by its path
name.   If the  journal has  any files  still assigned  to it, an
error code is returned and the journal is not deleted.

Usage

dcl ajmgr_$delete_aj entry (char(), fixed bin(35));

call ajmgr_$delete_aj (aj_path, code);

where:

aj_path                      (Input)
   is the  path name of the  journal to be created.   This is the
   name  given to  the File Manager  in order to  create the file
   that is the journal.

code                         (Output)
   is a standard system error code.

______                                                     ______

ajmgr_                                                     ajmgr_
______                                                     ______

Entry:  ajmgr_$open_aj

     This function makes the after  journal specified by the path
name ready for use by the  current process.  If the journal needs
a disk  or tape which  is not mounted, this  function may request
that it  be mounted or may  return an error code.   A process may
have several after journals open at the same time.

     Opening a  journal causes a  system table of  all open after
journals to  be updated.  This  table is used  in the event  of a
crash  by  the recovery  procedures in  order to  determine which
after journals were  open in at least one process  at the time of
the crash.  The table itself will be either a protected file or a
segment  that  is  carefully  updated  and  flushed  after  every
modification.  It may contain a list  for each journal of all the
processes that have it open.

Usage

dcl ajmgr_$open_aj entry (char(), fixed bin(35), bit(1), fixed
     bin(35));

call ajmgr_$open_aj (aj_path, aj_oid, do_not_mount_flag, code);

where:

aj_path                      (Input)
   is the path name of the after journal to be opened.

aj_oid                       (Output)
   is the opening identifier of the journal.  This specifier must
   be used  subsequently by the current  process to identify this
   journal.

do_not_mount_flag            (Input)
   is a bit  which, if ON, indicates that an  error code is to be
   returned if the  journal is on an unmounted  disk or tape.  If
   OFF, the open_aj entry requests the operator to mount the disk
   or tape.

code                         (Output)
   is a standard system error code.

______                                                     ______

ajmgr_                                                     ajmgr_
______                                                     ______

Entry:  ajmgr_$close_aj

     This  function  closes the  after  journal specified  by its
opening identifier in the current process.  Upon return from this
call  the  current process  cannot use  this journal  any longer,
unless  it  opens  it  again.   If the  request  is  issued  by a
transaction in  progress which has used  this particular journal,
the journal cannot be closed and an error code is returned to the
caller.  This entry point will also remove the process identifier
of this process from the list of processes that have this journal
open in the system table of open after journals.

Usage

dcl ajmgr_$close_aj entry (fixed bin(35), fixed bin(35));

call ajmgr_$close_aj (aj_oid, code);

where:

aj_oid                       (Input)
   is  the  opening  identifier  of the  after  journal.   If the
   opening identifier is -1, all after journals are closed.

code                         (Output)
   is a standard system error code.

______                                                     ______

ajmgr_                                                     ajmgr_
______                                                     ______

Entry:  ajmgr_$assign_pf

     This function is to be called by the File Manager when it is
creating  a  protected file,  changing  the file  attributes from
unprotected  to protected,  or reassigning a  protected file from
one journal  to another.  It establishes  the association between
the protected page  file and the after image  journal which is to
be used to protect it.  Journal management maintains an inventory
of the files assigned to a journal.  The inventory is stored in a
segment that is  carefully managed in such a way  that it can not
be  damaged by  a process  that aborts  while updating  it.  This
inventory is recorded in the journal header whenever it is stored
(such as at the beginning of each reel of tape or periodically if
the  journal  is a  disk file).   The inventories  help determine
which  journals must  be used  to recover  which protected files.
This entry point only makes the connection from the journal side,
the File Manager must also maintain a record of this assignment.

     The segment copy  of the inventory is not  relied on after a
crash.  Instead, when  a file is assigned to  an after journal, a
special "assign" mark  is placed in the journal.   The mark gives
the path name  and unique identifier of the  file being assigned.
After  a crash,  the journal header  is read.   It designates the
place in  the journal that was  the end when it  was written.  By
scanning from this  point forward to the end  of the journal, the
segment  copy  of  the  inventory  can  be  reconstructed.   This
involves only a little extra work, because the scanning must take
place anyway in order to find  the last control interval that was
written before the crash.

     In order to call this entry point, the journal must be open.
Also, the file  to be assigned must be  locked in exclusive mode.
Furthermore, if the file is not empty and has not been dumped, it
must be dumped.

Usage

dcl ajmgr_$assign_pf entry (fixed bin(35), char(), fixed bin(35),
     fixed bin(35));

call ajmgr_$assign_pf (aj_oid, file_path, file_uid, code);

where:

aj_oid                       (Input)
   is the number that was returned by ajmgr_$open_aj.

file_path                    (Input)
   is the path name of the file that is to be protected.

______                                                     ______

ajmgr_                                                     ajmgr_
______                                                     ______

file_uid                     (Input)
   is the unique identifier of the file.  this identifier will be
   included  with  every  after  image  record  produced  by  the
   protected file.

code                         (Output)
   is a standard system error code.

______                                                     ______

ajmgr_                                                     ajmgr_
______                                                     ______

Entry:  ajmgr_$deassign_pf

     This  entry point  is to be  called by File  Manager when it
deletes  a protected  file, reassigns  it to  another journal, or
changes  its  attributes  from   protected  to  unprotected.   It
terminates the association between  the specified journal and the
specified file.   This is a  unilateral termination, in  that the
File Manager also maintains a  copy of this association; and this
entry  point only  terminates the association  from the journal's
viewpoint.   The  File Manager  is  responsible for  breaking the
connection from the file side.

     Calling this  entry point causes  a "deassigned" mark  to be
written on the  after journal.  The file is  not actually deleted
from  the  inventory,  since  it may  be  needed  for rollforward
purposes.  Instead, it is marked as having been deassigned.  When
that portion  of the after  journal (during which  the assignment
lived) is deleted,  the inventory entry is also  deleted.  When a
file is assigned  to a journal, a new entry  is always created in
the inventory.  Thus, there may be several deassigned entries for
the same page file.  Before calling this entry point, the journal
must be  opened.  This entry  point obtains an  exclusive lock on
the file before deassigning it.  This is to insure that there are
no transactions in progress during the deassingment.

Usage

dcl ajmgr_$deassign_pf entry (fixed bin(35), fixed bin(35), fixed
     bin(35));

call ajmgr_$deassign_pf (aj_oid, file_uid, code);

where:

aj_oid                       (Input)
   is the number returned by ajmgr_$open_aj.

file_uid                     (Input)
   is the unique identifier of the file to be deassigned.

code                         (Output)
   is a standard system error code.

______                                                     ______

ajmgr_                                                     ajmgr_
______                                                     ______

Entry:  ajmgr_$list_assigned_files

     This  entry   point  returns  the  path   names  and  unique
identifiers  of  all protected  files  that are  assigned  to the
specified journal.  This information is obtained from the journal
inventory.  It can be used  for reports, for consistency checking
between  the File  Manager and the  After Journal  Manager, or to
determine what  protected files need to  be deleted or reassigned
in  order  to  delete the  journal.   The path  names  and unique
identifiers  are returned  one at  a time  in order  of ascending
unique  identifier.  The  sequence of ascension  is determined by
treating the unique identifier as an unsigned 36 bit number.

Usage

dcl ajmgr_$list_assigned_files entry (fixed bin(35), char(),
     fixed bin(35), fixed bin(35));

call ajmgr_$list_assigned_files (aj_oid, file_path, file_uid,
     code);

where:

aj_oid                       (Input)
   is the number returned by ajmgr_$open_aj.

file_path                    (Output)
   is the absolute  path name of the protected  file.  It will be
   left adjusted and padded with blanks.

file_uid                     (Input/Output)
   is the unique file identifier.   Initially, this should be set
   to 0.   Subsequently, it should  be the value  returned by the
   previous call.  When there are no more, this parameter will be
   set to 0.

   Warning:   this entry  point considers negative  numbers to be
   higher than positive numbers, with -1 the highest of all.

code                         (Output)
   is a standard system error code.

______                                                     ______

ajmgr_                                                     ajmgr_
______                                                     ______

Entry:  ajmgr_$write_after_image

     This function is called by  the File Manager after modifying
a  control  interval  of a  protected  file.  It  records  in the
journal the values of those portions of the control interval that
were  modified.   This  information  is used  by  the rollforward
mechanism to redo the modification.

Usage

dcl ajmgr_$write_after_image entry (fixed bin(35), fixed bin(35),
     fixed bin(35), fixed bin(35), fixed bin(24), ptr, fixed
     bin(35));

call ajmgr_$write_after_image (aj_oid, txn_id, txn_ix, file_uid,
     ci_number, ci_parts_ptr, code);

where:

aj_oid                       (Input)
   is the number returned by ajmgr_$open_aj.

txn_id                       (Input)
   is the transaction id.

txn_ix                       (Input)
   is the transaction index in the transaction table.

file_uid                     (Input)
   is the  unique identifier of  the file being  modified.  It is
   written in the after journal as part of the after image record
   and is used by the rollforward procedure to determine the file
   in which the modification has to be redone.

ci_number                    (Input)
   is  the   number  of  the   control  interval  in   which  the
   modification  was done.   It is  stored as  part of  the after
   image.

ci_parts_ptr                 (Input)
   is a pointer to a structure array describing what parts of the
   control  interval  have  been   modified,  in  order  for  the
   rollforward  procedure to  be able to  redo the modifications.
   Each  element of  the list  consists of  an offset  and length
   delimiting the part of the  control interval, and a pointer to
   its new value.  This list is stored in the after image record,
   after replacing the pointers by the values they point to.  The
   structure ci_parts is also used by the Before Journal Manager.

______                                                     ______

ajmgr_                                                     ajmgr_
______                                                     ______

code                         (Output)
   is a standard system error code.

The ci_parts structure

The  structure defines  the parts  of a  control interval  and is
declared in dm_ci_parts.incl.pl1.

dcl  1 ci_parts               aligned based (ci_parts_ptr),
       2 number_of_parts      fixed bin,
       2 part                 (cip_number_of_parts
                               refer (ci_parts.number_of_parts)),
         3 offset_in_bytes    fixed bin,
         3 length_in_bytes    fixed bin,
         3 local_ptr          ptr;

where:

number_of_parts
   is the number of parts.  Zero  is legal and there is currently
   no limit on the number of parts.

offset_in_bytes
   is the  offset of the  part within the  addressable portion of
   the control  interval.  It is  the zero relative  index of the
   first byte of the part.  It is the number of bytes that are to
   be  skipped,  starting  at  the beginning  of  the addressable
   portion.

   The addressable portion of a  control interval begins with the
   first byte after  the four word header and  ends with the last
   byte  before  the two  word  trailer.  The  only  exception is
   control interval zero.  It  has a smaller addressable portion,
   because the file attributes are stored in it.

   The length of the addressable  portion is 4072 bytes.  Control
   interval zero has 3176 bytes.   Constants for these values are
   declared in dm_ci_lengths.incl.pl1.

length_in_bytes
   is the number  of bytes in the part.  If  it is zero, the part
   is ignored.

local_ptr
   is  a pointer  to the  buffer provided  by the  caller for the
   part.

______                                                     ______

ajmgr_                                                     ajmgr_
______                                                     ______

Entry:  ajmgr_$write_rollforward_handler

          It  is  not always  possible  to redo  the effect  of a
transaction by merely restoring a portion of the data base to its
after image  value.  An example is  rolling forward modifications
done by  a transaction to  a directory.  In the  presence of this
kind of situation,  after performing a function F  that cannot be
redone by  the after image mechanism,  the transaction records in
the after journal the fact that  it performed function F and that
the effect of  this function can be rolled  forward by performing
function F again.  This is  accomplished by journalizing the name
of the procedure  tailored to redo F, with  the appropriate input
information  it needs  to do  its job.   What is  recorded in the
journal is  referred to as a  "rollforward handler" record.  This
entry  point of  the After  Journal Manager  writes a rollforward
handler record  in the after  journal, according to  the caller's
specifications.

Usage

dcl ajmgr_$write_rollforward_handler entry (fixed bin(35), fixed
     bin(35), fixed bin(35), char(), bit(), fixed bin(35)");

call ajmgr_$write_rollforward_handler (aj_oid, txn_id, txn_idx,
     proc_name, info_bits, code);

where:

txn_id                       (Input)
   is the transaction identifier.

txn_idx                      (Input)
   is the transaction index in the transaction table.

proc_name                    (Input)
   is the name  of the procedure to be  called if the transaction
   has  to be  rolled forward;  this name is  of the  form "a" or
   "a$b" where  "a" is the  name of a data  management module and
   "b" the entry point in this module.

info_bits                    (Input)
   is  the  bit string  representation  of the  input information
   expected by the entry point a$b to do its job.

code                         (Output)
   is a standard system error code.

______                                                     ______

ajmgr_                                                     ajmgr_
______                                                     ______

Entry:  ajmgr_$write_begin_dump_mark

          In order  to dump files  while they are  being updated,
the Dump Manager will need a  way to designate the portion of the
after  journal  that was  written  during the  dumping.   This is
achieved with "dump  marks" that are placed on  the after journal
to delimit the "dumping phase" for a file or set of files.  Since
the  Dump Manager  has not  been specified  or designed  yet, its
requirements can  not be completely anticipated.   However, it is
safe  to say  that there  must be  a quiesce  of the  files being
dumped  at  least once  (probably at  the end  of the  dump), and
possibly twice (beginning and end).  These quiesce points will be
achieved by  obtaining an exclusive  lock on all  the files being
dumped.  Following  is a prototype  of what this  entry point may
look like.

Usage

dcl ajmgr_$write_begin_dump_mark entry (fixed bin(35), dim()
     fixed bin(35), char(), fixed bin(71), fixed bin(35));

call ajmgr_$write_begin_dump_mark (aj_oid, file_uids,
     dump_description, begin_time, code);

where:

aj_oid                       (Input)
   is the number returned by ajmgr_$open_aj.

file_uids                    (Input)
   are the file unique identifiers of the files to be dumped.  If
   any  of  the files  in  this array  are  not assigned  to this
   journal, an  error code will  be returned and no  mark will be
   written.

dump_description             (Input)
   is a character string that will  be recorded in the begin dump
   mark to designate the dump.  It may be the tape identification
   or  a path  name or  anything else  that will  help locate the
   dump.

begin_time                   (Output)
   is the time  the begin dump mark was  logically written on the
   journal.   It  can  be   used  when  calling  the  rollforward
   primitive  to designate  the point  on the  journal from which
   rollforward is to commence.

code                         (Output)
   is a standard system error code.

______                                                     ______

ajmgr_                                                     ajmgr_
______                                                     ______

Entry:  ajmgr_$write_end_dump_mark

          This  entry  point  causes  an "end  dump"  mark  to be
written on  the specified journal.  It  will probably quiesce the
specified files  before writing the mark.   The description below
is preliminary and  will be modified to suit  the requirements of
the Dump Manager.

Usage

dcl ajmgr_$write_end_dump_mark entry (fixed bin(35), dim() fixed
     bin(35), fixed bin(71), fixed bin(35));

call ajmgr_$write_end_dump_mark (aj_oid, file_uids, end_time,
     code);

where:

aj_oid                       (Input)
   is the number returned by ajmgr_$open_aj.

file_uids                    (Input)
   are the file unique identifiers of the files that were dumped.
   If any of them are not assigned to this journal, an error code
   will be returned and no mark will be written.

end_time                     (Output)
   is  the time  the end dump  mark was logically  written on the
   journal.   It  can  be   used  when  calling  the  rollforward
   primitive to designate  the point on the journal  at which the
   rollforward  is  to  stop  if  all  that  is  desired  is  the
   restoration of a consistent dump.

code                         (Output)
   is a standard system error code.

______                                                     ______

ajmgr_                                                     ajmgr_
______                                                     ______

Entry:  ajmgr_$flush_transaction

     This function  is called mainly by  the Transaction Manager,
before calling  the write_committed_mark primitive  of the Before
Journal Manager.  It initiates as  many I/O requests as necessary
to  cause  all after  journal records  produced by  the specified
transaction on all  after journals that it used  to be written to
disk or tape if they are  not already written.  If specified, the
function  returns  to its  caller  only after  all  after journal
records  for  the  transaction  are  actually  on  disk  or tape.
Otherwise, it  returns to its  caller with no  guarantee that the
initiated I/O requests are completed.  It also returns the number
of I/O's on  the journals that have yet to  be completed in order
to complete  the physical journalization of  all records produced
in the journals by the transaction.

Usage

dcl ajmgr_$flush_transaction entry (fixed bin(35), fixed bin(35),
     bit(1) aligned, fixed bin(35), fixed bin(35));

call ajmgr_$flush_transaction (txn_id, txn_ix, wait_switch,
     number_io_pending, code);

where:

txn_id                       (Input)
   is the identifier of the transaction whose after images are to
   be flushed.

txn_ix                       (Input)
   is the transaction index in the transaction table.

wait_switch                  (Input)
   is  a flag  which, if on,  indicates that the  entry will wait
   until all I/O's that it  issues are completed before returning
   to the caller.  If off, the routine will return as soon as the
   I/O's are issued, with no guarantee of their completion.

number_io_pending            (Output)
   is the  number of I/O's  on the journals  that have yet  to be
   completed in order to  complete the physical journalization of
   all records produced in the journals by the transaction.

code                         (Output)
   is a standard system error code.

______                                                     ______

ajmgr_                                                     ajmgr_
______                                                     ______

Entry:  ajmgr_$rollforward

          This  after  journal primitive  is  for use  during the
repair of damaged files.  First,  the files must be reloaded from
the latest  dump.  Then, this function  redoes modifications that
occurred  during  the  dumping  and  subsequent  modifications by
applying the after images recorded  in the after journal.  It can
not  be completely  specified at this  time, because it  is to be
used in conjunction with the Dump  Manager which has not yet been
specified   or   designed.   This   specification   represents  a
preliminary description of what this entry point will do and what
arguments it will require.

Usage

dcl ajmgr_$rollforward entry (fixed bin(35), dim() char(), fixed
     bin(71), fixed bin(71), dim() char(), fixed bin(35));

call ajmgr_$rollforward (aj_oid, file_paths, begin_time,
     end_time, vol_ids, code);

where:

aj_oid                       (Input)
   is the number returned by ajmgr_$open_aj.

file_paths                   (Input)
   is  an array  of path  names which  specifies the  files to be
   rolled forward.   Each array element  must have one  path name
   that  is left  adjusted and padded  on the  right with blanks.
   These files  will be opened  and locked in  exclusive mode for
   the duration of the rollforward.

begin_time                   (Input)
   tells the  After Journal Manager  where to start  scanning the
   journal.  If this  argument is 0, the journal  will be scanned
   from the beginning.

end_time                     (Input)
   tells the After Journal Manager where to stop rolling forward.
   If this argument is 0, the journal will be scanned to the time
   when this entry point was called.

vol_ids                      (Input)
   tells the Journal Manager to scan these volumes.  There should
   be one  volume identifier per  array element.  They  should be
   left  adjusted  and  padded  on the  right  with  blanks.  The
   volumes will be  scanned in the order given  in the array.  If
   this argument is a zero length array, the Journal Manager will

______                                                     ______

ajmgr_                                                     ajmgr_
______                                                     ______

   try  to  determing what  volumes  to use  by  consulting other
   sources.

code                         (Output)
   is a standard system error code.

Notes on Rollforward

1.   The  rollforward procedure  reads all  after journal records
     produced  for  the specified  files in  chronological order,
     starting  from  the  first  image posted  subsequent  to the
     "begin dump" mark for each file that corresponds to the dump
     from which the file has been reloaded.  Each time it reads a
     record, it performs the appropriate  action to redo what the
     transaction   did.   In   order  to   redo  the   data  base
     modifications, the rollforward procedure has to write in the
     data base.  It does so  by calling the File Manager.  Unlike
     normal   modifications,   these    modifications   are   not
     journalized in a before or after journal.

2.   First,  the  Dump Manager  is  called to  reload  the files.
     Then,  the  After  Journal  Manager is  called  to  redo the
     modifications.

3.   While these functions are  performed, other transactions may
     not be in progress on the damaged files.

4.   The rollforward  procedure returns to its  caller only after
     all files have been rolled forward.

5.   Each after  image record contains  the file unique  id.  The
     uid is used  look up the file opening id  in a list which is
     maintained during rollforward.

______                                                     ______

ajmgr_                                                     ajmgr_
______                                                     ______

Entry:  ajmgr_$truncate_aj

     This function  deletes portions of  the journal that  are no
longer needed  because the files  that the journal  protects have
been dumped subsequent to the time when the after images in these
portions were recorded.  This  is a preliminary specification and
may be changed.

Usage

dcl ajmgr_$truncate_aj entry (fixed bin(35), fixed bin(71), fixed
     bin(35));

call ajmgr_$truncate_aj (aj_oid, truncate_prior_time, code);

where:

aj_oid                       (Input)
   is the number returned by ajmgr_$open_aj.

truncate_prior_time          (Input)
   is a Multics  clock time that specifies that  all after images
   in the journal that were recorded prior to this time are to be
   deleted.

code                         (Output)
   is a standard system error code.

______                                                     ______

ajmgr_                                                     ajmgr_
______                                                     ______

Entry:  ajmgr_$synchronize_with_bj

     This function is  used after a crash to  delete after images
in the after journal that  have no corresponding before images in
the before journal.   It will be specified later  because we have
not yet chosen the synchronization method.