NuoDB Database Connection. More...

#include <connection.h>

Data Fields
_NuoDB_Connection_state_t *	_state

NuoDB_Status(*	commit )(NuoDB_Connection *connection)
	Commit any outstanding SQL statements.

char (	convertUtf8ToLocal )(NuoDB_Connection connection, const char s, size_t sLen)
	Convert the given, presumably UTF-8 string, to the local encoding using the NuoDB_Connection's active encoding.

const char (	getActiveEncoding )(NuoDB_Connection *connection)
	Return the name of the active encoding for this NuoDB_connection which may not be the same as the default encoding for this NuoDB_Connection.

NuoDB_Status(*	getAutoCommit )(NuoDB_Connection connection, nuodb_bool_t autoCommit)
	Determine if the NuoDB_Connection has the auto-commit flag set.

const char (	getConnectionURL )(NuoDB_Connection *connection)
	Returns the connection URL string.

int(*	getConnectionVersion )(NuoDB_Connection *connection)
	Returns the connection version.

const char (	getDefaultEncoding )(NuoDB_Connection *connection)
	Return the name of the default encoding for this NuoDB_Connection.

NuoDB_EngineHandle (	getEngineHandle )(NuoDB_Connection *connection)
	Get a handle to the NuoDB Engine.

NuoDB_DatabaseMetaData (	getMetaData )(NuoDB_Connection *connection)
	Retrieve metadata for the database associated to this NuoDB_Connection.

NuoDB_Status(*	getNextSequenceValue )(NuoDB_Connection connection, const char schema, const char sequenceName, int64_t sequence)
	Returns next sequence value.

int(*	getProtocolVersion )(NuoDB_Connection *connection)

NuoDB_Status(*	getSchema )(NuoDB_Connection connection, char schemaName, size_t length)
	Retrieves this connection's current schema name.

NuoDB_Status(*	getTransactionIsolation )(NuoDB_Connection connection, NuoDB_TransactionIsolationLevel isolationLevel)
	Retrieves this NuoDB_Connection data structure's current transaction isolation level.

nuodb_bool_t(*	isConnected )(NuoDB_Connection *connection)
	Determine if the client has a valid connection to a NuoDB TE.

nuodb_bool_t(*	isReadOnly )(NuoDB_Connection *connection)
	Retrieves whether this NuoDB_Connection data structure is in read-only mode.

nuodb_bool_t(*	isUtf8 )(NuoDB_Connection *connection)
	Retrieves whether this NuoDB_Connection data structure is using UTF-8 strings.

NuoDB_Status(*	openDatabase )(NuoDB_Connection connection, const char dbname, const char user, const char password, NuoDB_Options *options)
	Open a database.

NuoDB_Status(*	openDatabaseEngine )(NuoDB_Connection connection, void nuoEngine, const char user, const char password, NuoDB_Options *options)
	Open a database with an NuoEngine.

NuoDB_Status(*	ping )(NuoDB_Connection *connection)
	Send a ping message to the server.

NuoDB_Status(*	rollback )(NuoDB_Connection *connection)
	Roll back any outstanding SQL statements.

NuoDB_Status(*	setAutoCommit )(NuoDB_Connection *connection, nuodb_bool_t autoCommit)
	Specify if statements related to this NuoDB_Connection should be auto-committed.

NuoDB_Status(*	setConverter )(NuoDB_Connection connection, const char encoding)
	Specify a non-default encoding for this client NuoDB_Connection.

NuoDB_Status(*	setDefaultConverter )(NuoDB_Connection connection, const char encoding)
	Specify a non-default encoding for this client NuoDB_Connection and set it as the default for the connection.

NuoDB_Status(*	setReadOnly )(NuoDB_Connection *connection, nuodb_bool_t readOnly)
	Puts this NuoDB_Connection in read-only mode as a hint to enable database optimizations.

NuoDB_Status(*	setTransactionIsolation )(NuoDB_Connection *connection, NuoDB_TransactionIsolationLevel level)
	Change the transaction isolation level for this NuoDB_Connection data structure to the one specified.

Detailed Description

NuoDB Database Connection.

NuoDB_Connection is a data structure that represents a connection to a NuoDB Database. Clients should call the NuoDB_Connection_create() function to create this data structure and then call the openDatabase() function to open a connection to a NuoDB database. Clients should call the NuoDB_Connection_free() function to release the NuoDB_Connection when the client application no longer needs the connection.

Field Documentation

◆ commit

NuoDB_Status(* NuoDB_Connection::commit) (NuoDB_Connection *connection)

Commit any outstanding SQL statements.

Makes all changes made since the previous commit/rollback permanent and releases any database locks currently held by this NuoDB_Connection data structure. This function should be used only when auto-commit mode has been disabled.

Parameters

[in] connection a pointer to the current (this) NuoDB_Connection data structure.

