Función JetSetColumn

Se aplica a: Windows | Windows Server

Función JetSetColumn

La función JetSetColumn modifica un único valor de columna en un registro modificado que se va a insertar o para actualizar el registro actual. Puede sobrescribir un valor existente, agregar un nuevo valor a una secuencia de valores en una columna con varios valores, quitar un valor de una secuencia de valores en una columna multivalor o actualizar todo o parte de un valor largo, una columna de tipo JET_coltypLongText o JET_coltypLongBinary.

    JET_ERR JET_API JetSetColumn(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in          JET_COLUMNID columnid,
      __in_opt      const void* pvData,
      __in          unsigned long cbData,
      __in          JET_GRBIT grbit,
      __in_opt      JET_SETINFO* psetinfo
    );

Parámetros

sesid

La sesión que se va a usar para esta llamada.

tableid

Cursor que se va a usar para esta llamada.

columnid

La JET_COLUMNID de la columna que se va a recuperar. Como alternativa, se puede proporcionar un valor columnid de 0 (cero). Cuando se da columnid 0 (cero), todas las columnas etiquetadas, las columnas dispersas y multivalor se tratan como una sola columna. Esto facilita la recuperación de todas las columnas dispersas que están presentes en un registro.

pvData

Búfer de entrada que contiene datos que se van a usar para el valor de columna.

cbData

Tamaño en bytes del búfer de entrada.

grbit

Un grupo de bits que contienen las opciones que se usarán para esta llamada, que incluyen cero o más de lo siguiente:

Valor	Significado
JET_bitSetAppendLV	Esta opción se usa para anexar datos a una columna de tipo JET_coltypLongText o JET_coltypLongBinary. El mismo comportamiento se puede lograr mediante la determinación del tamaño del valor largo existente y la especificación de ibLongValue en psetinfo. Sin embargo, es más sencillo usar este grbit , ya que no es necesario conocer el tamaño del valor de columna existente.
JET_bitSetOverwriteLV	Esta opción se usa para reemplazar el valor long existente por los datos recién proporcionados. Cuando se usa esta opción, es como si el valor largo existente se hubiera establecido en 0 (cero) longitud antes de establecer los nuevos datos.
JET_bitSetRevertToDefaultValue	Esta opción solo es aplicable a las columnas etiquetadas, dispersas o con varios valores. Hace que la columna devuelva el valor de columna predeterminado en las operaciones posteriores de recuperación de columna. Se quitan todos los valores de columna existentes.
JET_bitSetSeparateLV	Esta opción se usa para forzar que un valor largo, columnas de tipo JET_coltypLongText o JET_coltypLongBinary, se almacenen por separado del resto de los datos de registro. Esto ocurre normalmente cuando el tamaño del valor largo impide que se almacene con los datos de registro restantes. Sin embargo, esta opción se puede usar para forzar que el valor largo se almacene por separado. Tenga en cuenta que los valores largos de cuatro bytes de tamaño menor no se pueden forzar a ser independientes. En tales casos, se omite la opción.
JET_bitSetSizeLV	Esta opción se usa para interpretar el búfer de entrada como un número entero de bytes para establecer como la longitud del valor largo descrito por el columnid especificado y, si se proporciona, el número de secuencia en psetinfo-itagSequence>. Si el tamaño especificado es mayor que el valor de columna existente, la columna se extenderá con 0s. Si el tamaño es menor que el valor de columna existente, el valor se truncará.
JET_bitSetUniqueMultiValues	Esta opción se usa para exigir que todos los valores de una columna con varios valores sean distintos. Esta opción compara los datos de columna de origen, sin ninguna transformación, con otros valores de columna existentes y se devuelve un error si se encuentra un duplicado. Si se proporciona esta opción, JET_bitSetAppendLV, JET_bitSetOverwriteLV y JET_bitSetSizeLV tampoco se pueden proporcionar.
JET_bitSetUniqueNormalizedMultiValues	Esta opción se usa para exigir que todos los valores de una columna con varios valores sean distintos. Esta opción compara la transformación normalizada de clave de los datos de columna, con otros valores de columna existentes transformados de forma similar y se devuelve un error si se encuentra un duplicado. Si se proporciona esta opción, JET_bitSetAppendLV, JET_bitSetOverwriteLV y JET_bitSetSizeLV tampoco se pueden proporcionar.
JET_bitSetZeroLength	Esta opción se usa para establecer un valor en longitud cero. Normalmente, un valor de columna se establece en NULL pasando un cbMax de 0 (cero). Sin embargo, para algunos tipos, como JET_coltypText, un valor de columna puede ser de 0 (cero) longitud en lugar de NULL, y esta opción se usa para diferenciar entreNULL y 0 (cero) longitud. Nota En general, si la columna es una columna de longitud fija, este bit se omite y la columna se establece en NULL. Sin embargo, si la columna es una columna etiquetada de longitud fija, la longitud de la columna se establece en 0. Cuando la columna etiquetada de longitud fija se establece en 0 longitud, intenta recuperar la columna con JetRetrieveColumn o JetRetrieveColumns se realizará correctamente, pero la longitud real que se devuelve en el parámetro cbActual es 0.
JET_bitSetIntrinsicLV	Esta opción se usa para almacenar todo el valor largo en el registro.
JET_bitSetCompressed	Esta opción se usa para intentar la compresión de datos al almacenar los datos. Windows 7: JET_bitSetCompressed se introduce en Windows 7.
JET_bitSetUncompressed	Esta opción no se usa para intentar la compresión al almacenar los datos. Windows 7: JET_bitSetUnCompressed se introduce en Windows 7.

