SQLSetStmtAttr

Artículo
05/08/2013

El controlador ODBC de SQL Server Native Client no admite el modelo de cursor mixto (controlado por conjunto de claves/dinámico). Cualquier intento de establecer el tamaño del conjunto de claves mediante SQL_ATTR_KEYSET_SIZE generará un error si el conjunto de valores no es igual a 0.

La aplicación establece SQL_ATTR_ROW_ARRAY_SIZE en todas las instrucciones para declarar el número de filas devueltas en una llamada a las funciones SQLFetch o SQLFetchScroll. En las instrucciones que indican un cursor de servidor, el controlador utiliza SQL_ATTR_ROW_ARRAY_SIZE para determinar el tamaño del bloque de filas que genera el servidor con el fin de satisfacer una solicitud de captura del cursor. Dentro del tamaño de bloque de un cursor dinámico, la pertenencia y el orden de las filas son fijos si el nivel de aislamiento de la transacción es suficiente para asegurar la posibilidad de repetir las lecturas de las transacciones confirmadas. El cursor es completamente dinámico fuera del bloque indicado por este valor. El tamaño del bloque del cursor de servidor es completamente dinámico y se puede cambiar en cualquier punto del procesamiento de captura.

SQLSetStmtAttr y parámetros con valores de tabla

SQLSetStmtAttr se puede utilizar para establecer SQL_SOPT_SS_PARAM_FOCUS en el descriptor de parámetros de la aplicación (APD) antes de tener acceso a los campos descriptores de las columnas de parámetros con valores de tabla.

Si se intenta establecer SQL_SOPT_SS_PARAM_FOCUS en el ordinal de un parámetro que no es un parámetro con valores de tabla, SQLSetStmtAttr devuelve SQL_ERROR y se crea un registro de diagnóstico con SQLSTATE = HY024 y el mensaje "Valor de atributo no válido". SQL_SOPT_SS_PARAM_FOCUS no cambia cuando se devuelve SQL_ERROR.

Al establecer SQL_SOPT_SS_PARAM_FOCUS en 0, se restaura el acceso a los registros descriptores para parámetros.

SQLSetStmtAttr también se puede utilizar para establecer SQL_SOPT_SS_NAME_SCOPE. Para obtener más información, vea la sección sobre SQL_SOPT_SS_NAME_SCOPE en este mismo tema.

Para obtener más información, vea Metadatos de parámetros con valores de tabla para instrucciones preparadas.

Para obtener más información acerca de los parámetros con valores de tabla, vea Parámetros con valores de tabla (ODBC).

Compatibilidad de SQLSetStmtAttr con columnas dispersas

SQLSetStmtAttr se puede utilizar para establecer SQL_SOPT_SS_NAME_SCOPE. Para obtener más información, vea la sección sobre SQL_SOPT_SS_NAME_SCOPE en este mismo tema. Para obtener más información sobre las columnas dispersas, vea Compatibilidad con columnas dispersas (ODBC).

Atributos de instrucción

El controlador ODBC de SQL Server Native Client también admite los siguientes atributos de instrucción específicos del controlador.

SQL_SOPT_SS_CURSOR_OPTIONS

El atributo SQL_SOPT_SS_CURSOR especifica si el controlador utilizará las opciones de rendimiento específicas del controlador en cursores. No se permite SQLGetData cuando se establecen estas opciones. El valor predeterminado es SQL_CO_OFF. El valor ValuePtr es de tipo SQLLEN.

Valor ValuePtr	Descripción
SQL_CO_OFF	Predeterminado. Deshabilita los cursores de solo avance rápido y solo lectura y la captura automática, y habilita SQLGetData en cursores de solo avance y solo lectura. Si SQL_SOPT_SS_CURSOR_OPTIONS está establecido en SQL_CO_OFF, el tipo de cursor no cambiará. Es decir, el cursor de solo avance rápido seguirá siendo un cursor de solo avance rápido. Para cambiar el tipo de cursor, la aplicación debe establecer ahora un tipo de cursor diferente mediante SQLSetStmtAttr/SQL_ATTR_CURSOR_TYPE.
SQL_CO_FFO	Habilita los cursores de solo avance rápido y solo lectura, y deshabilita SQLGetData en cursores de solo avance y solo lectura.
SQL_CO_AF	Habilita la opción de captura automática en cualquier tipo de cursor. Cuando se establece esta opción para un identificador de instrucciones, SQLExecute o SQLExecDirect generarán un SQLFetchScroll (SQL_FIRST) implícito. El cursor se abre y se devuelve el primer lote de filas en un único viaje de ida y vuelta al servidor.
SQL_CO_FFO_AF	Habilita los cursores de solo avance rápido con la opción de captura automática. Es lo mismo que si se especifican SQL_CO_AF y SQL_CO_FFO.

