Copyright: Copyright © 2000 Inprise Corporation.                      All rights reserved.                                                 This Help file was compiled on   Monday, April 02, 2001 12:56:48.


dbExpress

dbExpress is a cross-platform, database-independent layer that provides methods for dynamic SQL processing. It defines a common interface for accessing a variety of SQL servers. For each supported server, dbExpress provides a driver, which acts as an independent library that implements the common dbExpress interfaces for processing queries and stored procedures. dbExpress drivers are available for both the Windows and the Linux platform as dynamic-link libraries (on Windows) or shared object files (on Linux).

dbExpress was designed to be fast, lightweight, and easy to deploy. As such, it does very little data processing, but mainly acts as a thin wrapper around the database server’s client-side software. It provides the advantages of a common API without the overhead of a more elaborate database engine such as the Borland Database Engine. For example, dbExpress drivers return only unidirectional cursors and perform no data or metadata caching.  By keeping the core runtime data-access layer thin and simple, dbExpress provides high performance database connectivity that can be easily adapted to new data sources.

On top of the core interfaces, application developers can create a layer for caching data and thereby provide forward and backward scrolling on the result set. For example, components such as a client dataset can provide the support for caching, scrolling, indexing, and filtering dbExpress result sets.

dbExpress interfaces

The four core interfaces in dbExpress are

SQLDriver

SQLConnection

SQLCommand

SQLCursor

In addition, there is a metadata access interface built on the core interfaces:

SQLMetaData

These interfaces are declared in dbxpress.h, and can be used directly in C++ code. In Object Pascal, these are accessed through interfaces (ISQLDriver, ISQLConnection, ISQLCommand, ISQLCursor, and ISQLMetaData), which are declared in the DBXpress unit.

All of these dbExpress objects act as reference-counted interfaced objects. That means that you do not need to explicitly free them. When your application releases the interface, the reference count drops. When the reference count drops to 0, the object is freed. In Object Pascal, the compiler automatically generates the call to release the interface. In C++, you must explicitly call the Release method when you are finished using an interface.

Data type mapping

Data sources represent data in various formats. dbExpress unifies this variety into a set of generic data types for getting individual field values. dbExpress defines a set of logical data types that surface most of the SQL data types supported by various databases.  Although there is a translation between SQL and logical types, the performance impact is negligible.


SQLDriver

C++ syntax	Object Pascal syntax	See also

SQLDriver handles database-specific initialization, such as loading the vendor client, initializing the environment, and allocating necessary handles. It can be used to obtain a SQLConnection interface.

Methods

getSQLConnection

setOption

getOption


SQLDriver: C++ syntax

abstract COMINTF SQLDriver

{

   virtual INT32 GCCSTDC QueryInterface( GUID riid, ppVOID ppv ) = 0;

   virtual UINT32 GCCSTDC AddRef( ) = 0;

   //Destructs the SQLDriver object

   virtual UINT32 GCCSTDC Release( ) = 0;

   // Gets a new SQLConnection object

   virtual SQLResult GCCSTDC getSQLConnection (

          ppSQLConnection ppConn) = 0;

   // Set/Get options for database driver level properties

   virtual SQLResult GCCSTDC setOption (

          eSQLDriverOption eDOption,

          INT32 lValue )  = 0;

   virtual SQLResult GCCSTDC getOption (

      eSQLDriverOption  eDOption,

      pINT32            plValue,

      INT16             iMaxLength,

      pINT16            piLength )  = 0;

};


ISQLDriver: Object Pascal syntax

ISQLDriver = interface

   function getSQLConnection(out pConn : ISQLConnection) : SQLResult; stdcall;

   function setOption(eDOption : TSQLDriverOption;

                     PropValue : LongInt): SQLResult; stdcall;

   function getOption(eDOption : TSQLDriverOption; PropValue : Pointer; MaxLength: SmallInt; out Length: SmallInt): SQLResult; stdcall;

end;


getSQLConnection (SQLDriver)

C++ example	Object Pascal example

C++ syntax:

virtual SQLResult GCCSTDC getSQLConnection (ppSQLConnection ppConn) = 0;

Object Pascal syntax:

function getSQLConnection(out pConn : ISQLConnection) : SQLResult; stdcall;

Description

getSQLConnection returns an SQLConnection interface pointer as the value of the ppConn (pConn) parameter. It returns SQL_SUCCESS if the interface is successfully returned. Otherwise, it returns an error code.

Parameters

ppConn (C++) or pConn (Object Pascal): A pointer to a variable that receives the SQLConnection interface pointer.


getSQLConnection example

pSQLConnection DBConnection;

SQLResult Status = pDriver->getSQLConnection(&DBConnection);


getSQLConnection example

var

  DBConnection: ISQLConnection;

  Status: SQLResult;

begin

  Status := Driver.getSQLConnection(DBConnection);


setOption (SQLDriver)

C++ example	Object Pascal example	See also

C++ syntax:

virtual SQLResult GCCSTDC setOption (eSQLDriverOption eDOption, INT32 PropValue) = 0;

Object Pascal syntax:

function setOption(eDOption : TSQLDriverOption; PropValue: LongInt) : SQLResult; stdcall;

Description

setOption sets the value of a specified driver property. It returns SQL_SUCCESS if the property value is successfully set, otherwise an error code.

Parameters

eDOption: the name of the driver property whose value is to be set.

PropValue: the value to set. Note that this value may represent another type that must be cast to a 32-bit integer.


setOption example

SQLResult Status = pDriver->setOption(eDrvBlobSize, 40);


setOption example

Status := Driver.setOption(eDrvBlobSize, 40);


getOption (SQLDriver)

C++ example	Object Pascal example	See also

C++ syntax:

virtual SQLResult GCCSTDC getOption (eSQLDriverOption eDOption, pINT32 plValue, INT16 iMaxLength, pINT16 piLength) = 0;

Object Pascal syntax:

function getOption(eDOption : TSQLDriverOption; plValue: Pointer; iMaxLength: SmallInt; out Length SmallInt) : SQLResult; stdcall;

Description

getOption retrieves the value of a specified driver property.  It returns SQL_SUCCESS if the property value is successfully fetched, otherwise an error code.

Parameters

eDOption: the name of the driver property whose value is to be retrieved.

plValue: a pointer to a variable that receives the property value.

iMaxLength: The maximum number of bytes that can be returned by plValue. That is, the size of the variable to which plValue points.

piLength (Length): Returns the number of bytes written to plValue.


getOption example

int MaxBlobSize = 0;

short int Len = 0;

SQLResult Status = pDriver->getOption(eDrvBlobSize, &MaxBlobSize, sizeof(int), &Len);


getOption example

var

  MaxBlobSize: Integer;

  Len: SmallInt;

  Status: SQLResult;

begin

  Status := Driver.getOption(eDrvBlobSize, Addr(MaxBlobSize), SizeOf(Integer), Len);


SQLConnection

C++ syntax	Object Pascal syntax	See also

SQLConnection establishes a connection to a database, gets a SQLCommand object for query and stored procedure processing, gets a SQLMetaData object for metadata retrieval, and handles transactions.

Methods

connect

disconnect

getSQLCommand

getSQLMetaData

setOption

getOption

beginTransaction

commit

rollback

getErrorMessage

getErrorMessageLen


SQLConnection: C++ syntax

abstract COMINTF SQLConnection

{

   virtual INT32 GCCSTDC QueryInterface( GUID riid,  ppVOID ppv ) = 0;

   virtual UINT32 GCCSTDC AddRef( ) = 0;

   //Destructs the SQLConnection object

   virtual UINT32 GCCSTDC Release( ) = 0;

   //Attach to a database server

   virtual SQLResult GCCSTDC connect (

      pCHAR pszServerName,

      pCHAR pszUserName,

      pCHAR pszPassword ) = 0;

   //Detach from a database server

   virtual SQLResult GCCSTDC disconnect () = 0;

   //Destructs the SQLConnection object

   //Gets a new SQLCommand object

   virtual SQLResult GCCSTDC getSQLCommand (

      ppSQLCommand ppComm) = 0;

   //Gets a new SQLMetaData object

   virtual SQLResult GCCSTDC getSQLMetaData (

      ppSQLMetaData ppMeta) = 0;

   //Set/Get options for database connection level properties

   virtual SQLResult GCCSTDC setOption (

      eSQLConnectOption eCOption,

      INT32             lValue )  = 0;

   virtual  SQLResult GCCSTDC getOption (

      eSQLConnectOption eCOption,

      pINT32            plValue,

      INT16             iMaxLength,

      pINT16            piLength )  = 0;

   //Transaction support

   virtual SQLResult GCCSTDC beginTransaction(

      UINT32 ulTrasnID );

   virtual SQLResult GCCSTDC commit(

      UINT32 ulTrasnID );

   virtual SQLResult GCCSTDC rollback(

      UINT32 ulTrasnID );

   //Error handling

   virtual SQLResult GCCSTDC getErrorMessage (

      pBYTE pszError ) = 0;

   virtual SQLResult GCCSTDC getErrorMessageLen (

      pUINT16 puErrorLen ) = 0;

};


ISQLConnection: Object Pascal syntax

ISQLConnection = interface

   function connect(ServerName : PChar; UserName : PChar; Password : PChar) : SQLResult; stdcall;

   function disconnect : SQLResult; stdcall;

   function getSQLCommand(out pComm : ISQLCommand) : SQLResult; stdcall;

   function getSQLMetaData(out pMetaData : ISQLMetaData) : SQLResult; stdcall;

   function setOption(eConnectOption : TSQLConnectionOption; lValue : LongInt) : SQLResult; stdcall;

   function getOption(eDOption : TSQLConnectionOption; PropValue : Pointer; MaxLength: SmallInt; out Length: SmallInt): SQLResult; stdcall;

   function beginTransaction(TranID: LongWord) : SQLResult; stdcall;

   function commit(TranID: LongWord) : SQLResult; stdcall;

   function rollback(TranID: LongWord) : SQLResult; stdcall;

   function getErrorMessage(Error : PChar) : SQLResult; overload; stdcall;

   function getErrorMessageLen(out ErrorLen: SmallInt): SQLResult; stdcall;

end;


connect (SQLConnection)

C++ example	Object Pascal example	See also

C++ syntax:

virtual SQLResult GCCSTDC connect (pCHAR pszServerName, pCHAR pszUserName, pCHAR pszPassword) = 0;

Object Pascal syntax:

function connect(pszServerName : PChar; pszUserName : PChar; pszPassword : PChar) : SQLResult; stdcall;

Description

connect establishes a connection to the database server. It returns SQL_SUCCESS if the connection is successfully established, otherwise an error code. If connect returns an error code, you can obtain an error message explaining the problem using the getErrorMessage method.

Parameters

pszServerName is the name of the database to which you are connecting. Its meaning varies slightly, depending on the driver. For most drivers, it is the client-side alias for the database. For InterBase, this is the name of the .gdb file. For Oracle, this is the entry in TNSNames.ora. For DB2, this is the client-side node.

UserName is the user name to use when logging into the database.

Password is the password for the user specified by UserName.


connect example

SQLResult Status = pConnection->connect("HRData.gdb", "Administrator", "MasterKey");


connect example

Status := Connection.connect('HRData.gdb', 'Administrator', 'MasterKey');


disconnect (SQLConnection)

C++ example	Object Pascal example	See also

C++ syntax:

virtual SQLResult GCCSTDC disconnect ( ) = 0;

Object Pascal syntax:

function disconnect : SQLResult; stdcall;

Description

disconnect terminates a connection that was established using the connect method. It returns SQL_SUCCESS if the connection is successfully terminated, otherwise an error code.


disconnect example

SQLResult Status = pConnection->disconnect();


disconnect example

Status := Connection.disconnect;


getSQLCommand (SQLConnection)

C++ example	Object Pascal example	See also

C++ syntax:

virtual SQLResult GCCSTDC getSQLCommand (ppSQLCommand ppComm) = 0;

Object Pascal syntax:

function getSQLCommand(out pComm : ISQLCommand): SQLResult; stdcall;

Description

getSQLCommand obtains an SQLCommand interface pointer, which can then be used to process queries and stored procedures. The SQLConnection object should be connected to the database server before you call this method. getSQLCommand returns SQL_SUCCESS if the command object is successfully retrieved, otherwise an error code. If this method returns an error code, use the getErrorMessage method to obtain an error message for the problem.

Parameters

ppComm (C++) or pComm (Object Pascal): A pointer to a variable that receives the SQLCommand interface pointer.


getSQLCommand example

pSQLCommand QueryObject;

SQLResult Status = pConnection->getSQLCommand(&QueryObject);


getSQLCommand example

var

  QueryObject: ISQLCommand;

  Status: SQLResult;

begin

  Status := DBConnection.getSQLCommand(QueryObject);


getSQLMetaData (SQLConnection)

C++ example	Object Pascal example	See also

C++ syntax:

virtual SQLResult GCCSTDC getSQLMetaData (ppSQLMetaData ppMeta) = 0;

Object Pascal syntax:

function getSQLMetaData(out pMetaData : ISQLMetaData): SQLResult; stdcall;

Description

getSQLMetaData obtains an SQLMetaData interface pointer, which can then be used to retrieve information about the tables, stored procedures, indexes, and other schema objects on the database server. The SQLConnection object should be connected to the database server before you call this method. getSQLMetaData returns SQL_SUCCESS if the metadata object is successfully retrieved, otherwise an error code. If this method returns an error code, use the getErrorMessage method to obtain an error message for the problem.

Parameters

ppMeta (C++) or pMetaData (Object Pascal): A pointer to a variable that receives the SQLMetaData interface pointer.


getSQLMetaData example

pSQLMetaData MetaDataPointer;

SQLResult Status = pConnection->getSQLMetaData(&MetaDataPointer);


getSQLMetaData example

var

  MetaDataObject: ISQLMetaData;

  Status: SQLResult;

begin

  Status := DBConnection.getSQLMetaData(MetaDataObject);


setOption (SQLConnection)

C++ example	Object Pascal example	See also

C++ syntax:

virtual SQLResult GCCSTDC setOption (eSQLConnectOption eCOption, INT32 lValue) = 0;

Object Pascal syntax:

function setOption(eCOption : TSQLConnectionOption; lValue: LongInt) : SQLResult; stdcall;

Description

setOption sets the value of a specified connection property. It returns SQL_SUCCESS if the property value is successfully set, otherwise an error code. Connection properties should be set before calling the connect method.

Parameters

eCOption: the name of the connection property whose value is to be set. Note that eCOption should not refer to a read-only property.

lValue: the value to set. Note that this value may represent another type that must be cast to a 32-bit integer.


setOption example

SQLResult Status = pConnection->setOption(eConnTxnIsoLevel, xilREPEATABLEREAD);


setOption example

Status := Connection.setOption(eConnTxnIsoLevel, xilREPEATABLEREAD);


getOption (SQLConnection)

C++ example	Object Pascal example	See also

C++ syntax:

virtual SQLResult GCCSTDC getOption (eSQLConnectOption eCOption, pINT32 plValue, INT16 iMaxLength, pINT16 piLength) = 0;

Object Pascal syntax:

function getOption(eCOption : TSQLConnectionOption; plValue: Pointer; iMaxLength: SmallInt; out Length SmallInt) : SQLResult; stdcall;

Description

getOption retrieves the value of a specified connection property.  It returns SQL_SUCCESS if the property value is successfully fetched, otherwise an error code.

Parameters

eCOption: the name of the driver property whose value is to be retrieved.

plValue: a pointer to a variable that receives the property value.

iMaxLength: The maximum number of bytes that can be returned by plValue. That is, the size of the variable to which plValue points.

piLength (Length): Returns the number of bytes written to plValue.


getOption example

char DBName[30];

short int Len;

SQLResult Status;

Status = pConnection->getOption(eConnDatabaseName, DBName, 30, &Len);

if (Status == SQL_SUCCESS)

  DBName[Len] = '\0';


getOption example

var

  Buffer: PChar;

  DBName: string;

  Len: SmallInt;

  Status: SQLResult;

begin

  Buffer := PChar(AllocMem(30));

  Status := Connection.getOption(eConnDatabaseName, Buffer, 30, Len);

  Buffer[Len] := 0;

  DBName := Buffer;

  FreeMem(Buffer);


beginTransaction (SQLConnection)

C++ example	Object Pascal example	See also

C++ syntax:

virtual SQLResult GCCSTDC beginTransaction (UINT32 ulTransDesc) = 0;

Object Pascal syntax:

function beginTransaction(ulTransDesc: LongWord) : SQLResult; stdcall;

Description

beginTransaction starts a new transaction. Updates, insertions, and deletions that take place after a call to beginTransaction are held by the server until the commit or rollback method is called. beginTransaction returns SQL_SUCCESS if the transaction is successfully started. Otherwise it returns an error code. Note that transactions are not supported by MySQL.

Parameters

ulTransDesc is a pointer to a TransactionDesc structure. It lets you specify

A user-defined transaction identifier. If the server supports nested or overlapped transactions, you can initiate multiple transactions by calling beginTransaction and providing each transaction with its own unique identifier.

The transaction isolation level. This indicates the degree to which this transaction can “see” changes made by other transactions.

Tip:	When working with multiple transactions, specify the transaction to which a command belongs using the eCommTransactionID property of the command object.


beginTransaction example

TransactionDesc TD;

TD.uTransID = 1;

TD.eTransIsoLevel = xilREPEATABLEREAD;

if (pConnection->beginTransaction(&TD) == SQL_SUCCESS)

{

  try

  {

..  . // perform some updates

    if (pConnection->commit(&TD) != SQL_SUCCESS)

      throw (ETransFailed);

  }

  catch (...)

  {

    pConnection->rollback(&TD);

  }

}


beginTransaction example

var

  TD: TTransactionDesc;

begin

  TD.TransactionID := 1;

  TD.IsolationLevel := xilREPEATABLEREAD;

  if Connection.beginTransaction(@TD) = SQL_SUCCESS then

  begin

    try

      { perform some updates }

      if not Connection.commit(@TD) = SQL_SUCCESS then

        raise ETransFailed.Create;

    except

      Connection.rollback(@TD);

    end;

  end;

end;


commit (SQLConnection)

C++ example	Object Pascal example	See also

C++ syntax:

virtual SQLResult GCCSTDC commit (UINT32 ulTransDesc) = 0;

Object Pascal syntax:

function commit(ulTransDesc: LongWord) : SQLResult; stdcall;

Description

commit saves (makes permanent) any changes made during the specified transaction and ends the transaction. It returns SQL_SUCCESS if the transaction is successfully committed, or an error code otherwise.

Parameters

ulTransDesc is a pointer to a TTransactionDesc structure for this transaction. This should match the transaction descriptor supplied to the beginTransaction method when starting the transaction.


commit example

TransactionDesc TD;

TD.uTransID = 1;

TD.eTransIsoLevel = xilREPEATABLEREAD;

if (pConnection->beginTransaction(&TD) == SQL_SUCCESS)

{

  try

  {

..  . // perform some updates

    if (pConnection->commit(&TD) != SQL_SUCCESS)

      throw (ETransFailed);

  }

  catch (...)

  {

    pConnection->rollback(&TD);

  }

}


commit example

var

  TD: TTransactionDesc;

begin

  TD.TransactionID := 1;

  TD.IsolationLevel := xilREPEATABLEREAD;

  if Connection.beginTransaction(@TD) = SQL_SUCCESS then

  begin

    try

      { perform some updates }

      if not Connection.commit(@TD) = SQL_SUCCESS then

        raise ETransFailed.Create;

    except

      Connection.rollback(@TD);

    end;

  end;

end;


rollback (SQLConnection)

C++ example	Object Pascal example	See also

C++ syntax:

virtual SQLResult GCCSTDC rollback (UINT32 ulTransDesc) = 0;

Object Pascal syntax:

function rollback(ulTransDesc: LongWord) : SQLResult; stdcall;

Description

rollback ends the specified transaction, backing out any changes made since the call to beginTransaction that started the transaction. It returns SQL_SUCCESS if the transaction is successfully rolled back, or an error code otherwise.

Parameters

ulTransDesc is a pointer to a TTransactionDesc structure for this transaction. This should match the transaction descriptor supplied to the beginTransaction method when starting the transaction.


rollback example

TransactionDesc TD;

TD.uTransID = 1;

TD.eTransIsoLevel = xilREPEATABLEREAD;

if (pConnection->beginTransaction(&TD) == SQL_SUCCESS)

{

  try

  {

..  . // perform some updates

    if (pConnection->commit(&TD) != SQL_SUCCESS)

      throw (ETransFailed);

  }

  catch (...)

  {

    pConnection->rollback(&TD);

  }

}


rollback example

var

  TD: TTransactionDesc;

begin

  TD.TransactionID := 1;

  TD.IsolationLevel := xilREPEATABLEREAD;

  if Connection.beginTransaction(@TD) = SQL_SUCCESS then

  begin

    try

      { perform some updates }

      if not Connection.commit(@TD) = SQL_SUCCESS then

        raise ETransFailed.Create;

    except

      Connection.rollback(@TD);

    end;

  end;

end;


