Función SQLGetFunctions

Conformidad
Versión introducida: Cumplimiento de estándares ODBC 1.0: ISO 92

Resumen
SQLGetFunctions devuelve información sobre si un controlador admite una función ODBC específica. Esta función se implementa en el Administrador de controladores; también se puede implementar en controladores. Si un controlador implementa SQLGetFunctions, el Administrador de controladores llama a la función en el controlador. De lo contrario, ejecuta la propia función.

Sintaxis

  
SQLRETURN SQLGetFunctions(  
     SQLHDBC           ConnectionHandle,  
     SQLUSMALLINT      FunctionId,  
     SQLUSMALLINT *    SupportedPtr);  

Argumentos

ConnectionHandle
[Entrada] Identificador de conexión.

Functionid
[Entrada] Valor #define que identifica la función ODBC de interés; SQL_API_ODBC3_ALL_FUNCTIONS orSQL_API_ALL_FUNCTIONS. SQL_API_ODBC3_ALL_FUNCTIONS usa una aplicación ODBC 3*.x* para determinar la compatibilidad de ODBC 3*.x* y funciones anteriores. SQL_API_ALL_FUNCTIONS usa una aplicación ODBC 2*.x* para determinar la compatibilidad con ODBC 2*.x* y las funciones anteriores.

Para obtener una lista de #define valores que identifican las funciones ODBC, consulte las tablas en "Comentarios".

SupportedPtr
[Salida] Si FunctionId identifica una sola función ODBC, SupportedPtr apunta a un único valor SQLUSMALLINT que se SQL_TRUE si el controlador admite la función especificada y SQL_FALSE si no se admite.

Si FunctionId es SQL_API_ODBC3_ALL_FUNCTIONS, SupportedPtr apunta a una matriz SQLSMALLINT con un número de elementos iguales a SQL_API_ODBC3_ALL_FUNCTIONS_SIZE. El Administrador de controladores trata esta matriz como un mapa de bits de 4000 bits que se puede usar para determinar si se admite una función ODBC 3*.x* o anterior. Se llama a la macro SQL_FUNC_EXISTS para determinar la compatibilidad de funciones. (Vea "Comments.") Una aplicación ODBC 3*.x* puede llamar a SQLGetFunctions con SQL_API_ODBC3_ALL_FUNCTIONS en un controlador ODBC 3*.x* o ODBC 2*.x*.

Si FunctionId es SQL_API_ALL_FUNCTIONS, SupportedPtr apunta a una matriz SQLUSMALLINT de 100 elementos. La matriz se indexa mediante #define valores utilizados por FunctionId para identificar cada función ODBC; Algunos elementos de la matriz no se usan y se reservan para su uso futuro. Un elemento se SQL_TRUE si identifica una función ODBC 2*.x* o anterior compatible con el controlador. Es SQL_FALSE si identifica una función ODBC no compatible con el controlador o no identifica una función ODBC.

Las matrices devueltas en *SupportedPtr usan la indexación basada en cero.

Devoluciones

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR o SQL_INVALID_HANDLE.

Diagnóstico

Cuando SQLGetFunctions devuelve SQL_ERROR o SQL_SUCCESS_WITH_INFO, se puede obtener un valor SQLSTATE asociado llamando a SQLGetDiagRec con un HandleType de SQL_HANDLE_DBC y un identificador de ConnectionHandle. En la tabla siguiente se enumeran los valores SQLSTATE devueltos normalmente por SQLGetFunctions y se explica cada uno en el contexto de esta función; la notación "(DM)" precede a las descripciones de SQLSTATEs devueltas por el Administrador de controladores. El código de retorno asociado a cada valor SQLSTATE es SQL_ERROR, a menos que se indique lo contrario.

Comentarios

SQLGetFunctions siempre devuelve que se admiten SQLGetFunctions, SQLDataSources y SQLDrivers . Esto se debe a que estas funciones se implementan en el Administrador de controladores. El Administrador de controladores asignará una función ANSI a la función Unicode correspondiente si existe la función Unicode y asignará una función Unicode a la función ANSI correspondiente si existe la función ANSI. Para obtener información sobre cómo las aplicaciones usan SQLGetFunctions, vea Niveles de conformidad de interfaz.

A continuación se muestra una lista de valores válidos para FunctionId para funciones que cumplen con el nivel de cumplimiento de estándares ISO 92:

A continuación se muestra una lista de valores válidos para FunctionId para las funciones conformes al nivel de cumplimiento de estándares de Open Group:

A continuación se muestra una lista de valores válidos para FunctionId para funciones conformes al nivel de cumplimiento de estándares ODBC.

[1] Cuando se trabaja con un controlador ODBC 2*.x*, SQLBulkOperations se devolverá como compatible solo si ambos de los siguientes son true: el controlador ODBC 2*.x* admite SQLSetPos y el tipo de información SQL_POS_OPERATIONS devuelve el bit de SQL_POS_ADD establecido.

