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);
Funciones relacionadas
| 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 |