Sviluppa funzioni di calcolo personalizzate

26 Sviluppo di funzioni di calcolo definite in modo personalizzato

Per migliorare le funzioni di calcolo disponibili per i cubi di memorizzazione a blocchi di Essbase, è possibile utilizzare Java per sviluppare le proprie funzioni (CDF, Custom-Defined Function). Dopo aver scritto le funzioni, installare la classe Java e quindi registrare le funzioni, a livello globale con il server Essbase o localmente in un'applicazione.

È possibile utilizzare le funzioni personalizzate negli script di calcolo di Essbase.

Essbase non fornisce strumenti per la creazione di classi e archivi Java. È necessario disporre di una versione supportata di JDK.

Per esempi di funzioni definite in modo personalizzato, vedere Esempi di codice Java.

Le funzioni definite in modo personalizzato sono disponibili solo per i cubi di memorizzazione a blocchi (non rilevanti per i cubi di memorizzazione di aggregazione).

Per creare una funzione definita in modo personalizzato, utilizzare il workflow riportato di seguito.

Esaminare i requisiti per le funzioni personalizzate: Requisiti per la validità delle funzioni definite in modo personalizzato
Scrivere una classe Java pubblica contenente almeno un metodo statico pubblico da utilizzare come funzione definita in modo personalizzato: Crea e compila una classe Java per funzioni definite in modo personalizzato
Installare la classe Java: Installazione di classi Java sul server Essbase
Registrare la funzione definita in modo personalizzato come funzione locale o globale: Registra funzioni definite in modo personalizzato

Requisiti per la validità delle funzioni definite in modo personalizzato

Le funzioni personalizzate di Essbase vengono progettate come metodi in una classe Java. Per le funzioni globali, scrivere i metodi in una classe. Per le funzioni dell'applicazione, utilizzare classi separate e file jar per applicazione. Eseguire il test delle funzioni localmente in un'applicazione prima di registrarle a livello globale. Prendere nota dei tipi di dati, delle variabili e delle convenzioni di denominazione supportati.

È possibile creare più metodi in una classe da utilizzare come funzione definita in modo personalizzato. In genere, Oracle consiglia di creare i metodi che si prevede di utilizzare in tutte le applicazioni di un server Essbase come funzioni definite in modo personalizzato in una singola classe. Se, tuttavia, si prevede di aggiungere funzioni definite in modo personalizzato che verranno utilizzate nelle applicazioni selettive sul server Essbase, creare queste funzioni definite in modo personalizzato in una classe separata e aggiungerle a server Essbase in un file .jar separato.

Quando si creano più classi Java contenenti metodi da utilizzare come funzioni definite in modo personalizzato, verificare che ogni nome di classe sia univoco. I nomi di classe duplicati impediscono il riconoscimento dei metodi nella classe duplicata e non è possibile registrare tali metodi come funzioni definite in modo personalizzato.

Utilizzando i programmi di test in Java, testare le classi e i metodi Java. Quando si è soddisfatti dell'output dei metodi, installarli in Server Essbase e registrarli in un'unica applicazione di test. Non registrare le funzioni a livello globale per i test; così facendo rende più difficile aggiornarle se si riscontrano problemi.

I metodi nelle funzioni definite in modo personalizzato possono avere qualsiasi combinazione dei seguenti tipi di dati supportati come parametri di input:

boolean
byte
char
com.hyperion.essbase.calculator.CalcBooleano
float, doppio
java.lang.String
corto, int, lungo
array di uno qualsiasi di questi tipi

CalcBoolean è un tipo di dati specifico di Essbase che può includere tre valori: TRUE, FALSE e #MISSING. Per informazioni sugli altri tipi di dati elencati, consultare la documentazione di JDK.

Il tipo di dati restituito dal metodo può essere nullo o uno qualsiasi dei tipi di dati precedenti. I tipi di dati restituiti vengono convertiti in tipi di dati specifici di Essbase. Le stringhe sono mappate a un tipo di stringa. I valori booleani vengono mappati al tipo di dati CalcBoolean. Tutti gli altri valori sono mappati a un tipo doppio.

Nota

Essbase non supporta le doppie variabili restituite con valori infiniti o non numerici. Se questi valori vengono restituiti da un programma Java, potrebbero non essere registrati o visualizzati correttamente in Essbase. Prima di tornare a Essbase, è necessario verificare la presenza di valori infiniti o non numerici nelle variabili doppie e impostarli su valori finiti. Vedere la voce relativa alla classe Doppio nella documentazione di JDK.

