Database access class. More...

#include <ilviews/dataccess/dbms/session.h>

Inheritance diagram for IliSQLSession:

Public Member Functions
	IliSQLSession ()
	This is the default constructor of the `IliSQLSession` class.

	IliSQLSession (const char dbmsName, const char params)
	Initializes an `IliSQLSession` object with specific data. More...

	IliSQLSession (const IliSQLSession &)
	This is the copy constructor of the `IliSQLSession` class.

IlBoolean	cancelAsyncCall ()
	Attempts to cancel any asynchronous call in progress. More...

IlBoolean	commit ()
	Commits any work pending in the current transaction. More...

IlBoolean	connect ()
	Attempts to connect to the remote database specified by the parameters of the session. More...

IlBoolean	disconnect ()
	Disconnects from the database. More...

virtual void	emitDate (IliString &dest, IliDate val) const
	Uses the database driver to format a date for a sql query. More...

virtual void	emitTime (IliString &dest, IliTime val) const
	Uses the database driver to format a time for a sql query. More...

IlBoolean	enterAsyncMode ()
	Attempts to switch to asynchronous mode. More...

IlBoolean	errorRaised () const
	Returns `IlTrue` if the last non-`const` member function, called on the session object, has failed. More...

const char *	getConnectionOptions () const
	Returns the connection options which will be used to locate the database server over the network. More...

const char *	getConnectionParams () const
	Returns the user name, the password, the database name, and the connection options, packaged into one character string. More...

const char *	getDatabaseName () const
	Returns the name of the database instance to which the session will connect. More...

const char *	getDbmsName () const
	Returns the name of the database driver. More...

IliSQLSession *	getEffectiveSQLSession ()
	Returns the effective session. More...

IliErrorMessage	getErrorMessage () const
	Returns the error message relative to the last non-`const` member function call. More...

IlAny	getHook () const
	Returns a hook into the database link layer being used. More...

const char *	getPassword () const
	Returns the password that will be used to log onto the remote database. More...

const char *	getSessionName () const
	Returns the name property of the session. More...

const char *	getUserName () const
	Returns the name of the user account that will be used to log onto the remote database. More...

IlBoolean	hasSameParams (const IliSQLSession *sess) const
	Returns `IlTrue` if the session object has the same parameters as another session object. More...

IlBoolean	isAMoniker () const
	Indicates if this session is a moniker session. More...

IlBoolean	isAsyncCallCompleted ()
	Returns `IlTrue` if the last call to one of the asynchronous-enabled member functions has completed. More...

IlBoolean	isConnected () const
	Returns `IlTrue` if the session is currently connected. More...

IlBoolean	isInAsyncMode ()
	Returns `IlTrue` if the session is currently in asynchronous mode. More...

IlBoolean	isPasswordSaved () const
	Returns `IlTrue` if the password is written along with the other parameters when the `write()` member function is called. More...

IlBoolean	isRegistered () const
	Returns `IlTrue` if the session is registered. More...

IliSQLCursor *	newCursor ()
	Allocates and returns a cursor attached to the session object. More...

IlBoolean	queryConnect (IlvDisplay display, IlvAbstractView view, IliSQLQueryConnectFlag flag=IliSQLQueryIfNeeded, IlBoolean showName=IlFalse)
	This member function is similar to the `connect()` member function, except that it attempts to connect to the effective session of this session. More...

IlBoolean	quitAsyncMode ()
	Attempts to switch to synchronous mode. More...

void	read (IL_STDPREF istream &input)
	Reads the definition of a session from an input stream. More...

char **	readSynonymNames (IlInt &count, const char *synOwner=0)
	Returns the list of synonym names. More...

IliSQLTableDef *	readTableDefinition (IlvDisplay display, const char tableName, const char *tableOwner=0, IlBoolean isSynonym=IlFalse)
	Returns the schema of one table. More...

char **	readTableNames (IlInt &count, const char *tableOwner=0)
	Reads the catalog of the database which the session is connected to, and returns an array of table names. More...

void	releaseCursor (IliSQLCursor *curs)
	Returns a cursor to the session object. More...

IlBoolean	rollback ()
	Cancels any work in progress in the current transaction. More...

void	savePassword (IlBoolean flag)
	Specifies whether the password must be saved along with the other parameters, when the `write()` member function is called. More...

void	setAsMoniker (IlBoolean moniker)
	Specifies whether this session is a moniker session. More...

void	setConnectionOptions (const char *opt)
	Sets the connection options that will be used to locate the database server over the network. More...

void	setConnectionParams (const char *params)
	Parses the parameters according to the rules of the database driver being used and sets the user, password, database, and connection options properties accordingly. More...

void	setDatabaseName (const char *name)
	Sets the name of the database which the session will connect. More...

void	setDbmsName (const char *name)
	Sets the name of the database driver. More...

