IColumnsInfo::MapColumnIDs

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

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

Parameters

cColumnIDs

[in]
The number of column IDs to map. If cColumnIDs is 0, 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.

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_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 and the method has not yet returned.

Comments

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

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 life 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.

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.