Returns: Enumerated integer NuoDB_Status. NUODB_SUCCESS (integer 0) on success, or a negative integer on failure.

◆ convertUtf8ToLocal

char *(* NuoDB_Connection::convertUtf8ToLocal) (NuoDB_Connection *connection, const char *s, size_t sLen)

Convert the given, presumably UTF-8 string, to the local encoding using the NuoDB_Connection's active encoding.

See: NuoDB_Connection::getActiveEncoding().

Parameters

[in]	connection	a pointer to the current (this) NuoDB_Connection data structure.
[in]	s	a pointer to the string.
[in]	sLen	length of the string.

Returns: a pointer to the converted string or NULL if there was an error. The client must call NuoDB_Connection_freeLocal() with this pointer.

◆ getActiveEncoding

const char *(* NuoDB_Connection::getActiveEncoding) (NuoDB_Connection *connection)

Return the name of the active encoding for this NuoDB_connection which may not be the same as the default encoding for this NuoDB_Connection.

Parameters

[in] connection a pointer to the current (this) NuoDB_Connection data structure.

Returns: a string that contains the name of the active encoding.

◆ getAutoCommit

NuoDB_Status(* NuoDB_Connection::getAutoCommit) (NuoDB_Connection *connection, nuodb_bool_t *autoCommit)

Determine if the NuoDB_Connection has the auto-commit flag set.

Parameters

[in]	connection	a pointer to the current (this) NuoDB_Connection data structure.
[out]	autoCommit	pointer to nuodb_bool_t to set auto-commit value.

Returns: Enumerated integer NuoDB_Status. NUODB_SUCCESS (integer 0) on success, or a negative integer on failure.

◆ getConnectionURL

const char *(* NuoDB_Connection::getConnectionURL) (NuoDB_Connection *connection)

Returns the connection URL string.

Parameters

[in] connection a pointer to the current (this) NuoDB_Connection data structure.

Returns: a pointer to the connection string.

◆ getConnectionVersion

int(* NuoDB_Connection::getConnectionVersion) (NuoDB_Connection *connection)

Returns the connection version.

Parameters

[in] connection a pointer to the current (this) NuoDB_Connection data structure.

Returns: the connection version

◆ getDefaultEncoding

const char *(* NuoDB_Connection::getDefaultEncoding) (NuoDB_Connection *connection)

Return the name of the default encoding for this NuoDB_Connection.

Parameters

[in] connection a pointer to the current (this) NuoDB_Connection data structure.

Returns: the name of the default encoding

◆ getEngineHandle

NuoDB_EngineHandle *(* NuoDB_Connection::getEngineHandle) (NuoDB_Connection *connection)

Get a handle to the NuoDB Engine.

Return the NuoDBEngine handle, or NULL if not available.

Parameters

[in] connection a pointer to the current (this) NuoDB_Connection data structure.

Returns: pointer to handle on success, NULL on fialure

◆ getMetaData

NuoDB_DatabaseMetaData *(* NuoDB_Connection::getMetaData) (NuoDB_Connection *connection)

Retrieve metadata for the database associated to this NuoDB_Connection.

The metadata includes information about the database's tables, its supported SQL grammar, its stored procedures, the capabilities of this NuoDB_Connection, and so on.

The NuoDB_Connection functions manage the memory allocated in the DatabaseMetaData data structure and the caller does not have to do so.

Parameters

[in] connection a pointer to the current (this) NuoDB_Connection data structure.

Returns: pointer to a NuoDB_DatabaseMetaData data structure or NULL on error.

◆ getNextSequenceValue

NuoDB_Status(* NuoDB_Connection::getNextSequenceValue) (NuoDB_Connection *connection, const char *schema, const char *sequenceName, int64_t *sequence)

Returns next sequence value.

Parameters

[in]	connection	a pointer to the current (this) NuoDB_Connection data structure.
[in]	schema	a pointer to a char for database schema
[in]	sequenceName	a pointer to a char for sequence name
[out]	sequence	a pointer to a int64_t for retrieved sequence value

Returns: Enumerated integer NuoDB_Status. NUODB_SUCCESS (integer 0) on success, or a negative integer on failure.

◆ getSchema

NuoDB_Status(* NuoDB_Connection::getSchema) (NuoDB_Connection *connection, char **schemaName, size_t *length)

Retrieves this connection's current schema name.

Parameters

[in]	connection	a pointer to the connection to get the current schema for
[out]	schemaName	on return contains the schema name
[out]	length	on return contains the length (in bytes) of the schema name

Remarks: the pointer placed in the schemaName argument is valid until the next invocation of getSchema or until the connection is closed

Returns: Enumerated integer NuoDB_Status. NUODB_SUCCESS (integer 0) on success, or a negative integer on failure.

◆ getTransactionIsolation