void	setPassword (const char *pwd)
	Sets the password that will be used to log onto the remote database. More...

void	setSessionName (const char *name)
	Sets the name property of the session. More...

void	setSessionParams (const IliSQLSession *sess)
	Overwrites the parameters of the session object with a copy of the session parameters of another session object. More...

void	setTimeout (short nsecs)
	Sets the time-out. More...

void	setUserName (const char *name)
	Sets the name of the user account that will be used to log onto the remote database. More...

IlBoolean	startTransaction ()
	Starts a new transaction. More...

IlBoolean	supportsAsyncMode ()
	Returns `IlTrue` if the database system supports asynchronous mode. More...

void	write (IL_STDPREF ostream &output) const
	Writes the definition of a session to an output stream in a form suitable for reading back by the `read()` member function. More...

Public Member Functions inherited from IliSession
	IliSession ()
	This is the default constructor of the `IliSession` class.

	IliSession (const IliSession &)
	This is the copy constructor of the `IliSession` class.

Public Member Functions inherited from IliRefCounted
IlInt	getRefCount () const
	Returns the reference count of the object. Initially, this property is set to `0`. More...

void	lock () const
	Increments the reference count of the object.

void	unLock () const
	Decrements the reference count of the object. More...

Static Public Member Functions
static void	ConnectToMessageDatabase (IlvDisplay *display)
	Calls the `ReadMessageDatabase()` member function. More...

static void	EnableSQLTrace (IlBoolean f)
	Enables/Disables the trace facility. More...

static void	ForwardErrorToGlobalSink (IlBoolean forward)
	Forwards the error messages to the global error sink. More...

static const char const	GetDbmsNames (IlInt &count)
	Returns the names of the database drivers which are supported in the program. More...

static IliSQLSession *	GetDefault ()
	Returns a default session object. More...

static IliSQLSession *	GetRegisteredSession (const char *name)
	Returns a session in the registering mechanism. More...

static IliSQLSession *	GetRegisteredSession (IlInt index)
	Returns a session in the registering mechanism. More...

static IlInt	GetRegisteredSessionsCount ()
	Returns the number of registered sessions. More...

static IliSQLTraceOptions	GetTraceOptions ()
	Returns the current settings of the trace facility. More...

static IlBoolean	IsBadLicense ()
	Returns `IlTrue` if the Data Access SQL license is invalid. More...

static IlBoolean	isForwardErrorToGlobalSink ()
	Returns `IlTrue` if the error message are forwarded to the global error sink. More...

static IlBoolean	IsSQLTraceEnabled ()
	Returns `IlTrue` if the trace facility is currently enabled. More...

static void	ReadMessageDatabase (IlvDisplay *display)
	Takes into account the translations for DbLink error messages that are currently in effect in the display message database. More...

static IlBoolean	RegisterSession (const char sessionName, const char dbmsName, const char *connectionParams)
	Registers a new session. More...

static IlBoolean	RegisterSession (IliSQLSession *sess)
	Registers a session under its own name. More...

static void	SetNewDbmsFunction (IliSQLNewDbmsFunction fct)
	Sets the function that will be used to create new Rogue Wave Views DBLink `IldDbms` objects, when required. More...

static void	SetTraceOptions (const IliSQLTraceOptions &opt)
	Sets the settings of the trace facility. More...

static void	UnRegisterSession (IliSQLSession *sess)
	Unregisters a session. More...

Additional Inherited Members
Protected Member Functions inherited from IliRefCounted
virtual	~IliRefCounted ()
	This is the virtual destructor of the `IliRefCounted` class. More...

Detailed Description

Database access class.

Library: dbaccess

The IliSQLSession class defines objects that can connect to, and serve as a communication channel with, a remote database system. It works in conjunction with a companion class, IliSQLCursor.

About reference counting

Session objects are reference counted. This means that many parts of a program can share the same session objects, and explains why session objects are never explicitly deleted. Instead, a session object must be locked before it can be used. It can then be used as long as necessary, until it is unlocked when finished with. In this way, the session object will effectively be deleted when the number of its users is zero.

About transactions

A transaction is a collection of related updates submitted to a database. To create a transaction through a connected session, you should first call the startTransaction() member function. You will obtain one or more cursors from the session, which should be used to submit a series of updates to the database in the form of SQL statements.

Once all the work that belongs to the transaction has been submitted, you can either commit the transaction with the commit() member function, or cancel it with the rollback() member function. The transaction concept allows you to group a collection of related updates to a database so that they will either succeed collectively, or fail collectively. You may then assume that the database will never be left in a state where some updates have succeeded, whereas others have failed.

About asynchronous mode

Asynchronous mode is a special mode that affects several member functions of the IliSQLSession and IliSQLCursor classes:

IliSQLSession: the readTableNames() and readTableDefinition() member functions.
IliSQLCursor: the parse(), select(), execute(), and fetchNext() member functions.

