CheatSheet pour travailler avec les globales
Quand on travaille avec les globales, on voit qu’il n’y a pas mantes fonction en ObjectScript (COS) à utiliser. C’est aussi le cas avec Python et Java. Toutefois, toutes ses fonctions sont indispensables quand on travaille directement avec les données sans utilisation des objets, des documents ou des tables.
Dans cet article je voudrais parler de différentes fonctions et commandes qui se servent à travailler avec les globales dans trois langues : ObjectScript, Python et Java (les deux derniers en utilisant Native API).
Avant de commencer par les commandes et fonctions qui s’utilisent pour travailler avec les globales, à mon avis, c’est important de discourir sur le sujet des globales en général. Qu'est-ce que c'est, la globale ?
En accord avec la documentation officielle, une globale (ou une variable globale) est une variable qui permet de stocker des données dans la base de données et de les rendre disponibles à tous les processus accédant à cette base de données. Pour signaler qu'une variable est globale, vous devez utiliser la syntaxe suivante :
^a
où a est le nom de la variable et ^ est le symbole qui signifie que cette variable doit être stockée dans la base de données.
La variable peut avoir des indices ou être sans eux. Dans l'exemple précédent, la variable n’a pas des indices. Si on veut les ajouter, on doit le faire en les écrivant dans les parenthèses comme ça:
^a(ind1, ind2, ...)
ou ind1 et ind2 sont les indices de la variable a.
Quand on parle des globales il est important de connaître les points suivants :
- Une globale consiste en un ensemble de nœuds (dans certains cas, un seul nœud), identifiés par des indices.
- Chaque nœud peut contenir une valeur.
- InterSystems IRIS fournit des fonctionnalités pour itérer à travers les nœuds d'un global et accéder rapidement aux valeurs (et on va discuter de ces fonctionnalités plus tard).
- Une globale est automatiquement stocké dans la base de données. Lorsque vous affectez une valeur à un nœud d'une variable globale, les données sont écrites immédiatement dans la base de données.
- Vous pouvez voir le contenu d'une globale par programmation ou sur le Management Portal.
Vous pouvez aussi lire plus sur les globales dans la série des articles sur la Communauté des Développeurs.
Pour travailler avec les globales en Python et Java on doit utiliser la Native API pour ces langages. En général, les Native APIs sont des interfaces légères qui permettent d'accéder directement aux globales. Et pour y accéder, premièrement, vous devez configurer votre environnement.
Configuration pour Python :
- Téléchargez InterSystems IRIS Native API en accord avec votre OS (s’il y a de nécessité, renommera le fichier, par exemple pour Windows et Python 3.10 ça doit être irisnative-1.0.0-py3-none-any.whl)
- Installez ce wheel :
Pip install irisnative-1.0.0-py3-none-any.whl
- Emportez le module :
import irisnative
- Ajoutez le code pour ouvrir la connexion et créer l’objet iris
args = {'hostname':'127.0.0.1',
'port':51773,
'namespace':'USER',
'username':'_SYSTEM',
'password':'SYS'}
conn = irisnative.createConnection(**args)
iris = irisnative.createIris(conn)
- Après tout est fini, n’oubliez pas à fermer la connexion et l’objet IRIS en utilisant le code ci-dessous :
conn.close()
iris.close()
Configuration pour Java :
- Ajoutez intersystems-jdbc-XXX.jar dans votre projet, où XXX est la version liée à votre version de Java. Vous pouvez trouver ce fichier dans le dossier <installation>/dev/java/lib/
- Emportez les modules suivants :
import com.intersystems.jdbc.IRISConnection;
import com.intersystems.jdbc.IRIS;
import com.intersystems.jdbc.IRISIterator;
- Dans votre code ajoutez le code pour ouvrir la connexion et créer l’objet IRIS :
String connStr = "jdbc:IRIS://<server>:<port>/<namespace>";
//par exemple "jdbc:IRIS://127.0.0.1:51773/USER"
String user = "_SYSTEM";
String pwd = "SYS";
IRISConnection conn = (IRISConnection)java.sql.DriverManager.getConnection(connStr,user,pwd);
IRIS iris = IRIS.createIRIS(conn);
- Après tout est fini, n’oubliez pas à fermer la connexion et l’objet IRIS en utilisant le code ci-dessous :
iris.close();
conn.close();
Maintenant que nous sommes familiarisés avec l’info de base sur les globales et comment configurer l’environnement, allons regarder sur les fonctions et commandes pour travailler avec eux en ObjectScript (COS), Python et Java.
Nom de fonction (commande) et sa description |
|||||||||
COS syntaxe |
COS exemples |
Python syntaxe |
Python exemples |
Java syntaxe |
Java exemples |
||||
set - attribue une valeur à une variable |
|||||||||
set:pc argument, ... où pc est post condition (facultative) et argument peut être soit variable = valeur soit (liste de variables) = valeur |
|
iris.set(value, globalName, *subscripts) où value est la valeur de datatype supportée, globalName est le nom de la globale et subscripts sont la liste des indices (une ou zéro des indices) |
|
void jdbc.IRIS.set(value, globalname, subscripts) où value est la valeur de datatype supportée, globalname est le nom de la globale et subscripts sont la liste des indices (une ou zéro des indices) |
|
||||
increment – augmente la global spécifié avec la valeur passée. S'il n'y a pas de nœud à l'adresse spécifiée, un nouveau nœud est créé avec la valeur passée. |
|||||||||
$increment(variable, num) où variable est la variable la valeur de laquelle doit être changée et num est l'incrément numérique que vous souhaitez ajouter (facultatif, par défaut = 1) |
|
iris.increment(value, globalName, *subscripts) où value est la valeur numérique, globalName est le nom de globale et subscripts sont la liste des indices (une ou zéro des indices) |
|
long increment(value, globalname, subscripts) où value est la valeur numérique, globalname est le nom de globale et subscripts sont la liste des indices (une ou zéro des indices) |
|
||||
get - obtient une valeur de la globale |
|||||||||
$get(variable, defaut) où variable est la variable la valeur de laquelle on veut obtenir et defaut est la valeur à renvoyer si la variable n'est pas définie (facultative). |
|
iris.get(globalName, *subscripts) iris.getBoolean(globalName, *subscripts) iris.getBytes(globalName, *subscripts) iris.getFloat(globalName, *subscripts) iris.getLong(globalName ,*subscripts) iris.getString(globalName, *subscripts) où globalName est le nom de globale et subscripts sont la liste des indices (une ou zéro des indices). |
|
Boolean jdbc.IRIS.getBoolean(globalname, subscripts) byte[] jdbc.IRIS.getBytes(globalname, subscripts) Date jdbc.IRIS.getDate(globalname, subscripts) Double jdbc.IRIS.getDouble(globalname, subscripts) Float jdbc.IRIS.getFloat(globalname, subscripts) InputStream jdbc.IRIS.getInputStream(globalname, subscripts) Integer jdbc.IRIS.getInteger(globalname, subscripts) Long jdbc.IRIS.getLong(globalname, subscripts) Object jdbc.IRIS.getObject(globalname, subscripts) Reader jdbc.IRIS.getReader(globalname, subscripts) Short jdbc.IRIS.getShort(globalname, subscripts) String jdbc.IRIS.getString(globalname, subscripts) Time jdbc.IRIS.getTime(globalname, subscripts) Timestamp jdbc.IRIS.getTimestamp(globalname, subscripts) IRISList jdbc.IRIS.getIRISList(globalname, subscripts) où globalname est le nom de globale et subscripts sont la liste des indices (une ou zéro des indices). Si le nœud n’existe pas la fonction retourne null. |
|
||||
kill – supprime des variables avec tous leurs nœuds descendants |
|||||||||
kill:pc argument, ... où pc est post condition (facultative) et argument (facultatif) peut être soit variable, ... soit (variable, ...) |
|
iris.kill(globalName, *subscripts) où globalname est le nom de globale et subscripts sont la liste des indices (une ou zéro des indices) |
|
jdbc.IRIS.kill(globalName, subscripts) où globalname est le nom de globale et subscripts sont la liste des indices (une ou zéro des indices) |
|
||||
zkill:pc nœud, ... où pc est post condition (facultative) et nœud est le noud exact de la globale |
|
||||||||
data/isDefined – renvoie une valeur indiquant si le nœud spécifié existe et s'il contient une valeur. Elle peut renvoyer quatre valeurs : 0 — le nœud spécifié n'existe pas ; 1 — le nœud existe et a une valeur ; 10 — le nœud est sans valeur mais a des sous-nœuds ; 11 — le nœud a à la fois une valeur et des sous-nœuds. |
|||||||||
$data(variable, target) où variable est la variable a vérifier et target est la variable où on renvoie la valeur actuelle de la variable (facultative) |
|
iris.isDefined(globalName, *subscripts) où globalName est le nom de globale et subscripts sont la liste des indices (une ou zéro des indices) |
|
int jdbc.IRIS.isDefined(globalName, subscripts) où globalname est le nom de globale et subscripts sont la liste des indices (une ou zéro des indices) |
|
||||
iterator - itère sur un ensemble de sous-nœuds. |
|||||||||
$order(variable, direction, target) où variable est la variable à partir de laquelle commence le parcours en largeur, direction est l’ordre croissant (1, par défaut) ou décroissant (-1) dans lequel on parcourt l’arbre (facultatif) et target est la variable où on renvoie la valeur actuelle de la variable trouvée (facultative) |
|
iris.iterator(globalName, *subscripts) - renvoie un objet iterator pour le nœud spécifié, où globalName est le nom de globale et subscripts sont la liste des indices (une ou zéro des indices)
|
|
IRISIterator getIRISIterator(globalName, subscripts) - renvoie un objet IRISIterator pour le nœud spécifié, où globalname est le nom de globale et subscripts sont la liste des indices (une ou zéro des indices) |
|
||||
iterator.items() – renvoi l’iterateur qui contient les indices et les valeurs
|
boolean hasNext() – renvoie true si l'itérateur a un élément suivant |
||||||||
$qsubscript(namevalue, intexpr) où namevalue est le string avec le nom de variable et intexpr est un numéro qui spécifie le nom à renvoyer : nom de l'espace de noms (-1), nom de la variable(0) ou nom de l'indice(1-..) |
|
iterator.values() – renvoi l’iterateur qui contient juste les valeurs
|
boolean hasPrevious() – renvoie true si l'itérateur a un élément précèdent |
||||||
iterator.subscripts() – renvoi l’iterateur qui contient juste les indices
|
String next() – renvoie l’élément suivant |
||||||||
$qlength(var) où var est le string avec le nom de variable dont la fonction compte le nombre d'indices |
|
iterator.reversed() – renvoi l’iterateur dans la direction opposée de la précédente
|
String previous() – renvoie l’élément suivant |
|
|||||
iterator.next() – renvoi l’indice, la valeur ou tous les deux du nœud suivant (ou précèdent) |
|
Object getValue() – obtient la valeur du nœud à la position actuelle de l'itérateur |
|||||||
$query(reference, direction, target) où reference est la variable à partir de laquelle commence le parcours en profondeur, direction est l’ordre croissant (1, par défaut) ou décroissant (-1) dans lequel on parcour l’arbre (facultatif) et target est la variable où on renvoie la valeur actuelle de la variable trouvée (facultative) |
|
iterator.startFrom(subscript) – renvoi l’iterateur qui commence par le nœud subscript |
void startFrom(subscript) – définit la position de départ de l'itérateur à l'indice spécifié où subscript est un point de départ arbitraire et n'a pas besoin de spécifier un nœud existant |
||||||
|
void remove() – supprime de la collection sous-jacente le dernier élément renvoyé par cet itérateur |
||||||||
String getSubscriptValue() – obtient l'indice de niveau le plus bas pour le nœud à la position actuelle de l'itérateur |
|||||||||
merge – copie la source dans la destination et tous les descendants de la source dans les descendants de la destination. |
|||||||||
merge:pc arg, ... où pc est post condition (facultative) et arg est destination = source |
|
merge = on recoit |
|||||||
*Tous les exemples utilisent le code présent dans les exemples précédents dans la même colonne.
J'espère que ce tableau vous aidera à développer votre propre code qui travaille directement avec les globales. Vous pouvez lire plus sur l’utilisation des globales dans la Documentation Native API pour Python et Native API pour Java. Si vous avez des questions, n'hésitez pas à les poser dans les commentaires.