# EssGBeginKeepOnly

Description

EssGBeginKeepOnly() begins a keep-only operation to isolate cells to keep, removing all others.

Syntax

    ESSG_FUNC_M EssGBeginKeepOnly (hGrid, usCells, pKeepCells, ulOptions);

ESSG_HGRID_T | hGrid
ESSG_USHORT_T | usCells
ESSG_RANGE_T | pKeepCells
ESSG_ULONG_T | ulOptions

Parameters

hGrid | Handle passed back from EssGNewGrid.
usCells | A count of the number of cell ranges in pKeepCells (the size of array).
pKeepCells | Describes the cells to be kept. The members to be kept applies only to one dimension. That is, if the user decides to keep, for example, "Qtr1", then all other members of the Time dimension will be removed and the only representative of the Time dimension will be "Qtr1". All other dimensions in the report will be left untouched. This is a one-dimensional array of cell ranges. More than one member from a dimension may be specified. Also, multiple dimensions may be specified.
ulOptions | Reserved for future use. Should be set to zero.

Return Value

If successful, returns ESSG_STS_NOERR.

Notes

- Begins a keep-only.
- The cells to be kept are described by a one-dimensional array of cell ranges. Items to be kept apply on a per dimension basis.

Access

None.

Example

    ESSG_VOID_T ESSG_BeginKeepOnly (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_USHORT_T        usCells;
      ESSG_RANGE_T         pKeepCells;
      ESSG_USHORT_T        usState;

      /* 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);

         pKeepCells.ulRowStart = 1;
         pKeepCells.ulColumnStart = 0;
         pKeepCells.ulNumRows = 1;
         pKeepCells.ulNumColumns = 1;
         ulOptions = 0;
         usCells = 1;

         /* start the keep-only operation */
         sts = EssGBeginKeepOnly(hGrid, usCells,
               &pKeepCells, ulOptions);
      }

      if(sts == 0)
      {
         /* send the entire grid to define the query */
         sts = EssGSendRows(hGrid, &rDataRangeIn,
               ppDataIn);
      }

      if(sts == 0)
      {
         /* perform the keep-only operation */
         sts = EssGPerformOperation(hGrid, 0);

         /* free the built data */
         FreeTwoDim(ppDataIn, rDataRangeIn.ulNumRows);
      }
      if (sts == 0)
      {
         /* determine the results of the keep-only operation */
         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)
      {
          EssGEndOperation(hGrid, 0);
         EssGDisconnect(hGrid, 0);
      }
    }

See Also

Using the Grid API Functions
Grid API Structures