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

    }