Cuando se establecen estas opciones, el servidor cierra el cursor automáticamente en cuanto detecta que se ha capturado la última fila. La aplicación debe seguir llamando a SQLFreeStmt (SQL_CLOSE) o SQLCloseCursor, pero el controlador no tiene que enviar la notificación de cierre al servidor.

Si la lista de selección contiene una columna text, ntext o image, el cursor de solo avance rápido se convierte en un cursor dinámico y se permite SQLGetData.

SQL_SOPT_SS_DEFER_PREPARE

El atributo SQL_SOPT_SS_DEFER_PREPARE determina si la instrucción se prepara inmediatamente o se difiere hasta que se ejecuta SQLExecute, SQLDescribeCol o SQLDescribeParam. En SQL Server 7.0 y versiones anteriores, esta propiedad se omite (no hay preparación diferida). El valor ValuePtr es de tipo SQLLEN.

Valor ValuePtr	Descripción
SQL_DP_ON	Predeterminado: Después de llamar a SQLPrepare Function, la preparación de instrucciones se difiere hasta que se llama a SQLExecute o se ejecuta la operación de metapropiedad (SQLDescribeCol o SQLDescribeParam).
SQL_DP_OFF	La instrucción se prepara en cuanto se ejecuta SQLPrepare.

SQL_SOPT_SS_REGIONALIZE

El atributo SQL_SOPT_SS_REGIONALIZE se utiliza para determinar la conversión de datos en el nivel de instrucción. El atributo hace que el controlador respete la configuración regional del cliente al convertir los valores de fecha, hora y moneda en cadenas de caracteres. La conversión solo se hace de tipos de datos nativos de SQL Server a cadenas de caracteres.

El valor ValuePtr es de tipo SQLLEN.

Valor ValuePtr	Descripción
SQL_RE_OFF	Predeterminado. El controlador no convierte los datos de fecha, hora y moneda a datos de cadenas de caracteres utilizando la configuración regional del cliente.
SQL_RE_ON	El controlador utiliza la configuración regional del cliente al convertir los datos de fecha, hora y moneda en datos de cadenas de caracteres.

La configuración de conversión regional se aplica a los tipos de datos de moneda, numéricos, de fecha y de hora. La configuración de conversión solamente es aplicable a la conversión de salida cuando los valores de moneda, numéricos, de fecha o de hora se convierten en cadenas de caracteres.

[!NOTA]

Si la opción de instrucción SQL_SOPT_SS_REGIONALIZE está activada, el controlador utiliza la configuración regional del Registro para el usuario actual. El controlador no respeta la configuración regional del subproceso actual si la aplicación la establece, por ejemplo, mediante una llamada a SetThreadLocale.

Modificar el comportamiento regional de un origen de datos puede producir errores en la aplicación. Una aplicación que analiza cadenas de fecha y espera que las cadenas de fecha aparezcan tal y como se definen en ODBC, podría verse afectada negativamente por la modificación de este valor.

SQL_SOPT_SS_TEXTPTR_LOGGING

El atributo SQL_SOPT_SS_TEXTPTR_LOGGING alterna el registro de operaciones en las columnas que contienen datos text o image. El valor ValuePtr es de tipo SQLLEN.

Valor ValuePtr	Descripción
SQL_TL_OFF	Deshabilita el registro de operaciones realizadas en datos text e image.
SQL_TL_ON	Predeterminado. Habilita el registro de operaciones realizadas en datos text e image.

SQL_SOPT_SS_HIDDEN_COLUMNS

El atributo SQL_SOPT_SS_HIDDEN_COLUMNS expone, en el conjunto de resultados, las columnas ocultas en una instrucción SELECT FOR BROWSE de SQL Server. El controlador no expone estas columnas de forma predeterminada. El valor de ValuePtr es de tipo SQLLEN.

Valor ValuePtr	Descripción
SQL_HC_OFF	Predeterminado. Las columnas FOR BROWSE se ocultan del conjunto de resultados.
SQL_HC_ON	Expone las columnas FOR BROWSE.

SQL_SOPT_SS_QUERYNOTIFICATION_MSGTEXT

El atributo SQL_SOPT_SS_QUERYNOTIFICATION_MSGTEXT devuelve el texto del mensaje de la solicitud de notificación de consulta.

SQL_SOPT_SS_QUERYNOTIFICATION_OPTIONS

El atributo SQL_SOPT_SS_QUERYNOTIFICATION_OPTIONS especifica las opciones utilizadas para la solicitud de notificación de consulta. Se especifican en una cadena con sintaxis name=value como se indica a continuación. La aplicación es la responsable de la creación del servicio y de la lectura de las notificaciones fuera de la cola.

