Lists Notation

This section covers, in alphabetic order, notational commands which are related to lists.

$add,$addbefore,$addafter

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

This section covers adding lines to a list. See $cols.$add for adding columns to lists or rows.

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!

You can use rLine in your calculations immediately following $add

; You can use rLine in a calculation after after a line.
Do List.$add() Returns rLine
Calculate rLine.ColName as 'ABC'

; You can use LineRef.$line to assign the current line immediately following $add
Do List.$add() Returns rLine
Do List.$line.$assign(LineRef.$line)
Calculate List.ColName as 'ABC'

; You can use $ref.$linecount to assign the current line immediately after $add.
Do List.$add()
Do List.$line.$assign($ref.$linecount)
Calculate List.ColName as 'ABC'

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

Adds an empty row before LineNum in the list. If you include values, they will be added by column number. If LineNum=0, the current line will be used.

$addbefore does not change the current line in the list!

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

Adds an empty row after LineNum in the list. If you include values, they will be added by column number. If LineNum=0, the current line will be used.

$assigncols

Do List.$assigncols(VALUE1,VALUE2,...)

$assignrow

Do List1.$assignrow(List2 [,bMatchColNames])

Assigns the values in the current line of List2 to the current line of List1.

If you include the optional parameter bMatchColNames as kTrue, the column names will be matched, otherwise column number is used.

; Assign row values to current line in the list.
Do List.$assignrow(Row,kTrue) ;; (Match column names)

; Assign values from the current line in List2 to the current line in List1.
Do List1.$assignrow(List2,kTrue) ;; (Match column names)

; Adds a line to the list and immediately assign the values from the row to the added line.
Do List.$add().$assignrow(Row)

$average

Average values in the list for the specified column. Boolean parameter allows you to specified selected lines only. Default is kFalse.

; Average of the values in a column of the list.
Calculate Average as List.$cols.ColName.$average()

; You can add the parameter kTrue to include selected lines only.
Calculate Average as List.$cols.ColName.$average(kTrue) ;; (Selected lines)

$clear

Do List.$clear()

Clears the list leaving the list definition in tact.

Do List.[LineNum].$clear()

Clears the column values in the LineNum. If LineNum=0 the current line column values are cleared.
Do Row.$clear()

Clears the column values in the row.

Do List.$cols.ColName.$clear()

$colcount

The number of columns in a list or row

$cols.$add,$addbefore,$addafter

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. You can start with an undefined list or row variable and use $cols.$add to completely define the list.

I used to think figuring out the extra kConstants was too much of a hassle, but now that I found the F9 Catalog > Constants tab > Data type and Data subtypes, it's much quicker and easier to use.

Example: 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(VarName)

If you use a local variable, the column name is lost when you leave the scope of the class instance. Because of this, and the fact that I first have to declare the variable, I rarely use a variable with $cols.$add()

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

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

You can move a column to a new position using the $ident
Do List.$cols.1.$ident.$assign(3)

You can also use $cols.$remove(rCol).
Do List.$cols.$remove(rCol)

Omnis Studio will not let you affect the original columns of a list or row defined using $definefromsqlclass. Omnis Studio will ignore $addbefore, $addafter, $ident.$assign, $name.$assign, or $remove if it affects the original columns of a list or row that has been defined using $definefromsqlclass. The reason for this is that SQL statements generated for you by Omnis Studio depend on the original set of columns that are mapped to the schema or query class.

$cols.$remove

You can use $cols.$remove(rCol), except on the original columns of lists or rows defined using $definefromsqlclass.

; Remove column 2.
Do List.$cols.$remove($ref.$cols.2)

$count

Count the number of non-null values in the list for the specified column. Boolean parameter allows you to specified selected lines only. Default is kFalse.

; Count the number of non-null values in a column of the list.
Calculate Count as List.$cols.ColName.$count()

; You can add the parameter kTrue to include selected lines only.

; Count the number of non-null values in a column of the list, selected lines only.
Calculate Count as List.$cols.ColName.$count(kTrue) ;; (Selected lines)

$define

Do List.$define()

If a list is already defined, this removes all the columns. Handy to use if you want to make sure a list has no columns before you issue the first Do List.$cols.$add(...

You can define a list using actual varaiables.

Do List.$define(Variable1,Variable2,Variable3)

One problem I've had with this format of the List.$define command, is if you use local variables for defining the list, the column names are lost when you leave the scope of the class instance. The data remains in tact, but the column names are gone.

I rarely use this format because I don't like having to first define a bunch of variables and then define the list. I like being able to define a list and store data in it without having the column names exist as variables anywhere.

$definefromsqlclass

• Do List.$definefromsqlclass("[LibName.] SchemaTableOrQueryClassName")
• Do List.$definefromsqlclass(SchemaTableOrQueryClassRef)

$first & $next

$first

and $next are useful for looping through selected lines in a list.

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

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

; Selected lines loop.
Do List.$first(kTrue) ;; 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

$line

$line

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

; Set %L to equal the current line in the list.
Calculate %L as List.$line
; or
Do List.$line Returns %L

; Set the current line to line 3.
Calculate LineNum as 3
Do List.$line.$assign(LineNum)

; Set the current line to zero. 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)

$linecount

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

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

$linemax

Do List.$linemax.$assign(100)

$loadcols

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

$maximum

Maximum value in the list for the specified column. Boolean parameter allows you to specified selected lines only. Default is kFalse.

; The maximum value in the specified column in the list.
Calculate Maximum as List.$cols.ColName.$maximum()

