Programmez vos propres constantes

Jim DORRANCE

Cette note technique vous explique comment créer, par programmation, vos propres constantes prédéfinies qui apparaîtront dans la fenêtre de l'explorateur à côté des constantes prédéfinies de 4D. La création des constantes par programmation élimine le besoin d'employer un Macintosh et un éditeur de ressources. Vous êtes également ainsi assuré que le “code source” de vos constantes est conservé avec le code source de votre base. ♪

- Titre : Programmez vos propres constantes

- Auteur : Jim DORRANCE

- Parution : 1 mars 2004

- Licence : Ce document est issu de https://www.developpez.com et reste la propriété exclusive de son auteur. La copie, modification et/ou distribution par quelque moyen que ce soit est soumise à l'obtention préalable de l'autorisation de l'auteur.

Sommaire

- I. Introduction

- II. Qu'est-ce qu'une constante prédéfinie 4DK# ?

- III. Employer des constantes prédéfinies

- IV. Créer des constantes prédéfinies

- V. La Base Demo :  Méthodes utilitaires

- VI. La Base Demo : Création des constantes Ks Project Method

- VII. Commentaire sur une des méthodes projet qui créent des déclarations de constantes

- VIII. Addendum

- IX. Bases exemples

I - Introduction

Une constante est une expression qui a une valeur fixe.

Il y a deux types de constantes dans 4D : les constantes prédéfinies que vous choisissez par nom, et les constantes littérales pour lesquelles vous écrivez la valeur réelle.

Cette note technique expliquera comment créer par programmation vos propres constantes prédéfinies qui apparaîtront dans la fenêtre de l'explorateur à côté des constantes prédéfinies de 4D.

La création des constantes par programmation élimine le besoin d'employer un Macintosh et un rédacteur de ressource tel que Resorcerer. Il s'assure également que le « code source »  de vos constantes est conservé avec le code source de votre base.

II - Qu'est-ce qu'une constante prédéfinie 4DK# ?

Les constantes prédéfinies sont des ressources, identiques en structure aux ressources STR#, mais enregistrées avec une signature différente : 4DK#.

Les constantes prédéfinies de 4D sont stockées dans le dossier de ressources du 4D ou du serveur 4D.

Un exemple des constantes prédéfinies 4D sont les événements formulaire :

Vos constantes peuvent être sauvegardées dans le fichier des ressources de votre base de données, ou dans un ficher des ressources externes. Cette note technique vous expliquera comment stocker vos constantes dans le fichier de ressources de la base exemple.

Si vous êtes sur Macintosh et avez un éditeur de ressources, 4DK# peut être visualisé en utilisant un template « customisé » ou en utilisant le STR# template.

La base de données de demo inclut un template 4DK# dans le fichier des ressources.

En analysant le template, nous pouvons comprendre la structure d'une ressource 4DK#.

