List Handling in ProcScript

Uniface provides ProcScript instructions that enable you to build lists, retrieve items from lists, and sort lists based on various criteria.

ProcScript for List Handling
Statement Action
delitem Remove a single item from a list.
forlist, forlist/id Defines a loop that processes each item in a list.
getitem Copy a single list item to a field or variable.
getlistitems Copy a group of list items to fields or variables.
putitem Copy a field or variable into a list item.
putlistitems Copy fields or variables into a group of list items.
$fieldvalrep Return or set the ValRep list for an instance of a field.
$valrep Return or set the ValRep used by a widget for a field.
$idpart Return the ID part of an associative list item.
$item Return the value that corresponds to a given ID in an associative list.
$itemcount Return the number of items in the list
$itemnr Return the list item that corresponds to a given sequence number in a list.
$valuepart Return the value part of an associative list item.

Building Lists

You can initialize a list using an assignment statement. For example, you can assign a list to a variable, and set it as the ValRep of a field:

vCountries = "=none;US=United States;UK=United Kingdom;SP=Spain"
$valrep(COUNTRY) = vCountries

You can use putitem to add an item to an indexed list, or putitem/id to add an associative list item. For example, to add German to the previous list:

putitem/id vCountries, "DE", "Germany"
; vCountries now contains "=none;US=United States;UK=United Kingdom;SP=Spain;DE=Germany

Remove all the items from a list by assigning an empty string: 

vCountries=""

Referencing List Items

Any list can be treated either as an indexed list or as an associative list. Consider the vCountries list created above.

To retrieve the representation of the third item in the list, use $itemnr(3) to retrieve the third item (treating the list as an indexed list), and use $idpart and $valuepart to retrieve the individual values of the associative list item:

vListItem = $itemnr(3, vCountries)
COUNTRY = $valuepart(vListItem)       ;returns "United Kingdom"
CODE = $idpart(vListItem)           ;returns "UK"

To retrieve the value associated with a specific ID, you can use $item. For example:

if ($item(COUNTRY, vCountries) = "United Kingdom")
   TELCODE = "44"
endif

Storing Lists

To store a list in a database field, the field should have data type String with packing codes C* or W*.

For more information, see Sorting Lists and Sublists.

ValRep Lists

Some widgets (radio groups and drop-down lists, for example) can deal with ValRep items in associative lists. The ProcScript functions $valrep and $fieldvalrep are useful in handling these widgets. For example:

$valrep(DATEFLD) = "mon=monday"
putitem/id $valrep(DATEFLD), "wed", "wednesday"
putitem/id $valrep(DATEFLD), "weekend", "sat;sun"

When using a Boolean value for the value part of a ValRep, only certain values are allowed. For a true value, use T, t, Y, y, or 1. For a false value use F, f, N, n, or 0. These values are completely disassociated from any packing code.

Related Topics