These member functions need to communicate with a database server through some form of remote procedure call. Consequently, they may take some time to complete. In synchronous mode, these member functions block the calling thread until completion of the function work. In asynchronous mode, these member functions do not block until completion. Instead, they may return prematurely in order to allow the calling thread to proceed with other tasks. Then, the calling thread can periodically call the member function at a later time until it completes its work.

When an IliSQLSession object is in asynchronous mode, all IliSQLCursor objects it owns are also in asynchronous mode.

Note that not all database systems support asynchronous mode and that when it is supported, there may be special constraints.

About error reporting

All non-const IliSQLSession member functions update the error status of the session object. If the member function succeeds, the error status is cleared, otherwise it is set to the relevant error message. Since the two member functions that allow you to query this error status are const, they do not modify the error status and can therefore be called repeatedly and in any order.

About registering

Session registering is a mechanism allowing session objects to be named and registered under their name. This name can then be used to retrieve them.

About trace options

The trace facility allows you to monitor the progress of the communication between an application and a database. By default, this facility is not enabled. The structure IliDbmsTraceOptions defines which type of events should be traced. All trace output is carried out using the IlvPrint() function. Note that as trace settings are global, it is not possible to restrict tracing to one session object. Instead, when tracing is enabled, it applies to all active sessions.

See also: IliErrorMessage, IliSQLCursor, IliSQLTableRef, IliSQLTableDef, IliSQLTraceOptions, IliSQLNewDbmsFunction, IliSQLQueryConnectFlag.

Accessors\nAccessors provide a scriptable and uniform way to inspect and modify an object by using its base class methods <tt>IlvValueInterface::queryValue()</tt>, <tt>IlvValueInterface::queryValues()</tt>, <tt>IlvValueInterface::changeValue()</tt>, <tt>IlvValueInterface::changeValues()</tt>.\n\n\nThis class inherits the accessors of its superclass \c IliSession and adds the following ones:

Data accessors

Name	Type	Equivalent methods
`connectionOptions`	String	`getConnectionOptions()`, `setConnectionOptions()`
`connectionParams`	String	`getConnectionParams()`, `setConnectionParams()`
`databaseName`	String	`getDatabaseName()`, `setDatabaseName()`
`dbmsName`	String	`getDbmsName()`, `setDbmsName()`
`effectiveSQLSession`	`IliSQLSession`	`getEffectiveSQLSession()`
`isAMoniker`	Boolean	`isAMoniker()`, `setAsMoniker()`
`password`	String	`getPassword()`, `setPassword()`
`passwordSaved`	Boolean	`isPasswordSaved()`, `savePassword()`
`userName`	String	`getUserName()`, `setUserName()`

Method accessors

Name	Return type	Equivalent methods
`cancelAsyncCall()`	Boolean	`cancelAsyncCall()`
`commit()`	Boolean	`commit()`
`connect()`	Boolean	`connect()`
`disconnect()`	Boolean	`disconnect()`
`enterAsyncMode()`	Boolean	`enterAsyncMode()`
`getErrorMessage()`	`IliErrorMessage`	`getErrorMessage()`
`isAsyncCallCompleted()`	Boolean	`isAsyncCallCompleted()`
`isConnected()`	Boolean	`isConnected()`
`isErrorRaised()`	Boolean	`errorRaised()`
`isInAsyncMode()`	Boolean	`isInAsyncMode()`
`isRegistered()`	Boolean	`isRegistered()`
`newCursor()`	`IliSQLCursor`	`newCursor()`
`queryConnect(IlvAbstractView view, Object flags)`	Boolean	`queryConnect(view->getDisplay(), view, flags, IlFalse)`
`quitAsyncMode()`	Boolean	`quitAsyncMode()`
`rollback()`	Boolean	`rollback()`
`setTimeout(Int timeout)`	Void	`setTimeout(timeout)`
`supportsAsyncMode()`	Boolean	`supportsAsyncMode()`

Session Usage A session can be one of the following:

a registered session
a moniker session
a stand-alone session

A registered session is usually defined in Rogue Wave Views Studio in the Application Properties dialog box. It is given a name and can be retrieved by calling the IliSQLSession.getSession() function. Its definition can be found in the application resource file (.iva).

The following code retrieves the session registered under the name "MAIN":

var session = IliSQLSession.getSession("MAIN");

The following syntax can also be used:

var session = IliSQLSession.MAIN;

In other words, the registered sessions become properties of the IliSQLSession object and can be accessed as such.

A moniker session is an object that contains the name of a registered session. At run time, users of a moniker session (such as IliSQLTable) retrieve the corresponding registered session (we call this session the effective session) and use it instead of the moniker session to communicate with a remote database.

A stand-alone session is used by itself to communicate with a remote database.