Per la creazione, l'eliminazione e la gestione di funzioni personalizzate, Essbase richiede le seguenti autorizzazioni di sicurezza:

Funzioni locali, a livello di applicazione e personalizzate: Application Manager o superiore
Funzioni globali, a livello di server e personalizzate: amministratore di sistema

Quando si registra una funzione definita in modo personalizzato in Essbase, si assegna alla funzione un nome, che viene utilizzato negli script di calcolo e nelle formule ed è distinto dalla classe e dal nome del metodo Java utilizzati dalla funzione.

Per denominare le funzioni definite in modo personalizzato, attenersi ai requisiti indicati di seguito.

Iniziare il nome con il simbolo @. Il resto di un nome di funzione può contenere lettere, numeri e i seguenti simboli: @, #, $ e _. I nominativi delle funzioni non possono contenere spazi.

Ad esempio: @MYFUNCTION
Avviare i nomi delle funzioni definite in modo personalizzato che vengono chiamate solo da macro definite in modo personalizzato con "@_", per distinguerle dalle funzioni e dalle macro di uso generale.

Ad esempio: @_MYFUNCTION
Le funzioni definite in modo personalizzato devono avere nomi univoci. I nomi delle funzioni devono essere diversi tra loro, dai nomi delle macro definite in modo personalizzato e dai nomi delle funzioni di calcolo esistenti.
Se un'applicazione Essbase contiene una funzione locale con lo stesso nome di una funzione globale, per il calcolo viene utilizzata la funzione locale.

Creazione e compilazione di una classe Java per funzioni definite in modo personalizzato

Per creare e compilare una classe Java per le funzioni CDF (Custom Defined Function) di Essbase, scrivere la classe utilizzando un editor di testo o un IDE (ambiente di sviluppo integrato) e compilarla utilizzando lo strumento javac.

Di seguito è riportato un workflow di esempio per la creazione di una classe Java per un CDF.

In un editor di testo, creare una classe Java.

Ad esempio:

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

Salvare il file con l'estensione .java.
Ad esempio:
```
CalcFunc.java
```
Passare alla directory in cui risiede il file .java; al prompt dei comandi, immettere il comando seguente:
```
javac java_filename
```
Ad esempio:
```
javac CalcFunc.java
```
Risolvere eventuali errori di compilazione finché il compilatore non crea un nuovo file con estensione .class.
Ad esempio:
```
CalcFunc.class
```

Installare le classi Java nel server Essbase

Per installare le classi Java per le funzioni di calcolo personalizzate (CDF) nel server Essbase, compilarle, copiare il file jar in una directory udf globale o a livello di applicazione, come specificato in queste istruzioni, quindi riavviare l'applicazione o il server.

Le classi Java devono essere compilate in un file JAR utilizzando lo strumento jar JDK.

Per creare un file .jar e installarlo in un server Essbase:

Passare alla directory in cui risiede il file .class; al prompt dei comandi, immettere il comando seguente:
```
jar cf jar_filename class_filename
```
Ad esempio:
```
jar cf CalcFunc.jar CalcFunc.class
```
Nel server Essbase copiare il file .jar in una delle seguenti directory (se la directory non esiste, crearla):
- Per i file .jar contenenti funzioni definite in modo personalizzato globali:
  ESSBASEPATH/java/udf/
- Per i file .jar da utilizzare solo con applicazioni specifiche:
  <Application Directory>/app/appname/udf/
  dove appname è il nome dell'applicazione in cui verrà utilizzato il CDF locale.
Se non si conosce la posizione di ESSBASEPATH o <Application Directory>, vedere Variabili di ambiente nella piattaforma Essbase.

Se successivamente il file .jar viene posizionato in un'altra posizione, è necessario modificare la variabile CLASSPATH per includere il percorso completo e il nome file per il file .jar.
Se le funzioni verranno utilizzate solo da applicazioni specifiche, riavviare tali applicazioni. In caso contrario, riavviare il server Essbase. Per informazioni sulle distribuzioni indipendenti, vedere Avvia, arresta e controlla server oppure Usa comandi per avviare, arrestare e visualizzare lo stato dei processi per la distribuzione dello stack su OCI.

