# 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

hGrid | Handle 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

- Begins the basic retrieval operation.
- Additionally, this function optionally locks blocks at the server for later update.
- 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.

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