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_BINDSTRATEGY_BALANCED (2)
#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_BOOLEAN_IMMUTABLE_ROWS "com.tibco.tibdg.immutablerows"
| Property to specify immutability of rows returned from ResultSet/Get APIs. 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 or TIBDG_CONNECTION_BINDSTRATEGY_BALANCED. More...
#define | TIBDG_CONNECTION_PROPERTY_LONG_OWNER_ID "com.tibco.tibdg.ownerid"
| Property to specify owner ID of this connection, for use with single owner tables. 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_LONG_TRANSPORT_TYPE "com.tibco.tibdg.tporttype"
| Property to indicate the type of transport the client will use to connect to proxies; 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_CONNECTION_TRANSPORT_TYPE_AUTO (1)
#define | TIBDG_CONNECTION_TRANSPORT_TYPE_DTCP (0)
#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_LISTENER_PROPERTY_STRING_EVENT_TYPE_LIST "com.tibco.tibdg.listener.eventtypelist"
| Property name for Listener event type list; string. More...
#define | TIBDG_SESSION_PROPERTY_BOOLEAN_IMMUTABLE_ROWS "com.tibco.tibdg.session.immutablerows"
| Property to specify immutability of rows returned from ResultSet/Get APIs. 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_BAD_BATCH (5112)
| Error code returned when a command in a batch of SQL commands causes the entire batch to fail. More...
#define | TIBDG_SQL_CMD_ERROR (5110)
| Error code returned when there is a generic error with a SQL command. More...
#define | TIBDG_SQL_DDL_CMD_ERROR (5107)
| Error code returned when there is an error during DDL command processing. More...
#define | TIBDG_SQL_DML_CMD_ERROR (5109)
| Error code returned when there is an error during DML 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_PERMITTED (5111)
| Error code returned a SQL statement encounters something which is not permitted. 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_RESOURCE_UNAVAILABLE (5113)
| Error code returned when a command failed but could succeed if it is run again. 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_DOUBLE_UPDATE_TIMEOUT "com.tibco.tibdg.statement.update.timeout"
| Property name for the Statement update 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...

## Detailed Description

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

## Macro Definition Documentation

## ◆ TIBDG_COMPATIBILITY_VERSION

#define TIBDG_COMPATIBILITY_VERSION (1)

## ◆ TIBDG_CONNECTION_BINDSTRATEGY_BALANCED

#define TIBDG_CONNECTION_BINDSTRATEGY_BALANCED (2)

## ◆ TIBDG_CONNECTION_BINDSTRATEGY_NAMED

#define TIBDG_CONNECTION_BINDSTRATEGY_NAMED (1)

## ◆ TIBDG_CONNECTION_BINDSTRATEGY_RANDOM

#define TIBDG_CONNECTION_BINDSTRATEGY_RANDOM (0)

## ◆ TIBDG_CONNECTION_HTTPS_CONNECTION_TRUST_EVERYONE

#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.

## ◆ TIBDG_CONNECTION_HTTPS_CONNECTION_USE_SPECIFIED_TRUST_FILE

#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.

## ◆ TIBDG_CONNECTION_PROPERTY_BOOLEAN_IMMUTABLE_ROWS

#define TIBDG_CONNECTION_PROPERTY_BOOLEAN_IMMUTABLE_ROWS "com.tibco.tibdg.immutablerows"

Property to specify immutability of rows returned from ResultSet/Get APIs.

Supply this property to tibdgGrid_Connect.

If true, rows returned cannot be modified.

If unspecified, the default value is false.

## ◆ TIBDG_CONNECTION_PROPERTY_DOUBLE_CONNECT_WAIT_TIME

#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.

## ◆ TIBDG_CONNECTION_PROPERTY_DOUBLE_TIMEOUT

#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.

## ◆ TIBDG_CONNECTION_PROPERTY_LONG_BINDSTRATEGY

#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_CONNECTION_BINDSTRATEGY_RANDOM will choose a proxy at random from the responses received. TIBDG_CONNECTION_BINDSTRATEGY_NAMED will choose only a proxy supplied using the property TIBDG_CONNECTION_PROPERTY_STRING_CONNECT_PROXYNAMES TIBDG_CONNECTION_BINDSTRATEGY_BALANCED will choose the proxy with the lowest load from the responses received.

## ◆ TIBDG_CONNECTION_PROPERTY_LONG_CONNECT_NUMRESPONSES

#define TIBDG_CONNECTION_PROPERTY_LONG_CONNECT_NUMRESPONSES "com.tibco.tibdg.connectnumresponses"

Property to cutoff wait time using TIBDG_BINDSTRATEGY_RANDOM or TIBDG_CONNECTION_BINDSTRATEGY_BALANCED.

