Clarion Community Help

Navigation: Language Reference > 4 - Entity Declarations > Queue Structures >====== QUEUE (declare a memory QUEUE structure) ======

label	QUEUE( [ group ] )	[,PRE] [,STATIC] [,THREAD] [,TYPE] [,BINDABLE] [,EXTERNAL] [,DLL]
fieldlabel	variable [,NAME( )]
	END

QUEUE	Declares a memory queue structure.
label	The name of the QUEUE.
group	The label of a previously declared GROUP, QUEUE, or RECORD structure from which it will inherit its structure. This may be a GROUP, QUEUE, or RECORD with or without the TYPE attribute.
PRE	Declare a fieldlabel prefix for the structure.
STATIC	Declares a QUEUE, local to a PROCEDURE, whose buffer is allocated in static memory.
THREAD	Specify memory for the queue is allocated once for each execution thread. This implies the STATIC attribute on Procedure Local data.
TYPE	Specify the QUEUE is just a type definition for other QUEUE declarations.
BINDABLE	Specify all variables in the queue may be used in dynamic expressions.
EXTERNAL	Specify the QUEUE is defined, and its memory is allocated, in an external library.
DLL	Specify the QUEUE is defined in a .DLL. This is required in addition to the EXTERNAL attribute.
fieldlabel	The name of the variables in the queue.
variable	Data declaration. The sum of the memory required for all declared variables in the QUEUE must not be greater than 4MB.

QUEUE declares a memory QUEUE structure. The label of the QUEUE structure is used in queue processing statements and procedures. When used in assignment statements, expressions, or parameter lists, a QUEUE is treated like a GROUP data type.

The structure of a QUEUE declared with the group parameter begins with the same structure as the named group; the QUEUE inherits the fields of the named group. The QUEUE may also contain its own declarations that follow the inherited fields. If the QUEUE will not contain any other fields, the name of the group from which it inherits may be used as the data type without the QUEUE or END keywords.

A QUEUE may be thought of as a “memory file” internally implemented as a “dynamic array” of QUEUE entries. When a QUEUE is declared, a data buffer is allocated (just as with a file). Each entry in the QUEUE is run-length compressed during an ADD or PUT to occupy as little memory as necessary, and de-compressed during GET. There is an 8 byte per-entry overhead for queues with uncompressed records, and 12 bytes per entry for queues with compressed records.

The data buffer for a Procedure local QUEUE (declared in the data section of a PROCEDURE) is allocated on the stack (unless it has the STATIC attribute or is too large). The memory allocated to the entries in a procedure-local QUEUE without the STATIC attribute is allocated only until you FREE the QUEUE, or you RETURN from the PROCEDURE–the QUEUE is automatically FREEd upon RETURN.

For a Global data, Module data, or Local data QUEUE with the STATIC attribute, the data buffer is allocated static memory and the data in the buffer is persistent between procedure calls. The memory allocated to the entries in the QUEUE remains allocated until you FREE the QUEUE.

The variables in the QUEUE's data buffer are not automatically initialized to any value, they must be explicitly assigned values. Do not assume that they contain blanks or zero before your program's first assignment to them.

As entries are added to the QUEUE, memory for the entry is dynamically allocated then the data copied from the buffer to the entry and compressed. As entries are deleted from the QUEUE, the memory used by the deleted entry is freed. The maximum number of entries in a QUEUE is theoretically 2^26 (67,108,864), but is actually dependent upon available virtual memory. The actual memory used by each entry in the QUEUE is dependent on the data compression ratio achieved by the runtime library.

A QUEUE with the BINDABLE attribute makes all the variables within the QUEUE available for use in a dynamic expression, without requiring a separate BIND statement for each (allowing BIND(queue) to enable all the fields in the queue). The contents of each variable's NAME attribute is the logical name used in the dynamic expression. If no NAME attribute is present, the label of the variable (including prefix) is used. Space is allocated in the .EXE for the names of all of the variables in the structure. This creates a larger program that uses more memory than it normally would. Therefore, the BINDABLE attribute should only be used when a large proportion of the constituent fields are going to be used.

A QUEUE with the TYPE attribute is not allocated any memory; it is only a type definition for QUEUEs that are passed as parameters to PROCEDUREs. This allows the receiving procedure to directly address component fields in the passed QUEUE. The parameter declaration on the PROCEDURE statement instantiates a local prefix for the passed QUEUE as it names the passed QUEUE for the procedure. For example, PROCEDURE(LOC:PassedGroup) declares the procedure uses the LOC: prefix (along with the individual field names used in the type declaration) to directly address component fields of the QUEUE actually passed as the parameter.

The WHAT and WHERE procedures allow access to the fields by their relative position within the QUEUE structure.

Related Procedures:

ADD	CHANGES	DELETE	FREE	GET	POINTER	POSITION
PUT	RECORDS	SORT

See Also:

Example:

NameQue QUEUE,PRE(Nam)           !Declare a queue
Name      STRING(20)
Zip       DECIMAL(5,0),NAME('SortField')
        END                      !End queue structure
 
NameQue2 QUEUE(NameQue),PRE(Nam2) !Queue that inherits Name and Zip fields
Phone     STRING(10)              ! and adds a Phone field
        END
 
NameQue3 NameQue2                 !Declare a second QUEUE with exactly
                                  ! the same structure as NameQue2

FieldPairsQueue QUEUE,TYPE
Left    ANY
Right   ANY
    END