GROUP (compound data structure)

Top  Previous  Next

 

label

GROUP( [ group ] )

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

 

 

[,THREAD] [,BINDABLE] [, TYPE] [,PRIVATE] [,PROTECTED]

 

    declarations

 

 

END

 

GROUP

A compound data structure.

group

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.

PRE

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

DIM

Dimension the variables into an array.

OVER

Share a memory location with another variable or structure.

NAME

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

EXTERNAL

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

DLL

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

STATIC

Specify the variable's memory is permanently allocated.

THREAD

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

BINDABLE

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

TYPE

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

PRIVATE

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.

PROTECTED

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

declarations

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.

Example:

     PROGRAM

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

F1          STRING(20)            ! first field

F2          STRING(1)             ! middle field

F3          STRING(20)            ! last field

          END

 

 MAP

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

 END

 

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

         END

 

CODE

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)

CODE

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

                                 !from passed parameter

 

See Also:

Field Qualification

WHAT

WHERE

WHO

ISGROUP

HOWMANY