Les API système, ce que le langage ne sait pas faire

Exemple 1 Une file de données

QSNDDTAQ et QRCVDTAQ : des commandes entre deux programmes

Une file de données (*DTAQ) fait passer des messages d'un programme à un autre, du même travail ou d'un autre : l'un dépose, l'autre retire, dans l'ordre d'arrivée. Ici, ENVOICL dépose trois commandes et un programme RPG les lit. La file a été créée par la commande CRTDTAQ, que lance le programme de l'exemple 2 :

CRTDTAQ DTAQ(JOBIAPI/COMMANDES) MAXLEN(50) TEXT('Commandes a traiter')

CL ENVOICL

/* ENVOICL : dépose trois commandes dans la file COMMANDES        */
/* par l'API QSNDDTAQ (un programme : on l'appelle par CALL).     */
             PGM
             DCL        VAR(&LONG) TYPE(*DEC) LEN(5 0) VALUE(50)
             DCL        VAR(&DATA) TYPE(*CHAR) LEN(50)

             CHGVAR     VAR(&DATA) VALUE('CDE-0001 ACM    3 x Clavier')
             CALL       PGM(QSNDDTAQ) PARM('COMMANDES' 'JOBIAPI' &LONG &DATA)
             CHGVAR     VAR(&DATA) VALUE('CDE-0002 BTP    1 x Ecran 27p')
             CALL       PGM(QSNDDTAQ) PARM('COMMANDES' 'JOBIAPI' &LONG &DATA)
             CHGVAR     VAR(&DATA) VALUE('CDE-0003 ACM   10 x Souris')
             CALL       PGM(QSNDDTAQ) PARM('COMMANDES' 'JOBIAPI' &LONG &DATA)

             SNDPGMMSG  MSG('3 commandes déposées dans COMMANDES')
             ENDPGM

RPG IV colonné RECOIT4

*...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
     H* RECOIT4 : lit les commandes en attente dans la file COMMANDES
     DLONGUEUR         S              5P 0
     DDONNEES          S             50A
     DATTENTE          S              5P 0 INZ(0)
     DNOMBRE           S             10I 0
     DTEXTE            S             52A
     C* CALL et PARM : l'appel d'un programme, a l'ancienne
     C* Attente 0 : rend la main tout de suite ; longueur 0 = file vide
     C                   DOU       LONGUEUR = 0
     C                   CALL      'QRCVDTAQ'
     C                   PARM      'COMMANDES'   FILE             10
     C                   PARM      'JOBIAPI'     BIB              10
     C                   PARM                    LONGUEUR
     C                   PARM                    DONNEES
     C                   PARM                    ATTENTE
     C                   IF        LONGUEUR > 0
     C                   EVAL      NOMBRE = NOMBRE + 1
     C     DONNEES       DSPLY
     C                   ENDIF
     C                   ENDDO
     C                   EVAL      TEXTE = 'Commandes lues : ' + %CHAR(NOMBRE)
     C     TEXTE         DSPLY
     C                   EVAL      *INLR = *ON

Full free RECOITF

**FREE
// RECOITF : lit les commandes en attente dans la file COMMANDES
dcl-pr QRCVDTAQ extpgm('QRCVDTAQ');
  file char(10) const;
  bibliotheque char(10) const;
  longueur packed(5:0);
  donnees char(50);
  attente packed(5:0) const;
end-pr;

dcl-s longueur packed(5:0);
dcl-s donnees char(50);
dcl-s nombre int(10);

// Attente 0 : l'API rend la main tout de suite ; longueur 0 = file vide
dow '1';
  QRCVDTAQ('COMMANDES' : 'JOBIAPI' : longueur : donnees : 0);
  if longueur = 0;
    leave;
  endif;
  nombre += 1;
  dsply %subst(donnees : 1 : longueur);
enddo;
dsply ('Commandes lues : ' + %char(nombre));
*inlr = *on;

CALL 'QRCVDTAQ' et ses PARM

En colonné, l'appel d'un programme à l'ancienne : un PARM par paramètre, dans l'ordre de la documentation. Les littéraux 'COMMANDES' et 'JOBIAPI' vont dans des zones de 10 caractères, définies sur la ligne du PARM.

dcl-pr QRCVDTAQ extpgm('QRCVDTAQ');

En full free, un prototype : le compilateur vérifie le nombre et le type des paramètres. Le mot-clé const marque ceux que l'API ne modifie pas : on peut alors passer des littéraux.

longueur packed(5:0) et attente packed(5:0)

Les types de la documentation, à respecter : Packed(5,0). Une attente de 0 rend la main tout de suite, avec une longueur de 0 si la file est vide ; négative, l'API attend sans fin ; positive, elle attend ce nombre de secondes.

CALL QCMD
ADDLIBLE JOBIAPI
CALL ENVOICL
CALL RECOITF
CALL ENVOICL
CALL RECOIT4

Exemple 2 Une commande depuis le RPG

