ISASColumnsInfo Custom Interface

The ISASColumnsInfo interface method supplements the standard OLE DB IColumnsInfo interface methods. Its single method returns column metadata that is specific to SAS and does not directly map to OLE DB constructs.

Method	Description
GetColumnInfo	Returns column metadata that is specific to SAS

The GetColumnInfo Method

As part of the ISASColumnsInfo customized interface, the GetColumnInfo method returns the SAS column metadata that is not supported by the GetColumnInfo method in the standard IColumnsInfo interface.

HRESULT GetColumnInfo(
        ULONG *                 pcColumns,
        SASCOLUMNINFO **        prgInfo,
        OLECHAR **              ppStringsBuffer );

Parameters

pcColumns: [out]
A pointer to the memory where the number of columns in the rowset will be returned. This number will not include the bookmark column even if there is one. If this method terminates as the result of an error, *pcColumns is set to 0.
prgInfo: [out]
A pointer to the memory where an array of SASCOLUMNINFO structures will be returned. One structure is returned for each column that is in the rowset. The provider allocates memory for the structures and returns the address of the memory location. When the memory is no longer needed by the column information, you use IMalloc::Free to release the memory. If *pcColumns is 0 when it is calculated or this method terminates as the result of an error, the provider does not allocate any memory and ensures that *prgInfo is a NULL pointer.
ppStringsBuffer: [out]
A pointer to the memory where column string names will be returned. All of the column string values (names) are stored within a single allocation block. If no returned columns have string names, or if this method terminates as the result of an error, *ppStringsBuffer will be set to NULL. If one or more columns has a string name, then the specified memory location contains the string values (names) for the columns. When the names are no longer needed, you use IMalloc::Free to release the memory. If *pcColumns is 0 when calculated or this method terminates as the result of an error, the provider does not allocate any memory and ensures that *ppStringsBuffer is a NULL pointer. Each string value stored in this buffer is terminated by a null-termination character.

Return Codes

S_OK: indicates that the method succeeded.
E_FAIL: indicates that a provider-specific error occurred.
E_INVALIDARG: indicates that pcColumns, prgInfo, or ppStringsBuffer was a null pointer.
E_OUTOFMEMORY: indicates that the provider was unable to allocate sufficient memory for the column information structures.

Usage Notes

This method makes no logical change to the state of the object. GetColumnInfo returns a fixed set of column metadata in an array of SASCOLUMNINFO structures, one structure per column.

The order of the structures is the order in which the columns appear in the rowset (column ordinal order). This is the same order in which they are returned from IColumnsInfo::GetColumnInfo.

Bookmark columns are never included in the output of this method.

Note: The GetColumnInfo method provides a quick alternative to the GetColumnsRowset method. While the GetColumnsRowset method returns all available column metadata, it does so in a rowset. To get the metadata, the consumer must create the column metadata rowset, create one or more accessors, get each row in the rowset, and get the data from the rowset.

The SASCOLUMNINFO Structure

GetColumnInfo returns column metadata in SASCOLUMNINFO structures.

typedef struct tagSASCOLUMNINFO {
        LPOLESTR pwszColDesc;
        LPOLESTR pwszFmtName;
        LPOLESTR pwszIFmtName;
        ULONG iOrdinal;
        SHORT iFmtLength;
        SHORT iFmtDecimal;
        SHORT iIFmtLength;
        SHORT iIFmtDecimal;
        SHORT iSortInfo;
        BOOL fIndexed;
} SASCOLUMNINFO;

The elements (members) of the SASCOLUMNINFO structure are described in the following table:

Element	Description
pwszColDesc	Pointer to the column description (the SAS variable label). If no label is associated with this column, this member is NULL.
pwszFmtName	Pointer to the persisted format name. If no format is associated with this column, this member is NULL.
pwszIFmtName	Pointer to the persisted informat name. If no informat is associated with this column, this member is NULL.
iOrdinal	The ordinal of the column. This corresponds to the SAS variable number.
iFmtLength	The width of the formatted data. This member is valid only when pwszFmtName is not NULL.
iFmtDecimal	The decimal width of the format data. This member is valid only when pwszFmtDecimal is not NULL.
iIFmtLength	The width of the informatted data. This member is valid only when pwszIFmtName is not NULL.
iIFmtDecimal	The decimal width of the informatted data. This member is valid only when pwszIFmtName is not NULL.
iSortInfo	A signed short value that indicates the column's position in any applied sorting hierarchy. Positive values indicate ascending sort order, and negative values indicate descending sort order. The absolute value of the signed short value describes the position of the variable in the sorting hierarchy. Zero (0) indicates that the column does not participate in sorting. Note: For the SAS/SHARE and local providers, this member is valid. For the SAS IOM Data Provider, this member is not valid. That is, it always contains 0 whether or not the column participates in the sorting.
fIndexed	True when this column is an indexed column.

Resources