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

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. More...
 
void setConnection (SAConnection *pConnection)
 Associates a command with an existing SAConnection object. More...
 
virtual void Open () SQLAPI_THROW(SAException)
 Opens the specified SACommand object. More...
 
virtual bool isOpened ()
 Tests whether the specified SACommand object is opened. More...
 
virtual bool isExecuted ()
 Tests whether the specified SACommand object is executed.
 
virtual void Close () SQLAPI_THROW(SAException)
 Closes the specified SACommand object. More...
 
virtual void Destroy ()
 Destroys the command. More...
 
virtual void Reset ()
 Clears all DBMS related handles and structures. More...
 
void setCommandText (const SAString &sSQL, SACommandType_t eCmdType=SA_CmdUnknown)
 Sets the command text. More...
 
SAString CommandText () const
 Returns the command text associated with the SACommand object. More...
 
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. More...
 
virtual void Execute () SQLAPI_THROW(SAException)
 Executes the current command. More...
 
bool isResultSet () SQLAPI_THROW(SAException)
 Tests whether a result set exists after the command execution. More...
 
long RowsAffected () SQLAPI_THROW(SAException)
 Returns number of rows affected by last DML operation. More...
 
bool FetchNext () SQLAPI_THROW(SAException)
 Fetches next row from a result set. More...
 
bool FetchPrior () SQLAPI_THROW(SAException)
 Fetches the previous row from a result set. More...
 
bool FetchFirst () SQLAPI_THROW(SAException)
 Fetches the first row from a result set. More...
 
bool FetchLast () SQLAPI_THROW(SAException)
 Fetches the last row from a result set. More...
 
bool FetchPos (int offset, bool Relative=false) SQLAPI_THROW(SAException)
 Fetches the specified row from a result set. More...
 
void Cancel () SQLAPI_THROW(SAException)
 Attempts to cancel the pending result set, or current statement execution. More...
 
void DestroyParams ()
 Destroys all parameters associated with the specified command. More...
 
int ParamCount ()
 Returns the number of parameters associated with the SACommand object. More...
 
SAParamParamByIndex (int i)
 Returns the SAParam object by index in the parameters array. More...
 
SAParamParam (int nParamByID)
 Returns the command parameter specified by its position. More...
 
SAParamParam (const SAString &sParamByName)
 Returns the command parameter specified by its name. More...
 
int FieldCount () SQLAPI_THROW(SAException)
 Returns the number of fields (columns) in a result set. More...
 
SAFieldField (int nField) SQLAPI_THROW(SAException)
 Returns the column specified by its position in the result set. More...
 
SAFieldField (const SAString &sField) SQLAPI_THROW(SAException)
 Returns the column specified by its name in the result set. More...
 
SAFieldoperator[] (int nField) SQLAPI_THROW(SAException)
 Returns the column specified by its position in the result set. More...
 
SAFieldoperator[] (const SAString &sField) SQLAPI_THROW(SAException)
 Returns the column specified by its name in the result set. More...
 
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). More...
 
SAParamCreateParam (const SAString &sName, SADataType_t eParamType, SAParamDirType_t eDirType=SA_ParamInput)
 Type of the parameter. More...
 
SAParamCreateParam (const SAString &sName, SADataType_t eParamType, int nNativeType, size_t nParamSize, int nParamPrecision, int nParamScale, SAParamDirType_t eDirType)
 Type of the parameter. More...
 
SACommandoperator<< (const SAPos &pos)
 Binds input variables. More...
 
SACommandoperator<< (const SANull &null)
 Binds input variables. More...
 
SACommandoperator<< (bool Value)
 Binds input variables. More...
 
SACommandoperator<< (short Value)
 Binds input variables. More...
 
SACommandoperator<< (unsigned short Value)
 Binds input variables. More...
 
SACommandoperator<< (long Value)
 Binds input variables. More...
 
SACommandoperator<< (unsigned long Value)
 Binds input variables. More...
 
SACommandoperator<< (double Value)
 Binds input variables. More...
 
SACommandoperator<< (const SANumeric &Value)
 Binds input variables. More...
 
SACommandoperator<< (sa_int64_t Value)
 Binds input variables. More...
 
SACommandoperator<< (sa_uint64_t Value)
 Binds input variables. More...
 
SACommandoperator<< (const SADateTime &Value)
 Binds input variables. More...
 
SACommandoperator<< (const SAChar *Value)
 Binds input variables. More...
 
SACommandoperator<< (const SAString &Value)
 Binds input variables. More...
 
SACommandoperator<< (const SABytes &Value)
 Binds input variables. More...
 
SACommandoperator<< (const SALongBinary &Value)
 Binds input variables. More...
 
SACommandoperator<< (const SALongChar &Value)
 Binds input variables. More...
 
SACommandoperator<< (const SABLob &Value)
 Binds input variables. More...
 
SACommandoperator<< (const SACLob &Value)
 Binds input variables. More...
 