No effect for other bind strategies

After receiving this many responses, the client will stop looking for additional responses

## ◆ TIBDG_CONNECTION_PROPERTY_LONG_OWNER_ID

#define TIBDG_CONNECTION_PROPERTY_LONG_OWNER_ID "com.tibco.tibdg.ownerid"

Property to specify owner ID of this connection, for use with single owner tables.

Must be a 64-bit integer value greater than zero.

## ◆ TIBDG_CONNECTION_PROPERTY_LONG_REALM_CONNECT_RETRIES

#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 tibdgGrid_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.

## ◆ TIBDG_CONNECTION_PROPERTY_LONG_TRANSPORT_TYPE

#define TIBDG_CONNECTION_PROPERTY_LONG_TRANSPORT_TYPE "com.tibco.tibdg.tporttype"

Property to indicate the type of transport the client will use to connect to proxies; long.

Supply this property to tibdgGrid_Connect.

The type of transport used by the client when this property is not provided is determined by the grid configuration.

TIBDG_CONNECTION_TRANSPORT_TYPE_DTCP will enable the client to connect to proxy processes via DTCP TIBDG_CONNECTION_TRANSPORT_TYPE_AUTO will enable the client to connect to proxies via an Auto Transport

## ◆ TIBDG_CONNECTION_PROPERTY_STRING_CLIENT_LABEL

#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.

## ◆ TIBDG_CONNECTION_PROPERTY_STRING_CONNECT_PROXYNAMES

#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

## ◆ TIBDG_CONNECTION_PROPERTY_STRING_SECONDARY_REALM

#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

## ◆ TIBDG_CONNECTION_PROPERTY_STRING_TRUST_FILE

#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.

## ◆ TIBDG_CONNECTION_PROPERTY_STRING_TRUST_TYPE

#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

## ◆ TIBDG_CONNECTION_PROPERTY_STRING_USERNAME

#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.

## ◆ TIBDG_CONNECTION_PROPERTY_STRING_USERPASSWORD

#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.

## ◆ TIBDG_CONNECTION_TRANSPORT_TYPE_AUTO

#define TIBDG_CONNECTION_TRANSPORT_TYPE_AUTO (1)

## ◆ TIBDG_CONNECTION_TRANSPORT_TYPE_DTCP

#define TIBDG_CONNECTION_TRANSPORT_TYPE_DTCP (0)

## ◆ TIBDG_GRID_IN_MAINTENANCE

#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.

## ◆ TIBDG_GRIDMETADATA_PROPERTY_STRING_CHECKPOINT_NAME

#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.

## ◆ TIBDG_INVALID_RESOURCE

#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.

## ◆ TIBDG_ITERATOR_CONSISTENCY_GLOBAL_SNAPSHOT

#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.

## ◆ TIBDG_ITERATOR_CONSISTENCY_SNAPSHOT

#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.

## ◆ TIBDG_ITERATOR_PROPERTY_DOUBLE_FETCH_TIMEOUT

#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. The use of an unlimited timeout is NOT advised in production environments because there are certain error situations that can result in the application waiting forever for a response that will not come. An unlimited timeout could be used in testing/development to discover how long a given iterator takes to execute so that a meaningful timeout can be set in production.

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.

## ◆ TIBDG_ITERATOR_PROPERTY_LONG_PREFETCH

#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. If not specified or a value <= 0 is specified, a default prefetch of 256 is used.

## ◆ TIBDG_ITERATOR_PROPERTY_STRING_CONSISTENCY

#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

## ◆ TIBDG_LISTENER_PROPERTY_STRING_EVENT_TYPE_LIST

#define TIBDG_LISTENER_PROPERTY_STRING_EVENT_TYPE_LIST "com.tibco.tibdg.listener.eventtypelist"

Property name for Listener event type list; string.

When creating a table listener, supply this property to tibdgTable_CreateListener. Its value should be a string containing a comma separated list of event types that can be used to configure the listener to only receive events of a specific type or types (ex: only expired and deleted). Only put, delete, and expired are currently supported as valid event types to use in the string. Error events will always be delivered. Use the utility function tibdgEventTypeList_ToString to construct the string from an array of event types.

## ◆ TIBDG_SESSION_PROPERTY_BOOLEAN_IMMUTABLE_ROWS

#define TIBDG_SESSION_PROPERTY_BOOLEAN_IMMUTABLE_ROWS "com.tibco.tibdg.session.immutablerows"

Property to specify immutability of rows returned from ResultSet/Get APIs.

Supply this property to tibdgConnection_CreateSession.

If true, rows returned cannot be modified.

If unspecified, the default value is inherited from the parent connection property com.tibco.tibdg.immutablerows, which is false by default.

