Desarrollo de funciones de cálculo definidas a medida

26 Desarrollo de funciones de cálculo definidas personalizadas

Para mejorar las funciones de cálculo disponibles para los cubos de almacenamiento de bloques de Essbase, puede utilizar Java para desarrollar sus propias funciones definidas personalizadas (CDF). Después de escribir las funciones, instale la clase Java y, a continuación, registre las funciones, ya sea globalmente con el servidor de Essbase o localmente en una aplicación.

Puede utilizar las funciones definidas personalizadas en los scripts de cálculo de Essbase.

Essbase no proporciona herramientas para crear clases y archivos Java; debe tener una versión soportada de JDK.

Para ver ejemplos de funciones definidas personalizadas, consulte Ejemplos de código Java.

Las funciones definidas personalizadas solo están disponibles para los cubos de almacenamiento de bloques (no relevantes para los cubos de almacenamiento agregado).

Para crear una función definida personalizada, utilice el siguiente flujo de trabajo.

Revise los requisitos para las funciones definidas personalizadas: Requisitos para la validez de las funciones definidas personalizadas
Escribir una clase Java pública que contenga al menos un método estático público que se utilizará como función definida personalizada: Crear y compilar una clase Java para funciones definidas personalizadas
Instalar la clase Java: Instalación de clases Java en el servidor Essbase
Registrar la función definida personalizada como una función local o global: Registrar funciones definidas personalizadas

Requisitos para la validez de funciones definidas a medida

Las funciones definidas personalizadas de Essbase se diseñan como métodos en una clase Java. Para las funciones globales, escriba métodos en una clase. Para las funciones de la aplicación, utilice clases y archivos jar independientes por aplicación. Pruebe las funciones localmente en una aplicación antes de registrarlas globalmente. Observe los tipos de dato, variables y convenciones de nomenclatura soportados.

Puede crear varios métodos en una clase para utilizarlos como una función definida personalizada. Normalmente, Oracle recomienda crear los métodos que tiene previsto utilizar en todas las aplicaciones de un servidor de Essbase como funciones definidas personalizadas en una sola clase. Sin embargo, si tiene previsto agregar funciones definidas personalizadas que se utilizarán en aplicaciones selectivas en el servidor de Essbase, cree estas funciones definidas personalizadas en una clase independiente y agréguelas a servidor de Essbase en un archivo .jar independiente.

Al crear varias clases Java que contienen métodos para su uso como funciones definidas personalizadas, compruebe que cada nombre de clase es único. Los nombres de clase duplicados hacen que los métodos de la clase duplicada no se reconozcan y no se pueden registrar como funciones definidas personalizadas.

Mediante programas de prueba en Java, pruebe las clases y los métodos Java. Cuando esté satisfecho con la salida de los métodos, instálelos en el servidor de Essbase y regístrelos en una única aplicación de prueba. No registre las funciones de forma global para las pruebas; al hacerlo, resulta más difícil actualizarlas si tiene problemas.

Los métodos de las funciones definidas personalizadas pueden tener cualquier combinación de los siguientes tipos de dato soportados como parámetros de entrada:

Booleano
byte
carácter
com.hyperion.essbase.calculator.CalcBoolean
flotador, doble
java.lang.String
corto, int, largo
matrices de cualquiera de estos tipos

CalcBoolean es un tipo de dato específico de Essbase que puede incluir tres valores: TRUE, FALSE y #MISSING. Para obtener información sobre los demás tipos de dato mostrados, consulte la documentación de JDK.

El tipo de dato de retorno del método puede ser nulo o cualquiera de los tipos de dato anteriores. Los tipos de dato devueltos se convierten a tipos de dato específicos de Essbase. Las cadenas se asignan a un tipo de cadena. Los valores booleanos se asignan al tipo de dato CalcBoolean. Todos los demás valores se asignan a un tipo doble.

Note:

Essbase no soporta variables dobles devueltas con valores infinitos o no numéricos. Si estos valores se devuelven desde un programa Java, es posible que no se registren ni se muestren correctamente en Essbase. Se deben comprobar las variables dobles para los valores infinitos o no numéricos y definirlas en valores finitos antes de volver a Essbase. Consulte la entrada de la clase Double en la documentación de JDK.