getErrorMessage (SQLConnection)

C++ example	Object Pascal example	See also

C++ syntax:

virtual SQLResult GCCSTDC getErrorMessage (pBYTE pszError) = 0;

Object Pascal syntax:

function getErrorMessage(Error : PChar) : SQLResult; overload; stdcall;

Description

getErrorMessage retrieves an error string for the last command that was sent to the server. Thus, if the last method that accessed the server returned an error code, calling getErrorMessage returns an error message for that error code. Note that once an application calls getErrorMessage, the error message is cleared and subsequent calls will not return the error message.

getErrorMessage returns SQL_SUCCESS if the error message is successfully returned. Otherwise, it returns an error code.

Parameters

pszError (Error) is a buffer that receives the null-terminated error string. Use the getErrorMessageLen method to determine the size required for this buffer.


getErrorMessage example

short int MessageLen = 0;

SQLResult Status = pC->getErrorMessageLen(MessageLen);

if (Status == SQL_SUCCESS && MessageLen > 0)

{

  char *Message = (char *)malloc(MessageLen + 1);

  if (Message)

  {

    Status = pC->getErrorMessage(Message);

    ExceptObject.Message = Message;

    free(Message);

  }

}


getErrorMessage example

var

  ExceptionMessage : string;

  Message: PChar;

  Status : SQLResult;

  MessageLen : SmallInt;

begin

  Message := nil;

  Status := C.getErrorMessageLen(MessageLen);

  if Status = SQL_SUCCESS then

  begin

    Message := AllocMem(MessageLen + 1);

    if Assigned(Message) then

    begin

      Status := C.getErrorMessage(Message);

      ExceptionMessage := Message;

      FreeMem(Message);

    end;

  end;

  ShowMessage(ExceptionMessage);

end;


getErrorMessageLen (SQLConnection)

C++ example	Object Pascal example	See also

C++ syntax:

virtual SQLResult GCCSTDC getErrorMessageLen (pUINT16 puErrorLen) = 0;

Object Pascal syntax:

function getErrorMessageLen(out ErrorLen: SmallInt) : SQLResult; stdcall;

Description

getErrorMessageLen indicates the number of characters (bytes) in an error string for the last command that was sent to the server. Use this method before allocating a buffer to hold the error message that the getErrorMessage method returns. The buffer needs to be puErrorLen + 1 bytes (an additional byte for the null terminating character).

Parameters

puErrorLen (ErrorLen) returns the number of bytes in the error string as a 16-bit integer.


getErrorMessageLen example

short int MessageLen = 0;

SQLResult Status = C.getErrorMessageLen(MessageLen);

if (Status == SQL_SUCCESS && MessageLen > 0)

{

  char *Message = (char *)malloc(MessageLen + 1);

  if (Message)

  {

    Status = C.getErrorMessage(Message);

    ExceptObject.Message = Message;

    free(Message);

  }

}


getErrorMessageLen example

var

  ExceptionMessage : string;

  Message: PChar;

  Status : SQLResult;

  MessageLen : SmallInt;

begin

  Message := nil;

  Status := C.getErrorMessageLen(MessageLen);

  if Status = SQL_SUCCESS then

  begin

    Message := AllocMem(MessageLen + 1);

    if Assigned(Message) then

    begin

      Status := C.getErrorMessage(Message);

      ExceptionMessage := Message;

      FreeMem(Message);

    end;

  end;

  ShowMessage(ExceptionMessage);

end;


SQLCommand

C++ syntax	Object Pascal syntax	See also

SQLCommand provides methods for processing a query or stored procedure. It can be used to fetch a SQLCursor interface after executing a command that returns a cursor. It supports executing a prepared query multiple times with parameter binding, and can return multiple cursors from a stored procedure.

Methods

setOption

getOption

setParameter

getParameter

prepare

execute

executeImmediate

getNextCursor

getRowsAffected

execute

executeImmediate

getErrorMessage

getErrorMessageLen


SQLCommand: C++ syntax

abstract COMINTF SQLCommand

{

   virtual INT32  GCCSTDC QueryInterface( GUID riid, ppVOID ppv ) = 0;

   virtual UINT32 GCCSTDC AddRef( ) = 0;

   //Destructs the SQLCommand object

   virtual UINT32 GCCSTDC Release( ) = 0;

   //Set/Get options for command level properties

   virtual SQLResult GCCSTDC setOption (

      eSQLCommandOption eSOption,

      INT32             lValue ) = 0;

   virtual SQLResult GCCSTDC getOption (

      eSQLCommandOption eSOption,

      pINT32            plValue,

      INT16             iMaxLength,

      pINT16            piLength )  = 0;

   //Set/Get  methods for parameter binding support

   virtual SQLResult GCCSTDC setParameter (

      UINT16     uParameterNumber,

      STMTParamType ePType,

      UINT16     uLogType,

      UINT16     uSubType,

      INT32      lMaxPrecision,

      INT32      lMaxScale,

      UINT32     ulLength,

      pVOID      pBuffer,

      BOOL       bIsNull ) = 0;

   virtual SQLResult GCCSTDC getParameter (

      UINT16  uParameterNumber,

      pVOID   pData,

      UINT32  ulLength,

      pINT32  plInd ) = 0;

   //Prepare and Execute SQL and Stored Procedure

   virtual SQLResult GCCSTDC prepare (

      pCHAR pszSQL ) = 0;

   virtual SQLResult GCCSTDC execute (

     ppSQLCursor ppCur) = 0;

   //Direct execution of Query or Stored Procedure or DDL

   //No parsing will be done

   virtual SQLResult GCCSTDC executeImmediate (

      pCHAR pszSQL,

      ppSQLCursor ppCur) = 0;

   //A new SQLCursor object will is returned if another result set exists

   >//available from a stored procedure execution

   virtual SQLResult GCCSTDC  getNextCursor (

      ppSQLCursor ppCur);

   //No.of rows affected as a result of INSERT/DELETE/UPDATE

   virtual SQLResult GCCSTDC getRowsAffected (

      pINT32 plRows) = 0;

   //Free resources used for parameter binding

   virtual SQLResult GCCSTDC close () = 0;

   //Error Handling

   virtual SQLResult GCCSTDC getErrorMessage (

      pBYTE pszError ) = 0;

   virtual SQLResult GCCSTDC getErrorMessageLen (

      pUINT16 puErrorLen ) = 0;

};


ISQLCommand: Object Pascal syntax

ISQLCommand = interface

   function setOption(

      eSqlCommandOption: TSQLCommandOption;

      ulValue : integer) : SQLResult; stdcall;

   function getOption(

      eSqlCommandOption: TSQLCommandOption;

      var pValue : Integer;

      MaxLength: SmallInt;

      out Length: SmallInt): SQLResult; stdcall;

   function setParameter(

      ulParameter : Word ;

      ulChildPos : Word ;

      eParamType : TSTMTParamType ;

      uLogType : Word;

      uSubType : Word;

      iPrecision : Integer;

      iScale : Integer;

      Length : LongWord ;

      pBuffer : Pointer;

      lInd : integer) : SQLResult; stdcall;

   function getParameter(

      ParameterNumber : Word;

      ulChildPos: Word;

      Value : Pointer;

      Length : Integer;

      var IsBlank : Integer) : SQLResult; stdcall;

   function prepare(

      SQL : PChar;

      ParamCount: Word) : SQLResult; stdcall;

   function execute(var Cursor : ISQLCursor) : SQLResult; stdcall;

   function executeImmediate(

      SQL : PChar;

      var Cursor : ISQLCursor) : SQLResult; stdcall;

   function getNextCursor(var Cursor: ISQLCursor): SQLResult; stdcall;

   function getRowsAffected(var Rows: LongWord) : SQLResult; stdcall;

   function close : SQLResult; stdcall;

   function getErrorMessage(Error : PChar) : SQLResult; overload; stdcall;

   function getErrorMessageLen(out ErrorLen: SmallInt): SQLResult; stdcall;

end;


setOption (SQLCommand)

C++ example	Object Pascal example	See also

C++ syntax:

virtual SQLResult GCCSTDC setOption (eSQLCommandOption eSOption, INT32 lValue) = 0;

Object Pascal syntax:

function setOption(eSOption : TSQLCommandOption; lValue: Integer) : SQLResult; stdcall;

Description

setOption sets the value of a specified command property. It returns SQL_SUCCESS if the property value is successfully set, otherwise an error code.

Parameters

eSOption: the name of the command property whose value is to be set. Note that eSOption should not refer to a read-only property.

lValue: the value to set. Note that this value may represent another type that must be cast to a 32-bit integer.


setOption example

Status = pCommand->setOption(eCommStoredProc, true);


setOption example

Status := Connection.setOption(eCommStoredProc, Integer(True));


getOption (SQLCommand)

C++ example	Object Pascal example	See also

C++ syntax:

virtual SQLResult GCCSTDC getOption (eSQLCommandOption eSOption, pINT32 plValue, INT16 iMaxLength, pINT16 piLength) = 0;

Object Pascal syntax:

function getOption(eSOption : TSQLCommandOption; plValue: Pointer; iMaxLength: SmallInt; out Length SmallInt) : SQLResult; stdcall;

Description

getOption retrieves the value of a specified command property.  It returns SQL_SUCCESS if the property value is successfully fetched, otherwise an error code.

Parameters

eSOption: the name of the command property whose value is to be retrieved.

plValue: a pointer to a variable that receives the property value.

iMaxLength: The maximum number of bytes that can be returned by plValue. That is, the size of the variable to which plValue points.

piLength (Length): Returns the number of bytes written to plValue.


getOption example

bool InBlockReadMode;

SQLResult Status;

Status = pCommand->getOption(eCommBlockRead, &InBlockReadMode, sizeof(bool), &Len);


getOption example

var

  InBlockReadMode: Boolean;

  Len: SmallInt;

  Status: SQLResult;

begin

  Status := Connection.getOption(eCommBlockRead, Addr(InBlockReadMode), SizeOf(Boolean), Len);


setParameter (SQLCommand)

C++ example	Object Pascal example	See also

C++ syntax:

virtual SQLResult GCCSTDC setParameter (UINT16 uParameterNumber, UINT16 uChildPos, STMTParamType ePType, UINT16 uLogType, UINT16 uSubType, INT32 lMaxPrecision, INT32 lMaxScale, UINT32 ulLength, pVOID pBuffer, BOOL bIsNull) = 0;

Object Pascal syntax:

function setParameter(uParameterNumber: Word; uChildPos: Word; ePType: TSTMTParamType; uLogType: Word; uSubType: Word; lMaxPrecision: Integer; lMaxScale: Integer; ulLength: LongWord; pBuffer: Pointer; bIsNull: Integer) : SQLResult; stdcall;

Description

setParameter sets a parameter value for the query or stored procedure before it is executed. It returns SQL_SUCCESS if the parameter value is successfully bound to the query or stored procedure. Otherwise, it returns an error code.

An application must call the prepare method before calling setParameter. After binding all the parameters with the setParameter method, the application can then call execute to execute the query or stored procedure.

Parameters

uParameterNumber: identifies the parameter to set by position. The first parameter has position 1, the second parameter has position 2, and so on.

uChildPos: If uParameterNumber identifies a parameter that takes an ADT or array value, uChildPos identifies the field or element within that value to be set by this call. The first field or element has position 1, the second has position 2, and so on. If uParameterNumber does not identify a parameter whose value is an ADT or array, set uChildPos to 0. Note that before you can assign the values of subelements of an ADT or array data type, you must first specify the type name for the ADT or array type. To specify the type name, use a uChildPos of 0 and supply the type name as the value of pBuffer.

eType: indicates whether the parameter is an input, output, input/output, or return parameter.

uLogType: The logical data type for the parameter. Possible values are listed in the Field Type column of the table of logical data types.

uSubType: The logical subtype (if appropriate) of the parameter’s data type. Possible values are listed in the Field subtype column of the table of logical data types .

lMaxPrecision: The maximum number of bytes required for parameter values:

If uLogType is fldZSTRING, this is the maximum string length (without the null terminator).

If uLogType is fldBYTES, this is the number of bytes for values.

If uLogType is fldVARBYTES, this is the field size minus the 2 bytes that are reserved for the field value’s length.

If uLogType is fldBCD, this is the precision (number of significant digits) for the field value.

For all other field types, this is the size of the datatype used to represent values. (e.g. 4 for fldDATE, 2 for fldINT16, and so on.)

lMaxScale: If uLogType is fldBCD, then lMaxScale indicates the number of digits beyond the decimal point.

ulLength: The number of bytes in the actual value specified by pBuffer. This value must be less than or equal to lMaxPrecision.

pBuffer: The value of the parameter. pBuffer points to a buffer of size ulLength.

bIsNull: Indicates whether the parameter value should be set to NULL (blank). In C++, this is a boolean value, where true indicates a null parameter value. In Object Pascal, this is an integer, where 1 indicates a null parameter value and 0 indicates a non-null value.


setParameter example

SQLResult Status = pCommand->setOption(eCommStoredProc, true);

if (Status == SQL_SUCCESS)

  Status = pCommand->prepare("TransferFunds", 2);

if (Status == SQL_SUCCESS)

  Status = pCommand->setParameter(1,0, paramIN, fldZString, 0, 20, 0, 10, "Petty Cash", false);

if (Status == SQL_SUCCESS)

{

  double Amt = 235.54;

  Status = pCommand->setParameter(2,0, paramIN, fldFLOAT, fldstMONEY, sizeof(double), 0, sizeof(double), &Amt, false);

}

if (Status == SQL_SUCCESS)

  Status = pCommand->execute(NULL); // no cursor returned


setParameter example

var

  Status : SQLResult;

  Amt: Double;

begin

  Status := Command.setOption(eCommStoredProc, Integer(True));

  if Status = SQL_SUCCESS then

    Status := Command.prepare('TransferFunds', 2);

  if Status = SQL_SUCCESS then

    Status := Command.setParameter(1, 0, paramIN, fldZString, 0, 20, 0, 10, 'Petty Cash', 0);

  if Status = SQL_SUCCESS then

  begin

    Amt := 237.54;

    Status := Command.setParameter(2, 0, paramIN, fldFLOAT, fldstMONEY, SizeOf(Double), 0, SizeOf(Double), Addr(Amt), 0);

  end;

  if Status = SQL_SUCCESS then

    Status := Command.execute(nil); { no cursor returned }


getParameter (SQLCommand)

C++ example	Object Pascal example	See also

C++ syntax:

virtual SQLResult GCCSTDC getParameter (UINT16 uParameterNumber, UINT16 uChildPos, pVOID pData, UINT32 ulLength, pINT32 plInd) = 0;

Object Pascal syntax:

function getParameter(uParameterNumber: Word; uChildPos: Word; pData: Pointer; ulLength: Integer; var IsBlank: Integer) : SQLResult; stdcall;

Description

getParameter retrieves an output parameter from a stored procedure after it has executed. It returns SQL_SUCCESS if the parameter value is successfully retrieved. Otherwise, it returns an error code.

An application must call the prepare method before executing a stored procedure that returns parameters. After calling the execute method to execute the stored procedure, the application can call getParameter to retrieve each output parameter.

Parameters

uParameterNumber: identifies the parameter to get by position. The first parameter has position 1, the second parameter has position 2, and so on.

uChildPos: If uParameterNumber identifies a parameter that returns an ADT or array value, uChildPos identifies the field or element within that value to be retrieved by this call. The first field or element has position 1, the second has position 2, and so on. If uParameterNumber does not identify a parameter whose value is an ADT or array, set uChildPos to 0.

pData: points to a buffer that receives the parameter value. The size of the buffer is given by the ulLength parameter.

ulLength: The number of bytes in the buffer specified by pData.

plInd (IsBlank): Returns an indication of whether the parameter value is blank (null). In C++, this is a boolean value, where true indicates a null parameter value. In Object Pascal, this is an integer, where 1 indicates a null parameter value and 0 indicates a non-null value.


getParameter example

int OutputValue;

bool IsBlank;

SQLResult Status = pCommand->getParameter(1,0, (pVOID) &OutputValue, sizeof(int), &IsBlank);


getParameter example

var

  OutputValue : Integer;

  Blank: Integer;

  Status: SQLResult;

begin

  Status := Command.getParameter(1, 0, Addr(OutputValue), SizeOf(Integer), Blank);

  ...


prepare (SQLCommand)

C++ example	Object Pascal example	See also

C++ syntax:

virtual SQLResult GCCSTDC prepare (pCHAR pszSQL, UINT16 uParamCount) = 0;

Object Pascal syntax:

function prepare(pszSQL: PChar; uParamCount: Word) : SQLResult; stdcall;

Description

prepare instructs the database server to set up a template for a query or stored procedure. Preparation is required before an application can execute a query or stored procedure that uses parameters. After calling prepare to instruct the server to prepare the query or stored procedure, the application can set any input parameter values using the setParameter method and then call the execute method to execute the query or stored procedure. An application can change parameter values and re-execute a query or stored procedure without calling prepare a second time.

Once the application no longer needs to execute the command, call the close method to free the resources that are allocated when the command is prepared.

If the query or stored procedure does not use parameters, an application can omit the call to prepare and execute the query or stored procedure by calling executeImmediate instead of execute. However, if the application executes the command more than once, there may still be a performance benefit to explicitly preparing the command and using the execute method.

Parameters

pszSQL: The text of the SQL query or the name of the stored procedure. Be sure to call setOption and identify the command as a stored procedure before calling prepare with a stored procedure name.

uParamCount: The number of parameters in the query or stored procedure.


prepare example

SQLResult Status = pCommand->setOption(eCommStoredProc, true);

if (Status == SQL_SUCCESS)

  Status = pCommand->prepare("TransferFunds", 2);

if (Status == SQL_SUCCESS)

  Status = pCommand->setParameter(1,0, paramIN, fldZString, 0, 20, 0, 10, "Petty Cash", false);

if (Status == SQL_SUCCESS)

{

  double Amt = 235.54;

  Status = pCommand->setParameter(2,0, paramIN, fldFLOAT, fldstMONEY, sizeof(double), 0, sizeof(double), &Amt, false);

}

if (Status == SQL_SUCCESS)

  Status = pCommand->execute(NULL); // no cursor returned


prepare example

var

  Status : SQLResult;

  Amt: Double;

begin

  Status := Command.setOption(eCommStoredProc, Integer(True));

  if Status = SQL_SUCCESS then

    Status := Command.prepare('TransferFunds', 2);

  if Status = SQL_SUCCESS then

    Status := Command.setParameter(1, 0, paramIN, fldZString, 0, 20, 0, 10, 'Petty Cash', 0);

  if Status = SQL_SUCCESS then

  begin

    Amt := 237.54;

    Status := Command.setParameter(2, 0, paramIN, fldFLOAT, fldstMONEY, SizeOf(Double), 0, SizeOf(Double), Addr(Amt), 0);

  end;

  if Status = SQL_SUCCESS then

    Status := Command.execute(nil); { no cursor returned }


execute (SQLCommand)

C++ example	Object Pascal example	See also

C++ syntax:

virtual SQLResult GCCSTDC execute (ppSQLCursor ppCur) = 0;

Object Pascal syntax:

function execute(var Cursor : ISQLCursor) : SQLResult; stdcall;

Description

execute executes a prepared query or stored procedure and returns a cursor interface if the query or stored procedure returns a cursor.

The application must call the prepare method and set the values of any input parameters before calling execute to execute the query or stored procedure. However, once a query or stored procedure has been prepared, an application can call execute multiple times without re-preparing it.

If the query or stored procedure does not include any parameters, it is possible to execute it without preparing it first. To execute a query or stored procedure without preparing it first, use the executImmediate method instead.

Parameters

ppSQLCursor (Cursor): returns a SQLCursor interface pointer if the query or stored procedure returns a cursor (for example, a SELECT query).


execute example

SQLResult Status = pCommand->prepare("Select * from Customer where CustID = ?", 1);

if (Status == SQL_SUCCESS)

{

  int CustID = 201;

  Status = pCommand->setParameter(1,0, paramIN, fldINT32, 0, sizeof(int), 0, 4, &CustID, false);

}

pSQLCursor Cursor;

if (Status == SQL_SUCCESS)

  Status = pCommand->execute(&Cursor);


execute example

var

  Status : SQLResult;

  CustID : Integer;

  Cursor: ISQLCursor;

begin

  Status := Command.prepare('Select * from Customer where CustID = ?', 1);

  if Status = SQL_SUCCESS then

  begin

    CustID := 201;

    Status := Command.setParameter(1, 0, paramIN, fldINT32, 0, 4, 0, 4, Addr(CustID), 0);

  end;

  if Status = SQL_SUCCESS then

    Status := Command.execute(Cursor);


executeImmediate (SQLCommand)

C++ example	Object Pascal example	See also

C++ syntax:

virtual SQLResult GCCSTDC executeImmediate (pCHAR pszSQL, ppSQLCursor ppCur) = 0;

Object Pascal syntax:

function executeImmediate(pszSQL: PChar; var Cursor: ISQLCursor) : SQLResult; stdcall;

Description

