1 03/15/85  before_journal_manager_
  2 
  3 
  4 The before_journal_manager_ subroutine provides the means to
  5 manipulate, and obtain information about, before journals.  Before
  6 journals are used to store before images of protected data management
  7 (DM) files, for the purpose of rolling back modifications to these
  8 files in the event of failure.
  9 
 10 
 11 Entry points in before_journal_manager_:
 12    (List is generated by the help command)
 13 
 14 
 15 :Entry:  close_bj:  03/15/85 before_journal_manager_$close_bj
 16 
 17 
 18 Function:  This entry point closes the specified before journal, making
 19 it unavailable to the current process.  A journal can be opened more
 20 than once in a process, in which case the same opening id is returned
 21 for each open request.  In that case, the close operation merely
 22 decreases by one the number of journal openings in the process.  If a
 23 close_bj request is issued by a process on a journal while the process
 24 still has an active transaction in that journal, the journal cannot be
 25 closed and an error code is returned to the caller.  If the journal to
 26 be closed was the default before journal for the process, the before
 27 journal which was last opened in the process (if any) becomes the
 28 default before journal (see "Notes" under the set_default_bj entry).
 29 
 30 
 31 Syntax:
 32 declare before_journal_manager_$close_bj entry (bit(36) aligned, fixed
 33      bin(35));
 34 call before_journal_manager_$close_bj (bj_opening_id, code);
 35 
 36 
 37 Arguments:
 38 bj_opening_id
 39    is the opening identifier of the before journal.  (Input)
 40 code
 41    is a standard system error code.  (Output)
 42 
 43 
 44 :Entry:  create_bj:  03/15/85 before_journal_manager_$create_bj
 45 
 46 
 47 Function:  This entry point creates a before journal file as specified
 48 by the input arguments.
 49 
 50 
 51 Syntax:
 52 declare before_journal_manager_$create_bj entry (char(*), char(*),
 53      fixed bin, fixed bin, fixed bin(35));
 54 call before_journal_manager_$create_bj (dir_name, entry_name,
 55      n_control_intervals, control_interval_size, code);
 56 
 57 
 58 Arguments:
 59 dir_name
 60    is the pathname of the directory in which the before journal is to
 61    be created.  (Input)
 62 entry_name
 63    is the entry name of the before journal to be created.  The .bj
 64    suffix must be included.  (Input)
 65 n_control_intervals
 66    is the size of the journal expressed in the number of control
 67    intervals.  (Input) A before journal is a circular file; when
 68    information is no longer useful (i.e., before images for committed
 69    or aborted transactions), it will be overwritten, allowing the space
 70    to be reused.  In estimating the size of a journal, you should
 71    consider the number of transactions to be using the journal
 72    simultaneously, as well as their profiles, i.e., their length in
 73    time and the rate at which they modify data, to optimize
 74    performance.
 75 
 76 
 77 control_interval_size
 78    is the size of the before journal control interval in number of
 79    bytes.  (Input) The size is currently fixed at 4096.
 80 code
 81    is a standard system error code.  (Output)
 82 
 83 
 84 :Entry: get_bj_path_from_oid: 03/15/85 before_journal_manager_$get_bj_path_from_oid
 85 
 86 
 87 Function:  This entry point returns the directory pathname and the
 88 entry name of the specified before journal.  For this operation to be
 89 successful, the before journal must be open in the current process.
 90 
 91 If a zero code is returned, the operation is successful and the
 92 dir_name and entry_name arguments are set to the proper values.  If a
 93 nonzero code is returned, the operation did not succeed and the values
 94 of dir_name and entry_name are left unchanged.
 95 
 96 
 97 Syntax:
 98 declare before_journal_manager_$get_bj_path_from_oid entry (bit(36)
 99      aligned, char(*), char(*), fixed bin(35));
