This class handles the connection to the RDBMS. More...

#include <ildblink/ilddbms.h>

Inheritance diagram for IldDbms:

Public Member Functions
virtual	~IldDbms ()
	This virtual destructor is invoked when the current object is being destroyed. More...

virtual IldDbms &	autoCommitOff (IldRequest r=0, const char tN=0)=0
	Turn off autocommit mode if this mode is supported by the RDBMS. More...

virtual IldDbms &	autoCommitOn (IldRequest r=0, const char tN=0)=0
	Turn on autocommit mode if this mode is supported by the RDBMS. More...

virtual IldDbms &	cancel ()=0
	Interrupt the execution of any asynchronous request in process. More...

virtual IldDbms &	commit (IldRequest r=0, const char tN=0)=0
	Cause the RDBMS to validate the current transaction. More...

virtual IldDbms &	connect (const char *cString)=0
	Connects an application to a database server. More...

virtual IldDbms &	connect (const char database, const char userName, const char *password)=0
	Connects an application to a database server using a connection string split into its three components. More...

virtual IldDbms &	disconnect ()=0
	Closes the current connection. More...

virtual IldDbms &	execute (const char query, IlInt rowCount=0)=0
	Execute a query immediately. More...

virtual void	freeEntity (IldSchemaEntity *ent)=0
	Delete the given object. More...

virtual IldDbms &	freeNames (char names, char owners=0)=0
	Delete the arrays allocated in DB Link and deallocate the array contents. More...

virtual void	freeTypeInfo (const IldSQLType **types)=0
	Delete the given array. More...

virtual IldADTDescriptor *	getAbstractType (const char typeName, const char owner=0)=0
	Search, by name, the cache for an abstract data type descriptor. More...

virtual IldADTDescriptor *	getAbstractType (IlInt typeId)=0
	Search, by identifier, the cache for an abstract data type descriptor. More...

virtual const char *	getDatabase () const =0
	Find the name of the currently connected to database. More...

virtual const char *	getDbmsServer () const =0
	Find the server name. More...

virtual IlUInt	getDbmsVersion ()=0
	Find the server verion number. More...

virtual const char *	getDbmsVersions ()=0
	Finds the RDBMS versions. More...

virtual IlUInt	getDefaultColArraySize () const =0
	Get the default size of the fetch array. More...

virtual IlUInt	getDefaultParamArraySize () const =0
	Get the default parameter array size. More...

virtual IldErrorReporter *	getErrorReporter () const =0
	Get the default error reporter. More...

virtual IldRequest *	getFreeRequest ()=0
	Get a new request. More...

virtual IlAny	getHook () const =0
	Find the RDBMS API hook. More...

virtual IldDbms &	getInfo (IldInfoItem info, IlInt intVal, char charVal)=0
	Find a server information item value. More...

virtual const char *	getName () const =0
	Finds the database name. More...

virtual IlInt	getNumberOfActiveConnections () const =0
	Find how many connections exist. More...

virtual IlUInt	getNumberOfEntities ()=0
	Find the number of metadata entity descriptors (tables, views, procedures or functions, synonyms) in the cache of the current object. More...

virtual IlUInt	getNumberOfRequests () const =0
	Find the number of existing requests. More...

virtual IldCallable *	getProcedure (const char procName, const char owner=0)=0
	Search, by name, the cache for a procedure descriptor. More...

virtual IldCallable *	getProcedure (IlInt procId)=0
	Search, by identifier, the cache for a procedure descriptor. More...

virtual IldRelation *	getRelation (const char relName, const char owner=0)=0
	Search, by name, the cache for a relation descriptor. More...

virtual IldRelation *	getRelation (IlInt relId)=0
	Search, by identifier, the cache for a relation descriptor. More...

virtual IldSynonym *	getSynonym (const char synName, const char owner=0)=0
	Search, by name, the cache for a synonym descriptor. More...

virtual IldSynonym *	getSynonym (IlInt synId)=0
	Search, by identifier, the cache for a synonym descriptor. More...

virtual const IldSQLType **	getTypeInfo (short cTy=IldSQLAllTypes)=0
	Find one or all built-in datatype descriptors. More...

virtual const char *	getUser () const =0
	Finds the current user name. More...

virtual IlBoolean	isAsync () const =0
	Indicate whether the current connection is set to process queries in asynchronous mode. More...

virtual IlBoolean	isAsyncSupported () const =0
	Tell if the RDBMS supports asynchronous processing. More...

virtual IlBoolean	isCompleted () const =0
	Indicates whether the request currently being executed has been completed. More...

virtual IlBoolean	isConnected () const =0
	Find if the connection is established. More...

virtual IlBoolean	isReadOnlyCapable () const =0
	Tell if the server supports read-only cursors. More...

virtual IlBoolean	isScrollableCapable () const =0
	Tell if the server supports scrollable cursors. More...

virtual IlBoolean	isTransactionEnabled ()=0
	Tell if the connected to server is handling transactions. More...

virtual IlBoolean	isTransactionReadOnly () const =0
	Tell if the transaction read-only mode is active. More...

virtual IldADTDescriptor *	readAbstractType (const char typeName, const char owner=0)=0
	Access the database schema to build the descriptor of a user-defined type (or abstract data type). More...

virtual IldADTDescriptor *	readAbstractType (IlInt typeId)=0
	Access the database schema to build the descriptor of a user-defined data type. More...

virtual char **	readAbstractTypeNames (const char *owner=0)=0
	Find the names of user-defined data types in the current database. More...

virtual IldRequest *	readEntityNames (IldEntityType entType, const char *owner=0)=0
	Query the database for the names and owners of all schema entities of a given type. More...

virtual IldDbms &	readForeignKeys (IldRelation *rel)=0
	Build the descriptor of the relation foreign keys. More...

virtual IldDbms &	readIndexes (IldRelation *rel)=0
	Build the descriptor of the relation indexes. More...

virtual char **	readOwners ()=0
	Find the names of all owner of any entity in the database. More...

virtual IldDbms &	readPrimaryKey (IldRelation *rel)=0
	Build the descriptor of the relation primary key. More...

virtual IldCallable *	readProcedure (const char procName, const char owner=0)=0
	Access the database schema to build the descriptor of a procedure or function. More...

virtual IldCallable *	readProcedure (IlInt procId)=0
	Access the database schema to build the descriptor of a procedure or function. More...

virtual char **	readProcedureNames (const char *owner=0)=0
	Find the names of the procedures or functions in the current database. More...

virtual IldRelation *	readRelation (const char relName, const char owner=0)=0
	Access the database schema to build the descriptor of a table or view. More...

virtual IldRelation *	readRelation (IlInt relId)=0
	Access the database schema to build the descriptor of a table or view. More...

virtual char **	readRelationNames (char **&owners)=0
	Read all the names and owners of all the tables and views from the database. More...

virtual char **	readRelationNames (const char *owner=0)=0
	Find the names of the relations in the current database. More...

virtual char **	readRelationOwners (const char *rN=0)=0
	Retrieves the list of relation owners. More...

virtual IldDbms &	readSpecialColumns (IldRelation *rel)=0
	Build the descriptor of the relation special columns. More...

virtual IldSynonym *	readSynonym (const char synName, const char own=0)=0
	Access the database schema to build the descriptor of a synonym. More...

virtual IldSynonym *	readSynonym (IlInt synId)=0
	Access the database schema to build the descriptor of a synonym. More...

virtual char **	readSynonymNames (const char *owner=0)=0
	Find the names of the synonyms in the current database. More...

virtual IldRequest *	readTablePrivileges (const char catalog, const char schema, const char *table)=0
	Query the database for the privileges established on a given table. More...