psetinfo

Puntero a parámetros de entrada opcionales que se pueden establecer para esta función mediante la estructura JET_SETINFO .

Si psetinfo se proporciona como NULL , la función se comporta como si se proporcionara una itagSequence de 1 y un ibLongValue de 0 (cero). Esto hace que el conjunto de columnas establezca el primer valor de una columna con varios valores y que establezca datos largos a partir del desplazamiento 0 (cero).

Se pueden establecer las siguientes opciones para este parámetro:

Valor	Significado
ibLongValue	Desplazamiento binario en un valor de columna largo donde deben comenzar los datos establecidos.
itagSequence	Número de secuencia del valor de columna multivalor deseado que se va a establecer. Si itagSequence se establece en 0 (cero), el valor proporcionado debe anexarse al final de la secuencia de valores multivalor. Si el número de secuencia proporcionado es mayor que el último valor multivalor existente, se anexará de nuevo el valor especificado al final de la secuencia de valores. Si el número de secuencia corresponde a un valor existente, ese valor se reemplaza por el valor especificado.

Valor devuelto

Esta función devuelve el JET_ERR tipo de datos con uno de los siguientes códigos de retorno. Para obtener más información sobre los posibles errores de ESE, vea Extensible Storage Engine Errors and Error Handling Parameters.

