IColumnsInfo::MapColumnIDs

OLE DB Programmer's Reference

Returns an array of ordinals of the columns in a rowset that are identified by the specified column IDs.

HRESULT MapColumnIDs (    DBORDINAL    cColumnIDs,    const DBID   rgColumnIDs[],    DBORDINAL    rgColumns[]);

Parameters

cColumnIDs: [in]
The number of column IDs to map. If cColumnIDs is 0, IColumnsInfo::MapColumnIDs does nothing and returns S_OK.
rgColumnIDs: [in]
An array of IDs of the columns of which to determine the column ordinals. If rgColumnIDs contains a duplicate column ID, a column ordinal is returned once for each occurrence of the column ID. If the column ID is invalid, the corresponding element of rgColumns is set to DB_INVALIDCOLUMN.
rgColumns: [out]
An array of cColumnIDs ordinals of the columns identified by the elements of rgColumnIDs. The consumer allocates, but is not required to initialize, memory for this array and passes the address of this memory to the provider. The provider returns the column IDs in the array.

Return Code

S_OK: The method succeeded. All elements of rgColumns are set to values other than DB_INVALIDCOLUMN.
cColumnIDs was zero; the method succeeded but did nothing. This return code supersedes E_INVALIDARG if cColumnIDs was zero and either or both rgColumnIDs and rgColumns was a null pointer.
DB_S_ERRORSOCCURRED: An element of rgColumnIDs was invalid. If the column ID is invalid, the corresponding element of rgColumns is set to DB_INVALIDCOLUMN.
E_FAIL: A provider-specific error occurred.
E_INVALIDARG: cColumnIDs was not 0, and rgColumnIDs was a null pointer.
rgColumns was a null pointer.
E_UNEXPECTED: ITransaction::Commit or ITransaction::Abort was called, and the object is in a zombie state. This error can be returned only when the method is called on a rowset.
DB_E_ERRORSOCCURRED: All elements of rgColumnIDs were invalid. All elements of rgColumns are set to DB_INVALIDCOLUMN.
DB_E_NOCOMMAND: No command text was set. This error can be returned only when this method is called from the command object.
DB_E_NOTABLE: ICommandPrepare was not implemented, and the specific table or view does not exist in the data store.
DB_E_NOTPREPARED: The command exposed ICommandPrepare, and the command text was set but the command was not prepared. This error can be returned only when this method is called from the command object.
DB_E_NOTREENTRANT: The provider called a method from IRowsetNotify in the consumer that had not yet returned, and the provider does not support reentrancy in this method.

Comments

This method makes no logical change to the state of the object.

IColumnsInfo::MapColumnIDs returns the ordinals of the columns in the rowset that are identified by the elements of rgColumnIDs. These column ordinals do not change during the lifetime of the rowset. Column ordinals may change between different instantiations of a rowset if the command text does not define an order, such as a SELECT * FROM MyTable.

Rowset column ordinals start at 1 and are numbered sequentially in increasing order (for example, 1, 2, 3, and so on). When a row object is derived from a rowset, the row-specific column ordinals must come after the rowset column ordinals.

Two column IDs that are the same—except that one contains a GUID and the other contains a pointer to a GUID—are equivalent if both use the same GUID. Both are mapped to the same column ordinal.

See Also