Compartir a través de

Función SQLSetDescRec

  • Artículo

de conformidad de
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. Esto 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 de marcador. Este argumento debe ser igual o mayor que 0. Si RecNumber es mayor que el valor de SQL_DESC_COUNT, SQL_DESC_COUNTis cambió al valor de RecNumber.

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

subtipo
[Entrada] Para los registros cuyo tipo es SQL_DATETIME o SQL_INTERVAL, este es el valor en el 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 del descriptor.

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

escalado
[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 descriptorHandle argumento 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.

Devuelve

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR o SQL_INVALID_HANDLE.

Diagnósticos

Cuando SQLSetDescRec devuelve SQL_ERROR o SQL_SUCCESS_WITH_INFO, se puede obtener un valor SQLSTATE asociado llamando a SQLGetDiagRec con un HandleType de SQL_HANDLE_DESC y un Handle 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 el 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 de *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 funciones (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) SQLExecute, SQLExecDirect, SQLBulkOperations, o sqlSetPos se llamó a para la StatementHandle con la que se ha asociado y devuelto el DescriptorHandle 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 llamó a una función de ejecución asincrónica para el identificador de conexión asociado a la DescriptorHandle. Esta función asincrónica todavía se estaba ejecutando cuando se llamó a la función SQLSetDescRec.

(DM) sqlExecute, SQLExecDirect, o SQLMoreResults se llamó a para uno de los identificadores de instrucción asociados con el DescriptorHandle y se devolvió 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 de 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 activada 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 un 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 las funciones de desconexión y solo lectura. (DM) Para obtener más información sobre el estado suspendido, vea función SQLEndTran.
HYT01 Tiempo de espera de conexión expirado 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 al DescriptorHandle no admite la función.

Comentarios

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

  • SQL_DESC_TYPE

  • SQL_DESC_DATETIME_INTERVAL_CODE (para 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 de 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 se llama a 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 de descriptor:

  • El campo SQL_DESC_TYPE debe ser uno de los tipos DE SQL o C de ODBC válidos o un tipo SQL específico del controlador. El campo SQL_DESC_CONCISE_TYPE debe ser uno de los tipos válidos de ODBC C o SQL, o un tipo de C o SQL específico del controlador, incluidos los tipos de fecha y hora y intervalo 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 de fecha y hora o intervalo 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 de intervalo 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 obtener información sobre Ver
Enlazar una columna función SQLBindCol
Enlazar un parámetro función SQLBindParameter de
Obtención de un único campo descriptor función SQLGetDescField
Obtención de varios campos de descriptor función SQLGetDescRec
Establecimiento de campos de descriptor único función SQLSetDescField

Consulte también

referencia de LA API ODBC
archivos de encabezado ODBC