# EssGBeginReport

Description

EssGBeginReport() runs a report script at the server.

Syntax

    ESSG_FUNC_M EssGBeginReport (hGrid, pszReportIn, ulOptions)

ESSG_HGRID_T | hGrid
ESSG_STR_T | pszReportIn
ESSG_ULONG_T | ulOptions

Parameters

hGrid | Handle passed back from EssGNewGrid.
pszReportIn | String (no greater than 64K) containing an Essbase report specification.
ulOptions | A bitmask which describes returned grid options. Valid values are: ESSG_NOATTRIBUTES returns grid without pAttributes values.

Return Value

If successful, returns ESSG_STS_NOERR.

Notes

- Runs a report script at the server.
- Returns the results as a two-dimensional array of cells.
- You do not need to send any rows for this operation. It is sufficient to call EssGPerformOperation, EssGGetResults, and EssGGetRows.
- Attributes for returned cell values are obtained using a second server request. Passing ESSG_NOATTRIBUTES for the ulOptions parameter will issue one less request of the server, and could, in large resulting grids, be faster.
- Reports passed to the server via the Grid API should be sure to request a tab delimited report format be returned {TABDELIM}. If a non-tab delimited report is returned, the Grid API may be unable to convert the resulting report into a grid.
- If the report specification modifies the string used for #Missing aliases, then Missing cells will be returned as string types (ESSG_DT_STRING) with the new #Missing alias as the text and not as ESSG_DT_MISSING cells.
- Client programs that call EssGBeginReport() and other report functions need to take into account new Grid API Structures and Grid API data types (specifically StringEx and MemberEx). Older programs should be revised in order to work with the newer servers.

Access

None.

Example

    ESSG_VOID_T ESSG_BeginReport (ESSG_HGRID_T hGrid)

    {
      ESSG_FUNC_M    sts = ESS_STS_NOERR;
      ESSG_PPDATA_T        ppDataOut;
      ESSG_RANGE_T         rDataRangeOut;
      ESSG_ULONG_T         ulOptions;
      ESSG_STR_T           pszReportIn;
      ESSG_USHORT_T        usState;

      /* connect the grid to a database on the server */
      sts = EssGConnect(hGrid, "Rainbow", "Admin", "Password", "Demo", "Basic",
            ESSG_CONNECT_DEFAULT);

      if(sts == 0)
      {
         pszReportIn = "{TabDelim}<idesc Year !";
         ulOptions = ESSG_NOATTRIBUTES;

         sts = EssGBeginReport(hGrid, pszReportIn,
               ulOptions);
      }

      if(sts == 0)
      {
         /* perform the report */
         sts = EssGPerformOperation(hGrid, 0);
      }

      if(sts == 0)
      {
         /* determine the results of the report */
         sts = EssGGetResults(hGrid, 0, &rDataRangeOut,
               &usState);
      }

      if(sts ==0)
      {
         /* 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