Función JetEnumerateColumns

Artículo
06/13/2023

Se aplica a: Windows | Windows Server

Función JetEnumerateColumns

La función JetEnumerateColumns recupera eficazmente un conjunto de columnas y sus valores del registro actual de un cursor o del búfer de copia de ese cursor. Las columnas y los valores recuperados se pueden restringir mediante una lista de identificadores de columna, números itagSequence y otras características. Esta API de recuperación de columnas es única en que devuelve información en la memoria asignada dinámicamente que se obtiene mediante una devolución de llamada compatible con realloc proporcionada por el usuario. Esta nueva flexibilidad permite la recuperación eficaz de los datos de columna con características específicas (como el tamaño y la multiplicidad) que son desconocidos para el autor de la llamada. Esto elimina la necesidad de usar los modos de detección de JetRetrieveColumn para determinar esas características con el fin de configurar una llamada final a JetRetrieveColumn que recuperará correctamente los datos deseados.

Windows XP: JetEnumerateColumns se introduce en Windows XP.

    JET_ERR JET_API JetEnumerateColumns(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in          unsigned long cEnumColumnId,
      __in_opt      JET_ENUMCOLUMNID* rgEnumColumnId,
      __out         unsigned long* pcEnumColumn,
      __out         JET_ENUMCOLUMN** prgEnumColumn,
      __in          JET_PFNREALLOC pfnRealloc,
      __in          void* pvReallocContext,
      __in          unsigned long cbDataMost,
      __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.

cEnumColumnId

Matriz de identificadores de columna, cada uno con una matriz opcional de números itagSequence que se van a enumerar.

Si cEnumColumnId es 0 (cero), rgEnumColumnId se omite y se enumeran todos los valores de columna y se devuelven al autor de la llamada. Si un elemento de la matriz de identificadores de columna hace referencia a un identificador de columna de 0 (cero), se omite la enumeración de esa columna y se generará una ranura correspondiente en la salida con un estado de columna de JET_wrnColumnSkipped.

Si ctagSequence es 0 (cero) para un elemento determinado de la matriz de identificadores de columna, se omite rgtagSequence y se enumeran todos los valores de columna de ese identificador de columna y se devuelven al autor de la llamada. Si un elemento de una matriz de números itagSequence hace referencia a un número itagSequence de 0 (cero), se omite la enumeración de ese número itagSequence y se generará una ranura correspondiente en la salida con un estado de valor de columna de JET_wrnColumnSkipped.

rgEnumColumnId

Consulte cEnumColumnId.

pcEnumColumn

Devuelve la matriz enumerada de columnas y sus valores en la memoria asignada a través de la devolución de llamada compatible con itagSequence proporcionada.

Si se solicita una matriz de identificadores de columna en la entrada, el orden y el tamaño de la matriz de salida reflejarán el orden y el tamaño de la matriz de entrada. Del mismo modo, si se solicita una matriz de números itagSequence para un identificador de columna determinado en la entrada, el orden y el tamaño de la matriz de salida de valores de columna para esa columna reflejarán el orden y el tamaño de la matriz de entrada.

Los parámetros de salida se establecen en 0 (cero) y NULL en cualquier error, excepto en JET_errBadColumnId y JET_errColumnNotFound. Cuando se devuelven estos errores, los datos de salida son válidos y se completan para todos, excepto los identificadores de columna afectados. El código de estado de cada uno de los identificadores de columna afectados se establece en uno de estos errores para que el autor de la llamada pueda determinar qué identificadores de columna eran incorrectos y potencialmente tomar medidas correctivas.

prgEnumColumn

Consulta pcEnumColumn.

pfnRealloc

Identifica una devolución de llamada compatible con reasignación y un puntero de contexto opcional que se usa para asignar memoria para la matriz de salida de columnas y sus valores.

pvReallocContext

Consulte pfnRealloc.

cbDataMost

Establece un límite en la cantidad de datos que se van a devolver de una columna binaria larga o de texto largo.

Este parámetro se puede usar para evitar la enumeración de un valor de columna extremadamente grande. Normalmente, esta enumeración podría producir un error en la llamada API con JET_errOutOfMemory. Si un valor de columna grande se trunca de tal manera, el estado del valor de la columna será JET_wrnColumnTruncated.

grbit

Un grupo de bits que especifica cero o más de las siguientes opciones.

Valor	Significado
JET_bitEnumerateCompressOutput	Al enumerar valores de columna, se pueden devolver todas las columnas para las que se recuperan todos los valores y que solo tienen un valor de columna distinto de NULL en un formato comprimido. El estado de estas columnas se establecerá en JET_wrnColumnSingleValue y el tamaño del valor de columna y la memoria que contiene el valor de columna se devolverá directamente en la estructura JET_ENUMCOLUMN . No se garantiza que todas las columnas aptas se comprima de esta manera. Consulte JET_ENUMCOLUMN para obtener más información.
JET_bitEnumerateCopy	Esta opción indica que los valores de columna modificados del registro deben enumerarse en lugar de los valores de columna originales. Si no se ha modificado un valor de columna, se enumera el valor de columna original. De esta manera, se puede enumerar un valor de columna que aún no se ha insertado o actualizado al insertar o actualizar un registro. Esta opción es idéntica a JET_bitRetrieveCopy cuando se usa con JetRetrieveColumn o JetRetrieveColumns.
JET_bitEnumerateIgnoreDefault	Si una columna determinada no está presente en el registro, no se devolverá ningún valor de columna. Normalmente, el valor predeterminado de la columna, si existe, se devolvería en este caso. Se garantiza que si la columna se establece en un valor distinto del valor predeterminado, se devolverá ese valor diferente (es decir, si una columna con un valor predeterminado se establece explícitamente en NULL , se devolverá un valor NULL como valor de esa columna). Tenga en cuenta que, incluso si se solicita esta opción, todavía es posible ver un valor de columna que es igual al valor predeterminado. No se realiza ningún esfuerzo para quitar valores de columna que coincidan con sus valores predeterminados. Es importante tener en cuenta que esta opción afecta a la salida de JetEnumerateColumns cuando se usa con JET_bitEnumeratePresenceOnly o JET_bitEnumerateTaggedOnly.
JET_bitEnumerateIgnoreUserDefinedDefault	Si una columna determinada no está presente en el registro y tiene un valor predeterminado definido por el usuario, no se devolverá ningún valor de columna. Esta opción impedirá que se llame a la devolución de llamada que calcula el valor predeterminado definido por el usuario para la columna al enumerar los valores de esa columna. Windows Server 2003 y versiones anteriores: Para Windows Server 2003 y versiones anteriores, se producirá un error en la operación con JET_errCallbackFailed. Windows Server 2003 SP1: Este valor posible solo está disponible para Windows Server 2003 SP1 y sistemas operativos posteriores. Si se especifica este valor posible y la tabla contiene una columna que tiene un valor predeterminado definido por el usuario, se producirá un error en la operación con JET_errCallbackFailed.
JET_bitEnumeratePresenceOnly	Si existe un valor distinto de NULL para el valor de columna o columna solicitado, no se devuelven los datos asociados. En su lugar, el estado asociado para ese valor de columna o columna se establecerá en JET_wrnColumnPresent. Si el valor de columna o columna es NULL , se devolverá JET_wrnColumnNull como de costumbre.
JET_bitEnumerateTaggedOnly	Al enumerar todos los valores de columna del registro (por ejemplo, es decir, cuando cEnumColumnId es cero), solo se devolverán los valores de columna etiquetados. Esta opción no se permite al enumerar una matriz específica de identificadores de columna.
JET_bitEnumerateInRecordOnly	Windows 7: JET_bitEnumerateInRecordOnly se introduce en Windows 7.

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. JetEnumerateColumns devolverá este error si se solicitaron identificadores de columna específicos, uno de esos identificadores de columna no era válido y el primer identificador de columna no válido produjo este error para su código de estado 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 identificador de columna especificado no existe en la tabla. JetEnumerateColumns devolverá este error si se solicitaron identificadores de columna específicos, uno de esos identificadores de columna no era válido y el primer identificador de columna no válido produjo este error para su código de estado de columna.
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: Windows XP solo devolverá este error y versiones posteriores.
JET_errInvalidgrbit	Una de las opciones solicitadas no era válida o no se implementó. JetEnumerateColumns devolverá este error cuando: JET_bitEnumerateLocal se especifica. Se especifica un grbit no válido.
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. JetEnumerateColumns devolverá este error cuando: pcEnumColumn es NULL. prgEnumColumn es NULL. pfnRealloc es NULL.
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_errRecordDeleted	El cursor se coloca en un registro que se ha eliminado. Esto puede ocurrir por diversos motivos. La razón más común es que la sesión no está en una transacción, el cursor se posicionó en un registro, ese registro se eliminó y, a continuación, el cursor intentó hacer referencia a ese registro.
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: Windows XP solo devolverá este error y versiones posteriores.
JET_errTermInProgress	No es posible completar la operación porque se está cerrando la instancia asociada a la sesión.

Si se ejecuta correctamente, los datos solicitados se devolverán en los búferes de salida. Es responsabilidad del autor de la llamada liberar cualquier memoria asignada por esta devolución de llamada y devolverla en los búferes de salida. Esa memoria debe liberarse a través de la devolución de llamada compatible con realloc proporcionada. No se producirá ningún cambio en el estado de la base de datos.

Si se produce un error, no se devolverá ninguno de los datos solicitados. Cualquier memoria asignada durante la llamada se liberará automáticamente mediante la devolución de llamada compatible con reasignación proporcionada. No se producirá ningún cambio en el estado de la base de datos.

Comentarios

Si va a enumerar todos los valores de columna del registro y no especificó JET_bitEnumerateIgnoreDefaults, no puede suponer que nunca verá un valor de columna o columna con un código de estado de JET_wrnColumnNull. Puede ver este código de estado si una columna tiene un valor predeterminado y se estableció explícitamente en NULL o si la columna es una columna no dispersa (por ejemplo, una columna fija o variable).

El parámetro cbDataMost no se aplica a todos los valores de columna. Este parámetro solo truncará los valores de texto largo y de columna binaria larga que sean tan grandes que se hayan almacenado por separado del registro.

Si JetEnumerateColumns devuelve datos en sus parámetros de salida, el autor de la llamada es responsable de liberar la memoria de la matriz, así como cualquier memoria a la que hacen referencia los punteros incrustados en esa matriz.

Requisitos

Requisito	Value
Cliente	Requiere Windows Vista o Windows XP.
Servidor	Requiere Windows Server 2008 o Windows Server 2003.
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_ENUMCOLUMNID
JET_ENUMCOLUMN
JET_ENUMCOLUMNVALUE
JET_PFNREALLOC
realloc
JetRetrieveColumn
JetRetrieveColumns

Función JetEnumerateColumns