SW_APPELER

Attention : dans le cas des programmes VADELIA batch cet ordre n'est pas compatible avec la génération client Mobile.

Contexte d'utilisation

Consommation d'un service Web SOAP.

Paragraphe d'utilisation

Tous

Syntaxe

SW_APPELER IdServiceWeb IdOperation ModeSync IdReq HttpAuthentification Headers Donnees

Description

Cet ordre appelle l'opération IdOperation du service Web IdServiceWeb.

La directive *ASYN permet d'appeler l'opération de façon asynchrone. Si une réponse est attendue, il faut utiliser l'ordre SW_RECUP_ETAT pour connaître la disponibilité du résultat.

Pour des appels simultanés asynchrones d'un même service, il faut préciser un id de requête à l'aide de la directive *ID. Cet id permet d'identifier une requête parmi un groupe de requêtes et permet de récupérer précisément le résultat de l'une de ces requêtes. Si aucun id n'est précisé alors l'id 1 est utilisé par défaut. Par défaut, le nombre maximum de requêtes simultanées est de 10. Il est possible de modifier ce nombre à l'aide de l'élément <NbMaxSessions> dans le fichier de configuration.

Si le service Web requiert une authentification HTTP, il faut utiliser la directive *CONNEXION pour renseigner le mode d'authentification (*BASIC par défaut), le nom de l'utilisateur, le mot de passe et, dans le cas du mode *NTLM, le nom du domaine. Ce dernier peut éventuellement se décomposer en : domaine, workstation, flags. Il est possible d'utiliser le mot réservé *USER pour qualifier le nom de l'utilisateur. Le mode *AUTO assure si besoin une authentification HTTP de type BASIC ou DIGEST.

L'option *HTTP_HEADERS(LISTE(alpha, alpha)) prend en paramètre une liste mémoire Adelia composée de 2 zones de type ALPHA.
Si la liste n'est pas vide avant l'appel, les headers sont ajoutés à la requête HTTP.
Lors du retour, en cas de succès, la liste contient les headers de la réponse HTTP.
Les headers de la réponse ne sont pas gérés dans le cas d'un appel asynchrone (*ASYN).
L'option *HTTP_HEADERS est ignorée lorsque le service web est de style SOAP RPC/Encoded avec un appel en mode "paramètre" (un message d'avertissement est envoyé lors de la génération).

L'opération d'un service Web peut être appelée en mode "message" ou en mode "paramètre". Ce dernier est possible uniquement pour une opération avec des paramètres simples (scalaires) en entrée : cette information est précisée dans les informations du service Web.

Dans le mode "paramètre", les paramètres effectifs de l'opération sont spécifiés à la fin de l'ordre. S'il ne s'agit pas de variables, ces paramètres peuvent être des constantes ou des mots réservés (de type ALPHA, NUM_E, NUM_P, NUM_BIN_2, NUM_BIN_4 ou NUM_BIN_8).

Dans le mode "message", les paramètres effectifs (ou données) sont passés via un document XML. Il prend la forme du corps du message SOAP et sa structure doit correspondre à celle proposée par l'option 'Requête exemple...' disponible dans la boite de modification du service web.

Le document XML est soit un fichier, dont le nom doit être renseigné dans la directive *CORPS_MSG_FIC, soit une zone mémoire (variable ou constante ALPHA ou variable IMAGE) qui doit être utilisée avec la directive *CORPS_MSG_MEM .

Par défaut la version de l'enveloppe SOAP créée s'appuie sur les informations du service web inscrit dans l'environnement Adélia. Si aucune information n'est donnée par le service, l'utilisateur peut ajouter un argument supplémentaire à l'aide des mots réservés *SOAP_ENV_11 et *SOAP_ENV_12. Si aucune information n'est précisée, ni par le service, ni par l'utilisateur, alors une enveloppe SOAP 1.1 est construite.

Facultativement, un en-tête SOAP ou des en-têtes SOAP peuvent être ajoutés au message. Pour cela il faut utiliser, selon la nature du(des) document(s) XML fourni(s) (fichier ou zone mémoire), une des deux directives *ENTETE_MSG_FIC ou *ENTETE_MSG_MEM.

Remarques :

• • L'appel d'une opération d'un service Web peut prendre un certain temps et peut échouer pour les raisons suivantes :

    • l'emplacement du service Web n'est plus valide ;

    • la réponse n'a pas été rendue dans le délai imparti (time-out) ;

    • la valeur d'un paramètre n'est pas conforme à sa définition (type, restriction).

  • En mode "paramètre", le nom IdOperation doit correspondre à une opération déclarée lors de l'inscription du service. La casse doit être respectée.

  • En mode "message", le nom IdOperation n'est pas contrôlé lors de la vérification. Il doit cependant correspondre à une opération réelle du service.

  • Les mots-clés *ASYN, *ID, *AUTO, *DIGEST, *NTLM ne sont pas supportés dans le mode "paramètre" si le style SOAP du service est "RPC/Encoded".

