# _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.

```
CPSTR * n = _CP_mkstr("myfile");
CPSTR * s = _CP_mkstr("select md sampling 3");
CPSTR * id = _CP_str_null;
int sl = -1;

int f = -1;
_CP_execute(_CP_EXECUTE, s, (CPSTR**) 0, (CPSTR**) 0);
_CP_open(&f, _CP_str_null, n);
_CP_select(f, &sl, 0);
while (_CP_readnext(&id, &sl, (int*) 0, 0) >= 0)
_CP_print(id);
```

## See also

- [C functions overview](https://d3codex.com/cfunctions/c-functions-overview/)
- [_CP_clearselect](https://d3codex.com/cfunctions/cp-clearselect/)

---
Source: https://d3codex.com/cfunctions/cp-select/ - part of the D3Codex reference.