Main Page | Namespace List | Class Hierarchy | Alphabetical List | Class List | File List | Namespace Members | Class Members | File Members | Related Pages
SQLDBC::SQLDBC_Connection

SQLDBC::SQLDBC_Connection Class Reference

Inheritance diagram for SQLDBC::SQLDBC_Connection:

SQLDBC::SQLDBC_ConnectionItem List of all members.

Detailed Description

Connection to the database kernel.

This class combines the functions necesary for managing a connection to the database. If a new connection object is created, it is not connected. The connection to the database is established when a successful connect() call was performed.

Todo:
Check more parameters after connection (version).
Todo:
Distribute the results of a COMMIT or ROLLBACK statment into dependent objects (for correct handling of PUTVAL commands).

Definition at line 3359 of file SQLDBC.h.

Public Member Functions

Member Function Documentation

SQLDBC_Retcode SQLDBC::SQLDBC_Connection::cancel (   ) 
 

Cancels the running database request that is executed on the connection.

For cancellation of a running SQL statement it is neccessary to call the cancel method asynchronously. Because of the asynchronous processing it is not guaranteed that the cancellation will be succeed. The returncode of the original function indicates whether the function completed or was cancelled. In case of cancelation the original function returns with the sql code -102 'SQL statement cancelled'. The the cancel methode returns with SQLDBC_OK if it has been send the cancel request to the database.

Returns:
SQLDBC_OK When the request to cancel the database session was sent, SQLDBC_NO_DATA_FOUND if there was no database session to be cancelled.
Note:
This is an UTF8 string.

void SQLDBC::SQLDBC_ConnectionItem::clearError (   )  [inherited]
 

Deletes the error has been stored.

void SQLDBC::SQLDBC_ConnectionItem::clearWarnings (   )  [inherited]
 

Deletes the warning stored in the SQLWarning object.

SQLDBC_Retcode SQLDBC::SQLDBC_Connection::close (   ) 
 

Closes the SQLDBC_Connection.

Releases the database and interface runtime resources immediately instead of waiting for them to be released by the destructor. The current transaction is rolled back.

After you called this method, you are able to connect again using one of the connect methods.

Returns:
SQLDBC_OK When the resources are released. SQLDBC_NOT_OK if there was an error occured.

SQLDBC_Retcode SQLDBC::SQLDBC_Connection::commit (   ) 
 

Commits all changes to the database session.

All changes made since the previous COMMIT/ROLLBACK statement are stored, any database locks held by this SQLDBC_Connection object are released.

Returns:
SQLDBC_OK if the COMMIT statement was successfull, SQLDBC_NOT_OK if the COMMIT statment failed, because of an error or timeout.

SQLDBC_Retcode SQLDBC::SQLDBC_Connection::commitWorkRelease (   ) 
 

Closes the SQLDBC_Connection.

Releases the database and interface runtime resources immediately instead of waiting for them to be released by the destructor. The current transaction is committed.

Returns:
SQLDBC_OK When the resources are released and the transaction is committed. SQLDBC_NOT_OK if there was an error occured.
After you called this method, you are able to connect again using one of the connect methods.

SQLDBC_Retcode SQLDBC::SQLDBC_Connection::connect (  const SQLDBC_ConnectProperties &  properties  ) 
 

Opens a new database session using the runtime abstraction interface.

This method attaches the connection object an existing session. It is recommended that you implement the virtual method getSession and releaseSession in the Runtime Abstraction Interface.

Parameters:
properties Connection properties.
Returns:
SQLDBC_OK if the connection to the database was established, SQLDBC_NOT_OK if the connection failed. In this case an error is set on this SQLDBC_Connection object.

SQLDBC_Retcode SQLDBC::SQLDBC_Connection::connect (   ) 
 

Opens a new database session using the runtime abstraction interface.

This method attaches the connection object an existing session. It is recommended that you implement the virtual method getSession and releaseSession in the Runtime Abstraction Interface.

Returns:
SQLDBC_OK if the connection to the database was established, SQLDBC_NOT_OK if the connection failed. In this case an error is set on this SQLDBC_Connection object.

SQLDBC_Retcode SQLDBC::SQLDBC_Connection::connect (  const char *  servernode,
const char *  serverdb,
const char *  username,
const char *  password,
const SQLDBC_ConnectProperties &  properties
) 
 

Opens a new database session using the SQLDBC_ConnectProperties object.

This method interprets all character arguments as zero-terminated ASCII strings.

