Récupération de la méthode de sortie.

28/03/2010
La plupart des utilitaires IBM (DSPPFM, DSPSPLF, DSPFD, DSPFFD, DSPJOB) positionnent deux indicateurs selon que la touche de fonction F3 ou F12 utilisée pour mettre fin à l’affichage. Récupérer cet indicateur peut être utile pour améliorer la navigation de l’utilisateur. N’importe quel programme peut positionner ces indicateurs

Les fonctions systèmes

Deux fonctions systèmes permettent de manipuler les indicateurs de sortie.
« Change Current Job » QWCCCJOB permet de positionner les indicateurs
« Retrieve Job Information » QUSRJOBI permet de lire les informations sur un travail dont les indicateurs de sortie.

Retrieve Job Information

La fonction Retrieve Job Information permet de récupérer de nombreuses informations sur un travail.
Le premier paramètre est la structure de données qui va recevoir les informations. Le format de cette structure dépend du type d'informations attendues.
Le deuxième paramètre donne la longueur de la structure passée dans le premier paramètre.
Le troisième paramètre indique le type de données attendues. C'est le nom de format de la structure passée au premier paramètre.
Voici un programme exemple :
H DFTACTGRP(*NO) ACTGRP(*CALLER)        
DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++++++Comments++++++++++++
 /copy API_WRK 
 /copy API_CMD
 /copy API_ERR
 /copy API_MSG
 * -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --                              
 * Procédure frontale pour récupération des indicateurs de sortie                                       
DGetExtCan        PR                                                                                    
D   ExitFlag                     1N                                                                     
D   CancelFlag                   1N                                                                     
 * -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --                              
D ErrDS           DS                  likeds(ERRAPI)                       Structure d'erreur OS        
D Cmd             S            250A   varying                              Ligne de commande            
D Cancel          S              1N                                        Indicateur F12               
D Exit            S              1N                                        Indicateur F3                
 * -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --                              
 /free                                                                                                  
   cmd = 'DSPJOB OPTION(*PGMSTK)';                            // Afficher la liste des appels programme 
   QCmdExc(Cmd : %len(cmd));                                  // Exécuter la commande
   GetExtCan( Exit : Cancel);                                 // Récupération des indicateurs 
   // Analyse des indicateurs                                                                 
   SELECT;                                                                                    
      when Exit;                                                                              
        Cmd = 'Sortie par F3.';                               // Exit                         
      when Cancel;                                                                            
        Cmd = 'Sortie par F12.';                              // Cancel                       
      when not (Exit or Cancel);                                                              
        Cmd = 'Sortie par ENTREE';                            // Entrée                       
   ENDSL;                                                                                     
   SndMsg( 'CPF9897' : CpfMsgf : Cmd : %len(Cmd) :                                            
           '*INFO' : '*PGMBDY' : 1 : *BLANK : ErrDS);                                         
                                                                                              
   SetJobKey( RstKey : ErrDS);                          // Remise à zéro des indicateurs      
                                                                                              
   return;                                                                                    
 /end-free                                                                                    
 * -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --                    
 * Procédure frontale de récupération des indicateurs                                         
 * -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --                    
PGetExtCan        B                                                                                     
D                 PI                                                                                    
D   ExitFlag                     1N                                                                     
D   CancelFlag                   1N                                                                     
 * -- -- -- -- -- -- -- -- -- -- -- --                                                                  
DInfDta           DS                  LIKEDS(JOBI0600)                     Structure retournée pas l'API
 * -- -- -- -- -- -- -- -- -- -- -- --                                                                  
 /free                                                                                                  
    RtvJobI( InfDta : %len(InfDta) : 'JOBI0600' : '*' : *BLANK);   // Retrieve Job Informations         
    ExitFlag = InfDta.ExitKey;                                     // Get Exit indic                    
    CancelFlag = InfDta.CancelKey;                                 // Get Cancel indic                  
 /end-free                                                                                              
PGetExtCan        E                                                                                     
  • Les membres en /COPY contiennent les prototypes des fonctions système et les définitions de structures de données de l'OS. Vous pouvez les télécharger depuis QRPGLESRC_API.zip ou API_WRK.txt, API_CMD.txt, API_ERR.txt, API_MSG.txt,
  • La procédure GetExtCan permet de simplifier la récupération des indicateurs. Pour un usage fréquent il est de bon ton de placer cette procédure dans un module contenant d'autre fonctions frontales de ce type.