SACommandoperator<< (const SAValueRead &Value)
 Binds input variables. More...
 
- Public Member Functions inherited from SAOptions
 SAOptions ()
 Default 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 DBMS specific command resources and unlinks used SAConnection.

Member Function Documentation

◆ Connection()

SAConnection * SACommand::Connection ( ) const

Returns a pointer to the current SAConnection object.

Indicates to which SAConnection object the specified SACommand object currently belongs.

Remarks
Use the Connection method to determine the SAConnection object associated whith the specified SACommand object.

To associate connection with the command call SACommand::setConnection method. Connection can also be associated in SACommand object constructor.

If you attempt to call any method on a SACommand object that requires database access with no valid connection, an error occurs.

See also
SACommand::setConnection SAConnection

◆ setConnection()

void SACommand::setConnection ( SAConnection pConnection)

Associates a command with an existing SAConnection object.

Remarks
Use the setConnection method to associate SACommand and SAConnection objects. Only one connection can be associated with a command.

Connection for the command can also be set in a SACommand constructor.

To get associated SAConnection object use Connection method.

When you call setConnection method on SACommand object that already has associated connection, the previous association will be correctly discarded (with closing opened command if needed) and new connection will be set.

If you attempt to call any method on a SACommand object that requires database access with no valid connection, an error occurs.

See also
SAConnection

◆ Open()

void SACommand::Open ( )
virtual

Opens the specified SACommand object.

Remarks
Use the method to open the command explicitly.

A command will be implicitly opened by any method that needs an open command, therefore you don't have to call it explicitly.

To test whether a command is opened use SACommand::isOpened method.

Exceptions
SAException
See also
SACommand::isOpened SACommand::Close

◆ isOpened()

bool SACommand::isOpened ( )
virtual

Tests whether the specified SACommand object is opened.

Returns

Returns true if the SACommand object is opened; otherwise false.
See also
SACommand::Open SACommand::Close

◆ Close()

void SACommand::Close ( )
virtual

Closes the specified SACommand object.

Remarks
Use the method to close the command explicitly.

A command will be implicitly closed in destructor, so you don't have to call Close method explicitly.

Exceptions
SAException
See also
SACommand::isOpened SACommand::Open

◆ Destroy()

void SACommand::Destroy ( )
virtual

Destroys the command.

Closes the specified SACommand object without throwing SAException.

Remarks
The method closes the command explicitly like SACommand::Close but doesn't throw SAException.
See also
SACommand::isOpened SACommand::Open SACommand::Close

◆ Reset()

void SACommand::Reset ( )
virtual

Clears all DBMS related handles and structures.

Clears all DBMS related handles and sturctures but doesn't destroy them.

Remarks
Useful for Unix fork/exec based applications. Just the object is reset the copy (and databases resources) can be used by the child process.

◆ setCommandText()

void SACommand::setCommandText ( const SAString sCmd,
SACommandType_t  eCmdType = SA_CmdUnknown 
)

Sets the command text.

Remarks
Use the method to set the command text. Command text can also be set in SACommand constructor.

It's not necessary to set a command type explicitly, because it is defined automatically in terms of command text string. But if you still have any reason to do it, use one of the SACommandType_t constants. To get command type use CommandType method.

If the command is an SQL statement and it has parameters, a set of SAParam objects creates implicitly.

See also
SACommand::CommandType SAString SAParam SACommandType_t
Parameters
sCmdA SAString object represents command text string (an SQL statement or a stored procedure name).

◆ CommandText()

SAString SACommand::CommandText ( ) const

Returns the command text associated with the SACommand object.

Returns
The SAString object represents the command text.
Remarks
Use the method to return the command text declared in SACommand constructor or setCommandText method.
See also
SACommand::setCommandText SACommand::CommandType SAString

◆ 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

◆ Prepare()

void SACommand::Prepare ( )
virtual

Validates and prepares the current command for execution.

Remarks
The method compiles the command, but does not execute it. The method detects syntax errors in command text and verifies the existence of database objects.

Execute method calls SACommand::Prepare method implicitly if needed, therefore you don't have to call it explicitly.

See also
SACommand::Execute

◆ Execute()

void SACommand::Execute ( )
virtual

Executes the current command.

Remarks
Use the method to execute the query or stored procedure specified in the command text. Execute method calls SACommand::Prepare method implicitly if needed. If the command has input parameters, they should be bound before calling SACommand::Execute method. Input parameters represented by SAParam object. To bind input variables assign a value to SAParam object returning by SACommand::Param or SACommand::ParamByIndex methods or bind input variables using stream operator <<.

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 is created after command execution. Rows from the result set can be fetched one by one using SACommand::FetchNext method. To get field description or value use Field method.

Output parameters represented by SAParam objects. They are available after command execution. To get parameter description or value use SACommand::Param or SACommand::ParamByIndex methods.

See also
SACommand::setCommandText SACommand::Prepare SACommand::RowsAffected SACommand::isResultSet SACommand::FetchNext SAParam SAField

◆ isResultSet()

bool SACommand::isResultSet ( )

Tests whether a result set exists after the command execution.

Returns
True if the result set exists; otherwise false.
See also
SACommand::Execute SACommand::FieldCount SACommand::Field SAField

◆ RowsAffected()

long SACommand::RowsAffected ( )

Returns number of rows affected by last DML operation.

Returns the number of rows affected by the last insert/update/delete command execution.

Remarks
Can also return the result set rows count, usually when the result set is cached at the client side.

◆ FetchNext()

bool SACommand::FetchNext ( )

Fetches next row from a result set.

Returns
True if the next row was fetched; otherwise false.
Remarks
Use the method to fetch row by row from the result set.

Each column of fetched row is represented by SAField object. If a result set exists after the last command execution, a set of SAField objects is created implicitly. To check whether a result set exists use isResultSet method. The method updates value parts of SAField objects.

To get field description or value use SACommand::Field method.

See also
SACommand::isResultSet SACommand::Field SACommand::FieldCount SAField

◆ FetchPrior()

bool SACommand::FetchPrior ( )

Fetches the previous row from a result set.

Returns
True if the row was fetched; otherwise false.
Remarks
Use the method to fetch the previous row from the result set.

Fething the previous result set row is possible only for the scrollable result set. The related SACommand option should be set before the command executed if it's mentioned in the Server Specific Guides

See also
SACommand::isResultSet SACommand::Field SACommand::FieldCount SAField

◆ FetchFirst()

bool SACommand::FetchFirst ( )

Fetches the first row from a result set.

Returns
True if the row was fetched; otherwise false.
Remarks
Use the method to fetch the first row from the result set.

Fething the previous result set row is possible only for the scrollable result set. The related SACommand option should be set before the command executed if it's mentioned in the Server Specific Guides

See also
SACommand::isResultSet SACommand::Field SACommand::FieldCount SAField

◆ FetchLast()

bool SACommand::FetchLast ( )

Fetches the last row from a result set.

Returns
True if the row was fetched; otherwise false.
Remarks
Use the method to fetch the last row from the result set.

Fething the previous result set row is possible only for the scrollable result set. The related SACommand option should be set before the command executed if it's mentioned in the Server Specific Guides

See also
SACommand::isResultSet SACommand::Field SACommand::FieldCount SAField

◆ FetchPos()

bool SACommand::FetchPos ( int  offset,
bool  Relative = false 
)

Fetches the specified row from a result set.

Returns
True if the row was fetched; otherwise false.
Remarks
Use the method to fetch the row from the specified result set position.

Fething the previous result set row is possible only for the scrollable result set. The related SACommand option should be set before the command executed if it's mentioned in the Server Specific Guides

See also
SACommand::isResultSet SACommand::Field SACommand::FieldCount SAField

◆ Cancel()

void SACommand::Cancel ( )

Attempts to cancel the pending result set, or current statement execution.

The exact definition is vendor-dependent.

Remarks
The method can cancel the following types of processing on a statement:

A function running asynchronously on the statement. A function running on the statement on another thread. After an application calls a function asynchronously, it checks repeatedly to determine whether it has finished processing. While the function is processing, an application can call SACommand::Cancel to cancel the function.

In a multithread application, the application can cancel a function that is running synchronously on a statement.

See also
Server Specific Guides

◆ CreateParam() [1/2]

SAParam & SACommand::CreateParam ( const SAString sName,
SADataType_t  eParamType,
SAParamDirType_t  eDirType = SA_ParamInput 
)

Type of the parameter.

Creates parameter associated with the specified command.

Returns
A reference to a SAParam object.
Remarks
Normally you should not create parameters by yourself. The Library automatically detects whether the command has parameters in terms of the command text and implicitly creates a set of SAParam objects.

Nevertheless, if you call SACommand::CreateParam explicitly you have to delete all SAParam objects created automatically by the Library before. Use SACommand::DestroyParams method before the first call of SACommand::CreateParam method.

See also
SACommand::DestroyParams SACommand::CommandText SACommand::setCommandText SACommand::CommandType SAParam
Parameters
sNameA string representing the name of parameter
eParamTypeType of the parameter's value

◆ CreateParam() [2/2]

SAParam & SACommand::CreateParam ( const SAString sName,
SADataType_t  eParamType,
int  nNativeType,
size_t  nParamSize,
int  nParamPrecision,
int  nParamScale,
SAParamDirType_t  eDirType 
)

Type of the parameter.

Returns
A reference to a SAParam object.
Remarks
Normally you should not create parameters by yourself. The Library automatically detects whether the command has parameters in terms of the command text and implicitly creates a set of SAParam objects.

Nevertheless, if you call SACommand::CreateParam explicitly you have to delete all SAParam objects created automatically by the Library before. Use SACommand::DestroyParams method before the first call of SACommand::CreateParam method.

See also
SACommand::DestroyParams SACommand::CommandText SACommand::setCommandText SACommand::CommandType SAParam
Parameters
sNameA string representing the name of parameter
eParamTypeType of the parameter's value
nNativeTypeAn integer value representes a code of server-specific data type, if known. Otherwise, -1
nParamSizeAn integer value represents parameter's value size
nParamPrecisionAn integer value represents parameter's value precision
nParamScaleAn integer value represents parameter's value scale

◆ DestroyParams()

void SACommand::DestroyParams ( )

Destroys all parameters associated with the specified command.

Remarks
The method destroys all parameters either created automatically by the Library or by user.

Normally you should not create and delete parameters by yourself. The Library automatically detects whether the command has parameters, implicitly creates a set of SAParam objects and then deletes them in SACommand destructor.

See also
SACommand::CreateParam SAParam

◆ ParamCount()

int SACommand::ParamCount ( )

Returns the number of parameters associated with the SACommand object.

Remarks
The method returns the number of parameters created explicitly by using SACommand::CreateParam method or (if parameters were not created before) creates them implicitly (can query native API if needed and therefore can throw exception on error) and returns the number of created parameters.

Command parameter is represented by SAParam object. You can look SAParam objects through and assign their values with SACommand::Param and SACommand::ParamByIndex methods. Values for the input parameters can also be supplied by operator << .

See also
SACommand::setCommandText SACommand::CreateParam SACommand::Param SACommand::ParamByIndex SAParam

◆ ParamByIndex()

SAParam & SACommand::ParamByIndex ( int  i)

Returns the SAParam object by index in the parameters array.

Parameters
iA zero-based index of the requested parameter in the array of SAParam objects. It must be greater than or equal to 0 and 1 less than the value returned by SACommand::ParamCount method.
Returns
A reference to a SAParam object.
Remarks
Normally you should use SACommand::Param method to access a parameter by its name or position (in SQL statement). SACommand::ParamByIndex method can be used if, for example, you want to walk through all the parameters.

If parameters were not created before calling SACommand::ParamParamByIndex method the Library creates them implicitly (can query native API if needed and therefore can throw exception on error) and then returns the specified parameter.

Passing a negative value of index or a value greater or equal than the value returned by SACommand::ParamParamCount method will result in a failed assertion.

SAParam object contains full information about a parameter: name, type, size, etc. Values for the input parameters can be assigned to SAParam object or supplied by operator << .

See also
SACommand::CreateParam SACommand::Param SACommand::ParamCount SAParam

◆ Param() [1/2]

SAParam & SACommand::Param ( int  nParamByID)

Returns the command parameter specified by its position.

Returns
The command parameter specified by its position.
Parameters
nParamByIDA position of parameter specified in the command text. Normally position is a number stated in the command text after a colon (for example, 1 for :1, 5 for :5).
Returns
A reference to a SAParam object.
Remarks
Use the method to access a parameter by its position (in SQL statement). If, for example, you want to walk through all the parameters use SACommand::ParamByIndex method.

If parameters were not created before calling SACommand::Param method the Library creates them implicitly (can query native API if needed and therefore can throw exception on error) and then returns the specified parameter.

Passing a value of name or position which does not specified in the command text will throw an exception.

SAParam object contains full information about a parameter: name, type, size, etc. Values for the input parameters can be assigned to SAParam object or supplied by operator << .

See also
SACommand::CreateParam SACommand::ParamByIndex SACommand::ParamCount SAParam

◆ Param() [2/2]

SAParam & SACommand::Param ( const SAString sParamByName)

Returns the command parameter specified by its name.

Returns
The command parameter specified by its name.
Parameters
sParamByNameA string that represents a name of the requested parameter. Normally name is a string stated in the command text after a colon (for example, 'city' for :city, 'my city' for :"my city") or a parameter name in a stored procedure or function.
Returns
A reference to a SAParam object.
Remarks
Use the method to access a parameter by its name (in SQL statement). If, for example, you want to walk through all the parameters use SACommand::ParamByIndex method.

If parameters were not created before calling SACommand::Param method the Library creates them implicitly (can query native API if needed and therefore can throw exception on error) and then returns the specified parameter.

Passing a value of name or position which does not specified in the command text will throw an exception.

SAParam object contains full information about a parameter: name, type, size, etc. Values for the input parameters can be assigned to SAParam object or supplied by operator << .

See also
SACommand::CreateParam SACommand::ParamByIndex SACommand::ParamCount SAParam

◆ operator<<() [1/20]

SACommand & SACommand::operator<< ( const SAPos pos)

Binds input variables.

