Custom Interfaces

About Custom Interfaces

SAS provides three custom interfaces that can be used to return data set metadata that does not directly map to OLE DB constructs.
  • The ISASColumnsInfo interface has one method.
  • The ISASDataSetInfo interface has two methods.
  • The ISASDataSetInfo90 interface is an extension to the ISASDataSetInfo interface. The ISASDataSetInfo90 interface has four methods. Two are shared with the ISASDataSetInfo interface and two are unique to the ISASDataSetInfo90 interface.

ISASColumnsInfo Custom Interface

The GetColumnInfo Method

The single ISASColumnsInfo interface method is called GetColumnInfo. GetColumnInfo supplements the standard OLE DB IColumnsInfo interface methods. It returns SAS column metadata that is not supported by the GetColumnInfo method in the standard IColumnsInfo interface.
HRESULT GetColumnInfo(
        DBORDINAL * pcColumns,
        SASCOLUMNINFO ** prgInfo,
        OLECHAR ** ppStringsBuffer );
GetColumnInfo returns a fixed set of column metadata in an array of SASCOLUMNINFO structures, one structure per column. The structures appear in the same order in which the columns appear in the rowset (column ordinal order). This order is determined by the order in which the columns are returned from IColumnsInfo::GetColumnInfo. Bookmark columns are never included in the output of this method. Here is the definition of the SASCOLUMNINFO structure:
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.
Elements (Members) of the SASCOLUMNINFO Structure
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 value 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.
iSortInfo1
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.
fIndexed
True when this column is an indexed column.
1For the SAS/SHARE, Local, and Base SAS providers, this member is valid. For the SAS IOM provider, this member is not valid. That is, it always contains 0 whether the column participates in the sorting.
Here are the parameters for the GetColumnInfo method:
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.
Here are the return codes for the GetColumnInfo method:
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.
Tip
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.

ISASDataSetInfo Custom Interface

The GetDataSetInfo Method

The GetDataSetInfo method returns SAS file metadata that is not supported by predefined OLE DB constructs.
HRESULT GetDataSetInfo(
        SASDATASETINFO ** ppDataSetInfo,
        OLECHAR ** ppStringsBuffer );
The GetDataSetInfo method makes no logical change to the state of the object. The GetDataSetInfo method returns metadata about the file in a SASDATASETINFO structure.
typedef struct tagSASDATASETINFO {
        LONG lLogicalRecordCount;
        LONG lPhysicalRecordCount;
        LONG lRecordLength;
        DATE dDateCreated;
        DATE dDateModified;
        LPOLESTR pwszLabel;
        LPOLESTR pwszCompressionRoutine;
        BOOL fIsIndexed;
} SASDATASETINFO;
The elements (members) of the SASDATASETINFO structure are described in the following table:
Elements (Members) of the SASDATASETINFO Structure
Element
Description
lLogicalRecordCount
The number of logical records in the data set. This value is the number of records that are returned if the caller sequentially reads through the entire data set. If this value is not immediately available, a value of -1 is returned in this field. This situation occurs when the data set is not a physical file (for example, a SAS data view or a WHERE clause). In such cases, you can use the GetRecordCounts method to computationally determine this value.
lPhysicalRecordCount
The number of physical records in the data set. This number can be greater than the number of logical records and can indicate the magnitude of the physical file size. If this value is not immediately available, a value of -1 is returned in this field. This situation occurs when the data set is not a physical SAS file (for example, a SAS data view or a SAS/ACCESS table). In such cases, you can use the GetRecordCounts method to computationally determine this value.
lRecordLength
The physical record length in bytes.
dDateCreated
The date that the data set was created.
dDateModified
The date that the data set was last modified.
pwszLabel
The data set label. NULL if none is set.
pwszCompressionRoutine
The name of the compression algorithm used. NO if none is set.
fIsIndexed
TRUE if an index exists on the data set.
Under some circumstances, the actual values for the lLogicalRecordCount and lPhysicalRecordCount members of the SASDATASETINFO structure are not immediately available. This situation occurs when the underlying data set is something other than a physical SAS data file (for example, a SAS data view, a WHERE clause, or a SAS/ACCESS file). In those cases, the members return a -1. To determine the actual values, call ISASDataSetInfo::GetRecordCounts.
Here are the parameters for the GetDataSetInfo method:
ppDataSetInfo
[out] A pointer to the memory where a SASDATASETINFO structure will be returned. If *ppDataSetInfo is NULL when GetDataSetInfo is executed, then the provider allocates memory for this structure and returns the address to the memory location specified by this pointer. When the memory is no longer needed, you use IMalloc::Free to free the memory. As an alternative to depending on the provider to allocate memory for the SASDATASETINFO structure, the consumer can allocate memory for this structure and pass in the address as *ppDataSetInfo.
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.
Here are the return codes for the GetDataSetInfo method:
S_OK
indicates that the method succeeded.
E_FAIL
indicates that a provider-specific error occurred.
E_INVALIDARG
indicates that the ppDataSetInfo or the ppStringsBuffer was a null pointer.
E_OUTOFMEMORY
indicates that the provider was unable to allocate sufficient memory for the data set information structures.

The GetRecordCounts Method

The GetRecordCounts method determines the number of logical and physical records in a data set by forcing a sequential read of the data set. Call this method only when GetDataSetInfo returns -1 in the SASDATASETINFO lLogicalRecordCount and lPhysicalRecordCount fields.
HRESULT GetRecordCounts(
        LONGLONG * plLogicalRecordCount,
        LONGLONG * plPhysicalRecordCount );