Para crear, suprimir y gestionar funciones definidas personalizadas, Essbase necesita los siguientes permisos de seguridad:

Funciones locales, de toda la aplicación y definidas de forma personalizada: Gestor de aplicaciones o superior
Funciones globales definidas por el servidor: administrador del sistema

Al registrar una función definida personalizada en Essbase, se asigna un nombre a la función, que se utiliza en scripts de cálculo y fórmulas y es distinta de la clase Java y el nombre de método utilizados por la función.

Siga estos requisitos para asignar nombres a funciones definidas personalizadas:

Inicie el nombre con el símbolo @. El resto de un nombre de función puede contener letras, números y los siguientes símbolos: @, #, $ y _. Los nombre de función no pueden contener espacios.

Por ejemplo: @MYFUNCTION
Inicie los nombres de las funciones definidas personalizadas a las que solo llaman las macros definidas personalizadas con "@_", para distinguirlas de las funciones y macros de uso general.

Por ejemplo: @_MYFUNCTION
Las funciones definidas personalizadas deben tener nombres únicos. Los nombres de funciones deben ser diferentes entre sí, de los nombres de macros definidas personalizadas y de los nombres de funciones de cálculo existentes.
Si una aplicación de Essbase contiene una función local que tiene el mismo nombre que una función global, la función local se utiliza para el cálculo.

Creación y compilación de una clase Java para funciones definidas personalizadas

Para crear y compilar una clase Java para funciones definidas personalizadas (CDF) de Essbase, escriba la clase mediante un editor de texto o un IDE (entorno de desarrollo integrado) y compílela mediante la herramienta javac.

A continuación se muestra un flujo de trabajo de ejemplo para crear una clase Java para un CDF:

En un editor de texto, cree una clase Java.

Por ejemplo:

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;
  }
}

Guarde el archivo con una extensión .java.
Por ejemplo:
```
CalcFunc.java
```
Navegue hasta el directorio donde reside el archivo .java; en un símbolo del sistema, introduzca este comando:
```
javac java_filename
```
Por ejemplo:
```
javac CalcFunc.java
```
Resuelva los errores de compilación hasta que el compilador cree un nuevo archivo con una extensión .class.
Por ejemplo:
```
CalcFunc.class
```

Instalación de clases Java en Essbase Server

Para instalar las clases Java para las funciones de cálculo definidas personalizadas (CDF) en el servidor de Essbase, compilarlas, copiar el archivo jar en un directorio udf global o de nivel de aplicación, como se especifica en estas instrucciones, y reiniciar la aplicación o el servidor.

Las clases Java se deben compilar en un archivo JAR mediante la herramienta jar de JDK.

Para crear un archivo .jar e instalarlo en un servidor de Essbase:

Navegue hasta el directorio donde reside el archivo .class; en un símbolo del sistema, introduzca este comando:
```
jar cf jar_filename class_filename
```
Por ejemplo:
```
jar cf CalcFunc.jar CalcFunc.class
```
En el servidor de Essbase, copie el archivo .jar en uno de los siguientes directorios (si el directorio no existe, créelo):
- Para los archivos .jar que contienen funciones definidas personalizadas globales:
  ESSBASEPATH/java/udf/
- Para que los archivos .jar se utilicen solo con aplicaciones específicas:
  <Application Directory>/app/appname/udf/
  donde appname es el nombre de la aplicación en la que se utilizará el CDF local.
Si no conoce la ubicación de ESSBASEPATH o <Application Directory>, consulte Variables de entorno en la plataforma Essbase.

Si el archivo .jar se coloca posteriormente en otra ubicación, debe modificar la variable CLASSPATH para incluir la ruta completa y el nombre de archivo para el archivo .jar.
Si las funciones solo las utilizarán aplicaciones específicas, reinicie esas aplicaciones. De lo contrario, reinicie Essbase Server. Consulte Inicio, Parada y Comprobación de Servidores para ver despliegues independientes o Uso de Comandos para Iniciar, Parar y Ver Estado de Procesos para ver el despliegue de pila en OCI.

