EssBuildDimXml

Performs outline editing using an XML file to make basic changes to the database outline. This XML outline editing method is a streamlined way to make basic outline edits without needing to use a rules file nor invoke the Outline API.

To use the XML outline editing feature, aggregate storage outlines that were created in an earlier release of Essbase must first be migrated to the current release. Once an aggregate storage outline is migrated, it cannot be edited in an earlier release client. Block storage outlines created in an earlier release of Essbase can use XML outline editing without needing to migrate the outline.

Syntax

ESS_FUNC_M EssBuildDimXml (hCtx, szXmlData, szErrorFile, ErrFileOverWrite);
ParameterData TypeDescription

hCtx

ESS_HCTX_T

API context handle.

szXmlData

ESS_POBJDEF_T

Pointer to XML object.

szErrorFile

ESS_STR_T

Name of error file to output on the client.

ErrFileOverWrite

ESS_BOOL_T

A Boolean value which determines whether this function overwrites an existing error file.

Notes

  • Before calling this function, you must create a valid restructuring XML document based on the XSD schema file, mbredit.xsd, located in essbase\bin. Essbase processes the XML document, based strictly on the schema, performing outline edits indicated in the XML document.

  • The XSD schema includes the following element names:

    Element NameDescription
    mbrUpdateSets member attribute information. Similar to EssOtlSetMemberInfo.
    mbrAddAdds a member to the outline. Similar to EssOtlAddMember.
    mbrDeleteRemoves a member from the outline. Similar to EssOtlDeleteMember.
    mbrRenameRenames a member. Similar to EssOtlRenameMember.

    Caution!

    If you use XML outline editing to rename a member, the cell data is not retained.

    mbrMoveMoves a member. Similar to EssOtlMoveMember.
    mbrAssocAssociates an attribute member with a standard or base member. Similar to EssOtlAssociateAttributeMember.
    dimAddAdds a dimension to the outline. Similar to EssOtlAddDimension.
    dimUpdateSets member attribute information. Similar to EssOtlSetMemberInfo.
  • In the XML document, to use some special characters in member names, you must replace them with character entity references.

    Desired Special CharacterCharacter Entity ReferenceExample
    & (ampersand)&&IM& produces &IM&
    < (less-than symbol)&lt;&lt;ST produces <ST
    > (greater-than symbol)&gt;OP&gt; produces OP>
    " (straight quotation mark)&quot;&quot;mbr1&quot; produces "mbr1"
    ' (apostrophe)&apos;CC&amp;R&apos;s produces CC&R's
  • In the XML document, the value you specify for the otlVersion element must be the correct revision number of the outline. You can use the revision number to keep track how many times you update the outline using the XML document. If you specify an incorrect revision number, the outline edit will abort, returning the correct revision number. Or, you can specify -1 as the value for otlVersion, which causes Essbase to ignore the revision number check and reset otlVersion to 0.

    For example:

    <otlEditMain xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns="mbredit"
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    otlVersion="-1">
    

Return Value

Returns a zero if successful.

Access

This function requires database design privilege ESS_PRIV_DBDESIGN for the specified database.

Example

C API Function Call Example

ESS_FUNC_M EssBuildDimXml (ESS_HCTX_T hCtx)
{
   ESS_FUNC_M sts = ESS_STS_NOERR;
   ESS_OBJDEF_T       xmlObj;
   memset(&xmlObj, '\0', sizeof(ESS_OBJDEF_T));
   xmlObj.hCtx = hCtx;
   xmlObj.ObjType = ESS_OBJTYPE_XML;
   xmlObj.AppName = "sample";
   xmlObj.DbName = "basic";
   xmlObj.FileName = "BuildDimSampleBasic";

   sts = EssBuildDimXml(hCtx,&xmlObj,"xmlbuild.err",ESS_TRUE);
   return sts;
}

XML Document Example

The XML object referenced in the function call must be a valid XML file, formed in congruence to the following example:

<?xml version="1.0" encoding="UTF-8"?>

<otlEditMain xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns="mbredit"
             xmlns:xs="http://www.w3.org/2001/XMLSchema"
		otlVersion="0">

<!-- Create new dimension Measures, update existing Year dimension -->
<!-- time and account type -->
<!-- two pass calc to true, formula and storage dynamic and label only -->
<!-- alias table long name to add new alias name -->
  
  <otlUpdate caseSensitive="true" enableMemberType="false">
		<impliedShareSetting> default </impliedShareSetting>
		<aliasTable>LongName</aliasTable>
		<aliasTable>aliastable3</aliasTable>
		<dtsMbr mbrName="Q-T-D" number="2" enable="true" /> 
	</otlUpdate>

<mbrDelete thisMbr="Qtr1"/>
<mbrDelete thisMbr="Qtr2"/>