QCMDEXC : exécuter une commande CL

Le RPG n'a pas d'instruction pour lancer une commande CL : QCMDEXC le fait. Deux paramètres : la commande, puis sa longueur en packed(15:5). CMDF crée la file de l'exemple 1 :

**FREE
// CMDF : cree la file COMMANDES par l'API QCMDEXC
dcl-pr QCMDEXC extpgm('QCMDEXC');
  commande char(3000) const options(*varsize);
  longueur packed(15:5) const;
end-pr;

// Statut du programme : identifiant du dernier message d'erreur
dcl-ds etat psds qualified;
  message char(7) pos(40);
end-ds;

dcl-s commande varchar(200);

commande = 'CRTDTAQ DTAQ(JOBIAPI/COMMANDES) MAXLEN(50) '
         + 'TEXT(''Commandes a traiter'')';
monitor;
  QCMDEXC(commande : %len(commande));
  dsply 'File COMMANDES creee';
on-error;
  dsply ('CRTDTAQ refuse : ' + etat.message);
endmon;
*inlr = *on;

commande char(3000) const options(*varsize)

La commande est passée telle quelle ; sa vraie longueur est donnée par le second paramètre, %len(commande).

monitor; … on-error;

Une commande qui échoue envoie son message d'erreur au programme. MONITOR l'intercepte, et l'identifiant du message se lit dans la structure d'état du programme (psds, positions 40 à 46).

En SQL, la procédure QSYS2.QCMDEXC rend le même service.

Exemple 3 Le code erreur en pratique

QUSROBJD : la description d'un objet

QUSROBJD remplit une zone, le récepteur, avec la description d'un objet, selon un format : OBJD0100 pour l'essentiel, OBJD0200 pour davantage de champs, dont l'attribut et le texte. Le programme décrit le format par une structure, aux positions de la documentation :

**FREE
// OBJDF : description d'un objet par l'API QUSROBJD
dcl-pi *n;
  objet char(10);
  type char(10);
end-pi;

dcl-pr QUSROBJD extpgm('QUSROBJD');
  recepteur char(32767) options(*varsize);
  longueur int(10) const;
  format char(8) const;
  nomQualifie char(20) const;
  typeObjet char(10) const;
  erreur likeds(codeErreur);
end-pr;

// Debut du format OBJD0200, aux positions donnees par la documentation
dcl-ds objd0200 qualified;
  octetsRendus int(10);
  octetsDispo int(10);
  nom char(10);
  bibliotheque char(10);
  type char(10);
  bibRetour char(10);
  asp int(10);
  proprietaire char(10);
  domaine char(2);
  creation char(13);
  modification char(13);
  attribut char(10);
  texte char(50);
end-ds;

// Code erreur : octets fournis > 0, l'API y range l'erreur
// au lieu d'envoyer un message d'exception
dcl-ds codeErreur qualified;
  fournis int(10) inz(%size(codeErreur));
  disponibles int(10) inz(0);
  message char(7);
  *n char(1);
  donnees char(100);
end-ds;

QUSROBJD(objd0200 : %size(objd0200) : 'OBJD0200'
        : objet + '*LIBL' : type : codeErreur);
if codeErreur.disponibles > 0;
  dsply ('Erreur ' + codeErreur.message + ' sur ' + %trim(objet));
else;
  dsply (%trim(objd0200.bibRetour) + '/' + %trim(objd0200.nom)
        + ' proprietaire ' + objd0200.proprietaire);
  dsply objd0200.texte;
endif;
*inlr = *on;

La même API, avec un code erreur dont les octets fournis valent 0 :

**FREE
// OBJEXCF : QUSROBJD avec un code erreur de 0 octet fourni
dcl-pi *n;
  objet char(10);
  type char(10);
end-pi;

dcl-pr QUSROBJD extpgm('QUSROBJD');
  recepteur char(32767) options(*varsize);
  longueur int(10) const;
  format char(8) const;
  nomQualifie char(20) const;
  typeObjet char(10) const;
  erreur likeds(codeErreur);
end-pr;

dcl-ds etat psds qualified;
  message char(7) pos(40);
end-ds;

dcl-s recepteur char(100);

// Octets fournis = 0 : l'API envoie l'erreur en message d'exception
dcl-ds codeErreur qualified;
  fournis int(10) inz(0);
  disponibles int(10) inz(0);
end-ds;

monitor;
  QUSROBJD(recepteur : %size(recepteur) : 'OBJD0100'
          : objet + '*LIBL' : type : codeErreur);
  dsply ('Objet trouve : ' + %trim(objet));
on-error;
  dsply ('Exception ' + etat.message + ', statut ' + %char(%status));
endmon;
*inlr = *on;

CALL OBJDF PARM(COMMANDES '*DTAQ')
CALL OBJDF PARM(INCONNUE '*DTAQ')
CALL OBJEXCF PARM(INCONNUE '*DTAQ')

