CA_Execute_State

Purpose

Requests a channel process to execute a state table.

Libraries

Blueworx Voice Response library (libvae.a)

Custom Server library (libca.a)

Syntax

#include "CA_header.h"
int CA_Execute_State_Table (
 short                          link_id,
 int                            wait_flag,
 char                           *state_table_name,
 char                           *entry_label,
 int                            num_args,
 char                           *arg_array[],
 EXECUTE_STATE_TABLE_RETURN_ST  *execute_state_table_return_sp
);

Description

This subroutine requests a linked channel process to execute a specified state table, starting at the entry point specified and using the parameters specified. The wait_flag allows the custom server to either wait for the completion of the state table or run asynchronously.

The EXECUTE_STATE_TABLE_RETURN_ST output structure returns information about how the state table completed. If you do not want this data returned (or if the wait_flag is set to CA_NOWAIT), set the execute_state_table_return_sp pointer to NULL.

When you call state tables from a custom server using CA_Execute_State_Table(), ExitStateTable should be used to return control to the calling custom server. CloseEverything should only be used to end state tables that are directly handling telephone calls.

Parameters

link_id: The ID of the channel process.
wait_flag: A flag that indicates whether or not to wait for a response from the corresponding channel process. Valid values for this parameter are CA_WAIT and CA_NOWAIT. Using the CA_WAIT flag will cause the subroutine to wait up to a maximum of 2 hours.
state_table_name: The name of the state table. The maximum number of characters allowed in this string is MAX_STATE_TABLE_LENGTH. This string must be terminated with a zero.
entry_label: State table entry point label. The maximum length of this string, which must be terminated with a zero, is MAX_ENTRY_LABEL_LENGTH.
num_args: The number of arguments being passed in the arg_array to the state table.
arg_array: An array of pointers to character strings, each string being an argument to be passed to the state table script. If there are no arguments, set this parameter to NULL.
There is a limit to the maximum combined length of all parameters passed to the arg_array, see CA_PARMS_TOO_LARGE.
execute_state_table_return_sp: A pointer to an EXECUTE_STATE_TABLE_RETURN_ST output structure that will be filled in as described in EXECUTE_STATE_TABLE_RETURN_ST.

Return codes

0: The result of the last action that was executed in the state table. See the actionedges.h header file for the #define that corresponds to the returning result value. More information is returned in execute_state_stable_return_sp.
-1: Unsuccessful (global error number CA_errno is set to indicate the error)

Error names

CA_ACCESS_NOBUFS
CA_INV_ADDR
CA_INV_ENTRY_LABEL
CA_INV_LINK_ID
CA_INV_PARM_COUNT
CA_INV_STATE_TABLE_NAME
CA_LINK_NOT_OPEN
CA_NO_MSG_RECV
CA_NOT_INIT
CA_PARMS_TOO_LARGE
CA_REQ_FAILED
CA_STATE_TABLE_NOT_VALID
CA_TERMINATING
CA_UNABLE_TO_EXEC_STATE_TABLE

Related information

CA_Open_CHP_Link(), CA_Ping_CHP_Link(), CA_Close_CHP_Link().