Función SQLDescribeParam

  • Artículo

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 instrucción.

ParameterNumber
[Entrada] Número de marcador de parámetro ordenado secuencialmente en orden creciente de parámetros, empezando por 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 desde el campo de registro SQL_DESC_CONCISE_TYPE del IPD. Se trata de 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. x driver o when an ODBC 3. La aplicación x funciona con ODBC 2. controlador x .

Cuando ColumnNumber es igual a 0 (para una columna de marcador), SQL_BINARY se devuelve en *DataTypePtr para marcadores de longitud variable. (SQL_INTEGER se devuelve si 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. controlador x ).

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 según lo definido por 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 presentació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 según lo definido por el origen de datos. 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.

NullablePtr
[Salida] Puntero a un búfer en el que se va a devolver un valor que indica si el parámetro permite valores NULL. Este valor se lee desde el 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ámetro formaba parte de una instrucción que no es 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 Insertar lista de valores 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 función (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 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 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 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 responda 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, empezando por 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 de 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 los parámetros 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 an 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);
Para información acerca de 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

Consulte también

Referencia de API ODBC
Archivos de encabezado de ODBC