Función SQLSetDescRec

  • Artículo

Conformidad
Versión introducida: Cumplimiento de estándares ODBC 3.0: ISO 92

Resumen
La función SQLSetDescRec establece varios campos descriptores que afectan al tipo de datos y al búfer enlazados a una columna o datos de parámetros.

Sintaxis

  
SQLRETURN SQLSetDescRec(  
      SQLHDESC      DescriptorHandle,  
      SQLSMALLINT   RecNumber,  
      SQLSMALLINT   Type,  
      SQLSMALLINT   SubType,  
      SQLLEN        Length,  
      SQLSMALLINT   Precision,  
      SQLSMALLINT   Scale,  
      SQLPOINTER    DataPtr,  
      SQLLEN *      StringLengthPtr,  
      SQLLEN *      IndicatorPtr);

Argumentos

DescriptorHandle
[Entrada] Identificador de descriptor. No debe ser un identificador IRD.

RecNumber
[Entrada] Indica el registro descriptor que contiene los campos que se van a establecer. Los registros descriptores se numeran a partir de 0, y el número de registro 0 es el registro del marcador. Este argumento debe ser igual o mayor que 0. Si RecNumber es mayor que el valor de SQL_DESC_COUNT, SQL_DESC_COUNTis cambia al valor de RecNumber.

Tipo
[Entrada] Valor en el que se va a establecer el campo SQL_DESC_TYPE para el registro descriptor.

Subtipo
[Entrada] Para los registros cuyo tipo es SQL_DATETIME o SQL_INTERVAL, este es el valor al que se va a establecer el campo SQL_DESC_DATETIME_INTERVAL_CODE.

Longitud
[Entrada] Valor en el que se va a establecer el campo SQL_DESC_OCTET_LENGTH para el registro descriptor.

Precisión
[Entrada] Valor en el que se va a establecer el campo SQL_DESC_PRECISION para el registro descriptor.

Escala
[Entrada] Valor en el que se va a establecer el campo SQL_DESC_SCALE para el registro descriptor.

DataPtr
[Entrada diferida o salida] Valor en el que se va a establecer el campo SQL_DESC_DATA_PTR para el registro descriptor. DataPtr se puede establecer en un puntero nulo.

El argumento DataPtr se puede establecer en un puntero nulo para establecer el campo SQL_DESC_DATA_PTR en un puntero nulo. Si el identificador del argumento DescriptorHandle está asociado a un ARD, desenlace la columna.

StringLengthPtr
[Entrada diferida o salida] Valor en el que se va a establecer el campo SQL_DESC_OCTET_LENGTH_PTR para el registro descriptor. StringLengthPtr se puede establecer en un puntero nulo para establecer el campo SQL_DESC_OCTET_LENGTH_PTR en un puntero nulo.

IndicatorPtr
[Entrada diferida o salida] Valor en el que se va a establecer el campo SQL_DESC_INDICATOR_PTR para el registro descriptor. IndicatorPtr se puede establecer en un puntero nulo para establecer el campo SQL_DESC_INDICATOR_PTR en un puntero nulo.

Devoluciones

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR o SQL_INVALID_HANDLE.

Diagnóstico

Cuando SQLSetDescRec devuelve SQL_ERROR o SQL_SUCCESS_WITH_INFO, se puede obtener un valor SQLSTATE asociado mediante una llamada a SQLGetDiagRec con un HandleType de SQL_HANDLE_DESC y un identificador de DescriptorHandle. En la tabla siguiente se enumeran los valores SQLSTATE devueltos normalmente por SQLSetDescRec 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 El argumento RecNumber se estableció en 0 y DescriptorHandle hizo referencia a un identificador IPD.

El argumento RecNumber era menor que 0.

El argumento RecNumber era mayor que el número máximo de columnas o parámetros que el origen de datos puede admitir y el argumento DescriptorHandle era un APD, IPD o ARD.

El argumento RecNumber era igual a 0 y el argumento DescriptorHandle hacía referencia a un APD asignado implícitamente. (Este error no se produce con un descriptor de aplicación asignado explícitamente porque no se sabe si un descriptor de aplicación asignado explícitamente es un APD o ARD hasta el tiempo de ejecución).
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 (DM) El DescriptorHandle estaba asociado a un StatementHandle para el que se llamó a una función de ejecución asincrónica (no esta) 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 con la que se asoció el DescriptorHandle 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.

(DM) Se ha llamado a una función de ejecución asincrónica para el identificador de conexión asociado a DescriptorHandle. Esta función ayncrónica todavía se estaba ejecutando cuando se llamó a la función SQLSetDescRec .

Se llamó a SQLExecute, SQLExecDirect o SQLMoreResults para uno de los identificadores de instrucción asociados a DescriptorHandle y devueltos 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 tener acceso a los objetos de memoria subyacentes, posiblemente debido a condiciones de memoria baja.
HY016 No se puede modificar un descriptor de fila de implementación El argumento DescriptorHandle estaba asociado a un IRD.
HY021 Información de descriptor incoherente El campo Tipo , o cualquier otro campo asociado al campo SQL_DESC_TYPE en el descriptor, no era válido o coherente.