Change Current Job

Permet de modifier la valeur des deux indicateurs Cancel Key et Exit Key. La fonction attend en paramètre une structure de données de longueur variable et une structure de retour d’erreur.
Le premier champ de la structure indique le nombre d’attributs modifiés.
Le reste de du paramètre contient une ou plusieurs structures pour indiquer les attributs a modifier et leur valeurs.
Nombre d’attributsEntier(4)
Description des attributs modifiéschar(*)

La structure de description de l’attribut comporte trois champs :

Clef Entier(4)
Longueur de données Entier(4)
La valeur de la donnée Variable


La valeur de la clef peut être :
1 Positionnement du champ Exit key
Positionnement du champ Cancel key
La valeur de longueur de données est toujours à un puisque la donnée sera ‘1’ ou ‘0’ selon que l’on veuille activer ou désactiver l’indicateur.

Pour simplifier l’utilisation de cette fonction on va définir 3 structures de données dans un membre source en copie.
 * Structure pour lever l’indicateur Exit (Touche F3)
DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++++++Comments++++++++++++
DSetExit          DS                                                                          
D                               10I 0 INZ(1)                               Nombre d'attributs 
D                               10I 0 INZ(1)                               Clef pour Exit (F3)
D                               10I 0 INZ(1)                               Longueur de donnée 
D                                1A   INZ('1')                             Valeur 1 (*ON)     
 * Structure pour lever l’indicateur Cancel (Touche F12)
DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++++++Comments++++++++++++
DSetCancel        DS                                                                             
D                               10I 0 INZ(1)                               Nombre d'attributs    
D                               10I 0 INZ(2)                               Clef pour Cancel (F12)
D                               10I 0 INZ(1)                               Longueur de donnée    
D                                1A   INZ('1')                             Valeur 1 (*ON)        

 * Structure pour abaisser les deux indicateurs
DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++++++Comments++++++++++++
DRstKey           DS                          
D                               10I 0 INZ(2)                               Nombre d'attributs
 * Indicateur Cancel
D                               10I 0 INZ(2)                               Clef pour cancel
D                               10I 0 INZ(1)                               Longueur de donnée
D                                1A   INZ('0')                             Valeur 0 (*OFF)
D                               10I 0 INZ(1)                               Clef pour exit
D                               10I 0 INZ(1)                               Longueur de donnée
D                                1A   INZ('0')                             Valeur 0 (*OFF)
Pour utiliser ces structures on définie le prototype de la fonction et la structure de retour d’erreur.
 * Change Current Job (QWCCCJOB) API                         
DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++++++Comments++++++++++++
DSetJobKey        PR                  EXTPGM('QWCCCJOB')     
D  ChgInf                       20A   CONST OPTIONS(*VARSIZE)
D  ErrorCode                   200A   OPTIONS(*VARSIZE)      

 * Structure d'erreur 
DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++++++Comments++++++++++++
DErrApi           DS                   qualified                                          
D  ErrLen                       10I 0  inz(%len(ErrApi))                   Bytes provided 
D  ErrRtn                       10I 0                                      Bytes available
D  ErrId                         7A                                        Exception ID   
D                                1A                                        Reserved  data 
D  ErrData                   32767A                                        Exception data 
Nous pouvons alors positionner les indicateurs en fonction de la touche utilisée pour sortir du programme.
          when Fkey  = F3;
             SetJobKey(SetExit);
             *INLR = *ON;
             return;
          when Fkey  = F12;
             SetJobKey(SetCancel);
             *INLR = *ON;
             return;
… A charge du programme appelant de lire ces indicateurs pour assurer la suite du scenario.

Fichiers

QRPGLESRC_API.zip Fichier zip avec les fichiers suivant:
  • API_WRK.txt avec les prototypes des fonctions système Retrieve Job infomation et Change Current Job ainsi que les définitions de structures de données utilisées par ces API.
  • API_CMD.txt avec les prototypes des fonctions système pour exécuter des commandes. Le membre contient notamment le prototype de QCMDEXC.
  • API_ERR.txt avec les définitions des structures d'erreur renvoyées par les fonctions systèmes (API)
  • API_MSG.txt avec les prototypes de gestion des messages (Envoie, réception...)