MaxL et ESSCMD, les langages d'administration d'Essbase

| Antoine Dinimant | Fleur-Anne.Blain |

Ce tutOriel présente les deux langages d'administration d'Oracle/Hyperion Essbase, ESSCMD et MaxL. Bien qu'assez limités, ces langages de script sont la base de toute automatisation des cubes Essbase.

Cet article s'adresse à tout essbasien qui a un minimum de connaissance du fonctionnement de l'outil, et donc un peu de pratique de l'une des consoles d'administration (Application Manager en version 6, EAS console en versions 7 et 9). Si vous êtes débutant complet avec les scripts d'administration, cette introduction vous sera des plus utiles ; si vous en êtes un vieux routier, vous trouverez sans doute quelques éléments à glaner, en particulier dans les deux chapitres consacrés à l'angoissante question « où sont mes fichiers ? » Si vous n'avez pas besoin du vieil ESSCMD et que MaxL vous suffit, n'hésitez pas à passer directement à cette partie.

Enfin, si vous souhaitez discuter un point ou un autre soulevé par cet article, vous trouverez un lien vers le sujet ad hoc du forum.

Bonne lecture !

Commentez

- Titre : MaxL et ESSCMD, les langages d'administration d'Essbase

- Auteurs : Antoine Dinimant, Fleur-Anne.Blain

- Parution : 21 avril 2009

- Mise à jour : 16 avril 2012

- Licence : Copyright ® 2009-2012 Antoine Dinimant. Aucune reproduction, même partielle, ne peut être faite de ce site et de l'ensemble de son contenu : textes, documents, images, etc. sans l'autorisation expresse de l'auteur. Sinon vous encourez selon la loi jusqu'à trois ans de prison et jusqu'à 300 000 € de dommages et intérêts.

Sommaire

- 1. Présentation : les différents langages d'Essbase

- 2. ESSCMD

- 2-A. Présentation du langage

- 2-A-1. Principes de la syntaxe

- 2-A-2. Modes de fonctionnement

- 2-A-3. Exécuter un script ESSCMD

- 2-B. Utilisation de scripts ESSCMD

- 2-B-1. Premier exemple

- 2-B-2. Gestion des erreurs

- 2-B-3. Logs et valeur de retour

- 2-B-4. Où sont mes fichiers ?

- 2-B-5. Rédaction à la volée des scripts ESSCMD

- 2-C. Intérêt et limites d'ESSCMD

- 3. MaxL

- 3-A. Présentation du langage

- 3-A-1. Principes de la syntaxe

- 3-A-2. MaxL et MDX

- 3-A-3. Modes de fonctionnement

- 3-A-4. Les commandes MaxL de la console EAS

- 3-A-5. Exécuter un script MaxL

- 3-B. Utilisation de scripts MaxL

- 3-B-1. Premier exemple

- 3-B-2. Les commandes du client Essmsh

- 3-B-3. Gestion des erreurs

- 3-B-4. Logs et valeur de retour

- 3-B-5. Où sont mes fichiers ?

- 3-B-6. Variables

- 3-B-7. Commandes supplémentaires par rapport à ESSCMD

- 3-C. MaxL et les triggers

- 3-C-1. Création de triggers en MaxL

- 3-C-2. Administrer les triggers

- 3-C-3. Fichiers de spool

- 3-C-4. Envoi de mail

- 4. Quelques trucs à connaître

- 4-A. Chargement d'information et codes d'erreurs

- 4-B. Optimiser un chargement d'outline

- 4-B-1. ESSCMD et l'incremental dimension building

- 4-B-2. MaxL et le chargement multiple

- 4-C. Emplacement des fichiers de données et rapidité d'exécution

- 4-D. Limites sur la consultation des utilisateurs, des groupes et des privilèges

- 5. Conclusion

- 6. Annexes

- 6-A. Versions utilisées

- 6-B. Quelques lectures

- 6-C. Remerciements

- 6-D. Pour discuter

1 - Présentation : les différents langages d'Essbase

Contrairement aux bases relationnelles, qui disposent avec le SQL d'un langage à tout faire, Essbase utilise différents langages propres aux diverses tâches :

- calculs dans la base : langage des scripts de calcul ;

- extractions : Report Writer Commands, MDX ;

- chargements : règles de chargement (fichiers binaires) ;

- administration : ESSCMD, MaxL.

Les langages d'administration ont pour rôle de scripter les actions de la console d'administration. Les modules gouvernés par leur propre éditeur étant exclus, il s'agit essentiellement de lancer certaines actions, mais pas de créer ou de modifier directement des objets Essbase (outlines, calc scripts, report scripts, DLR).

Tous deux sont des langages très simples, dépourvus de structures de contrôle (pas de boucles, pas de IF). Ils sont généralement pilotés par des scripts de l'OS et/ou rédigés dynamiquement par un L4G (VB, Java, Perl, etc.) ou un outil externe (Excel par exemple). On se concentrera ici sur les modes d'utilisation de ces deux langages, en s'appuyant sur les cas les plus courants, les chargements et exports de données ; la documentation officielle de ces deux langages se trouve dans la Technical Reference, ainsi que la liste intégrale des commandes disponibles.

Pourquoi deux langages ? Le premier, ESSCMD, est assez rudimentaire et surtout peu lisible ; le second langage, MaxL a été créé pour répondre aux défauts d'ESSCMD et le remplacer. ESSCMD et MaxL ont donc le même rôle et couvrent à peu près les mêmes fonctionnalités ; toutefois, MaxL est paramétrable et offre quelques nouvelles instructions. Pour analyser un système existant, il est souvent nécessaire de connaître ESSCMD ; pour en développer un nouveau, on se tournera plutôt vers MaxL. Si vous êtes dans ce dernier cas, n'hésitez pas à sauter directement en .

2 - ESSCMD

2-A - Présentation du langage

2-A-1 - Principes de la syntaxe

Chaque commande ESSCMD est constituée d'un seul mot, insensible à la casse, suivi d'une série d'arguments numériques ou textuels séparés par un ou plusieurs espaces (ou autres "caractères blancs"). La plupart des commandes s'appliquent au cube courant choisi lors de la connexion ou par l'instruction SELECT.

