• Comment créer une procédure stockée et une requête stockée.
• Comment déployer une procédure stockée et les requêtes stockées associées.
• Comment exécuter une procédure stockée dans vos programmes.
• Comment gérer des erreurs dans les procédures stockées.

La création de procédures stockées est effectuée dans l'analyse.

1. Créez si nécessaire la collection de procédures stockées dans l'analyse :
   • soit cliquez sur parmi les boutons d'accès rapide.
     • La fenêtre de création d'un nouvel élément s'affiche : cliquez sur "Données" puis sur "Collection de procédures stockées".
     • Saisissez le nom de la collection de procédures et validez.
   • soit par le volet "Analyse" : sélectionnez le dossier "Procédures stockées". Dans le menu contextuel, sélectionnez l'option "Nouvelle collection de procédures". La collection de procédures stockées est automatiquement créée. Par défaut, cette collection de procédures a pour nom "Collection_<Nom analyse>".
   • soit dans le ruban de l'éditeur d'analyses : sous le volet "Analyse", dans le groupe "Création", déroulez "Nouveau" et sélectionnez "Collection de procédures stockées". La collection de procédures stockées est automatiquement créée. Par défaut, cette collection de procédures a pour nom "Collection_<Nom analyse>".
2. Cette collection est enregistrée physiquement dans le sous-répertoire "Code" du répertoire de l'analyse.
3. Créez une procédure dans la collection de procédures. Cette procédure sera une procédure stockée.

Importer une collection de procédures existante

1. Ouvrez si nécessaire l'éditeur d'analyses.
2. Dans le volet "Analyse", sélectionnez le dossier "Procédures stockées".
3. Affichez le menu contextuel et sélectionnez l'option "Importer une collection de procédures". Dans la fenêtre qui s'ouvre, sélectionnez la collection de procédures à importer et validez.
4. Les opérations effectuées sont les suivantes :
   • Si la collection de procédures appartient au projet en cours : la collection de procédures du projet est automatiquement recopiée dans le répertoire "Code" de l'analyse. Le nom logique de cette procédure est automatiquement renommé.
     Attention : Les deux collections de procédures sont dissociées : une modification effectuée dans la collection de procédures du projet ne sera pas reportée dans la collection de procédures de l'analyse et inversement.
   • Si la collection de procédures n'appartient pas au projet en cours : la collection de procédures est automatiquement recopiée dans le répertoire "Code" de l'analyse, et définie comme procédure stockée.

Utiliser une requête dans une procédure stockée

• Méthode 1 :
  1. Cliquez sur parmi les boutons d'accès rapide.
     • La fenêtre de création d'un nouvel élément s'affiche : cliquez sur "Données" puis sur "Requête stockée".
     • L'assistant de création d'une requête est automatiquement lancé. La requête est automatiquement créée. La requête est enregistrée physiquement dans le sous-répertoire "Code" du répertoire de l'analyse.
  2. La requête peut être utilisée dans une des procédures stockées de l'analyse.
• Méthode 2 :
  1. Affichez l'éditeur d'analyses.
  2. Affichez le volet "Analyse" et sélectionnez l'option "Nouvelle requête" du menu contextuel. L'assistant de création d'une requête est automatiquement lancé. La requête est automatiquement créée. La requête est enregistrée physiquement dans le sous-répertoire "Code" du répertoire de l'analyse.
  3. La requête peut être utilisée dans une des procédures stockées de l'analyse.

1. Ouvrez si nécessaire l'éditeur d'analyses.
2. Dans le volet "Analyse", sélectionnez le dossier "Requêtes".
3. Dans le menu contextuel, sélectionnez l'option "Importer une requête". Dans la fenêtre qui s'ouvre, sélectionnez la requête à importer et validez.
4. Les opérations effectuées sont les suivantes :
   • Si la requête appartient au projet en cours : la requête du projet est automatiquement recopiée dans le répertoire "Code" de l'analyse, et relocalisée : une seule requête est utilisée par le projet et l'analyse. Ainsi une modification effectuée dans la requête du projet sera automatiquement reportée dans la requête de l'analyse et inversement.
   • Si la requête n'appartient pas au projet en cours : la requête est automatiquement recopiée dans le répertoire "Code" de l'analyse, et définie comme requête liée à l'analyse.

Code WLangage utilisable dans les procédures stockées

