Développer des fonctions de calcul personnalisées

26 Développer des fonctions de calcul personnalisées

Pour améliorer les fonctions de calcul disponibles pour les cubes en mode "block storage" Essbase, vous pouvez utiliser Java pour développer vos propres fonctions personnalisées (CDF). Après avoir écrit les fonctions, installez la classe Java, puis enregistrez les fonctions, soit globalement auprès du serveur Essbase, soit localement auprès d'une application.

Vous pouvez utiliser vos fonctions personnalisées dans les scripts de calcul Essbase.

Essbase ne fournit pas d'outils pour la création de classes et d'archives Java. Vous devez disposer d'une version prise en charge du JDK.

Pour obtenir des exemples de fonctions personnalisées, reportez-vous à Exemples de code Java.

Les fonctions personnalisées définies sont disponibles uniquement pour les cubes en mode "block storage" (non pertinentes pour les cubes en mode "aggregate storage").

Pour créer une fonction personnalisée, utilisez le workflow suivant.

Examinez les exigences relatives aux fonctions personnalisées : Exigences de validité des fonctions personnalisées
Ecrire une classe Java publique qui contient au moins une méthode statique publique à utiliser en tant que fonction personnalisée : Create and Compile a Java Class for Custom Defined Functions
Installez la classe Java : Installation de classes Java sur le serveur Essbase
Enregistrez la fonction personnalisée en tant que fonction locale ou globale : Inscription de fonctions personnalisées

Exigences de validité des fonctions personnalisées

Vous concevez vos fonctions personnalisées Essbase en tant que méthodes dans une classe Java. Pour les fonctions globales, écrivez des méthodes dans une seule classe. Pour les fonctions d'application, utilisez des classes et des fichiers JAR distincts par application. Testez les fonctions localement sur une application avant de les enregistrer globalement. Notez les types de données, les variables et les conventions de dénomination pris en charge.

Vous pouvez créer plusieurs méthodes dans une classe pour les utiliser en tant que fonction personnalisée. En général, Oracle recommande de créer les méthodes que vous prévoyez d'utiliser dans toutes les applications d'un serveur Essbase en tant que fonctions personnalisées dans une seule classe. Toutefois, si vous prévoyez d'ajouter des fonctions personnalisées qui seront utilisées dans des applications sélectives sur le serveur Essbase, créez ces fonctions personnalisées dans une classe distincte et ajoutez-les au serveur Essbase dans un fichier .jar distinct.

Lorsque vous créez plusieurs classes Java qui contiennent des méthodes à utiliser en tant que fonctions personnalisées, vérifiez que chaque nom de classe est unique. Les noms de classe en double empêchent les méthodes de la classe en double d'être reconnues et vous ne pouvez pas les enregistrer en tant que fonctions personnalisées.

A l'aide de programmes de test dans Java, testez les classes et les méthodes Java. Lorsque vous êtes satisfait de la sortie des méthodes, installez-les sur le serveur Essbase et enregistrez-les dans une seule application de test. N'enregistrez pas les fonctions globalement à des fins de test, ce qui rend leur mise à jour plus difficile si vous rencontrez des problèmes.

Les méthodes des fonctions personnalisées peuvent comporter n'importe quelle combinaison des types de données pris en charge suivants en tant que paramètres d'entrée :

valeur booléenne
byte
char
com.hyperion.essbase.calculator.CalcBooléen
flotteur, double
java.lang.String
short, int, long
tableaux de l'un de ces types

CalcBoolean est un type de données spécifique à Essbase qui peut inclure trois valeurs : TRUE, FALSE et #MISSING. Pour plus d'informations sur les autres types de données répertoriés, reportez-vous à la documentation du kit JDK.

Le type de données renvoyé par la méthode peut être void ou l'un des types de données précédents. Les types de données renvoyés sont convertis en types de données propres à Essbase. Les chaînes sont mises en correspondance avec un type de chaîne. Les valeurs booléennes sont mises en correspondance avec le type de données CalcBoolean. Toutes les autres valeurs sont mises en correspondance avec un type double.

Remarques :

Essbase ne prend pas en charge les variables doubles renvoyées avec des valeurs infinies ou non numériques. Si ces valeurs sont renvoyées à partir d'un programme Java, elles peuvent ne pas être enregistrées ou affichées correctement dans Essbase. Les variables doubles doivent être vérifiées pour les valeurs infinies ou non numériques et définies sur des valeurs finies avant d'être renvoyées à Essbase. Reportez-vous à l'entrée correspondant à la classe Double dans la documentation JDK.

