AdgConnection class | QSYS API Reference Guide

Estimated reading time: 8 minutes

The AdgConnection class controls database connection resources and allows them to be shared among DataGate objects in your program.

Namespace: ASNA.DataGate.Client Assembly: ASNA.QSys.DataGate.Client.dll

Inheritance: Object

Thread Safety

Any public static (Shared) members of this type are safe for multithreaded operations.

Any instance members are not guaranteed to be thread safe.

A single instance of AdgConnection should not be shared by multiple threads of an application, unless application access to the instance is protected by a mutual exclusion mechanism, or unpredictable results may occur.

For example, an ASP.NET application must take special care when using a shared instance of AdgConnection among multiple ASP.NET sessions.

As an alternative, consider using a separate instance of AdgConnection (optionally configured for connection pooling via the PoolingTimeout property of SourceProfile) in each ASP.NET session. Note also that other DG classes with properties and method parameters of type AdgConnection, such as FileAdapter, may employ the non-thread safe members of AdgConnection internally. By association, instance members of these classes are not guaranteed to be thread safe.

Remarks

An instance of AdgConnection represents a connection to a database server. The connection is initially in the Closed state, as reflected by the Stateproperty. Connection details are described by the SourceProfile property. Connection details are set in AdgConnection at construction and cannot be changed during the lifetime of the object.

Several Open methods are available for transitioning AdgConnection to the Open state. When an AdgConnection object is in the Open state, the values of certain properties reflect the state of a server-side “job”. Some job-oriented operations, such as commitment control, can be effected through AdgConnection methods.

An Open AdgConnection object may enter the Closed state via the Close method. Connections may also be closed via the IDispose.Dispose method. Note that it is the responsibility of the programmer to close database connections. If AdgConnection objects are garbage-collected in the Open state, the resulting state of the underlying connection resources (including network connections) is non-deterministic.

AdgConnection is used by other classes for specific functions such as record access and program call. DataGate objects may hold references to an AdgConnection instance, and those objects may assume that the AdgConnection object is in the Open state. When in the Closed state, the AdgConnection object must not be used by any object which references its database connection, or an exception may occur. Care should be taken not to call methods of DataGate objects which reference AdgConnection objects in the Closed state.

Constructors

Properties

Methods

Examples

Create an AdgConnection

Shows how to new an AdgConnection using a Database Source Profile Name.

    IDataGateConfig dgConfig;

    public void PrepareStore(params string[] configJsonFiles) 
    {
        ConfigurationBuilder builder = new ConfigurationBuilder();
        builder.AddJsonFile(AsnaConfigHelper.DefaultConfigFilePath);
        foreach (var configFile in configJsonFiles)
            builder.AddJsonFile(configFile);
        IAsnaConfig config = new AsnaConfig(builder.Build());
        dgConfig = config.DataGate;
    }

    private AdgConnection createAdgConnection(string dbName)
    {
        SourceProfile sourceProfile = dgConfig.ResolveSourceName(dbName);
        AdgConnection dbConnection = new AdgConnection(sourceProfile);
        return dbConnection;
    }


    public void start()
    {
        PrepareStore(AsnaConfigHelper.DefaultConfigFilePath, "./appsetting.json");
        . . . 
        AdgConnection dbConnection = createAdgConnection("MyDatabaseName");
        dbConnection.Open();
        . . .
        . . .
        //Disconnects from the dataBase by closing the connection.
        dbConnection.Close();
    }

Open a Database File

See Create an AdgConnection

    private FileAdapter openCustomerFile(AdgConnection dbConnection, out AdgDataSet dataSet)
    {
        /* Here we need to use an AdgConnection to open the Customer File.
          We first check to make sure that the AdgConnection has 
          been initialized and that the connection has been made to
          avoid throwing an exception. */

        FileAdapter dbFile =  null;
        dataSet = null;
        if (dbConnection != null && dbConnection.State == ConnectionState.Open)
        {
          dbFile = new FileAdapter(dbConnection, "MyLibrary/CustMast");
          dbFile.OpenAttributes.FileLocks = FileLocks.Auto;
          dbFile.AccessMode = AccessMode.RWCD;
          dbFile.OpenNewAdgDataSet(out dataSet);
          return dbFile;
        }

        //If the AdgConnection was not ready, you cannot immediately
        //open the file, so take alternative action here.
        . . . 
    }

    public void start()
    {
        PrepareStore(AsnaConfigHelper.DefaultConfigFilePath, "./appsetting.json");
        . . . 
        AdgConnection dbConnection = createAdgConnection("MyDatabaseName");
        dbConnection.Open();

        AdgDataSet dataSet;       
        FileAdapter dbFile = openCustomerFile(dbConnection, out dataSet);
        . . .
        . . .
        dbFile.Close();

        //Disconnects from the dataBase by closing the connection.
        dbConnection.Close();
    }