2    Using the Callable Interface

The FUSE EnCASE callable interface allows you to send and receive messages that the FUSE message server processes. Section 2.1 describes how to use the callable interface. Section 2.2 provides reference information for each C function and script command in the callable interface.

2.1    Overview of FUSE Messages

Your tool can use the FUSE message server to send and receive its own messages as well as any of the FUSE messages listed in Chapter 5. Use the FUSE tool messages to:

• Be aware of a FUSE tool activity.

• Inform a FUSE tool of your tool activity.

• Direct a FUSE tool to perform a task based on a message sent by your tool.

• Perform a task based on a message sent by a FUSE tool.

Table 2-1 summarizes messages about FUSE tool activities that your tool can use.

Table 2-1:  Summary of FUSE Tool Messaging Activities

Tool	Messaging Activities
Builder	Start a build, identify the current build target, update the makefile graph, set the current build target, and receive notification of completed build process.
Call Graph	Select a node on the call graph, manage the call graph, and receive notification and information about highlighted and selected nodes.
C++ Class Browser	Select an item on the class graph, manage the class graph, and receive notification and information about an item on the class graph.
Code Manager	Insert files into a library, check files in, check files out, cancel locks, and send notification about file insertion, check in, check out, and canceled locks.
Compare	Load a file into a difference window and start a compare operation.
Control Panel	Receive information about the FUSE session, tool groups, tool status and working data, and save and restore configuration files.
Program Visualizer	Send the name of a DataSet file to the Program Visualizer.
Database Server	Issue a database query and manage the static analysis database.
Debugger	Request that the debugger set or delete a breakpoint. Notify tools about breakpoints.
FUSE Editor	Open or insert files, set or clear annotations, navigate within and among buffers, search and replace text, add and remove lines, and highlight and remove highlighting from text.
Heap Analyzer	Generate and display memory analysis data.
Helper	Request online help information.
Man Tool	Display a reference (man) page in a window.
Porting Assistant	Request to get information about a Assistant function that is not available on Digital UNIX.
Profiler	Generate and display performance data.
Search	Search files for expressions or strings.
Version Controller	Insert files into a library, check files in, check files out, cancel locks, and send notification about file insertion, check in, check out, and canceled locks.
Version stamp facility	Retrieve the current FUSE version stamp.

The FUSE EnCASE callable interface provides a set of C functions and a script command that allow your tool to communicate with the message server. The C functions provide more flexibility in sending and receiving messages than the script command. Refer to Section 2.2.1 for a description of each function in the C callable interface and Section 2.1.2 for a description of each command option in the script callable interface.

Each function or command, when called by your tool, automatically expands to define additional statements or commands for communicating with the message server. This minimizes the amount and complexity of FUSE-specific code required in your tool.

Each message that your tool processes through the FUSE message server must be listed in the Tool Integration Language (TIL) file. Otherwise, the functions or commands that your tool calls for sending or receiving the message result in errors.

For examples of using the callable interface, refer to Section 4.1.1.

2.1.1    Initializing a Tool

If you are using the C interface, your tool must call the following function to be initialized before it can use the FUSE message server:

int FUSE_init(void(*register_fct()))

This function connects your tool to the message server and informs the Control Panel of the connection.

The FUSE_init call specifies another function, *register_fct(), which informs the tool of the socket on which FUSE messages are received and declares a pointer to the function that processes the messages that appear on the socket. The function is:

void register_fct(int socket_id, void (*msg_handler)())

For tools using Motif or the X Toolkit, make sure that the tool uses the XtMainLoop or XtAppMainLoop to listen to FUSE messages as well as X messages. The register function (register_fct) must specify that XtAddInput() or XtAppAddInput() is called to process FUSE messages. The following example shows how the FUSE_init function is used in a tool using Motif or the X Toolkit:

