Cette fonction permet de créer un nouvel élément à la fin de la liste définie par la section, donnée en paramètre, dans le fichier de données.
Important :
- La dll PgExTool doit être chargée (ordre CHARGER_DLL) en début de programme et doit rester chargée au moment de l'appel des fonctions de gestion de listes de sections.
- Cette fonction n'écrit pas dans le fichier de données ; par conséquent, le nouvel élément de la section ne sera accessible par les fonctions PgExToolFirstItemSection, PgExToolLastItemSection, PgExToolNextItemSection, PgExToolPreviousItemSection ou PgExToolItemSectionInUse que si une valeur est écrite auparavant dans le fichier de données.
- De même, la fonction PgExToolNewItemSection retournera toujours le même nouvel élément tant qu'aucune écriture ne sera effectuée dans le fichier de données pour cette nouvelle section.
- La fonction PgExToolNewItemSection n'influe pas sur la gestion de l'élément courant de la liste, donc sur le résultat de la fonction PgExToolItemSectionInUse.
Paramètres
ALPHA(256) |
Fichier |
Nom complet du fichier de données. |
ALPHA(n) |
SectionListe |
Section liste. |
ALPHA(n) |
SectionElt |
Section élément de liste (mis à jour par la fonction) de type SectionListe#numéro ; il faut donc prévoir SectionElt plus grand que ce que contient SectionListe . |
NUM_BIN_4 |
TailleSection |
Taille de SectionElt : n. |
NUM_BIN_4 |
CodeRetour |
Code retour de lecture (mis à jour par la fonction). |
Valeurs possibles du code retour
0 |
Création réussie : SectionElt est alors renseignée et contient une section qui peut être utilisée d'abord dans la fonction PgExToolWriteValue, puis dans la fonction PgExToolReadValue dès qu'au moins une valeur aura été écrite. |
Echec lors de la création de l'élément de la liste : SectionElt est retournée à blanc.
-1 |
Fichier paramètre non trouvé. |
-2 |
SectionListe invalide : - soit SectionListe est vide, - soit le fichier de données est un fichier paramètre destiné à un programme EXIT et SectionListe ne fait pas partie des sections autorisées. |
-4 |
SectionElt est trop petit pour recevoir le résultat de la fonction. |
-20 |
SectionListe non modifiable : contrôle exclusivement effectué si le fichier de données est un fichier paramètre destiné à un programme EXIT. |
Exemple
/* Cet exemple manipule un fichier paramètre
/* destiné à un programme EXIT lors d'une validation de correction
ALPHA(256) |
FicParam |
|
PARAM |
FicParam |
/* paramètre d'appel du programme EXIT |
/* pour la gestion de la liste :
ALPHA(40) |
SectionListe |
ALPHA(50) |
SectionElt |
NUM_BIN_4 |
TailleSection |
NUM_BIN_4 |
CodeRetour |
/* pour l'écriture et la lecture de valeur :
ALPHA(40) |
Cle |
ALPHA(200) |
Valeur |
NUM_BIN_4 |
TailleValeur |
/* Début de programme : chargement de la dll PgExTool
CHARGER_DLL 'PgExTool'
/* Mise à jour du rapport qui sera inséré dans le rapport
/* final de validation de correction
SectionListe = 'MSG_RAPPORT'
TailleSection = 50
/* Nouvelle section élément en fin de rapport
APPELER_DLL 'PgExTool' 'PgExToolNewItemSection' FicParam SectionListe SectionElt TailleSection CodeRetour
Cle = 'VALEUR'
Valeur = 'Première ligne du rapport'
/* écriture de la première ligne du rapport
APPELER_DLL 'PgExTool' 'PgExToolWriteValue' FicParam SectionElt Cle Valeur CodeRetour
/* Nouvelle section élément en fin de rapport
APPELER_DLL 'PgExTool' 'PgExToolNewItemSection' FicParam SectionListe SectionElt TailleSection CodeRetour
Cle = 'VALEUR'
Valeur = *BLANK
/* écriture d'une ligne vide dans le rapport => saut de ligne
APPELER_DLL 'PgExTool' 'PgExToolWriteValue' FicParam SectionElt Cle Valeur CodeRetour
/* Remarque : cette écriture correspond normalement à une suppression de clé,
/* mais ici, comme on manipule un nouvel élément de liste, cette action
/* valide la création de la section élément dans le fichier de données,
/* même si aucune clé n'y est écrite.
/* Nouvelle section élément en fin de rapport
APPELER_DLL 'PgExTool' 'PgExToolNewItemSection' FicParam SectionListe SectionElt TailleSection CodeRetour
Cle = 'VALEUR'
Valeur = 'Troisième ligne du rapport'
/* écriture de la dernière ligne du rapport
APPELER_DLL 'PgExTool' 'PgExToolWriteValue' FicParam SectionElt Cle Valeur CodeRetour
/* lecture du nombre de lignes du rapport
Cle = 'NB_ELT'
TailleValeur = 200
/* lecture du nombre d'éléments de la section liste dans le fichier paramètre
APPELER_DLL 'PgExTool' 'PgExToolReadValue' FicParam SectionListe Cle Valeur TailleValeur CodeRetour
/* à ce moment : Valeur = '3'
/* Fin de programme : déchargement de la dll PgExTool
DECHARGER_DLL 'PgExTool'
Cliquez ci-dessous pour plus d'informations sur :
les programmes EXIT.