, 5 raisons pour utiliser Isphere

Isphere est un plugin eclipse que l’on peut installer sous RDi et qui apporte des fonctionnalités complémentaires

Raison 1

Il est gratuit, donc ça ne coûte rien de l’installer pour voir !
et c’est un produit open source vous pouvez même participer à son évolution


Raison 2

Vous avez un comparateur de sources un peu plus simple, qui permet par exemple de comparer 3 Sources …

Raison 3

Sur la gestion de vos spools le plugin permet d’avoir beaucoup plus d’options
C’est également vrai sur la gestion des messages …

Raison 4

Vous avez un outil qui permet de chercher des informations dans des sources avec une grande facilité d’utilisation

Raison 5

Editer simplement le contenu d’un fichier message .

En conclusions :

Voici les principales options qu’on utilise chez GAIA

Il en existe d’autres, par exemple des options ILE sur les objets …

Plus toutes celles qu’on n’a pas trouvé encore !

, Premiers tests services web REST SQL

Une des fonctionnalités attendues disponible avec la 7.4 / 7.3 TR6 (SF99722 niveau 19) est la possibilité de déployer des services web (REST uniquement) basés sur des instructions SQL au lieu de programmes ILE.

 

Voici nos premiers tests, effectués « à vue » la documentation IBM n’étant pas encore disponible …

 

Services REST SQL

En bref, vous avez désormais les possibilités suivantes :

  • effectuer des SELECT, UPDATE, INSERT
  • appeler des fonctions SQL utilisateur (UDF), des fonctions tables (UDTF)
  • appeler des procédures stockées (procédures cataloguées)
  • utiliser directement la syntaxe VALUES …
  • retourner des données BINAIRES (images, pdf, …)

De plus, IWS vous propose également un format de sortie HTML, en plus de JSON et XML déjà en place. De quoi faciliter l’intégration de vos données dans des pages web !

 

Comment fait-on ?

Déployer un nouveau service : vos avez maintenant la possibilité de choisir SQL

Comme d’habitude pour les services REST, vous indiquez nom de service et nom de ressource

Maintenant, vous avez des paramètres spécifiques à un service basé sur SQL vous permettant de régler les conventions de nommage et la résolution des objets non qualifiés dans vos requêtes. Le fonctionnement est habituel en SQL. Pour simplifier : basé sur la *LIBL en convention *SYS, sur un schéma par défaut en *SQL

Vous pouvez indiquer plusieurs « procédures » dans un service REST SQL, c’est à dire plusieurs opérations disponibles au travers de votre service, et identifiées (plus tard) par des URL et/ou des méthodes HTTP différentes

Pour commencer simplement :

Bien sûr, vous pouvez utiliser des paramètres dans vos requêtes SQL, identifiés par « ? » :

L’outil est plutôt bien fait de ce côté-là : il est capable de détecter le type des données correspondant à vos paramètres en analysant le fichier :

Vous devez ensuite régler le comportement attendu de votre traitement :

la suite des écrans est classique et ne présente pas de particularité dû au SQL, en dehors du type de sortie *HTML proposé.

Quelques exemples de résultats fournis par les appels de différents services (renvoyant une ligne ou plusieurs lignes, en JSON, en XML, en HTML …) :

 

L’outil vous permet également d’obtenir des informations sur l’exécution et les erreurs SQL :

 

Données binaires

Maintenant, passons à la possibilité qui ouvre d’autres perspectives !

Avec les services basés sur des programmes ILE RPG/COBOL, nous n’arrivons pas à retourner des images ou documents binaires : toutes les données sont converties en UTF-8 (par défaut) pour sortir sur le flux HTTP. Nos données binaires ne supportent pas bien … seule solution jusqu’ici : encoder en base64 (c’est à dire en caractères) ! Mais cela complexifie, nécessite du temps machine et augmente la taille de la sortie.

Lors du déploiement, sélectionner le type « Media resource »

Vous devez indiquer le type de ressource (seule la première valeur est prise en compte) :

Dès lors, vos services web peuvent retourner des documents (au sens large), par exemple un pdf accessible depuis un navigateur :

Ou une image (vous devriez reconnaître) :

 

Adaptation des scripts shell

Un nouveau script shell a fait son apparition dans /qibm/proddata/os/webservices/bin : getConfigurationFile.sh

 

Les informations disponibles actuellement : https://www.ibm.com/developerworks/community/wikis/home?lang=en#!/wiki/dW%20IBM%20Integrated%20Web%20Services%20for%20i/page/Script%20to%20generate%20property%20file%20for%20a%20service

Ce dernier génère deux fichiers pour un service :

  • un fichier .properties
  • un fichier .xml

Le fichier properties contient les attributs du service, des procédures/méthodes, du connecteur jdbc.

Le fichier xml est en réalité un fichier pcml contenant des balises spécifiques utilisées pour le déploiement d’un service.