## ◆ TIBDG_SESSION_PROPERTY_BOOLEAN_TRANSACTED

#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.

## ◆ TIBDG_SESSION_PROPERTY_STRING_CHECKPOINT_NAME

#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.

## ◆ TIBDG_SQL_BAD_BATCH

#define TIBDG_SQL_BAD_BATCH (5112)

Error code returned when a command in a batch of SQL commands causes the entire batch to fail.

This error code will be returned when a batch of SQL commands could not be successfully processed due to one or more bad commands in the batch. When this happens, the entire batch of commands is rolled back.

## ◆ TIBDG_SQL_CMD_ERROR

#define TIBDG_SQL_CMD_ERROR (5110)

Error code returned when there is a generic error with a SQL command.

This error code will be returned when a generic SQL command error occurs during the processing of a SQL command in the data grid.

## ◆ TIBDG_SQL_DDL_CMD_ERROR

#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 in the data grid.

## ◆ TIBDG_SQL_DML_CMD_ERROR

#define TIBDG_SQL_DML_CMD_ERROR (5109)

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

This error code will be returned when an unexpected error occurs during the processing of an INSERT, UPDATE or DELETE command in the data grid.

## ◆ TIBDG_SQL_INVALID_VALUE

#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.

## ◆ TIBDG_SQL_LAST_ERROR_CODE

#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.

## ◆ TIBDG_SQL_NOT_PERMITTED

#define TIBDG_SQL_NOT_PERMITTED (5111)

Error code returned a SQL statement encounters something which is not permitted.

This error code will be returned if a SQL statement tries to do something which is not by the data grid permitted.

## ◆ TIBDG_SQL_NOT_SUPPORTED

#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.

## ◆ TIBDG_SQL_PARSER_ERROR

#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.

## ◆ TIBDG_SQL_QUERY_CMD_ERROR

#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.

## ◆ TIBDG_SQL_QUERY_ERROR

#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.

## ◆ TIBDG_SQL_RESOURCE_UNAVAILABLE

#define TIBDG_SQL_RESOURCE_UNAVAILABLE (5113)

Error code returned when a command failed but could succeed if it is run again.

This error code will be returned when a SQL command could not be successfully processed due to a resource needed by the command being unavailable. Running the command again might result in it being successfully processed.

## ◆ TIBDG_SQL_STMT_ERROR

#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.

## ◆ TIBDG_SQL_SYNTAX_ERROR

#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.

## ◆ TIBDG_SQL_SYSTEM_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.

## ◆ TIBDG_STATEMENT_CONSISTENCY_GLOBAL_SNAPSHOT

#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.

## ◆ TIBDG_STATEMENT_CONSISTENCY_SNAPSHOT

#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.

## ◆ TIBDG_STATEMENT_PROPERTY_DOUBLE_FETCH_TIMEOUT

#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. The use of an unlimited timeout is NOT advised in production environments because there are certain error situations that can result in the application waiting forever for a response that will not come. An unlimited timeout could be used in testing/development to discover how long a given query takes to execute so that a meaningful timeout can be set in production.

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.

## ◆ TIBDG_STATEMENT_PROPERTY_DOUBLE_UPDATE_TIMEOUT

#define TIBDG_STATEMENT_PROPERTY_DOUBLE_UPDATE_TIMEOUT "com.tibco.tibdg.statement.update.timeout"

Property name for the Statement update timeout; double.

This value determines how long (in seconds) the application will wait for a reply to an ExecuteUpdate request, on a statement, 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. The use of an unlimited timeout is NOT advised in production environments because there are certain error situations that can result in the application waiting forever for a response that will not come. An unlimited timeout could be used in testing/development to discover how long a given update takes to execute so that a meaningful timeout can be set in production.

When creating a statement, supply this property to tibdgSession_CreateStatement. This property can also be supplied to tibdgStatement_ExecuteUpdate to override the value that was used when the statement was created.

## ◆ TIBDG_STATEMENT_PROPERTY_LONG_PREFETCH

#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. If not specified or a value <= 0 is specified, a default prefetch of 256 is used.

## ◆ TIBDG_STATEMENT_PROPERTY_STRING_CONSISTENCY

#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.

See also
  TIBDG_STATEMENT_CONSISTENCY_GLOBAL_SNAPSHOT
  TIBDG_STATEMENT_CONSISTENCY_SNAPSHOT

## Function Documentation

## ◆ tibdg_Close()

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

  e | The exception object captures information about failures.

Returns
  void

## ◆ tibdg_Open()

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

  e | The exception object captures information about failures.
  compatible_version | The program must supply the constant TIBDG_COMPATIBILITY_VERSION.

Returns
  void