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.
|
Mark Juras