Ces formats de fichiers permettront également le déploiement par script shell (avec installWebService.sh) des services REST SQL.

 

 

En conclusion

L’outil poursuit sa belle évolution, avec toujours plus de fonctionnalités et de possibilités ! Nous compléterons prochainement avec des tests plus approfondis.

D’ici là, bonnes vacances à tous, et rendez-vous à la rentrée, reposé et bronzé !

,

Contrôler ses données avec SQL as a service

 

L’arrivée de la function table joblog_info qui permet de voir la log d’un travail ouvre de nouvelles manières de travailler.

En voici une qui va vous permettre de savoir si vous avez des données erronées dans vos fichiers PF.

Quand vous faites une requête avec un select sur un pf qui a des données en erreur, en fonction de votre interface vous obtenez des ++++ ou autres qui vous indique que vos données sont en erreur !

Mais surtout ça génère un message CPF5035 dans votre log qui vous indique la ligne et la zone en erreur

Exemple :

select substr(MESSA00007, 1, 10) as fichier ,
substr(MESSA00007, 21, 10) as biblio,
substr(MESSA00009, 55, 71) as texte
from table(qsys2.joblog_info(‘*’)) a
where MESSAGE_ID = ‘CPF5035’

Qui vous donnera

CLIENTS GAIA la zone CLIENTS_1.CAANC, numéro d’enreg 213, format *FIRST, membre
CLIENTS GAIA la zone CLIENTS_1.CAAN1, numéro d’enreg 213, format *FIRST, membre
CLIENTS GAIA la zone CLIENTS_1.CAAN2, numéro d’enreg 213, format *FIRST, membre

Ici on voit que sur l’enregistrement 213 (rang relatif) a des zones CAANC, CAAN1 et CAAN2  qui ont des données en erreur

Vous pouvez corriger facilement en faisant

update gaia.clients a set caanc = 0 where rrn(a) = 213

Voici un petit script CLLE qui vous permettra de savoir si un PF à des données en erreur

pgm parm(&table &lib)
dcl &table *char 10
dcl &lib *char 10
chkobj &lib/&table *file
RUNSQL SQL(‘drop table qtemp/wtest’) COMMIT(*NONE)
monmsg SQL9010
RUNSQL SQL(‘create table qtemp/wtest as (select * +
from’ *BCAT &LIB *TCAT ‘/’ *TCAT &TABLE +
*bcat ‘)with data’) COMMIT(*NONE)
monmsg SQL9010 exec(do)

/* ici votre traitement pour récupérer les erreurs CPF5035 */
/* select substr(MESSA00009, 55, 71) as texte */
/* from table(qsys2.joblog_info(‘*’)) a */
/* where MESSAGE_ID = ‘CPF5035’ */
/* vous devrez par exemple écrire ces données dans une table */

endpgm

Ce script est a améliorer en effet il ne donne que le premier enregistrement corrompu , sql interrompant le traitement à la première erreur.

,

Parser un tableau JSON avec l’opération SQL JSON_TABLE

L’opération SQL JSON_TABLE sert à extraire les données d’un flux JSON pour les intégrer en base de données.

Pour rappel, les services web REST renvoient  la plupart du temps des réponses en JSON.
L’opération fonctionne bien si le premier niveau hiérarchique du flux est un objet JSON,  pouvant lui-même contenir un tableau.
Prenons par exemple un flux JSON contenant l’objet « qteage » étant lui-même un tableau :

{
« qteage »: [
{
« agence »: « LY »,
« qte »: 567
},
{
« agence »: « PA »,
« qte »: 879
}
],
« code »: « OK »,
« message »: «  »
}

Nous pouvons récupérer les éléments du tableau sans problème par la requête :

select u.* from json_table( ‘{
« qteage »: [
{
« agence »: « LY »,
« qte »: 567
},
{
« agence »: « PA »,
« qte »: 879
}
],
« code »: « OK »,
« message »: «  »
}’, ‘strict $.qteage[*]’
COLUMNS( « CodAge » varchar(50) PATH ‘strict $.agence’ ,
« Quantite » decimal   PATH ‘strict $.qte’
)  ) AS U;

Par contre si le flux JSON renvoie directement un tableau, l’opération JSON_TABLE n’arrive plus à extraire les données :

Prenons par exemple, le flux suivant, qui est reconnu par les outils de validation en ligne :

Lorsque nous essayons de travailler avec ce flux, l’opération JSON_TABLE, ne fonctionne plus :

select u.* from json_table( ‘[
{
« agence »: « LY »,
« qte »: 567
},
{
« agence »: « PA »,
« qte »: 879
}
]’, ‘strict $.[*]’
COLUMNS( « CodAge » varchar(50) PATH ‘strict $.agence’ ,
« Quantite » decimal   PATH ‘strict $.qte’
)  ) AS U;

L’instruction est bien traitée, mais le résultat est vide :

