TIBCO ActiveSpaces®
Macros | Functions
tibdg.h File Reference

This file defines calls that intialize and terminate an ActiveSpaces client. More...

Macros

#define TIBDG_COMPATIBILITY_VERSION   (1)
 
#define TIBDG_CONNECTION_HTTPS_CONNECTION_TRUST_EVERYONE   "trust_everyone"
 Trust any realm server; property value constant. More...
 
#define TIBDG_CONNECTION_HTTPS_CONNECTION_USE_SPECIFIED_TRUST_FILE   "trust_file"
 Trust a realm server if its certificate is in a trust file; property value constant. More...
 
#define TIBDG_CONNECTION_PROPERTY_DOUBLE_CONNECT_WAIT_TIME   "com.tibco.tibdg.connectwaittime"
 Property name for initial connection timeout; double. More...
 
#define TIBDG_CONNECTION_PROPERTY_DOUBLE_TIMEOUT   "com.tibco.tibdg.timeout"
 Property name for connection timeout; double. More...
 
#define TIBDG_CONNECTION_PROPERTY_STRING_SECONDARY_REALM   "com.tibco.tibdg.connection.secondaryrealm"
 Property name for specifying secondary/backup realm server; string. More...
 
#define TIBDG_CONNECTION_PROPERTY_STRING_TRUST_FILE   "com.tibco.tibdg.trust.file"
 Property name for secure realm server trust file; string. More...
 
#define TIBDG_CONNECTION_PROPERTY_STRING_TRUST_TYPE   "com.tibco.tibdg.trust.type"
 Property name for secure realm server trust type; long. More...
 
#define TIBDG_CONNECTION_PROPERTY_STRING_USERNAME   "com.tibco.tibdg.username"
 Property name for realm server username; string. More...
 
#define TIBDG_CONNECTION_PROPERTY_STRING_USERPASSWORD   "com.tibco.tibdg.userpassword"
 Property name for realm server password; string. More...
 
#define TIBDG_INVALID_RESOURCE   (5002)
 Error code returned when a resource needs to be recreated; property value constant. More...
 
#define TIBDG_ITERATOR_CONSISTENCY_GLOBAL_SNAPSHOT   "global_snapshot"
 Global snapshot consistency; property value constant. More...
 
#define TIBDG_ITERATOR_CONSISTENCY_SNAPSHOT   "snapshot"
 Snapshot consistency; property value constant. More...
 
#define TIBDG_ITERATOR_PROPERTY_LONG_PREFETCH   "com.tibco.tibdg.prefetch"
 Property name for iterator prefetch; long. More...
 
#define TIBDG_ITERATOR_PROPERTY_STRING_CONSISTENCY   "com.tibco.tibdg.consistency"
 Property name for iterator consistency; string. More...
 
#define TIBDG_SESSION_PROPERTY_BOOLEAN_TRANSACTED   "com.tibco.tibdg.transacted"
 Property name for a transacted session; boolean. More...
 
#define TIBDG_SQL_DDL_CMD_ERROR   (5107)
 Error code returned when there is an error during DDL command processing. More...
 
#define TIBDG_SQL_INVALID_VALUE   (5102)
 Error code returned when a SQL statement specifies an invalid value. More...
 
#define TIBDG_SQL_NOT_SUPPORTED   (5101)
 Error code returned when a SQL statement includes an unsupported feature. More...
 
#define TIBDG_SQL_PARSER_ERROR   (5103)
 Error code returned when there is a SQL parser error. More...
 
#define TIBDG_SQL_QUERY_CMD_ERROR   (5108)
 Error code returned when there is an error with a query command. More...
 
#define TIBDG_SQL_QUERY_ERROR   (5106)
 Error code returned when there is an error during query processing. More...
 
#define TIBDG_SQL_STMT_ERROR   (5104)
 Error code returned when there is an error relating to a SQL statement. More...
 
#define TIBDG_SQL_SYNTAX_ERROR   (5100)
 Error code returned when an error is detected in the syntax of a SQL statement. More...
 
#define TIBDG_SQL_SYSTEM_ERROR   (5105)
 Error code returned when there is an internal SQL system error. More...
 
