Files of Records
[Storage Structures]

Collaboration diagram for Files of Records:

---

Detailed Description

You can create, destroy, and scan files of records. You may exert some control over the order in which records appear in the file (a physical scan), but, in general, the storage manager decides where to put records.

Pages in a file are slotted pages: Each page contains an array of slots. Records take one of three forms: small, large, and very large.

• Small records fit in the slots on the file pages.
• Large records are too big to fit on a slotted page, so they are put elsewhere, and the slots point to these records. Actually, what is in a slot is a small array of page pointers to the data of the large record.
• A very large record is one whose slot in the file page contains a single reference to a page that is an index of data pages.

Because records may take these forms, the API for creating records contains the opportunity for you to provide a hint about the ultimate size of the record so that the storage manager can create the proper structure for the record immediately, rather than creating a small record that is soon to be converted to a large, then a very large record by subsequent appends.

All records contain a client-defined header. This is for the convenience of server-writers. The header must fit on the slotted page, so it should never be very large.

The following methods manipulate files of records and the records found there.

Modules below describe file traversal and appending to files (Scanning Files), and pinning individual records in the buffer pool for extended operations (Pinning Records).

Uninitialized Data

The functions create_rec, append_rec, and update_rec can be used to write blocks of data that are all zeroes, with minimal logging. This is useful for creating records of known size but with uninitialized data. The type zvec_t, a special case of vec_t, is for this purpose. Construct it with only a size, as follows:

 zvec_t zdata(100000);

The underlying logging code recognizes that this is a vector of zeroes and logs only a count, not the data themselves.

Errors

If an error occurs in the middle of one of these methods that is updating persistent data, the record or file could be in an inconsistent state. The caller has the choice of aborting the transaction or rolling back to the nearest savepoint (see Transactions, Locking and Logging).

See also:

Scanning, Pinning Records, vec_t, zvec_t, IDs.

Modules
	Pinning Records
Functions
static rc_t	ss_m::create_file (vid_t vid, stid_t &fid, store_property_t property, shpid_t cluster_hint=0)
	Create a file of records.
static rc_t	ss_m::destroy_file (const stid_t &fid)
	Destroy a file of records.
static rc_t	ss_m::create_rec (const stid_t &fid, const vec_t &hdr, smsize_t len_hint, const vec_t &data, rid_t &new_rid)
	Create a new record.
static rc_t	ss_m::destroy_rec (const rid_t &rid)
	Destroy a record.
static rc_t	ss_m::update_rec (const rid_t &rid, smsize_t start, const vec_t &data)
	Modify the body of an existing record.
static rc_t	ss_m::update_rec_hdr (const rid_t &rid, smsize_t start, const vec_t &hdr)
	Modify the header of an existing record.
static rc_t	ss_m::append_rec (const rid_t &rid, const vec_t &data)
	Append bytes to a record body.
static rc_t	ss_m::truncate_rec (const rid_t &rid, smsize_t amount)
	Chop bytes off the end of a record body.
static rc_t	ss_m::truncate_rec (const rid_t &rid, smsize_t amount, bool &should_forward)
	Chop bytes off the end of a record body.
rc_t	append_file_i::create_rec (const vec_t &hdr, smsize_t len_hint, const vec_t &data, rid_t &rid)
	Append a new record to the end of the file.

---

Function Documentation

static rc_t ss_m::create_file	(	vid_t	vid,
		stid_t &	fid,
		store_property_t	property,
		shpid_t	cluster_hint = 0
	)			[static, inherited]

Create a file of records.

Parameters:

[in]	vid	Volume on which to create a file.
[out]	fid	Returns (store) ID of the new file here.
[in]	property	Give the file the this property.
[in]	cluster_hint	Not used.

The cluster hint is included in the API for future use. It has no effect.

Examples:

create_rec.cpp, log_exceed.cpp, sort_stream.cpp, and vtable_example.cpp.