When a IliSQLDataSource is defined in Rogue Wave Views Studio, the Connect dialog box can be used in two different ways:

An application-defined session is specified in the "Name" field. In this case, the underlying IliSQLTable is defined as having a moniker session.
No application-defined session is specified. Instead, all the required connection parameters are entered. In this case, the underlying IliSQLTable is defined as having a stand-alone session.

Constructor & Destructor Documentation

◆ IliSQLSession()

IliSQLSession::IliSQLSession	(	const char *	dbmsName,
		const char *	params
	)

Initializes an IliSQLSession object with specific data.

Just after an IliSQLSession object is created, the member function lock() should be called so that it can be used as long as required. When it is not needed anymore, the member function unlock() should be called. Note that a newly constructed session object is not connected to a database.

Parameters

dbmsName	The name of the database driver.
params	The connection parameters.

Member Function Documentation

◆ cancelAsyncCall()

IlBoolean IliSQLSession::cancelAsyncCall ( )

Attempts to cancel any asynchronous call in progress.

Returns: IlTrue if successful.

◆ commit()

IlBoolean IliSQLSession::commit ( )

Commits any work pending in the current transaction.

Returns: IlTrue if successful.

◆ connect()

IlBoolean IliSQLSession::connect ( )

Attempts to connect to the remote database specified by the parameters of the session.

Returns: IlTrue if successful, or IlFalse if the connection could not be established or if the session was already connected. In this case, an error message describing the cause of the failure to connect, can be retrieved with the getErrorMessage() member function.

◆ ConnectToMessageDatabase()

static void IliSQLSession::ConnectToMessageDatabase ( IlvDisplay * display )

static

Calls the ReadMessageDatabase() member function.

In addition, it installs a language change hook into the display that will call the ReadMessageDatabase member function again each time a new language is made current.

Parameters

display The display.

◆ disconnect()

IlBoolean IliSQLSession::disconnect ( )

Disconnects from the database.

Returns: IlTrue If the session was currently connected to a remote database, and is disconnected from the database. Otherwise, IlFalse is returned. Any cursors obtained through this session object are deleted.

◆ emitDate()

virtual void IliSQLSession::emitDate	(	IliString &	dest,
		IliDate	val
	)		const

virtual

Uses the database driver to format a date for a sql query.

Parameters

dest	The formated string.
val	The date.

Reimplemented from IliSession.

◆ emitTime()

virtual void IliSQLSession::emitTime	(	IliString &	dest,
		IliTime	val
	)		const

virtual

Uses the database driver to format a time for a sql query.

Parameters

dest	The formated string.
val	The time.

Reimplemented from IliSession.

◆ EnableSQLTrace()

static void IliSQLSession::EnableSQLTrace ( IlBoolean f )

static

Enables/Disables the trace facility.

Parameters

f	If `IlTrue`, the trace facility is enabled. The trace facility is disabled otherwise.

◆ enterAsyncMode()

IlBoolean IliSQLSession::enterAsyncMode ( )

Attempts to switch to asynchronous mode.

Returns: IlTrue if successful.

◆ errorRaised()

IlBoolean IliSQLSession::errorRaised ( ) const

Returns IlTrue if the last non-const member function, called on the session object, has failed.

Returns: IlTrue if the last non-const member function, called on the session object, has failed. In this case, an error message is available through the getErrorMessage member function.

◆ ForwardErrorToGlobalSink()

static void IliSQLSession::ForwardErrorToGlobalSink ( IlBoolean forward )

static

Forwards the error messages to the global error sink.

Parameters

forward If IlTrue The error messages are forwarded to the global error sink. See The IliErrorMessage class.

◆ getConnectionOptions()

const char* IliSQLSession::getConnectionOptions ( ) const

Returns the connection options which will be used to locate the database server over the network.

The default for this property is the empty string. The precise meaning of this property depends on the database driver being used:

ORACLE: The SQL*NET connect string.
INFORMIX: The name of the INFORMIX server.
DB2: Not applicable.
SYBASE: The name of the SYBASE server.
ODBC: Not applicable.
OLEDB: Depend upon final database.
MSSQL: The connect string.

Returns: The connection options.

◆ getConnectionParams()

const char* IliSQLSession::getConnectionParams ( ) const

Returns the user name, the password, the database name, and the connection options, packaged into one character string.

The format of the returned value depends on the database driver being used:

ORACLE: "<user>/<password>@<options>"
INFORMIX: "<user>/<password>/<database>@<options>"
DB2: "<user>/<password>/<database>"
SYBASE: "<user>/<password>/<database>/<options>"
ODBC: "<database>/<user>/<password>"
OLEDB: "<database>/<user>/<password>"
MSSQL: "/<user>/<password>/<database>/<server>"

Returns: The user name, the password, the database name, and the connection options.

◆ getDatabaseName()

const char* IliSQLSession::getDatabaseName ( ) const

