Working with lists with LotusScript®

LotusScript® provides a number of functions and statements for use with lists.

TypeName( listName ) returns a string of the form dataType LIST, for example, STRING LIST, where dataType is the data type that appeared or was implicit in the statement that declared the list.

TypeName( listName( listTag )) returns a string of the form dataType, for example, STRING, where dataType is the data type of the specified list element. You might test for the data type of an individual element in a list when the list has been declared to be of type Variant, since Variants can hold data of a variety of types.

DataType( listName ) returns an integer equal to 2048 + dataTypeCode, for example, 2056 (2048 + 8, that is, the code for List + the code for String).

DataType( listName( listTag )) returns an integer representing the data type code of the specified element, for example, 8 (the code for String).

IsList( listName ) returns True (-1) or False (0) depending on whether listName is a list.

IsElement( listName ( stringExpr )) returns True (-1) or False (0) depending on whether stringExpr is a list tag in listName. There are a variety of circumstances under which you might want to test for the existence of a particular list tag in a list. Two cases are:

You want to add a new element to a list and want to make sure that the list tag you plan to use isn't already in use (because if it is, and you used it in an assignment statement, you would overwrite the element that it identifies).
You want to refer to an element and want to make sure that the element exists before doing so (because if you refer to a nonexistent list tag, LotusScript® returns an error).

ListTag( refVar ) returns the list tag of the element currently being processed in a ForAll loop. The refVar argument is the reference variable in a ForAll loop.

LotusScript® executes the statements in a ForAll refVar In container block for each element in the list identified by container.

Erase listName removes all the elements in listName and reclaims the storage previously allocated to them. Erase listName( listTag ) removes the individual element identified by listTag from the list and reclaims the storage previously allocated to it, leaving the rest of the list intact.

These functions are illustrated in the following example, which removes an employee's access to a parking space when the user enters a valid employee name (a valid list tag) and matching employee ID:

' Declare a list to hold employee IDs.
' The list tags will be the names of the employees.
Dim empList List As Double
' Make absolutely sure empList is Double.
If TypeName(empList) <> "DOUBLE LIST" Then
  Print "Warning: empList is " & TypeName(empList)
End If
If DataType(empList) <> 2053 Then
  Print "Warning: empList is " & CStr(DataType(empList))
  ' We expected 2053 (that is, 2048 + 5).
End If
' Declare a String variable for user name.
Dim ans As String
' Declare a Double variable for user ID.
Dim yourID As Double
' Declare an Integer variable to serve as a flag.
Dim found As Boolean
' Create some list elements and assign them values.
empList("Maria Jones") = 12345
empList("Roman Minsky") = 23456
empList("Joe Smith") = 34567
empList("Sal Piccio") = 91234
' Ask the user to enter the name to be removed from the
' list of employees who have been assigned parking spaces.
ans$ = InputBox$("Which employee no longer needs a space?")
' Check to see if the employee's name appears as a list tag
' in the list. If not, display a message and stop. Otherwise,
' validate the employee's ID. If everything checks out,
' remove the employee item from the parking list. 
If IsElement(empList(ans$)) = True then
    Print ans$ & "  is a valid employee name."
    yourID# = CDbl(InputBox$("What's " & ans$ & "'s ID?"))
    ' The following ForAll block does two things:
    ' it checks to see if yourID# is a valid ID and,
    ' if so, if it matches the ID for the employee
    ' whose name is ans$. If so, that element is removed
    ' (erased) from the list. The found flag is initially
    ' FALSE (0). If yourID# is a valid ID, found is set to
    ' TRUE (-1). The variable empID is the reference variable
    ' in the ForAll loop.
    found = FALSE
    ForAll empID In empList
        If empID = yourID# then
           found = TRUE
           If ListTag(empID) = ans$ then
              Erase empList(ans$)
              ' Verify the removal of the list element.
              If  IsElement(empList(ans$)) = FALSE then
                Print ans$ & " is no longer on the list."
             End If
           Else
              Print "Valid ID but wrong employee."
           End If
           ' No need to look further for yourID#,
           ' so get out of the ForAll loop.
           Exit ForAll
        End If
     End ForAll
     If found = False then
        Print "No such employee ID."
     End If
Else
   Print "No such employee."
End if