Parameters:
servernode The zero-terminated name of the database server (ASCII).
serverdb The zero-terminated name of the database instance (ASCII).
username The zero-terminated name of the database user (ASCII).
password The zero-terminated password of the database user (ASCII).
properties Further connection properties.
Returns:
SQLDBC_OK if the connection to the database was established, SQLDBC_NOT_OK if the connection failed. In this case an error is set on this SQLDBC_Connection object.

SQLDBC_Retcode SQLDBC::SQLDBC_Connection::connect (  const char *  servernode,
const char *  serverdb,
const char *  username,
const char *  password,
const SQLDBC_StringEncoding  userpwdEncoding,
const SQLDBC_ConnectProperties &  properties
) 
 

Opens a new database session using the SQLDBC_ConnectProperties object.

This method interpres all character arguments as zero-terminated ASCII strings. User name and password must be in userpwdEncoding code.

Parameters:
servernode The zero-terminated name of the database server (ASCII).
serverdb The zero-terminated name of the database instance (ASCII).
username The zero-terminated name of the database user. The encoding of this string depends on the userpwdEncoding argument.
password The zero-terminated password of the database user. The encoding of this string depends on the userpwdEncoding argument.
userpwdEncoding The character encoding of the username/password combination.
properties Further connection properties.
Returns:
SQLDBC_OK if the connection to the database was established, SQLDBC_NOT_OK if the connection failed. In this case an error is set on this SQLDBC_Connection object.

SQLDBC_Retcode SQLDBC::SQLDBC_Connection::connect (  const char *  servernode,
SQLDBC_Length  servernodeLength,
const char *  serverdb,
SQLDBC_Length  serverdbLength,
const char *  username,
SQLDBC_Length  usernameLength,
const char *  password,
SQLDBC_Length  passwordLength,
const SQLDBC_StringEncoding  userpwdEncoding,
const SQLDBC_ConnectProperties &  properties
) 
 

Opens a new database session using the SQLDBC_ConnectProperties object.

For the connection options not specified, the following default values are used:

COMPNAME
"R ifr80"
APPLICATION
"ODB"
APPVERSION
"70404"
UNICODE
false
SQLMODE
INTERNAL
Parameters:
servernode The name of the database server (ASCII).
servernodeLength The length in bytes of the database server name.
serverdb The name of the database instance (ASCII).
serverdbLength The length in bytes of the database instance name.
username The name of the database user. The encoding of this string depends on the userpwdEncoding argument.
usernameLength The length in bytes of the database user name.
password The password of the database user. The encoding of this string depends on the userpwdEncoding argument.
passwordLength The length in bytes of the database users password.
userpwdEncoding The character encoding of the username/password combination.
properties Further connection properties.
Returns:
SQLDBC_OK if the connection to the database was established, SQLDBC_NOT_OK if the connection failed. In this case an error is set on this SQLDBC_Connection object.

SQLDBC_Retcode SQLDBC::SQLDBC_Connection::connect (  const char *  servernode,
const char *  serverdb,
const char *  username,
const char *  password
) 
 

Opens a new database session using the default values for the options.

The method accepts all character arguments as zero-terminated ASCII strings.

Parameters:
servernode The zero-terminated name of the database server (ASCII).
serverdb The zero-terminated name of the database instance (ASCII).
username The zero-terminated name of the database user (ASCII).
password The zero-terminated password of the database user (ASCII).
Returns:
SQLDBC_OK if the connection to the database was established, SQLDBC_NOT_OK if the connection failed. In this case an error is set on this SQLDBC_Connection object.

SQLDBC_Retcode SQLDBC::SQLDBC_Connection::connect (  const char *  servernode,
const char *  serverdb,
const char *  username,
const char *  password,
const SQLDBC_StringEncoding  userpwdEncoding
) 
 

Opens a new database session using the default values for the options.

This method interprets all character arguments as zero-terminated ASCII strings. User name and password must be in userpwdEncoding code.

Parameters:
servernode The zero-terminated name of the database server (ASCII).
serverdb The zero-terminated name of the database instance (ASCII).
username The zero-terminated name of the database user. The encoding of this string depends on the userpwdEncoding argument.
password The zero-terminated password of the database user. The encoding of this string depends on the userpwdEncoding argument.
userpwdEncoding The character encoding of the username/password combination.
Returns:
SQLDBC_OK if the connection to the database was established, SQLDBC_NOT_OK if the connection failed. In this case an error is set on this SQLDBC_Connection object.

