You can define a list from individual variables or base a list on one of the Omnis SQL data classes including schema, query, or table classes. In the latter case, the list gets its column definitions from the columns defined in the SQL class. Each list can hold an unlimited number of lines with up to 32,000 columns, memory permitting of course!
Omnis Studio provides many powerful methods to create, define, and change lists which we will look at briefly below. I suggest you refer to the List Programming chapter in the Omnis Programming guide to find out more about lists.
Creating lists on the fly
First, you need to create a list variable and additional variable to define its columns. You can then use the $define method to define the list itself. Alternatively, you can build a list definition with the $add function on the $cols group of the list.
Do myList.$define(var1, var2, var3) ;; myList & vars previously defined
In this example, a list with three columns is created. The parameters of the $add method describe the name, the type, the subtype and the length of the definition. However, depending on the column type, not all of these parameters are required.
Adding data to a list
Second, we need some sample data. You can use the $add method to add data to the list. You can pass the values directly as parameters or an empty row could be added with $add():
Do myList.$add(‘Donald’,27,kTrue) ;; adds a new row with the values passed
Do myList.$add() ;; adds an empty row
You can add the content of a row variable to a new row in the list. To do this, we can make use of the fact that the $add method returns a reference to the new list row:
Please note the brackets after the $add method. With the brackets an empty list row is created. As the function $add returns a reference the $assignrow function can add the data from myRow. The second parameter determines whether the column names or column order is used to add the data from the row to the list. You can use the $addbefore and $addafter methods to add data before or after a specific column.
Deleting rows in a list
Sometimes you may also need to delete some list rows. The easiest way of doing this is to use the $remove method. For example, if you want to delete the current row of a list it works like this:
If you want to delete several list rows that correspond to a certain condition, you can first use the $search function:
Here in the first step all rows that have the value ‘Donald‘ in the column ‘myFieldName’ will be marked as selected. Now you can delete them using:
Alternatively, you can use the kListKeepSelected constant to delete the non-selected list lines.
Copying and merging lists
Sometimes you might want to mirror lists, or copy the contents of one list into another. You can do this using the command:
Calculate NewList as OldList
You can copy the definition from one list into another using $copydefinition:
This method creates an empty list with the same definition as the initial list. You may want to add the data from one list into another list, so you can use the $merge method:
In this case the data from OldList will be added to NewList. Here the second parameter determines that we want to match the column names rather than using the column order.
If you want to remove the data from a list variable, you can use the $clear method:
If you also want to delete the column definitions in the list you can use $define without any parameters:
As illustrated above, lists are a very powerful and versatile data type in Omnis Studio. For row variables, the same rules apply except for the $search function. Added to this, if your row or list is based on a SQL table class you can build your own functions into your variable, but then that’s for another lesson!
Posted by: Andreas Pfeiffer