Share via

IRow::GetColumns

  • Article

Retrieves the values of one or more named columns from the row object.

Syntax

HRESULT GetColumns(
   DBORDINAL        cColumns,
   DBCOLUMNACCESS   rgColumns[ ]
);

Parameters

  • cColumns
    [in] Count of columns specified in the rgColumns array. If cColumns is zero, no columns are created or updated.

  • rgColumns
    [in/out] A caller-supplied array of DBCOLUMNACCESS structures. The DBCOLUMNACCESS structure is defined as follows:

    typedef struct tagDBCOLUMNACCESS {
   void          *pData;
   DBID           columnid;
   DBLENGTH       cbDataLen;
   DBSTATUS       dwStatus;
   DBLENGTH       cbMaxLen;
   DB_DWRESERVE   dwReserved;
   DBTYPE         wType;
   BYTE           bPrecision;
   BYTE           bScale;
} DBCOLUMNACCESS;

  • pData
    Pointer of type wType to caller-allocated storage. On return, the area of storage contains the value stored in the column specified by columnid. The provider should attempt to coerce the column value to type wType. If wType is DBTYPE_VARIANT, the provider is responsible for allocating any variable-length storage pointed to by the VARIANT. If the caller passes a null pointer, the provider returns only the untruncated length (cbDataLen) and status (dwStatus) and does not return a data value.

    If the row is in immediate mode and a row-specific columns has been deleted, the provider returns DBSTATUS_E_DOESNOTEXIST. If the row is in deferred mode and a row-specific column has been deleted, the provider returns a null value and DBSTATUS_S_ISNULL.

    For more information, see Getting and Setting Data.

  • columnid
    columnid is a DBID that identifies the column to be accessed. columnid values must be unique within a row.

  • cbDataLen
    The returned length of the value contained in *pData. If the length of the column value is greater than cbMaxLen, the provider truncates the data to fit the buffer, returns the full data size in cbDataLen, and sets dwStatus to DBSTATUS_S_TRUNCATED.

  • dwStatus
    A DBSTATUS status field set by the provider on return, indicating whether pData or some other value should be used. On return, dwStatus indicates whether the field was successfully retrieved and provides other information about this column. For more information about status values, see Status in Getting and Setting Data.

  • cbMaxLen
    The maximum length of the caller-initialized memory pointed to by pData. For more information on cbMaxLen in the binding structure, see DBBINDING Structures in Getting and Setting Data.

  • dwReserved
    Reserved. Consumers should set this parameter to zero.

  • wType
    On input, wType identifies the data type requested by the consumer. The provider attempts to convert the value from the type of the column to this type.

    wType should not change on return; if the provider could not convert, a status of DBSTATUS_E_CANTCONVERTVALUE would be returned.

  • bPrecision
    The maximum precision to use when getting data and wType is DBTYPE_NUMERIC. bPrecision is ignored when setting data or if wType is not DBTYPE_NUMERIC. For more information, see Conversions Involving DBTYPE_NUMERIC or DBTYPE_DECIMAL in Appendix A: Data Types.

  • bScale
    The scale to use when getting data and wType is DBTYPE_NUMERIC or DBTYPE_DECIMAL. This is ignored when setting data. It is also ignored if wType is not DBTYPE_NUMERIC or DBTYPE_DECIMAL. For more information, see Conversions Involving DBTYPE_NUMERIC or DBTYPE_DECIMAL in Appendix A: Data Types.

Return Code

  • S_OK
    The provider successfully retrieved all of the columns.

  • E_INVALIDARG
    rgColumns was a null pointer, and cColumns was not zero.

  • DB_SEC_E_PERMISSIONDENIED
    The provider was unable to access any of the columns.

  • DB_E_ERRORSOCCURRED
    The provider was unable to retrieve any of the specified columns. The caller should check dwStatus of each element of rgColumns to determine why each column was not retrieved.

  • DB_S_ERRORSOCCURRED
    The provider was unable to retrieve some of the specified columns. The caller should check dwStatus of each element of rgColumns to determine whether a column was retrieved.

  • DB_E_DELETEDROW
    The row was either a pending delete row or a row for which a deletion had already been transmitted to the data store.

  • E_FAIL
    A provider-specific error occurred.

  • E_UNEXPECTED
    ITransaction::Commit or ITransaction::Abort was called, and the object is in a zombie state.

Comments

IRow::GetColumns retrieves as many of the columns specified in the rgColumns array as can be found on the row object. As long as at least one of the requested columns is retrieved, a failure to retrieve one or more of the remaining columns is not an error. Instead, the caller should examine the corresponding status field to ensure that a column was retrieved. A return value of DBSTATUS_E_DOESNOTEXIST indicates that a named column does not exist. When none of the requested columns exist, the provider should return DB_E_ERRORSOCCURRED and not set any of the *pData values pointed to by the elements of rgColumns. If any other error is returned, no column values are retrieved.

If a row is obtained from a parent row using this method, the updatability of the row is inherited from the parent row.

If a column is of type DBTYPE_IDISPATCH or DBTYPE_IUNKNOWN or is a DBTYPE_VARIANT containing an object value, IRow::GetColumns returns an IDispatch or IUnknown pointer, as appropriate. Callers that wish to request another interface supported by the object should call IRow::Open.

If a row object has a source rowset and changes to the source rowset are deferred, changes to all columns of the row object are also deferred. Therefore, IRow::GetColumns returns the current value of all row columns and the original values of row columns that are not part of the source rowset are unavailable.

If the provider supports type conversions to or from the data types described by the DBCOLUMNINFO structure, it should implement IConvertType on row objects. This interface is used to report whether a given conversion is supported. Providers are strongly encouraged to delegate data type conversions to the OLE DB Data Conversion library (Oledb32.dll).

For more information, see Data Conversion Library in Appendix H: Data Type Conversion Interfaces.