GROUP (compound data structure)

Top  Previous  Next



GROUP( [ group ] )

[,PRE( )] [,DIM( )] [,OVER( )] [,NAME( )] [,EXTERNAL] [,DLL] [,STATIC]











A compound data structure.


The label of a previously declared GROUP or QUEUE structure from which it will inherit its structure. This may be a GROUP or QUEUE with the TYPE attribute.


Declare a label prefix for variables within the structure. Not valid on a GROUP within a FILE structure.


Dimension the variables into an array.


Share a memory location with another variable or structure.


Specify an alternate, "external" name for the field.


Specify the variable is defined, and its memory is allocated, in an external library. Not valid within FILE, QUEUE, or GROUP declarations.


Specify the variable is defined in a .DLL. This is required in addition to the EXTERNAL attribute.


Specify the variable's memory is permanently allocated.


Specify memory for the variable is allocated once for each execution thread. Also implicitly adds the STATIC attribute on Procedure Local data.


Specify all variables in the group may be used in dynamic expressions.


Specify the GROUP is a type definition for GROUPs passed as parameters.


Specify the GROUP and all the component fields of the GROUP are not visible outside the module containing the CLASS methods. Valid only in a CLASS.


Specify the variable is not visible outside base CLASS and derived CLASS methods. Valid only in a CLASS.


Multiple consecutive variable declarations.


A GROUP structure allows multiple variable declarations to be referenced by a single label. It may be used to dimension a set of variables, or to assign or compare sets of variables in a single statement. In large complicated programs, a GROUP structure is helpful for keeping sets of related data organized. A GROUP must be terminated by a period or the END statement.

The structure of a GROUP declared with the group parameter begins with the same structure as the named group; the GROUP inherits the fields of the named group. The GROUP may also contain its own declarations that follow the inherited fields. If the group parameter names a QUEUE or RECORD structure, only the fields are inherited and not the functionality implied by the QUEUE or RECORD.

When referenced in a statement or expression, a GROUP is treated as a STRING composed of all the variables within the structure. A GROUP structure may be nested within another data structure, such as a RECORD or another GROUP.

Because of their internal storage format, numeric variables (other than DECIMAL) declared in a group do not collate properly when treated as strings. For this reason, building a KEY on a GROUP that contains numeric variables may produce an unexpected collating sequence.

A GROUP with the BINDABLE attribute makes all the variables within the GROUP available for use in a dynamic expression. 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 GROUP with the TYPE attribute is not allocated any memory; it is only a type definition for GROUPs that are passed as parameters to PROCEDUREs. This allows the receiving procedure to directly address component fields in the passed GROUP. The parameter declaration on the PROCEDURE statement can instantiate a local prefix for the passed GROUP as it names the passed GROUP for the procedure, however this is not necessary if you use the Field Qualification syntax instead of prefixes. For example, PROCEDURE(LOC:PassedGroup) declares the procedure uses the LOC: prefix (along with the individual field names used in the type definition) to directly address component fields of the GROUP passed as the parameter.

The data elements of a GROUP with the DIM attribute (a structured array) are referenced using standard Field Qualification syntax with each subscript specified at the GROUP level at which it is dimensioned.

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



PassGroup  GROUP,TYPE             !Type-definition for passed GROUP parameters

F1          STRING(20)            ! first field

F2          STRING(1)             ! middle field

F3          STRING(20)            ! last field




  MyProc1(PassGroup)             !Passes a GROUP defined the same as PassGroup



NameGroup GROUP                   !Name group

First      STRING(20)             ! first name

Middle     STRING(1)              ! middle initial

Last       STRING(20)             ! last name

         END                     !End group declaration


NameGroup2 GROUP(PassGroup)       !Group that inherits PassGroup's fields

                                 ! resulting in NameGroup2.F1, NameGroup2.F2,

                                 ! and NameGroup2.F3

          END                    ! fields declared in this group


DateTimeGrp GROUP,DIM(10)         !Date/time array

Date          LONG                ! Referenced as DateTimeGrp[1].Date

StartStopTime LONG,DIM(2)         ! Referenced as DateTimeGrp[1].Time[1]

           END                   !End group declaration


FileNames GROUP,BINDABLE          !Bindable group

FileName   STRING(8),NAME('FILE') !Dynamic name: FILE

Dot        STRING('.')            !Dynamic name: Dot

Extension  STRING(3),NAME('EXT')  !Dynamic name: EXT




MyProc1(NameGroup)               !Call proc passing NameGroup as parameter

MyProc1(NameGroup2)              !Call proc passing NameGroup2 as parameter


MyProc1   PROCEDURE(PassedGroup)  !Proc to receive GROUP parameter

LocalVar  STRING(20)


LocalVar = PassedGroup.F1        !Assign value in the first field to LocalVar

                                 !from passed parameter


See Also:

Field Qualification