Defines a specific command that you intend to execute against a data source. More...

#include <SQLAPI.h>

Inherits SAOptions.

Public Member Functions

 SACommand ()
 Construct command with no associated connection and SQL.
 
 SACommand (SAConnection *pConnection, const SAString &sCmd=SAString(), SACommandType_t eCmdType=SA_CmdUnknown)
 Construct command based on the given connection and SQL.
 
virtual ~SACommand ()
 A destructor. More...
 
SAConnectionConnection () const
 Returns a pointer to the current SAConnection object.
 
void setConnection (SAConnection *pConnection)
 Associates a command with an existing SAConnection object.
 
virtual void Open () SQLAPI_THROW(SAException)
 Opens the specified SACommand object.
 
virtual bool isOpened ()
 Tests whether the specified SACommand object is opened.
 
virtual bool isExecuted ()
 Tests whether the specified SACommand object is executed.
 
virtual void Close () SQLAPI_THROW(SAException)
 Closes the specified SACommand object.
 
virtual void Destroy ()
 Destroys the command.
 
virtual void Reset ()
 Clears all DBMS related handles and sturctures.
 
void setCommandText (const SAString &sSQL, SACommandType_t eCmdType=SA_CmdUnknown)
 Sets the command text.
 
SAString CommandText () const
 Returns the command text associated with the SACommand object.
 
SACommandType_t CommandType () const
 Returns the command type currently associated with the SACommand object. More...
 
virtual void Prepare () SQLAPI_THROW(SAException)
 Validates and prepares the current command for execution.
 
virtual void Execute () SQLAPI_THROW(SAException)
 Executes the current command.
 
bool isResultSet () SQLAPI_THROW(SAException)
 Tests whether a result set exists after the command execution.
 
long RowsAffected () SQLAPI_THROW(SAException)
 Returns number of rows affected by last DML operation.
 
bool FetchNext () SQLAPI_THROW(SAException)
 Fetches next row from a result set.
 
bool FetchPrior () SQLAPI_THROW(SAException)
 Fetches previous row from a result set.
 
bool FetchFirst () SQLAPI_THROW(SAException)
 Fetches the first row from a result set.
 
bool FetchLast () SQLAPI_THROW(SAException)
 Fetches the last row from a result set.
 
bool FetchPos (int offset, bool Relative=false) SQLAPI_THROW(SAException)
 Fetches specified row from a result set.
 
void Cancel () SQLAPI_THROW(SAException)
 Attempts to cancel the pending result set, or current statement execution.
 