NuoDB_Status(* NuoDB_Connection::getTransactionIsolation) (NuoDB_Connection *connection, NuoDB_TransactionIsolationLevel *isolationLevel)

Retrieves this NuoDB_Connection data structure's current transaction isolation level.

The transction isolation level will be one of:

NUODB_TXN_ISOLATION_WRITE_COMMITTED = 5
NUODB_TXN_ISOLATION_READ_COMMITTED = 2
NUODB_TXN_ISOLATION_CONSISTENT_READ = 7
NUODB_TXN_ISOLATION_SERIALIZABLE = 8

Parameters

[in]	connection	a pointer to the current (this) NuoDB_Connection data structure.
[out]	isolationLevel	a pointer to a NuoDB_TransactionIsolationLevel.

Returns: Enumerated integer NuoDB_Status. NUODB_SUCCESS (integer 0) on success, or a negative integer on failure.

◆ isConnected

nuodb_bool_t(* NuoDB_Connection::isConnected) (NuoDB_Connection *connection)

Determine if the client has a valid connection to a NuoDB TE.

Parameters

[in] connection a pointer to the current (this) NuoDB_Connection data structure.

Returns: true if the socket which communicates to the server exists and is open.

◆ isReadOnly

nuodb_bool_t(* NuoDB_Connection::isReadOnly) (NuoDB_Connection *connection)

Retrieves whether this NuoDB_Connection data structure is in read-only mode.

Parameters

[in] connection a pointer to the current (this) NuoDB_Connection data structure.

Returns: true if the database is read-only, otherwise returns false.

◆ isUtf8

nuodb_bool_t(* NuoDB_Connection::isUtf8) (NuoDB_Connection *connection)

Retrieves whether this NuoDB_Connection data structure is using UTF-8 strings.

Parameters

[in] connection a pointer to the current (this) NuoDB_Connection data structure.

Returns: returns true if the NuoDB_Connection is using UTF-8 strings. Otherwise returns false.

◆ openDatabase

NuoDB_Status(* NuoDB_Connection::openDatabase) (NuoDB_Connection *connection, const char *dbname, const char *user, const char *password, NuoDB_Options *options)

Open a database.

Given an already existing NuoDB_Connection data structure, clients must call this function to open a database.

Parameters

[in]	connection	a pointer to the current (this) NuoDB_Connection data structure.
[in]	dbname	a pointer to a const char string representing the database name.
[in]	user	a pointer to a const char string that contains the database username.
[in]	password	a pointer to a const char string that contains the database password.
[in]	options	a pointer to optional NuoDB_Options. If no specific options are needed, the caller can pass a NULL.

Returns: Enumerated integer NuoDB_Status. NUODB_SUCCESS (integer 0) on success, or a negative integer on failure.

◆ openDatabaseEngine

NuoDB_Status(* NuoDB_Connection::openDatabaseEngine) (NuoDB_Connection *connection, void *nuoEngine, const char *user, const char *password, NuoDB_Options *options)

Open a database with an NuoEngine.

Given an already existing NuoDB_Connection data structure, clients may call this to open a database.

Parameters

[in]	connection	a pointer to the current (this) NuoDB_Connection data structure.
[in]	nuoEngine	a pointer to an NuoEngine.
[in]	user	a pointer to a const char string that contains the database username.
[in]	password	a pointer to a const char string that contains the database password.
[in]	options	a pointer to optional NuoDB_Options. If no specific options are needed, the caller can pass a NULL.

Returns: Enumerated integer NuoDB_Status. NUODB_SUCCESS (integer 0) on success, or a negative integer on failure.

◆ ping

NuoDB_Status(* NuoDB_Connection::ping) (NuoDB_Connection *connection)

Send a ping message to the server.

If no error occurs, the server is alive.

Parameters

[in] connection a pointer to the current (this) NuoDB_Connection data structure.

Returns: Enumerated integer NuoDB_Status. NUODB_SUCCESS (integer 0) on success, or a negative integer on failure.

◆ rollback

NuoDB_Status(* NuoDB_Connection::rollback) (NuoDB_Connection *connection)

Roll back any outstanding SQL statements.

Undoes all changes made in the current transaction and releases any database locks currently held by this NuoDB_Connection data structure. This function should be used only when auto-commit mode has been disabled.

Parameters

[in] connection a pointer to the current (this) NuoDB_Connection data structure.

Returns: Enumerated integer NuoDB_Status. NUODB_SUCCESS (integer 0) on success, or a negative integer on failure.

◆ setAutoCommit

NuoDB_Status(* NuoDB_Connection::setAutoCommit) (NuoDB_Connection *connection, nuodb_bool_t autoCommit)

Specify if statements related to this NuoDB_Connection should be auto-committed.

