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

hGridHandle passed back from EssGNewGrid.
pszConditionsString (no greater than 64K) containing Essbase report specification commands relating to the conditions for the retrieval.
ulOptionsA 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

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