executeImmediate executes a query or stored procedure that does not need to be prepared. Unlike the execute method, applications do not need to call prepare before calling executeImmediate. However, because there is no preparation, queries or stored procedures executed in this manner can’t include any parameters.

Even if the query or stored procedure does not include any parameters, if you are executing the command more than once, you may achieve a performance benefit by preparing the command and using the execute method instead.

Parameters

pszSQL: the text of the query or the name of the stored procedure to execute.

ppSQLCursor (Cursor): returns a SQLCursor interface pointer if the query or stored procedure returns a cursor (for example, a SELECT query).


executeImmediate example

pSQLCursor Cursor;

SQLResult Status = pCommand->executeImmediate("Select * from Regions", &Cursor);


executeImmediate example

var

  Status : SQLResult;

  Cursor: ISQLCursor;

begin

  Status := Command.executeImmediate('Select * from Regions', Cursor);


getNextCursor (SQLCommand)

C++ example	Object Pascal example	See also

C++ syntax:

virtual SQLResult GCCSTDC getNextCursor (ppSQLCursor ppCur) = 0;

Object Pascal syntax:

function getNextCursor(var Cursor : ISQLCursor) : SQLResult; stdcall;

Description

getNextCursor returns additional cursors after executing a stored procedure that returns multiple cursors. The first cursor is returned by the execute or executeImmediate method. Following the execute call, calling getNextCursor returns the next cursor that the stored procedure returns, if any. Additional calls to getNextCursor return the next cursor until all cursors have been returned.

Parameters

ppSQLCursor (Cursor): returns a SQLCursor interface pointer if there is an additional cursor returned by the stored procedure that has not yet been fetched. If there are no additional cursors to return, this parameter returns NULL (nil).


getNextCursor example

SQLResult Status = pCommand->setOption(eCommStoredProc, true);

pSQLCursor LookupCursors[2];

if (Status == SQL_SUCCESS)

  Status = pCommand->executeImmediate("FetchLookupTables", &LookupCursors[0]);

if (Status == SQL_SUCCESS)

  Status = pCommand->getNextCursor(&LookupCursors[1]);


getNextCursor example

var

  Status : SQLResult;

  LookupCursors: array[0..1] of ISQLCursor;

begin

  Status := Command.setOption(eCommStoredProc, Integer(True));

  if Status = SQL_SUCCESS then

    Status := Command.executeImmediate('FetchLookupTables', LookupCursors[0]);

  if Status = SQL_SUCCESS then

    Status := Command.getNextCursor(LookupCursors[1]);


getRowsAffected (SQLCommand)

C++ example	Object Pascal example	See also

C++ syntax:

virtual SQLResult GCCSTDC getRowsAffected( pINT32 plRows) = 0;

Object Pascal syntax:

function getRowsAffected(var Rows: LongWord) : SQLResult; stdcall;

Description

getRowsAffected returns the number of records that were inserted, deleted, or updated by an INSERT, DELETE, or UPDATE query. Do not call getRowsAffected until after executing the command with a call to execute or executeImmediate.

Parameters

plRows (Rows): returns the number of records that were affected when the command was executed.


getRowsAffected example

int nItemsDeleted = 0;

SQLResult Status = pCommand->executeImmediate("DELETE FROM LineItems WHERE (OrderNo = 1099)", NULL);

if (Status == SQL_SUCCESS)

  Status = pCommand->getRowsAffected(&nItemsDeleted);


getRowsAffected example

var

  Status : SQLResult;

  nItemsDeleted: LongWord;

begin

  Status := Command.executeImmediate('DELETE FROM LineItems WHERE (OrderNo = 1099)', nil);

  if Status = SQL_SUCCESS then

    Status := Command.getRowsAffected(nItemsDeleted);


close (SQLCommand)

C++ example	Object Pascal example	See also

C++ syntax:

virtual SQLResult GCCSTDC close () = 0;

Object Pascal syntax:

function close : SQLResult; stdcall;

Description

close frees the resources that are allocated when a query or stored procedure is prepared (by a call to the prepare method). After calling close, the command must be re-prepared before you can call the execute method again.

Some database servers limit the number of active commands that can be held by a single connection. On such a server, closing a command allows other commands to execute.


close example

SQLResult Status = pCommand->prepare("Select * from Customer where CustID = ?", 1);

if (Status == SQL_SUCCESS)

{

  int CustID = 201;

  Status = pCommand->setParameter(1,0, paramIN, fldINT32, 0, sizeof(int), 0, 4, &CustID, false);

}

pSQLCursor Cursor;

if (Status == SQL_SUCCESS)

  Status = pCommand->execute(&Cursor);

pCommand->close(); // now that we are done, close the command


close example

var

  Status : SQLResult;

  CustID : Integer;

  Cursor: ISQLCursor;

begin

  Status := Command.prepare('Select * from Customer where CustID = ?', 1);

  if Status = SQL_SUCCESS then

  begin

    CustID := 201;

    Status := Command.setParameter(1, 0, paramIN, fldINT32, 0, 4, 0, 4, Addr(CustID), 0);

  end;

  if Status = SQL_SUCCESS then

    Status := Command.execute(Cursor);

  Command.close; {now that we have a cursor, close the command }


getErrorMessage (SQLCommand)

C++ example	Object Pascal example	See also

C++ syntax:

virtual SQLResult GCCSTDC getErrorMessage (pBYTE pszError) = 0;

Object Pascal syntax:

function getErrorMessage(Error : PChar) : SQLResult; overload; stdcall;

Description

getErrorMessage retrieves an error string for the last command that was sent to the server. Thus, if the last method that accessed the server returned an error code, calling getErrorMessage returns an error message for that error code. Note that once an application calls getErrorMessage, the error message is cleared and subsequent calls will not return the error message.

getErrorMessage returns SQL_SUCCESS if the error message is successfully returned. Otherwise, it returns an error code.

Parameters

pszError (Error) is a buffer that receives the null-terminated error string. Use the getErrorMessageLen method to determine the size required for this buffer.


getErrorMessageLen (SQLCommand)

C++ example	Object Pascal example	See also

C++ syntax:

virtual SQLResult GCCSTDC getErrorMessageLen (pUINT16 puErrorLen) = 0;

Object Pascal syntax:

function getErrorMessageLen(out ErrorLen: SmallInt) : SQLResult; stdcall;

Description

getErrorMessageLen indicates the number of characters (bytes) in an error string for the last command that was sent to the server. Use this method before allocating a buffer to hold the error message that the getErrorMessage method returns. The buffer needs to be puErrorLen + 1 bytes (an additional byte for the null terminating character).

Parameters

puErrorLen (ErrorLen) returns the number of bytes in the error string as a 16-bit integer.


SQLCursor

C++ syntax	Object Pascal syntax	See also

SQLCursor holds data and metadata that was returned by a query or stored procedure when it executes. It has methods for obtaining information about the individual fields and for getting their values.

Note:	SQLCursor can’t be used to change field values. To update records, you must write an UPDATE query.

Methods

setOption

getOption

getErrorMessage

getErrorMessageLen

getColumnCount

getColumnNameLength

getColumnName

getColumnType

getColumnLength

getColumnPrecision

getColumnScale

isNullable

isReadOnly

isSearchable

isBlobSizeExact

next

getString

getShort

getLong

getDouble

getBcd

getTimeStamp

getTime

getDate

getBytes

getBlobSize

getBlob


SQLCursor: C++ syntax

abstract COMINTF SQLCursor

{

   virtual INT32 GCCSTDC QueryInterface( GUID riid, ppVOID ppv ) = 0;

   virtual UINT32 GCCSTDC  AddRef( ) = 0;

   //Destructs the SQLCursor object

   virtual UINT32 GCCSTDC  Release( ) = 0;

   //Error handling

   virtual SQLResult GCCSTDC getErrorMessage (

      pBYTE pszError );

   virtual SQLResult GCCSTDC getErrorMessageLen (

      pUINT16 puErrorLen );

   //Metadata access methods

   virtual SQLResult GCCSTDC getColumnCount (pUINT16 puColumns) = 0;

   virtual SQLResult GCCSTDC getColumnNameLength (

      UINT16  uColumnNumber,

      pUINT16 puLen ) = 0;

   virtual SQLResult GCCSTDC getColumnName (

      UINT16 uColumnNumber,

      pCHAR  pColumnName) = 0;

   virtual SQLResult GCCSTDC getColumnType (

      UINT16  uColumnNumber,

      pUINT16 puType,

      pUINT16 puSubType ) = 0;

   virtual SQLResult GCCSTDC getColumnLength (

      UINT16  uColumnNumber,

      pUINT32 pulLength ) = 0;

   virtual SQLResult GCCSTDC getColumnPrecision (

      UINT16 uColumnNumber,

      pINT16 piPrecision ) = 0;

   virtual SQLResult GCCSTDC getColumnScale (

      UINT16 uColumnNumber,

      pINT16 piScale ) = 0;

   virtual SQLResult GCCSTDC isNullable (

      UINT16 uColumnNumber,

      pBOOL  pbNullable ) = 0;

   virtual> SQLResult GCCSTDC  isAutoIncrement (

      UINT16 uColumnNumber,

      pBOOL  pbAutoIncr ) = 0;

   virtual> SQLResult GCCSTDC isReadOnly (

      UINT16 uColumnNumber,

      pBOOL  pbReadOnly ) = 0;

   virtual SQLResult GCCSTDC isSearchable(

      UINT16 uColumnNumber,

      pBOOL  pbSearchable ) = 0;

   virtual SQLResult GCCSTDC isBlobSizeExact(

      UINT16 uColumnNumber,

      pBOOL  pbBlobExactSize );

   //Fetch the next record or the next set of records

   virtual SQLResult GCCSTDC  next() = 0;

   //Data access methods

   virtual SQLResult GCCSTDC getString (

      UINT16 uColumnNumber,

      pCHAR  pData,

      pBOOL  pbIsNull );

   virtual SQLResult GCCSTDC getShort (

      UINT16 uColumnNumber,

      pINT16 pData,

      pBOOL  pbIsNull );

   virtual SQLResult GCCSTDC getLong (

      UINT16 uColumnNumber,

      pINT32 pData,

      pBOOL  pbIsNull );

   virtual SQLResult GCCSTDC getDouble (

      UINT16 uColumnNumber,

      pDFLOAT  pData,

      pBOOL  pbIsNull );

   virtual SQLResult GCCSTDC getBcd (

      UINT16 uColumnNumber,

      pFMTBcd  pData,

      pBOOL  pbIsNull );

   virtual SQLResult GCCSTDC getTimeStamp (

      UINT16          uColumnNumber,

      pSQLLTIMESTAMP  pData,

      pBOOL           pbIsNull );

   virtual SQLResult GCCSTDC getTime (

      UINT16     uColumnNumber,

      pINT32     pData,

      pBOOL      pbIsNull );

   virtual SQLResult GCCSTDC getDate (

      UINT16     uColumnNumber,

      pINT32     pData,

      pBOOL      pbIsNull );

   virtual SQLResult GCCSTDC getBytes (

      UINT16     uColumnNumber,

      pBYTE      pData,

      pBOOL      pbIsNull );

   virtual SQLResult GCCSTDC getBlobSize (

      UINT16  uColumnNumber,

      pUINT32 pulLength,

      pBOOL   bIsNull );

   virtual SQLResult GCCSTDC getBlob (

      UINT16 uColumnNumber,

      pVOID  pData,

      pBOOL  bIsNull,

      UINT32 ulLength );

};


ISQLCursor: Object Pascal syntax

ISQLCursor = interface

   function setOption(

       eOption : TSQLCursorOption;

       PropValue : LongInt): SQLResult; stdcall;

   function getOption(

       eOption : TSQLCursorOption; P

       PropValue : Pointer;

       MaxLength: SmallInt;

       out Length: SmallInt): SQLResult; stdcall;

   function getErrorMessage(

       Error : PChar) : SQLResult; overload; stdcall;

   function getErrorMessageLen(

       out ErrorLen: SmallInt): SQLResult; stdcall;

   function getColumnCount(var pColumns : Word) : SQLResult; stdcall;

   function getColumnNameLength(

      ColumnNumber : Word;

      var pLen : Word) : SQLResult; stdcall;

   function getColumnName(

      ColumnNumber : Word;

      pColumnName : PChar) : SQLResult; stdcall;

   function getColumnType(

      ColumnNumber : Word;

      var puType : Word;

      var puSubType : Word) : SQLResult; stdcall;

   function  getColumnLength(

      ColumnNumber : Word;

      var pLength : LongWord) : SQLResult; stdcall;

   function getColumnPrecision(

      ColumnNumber : Word;

      var piPrecision : SmallInt) : SQLResult; stdcall;

   function getColumnScale(

      ColumnNumber : Word;

      var piScale : SmallInt) : SQLResult; stdcall;

   function isNullable(

      ColumnNumber : Word;

      var Nullable : LongBool) : SQLResult; stdcall;

   function isAutoIncrement(

      ColumnNumber : Word;

      var AutoIncr : LongBool) : SQLResult; stdcall;

   function isReadOnly(

      ColumnNumber : Word;

      var ReadOnly : LongBool) : SQLResult; stdcall;

   function isSearchable(

      ColumnNumber : Word;

      var Searchable : LongBool) : SQLResult; stdcall;

   function isBlobSizeExact(

      ColumnNumber : Word;

      var IsExact : LongBool) : SQLResult; stdcall;

   function next : SQLResult; stdcall;

   function getString(

      ColumnNumber : Word;

      Value : Pointer;

      var IsBlank : LongBool) : SQLResult; stdcall;

   function getShort(

       ColumnNumber : Word;

       Value : Pointer;

       var IsBlank : LongBool) : SQLResult; stdcall;

   function getLong(

       ColumnNumber : Word;

       Value : Pointer;

       var IsBlank : LongBool) : SQLResult; stdcall;

   function getDouble(

       ColumnNumber : Word;

       Value : Pointer;

       var IsBlank : LongBool) : SQLResult; stdcall;

   function getBcd(

       ColumnNumber : Word;

       Value : Pointer;

       var IsBlank : LongBool) : SQLResult; stdcall;

   function getTimeStamp(

       ColumnNumber : Word;

       Value : Pointer;

       var IsBlank : LongBool) : SQLResult; stdcall;

   function getTime(C

       ColumnNumber : Word;

       Value : Pointer;

       var IsBlank : LongBool) : SQLResult; stdcall;

   function getDate(

       ColumnNumber : Word;

       Value : Pointer;

       var IsBlank : LongBool) : SQLResult; stdcall;

   function getBytes(

       ColumnNumber : Word;

       Value : Pointer;

       var IsBlank : LongBool): SQLResult; stdcall;

   function getBlobSize(

       ColumnNumber : Word;

       var Length : LongWord;

       var IsBlank : LongBool): SQLResult; stdcall;

   function getBlob(

       ColumnNumber : Word;

       Value : Pointer;

       var IsBlank : LongBool;

       Length : LongWord) : SQLResult; stdcall;

end;


setOption (SQLCursor)

C++ example	Object Pascal example	See also

C++ syntax:

virtual SQLResult GCCSTDC setOption (eSQLCursorOption eCurOption, INT32 lValue) = 0;

Object Pascal syntax:

function setOption(eCurOption : TSQLCursorOption; lValue: LongInt) : SQLResult; stdcall;

Description

setOption sets the value of a specified cursor property. Currently, all cursor properties are read-only, so any call to the setOption property of SQLCursor returns DBXERR_NOTSUPPORTED.

Parameters

eCurOption: the name of the cursor property whose value is to be set.

lValue: the value to set. This is a pointer to a structure that indicates the field whose attribute is to be set and the value for that field attribute. The type of the structure depends on eCurOption.


setOption example

Currently, there are no settable properties on SQLCursor.


setOption example

Currently, there are no settable properties on SQLCursor.


getOption (SQLCursor)

C++ example	Object Pascal example	See also

C++ syntax:

virtual SQLResult GCCSTDC getOption (eSQLCursorOption eCurOption, pINT32 plValue, INT16 iMaxLength, pINT16 piLength) = 0;

Object Pascal syntax:

function getOption(eCurOption : TSQLCursorOption; plValue: Pointer; iMaxLength: SmallInt; out Length SmallInt) : SQLResult; stdcall;

Description

getOption retrieves the value of a specified cursor property. Cursor properties are typically used to get the value of a field attribute. getOption returns SQL_SUCCESS if the property value is successfully fetched, otherwise an error code.

Parameters

eCurOption: the name of the cursor property whose value is to be retrieved.

plValue: a pointer to a structure that indicates the field whose attribute is desired and which is filled in to return the field attribute. The type of the structure depends on eCurOption.

iMaxLength: The size of the structure to which plValue points.

piLength (Length): Returns the number of bytes written to plValue.


getOption example

short int Type, NotUsed;

SQLResult Status = pCursor->getColumnType(1, &Type, &NotUsed);

if (Status == SQL_SUCCESS && Type == fldADT)

{

  ObjTypeDesc td;

  td.uColNum = 1;

  Status = pConnection->getOption(eCurObjectTypeName, &td, sizeof(ObjTypeDesc), &NotUsed);

  // do something with the type name

}


getOption example

var

  Type, NotUsed: SmallInt;

  Status: SQLResult;

  TypeDesc: ObjTypeDesc;

begin

  Status := Connection.getColumnType(1, Type, NotUsed);

  if (Status = SQL_SUCCESS) and (Type = fldADT) then

  begin

    TypeDesc.uColNum := 1;

    Status := Connection.getOption(eCurObjectTypeName, Addr(TypeDesc), SizeOf(ObjTypeDesc), NotUsed);

    ...


getErrorMessage (SQLCursor)

C++ example	Object Pascal example	See also

C++ syntax:

virtual SQLResult GCCSTDC getErrorMessage (pBYTE pszError) = 0;

Object Pascal syntax:

function getErrorMessage(Error : PChar) : SQLResult; overload; stdcall;

Description

getErrorMessage retrieves an error string for the last command that was sent to the server. Thus, if the last method that accessed the server returned an error code, calling getErrorMessage returns an error message for that error code. Note that once an application calls getErrorMessage, the error message is cleared and subsequent calls will not return the error message.

getErrorMessage returns SQL_SUCCESS if the error message is successfully returned. Otherwise, it returns an error code.

Parameters

pszError (Error) is a buffer that receives the null-terminated error string. Use the getErrorMessageLen method to determine the size required for this buffer.


getErrorMessageLen (SQLCursor)

C++ example	Object Pascal example	See also

C++ syntax:

virtual SQLResult GCCSTDC getErrorMessageLen (pUINT16 puErrorLen) = 0;

Object Pascal syntax:

function getErrorMessageLen(out ErrorLen: SmallInt) : SQLResult; stdcall;

Description

getErrorMessageLen indicates the number of characters (bytes) in an error string for the last command that was sent to the server. Use this method before allocating a buffer to hold the error message that the getErrorMessage method returns. The buffer needs to be puErrorLen + 1 bytes (an additional byte for the null terminating character).

Parameters

puErrorLen (ErrorLen) returns the number of bytes in the error string as a 16-bit integer.


getColumnCount (SQLCursor)

C++ example	Object Pascal example

C++ syntax:

virtual SQLResult GCCSTDC getColumnCount (pUINT16 puColumns) = 0;

Object Pascal syntax:

function getColumnCount(var puColumns: Word) : SQLResult; stdcall;

Description

getColumnCount retrieves the number of columns (fields) in a single record. This value can be used as an upper bound for the column number when iterating over all of the fields in a record. getColumnCount returns SQL_SUCCESS if the number of columns is successfully returned, an error code otherwise.

Parameters

puColumns returns the number of columns.


getColumnCount example

short int nCols;

Status = pCursor->getColumnCount(&nCols);

if (Status == SQL_SUCCESS)

{

  for (int i = 1; i <= nCols; i++)

  {

    // do something with each field in the record

  }

}


getColumnCount example

var

  nCols: Word;

  Status: SQLResult;

  FldNo: Integer;

begin

  Status := Cursor.getColumnCount(nCols);

  if Status = SQL_SUCCESS then

    for FldNo := 1 to nCols do

    begin

      { do something for each field in the record }

    end;


getColumnNameLength (SQLCursor)

C++ example	Object Pascal example	See also

C++ syntax:

virtual SQLResult GCCSTDC getColumnNameLength (UINT16 uColumnNumber, pUINT16 puLen) = 0;

Object Pascal syntax:

function getColumnNameLength(uColumnNumber: Word; var puLen: Word) : SQLResult; stdcall;

Description

getColumnNameLength retrieves the number of characters (bytes) needed for the name of a specified column. Use this method to determine the buffer size needed for calling the getColumnName method.

getColumnNameLen returns SQL_SUCCESS if the column name length is returned in the puLen parameter, an error code otherwise.

Parameters

uColumnNumber identifies the column (field) for which you want the size of the name. The first column is specified by 1, the second by 2 and so on. Use the getColumnCount method to obtain an upper bound on the possible values.

puLen returns the number of bytes needed for the column name. When using this value to allocate a buffer to receive the column name, add one to puLen for the terminating null character.


getColumnNameLength example

short int nCols;

Status = pCursor->getColumnCount(&nCols);