Returns the name of the database instance to which the session will connect.

The database name should not be confused with the database driver name returned by the getDbmsName() member function. The default for this property is the empty string. The precise meaning of this property depends on the database driver being used:

ORACLE: Not applicable.
INFORMIX: The name of the database.
DB2: The name of the database.
SYBASE: The name of the database.
MSSQL: The name of the database.
ODBC: The name of the ODBC data source.
OLEDB: The name of the OLEDB data source.

Returns: The name of the database.

◆ getDbmsName()

const char* IliSQLSession::getDbmsName ( ) const

Returns the name of the database driver.

Returns: The name of the database driver.

◆ GetDbmsNames()

static const char* const* IliSQLSession::GetDbmsNames ( IlInt & count )

static

Returns the names of the database drivers which are supported in the program.

Parameters

count The drivers count.

Returns: The names of the database drivers which are supported in the program. The return value is an array of database driver names. The number of driver names in this array is returned through the count parameter. The database drivers that are included in the program are determined at compile time.

See also: SetNewDbmsFunction().

◆ GetDefault()

static IliSQLSession* IliSQLSession::GetDefault ( )

static

Returns a default session object.

Returns: A session.

◆ getEffectiveSQLSession()

IliSQLSession* IliSQLSession::getEffectiveSQLSession ( )

Returns the effective session.

The effective session is retrieved according to the following rules:

If the session has a non null name and if a registered session with that name already exists, the effective session is this registered session,
In all other cases, the effective session is the session itself.

This mechanism is used by some users of the IliSQLSession class (such as IliSQLTable) to implement session sharing.

Returns: The effective session.

◆ getErrorMessage()

IliErrorMessage IliSQLSession::getErrorMessage ( ) const

Returns the error message relative to the last non-const member function call.

Returns: The error message relative to the last non-const member function call.

◆ getHook()

IlAny IliSQLSession::getHook ( ) const

Returns a hook into the database link layer being used.

Returns: A hook into the database link layer being used, if the session object is connected, and 0 otherwise. In the current version of Rogue Wave Views Data Access, this is always an instance of the Rogue Wave Views DBLink class IldDbms.

◆ getPassword()

const char* IliSQLSession::getPassword ( ) const

Returns the password that will be used to log onto the remote database.

The default for this property is the empty string.

Returns: The password.

◆ GetRegisteredSession() [1/2]

static IliSQLSession* IliSQLSession::GetRegisteredSession ( const char * name )

static

Returns a session in the registering mechanism.

Parameters

name	The session name.

Returns: The session in the registering mechanism. Otherwise returns 0.

◆ GetRegisteredSession() [2/2]

static IliSQLSession* IliSQLSession::GetRegisteredSession ( IlInt index )

static

Returns a session in the registering mechanism.

Parameters

index The session index.

Returns: The session in the registering mechanism. Returns 0 if the index is out of bounds.

◆ GetRegisteredSessionsCount()

static IlInt IliSQLSession::GetRegisteredSessionsCount ( )

static

Returns the number of registered sessions.

Returns: The count.

◆ getSessionName()

const char* IliSQLSession::getSessionName ( ) const

Returns the name property of the session.

Returns: The name property of the session. The name property designates the session that will be returned by the getEffectiveSQLSession() member function. The default for this property is the empty string.

◆ GetTraceOptions()

static IliSQLTraceOptions IliSQLSession::GetTraceOptions ( )

static

Returns the current settings of the trace facility.

Returns: The current settings of the trace facility.

◆ getUserName()

const char* IliSQLSession::getUserName ( ) const

Returns the name of the user account that will be used to log onto the remote database.

The default for this property is the empty string.

Returns: The user name.

◆ hasSameParams()

IlBoolean IliSQLSession::hasSameParams ( const IliSQLSession * sess ) const

Returns IlTrue if the session object has the same parameters as another session object.

Parameters

sess	Another session object.

Returns: IlTrue if the session object has the same parameters as the sess session object.

◆ isAMoniker()

IlBoolean IliSQLSession::isAMoniker ( ) const

Indicates if this session is a moniker session.

Returns: IlTrue if this session is a moniker session and IlFalse otherwise.

◆ isAsyncCallCompleted()

IlBoolean IliSQLSession::isAsyncCallCompleted ( )

Returns IlTrue if the last call to one of the asynchronous-enabled member functions has completed.

Returns: IlTrue if the last call to one of the asynchronous-enabled member functions (select(), fetchNext(), and fetchAll()) has completed. If this member function returns IlFalse, is is necessary to call the asynchronous-enabled member function (with the same parameter values) periodically until isAsyncCallCompleted() returns IlTrue.

◆ IsBadLicense()

static IlBoolean IliSQLSession::IsBadLicense ( )

static

Returns IlTrue if the Data Access SQL license is invalid.