#define TIBDG_STATEMENT_CONSISTENCY_GLOBAL_SNAPSHOT   "global_snapshot"
 Global snapshot consistency; property value constant. More...
 
#define TIBDG_STATEMENT_CONSISTENCY_SNAPSHOT   "snapshot"
 Snapshot consistency; property value constant. More...
 
#define TIBDG_STATEMENT_PROPERTY_LONG_PREFETCH   "com.tibco.tibdg.statement.prefetch"
 Property name for Statement query prefetch; long. More...
 
#define TIBDG_STATEMENT_PROPERTY_STRING_CONSISTENCY   "com.tibco.tibdg.statement.consistency"
 Property name for Statement consistency; string. More...
 

Functions

TIBDG_API void tibdg_Close (tibEx e)
 Cleanup ActiveSpaces. More...
 
TIBDG_API void tibdg_Open (tibEx e, tibint32_t compatible_version)
 Initialize ActiveSpaces. More...
 

Detailed Description

This file defines calls that intialize and terminate an ActiveSpaces client.

Macro Definition Documentation

#define TIBDG_COMPATIBILITY_VERSION   (1)
#define TIBDG_CONNECTION_HTTPS_CONNECTION_TRUST_EVERYONE   "trust_everyone"

Trust any realm server; property value constant.

This constant is one possible value of the property TIBDG_CONNECTION_PROPERTY_STRING_TRUST_TYPE in the method tibdgGrid_Connect.

The client trusts any realm server without verifying trust in the server's certificate. Do not use this value except for convenience in development and testing. It is not secure.

#define TIBDG_CONNECTION_HTTPS_CONNECTION_USE_SPECIFIED_TRUST_FILE   "trust_file"

Trust a realm server if its certificate is in a trust file; property value constant.

This constant is one possible value of the property TIBDG_CONNECTION_PROPERTY_STRING_TRUST_TYPE in the method tibdgGrid_Connect.

The client trusts the realm server based on the trust file created by the realm server and distributed by the administrator.

Specify the file path of the trust file in the property TIBDG_CONNECTION_PROPERTY_STRING_TRUST_FILE.

#define TIBDG_CONNECTION_PROPERTY_DOUBLE_CONNECT_WAIT_TIME   "com.tibco.tibdg.connectwaittime"

Property name for initial connection timeout; double.

When connecting to a data grid, supply this property to tibdgGrid_Connect. This value sets the fixed amount of time the call will wait inside tibdgGrid_Connect while it collects proxy responses. The value must be set to greater than the client-proxy roundtrip time or the connection will fail and must be retried. Default is 0.1 seconds.

#define TIBDG_CONNECTION_PROPERTY_DOUBLE_TIMEOUT   "com.tibco.tibdg.timeout"

Property name for connection timeout; double.

When connecting to a data grid, supply this property to tibdgGrid_Connect. Its value determines how long all calls, other than tibdgGrid_Connect, block waiting for the data grid to respond. Default is 5.0 seconds.

#define TIBDG_CONNECTION_PROPERTY_STRING_SECONDARY_REALM   "com.tibco.tibdg.connection.secondaryrealm"

Property name for specifying secondary/backup realm server; string.

When connecting to a data grid, supply this property to tibdgGrid_Connect. This value sets the url of the realm server to use in case of failures of the primary

#define TIBDG_CONNECTION_PROPERTY_STRING_TRUST_FILE   "com.tibco.tibdg.trust.file"

Property name for secure realm server trust file; string.

When connecting to a secure realm server, supply this property to tibdgGrid_Connect.

If the grid connect call specifies the trust type as TIBDG_CONNECTION_HTTPS_CONNECTION_USE_SPECIFIED_TRUST_FILE, use this property to indicate the location of the trust file.

#define TIBDG_CONNECTION_PROPERTY_STRING_TRUST_TYPE   "com.tibco.tibdg.trust.type"

Property name for secure realm server trust type; long.

When connecting to a secure realm server, supply this property to tibdgGrid_Connect. Its value determines trust in the realm server's certificate.