IBM confirme que l’instruction attend un objet JSON et non un tableau sur le premier niveau hiérarchique.

Si vous êtes confronté à ce problème, vous n’aurez pas d’autre solution que de modifier le JSON reçu, pour ajouter un niveau hiérarchique qui englobera votre flux initial.

Par exemple par l’ajout de l’objet « data ». Votre flux deviendra :

{ « data » : 

[
{
« agence »: « LY »,
« qte »: 567
},
{
« agence »: « PA »,
« qte »: 879
}
] }

Vous pouvez le faire, entre autre, par SQL  :

SET :donnees = ‘{« data » : ‘ || trim(:donnees) || ‘}’ ;

Attention toutefois à l’encodage de votre résultat, le flux JSON d’origine est encodé en UTF8. Si le CCSID de votre machine est 65535, vous  devrez modifier le CCSID de travail pour que l’instruction SQL s’exécute sans erreur, soit au niveau du job, de l’utilisateur, de variables de travail…. Mais là c’est une autre histoire ! 

 

,

Retourner des documents grâce aux Web Services !

Vous êtes de plus en plus nombreux à utiliser IWS pour exposer des programmes (de service) ILE sous forme de service web ! Cette technique fonctionne bien : elle est simple, automatique, le code est écrit en RPG.

Mais utilisez vous toutes les possibilités fournies : XML ou JSON pour encapsuler les paramètres en sortie ?

De plus, nous sommes limités par le nombre de paramètres du code RPG :

  •  7 paramètres pour une procédure (SIC !!)
  • 256 paramètres pour un programme

 

Personnalisez vos services

Nous vous proposons aujourd’hui d’utiliser un type de media personnalisé en valeur de retour : vos services pourront retourner des documents de type XML, JSON, CSV, HTML, … en réalité tous les types usuels du web basés sur du texte.

 

Par exemple, la procédure suivante ramène les profils utilisateurs non système (la première lettre est différente de Q) et désactivés (une occasion de faire du ménage) :

Les paramètres :

  • data_LENGTH et data
    • longueur et valeur des données en sortie
  • httpStatus
    • permet le contrôle du code HTTP en retour par le programme RPG
    • un code 200 signifie OK et est celui généré automatiquement par l’outil. Un autre code connu : 404 NOT FOUND

 

Au déploiement du service vous devez indiquer certaines options :

On remarque :

  • HTTP response code output parameter -> httpStatus
  • Returned output media types -> application/xml

Cette dernière option signifie que la valeur de retour sera toujours un document XML

 

Exemple lors de l’appel depuis un navigateur :

Ici le navigateur se base sur le type indiqué pour le retour (application/xml) pour mettre en forme le résultat.

 

Encore plus !

Nous pouvons maintenant aller plus loin en rendant dynamique les types de données en sortie !

Par exemple, une procédure permettant de lire un fichier sur l’IFS dont le nom est transmis en paramètre, et de retourner son contenu :

Le nom du fichier à retourner est reçu dans le paramètre file.

Nous gérons dans le tableau httpHeaders() la valeur du type de contenu en retour via une entête HTTP Content-Type. Les valeurs usuelles sont listées ici : https://en.wikipedia.org/wiki/Media_type

Le type de contenu est défini en fonction de l’extension du fichier : application/xml pour tous les fichiers *.xml.

Si une extension n’est pas connu du programme, nous provoquons une erreur HTTP 406 NOT ACCEPTABLE.

De plus, si le fichier n’est pas trouvé, un code HTTP 404 NOT FOUND est généré.

 

Lors du déploiement, il est également nécessaire d’indiquer certaines options :

Principalement dans « Returned output media types » -> doit contenir la liste de tous les types de médias retournées par le programme. Une valeur qui ne serait pas présente ici sera interceptée par le serveur IWS et provoquera une erreur HTTP 500 (Internal Server Error) et aucune valeur ne sera retournée.

Les différentes valeurs sont séparées par des virgules :  application/xml, text/csv, text/html, text/plain.

Le swagger généré tient compte de ces informations pour une meilleur documentation et interopérabilité de vos services.

 

Lors des différents appels (les fichiers indiqués sur l’URL existent dans le répertoire /home/NB/ressources) :

 

Pour la gestion des cas d’erreur (extension non gérée ou fichier inexistant) :

 

Grâce à IWS, vos programmes RPG peuvent désormais facilement renvoyer tous types de documents, que le contenu soit statique (comme un fichier dans l’IFS) ou dynamique (calculé en live par votre programme). Et n’oubliez pas, DB2 offre de nombreuses possibilités (XML, JSON, accès à l’IFS …) qui sont donc directement utilisables en SQLRPGLE.

Prochaine étape : des fichiers binaires (image, pdf) !

, , ,

Sauvegarde restauration d’un serveur de webservices

Sauvegarde et Restauration des webservers

