AdgConnection class | QSYS API Reference Guide

Estimated reading time: 24 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.

Constructors

AdgConnection(SourceProfile)

Initializes a new instance of the AdgConnection class with the specified SourceProfile.

AdgConnection(SourceProfile)

Parameters

AdgConnection(SourceProfile, IExchange5250)

Initializes a new instance of the AdgConnection class with the specified SourceProfile and IExchange5250.

AdgConnection(SourceProfile, IExchange5250)

Parameters

Properties

Methods

IAdgTransaction BeginAutoTransaction(TransactionLevel tl, string Options)

Begins an automatic transaction with the specified transaction level and options.

Remarks

This method begins a new automatic transaction with the specified transaction level and options.An automatic transaction is a transaction that is automatically committed or rolled back by the system.The transaction level determines the isolation level of the transaction.The options parameter can be used to specify additional options for the transaction.This method calls the BeginAutoTransaction method with an empty string for the name parameter, meaning the transaction will not have a name.

IAdgTransaction BeginAutoTransaction(TransactionLevel tl, string Options)

Parameters

Returns

IAdgTransaction BeginAutoTransaction(string Name, string Options)

Begins an automatic transaction with the specified name and options.

Remarks

This method begins a new automatic transaction with the specified name and options.An automatic transaction is a transaction that is automatically committed or rolled back by the system.The transaction level for this method is set to Medium by default.The name parameter can be used to specify a name for the transaction.The options parameter can be used to specify additional options for the transaction.

IAdgTransaction BeginAutoTransaction(string Name, string Options)

Parameters

Returns

IAdgTransaction BeginAutoTransaction(TransactionLevel tl, string Name, string Options)

Begins an automatic transaction with the specified transaction level, name, and options.

Remarks

This method begins a new automatic transaction with the specified transaction level, name, and options.An automatic transaction is a transaction that is automatically committed or rolled back by the system.The transaction level determines the isolation level of the transaction.The name parameter can be used to specify a name for the transaction.The options parameter can be used to specify additional options for the transaction.The transaction attributes are set to CommitAndRestart and RollbackAndRestart, meaning that if the transaction is committed or rolled back, it will automatically restart.

IAdgTransaction BeginAutoTransaction(TransactionLevel tl, string Name, string Options)

Parameters

Returns

IAdgTransaction BeginTransaction(TransactionLevel tl)

Begins a transaction with the specified transaction level.

Remarks

This method begins a new transaction with the specified transaction level.The transaction level determines the isolation level of the transaction.This method calls the BeginTransaction method with an empty string for the name parameter, meaning the transaction will not have a name.

IAdgTransaction BeginTransaction(TransactionLevel tl)

Parameters

Returns

IAdgTransaction BeginTransaction(string Name)

Begins a transaction with the specified name.

Remarks

This method begins a new transaction with the specified name.The transaction level for this method is set to Medium by default.The name parameter can be used to specify a name for the transaction.

IAdgTransaction BeginTransaction(string Name)

Parameters

Returns

IAdgTransaction BeginTransaction(TransactionLevel tl, string Name)

Begins a transaction with the specified transaction level and name.

Remarks

This method begins a new transaction with the specified transaction level and name.The transaction level determines the isolation level of the transaction.The name parameter can be used to specify a name for the transaction.This method calls the BeginTransaction method with an empty string for the options parameter, meaning the transaction will not have any additional options.

IAdgTransaction BeginTransaction(TransactionLevel tl, string Name)

Parameters

Returns

IAdgTransaction BeginTransaction(TransactionLevel tl, string Name, string Options)

Begins a transaction with the specified transaction level, name, and options.

Remarks

This method begins a new transaction with the specified transaction level, name, and options.The transaction level determines the isolation level of the transaction.The name parameter can be used to specify a name for the transaction.The options parameter can be used to specify additional options for the transaction.The transaction attributes are set to None, meaning that the transaction will not automatically restart if it is committed or rolled back.A new AdgTransaction object is created with the specified parameters and returned.

IAdgTransaction BeginTransaction(TransactionLevel tl, string Name, string Options)

Parameters

Returns

object Clone()

Creates a new AdgConnection that is a copy of the current instance.

Remarks

This method creates a new AdgConnection that is a copy of the current instance.It first gets a copy of the SourceProfile of the current connection.Then it creates a new AdgConnection with the copied SourceProfile.If the current connection is open, it also opens the new connection.The new connection is then returned.

object Clone()

void Close()

Closes the connection to the database.