if (Status == SQL_SUCCESS)

{

  for (int i = 1; i <= nCols; i++)

  {

    short int Len;

    Status = pCursor->getColumnNameLength(i, &Len);

    if (Status == SQL_SUCCESS)

    {

      char *pName = (char *)malloc(Len + 1);

      if (pName)

      {

        Status = pCursor->getColumnName(i, pName);

        if (Status == SQL_SUCCESS)

        {

          // do something with the name;

        }

        free(pName);

      }

    }

  }

}


getColumnNameLength example

var

  nCols, Len: Word;

  Status: SQLResult;

  FldNo: Integer;

  Name: PChar;

begin

  Status := Cursor.getColumnCount(nCols);

  if Status = SQL_SUCCESS then

    for FldNo := 1 to nCols do

    begin

      Status = Cursor.getColumnNameLength(FldNo, Len);

      if Status = SQL_SUCCESS then

      begin

        Name := AllocMem(Len + 1);

        if Assigned(Name) then

        begin

          Status := Cursor.getColumnName(Name);

          { do something with the field name }

          FreeMem(Name);

        end;

      end;

    end;

end;


getColumnName (SQLCursor)

C++ example	Object Pascal example	See also

C++ syntax:

virtual SQLResult GCCSTDC getColumnName (UINT16 uColumnNumber, pCHAR pColumnName) = 0;

Object Pascal syntax:

function getColumnName(uColumnNumber: Word; pColumnName: PChar) : SQLResult; stdcall;

Description

getColumnName retrieves the name of a specified column (field). getColumnName returns SQL_SUCCESS if the column name is returned in the pColumnName parameter, an error code otherwise.

Parameters

uColumnNumber identifies the column (field) for which you want the name. The first column is specified by 1, the second by 2 and so on. Use the getColumnCount method to obtain an upper bound on the possible values.

pColumnName points to a buffer that receives the column name. Use the getColumnNameLength method to determine how big this buffer must be.


getColumnName example

short int nCols;

Status = pCursor->getColumnCount(&nCols);

if (Status == SQL_SUCCESS)

{

  for (int i = 1; i <= nCols; i++)

  {

    short int Len;

    Status = pCursor->getColumnNameLength(i, &Len);

    if (Status == SQL_SUCCESS)

    {

      char *pName = (char *)malloc(Len + 1);

      if (pName)

      {

        Status = pCursor->getColumnName(i, pName);

        if (Status == SQL_SUCCESS)

        {

          // do something with the name;

        }

        free(pName);

      }

    }

  }

}


getColumnName example

var

  nCols, Len: Word;

  Status: SQLResult;

  FldNo: Integer;

  Name: PChar;

begin

  Status := Cursor.getColumnCount(nCols);

  if Status = SQL_SUCCESS then

    for FldNo := 1 to nCols do

    begin

      Status = Cursor.getColumnNameLength(FldNo, Len);

      if Status = SQL_SUCCESS then

      begin

        Name := AllocMem(Len + 1);

        if Assigned(Name) then

        begin

          Status := Cursor.getColumnName(Name);

          if Status = SQL_Success then

            { do something with the field name }

          FreeMem(Name);

        end;

      end;

    end;

end;


getColumnType (SQLCursor)

C++ example	Object Pascal example	See also

C++ syntax:

virtual SQLResult GCCSTDC getColumnType (UINT16 uColumnNumber, pUINT16 puType, pUINT16 puSubType) = 0;

Object Pascal syntax:

function getColumnType(uColumnNumber: Word; var puType: Word; var puSubType: Word) : SQLResult; stdcall;

Description

getColumnType retrieves the logical data type and subtype for a specified column. getColumnType returns SQL_SUCCESS if the type and subtype are returned in the puType and puSubType parameters, an error code otherwise.

Note:	For some field types, additional information is required to determine the field type. For example, with string fields, you must also know the maximum length of the strings, with BCD fields you must know the precision and scale, with ADT fields, you need to know the number of members (both immediate children and the count that includes children of those children). Use the getColumnPrecision and getColumnScale methods to retrieve that addtional information for field types that require it.

Parameters

uColumnNumber identifies the column (field) for which you want the data type. The first column is specified by 1, the second by 2 and so on. Use the getColumnCount method to obtain an upper bound on the possible values.

puType returns the logical field type for the column. The return value is one of the values in the Field Type column of the table of logical data types.

puSubType returns the logical subtype for the column. The return value is one of the values in the Field Subtype column of the table of logical data types.


getColumnType example

short int Type, SubType;

SQLResult Status = pCursor->getColumnType(1, &Type, &SubType);


getColumnType example

var

  Type, SubType: Word;

  Status: SQLResult;

begin

  Status := Cursor.getColumnType(1, Type, SubType);


getColumnLength (SQLCursor)

C++ example	Object Pascal example	See also

C++ syntax:

virtual SQLResult GCCSTDC getColumnLength (UINT16 uColumnNumber, pUINT32 pulLength) = 0;

Object Pascal syntax:

function getColumnLength(uColumnNumber: Word; var pulLength: LongWord) : SQLResult; stdcall;

Description

getColumnLength retrieves the length, in bytes, of the values in a specified column. This size can be used when allocating a buffer to hold field values from the specified column. getColumnLength returns SQL_SUCCESS if the length is successfully returned, an error code otherwise.

Parameters

uColumnNumber identifies the column (field) for which you want the size. The first column is specified by 1, the second by 2 and so on. Use the getColumnCount method to obtain an upper bound on the possible values.

pulLength returns the number of bytes required to hold the logical field values for this column.


getColumnLength example

unsigned int Size;

SQLResult Status = pCursor->getColumnLength(1, &Size);


getColumnLength example

var

  Size: LongWord;

  Status: SQLResult;

begin

  Status := Cursor.getColumnLength(1, Size);


getColumnPrecision (SQLCursor)

C++ example	Object Pascal example	See also

C++ syntax:

virtual SQLResult GCCSTDC getColumnPrecision (UINT16 uColumnNumber, pINT16 piPrecision) = 0;

Object Pascal syntax:

function getColumnPrecision(uColumnNumber: Word; var piPrecision: SmallInt) : SQLResult; stdcall;

Description

getColumnPrecision retrieves the number of digits, characters, or elements of a field value. The interpretation of the precision depends on the column type, as indicated in the following table:

Column Type	Meaning of precision

fldZSTRING	Maximum number of characters in the string.

fldBytes	Number of bytes in the field value.

fldVarBytes	Maximum number of bytes in the field, ignoring the first two bytes that are used to indicate the length.

fldBCD	Number of significan digits in the BCD values. (Note that the number of decimal places is returned by the getColumnScale method.)

fldADT	The number of immediate child members of the ADT field. (Note that if any of these child members are ADT fields, the total number of children, which is returned by the getColumnScale method, will exceed the precision value.)

fldArray	The number of elements in the array. (Note that if the array element type is an ADT or array field, the total number of child elements, which is returned by the getColumnScale method, will exceed the precision value.)

Do not call getColumnPrecision for any other column type. To determine the column type, which can be used for interpreting the meaning of the precision, call the getColumnType method.

Parameters

uColumnNumber identifies the column (field) for which you want the precision. The first column is specified by 1, the second by 2 and so on. Use the getColumnCount method to obtain an upper bound on the possible values.

piPrecision returns the precision for the column’s data type.


getColumnPrecision example

short int Size;

SQLResult Status = pCursor->getColumnPrecision(1, &Size);


getColumnPrecision example

var

  Size: SmallInt;

  Status: SQLResult;

begin

  Status := Cursor.getColumnPrecision(1, Size);


getColumnScale (SQLCursor)

C++ example	Object Pascal example	See also

C++ syntax:

virtual SQLResult GCCSTDC getColumnScale (UINT16 uColumnNumber, pINT16 piScale) = 0;

Object Pascal syntax:

function getColumnScale(uColumnNumber: Word; var piScale: SmallInt) : SQLResult; stdcall;

Description

getColumnScale retrieves the number of subelements of a field value. The interpretation of the scale depends on the column type, as indicated in the following table:

Column Type	Meaning of scale

fldBCD	The number of digits past the decimal.

fldADT	The total number of child fields, including those that are children of child fields that are also ADT fields.

fldArray	The number of child elements, including those that are children of array elements when the array contains ADT fields as elements.

getColumnScale returns SQL_SUCCESS if the scale is successfully retrieved into piScale. It returns an error code otherwise.

Parameters

uColumnNumber identifies the column (field) for which you want the precision. The first column is specified by 1, the second by 2 and so on. Use the getColumnCount method to obtain an upper bound on the possible values.

piScale returns the scale for the specified column.


getColumnScale example

short int Type, SubType;

SQLResult Status = pCursor->getColumnType(1, &Type, &SubType);

if (Status == SQL_SUCCESS && Type == fldBCD)

{

  short int Precision, Scale;

  pCursor->getColumnPrecision(1, &Precision);

  pCursor->getColumnScale(1, &Scale);

  // do something now that column type is fully known.

}


getColumnScale example

var

  Type, SubType: Word;

  Precision, Scale: SmallInt;

  Status: SQLResult;

begin

  Status := Cursor.getColumnType(1, Type, SubType);

  if (Status = SQL_SUCCESS) and (type = fldBCD) then

  begin

    Cursor.getColumnPrecision(1, Precision);

    Cursor.getColumnScale(1, Scale);

    ...


isNullable (SQLCursor)

C++ example	Object Pascal example	See also

C++ syntax:

virtual SQLResult GCCSTDC isNullable (UINT16 uColumnNumber, pBOOL pbNullable) = 0;

Object Pascal syntax:

function isNullable(uColumnNumber: Word; var pbNullable: LongBool) : SQLResult; stdcall;

Description

isNullable indicates whether a specified column can have a null value (can be left blank). It returns SQL_SUCCESS if it successfully returns an indication of whether the specified column is nullable. It returns an error code otherwise.

Parameters

uColumnNumber identifies the column (field) about which you want information. The first column is specified by 1, the second by 2 and so on. Use the getColumnCount method to obtain an upper bound on the possible values.

pbNullable returns true if the column can be blank, false if it requires a value.


isNullable example

BOOL CanBeBlank;

SQLResult Status = pCursor->isNullable(1, &CanBeBlank);


isNullable example

var

  CanBeBlank: LongBool;

  Status: SQLResult;

begin

  Status := Cursor.isNullable(1, CanBeBlank);


isAutoIncrement (SQLCursor)

C++ example	Object Pascal example	See also

C++ syntax:

virtual SQLResult GCCSTDC isAutoIncrement (UINT16 uColumnNumber, pBOOL pbAutoIncr) = 0;

Object Pascal syntax:

function isAutoIncrement(uColumnNumber: Word; var pbAutoIncr: LongBool) : SQLResult; stdcall;

Description

isAutoIncrement indicates whether a specified column represents a value that can be generated by the database server. Such columns include auto-incrementing fields and fields with default values. When a field can be generated by the server, applications should refresh the data after making updates so that they fetch the newly-generated value. isAutoIncrement returns SQL_SUCCESS if it successfully returns an indication of whether the specified column can have a server-generated value. It returns an error code otherwise.

Parameters

uColumnNumber identifies the column (field) about which you want information. The first column is specified by 1, the second by 2 and so on. Use the getColumnCount method to obtain an upper bound on the possible values.

pbAutoIncr returns true if the column value can be generated by the server, false if new values can only be set by client applications.


isAutoIncrement example

BOOL ServerGeneratedValue;

SQLResult Status = pCursor->isAutoIncrement(1, &ServerGeneratedValue);


isAutoIncrement example

var

  ServerGeneratedValue: LongBool;

  Status: SQLResult;

begin

  Status := Cursor.isAutoIncrement(1, ServerGeneratedValue);


isReadOnly (SQLCursor)

C++ example	Object Pascal example	See also

C++ syntax:

virtual SQLResult GCCSTDC isReadOnly (UINT16 uColumnNumber, pBOOL pbReadOnly) = 0;

Object Pascal syntax:

function isReadOnly(uColumnNumber: Word; var pbReadOnly: LongBool) : SQLResult; stdcall;

Description

isReadOnly indicates whether a specified column represents a read-only field. It returns SQL_SUCCESS if it successfully returns an indication of whether field values for the specified column can be updated by an UPDATE query. It returns an error code otherwise.

Parameters

uColumnNumber identifies the column (field) about which you want information. The first column is specified by 1, the second by 2 and so on. Use the getColumnCount method to obtain an upper bound on the possible values.

pbReadOnly returns true if the column value is read-only, false if it can be changed by an UPDATE query.


isReadOnly example

BOOL ReadOnly;

SQLResult Status = pCursor->isReadOnly(1, &ReadOnly);


isReadOnly example

var

  ReadOnly: LongBool;

  Status: SQLResult;

begin

  Status := Cursor.isReadOnly(1, ReadOnly);


isSearchable (SQLCursor)

C++ example	Object Pascal example	See also

C++ syntax:

virtual SQLResult GCCSTDC isSearchable (UINT16 uColumnNumber, pBOOL pbSearchable) = 0;

Object Pascal syntax:

function isSearchable(uColumnNumber: Word; var pbSearchable: LongBool) : SQLResult; stdcall;

Description

isSearchable indicates whether a specified column represents a field that can appear in the WHERE clause of an SQL query. It returns SQL_SUCCESS if it successfully returns an indication of whether field can appear in a WHERE clause. It returns an error code otherwise.

Parameters

uColumnNumber identifies the column (field) about which you want information. The first column is specified by 1, the second by 2 and so on. Use the getColumnCount method to obtain an upper bound on the possible values.

pbSearchable returns true if the column represents a field that can appear in the WHERE clause of an SQL query, false if not.


isSearchable example

BOOL AddToWhereClause;

SQLResult Status = pCursor->isSearchable(1, &AddToWhereClause);


isSearchable example

var

  AddToWhereClause: LongBool;

  Status: SQLResult;

begin

  Status := Cursor.isSearchable(1, AddToWhereClause);


isBlobSizeExact (SQLCursor)

C++ example	Object Pascal example	See also

C++ syntax:

virtual SQLResult GCCSTDC isBlobSizeExact (UINT16 uColumnNumber, pBOOL pbBlobExactSize) = 0;

Object Pascal syntax:

function isBlobSizeExact(uColumnNumber: Word; var pbBlobExactSize: LongBool) : SQLResult; stdcall;

Description

isBlobSizeExact indicates whether the getBlobSize method can accurately return the size of BLOB field value. If isBlobSizeExact returns true, the value returned by getBlobSize can be used when allocating a buffer to hold the BLOB field’s value. If isBlobSizeExact returns false, then the buffer must be set to the maximum BLOB size that is specified as an option of the SQLCommand, SQLConnection, or SQLDriver object. isBlobSizeExact returns SQL_SUCCESS if it successfully returns an indication of whether getBlobSize can be used. It returns an error code otherwise.

Parameters

uColumnNumber identifies the column (field) about which you want information. This should represent a field of type fldBLOB (any subtype). The first column is specified by 1, the second by 2 and so on. Use the getColumnCount method to obtain an upper bound on the possible values.

pbBlobExactSize returns true if the getBlobSize method returns the size of the field’s value, false if not.


isBlobSizeExact example

short int Type, SubType;

SQLResult Status = pCursor->getColumnType(1, &Type, &SubType);

if (Status == SQL_SUCCESS && Type == fldBLOB)

{

  BOOL bBlobIsNull = False;

  unsignedint BlobSize;

  BOOL bCanUseSize;

  Status = pCursor->isBlobSizeExact(1, &bCanUseSize);

  if (Status == SQL_SUCCESS && bCanUseSize)

    pCursor->getBlobSize(1, &BlobSize, &bBlobIsNull);

  else

  {

    short int Len = 1;

    pConnection->getOption(eDrvBlobSize, &BlobSize, sizeof(int), &Len);

  }

  pVOID Buffer;

  if (!bBlobIsNull)

  {

    Buffer = malloc(BlobSize);

    if (Buffer)

      Status = pCursor->getBlob(1, Buffer, &bBlobIsNull, BlobSize);

  }

  if (Status == SQL_SUCCESS && !bBlobIsNull)

  {

    // do something with the BLOB value in the buffer

  }

  if (Buffer)

    free(Buffer)

}


isBlobSizeExact example

var

  Type, NotUsed: Word;

  Status: SQLResult;

  BlobIsNull, CanUseSize: LongBool;

  BlobSize: Word;

  Buffer: Pointer;

begin

  Status := Cursor.getColumnType(1, Type, NotUsed);

  if (Status = SQL_SUCCESS) and (type = fldBLOB) then

  begin

    BlobIsNull = False;

    Status = Cursor.isBlobSizeExact(1, CanUseSize);

    if (Status = SQL_SUCCESS) and CanUseSize then

      Cursor.getBlobSize(1, BlobSize, BlobIsNull)

    else

      Connection.getOption(eDrvBlobSize, Addr(BlobSize), SizeOf(Integer), NotUsed);

    if not BlobIsNull then

    begin

      Buffer := AllocMem(BlobSize);

      if Assigned(Buffer) then

        Status := Cursor.getBlob(1, Buffer, BlobIsNull, BlobSize);

    end;

    if (Status = SQL_SUCCESS) and (not BlobIsNull) then

      { do something with the BLOB value in the buffer};

    if Assigned(Buffer) then

      FreeMem(Buffer);

  end;

end;


next (SQLCursor)

C++ example	Object Pascal example

C++ syntax:

virtual SQLResult GCCSTDC next () = 0;

Object Pascal syntax:

function next: SQLResult; stdcall;

Description

next moves the cursor to the next record. It returns SQL_SUCCESS if it successfully moves to the next record, an error code otherwise. next returns DBXERR_EOF when you try to move past the last record.


next example

SQLResult Status;

do

{

  // process each record

  Status = pCursor->next();

} while (Status == SQL_SUCCESS);


next example

repeat

  {process each record }

  Status := Cursor.next;

until Status <> SQL_SUCCESS);


getString (SQLCursor)

C++ example	Object Pascal example	See also

C++ syntax:

virtual SQLResult GCCSTDC getString (UINT16 uColumnNumber, pCHAR pData, pBOOL pbIsNull) = 0;

Object Pascal syntax:

function getString(uColumnNumber: Word; pData: Pointer; var pbIsNull: LongBool) : SQLResult; stdcall;

Description

getString retrieves the value of a string field. Use the getColumnType method to check that the field is of type fldZSTRING before calling getString. getString returns SQL_SUCCESS if it successfully retrieves a field value, an error code otherwise.

Parameters

uColumnNumber identifies the column (field) whose value you want to fetch. The first column is specified by 1, the second by 2 and so on. Use the getColumnCount method to obtain an upper bound on the possible values.

pData is a buffer to receive the string. Use the getColumnPrecision method to determine the size this buffer needs to be.

pbIsNull indicates whether the field value is blank (NULL).


getString example

short int nCols;

Status = pCursor->getColumnCount(&nCols);

if (Status == SQL_SUCCESS)

{

  for (int i = 1; i <= nCols; i++)

  {

    short int Type, SubType;

    Status = pCursor->getColumnType(i, &Type, &SubType);

    if (Status == SQL_SUCCESS)

    {

      short int Length;

      BOOL bIsNull;

      switch (Type)

      {

        case fldZSTRING:

          Status = pCursor->getColumnPrecision(i, &Length);

          if (Status == SQL_SUCCESS)

          {

            char *pString = (char *)malloc(Length + 1);

            if (pString)

            {

              Status = pCursor->getString(i, pString, &bIsNull);

              if (Status == SQL_SUCCESS && !bIsNull)

              {

                // do something with the field value;

              }

              free(pString);

            }

          }

          break;

        // fetch values for other field types in other cases

      }

    }

  }

}


getString example

var

  nCols, Type, SubType, FldNo, Precision: Word;

  NullValue: LongBool;

  Status: SQLResult;

  Value: Pointer;

begin

  Status := Cursor.getColumnCount(nCols);

  if Status = SQL_SUCCESS then

    for FldNo := 1 to nCols do

    begin

      Value := nil;

      Status = Cursor.getColumnType(FldNo, Type, SubType);

      if Status = SQL_SUCCESS then

      begin

        case Type of

          fldZString:

            begin

              Status := Cursor.getColumnPrecision(FldNo, Precision);

              if Status = SQL_SUCCESS then

                Value = AllocMem(Precision + 1);

              if Assigned(Value) then

                Status := Cursor.getString(FldNo, Value, NullValue);

              if Status <> SQL_SUCCESS then

                NullValue := True; { treat failure like blank field }

            end;

          {fetch the values for other field types in other cases }

        end;

        if Assigned(Value) then

        begin

          { do something with the field value }

          FreeMem(Value);

        end;

      end;

    end; { for loop }

end;


getShort (SQLCursor)

C++ example	Object Pascal example	See also

C++ syntax:

virtual SQLResult GCCSTDC getShort (UINT16 uColumnNumber, pINT16 pData, pBOOL pbIsNull) = 0;

Object Pascal syntax:

function getShort(uColumnNumber: Word; pData: Pointer; var pbIsNull: LongBool) : SQLResult; stdcall;