Pour la création, la suppression et la gestion de fonctions personnalisées, Essbase requiert les autorisations de sécurité suivantes :

Fonctions locales, à l'échelle de l'application et personnalisées : Application Manager ou supérieur
Fonctions globales, à l'échelle du serveur et personnalisées : Administrateur système

Lorsque vous enregistrez une fonction personnalisée dans Essbase, vous lui attribuez un nom, qui est utilisé dans les scripts de calcul et les formules et qui est distinct du nom de la classe et de la méthode Java utilisées par la fonction.

Pour nommer des fonctions personnalisées, procédez comme suit :

Commencez le nom par le symbole @. Le reste d'un nom de fonction peut contenir des lettres, des chiffres et les symboles suivants : @, #, $ et _. Le nom des fonctions ne peut pas contenir d'espaces.

Par exemple : @MYFUNCTION
Démarrez les noms des fonctions personnalisées qui sont appelées uniquement par des macros personnalisées avec "@_", pour les distinguer des fonctions et macros à usage général.

Par exemple : @_MYFUNCTION
Les fonctions personnalisées doivent avoir des noms uniques. Les noms de fonction doivent être différents les uns des autres, des noms des macros personnalisées et des noms des fonctions de calcul existantes.
Si une application Essbase contient une fonction locale portant le même nom qu'une fonction globale, la fonction locale est utilisée pour le calcul.

Création et compilation d'une classe Java pour des fonctions personnalisées

Pour créer et compiler une classe Java pour les fonctions personnalisées (CDF) Essbase, écrivez la classe à l'aide d'un éditeur de texte ou d'un IDE (environnement de développement intégré), puis compilez-la à l'aide de l'outil javac.

Voici un exemple de workflow pour la création d'une classe Java pour un CDF :

Dans un éditeur de texte, créez une classe Java.

Exemple :

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

Enregistrez le fichier avec l'extension .java.
Exemple :
```
CalcFunc.java
```
Accédez au répertoire dans lequel réside le fichier .java. A l'invite de commande, entrez la commande suivante :
```
javac java_filename
```
Exemple :
```
javac CalcFunc.java
```
Résolvez les erreurs de compilation jusqu'à ce que le compilateur crée un fichier avec l'extension .class.
Exemple :
```
CalcFunc.class
```

Installation de classes Java sur le serveur Essbase

Pour installer les classes Java de vos fonctions de calcul personnalisées sur le serveur Essbase, compilez-les, copiez le fichier JAR dans un répertoire udf global ou de niveau application comme indiqué dans ces instructions, puis redémarrez l'application ou le serveur.

Les classes Java doivent être compilées dans un fichier JAR à l'aide de l'outil JDK jar.

Pour créer un fichier .jar et l'installer sur un serveur Essbase, procédez comme suit :

Accédez au répertoire dans lequel réside le fichier .class. A l'invite de commande, entrez la commande suivante :
```
jar cf jar_filename class_filename
```
Exemple :
```
jar cf CalcFunc.jar CalcFunc.class
```
Sur le serveur Essbase, copiez le fichier .jar dans l'un des répertoires suivants (si le répertoire n'existe pas, créez-le) :
- Pour les fichiers .jar contenant des fonctions personnalisées globales :
  ESSBASEPATH/java/udf/
- Pour que les fichiers .jar soient utilisés uniquement avec des applications spécifiques :
  <Application Directory>/app/appname/udf/
  où appname est le nom de l'application dans laquelle le CDF local sera utilisé.
Si vous ne connaissez pas l'emplacement de ESSBASEPATH ou <Application Directory>, reportez-vous à Variables d'environnement dans la plate-forme Essbase.

Si le fichier .jar est ensuite placé à un autre emplacement, vous devez modifier la variable CLASSPATH afin d'inclure le chemin complet et le nom du fichier .jar.
Si les fonctions sont utilisées uniquement par des applications spécifiques, redémarrez ces applications. Sinon, redémarrez le serveur Essbase. Reportez-vous à Démarrage, arrêt et vérification des serveurs pour connaître les déploiements indépendants ou à Utilisation de commandes pour démarrer, arrêter et visualiser le statut des processus pour le déploiement de pile sur OCI.

Inscrire des fonctions personnalisées

