| Navigation: Language Reference > 4 - Entity Declarations > Complex Data Structures >====== GROUP (compound data structure) ====== |    |
| 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: