SOMMAIRE

XPSQL utilitaire

L'utilitaire XPSQL doit impérativement être exécuté sur le serveur où le service XLANSQL est actif et où se trouve le serveur de base de données SQL.
Il permet de créer, modifier ou supprimer la fiche paramètre des fichiers transférés dans une base de données SQL. Il permet en outre de tester la connexion au serveur SQL ainsi que la cohérence de vos descriptions de données dans le dictionnaire avant le transfert, de créer et de transférer les informations vers les tables SQL, d'extraire les informations des tables SQL vers un fichier Harmony.
Il permet également de définir le type de serveur SQL, le nom de la base de données, ainsi que le nombre de décimales variables pour chaque base.
Le fichier paramètre FHSQL.dhfi contient la liste des fichiers à gérer dans la base SQL.
Pour chaque base de données sous SQL, il y a sur le serveur un répertoire correspondant à la base de données sous le répertoire Harmony. Il porte impérativement le nom de la base de données. Il contient :

• Obligatoirement le fichier paramètre Fhsql.dhfi des fichiers sous SQL

• Les dictionnaires de données des fichiers à transférer sous SQL. (sauf dans le cas où un chemin absolu a été défini dans les paramètres des fichiers).

• Les originaux des fichiers à transférer sous SQL.

XPSQL est en fait un zoom sur le fichier FHSQL et permet donc de faire toutes les opérations du zoom sur un fichier (pour le fonctionnement détaillé du zoom voir la documentation en ligne du zoom dans XPSQL).
Dans la suite de ce chapitre nous verrons :

• Les paramètres généraux de XPSQL.

• Tous les paramètres concernant un fichier.

• Le regroupement des fichiers par application.

• Les actions que permet de réaliser XPSQL soit pour un fichier en particulier, soit pour une application complète :

• Audit

  • L'audit pour tester la connexion au serveur SQL et vérifier la cohérence du dictionnaire de données.

  • La création des tables dans SQL.

  • La copie des données vers SQL.

  • L'extraction des données depuis SQL vers un fichier Harmony.

Voir également :
Paramètres généraux de XPSQL.
Paramètres d'un fichier.
Application.
Actions.
Connexion au serveur SQL
Audit.
Création des tables.
Copie des fichiers.
Extraction des fichiers.
Erreurs les plus courantes

Paramètres généraux de XPSQL

Choix du type de serveur
XLANSQL est prévu pour accéder à divers type de serveurs. Le bouton "Serveur SQL" permet de choisir le fournisseur du serveur. Voir les documentations version produit pour les versions supportées. Ce bouton permet aussi, le cas échéant, de mettre en oeuvre les types de connexion https://divalto.atlassian.net/wiki/spaces/PAI/pages/11475812353 (Mars ou autre).
Choix de la base SQL.
Le bouton « Base SQL » permet de choisir la base SQL. Il est grisé lorsqu'une seule base a été configurée dans la table des serveurs.
Pour chaque base de données, il faut sur le serveur sous le répertoire Harmony un répertoire portant le nom de la base de données avec :

• Obligatoirement le fichier paramètre Fhsql.dhfi des fichiers sous SQL. S'il n'existe pas, ce fichier est crée automatiquement à partir du fichier modèle FhsqlDivalto.dhfi.

• Les dictionnaires de données des fichiers à transférer sous SQL. (sauf dans le cas où un chemin absolu a été défini dans les paramètres des fichiers).

• Les originaux des fichiers à transférer sous SQL.

Mettre à jour la liste des fichiers
Ce bouton de la barre des boutons permet d'ajouter les fichiers susceptibles d'être exploités sous SQL dans le Fhsql.dhfi à partir du modèle FhsqlDivalto.dhfi.. Ce choix ne modifie pas les fichiers existants.
Décimales variables.
Harmony permet de définir des nombres de décimales variables pour les valeurs numériques. Par exemple, dans certains pays les montants s'expriment avec trois décimales, en gestion les quantités peuvent s'exprimer avec 0, 1, 2 ou n décimales selon la nature de l'objet.
Diva peut gérer jusque 10 types de décimales variables. Cette définition s'effectue par classe (10 classes en tout). Pour chaque classe on indique le nombre de décimales pour les nombres de cette classe. Dans le dictionnaire de données, lors de la définition d'un champ de nature "Numérique,D" on indique à quelle classe il appartient.
Le bouton "Décimales" de XPSQL permet de paramétrer le nombre de décimales pour chacune des classes dans la base SQL. Ce paramètre est pris en compte lors de la création des tables dans la base SQL.
Attention
Contrairement au fonctionnement avec un fichier Harmony, le nombre de décimales d'une classe est fixe pour une colonne donnée d'une table et sa valeur doit être connue lors de la création des tables.