La información del descriptor comprobada durante una comprobación de coherencia no era coherente. (Vea "Comprobaciones de coherencia", más adelante en esta sección).
HY090 Longitud de búfer o cadena no válida (DM) El controlador era un controlador ODBC 2.x , el descriptor era ARD, el argumento ColumnNumber se estableció en 0 y el valor especificado para el argumento BufferLength no era igual a 4.
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 DescriptorHandle no admite la función .

Comentarios

Una aplicación puede llamar a SQLSetDescRec para establecer los campos siguientes para una sola columna o parámetro:

  • SQL_DESC_TYPE

  • SQL_DESC_DATETIME_INTERVAL_CODE (para los registros cuyo tipo es SQL_DATETIME o SQL_INTERVAL)

  • SQL_DESC_OCTET_LENGTH

  • SQL_DESC_PRECISION

  • SQL_DESC_SCALE

  • SQL_DESC_DATA_PTR

  • SQL_DESC_OCTET_LENGTH_PTR

  • SQL_DESC_INDICATOR_PTR

Nota

Si se produce un error en una llamada a SQLSetDescRec , el contenido del registro descriptor identificado por el argumento RecNumber no está definido.

Al enlazar una columna o parámetro, SQLSetDescRec permite cambiar varios campos que afectan al enlace sin llamar a SQLBindCol o SQLBindParameter o realizar varias llamadas a SQLSetDescField. SQLSetDescRec puede establecer campos en un descriptor que no está asociado actualmente a una instrucción . Tenga en cuenta que SQLBindParameter establece más campos que SQLSetDescRec, puede establecer campos en un APD y un IPD en una llamada, y no requiere un identificador descriptor.

Nota

El atributo de instrucción SQL_ATTR_USE_BOOKMARKS siempre debe establecerse antes de llamar a SQLSetDescRec con un argumento RecNumber de 0 para establecer campos de marcador. Aunque esto no es obligatorio, se recomienda encarecidamente.

Comprobaciones de coherencia

El controlador realiza automáticamente una comprobación de coherencia cada vez que una aplicación establece el campo SQL_DESC_DATA_PTR de un APD, ARD o IPD. Si alguno de los campos es incoherente con otros campos, SQLSetDescRec devolverá SQLSTATE HY021 (información de descriptor incoherente).

Cada vez que una aplicación establece el campo SQL_DESC_DATA_PTR de un APD, ARD o IPD, el controlador comprueba que el valor del campo SQL_DESC_TYPE y los valores aplicables a ese campo de SQL_DESC_TYPE sean válidos y coherentes. Esta comprobación siempre se realiza cuando se llama a SQLBindParameter o SQLBindCol o cuando se llama a SQLSetDescRec para un APD, ARD o IPD. Esta comprobación de coherencia incluye las siguientes comprobaciones en los campos descriptores:

  • El campo SQL_DESC_TYPE debe ser uno de los tipos ODBC C o SQL válidos o un tipo SQL específico del controlador. El campo SQL_DESC_CONCISE_TYPE debe ser uno de los tipos ODBC C o SQL válidos o un tipo C o SQL específico del controlador, incluidos los tipos de intervalo y fecha y hora concisos.

  • Si el campo de registro de SQL_DESC_TYPE es SQL_DATETIME o SQL_INTERVAL, el campo SQL_DESC_DATETIME_INTERVAL_CODE debe ser uno de los códigos datetime o interval válidos. (Vea la descripción del campo SQL_DESC_DATETIME_INTERVAL_CODE en SQLSetDescField).

  • Si el campo SQL_DESC_TYPE indica un tipo numérico, se comprueba que los campos SQL_DESC_PRECISION y SQL_DESC_SCALE sean válidos.

  • Si el campo SQL_DESC_CONCISE_TYPE es un tipo de datos time o timestamp, un tipo de intervalo con un componente de segundos o uno de los tipos de datos interval con un componente de hora, se comprueba que el campo SQL_DESC_PRECISION sea una precisión de segundos válida.

  • Si el SQL_DESC_CONCISE_TYPE es un tipo de datos interval, se comprueba que el campo SQL_DESC_DATETIME_INTERVAL_PRECISION sea un valor de precisión inicial de intervalo válido.

El campo SQL_DESC_DATA_PTR de un IPD no se establece normalmente; sin embargo, una aplicación puede hacerlo para forzar una comprobación de coherencia de los campos IPD. No se puede realizar una comprobación de coherencia en un IRD. El valor en el que el campo SQL_DESC_DATA_PTR del IPD está establecido en no se almacena realmente y no se puede recuperar mediante una llamada a SQLGetDescField o SQLGetDescRec; la configuración solo se realiza para forzar la comprobación de coherencia.

Para información acerca de Vea
Enlace de una columna SQLBindCol (función)
Enlace de un parámetro Función SQLBindParameter
Obtención de un único campo descriptor Función SQLGetDescField
Obtención de varios campos descriptores Función SQLGetDescRec
Establecimiento de campos de descriptor único Función SQLSetDescField

Consulte también

Referencia de API ODBC
Archivos de encabezado de ODBC