Pour Sauvegarder et Restaurer un server de webservices vous pouvez utiliser les scriptes QSH prévus à cet effet.

Sauvegarde

saveWebServicesServer.sh
-server ‘server’
-saveFile ‘savf’ (‘/qsys.lib/libsavf.lib/savf.file’)

Restauration

restoreWebServicesServer.sh
-fromServerDirectory ‘server-directory’ (‘/www/server’)
-saveFile ‘savf’ (‘/qsys.lib/libsavf.lib/savf.file’)

Remarque :

Le seul support est le SAVF

Mais comment restaurer un serveur de webservices, si vous n’avez que les répertoires de l’IFS.

Il faut savoir qu’un webserveur de webservices c’est 3 choses :

– des répertoires de configuration (dans /www/)
– une instance APACHE déclarée dans http server (fichier QATMHINSTC qui contient un membre pour chacun instance)
– un enregistrement dans LWI ou Liberty.

Il vous faudra donc respecter les étapes suivantes

1) Restauration des répertoires de L’IFS

  • RST DEV(‘/qsys.lib/qgpl.lib/savfIFS.file’)
    OBJ((‘/www/YOURSERVER’))
    Vous pouvez restaurer l’IFS à partir d’autres supports…

2) Autorisation de la branche du server au profil QTMHHTTP

