Función JetRetrieveColumns

Artículo
06/12/2023

Se aplica a: Windows | Windows Server

Función JetRetrieveColumns

La función JetRetrieveColumns recupera varios valores de columna del registro actual en una sola operación. Se usa una matriz de estructuras de JET_RETRIEVECOLUMN para describir el conjunto de valores de columna que se van a recuperar y para describir los búferes de salida para cada valor de columna que se va a recuperar.

    JET_ERR JET_API JetRetrieveColumns(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in_out_opt  JET_RETRIEVECOLUMN* pretrievecolumn,
      __in          unsigned long cretrievecolumn
    );

Parámetros

sesid

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

tableid

Cursor que se va a usar para esta llamada.

pretrievecolumn

Puntero a una matriz de una o varias estructuras JET_RETRIEVECOLUMN . Cada estructura incluye descripciones del valor de columna que se va a recuperar y dónde almacenar los datos devueltos.

cretrievecolumn

Número de estructuras de JET_RETRIEVECOLUMN de la matriz dadas por pretrievecolumn.

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 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) es válido para esta función, pero no es válido para JetRetrieveColumn.
JET_errBadColumnId	El identificador de columna especificado está fuera de los límites legales de un identificador 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 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_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 de búfer insuficiente, se devuelve JET_errInvalidBufferSize y no se devuelve ningún dato de columna.
JET_errInvalidgrbit	Las opciones proporcionadas son desconocidas o una combinación ilegal de la configuración de bits conocida.
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_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_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 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.
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.

Si se ejecuta correctamente, los datos de columnas y el tamaño de columna se devuelven en los búferes proporcionados que se describen en la matriz de estructuras de JET_RETRIEVECOLUMN . Si se estableció una itagSequence en 0 (cero) para indicar que el número de instancias de un campo multivalor era deseado en lugar de datos de columna, el número de instancias de una columna con varios valores se devuelve en el propio campo itagSequence . Cada estructura JET_RETRIEVECOLUMN tiene un campo de error que contiene advertencias para la columna recuperada. Si la columna tenía valores NULL , el código de error se establecerá en JET_wrnColumnNull.

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.

Comentarios

JetRetrieveColumns admite una característica que JetRetrieveColumn no. Esta es la capacidad de recuperar el número de instancias de una columna con varios valores. El propósito de esta característica es permitir que una aplicación recupere todos los valores de una columna. Para ello, primero debe determinar el número de valores que tiene una columna. A continuación, sus longitudes se pueden determinar llamando a JetRetrieveColumns de nuevo con una estructura JET_RETRIEVECOLUMN asignada para cada valor para determinar la longitud de los datos de columna. Esto se puede hacer pasando punteros PVData NULL con cbMax de 0 (cero) y recuperando la longitud de la columna en cbActual. La tercera y la última llamada se pueden realizar con memoria asignada para los datos de valor de columna.

Si se trunca cualquier columna recuperada debido a un búfer de longitud insuficiente, la API devolverá JET_wrnBufferTruncated. Sin embargo, otros errores, JET_wrnColumnNull solo se devuelven en el campo error de JET_RETRIEVECOLUMN. La razón de esto es que las aplicaciones a menudo quieren asegurarse de que se han recuperado todos los datos y devolver este error de JetRetrieveColumns facilita esta comprensión.

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_SESID
JET_TABLEID
JET_RETRIEVECOLUMN
JetEnumerateColumns
JetRetrieveColumn
JetSetColumns

Función JetRetrieveColumns