ISASDataSetInfo

The ISASDataSetInfo interface surfaces data set metadata that does not directly map to OLE DB constructs.

Method	Description
GetDataSetInfo	Returns SAS specific file metadata.
GetRecordCounts	Returns information about the number of records that are associated with a file.

ISASDataSetInfo::GetDataSetInfo

Returns SAS file metadata that is not supported by predefined OLE DB constructs.

HRESULT GetDataSetInfo(
        SASDATASETINFO **       ppDataSetInfo,
        OLECHAR **              ppStringsBuffer );

Parameters

pDataSetInfo

[out]
A pointer to memory in which to return a SASDATASETINFO structure. If *pDataSetInfo is NULL on entry, then the provider allocates memory for this structure and returns the address to this memory. The user releases this memory with IMalloc::Free when it is done. The user can allocate memory for this structure itself and pass in the address as *pDataSetInfo.

ppStringsBuffer

[out]
A pointer to memory in which to return a pointer to storage for all string values (for example,  pwszLabel and pwszCompressionRoutine) within a single allocation block.  If there is no string data to return or if this method terminates due to error, this parameter is NULL on return. If there is any string data, then this will be a buffer containing all the values for those strings. The user should free the buffer with IMalloc::Free when finished working with the strings. Each of the individual strings that is 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 ppDataSetInfo or ppStringsBuffer was a null pointer.

E_OUTOFMEMORY

indicates that the provider was unable to allocate sufficient memory in which to return the data set information structures.

Details

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

The lLogicalRecordCount and lPhysicalRecordCount members of the SASDATASETINFO structure returned may be -1. This indicates that the actual values for these members is not immediately available.  Such is the case when the underlying data set is something other than a phsyical SAS data file (for example, a view, a WHERE clause, a SAS/Access file, and so on). In these instances, you can determine these values by calling ISASDataSetInfo's other method, GetRecordCounts.

SASDATASETINFO Structure

GetDataSetInfo returns file metadata 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 of this structure are used as follows:

Element	Description
lLogicalRecordCount	The number of logical records in the data set. This 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, -1 is returned in this field; such is the case when the data set is not a physical file (for example, a view or a WHERE clause is set).   In such cases, GetRecordCounts can be used to computationally determine this value.
lPhysicalRecordCount	The number of physical records in the data set.  This can be greater than the number of logical records. This value can indicate the magnitude of the physical file size. If this value is not immediately available, -1 is returned in this field; such is the case when the data set is not a physical SAS file (for example, a view or a SAS Access table). In such cases, GetRecordCounts can be used to computationally determine this value.
lRecordLength	The physical record length in bytes.
dDateCreated	The date the data set was created.
dDateModified	The date 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.

ISASDataSetInfo::GetRecordCounts

Forces a count of the number of logical and physical records on a data set.  This should only be called when GetDataSetInfo returns -1 in the SASDATASETINFO lLogicalRecordCount and lPhysicalRecordCount fields.

HRESULT GetRecordCounts(
        LONG *          plLogicalRecordCount,
        LONG *          plPhysicalRecordCount );

Parameters

plLogicalRecordCount

[out]

pointer to memory in which to return the logical number of records in the data set.   This number indicates how many rows are returned if every row is read once.

plPhysicalRecordCount

[out]
pointer to memory in which to return the physical number of records in the data set. This number might be greater than the number of logical records. It indicates how many records are allocated in the data set.

Return Codes

S_OK

indicates that the method succeeded.

E_FAIL

indicates that a provider-specific error occurred.

E_INVALIDARG

indicates that plLogicalRecordCount of plPhysicalRecordCount was a null pointer.

Comments

This method forces a sequential read of the data set in order to determine the record counts. If the underlying data set is large, this can take some time. The consumer should not call this method indiscriminately.  Some data sets contain literally millions of records, and executing this method on such a data set can incur a significant performance cost.