StudioTips - Classic to Studio - Omnis List Commands

Tips_classictostudio > Omnis List Commands

Omnis List Commands

If you are familiar with the Omnis commands for looping through lists, searching lists, etc., this section gives you the Omnis notation equivalents.

#L - Current Line

* $line tells you the current line number in the list. Using $assign or Calculate you can set the current line.

Either of the following will tell you the current line.

Calculate %L as List.$line
Do List.$line Returns %L

Set the current line to the value of LineN, provided LineN is between 1 and List.$linecount.

Do List.$line.$assign(LineNum)

Set the current line to zero so that there is no current line.

Do List.$line.$assign(0)

Set the current line to the last line in the list.

Do List.$line.$assign($ref.$linecount)

Remember that the selected line and the current line are not the same thing, they can be different.

#LM - Maximum Lines

Set the maximum number of lines in the list.

Do List.$linemax.$assign(100)

#LN - Linecount

Either of the following will tell you the total number of lines in the list.

Calculate %LN as List.$linecount
Do List.$linecount Returns %LN

Add line to list

The $add function is used all over the place in Omnis Studio. With respect to lists it is used to add rows or add columns. Also see $remove for various ways to delete line(s) from a list.

Do List.$add([Col1Value,Col2Value,...]) Returns rLine

Adds an empty row to the end of the list. If you include values, they will be added by column number.
$add does not change the current line in the list.

Avoid immediately setting the column values in the $add line. Code that depends on the column order is fragile. If the schema class or method that defined the list changes the order of the columns your code is broken. It is much safer to add the line to the list, set the current line, and then calculate the column values by name.

You can use rLine in your calculations immediately following $add

Do List.$add() Returns rLine
Calculate rLine.ColName as 'ABC'

or you can use rLine.$line to assign the current line immediately following $add

Do List.$add() Returns rLine
Do List.$line.$assign(rLine.$line)
Calculate List.ColName as 'ABC'

or you can use $ref.$linecount to assign the current line immediately following $add since it will always the last line.

Do List.$add()
Do List.$line.$assign($ref.$linecount)

To add a line before another line, use $addbefore.

Do List.$addbefore(LineNum [,Col1Value,Col2Value,...]) Returns rLine

This adds an empty row before LineNum in the list. If LineNum=0, the current line will be used. $addbefore does not change the current line in the list!

To add a line after another line, use $addafter.

Do List.$addafter(LineNum [,Col1Value,Col2Value,...]) Returns rLine

This adds an empty row after LineNum in the list. If LineNum=0, the current line will be used. $addafter does not change the current line in the list.

Build list columns list

To build a list of columns of a list.

Do List.$cols.$makelist($ref().$name,$ref.$objtype,$ref.$objsubtype,$ref.$objsublen) Returns ColsList

This produces a four column list. The columns are not named. You can reference the columns by the column aliases C1,C2,C3,C4 or $assign the column names.

Clear line in list

Do List.[LineNum].$clear()

Where LineNum is the line number to be cleared. You can use zero for the current line.

Clear list

Do List.$clear()

Clears the list. The list definition remains.

You must include the open and close () parenthesis with Do List.$clear().

Copy list definition

Do List2.$copydefinition(List1)

Define list

There are many ways to define a list in Omnis Studio.

The most common methods which I use are:

$definefromsqlclass
$cols.$add()
Calculate List2 as List1

The SQL classes in Omnis Studio are schema classes, query classes, and table classes. Table classes have a $sqlclassname property which points the table class to a schema class or query class to be used for the table class' list definition. There are several ways to define a list from a SQL class.

Do ListRow.$definefromsqlclass([LibName.] TableSchemaOrQueryClassName)
Do List.$definefromsqlclass('t_author')
Do List.$definefromsqlclass(TableSchemaOrQueryClassRef)

The list is defined to match all the columns listed in the schema or query class.

The $definefromsqlclass has become a favourite for me. Fast and easy, a very handy command. I will sometimes create a dummy schema class which I just use for defining a list. The dummy schema class is never used for database communication.

If you use table classes (and you should), $definefromsqlclass binds an instance of the table class to the list/row variable. Once the variable is bound to the table class you have direct access to all of the table class methods from the variable. This is similar to object type variables where the object class is bound to the object type variable.

You can add columns to a list or row variable use $cols.$add notation.

Do ListRow.$cols.$add(variable|'ColName' [,kDataType,kDataSubtype,iMaxLen]) Returns ColRef

It took me a while to catch on to this one, but now I use it all the time. Use the F9 Catalog > Constants tab > Data types and Data subtypes for find the correct kContant variables.

