Procédure globale · ORM_CSHX2 · Diagnostic

ORM_VerboseMode

Active ou désactive le mode verbose du framework. Lorsqu'il est actif, toutes les requêtes SQL exécutées par ORM_CSHX2 ainsi que les ouvertures et clôtures de transaction sont tracées en temps réel. Outil indispensable pour diagnostiquer un comportement inattendu, comprendre une cascade de suppressions, ou auditer une opération métier complexe.

PUBLIQUE DIAGNOSTIC MySQL · MariaDB · PostgreSQL

📋 Description

Le mode verbose intercepte toutes les requêtes SQL avant leur exécution et trace leur contenu textuel. Il intercepte également les ouvertures, validations et annulations de transaction. C'est la fenêtre de visibilité sur ce que fait réellement le framework derrière les méthodes mth_* et ORM_*.

Activé via ORM_VerboseMode(Vrai), désactivé via ORM_VerboseMode(Faux). L'état est mémorisé au niveau de la session ORM_CSHX2.

Deux modes de sortie possibles :

• Trace WinDev par défaut — les lignes apparaissent dans la fenêtre Trace de l'IDE. Utile en débogage interactif.

• Callback personnalisé — l'appelant fournit le nom d'une procédure projet qui recevra chaque ligne de trace. Utile pour rediriger vers un fichier, un champ libellé, une zone de texte, un système de logs centralisé…

🔑 Signature

Déclaration

PROCÉDURE ORM_VerboseMode(
LOCAL bModeVerboseStatus est un booléen,
LOCAL sCallBack est une chaîne = ""
)

Paramètres

Paramètre	Type	Défaut	Rôle
`bModeVerboseStatus`	booléen	—	`Vrai` active le mode verbose, `Faux` le désactive.
`sCallBack`	chaîne	`""`	Nom d'une procédure projet qui recevra chaque ligne de trace. Vide → traces envoyées à la fenêtre Trace WinDev.

Retour : aucun (procédure void).

🔍 Ce qui est tracé

Chaque ligne de trace est préfixée par un emoji qui identifie en un coup d'œil le type d'opération :

Préfixe	Signification	Source
`🔍`	Requête SELECT (lecture)	Toute requête commençant par `SELECT`
`🛢️`	Autre requête SQL (INSERT, UPDATE, DELETE, CREATE, ALTER…)	Toute requête ne commençant pas par `SELECT`
`🔁 BEGIN`	Ouverture d'une transaction	`ORM_TransactionBegin`
`✅ COMMIT`	Validation d'une transaction	`ORM_TransactionCommit`
`↩️ ROLLBACK`	Annulation d'une transaction	`ORM_TransactionRollBack`

Pour les transactions, la trace inclut aussi le nom de la procédure qui pilote la transaction (la procédure « owner » au sens du modèle owner) — utile pour reconstituer la cascade des appels.

ℹ️ Trace fidèle à la requête réellement exécutée

Les requêtes tracées sont celles qui sont effectivement transmises au moteur SQL, après encapsulation des identifiants spécifique au provider (backquotes MySQL/MariaDB, double-quotes PostgreSQL…). Ce que la trace montre est ce que la base reçoit.

📤 Modes de sortie

Mode 1 — Trace WinDev (par défaut)

Si sCallBack est vide ou non fourni, les lignes sont envoyées à la fenêtre Trace de l'IDE WinDev via la fonction native Trace(). C'est le mode le plus simple, idéal pour le débogage en cours de développement.

// ── Activation simple : traces dans la fenêtre Trace WinDev ─────
ORM_VerboseMode(Vrai)

// ... opérations ORM_CSHX2 ...

ORM_VerboseMode(Faux)    // désactivation

Mode 2 — Callback personnalisé