CAUTION:
Executing this method on a very large data set might incur a significant performance cost.
Here are the parameters for the GetRecordCounts method:
plLogicalRecordCount
[out]
A pointer to the memory where the logical number of records in the data set will be returned. This number indicates how many rows are returned if every row is read once. If this value exceeds a LONGLONG, a value of -1 is returned in this field.
plPhysicalRecordCount
[out]
A pointer to the memory where the physical number of records in the data set will be returned. This number might be greater than the number of logical records. It indicates how many records are allocated in the data set. This value multiplied by the length of an individual record (lRecordLength returned by GetDataSetInfo approximates the magnitude of the physical size of the data set. If this value exceeds a LONGLONG, a value of -1 is returned in this field.
Here are the return codes for the GetRecordCounts method:
S_OK
indicates that the method succeeded.
E_FAIL
indicates that a provider-specific error occurred.
E_INVALIDARG
indicates that plLogicalRecordCount or plPhysicalRecordCount was a null pointer.

ISASDataSetInfo90 Custom Interface

The GetDataSetInfo_2 Method

The GetDataSetInfo_2 method returns file metadata that is specific to SAS. It is a revised version of GetDataSetInfo that permits larger record counts.
HRESULT GetDataSetInfo_2(
        SASDATASETINFO90 ** ppDataSetInfo,
        OLECHAR ** ppStringsBuffer );
This method makes no logical change to the state of the [SAS file?] object. The GetDataSetInfo_2 method returns file metadata in a SASDATASETINFO90 structure.
typedef struct tagSASDATASETINFO90 {
        LONGLONG llLogicalRecordCount;
        LONGLONG llPhysicalRecordCount;
        LONG lRecordLength;
        DATE dDateCreated;
        DATE dDateModified;
        LPOLESTR pwszLabel;
        LPOLESTR pwszCompressionRoutine;
        BOOL fIsIndexed;
} SASDATASETINFO90;
The elements (members) of the SASDATASETINFO90 structure are described in the following table:
Elements (Members) of the SASDATASETINFO90 Structure
Element
Description
llLogicalRecordCount
The number of logical records in the data set. This value is the number of records that are returned if the caller reads sequentially through the entire data set. If this value is not immediately available, a value of -1 is returned in this field. This situation occurs when the data set is not a physical file (for example, a SAS data view or a WHERE clause). In such cases, you can use the GetRecordCounts_2 method to computationally determine this value.
llPhysicalRecordCount
The number of physical records in the data set. This number can be greater than the number of logical records and can indicate the magnitude of the physical file size. If this value is not immediately available, a value of -1 is returned in this field. This situation occurs when the data set is not a physical SAS file (for example, a SAS data view or a SAS/ACCESS table). In such cases, you can use the GetRecordCounts_2 method to computationally determine this value.
lRecordLength
The physical record length in bytes.
dDateCreated
The date that the data set was created.
dDateModified
The date that the data set was last modified.
pwszLabel
The data set label. NULL if none is set.
pwszCompressionRoutine
The name of the compression algorithm used. NO if none is set.
fIsIndexed
TRUE if an index exists on the data set.
Under some circumstances, the actual values for the llLogicalRecordCount and llPhysicalRecordCount members of the SASDATASETINFO90 structure are not immediately available. This situation occurs when the underlying data set is something other than a physical SAS data file (for example, a SAS data view, a WHERE clause, or a SAS/ACCESS file). In those cases, the members return a -1. To determine the actual values, call ISASDataSetInfo90::GetRecordCounts_2.
Here are the parameters for the GetDataSetInfo_2 method:
ppDataSetInfo
[out] A pointer to the memory where a SASDATASETINFO90 structure will be returned. If *ppDataSetInfo is NULL when GetDataSetInfo_2 is executed, then the provider allocates memory for this structure and returns the address to the memory location specified by this pointer. When the memory is no longer needed, you use IMalloc::Free to free the memory. As an alternative to depending on the provider to allocate memory for the SASDATASETINFO90 structure, the consumer can allocate memory for this structure and pass in the address as *ppDataSetInfo.
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.
Here are the return codes for the GetDataSetInfo_2 method:
S_OK
indicates that the method succeeded.
E_FAIL
indicates that a provider-specific error occurred.
E_INVALIDARG
indicates that ppDataSetInfo or ppStringsBuffer was a null pointer.
E_OUTOFMEMORY
indicates that the provider was unable to allocate sufficient memory for the data set information structures.

The GetRecordCounts_2 Method

The GetRecordCounts_2 method determines a count of the number of logical and physical records in a data set by forcing a sequential read of the data set. Call this method only when GetDataSetInfo_2 returns -1 in the SASDATASETINFO90 llLogicalRecordCount and llPhysicalRecordCount fields.
HRESULT GetRecordCounts_2(
        LONGLONG * pllLogicalRecordCount,
        LONGLONG * pllPhysicalRecordCount );
CAUTION:
Executing this method on a very large data set might incur a significant performance cost.
Here are the parameters for the GetRecordCounts_2 method:
pllLogicalRecordCount
[out] A pointer to the memory where the logical number of records in the data set will be returned. This number indicates how many rows are returned if every row is read once.
pllPhysicalRecordCount
[out] A pointer to the memory where the physical number of records in the data set will be returned. This number might be greater than the number of logical records. It indicates how many records are allocated in the data set. This value multiplied by the length of an individual record (lRecordLength returned by GetDataSetInfo_2) approximates the magnitude of the physical size of the data set.
Here are the return codes for the GetRecordCounts_2 method:
S_OK
indicates that the method succeeded.
E_FAIL
indicates that a provider-specific error occurred.
E_INVALIDARG
indicates that pllLogicalRecordCount or pllPhysicalRecordCount was a null pointer.