Función JetIntersectIndexes

Artículo
06/13/2023

Se aplica a: Windows | Windows Server

Función JetIntersectIndexes

La función JetIntersectIndexes calcula la intersección entre varios conjuntos de entradas de índice de distintos índices secundarios en la misma tabla. Esta operación es útil para buscar el conjunto de registros en una tabla que coincida con dos o más criterios que se pueden expresar mediante intervalos de índices.

    JET_ERR JET_API JetIntersectIndexes(
      __in          JET_SESID sesid,
      __in          JET_INDEXRANGE* rgindexrange,
      __in          unsigned long cindexrange,
      __in_out      JET_RECORDLIST* precordlist,
      __in          JET_GRBIT grbit
    );

Parámetros

sesid

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

rgindexrange

Puntero a una matriz de estructuras de JET_IndexRange . Cada estructura incluye una JET_TABLEID que se ha configurado para contener uno de los intervalos de índice que se van a intersecr. Para obtener más información, consulte JET_IndexRange.

cindexrange

Número de estructuras de JET_IndexRange de la matriz contenida en el parámetro rgindexrange .

precordlist

Puntero a una estructura de JET_RECORDLIST . Esta estructura se rellenará con suficiente información para recorrer la tabla temporal con los resultados de JetIntersectIndexes.

Búfer de salida que recibe una estructura de JET_RECORDLIST . La estructura contiene una descripción del conjunto de resultados de la intersección.

grbit

Reservado para uso futuro.

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 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_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: Este valor devuelto se introduce en Windows XP.
JET_errInvalidgrbit	Una de las opciones solicitadas no era válida, se usaba incorrectamente o no se implementaba. JetIntersectIndexes devuelve este error cuando: El grbit contenido en la estructura JET_IndexRange apuntado por cualquier elemento de la matriz rgindexrange no es igual a JET_bitRecordInIndex.
JET_errInvalidParameter	Uno de los parámetros proporcionados contiene un valor inesperado o un valor que es incoherente cuando se combina con el valor de otro parámetro. JetIntersectIndexes devuelve este error por los siguientes motivos: El parámetro precordlist es NULL. El miembro cbStruct de la estructura JET_RECORDLIST especificada en el parámetro precordlist no es igual al tamaño de la estructura JET_RECORDLIST . El parámetro cindexrange es cero. El parámetro cindexrange es mayor que 64. El miembro cbStruct de cualquier elemento de la matriz especificada por el parámetro rgindexrange no es igual al tamaño de la estructura JET_IndexRange . Los elementos de la matriz rgindexrange contienen JET_TABLEIDs de tablas diferentes. Un elemento de la matriz rgindexrange contiene un JET_TABLEID que no está colocado en un índice secundario. Uno o varios de los elementos de la matriz rgindexrange contienen JET_TABLEIDcolocados en el mismo índice secundario.
JET_errInvalidSesid	El identificador de sesión no es válido o hace referencia a una sesión cerrada. Este error no se devuelve en todas las circunstancias. Los identificadores solo se validan con el mejor esfuerzo.
JET_errNotInitialized	No es posible completar la operación porque la instancia asociada a la sesión no se ha inicializado.
JET_errOutOfCursors	Error en la operación porque el motor no pudo asignar los recursos necesarios para abrir un nuevo cursor. Los recursos de cursor se configuran llamando a JetSetSystemParameter con JET_paramMaxCursors especificados en el parámetro paramid .
JET_errOutOfMemory	Error en la operación porque no se pudo asignar suficiente memoria para completarla. JetIntersectIndexes puede devolver JET_errOutOfMemory si el espacio de direcciones del proceso host se vuelve demasiado fragmentado. El administrador de tablas temporales siempre asignará un fragmento de 1 MB de espacio de direcciones para cada tabla temporal creada independientemente de la cantidad de datos que se van a almacenar. JetIntersectIndexes creará una tabla temporal para cada JET_IndexRange especificada en el parámetro rgindexrange y una tabla temporal para la salida en JET_RECORDLIST.
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 es válido usar la misma sesión desde más de un subproceso al mismo tiempo. Windows XP: Este valor devuelto se introduce en Windows XP.
JET_errTermInProgress	No es posible completar la operación porque la instancia asociada a la sesión se está cerrando.
JET_errTooManyOpenIndexes	Error en la operación porque el motor no pudo asignar los recursos necesarios para almacenar en caché los índices de la tabla. El número de índices cuyo esquema se puede almacenar en caché se configura mediante JetSetSystemParameter con JET_paramMaxOpenTables especificados en el parámetro paramid .
JET_errTooManyOpenTables	Error en la operación porque el motor no pudo asignar los recursos necesarios para almacenar en caché el esquema de la tabla. El número de tablas cuyo esquema se puede almacenar en caché se configura mediante JetSetSystemParameter con JET_paramMaxOpenTables especificado en el parámetro paramid .
JET_errTooManySorts	Error en la operación porque el motor no pudo asignar los recursos necesarios para crear una tabla temporal. Los recursos de tabla temporal se configuran mediante JetSetSystemParameter con JET_paramMaxTemporaryTables especificados en el parámetro paramid .

Si se ejecuta correctamente, se devuelve una nueva tabla temporal que contiene los marcadores de los registros que coinciden con los criterios representados por cada una de las descripciones del intervalo de índice de entrada.

Si se produce un error, no se creará la tabla temporal que contiene los resultados. Se puede cambiar el estado de la base de datos temporal. El estado de cualquier base de datos normal en uso por el motor de base de datos permanecerá sin cambios. Se puede cambiar la posición actual de los JET_TABLEIDproporcionados a esta función.

Comentarios

JetIntersectIndexes se puede usar para filtrar eficazmente los registros de una tabla por varios criterios si esos criterios se pueden expresar en términos de los índices secundarios de esa tabla. Por ejemplo, considere que tiene una tabla muy grande que contiene personas. La tabla puede tener columnas para su identificador de usuario, nombre, apellido, etc. Supongamos que cada una de estas columnas se indexa por separado y que el índice principal de la tabla se realiza a través del identificador de usuario. Si desea encontrar a todos los usuarios cuyo nombre empieza por una A y cuyo apellido comienza por G, realizaría los pasos siguientes:

Abra un nuevo cursor en la tabla y establezca ese cursor para usar el índice sobre la columna "nombre". A continuación, configure un intervalo de índices para todas las personas cuyo "nombre" comenzó con "A" y cree una estructura de JET_IndexRange que contenga este cursor.
Repita el paso 1 con un nuevo cursor en el índice de "apellidos" para todas las personas cuyo "apellido" comenzó con "G".
Pase estos criterios a JetIntersectIndexes para calcular el resultado en una tabla temporal.
Recorra la tabla temporal y recupere cada uno de los registros que pasan los criterios por marcador.

La tabla temporal que contiene el conjunto de resultados es una tabla simple con una columna que contiene el marcador de cada registro que pasó todos los criterios usados para calcular la intersección. El conjunto de resultados se ordena en el mismo orden que el índice principal y no contiene entradas duplicadas. La aplicación puede enumerar los resultados de la intersección mediante la enumeración de las filas de la tabla temporal, la recuperación del marcador para cada resultado mediante JetRetrieveColumn y, a continuación, visitar el registro en la base de datos llamando a JetGotoBookmark con ese marcador en un cursor situado en el índice principal.

La tabla temporal devuelta por JetIntersectIndexes solo se puede examinar en una dirección hacia delante. También debe cerrarse a través de JetCloseTable cuando se haya completado el examen. Para obtener más información sobre las tablas temporales y cómo funcionan, consulte JetOpenTemporaryTable.

JetIntersectIndexes es generalmente una manera eficaz y cómoda de filtrar registros en función de varios criterios indexados. Sin embargo, hay algunas sugerencias importantes que se deben seguir para maximizar la utilidad de esta característica. Si sabe que uno de los criterios es tan restrictivo que el intervalo de índices resultante tiene muy pocos registros, probablemente sea mejor simplemente recorrer ese intervalo de índice y filtrar los registros en el nivel de aplicación. Además, si sabe que tiene criterios mucho menos restrictivos que otros criterios en la intersección, podría considerar la posibilidad de quitar esos criterios mucho menos restrictivos de la intersección. Por último, si sabe que uno de los criterios no es restrictivo, de modo que el intervalo de índices resultante sea casi tan grande como el índice principal, es poco probable que la intersección con ese intervalo de índices se beneficie (reducir el tamaño del conjunto de resultados). En todos los casos, debe seleccionar criterios de una manera que tome las entradas de índice más mínimas posibles en la entrada y genere el conjunto de marcadores más específico en la salida para obtener el máximo rendimiento.

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
JET_IndexRange
JET_RECORDLIST
JetGotoBookmark
JetRetrieveColumn
JetSetIndexRange

Compartir a través de

Función JetIntersectIndexes