TIBCO FTL®

Typedefs
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).