SETITEMC, SETITEML, SETITEMN, and SETITEMO

SETITEMC, SETITEML, SETITEMN, and SETITEMO

Store a value at an indexed position in an SCL list

Category: List

Syntax
Details
See Also

Syntax

rc=SETITEMC(list-id,cval<,index<,autogrow>>);

rc=SETITEML(list-id,sublist-id<,index<autogrow>>);

rc=SETITEMN(list-id,nval<,index<,autogrow>>);

rc=SETITEMO(list-id,object-id<,index<,autogrow>>);

rc

is the list-id, which is the identifier of the modified list.

Type: Numeric

list-id

is the identifier of the list into which the value is stored. An invalid list-id produces an error condition.

Type: Numeric or List

cval

is the character value for SETITEMC to store in the list.

Type: Character

sublist-id

is the identifier of the sublist for SETITEML to store in the list. An invalid sublist-id produces an error condition.

nval

is the numeric value for SETITEMN to store in the list.

Type: Numeric

object-id

is the identifier of the object for SETITEMO to store in the list. An invalid object-id produces an error condition.

Type: Numeric or Object

index

is the position of the item in the list. The position can be specified as a positive or negative number. By default, index is 1 (the first item). If index is a positive number, then the item is at position index from the beginning of the list. If index is a negative number, then the item is at position ABS(index) from the end of the list. An error condition results if the absolute value for index is zero or if it is greater than the number of items in the list.

Type: Numeric

autogrow

specifies whether the list can expand to accommodate a new item:

`'N'`	The size of the list cannot change. (This is the default.)
`'Y'`	The size of the list can increase to accommodate a new item that is being added to the list. The list expands only if *index* is greater than the current number of items in the list and the list does not have the FIXEDLENGTH attribute.

Type: Character

Details

Using SETITEMC, SETITEML, SETITEMN, or SETITEMO is analogous to assigning a character, a sublist identifier, a numeric value, or an object identifier, respectively, to an indexed item in an array. Index specifies the position in the list of the item whose value is assigned. If autogrow is Y , then index can be greater than the length of the list. These functions then expand the list to a total of index items. They also set all other new items to missing values, and they place the new value into the list. These functions can add items only to the end of a list. Use INSERTC, INSERTL, INSERTN, or INSERTO to insert values elsewhere in a list.

SETITEMC, SETITEML, SETITEMN, and SETITEMO replace an existing item in a list and even change its type unless the item or the list has the FIXEDTYPE attribute.

SETITEMC, SETITEML, SETITEMN, and SETITEMO do not make a copy of the list before assigning the new item. The list is modified in place.

Note: The return value of these functions is not used to indicate whether an error has been detected. When an error occurs, the program simply halts. [cautionend]

An error condition results

if the absolute value of index is zero, or if it is greater than the number of items in the list and autogrow is N.
if the absolute value of index is greater than the length of the list and the list has the FIXEDLENGTH attribute (even if autogrow is Y).
if the list or item has the NOUPDATE attribute.
if the list or item has the FIXEDTYPE attribute and the function attempts to set the item to a different type. For example, if item 4 is numeric and has the FIXEDTYPE attribute, then the following statement fails:
```
list=setitemc(list,'abc',4);
```
with SETITEMC or SETITEML, if the list has the NUMONLY attribute.
with SETITEMN or SETITEML, if the list has the CHARONLY attribute.
with SETITEML, if sublist-id identifies a local list and list-id identifies a global list. (You cannot place local lists into global lists.)

To check the attributes of a list or list item, use HASATTR. To change attributes, use SETLATTR.

See Also

GETITEMC, GETITEML, GETITEMN, and GETITEMO

INSERTC, INSERTL, INSERTN, and INSERTO

NAMEITEM

SETNITEMC, SETNITEML, SETNITEMN, and SETNITEMO

Chapter Contents
Previous
Next
Top of Page