Remarks

This method closes the connection by calling the Dispose method. The Dispose method releases all resources used by the AdgConnection, including the underlying database connection. After the connection is closed, it cannot be reopened. To open a new connection, you need to create a new AdgConnection instance.

void Close()

void Dispose()

Releases all resources used by the AdgConnection.

Remarks

This method disposes the AdgConnection by calling the Dispose method with the argument true. The Dispose method releases all resources used by the AdgConnection, including the underlying database connection. After the connection is disposed, it cannot be used again. The GC.SuppressFinalize(this) call prevents the garbage collector from calling the finalizer if it was overridden, which could have also disposed the object. This is done for performance reasons, since the object has already been disposed.

void Dispose()

void Dispose(bool isDisposing)

Releases the resources used by the AdgConnection.

Remarks

This method is called by the public Dispose() method and the Finalize method. Dispose() invokes the protected Dispose() method with the isDisposing parameter set to true. Finalize invokes Dispose with isDisposing set to false.When the isDisposing parameter is true, this method releases all resources held by any managed objects that this AdgConnection references. This method invokes the Dispose() method of each referenced object.The method first checks if the connection is open and if certain conditions are met (SourceProfile.PoolingTimeout is not zero, m_exchange5250 is null, and SourceProfile is not an SQL client platform). If these conditions are met, it logs the closure and disconnects the connection from the ConnectionPooler instance.If the SourceProvider is not null, it logs the permanent disconnection and closes the SourceProvider. Finally, it sets the SourceProvider to null.Note: Because the Dispose method is called twice (once by the public Dispose method and once by the finalizer), this method checks the isDisposing parameter to make sure it doesn’t execute certain code twice.

void Dispose(bool isDisposing)

Parameters

bool Equals(object obj)

Determines whether the current AdgConnection instance is equal to the specified object.

Remarks

This method checks if the specified object is an AdgConnection and if its SourceProfile is equal to the SourceProfile of the current instance.The SourceProfile is a property that contains the configuration settings for the connection, such as the database name, server name, and other connection parameters.If the specified object is not an AdgConnection or if its SourceProfile is different from the SourceProfile of the current instance, the method returns false.

bool Equals(object obj)

Parameters

Returns

DatabaseAttributes GetDatabaseAttributes()

Gets the attributes of the database.

Remarks

This method retrieves the attributes of the database from the SourceProvider if the connection is open.The attributes include information about the database such as its name, version, and other metadata.If the connection is not open, it throws an ApplicationException.

DatabaseAttributes GetDatabaseAttributes()

int GetDeviceCodePageID()

Gets the device code page ID.

Remarks

This method retrieves the device code page ID from the DataLinkSource if the connection is open.The device code page ID is used to determine the character encoding for the connection.If the connection is not open, it throws an ApplicationException.

int GetDeviceCodePageID()

int GetHashCode()

Serves as the default hash function.

Remarks

This method overrides the base GetHashCode method and provides a hash code for the current AdgConnection instance.The hash code is obtained from the SourceProfile of the current instance.The SourceProfile is a property that contains the configuration settings for the connection, such as the database name, server name, and other connection parameters.

int GetHashCode()

int GetPeerAltCodePageID()

Gets the peer alternative code page ID.

Remarks

This method retrieves the peer alternative code page ID from the DataLinkSource if the connection is open.The peer alternative code page ID is used to determine the character encoding for the connection.If the connection is not open, it throws an ApplicationException.

int GetPeerAltCodePageID()

ProtoLevel GetPeerVersion()

Gets the protocol level of the peer.

Remarks

This method retrieves the protocol level of the peer from the DataLinkSource if the connection is open.The protocol level is used to determine the version of the protocol used for communication.If the connection is not open, it throws an ApplicationException.If the SourceProvider is not a DataLinkSource, it returns the current protocol version.

ProtoLevel GetPeerVersion()

SourceProfile GetSourceProfileCopy()

Return a deep-copy of the current value of .

Remarks

Since the returned object is a copy, modifications to it have no effect on this AdgConnection instance.

SourceProfile GetSourceProfileCopy()

bool GetSupportsMultiMember()

Gets a value indicating whether the connection supports multi-member files.

Remarks

This method checks if the connection supports multi-member files. It first checks if the value is cached (m_supportsMultimember). If it is, it returns the cached value.If the value is not cached, it calls the GetSupportsMultiMemberFromProvider method to get the value from the provider and caches it.The value is cached to avoid unnecessary calls to the provider, improving performance.

