SalSqlSessionHandle

Namespace: PPJ.Runtime.Sql

Assembly: PPJ.Runtime.50 (5.0.0.0)

Represents a database session shared by statement handles.

C#

public struct SalSqlSessionHandle : ValueType, ISerializable, IXmlSerializable

VB.NET

Public Structure SalSqlSessionHandle
    Implements ValueType, ISerializable, IXmlSerializable

Copies of this value refer to the same runtime SQL object. Boolean-returning operations can return the value supplied by SQL error handling; unhandled SQL errors are thrown.

Example:

using PPJ.Runtime.Sql;

var handle = SalSqlSessionHandle.Null;
if (handle.Create("your provider connection string"))
{
    try
    {
        var statement = SalSqlHandle.Null;
        if (handle.CreateStatement(ref statement))
            statement.Disconnect();
    }
    finally { handle.Free(); }
}

Properties

Connection

IDbConnection: Gets the underlying ADO.NET database connection.

Handle

IntPtr: Gets the runtime handle, or Zero when unassigned.

IsNull

Boolean: Gets whether the underlying handle is zero.

LastError

SalSqlError: Gets the most recent SQL error, including connection validation errors, or when none is recorded.

LastErrorCode

SalNumber: Gets the last SQL error number, or zero when no error is recorded.

LastErrorMessage

SalString: Gets the last SQL error message, or an empty string when no error is recorded.

LastErrorPosition

SalNumber: Gets the statement position reported by the last SQL error, or zero when no error is recorded.

Properties

SqlProperties: Gets the database configuration used by the connection.

Transaction

IDbTransaction: Gets the current transaction associated with the connection.

Methods

BeginTransaction()

Starts or retrieves the connection transaction when autocommit is disabled.

Returns: IDbTransaction. The transaction, or when autocommit is enabled.

Commit()

Commits the transaction shared by statements using this database connection.

Returns: Boolean. True when the operation succeeds; on a SQL error, the value returned by SQL error handling.

Commit(errorHandler)

Commits the transaction shared by statements using this database connection.

Parameter	Type	Description
errorHandler	WhenSqlErrorHandler	The SQL error handler to use for the duration of this operation.

Returns: Boolean. True when the operation succeeds; on a SQL error, the value returned by SQL error handling.

Create(connectionString)

Acquires a database session using the current SQL database and credentials and the supplied connection string.

Parameter	Type	Description
connectionString	String	The provider connection string used to acquire the session.

Returns: Boolean. True when the operation succeeds; on a SQL error, the value returned by SQL error handling.

The database, user, and password come from Database, User, and Password.

Create(connectionString, errorHandler)

Acquires a database session using the current SQL database and credentials and the supplied connection string.

Parameter	Type	Description
connectionString	String	The provider connection string used to acquire the session.
errorHandler	WhenSqlErrorHandler	The SQL error handler to use for the duration of this operation.

Returns: Boolean. True when the operation succeeds; on a SQL error, the value returned by SQL error handling.

The database, user, and password come from Database, User, and Password.

CreateStatement(hSql)

Creates a statement handle associated with this session.

Parameter	Type	Description
hSql	SalSqlHandle	Receives the newly created statement handle.

Returns: Boolean. True when the operation succeeds; on a SQL error, the value returned by SQL error handling.

Free()

Releases this session reference to its database connection.

Returns: Boolean. True when the operation succeeds; on a SQL error, the value returned by SQL error handling.

Free(errorHandler)

Releases this session reference to its database connection.

Parameter	Type	Description
errorHandler	WhenSqlErrorHandler	The SQL error handler to use for the duration of this operation.

Returns: Boolean. True when the operation succeeds; on a SQL error, the value returned by SQL error handling.

FromHandle(handle)

Resolves a SQL handle registered with the runtime.

Parameter	Type	Description
handle	IntPtr	The registered runtime handle to resolve.

Returns: SalSqlSessionHandle. The wrapper for the registered handle, or a null handle when the value is zero.

GetErrorInfo(nErrorNumber, sErrorDescription, sSqlState)

Copies the last SQL error and connection state into the supplied variables.

Parameter	Type	Description
nErrorNumber	SalNumber	Receives the error number, or zero when no error is recorded.
sErrorDescription	SalString	Receives the error description, or a null SAL string when no error is recorded.
sSqlState	SalString	Receives the connection state name; this is not a provider SQLSTATE code.

Returns: Boolean. if an error is available; otherwise, .

GetObjectData(info, context)

Serializes the runtime handle.

Parameter	Type	Description
info	SerializationInfo	The serialization record that receives the handle.
context	StreamingContext	The serialization context; this implementation does not use it.

Serialization stores the handle value only; it does not serialize or recreate a database connection.

GetParameter(parameter, nValue, sValue)

Reads a supported database configuration parameter.

Parameter	Type	Description
parameter	Int32	The Sys.DBP_* identifier of the setting.
nValue	SalNumber	Receives the numeric setting when applicable.
sValue	SalString	Receives the string setting when applicable.

Returns: Boolean. True when the operation succeeds; on a SQL error, the value returned by SQL error handling. Unsupported parameter identifiers return false.

The numeric or string output receives the value appropriate to the selected parameter.

Rollback()

Rolls back the transaction shared by statements using this database connection.

Returns: Boolean. True when the operation succeeds; on a SQL error, the value returned by SQL error handling.

Rollback(errorHandler)

Rolls back the transaction shared by statements using this database connection.

Parameter	Type	Description
errorHandler	WhenSqlErrorHandler	The SQL error handler to use for the duration of this operation.

Returns: Boolean. True when the operation succeeds; on a SQL error, the value returned by SQL error handling.

SetParameter(parameter, numberValue, stringValue)

Changes a supported database configuration parameter.

Parameter	Type	Description
parameter	Int32	The Sys.DBP_* identifier of the setting.
numberValue	Int32	The numeric value, used for numeric and Boolean settings.
stringValue	String	The value for a string setting.

Returns: Boolean. True when the operation succeeds; on a SQL error, the value returned by SQL error handling. Unsupported parameter identifiers return false.

Supported parameters include DBP_BRAND, DBP_VERSION, DBP_LOCKWAITTIMEOUT, DBP_AUTOCOMMIT, and DBP_ISOLEVEL.

Used By

Name	Description
Sal.WindowHandleToNumber	Returns a runtime handle identifier as a SAL number.
SalSqlHandle.GetSessionHandle	Gets the session used to create this statement handle.
SalSqlSessionHandle.FromHandle	Resolves a SQL handle registered with the runtime.
Sql.CommitSession
Sql.CreateStatement
Sql.RollbackSession
Sql.GetSessionErrorInfo
Sql.SetSessionParameter
Sql.GetSessionParameter