Pour vérifier si l'appel s'est bien effectué, il est possible de tester le mot réservé *CODE_RETOUR.

Si ce mot réservé retourne une valeur différente de *NORMAL, le mot réservé *MSG_RETOUR donne un descriptif de l'erreur.

Par exemple

Exemples (mode "paramètre")

/* Appel de l'opération longueurChaine du service GESTIONCHAINES

/* Passage d'un paramètre unique

SW_APPELER GESTIONCHAINES longueurChaine chs_chaine:

si *code_retour <> *normal

   AFF_CODE_RET: = *CODE_RETOUR

   AFF_MSG_RET_DEBUG: = *MSG_RETOUR

fin

/* Appel de l'opération GetWeather du service GLOBALWEATHER

/* Passage de 2 paramètres ALPHA

SW_APPELER GLOBALWEATHER GetWeather 'grenoble' 'france'

/* Appel de l'opération oper1 du service MONSERVICE avec une authentification HTTP en mode AUTO.

/* Le mode AUTO détermine si une authentification HTTP est nécessaire et si c'est le cas détermine entre BASIC et DIGEST le mode à utiliser. La connexion est ensuite réalisée dans le mode requis avec

/* les informations d'authentification.

SW_APPELER MONSERVICE oper1 *CONNEXION(*AUTO, 'nomutilisateur', 'password') Param1 Param2

/* Appel de l'opération oper1 du service MONSERVICE de façon asynchrone.

SW_APPELER MONSERVICE oper1 *ASYN Param1 Param2

Remarque : l'appel asynchrone en mode 'paramètre' est possible uniquement pour un service Web de style SOAP autre que 'RPC/Encoded' et sous condition de compatibilité du moteur de services Web utilisé par le serveur.

Exemples (mode "message")

a. Passage du corps du message (données)
 

Document XML à utiliser comme corps du message :

<ns:GetWeather xmlns:ns="http://www.webserviceX.NET">

   <ns:CityName>grenoble</ns:CityName>

   <ns:CountryName>france</ns:CountryName>

</ns:GetWeather>

L'encodage par défaut du document XML est l'UTF-8. Pour changer d'encodage, il faut ajouter au document l'en-tête xml précisant l'encodage souhaité :

<?xml version="1.0" encoding="windows-1252"?>

<ns:GetWeather xmlns:ns="http://www.webserviceX.NET">

   <ns:CityName>grenoble</ns:CityName>

   <ns:CountryName>france</ns:CountryName>

</ns:GetWeather>

- Utilisation d'un buffer mémoire (variable ou constante)

Variable

ALPHA(500) varAlpXML

varAlpXML = '<ns:GetWeatger xmlns:ns="http://www.webserviceX.NET"><ns:CityName>grenoble</ns:CityName><ns:CountryName>france</ns:CountryName></ns:GetWeather>'

SW_APPELER GLOBALWEATHER GetWeather *CORPS_MSG_MEM(varAlpXML)

Constante

SW_APPELER GLOBALWEATHER GetWeather *CORPS_MSG_MEM('<ns:GetWeatger xmlns:ns="http://www.webserviceX.NET"><ns:CityName>grenoble</ns:CityName><ns:CountryName>france</ns:CountryName></ns:GetWeather>)

- Utilisation d'un fichier

L'emplacement du fichier est précisé à l'aide d'une variable ou d'une constante alphanumérique.

Variable

ALPHA(128) varAlpDir

varAlpDir = 'c:\xmlbodies\bodyweather1.xml'

SW_APPELER GLOBALWEATHER GetWeather *CORPS_MSG_FIC(varAlpDir)

Constante

SW_APPELER GLOBALWEATHER GetWeather *CORPS_MSG_FIC('c:\xmlbodies\bodyweather1.xml')

b. Passage d'un en-tête SOAP
 

De façon facultative, il est possible d'ajouter un ou plusieurs en-têtes au message SOAP à envoyer au service.

- Utilisation d'un buffer mémoire (variable ou constante)

Variable

varHeader = '<reqinfo><timestamp>2012-01-15-09.32.00</timestamp></reqinfo>'

SW_APPELER GLOBALWEATHER GetWeather *CORPS_MSG_FIC(varAlpDir) *ENTETE_MSG_MEM(varHeader)

Utilisation d'une table pour passer de façon simultanée plusieurs headers distincts :

ALPHA(1500) varthead(2)

varthead(1) = '<reqinfo><timesamp>2012-01-15-09.32.00</timestamp></reqinfo>'

varthead(2) = '<idsession>12</idsession>'

SW_APPELER GLOBALWEATHER GetWeather *CORPS_MSG_FIC(varAlpDir) *ENTETE_MSG_MEM(varthead)

Constante

SW_APPELER GLOBALWEATHER GetWeather *CORPS_MSG_FIC(varAlpDir) *ENTETE_MSG_MEM('<reqinfo><timestamp>2012-01-15-09.32.00</timestamp></reqinfo>')

- Utilisation d'un fichier

L'emplacement du fichier est précisé à l'aide d'une variable ou d'une constante alphanumérique.

Variable

varHeaderFic = 'c:\xmlheaders\headweather1.xml'

SW_APPELER GLOBALWEATHER GetWeather *CORPS_MSG_FIC(varAlpDir) *ENTETE_MSG_FIC(varHeaderFic)

Constante

SW_APPELER GLOBALWEATHER GetWeather *CORPS_MSG_FIC(varAlpDir) *ENTETE_MSG_FIC('c:\xmlheaders\headweather1.xml')

c. Autres directives
 

/* Appel asynchrone avec un identifiant de requête égal à 2.

/* Authentification HTTP automatique avec profil de connexion ('user', 'pwd').

SW_APPELER GLOBALWEATHER GetWeather *ASYN *ID(2) *CONNEXION(*AUTO, 'user', 'pwd') *CORPS_MSG_MEM(varAlpXML)

/* Authentification HTTP de type BASIC avec profil de connexion ('user', 'pwd').

SW_APPELER GLOBALWEATHER GetWeather *CONNEXION(*BASIC, 'user', 'pwd') *CORPS_MSG_MEM(varAlpXML)

 /* Authentification HTTP de type NTLM avec profil de connexion ('user', 'pwd') sur le domaine windows 'domain'.

SW_APPELER GLOBALWEATHER GetWeather *CONNEXION(*NTLM, 'user', 'pwd', 'domain') *CORPS_MSG_MEM(varAlpXML)

 /* Authentification HTTP de type NTLM avec profil de connexion ('user', 'pwd') sur le domaine windows 'domain', workstation 'ws'.

ALPHA(32) varDomain

ALPHA(32) varWorkstation

varDomain = 'domain'

varWorkstation = 'ws'

SW_APPELER GLOBALWEATHER GetWeather *CONNEXION(*NTLM, 'user', 'pwd', varDomain:varWorkstation) *CORPS_MSG_MEM(varAlpXML)

ou

SW_APPELER GLOBALWEATHER GetWeather *CONNEXION(*NTLM, 'user', 'pwd', 'domain:ws') *CORPS_MSG_MEM(varAlpXML)

/* Utilisation de *HTTP_HEADERS

ALPHA(64)  HdrAttr

ALPHA(128) HdrValue 

LISTE lHeaders HdrAttr HdrValue 

HdrAttr = 'JWT1' 

HdrValue = 'Mon jeton1' 

INSERER_ELT lHeaders 

HdrAttr = 'JWT2' 

HdrValue = 'Mon jeton2' 

INSERER_ELT lHeaders

SW_APPELER WSABCD OpenSession *HTTP_HEADERS(lHeaders)

LECTURE_LST lHeaders 

   zTrace = HdrAttr /// ':' /// HdrValue 

   AJOUTER_TRACE zTrace

FIN_LECTURE_LST

Exemple de constitution d'un document XML à l'aide des ordres Adélia XML

Un document XML peut être constitué à l'aide des ordres XML Adélia. De la sorte, tous les types Adélia sont sérialisés automatiquement.

D'autre part, l'ordre Adélia XML_OUVRIR permet tout aussi bien de créer un document XML dans un fichier, dans une variable ALPHA ou dans une variable IMAGE.

Création du document XML exemple à l'aide des ordres XML Adélia :

/* Déclaration d'un XML_IDF avec des formats spécifiques aux services

/* web pour la sérialisation des types HEURE et TIMESTAMP.

XML_IDF idfx *FMT_TIME('*HMS') *FMT_TMS('YYYY-MM-DDTHH:mm:SS.sss')

/* Document XML contenu dans une variable IMAGE

IMAGE docXML

/* Création d'un document XML avec un encodage 'windows-1252'

XML_OUVRIR idfx *ecriture *VAR_DOC(docXML) *version ('1.0') *encodage_fic ('windows-1252')

/* Création des différents nœuds du document

XML_CREER_NOEUD idfx *FILS 'ns:GetWeather'

XML_CREER_VAL idfx xmlns:ns 'http:// www.webserviceX.NET'

XML_CREER_NOEUD idfx *FILS 'ns:CityName'

XML_CREER_VAL idfx 'grenoble'

XML_CREER_NOEUD idfx *FRERE 'ns:CountryName'

XML_CREER_VAL idfx 'france'

XML_FERMER idfx

/* Appel de l'opération GetWeahter du service GLOBALWEATHER avec

/* le document construit précédemment.

SW_APPELER GLOBALWEATHER GetWeather *CORPS_MSG_MEM(docXML)

↑ Haut de page