<mbrDelete thisMbr="Measures"/>


   <mbrUpdate thisMbr="Year">
	<mbrInfo>
		<alias aliasTable="default" alias="Year"/>
		<alias aliasTable="LongName" alias="Year extension"/>
		<dataStorage>dynamic</dataStorage>
	</mbrInfo>
   </mbrUpdate>

	<mbrAdd mbrName="Qtr1" parent="Year" >
	</mbrAdd>

	<mbrUpdate thisMbr="Qtr1">
		<mbrInfo>
			<alias aliasTable="default" alias="Q1"/>
			<alias aliasTable="LongName" alias="Quarter1"/>
			<dataStorage>dynamic</dataStorage>
      			<consolidation>+</consolidation>
		</mbrInfo>
        </mbrUpdate>
	
	<mbrAdd mbrName="Jan" parent="Qtr1" />
	<mbrUpdate thisMbr="Jan">
		<mbrInfo>
			<dataStorage>storeData</dataStorage>
      			<consolidation>+</consolidation>
		</mbrInfo>
        </mbrUpdate>

	<mbrAdd mbrName="Feb" parent="Qtr1" preSibling="Jan" />
	<mbrUpdate thisMbr="Feb">
		<mbrInfo>
			<dataStorage>storeData</dataStorage>
      			<consolidation>+</consolidation>
		</mbrInfo>
        </mbrUpdate>


	<mbrAdd mbrName="Qtr2" parent="Year" preSibling="Qtr1"/>
	<mbrUpdate thisMbr="Qtr2">
		<mbrInfo>
			<alias aliasTable="default" alias="Q2"/>
			<alias aliasTable="LongName" alias="Quarter2"/>
			<dataStorage>dynamic</dataStorage>
      			<consolidation>+</consolidation>
		</mbrInfo>
        </mbrUpdate>

	<mbrAdd mbrName="Apr" parent="Qtr2" />
	<mbrUpdate thisMbr="Apr">
		<mbrInfo>
			<dataStorage>storeData</dataStorage>
      			<consolidation>+</consolidation>
		</mbrInfo>
        </mbrUpdate>

	<mbrAdd mbrName="May" parent="Qtr2" preSibling="Apr"/>
		<mbrUpdate thisMbr="May">
		<mbrInfo>
			<dataStorage>storeData</dataStorage>
      			<consolidation>+</consolidation>
		</mbrInfo>
        </mbrUpdate>


 <!-- End of Time dimension Update -->

  <dimAdd dimName="Measures" preSibling="Year" >
   <properties>
    	<category>account</category>
	<storage>dense</storage>
	<storageCategory>account</storageCategory>
    </properties>
   </dimAdd>

  <mbrUpdate thisMbr="Measures">
	<mbrInfo>
		<dataStorage>labelOnly</dataStorage>
	</mbrInfo>
  </mbrUpdate>

	<mbrAdd mbrName="Profit" parent="Measures" />
	<mbrUpdate thisMbr="Profit">
		<mbrInfo>
			<alias aliasTable="default" alias="Pf"/>
			<alias aliasTable="LongName" alias="Profitex"/>
			<dataStorage>dynamic</dataStorage>
      			<consolidation>+</consolidation>
		</mbrInfo>
        </mbrUpdate>

	<mbrAdd mbrName="Margin" parent="Profit" />
	<mbrUpdate thisMbr="Margin">
		<mbrInfo>
			<dataStorage>dynamic</dataStorage>
      			<consolidation>+</consolidation>
		</mbrInfo>
        </mbrUpdate>


	<mbrAdd mbrName="Sales" parent="Margin" />
	<mbrUpdate thisMbr="Sales">
		<mbrInfo>
			<dataStorage>storeData</dataStorage>
      			<consolidation>+</consolidation>
			<alias aliasTable="LongName" alias="Revenue"/>
		</mbrInfo>
        </mbrUpdate>

	<mbrAdd mbrName="COGS" parent="Margin" preSibling="Sales" />
	<mbrUpdate thisMbr="COGS">
		<mbrInfo>
			<dataStorage>storeData</dataStorage>
      			<consolidation>-</consolidation>
			<alias aliasTable="aliastable3" alias="Cost of Goods Sold"/>
		</mbrInfo>
        </mbrUpdate>

	<mbrAdd mbrName="Ratios" parent="Measures" preSibling="Margin" />
	<mbrUpdate thisMbr="Ratios">
		<mbrInfo>
			<dataStorage>labelOnly</dataStorage>
      			<consolidation>~</consolidation>
		</mbrInfo>
        </mbrUpdate>

	<mbrAdd mbrName="Margin %" parent="Ratios" />
	<mbrUpdate thisMbr="Margin %">
		<mbrInfo twoPassCalc="true" >
			<dataStorage>dynamic</dataStorage>
      			<consolidation>+</consolidation>
			<formula>Margin % Sales;</formula>
		</mbrInfo>
    </mbrUpdate>

	
	<mbrAdd mbrName="Profit %" parent="Ratios" preSibling="Margin %" />
	<mbrUpdate thisMbr="Profit %">
		<mbrInfo twoPassCalc="true" >
			<dataStorage>dynamic</dataStorage>
      			<consolidation>~</consolidation>
			<formula>Profit % Sales;</formula>
		</mbrInfo>
        </mbrUpdate>

	<mbrAdd mbrName="Profit per Ounce" parent="Ratios" preSibling="Profit %" />
	<mbrUpdate thisMbr="Profit per Ounce">
		<mbrInfo twoPassCalc="true" >
			<dataStorage>dynamic</dataStorage>
      			<consolidation>~</consolidation>
			<formula>Profit/@ATTRIBUTEVAL(@NAME(Ounces));</formula>
		</mbrInfo>
        </mbrUpdate>
	
</otlEditMain>