Código devuelto	Descripción
JET_errSuccess	La operación se ha completado correctamente.
JET_errBadColumnId	El identificador de columna especificado está fuera de los límites legales de un identificador de columna.
JET_errClientRequestToStopJetService	No es posible completar la operación porque toda la actividad de la instancia asociada a la sesión ha dejado de funcionar como resultado de una llamada a JetStopService.
JET_errColumnNotFound	La columna descrita por el columnid especificado no existe en la tabla.
JET_errColumnNotUpdatable	Se intentó actualizar un valor largo durante una operación de actualización original de la eliminación de copia de inserción.
JET_errColumnTooBig	Los datos de valor de columna especificados en el búfer de entrada superan la limitación de tamaño natural para una columna de longitud fija o configurada para columnas binarias o texto de longitud fija. Este error también se devuelve al pasar más de 1024 bytes de datos para una columna larga y establecer la marca de JET_bitSetIntrinsicLV.
JET_errInstanceUnavailable	No es posible completar la operación porque la instancia asociada a la sesión ha encontrado un error irrecuperable que requiere que se revoque el acceso a todos los datos para proteger la integridad de esos datos. Windows XP: Este error solo lo devolverá Windows XP y versiones posteriores.
JET_errInvalidBufferSize	El tamaño de datos del valor de columna especificado no coincide con lo que es natural para el tipo de datos de longitud fija.
JET_errInvalidColumnType	Se intentó actualizar una columna de incremento automático durante una operación de inserción o actualización, o para actualizar una columna de versión durante una operación de reemplazo.
JET_errInvalidgrbit	Las opciones proporcionadas son desconocidas o una combinación ilegal de la configuración de bits conocida.
JET_errInvalidParameter	La estructura psetinfo-cbStruct> especificada no es un tamaño válido para la estructura de JET_SETINFO .
JET_errMultiValuedDuplicate	La operación establecer columna intentó crear un valor duplicado y especificó JET_bitSetUniqueMultiValues o JET_bitSetUniqueNormalizedMultiValues.
JET_errNotInitialized	No es posible completar la operación porque la instancia asociada a la sesión aún no se ha inicializado.
JET_errNotInTransaction	Se intentó actualizar un valor de columna largo cuando la sesión de llamada no estaba en una transacción.
JET_errNullInvalid	Se intentó establecer una columna que no es NULL en NULL.
JET_errColumnIllegalNull	Igual que JET_errNullInvalid.
JET_errRecordTooBig	No se pudo establecer el valor de la columna en el valor del búfer de entrada porque habría provocado que el registro superara su limitación de tamaño de página relacionada. Las columnas de tipo JET_coltypLongText o JET_coltypLongBinary se pueden almacenar por separado de los datos de registro restantes. Sin embargo, otras columnas deben almacenarse con el registro y pueden hacer que se supere la limitación del tamaño del registro. Incluso las columnas largas requieren 5 bytes de espacio dentro del registro como una vinculación y esto también puede provocar que se devuelva JET_errRecordTooBig.
JET_errRestoreInProgress	No es posible completar la operación porque una operación de restauración está en curso en la instancia asociada a la sesión.
JET_errSessionSharingViolation	No se puede usar la misma sesión para más de un subproceso al mismo tiempo. Windows XP: Este error solo lo devolverá Windows XP y versiones posteriores.
JET_errTermInProgress	No es posible completar la operación porque la instancia asociada a la sesión se está cerrando.
JET_errUpdateNotPrepared	El cursor no está actualmente en proceso de insertar un nuevo registro o actualizar un registro existente.
JET_errVersionStoreOutOfMemory	Este error se producirá cuando el tamaño configurado del almacén de versiones no sea suficiente para contener todas las actualizaciones pendientes.
JET_wrnColumnMaxTruncated	El valor de columna del búfer de entrada superó la longitud máxima configurada para una columna de longitud variable y se truncaba.

Si se ejecuta correctamente, la parte deseada de un valor de columna para la columna especificada se establece con los datos copiados del búfer de entrada. Es posible que el conjunto de datos se haya truncado si superó la longitud máxima especificada para una columna de longitud variable.

Si se produce un error, la ubicación del cursor se deja sin cambios y no se actualiza ningún dato de valor de columna en el búfer de copia.

Comentarios

Establecer valores largos, los valores de las columnas JET_coltypLongBinary de tipo JET_coltypLongText o JET_coltypLongBinary, solo deben realizarse cuando la sesión de llamada se encuentra en una transacción. Si la sesión de llamada no está en una transacción, las modificaciones en valores largos que se almacenan por separado se pueden confirmar completamente incluso cuando la operación de actualización se cancele posteriormente. Si la sesión de llamada está en una transacción, los efectos de la actualización se pueden revertir completamente cancelando la actualización y revieriendo la transacción de sesión.

Las actualizaciones de índice no se realizan como resultado de las operaciones de JetSetColumn . En su lugar, los índices solo se actualizan después de que se completen todas las modificaciones de columna y se llame a JetUpdate . Esto permite la actualización más eficaz de los índices cuando los índices implican más de una columna que se está modificando.

Un registro tiene un tamaño limitado en función del tamaño de la página de la base de datos. Los valores largos del registro de más de cinco bytes se almacenarán separados del registro si los datos del registro superan su límite como resultado de una operación JetSetColumn . El error JET_errRecordTooBig solo se devolverá después de que todos los datos de columna de registro separados se hayan almacenado por separado del registro y el registro siga superando el límite de tamaño del registro.

Requisitos

Requisito	Value
Cliente	Requiere Windows Vista, Windows XP o Windows 2000 Professional.
Servidor	Requiere Windows Server 2008, Windows Server 2003 o Windows 2000 Server.
Encabezado	Declarado en Esent.h.
Library	Use ESENT.lib.
Archivo DLL	Requiere ESENT.dll.

Consulte también

JET_COLUMNID
JET_ERR
JET_SESID
JET_TABLEID
JET_SETINFO
JetRetrieveColumn
JetSetColumns