Función SQLProcedureColumns
Conformidad
Versión introducida: Cumplimiento de estándares odbc 1.0: ODBC
Resumen
SQLProcedureColumns devuelve la lista de parámetros de entrada y salida, así como las columnas que componen el conjunto de resultados para los procedimientos especificados. El controlador devuelve la información como un conjunto de resultados en la instrucción especificada.
Sintaxis
SQLRETURN SQLProcedureColumns(
SQLHSTMT StatementHandle,
SQLCHAR * CatalogName,
SQLSMALLINT NameLength1,
SQLCHAR * SchemaName,
SQLSMALLINT NameLength2,
SQLCHAR * ProcName,
SQLSMALLINT NameLength3,
SQLCHAR * ColumnName,
SQLSMALLINT NameLength4);
Argumentos
StatementHandle
[Entrada] Identificador de instrucción.
CatalogName
[Entrada] Nombre del catálogo de procedimientos. Si un controlador admite catálogos para algunos procedimientos, pero no para otros, como cuando el controlador recupera datos de diferentes DBMS, una cadena vacía ("") denota los procedimientos que no tienen catálogos. CatalogName no puede contener un patrón de búsqueda de cadenas.
Si el atributo de instrucción SQL_ATTR_METADATA_ID se establece en SQL_TRUE, CatalogName se trata como un identificador y su caso no es significativo. Si es SQL_FALSE, CatalogName es un argumento normal; se trata literalmente y su caso es significativo. Para obtener más información, vea Argumentos en funciones de catálogo.
NameLength1
[Entrada] Longitud en caracteres de *CatalogName.
SchemaName
[Entrada] Patrón de búsqueda de cadenas para los nombres de esquema de procedimiento. Si un controlador admite esquemas para algunos procedimientos, pero no para otros, como cuando el controlador recupera datos de diferentes DBMS, una cadena vacía ("") denota esos procedimientos que no tienen esquemas.
Si el atributo de instrucción SQL_ATTR_METADATA_ID se establece en SQL_TRUE, SchemaName se trata como un identificador y su caso no es significativo. Si es SQL_FALSE, SchemaName es un argumento de valor de patrón; se trata literalmente y su caso es significativo.
NameLength2
[Entrada] Longitud en caracteres de *SchemaName.
ProcName
[Entrada] Patrón de búsqueda de cadenas para los nombres de procedimiento.
Si el atributo de instrucción SQL_ATTR_METADATA_ID se establece en SQL_TRUE, ProcName se trata como un identificador y su caso no es significativo. Si es SQL_FALSE, ProcName es un argumento de valor de patrón; se trata literalmente y su caso es significativo.
NameLength3
[Entrada] Longitud en caracteres de *ProcName.
ColumnName
[Entrada] Patrón de búsqueda de cadenas para los nombres de columna.
Si el atributo de instrucción SQL_ATTR_METADATA_ID se establece en SQL_TRUE, ColumnName se trata como un identificador y su caso no es significativo. Si es SQL_FALSE, ColumnName es un argumento de valor de patrón; se trata literalmente y su caso es significativo.
NameLength4
[Entrada] Longitud en caracteres de *ColumnName.
Devoluciones
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR o SQL_INVALID_HANDLE.
Diagnóstico
Cuando SQLProcedureColumns devuelve SQL_ERROR o SQL_SUCCESS_WITH_INFO, se puede obtener un valor SQLSTATE asociado llamando a SQLGetDiagRec con un HandleType de SQL_HANDLE_STMT y un identificador de StatementHandle. En la tabla siguiente se enumeran los valores SQLSTATE devueltos normalmente por SQLProcedureColumns 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. |
| 24000 | Estado de cursor no válido | Se ha abierto un cursor en StatementHandle y se ha llamado a SQLFetch o SQLFetchScroll . El Administrador de controladores devuelve este error si SQLFetch o SQLFetchScroll no ha devuelto SQL_NO_DATA y el controlador devuelve si SQLFetch o SQLFetchScroll ha devuelto SQL_NO_DATA. Se ha abierto un cursor en StatementHandle, pero no se ha llamado a SQLFetch o SQLFetchScroll . |
| 40001 | Error de serialización | La transacción se revierte debido a un interbloqueo de recursos con otra transacción. |
| 40003 | Finalización de instrucciones desconocida | Error en la conexión asociada durante la ejecución de esta función y no se puede determinar el estado de la transacción. |
| 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 SQLError 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. |
| HY008 | Operación cancelada | El procesamiento asincrónico se ha habilitado para StatementHandle. Se llamó a la función y antes de completar la ejecución, se llamó a SQLCancel o SQLCancelHandle en statementHandle. A continuación, se llamó a la función de nuevo en StatementHandle. Se llamó a la función y antes de completar la ejecución, se llamó a SQLCancel o SQLCancelHandle en statementHandle desde un subproceso diferente en una aplicación multiproceso. |
| HY009 | Uso no válido del puntero nulo | El atributo de instrucción SQL_ATTR_METADATA_ID se estableció en SQL_TRUE, el argumento CatalogName era un puntero nulo y el SQL_CATALOG_NAME InfoType devuelve que se admiten nombres de catálogo. (DM) El atributo de instrucción SQL_ATTR_METADATA_ID se estableció en SQL_TRUE, y el argumento SchemaName, ProcName o ColumnName era un puntero nulo. |
| HY010 | Error de secuencia de función | (DM) Se llamó a una función de ejecución asincrónica para el identificador de conexión asociado a StatementHandle. Esta función aynschronous todavía se estaba ejecutando cuando se llamó a la función SQLProcedureColumns. (DM) SE llamó a SQLExecute, SQLExecDirect o SQLMoreResults para la instrucciónHandle y devolvió SQL_PARAM_DATA_AVAILABLE. Se llamó a esta función antes de recuperar los datos para todos los parámetros transmitidos. (DM) Se llamó a una función de ejecución asincrónica (no esta) para statementHandle y todavía se estaba ejecutando cuando se llamó a esta función. (DM) SE llamó a SQLExecute, SQLExecDirect, SQLBulkOperations o SQLSetPos para la instrucciónHandle y devolvió SQL_NEED_DATA. Se llamó a esta función antes de enviar datos para todos los parámetros o columnas de datos en ejecución. |
| HY090 | Longitud de búfer o cadena no válida | (DM) El valor de uno de los argumentos de longitud de nombre era menor que 0, pero no igual a SQL_NTS. El valor de uno de los argumentos de longitud de nombre superó el valor de longitud máxima para el nombre de columna, el esquema, el esquema o el catálogo correspondientes. |
| 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. |
| HYC00 | Característica opcional no implementada | Se especificó un catálogo de procedimientos y el controlador o el origen de datos no admite catálogos. Se especificó un esquema de procedimiento y el controlador o el origen de datos no admite esquemas. Se especificó un patrón de búsqueda de cadenas para el esquema de procedimiento, el nombre del procedimiento o el nombre de columna, y el origen de datos no admite patrones de búsqueda para uno o varios de esos argumentos. La combinación de la configuración actual del SQL_ATTR_CONCURRENCY y los atributos de instrucción SQL_ATTR_CURSOR_TYPE no se admiten en el controlador o el origen de datos. El atributo de instrucción SQL_ATTR_USE_BOOKMARKS se estableció en SQL_UB_VARIABLE y el atributo de instrucción SQL_ATTR_CURSOR_TYPE se estableció en un tipo de cursor para el que el controlador no admite marcadores. |
| HYT00 | Tiempo de espera agotado | El período de tiempo de espera expirado antes de que el origen de datos devuelva el conjunto de resultados. El período de tiempo de espera se establece a través de SQLSetStmtAttr, SQL_ATTR_QUERY_TIMEOUT. |
| 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. |
| IM001 | El controlador no admite esta función | (DM) El controlador asociado a StatementHandle no admite la función . |
| IM017 | El sondeo está deshabilitado en modo de notificación asincrónica | Cada vez que se usa el modelo de notificación, el sondeo está deshabilitado. |
| IM018 | No se ha llamado a SQLCompleteAsync para completar la operación asincrónica anterior en este identificador. | Si la llamada de función anterior en el identificador devuelve SQL_STILL_EXECUTING y si el modo de notificación está habilitado, se debe llamar a SQLCompleteAsync en el identificador para realizar el procesamiento posterior y completar la operación. |
Comentarios
Esta función se usa normalmente antes de la ejecución de instrucciones para recuperar información sobre los parámetros del procedimiento y las columnas que componen el conjunto de resultados o conjuntos devueltos por el procedimiento, si los hay. Para más información, vea Procedimientos en Visual Basic.
Nota
SQLProcedureColumns podría no devolver todas las columnas usadas por un procedimiento. Por ejemplo, un controlador podría devolver solo información sobre los parámetros usados por un procedimiento y no las columnas de un conjunto de resultados que genera.
Los argumentos SchemaName, ProcName y ColumnName aceptan patrones de búsqueda. Para obtener más información sobre los patrones de búsqueda válidos, vea Argumentos de valor de patrón.
Nota
Para obtener más información sobre el uso general, los argumentos y los datos devueltos de las funciones de catálogo ODBC, vea Funciones de catálogo.
SQLProcedureColumns devuelve los resultados como un conjunto de resultados estándar, ordenado por PROCEDURE_CAT, PROCEDURE_SCHEM, PROCEDURE_NAME y COLUMN_TYPE. Los nombres de columna se devuelven para cada procedimiento en el orden siguiente: el nombre del valor devuelto, los nombres de cada parámetro de la invocación de procedimiento (en orden de llamada) y, a continuación, los nombres de cada columna del conjunto de resultados devuelto por el procedimiento (en orden de columna).
Las aplicaciones deben enlazar columnas específicas del controlador con respecto al final del conjunto de resultados. Para obtener más información, vea Datos devueltos por funciones de catálogo.
Para determinar las longitudes reales de las columnas PROCEDURE_CAT, PROCEDURE_SCHEM, PROCEDURE_NAME y COLUMN_NAME, una aplicación puede llamar a SQLGetInfo con las opciones SQL_MAX_CATALOG_NAME_LEN, SQL_MAX_SCHEMA_NAME_LEN, SQL_MAX_PROCEDURE_NAME_LEN y SQL_MAX_COLUMN_NAME_LEN.
Se ha cambiado el nombre de las columnas siguientes para ODBC 3. x. Los cambios en el nombre de columna no afectan a la compatibilidad con versiones anteriores porque las aplicaciones se enlazan por número de columna.
| Columna ODBC 2.0 | ODBC 3. columna x |
|---|---|
| PROCEDURE_QUALIFIER | PROCEDURE_CAT |
| _OWNER PROCEDURE | PROCEDURE_SCHEM |
| PRECISION | COLUMN_SIZE |
| LENGTH | BUFFER_LENGTH |
| SCALE | DECIMAL_DIGITS |
| RADIX | NUM_PREC_RADIX |
Las columnas siguientes se han agregado al conjunto de resultados devuelto por SQLProcedureColumns para ODBC 3. x:
COLUMN_DEF
DATETIME_CODE
CHAR_OCTET_LENGTH
ORDINAL_POSITION
IS_NULLABLE
En la tabla siguiente se enumeran las columnas del conjunto de resultados. El controlador puede definir columnas adicionales más allá de la columna 19 (IS_NULLABLE). Una aplicación debe obtener acceso a columnas específicas del controlador contando desde el final del conjunto de resultados en lugar de especificar una posición ordinal explícita. Para obtener más información, vea Datos devueltos por funciones de catálogo.
| Nombre de la columna | Número de columna | Tipo de datos | Comentarios |
|---|---|---|---|
| PROCEDURE_CAT (ODBC 2.0) | 1 | Varchar | Nombre del catálogo de procedimientos; NULL si no es aplicable al origen de datos. Si un controlador admite catálogos para algunos procedimientos, pero no para otros, como cuando el controlador recupera datos de diferentes DBMS, devuelve una cadena vacía ("") para los procedimientos que no tienen catálogos. |
| PROCEDURE_SCHEM (ODBC 2.0) | 2 | Varchar | Nombre del esquema del procedimiento; NULL si no es aplicable al origen de datos. Si un controlador admite esquemas para algunos procedimientos, pero no para otros, como cuando el controlador recupera datos de diferentes DBMS, devuelve una cadena vacía ("") para los procedimientos que no tienen esquemas. |
| PROCEDURE_NAME (ODBC 2.0) | 3 | Varchar no NULL | Nombre del procedimiento. Se devuelve una cadena vacía para un procedimiento que no tiene un nombre. |
| COLUMN_NAME (ODBC 2.0) | 4 | Varchar no NULL | Nombre de columna de procedimiento. El controlador devuelve una cadena vacía para una columna de procedimiento que no tiene un nombre. |
| COLUMN_TYPE (ODBC 2.0) | 5 | Smallint no NULL | Define la columna de procedimiento como un parámetro o una columna del conjunto de resultados: SQL_PARAM_TYPE_UNKNOWN: la columna de procedimiento es un parámetro cuyo tipo es desconocido. (ODBC 1.0) SQL_PARAM_INPUT: la columna de procedimiento es un parámetro de entrada. (ODBC 1.0) SQL_PARAM_INPUT_OUTPUT: la columna de procedimiento es un parámetro de entrada y salida. (ODBC 1.0) SQL_PARAM_OUTPUT: la columna de procedimiento es un parámetro de salida. (ODBC 2.0) SQL_RETURN_VALUE: la columna de procedimiento es el valor devuelto del procedimiento. (ODBC 2.0) SQL_RESULT_COL: la columna de procedimiento es una columna de conjunto de resultados. (ODBC 1.0) |
| DATA_TYPE (ODBC 2.0) | 6 | Smallint no NULL | Tipo de datos SQL. Puede ser un tipo de datos SQL ODBC o un tipo de datos SQL específico del controlador. Para los tipos de datos datetime e interval, esta columna devuelve los tipos de datos concisos (por ejemplo, SQL_TYPE_TIME o SQL_INTERVAL_YEAR_TO_MONTH). Para obtener una lista de los tipos de datos DE SQL ODBC válidos, vea Tipos de datos SQL en el Apéndice D: Tipos de datos. Para información sobre los tipos de datos SQL específicos del controlador, consulte la documentación del controlador. |
| TYPE_NAME (ODBC 2.0) | 7 | Varchar no NULL | Nombre del tipo de datos dependiente del origen de datos; por ejemplo, "CHAR", "VARCHAR", "MONEY", "LONG VARBINARY" o "CHAR ( ) FOR BIT DATA". |
| COLUMN_SIZE (ODBC 2.0) | 8 | Entero | Tamaño de columna de la columna de procedimiento en el origen de datos. Se devuelve NULL para los tipos de datos en los que el tamaño de columna no es aplicable. Para obtener más información sobre la precisión, vea Tamaño de columna, Dígitos decimales, Longitud del octeto de transferencia y Tamaño de presentación en el Apéndice D: Tipos de datos. |
| BUFFER_LENGTH (ODBC 2.0) | 9 | Entero | Longitud en bytes de datos transferidos en una operación SQLGetData o SQLFetch si se especifica SQL_C_DEFAULT. Para los datos numéricos, este tamaño puede ser diferente del tamaño de los datos almacenados en el origen de datos. Para obtener más información, vea Tamaño de columna, Dígitos decimales, Longitud del octeto de transferencia y Tamaño de presentación, en apéndice D: Tipos de datos. |
| DECIMAL_DIGITS (ODBC 2.0) | 10 | Smallint | Dígitos decimales de la columna de procedimiento en el origen de datos. Se devuelve NULL para los tipos de datos en los que los dígitos decimales no son aplicables. Para obtener más información sobre los dígitos decimales, vea Tamaño de columna, Dígitos decimales, Longitud del octeto de transferencia y Tamaño de presentación, en el Apéndice D: Tipos de datos. |
| NUM_PREC_RADIX (ODBC 2.0) | 11 | Smallint | Para los tipos de datos numéricos, ya sea 10 o 2. Si es 10, los valores de COLUMN_SIZE y DECIMAL_DIGITS proporcionan el número de dígitos decimales permitidos para la columna. Por ejemplo, una columna DECIMAL(12,5) devolvería un NUM_PREC_RADIX de 10, un COLUMN_SIZE de 12 y un DECIMAL_DIGITS de 5; Una columna FLOAT podría devolver un NUM_PREC_RADIX de 10, un COLUMN_SIZE de 15 y un DECIMAL_DIGITS de NULL. Si es 2, los valores de COLUMN_SIZE y DECIMAL_DIGITS proporcionen el número de bits permitidos en la columna. Por ejemplo, una columna FLOAT podría devolver un NUM_PREC_RADIX de 2, un COLUMN_SIZE de 53 y un DECIMAL_DIGITS de NULL. Se devuelve NULL para los tipos de datos en los que no se aplica NUM_PREC_RADIX. |
| NULLABLE (ODBC 2.0) | 12 | Smallint no NULL | Si la columna de procedimiento acepta un valor NULL: SQL_NO_NULLS: la columna de procedimiento no acepta valores NULL. SQL_NULLABLE: la columna de procedimiento acepta valores NULL. SQL_NULLABLE_UNKNOWN: no se sabe si la columna del procedimiento acepta valores NULL. |
| COMENTARIOS (ODBC 2.0) | 13 | Varchar | Descripción de la columna de procedimiento. |
| COLUMN_DEF (ODBC 3.0) | 14 | Varchar | Valor predeterminado de la columna. Si se especificó NULL como valor predeterminado, esta columna es la palabra NULL, no entre comillas. Si el valor predeterminado no se puede representar sin truncamiento, esta columna contiene TRUNCATED, sin comillas simples envolventes. Si no se especificó ningún valor predeterminado, esta columna es NULL. El valor de COLUMN_DEF se puede usar para generar una nueva definición de columna, excepto cuando contiene el valor TRUNCATED. |
| SQL_DATA_TYPE (ODBC 3.0) | 15 | Smallint no NULL | Valor del tipo de datos SQL tal y como aparece en el campo SQL_DESC_TYPE del descriptor. Esta columna es la misma que la columna DATA_TYPE, excepto para los tipos de datos datetime e interval. Para los tipos de datos datetime e interval, el campo SQL_DATA_TYPE del conjunto de resultados devolverá SQL_INTERVAL o SQL_DATETIME, y el campo SQL_DATETIME_SUB devolverá el subcódigo para el tipo de datos datetime o intervalo específico. (Consulte el Apéndice D: Tipos de datos). |
| SQL_DATETIME_SUB (ODBC 3.0) | 16 | Smallint | El código de subtipo para los tipos de datos datetime e interval. Para otros tipos de datos, esta columna devuelve un valor NULL. |
| CHAR_OCTET_LENGTH (ODBC 3.0) | 17 | Entero | Longitud máxima en bytes de una columna de tipo de datos binario o carácter. Para todos los demás tipos de datos, esta columna devuelve NULL. |
| ORDINAL_POSITION (ODBC 3.0) | 18 | Integer no NULL | En el caso de los parámetros de entrada y salida, la posición ordinal del parámetro en la definición del procedimiento (en orden de aumento de parámetros, a partir de 1). Para un valor devuelto (si existe), se devuelve 0. Para las columnas del conjunto de resultados, la posición ordinal de la columna en el conjunto de resultados, con la primera columna del conjunto de resultados siendo el número 1. Si hay varios conjuntos de resultados, las posiciones ordinales de columna se devuelven de forma específica del controlador. |
| IS_NULLABLE (ODBC 3.0) | 19 | Varchar | "NO" si la columna no incluye valores NULL. "Sí" si la columna puede incluir valores NULL. Esta columna devuelve una cadena de longitud cero si no se conoce la nulabilidad. Se siguen las normas ISO para determinar la nulabilidad. Un DBMS que cumpla la norma ISO SQL no puede devolver una cadena vacía. El valor devuelto para esta columna es diferente del valor devuelto para la columna NULLABLE. (Vea la descripción de la columna NULLABLE). |
Ejemplo de código
Consulte Llamadas a procedimiento.
Funciones relacionadas
| Para información acerca de | Vea |
|---|---|
| Enlace de un búfer a una columna de un conjunto de resultados | SQLBindCol (función) |
| Cancelación del procesamiento de instrucciones | Función SQLCancel |
| Capturar una sola fila o un bloque de datos en una dirección de solo avance | Función SQLFetch |
| Capturar un bloque de datos o desplazarse por un conjunto de resultados | Función SQLFetchScroll |
| Devolver una lista de procedimientos en un origen de datos | Función SQLProcedures |