Using Lists in Omnis


The “List” structured data type is the single most important data type in Omnis programming. To master Omnis programming, and to build web and mobile applications in Omnis Studio, you need to get to know list variables and how to manipulate them. List variables can provide the data (content) and formatting for many of the visual list- or grid-type JavaScript components in your web and mobile forms, including droplists, menus, data grids, complex grids, and tree lists. Open the JavaScript Components Gallery and view the many list example apps.

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
Do myList.$cols.$add(‘myFieldName’,kCharacter,kSimpleChar,255)
Do myList.$cols.$add(‘anotherColumn’,kInteger,kLongInt)
Do myList.$cols.$add(‘yetAnotherColumn’,kBoolean

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:

Do myList.$add().$assignrow(myRow,kTrue)

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:

Do myList.$remove(myList.$line())

If you want to delete several list rows that correspond to a certain condition, you can first use the $search function:

Do myList.$search($ref.myFieldName=’Donald’,kTrue)

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:

Do myList.$remove(kListDeleteSelected)

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:

Do NewList.$copydefinition(OldList)

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:

Do NewList.$merge(OldList,kTrue)

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.

Clearing lists

If you want to remove the data from a list variable, you can use the $clear method:

Do myList.$clear()

If you also want to delete the column definitions in the list you can use $define without any parameters:

Do myList.$define()


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!

Leave a Reply

Your email address will not be published. Required fields are marked *


You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>