; Define a 3 column list.
Do List.$cols.$add('name',kCharacter,kSimplechar,200)
Do List.$cols.$add('total',kInteger,kLongint)
Do List.$cols.$add('Active',kBoolean)

You can also use a variable which you've already defined. The column name becomes the variable name.

Do List.$cols.$add(Name)

You can also use $addbefore, $addafter on $cols.

Do List.$cols.$addbefore(1,'Test',kBoolean)
Do List.$cols.$addafter(2,'Test2',kBoolean)

$addbefore and $addafter will not work with lists or rows that were defined using $definefromsqlclass. You can only $add columns to those lists.

You can move the column to a new position using the $ident .

Do List.$cols.1.$ident.$assign(3)

You can also use $cols.$remove to remove columns, except on list/rows which were $definefromsqlclass.

Do List.$cols.$remove(rCol)

You can make a copy of a list using Calculate.

Calculate ListB as ListA

This copies the list definition and data from one list to another.

You can copy the current row in a list to a row variable.

Calculate Row as List

If the list is large, Calculate Row as List, is very slow. You are better to Calculate Row as List when the list is empty, and then use Row.$assignrow(List) in the loop.

Delete line in list

* $remove can be used for removing line(s) in a list.

Remove the current line.

Do List.$remove(0)

Remove LineNum.

Do List.$remove(LineNum)

Delete selected lines

Delete the selected lines, remove the rest.

Do List.$remove(kListDeleteSelected)

Keep the selected lines, remove the rest.

Do List.$remove(kListKeepSelected)

$remove is one of my favourite list methods. Used with the $search, and $merge, you can do some very powerful work.

Deselect list line(s)

Deselect the current line.

Do List.0.$selected.$assign(kFalse)

Deselect line 3.

Do List.3.$selected.$assign(kFalse)

Deselect all lines.

Do List.$search(kFalse)

For each line in list

There are several methods for looping through a list of records using notation. The best ones I've found are listed below.

Loop through all the lines in a list.

For List.$line from 1 to List.$linecount step 1

; The current line is automatically set by the For loop

End For

Loop through the selected lines in a list.

Do List.$first([bOnlySelectedNY,bBackwardsNY])
Do List.$next(LineN,[bOnlySelectedNY,bBackwardsNY])

Do List.$first(kTrue) ;; Only Selected Lines
While List.$line

; The current line is automatically set by $first, then $next
Do List.$next(0,kTrue) ;; 0=starting with the current line, kTrue=next selected line

End While

Go to next selected line

Along with $first, $next is useful for looping through selected lines in a list.

Do not use this for looping through all lines in a list. A For loop is faster if you have to loop through all the lines.

Insert line in list

See $addafter and $addbefore in the Add line to list topic.

Invert selection for line(s)

Invert selection for the current line.

Do List.0.$selected.$assign(not($ref.$selected))

Replace zero with a specific line number to select any line in the list.

Do List.3.$selected.$assign(not($ref.$selected))

You can invert selection for all lines in a list using $sendall.

Do List.$sendall($ref.$selected.$assign(not($ref.$selected)))

Load from list

Load the columns into the specfied variables.

Do List.$loadcols(VARIABLE1,VARIABLE2,...)

Use of this command tends towards fragile code. If the list column order changes, your code will break.

Merge list

Merge the data from List2 into List1. List2 must be defined before the $merge is executed. Omnis Studio won't define the list for you.

Do List1.$merge(List2 [,bMatchColNamesNY,bOnlySelectedNY])

Match by column number. Merge all lines.

Do List1.$merge(List2)

Match by column name. Merge all lines.

Do List1.$merge(List2,kTrue)

Match by column name. Merge selected lines only.

Do List1.$merge(List2,kTrue,kTrue)

Match by column number. Merge selected lines only.

Do List1.$merge(List2,kFalse,kTrue)

You can merge a Row into a List.

Do List1.$merge(Row)

Redefine list

There are various methods you can use to redefine a list. $cols.$add, $cols.$addbefore, $cols.$addafter.

Do ListRow.$cols.$add(variable|'ColName' [,kDataType,kDataSubtype,iMaxLen]) Returns rCol

To rename a column.

Do List.$cols.2.$name.$assign('NewColName')

To move column 1 to column 3

Do List.$cols.1.$ident.$assign(3)

To remove a column.

Do List.$cols.$remove(rCol)

You can not move or remove a column in a list that has been defined using $definefromsqlclass.

Replace line in list

Assign row values to current line in the list without matching column names.

Do List.$assignrow(Row)