virtual void	removeEntity (IldSchemaEntity *ent)=0
	Remove an entity descriptor from the current object cache. More...

virtual void	removeRelation (IldRelation *rel)=0
	Remove a relation descriptor obejct from the cache. More...

virtual IldDbms &	rollback (IldRequest r=0, const char tN=0)=0
	Cause the RDBMS to undo what had been processed since the begining of the current transaction. More...

virtual IldDbms &	setAsync (IlBoolean flag)=0
	Change the asynchronous processing mode. More...

virtual IldDbms &	setDefaultColArraySize (IlUInt size)=0
	Set the default size of the fetch array of requests. More...

virtual IldDbms &	setDefaultParamArraySize (IlUInt size)=0
	Set the default parameter array size. More...

virtual IldDbms &	setErrorReporter (IldErrorReporter *r)=0
	Set the default user error reporter. More...

virtual IldDbms &	setHook (IlAny hook)=0
	Establish a hook into the RDBMS. More...

virtual IldDbms &	setTimeOut (short secs)=0
	Set the time-out period for long executing queries. More...

virtual IldDbms &	setTransactionReadOnly (IlBoolean f=IlTrue)=0
	Activates or deactivates transactions read-only mode. More...

virtual IldDbms &	startTransaction (IldRequest r=0, const char tN=0)=0
	Open a transaction. More...

virtual IldDbms &	subscribeEvent (const char *name, IldNotifFunction usrCB, IlAny usrData)=0
	Register the application to receive a notification. More...

virtual IldDbms &	unSubscribeEvent (const char *name)=0
	Unsubscribe from the given event. More...

Public Member Functions inherited from IldIldBase
virtual	~IldIldBase ()
	Destructor for the base class of DB Link session and cursor classes. More...

void	clearDiagnostics ()
	Set diagnostic flags to false. More...

virtual const IldDiagnostic *	getError () const =0
	Get the error container. More...

virtual IlInt	getErrorCode () const =0
	Get the error code. More...

virtual const char *	getErrorConnection () const =0
	Get the conneciton string. More...

virtual const char *	getErrorMessage () const =0
	Get the error message text. More...

virtual const char *	getErrorName () const =0
	Get the error object name. More...

virtual IldErrorOrigin	getErrorOrigin () const =0
	Get the error origin. More...

virtual const char *	getErrorSqlstate () const =0
	Get the SQL state. More...

virtual const IldDiagnostic *	getInformation () const =0
	Get the information container. More...

virtual IlInt	getInformationCode () const =0
	Get the information code. More...

virtual const char *	getInformationMessage () const =0
	Get the information message. More...

virtual IlBoolean	isErrorRaised () const =0
	Tell if an error was raised. More...

virtual IlBoolean	isInformationRaised () const =0
	Tell if a warning was raised. More...

virtual int	operator! () const =0
	Tell if an error was raised. More...

virtual void	setError (IldDiagnostic *diag)=0
	Set the diagnostic container provided as the error container. More...

virtual void	setInformation (IldDiagnostic *diag)=0
	Set the diagnostic container provided as the warning container. More...

virtual void	setNumericUse (IlBoolean flag)=0
	Turn the numeric-as-objects feature ON or OFF. More...

virtual void	setStringDateUse (IlBoolean flag=IlTrue)=0
	Turn the date-as-string feature ON or OFF. More...

virtual void	setStringNumericUse (IlBoolean flag=IlTrue)=0
	Turn the number-as-string feature ON or OFF. More...

virtual IlBoolean	useNumeric () const =0
	Tell if numeric data is handled as objects. More...

virtual IlBoolean	useStringDate () const =0
	Tell if date values will be sent and retrieved as strings. More...

virtual IlBoolean	useStringNumeric () const =0
	Tell if numeric are handled as strings. More...

Detailed Description

This class handles the connection to the RDBMS.

Library: dbkernel

It contains the declaration of all the operations that can be applied to the IldDbms class of objects. But you cannot directly allocate an object of the IldDbms class. You always manipulate objects that are instances of classes derived from the IldDbms class. Those instances may be created in two ways:

Using the function IldAllocConnect,
Using the constructor of the IldDbmsModel class. This class provides a constructor, and thus new classes can be derived from it. Most of its functionalities are the same as those of the IldDbms class. The few differences are documented in the IldDbmsModel class.

Note: The inline function IldNewDbms, which takes the same arguments as the IldAllocConnect function, is deprecated but was kept for compatibility. Its use should be avoided.

As a class, IldDbms provides the functional interface that lets you:

Connect to and disconnect from an RDBMS.
Create request objects to execute SQL queries.
Manage transactions in RDBMSs.
Read and use the schema (or data dictionary) in a database.
Recover from errors.

The maximum number of IldDbms objects that can be created during one session is equal to the maximum number of simultaneous connections authorized by the RDBMS.

An IldDbms instance makes it possible to instantiate the IldRequest and schema entity descriptor classes. It does cache these objects, allowing cursor pooling and the fast retrieval of descriptors. When your application destroys one of these instances, the IldDbms object involved is notified about the destruction. When the IldDbms object itself is destroyed, all remaining IldRequest and registered schema-entity descriptor objects are also destroyed at the same time.

See also: IldADTDescriptor, IldCallable, IldDbmsModel, IldInfoItem, IldRelation, IldRequest, IldSQLType, IldSynonym, "Connection String Format" and "Erroneous IldDbms and IldRequest Objects" in the Rogue Wave DB Link User's Manual.

Constructor & Destructor Documentation

◆ ~IldDbms()

virtual IldDbms::~IldDbms ( )

virtual

This virtual destructor is invoked when the current object is being destroyed.

The destructor frees (that is, deallocates) all the IldRequest objects and registered schema entity descriptor objects associated with the IldDbms object being destroyed. It also closes the connection if the current object is connected to a database. If there are IldErrorReporter objects referenced by the current object, this destructor also frees these objects if these references are the only references to the IldErrorReporter objects.

Member Function Documentation

◆ autoCommitOff()

virtual IldDbms& IldDbms::autoCommitOff	(	IldRequest *	r = `0`,
		const char *	tN = `0`
	)

pure virtual

Turn off autocommit mode if this mode is supported by the RDBMS.

Parameters

r	Optionally, the request object.
tN	Optionally, the transaction name.

Returns: The current object by reference.

The behavior of this member function changes depending on the RDBMS features:

If autocommit mode is supported, this member function turns off the autocommit mode for the session.
If not, this member function ignores the parameters, and does nothing.

This member function can raise the following errors:

ILD_DBMS_NOT_CONNECTED
ILD_REQUEST_REQUIRED
Any error detected by the RDBMS itself.

Implemented in IldDbmsModel.

◆ autoCommitOn()

virtual IldDbms& IldDbms::autoCommitOn	(	IldRequest *	r = `0`,
		const char *	tN = `0`
	)

pure virtual

Turn on autocommit mode if this mode is supported by the RDBMS.

Parameters

r	Optionally, the request object.
tN	Optionally, the transaction name.

Returns: The current object by reference.

The behavior of this member function changes depending on the RDBMS features:

If autocommit mode is supported, this member function turns on the autocommit mode.
If not supported, this member function ignores the parameters, and does nothing.

This member function can raise the following errors:

ILD_DBMS_NOT_CONNECTED
ILD_REQUEST_REQUIRED
Any error detected by the RDBMS itself.

Implemented in IldDbmsModel.

◆ cancel()

virtual IldDbms& IldDbms::cancel ( )

pure virtual

Interrupt the execution of any asynchronous request in process.

Returns: The current object by reference.

This member function does nothing for any RDBMS other than DB2, MS SQL Server, ODBC, Oledb and Oracle.

