Méthode publique · ORM_CSHX2 · Cycle de vie

mth_RAZ

ORM_RAZ

Réinitialise une instance de classe métier à un état propre : membres mappés SQL, flags d'état, clauses SELECT, et m_tabResults. Les deux paramètres optionnels permettent de moduler la portée du reset selon le besoin.

PUBLIQUE CYCLE DE VIE MySQL · MariaDB · PostgreSQL

📋 Description

mth_RAZ remet l'objet courant dans l'état d'une instance fraîchement allouée : tous les membres mappés à des colonnes SQL repassent à leur valeur par défaut selon leur type, et les marqueurs internes de l'objet (flags d'état, clauses de chargement, tableau de résultats) sont eux aussi remis à zéro.

La méthode est conçue pour réutiliser une instance existante sans avoir à la détruire et à la réallouer — opération coûteuse en WLangage, surtout dans des boucles de traitement.

🎯 Quand utiliser cette méthode

1. Réutilisation d'une instance pour plusieurs requêtes successives. Charger un client, le traiter, vider l'objet, charger le suivant — sans réallouer à chaque itération.

2. Annulation d'une saisie. L'utilisateur abandonne un formulaire : on vide l'objet pour qu'il ne soit pas accidentellement enregistré ou que ses valeurs ne polluent pas un futur usage.

3. Préparation après une erreur. Repartir d'un état propre après un échec d'opération qui a pu laisser l'objet dans un état partiellement renseigné.

4. Réinitialiser l'objet courant en préservant m_tabResults. Appeler mth_RAZ(Faux) pour repartir d'un état propre tout en conservant les résultats déjà chargés (par exemple pour itérer manuellement sur m_tabResults sans perdre la liste).

🔑 Signature

Déclaration

PROCÉDURE mth_RAZ(
LOCAL bRAZComplet est un booléen = Vrai,
LOCAL bRAZClauses est un booléen = Vrai
) : (booléen, entier, chaîne)

Élément	Valeur
Visibilité	PUBLIQUE

Paramètres

Paramètre	Type	Défaut	Rôle
`bRAZComplet`	booléen	`Vrai`	Si `Vrai`, le tableau interne `m_tabResults` est vidé. Si `Faux`, `m_tabResults` est préservé — utile pour réinitialiser l'objet courant tout en conservant la liste des résultats déjà chargés.
`bRAZClauses`	booléen	`Vrai`	Si `Vrai`, les 9 clauses SELECT positionnées sur l'objet (`p_sClauseWhere`, `p_sClauseOrderBy`, `p_nClauseLock`, etc.) sont remises à leur valeur par défaut. Si `Faux`, ces clauses sont préservées.

🧹 Ce qui est remis à zéro

Membres mappés SQL — toujours

Tous les membres de la classe mappés à des colonnes SQL sont remis à leur valeur par défaut selon leur type :

Type SQL	Valeur de reset
Entiers, réels, monétaires, durées, IDAuto	`0`
Chaînes (texte, mémo, caractère, Unicode)	`""`
Dates et heures (date6, date8, dateheure, heure)	`""`
Booléens	`Faux`

Flags d'état — toujours

Les marqueurs internes de l'objet sont systématiquement remis à zéro :

Flag	Valeur de reset
`p_bNouvelEnregistrement`	`Faux`
`p_bRécupérationID`	`Faux`
`p_bInsertedByAPI`	`Faux`
`p_bEnregistrementSupprimé`	`Faux`
`p_bBlocageEnregistrement`	`Faux`
`p_bPartiallyHydrated`	`Faux`
`p_nTypeAccèsDonnéesSQL`	`SGBD_LectureEcriture`
`p_sGUIDTemp`	`""`

Tableau interne `m_tabResults` — selon `bRAZComplet`

Si bRAZComplet = Vrai (défaut), m_tabResults est vidé. Si Faux, le tableau est conservé tel quel — utile pour réinitialiser l'objet courant sans perdre les résultats déjà chargés.

Clauses SELECT — selon `bRAZClauses`

Si bRAZClauses = Vrai (défaut), les 9 clauses SELECT sont remises à leur valeur par défaut :

Clause	Valeur de reset
`p_sClauseWhere`	`""`
`p_sClauseOrderBy`	`""`
`p_nClauseLock`	`NoLock`
`p_nClauseLimit`	`0`
`p_nClauseOffset`	`0`
`p_sClauseSelect`	`""`
`p_sClauseNotSelect`	`""`
`p_sClauseWith`	`""`
`p_sClauseJoin`	`""`

⚠️ Gestion des erreurs

Constante	Condition
`ERR_ORM_RAZ_TYPE_NON_GERE`	Un membre de la classe métier est mappé sur un type SQL non géré par la méthode (cas rarissime — l'ensemble des types HF usuels est couvert : entiers, réels, chaînes, dates, heures, booléens, monétaires, durées, IDAuto).

Si cette erreur est rencontrée, le reset des membres mappés déjà traités est conservé (les valeurs déjà mises à zéro restent à zéro), mais le reset des flags d'état, des clauses et de m_tabResults est annulé. Les valeurs d'origine de ces éléments sont préservées pour permettre le diagnostic.

💡 Exemples

Mode 1 — reset complet (cas nominal)

// ── Réutiliser une instance pour traiter plusieurs clients ──────
clClient est un Client

POUR i = 1 _À_ 10
    (bProcessing, nErrorCode, sErrorMessage) = clClient:mth_ChargerSelonID(tabIDs[i])

    SI bProcessing ET clClient:p_nOccurrencesTrouvées = 1 ALORS
        // ... traitement de l'objet ...
        TraiterClient(clClient)
    FIN

    // 🧹 Reset complet avant l'itération suivante
    clClient:mth_RAZ()
FIN

Mode 2 — reset partiel : préserver m_tabResults

Cas d'usage : on a chargé une liste d'enregistrements, on veut itérer manuellement dessus sans réallouer une nouvelle instance pour chaque tuple.

// ── Charger plusieurs enregistrements ───────────────────────────
clClient:p_sClauseWhere = "clients.VILLE = 'Paris'"
(bProcessing, nErrorCode, sErrorMessage) = clClient:mth_ChargerSelonClauseWhere()

SI bProcessing ALORS

    POUR i = 1 _À_ TableauOccurrence(clClient:m_tabResults, indVariable)

        // 🧹 Vider l'objet courant en gardant m_tabResults pour itération
        clClient:mth_RAZ(Faux)

        // Travailler sur l'élément courant du tableau
        TraiterClient(clClient:m_tabResults[i])

    FIN

FIN

Mode 3 — annulation d'une saisie

// ── L'utilisateur a cliqué sur "Annuler" dans le formulaire ─────
SI OuiNon("Abandonner les modifications en cours ?") ALORS
    clClient:mth_RAZ()
    Ferme()
FIN

Mode 4 — reset après erreur

(bProcessing, nErrorCode, sErrorMessage,) = clClient:mth_Enregistrer()

SI bProcessing = Faux ALORS
    Erreur(sErrorMessage)
    // 🧹 Repartir d'un état propre pour les opérations suivantes
    clClient:mth_RAZ()
FIN