See Also
TIBDG_CONNECTION_HTTPS_CONNECTION_USE_SPECIFIED_TRUST_FILE
TIBDG_CONNECTION_HTTPS_CONNECTION_TRUST_EVERYONE
#define TIBDG_CONNECTION_PROPERTY_STRING_USERNAME   "com.tibco.tibdg.username"

Property name for realm server username; string.

Supply this property to tibdgGrid_Connect if using a secure realm server.

#define TIBDG_CONNECTION_PROPERTY_STRING_USERPASSWORD   "com.tibco.tibdg.userpassword"

Property name for realm server password; string.

Supply this property to tibdgGrid_Connect if using a secure realm server.

#define TIBDG_INVALID_RESOURCE   (5002)

Error code returned when a resource needs to be recreated; property value constant.

If a Prepared Statement exists prior to a grid redistribution, a subsequent Execute Query may fail. In this case, the Prepared Statement needs to be closed and recreated before running any more Execute Query commands.

#define TIBDG_ITERATOR_CONSISTENCY_GLOBAL_SNAPSHOT   "global_snapshot"

Global snapshot consistency; property value constant.

This constant is one possible value of the property TIBDG_ITERATOR_PROPERTY_STRING_CONSISTENCY in the method tibdgTable_CreateIterator.

This value will cause a global snapshot to be taken across all nodes in the grid, which will then be used when iterating through the results. A global snapshot will ensure no partially committed transactions that span multiple nodes are observed in the iterator results at the cost of needing to coordinate the global snapshot when creating the iterator.

#define TIBDG_ITERATOR_CONSISTENCY_SNAPSHOT   "snapshot"

Snapshot consistency; property value constant.

This constant is one possible value of the property TIBDG_ITERATOR_PROPERTY_STRING_CONSISTENCY in the method tibdgTable_CreateIterator.

This value will cause a snapshot to be taken at each node independently, which will then be used when iterating through the results. A snapshot taken at each node does not require waiting to create a global snapshot across the entire grid when creating the iterator but could result in a partially committed transaction that spanned multiple nodes being observed in the results.

#define TIBDG_ITERATOR_PROPERTY_LONG_PREFETCH   "com.tibco.tibdg.prefetch"

Property name for iterator prefetch; long.

When creating an iterator, supply this property to tibdgTable_CreateIterator. Its value determines the maximum number of rows that will be prefetched from the data grid.

#define TIBDG_ITERATOR_PROPERTY_STRING_CONSISTENCY   "com.tibco.tibdg.consistency"

Property name for iterator consistency; string.

When creating an iterator, supply this property to tibdgTable_CreateIterator. Its value determines the consistency of the iterator and whether or not a global snapshot needs to be taken.

See Also
TIBDG_ITERATOR_CONSISTENCY_GLOBAL_SNAPSHOT
TIBDG_ITERATOR_CONSISTENCY_SNAPSHOT
#define TIBDG_SESSION_PROPERTY_BOOLEAN_TRANSACTED   "com.tibco.tibdg.transacted"

Property name for a transacted session; boolean.

When creating a session, supply this property to tibdgConnection_CreateSession. The value true specifies that the created session will be transacted.

#define TIBDG_SQL_DDL_CMD_ERROR   (5107)

Error code returned when there is an error during DDL command processing.

This error code will be returned when an unexpected error occurs during the processing of a table or index DDL command by a tibdgnode.

#define TIBDG_SQL_INVALID_VALUE   (5102)

Error code returned when a SQL statement specifies an invalid value.

This error code will be returned if the string containing a SQL statement includes syntax which cannot be used in a particular scenario.

#define TIBDG_SQL_NOT_SUPPORTED   (5101)

Error code returned when a SQL statement includes an unsupported feature.

This error code will be returned if the string containing a SQL statement includes the syntax of an unsupported feature.

#define TIBDG_SQL_PARSER_ERROR   (5103)

Error code returned when there is a SQL parser error.

This error code will be returned when an unexpected error occurs during the parsing of a SQL statement.

#define TIBDG_SQL_QUERY_CMD_ERROR   (5108)

Error code returned when there is an error with a query command.

This error code will be returned when the query command cannot be processed by a tibdgnode due to an error in the command received by a tibdgnode.