Implemented in IldDbmsModel.

◆ commit()

virtual IldDbms& IldDbms::commit	(	IldRequest *	r = `0`,
		const char *	tN = `0`
	)

pure virtual

Cause the RDBMS to validate the current transaction.

Parameters

r	Optionally, the request object.
tN	Optionally, the transaction name.

Returns: The current object by reference.

This member function can raise the following errors:

ILD_DBMS_NOT_CONNECTED
ILD_REQUEST_REQUIRED
ILD_INVALID_SEQUENCE
Any error detected by the RDBMS itself.

Implemented in IldDbmsModel.

◆ connect() [1/2]

virtual IldDbms& IldDbms::connect ( const char * cString )

pure virtual

Connects an application to a database server.

Parameters

cString The connection string.

Returns: The current object by reference.

The argument format is the same as those for the matching IldAllocConnect function.

This member function connects your application using the authentication supplied by the connection string parameter cString and returns the current object by reference.

Usually, one IldDbms object is connected to one database controlled by only one RDBMS. However, during a session, such an object may be disconnected from and reconnected to a different database in the same RDBMS.

This member function can raise the following errors:

ILD_ALREADY_CONNECTED
ILD_BAD_DB_SPEC
ILD_DBMS_FATAL_ERROR
ILD_MEMORY_EXHAUSTED
Any error detected by the RDBMS itself.

Implemented in IldDbmsModel.

◆ connect() [2/2]

virtual IldDbms& IldDbms::connect	(	const char *	database,
		const char *	userName,
		const char *	password
	)

pure virtual

Connects an application to a database server using a connection string split into its three components.

Parameters

database	The connection string to the RDBMS.
userName	The user name.
password	The user password.

Returns: The current object by reference.

The password is not kept once the connection is established. The database argument format is the same as those for the matching IldAllocConnect function.

This member function can raise the following errors:

ILD_ALREADY_CONNECTED
ILD_BAD_DB_SPEC
ILD_DBMS_FATAL_ERROR
ILD_MEMORY_EXHAUSTED
Any error detected by the RDBMS itself.

Implemented in IldDbmsModel.

◆ disconnect()

virtual IldDbms& IldDbms::disconnect ( )

pure virtual

Closes the current connection.

Returns: The current object by reference.

In doing so, it frees (that is, deallocates) all the IldRequest objects and all the schema entity descriptor objects referenced by the current IldDbms object.

This member function can raise the following errors:

ILD_DBMS_NOT_CONNECTED
Any error detected by the RDBMS itself.

Implemented in IldDbmsModel.

◆ execute()

virtual IldDbms& IldDbms::execute	(	const char *	query,
		IlInt *	rowCount = `0`
	)

pure virtual

Execute a query immediately.

Parameters

query	The SQL stateemnt to execute.
rowCount	Optionally, to be filled on output with the number of modified rows.

Returns: The current object by reference.

This member function takes the SQL statement contained in query and submits it to the RDBMS. When the optional argument rowCount is provided, it indicates the number of rows affected by the SQL query. This information is useful especially if the query is of type insert, update, or delete.

This member function is not appropriate for SQL select statements because it cannot "fetch" data, nor can it be used for parameterized queries since the binding interface is not accessible. It is however the most appropriate for DDL (Data Definition Language) statements.

Any error detected by the RDBMS itself will be raised.

Implemented in IldDbmsModel.

◆ freeEntity()

virtual void IldDbms::freeEntity ( IldSchemaEntity * ent )

pure virtual

Delete the given object.

Parameters

ent	The schema entity descriptor to destroy.

This function must be used on PCs if the application is linked with the libraries in DLL mode. In such a case, simply deleting the object in the application code would lead to a run-time error. For portability reasons, this function must be used no matter what the target platform.

Implemented in IldDbmsModel.

◆ freeNames()

virtual IldDbms& IldDbms::freeNames	(	char **	names,
		char **	owners = `0`
	)

pure virtual

Delete the arrays allocated in DB Link and deallocate the array contents.

Parameters

names	An array of strgins to be deleted.
owners	Optionally, a second array of strings to be deleted.

Returns: The current object by reference.

This function must be used on PCs if the application is linked with the libraries in DLL mode. In this case, simply deleting the arrays in the application code will lead to a run-time error. For portability reasons, this function can be used on any target platform.

Implemented in IldDbmsModel.

◆ freeTypeInfo()

virtual void IldDbms::freeTypeInfo ( const IldSQLType ** types )

pure virtual

Delete the given array.

Parameters

types The array of type descriptors to destroy.

This member function must be used on PCs if the application is linked in DLL mode. In such a case, simply deleting the array in the application code would lead to a run-time error. For portability reasons, this function must be used no matter what the target platform.

Implemented in IldDbmsModel.

◆ getAbstractType() [1/2]

virtual IldADTDescriptor* IldDbms::getAbstractType	(	const char *	typeName,
		const char *	owner = `0`
	)

pure virtual

Search, by name, the cache for an abstract data type descriptor.

Parameters

typeName	The name of the type.
owner	Optionally, the types' owner name.

Returns: The type descriptor or a null pointer.

If no descriptor with such name is found in the cache of the current object, this member function queries the RDBMS with the arguments typeName and own, and returns the matching results.

Note: If an object is created, it is stored in the cache. Thus it must not be destroyed by the application.

This member function can raise the following errors:

ILD_DBMS_NOT_CONNECTED
ILD_MEMORY_EXHAUSTED
ILD_UNKNOWN_ENTITY
Any error detected by the RDBMS itself.

In case of error, this member function returns a null pointer.

Implemented in IldDbmsModel.

◆ getAbstractType() [2/2]

virtual IldADTDescriptor* IldDbms::getAbstractType ( IlInt typeId )

pure virtual

Search, by identifier, the cache for an abstract data type descriptor.

Parameters

typeId The type identifier.

Returns: The types' descriptor or a null pointer.

If no such descriptor is found in the cache of the current object, this member function queries the RDBMS with the argument typeId and returns the matching results.

Note: If an object is created, it is stored in the cache. Thus it must not be destroyed by the application.

This member function can raise the following errors:

ILD_DBMS_NOT_CONNECTED
ILD_MEMORY_EXHAUSTED
ILD_UNKNOWN_ENTITY
Any error detected by the RDBMS itself.

In case of error, this member function returns a null pointer.

Implemented in IldDbmsModel.

◆ getDatabase()

virtual const char* IldDbms::getDatabase ( ) const

pure virtual

Find the name of the currently connected to database.

Returns: The name of the current database.

Implemented in IldDbmsModel.

◆ getDbmsServer()

virtual const char* IldDbms::getDbmsServer ( ) const

pure virtual

Find the server name.

Returns: The name of the server to which this object is connected.

Note: This function is deprecated. Using IldDbms::getInfo(IldServerName) should be preferred.

Implemented in IldDbmsModel.

◆ getDbmsVersion()

virtual IlUInt IldDbms::getDbmsVersion ( )

pure virtual

Find the server verion number.

Returns: A number indicating the main version number of the RDBMS for which the current version of the DB Link library was tested.

The return value could look like this: 11 with Oracle, for example.

Implemented in IldDbmsModel.

◆ getDbmsVersions()

virtual const char* IldDbms::getDbmsVersions ( )

pure virtual

Finds the RDBMS versions.

Returns: A string that indicates the range of version numbers of the RDBMS for which the current version of the DB Link library was tested.

The return value could look like this: 9.2-11.1 with Oracle, for example.

Note: This function is deprecated. Using IldDbms::getInfo(IldDBMSVersion) should be preferred.

Implemented in IldDbmsModel.

◆ getDefaultColArraySize()