Le profil QTMHHTTP est le profil utilisé par http server pour la plupart de ses opérations. Il doit avoir un droit explicite sur ces fichiers.

  • CHGAUT OBJ(‘/www/YOURSERVER/*’)
    USER(QTMHHTTP)
    DTAAUT(*RWX)
    OBJAUT(*ALL)
    SUBTREE(*ALL)

Remarque :

Cette étape peut être facultative si vous avez une sauvegarde avec les droits privées paramètres PVTAUT(*YES) de vos commandes SAVXXX.

Il vous faudra préciser dans la commande RST … le paramètre PVTAUT(*YES)

3) Création du membre de l’instance APACHE dans le fichier QATMHINSTC de QUSRSYS.

En utilisant la commande

wrkmbrpdm qusrsys/QATMHINSTC

Dupliquer un membre existant en lui donnant le nom de votre server YOURSERVER
puis modifier le contenu en lui indiquant le nom de votre serveur
-apache -d /www/YOURSERVER -f conf/httpd.conf

Cette modification peut-être faite, via l’option 18, par SQL, par script…

 

4) Enregistrement de votre serveur dans liberty ou LWI

Sous LWI

java -cp /QIBM/ProdData/OS400/jt400/lib/jt400Native.jar:/QIBM/ProdData/OS/OSGi/LWI81/native/iasadmin.jar com.ibm.lwi.admin.IntegratedServerAdmin -registerServer YOURSERVER /www

Remarque :
La version de votre lwi ici 8.1, dépend de votre système pour la connaitre :
Se mettre sous qsh
cd /QIBM/ProdData/OS/OSGi
puis ls
o


par exemple ici la version est 6.0
donc la commande devient
java -cp /QIBM/ProdData/OS400/jt400/lib/jt400Native.jar:/QIBM/ProdData/OS/OSGi/LWI60/native/iasadmin.jar com.ibm.lwi.admin.IntegratedServerAdmin -registerServer YOURSERVER /www

Sous Liberty

java -cp /QIBM/ProdData/OS400/jt400/lib/jt400Native.jar:/QIBM/ProdData/OS/OSGi/shared/lib/iasadmin.jar com.ibm.lwi.admin.IntegratedServerAdmin -registerServer YOURSERVER /www

Vous avez un fichier de propriétés, il est dans le répertoire LWI correspondant :

Votre serveur est opérationnel et vous pouvez l’utiliser à nouveau.

Les fichiers de référence des serveurs enregistrés se trouvent :
En 6.1, dans /QIBM/UserData/OS/OSGi/registry/registry.data pour Lwi

À partir de la 7.1,  dans /QIBM/UserData/OS/OSGi/registry/iasregistry.data pour Liberty

Vous pouvez désormais arrêter et redémarrer votre serveur.
ENDTCPSVR *HTTP HTTPSVR(YOURSERVER)
STRTCPSVR *HTTP HTTPSVR(YOURSERVER)

Exemple de requêtes SQL pour retrouver des informations

Liste des instances apaches démarrées

SELECT DISTINCT SERVER_TYPE
FROM TABLE(QSYS2.ACTIVE_JOB_INFO(
SUBSYSTEM_LIST_FILTER => ‘QHTTPSVR’)) X_table

WHERE function = ‘QZSRHTTP’

Liste des instances HTTP déclarées

SELECT TABLE_PARTITION as MEMBER FROM SYSPARTITIONSTAT
WHERE TABLE_NAME = ‘QATMHINSTC’ AND TABLE_SCHEMA = ‘QUSRSYS’

Remarque :

Admin n’a pas d’instance dans ce fichier

La jonction entre les tables pour voir celles qui ne sont pas démarrées

SELECT DISTINCT SERVER_TYPE, TABLE_PARTITION
FROM SYSPARTITIONSTAT a
Join TABLE(QSYS2.ACTIVE_JOB_INFO(
SUBSYSTEM_LIST_FILTER => ‘QHTTPSVR’)) B
on B.server_type = ‘QIBM_HTTP_’ concat TABLE_PARTITION
and TABLE_NAME = ‘QATMHINSTC’
AND TABLE_SCHEMA = ‘QUSRSYS’
where function = ‘QZSRHTTP’

, ,

PCML : Gérer l’usage des paramètres lors déploiements de web service par script

Nous avons vu dans le premier article sur le PCML, que la gestion de l’usage des paramètres ne peut se faire dans le source d’un programme. On peut au mieux déclarer les paramètres en entrée, par le mot clé « const ».

Tous les autres paramètres seront déclarés en entrée/sortie dans le PCML.

Lors de déploiements de web service par script, il faut pouvoir gérer ces paramètres, de façon à générer des WSDL (SOAP) ou des SWAGGER (REST) corrects.

Cet article recense plusieurs méthodes possibles pour cette gestion.

PCML généré dans l’IFS – ajustement manuel :

Prérequis : génération du PCML dans l’IFS, options de compilation PGMINFO et INFOSTMF à renseigner.

On peut éditer le fichier et le modifier manuellement.
Il faudra faire attention à bien respecter le formalisme du PCML.

Avantages :

  •  Mise en œuvre minimaliste.

Inconvénients :

  • Il faut penser après génération du PCML à le modifier, risque d’oubli comme pour toutes procédures peu usitées.
  • Risque d’écraser le PCML modifié par le PCML standard lors d’une prochaine compilation.
  • Risque d’erreur dans la modification, rendant inopérant le PCML.
  • Ce n’est pas sport !

Cette méthode peut être utilisée si vous n’exposez que peu de web service, contenant que quelques paramètres. Même si nous la déconseillons fortement.

PCML généré dans l’IFS – ajustement programmatique :

Prérequis : génération du PCML dans l’IFS, options de compilation PGMINFO et INFOSTMF à renseigner.

Plutôt que d’éditer un PCML dans l’IFS, on peut prévoir de le modifier par programme, en se basant sur un formalisme de nommage des paramètres.
Par exemple, en suffixant le paramètre en entrée par « _I » et les paramètres en sortie par « _O ». Les paramètres en entrée/sortie n’auront pas besoin de suffixe, leurs usages dans le PCML est déjà correct.
Le programme devra mettre à jour le PCML dans l’IFS, en transformant l’usage des paramètres selon le suffixe.
Pour exemple, dans l’extrait de code ci-dessous, nous utilisons les API « C » pour modifier le PCML :
Si vous le souhaitez, nous pouvons sur demande fournir le code complet.

// Ouverture du fichier en mise à jour
 fd = OpenFile(Path : O_RDWR + O_TEXTDATA + O_CCSID : S_IRGRP : 37 ) ;
 if (fd < 0) ;
 // fichier non ouvert : non trouvé ou vérouillé ou ...
 // gestion personnalisée à faire
 *inlr = *on ;
 return ;
 endif ;

// Boucle de lecture infinie - sortie explicite via le leave
 // lecture du fichier totale, avec recherche de chaîne
 Pos = 0 ;
 dow (1 = 1) ;
 // récupération de la longueur du fichier entre la position actuelle
 // et la fin de fichier au premier passage, longueur totale du PCML
 Length = ReadFile(fd:%addr(Data):%size(Data)) ;

// Longueur à 0 --> fin de fichier on sort de la boucle
 if (Length = 0);
 leave;
 else;
 // Recherche du tag de déclaration d'un paramètre
 // on récupère sa position
 Debut = %scan('<data name="' : Data) ;
 if Debut > 0;
 // Extraction de la position du suffixe
 // En fin de nom paramètre sur 2
 Debut += 12 ; // longueur chaîne '<data name="'
 DebSuf = %scan('"' : Data : Debut) - 2;

// Extraction de la position de l'usage du paramètre
 DebUsage = %scan('usage="' : Data : Debut) + 6; // + lng'usage="'

// détermination de l'usage en fonction du suffixe
 select;
 when %scan('_I' : Data : DebSuf : 2) > 0;
 UsageIO = 'input" />' ;
 when %scan('_O' : Data : DebSuf : 2) > 0;
 UsageIO = 'output" />' ;
 other;
 UsageIO = 'inputoutput" />' ;
 endsl;

// positionnement sur l'adresse de début de modification
 Pos += DebUsage;
 Data = UsageIO ;
 lseek(fd: Pos: SEEK_SET) ;
 // modification du fichier
 WriteOK = write(fd:%addr(data): 15) ;
 Pos += 15 ;
 endif;
 endif;

enddo;

PCML issu de la compilation :

<pcml version="6.0"> 
 <!-- RPG program: TESTWS --> 
 <!-- created: 2018-03-12-11.09.56 --> 
 <!-- source: DT/QRPGLESRC(TESTWS) --> 
 <!-- 3 --> 
 <program name="TESTWS" path="/QSYS.LIB/DT.LIB/TESTWS.PGM"> 
 <data name="VARIN_I" type="char" length="15" usage="inputoutput" /> 
 <data name="VAROUT_O" type="char" length="30" usage="inputoutput" /> 
 </program> 
</pcml>

PCML après traitement par le PGM :

<pcml version="6.0"> 
 <!-- RPG program: TESTWS --> 
 <!-- created: 2018-03-12-11.09.56 --> 
 <!-- source: DT/QRPGLESRC(TESTWS) --> 
 <!-- 3 --> 
 <program name="TESTWS" path="/QSYS.LIB/DT.LIB/TESTWS.PGM"> 
 <data name="VARIN_I" type="char" length="15" usage="input" /> 
 <data name="VAROUT_O" type="char" length="30" usage="output" /> 
 </program> 
</pcml>

Avantages :

  •  Automatisation possible, à la création du web service, en masse sur un répertoire de l’IFS, … Au gré des besoins !
  • Si vous avez l’utilité du PCML pour d’autres applications que l’exposition des web services, vous pouvez par ce biais ne gérer qu’une fois cette problématique.

Inconvénients :

  • Risque d’oubli de génération du PCML dans l’IFS.
  • Risque d’écraser le PCML modifié par le PCML standard lors d’une prochaine compilation.
  • Risque de conflit entre les normes de nommage, ou de non utilisation de la norme.
  • Si vous avez plusieurs partitions, il faudra soit déployer le PCML dans l’IFS de chaque partition, soit le générer dans l’IFS puis le modifier via le programme.

Extraction des informations du PCML d’un objet :

Prérequis : génération du PCML dans l’objet, les options de compilation peuvent être dans le source.

Cette méthode consiste à :

  • Extraire les informations du PCML, via l’API QBNRPII. Les informations relatives aux paramètres seront stockés dans fichier.
  • Gérer l’usage des paramètres trouvés, par un interactif.
  • Générer le paramètre -parameterUsage à ajouter à la commande shell de création de web service.

Programme d’extraction des informations PCML :

**free

/if defined(*crtbndrpg)
ctl-opt actgrp(*NEW) ;
/endif
ctl-opt option(*NODEBUGIO : *SRCSTMT);

//-------------------------------------------------------------------------------------------------/
// Paramètre PGM
Dcl-Pi *N;
 P_Objet Char(10) const;
 P_Lib Char(10) const;
 P_Type Char(10) const;
 P_Error Char(110);
End-Pi;

//-------------------------------------------------------------------------------------------------/
// DS objet et module pour appel APi
dcl-ds qualname qualified based(TypeDef);
 Obj Char(10);
 Lib Char(10);
end-ds;

dcl-ds Qbn_Interface_Entry_t qualified based(TypeDef);
 // Offset from start of receiver
 Offset_Next_Entry int(10) ;
 Module_Name Char(10) ;
 Module_Library Char(10) ;
 Interface_Info_CCSID int(10) ;
 Interface_Info_Type int(10) ;
 Offset_Interface_Info int(10) ;
 Interface_Info_Length_Ret int(10) ;
 Interface_Info_Length_Avail int(10) ;
end-ds;

dcl-ds Qbn_PGII0100_t qualified based(TypeDef);
 Bytes_Returned int(10) ;
 Bytes_Available int(10) ;
 Obj_Name Char(10) ;
 Obj_Lib_Name Char(10) ;
 Obj_Type Char(10) ;
 Reserved3 Char(2) ;
 Offset_First_Entry int(10) ;
 Number_Entries int(10) ;
end-ds;

dcl-ds errcode qualified;
 bytesprov int(10) inz(0);
 bytesavail int(10) ;
end-ds;

dcl-ds psds psds ;
 codmsg char(7) pos(40);
 Libmsg char(100) pos(91);
end-ds;

// Define the initial storage for the first call to the API
dcl-ds tempRcvr likeds(Qbn_PGII0100_t);
dcl-ds rcvr likeds(Qbn_PGII0100_t) based(pRcvr);
dcl-ds entry likeds(Qbn_Interface_Entry_t) based(pEntry);
dcl-ds NomObj likeds(qualname);
dcl-ds NomMod likeds(qualname);

//-------------------------------------------------------------------------------------------------/
// Constantes
dcl-c AllMod '*ALLBNDMOD' ;
dcl-c LibModPGM 'QTEMP' ;
dcl-c Format_retour 'RPII0100' ;
// tailleXml doit avoir la même valeur que la variable XMLVALUE
dcl-c tailleXml 8192 ;

//-------------------------------------------------------------------------------------------------/
// Variables
dcl-s pRcvr pointer inz(*null);
dcl-s data Char(tailleXml) based(pData);
dcl-s pcml Varchar(tailleXml);
dcl-s len int(10);
dcl-s i int(10);
dcl-s entry_off int(10);

//-------------------------------------------------------------------------------------------------/
// Prototype d'appel de l'API QBNRPII (Retrieve Program Interface Information)
dcl-pr QBNRPII extpgm('QBNRPII') ;
 Receiver_variable likeds(Qbn_PGII0100_t);
 Length_of_receiver_variable int(10) const;
 Format_name Char(8) const;
 Qualified_object_name likeds(qualname) const;
 Object_Type Char(10) const ;
 Qualified_bound_module_name likeds(qualname) const;
 Error_code likeds(errcode);
end-pr;

// Prototype d'initialisation SQL
dcl-pr initSQL end-pr;

// Prototype déallocation mémoire
dcl-pr cleanup end-pr;

// Prototype extraction paramètre
dcl-pr rtvparam ind end-pr;

//-------------------------------------------------------------------------------------------------/
 initSQL();

// Construction des DS objet et module pour l'appel de l'API
 NomObj.Obj = P_Objet ;
 NomObj.Lib = P_Lib ;
 if P_Type = '*PGM' ;
 // Dans le cas d'un programme, nom module = nom PGM et bib = QTEMP
 NomMod.Obj = P_Objet ;
 NomMod.Lib = LibModPGM ;
 else;
 // Dans le cas d'un programme de service, appel de l'API pour tous les modules
 NomMod.Obj = AllMod ;
 NomMod.Lib = *blanks ;
 endif;

// Appel de l'API - détermination de la taille du retour contenant l'ensemble des PCML
 callp(e) QBNRPII (tempRcvr : %size(tempRcvr) : Format_retour : NomObj : P_Type : NomMod : errcode);

// Non trouvé : objet ou programme ou bibliothèque
 if %error;
 P_Error = codmsg + ' - ' + libmsg ;
 cleanup() ;
 return;
 endif;

// Pas de PCML
 if tempRcvr.Bytes_Available <= tempRcvr.Bytes_Returned;
 P_Error = 'Aucun PCML trouvé dans l''objet ' + P_Objet + ' de la bibliothèque ' + P_Lib ;
 cleanup() ;
 return;
 endif;

pRcvr = %alloc(tempRcvr.Bytes_Available);
 callp(e) QBNRPII (rcvr : tempRcvr.Bytes_Available : Format_retour : NomObj : P_Type : NomMod : errcode);
// Normalement, aucune erreur à ce niveau, mais par sécurité on refait les tests
 if %error or rcvr.Number_Entries = 0 ;
 if codmsg = *blanks ;
 P_Error = 'Erreur API - aucune donnée retournée';
 else;
 P_Error = codmsg + ' - ' + libmsg ;
 endif;

cleanup();
 return;
 endif;

// Lecture de la variable retour par PCML 
// --> Pour les *PGM, un seul PCML, pour les *SRVPGM, autant de PCML que de modules
 entry_off = rcvr.offset_First_Entry;
 for i = 1 to rcvr.Number_Entries;
 pEntry = pRcvr + entry_off;
 entry_off = entry.Offset_Next_Entry;
 pData = pRcvr + entry.Offset_Interface_Info;
 len = entry.Interface_Info_Length_Ret;

// Si le PCML récupéré est plus grand que la taille de la variable prévue --> erreur
 if len > tailleXml ;
 P_Error = 'Taille PCML : ' + %char(len) + ' trop grande pour la variable retour : ' + %editc(tailleXml : 'X') ;
 cleanup() ;
 return;
 endif;

pcml = %subst(data : 1: len);
 if not rtvparam() ;
 return;
 endif;
 endfor;

cleanup();
 P_Error = *blanks ;
 return;

//----------------------------------------------------------------------------------------//
// Procédure d'initialisation SQL //
//----------------------------------------------------------------------------------------//
dcl-Proc initSQL;
 Dcl-Pi *n end-Pi;

// initialisation des options de compilation sql
 EXEC SQL
 Set Option
 Naming = *Sys,
 Commit = *None,
 UsrPrf = *User,
 DynUsrPrf = *User,
 Datfmt = *iso,
 CloSqlCsr = *EndMod;

// création de la table de travail dans QTEMP, ou remise à blanc si elle existe déjà
 EXEC SQL
 create or replace table qtemp.wsparam
 (PROCNAME varchar(128),
 ENTRPT varchar(128),
 PARNAME varchar(128),
 USAGEIO varchar(11))
 on replace delete rows;

end-proc;

//----------------------------------------------------------------------------------------//
// Procédure de désallocation de la mémoire //
//----------------------------------------------------------------------------------------//
dcl-Proc Cleanup;
 Dcl-Pi *n end-Pi;

if pRcvr <> *null and pRcvr <> %addr(tempRcvr);
 dealloc(n) pRcvr;
 endif;

end-proc;

//----------------------------------------------------------------------------------------//
// Procédure d'extraction des paramètres //
//----------------------------------------------------------------------------------------//
dcl-Proc rtvparam;
 Dcl-Pi *n ind end-Pi;

dcl-s XMLVALUE sqltype(XML_CLOB : 8192);

// conversion du texte PCML en un champs XML
 EXEC SQL
 set :XMLVALUE = xmlparse(document :pcml) ;

if sqlcode <> 0 ;
 P_Error = 'Erreur de conversion XML, SQLCODE = ' + %char(sqlcode);
 cleanup() ;
 return *off;
 endif;

// Extraction du XML du nom du module, du nom de point d'entrée, du nom des paramètres et de leur usage,
// dans une table temporaire de QTEMP

EXEC SQL
 insert into qtemp.wsparam select x.* from
 xmltable('$d/pcml/program/data' passing :XMLVALUE
 as "d"
 columns PROCNAME varchar(128) path '../@name',
 ENTRPT varchar(128) path '../@entrypoint',
 PARNAME varchar(128) path '@name',
 USAGEIO varchar(11) path '@usage') as X ;
 if sqlcode <> 0 ;
 P_Error = 'Erreur insertion WSPARAM, SQLCODE = ' + %char(sqlcode);
 cleanup() ;
 return *off;
endif;

return *on ;

END-PROC;

A partir du fichier généré, vous pouvez gérer l’usage des paramètres :

Il ne reste plus qu’à créer le paramètre de la commande shell.

Extrait de code de la génération du paramètre -parameterUsage :

formalisme : -parameterUsage PROC1:i,o:PROC2:i,i,io

Attention à la casse des points d’entrée (PROC1 / PROC2…).

dcl-Proc gener_Opt;
 Dcl-Pi *n end-Pi;

Dcl-s LProc char(128);
 Dcl-s LEntrpt char(128);
 Dcl-s LParam char(128);
 Dcl-s LProcSh char(128);
 Dcl-s LUsage char(11);
 Dcl-s LProcSV char(30) inz(*blanks);
 Dcl-s param1 ind;
//------------------------------------//
// Constantes
dcl-c Deb_Opt '-parameterUsage ';
dcl-c SRVPGM '*SRVPGM' ;
//------------------------------------//

// Création d'un curseur récupérant les données du fichier de travail QTEMP/WSPARAM
 EXEC SQL
 declare curs02 cursor for
 SELECT PROCNAME, ENTRPT, PARNAME, USAGEIO
 FROM WSPARAM;

EXEC SQL
 open curs02;

// Lecture du fichier WSPARAM, pour alimentation de la variable retour
 dou sqlcode <> 0;
 EXEC SQL
 fetch from curs02
 into :LProc, :LEntrpt, :LParam, :LUsage;

if sqlcode = 0;
 //Entête module
 if LProc <> LProcSV ;
 // détermination du nom de la procédure pour la commande Shell (casse sensitive)
 if P_Type = SRVPGM ;
 LProcSh = LEntrpt ;
 else ;
 LProcSh = LProc ;
 endif;

// Insertion du nom de la procédure dans la commande
 if LProcSV = *blanks;
 P_Opt = Deb_Opt + %trim(LProcSh) +':'; // initialisation commande - 1ière proc
 else;
 P_Opt = %trim(P_Opt) + ':' + %trim(LProcSh) +':'; // Ajout 2ième procédure et suivan
 endif;
 LProcSV = LProc;
 param1 = *on ;
 endif;

//détail paramètre - construction de l'usage des paramètres
 if param1 ;
 param1 = *off ;
 else;
 P_Opt = %trim(P_Opt) + ',';
 endif;

select ;
 when LUsage = Input;
 P_Opt = %trim(P_Opt) + 'i';
when LUsage = Output;
 P_Opt = %trim(P_Opt) + 'o';
other;
 P_Opt = %trim(P_Opt) + 'io';
endsl;
 endif;
enddo;

EXEC SQL
 close curs02;

end-proc;

Dans le cas de web service de type REST, il faudra alimenter le fichier de propriété avec les bons usages des paramètres au lieu de construire le paramètre -parameterUsage.

Avantages :

  • Gestion de l’usage des paramètres au déploiement du web service.
  • Intégration simple au scénario de déploiement de web service ou autre traitement si besoin.
  • Dans le cas de sauvegarde du script de déploiement, il est directement utilisable sur une autre partition.

Inconvénients :

  • Aucun lorsqu’on a le source à disposition !

Cette dernière méthode sera intégrée à la prochaine version de notre outils WEBCONSOLE.

Retrouvez-nous à l’université du i les 16 et 17 mai.