Library error exception class. More...

#include <SQLAPI.h>

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 SAExceptionNestedException () 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
nUserCodeAn integer value of user-defined error code.
lpszFormatA 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.