except.h File Reference

Exceptions capture error information during FTL calls. More...

Macros
Error Codes
FTL exceptions can report these error and status codes.
#define	TIB_ALREADY_EXISTS   ((tibErrorCode) 14)
	Conflict with an existing object, value or definition. More...
#define	TIB_CLIENT_SHUTDOWN   ((tibErrorCode) 20)
	The program attempted an operation on an unusable realm object. More...
#define	TIB_END_OF_BUFFER   ((tibErrorCode) 12)
	End of buffer while parsing an inbound message. More...
#define	TIB_EXCEPTION   ((tibErrorCode) 100)
	Unclassified exception. More...
#define	TIB_FILE_IO_ERROR   ((tibErrorCode) 15)
	I/O error. More...
#define	TIB_FORMAT_UNAVAILABLE   ((tibErrorCode) 23)
	A format required by the client program is unavailable. More...
#define	TIB_ILLEGAL_STATE   ((tibErrorCode) 10)
	An action is inconsistent with internal state. More...
#define	TIB_INTR   ((tibErrorCode) 7)
	Thread internal interrupt. More...
#define	TIB_INVALID_ARG   ((tibErrorCode) 1)
	Invalid argument (or invalid value embedded in an argument). More...
#define	TIB_INVALID_CONFIG   ((tibErrorCode) 18)
	Invalid or contradictory property values. More...
#define	TIB_INVALID_FORMAT   ((tibErrorCode) 19)
	The FTL client library encountered a message with an invalid format. More...
#define	TIB_INVALID_TYPE   ((tibErrorCode) 17)
	Field datatype mismatch. More...
#define	TIB_INVALID_VALUE   ((tibErrorCode) 16)
	FTL internal error. More...
#define	TIB_LIMIT_REACHED   ((tibErrorCode) 22)
	A resource cannot accept data because it has reached a limit. More...
#define	TIB_NO_MEMORY   ((tibErrorCode) 2)
	Memory allocation failed. More...
#define	TIB_NOT_FOUND   ((tibErrorCode) 9)
	Cannot find a requested object. More...
#define	TIB_NOT_INITIALIZED   ((tibErrorCode) 5)
	The program has not yet called tib_Open to start FTL. More...
#define	TIB_NOT_PERMITTED   ((tibErrorCode) 8)
	Invalid operation (on a valid object). More...
#define	TIB_NOT_SUPPORTED   ((tibErrorCode) 11)
	Unsupported datatype or feature. More...
#define	TIB_NULL_EXCEPTION   ((tibErrorCode) -1)
	The program supplied NULL instead of an exception object. More...
#define	TIB_OK   ((tibErrorCode) 0)
	The FTL call completed correctly (success) – that is, no errors occurred in executing the FTL call. The return value is reliable. More...
#define	TIB_OS_ERROR   ((tibErrorCode) 6)
	An operating system call failed. More...
#define	TIB_RESOURCE_UNAVAILABLE   ((tibErrorCode) 21)
	A resource required by the client program is unavailable. More...
#define	TIB_TIMEOUT   ((tibErrorCode) 4)
	Internal timeout elapsed. More...
#define	TIB_UNKNOWN_SYSPROP   ((tibErrorCode) 101)
	The client detected a corrupted message during reassembly. More...
#define	TIB_VERSION_MISMATCH   ((tibErrorCode) 13)
	Incompatible versions of FTL components. More...

Typedefs
typedef int	tibErrorCode

Realm Service Error Codes
These exceptions occur primarily within the realm service. The client library may throw these exceptions.
#define	TIB_RS_ADMIN_OPERATION_FAILED   ((tibErrorCode) 1015)
	The requested administrative operation failed. More...
#define	TIB_RS_DB_GENERATION_MISMATCH   ((tibErrorCode) 1012)
	Fault-tolerant servers have different generations of the realm configuration. More...
#define	TIB_RS_INCOMPATIBLE_CLIENT   ((tibErrorCode) 1018)
	Client version is not compatible with configuration. More...
#define	TIB_RS_INTERNAL_SERVER_ERROR   ((tibErrorCode) 1003)
	Internal error. More...
#define	TIB_RS_INVALID_MODE   ((tibErrorCode) 1014)
	The server cannot resume in the requested mode. More...
#define	TIB_RS_INVALID_SESSION_USER   ((tibErrorCode) 1001)
	A client program or administrative utility supplied invalid authentication credentials. More...