A continuación se muestra una lista de valores válidos para FunctionId para las funciones introducidas en ODBC 3.8 o posterior:

[2] SQLCancelHandle se devolverá como compatible solo si el controlador admite SQLCancel y SQLCancelHandle. Si se admite SQLCancel pero SQLCancelHandle no es así, la aplicación todavía puede llamar a SQLCancelHandle en un identificador de instrucción, ya que se asignará a SQLCancel.

SQL_FUNC_EXISTS Macro

La macro SQL_FUNC_EXISTS(SupportedPtr, FunctionID) se usa para determinar la compatibilidad de ODBC 3*.x* o funciones anteriores después de llamar a SQLGetFunctions con un argumento FunctionId de SQL_API_ODBC3_ALL_FUNCTIONS. La aplicación llama a SQL_FUNC_EXISTS con el argumento SupportedPtr establecido en supportedPtr pasado en SQLGetFunctions y con el argumento FunctionID establecido en el #define de la función. SQL_FUNC_EXISTS devuelve SQL_TRUE si se admite la función y SQL_FALSE de lo contrario.

Ejemplo de código

En los tres ejemplos siguientes se muestra cómo una aplicación usa SQLGetFunctions para determinar si un controlador admite SQLTables, SQLColumns y SQLStatistics. Si el controlador no admite estas funciones, la aplicación se desconecta del controlador. En el primer ejemplo se llama a SQLGetFunctions una vez para cada función.

SQLUSMALLINT TablesExists, ColumnsExists, StatisticsExists;  
RETCODE retcodeTables, retcodeColumns, retcodeStatistics  
  
retcodeTables = SQLGetFunctions(hdbc, SQL_API_SQLTABLES, &TablesExists);  
retcodeColumns = SQLGetFunctions(hdbc, SQL_API_SQLCOLUMNS, &ColumnsExists);  
retcodeStatistics = SQLGetFunctions(hdbc, SQL_API_SQLSTATISTICS, &StatisticsExists);  
  
// SQLGetFunctions is completed successfully and SQLTables, SQLColumns, and SQLStatistics are supported by the driver.  
if (retcodeTables == SQL_SUCCESS && TablesExists == SQL_TRUE &&   
retcodeColumns == SQL_SUCCESS && ColumnsExists == SQL_TRUE &&   
retcodeStatistics == SQL_SUCCESS && StatisticsExists == SQL_TRUE)   
{  
  
   // Continue with application  
  
}  
  
SQLDisconnect(hdbc);  

En el segundo ejemplo, una aplicación ODBC 3.x llama a SQLGetFunctions y la pasa una matriz en la que SQLGetFunctions devuelve información sobre todas las funciones ODBC 3.x y anteriores.

RETCODE retcodeTables, retcodeColumns, retcodeStatistics  
SQLUSMALLINT fExists[SQL_API_ODBC3_ALL_FUNCTIONS_SIZE];  
  
retcode = SQLGetFunctions(hdbc, SQL_API_ODBC3_ALL_FUNCTIONS, fExists);  
  
// SQLGetFunctions is completed successfully and SQLTables, SQLColumns, and SQLStatistics are supported by the driver.  
if (reccode == SQL_SUCCESS &&   
SQL_FUNC_EXISTS(fExists, SQL_API_SQLTABLES) == SQL_TRUE &&  
   SQL_FUNC_EXISTS(fExists, SQL_API_SQLCOLUMNS) == SQL_TRUE &&  
   SQL_FUNC_EXISTS(fExists, SQL_API_SQLSTATISTICS) == SQL_TRUE)   
{  
  
   // Continue with application  
  
}  
  
SQLDisconnect(hdbc);  

El tercer ejemplo es una aplicación ODBC 2.x llama a SQLGetFunctions y la pasa una matriz de 100 elementos en los que SQLGetFunctions devuelve información sobre todas las funciones ODBC 2.x y anteriores.

#define FUNCTIONS 100  
  
RETCODE retcodeTables, retcodeColumns, retcodeStatistics  
SQLUSMALLINT fExists[FUNCTIONS];  
  
retcode = SQLGetFunctions(hdbc, SQL_API_ALL_FUNCTIONS, fExists);  
  
/* SQLGetFunctions is completed successfully and SQLTables, SQLColumns, and SQLStatistics are supported by the driver. */  
if (retcode == SQL_SUCCESS &&   
fExists[SQL_API_SQLTABLES] == SQL_TRUE &&  
   fExists[SQL_API_SQLCOLUMNS] == SQL_TRUE &&  
   fExists[SQL_API_SQLSTATISTICS] == SQL_TRUE)   
{  
  
   /* Continue with application */  
  
}  
  
SQLDisconnect(hdbc);  

Funciones relacionadas

Consulte también

Referencia de API ODBC
Archivos de encabezado de ODBC