EssGBeginConditionalRetrieve

Begins a conditional retrieval operation.

Syntax

ESSG_FUNC_M EssGBeginConditionalRetrieve (hGrid, pszConditions, 
ulOptions);

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

Parameter

Data Type

Description

hGrid

ESSG_HGRID_T

Handle passed back from EssGNewGrid.

pszConditions

ESSG_STR_T

String (no greater than 64K) containing Essbase report specification commands relating to the conditions for the retrieval. Do not use Report Writer member/alias/unique name handling formatting commands for the pszConditions parameter. Use the options available in the EssGSetGridOption function.

ulOptions

ESSG_ULONG_T

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 added into ulOptions using bitwise OR (|): ESSG_NOATTRIBUTES returns grid without pAttributes values.

Notes

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