Returns: IlTrue if the Data Access SQL license is invalid.

◆ isConnected()

IlBoolean IliSQLSession::isConnected ( ) const

Returns IlTrue if the session is currently connected.

Returns: IlTrue if the session is currently connected.

◆ isForwardErrorToGlobalSink()

static IlBoolean IliSQLSession::isForwardErrorToGlobalSink ( )

static

Returns IlTrue if the error message are forwarded to the global error sink.

Returns: IlTrue if the error messages are forwarded to the global error sink. The default value is IlFalse.

◆ isInAsyncMode()

IlBoolean IliSQLSession::isInAsyncMode ( )

Returns IlTrue if the session is currently in asynchronous mode.

Initially, a session is not in asynchronous mode.

Returns: IlTrue if the session is currently in asynchronous mode.

◆ isPasswordSaved()

IlBoolean IliSQLSession::isPasswordSaved ( ) const

Returns IlTrue if the password is written along with the other parameters when the write() member function is called.

The default for this property is IlFalse.

Returns: IlTrue if the password is written along with the other parameters when the write() member function is called.

◆ isRegistered()

IlBoolean IliSQLSession::isRegistered ( ) const

Returns IlTrue if the session is registered.

Returns: IlTrue if the session is registered.

◆ IsSQLTraceEnabled()

static IlBoolean IliSQLSession::IsSQLTraceEnabled ( )

static

Returns IlTrue if the trace facility is currently enabled.

Returns: IlTrue if the trace facility is currently enabled.

◆ newCursor()

IliSQLCursor* IliSQLSession::newCursor ( )

Allocates and returns a cursor attached to the session object.

A cursor is required to submit SQL statements to the database. At any given point in time, a session may have a number of cursors in use (the maximum number of simultaneous cursors depends on the database driver). All work completed through these cursors, belongs to the same database transaction. The cursor returned by this member function can be used as long as it is needed. When it is no longer required, it should be returned to the session with the releaseCursor() member function. Note that all cursors attached to a session will be deleted without notice when the session is disconnected from the database.

Returns: A cursor attached to the session object or it returns 0 if the maximum number of cursors allowed has been reached, or if the session is not connected to a database.

◆ queryConnect()

IlBoolean IliSQLSession::queryConnect	(	IlvDisplay *	display,
		IlvAbstractView *	view,
		IliSQLQueryConnectFlag	flag = `IliSQLQueryIfNeeded`,
		IlBoolean	showName = `IlFalse`
	)

This member function is similar to the connect() member function, except that it attempts to connect to the effective session of this session.

Moreover, a dialog box will be opened so that the user can enter some of the parameters of the effective session that may be required to connect successfully.

Parameters

display	The display.
view	If not `0`, it designates the view over which the dialog box will be displayed.
flag	May take one of the following values: `IliSQLQueryPasswordOnly` `IliSQLQueryIfNeeded` `IliSQLQueryAlways` If the flag is set to `IliSQLQueryPasswordOnly`, and if the effective session is not already connected or cannot connect successfully, the user will be prompted for a password. A new attempt to connect will be made.

If the flag is set to IliSQLQueryIfNeeded, and if the effective session is not already connected or cannot connect successfully, the user will be prompted for a user name, a password, a database name and connection options (when these are applicable to the database driver in use). A new attempt to connect will be made.

If the flag is set to IliSQLQueryAlways, the effective session will be disconnected if it is already connected. The user will be prompted for a user name, a password, a database name, and connection options (when these are applicable to the database driver in use).

Parameters

showName If IlTrue, the user will also be prompted for a session name. A new attempt to connect will be made.

Returns: IlTrue if the effective session is eventually connected.

◆ quitAsyncMode()

IlBoolean IliSQLSession::quitAsyncMode ( )

Attempts to switch to synchronous mode.

Note that if there is an asynchronous call in progress, this member function will block until the call is completed.

Returns: IlTrue if successful.

◆ read()

void IliSQLSession::read ( IL_STDPREF istream & input )

Reads the definition of a session from an input stream.

Parameters

input The input stream.

◆ ReadMessageDatabase()

static void IliSQLSession::ReadMessageDatabase ( IlvDisplay * display )

static

Takes into account the translations for DbLink error messages that are currently in effect in the display message database.

It should be called after the dataccess/dblink.dbm message database file has been read by the display.

Parameters

display The display.

◆ readSynonymNames()

char** IliSQLSession::readSynonymNames	(	IlInt &	count,
		const char *	synOwner = `0`
	)

Returns the list of synonym names.

Parameters

count	returns the number of synonyms.
synOwner	the function will look for synonyms belonging to that database user.

Returns: an array that contains the name of synonyms.

◆ readTableDefinition()

IliSQLTableDef* IliSQLSession::readTableDefinition	(	IlvDisplay *	display,
		const char *	tableName,
		const char *	tableOwner = `0`,
		IlBoolean	isSynonym = `IlFalse`
	)

