EssGBeginConditionalZoomIn
Description
EssGBeginConditionalZoomIn() begins a conditional zoom-in.
Syntax
ESSG_FUNC_M EssGBeginConditionalZoomIn (hGrid, pZoomCell,
pszConditions, ulOptions);
ESSG_HGRID_T | hGrid |
ESSG_PRANGE_T |
pZoomCell |
ESSG_STR_T | pszConditions |
ESSG_ULONG_T | ulOptions |
Parameters
hGrid | Handle passed back from
EssGNewGrid.
|
pZoomCell | Describes the cell
to be zoomed in upon. This must be a single cell for conditional zoomin.
|
pszConditions | String (no
greater than 64K) containing Essbase report specification commands relating
to the conditions for the zoom-in.
|
ulOptions | A bitmask which
describes the type of zoom-in (across or down). The following two values are
mutually exclusive:
- ESSG_ZOOM_DOWN Any page/title dimensions
selected will be zoomed down
- ESSG_ZOOM_ACROSS Any page dimensions selected
will be zoomed across
The following option may be or-ed in to the ulOptions parameter:
ESSG_NOATTRIBUTES returns grid without pAttributes values
|
Return Value
If successful, returns ESSG_STS_NOERR.
Notes
- Begins a conditional zoom-in.
- The cell to be zoomed in upon is described by single range,
the conditions to be applied are passed as a string containing
Essbase report specification commands.
- Attributes for returned cell values are obtained using a second
server request. Passing ESSG_NOATTRIBUTES for the
ulOptions parameter will issue one less request of the
server, and could, in large resulting grids, be faster.
- Conditional zoom-in will only work on one zoom cell at a time.
- There are only three valid zoom levels when doing a conditional
ZoomIn - ESSG_NEXTLEVEL, ESSG_BOTTOMLEVEL
or ESSG_ALLLEVELS. The Zoom level for conditional
ZoomIn must be set via EssGSetGridOption to one of the
three valid levels. If a non-valid level is set when performing
a conditional ZoomIn the API will default to ESSG_NEXTLEVEL.
- If the zoom level is ESSG_BOTTOMLEVEL the resulting
members are selected based on the conditions from all Level zero
members in the dimension being zoomed on. For example, if the
zoom cell contains East, from the Market dimension, and the zoom
level is ESS_BOTTOMLEVEL, the resulting members could
be any of the leaf members of Market, not just descendents of
East.
Access
None.
Example
ESSG_VOID_T ESSG_BeginConditionalZoomIn(ESSG_HGRID_T hGrid)
{
ESSG_FUNC_M sts = ESS_STS_NOERR;
ESSG_PPDATA_T ppDataIn;
ESSG_PPDATA_T ppDataOut;
ESSG_RANGE_T rDataRangeIn, rDataRangeOut;
ESSG_ULONG_T ulOptions;
ESSG_RANGE_T pZoomCells;
ESSG_USHORT_T usState;
ESSG_STR_T pszConditions;
/* connect the grid to a database on the server */
sts = EssGConnect(hGrid, "Rainbow", "Admin",
"Password", "Demo", "Basic", ESSG_CONNECT_DEFAULT);
if(sts == 0)
{
ppDataIn = BuildTable(&rDataRangeIn);
ulOptions = ESSG_ZOOM_DOWN | ESSG_ALLLEVELS;
pZoomCells.ulRowStart = 0;
pZoomCells.ulColumnStart = 2;
pZoomCells.ulNumRows = 1;
pZoomCells.ulNumColumns = 1;
pszConditions = "<TOP("Scenario",3,@Datacol(3))";
/* start the conditional zoom-in operation */
sts = EssGBeginConditionalZoomIn(hGrid,
&pZoomCells, pszConditions, ulOptions);
}
if(sts == 0)
{
/* send the entire grid to define the query */
sts = EssGSendRows(hGrid, &rDataRangeIn,
ppDataIn);
}
if(sts == 0)
{
/* perform the conditional zoom-in */
sts = EssGPerformOperation(hGrid, 0);
/* Free the built data */
FreeTwoDim(ppDataIn, rDataRangeIn.ulNumRows);
}
if(sts == 0)
{
/* determine the results of conditional zoom-in */
sts = EssGGetResults(hGrid, 0, &rDataRangeOut, &usState);
}
if(sts ==0)
{
/* get all the data */
sts = EssGGetRows(hGrid, 0, &rDataRangeOut,
&rDataRangeOut, &ppDataOut);
}
if(sts == 0)
{
DisplayOutput(ppDataOut, rDataRangeOut);
/* free the returned data */
EssGFreeRows(hGrid, &rDataRangeOut, ppDataOut);
}
if(sts == 0)
{
EssGEndOperation(hGrid, 0);
EssGDisconnect(hGrid, 0);
}
}
See Also
Using the Grid API Functions
Grid API Structures