EssGBeginRetrieve

Description

EssGBeginRetrieve() begins the basic retrieval operation. Additionally, this function will optionally lock blocks at the server for eventual update as the rows are passed in via EssGSendRows.

Syntax

ESSG_FUNC_M EssGBeginRetrieve (hGrid, ulOptions);
ESSG_HGRID_T hGrid
ESSG_ULONG_T ulOptions

Parameters

hGridHandle passed back from EssGNewGrid.
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)

Return Value

If successful, returns ESSG_STS_NOERR.

Notes

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

See Also

Using the Grid API Functions
Grid API Structures