Parameters
posA reference to the SAPos object which represents the position (by number or name) of input parameter in the command.
nullIf you want to assign null value to an input variable you have to include SANull object in the chain of bind operators in place of null value.
ValueA value of an input variable.
LongValueA reference to an aiding object representing a value of a long input variable or a callback function which will be used for getting the long value.
LobValueA reference to an aiding object representing a value of a Lob input variable or a callback function which will be used for getting the Lob value.
Remarks
This operator is used for associating data objects to the command object. Every command object maintains an internal heterogeneous array of parameter objects - this operator assigns values to parameter objects from this array.

Because of the operator returns a reference to a SACommand object you can chain the operator e.g. cmd << 3 << 2.5 << "Istanbul";

◆ operator<<() [2/20]

SACommand & SACommand::operator<< ( const SANull null)

Binds input variables.

Parameters
posA reference to the SAPos object which represents the position (by number or name) of input parameter in the command.
nullIf you want to assign null value to an input variable you have to include SANull object in the chain of bind operators in place of null value.
ValueA value of an input variable.
LongValueA reference to an aiding object representing a value of a long input variable or a callback function which will be used for getting the long value.
LobValueA reference to an aiding object representing a value of a Lob input variable or a callback function which will be used for getting the Lob value.
Remarks
This operator is used for associating data objects to the command object. Every command object maintains an internal heterogeneous array of parameter objects - this operator assigns values to parameter objects from this array.

Because of the operator returns a reference to a SACommand object you can chain the operator e.g. cmd << 3 << 2.5 << "Istanbul";

◆ operator<<() [3/20]

SACommand & SACommand::operator<< ( bool  Value)

Binds input variables.

Parameters
posA reference to the SAPos object which represents the position (by number or name) of input parameter in the command.
nullIf you want to assign null value to an input variable you have to include SANull object in the chain of bind operators in place of null value.
ValueA value of an input variable.
LongValueA reference to an aiding object representing a value of a long input variable or a callback function which will be used for getting the long value.
LobValueA reference to an aiding object representing a value of a Lob input variable or a callback function which will be used for getting the Lob value.
Remarks
This operator is used for associating data objects to the command object. Every command object maintains an internal heterogeneous array of parameter objects - this operator assigns values to parameter objects from this array.

Because of the operator returns a reference to a SACommand object you can chain the operator e.g. cmd << 3 << 2.5 << "Istanbul";

◆ operator<<() [4/20]

SACommand & SACommand::operator<< ( short  Value)

Binds input variables.

Parameters
posA reference to the SAPos object which represents the position (by number or name) of input parameter in the command.
nullIf you want to assign null value to an input variable you have to include SANull object in the chain of bind operators in place of null value.
ValueA value of an input variable.
LongValueA reference to an aiding object representing a value of a long input variable or a callback function which will be used for getting the long value.
LobValueA reference to an aiding object representing a value of a Lob input variable or a callback function which will be used for getting the Lob value.
Remarks
This operator is used for associating data objects to the command object. Every command object maintains an internal heterogeneous array of parameter objects - this operator assigns values to parameter objects from this array.

Because of the operator returns a reference to a SACommand object you can chain the operator e.g. cmd << 3 << 2.5 << "Istanbul";

◆ operator<<() [5/20]

SACommand & SACommand::operator<< ( unsigned short  Value)

Binds input variables.

Parameters
posA reference to the SAPos object which represents the position (by number or name) of input parameter in the command.
nullIf you want to assign null value to an input variable you have to include SANull object in the chain of bind operators in place of null value.
ValueA value of an input variable.
LongValueA reference to an aiding object representing a value of a long input variable or a callback function which will be used for getting the long value.
LobValueA reference to an aiding object representing a value of a Lob input variable or a callback function which will be used for getting the Lob value.
Remarks
This operator is used for associating data objects to the command object. Every command object maintains an internal heterogeneous array of parameter objects - this operator assigns values to parameter objects from this array.

Because of the operator returns a reference to a SACommand object you can chain the operator e.g. cmd << 3 << 2.5 << "Istanbul";

◆ operator<<() [6/20]

SACommand & SACommand::operator<< ( long  Value)

Binds input variables.

Parameters
posA reference to the SAPos object which represents the position (by number or name) of input parameter in the command.
nullIf you want to assign null value to an input variable you have to include SANull object in the chain of bind operators in place of null value.
ValueA value of an input variable.
LongValueA reference to an aiding object representing a value of a long input variable or a callback function which will be used for getting the long value.
LobValueA reference to an aiding object representing a value of a Lob input variable or a callback function which will be used for getting the Lob value.
Remarks
This operator is used for associating data objects to the command object. Every command object maintains an internal heterogeneous array of parameter objects - this operator assigns values to parameter objects from this array.

Because of the operator returns a reference to a SACommand object you can chain the operator e.g. cmd << 3 << 2.5 << "Istanbul";

◆ operator<<() [7/20]

SACommand & SACommand::operator<< ( unsigned long  Value)

Binds input variables.