virtual IlUInt IldDbms::getDefaultColArraySize ( ) const

pure virtual

Get the default size of the fetch array.

Returns: The default number of rows per result set for all IldRequest objects created using the current connection.

Implemented in IldDbmsModel.

◆ getDefaultParamArraySize()

virtual IlUInt IldDbms::getDefaultParamArraySize ( ) const

pure virtual

Get the default parameter array size.

Returns: The default number of parameter rows that will be sent simultaneously by an IldRequest object using this connection.

Implemented in IldDbmsModel.

◆ getErrorReporter()

virtual IldErrorReporter* IldDbms::getErrorReporter ( ) const

pure virtual

Get the default error reporter.

Returns: The user-installed error reporter if there is one, or a null pointer if no error reporter has been set.

Implements IldIldBase.

Implemented in IldDbmsModel.

◆ getFreeRequest()

virtual IldRequest* IldDbms::getFreeRequest ( )

pure virtual

Get a new request.

Returns: A pointer to an IldRequest instance.

The object may be one that already exists and has been released, or it may be a new object.

This member function can raise the following errors:

ILD_DBMS_NOT_CONNECTED
ILD_MEMORY_EXHAUSTED
Any error detected by the RDBMS itself.

In case of error, this member function returns a null pointer or an error request object.

For more information on these return values, see the section "Erroneous IldDbms and IldRequest Objects" in the Rogue Wave DB Link User's Manual.

Implemented in IldDbmsModel.

◆ getHook()

virtual IlAny IldDbms::getHook ( ) const

pure virtual

Find the RDBMS API hook.

Returns: The hook into the RDBMS.

The structure of this hook depends on the RDBMS. As a consequence, you will have to apply an appropriate cast before using it.

See the section "Extending the IldDbms Class" in the Rogue Wave DB Link User's Manual.

Note: Do not alter the returned value. If it is modified, the behavior of DB Link would become unpredictable.

Implemented in IldDbmsModel.

◆ getInfo()

virtual IldDbms& IldDbms::getInfo	(	IldInfoItem	info,
		IlInt *	intVal,
		char *	charVal
	)

pure virtual

Find a server information item value.

Parameters

info	The information code.
intVal	On output, if relevant, will contain the integer value of the information item.
charVal	On output, if relevant, will contain the character value of the information item.

Returns: The current object by reference.

This member function returns the server information corresponding to the item defined by the code info to either intVal or charVal.

Note: The type of the returned value, depending on the info code used, can be found in the file ildblink/ildconst.h at the section Implementation information.

If an error is raised when retrieving the server information, intVal is set to -1 and charVal is set to the empty string (the first character is null). The valid values of retrievable information items are defined by the enumeration IldInfoItem.

The following errors can be raised:

ILD_DBMS_NOT_CONNECTED
Any error detected by the RDBMS itself.

Implemented in IldDbmsModel.

◆ getName()

virtual const char* IldDbms::getName ( ) const

pure virtual

Finds the database name.

Returns: The DB Link name of the current RDBMS.

The name is one of the following values:

"db2"
"db29x"
"informix9" or "informix"
"mysql"
"oledb"
"odbc"
"oracle10", "oracle11", or "oracle"
"sybase"

Note: The names "oracle10" and "oracle11" are deprecated.

Implemented in IldDbmsModel.

◆ getNumberOfActiveConnections()

virtual IlInt IldDbms::getNumberOfActiveConnections ( ) const

pure virtual

Find how many connections exist.

Returns: The number of connections established to the current RDBMS, that is, the number of IldDbms objects created for that specific RDBMS.

Implemented in IldDbmsModel.

◆ getNumberOfEntities()

virtual IlUInt IldDbms::getNumberOfEntities ( )

pure virtual

Find the number of metadata entity descriptors (tables, views, procedures or functions, synonyms) in the cache of the current object.

Returns: An unsigned integer.

Note

This function replaces the deprecated function getNumberOfRelations whose name was misleading and the documentation false. The previous function does not exist anymore. Nonetheless the code compatibility of existing application is preserved due to declaration of the synonym:

#define getNumberOfRelations getNumberOfEntities

Implemented in IldDbmsModel.

◆ getNumberOfRequests()

virtual IlUInt IldDbms::getNumberOfRequests ( ) const

pure virtual

Find the number of existing requests.

Returns: The number of IldRequest objects created by the current object.

Implemented in IldDbmsModel.

◆ getProcedure() [1/2]

virtual IldCallable* IldDbms::getProcedure	(	const char *	procName,
		const char *	owner = `0`
	)

pure virtual

Search, by name, the cache for a procedure descriptor.

Parameters

procName	The procedure name.
owner	Optionally, the owner's name.

Returns: The procedure descriptor or a null pointer.

If no descriptor with such name and owner is found in the cache of the current object, this member function queries the RDBMS with the arguments procName and owner, and returns the matching results.

Note: If an object is created, it is stored in the cache.

This member function can raise the following errors:

ILD_DBMS_NOT_CONNECTED
ILD_MEMORY_EXHAUSTED
ILD_UNKNOWN_ENTITY
Any error detected by the RDBMS itself.

In case of error, this member function returns a null pointer.

Implemented in IldDbmsModel.

◆ getProcedure() [2/2]

virtual IldCallable* IldDbms::getProcedure ( IlInt procId )

pure virtual

Search, by identifier, the cache for a procedure descriptor.

Parameters

procId The procedure identifier.

Returns: The procedure descriptor or a null pointer.

If no descriptor with such an identifier is found in the cache of the current object, this member function queries the RDBMS with the argument procId and returns the matching results.

Note: If an object is created, it is stored in the cache. Thus it must not be destroyed by the application.

This member function can raise the following errors:

ILD_DBMS_NOT_CONNECTED
ILD_MEMORY_EXHAUSTED
ILD_UNKNOWN_ENTITY
Any error detected by the RDBMS itself.

In case of error, this member function returns a null pointer.

Implemented in IldDbmsModel.

◆ getRelation() [1/2]

virtual IldRelation* IldDbms::getRelation	(	const char *	relName,
		const char *	owner = `0`
	)

pure virtual

Search, by name, the cache for a relation descriptor.

Parameters

relName	The relation name.
owner	Optionally, the relation owner's name.

Returns: The relation descriptor or a null pointer.

If no such relation is found in the cache of the current object, this member function queries the relational database management server with the arguments relName and own, and returns the matching results.

Note: If an object is created, it is stored in the cache. Thus it must not be destroyed by the application.

This member function can raise the following errors:

ILD_DBMS_NOT_CONNECTED
ILD_MEMORY_EXHAUSTED
ILD_UNKNOWN_ENTITY
Any error detected by the RDBMS itself.

In case of error, this member function returns a null pointer.

Implemented in IldDbmsModel.

◆ getRelation() [2/2]

virtual IldRelation* IldDbms::getRelation ( IlInt relId )

pure virtual

Search, by identifier, the cache for a relation descriptor.

Parameters

relId The identifier of the relation.

Returns: The relation descriptor or a null pointer.

If no such relation is found in the cache, this member function queries the RDBMS with the argument relId and returns the matching results.

Note: If an object is created, it is stored in the cache. Thus it must not be destroyed by the application.

This member function can raise the following errors:

ILD_DBMS_NOT_CONNECTED
ILD_MEMORY_EXHAUSTED
ILD_UNKNOWN_ENTITY
Any error detected by the RDBMS itself.

In case of error, this member function returns a null pointer.

Implemented in IldDbmsModel.

◆ getSynonym() [1/2]

virtual IldSynonym* IldDbms::getSynonym	(	const char *	synName,
		const char *	owner = `0`
	)

pure virtual

Search, by name, the cache for a synonym descriptor.

