`SQLGetFunctions()` - Get functions

SQLGetFunctions() indicates if a specific function is supported.

SQLGetFunctions() allows applications to adapt to different levels of support when they connect to different database servers. A connection to a database server must exist before SQLGetFunctions() is called.

ODBC specifications for `SQLGetFunctions()`

Table 1. `SQLGetFunctions()` specifications
ODBC specification level	In X/Open CLI CAE specification?	In ISO CLI specification?
1.0	Yes	Yes

Syntax

SQLRETURN   SQLGetFunctions  (SQLHDBC           hdbc,
                              SQLUSMALLINT      fFunction,
                              SQLUSMALLINT FAR  *pfExists);

Function arguments

The following table lists the data type, use, and description for each argument in this function.

Table 2. `SQLGetFunctions()` arguments
Data type	Argument	Use	Description
SQLHDBC	hdbc	input	Specifies a database connection handle.
SQLUSMALLINT	fFunction	input	Specifies which function is queried. Table 3 shows valid fFunction values.
SQLUSMALLINT *	pfExists	output	Points to the buffer where this function returns SQL_TRUE or SQL_FALSE. If the function that is queried is supported, SQL_TRUE is returned into the buffer. If the function is not supported, SQL_FALSE is returned into the buffer.

Usage

Table 3 shows the valid values for the fFunction argument and whether the corresponding function is supported.

If the fFunction argument is set to SQL_API_ALL_FUNCTIONS, then the pfExists argument must point to an SQLSMALLINT array of 100 elements. The array is indexed by the values in the fFunction argument that are used to identify many of the functions. Some elements of the array are unused and reserved. Because some values for the fFunction argument are greater than 100, the array method can not be used to obtain a list of all functions. The SQLGetFunctions() call must be explicitly issued for all values equal to or above 100 for the fFunction argument. The complete set of fFunction values is defined in sqlcli1.h.