Open

Paramètres d'un fichier

Le serveur XLANSQL, à l'ouverture d'un fichier sur le serveur SQL charge ses paramètres depuis le fichier FHSQL.dhfi du répertoire correspondant à la base SQL. S'ils n'existent pas ou si l'enregistrement paramètre n'est pas valide, XLANSQL renvoie un code erreur fichier absent.
Dans la fiche paramètre, XLANSQL trouve les informations suivantes :

• Le nom du dictionnaire où se trouve la description du fichier. Par défaut, le dictionnaire est cherché dans le répertoire /Divalto/ « nom de base sql ».

• Le nom du fichier dans le dictionnaire.

• L'application à laquelle appartient le fichier.

• La version des tables dans la base SQL. Celle-ci correspond au numéro de version pris dans le dictionnaire de données au moment de la création des tables.

• L'indicateur de validité de la fiche paramètres.

Open

Application

Dans la fiche paramètres d'un fichier, on indique l'application à laquelle il appartient. Cette information permet de regrouper tous les fichiers d'une application. Les boutons d'action " par application " de l'utilitaire XPSQL permettent d'effectuer les opérations pour une application complète et non plus fichier par fichier. Dans ce cas le paramètre " Valide " de la fiche paramètres indique si ce fichier doit être pris en compte ou non.
Pour les applications Divalto, les paramètres des fichiers de base sont fournis par application. Par défaut, les paramètres ne sont pas valides. Pour un transfert complet d'une application, on se positionnera sur un des fichiers de l'application et on l'activera avec le bouton "Validation/Invalidation". Si l'on décide de faire un transfert partiel des fichiers de l'application dans la base SQL, il suffit de valider les fiches paramètres des fichiers que l'on souhaite transférer.
En cas de mise à jour, le fichier paramètre FHSQL n'est pas copié sur le disque. L'installateur copie le fichier paramètres modèle (FhsqlDivalto) dans le répertoire /divalto/sys. Le bouton "Mettre à jour la liste des fichiers" effectue la mise à jour des fichiers à partir du modèle.

Actions

Les actions que permet d'exécuter XPSQL sont matérialisées par deux barres de boutons situées sur la droite de l'écran. La barre de boutons du haut porte sur le fichier ou les fichiers sélectionnés. La barre de boutons du bas porte sur tous les fichiers " Valides " de l'application de la fiche sélectionnée.

• Lorsqu'une action est en cours, on trouve dans la fiche affichée à l'écran, le libellé de l'action.

• Dans la fiche, une zone de texte enrichie contient l'état d'avancement de l'action ainsi que les erreurs éventuellement détectées.

• XPSQL écrit également les résultats et les erreurs survenues dans le fichier DHOdbcConfigSQL.LOG.

Connexion

Voir la page dédiée

https://divalto.atlassian.net/wiki/spaces/PAI/pages/11475812353

Audit

La fonction d'audit doit être utilisée principalement lors du paramétrage d'un nouveau fichier à transférer dans la base SQL. Cette fonction effectue de nombreuses opérations de test, notamment de connexion à la base et de cohérence de la description du fichier dans le dictionnaire. Elle n'effectue pas de mise à jour de la base de données. On exécutera ce choix fichier par fichier plutôt que pour une application complète.
Les tests effectués par l'audit :
La validation du choix de l'audit déroule les tests suivants, soit pour un seul fichier (choix conseillé), soit pour tous les fichiers d'une application.
Pour chaque enregistrement d'un fichier :
Test des chevauchements de données :
XPSQL vérifie dans le dictionnaire de données s'il y a des chevauchements de données (redéfinition ou découpage). Pour chaque donnée concernée, il indique quelle donnée est chevauchée.
Index :
XPSQL contrôle que la description des clés du dictionnaire correspond effectivement aux clés du fichier. Pour cela XPSQL compare la description des clés du dictionnaire avec les clés réelles du fichier sous Harmony. Le paramètre "Chemin du fichier de référence pour la comparaison des clés" permet d'indiquer le chemin où se trouve le fichier Harmony. Il est indispensable d'indiquer ce chemin.
Enregistrement et données :
XPSQL contrôle que les noms de données ne correspondent pas à des mots réservés du langage SQL.

Création des tables

Ce choix permet de créer les tables dans la base SQL. Il enchaîne à la copie des fichiers dans la base.
Lorsque l'opération s'applique à une sélection de fichiers, XPSQL valide automatiquement l'ensemble des fichiers sélectionnés.

Attention
Si les tables existent déjà dans SQL, elles sont supprimées et toutes les données existantes sont perdues.
.

Copie des fichiers

Ce choix permet de copier un fichier HARMONY dans la base SQL. Il demande :

