SalSqlSessionHandle
Namespace: PPJ.Runtime.Sql
Assembly: PPJ.Web.50 (5.0.0.0)
Represents a database session shared by statement handles.
- C#
- VB.NET
public struct SalSqlSessionHandle : ValueType, ISerializable, IXmlSerializable
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 |