dim record statement

	<< Index >>	FutureBasic 5
dim record		statement

Syntax:

dim record recordName

  dim declaration1 [,declaration2...]

  [dim declaration3 [,declaration4...]]

      :

dim end record recIdentifier

A declaration can have any of the following forms:

identifier[typeSuffix][;statExpr]

[maxLen] identifier$ [;statExpr]

identifier as {predefinedType|userType}[;statExpr]

identifier.constant [;statExpr]

{% | & | && | &&&}

identifier is any standard FutureBasic identifier that begins with a letter and contains only letters and digits.
typeSuffix is any type-identifier suffix.
statExpr is a non-negative static integer expression.
maxLen is a literal or symbolic integer constant in the range 1 through 255.
predefinedType is one of the following: char, [unsigned] byte, [unsigned] word, [unsigned] short, [unsigned] int, UInt16, [unsigned] long, UInt32, Point, Fixed, Rect, Handle, RgnHandle, Str255, Str63, Str31, Str15, double, single
userType is a type name defined in a previous begin record statement, or in a previous #define statement.
constant is a non-negative literal integer or a symbolic constant; but if a symbolic constant is used, its initial underscore character is omitted.
recIdentifier is an identifier that begins either with an underscore character or a period.

Description:
The dim record statement indicates the beginning of a "pseudo-record" definition block (as contrasted with a "true record" definition, which is declared using a begin record...end record block). As shown in the syntax description, the block must contain dim statements, and must end with a dim end record statement. The "pseudo-record" definition block instructs the compiler to generate a new symbolic integer constant from each identifier, and from recIdentifier. For example, the following block:

dim record myRecord

  dim firstField%

  dim 5 secondField$

  dim thirdField&

  dim fourthField.10

dim end record .myRecSize

is exactly equivalent to these statements:

_firstField = 0

_secondField = 2

_thirdField = 8

_fourthField = 12

_myRecSize = 22

For this reason, each identifier, and recIdentifier, must have names which are different from any symbolic constants defined anywhere else in the program, and different from the names of any FutureBasic predefined symbolic constants. This also implies that none of the identifier and recIdentifier names in one dim record block can be the same as any identifier or recIdentifier names in any other dim record block.
After these symbolic constants have been generated, you can use the recIdentifier constant to declare a "pseudo-record" variable. Using the above example, you could specify the following anywhere after the dim record block:
dim aRecord.myRecSize
This reserves 22 bytes for the variable "aRecord," and is exactly equivalent to this declaration:
dim aRecord.22
You can then think of this 22-byte area as being divided into four "fields":

A 2-byte short integer (firstField%)
A 6-byte (max 5 characters) string (secondField$)
A 4-byte long integer (thirdField&)
A 10-byte sub-record (fourthField)

Notice that the values of the first four symbolic constants generated in the dim record block represent the byte offset values to the beginnings of these fields. This means that you can use those constants along with FutureBasic's "embedded-dot" syntax to access the individual fields within the pseudo-record (see Appendix B - Variables, to learn more about the embedded-dot syntax). For example:
print aRecord.thirdField&
This instructs FutureBasic to print the long integer which is located 8 bytes past the beginning of aRecord. Note that you could also have written this statement as:
print aRecord.8&
However, using the symbolic constant names generally makes the program easier to read and maintain.

Using the alignment declarators (%, &, &&, &&&)
These are used in a way similar to their use in the "standalone" dim statement. An alignment declarator causes the symbolic constant generated from the next declared identifier or recIdentifier to have a value which is divisible by 2, 4, 8 or 16.
For example:

dim record myRec

  dim abc.9

  dim n%

  dim &, xyz%

dim end record .recSize

The "&" declarator forces the constant _xyz to have a value which is divisible by 4. The constants are generated with these values:

_abc = 0

_n = 9

_xyz = 12

_recSize = 14

Using the semicolon (;) syntax
This is used in a way similar to its use in the "standalone" dim statement. A declaration of the form dim var1; constant, var2 causes var1 and var2 to generate constants which differ by the value of constant. For example:

dim record myRec

  dim 5 theName$

  dim theRect;0

  dim pt1.4

  dim pt2.4

dim end record .recSize

This block causes the following constants to be generated:

_theName = 0

_theRect = 6

_pt1 = 6

_pt2 = 10

_recSize = 14

Using an underscore with recIdentifier
If recIdentifier begins with an underscore character rather than with a period, then in addition to generating new symbolic constants, FutureBasic also reserves storage space for a single pseudo-record variable (whose name is specified by the recordName parameter), as well as a variable for each of the "fields." Furthermore, the field variables are assigned storage which lies inside the record variable. For example, this block:

dim record myRecord

  dim firstField%

  dim 5 secondField$

  dim thirdField&

  dim fourthField.10

dim end record _myRecSize

is exactly equivalent to these statements:

_firstField = 0

_secondField = 2

_thirdField = 8

_fourthField = 12

_myRecSize = 22

dim myRecord.myRecSize;0

dim firstField%, 5 secondField$

dim thirdField&, fourthField.10

In this case, while the scope of the symbolic constants is global, the scope of the declared variables depends on where in the program the dim record block appears.

See Also:
dim; begin record...end record