Handling Errors

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:

• Tt_status

• int

• char* or opaque handle

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:

• Without a problem -- the Tt_status code returned is TT_OK.

• With a problem -- the Tt_status code returned is TT_ERR_SESSION. This status code informs you that the sessid you passed was not valid.

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

The return type for these function is Tt_status.

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

Returned Value Status

The following sections describe the return value status of functions with natural return values and functions with no natural return value.

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 the return value is 0, the Tt_status enum is either TT_OK or a warning.

• If the return value is 1, the Tt_status enum is an error.

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 Example 14-1.

Example 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));
}

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.

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

Example 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;
}

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.

Example 14-3 checks a returned integer.

Example 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));
}