Clarion Community Help

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
| **Navigation:**  [[introduction.htm|Language Reference]] > 4 - Entity Declarations > Queue Structures >====== QUEUE (declare a memory QUEUE structure) ====== | [[queue structures.htm|{{btn_prev_n.gif|Previous page}}]][[introduction.htm|{{btn_home_n.gif|Return to chapter overview}}]][[additional queue considerations.htm|{{btn_next_n.gif|Next page}}]] |
|  ||

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

{{blk2blue.jpg|blk2blue.jpg}}

| **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  add an entry .htm|ADD]] | [[changes  return changed queue .htm|CHANGES]] | [[delete  delete a record .htm|DELETE]] | [[free  delete all entries .htm|FREE]] | [[get  read a record or entry .htm|GET]] | [[pointer  return last queue entry position .htm|POINTER]] | [[position  return record sequence position .htm|POSITION]] |
| [[put  re write record .htm|PUT]] | [[records  return number of rows in data set .htm|RECORDS]] | [[sort  sort queue entries .htm|SORT]] |  |  |  |  |

**See Also:**

[[pre  set label prefix .htm|PRE]]

[[static  set allocate static memory .htm|STATIC]]

[[name  set external name .htm|NAME]]

[[free  delete all entries .htm|FREE]]

[[thread  set thread specific memory allocation .htm|THREAD]]

[[what  return field from group .htm|WHAT]]

[[where  return field position in group .htm|WHERE]]

[[from_set_listbox_data_source_.htm|FROM(Queue)]]

[[module_definition_files_exp_files_.htm#exporting_a_queue|Export a QUEUE]]


**Example:**

<code>
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
</code>