gmSCSequenceClass
The Sequence Service Class
Section titled “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
Section titled “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
Section titled “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
Section titled “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
Section titled “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
Section titled “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
Section titled “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
Section titled “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. |