#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, bool prefetch = false); NORET scan_file_i( const lvid_t& lvid, const serial_t& fid, const serial_t& start_rid, concurrency_t cc = t_cc_file, bool prefetch = false); 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 scan_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 };
Class append_file_i allows a VAS to appending of records to a file in rapid succession. The location of the end of the file is maintained by the append_file_iobject. The constructor of the append_file_i exclusively locks the file. The effect of using more than one append_file_i on a single file within a single transaction is undefined.
Each instance of scan_file_i and append_file_i keeps a record pinned (and therefore, a page fixed) throughout its existence. You must carefully control the use of these classes to avoid fixing all the pages in the buffer pool.
The order in which records are visited by a 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: creating a 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.
scan_file_i(lvid, fid, cc)
scan_file_i(lvid, fid, start_rid, cc)
next(pin_ptr, start_offset, eof)
Do not unpin the record explicitly during a scan.
The finish method unpins 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 ERRORS section for more information.
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:
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_recisthemore 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.