Skip to content

Basic cConnection Class Usage

At the simplest level, managed connections consist of:

  1. Create a Connections INI file (using the Studio’s Manage Connections dialog).
  2. Configure your tables to use managed connections (using the Studio’s Connection Wizard).
  3. Add a few lines of standard code to your application:
  4. Use the cConnection package.
  5. Create a cConnection object and place it above or inside your cApplication object.
  6. Add a login encryption object package and a database login dialog package inside or above the cConnection object.
  7. Compile and run your application. The cApplication object will automatically register and log in all managed connections.
Use cConnection.pkg

Object oApplication is a cApplication
    Set psProduct to "DataFlex Examples"

    Object oConnection is a cConnection
        Set pbLoginOnOpen to False
        Use LoginEncryption.pkg
        Use DatabaseLoginDialog.dg
    End_Object
End_Object

pbAutoConnect and AutoConnect

After the cApplication object successfully opens a workspace, it sends the message AutoConnect to the cConnection object (only if the cConnection object is defined). The cConnection AutoConnect method checks if the pbAutoConnect property is true, which it is by default. When true, AutoConnect registers all connections by sending RegisterAllConnections and logs in to all connections by sending LoginAll. If either of these messages fail, the application is aborted.

The AutoConnect method can be augmented to customize this process.

pbLoginOnOpen

The pbLoginOnOpen property determines if the DataFlex Open command should attempt a login if the server is not already logged in. The default value is true, which maintains legacy behaviors. We suggest you set this to false. This enforces a more standard SQL mechanism, where you first log in to a database server and then you use tables within that server.

ghoConnection Handle

Typically, there will be a single global cConnection object. When the object is created, the system global variable ghoConnection is set to its object handle. This allows other parts of the framework to communicate with the cConnection object without knowing its name and location. Developers should use this handle when communicating with the cConnection object.

Because a global handle is used, it does not really matter where the cConnection object is located, as long as it is created before it is used. As a general rule, it should be created before or inside your cApplication object.

Embedded SQL and cConnection

Using Connection IDs makes it easier to use Embedded SQL (ESQL). Once a connection is created and logged into, you may obtain an SQL connection handle by calling SQLConnectionId and passing the connection ID. This lets you create SQL statements without having to worry about connection server strings and logins.

Get SQLConnectionId of ghoConnection "ID1" to hoConnect
Get SQLOpen of hoConnect to hoStmt
Send SQLExecDirect of hoStmt "select * from salesp"
Get SQLFetchResultsetValues of hoStmt to Mydata
Send SQLClose of hoStmt
Send SQLDisconnect of hoConnect

Note that the connection must be registered and logged into before it can be used.

In addition to SQLConnectionId, the message SQLConnectionByTable may be used to create a connection handle for the connection being used by an opened table.

Previous Topic

Logins, Table Opens and Connection IDs

Next Topic

Advanced cConnection Class Usage