scan_file_i Class Reference
[Scanning Files]

Inherits smlevel_top, and xct_dependent_t.

Inherited by append_file_i.

Inheritance diagram for scan_file_i:

[legend]Collaboration diagram for scan_file_i:

[legend]List of all members.

---

Detailed Description

Iterator over a file of records.

To iterate over the records in a file, construct an instance of this class, and use its next, next_page and eof methods to located the records in the file. The methods next and next_page return a pin_i, which lets you manipulate the record (pin it in the buffer pool while you use it). It is unwise to delete or insert records while you have a scan open on the file (in the same transaction).

 stid_t fid(1,7);
 scan_file_i scan(fid);
 pin_i*      cursor(NULL);
 bool        eof(false);
 do {
    w_rc_t rc = scan.next(cursor, 0, eof);
    if(rc.is_error()) {
       // handle error
       ...
    }
    if(eof) break;
    // handle record
    ...
    const char *body = cursor->body();
    ...
 } while (1);

Examples:

create_rec.cpp, and sort_stream.cpp.

Definition at line 437 of file scan.h.

Public Member Functions
NORET	scan_file_i (const stid_t &stid, const rid_t &start, concurrency_t cc=t_cc_file, bool prefetch=false, lock_mode_t ignored=SH)
	Construct an iterator over the given store (file).
NORET	scan_file_i (const stid_t &stid, concurrency_t cc=t_cc_file, bool prefetch=false, lock_mode_t ignored=SH)
	Construct an iterator over the given store (file).
void	cursor (pin_i *&pin_ptr, bool &eof)
	Return the pin_i that represents the scan state.
rc_t	next (pin_i *&pin_ptr, smsize_t start_offset, bool &eof)
	Advance to the next record of the file.
rc_t	next_page (pin_i *&pin_ptr, smsize_t start_offset, bool &eof)
	Advance to the first record on the next page in the file.
void	finish ()
	Free resources acquired by this iterator. Useful if you are finished with the scan but not ready to delete it.
bool	eof ()
	End of file was reached. Cursor is not usable.
const rc_t &	error_code () const
	Error code returned from last method call.
tid_t	xid () const
	ID of the transaction that created this iterator.
Public Attributes
stid_t	stid
rid_t	curr_rid
Protected Attributes
tid_t	tid
bool	_eof
w_rc_t	_error_occurred
pin_i	_cursor
lpid_t	_next_pid
concurrency_t	_cc
lock_mode_t	_page_lock_mode
lock_mode_t	_rec_lock_mode

---

Constructor & Destructor Documentation

NORET scan_file_i::scan_file_i	(	const stid_t &	stid,
		const rid_t &	start,
		concurrency_t	cc = t_cc_file,
		bool	prefetch = false,
		lock_mode_t	ignored = SH
	)

Construct an iterator over the given store (file).

Parameters:

[in]	stid	ID of the file over which to iterate.
[in]	start	ID of the first record of interest, can be used to start a scan in the middle of the file.
[in]	cc	Locking granularity to be used. See discussion for other constructor.
[in]	prefetch	If true, a background thread will pre-fetch pages in support of this scan. For this to work the server option sm_prefetch must be enabled.
[in]	ignored	not used

Record-level locking is not supported here because there are problems with phantoms if another transaction is altering the file while this scan is going on. Thus, if you try to use record-level locking, you will get page-level locking instead.

NORET scan_file_i::scan_file_i	(	const stid_t &	stid,
		concurrency_t	cc = t_cc_file,
		bool	prefetch = false,
		lock_mode_t	ignored = SH
	)

Construct an iterator over the given store (file).

Parameters:

[in]	stid	ID of the file over which to iterate.
[in]	cc	Locking granularity to be used. The following are permissible, and their implied store, page and record lock modes are given: t_cc_none : store - IS page - none record - none t_cc_record : store - IS page - SH record - none t_cc_page : store - IS page - SH record - none t_cc_append : store - IX page - EX record - EX t_cc_file : store - SH page - none record - none
[in]	prefetch	If true, a background thread will pre-fetch pages in support of this scan. For this to work the server option sm_prefetch must be enabled.
[in]	ignored	not used

Record-level locking is not supported here because there are problems with phantoms if another transaction is altering the file while this scan is going on. Thus, if you try to use record-level locking, you will get page-level locking instead.

---

Member Function Documentation

void scan_file_i::cursor	(	pin_i *&	pin_ptr,
		bool &	eof
	)			[inline]

Return the pin_i that represents the scan state.

Parameters:

[out]	pin_ptr	Populate the caller's pointer.
[out]	eof	False if the pin_i points to a record, true if there were no next record to pin.

Definition at line 502 of file scan.h.

References _cursor, and _eof.

rc_t scan_file_i::next	(	pin_i *&	pin_ptr,
		smsize_t	start_offset,
		bool &	eof
	)

Advance to the next record of the file.

Parameters:

[out]	pin_ptr	Populate the caller's pointer.
[in]	start_offset	Pin the next record at this offset. Meaningful only for large records.
[out]	eof	False if the pin_i points to a record, true if there were no next record to pin.

This must be called once to get the first record of the file.

Reimplemented in append_file_i.

rc_t scan_file_i::next_page	(	pin_i *&	pin_ptr,
		smsize_t	start_offset,
		bool &	eof
	)

Advance to the first record on the next page in the file.

Parameters:

[out]	pin_ptr	Populate the caller's pointer. This pin_i represents the state of this scan.
[in]	start_offset	Pin the next record at this offset. This is meaningful only for large records.
[out]	eof	False if the pin_i points to a record, true if there were no next record to pin.

If next_page is called after the scan_file_i is initialized it will advance the cursor to the first record in the file, just as next() would do.

---

The documentation for this class was generated from the following file:

• src/sm/scan.h

---