; You can add the parameter kTrue to include selected lines only.
Calculate Maximum as List.$cols.ColName.$maximum(kTrue) ;; (Selected lines)

$merge

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

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

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 name. Merge all lines only. First clear the list
Do List1.$merge(List2,kTrue,kFalse,kTrue)

You can merge a Row into a List.
Do List1.$merge(Row)

To make your code more readable for yourself and other developers, it is a good habit to comment the true/false parameters, or declare local variable with their initial value value set to the boolean value you want to use.


; Merge list. Match by column name. Merge selected lines. First Clear the list.

; Code without parameter comments.
Do List1.$merge(List2,kFalse,kTrue,kTrue)

; Code with parameter comments.
Do List1.$merge(List2,kTrue,kTrue,kTrue) ;; (Match column names, Selected lines, Clear list)

; Code with local variable parameters preset using Init. Value/Calc.
Do List1.$merge(List2,bMatchColumnNames,bSelectedLines,bClearList)

$minimum

Minimum value in the list for the specified column. Boolean parameter allows you to specified selected lines only. Default is kFalse.

; The minimum value in the specified column in the list.
Calculate Minimum as List.$cols.ColName.$minimum()

; You can add the parameter kTrue to include selected lines only.
Calculate Minimum as List.$cols.ColName.$minimum(kTrue) ;; (Selected lines)

$next & $first

$remove

Once you search and select lines in a list you often will either want to remove the lines or merge them. If you want to remove lines, then $remove is the ticket.

; Remove the current line.
Do List.$remove(0)

; Remove a specific line.
Calculate LineNum as 5
Do List.$remove(LineNum)

; Keep the selected lines, remove the rest.
Do List.$remove(kListKeepSelected)

; Delete the selected lines, leave the rest.
Do List.$remove(kListDeleteSelected)

$removeduplicates

Do List.$cols.ColName.$removeduplicates(bSortNY,bIgnoreCaseNY)

$search

Searching, selecting lines and deselecting lines in list is something I do a lot. When I started using Omnis Studio, I worked with smartlist filters, but later found $search with $remove to be much much faster.

Do List.$search(SearchCriteria [,kFromStartYN,kOnlySelectedNY,kSelectMatchesYN,kDeselectNonMatchesYN])
Do List.$search($ref.ColumnName=Value)

Do not use $ref in the Value, the search will fail if you try. If you want Value to be another column in the list on the same line use List.OtherColumnName in place of Value. The Value can be a calculation such as pos('doug',low(List.FirstName))>0.

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

$search returns the line number of the first match found, or zero if no matches found

To select or deselect all lines in a list:

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

To search all the lines in the list for the first matching value and set that line to the current line:

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

By setting parameters 3 & 4 to kFalse (meaning don't select matches and don't deselect non-matches) the $search will change the current line to the first line which is found. If no matching line is found, %L will be zero.

You can use $search in an If statement to test whether or not a matching record was found in a list.


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

If List.$search(pos('doug',low($ref.FirstName))>0)
OK message (Icon) {'Doug' was found in the list.}
Else
OK message (Icon) {'Doug' was NOT found in the list.}
End If

; Search with special arguments.
If List.$search(low($ref.FirstName)='john'&low($ref.LastName)='smith')
OK message (Icon) {'John Smith' was found in the list.}
Else
OK message (Icon) {'John Smith' was NOT found in the list.}
End If

You can get quite creative with the search criteria!

You can use arguments like:

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

Do not use $ref in the Value. The search will fail if you try.

; This does NOT work.
Do List.$search($ref.ColumnName=$ref.OtherColumnName)

; This does work.
Do List.$search($ref.ColumnName=List.OtherColumnName)

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

$selected

$selected

tells you whether or not a line is currently selected. Using $assign you can select or deselect the line.

; Is the current line selected?
Calculate bSelected as List.0.$selected

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

; Set the current line to selected.
Do List.0.$selected.$assign(kTrue)
; Replace zero with a specific line number to set any line in the list.

; Select all the lines in the list.
Do List.$search(kTrue)

; Deselect all the lines in the list.
Do List.$search(kFalse)

; You can invert selection for all lines in a list using $sendall.
Do List.$sendall($ref.$selected.$assign(not($ref.$selected())))

; Total selected lines in the list.
Calculate %N as List.$totc(#LSEL)

$sendall

$sendall

is a powerful function with many different uses in Omnis Studio.

$sort

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

You can have up to 9 columns in the $sort.

; Sort the list by the "LastName" column, ascending.
Do List.$sort($ref.LastName)

; Sort the list by the "DateOrdered" column, descending.
Do List.$sort($ref.DateOrdered,kTrue)

; Sort the list by the "LastName/FirstName" ascending.
Do List.$sort($ref.FirstName,kFalse,$ref.LastName,kFalse)

; Sort the list on column number 3 without having to specify the column name.
Do List.$sort($ref.C3)

; Sort the list on the uppercase values of the "LastName" column, ascending.
Do List.$sort(upp($ref.LastName),kFalse)

$total

Total sum value of the specified column in the list. Boolean parameter allows you to specified selected lines only. Default is kFalse.

; Total of the values in a column of the list.
Calculate Total as List.$cols.ColName.$total()

; You can add the parameter kTrue to include selected lines only.

; Total value of the values in a column of the list, selected lines only.
Calculate Total as List.$cols.ColName.$total(kTrue) ;; (Selected lines)

Use $totc to find the total number of selected lines in list.

; Number of selected lines in a list.
Calculate %N as List.$totc(#LSEL)

$totc

$totc(expression)

StudioTips Documentation - Copyright 2006 Vencor Software