Table des matières

1. Objectif de l'article
2. Les conteneurs : définition et pertinence dans le cadre d'IRIS
    2.1 Les conteneurs et les images en quelques mots
    2.2 Avantages des conteneurs pour les développeurs
    2.3 Pourquoi IRIS fonctionne bien avec Docker
3. Conditions préalables
4. Installation de l'image InterSystems IRIS
    4.1 Utilisation de Docker Hub
    4.2 Extraction de l'image
5. Exécution de l'image InterSystems IRIS
    5.1 Démarrage d'un conteneur IRIS
    5.2 Vérification de l'état des conteneurs
    5.3 Exécution de code dans le terminal conteneur
    5.4 Accès au portail de gestion IRIS
    5.5 Connexion du conteneur à VS Code
    5.6 Arrêt ou suppression du conteneur
    5.7 Configuration d'un mot de passe spécifique avec un montage de type bind
    5.8 Utilisation de volumes %SYS durables
     5.8.1 Contenu stocké sous %SYS durable
     5.8.2 Comment activer %SYS durable
6. Utilisation de Docker Compose
    6.1 Exemple d'utilisation de l'outil Docker Compose
    6.2 Exécution de Docker Compose
7. Utilisation d'un fichier Dockerfile pour l'exécution d'un code source personnalisé
    7.1 Exemple de fichier Dockerfile
    7.2 Exemple de Docker Compose
    7.3 Compréhension des couches, du balisage des images et de la différence entre le temps de compilation et le temps d'exécution
    7.4 Code source et script d'initialisation
    7.5 Création de l'image avec le fichier Dockerfile
    7.6 Exécution d'instructions dans le terminal IRIS conteneurisé
8. Conclusion et suite

1. Objectif de l'article

La communauté de développeurs InterSystems propose déjà de nombreux articles intéressants qui expliquent le fonctionnement de Docker, les commandes les plus importantes et plusieurs cas d'utilisation d'InterSystems IRIS dans un environnement conteneurisé.

Les articles de cette série ont un objectif quelque peu différent. Je suis un grand fan des guides étape par étape, c'est pourquoi je souhaite créer un guide complet sur la configuration et l'utilisation de Docker avec InterSystems IRIS, en commençant par les bases pour ensuite passer progressivement à des scénarios plus avancés tels que les instances à espaces de noms multiples, les conteneurs interconnectés, les intégrations avec des systèmes externes et les applications comprenant une interface utilisateur.

2. Les conteneurs : définition et pertinence dans le cadre d'IRIS

2.1 Les conteneurs et les images en quelques mots

Traditionnellement, pour exécuter une application, il fallait faire correspondre sa version à celle de votre système d'exploitation et la packager pour cette cible spécifique. Dans le même temps, chaque application doit être conçue pour fonctionner spécifiquement avec un système cible. Si vous vouliez qu'une application fonctionne sous macOS et Windows, vous deviez modifier sa conception et la packager pour ces différents systèmes. Les images et conteneurs Docker constituent des technologies de déploiement d'applications qui résolvent ces problèmes en permettant aux développeurs de packager un logiciel une seule fois et de l'exécuter n'importe où. 

Docker est une plateforme logicielle qui regroupe des logiciels dans des conteneurs. Une image Docker, ou image de conteneur, est un fichier exécutable autonome contenant toutes les instructions (bibliothèques, dépendances et fichiers) nécessaires pour créer et exécuter un conteneur. Une image Docker est partageable et portable, ce qui vous permet de déployer la même image à plusieurs endroits à la fois. Un conteneur Docker est un environnement d'exécution qui contient tous les composants nécessaires pour exécuter le code de l'application sans utiliser les dépendances de la machine hôte.  

Contrairement aux machines virtuelles, les conteneurs sont légers. Ils n'ont pas besoin d'un système d'exploitation complet et fonctionnent directement sur le système d'exploitation hôte via le moteur Docker Engine en utilisant uniquement les binaires et les bibliothèques nécessaires à l'application spécifique, ce qui les rend plus efficaces. Plusieurs conteneurs isolés peuvent être lancés en même temps sur la même machine sans interférer les uns avec les autres.

2.2 Avantages des conteneurs pour les développeurs

• Isolation: exécution dans un environnement propre et reproductible sans affecter le système hôte.
• Reproductibilité: assurance que la configuration fonctionne de la même manière sur différentes machines.
• Configuration facile: lancement d'une instance IRIS en quelques secondes à l'aide d'une seule commande, sans installation manuelle.

2.3 Pourquoi IRIS fonctionne bien avec Docker

L'exécution d'InterSystems IRIS dans Docker présente plusieurs avantages:

• L'application peut être exécutée et testée dans des conteneurs isolés,
• Il est possible d'utiliser des systèmes de contrôle de version partagés (tels que Git) au lieu de travailler directement sur le serveur
• L'environnement conteneurisé peut être répliqué à n'importe quelle étape, ce qui garantit la cohérence tout au long du cycle de vie du logiciel.
• Votre application peut facilement être exécutée sur n'importe quel ordinateur.

3. Conditions préalables

Pour exécuter InterSystems IRIS dans un conteneur Docker, il faut que vous ayez:

• Le moteurDocker Engine installé et en cours d'exécution:
  • Installer le moteur Docker Engine sous Linux.
  • Le moteur Docker Engine est également disponible pour Windows, macOS et Linux, via Docker Desktop.
• Gitpour permettre l'utilisation de référentiels de contrôle de source partagés.
• Le code "Visual Studio Code" pour afficher et modifier le code source.

4. Installation de l'image InterSystems IRIS

4.1 Utilisation de Docker Hub

Docker Hub est le registre central des images Docker. Il fournit une vaste bibliothèque d'images pré-construites que vous pouvez utiliser comme point de départ. InterSystems y publie les images officielles IRIS Community Edition que vous pouvez télécharger pour exécuter IRIS localement dans votre conteneur. Vous pouvez également utiliser Docker Hub pour pousser vos propres images personnalisées afin de les partager au sein de votre équipe ou de les distribuer à la communauté. Docker Hub est disponible en ligne et intégré à Docker Desktop.

4.2 Extraction de l'image

Voici quelques commandes courantes pour les images Docker :

Vous trouverez la commande pull exacte directement sur la page Docker Hub de l'image:

Pour l'image InterSystems IRIS, la commande est comme suit:

docker pull intersystems/iris-community:latest-cd

Vous pouvez également rechercher iris-community dans la barre de recherche de Docker Desktop et cliquer sur Pull:

Une fois l'installation terminée, l'image InterSystems IRIS devrait apparaître dans la liste de vos images locales:

5. Exécution de l'image InterSystems IRIS

Une fois l'image InterSystems IRIS extraite de Docker Hub, vous pouvez l'exécuter dans un conteneur. 

Voici les principales commandes pour les conteneurs Docker:

5.1 Démarrage d'un conteneur IRIS

Vous pouvez démarrer un conteneur InterSystems IRIS Community Edition nommé "my-iris" via l'interface utilisateur Docker Desktop en cliquant simplement sur le bouton Run de l'image que vous souhaitez exécuter dans le panneau Images. Pour l'image InterSystems, il est possible de spécifier quelques paramètres facultatifs, tels que les ports à exposer sur votre machine hôte pour communiquer avec les services exécutés dans le conteneur.

Cela peut être fait via le menu ci-dessus, en considérant que:

• côté gauche → port sur la machine hôte
• côté droit → port à l'intérieur du conteneur

Ports IRIS courants (à l'intérieur du conteneur)

• 1972 → Port Superserver : utilisé par IRIS pour les protocoles réseau (ObjectScript, JDBC, etc.).
• 52773 → Port du serveur Web : utilisé par IRIS pour le portail de gestion (interface Web).

Si vous ne mappez pas explicitement les ports, Docker attribuera des ports aléatoires sur l'hôte.

Vous pouvez également exécuter le conteneur à l'aide du terminal:

docker run --name my-iris -d --publish 9091:1972 --publish 9092:52773 intersystems/iris-community:latest-cd

Dans cet exemple:

• 9091 sur l'hôte est mappé à 1972à l'intérieur du conteneur (Superserver).
• 9092 sur l'hôte est mappé à 52773 à l'intérieur du conteneur (Portail de gestion).

5.2 Vérification de l'état des conteneurs

Après avoir exécuté cette commande, exécutez docker ps pour vérifier si le conteneur fonctionne correctement.

> docker ps
CONTAINER ID   IMAGE                                   COMMAND                 CREATED         STATUS                            PORTS                                                                                        NAMES
907d4c2b4ab5   intersystems/iris-community:latest-cd   "/tini -- /iris-main"   3 seconds ago   Up 2 seconds (health: starting)   0.0.0.0:9091->1972/tcp, [::]:9091->1972/tcp, 0.0.0.0:9092->52773/tcp, [::]:9092->52773/tcp   my-iris

Les conteneurs en cours d'exécution sont également répertoriés dans le panneau Containers de Docker Desktop:

L'état des images associées sera "In Use" (En cours d'utilisation), comme indiqué dans le panneau Images :

5.3 Exécution de code dans le terminal conteneur

Une fois que le statut du conteneur indique Running (exécution), tout fonctionne correctement. 

Vous pouvez le tester en ouvrant le terminal du conteneur (cliquez sur le nom du conteneur dans le panneau de conteneurs (Containers) de Docker Desktop et accédez à Exec) et en saisissant:

iris session IRIS

Cela ouvre un terminal IRIS à l'intérieur du conteneur Docker, où vous pouvez utiliser la syntaxe ObjectScript standard pour exécuter des commandes et des scripts.

5.4 Accès au portail de gestion IRIS de l'instance conteneurisée

Ensuite, ouvrez votre navigateur et accédez à:

http://localhost:9092/csp/sys/UtilHome.csp

Par défaut, les conteneurs IRIS se servent de l'utilisateur _SYSTEM avec le mot de passe SYS. Il est nécessaire de changer le mot de passe après la connexion.

Cela vous donne un accès complet au portail de gestion IRIS, vous permettant de gérer les espaces de noms, les bases de données et d'autres fonctionnalités IRIS directement depuis l'interface web.

5.5 Connexion du conteneur VSCode

Vous pouvez connecter votre IDE préféré (tel que VS Code ou Studio) au conteneur IRIS à l'aide du port Superserver mappé (par défaut 1972 à l'intérieur du conteneur, par exemple, 9091 sur l'hôte) et du port du serveur Web (par défaut 52773 à l'intérieur du conteneur, par exemple, 9092 sur l'hôte). Cela vous permet de développer et de tester du code ObjectScript directement sur le conteneur en cours d'exécution.

Pour connecter le conteneur à VSCode:

• Installez la solution InterSystems ObjectScript Extension Pack
• Ouvrez l'extension InterSystems Server
• Cliquez sur les trois points et sélectionnez "Edit server" (Modifier le serveur)
•  
• Cliquez sur "Modifier dans settings.json"
• Ajoutez cet élément au fichier json "intersystems.servers":

"docker_iris": {
    "webServer": {
         "scheme": "http",
         "host": "localhost",
         "port": 9092
    },
    "description": "Connection to Docker container."
}

• Maintenant le serveur est connecté. Vous pouvez vous connecter avec l'utilisateur _SYSTEM.
• Comme vous pouvez le constater, l'espace de noms USER (UTILISATEUR) est le seul disponible:

5.6 Arrêt ou suppression du conteneur

Pour arrêter un conteneur en cours d'exécution, utilisez la commande:

docker stop my-iris

Redémarrage du conteneur

Pour redémarrer le conteneur, utilisez la commande

docker start my-iris

Suppression (effacement) du conteneur

Pour supprimer l'instance du conteneur, mais pas l'image, utilisez la commande: 

docker rm my-iris

La totalité des données contenues dans le conteneur sera perdue, sauf si vous avez monté des volumes (nous en parlerons dans les paragraphes suivants).

