> Tech > Parameter Summary Area

Parameter Summary Area

Tech - Par Renaud ROSSET - Publié le 24 juin 2010
email

En haut des pages de la plupart des API, un tableau montre les paramètres que vous pouvez passer à l’API et explique lesquels sont obligatoires, les types de données que vous devez passer, et comment les paramètres sont utilisés. La figure 6 montre la Parameter Summary Area pour l’API QMHSNDPM.

Parameter Summary Area

On voit que les paramètres de cette API particulière sont divisés en trois groupes : Required Parameter Group, Optional Parameter Group 1 et Optional Parameter Group 2. Quand vous appelez cette API, vous devez passer les neuf premiers paramètres parce qu’ils se trouvent dans le groupe des paramètres obligatoires (Required Paramters). Les paramètres 10-12 sont facultatifs mais si vous passez l’un d’eux, il faut les passer tous les trois (c’est-à-dire tous le groupe). Les paramètres 13 et 14 sont eux aussi facultatifs ; si vous passez l’un d’eux, il faut passer les deux – de plus, vous devez aussi passer les deux groupes avant eux. Autrement dit, vous devez toujours passer tous les paramètres qui précèdent chaque groupe optionnel que vous décidez d’utiliser.

Certaines API utilisent un groupe omissible au lieu d’un groupe facultatif, mais cet exemple ne contient pas de groupes de paramètres omissibles. Il est important de comprendre la différence. Bien que les mots se ressemblent, ils ne signifient pas la même chose. Un groupe facultatif peut être laissé de côté quand vous appelez l’API. Vous ne devez pas du tout passer un groupe facultatif si vous n’en avez pas besoin. Mais vous devez toujours passer un groupe omissible ; cependant vous pouvez très bien passer la valeur spéciale *OMIT comme paramètre au lieu d’une valeur réelle.

La deuxième colonne de la Summary Area décrit ce à quoi sert le paramètre. Si ce résumé d’une ligne n’est pas suffisant, vous pourrez trouver une description plus poussée dans la section Detailed Parameter.

La troisième colonne contiendra Input, Output, ou I/O pour indiquer comment l’API utilisera le paramètre. Input signifie que l’API lira ce paramètre, sans le changer. Autrement dit, c’est seulement pour l’entrée dans l’API. Output, bien entendu, représente le contraire : l’API ne lira pas le contenu du paramètre, mais elle l’utilisera pour retransmettre de l’information à votre programme. I/O signifie que l’API utilise le paramètre pour l’entrée et la sortie.

La dernière colonne dans la zone Summary de l’API est le type de données. Précisons tout de suite que ce type de données est neutre vis-à-vis du langage de programmation ; autrement dit, il n’a pas à correspondre au type de données d’un langage de programmation particulier. Peut-être que l’erreur la plus courante commise par les programmeurs RPG quand ils lisent une description d’API est de mal interpréter BINARY( 4) BINARY(4) ne signifie pas que le code RPG devrait dire 4B 0. D’abord parce que le type de données B de RPG n’est pas un vrai type de données binaires. Ensuite, quand la documentation de l’API spécifie 4 comme longueur, il veut dire 4 octets. En revanche, quand vous codez 4B 0 en RPG, vous déclarez que le nombre a quatre chiffres.

Voyons comment les variables packées fonctionnent. Quand vous définissez un nombre packé sous la forme 9P 0, vous savez qu’il pourra stocker des nombres d’un maximum de neuf chiffres, mais que la variable n’occupera que 5 octets de mémoire. Il en est de même pour les variables binaires : si vous définissez une variable binaire sous la forme 4B 0, elle permet des nombres de quatre chiffres maximum, mais n’occupe que deux octets de mémoire. Comme l’API pense que vous allez passer quatre octets, vous recevrez le « unexpected results » tant redouté contre lequel les manuels IBM nous mettent en garde. En RPG, le bon type de données à passer à un paramètre BINARY(4) est 10I 0, qui est un vrai nombre binaire de quatre octets de long.

Outre BINARY(4), la plupart des types de données que les API utilisent sont auto-explicatifs. CHAR(7) est 7A en RPG, CHAR(20) est 20A en RPG. Mais que faites-vous quand l’API dit CHAR(*) ? L’astérisque signifie que le champ peut varier : il n’est pas toujours de longueur fixe. Une autre erreur courante des programmeurs RPG consiste à passer une chaîne VARYING quand l’API dit CHAR(*). En RPG, VARYING est un type de données spécial dans lequel une chaîne de longueur fixe a comme préfixe un nombre de 2 octets qui indique au système combien il peut utiliser de la chaîne de longueur fixe. Cela fonctionne bien, mais l’API sera perturbée par ces deux octets supplémentaires. Au lieu d’utiliser VARYING, utilisez plutôt les options (*VARSIZE) sur un prototype pour une API qui spécifie CHAR(*), et vous devriez donner au paramètre la plus grande longueur prévue.

Le prototype RPG pour l’API QMHSNDPM (figure 7 en A) est un prototype qui correspond bien à la Parameter Summary Area. La ligne supérieure du prototype dit au système quel programme appeler et les lignes qui suivent représentent les différents paramètres. Les paramètres qui sont définis comme Input dans le Parameter Summary sont marqués comme CONST en RPG pour signifier clairement que l’API ne les changera pas. Les types de données des paramètres sont les équivalents RPG de ceux qui sont listés dans la Parameter Summary Area. Comme je n’ai besoin d’aucun des groupes de paramètres facultatifs, je ne les code pas sur le prototype. Je ne passe que le groupe de paramètres requis.

Après avoir défini le prototype, je peux l’appeler pour exécuter l’API (figure 7 en B). Dans ce cas, j’utilise l’API QMHSNDPM pour mettre la déclaration « Ceci est un test, ne pas le lire » dans mon job log. Je peux maintenant me balader dans le service IP où je travaille et demander sournoisement à d’autres personnes de le lire !

Téléchargez cette ressource

Cybersécurité des collectivités : Enjeux, Perspectives & Solutions

Cybersécurité des collectivités : Enjeux, Perspectives & Solutions

Villes, intercommunalités, métropoles, départements et régions sont particulièrement exposés aux risques de cybersécurité. Ce livre blanc Stormshield présente les défis cyber que rencontrent les collectivités, les solutions et perspectives pour qu’elles puissent assurer leur mission d’utilité publique, en toute sécurité.

Tech - Par Renaud ROSSET - Publié le 24 juin 2010