#define	TIB_RS_INVALID_STATE   ((tibErrorCode) 1013)
	The server is in the wrong state for the requested operation. More...
#define	TIB_RS_KEY_NOT_FOUND   ((tibErrorCode) 1007)
	A client requested a value that is not in the database. More...
#define	TIB_RS_MISSING_CLIENT_ID   ((tibErrorCode) 1006)
	A client or utility omitted its client identifier from a protocol message. More...
#define	TIB_RS_MISSING_PROTOCOL   ((tibErrorCode) 1005)
	A client or utility omitted the protocol version from its intial handshake message. More...
#define	TIB_RS_PROTOCOL_MISMATCH   ((tibErrorCode) 1004)
	The communication protocol between the realm service and its clients has changed. More...
#define	TIB_RS_SERVER_IS_READONLY   ((tibErrorCode) 1009)
	The server is in a read-only state, so it cannot accept configuration changes. More...
#define	TIB_RS_SERVER_IS_SHUTTING_DOWN   ((tibErrorCode) 1010)
	The server does not accept requests during its exit sequence. More...
#define	TIB_RS_SERVER_IS_STARTING_UP   ((tibErrorCode) 1011)
	The server cannot accept requests until it completes its initialization sequence. More...
#define	TIB_RS_SERVER_ISNT_PAUSED   ((tibErrorCode) 1008)
	The server must be paused before attempting this operation. More...
#define	TIB_RS_UNKNOWN_ERROR   ((tibErrorCode) 1000)
	Internal error. More...
#define	TIB_RS_UNKNOWN_OPERATION_CODE   ((tibErrorCode) 1002)
	An administrative utility sent an invalid command. More...
#define	TIB_RS_UPDATE_IN_PROGRESS   ((tibErrorCode) 1016)
	Clients cannot connect while an update is in progress. Try to connect again after the update is complete. More...
typedef struct tibExStruct *	tibEx
TIB_IMPORT void	tibEx_Clear (tibEx e)
	Clear an exception object. More...
TIB_IMPORT tibEx	tibEx_Create (void)
	Create an exception object. More...
TIB_IMPORT void	tibEx_Destroy (tibEx e)
	Destroy an exception object. More...
TIB_IMPORT const char *	tibEx_GetDetailString (tibEx e)
	Get the detail string from an exception object. More...
TIB_IMPORT tibErrorCode	tibEx_GetErrorCode (tibEx e)
	Get the error code from an exception object. More...
TIB_IMPORT const char *	tibEx_GetSummaryString (tibEx e)
	Get the summary string from an exception object. More...
TIB_IMPORT int	tibEx_ToString (tibEx e, char *buffer, int buflen)
	Get the detailed description of an exception object. More...

Detailed Description

Exceptions capture error information during FTL calls.

This file defines FTL exception objects, calls that manipulate them, and the error codes that can appear within them.

Macro Definition Documentation

TIB_ALREADY_EXISTS

#define TIB_ALREADY_EXISTS   ((tibErrorCode) 14)

Conflict with an existing object, value or definition.

Common Diagnoses:

• Adding or setting a value conflicts with an existing value.

• Cannot add a subscriber to an event queue, because that subscriber is already associated with another queue.

• Erroneous realm configuration. Ask your administrator for assistance.

• Cannot create a subscriber on a non-shared durable because another subscriber on the same durable already exists within the same client process.

TIB_CLIENT_SHUTDOWN

#define TIB_CLIENT_SHUTDOWN   ((tibErrorCode) 20)

The program attempted an operation on an unusable realm object.

Common Diagnoses:

• The program has closed the realm object.
• The administrator has disabled the application.

TIB_END_OF_BUFFER

#define TIB_END_OF_BUFFER   ((tibErrorCode) 12)

End of buffer while parsing an inbound message.

Common Diagnoses:

• Message data is corrupted.

TIB_EXCEPTION

#define TIB_EXCEPTION   ((tibErrorCode) 100)

Unclassified exception.

TIB_FILE_IO_ERROR

#define TIB_FILE_IO_ERROR   ((tibErrorCode) 15)

I/O error.

Common Diagnoses:

• Error accessing shared memory.

• Error accessing file system.

TIB_FORMAT_UNAVAILABLE

#define TIB_FORMAT_UNAVAILABLE   ((tibErrorCode) 23)

A format required by the client program is unavailable.

Common Diagnoses:

• The format has not been made available to an application as a preload format.