5.7 Configuration d'un mot de passe spécifique avec un montage de type bind

Il est possible de configurer un mot de passe personnalisé lors du démarrage d'un conteneur à l'aide d'un fichier de mots de passe. Le fichier sera enregistré sur notre hôte et copié dans le conteneur à l'aide du mécanisme bind mount .

Lorsque vous utilisez un bind mount, un fichier ou un répertoire sur la machine hôte est monté depuis l'hôte dans un conteneur, ce qui permet de partager le code source ou les artefacts de compilation entre un environnement de développement sur l'hôte Docker et un conteneur. 

• Créez un fichier nommé password.txt contenant uniquement votre mot de passe sous forme de chaîne (attention! Notez votre mot de passe, vous en aurez besoin plus tard). 
• Copiez le chemin d'accès, dans cet exemple ce sera C:\InterSystems\DockerTest\password\password.txt
• Exécutez la commande suivante:

docker run --name my-iris -d --publish 9091:1972 --publish 9092:52773 --volume "C:\InterSystems\DockerTest:/durable" intersystems/iris-community:latest-cd --password-file /durable/password/password.txt 

Une fois le conteneur lancé, vous pouvez vous connecter avec l'utilisateur _SYSTEM et le mot de passe que vous avez enregistré dans votre fichier de mots de passe. 

À l'intérieur du conteneur Docker, vous verrez un fichier password.txt.done . Le même fichier se trouvera dans votre dossier hôte.

L'extension du fichier est remplacée par .done afin d'éviter la présence du mot de passe dans le texte brut. Il s'agit du comportement standard d'InterSystems IRIS avec les fichiers de mots de passe. Par conséquent, une fois le mot de passe lu à partir du fichier password.txt et l'utilisateur IRIS par défaut (_SYSTEM) mis à jour avec ce mot de passe, le fichier est mis à jour en ajoutant .done et en supprimant le mot de passe pour des raisons de sécurité.

Vous pouvez vous connecter au Portail de gestion à l'aide de votre mot de passe personnalisé (je vous avais dit de le noter :D). InterSystems IRIS ne vous obligera pas à changer le mot de passe après votre connexion.