• Le code des procédures stockées est écrit en WLangage. Il est possible d'utiliser un grand nombre de fonctions du WLangage.
• Pour savoir si une fonction est utilisable ou non dans une procédure stockée, il suffit de consulter l'aide de cette fonction : si l'image est affichée dans la barre de titre de la fonction, la fonction est utilisable dans le code des procédures stockées.
  De plus, lors de la compilation du code, des messages d'erreur vous informent de l'utilisation de fonctions non autorisées dans le code des procédures stockées.
  Par exemple, seuls les types simples peuvent être utilisés dans le code des procédures stockées (Chaînes, entiers, ...). Un paramètre de procédure stockée doit être de type simple : un objet ou un tableau ne peut pas être passé en paramètre. Il est cependant possible d'utiliser la fonction Sérialise par exemple pour passer un tableau en paramètre à une procédure stockée.
• Il n'est pas possible d'utiliser dans des procédures stockées : des classes, des états, des fenêtres, des pages, ...
• Les fenêtres/pages de gestion automatique des erreurs ne sont pas disponibles dans les procédures stockées. Il est cependant possible d'utiliser la fonction HSurErreur pour rediriger l'erreur sur une procédure (cette procédure doit également être une procédure stockée).
• Plusieurs variables WLangage permettent à partir d'une procédure stockée d'obtenir des renseignements sur l'application cliente l'utilisant.
  Ces variables sont les suivantes :
  

  HInfoExécution.Application	Application cliente qui a lancé la procédure stockée en cours.
  HInfoExécution.Base	Base manipulée par l'application cliente qui a lancé la procédure stockée en cours.
  HInfoExécution.Login	Login de l'utilisateur de l'application cliente qui a lancé la procédure stockée en cours.
  HInfoExécution.Machine	Poste de l'utilisateur qui a lancé la procédure stockée en cours (adresse IP ou nom du poste).

• Il est possible de sauvegarder des valeurs sur le serveur à partir d'une procédure stockée. Cette valeur pourra être relue par une autre procédure stockée ou par un trigger par exemple. Les fonctions permettant de gérer les valeurs persistantes sur le serveur sont les suivantes :
  

  HChargeParamètre	Lit un paramètre précédemment sauvegardé à partir d'une procédure stockée grâce à la fonction HSauveParamètre.
  HListeParamètre	Renvoie la liste des paramètres sauvegardés à partir des procédures stockées sur le serveur.
  HSauveParamètre	Sauve une valeur persistante sur le serveur HFSQL.
  HSupprimeParamètre	Supprime un paramètre précédemment sauvé avec la fonction HSauveParamètre.
• Il est possible d'enregistrer des fichiers temporaires dans un répertoire du serveur et de purger ce répertoire. Les fonctions utilisables sont les suivantes :
  

  HPurgeRepTravail	Purge et détruit le répertoire temporaire précédemment créé lors de l'exécution de la fonction HRepTravailServeur.
  HRepTravailServeur	Renvoie le chemin d'un répertoire temporaire sur le serveur HFSQL.

• Pour manipuler des fichiers de données, il faut utiliser la fonction HDéclareExterne.
  Par exemple :
  

  PROCÉDURE NomDeLaProcédureStockée()
  
  // Vérification de l'existence du fichier logique
  SI PAS HFichierExiste(CODEPOSTAUX) ALORS
  	// Fichier non connu, il faut le déclarer
  	// Attention, pour déclarer un nouveau fichier dans une procédure stockée HFSQL, 
  	// il faut :
  	// - NE PAS utiliser de connexion : C'est la base en cours 
  	// sur laquelle se trouve la procédure stockée qui sera utilisée
  	// - NE PAS donner un chemin complet : 
  	// Le fichier sera recherché dans la base en cours. 
  	// Il est possible d'indiquer un sous-répertoire de la base de données. 
  	// - donner le nom complet du fichier, extension comprise (.FIC)
  	SI PAS HDéclareExterne("CODEPOSTAUX.FIC", "CODEPOSTAUX") ALORS
  		// Erreur de déclaration du fichier
  		RENVOYER HErreurInfo()
  	FIN
  FIN
  
  // Utilisation du fichier de données
  // POUR TOUT CODEPOSTAUX 
  //	//Traitement...
  // FIN
  
  // Traitement OK, sans erreur
  RENVOYER ""

1. Affichez la fenêtre de description de l'analyse.
   • Ouvrez si nécessaire l'éditeur d'analyses.
   • Affichez le menu contextuel de l'analyse (clic droit sur le graphe de l'analyse) et sélectionnez l'option "Description de l'analyse".
2. Affichez l'onglet "Compilation".
3. Cochez l'option "Activer les erreurs de compilation pour la compatibilité 64 bits".
4. Validez.

Tester une procédure stockée

1. Sélectionnez la procédure stockée à tester dans le volet de l'analyse.
2. Affichez le menu contextuel de la procédure stockée (clic droit) et sélectionnez l'option "Tester la procédure".
3. La fenêtre de saisie des paramètres de la procédure s'affiche. Dans cette fenêtre, il est possible de :
   • Saisir les paramètres de la procédure.
   • Lancer le test de la procédure.
     Remarque : cette fenêtre peut être utilisée pour relancer plusieurs fois l'exécution en modifiant les paramètres.
