op_prg_odb_command_register()
Abstract
Allows the user to add custom commands to ODB that result in the invocation of custom callback functions.
Syntax
op_prg_odb_command_register (command_name, usage, category, short_desc, long_desc, callback, state_ptr, destroy_callback)
| Argument | Type | Description |
|---|---|---|
command_name |
const char* |
name of the command to be added to ODB. The command name specified here can be typed at the ODB prompt to activate a user-specified callback function. |
usage |
const char* |
string describing the command’s usage. [This string appears if the user requests help for the registered command in ODB. |
category |
const char* |
category to which the command belongs |
short_desc |
cconst har* |
short description of the command |
long_desc |
const char* |
long description of the command |
callback |
Procedure |
function to be called by the new ODB command. The typedef used for this procedure is Prg_Odb_Command_Callback. |
state_ptr |
state_ptr |
pointer that is passed to the callback function. This pointer is passed to the callback and destroy callback functions when the user invokes the registered command. |
destroy_callback |
Procedure |
function called when the command is removed from ODB. The typedef used for this procedure is Prg_Odb_State_Destroy. |
Return Type
Compcode
Completion code indicating whether the function was successfully registered. This return code can be compared to the constants OPC_COMPCODE_SUCCESS and OPC_COMPCODE_FAILURE to determine if the command was successfully registered.
Example
/* Register a command with ODB that will invoke the function */
/* tcp_connection_info_display(). Call the odb command "tcp_info" */
op_prg_odb_command_register ("tcp_info", "tcp_info [ip-address]",
"TCP Commands" /*category of commands */,
"This command will print out information on open TCP connections."
/*short description */,
"This command will print out information on open TCP connections\n"
"given an optional ip-address. Information includes source and\n"
"destination ip addresses, as well as statistics regarding the\n"
"currently open connection." /* long description */,
tcp_connection_info_display /* callback function */,
TcpI_Conn_Info_Ptr /* a pointer within this process model containing */
/* all necessary information needed for printing out connection information.*/,
tcp_connection_info_destroy /* destroy callback */ );
Details
This KP allows processes to install their own commands to be used at the ODB prompt during simulation debugging. When invoked by the user, the command activates a model developer-specified callback function. The callback function is prototyped to be of the following form:
int
callback_function (const char *arguments, void *state_ptr)
The arguments passed are taken from the ODB command line and consist of any character string typed after the command. The callback function is expected to return an integer. If the integer returned is 0, the user is prompted for another command at the ODB prompt. If the integer is not 0, the simulation continues execution.
The destroy callback function is defined as follows:
void
destroy_callback (void *state_ptr)
The destroy callback function is passed the same state pointer that was used in the callback function. This function deallocates any command-specific state to free up resources specific to the installed command. If a dynamic process installs a command using this KP and that process is later destroyed, this function is called to free up the state and remove the command from ODB.
The usage, long_desc, and short_desc arguments all present information through ODB’s various help functions.
This KP returns OPC_COMPCODE_FAILURE when used with an optimized simulation kernel.
Purpose
Provides a mechanism to allow states to define their own specified ODB commands. When entered at the ODB prompt, the command calls a function created by the user.
Errors
- Program Abort: KP requires process context.
Reference
- Use the KP op_prg_odb_bkpt() to define when a breakpoint should occur