Les API

détaillées que les commandes ou
les catalogues. Mais, l’utilisation d’API pour accéder aux métadonnées présente
un inconvénient : leur complexité. Alors que l’on peut utiliser SQL ou
un utilitaire de fichiers pour travailler avec les catalogues OS/400 et SQL, la
programmation qu’exige l’utilisation des API sera parfois très importante.

La figure 2 présente la liste des API
disponibles pour accéder aux métadonnées AS/400 :

• QDBRTVFD extrait la description d’un fichier
  ou d’un format.
  
  
• QUSLOBJ envoie la liste des objets d’une
  bibliothèque dans un espace utilisateur. On peut limiter la liste à  un
  type d’objet, comme *FILE.
  
  
• QDBLDBR envoie la liste des informations
  relationnelles concernant un fichier à  un espace utilisateur.
  
  
• QUSLRCD envoie une liste de formats
  d’enregistrement d’un fichier dans un espace utilisateur.
  
  
• QUSLFLD envoie la liste des champs d’un
  fichier dans un espace utilisateur.
  
  

Les API sont idéales pour programmer des
utilitaires en privilégiant vitesse et souplesse. Ainsi, dans l’article
"Convertir ses données AS/400 pour FTP", NEWSMAGAZINE, janvier 1998,
je montrais comment utiliser la commande utilitaire CPYTORMTF pour convertir un
fichier base de données  OS/400 en
variables séparées par des virgules, transmissibles à  un autre système. La
commande utilise l’API QUSLFLD pour extraire les définitions de champs d’un
fichier sélectionné. Les définitions sont ensuite utilisées pour extraire et
convertir les champs provenant des enregistrements du fichier. Le code de la
figure 4 montre comment la commande CPYTORMTF extrait des définitions de champs
d’un fichier. Tout d’abord le programme (en A) copie les membres d’en-tête
pour les programmes de service dans les champs de liste (FldLstH) et manipule
les listes dans les espaces utilisateur (UsrLstH). (Note du Traducteur :
phrase anglaise précédente ambiguà«). Deuxièmement, les cartes D (en B) définissent
un tableau de définitions de champs (FldDefAry) pour être comme une définition
de champ (FldDefDs). Troisièmement, la sous-routine GetFldDefs (en C) utilise
les procédures provenant des programmes de service FldLst et UsrLst pour
extraire les définitions de champs suivantes :

• CreateUsrLst, qui crée une liste
  d’utilisateurs (c’est-à -dire, un espace utilisateur contenant une
  liste)
  
  
• LoadFldLst, qui charge une liste de champs
  d’un format de fichiers dans la liste d’utilisateurs
  
  
• NextUsrLstEnt, qui extrait l’entrée
  suivante de la liste d’utilisateurs
  
  
• DeleteUsrLst, qui supprime la liste
  d’utilisateurs
  
  

Pour bien utiliser les API, l’astuce consiste
à  les encapsuler dans des programmes de service, comme l’illustre la figure
4. On accède à  chaque programme de service via un membre d’en-tête
contenant un prototype pour chacune de ses procédures et définitions pour les
variables et constantes requises pour utiliser les procédures. Le code de la
figure 5 montre le membre d’en-tête du programme de service FldLst, qui liste
les champs présents dans un format de fichier. Le membre FldLstH prototype la
procédure LoadFldLst (en A) et définit la structure de données LstFldDs (en
B) qui stocke une entrée de la liste. L’utilisation des programmes de service
et des membres d’en-tête dispense de "réinventer la roue" chaque
fois qu’on utilise une API.

            On
peut accéder aux métadonnées de manière directe en utilisant les API
(QUSLOBJ, QDBLDBR, QUSLRCD et QUSLFLD) de la liste. Mais pour obtenir des
informations de fichiers plus détaillées, une seule API fera l’affaire :
QDBRTVFD. Cette API renvoie des informations dans une mémoire tampon pouvant
contenir des centaines d’occurrences de nombreuses structures de données
uniques auxquelles on accède par divers moyens : pointeurs, différences
(offsets) et compteurs. Le problème posé par QDBRTVFD ne se situe pas dans son
appel, mais dans la navigation à  l’intérieur de la mémoire tampon qu’elle
renvoie. Pour simplifier l’utilisation de cette API, le kit RPG IV Tools (téléchargeable
depuis l’adresse http://www.newsmag.com) contient le programme de
service FilDsc, qui inclut les procédures suivantes pour extraire la
description d’un fichier :

• GetFilDsc, qui envoie une description de
  fichier à  un espace utilisateur et initialise un pointeur sur la première
  structure de données dans l’espace utilisateur
  
  
• NextFilDscEnt, qui extrait le pointeur et le
  type de la prochaine structure de données depuis l’espace utilisateur
  
  
• ResetFilDsc, qui repositionne le pointeur sur
  la première structure de données dans l’espace utilisateur
  
  

Les procédures GetFmtDsc, NextFmtDscEnt et
ResetFmtDsc du programme de service FilDsc offrent une fonctionnalité similaire
pour extraire la description d’un format de fichier. Les tableaux des figures
6a et 6b contiennent les structures de données renvoyées par les procédures.
Toutes les structures de données sont définies dans le membre copie FilDscH du
kit.

            Le
code de la figure 7 montre comment extraire une description de fichier en
utilisant FilDsc. Le programme copie d’abord (en A) les membres d’en-tête
pour les programmes de service FilDscH et UsrSpcH (qui manipule les espaces
utilisateurs). Ensuite, les carte D (en B) définissent les variables d’un
espace utilisateur qui contiendra la description de fichier (FilSpcxxx)
et les variables permettant d’accéder à  l’entrée suivante dans la
description de fichier (FilEntxxx). Enfin, la sous-routine ProcFilDsc (en
C) utilise les procédures des programmes de service FilDsc et UsrSpc pour
traiter la description de fichier ci-dessous :

• CreateUsrSpc crée un espace utilisateur qui
  contiendra la description de fichier.
  
  
• GetUsrSpcPtr extrait un pointeur sur
  l’espace utilisateur.
  
  
• GetFilDsc place la description d’un fichier
  dans l’espace utilisateur.
  
  
• NextFilDscEnt extrait les détails de la
  prochaine entrée, de l’espace utilisateur. FilEntTyp identifie la
  structure de données sur laquelle pointe FilEntPtr. Le bloc Select à 
  l’intérieur de la boucle DoW traite les structures de données requises
  par le programme.
  
  
• DeleteUsrSpc supprime l’espace utilisateur.