SQLDBC_Retcode SQLDBC::SQLDBC_Connection::connect (  const char *  servernode,
SQLDBC_Length  servernodeLength,
const char *  serverdb,
SQLDBC_Length  serverdbLength,
const char *  username,
SQLDBC_Length  usernameLength,
const char *  password,
SQLDBC_Length  passwordLength,
const SQLDBC_StringEncoding  userpwdEncoding
) 
 

Opens a new database session using the default values for the options.

Parameters:
servernode The name of the database server (ASCII).
servernodeLength The length in bytes of the database server name.
serverdb The name of the database instance (ASCII).
serverdbLength The length in bytes of the database instance name.
username The name of the database user. The encoding of this string depends on the userpwdEncoding argument.
usernameLength The length in bytes of the database user name.
password The password of the database user. The encoding of this string depends on the userpwdEncoding argument.
passwordLength The length in bytes of the database users password.
userpwdEncoding The character encoding of the username/password combination.
Returns:
SQLDBC_OK if the connection to the database was established, SQLDBC_NOT_OK if the connection failed. In this case an error is set on this SQLDBC_Connection object.

SQLDBC_Retcode SQLDBC::SQLDBC_Connection::connect (  const char *  connectURL,
SQLDBC_Length  connectURLLength,
const char *  connectCommand,
SQLDBC_Length  connectCommandLength,
SQLDBC_StringEncoding  connectCommandEncoding,
SQLDBC_ConnectProperties &  connectProperties
) 
 

Opens a new database session using an explicit URL and a CONNECT statement.

This method should be used only for custom connections together with a custom implementation of the SQLDBC_IRuntime interface.

Parameters:
connectURL The connect URL, which may be 0.
connectURLLength The length of the connect URL, which may be SQLDBC_NTS to indicate a zero-terminated string.
connectCommand The CONNECT statement.
connectCommandLength The length of the CONNECT statement, which may be SQLDBC_NTS to indicate a zero-terminated string.
connectCommandEncoding The code of the connect statement.
connectProperties Connect properties. It is recommended that you set environmental options, such as SQL mode, component name and version, to correctly initialize the internal handling of the runtime, since neither the URL nor your CONNECT statement are parsed fetch these options.
Returns:
SQLDBC_OK if the connection to the database was established, SQLDBC_NOT_OK if the connection failed. In this case an error is set on this SQLDBC_Connection object.

SQLDBC_PreparedStatement* SQLDBC::SQLDBC_Connection::createPreparedStatement (   ) 
 

Creates an SQLDBC_PreparedStatement object for sending SQL statements to the database.

An SQLDBC_PreparedStatement object is 'prepared' in the database server and can use binding variables for input/output parameters.

Returns:
The SQLDBC_PreparedStatement object created by this method.
See also:
SQLDBC_PreparedStatement

SQLDBC_Statement* SQLDBC::SQLDBC_Connection::createStatement (   ) 
 

Creates an SQLDBC_Statement object for sending SQL statements to the database.

SQL statements without parameters are normally executed using SQLDBC_Statement objects. Applications executing SQL statements several times or binding parameters for input and/or output must use SQLDBC_PreparedStatement objects.

Returns:
The SQLDBC_Statement object created by this method.
See also:
SQLDBC_Statement

SQLDBC_Retcode SQLDBC::SQLDBC_Connection::disconnect (   ) 
 

Closes the SQLDBC_Connection.

Releases the database and interface runtime resources immediately instead of waiting for them to be released by the destructor. No SQL statement that handles the current transaction is sent to the database, so the transaction may be implicitely rolled back by the database server.

After you called this method, you are able to connect again using one of the connect methods.

Returns:
SQLDBC_OK When the resources are released. SQLDBC_NOT_OK if there was an error occured.

SQLDBC_ErrorHndl& SQLDBC::SQLDBC_ConnectionItem::error (   )  [inherited]
 

Returns a reference to the ErrorHndl object.

Note:
Applications should retrieve the content of the SQLDBC_ErrorHndl object immediatly since an new call to any SQLDBC function except the warning() method will empty SQLDBC_ErrorHndl object.
Returns:
An SQLDBC_ErrorHndl object.

SQLDBC_Bool SQLDBC::SQLDBC_Connection::getAutoCommit (   )  const
 

Returns whether the connection is in AUTCOMMIT mode.

Returns:
SQLDBC_TRUE if the connection is in AUTOCOMMIT mode or SQLDBC_FALSE if it is not.
See also:
setAutoCommit

