Compartir a través de


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.

SQLSTATE Error Descripción
01000 Advertencia general Mensaje informativo específico del controlador. (Function devuelve SQL_SUCCESS_WITH_INFO).
08S01 Error de vínculo de comunicación Se produjo un error en el vínculo de comunicación entre el controlador y el origen de datos al que se conectó el controlador antes de que la función completara el procesamiento.
HY000 Error general Se produjo un error para el que no había ningún SQLSTATE específico y para el que no se definió SQLSTATE específico de la implementación. El mensaje de error devuelto por SQLGetDiagRec en el búfer *MessageText describe el error y su causa.
HY001 Error de asignación de memoria El controlador no pudo asignar memoria necesaria para admitir la ejecución o finalización de la función.
HY010 Error de secuencia de función Se llamó a SQLGetFunctions antes de SQLConnect, SQLBrowseConnect o SQLDriverConnect.

Se llamó a SQLBrowseConnect (DM) para ConnectionHandle y devolvió SQL_NEED_DATA. Se llamó a esta función antes de que SQLBrowseConnect devolva SQL_SUCCESS_WITH_INFO o SQL_SUCCESS.

(DM) SE llamó a SQLExecute, SQLExecDirect o SQLMoreResults para connectionHandle y devolvió SQL_PARAM_DATA_AVAILABLE. Se llamó a esta función antes de recuperar los datos para todos los parámetros transmitidos.
HY013 Error de administración de memoria No se pudo procesar la llamada de función porque no se pudo acceder a los objetos de memoria subyacentes, posiblemente debido a condiciones de memoria baja.
HY095 Tipo de función fuera del intervalo (DM) Se especificó un valor FunctionId no válido.
HY117 La conexión se suspende debido a un estado de transacción desconocido. Solo se permiten funciones de desconexión y de solo lectura. (DM) Para obtener más información sobre el estado suspendido, vea Función SQLEndTran.
HYT01 Se ha agotado el tiempo de espera de la conexión. El período de tiempo de espera de conexión expiró antes de que el origen de datos respondiera a la solicitud. El período de tiempo de espera de conexión se establece a través de SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT.

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:

Valor de FunctionId Valor de FunctionId
SQL_API_SQLALLOCHANDLE SQL_API_SQLGETDESCFIELD
SQL_API_SQLBINDCOL SQL_API_SQLGETDESCREC
SQL_API_SQLCANCEL SQL_API_SQLGETDIAGFIELD
SQL_API_SQLCLOSECURSOR SQL_API_SQLGETDIAGREC
SQL_API_SQLCOLATTRIBUTE SQL_API_SQLGETENVATTR
SQL_API_SQLCONNECT SQL_API_SQLGETFUNCTIONS
SQL_API_SQLCOPYDESC SQL_API_SQLGETINFO
SQL_API_SQLDATASOURCES SQL_API_SQLGETSTMTATTR
SQL_API_SQLDESCRIBECOL SQL_API_SQLGETTYPEINFO
SQL_API_SQLDISCONNECT SQL_API_SQLNUMRESULTCOLS
SQL_API_SQLDRIVERS SQL_API_SQLPARAMDATA
SQL_API_SQLENDTRAN SQL_API_SQLPREPARE
SQL_API_SQLEXECDIRECT SQL_API_SQLPUTDATA
SQL_API_SQLEXECUTE SQL_API_SQLROWCOUNT
SQL_API_SQLFETCH SQL_API_SQLSETCONNECTATTR
SQL_API_SQLFETCHSCROLL SQL_API_SQLSETCURSORNAME
SQL_API_SQLFREEHANDLE SQL_API_SQLSETDESCFIELD
SQL_API_SQLFREESTMT SQL_API_SQLSETDESCREC
SQL_API_SQLGETCONNECTATTR SQL_API_SQLSETENVATTR
SQL_API_SQLGETCURSORNAME SQL_API_SQLSETSTMTATTR
SQL_API_SQLGETDATA

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:

Valor de FunctionId Valor de FunctionId
SQL_API_SQLCOLUMNS SQL_API_SQLSTATISTICS
SQL_API_SQLSPECIALCOLUMNS SQL_API_SQLTABLES

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

Valor de FunctionId Valor de FunctionId
SQL_API_SQLBINDPARAMETER SQL_API_SQLNATIVESQL
SQL_API_SQLBROWSECONNECT SQL_API_SQLNUMPARAMS
SQL_API_SQLBULKOPERATIONS[1] SQL_API_SQLPRIMARYKEYS
SQL_API_SQLCOLUMNPRIVILEGES SQL_API_SQLPROCEDURECOLUMNS
SQL_API_SQLDESCRIBEPARAM SQL_API_SQLPROCEDURES
SQL_API_SQLDRIVERCONNECT SQL_API_SQLSETPOS
SQL_API_SQLFOREIGNKEYS SQL_API_SQLTABLEPRIVILEGES
SQL_API_SQLMORERESULTS

[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:

Valor de FunctionId
SQL_API_SQLCANCELHANDLE [2]

[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.

Nota

Cuando se trabaja con un controlador ODBC 2*.x*, el Administrador de controladores ODBC 3*.x* devolverá SQL_TRUE para SQLAllocHandle y SQLFreeHandle porque SQLAllocHandle está asignado a SQLAllocEnv, SQLAllocConnect o SQLAllocStmt y porque SQLFreeHandle está asignado a SQLFreeEnv, SQLFreeConnect o SQLFreeStmt. SQLAllocHandle o SQLFreeHandle con un argumento HandleType de SQL_HANDLE_DESC no se admite, sin embargo, aunque se devuelve SQL_TRUE para las funciones, porque no hay ninguna función ODBC 2*.x* a la que asignar en este caso.

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);  
Para información acerca de Vea
Devolver la configuración de un atributo de conexión Función SQLGetConnectAttr
Devolver información sobre un controlador o un origen de datos Función SQLGetInfo
Devolver el valor de un atributo de instrucción Función SQLGetStmtAttr

Consulte también

Referencia de API ODBC
Archivos de encabezado de ODBC