Multics Technical Bulletin MTB-567
Before Journal Storage
To: Distribution
From: Andre Bensoussan
Date: 02/03/82
Subject: Data Management: Before Journal Storage Operations
1 ABSTRACT
This MTB is part of the Before Journal Manager Design
documents. It describes, in the format used for the MPM
documentation, the set of operations made available by the
bjmgr_storage_ module, to do storage and retrieval of logical
records in the before journal. This module is called only by the
before journal manager primitives, at journalling time, at
rollback time and at rollback after crash time.
Comments should be sent to the author:
via Multics Mail:
Bensoussan.Multics on System M.
via US Mail:
André Bensoussan
Honeywell Information Systems, inc.
4 Cambridge Center
Cambridge, Massachusetts 02142
via telephone:
(HVN) 261-9334, or
(617) 492-9334
_________________________________________________________________
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 Description of the Operations . . . 1
bjmgr_storage_ . . . . . . . . . . 1
$append . . . . . . . . . . . . 2
$flush . . . . . . . . . . . . . 3
$get . . . . . . . . . . . . . . 4
$get_prior . . . . . . . . . . . 5
$get_last . . . . . . . . . . . 6
$truncate . . . . . . . . . . . 7
Multics Technical Bulletin MTB-567
Before Journal Storage
2 DESCRIPTION OF THE OPERATIONS
Name: bjmgr_storage_
This module provides a set of operations to store and
retrieve logical records in and from a Before Journal. It does
not understand the contents of a logical record and views it
merely as a bit string. It provides the following functions:
1. Append a logical record at the end of a Before Journal and
return the record id assigned to the appended record.
2. Flush the journal to disk up to, and including, a given
logical record, with the option of waiting for I/O
completion.
3. Get the logical record specified by its record identifier
from a Before Journal.
4. Get the logical record that precedes the logical record
specified by its record id from a Before Journal, with its
record identifier.
5. Get the last logical record that was appended to a Before
Journal, with its record identifier.
6. Truncate the journal from its beginning up to, and including,
the logical record specified by its record identifier.
______________ ______________
bjmgr_storage_ bjmgr_storage_
______________ ______________
Entry: bjmgr_storage_$append
This entry appends the logical record passed by the caller to the
end of the Before Journal and returns the record identifier
associated with the record just appended.
Usage
dcl bjmgr_storage_$append entry (fixed bin (35), bit ()
varying, fixed bin (35), fixed bin (35));
call bjmgr_storage_$append (bj_oid, record, record_id,
code);
where:
bj_oid (Input)
is the before journal opening identifier of the journal in
which the record is to be appended.
record (Input)
is the bit string representation of the logical record to be
appended.
record_id (Output)
is the record identifier assigned to the appended record,
which can be used subsequently to designate this particular
record in the journal.
code (Output)
is a standard error code.
______________ ______________
bjmgr_storage_ bjmgr_storage_
______________ ______________
Entry: bjmgr_storage_$flush
This entry causes all records of the journal that may not have
been physically written to disk to be force written, up to, and
including a record specified by the caller. Depending on the
caller's request it returns either after all necessary I/O's are
initiated, or after all necessary I/O's are completed.
Usage
dcl bjmgr_storage_$flush entry (fixed bin (35), fixed bin
(35), bit(1), fixed bin (35));
call bjmgr_storage_$flush (bj_oid, record_id, wait_switch,
n_io_pending, code);
where:
bj_oid (Input)
is the opening id of the journal to be flushed.
record_id (Input)
is the record identifier of the last record to be flushed; it
specifies how far the journal has to be flushed: Records to
be flushed include the record specified by this record_id and
all records that have been appended to the journal,prior to
that record.
wait_switch (Input)
indicates whether or not the entry should wait until all I/O's
associated with the flush must be completed. If its value is
1 the entry waits, if it is 0 it does not.
n_io_pending (Output)
is the number of I/O's that are yet to be completed for the
physical journalization to be complete.
code (Output)
is a standard error code.
______________ ______________
bjmgr_storage_ bjmgr_storage_
______________ ______________
Entry: bjmgr_storage_$get
This entry retrieves the logical record specified by the caller
and returns it as a bit string. The record is specified by its
record identifier.
Usage
dcl bjmgr_storage_$get entry (fixed bin (35), fixed bin
(35), bit () varying, fixed bin (35));
call bjmgr_storage_$get (bj_oid, record_id, record, code);
where:
bj_oid (Input)
is the opening id for the journal from which to get the
record.
record_id (Input)
is the record identifier of the record to get.
record (Output)
is the record string returned to the caller in response to his
request. This bit string is the same bit string that was
passed to the append entry point of this module when this
record was appended.
code (Output)
is a standard error code.
______________ ______________
bjmgr_storage_ bjmgr_storage_
______________ ______________
Entry: bjmgr_storage_$get_prior
This entry retrieves the logical record prior to the record
specified by its record identifier; it returns the record string
and the record identifier of the record it retrieved.
Usage
dcl bjmgr_storage_$get_prior entry (fixed bin (35), fixed
bin (35), bit () varying, fixed bin (35), fixed bin
(35));
call bjmgr_storage_$get_prior (bj_oid, current_record_id,
record, record_id, code);
where:
bj_oid (Input)
is the opening id of the journal from which the record is to
be retrieved.
current_record_id (Input)
is the record identifier of the record to which the record to
be retrieved is prior.
record (Output)
is the record string of the requested record.
record_id (Output)
is the record identifier of the requested record.
code (Output)
is a standard error code.
______________ ______________
bjmgr_storage_ bjmgr_storage_
______________ ______________
Entry: bjmgr_storage_$get_last
This entry returns the record string and the record identifier of
the last record appended to the journal.
Usage
dcl bjmgr_storage_$get_last entry (fixed bin (35), fixed bin
(35), bit () varying, fixed bin (35));
call bjmgr_storage_$get_last (bj_oid, last_record_id,
last_record, code);
where:
bj_oid (Input)
is the opening id of the journal in which the last record is
to be retrieved.
last_record_id (Output)
is the record identifier of the requested record.
last_record (Output)
is the record string of the requested record.
code (Output)
is a standard error code.
______________ ______________
bjmgr_storage_ bjmgr_storage_
______________ ______________
Entry: bjmgr_storage_$truncate
This entry truncates the journal from its beginning up to, and
including, the logical record specified by the caller. The
logical record following the record specified by the caller
becomes the first logical record of the journal.
Usage
dcl bjmgr_storage_$truncate entry (fixed bin (35), fixed bin
(35), fixed bin (35));
call bjmgr_storage_$truncate (bj_oid, record_id, code);
where:
bj_oid (Input)
is the opening id of the journal to be truncated.
record_id (Input)
is the record_id specifying the last record to be truncated.
code (Output)
is a standard error code.