ZBasic System Library
149
ZBasic Microcontrollers
Type
Subroutine
Invocation
GetQueue(queue, var, count)
GetQueue(queue, var, count, timeLimit, timeoutFlag)
Parameter
Method
Type
Description
queue
ByRef
array of Byte
The queue from which to read data.
var
ByRef
any type
The variable to which to write the data from the queue.
count
ByVal
int16
The number of bytes to read from the queue.
timeLimit
ByVal
Single
The amount of time to wait for data availability, in seconds.
timeoutFlag
ByRef
Boolean
A variable to indicate if the call timed out.
Discussion
This routine has two forms. The first form simply attempts to read the given number of bytes from the
specified queue and place them in RAM beginning at the location of the given variable. In this case, the
routine will not return until requested number of bytes is available. If not enough data is placed in the
queue, the routine will never return. Note that if the calling task is locked and the queue contains
insufficient space for the data to be written data when this routine is called, the task will be unlocked to
allow other tasks to run.
The second form specifies, additionally, a timeLimit and a flag variable. In this case, if the requested
number of bytes does not become available within the specified time, the routine will return, having
transferred zero bytes, and the flag variable will be set to True indicating that the routine timed out. If
the requested number of bytes does become available before the specified time expires, that number of
bytes will be removed from the queue and transferred to the specified memory location and the flag
variable will be set to False indicating that the transfer did not time out. The resolution of the timeout
value is the same as the RTC tick, approximately 1.95mS.
In either case, if data is removed from the queue it is written to RAM beginning at the location of the
specified variable. Note that if the count specifies a number of bytes larger than the variable, the
additional bytes will be written to subsequent RAM locations. This may have exactly the effect that you
intended but depending on the function of those subsequent bytes it may have a deleterious effect on
your program.
Note that before any queue operations are performed, the queue data structure must be initialized. See
the discussion of OpenQueue() for more details. Also, attempting to retrieve data from a queue that has
been assigned to a Com port as the transmit queue will produce undefined results.
Although this subroutine will accept a String variable as the second parameter it is generally not useful to
do so because the control bytes at the beginning of the string will be overwritten. If you want to populate
a string using data from a queue the alternatives are:
1)
Build up the string by retrieving individual characters one by one and appending them to a string.
2)
Retrieve a group of bytes to a Byte array and use the MakeString() function to create a string
from the constituent bytes.
3)
Use the GetQueueStr() function to obtain a string containing characters from the queue.
Example
Dim inQueue(1 to 40) as Byte
Dim lval as Long
Call OpenQueue(inQueue, SizeOf(inQueue))
 |
 |
 |