(voir le site : http://www.mathemaesthetics.com/ResTemplates.html)

- OCNT (one-based count of list Items) : le nombre d'éléments dans une liste.

- LSTC (Begin Counted List Item): commence une liste en utilisant le champ OCNT.

- Le champ de PSTR (Pascal String) analyse une chaîne Pascal : (de 1 à 256 octets : 1 octet de longueur suivi des données Ascii).

- LSTE (End of any List Item) : déclare la fin d'une séquence.

Ainsi une ressource constante prédéfinie est une liste (array) de chaînes Pascal.

III - Employer des constantes prédéfinies

Des constantes prédéfinies sont énumérées dans la fenêtre de l'explorateur.

Les constantes sont énumérées par famille.
Pour utiliser une constante prédéfinie dans une méthode, glissez/déposez la constante de la fenêtre de l'explorateur dans le rédacteur de méthode, ou, dactylographiez directement son nom dans le rédacteur de méthode. Les noms des constantes prédéfinies peuvent contenir jusqu'à 31 caractères.

Si vous écrivez directement le nom d'une constante prédéfinie, vous pouvez employer le symbole “@” pour éviter d'écrire le nom de la constante dans sa totalité ou simplement utiliser la tabulation.

IV - Créer des constantes prédéfinies

Créer des constantes prédéfinies implique la création d'un tableau alpha où chaque élément contient trois informations : le nom de la constante, la valeur de la constante, et le type de la constante.

Chaque élément est composé : « Nom:Valeur:Type »

Les constantes prédéfinies peuvent être de l'un de ces trois types de données:  Alpha, Réel, ou Entier long.

Voici les exemples de constantes valides :

- kAlert_BadParamCount:1:L ;

- Austrian Shilling to Euros:13,7603:R ;

- Austrian Schilling:ATS:S.

Assurez-vous que des valeurs numériques sont déclarées comme Longints (L) ou Reals (R) et les chaînes de caractères comme String (S). N'importe quel autre type produira d'un avertissement.

V - La Base Demo :  Méthodes utilitaires

Plusieurs méthodes projet peuvent être considérées comme des méthodes utilitaires.

Ks_TBox_Add1 additionne 1 à la variable passée par pointeur à la méthode et renvoie le résultat dans $0.

1. C_ENTIER($0)

3. C_POINTEUR($1)

5. $1->:=$1->+1

7. $0:=$1->

Ks_TBox_SubString vérifie que la longueur de la chaîne passée dans $1 n'excède pas 31 caractères de longueur, la longueur maximum permise pour une constante. Tous les caractères au-dessus du caractère 31 seront tronqués dans 4D.

Ks_TBox_Update_4D4D met à jour la ressource 4D4D dans le fichier de ressource de la structure.

La ressource 4D4D est une « signature » que 4D Serveur utilise pour déterminer quand recharger les ressources sur chaque Client. La signature est juste un nombre. Quand le client se relie au serveur 4D, si la ressource 4D4D du 4D Client contient une valeur différente de la ressource 4D4D sur le serveur, le fichier des ressources du Server est copié sur le Client.

La modification du « resource fork » avec le code 4D ne modifie pas automatiquement la ressource 4D4D.

Ks_TBox_WriteResource coupe les grands tableaux en plusieurs petits tableaux pour une meilleure lisibilité dans l'explorateur. On l'a arbitrairement placé à 50 pour démontrer comment cela fonctionne.

1. C_ENTIER LONG ($SegementArraySize)

3. $SegementArraySize:=50

Chaque rangée est alors temporairement sauvegardée comme ressource STR#, et ensuite copiée dans le fichier de ressource 4DK#. Le fichier est renommé et la STR# provisoire est supprimée.

1. $ResID:=Ks_TBox_Add1 ($pResID)

3. `

4. TABLEAU VERS LISTE DE CHAINES ($ArStr;32000)

5. C_BLOB($Blob)

6. LIRE RESSOURCE ("STR#";32000;$Blob;$ResFile)

7. ECRIRE RESSOURCE ("4DK#";$ResID;$Blob;$ResFile)

8. Si ($i>1)

9. ECRIRE NOM RESSOURCE("4DK#";$ResID;$ResName+Chaine($i);$ResFile)

10. Sinon

11. ECRIRE NOM RESSOURCE("4DK#";$ResID;$ResName;$ResFile)

12. Fin de si

13. FIXER TAILLE BLOB($Blob;0)

15. SUPPRIMER RESSOURCE("STR#";32000)

VI - La Base Demo : Création des constantes Ks Project Method

Des constantes sont créées dans l'environnement “Utilisation”, menu “Spécial”, exécute une méthode “Ks_”.

La Méthode Projet “Ks_” :

1. Déclaration des variables ;

2. Vérification que c'est bien 4D, pas 4D Client ou 4D Serveur ;

3. Ouverture du fichier de ressources de la structure ;

4. Initialisation de quatre compteurs ;

5. Initialisation d'un Tableau Alpha pour contenir les déclarations des constantes ;

6. On remplit le Tableau Alpha des déclarations des constantes et on enregistre le Tableau Alpha en tant que ressource 4DK# ;

7. Mises à jour de la ressource 4D4D ;

8. On ferme le fichier de ressources de la structure ;

9. On quitte 4D.

Après avoir appelé la méthode Compiler_Process, la méthode crée un TABLEAU ENTIER LONG avec quatre éléments. Chaque élément du tableau sera employé comme compteur, la valeur contenue sera augmentée de 1 quand nécessaire.

Le premier élément contient l'ID de la ressource courante 4DK#.

Les constantes entrent dans la même catégorie que toutes autres ressources supplémentaires à une application : le Compilateur de 4D est compatible avec les ID de ressources supérieurs à 15 000. Pour la demo, 31 000 est employé comme premier ID. L'ID des ressources ne doit pas dépasser 32 767.

Le deuxième élément contient l'index pour un élément du tableau. Ce compteur est remis à zéro chaque fois qu'une nouvelle ressource 4DK# est créée.

Le troisième élément est utile pour produire par programmation un nombre séquentiel. Dans la base de données d'exemple, des constantes sont créées pour être employées comme sélecteur dans une méthode d'alerte générique. Ici le contenu de la constante n'a aucune signification : elle doit juste être unique.

Le quatrième élément est employé comme compteur de « Famille ». Il est parfois utile d'organiser des constantes par famille.

La méthode projet ExampleFamilyConstants illustre ce concept en utilisant un modulo de 1 000.

VII - Commentaire sur une des méthodes projet qui créent des déclarations de constantes

1. ` Méthode projet : Ks_Alerts

3. `

4. C_HEURE($1)   `THE RES FILE

5. C_POINTEUR($2)   `THE RES ID POINTER

6. C_POINTEUR($3)   `THE ITEM POINTER

7. C_POINTEUR($4)   `THE FAMILY POINTER

8. C_POINTEUR($5)   `THE VALUE POINTER

9. C_POINTEUR($6)   `THE STRING ARRAY

10. `

11. `

12. Si (Nombre de parametres=6)

13. `

14. C_HEURE($ResFile)

15. $ResFile:=$1

16. `

17. C_POINTEUR($pResID;$pIndex;$pFamily;$pValue)

18. $pResID:=$2

19. $pIndex:=$3

20. $pFamily:=$4

21. $pValue:=$5

22. `

23. $pIndex->:=0

24. $pValue->:=0

25. `

26. C_POINTEUR($pArStr)

27. $pArStr:=$6

28. `

29. C_ALPHA(255;$ResName)

30. $ResName:=Sous chaine(Nom méthode courante;4)

31. `

32. `CREATE AN "OVERSIZED" ARRAY TO AVOID REPEATED CALLS TO "INSERT ELEMENT"

33. `

34. TABLEAU ALPHA(255;$pArStr->;10)

35. `

36. `SELECTORS FOR Alert_

37. `

38. $pValue->:=0

39. $pArStr->{Ks_TBox_Add1 ($pIndex)}:=Ks_TBox_SubString ("kAlert_BadParamCount")+":"

40. +Chaine(Ks_TBox_Add1 ($pValue))+":L"

41. $pArStr->{Ks_TBox_Add1 ($pIndex)}:=Ks_TBox_SubString ("kAlert_LockedRecord")+":"

42. +Chaine(Ks_TBox_Add1 ($pValue))+":L"

43. $pArStr->{Ks_TBox_Add1 ($pIndex)}:=Ks_TBox_SubString ("kAlert_SingleUserOnly")+":"

44. +Chaine(Ks_TBox_Add1 ($pValue))+":L"

45. $pArStr->{Ks_TBox_Add1 ($pIndex)}:=Ks_TBox_SubString ("kAlert_ClientServerOnly")+":"

46. +Chaine(Ks_TBox_Add1 ($pValue))+":L"

47. `

48. `WRITE THE RESOURCE

49. `

50. Ks_TBox_WriteResource ($ResFile;$ResName;$pResID;$pIndex;$pFamily;$pValue;$pArStr)

51. `

52. `

53. Sinon

54. ALERTE("Incorrect parameters were sent to the procedure "+Caractere(34)

55. +Nom methode courante+Caractere(34)+".")

57. Fin de si

crée un tableau :

1. arStr255{1}:="kAlert_BadParamCount:1:L"

2. arStr255{2}:="kAlert_LockedRecord:2:L"

3. arStr255{3}:="kAlert_SingleUserOnly:3:L"

4. arStr255{4}:="kAlert_ClientServerOnly:4:L"

et le sauve sous le nom “Alerts”.

VIII - Addendum

Les ressources 4DK# sont chargées en mémoire Sur Démarrage.
Si vous avez créé une application enginée, si vous avez créé des milliers de constantes prédéfinies, et si aucun appel à EXECUTER n'est fait en utilisant des constantes prédéfinies, vous pouvez supprimer les ressources 4DK# de votre application compilée et récupérer ainsi la mémoire.

IX - Bases exemples

Téléchargez les bases exemples :

base exemple Mac

base exemple Windows