EssGBeginRetrieve

Begins the basic retrieval operation.

Syntax

ESSG_FUNC_M EssGBeginRetrieve (hGrid, ulOptions);

Parameter	Data Type	Description
hGrid	ESSG_HGRID_T	Handle passed back from EssGNewGrid.
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)

Notes

Optionally locks blocks at the server for later update as the rows are passed in via EssGSendRows.
You can do a retrieval without sending any rows in order to get a default grid with the only the dimension names used as members.

Return Value

If successful, returns ESSG_STS_NOERR.

Access

None.

Example

#include <essapin.h>
#include <essgapin.h>
   
ESSG_VOID_T ESSG_BeginRetrieve(ESSG_HGRID_T hGrid)
   {
   ESSG_FUNC_M     sts = ESS_STS_NOERR;
   ESSG_PPDATA_T   pDataIn;
   ESSG_PPDATA_T   ppDataOut;
   ESSG_RANGE_T    rDataRangeIn, rDataRangeOut;
   ESSG_ULONG_T    ulOptions;
   ESSG_USHORT_T   usState;

   /* connect the grid to a database on the server */
   sts = EssGConnect(hGrid, "Rainbow", "Admin",
         "Password", "Demo", "Basic", ESSG_CONNECT_NODIALOG);
   
if(sts == 0)
   {
      ppDataIn = BuildTable(&rDataRangeIn);
      ulOptions = ESSG_RET_RETRIEVE;
      /* start the retrieve operation */
      sts = EssGBeginRetrieve(hGrid, ulOptions);
   }

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

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 && usState == ESSG_STATE_DONE)
   {
      /* 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);
   }
}