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

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:

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

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:

The method Sequence_GetLength

Prototype

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:

The method Sequence_GetRoot

Prototype

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:

The method Sequence_GetStorage

Prototype

The Sequence_GetStorage method returns the handle of the LongMemory storage area that contains the sequence. Its parameter is as follows:

The method Sequence_Create

Prototype

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:

The method Sequence_Open

Prototype

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: