Función JetSetCurrentIndex4

Se aplica a: Windows | Windows Server

Función JetSetCurrentIndex4

La función JetSetCurrentIndex4 se usa para establecer el índice actual de un cursor. El índice actual de un cursor define qué registros de una tabla son visibles para ese cursor y el orden en que aparecen seleccionando el conjunto de entradas de índice que se van a usar para exponer esos registros.

    JET_ERR JET_API JetSetCurrentIndex4(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in_opt      JET_PCSTR szIndexName,
      __in_opt      JET_INDEXID* pindexid,
      __in          JET_GRBIT grbit,
      __in          unsigned long itagSequence
    );

Parámetros

sesid

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

tableid

Cursor que se va a usar para esta llamada.

szIndexName

Nombre del índice que se va a seleccionar para el cursor. Si este parámetro es NULL o una cadena vacía, se seleccionará el índice agrupado. Si se define un índice principal para la tabla, ese índice se seleccionará porque es el mismo que el índice agrupado. Si no se define ningún índice principal para la tabla, se seleccionará el índice secuencial. El índice secuencial no tiene ninguna definición de índice. Consulte JetCreateIndex para obtener más información.

Si pindexid no es NULL, se omitirá el nombre del índice y su identificador de índice seleccionará el índice.

pindexid

Identificador del índice que se va a seleccionar para el cursor.

El identificador de índice es un identificador volátil y opaco que se puede usar para seleccionar rápidamente un índice. Este identificador se puede recuperar mediante JetGetIndexInfo o JetGetTableIndexInfo mediante la opción JET_IdxInfoIndexId.

Si pindexid es NULL, el índice se seleccionará por su nombre de índice y se omitirá el identificador de índice.

Cuando este parámetro no está presente, se supone que su valor es NULL.

grbit

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_bitMoveFirst	Esta opción indica que el cursor debe colocarse en la primera entrada del índice especificado. Si se selecciona el índice clúster (índice principal o índice secuencial) y el índice actual es un índice secundario, se supone JET_bitMoveFirst. Si se selecciona el índice actual, esta opción se omite y no se realiza ningún cambio en la posición del cursor.
JET_bitNoMove	Esta opción indica que el cursor debe colocarse en la entrada de índice del nuevo índice que corresponde al registro asociado a la entrada de índice en la posición actual del cursor en el índice anterior. Si la definición del nuevo índice contiene al menos una columna de clave con varios valores, la entrada del índice de destino es ambigua. En este caso, se usa la itagSequence especificada para seleccionar qué valor múltiple de la columna de clave multivalor más significativa se usa para colocar el cursor. Solo es necesario pasar una sola itagSequence incluso en el caso de varias columnas de clave con varios valores porque el motor solo expande todos los valores de la columna de clave multivalor más significativa. Consulte JetCreateIndex para obtener más detalles. Si se especifica JET_bitMoveFirst, se omite esta opción. Si se selecciona el índice actual, esta opción se omite y no se realiza ningún cambio en la posición del cursor. Cuando este parámetro no está presente, se supone que su valor es JET_bitMoveFirst.

itagSequence

Número de secuencia del valor de columna multivalor que se usará para colocar el cursor en el nuevo índice.

Este parámetro solo se usa junto con JET_bitNoMove. Consulte la descripción de esta opción para obtener más detalles.

Cuando este parámetro no está presente o se establece en cero, se supone que su valor es 1.

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_errBadItagSequence	Se selecciona un índice secundario con la opción JET_bitNoMove y no hay ningún valor para la primera columna de clave multivalor en la definición del nuevo índice que corresponde al número de secuencia especificado.
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_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 solo devolverá este error y versiones posteriores.
JET_errInvalidIndexId	El contenido del identificador de índice no era válido o ha expirado y debe actualizarse. Esto puede ocurrir para JetSetCurrentIndex4 cuando: pindexid-cbStruct> no tiene el tamaño esperado (Windows Server 2003 y versiones posteriores). El motor se ha apagado desde que se capturó el identificador de índice. Todos los cursores que hacen referencia a la tabla que contiene el índice correspondiente al identificador de índice se han cerrado y el motor ha expulsado la definición del índice de la caché de esquemas. El identificador de índice se usa con un cursor abierto en la tabla incorrecta. El índice se ha quitado o aún no está visible para la sesión.
JET_errInvalidName	Uno de los nombres de objeto especificados no era válido. Todos los nombres de objeto deben cumplir el mismo conjunto de reglas. Estas reglas son: Los nombres de objeto deben estar compuestos de caracteres ASCII. Los nombres de objeto deben tener al menos un carácter de longitud. Los nombres de objeto no pueden superar JET_cbNameMost (64) caracteres de longitud. Es posible que los nombres de objeto no comiencen por un espacio. Es posible que los nombres de objeto no contengan caracteres de control ASCII (0x00 a través de 0x1F). Los nombres de objeto no pueden contener un signo de exclamación (!), punto (.), corchete izquierdo ([) o corchete derecho (]). Una vez validado, solo se usará la parte de la cadena hasta el primer espacio (si existe) para el nombre del objeto. Esto significa eficazmente que los nombres de objeto tampoco pueden contener un espacio.
JET_errInvalidParameter	Uno de los parámetros proporcionados contenía un valor inesperado o contenía un valor que no tenía sentido cuando se combinaba con el valor de otro parámetro. Esto puede ocurrir para JetSetCurrentIndex4 cuando pindexid no es NULL y pindexid-cbStruct> no es del tamaño esperado (Windows XP y versiones anteriores).
JET_errNoCurrentRecord	Se selecciona un índice secundario con la opción JET_bitNoMove y no hay ninguna entrada de índice en el nuevo índice que corresponda al registro asociado a la entrada de índice en la posición actual del cursor en el índice anterior.
JET_errNotInitialized	No es posible completar la operación porque la instancia asociada a la sesión aún no se ha inicializado.
JET_errOutOfCursors	El motor ha agotado su grupo de recursos que se usan para abrir cursores. El número máximo de cursores que se pueden abrir en cualquier momento se controla mediante JET_paramMaxCursors. Consulte JetSetSystemParameter para obtener más información. Esto puede ocurrir para JetSetCurrentIndex4 cuando se ha seleccionado un índice secundario y el motor no puede abrir un cursor interno para usar ese índice.
JET_errRestoreInProgress	No es posible completar la operación 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 solo devolverá este error y versiones posteriores.
JET_errTermInProgress	No es posible completar la operación porque la instancia asociada a la sesión se está cerrando.

Si se ejecuta correctamente, el índice actual del cursor se establece en el índice solicitado. Ahora se pueden buscar entradas de índice con JetSeek según la definición de índice del índice solicitado. Las entradas de índice también se pueden enumerar con JetMove en el orden especificado por esa definición de índice. La posición actual del cursor se establece en la primera entrada de índice del índice (JET_bitMoveFirst) o en una entrada de índice específica relacionada con la posición actual del cursor en el índice anterior (JET_bitNoMove). No se producirá ningún cambio en el estado de la base de datos.

Si se produce un error, el índice actual y la posición actual del cursor están en un estado indefinido. No se producirá ningún cambio en el estado de la base de datos.

Comentarios

Si la sugerencia de identificador de índice está obsoleta, simplemente se produce un error en la API. En este caso, no hay ninguna reserva en el nombre de texto del índice, como podría esperarse. El autor de la llamada de la API debe realizar manualmente esta reserva.

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.
Unicode	Se implementa como JetSetCurrentIndex4W (Unicode) y JetSetCurrentIndex4A (ANSI).

Consulte también

JET_ERR
JET_GRBIT
JET_SESID
JET_TABLEID
JET_INDEXID
JetCreateIndex
JetGetCurrentIndex
JetGetIndexInfo
JetGetTableIndexInfo
JetMove
JetSeek
JetSetSystemParameter