Veuillez noter que si le conteneur est supprimé puis redémarré sans aucun volume durable monté (pour plus d'informations, voir le paragraphe suivant), le mot de passe ne sera pas relu à partir du fichier password.txt , car il a été remplacé par le fichier password.txt.done. Dans ce cas, le mot de passe standard "SYS" sera utilisé. 

5.8 Démarrage du conteneur avec un volume durable spécifique. Utilisation de volumes %SYS durables

Par défaut, tout ce que vous enregistrez dans un conteneur Docker en cours d'exécution disparaît lorsque vous le supprimez à l'aide de la commande docker rm <container's name> . 

Pour éviter de perdre vos données, InterSystems IRIS fournit la fonctionnalité durable %SYS. Cette fonctionnalité permet à l'instance de stocker tous les fichiers importants sur votre machine hôte, afin qu'ils survivent aux redémarrages du conteneur et de l'instance.

5.8.1 Contenu stocké sous %SYS durable

Voici quelques exemples:

• Fichiers de configuration (iris.cpf, httpd.conf)
• Configurations et journaux de la passerelle Web (/csp)
• Bases de données système (IRIS, USER, IRISSECURITY, IRISTEMP, etc.)
• Journaux, fichiers image d'écriture (WIJ) et fichiers temporaires
• Fichiers journaux (messages.log, SystemMonitor.log, etc.)
• Clé de licence (iris.key)
• Toute autre base de données que vous avez créée

5.8.2 Comment activer %SYS durable

La première chose à faire est de choisir un dossier sur votre hôte, tel que C:\InterSystems\DockerTest

• Sous Linux, assurez-vous qu'IRIS peut y écrire en créant l'utilisateur irisowner et en lui attribuant la propriété du répertoire:

adduser irisowner
chown -R irisowner:irisowner /InterSystems/DockerTest

• Sous Windows, vous pouvez ignorer cette étape, car Docker Desktop will montera le dossier avec vos autorisations utilisateur Windows actuelles.

Ensuite, montez votre dossier hôte et indiquez à IRIS où écrire ses données durables à l'aide de la variable ISC_DATA_DIRECTORY:

  --volume "C:\InterSystems\DockerTest:/durable" --env ISC_DATA_DIRECTORY=/durable/iris

L'instruction complète à exécuter sur le terminal est la suivante:

docker run --name my-iris -d --publish 9091:1972 --publish 9092:52773 --volume "C:\InterSystems\DockerTest:/durable" --env ISC_DATA_DIRECTORY=/durable/iris intersystems/iris-community:latest-cd --password-file /durable/password/password.txt

À ce stade, vous pouvez inspecter votre conteneur et observer qu'un dossier durable est monté et contient les répertoires iris/ (pour le %SYS durable) et password/. Sur votre hôte, vous pouvez également voir les deux répertoires:

Si le conteneur est arrêté et supprimé, lorsque vous recréez le conteneur avec la même commande de Docker Compose IRIS restaurera son état précédent (utilisateurs, configuration, journaux, bases de données, etc.) à l'aide des données du dossier iris/, de sorte que rien ne soit perdu. Vous pouvez tester cette méthode en créant une application web, en arrêtant et en supprimant le conteneur, puis en le recréant une deuxième fois. Sans utiliser la fonctionnalité durable %SYS, toutes les modifications apportées à %SYS sont perdues lorsque le conteneur est supprimé et l'instance est lancée à chaque fois comme une nouvelle instance. 

Veuillez noter que si vous supprimez le dossier iris/, la prochaine fois que vous lancerez le conteneur IRIS, il sera initialisé comme lors d'une nouvelle installation, car il ne trouvera pas les données %SYS précédentes. Un tout nouveau dossier iris/ sera créé.

6. Utilisation de Docker Compose 

Jusqu'à présent, vous avez démarré InterSystems IRIS à l'aide d'une seule commande longue docker run. Cela fonctionne, mais il devient rapidement difficile de tout gérer avec des commandes shell simples.

Docker Compose est un fichier de configuration YAML qui permet de définir comment exécuter un ou plusieurs conteneurs. Cela simplifie le contrôle de l'ensemble de votre pile d'applications, facilitant la gestion des services, des réseaux et des volumes. Une seule commande vous permet de créer et de démarrer tous les services à partir de votre fichier de configuration.

Voici les commandes courantes pour Docker Compose:

6.1 Exemple d'utilisation de l'outil Docker Compose

Pour utiliser Docker Compose, il est nécessaire de créer un fichier docker-compose.yml contenant toutes les configurations du conteneur que l'on souhaite créer et démarrer.

Ainsi la commande suivante:

docker run --name my-iris -d --publish 9091:1972 --publish 9092:52773 --volume "C:\InterSystems\DockerTest:/durable" --env ISC_DATA_DIRECTORY=/durable/iris intersystems/iris-community:latest-cd --password-file /durable/password/password.txt

peut être remplacé par la suivante docker-compose.yml:

# docker-compose.yml     
services:
  iris:
    container_name: my-iris
    image: intersystems/iris-community:latest-cd
    init: true
    volumes:
      # Données système/persistantes (installation IRIS, bases de données, etc.)# Sous Windows, vous pouvez utiliser les deux options: "C:\\InterSystems\\DockerTest:/durable"
      - C:/InterSystems/DockerTest:/durable
      ports:
      - "9092:52773"# Portail de gestion / API REST
      - "9091:1972"# Port SuperServer
      environment:
      - ISC_DATA_DIRECTORY=/durable/iris
      # Utilisation du fichier de mots de passe pour se connecter au conteneur
      command: --password-file /durable/password/password.txt

6.2 Exécution de Docker Compose 

Ouvrez un terminal dans le répertoire où le fichier Docker Compose est enregistré (ou utilisez l'option -f) et exécutez la commande suivante:

docker compose up -d

Votre conteneur IRIS démarrera dans la configuration exacte spécifiée dans le fichier Docker Compose

Dans Docker Desktop, vous pouvez désormais voir qu'une pile composée appelée "dockertest" (elle prend le nom du dossier dans lequel Docker Compose est enregistré) a été créée et associée au conteneur "my-iris":

7. Utilisation d'un fichier Dockerfile pour l'exécution d'un code source personnalisé

Jusqu'à présent, vous avez exécuté InterSystems IRIS directement à partir de l'image Docker officielle. Cependant, nous aurons peut-être besoin de télécharger automatiquement des classes ObjectScript ou d'autres codes personnalisés dans l'image lors de sa création. 

Un fichier Dockerfileest un fichier texte contenant des instructions pour créer une image à partir d'une image de base (comme intersystems/iris-community:latest-cd). Grâce à un fichier Dockerfile, nous pouvons ajouter du code source personnalisé dans le conteneur et exécuter des commandes personnalisées lors de la création de l'image. 

7.1 Exemple de fichier Dockerfile

Le prochain exemple fournit un fichier Dockerfile qui effectue les opérations suivantes:

• Démarrez l' image à partir de l'image officielle InterSystems IRIS.
• Copiez le code de votre application depuis le dossier src/ vers le conteneur.
• Exécutez un script pour importer les classes et initialiser l'application conteneurisée, puis enregistrez les journaux dans un fichier journal.
• Exposez les ports InterSystems IRIS par défaut.

7.2 Exemple d'utilisation de l'outil Docker Compose

Vous devez également modifier Docker Compose afin de spécifier la création de l'image à partir du fichier Dockerfile situé dans le dossier courant:

# docker-compose.yml     
services:
  iris:
    container_name: my-iris
    build: # Cela indique à Docker de créer une nouvelle image basée sur celle spécifiée dans le fichier Dockerfile
      context: .        # Construction de l'image à partir du fichier Dockerfile local
      dockerfile: Dockerfile
    image: my-modified-iris-image:latest   # attribution d'une nouvelle balise à la nouvelle image afin d'éviter de remplacer l'image de base
    init: true
    volumes:
      # Données système/persistantes (installation IRIS, bases de données, etc.)# Sous Windows, vous pouvez utiliser les deux options: "C:\\InterSystems\\DockerTest:/durable"
      - C:/InterSystems/DockerTest:/durable
ports:
      - "9092:52773"# Portail de gestion / API REST
      - "9091:1972"# Port SuperServer
environment:
      - ISC_DATA_DIRECTORY=/durable/iris
    # Utilisation du fichier de mots de passe pour se connecter au conteneur
    command: --password-file /durable/password/password.txt

7.3 Compréhension des couches, du balisage des images et de la différence entre le temps de compilation et le temps d'exécution

Dans Docker, comme expliqué ici: Qu'est-ce qu'une image?, il y a deux principes importants à garder à l'esprit:

1. Les images sont immuables: une fois qu'une image est créée, elle ne peut plus être modifiée. Vous pouvez uniquement créer une nouvelle image ou y ajouter des modifications.
2. Les images de conteneur sont composées de couches: chaque couche représente un ensemble de modifications du système de fichiers qui ajoutent, suppriment ou modifient des fichiers.

De nouvelles couches sont ajoutées à une image lorsque les instructions spécifiées dans un fichier Dockerfile sont exécutées. Ces couches apparaîtront également dans les informations relatives à l'image.

Dans cette optique, il est très important de distinguer ce que fait Docker au temps de compilation (lorsqu'il crée une image à partir d'un fichier Dockerfile) et au temps d' exécution (lorsqu'il démarre un conteneur à partir de cette image).

Chacune de ces instructions Dockerfile est exécutée au temps de compilation: 

• COPY: les fichiers sont copiés dans l'image
• RUN: exécute des commandes et enregistre les résultats sous forme de nouvelles couches d'image
• ENTRYPOINT: ne modifie pas le système de fichiers, mais définit le processus par défaut qui sera lancé au moment de l'exécution
• EXPOSE: définit les métadonnées relatives aux ports que l'image prévoit d'utiliser

Au temps d'exécution, Docker ne reconstruit pas l'image, mais ajoute une couche de conteneur par-dessus. Toutes les modifications apportées pendant l'exécution du conteneur (comme les nouveaux fichiers, les modifications, les journaux) sont enregistrées dans cette couche temporaire.

D'après le dernier exemple fourni par Docker Compose:

build: # cela indique à Docker de créer une nouvelle image basée sur celle spécifiée dans le fichier Dockerfile
context: .        # Construction de l'image à partir du fichier Dockerfile local
dockerfile: Dockerfile
image: my-modified-iris-image:latest   # attribution d'une nouvelle balise à la nouvelle image afin d'éviter de remplacer l'image de base

Ces instructions indiquent à Docker de créer une nouvelle image appelée "my-modified-iris-image:latest" (ceci s'appelle un tag) en récupérant l'image de base et en la modifiant comme décrit dans le fichier Dockerfile. Il est très important de marquer la nouvelle image avec un nom distinct. Si nous évitons d'apposer une balise sur l'image nouvellement créée, l'image de base sera remplacée par la nouvelle. L'image officielle sera toujours disponible sur Docker Hub, mais cette version locale la masquera et tous les projets faisant référence à cette balise utiliseront désormais, sans le savoir, l'image personnalisée, contenant plusieurs nouvelles couches.

Pour éviter cela, utilisez toujours une balise distincte pour créer une nouvelle image distincte tout en conservant l'image de base officielle propre et réutilisable. 

7.4 Code source et script d'initialisation

À ce stade, nous devons créer au moins une classe et la placer dans le src/ dossier. La classe sera copiée dans le conteneur et importée via le iris.script fichier, qui contient toutes les instructions nécessaires pour importer les classes et initialiser l'application lors de la création de l'image.

Créez un nouveau répertoire appelé src/DockerStepByStep dans le dossier de votre projet et créez le fichier de classe suivant:

Class DockerStepByStep.cheers Extends%RegisteredObject
{
ClassMethod sayHi() As%Status
{
Set sc = $$$OKw"Hi mom!",!
Return sc
}
}

Dans la racine de votre projet, créez un fichier portant le nom iris.script:

// Non-expiration des mots de passe pour le mode devzn"%SYS"Do##class(Security.Users).UnExpireUserPasswords("*")
// Téléchargement des cours à partir d'une source fiablezn"USER"// Les classes à importerset importPath = "/opt/irisapp/src"write"Loading classes at '", importPath, "' ...", !
set errors = ""do$System.OBJ.Import(importPath,"cuk",,.errors)
if errors = 0 { write"Classes loaded successfully", ! } else { write errors, " errors occurred while loading classes!", ! }
halt

7.5 Création de l'image avec le fichier Dockerfile

Pour la première exécution, vous pouvez utiliser la commande suivante pour créer l'image à partir du fichier Dockerfile (le drapeau --build force Docker à recréer l'image à partir de votre fichier Dockerfile):

docker-compose up --build

Pour les autres exécutions, si le fichier Dockerfile n'a pas été modifié, vous pouvez simplement exécuter ce qui suit: 

docker-compose up -d

Une fois la création de l'image lancée, vous verrez apparaître les journaux suivants dans le terminal:

PS C:\InterSystems\DockerTest> docker-compose up --build
[+] Building 21.5s (13/13) FINISHED
 => [internal] load local bake definitions                                                                     0.0s
 => => reading from stdin 530B                                                                                 0.0s
 => [internal] load build definition from Dockerfile                                                           0.0s
 => => transferring dockerfile: 1.73kB                                                                         0.0s
 => [internal] load metadata for docker.io/intersystems/iris-community:latest-cd                              10.0s
 => [internal] load .dockerignore                                                                              0.0s
 => => transferring context: 2B                                                                                0.0s
 => [1/6] FROM docker.io/intersystems/iris-community:latest-cd@sha256:93488df381f5868649e7bfc33a9083a3e86a22d  0.9s
 => => resolve docker.io/intersystems/iris-community:latest-cd@sha256:93488df381f5868649e7bfc33a9083a3e86a22d  0.0s
 => [internal] load build context                                                                              0.0s
 => => transferring context: 147B                                                                              0.0s
 => [2/6] WORKDIR /opt/irisapp                                                                                 0.0s
 => [3/6] COPY src src                                                                                         0.1s
 => [4/6] COPY iris.script .                                                                                   0.1s
 => [5/6] RUN mkdir -p /opt/irisapp/logs                                                                       0.3s
 => [6/6] RUN iris start IRIS &&     iris session IRIS < iris.script > /opt/irisapp/logs/build.log 2>&1 &&     4.5s
 => exporting to image                                                                                         4.5s
 => => exporting layers                                                                                        3.3s
 => => exporting manifest sha256:3ce316cefa21a3707251c4287005a15b02e6dc0151b24baf2a82f76064792250              0.0s
 => => exporting config sha256:00238e19edef86b29149d2eb89ff75f4d1465ba0d9a2ac4494a14d3bd3746a94                0.0s
 => => exporting attestation manifest sha256:3579cab5c8accc7958090276deb60bd7dbbc2ecbf13af8e7fa8c4ff2dfe91028  0.0s
 => => exporting manifest list sha256:17b969c340f57d611cc7603287cc6db50cffd696258a72b5648ece0a919676ac         0.0s
 => => naming to docker.io/intersystems/iris-community:latest-cd                                               0.0s
 => => unpacking to docker.io/intersystems/iris-community:latest-cd                                            0.9s
 => resolving provenance for metadata file                                                                     0.0s
[+] Running 3/3
 ✔ intersystems/iris-community:latest-cd  Built                                                                0.0s
 ✔ Network dockertest_default             Created                                                              0.1s
 ✔ Container my-iris                      Created                                                              0.2s 

À l'étape 6/6, le fichier iris.script est exécuté dans l'instance IRIS conteneurisée et les journaux sont enregistrés dans le chemin /opt/irisapp/logs/build.log.

Pour afficher les journaux, vous pouvez exécuter l'instruction suivante:

docker exec -it my-iris cat /opt/irisapp/logs/build.log

Vous devriez voir les enregistrements suivants qui vous informent du résultat de la compilation de la classe:

Node: buildkitsandbox, Instance: IRIS
USER>
USER>
%SYS>
%SYS>
%SYS>
%SYS>
USER>
USER>
USER>
USER>
Loading classes at '/opt/irisapp/src' ...
USER>
USER>
Load of directory started on 09/16/202507:46:28
Loading file /opt/irisapp/src/DockerStepByStep/cheers.cls as udl
Compilation started on 09/16/202507:46:28 with qualifiers 'cuk'
Class DockerStepByStep.cheers is up-to-date.
Compilation finished successfully in 0.005s.
Load finished successfully.
USER>
Classes loaded successfully
USER>
USER>

Sur Docker Desktop, vous pouvez voir qu'une nouvelle image appelée "my-modified-iris-image" a été créée et s'exécute parallèlement à l'image officielle de base.

Si vous examinez les images, vous constaterez que la version personnalisée est composée de 31 couches, contre 25 couches pour l'originale. Les nouvelles couches correspondent aux instructions exécutées au moment de la compilation par le fichier Dockerfile:

7.6 Exécution d'instructions dans le terminal IRIS conteneurisé

Pour tester les classes, vous pouvez activer le terminal Iris dans l'instance IRIS conteneurisée. Pour ce faire, exécutez l'instruction suivante:

docker exec -it my-iris iris session IRIS

À ce stade, vous pouvez invoquer la méthode de classe à partir de l'espace de noms USER à l'aide de la commande suivante:

do##class(DockerStepByStep.cheers).sayHi()

Finalement, vous devriez obtenir le résultat suivant:

PS C:\InterSystems\DockerTest> docker exec -it my-iris iris session IRIS
Node: 41c3c7a9f2e4, Instance: IRIS
USER>do##class(DockerStepByStep.cheers).sayHi()
Hi mom!

8. Conclusion et suite

Nous avons parcouru l'ensemble du cycle de mise en œuvre d'InterSystems IRIS dans Docker:

• extraction de l'image
• démarrage et configuration des conteneurs
• persistance des données avec %SYS durable
• création d'images personnalisées avec votre propre code et vos propres scripts

Cela suffit pour commencer à expérimenter IRIS dans un environnement conteneurisé et l'utiliser pour le développement.

Un référentiel GitHub contenant tous les fichiers mentionnés dans la dernière partie (Docker Compose, Dockerfile, iris.script, etc.) est disponible.

Ne manquez pas le prochain article!

Cet article vous présente le concept des environnements virtuels en Python, qui sont essentiels pour gérer les dépendances et isoler les projets du système d'exploitation.

Qu'est-ce qu'un environnement virtuel?

Un environnement virtuel est un dossier qui contient :

• Une version spécifique de Python
• Au démarrage, un répertoire site-packages vide

Les environnements virtuels vous aideront à isoler votre projet de l'installation Python du système d'exploitation et d'autres projets.

Utilisation

Pour utiliser les environnements virtuels, vous pouvez suivre les étapes suivantes:

1. Création d'un environnement virtuel: Vous pouvez créer un environnement virtuel à l'aide du module venv fourni avec Python. Ouvrez votre terminal et exécutez:

   python -m venv .venv
   

   Remplacez .venv par le nom de l'environnement souhaité.

2. Activation de l'environnement virtuel: Après avoir créé l'environnement virtuel, vous devez l'activer. La commande varie en fonction de votre système d'exploitation:

   • Sous Windows:

   .venv\Scripts\Activate.ps1
   

   Si vous rencontrez une erreur, vous devrez peut-être exécuter la commande suivante dans votre terminal

   Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process -Force; .venv\Scripts\Activate.ps1
   

   • Sous macOS et Linux:

   source .venv/bin/activate
   

Une fois activé, le prompt de votre terminal se modifie pour indiquer que vous travaillez désormais dans l'environnement virtuel.

Exemple:

(.venv) user@machine:~/project$

Remarquez le préfixe (.venv) du prompt du terminal, qui indique que l'environnement virtuel est actif.

Vous pouvez maintenant installer des packages à l'aide de pip. Ils seront installés dans l'environnement virtuel plutôt que dans l'installation globale de Python.

Puis-je utiliser des environnements virtuels dans IRIS?

Bonne question!

La réponse est simple : oui et non.

• Non, puisque IRIS ne prend pas officiellement en charge les environnements virtuels.
• Oui, puisque après avoir lu tous ces articles, nous connaissons désormais le fonctionnement de Python, celui d'IRIS et nous savons ce qu'est un environnement virtuel. Nous sommes donc peut-être en mesure de simuler un environnement virtuel dans IRIS en utilisant les configurations et les paramètres appropriés.

Comment simuler un environnement virtuel dans IRIS?

Un environnement virtuel comprend deux éléments:

• Une version spécifique de Python
• Un répertoire site-packages

IRIS dispose d'un système appelé Flexible Python Runtime (environnement d'exécution Python flexible) qui nous donne la possibilité suivante:

• utiliser une version spécifique de Python.
• mettre à jour le sys.path pour inclure un répertoire spécifique.

Nous pouvons donc simuler un environnement virtuel dans IRIS en utilisant leFlexible Python Runtime et en configurant le sys.path pour inclure un répertoire spécifique et une version spécifique de Python. 🥳

La configuration d'un Flexible Python Runtime dans IRIS est facile, vous pouvez suivre les étapes décrites dans la documentation IRIS.

En bref, il faut:

1. Configurez PythonRuntimeLibrary pour l'orienter vers le fichier lib python de la version Python spécifique que vous souhaitez utiliser.

   Exemple:

   • Windows : C:\Program Files\Python311\python3.dll (Python 3.11 sous Windows)
   • Linux : /usr/lib/x86_64-linux-gnu/libpython3.11.so.1.0 (Python 3.11 sous Ubuntu 22.04 avec architecture x86)

