|
TIBCO ActiveSpaces®
|
This file defines calls that intialize and terminate an ActiveSpaces client. More...
Macros | |
| #define | TIBDG_COMPATIBILITY_VERSION (1) |
| #define | TIBDG_CONNECTION_BINDSTRATEGY_NAMED (1) |
| #define | TIBDG_CONNECTION_BINDSTRATEGY_RANDOM (0) |
| #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_LONG_BINDSTRATEGY "com.tibco.tibdg.connectbindstrategy" |
| Property name for specifying how a client chooses a proxy to establish a connection. More... | |
| #define | TIBDG_CONNECTION_PROPERTY_LONG_CONNECT_NUMRESPONSES "com.tibco.tibdg.connectnumresponses" |
| Property to cutoff wait time using TIBDG_BINDSTRATEGY_RANDOM. More... | |
| #define | TIBDG_CONNECTION_PROPERTY_LONG_REALM_CONNECT_RETRIES "com.tibco.tibdg.realmconnectretries" |
| Property name for initial realm connection retries; long. More... | |
| #define | TIBDG_CONNECTION_PROPERTY_STRING_CLIENT_LABEL "com.tibco.tibdg.clientlabel" |
| Property name for client label; string. More... | |
| #define | TIBDG_CONNECTION_PROPERTY_STRING_CONNECT_PROXYNAMES "com.tibco.tibdg.connectproxynames" |
| Property name for specifying pipe '|' delimited list of proxy names for TIBDG_BINDSTRATEGY_NAMED. 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_GRID_IN_MAINTENANCE (5003) |
| Error code returned when a grid in maintenance mode receives a write op. More... | |
| #define | TIBDG_GRIDMETADATA_PROPERTY_STRING_CHECKPOINT_NAME "com.tibco.tibdg.gridmetadata_checkpointname" |
| Property name for specifying a Checkpoint to be used when retrieving data grid and table metadata; 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_DOUBLE_FETCH_TIMEOUT "com.tibco.tibdg.fetch.timeout" |
| Property name for the iterator fetch timeout; double. 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_SESSION_PROPERTY_STRING_CHECKPOINT_NAME "com.tibco.tibdg.checkpointname" |
| Property name for specifying a Checkpoint to be used for reads; string. 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_LAST_ERROR_CODE (5199) |
| Marks the end of the error codes reserved for SQL related errors. 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_DOUBLE_FETCH_TIMEOUT "com.tibco.tibdg.statement.fetch.timeout" |
| Property name for the Statement fetch timeout; double. 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... | |
This file defines calls that intialize and terminate an ActiveSpaces client.
| #define TIBDG_COMPATIBILITY_VERSION (1) |
| #define TIBDG_CONNECTION_BINDSTRATEGY_NAMED (1) |
| #define TIBDG_CONNECTION_BINDSTRATEGY_RANDOM (0) |
| #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. This value should generally be kept to less than 10 seconds. For ways to reduce to reduce the binding time, refer to the documentation for TIBDG_CONNECTION_PROPERTY_LONG_BINDSTRATEGY and related properties.
Note: this duration applies once the realm connection has been established. If the realm server experiences disruption, up to 5 additional seconds may be required.
| #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_LONG_BINDSTRATEGY "com.tibco.tibdg.connectbindstrategy" |
Property name for specifying how a client chooses a proxy to establish a connection.
Supply this property to tibdgGrid_Connect.
TIBDG_BINDSTRATEGY_RANDOM will choose a proxy at random from the responses received. TIBDG_BINDSTRATEGY_NAMED will choose only a proxy supplied using the property TIBDG_CONNECTION_PROPERTY_STRING_CONNECT_PROXYNAMES
| #define TIBDG_CONNECTION_PROPERTY_LONG_CONNECT_NUMRESPONSES "com.tibco.tibdg.connectnumresponses" |
Property to cutoff wait time using TIBDG_BINDSTRATEGY_RANDOM.
No effect for other bind strategies
After receiving this many responses, the client will stop looking for additional responses
| #define TIBDG_CONNECTION_PROPERTY_LONG_REALM_CONNECT_RETRIES "com.tibco.tibdg.realmconnectretries" |
Property name for initial realm connection retries; long.
When connecting to a data grid, supply this property to DataGrid.connect. This value sets the number of times the underlying TIBCO FTL client library will attempt to connect to the Realm. The default is 5.
| #define TIBDG_CONNECTION_PROPERTY_STRING_CLIENT_LABEL "com.tibco.tibdg.clientlabel" |
Property name for client label; string.
It is good practice to include this property in tibdgGrid_Connect calls of every application program. Administrators can use client labels in monitoring and management to recognize and distinguish among processes.
| #define TIBDG_CONNECTION_PROPERTY_STRING_CONNECT_PROXYNAMES "com.tibco.tibdg.connectproxynames" |
Property name for specifying pipe '|' delimited list of proxy names for TIBDG_BINDSTRATEGY_NAMED.
A client using TIBDG_BINDSTRATEGY_NAMED will not bind to a proxy not in the list
Note: existing proxy names utilizing this reserved character are not eligible
| #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.
| #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_GRID_IN_MAINTENANCE (5003) |
Error code returned when a grid in maintenance mode receives a write op.
This error code will be returned when a client submits any operation that modifies the data on disk while the grid is in maintenance mode.
| #define TIBDG_GRIDMETADATA_PROPERTY_STRING_CHECKPOINT_NAME "com.tibco.tibdg.gridmetadata_checkpointname" |
Property name for specifying a Checkpoint to be used when retrieving data grid and table metadata; string.
Specifying this property instructs the data grid to use the named checkpoint when retrieving metadata for the data grid or tables.
| #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_DOUBLE_FETCH_TIMEOUT "com.tibco.tibdg.fetch.timeout" |
Property name for the iterator fetch timeout; double.
This value determines how long (in seconds) the application will wait for the next batch of rows before timing out. If this property is not supplied the current timeout for the parent Connection is used. If a value of zero is supplied then there will be no limit to how long the application will wait.
When creating an iterator, supply this property to tibdgTable_CreateIterator. This property can also be supplied to tibdgStatement_ExecuteQuery to override the value that was used when the statement was created.
| #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.
| #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_SESSION_PROPERTY_STRING_CHECKPOINT_NAME "com.tibco.tibdg.checkpointname" |
Property name for specifying a Checkpoint to be used for reads; string.
Specifying this property instructs the datagrid to use the named checkpoint as the data source for this session's read operations (gets, iterators, queries, or statements). Write operations (puts, deletes) do not support this property.
| #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_LAST_ERROR_CODE (5199) |
Marks the end of the error codes reserved for SQL related errors.
This error code is never returned but can be used to see if a specific error code falls within the range of error codes related to SQL processing.
| #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 methods tibdgSession_CreateStatement and tibdgStatement_ExecuteQuery.
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 methods tibdgSession_CreateStatement and tibdgStatement_ExecuteQuery.
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_DOUBLE_FETCH_TIMEOUT "com.tibco.tibdg.statement.fetch.timeout" |
Property name for the Statement fetch timeout; double.
This value determines how long (in seconds) the application will wait for the next batch of rows before timing out. If this property is not supplied the current timeout for the parent Connection is used. If a value of zero is supplied then there will be no limit to how long the application will wait.
When creating a statement, supply this property to tibdgSession_CreateStatement. This property can also be supplied to tibdgStatement_ExecuteQuery to override the value that was used when the statement was created.
| #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. This property can also be supplied to tibdgStatement_ExecuteQuery to override the value that was used when the statement was created.
| #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. This property can also be supplied to tibdgStatement_ExecuteQuery to override the value that was used when the statement was created.
| 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.
| e | The exception object captures information about failures. |
| 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.
| e | The exception object captures information about failures. |
| compatible_version | The program must supply the constant TIBDG_COMPATIBILITY_VERSION. |
1.8.5