Parameters

synName	The synonyms' name.
owner	Optionally, the owenr's name.

Returns: The synonyms' descriptor or a null pointer.

If no descriptor with such a name is found in the cache of the current object, this member function queries the RDBMS with the arguments synName and own, and returns the matching results.

Note: If an object is created, it is stored in the cache.

This member function can raise the following errors:

ILD_DBMS_NOT_CONNECTED
ILD_MEMORY_EXHAUSTED
ILD_UNKNOWN_ENTITY
Any error detected by the RDBMS itself.

In case of error, this member function returns a null pointer.

Implemented in IldDbmsModel.

◆ getSynonym() [2/2]

virtual IldSynonym* IldDbms::getSynonym ( IlInt synId )

pure virtual

Search, by identifier, the cache for a synonym descriptor.

Parameters

synId The synonyms' identifier.

Returns: The synonyms' descriptor or a null pointer.

If no descriptor with such identifier is found in the cache of the current object, this member function queries the RDBMS with the argument synId and returns the matching results.

Note: If an object is created, it is stored in the cache.

This member function can raise the following errors:

ILD_DBMS_NOT_CONNECTED
ILD_MEMORY_EXHAUSTED
ILD_UNKNOWN_ENTITY
Any error detected by the RDBMS itself.

In case of error, this member function returns a null pointer.

Implemented in IldDbmsModel.

◆ getTypeInfo()

virtual const IldSQLType** IldDbms::getTypeInfo ( short cTy = IldSQLAllTypes )

pure virtual

Find one or all built-in datatype descriptors.

Parameters

cTy	The code of the type descriptor to retrieve.

Returns: a null-terminated array of IldSQLType objects.

These objects describe, from the RDBMS point of view, all possible built-in column data types corresponding to the type code cTy. The default value IldSQLAllTypes means that all available data type descriptions must be returned. All other possible values are listed in the description of the function IldSQLType::getType.

This member function can raise the following errors:

ILD_DBMS_NOT_CONNECTED
ILD_MEMORY_EXHAUSTED
ILD_OUT_OF_RANGE
Any error detected by the RDBMS itself.

In case of error, this member function returns a null pointer.

Implemented in IldDbmsModel.

◆ getUser()

virtual const char* IldDbms::getUser ( ) const

pure virtual

Finds the current user name.

Returns: The name of the user of the current database.

This member function returns a null pointer if the current object is not connected. The notion of a "user" depends on the RDBMS. A user may also be the owner of a subset of the current database.

Implemented in IldDbmsModel.

◆ isAsync()

virtual IlBoolean IldDbms::isAsync ( ) const

pure virtual

Indicate whether the current connection is set to process queries in asynchronous mode.

Returns: IlFalse or IlTrue when the asynchronous mode has not or has been turned on.

Calling this function only makes sense for RDBMS that supports asynchronous mode.

Implemented in IldDbmsModel.

◆ isAsyncSupported()

virtual IlBoolean IldDbms::isAsyncSupported ( ) const

pure virtual

Tell if the RDBMS supports asynchronous processing.

Returns: IlTrue or IlFalse depending on whether statements can be processed in asynchronous mode or not.

Asynchronous mode is supported only by DB2, MS SQL Server, ODBC, Oledb and Oracle.

Implemented in IldDbmsModel.

◆ isCompleted()

virtual IlBoolean IldDbms::isCompleted ( ) const

pure virtual

Indicates whether the request currently being executed has been completed.

Returns: IlTrue always when the RDBMS is not one of (DB2, MS SQL Server, ODBC, Oledb and Oracle). For these, it returns IlFalse if and only if the connection is in asynchronous mode and it is not in the waiting state.

Implemented in IldDbmsModel.

◆ isConnected()

virtual IlBoolean IldDbms::isConnected ( ) const

pure virtual

Find if the connection is established.

Returns: IlTrue if the current object is connected. Otherwise, it returns IlFalse.

Note: This predicate actually tells if the connect function was called and the connection was successfully established. It can not be used to verify if the connection was not lost due to network issues or server unavailability.

Implemented in IldDbmsModel.

◆ isReadOnlyCapable()

virtual IlBoolean IldDbms::isReadOnlyCapable ( ) const

pure virtual

Tell if the server supports read-only cursors.

Returns: IlTrue if the server the object is connected to has the capability to handle cursors in read-only mode.

Implemented in IldDbmsModel.

◆ isScrollableCapable()

virtual IlBoolean IldDbms::isScrollableCapable ( ) const

pure virtual

Tell if the server supports scrollable cursors.

Returns: IlTrue if the server the object is connected to has the capability to handle scrollable cursors.

Implemented in IldDbmsModel.

◆ isTransactionEnabled()

virtual IlBoolean IldDbms::isTransactionEnabled ( )

pure virtual

Tell if the connected to server is handling transactions.

Returns: IlTrue if the server the object is connected to has the capability to handle transactions. Otherwise, it returns IlFalse.

Implemented in IldDbmsModel.

◆ isTransactionReadOnly()

virtual IlBoolean IldDbms::isTransactionReadOnly ( ) const

pure virtual

Tell if the transaction read-only mode is active.

Returns: IlTrue if transaction read-only mode is activated.

Implemented in IldDbmsModel.

◆ readAbstractType() [1/2]

virtual IldADTDescriptor* IldDbms::readAbstractType	(	const char *	typeName,
		const char *	owner = `0`
	)

pure virtual

Access the database schema to build the descriptor of a user-defined type (or abstract data type).

Parameters

typeName	The name of the type.
owner	Optionally, the owner name.

Returns: The type descriptor or null.

Since the second argument is optional, if two abstract data types with the same name are accessible to the current user, only the first one will be described.

Warning: This function is implemented only for Object Relational Database Management Systems (ORDBMSs).

This function can raise the following errors:

ILD_DBMS_NOT_CONNECTED
ILD_NOT_IMPLEMENTED
ILD_MEMORY_EXHAUSTED
ILD_UNKNOWN_ENTITY
Any error detected by the RDBMS itself.

In case of error, this member function returns a null pointer.

Note: The returned descriptor is not stored in the entity cache of the current object and, therefore, cannot be found in the cache by the getAbstractType functions that will reread it from the server. The application should delete the descriptor when it is no longer needed.

Implemented in IldDbmsModel.

◆ readAbstractType() [2/2]

virtual IldADTDescriptor* IldDbms::readAbstractType ( IlInt typeId )

pure virtual

Access the database schema to build the descriptor of a user-defined data type.

Parameters

typeId The type identifier.

Returns: The type descriptor or null.

Warning: This function is implemented only for Object Relational Database Management Systems (ORDBMSs).

This function can raise the following errors:

ILD_DBMS_NOT_CONNECTED
ILD_NOT_IMPLEMENTED
ILD_MEMORY_EXHAUSTED
ILD_UNKNOWN_ENTITY
Any error detected by the RDBMS itself.

In case of error, this member function returns a null pointer.

Note: The returned descriptor is not stored in the entity cache of the current object and, therefore, cannot be found in the cache by the getAbstractType functions that will reread it from the server. The application should delete the descriptor when it is no longer needed.

Implemented in IldDbmsModel.

◆ readAbstractTypeNames()

virtual char** IldDbms::readAbstractTypeNames ( const char * owner = 0 )

pure virtual

Find the names of user-defined data types in the current database.

Parameters

owner Optionally, the owner's name.

Returns: An array of character strings that is terminated by a null pointer.

The argument owner is optional. If it is not provided, the member function returns the names of all accessible user-defined data types in the database. The same name can appear several times in the array if there are several user-defined data types accessible to the current user with the same name in the database.

