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

本站文档由 北京智网畅联科技有限公司 整理、翻译并提供 · Documentation compiled and provided by Beijing ZNetLink Technology Co., Ltd.

交流群 · QQ Group:OPNET/智网妙算网络仿真交流群(群号 486383494)

原文档 © 2017 Riverbed Technology · 本站为公益翻译,由 AI 辅助完成,请仔细甄别

Original documentation © 2017 Riverbed Technology. Community translation, AI-assisted. Contact: jiazequn@znetlink.com