Le programme passe *LIBL comme bibliothèque : celle où l'objet a été trouvé revient dans bibRetour, ici JOBIAPI. Le texte affiché est celui donné à CRTDTAQ.

Exemple 4 Une API procédure

QsnWrtDta : écrire sur l'écran sans DSPF

Les API DSM (Dynamic Screen Manager) pilotent l'écran 5250 directement : effacer, écrire un texte à une ligne et une colonne, attendre une touche. Ce sont des procédures du programme de service QSNAPI : le programme est ILE, d'où dftactgrp(*no), et les prototypes utilisent EXTPROC.

**FREE
// ECRANF : ecrit sur l'ecran 5250 avec les API DSM (procedures ILE)
ctl-opt dftactgrp(*no) actgrp(*new);

dcl-ds codeErreur qualified template;
  fournis int(10);
  disponibles int(10);
  message char(7);
  *n char(1);
end-ds;

dcl-pr QsnClrScr int(10) extproc('QsnClrScr');
  mode char(1) const options(*omit);
  tampon int(10) const options(*omit);
  environnement int(10) const options(*omit);
  erreur likeds(codeErreur) options(*omit);
end-pr;

dcl-pr QsnWrtDta int(10) extproc('QsnWrtDta');
  donnees char(132) const options(*varsize);
  longueur int(10) const;
  zone int(10) const options(*omit);
  ligne int(10) const;
  colonne int(10) const;
  attributDebut char(1) const options(*omit);
  attributFin char(1) const options(*omit);
  couleurDebut char(1) const options(*omit);
  couleurFin char(1) const options(*omit);
  tampon int(10) const options(*omit);
  environnement int(10) const options(*omit);
  erreur likeds(codeErreur) options(*omit);
end-pr;

dcl-pr QsnGetAID char(1) extproc('QsnGetAID');
  touche char(1) options(*omit);
  tampon int(10) const options(*omit);
  environnement int(10) const options(*omit);
  erreur likeds(codeErreur) options(*omit);
end-pr;

// Attributs 5250 : 20 normal (vert), 21 inverse, 22 blanc,
// 30 turquoise, 32 jaune, 28 rouge ; sur un ecran couleur,
// c'est l'attribut de couleur qui compte
dcl-c NORMAL x'20';
dcl-c BLANC x'22';
dcl-c INVERSE x'21';
dcl-c TURQUOISE x'30';
dcl-c JAUNE x'32';
dcl-c ROUGE x'28';

dcl-s texte varchar(80);
dcl-s touche char(1);

// Mode '0' : effacer l'ecran et passer en 24 x 80
QsnClrScr('0' : *omit : *omit : *omit);

texte = 'Ecran ecrit par QsnWrtDta';
QsnWrtDta(texte : %len(texte) : 0 : 2 : 27
         : BLANC : NORMAL : BLANC : NORMAL : *omit : *omit : *omit);
texte = ' Pas de DSPF : le programme place lui-meme chaque texte ';
QsnWrtDta(texte : %len(texte) : 0 : 5 : 11
         : INVERSE : NORMAL : INVERSE : NORMAL : *omit : *omit : *omit);
texte = 'Ligne 8, colonne 11, en jaune';
QsnWrtDta(texte : %len(texte) : 0 : 8 : 11
         : NORMAL : NORMAL : JAUNE : NORMAL : *omit : *omit : *omit);
texte = 'Ligne 10, colonne 30, en rouge';
QsnWrtDta(texte : %len(texte) : 0 : 10 : 30
         : NORMAL : NORMAL : ROUGE : NORMAL : *omit : *omit : *omit);
texte = 'Appuyez sur Entree ou sur F3';
QsnWrtDta(texte : %len(texte) : 0 : 22 : 2
         : NORMAL : NORMAL : TURQUOISE : NORMAL : *omit : *omit : *omit);

// QsnGetAID attend une touche et rend son code AID
touche = QsnGetAID(*omit : *omit : *omit : *omit);
if touche = x'33';
  dsply 'Touche lue : F3';
elseif touche = x'F1';
  dsply 'Touche lue : Entree';
else;
  dsply 'Touche lue : une autre';
endif;
*inlr = *on;

options(*omit)

Les paramètres facultatifs des API DSM (tampon de commandes, environnement, code erreur) sont omis : l'API prend alors l'écran courant et ses valeurs par défaut.

QsnWrtDta(texte : %len(texte) : 0 : ligne : colonne : …)

Le texte, sa longueur, 0 pour « pas d'identifiant de zone » (le texte se place alors par ligne et colonne), la ligne et la colonne, puis les attributs de début et de fin : monochrome, puis couleur. Sur un écran couleur, c'est l'attribut de couleur qui compte : x'21' en couleur donne la vidéo inverse.

QsnGetAID

Attend une touche et rend son code AID : x'F1' pour Entrée, x'33' pour F3.

Pour un vrai écran de saisie, un DSPF reste plus simple à écrire et à maintenir. DSM sert aux outils qui construisent leur écran à l'exécution.