Accessors for class IliSQLSession

Properties

connectionOptions
connectionParams
databaseName
dbmsName
effectiveSQLSession
isAMoniker
password
passwordSaved
userName

Methods

cancelAsyncCall
commit
connect
disconnect
enterAsyncMode
getErrorMessage
isAsyncCallCompleted
isConnected
isErrorRaised
isInAsyncMode
isRegistered
newCursor
queryConnect
quitAsyncMode
rollback
setTimeout
supportsAsyncMode

Description

Variables

IliSQLSession.sessionsCount
IliSQLSession.traceConnects
IliSQLSession.traceCursors
IliSQLSession.traceSQL

Functions

IliSQLSession.getSession
IliSQLSession.getSessionAt

Verbose: 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 the IliSQLCursor class.

Transactions

A transaction is a collection of related updates submitted to a database. To create a transaction through a session, you obtain one or more cursors from the session that are 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 method, or cancel it with the rollback method. From then on, you can start a new series of updates to create a new transaction or disconnect the session if you are done with it.
The transaction concept allows you to group a collection of related updates to the database so that they will either succeed collectively, or fail collectively. You can then assume that the database will never be left in a state where some of the updates have succeeded and others have failed.

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.

Asynchronous Mode

Asynchronous mode is a special mode that affects the following methods of the IliSQLCursor class: select, execute, and fetchNext.
These methods 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's work. In asynchronous mode, these methods do not block until completion. Instead, they may return prematurely in order to allow the calling thread to proceed with other tasks. Then, it 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 that apply to asynchronous mode. For example, Oracle 7.x has the following constraint. There can be at most one non-complete asynchronous call among all cursors obtained through the session. This means that you cannot execute asynchronously and in parallel two SQL statements through two cursors that belong to the same session.

Type Name Description Notes

String connectionOptions Contains additional information used to connect to the remote database server. The precise meaning of this property is database system dependent:

INFORMIX: The name of the INFORMIX server
INGRES: Not applicable
ODBC: Not applicable
ORACLE: The SQL*NET connection string
SYBASE: The name of the SYBASE server

String connectionParams Contains the user name, the password, the database name, and the connection options packaged into one character string. The format of the value depends on the database driver being used:

INFORMIX: <user>/<password>/<database>@<options>
INGRES: <user>/<password>/<database>/<options>
ODBC: <database>/<user>/<password>
ORACLE: <user>/<password>@<options>
SYBASE: <database>

String databaseName Contains the name of the remote database instance to which this session will connect. (The database name should not be confused with the database driver name contained in property dbmsName). The precise meaning of this property is database system dependent:

INFORMIX: The name of the database
INGRES: The name of the database
ODBC: The name of the ODBC data source
ORACLE: Not applicable
SYBASE: The name of the database

String dbmsName Contains the name of the database driver that is used to connect to the remote database. It is one of the following:

informix
informix72
informix9
ingres
oracle
oracle73
oracle8
sybase

IliSQLSession effectiveSQLSession Contains the session that should be used instead of this session object. If this session is a moniker session then the effectiveSession property contains the corresponding registered session. Otherwise, it contains the session itself. read-only

Boolean isAMoniker Contains true if the session object is a moniker session. In such a case, the effectiveSQLSession property will contain the corresponding registered session (if available). read-only

String password Contains the password that is used to log onto the remote database.

Boolean passwordSaved Contains true if the password is saved along with this object in .ilv and .iva data files. If this property is false, the end user will be prompted for the password at connect time.

String userName Contains the name of the user account that is used to log onto the remote database.

Boolean cancelAsyncCall() Attempts to cancel any asynchronous call in progress that is not completed and returns true if successful.

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

Boolean connect() Attempts to connect to the remote database specified by the parameters of the session. This method returns true if successful, or false if the session was already connected or cannot connect successfully. In this case, an error message describing the cause of the failure to connect can be retrieved with the getErrorMessage method.

Boolean disconnect() If the session object is currently connected to a remote database, this method disconnects it from the database and return true. Otherwise, false is returned. Any cursors obtained through this session object become invalid after a successful call to disconnect.

Boolean enterAsyncMode() Attempts to switch to asynchronous mode and returns true if successful.

