Función SQLDescribeParam
Conformidad
Versión introducida: Cumplimiento de estándares ODBC 1.0: ODBC
Resumen
SQLDescribeParam devuelve la descripción de un marcador de parámetro asociado a una instrucción SQL preparada. Esta información también está disponible en los campos del IPD.
Sintaxis
SQLRETURN SQLDescribeParam(
SQLHSTMT StatementHandle,
SQLUSMALLINT ParameterNumber,
SQLSMALLINT * DataTypePtr,
SQLULEN * ParameterSizePtr,
SQLSMALLINT * DecimalDigitsPtr,
SQLSMALLINT * NullablePtr);
Argumentos
StatementHandle
[Entrada] Identificador de instrucciones.
ParameterNumber
[Entrada] Número de marcador de parámetro ordenado secuencialmente en orden de aumento de parámetros, a partir de 1.
DataTypePtr
[Salida] Puntero a un búfer en el que se va a devolver el tipo de datos SQL del parámetro. Este valor se lee del campo de registro SQL_DESC_CONCISE_TYPE del IPD. Este será uno de los valores de la sección Tipos de datos SQL del Apéndice D: Tipos de datos o un tipo de datos SQL específico del controlador.
En ODBC 3.x, SQL_TYPE_DATE, SQL_TYPE_TIME o SQL_TYPE_TIMESTAMP se devolverán en *DataTypePtr para los datos de fecha, hora o marca de tiempo, respectivamente; en ODBC 2.Se devolverá x, SQL_DATE, SQL_TIME o SQL_TIMESTAMP. El Administrador de controladores realiza las asignaciones necesarias cuando odbc 2.La aplicación x funciona con ODBC 3.Controlador x o cuando un ODBC 3.La aplicación x funciona con ODBC 2.x driver.
Cuando ColumnNumber es igual a 0 (para una columna de marcador), se devuelve SQL_BINARY en *DataTypePtr para los marcadores de longitud variable. (SQL_INTEGER se devuelve si un ODBC 3 usa marcadores.x aplicación que funciona con ODBC 2.Controlador x o mediante ODBC 2.x aplicación que funciona con ODBC 3.x driver.)
Para obtener más información, 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.
ParameterSizePtr
[Salida] Puntero a un búfer en el que se va a devolver el tamaño, en caracteres, de la columna o expresión del marcador de parámetro correspondiente, tal como se define en el origen de datos. Para obtener más información sobre el tamaño de columna, vea Tamaño de columna, Dígitos decimales, Longitud del octeto de transferencia y Tamaño de visualización.
DecimalDigitsPtr
[Salida] Puntero a un búfer en el que se va a devolver el número de dígitos decimales de la columna o expresión del parámetro correspondiente tal como se define en el origen de datos. Para obtener más información sobre los dígitos decimales, vea Tamaño de columna, Dígitos decimales, Longitud de octeto de transferencia y Tamaño de visualización.
NullablePtr
[Salida] Puntero a un búfer en el que se devuelve un valor que indica si el parámetro permite valores NULL. Este valor se lee del campo SQL_DESC_NULLABLE del IPD. Uno de los siguientes:
SQL_NO_NULLS: el parámetro no permite valores NULL (este es el valor predeterminado).
SQL_NULLABLE: el parámetro permite valores NULL.
SQL_NULLABLE_UNKNOWN: el controlador no puede determinar si el parámetro permite valores NULL.
Devoluciones
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR o SQL_INVALID_HANDLE.
Diagnóstico
Cuando SQLDescribeParam 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 SQLDescribeParam 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). |
| 07009 | Índice de descriptor no válido | (DM) El valor especificado para el argumento ParameterNumber es menor que 1. El valor especificado para el argumento ParameterNumber era mayor que el número de parámetros de la instrucción SQL asociada. El marcador de parámetros formaba parte de una instrucción no DML. El marcador de parámetros formaba parte de una lista SELECT . |
| 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. |
| 21S01 | La lista de valores de inserción no coincide con la lista de columnas | El número de parámetros de la instrucción INSERT no coincide con el número de columnas de la tabla denominada en la instrucció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 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. |
| 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. |
| HY010 | Error de secuencia de funciones | (DM) Se llamó a la función antes de llamar a SQLPrepare o SQLExecDirect para StatementHandle. (DM) Se llamó a una función de ejecución asincrónica para el identificador de conexión asociado a StatementHandle. Esta función asincrónica todavía se estaba ejecutando cuando se llamó a la función SQLDescribeParam . (DM) Se llamó a una función que ejecuta de forma 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 el statementHandle 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. |
| HY013 | Error de administración de memoria | No se pudo procesar la llamada de función porque no se pudo tener acceso a los objetos de memoria subyacentes, posiblemente debido a condiciones de memoria baja. |
| HY117 | La conexión se suspende debido al estado de transacción desconocido. Solo se permiten las funciones de desconexión y 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. |
| 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
Los marcadores de parámetro se numeran en orden creciente de parámetros, a partir de 1, en el orden en que aparecen en la instrucción SQL.
SQLDescribeParam no devuelve el tipo (entrada, entrada/salida o salida) de un parámetro en una instrucción SQL. Excepto en las llamadas a procedimientos, todos los parámetros de las instrucciones SQL son parámetros de entrada. Para determinar el tipo de cada parámetro en una llamada a un procedimiento, una aplicación llama a SQLProcedureColumns.
Para obtener más información, consulte Descripción de parámetros.
Ejemplo de código
En el ejemplo siguiente se solicita al usuario una instrucción SQL y, a continuación, se prepara esa instrucción. A continuación, llama a SQLNumParams para determinar si la instrucción contiene parámetros. Si la instrucción contiene parámetros, llama a SQLDescribeParam para describir esos parámetros y SQLBindParameter para enlazarlos. Por último, solicita al usuario los valores de cualquier parámetro y, a continuación, ejecuta la instrucción .
SQLCHAR Statement[100];
SQLSMALLINT NumParams, i, DataType, DecimalDigits, Nullable;
SQLUINTEGER ParamSize;
SQLHSTMT hstmt;
// Prompt the user for a SQL statement and prepare it.
GetSQLStatement(Statement);
SQLPrepare(hstmt, Statement, SQL_NTS);
// Check to see if there are any parameters. If so, process them.
SQLNumParams(hstmt, &NumParams);
if (NumParams) {
// Allocate memory for three arrays. The first holds pointers to buffers in which
// each parameter value will be stored in character form. The second contains the
// length of each buffer. The third contains the length/indicator value for each
// parameter.
SQLPOINTER * PtrArray = (SQLPOINTER *) malloc(NumParams * sizeof(SQLPOINTER));
SQLINTEGER * BufferLenArray = (SQLINTEGER *) malloc(NumParams * sizeof(SQLINTEGER));
SQLINTEGER * LenOrIndArray = (SQLINTEGER *) malloc(NumParams * sizeof(SQLINTEGER));
for (i = 0; i < NumParams; i++) {
// Describe the parameter.
SQLDescribeParam(hstmt, i + 1, &DataType, &ParamSize, &DecimalDigits, &Nullable);
// Call a helper function to allocate a buffer in which to store the parameter
// value in character form. The function determines the size of the buffer from
// the SQL data type and parameter size returned by SQLDescribeParam and returns
// a pointer to the buffer and the length of the buffer.
AllocParamBuffer(DataType, ParamSize, &PtrArray[i], &BufferLenArray[i]);
// Bind the memory to the parameter. Assume that we only have input parameters.
SQLBindParameter(hstmt, i + 1, SQL_PARAM_INPUT, SQL_C_CHAR, DataType, ParamSize,
DecimalDigits, PtrArray[i], BufferLenArray[i],
&LenOrIndArray[i]);
// Prompt the user for the value of the parameter and store it in the memory
// allocated earlier. For simplicity, this function does not check the value
// against the information returned by SQLDescribeParam. Instead, the driver does
// this when the statement is executed.
GetParamValue(PtrArray[i], BufferLenArray[i], &LenOrIndArray[i]);
}
}
// Execute the statement.
SQLExecute(hstmt);
// Process the statement further, such as retrieving results (if any) and closing the
// cursor (if any). Code not shown.
// Free the memory allocated for each parameter and the memory allocated for the arrays
// of pointers, buffer lengths, and length/indicator values.
for (i = 0; i < NumParams; i++) free(PtrArray[i]);
free(PtrArray);
free(BufferLenArray);
free(LenOrIndArray);
Funciones relacionadas
| Para obtener información sobre | Vea |
|---|---|
| Enlace de un búfer a un parámetro | Función SQLBindParameter |
| Cancelación del procesamiento de instrucciones | Función SQLCancel |
| Ejecución de una instrucción SQL preparada | Función SQLExecute |
| Preparación de una instrucción para su ejecución | Función SQLPrepare |