If a NuoDB_Connection is in auto-commit mode, then all its SQL statements will be executed and committed as individual transactions. Otherwise, its SQL statements are grouped into transactions that are terminated by a call to either the function commit() or the function rollback(). By default, new NuoDB_Connections are in auto-commit mode.

Parameters

[in]	autoCommit	If true, set autoCommit on and if false, turn autoCommit off
[in]	connection	a pointer to the current (this) NuoDB_Connection data structure.

Returns: Enumerated integer NuoDB_Status. NUODB_SUCCESS (integer 0) on success, or a negative integer on failure.

◆ setConverter

NuoDB_Status(* NuoDB_Connection::setConverter) (NuoDB_Connection *connection, const char *encoding)

Specify a non-default encoding for this client NuoDB_Connection.

NuoDB uses ICU (International Components for Unicode) for converting strings from the local client environment to UTF-8. NuoDB Transaction Engines require all strings to be UTF-8. setConverter() allows you to specify a non-default character set table (encoding) that is being used by the client. This may have options appended to the string. IANA alias character set names, IBM CCSIDs starting with "ibm-", Windows codepage numbers starting with "windows-" are frequently ' used for this parameter. See ICU ucnv_open() for more information.

Parameters

[in]	connection	a pointer to the current (this) NuoDB_Connection data structure.
[in]	encoding	ICU name of a non-default character set table. If this parameter is NULL, the default converter will be used.

Returns: Enumerated integer NuoDB_Status. NUODB_SUCCESS (integer 0) on success, or a negative integer on failure.

◆ setDefaultConverter

NuoDB_Status(* NuoDB_Connection::setDefaultConverter) (NuoDB_Connection *connection, const char *encoding)

Specify a non-default encoding for this client NuoDB_Connection and set it as the default for the connection.

NuoDB uses ICU (International Components for Unicode) for converting strings from the local client environment to UTF-8. NuoDB Transaction Engines require all strings to be UTF-8. setDefaultConverter() allows you to specify a non-default character set table (encoding) that is being used by the client. This may have options appended to the string. IANA alias character set names, IBM CCSIDs starting with "ibm-", Windows codepage numbers starting with "windows-" are frequently used for this parameter. See ICU ucnv_open() for more information.

setDefaultConverter() will set the NuoDB_Connections default converter to that for the given encoding. Future calls to getDefaultEncoding() will return this new default encoding.

Parameters

[in]	connection	a pointer to the current (this) NuoDB_Connection data structure.
[in]	encoding	ICU name of a non-default character set table. If this parameter is NULL, the default converter will be used.

Returns: Enumerated integer NuoDB_Status. NUODB_SUCCESS (integer 0) on success, or a negative integer on failure.

◆ setReadOnly

NuoDB_Status(* NuoDB_Connection::setReadOnly) (NuoDB_Connection *connection, nuodb_bool_t readOnly)

Puts this NuoDB_Connection in read-only mode as a hint to enable database optimizations.

Parameters

[in]	connection	a pointer to the current (this) NuoDB_Connection data structure.
[in]	readOnly	a boolean that indicates the read-only mode.

Returns: Enumerated integer NuoDB_Status. NUODB_SUCCESS (integer 0) on success, or a negative integer on failure.

◆ setTransactionIsolation

NuoDB_Status(* NuoDB_Connection::setTransactionIsolation) (NuoDB_Connection *connection, NuoDB_TransactionIsolationLevel level)

Change the transaction isolation level for this NuoDB_Connection data structure to the one specified.

Valid transaction isolation levels are:

NUODB_TXN_ISOLATION_WRITE_COMMITTED = 5
NUODB_TXN_ISOLATION_READ_COMMITTED = 2
NUODB_TXN_ISOLATION_CONSISTENT_READ = 7
NUODB_TXN_ISOLATION_SERIALIZABLE = 8

Parameters

[in] connection a pointer to the current (this) NuoDB_Connection data structure.

Returns: Enumerated integer NuoDB_Status. NUODB_SUCCESS (integer 0) on success, or a negative integer on failure.

The documentation for this struct was generated from the following file:

/data/builds/RELEASE-DB17-LIN/CDriver/nuodb/connection.h

Data Fields

Detailed Description

Field Documentation

◆ commit

◆ convertUtf8ToLocal

◆ getActiveEncoding

◆ getAutoCommit

◆ getConnectionURL

◆ getConnectionVersion

◆ getDefaultEncoding

◆ getEngineHandle

◆ getMetaData

◆ getNextSequenceValue

◆ getSchema

◆ getTransactionIsolation

◆ isConnected

◆ isReadOnly

◆ isUtf8

◆ openDatabase

◆ openDatabaseEngine

◆ ping

◆ rollback

◆ setAutoCommit

◆ setConverter

◆ setDefaultConverter

◆ setReadOnly

◆ setTransactionIsolation