STRUCT statement

<struct-statement>
struct-statement ::= 
STRUCT <struct-name> [ BYTE | WORD ] { <struct-member-list> } 

A STRUCT statement defines the format of a struct; all resources are defined in terms of structs. The struct has a name designated by struct-name, and some items designated by struct-member-list.

Struct names

The following rules must be observed for struct-names:

  • they must be given in upper case

  • they must begin with an alphabetic character, although subsequent characters may be numeric

  • they may not begin with any of the 12 struct type-names (see STRUCT members), or the keywords: GLOBAL, STRUCT, LEN or RESOURCE. This restriction applies only to the struct-name, not the member-name of any individual struct members.

    So the following struct definition will generate an error

    STRUCT BUFTHING
     {
     BUF buffer;
     }

    whereas this struct definition will compile correctly

    STRUCT ABUFTHING
     {
     BUF buffer;
     }

Struct member list

The struct-member-list is a sequence of struct-member s where each member is terminated by a semi-colon. The complete list is enclosed within a pair of braces.

See STRUCT members for more details.

BYTE/WORD keywords

STRUCT definitions allow resource instances to be of variable length, as the struct can allow default variables for its members. A resource’s entire length can be deduced from the position of the next resource; this information is available in a resource file’s index. If the resource is used as a member within an instance of another resource, however, its length must be identified another way.

  • Use BYTE to prefix the struct with a single byte indicating its length (zero to 255 characters).

  • Use WORD to prefix the struct with a word indicating its length (zero to 65,535 characters).

The following are valid STRUCT statements:

STRUCT STRING
 {
 LTEXT str;
 }

This defines a struct called STRING which contains a single LTEXT item.

STRUCT TEST BYTE
 {
 WORD status;
 STRUCT text;
 }

This defines a struct called TEST which contains a WORD and an embedded struct. The total length of TEST is unknown, but should not exceed 255 characters: the BYTE directive in the definition indicates that, when this struct is embedded within another, it should be preceded with a byte indicating its length (zero to 255 characters).