- Created by Mark Juras , last modified on Nov 02, 2016
You are viewing an old version of this page. View the current version.
Compare with Current View Page History
« Previous Version 2 Next »
The LongMemory Service Class
The service class LongMemory manages long memory areas. In the area of information management program storage must be viewed as containing a wide variety of different structures, indexes, lists, fixed records, long unformatted records, etc.. In addition it may be purely memory bound or it may be stored in a persistent file system. The role of this class is to provide a single interface for storing and retrieving information. It is sufficiently robust to allow for the management of large files in the multiple gigabyte size range; while it is still efficient for use by purely memory bound applications. Physically, a long memory storage area consists of a series or relatively large fixed sized blocks. The manner in which these blocks are created, maintained, and accessed is determined when the storage area is created. See the discussion within the LongMemory_Create method for a description of the different approaches used. Within these large fixed sized blocks there are four fundamentally different record types stored within the storage area:- Control Tables -- These are relatively short tables that are always stored entirely within a single block. The method LongMemory_Allocate is used to enter new control tables into the storage area.
- Data Tables -- These are arbitrarily long vectors that may cross block boundaries, but whose entire expanse consists of a logically contiguous area. The method LongMemory_Expand is used to enter new data tables into the storage area.
- Blocked Tables -- These are arbitrary collections of information that use entire storage blocks that need not be contiguous. The manner in which the blocks are used is dependent on the type of information collections. Most complex entities like indexes, storage based property sequences, short volatile records, etc. are blocked tables. The method LongMemory_EmptyBlock is used to allocate blocked tables in the storage area.
- Posting blocks -- These are fixed sized linked smaller blocks used to contain posting, collections of integer value such as selection vectors, inverted indexes, and sorting control tables.
The method LongMemory_Access
Prototypeint* LongMemory_Access(void* This,int Offset,int Delta);
Parameter | Description |
This | Specifies the handle for the storage area control structure. It must have been obtained from a storage area creation or open method. |
Offset | Specifies the sequence number relative to zero of the word in the storage area that the user wishes to access. |
Delta | Specifies, if nonzero, the callers intent to change the content of the word; else he wishes only to read it. |
If all goes well this method returns a semipermanent pointer to the word; else it takes a fatal error branch and does not return.
The method LongMemory_Allocate
Prototypeint LongMemory_Allocate(void* This,int Size);
Parameter | Description |
This | Specifies the handle for the storage area control structure. It must have been obtained from a storage area creation or open method. |
Size | Specifies the size in words of the structure being allocated. |
This method returns the actual starting offset in the persistent storage area of the allocated area.
The method LongMemory_AllocateBytes
Prototypeint LongMemory_AllocateBytes(void* This,int Size);
Parameter | Description |
This | Specifies the handle for the storage area control structure. It must have been obtained from a storage area creation or open method. |
Size | Specifies size in bytes of the structure being allocated. |
This method returns the actual starting offset in the persistent storage area of the allocated area.
The method LongMemory_Close
Prototypevoid LongMemory_Close(void* This);
Parameter | Description |
This | Specifies the handle for the storage area control structure. This must have been obtained from a storage area creation or open method. |
This method has no return value.
The method LongMemory_Create
Prototypevoid* LongMemory_Create(char* FileName,int PagingMethod,int PageSize,int MaximumPages,int MaximumBlocks);
Parameter | Description |
FileName | Contains the name of the file to be used if the persistent storage area is to reside within the file system of the host platform. Note that non-file resident persistent areas must use a the memory mapped paging algorithm. This parameter is NULL for non-file-based persistent storage areas. |
PagingMethod | Specifies the paging algorithm to be used. One of the following constants must be used: PagingType_BlockVector, PagingType_BlockSequence, PagingType_SarchForBlock, PagingType_MemoryMapped, or PagingType_MemorySequence. |
PageSize | Specifies the size of each page in the storage area. If set to zero, the value PagingSystem_PageSize is used. Note this value is expressed in bytes not words. |
MaximumPages | Specifies the maximum number of pages in memory to be allocated for the storage area. |
MaximumBlocks | specifies the maximum number of blocks to be allocated for the storage area in its file-based form. |
If all goes well, this method returns the storage area handle to be used for the created area; else it returns NULL.
The method LongMemory_DeleteBlock
Prototypevoid LongMemory_DeleteBlock(void* This,int BlockNumber);
Parameter | Description |
This | Specifies the handle for the storage area control structure. It must have been obtained from a storage area creation or open method. |
BlockNumber | contains the number of the block to be marked as being deleted. |
This method has no return value.
The method LongMemory_DeleteRecord
Prototypevoid LongMemory_DeleteRecord(void* This,int ioiad,int length);
Parameter | Description |
This | Specifies the handle for the storage area control structure. It must have been obtained from a storage area creation or open method. |
ioiad | Specifies the starting address of the record in the long memory area. |
length S | pecifies the length of the contiguous area being deleted. |
This method has no return value.
The method LongMemory_EmptyBlock
Prototypeint* LongMemory_EmptyBlock(void* This,int* BlockNumber);
Parameter | Description |
This | Specifies the handle for the storage area control structure. It must have been obtained from a storage area creation or open method. |
BlockNumber | returns the block number of the empty block. It is this block number that is the primary persistent retrieval value for the block in all future accesses. |
If all goes well this method returns a semipermanent pointer to the start of the block; else it returns a NULL and stores a zero in the BlockNumber parameter.
The method LongMemory_Extend
Prototypeint LongMemory_Extend(void* This,int nWord);
Parameter | Description |
This | Specifies the handle for the storage area control structure. It must have been obtained from a storage area creation or open method. |
nWord | Specifies the number of words to extend the storage area by. |
This method returns the actual offset in the persistent storage area of the start of the new area.
The method LongMemory_GetBlock
Prototypeint* LongMemory_GetBlock(void* This,int BlockNumber,int Delta);
Parameter | Description |
This | Specifies the handle for the storage area control structure. This must have been obtained from a storage area creation or open method. |
BlockNumber | Specifies the number of the block to access. |
Delta | Specifies the callers intent to change the content of the block. If it is nonzero, then the user intends to change the content of the block; else he will only read it. |
If all goes well this method returns a semipermanent pointer to the start of the block, else it takes a fatal error branch and does not return.
The method LongMemory_GetDeleted
Prototypeint LongMemory_GetDeleted(void* This,int nAllocate);
Parameter | Description |
This | Specifies the handle for the storage area control structure. This must have been obtained from a storage area creation or open method. |
nAllocate | specifies the length of the desired allocation in words. |
If a deleted segment is found that contains sufficient room to satisfy the request, then its offset in the long memory area is returned. Else a zero is returned.
The method LongMemory_GetNext
Prototypeint LongMemory_GetNext(void* This);
Parameter | Description |
This | Specifies the handle for the storage area control structure. It must have been obtained from a storage area creation or open method. |
This method returns the retrieval offset for the next available word of storage.
The method LongMemory_GetPageSize
Prototypeint LongMemory_GetPageSize(void* This);
Parameter | Description |
This | Specifies the handle for the storage area control structure. It must have been obtained from a storage area creation or open method. |
This method returns the page size of the storage area.
The method LongMemory_GetPostingSize
Prototypeint LongMemory_GetPostingSize(void* This);
Parameter | Description |
This | Specifies the handle for the storage area control structure. It must have been obtained from a storage area creation or open method. |
This method returns the posting size of the storage area.
The method LongMemory_HasChanged
Prototypeint LongMemory_HasChanged(void* This);
Parameter | Description |
This | Specifies the handle for the storage area control structure. It must have been obtained from a storage area creation or open method. |
If the storage area has not been changed, then a zero is returned. If it has been changed, then a nonzero value is returned.
The method LongMemory_Open
Prototypevoid* LongMemory_Open(char* FileName,int PagingMethod,int AccessType,int MaximumPages,int MaximumBlocks);
Parameter | Description |
FileName | Contains the name of the file used for the persistent storage area when it was created. |
PagingMethod | Specifies the paging algorithm to be used. One of the following constants must be used: PagingType_BlockVector, PagingType_BlockSequence, PagingType_SearchForBlock, PagingType_MemoryMapped, or PagingType_MemorySequence. |
AccessType | Specifies if access is be read-write, value is zero, or one if it is to be readonly. |
MaximumPages | Specifies the maximum number of pages in memory to be allocated for the storage area. |
MaximumBlocks | specifies the maximum number of blocks to be allocated for the storage area in its file-based form. If zero then the number of blocks currently on the file is used. |
If all goes well,this method returns the storage area handle to be used to reference the storage area. A NULL return value means that the file could not be opened.
The method LongMemory_NewBlock
Prototypeint* LongMemory_NewBlock(void* This);
Parameter | Description |
This | Specifies the handle for the storage area control structure. It must have been obtained from a storage area creation or open method. |
If no new blocks can be allocated to the long memory area then a NULL is returned; else a semipermanent pointer to the start of the block is returned.
The method LongMemory_OpenArea
Prototypevoid* LongMemory_OpenArea(char* FileName,int Mode,int ReadOnly);
Parameter | Description |
FileName | Contains the name of the file used for the long storage area when it was created or the name to be used if it is to be a new storage area. |
Mode | Specifies the mode of the file and must be one of the following constants -- LongMemory_Open_Existing, LongMemory_Open_New, LongMemory_Open_Virtual, or LongMemory_Open_Memory. |
ReadOnly | Specifies the access type. It contains zero if access is the be read-write and one if it is to be readonly. |
If all goes well,this method returns the storage area handle to be used to reference the storage area else it returns a NULL.
The method LongMemory_OpenRaw
Prototypevoid* LongMemory_OpenRaw(char* FileName,int Mode,int ReadOnly);
Parameter | Description |
FileName | Contains the name of the file used for the persistent storage area when it was created. |
Mode | Specifies the mode of the file and must be one of the following constants:
|
ReadOnly | Specifies the access type. It contains zero if access is the be read-write and one if it is to be readonly. |
If all goes well this method returns the handle for the controlling storage structure; else it returns a NULL.
The method LongMemory_ReadBytes
Prototypevoid LongMemory_ReadBytes(void* This,int Offset,UBYTE* Bytes,int nByte);
Parameter | Description |
This | Specifies the hhandle for the storage area control structure. It must have been obtained from a storage area creation or open method. |
Offset | Specifies the word offset of the start of the bytes to be read. |
Bytes | Receives the bytes read. |
nByte | Specifies the number of bytes to be read. |
The method LongMemory_RewriteBytes
Prototypevoid LongMemory_RewriteBytes(void* This,int Offset,UBYTE* Bytes,int nByte);
Parameter | Description |
This | Specifies the handle for the storage area control structure. It must have been obtained from a storage area creation or open method. |
Offset | Specifies the word offset of the start of the bytes to be written. |
Bytes | Contains the bytes to be rewritten. |
nByte | Specifies the number of bytes to be rewritten. |
The method LongMemory_ZeroBytes
Prototypevoid LongMemory_ZeroBytes(void* This,int Offset,int nByte);
Parameter | Description |
This | Specifies the handle for the storage area control structure. It must have been obtained from a storage area creation or open method. |
Offset | Specifies the word offset of the start of the bytes to be zeroed. |
nByte | Specifies the number of bytes to be zeroed. |
The method LongMemory_WriteBytes
Prototypeint LongMemory_WriteBytes(void* This,UBYTE* Bytes,int nByte,int nStart);
Parameter | Description |
This | Specifies the handle for the storage area control structure. It must have been obtained from a storage area creation or open method. |
Bytes | Contains the bytes to be written. |
nByte | Specifies the number of bytes to be written. |
nStart | Specifies the number of bytes that must be written as part of a contiguous block -- i.e., without an intervening block boundary. |
The return value from the method is the actual offset in persistent storage of the start of the new area. Note that the offset is word-oriented, not byte oriented.
The method LongMemory_Read
Prototypevoid LongMemory_Read(void* This,int Offset,int* Buffer,int nWord);
Parameter | Description |
This | Specifies the handle for the storage area control structure. It must have been obtained from a storage area creation or open method. |
Offset | Specifies the word offset of the start of the words to be read. |
Buffer | Receives the words read. |
nWord | Specifies the number of words to be read. |
The method LongMemory_Rewrite
Prototypevoid LongMemory_Rewrite(void* This,int Offset,int* Buffer,int nWord);
Parameter | Description |
This | Specifies the handle for the storage area control structure. It must have been obtained from a storage area creation or open method. |
Offset | Specifies the offset of the start of the words to be rewritten. |
Buffer | Contains the words being rewritten. |
nWord | Specifies the number of words to be rewritten. |
The method LongMemory_Write
Prototypeint LongMemory_Write(void* This,int* Record,int nRecord);
Parameter | Description |
This | Specifies the handle for the storage area control structure. It must have been obtained from a storage area creation or open method. |
Record | Contains the words to be written. |
nRecord | Specifies the number of words to be written. |
The method returns the actual offset in storage of the start of the record. The record can be later read using this offset.
Table of Contents
- No labels