FUSE_init(register_socket);
/* This is how register_socket is defined.
/*
static void register_socket(int socket_id, void (*msg_handler)())
{
 XtAppAddInput(AppCont, socket_id, XtInputReadMask, msg_handler, NULL);
};

Tools that do not use Motif or the X Toolkit must manually monitor socket_id for incoming data. When there is incoming data, the tool calls msg_handler to process the message.

The message server assumes that your tool is in the start state when first connected, unless otherwise informed. If different states are not important for your tool's operation, being in a continual start state is sufficient. However, if you use state information to limit tool activity or if your tool receives trigger messages, your tool must inform the message server of a state change.

For a tool to receive trigger messages, it must have a running state and it must change to the running state. The change to a running state informs the message server that the tool is ready to receive trigger messages.

Use the following C function to inform the message server of a tool state change:

int FUSE_state_change(char *state)

If you are using script commands, use the following command:

fusescript -state state_name

The state you specify must match a state declared in the TIL file.

2.1.2    Sending a Message

For sending messages, use the following C function:

FUSE_SEND_message-name(void(*callback)(),void*user_data,[param ...])

You can also use the following script command:

fusescript -send message-name [param ...]

Use the void(*callback)(),void*user_data portion only when the message you are sending has a return value.

A tool can send up to 32 messages at a time. If a tool needs to send more, the messages can be sent in smaller amounts at a time, or the next message will have to wait until a reply for the previous message is received.

When using the C interface, you can specify a callback function that is called on receipt of the return value. The return value can be used to synchronize the message with its receipt and to inform your tool of a reply from the message recipient.

To ensure that replies to messages are accurate, use user_data to provide identifying information about the reply. For example, your tool sends the EditorOpenFile(char *filename) message twice to open two different files (file1 and file2) and it is important for your tool to know the success or failure of each request. In the first EditorOpenFile message, specify that user_data is equal to file1 . In the second EditorOpenFile message, specify and that user_data is equal to file2. Your tool can then use the callback function to accurately determine the success or failure of opening each file by using the value in user_data.

For example, the following code fragment shows how to use user_data to differentiate replies between two EditorOpenFile messages:

char *file1 = "saying.c",
     *file2 = "getsaying.c",
     *reply_cb_data1,
     *reply_cb_data2;

reply_cb_data1 = malloc(strlen(file1)+1);
strcpy(reply_cb_data1,file1);
reply_cb_data2 = malloc(strlen(file2)+1);
strcpy(reply_cb_data2,file2);

FUSE_SEND_EditorOpenFile(reply_cb,reply_cb_data1,file1);
FUSE_SEND_EditorOpenFile(reply_cb,reply_cb_data2,file2);

void reply_cb(void *user_data, char *reply)
{
printf("reply for %s = %s\n",(char *)user_data,reply);
free(user_data);
if (reply != NULL)
   free(reply);
}

The reply information returned for each EditorOpenFile message is specific to each message:

reply for saying.c = SUCCESS
reply for getsaying.c = FAILURE

For information about memory management when sending or receiving messages, see Section 2.1.6.

When you send a message with a parameter specified as NULL, the message server always converts NULL into a zero-length string ("").

If your tool is working with multiple instances of another tool and you need to direct a message to a specific instance of a tool, use the following C function:

int FUSE_set_dest(int instance_id)

You can also use the following script command:

fusescript -set_dest instance_id

This function (or command) sends all subsequent messages to a specific tool instance, identified by instance_id. Obtain the instance_id using the following C function:

int FUSE_req_sender()

You can also use the following script command:

int FUSE_req_sender()

Use another FUSE_set_dest or fusescript -set_dest call to change the message destination. To clear the message destination without redirecting to another tool instance, use the following C function:

int FUSE_clear_dest()

You can also use the following script command:

fusescript -clear_dest

2.1.3    Receiving a Message

For receiving messages, use the following C function:

FUSE_RECV_<message-name>([param1, ...][,int call_id])

You can also use the following script command:

fusescript -recv [timeout]

The call_id argument is the identifier of the message instance. It is returned if you have declared a return value for the message in the TIL file. Use call_id to reply to a message, based on the type of message (as declared in the TIL file):

• If the message is a synchronized message, pass the call_id to FUSE_message_finish or fusescript -message_finish. This function (or command) informs the message server that your tool has received the message.

  Refer to Section 3.1.3 for a description of synchronized messages.

• If the message has a char* return value and you want to send information back in your reply, pass the call_id to FUSE_reply or fusescript -reply. Use the reply argument to send back your tool's information, along with the call_id.

• If the message is an eavesdrop message, you can pass call_id to FUSE_reply or FUSE_message_finish (or fusescript -reply or fusescript -message_finish), but it is ignored.

  Refer to Messages Clause in Section 3.1 for a description of eavesdrop messages.

If you include libraries that receive the same messages as another part of your program, you can only use FUSE_RECV for the same message once. Then, direct FUSE_RECV to send the message information to the appropriate component.

For information about memory management when sending or receiving messages, see Section 2.1.6.

2.1.4    Obtaining Messaging Information

To obtain other information about messaging activities, use these functions:

• To obtain the identifier of your tool, use the following C function:

  int FUSE_req_id()
  

  You can also use the following script command:

  fusescript -req_id
  

  The message server uses the identifier to identify your tool during the current session.

• To obtain the identifier of the tool sending or replying to the current message that is being processed, use the following C function:

  int FUSE_req_sender()
  

  You can also use the following script command:

  fusescript -req_sender
  

  Use the value returned by this function for the instance_id in FUSE_set_dest.

2.1.5    Responding to Failed Messaging

Messaging is no longer possible if one of the functions in the C interface returns a negative value, or one of the commands in the script interface returns an exit code of 1 to indicate failure. It is likely that the message server can no longer operate and your tool should exit. In most cases, the entire FUSE session has to be restarted.

2.1.6    Managing Memory When Sending and Receiving Messages

Use the following rules regarding memory allocation when sending and receiving messages.

FUSE_SEND_<message_name>

The FUSE_SEND_<message_name> functions make copies of all string parameters. Therefore, if the caller allocates memory for a parameter to these functions, the caller is responsible for freeing that memory.

There is one exception to this rule. The caller can allocate a structure that it passes as userdata and that will be returned to the callback function. In this case, the callback function should free this memory.

Callbacks from FUSE_SEND_<message_name>

The callback function is responsible for freeing memory for the reply parameter. In addition, if the message sender allocated memory for the userdata parameter, the callback function should free this memory.

FUSE_reply

The FUSE_reply function makes a copy of the reply string parameter. Therefore, if the caller allocates memory for the reply string, the caller is responsible for freeing that memory.

FUSE_RECV_<message_name>

The FUSE_RECV_<message_name> functions should never free memory for the parameters passed to them. The message client code is responsible for freeing memory for these parameters.

2.2    Callable Interface Reference Section

This section provides the reference information for each C function and script command option for the callable interface. Both interfaces support the same messaging functions:

• Sending

• Receiving

• Replying

• Notification of state change

Where possible, use the C interface because it is more flexible in sending, receiving, and replying to messages.

2.2.1    C Functions

This section describes the C functions. The functions are listed in alphabetical order.

FUSE_clear_dest

Clears a FUSE message destination request.

int FUSE_clear_dest()

The FUSE_clear_dest function clears a request to send messages to a specific tool issued by the FUSE_set_dest function.

On successful completion, a value of 0 is returned. On failure, a negative value is returned and further messaging is not possible.

FUSE_init

Initializes the tool in FUSE.

int FUSE_init(void( *register_fct()))

The FUSE_init function initializes a tool in FUSE completing the following actions:

• Initializes the FUSE interface layer

• Registers the tool's message handlers

• Connects to the message server

• Announces the tool's connection to the Control Panel, after which the Control Panel displays information in its display area

Call this function before you start any other messaging for your tool.

The function enables the receipt of messages from the message server. It associates the message server socket with the tool's message handling routine. The tool should have a definition of the register_fct function as follows:

void register_fct(int socket_id, void (*msg_handler)())

If the tool uses Motif or the X Toolkit, this function can call XtAddInput() or XtAppAddInput() for monitoring receipt of messages. If the tool does not use Motif or the X Toolkit, the tool must monitor the socket_id for incoming data and call the msg_handler when data is received.

On successful completion, a value of 0 is returned. On failure, a negative value is returned and further messaging is not possible.

FUSE_message_finish

Notifies the message server that processing of a FUSE message is complete.

int FUSE_message_finish(int call_id)

The FUSE_message_finish function notifies the message server that the tool has finished processing the message specified by call_id. When all message recipients have issued this call, the message server notifies the message sender that the message has been received and processed.

This routine should be called when an application has finished processing a synchronized message. (See Section 3.1.3 for more information.)

This function must be called by each tool for any message that has been declared a synchronized message in the TIL file. The call_id for the message is returned in the FUSE_RECV_message-name function.

On successful completion, a value of 0 is returned. On failure, a negative value is returned and further messaging is not possible.

FUSE_RECV_<message_name>

Receives a FUSE message.

void FUSE_RECV_message-name([param,...] [,int
call_id])

The FUSE_RECV_message_name function receives the message specified by message-name. You must have declared in the TIL file the message referenced by message-name and any parameters. The parameters listed in the function must match the parameters and the type listed for the message in the TIL file.

If the message is declared in the TIL file to have a return value, then call_id is passed, which is the identifier of the message instance to be passed to FUSE_message_finish or FUSE_reply. If the return value is synchronized (that is, it is declared in the TIL file as sync, then call_id must be passed to FUSE_message_finish to inform the message server that the message has been received. If the message is declared in the TIL file as an eavesdropped message, call_id can be passed to FUSE_message_finish or to FUSE_reply, but it will be ignored.

If one of the message parameters is of type char* and you want to save it, you must allocate a buffer and copy the information to the buffer. Otherwise, the information is freed upon return from the routine. For information about memory management when sending or receiving messages, see Section 2.1.6.

FUSE_reply

Sends a reply to a FUSE message.

int FUSE_reply(int call_id, char *reply)

The FUSE_reply function sends a reply to the message specified by call_id, which is the identifier of the message instance sending the message. The message server uses this call to verify that all message recipients have received the message. The reply is specified in reply.

The call_id is specified in the FUSE_RECV_message-name function.

On successful completion, a value of 0 is returned. On failure, a negative value is returned and further messaging is not possible.

For information about memory management when sending or receiving messages, see Section 2.1.6.

FUSE_req_id

Provides the tool's identifier.

int FUSE_req_id()

The FUSE_req_id function returns the instance identifier of the tool calling this function. The instance identifier is used by the message server to identify the tool for the current FUSE session.

FUSE_req_sender

Provides the identifier of a FUSE message sender.

int FUSE_req_sender()

The FUSE_req_sender function returns the instance identifier of the tool that is sending the current message or message reply that is being processed. If there is no current message or message reply, -1 is returned.

This function is used to obtain the instance_id for use in the FUSE_set_dest function.

FUSE_SEND_<message_name>

Sends a FUSE message.

int FUSE_SEND_message-name(void(*callback)(),void
*user_data, [param,...])

or

int FUSE_SEND_message-name([param,...]

The FUSE_SEND_message_name function sends the message specified by message-name. The message referenced by message-name and all parameters must be declared in the TIL file before the message can be sent.

If the message has a return value, you must specify either a callback function, callback(), to accept the return value or a value of NULL for callback(). If the message server cannot deliver a message, a value of NULL is returned as the reply to the callback routine.

You can also specify a pointer to a different data area, in user_data, for each message sent so that the tool can differentiate among replies. If you do not use user_data, you must specify a value of NULL.

On successful completion, a value of 0 or higher is returned. On failure, a negative value is returned and further messaging is not possible.

The format of the callback function is:

void callback(void *user_data, char *reply)

The user_data argument is a pointer specified when the FUSE_SEND function is called and reply is the return value of the message. After reading reply, you must free it (using free(), because it is not automatically freed). For information about memory management when sending or receiving messages, see Section 2.1.6.

If you have declared the message in the TIL file as a synchronized message, you must specify a callback function. The format of the callback function for a synchronized message is:

void callback(void *user_data)

The message sent must be processed by the receivers; no other information is required.

FUSE_set_dest

Directs FUSE messages to a specified tool.

int FUSE_set_dest(int instance_id)

The FUSE_set_dest function directs all messages following this call to be sent to the tool specified by instance_id. Use this function to guarantee that your tool's messages are sent to the correct tool. For example, if there are three instances of one tool running in a FUSE session and you want to send messages to only one of those tool instances, use this function to specify the correct tool instance.

Use FUSE_set_dest to redirect the messages or FUSE_clear_dest function to clear the destination of messages to a tool instance.

You can obtain the instance_id from the FUSE_req_sender function or by using the ControlPanelQuery message.

On successful completion, a value of 0 is returned. On failure, a negative value is returned and further messaging is not possible.

FUSE_state_change

Announces a FUSE tool state change.

int FUSE_state_change(char *state)

The FUSE_state_change function announces to the message server that there is a change in the state of the tool. After successful completion of this call, messages to be sent or received by the tool are limited to messages allowed in the new state, as specified in the TIL file.

You must use this function to inform the server of a state change. Otherwise, the message server assumes that your tool is in the start state.

On successful completion, a value of 0 is returned. On failure, a negative value is returned and further messaging is not possible.

2.2.2    Script Command Options

This section describes the fusescript command and its options. The options are listed in alphabetical order.

While using this command, you may receive on stderr one of the following error messages:

• No input option - An option to the fusescript command was not specified.

• Unmatched arguments - The arguments specified in the message do not match those defined in the TIL file.

• Cannot connect to Fuse script server - The script interface cannot communicate with the FUSE message server. Exit from the window running the script and start a new session.

• Cannot register message socket - The script cannot be run because there is a problem between the script and message server.

• Cannot open socket # - The network is not running properly.

• Cannot create and connect to the script server - There is a problem with process creation.

• Unknown host name - The workstation setup is incorrect and the workstation cannot be accessed. An incorrect workstation setup can be due to security or network problems.

fusescript -clear_dest

Clears the FUSE message destination.

fusescript -clear_dest

The -clear_dest option clears a request to send messages to a specific tool instance issued by the fusescript -set_dest command.

On successful completion, an exit code of 0 is returned. On failure, an exit code of 1 is returned and further messaging is not possible.

fusescript -help

Provides help information.

fusescript -help

The -help option displays help information about each fusescript command option.

On successful completion, an exit code of 0 is returned. On failure, an exit code of 1 is returned and further messaging is not possible.

fusescript -info

Specifies whether informational messages are displayed.

fusescript -info option

The -info option specifies whether informational messages are displayed, where option is either on to display the messages, or off to not display the messages. The default is off.

On successful completion, an exit code of 0 is returned. On failure, an exit code of 1 is returned and further messaging is not possible.

fusescript -message_finish

Notifies the message server that processing of a FUSE message is complete.

fusescript -message_finish call_id

The -message_finish option notifies the message server that the tool has finished processing the message specified by call_id. The value for call_id is the identifier (a unique positive integer) returned by the fusescript -recv command.

On successful completion, an exit code of 0 is returned. On failure, an exit code of 1 is returned and further messaging is not possible.

fusescript -recv

Receives a FUSE message.

fusescript -recv [timeout]

The -recv option receives a message sent by other FUSE tools. The message must be declared in the TIL file. Once a message is received, the command echoes the result, including parameters and the identifier of the message sender, to standard output. The format of the return status is the following:

id message-name param ...

If the message expects a response from the fusescript -reply or fusescript -message_finish commands, the id is a unique positive integer used as the call-id in those commands. If the message does not expect a response, the id is -1.

message-name and param are the message name and the values of the parameters.

If you specify a value in seconds for timeout, a message must be received within the specified time. Otherwise, an error (return exit code of 2) is returned.

On successful completion, an exit code of 0 is returned. On failure, an exit code of 1 is returned and further messaging is not possible. If you have specified a timeout value and a message has not been received during that period, an exit code of 2 is returned.

fusescript -recvall

Obtains status on the message currently received.

fusescript -recvall

The -recvall option queries from the message server the status of messages currently being processed.

On successful completion, an exit code of 0 is returned. On failure, an exit code of 1 is returned and further messaging is not possible.

fusescript -reply

Sends a reply to a FUSE message.

fusescript -reply call_id reply_text

The -reply option sends a reply to a message that has a return value. This command must specify the message identifier for call_id, returned as a unique positive integer by the fusescript -recv command, and include the reply text.

On successful completion, an exit code of 0 is returned. On failure, an exit code of 1 is returned and further messaging is not possible.

fusescript -req_id

Provides the tool's identifier.

fusescript -req_id

The -req_id option echoes to standard output the instance identifier of the tool issuing this command. The instance identifier is used by the message server to identify the tool for the current FUSE session.

On successful completion, an exit code of 0 is returned. On failure, an exit code of 1 is returned and further messaging is not possible.

fusescript -req_sender

Provides the identifier of a FUSE message sender.

fusescript -req_sender

The -req_sender option echoes to standard output the instance identifier of the tool that is sending the current message or message reply. An exit code of 2 is returned if there is no current message or message reply.

Use this command to obtain the instance_id for use in the fusescript -set_dest command.

On successful completion, an exit code of 0 is returned. On failure, an exit code of 1 is returned and further messaging is not possible. An exit code of 2 is returned if there is no current message or message reply.

fusescript -send

Sends a FUSE message.

fusescript -send message-name [param...]

The -send option sends a message, specified by message-name, using the specified parameters. If this message has a return value, the command will not complete until the reply is received. The reply is echoed to standard output upon receipt.

If this message is declared in the TIL file as a synchronized message, the command does not complete until the fusescript -message_finish command confirms that the message has been received and processed by all receivers. Confirmation and completion of a synchronized message send are not echoed to standard output.

The message referenced by message-name and any parameters must be declared in the TIL file.

On successful completion, an exit code of 0 is returned. On failure, an exit code of 1 is returned and further messaging is not possible.

fusescript -service

Shows available messages.

fusescript -service

The -service option displays messages that are available for sending and receiving.

On successful completion, an exit code of 0 is returned. On failure, an exit code of 1 is returned and further messaging is not possible.

fusescript -set_dest

Directs FUSE messages to a specific tool.

fusescript -set_dest instance_id

The -set_dest option directs all messages that follow this command to be sent to the tool instance specified by instance_id. Use this command to guarantee that your tool's messages are being sent to the correct tool. For example, if there are three instances of one tool running in a FUSE session and you want to send messages to only one of those tool instances, use this function to specify the correct tool instance.

The fusescript -clear_dest command clears the destination of messages to a tool instance.

The instance_id is obtained from the fusescript -req_sender command.

On successful completion, an exit code of 0 is returned. On failure, an exit code of 1 is returned and further messaging is not possible.

fusescript -state

Announces a FUSE tool state change.

fusescript -state state_name

The -state option announces to the message server that there is a change in the state of the tool. After successful completion of this call, messages to be sent or received by the tool are limited to messages allowed in the new state, as specified in the TIL file.

You must use this command to inform the server of a state change. Otherwise, the message server assumes that your tool is in the start state.

On successful completion, an exit code of 0 is returned. On failure, an exit code of 1 is returned and further messaging is not possible.