2. Configurez le PythonPath pour l'orienter vers le répertoire site-packages de la version Python spécifique que vous souhaitez utiliser.

   Exemple:

   • Utilisez le répertoire site-packages de votre environnement virtuel, qui se trouve généralement dans le répertoire .venv/lib/python3.x/site-packages.

⚠️ Ainsi, toute votre instance IRIS sera configurée pour l'utilisation d'une version spécifique de Python et d'un répertoire site-packages spécifique.

🩼 Limitation :

• Vous n'obtiendrez pas exactement le même sys.path que pour un environnement virtuel, car IRIS ajoutera automatiquement certains répertoires au sys.path, tels que <installation_directory>/lib/python et d'autres que nous avons examinés dans l'article sur les modules.

🤫 Si vous souhaitez automatiser cette opération, vous pouvez utiliser ce formidable package: iris-embedded-python-wrapper

Pour l'utiliser, il faut:

Que vous soyez dans votre environnement venv, puis installez le package:

(.venv) user@machine:~/project$
pip install iris-embedded-python-wrapper

Ensuite, liez simplement ce venv à IRIS à l'aide de la commande suivante:

(.venv) user@machine:~/project$
bind_iris

Vous verrez le message suivant:

INFO:iris_utils._find_libpyton:Created backup at /opt/intersystems/iris/iris.cpf.0f4a1bebbcd4b436a7e2c83cfa44f515
INFO:iris_utils._find_libpyton:Created merge file at /opt/intersystems/iris/iris.cpf.python_merge
IRIS Merge of /opt/intersystems/iris/iris.cpf.python_merge into /opt/intersystems/iris/iris.cpf
INFO:iris_utils._find_libpyton:PythonRuntimeLibrary path set to /usr/local/Cellar/python@3.11/3.11.13/Frameworks/Python.framework/Versions/3.11/Python
INFO:iris_utils._find_libpyton:PythonPath set to /xxxx/.venv/lib/python3.11/site-packages
INFO:iris_utils._find_libpyton:PythonRuntimeLibraryVersion set to 3.11

Pour dissocier le venv d'IRIS, vous pouvez utiliser la commande suivante:

(.venv) user@machine:~/project$
unbind_iris

Conclusion

Vous avez découvert les avantages de l'utilisation d'environnements virtuels en Python, la manière de les créer et de les utiliser, ainsi que la manière de simuler un environnement virtuel dans IRIS à l'aide du Flexible Python Runtime.

Introduction

Depuis qu'InterSystems a récemment annoncé l'arrêt du support d'InterSystems Studio à partir de la version 2023.2 au profit du développement exclusif d'extensions pour l'IDE Visual Studio Code (VSC), estimant que ce dernier offre une expérience supérieure par rapport à Studio, beaucoup d'entre nous, développeurs, avons changé ou commencé à utiliser VSC. Beaucoup se sont peut-être demandé comment ouvrir le Terminal pour effectuer des opérations, car VSC n'a pas de panneau de sortie comme Studio, ni de fonctionnalité intégrée pour ouvrir le terminal IRIS, sauf en téléchargeant les plugins développés par InterSystems.

InterSystems FAQ rubric

Lorsque vous exécutez une routine dans le terminal et qu'une erreur se produit dans le programme, si vous n'avez pas défini correctement le piège à erreurs, le programme entrera en mode de débogage comme indiqué ci-dessous.

USER>do^error1
 write A
^
a+2^error1 *A
USER 2d0>

A partir de cet état, entrez la commandeQuit pour revenir à l'état précédant le démarrage de la routine.

USER 2d0>Quit

Si une transaction est en cours de traitement dans la routine où l'erreur s'est produite, une invite similaire à celle ci-dessous s'affiche.

Interagir avec les utilisateurs dans le terminal : Guide d'utilisation de %Library.Prompt dans IRIS

Vous êtes-vous déjà demandé comment des commandes telles que ^DATABASE interagissent avec les utilisateurs dans le terminal ? Ou peut-être écrivez-vous une routine d'automatisation et souhaitez-vous spécifier des options directement à partir du terminal. Heureusement, la classe %Library.Prompt d'IRIS offre un moyen simple de le faire !

Saisie d'une chaîne de caractères

Bonjour les développeurs !

Récemment, j'ai été impressionné par l'article  de @Dan Pasco  dans lequel il explique également comment il utilise les alias de terminal. 

Les alias de terminal sont un outil très puissant pour les développeurs et les administrateurs système si vous avez souvent besoin d'appeler des expressions de terminal encombrantes et de les rendre plus courtes et plus propres. Voici le lien pour la documentation
de l'alias de terminal .
 

Mais qu'en est-il des environnements Docker ? Que faire si vous êtes fan des environnements de développement Docker mais que vous souhaitez continuer à utiliser vos alias préférés avec Docker ?

Il s'avère que c'est tout à fait possible.

Nous avons un délicieux dataset avec des recettes écrites par plusieurs utilisateurs de Reddit, mais la plupart des informations sont du texte libre comme le titre ou la description d'un article. Voyons comment nous pouvons très facilement charger l'ensemble de données, extraire certaines fonctionnalités et l'analyser à l'aide des fonctionnalités du grand modèle de langage OpenAI contenu dans Embedded Python et le framework Langchain.

Chargement de l'ensemble de données

Tout d’abord, nous devons charger l’ensemble de données ou pouvons-nous simplement nous y connecter ?

Il existe différentes manières d'y parvenir : par exemple CSV Record Mapper vous pouvez utiliser dans une production d'interopérabilité ou même de belles applications OpenExchange comme csvgen.

Nous utiliserons Foreign Tables. Une fonctionnalité très utile pour projeter des données physiquement stockées ailleurs vers IRIS SQL. Nous pouvons l'utiliser pour avoir une toute première vue des fichiers de l'ensemble de données.

Nous créons un Foreign Server:

CREATE FOREIGN SERVER dataset FOREIGN DATA WRAPPER CSV HOST '/app/data/'

Et puis une table étrangère qui se connecte au fichier CSV:

CREATE FOREIGN TABLE dataset.Recipes (
  CREATEDDATE DATE,
  NUMCOMMENTS INTEGER,
  TITLE VARCHAR,
  USERNAME VARCHAR,
  COMMENT VARCHAR,
  NUMCHAR INTEGER
) SERVER dataset FILE 'Recipes.csv' USING
{
  "from": {
    "file": {
       "skip": 1
    }
  }
}

Et voilà, nous pouvons immédiatement exécuter des requêtes SQL sur dataset.Recipes:

## De quelles données avons-nous besoin ? L’ensemble de données est intéressant et nous avons faim. Cependant, si nous voulons décider d'une recette à cuisiner, nous aurons besoin de plus d'informations que nous pourrons utiliser pour analyser.

Nous allons travailler avec deux classes persistantes (tables):

• yummy.data.Recipe: une classe contenant le titre et la description de la recette et quelques autres propriétés que nous souhaitons extraire et analyser (par exemple Score, Difficulty, Ingredients, CuisineType, PreparationTime)
• yummy.data.RecipeHistory: une classe simple pour enregistrer que faisons-nous avec la recette

Nous pouvons maintenant charger nos tables yummy.data* avec le contenu de l'ensemble de données:

do ##class(yummy.Utils).LoadDataset()

Cela a l'air bien, mais nous devons encore découvrir comment générer des données pour les champs Score, Difficulty, Ingredients, PreparationTime et CuisineType. ## Analyser les recettes Nous souhaitons traiter le titre et la description de chaque recette et :

• Extraire des informations telles que Difficulté, Ingrédients, Type de Cuisine, etc.
• Construire notre propre score en fonction de nos critères afin que nous puissions décider de ce que nous voulons cuisiner.

Nous allons utiliser ce qui suit :

• yummy.analysis.Analysis - une structure d'analyse générique que nous pouvons réutiliser au cas où nous souhaiterions construire plus d'analyse.
• yummy.analysis.SimpleOpenAI - une analyse qui utilise le modèle Embedded Python + Langchain Framework + OpenAI LLM.

LLM (large language models) sont vraiment un excellent outil pour traiter le langage naturel.

LangChainest prêt à fonctionner en Python, nous pouvons donc l'utiliser directement dans InterSystems IRIS en utilisant Embedded Python.

La classe complète SimpleOpenAI ressemble à ceci:

/// Analyse OpenAI simple pour les recettes
Class yummy.analysis.SimpleOpenAI Extends Analysis
{

Property CuisineType As %String;

Property PreparationTime As %Integer;

Property Difficulty As %String;

Property Ingredients As %String;

/// Run
/// Vous pouvez essayer ceci depuis un terminal :
/// set a = ##class(yummy.analysis.SimpleOpenAI).%New(##class(yummy.data.Recipe).%OpenId(8))
/// do a.Run()
/// zwrite a
Method Run()
{
    try {
        do ..RunPythonAnalysis()

        set reasons = ""

        // mes types de cuisine préférés
        if "spanish,french,portuguese,italian,korean,japanese"[..CuisineType {
            set ..Score = ..Score + 2
            set reasons = reasons_$lb("It seems to be a "_..CuisineType_" recipe!")
        }

        // je ne veux pas passer toute la journée à cuisiner :)
        if (+..PreparationTime < 120) {
            set ..Score = ..Score + 1
            set reasons = reasons_$lb("You don't need too much time to prepare it") 
        }
        
        // bonus pour les ingrédients préférés !
        set favIngredients = $listbuild("kimchi", "truffle", "squid")
        for i=1:1:$listlength(favIngredients) {
            set favIngred = $listget(favIngredients, i)
            if ..Ingredients[favIngred {
                set ..Score = ..Score + 1
                set reasons = reasons_$lb("Favourite ingredient found: "_favIngred)
            }
        }

        set ..Reason = $listtostring(reasons, ". ")

    } catch ex {
        throw ex
    }
}

/// Mettre à jour la recette avec les résultats de l'analyse
Method UpdateRecipe()
{
    try {
        // appeler d'abord l'implémentation de la classe parent
        do ##super()

        // ajouter des résultats d'analyse spécifiques à OpenAI
        set ..Recipe.Ingredients = ..Ingredients
        set ..Recipe.PreparationTime = ..PreparationTime
        set ..Recipe.Difficulty = ..Difficulty
        set ..Recipe.CuisineType = ..CuisineType

    } catch ex {
        throw ex
    }
}

/// Exécuter une analyse à l'aide de Embedded Python + Langchain
/// do ##class(yummy.analysis.SimpleOpenAI).%New(##class(yummy.data.Recipe).%OpenId(8)).RunPythonAnalysis(1)
Method RunPythonAnalysis(debug As %Boolean = 0) [ Language = python ]
{
    # load OpenAI APIKEY from env
    import os
    from dotenv import load_dotenv, find_dotenv
    _ = load_dotenv('/app/.env')

    # account for deprecation of LLM model
    import datetime
    current_date = datetime.datetime.now().date()
    # date after which the model should be set to "gpt-3.5-turbo"
    target_date = datetime.date(2024, 6, 12)
    # set the model depending on the current date
    if current_date > target_date:
        llm_model = "gpt-3.5-turbo"
    else:
        llm_model = "gpt-3.5-turbo-0301"

    from langchain.chat_models import ChatOpenAI
    from langchain.prompts import ChatPromptTemplate
    from langchain.chains import LLMChain

    from langchain.output_parsers import ResponseSchema
    from langchain.output_parsers import StructuredOutputParser

    # init llm model
    llm = ChatOpenAI(temperature=0.0, model=llm_model)

    # prepare the responses we need
    cuisine_type_schema = ResponseSchema(
        name="cuisine_type",
        description="What is the cuisine type for the recipe? \
                     Answer in 1 word max in lowercase"
    )
    preparation_time_schema = ResponseSchema(
        name="preparation_time",
        description="How much time in minutes do I need to prepare the recipe?\
                     Anwer with an integer number, or null if unknown",
        type="integer",
    )
    difficulty_schema = ResponseSchema(
        name="difficulty",
        description="How difficult is this recipe?\
                     Answer with one of these values: easy, normal, hard, very-hard"
    )
    ingredients_schema = ResponseSchema(
        name="ingredients",
        description="Give me a comma separated list of ingredients in lowercase or empty if unknown"
    )
    response_schemas = [cuisine_type_schema, preparation_time_schema, difficulty_schema, ingredients_schema]

    # get format instructions from responses
    output_parser = StructuredOutputParser.from_response_schemas(response_schemas)
    format_instructions = output_parser.get_format_instructions()
    
    analysis_template = """\
    Interprete and evaluate a recipe which title is: {title}
    and the description is: {description}
    
    {format_instructions}
    """
    prompt = ChatPromptTemplate.from_template(template=analysis_template)

    messages = prompt.format_messages(title=self.Recipe.Title, description=self.Recipe.Description, format_instructions=format_instructions)
    response = llm(messages)

    if debug:
        print("======ACTUAL PROMPT")
        print(messages[0].content)
        print("======RESPONSE")
        print(response.content)

    # populate analysis with results
    output_dict = output_parser.parse(response.content)
    self.CuisineType = output_dict['cuisine_type']
    self.Difficulty = output_dict['difficulty']
    self.Ingredients = output_dict['ingredients']
    if type(output_dict['preparation_time']) == int:
        self.PreparationTime = output_dict['preparation_time']

    return 1
}

}

La méthode RunPythonAnalysis c'est ici qu'entre en jeu OpenAI :). Vous pouvez le lancer directement depuis votre terminal pour une recette donnée :

do ##class(yummy.analysis.SimpleOpenAI).%New(##class(yummy.data.Recipe).%OpenId(12)).RunPythonAnalysis(1)

Nous obtiendrons un résultat comme celui-ci :

USER>do ##class(yummy.analysis.SimpleOpenAI).%New(##class(yummy.data.Recipe).%OpenId(12)).RunPythonAnalysis(1)
======ACTUAL PROMPT
                    Interprete and evaluate a recipe which title is: Folded Sushi - Alaska Roll
                    and the description is: Craving for some sushi but don't have a sushi roller? Try this easy version instead. It's super easy yet equally delicious!
[Video Recipe](https://www.youtube.com/watch?v=1LJPS1lOHSM)
# Ingredients
Serving Size:  \~5 sandwiches      
* 1 cup of sushi rice
* 3/4 cups + 2 1/2 tbsp of water
* A small piece of konbu (kelp)
* 2 tbsp of rice vinegar
* 1 tbsp of sugar
* 1 tsp of salt
* 2 avocado
* 6 imitation crab sticks
* 2 tbsp of Japanese mayo
* 1/2 lb of salmon  
# Recette     
* Place 1 cup of sushi rice into a mixing bowl and wash the rice at least 2 times or until the water becomes clear. Then transfer the rice into the rice cooker and add a small piece of kelp along with 3/4 cups plus 2 1/2 tbsp of water. Cook according to your rice cookers instruction.
* Combine 2 tbsp rice vinegar, 1 tbsp sugar, and 1 tsp salt in a medium bowl. Mix until everything is well combined.
* After the rice is cooked, remove the kelp and immediately scoop all the rice into the medium bowl with the vinegar and mix it well using the rice spatula. Make sure to use the cut motion to mix the rice to avoid mashing them. After thats done, cover it with a kitchen towel and let it cool down to room temperature.
* Cut the top of 1 avocado, then slice into the center of the avocado and rotate it along your knife. Then take each half of the avocado and twist. Afterward, take the side with the pit and carefully chop into the pit and twist to remove it. Then, using your hand, remove the peel. Repeat these steps with the other avocado. Dont forget to clean up your work station to give yourself more space. Then, place each half of the avocado facing down and thinly slice them. Once theyre sliced, slowly spread them out. Once thats done, set it aside.
* Remove the wrapper from each crab stick. Then, using your hand, peel the crab sticks vertically to get strings of crab sticks. Once all the crab sticks are peeled, rotate them sideways and chop them into small pieces, then place them in a bowl along with 2 tbsp of Japanese mayo and mix until everything is well mixed.
* Place a sharp knife at an angle and thinly slice against the grain. The thickness of the cut depends on your preference. Just make sure that all the pieces are similar in thickness.
* Grab a piece of seaweed wrap. Using a kitchen scissor, start cutting at the halfway point of seaweed wrap and cut until youre a little bit past the center of the piece. Rotate the piece vertically and start building. Dip your hand in some water to help with the sushi rice. Take a handful of sushi rice and spread it around the upper left hand quadrant of the seaweed wrap. Then carefully place a couple slices of salmon on the top right quadrant. Then place a couple slices of avocado on the bottom right quadrant. And finish it off with a couple of tsp of crab salad on the bottom left quadrant. Then, fold the top right quadrant into the bottom right quadrant, then continue by folding it into the bottom left quadrant. Well finish off the folding by folding the top left quadrant onto the rest of the sandwich. Afterward, place a piece of plastic wrap on top, cut it half, add a couple pieces of ginger and wasabi, and there you have it.

                    
Le résultat doit être un extrait de code de démarque formaté selon le schéma suivant, incluant les caractères "```json" and "```" :
json
{
        "cuisine_type": string  // Quel est le type de cuisine de la recette ? Réponse en 1 mot maximum en minuscule
        "preparation_time": integer  // De combien de temps en minutes ai-je besoin pour préparer la recette ? Répondez avec un nombre entier, ou nul si inconnu
        "difficulty": string  // À quel point cette recette est-elle difficile ? Répondez avec l'une de ces valeurs : facile, normal, difficile, très difficile
        "ingredients": string  // Donnez-moi une liste d'ingrédients séparés par des virgules en minuscules ou vide si inconnu
}

                    
======RESPONSE
json
{
        "cuisine_type": "japanese",
        "preparation_time": 30,
        "difficulty": "easy",
        "ingredients": "sushi rice, water, konbu, rice vinegar, sugar, salt, avocado, imitation crab sticks, japanese mayo, salmon"
}

Ça à l'air bon. Il semble que notre invite OpenAI soit capable de renvoyer des informations utiles. Exécutons toute la classe d'analyse depuis le terminal :

set a = ##class(yummy.analysis.SimpleOpenAI).%New(##class(yummy.data.Recipe).%OpenId(12))
do a.Run()
zwrite a

USER>zwrite a
a=37@yummy.analysis.SimpleOpenAI  ; <OREF>
+----------------- general information ---------------
|      oref value: 37
|      class name: yummy.analysis.SimpleOpenAI
| reference count: 2
+----------------- attribute values ------------------
|        CuisineType = "japanese"
|         Difficulty = "easy"
|        Ingredients = "sushi rice, water, konbu, rice vinegar, sugar, salt, avocado, imitation crab sticks, japanese mayo, salmon"
|    PreparationTime = 30
|             Reason = "It seems to be a japanese recipe!. You don't need too much time to prepare it"
|              Score = 3
+----------------- swizzled references ---------------
|           i%Recipe = ""
|           r%Recipe = "30@yummy.data.Recipe"
+-----------------------------------------------------

## Analyser toutes les recettes ! Naturellement, vous souhaitez exécuter l’analyse sur toutes les recettes que nous avons chargées.

Vous pouvez analyser une gamme d’identifiants de recettes de cette façon :

USER>do ##class(yummy.Utils).AnalyzeRange(1,10)
> Recipe 1 (1.755185s)
> Recipe 2 (2.559526s)
> Recipe 3 (1.556895s)
> Recipe 4 (1.720246s)
> Recipe 5 (1.689123s)
> Recipe 6 (2.404745s)
> Recipe 7 (1.538208s)
> Recipe 8 (1.33001s)
> Recipe 9 (1.49972s)
> Recipe 10 (1.425612s)

Après cela, regardez à nouveau votre tableau de recettes et vérifiez les résultats.

select * from yummy_data.Recipe

Je pense que je pourrais essayer la pizza à la courge poivrée ou le kimchi coréen au tofu et au porc :). De toute façon, je devrai vérifier à la maison :)

Notes finales

Vous pouvez trouver l'exemple complet sur https://github.com/isc-afuentes/recipe-inspector

Avec cet exemple simple, nous avons appris à utiliser les techniques LLM pour ajouter des fonctionnalités ou analyser certaines parties de vos données dans InterSystems IRIS.

Avec ce point de départ, vous pourriez penser à :

• Utiliser InterSystems BI pour explorer et parcourir vos données à l'aide de cubes et de tableaux de bord.
• Créer une application Web et fournir une interface utilisateur (par exemple Angular) pour cela, vous pouvez exploiter des packages tels que RESTForms2 pour générer automatiquement des API REST pour vos classes persistantes.
• Et pourquoi garder en base l'information indiquant les recettes que vous aimez et celles que vous n'aimez pas, puis d'essayer de déterminer si une nouvelle recette vous plaira ? Vous pourriez essayer une approche IntegratedML, ou même une approche LLM fournissant des exemples de données et construisant un cas d'utilisation RAG (Retrieval Augmented Generation).

Quelles autres choses pourriez-vous essayer ? Laissez-moi savoir ce que vous pensez!

Je pense que c'est une façon plutôt intéressante d'installer un webterminal dans un environnement où j'avais accès au Management Portal / VSCode, mais je n'avais pas d'accès au terminal.
zpm était déjà présent. Sinon vous pourriez l'ajouter dans la même classe.

1. Créez la classe suivante
2. Compilez. Cela prendra un certain temps, puis vous verrez le résultat de zpm !
3. Vous pouvez maintenant ouvrir le webterminal en ouvrant http://votre-hôte/terminal/

Avez-vous déjà modifié des fichiers dans VS Code, mais avez-vous dû vérifier une valeur globale ou exécuter quelques commandes ObjectScript ? C’est désormais possible, sans aucune configuration requise ! Si vous disposez de l'extension vscode-objectscript version 2.10.0 ou ultérieure et que vous êtes connecté à InterSystems IRIS 2023.2 ou version ultérieure, vous pouvez ouvrir maintenant une connexion de terminal à votre serveur, quel que soit l'endroit où il se trouve.

Il existe trois manières d'ouvrir ce nouveau terminal :

Salut tout le monde,

Quand une publication de la communauté des développeurs n'est pas une publication de la communauté des développeurs ?

Quand il ne s'agit que de quelques phrases enroulées autour d'un lien vers la documentation InterSystems !

Et quelle meilleure façon de terminer 2021 qu’en vous parlant de quelque chose de cool disponible depuis la v2020.3 ? Alors que le ballon tombe à Times Square, détendez-vous avec ceci :

Repeating Previous Commands

Je pense que cela vous apportera de la joie ! Publiez vos alias préférés ci-dessous. Bonne année!

Bonjour à tous,

je souhaite pouvoir lancer le terminal IRIS sans avoir à saisir de nom d'utilisateur ni de mot de passe.

Pour bien comprendre :

• IRIS est installé directement sur une machine Windows
• Lorsque j'utilise mon compte de domaine en me connectant en RDP lorsque je lance le terminal il s'exécute sans me demander de log de connexion. 
  • Je sais que cela fonctionne car le compte est aussi créé dans IRIS avec le même Nom
• Un utilisateur Windows local a été créé, c'est avec ce compte que je veux ouvrir le terminal.

Bonjour,

Nous voulons créer une CD pour InterSystems. Nous avons créé un script IRIS qui permet de compiler automatiquement les fichiers .cls dans les bons namespaces et pour exécuter ce script, nous faisons la commande: iristerm /console=cn_ap:IRIS .\import.scr'

