JetRetrieveColumns Function


Last modified: March 09, 2015

Applies to: Windows | Windows Server

The JetRetrieveColumns function retrieves multiple column values from the current record in a single operation. An array of JET_RETRIEVECOLUMN structures is used to describe the set of column values to be retrieved, and to describe output buffers for each column value to be retrieved.

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



The session to use for this call.


The cursor to use for this call.


A pointer to an array of one or more JET_RETRIEVECOLUMN structures. Each structure includes descriptions of which column value to retrieve and where to store returned data.


The number of JET_RETRIEVECOLUMN structures in the array given by pretrievecolumn.

Return Value

This function returns the JET_ERR datatype with one of the following return codes. For more information about the possible ESE errors, see Extensible Storage Engine Errors and Error Handling Parameters.

Return code



The operation completed successfully.


An invalid multi-valued column sequence number value has been passed in pretinfo->itagSequence. Valid values for the multi-valued column value sequence numbers are 1 or greater. A value of 0 (zero) is valid for this function but is invalid for JetRetrieveColumn.


The column ID given is outside the legal limits of a column ID.


It is not possible to complete the operation because all activity on the instance associated with the session has ceased as a result of a call to JetStopService.


The column described by the given columnid does not exist in the table.


Columns indexed as substrings cannot be retrieved from the index, since only a small portion of the column is typically present in each index entry.


In some cases, the buffer given for the retrieve column must be sufficiently sized in order to return any amount of the column value. For example, escrow updatable columns are adjusted to be consistent for the transactional context of the calling session and this adjustment requires the buffer provided by the caller. If insufficient buffer space is supplied, then JET_errInvalidBufferSize is returned and no column data whatsoever is returned.


The options supplied are unknown or an illegal combination of known bit settings.


One or more of the parameters given is incorrect. This can happen if the retinfo.cbStruct is smaller that the size of JET_RETINFO.


It is not possible to complete the operation because the instance associated with the session has encountered a fatal error that requires that access to all data be revoked to protect the integrity of that data.

Windows XP:  This error will only be returned by Windows XP and later releases.


The cursor is not positioned on a record. This can happen for many different reasons. For example, this will happen if the cursor is currently positioned after the last record on the current index.


It is not possible to complete the operation because the instance associated with the session has not been initialized yet.


It is not possible to complete the operation because a restore operation is in progress on the instance associated with the session.


The same session cannot be used for more than one thread at the same time.

Windows XP:  This error will only be returned by Windows XP and later releases.


It is not possible to complete the operation because the instance associated with the session is being shut down.


The entire column value could not be retrieved because the given buffer is smaller than the size of the column.

On success, columns data and column size are returned in provided buffers described in array of JET_RETRIEVECOLUMN structures. If an itagSequence was set to 0 (zero) to indicate that the number of instances of a multi-valued field was desired instead of column data, then the number of instances of a multi-valued column is returned in the itagSequence field itself. Each JET_RETRIEVECOLUMN structure has an error field that contains warnings for the column retrieved. If the column was NULL valued, then the error code will be set to JET_wrnColumnNull.

On failure, the cursor location is left unchanged and no data is copied into the provided buffer.


JetRetrieveColumns supports one feature that JetRetrieveColumn does not. This is the ability to retrieve the number of instances of a multi-valued column. The purpose of this feature is to allow an application to retrieve all values of a column. This can be done by first determining the number of values that a column has. Next, their lengths can be determined by calling JetRetrieveColumns again with one JET_RETRIEVECOLUMN structure allocated for each value to determine the length of column data. This can be done by passing NULLpvData pointers with cbMax of 0 (zero) and retrieving the column length in cbActual. The third and last call can be made with allocated memory for the column value data.

If any column retrieved is truncated due to an insufficient length buffer, then the API will return JET_wrnBufferTruncated. However, other errors, JET_wrnColumnNull are returned only in the error field in JET_RETRIEVECOLUMN. The reason for this is that applications often want to ensure that all data has been retrieved and returning this error from JetRetrieveColumns facilitates this understanding.



Requires Windows Vista, Windows XP, or Windows 2000 Professional.


Requires Windows Server 2008, Windows Server 2003, or Windows 2000 Server.


Declared in Esent.h.


Use ESENT.lib.


Requires ESENT.dll.

See Also