La sintaxis de la cadena de opciones de notificaciones de consulta es:

service=<service-name>[;(local database=<database>|broker instance=<broker instance>)]

Por ejemplo:

service=mySSBService;local database=mydb

SQL_SOPT_SS_QUERYNOTIFICATION_TIMEOUT

El atributo SQL_SOPT_SS_QUERYNOTIFICATION_TIMEOUT especifica el número de segundos que va a seguir estando activa la notificación de consulta. El valor predeterminado es de 432000 segundos (5 días). El valor ValuePtr es de tipo SQLLEN.

SQL_SOPT_SS_PARAM_FOCUS

El atributo SQL_SOPT_SS_PARAM_FOCUS especifica el foco para las llamadas posteriores a SQLBindParameter, SQLGetDescField, SQLSetDescField, SQLGetDescRec y SQLSetDescRec.

El tipo para SQL_SOPT_SS_PARAM_FOCUS es SQLULEN.

El valor predeterminado es 0, lo que significa que estas llamadas direccionan parámetros que corresponden a marcadores de parámetros en la instrucción SQL. Cuando se establecen en el número de parámetro de un parámetro con valores de tabla, estas llamadas direccionan columnas de ese parámetro con valores de tabla. Cuando se establece en un valor que no es el número de parámetro de un parámetro con valores de tabla, estas llamadas devuelven el error IM020: "El foco del parámetro no hace referencia a un parámetro de valores de tabla".

SQL_SOPT_SS_NAME_SCOPE

El atributo SQL_SOPT_SS_NAME_SCOPE especifica el ámbito de nombres para las llamadas posteriores a funciones de catálogo. El conjunto de resultados devuelto por SQLColumns depende del valor de SQL_SOPT_SS_NAME_SCOPE.

El tipo para SQL_SOPT_SS_NAME_SCOPE es SQLULEN.

Valor ValuePtr	Descripción
SQL_SS_NAME_SCOPE_TABLE	Predeterminado. Cuando se utilizan parámetros con valores de tabla, indica que se deben devolver metadatos para las tablas reales. Si se utiliza la característica de columnas dispersas, SQLColumns solo devolverá columnas que no sean miembros del column_set disperso.
SQL_SS_NAME_SCOPE_TABLE_TYPE	Indica que la aplicación requiere metadatos para un tipo de tabla, en lugar de una tabla real (las funciones de catálogo deben devolver metadatos para los tipos de tabla). A continuación, la aplicación pasa el TYPE_NAME del parámetro con valores de tabla como parámetro TableName.
SQL_SS_NAME_SCOPE_EXTENDED	Cuando se utiliza la característica de columnas dispersas, SQLColumns devuelve todas las columnas, sin tener en cuenta la pertenencia al column_set.
SQL_SS_NAME_SCOPE_SPARSE_COLUMN_SET	Si se utiliza la característica de columnas dispersas, SQLColumns solo devuelve columnas que no sean miembros del column_set disperso.
SQL_SS_NAME_SCOPE_DEFAULT	Igual que SQL_SS_NAME_SCOPE_TABLE.

SS_TYPE_CATALOG_NAME y SS_TYPE_SCHEMA_NAME se utilizan con los parámetros SchemaName y CatalogName respectivamente para identificar el catálogo y el esquema para el parámetro con valores de tabla. Cuando una aplicación ha terminado de recuperar los metadatos para los parámetros con valores de tabla, debe volver a establecer SQL_SOPT_SS_NAME_SCOPE en su valor predeterminado de SQL_SS_NAME_SCOPE_TABLE.

Si SQL_SOPT_SS_NAME_SCOPE está establecido en SQL_SS_NAME_SCOPE_TABLE, las consultas a los servidores vinculados producen un error. Las llamadas a SQLColumns o SQLPrimaryKeys con un catálogo que contenga un componente del servidor no podrán realizarse.

Si intenta establecer SQL_SOPT_SS_NAME_SCOPE en un valor no válido, se devuelve SQL_ERROR y se genera un registro de diagnóstico con SQLSTATE HY024 y el mensaje "Valor de atributo no válido".

Si se llama a una función de catálogo que no sea SQLTables, SQLColumns o SQLPrimaryKeys y SQL_SOPT_SS_NAME_SCOPE tiene un valor distinto de SQL_SS_NAME_SCOPE_TABLE, se devuelve SQL_ERROR. Se genera un registro de diagnóstico con SQLSTATE HY010 y el mensaje "Error en la secuencia de función (SQL_SOPT_SS_NAME_SCOPE no está establecido en SQL_SS_NAME_SCOPE_TABLE)".

Compartir a través de