Table 3. `SQLGetFunctions()` functions and values
fFunction	Value Db2 ODBC returns
SQL_API_SQLALLOCCONNECT	SQL_TRUE
SQL_API_SQLALLOCENV	SQL_TRUE
SQL_API_SQLALLOCHANDLE	SQL_TRUE
SQL_API_SQLALLOCSTMT	SQL_TRUE
SQL_API_SQLBINDCOL	SQL_TRUE
SQL_API_SQLBINDFILETOCOL	SQL_TRUE
SQL_API_SQLBINDFILETOPARAM	SQL_TRUE
SQL_API_SQLBINDPARAMETER	SQL_TRUE
SQL_API_SQLBROWSECONNECT	SQL_FALSE
SQL_API_SQLBULKOPERATIONS	SQL_TRUE
SQL_API_SQLCANCEL	SQL_TRUE
SQL_API_SQLCLOSECURSOR	SQL_TRUE
SQL_API_SQLCOLATTRIBUTE	SQL_TRUE
SQL_API_SQLCOLATTRIBUTES	SQL_TRUE
SQL_API_SQLCOLUMNPRIVILEGES	SQL_TRUE
SQL_API_SQLCOLUMNS	SQL_TRUE
SQL_API_SQLCONNECT	SQL_TRUE
SQL_API_SQLDATASOURCES	SQL_TRUE
SQL_API_SQLDESCRIBECOL	SQL_TRUE
SQL_API_SQLDESCRIBEPARAM	SQL_TRUE
SQL_API_SQLDISCONNECT	SQL_TRUE
SQL_API_SQLDRIVERCONNECT	SQL_TRUE
SQL_API_SQLENDTRAN	SQL_TRUE
SQL_API_SQLERROR	SQL_TRUE
SQL_API_SQLEXECDIRECT	SQL_TRUE
SQL_API_SQLEXECUTE	SQL_TRUE
SQL_API_SQLEXTENDEDFETCH	SQL_TRUE
SQL_API_SQLFETCH	SQL_TRUE
SQL_API_SQLFETCHSCROLL	SQL_TRUE
SQL_API_SQLFOREIGNKEYS	SQL_TRUE
SQL_API_SQLFREECONNECT	SQL_TRUE
SQL_API_SQLFREEENV	SQL_TRUE
SQL_API_SQLFREEHANDLE	SQL_TRUE
SQL_API_SQLFREESTMT	SQL_TRUE
SQL_API_SQLGETCONNECTATTR	SQL_TRUE
SQL_API_SQLGETCONNECTOPTION	SQL_TRUE
SQL_API_SQLGETCURSORNAME	SQL_TRUE
SQL_API_SQLGETDATA	SQL_TRUE
SQL_API_SQLGETDIAGREC	SQL_TRUE
SQL_API_SQLGETENVATTR	SQL_TRUE
SQL_API_SQLGETFUNCTIONS	SQL_TRUE
SQL_API_SQLGETINFO	SQL_TRUE
SQL_API_SQLGETLENGTH	SQL_TRUE
SQL_API_SQLGETPOSITION	SQL_TRUE
SQL_API_SQLGETSQLCA	SQL_TRUE
SQL_API_SQLGETSTMTATTR	SQL_TRUE
SQL_API_SQLGETSTMTOPTION	SQL_TRUE
SQL_API_SQLGETSUBSTRING	SQL_TRUE
SQL_API_SQLGETTYPEINFO	SQL_TRUE
SQL_API_SQLMORERESULTS	SQL_TRUE
SQL_API_SQLNATIVESQL	SQL_TRUE
SQL_API_SQLNUMPARAMS	SQL_TRUE
SQL_API_SQLNUMRESULTCOLS	SQL_TRUE
SQL_API_SQLPARAMDATA	SQL_TRUE
SQL_API_SQLPARAMOPTIONS	SQL_TRUE
SQL_API_SQLPREPARE	SQL_TRUE
SQL_API_SQLPRIMARYKEYS	SQL_TRUE
SQL_API_SQLPROCEDURECOLUMNS	SQL_TRUE
SQL_API_SQLPROCEDURES	SQL_TRUE
SQL_API_SQLPUTDATA	SQL_TRUE
SQL_API_SQLROWCOUNT	SQL_TRUE
SQL_API_SQLSETCOLATTRIBUTES	SQL_TRUE
SQL_API_SQLSETCONNECTATTR	SQL_TRUE
SQL_API_SQLSETCONNECTION	SQL_TRUE
SQL_API_SQLSETCONNECTOPTION	SQL_TRUE
SQL_API_SQLSETCURSORNAME	SQL_TRUE
SQL_API_SQLSETENVATTR	SQL_TRUE
SQL_API_SQLSETPARAM	SQL_TRUE
SQL_API_SQLSETPOS	SQL_TRUE
SQL_API_SQLSETSCROLLOPTIONS	SQL_FALSE
SQL_API_SQLSETSTMTATTR	SQL_TRUE
SQL_API_SQLSETSTMTOPTION	SQL_TRUE
SQL_API_SQLSPECIALCOLUMNS	SQL_TRUE
SQL_API_SQLSTATISTICS	SQL_TRUE
SQL_API_SQLTABLEPRIVILEGES	SQL_TRUE
SQL_API_SQLTABLES	SQL_TRUE
SQL_API_SQLTRANSACT	SQL_TRUE

Return codes

After you call SQLGetFunctions(), it returns one of the following values:

SQL_SUCCESS
SQL_ERROR
SQL_INVALID_HANDLE

Diagnostics

The following table lists each SQLSTATE that this function generates, with a description and explanation for each value.

Table 4. `SQLGetFunctions()` SQLSTATEs
SQLSTATE	Description	Explanation
08S01	Communication link failure.	The communication link between the application and data source fails before the function completes.
58004	Unexpected system failure.	Unrecoverable system error.
HY001	Memory allocation failure.	Db2 ODBC is not able to allocate the required memory to support the execution or the completion of the function.
HY009	Invalid use of a null pointer.	The argument pfExists specifies a null pointer.
HY010	Function sequence error.	`SQLGetFunctions()` is called before a database connection is established.
HY013	Unexpected memory handling error.	Db2 ODBC is not able to access the memory that is required to support execution or completion of the function.

Example

The following example shows an application that connects to a database server and checks for API support using SQLGetFunctions().

Figure 1. An application that checks the database server for API support

 /******************************************************************/
 /*  Execute SQLGetFunctions to verify that APIs required          */
 /*  by application are supported.                                 */
 /******************************************************************/