Pour rediriger les traces vers une autre destination (fichier, champ libellé d'une fenêtre, zone de texte, système de logs externe…), fournir le nom d'une procédure projet qui recevra chaque ligne en paramètre.

// ── Activation avec callback personnalisé ───────────────────────
ORM_VerboseMode(Vrai, "MaTraceVerbose")

// ... opérations ORM_CSHX2 ...


// ── Procédure projet qui reçoit les traces ──────────────────────
PROCÉDURE MaTraceVerbose(LOCAL sLigne est une chaîne)
    // Exemple : redirection vers un champ multiligne d'une fenêtre
    SAI_Logs = SAI_Logs + sLigne
    // ou : écriture dans un fichier
    // fEcritLigne(nFichier, sLigne)
FIN

💡 Cas d'usage typiques du callback

• Fichier de log applicatif — capturer toutes les requêtes SQL d'une session pour analyse a posteriori.

• Fenêtre de débogage utilisateur — proposer à un utilisateur avancé de visualiser ce qui se passe pendant un traitement complexe.

• Capture d'un cas reproduisant un bug — sauvegarder le scénario SQL exact qui mène à un comportement anormal pour le rejouer en environnement de test.

💡 Exemple — visualiser une suppression complète

Le mode verbose est particulièrement utile pour visualiser ce qui se passe lors d'opérations qui orchestrent plusieurs requêtes SQL en une seule appel — typiquement mth_EffacerSelonID qui supprime l'enregistrement principal, ses fiches liées, ses traductions et l'archive dans la corbeille en une seule transaction.

// ── Activation + suppression ────────────────────────────────────
ORM_VerboseMode(Vrai)

clClient est un Client
clClient:mth_EffacerSelonID(42)

ORM_VerboseMode(Faux)

Trace produite (extrait illustratif) :

🔁 BEGIN mth_EffacerSelonID 🔍 SELECT clients.SQL_ID_USER_UPDATE, clients.SQL_IP_USER, clients.SQL_LOCKED, clients.SQL_UPDATED, clients.SQL_UUID FROM clients WHERE clients.ID_CLIENT = 42 FOR UPDATE 🛢️ DELETE FROM clients WHERE clients.ID_CLIENT = 42 🛢️ DELETE FROM commandes WHERE commandes.ID_CLIENT = 42 🛢️ DELETE FROM cshx2_traductions WHERE ID_TRADUCTION = ... 🛢️ INSERT INTO cshx2_trashcan (...) ✅ COMMIT mth_EffacerSelonID

D'un coup d'œil, le développeur voit :

• La transaction qui s'ouvre, pilotée par mth_EffacerSelonID

• Le SELECT FOR UPDATE qui pose le verrou ligne et lit les colonnes de contrôle

• Le DELETE de l'enregistrement principal

• La cascade applicative — DELETE des lignes filles dans commandes

• La suppression des traductions associées dans cshx2_traductions

• L'archivage dans la corbeille cshx2_trashcan

• Le COMMIT qui valide l'ensemble

⚠️ Mode verbose à désactiver en production

Le mode verbose impacte les performances (chaque requête déclenche une trace) et expose des informations sensibles (valeurs SQL en clair). Il est destiné au débogage et doit rester désactivé sur les environnements de production.

Si une trace en production est nécessaire (audit, capture de bug client), utiliser le callback personnalisé pour cibler précisément ce qui doit être journalisé, et limiter la durée d'activation au strict minimum.

✅ Bonnes pratiques

💡 Activer ponctuellement autour d'une zone à diagnostiquer

Plutôt que d'activer le mode verbose pour toute la session, l'encadrer autour de l'appel suspect :

ORM_VerboseMode(Vrai)
// ... opération à diagnostiquer ...
ORM_VerboseMode(Faux)

Trace concise et lisible plutôt qu'un torrent de lignes à filtrer.

💡 Utiliser un callback dédié pour capturer un scénario

Pour reproduire un bug client, fournir un callback qui écrit dans un fichier joignable au ticket :

nFichierLog est un entier = fOuvre("trace_bug.log", foCréation)
ORM_VerboseMode(Vrai, "EcrireLog")
// ... reproduction du scénario ...
ORM_VerboseMode(Faux)
fFerme(nFichierLog)