User-defined types (UDTs) are structure definitions created using the Type statement. UDTs are equivalent to C language structures.

Declaring Structures

The Type statement is used to create a structure definition. Type declarations must appear outside the body of all subroutines and functions within a script and are therefore global to an entire script.

Once defined, a UDT can be used to declare variables of that type using the Dim, Public, or Private statement. The following example defines a rectangle structure:

  Type Rect
    left As Integer
    top As Integer
    right As Integer
    bottom As Integer
  End Type
    :
  Sub Main()
    Dim r As Rect
      :
    r.left = 10
  End Sub

Any fundamental data type can be used as a structure member, including other user-defined types. Only fixed arrays can be used within structures.

Copying Structures

UDTs of the same type can be assigned to each other, copying the contents. No other standard operators can be applied to UDTs.

  Dim r1 As Rect
  Dim r2 As Rect
    :
  r1 = r2

When copying structures of the same type, all strings in the source UDT are duplicated and references are placed into the target UDT.

The LSet statement can be used to copy a UDT variable of one type to another:

  LSet variable1 = variable2

LSet cannot be used with UDTs containing variable-length strings. The smaller of the two structures determines how many bytes get copied.

Passing Structures

UDTs can be passed both to user-defined routines and to external routines, and they can be assigned. UDTs are always passed by reference.

Since structures are always passed by reference, the ByVal keyword cannot be used when defining structure arguments passed to external routines (using Declare). The ByVal keyword can only be used with fundamental data types such as Integer and String.

Passing structures to external routines actually passes a far pointer to the data structure.

Size of Structures

The Len function can be used to determine the number of bytes occupied by a UDT:

  Len(udt_variable_name)

Since strings are stored in the Basic Control Engine's data space, only a reference (currently, 2 bytes) is stored within a structure. Thus, the Len function may seem to return incorrect information for structures containing strings.

U