Classes Class DacSession()

Class DacSession() Professional

Class function of the DacSession class.

Description

The DacSession class is used for session management. In addition to establishing and closing down connections to a server, the class also offers functionality to invoke a transaction processing system, if supported by the server.

The successful connection to a server marks the beginning of a session, which ends when the client application disconnects. While the session is open, all database operations triggered by database functions and commands such as USE database or DbCreate() are forwarded to the server by a DacSession object. The database operations are then performed by the server rather than by the client application. A DacSession object in turn receives the response from the server and returns it to the client application. This way, data sources residing on a server can be accessed as if they were stored on the computer running the application (client station).

An application may create multiple DacSession objects, and each object can handle a connection to a different server. In this case, the default session becomes important. Many functions and commands of the Xbase++ language do not allow to specify the server which is to perform a certain database operation. When the client application executes such a function or command, it is the DacSession object defined as the default session which accepts the request and forwards it to the server it is connected to. Also see the methods :setDefault() and :getDefault() for further information.

The default session has thread-local scope. This means that each thread in a multi-threaded program may have a different DacSession object defined as the default session. As a result, the database operations corresponding to a DbCreate() function call for example, could be performed by different servers if DbCreate() is used in threads with a different default session set.

Class methods
:new()
Creates a DacSession object and connects it to a server.
:getDefault()
Retrieves the default DacSession object of the current thread.
:sessionList()
Retrieves all active sessions.
Connection
:connect()
Establishes a connection to a server.
:disconnect()
Disconnects the session from the server.
:getConnectionHandle()
Retrieves the connection handle.
:getConnectionString()
Retrieves the connection string.
:isConnected()
Checks if a connection is established.
SQL command execution
:executeQuery()
Executes an SQL SELECT statement.
:executeStatement()
Executes arbitrary SQL statements.
Error information
:getLastError()
Returns the numeric value of the last error.
:getLastMessage()
Returns the message text associated with the last operation.
Property access & manipulation
:setProperty()
Retrieves or sets properties of the server
Session Management
:isUsed()
Check if the session is used by one or more work areas
:isDefault()
Checks if the session is the default session
:setDefault()
Changes the default session of the current thread
Transaction
:beginTransaction()
Begins a transaction.
:commitTransaction()
Commits a transaction.
:inTransaction()
Determines whether a transaction is currently being processed.
:rollbackTransaction()
Aborts a transaction.
Examples
Connecting to the PostgreSQL server 

#include "dac.ch" 

PROCEDURE Main 

LOCAL cConnect, oSession 

// Ensure that PostgreSQL DatabaseEngine is loaded 
// and set as the default dbe 
IF !Dbeload( "PGDBE", .F. ) 
  Alert( "PGDBE could not be loaded!" ) 
ENDIF 
DbeSetDefault( "PGDBE" ) 

/* Connect to server:myserver and database:crm_system 
 * as user:uid with password:pwd 
 */ 
cConnect := "DBE=PGDBE;SERVER=myserver;DB=crm_system;" 
cConnect += "UID=username;PWD=password;" 
oSession := DacSession():New( cConnect ) 

// Test for connection success 
IF .NOT. oSession:isConnected() 
  ? "Error code :", oSession:getLastError() 
  ? "Description:", oSession:getLastMessage() 
ELSE 
  ? "Connection to server established." 
ENDIF 

// Your data access code goes here... 

oSession:disconnect() 

RETURN
Connecting to the Advantage Database Server 

#include "dac.ch" 

PROCEDURE Main 

LOCAL cConnect, oSession 

// Ensure that ADS DatabaseEngine is loaded and 
// set as the default dbe 
IF !Dbeload( "ADSDBE", .F. ) 
  Alert( "ADSDBE could not be loaded!" ) 
ENDIF 
DbeSetDefault( "ADSDBE" ) 

/* Connect to server:lichtenstein and share:roy01 
 */ 
