TDAESQLCommand

Overview

The TDAESQLCommand class is a base class for all dataset classes in the Data Abstract Architecture.

Please refer to the article How to create a Data Abstract Driver (Delphi) for an overall description.

Location

  • Unit: uDAESQLCommand.pas
  • Ancestry: TDAEngineBaseObject | TDAESQLCommand


 

constructor Create  virtual

Creates a new instance.

constructor Create(aConnection: IDAConnection; aDataset: TDataset; const aName: string)

Parameters:

  • aConnection: Connection
  • aDataset: Dataset
  • aName: Name

CachedParams  protected

property CachedParams: TDictionary<string, Integer> read

CanUseNativeFieldData  protected safecall

Specifies that given field can return data in GetNativeFieldData method

function CanUseNativeFieldData(Index: Integer): Boolean

Parameters:

  • Index: Required field index

ClearParams  protected virtual

Clears parameter values.

procedure ClearParams

Connection  protected

Presents the IDAConnection to access information about available databases, tables, columns, etc.

property Connection: IDAConnection read

CreateNativeDatabaseAccess  protected virtual

Creates an IDANativeDatabaseAccess implementor.

function CreateNativeDatabaseAccess: IDANativeDatabaseAccess

Dataset

Access to the standard VCL TDataSet.

property Dataset: TDataset read

DoCreateNativeObject  protected virtual abstract

Creates a object specific to the given connection.

function DoCreateNativeObject: TObject

DynamicWhere  protected

Implementation of Dynamic Where.

property DynamicWhere: TDAWhereBuilder read write

Execute  protected virtual safecall abstract

Executes the SQL command.

function Execute: Integer

FindCachedParameter  protected

function FindCachedParameter(const AParams: TParams; const AParamName: string): TParam

Parameters:

  • AParams:
  • AParamName:

FindParameter  protected

Finds the AParamName parameter in the |TParams collection.

function FindParameter(const AParams: TParams; const AParamName: string): TParam

Parameters:

  • AParams:
  • AParamName:

GetDataset  protected safecall

Implements IDASQLCommand by returning the result of CreateDataset.

function GetDataset: TDataset

GetName  protected safecall

Implements IDASQLCommand by returning a value set in the constructor.

function GetName: string

GetNativeFieldData  protected virtual safecall

Sets the DataSize to the according field size value, allocates the Data memory and copies the content of the field.

function GetNativeFieldData(Index: Integer; var Buffer: TBytes): Boolean

Parameters:

  • Index: Required field index
  • Buffer:

GetNativeFieldDataType  protected safecall

Returns the field type of the Index field

function GetNativeFieldDataType(Index: Integer): TFieldType

Parameters:

  • Index: field index

GetParams  protected safecall

Implements IDASQLCommand by returning the current parameters.

function GetParams: TDAParamCollection

GetParamValues  protected virtual safecall abstract

Retrieves the values of the given parameters.

procedure GetParamValues(Params: TDAParamCollection)

Parameters:

  • Params: Parameters

GetParamValuesStd  protected

Retrieves the values from Params2 for the daptOutput, daptInputOutput and daptResult parameters of Params1.

procedure GetParamValuesStd(Params1: TDAParamCollection; Params2: TParams)

Parameters:

  • Params1: Parameters guide
  • Params2: Values source

intVCLTypeToDAType  protected virtual

Gets mapping |TFieldType to TDADataType.

function intVCLTypeToDAType(aFieldType: TFieldType; ASize: Integer; ADecimalPrecision: Integer; aDecimalScale: Integer): TDADataType

Parameters:

  • aFieldType:
  • ASize:
  • ADecimalPrecision:
  • aDecimalScale:

IsTDatasetCompatible  protected safecall

Returns true if data access object is TDataset descendant.

function IsTDatasetCompatible: Boolean

Name  protected

Returns a human-readable name for the command.

property Name: string read

NativeDatabaseAccess  protected

property NativeDatabaseAccess: IDANativeDatabaseAccess read

NativeFieldCount  protected safecall

Implements IDASQLCommandNativeObject by delegating the call to the FNativeDatabaseAccess member.

function NativeFieldCount: Integer

NativeFields  protected

property NativeFields[Index: Integer]: IDANativeField read

NativeFindField  protected safecall

Implements IDASQLCommandNativeObject by delegating the call to the FNativeDatabaseAccess member.

function NativeFindField(const FieldName: string): IDANativeField

Parameters:

  • FieldName: name of the searched field

NativeObject  protected

Access to the standard VCL |TObject which implements the data access.

property NativeObject: TObject read

OnAfterExecute

Fires right after a command was executed.

