Grid API Reference

Grid API Declarations
Grid API Functions Reference
Example
Error Codes

Example

This example illustrates the steps needed to perform a basic retrieval. The following grid shows a five dimensional template with one datapoint illustrated.

The following code fragment shows how the data structures are setup and the function calls that are needed to perform the retrieval. Note: No error checking is done in the following functions.

/* This function allocates the necessary data to send to the server */
ESSG_PPDATA_T AllocTwoDims (ESS_ULONG_T ulRows, ESS_ULONG_T ulCols)
{
        ESSG_PPDATA_T   ppTemp;
        ESS_ULONG_T     ulIndex;

        ppTemp = malloc(sizeof(ESSG_PDATA_T) * ulRows);
        for (ulIndex = 0; ulIndex < ulRows; ulIndex++)
        {
                ppTemp[ulIndex] = malloc(sizeof(ESSG_DATA_T) * ulCols);
        }

        return ppTemp;
}

/* This function frees the memory allocated by AllocTwoDims */
void FreeTwoDim(ESSG_PPDATA_T ppDataToFree, ESS_ULONG_T ulRows)
{
        ESS_ULONG_T ulIndex;

        for (ulIndex = 0; ulIndex < ulRows; ulIndex++)
        {
                if(ppDataToFree[ulIndex]->usType == ESSG_DT_STRING)
                {
                        free(ppDataToFree[ulIndex]->Value.pszStr);
                }
                free(ppDataToFree[ulIndex]);
        }
        free(ppDataToFree);
}

/* This function builds a table based on the above grid. */
/* Note: The items in the grid are hard coded.           */
ESSG_PPDATA_T BuildTable(ESSG_PRANGE_T pRange)
{
        ESSG_PPDATA_T   ppTable;
        ESS_ULONG_T     ulRow, ulCol;

        /* Your code would probably not be hard-coded here... */
        pRange->ulRowStart      = 0;
        pRange->ulColumnStart   = 0;
        pRange->ulNumRows       = 2;
        pRange->ulNumColumns    = 5;
        ppTable = AllocTwoDims(2, 5);

        /* ROW 1 */
        ppTable[0][0].usType = ESSG_DT_BLANK;
        ppTable[0][1].usType = ESSG_DT_BLANK;
        ppTable[0][2].usType = ESSG_DT_STRING;
        /* Some compilers allow you to specify \p to indicate */
        /* the length of the string */
        ppTable[0][2].Value.pszStr = "\pYear";
        ppTable[0][3].usType = ESSG_DT_STRING;
        ppTable[0][3].Value.pszStr = "\pProduct";
        ppTable[0][4].usType = ESSG_DT_STRING;
        ppTable[0][4].Value.pszStr = "\pMarket";

        /* ROW 2 */
        ppTable[1][0].usType = ESSG_DT_STRING;
        ppTable[1][0].Value.pszStr = "\pActual";
        ppTable[1][1].usType = ESSG_DT_STRING;
        ppTable[1][1].Value.pszStr = "\pSales";
        ppTable[1][2].usType = ESSG_DT_DOUBLE;
        ppTable[1][2].dblData = 123.45;
        ppTable[1][3].usType = ESSG_DT_BLANK;
        ppTable[1][4].usType = ESSG_DT_BLANK;

        return (ppTable);
}

/* This function makes the necessary calls to the */
/* EGAPI to perform a basic retrieval.            */
/* NOTE:  This example does not show the                   */
/* initialization of the EGAPI or the grid.       */
/* Also, the hGrid is assumed to be external.    */
void CallEGAPI(void)
{
        ESSG_PPDATA_T   ppDataIn,
        ESSG_PPDATA_T   ppDataOut;
        ESSG_RANGE_T    rRangeDataIn,rRangeDataOut;
        ESSG_STS_T      sts;
        ESSG_ULONG_T    ulRow, ulCol;
        ESSG_USHORT_T   usState;

        /* Connect the grid to a database on the server */
        sts = EssGConnect(hGrid, "Server", "User", "Password",
                                       "App", "Db", ESSG_CONNECT_DEFAULT);
        if (sts == 0)
        {
                ppDataIn = BuildTable(&rRangeDataIn);
                /* Start the retrieve operation */
                sts = EssGBeginRetrieve(hGrid, ESSG_RET_RETRIEVE);
        }
        if (sts == 0)
        {
                /* Send the entire grid to define the query */
                sts = EssGSendRows(hGrid, &rRangeDataIn, ppDataIn);
        }
        if (sts == 0)
        {
                /* We're done sending rows, perform the retrieval */
                sts = EssGPerformOperation(hGrid, 0);
        
                /* Free the data we built */
                FreeTwoDim(ppDataIn, rRangeDataIn.ulNumRows);
        }
        if (sts == 0)
        {
                /* Determine the results of the retrieve and how much data
                 * is being returned.
                 */
                sts = EssGGetResults(hGrid, 0, &rRangeDataOut, &usState);
        }
        if (sts == 0)
        {
                /* Get all of the data */
                sts = EssGGetRows(hGrid,0, &rRangeDataOut, 
                        &rRangeDateOut, &ppDataOut);
        }
        if (sts == 0)
        {
                /* Interate though the data ... */
                /* First the rows */
                for (ulRow = rRangeDataOut.ulRowStart;
                                ulRow < rRangeDataOut.ulNumRows;
                                ulRow++)
                {
                        /* Then the columns */
                        for (ulCol = rRangeDataOut.ulColumnStart;
                                        ulCol < rRangeDataOut.ulNumColumns;
                                        ulCol++)
                        {
                                /* Here's a cell ... just render it. */
                                switch (ppDataOut[ulRow][ulCol].usType)
                                {
                                        case (ESSG_DT_STRING):
                                                DisplayString(ppDataOut[ulRow][ulCol].Value.pszStr);
                                                break;
                                        case (ESSG_DT_LONG):
                                                DisplayValue(ppDataOut[ulRow][ulCol].Value.lData);
                                                break;
                                        case (ESSG_DT_DOUBLE):
                                                DisplayValue(ppDataOut[ulRow][ulCol].Value.dblData);
                                                break;
                                        case (ESSG_DT_BLANK):
                                                DisplayBlank();
                                                break;
                                        case (ESSG_DT_MISSING):
                                                DisplayMissing();
                                                break;
                                        case (ESSG_DT_ZERO):
                                                DisplayValue(0);
                                                break;
                                        case (ESSG_DT_NOACCESS):
                                                DisplayNoAccess();
                                                break;
                                        case (ESSG_DT_MEMBER):
                                                DisplayString(ppDataOut[ulRow][ulCol].Value.pszStr);
                                                break;
                                        default:
                                                DisplayOops();
                                                break;
                                }
                        }
                }
                /* Tell the API we don't care about this request any more */
                EssGEndOperation(hGrid, 0);
                /* Free the data returned */
                EssGFreeRows(hGrid, &rRangeDataOut, ppDataOut);
        }

        /* Disconnect if you wish */
        EssGDisconnect(hGrid, 0);

}