EssLROGetCatalogBatch

Retrieves a list of LRO catalog entries for multiple data cells in an Essbase database.

Syntax

ESS_FUNC_M EssLROGetCatalogBatch (hCtx, memCount, pMemComb, cellCount, pulLROCount, ppLRODescList)

Parameter	Data Type	Description
hCtx	ESS_HCTX_T	API context handle.
memCount	ESS_ULONG_T *	Array of 'Number of members' specified in pMemComb,, one for each cell.
pMemComb	ESS_PMBRNAMECOMB_T *	Array of 'member name' combination. Each element of array itself is an array of member names, one for each cell.
cellCount	ESS_ULONG_T	Count of LRO cells.
pulLROCount	ESS_ULONG_T *	Array of 'Number of LRO' catalog entries returned to caller. Each element in array corresponds to the number of LRO catalog entries for an input cell.
pLRODescList	ESS_LRODESC_API_T	Address of pointer to the list of LRO catalog entries returned to caller.

Notes

To use this function, initialize the program with the MaxBuffer field of the initialization structure ESS_INIT_T set to 0xFFFFFFFF bytes.

Return Value

If successful, returns ESS_STS_NOERR. Otherwise, returns an error code.

Access

A call to this function requires read privileges (ESS_PRIV_READ) for the active database.

Example

/*
 * ESS_GetLinkedObjectCatalogBatch() -- Gets a list of LRO description for a list of given data cell
 * From the Database Sample.Basic, it will fetch LROs for the following Cells.
 * 1) "Jan", "Sales", "100-10", "New York", "Actual" 
 * 2) "Feb", "COGS", "200-10", "Utah", "Budget"
 * 3) "Mar", "Payroll", "300-10", "Texas", "Variance"
 */
ESS_STS_T ESS_GetLinkedObjectCatalogBatch(ESS_HINST_T hInst, ESS_HCTX_T hCtx)
{
   ESS_STS_T               status = 0;
   ESS_UINT_T              memberLength = ESS_MBRNAMELEN_NONUNI; 
   ESS_PMBRNAME_NONUNI_T  *ppMemComb=NULL;
   ESS_PMBRNAME_NONUNI_T   pMemComb = NULL;
   ESS_ULONG_T            *pulLroCount= NULL;
   ESS_PLRODESC_API_T      pLroDescList = NULL;
   ESS_PLRODESC_API_T     *ppLroDescList = NULL;
   ESS_ULONG_T             cellCount = 3;            /* Number of cells for which to retrieve LROs */
   ESS_ULONG_T             mbrsCount[3] = {5, 5, 5}; /* Number of members in combinations for each cell */

   ESS_ULONG_T             i,j,k,offset;
   ESS_CHAR_T             *pMember = NULL;
   ESS_CHAR_T              response;

   status = EssAlloc(hInst, cellCount * sizeof(ESS_PMBRNAMECOMB_T), (ESS_PPVOID_T)&ppMemComb);
   if (status) 
      goto exit;

   /* Member combination for Cell # 1 */
   status = EssAlloc(hInst, mbrsCount[0] * memberLength, (ESS_PPVOID_T)&(ppMemComb[0]));
   if (status) 
      goto exit;
   pMemComb = ppMemComb[0];
   memset(pMemComb, 0, mbrsCount[0]* memberLength);
   strcpy((pMemComb)[0], "Jan");
   strcpy((pMemComb)[1], "Sales");
   strcpy((pMemComb)[2], "100-10");
   strcpy((pMemComb)[3], "New York");
   strcpy((pMemComb)[4], "Actual");

   /* Member combination for Cell # 2 */
   status = EssAlloc(hInst, mbrsCount[1] * memberLength, (ESS_PPVOID_T)&(ppMemComb[1]));
   if (status) 
      goto exit;
   pMemComb = ppMemComb[1];
   memset(pMemComb, 0, mbrsCount[1] * memberLength);
   strcpy((pMemComb)[0], "Feb");
   strcpy((pMemComb)[1], "COGS");
   strcpy((pMemComb)[2], "200-10");
   strcpy((pMemComb)[3], "Utah");
   strcpy((pMemComb)[4], "Budget");

   /* Member combination for Cell # 3 */
   status = EssAlloc(hInst, mbrsCount[2] * memberLength, (ESS_PPVOID_T)&(ppMemComb[2]));
   if (status) 
      goto exit;
   pMemComb = ppMemComb[2];
   memset(pMemComb, 0, mbrsCount[2] * memberLength);
   strcpy((pMemComb)[0], "Mar");
   strcpy((pMemComb)[1], "Payroll");
   strcpy((pMemComb)[2], "300-10");
   strcpy((pMemComb)[3], "Texas");
   strcpy((pMemComb)[4], "Variance");

   /* Will hold inormation about how many LROs fetched for each Cell */
   status = EssAlloc(hInst, cellCount * sizeof(ESS_ULONG_T), (ESS_PPVOID_T)&pulLroCount);
   if (status) 
      goto exit;
   memset(pulLroCount, 0, cellCount * sizeof(ESS_ULONG_T));

   ppLroDescList = &pLroDescList;

   status = EssLROGetCatalogBatch(hCtx, mbrsCount, ppMemComb, cellCount, pulLroCount, ppLroDescList);
   if (status) 
      goto exit;


   for (k=0, offset=0; k<cellCount; k++)
   {
      ESS_LRODESC_API_T *pLroDesc = &pLroDescList[offset];
      for (i=0; i<pulLroCount[k]; i++, offset++)
      {
         printf("***** information for linked object ********\n");
         printf("Object type - %2d\n", (pLroDesc+i)->usObjType);
         printf("Link Id : \n");
         printf("   Object handle  -   %d \n", (pLroDesc+i)->linkId.hObject);
         printf("   Cell offset    -   %d \n", (pLroDesc+i)->linkId.cellKey.cellOffset);
         printf("   Block offset   -   %lf \n", (pLroDesc+i)->linkId.cellKey.blkOffset);
         printf("   Segment        -   %lf \n", (pLroDesc+i)->linkId.cellKey.segment);
         if ((pLroDesc+i)->usObjType > 0)
         {
            printf("Object name - %s\n",(pLroDesc+i)->lro.lroInfo.objName);
            printf("Object description - %s\n",(pLroDesc+i)->lro.lroInfo.objDesc);
         }
         else
         {
            printf("Cell notes - %s\n",(pLroDesc+i)->lro.note);
         }
         printf("User name - %s\n", (pLroDesc+i)->userName);
         printf("Security Access Level -  %d\n", (pLroDesc+i)->accessLevel);
         if ((pLroDesc+i)->pMemComb)
         {
            printf("Member Name : \n");
            pMember = (ESS_CHAR_T *) (pLroDesc+i)->pMemComb;
            for (j=0; j < (pLroDesc+i)->memCount; j++)
            {
               printf("      %s\n",pMember);
               pMember += memberLength;
            }
            EssFree(hInst, (pLroDesc+i)->pMemComb);
         }
         printf("\n");
      }   
   }
   printf("********* complete **********\n");
   
exit:
   if (status)
      printf("Fail Getting Catalog Information.\n");

   if (ppMemComb)
   {
      for(i=0; i<cellCount; i++) 
      {
         EssFree(hInst, ppMemComb[i]);
      }
      EssFree(hInst, ppMemComb);
   }

   if (pLroDescList)
      EssFree(hInst, pLroDescList);

   if (pulLroCount)
      EssFree(hInst, pulLroCount);

   return(status);

}