125 of 307
ZBasic System Library 115 ZX Microcontroller Family GetQueue 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))