Utilisez MaxL pour enregistrer vos fonctions personnalisées (CDF) dans Essbase. La tâche d'enregistrement intervient une fois que vous avez écrit les CDF dans les classes Java, compilé les classes et installé les fichiers JAR.

Après avoir compilé les classes Java pour les fichiers CDF dans des fichiers .jar et installé les fichiers .jar sur le serveur Essbase, vous devez enregistrer les fonctions avant de pouvoir les utiliser dans les scripts de calcul et les formules. Reportez-vous à Exigences de validité des fonctions personnalisées.

Lorsque vous enregistrez un fichier CDF global, toutes les applications Essbase sur le serveur Essbase peuvent l'utiliser. Testez les fonctions dans une seule application (et enregistrez-les uniquement dans cette application) avant de les rendre globales.

Utilisez le même processus pour mettre à jour le catalogue de fonctions que pour mettre à jour le catalogue de macros. Reportez-vous à Actualisation du catalogue de macros personnalisées.

Attention :

N'enregistrez pas les fonctions globales à des fins de test, ce qui rend leur modification plus difficile si vous rencontrez des problèmes.

Pour enregistrer un CDF, utilisez l'instruction create function MaxL.

Pour inscrire un CDF avec une portée locale, incluez le nom de l'application comme préfixe. Par exemple, l'instruction MaxL suivante enregistre la fonction @JSUM dans la classe CalcFunc en tant que fonction locale à utiliser dans l'application Sample :

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

Pour inscrire un CDF avec une portée globale, n'incluez pas le nom de l'application comme préfixe. Par exemple, l'instruction MaxL suivante enregistre la fonction @JSUM dans la classe CalcFunc en tant que fonction globale à utiliser dans n'importe quelle application sur le serveur Essbase :

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

Remarques :

La spécification des paramètres d'entrée pour la méthode Java est facultative. Si vous ne spécifiez pas de paramètres d'entrée, Essbase les lit à partir de la définition de la méthode dans le code Java. Toutefois, si vous enregistrez plusieurs CDF avec le même nom de méthode mais avec des jeux de paramètres différents, vous devez enregistrer chaque version de la fonction séparément, en spécifiant les paramètres pour chaque version de la fonction.

Implémenter des fonctions personnalisées enregistrées

Vous pouvez utiliser des fonctions personnalisées (CDF) enregistrées dans des scripts de calcul et des formules, de la même manière que les fonctions de calcul Essbase natives.

Pour utiliser un CDF enregistré :

Créez ou ouvrez un script ou une formule de calcul existant.
- Si le CDF a été enregistré localement (dans une application spécifique), vous devez utiliser un script de calcul ou une formule au sein de cette application.
- Si le CDF a été enregistré globalement, vous pouvez utiliser n'importe quel script ou formule de calcul sur le serveur Essbase.
Ajoutez la fonction au script de calcul ou à la formule.

Par exemple, pour utiliser JSUM, utilisez le script de calcul suivant :

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

Utilisez ce script de calcul avec l'exemple de base Sample.Basic ou remplacez "New York" par le nom d'un membre dans une base de données de test.
Enregistrez le script ou la formule de calcul, puis exécutez-le comme d'habitude.

Mettre à jour les fonctions personnalisées

Pour mettre à jour une fonction personnalisée (CDF) Essbase, déterminez s'il s'agit d'une portée locale ou globale, arrêtez les applications concernées, remplacez le fichier .jar qui contient le code de la fonction et réenregistrez la fonction.

La procédure de mise à jour des CDF dépend des conditions suivantes :

