Scan_file_i(SSM)

Shore Programmer's Manual - 2 August 96

NAME

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();
};

class append_file_i {
public:
    NORET			append_file_i(
	const lvid_t&		    lvid, 
	const serial_t& 	    fid
	);

    NORET			~append_file_i();
    
   rc_t                        create_rec(
        const vec_t&                hdr,
        smsize_t                    len_hint,
        const vec_t&                data,
        lrid_t&                     lrid); // logical id

    rc_t                        create_rec(
        const vec_t&                hdr,
        smsize_t                    len_hint,
        const vec_t&                data,
        rid_t&                      rid); // physical id

    // logical serial # and volume ID of the file if created that way
    const serial_t&		lfid() const;
    const lvid_t&		lvid() const;
   
    void			finish();
    rc_t			error_code();
};

DESCRIPTION

Each instance of scan_file_i and append_file_i keeps a record pinned (and therefore, a page fixed) throughout its existence. You must be carefully control the use of these classes in order to avoid fixing all the pages in the buffer pool and thereby causing a fatal error.

The class append_file_i is for appending records to a file (this is the only way to create records in a known place in a file).

The order in which records are visited by the scan is called the scan order. There are two guarantees about scan order.

The first guarantee is that if two scans are performed on a file, the scan orders will be identical as long as none of the following operations occur between the two scans: creatinga record in the file destroying a record in the file changing the size of a record in the file.

The second guarantee is that if a file is created using the append_file_i class, and no updates are performed on the file or any of its records, 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.

append_file_i(lvid, fid)

The arguments to append_file_i() are as described above, for the scan_file_iconstructors.

~scan_file_i() ~append_file_i()

These destructor un-pin the current record, if any, and destroys the object. To unpin the record before destroying the object, you may explicitly call finish().

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 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.

Appending to a file

Create_rec in class append_file_i appends a record to a file. It is used much the same way that the static function ss_m::create_rec is used, but appending to a file with append_file_i::create_rec is the more efficient way to populate a file if many creations are to be performed without other intervening operations on the file, and it guarantees that new records are placed at the end of the file.

ERRORS

EXAMPLES

VERSION

SPONSORSHIP

COPYRIGHT

SEE ALSO