# EssGBeginConditionalRetrieve

Description

EssGBeginConditionalRetrieve() begins a conditional retrieval operation.

Syntax

    ESSG_FUNC_M EssGBeginConditionalRetrieve (hGrid, pszConditions,
    ulOptions);

ESSG_HGRID_T | hGrid
ESSG_STR_T | pszConditions
ESSG_ULONG_T | ulOptions

Parameters

hGrid | Handle passed back from EssGNewGrid.
pszConditions | String (no greater than 64K) containing Essbase report specification commands relating to the conditions for the retrieval.
ulOptions | A constant which describes the type of retrieval. One of the following values must be used: ESSG_RET_RETRIEVE Retrieve Only ESSG_RET_RETRIEVELOCK Retrieve and Lock ESSG_RET_LOCKONLY Lock Only (No data is to be retrieved) The following value may be or-ed into ulOptions: ESSG_NOATTRIBUTES returns grid without pAttributes values

Return Value

If successful, returns ESSG_STS_NOERR.

Notes

- Begins a conditional retrieval operation.
- Conditions, as defined in a partial report specification, are applied to the provided grid.
- Attributes for returned cell values are obtained using a second server request. Passing ESSG_NOATTRIBUTES in the ulOptions parameter will issue one less request of the server, and could, in large resulting grids, be faster.

Access

None.

Example

    ESSG_VOID_T ESSG_BeginConditionalRetrieve(ESSG_HGRID_T hGrid)
    {
      ESSG_STS_T     sts = ESS_STS_NOERR;
      ESSG_PPDATA_T   ppDataIn;
      ESSG_PPDATA_T   ppDataOut;
      ESSG_RANGE_T   rDataRangeIn, rDataRangeOut;
      ESSG_ULONG_T   ulOptions;
      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_RET_RETRIEVE;
        pszConditions = "<TOP(Scenario,3,@Datacol(3))";
        /* start the conditional retrieve operation */
        sts = EssGBeginConditionalRetrieve(hGrid,
              pszConditions, ulOptions);
      }

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

      if(sts == 0)
      {
        /* perform the retrieval */
        sts = EssGPerformOperation(hGrid, 0);

        /* free the built data */
        FreeTwoDim(ppDataIn, rDataRangeIn.ulNumRows);
      }
      if(sts == 0)
      {
        /* determine the results of the retrieve */
        sts = EssGGetResults(hGrid, 0, &rDataRangeOut,
              &usState);
      }
      if(sts ==0)
      {
        /* get all the data */
        sts = EssGGetRows(hGrid, 0, &rDataRangeOut,
              &rDataRangeOut, &ppDataOut);
      }

      if(sts == 0)
      {
        /* display the results */
        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