EssGBeginConditionalZoomIn

Begins a conditional zoom-in.

Syntax

ESSG_FUNC_M EssGBeginConditionalZoomIn (hGrid, pZoomCell,
pszConditions, ulOptions);

Parameter	Data Type	Description
hGrid	ESSG_HGRID_T	Handle passed back from EssGNewGrid.
pZoomCell	ESSG_RANGE_T	Describes the cell to be zoomed in upon. This must be a single cell for conditional zoomin.
pszConditions	ESSG_STR_T	String (no greater than 64K) containing Essbase report specification commands relating to the conditions for the zoom-in. Do not use Report Writer member/alias/unique name handling formatting commands for the pszConditions parameter. Use the options available in EssGSetGridOption.
ulOptions	ESSG_ULONG_T	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 added into ulOptions using bitwise OR (\|): ESSG_NOATTRIBUTES returns grid without pAttributes values.

Notes

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.
In case of Type-enabled applications, such as applications with SmartList, Date, or Format strings, you will get textual encoded data but without type information if you specify ESSG_NOATTRIBUTES. Type information works like member attributes, so do not use ESSG_NOATTRIBUTES if type information is required.

Return Value

If successful, returns ESSG_STS_NOERR.

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);
  }

}