Cependant, cela va nous ouvrir un terminal IRIS dans une nouvelle fenêtre (GUI). Le problème, c'est que nous passons par un user SSH, en exécutant la commande : 

ssh user@hostname 'E: && iristerm /console=cn_ap:IRIS .\import.scr'

Création et utilisation des nouvelles extensions SDA pour le stockage d'éléments de données personnalisés

Dans HSCore 15.01, il existe une nouvelle façon de stocker les éléments de données personnalisés.  HealthShare peut désormais utiliser des extensions personnalisées pour de nombreux éléments SDA.

Cet article a pour but de :

1. Montrer comment configurer votre système pour utiliser les extensions SDA.
2. Créer une nouvelle propriété d'extension SDA
3. Utiliser la nouvelle propriété d'extension SDA dans les transactions HL7
4. Interagir avec les nouvelles données
5. Montrer la nouvelle extension SDA utilisée dans une personnalisation du Rapport de résumé du patient (Patient Summary Report).

<td>
   
</td>

Note: Pour cet article, je me sers de build :
HS-2016.1.1.108.0-hscore15.01_hsaa15_hspi15_hsviewer15.01_linkage15-b2136-win_x64
J'ai également créé le système en utilisant “d ##class(HS.Util.Installer).InstallBusDemo()”

Configurez votre système pour les extensions SDA

Cette section décrit comment configurer les extensions SDA pour un environnement HSCore 15.01.

Création d'un nouvel espace de noms

Dans le cadre des nouvelles extensions SDA, le nom de l'espace de noms personnalisé doit être HSCUSTOM.

Vous pouvez l'ajouter en allant dans : Management Portal->System Administration->Configuration->System Configuration->Namespaces (Portail de gestion->Administration du système->Configuration->Configuration du système->Espaces de noms).

Étapes pour créer un nouvel espace de noms :

1. Cliquez sur le bouton "Create New Namespace" (créer un nouvel espace de noms).
2. Entrez HSCUSTOM dans le champ “Name of the namespace” (Nom de l'espace de noms) (obligatoire).
3. Sélectionnez le bouton "Create New Database" (Créer une nouvelle base de données)

• Saisissez HSCUSTOM dans le champ "Enter the name of your database" (Entrez le nom de votre base de données).
• Pour le champ “Database directory” (Répertoire de la base de données) :
  1. Cliquez sur le bouton "Browse...".
  2. Créez un nouveau dossier/répertoire, j'ai nommé mon répertoire "HSCUSTOM", il se trouve dans le répertoire “mgr”.
  3. Cliquez sur le bouton “OK”
• Cliquez sur le bouton “Next”

• Acceptez les valeurs par défaut, et cliquez sur le bouton "Next".
• Créez une nouvelle ressource appelée %DB_HSCUSTOM et octroyez-lui des droits de lecture et d'écriture
• Cliquez sur le bouton "Finish" (terminer).

4.  De retour à l'écran "New Namespace" (nouvel espace de noms), cliquez sur le bouton "Save" (enregistrer).

Cette procédure a pour effet de créer un nouvel espace de noms HSCUSTOM avec tous les mappings par défaut.

Exportation du paquet HS.Local

Une des choses que nous devons faire est de copier les classes et le code de la base de données HSLIB vers la base de données HSCUSTOM.

Vous pouvez le faire de plusieurs façons.  Je vais vous parler de la façon de le faire à partir de Studio ou de Terminal.

Exportation à partir de Studio :

1. Connectez-vous à Studio
2. Changez l'espace de noms en espace de noms HSLIB (remarque : ceci peut être fait à partir de n'importe quel espace de noms qui a un paquetage HS mappé à HSLIB)
3. Allez dans le menu "Tools->Export" (outils - exportation).
4. Cliquez sur le bouton "Add" (ajouter)
5. Sélectionnez le dossier HS/Local, sélectionnez tout et cliquez sur le bouton "Open" (ouvrir).
6. Cela va tout sélectionner
7. Sélectionnez un fichier local ou distant pour exporter ces classes
   • Dans cet exemple, j'ai nommé le fichier "HSLocal.xml"

      8.  Cliquez sur le bouton "OK". 

Exportation à partir d'une session Terminal :

1. Connectez-vous à Terminal
2. Changez l'espace de noms en espace de noms HSLIB ( remarque : ceci peut être fait à partir de n'importe quel espace de noms qui a un paquetage HS mappé à HSLIB )
3. HSLIB>d $system.OBJ.Export("HS.Local.*.cls","C:\Intersystems\Export\HSLocal.xml")

Ajoutez une nouvelle cartographie de paquet

Le paquet "HS.Local" doit être référencé à partir du nouvel espace de noms HSCUSTOM.  Lorsque HSCUSTOM sera créé, "HS" sera mappé vers HSLIB.  Vous devrez ajouter "HS.Local" à l'espace de noms HSCUSTOM, car il est actuellement pointé vers HSLIB.

Vous pouvez le faire manuellement via le Management Portal (Portail de gestion) ou de manière programmatique.

Management Portal (Portail de gestion) :

1. Allez dans le Portail de gestion->Administration du système->Configuration->Configuration du système->Espaces de noms.
2. Recherchez HSCUSTOM dans la colonne des espaces de noms et sélectionnez le lien "Package Mapping".
3. Cliquez sur le bouton "New"
4. Sélectionnez HSCUSTOM dans le menu déroulant "Pakage Database Location" (location de la base de données de paquet)
5. Sélectionnez le bouton radio "Specify a new package” (Spécifier un nouveau paquet).
6. Entrez HS.Local dans le champ "Packaga Name" (Nom du paquet)

         7. Cliquez sur le bouton "OK"

Par programmation :

Vous pouvez créer du code pour ajouter ce mappage à un espace de noms.

1. Déplacez-vous vers l'espace de noms %SYS
   • HSCUSTOM> ZN “%SYS”
2. Définissez la propriété de la base de données
   • %SYS> set tProperties("Database")="HSCUSTOM"
3. Créez le mappage
   • %SYS>w ##class(Config.MapPackages).Create("HSCUSTOM","HS.Local",.tProperties)

Remarque:  Vous devrez le faire pour chaque espace de noms et instance qui est un espace de noms HealthShare, à l'exception des espaces de noms Library.   Il est important d'avoir ces mappages pour que les autres espaces de noms puissent accéder au code HSCUSTOM à utiliser dans leur traitement, comme les applications telles que Patient Index et Health Insight.

Importation du paquet HS.Local

Maintenant que les paquets HS.Local pointent vers HSCUSTOM, vous pouvez déplacer les classes que nous avons exportées précédemment dans l'espace de noms HSCUSTOM.

Vous pouvez le faire de plusieurs façons.  Je vais vous parler de la façon de le faire à partir de Studio ou de Terminal.

Importation à partir de Studio:

1. Connectez-vous à Studio
2. Changez l'espace de noms en espace de noms HSCUSTOM.
3. Allez dans le menu Tools->Import Local (Outils->Importer Local).
4. Sélectionnez le fichier que vous avez exporté
5. Appuyez sur le bouton "Open" (ouvrir).
6. Vous devriez voir toutes les classes cochées et l'option "Compile Imported Items" (Compiler les éléments importés) cochée.

     7.  Cliquez sur le bouton "OK". 

Importation à partir d'une session Terminal :

1. Connectez-vous à Terminal
2. Changer l'espace de noms en HSCUSTOM
3. HSLIB>d $system.OBJ.Load("C:\Intersystems\Export\HSLocal.xml",”ck”)

Résumé

Nous avons maintenant l'infrastructure pour les nouvelles extensions SDA personnalisées de HSCore 15.01.  Nous avons les classes HS.Local définies dans une nouvelle base de données HSCUSTOM et nous avons tous les espaces de noms qui pointent vers la localisation appropriée.

Si vous avez plus d'une instance de cache, l'espace de noms HSCUSTOM et les mappages HS.Local doivent se trouver sur chaque instance qui exécute HealthShare.

Création d'une nouvelle extension SDA personnalisée

Maintenant que nous avons les éléments nécessaires, nous allons créer une nouvelle propriété personnalisée.

Nous allons commencer par créer une propriété personnalisée pour le Patient SDA (SDA du patient).

En regardant les annotations HL7, il semble que "Veterans Military Status" (statut militaire des vétérans), qui est le PID, pièce 27, n'est pas utilisé dans SDA, alors essayons de créer ceci comme notre extension SDA personnalisée.

Comme la pièce PID 27 est un champ d'entrée codé, nous allons montrer que les nouvelles extensions SDA personnalisées sont plus que la paire nom/valeur précédente, il s'agit maintenant d'un type de données plus complexe.  Dans cet exemple, nous créons un type de propriété personnalisé.

Edit HS.Local.SDA3.PatientExtension.cls

Nous devons ajouter la nouvelle propriété à HS.Local.SDA3.PatientExtension.cls

1. Connectez-vous à Studio
2. Changez l'espace de noms en HSCUSTOM
3. Modifiez HS.Local.SDA3.PatientExtension.cls
4. Ajouter une classe personnalisée "Custom Class"
   • Cette classe représente un type de données complexe qui aura :
     • Champ de code
     • Description du Champ

    5.   Ajoutez la propriété VeteransMilitaryStatus

• Propriété VeteransMilitaryStatus En tant que CUSTOM.SDA3.CodeTableDetail.VeteransMilitaryStatus;

      6.  Compilez HS.Local.SDA3.PatientExtension.cls

      7.  Compilez la classe HS.SDA3.Patient

      8.  Compilez la classe HS.Registry.Patient

Cette propriété est maintenant disponible pour être ajoutée/modifiée/supprimée à partir du streamlet SDA.

Utiliser la nouvelle propriété d'extension SDA dans les transactions HL7

Avant de pouvoir utiliser la propriété d'extension SDA, nous devons créer une nouvelle classe personnalisée qui étendra la classe HS.Gateway.HL7.HL7ToSDA3.  Ce code sera exécuté sur la passerelle EDGE.

Voici un exemple de code de la nouvelle classe personnalisée :

Class CUSTOM.Gateway.HL7.HL7ToSDA3 Extends HS.Gateway.HL7.HL7ToSDA3 [ Not ProcedureBlock ]
{

/// Méthode de rappel pour le traitement personnalisé du streamlet Patient
ClassMethod OnPatient()
{
                do ..write(cr_"<Extension>")
                set tVMSCode = $$$xml($g(^||d(s,27,1)))
                set tVMSDescription = $$$xml($g(^||d(s,27,2)))
                if tVMSCode'="" {
                                do ..write(cr_"<VeteransMilitaryStatus>")
                                do ..write(cr_""_tVMSCode_"")
                                do ..write(cr_"<Description>"_tVMSDescription_"</Description>")
                                do ..write(cr_"</VeteransMilitaryStatus>")
                }             
                do ..write(cr_"</Extension>")
                Quit
}

Mise à jour de Production de Edge Gateway Ensemble.

Modifiez l'opération : HS.Gateway.HL7.InboundProcess et changez le paramètre "HL7ToSDA3Class" pour utiliser la nouvelle classe que nous venons de créer.

Cliquez sur le bouton "Apply" (appliquer) pour enregistrer les modifications.

Nous utilisons le message HL7 suivant :  (Notez que la pièce PID 27 a une valeur de "V^Veteran")

MSH|^~\&||HC6|||||ADT^A04|||2.5EVN|A04|20160711094500PID|||STM123^^^HC6^MR||Bolton^George||19271014|M|||1 Memorial Drive^^Cambridge^MA^02142||||||||028345081||||||||V^Veteran

Nous traitons maintenant ce HL7 sur une passerelle Edge Gateway.

Maintenant si nous regardons la trace, nous pouvons voir nos données dans le <Patient> SDA.

Interaction avec les nouvelles données

Maintenant que nous avons les données stockées dans SDA qui se trouvent sur le Edge (et le Registry (Registre)), nous pouvons les examiner de plusieurs façons.