#define TIBDG_SQL_QUERY_ERROR   (5106)

Error code returned when there is an error during query processing.

This error code will be returned when an unexpected error occurs during the processing of a query by a tibdgnode.

#define TIBDG_SQL_STMT_ERROR   (5104)

Error code returned when there is an error relating to a SQL statement.

This error code will be returned when an unexpected error occurs during the processing of a SQL statement.

#define TIBDG_SQL_SYNTAX_ERROR   (5100)

Error code returned when an error is detected in the syntax of a SQL statement.

This error code will be returned if the string containing a SQL statement contains a syntax error.

#define TIBDG_SQL_SYSTEM_ERROR   (5105)

Error code returned when there is an internal SQL system error.

This error code will be returned when an unexpected SQL system error occurs during the processing of a query.

#define TIBDG_STATEMENT_CONSISTENCY_GLOBAL_SNAPSHOT   "global_snapshot"

Global snapshot consistency; property value constant.

This constant is one possible value of the property TIBDG_STATEMENT_PROPERTY_STRING_CONSISTENCY in the method tibdgSession_CreateStatement.

This value will cause a global snapshot to be taken across all nodes in the grid when a query is executed, which will then be used when iterating through the results. A global snapshot will ensure no partially committed transactions that span multiple nodes are observed in the query results at the cost of needing to coordinate the global snapshot when executing the query.

#define TIBDG_STATEMENT_CONSISTENCY_SNAPSHOT   "snapshot"

Snapshot consistency; property value constant.

This constant is one possible value of the property TIBDG_STATEMENT_PROPERTY_STRING_CONSISTENCY in the method tibdgSession_CreateStatement.

This value will cause a snapshot to be taken at each node independently when a query is executed, which will then be used when iterating through the results. A snapshot taken at each node does not require waiting to create a global snapshot across the entire grid when executing the query but could result in a partially committed transaction that spanned multiple nodes being observed in the results.

#define TIBDG_STATEMENT_PROPERTY_LONG_PREFETCH   "com.tibco.tibdg.statement.prefetch"

Property name for Statement query prefetch; long.

When creating a statement, supply this property to tibdgSession_CreateStatement. Its value determines the maximum number of rows that will be prefetched from the data grid when executing a query.

#define TIBDG_STATEMENT_PROPERTY_STRING_CONSISTENCY   "com.tibco.tibdg.statement.consistency"

Property name for Statement consistency; string.

When creating a statement, supply this property to tibdgSession_CreateStatement. Its value determines the consistency when executing a query and whether or not a global snapshot needs to be taken.

See Also
TIBDG_STATEMENT_CONSISTENCY_GLOBAL_SNAPSHOT
TIBDG_STATEMENT_CONSISTENCY_SNAPSHOT

Function Documentation

TIBDG_API void tibdg_Close ( tibEx  e)

Cleanup ActiveSpaces.

This call terminates ActiveSpaces within your program, and reclaims related resources that tibdg_Open allocated and initialized.

Calls to tibdg_Close decrement the ActiveSpaces reference counter, but actually close terminate ActiveSpaces only when the counter reaches zero.

In each program, the number of calls to tibdg_Open() and tibdg_Close() must match.

Programs must not call tibdg_Close within an ActiveSpaces callback.

Programs must cleanup other ActiveSpaces objects before closing ActiveSpaces.

Parameters
eThe exception object captures information about failures.
Returns
void
TIBDG_API void tibdg_Open ( tibEx  e,
tibint32_t  compatible_version 
)

Initialize ActiveSpaces.

This call initializes ActiveSpaces within your program, including threads and global data structures.

The first time a program calls it, this call initializes ActiveSpaces. If the program (or a third-party package) calls it again, it increments a reference counter, but does not reinitialize ActiveSpaces. Calls to tibdg_Close decrement the ActiveSpaces reference counter, but actually terminate ActiveSpaces only when the counter reaches zero.

In each program, the number of calls to tibdg_Open() and tibdg_Close() must match.

Parameters
eThe exception object captures information about failures.
compatible_versionThe program must supply the constant TIBDG_COMPATIBILITY_VERSION.
Returns
void