TIB_ILLEGAL_STATE

#define TIB_ILLEGAL_STATE   ((tibErrorCode) 10)

An action is inconsistent with internal state.

Common Diagnoses:

• When a transport is associated with an inline event queue, it cannot be associated with any other event queue. Adding a subscriber to a queue can violate this restriction, triggering this exception. For a detailed explanation, see the book TIBCO FTL Development.

• The action would violate a low-level transport constraint.

TIB_INTR

#define TIB_INTR   ((tibErrorCode) 7)

Thread internal interrupt.

TIB_INVALID_ARG

#define TIB_INVALID_ARG   ((tibErrorCode) 1)

Invalid argument (or invalid value embedded in an argument).

Common Diagnoses:

• A NULL argument (where NULL is not acceptable).

• A nonsensical value.

• A field or property value does not match the required data type.

• A value is outside the range of legal values.

• An object that is invalid (that is, it has already been destroyed or closed).

• The realm object is closed.

TIB_INVALID_CONFIG

#define TIB_INVALID_CONFIG   ((tibErrorCode) 18)

Invalid or contradictory property values.

Common Diagnoses:

• Configuration mismatch among event queue discard policy properties.

• A program attempted to create a dynamic durable but the endpoint is not associated with a store.

• A program attempted to unsubscribe a dynamic durable but the endpoint is not associated with a store.

• An argument to an API call does not support the action of that call.

TIB_INVALID_FORMAT

#define TIB_INVALID_FORMAT   ((tibErrorCode) 19)

The FTL client library encountered a message with an invalid format.

Common Diagnoses:

• The library received a malformed message.
• The program supplied a malformed message to tibMessage_ReadFromByteArray.

TIB_INVALID_TYPE

#define TIB_INVALID_TYPE   ((tibErrorCode) 17)

Field datatype mismatch.

Common Diagnoses:

• A message field access call received a datatype indicator that does not match the actual datatype of the field's value.

• A message field access call received a datatype indicator that does not represent an FTL field datatype.

TIB_INVALID_VALUE

#define TIB_INVALID_VALUE   ((tibErrorCode) 16)

FTL internal error.

Common Diagnoses:

• FTL client cannot deserialize a malformed message.

• FTL internal I/O received a malformed packet.

• FTL client received a malformed realm definition.

TIB_LIMIT_REACHED

#define TIB_LIMIT_REACHED   ((tibErrorCode) 22)

A resource cannot accept data because it has reached a limit.

Common Diagnoses:

• A persistent store is full.

TIB_NO_MEMORY

#define TIB_NO_MEMORY   ((tibErrorCode) 2)

Memory allocation failed.

TIB_NOT_FOUND

#define TIB_NOT_FOUND   ((tibErrorCode) 9)

Cannot find a requested object.

Common Diagnoses:

• A property doesn't exist in a properties object.

• A transport doesn't exist in the realm.

• A field is not set in the message, or not defined in the format.

• A message iterator has already presented the last field of its message.

• Cannot connect to the FTL server at the URLs supplied.

• Cannot remove a subscriber from a queue because it is not associated with that queue.

• Cannot destroy a timer because it is not associated with the queue.

TIB_NOT_INITIALIZED

#define TIB_NOT_INITIALIZED   ((tibErrorCode) 5)

The program has not yet called tib_Open to start FTL.

TIB_NOT_PERMITTED

#define TIB_NOT_PERMITTED   ((tibErrorCode) 8)

Invalid operation (on a valid object).

Common Diagnoses:

• A program attempted to destroy a message that the program did not create (that is, the FTL library created it).

• A program attempted to unsubscribe a static durable. (Unsubscribe applies only to dynamic durables.)

• A program attempted to unsubscribe a dynamic durable, but the endpoint does not support dynamic durables.

TIB_NOT_SUPPORTED

#define TIB_NOT_SUPPORTED   ((tibErrorCode) 11)

Unsupported datatype or feature.

Common Diagnoses:

• A message from a later release of FTL contains a field datatype that this version does not support (that is, it cannot manipulate the value, nor resend it).

TIB_NULL_EXCEPTION

#define TIB_NULL_EXCEPTION   ((tibErrorCode) -1)

The program supplied NULL instead of an exception object.

Some calls require an actual exception object.
Other calls allow NULL as a special value.

TIB_OK

#define TIB_OK   ((tibErrorCode) 0)