IliErrorMessage getErrorMessage() Returns the error message caused by the failure of last method call, or null if no such failure occurred.

Boolean isAsyncCallCompleted() Returns true if there are no noncompleted asynchronous calls in progress.

Boolean isConnected() Returns true if the session is currently connected to remote database server.

Boolean isErrorRaised() Returns true if the last method call failed.

Boolean isInAsyncMode() Returns true if the session is currently in asynchronous mode. Initially, a session is not in asynchronous mode.

Boolean isRegistered() Returns true if the session is registered.

IliSQLCursor newCursor() Allocates and returns a cursor attached to the session object, or it returns null if the maximum number of cursors allowed has been reached or if the session is not connected to a database. Note that all cursors attached to this session object will become invalid without notice when the session is disconnected from the database.

Boolean queryConnect(IlvAbstractView view, IliSQLQueryConnectFlag flags) This method attempts to connect the effective session of this session object. 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. The view parameter designates the view over which the dialog box will be displayed. The flags parameter can be one of the following string values:

IliSQLQueryPasswordOnly
IliSQLQueryIfNeeded
IliSQLQueryAlways
When the flags parameter is set to IliSQLQueryPasswordOnly, if the effective session is not already connected or cannot connect successfully, the user will be prompted for a password and a new attempt to connect will be made.
When the flags parameter is set to IliSQLQueryIfNeeded, 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 then be made.
If the flags parameter is set to IliSQLQueryAlways, the effective session will be disconnected if 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). An attempt to connect will then be made.

Boolean quitAsyncMode() Attempts to switch to synchronous mode and returns true if successful. Note that if there is a noncompleted asynchronous call in progress, this member function will block until the call is completed.

Boolean rollback() Cancels any work pending in the current transaction.

Void setTimeout(Int nSec) Sets the time-out to nSec seconds. 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.)

Boolean supportsAsyncMode() Returns true if the database system supports asynchronous mode.

Int IliSQLSession Contains the number of registered sessions. See the IliSQLSession.getSessionAt function. read-only

Callback Boolean Contains true if each connect and each disconnect event should be traced.

Callback Boolean Contains true if each cursor allocation and de-allocation event should be traced.

Callback Boolean Contains true if each SQL statement that is submitted should be traced

IliSQLSession IliSQLSession Returns the registered session named name. Returns null if no such session has been registered. Note that since registered sessions become properties of the IliSQLSession object, they can be directly accessed as such as in:

var session = IliSQLSession.MAIN;

IliSQLSession IliSQLSession Returns the registered session at position index or null if index is out of bounds. The index parameter must be >= 0 and < IliSQLSession.sessionsCount.