Sur l'Edge, je peux exécuter le code suivant :

ClassMethod ListVeteransStatus()
{
                #dim tPatient as HS.SDA3.Patient            
                set sql="Select ID from HS_SDA3_Streamlet.Patient"
                set statement = ##class(%SQL.Statement).%New()
                set tSC = statement.%Prepare(sql)
                quit:$$$ISERR(tSC) tSC
                set result = statement.%Execute()
                while result.%Next() {
                      set tStreamletID = result.ID
                      set tSC = ##class(HS.SDA3.Container).LoadSDAObject(tStreamletID,.tPatient)
                      w !,tPatient.Name.GivenName_" "_tPatient.Name.FamilyName
                      w ": Veteran Status = "_tPatient.Extension.VeteransMilitaryStatus.Description
                }             
                Quit
}

Et j'obtiens ce qui suit :

On peut voir que nous utilisons la propriété "Extension.VeteransMilitaryStatus.Description" pour afficher les nouvelles données personnalisées.

Sur HSREGISTRY, nous pouvons consulter les éléments suivants :

HSREGISTRY>s oPat=##class(HS.Registry.Patient).%OpenId(1)HSREGISTRY>w oPat.Extension.VeteransMilitaryStatus.CodeVHSREGISTRY>w oPat.Extension.VeteransMilitaryStatus.DescriptionVeteran

Pour les informations sur les patients, nous pouvons voir que la propriété personnalisée est disponible non seulement dans le SDA qui est stocké sur la passerelle Edge Gateway, mais aussi dans le registre des patients "Patient Registry".

Utilisation d'un SDA personnalisé dans une personnalisation du rapport sommaire du patient "Patient Summary Report".

Ceci n'est qu'un aperçu rapide de la manière dont vous pouvez utiliser la nouvelle extension SDA dans un code personnalisé.

Dans cet exemple, nous allons créer un rapport sommaire du patient "Patient Summary Report".

J'ai créé une classe CUSTOM.Reports.Patient.Summary, je peux simplement ajouter un nouvel élément à afficher en utilisant le code suivant :

<item field="Extension/VeteransMilitaryStatus/Description" >
        <caption value="Military Status" style="padding:5px;"/>
</item>

Now, when we bring up the patient and view Patient Summary Reports we can see the following:

Summary

This article showed how to set up the environment to use the new SDA extensions.  It showed how to populate the new property using HL7.  We showed how to access the data.  In this case, we were using patient data, so we were able to access it from both the Edge gateway and Registry.  We also used this new information in an example using a custom patient summary report.  Now that this data is in the SDA, it can be used by Health Insight and Patient Index as well as any other place that uses SDA.

Salut les Devs !

Pour moi, l'une des choses les plus pénibles à propos d'ObjectScript est de taper ##class(Class).Method() pour appeler une méthode de classe dans le code ou dans un terminal. J'ai même soumis une idée pour le simplifier en ObjectScript.

Mais! Il y a une nouvelle fonctionnalité dans VSCode ObjectScript qui vient d'être introduite dans le plugin - Copy Invocation !

Passez simplement le curseur sur le lien Copy Invocation au-dessus de chaque méthode de classe dans un code, cliquez dessus et l'invocation est copiée dans le buffer:

Collez-le où vous voulez qu'il s'exécute !

Comme nous le savons tous, Caché est une excellente base de données qui accomplit de nombreuses tâches en son sein. Cependant, que faites-vous lorsque vous avez besoin d'accéder à une base de données externe ? Une façon de le faire est d'utiliser la passerelle Caché SQL Gateway via JDBC. Dans cet article, mon objectif est de répondre aux questions suivantes pour vous aider à vous familiariser avec cette technologie et à déboguer certains problèmes courants.

Plan de travail

• Quels sont les paramètres de connexion dont vous avez besoin pour vous connecter à une base de données distante ?
• Qu'est-ce que la passerelle JDBC Gateway et le service de passerelle Java Gateway Service dans Ensemble ?
• Quels outils et méthodes sont disponibles pour déboguer les problèmes ?
• Quels sont les types de problèmes courants et les approches pour les résoudre ?

Avant de se plonger dans ces questions, discutons rapidement de l'architecture de la passerelle JDBC SQL Gateway. Pour simplifier, vous pouvez considérer que l'architecture est la suivante : Cache établit une connexion TCP avec un processus Java, appelé processus de passerelle. Le processus de passerelle se connecte ensuite à une base de données distante, telle que Caché, Oracle ou SQL Server, en utilisant le pilote spécifié pour cette base de données. Pour plus d'informations sur l'architecture de la passerelle SQL Gateway, veuillez consulter la documentation sur Utilisation de la passerelle Caché SQL Gateway.

Paramètres de connexion

Lorsque vous vous connectez à une base de données distante, vous devez fournir les paramètres suivants :

• nom d'utilisateur
• mot de passe
• nom du pilote
• URL
• chemin de classe

Connexion à la base de données Caché

Par exemple, si vous avez besoin de vous connecter à une instance de Caché en utilisant la passerelle SQL Gateway via JDBC, vous devez naviguer vers [System Administration] -> [Configuration] -> [Connectivity] -> [SQL Gateway Connections] dans le portail de gestion du système (SMP). Cliquez ensuite sur "Créer une nouvelle connexion" et spécifiez "JDBC" comme type de connexion.

Lors de la connexion à un système Caché, le nom du pilote doit toujours être com.intersys.jdbc.CacheDriver, comme indiqué dans la capture d'écran. Si vous vous connectez à une base de données tierce, vous devrez utiliser un nom de pilote différent (voir Connexion à des bases de données tierces ci-dessous).

Lorsque vous vous connectez aux bases de données Caché, vous n'avez pas besoin de spécifier un chemin de classe car le fichier JAR est téléchargé automatiquement.

Le paramètre URL varie également en fonction de la base de données à laquelle vous vous connectez. Pour les bases de données Caché, vous devez utiliser une URL de la forme suivante

jdbc:Cache://[server_address]:[superserver_port]/[namespace]

Connexion à des bases de données tierces

Une base de données tierce courante est Oracle. Un exemple de configuration est présenté ci-dessous.

Comme vous pouvez le constater, le nom du pilote et l'URL ont des caractéristiques différentes de celles que nous avons utilisées pour la connexion précédente. En outre, j'ai spécifié un chemin de classe dans cet exemple, car je dois utiliser le pilote d'Oracle pour me connecter à leur base de données.

Comme vous pouvez l'imaginer, SQL Server utilise différents modèles d'URL et de noms de pilotes.

Vous pouvez tester si les valeurs sont valides en cliquant sur le bouton " Testez la connexion ". Pour créer la connexion, cliquez sur "Enregistrer".

JDBC Gateway vs le service Java Gateway Business Service

Tout d'abord, la passerelle JDBC et le service de passerelle Java sont complètement indépendants l'un de l'autre. La passerelle JDBC peut être utilisée sur tous les systèmes basés sur Caché, alors que le service de passerelle Java n'existe que dans le cadre d'Ensemble. En outre, le service de passerelle Java utilise un processus différent de celui utilisé par la passerelle JDBC. Pour plus de détails sur le service commercial de passerelle Java, veuillez consulter Le service commercial de passerelle Java.

Méthodes et outils

Vous trouverez ci-dessous 5 outils et méthodes couramment utilisés pour résoudre des problèmes avec la passerelle JDBC SQL Gateway. Je vais d'abord parler de ces outils et vous montrer quelques exemples de leur utilisation dans la section suivante.

1. Journaux

A. Journal du pilote et journal de la passerelle

Lorsque vous utilisez la passerelle JDBC, le journal correspondant est le journal de la passerelle JDBC SQL. Comme nous l'avons vu précédemment, la passerelle JDBC est utilisée lorsque Caché doit accéder à des bases de données externes, ce qui signifie que Caché est le client. Le journal du pilote, par contre, correspond à l'utilisation du pilote JDBC d'InterSystems pour accéder à une base de données Caché à partir d'une application externe, ce qui signifie que Caché est le serveur. Si vous avez une connexion d'une base de données Caché à une autre base de données Caché, les deux types de journaux peuvent être utiles.

Dans notre documentation la section relative à l'activation du journal du pilote est intitulée "Activation de la journalisation pour JDBC", et la section relative à l'activation du journal de la passerelle est intitulée "Activation de la journalisation pour la passerelle SQL JDBC".

Même si les deux journaux comportent le mot "JDBC", ils sont totalement indépendants. L'objet de cet article est la passerelle JDBC, c'est pourquoi j'aborderai plus en détail le journal de la passerelle. Pour plus d'informations sur le journal du pilote, veuillez vous reporter à la section Activation du journal du pilote.

B. Activation du journal du pilote

Si vous utilisez la passerelle Caché JDBC SQL Gateway, vous devez effectuer les opérations suivantes pour activer la journalisation : dans le portail de gestion, allez dans [System Administration] > [Configuration] > [Connectivity] > [JDBC Gateway Settings]. Indiquez une valeur pour le journal de la passerelle JDBC. Ce doit être le chemin complet et le nom d'un fichier journal (par exemple, /tmp/jdbcGateway.log). Le fichier sera automatiquement créé s'il n'existe pas, mais le répertoire ne le sera pas. Caché va démarrer la passerelle JDBC SQL Gateway avec journalisation pour vous.

Si vous utilisez le service commercial Java Gateway dans Ensemble, veuillez consulter Activation de la journalisation de la passerelle Java Gateway dans Ensemble pour savoir comment activer la journalisation.

C. Analyse du journal d'une passerelle

Maintenant que vous avez collecté un journal de passerelle, vous vous posez peut-être la question suivante : quelle est la structure du journal et comment le lire ? Bonne question ! Je vais vous fournir ici quelques informations de base pour vous aider à démarrer. Malheureusement, il n'est pas toujours possible d'interpréter complètement le journal sans avoir accès au code source. Pour les situations complexes, n'hésitez pas à contacter le WRC (Centre de réponse global d'InterSystems) !

Pour démystifier la structure du journal, rappelez-vous qu'il s'agit toujours d'un morceau de données suivi d'une description de ce qu'il fait. Par exemple, voyez cette image avec une coloration syntaxique de base :

Afin de comprendre ce que Received signifie ici, vous devez vous rappeler que le journal de la passerelle enregistre les interactions entre la passerelle et la base de données descendante. Ainsi, Received signifie que la passerelle a reçu l'information de Caché/Ensemble. Dans l'exemple ci-dessus, la passerelle a reçu le texte d'une requête SELECT. Les significations des différentes valeurs de msgId peuvent être trouvées dans le code interne. Le 33 que nous voyons ici signifie " Preparer l'instruction ".

Le journal lui-même fournit également des informations sur le pilote, ce qui est intéressant à vérifier lors du débogage des problèmes. Voici un exemple,

Comme nous pouvons le voir, le Driver Name est com.intersys.jdbc.CacheDriver, ce qui est le nom du pilote utilisé pour se connecter au processus de passerelle. Le Jar File Name est cachejdbc.jar, ce qui est le nom du fichier jar situé dans <cache_install_directory>\lib\.

2. Trouver le processus de passerelle

Pour trouver le processus de passerelle, vous pouvez exécuter la commande ps. Par exemple,

ps -ef | grep java

Cette commande ps affiche des informations sur le processus Java, notamment le numéro de port, le fichier jar, le fichier journal, l'ID du processus Java et la commande qui a lancé le processus Java.

Voici un exemple du résultat de la commande :