Parameters
posA reference to the SAPos object which represents the position (by number or name) of input parameter in the command.
nullIf you want to assign null value to an input variable you have to include SANull object in the chain of bind operators in place of null value.
ValueA value of an input variable.
LongValueA reference to an aiding object representing a value of a long input variable or a callback function which will be used for getting the long value.
LobValueA reference to an aiding object representing a value of a Lob input variable or a callback function which will be used for getting the Lob value.
Remarks
This operator is used for associating data objects to the command object. Every command object maintains an internal heterogeneous array of parameter objects - this operator assigns values to parameter objects from this array.

Because of the operator returns a reference to a SACommand object you can chain the operator e.g. cmd << 3 << 2.5 << "Istanbul";

◆ operator<<() [8/20]

SACommand & SACommand::operator<< ( double  Value)

Binds input variables.

Parameters
posA reference to the SAPos object which represents the position (by number or name) of input parameter in the command.
nullIf you want to assign null value to an input variable you have to include SANull object in the chain of bind operators in place of null value.
ValueA value of an input variable.
LongValueA reference to an aiding object representing a value of a long input variable or a callback function which will be used for getting the long value.
LobValueA reference to an aiding object representing a value of a Lob input variable or a callback function which will be used for getting the Lob value.
Remarks
This operator is used for associating data objects to the command object. Every command object maintains an internal heterogeneous array of parameter objects - this operator assigns values to parameter objects from this array.

Because of the operator returns a reference to a SACommand object you can chain the operator e.g. cmd << 3 << 2.5 << "Istanbul";

◆ operator<<() [9/20]

SACommand & SACommand::operator<< ( const SANumeric Value)

Binds input variables.

Parameters
posA reference to the SAPos object which represents the position (by number or name) of input parameter in the command.
nullIf you want to assign null value to an input variable you have to include SANull object in the chain of bind operators in place of null value.
ValueA value of an input variable.
LongValueA reference to an aiding object representing a value of a long input variable or a callback function which will be used for getting the long value.
LobValueA reference to an aiding object representing a value of a Lob input variable or a callback function which will be used for getting the Lob value.
Remarks
This operator is used for associating data objects to the command object. Every command object maintains an internal heterogeneous array of parameter objects - this operator assigns values to parameter objects from this array.

Because of the operator returns a reference to a SACommand object you can chain the operator e.g. cmd << 3 << 2.5 << "Istanbul";

◆ operator<<() [10/20]

SACommand & SACommand::operator<< ( sa_int64_t  Value)

Binds input variables.

Parameters
posA reference to the SAPos object which represents the position (by number or name) of input parameter in the command.
nullIf you want to assign null value to an input variable you have to include SANull object in the chain of bind operators in place of null value.
ValueA value of an input variable.
LongValueA reference to an aiding object representing a value of a long input variable or a callback function which will be used for getting the long value.
LobValueA reference to an aiding object representing a value of a Lob input variable or a callback function which will be used for getting the Lob value.
Remarks
This operator is used for associating data objects to the command object. Every command object maintains an internal heterogeneous array of parameter objects - this operator assigns values to parameter objects from this array.

Because of the operator returns a reference to a SACommand object you can chain the operator e.g. cmd << 3 << 2.5 << "Istanbul";

◆ operator<<() [11/20]

SACommand & SACommand::operator<< ( sa_uint64_t  Value)

Binds input variables.

Parameters
posA reference to the SAPos object which represents the position (by number or name) of input parameter in the command.
nullIf you want to assign null value to an input variable you have to include SANull object in the chain of bind operators in place of null value.
ValueA value of an input variable.
LongValueA reference to an aiding object representing a value of a long input variable or a callback function which will be used for getting the long value.
LobValueA reference to an aiding object representing a value of a Lob input variable or a callback function which will be used for getting the Lob value.
Remarks
This operator is used for associating data objects to the command object. Every command object maintains an internal heterogeneous array of parameter objects - this operator assigns values to parameter objects from this array.

Because of the operator returns a reference to a SACommand object you can chain the operator e.g. cmd << 3 << 2.5 << "Istanbul";

◆ operator<<() [12/20]

SACommand & SACommand::operator<< ( const SADateTime Value)

Binds input variables.

Parameters
posA reference to the SAPos object which represents the position (by number or name) of input parameter in the command.
nullIf you want to assign null value to an input variable you have to include SANull object in the chain of bind operators in place of null value.
ValueA value of an input variable.
LongValueA reference to an aiding object representing a value of a long input variable or a callback function which will be used for getting the long value.
LobValueA reference to an aiding object representing a value of a Lob input variable or a callback function which will be used for getting the Lob value.
Remarks
This operator is used for associating data objects to the command object. Every command object maintains an internal heterogeneous array of parameter objects - this operator assigns values to parameter objects from this array.

Because of the operator returns a reference to a SACommand object you can chain the operator e.g. cmd << 3 << 2.5 << "Istanbul";