static rc_t ss_m::destroy_file

(

const stid_t &

fid

)

[static, inherited]

Destroy a file of records.

Parameters:

[in]

fid

ID of the file to destroy.

static rc_t ss_m::create_rec	(	const stid_t &	fid,
		const vec_t &	hdr,
		smsize_t	len_hint,
		const vec_t &	data,
		rid_t &	new_rid
	)			[static, inherited]

Create a new record.

Parameters:

[in]	fid	ID of the file in which to create a record.
[in]	hdr	What to put in the record's header.
[in]	len_hint	Hint about how big the record will ultimately be. This is used to determine the initial format of the record. If you plan to append to the record and know that it will ultimately become a large record, it is more efficient to give a size hint that is larger than a page here. Otherwise, the record will be made small (as determined by the size of the parameter data ), and subsequent appends will cause the record to be converted to a large record.
[in]	data	What to put in the record's body.
[out]	new_rid	ID of the newly created record.

Examples:

create_rec.cpp, log_exceed.cpp, sort_stream.cpp, and vtable_example.cpp.

static rc_t ss_m::destroy_rec

(

const rid_t &

rid

)

[static, inherited]

Destroy a record.

Parameters:

[in]

rid

ID of the record to destroy.

static rc_t ss_m::update_rec	(	const rid_t &	rid,
		smsize_t	start,
		const vec_t &	data
	)			[static, inherited]

Modify the body of an existing record.

Parameters:

[in]	rid	ID of the record to modify.
[in]	start	First byte to change.
[in]	data	What to put in the record's body.

This overwrites the existing bytes, starting at the offset start through the byte at start + data.size(). This method cannot be used to change the size of a record. Attempting this will result in an error.

Examples:

log_exceed.cpp.

static rc_t ss_m::update_rec_hdr	(	const rid_t &	rid,
		smsize_t	start,
		const vec_t &	hdr
	)			[static, inherited]

Modify the header of an existing record.

Parameters:

[in]	rid	ID of the record to modify.
[in]	start	First byte to change.
[in]	hdr	What to put in the record's header.

This overwrites the existing bytes, starting at the offset start through the byte at start + data.size(). This method cannot be used to change the size of a record header. There are no methods for appending to or truncating a record header.

See also:

pin_i::update_rec, Pinning Records

static rc_t ss_m::append_rec	(	const rid_t &	rid,
		const vec_t &	data
	)			[static, inherited]

Append bytes to a record body.

Parameters:

[in]	rid	ID of the record to modify.
[in]	data	What to append to the record.

Note:

This appends to a record; it does not append a record to a file!

See also:

pin_i::append_rec, Pinning Records

static rc_t ss_m::truncate_rec	(	const rid_t &	rid,
		smsize_t	amount
	)			[static, inherited]

Chop bytes off the end of a record body.

Parameters:

[in]	rid	ID of the record to modify.
[in]	amount	How many bytes to lop off.

See also:

pin_i::truncate_rec, Pinning Records

static rc_t ss_m::truncate_rec	(	const rid_t &	rid,
		smsize_t	amount,
		bool &	should_forward
	)			[static, inherited]

Chop bytes off the end of a record body.

Parameters:

[in]	rid	ID of the record to modify.
[in]	amount	How many bytes to lop off.
[out]	should_forward	Returns true if the record started out large but is now small as a result of the truncation. This enables a value-added server to take action in this event, should it so desire.

See also:

pin_i::truncate_rec, Pinning Records

rc_t append_file_i::create_rec	(	const vec_t &	hdr,
		smsize_t	len_hint,
		const vec_t &	data,
		rid_t &	rid
	)			[inherited]

Append a new record to the end of the file.

Parameters:

[in]	hdr	The client-defined record header.
[in]	len_hint	The length of the record, more or less. More accuracy here helps the sm reduce its work.
[in]	data	The client-defined record contents.
[out]	rid	The identifier of the new record.

---