4. Lorsque le test de la procédure est lancé :
   • Une mise à jour de la procédure stockée sur le serveur est proposée si nécessaire.
   • La procédure est lancée sur le serveur.
   • La valeur de retour de la procédure est affichée si nécessaire.

• Le port de débogage est le port 27281 par défaut. Il est nécessaire d'ouvrir ce port dans le firewall. Ce port peut être modifié dans le fichier HFConf.ini. Pour plus de détails sur le débogage des procédures stockées, consultez Déboguer une connexion à un serveur HFSQL.
• Pour lancer le test d'une procédure stockée, il est nécessaire d'avoir le droit de débogage sur la base de données.
• Les traces utilisées dans les procédures stockées sont affichées dans le volet Trace du débogueur.
• Le code de la procédure stockée peut contenir des points d'arrêt : le débogueur sera alors lancé.
• Les éléments déployés sur le serveur sont utilisés lors du test.
• La fonction EnModeTest renvoie Vrai.

Limite

Présentation

• pour test : les procédures stockées et/ou les requêtes sont déployées sur le serveur choisi, mais l'analyse n'est pas mise à jour. Cette manipulation est conseillée par exemple si l'analyse est très importante et demande une génération relativement longue.
  Attention : si une application est déployée sur le serveur, celle-ci pourra ne plus fonctionner après ce déploiement pour test. Cette option est à utiliser sur un serveur de test.
• réellement : l'analyse doit être re-générée et la modification automatique des fichiers de données doit être effectuée lors de l'installation de la version cliente.

Déployer pour test

1. Dans l'éditeur d'analyses, sous le volet "Analyse", dans le groupe "Analyse", déroulez "Synchronisation" et sélectionnez "Mettre à jour les éléments stockés (HFSQL Client/Serveur)".
2. Dans la fenêtre qui s'affiche, sélectionnez :
   • les collections de procédures à mettre à jour.
   • les requêtes à mettre à jour.
   • les triggers à mettre à jour.
   • la connexion concernée par la mise à jour. Il est également possible de saisir directement les caractéristiques de la connexion.
     
3. Validez la mise à jour.

Déployer en réel

1. Générer l'analyse contenant les procédures stockées (option "Génération de l'analyse" du menu contextuel de l'analyse). Une modification des fichiers de données peut être effectuée lors de cette étape.
2. Créer la version Client en demandant une modification automatique des fichiers de données : sous le volet "Projet", dans le groupe "Génération", déroulez "Procédure d'installation" et sélectionnez "Créer la procédure d'installation".
   Remarque : il suffit de modifier le code des procédures stockées ou les requêtes de l'analyse pour qu'une modification automatique des fichiers de données soit proposée.
3. Installer l'application.

• Les fonctions WLangage HMiseAJourCollection et HSupprimeCollection permettent de forcer par programmation la mise à jour et la suppression de collections de procédures stockées sur le serveur.
• Les fonctions WLangage HMiseAJourRequête et HSupprimeRequête permettent de forcer par programmation la mise à jour et la suppression des requêtes stockées sur le serveur.
• La fonction HListeElémentStocké permet de lister les collections de procédures, les requêtes et les procédures installées sur un serveur.
• Le Centre de Contrôle HFSQL permet de gérer les procédures stockées et les requêtes présentes sur le serveur.

Mise à jour à chaud des procédures stockées sur le serveur HFSQL

• Si aucune procédure de la collection n'a été lancée, la collection de procédures peut être mise à jour sur le serveur.
• Si une procédure de la collection a été lancée, la collection de procédures peut être mise à jour uniquement si la modification de la collection de procédure ne concerne pas les variables globales. Si les variables globales de la collection de procédures ont été modifiées, la fonction HMiseAJourCollection renvoie Faux. Dans ce cas, il est nécessaire de déconnecter tous les utilisateurs pour effectuer la mise à jour.
  Attention : Dans ce dernier cas, si la mise à jour a été effectuée, les utilisateurs connectés avant la mise à jour utiliseront lors de la prochaine exécution d'une procédure stockée :
  • le nouveau code de la procédure stockée,
  • les variables globales avec les valeurs définies avant la mise à jour.

• soit directement grâce à la fonction HExécuteProcédure.
• soit dans une requête SQL, exécutée avec la fonction HExécuteRequêteSQL.

Exécution d'une procédure stockée depuis une requête SQL