#include <stdio.h>
#include <string.h>
#include <stdlib.h>
#include <sqlca.h>
#include "sqlcli1.h"
typedef struct odbc_api
{
  SQLUSMALLINT   api;
  char           api_name _40];
} ODBC_API;
 /******************************************************************/
 /* CLI APIs required by application                               */
 /******************************************************************/
ODBC_API o_api [7] = {
   { SQL_API_SQLBINDPARAMETER, "SQLBindParameter" } ,
   { SQL_API_SQLDISCONNECT   , "SQLDisconnect"    } ,
   { SQL_API_SQLGETTYPEINFO  , "SQLGetTypeInfo"   } ,
   { SQL_API_SQLFETCH        , "SQLFetch"         } ,
   { SQL_API_SQLTRANSACT     , "SQLTransact"      } ,
   { SQL_API_SQLBINDCOL      , "SQLBindCol"       } ,
   { SQL_API_SQLEXECDIRECT   , "SQLExecDirect"    }
                                       } ;
   
  /******************************************************************/
  /* Validate that required APIs are supported.                    */
  /******************************************************************/
int main( )
{
   SQLHENV         hEnv    = SQL_NULL_HENV;
   SQLHDBC         hDbc    = SQL_NULL_HDBC;
   SQLRETURN       rc      = SQL_SUCCESS;
   SQLINTEGER      RETCODE = 0;
   int             i;
   // SQLGetFunctions parameters
   SQLUSMALLINT     fExists  = SQL_TRUE;
   SQLUSMALLINT    *pfExists = &fExists;
   (void) printf ("**** Entering CLIP05.\n\n");
  /*****************************************************************/
  /* Allocate environment handle                                   */
  /*****************************************************************/
   RETCODE = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &hEnv);
   if (RETCODE != SQL_SUCCESS)
     goto dberror;
  /*****************************************************************/
  /* Allocate connection handle to DSN                             */
  /*****************************************************************/
   RETCODE = SQLAllocHandle(SQL_HANDLE_DBC, hEnv, &hDbc);
   if( RETCODE != SQL_SUCCESS )      // Could not get a connect handle
     goto dberror;
  /*****************************************************************/
  /* CONNECT TO data source (STLEC1)                               */
  /*****************************************************************/
   RETCODE = SQLConnect(hDbc,        // Connect handle
                        (SQLCHAR *) "STLEC1", // DSN
                        SQL_NTS,     // DSN is nul-terminated
                        NULL,        // Null UID
                        0   ,
                        NULL,        // Null Auth string
                        0);
   if( RETCODE != SQL_SUCCESS )      // Connect failed
     goto dberror;
   /*****************************************************************/
  /* See if DSN supports required ODBC APIs                        */
  /*****************************************************************/
   for (i = 0, (*pfExists = SQL_TRUE);
        (i < (sizeof(o_api)/sizeof(ODBC_API)) && (*pfExists) == SQL_TRUE);
        i++)
   {
     RETCODE = SQLGetFunctions (hDbc,
                                o_api[i].api,
                                pfExists);
     if (*pfExists == SQL_TRUE)      // if api is supported then print
     {
       (void) printf ("**** ODBC api %s IS supported.\n",
                      o_api[i].api_name);
     }
   }
   if (*pfExists == SQL_FALSE)      // a required api is not supported
   {
     (void) printf ("**** ODBC api %s not supported.\n",
                    o_api[i].api_name);
   }
  /*****************************************************************/
  /* DISCONNECT from data source                                   */
  /*****************************************************************/
   RETCODE = SQLDisconnect(hDbc);
   if (RETCODE != SQL_SUCCESS)
     goto dberror;
  /*****************************************************************/
  /* Deallocate connection handle                                  */
  /*****************************************************************/
   RETCODE = SQLFreeHandle(SQL_HANDLE_DBC, hDbc);
   if (RETCODE != SQL_SUCCESS)
     goto dberror;
  /*****************************************************************/
  /* Free environment handle                                       */
  /*****************************************************************/
   RETCODE = SQLFreeHandle(SQL_HANDLE_ENV, hEnv);
   if (RETCODE == SQL_SUCCESS)
     goto exit;
   dberror:
   RETCODE=12;
   exit:
   (void) printf("\n\n**** Exiting  CLIP05.\n\n   ");
   return(RETCODE);
}