1/22/2017

DevelopingCustomDefinedCalculationFunctions

DevelopingCustomDefinedCalculationFunctions
InThisSection:
ProcessforCreatingCustomDefinedFunctions
CustomDefinedFunctionRequirements
CreatingandCompilingaJavaClass
InstallingJavaClassesonEssbaseServer
RegisteringCustomDefinedFunctions
UsingRegisteredCustomDefinedFunctions
UpdatingCustomDefinedFunctions
ViewingCustomDefinedFunctions
RemovingCustomDefinedFunctions
CopyingCustomDefinedFunctions
PerformanceConsiderationsforCustomDefinedFunctions
MemoryConsiderationsforCustomDefinedFunctions
Theinformationinthischapterappliesonlytoblockstoragedatabasesandisnotrelevantto
aggregatestoragedatabases.AlsoseeComparisonofAggregateandBlockStorage.

ProcessforCreatingCustomDefinedFunctions
ToenhancethecalculationfunctionsprovidedwithEssbase,youcancreatecustomdefinedfunctions
foruseincalculationscripts.Essbasedoesnotprovidesamplecustomdefinedfunctions.
CustomdefinedcalculationfunctionsarewritteninJava.Essbasedoesnotprovidetoolsforcreating
JavaclassesandarchivesyoumusthaveasupportedversionoftheJDK.SeetheOracleHyperion
EnterprisePerformanceManagementSystemCertificationMatrix
(http://www.oracle.com/technology/software/products/ias/files/fusion_certification.html).
Forexamplesofcustomdefinedfunctions,seetheOracleEssbaseTechnicalReference.
Tocreateacustomdefinedfunction:
1.Reviewtherequirementsforcustomdefinedfunctions.
SeeCustomDefinedFunctionRequirements.
2.WriteapublicJavaclassthatcontainsatleastonepublic,staticmethodtobeusedasa
customdefinedfunction.
SeeCreatingandCompilingaJavaClass.
3.InstalltheJavaclass.
SeeInstallingJavaClassesonEssbaseServer.
4.Registerthecustomdefinedfunctionasalocalorglobalfunction.
SeeRegisteringCustomDefinedFunctions.
http://docs.oracle.com/cd/E40248_01/epm.1112/essbase_db/frameset.htm?dcaudfs.html

1/9

1/22/2017

DevelopingCustomDefinedCalculationFunctions

CustomDefinedFunctionRequirements
Youcancreatemultiplemethodsinaclassforuseasacustomdefinedfunction.Typically,Oracle
recommendsthatyoucreatethemethodsthatyouplantouseacrossallapplicationsonanEssbase
Serverascustomdefinedfunctionsinasingleclass.If,however,youplantoaddcustomdefined
functionsthatwillbeusedinselectiveapplicationsontheEssbaseServer,createthesecustom
definedfunctionsinaseparateclassandaddthemtoEssbaseServerinaseparate.jarfile.
WhencreatingmultipleJavaclassesthatcontainmethodsforuseascustomdefinedfunctions,verify
thateachclassnameisunique.Duplicateclassnamescausemethodsintheduplicateclassnottobe
recognized,andyoucannotregisterthosemethodsascustomdefinedfunctions.
UsingtestprogramsinJava,testtheJavaclassesandmethods.Whenyouaresatisfiedwiththe
outputofthemethods,installthemonEssbaseServerandregistertheminasingletestapplication.
Donotregisterfunctionsgloballyfortestingdoingsomakesupdatingthemmoredifficultifyou
encounterproblems.
Methodsincustomdefinedfunctionscanhaveanycombinationofthefollowingsupporteddatatypes
asinputparameters:
boolean
byte
char
com.hyperion.essbase.calculator.CalcBoolean
float,double
java.lang.String
short,int,long
arraysofanyofthesetypes

CalcBooleanisanEssbasespecificdatatypethatcanincludethreevaluesTRUE,FALSE,and
#MISSING.Forinformationabouttheotherlisteddatatypes,seetheJDKdocumentation.
Themethodreturndatatypecanbevoidoranyoftheprecedingdatatypes.Returneddatatypesare
convertedtoEssbasespecificdatatypes.Stringsaremappedtoastringtype.Booleanvaluesare
mappedtotheCalcBooleandatatype.Allothervaluesaremappedtoadoubletype.
Note: EssbasedoesnotsupportdoublevariablesreturnedwithinfiniteorNotaNumbervalues.If
thesevaluesarereturnedfromaJavaprogram,theymaynotberecordedordisplayed
correctlyinEssbase.DoublevariablesshouldbecheckedforinfiniteorNotaNumbervalues
andsettofinitevaluesbeforebeingreturnedtoEssbase.Seetheentryfortheclass,
Double,intheJDKdocumentation.

Forcreating,deleting,andmanagingcustomdefinedfunctions,Essbaserequiresthesesecurity
permissions:
Local,applicationwide,customdefinedfunctions:ApplicationManagerorhigher
Global,serverwide,customdefinedfunctions:Administrator

WhenyouregisteracustomdefinedfunctioninEssbase,yougivethefunctionaname,whichisused
incalculationscriptsandformulasandisdistinctfromtheJavaclassandmethodnameusedbythe
function.
http://docs.oracle.com/cd/E40248_01/epm.1112/essbase_db/frameset.htm?dcaudfs.html

2/9

1/22/2017

DevelopingCustomDefinedCalculationFunctions

Followtheserequirementsfornamingcustomdefinedfunctions:
Startthenamewiththe@symbol.Therestofafunctionnamecancontainletters,numbers,
andthefollowingsymbols:@,#,$,and_.Functionnamescannotcontainspaces.
Forexample:@MYFUNCTION
Startthenamesofcustomdefinedfunctionsthatarecalledonlybycustomdefinedmacroswith
@_,todistinguishthemfromgeneralusefunctionsandmacros.
Forexample:@_MYFUNCTION
Customdefinedfunctionsmusthaveuniquenames.Functionnamesmustbedifferentfromeach
other,fromthenamesofcustomdefinedmacros,andfromthenamesofexistingcalculation
functions.
IfanEssbaseapplicationcontainsalocalfunctionthathasthesamenameasaglobalfunction,
thelocalfunctionisusedforcalculation.

CreatingandCompilingaJavaClass
TocreateandcompileaJavaclass,useatexteditorandtheJDKjavactool.
TocreateaJavaclassforacustomdefinedfunction:
1.Inatexteditor,createaJavaclass.
Forexample:
publicclassCalcFunc{
publicstaticdoublesum(double[]data){
inti,n=data.length
doublesum=0.0d
for(i=0i<ni++){
doubled=data[i]
sum=sum+d
}
returnsum
}
}
2.Savethefilewitha.javaextension.
Forexample:
CalcFunc.java
3.Navigatetothedirectorywherethe.javafileresidesatacommandprompt,enterthis
command:
javacjava_filename
Forexample:
javacCalcFunc.java
4.Resolveanycompilingerrorsuntilthecompilercreatesanewfilewitha.classextension.
Forexample:
http://docs.oracle.com/cd/E40248_01/epm.1112/essbase_db/frameset.htm?dcaudfs.html

3/9

1/22/2017

DevelopingCustomDefinedCalculationFunctions

CalcFunc.class

InstallingJavaClassesonEssbaseServer
JavaclassesmustbecompiledinaJARfile,usingtheJDKjartool.
Tocreatea.jarfileandinstallitonanEssbaseServer:
1.Navigatetothedirectorywherethe.classfileresidesatacommandprompt,enterthis
command:
jarcfjar_filenameclass_filename
Forexample:
jarcfCalcFunc.jarCalcFunc.class
2.OnthecomputerrunningEssbaseServer,copythe.jarfiletooneofthefollowingdirectories(if
thedirectorydoesnotexist,createit):
For.jarfilescontainingglobalcustomdefinedfunctions:
ARBORPATH/java/udf/
For.jarfilestobeusedonlywithspecificapplications:
ARBORPATH/app/appName/udf/
whereappNameisthenameoftheapplicationwherethelocalcustomdefinedfunctionwill
beused.

Ifthe.jarfileissubsequentlyplacedinanotherlocation,youmustmodifytheCLASSPATH
variabletoincludethefullpathandfilenameforthe.jarfile.
3.Ifthefunctionswillbeusedonlybyspecificapplications,restartthoseapplicationsinEssbase.
Otherwise,restartEssbaseServer.

RegisteringCustomDefinedFunctions
AfteryouhavecompiledtheJavaclassesforcustomdefinedfunctionsinto.jarfilesandinstalledthe
.jarfilesonEssbaseServer,youmustregisterthecustomdefinedfunctionsbeforeyoucanusethem
incalculationscriptsandformulas.SeeCustomDefinedFunctionRequirements.
Whenyouregisteraglobalcustomdefinedfunction,allEssbaseapplicationsontheEssbaseServer
canuseit.Testcustomdefinedfunctionsinasingleapplication(andregisterthemonlyinthat
application)beforemakingthemglobalfunctions.
Usethesameprocessforupdatingthecatalogoffunctionsasforupdatingthecatalogofmacros.See
RefreshingtheCatalogofCustomDefinedMacros.
Caution! Donotregisterglobalfunctionsfortestingdoingsomakeschangingthemmoredifficult
ifyouencounterproblems.

Toregisteracustomdefinedfunction,useatool:
http://docs.oracle.com/cd/E40248_01/epm.1112/essbase_db/frameset.htm?dcaudfs.html

4/9

1/22/2017

DevelopingCustomDefinedCalculationFunctions

Tool

Topic

Location

Administration
Services

CreatingCustomDefined
Functions

OracleEssbaseAdministrationServicesOnline
Help

MaxL

createfunction

OracleEssbaseTechnicalReference

Toregisteracustomdefinedfunctionwithlocalscope,includetheapplicationnameasaprefix.For
example,thefollowingMaxLstatementregistersthecustomdefinedfunction,@JSUM,intheCalcFunc
classasalocalfunctionforusewithintheSampleapplication:
createfunctionSample.'@JSUM'
as'CalcFunc.sum'
spec'@JSUM(memberRange)'
comment'addslistofinputmembers'
Toregisteracustomdefinedfunctionwithglobalscope,donotincludetheapplicationnameasa
prefix.Forexample,thefollowingMaxLstatementregistersthecustomdefinedfunction,@JSUM,in
theCalcFuncclassasaglobalfunctionforuseinanyapplicationonEssbaseServer:
createfunction'@JSUM'
as'CalcFunc.sum'
spec'@JSUM(memberRange)'
comment'addslistofinputmembers'
Note: SpecifyinginputparametersfortheJavamethodisoptional.Ifyoudonotspecifyinput
parameters,EssbasereadsthemfromthemethoddefinitionintheJavacode.If,however,
youareregisteringmultiplecustomdefinedfunctionswiththesamemethodnamebutwith
differentparametersets,youmustregistereachversionofthefunctionseparately,
specifyingtheparametersforeachversionofthefunction.

UsingRegisteredCustomDefinedFunctions
YoucanuseregisteredcustomdefinedfunctionslikenativeEssbasecalculationcommands.
Tousearegisteredcustomdefinedfunction:
1.Createoropenanexistingcalculationscriptorformula.
Ifthecustomdefinedfunctionwasregisteredlocallywithinaspecificapplicationyou
mustuseacalculationscriptorformulawithinthatapplication.
Ifthecustomdefinedfunctionwasregisteredglobally,youcanuseanycalculationscript
orformulaonEssbaseServer.
2.Addthecustomdefinedfunctiontothecalculationscriptorformula.
Forexample,touseJSUM,usethiscalculationscript:
"NewYork"=@JSUM(@LIST(2.3,4.5,6.6,1000.34))
UsethiscalculationscriptwiththeSample.Basicsampledatabase,orreplaceNewYorkwith
thenameofamemberinatestdatabase.
3.Savethecalculationscriptorformula,andthenrunitasusual.
http://docs.oracle.com/cd/E40248_01/epm.1112/essbase_db/frameset.htm?dcaudfs.html

5/9

1/22/2017

DevelopingCustomDefinedCalculationFunctions

UpdatingCustomDefinedFunctions
Theprocedureforupdatingcustomdefinedfunctionsdependsontheseconditions:
Whetherthefunctionisregisteredlocallyorglobally
Whetherthesignatureofthecustomdefinedfunctionclassname,methodname,orinput
parametershasbeenchangedintheJavacodeforthecustomdefinedfunction

Typically,toupdateacustomdefinedfunction,youmustreplacethe.jarfilethatcontainsthecode
forthefunction,andthenreregisterthefunction.If,however,thesignatureofthecustomdefined
functionhasnotchanged,andthefunctionhasonlyonesetofinputparameters(itisnotan
overloadedmethod),youcanreplacethe.jarfilethatcontainsthefunction.
Note: OnlyDBAsshouldupdateglobalcustomdefinedfunctions.

Toupdateacustomdefinedfunction:
1.Determinewhetherthefunctionislocalorglobal.
SeeViewingCustomDefinedFunctions.
2.MakethechangestotheJavaclassforthecustomdefinedfunctionanduseJavatestprograms
totestitsoutput.
3.CompiletheJavaclassesandarchivetheminanew.jarfile,usingthesamenameasthe
previous.jarfile.
Includeanyotherclassesandmethodsforcustomdefinedfunctionsthatwereincludedinthe
previous.jarfile.
4.Performanaction,dependingonwhetheryouareupdatingalocalorglobalcustomdefined
function:
a.Local:ShutdownanyEssbaseapplicationsthatusethefunctionsinthe.jarfile.
b.Global:ShutdownallEssbaseapplications
IfyouareunsurewhichEssbaseapplicationsusewhichfunctionsinthe.jarfile,shutdownall
Essbaseapplications.
5.Copythenew.jarfiletoEssbaseServer,replacingtheexisting.jarfilewiththesamename.
6.Ifthesignatureofthecustomdefinedfunctionhasnotchanged,skiptostep8.
7.Toreplacethecustomdefinedfunction,useatool:
AdministrationServices:SeeEditingCustomDefinedFunctionsintheOracleEssbase
AdministrationServicesOnlineHelp.
MaxL:Usethecreateorreplacefunctionstatement.Forexample:
Local:
createorreplacefunctionsample.'@JSUM'
as'CalcFunc.sum'
Global:

http://docs.oracle.com/cd/E40248_01/epm.1112/essbase_db/frameset.htm?dcaudfs.html

6/9

1/22/2017

DevelopingCustomDefinedCalculationFunctions

createorreplacefunction'@JSUM'
as'CalcFunc.sum'
8.Restarttheapplicationsthatyoushutdown,whichupdatesthecatalog.

ViewingCustomDefinedFunctions
Youcanviewcustomdefinedfunctionstodeterminewhetherafunctionhasbeenregistered
successfullyandwhetheritisregisteredlocallyorglobally.Customdefinedfunctionsarenotdisplayed
untiltheyhavebeencreatedandregistered.
Toviewacustomdefinedfunction,useatool:

Tool

Topic

Location

Administration
Services

ViewingCustomDefined
Functions

OracleEssbaseAdministrationServicesOnline
Help

MaxL

displayfunction

OracleEssbaseTechnicalReference

Forexample,usethefollowingMaxLstatementtoviewthecustomdefinedfunctionsintheSample
applicationandanyregisteredglobalfunctions:
displayfunctionSample
Thedisplayfunctionstatementlistsglobalfunctionswithoutanapplicationnametoindicatethat
theyareglobal.Iftheapplicationcontainsafunctionwiththesamenameasaglobalfunction,only
thelocalfunctionislisted.

RemovingCustomDefinedFunctions
Thefollowingpermissionsarerequiredtoremoveacustomdefinedfunction:
Local:ApplicationManagerpermissionfortheapplication,oranywiderpermission
Global:Administratorpermission

Beforeremovingcustomdefinedfunctions,youshouldverifythatnocalculationscriptsorformulasare
usingthem.Globalcustomdefinedfunctionscanbeusedincalculationscriptsandformulasacross
EssbaseServer,soyoumustverifythatnocalculationscriptsorformulasonEssbaseServerareusing
aglobalcustomdefinedfunctionbeforeremovingit.
Caution! RemoveglobalcustomdefinedfunctionsonlywhenusersarenotaccessingEssbase
databasesandcalculationroutinesarenotbeingperformed.

Toremoveacustomdefinedfunction:
1.Determinewhetherthefunctionislocalorglobal.
SeeViewingCustomDefinedFunctions.
http://docs.oracle.com/cd/E40248_01/epm.1112/essbase_db/frameset.htm?dcaudfs.html

7/9

1/22/2017

DevelopingCustomDefinedCalculationFunctions

2.Performanaction,dependingonwhetheryouareremovingalocalorglobalcustomdefined
function:
a.Local:ShutdownanyEssbaseapplicationsthatusethefunctionsinthe.jarfile.
b.Global:ShutdownallEssbaseapplications.
3.Toremovethecustomdefinedfunction,useatool:
AdministrationServices:SeeDeletingCustomDefinedFunctionsintheOracleEssbase
AdministrationServicesOnlineHelp
MaxL:UsethedropfunctionMaxLstatement.Forexample:
Local:
dropfunctionSample.'@JSUM'
Global:
dropfunction'@JSUM'
4.Restarttheapplicationsthatyoushutdown,whichupdatesthecatalog.

CopyingCustomDefinedFunctions
YoucancopycustomdefinedfunctionstoanyEssbaseServerandapplicationtowhichyouhave
appropriateaccess.
Tocopyacustomdefinedfunction,useatool:

Tool

Topic

Location

Administration
Services

CopyingCustomDefined
Functions

OracleEssbaseAdministrationServicesOnline
Help

MaxL

createfunction

OracleEssbaseTechnicalReference

PerformanceConsiderationsforCustomDefinedFunctions
BecausecustomdefinedfunctionsareimplementedasanextensionoftheEssbasecalculator
framework,youcanexpectcustomdefinedfunctionstooperatelessefficientlythanfunctionsnative
totheEssbasecalculatorframework.
Tooptimizeperformance,limittheuseofcustomdefinedfunctionstocalculationsthatyoucannot
performwithnativeEssbasecalculationcommands,particularlyinapplicationswherecalculationspeed
iscritical.

MemoryConsiderationsforCustomDefinedFunctions
UseoftheJVMAPIandJavaAPIforXMLParsinghasaninitialeffectonthememoryrequiredtorun
Essbase.Thememoryrequiredtoruntheseadditionalcomponentsisdocumentedinthememory
http://docs.oracle.com/cd/E40248_01/epm.1112/essbase_db/frameset.htm?dcaudfs.html

8/9

1/22/2017

DevelopingCustomDefinedCalculationFunctions

requirementsforEssbase.SeetheOracleEnterprisePerformanceManagementSystemInstallationand
ConfigurationGuide.
Beyondthesestartupmemoryrequirements,theJavaprogramsyoudevelopforcustomdefined
functionssometimesrequireadditionalmemory.Whenstarted,theJVMforWin32operatingsystems
immediatelyallocates2MBofmemoryforprograms.Thisallocationisincreasedaccordingtothe
requirementsoftheprogramsthatarethenrunbytheJVM.Thedefaultupperlimitofmemory
allocationfortheJVMonWin32operatingsystemsis64MB.IftheexecutionofaJavaprogram
exceedsthedefaultupperlimitofmemoryallocationfortheJVM,theJVMgeneratesanerror.Formore
informationaboutJVMmemorymanagementandmemoryallocationdetailsforotheroperating
systems,seeJDKdocumentation.
ConsideringthedefaultmemoryrequirementsoftheJVMandthelimitationsofthehardwareonwhich
yourunservers,carefullymonitoryouruseofmemory.Inparticular,developersofcustomdefined
functionsshouldbecarefulnottoexceedmemorylimitsoftheJVMwhencreatinglargeartifactswithin
customdefinedfunctions.

http://docs.oracle.com/cd/E40248_01/epm.1112/essbase_db/frameset.htm?dcaudfs.html

9/9