_CP_select

_CP_select is equivalent to the select expression1 to list BASIC statement.

Syntax

int _CP_select(int expression1, int* list, int expression2)

If expression2 is nonzero, then the secondary list is assumed. The default behavior of _CP_select is to create an internal select list which contains the item-IDs of the file pointed to by expression1. expression1 must have been previously created by a _CP_open call.

NOTE	In BASIC, if an external select list is present (that is, one created by a previous call to _CP_execute), the value of expression1 will be ignored. In this case, the user can pass -1 for expression1 if desired.

Description

This function returns -1 if an error occurs. The error code is contained in _CP_errno.

TIP	When possible, the user should use _CP_select on a file rather than a _CP_execute of a TCL select command as the _CP_select call is more efficient.

CAUTION

The user C program should always process all of the items in the list or call _CP_clearselect to dispose of the list prematurely. Failure to do this can cause excessive memory or overflow usage.

Example(s)

/* Prints the item names in "myfile". */

CPSTR * n = _CP_mkstr("myfile");

CPSTR * id = _CP_str_null;

int sl = -1;

int f = -1;

_CP_open(&f, _CP_str_null, n);

_CP_select(f, &sl, 0);

while (_CP_readnext(&id,&sl,(int*)0,0)>=0)

_CP_print(id);

The example below demonstrates how an external select list overrides the file variable passed as expression1. Here, "myfile" is passed to the select, but the readnext returns items from the master dictionary.