Función SQLSetDescField
Conformidad
Versión introducida: Cumplimiento de estándares odbc 3.0: ISO 92
Resumen
SQLSetDescField establece el valor de un único campo de un registro descriptor.
Sintaxis
SQLRETURN SQLSetDescField(
SQLHDESC DescriptorHandle,
SQLSMALLINT RecNumber,
SQLSMALLINT FieldIdentifier,
SQLPOINTER ValuePtr,
SQLINTEGER BufferLength);
Argumentos
DescriptorHandle
[Entrada] Identificador de descriptor.
RecNumber
[Entrada] Indica el registro descriptor que contiene el campo que la aplicación busca establecer. Los registros descriptores se numeran a partir de 0, siendo el número de registro 0 el registro de marcador. El argumento RecNumber se omite para los campos de encabezado.
FieldIdentifier
[Entrada] Indica el campo del descriptor cuyo valor se va a establecer. Para obtener más información, vea "FieldIdentifier Argument" en la sección "Comments".
ValuePtr
[Entrada] Puntero a un búfer que contiene la información del descriptor o un valor entero. El tipo de datos depende del valor de FieldIdentifier. Si ValuePtr es un valor entero, se puede considerar como 8 bytes (SQLLEN), 4 bytes (SQLINTEGER) o 2 bytes (SQLSMALLINT), dependiendo del valor del argumento FieldIdentifier .
BufferLength
[Entrada] Si FieldIdentifier es un campo definido por ODBC y ValuePtr apunta a una cadena de caracteres o a un búfer binario, este argumento debe ser la longitud de *ValuePtr. Para los datos de cadena de caracteres, este argumento debe contener el número de bytes de la cadena.
Si FieldIdentifier es un campo definido por ODBC y ValuePtr es un entero, se omite BufferLength .
Si FieldIdentifier es un campo definido por el controlador, la aplicación indica la naturaleza del campo en el Administrador de controladores estableciendo el argumento BufferLength . BufferLength puede tener los siguientes valores:
Si ValuePtr es un puntero a una cadena de caracteres, BufferLength es la longitud de la cadena o SQL_NTS.
Si ValuePtr es un puntero a un búfer binario, la aplicación coloca el resultado de la macro SQL_LEN_BINARY_ATTR(length) en BufferLength. Esto coloca un valor negativo en BufferLength.
Si ValuePtr es un puntero a un valor distinto de una cadena de caracteres o una cadena binaria, BufferLength debe tener el valor SQL_IS_POINTER.
Si ValuePtr contiene un valor de longitud fija, BufferLength es SQL_IS_INTEGER, SQL_IS_UINTEGER, SQL_IS_SMALLINT o SQL_IS_USMALLINT, según corresponda.
Devoluciones
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR o SQL_INVALID_HANDLE.
Diagnóstico
Cuando SQLSetDescField 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 identificador de DescriptorHandle. En la tabla siguiente se enumeran los valores SQLSTATE devueltos normalmente por SQLSetDescField 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). |
| 01S02 | Valor de opción cambiado | El controlador no admitía el valor especificado en *ValuePtr (si ValuePtr era un puntero) o el valor de ValuePtr (si ValuePtr era un valor entero) o *ValuePtr no era válido debido a las condiciones de trabajo de implementación, por lo que el controlador sustituyó un valor similar. (Function devuelve SQL_SUCCESS_WITH_INFO). |
| 07009 | Índice de descriptor no válido | El argumento FieldIdentifier era un campo de registro, el argumento RecNumber era 0 y el argumento DescriptorHandle hacía referencia a un identificador IPD. El argumento RecNumber era menor que 0 y el argumento DescriptorHandle hacía referencia a un ARD o a un APD. 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 hacía referencia a un APD o ARD. (DM) El argumento FieldIdentifier se SQL_DESC_COUNT y el argumento *ValuePtr era menor que 0. 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, ya que 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. |
| 22001 | Datos de cadena, truncados a la derecha | El argumento FieldIdentifier se SQL_DESC_NAME y el argumento BufferLength era un valor mayor que SQL_MAX_IDENTIFIER_LEN. |
| 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) 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 llamó a una función de ejecución asincrónica para el identificador de conexión asociado al DescriptorHandle. Esta función asincrónica todavía se estaba ejecutando cuando se llamó a la función SQLSetDescField . (DM) se llamó a SQLExecute, SQLExecDirect o SQLMoreResults para uno de los identificadores de instrucción asociados a DescriptorHandle y 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 acceder 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 y el argumento FieldIdentifier no se SQL_DESC_ARRAY_STATUS_PTR ni SQL_DESC_ROWS_PROCESSED_PTR. |
| HY021 | Información de descriptor incoherente | Los campos SQL_DESC_TYPE y SQL_DESC_DATETIME_INTERVAL_CODE no forman un tipo SQL ODBC válido ni un tipo SQL específico del controlador válido (para IPD) o un tipo de C ODBC válido (para APD o ARD). La información del descriptor activada durante una comprobación de coherencia no era coherente. (Vea "Comprobación de coherencia" en SQLSetDescRec). |
| HY090 | Longitud de búfer o cadena no válida | (DM) *ValuePtr es una cadena de caracteres y BufferLength era menor que cero, pero no era igual a SQL_NTS. (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. |
| HY091 | Identificador de campo de descriptor no válido | El valor especificado para el argumento FieldIdentifier no era un campo definido por ODBC y no era un valor definido por la implementación. El argumento FieldIdentifier no era válido para el argumento DescriptorHandle . El argumento FieldIdentifier era un campo definido por ODBC de solo lectura. |
| HY092 | Identificador de atributo o opción no válido | El valor de *ValuePtr no era válido para el argumento FieldIdentifier . El argumento FieldIdentifier se SQL_DESC_UNNAMED y ValuePtr se SQL_NAMED. |
| HY105 | Tipo de parámetro no válido | (DM) El valor especificado para el campo SQL_DESC_PARAMETER_TYPE no era válido. (Para obtener más información, vea la sección "InputOutputType Argument" en SQLBindParameter). |
| 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 Novedades de ODBC 3.8. |
| 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 SQLSetDescField para establecer cualquier campo descriptor de uno en uno. Una llamada a SQLSetDescField establece un único campo en un único descriptor. Se puede llamar a esta función para establecer cualquier campo en cualquier tipo de descriptor, siempre que se pueda establecer el campo. (Consulte la tabla más adelante en esta sección).
Nota
Si se produce un error en una llamada a SQLSetDescField , el contenido del registro descriptor identificado por el argumento RecNumber no está definido.
Se puede llamar a otras funciones para establecer varios campos descriptores con una sola llamada de la función. La función SQLSetDescRec establece una variedad de campos que afectan al tipo de datos y al búfer enlazado a una columna o parámetro (los campos SQL_DESC_TYPE, SQL_DESC_DATETIME_INTERVAL_CODE, SQL_DESC_OCTET_LENGTH, SQL_DESC_PRECISION, SQL_DESC_SCALE, SQL_DESC_DATA_PTR, SQL_DESC_OCTET_LENGTH_PTR y SQL_DESC_INDICATOR_PTR). SQLBindCol o SQLBindParameter se pueden usar para crear una especificación completa para el enlace de una columna o parámetro. Estas funciones establecen un grupo específico de campos descriptores con una llamada de función.
Se puede llamar a SQLSetDescField para cambiar los búferes de enlace agregando un desplazamiento a los punteros de enlace (SQL_DESC_DATA_PTR, SQL_DESC_INDICATOR_PTR o SQL_DESC_OCTET_LENGTH_PTR). Esto cambia los búferes de enlace sin llamar a SQLBindCol o SQLBindParameter, lo que permite que una aplicación cambie SQL_DESC_DATA_PTR sin cambiar otros campos, como SQL_DESC_DATA_TYPE.
Si una aplicación llama a SQLSetDescField para establecer cualquier campo que no sea SQL_DESC_COUNT o los campos diferidos SQL_DESC_DATA_PTR, SQL_DESC_OCTET_LENGTH_PTR o SQL_DESC_INDICATOR_PTR, el registro se desenlace.
Los campos de encabezado de descriptor se establecen mediante una llamada a SQLSetDescField con el FieldIdentifier adecuado. Muchos campos de encabezado también son atributos de instrucción, por lo que también se pueden establecer mediante una llamada a SQLSetStmtAttr. Esto permite a las aplicaciones establecer un campo descriptor sin obtener primero un identificador de descriptor. Cuando se llama a SQLSetDescField para establecer un campo de encabezado, se omite el argumento RecNumber .
Se usa recnumber de 0 para establecer campos de marcador.
Nota
El atributo de instrucción SQL_ATTR_USE_BOOKMARKS siempre debe establecerse antes de llamar a SQLSetDescField para establecer campos de marcador. Aunque esto no es obligatorio, se recomienda encarecidamente.
Secuencia de campos descriptores de configuración
Al establecer campos descriptores mediante una llamada a SQLSetDescField, la aplicación debe seguir una secuencia específica:
La aplicación debe establecer primero el campo SQL_DESC_TYPE, SQL_DESC_CONCISE_TYPE o SQL_DESC_DATETIME_INTERVAL_CODE.
Una vez establecido uno de estos campos, la aplicación puede establecer un atributo de un tipo de datos y el controlador establece los campos de atributo de tipo de datos en los valores predeterminados adecuados para el tipo de datos. El valor predeterminado automático de los campos de atributo de tipo garantiza que el descriptor siempre esté listo para usar una vez que la aplicación haya especificado un tipo de datos. Si la aplicación establece explícitamente un atributo de tipo de datos, se invalida el atributo predeterminado.
Una vez que se ha establecido uno de los campos enumerados en el paso 1 y se han establecido atributos de tipo de datos, la aplicación puede establecer SQL_DESC_DATA_PTR. Esto solicita una comprobación de coherencia de los campos descriptores. Si la aplicación cambia el tipo de datos o los atributos después de establecer el campo SQL_DESC_DATA_PTR, el controlador establece SQL_DESC_DATA_PTR en un puntero nulo, desenlace el registro. Esto obliga a la aplicación a completar los pasos adecuados en secuencia, antes de que se pueda usar el registro del descriptor.
Inicialización de campos de Descriptor
Cuando se asigna un descriptor, los campos del descriptor se pueden inicializar en un valor predeterminado, inicializarse sin un valor predeterminado o ser indefinidos para el tipo de descriptor. Las tablas siguientes indican la inicialización de cada campo para cada tipo de descriptor, con "D" que indica que el campo se inicializa con un valor predeterminado y "ND" que indica que el campo se inicializa sin un valor predeterminado. Si se muestra un número, el valor predeterminado del campo es ese número. Las tablas también indican si un campo es de lectura y escritura (R/W) o de solo lectura (R).
Los campos de un IRD tienen un valor predeterminado solo después de que se haya preparado o ejecutado la instrucción y se haya rellenado el IRD, no cuando se haya asignado el identificador de instrucción o el descriptor. Hasta que se haya rellenado el IRD, cualquier intento de obtener acceso a un campo de un IRD devolverá un error.
Algunos campos descriptores se definen para uno o varios, pero no todos, de los tipos de descriptor (ARD e IRD, y APD e IPD). Cuando un campo no está definido para un tipo de descriptor, no es necesario para ninguna de las funciones que usan ese descriptor.
SQLGetDescField no puede establecer necesariamente los campos a los que sqlSetDescField puede tener acceso. Los campos que sqlSetDescField puede establecer se muestran en las tablas siguientes.
La inicialización de los campos de encabezado se describe en la tabla siguiente.
| Nombre del campo de encabezado | Tipo | L/E | Valor predeterminado |
|---|---|---|---|
| SQL_DESC_ALLOC_TYPE | SQLSMALLINT | ARD: R APD: R IRD: R IPD: R | ARD: SQL_DESC_ALLOC_AUTO para SQL_DESC_ALLOC_USER implícitas o explícitas APD: SQL_DESC_ALLOC_AUTO para SQL_DESC_ALLOC_USER implícitas o explícitas IRD: SQL_DESC_ALLOC_AUTO IPD: SQL_DESC_ALLOC_AUTO |
| SQL_DESC_ARRAY_SIZE | SQLULEN | ARD: R/W APD: R/W IRD: IPD sin usar: Sin usar | ARD:[1] APD:[1] IRD: IPD sin usar: Sin usar |
| SQL_DESC_ARRAY_STATUS_PTR | SQLUSMALLINT* | ARD: R/W APD: R/W IRD: R/W IPD: R/W | ARD: Null ptr APD: Null ptr IRD: Null ptr IPD: Null ptr |
| SQL_DESC_BIND_OFFSET_PTR | SQLLEN* | ARD: R/W APD: R/W IRD: IPD sin usar: Sin usar | ARD: Null ptr APD: Null ptr IRD: IPD sin usar: Sin usar |
| SQL_DESC_BIND_TYPE | SQLINTEGER | ARD: R/W APD: R/W IRD: IPD sin usar: Sin usar | ARD: SQL_BIND_BY_COLUMN APD: SQL_BIND_BY_COLUMN IRD: sin usar IPD: sin usar |
| SQL_DESC_COUNT | SQLSMALLINT | ARD: R/W APD: R/W IRD: R IPD: R/W | ARD: 0 APD: 0 IRD: D IPD: 0 |
| SQL_DESC_ROWS_PROCESSED_PTR | SQLULEN* | ARD: APD sin usar: IRD sin usar: IPD de R/W: R/W | ARD: APD sin usar: IRD sin usar: Null ptr IPD: Null ptr |
[1] Estos campos se definen solo cuando el controlador rellena automáticamente el IPD. Si no es así, no están definidos. Si una aplicación intenta establecer estos campos, se devolverá SQLSTATE HY091 (identificador de campo de descriptor no válido).
La inicialización de los campos de registro se muestra en la tabla siguiente.
| Nombre del campo de registro | Tipo | L/E | Valor predeterminado |
|---|---|---|---|
| SQL_DESC_AUTO_UNIQUE_VALUE | SQLINTEGER | ARD: APD sin usar: IRD sin usar: R IPD: Sin usar | ARD: APD sin usar: IRD sin usar: D IPD: Sin usar |
| SQL_DESC_BASE_COLUMN_NAME | SQLCHAR * | ARD: APD sin usar: IRD sin usar: R IPD: Sin usar | ARD: APD sin usar: IRD sin usar: D IPD: Sin usar |
| SQL_DESC_BASE_TABLE_NAME | SQLCHAR * | ARD: APD sin usar: IRD sin usar: R IPD: Sin usar | ARD: APD sin usar: IRD sin usar: D IPD: Sin usar |
| SQL_DESC_CASE_SENSITIVE | SQLINTEGER | ARD: APD sin usar: IRD sin usar: R IPD: R | ARD: APD sin usar: IRD sin usar: D IPD: D[1] |
| SQL_DESC_CATALOG_NAME | SQLCHAR * | ARD: APD sin usar: IRD sin usar: R IPD: Sin usar | ARD: APD sin usar: IRD sin usar: D IPD: Sin usar |
| SQL_DESC_CONCISE_TYPE | SQLSMALLINT | ARD: R/W APD: R/W IRD: R IPD: R/W | ARD: SQL_C_ APD PREDETERMINADO: SQL_C_ IRD PREDETERMINADO: D IPD: ND |
| SQL_DESC_DATA_PTR | SQLPOINTER | ARD: R/W APD: R/W IRD: IPD sin usar: Sin usar | ARD: Null ptr APD: Null ptr IRD: Unused IPD: Unused[2] |
| SQL_DESC_DATETIME_INTERVAL_CODE | SQLSMALLINT | ARD: R/W APD: R/W IRD: R IPD: R/W | ARD: ND APD: ND IRD: D IPD: ND |
| SQL_DESC_DATETIME_INTERVAL_PRECISION | SQLINTEGER | ARD: R/W APD: R/W IRD: R IPD: R/W | ARD: ND APD: ND IRD: D IPD: ND |
| SQL_DESC_DISPLAY_SIZE | SQLLEN | ARD: APD sin usar: IRD sin usar: R IPD: Sin usar | ARD: APD sin usar: IRD sin usar: D IPD: Sin usar |
| SQL_DESC_FIXED_PREC_SCALE | SQLSMALLINT | ARD: APD sin usar: IRD sin usar: R IPD: R | ARD: APD sin usar: IRD sin usar: D IPD: D[1] |
| SQL_DESC_INDICATOR_PTR | SQLLEN * | ARD: R/W APD: R/W IRD: IPD sin usar: Sin usar | ARD: Null ptr APD: Null ptr IRD: Unused IPD: Unused |
| SQL_DESC_LABEL | SQLCHAR * | ARD: APD sin usar: IRD sin usar: R IPD: Sin usar | ARD: APD sin usar: IRD sin usar: D IPD: Sin usar |
| SQL_DESC_LENGTH | SQLULEN | ARD: R/W APD: R/W IRD: R IPD: R/W | ARD: ND APD: ND IRD: D IPD: ND |
| SQL_DESC_LITERAL_PREFIX | SQLCHAR * | ARD: APD sin usar: IRD sin usar: R IPD: Sin usar | ARD: APD sin usar: IRD sin usar: D IPD: Sin usar |
| SQL_DESC_LITERAL_SUFFIX | SQLCHAR * | ARD: APD sin usar: IRD sin usar: R IPD: Sin usar | ARD: APD sin usar: IRD sin usar: D IPD: Sin usar |
| SQL_DESC_LOCAL_TYPE_NAME | SQLCHAR * | ARD: APD sin usar: IRD sin usar: R IPD: R | ARD: APD sin usar: IRD sin usar: D IPD: D[1] |
| SQL_DESC_NAME | SQLCHAR * | ARD: APD sin usar: IRD sin usar: R IPD: R/W | ARD: ND APD: ND IRD: D IPD: ND |
| SQL_DESC_NULLABLE | SQLSMALLINT | ARD: APD sin usar: IRD sin usar: R IPD: R | ARD: ND APD: ND IRD: D IPD: ND |
| SQL_DESC_NUM_PREC_RADIX | SQLINTEGER | ARD: R/W APD: R/W IRD: R IPD: R/W | ARD: ND APD: ND IRD: D IPD: ND |
| SQL_DESC_OCTET_LENGTH | SQLLEN | ARD: R/W APD: R/W IRD: R IPD: R/W | ARD: ND APD: ND IRD: D IPD: ND |
| SQL_DESC_OCTET_LENGTH_PTR | SQLLEN * | ARD: R/W APD: R/W IRD: IPD sin usar: Sin usar | ARD: Null ptr APD: Null ptr IRD: Unused IPD: Unused |
| SQL_DESC_PARAMETER_TYPE | SQLSMALLINT | ARD: APD sin usar: IRD sin usar: IPD sin usar: R/W | ARD: APD sin usar: IRD sin usar: IPD sin usar: D=SQL_PARAM_INPUT |
| SQL_DESC_PRECISION | SQLSMALLINT | ARD: R/W APD: R/W IRD: R IPD: R/W | ARD: ND APD: ND IRD: D IPD: ND |
| SQL_DESC_ROWVER | SQLSMALLINT | ARD: Sin usar APD: Sin usar IRD: R IPD: R |
ARD: Sin usar APD: Sin usar IRD: ND IPD: ND |
| SQL_DESC_SCALE | SQLSMALLINT | ARD: R/W APD: R/W IRD: R IPD: R/W | ARD: ND APD: ND IRD: D IPD: ND |
| SQL_DESC_SCHEMA_NAME | SQLCHAR * | ARD: APD sin usar: IRD sin usar: IPD de R: sin usar | ARD: APD sin usar: IRD sin usar: D IPD: Sin usar |
| SQL_DESC_SEARCHABLE | SQLSMALLINT | ARD: APD sin usar: IRD sin usar: IPD de R: sin usar | ARD: APD sin usar: IRD sin usar: D IPD: Sin usar |
| SQL_DESC_TABLE_NAME | SQLCHAR * | ARD: APD sin usar: IRD sin usar: IPD de R: sin usar | ARD: APD sin usar: IRD sin usar: D IPD: Sin usar |
| SQL_DESC_TYPE | SQLSMALLINT | ARD: R/W APD: R/W IRD: R IPD: R/W | ARD: SQL_C_DEFAULT APD: SQL_C_DEFAULT IRD: D IPD: ND |
| SQL_DESC_TYPE_NAME | SQLCHAR * | ARD: APD sin usar: IRD sin usar: R IPD: R | ARD: APD sin usar: IRD sin usar: D IPD: D[1] |
| SQL_DESC_UNNAMED | SQLSMALLINT | ARD: APD sin usar: IRD sin usar: R IPD: R/W | ARD: ND APD: ND IRD: D IPD: ND |
| SQL_DESC_UNSIGNED | SQLSMALLINT | ARD: APD sin usar: IRD sin usar: R IPD: R | ARD: APD sin usar: IRD sin usar: D IPD: D[1] |
| SQL_DESC_UPDATABLE | SQLSMALLINT | ARD: APD sin usar: IRD sin usar: IPD de R: sin usar | ARD: APD sin usar: IRD sin usar: D IPD: Sin usar |
[1] Estos campos solo se definen cuando el controlador rellena automáticamente el IPD. Si no es así, no están definidos. Si una aplicación intenta establecer estos campos, se devolverá SQLSTATE HY091 (identificador de campo descriptor no válido).
[2] El campo SQL_DESC_DATA_PTR del IPD se puede establecer para forzar una comprobación de coherencia. En una llamada posterior a SQLGetDescField o SQLGetDescRec, el controlador no es necesario para devolver el valor en el que se estableció SQL_DESC_DATA_PTR.
Argumento FieldIdentifier
El argumento FieldIdentifier indica el campo descriptor que se va a establecer. Un descriptor contiene el encabezado descriptor, que consta de los campos de encabezado descritos en la sección siguiente, "Campos de encabezado" y cero o más registros descriptores, que constan de los campos de registro descritos en la sección que sigue a la sección "Campos de encabezado".
Campos de encabezado
Cada descriptor tiene un encabezado que consta de los siguientes campos:
SQL_DESC_ALLOC_TYPE [Todos]
Este campo de encabezado SQLSMALLINT de solo lectura especifica si la aplicación asignó automáticamente el descriptor o explícitamente. La aplicación puede obtener, pero no modificar, este campo. El controlador establece el campo en SQL_DESC_ALLOC_AUTO si el controlador asignó automáticamente el descriptor. El controlador establece en SQL_DESC_ALLOC_USER si la aplicación asignó explícitamente el descriptor.
SQL_DESC_ARRAY_SIZE [Descriptores de aplicación]
En ARDs, este campo de encabezado SQLULEN especifica el número de filas del conjunto de filas. Este es el número de filas que se devolverán mediante una llamada a SQLFetch o SQLFetchScroll o a las que operará una llamada a SQLBulkOperations o SQLSetPos.
En APDs, este campo de encabezado SQLULEN especifica el número de valores para cada parámetro.
El valor predeterminado de este campo es 1. Si SQL_DESC_ARRAY_SIZE es mayor que 1, SQL_DESC_DATA_PTR, SQL_DESC_INDICATOR_PTR y SQL_DESC_OCTET_LENGTH_PTR de apD o ARD apuntan a matrices. La cardinalidad de cada matriz es igual al valor de este campo.
Este campo de ARD también se puede establecer llamando a SQLSetStmtAttr con el atributo SQL_ATTR_ROW_ARRAY_SIZE. Este campo del APD también se puede establecer llamando a SQLSetStmtAttr con el atributo SQL_ATTR_PARAMSET_SIZE.
SQL_DESC_ARRAY_STATUS_PTR [Todos]
Para cada tipo de descriptor, este campo de encabezado SQLUSMALLINT * apunta a una matriz de valores SQLUSMALLINT. Estas matrices se denominan de la siguiente manera: matriz de estado de fila (IRD), matriz de estado de parámetros (IPD), matriz de operaciones de fila (ARD) y matriz de operaciones de parámetros (APD).
En el IRD, este campo de encabezado apunta a una matriz de estado de fila que contiene valores de estado después de una llamada a SQLBulkOperations, SQLFetch, SQLFetchScroll o SQLSetPos. La matriz tiene tantos elementos como hay filas en el conjunto de filas. La aplicación debe asignar una matriz de SQLUSMALLINTs y establecer este campo para que apunte a la matriz. El campo se establece en un puntero nulo de forma predeterminada. El controlador rellenará la matriz, a menos que el campo SQL_DESC_ARRAY_STATUS_PTR esté establecido en un puntero nulo, en cuyo caso no se generan valores de estado y la matriz no se rellena.
Precaución
El comportamiento del controlador no está definido si la aplicación establece los elementos de la matriz de estado de fila a los que apunta el campo SQL_DESC_ARRAY_STATUS_PTR del IRD.
La matriz se rellena inicialmente mediante una llamada a SQLBulkOperations, SQLFetch, SQLFetchScroll o SQLSetPos. Si la llamada no devolvió SQL_SUCCESS o SQL_SUCCESS_WITH_INFO, el contenido de la matriz a la que apunta este campo no está definido. Los elementos de la matriz pueden contener los siguientes valores:
SQL_ROW_SUCCESS: la fila se ha capturado correctamente y no ha cambiado desde que se capturó por última vez.
SQL_ROW_SUCCESS_WITH_INFO: la fila se ha capturado correctamente y no ha cambiado desde que se capturó por última vez. Sin embargo, se devolvió una advertencia sobre la fila.
SQL_ROW_ERROR: error al capturar la fila.
SQL_ROW_UPDATED: la fila se ha capturado correctamente y se ha actualizado desde que se capturó por última vez. Si la fila se recupera de nuevo, su estado es SQL_ROW_SUCCESS.
SQL_ROW_DELETED: la fila se ha eliminado desde que se capturó por última vez.
SQL_ROW_ADDED: SQLBulkOperations insertó la fila. Si la fila se recupera de nuevo, su estado es SQL_ROW_SUCCESS.
SQL_ROW_NOROW: el conjunto de filas se superpone al final del conjunto de resultados y no se devolvió ninguna fila correspondiente a este elemento de la matriz de estado de fila.
Este campo del IRD también se puede establecer llamando a SQLSetStmtAttr con el atributo SQL_ATTR_ROW_STATUS_PTR.
El campo SQL_DESC_ARRAY_STATUS_PTR del IRD solo es válido después de que se haya devuelto SQL_SUCCESS o SQL_SUCCESS_WITH_INFO. Si el código de retorno no es uno de estos, la ubicación a la que apunta SQL_DESC_ROWS_PROCESSED_PTR no está definida.
En el IPD, este campo de encabezado apunta a una matriz de estado de parámetros que contiene información de estado para cada conjunto de valores de parámetro después de una llamada a SQLExecute o SQLExecDirect. Si la llamada a SQLExecute o SQLExecDirect no devolvió SQL_SUCCESS o SQL_SUCCESS_WITH_INFO, el contenido de la matriz a la que apunta este campo no está definido. La aplicación debe asignar una matriz de SQLUSMALLINTs y establecer este campo para que apunte a la matriz. El controlador rellenará la matriz, a menos que el campo de SQL_DESC_ARRAY_STATUS_PTR esté establecido en un puntero nulo, en cuyo caso no se generan valores de estado y la matriz no se rellena. Los elementos de la matriz pueden contener los siguientes valores:
SQL_PARAM_SUCCESS: la instrucción SQL se ejecutó correctamente para este conjunto de parámetros.
SQL_PARAM_SUCCESS_WITH_INFO: la instrucción SQL se ejecutó correctamente para este conjunto de parámetros; sin embargo, la información de advertencia está disponible en la estructura de datos de diagnóstico.
SQL_PARAM_ERROR: error al procesar este conjunto de parámetros. La información adicional sobre errores está disponible en la estructura de datos de diagnóstico.
SQL_PARAM_UNUSED: este conjunto de parámetros no se usaba, posiblemente debido al hecho de que algún conjunto de parámetros anterior provocó un error que anuló el procesamiento adicional, o porque SQL_PARAM_IGNORE se estableció para ese conjunto de parámetros en la matriz especificado por el campo SQL_DESC_ARRAY_STATUS_PTR del APD.
SQL_PARAM_DIAG_UNAVAILABLE: la información de diagnóstico no está disponible. Un ejemplo de esto es cuando el controlador trata las matrices de parámetros como una unidad monolítica, por lo que no genera este nivel de información de error.
Este campo del IPD también se puede establecer llamando a SQLSetStmtAttr con el atributo SQL_ATTR_PARAM_STATUS_PTR.
En ARD, este campo de encabezado apunta a una matriz de valores de operación de fila que la aplicación puede establecer para indicar si se omitirá esta fila para las operaciones SQLSetPos . Los elementos de la matriz pueden contener los siguientes valores:
SQL_ROW_PROCEED: la fila se incluye en la operación masiva mediante SQLSetPos. (Esta configuración no garantiza que la operación se produzca en la fila. Si la fila tiene el estado SQL_ROW_ERROR en la matriz de estado de fila IRD, es posible que el controlador no pueda realizar la operación en la fila).
SQL_ROW_IGNORE: la fila se excluye de la operación masiva mediante SQLSetPos.
Si no se establecen elementos de la matriz, todas las filas se incluyen en la operación masiva. Si el valor del campo SQL_DESC_ARRAY_STATUS_PTR de ARD es un puntero nulo, todas las filas se incluyen en la operación masiva; la interpretación es la misma que si el puntero apuntaba a una matriz válida y todos los elementos de la matriz se SQL_ROW_PROCEED. Si un elemento de la matriz se establece en SQL_ROW_IGNORE, no se cambia el valor de la matriz de estado de fila de la fila omitida.
Este campo de ARD también se puede establecer llamando a SQLSetStmtAttr con el atributo SQL_ATTR_ROW_OPERATION_PTR.
En el APD, este campo de encabezado apunta a una matriz de valores de operación de parámetros que la aplicación puede establecer para indicar si se omitirá este conjunto de parámetros cuando se llame a SQLExecute o SQLExecDirect . Los elementos de la matriz pueden contener los siguientes valores:
SQL_PARAM_PROCEED: el conjunto de parámetros se incluye en la llamada SQLExecute o SQLExecDirect .
SQL_PARAM_IGNORE: el conjunto de parámetros se excluye de la llamada SQLExecute o SQLExecDirect .
Si no se establecen elementos de la matriz, todos los conjuntos de parámetros de la matriz se usan en las llamadas a SQLExecute o SQLExecDirect . Si el valor del campo SQL_DESC_ARRAY_STATUS_PTR del APD es un puntero nulo, se usan todos los conjuntos de parámetros; la interpretación es la misma que si el puntero apuntaba a una matriz válida y todos los elementos de la matriz se SQL_PARAM_PROCEED.
Este campo del APD también se puede establecer llamando a SQLSetStmtAttr con el atributo SQL_ATTR_PARAM_OPERATION_PTR.
SQL_DESC_BIND_OFFSET_PTR [Descriptores de aplicación]
Este campo de encabezado SQLLEN * apunta al desplazamiento de enlace. Se establece en un puntero nulo de forma predeterminada. Si este campo no es un puntero nulo, el controlador desreferencia el puntero y agrega el valor desreferenciado a cada uno de los campos aplazados que tienen un valor distinto de NULL en el registro de descriptor (SQL_DESC_DATA_PTR, SQL_DESC_INDICATOR_PTR y SQL_DESC_OCTET_LENGTH_PTR) en el momento de la captura y usa los nuevos valores de puntero al enlazar.
El desplazamiento de enlace siempre se agrega directamente a los valores de los campos SQL_DESC_DATA_PTR, SQL_DESC_INDICATOR_PTR y SQL_DESC_OCTET_LENGTH_PTR. Si el desplazamiento se cambia a un valor diferente, el nuevo valor se sigue agregando directamente al valor de cada campo descriptor. El nuevo desplazamiento no se agrega al valor del campo más ningún desplazamiento anterior.
Este campo es un campo diferido: no se usa en el momento en que se establece, pero el controlador usa en un momento posterior cuando necesita determinar las direcciones de los búferes de datos.
Este campo de ARD también se puede establecer llamando a SQLSetStmtAttr con el atributo SQL_ATTR_ROW_BIND_OFFSET_PTR. Este campo de ARD también se puede establecer llamando a SQLSetStmtAttr con el atributo SQL_ATTR_PARAM_BIND_OFFSET_PTR.
Para obtener más información, vea la descripción del enlace de fila en SQLFetchScroll y SQLBindParameter.
SQL_DESC_BIND_TYPE [Descriptores de aplicación]
Este campo de encabezado SQLUINTEGER establece la orientación de enlace que se usará para enlazar columnas o parámetros.
En ARDs, este campo especifica la orientación de enlace cuando se llama a SQLFetchScroll o SQLFetch en el identificador de instrucción asociado.
Para seleccionar el enlace de columnas para las columnas, este campo se establece en SQL_BIND_BY_COLUMN (valor predeterminado).
Este campo de ARD también se puede establecer llamando a SQLSetStmtAttr con el atributo SQL_ATTR_ROW_BIND_TYPE.
En LOS APD, este campo especifica la orientación de enlace que se va a usar para los parámetros dinámicos.
Para seleccionar el enlace de columnas para los parámetros, este campo se establece en SQL_BIND_BY_COLUMN (valor predeterminado).
Este campo del APD también se puede establecer llamando a SQLSetStmtAttr con el atributo SQL_ATTR_PARAM_BIND_TYPE.
SQL_DESC_COUNT [Todos]
Este campo de encabezado SQLSMALLINT especifica el índice basado en 1 del registro numerado más alto que contiene datos. Cuando el controlador establece la estructura de datos para el descriptor, también debe establecer el campo SQL_DESC_COUNT para mostrar cuántos registros son significativos. Cuando una aplicación asigna una instancia de esta estructura de datos, no tiene que especificar cuántos registros se van a reservar espacio. Como la aplicación especifica el contenido de los registros, el controlador realiza cualquier acción necesaria para asegurarse de que el identificador del descriptor hace referencia a una estructura de datos del tamaño adecuado.
SQL_DESC_COUNT no es un recuento de todas las columnas de datos enlazadas (si el campo está en un ARD) o de todos los parámetros enlazados (si el campo está en un APD), pero el número del registro con mayor número. Si la columna o el parámetro con número más alto no están enlazados, se cambia SQL_DESC_COUNT al número de la siguiente columna o parámetro con el número más alto. Si una columna o un parámetro con un número menor que el número de la columna con el número más alto no está enlazado (llamando a SQLBindCol con el argumento TargetValuePtr establecido en un puntero nulo o SQLBindParameter con el argumento ParameterValuePtr establecido en un puntero nulo), no se cambia SQL_DESC_COUNT. Si las columnas o parámetros adicionales están enlazadas con números mayores que el registro numerado más alto que contiene datos, el controlador aumenta automáticamente el valor en el campo SQL_DESC_COUNT. Si todas las columnas están sin enlazar llamando a SQLFreeStmt con la opción SQL_UNBIND, los campos de SQL_DESC_COUNT de ARD e IRD se establecen en 0. Si se llama a SQLFreeStmt con la opción SQL_RESET_PARAMS, los campos de SQL_DESC_COUNT del APD e IPD se establecen en 0.
El valor de SQL_DESC_COUNT se puede establecer explícitamente mediante una aplicación llamando a SQLSetDescField. Si el valor de SQL_DESC_COUNT se reduce explícitamente, todos los registros con números mayores que el nuevo valor de SQL_DESC_COUNT se quitan de forma eficaz. Si el valor de SQL_DESC_COUNT se establece explícitamente en 0 y el campo está en un ARD, se liberan todos los búferes de datos excepto una columna de marcador enlazada.
El recuento de registros de este campo de una ARD no incluye una columna de marcador enlazada. La única manera de desenlazar una columna de marcador es establecer el campo SQL_DESC_DATA_PTR en un puntero nulo.
SQL_DESC_ROWS_PROCESSED_PTR [Descriptores de implementación]
En un IRD, este campo de encabezado SQLULEN * apunta a un búfer que contiene el número de filas capturadas después de una llamada a SQLFetch o SQLFetchScroll, o el número de filas afectadas en una operación masiva realizada por una llamada a SQLBulkOperations o SQLSetPos, incluidas las filas de error.
En un IPD, este campo de encabezado SQLUINTEGER * apunta a un búfer que contiene el número de conjuntos de parámetros que se han procesado, incluidos los conjuntos de errores. No se devolverá ningún número si se trata de un puntero nulo.
SQL_DESC_ROWS_PROCESSED_PTR solo es válido después de que SQL_SUCCESS o SQL_SUCCESS_WITH_INFO se haya devuelto después de una llamada a SQLFetch o SQLFetchScroll (para un campo IRD) o SQLExecute, SQLExecDirect o SQLParamData (para un campo IPD). Si la llamada que rellena el búfer al que apunta este campo no devuelve SQL_SUCCESS o SQL_SUCCESS_WITH_INFO, el contenido del búfer no está definido, a menos que devuelva SQL_NO_DATA, en cuyo caso el valor del búfer se establece en 0.
Este campo de ARD también se puede establecer llamando a SQLSetStmtAttr con el atributo SQL_ATTR_ROWS_FETCHED_PTR. Este campo del APD también se puede establecer llamando a SQLSetStmtAttr con el atributo SQL_ATTR_PARAMS_PROCESSED_PTR.
La aplicación asigna el búfer al que apunta este campo. Es un búfer de salida diferido establecido por el controlador. Se establece en un puntero nulo de forma predeterminada.
Campos de registro
Cada descriptor contiene uno o varios registros que constan de campos que definen datos de columna o parámetros dinámicos, en función del tipo de descriptor. Cada registro es una definición completa de una sola columna o parámetro.
SQL_DESC_AUTO_UNIQUE_VALUE [IRD]
Este campo de registro SQLINTEGER de solo lectura contiene SQL_TRUE si la columna es una columna de incremento automático o SQL_FALSE si la columna no es una columna de incremento automático. Este campo es de solo lectura, pero la columna de incremento automático subyacente no es necesariamente de solo lectura.
SQL_DESC_BASE_COLUMN_NAME [IRD]
Este campo de registro SQLCHAR * de solo lectura contiene el nombre de columna base de la columna del conjunto de resultados. Si no existe un nombre de columna base (como en el caso de las columnas que son expresiones), esta variable contiene una cadena vacía.
SQL_DESC_BASE_TABLE_NAME [IRD]
Este campo de registro SQLCHAR * de solo lectura contiene el nombre de la tabla base para la columna del conjunto de resultados. Si no se puede definir un nombre de tabla base o no es aplicable, esta variable contiene una cadena vacía.
SQL_DESC_CASE_SENSITIVE [Descriptores de implementación]
Este campo de registro SQLINTEGER de solo lectura contiene SQL_TRUE si la columna o el parámetro se trata como distingue mayúsculas de minúsculas para las intercalaciones y comparaciones, o SQL_FALSE si la columna no se trata como distingue mayúsculas de minúsculas para las intercalaciones y comparaciones o si es una columna que no es de caracteres.
SQL_DESC_CATALOG_NAME [IRD]
Este campo de registro SQLCHAR * de solo lectura contiene el catálogo de la tabla base que contiene la columna. El valor devuelto depende del controlador si la columna es una expresión o si la columna forma parte de una vista. Si el origen de datos no admite catálogos o el catálogo no se puede determinar, esta variable contiene una cadena vacía.
SQL_DESC_CONCISE_TYPE [Todos]
Este campo de encabezado SQLSMALLINT especifica el tipo de datos conciso para todos los tipos de datos, incluidos los tipos de datos datetime y interval.
Los valores de los campos SQL_DESC_CONCISE_TYPE, SQL_DESC_TYPE y SQL_DESC_DATETIME_INTERVAL_CODE son interdependientes. Cada vez que se establece uno de los campos, también se debe establecer el otro. SQL_DESC_CONCISE_TYPE se puede establecer mediante una llamada a SQLBindCol o SQLBindParameter o SQLSetDescField. SQL_DESC_TYPE se puede establecer mediante una llamada a SQLSetDescField o SQLSetDescRec.
Si SQL_DESC_CONCISE_TYPE se establece en un tipo de datos conciso distinto de un tipo de datos interval o datetime, el campo SQL_DESC_TYPE se establece en el mismo valor y el campo SQL_DESC_DATETIME_INTERVAL_CODE se establece en 0.
Si SQL_DESC_CONCISE_TYPE se establece en el tipo de datos datetime o interval conciso, el campo SQL_DESC_TYPE se establece en el tipo detallado correspondiente (SQL_DATETIME o SQL_INTERVAL) y el campo SQL_DESC_DATETIME_INTERVAL_CODE se establece en el subcódigo adecuado.
SQL_DESC_DATA_PTR [Descriptores de aplicación e IPD]
Este campo de registro SQLPOINTER apunta a una variable que contendrá el valor del parámetro (para APD) o el valor de columna (para ARD). Este campo es un campo diferido. No se usa en el momento en que se establece, pero el controlador usa en un momento posterior para recuperar datos.
La columna especificada por el campo SQL_DESC_DATA_PTR del ARD no está delimitada si el argumento TargetValuePtr de una llamada a SQLBindCol es un puntero nulo o si el campo SQL_DESC_DATA_PTR del ARD se establece mediante una llamada a SQLSetDescField o SQLSetDescRec a un puntero nulo. Otros campos no se ven afectados si el campo SQL_DESC_DATA_PTR está establecido en un puntero nulo.
Si la llamada a SQLFetch o SQLFetchScroll que rellena el búfer al que apunta este campo no devolvió SQL_SUCCESS o SQL_SUCCESS_WITH_INFO, el contenido del búfer no está definido.
Cada vez que se establece el campo SQL_DESC_DATA_PTR de un APD, ARD o IPD, el controlador comprueba que el valor del campo SQL_DESC_TYPE contiene uno de los tipos de datos ODBC C válidos o un tipo de datos específico del controlador, y que todos los demás campos que afectan a los tipos de datos son coherentes. Solicitar una comprobación de coherencia es el único uso del campo SQL_DESC_DATA_PTR de un IPD. En concreto, si una aplicación establece el campo SQL_DESC_DATA_PTR de un IPD y, posteriormente, llama a SQLGetDescField en este campo, no se devuelve necesariamente el valor que había establecido. Para obtener más información, vea "Comprobaciones de coherencia" en SQLSetDescRec.
SQL_DESC_DATETIME_INTERVAL_CODE [Todos]
Este campo de registro SQLSMALLINT contiene el subcódigo para el tipo de datos datetime o interval específico cuando el campo de SQL_DESC_TYPE está SQL_DATETIME o SQL_INTERVAL. Esto es así para los tipos de datos SQL y C. El código consta del nombre del tipo de datos con "CODE" sustituido por "TYPE" o "C_TYPE" (para los tipos datetime) o "CODE" sustituidos por "INTERVAL" o "C_INTERVAL" (para los tipos de intervalo).
Si SQL_DESC_TYPE y SQL_DESC_CONCISE_TYPE en un descriptor de aplicación se establecen en SQL_C_DEFAULT y el descriptor no está asociado a un identificador de instrucción, el contenido de SQL_DESC_DATETIME_INTERVAL_CODE no está definido.
Este campo se puede establecer para los tipos de datos datetime enumerados en la tabla siguiente.
| Tipos de datetime | DATETIME_INTERVAL_CODE |
|---|---|
| SQL_TYPE_DATE/SQL_C_TYPE_DATE | SQL_CODE_DATE |
| SQL_TYPE_TIME/SQL_C_TYPE_TIME | SQL_CODE_TIME |
| SQL_TYPE_TIMESTAMP/ SQL_C_TYPE_TIMESTAMP | SQL_CODE_TIMESTAMP |
Este campo se puede establecer para los tipos de datos interval enumerados en la tabla siguiente.
| Tipo de intervalo | DATETIME_INTERVAL_CODE |
|---|---|
| SQL_INTERVAL_DAY/SQL_C_INTERVAL_DAY | SQL_CODE_DAY |
| SQL_INTERVAL_DAY_TO_HOUR/ SQL_C_INTERVAL_DAY_TO_HOUR | SQL_CODE_DAY_TO_HOUR |
| SQL_INTERVAL_DAY_TO_MINUTE/SQL_C_INTERVAL_DAY_TO_MINUTE | SQL_CODE_DAY_TO_MINUTE |
| SQL_INTERVAL_DAY_TO_SECOND/SQL_C_INTERVAL_DAY_TO_SECOND | SQL_CODE_DAY_TO_SECOND |
| SQL_INTERVAL_HOUR/SQL_C_INTERVAL_HOUR | SQL_CODE_HOUR |
| SQL_INTERVAL_HOUR_TO_MINUTE/SQL_C_INTERVAL_HOUR_TO_MINUTE | SQL_CODE_HOUR_TO_MINUTE |
| SQL_INTERVAL_HOUR_TO_SECOND/SQL_C_INTERVAL_HOUR_TO_SECOND | SQL_CODE_HOUR_TO_SECOND |
| SQL_INTERVAL_MINUTE/SQL_C_INTERVAL_MINUTE | SQL_CODE_MINUTE |
| SQL_INTERVAL_MINUTE_TO_SECOND/SQL_C_INTERVAL_MINUTE_TO_SECOND | SQL_CODE_MINUTE_TO_SECOND |
| SQL_INTERVAL_MONTH/SQL_C_INTERVAL_MONTH | SQL_CODE_MONTH |
| SQL_INTERVAL_SECOND/ SQL_C_INTERVAL_SECOND | SQL_CODE_SECOND |
| SQL_INTERVAL_YEAR/SQL_C_INTERVAL_YEAR | SQL_CODE_YEAR |
| SQL_INTERVAL_YEAR_TO_MONTH/SQL_C_INTERVAL_YEAR_TO_MONTH | SQL_CODE_YEAR_TO_MONTH |
Para obtener más información sobre los intervalos de datos y este campo, vea Identificadores y descriptores de tipo de datos.
SQL_DESC_DATETIME_INTERVAL_PRECISION [Todo]
Este campo de registro SQLINTEGER contiene la precisión inicial del intervalo si el campo de SQL_DESC_TYPE está SQL_INTERVAL. Cuando el campo SQL_DESC_DATETIME_INTERVAL_CODE se establece en un tipo de datos interval, este campo se establece en la precisión inicial del intervalo predeterminado.
SQL_DESC_DISPLAY_SIZE [IRD]
Este campo de registro SQLINTEGER de solo lectura contiene el número máximo de caracteres necesarios para mostrar los datos de la columna.
SQL_DESC_FIXED_PREC_SCALE [Descriptores de implementación]
Este campo de registro SQLSMALLINT de solo lectura se establece en SQL_TRUE si la columna es una columna numérica exacta y tiene una precisión fija y una escala distinta de cero, o para SQL_FALSE si la columna no es una columna numérica exacta con una precisión y escala fijas.
SQL_DESC_INDICATOR_PTR [Descriptores de aplicación]
En ARDs, este campo de registro SQLLEN * apunta a la variable de indicador. Esta variable contiene SQL_NULL_DATA si el valor de columna es NULL. Para los APD, la variable de indicador se establece en SQL_NULL_DATA para especificar argumentos dinámicos NULL. De lo contrario, la variable es cero (a menos que los valores de SQL_DESC_INDICATOR_PTR y SQL_DESC_OCTET_LENGTH_PTR sean el mismo puntero).
Si el campo SQL_DESC_INDICATOR_PTR de un ARD es un puntero nulo, se impide que el controlador devuelva información sobre si la columna es NULL o no. Si la columna es NULL y SQL_DESC_INDICATOR_PTR es un puntero nulo, SQLSTATE 22002 (variable indicador necesaria pero no proporcionada) se devuelve cuando el controlador intenta rellenar el búfer después de una llamada a SQLFetch o SQLFetchScroll. Si la llamada a SQLFetch o SQLFetchScroll no devolvió SQL_SUCCESS o SQL_SUCCESS_WITH_INFO, el contenido del búfer no está definido.
El campo SQL_DESC_INDICATOR_PTR determina si se establece el campo al que apunta SQL_DESC_OCTET_LENGTH_PTR. Si el valor de datos de una columna es NULL, el controlador establece la variable de indicador en SQL_NULL_DATA. El campo al que apunta SQL_DESC_OCTET_LENGTH_PTR no se establece. Si no se encuentra un valor NULL durante la captura, el búfer al que apunta SQL_DESC_INDICATOR_PTR se establece en cero y el búfer al que apunta SQL_DESC_OCTET_LENGTH_PTR se establece en la longitud de los datos.
Si el campo SQL_DESC_INDICATOR_PTR de un APD es un puntero nulo, la aplicación no puede usar este registro descriptor para especificar argumentos NULL.
Este campo es un campo diferido: no se usa en el momento en que se establece, pero el controlador usa en un momento posterior para indicar nulabilidad (para ARD) o para determinar la nulabilidad (para APD).
SQL_DESC_LABEL [IRD]
Este campo de registro SQLCHAR * de solo lectura contiene la etiqueta de columna o el título. Si la columna no tiene una etiqueta, esta variable contiene el nombre de columna. Si la columna no tiene nombre y no está etiquetada, esta variable contiene una cadena vacía.
SQL_DESC_LENGTH [Todo]
Este campo de registro SQLULEN es la longitud máxima o real de una cadena de caracteres en caracteres o un tipo de datos binario en bytes. Es la longitud máxima de un tipo de datos de longitud fija o la longitud real de un tipo de datos de longitud variable. Su valor siempre excluye el carácter de terminación null que termina la cadena de caracteres. Para los valores cuyo tipo es SQL_TYPE_DATE, SQL_TYPE_TIME, SQL_TYPE_TIMESTAMP o uno de los tipos de datos de intervalo de SQL, este campo tiene la longitud en caracteres de la representación de cadena de caracteres del valor datetime o interval.
El valor de este campo puede ser diferente del valor de "length", tal como se define en ODBC 2*.x*. Para obtener más información, vea Apéndice D: Tipos de datos.
SQL_DESC_LITERAL_PREFIX [IRD]
Este campo de registro SQLCHAR * de solo lectura contiene el carácter o los caracteres que el controlador reconoce como prefijo para un literal de este tipo de datos. Esta variable contiene una cadena vacía para un tipo de datos para el que no se aplica un prefijo literal.
SQL_DESC_LITERAL_SUFFIX [IRD]
Este campo de registro SQLCHAR * de solo lectura contiene el carácter o los caracteres que el controlador reconoce como sufijo para un literal de este tipo de datos. Esta variable contiene una cadena vacía para un tipo de datos para el que no se aplica un sufijo literal.
SQL_DESC_LOCAL_TYPE_NAME [descriptores de implementación]
Este campo de registro SQLCHAR * de solo lectura contiene cualquier nombre localizado (idioma nativo) para el tipo de datos que puede ser diferente del nombre normal del tipo de datos. Si no hay ningún nombre localizado, se devuelve una cadena vacía. Este campo es solo para fines de visualización.
SQL_DESC_NAME [Descriptores de implementación]
Este campo de registro SQLCHAR * de un descriptor de fila contiene el alias de columna, si se aplica. Si no se aplica el alias de columna, se devuelve el nombre de columna. En cualquier caso, el controlador establece el campo SQL_DESC_UNNAMED en SQL_NAMED cuando establece el campo SQL_DESC_NAME. Si no hay ningún nombre de columna o alias de columna, el controlador devuelve una cadena vacía en el campo SQL_DESC_NAME y establece el campo SQL_DESC_UNNAMED en SQL_UNNAMED.
Una aplicación puede establecer el campo SQL_DESC_NAME de un IPD en un nombre de parámetro o alias para especificar parámetros de procedimiento almacenado por nombre. (Para obtener más información, vea Binding Parameters by Name (Named Parameters)). El campo SQL_DESC_NAME de un IRD es un campo de solo lectura; SQLSTATE HY091 (identificador de campo de descriptor no válido) se devolverá si una aplicación intenta establecerla.
En IPD, este campo no está definido si el controlador no admite parámetros con nombre. Si el controlador admite parámetros con nombre y es capaz de describir parámetros, el nombre del parámetro se devuelve en este campo.
SQL_DESC_NULLABLE [Descriptores de implementación]
En los IRD, este campo de registro SQLSMALLINT de solo lectura se SQL_NULLABLE si la columna puede tener valores NULL, SQL_NO_NULLS si la columna no tiene valores NULL o SQL_NULLABLE_UNKNOWN si no se sabe si la columna acepta valores NULL. Este campo pertenece a la columna del conjunto de resultados, no a la columna base.
En IPD, este campo siempre se establece en SQL_NULLABLE porque los parámetros dinámicos siempre aceptan valores NULL y no se pueden establecer mediante una aplicación.
SQL_DESC_NUM_PREC_RADIX [All]
Este campo SQLINTEGER contiene un valor de 2 si el tipo de datos del campo SQL_DESC_TYPE es un tipo de datos numérico aproximado, ya que el campo SQL_DESC_PRECISION contiene el número de bits. Este campo contiene un valor de 10 si el tipo de datos del campo SQL_DESC_TYPE es un tipo de datos numérico exacto, ya que el campo SQL_DESC_PRECISION contiene el número de dígitos decimales. Este campo se establece en 0 para todos los tipos de datos no numéricos.
SQL_DESC_OCTET_LENGTH [Todo]
Este campo de registro SQLLEN contiene la longitud, en bytes, de una cadena de caracteres o de un tipo de datos binario. Para los tipos binarios o caracteres de longitud fija, esta es la longitud real en bytes. Para los tipos binarios o caracteres de longitud variable, esta es la longitud máxima en bytes. Este valor siempre excluye el espacio del carácter de terminación NULL para los descriptores de implementación e incluye siempre el espacio para el carácter de terminación NULL para los descriptores de aplicación. Para los datos de la aplicación, este campo contiene el tamaño del búfer. En el caso de los APD, este campo solo se define para los parámetros de salida o entrada/salida.
SQL_DESC_OCTET_LENGTH_PTR [Descriptores de aplicación]
Este campo de registro DE SQLLEN * apunta a una variable que contendrá la longitud total en bytes de un argumento dinámico (para descriptores de parámetros) o de un valor de columna enlazado (para descriptores de fila).
Para un APD, este valor se omite para todos los argumentos excepto la cadena de caracteres y el binario; si este campo apunta a SQL_NTS, el argumento dinámico debe terminar en null. Para indicar que un parámetro enlazado será un parámetro data-at-execution, una aplicación establece este campo en el registro adecuado del APD en una variable que, en tiempo de ejecución, contendrá el valor SQL_DATA_AT_EXEC o el resultado de la macro SQL_LEN_DATA_AT_EXEC. Si hay más de un campo de este tipo, SQL_DESC_DATA_PTR se puede establecer en un valor que identifique de forma única el parámetro para ayudar a la aplicación a determinar qué parámetro se solicita.
Si el campo OCTET_LENGTH_PTR de un ARD es un puntero nulo, el controlador no devuelve información de longitud para la columna. Si el campo SQL_DESC_OCTET_LENGTH_PTR de un APD es un puntero nulo, el controlador supone que las cadenas de caracteres y los valores binarios están terminadas en null. (Los valores binarios no deben terminar en null, pero deben tener una longitud para evitar el truncamiento).
Si la llamada a SQLFetch o SQLFetchScroll que rellena el búfer al que apunta este campo no devolvió SQL_SUCCESS o SQL_SUCCESS_WITH_INFO, el contenido del búfer no está definido. Este campo es un campo diferido. No se usa en el momento en que se establece, pero el controlador lo usa más adelante para determinar o indicar la longitud del octeto de los datos.
SQL_DESC_PARAMETER_TYPE [IPD]
Este campo de registro SQLSMALLINT se establece en SQL_PARAM_INPUT para un parámetro de entrada, SQL_PARAM_INPUT_OUTPUT para un parámetro de entrada y salida, SQL_PARAM_OUTPUT para un parámetro de salida, SQL_PARAM_INPUT_OUTPUT_STREAM para un parámetro transmitido por entrada/salida o SQL_PARAM_OUTPUT_STREAM para un parámetro transmitido por secuencias de salida. Se establece en SQL_PARAM_INPUT de forma predeterminada.
Para un IPD, el campo se establece en SQL_PARAM_INPUT de forma predeterminada si el controlador no rellena automáticamente el IPD (el atributo de instrucción SQL_ATTR_ENABLE_AUTO_IPD es SQL_FALSE). Una aplicación debe establecer este campo en el IPD para los parámetros que no son parámetros de entrada.
SQL_DESC_PRECISION [Todos]
Este campo de registro SQLSMALLINT contiene el número de dígitos de un tipo numérico exacto, el número de bits de la mantisa (precisión binaria) para un tipo numérico aproximado o el número de dígitos del componente fraccionario de segundos para el SQL_TYPE_TIME, SQL_TYPE_TIMESTAMP o SQL_INTERVAL_SECOND tipo de datos. Este campo no está definido para todos los demás tipos de datos.
El valor de este campo puede ser diferente del valor de "precisión", tal y como se define en ODBC 2*.x*. Para obtener más información, vea Apéndice D: Tipos de datos.
SQL_DESC_ROWVER [descriptores de implementación]
Este campo SQLSMALLINTrecord indica si dbMS modifica automáticamente una columna cuando se actualiza una fila (por ejemplo, una columna del tipo "timestamp" en SQL Server). El valor de este campo de registro se establece en SQL_TRUE si la columna es una columna de control de versiones de fila y en SQL_FALSE de lo contrario. Este atributo de columna es similar a llamar a SQLSpecialColumns con IdentifierType de SQL_ROWVER para determinar si una columna se actualiza automáticamente.
SQL_DESC_SCALE [Todos]
Este campo de registro SQLSMALLINT contiene la escala definida para los tipos de datos decimales y numéricos. El campo no está definido para todos los demás tipos de datos.
El valor de este campo puede ser diferente del valor de "escala", tal como se define en ODBC 2*.x*. Para obtener más información, vea Apéndice D: Tipos de datos.
SQL_DESC_SCHEMA_NAME [IRD]
Este campo de registro SQLCHAR * de solo lectura contiene el nombre de esquema de la tabla base que contiene la columna. El valor devuelto depende del controlador si la columna es una expresión o si la columna forma parte de una vista. Si el origen de datos no admite esquemas o no se puede determinar el nombre del esquema, esta variable contiene una cadena vacía.
SQL_DESC_SEARCHABLE [IRD]
Este campo de registro SQLSMALLINT de solo lectura se establece en uno de los siguientes valores:
SQL_PRED_NONE si la columna no se puede usar en una cláusula WHERE . (Es el mismo que el valor de SQL_UNSEARCHABLE en ODBC 2*.x*).
SQL_PRED_CHAR si la columna se puede usar en una cláusula WHERE , pero solo con el predicado LIKE . (Es el mismo que el valor de SQL_LIKE_ONLY en ODBC 2*.x*).
SQL_PRED_BASIC si la columna se puede usar en una cláusula WHERE con todos los operadores de comparación excepto LIKE. (Es el mismo que el valor de SQL_EXCEPT_LIKE en ODBC 2*.x*).
SQL_PRED_SEARCHABLE si la columna se puede usar en una cláusula WHERE con cualquier operador de comparación.
SQL_DESC_TABLE_NAME [IRD]
Este campo de registro SQLCHAR * de solo lectura contiene el nombre de la tabla base que contiene esta columna. El valor devuelto depende del controlador si la columna es una expresión o si la columna forma parte de una vista.
SQL_DESC_TYPE [Todos]
Este campo de registro SQLSMALLINT especifica el tipo de datos SQL o C conciso para todos los tipos de datos excepto los tipos de datos datetime e interval. Para los tipos de datos datetime e interval, este campo especifica el tipo de datos detallado, que es SQL_DATETIME o SQL_INTERVAL.
Siempre que este campo contenga SQL_DATETIME o SQL_INTERVAL, el campo SQL_DESC_DATETIME_INTERVAL_CODE debe contener el subcódigo adecuado para el tipo conciso. Para los tipos de datos datetime, SQL_DESC_TYPE contiene SQL_DATETIME y el campo SQL_DESC_DATETIME_INTERVAL_CODE contiene un subcódigo para el tipo de datos datetime específico. Para los tipos de datos de intervalo, SQL_DESC_TYPE contiene SQL_INTERVAL y el campo SQL_DESC_DATETIME_INTERVAL_CODE contiene un subcódigo para el tipo de datos de intervalo específico.
Los valores de los campos SQL_DESC_TYPE y SQL_DESC_CONCISE_TYPE son interdependientes. Cada vez que se establece uno de los campos, también se debe establecer el otro. SQL_DESC_TYPE se puede establecer mediante una llamada a SQLSetDescField o SQLSetDescRec. SQL_DESC_CONCISE_TYPE se puede establecer mediante una llamada a SQLBindCol o SQLBindParameter o SQLSetDescField.
Si SQL_DESC_TYPE se establece en un tipo de datos conciso distinto de un tipo de datos interval o datetime, el campo SQL_DESC_CONCISE_TYPE se establece en el mismo valor y el campo SQL_DESC_DATETIME_INTERVAL_CODE se establece en 0.
Si SQL_DESC_TYPE se establece en el tipo de datos datetime o interval detallado (SQL_DATETIME o SQL_INTERVAL) y el campo SQL_DESC_DATETIME_INTERVAL_CODE se establece en el subcódigo adecuado, el campo SQL_DESC_CONCISE TYPE se establece en el tipo conciso correspondiente. Si se intenta establecer SQL_DESC_TYPE en uno de los tipos datetime o interval concisos, se devolverá SQLSTATE HY021 (información de descriptor incoherente).
Cuando el campo SQL_DESC_TYPE se establece mediante una llamada a SQLBindCol, SQLBindParameter o SQLSetDescField, los campos siguientes se establecen en los siguientes valores predeterminados, como se muestra en la tabla siguiente. Los valores de los campos restantes del mismo registro no están definidos.
| Valor de SQL_DESC_TYPE | Otros campos se establecen implícitamente |
|---|---|
| SQL_CHAR, SQL_VARCHAR, SQL_C_CHAR, SQL_C_VARCHAR | SQL_DESC_LENGTH se establece en 1. SQL_DESC_PRECISION se establece en 0. |
| SQL_DATETIME | Cuando SQL_DESC_DATETIME_INTERVAL_CODE se establece en SQL_CODE_DATE o SQL_CODE_TIME, SQL_DESC_PRECISION se establece en 0. Cuando se establece en SQL_DESC_TIMESTAMP, SQL_DESC_PRECISION se establece en 6. |
| SQL_DECIMAL, SQL_NUMERIC, SQL_C_NUMERIC | SQL_DESC_SCALE se establece en 0. SQL_DESC_PRECISION se establece en la precisión definida por la implementación para el tipo de datos correspondiente. Vea SQL a C: Numérico para obtener información sobre cómo enlazar manualmente un valor de SQL_C_NUMERIC. |
| SQL_FLOAT, SQL_C_FLOAT | SQL_DESC_PRECISION se establece en la precisión predeterminada definida por la implementación para SQL_FLOAT. |
| SQL_INTERVAL | Cuando SQL_DESC_DATETIME_INTERVAL_CODE se establece en un tipo de datos interval, SQL_DESC_DATETIME_INTERVAL_PRECISION se establece en 2 (la precisión inicial del intervalo predeterminado). Cuando el intervalo tiene un componente de segundos, SQL_DESC_PRECISION se establece en 6 (la precisión de intervalo de intervalo predeterminada). |
Cuando una aplicación llama a SQLSetDescField para establecer campos de un descriptor en lugar de llamar a SQLSetDescRec, la aplicación primero debe declarar el tipo de datos. Cuando lo hace, los demás campos indicados en la tabla anterior se establecen implícitamente. Si alguno de los valores establecidos implícitamente es inaceptable, la aplicación puede llamar a SQLSetDescField o SQLSetDescRec para establecer explícitamente el valor inaceptable.
SQL_DESC_TYPE_NAME [Descriptores de implementación]
Este campo de registro SQLCHAR * de solo lectura contiene el nombre de tipo dependiente del origen de datos (por ejemplo, "CHAR", "VARCHAR", etc.). Si el nombre del tipo de datos es desconocido, esta variable contiene una cadena vacía.
SQL_DESC_UNNAMED [descriptores de implementación]
El controlador establece este campo de registro SQLSMALLINT en un descriptor de fila en SQL_NAMED o SQL_UNNAMED cuando establece el campo SQL_DESC_NAME. Si el campo SQL_DESC_NAME contiene un alias de columna o si no se aplica el alias de columna, el controlador establece el campo SQL_DESC_UNNAMED en SQL_NAMED. Si una aplicación establece el campo SQL_DESC_NAME de un IPD en un nombre de parámetro o alias, el controlador establece el campo SQL_DESC_UNNAMED del IPD en SQL_NAMED. Si no hay ningún nombre de columna o alias de columna, el controlador establece el campo SQL_DESC_UNNAMED en SQL_UNNAMED.
Una aplicación puede establecer el campo SQL_DESC_UNNAMED de un IPD en SQL_UNNAMED. Un controlador devuelve SQLSTATE HY091 (identificador de campo de descriptor no válido) si una aplicación intenta establecer el campo SQL_DESC_UNNAMED de un IPD en SQL_NAMED. El campo SQL_DESC_UNNAMED de un IRD es de solo lectura; SQLSTATE HY091 (identificador de campo de descriptor no válido) se devolverá si una aplicación intenta establecerla.
SQL_DESC_UNSIGNED [descriptores de implementación]
Este campo de registro SQLSMALLINT de solo lectura se establece en SQL_TRUE si el tipo de columna no está firmado o no numérico, o SQL_FALSE si el tipo de columna está firmado.
SQL_DESC_UPDATABLE [IRD]
Este campo de registro SQLSMALLINT de solo lectura se establece en uno de los siguientes valores:
SQL_ATTR_READ_ONLY si la columna del conjunto de resultados es de solo lectura.
SQL_ATTR_WRITE si la columna del conjunto de resultados es de lectura y escritura.
SQL_ATTR_READWRITE_UNKNOWN si no se sabe si la columna del conjunto de resultados es actualizable o no.
SQL_DESC_UPDATABLE describe la portabilidad de la columna en el conjunto de resultados, no la columna de la tabla base. La portabilidad de la columna de la tabla base en la que se basa esta columna del conjunto de resultados puede ser diferente del valor de este campo. Si una columna es actualizable puede basarse en el tipo de datos, los privilegios de usuario y la definición del propio conjunto de resultados. Si no está claro si una columna es actualizable, se debe devolver SQL_ATTR_READWRITE_UNKNOWN.
Comprobaciones de coherencia
El controlador realiza automáticamente una comprobación de coherencia cada vez que una aplicación pasa un valor para el campo SQL_DESC_DATA_PTR del ARD, APD o IPD. Si alguno de los campos es incoherente con otros campos, SQLSetDescField devolverá SQLSTATE HY021 (información de descriptor incoherente). Para obtener más información, vea "Comprobación de coherencia" en SQLSetDescRec.
Funciones relacionadas
| 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 campo descriptor | Función SQLGetDescField |
| Obtención de varios campos descriptores | Función SQLGetDescRec |
| Establecimiento de varios campos descriptores | Función SQLSetDescRec |