# _CP_call

_CP_call is equivalent to the `call *name*( {*string1* {, *string2* {, ...}}})` BASIC statement.

## Syntax

```
int _CP_call(int* number, CPSTR* name, int expression,
{ CPSTR** string1{,CPSTR** string2{,... }}})
```
The *number* parameter *must* be
a pointer to an integer. On the first call to a particular subroutine,
this integer *must* contain -1. Upon successful return, this
location will contain an index number that should be passed down to
all succeeding _CP_calls to the same subroutine.
This index allows the system to jump directly into the subroutine
code without having to look up the name in the master dictionary.

The *name* parameter should be a CPSTR* pointing
to the subroutine name. The subroutine to be called *must* be
previously compiled with FlashBASIC and be cataloged in the current
master dictionary. The *expression* must be the number
of parameters to pass.

Note: All subroutines called must have
been previously compiled with the current version of FlashBASIC.

## Description

Each parameter passed to FlashBASIC
must be a CPSTR**. Upon return from the subroutine, FlashBASIC will
reconvert its variables back to strings, if necessary, and stuff the
results back into the passed CPSTR**s.

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

| PE_BAD_PARAMS | Indicates that too many parameters were passed as expression. The user can only pass _CP_MAX_PARAM parameters. |
| --- | --- |
| PE_LOAD_ERR | Indicates that the system could not load the subroutine. The subroutine must be cataloged, and must be compiled with the current version of FlashBASIC. |

## Example(s)

```
/* call a user-written routine */
CPSTR * s = _CP_mkstr("hi");
int i = -1;
r = _CP_call(&i,s,0);
if (r < 0)
{
_CP_logoff();
exit(-1);
}
/* Now that the subroutine is loaded, it can be called */
/* very efficiently */
for (j=1; j < 100; j++) _CP_call(&i,s,0);
```

## See also

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

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