SalSqlHandle

Namespace: PPJ.Runtime.Sql

Assembly: PPJ.Web.50 (5.0.0.0)

Represents a database statement, its bind expressions, results, and SQL error state.

C#

public struct SalSqlHandle : ValueType, ISerializable, IXmlSerializable

VB.NET

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
SalComboBox.PopulateList
SalListBox.PopulateList
SalFormTableWindow.DeleteSelected
SalFormTableWindow.DoDeletes
SalFormTableWindow.DoInserts
SalFormTableWindow.DoUpdates
SalFormTableWindow.Populate
SalWindow.PopulateList	Executes a query and populates a list with its 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 statement for matching existing rows and marks each processed row deleted.
SalTableWindow.DoInserts	Executes the prepared SQL statement in the context of each matching new rows.
SalTableWindow.DoUpdates	Executes the prepared SQL statement in the context of each matching edited rows that are not new.
SalTableWindow.Populate	Executes a query and populates the table, replacing existing rows and previous automatic columns.
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.
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.
VisOutlineListBox.PopulateList