Description

getShort retrieves the value of a field with type fldINT16 or fldBOOL. Use the getColumnType method to check the field type before calling getShort. getShort returns SQL_SUCCESS if it successfully retrieves a field value, an error code otherwise.

Parameters

uColumnNumber identifies the column (field) whose value you want to fetch. The first column is specified by 1, the second by 2 and so on. Use the getColumnCount method to obtain an upper bound on the possible values.

pData is a buffer to receive the value.

pbIsNull indicates whether the field value is blank (NULL).


getShort example

short int nCols;

Status = pCursor->getColumnCount(&nCols);

if (Status == SQL_SUCCESS)

{

  for (int i = 1; i <= nCols; i++)

  {

    short int Type, SubType;

    Status = pCursor->getColumnType(i, &Type, &SubType);

    if (Status == SQL_SUCCESS)

    {

      BOOL bIsNull;

      switch (Type)

      {

        case fldINT16:

        case fldBOOL:

          short int Value;

          Status = pCursor->getShort(i, &Value, &bIsNull);

          if (Status == SQL_SUCCESS && !bIsNull)

          {

            // do something with the field value;

          }

          break;

        // fetch values for other field types in other cases

      }

    }

  }

}


getShort example

var

  nCols, Type, SubType, FldNo, Precision: Word;

  NullValue: LongBool;

  Status: SQLResult;

  Value: Pointer;

begin

  Status := Cursor.getColumnCount(nCols);

  if Status = SQL_SUCCESS then

    for FldNo := 1 to nCols do

    begin

      Value := nil;

      Status = Cursor.getColumnType(FldNo, Type, SubType);

      if Status = SQL_SUCCESS then

      begin

        case Type of

          fldINT16, fldBOOL:

            begin

              Value = AllocMem(SizeOf(SmallInt));

              if Assigned(Value) then

                Status := Cursor.getShort(FldNo, Value, NullValue);

              if Status <> SQL_SUCCESS then

                NullValue := True; { treat failure like blank field }

            end;

          {fetch the values for other field types in other cases }

        end;

        if Assigned(Value) then

        begin

          { do something with the field value }

          FreeMem(Value);

        end;

      end;

    end; { for loop }

end;


getLong (SQLCursor)

C++ example	Object Pascal example	See also

C++ syntax:

virtual SQLResult GCCSTDC getLong (UINT16 uColumnNumber, pINT32 pData, pBOOL pbIsNull) = 0;

Object Pascal syntax:

function getLong(uColumnNumber: Word; pData: Pointer; var pbIsNull: LongBool) : SQLResult; stdcall;

Description

getLong retrieves the value of a field that is a 32-bit integer. Use the getColumnType method to check that the field is of type fldINT32 before calling getLong. getLong returns SQL_SUCCESS if it successfully retrieves a field value, an error code otherwise.

Parameters

uColumnNumber identifies the column (field) whose value you want to fetch. The first column is specified by 1, the second by 2 and so on. Use the getColumnCount method to obtain an upper bound on the possible values.

pData is a buffer to receive the value.

pbIsNull indicates whether the field value is blank (NULL).


getLong example

short int nCols;

Status = pCursor->getColumnCount(&nCols);

if (Status == SQL_SUCCESS)

{

  for (int i = 1; i <= nCols; i++)

  {

    short int Type, SubType;

    Status = pCursor->getColumnType(i, &Type, &SubType);

    if (Status == SQL_SUCCESS)

    {

      BOOL bIsNull;

      switch (Type)

      {

        case fldINT32:

          long Value;

          Status = pCursor->getLong(i, &Value, &bIsNull);

          if (Status == SQL_SUCCESS && !bIsNull)

          {

            // do something with the field value;

          }

          break;

        // fetch values for other field types in other cases

      }

    }

  }

}


getLong example

var

  nCols, Type, SubType, FldNo, Precision: Word;

  NullValue: LongBool;

  Status: SQLResult;

  Value: Pointer;

begin

  Status := Cursor.getColumnCount(nCols);

  if Status = SQL_SUCCESS then

    for FldNo := 1 to nCols do

    begin

      Value := nil;

      Status = Cursor.getColumnType(FldNo, Type, SubType);

      if Status = SQL_SUCCESS then

      begin

        case Type of

          fldINT32:

            begin

              Value = AllocMem(SizeOf(LongInt));

              if Assigned(Value) then

                Status := Cursor.getLong(FldNo, Value, NullValue);

              if Status <> SQL_SUCCESS then

                NullValue := True; { treat failure like blank field }

            end;

          {fetch the values for other field types in other cases }

        end;

        if Assigned(Value) then

        begin

          { do something with the field value }

          FreeMem(Value);

        end;

      end;

    end; { for loop }

end;


getDouble (SQLCursor)

C++ example	Object Pascal example	See also

C++ syntax:

virtual SQLResult GCCSTDC getDouble (UINT16 uColumnNumber, pDFLOAT pData, pBOOL pbIsNull) = 0;

Object Pascal syntax:

function getDouble(uColumnNumber: Word; pData: Pointer; var pbIsNull: LongBool) : SQLResult; stdcall;

Description

getDouble retrieves the value of a field that is a Double. Use the getColumnType method to check that the field is of type fldFLOAT before calling getDouble. getDouble returns SQL_SUCCESS if it successfully retrieves a field value, an error code otherwise.

Parameters

uColumnNumber identifies the column (field) whose value you want to fetch. The first column is specified by 1, the second by 2 and so on. Use the getColumnCount method to obtain an upper bound on the possible values.

pData is a buffer to receive the value.

pbIsNull indicates whether the field value is blank (NULL).


getDouble example

short int nCols;

Status = pCursor->getColumnCount(&nCols);

if (Status == SQL_SUCCESS)

{

  for (int i = 1; i <= nCols; i++)

  {

    short int Type, SubType;

    Status = pCursor->getColumnType(i, &Type, &SubType);

    if (Status == SQL_SUCCESS)

    {

      BOOL bIsNull;

      switch (Type)

      {

        case fldFLOAT:

          double Value;

          Status = pCursor->getDouble(i, &Value, &bIsNull);

          if (Status == SQL_SUCCESS && !bIsNull)

          {

            // do something with the field value;

          }

          break;

        // fetch values for other field types in other cases

      }

    }

  }

}


getDouble example

var

  nCols, Type, SubType, FldNo, Precision: Word;

  NullValue: LongBool;

  Status: SQLResult;

  Value: Pointer;

begin

  Status := Cursor.getColumnCount(nCols);

  if Status = SQL_SUCCESS then

    for FldNo := 1 to nCols do

    begin

      Value := nil;

      Status = Cursor.getColumnType(FldNo, Type, SubType);

      if Status = SQL_SUCCESS then

      begin

        case Type of

          fldFLOAT:

            begin

              Value = AllocMem(SizeOf(Double));

              if Assigned(Value) then

                Status := Cursor.getDouble(FldNo, Value, NullValue);

              if Status <> SQL_SUCCESS then

                NullValue := True; { treat failure like blank field }

            end;

          {fetch the values for other field types in other cases }

        end;

        if Assigned(Value) then

        begin

          { do something with the field value }

          FreeMem(Value);

        end;

      end;

    end; { for loop }

end;


getBcd (SQLCursor)

C++ example	Object Pascal example	See also

C++ syntax:

virtual SQLResult GCCSTDC getBcd (UINT16 uColumnNumber, pFMTBcd pData, pBOOL pbIsNull) = 0;

Object Pascal syntax:

function getBcd(uColumnNumber: Word; pData: Pointer; var pbIsNull: LongBool) : SQLResult; stdcall;

Description

getBcd retrieves the value of a BCD field. Use the getColumnType method to check that the field is of type fldBCD before calling getBcd. getBcd returns SQL_SUCCESS if it successfully retrieves a field value, an error code otherwise.

Parameters

uColumnNumber identifies the column (field) whose value you want to fetch. The first column is specified by 1, the second by 2 and so on. Use the getColumnCount method to obtain an upper bound on the possible values.

pData is a buffer to receive the BCD value. It should point to a FMTBcd structure in C++ or a TBcd record in Object Pascal.

pbIsNull indicates whether the field value is blank (NULL).


getBcd example

short int nCols;

Status = pCursor->getColumnCount(&nCols);

if (Status == SQL_SUCCESS)

{

  for (int i = 1; i <= nCols; i++)

  {

    short int Type, SubType;

    Status = pCursor->getColumnType(i, &Type, &SubType);

    if (Status == SQL_SUCCESS)

    {

      BOOL bIsNull;

      switch (Type)

      {

        case fldBCD:

          FMTBcd BcdVal;

          Status = pCursor->getBcd(i, &BcdVal, &bIsNull);

          if (Status == SQL_SUCCESS && !bIsNull)

          {

             // do something with the field value;

          }

          break;

        // fetch values for other field types in other cases

      }

    }

  }

}


getBcd example

var

  nCols, Type, SubType, FldNo: Word;

  NullValue: LongBool;

  Status: SQLResult;

  Value: Pointer;

begin

  Status := Cursor.getColumnCount(nCols);

  if Status = SQL_SUCCESS then

    for FldNo := 1 to nCols do

    begin

      Value := nil;

      Status = Cursor.getColumnType(FldNo, Type, SubType);

      if Status = SQL_SUCCESS then

      begin

        case Type of

          fldBCD:

            begin

              Value = AllocMem(SizeOf(TBcd));

              if Assigned(Value) then

                Status := Cursor.getBcd(FldNo, Value, NullValue);

              if Status <> SQL_SUCCESS then

                NullValue := True; { treat failure like blank field }

            end;

          {fetch the values for other field types in other cases }

        end;

        if Assigned(Value) then

        begin

          { do something with the field value }

          FreeMem(Value);

        end;

      end;

    end; { for loop }

end;


getTimeStamp (SQLCursor)

C++ example	Object Pascal example	See also

C++ syntax:

virtual SQLResult GCCSTDC getTimeStamp (UINT16 uColumnNumber, pSQLLTIMESTAMP pData, pBOOL pbIsNull) = 0;

Object Pascal syntax:

function getTimeStamp(uColumnNumber: Word; pData: Pointer; var pbIsNull: LongBool) : SQLResult; stdcall;

Description

getTimeStamp retrieves the value of a date-and-time field. Use the getColumnType method to check that the field is of type fldDATETIME before calling getTimeStamp. getTimeStamp returns SQL_SUCCESS if it successfully retrieves a field value, an error code otherwise.

Parameters

uColumnNumber identifies the column (field) whose value you want to fetch. The first column is specified by 1, the second by 2 and so on. Use the getColumnCount method to obtain an upper bound on the possible values.

pData is a buffer to receive the date/time value. It should point to a CTIMESTAMP structure in C++ or a TSQLTimeStamp record in Object Pascal.

pbIsNull indicates whether the field value is blank (NULL).


getTimeStamp example

short int nCols;

Status = pCursor->getColumnCount(&nCols);

if (Status == SQL_SUCCESS)

{

  for (int i = 1; i <= nCols; i++)

  {

    short int Type, SubType;

    Status = pCursor->getColumnType(i, &Type, &SubType);

    if (Status == SQL_SUCCESS)

    {

      BOOL bIsNull;

      switch (Type)

      {

        case fldDATETIME:

          CTIMESTAMP DateAndTime;

          Status = pCursor->getTimeStamp(i, &DateAndTime, &bIsNull);

          if (Status == SQL_SUCCESS && !bIsNull)

          {

             // do something with the field value;

          }

          break;

        // fetch values for other field types in other cases

      }

    }

  }

}


getTimeStamp example

var

  nCols, Type, SubType, FldNo: Word;

  NullValue: LongBool;

  Status: SQLResult;

  Value: Pointer;

begin

  Status := Cursor.getColumnCount(nCols);

  if Status = SQL_SUCCESS then

    for FldNo := 1 to nCols do

    begin

      Value := nil;

      Status = Cursor.getColumnType(FldNo, Type, SubType);

      if Status = SQL_SUCCESS then

      begin

        case Type of

          fldDATETIME:

            begin

              Value = AllocMem(SizeOf(TSQLTimeStamp));

              if Assigned(Value) then

                Status := Cursor.getTimeStamp(FldNo, Value, NullValue);

              if Status <> SQL_SUCCESS then

                NullValue := True; { treat failure like blank field }

            end;

          {fetch the values for other field types in other cases }

        end;

        if Assigned(Value) then

        begin

          { do something with the field value }

          FreeMem(Value);

        end;

      end;

    end; { for loop }

end;


getTime (SQLCursor)

C++ example	Object Pascal example	See also

C++ syntax:

virtual SQLResult GCCSTDC getTime (UINT16 uColumnNumber, pINT32 pData, pBOOL pbIsNull) = 0;

Object Pascal syntax:

function getTime(uColumnNumber: Word; pData: Pointer; var pbIsNull: LongBool) : SQLResult; stdcall;

Description

getTime retrieves the value of a time field. Use the getColumnType method to check that the field is of type fldTIME before calling getTime. getTime returns SQL_SUCCESS if it successfully retrieves a field value, an error code otherwise.

Parameters

uColumnNumber identifies the column (field) whose value you want to fetch. The first column is specified by 1, the second by 2 and so on. Use the getColumnCount method to obtain an upper bound on the possible values.

pData is a buffer to receive the time. It should point to a 32-bit integer in C++ or a TDateTime value in Object Pascal. This type represents time values as a fraction of a 24-hour day.

pbIsNull indicates whether the field value is blank (NULL).


getTime example

short int nCols;

Status = pCursor->getColumnCount(&nCols);

if (Status == SQL_SUCCESS)

{

  for (int i = 1; i <= nCols; i++)

  {

    short int Type, SubType;

    Status = pCursor->getColumnType(i, &Type, &SubType);

    if (Status == SQL_SUCCESS)

    {

      BOOL bIsNull;

      switch (Type)

      {

        case fldTIME:

          long Value;

          Status = pCursor->getTime(i, &Value, &bIsNull);

          if (Status == SQL_SUCCESS && !bIsNull)

          {

             // do something with the field value;

          }

          break;

        // fetch values for other field types in other cases

      }

    }

  }

}


getTime example

var

  nCols, Type, SubType, FldNo: Word;

  NullValue: LongBool;

  Status: SQLResult;

  Value: Pointer;

begin

  Status := Cursor.getColumnCount(nCols);

  if Status = SQL_SUCCESS then

    for FldNo := 1 to nCols do

    begin

      Value := nil;

      Status = Cursor.getColumnType(FldNo, Type, SubType);

      if Status = SQL_SUCCESS then

      begin

        case Type of

          fldDATETIME:

            begin

              Value = AllocMem(SizeOf(TDateTime));

              if Assigned(Value) then

                Status := Cursor.getTime(FldNo, Value, NullValue);

              if Status <> SQL_SUCCESS then

                NullValue := True; { treat failure like blank field }

            end;

          {fetch the values for other field types in other cases }

        end;

        if Assigned(Value) then

        begin

          { do something with the field value }

          FreeMem(Value);

        end;

      end;

    end; { for loop }

end;


getDate (SQLCursor)

C++ example	Object Pascal example	See also

C++ syntax:

virtual SQLResult GCCSTDC getDate (UINT16 uColumnNumber, pINT32 pData, pBOOL pbIsNull) = 0;

Object Pascal syntax:

function getDate(uColumnNumber: Word; pData: Pointer; var pbIsNull: LongBool) : SQLResult; stdcall;

Description

getDate retrieves the value of a date field. Use the getColumnType method to check that the field is of type fldDATE before calling getDate. getDate returns SQL_SUCCESS if it successfully retrieves a field value, an error code otherwise.

Parameters

uColumnNumber identifies the column (field) whose value you want to fetch. The first column is specified by 1, the second by 2 and so on. Use the getColumnCount method to obtain an upper bound on the possible values.

pData is a buffer to receive the date. It should point to a 32-bit integer in C++ or a TDateTime value in Object Pascal. This type represents dates as the number of days that have passed since 12/30/1899.

pbIsNull indicates whether the field value is blank (NULL).


getDate example

short int nCols;

Status = pCursor->getColumnCount(&nCols);

if (Status == SQL_SUCCESS)

{

  for (int i = 1; i <= nCols; i++)

  {

    short int Type, SubType;

    Status = pCursor->getColumnType(i, &Type, &SubType);

    if (Status == SQL_SUCCESS)

    {

      BOOL bIsNull;

      switch (Type)

      {

        case fldTIME:

          long Value;

          Status = pCursor->getDate(i, &Value, &bIsNull);

          if (Status == SQL_SUCCESS && !bIsNull)

          {

             // do something with the field value;

          }

          break;

        // fetch values for other field types in other cases

      }

    }

  }

}


getDate example

var

  nCols, Type, SubType, FldNo: Word;

  NullValue: LongBool;

  Status: SQLResult;

  Value: Pointer;

begin

  Status := Cursor.getColumnCount(nCols);

  if Status = SQL_SUCCESS then

    for FldNo := 1 to nCols do

    begin

      Value := nil;

      Status = Cursor.getColumnType(FldNo, Type, SubType);

      if Status = SQL_SUCCESS then

      begin

        case Type of

          fldDATETIME:

            begin

              Value = AllocMem(SizeOf(TDateTime));

              if Assigned(Value) then

                Status := Cursor.getDate(FldNo, Value, NullValue);

              if Status <> SQL_SUCCESS then

                NullValue := True; { treat failure like blank field }

            end;

          {fetch the values for other field types in other cases }

        end;

        if Assigned(Value) then

        begin

          { do something with the field value }

          FreeMem(Value);

        end;

      end;

    end; { for loop }

end;


getBytes (SQLCursor)

C++ example	Object Pascal example	See also

C++ syntax:

virtual SQLResult GCCSTDC getBytes (UINT16 uColumnNumber, pBYTE pData, pBOOL pbIsNull) = 0;

Object Pascal syntax:

function getBytes(uColumnNumber: Word; pData: Pointer; var pbIsNull: LongBool) : SQLResult; stdcall;

Description

getBytes retrieves the value of a field that contains untyped binary data. Use the getColumnType method to check that the field is of type fldBYTES or fldVARBYTES before calling getBytes. getBytes returns SQL_SUCCESS if it successfully retrieves a field value, an error code otherwise.

Parameters

uColumnNumber identifies the column (field) whose value you want to fetch. The first column is specified by 1, the second by 2 and so on. Use the getColumnCount method to obtain an upper bound on the possible values.

pData is a buffer to receive the field value. Use the getColumnLength method to determine the size this buffer needs to be.

pbIsNull indicates whether the field value is blank (NULL).


getBytes example

short int nCols;

Status = pCursor->getColumnCount(&nCols);

if (Status == SQL_SUCCESS)

{

  for (int i = 1; i <= nCols; i++)

  {

    short int Type, SubType;

    Status = pCursor->getColumnType(i, &Type, &SubType);

    if (Status == SQL_SUCCESS)

    {

      UINT32 Size;

      BOOL bIsNull;

      switch (Type)

      {

        case fldBYTES:

        case fldVARBYTES:

          Status = pCursor->getColumnLength(i, &Size);

          if (Status == SQL_SUCCESS)

          {

            pBYTE Buffer = (char *)malloc(Size);

            if (Buffer)

            {

              Status = pCursor->getBytes(i, Buffer, &bIsNull);

              if (Status == SQL_SUCCESS && !bIsNull)

              {

                // do something with the field value;

              }

              free(Buffer);

            }

          }

          break;

        // fetch values for other field types in other cases

      }

    }

  }

}


getBytes example

var

  nCols, Type, SubType, FldNo, Size: Word;

  NullValue: LongBool;

  Status: SQLResult;

  Value: Pointer;

begin

  Status := Cursor.getColumnCount(nCols);

  if Status = SQL_SUCCESS then

    for FldNo := 1 to nCols do

    begin

      Value := nil;

      Status = Cursor.getColumnType(FldNo, Type, SubType);

      if Status = SQL_SUCCESS then

      begin

        case Type of

          fldBYTES, fldVARBYTES:

            begin

              Status := Cursor.getColumnLength(FldNo, Size);

              if Status = SQL_SUCCESS then

                Value = AllocMem(Size);

              if Assigned(Value) then

                Status := Cursor.getBytes(FldNo, Value, NullValue);

              if Status <> SQL_SUCCESS then

                NullValue := True; { treat failure like blank field }

            end;

          {fetch the values for other field types in other cases }

        end;

        if Assigned(Value) then

        begin

          { do something with the field value }

          FreeMem(Value);

        end;

      end;

    end; { for loop }

end;


getBlobSize (SQLCursor)

C++ example	Object Pascal example	See also

C++ syntax:

virtual SQLResult GCCSTDC getBlobSize (UINT16 uColumnNumber, pUINT32 pulLength, pBOOL bIsNull) = 0;

Object Pascal syntax:

function getBlobSize(uColumnNumber: Word; var pulLength: LongWord; var bIsNull: LongBool) : SQLResult; stdcall;

Description

