GETNITEMC, GETNITEML, GETNITEMN, and GETNITEMO

GETNITEMC, GETNITEML, GETNITEMN, and GETNITEMO

Return a value identified by its item name in an SCL list

Category: List

Syntax
Details
Examples
	Example 1: Using the GETNITEMC Function
	Example 2: Searching for an Item of Unknown Type
	Example 3: Using GETNITEML and Specifying a Default Value
	Example 4: Using GETNITEMC and Specifying a Default Value
See Also

Syntax

cval=GETNITEMC(list-id,name<,occurrence
<,start-index<,default<,force>>>>);

sublist-id=GETNITEML(list-id,name<,occurrence
<,start-index<,default<,force>>>>);

nval=GETNITEMN(list-id,name<,occurrence
<,start-index<,default<,force>>>>);

obj-val=GETNITEMO(list-id,name<,occurrence
<,start-index<,default<,force>>>>);

cval

contains the character value that is returned by GETNITEMC.

Type: Character

list-id

is the identifier of the list to search. An invalid list-id produces an error condition.

Type: List

name

is the name of the item to search in the list. Item names are converted to uppercase during the search if force is 'Y' or if the searched list has the attribute NOHONORCASE set. Trailing blanks are ignored when the list is searched for a matching name. Thus, the names 'abc' and 'Abc' are converted to 'ABC'.

IGNORECASE is the alias for NOHONORCASE and is the default for a list. But you can use the SETLATTR function to set a list's attribute to HONORCASE.

Type: Character

occurrence

is the number of the occurrence of the named item to be searched. The default, 1, indicates the first occurrence of the item.

Type: Numeric or List

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, the search begins at position start-index items from the beginning of the list. If start-index is negative, 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

default

is a default value to return if the named item is not found in the list. This value must have the appropriate data type for the function that is being used:

GETNITEMC: a character value
GETNITEML: a sublist identifier or a list value
GETNITEMN: a numeric value
GETNITEMO: an object identifier.

Type: Character, Numeric, List, or Object

sublist-id

is the identifier for the sublist that is returned by GETNITEML.

Type: List

nval

is the numeric value that is returned by GETNITEMN.

Type: Numeric

obj-val

is the object identifier that is returned by GETNITEMO.

Type: Object

force

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 list attributes specified with SETLATTR.

Type: Character

Details

By default, the search starts at the beginning of the list and returns the first item found that has the specified item name. However, you can start the search at a different place in the list by specifying a start-index other than 1. You can also specify a different occurrence of the item (for example, the second, tenth, or twentieth) by specifying an occurrence other than 1. If the item is not found and you have specified a value for default as the fifth parameter, then that value is returned instead of an error condition.

If occurrence and start-index are both positive or both negative, 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 occurrence or start-index is negative, then the search is backwards. For backward searches, the search continues only to the beginning of the list and does not wrap back to the end of the list.

GETNITEMC combines the actions of NAMEDITEM and GETITEMC. GETNITEML combines the actions of NAMEDITEM and GETITEML. GETNITEMN combines the actions of NAMEDITEM and GETITEMN. GETNITEMO combines the actions of NAMEDITEM and GETITEMO.

In situations where your application manipulates an SCL list and you cannot guarantee that the named item is character, you should not use GETNITEMC. Instead, when manipulating SCL lists which may contain other types, you should use NAMEDITEM with ITEMTYPE with GETITEMC, GETITEML, GETITEMN, or GETITEMO.

An error condition results if

the named item is not a character value and you are using GETNITEMC
the item is not a list identifier and you are using GETNITEML
the item is not a numeric value and you are using GETNITEMN
the item is not an object and you are using GETNITEMO.
the named item does not exist and default is not specified.

Examples

Example 1: Using the GETNITEMC Function

Halt the program if there are fewer than two items named 'Software Sales' in the list identified by DIRECTORY. Omitting the default value from GETNITEMC designates that the character item must exist in the list.

s=getnitemc(directory,'Software Sales',2,-1);

This statement is equivalent to the following statements:

ssi=nameditem(directory,'Software Sales',2,-1);
s=getitemc(directory,ssi);

Both of the preceding examples search for the second occurrence of 'Software Sales', starting from the end of the list.

Example 2: Searching for an Item of Unknown Type

This example shows how to search for a named item in an SCL list when you do not know the type of that item.

index = nameditem(listid, 'A', occurrence,
                               startIndex);
if index then
   select (itemtype(listid, index));
     when ('C') c = getitemc(listid, index);
     when ('L') l = getiteml(listid, index);
     when ('N') n = getitemn(listid, index);
     when ('O') o = getitemo(listid, index);
   end;

Example 3: Using GETNITEML and Specifying a Default Value

If the named item may not be in the list, supply a list identifier value for default for GETNITEML:

sslistid=getniteml
(emp_list,'Marketing',2,-10,-1);

The preceding program statement is equivalent to the following:

mpos=nameditem(emp_list,'Marketing',2,-10);
if mpos ne 0 then
   sslistid=getiteml(emp_list,mpos);
else
   sslistid=-1;

Example 4: Using GETNITEMC and Specifying a Default Value

This example shows GETNITEMC, using a default value that contains an error message.

defaultc='Value not found';
s=getnitemc
(directory,'Software Sales',2,-1,defaultc);

NAMEDITEM

NAMEITEM

SEARCHC, SEARCHL, SEARCHN, and SEARCHO

SETLATTR

SETNITEMC, SETNITEML, SETNITEMN, and SETNITEMO

Chapter Contents
Previous
Next
Top of Page