IMDDataset::GetAxisInfo

OLE DB Programmer's Reference

Returns the number of axes in the current dataset and detailed information about each axis.

HRESULT GetAxisInfo(    DBCOUNTITEM   *pcAxes,    MDAXISINFO   **prgAxisInfo);

Parameters

*pcAxes

[out]
A pointer to a long integer. The provider populates this with the number of elements in the prgAxisInfo array, which is the number of axes in the dataset.

prgAxisInfo

[out]
A pointer to an array of MDAXISINFO structures. Each member of this array contains information about one axis. The provider allocates this array as long as prgAxisInfo is not a null pointer.

Return Code

S_OK

The method succeeded.

E_FAIL

A provider-specific error occurred.

E_INVALIDARG

pcAxes was a null pointer.

Both pcAxes and prgAxisInfo were null pointers.

E_OUTOFMEMORY

The provider was unable to allocate sufficient memory to return the array of MDAXISINFO structures.

Comments

Information about the slicer dimensions is returned as an MDAXISINFO structure whose iAxis is MDAXIS_SLICERS. Information about each axis is available in the form of the MDAXISINFO structure. (For a description of the various structure fields, see "MDAXISINFO Structure.")

When moving from one element of the MDAXISINFO array to the next, consumers should use the macro PMDAXISINFO_GETAT or MDAXISINFO_GETAT. These macros are defined in the header as follows:

// Return a ptr to a MDAXISINFO struct given a pointer to an array of // MDAXISINFO structures typically used by applications to iterate over // the array returned by IMDDataset::GetAxisInfo. #define PMDAXISINFO_GETAT(rgAxisInfo,iAxis) \    ((MDAXISINFO *)(((BYTE*)rgAxisInfo) + iAxis * rgAxisInfo[0].cbSize)) // Return a MDAXISINFO structure given a pointer to an array of // MDAXISINFO structures typically used by applications to iterate over // the array returned by IMDDataset::GetAxisInfo. #define MDAXISINFO_GETAT(rgAxisInfo,iAxis) \    (*PMDAXISINFO_GETAT(rgAxisInfo, iAxis))

PMDAXISINFO_GETAT takes a pointer to an MDAXISINFO array and a desired axis (index into the array). It returns a pointer to the MDAXISINFO structure for that axis. MDAXISINFO_GETAT simply dereferences the pointer returned by PMDAXISINFO_GETAT.

For example, the following code processes the MDAXISINFO array returned by this method in a loop:

pIMDDataset->GetAxisInfo(&cAxes, &rgAxisInfo); for (iAxis = 0; iAxis < cAxes; iAxis++) {    ProcessAxisRowset(PMDAXISINFO_GETAT(rgAxisInfo, iAxis); }

Consumers must use IMDDataset::FreeAxisInfo to free memory allocated for prgAxisInfo. Using IMalloc::Free might not free all the memory allocated for the array of MDAXISINFO structures.

If prgAxisInfo is a null pointer, the provider returns only the number of axes in the dataset.

If an error occurs, *pcAxes is set to 0 and *prgAxisInfo is set to NULL.

1998-2001 Microsoft Corporation. All rights reserved.