100 call before_journal_manager_$get_bj_path (bj_oid, dir_name, entry_name,
101      code);
102 
103 
104 Arguments:
105 bj_oid
106    is the opening identifier of the before journal for which the
107    pathname is requested.  (Input)
108 dir_name
109    is the pathname of the directory in which the before journal
110    resides.  (Output)
111 entry_name
112    is the entry name of the before journal.  (Output)
113 code
114    is a standard system error code.  (Output)
115 
116 
117 :Entry: get_default_bj: 03/15/85 before_journal_manager_$get_default_bj
118 
119 
120 Function:  This entry point returns the opening identifier of the
121 before journal to be used as the default in those cases where a before
122 journal specification is expected but not supplied.  The rules for
123 determining this default before journal are described in "Notes" under
124 the set_default_bj entry point.  If the journal which is to serve as
125 the default before journal is not open at the time of this call, it is
126 opened automatically.
127 
128 
129 Syntax:
130 declare before_journal_manager_$get_default_bj entry (bit(36) aligned,
131      fixed bin(35));
132 call before_journal_manager_$get_default_bj (bj_oid, code);
133 
134 
135 Arguments:
136 bj_oid
137    is the opening identifier of the current default before journal.
138    (Output)
139 code
140    is a standard system error code.  (Output)
141 
142 
143 :Entry:  open_bj:  03/15/85 before_journal_manager_$open_bj
144 
145 
146 Function:  This entry point makes the before journal specified by the
147 pathname, ready for use by any transaction of the current process.  A
148 process may have several before journals open at the same time, and may
149 also have the same journal opened more than one time.  When a
150 transaction is started, one of the open journals must be associated
151 with the transaction, if the transaction needs a before journal.  One
152 can expect that in most cases, a process will open only one before
153 journal, which will be used by all its transactions.
154 
155 This entry may also change the default before journal for the process
156 to the newly opened journal (see "Notes" under set_default_bj).
157 
158 
159 Syntax:
160 declare before_journal_manager_$open_bj entry (char(*), char(*),
161      bit(36) aligned, fixed bin(35));
162 call before_journal_manager_$open_bj (dir_name, entry_name,
163      bj_opening_id, code);
164 
165 
166 Arguments:
167 dir_name
168    is the pathname of the directory in which the before journal to be
169    opened resides.  (Input)
170 entry_name
171    is the entry name of the before journal to be opened.  The .bj
172    suffix must be included (Input)
173 bj_opening_id
174    is the opening identifier of the journal.  (Output) This specifier
175    must be used subsequently by the current process to identify this
176    journal.
177 code
178    is a standard system error code.  (Output)
179 
180 
181 Notes:  When a before journal is opened, it is remembered in a per
182 system table containing the pathnames and unique identifiers of all
183 before journals opened in the system.  This table is used after a
184 system crash to determine which journals must be reopened and examined
185 in order to perform a rollback operation.  To preserve the integrity of
186 this table, it is written out to disk automatically each time it is
187 updated with a newly opened journal.
188 
189 If a process opens the same before journal more than one time, the
190 opening identifier received from the open_bj will be the same for each
191 call.  The process must close a before journal the same number of times
192 it opens it, to render the journal inaccessible through the same
193 opening identifier.
194 
195 
196 :Entry:  set_default_bj:  03/15/85 before_journal_manager_$set_default_bj
197 
198 
199 Function:  This entry point causes the specified before journal to
200 become the default before journal.  When no before journal is
201 explicitly specified by the user at the beginning of a transaction, the
202 default before journal for the process will be assigned to the
203 transaction.  The default before journal must be one of the before
204 journals open in the process.
205 
206 
207 Syntax:
208 declare before_journal_manager_$set_default_bj entry (bit(36) aligned,
209      fixed bin(35));
210 call before_journal_manager_$set_default_bj (bj_opening_id, code);
211 
212 
213 Arguments:
214 bj_opening_id
215    is the opening identifier of the before journal.  (Input)
216 code
217    is a standard system error code.  (Output)
218 
219 
220 Notes:  Several before_journal_manager_ entries expect an opening id to
221 specify which before journal to use.  If bj_opening_id is null, the
222 following default assignments are attempted, in the order in which they
223 are mentioned below, until one of them succeeds:
224 
225 The current default before journal in this process, if there is
226 one; otherwise,
227 
228 The most recently open before journal among those that are still
229 open, if there is one; otherwise,
230 
231 The system before journal.  If the system before journal has not
232 been opened yet in the current process, it is automatically
233 opened.
234 
235 
236 :Entry: set_transaction_storage_limit: 03/15/85 before_journal_manager_$set_transaction_storage_limit
237 
238 
239 Syntax:
240 declare before_journal_manager_$set_transaction_storage_limit entry
241     (char (*), char(*), fixed bin (35), fixed bin (35));
242 call before_journal_manager_$set_transaction_storage_limit (dir_name,
243      entryname, storage_limit, code);
244 
245 
246 Arguments:
247 dir_name
248    is the pathname of the containing directory.  (Input)
249 entryname
250    is the entryname of the before journal.  (Input)
251 storage_limit
252    is the maximum number of bytes a single transaction may use in the
253    before journal.
254 code
255    is a storage system status code.  (Output)