cConnect := "DBE=ADSDBE;SERVER=\\LICHTENSTEIN\ROY01" 
oSession := DacSession():New( cConnect ) 

// Test for connection success 
IF .NOT. oSession:isConnected() 
  ? "Error code :", oSession:getLastError() 
  ? "Description:", oSession:getLastMessage() 
ELSE 
  ? "Connection to server established." 
ENDIF 

// Your data access code goes here... 

oSession:disconnect() 

RETURN
Connecting to Visual FoxPro Database Container (DBC) 

#include "dac.ch" 

PROCEDURE Main 

LOCAL cConnect, oSession 

// Ensure that ODBC DatabaseEngine is loaded 
// and set as the default dbe 
IF !Dbeload( "ODBCDBE", .F. ) 
  Alert( "ODBCDBE could not be loaded!" ) 
ENDIF 
DbeSetDefault( "ODBCDBE" ) 

/* Connect to DBC as defined by SOURCEDB; 
 * use DELETED records, make visible in 
 * shared mode and use collation table 
 * "machine". 
 */ 
cConnect := "DBE=ODBCDBE;DRIVER={Microsoft Visual FoxPro Driver};" 
cConnect += "SOURCETYPE=DBC;SOURCEDB=c:\myvfp.dbc;Exclusive=No;" 
cConnect += "NULL=no;COLLATE=machine;BACKGROUNDFETCH=no;DELETED=no;" 
oSession := DacSession():New( cConnect ) 

// Test for connection success 
IF .NOT. oSession:isConnected() 
  ? "Error code :", oSession:getLastError() 
  ? "Description:", oSession:getLastMessage() 
ELSE 
  ? "Connection to server established." 
ENDIF 

// Your data access code goes here... 

oSession:disconnect() 

RETURN
Connecting to a ODBC DSN datasource 

#include "dac.ch" 

PROCEDURE Main 

LOCAL cConnect, oSession 

// Ensure that ODBC DatabaseEngine is loaded 
// and set as the default dbe 
IF !Dbeload( "ODBCDBE", .F. ) 
  Alert( "ODBCDBE could not be loaded!" ) 
ENDIF 
DbeSetDefault( "ODBCDBE" ) 

/* Connect to DSN:crm_system as 
 * username:uid with password:uid 
 * To set up a DSN (DataSoureName), use the 
 * ODBC Admin or Midex 
 */ 
cConnect := "DBE=ODBCDBE;DSN=crm_system;UID=username;PWD=password" 
oSession := DacSession():New( cConnect ) 

// Test for connection success 
IF .NOT. oSession:isConnected() 
  ? "Error code :", oSession:getLastError() 
  ? "Description:", oSession:getLastMessage() 
ELSE 
  ? "Connection to server established." 
ENDIF 

// Your data access code goes here... 

oSession:disconnect() 

RETURN
Connecting to a ODBC DRIVER datasource 

#include "dac.ch" 

PROCEDURE Main 

LOCAL cConnect, oSession 

// Ensure that ODBC DatabaseEngine is loaded 
// and set as the default dbe 
IF !Dbeload( "ODBCDBE", .F. ) 
  Alert( "ODBCDBE could not be loaded!" ) 
ENDIF 
DbeSetDefault( "ODBCDBE" ) 

/* Connect using the ODBC driver:DRIVER to 
 * the server:SERVER and the database:DATABASE 
 * using the given uid:username and pwd:password. 
 */ 
cConnect := "DBE=ODBCDBE;DRIVER=SQL Server;" 
cConnect += "SERVER=myserver;DATABASE=crm_system;UID=username;PWD=password;" 
oSession := DacSession():New( cConnect ) 

// Test for connection success 
IF .NOT. oSession:isConnected() 
  ? "Error code :", oSession:getLastError() 
  ? "Description:", oSession:getLastMessage() 
ELSE 
  ? "Connection to server established." 
ENDIF 

// Your data access code goes here... 

oSession:disconnect() 

RETURN
Feedback

If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.