Language Reference
LISTGETITEM Function
LISTGETITEM (list, position <flag> ) ;
This function is supported by the IML procedure and the iml action.
The ListGetItem function returns the value of a list item. For examples and a general discussion of using lists, see Chapter 9, Lists and Data Structures.
The function takes the following arguments:
- list
specifies an existing list.
- position
specifies a numeric matrix of indices or a character matrix of item names. Names are not case sensitive.
- flag
-
controls what happens to the list item after its value is copied. Valid values are:
- 'c'
copies the list item, but does not change it. This is the default behavior.
- 'm'
moves the list item. The item specified by position becomes empty, but the length of the list does not change.
- 'd'
deletes the list item. The length of the list decreases by one, and the indices of subsequent items are adjusted. For example, if you delete the fourth item, the fifth item becomes the fourth item, the sixth item becomes the fifth item, and so on.
For example, the following statements create a list that contains four items and assign a matrix to each item. The first item is a 
matrix, the second item is a 
matrix, the third item is a matrix, and the fourth item is a 
matrix.
L = ListCreate(4);
do n = 1 to 4;
call ListSetItem(L, n, j(n,n,n)); /* n x n matrix */
end;
x1 = ListGetItem(L, 1); /* copy value */
x2 = ListGetItem(L, 2, 'd'); /* copy value; delete item */
x3 = ListGetItem(L, 3, 'm'); /* copy value; free item */
The first call to the ListGetItem function copies the first item from the list into the x1 matrix. The list is unchanged.
The second call to the ListGetItem function copies the second item from the list into the x2 matrix. The 'd' parameter requests that the second list item be deleted. The length of the list decreases by one. After the call returns, the second item is a 
matrix and the third item is a matrix.
The third call to the ListGetItem function copies the third item from the list into the x3 matrix. The 'm' parameter requests that the third list item become an empty matrix, but leaves the length of the list unchanged.
After the program runs, the list contains three items: a matrix, a matrix, and an empty matrix.
Alternatively, if you want to copy an item from a list, you can use the list item operator ($) to extract the item. For example, the following statements set four items of a list and then retrieve the first item:
L = ListCreate(4);
do n = 1 to 4;
L$n = j(n,n,n); /* n x n matrix */
end;
x1 = L$1; /* copy value */