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.