Función JetRetrieveColumn

Se aplica a: Windows | Windows Server

Función JetRetrieveColumn

La función JetRetrieveColumn recupera un único valor de columna del registro actual. El registro es ese registro asociado a la entrada de índice en la posición actual del cursor. Como alternativa, esta función puede recuperar una columna de un registro que se crea en el búfer de copia del cursor. Esta función también puede recuperar datos de columna de una entrada de índice que haga referencia al registro actual. Además de recuperar el valor real de la columna, también se puede usar JetRetrieveColumn para recuperar el tamaño de una columna, antes de recuperar los propios datos de columna para que los búferes de aplicación se puedan ajustar correctamente.

    JET_ERR JET_API JetRetrieveColumn(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in          JET_COLUMNID columnid,
      __out_opt     void* pvData,
      __in          unsigned long cbData,
      __out_opt     unsigned long* pcbActual,
      __in          JET_GRBIT grbit,
      __in_out_opt  JET_RETINFO* pretinfo
    );

Parámetros

sesid

Sesión que se va a usar para esta llamada.

tableid

Cursor que se va a usar para esta llamada.

columnid

El JET_COLUMNID de la columna que se va a recuperar.

Se puede proporcionar un valor columnid de 0 (cero) que no hace referencia a ninguna columna individual. Cuando se da columnid 0 (cero), todas las columnas etiquetadas, dispersas y con varios valores se tratan como una sola columna. Esto facilita la recuperación de todas las columnas dispersas presentes en un registro.

pvData

Búfer de salida que recibe el valor de la columna.

cbData

Tamaño máximo, en bytes, del búfer de salida.

pcbActual

Recibe el tamaño real, en bytes, del valor de la columna.

Si este parámetro es NULL, no se devolverá el tamaño real del valor de columna.

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:

Value

Significado

JET_bitRetrieveCopy

Esta marca hace que la columna recupere el valor modificado en lugar del valor original. Si el valor no se ha modificado, se recupera el valor original. De esta manera, se puede recuperar un valor que aún no se ha insertado o actualizado durante el funcionamiento de la inserción o actualización de un registro.

JET_bitRetrieveFromIndex

Esta opción se usa para recuperar valores de columna del índice, si es posible, sin tener acceso al registro. De esta manera, se puede evitar la carga innecesaria de registros cuando los datos necesarios están disponibles en las entradas de índice. En los casos en los que no se pueda recuperar el valor de columna original del índice, debido a transformaciones irreversibles o truncamiento de datos, se tendrá acceso al registro y se recuperarán los datos como normales. Se trata de una opción de rendimiento y solo se debe especificar cuando es probable que el valor de columna se pueda recuperar del índice. Esta opción no se debe especificar si el índice actual es el índice agrupado, ya que las entradas de índice para el clúster o el índice principal son los propios registros. Este bit no se puede establecer si también se establece JET_bitRetrieveFromPrimaryBookmark.

JET_bitRetrieveFromPrimaryBookmark

Esta opción se usa para recuperar valores de columna del marcador de índice y puede diferir del valor de índice cuando una columna aparece tanto en el índice principal como en el índice actual. Esta opción no se debe especificar si el índice actual es el índice agrupado o principal. Este bit no se puede establecer si también se establece JET_bitRetrieveFromIndex.

JET_bitRetrieveTag

Esta opción se usa para recuperar el número de secuencia de un valor de columna de varios valores en pretinfo-itagSequence>. El campo itagSequence suele ser una entrada para recuperar valores de columna con varios valores de un registro. Sin embargo, al recuperar valores de un índice, también es posible asociar la entrada de índice a un número de secuencia determinado y recuperar también este número de secuencia. Recuperar el número de secuencia puede ser una operación costosa y solo debe realizarse si es necesario.

JET_bitRetrieveNull

Esta opción se usa para recuperar valores NULL de columna multivalor. Si no se especifica esta opción, se omitirán automáticamente los valores NULL de columna multivalor.

JET_bitRetrieveIgnoreDefault

Esta opción afecta solo a las columnas de varios valores y hace que se devuelva un valor NULL cuando el número de secuencia solicitado es 1 y no hay valores establecidos para la columna en el registro.

JET_bitRetrieveLongId

Esta marca es solo para uso interno y no está pensada para usarse en la aplicación.

JET_bitRetrieveLongValueRefCount

Esta marca es solo para uso interno y no está pensada para usarse en la aplicación.

JET_bitRetrieveTuple

Esta marca permitirá la recuperación de un segmento de tupla del índice. Este bit debe especificarse con JET_bitRetrieveFromIndex.

pretinfo

Si pretinfo 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 la recuperación de columnas recupere el primer valor de una columna con varios valores y recupere datos largos en el desplazamiento 0 (cero).

Este parámetro se usa para proporcionar uno o varios de los siguientes elementos:

Value

Significado

ibLongValue

Proporciona un desplazamiento binario en un valor de columna larga al recuperar una parte de un valor de columna.

itagSequence

Proporciona el número de secuencia del valor de columna multivalor deseado. Tenga en cuenta que este campo solo se establece si se especifica el JET_bitRetrieveTag. De lo contrario, no se modifica.

columnidNextTagged

Devuelve el identificador de columna del valor de columna devuelto al recuperar todas las columnas etiquetadas, dispersas y multivalor, mediante el paso de columnid de 0 (cero).

Valor devuelto

Esta función devuelve el tipo de datos JET_ERR 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_errBadItagSequence

Se ha pasado un valor de número de secuencia de columnas de varios valores no válido en pretinfo-itagSequence>. Los valores válidos para los números de secuencia de valores de columna multivalor son 1 o superior. Un valor de 0 (cero) no es válido para esta función.

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_errIndexTuplesCannotRetrieveFromIndex

