SAException

Library error exception class. More...

Inherited by SAUserException.

Public Member Functions
SAErrorClass_t	ErrClass () const
	Returns a class of error. More...
int	ErrNativeCode () const
	Returns a native code associated with current error. More...
int	ErrPos () const
	Returns an error position in SQL statement. More...
SAString	ErrMessage () const
	Returns an error message. More...
SAString	ErrText () const
	Returns a full error text (with nested SAException error messages). More...
SAString	CommandText () const
	Returns an error related command. More...
const SAException *	NestedException () const
	Returns a nested SAException pointer. More...

Static Public Member Functions
static void SQLAPI_CALLBACK	throwUserException (int nUserCode, const SAChar *lpszFormat,...)
	Throws an exception to stop an end-user operation. More...

Detailed Description

Library error exception class.

Member Function Documentation

throwUserException()

void SQLAPI_CALLBACK SAException::throwUserException ( int  nUserCode, const SAChar *  lpszFormat,   ...  )

static

Throws an exception to stop an end-user operation.

Remarks

Call SAException::throwUserException method to use the throw/catch exception mechanism for application-specific exceptions and to write formatted data to error text in the same way that sprintf formats data into a C-style character array.

SAException::throwUserException method throws an exception of SAUserException class derived from SQLAPI++ SAException class. That's why user exception can be handled by usual SAException handler.

Parameters

nUserCode	An integer value of user-defined error code.
lpszFormat	A format-control string.

ErrClass()

SAErrorClass_t SAException::ErrClass

(

)

const

Returns a class of error.

A SAException object handles the next error classes:

• User - generated errors
• Library errors
• DBMS API errors

The Library errors are generated by the Library itself. It can be like detecting some mistake in passing arguments to the function or referencing the parameter with an inappropriate name. To get a Library - defined error text call ErrText method.

The DBMS API errors come to the Library from the DBMS Client or Server. In this case the Library returns an error code and text Client - or Server - defined.To get error code and error text returned by the server call ErrNativeCode and ErrText methods.

The User - generated exception is "SQLAPI++ compatible" exception thrown by the user. To throw user exception use SAException::throwUserException method.

ErrNativeCode()

int SAException::ErrNativeCode

(

)

const

Returns a native code associated with current error.

Returns

An integer value represents a native code associated with current error.

A native error code depends on a class of error.

If error class is DBMS API error the SAException::ErrNativeCode method returns error code received from DBMS Server or Client. If error class is User-defined error the SAException::ErrNativeCode method returns an error code specified by user (see SAException::throwUserException method). If error class is Library error the SAException::ErrNativeCode method returns -1 or any special code defined in SALibraryErrorType_t enum.

See also

SAException::ErrClass

ErrPos()

int SAException::ErrPos

(

)

const

Returns an error position in SQL statement.

Returns

An integer value representing error position.

If a command object's associated SQL statement contains any syntax errors, an exception will be thrown when you try to compile. ErrPos method returns the error position within the command string.

Not all DBMS servers allow to get error position. See Server specific notes to get detailed information about returned value.

Server specific notes

DBMS server	SAException::ErrPos method returned value
Oracle	Parse error offset.
SQL Server	The number of line within SQL statement where error occurred.
Sybase	The number of line within SQL statement where error occurred.
DB2	-1. DB2 does not support this function.
Informix	-1. Informix does not support this function.
InterBase	-1. InterBase does not support this function.
SQLBase	Character position of the syntax error within an SQL statement. The first character is position 0.
MySQL	-1. MySQL does not support this function.
PostgreSQL	-1. PostgreSQL does not support this function.
ODBC	-1. ODBC does not support this function.
SQLite	-1. SQLite does not support this function.

ErrMessage()

SAString SAException::ErrMessage

(

)

const

Returns an error message.

Returns

A string of the single error description. To get the whole problem text call SAException::ErrText method.

Remarks

A error text depends on a class of error. If error class is Library error the SAException::ErrMessage method returns Library-defined error text. If error class is DBMS API error the SAException::ErrMessage method returns an error text gotten from DBMS Server or Client. If error class is User-defined error the SAException::ErrMessage method returns an error text specified by user (see SAException::throwUserException method).

ErrText()

SAString SAException::ErrText

(

)

const

Returns a full error text (with nested SAException error messages).

Returns

A string of the exception description. Includes descriptions for all exception related errors (all nested exception error messages).

Remarks

To get the single exception message call SAException::ErrMessage method.

CommandText()

SAString SAException::CommandText

(

)

const

Returns an error related command.

Returns

Related SQL command text or empty string.

Remarks

When an error occured during a command execution the actual SQL command is saved inot SAException objects.

NestedException()

const SAException * SAException::NestedException

(

)

const

Returns a nested SAException pointer.

Returns

SAException pointer or NULL if there is no any nested error occured.

Remarks

When several errors occured during a command execution they are collected into a chain of SAException objects. The last SAException is thrown so it is possible to get and analize each error separately by using NestedException method.