大网数据广告活动
磁盘与文件系统

JetRetrieveColumns Function

· 52CE 我爱测

Learn more about: JetRetrieveColumns Function

Applies to: Windows | Windows Server

JetRetrieveColumns Function

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
    );

Parameters

sesid

The session to use for this call.

tableid

The cursor to use for this call.

pretrievecolumn

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.

cretrievecolumn

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 Description
JET_errSuccess The operation completed successfully.
JET_errBadItagSequence 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 <a href="gg269198(v=exchg.10).md">JetRetrieveColumn</a>.
JET_errBadColumnId The column ID given is outside the legal limits of a column ID.
JET_errClientRequestToStopJetService 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 <a href="gg269240(v=exchg.10).md">JetStopService</a>.
JET_errColumnNotFound The column described by the given columnid does not exist in the table.
JET_errIndexTuplesCannotRetrieveFromIndex 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.
JET_errInvalidBufferSize 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.
JET_errInvalidgrbit The options supplied are unknown or an illegal combination of known bit settings.
JET_errInvalidParameter One or more of the parameters given is incorrect. This can happen if the retinfo.cbStruct is smaller that the size of <a href="gg294049(v=exchg.10).md">JET_RETINFO</a>.
JET_errInstanceUnavailable 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.
JET_errNoCurrentRecord 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.
JET_errNotInitialized It is not possible to complete the operation because the instance associated with the session has not been initialized yet.
JET_errRestoreInProgress It is not possible to complete the operation because a restore operation is in progress on the instance associated with the session.
JET_errSessionSharingViolation 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.
JET_errTermInProgress It is not possible to complete the operation because the instance associated with the session is being shut down.
JET_wrnBufferTruncated 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.

Remarks

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.

Requirements
Requirement Value
Client Requires Windows Vista, Windows XP, or Windows 2000 Professional.
Server Requires Windows Server 2008, Windows Server 2003, or Windows 2000 Server.
Header Declared in Esent.h.
Library Use ESENT.lib.
DLL Requires ESENT.dll.
See Also

JET_ERR
JET_SESID
JET_TABLEID
JET_RETRIEVECOLUMN
JetEnumerateColumns
JetRetrieveColumn
JetSetColumns

Source: Microsoft Learn / Windows Win32 documentation by Microsoft and contributors. Documentation licensed CC BY 4.0. Code samples are covered by the MIT License. Converted from Markdown, with links normalized and embedded media omitted.

资料来源与适用范围

资料来源
Microsoft Learn / Windows Win32 documentation
适用范围
Windows Win32 API · Source date 04/11/2016
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-15
授权说明
CC BY 4.0 (documentation), MIT (code samples)

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。