AdgConnection.BeginTransaction Method

Estimated reading time: 9 minutes

Definition

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

Begins a manual database transaction creating an instance of an IAdgTransaction object with combinations of transaction locking level, name, and command options parameters specified.

Overloads

Signature Description
BeginTransaction(TransactionLevel) Begins a transaction with the specified transaction level.
BeginTransaction(String) Begins a transaction with the specified name.
BeginTransaction(TransactionLevel, String) Begins a transaction with the specified transaction level and name.
BeginTransaction(TransactionLevel, String, String) Begins a transaction with the specified transaction level, name, and options.

IAdgTransaction BeginTransaction(TransactionLevel tl)

Begins a transaction with the specified transaction level.

Remarks

This method begins a manual transaction for those database providers that support transaction processing. The returned IAdgTransaction object representing the transaction is associated with the database connection of AdgConnection. This version of BeginTransaction produces an anonymous transaction, where the Name property of the returned IAdgTransaction object is the empty string.

A manual transaction (as initiated by BeginTransaction) is distinguished from an automatic transaction (as initiated by the BeginAutoTransaction methods) by the behaviors of the IAdgTransaction.Commit and IAdgTransaction.Rollback methods. Commit and Rollback result in the acceptance and cancellation, respectively, of accumulated database modifications within the current transaction’s boundaries. In an automatic transaction, these methods also result in the end of the current transaction followed by the immediate creation of a new transaction under the control of IAdgTransaction. Thus, the behavior of an automatic transaction is similar to the behavior of an IBM i database transaction for all database provider platforms.

Manual transactions should be used when an application requires a high degree of control over the transaction. Manual transactions can only be initiated with the BeginTransaction method. Further, manual transactions are not automatically renewed by DCS in the Commit and Rollback methods, as automatic transactions are. When multi-platform compatibility is of greater concern, use of automatic transactions is recommended (see BeginAutoTransaction). For the finest level of control over each transaction, use of manual transactions is recommended.

tl specifies the initial transaction level and is used to initialize the value of the TransactionLevel property of the IAdgTransaction object returned.

IAdgTransaction BeginTransaction(TransactionLevel tl)

Parameters

Type Parameter name Description
TransactionLevel tl The transaction level for the new transaction.

Returns

Type Description
IAdgTransaction A new IAdgTransaction representing the transaction.

IAdgTransaction BeginTransaction(string Name)

Begins a transaction with the specified name.

Remarks

This method begins a manual transaction for those database providers that support transaction processing. The returned IAdgTransaction object representing the transaction is associated with the database connection of AdgConnection.

A manual transaction (as initiated by BeginTransaction) is distinguished from an automatic transaction (as initiated by the BeginAutoTransaction methods) by the behaviors of the IAdgTransaction.Commit and IAdgTransaction.Rollback methods. Commit and Rollback result in the acceptance and cancellation, respectively, of accumulated database modifications within the current transaction’s boundaries. In an automatic transaction, these methods also result in the end of the current transaction followed by the immediate creation of a new transaction under the control of IAdgTransaction. Thus, the behavior of an automatic transaction is similar to the behavior of an IBM i database transaction for all database provider platforms.

Manual transactions should be used when an application requires a high degree of control over the transaction. Manual transactions can only be initiated with the BeginTransaction method. Further, manual transactions are not automatically renewed by DCS in the Commit and Rollback methods, as automatic transactions are. When multi-platform compatibility is of greater concern, use of automatic transactions is recommended (see BeginAutoTransaction). For the finest level of control over each transaction, use of manual transactions is recommended.

Name may be used by the database provider to identify transaction resources. Name initializes the Name property of the IAdgTransaction object returned. Specifying the empty string or a null reference for Name results in an anonymous transaction.

The value of the TransactionLevel property of the **IAdgTransaction **object returned is TransactionLevel.Medium.

IAdgTransaction BeginTransaction(string Name)

Parameters

Type Parameter name Description
String Name The name for the new transaction.

Returns

Type Description
IAdgTransaction A new IAdgTransaction representing the transaction.

IAdgTransaction BeginTransaction(TransactionLevel tl, string Name)

Begins a transaction with the specified transaction level and name.

