Función JetMove

Se aplica a: Windows | Windows Server

Función JetMove

La función JetMove coloca un cursor al principio o al final de un índice y recorre las entradas de ese índice hacia delante o hacia atrás. También es posible mover el cursor hacia delante o hacia atrás en el índice actual por un número especificado de entradas de índice. Otro enfoque consiste en limitar artificialmente las entradas de índice que se pueden enumerar mediante JetMove mediante la configuración de un intervalo de índice en el cursor mediante JetSetIndexRange.

    JET_ERR JET_API JetMove(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in          long cRow,
      __in          JET_GRBIT grbit
    );

Parámetros

sesid

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

tableid

Cursor que se va a usar para esta llamada.

Cuervo

Desplazamiento arbitrario que indica el movimiento deseado del cursor en el índice actual.

Además de los desplazamientos estándar, este parámetro también se puede establecer con una de las siguientes opciones.

Valor	Significado
JET_MoveFirst	Mueve el cursor a la primera entrada de índice del índice (si existe). Esto restablece cualquier intervalo de índice establecido con JetSetIndexRange. Nota El valor literal de -2147483648 se usa para indicar esta opción. No use este valor como un desplazamiento normal o un comportamiento no deseado.
JET_MoveLast	Mueve el cursor a la última entrada de índice del índice (si existe). Esto restablece cualquier intervalo de índice establecido con JetSetIndexRange. Nota El valor literal de 2147483647 se usa para indicar esta opción. No use este valor como un desplazamiento normal o un comportamiento no deseado.
JET_MoveNext	Mueve el cursor a la siguiente entrada de índice del índice (si existe). Este valor es exactamente igual a un desplazamiento normal de +1. Respeta los intervalos de índice establecidos con JetSetIndexRange.
JET_MovePrevious	Mueve el cursor a la entrada de índice anterior en el índice (si existe). Respeta los intervalos de índice establecidos con JetSetIndexRange. Este valor es exactamente igual a un desplazamiento normal de -1 o 0 (Cero). El cursor permanece en la posición lógica actual y se probará la existencia de la entrada de índice correspondiente a esa posición lógica.

grbit

Grupo de bits que especifican cero o más de las siguientes opciones.

Valor

Significado

JET_bitMoveKeyNE

Mueve el cursor hacia delante o hacia atrás por el número de entradas de índice necesarias para omitir el número solicitado de valores de clave de índice encontrados en el índice. Esto tiene el efecto de contraer entradas de índice con valores de clave duplicados en una sola entrada de índice. Normalmente, un desplazamiento moverá el cursor por el número especificado de entradas de índice independientemente de sus valores de clave.

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. Para JetMove, esto significa que se encontró una entrada de índice en la ubicación solicitada o desplazamiento en el índice actual.
JET_errClientRequestToStopJetService	La operación no se puede completar porque toda la actividad de la instancia asociada a la sesión ha dejado de funcionar como resultado de una llamada a JetStopService.
JET_errInstanceUnavailable	La operación no se puede completar porque la instancia asociada a la sesión encontró un error irrecuperable que requiere que se revoque el acceso a todos los datos para proteger la integridad de esos datos. Windows XP: Este valor devuelto se introduce en Windows XP.
JET_errNoCurrentRecord	El cursor no se coloca actualmente en una entrada de índice. Para JetMove, esto significa que no se encontró una entrada de índice en la ubicación solicitada o desplazamiento en el índice actual.
JET_errNotInitialized	La operación no se puede completar porque la instancia asociada a la sesión aún no se ha inicializado.
JET_errRecordDeleted	El cursor se coloca lógicamente en una entrada de índice que corresponde a un registro que se ha eliminado.
JET_errRestoreInProgress	La operación no se puede completar porque hay una operación de restauración 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 valor devuelto se introduce en Windows XP.
JET_errTermInProgress	La operación no se puede completar porque la instancia asociada a la sesión se está cerrando.

Si esta función se realiza correctamente, el cursor se colocará en una entrada de índice que coincida con la ubicación o el desplazamiento solicitados. Si se ha preparado un registro para la actualización, esa actualización se cancelará. Si un intervalo de índices está en vigor y JET_MoveFirst o JET_MoveLast se especificó, ese intervalo de índice se cancelará. No se producirá ningún cambio en el estado de la base de datos.

Si se produce un error en esta función, la posición del cursor permanecerá sin cambios a menos que se devuelva JET_errNoCurrentRecord. En ese caso, el cursor se colocará donde habría sido la entrada de índice que coincida con la ubicación o el desplazamiento solicitados. El cursor se puede mover con relación a esa posición, pero aún no está en una entrada de índice válida. Si se ha preparado un registro para la actualización, esa actualización se cancelará. Si un intervalo de índices está en vigor y JET_MoveFirst o JET_MoveLast se especificó, ese intervalo de índice se cancelará. No se producirá ningún cambio en el estado de la base de datos.

Comentarios

Un cursor se puede mover a dos posiciones especiales mediante JetMove, Before First y After Last. Si el cursor está en la primera entrada de índice de la tabla y se llama a JetMove con JET_MovePrevious, se producirá un error en la llamada a JET_errNoCurrentRecord y el cursor se colocará lógicamente antes de la primera entrada del índice. Esta posición lógica se mantiene incluso si se inserta otra entrada de índice antes de la primera entrada del índice. Se produce una situación análoga para After Last con respecto al final del índice. Antes de First y After Last son más útiles al configurar un intervalo de entradas de índice que se van a iterar mediante JetMove, mediante un modelo de iterador que espera pasar siempre al siguiente elemento (o anterior) antes de usar ese elemento.

El conjunto de entradas de índice que puede visitar JetMove se puede limitar mediante la configuración de un intervalo de índice en el cursor. Esto resulta útil para las aplicaciones que enumeran un conjunto de entradas de índice que coinciden con criterios simples que se pueden expresar a través de un par de claves de búsqueda creadas para ese índice. Para obtener más información, consulte JetSetIndexRange.

En las versiones anteriores a Windows Server 2003 SP1, hay un problema en JetMove que se produce en algunos casos específicos, lo que afecta al cumplimiento correcto de un intervalo de índices tal como lo configura la función JetSetIndexRange . Si el cursor está actualmente antes de la primera entrada de índice y se establece un intervalo de índice con un límite superior que es menor que la primera entrada de índice, la siguiente llamada a JetMove pasará erróneamente a esa entrada de índice en lugar de generar errores con JET_errNoCurrentRecord, según lo previsto. Se producirá el mismo error para la situación análoga a partir del final del índice. Esta situación puede producirse en una aplicación que configura un intervalo de índices y la navega mediante un iterador que espera empezar antes de la primera entrada de índice que es miembro del conjunto de entradas que se van a enumerar, en lugar de iniciarse en la primera entrada de índice de ese conjunto. Esta situación también se produce en el caso análogo a partir del final del índice. La solución alternativa es que la aplicación compruebe manualmente que la entrada de índice adquirida está dentro del intervalo de índices comparando la clave de la entrada de índice actual (recuperada mediante JetRetrieveKey) con la clave que representa el final del intervalo de índice actual (recuperado mediante JetRetrieveKey mediante JET_bitRetrieveCopy).

Es importante tener cuidado al pasar desplazamientos calculados a JetMove. Si el desplazamiento calculado es menor o igual que JET_MoveFirst, ese desplazamiento debe dividirse en varias partes, cada una de las cuales se pasa a JetMove por separado, pero dentro de una sola transacción para obtener el efecto deseado. Lo mismo ocurre con los desplazamientos mayores o iguales que JET_MoveNext. Es poco probable que una aplicación se someta a esto en el mundo real, pero es bueno tener una defensa contra este caso dada la semántica muy diferente de JET_MoveFirst y JET_MoveLast desde un desplazamiento normal.

Cuando se llama a JetMove con un desplazamiento muy grande, como cuando el parámetro cRow se establece en 1000, JetMove recorre todas las 1000 entradas de índice para alcanzar la posición final. Actualmente, la API de ESE no proporciona una manera eficaz de moverse directamente a una entrada de índice determinada por desplazamiento sin atravesar cada entrada de índice.

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_ERR
JET_GRBIT
JET_SESID
JET_TABLEID
JetRetrieveKey
JetSetIndexRange