◆ operator<<() [13/20]

SACommand & SACommand::operator<< ( const SAChar Value)

Binds input variables.

Parameters
posA reference to the SAPos object which represents the position (by number or name) of input parameter in the command.
nullIf you want to assign null value to an input variable you have to include SANull object in the chain of bind operators in place of null value.
ValueA value of an input variable.
LongValueA reference to an aiding object representing a value of a long input variable or a callback function which will be used for getting the long value.
LobValueA reference to an aiding object representing a value of a Lob input variable or a callback function which will be used for getting the Lob value.
Remarks
This operator is used for associating data objects to the command object. Every command object maintains an internal heterogeneous array of parameter objects - this operator assigns values to parameter objects from this array.

Because of the operator returns a reference to a SACommand object you can chain the operator e.g. cmd << 3 << 2.5 << "Istanbul";

◆ operator<<() [14/20]

SACommand & SACommand::operator<< ( const SAString Value)

Binds input variables.

Parameters
posA reference to the SAPos object which represents the position (by number or name) of input parameter in the command.
nullIf you want to assign null value to an input variable you have to include SANull object in the chain of bind operators in place of null value.
ValueA value of an input variable.
LongValueA reference to an aiding object representing a value of a long input variable or a callback function which will be used for getting the long value.
LobValueA reference to an aiding object representing a value of a Lob input variable or a callback function which will be used for getting the Lob value.
Remarks
This operator is used for associating data objects to the command object. Every command object maintains an internal heterogeneous array of parameter objects - this operator assigns values to parameter objects from this array.

Because of the operator returns a reference to a SACommand object you can chain the operator e.g. cmd << 3 << 2.5 << "Istanbul";

◆ operator<<() [15/20]

SACommand & SACommand::operator<< ( const SABytes Value)

Binds input variables.

Parameters
posA reference to the SAPos object which represents the position (by number or name) of input parameter in the command.
nullIf you want to assign null value to an input variable you have to include SANull object in the chain of bind operators in place of null value.
ValueA value of an input variable.
LongValueA reference to an aiding object representing a value of a long input variable or a callback function which will be used for getting the long value.
LobValueA reference to an aiding object representing a value of a Lob input variable or a callback function which will be used for getting the Lob value.
Remarks
This operator is used for associating data objects to the command object. Every command object maintains an internal heterogeneous array of parameter objects - this operator assigns values to parameter objects from this array.

Because of the operator returns a reference to a SACommand object you can chain the operator e.g. cmd << 3 << 2.5 << "Istanbul";

◆ operator<<() [16/20]

SACommand & SACommand::operator<< ( const SALongBinary Value)

Binds input variables.

Parameters
posA reference to the SAPos object which represents the position (by number or name) of input parameter in the command.
nullIf you want to assign null value to an input variable you have to include SANull object in the chain of bind operators in place of null value.
ValueA value of an input variable.
LongValueA reference to an aiding object representing a value of a long input variable or a callback function which will be used for getting the long value.
LobValueA reference to an aiding object representing a value of a Lob input variable or a callback function which will be used for getting the Lob value.
Remarks
This operator is used for associating data objects to the command object. Every command object maintains an internal heterogeneous array of parameter objects - this operator assigns values to parameter objects from this array.

Because of the operator returns a reference to a SACommand object you can chain the operator e.g. cmd << 3 << 2.5 << "Istanbul";

◆ operator<<() [17/20]

SACommand & SACommand::operator<< ( const SALongChar Value)

Binds input variables.

Parameters
posA reference to the SAPos object which represents the position (by number or name) of input parameter in the command.
nullIf you want to assign null value to an input variable you have to include SANull object in the chain of bind operators in place of null value.
ValueA value of an input variable.
LongValueA reference to an aiding object representing a value of a long input variable or a callback function which will be used for getting the long value.
LobValueA reference to an aiding object representing a value of a Lob input variable or a callback function which will be used for getting the Lob value.
Remarks
This operator is used for associating data objects to the command object. Every command object maintains an internal heterogeneous array of parameter objects - this operator assigns values to parameter objects from this array.

Because of the operator returns a reference to a SACommand object you can chain the operator e.g. cmd << 3 << 2.5 << "Istanbul";

◆ operator<<() [18/20]

SACommand & SACommand::operator<< ( const SABLob Value)

Binds input variables.

Parameters
posA reference to the SAPos object which represents the position (by number or name) of input parameter in the command.
nullIf you want to assign null value to an input variable you have to include SANull object in the chain of bind operators in place of null value.
ValueA value of an input variable.
LongValueA reference to an aiding object representing a value of a long input variable or a callback function which will be used for getting the long value.
LobValueA reference to an aiding object representing a value of a Lob input variable or a callback function which will be used for getting the Lob value.
Remarks
This operator is used for associating data objects to the command object. Every command object maintains an internal heterogeneous array of parameter objects - this operator assigns values to parameter objects from this array.