getBlobSize retrieves the number of bytes need to hold the current value of a BLOB field. Use this method to determine the size needed for a buffer before calling the getBlob method. Before calling getBlobSize, check the isBlobSizeExact method to determine whether getBlobSize can accurately return the size of BLOB field value. getBlobSize returns SQL_SUCCESS if it returns a size for the BLOB field. It returns an error code otherwise.

Parameters

uColumnNumber identifies the column (field) that contains the BLOB data. This should represent a field of type fldBLOB (any subtype). The first column is specified by 1, the second by 2 and so on. Use the getColumnCount method to obtain an upper bound on the possible values.

pulLength returns the number of bytes needed to hold the BLOB field’s value (if it is not blank).

bIsNull returns true if the BLOB field is blank, false if it contains data.


getBlobSize example

short int Type, SubType;

SQLResult Status = pCursor->getColumnType(1, &Type, &SubType);

if (Status == SQL_SUCCESS && Type == fldBLOB)

{

  BOOL bBlobIsNull = False;

  unsignedint BlobSize;

  BOOL bCanUseSize;

  Status = pCursor->isBlobSizeExact(1, &bCanUseSize);

  if (Status == SQL_SUCCESS && bCanUseSize)

    pCursor->getBlobSize(1, &BlobSize, &bBlobIsNull);

  else

  {

    short int Len = 1;

    pConnection->getOption(eDrvBlobSize, &BlobSize, sizeof(int), &Len);

  }

  pVOID Buffer;

  if (!bBlobIsNull)

  {

    Buffer = malloc(BlobSize);

    if (Buffer)

      Status = pCursor->getBlob(1, Buffer, &bBlobIsNull, BlobSize);

  }

  if (Status == SQL_SUCCESS && !bBlobIsNull)

  {

    // do something with the BLOB value in the buffer

  }

  if (Buffer)

    free(Buffer)

}


getBlobSize example

var

  Type, NotUsed: Word;

  Status: SQLResult;

  BlobIsNull, CanUseSize: LongBool;

  BlobSize: Word;

  Buffer: Pointer;

begin

  Status := Cursor.getColumnType(1, Type, NotUsed);

  if (Status = SQL_SUCCESS) and (type = fldBLOB) then

  begin

    BlobIsNull = False;

    Status = Cursor.isBlobSizeExact(1, CanUseSize);

    if (Status = SQL_SUCCESS) and CanUseSize then

      Cursor.getBlobSize(1, BlobSize, BlobIsNull)

    else

      Connection.getOption(eDrvBlobSize, Addr(BlobSize), SizeOf(Integer), NotUsed);

    if not BlobIsNull then

    begin

      Buffer := AllocMem(BlobSize);

      if Assigned(Buffer) then

        Status := Cursor.getBlob(1, Buffer, BlobIsNull, BlobSize);

    end;

    if (Status = SQL_SUCCESS) and (not BlobIsNull) then

      { do something with the BLOB value in the buffer};

    if Assigned(Buffer) then

      FreeMem(Buffer);

  end;

end;


getBlob (SQLCursor)

C++ example	Object Pascal example	See also

C++ syntax:

virtual SQLResult GCCSTDC getBlob (UINT16 uColumnNumber, pVOID pData, pBOOL pbIsNull, UINT32 ulLength) = 0;

Object Pascal syntax:

function getBlob(uColumnNumber: Word; pData: Pointer; var pbIsNull: LongBool; ulLength: LongWord) : SQLResult; stdcall;

Description

getBlob retrieves the value of a binary large object (BLOB) field. Use the getColumnType method to check that the field is of type fldBLOB before calling getBlob. getBlob returns SQL_SUCCESS if it successfully retrieves a value, an error code otherwise.

Parameters

uColumnNumber identifies the column (field) whose value you want to fetch. The first column is specified by 1, the second by 2 and so on. Use the getColumnCount method to obtain an upper bound on the possible values.

pData is a buffer to receive the BLOB value.

pbIsNull indicates whether the field value is blank (NULL).

ulLength indicates the size of the buffer to which pData points.


getBlob example

short int Type, SubType;

SQLResult Status = pCursor->getColumnType(1, &Type, &SubType);

if (Status == SQL_SUCCESS && Type == fldBLOB)

{

  BOOL bBlobIsNull = False;

  unsignedint BlobSize;

  BOOL bCanUseSize;

  Status = pCursor->isBlobSizeExact(1, &bCanUseSize);

  if (Status == SQL_SUCCESS && bCanUseSize)

    pCursor->getBlobSize(1, &BlobSize, &bBlobIsNull);

  else

  {

    short int Len = 1;

    pConnection->getOption(eDrvBlobSize, &BlobSize, sizeof(int), &Len);

  }

  pVOID Buffer;

  if (!bBlobIsNull)

  {

    Buffer = malloc(BlobSize);

    if (Buffer)

      Status = pCursor->getBlob(1, Buffer, &bBlobIsNull, BlobSize);

  }

  if (Status == SQL_SUCCESS && !bBlobIsNull)

  {

    // do something with the BLOB value in the buffer

  }

  if (Buffer)

    free(Buffer)

}


getBlob example

var

  Type, NotUsed: Word;

  Status: SQLResult;

  BlobIsNull, CanUseSize: LongBool;

  BlobSize: Word;

  Buffer: Pointer;

begin

  Status := Cursor.getColumnType(1, Type, NotUsed);

  if (Status = SQL_SUCCESS) and (type = fldBLOB) then

  begin

    BlobIsNull = False;

    Status = Cursor.isBlobSizeExact(1, CanUseSize);

    if (Status = SQL_SUCCESS) and CanUseSize then

      Cursor.getBlobSize(1, BlobSize, BlobIsNull)

    else

      Connection.getOption(eDrvBlobSize, Addr(BlobSize), SizeOf(Integer), NotUsed);

    if not BlobIsNull then

    begin

      Buffer := AllocMem(BlobSize);

      if Assigned(Buffer) then

        Status := Cursor.getBlob(1, Buffer, BlobIsNull, BlobSize);

    end;

    if (Status = SQL_SUCCESS) and (not BlobIsNull) then

      { do something with the BLOB value in the buffer};

    if Assigned(Buffer) then

      FreeMem(Buffer);

  end;

end;


SQLMetaData

C++ syntax	Object Pascal syntax	See also

The SQLMetaData interface retrieves the various database metadata that can be obtained on an opened database connection.  SQLMetaData provides only the metadata needed by Delphi and C++ Builder data-access components. Although database servers define other types of metadata, these are not supported in the interest of simplicity. Driver writers can surface such additional metadata by expanding the options available to the getOption and setOption methods.

Before using SQLMetaData to fetch metadata, you should use the setOption to specify the Catalog (if appropriate) and schema (user) for which you want metadata.

Methods

setOption

getOption

getObjectList

getTables

getProcedures

getColumns

getProcedureParams

getIndices

getErrorMessage

getErrorMessageLen


SQLMetaData: C++ syntax

abstract COMINTF SQLMetaData

{

   virtual INT32 GCCSTDC  QueryInterface( GUID riid, ppVOID ppv ) = 0;

   virtual UINT32 GCCSTDC AddRef( ) = 0;

   //Destructs the SQLMetaData object

   virtual UINT32 GCCSTDC Release( ) = 0;

   //Set/Get options for database metadata properties

   virtual SQLResult GCCSTDC  setOption (

      eSQLMetaDataOption  eMOption,

      INT32               lValue ) = 0;

   virtual SQLResult GCCSTDC  getOption (

      eSQLMetaDataOption  eDOption,

      pINT32              plValue,

      INT16               iMaxLength,

      pINT16              piLength ) = 0;

   //Get Object list

   virtual SQLResult GCCSTDC  getObjectList (

      eSQLObjectType eObjType,

      ppSQLCursor    ppCur) = 0;

   //Get Table list

   virtual SQLResult  GCCSTDC  getTables (

      pCHAR pszTableName,

      UINT32 uTableType,

      ppSQLCursor ppCur) = 0;

   //Get Procedure list

   virtual SQLResult GCCSTDC  getProcedures (

      pCHAR pszProcName,

      UINT32 uProcType,

      ppSQLCursor ppCur) = 0;

   //Get Column metadata for a given table

   virtual SQLResult  GCCSTDC  getColumns (

      pCHAR pszTableName,

      pCHAR pszColumnName,

      UINT32 uColType,

      ppSQLCursor ppCur) = 0;

   //Get Parameter metadata for a given Stored Procedure

   virtual SQLResult  GCCSTDC getProcedureParams (

      pCHAR pszProcName,

      pCHAR pszParamName,

      ppSQLCursor ppCur) = 0;

   //Get Index info associated with a given table

   virtual SQLResult GCCSTDC  getIndices (

      pCHAR pszTableName,

      UINT32 uIndexType,

      ppSQLCursor ppCur) = 0;

   //Error handling

   virtual SQLResult GCCSTDC getErrorMessage (

      pBYTE pszError );

   virtual SQLResult GCCSTDC getErrorMessageLen (

      pUINT16 puErrorLen );

};


ISQLMetaData: Object Pascal syntax

ISQLMetaData = interface

   function setOption(eDOption : TSQLMetaDataOption;

                      PropValue : LongInt): SQLResult; stdcall;

   function getOption(eDOption : TSQLMetaDataOption;

                      PropValue : Pointer; MaxLength: SmallInt;

                      out Length: SmallInt): SQLResult; stdcall;

   function getObjectList(eObjType: TSQLObjectType;

                      out Cursor: ISQLCursor): SQLResult; stdcall;

   function getTables(TableName: PChar; TableType: LongWord;

                      out Cursor : ISQLCursor): SQLResult; stdcall;

   function getProcedures(ProcedureName: PChar; ProcType: LongWord;

                      out Cursor: ISQLCursor): SQLResult; stdcall;

   function getColumns(TableName: PChar; ColumnName: PChar;

                      ColType: LongWord;

                      out Cursor: ISQLCursor): SQLResult; stdcall;

   function getProcedureParams(ProcName: PChar; ParamName: PChar;

                      out Cursor: ISQLCursor): SQLResult; stdcall;

   function getIndices(TableName: PChar; IndexType: LongWord;

                      out Cursor: ISQLCursor): SQLResult; stdcall;

   function getErrorMessage(Error : PChar) : SQLResult; overload; stdcall;

   function getErrorMessageLen(out ErrorLen: SmallInt): SQLResult; stdcall;

end;


setOption (SQLMetaData)

C++ example	Object Pascal example	See also

C++ syntax:

virtual SQLResult GCCSTDC setOption (eSQLMetaDataOption eDOption, INT32 lValue) = 0;

Object Pascal syntax:

function setOption(eDOption : TSQLMetaDataOption; lValue: LongInt) : SQLResult; stdcall;

Description

setOption sets the value of a specified metadata property. It returns SQL_SUCCESS if the property value is successfully set, otherwise an error code.

Most metadata properties are read-only. They return metadata information and you can’t set them using the setOption method. However, you can set options that limit the metadata returned by other methods to a specific catalog (eMetaCatalogName) or user (eMetaSchemaName).

Parameters

eDOption: the name of the metadata property whose value is to be set. eDOption should be eMetaCatalogName (to limit metadata returned by other methods to a specific catalog), or eMetaSchemaName (to limit metadata returned by other methods to a specific schema, or user).

lValue: the value to set. Note that this value is a pointer to a string, and must be cast to a 32-bit integer.


setOption example

char *pName = "Administrator";

Status = pCommand->setOption(eMetaSchemaName, (INT32) pName);


setOption example

var

  Name: string;

  Status: SQLResult;

begin

  Name := 'Administrator';

  Status := Connection.setOption(eMetaSchemaName, LongInt(PChar(Name)));


getOption (SQLMetaData)

C++ example	Object Pascal example	See also

C++ syntax:

virtual SQLResult GCCSTDC getOption (eSQLMetaDataOption eDOption, pINT32 plValue, INT16 iMaxLength, pINT16 piLength) = 0;

Object Pascal syntax:

function getOption(eDOption : TSQLMetaDataOption; plValue: Pointer; iMaxLength: SmallInt; out Length SmallInt) : SQLResult; stdcall;

Description

getOption retrieves the value of a specified metadata property.  It returns SQL_SUCCESS if the property value is successfully fetched, otherwise an error code.

Parameters

eDOption: the name of the metadata property whose value is to be retrieved.

plValue: a pointer to a variable that receives the property value.

iMaxLength: The maximum number of bytes that can be returned by plValue. That is, the size of the variable to which plValue points.

piLength (Length): Returns the number of bytes written to plValue.


getOption example

int NameBufferSize;

short int Len;

SQLResult Status;

Status = pCommand->getOption(eMetaMaxObjectNameLength, &NameBufferSize, sizeof(int), &Len);


getOption example

var

  NameBufferSize: Integer;

  Len: SmallInt;

  Status: SQLResult;

begin

  Status := Connection.getOption(eMetaMaxObjectNameLength, Addr(NameBufferSize), SizeOf(Integer), Len);


getObjectList (SQLMetaData)

C++ example	Object Pascal example

C++ syntax:

virtualSQLResult GCCSTDC getObjectList(eSQLObjectType eObjType, ppSQLCursor ppCur) = 0;

Object Pascal syntax:

function getObjectList(eObjType: TSQLObjectType; out Cursor: ISQLCursor): SQLResult; stdcall;

Description

getObjectList returns a cursor for a dataset where each row describes an object of a specified type that is available on the database. The dataset lists all available objects of the specified type.

Columns in the returned cursor are

Column	Type	Meaning
1.RECNO	fldINT32	A record number that uniquely identifies each record.
2.CATALOG_NAME	fldZSTRING	The name of the catalog (database) that contains the object.
3.SCHEMA_NAME	fldZSTRING	The name of the schema that identifies the owner of the object.
4.OBJECT_NAME	fldZSTRING	The name of the object.
Cursor columns are ordered by the object name (OBJECT_NAME).

Parameters

eObjType specifies the type of object to include in the list.

ppCur (Cursor) returns an SQLCursor interface pointer that can be used to retrieve the information in the resulting dataset.


getObjectList example

pSQLCursor ObjectCursor;

Status = pMetaData->getObjectList(eObjTypeDataType, &ObjectCursor);


getObjectList example

var

  ObjectCursor: ISQLCursor;

  Status: SQLResult;

begin

  Status := MetaData.getObjectList(eObjTypeDataType, ObjectCursor);


getTables (SQLMetaData)

C++ example	Object Pascal example

C++ syntax:

virtualSQLResult GCCSTDC getTables(pCHAR pszTableName, UINT32 uTableType, ppSQLCursor ppCur) = 0;

Object Pascal syntax:

function getTables(pszTableName: PChar; uTableType: LongWord; out Cursor: ISQLCursor): SQLResult; stdcall;

Description

getTables returns a cursor for a dataset where each row describes a table or equivalent that is available on the database. The dataset lists all available tables of a specified set of types.

Columns in the returned cursor are

Column	Type	Meaning
1.RECNO	fldINT32	A record number that uniquely identifies each record.
2.CATALOG_NAME	fldZSTRING	The name of the catalog (database) that contains the table.
3.SCHEMA_NAME	fldZSTRING	The name of the schema that identifies the owner of the table.
4.TABLE_NAME	fldZSTRING	The name of the table.
5.TABLE_TYPE	fldINT32	An eSQLTableType value (C++) or table type constant (Object Pascal) that indicates the type of table.
Cursor columns are ordered by the table name (TABLE_NAME).

Parameters

pszTableName is a search pattern that all returned tables must match. To obtain a list of all tables, pass NULL (nil) for this parameter.

uTableType indicates the types of tables (view, synonyms, etc) that should be returned. This value is created by combining one or more eSQLTableType values (C++) or table type constants (Object Pascal).

ppCur (Cursor) returns an SQLCursor interface pointer that can be used to retrieve the information in the resulting dataset.


getTables example

pSQLCursor TableListCursor;

Status = pMetaData->getTables(NULL, eSQLTable | eSQLView | eSQLSynonym, &TableListCursor);


getTables example

var

  TableListCursor: ISQLCursor;

  Status: SQLResult;

begin

  Status := MetaData.getTables(nil, eSQLTable or eSQLView or eSQLSynonym, TableListCursor);


getProcedures (SQLMetaData)

C++ example	Object Pascal example

C++ syntax:

virtualSQLResult GCCSTDC getProcedures(pCHAR pszProcName, UINT32 uProcType, ppSQLCursor ppCur) = 0;

Object Pascal syntax:

function getProcedures(pszProcName: PChar; uProcType: LongWord; out Cursor: ISQLCursor): SQLResult; stdcall;

Description

getProcedures returns a cursor for a dataset where each row describes a stored procedure that is available on the database. The dataset lists all available stored procedures of a specified set of types.

Columns in the returned cursor are

Column	Type	Meaning
1.RECNO	fldINT32	A record number that uniquely identifies each record.
2.CATALOG_NAME	fldZSTRING	The name of the catalog (database) that contains the stored procedure.
3.SCHEMA_NAME	fldZSTRING	The name of the schema that identifies the owner of the stored procedure.
4.PROC_NAME	fldZSTRING	The name of the stored procedure.
5.PROC_TYPE	fldINT32	An eSQLProcType value (C++) or stored procedure type constant (Object Pascal) that indicates the type of stored procedure.
6.IN_PARAMS	fldINT16	The number of input parameters.
7.OUT_PARAMS	fldINT16	The number of output parameters.
Cursor columns are ordered by the procedure name (PROC_NAME).

Parameters

pszProcName is a search pattern that all returned stored procedures must match. To obtain a list of all stored procedures, pass NULL (nil) for this parameter.

uProcType indicates the types of procedures (functions, packages, etc) that should be returned. This value is created by combining one or more eSQLProcType values (C++) or stored procedure type constants (Object Pascal).

ppCur (Cursor) returns an SQLCursor interface pointer that can be used to retrieve the information in the resulting dataset.


getProcedures example

pSQLCursor ProcListCursor;

Status = pMetaData->getProcedures(NULL, eSQLProcedure | eSQLFunction, &ProcListCursor);


getProcedures example

var

  ProcListCursor: ISQLCursor;

  Status: SQLResult;

begin

  Status := MetaData.getProcedures(nil, eSQLProcedure or eSQLFunction, ProcListCursor);


getColumns (SQLMetaData)

C++ example	Object Pascal example

C++ syntax:

virtualSQLResult GCCSTDC getColumns(pCHAR pszTableName, pCHAR pszColumnName, UINT32 uColType, ppSQLCursor ppCur) = 0;

Object Pascal syntax:

function getColumns(pszTableName: PChar; pszColumnName: PChar; uColType: LongWord; out Cursor: ISQLCursor): SQLResult; stdcall;

Description

getColumns returns a cursor for a dataset where each row describes a column (field) from a specified table. The dataset lists all columns that match a specified set of criteria.

Columns in the returned cursor are

Column	Type	Meaning
1.RECNO	fldINT32	A record number that uniquely identifies each record.
2.CATALOG_NAME	fldZSTRING	The name of the catalog (database) that contains the table.
3.SCHEMA_NAME	fldZSTRING	The name of the schema that identifies the owner of the table.
4.TABLE_NAME	fldZSTRING	The name of the table in which the column appears.
5. COLUMN_NAME	fldZSTRING	The name of the field (column).
6.COLUMN_POSITION	fldINT16	The position of the column in its table.
7.COLUMN_TYPE	fldINT32	An eSQLColType value (C++) or column type constant (Object Pascal) that indicates the type of field.
8.COLUMN_DATATYPE	fldINT16	The logical data type for the field.
9. COLUMN_TYPENAME	fldZSTRINGG	A string describing the datatype. This is the same information as contained in COLUMN_DATATYPE and COLUMN_SUBTYPE, but in a form used in some DDL statements.
10. COLUMN_SUBTYPE	fldINT16	The logical data subtype for the field.
11. COLUMN_PRECISION	fldINT32	The size of the field type (number of characters in a string, bytes in a bytes field, significant digits in a BCD value, members of an ADT field, and so on)
12. COLUMN_SCALE	fldINT16	The number of digits to the right of the decimal on BCD values, or descendants on ADT and array fields.
13. COLUMN_LENGTH	fldINT32	The number of bytes required to store field values.
14. COLUMN_NULLABLE	fldINT16	0 if the field requires a value, nonzero if it can be blank.
Cursor columns are ordered by the column name (COLUMN_NAME).

Parameters

pszTableName is the name of the table whose columns you want listed. Typically, this is a literal string, although you can use a search pattern.

pszColumnName is a search pattern that all returned columns (field names) must match. To obtain a list of all columns in the table, pass NULL (nil) for this parameter.

uColType indicates the types of any special columns that should be returned. This value is created by combining one or more eSQLColType values (C++) or column type constants (Object Pascal). To obtain a list of all columns, pass 0.

ppCur (Cursor) returns an SQLCursor interface pointer that can be used to retrieve the information in the resulting dataset.


getColumns example

pSQLCursor ColListCursor;

Status = pMetaData->getColumns("Inventory", NULL, 0, &ColListCursor);


getColumns example

var

  Table: string;

  ColListCursor: ISQLCursor;

  Status: SQLResult;

begin

  Table := 'Inventory';

  Status := MetaData.getColumns(PChar(Table), nil, 0, ColListCursor);


