// Module:  AS_PER_genericStore
// Description:
//
//     This module defines the interface and implementation of the index
//     and string "stores" -- binary files used to store fixed and
//     variable size data for the assembler.  An additional type of
//     store needs to be implemented, for storing variable length
//     records.  Strings should probably be implemented as a variable
//     length record prefixed by its length.  The Fragment Store is
//     built using the building blocks of the index and string stores.
//     Both types of stores provide both a file-based and memory-based
//     implementations.  The intent is for the client to build up
//     buffers of records/strings in a memory-based store, and
//     concatenate them to the file-based store using the (as yet
//     unimplemented) concat operation.  A store consists of a fixed
//     length header, followed by data.  The only types of modifications
//     to the store that are currently permitted are to append a new
//     record/string to the store, or to mark a record in an indexStore
//     as deleted.  In principle, there is no reason why the index store
//     could not support a replace operation, that would replace a
//     record with new data, as long as the index of the record in
//     question was within range.
//
//     Client code relates to a store through an opaque handle.  This
//     will faciliate changes to the store structure as we learn more
//     about requirements and optimization.
//
//     Each type of store supports a "stream" operation, for read access
//     to successive elements of the store.
//
// Assumptions:
//
//      To support the delete operation on an index store, the Most
//      Significant Bit of the stored data record must be a deleted
//      flag.  Currently, only the client pays attention to the deleted
//      bit.
//
// Document:
//      GenericStore.rtf


/******************************************************************************
 * Function: createIndexStore:
 * Description:
 *     Allocates an index store, and returns its handle.
 *
 * Inputs:
 *     StorePath   path to the indexStore.  If NULL this is a memory Store.
 *     storeType   Currently for user use only
 *     elementSize Size of the fixed length records
 *     version     Currently for user use,
 *                 we may need this to do version conversions in the future.
 *     firstID     Index of the first element in the store.
 *
 * Return Value:
 *     Zero if success.
 *****************************************************************************/
/******************************************************************************
 * Function: resetIndexStore:
 * Description:
 *     Recycles a string store, nuking its data.
 *
 * Inputs:
 *     sh           handle of open Index Store
 *     firstID      First ID for reset Store
 *
 * Return Value:
 *     Zero if success.
 *****************************************************************************/
/******************************************************************************
 * Function: createStringStore:
 * Description:
 *     Allocates a string store, and returns its handle.
 *
 * Inputs:
 *     StorePath   path to the indexStore.  If NULL this is a memory Store.
 *     storeType   Currently for user use only
 *     expectedStringSize   May be used in the future for optimization
 *     version     Currently for user use,
 *                 we may need this to do version conversions in the future.
 *
 * Return Value:
 *     Zero if success.
 *****************************************************************************/
/******************************************************************************
 * Function: resetStringStore:
 * Description:
 *     Recycles a string store, nuking its data.
 *
 * Inputs:
 *     sh           handle of open string Store
 *
 * Return Value:
 *     Zero if success.
 *****************************************************************************/
/******************************************************************************
 * Function: createVLRecordStore:
 * Description:
 *     Allocates a VLRecord store, and returns its handle.
 *
 * Inputs:
 *     StorePath   path to the indexStore.  If NULL this is a memory Store.
 *     storeType   Currently for user use only
 *     expectedRecordSize   May be used in the future for optimization
 *     version     Currently for user use,
 *                 we may need this to do version conversions in the future.
 *
 * Return Value:
 *     Zero if success.
 *****************************************************************************/
/******************************************************************************
 * Function: resetVLRecordStore:
 * Description:
 *     Recycles a VLRecord store, nuking its data.
 *
 * Inputs:
 *     sh           handle of open VLRecord  Store
 *
 * Return Value:
 *     Zero if success.
 *****************************************************************************/
/******************************************************************************
 * Function: openStore:
 * Description:
 *     Opens an existing, file-based store.
 *
 * Inputs:
 *     StorePath   path to the indexStore.  If NULL this is a memory Store.
 *     rw          file access mode
 *
 * Return Value:
 *     StoreHandle != NULLSTOREHANDLE on success
 *****************************************************************************/
/******************************************************************************
 * Function: closeStore:
 * Description:
 *     Close an open store.  Updates lastElem and lastCommittedElem.
 *
 * Inputs:
 *     sh    Handle to store we want to close
 *
 * Return Value:
 *     Zero if success.
 *****************************************************************************/
/******************************************************************************
 * Function: getIndexStore
 * Description:
 *     Random access to records in an index store
 *
 * Inputs:
 *     fs         Handle of index store
 *     index      index of record
 * Outputs:
 *     buffer     Buffer for element
 *
 * Return Value:
 *     Zero if success.
 *****************************************************************************/
/******************************************************************************
 * Function: getStringStore
 * Description:
 *     Random access to strings in a string store
 *
 * Inputs:
 *     fs         Handle of string store
 *     offset     offset of string
 * Outputs:
 *     buffer     Buffer for element
 *     maxLength  size of buffer
 *
 * Return Value:
 *     Zero if success.
 *     Hitting an EOF before an EOS is a no-no.
 *****************************************************************************/
/******************************************************************************
 * Function: getVLRecordStore
 * Description:
 *     Random access to VLRecords in a VLRecord store
 *
 * Inputs:
 *     fs         Handle of VLRecord store
 *     offset     offset of VLRecord
 * Outputs:
 *     buffer     Buffer for element
 *     maxLength  size of buffer (if maxLength is less than record size --> error )
 *
 * Return Value:
 *     Zero if success.
 *     If maxLength < recordLength, return -1
 *****************************************************************************/