property OnAfterExecute: TDAAfterExecuteCommandEvent read write
delegate: procedure OnAfterExecute(const Sender: IDASQLCommand; ActualSQL: string; ElapsedMilliseconds: Cardinal)

OnBeforeExecute

Fires before command execution

property OnBeforeExecute: TDABeforeExecuteCommandEvent read write
delegate: procedure OnBeforeExecute(const Sender: IDASQLCommand)

OnExecuteError

Fires when exception is detected during command execution

property OnExecuteError: TDAExecuteCommandErrorEvent read write
delegate: procedure OnExecuteError(const Sender: IDASQLCommand; ActualSQL: string; Error: Exception)

ParamByName  protected safecall

Locates a specific parameter, based on its name. If no matching parameter is defined, an exception will be raised.

function ParamByName(const aName: string): TDAParam

Parameters:

  • aName: name of the parameter

Params  protected

Provides access to the list of parameters defined for the command.

property Params: TDAParamCollection read

Prepared  protected

Specifies whether the SQL statement has been prepared for execution on the database (true) or not (false). Setting this property to true will automatically prepare the statement. Preparing statements on the database server allows for faster execution, especially if the statement will be executed multiple times, as the server will not need to re-parse the SQL text for every execution. Please refer to your database system's documentation for more information on preparing statements.

Note that changing the SQL or Where properties will automatically un-prepare the statement.

property Prepared: Boolean read write

PrepareSQLStatement  protected virtual abstract

Builds a well formed SQL instruction and prepares it via DoPrepare.

procedure PrepareSQLStatement

RecreateCachedParams  protected

procedure RecreateCachedParams(aParams: TParams)

Parameters:

  • aParams:

RefreshParams  protected virtual safecall

Refreshes the list of parameters defined for the command based on the actual parameter names found in the SQL statement and Where clause.

procedure RefreshParams

SetParamValues  protected virtual safecall abstract

Converts values from Data Abstract TDAParam values.

procedure SetParamValues(Params: TDAParamCollection)

Parameters:

  • Params: parameters

SetParamValuesStd  protected

Utility method to set the values of Params2 (|TParams) for the daptOutput, daptInputOutput and daptResult parameters of Params1 (TDAParamCollection).

procedure SetParamValuesStd(Params1: TDAParamCollection; Params2: TParams)

Parameters:

  • Params1: Parameters guide
  • Params2: Values holder

SQL  protected

Defines the SQL statement to be executed.

property SQL: string read write

SQLContainsDynamicWhere  protected virtual safecall

Checks if SQL contains Dynamic Where macros.

function SQLContainsDynamicWhere: Boolean

 

CachedParams  protected

property CachedParams: TDictionary<string, Integer> read

Connection  protected

Presents the IDAConnection to access information about available databases, tables, columns, etc.

property Connection: IDAConnection read

Dataset

Access to the standard VCL TDataSet.

property Dataset: TDataset read

DynamicWhere  protected

Implementation of Dynamic Where.

property DynamicWhere: TDAWhereBuilder read write

Name  protected

Returns a human-readable name for the command.

property Name: string read

NativeDatabaseAccess  protected

property NativeDatabaseAccess: IDANativeDatabaseAccess read

NativeFields  protected

property NativeFields[Index: Integer]: IDANativeField read

NativeObject  protected

Access to the standard VCL |TObject which implements the data access.

property NativeObject: TObject read

Params  protected

Provides access to the list of parameters defined for the command.

property Params: TDAParamCollection read

Prepared  protected

Specifies whether the SQL statement has been prepared for execution on the database (true) or not (false). Setting this property to true will automatically prepare the statement. Preparing statements on the database server allows for faster execution, especially if the statement will be executed multiple times, as the server will not need to re-parse the SQL text for every execution. Please refer to your database system's documentation for more information on preparing statements.

Note that changing the SQL or Where properties will automatically un-prepare the statement.

property Prepared: Boolean read write

SQL  protected

Defines the SQL statement to be executed.

property SQL: string read write

 

constructor Create  virtual

Creates a new instance.

constructor Create(aConnection: IDAConnection; aDataset: TDataset; const aName: string)

Parameters:

  • aConnection: Connection
  • aDataset: Dataset
  • aName: Name

CanUseNativeFieldData  protected safecall

Specifies that given field can return data in GetNativeFieldData method

function CanUseNativeFieldData(Index: Integer): Boolean

Parameters:

  • Index: Required field index

ClearParams  protected virtual

Clears parameter values.

procedure ClearParams

CreateNativeDatabaseAccess  protected virtual

Creates an IDANativeDatabaseAccess implementor.

function CreateNativeDatabaseAccess: IDANativeDatabaseAccess

DoCreateNativeObject  protected virtual abstract

Creates a object specific to the given connection.

function DoCreateNativeObject: TObject

