Coder les procédures Key

Les modules d’externalisation contiennent la définition de deux procédures pour traiter les clés et d’une sous-procédure pour libérer un verrou sur le fichier traité, comme on le voit dans la figure 5 (se reporter aux renvois). Ces procédures peuvent être appelées directement par les sous-procédures présentes dans le membre include pFileStd ou peuvent être appelées (un rétro-appel) à partir des sous-procédures du module FILE00A.

A.    setStoreKeys()  copie la valeur des champs clés de la structure clé dans l’image d’enregistrement stockée.

B.    setKeyDS() copie la valeur des champs clés de l’image d’enregistrement stockée dans la structure clé.

C.    unlockRow() libère le verrou sur le fichier traité. Cette sous-procédure doit être codée parce que l’opération UNLOCK requiert que le nom du fichier soit spécifié plutôt que le nom du format d’enregistrement ; faute de quoi ce serait une sous-procédure dans le membre include pFileStd.

Valeurs par défaut et validation

Deux autres sous-procédures —setDefaults() et validData()—doivent être codées, même si elles se contentent de renvoyer (elles sont appelées à partir des sous-procédures dans FILE00A). La figure 6 montre un exemple des deux sous-procédures. setDefaults() définit les valeurs de colonnes par défaut pour une nouvelle ligne sur la base de données. validData() valide les colonnes dans une ligne avant de mettre (ajouter ou supprimer) la ligne dans le fichier.

Instancier, libérer un handle, timeouts

La figure 7 montre les sous-procédures pour instancier et pour libérer un produit. La sous- procédure new_Product() prend les valeurs clés passées, définit les champs clés (dans la structure de données key), et appelle la sous-procédure internal_New(), qui effectue un rétro- appel (callback) vers getRow() (dans pFileStd) pour obtenir une ligne d’une table, stocker l’image de ligne demandée dans un espace utilisateur, et renvoyer un handle unique (persistId).

La sous-procédure release_Product() libère l’espace alloué au handle dans l’espace utilisateur : vous n’aimeriez pas être à court d’ID ! Ici, peu de code accomplit beaucoup de travail. Les sous-procédures internal_xxxxxxx() sont des enveloppes (codées dans pFileStd) utilisées pour appeler les routines correspondantes dans le module FILE00A. Les enveloppes servent à simplifier l’interface d’appel. Les procédures présentes dans FILE00A requièrent des éléments tels que des pointeurs vers des structures de données standard et des sous-procédures standard. Les sous-procédures internal_xxxxxxx() ont les paramètres complets.

Timeouts

L’espace alloué à un élément stocké ne sera pas gardé indéfiniment. Une structure de données vient spécifier la durée de stockage limite d’une image, au-delà de laquelle un  handle est automatiquement libéré.

Une partie du handle renvoyé (quand un élément est alloué) est un tampon horodateur. Les procédures internes (dans FILE00A) utilisent celui-ci pour s’assurer que le bon handle est utilisé. Si un client référence un handle incorrect, un message d’erreur est généré (c’est-à-dire, si le handle a été libéré en raison d’un timeout).

Getters

Les sous-procédures getter sont simples et directes : elles placent simplement les données requises dans les champs de paramètres pour le getter. Autrement dit, les données sont copiées à partir de l’image stockée dans l’espace utilisateur et/ou extraites d’ailleurs et/ou calculées.
La figure 8 montre l’exemple d’un format getter (get_product_Data) et d’un column getter (get_stock_On_Hand). Les sous-procédures sont appelées de la manière suivante :

get_product_Data(Id:ProductData);
stock =  get_stock_On_Hand(persistId);

Les points principaux à noter sont les suivants. Reportez-vous aux renvois :

A.    L’appel à la routine interne setHandle() (dans FILE00A) s’assure que la bonne image dans l’espace utilisateur est atteinte et qu’il n’y a pas eu de timeout.
B.    Les données peuvent être copiées à partir de l’image stockée (dans l’espace utilisateur).
C.    Les données peuvent être extraites d’autres sources.
D.    Les données peuvent être calculées.

Mais ce ne sont pas les seuls types de getters. Voir les deux encadrés de cet article : « Un getter qui renvoie une liste d’éléments en utilisant SQL imbriqué (embedded SQL) » et « L’usage des quick getters ».

Setters

Les setters sont encore plus simples que les getters car ils se cantonnent à copier des données de paramètres dans l’image stockée.

La figure 9 montre un exemple de format setter (set_product_Data) et un column setter (set_buying_Price). Les sous-procédures sont appelées de la manière suivante :

set_product_Data(persistId: productData);
set_buying_Price(persistIdId: newPrice);

Comme avec les getters, un appel à la routine interne setHandle() (dans FILE00A) s’assure que la bonne image dans l’espace utilisateur est atteinte et qu’il n’y a pas eu de timeout.

Les figures et illustrations de cet article sont accessibles via le Club Abonnés.