QUEUE (declare a memory QUEUE structure)

Top  Previous  Next

 

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:

 

See Also:

PRE

STATIC

NAME

FREE

THREAD

WHAT

WHERE

 

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