bool GetSupportsMultiMember()

bool IsCanceledException(Exception e)

Determines whether the specified exception is due to a cancellation request.

Remarks

This method checks if the cancellation token for the connection is CancellationToken.None.If it is, it returns false, because a cancellation request could not have been made.If the cancellation token is not CancellationToken.None, it calls the IsCanceledExceptionInternal method to check if the specified exception is due to a cancellation request.

bool IsCanceledException(Exception e)

Parameters

Returns

bool op_Equality(AdgConnection x, AdgConnection y)

Determines whether two AdgConnection instances are equal.

Remarks

This operator checks if the two AdgConnection instances are the same instance, or if they are both null, in which case it returns true.If only one of them is null, it returns false.If neither of them is null, it calls the Equals method to determine if they are equal.

bool op_Equality(AdgConnection x, AdgConnection y)

Parameters

Returns

bool op_Inequality(AdgConnection x, AdgConnection y)

Determines whether two AdgConnection instances are not equal.

Remarks

This operator checks if the two AdgConnection instances are not equal.It does this by using the equality operator (==) to check if the instances are equal, and then returns the opposite result.

bool op_Inequality(AdgConnection x, AdgConnection y)

Parameters

Returns

void Open(CancellationToken ct)

Opens a connection to the database with default options.

Remarks

This method opens a connection to the database with default options.If the connection is already open, it returns immediately.It calls the Open method with the OpenOptions.Default parameter, meaning the connection will be opened with the default options.The ct parameter can be used to request cancellation of the operation. If the operation is canceled, it throws an OperationCanceledException.

void Open(CancellationToken ct)

Parameters

void Open(OpenOptions openOptions, CancellationToken ct)

Opens a connection to the database with the specified options.

Remarks

This method opens a connection to the database with the specified options.If the connection is already open, it returns immediately.If the SourceProfile indicates that connection pooling is disabled, or if the SourceProfile is for an SQL client platform, or if there is an existing 5250 exchange or OpenAccess RPG session, or if the connection cannot be pooled, it creates a new SourceProvider and opens it with the specified options.If the connection is not pooled, it sets up the user portion of the library list if specified in the SourceProfile.If the connection is pooled, it retrieves the connection from the pool.After the connection is opened, it logs the operation and completes the opening of any existing 5250 exchange.

void Open(OpenOptions openOptions, CancellationToken ct)

Parameters

AdgConnection Synchronized(AdgConnection cn)

Returns a synchronized (thread-safe) wrapper for the AdgConnection.

Remarks

This method checks if the provided AdgConnection is already a SyncConnection. If it is, it returns the connection as is. If it’s not, it creates a new SyncConnection with the provided connection and returns it.If the provided connection is in the open state, it also opens the new SyncConnection.The SyncConnection is a thread-safe wrapper for the AdgConnection. It ensures that only one thread can access the AdgConnection at a time, which is necessary when multiple threads are working with the same connection.

AdgConnection Synchronized(AdgConnection cn)

Parameters

Returns

Example 1. Constructor example.

  try
  {
      AdgConnection dataBase = new AdgConnection("*Public/DG NET IBM i");
  }
  catch(dgException e)
  {
      //At this point, dataBase will be set to null.  Do error handling here.
      System.Windows.Forms.MessageBox.Show(e.Message, "Unable to create connection.");
  }

Example 2. Use of ConnctionState Property.

  /* Here we need to use an AdgConnection "dataBase" to open
     a 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;
  AdgDataSet dataSet = null;
  if (dataBase != null && dataBase.State == ConnectionState.Open)
  {
     dbFile = new FileAdapter(dataBase);
     dbFile.OpenNewAdgDataSet(out dataSet);
  }
  else
  { 
     //If the AdgConnection was not ready, you cannot immediately
     //open the file, so take alternative action here.
  }

Example 3. Use of SourceProfile Property.

  AdgConnection Cx;
  Cx = new AdgConnection("*Public/DG NET IBM i");
  MessageBox.Show("The database name \"*Public/DG NET IBM i\" refers to a connection to "
           + Cx.SourceProfile.Server + " on port " + Cx.SourceProfile.Port.ToString());

Example 4. Use of Open method.

  try
  {
      AdgConnection dataBase = new AdgConnection("*Public/DG NET IBM i");
      dataBase.Open();
  }
  catch(dgException e)
  {
      System.Windows.Forms.MessageBox.Show(e.Message, "Error establishing connection to database.");
  }

Example 5. Use of Close method.

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