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.