putitem

Add or replace an item in a list.

putitem  IndexedList,Index,ItemValue

putitem/id{/case}   AssociativeList,ItemId  {,ItemValue}

Example: putitem/id vList, "NS", "Nova Scotia"

Qualifiers

Qualifiers
Qualifier Description
/id Add or replace the list item identified by ItemId in an associative list.
/case Ensure that ItemId matches the case of the item id in the associative list.

Parameters

Parameters
Parameter Data Type Description
IndexedList

AssociativeList

String Variable or field containing the Uniface list to be modified
Index Number Sequence number of the list item to be updated; one of:.
  • -1 append as the last item in List.
  • > 0 copy to specified position. If N is greater than the number of items in List, empty items are created until the Nth item is reached.
ItemId String Id part of the list item to be updated
ItemValue String Value part of the list item to be updated

Return Values

Values returned in $status
Value Meaning
0 No item was replaced or added; the specified source is empty.
>0 Sequence number of the list item that was replaced or added.

Use

Allowed in all component types.

Description

Use the putitem statement to add or replace an item in an indexed list of values or an associative list of id=value pairs. For more information, see Lists and Sublists.

Tip: To set the initial values in a list, it is also possible to use a simple assignment. For example, to set the ValRep list of a field, assign a Gold ; separated string to $valrep: 

$valrep(DBMSFLD) = "rms;ora;syb;db2"

Indexed Lists

Use the putitem statement without qualifiers to add or replace an item in a Uniface list at the Nth position of TargetList. Items are numbered starting with 1. If N is:

  • -1, the item is added to the end of the list.
  • 0 or <-1, the item is not added
  • Greater than the number of items in List, empty items are created until the Nth item is reached.

If List contains an associative list, the entire ValRep of the associative item is replaced by Item.

An empty list cannot be distinguished from a list containing a single empty item. When an empty item is added to an empty list, the list remains empty. For example, after the following statements are executed, vList contains only one item: 

vList = "" ;an empty list
$1 = ""
putitem vList, -1, $1
putitem vList, -1, $1
putitem vList, -1, "Zeeland" 
;Result: vList contains "Zeeland"

Empty items that are added to a list that already contains at least one nonempty item are simply empty items. For example, after the following statements are executed, $LIST$ contains three items: 

vList = "" ;an empty list
$1 = ""
putitem vList, -1, "Limburg" 
; Result: vList contains "Limburg"

putitem vList, -1, $1 
;Result: vList contains "Limburg;"

putitem vList, -1, "Zeeland" 
;Result: vList contains "Limburg;;Zeeland"

Associative Lists

For associative lists, use the /id switch to replace or append the specified item in the list. By default, matching ItemId with the item values is not case-sensitive.

For example, the following statement replaces the first item in vList whose value is ab, Ab, aB, or AB with the item ab=Limburg or adds that item to the end of the list if none of these are found: 

putitem/id vList, "ab", "Limburg"

To make matching case sensitive, use the /case switch. For example, the following statement replaces or adds an item whose value is ab: 

putitem/id/case vList, "ab", "Limburg"

Using putitem

In the examples below, ; and !; ) represent the Uniface Gold subfield separators.

Building an Indexed List

The following example builds an indexed list with four items, and copies the value of the third item to the variable vItem: 

; initialize list:
$valrep(DBMSFLD) = "mss"

; Append list items:
putitem $valrep(DBMSFLD), -1, "ora"
; Result: ValRep is "mss;ora"

putitem $valrep(DBMSFLD), -1, "syb"
; Result: ValRep is "mss;ora;syb"

putitem $valrep(DBMSFLD), -1, "db2"
; Result: ValRep is "mss;ora;syb;db2"

getitem vItem, $valrep(DBMSFLD), 3
; Result: vItem is "syb"

Example: Building an Associative List

The following example:

  1. Builds an associative list with four items.
  2. Looks for an item whose ID is tue and copies the value of that item to the variable $1.
  3. Copies the value of the item whose ID is weekend to $2.
  4. Assuming that $2 now contains a list, it copies the first item in that list to $3. 
Callout 1; Initialise the list and append items to it:
$valrep(DATEFLD) = "mon=monday"
putitem/id $valrep(DATEFLD), "tue", "tuesday"
putitem/id $valrep(DATEFLD), "wed", "wednesday"
putitem/id $valrep(DATEFLD), "weekend", "sat;sun"
; Result: ValRep is "mon=monday;tue=tuesday;wed=wednesday;weekend=sat!;sun"

Callout 2; Copy "tuesday" to $1
getitem/id $1, $valrep(DATEFLD), "tue"

Callout 3; Copy "sat;sun" to $2
getitem/id $2, $valrep(DATEFLD), "weekend"

Callout 4; copy "sat" to $3
getitem $3, $2, $1

Related Topics