# 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