Registra funzioni custom-defined

Utilizzare MaxL per registrare le funzioni customizzate (CDF) con Essbase. L'attività di registrazione viene dopo aver scritto i CDF all'interno delle classi Java, compilato le classi e installato i file jar.

Dopo aver compilato le classi Java per i CDF in file .jar e aver installato i file .jar in Server Essbase, è necessario registrare le funzioni prima di poterle utilizzare negli script di calcolo e nelle formule. Vedere Requisiti per la validità delle funzioni definite in modo personalizzato.

Quando si registra un CDF globale, tutte le applicazioni Essbase nel server Essbase possono utilizzarlo. Eseguire il test delle funzioni in un'unica applicazione (e registrarle solo in tale applicazione) prima di renderle globali.

Utilizzare lo stesso processo per l'aggiornamento del catalogo delle funzioni come per l'aggiornamento del catalogo delle macro. Vedere Aggiornamento del catalogo delle macro definite in modo personalizzato.

Attenzione

Non registrare le funzioni globali per i test; farlo rende più difficile cambiarle se si riscontrano problemi.

Per registrare un CDF, utilizzare l'istruzione MaxL create function.

Per registrare un CDF con ambito locale, includere il nome dell'applicazione come prefisso. Ad esempio, l'istruzione MaxL riportata di seguito registra la funzione @JSUM nella classe CalcFunc come funzione locale da utilizzare nell'applicazione Sample.

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

Per registrare un CDF con ambito globale, non includere il nome dell'applicazione come prefisso. Ad esempio, la seguente istruzione MaxL registra la funzione @JSUM nella classe CalcFunc come funzione globale da utilizzare in qualsiasi applicazione su Essbase Server:

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

Nota

La specifica dei parametri di input per il metodo Java è facoltativa. Se non si specificano parametri di input, Essbase li legge dalla definizione del metodo nel codice Java. Se, tuttavia, si stanno registrando più CDF con lo stesso nome di metodo ma con set di parametri diversi, è necessario registrare ogni versione della funzione separatamente, specificando i parametri per ogni versione della funzione.

Implementa funzioni personalizzate registrate

È possibile utilizzare le funzioni CDF registrate negli script di calcolo e nelle formule, nello stesso modo in cui si utilizzano le funzioni di calcolo native di Essbase.

Per utilizzare un CDF registrato:

Creare o aprire uno script o una formula di calcolo esistente.
- Se il CDF è stato registrato localmente, all'interno di un'applicazione specifica, è necessario utilizzare uno script di calcolo o una formula all'interno di tale applicazione.
- Se il CDF è stato registrato a livello globale, è possibile utilizzare qualsiasi script o formula di calcolo nel server Essbase.
Aggiungere la funzione allo script di calcolo o alla formula.

Ad esempio, per utilizzare JSUM, utilizzare questo script di calcolo:

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

Utilizzare questo script di calcolo con il database di esempio Sample.Basic oppure sostituire "New York" con il nome di un membro in un database di test.
Salvare lo script o la formula di calcolo, quindi eseguirla come al solito.

Aggiorna funzioni con definizioni customizzate

Per aggiornare una funzione CDF (Custom Defined Function) di Essbase, determinare se si tratta di un ambito locale o globale, chiudere le applicazioni interessate, sostituire il file .jar contenente il codice della funzione e registrare di nuovo la funzione.

La procedura di aggiornamento dei CDF dipende dalle condizioni riportate di seguito.

Indica se la funzione è registrata localmente o globalmente.
Se la firma del CDF, ovvero il nome della classe, il nome del metodo o i parametri di input, è stata modificata nel codice Java.

In genere, per aggiornare un CDF, è necessario sostituire il file .jar che contiene il codice della funzione, quindi registrarlo di nuovo. Se, tuttavia, la firma del CDF non è stata modificata e dispone di un solo set di parametri di input (non è un metodo sovraccarico), è possibile sostituire il file .jar che contiene la funzione.

Nota

Solo gli amministratori devono aggiornare i CDF globali.

Per aggiornare un CDF:

Determinare se la funzione è locale o globale.

Vedere Visualizza funzioni definite in modo personalizzato.
Apportare le modifiche alla classe Java per il CDF e utilizzare i programmi di test Java per eseguire il test dell'output.
Compilare le classi Java e archiviarle in un nuovo file .jar, utilizzando lo stesso nome del file .jar precedente.