The FTL call completed correctly (success) – that is, no errors occurred in executing the FTL call. The return value is reliable.

TIB_OS_ERROR

#define TIB_OS_ERROR   ((tibErrorCode) 6)

An operating system call failed.

Common Diagnoses:

• File access failed.

• Socket access failed.

TIB_RESOURCE_UNAVAILABLE

#define TIB_RESOURCE_UNAVAILABLE   ((tibErrorCode) 21)

A resource required by the client program is unavailable.

Common Diagnoses:

• A persistent application cannot access its store.

TIB_RS_ADMIN_OPERATION_FAILED

#define TIB_RS_ADMIN_OPERATION_FAILED   ((tibErrorCode) 1015)

The requested administrative operation failed.

TIB_RS_DB_GENERATION_MISMATCH

#define TIB_RS_DB_GENERATION_MISMATCH   ((tibErrorCode) 1012)

Fault-tolerant servers have different generations of the realm configuration.

TIB_RS_INCOMPATIBLE_CLIENT

#define TIB_RS_INCOMPATIBLE_CLIENT   ((tibErrorCode) 1018)

Client version is not compatible with configuration.

TIB_RS_INTERNAL_SERVER_ERROR

#define TIB_RS_INTERNAL_SERVER_ERROR   ((tibErrorCode) 1003)

Internal error.

Review the server log for details.

TIB_RS_INVALID_MODE

#define TIB_RS_INVALID_MODE   ((tibErrorCode) 1014)

The server cannot resume in the requested mode.

TIB_RS_INVALID_SESSION_USER

#define TIB_RS_INVALID_SESSION_USER   ((tibErrorCode) 1001)

A client program or administrative utility supplied invalid authentication credentials.

TIB_RS_INVALID_STATE

#define TIB_RS_INVALID_STATE   ((tibErrorCode) 1013)

The server is in the wrong state for the requested operation.

TIB_RS_KEY_NOT_FOUND

#define TIB_RS_KEY_NOT_FOUND   ((tibErrorCode) 1007)

A client requested a value that is not in the database.

TIB_RS_MISSING_CLIENT_ID

#define TIB_RS_MISSING_CLIENT_ID   ((tibErrorCode) 1006)

A client or utility omitted its client identifier from a protocol message.

TIB_RS_MISSING_PROTOCOL

#define TIB_RS_MISSING_PROTOCOL   ((tibErrorCode) 1005)

A client or utility omitted the protocol version from its intial handshake message.

TIB_RS_PROTOCOL_MISMATCH

#define TIB_RS_PROTOCOL_MISMATCH   ((tibErrorCode) 1004)

The communication protocol between the realm service and its clients has changed.

Common Diagnoses:

• A significant version difference between the realm service and the FTL client library prevents communcation.

TIB_RS_SERVER_IS_READONLY

#define TIB_RS_SERVER_IS_READONLY   ((tibErrorCode) 1009)

The server is in a read-only state, so it cannot accept configuration changes.

TIB_RS_SERVER_IS_SHUTTING_DOWN

#define TIB_RS_SERVER_IS_SHUTTING_DOWN   ((tibErrorCode) 1010)

The server does not accept requests during its exit sequence.

TIB_RS_SERVER_IS_STARTING_UP

#define TIB_RS_SERVER_IS_STARTING_UP   ((tibErrorCode) 1011)

The server cannot accept requests until it completes its initialization sequence.

TIB_RS_SERVER_ISNT_PAUSED

#define TIB_RS_SERVER_ISNT_PAUSED   ((tibErrorCode) 1008)

The server must be paused before attempting this operation.

TIB_RS_UNKNOWN_ERROR

#define TIB_RS_UNKNOWN_ERROR   ((tibErrorCode) 1000)

Internal error.

TIB_RS_UNKNOWN_OPERATION_CODE

#define TIB_RS_UNKNOWN_OPERATION_CODE   ((tibErrorCode) 1002)

An administrative utility sent an invalid command.

Common Diagnoses:

• A newer version of the administrative utility sent a command that an older version of the realm service does not recogize.

TIB_RS_UPDATE_IN_PROGRESS

#define TIB_RS_UPDATE_IN_PROGRESS   ((tibErrorCode) 1016)

Clients cannot connect while an update is in progress. Try to connect again after the update is complete.

TIB_TIMEOUT

#define TIB_TIMEOUT   ((tibErrorCode) 4)

Internal timeout elapsed.

Common Diagnoses:

• Cannot connect to an FTL server within a reasonable time period.

• A transport failed to start within a reasonable time period.

TIB_UNKNOWN_SYSPROP

#define TIB_UNKNOWN_SYSPROP   ((tibErrorCode) 101)

The client detected a corrupted message during reassembly.

TIB_VERSION_MISMATCH

#define TIB_VERSION_MISMATCH   ((tibErrorCode) 13)

Incompatible versions of FTL components.

Common Diagnoses:

• Your program compiled and linked different compatibility versions of FTL; see tib_Open and TIB_COMPATIBILITY_VERSION.

• The FTL client library is not compatible with the FTL server.

Typedef Documentation

tibErrorCode

typedef int tibErrorCode

tibEx

typedef struct tibExStruct* tibEx

Function Documentation

tibEx_Clear()

TIB_IMPORT void tibEx_Clear

(

tibEx

e

)

Clear an exception object.

When an FTL call receives an exception argument that already indicates an error, the call returns immediately. That is, the call has no effect, and the exception's error code remains unchanged.

Your code can clear an exception before passing it to another FTL call, so that call can operate correctly.

Parameters

e	The call clears this exception object.

Returns

void

tibEx_Create()

TIB_IMPORT tibEx tibEx_Create

(

void

)

Create an exception object.

An exception object captures information about failures within FTL API calls.

1. A program creates an exception object.

2. The program passes a cleared exception object as the first parameter to an FTL call.

3. The FTL call stores a return code in the exception object before the call returns.

4. The program must check the return code before using any return value or output parameter from the call. If the code represents an error (that is, any code other than TIB_OK), then values from the call are unreliable.

When an FTL call receives an exception argument that already indicates an error, the call returns immediately. That is, the call has no effect, and the exception's error code remains unchanged.

To clear an exception's error code (so that calls that receive it can operate correctly), use tibEx_Clear.

Exception objects are not thread-safe. Programs must not access an exception object simultaneously from different threads.

Returns

a new exception object

tibEx_Destroy()

TIB_IMPORT void tibEx_Destroy

(

tibEx

e

)

Destroy an exception object.

Parameters

e	The call destroys this exception object.

Returns

void

tibEx_GetDetailString()

TIB_IMPORT const char * tibEx_GetDetailString

(

tibEx

e

)

Get the detail string from an exception object.

This call returns NULL if no details are available. Otherwise, this call returns a NULL-terminated string that describes the exception in detail.

Programs can output this detail string to end users, administrators or log files.

Parameters

e	The call gets the detail string from this exception object.

Returns

a pointer to the detail string

tibEx_GetErrorCode()

TIB_IMPORT tibErrorCode tibEx_GetErrorCode

(

tibEx

e

)

Get the error code from an exception object.

TIB_OK indicates that the call returned correctly.

If the exception is NULL, this call returns TIB_NULL_EXCEPTION, indicating that your program erroneously passed NULL as the exception argument (instead of an actual exception object).

Parameters

e	The call returns the error code from this exception object.

Returns

the error code

tibEx_GetSummaryString()

TIB_IMPORT const char * tibEx_GetSummaryString

(

tibEx

e

)

Get the summary string from an exception object.

This call returns a brief NULL-terminated string that describes the exception object's error code.

Parameters

e	The call gets the summary string from this exception object.

Returns

a pointer to the summary string

tibEx_ToString()

TIB_IMPORT int tibEx_ToString	(	tibEx	e,
		char *	buffer,
		int	buflen
	)

Get the detailed description of an exception object.

Programs can output this description to end users, administrators or log files.

The description string includes this information:

• Error code number
• Summary string (see tibEx_GetSummaryString)
• Detail about the error (could be empty; see tibEx_GetDetailString)
• Name of the thread in which the error occurred
• Stack trace

If a program passes NULL as the buffer argument, this call returns the length of the description string, without actually writing it.

If the non-null buffer is too short for the entire description string, the call writes to the end of the buffer, truncating the string, and returns the actual number of bytes in the buffer.

Parameters

e	The call returns a string corresponding to this exception object.
buffer	The program supplies a string location, into which the call stores the description. We recommend a buffer of at least 2 kilobytes.
buflen	The program supplies the length of the buffer (in bytes).

Returns

• On success, this call returns the actual length of the description string (that is, the actual number of bytes the call wrote into the buffer), including the terminating NULL character.
• On failure, this call returns zero, indicating failure (and the buffer remains unchanged).