mlimbpr15:~ mli$ ps -ef | grep java
17182 45402 26852   0 12:12PM ??         0:00.00 sh -c java -Xrs -classpath /Applications/Cache20151/lib/cachegateway.jar:/Applications/Cache20151/lib/cachejdbc.jar com.intersys.gateway.JavaGateway 62972 /Applications/Cache20151/mgr/JDBC.log 2>&1
17182 45403 45402   0 12:12PM ??         0:00.22 /usr/bin/java -Xrs -classpath /Applications/Cache20151/lib/cachegateway.jar:/Applications/Cache20151/lib/cachejdbc.jar com.intersys.gateway.JavaGateway 62972 /Applications/Cache20151/mgr/JDBC.log
502 45412 45365   0 12:12PM ttys000    0:00.00 grep java

Dans Windows, vous pouvez consulter le gestionnaire des tâches pour trouver des informations sur le processus de passerelle.

3. Lancement et arrêt de la passerelle

Il y a deux façons de lancer et d'arrêter la passerelle :

1. Par le biais du SMP
2. Utilisation du terminal

A. Par le biais du SMP

Vous pouvez lancer et arrêter la passerelle dans le SMP en accédant à [System Administration] -> [Configuration] -> [Connectivity] -> [JDBC Gateway Server].

B. Utilisation du terminal

Sur les machines Unix, vous pouvez également démarrer la passerelle depuis le terminal. Comme nous l'avons vu dans la section précédente, le résultat de ps -ef | grep java contient la commande qui a démarré le processus Java, qui dans l'exemple ci-dessus est le suivant:

java -Xrs -classpath /Applications/Cache20151/lib/cachegateway.jar:/Applications/Cache20151/lib/cachejdbc.jar com.intersys.gateway.JavaGateway 62972 /Applications/Cache20151/mgr/JDBC.log

Pour arrêter la passerelle depuis le terminal, vous pouvez tuer le processus. L'ID du processus Java est le deuxième chiffre de la ligne qui contient la commande ci-dessus, dans l'exemple ci-dessus c'est 45402. Ainsi, pour arrêter la passerelle, vous pouvez exécuter :

kill 45402

4. Écrire un programme Java

Exécuter un programme Java pour se connecter à une base de données descendante est un excellent moyen de tester la connexion, de vérifier la requête et d'aider à isoler la cause d'un problème donné. Je joins un exemple de programme Java qui établit une connexion avec SQL Server et imprime une liste de tous les tableaux. J'expliquerai pourquoi cela peut être utile dans la section suivante.

import java.sql.*;
import java.sql.Date;
import java.util.*;
import java.lang.reflect.Method;
import java.io.InputStream;
import java.io.ByteArrayInputStream;
import java.math.BigDecimal;
import javax.sql.*;

// Auteur : Vicky Li
// Ce programme établit une connexion avec le serveur SQL et récupère tous les tableaux. Le résultat est une liste de tableaux.

public class TestConnection {
    public static void main(String[] args) {
        try {
            Class.forName("com.microsoft.sqlserver.jdbc.SQLServerDriver");
            //please replace url, username, and password with the correct parameters
            Connection conn = DriverManager.getConnection(url,username,password);

            System.out.println("connected");

            DatabaseMetaData meta = conn.getMetaData();
            ResultSet res = meta.getTables(null, null, null, new String[] {"TABLE"});
            System.out.println("List of tables: ");
            while (res.next()) {
                System.out.println(
                    "   " + res.getString("TABLE_CAT") +
                    ", " + res.getString("TABLE_SCHEM") +
                    ", " + res.getString("TABLE_NAME") +
                    ", " + res.getString("TABLE_TYPE")
                );
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

Pour exécuter ce programme Java (ou tout autre programme Java), vous devez d'abord compiler le fichier .java, qui dans notre cas s'appelle TestConnection.java. Ensuite, un nouveau fichier sera généré au même endroit, que vous pourrez ensuite exécuter avec la commande suivante sur un système UNIX :

java -cp "<path to driver>/sqljdbc4.jar:lib/*:." TestConnection

Dans Windows, vous pouvez exécuter la commande suivante :

java -cp "<path to driver>/sqljdbc4.jar;lib/*;." TestConnection

5. Suivi d'une trace de jstack

Comme son nom l'indique, jstack imprime l'arborescence des appels de procédure Java. Cet outil peut devenir pratique lorsque vous avez besoin de mieux comprendre ce que fait le processus Java. Par exemple, si vous voyez le processus de la passerelle s'accrocher à un certain message dans le journal des passerelles, vous pourriez vouloir recueillir une trace jstack. Je tiens à souligner que jstack est un outil de bas niveau qui ne devrait être utilisé que lorsque d'autres méthodes, comme l'analyse du journal des passerelles, ne résolvent pas le problème.

Avant de collecter une trace jstack, vous devez vous assurer que le JDK est installé. Voici la commande pour collecter une trace jstack :

jstack -F <pid> > /<path to file>/jstack.txt

où le pid est l'ID du processus de la passerelle, qui peut être obtenu en exécutant la commande ps, telle que ps -ef | grep java. Pour plus d'informations sur la façon de trouver le pid, veuillez consulter Lancement et arrêt de la passerelle.

Maintenant, voici quelques considérations spéciales pour les machines Red Hat. Dans le passé, il y a eu des problèmes pour attacher jstack au processus de la passerelle JDBC (ainsi qu'au processus du service métier de la passerelle Java lancé par Ensemble) sur certaines versions de Red Hat, donc la meilleure façon de collecter une trace jstack sur Red Hat est de lancer le processus de la passerelle manuellement. Pour les instructions, veuillez consulter Collecter une trace jstack sur Red Hat.

Types courants de problèmes et approches pour les résoudre

1. Problème : Java n'est pas installé correctement

Dans cette situation, vérifiez la version de Java et les variables d'environnement.

Pour vérifier la version de Java, vous pouvez exécuter la commande suivante à partir d'un terminal :

java -version

Si vous obtenez l'erreur java : Command not found, cela signifie que le processus Cache ne peut pas trouver l'emplacement des exécutables Java. Cela peut généralement être résolu en plaçant les exécutables Java dans le PATH. Si vous rencontrez des problèmes, n'hésitez pas à contacter le WRC (Centre de réponse global).

2. Problème : échec de la connexion

Un bon diagnostic des échecs de connexion est la vérification du lancement du processus de la passerelle. Vous pouvez le faire en vérifiant le journal de la passerelle ou le processus de la passerelle. Sur les versions modernes, vous pouvez également aller sur le SMP et visiter [System Administration] -> [Configuration] -> [Connectivity] -> [JDBC Gateway Server], et vérifier si la page affiche "JDBC Gateway is running".

Si le processus de passerelle ne s'exécute pas, il est probable que Java n'est pas installé correctement ou que vous utilisez le mauvais port ; si le processus de passerelle s'exécute, il est probable que les paramètres de connexion sont incorrects.

Dans le premier cas, veuillez vous reporter à la section précédente et vérifiez le numéro de port. Je discuterai plus en détail de la deuxième situation ici.

Il est de la responsabilité du client d'utiliser les paramètres de connexion corrects :

• nom d'utilisateur
• mot de passe
• nom du pilote
• URL
• chemin de classe

Vous pouvez vérifier si vous avez les bons paramètres de l'une des trois façons suivantes :

• Utilisez le bouton "Test Connection" après avoir sélectionné un nom de connexion dans [System Administration] -> [Configuration] -> [Connectivity] -> [SQL Gateway Connections]. Note : pour les systèmes modernes, "Test Connection" donne des messages d'erreur utiles ; pour les systèmes plus anciens, le JDBC gateway log est nécessaire pour trouver plus d'informations sur l'échec.

• Exécutez la ligne de commande suivante depuis un terminal Caché pour tester la connexion :

    d $SYSTEM.SQLGateway.TestConnection(<connection name>)
  

• Exécutez un programme Java pour établir une connexion. Le programme que vous écrivez peut être similaire à l' example dont nous avons parlé précédemment.

3. Problème : décalage entre la façon dont Caché comprend JDBC et la façon dont la base de données distante comprend JDBC, par exemple :

• problèmes de type de données
• procédure stockée avec des paramètres de sortie
• flux

Pour cette catégorie, il est souvent plus utile de travailler avec le WRC (Centre de réponse global). Voici ce que nous faisons souvent pour déterminer si le problème se situe dans notre code interne ou dans la base de données distante (ou dans le pilote) :

• regarder les journaux et analyser ce qui est envoyé
• reproduire le problème en dehors de Caché en écriture d'un programme java.

Remarque

Le service commercial de la passerelle Java

Le nom de la classe du Service Métier d' Ensemble est EnsLib.JavaGateway.Service, et la classe de l'adaptateur est EnsLib.JavaGateway.ServiceAdapter. La session Ensemble crée d'abord une connexion avec le serveur Java Gateway, qui est un processus Java. L'architecture est similaire à celle de la passerelle JDBC SQL, sauf que le processus Java est géré par l'opération commerciale. Pour plus de détails, veuillez consulter la documentation.

Activation du journal du pilote

Pour activer le journal du pilote, vous devez ajouter un nom de fichier journal à la fin de la chaîne de connexion JDBC. Par exemple, si la chaîne de connexion originale ressemble à czci :

jdbc:Cache://127.0.0.1:1972/USER

Pour activer la journalisation, ajoutez un fichier (jdbc.log) à la fin de la chaîne de connexion, de sorte qu'elle ressemble à ceci :

jdbc:Cache://127.0.0.1:1972/USER/jdbc.log

Le fichier journal sera enregistré dans le répertoire de travail de l'application Java.

Activation de la journalisation de la passerelle Java dans Ensemble

Si vous utilisez le service métier de la passerelle Java dans Ensemble pour accéder à une autre base de données, vous devez, pour activer la journalisation, spécifier le chemin et le nom d'un fichier journal (par exemple, /tmp/javaGateway.log) dans le champ "Log File" du service de la passerelle Java. Veuillez noter que le chemin d'accès doit exister.

N'oubliez pas que la connexion de la passerelle Java utilisée par la production Ensemble est distincte des connexions utilisées par les tableaux liés ou d'autres productions. Ainsi, si vous utilisez Ensemble, vous devez collecter le journal dans le service de passerelle Java. Le code qui démarre le service de passerelle Java utilise le paramètre "Log File" dans Ensemble, et n'utilise pas le paramètre dans la passerelle Caché SQL dans le SMP comme décrit précédemment.

Récupération d'une trace jstack sur Red Hat

La clé ici est de lancer le processus de la passerelle manuellement, et la commande pour lancer la passerelle peut être obtenue en exécutant ps -ef | grep java. Vous trouverez ci-dessous les étapes complètes à suivre pour collecter une trace jstack sur Red Hat lors de l'exécution de la passerelle JDBC ou du service métier de la passerelle Java.

1. Assurez-vous que le JDK est installé.

2. Dans un terminal, exécutez ps -ef | grep java. Obtenez les deux informations suivantes à partir du résultat :

   • a. Copiez la commande qui a lancé la passerelle. Cela devrait ressembler à quelque chose comme ça : java -Xrs -classpath /Applications/Cache20151/lib/cachegateway.jar:/Applications/Cache20151/lib/cachejdbc.jar com.intersys.gateway.JavaGateway 62972 /Applications/Cache20151/mgr/JDBC2.log

   • b. Obtenez l'ID du processus Java (pid), qui est le deuxième chiffre de la ligne qui contient la commande ci-dessus.

3. Arrêtez le processus avec kill <pid>.

4. Exécutez la commande que vous avez copiée à l'étape 2.a. pour lancer manuellement un processus de passerelle.

5. Jetez un coup d'oeil au journal de la passerelle (dans notre exemple, il est situé dans /Applications/Cache20151/mgr/JDBC2.log) et assurez-vous que vous voyez des entrées comme >> LOAD_JAVA_CLASS: com.intersys.jdbc.CacheDriver. Cette étape est juste pour vérifier qu'un appel à la passerelle est effectué avec succès.

6. Dans un nouveau terminal, exécutez ps -ef | grep java pour obtenir le pid du processus de la passerelle.

7. Rassemblez une trace jstack : jstack -F <pid> > /tmp/jstack.txt