ToolTalk User's Guide

14 Handling Errors

Contents of Chapter:
14.1 Retrieving ToolTalk Error Status
14.2 Checking ToolTalk Error Status
14.3 Returned Value Status
14.4 Returned Pointer Status
14.5 Returned Integer Status
14.6 Broken Connections
14.7 Error Propagation
The ToolTalk service returns error status in the function's return value rather than in a global variable. ToolTalk functions return one of these error values:

Each return type is handled differently to determine if an error occurred. For example, the return value for tt_default_session_set is a Tt_status code. If the ToolTalk service sets the default session to the specified sessid:

14.1 Retrieving ToolTalk Error Status

You can use the ToolTalk error handling functions shown in Table 14-1 to retrieve error values.

Table 14-1 Retrieving ToolTalk Error Status

14.2 Checking ToolTalk Error Status

You can use the ToolTalk error macro shown in Table 14-2 to check error values.

Table 14-2 ToolTalk Error Macros

14.3 Returned Value Status

Functions with Natural Return Values

If a ToolTalk function has a natural return value such as a pointer or an integer, a special error value is returned instead of the real value.

Functions with No Natural Return Values

If a ToolTalk function does not have a natural return value, the return value is an element of Tt_status enum.

To see if there is an error, use the ToolTalk macro tt_is_err, which returns an integer.

If there is an error, you can use the tt_status_message function to obtain the character string that explains the Tt_status code, as shown in Figure 14-1.

Figure 14-1 Obtaining an Error Explanation

char *spec_id, my_application_name;
Tt_status tterr;

tterr = tt_spec_write(spec_id);
if (tt_is_err(tterr)) {
     fprintf(stderr, "%s: %s\n", my_application_name,
         tt_status_message(tterr));
}

14.4 Returned Pointer Status

If an error occurs during a ToolTalk function that returns a pointer, the ToolTalk service provides an address within the ToolTalk API library that indicates the appropriate Tt_status code. To check whether the pointer is valid, you can use the ToolTalk macro tt_ptr_error. If the pointer is an error value, you can use tt_status_message to get the Tt_status character string.

Figure 14-2 checks the pointer and retrieves and prints the Tt_status character string if an error value is found.

Figure 14-2 Retrieving a Returned Pointer Status

char *old_spec_id, new_file, new_spec_id, my_application_name;
Tt_status tterr;

new_spec_id = tt_spec_move(old_spec_id, new_file);
tterr = tt_ptr_error(new_spec_id);
switch (tterr) {
    case TT_OK:
      /*
       * Replace old_spec_id with new_spec_id in my internal
       * data structures.
       */
      update_my_spec_ids(old_spec_id, new_spec_id);
      break;
    case TT_WRN_SAME_OBJID:
      /*
       * The spec must have stayed in the same filesystem,
       * since ToolTalk is reusing the spec id. Do nothing.
       */
      break;
    case TT_ERR_FILE:
    case TT_ERR_ACCESS:
    default:
      fprintf(stderr, "%s: %s\n", my_application_name,
          tt_status_message(tterr));
      break;
}

14.5 Returned Integer Status

If an error occurs during a ToolTalk function that returns an integer, the return value is out-of-bounds. The tt_int_error function returns a status of TT_OK if the value is not out-of-bounds.

To check if a value is out-of-bounds, you can use the tt_is_err macro to determine if an error or a warning occurred.

To retrieve the character string for a Tt_status code, you can use tt_status_message.

Figure 14-3 checks a returned integer.

Figure 14-3 Checking a Returned Integer

Tt_message msg;
int num_args;
Tt_status tterr;
char *my_application_name;

num_args = tt_message_args_count(msg);
tterr = tt_int_error(num_args);
if (tt_is_err(tterr)) {
     fprintf(stderr, "%s: %s\n", my_application_name,
         tt_status_message(tterr));
}

14.6 Broken Connections

The ToolTalk service provides a function to notify processes if your tool exits unexpectedly. When you include the tt_message_send_on_exit call, the ToolTalk service queues the message internally until one of two events happen:

  1. Your process calls tt_close.

    In this case, the ToolTalk service deletes the message from its queue.

  2. The connection between the ttsession server and your process is broken; for example, the application crashed.

    In this case, the ToolTalk service matches the queued message to a pattern and delivers it in the same manner as if your had sent the message normally before exiting.

Your process can also send a normal message on a normal termination by calling tt_message_send before it calls tt_close. In this case, if your process sends its normal termination message but crashes before it calls tt_close, the ToolTalk service will deliver both the normal termination message and the tt_message_send_on_exit message to interested processes.

14.7 Error Propagation

ToolTalk functions that accept pointers always check the pointer passed in and return TT_ERR_POINTER if the pointer is an error value. This check allows you to combine calls in reasonable ways without checking the value of the pointer for every single call.

In the following code sample, a message is created, filled in, and sent. If tt_message_create fails, an error object is assigned to m, and all the tt_message_xxx_set and tt_message_send calls fail. To detect the error without checking between each call, you only need to check the return code from tt_message_send.

Tt_message m;

m=tt_message_create();
tt_message_op_set(m,"OP");
tt_message_address_set(m,TT_PROCEDURE);
tt_message_scope_set(m,TT_SESSION);
tt_message_class_set(m,TT_NOTICE);
tt_rc=tt_message_send(m);
if (tt_rc!=TT_OK)...

Generated with CERN WebMaker