Type	Name	Description	Notes
`String`	`connectionOptions`	Contains additional information used to connect to the remote database server. The precise meaning of this property is database system dependent: INFORMIX: The name of the INFORMIX server INGRES: Not applicable ODBC: Not applicable ORACLE: The SQL*NET connection string SYBASE: The name of the SYBASE server
`String`	`connectionParams`	Contains the user name, the password, the database name, and the connection options packaged into one character string. The format of the value depends on the database driver being used: INFORMIX: `<user>/<password>/<database>@<options>` INGRES: `<user>/<password>/<database>/<options>` ODBC: `<database>/<user>/<password>` ORACLE: `<user>/<password>@<options>` SYBASE: `<database>`
`String`	`databaseName`	Contains the name of the remote database instance to which this session will connect. (The database name should not be confused with the database driver name contained in property `dbmsName`). The precise meaning of this property is database system dependent: INFORMIX: The name of the database INGRES: The name of the database ODBC: The name of the ODBC data source ORACLE: Not applicable SYBASE: The name of the database
`String`	`dbmsName`	Contains the name of the database driver that is used to connect to the remote database. It is one of the following: `informix` `informix72` `informix9` `ingres` `oracle` `oracle73` `oracle8` `sybase`
`IliSQLSession`	`effectiveSQLSession`	Contains the session that should be used instead of this session object. If this session is a moniker session then the `effectiveSession` property contains the corresponding registered session. Otherwise, it contains the session itself.	read-only
`Boolean`	`isAMoniker`	Contains `true` if the session object is a moniker session. In such a case, the `effectiveSQLSession` property will contain the corresponding registered session (if available).	read-only
`String`	`password`	Contains the password that is used to log onto the remote database.
`Boolean`	`passwordSaved`	Contains `true` if the password is saved along with this object in `.ilv` and `.iva` data files. If this property is `false`, the end user will be prompted for the password at connect time.
`String`	`userName`	Contains the name of the user account that is used to log onto the remote database.
`Boolean`	`cancelAsyncCall()`	Attempts to cancel any asynchronous call in progress that is not completed and returns `true` if successful.
`Boolean`	`commit()`	Commits any work pending in the current transaction.
`Boolean`	`connect()`	Attempts to connect to the remote database specified by the parameters of the session. This method returns `true` if successful, or `false` if the session was already connected or cannot connect successfully. In this case, an error message describing the cause of the failure to connect can be retrieved with the `getErrorMessage` method.
`Boolean`	`disconnect()`	If the session object is currently connected to a remote database, this method disconnects it from the database and return `true`. Otherwise, `false` is returned. Any cursors obtained through this session object become invalid after a successful call to disconnect.
`Boolean`	`enterAsyncMode()`	Attempts to switch to asynchronous mode and returns `true` if successful.
`IliErrorMessage`	`getErrorMessage()`	Returns the error message caused by the failure of last method call, or `null` if no such failure occurred.
`Boolean`	`isAsyncCallCompleted()`	Returns `true` if there are no noncompleted asynchronous calls in progress.
`Boolean`	`isConnected()`	Returns `true` if the session is currently connected to remote database server.
`Boolean`	`isErrorRaised()`	Returns `true` if the last method call failed.
`Boolean`	`isInAsyncMode()`	Returns `true` if the session is currently in asynchronous mode. Initially, a session is not in asynchronous mode.
`Boolean`	`isRegistered()`	Returns `true` if the session is registered.
`IliSQLCursor`	`newCursor()`	Allocates and returns a cursor attached to the session object, or it returns `null` if the maximum number of cursors allowed has been reached or if the session is not connected to a database. Note that all cursors attached to this session object will become invalid without notice when the session is disconnected from the database.
`Boolean`	`queryConnect(IlvAbstractView view, IliSQLQueryConnectFlag flags)`	This method attempts to connect the effective session of this session object. 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. The `view` parameter designates the view over which the dialog box will be displayed. The `flags` parameter can be one of the following string values: `IliSQLQueryPasswordOnly` `IliSQLQueryIfNeeded` `IliSQLQueryAlways` When the `flags` parameter is set to `IliSQLQueryPasswordOnly`, if the effective session is not already connected or cannot connect successfully, the user will be prompted for a password and a new attempt to connect will be made. When the `flags` parameter is set to `IliSQLQueryIfNeeded`, 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 then be made. If the `flags` parameter is set to `IliSQLQueryAlways`, the effective session will be disconnected if 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). An attempt to connect will then be made.
`Boolean`	`quitAsyncMode()`	Attempts to switch to synchronous mode and returns true if successful. Note that if there is a noncompleted asynchronous call in progress, this member function will block until the call is completed.
`Boolean`	`rollback()`	Cancels any work pending in the current transaction.
`Void`	`setTimeout(Int nSec)`	Sets the time-out to `nSec` seconds. 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.)
`Boolean`	`supportsAsyncMode()`	Returns `true` if the database system supports asynchronous mode.
`Int`	`IliSQLSession`	Contains the number of registered sessions. See the `IliSQLSession.getSessionAt` function.	read-only
`Callback`	`Boolean`	Contains `true` if each connect and each disconnect event should be traced.
`Callback`	`Boolean`	Contains `true` if each cursor allocation and de-allocation event should be traced.
`Callback`	`Boolean`	Contains `true` if each SQL statement that is submitted should be traced
`IliSQLSession`	`IliSQLSession`	Returns the registered session named `name`. Returns `null` if no such session has been registered. Note that since registered sessions become properties of the `IliSQLSession` object, they can be directly accessed as such as in: var session = IliSQLSession.MAIN;
`IliSQLSession`	`IliSQLSession`	Returns the registered session at position `index` or `null` if `index` is out of bounds. The `index` parameter must be `>= 0` and `< IliSQLSession.sessionsCount`.