• Le chemin du fichier d'origine.

• Le chemin du fichier de destination. Rappelons qu'il s'agit d'un chemin correspondant au serveur SQL. Les accès à la base sont toujours effectués en mode client-serveur, même à partir du serveur.

• L'option avec ou sans effacement du contenu des tables existantes.

Lorsque la copie est lancée " par application " le mode " pas à pas " permet d'intervenir dans le déroulement du transfert fichier par fichier.
Exemple :
Chemin d'origine : /Divalto/ERPDivalto
Chemin de destination //ServeurSQL/ERPDivalto

Filtrage des tables à l'import
Il est possible de ne pas transférer (et donc de ne pas effacer) des tables lors de la copie des données vers SQL.
Pour cela, il faut, dans le répertoire de la base, créer un fichier "excludeimport.txt" (excludeimportu.txt pour la plateforme cloud).
Dans ce fichier, il faut indiquer les couples dictionnaire / fichier / table pour chaque table à ignorer. Il y a un couple par ligne.
Exemple :
gtfdd.dhsd;gtfat.dhfi;art;
gtfdd.dhsd;gtfdos.dhfi;ets;
Note : les points-virgules sont obligatoires, même le dernier, celui après le nom de la table.
Dans la fenêtre de compte-rendu, le texte suivant s'affiche si une ou plusieurs tables ont été ignorées : "Des tables ont été exclues de la copie des données".

Remarques BLOB

Xpsql ne sachant historiquement pas traiter des champs de type BLOB pour une migration, il fallait passer par une extraction du contenu des tables avec BLOB dans des fichiers harmony .dhfd/.dhfi puis un import dans la table. Le fichier .blob contient le ou les champs de type blob de la table.

Maintenant, la copie avec l'option effacement requiert le fichier .blob correspondant à la table car il y a un lien fort entre la position dans le fichier blob et la ligne à importer. Ce fichier est créé lors de l'extraction des données. En mode avec effacement, l'id sql est réinitialisé pour commencer à 1.

Remarques

• La copie des données vérifie le numéro de version du fichier .dhfd. Si le numéro de version du fichier .dhfd ne correspond pas à celui renseigné dans xpsql, une erreur est affichée. Si vous êtes en possession d'un fichier sans version, il est possible de la renseigner via l'utilitaire xtools.dhop

• Si le fichier est comprimé (.dhzi), l'utilitaire effectue la décompression.
  Voir également :

• Les erreurs de transfert.

• Les erreurs

Extraction des données depuis SQL

Ce choix permet d'extraire les tables depuis SQL vers un fichier Harmony. Il demande :

• Le chemin de la base SQL.

• Le chemin du fichier Harmony de destination.

• L'option avec ou sans effacement du contenu des tables existantes.

• S'il faut comprimer les fichiers

Lorsque la copie est lancée " par application " le mode " pas à pas " permet d'intervenir dans le déroulement du transfert fichier par fichier.

Remarques BLOB

Maintenant, l'extraction va générer un fichier .blob, automatiquement créé lors de l'export, qui contient les champs de type Blob. Ce fichier sera utilisé lors de la copie des données.

Remarques :

• La version du fichier est maintenant renseignée dans les attributs du fichier .dhfd. Cette version est contrôlée lors de la copie des données vers SQL. Si vous êtes en possession d'un fichier .dhfd sans version, il est possible de la renseigner via l'utilitaire xtools.dhop

• Si l'option "Compression des donneés" est activée, le fichier .dhfd est comprimé en .dhzi. Le .dhfd est supprimé. La copie des données détecte si le fichier est comprimé et effectue la décompression.
  Voir également :

• Les erreurs de transfert.

• Les erreurs

Contrôle d'intégrité des fichiers Harmony

Avant le transfert de fichiers Harmony existants vers une base de données, il est fortement recommandé d'effectuer un contrôle d'intégrité des fichiers. Le lancement du contrôle d'intégrité est disponible directement depuis l'utilitaire XPSQL. Le contrôle s'applique aux fichiers sélectionnés valides.

Pilotage des imports et des exports