getProcedureParams (SQLMetaData)

C++ example	Object Pascal example

C++ syntax:

virtualSQLResult GCCSTDC getProcedureParams(pCHAR pszProcName, pCHAR pszParamName, ppSQLCursor ppCur) = 0;

Object Pascal syntax:

function getProcedureParams(pszProcName: PChar; pszParamName: PChar; out Cursor: ISQLCursor): SQLResult; stdcall;

Description

getProcedureParams returns a cursor for a dataset where each row describes a parameter for a specified stored procedure. The dataset lists all parameters that match a specified search pattern.

Columns in the returned cursor are

Column	Type	Meaning
1.RECNO	fldINT32	A record number that uniquely identifies each record.
2.CATALOG_NAME	fldZSTRING	The name of the catalog (database) that contains the stored procedure.
3.SCHEMA_NAME	fldZSTRING	The name of the schema that identifies the owner of the stored procedure.
4.PROC_NAME	fldZSTRING	The name of the procedure in which the parameter appears.
5. PARAM_NAME	fldZSTRING	The name of the parameter.
6.PARAM_TYPE	fldINT16	A STMTParamType value that indicates whether the parameter is used for input, output, or result.
7.PARAM_DATATYPE	fldINT16	The logical data type for the parameter.
8.PARAM_SUBTYPE	fldINT16	The logical data subtype for the parameter.
9. PARAM_TYPENAME	fldZSTRING	A string describing the datatype. This is the same information as contained in PARAM_DATATYPE and PARAM_SUBTYPE, but in a form used in some DDL statements.
10. PARAM_PRECISION	fldINT32	The size of the parameter type (number of characters in a string, bytes in a bytes field, significant digits in a BCD value, members of an ADT, and so on)
11. PARAM_SCALE	fldINT16	The number of digits to the right of the decimal on BCD values, or descendants on ADT and array values.
12. PARAM_LENGTH	fldINT32	The number of bytes required to store parameter values.
13. PARAM_NULLABLE	fldINT16	0 if the parameter requires a value, nonzero if it can be blank.
Cursor columns are ordered by the parameter name (PARAM_NAME).

Parameters

pszProcName is the name of the stored procedures whose parameters you want listed. Typically, this is a literal string, although you can use a search pattern.

pszParamName is a search pattern that all returned parameters must match. To obtain a list of all parameters for the stored procedure, pass NULL (nil) for this parameter.

ppCur (Cursor) returns an SQLCursor interface pointer that can be used to retrieve the information in the resulting dataset.


getProcedureParams example

pSQLCursor ParamListCursor;

Status = pMetaData->getProcedureParams("TransferFunds", NULL, &ParamListCursor);


getProcedureParams example

var

  Procedure: string;

  ParamListCursor: ISQLCursor;

  Status: SQLResult;

begin

  Procedure := 'TransferFunds';

  Status := MetaData.getProcedureParams(PChar(Procedure), nil, ParamListCursor);


getIndices (SQLMetaData)

C++ example	Object Pascal example

C++ syntax:

virtualSQLResult GCCSTDC getIndices(pCHAR pszTableName, UINT32 uIndexType, ppSQLCursor ppCur) = 0;

Object Pascal syntax:

function getIndices(pszTableName: PChar; uIndexType: LongWord; out Cursor: ISQLCursor): SQLResult; stdcall;

Description

getIndices returns a cursor for a dataset where each row describes a field in an index for a specified table. The dataset lists all indexes that match specified criteria.

Columns in the returned cursor are

Column	Type	Meaning
1.RECNO	fldINT32	A record number that uniquely identifies each record.
2.CATALOG_NAME	fldZSTRING	The name of the catalog (database) that contains the index.
3.SCHEMA_NAME	fldZSTRING	The name of the schema that identifies the owner of the index.
4.TABLE_NAME	fldZSTRING	The name of the table for which the index is defined.
5.INDEX_NAME	fldZSTRING	The name of the index.
6.PKEY_NAME	fldZSTRING	The name of the primary key.
7.COLUMN_NAME	fldZSTRING	The name of the column (field) in the index.
8.COLUMN_POSITION	fldINT16	The position of this field in the index.
9.INDEX_TYPE	fldINT16	An eSQLIndexType value (C++) or index type constant (Object Pascal) that indicates any special properties of the index.
10.SORT_ORDER	fldZSTRING	Indicates whether the index sorts on this field in ascending (a) or descending (d) order.
11.FILTER	fldZSTRING	A string that gives a filter condition limiting indexed records.
Cursor columns are ordered by the index name (INDEX_NAME).

Parameters

pszTableName is the name of the table whose indexes you want listed. Typically, this is a literal string, although you can use a search pattern.

uIndexType indicates the types of indexes that should be returned. This value is created by combining one or more eSQLIndexType values (C++) or index type constants (Object Pascal). To obtain a list of all indexes, pass 0.

ppCur (Cursor) returns an SQLCursor interface pointer that can be used to retrieve the information in the resulting dataset.


getIndices example

pSQLCursor IndexListCursor;

Status = pMetaData->getIndices("Inventory", 0, &IndexListCursor);


getIndices example

var

  Table: string;

  IndexListCursor: ISQLCursor;

  Status: SQLResult;

begin

  Table := 'Inventory';

  Status := MetaData.getIndices(PChar(Table), 0, IndexListCursor);


getErrorMessage (SQLMetaData)

C++ example	Object Pascal example	See also

C++ syntax:

virtual SQLResult GCCSTDC getErrorMessage (pBYTE pszError) = 0;

Object Pascal syntax:

function getErrorMessage(Error: PChar) : SQLResult; overload; stdcall;

Description

getErrorMessage retrieves an error string for the last command that was sent to the server. Thus, if the last method that accessed the server returned an error code, calling getErrorMessage returns an error message for that error code. Note that once an application calls getErrorMessage, the error message is cleared and subsequent calls will not return the error message.

getErrorMessage returns SQL_SUCCESS if the error message is successfully returned. Otherwise, it returns an error code.

Parameters

pszError (Error) is a buffer that receives the null-terminated error string. Use the getErrorMessageLen method to determine the size required for this buffer.


getErrorMessageLen (SQLMetaData)

C++ example	Object Pascal example	See also

C++ syntax:

virtual SQLResult GCCSTDC getErrorMessageLen (pUINT16 puErrorLen) = 0;

Object Pascal syntax:

function getErrorMessageLen(out ErrorLen: SmallInt) : SQLResult; stdcall;

Description

getErrorMessageLen indicates the number of characters (bytes) in an error string for the last command that was sent to the server. Use this method before allocating a buffer to hold the error message that the getErrorMessage method returns. The buffer needs to be puErrorLen + 1 bytes (an additional byte for the null terminating character).

Parameters

puErrorLen (ErrorLen) returns the number of bytes in the error string as a 16-bit integer.


Fetching the driver interface

See also

The first step when working with dbExpress is to obtain an interface for the driver. To obtain this interface, you must call a global driver-specific function that returns the appropriate interface:

extern "C" SQLResult GCCSTDC getSQLDriverINTERBASE(pCHAR pszVendorLib, pCHAR pszResourceFile, ppSQLDriver ppDrv);

extern "C" SQLResult GCCSTDC getSQLDriverMYSQL(pCHAR pszVendorLib, pCHAR pszResourceFile, ppSQLDriver ppDrv);

extern "C" SQLResult GCCSTDC getSQLDriverDB2(pCHAR pszVendorLib, pCHAR pszResourceFile, ppSQLDriver ppDrv);

extern "C" SQLResult GCCSTDC getSQLDriverORACLE(pCHAR pszVendorLib, pCHAR pszResourceFile, ppSQLDriver ppDrv);

The pszVendorLib parameter is the fully-qualified file name for the client-side runtime software supplied by the database server.

The pszResourceFile parameter is the name of a file that contains the message catalog. This message catalog is a set of localized error messages for the driver to use.

The ppDrv parameter takes a pointer to a SQLDriver interface pointer and returns the interface pointer for the appropriate driver.

C++ Example

pSQLDriver IBDriver;

Status = getSQLDriverINTERBASE("GDS32.DLL", "", &IBDriver);

  ...

Note:	The dbxpress unit in Object Pascal does not include these global functions. To obtain a driver interface in Object Pascal, you must call GetProcAddress to obtain an entry point to the appropriate function in the dbExpress driver. For example:

var

  GetDriver : function(sVendorLib : PChar; sResourceFile : PChar; out Obj): SQLResult; stdcall;

  IBDriver: ISQLDriver;

begin

  GetDriver := GetProcAddress(LoadLibrary('dbexpint.dll'), 'getSQLDriverINTERBASE');

  Status := GetDriver(sVendorLib, sResourceFile, IBDriver);

  ...


SQLResult

SQLResult is the return type for dbExpress function calls

C++ syntax: typedef INT32 SQLResult;

Object Pascal syntax: SQLResult = Word;

SQLResult indicates the success or failure of a dbExpress function. The following table lists the error codes defined for dbExpress:

SQLResult value	Meaning
SQL_SUCCESS	The function call was successful.
DBXERR_NONE	Same as SQL_SUCCESS.
DBXERR_NOMEMORY	Insufficient memory.
DBXERR_INVALIDFLDTYPE	Invalid field type.
DBXERR_INVALIDHNDL	Invalid handle
DBXERR_INVALIDTIME	Invalid time value.
DBXERR_NOTSUPPORTED	Feature not supported.
DBXERR_INVALIDXLATION	Invalid translation
DBXERR_INVALIDPARAM	Invalid parameter.
DBXERR_OUTOFRANGE	Value out of range.
DBXERR_SQLPARAMNOTSET	Parameter not set.
DBXERR_EOF	Unexpected end-of-file
DBXERR_INVALIDUSRPASS	Invalid user password
DBXERR_INVALIDPRECISION	Invalid precision on a BCD value.
DBXERR_INVALIDLEN	Invalid length
DBXERR_INVALIDTXNISOLEVEL	Invalid transaction isolation level.
DBXERR_INVALIDTXNID	Invalid transaction id.
DBXERR_DUPLICATETXNID	Duplicate transaction id.
DBXERR_DRIVERRESTRICTED	Driver restricted.
DBXERR_LOCALTRANSACTIVE	An attempt to start multiple local transactions (only 1 allowed).


Logical field types

The following are the logical data types and subtypes that are used by dbExpress. Internally, dbExpress maps database-specific SQL types into database-specific physical data types and one or more physical data type maps into a logical data type. dbExpress does not expose the physical data types to the clients. However, individual database driver developers can choose to return physical data types.

Field Types (Logical)

Field type	Field subtype	Meaning
fldUNKNOWN		Field type is unknown.
fldZSTRING		Null terminated string
fldZSTRING	fldstFIXED	CHAR
fldDATE		Date (32-bit)
fldDATE	fldstADTDATE	Date (OCIDate) inside an ADT
fldBLOB		Binary large object (BLOB)
fldBLOB	fldstMEMO	Text memo
fldBLOB	fldstBINARY	binary data
fldBLOB	fldstHMEMO	CLOB
fldBLOB	fldstHBINARY	BLOB
fldBLOB	fldstBFILE	BFILE
fldBOOL		Boolean  (16 bit)
fldINT16		16-bit signed integer
fldINT32		32-bit signed integer
fldINT32	fldstAUTOINC	auto-incrementing field
fldFLOAT		64-bit floating point
fldFLOAT	fldstMONEY	Money
fldBCD		Binary-coded decimal (BCD)
fldBYTES		Fixed number of bytes
fldTIME		Time (32-bit)
fldVARBYTES		Length-prefixed var bytes
fldDATETIME		DateTime structure field
fldCURSOR		Cursor parameter – used by stored procedures that return a cursor as a parameter.
fldADT		Abstract datatype (structure). Cursors use fldADT to indicate the number of members contained in the ADT field. The values of the field members appear as subsequent fields on the same cursor.
fldADT	fldstADTNestedTable	Nested table (ADT). Cursors use this field type and subtype to indicate the number of fields in the nested table. The values of those fields appear a subsequent fields on the same cursor.
fldARRAY		Array field type. Cursors use fldARRAY to indicate the number of elements in the array. The values of those elements appear as subsequent fields on the same cursor.
fldREF		Reference to ADT  (not currently supported)
fldTABLE		Nested table (reference) (not currently supported)
fldFMTBCD		Binary-coded decimal (BCD)
Note:	These logical datatypes match logical types used by the Borland Database Engine, which allows for compatibility and more easy porting of applications. However, the mapping from SQL to logical data type may not be the same as in BDE. For example, fldDATETIME is introduced to represent timestamp data without any data loss. Similarly, numeric data that can't fit in a double are directly mapped into binary-coded decimal (BCD).


eSQLDriverOption (TSQLDriverOption)

This enumerated type identifies the various properties (or options) that can be set to configure an SQLDriver object.

C++ syntax

enum eSQLDriverOption

{

  eDrvBlobSize     = 0,

  eDrvCallBack     = 1,

  eDrvCallBackInfo = 2

  eDrvRestrict     = 3

};

Object Pascal syntax

type TSQLDriverOption = (eDrvBlobSize, eDrvCallBack, eDrvCallBackInfo, eDrvRestrict);

Description

The following table describes the possible values:

Value	Meaning

eDrvBlobSize	For drivers that don’t provide the available blob size before fetching, this specifies the number of kilobytes of BLOB data that is fetched for BLOB fields. (Note that for drivers that can supply the available BLOB size, the cursor’s getBlobSize returns the size of BLOB data).

eDrvCallBack	A callback that is executed for every message that passes between the application and the driver. The value of this option is a pointer to a callback function of type pfCallBack (C++) or TSQLCallBack (Object Pascal).

eDrvCallBackInfo	An application-defined value that is passed to the callback function specified by eDrvCallBack.

eDrvRestrict	Used internally. This should not be used by applications.


pfCallBack (TSQLCallbackEvent)

The type for callback functions on dbExpress objects.

C++ syntax

typedef CBRType (*pfCallBack) (CBType ecbType, pVOID pCbInfo);

Object Pascal syntax

type TSQLCallbackEvent = function(CallType: TRACECat; CBInfo: Pointer): CBRType; stdcall;

Description

The callback function includes the following parameters:

Parameter	Description

CBType or CallType	Indicates the type of callback function. Only one value is possible: cbTRACE, which indicates that the callback is executed for every message that passes between the driver and the database server.

pCbInfo or CBInfo	A pointer to the parameter structure for the callback type specified by the first parameter. For dbTRACE, this is a TRACEDesc structure. TRACEDesc includes the text of the message just passed, the category of the message, and a user-defined value supplied as an option on the dbExpress object.

The callback returns a value indicating how monitoring should proceed. Typically, this is cbrUSEDEF. Other possible return values are cbrCONTINUE, cbrABORT, cbrCHKINPUT, cbrYES, cbrNO, cbrPARTIALASSIST, cbrSKIP, and cbrRETRY.


TRACEDesc (TSQLTraceDesc)
TRACEDesc (SQLTRACEDesc)

TRACEDesc (C++) or SQLTraceDesc (Object Pascal) encodes information about a message that passes between a dbExpress object and a database server.

C++ syntax

typedef struct

{

  CHAR szTrace[1024];

  TRACECat eTraceCat;

  INT32 iCBInfo;

  UINT16 uTotalMsgLen;

} TRACEDesc;

Object Pascal syntax

type SQLTRACEDesc = packed record

     pszTrace     : array [0..1023] of Char;

     eTraceCat    : TRACECat;

     ClientData   : Integer;

     uTotalMsgLen : Word;

     end;

Description

TRACEDesc (C++) and SQLTRACEDesc (Object Pascal) describe a message that was just passed between a dbExpress driver and a database server.

szTrace (pszTrace) is the command that was just passed.

eTraceCat is the category of command that was just passed.

iCBInfo (ClientData) is an application-specific value supplied as an option on the dbExpress object with which the callback is registered.

uTotalMsgLen is the length of the string in szTrace.


TRACECat

Indicates the type of an SQL command that is being monitored.

C++ syntax

typedef enum  {traceQPREPARE, traceQEXECUTE, traceERROR, traceSTMT, traceCONNECT, traceTRANSACT, traceBLOB, traceMISC, traceVENDOR, traceDATAIN, traceDATAOUT} TRACECat;

Object Pascal syntax

typeTRACECat = TypedEnum;

Description

TRACECat indicates the type of a message between a dbExpress driver and a database server.

TRACECat can have the following values:

C++ value	Object Pascal value	Type of SQL command

traceQPREPARE	trQPREPARE	Prepared queries sent to the server

traceQEXECUTE	trQEXECUTE	Queries to be executed by the server. Note that a single statement may be prepared once and executed several times with different parameter bindings.

traceERROR	trERROR	Error messages returned by the server.  The error message may include an error code, depending on the server.

traceSTMT	trSTMT	Operations to be performed such as ALLOCATE, PREPARE, EXECUTE, and FETCH.

traceCONNECT	trCONNECT	Operations associated with connecting and disconnecting to databases, including allocation of connection handles and freeing connection handles, if required by server.

traceTRANSACT	trTRANSACT	Transaction operations such as BEGIN, COMMIT, and ROLLBACK (ABORT).

traceBLOB	trBLOB	Operations on Binary Large Object (BLOB) data, including STORE BLOB, GET BLOB HANDLE, and so on.

traceMISC	trMISC	Commands not covered by any other value.

traceVENDOR	trVENDOR	API function calls to the server.  For example, ORLON for Oracle, ISC_ATTACH for InterBase.

traceDATAIN	trDATAIN	Parameter data sent to servers when doing INSERTs or UPDATEs.

traceDATAOUT	trDATAOUT	Data retrieved from the server.


eSQLConnectOption (TSQLConnectionOption)

This enumerated type identifies the various properties (or options) that configure an SQLConnection object.

C++ syntax

enum eSQLConnectOption

{

  eConnAutoCommit    = 0,

  eConnBlockingMode    = 1,

  eConnBlobSize = 2,

  eConnRoleName = 3,

  eConnWaitOnLocks = 4,

  eConnCommitRetain = 5,

  eConnTxnIsoLevel = 6,

  eConnNativeHandle =7,

  eConnServerVersion = 8,

  eConnCallBack = 9,

  eConnHostName = 10,

  eConnDatabaseName = 11,

  eConnCallBackInfo = 12,

  eConnObjectMode = 13,

  eConnMaxActiveComm = 14,

  eConnServerCharSet = 15,

  eConnServerDialect = 16

};

Object Pascal syntax

type TSQLConnectionOption = (eConnAutoCommit, eConnBlockingMode, eConnBlobSize, eConnRoleName, eConnWaitOnLocks, eConnCommitRetain, eConnTxnIsoLevel, eConnNativeHandle, eConnServerVersion, eConnCallBack, eConnHostName, eConnDatabaseName, eConnCallBackInfo, eConnObjectMode, eConnMaxActiveConnection, eConnServerCharSet, eConnServerDialect);

Description

The following table describes the possible values:

Value	Meaning
eConnAutoCommit	Boolean value that indicates whether all updates to the database server are wrapped in an implicit transaction.  This option is true by default. Oracle only.
eConnBlockingMode	Boolean value that indicates whether the connection supports asynchronous processing. When true, processing is synchronous (caller must wait until command has completed). Oracle only.
eConnBlobSize	For drivers that don’t provide the available blob size before fetching, this specifies the number of kilobytes of BLOB data that is fetched for BLOB fields. This overrides any value specified at the driver level using eDrvBlobSize.
eConnRoleName	String value that specifies the role to use when establishing a connection. Only supported by the InterBase driver.
eConnWaitOnLocks	Boolean that indicates whether application should wait until a locked resource is free rather than raise an exception. Only supported by the InterBase driver.
eConnCommitRetain	Boolean that indicates whether cursors are retained or dropped when a transaction is committed. Only supported by InterBase. Other drivers always retain the cursor when transactions are committed.
eConnTxnIsoLevel	Transaction isolation level. Value is of type eXILType (C++) or TTransIsolationLevel (Object Pascal).
eConnNativeHandle	Provides access to the native SQL connection handle that can be used when writing code that directly uses the server’s API. (Read-only)
eConnServerVersion	The version number of the database server. (Read-only)
eConnCallBack	A callback that is executed for every message that passes between the application and this connection. The value of this option is a pointer to a callback function of type pfCallBack (C++) or TSQLCallBack (Object Pascal).
eConnHostName	The host name for the machine which is running the database server. This value is needed only for the MySQL driver.
eConnDatabaseName	The full name of the database to which this object connects. This name may include more information than the name supplied when establishing a connection. (Read-only)
eConnCallBackInfo	An application-defined value that is passed to the callback function specified by eConnCallBack.
eConnObjectMode	Boolean value to enable or disable object fields in Oracle8 tables. Setting eConnObjectMode to false conserves system resources when the application is not using object fields.
eConnMaxActiveComm (C++) eConnMaxActiveConnection (OP)	The maximum number of active commands that can be executed by a single connection. (Read-only)
eConnServerCharSet	A string that gives the name of the character set used by an InterBase database server.
eConnSQLDialect	The default dialect to use for all SQL commands that pass from clients over this connection. (InterBase only). InterBase 5 only supports a value of 1. For InterBase 6, the value can be 1, 2, or 3.