Indique si la fonction est enregistrée localement ou globalement.
Indique si la signature du CDF (nom de classe, nom de méthode ou paramètres d'entrée) a été modifiée dans le code Java.

En règle générale, pour mettre à jour un CDF, vous devez remplacer le fichier .jar qui contient le code de la fonction, puis le réenregistrer. Toutefois, si la signature du CDF n'a pas changé et qu'elle ne comporte qu'un seul ensemble de paramètres d'entrée (il ne s'agit pas d'une méthode surchargée), vous pouvez remplacer le fichier .jar qui contient la fonction.

Remarques :

Seuls les administrateurs doivent mettre à jour les CDF globaux.

Pour mettre à jour un CDF :

Déterminez si la fonction est locale ou globale.

Reportez-vous à Affichage des fonctions personnalisées.
Apportez les modifications à la classe Java pour CDF et utilisez des programmes de test Java pour tester sa sortie.
Compilez les classes Java et archivez-les dans un nouveau fichier .jar, en utilisant le même nom que le fichier .jar précédent.

Incluez toutes les autres classes et méthodes pour les CDF incluses dans le fichier .jar précédent.
Effectuez une action, selon que vous mettez à jour une fonction personnalisée locale ou globale :
1. Local : arrêtez toutes les applications Essbase qui utilisent les fonctions du fichier .jar.
2. Global : arrêter toutes les applications Essbase
Si vous ne savez pas quelles applications Essbase utilisent les fonctions du fichier .jar, arrêtez toutes les applications Essbase.
Copiez le nouveau fichier .jar vers le serveur Essbase, en remplaçant le fichier .jar existant par le même nom.
Si la signature du CDF n'a pas changé, passez à l'étape 8.

Pour remplacer le CDF, utilisez l'instruction Créer ou remplacer une fonction MaxL. Par exemple :

Local :

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

Global:

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

Redémarrez les applications que vous arrêtez et qui mettent à jour le catalogue.

Afficher les fonctions personnalisées

Affichez une fonction personnalisée (CDF) dans Essbase pour déterminer si elle a été enregistrée et si elle a une portée locale ou globale. Les CDF ne s'affichent pas tant qu'ils n'ont pas été créés et enregistrés.

Pour afficher un CDF :

Utilisez l'instruction MaxL de la fonction d'affichage.

Par exemple, utilisez l'instruction MaxL suivante pour afficher les CDF dans l'exemple d'application et toutes les fonctions globales inscrites :

display function Sample;

L'instruction display function répertorie les fonctions globales sans nom d'application pour indiquer qu'elles sont globales. Si l'application contient une fonction portant le même nom qu'une fonction globale, seule la fonction locale est répertoriée.

Enlever les fonctions personnalisées

Pour supprimer/annuler l'enregistrement des fonctions personnalisées (CDF) Essbase, assurez-vous d'abord qu'elles ne sont pas utilisées. Ensuite, arrêtez les applications dans lesquelles les CDF sont définis, supprimez les CDF en émettant l'instruction MaxL drop function, puis redémarrez les applications concernées.

Les droits d'accès suivants sont requis pour enlever un CDF :

Local : Au moins l'autorisation du gestionnaire d'applications pour l'application
Global : autorisation d'administrateur système

Avant de supprimer des CDF, vous devez vérifier qu'aucun script ou formule de calcul ne les utilise. Les CDF globaux peuvent être utilisés dans des scripts et des formules de calcul sur le serveur Essbase. Vous devez donc vérifier qu'aucun script ou formule de calcul sur le serveur Essbase n'utilise un CDF global avant de le supprimer.

Attention :

Enlevez les CDF globaux uniquement lorsque les utilisateurs n'accèdent pas aux cubes Essbase et que les routines de calcul ne sont pas exécutées.

Pour supprimer un CDF :

Déterminez si la fonction est locale ou globale.

Reportez-vous à Affichage des fonctions personnalisées.
Effectuez une action, selon que vous enlevez un CDF local ou global :
1. Local : arrêtez toutes les applications Essbase qui utilisent les fonctions du fichier .jar.
2. Global : arrêtez toutes les applications Essbase.
Pour enlever le CDF, utilisez l'instruction Fonction de suppression MaxL. Par exemple :
- Local :
```
drop function Sample.'@JSUM';
```
- Global:
```
drop function '@JSUM';
```
Redémarrez les applications que vous arrêtez et qui mettent à jour le catalogue.

Copier des fonctions personnalisées

Vous pouvez copier des fonctions personnalisées (CDF) vers n'importe quel serveur Essbase et n'importe quelle application à laquelle vous disposez des droits d'accès appropriés.

Pour copier un CDF, utilisez l'instruction create or replace function as MaxL.

Remarques concernant les performances des fonctions personnalisées

Les fonctions personnalisées étant implémentées en tant qu'extension de la structure de calculatrice Essbase, vous pouvez vous attendre à ce que les CDF fonctionnent moins efficacement que les fonctions de calcul Essbase natives.

Pour optimiser les performances, limitez l'utilisation de fonctions personnalisées aux calculs que vous ne pouvez pas effectuer avec les commandes et les fonctions de calcul Essbase natives, en particulier dans les applications où la vitesse de calcul est critique.