Assign row values to current line in the list and matching column names.

Do List.$assignrow(Row,kTrue)

Assign values from the current line in List2 to the current line in List1. Match the column names.

Do List1.$assignrow(List2,kTrue)

Adds a line to the list and immediately assign the values from the row to the added line. Match the column names.

Do List.$add().$assignrow(Row,kTrue)

If you want the added line to be the current line you must set it after adding the line.

Search list

The $search method is very useful. Remembering the 4 parameters is the harder part of using this method. I keep forgetting the order and have to check back with the documentation to make sure I've got them right.

Do List.$search(SearchCriteria [,kFromStartYN,kOnlySelectedNY,kSelectMatchesYN,kDeselectNonMatchesYN])

If parameters 3 and 4 are set to kFalse, $search will set the current line in the list to the first matched line, otherwise $search does not change the current line.

To select or deselect all the lines in a list.

Do List.$search(kTrue) ;; Select all lines
Do List.$search(kFalse) ;; Deselect all line

To select all the lines in a list which have the CityName of Orlando.

Do List.$search($ref.CityName='Orlando')

To do a case-insensitive search for Orlando, orlando, or ORLANDO.

Do List.$search(low($ref.CityName)='orlando')

The following $search will select the first matching line, set it to be the current line, and return the line number.

Do List.$search($ref.ColName=Value,kTrue,kFalse,kFalse,kFalse) Returns LineNum

The above search is a common one to use. I got tired of typing the kTrue,kFalse,kFalse,kFalse, and switched to using ones (1) and zeroes (0).

Do List.$search($ref.ColName=Value,1,0,0,0) Returns LineNum

You can use this $search in an If statement to test if a line matching your search criteria exist. If the test is true, the current line is immedately set for you as well.

If List.$search($ref.ColName=Value,1,0,0,0)

  ; The value was found and the current line is set

Else

  ; The value was not found in the list and the current line is zero.

End if

You can get quite creative with the search criteria. You can use arguments like:

pos('abc',$ref.ColName)>0
len($ref.ColName)>5

Do not use $ref in the comparison value. The following search would fail.

Do List.$search($ref.Col1Name=$ref.Col2Name)

This following search would succeed.

Do List.$search($ref.Col1Name=List.Col2Name)

Select list line(s)

Select the current line.

Do List.0.$selected.$assign(kTrue)

Replace zero with a specific line number to select a specific line in the list.

Do List.3.$selected.$assign(kTrue)

Select all lines.

Do List.$search(kTrue)

Set current list

You shouldn't be using this command. See the topic Set Current.

Set final line number

Use $linemax to set the final line number.

Do List.$linemax.$assign(%LN)

Where %LN = the maximum number of lines for the list.

Sort list

You can have up to 9 columns using $sort.

Do List.$sort($ref.ColName|$ref.C# [,bDescendingNY,$ref.ColName,bDescendingNY,...])

Sort the list by the ColName column, ascending.

Do List.$sort($ref.ColName)

Sort the list by the ColName column, descending.

Do List.$sort($ref.name,kTrue)

Sort the list by the Col1Name column, ascending, Col2Name column, descending.

Do List.$sort($ref.Col1Name,kFalse,$ref.Col2Name,kTrue)

Sort the list on column number 3 without having to specify the column name.

Do List.$sort($ref.C3)

C# is a column alias which you can use anywhere to refer to a column by its column number, rather than the column name. Be forewarned that code which depends on the column number is fragile code and is harder for read. Only use the column number if the list is not being passed in or out of the method where you are are defining the list and using C#.

Sort the list on the uppercase values of the ColName column, descending

Do List.$sort(upp($ref.name))

Swap lists

Not sure how often you'd use this. I think you'd have to use a 3rd temp list to accomplish this.

Calculate TempList as List1
Calculate List1 as List2
Calculate List2 as TempList
Do TempList.$clear()

Test for list line selected

$selected

tells you whether or not a line is currently selected.

Either of the following will set the bSelected boolean variable based on the current line in the list is selected.

Calculate bSelected as List.0.$selected
Do List.0.$selected Returns bSelected

Replace zero with a specific line number to find the selection state any line in the list.

Do List.3.$selected Returns bSelected

tot(#LSEL)

The tot(#LSEL) function is used to return the number of lines selected in a list. The tot() function defaults to the current list, but since we want to avoid the Omnis command Set current list, we need to specify the list.

Calculate LinesSelected as tot(List,#LSEL)

Even though this command uses a hash variable the object-oriented police are okay with it because we can specify the list and the hash variable value is immediately calculated to a local variable.