Includere eventuali altre classi e metodi per i CDF inclusi nel file .jar precedente.
Eseguire un'azione, a seconda che si stia aggiornando una funzione personalizzata locale o globale.
1. Locale: chiudere tutte le applicazioni Essbase che utilizzano le funzioni nel file .jar.
2. Globale: Arresta tutte le applicazioni Essbase
Se non si è sicuri di quali applicazioni Essbase utilizzano le funzioni del file .jar, chiudere tutte le applicazioni Essbase.
Copiare il nuovo file .jar nel server Essbase, sostituendo il file .jar esistente con lo stesso nome.
Se la firma del CDF non è stata modificata, andare al passo 8.

Per sostituire il CDF, utilizzare l'istruzione create or replace function MaxL. Ad esempio:

Locale:

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

Globale:

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

Riavviare le applicazioni arrestate, che aggiornano il catalogo.

Visualizza funzioni customizzate

Visualizzare una funzione personalizzata (CDF) in Essbase per determinare se è stata registrata correttamente e se si tratta di un ambito locale o globale. I CDF vengono visualizzati solo dopo essere stati creati e registrati.

Per visualizzare un CDF:

Utilizzare l'istruzione display function MaxL.

Ad esempio, utilizzare la seguente istruzione MaxL per visualizzare i CDF nell'applicazione di esempio e le funzioni globali registrate:

display function Sample;

L'istruzione Funzione di visualizzazione elenca le funzioni globali senza un nome di applicazione per indicare che sono globali. Se l'applicazione contiene una funzione con lo stesso nome di una funzione globale, viene elencata solo la funzione locale.

Rimuovi funzioni custom-defined

Per rimuovere/annullare la registrazione delle funzioni CDF (Custom Defined Function) di Essbase, assicurarsi innanzitutto che non siano in uso. Quindi, arrestare l'applicazione o le applicazioni in cui sono definiti i CDF, rimuovere i CDF emettendo l'istruzione MaxL drop function e riavviare l'applicazione o le applicazioni interessate.

Per rimuovere un CDF sono necessarie le seguenti autorizzazioni:

Locale: almeno l'autorizzazione Application Manager per l'applicazione
Globale: autorizzazione amministratore di sistema

Prima di rimuovere i CDF, è necessario verificare che non vengano utilizzati script di calcolo o formule. I CDF globali possono essere utilizzati negli script di calcolo e nelle formule in server Essbase, pertanto è necessario verificare che nessun script di calcolo o formula in server Essbase utilizzi un CDF globale prima di rimuoverlo.

Attenzione

Rimuovere i CDF globali solo quando gli utenti non accedono ai cubi di Essbase e le routine di calcolo non vengono eseguite.

Per rimuovere un CDF:

Determinare se la funzione è locale o globale.

Vedere Visualizza funzioni definite in modo personalizzato.
Eseguire un'azione, a seconda che si stia rimuovendo un CDF locale o globale:
1. Locale: chiudere tutte le applicazioni Essbase che utilizzano le funzioni nel file .jar.
2. Globale: chiudere tutte le applicazioni Essbase.
Per rimuovere CDF, utilizzare l'istruzione drop function MaxL. Ad esempio:
- Locale:
```
drop function Sample.'@JSUM';
```
- Globale:
```
drop function '@JSUM';
```
Riavviare le applicazioni arrestate, che aggiornano il catalogo.

Copia funzioni custom-defined

È possibile copiare le funzioni definite in modo personalizzato (CDF) in qualsiasi server Essbase e applicazione a cui si dispone dell'accesso appropriato.

Per copiare un CDF, utilizzare la funzione di creazione o sostituzione come istruzione MaxL.

Considerazioni sulle prestazioni per funzioni definite in modo personalizzato

Poiché le funzioni definite in modo personalizzato vengono implementate come estensione del framework della calcolatrice Essbase, è possibile prevedere che i CDF funzionino in modo meno efficiente rispetto alle funzioni di calcolo Essbase native.

Per ottimizzare le prestazioni, limitare l'utilizzo di funzioni personalizzate ai calcoli che non è possibile eseguire con i comandi e le funzioni di calcolo nativi di Essbase, in particolare nelle applicazioni in cui la velocità di calcolo è fondamentale.