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...

SAConnection *	Connection () 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...

sa_uint64_t	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...

SAParam &	ParamByIndex (int i)
	Returns the SAParam object by index in the parameters array. More...

SAParam &	Param (int nParamByID)
	Returns the command parameter specified by its position. More...

SAParam &	Param (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...

SAField &	Field (int nField) SQLAPI_THROW(SAException)
	Returns the column specified by its position in the result set. More...

SAField &	Field (const SAString &sField) SQLAPI_THROW(SAException)
	Returns the column specified by its name in the result set. More...

bool	FieldExists (const SAString &sField)
	Checks the column specified by its name in the result set.

SAField &	operator[] (int nField) SQLAPI_THROW(SAException)
	Returns the column specified by its position in the result set. More...

SAField &	operator[] (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.

saCommandHandles *	NativeHandles () SQLAPI_THROW(SAException)
	Returns native DBMS client command related handle(s). More...


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

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


SACommand &	operator<< (const SAPos &pos)
	Binds input variables. More...

SACommand &	operator<< (const SANull &null)

SACommand &	operator<< (bool Value)

SACommand &	operator<< (short Value)

SACommand &	operator<< (unsigned short Value)

SACommand &	operator<< (sa_int32_t Value)

SACommand &	operator<< (sa_uint32_t Value)

SACommand &	operator<< (double Value)

SACommand &	operator<< (const SANumeric &Value)

SACommand &	operator<< (sa_int64_t Value)

SACommand &	operator<< (sa_uint64_t Value)

SACommand &	operator<< (const SADateTime &Value)

SACommand &	operator<< (const SAChar *Value)

SACommand &	operator<< (const SAString &Value)

SACommand &	operator<< (const SABytes &Value)

SACommand &	operator<< (const SALongBinary &Value)

SACommand &	operator<< (const SALongChar &Value)

SACommand &	operator<< (const SABLob &Value)

SACommand &	operator<< (const SACLob &Value)

SACommand &	operator<< (const SAValueRead &Value)

Public Member Functions inherited from SAOptions
	SAOptions ()
	Default constructor.

virtual SAString &	setOption (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:

Associate an opened connection with a SACommand object by using its SACommand::setConnection method.
Define the executable text of the command (for example, a SELECT statement or a stored procedure name) and the command type with the SACommand::setCommandText method.
Bind query input variables assigning SAParam object(s) returning by SACommand::Param and SACommand::ParamByIndex methods, or bind input variables using stream operator <<.
Execute a command using Execute method.
Check whether a result set exists using SACommand::isResultSet method, and fetch row by row from it with the SACommand::FetchNext method. Get SAField objects with Field method and access their descriptions and values.
Receive output variables and access their values using SACommand::Param and SACommand::ParamByIndex methods.

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

sCmd	A SAString object represents command text string (an SQL statement or a stored procedure name).
eCmdType	The type of the command.

◆ 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()

sa_uint64_t 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`
	)

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

sName	A string representing the name of parameter
eParamType	Type of the parameter's value
eDirType	Type of the parameter

◆ CreateParam() [2/2]

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

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

sName	A string representing the name of parameter
eParamType	Type of the parameter's value
nNativeType	An integer value representes a code of server-specific data type, if known. Otherwise, -1
nParamSize	An integer value represents parameter's value size
nParamPrecision	An integer value represents parameter's value precision
nParamScale	An integer value represents parameter's value scale
eDirType	Type of the parameter

◆ 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

i	A 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

nParamByID A 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

sParamByName A 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

pos	A reference to the SAPos object which represents the position (by number or name) of input parameter in the command.

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 )

Parameters

null	If 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.