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
| 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
| 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:
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
| 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