Your application must manage the deallocations of the strings and array returned when they are no longer needed. It is recommended using the function IldDbms::freeNames.

This member function can raise the following errors:

ILD_DBMS_NOT_CONNECTED
ILD_MEMORY_EXHAUSTED
Any error detected by the RDBMS itself.

In case of error, this member function returns a null pointer.

Implemented in IldDbmsModel.

◆ readEntityNames()

virtual IldRequest* IldDbms::readEntityNames	(	IldEntityType	entType,
		const char *	owner = `0`
	)

pure virtual

Query the database for the names and owners of all schema entities of a given type.

Parameters

entType	The type of the entities.
owner	Optionally, the name of the entities owner.

Returns: A result set, handled inside an IldRequest instance.

In this result set, the first column is made up of the catalog names of the entities. The second column is made of the owner names of these entities. The third column holds the entity names.

If the optional second argument is passed, only the names of the entities belonging to that owner will be returned.

This function can raise the following errors:

ILD_DBMS_NOT_CONNECTED
ILD_MEMORY_EXHAUSTED
ILD_OUT_OF_RANGE
Any error detected by the RDBMS itself.

In case of error, this member function returns a null pointer.

Once all entity names and owners have been fetched, the returned IldRequest instance can be either released or reused.

Implemented in IldDbmsModel.

◆ readForeignKeys()

virtual IldDbms& IldDbms::readForeignKeys ( IldRelation * rel )

pure virtual

Build the descriptor of the relation foreign keys.

Parameters

rel	The relation whose foreign keys descriptors are to be retrieved.

Returns: The current object by reference.

Implemented in IldDbmsModel.

◆ readIndexes()

virtual IldDbms& IldDbms::readIndexes ( IldRelation * rel )

pure virtual

Build the descriptor of the relation indexes.

Parameters

rel	The relation whose index descriptors are to be retrieved.

Returns: The current object by reference.

Implemented in IldDbmsModel.

◆ readOwners()

virtual char** IldDbms::readOwners ( )

pure virtual

Find the names of all owner of any entity in the database.

Returns: An array of all owner names found in the database, that is, of the names of all the users who own at least one entity in the database.

It is the application responsibility to free the array and its individual strings once it is done with it.

The following errors can be raised:

ILD_DBMS_NOT_CONNECTED
ILD_MEMORY_EXHAUSTED
Any error detected by the RDBMS itself.

Implemented in IldDbmsModel.

◆ readPrimaryKey()

virtual IldDbms& IldDbms::readPrimaryKey ( IldRelation * rel )

pure virtual

Build the descriptor of the relation primary key.

Parameters

rel	The realtion whose primary descriptor is to be built.

Returns: The current object by reference.

Implemented in IldDbmsModel.

◆ readProcedure() [1/2]

virtual IldCallable* IldDbms::readProcedure	(	const char *	procName,
		const char *	owner = `0`
	)

pure virtual

Access the database schema to build the descriptor of a procedure or function.

Parameters

procName	The procedure or function name.
owner	Optionally, the owner name.

Returns: The procedure or function descriptor.

Since the second argument is optional, if it is not given a value and two procedures or functions with the same name are accessible to the current user, only the first one will be described. Which object comes first is RDBMS dependent.

This function can raise the following errors:

ILD_DBMS_NOT_CONNECTED
ILD_MEMORY_EXHAUSTED
ILD_UNKNOWN_ENTITY
Any error detected by the RDBMS itself.

In case of error, this member function returns a null pointer.

Note: The returned descriptor is not stored in the entity cache of the current object and, therefore, cannot be found in the cache by the getProcedure functions that will read it again from the server. The application should delete the descriptor when it is no longer needed.

Implemented in IldDbmsModel.

◆ readProcedure() [2/2]

virtual IldCallable* IldDbms::readProcedure ( IlInt procId )

pure virtual

Access the database schema to build the descriptor of a procedure or function.

Parameters

procId The identifier of the procedure or function.

Returns: The procedure or function descriptor or null.

This function can raise the following errors:

ILD_NOT_IMPLEMENTED
ILD_DBMS_NOT_CONNECTED
ILD_MEMORY_EXHAUSTED
ILD_UNKNOWN_ENTITY
Any error detected by the RDBMS itself.

In case of error, this member function returns a null pointer.

Note: The returned descriptor is not stored in the entity cache of the current object and, therefore, cannot be found in the cache by the getProcedure functions that will reread it from the server. The application should delete the descriptor when it is no longer needed.

Warning: For Oracle, two overloaded procedures or functions belonging to the same package share the same numerical identifier. As a consequence, only the first one will be retrieved by this function.

Implemented in IldDbmsModel.

◆ readProcedureNames()

virtual char** IldDbms::readProcedureNames ( const char * owner = 0 )

pure virtual

Find the names of the procedures or functions in the current database.

Parameters

owner Optionally, the name of the owner of the procedures or functions.

Returns: An array of character strings that is terminated by a null pointer.

The argument owner is optional. If it is not provided, the member function returns the names of all accessible procedures or functions in the database. The same name can appear several times in the array if there are several procedures accessible to the current user with the same name in the database.

Your application must manage the deallocation of the strings and array returned when they are no longer needed. It is recommended to use the function IldDbms::freeNames.

This member function can raise the following errors:

ILD_DBMS_NOT_CONNECTED
ILD_MEMORY_EXHAUSTED
Any error detected by the RDBMS itself.

In case of error, this member function returns a null pointer.

Implemented in IldDbmsModel.

◆ readRelation() [1/2]

virtual IldRelation* IldDbms::readRelation	(	const char *	relName,
		const char *	owner = `0`
	)

pure virtual

Access the database schema to build the descriptor of a table or view.

Parameters

relName	The name of the relation (table or view).
owner	Optionally, the owner name.

Returns: The relation descriptor or null.

Since the second argument is optional, if two tables or views with the same name are accessible to the current user, only the first one will be described.

This function can raise the following errors:

ILD_DBMS_NOT_CONNECTED
ILD_MEMORY_EXHAUSTED
ILD_UNKNOWN_ENTITY
Any error detected by the RDBMS itself.

In case of error, this member function returns a null pointer.

Note: The returned descriptor is not stored in the entity cache of the current object and, therefore, cannot be found in the cache by the getRelation functions that will reread it from the server. The application should delete the descriptor when it is no longer needed. Also, the application will not be able to get the keys or indexes of the table because the descriptor is not attached to the connection.

Implemented in IldDbmsModel.

◆ readRelation() [2/2]

virtual IldRelation* IldDbms::readRelation ( IlInt relId )

pure virtual

Access the database schema to build the descriptor of a table or view.

Parameters

relId The identifier of the relation or view.

Returns: The relation descriptor or null.

This function can raise the following errors:

ILD_NOT_IMPLEMENTED
ILD_DBMS_NOT_CONNECTED
ILD_MEMORY_EXHAUSTED
ILD_UNKNOWN_ENTITY
Any error detected by the RDBMS itself.

In case of error, this member function returns a null pointer.

Note: The returned descriptor is not stored in the entity cache of the current object and, therefore, cannot be found in the cache by the getRelation functions that will read it again from the server. The application should delete the descriptor when it is no longer needed. Also, the application will not be able to get the keys or indexes of the table because the descriptor is not attached to the connection.

Implemented in IldDbmsModel.

◆ readRelationNames() [1/2]

virtual char** IldDbms::readRelationNames ( char **& owners )

pure virtual

Read all the names and owners of all the tables and views from the database.

Parameters

owners The reference to a place where an array of strings will be set.

Returns: An array of the relation names and sets the argument owners to an array of the owner names. Both arrays are terminated by a null pointer.

