getitem

Copy an item from a list to a field or variable.

getitem  Target,IndexedList,Index

getitem/id{/case}   Target,AssociativeList,ItemId

Example: getitem/id vProvince, $valrep(STATE), "NS"

Qualifiers

Qualifiers
Qualifier Description
/id Get the item specified by Index from an associative list.
/case Both the value and the case of Index must match the item in the list

Parameters

Parameters
Parameter Data Type Description
Target String Destination of the copied item, such as a field or variable
IndexList

AssociativeList

String List containing the item to be copied
Index Number Sequence number of the list item to copy; one of:
  • -1 copy the last item in the list.
  • > 0 copy to specified position.

If Index does not refer to an existing item, no item is copied.

ItemID String ID part of an item in an associative list

Return Values

Values returned in $status
Value Description
0 No item was copied; Target is empty.
>0 Sequence number of the list item that was copied.

Use

Allowed in all component types.

Description

Use the getitem statement to copy an item from an indexed list of values or an associative list of ID=value pairs. For more information, see Lists and Sublists.

Indexed Lists

Use getitem without /id to copy an item from an indexed list, as specified by the Index position.

For example, the following code copies the third item from an indexed list to the variable vItem: 

$valrep(DBMSFLD) = "mss;ora;syb;db2" 
getitem vItem, $valrep(DBMSFLD), 3
;Result: "syb" copied to vItem

The same item could also be copied by treating the list as an associative list: 

$valrep(DBMSFLD) = "mss;ora;syb;db2"
getitem/id vItem, $valrep(DBMSFLD), "syb"

Note:  If getitem is used without /id and the specified list is an associative list, the entire ID=value pair is copied.

Associative Lists

Use getitem/id to copy the value of an associative list item identified by IdPart.

By default, matching IdPart with item values is not case-sensitive. For example, the following statement gets from vList the first item encountered whose value is ab, Ab, aB, or AB: 

getitem/id vItem, vList, "ab"

Use the /case switch to cause matching to be case-sensitive. For example, the following statement only gets an item whose value is ab: 

getitem/id/case vItem, vList, "ab"

Using getitem

In the following examples, the subfield separators (by default GOLD ;) are represented by an underlined semicolon ( ; ) or exclamation mark ( !).

Copying an Associative List Item to a Variable

The following example looks in an associative list to find an item whose ID is tue and copies the corresponding value to the variable vItem: 

$valrep(DATEFLD) = %\
"mon=monday;tue=tuesday;wed=wednesday;weekend=sat!;sun"
getitem/id vDay, $valrep(DATEFLD), "TUE"    
;Result: "tuesday" copied to vDay

Treating an Associative List as an Indexed List

The following example treats the associative list as an indexed list and copies the entire third list item from the list to the variable vDay: 

$valrep(DATEFLD) = %\
"mon=monday;tue=tuesday;wed=wednesday;weekend=sat!;sun"
getitem vDay, $valrep(DATEFLD), 3   
;Result: "wed=wednesday" copied to vItem

Finding Items in Associative Lists

The following example looks in an associative list to find the item whose ID part is weekend and copies the value of that item to the variable vWeekend. Finally, assuming that vWeekend now contains a list, it copies the first item in that list to vDay. 

$valrep(DATEFLD) = %\
"mon=monday;tue=tuesday;wed=wednesday;weekend=sat!;sun"
getitem/id vWeekend, $valrep(DATEFLD), "weekend"   ;"sat;sun" copied to vWeekend
getitem vDay, vWeekend, 1   ;"sat" copied to vDay

Related Topics