Data queue functions

execDataQueueOk()

Function prototype:

boolean execDataQueueOk (byte *Queue, word or byte QueueSize);

Parameters: Queue the queue to get the data from
QueueSize the size of the queue in bytes

Returns: true if the queue is not corrupted. It will return false if the queue’s internal data structures (pointers, etc.) imply that queue entries exist outside the memory extent of the queue or overlap one another.

The QueueSize is the size of the Queue array in bytes, which is best obtained using the sizeof() operator. This may be most easily done using the DATAQ() macro, where DATAQ(MyQueue) expands to MyQueue, sizeof(MyQueue). Note that MyQueue must be defined by extern byte MyQueue[x] not extern byte *MyQueue in the application’s header file.

For details of the queue implementation, see section 3.4.4.

execGetData()

Function prototype:

byte execGetData (byte *Queue, word or byte QueueSize,
                  byte *Buffer);

Parameters: Queue the queue to get the data from
QueueSize the size of the queue in bytes
Buffer the buffer in which to place the retrieved data

Returns: the number of bytes retrieved. It will return 0 if there is nothing pending on the data queue.

The buffer must be big enough to hold the data retrieved (no check is made). The number of bytes retrieved will never exceed 255.

For details of the queue implementation, see section 3.4.4.

execGetDataItems()

Function prototype:

byte or word execGetDataItems (byte *Queue,
                               word or byte QueueSize);

Parameters: Queue the queue in which to count items
QueueSize the size of the queue in bytes

Returns: the number of items (individually posted buffers) that are present on the queue. It will return 0 if the queue is empty.

For details of the queue implementation, see section 3.4.4.

execGetDataSpace()

Function prototype:

byte execGetDataSpace (byte *Queue, word or byte QueueSize);

Parameters: Queue the queue to examine for space
QueueSize the size of the queue in bytes

Returns: the number of bytes that can be posted onto the given data queue. It will return 0 if the data queue is completely full.

For details of the queue implementation, see section 3.4.4.

execPeekData()

Function prototype:

byte execPeekData (byte *Queue, word or byte QueueSize,
                   byte *Buffer, word or byte ItemNumber);

Parameters: Queue the queue to get the data from
QueueSize the size of the queue in bytes
Buffer the buffer in which to place the retrieved data
ItemNumber the buffer from the front of the queue to inspect

Returns: the number of bytes retrieved. It will return 0 if the item number does not exist (i.e. is outside the bounds of the number of items on the queue).

The buffer must be big enough to hold the data retrieved (no check is made). The number of bytes retrieved will never exceed 255.

When the data is retrieved, only a copy of the data is taken. The queue itself remains unaltered.

Item number 0 refers to the item that will be fetched in the next execGetData() call. Item numbers then follow sequentially along the queue from there, up to the most recently posted.

For details of the queue implementation, see section 3.4.4.

execPendingData()

Function prototype:

byte execPendingData (byte *Queue);

Parameters: Queue the queue on which to check whether there is data

Returns: the number of bytes pending retrieval. It will return 0 if there is nothing pending on the data queue.

For details of the queue implementation, see section 3.4.4.

execPostData()

Function prototype:

boolean execPostData (byte *Queue, word or byte QueueSize,
                      byte *Buffer, byte Size);

Parameters: Queue the queue on which to post the data
QueueSize the size of the queue in bytes
Buffer the data to post
Size the number of bytes of data to post

Returns: true if it succeeded or false if it failed. It will fail if there is not enough space on the queue to post the data.

For details of the queue implementation, see section 3.4.4.

execPurgeData()

Function prototype:

void execPurgeData (byte *Queue);

Parameters: Queue the queue to be purged

Returns: nothing.

This function resets a queue and deletes all its contents. (In actual fact, only the header data is reset. The remaining bytes are untouched.)