• La procédure stockée doit être une fonction stockée : elle doit toujours renvoyer une valeur. Dans le cas contraire, une erreur d'exécution sera générée.
• Si le nom de la procédure stockée est identique à celui d'une fonction ou procédure du projet, il est nécessaire de préfixer son nom par le nom de la collection de procédures stockées.

// Requête exécutée par le poste client
HExécuteRequêteSQL("CAClient34", "SELECT NomClient, CodePostal, " + ...
	"nRenvoieCA(Client.NumClient,'20061201') " + ...
	"as Total from Client where codepostal like '34%')")

// Procédure stockée exécutée sur le serveur
PROCÉDURE nRenvoieCA(nNumClient, DateLimite)
nTotal est un monétaire
// On filtre sur la date limite 
// On veut les commandes à partir de DateLimite
HFiltre(Commande, NumClient, hValMin, hValMax, "DateCommande >= '" + DateLimite + "'")
// On récupère toutes les commandes du client et on additionne leur montant
HLitRecherchePremier(Commande, NumClient, nNumClient)
TANTQUE HTrouve(Commande)
	nTotal += Commande.TotalTTC
	HLitSuivant(Commande, NumClient)
FIN
RENVOYER nTotal

sdProcStock est une Source de Données
SI PAS HExécuteRequêteSQL(sdProcStock, CnxHFSQL, hRequêteDéfaut, ChaîneConstruit([
SELECT Fonction_ProcédureStockée(%1,'%2') 
FROM DUAL
], 3, "chaîne à passer en paramètre")) ALORS
	Erreur("Echec de l'appel à la procédure stockée ", HErreurInfo())
SINON
	SI HLitPremier(sdProcStock) ALORS
		Info("Résultat de la procédure stockée : ", HEnregistrementVersChaîne(sdProcStock))
	FIN
FIN

Mécanisme des sous-erreurs

PROCÉDURE Procédure_Client()
// Procédure exécutée sur le poste client
...
// Ligne 10 : Exécute une procédure sur le serveur
HExécuteProcédure(UneConnexion, UneProcédureStockée)

// Procédure stockée sur le serveur
PROCÉDURE UneProcédureStochée
...
// Ligne 5 : Le mécanisme de sécurité du WLangage 
// détecte un identificateur inconnu
RENVOYER ElementInconnu

• Erreur principale : informations concernant la partie cliente : "Erreur remontée par le serveur XXX", Procédure Procédure_Client, Ligne 10, ...
• Sous-Erreur : informations concernant la partie serveur : "Identificateur ElementInconnu inconnu", Procédure UneProcédure, Ligne 5, ...

PROCÉDURE Procédure_Client()
// Procédure exécutée sur le poste client
...
// Ligne 10 : Exécute une procédure sur le serveur
HExécuteProcédure(UneConnexion, UneProcédureStockée)

// Procédure stockée sur le serveur
PROCÉDURE UneProcédureStochée
...
// Ligne 3 : exécution d'une requête
HExécuteRequêteSQL(UneRequête, "SELECT ProcédureCalcul(Fic.Rub) FROM Fic")
// Ligne 5 : Parcours de la requête
POUR TOUT UneRequête
...
FIN

// Procédure de calcul appelé depuis la requête
PROCÉDURE ProcédureCalcul(param)
...
// Ligne 4 : Le mécanisme de sécurité du WLangage
// détecte un identificateur inconnu
RENVOYER ElementInconnu

• Erreur principale : informations concernant la partie cliente : "Erreur remontée par le serveur XXX", Procédure Procédure_Client, Ligne 10, ...
• Sous-Erreur 1 : informations de la partie serveur concernant la procédure UneProcédureStockée : "Erreur pendant l'exécution de la requête", procédure UneProcédureStockée, ligne 5, ...
• Sous-Erreur 2 : informations de la partie serveur concernant la procédure ProcédureCalcul : "Identificateur ElementInconnu inconnu", procédure ProcédureCalcul, ligne 4, ...

// Première erreur sur le serveur
ExceptionInfo(errMessage, errOrigine)

Codes d'erreur pouvant être rencontrés dans les procédures stockées

• Une procédure stockée de même nom est utilisée avec plusieurs bases de données, et plusieurs connexions. Le serveur ne peut pas déterminer si la procédure XXX doit être exécutée avec la connexion YYY sur la base de données ZZZ ou avec la connexion YYY1 sur la base de données ZZZ1.
  Solution : Spécifier la connexion et la base de données à utiliser.
• Deux connexions à la base de données sont disponibles. Le serveur ne peut pas déterminer si la procédure XXX sur la base de données ZZZ doit être exécutée avec la connexion YYY ou avec la connexion YYY1.
  Solution : Spécifier la connexion à utiliser
• La procédure est utilisée dans plusieurs collections de procédures.