SAParamCreateParam (const SAString &sName, SADataType_t eParamType, SAParamDirType_t eDirType=SA_ParamInput)
 @ { Creates parameter associated with the specified command.
 
void DestroyParams ()
 Destroys all parameters associated with the specified command.
 
int ParamCount ()
 Returns the number of parameters associated with the SACommand object.
 
SAParamParamByIndex (int i)
 Returns the SAParam object by index in the parameters array.
 
SAParamParam (int nParamByID)
 Returns the command parameter specified by its position.
 
SAParamParam (const SAString &sParamByName)
 Returns the command parameter specified by its name.
 
int FieldCount () SQLAPI_THROW(SAException)
 Returns the number of fields (columns) in a result set.
 
SAFieldField (int nField) SQLAPI_THROW(SAException)
 Returns the column specified by its position in the result set.
 
SAFieldField (const SAString &sField) SQLAPI_THROW(SAException)
 Returns the column specified by its name in the result set.
 
SAFieldoperator[] (int nField) SQLAPI_THROW(SAException)
 Returns the column specified by its position in the result set.
 
SAFieldoperator[] (const SAString &sField) SQLAPI_THROW(SAException)
 Returns the column specified by its name in the result set.
 
virtual SAString Option (const SAString &sOptionName) const
 Returns the string value of an option.
 
saCommandHandlesNativeHandles () SQLAPI_THROW(SAException)
 Returns native DBMS client command related handle(s).
 
SACommandoperator<< (const SAPos &pos)
 Binds input variables.
 
SACommandoperator<< (const SANull &null)
 Binds input variables.
 
SACommandoperator<< (bool Value)
 Binds input variables.
 
SACommandoperator<< (short Value)
 Binds input variables.
 
SACommandoperator<< (unsigned short Value)
 Binds input variables.
 
SACommandoperator<< (long Value)
 Binds input variables.
 
SACommandoperator<< (unsigned long Value)
 Binds input variables.
 
SACommandoperator<< (double Value)
 Binds input variables.
 
SACommandoperator<< (const SANumeric &Value)
 Binds input variables.
 
SACommandoperator<< (sa_int64_t Value)
 Binds input variables.
 
SACommandoperator<< (sa_uint64_t Value)
 Binds input variables.
 
SACommandoperator<< (const SADateTime &Value)
 Binds input variables.
 
SACommandoperator<< (const SAChar *Value)
 Binds input variables.
 
SACommandoperator<< (const SAString &Value)
 Binds input variables.
 
SACommandoperator<< (const SABytes &Value)
 Binds input variables.
 
SACommandoperator<< (const SALongBinary &Value)
 Binds input variables.
 
SACommandoperator<< (const SALongChar &Value)
 Binds input variables.
 
SACommandoperator<< (const SABLob &Value)
 Binds input variables.
 
SACommandoperator<< (const SACLob &Value)
 Binds input variables.
 
SACommandoperator<< (const SAValueRead &Value)
 Binds input variables.
 
- Public Member Functions inherited from SAOptions
 SAOptions ()
 Defaut constructor.
 
virtual SAStringsetOption (const SAString &sOptionName)
 Sets a string value of a specific option. More...
 
virtual int TotalOptions () const
 Returns the count of options.
 
virtual SAString OptionName (int nIndex) const
 Returns the string value of an option.
 

Detailed Description

Defines a specific command that you intend to execute against a data source.

A SACommand object may be used to query a database and return records, insert or update data, to manipulate the structure of a database, or to run a stored procedure.

With the methods of a SACommand object you can do the following:

Remarks
You can construct command based on the given connection, or with no associated SAConnection object using appropriate SACommand constructor. If you create new command with no connection, you need to use setConnection method before executing any other SACommand methods.

To set command text use SACommand::setCommandText method. If the command has parameters, a set of SAParam objects creates implicitly. You can get the number of parameters with SACommand::ParamCount method and look them through (and assign) with SACommand::Param and SACommand::ParamByIndex methods. Values for the input parameters can also be supplied by operator <<.

To prepare a command use Prepare method. If you will not prepare a command it will be prepared implicitly before execution. If needed a command will be implicitly opened. If, for some reason, you want to open a command explicitly use SACommand::Open method. To execute a command use SACommand::Execute method. A command will be implicitly closed in destructor. If, for some reason, you want to close a command explicitly use SACommand::Close method. To test whether a command is opened use SACommand::isOpened method.

A command (an SQL statement or procedure) can have a result set after executing. To check whether a result set exists use SACommand::isResultSet method. If result set exists, a set of SAField objects created implicitly. SAField object contains full information about a field (name, type, size, etc.) and a field's value after fetching a row (SACommand::FetchNext method). You can get the number of fields with SACommand::FieldCount method and look them through with SACommand::Field method or operator [] .

If command has output parameters, you can get them after a command execution using SACommand::Param and SACommand::ParamByIndex methods.

See also
SAConnection

Constructor & Destructor Documentation

◆ ~SACommand()

SACommand::~SACommand ( )
virtual

A destructor.

Implicitly releases DBMC specific command resources and unlinks used SAConnection.

Member Function Documentation

◆ CommandType()

SACommandType_t SACommand::CommandType ( ) const

Returns the command type currently associated with the SACommand object.

Gets the command type currently associated with the SACommand object.

Returns
One of the following values from SACommandType_t enum.

The CommandType method returns the command type value that was specified in SACommand constructor or setCommandText method. If you declared the command type value as SA_CmdUnknown (the default value) then command type is detected by the Library and the CommandType method returns this detected value.

Remarks
The command type can be explicitly set in SACommand constructor and setCommandText method, but it's not necessary to do it.
See also
SACommandType_t | CommandText