The argument owners is set to an array of strings containing the relation-owner names. The indexes in that array correspond to the indexes in the array of relations. In other words, the relation at index 0 is owned by the owner at index 0, and so on.

Your application must manage the deallocation of the strings and arrays returned when they are no longer needed. It is recommended using the function IldDbms::freeNames.

This function can raise the following errors:

ILD_DBMS_NOT_CONNECTED
ILD_MEMORY_EXHAUSTED
Any error detected by the RDBMS itself.

In case of error, this member function returns a null pointer and owners is not set.

Implemented in IldDbmsModel.

◆ readRelationNames() [2/2]

virtual char** IldDbms::readRelationNames ( const char * owner = 0 )

pure virtual

Find the names of the relations in the current database.

Parameters

owner Optionally, tne name of the relations' owner.

Returns: An array of strings.

The relation names are returned as an array of character strings that is terminated by a null pointer.

The argument owner is optional. If it is not provided, the function returns the names of all accessible relations in the database. The same name can appear several times in the array if there are several relations accessible to the current user with the same name in the database. (Certain RDBMSs allow different users to create more than one table with the same name. These systems distinguish the tables by their owners–the users who created the tables).

Your application must manage the deallocation of the strings and array returned when they are no longer needed. It is recommended using the function IldDbms::freeNames.

This function can raise the following errors:

ILD_DBMS_NOT_CONNECTED
ILD_MEMORY_EXHAUSTED
Any error detected by the RDBMS itself.

In case of error, this member function returns a null pointer.

Implemented in IldDbmsModel.

◆ readRelationOwners()

virtual char** IldDbms::readRelationOwners ( const char * rN = 0 )

pure virtual

Retrieves the list of relation owners.

Parameters

rN	Optionally, a relation name.

Returns: The list of relation owner names.

This member function accepts the name of a relation relName as an optional argument. It returns an array of character strings indicating the names of the owners of all tables or views, or the names of the owners of the given table or view. The array is terminated by a null pointer.

Your application must manage the deallocation of the strings and array returned when they are no longer needed. It is recommended using the function IldDbms::freeNames.

This function can raise the following errors:

ILD_DBMS_NOT_CONNECTED
ILD_MEMORY_EXHAUSTED
Any error detected by the RDBMS itself.

In case of error, this member function returns a null pointer.

If a relation name was passed but no such table or view exists in the database, the returned value is also null.

Implemented in IldDbmsModel.

◆ readSpecialColumns()

virtual IldDbms& IldDbms::readSpecialColumns ( IldRelation * rel )

pure virtual

Build the descriptor of the relation special columns.

Parameters

rel	The relation whose special columns descriptor is to be built.

Returns: The current object by reference.

Implemented in IldDbmsModel.

◆ readSynonym() [1/2]

virtual IldSynonym* IldDbms::readSynonym	(	const char *	synName,
		const char *	own = `0`
	)

pure virtual

Access the database schema to build the descriptor of a synonym.

Parameters

synName	The synonym name.
own	Optionally, the owner name.

Returns: The synonym decriptor or null.

Since the second argument is optional, if it is not given a value and two synonyms with the same name are accessible to the current user, only the first one will be described.

Warning: This function is implemented only for RDBMSs that support synonyms.

This function can raise the following errors:

ILD_DBMS_NOT_CONNECTED
ILD_NOT_IMPLEMENTED
ILD_MEMORY_EXHAUSTED
ILD_UNKNOWN_ENTITY
Any error detected by the RDBMS itself.

In case of error, this member function returns a null pointer.

Note: The returned descriptor is not stored in the entity cache of the current object and, therefore, cannot be found in the cache by the getAbstractType functions that will reread it from the server. The application should delete the descriptor when it is no longer needed.

Implemented in IldDbmsModel.

◆ readSynonym() [2/2]

virtual IldSynonym* IldDbms::readSynonym ( IlInt synId )

pure virtual

Access the database schema to build the descriptor of a synonym.

Parameters

synId The synonum identifier.

Returns: The synonym descriptor or null.

Warning: This function is implemented only for RDBMSs that support synonyms.

This function can raise the following errors:

ILD_DBMS_NOT_CONNECTED
ILD_NOT_IMPLEMENTED
ILD_MEMORY_EXHAUSTED
ILD_UNKNOWN_ENTITY
Any error detected by the RDBMS itself.

In case of error, this member function returns a null pointer.

Note: The returned descriptor is not stored in the entity cache of the current object and, therefore, cannot be found in the cache by the getAbstractType functions that will reread it from the server. The application should delete the descriptor when it is no longer needed.

Implemented in IldDbmsModel.

◆ readSynonymNames()

virtual char** IldDbms::readSynonymNames ( const char * owner = 0 )

pure virtual

Find the names of the synonyms in the current database.

Parameters

owner Optionally, the owner name of the synonyms.

Returns: An array of character strings that is terminated by a null pointer.

The argument owner is optional. If it is not provided, the member function returns the names of all accessible synonyms in the database. The same name can appear several times in the array if there are several synonyms accessible to the current user with the same name in the database.

Your application must manage the deallocation of the strings and array returned when they are no longer needed. It is recommended using the function IldDbms::freeNames.

This member function can raise the following errors:

ILD_DBMS_NOT_CONNECTED
ILD_MEMORY_EXHAUSTED
Any error detected by the RDBMS itself.

In case of error, this member function returns a null pointer.

Implemented in IldDbmsModel.

◆ readTablePrivileges()

virtual IldRequest* IldDbms::readTablePrivileges	(	const char *	catalog,
		const char *	schema,
		const char *	table
	)

pure virtual

Query the database for the privileges established on a given table.

Parameters

catalog	May be the database name. The exact meaning of this argument will differ according to the RDBMS.
schema	The schema name (or the table owner name).
table	The name of the table.

Returns

A result set with the following columns:

table_qualifier
table_owner
table_name
grantor
grantee
privilege
is_grantable

The table is identified by the values of the parameters. These three parameters may be null.

The privilege field will be a character string with one of the following values: SELECT, INSERT, UPDATE, DELETE, or REFERENCES.

This member function can raise the following errors:

ILD_DBMS_NOT_CONNECTED
ILD_MEMORY_EXHAUSTED
ILD_INVALID_SEQUENCE
Any error detected by the RDBMS itself.

In case of error, this member function returns a null pointer.

Once all privileges have been fetched, the returned IldRequest instance can be either destroyed, released, or reused.

Implemented in IldDbmsModel.

◆ removeEntity()

virtual void IldDbms::removeEntity ( IldSchemaEntity * ent )

pure virtual

Remove an entity descriptor from the current object cache.

Parameters

ent	The entity descriptor to dereference.

The entity descriptor object is not deleted; it just does not reference the connection any more.

This member function can raise the following error:

ILD_DBMS_NOT_CONNECTED

Implemented in IldDbmsModel.

◆ removeRelation()

virtual void IldDbms::removeRelation ( IldRelation * rel )

pure virtual

Remove a relation descriptor obejct from the cache.

Parameters

rel	The relation descriptor to remove.

The relation object is not deleted; it just does not reference the connection any more.

This member function can raise the following errors:

ILD_DBMS_NOT_CONNECTED

Implemented in IldDbmsModel.

◆ rollback()

virtual IldDbms& IldDbms::rollback	(	IldRequest *	r = `0`,
		const char *	tN = `0`
	)

pure virtual

Cause the RDBMS to undo what had been processed since the begining of the current transaction.

Parameters

r	Optionally, the request object.
tN	Optionally, the transaction name.

Returns: The current object by reference.

This member function can raise the following errors:

ILD_DBMS_NOT_CONNECTED
ILD_REQUEST_REQUIRED
ILD_INVALID_SEQUENCE
Any error detected by the RDBMS itself.

