# EssLROAddObject

Description

EssLROAddObject() links reporting objects to a data cell in an Essbase database.

Syntax

    ESS_FUNC_M EssLROAddObject (hCtx, memCount, pMemComb, usOption,
    pLRODesc);

ESS_HCTX_T | hCtx
ESS_ULONG_T | memCount
ESS_PMBRNAME_T | pMemComb
ESS_USHORT_T | usOption
ESS_PLRODESC_API_T | pLRODesc

Parameters

hCtx | Essbase API context handle.
memCount | The number of members specified in pMemComb.
pMemComb | Array of the member names that define the data cell to be linked.
usOption | Option specifying where to store the object. Use one of these values: ESS_STORE_OBJECT_API to store an object on the server. ESS_NOSTORE_OBJECT_API to not store the object on a server.
pLRODesc | Pointer to object's description structure, ESS_LRODESC_API_T.

Return Value

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

Notes

- The linked object can be any of the following types:
  - A flat file, such as a Word document, Excel spreadsheet, or bitmap image.
  - A cell note containing up to 599 characters of text.
  - A link to a URL.
  - A link to another Essbase database (a linked partitions feature).
- If you elect not to store the object on the server (usOption), your application is responsible for all file management tasks for the object (that is, because the object is not being stored with the Essbase database, some other program must take responsibility for it).
- The usOption parameter is ignored for cell notes, which are always stored on the server.
- The usOption parameter for a URL linked object should always be ESS_NOSTORE_OBJECT_API.
- EssLROAddObject uses the currently logged in user name as the "created by" user name for the object and ignores any user name specified in the pLRODesc object description structure.

Access

A call to this function requires write privileges (ESS_PRIV_WRITE) to the active database.

Example

    ESS_STS_T  ESS_LROAddObject (ESS_HCTX_T hCtx, ESS_HINST_T hInst)
    {
    	ESS_STS_T			sts = ESS_STS_NOERR;
    	ESS_PMBRNAME_T	pMemComb = NULL;
    	ESS_LRODESC_API_T	lroDesc;
    	ESS_USHORT_T		usOption = 0;
    	ESS_ULONG_T		memCount;

    	memset (&lroDesc, 0 , sizeof(ESS_LRODESC_API_T));

    	lroDesc.usObjType = 0;    /* Creating a cell note */
    	strcpy(lroDesc.lro.note, "The profit for Colas in the East based on actuals");
    	usOption = ESS_NOSTORE_OBJECT_API;
    	strcpy(lroDesc.userName, "user1");
    	memCount = 5;

    	sts = EssAlloc(hInst, memCount*sizeof(ESS_MBRNAME_T),
    					(ESS_PPVOID_T)&pMemComb);
    	if (sts)
    	{
    		printf("could not allocate memory\n");
    		return sts;
    	}

    	memset(pMemComb, 0, memCount*sizeof(ESS_MBRNAME_T));
    	strcpy( pMemComb[0], "Profit");
    	strcpy( pMemComb[1], "East");
    	strcpy( pMemComb[2], "Actual");
    	strcpy( pMemComb[3], "Colas");
    	strcpy( pMemComb[4], "Year");

    	sts = EssLROAddObject( hCtx, memCount, pMemComb, usOption, &lroDesc);

    	if (sts)
    	{
    		printf( "Could not attach LRO\n");
    	}
    	EssFree(hInst, pMemComb);
    	return sts;
    }

See Also

LRO Constant and Structure Definitions
EssLROGetObject()
EssLROUpdateObject()
EssLRODeleteObject()