Remarks

This method begins a manual transaction for those database providers that support transaction processing. The returned IAdgTransaction object representing the transaction is associated with the database connection of AdgConnection.

A manual transaction (as initiated by BeginTransaction) is distinguished from an automatic transaction (as initiated by the BeginAutoTransactionmethods) by the behaviors of the IAdgTransaction.Commit and IAdgTransaction.Rollback methods. Commit and Rollback result in the acceptance and cancellation, respectively, of accumulated database modifications within the current transaction’s boundaries. In an automatic transaction, these methods also result in the end of the current transaction followed by the immediate creation of a new transaction under the control of IAdgTransaction. Thus, the behavior of an automatic transaction is similar to the behavior of an IBM i database transaction for all database provider platforms.

Manual transactions should be used when an application requires a high degree of control over the transaction. Manual transactions can only be initiated with the BeginTransaction method. Further, manual transactions are not automatically renewed by DCS in the Commit and Rollback methods, as automatic transactions are. When multi-platform compatibility is of greater concern, use of automatic transactions is recommended (see BeginAutoTransaction). For the finest level of control over each transaction, use of manual transactions is recommended.

Name may be used by the database provider to identify transaction resources. Name initializes the Name property of the IAdgTransaction object returned. Specifying the empty string or a null reference for Name results in an anonymous transaction.

tl specifies the initial transaction level and is used to initialize the value of the TransactionLevel property of the IAdgTransaction object returned.

This method uses an empty string for the options parameter, meaning the transaction will not have any additional options.

IAdgTransaction BeginTransaction(TransactionLevel tl, string Name)

Parameters

Type Parameter name Description
TransactionLevel tl The transaction level for the new transaction.
String Name The name for the new transaction.

Returns

Type Description
IAdgTransaction A new IAdgTransaction representing the transaction.

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

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

Remarks

This method begins a manual transaction for those database providers that support transaction processing. The returned IAdgTransaction object representing the transaction is associated with the database connection of AdgConnection.

A manual transaction (as initiated by BeginTransaction) is distinguished from an automatic transaction (as initiated by the BeginAutoTransaction methods) by the behaviors of the IAdgTransaction.Commit and IAdgTransaction.Rollback methods. Commit and Rollback result in the acceptance and cancellation, respectively, of accumulated database modifications within the current transaction’s boundaries. In an automatic transaction, these methods also result in the end of the current transaction followed by the immediate creation of a new transaction under the control of IAdgTransaction. Thus, the behavior of an automatic transaction is similar to the behavior of an IBM i database transaction for all database provider platforms.

Manual transactions should be used when an application requires a high degree of control over the transaction. Manual transactions can only be initiated with the BeginTransaction method. Further, manual transactions are not automatically renewed by DCS in the Commit and Rollback methods, as automatic transactions are. When multi-platform compatibility is of greater concern, use of automatic transactions is recommended (see BeginAutoTransaction). For the finest level of control over each transaction, use of manual transactions is recommended.

Name may be used by the database provider to identify transaction resources. Name initializes the Name property of the IAdgTransaction object returned. Specifying the empty string or a null reference for _Name _results in an anonymous transaction.

tl specifies the initial transaction level and is used to initialize the value of the TransactionLevel property of the IAdgTransaction object returned.

Options specifies command options for initiating the new IAdgTranaction object specific to the database provider. For example, transactions on IBM i database providers are initiated via the “STRCMTCTL” CL command, with the “LCKLVL”, “TEXT”, and “CMTSCOPE(*JOB)” parameters. Other parameters not specified by DCS, such as “NFYOBJ” and “DFTJRN”, may be specified via Options (e.g. “NFYOBJ(MYLIB/MYOBJ *MSGQ) DFTJRN(MYLIB/MYJRN)” ). If other command options are not required, specify the empty string or null reference for Options. Note that non-empty string values for Options may restrict use of the application to a particular database provider.

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

Parameters

Type Parameter name Description
TransactionLevel tl The transaction level for the new transaction.
String Name The name for the new transaction.
String Options The options for the new transaction.

Returns

Type Description
IAdgTransaction A new IAdgTransaction representing the transaction.