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.

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

Consulte también

Referencia de API ODBC
Archivos de encabezado de ODBC