SalSqlHandle
Namespace: PPJ.Runtime.Sql
Assembly: PPJ.Runtime.50 (5.0.0.0)
Represents a database statement, its bind expressions, results, and SQL error state.
- C#
- VB.NET
public struct SalSqlHandle : ValueType, ISerializable, IXmlSerializable
Public Structure SalSqlHandle
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 = SalSqlHandle.Null;
if (handle.Connect())
{
try
{
if (handle.PrepareAndExecute("SELECT CustomerId FROM Customers"))
while (handle.MoveNext())
System.Console.WriteLine(handle.Read()[0]);
}
finally { handle.Disconnect(); }
}
Properties
BindVars
SalSqlBindVariables: Gets the bind expressions and INTO targets associated with the statement.
Command
IDbCommand: Gets the prepared ADO.NET command, or when no command is available.
Connection
IDbConnection: Gets the underlying ADO.NET database connection.
Database
String: Gets the global SQL database value captured after the last successful connection.
Even when connection arguments are supplied explicitly, this property records Database.
DataReader
IDataReader: Gets the runtime data reader, or when no reader is active; buffered results are available through DataSet.
DataSet
DataSet: Gets the buffered result set, or when no data set is available.
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.
LastStatement
String: Gets the SQL text most recently prepared on this handle.
Password
String: Gets the global SQL password value captured after the last successful connection.
Even when connection arguments are supplied explicitly, this property records Password.
Properties
SqlProperties: Gets the database configuration used by the connection.
ProviderDataReader
IDataReader: Gets the underlying provider reader, or when no reader is active.
Transaction
IDbTransaction: Gets the current transaction associated with the connection.
User
String: Gets the global SQL user value captured after the last successful connection.
Even when connection arguments are supplied explicitly, this property records User.
Methods
BeginTransaction()
Starts or retrieves the connection transaction when autocommit is disabled.
Returns: IDbTransaction. The transaction, or when autocommit is enabled.
ClearContext()
Clears the explicitly assigned bind expression context.
Returns: SalBoolean. True when the operation succeeds; on a SQL error, the value returned by SQL error handling.
CloseAllSPResultSets()
Closes the active result set and releases its reader or buffered data.
Returns: SalBoolean. True when the operation succeeds; on a SQL error, the value returned by SQL error handling.
CloseResultSet()
Closes the active result set and releases its reader or buffered data.
Returns: SalBoolean. True when the operation succeeds; on a SQL error, the value returned by SQL error handling.
Commit()
Commits the transaction shared by statements using this database connection.
Returns: SalBoolean. 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: SalBoolean. True when the operation succeeds; on a SQL error, the value returned by SQL error handling.
Connect()
Connects a statement handle using the current SQL database and credentials.
Returns: SalBoolean. True when the operation succeeds; on a SQL error, the value returned by SQL error handling.
The database must be configured in sql.config or the runtime database registry.
Connect(errorHandler)
Connects a statement handle using the current SQL database and credentials.
| Parameter | Type | Description |
|---|---|---|
| errorHandler | WhenSqlErrorHandler | The SQL error handler to use for the duration of this operation. |
Returns: SalBoolean. True when the operation succeeds; on a SQL error, the value returned by SQL error handling.
The database must be configured in sql.config or the runtime database registry.
Connect(database, user, password)
Connects a statement handle to the specified configured database.
| Parameter | Type | Description |
|---|---|---|
| database | String | The configured database name. |
| user | String | The database user name. |
| password | String | The database password. |
Returns: SalBoolean. True when the operation succeeds; on a SQL error, the value returned by SQL error handling.
Returns false for an empty database name. If establishing the new connection fails, the existing statement object is retained.
DirectoryByName(serverName)
Returns the names of all configured databases.
| Parameter | Type | Description |
|---|---|---|
| serverName | String | Reserved for compatibility; this value is ignored. |
Returns: String[]. The configured database names.
This method reads the configuration registry; it does not query a database server.
Disconnect()
Closes this statement and releases its connection reference.
Returns: SalBoolean. True when the operation succeeds; on a SQL error, the value returned by SQL error handling.
The handle becomes null even if closing the statement reports an error.
Disconnect(errorHandler)
Closes this statement and releases its connection reference.
| Parameter | Type | Description |
|---|---|---|
| errorHandler | WhenSqlErrorHandler | The SQL error handler to use for the duration of this operation. |
Returns: SalBoolean. True when the operation succeeds; on a SQL error, the value returned by SQL error handling.
The handle becomes null even if closing the statement reports an error.
Execute()
Evaluates bind expressions and executes the prepared SQL statement or stored procedure.
Returns: SalBoolean. True when the operation succeeds; on a SQL error, the value returned by SQL error handling.
Execute(errorHandler)
Evaluates bind expressions and executes the prepared SQL statement or stored procedure.
| Parameter | Type | Description |
|---|---|---|
| errorHandler | WhenSqlErrorHandler | The SQL error handler to use for the duration of this operation. |
Returns: SalBoolean. True when the operation succeeds; on a SQL error, the value returned by SQL error handling.
FetchNext(code)
Fetches the next result row and assigns its values to the INTO variables.
| Parameter | Type | Description |
|---|---|---|
code  | SalNumber | Receives Sys.FETCH_Ok initially, or Sys.FETCH_EOF when the cursor reaches the relevant result boundary. SQL errors are reported separately through SQL error handling. |
Returns: SalBoolean. True if a row was fetched; false at a result boundary, or the SQL error-handler result on failure.
Example:
Process INTO values only after a successful fetch, then distinguish end-of-data from an error. The scope suppresses global SQL error handling so unhandled SQL errors throw instead of being mistaken for fetched rows.
using System;
using PPJ.Runtime;
using PPJ.Runtime.Sql;
public static class ResultReader
{
public static bool ReadAll(SalSqlHandle sql, Action readCurrentValues)
{
// The caller has executed a query and configured its INTO targets.
using (new WhenSqlError())
{
SalNumber code = Sys.FETCH_Ok;
while (sql.FetchNext(ref code))
readCurrentValues();
// A failed fetch is not necessarily end-of-data.
return code == Sys.FETCH_EOF;
}
}
}
FetchNext(code, errorHandler)
Fetches the next result row and assigns its values to the INTO variables.
| Parameter | Type | Description |
|---|---|---|
| code | SalNumber | Receives Sys.FETCH_Ok initially, or Sys.FETCH_EOF when the cursor reaches the relevant result boundary. SQL errors are reported separately through SQL error handling. |
| errorHandler | WhenSqlErrorHandler | The SQL error handler to use for the duration of this operation. |
Returns: SalBoolean. True if a row was fetched; false at a result boundary, or the SQL error-handler result on failure.
FetchNext()
Fetches the next result row and assigns its values to the INTO variables.
Returns: SalNumber. Sys.FETCH_Ok or Sys.FETCH_EOF; SQL errors are reported separately through SQL error handling.
FetchNext(errorHandler)
Fetches the next result row and assigns its values to the INTO variables.
| Parameter | Type | Description |
|---|---|---|
| errorHandler | WhenSqlErrorHandler | The SQL error handler to use for the duration of this operation. |
Returns: SalNumber. Sys.FETCH_Ok or Sys.FETCH_EOF; SQL errors are reported separately through SQL error handling.
FetchPrevious(code)
Fetches the previous buffered row and assigns its values to the INTO variables.
| Parameter | Type | Description |
|---|---|---|
| code | SalNumber | Receives Sys.FETCH_Ok initially, or Sys.FETCH_EOF when the cursor reaches the relevant result boundary. SQL errors are reported separately through SQL error handling. |
Returns: SalBoolean. True if a row was fetched; false at a result boundary, or the SQL error-handler result on failure.
Requires buffered result set mode.
FetchPrevious(code, errorHandler)
Fetches the previous buffered row and assigns its values to the INTO variables.
| Parameter | Type | Description |
|---|---|---|
| code | SalNumber | Receives Sys.FETCH_Ok initially, or Sys.FETCH_EOF when the cursor reaches the relevant result boundary. SQL errors are reported separately through SQL error handling. |
| errorHandler | WhenSqlErrorHandler | The SQL error handler to use for the duration of this operation. |
Returns: SalBoolean. True if a row was fetched; false at a result boundary, or the SQL error-handler result on failure.
Requires buffered result set mode.
FetchPrevious()
Fetches the previous buffered row and assigns its values to the INTO variables.
Returns: SalNumber. Sys.FETCH_Ok or Sys.FETCH_EOF; SQL errors are reported separately through SQL error handling.
Requires buffered result set mode.
FetchPrevious(errorHandler)
Fetches the previous buffered row and assigns its values to the INTO variables.
| Parameter | Type | Description |
|---|---|---|
| errorHandler | WhenSqlErrorHandler | The SQL error handler to use for the duration of this operation. |
Returns: SalNumber. Sys.FETCH_Ok or Sys.FETCH_EOF; SQL errors are reported separately through SQL error handling.
Requires buffered result set mode.
FetchRow(code)
Copies the current result row into the INTO variables.
| Parameter | Type | Description |
|---|---|---|
| code | SalNumber | Receives Sys.FETCH_Ok initially, or Sys.FETCH_EOF when the cursor reaches the relevant result boundary. SQL errors are reported separately through SQL error handling. |
Returns: SalBoolean. True if a row was fetched; false at a result boundary, or the SQL error-handler result on failure.
FetchRow(row, code)
Fetches the specified buffered row into the INTO variables.
| Parameter | Type | Description |
|---|---|---|
| row | Int32 | The zero-based buffered row index. |
| code | SalNumber | Receives Sys.FETCH_Ok initially, or Sys.FETCH_EOF when the cursor reaches the relevant result boundary. SQL errors are reported separately through SQL error handling. |
Returns: SalBoolean. True if a row was fetched; false at a result boundary, or the SQL error-handler result on failure.
FetchRow(row, code, errorHandler)
Fetches the specified buffered row into the INTO variables.
| Parameter | Type | Description |
|---|---|---|
| row | Int32 | The zero-based buffered row index. |
| code | SalNumber | Receives Sys.FETCH_Ok initially, or Sys.FETCH_EOF when the cursor reaches the relevant result boundary. SQL errors are reported separately through SQL error handling. |
| errorHandler | WhenSqlErrorHandler | The SQL error handler to use for the duration of this operation. |
Returns: SalBoolean. True if a row was fetched; false at a result boundary, or the SQL error-handler result on failure.
FetchRow(row)
Fetches the specified buffered row into the INTO variables.
| Parameter | Type | Description |
|---|---|---|
| row | Int32 | The zero-based buffered row index. |
Returns: SalNumber. Sys.FETCH_Ok or Sys.FETCH_EOF; SQL errors are reported separately through SQL error handling.
FetchRow(row, errorHandler)
Fetches the specified buffered row into the INTO variables.
| Parameter | Type | Description |
|---|---|---|
| row | Int32 | The zero-based buffered row index. |
| errorHandler | WhenSqlErrorHandler | The SQL error handler to use for the duration of this operation. |
Returns: SalBoolean. The numeric fetch status converted to SalBoolean; this overload does not return the row-fetched Boolean from the ref-code overload.
FromHandle(handle)
Resolves a SQL handle registered with the runtime.
| Parameter | Type | Description |
|---|---|---|
| handle | IntPtr | The registered runtime handle to resolve. |
Returns: SalSqlHandle. The wrapper for the registered handle, or a null handle when the value is zero.
GetContext()
Gets the object currently used to resolve bind expressions.
Returns: Object. The assigned context; if error handling returns after a failure, the boxed error-handler result.
GetError(nError, sError)
Copies the last SQL error number and message into the supplied variables.
| Parameter | Type | Description |
|---|---|---|
| nError | SalNumber | Receives the error number, or zero when no error is recorded. |
| sError | SalString | Receives the error message, or a null SAL string when no error is recorded. |
Returns: SalBoolean. if an error is recorded; otherwise, .
GetErrorPosition(nPos)
Gets the statement offset reported by the last SQL error.
| Parameter | Type | Description |
|---|---|---|
| nPos | SalNumber | Receives the statement offset of the last error. |
Returns: SalBoolean. True after assigning the error position.
An error must be available; this method dereferences the last error without a null check.
GetErrorPosition()
Gets the statement offset reported by the last SQL error.
Returns: SalNumber. The last error offset.
An error must be available; this method dereferences the last error without a null check.
GetIsolationLevel()
Gets the connection transaction isolation mode.
Returns: SalString. The isolation code, or a null SAL string if error handling returns after a failure.
GetLastStatement()
Gets the SQL text most recently prepared through the current SQL globals.
Returns: String. The most recently recorded statement text.
GetModifiedRows(nRows)
Gets the provider-reported number of rows affected by the last execution.
| Parameter | Type | Description |
|---|---|---|
| nRows | SalNumber | Receives the provider-reported affected-row count. |
Returns: SalBoolean. True when the operation succeeds; on a SQL error, the value returned by SQL error handling.
GetModifiedRows()
Gets the provider-reported number of rows affected by the last execution.
Returns: SalNumber. The row count, or zero if error handling returns before a count can be assigned.
GetNextSPResultSet(intoList, end)
Advances to the next stored procedure result set and replaces its INTO targets.
| Parameter | Type | Description |
|---|---|---|
| intoList | String | The comma-separated INTO target expressions, for example ":customerId, :customerName". |
| end | SalBoolean | Receives true when no further result set is available; otherwise, false. |
Returns: SalBoolean. True if the advance operation completed, including when no result set remains; on error, the SQL error-handler result.
GetNextSPResultSet(intoList)
Advances to the next stored procedure result set and replaces its INTO targets.
| Parameter | Type | Description |
|---|---|---|
| intoList | String | The comma-separated INTO target expressions, for example ":customerId, :customerName". |
Returns: SalBoolean. True when no further result set exists; false 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: SalBoolean. 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.
GetResultSetCount(count)
Gets the number of rows in the current result set.
| Parameter | Type | Description |
|---|---|---|
| count | SalNumber | Receives the result row count. |
Returns: SalBoolean. True when the operation succeeds; on a SQL error, the value returned by SQL error handling.
GetResultSetCount()
Gets the number of rows in the current result set.
Returns: SalNumber. The row count, or zero if error handling returns before a count can be assigned.
GetResultSetCount(errorHandler)
Gets the number of rows in the current result set.
| Parameter | Type | Description |
|---|---|---|
| errorHandler | WhenSqlErrorHandler | The SQL error handler to use for the duration of this operation. |
Returns: SalNumber. The row count, or zero if error handling returns before a count can be assigned.
GetResultSetCount(count, errorHandler)
Gets the number of rows in the current result set.
| Parameter | Type | Description |
|---|---|---|
| count | SalNumber | Receives the result row count. |
| errorHandler | WhenSqlErrorHandler | The SQL error handler to use for the duration of this operation. |
Returns: SalBoolean. True when the operation succeeds; on a SQL error, the value returned by SQL error handling.
GetSessionHandle(hSession)
Gets the session used to create this statement handle.
| Parameter | Type | Description |
|---|---|---|
| hSession | SalSqlSessionHandle | Receives the creating session, or a null session for a directly connected statement. |
Returns: SalBoolean. True after assigning the session handle.
A statement created by Connect has a null session handle.
GetSessionHandle()
Gets the session used to create this statement handle.
Returns: SalSqlSessionHandle. The creating session handle, or a null session handle.
A statement created by Connect has a null session handle.
GetStatementErrorInfo(errorNumber, errorDescription, sqlState)
Copies the last statement error and the connection state into the supplied variables.
| Parameter | Type | Description |
|---|---|---|
| errorNumber | SalNumber | Receives the error number, or zero when no error is recorded. |
| errorDescription | SalString | Receives the error description, or a null SAL string when no error is recorded. |
| sqlState | SalString | Receives the connection state name, rather than a provider SQLSTATE code. |
Returns: SalBoolean. if an error is recorded; otherwise, .
MoveNext()
Moves to the next result row without assigning INTO variables.
Returns: Boolean. if a row is available; otherwise, .
MovePrev()
Moves to the previous buffered row without assigning INTO variables.
Returns: Boolean. if a row is available; otherwise, .
Requires buffered result set mode.
MoveTo(row)
Moves the cursor to the specified buffered row without assigning INTO variables.
| Parameter | Type | Description |
|---|---|---|
| row | Int32 | The zero-based buffered row index. |
Returns: Boolean. if the position is accepted; otherwise, .
Requires buffered result set mode. A negative index positions the cursor before the first row.
OraPLSQLCommand(command)
Prepares and executes an Oracle procedure call, including array and output parameters.
| Parameter | Type | Description |
|---|---|---|
| command | SalString | The Oracle procedure invocation text. |
Returns: SalBoolean. True when the operation succeeds; on a SQL error, the value returned by SQL error handling.
OraPLSQLCommand(command, errorHandler)
Prepares and executes an Oracle procedure call, including array and output parameters.
| Parameter | Type | Description |
|---|---|---|
| command | SalString | The Oracle procedure invocation text. |
| errorHandler | WhenSqlErrorHandler | The SQL error handler to use for the duration of this operation. |
Returns: SalBoolean. True when the operation succeeds; on a SQL error, the value returned by SQL error handling.
OraPLSQLExecute()
Executes the prepared Oracle PL/SQL block and writes output parameters to the bind variables.
Returns: SalBoolean. True when the operation succeeds; on a SQL error, the value returned by SQL error handling.
OraPLSQLExecute(errorHandler)
Executes the prepared Oracle PL/SQL block and writes output parameters to the bind variables.
| Parameter | Type | Description |
|---|---|---|
| errorHandler | WhenSqlErrorHandler | The SQL error handler to use for the duration of this operation. |
Returns: SalBoolean. True when the operation succeeds; on a SQL error, the value returned by SQL error handling.
OraPLSQLPrepare(anonymousPLSQLBlock)
Prepares an Oracle anonymous PL/SQL block for subsequent execution.
| Parameter | Type | Description |
|---|---|---|
| anonymousPLSQLBlock | SalString | The Oracle PL/SQL text to prepare. |
Returns: SalBoolean. True when the operation succeeds; on a SQL error, the value returned by SQL error handling.
OraPLSQLPrepare(anonymousPLSQLBlock, errorHandler)
Prepares an Oracle anonymous PL/SQL block for subsequent execution.
| Parameter | Type | Description |
|---|---|---|
| anonymousPLSQLBlock | SalString | The Oracle PL/SQL text to prepare. |
| errorHandler | WhenSqlErrorHandler | The SQL error handler to use for the duration of this operation. |
Returns: SalBoolean. True when the operation succeeds; on a SQL error, the value returned by SQL error handling.
ParseIntoVariables(intoList)
Replaces the INTO targets used by subsequent fetch operations.
| Parameter | Type | Description |
|---|---|---|
| intoList | String | The comma-separated INTO target expressions, for example ":customerId, :customerName". |
Prepare(statement)
Parses and prepares SQL text for subsequent execution.
| Parameter | Type | Description |
|---|---|---|
| statement | String | The SQL text, including any bind expressions and INTO targets; null is treated as an empty string. |
Returns: SalBoolean. True when the operation succeeds; on a SQL error, the value returned by SQL error handling.
Clears the previously assigned bind context before preparing the statement. Bind and INTO expressions are resolved through the SQL context.
Example:
Prepare, assign the bind context, execute, and fetch one row. Public fields supply input and INTO values. The scope suppresses global SQL error handling; unhandled SQL errors throw.
using PPJ.Runtime;
using PPJ.Runtime.Sql;
public sealed class CustomerLookup
{
public SalNumber CustomerId = 42;
public SalString CustomerName = SalString.Null;
public bool Read(SalSqlHandle sql)
{
// The caller supplies a connected handle and a Customers table.
using (new WhenSqlError())
{
if (!sql.Prepare("SELECT Name INTO :CustomerName " +
"FROM Customers WHERE Id = :CustomerId"))
return false;
// Prepare clears the old context; assign this object afterward.
if (!sql.SetContext(this) || !sql.Execute())
return false;
SalNumber code = Sys.FETCH_Ok;
return sql.FetchNext(ref code);
}
}
}
Prepare(statement, errorHandler)
Parses and prepares SQL text for subsequent execution.
| Parameter | Type | Description |
|---|---|---|
| statement | String | The SQL text, including any bind expressions and INTO targets; null is treated as an empty string. |
| errorHandler | WhenSqlErrorHandler | The SQL error handler to use for the duration of this operation. |
Returns: SalBoolean. True when the operation succeeds; on a SQL error, the value returned by SQL error handling.
Clears the previously assigned bind context before preparing the statement. Bind and INTO expressions are resolved through the SQL context.
PrepareAndExecute(statement)
Prepares SQL text and executes it with the current bind values.
| Parameter | Type | Description |
|---|---|---|
| statement | String | The SQL text, including any bind expressions and INTO targets; null is treated as an empty string. |
Returns: SalBoolean. True when the operation succeeds; on a SQL error, the value returned by SQL error handling.
PrepareAndExecute(statement, errorHandler)
Prepares SQL text and executes it with the current bind values.
| Parameter | Type | Description |
|---|---|---|
| statement | String | The SQL text, including any bind expressions and INTO targets; null is treated as an empty string. |
| errorHandler | WhenSqlErrorHandler | The SQL error handler to use for the duration of this operation. |
Returns: SalBoolean. True when the operation succeeds; on a SQL error, the value returned by SQL error handling.
PrepareSP(call, intoList)
Prepares a stored procedure call and its INTO targets for subsequent execution.
| Parameter | Type | Description |
|---|---|---|
| call | String | The stored procedure invocation text; null is treated as an empty string. |
| intoList | String | The comma-separated INTO target expressions, for example ":customerId, :customerName". |
Returns: SalBoolean. True when the operation succeeds; on a SQL error, the value returned by SQL error handling.
Overloads without a nonQuery argument prepare the call to return results.
Example:
Prepare a procedure that accepts an identifier and returns a one-column result set. The INTO list names the destination field, not a database column.
using PPJ.Runtime;
using PPJ.Runtime.Sql;
public sealed class CustomerProcedure
{
public SalNumber CustomerId = 42;
public SalString CustomerName = SalString.Null;
public bool Read(SalSqlHandle sql)
{
// Requires a connected handle and a procedure returning a Name column.
// Adapt the invocation syntax to the configured database provider.
using (new WhenSqlError())
{
if (!sql.PrepareSP("GetCustomerName :CustomerId", ":CustomerName"))
return false;
if (!sql.SetContext(this) || !sql.Execute())
return false;
SalNumber code = Sys.FETCH_Ok;
return sql.FetchNext(ref code);
}
}
}
PrepareSP(call, intoList, nonQuery)
Prepares a stored procedure call and its INTO targets for subsequent execution.
| Parameter | Type | Description |
|---|---|---|
| call | String | The stored procedure invocation text; null is treated as an empty string. |
| intoList | String | The comma-separated INTO target expressions, for example ":customerId, :customerName". |
| nonQuery | Boolean | True to execute without returning a query result; otherwise, false. |
Returns: SalBoolean. True when the operation succeeds; on a SQL error, the value returned by SQL error handling.
Overloads without a nonQuery argument prepare the call to return results.
PrepareSP(call, intoList, errorHandler)
Prepares a stored procedure call and its INTO targets for subsequent execution.
| Parameter | Type | Description |
|---|---|---|
| call | String | The stored procedure invocation text; null is treated as an empty string. |
| intoList | String | The comma-separated INTO target expressions, for example ":customerId, :customerName". |
| errorHandler | WhenSqlErrorHandler | The SQL error handler to use for the duration of this operation. |
Returns: SalBoolean. True when the operation succeeds; on a SQL error, the value returned by SQL error handling.
Overloads without a nonQuery argument prepare the call to return results.
PrepareSP(call, intoList, errorHandler, nonQuery)
Prepares a stored procedure call and its INTO targets for subsequent execution.
| Parameter | Type | Description |
|---|---|---|
| call | String | The stored procedure invocation text; null is treated as an empty string. |
| intoList | String | The comma-separated INTO target expressions, for example ":customerId, :customerName". |
| errorHandler | WhenSqlErrorHandler | The SQL error handler to use for the duration of this operation. |
| nonQuery | Boolean | True to execute without returning a query result; otherwise, false. |
Returns: SalBoolean. True when the operation succeeds; on a SQL error, the value returned by SQL error handling.
Overloads without a nonQuery argument prepare the call to return results.
Read()
Reads the field values at the current result row.
Returns: Object[]. The current row values in column order.
Retrieve(name, bindList, intoList)
Prepares a named stored procedure or SQLBase compiled command with bind and INTO lists.
| Parameter | Type | Description |
|---|---|---|
| name | String | The stored procedure or compiled command name. |
| bindList | String | The comma-separated input/output bind expressions; missing colon markers are added. |
| intoList | String | The comma-separated INTO target expressions, for example ":customerId, :customerName". |
Returns: SalBoolean. True when the operation succeeds; on a SQL error, the value returned by SQL error handling.
Adapts the invocation syntax to the configured provider. Call Execute to run the prepared command.
Retrieve(name, bindList, intoList, nonQuery)
Prepares a named stored procedure or SQLBase compiled command with bind and INTO lists.
| Parameter | Type | Description |
|---|---|---|
| name | String | The stored procedure or compiled command name. |
| bindList | String | The comma-separated input/output bind expressions; missing colon markers are added. |
| intoList | String | The comma-separated INTO target expressions, for example ":customerId, :customerName". |
| nonQuery | Boolean | True to execute without returning a query result; otherwise, false. |
Returns: SalBoolean. True when the operation succeeds; on a SQL error, the value returned by SQL error handling.
Adapts the invocation syntax to the configured provider. Call Execute to run the prepared command.
Retrieve(name, bindList, intoList, errorHandler)
Prepares a named stored procedure or SQLBase compiled command with bind and INTO lists.
| Parameter | Type | Description |
|---|---|---|
| name | String | The stored procedure or compiled command name. |
| bindList | String | The comma-separated input/output bind expressions; missing colon markers are added. |
| intoList | String | The comma-separated INTO target expressions, for example ":customerId, :customerName". |
| errorHandler | WhenSqlErrorHandler | The SQL error handler to use for the duration of this operation. |
Returns: SalBoolean. True when the operation succeeds; on a SQL error, the value returned by SQL error handling.
Adapts the invocation syntax to the configured provider. Call Execute to run the prepared command.
Retrieve(name, bindList, intoList, errorHandler, nonQuery)
Prepares a named stored procedure or SQLBase compiled command with bind and INTO lists.
| Parameter | Type | Description |
|---|---|---|
| name | String | The stored procedure or compiled command name. |
| bindList | String | The comma-separated input/output bind expressions; missing colon markers are added. |
| intoList | String | The comma-separated INTO target expressions, for example ":customerId, :customerName". |
| errorHandler | WhenSqlErrorHandler | The SQL error handler to use for the duration of this operation. |
| nonQuery | Boolean | True to execute without returning a query result; otherwise, false. |
Returns: SalBoolean. True when the operation succeeds; on a SQL error, the value returned by SQL error handling.
Adapts the invocation syntax to the configured provider. Call Execute to run the prepared command.
Rollback()
Rolls back the transaction shared by statements using this database connection.
Returns: SalBoolean. 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: SalBoolean. True when the operation succeeds; on a SQL error, the value returned by SQL error handling.
SetContext(context)
Sets the object used to resolve bind expressions.
| Parameter | Type | Description |
|---|---|---|
| context | Object | The object used to resolve bind expressions. |
Returns: SalBoolean. True when the operation succeeds; on a SQL error, the value returned by SQL error handling.
Example:
Assign an object after preparing a statement whose bind expressions name its public fields. Keep this object alive while executing and fetching.
using PPJ.Runtime;
using PPJ.Runtime.Sql;
public sealed class CustomerParameters
{
public SalNumber CustomerId;
public SalString CustomerName;
public bool ExecuteLookup(SalSqlHandle sql, SalNumber id)
{
// sql is connected; its prepared statement references these fields.
CustomerId = id;
using (new WhenSqlError())
{
return sql.SetContext(this) && sql.Execute();
}
}
}
SetContextToForm(context)
Uses the supplied control as the bind expression context.
| Parameter | Type | Description |
|---|---|---|
| context | Control | The object used to resolve bind expressions. |
Returns: SalBoolean. True when the operation succeeds; on a SQL error, the value returned by SQL error handling.
SetContextToForm()
Uses the current form as the bind expression context.
Returns: SalBoolean. True when the operation succeeds; on a SQL error, the value returned by SQL error handling.
SetIsolationLevel(isolation)
Sets the connection transaction isolation mode.
| Parameter | Type | Description |
|---|---|---|
| isolation | String | The SAL isolation code, such as CS, RL, RO, or RR. |
Returns: SalBoolean. 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: SalBoolean. 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.
SetResultSet(enable)
Enables or disables buffered result sets for this statement.
| Parameter | Type | Description |
|---|---|---|
| enable | Boolean | True to buffer results; false to use a forward-only reader. |
Returns: SalBoolean. True when the operation succeeds; on a SQL error, the value returned by SQL error handling.
SetResultSetMode(mode)
Validates the connection for the result set mode compatibility API.
| Parameter | Type | Description |
|---|---|---|
| mode | ResultSetMode | The requested compatibility mode; currently ignored. |
Returns: SalBoolean. True when the operation succeeds; on a SQL error, the value returned by SQL error handling.
The current implementation ignores the requested mode and does not change result set behavior.
SetTimeout(timeout)
Sets the command timeout for the database connection.
| Parameter | Type | Description |
|---|---|---|
| timeout | Int32 | The command timeout in seconds. |
Returns: SalBoolean. True when the operation succeeds; on a SQL error, the value returned by SQL error handling.
VarSetup(context)
Captures a temporary SQL context for resolving this statement's bind variables.
| Parameter | Type | Description |
|---|---|---|
| context | Object | The object used to resolve bind expressions. |
Returns: SalBoolean. True when the operation succeeds; on a SQL error, the value returned by SQL error handling.
Used By
| Name | Description |
|---|---|
| Sal.WindowHandleToNumber | Returns a runtime handle identifier as a SAL number. |
| Sal.ListPopulate | |
| Sal.TblDeleteSelected | |
| Sal.TblDoDeletes | |
| Sal.TblDoInserts | |
| Sal.TblDoUpdates | |
| Sal.TblPopulate | |
| SalWindowHandle.PopulateList | |
| SalWindowHandle.DeleteSelected | |
| SalWindowHandle.DoDeletes | |
| SalWindowHandle.DoInserts | |
| SalWindowHandle.DoUpdates | |
| SalWindowHandle.Populate | |
| SalSqlHandle.FromHandle | Resolves a SQL handle registered with the runtime. |
| Sql.CloseAllSPResultSets | |
| Sql.CloseResultSet | |
| Sql.Commit | |
| Sql.Rollback | |
| Sql.ContextClear | |
| Sql.ContextSet | Uses the current form as the SQL variable-resolution context. |
| Sql.ContextSetToForm | |
| Sql.Error | Returns the most recent error code recorded by a statement handle. |
| Sql.Execute | |
| Sql.FetchNext | |
| Sql.FetchPrevious | |
| Sql.FetchRow | |
| Sql.GetError | |
| Sql.GetErrorPosition | |
| Sql.GetModifiedRows | |
| Sql.GetNextSPResultSet | |
| Sql.GetParameter | |
| Sql.GetResultSetCount | |
| Sql.Prepare | |
| Sql.PrepareAndExecute | |
| Sql.PrepareSP | |
| Sql.Retrieve | |
| Sql.SetIsolationLevel | |
| Sql.SetParameter | |
| Sql.SetResultSet | |
| Sql.VarSetup | |
| Sql.GetStatementErrorInfo | |
| Sql.SetLockTimeout | |
| Sql.GetSessionHandle | |
| Sql.OraPLSQLExecute | Executes a previously prepared anonymous Oracle PL/SQL block. |
| Sql.OraPLSQLPrepare | Prepares an anonymous Oracle PL/SQL block and its bind variables. |
| Sql.OraPLSQLCommand | Prepares and executes an Oracle PL/SQL stored-procedure command. |
| Sql.ConnectUsingCursor | Retains the unsupported ConnectUsingCursor operation for source compatibility. |
| Sql.DisconnectWithoutCursor | Retains the unsupported DisconnectWithoutCursor operation for source compatibility. |
| Sql.ExecutionPlan | Retains the unsupported ExecutionPlan operation for source compatibility. |
| Sql.GetCursor | Retains the unsupported GetCursor operation for source compatibility. |
| Sql.GetSqlHandle | Retains the unsupported GetSqlHandle operation for source compatibility. |
| SqlOra.PLSQLPrepare | Normalizes and prepares Oracle PL/SQL text. |
| SqlOra.PLSQLExecute | Executes the prepared PL/SQL block and copies Oracle output parameters into bind variables. |
| SqlOra.PLSQLCommand | Adds missing bind markers, prepares an Oracle procedure call, and executes it. |
| SalComboBox.PopulateList | Replaces list items with tab-separated rows from a SQL result and calculates column tab stops. |
| SalListBox.PopulateList | Replaces list items with tab-separated rows from a SQL result and calculates column tab stops. |
| SalFormTableWindow.DeleteSelected | Executes the prepared SQL command for selected existing rows and marks selected rows deleted. |
| SalFormTableWindow.DoDeletes | Executes a prepared delete command for matching existing rows and marks matching rows deleted. |
| SalFormTableWindow.DoInserts | Executes the prepared command with each new row as context. |
| SalFormTableWindow.DoUpdates | Executes the prepared command with each edited, nonnew row as context. |
| SalFormTableWindow.Populate | Executes a query and repopulates the table using immediate, demand-driven, or background filling. |
| SalWindow.PopulateList | Executes a query and replaces list items with tab-separated result rows. |
| SalTableColumn.PopulateList | Replaces list items with tab-separated rows from a SQL result and calculates column tab stops. |
| SalTableWindow.DeleteSelected | Executes the prepared SQL command for selected existing rows and marks selected rows deleted. |
| SalTableWindow.DoDeletes | Executes a prepared delete command for matching existing rows and marks matching rows deleted. |
| SalTableWindow.DoInserts | Executes the prepared command with each new row as context. |
| SalTableWindow.DoUpdates | Executes the prepared command with each edited, nonnew row as context. |
| SalTableWindow.Populate | Executes a query and repopulates the table using immediate, demand-driven, or background filling. |
| VisOutlineListBox.PopulateList |