LOTUSSCRIPT LANGUAGE

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


End Type
ElementDescription
Public, PrivatePublic 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.
typeNameThe name of the data type.
member variable declarationsDeclarations 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 above, 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:


Working with data stored in files

You often create user-defined data types to work with data stored in files. For example, the script below and following 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.

See Also