Implemented in IldDbmsModel.

◆ setAsync()

virtual IldDbms& IldDbms::setAsync ( IlBoolean flag )

pure virtual

Change the asynchronous processing mode.

Parameters

flag	Asynchronous mode is turned ON if it is set to `IlTrue` or OFF if it is set to `IlFalse`.

Returns: the current object by reference.

It raises the error ILD_NOT_IMPLEMENTED for all RDBMSs except Db2, MS SQL Server, ODBC, Oledb and Oracle.

Implemented in IldDbmsModel.

◆ setDefaultColArraySize()

virtual IldDbms& IldDbms::setDefaultColArraySize ( IlUInt size )

pure virtual

Set the default size of the fetch array of requests.

Parameters

size	The default result set size for all `IldRequest` objects created using this connection.

Returns: The current connection object by reference.

Implemented in IldDbmsModel.

◆ setDefaultParamArraySize()

virtual IldDbms& IldDbms::setDefaultParamArraySize ( IlUInt size )

pure virtual

Set the default parameter array size.

Parameters

size	The default number of parameter rows that will be sent simultaneously to the server by an `IldRequest` object issued from the current connection when executing a query.

Returns: The current object by reference.

Implemented in IldDbmsModel.

◆ setErrorReporter()

virtual IldDbms& IldDbms::setErrorReporter ( IldErrorReporter * r )

pure virtual

Set the default user error reporter.

Parameters

r	The default user error reporter for the current object.

Returns: The current object by reference.

If there are no more references to the previous error reporter, DB Link destroys the unreferenced object. If the reporter is the same as the already present one, nothing will happen.

This function can raise the error:

ILD_NO_REPORTER

Implemented in IldDbmsModel.

◆ setHook()

virtual IldDbms& IldDbms::setHook ( IlAny hook )

pure virtual

Establish a hook into the RDBMS.

Parameters

hook	The RDBMS API hook to use.

Returns: The current object by reference.

This member function is used to integrate DB Link within an already existing application built with the RDBMS native API.

For example, you may use the RDBMS native API in an already existing program, and initialize an IldDbms connection with a connection already opened by this program.

To use this member function, the IldDbms instance must be already disconnected. The connection attached to the IldDbms object will not be destroyed when the IldDbms object is deleted.

This member function can raise the error:

ILD_INVALID_SEQUENCE

Implemented in IldDbmsModel.

◆ setTimeOut()

virtual IldDbms& IldDbms::setTimeOut ( short secs )

pure virtual

Set the time-out period for long executing queries.

Parameters

secs	The number of seconds to wait.

Returns: The current object by reference.

Warning: Not all RDBMSs support this capability dynamically.

This member function can raise the following errors:

ILD_NOT_IMPLEMENTED
ILD_UNCHGEABLE
Any error detected by the RDBMS itself.

Note: This function is not implemented for Sybase.

Implemented in IldDbmsModel.

◆ setTransactionReadOnly()

virtual IldDbms& IldDbms::setTransactionReadOnly ( IlBoolean f = IlTrue )

pure virtual

Activates or deactivates transactions read-only mode.

Parameters

f	Use `IlTrue` to activate read-only mode, `IlFalse` to deactivate it.

Returns: The current object by reference.

Transactions can be either in "read write" or "read only" mode. "read write" is usually the database default. "read only" mode will affect two points :

whether the transaction can run update queries,
whether it is isolated from updates done by other transactions.

By default read-write mode is used. That setting must be done before the transaction is opened.

This function can raise the error:

ILD_NOT_IMPLEMENTED

Implemented in IldDbmsModel.

◆ startTransaction()

virtual IldDbms& IldDbms::startTransaction	(	IldRequest *	r = `0`,
		const char *	tN = `0`
	)

pure virtual

Open a transaction.

Parameters

r	Optionally, the request object.
tN	Optionally, the transaction name.

Returns: The current object by reference.

In a system where a request object is required for a transaction, the parameter r indicates that object. In a system where instantiating transactions is allowed, tN indicates the name of the transaction.

This member function can raise the following errors:

ILD_DBMS_NOT_CONNECTED
ILD_REQUEST_REQUIRED
Any error detected by the RDBMS itself.

Implemented in IldDbmsModel.

◆ subscribeEvent()

virtual IldDbms& IldDbms::subscribeEvent	(	const char *	name,
		IldNotifFunction	usrCB,
		IlAny	usrData
	)

pure virtual

Register the application to receive a notification.

Parameters

name	The event name.
usrCB	The user callback to call.
usrData	The user data to pass when calling the callback.

Returns: The current object by reference.

When the event is triggered, usrCB is called with usrData as a parameter. usrCB is a required parameter (that is cannot be null), but usrData does not need to be set if it is not required by usrCB.

This member function can raise the following errors:

ILD_INVALID_SEQUENCE
ILD_INVALID_PARAMETER
ILD_MEMORY_EXHAUSTED
Any error detected by the RDBMS itself.

Implemented in IldDbmsModel.

◆ unSubscribeEvent()

virtual IldDbms& IldDbms::unSubscribeEvent ( const char * name )

pure virtual

Unsubscribe from the given event.

Parameters

name	The vent to unsubscribe from.

Returns: The current object by reference.

This member function can raise the following errors:

Any error detected by the RDBMS itself.

Implemented in IldDbmsModel.

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ~IldDbms()

Member Function Documentation

◆ autoCommitOff()

◆ autoCommitOn()

◆ cancel()

◆ commit()

◆ connect() [1/2]

◆ connect() [2/2]

◆ disconnect()

◆ execute()

◆ freeEntity()

◆ freeNames()

◆ freeTypeInfo()

◆ getAbstractType() [1/2]

◆ getAbstractType() [2/2]

◆ getDatabase()

◆ getDbmsServer()

◆ getDbmsVersion()

◆ getDbmsVersions()

◆ getDefaultColArraySize()

◆ getDefaultParamArraySize()

◆ getErrorReporter()

◆ getFreeRequest()

◆ getHook()

◆ getInfo()

◆ getName()

◆ getNumberOfActiveConnections()

◆ getNumberOfEntities()

◆ getNumberOfRequests()

◆ getProcedure() [1/2]

◆ getProcedure() [2/2]

◆ getRelation() [1/2]

◆ getRelation() [2/2]

◆ getSynonym() [1/2]

◆ getSynonym() [2/2]

◆ getTypeInfo()

◆ getUser()

◆ isAsync()

◆ isAsyncSupported()

◆ isCompleted()

◆ isConnected()

◆ isReadOnlyCapable()

◆ isScrollableCapable()

◆ isTransactionEnabled()

◆ isTransactionReadOnly()

◆ readAbstractType() [1/2]

◆ readAbstractType() [2/2]

◆ readAbstractTypeNames()

◆ readEntityNames()

◆ readForeignKeys()

◆ readIndexes()

◆ readOwners()

◆ readPrimaryKey()

◆ readProcedure() [1/2]

◆ readProcedure() [2/2]

◆ readProcedureNames()

◆ readRelation() [1/2]

◆ readRelation() [2/2]

◆ readRelationNames() [1/2]

◆ readRelationNames() [2/2]

◆ readRelationOwners()

◆ readSpecialColumns()

◆ readSynonym() [1/2]

◆ readSynonym() [2/2]

◆ readSynonymNames()

◆ readTablePrivileges()

◆ removeEntity()

◆ removeRelation()

◆ rollback()

◆ setAsync()

◆ setDefaultColArraySize()

◆ setDefaultParamArraySize()

◆ setErrorReporter()

◆ setHook()

◆ setTimeOut()

◆ setTransactionReadOnly()

◆ startTransaction()