You design your Essbase custom-defined functions as methods in a Java class. For global functions, write methods in one class. For application functions, use separate classes and jar files per application. Test functions locally to one application before registering them globally. Note the supported data types, variables, and naming conventions.

To create and compile a Java class for Essbase custom defined functions (CDFs), write the class using a text editor or IDE (integrated development environment), and compile it using the javac tool.

1. In a text editor, create a Java class.

   For example:

   public class CalcFunc {
     public static double sum (double[] data) {
       int i, n = data.length;
       double sum = 0.0d;
       for (i=0; i<n; i++) {
         double d = data [i];
         sum = sum + d;
       }
       return sum;
     }
   }
   

2. Save the file with a .java extension.

   For example:

   CalcFunc.java

3. Navigate to the directory where the .java file resides; at a command prompt, enter this command:

   javac java_filename

   For example:

   javac CalcFunc.java

4. Resolve any compiling errors until the compiler creates a new file with a .class extension.

   For example:

   CalcFunc.class

To install the Java classes for your custom defined calculation functions (CDFs) onto the Essbase Server, compile them, copy the jar file to a global or application level udf directory as specified in these instructions, and restart the application or server.

1. Navigate to the directory where the .class file resides; at a command prompt, enter this command:

   jar cf jar_filename class_filename

   For example:

   jar cf CalcFunc.jar CalcFunc.class

2. On the Essbase Server, copy the .jar file to one of the following directories (if the directory does not exist, create it):

   • For .jar files containing global custom-defined functions:

     ESSBASEPATH/java/udf/

   • For .jar files to be used only with specific applications:

     <Application Directory>/app/appname/udf/

     where appname is the name of the application where the local CDF will be used.

   If you do not know the location of ESSBASEPATH or <Application Directory>, see Environment Variables in the Essbase Platform.

   If the .jar file is subsequently placed in another location, you must modify the CLASSPATH variable to include the full path and filename for the .jar file.

3. If the functions will be used only by specific applications, restart those applications. Otherwise, restart Essbase Server. See Start, Stop, and Check Servers for independent deployments, or Use Commands to Start, Stop, and View Status of Processes for stack deployment on OCI.

Use MaxL to register your custom defined functions (CDFs) with Essbase. The registration task comes after you have written the CDFs within Java classes, compiled the classes, and installed the jar files.

create function Sample.'@JSUM'
as 'CalcFunc.sum'
spec '@JSUM(memberRange)'
comment 'adds list of input members';

create function '@JSUM'
as 'CalcFunc.sum'
spec '@JSUM(memberRange)'
comment 'adds list of input members';

You can use registered custom-defined functions (CDFs) in calculation scripts and formulas, the same way you use native Essbase calculation functions.

1. Create or open an existing calculation script or formula.

   • If the CDF was registered locally—within a specific application—you must use a calculation script or formula within that application.

   • If the CDF was registered globally, you can use any calculation script or formula on Essbase Server.

2. Add the function to the calculation script or formula.

   For example, to use JSUM, use this calculation script:

   "New York" = @JSUM(@LIST(2.3, 4.5, 6.6, 1000.34));

   Use this calculation script with the Sample.Basic sample database, or replace "New York" with the name of a member in a test database.

3. Save the calculation script or formula, and then run it as usual.

To update an Essbase custom defined function (CDF), determine if it is local or global in scope, shut down the impacted application(s), replace the .jar file that contains the code for the function, and re-register the function.

1. Determine whether the function is local or global.

   See View Custom-Defined Functions.

2. Make the changes to the Java class for the CDF and use Java test programs to test its output.
3. Compile the Java classes and archive them in a new .jar file, using the same name as the previous .jar file.

   Include any other classes and methods for CDFs that were included in the previous .jar file.

4. Perform an action, depending on whether you are updating a local or global custom-defined function:
   1. Local: Shut down any Essbase applications that use the functions in the .jar file.
   2. Global: Shut down all Essbase applications

   If you are unsure which Essbase applications use which functions in the .jar file, shut down all Essbase applications.

5. Copy the new .jar file to Essbase Server, replacing the existing .jar file with the same name.
6. If the signature of the CDF has not changed, skip to step 8.
7. To replace the CDF, use the create or replace function MaxL statement. For example:

   • Local:

     create or replace function sample.'@JSUM'
     as 'CalcFunc.sum';

   • Global:

     create or replace function '@JSUM'
     as 'CalcFunc.sum';

8. Restart the applications that you shut down, which updates the catalog.

View a custom-defined function (CDF) in Essbase to determine whether it has been registered successfully and whether it is local or global in scope. CDFs are not displayed until they have been created and registered.

display function Sample;

To remove/unregister Essbase custom defined functions (CDFs), first be sure that they are not in use. Then, shut down the application(s) in which the CDFs are defined, remove the CDFs by issuing the MaxL drop function statement, and restart the affected application(s).

1. Determine whether the function is local or global.

   See View Custom-Defined Functions.

2. Perform an action, depending on whether you are removing a local or global CDF:
   1. Local: Shut down any Essbase applications that use the functions in the .jar file.
   2. Global: Shut down all Essbase applications.
3. To remove the CDF, use the drop function MaxL statement. For example:

   • Local:

     drop function Sample.'@JSUM';

   • Global:

     drop function '@JSUM';

4. Restart the applications that you shut down, which updates the catalog.

You can copy custom-defined functions (CDFs) to any Essbase Server and application to which you have appropriate access.

Because custom-defined functions are implemented as an extension of the Essbase calculator framework, you can expect CDFs to operate less efficiently than native Essbase calc functions.