/
gmSCSequenceClass

gmSCSequenceClass

Owned by Mark Juras
Last updated: Jul 30, 2018Version comment

The Sequence Service Class

The service class Sequence manages sequences stored in long memory. A Sequence is an open ended list of entries. New entries can only be added to the end. Entries can be retrieved by their position number in the list. They are based in long memory and have no upper limit other than that imposed by the platform limits. Conceptually, the records of a sequence are viewed as records within a linear vector with no upper bound. The problem is that since multiple sequences must share the same linear addressing scheme, each sequence must be blocked and the locations in long memory of those blocks must be retained in higher level blocks.

The method Sequence_Access

Prototype


int* Sequence_Access(void* This,int SeqNum,int delta);
The Sequence_Access method accesses a storage based sequence. It returns a semi-permanent pointer to a slot in memory which contains a word or storage specified via its subscript or sequence number (relative to one). Note that the pointer returned is within a block of memory being managed by a virtual memory manager therefore, it can be assumed to be valid only for a relatively short time. The method makes no attempt to check the specified sequence number for reasonableness. It assumes that entries are being allocated more-or-less sequentially. When a slot for a specified number is not yet in the sequence, then the appropriate blocks are allocated to extend the sequence. These entries are initialized at zero. This feature can be used lay out a sequence of zeros, as when initializing a vector. If the next slot in sequence is desired, then pass a zero sequence number to this method. Its parameters are as follows:

Parameter Description
This Specifies the handle for the information structure controlling the sequence.
SeqNum Specifies the sequence number of desired record. A zero indicates that a new record is desired at the back of the stream.
delta Specifies the intent of the access -- a nonzero value indicates that the record will be changed and a zero value indicates that it will only be read.

The method returns a pointer to the start of the requested slot. If there is insufficient file space to achieve this, then a NULL is returned.

The method Sequence_Close

Prototype


void Sequence_Close(void* This);
The Sequence_Close method closes a storage-based sequence. If no changes have been made to the sequence, then this method ends up doing nothing beyond freeing the control structure. If the sequence has been changed, then its root information is updated in the storage area containing the sequence. Its parameter is as follows:

Parameter Description
This Specifies the handle for the information structure controlling the sequence.


The method Sequence_GetLength

Prototype


int Sequence_GetLength(void* This);
The Sequence_GetLength method returns the number of entries encompassed by the sequence, which is also the sequence number of the last record in the sequence, since sequences use one-based indexing. This can be zero if the sequence is empty. Its parameter is as follows:

Parameter Description
This Specifies the handle for the information structure controlling the sequence.


The method Sequence_GetRoot

Prototype


int Sequence_GetRoot(void* This);
The Sequence_GetRoot method returns the root offset of a sequence. This is the offset at which the control information for the sequence is stored. This offset is needed to reopen a sequence once it has been closed. Its parameter is as follows:

Parameter Description
This Specifies the handle for the information structure controlling the sequence.


The method Sequence_GetStorage

Prototype


void* Sequence_GetStorage(void* This);
The Sequence_GetStorage method returns the handle of the LongMemory storage area that contains the sequence. Its parameter is as follows:

Parameter Description
This Specifies the handle for the information structure controlling the sequence.


The method Sequence_Create

Prototype


void* Sequence_Create(void* Storage,int blockSize);
The Sequence_Create method creates a new empty sequence within a specified storage area and initializes its control structure accordingly. The method returns a handle to the control structure. This handle could be NULL in the event that memory has been exhausted. Its parameters are as follows:

Parameter Description
Storage Specifies the handle for the LongMemory storage area that is to contain the sequence.
blockSize Specifies the size of each block within the sequence. It is normally a small value like 8 or 16.


The method Sequence_Open

Prototype


void* Sequence_Open(void* Storage,int Properties);
The Sequence_Open method opens a storage-based sequence. The method returns a handle to the control structure. This handle could be NULL in the event that memory has been exhausted. Its parameters are as follows:

Parameter Description
Storage Specifies the handle for theLongMemory storage area that contains the sequence.
Properties Specifies the base address in the storage area of the property vector for the sequence. This value must have been originally obtained from the Sequence_GetRoot method after the sequence was created.


Table of Contents