Scan_file_i(SSM)
Shore Programmer's Manual - 18 September 95
NAME
scan_file_i \- Class for Scanning Files in the Shore Storage Manager
SYNOPSIS
#include <sm_vas.h> // which includes scan.h
class scan_file_i {
public:
NORET scan_file_i(
const lvid_t& lvid,
const serial_t& fid,
concurrency_t cc = t_cc_file);
NORET scan_file_i(
const lvid_t& lvid,
const serial_t& fid,
const serial_t& start_rid,
concurrency_t cc = t_cc_file);
NORET ~scan_file_i();
rc_t next(
pin_i*& pin_ptr,
smsize_t start_offset,
bool& eof);
rc_t next_page(
pin_i*& pin_ptr,
smsize_t start_offset,
bool& eof);
// logical serial # and volume ID of the file if created that way
const serial_t& lfid() const;
const lvid_t& lvid() const;
void finish();
bool eof();
rc_t error_code();
};
DESCRIPTION
Class
scan_file_i
supports iterating over the records in a file.
The scan is controlled by a scan_file_i object.
Multiple scans can be open at the same time.
The order in which records are visited by the scan is called
the
scan order.
There are two guarantees about scan order. These guarantees are based
on the notion of a
size changing operation.
Size changing operations include creating or destroying records in a
file and any operation on a record that changes its size. The first
guarantee is that if two scans are performed on a file, the scan orders
will be identical as long as no intervening size changing operation has
been performed. The second guarantee is that for a file in which the
only size changing operation performed has been record creations, the
scan order is identical to the order of record creation.
Constructors and Destructors
scan_file_i(lvid, fid, cc)
scan_file_i(lvid, fid, start_rid, cc)
-
- The
scan_file_i
constructors have a number of parameters in common.
The first two parameters,
lvid
and
fid
specify the
logical ID
of the file to be scanned. The
cc
parameter specifies
concurrency control granularity. See
enum(ssm)
for a complete description of the values. Here are the
effects of all valid values for file scan:
-
- t_cc_none:
The file is IS locked, but no locks are obtained on any
pages or records in the file.
-
- t_cc_record:
The file is IS locked and records are SH locked as they
are pinned.
-
- t_cc_file:
The file is SH locked, so no finer granularity locks
are obtained.
-
- The starting location (record) of the scan can
be controlled using the optional
start_rid
parameter.
~scan_file_i()
-
- The
scan_file_i
destructor un-pins the current record, if any, and closes the scan.
Scanning
next(pin_ptr, start_offset, eof)
-
- The
next
method
is used to retrieve records from the scan and
(including the first).
A handle to the retrieved record
made available through the
pin_ptr
parameter. See
pin_i(ssm)
for information on using this handle. The
start_offset
parameter controls what part of the record to retrieve.
This parameter is passed directly to the
pin_i
constructor. The
eof
parameter will be set to
true
only when no value can be retrieved. So, if a file contains two
records and
next
has been called twice,
eof
will return
false
on the second call, and
true
on the third.
next_page(pin_ptr, start_offset, eof)
-
- The
next_page
method
advances the scan to the next disk page in the file and
returns a handle to the first record in the page.
Its parameters are identical to those of
next.
Other Member Functions
The
lfid
and
lvid
methods return the logical ID of the file being scanned.
The
finish
method un-pins the current record and closes the scan.
The
eof
method returns
true
if the end of the file has been reached.
The
error_code
method returns any error code generated by the
the scan member methods. See the
ERRORSsection for more information.
Updates While Scanning
A common question is what is the effect of changes to a file (or
its records) made by a transaction that is also scanning the file.
In general, it is safest not to change anything in the file
while scanning. Instead, a list of changes should be made during
the scan and only performed after the scan is complete.
However, there are a number of changes that can safely be made to
a file while scanning. It is safe to:
-
- Update any record in the file using
update_rec
or
update_rec_hdr.
-
- Destroy any record in the file using
destroy_rec,
including the current one (although the
pin_i
for the current record will no longer be valid.
It is also safe to change the size of records using
truncate_rec
or
append_rec
and to create new records. However, this may cause records
to be moved and therefore revisited or never visited during the
scan.
ERRORS
A scan_file_i object remembers if an error has occured while
constructing the scan or while scanning. An error that
occurs in constructing the scan (such as having a bad file ID),
can be detected by calling
error_code.
Alternatively, the error can be detected on the first call to
next
which will return the remembered error code. Therefore, if an error
occurs while constructing or scanning, repeated calls
to next will all return the first error code and no progress
will be made on the scan.
EXAMPLES
To Do.
VERSION
This manual page applies to Version 0.9.3 (Beta) of theShore software.
SPONSORSHIP
The Shore project is sponsored by the Advanced Research Project Agency, ARPA order number 018 (formerly 8230), monitored by the U.S. Army Research Laboratory under contract DAAB07-91-C-Q518.
COPYRIGHT
Copyright (c) 1994, 1995 Computer Sciences Department, University of Wisconsin -- Madison. All Rights Reserved.SEE ALSO
pin_i(ssm)
,
file(ssm)
,
scan_index_i(ssm)
,
intro(ssm)
,