Returns the schema of one table.

Inspects the catalog of the database which the session is connected to, and looks for a table named tableName belonging to the user tableOwner. If such a table exists, its schema definition is read from the database catalog and an IliSQLTableDef object is allocated, and filled with this information. The member function then returns this object. If no such table is found in the database, 0 is returned. Note that ownership of the returned value is transferred to the caller that is responsible for its deletion.

Parameters

display	The display.
tableName	The table name.
tableOwner	The table owner. If `0`, belonging to the user of the session.
isSynonym	must be set to IlTrue if tableName and tableOwner are names of a synonym. In which case, the definition of the table referenced by the synonym is retrieved.

Returns: The schema.

◆ readTableNames()

char** IliSQLSession::readTableNames	(	IlInt &	count,
		const char *	tableOwner = `0`
	)

Reads the catalog of the database which the session is connected to, and returns an array of table names.

The returned array, and the character strings it contains, are allocated by the new[] operator and their ownership is transferred to the caller that is responsible for their deletion.

Parameters

count	The table count.
tableOwner	If `0`, or if it is an empty character string, all table names in the database are returned. Otherwise, tableOwner designates a database user, and this member function returns the names of all tables belonging to that user.

Returns: An array of table names.

◆ RegisterSession() [1/2]

static IlBoolean IliSQLSession::RegisterSession	(	const char *	sessionName,
		const char *	dbmsName,
		const char *	connectionParams
	)

static

Registers a new session.

Allocates a new session object defined by the parameters. This session will then be registered.

Parameters

sessionName	The session name.
dbmsName	The database name.
connectionParams	The connection parameters.

Returns: IlTrue if successful.

◆ RegisterSession() [2/2]

static IlBoolean IliSQLSession::RegisterSession ( IliSQLSession * sess )

static

Registers a session under its own name.

Once a session has been registered, it is not necessary to keep it locked. Instead the registering mechanism handles the locking of sessions, and a registered session will automatically be unlocked when the application exits.

Parameters

sess	The session.

Returns: IlTrue if the session can be registered and IlFalse if the session name is empty or if there is already a session registered under that name.

◆ releaseCursor()

void IliSQLSession::releaseCursor ( IliSQLCursor * curs )

Returns a cursor to the session object.

Any cursor obtained through the newCursor() member function should be returned to the session when it is no longer needed.

Parameters

curs	The cursor.

◆ rollback()

IlBoolean IliSQLSession::rollback ( )

Cancels any work in progress in the current transaction.

Returns: IlTrue if successful.

◆ savePassword()

void IliSQLSession::savePassword ( IlBoolean flag )

Specifies whether the password must be saved along with the other parameters, when the write() member function is called.

Parameters

flag	If `IlTrue` the password is written.

◆ setAsMoniker()

void IliSQLSession::setAsMoniker ( IlBoolean moniker )

Specifies whether this session is a moniker session.

Parameters

moniker If IlTrue, this session is specified to be a moniker session.

◆ setConnectionOptions()

void IliSQLSession::setConnectionOptions ( const char * opt )

Sets the connection options that will be used to locate the database server over the network.

This member function should not be called while the session is connected.

Parameters

opt	The options.

◆ setConnectionParams()

void IliSQLSession::setConnectionParams ( const char * params )

Parses the parameters according to the rules of the database driver being used and sets the user, password, database, and connection options properties accordingly.

This member function should not be called while the session is connected.

Parameters

params The parameters.

◆ setDatabaseName()

void IliSQLSession::setDatabaseName ( const char * name )

Sets the name of the database which the session will connect.

This member function should not be called while the session is connected.

Parameters

name	The name of the database.

◆ setDbmsName()

void IliSQLSession::setDbmsName ( const char * name )

Sets the name of the database driver.

This member function should not be called while the session is connected.

Parameters

name	The name of the database driver.

◆ SetNewDbmsFunction()

static void IliSQLSession::SetNewDbmsFunction ( IliSQLNewDbmsFunction fct )

static

Sets the function that will be used to create new Rogue Wave Views DBLink IldDbms objects, when required.

It is necessary to call this static member function at the beginning of the program execution. The set of supported databases in Rogue Wave Views Data Access depends on how the fct parameter has been set up.

For example, to ensure that support for ORACLE and for Informix databases is available, you should include the following code fragment with your main function:

#define ILDORACLE
#define ILDINFORMIX
#include <ildblink/dblink.h>
#include <ilviews/dataccess/dbms/session.h>
static IldDbms* ILVCALLBACK
NewDbms(const char* db, const char* param) {
return IldNewDbms(db, param);
}
int main() {
IliSQLSession::SetNewDbmsFunction(NewDbms);
...
return 0;
}

Here are the macro symbols that need to be defined according to the database used:

DB2: ILDDB2
ORACLE: ILDORACLE
INFORMIX: ILDINFORMIX
SYBASE: ILDCTSYBASE
ODBC: ILDODBC
OLEDB: ILDOLEDB
MSSQL: ILDMSSQL

Parameters

fct	The function.

◆ setPassword()

void IliSQLSession::setPassword ( const char * pwd )

Sets the password that will be used to log onto the remote database.

This member function should not be called while the session is connected.

Parameters

pwd	The password.

◆ setSessionName()

void IliSQLSession::setSessionName ( const char * name )

Sets the name property of the session.

Parameters

name	The session name.

◆ setSessionParams()

void IliSQLSession::setSessionParams ( const IliSQLSession * sess )

Overwrites the parameters of the session object with a copy of the session parameters of another session object.

Parameters

sess	Another session object.

◆ setTimeout()

void IliSQLSession::setTimeout ( short nsecs )

Sets the time-out.

The time-out indicates to the database library that an error should be raised if a subsequent call to the database server takes more than a given number of seconds. Note that not all database systems support this feature. (Oracle, for instance, does not. Calling this method has no effect when the session connects to an Oracle server.)

Parameters

nsecs The time-out (in seconds).

◆ SetTraceOptions()

static void IliSQLSession::SetTraceOptions ( const IliSQLTraceOptions & opt )

static

Sets the settings of the trace facility.

Parameters

opt	The settings.

◆ setUserName()

void IliSQLSession::setUserName ( const char * name )

Sets the name of the user account that will be used to log onto the remote database.

This member function should not be called while the session is connected.

Parameters

name	The user name.

◆ startTransaction()

IlBoolean IliSQLSession::startTransaction ( )

Starts a new transaction.

It should be called while there is no transaction in progress (that is, after the session has been connected, or after one of the commit() or rollback() member functions has been called).

Returns: IlTrue if successful.

◆ supportsAsyncMode()

IlBoolean IliSQLSession::supportsAsyncMode ( )

Returns IlTrue if the database system supports asynchronous mode.

Returns: IlTrue if the database system supports asynchronous mode.

◆ UnRegisterSession()

static void IliSQLSession::UnRegisterSession ( IliSQLSession * sess )

static

Unregisters a session.

Parameters

sess	The session. If it is indeed registered, it will first be removed from the registering mechanism, and then unlocked. So if you intend to use it after calling this static member function, you should lock it before calling the function.

◆ write()

void IliSQLSession::write ( IL_STDPREF ostream & output ) const

Writes the definition of a session to an output stream in a form suitable for reading back by the read() member function.

Parameters

output The output stream.

Public Member Functions

Static Public Member Functions

Additional Inherited Members

Detailed Description

Data accessors

Method accessors

Constructor & Destructor Documentation

◆ IliSQLSession()

Member Function Documentation

◆ cancelAsyncCall()

◆ commit()

◆ connect()

◆ ConnectToMessageDatabase()

◆ disconnect()

◆ emitDate()

◆ emitTime()

◆ EnableSQLTrace()

◆ enterAsyncMode()

◆ errorRaised()

◆ ForwardErrorToGlobalSink()

◆ getConnectionOptions()

◆ getConnectionParams()

◆ getDatabaseName()

◆ getDbmsName()

◆ GetDbmsNames()

◆ GetDefault()

◆ getEffectiveSQLSession()

◆ getErrorMessage()

◆ getHook()

◆ getPassword()

◆ GetRegisteredSession() [1/2]

◆ GetRegisteredSession() [2/2]

◆ GetRegisteredSessionsCount()

◆ getSessionName()

◆ GetTraceOptions()

◆ getUserName()

◆ hasSameParams()

◆ isAMoniker()

◆ isAsyncCallCompleted()

◆ IsBadLicense()

◆ isConnected()

◆ isForwardErrorToGlobalSink()

◆ isInAsyncMode()

◆ isPasswordSaved()

◆ isRegistered()

◆ IsSQLTraceEnabled()

◆ newCursor()

◆ queryConnect()

◆ quitAsyncMode()

◆ read()

◆ ReadMessageDatabase()

◆ readSynonymNames()

◆ readTableDefinition()

◆ readTableNames()

◆ RegisterSession() [1/2]

◆ RegisterSession() [2/2]

◆ releaseCursor()

◆ rollback()

◆ savePassword()

◆ setAsMoniker()

◆ setConnectionOptions()

◆ setConnectionParams()

◆ setDatabaseName()

◆ setDbmsName()

◆ SetNewDbmsFunction()

◆ setPassword()

◆ setSessionName()

◆ setSessionParams()

◆ setTimeout()

◆ SetTraceOptions()

◆ setUserName()

◆ startTransaction()

◆ supportsAsyncMode()

◆ UnRegisterSession()

◆ write()