Performance
Ces choix permettent d'accélérer sensiblement la copie de fichiers Harmony volumineux vers ou depuis une base de données. Pour cela, il faut que les fichiers Harmony et la base de données soient hébergés sur le même serveur. Dans ce cas, les utilitaires d'import et export ne font pas transiter les données copiées par le réseau local.
Ces choix sont donc particulièrement intéressants lors de la migration de fichiers volumineux vers une base de données.
Tout comme xpsql, ces utilitaires contrôles la version des fichiers, et prennent en compte l'exclusion de tables lors de la copie des données vers SQL.
Utilitaires
L'utilitaire XpsqlImport.dhop permet d'importer des fichiers Harmony vers une base SQL.
L'utilitaire XpsqlExport.dhop permet d'exporter une base SQL vers des fichiers Harmony.
Génération des fichiers de pilotage
Le bouton « Piloter Import/Export » permet de générer un fichier de pilotage des importations ou des exportations de fichiers Harmony.
La liste des fichiers à importer ou à exporter correspond à l'ensemble des fichiers sélectionnés valides.
Les fichiers de pilotage, respectivement pilimport.txt pour un import et pilexport.txt pour un export, sont générés dans le répertoire /divalto/« base sql ».
Exemple de pilotage généré
XsqlImport
\\LocalHost\divalto\erpdivalto\gtfoftrc.dhfd
\\LocalHost\erpdivalto\gtfoftrc.dhfi
Importation ou exportation des fichiers
Pour effectuer l'importation ou l'exportation des fichiers, il convient d'exécuter le fichier de commandes =pilimport.txt ou =pilexport.txt.
Les fichiers feventxpsql.log et ferrorxpsql.log contiennent respectivement les comptes-rendus des transferts et des erreurs.
Pilotage via ping
Ces deux utilitaires peuvent également être piloté via ping :

• « Harmony » : Nom du fichier Harmony à copier / extraire

• « SQL » : Nom du fichier SQL à copier / extraire

• « Mode » : Facultatif. S'il vaut 'C', alors la copie / extraction se fera en mode sans effacement

Exemple :
Ping (« Harmony », « \\LocalHost\divalto\erpdivalto\gtfoftrc.dhfi »)
Ping (« SQL », « \\Localhost\erpdivalto\gtfoftrc.dhfi »)
ProgramCall (« xsqlimport.dhoq », , CALL_WAIT)
Remarque : Lorsque le programme est piloté via ping, les fichiers générés sont comprimés en .dhzi.

Erreurs les plus courantes

Les erreurs renvoyées par la base SQL.
Les erreurs renvoyées par SQL comportent :

• Un code d'état (SQLSTATE) normalisé par X/OPEN et SQL CAE spécification (1992). Par exemple S0001 signifie " Base, table ou vue déjà existante ".

• Un message d'erreur en clair de la forme :

[Microsoft][ODBC SQL Server Driver][SQL Server] message en clair.
Le message en clair peut être par exemple :

• Echec à la connexion de l'utilisateur 'demo'

• Il existe déjà un objet nommé 'désir' dans la base de données.

La documentation en ligne de la base utilisée peut être consultée pour des explications complémentaires.
L'erreur 0B17.
Lors du transfert d'un fichier dans une base SQL, si le fichier comporte plusieurs types d'enregistrements différents, ils doivent impérativement être identifiés par un identifiant. A l'écriture dans la base, XLANSQL doit reconnaître l'enregistrement grâce à cet identifiant. Si l'enregistrement ne correspond à aucun enregistrement décrit dans le dictionnaire de données, XLANSQL renvoie une erreur 0B17. L'utilitaire XPSQL affiche l'erreur avec le rang de l'enregistrement dans le fichier des données. Il convient alors de vérifier soit :

• La description des enregistrements du dictionnaire.

• La valeur de l'identifiant pour l'enregistrement concerné dans le fichier d'origine.

Type de données incorrect.
Les données de la base sont typées. Le moteur de base de données vérifie la cohérence des informations écrites dans la base. Les données numériques doivent être numériques et ne pas dépasser la capacité prévue, les dates doivent être correctes.
Avant d'écrire dans la base, XLANSQL effectue une affection numérique des données numériques (ce qui a pour effet d'éliminer les caractères non numériques) et contrôle les dates (une date erronée est remplacée par le 1/1/1753 sous SQL server). Dans le cas d'une date erronée, XLANSQL écrit un message d'erreur dans le journal des événements de Windows, mais laisse l'application poursuivre son déroulement normal. Il arrive néanmoins que les données écrites soient rejetées par le moteur de la base de données. Dans ce cas le message d'erreur sera celui renvoyé par la base de données.
Le journal des événements de Windows.
En cas d'erreur, XLANSQL renvoie un code d'erreur Erreurs : Xlan SQL . Il écrit également un message en clair dans le journal des événements des applications de Windows. Pour les erreurs d'exécution des requêtes SQL, XLANSQL écrit le source de la requête dans ce journal, ainsi que le message d'erreur renvoyé par le moteur de la base de données.
Fichier log de XPSQL.
L'utilitaire XPSQL consigne dans le fichier DHOdbcConfigSQL.log le déroulement des actions d'une session. On y trouvera notamment les erreurs lors du transfert des fichiers HARMONY vers la base. Attention ce fichier est effacé à chaque session de XPSQL.