User-defined data types

User-defined data types are a common feature in BASIC programming and are used to support database, file read/write, and print operations. A user-defined data type lets you group data of different types in a single variable. This data type can contain any kind of related information you want to store and use together, such as personnel information, company financial information, inventory, and customer and sales records. A variable of a user-defined data type holds actual data, not a pointer to that data.

The syntax is :

[ Public | Private ] Type typeName

member variable declarations

End Type

Element

Description

Public, Private

Public specifies that the data type is accessible outside the module in which it is defined. Private (default) specifies that the data type is accessible only within the module in which it is defined.

typeName

The name of the data type.

member variable declarations

Declarations for members of the type. Member variables can hold scalar values, Variants, fixed arrays, or other user-defined data types. A member variable declared as Variant can hold fixed or dynamic arrays, a list, or an object reference, in addition to any scalar value. Declarations cannot include Const statements.

While member variable declarations resemble those of local variables declared in a function, LotusScript® allocates space for them only when an application creates the user-defined data type. When this happens, LotusScript® allocates space for all the member variables at the same time.

User-defined data types cannot contain procedures (properties and methods) and cannot be extended.

This example shows how you could create an Employee data type that contains three member variables (ID, lastName, and firstName) to hold database records of employee information:

Employee table containing ID, Last, and First variables

Declaring a variable of a user-defined data type

After you define a user-defined data type, you can declare a member variable.

For example:

Dim President As Employee ' Create a single employee record.

If you want to hold data from many database records, you can declare an array of member variables.

For example:

Dim Staff(10) As Employee ' Create an array of ten employee    ' records.

Referring to member variables

Use dot notation (object.memberVariable) to refer to member variables. Use an assignment statement to assign values.

President.ID = 42
President.lastName = "Wilkinson"
President.firstName = "May"

You can refer to the elements of a member variable that is an array or list:

Staff(1).ID = 1134
Staff(1).lastName = "Robinson"
Staff(1).firstName = "Bill"

Staff(2).ID = 2297
Staff(2).lastName = "Perez"
Staff(2).firstName = "Anna"

You can retrieve data from member variables by assigning a member variable value to a variable or printing the value of a member variable:

Dim X As String
X$ = Staff(2).lastName
Print X$              ' Prints Perez.

Conserving memory when declaring member variables

Members of a user-defined data type are not necessarily stored in consecutive bytes of memory. You can use data space efficiently by declaring members with the highest boundary first and those with the lowest boundary last. Wasted space in the definition becomes wasted space in every variable of that user-defined data type.

This example shows a well-aligned variable:

Type T1
  m1 As Variant     ' 16 bytes
  m2 As Double      '  8 bytes
  m3 As Long        '  4 bytes
  m4 As String      '  4 bytes
  m5 As Integer     '  2 bytes
  m6(10) As Integer '  2 bytes
  m7 As String * 30 '  1 byte
End Type

LotusScript® stores a variable of a user-defined data type on a boundary equal to the size of its largest member.

This example, continued from the preceding, shows how each variable of user-defined data type T1 is aligned on a 16-byte boundary.

Type T2
  m1 As T1'16-byte boundary;T1's largest member boundary is 16.
  m2(3) As Long     ' 4 bytes.
End Type

When you declare member variables:

  • A fixed-length string is not aligned on any boundary.
  • A fixed array is aligned on the boundary of its declared data type.
  • The order for data types that align on the same boundary is not important. For example:
    Dim x As Long
    Dim y As String

    is as efficient as

    Dim y As String
    Dim x As Long

Working with data stored in files

You often create user-defined data types to work with data stored in files. For example, the following script and illustration read a sample ASCII file that contains employee parking information into an array of user-defined data types:

Comma-delimited text file containing employee ids, names, etc.

Type RecType
  empID As Double                ' Employee ID
  employee As String             ' Employee name 
  theSection As Integer          ' Car parking section
  theSpace As Integer            ' Designated parking space
  theFloor As Integer            ' Car parking level
  

End Type
       
' Dynamic array sizes to fit the lines in the file.
Dim arrayOfRecs() As RecType 
  
Dim txt As String
Dim fileNum As Integer
Dim counter As Integer
Dim countRec As Integer
Dim found As Boolean

fileNum% = FreeFile        ' Get a file number to open a file.
counter% = 0
Open "c:\myfile.txt" For Input As fileNum%
Do While Not EOF(fileNum%)
    Line Input #fileNum%, txt$  ' Read each line of the file.
    counter% = counter% + 1     ' Increment the line count.
Loop
Seek fileNum%, 1                ' Pointer to beginning of file
' Since file has counter% number of lines, define arrayOfRecs  ' to have that number of elements.
ReDim arrayOfRecs(1 To counter%)
' Read the file contents into arrayOfRecs.
For countRec% = 1 to counter%    
   Input #fileNum%, arrayOfRecs(countrec%).empID, _  
     arrayOfRecs(countRec%).employee, _
     arrayOfRecs(countrec%).theSection, _
     arrayOfRecs(countrec%).theSpace, _ 
     arrayOfRecs(countrec%).theFloor
Next
Close fileNum%
' Elicit an employee's name and look for it in arrayOfRecs.
ans$ = InputBox$("What's your name?")
found = False
For x% = 1 To counter%
   If arrayOfRecs(x%).employee = ans$ Then
       found = True
       Print "Greetings, " & ans$ & "."
       Exit For
   End If
Next
If found = False Then Print "No such employee.