2-A-2 - Modes de fonctionnement

ESSCMD est transmis au serveur par la console ESSCMD.exe, soit en mode interactif (l'utilisateur tape les commandes à l'écran), soit en mode batch (le client exécute les instructions contenues dans un fichier).

Le client ESSCMD.exe se trouve dans le dossier %Hyperion_HOME%\products\Essbase\EssbaseClient\bin, comme l'Add-in Excel.

Selon l'environnement, il arrive que les variables système ne soient pas lues correctement par ESSCMD ; vous pouvez le démarrer en utilisant le batch startEsscmd.cmd, qui renseigne les variables nécessaires avant de lancer ESSCMD.

Le mode batch impose des contraintes supplémentaires, facultatives en mode interactif :

- les commandes doivent se terminer par un point-virgule (son absence peut entraîner des erreurs d'interprétation pour les instructions à arguments facultatifs) ;

- tout ce qui est à droite du point-virgule sur la même ligne est ignoré, on ne peut donc y mettre que des commentaires, mais pas de seconde instruction ;

- les arguments textuels doivent être systématiquement écrits entre guillemets.

Dans la console ESSCMD, appuyer sur la touche Echap permet d'interrompre l'opération en cours (calcul, restructuration, etc.).

Comme il n'y a pas de système d'échappement des guillemets, cela interdit de faire référence à des noms de membres qui auraient besoin d'être écrits entre guillemets (présence d'espaces ou de caractères spéciaux, ou encore noms entièrement numériques).

2-A-3 - Exécuter un script ESSCMD

Il suffit d'appeler le client ESSCMD.exe en lui passant le nom du script en argument. Les scripts ESSCMD portent classiquement l'extension .scr, mais ce n'est pas une obligation technique.

Appel d'un script ESSCMD par le shell de l'OS

Esscmd c:\test\helloworld.scr

ESSCMD.exe n'accepte pas d'autre argument.

2-B - Utilisation de scripts ESSCMD

2-B-1 - Premier exemple

Le script suivant met en place un scénario classique de chargement de données mensuel : il se connecte au cube Demo.Basic, charge le fichier data_feb situé sur le cube, crée ou modifie la variable de substitution curmonth", exécute le script de calcul newmonth et exporte les résultats.

premier exemple de script ESSCMD

LOGIN "serveur" "admin" "password" ;
SELECT "demo" "basic" ;
LOADDATA 2 "data_feb" ;
CREATEVARIABLE "curmonth" "serveur" "demo" "basic" "FEB" ;
RUNCALC 2 "newmonth" ;
RUNREPT 2 "expmonth" "c:/FEB.txt" ;
LOGOUT ;

Cet exemple est assez représentatif du style très concis mais assez cryptique d'ESSCMD. Ainsi, le "2" dans LOADDATA, RUNCALC et RUNREPT indique que le fichier désigné juste ensuite se trouve sur le serveur. De même, les cinq arguments du CREATEVARIABLE désignent, dans l'ordre, la variable de substitution, le serveur, l'application, le cube (database), et la valeur que doit prendre la variable. Comme vous pouvez l'imaginer, il est indispensable d'avoir la Tech Ref sous les yeux pour lire ou rédiger un script ESSCMD.

En ESSCMD, les chemins de fichier s'écrivent avec des slashes (/), quel que soit le système d'exploitation.

2-B-2 - Gestion des erreurs

Dans le script précédent, si jamais le chargement de données échoue, le calcul et l'export de données sont néanmoins effectués. Dans la plupart des cas, on souhaite plutôt un arrêt du script. C'est ce que permet l'instruction IFERROR, qui renvoie à une étiquette prédéfinie :

Exemple avec gestion d'erreur

LOGIN "serveur" "admin" "password" ;
SELECT "demo" "basic" ;
LOADDATA 2 "data_feb" ;
IFERROR horsdici ;
CREATEVARIABLE "curmonth" "localhost" "demo" "basic" "FEB" ;
RUNCALC 2 "newmonth" ;
IFERROR horsdici ;
RUNREPT 2 "expmonth" "c:/FEB.txt" ;
IFERROR horsdici ;
LOGOUT ;
:horsdici ;

Il n'est pas impossible de développer des procédures de reprise sur erreur plus évoluées qu'une simple sortie du code. Toutefois, les possibilités offertes par le langage restent rudimentaires (IFERROR et GOTO).

2-B-3 - Logs et valeur de retour

La commande OUTPUT permet de créer un fichier de log, contenant, selon l'option choisie, l'intégralité de la session ou les seules erreurs survenues. Ce fichier de log est systématiquement situé côté client (voir plus loin, ).

À la fin de l'exécution du script, le statut renvoyé par la dernière commande (le numéro d'erreur Essbase en cas de problème, 0 si tout s'est bien passé) est transmis au système d'exploitation. Sous Windows par exemple, il alimente la variable d'environnement %ERRORLEVEL%.

Dans le script précédent, l'étiquette horsdici est placée après l'instruction LOGOUT afin de permettre une récupération du code d'erreur. En effet, si LOGOUT était la dernière instruction exécutée, elle renverrait un 0 (la déconnexion s'est bien passée) au lieu de l'erreur qui a déclenché le IFERROR. Dans tous les cas, le LOGOUT est facultatif en mode batch, car le client se déconnecte automatiquement en fin de script.

2-B-4 - Où sont mes fichiers ?

L'une des principales utilisations des langages d'administration consiste à gérer les imports et exports de fichiers de données ou métadonnées ; en mode batch, on va également devoir produire et trouver des fichiers de log. Or, l'emplacement de ces divers fichiers n'est pas simple à comprendre, même avec la Tech Ref sous les yeux... tentons donc d'éclaircir le système.

À travers les diverses commandes et syntaxes, on retrouve quatre emplacements principaux. Trois d'entre eux sont relatifs à la variable d'environnement HYPERION_HOME, mise en place sur l'OS par l'installation du serveur ou du client Essbase (par exemple, sous Windows, cela peut être C:\HYPERION). Les chemins présentés ci-dessous le sont en syntaxe Windows, mais sont aisément transposables à Unix/Linux ou à un autre système.

