Travailler avec des API, première partie

La figure 1 présente un programme de
style traditionnel avec un appel programme
qui utilise une PLIST. Cet
exemple emploie une API pour extraire
une description d’objet : ici, une bibliothèque.
Le programme est appelé
de la ligne de commande et se voit
transmettre le nom de la bibliothèque
comme un paramètre. Si la bibliothèque
existe, le programme revient
normalement ; si elle n’existe pas,
le programme fait un dump avant
d’échouer
Vous pouvez aussi cheminer dans
ce programme en utilisant la commande
STRDBG (Start Debug) qui permet
de voir les variables changer.
Examinons maintenant ce programme
plus en détail.
Le membre copy en A est un fichier
« system include » d’une structure de
données utilisé pour contrôler les erreurs.
Si votre système ne possède pas
de fichiers system include, vous pouvez
les charger à  partir des CD d’installation
(nous reviendrons sur le traitement
des erreurs un peu plus loin).
En B se trouve un autre membre
copy qui a la structure de données à  laquelle
l’API renvoie les données. En
fait, dans le membre copy, il y a plus
d’une structure de données définie,
chacune montrant davantage de données
que la première. Le but est de
permettre de renvoyer des données
différentes à  des coûts différents (overhead
de traitement). On choisit la
structure de données voulue quand on
appelle l’API. (Pour une liste des API et
de leurs fonctions, visitez l’Info Center
d’IBM à  http://publib.boulder.ibm.com/iseries/v5r2/is2924/info/apis/api.
htm.)
L’API utilise les champs de travail
en C. La « *ENTRY PLIST (en D) transmet
le nom de la bibliothèque au programme.
La sous-routine *INZSR en E
initialise la structure d’erreur afin
qu’un simple RESET restaure les valeurs.
Comme ce programme est la fondation
sur laquelle nous construisons
le reste de l’utilitaire (que la 2e partie
couvrira), nous plaçons l’appel d’API
dans la sous-routine INIT en F (la raison
pour agir ainsi s’éclairera à  l’examen
de la figure 2). Donc, dans la sousroutine
INIT, nous allons

• redéfinir la structure de données
  d’erreur pour l’appel d’API

• définir la longueur conformément à 
  la structure de données qui contiendra
  les données renvoyées ; la longueur
  peut être plus courte que la
  structure, pourvu que la longueur
  couvre les champs de la structure
  que nous voulons utiliser (si nous
  spécifions une longueur supérieure,
  l’API risque de dépasser la longueur
  réelle de la structure de données et
  de corrompre la zone de stockage où
  le programme range ses variables)

• dire à  l’API quel format de données
  nous aimerions voir renvoyé (dans
  ce cas, nous choisissons le premier
  format ‘OBJD0100’).

• spécifier le nom et la bibliothèque de
  l’objet sous la forme d’un champ de
  20 octets ; c’est courant dans les API
  et les données doivent être espacées
  en 10 + 10 sans séparateurs

• spécifier le type d’objet

Nous appelons ensuite l’API et lui
passons notre structure de données
choisie, les champs que nous avons
préparés et la structure d’erreur API.
Après l’appel, nous testons la structure
d’erreur pour rechercher les erreurs.
S’il y en a, nous faisons échouer le programme
en appelant *PSSR.
Si nous examinions un dump qui a
été produit en appelant le programme
avec une bibliothèque incorrecte (ou
un nom de bibliothèque pas entièrement
en majuscules), nous verrions
que la structure de données que nous
avons entrée dans l’API – QUSD0100 –
est inchangée (elle est restée vierge).
L’API a défini 26 comme octets disponibles,
mais les octets fournis restent à 
16 – la différence étant de 10 octets,
servant à  contenir les données de substitution
pour le message d’erreur
(CPF9810) (il contient le nom de la bibliothèque
incorrecte que nous avons
demandée) si la structure de données
est suffisamment longue.