ss_m::file/record(SSM)

Shore Programmer's Manual - 18 September 95

NAME

append_rec, create_file, create_id, create_rec, create_rec_id, destroy_file, destroy_rec, lfid_of_lrid, truncate_rec, update_rec, update_rec_hdr \- Class ss_m Methods for File/Record Operations

SYNOPSIS

#include <sm_vas.h>  // which includes sm.h


    static rc_t			create_file(
	const lvid_t& 		    lvid, 
	serial_t& 		    lfid,
	store_property_t	    property);

    static rc_t			destroy_file(
	const lvid_t& 		    lvid,
	const serial_t& 	    lfid); 

    static rc_t			create_rec(
	const lvid_t& 		    lvid, 
	const serial_t& 	    lfid,
	const vec_t& 		    hdr, 
	smsize_t		    len_hint,
	const vec_t& 		    data, 
	serial_t& 		    lrid); 

    static rc_t			create_id(
	const lvid_t& 		    lvid, 
	int 			    id_count, 
	serial_t& 		    id_start); 

    static rc_t			create_rec_id(
	const lvid_t& 		    lvid, 
	const serial_t& 	    lfid,
	const vec_t& 		    hdr,
	smsize_t		    len_hint,
	const vec_t& 		    data, 
	const serial_t& 	    lrid); 

    static rc_t			destroy_rec(
	const lvid_t& 		    lvid, 
	const serial_t& 	    lrid);

    static rc_t			update_rec(
	const lvid_t& 		    lvid, 
	const serial_t& 	    lrid,
	smsize_t		    start, 
	const vec_t& 		    data);

    static rc_t			update_rec_hdr(
        const lvid_t&		    lvid, 
	const serial_t& 	    lrid,
	smsize_t		    start, 
	const vec_t& 		    hdr);

    static rc_t			append_rec(
	const lvid_t&		    lvid, 
	const serial_t& 	    lrid,
	const vec_t& 		    data);

    static rc_t			truncate_rec(
	const lvid_t&		    lvid, 
	const serial_t& 	    lrid, 
	smsize_t		    amount);

    // lfid_of_lrid converts a logical record ID into a logical file ID
    static rc_t			lfid_of_lrid(
	const lvid_t& 		    lvid, 
	const serial_t& 	    lrid,
	serial_t& 		    lfid);

DESCRIPTION

The above class ss_m methods all deal with manipulating files and records.

Common Parameters

There are a number of common parameters for these methods:

lvid: Logical volume ID of volume containing a file/record.
lfid: Logical file ID, the serial number of a file.
lrid: Logical record ID, the serial number of a record.
data: A vector pointing to data used to fill/overwrite the body of a record.
hdr: A vector pointing to data used to fill/overwrite the header of a record.

create_file(lvid, lfid, property)

: The create_file method creates a new file on the volume lvid, and returns its serial number in lfid. The property parameter specifies whether the file is temporary or not. See enum(ssm) for more information on file properties.

: See the "ROOT INDEX METHODS" section of volume(ssm) for information on how to keep track of the files on a volume.

destroy_file(lvid, lfid)

: The destroy_file method destroys all records in the file and deallocates space used by a file. The space used by the file is not available for reuse until the transaction destroying the file commits.

create_rec(lvid, lfid, hdr, len_hint, data, lrid)

: The create_rec method creates a record in a file. The ID of the new record is returned in the lrid parameter. The len_hint parameter is a "hint" about the final length of the record. If the creation will be followed by appends, len_hint should ideally be set to the final length of the record. This will allow the SM to locate the record in a location with sufficient contiguous space for the record. A value of 0 should be used if the final length is unknown.

create_id(lvid, id_count, id_start)

: The create_id method generates id_count new IDs that can be used later by create_rec_id to associate a records with the IDs. The first ID is returned in id_start. The other IDs should be obtained by calling id_start::increment(1) id_count -1 times.

create_rec_id(lvid, lfid, hdr, len_hint, data, lrid)

: The create_rec_id method is identical to create_rec except that the record ID is specified by the caller with the lrid parameter rather than being generated and returned in lrid as is done in create_rec.

destroy_rec(lvid, lrid)

: The destroy_rec method destroys the specified record.

update_rec(lvid, lrid, start, data)

: The update_rec method updates a range of bytes in the body of the record specified by lvid, lrid . The byte offset, from the beginning of the record body, for the beginning of the range is specified by the start parameter. The length of the range is the length of the data vector. The range is replaced by the bytes pointed to by the data parameter. Note that update_rec cannot be used to change the size of the record. It is an error to specify a starting location and vector length that imply updating beyond the end of the record.

update_rec_hdr(lvid, lrid, start, hdr)

: The update_rec_hdr method updates a range of bytes in the header of the record specified by lvid, lrid . The byte offset, from the beginning of the header, for the beginning of the range is specified by the start parameter. The length of the range is the length of the hdr vector. The range is replaced by the bytes pointed to by the hdr parameter.
: Note: There are no methods for appending to a record header or truncating a record header (as there are for a record body). If these methods would be useful for you, please contact the Shore developers.

append_rec(lvid, lrid, data)

: The append_rec method appends the bytes pointed to by data to the end of the record body.

truncate_rec(lvid, lrid, amount)

: The truncate_rec method removes amount bytes from the end of a record body.

lfid_of_lrid(lvid, lrid, lfid)

: The lfid_of_lrid method returns, in lfid, the ID of file containing the record, lrid.

ERRORS

All of the above methods return a w_rc_t error code. If an error occurs during a method that is updating persistent data (the create, update, append, and truncate methods will update data) then the record/file could be in an inconsistent state. The caller then has the choice of aborting the transaction or rolling back to the nearest save-point (see transaction(ssm) ).

See errors(ssm) for more information on error handling.

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.