Sur le serveur :

- le dossier APP, c'est-à-dire %HYPERION_HOME%\products\Essbase\EssbaseServer\APP (utilisé en écriture) ;

- le dossier du cube courant, donc APP\appli\cube (utilisé en lecture).

Sur le client :

- le dossier de travail du client ESSCMD (le dossier courant de la session shell d'où ESSCMD.exe est appelé) ;

- le miroir sur le client du dossier du cube courant, donc le APP\appli\cube du client ; la plupart du temps, ce dossier n'existe pas et doit être créé.

Les chemins par défaut indiqués ici sont ceux d'Essbase 11.1.1.3 ; ils peuvent varier selon la version. La variable HYPERION_HOME n'existant pas dans les versions trop anciennes, on pourra alors utiliser son ancêtre, ARBORPATH.

À partir de là, deux cas se présentent.

Les fichiers dont l'emplacement est précisé par un code numérique :

- 1 = dossier cube du client (permet d'utiliser des report scripts ou des règles de chargement locaux ;

- 2 = dossier cube du serveur ;

- 3 = dossier courant du client, adresse relative à ce dossier, ou encore adresse absolue sur le client ;

- 4 = table SQL.

Dans les deux premiers cas, notez bien que les fichiers doivent être précisément dans le dossier désigné, ni en amont ni en aval. Seule l'option 3 permet une adresse complète.

Les fichiers produits dont on ne précise pas l'emplacement :

- OUTPUT et erreurs de chargement : dossier courant du client ;

- fichier produit par un ordre RUNREPT : dossier courant du client ;

- fichier produit par un ordre EXPORT : dossier APP du serveur.

Si l'on reprend le RUNREPT de l'exemple de code utilisé :

RUNREPT 2 "expmonth" "c:/FEB.txt" ;

On comprend maintenant que le rapport utilisé est le fichier expmonth.rep dans le dossier cube du serveur, tandis que les données exportées vont partir dans un fichier c:\FEB.txt du client. Notez qu'on n'indique pas l'extension quand le fichier correspond à un type d'objet Essbase évident dans le contexte (on omet donc le .RUL dans un chargement, le .CSC dans un calcul et le .REP dans une extraction).

Ce système est relativement complexe et contraignant ; MaxL viendra simplifier certains éléments... tout en introduisant de nouvelles complexités !

2-B-5 - Rédaction à la volée des scripts ESSCMD

Du fait de l'absence de variable, il est souvent nécessaire de faire rédiger à la volée les scripts ESSCMD par un langage externe, et de le faire rédiger intégralement, car il est impossible d'imbriquer les scripts. Si l'on souhaite par exemple utiliser sous Windows les variables d'environnement %COMPTE%, %MDP% et %MOIS% (positionnées au niveau de l'OS) dans le script précédent, cela donnera ce script DOS (fichier .bat) :

Exemple de rédaction à la volée par un script DOS

echo LOGIN "serveur" "%COMPTE%" "%MDP%" ;>script.scr
echo SELECT "demo" "basic" ;>>script.scr
echo LOADDATA 2 "data_%MOIS%" ;>>script.scr
echo IFERROR horsdici ;>>script.scr
echo CREATEVARIABLE "curmonth" "localhost" "demo" "basic" "%MOIS%" ;>>script.scr
echo RUNCALC 2 "newmonth" ;>>script.scr
echo IFERROR horsdici ;>>script.scr
echo RUNREPT 2 "expmonth" "c:/%MOIS%.txt" ;>>script.scr
echo IFERROR horsdici ;>>script.scr
echo LOGOUT ;>>script.scr
echo :horsdici ;>>script.scr
call esscmd.exe script.scr

Cette imbrication extrême entre script externe et script ESSCMD n'est évidemment pas pour simplifier le débogage...

2-C - Intérêt et limites d'ESSCMD

Non paramétrable, doté d'une gestion d'erreur minimaliste, ESSCMD n'est plus maintenu que pour assurer la compatibilité ascendante. Toutefois, il présente deux avantages marginaux par rapport à MaxL :

- le feedback renvoyé par le processus de calcul apparaît au fur et à mesure sur le shell au lieu d'être envoyé en fin de calcul comme sous MaxL ; dans certains cas de débogage ou d'optimisation, il peut être plus simple de lancer les calculs par ESSCMD que de fouiller dans les logs ;

- il est possible de détourner l'instruction ENDINCBUILDDIM pour copier des outlines d'un cube à l'autre, ce qui est normalement interdit ().

Utilitaire de conversion : le client Essbase est livré avec l'utilitaire CMD2MXL.exe, qui réécrit un script ESSCMD en MaxL. La documentation de cet utilitaire dans la Technical Reference présente la correspondance entre les instructions des deux langages.

3 - MaxL

MaxL vient remédier à deux défauts d'ESSCMD : il est beaucoup plus lisible et peut recevoir des paramètres externes, utilisés ensuite comme variables.

3-A - Présentation du langage

3-A-1 - Principes de la syntaxe

Les commandes MaxL se veulent proches de phrases à l'impératif ; elles commencent toutes par l'un des dix verbes existant, suivi d'un complément d'objet (create application, alter system, drop database, display user, etc.). Chaque commande se termine par un point-virgule.

Les règles de syntaxe globales sont les suivantes :

- il n'y a pas de cube courant ; au contraire, l'application ou le cube auquel s'applique l'instruction doit être précisé à chaque fois ;

- les objets Essbase sont désignés par une syntaxe à point, par exemple :

execute calculation sample.basic.aggreg ;

- les arguments textuels susceptibles de contenir des points ou des espaces doivent être écrits entre apostrophes (single quotes), par exemple :

alter user 'ted.codd' add to group GR_ADMINS ;

- MaxL accepte les commentaires, écrits entre /* et */ ;

- les chemins de fichiers s'écrivent entre apostrophes, les séparateurs de dossiers étant indifféremment des slashes /, des backslashes \ ou des doubles backslashes \\, quel que soit l'OS.

export database sample.basic data to data_file 'D:\\fileout.txt' ;

Comme \ et \\ sont équivalents, la syntaxe \\serveur\dossier doit être saisie comme \\\\serveur\\dossier ou \\\serveur\dossier.

3-A-2 - MaxL et MDX

La Tech Ref présente MaxL comme étant "MaxL DDL", et MDX comme sa contrepartie DML. Ces termes renvoient au SQL, qui se compose d'une série de sous-langages spécialisés, dont le DML (data manipulation language, chargé notamment des requêtes d'extraction et des calculs) et le DDL (data definition language, chargé de définir les objets de la base).

Cette présentation, qui sous-entend que MDX serait une sorte de MaxL DML, fait l'impasse sur le fait que MDX (aujourd'hui un standard implémenté par toutes les solutions OLAP) est un langage développé par Microsoft et non par Hyperion ou Oracle, qu'Essbase est probablement le dernier outil multidimensionnel à l'adopter, et que les syntaxes des deux langages n'ont pas grand-chose en commun !

Reste néanmoins le fait qu'Hyperion a souhaité un certain rapprochement entre les deux langages : ainsi, la console MaxL (Essmsh.exe) accepte les requêtes MDX ; la console EAS juxtapose un éditeur MDX et un éditeur MaxL quasiment identiques, et la création des triggers se fait dans un MaxL qui encapsule du MDX.

3-A-3 - Modes de fonctionnement

Le premier mode de fonctionnement de MaxL consiste à utiliser la console Essmsh.exe, soit en mode interactif (l'utilisateur tape les commandes à l'écran), soit en mode batch (le client exécute les instructions contenues dans un fichier). Il n'y a pas de différence de syntaxe significative entre les deux modes.

Le client Essmsh.exe se trouve dans le dossier %Hyperion_HOME%\products\Essbase\EssbaseClient\bin, comme l'Add-in Excel ou la console ESSCMD.

Selon l'environnement, il arrive, comme avec ESSCMD, que les variables système ne soient pas lues correctement par Essmsh ; vous pouvez le démarrer en utilisant le batch startMaxl.cmd, qui renseigne les variables nécessaires avant de lancer Essmsh.

Dans la console MaxL, appuyer sur la touche Echap permet d'interrompre l'opération en cours (calcul, restructuration, etc.).

La console EAS comprend également un éditeur MaxL, que vous pouvez lancer avec File / Editors / MaxL Script Editor. Cet éditeur est très proche de l'éditeur MDX ; il propose une coloration syntaxique minimale, ainsi qu'un gestionnaire de variables, et permet d'enregistrer les scripts en local ou sur le serveur EAS.

L'éditeur permet ainsi de rédiger et de tester en mode interactif des scripts qui seront ensuite exécutés en mode batch par la console Essmsh.exe.

Un troisième mode de fonctionnement consiste à utiliser une API, notamment le module Perl permettant de passer des commandes MaxL au serveur Essbase. Ce mode de fonctionnement ne sera pas présenté, mais il est décrit en détail dans la Tech Ref (section MaxL Perl Module du chapitre MaxL ; la mise en place de l'API Perl est décrite dans le fichier readme du dossier perlmod installé avec le serveur Essbase).

3-A-4 - Les commandes MaxL de la console EAS

La console EAS communique avec Essbase en utilisant MaxL. Elle vous permet de les voir ; pour cela, allez dans Tools / Console options, choisissez l'onglet Essbase et cochez Show MaxL statements in the message panel :

Un onglet MaxL Statements apparaît maintenant dans le panneau de messages, qui vous permet de retrouver vos actions exprimées en MaxL :

3-A-5 - Exécuter un script MaxL

Il suffit d'appeler le client Essmsh.exe en lui passant le nom du script en argument. Les scripts MaxL portent classiquement l'extension .msh ou .mxl, mais ce n'est pas une obligation technique.

Appel d'un script MaxL par le shell de l'OS

Essmsh c:\test\helloworld.msh

Essmsh admet d'autres arguments, comme des arguments transmis au script MaxL (voir plus bas), ou encore des options introduites par un tiret :

Appel de la console MaxL avec connexion initiale

Essmsh c:\test\helloworld.msh -l admin password -s serveur

La syntaxe complète s'obtient avec l'option -h :

Appel de l'aide d'Essmsh

E:\HYPERION\Products\ESSBASE\EssbaseServer\bin>Essmsh -h
essmsh(1)

NAME
essmsh -- MaxL Shell

SYNOPSIS
essmsh [-hlsmup] [-a | -i | file] [arguments...]
[...]

3-B - Utilisation de scripts MaxL

3-B-1 - Premier exemple

Le script suivant est l'équivalent de l'exemple vu en ESSCMD (connexion, importation d'un fichier free-form, mise à jour d'une variable de substitution, calcul et export) :

Premier exemple de script MaxL

login admin password on serveur ;
import database demo.basic data from server text data_file 'data_feb.txt' on error abort ;
alter database demo.basic set variable curmonth FEB ;
execute calculation demo.basic.newmonth ;
export database demo.basic using server report_file expmonth to data_file 'c:/FEB.txt' ;
logout ;

Après la sécheresse d'ESSCMD, MaxL peut apparaître comme exagérément verbeux...

3-B-2 - Les commandes du client Essmsh

Le client comprend quelques commandes qui ne font pas partie du langage MaxL lui-même. Cette nuance entre commandes MaxL et commandes du client a trois conséquences :

- ces commandes sont documentées au chapitre MaxL Shell > Commands de la Technical Reference, et non parmi les MaxL Statements;

- elles ne sont pas utilisables si vous passez par un autre canal que le client (par exemple, si vous utilisez le perlmod) ;

- les règles d'interpolation des variables ne sont pas exactement les mêmes, ce qui cause de subtiles différences syntaxiques sur l'écriture des noms de fichier.

Les plus intéressantes sont :

- spool;

- iferror;

- goto;

- define label (définit une étiquette de branchement utilisée par iferror et goto) ;

- msh (exécute un script MaxL imbriqué) ;

- shell (exécute une commande de l'OS) ;

- set display column width (fixe la largeur des colonnes de sortie d'un display) ;

- set timestamp on (horodate les commandes) ;

La plupart des commandes du client Essmsh sont utilisables avec l'éditeur MaxL de la console EAS.

3-B-3 - Gestion des erreurs

La gestion des erreurs est exactement la même qu'avec ESSCMD. Notez que l'instruction iferror fait partie des commandes d'Essmsh et non du langage MaxL.

Exemple avec gestion d'erreur

login admin password on serveur ;
iferror 'horsdici' ;
import database demo.basic data from server text data_file 'data.txt' on error abort ;
iferror 'horsdici' ;
alter database demo.basic set variable curmonth FEB ;
iferror 'horsdici' ;
execute calculation demo.basic.newmonth ;
iferror 'horsdici' ;
export database demo.basic using server report_file expmonth to data_file 'c:/FEB.txt' ;
iferror 'horsdici' ;
define label 'horsdici' ;
logout ;

Contrairement à ESSCMD, le client Essmsh ne se déconnecte pas automatiquement en fin de script. Cela permet donc d'enchaîner ou d'imbriquer les scripts (avec la commande msh).
En corollaire, le logout n'écrase pas le statut d'erreur éventuellement obtenu, ce qui permet de placer l'étiquette avant lui.

3-B-4 - Logs et valeur de retour

Les logs sont créés par spool, qui est une commande du client Essmsh.exe. La valeur de retour d'un script est déterminée de la même manière qu'avec ESSCMD : la dernière instruction du script transmet son code de retour à l'OS.

Syntaxiquement, il est possible de séparer le spool stdout (log normal) du spool stderr (log d'erreur), ou même de ne faire que l'un des deux. Cette option est hélas peu commode, car les messages d'erreur se trouvent alors séparés des instructions qui les ont provoqués... La pratique courante est donc d'utiliser le spool indifférencié, et de rechercher le mot-clef ERROR (et, si nécessaire, WARNING) dans les fichiers de logs.

Faire figurer le login et le mot de passe en clair dans un script est un problème de sécurité, qui peut être réglé (ou du moins déplacé) en les passant systématiquement en variables. Cela n'évitera néanmoins pas que les logins et mots de passe apparaissent en clair dans les logs. MaxL prévoit une série d'options pour les crypter (à ce sujet, voir la Tech Ref, MaxL Shell > Invocation > Encryption), ainsi que l'article de Sébastien Roux.

3-B-5 - Où sont mes fichiers ?

On a vu qu'ESSCMD n'était pas d'une clarté limpide quant à l'emplacement des divers fichiers lus ou produits. Avec des principes syntaxiques relativement différents, MaxL clarifie certains points tout en introduisant de nouvelles interrogations... Si l'étrange notion de "dossier cube miroir sur le client" a disparu, on retrouve les autres emplacements principaux.

Sur le serveur :

- le dossier APP (utilisé en écriture) ;

- le dossier du cube courant, donc APP\appli\cube (utilisé en lecture).

Sur le client :

- le dossier de travail du client Essmsh.exe (le dossier courant de la session shell d'où Essmsh.exe est invoqué).

Ces trois emplacements ne sont pas exclusifs, mais ils servent de points de repère. En fait, il ne faut pas moins de six règles, présentées ici de la plus générale à la plus spécifique, pour savoir exprimer les emplacements que vous souhaitez, et savoir s'ils sont utilisables ou non (certaines combinaisons étant impossibles) :

1. de manière générale, les mots-clefs local et server vous permettent de préciser de quel côté se situent les fichiers concernés ; hélas, ces mots-clés ne sont pas systématiquement permis dans toutes les syntaxes ;

2. côté client, MaxL permet d'utiliser indifféremment un nom de fichier simple (qui sera alors dans le dossier courant), une adresse relative (qui sera donc située par rapport au même dossier courant), ou une adresse absolue ;

3. les fichiers de spool et d'erreurs au chargement sont toujours côté client (dans le le dossier courant du client pour un nom de fichier simple, par rapport à lui pour une adresse relative, ou encore sur une adresse absolue) ;

4. l'import (import... data) utilise indifféremment des fichiers de données et de règle (.rul) situés d'un côté ou de l'autre ; toutefois, sur le serveur, les adresses absolues ne fonctionnent pas ; les adresses relatives sont situées par rapport au dossier du cube ; les noms de fichiers simples peuvent être indiqués avec ou sans l'extension (.txt pour les données et .rep pour les rapports) ;

5. l'export sans rapport (export... data) produit toujours son fichier de résultats sur le serveur ; ce fichier de résultats peut être indiqué comme un nom de fichier simple ou une adresse relative (situé dans le dossier APP ou par rapport à lui), ou comme une adresse absolue ;

6. l'export avec rapport (export... using) produit, lui, ses fichiers sur le client, avec là encore les trois possibilités : nom de fichier simple, adresse relative (dans le dossier courant ou par rapport à lui) ou adresse absolue ; le fichier de rapport peut être local ou sur le serveur (dans ce dernier cas, il doit obligatoirement être situé sur le cube et indiqué comme un simple nom, sans l'extension .rep)

Si les premières règles sont relativement simples, les possibilités limitées par les dernières sont vite surprenantes, notamment la différence de comportement entre les deux versions de la même instruction export. Les habitués d'ESSCMD y retrouveront la différence entre l'EXPORT et le RUNREPT.

La Tech Ref est parfaitement exacte, mais laisse un certain nombre de points dans l'ombre. Les règles présentées ci-dessus n'ont rien d'officiel, mais ont été reconstituées à partir de nombreux tests permettant de combler les trous de la documentation.

3-B-6 - Variables

MaxL n'est pas lui-même capable de définir ou modifier des variables. Toutefois, il peut utiliser deux sortes de variables provenant du système d'exploitation :

- les variables d'environnement de l'OS, qu'elles soient définies par le système ou par l'utilisateur ; ces variables gardent leur nom, préfixé par un $. Par exemple : $USERNAME, $MOISCOURANT;

- lors de l'invocation d'un script MaxL avec Essmsh.exe, il est possible de passer des paramètres qui sont ensuite appelés $1, $2, $3, etc. dans le script MaxL. Par exemple, si l'on appelle un script ainsi :

Appel d'un script MaxL avec passage de paramètres

Essmsh monscript.msh admin password c:/data.txt

Le script pourra ensuite utiliser ces paramètres selon l'ordre dans lequel ils ont été placés :

Exemple de script avec paramètres numérotés

login $1 $2 on serveur ;
import database demo.basic data from text data_file $3 on error abort ;

Grâce à ce système de variables, on évitera de devoir recourir à un script externe pour rédiger à la volée le script MaxL. Classiquement, on se contentera (sous Windows) d'un script DOS appelant le script MaxL en lui passant les paramètres nécessaires.

Si ce système est beaucoup plus pratique que la rédaction à la volée d'ESSCMD, il n'est toutefois pas exempt de pièges ! Ainsi, les variables ne sont pas interprétées (expanded) si elles sont situées dans une chaîne entre apostrophes ; pour forcer l'interprétation, il est alors possible d'ajouter des guillemets autour des apostrophes :

Utilisation des guillemets pour forcer l'interprétation de $1

export database demo.basic using server report_file $1 to data_file "'c:/$1.txt'" ;

Dans une chaîne entre apostrophes, les backslashes simples sont ignorés ; ils doivent donc être systématiquement doublés pour être pris en compte ! Ceci n'est valable que pour la partie littérale, et non pour les variables, qui sont, elles, interprétées correctement. Voici un petit exemple de script valide pour éclaircir mon propos :

Guillemets, variable et backslash sous Windows :

E:\courant>set chemin=f:\test

E:\courant>essmsh -l admin password -s serveur

Essbase MaxL Shell - Release 9.3.1 (ESB9.3.1.0.0B181)
(...)

MAXL> import database demo.basic data from local text data_file "'$chemin\\basic.txt'" on error abort ;
(...)
OK/INFO - 1241113 - Database import completed ['demo'.'basic'].

Le spool, qui ne fait pas partie de MaxL mais des commandes du client Essmsh.exe, ne comprend pas correctement la combinaison guillemets + apostrophes. Heureusement, il n'impose pas non plus d'écrire les adresses de fichiers entre apostrophes ! On écrira donc directement le chemin avec variable sans guillemets ni apostrophes :

Utilisation de variable dans un spool

MAXL> spool on to $chemin/test.log ;

Quelques contre-exemples :

Utilisations incorrectes du spool

MAXL> spool on to "'f:/test/test.log'" ;
essmsh error: Unable to open log file 'f:/test/test.log'

MAXL> spool on to '$chemin/test.log' ;
essmsh error: Unable to open log file $chemin/test.log

MAXL> spool on to "'$chemin/test.log'" ;
essmsh error: Unable to open log file 'f:/test/test.log'

3-B-7 - Commandes supplémentaires par rapport à ESSCMD

MaxL évolue et suit le développement d'Essbase, tandis qu'ESSCMD reste figé en version 6.

Ainsi, la version 7 d'Essbase présente quelques commandes ou options qui n'existent qu'en MaxL et non en ESSCMD ; la plus notable est alter database force restructure, qui provoque une restructuration dense, et les diverses commandes destinées à l'ASO.

Avec System 9, on trouve également les commandes permettant de déclencher des interactions entre Essbase et Shared Services, notamment alter system resync sss (rafraîchit la sécurité) et alter application reregister (redéclare une application défaillante auprès d'HSS).

En version 11, on trouve notamment un nouveau verbe MaxL, deploy, qui est lié à Essbase Studio.

3-C - MaxL et les triggers

3-C-1 - Création de triggers en MaxL

La version 9 a vu l'apparition des triggers. Que les experts des bases de données relationnelles ne rêvent pas trop, les triggers d'Essbase ont un champ d'action beaucoup plus limité que ceux d'Oracle, SQL Server ou même MySQL. Il s'agit essentiellement d'un outil de traçabilité : si les valeurs de certaines cellules franchissent des seuils d'alerte, ou plus généralement remplissent les conditions définies, le trigger pourra soit enregistrer un fichier de log, soit envoyer un e-mail. Il n'est pas question de refuser une saisie, ni de déclencher un calcul ou une sauvegarde.

On pourrait imaginer de mettre en place un processus parallèle qui attend la création d'un fichier par le trigger, et déclenche alors ce qu'il souhaite par des scripts MaxL. Même si les triggers d'Essbase ne proposent pas directement la possibilité de (par exemple) déclencher un calcul par un trigger, ce serait un moyen indirect d'atteindre ce but.

Les triggers s'appliquent sur des modifications de valeur de cellules, qu'elles soient dues à un chargement, un calcul ou une saisie. Il existe deux types de trigger, selon le moment où ils se déclenchent et les possibilités techniques induites :

- les triggers on update sont exécutés alors que le bloc modifié est encore en mémoire ; ils peuvent récupérer l'ancienne valeur (option log_value on) permettent l'envoi de mail, mais ne sont possibles qu'avec les cubes BSO ;

- les triggers after update sont exécutés après validation de la transaction, quand l'ancienne valeur est oubliée ; ils sont compatibles avec les cubes ASO, mais ne permettent pas l'envoi de mail

syntaxe des créations des triggers

create or replace on udpate trigger application.cube.nom_du_trigger
log_value on
where set MDX à surveiller
when condition1
then spool fichier_d_alerte1
when condition2
then mail ([serveur SMTP], [expéditeur], [destinataire], [sujet])
end ;

La documentation des triggers est assez rapide et pas exempte de coquille. Ainsi, les exemples du DBAG présentent à tort le set MDX entre guillemets ; réciproquement, la Tech Ref s'emmêle dans les parenthèses et crochets de l'action mail.

Sur DMDemo.Basic, on peut par exemple poser une alerte au cas où les ventes réalisées d'un produit sur un marché précis sont inférieures à celles du même mois de l'année précédente :

Création du trigger trig_recul

create or replace on update trigger DMDemo.Basic.trig_recul
log_value on
where crossjoin(Years.children,
crossjoin(Product.levels(0).members,
crossjoin(Market.levels(0).members,
crossjoin(Year.levels(1).members,
{(Actual, Sales)}
))))
when Sales &lt; (Sales, Years.currentMember.prevMember)
then spool recul_ventes
end ;

Les clauses where et when s'écrivent en MDX. On peut voir sur cet exemple qu'un set MDX répond à des règles très différentes de celles du FIX :

- les croisements entre sets de plusieurs membres se font par la fonction crossjoin ; comme elle n'accepte que deux arguments, il est nécessaire d'imbriquer plusieurs crossjoin ;

- le membre Ventes peut apparaître à la fois dans le where et dans le when…

- ...il est même fortement recommandé de citer toutes les dimensions, car pour les dimensions omises, MDX se positionnera par défaut sur le sommet de la dimension (et non sur l'ensemble des membres, comme le ferait un FIX).

3-C-2 - Administrer les triggers

Exécutez la requête ci-dessus, dans Essmsh ou avec l'éditeur MaxL de la console EAS. Vous devez obtenir confirmation de la bonne création du trigger :

OK/INFO - 1056213 - message du serveur [La commande du déclencheur a abouti].
OK/INFO - 1056213 - message du serveur [Mémoire disponible pour la création du déclencheur [2742] octets].
OK/INFO - 1056323 - Déclencheur remplacé - ['DMDemo.Basic.trig_recul'].

Dans la console EAS, vous pouvez maintenant faire un clic droit sur le cube et choisir Edit > Triggers. La liste des triggers apparaît :

Cette fenêtre vous permet de modifier (Edit), désactiver (Disable), supprimer (Delete) les triggers.

Le bouton New propose un assistant de création des triggers ; toutefois, il ne vous assiste pas pour la rédaction des deux clauses MDX, ce qui limite fortement sa valeur ajoutée ; de plus, sa fiabilité ne semble pas totalement assurée.

3-C-3 - Fichiers de spool

Rendez-vous dans l'Add-in Excel, faites une requête affichant les ventes mensuelles au niveau fin des autres dimensions, et saisissez un chiffre inférieur à celui de l'année précédente :

Faites un Lock and Send, puis retournez sur la console EAS. Faites un clic droit sur le cube, et choisissez Edit > View spool files :

Le fichier présente chaque alerte avec identification de l'utilisateur en cause, horodatage, point de vue, valeur avant et après modification.

Les fichiers de spool sont situés dans le sous-dossier trig du cube :

De nouvelles alertes déclenchées par le même trigger viendront s'ajouter dans le même fichier.

3-C-4 - Envoi de mail

Si la création d'un fichier de spool ne vous semble pas assez interactive, vous pouvez opter pour l'envoi d'un e-mail automatique. Pour cela, modifiez la requête de création, et exécutez la version modifiée :

Création du trigger trig_recul

when Sales &lt; (Sales, Years.currentMember.prevMember)
then mail ([smtp.dvp.com],
[alerte@dvp.com],
[antoun@dvp.com, sroux@dvp.com],
[chute des ventes]
)

Saisissez à nouveau un chiffre en recul annuel sur un niveau fin ; vous devriez recevoir le mail suivant :

This Alert is being sent to you as a result of a constraint violation in trigger(triggername_constraint-index) trig_recul_1.txt by user admin
DMDemo Basic admin Fri Apr 15 05:59:46 2011 tmail - 1 "Ventes","DEC","REALISE","A2011","PERIODIQUE","PARASOL","FRA","FRANCHISE" 49230.248996 2000.000000

Pour que l'envoi d'e-mail puisse marcher, le serveur Essbase doit avoir accès à un serveur d'envoi de mail (SMTP) non sécurisé, dont l'adresse est le premier paramètre de l'action mail.

4 - Quelques trucs à connaître

4-A - Chargement d'information et codes d'erreurs

Pour charger des données (Data Load) dans un cube, ESSCMD comme MaxL proposent soit le mode intégral (tout est annulé s'il y a la moindre erreur), soit le mode partiel (les lignes qui passent sont acceptées, celles qui provoquent une erreur sont rejetées dans un log).

Si vous choisissez le chargement partiel, Essbase renverra un code 0 (pas d'erreur) même si l'intégralité du fichier est rejetée ! Les indices que quelque chose s'est mal passé sont un WARNING dans les logs et la présence d'un fichier de rejet.
À l'inverse, si vous exigez un chargement intégral, vous n'aurez pas de fichier de rejet, ce qui ne facilite pas vraiment le débogage...

Au final, on choisit donc généralement le chargement partiel, assorti de recherche d'un WARNING et/ou de fichier de rejet, quitte à vider ensuite le cube pour le recharger sans données incomplètes.

Enfin, pour ce qui concerne le chargement d'outline (Dimension Building), vous n'aurez de toute façon pas le choix : seul le chargement partiel avec création de fichier de rejet est possible.

Codes d'erreur non documentés : de très nombreux codes d'erreur renvoyés par Essbase, aussi bien en ESSCMD qu'en MaxL, ne sont pas documentés... Certains peuvent être trouvés sur le web, pour les autres, le développeur en est réduit à déboguer à l'aveuglette.

4-B - Optimiser un chargement d'outline

À l'issue d'un dimension build, Essbase effectue une restructuration, pour laquelle vous avez l'option de conserver les données ou de vider le cube. Si vous gardez vos données et que vous avez modifié une ou plusieurs dimension(s) dense(s), le chargement d'outline provoquera une restructuration dense, ce qui peut être assez long.

Dans le cas où vous enchaînez plusieurs chargements d'outline, vous risquez donc de perdre énormément de temps à restructurer inutilement à la fin de chaque chargement. Pour optimiser votre dimension build, vous avez deux solutions :

- exporter les données en freeform, faire les chargements d'outline en effaçant les données, puis recharger le cube avec le fichier d'export ;

- utiliser les syntaxes spécifiques à ESSCMD et MaxL, que nous allons détailler maintenant.

4-B-1 - ESSCMD et l'incremental dimension building

Pour résoudre ce problème, ESSCMD a mis en place la notion de chargement incrémental (en plusieurs étapes), et des ordres spécifiques. Par exemple :

Chargement incrémental en ESSCMD

BEGININCBUILDDIM ;
INCBUILDDIM 2 "ACCOUNTS.RUL" 2 "payroll.txt" 4 "payroll.err" 1 ;
INCBUILDDIM 2 "MARKET.RUL" 2 "north.txt" 4 "north.err" 1 ;
INCBUILDDIM 2 "YEAR.RUL" 2 "time.txt" 4 "time.err" 1 ;
ENDINCBUILDDIM 4;

BEGININCBUILDDIM provoque la création d'une outline temporaire, enregistrée dans un fichier .otn. Les INCBUILDDIM successifs viennent modifier ce fichier, sans toucher à l'outline originale. Enfin, le ENDINCBUILDDIM provoque la restructuration ; le fichier .otn remplace alors le .otl. Ce fonctionnement est similaire à une modification à travers l'éditeur d'outlines (Outline > Update outline).

Il est possible d'utiliser ENDINCBUILDDIM même s'il n'y a pas eu de BEGININCBUILDDIM ni d'INCBUILDDIM. Une astuce pour scripter la copie d'un fichier outline d'un cube à un autre est donc de copier le .otl du cube source vers le cube cible en modifiant l'extension en .otn, puis de faire un ENDINCBUILDDIM afin de provoquer le remplacement d'outline et la restructuration.
Cette astuce n'a pas d'équivalent en MaxL.

4-B-2 - MaxL et le chargement multiple

MaxL traite ce problème de manière plus simple : le import database... dimensions permet de faire plusieurs chargements en une seule instruction ; la restructuration n'a alors lieu qu'en fin d'instruction.

Voici l'instruction MaxL correspondant à l'exemple ESSCMD ci-dessus :

Chargement multiple en MaxL

import database Demo.Basic dimensions
from server text data_file 'payroll.txt' using server rules_file ACCOUNTS,
from server text data_file 'north.txt' using server rules_file MARKET,
from server text data_file 'time.txt' using server rules_file YEAR
preserve all data
on error append to 'dimbuild.err' ;

Au passage, vous remarquerez qu'on perd la possibilité d'avoir des fichiers de rejet différents.

4-C - Emplacement des fichiers de données et rapidité d'exécution

Lors d'un import ou d'un export, vous avez la possibilité d'indiquer que le fichier source d'un import, ou le fichier cible d'un export, est situé sur le client ou sur le serveur. Dans le cas de fichiers volumineux, les imports/exports sont beaucoup plus rapides lorsque les fichiers sont situés sur le serveur ; de manière générale, ce gain de temps est très rentable même si vous devez ensuite déplacer les fichiers d'une machine à l'autre.

Si vous lancez vos scripts de chargement depuis un poste client, indiquez bien à Essbase que vos fichiers sont sur le serveur (option 2 en ESSCMD, option server data_file en MaxL). Utiliser un partage réseau est une très mauvaise idée, car cela force un transit par le client qui ralentit énormément le chargement.

Comme nous avons pu le voir, l'exécution d'un report script produit toujours un résultat sur le client, que ce soit en MaxL ou en ESSCMD.

4-D - Limites sur la consultation des utilisateurs, des groupes et des privilèges

Assez étrangement, les instructions de consultation de la sécurité sont incomplètes ; ainsi, il est possible de voir les privilèges d'un utilisateur ou d'un groupe, mais pas les utilisateurs ou groupes jouissant d'un privilège précis. Il est possible de voir les utilisateurs d'un groupe, mais pas les groupes d'un utilisateur.

MaxL est très pratique pour automatiser la gestion des utilisateurs et de leurs privilèges. Si vous utilisez Shared Services, il faut garder à l'esprit les différences conceptuelles entre les deux systèmes, et penser utiliser MaxL revient à faire les modifications côté Essbase, et à répercuter ensuite ces modifications sur Shared Services, avec la commande alter system resync sss. MaxL ne vous permettra donc pas d'inclure un groupe dans un autre groupe ; de même, le privilège database manager sur un cube sera transmis à l'ensemble des cubes de l'application, et ainsi de suite.

Par ailleurs, Shared Services permet d'inclure des groupes dans un groupe ; cela n'est pas possible en MaxL ou ESSCMD (mais seulement sur le OpenLDAP ou à travers l'API Java).

5 - Conclusion

Au-delà de leurs différences syntaxiques, ESSCMD et MaxL sont très proches, à la fois par leurs possibilités et par leurs limites. Même si MaxL permet de passer des paramètres plutôt que de rédiger les scripts dynamiquement (ce qui simplifie largement le développement), les possibilités limitées du langage (gestion d'erreur rudimentaire, absence de structure conditionnelle ou de boucle, etc.) font que l'encapsulation dans un langage-hôte reste le plus souvent nécessaire.

Pour ceux qui ont besoin des fonctionnalités d'un vrai langage de programmation, les API (VB, C, Java) viennent donc offrir une possibilité à considérer sérieusement.

6 - Annexes

6-A - Versions utilisées

Les tests menés pour la réalisation de cet article ont été effectués sur un Essbase 11.1.1.3, hébergé sur une VirtualBox en Windows XP.

6-B - Quelques lectures

Pour un premier aperçu des possibilités et de l'architecture d'Essbase, je vous invite à lire la Présentation d'Oracle Hyperion Essbase, de mon confrère Sébastien Roux.

Pour une synthèse sur la notion de cube (M)OLAP, vous pouvez consulter mon billet Qu'est-ce que la modélisation multidimensionnelle ? sur le blog de la rubrique Business Intelligence.

Enfin, si malgré mes objurgations vous avez perdu l'adresse de la Technical Reference, la revoici :
http://download.oracle.com/docs/cd/E12825_01/epm.111/esb_techref/launch.htm.

6-C - Remerciements

Je remercie vivement Marc, le premier qui a eu l'idée saugrenue de me coller sur Essbase, ainsi que les collègues qui ont accompagné et subi mes premiers pas sur ESSCMD et MaxL : Matthieu, Laëtitia, Wojtek et Timothée. Merci tout autant à mes stagiaires Vadim et Andrei, venus d'outre-Prut pour essuyer les plâtres de cette formation aux langages d'administration.

Un grand merci enfin à mes correcteurs, Cécile, sroux, dourouc05, Bruno2r, kalyparker et ClaudeLELOUP pour leurs précieuses relectures et additions !

6-D - Pour discuter

Si vous avez des questions, des remarques, des ajouts, des critiques à faire à propos de cet article, je vous invite à les poster dans cette discussion ( Commentez ).