How You Can Open a New Database Session
Before you can open a session other than a frame's starting session, you must create the DBSessionObject object for the new session by declaring a global or local reference variable of type DBSessionObject.
Declaring the variable globally lets you open the session represented by the variable in any frame of the application. If you declare a local variable, you can reference that variable in the frame in which the variable is declared or pass it to a frame or procedure called by that frame. You can open the session only within the frame in which you declared it or in subsequent frames or procedures called by that frame.
The DBSessionObject system class provides the following two methods for opening a new connection to a database:
• The Connect method
• The OpenNew Connection method
Connect Method
Use this method to start a session that is different from any of the currently open sessions, for example, a session with a different database or a different set of DBMS flags.
The syntax is:
integer = DBSessionObject.Connect(database = varchar(256),[flags = varchar(256)])
The DBSessionObject object must not be open already (the state must be DS_DISCONNECTED) when you invoke this method. You can specify any database, including one to which the application already is connected.
flags
Lets you define the runtime environment for the session. For example, you can open a session as another user by specifying the -u flag.
If the Connect method succeeds in opening the connection, it returns ER_OK. If it does not succeed, it returns an error code.
OpenNew Connection Method
This method opens a connection that is identical to a previously opened connection. Use this method to have two or more concurrent transactions against the same database with the same parameter settings.
The syntax is:
DBSessionObject = DBSessionObject.OpenNewConnection()
The DBSessionObject object on which the method is invoked must represent an open session, because this method uses the existing session as a template for the new session.
When the method completes, it returns a DBSessionObject object representing the new session. The new session accesses the same database and runs under the same flags as the existing session. If the method fails, it returns null.
For more information about these statements, see the Language Reference Guide.
Examples of Opening New Database Connections
The following examples show various ways to open a new database connection.
Using the OpenNewConnection method in the initialize block
The following initialize block locally declares the reference variable second_session for the DBSessionObject and uses the OpenNewConnection method to open a database session that is identical to the one for the calling frame:
initialize (
second_session = DBSessionObject;) =
begin
second_session =
CurFrame.DBSession.OpenNewConnection();
...
end;
Using the Connect method in the initialize block
The following initialize block uses the Connect method to open a connection to the videos database, specifying the user as marg and setting the arithmetic-handling mode of the session. The statement uses a globally-declared reference variable third_session for the DBSessionObject:
initialize (
status = integer;) =
begin
status = third_session.Connect(database =
'videos',
flags = '-umarg -xw');
end;
Using the OpenNewConnection method in a frame-invoking statement
The following openframe statement in a calling frame establishes a new, identical database session for the called frame (newframe):
newframe = openframe newframe with dbsession =
CurFrame.DBSession.OpenNewConnection();