/******************************************************************************
 * Function: appendVLRecordStore
 * Description:
 *     Append an element to an index store
 *
 * Inputs:
 *     store      Handle of index store
 *     element    Pointer to record for append
 *
 * Return Value:
 *     Zero if success.
 *****************************************************************************/
/******************************************************************************
 * Function: setIndexStore
 * Description:
 *     Overwrite an existing  element of an index store
 *
 * Inputs:
 *     store      Handle of index store
 *     index      index of element to overwrite
 *     element    Pointer to record for overwrite
 *
 * Return Value:
 *     Zero if success.
 *****************************************************************************/
/******************************************************************************
 * Function: appendStringStore
 * Description:
 *     Append a string to a string store
 *
 * Inputs:
 *     store      Handle of index store
 *     string     String to be appended
 *
 * Return Value:
 *     Zero if success.
 *****************************************************************************/
/******************************************************************************
 * Function: statsStore
 * Description:
 *     Get statistics on a store
 *
 * Inputs:
 *     store      Handle of index store
 * Outputs:
 *     stats      Pointer to StoreStat structure
 *
 * Return Value:
 *     Zero if success.
 *****************************************************************************/
/******************************************************************************
 * Function: getLastElemStore
 * Description:
 *   Get the index of the last Element of the Store
 *
 * Inputs:
 *     store           FragStore Handle
 * Return Value
 *     lastElem           Pointer to int to hold result.
 *
 *****************************************************************************/
/******************************************************************************
 * Function: getFirstElemStore
 * Description:
 *   Get the index of the first Element of the Store
 *
 * Inputs:
 *     store           Store Handle
 * ReturnValue
 *     lastElem           Pointer to int to hold result.
 *
 *****************************************************************************/
/******************************************************************************
 * Function: getStartIndexStream
 * Description:
 *   Get the startindex of the Stream
 *
 * Inputs:
 *     stream           Stream Handle
 * ReturnValue
 *     StartIndex
 *
 *****************************************************************************/
/******************************************************************************
 * Function: getStore
 * Description:
 *     Random access to records in an index store
 *
 * Inputs:
 *     fs         Handle of index store
 *     index      index of record
 * Outputs:
 *     buffer     Buffer for element
 *
 * Return Value:
 *     Zero if success.
 *****************************************************************************/
/******************************************************************************
 * Function: getStringStore
 * Description:
 *     Random access to strings in a string store
 *
 * Inputs:
 *     fs         Handle of string store
 *     offset     offset of string
 * Outputs:
 *     buffer     Buffer for element
 *     maxLength  size of buffer
 *
 * Return Value:
 *     Zero if success.
 *     Hitting an EOF before an EOS is a no-no.
 *****************************************************************************/
/******************************************************************************
 * Function: appendIndexStore
 * Description:
 *     Append an element to an index store
 *
 * Inputs:
 *     store      Handle of index store
 *     element    Pointer to record for append
 *
 * Return Value:
 *     Zero if success.
 *****************************************************************************/
/******************************************************************************
 * Function: openStream:
 * Description:
 *     Open a stream on an open Index Store
 *
 * Inputs:
 *     sh         Handle of store we want to stream
 *     buffer     Memory buffer for prefetching or optimization (currently unused)
 *     bufferSize Size of Memory buffer (currently unused)
 *
 * Return Value:
 *     Handle of opened Stream
 *****************************************************************************/
/******************************************************************************
 * Function: openStringStream:
 * Description:
 *     Opens a stream on an open String Store
 *
 * Inputs:
 *     fs         Handle of store we want to stream
 *     startOffset Offest of first string
 *     buffer     Memory buffer for prefetching or optimization (currently unused)
 *     bufferSize Size of Memory buffer (currently unused)
 *
 * Return Value:
 *     Zero if success.
 *****************************************************************************/
/******************************************************************************
 * Function: resetStream:
 * Description:
 *     Reset a stream with  new start/end indices
 *
 * Inputs:
 *     sh         Handle of store we want to stream
 *     startIndex First element of the store we want to see
 *     endIndex   Last element of the store we want to see
 *
 * Return Value:
 *     Zero if success.
 *****************************************************************************/
/******************************************************************************
 * Function: getStartIndexStream
 * Description:
 *   Get the startindex of the frag Stream
 *
 * Inputs:
 *     stream           FragStream Handle
 * ReturnValue
 *     StartIndex
 *
 *****************************************************************************/
/******************************************************************************
 * Function: nextStream
 * Description:
 *     Read the next record from an open index stream
 *
 * Inputs:
 *     sh         Handle of stream
 * Outputs:
 *     buffer     Buffer big enough to hold an element.
 *
 * Return Value:
 *     Zero if success.
 *****************************************************************************/
/******************************************************************************
 * Function: nextStringStream
 * Description:
 *     Read the next string from an open string stream
 *
 * Inputs:
 *     sh         Handle of string stream
 * Outputs:
 *     buffer     Buffer for string
 *     maxLength  Size of string that buffer can accomodate
 *
 * Return Value:
 *     Zero if success.
 *****************************************************************************/
/******************************************************************************
 * Function: nextVLRecordStream
 * Description:
 *     Read the next VLRecord from an open VLRecord stream
 *
 * Inputs:
 *     sh         Handle of VLRecord Stream
 * Outputs:
 *     buffer     Buffer for VLRecord
 *     maxLength  Size of VLRecord that buffer can accomodate
 *
 * Return Value:
 *     Zero if success.
 *****************************************************************************/
/******************************************************************************
 * Function: closeStream
 * Description:
 *     Closes a stream
 *
 * Inputs:
 *     sh         Handle of stream we want to close
 * Return Value:
 *     Zero if success.
 *****************************************************************************/