SQLDBC_Retcode SQLDBC::SQLDBC_Connection::getConnectionFeatures (  SQLDBC_ConnectProperties &  properties  ) 
 

Retrieve active features of the connection.

This method retrieves the active connection features of the current connection. The active connection features are basically all (explicitely or implicitely) connect properties that have been set if the database kernel can fulfill them.

The method requires that a connection has been established before.

Parameters:
properties Connection properties to fill with current features.
Returns:
SQLDBC_OK if the properties can be retrieved. SQLDBC_NOT_OK if there is an error. In this case an error is set on this SQLDBC_Connection object.

SQLDBC_DateTimeFormat::Format SQLDBC::SQLDBC_Connection::getDateTimeFormat (   )  const
 

Returns the currently active date/time format.

Returns:
The date/time format. See SQLDBC_DateTimeFormat::Format

SQLDBC_Int4 SQLDBC::SQLDBC_Connection::getKernelVersion (   )  const
 

Returns the kernel version.

It will be returned in the following format: <major_release><minor_releaser><correction_level>

  • mayor_release (1 digit)
  • minor_release (2 digit)
  • correction_level (2 digits)
    Returns:
    The kernel version, which is a computed <major_release> * 10000 + <minor_release> * 100 + <correction_level>. Example: For version 7.4.04 version number 70404 is returned.

SQLDBC_Int4 SQLDBC::SQLDBC_Connection::getTransactionIsolation (   )  const
 

Returns the transaction isolation level.

Returns:
The isolation level (0, 1, 10, 15, 2, 20, 3, or 30). The lowest level is 0.
See also:
setTransactionIsolation

SQLDBC_Bool SQLDBC::SQLDBC_Connection::isConnected (   )  const
 

Returns whether if the connection to the database was established.

Returns:
SQLDBC_TRUE if the connection was established. It is not checked whether the connection timed out or the database server is still running.

SQLDBC_Bool SQLDBC::SQLDBC_Connection::isUnicodeDatabase (   )  const
 

Returns whether the database is an unicode database or not.

Returns:
SQLDBC_TRUE if the database is an unicode database.

void SQLDBC::SQLDBC_Connection::releaseStatement (  SQLDBC_PreparedStatement *  stmt  ) 
 

Releases an SQLDBC_PreparedStatement.

Parameters:
stmt A reference to an SQLDBC_PreparedStatement object to be released.

void SQLDBC::SQLDBC_Connection::releaseStatement (  SQLDBC_Statement *  stmt  ) 
 

Releases an SQLDBC_Statement.

Parameters:
stmt A reference to an SQLDBC_Statement object to be released.

SQLDBC_Retcode SQLDBC::SQLDBC_Connection::rollback (   ) 
 

Undoes all changes made in the current transaction and releases any database locks held by this connection object.

void SQLDBC::SQLDBC_Connection::setAutoCommit (  SQLDBC_Bool  autocommit  ) 
 

Sets the AUTOCOMMIT mode for the connection.

Parameters:
autocommit The value for AUTOCOMMIT mode.
See also:
getAutoCommit

void SQLDBC::SQLDBC_Connection::setSQLMode (  SQLDBC_SQLMode  sqlmode  ) 
 

Sets the SQL mode.

Parameters:
sqlmode The SQL mode to be used: SQLDBC_INTERNAL | SQLDBC_ANSI | SQLDBC_DB2 | SQLDBC_ORACLE
See also:
SQLDBC_ConnectProperties

SQLDBC_Retcode SQLDBC::SQLDBC_Connection::setTransactionIsolation (  SQLDBC_Int4  isolationlevel  ) 
 

Sets the transaction isolation level.

Parameters:
isolationlevel The isolation level to be used. Possible values for the isolation level are 0, 1, 10, 15, 2, 20, 3, or 30. The lowest level is 0.
Returns:
SQLDBC_OK if the isolation level was set, SQLDBC_NOT_OK if the isolation level was not set, In this case an error is set on this SQLDBC_Connection object.
See also:
getTransactionIsolation

SQLDBC_SQLWarning* SQLDBC::SQLDBC_ConnectionItem::warning (   )  [inherited]
 

Returns a reference to an SQLWarning object stored in the SQLDBC_ConnectionItem object.

Note:
Getting the reference to the SQLWarning object will not clear the ErrorHndl object. All other function calls will empty the ErrorHndl object.
Returns:
The SQLWarning object stored in the item.