Registrar funciones definidas personalizadas

Utilice MaxL para registrar las funciones definidas personalizadas (CDF) con Essbase. La tarea de registro se produce después de haber escrito los CDF en las clases Java, haber compilado las clases e instalado los archivos jar.

Después de haber compilado las clases Java para CDF en archivos .jar e instalado los archivos .jar en el servidor de Essbase, debe registrar las funciones para poder utilizarlas en scripts de cálculo y fórmulas. Consulte Requisitos para la validez de funciones definidas de forma personalizada.

Al registrar un CDF global, todas las aplicaciones de Essbase en el servidor de Essbase pueden utilizarlo. Pruebe las funciones en una sola aplicación (y regístrelas solo en esa aplicación) antes de hacerlas globales.

Utilice el mismo proceso para actualizar el catálogo de funciones que para actualizar el catálogo de macros. Consulte Refresh the Catalog of Custom-Defined Macros.

Atención:

No registre las funciones globales para las pruebas; hacerlo hace que cambiarlas sea más difícil si tiene problemas.

Para registrar un CDF, utilice la sentencia MaxL de la función de creación.

Para registrar un CDF con ámbito local, incluya el nombre de la aplicación como prefijo. Por ejemplo, la siguiente sentencia MaxL registra la función @JSUM en la clase CalcFunc como una función local para su uso en la aplicación de ejemplo:

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

Para registrar un CDF con ámbito global, no incluya el nombre de la aplicación como prefijo. Por ejemplo, la siguiente sentencia MaxL registra la función @JSUM en la clase CalcFunc como una función global para su uso en cualquier aplicación del servidor de Essbase:

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

Note:

La especificación de parámetros de entrada para el método Java es opcional. Si no especifica parámetros de entrada, Essbase los lee desde la definición del método en el código Java. Sin embargo, si está registrando varios CDF con el mismo nombre de método pero con diferentes juegos de parámetros, debe registrar cada versión de la función por separado, especificando los parámetros para cada versión de la función.

Implantación de Funciones Personalizadas Registradas Definidas

Puede utilizar funciones personalizadas registradas (CDF) en fórmulas y scripts de cálculo, de la misma forma que utiliza funciones de cálculo nativas de Essbase.

Para utilizar un CDF registrado:

Cree o abra un script o fórmula de cálculo existente.
- Si el CDF se registró localmente, dentro de una aplicación específica, debe usar un script de cálculo o una fórmula dentro de esa aplicación.
- Si el CDF se registró globalmente, puede utilizar cualquier script o fórmula de cálculo en el servidor de Essbase.
Agregue la función al script o la fórmula de cálculo.

Por ejemplo, para utilizar JSUM, utilice este script de cálculo:

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

Utilice este script de cálculo con la base de datos de ejemplo Sample.Basic o sustituya "New York" por el nombre de un miembro en una base de datos de prueba.
Guarde la secuencia de comandos o fórmula de cálculo y, a continuación, ejecución como de costumbre.

Actualización de funciones definidas personalizadas

Para actualizar una función definida personalizada (CDF) de Essbase, determinar si es de ámbito local o global, cerrar las aplicaciones afectadas, sustituir el archivo .jar que contiene el código de la función y volver a registrar la función.

El procedimiento para actualizar los CDF depende de estas condiciones:

Si la función está registrada localmente o globalmente.
Si la firma del CDF (nombre de clase, nombre de método o parámetros de entrada) se ha cambiado en el código Java.

Normalmente, para actualizar un CDF, debe reemplazar el archivo .jar que contiene el código para la función y, a continuación, volver a registrarlo. Sin embargo, si la firma del CDF no ha cambiado y solo tiene un juego de parámetros de entrada (no es un método sobrecargado), puede reemplazar el archivo .jar que contiene la función.

Note:

Solo los administradores deben actualizar los CDF globales.

Para actualizar un CDF:

Determine si la función es local o global.

