ss_m::file/record(SSM)

Shore Programmer's Manual - 2 August 96

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 place 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. No order is defined on the records in a file: when a new record is created, the I/O subsystem may place the record anywhere in the file.

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.

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 example, when a value-added server creates a record of a known size but with uninitialized data. To make use of this feature, these functions are called with data vectors of a specialized type, zvec_t, whose constructor takes only a size:

    rc_t    rc;
    char    h[HEADER_SIZE];
    vec_t   hdr(h, sizeof(h));

    // ... fill in hdr

    // create a vector representing 1000 
    // contiuous bytes of zeroes
    zvec_t  zdata(1000);

    rc = ss_m::create_rec(lvid, lfid, hdr,
        HEADER_SIZE + 1000, zdata, result);

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 1.0 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-92-C-Q508.