Execute  protected virtual safecall abstract

Executes the SQL command.

function Execute: Integer

FindCachedParameter  protected

function FindCachedParameter(const AParams: TParams; const AParamName: string): TParam

Parameters:

  • AParams:
  • AParamName:

FindParameter  protected

Finds the AParamName parameter in the |TParams collection.

function FindParameter(const AParams: TParams; const AParamName: string): TParam

Parameters:

  • AParams:
  • AParamName:

GetDataset  protected safecall

Implements IDASQLCommand by returning the result of CreateDataset.

function GetDataset: TDataset

GetName  protected safecall

Implements IDASQLCommand by returning a value set in the constructor.

function GetName: string

GetNativeFieldData  protected virtual safecall

Sets the DataSize to the according field size value, allocates the Data memory and copies the content of the field.

function GetNativeFieldData(Index: Integer; var Buffer: TBytes): Boolean

Parameters:

  • Index: Required field index
  • Buffer:

GetNativeFieldDataType  protected safecall

Returns the field type of the Index field

function GetNativeFieldDataType(Index: Integer): TFieldType

Parameters:

  • Index: field index

GetParams  protected safecall

Implements IDASQLCommand by returning the current parameters.

function GetParams: TDAParamCollection

GetParamValues  protected virtual safecall abstract

Retrieves the values of the given parameters.

procedure GetParamValues(Params: TDAParamCollection)

Parameters:

  • Params: Parameters

GetParamValuesStd  protected

Retrieves the values from Params2 for the daptOutput, daptInputOutput and daptResult parameters of Params1.

procedure GetParamValuesStd(Params1: TDAParamCollection; Params2: TParams)

Parameters:

  • Params1: Parameters guide
  • Params2: Values source

intVCLTypeToDAType  protected virtual

Gets mapping |TFieldType to TDADataType.

function intVCLTypeToDAType(aFieldType: TFieldType; ASize: Integer; ADecimalPrecision: Integer; aDecimalScale: Integer): TDADataType

Parameters:

  • aFieldType:
  • ASize:
  • ADecimalPrecision:
  • aDecimalScale:

IsTDatasetCompatible  protected safecall

Returns true if data access object is TDataset descendant.

function IsTDatasetCompatible: Boolean

NativeFieldCount  protected safecall

Implements IDASQLCommandNativeObject by delegating the call to the FNativeDatabaseAccess member.

function NativeFieldCount: Integer

NativeFindField  protected safecall

Implements IDASQLCommandNativeObject by delegating the call to the FNativeDatabaseAccess member.

function NativeFindField(const FieldName: string): IDANativeField

Parameters:

  • FieldName: name of the searched field

ParamByName  protected safecall

Locates a specific parameter, based on its name. If no matching parameter is defined, an exception will be raised.

function ParamByName(const aName: string): TDAParam

Parameters:

  • aName: name of the parameter

PrepareSQLStatement  protected virtual abstract

Builds a well formed SQL instruction and prepares it via DoPrepare.

procedure PrepareSQLStatement

RecreateCachedParams  protected

procedure RecreateCachedParams(aParams: TParams)

Parameters:

  • aParams:

RefreshParams  protected virtual safecall

Refreshes the list of parameters defined for the command based on the actual parameter names found in the SQL statement and Where clause.

procedure RefreshParams

SetParamValues  protected virtual safecall abstract

Converts values from Data Abstract TDAParam values.

procedure SetParamValues(Params: TDAParamCollection)

Parameters:

  • Params: parameters

SetParamValuesStd  protected

Utility method to set the values of Params2 (|TParams) for the daptOutput, daptInputOutput and daptResult parameters of Params1 (TDAParamCollection).

procedure SetParamValuesStd(Params1: TDAParamCollection; Params2: TParams)

Parameters:

  • Params1: Parameters guide
  • Params2: Values holder

SQLContainsDynamicWhere  protected virtual safecall

Checks if SQL contains Dynamic Where macros.

function SQLContainsDynamicWhere: Boolean

 

OnAfterExecute

Fires right after a command was executed.

property OnAfterExecute: TDAAfterExecuteCommandEvent read write
delegate: procedure OnAfterExecute(const Sender: IDASQLCommand; ActualSQL: string; ElapsedMilliseconds: Cardinal)

OnBeforeExecute

Fires before command execution

property OnBeforeExecute: TDABeforeExecuteCommandEvent read write
delegate: procedure OnBeforeExecute(const Sender: IDASQLCommand)

OnExecuteError

Fires when exception is detected during command execution

property OnExecuteError: TDAExecuteCommandErrorEvent read write
delegate: procedure OnExecuteError(const Sender: IDASQLCommand; ActualSQL: string; Error: Exception)