IliSQLSession Class Reference

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 IliSQLSession &)
	This is the copy constructor of the IliSQLSession class.
	IliSQLSession (const char *dbmsName, const char *params)
	Initializes an IliSQLSession object with specific data. More...
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 (IlInt index)
	Returns a session in the registering mechanism. More...
static IliSQLSession *	GetRegisteredSession (const char *name)
	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 (IliSQLSession *sess)
	Registers a session under its own name. More...
static IlBoolean	RegisterSession (const char *sessionName, const char *dbmsName, const char *connectionParams)
	Registers a new session. 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

Accessors provide a scriptable and uniform way to inspect and modify an object by using its base class methods IlvValueInterface::queryValue(), IlvValueInterface::queryValues(), IlvValueInterface::changeValue(), IlvValueInterface::changeValues(). This class inherits the accessors of its superclass 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	(	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

IlBoolean IliSQLSession::cancelAsyncCall

(

)

Attempts to cancel any asynchronous call in progress.

Returns

IlTrue if successful.

IlBoolean IliSQLSession::commit

(

)

Commits any work pending in the current transaction.

Returns

IlTrue if successful.

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.

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.

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.

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.

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.

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.

IlBoolean IliSQLSession::enterAsyncMode

(

)

Attempts to switch to asynchronous mode.

Returns

IlTrue if successful.

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.

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.

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.

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.

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.

const char* IliSQLSession::getDbmsName

(

)

const

Returns the name of the database driver.

Returns

The name of the database driver.

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().

static IliSQLSession* IliSQLSession::GetDefault ( )

static

Returns a default session object.

Returns

A session.

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.

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.

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.

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.

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.

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.

static IlInt IliSQLSession::GetRegisteredSessionsCount ( )

static

Returns the number of registered sessions.

Returns

The count.

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.

static IliSQLTraceOptions IliSQLSession::GetTraceOptions ( )

static

Returns the current settings of the trace facility.

Returns

The current settings of the trace facility.

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.

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.

IlBoolean IliSQLSession::isAMoniker

(

)

const

Indicates if this session is a moniker session.

Returns

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

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.

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.

IlBoolean IliSQLSession::isConnected

(

)

const

Returns IlTrue if the session is currently connected.

Returns

IlTrue if the session is currently connected.

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.

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.

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.

IlBoolean IliSQLSession::isRegistered

(

)

const

Returns IlTrue if the session is registered.

Returns

IlTrue if the session is registered.

static IlBoolean IliSQLSession::IsSQLTraceEnabled ( )

static

Returns IlTrue if the trace facility is currently enabled.

Returns

IlTrue if the trace facility is currently enabled.

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.

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.

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.

void IliSQLSession::read

(

IL_STDPREF istream &

input

)

Reads the definition of a session from an input stream.

Parameters

input

The input stream.

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.

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.

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.

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.

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.

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.

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.

IlBoolean IliSQLSession::rollback

(

)

Cancels any work in progress in the current transaction.

Returns

IlTrue if successful.

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.

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.

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.

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.

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.

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.

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.

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.

void IliSQLSession::setSessionName

(

const char *

name

)

Sets the name property of the session.

Parameters

name	The session name.

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.

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

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

static

Sets the settings of the trace facility.

Parameters

opt	The settings.

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.

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.

IlBoolean IliSQLSession::supportsAsyncMode

(

)

Returns IlTrue if the database system supports asynchronous mode.

Returns

IlTrue if the database system supports asynchronous mode.

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.

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.