SETNITEMC, SETNITEML, SETNITEMN, and SETNITEMO

SETNITEMC, SETNITEML, SETNITEMN, and SETNITEMO

Assign a value to a named item in an SCL list

Category: List

Syntax
Details
See Also

Syntax

rc=SETNITEMC(list-id,cval,name,<occurrence
<,start-index <,index<,forceup>>>>);

rc=SETNITEML(list-id,sublist-id,name,<occurrence
<,start-index<,index<,forceup>>>>);

rc=SETNITEMN(list-id,nval,name ,<occurrence
<,start-index<,index<,forceup>>>>);

rc=SETNITEMO(list-id,object-id,name, <occurrence
<,start-index<,index<,forceup>>>>);

rc

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

Type: Numeric

list-id

is the identifier of the list that contains the named item. An invalid list-id produces an error condition.

Type: Numeric or List

cval

is the character value for SETNITEMC to assign.

Type: Character

sublist-id

is the identifier of the sublist for SETNITEML to assign. An error condition results if sublist-id is not a valid identifier.

Type: Numeric

nval

is the numeric value for SETNITEMN to assign.

Type: Numeric

object-id

is the identifier of the object for SETNITEMO to assign. An error condition results if object-id is not a valid identifier.

Type: Numeric or Object

name

is the name of the item. If the named item is not found in the list, it is inserted into the list.

Type: Character

occurrence

specifies which occurrence of the named item to assign the specified value to, starting from the position specified in start-index. The default, 1, indicates the first occurrence of the item.

Type: Numeric

start-index

specifies where in the list to begin searching for the item. By default, start-index is 1 (the first item). If start-index is positive, then the search begins at position start-index items from the beginning of the list. If start-index is negative, then the search begins at the item specified by ABS(start-index) items from the end of the list. An error condition results if the absolute value of start-index is zero or if it is greater than the number of items in the list.

Type: Numeric

index

is a variable to contain the index of the modified or inserted item.

Note: This parameter is an update parameter. See Input, Output, and Update Parameters for more information. [cautionend]

Type: Numeric

forceup

specifies whether to conduct the name search in uppercase.

`'N'`	searches according to the list attributes HONORCASE and NOHONORCASE, which are specified with SETLATTR. (This is the default.)
`'Y'`	conducts the name search in uppercase regardless of the list attributes that are specified with SETLATTR. The HONORCASE and IGNORECASE attributes are ignored.

IGNORECASE is an alias for NOHONORCASE.

Type: Character

Details

SETNITEMC, SETNITEML, SETNITEMN, and SETNITEMO do not make a copy of the list before modifying or inserting an item. The list is modified in place. If the named item is not found in the list (and if the list does not have the FIXEDLENGTH attribute), the item is inserted into the list.

If you specify a variable name for index, then these functions return the index number in the list of the modified or inserted item. You can reference this index to access the same item with these functions and other SCL list functions, as long as the items do not change positions (for example, as a result of an insert or delete operation). If the position of items in a list is stable, then using the index argument and subsequent index-based functions such as SETITEMC rather than name-based functions improves performance, because the list does not have to be searched multiple times to find a name match.

If occurrence and start-index are both positive or both negative, then the search proceeds forward from the start-index item. For forward searches, the search continues only to the end of the list and does not wrap back to the front of the list. If the named item is not found, it is inserted at the end of the list. If occurrence or start-index is negative, the search proceeds backwards from the end to the beginning of the list. For backward searches, the search continues only to the beginning of the list and does not wrap back to the end of the list. If the named item is not found, it is inserted at the beginning of the list.

The result of using SETNITEMC, SETNITEML, SETNITEMN, and SETNITEMO is similar to combining NAMEDITEM and SETITEM, SETITEML, SETITEMN, and SETITEMO, respectively. For example, consider the following statement:

mylist=setnitemc(mylist,'Jones','NAMES',1,1,i);

This statement performs the same operations as the following statements:

i=nameditem(mylist,'NAMES');
   /* If NAMES isn't found, insert it */
   /* at the end of the list. */
if i=0
then mylist=insertc(mylist,'Jones',-1,'NAMES');
else mylist=setitemc(mylist,'Jones',i);

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 either the item or the list has the NOUPDATE attribute.
if either the item or the list has the FIXEDTYPE attribute and the new value is being assigned to an item that has a different type.
if the named item was not found and the list has the FIXEDLENGTH attribute.
with SETNITEMC and SETNITEML, if the list has the NUMONLY attribute.
with SETNITEMN and SETNITEML, if the list has the CHARONLY attribute.
with SETNITEML, if list-id identifies a global list and sublist-id identifies a local list. (Local lists cannot be placed into global lists.)

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

See Also

GETNITEMC, GETNITEML, GETNITEMN, and GETNITEMO

INSERTC, INSERTL, INSERTN, and INSERTO

NAMEDITEM

NAMEITEM

SETITEMC, SETITEML, SETITEMN, and SETITEMO

SETLATTR

Chapter Contents
Previous
Next
Top of Page