Las columnas indizadas como subcadenas no se pueden recuperar del índice, ya que solo una pequeña parte de la columna suele estar presente en cada entrada de índice.

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. Este error solo se devolverá en Windows XP y versiones posteriores.

JET_errInvalidBufferSize

En algunos casos, el búfer especificado para la columna de recuperación debe tener el tamaño suficiente para devolver cualquier cantidad del valor de columna. Por ejemplo, las columnas actualizables de custodia se ajustan para que sean coherentes para el contexto transaccional de la sesión de llamada y este ajuste requiere el búfer proporcionado por el autor de la llamada. Si se proporciona espacio en búfer insuficiente, se devuelve JET_errInvalidBufferSize y no se devuelve ningún dato de columna.

JET_errInvalidParameter

Uno o varios de los parámetros especificados son incorrectos. Esto puede ocurrir si retinfo.cbStruct es menor que el tamaño de JET_RETINFO.

JET_errInvalidgrbit

Las opciones proporcionadas son desconocidas o una combinación ilegal de la configuración de bits conocida.

JET_errNoCurrentRecord

El cursor no se coloca en un registro. Esto puede ocurrir por diversos motivos. Por ejemplo, esto ocurrirá si el cursor se coloca actualmente después del último registro del índice actual.

JET_errNotInitialized

No es posible completar la operación porque la instancia asociada a la sesión aún no se ha inicializado.

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_wrnBufferTruncated

No se pudo recuperar el valor de columna completo porque el búfer especificado es menor que el tamaño de la columna.

JET_wrnColumnNull

El valor de columna recuperado es NULL.

Si se ejecuta correctamente, el valor de columna de la columna especificada se copia en el búfer especificado. Se copia menos que todo el valor de columna con la advertencia JET_wrnBufferTruncated se devuelve. Si se dio el pcbActual , se devuelve el tamaño real del valor de la columna. Tenga en cuenta que los valores NULL tienen 0 (cero) longitud y, por tanto, establecerán el tamaño devuelto en 0 (cero). Si la columna recuperada era una columna con varios valores y se dio pretinfo , y JET_bitReturnTag se estableció como opción, el número de secuencia del valor de columna se devuelve en pretinfo-itagSequence>.

En caso de error, la ubicación del cursor se deja sin cambios y no se copia ningún dato en el búfer proporcionado.

Observaciones

Esta llamada se usa una sola vez para recuperar datos de tamaño fijo o conocido para columnas que no son de varios valores. Sin embargo, cuando los datos de columna tienen un tamaño desconocido, esta llamada se suele usar dos veces. Se llama primero para determinar el tamaño de los datos para que pueda asignar el espacio de almacenamiento necesario. A continuación, se vuelve a realizar la misma llamada para recuperar los datos de columna. Cuando se desconoce el número real de valores, porque una columna tiene varios valores, la llamada se suele usar tres veces. En primer lugar, para obtener el número de valores y, a continuación, dos veces más para asignar almacenamiento y recuperar los datos reales.

Para recuperar todos los valores de una columna con varios valores, puede llamar repetidamente a esta función con un valor pretinfo-itagSequence> a partir de 1 y aumentar en cada llamada posterior. Se sabe que el último valor de columna se recupera cuando se devuelve un JET_wrnColumnNull de la función. Tenga en cuenta que este método no se puede realizar si la columna de varios valores tiene valores NULL explícitos establecidos en su secuencia de valores, ya que estos valores se omitirían. Si una aplicación desea recuperar todos los valores de columna con varios valores, incluidos los establecidos explícitamente en NULL, se debe usar JetRetrieveColumns en lugar de JetRetrieveColumn. Tenga en cuenta que esta función no devuelve el número de valores de una función multivalor cuando se proporciona un valor itagSequence de 0 (cero). Solo JetRetrieveColumns devolverá el número de valores de un valor de columna cuando se pasa un valor itagSequence de 0 (cero).

Si se llama a esta función en el nivel de transacción 0 (cero), por ejemplo, la sesión de llamada no se encuentra en una transacción, se abre y cierra una transacción dentro de la función. El propósito de esto es devolver resultados coherentes en caso de que un valor largo abarque las páginas de la base de datos. Tenga en cuenta que la transacción se libera entre las llamadas de función y una serie de llamadas a esta función cuando la sesión no está en una transacción puede devolver datos actualizados después de la primera llamada a esta función.

El valor de columna predeterminado se recuperará cuando la columna no se haya establecido explícitamente en otro valor, a menos que se establezca la opción JET_bitRetrieveIgnoreDefault.

Recuperar el valor de columna de creación automática del búfer de copia antes de insertar es un medio común de identificar un registro de forma única para la vinculación al insertar datos normalizados en varias tablas. El valor de autoincremento se asigna cuando comienza la operación de inserción y se puede recuperar del búfer de copia en cualquier momento hasta que se complete la actualización.

Al recuperar todas las columnas etiquetadas, multivalor y dispersas, estableciendo columnid en 0 (cero), las columnas se recuperan en orden columnid de menor a columnid más alto. Se devuelve el mismo orden de los valores de columna cada vez que se recuperan los valores de columna. El orden es determinista.

Requisitos

Requisito Value

Cliente

Requiere Windows Vista, Windows XP o Windows 2000 Professional.

Server

Requiere Windows Server 2008, Windows Server 2003 o Windows 2000 Server.

Encabezado

Declarado en Esent.h.

Library

Use ESENT.lib.

DLL

Requiere ESENT.dll.

Consulte también

JET_COLUMNID
JET_ERR
JET_SESID
JET_TABLEID
JET_RETINFO
JetSetColumn
JetRetrieveColumns