eXILType (TTransIsolationLevel)

This enumerated type identifies the degree to which transactions are isolated from each other.

C++ syntax

typedef enum { xilREADCOMMITTED, xilREPEATABLEREAD, xilDIRTYREAD, xilCUSTOM } eXILType;

Object Pascal syntax

type TTransIsolationLevel = (xilREADCOMMITTED, xilREPEATABLEREAD, xilDIRTYREAD, xilCUSTOM);

Description

The following table describes the possible values:

Value	Meaning

xilDIRTYREAD	Current transaction sees all changes made by other transactions, even if they have not yet been committed. This option is not available for the Oracle driver.

xilREADCOMMITTED	Current transaction sees only changes that have been committed, but can receive an inconsistent view of the data if additional changes are committed before the transaction ends.

xilREPEATABLEREAD	Current transaction is guaranteed a consistent view of the data, which includes only changes committed by other transactions at the start of the transaction.

xilCUSTOM	Current transaction uses a database-specific isolation level. When the eConnTxnIsoLevel option is xilCUSTOM, the transaction descriptor gives the actual isolation level. This is not currently supported by any drivers, but allows future drivers the ability to expand the number of isolation levels.


eSQLCommandOption (TSQLCommandOption)

This enumerated type identifies the various properties (or options) that configure an SQLCommand object.

C++ syntax

enum eSQLCommandOption

{

  eCommRowsetSize    = 0,

  eCommBlobSize    = 1,

  eCommBlockRead = 2,

  eCommBlockWrite = 3,

  eCommParamCount = 4,

  eCommNativeHandle = 5,

  eCommCursorName = 6,

  eCommStoredProc =7,

  eCommSQLDialect = 8,

  eCommTransactionID = 9

};

Object Pascal syntax

type TSQLCommandOption = ( eCommRowsetSize, eCommBlobSize, eCommBlockRead, eCommBlockWrite, eCommParamCount, eCommNativeHandle, eCommCursorName, eCommStoredProc, eCommSQLDialect, eCommTransactionID);

Description

The following table describes the possible values:

Value	Meaning
eCommRowsetSize	The number of records included in a block when performing block reads. This option is only used when eCommBlockRead is true.
eCommBlobSize	For drivers that don’t provide the available blob size before fetching, this specifies the number of kilobytes of BLOB data that is fetched for BLOB fields. This overrides any value specified at the driver level or connection level.
eCommBlockRead	Boolean value that indicates whether block fetching is in effect. With block fetching, multiple records are retrieved from the database server in a single operation. This option is only supported by the DB2 and Oracle drivers.
eCommBlockWrite	Boolean value that indicates whether block updates are in effect. With block updates, multiple records are written to the database server in a single operation. This option is currently not implemented for any drivers.
eCommParamCount	Indicates the number of parameters used by the query or stored procedure. (Read-only)
eCommNativeHandle	Provides access to the native SQL handle that can be used when writing code that directly uses the server’s API. (Read-only)
eCommCursorName	A string that names the cursor. Assigning a name to a cursor can facilitate error tracking on the server. This option is only supported by the DB2 driver.
eCommStoredProc	Boolean value to indicate whether the command represents a query or a stored procedure. When true, the command represents a stored procedure. When false, the command represents a query.
eCommSQLDialect	The SQL dialect used to express this command. (InterBase only). InterBase 5 only supports a value of 1. For InterBase 6, the value can be 1, 2, or 3. This value overrides any default dialect specified by the connection object.
eCommTransactionID	The identifier for the transaction to which this command belongs. This is the same as the identifier specified when calling beginTransaction. If not specified, the command always belongs to the most recently started transaction. eCommTransactionID is most useful for InterBase overlapped transactions, where a command can belong to any transaction that has been started. Oracle transactions, which can be nested or overlapped, do not require this property because a command always belongs to the most recently started transaction. Note: On Oracle 8, a transaction ID of 0 specifies a local transaction. There can be only on active local transaction.


STMTParamType (TSTMTParamType)

This enumerated type indicates whether a parameter acts as in input, output, input/output, or return parameter.

C++ syntax

enum STMTParamType

{

  paramUNKNOWN = 0,

  paramIN      = 1,

  paramOUT     = 2,

  paramINOUT   = 3,

  paramRET     = 4

};

Object Pascal syntax

typeTSTMTParamType = (paramUNKNOWN, paramIN, paramOUT, paramINOUT, paramRET);

Description

The following table describes the possible values:

Value	Meaning
paramUNKNOWN	The parameter type is unknown (generates an error)
paramIN	Input parameter
paramOUT	Output parameter
paramINOUT	Input/Output parameter


eSQLCursorOption (TSQLCursorOption)

This enumerated type identifies the various properties (or options) that configure the fields of an SQLCursor object.

C++ syntax

enum eSQLCursorOption

{

  eCurObjectAttrName = 0,

  eCurObjectTypeName = 1,

  eCurParentFieldID  = 2

};

Object Pascal syntax

type TSQLCursorOption = (eCurObjectAttrName, eCurObjectTypeName, eCurParentFieldID);

Description

The following table describes the possible values:

Value	Meaning

eCurObjectAttrName	The full name of the object member that a specified field represents. (Used for member fields of ADT fields). The column number and attribute name appear in a structure of type ObjAttrDesc.

eCurObjectTypeName	The type name of the object that a specified field represents (used for ADT fields). The column number and type name appear in a structure of type ObjTypeDesc.

eCurParentFieldID	The field number of the parent field for a specified field (used for member fields of ADT or array fields). The column number and parent field number appear in a structure of type ObjParentDesc.


ObjAttrDesc

ObjAttrDesc is used for retrieving the full member name of a field that represents a member of an ADT field.

C++ syntax

typedef struct

{

  UINT16 uColNum;

  pCHAR pszAttributeName;

} ObjAttrDesc;

Object Pascal syntax

type ObjAttrDesc = packed record

     iFldNum          : Word;

     pszAttributeName : PChar;

     end;

Description

Fill in the uColNum or iFldNum member of an ObjAttrDesc structure when fetching the full member name of a field that represents a member of an ADT field. The cursor’s getOption method assigns a value to the pszAttributeName member to return the name.

uColNum (C++) or iFldNum (Object Pascal) is the number of the column that represents a member of an ADT field. This is the column number on the SQLCursor object, where the first field has number 1, the second field has number 2, and so on.

pszAttributeName is a null-terminated string that gives the full member name of the field. This is a name of the form objectfieldName.membername.


ObjTypeDesc

ObjTypeDesc is used for retrieving the type name an ADT field.

C++ syntax

typedef struct

{

  UINT16 uColNum;

  CHAR szTypeName[DBXMAXNAMELEN];

} ObjTypeDesc;

Object Pascal syntax

type ObjTypeDesc = packed record

     iFldNum          : Word;

     szTypeName : array[0..30] of Char;

     end;

Description

Fill in the uColNum or iFldNum member of an ObjTypeDesc structure when fetching the type name of an ADT field. The cursor’s getOption method assigns a value to the szTypeName member to return the name.

uColNum (C++) or iFldNum (Object Pascal) is the number of the column that represents an ADT field. This is the column number on the SQLCursor object, where the first field has number 1, the second field has number 2, and so on.

szTypeName is a null-terminated string that gives the name of the ADT type.


ObjParentDesc

ObjParentDesc is used for retrieving the parent field number of a field that is a member of an ADT or array field.

C++ syntax

typedef struct

{

  UINT16 uColNum;

  UINT16 uParentColNum;

} ObjParentDesc;

Object Pascal syntax

type ObjParentDesc = packed record

     iFldNum       : Word;

     iParentFldNum : Word;

     end;

Description

Fill in the uColNum or iFldNum member of an ObjParentDesc structure when fetching the field number for a field’s parent field. The cursor’s getOption method assigns a value to the uParentColNum or iParentFldNum member to return the field number of the parent field.

uColNum (C++) or iFldNum (Object Pascal) is the number of the member field. This is the column number on the SQLCursor object, where the first field has number 1, the second field has number 2, and so on. The specified field should be a child field that is a member of an ADT or array field.

uParentColNum (C++) or iParentFldNum (Object Pascal) is the column number on the SQLCursor for the specified field’s parent field.


TransactionDesc (TTransactionDesc)

TTransactionDesc describes a transaction. A pointer to this structure is passed as a parameter to the beginTransaction, commit, and rollback methods.

C++ syntax

typedef struct

{

  UINT32  uTransID;

  UINT32  uGID;

  eXILType eTransIsoLevel;

  UINT32  uCustomIsolation;

} TransactionDesc;

Object Pascal syntax

type TTransactionDesc = packed record

     TransactionID    : LongWord;

     GlobalID         : LongWord;

     IsolationLevel   : TTransIsolationLevel;

     CustomIsolation  : LongWord;

     end;

Description

Fill in a TransactionDesc structure (TTransactionDesc record) to describe the transaction you are starting, committing, or rolling back.

uTransID (TransactionID) is a unique identifier for the transaction. The transaction identifier is assigned when you call beginTransaction, and identifies the transaction in subsequent method calls. It can also be assigned to the eCommTransactionID option of a command object to associated the command with a specific transaction. The value you assign to TransactionID must not match the identifier of any other active transaction.

Note:	On Oracle 8, a transaction ID of 0 specifies a local (vs global) transaction. Local transactions are relative to a user session, and there can be only one active local transaction. When the transaction is local, the uGID (GlobalID) must be 0 as well.

uGID (GlobalID) is used for ORACLE transactions. Each transaction requires a unique global ID if there are multiple or nested transactions. For local transactions, this value must be 0.

eTransIsoLevel (IsolationLevel) indicates the degree to which this transaction is isolated from other transactions. Note that different drivers support different isolation levels.

uCustomIsolation (CustomIsolation) identifies a custom isolation level when the IsolationLevel field is xilCUSTOM.


FMTBcd (TBcd)

FMTBcd (C++) and TBcd (Object Pascal) represent a binary-coded decimal value.

C++ syntax

typedef struct

{

  BYTE iPrecision;

  BYTE iSignSpecialPlaces;

  BYTE iFraction[32];

} FMTBcd;

Object Pascal syntax

type

  TBcd  = packed record

    Precision: Byte;

    SignSpecialPlaces: Byte;

    Fraction: packed array [0..31] of Byte;

  end;

Description

FMTBcd (C++) or TBcd (Object Pascal) represents a binary-coded decimal value. It contains the following fields:

Field	Contents
iPrecision (Precision)	The number of digits in the decimal version of the value.
iSignSpecialPlaces (SignSpecialPlaces)	The sign bit (0 is positive, any other value negative) the special bit (nonzero indicates that the value is blank) the number of digits after the decimal (0 to iPrecision)
iFraction (Fraction)	An array of BCD nibbles, 00 to 99 per byte, high nibble first. Only the first iPrecision nibbles are used.


CTIMESTAMP (TSQLTimeStamp)

CTIMESTAMP (C++) and TSQLTimeStamp (Object Pascal) represent a date-and-time value.

C++ syntax

typedef struct

{

  INT16 year;

  UINT16 month;

  UINT16 day;

  UINT16 hour;

  UINT16 minute;

  UINT16 second;

  UINT32 fraction;

} CTIMESTAMP;

Object Pascal syntax

type TSQLTimeStamp = packedrecord

    Year : SmallInt;

    Month : Word;

    Day : Word;

    Hour : Word;

    Minute : Word;

    Second : Word;

    Fractions : LongWord;

  end;

Description

CTIMESTAMP (C++) or TSQLTimeStamp (Object Pascal) represents a date-and-time value. It contains the following fields:

year specifies a year from 1 to 9999.

month specifies a month from 1 to 12.

day specifies a day of the month, from 1 through 28, 29, 30, or 31, depending on the month value.

hour specifies the hour from 0 to 23.

minute and second can range from 0 to 59.

fraction (Fractions) specifies milliseconds from 0 to 999.


Search Patterns

Most of the methods on SQLMetaData let you specify a search pattern to limit the set of objects returned. Search patterns are templates against which an object name is compared.

In addition to literal characters, search patterns can contain the following characters, which are based on standard SQL wildcard characters.

An underscore (_) matches any single character

A percent sign (%) matches a sequence of one or more characters

An escape character, when preceded to the underscore or the percent sign character, allows the underscore or percent sign to be used as a literal character. Similarly, a sequence of two escape characters allows the escape character to be used as a literal character.

Note:	The character used as an escape character is server-specific. To determine the escape character for a particular server, call the SQLMetaData object’s getOption method, specifying eMetaSQLEscapeChar as the option.

Specifying a search pattern that contains only literal characters requires an exact match. Specifying a search pattern of NULL (nil) matches any object in the scope of the method.


eSQLMetaDataOption (TSQLMetaDataOption)

This enumerated type identifies the various properties (or options) of an SQLMetaDataobject.

C++ syntax

enum eSQLMetaDataOption

{

  eMetaCatalogName          = 0,

  eMetaSchemaName           = 1,

  eMetaDatabaseName         = 2,

  eMetaDatabaseVersion      = 3,

  eMetaTransactionIsoLevel  = 4,

  eMetaSupportsTransaction  = 5,

  eMetaMaxObjectNameLength  = 6,

  eMetaMaxColumnsInTable    =7,

  eMetaMaxColumnsInSelect   = 8,

  eMetaMaxRowSize           = 9,

  eMetaMaxSQLLength         = 10,

  eMetaObjectQuoteChar      = 11,

  eMetaSQLEscapeChar        =12,

  eMetaProcSupportsCursor   = 13,

  eMetaProcSupportsCursors  = 14,

  eMetaSupportsTransactions = 15

};

Object Pascal syntax

type TSQLMetaDataOption = (eMetaCatalogName, eMetaSchemaName, eMetaDatabaseName, eMetaDatabaseVersion, eMetaTransactionIsoLevel, eMetaSupportsTransaction, eMetaMaxObjectNameLength, eMetaMaxColumnsInTable, eMetaMaxColumnsInSelect, eMetaMaxRowSize, eMetaMaxSQLLength, eMetaObjectQuoteChar, eMetaSQLEscapeChar, eMetaProcSupportsCursor, eMetaProcSupportsCursors,  eMetaSupportsTransactions);

Description

The following table describes the possible values:

Value	Meaning
eMetaCatalogName	A string that specifies the name of the catalog from which SQLMetaData retrieves information.
eMetaSchemaName	A string that specifies the name of the schema, or user, for which SQLMetaData retrieves information.
eMetaDatabaseName	The full name of the database about which SQLMetaData returns information. The value of this property reflects the database to which the SQLConnection object forms an attachment. (Read-only)
eMetaDatabaseVersion	A string giving the version number of the database about which SQLMetaData returns information. (Read-only)
eMetaTransactionIsoLevel	An eXILType (C++) or TTransIsolationLevel (Object Pascal) value that indicates the current transaction isolation level for the current connection. (Read-only: use the options of SQLConnection to set the transaction isolation level)
eMetaSupportsTransaction	Boolean value that indicates whether the server supports transactions. For example, MySQL does not support transactions. (Read-only)
eMetaMaxObjectNameLength	Integer that indicates the maximum number of bytes that can be used for the name of an object (table name, index, name, etc). (Read-only)
eMetaMaxColumnsInTable	Integer value that indicates the maximum number of fields (columns) that can appear in a single table. (Read-only)
eMetaMaxColumnsInSelect	Integer value that indicates the maximum number of fields (columns) that can be requested by a SELECT query. (Read-only)
eMetaMaxRowSize	Integer that indicates the maximum number of bytes in a record buffer. (Read-only)
eMetaMaxSQLLength	Integer that indicates the maximum number of characters (bytes) in an SQL statement. (Read-only)
eMetaObjectQuoteChar	Pointer to the character that should be used as a quotation mark for names in SQL statements. (Read-only)
eMetaSQLEscapeChar	Pointer to the character that is used as an escape character when creating pattern strings. (Read-only)
eMetaProcSupportsCursor	Boolean value that indicates whether stored procedures on the server can return a cursor. (Read-only)
eMetaProcSupportsCursors	Boolean value that indicates whether stored procedures on the server can return multiple cursors. (Read-only)
eMetaSupportsTransactions	Boolean value that indicates whether the server supports nested transactions. (Read-only)


eSQLObjectType (TSQLObjectType)

This enumerated type identifies the types of objects of which SQLMetaData can generate a list.

C++ syntax

enum eSQLObjectType

{

  eObjTypeDatabase = 0,

  eObjTypeDataType = 1,

  eObjTypeTable = 2,

  eObjTypeView = 3,

  eObjTypeSynonym = 4,

  eObjTypeProcedure = 5,

  eObjTypeUser = 6,

  eObjTypeRole =7,

  eObjTypeUDT = 8

};

Object Pascal syntax

type TSQLObjectType = (eObjTypeDatabase, eObjTypeDataType, eObjTypeTable, eObjTypeView, eObjTypeSynonym, eObjTypeProcedure, eObjTypeUser, eObjTypeRole, eObjTypeUDT);

Description

The getObjectList method of SQLMetaData returns a cursor for accessing a table of information about every object of a specified type. eSQLObjectType (TSQLObjectType) identifies the type of object to list.

The following table describes the possible values:

Value	Meaning
eObjTypeDatabase	All available databases on the server.
eObjTypeDataType	Data types supported by the server.
eObjTypeTable	All tables.
eObjTypeView	All defined views.
eObjTypeSynonym	All defined synonyms.
eObjTypeProcedure	All defined stored procedures.
eObjTypeUser	All valid users.
eObjTypeRole	All defined roles (InterBase only).
eObjTypeUDT	All User-defined types (Oracle only)


eSQLTableType (table type constants)

These values identify the types of tables to include in the list that the getTables method returns.

C++ syntax

enum eSQLTableType

{

  eSQLTable       = 0,

  eSQLView        = 1,

  eSQLSystemTable = 2,

  eSQLSynonym     = 3,

  eSQLTempTable   = 4,

  eSQLLocal       = 5

};

Object Pascal syntax

const

  eSQLTable       = $0001;

  eSQLView        = $0002;

  eSQLSystemTable = $0004;

  eSQLSynonym     = $0008;

  eSQLTempTable   = $0010;

  eSQLLocal       = $0020;

Description

The following table describes the possible values:

Value	Meaning
eSQLTable	Tables that contain data.
eSQLView	Views.
eSQLSystemTable	System tables.
eSQLSynonym	Synonyms.
eSQLTempTable	Temporary tables.
eSQLLocal	Local tables.


eSQLProcType (stored procedure type constants)

These values identify the types of stored procedures to include in the list that the getProcedures method returns.

C++ syntax

enum eSQLProcType

{

  eSQLProcedure    = 0,

  eSQLFunction     = 1,

  eSQLPackage      = 2,

  eSQLSysProcedure = 3

};

Object Pascal syntax

const

  eSQLProcedure    = $0001;

  eSQLFunction     = $0002;

  eSQLPackage      = $0004;

  eSQLSysProcedure = $0008;

Description

The following table describes the possible values:

Value	Meaning
eSQLProcedure	Procedures
eSQLFunction	Functions.
eSQLPackage	Packages (Oracle only)
eSQLSysProcedure	System procedures.


eSQLColType (column type constants)

These values identify the types of columns to include in the list that the getColumns method returns.

C++ syntax

enum eSQLColType

{

  eSQLRowId      = 0,

  eSQLRowVersion = 1,

  eSQLAutoIncr   = 2,

  eSQLDefault    = 3

};

Object Pascal syntax

const

  eSQLRowId       = $0001;

  eSQLRowVersion  = $0002;

  eSQLAutoIncr    = $0004;

  eSQLDefault     = $0008;

Description

The following table describes the possible values:

Value	Meaning
eSQLRowId	Row Id number.
eSQLRowVersion	Version number.
eSQLAutoIncr	Auto-incrementing field (server generates value).
eSQLDefault	Field with a default value. (server can generate value)


eSQLIndexType (index type constants)

These values identify the types of index to include in the list that the getInices method returns.

C++ syntax

enum eSQLIndexType

{

  eSQLNonUnique  = 0,

  eSQLUnique     = 1,

  eSQLPrimaryKey = 2,

};

Object Pascal syntax

const

  eSQLNonUnique   = $0001;

  eSQLUnique      = $0002;

  eSQLPrimaryKey  = $0004;

Description

The following table describes the possible values:

Value	Meaning
eSQLNonUnique	Index that can point to multiple rows with the same key.
eSQLUnique	Index that points to a unique row for each key.
eSQLPrimaryKey	Primary key for the table.


Link not found

The topic you requested is either not available or not linked to this Help system. This can occur if you launched this Help file from a system on which Delphi has not yet been installed, or if the subject matter you are requesting is not available in your edition of Delphi


The topic you requested is now loading. If it does not appear within a few seconds, the topic is either not available or not linked to this Help system. This can occur if you launched this Help file from a system on which Delphi has not yet been installed, or if the subject matter you are requesting is not available in your edition of Delphi.