Consulte Visualización de funciones definidas personalizadas.
Realice los cambios en la clase Java para CDF y utilice los programas de prueba Java para probar su salida.
Compile las clases Java y archívelas en un nuevo archivo .jar, utilizando el mismo nombre que el archivo .jar anterior.

Incluya otras clases y métodos para los CDF que se incluyeron en el archivo .jar anterior.
Realice una acción, en función de si está actualizando una función personalizada local o global:
1. Local: cierre cualquier aplicación de Essbase que utilice las funciones del archivo .jar.
2. Global: cierre todas las aplicaciones de Essbase
Si no está seguro de qué aplicaciones de Essbase utilizan qué funciones del archivo .jar, cierre todas las aplicaciones de Essbase.
Copie el nuevo archivo .jar en el servidor de Essbase y sustituya el archivo .jar existente por el mismo nombre.
Si la firma del CDF no ha cambiado, vaya al paso 8.

Para sustituir el CDF, utilice la sentencia crear o sustituir función MaxL. Por ejemplo:

Local:

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

Global:

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

Reinicie las aplicaciones que ha cerrado, lo que actualiza el catálogo.

Ver funciones definidas personalizadas

Vea una función definida personalizada (CDF) en Essbase para determinar si se ha registrado correctamente y si tiene un ámbito local o global. Los CDF no se muestran hasta que se hayan creado y registrado.

Para ver un CDF:

Utilice la instrucción MaxL de la función de visualización.

Por ejemplo, utilice la siguiente sentencia MaxL para ver los CDF en la aplicación de ejemplo y cualquier función global registrada:

display function Sample;

La sentencia display function muestra las funciones globales sin un nombre de aplicación para indicar que son globales. Si la aplicación contiene una función con el mismo nombre que una función global, solo se muestra la función local.

Eliminar funciones definidas personalizadas

Para eliminar o anular el registro de las funciones definidas personalizadas (CDF) de Essbase, primero asegúrese de que no estén en uso. A continuación, cierre las aplicaciones en las que están definidos los CDF, elimine los CDF emitiendo la sentencia Función de baja MaxL y reinicie las aplicaciones afectadas.

Los siguientes permisos son necesarios para eliminar un CDF:

Local: al menos permiso de Application Manager para la aplicación
Global: permiso de administrador del sistema

Antes de eliminar los CDF, debe verificar que no haya scripts de cálculo ni fórmulas que los utilicen. Los CDF globales se pueden utilizar en scripts de cálculo y fórmulas en el servidor de Essbase, por lo que debe verificar que no haya scripts de cálculo ni fórmulas en el servidor de Essbase que utilicen un CDF global antes de eliminarlo.

Atención:

Elimine los CDF globales solo cuando los usuarios no accedan a los cubos de Essbase y no se estén realizando rutinas de cálculo.

Para eliminar un CDF:

Determine si la función es local o global.

Consulte Visualización de funciones definidas personalizadas.
Realice una acción, dependiendo de si va a eliminar un CDF local o global:
1. Local: cierre cualquier aplicación de Essbase que utilice las funciones del archivo .jar.
2. Global: cierre todas las aplicaciones de Essbase.
Para eliminar el CDF, utilice la sentencia drop function MaxL. Por ejemplo:
- Local:
```
drop function Sample.'@JSUM';
```
- Global:
```
drop function '@JSUM';
```
Reinicie las aplicaciones que ha cerrado, lo que actualiza el catálogo.

Copiar funciones definidas personalizadas

Puede copiar funciones definidas personalizadas (CDF) en cualquier servidor de Essbase y aplicación a la que tenga el acceso adecuado.

Para copiar un CDF, utilice la sentencia crear o sustituir función como MaxL.

Consideraciones de Rendimiento para Funciones Personalizadas

Debido a que las funciones definidas personalizadas se implementan como una extensión del marco de la calculadora de Essbase, puede esperar que los CDF funcionen con menos eficacia que las funciones de cálculo nativas de Essbase.

Para optimizar el rendimiento, limite el uso de funciones definidas personalizadas a cálculos que no puede realizar con comandos y funciones de cálculo de Essbase nativos, especialmente en aplicaciones en las que la velocidad de cálculo es crítica.