Because of the operator returns a reference to a SACommand object you can chain the operator e.g. cmd << 3 << 2.5 << "Istanbul";

◆ operator<<() [19/20]

SACommand & SACommand::operator<< ( const SACLob Value)

Binds input variables.

Parameters
posA reference to the SAPos object which represents the position (by number or name) of input parameter in the command.
nullIf you want to assign null value to an input variable you have to include SANull object in the chain of bind operators in place of null value.
ValueA value of an input variable.
LongValueA reference to an aiding object representing a value of a long input variable or a callback function which will be used for getting the long value.
LobValueA reference to an aiding object representing a value of a Lob input variable or a callback function which will be used for getting the Lob value.
Remarks
This operator is used for associating data objects to the command object. Every command object maintains an internal heterogeneous array of parameter objects - this operator assigns values to parameter objects from this array.

Because of the operator returns a reference to a SACommand object you can chain the operator e.g. cmd << 3 << 2.5 << "Istanbul";

◆ operator<<() [20/20]

SACommand & SACommand::operator<< ( const SAValueRead Value)

Binds input variables.

Parameters
posA reference to the SAPos object which represents the position (by number or name) of input parameter in the command.
nullIf you want to assign null value to an input variable you have to include SANull object in the chain of bind operators in place of null value.
ValueA value of an input variable.
LongValueA reference to an aiding object representing a value of a long input variable or a callback function which will be used for getting the long value.
LobValueA reference to an aiding object representing a value of a Lob input variable or a callback function which will be used for getting the Lob value.
Remarks
This operator is used for associating data objects to the command object. Every command object maintains an internal heterogeneous array of parameter objects - this operator assigns values to parameter objects from this array.

Because of the operator returns a reference to a SACommand object you can chain the operator e.g. cmd << 3 << 2.5 << "Istanbul";

◆ FieldCount()

int SACommand::FieldCount ( )

Returns the number of fields (columns) in a result set.

Remarks
The method returns the number of fields created implicitly after the command execution if a result set exists.

A field is represented by SAField object. You can get field value and description using Field method or operator [ ] .

See also
SACommand::Field SAField

◆ Field() [1/2]

SAField & SACommand::Field ( int  nField)

Returns the column specified by its position in the result set.

Parameters
nFieldA one-based field number in a result set.
Returns
A reference to a SAField object.
Remarks
Use the method to access a field by its position in the result set.

Using nField value smaller than 1 and greater then the value returned by SACommand::FieldCount method will result in a failed assertion.

A set of SAField objects creates implicitly after the command execution if the result set exists. SAField object contains full information about a column: name, type, size, value. SAField object can also be gotten by operator [ ] .

See also
SACommand::FieldCount SAField

◆ Field() [2/2]

SAField & SACommand::Field ( const SAString sField)

Returns the column specified by its name in the result set.

Parameters
sFieldA string that represents a name of the requested field.
Returns
A reference to a SAField object.
Remarks
Use the method to access a field by its name in the result set.

Using a non-existent field name will throw an exception.

A set of SAField objects creates implicitly after the command execution if the result set exists. SAField object contains full information about a column: name, type, size, value. SAField object can also be gotten by operator [ ] .

See also
SAField

◆ operator[]() [1/2]

SAField & SACommand::operator[] ( int  nField)

Returns the column specified by its position in the result set.

Parameters
nFieldA one-based field number in a result set.
Returns
A reference to a SAField object.
Remarks
Use the method to access a field by its position in the result set.
See also
SACommand::Field

◆ operator[]() [2/2]

SAField & SACommand::operator[] ( const SAString sField)

Returns the column specified by its name in the result set.

Parameters
sFieldA string that represents a name of the requested field.
Returns
A reference to a SAField object.
Remarks
Use the method to access a field by its name in the result set.
See also
SACommand::Field

◆ NativeHandles()

saCommandHandles * SACommand::NativeHandles ( )

Returns native DBMS client command related handle(s).

Returns
A pointer to a base class saCommandHandles from which a family of DBMS implementation-specific classes are derived.
Remarks
You have to use native API handles when you want to call DBMS specific API functions which are not directly supported by the Library. API functions usually need to receive one or more active handles as a parameter(s). The method returns a pointer to the set of native API command related handles. To use API handles directly you have to downcast saCommandHandles pointer to the appropriate type and use its implementation-specific members. If you need to use connection related handles see SAConnection::NativeHandles method.

See Server Specific Guides section to know what type cast you have to make and what additional header file you have to include to work with specific DBMS client API. Note that for some DBMS using appropriate type casting depends on an API version (that generally mean that you have to explicitly check client version before casting, see SAConnection::ClientVersion method).

To get more information about DBMS API functions and handles see this DBMS specific documentation.

Please be aware of the complications associated with making direct API calls, as the internal logic of the SQLAPI++ Library is not used. Besides, making direct API calls reduces an application's portability.