ORM_Setup
Point d'entrée unique d'initialisation du composant ORM_CSHX2. À appeler depuis le projet hôte une seule fois, avant toute utilisation de l'ORM. Configure connexion, session, sécurité et noms de colonnes framework via la structure ST_ORM_Config. Valide les paramètres obligatoires, applique les valeurs par défaut pour les paramètres optionnels.
📋 Description
ORM_Setup est l'unique point d'entrée d'initialisation du composant ORM_CSHX2. Il est conçu pour être appelé une seule fois, au démarrage du projet hôte, avant toute utilisation des classes métier qui héritent du composant.
Son rôle :
- Recevoir une structure
ST_ORM_Configentièrement renseignée par le projet hôte - Valider les paramètres obligatoires (et lever une erreur de configuration si invalide)
- Appliquer les valeurs par défaut sur les paramètres optionnels
- Préparer la session ORM (utilisateur, poste, version, langue, mode MetaData)
- Activer les fonctionnalités optionnelles configurées (MongoDB, mode API, chiffrement RGPD)
Cette procédure ne doit être appelée qu'une seule fois par instance d'application, typiquement dans l'événement d'initialisation du projet WinDev. Un second appel reconfigurerait l'ORM en cours d'exécution avec un comportement non garanti.
🔑 Signature
| Position | Élément | Type | Description |
|---|---|---|---|
| Entrée | stConfig | ST_ORM_Config | Structure de configuration complète. Voir §03 pour le détail. |
| Sortie 1 | bProcessing | booléen | Vrai si l'initialisation a réussi, Faux sinon. |
| Sortie 2 | nErrorCode | entier | Code d'erreur (0 si succès) — voir page Codes d'erreur. |
| Sortie 3 | sErrorMessage | chaîne | Message d'erreur localisé (vide si succès). |
📦 Structure ST_ORM_Config
Structure de configuration unique du composant ORM.
🔌 Connexion
| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| cnxData | Connexion | Oui | Connexion native WinDev vers la base de données cible (MySQL, MariaDB ou PostgreSQL). |
⚙️ Session
| Champ | Type | Obligatoire | Défaut | Description |
|---|---|---|---|---|
| nMetaDataMode | entier | Oui | — | Mode MetaData : METADATA_MODE_STANDARD (1), METADATA_MODE_SQL_ONLY (2) ou METADATA_MODE_JOIN (3). Voir le guide MetaData. |
| nUserID | entier | Oui | — | Identifiant de l'utilisateur courant. Doit être > 0. |
| sWorkStationID | chaîne | Oui | — | Identifiant du poste de travail. Tracé dans les colonnes SQL_IP_USER. |
| sExeName | chaîne | Oui | — | Nom de l'exécutable hôte. Tracé dans la colonne SQL_EXE. |
| sCurrentVersion | chaîne | Non | "" | Version courante du projet hôte. Information libre, écrite telle quelle. |
| sUUIDPrefix | chaîne | Non | "ORM" | Préfixe utilisé pour la génération des UUID. Voir p_sUUIDPrefix. |
| nDisplayedLanguageID | entier | Non | 1 | ID de la langue d'affichage par défaut de la session. 0 ou non renseigné → fallback sur 1. |
| bGDPREncoding | booléen | Non | Faux | Active le chiffrement RGPD des colonnes sensibles. Si Vrai, sCryptKey devient obligatoire. |
| sCryptKey | chaîne | Non* | "" | Clé de chiffrement RGPD. Immuable : assignable une seule fois (n'écrase jamais une clé existante). Obligatoire si bGDPREncoding = Vrai. |
🐘 Sous-structure PostgreSQLSetUp — type ST_ORM_PostgreSQL
| Champ | Type | Obligatoire | Défaut | Description |
|---|---|---|---|---|
| bBooleanAsInteger | booléen | Non | Faux | PostgreSQL spécifique : si Vrai, les booléens sont stockés sous forme d'entier (0/1) au lieu du type natif BOOLEAN. Sans effet sur MySQL/MariaDB. |
📦 Sous-structure MongoSetUp — type ST_ORM_Mongo
| Champ | Type | Description |
|---|---|---|
| bMongoArchiveEnabled | booléen | Active globalement l'archivage MongoDB après écriture. |
| bMongoArchiveDeferred | booléen | Si Vrai, l'archivage est différé (asynchrone). Sinon, synchrone bloquant. |
| sMongoServerAddress | chaîne | Adresse du serveur MongoDB (FQDN ou IP). |
| nMongoPort | entier | Port d'écoute MongoDB (par défaut 27017). |
| sMongoDatabase | chaîne | Nom de la base d'archivage MongoDB. |
| sMongoUser | chaîne | Identifiant de connexion MongoDB. |
| sMongoPassword | chaîne | Mot de passe MongoDB. |
🌐 Sous-structure APISetUp — type ST_ORM_API
| Champ | Type | Description |
|---|---|---|
| bAPI_Mode | booléen | Active le mode API (calcul automatique du drapeau m_bIsAPIServer). |
| sAPI_Url | chaîne | URL de base du serveur API. |
| API_Token | AuthToken | Jeton d'authentification (type WinDev natif AuthToken). |
🏷️ Sous-structure MetadataColumns — type ST_ORM_Colonnes (optionnel)
Permet au projet hôte de surcharger les noms par défaut des colonnes framework. Tout membre laissé vide conserve son nom par défaut.
| Champ | Colonne par défaut | Description |
|---|---|---|
| sUUID | SQL_UUID | Identifiant unique universel de la ligne. |
| sID_USER_INSERT | SQL_ID_USER_INSERT | Utilisateur ayant créé la ligne. |
| sID_USER_UPDATE | SQL_ID_USER_UPDATE | Dernier utilisateur l'ayant modifiée. |
| sIP_USER | SQL_IP_USER | Identifiant du poste de travail. |
| sLOCKED | SQL_LOCKED | Drapeau de verrouillage applicatif. |
| sINSERTED | SQL_INSERTED | Horodatage d'insertion. |
| sUPDATED | SQL_UPDATED | Horodatage de dernière modification. |
| sEXE | SQL_EXE | Nom de l'exécutable. |
| sPROCEDURE_INSERT | SQL_PROCEDURE_INSERT | Procédure d'origine de l'insertion. |
| sPROCEDURE_UPDATE | SQL_PROCEDURE_UPDATE | Procédure d'origine de la dernière modification. |
| sSTATUS | SQL_STATUS | Statut applicatif de la ligne. |
Le remapping des noms de colonnes framework est incompatible avec METADATA_MODE_JOIN. Si le mode 3 est utilisé, MetadataColumns doit rester intégralement vide. Voir validation #6 ci-dessous.
💡 Exemples
Exemple 1 — Initialisation MySQL standard
Initialisation au démarrage d'un projet WinDev avec MySQL, mode MetaData standard, pas de chiffrement RGPD, archivage MongoDB activé en différé :
Dans cet exemple, MaConnexionMySQL désigne la connexion aux données définie dans l'analyse du projet hôte (onglet Connexion de l'éditeur d'analyses WinDev). Le composant ORM_CSHX2 utilise cette connexion telle quelle — il ne la crée pas et ne la modifie pas.
Exemple 2 — PostgreSQL avec booléens stockés en entier
Lorsque le projet utilise PostgreSQL et impose un stockage des booléens sous forme d'entier (0/1) — typiquement pour interopérer avec une base existante ou un framework qui ne supporte pas le type natif BOOLEAN — la sous-structure PostgreSQLSetUp permet d'activer ce comportement.
bBooleanAsInteger n'a d'effet que sur les connexions PostgreSQL. Sur MySQL et MariaDB, les booléens sont déjà stockés en TINYINT(1) nativement — la propriété est ignorée.
Exemple 3 — Personnalisation des noms de colonnes framework
La sous-structure MetadataColumns permet de surcharger les noms par défaut des colonnes framework (SQL_UUID, SQL_INSERTED, etc.) — utile pour interopérer avec une base existante dont les conventions de nommage diffèrent. Tout membre laissé vide conserve son nom par défaut.
Cette personnalisation est incompatible avec METADATA_MODE_JOIN. Le mode 3 repose sur des noms de colonnes framework fixes — toute valeur non vide dans MetadataColumns sera rejetée par les validations.