|
VADELIA |
SADELIA |
WADELIA |
EADELIA |
(I/B) (C/S) |
(B) (S) |
(I/B) (C/S) |
(B) (C/S) |
Paragraphe d'utilisation
DECLARATION
Syntaxe
PARAM SuiteParam
SuiteParam |
→ |
SuiteParam ZoneParam | ZoneParam |
|
ZoneParam |
→ |
IdVar |
|
→ |
IdVar, GenreSOAP |
(Seulement dans le cas de service Web SOAP) |
|
→ |
IdVar, GenreSOAP, NomExport |
(Seulement dans le cas de service Web SOAP) |
|
→ |
IdVar, GenreRest |
Seulement dans le cas de service Web Rest) |
|
→ |
IdVar, GenreRest, NomExport |
Seulement dans le cas de service Web Rest) |
|
GenreSOAP |
→ |
I | O | B |
|
GenreRest |
→ |
I[NatureI] | O[NatureO] |
|
NatureI |
→ |
path |
|
→ |
query:ReqOpt |
||
→ |
header:ReqOpt |
||
→ |
header(csteAlpha):ReqOpt |
||
→ |
form:ReqOpt |
||
→ |
form(csteAlpha):ReqOpt |
||
→ |
cookie:ReqOpt |
||
→ |
cookie(csteAlpha):ReqOpt |
||
→ |
content |
||
→ |
multipart:ReqOpt |
||
→ |
multipart(csteAlpha):ReqOpt |
||
→ |
multipart:type(csteAlpha):ReqOpt |
||
→ |
multipart(csteAlpha):type(csteAlpha):ReqOpt |
||
→ |
attachment |
||
ReqOpt |
→ |
required | optional | optional(cste) |
|
cste |
→ |
csteNum | csteAlpha |
|
NatureO |
→ |
header |
|
→ |
header(csteAlpha) |
||
→ |
cookie |
||
→ |
cookie(csteAlpha) |
||
→ |
cookie:comment(csteAlpha) |
||
→ |
cookie:max_age(csteNum) |
||
→ |
cookie(csteAlpha):comment(csteAlpha):max_age(csteNum) |
||
→ |
content |
||
→ |
multipart |
||
→ |
multipart(csteAlpha) |
||
→ |
multipart:type(csteAlpha) |
||
→ |
multipart(csteAlpha):type(csteAlpha) |
||
→ |
attachment |
||
→ |
HTTPstatus |
Description
Déclaration des paramètres du programme ou d'une procédure.
Cette déclaration ne peut être faite qu'une seule fois pour le programme et pour chaque procédure. Les paramètres sont tous déclarés dans la liste SuiteParam , qui doit contenir au moins une zone.
Les variables, paramètres du programme, doivent être globales au programme.
Les variables, paramètres d'une procédure, doivent être locales à la procédure.
Les variables peuvent être de type simple, c'est-à-dire NUM_E, NUM_P, NUM_BIN_2, NUM_BIN_4, NUM_BIN_8, BOOL, DATE, TIME, TIMESTAMP, ALPHA et IMAGE. Elles peuvent être sous forme de tableaux. Les listes mémoires et les classes (REF_CLASSE) peuvent aussi être un paramètre.
Pour les programmes VADELIA Batch sans état destinés à la production de services Web, lorsque l'ordre PARAM correspond au paragraphe de déclaration générale ou au paragraphe de déclaration d'une procédure publique, la syntaxe de l'ordre PARAM requiert l'adjonction d'une information précisant le genre du paramètre. Le genre est précisé à l'aide d'une des trois lettres suivantes :
- I : paramètre en entrée,
- O : paramètre en sortie,
- B : paramètre en entrée/sortie (uniquement service SOAP),
D'autre part il est possible, de façon facultative, d'associer au paramètre un nom exporté NomExport. Ce dernier est alors utilisé à la place du mot directeur Adélia dans le schéma XML (SOAP) ou dans la représentation (REST) du service Web produit. NomExport est un identifiant de 128 caractères de long au maximum et la casse est prise en compte.
Le genre d'un paramètre est obligatoire à partir du moment où ce dernier joue un rôle dans une des opérations du service Web produit, c'est-à-dire si le paramètre est un paramètre du programme ou d'une procédure publique du programme.
Dans le cadre des services REST, il est possible d'adjoindre au genre du paramètre une multitude de natures, dont voici la liste :
Pour un paramètre en entrée (Genre I) :
Nature |
Types supportés |
Occ. max |
Facul |
Valeurs multiples |
Commentaires |
path |
SSI |
N |
Non |
non |
Paramètre associé à une variable citée via une annotation @Path. Exemple : /car/{idcar}/{idcolor} Le nombre d'occurrences est égal au nombre trouvé de {variable} dans l'URI. Exemple : PARAM idcar,I[path] idcolor,I[path] |
query |
SSI ou SSI_1D |
N |
Oui |
oui |
Paramètre associé à un paramètre d'une URL. Exemple : /car?id=10&color=blue Le nombre d'occurrences est égal au nombre trouvé de variables paramètre dans l'URL. Exemple : /car?id=10&color=blue PARAM id,I[query:required] color,I[query:optional('red')] Il est possible d'avoir plusieurs variables paramètre de même nom et donc de récupérer une collection de valeurs. Le paramètre déclaré doit alors être une table de dimension 1. Exemple : /car?color=blue&color=green&color=red PARAM color,I[query:required],color Pour un paramètre de nom interne NomParam, ne définissant pas de nom externe, le nom du paramètre à écrire dans la chaîne de paramètres de l'URL doit être : pmNOMPARAM Exemple : NUM_BIN_4 id ALPHA(32) color PARAM id,I[query:required] color,I[query:optional('red')] URL : /car?pmID=10&pmCOLOR=red |
header |
SSI ou SSI_1D |
N |
Oui |
Oui |
Paramètre associé à un header HTTP. Le nombre d'occurrences est égal au nombre de header à récupérer. Il est possible d'avoir plusieurs champs header de même nom et donc de récupérer une collection de valeurs. Le paramètre déclaré doit alors être une table de dimension 1. Exemple : ALPHA(256) hdrCT PARAM hdrCT,I[header('Content-Type'):required] |
form |
SSI |
N |
Oui |
Non |
Paramètre associé à un champ de formulaire HTTP. Exemple : ALPHA(256) NomCli PARAM NomCli,I[form('name'):required] |
cookie |
SSI |
N |
Oui |
Non |
Paramètre associé à un cookie. Le nombre d'occurrences est égal au nombre de cookies à récupérer. ALPHA(256) infCookCli PARAM infCookcli,I[cookie('cook_inf_lastcli'):required] |
content |
SwCLS |
1 |
Non |
Non |
Paramètre associé au contenu (corps) de la requête HTTP. Le format de ce contenu est l'un de ceux définis via l'annotation @Consumes.
|
multipart |
SwCLS |
N |
Oui |
Non |
Paramètre associé à une partie de contenu de la requête HTTP dans le cas d'un message composé de plusieurs ensembles de données regroupées dans un même corps ; le format de ce contenu est nommé multipart. Chaque partie identifiée du contenu peut être associée à un paramètre ; un type mime (Content-Type) peut être précisé pour chacune des parties. REF_CLASSE(COMPUTER) iComputer REF_CLASSE(PRINTER) iPrinter PARAM iComputer,I[multipart('id1'):type('application/xml'):required] iPrinter,I[multipart('id2'):type('application/json'):optional]
|
attachment |
ALPHA ou ALPHA(n) ou LISTE |
1 |
Non |
Oui |
Paramètre associé à un ou plusieurs fichiers à récupérer (upload). Le paramètre est alors soit de type ALPHA, soit une table ALPHA à une dimension, soit une liste d'une zone ALPHA. Le paramètre contient le(s) nom(s) et emplacement(s) du(des) fichier(s) uploadé(s). Le répertoire cible de stockage des fichiers attachés est par défaut le répertoire défini par la variable d'environnement java.temp de la JVM. La fonction VaToolBxWSSetAttachmentDirectory permet de changer cet emplacement et doit être appelée en amont de l'appel de la procédure de service, c'est à dire dans le pavé INIT_PGM du programme, pavé déclaré au préalable comme un pavé d'initialisation de service : SW_CONFIGURER *SERVICE '_init_pgm_as_method' 'false'.
SW_CONFIGURER *OPERATION '@Consumes' 'multipart/form-data' ALPHA(256) FileName LISTE LstAttachedFiles FileName PARAM LstAttachedFiles,I[attachment] [DECL_PGM] APPELER_CLASS 'VaToolBx' 'VaToolBxWSSetAttachmentDirectory' 'c:\temp\files' |
Notes :
- Définition des types supportés (sous-ensembles)
Simple => ALPHA|NUM_E|NUM_P|BOOL|NUM_BIN_2|NUM_BIN_4|NUM_BIN_8|DATE|TIME|TIMESTAMP|IMAGE
SSI => ALPHA|NUM_E|NUM_P|BOOL|NUM_BIN_2|NUM_BIN_4|NUM_BIN_8|DATE|TIME|TIMESTAMP
SSI_1D => SimpleSansImage(N)
SwCLS => Simple | REF_CLASSE
- Occurrence maximale : indique le nombre maximal d'occurrences d'un paramètre pour une nature donnée. Par exemple, un seul paramètre de nature content est autorisé alors que plusieurs paramètres de nature query sont autorisés.
REF_CLASSE(CLIENT) iClient
PARAM iClient,I[content]
ALPHA(18) CodeCli
ALPHA(50) NomCli
PARAM CodeCli,I[path] NomCli,i[path]
- Facultatif : si le paramètre peut-être facultatif alors il faut préciser s'il est requis ou optionnel. Dans ce dernier cas, il est possible de lui assigner une valeur par défaut.
NUM_BIN_4 CodePers
ALPHA(32) CodeGroup
BOOL Active
DATE Since
PARAM CodePers,I[query:required] CodeGroup,I[query:optional('HardisGroup')] Active,I[query:optional(true)] Since,I[query:optional(19950325)]
- Valeurs multiples : indique si un même paramètre peut recevoir plusieurs valeurs. Si c'est le cas le paramètre doit déclarer une table à une dimension avec un nombre d'éléments supérieur ou égal au nombre de valeurs à recevoir ou, si la nature le permet, une LISTE.
NUM_BIN_4 CodesPers[10]
PARAM CodesPers,I[query:required]
- Les natures form, content, multipart, et attachment sont exclusives.
Pour un paramètre en sortie (Genre O) :
Nature |
Types supportés |
Occ. max |
Valeurs multiples |
Commentaires |
header |
SSI ou SSI_1D |
N |
Oui |
Paramètre associé à un header HTTP. Le nombre d'occurrences est égal au nombre de champs header à envoyer. Exemple : ALPHA(256) hdrLocation PARAM hdrLocation,O[header('Content-Location')]
Exemple : ALPHA(32) hdrValues(2) hdrValues(1)=value1 hdrValues(2)=value2 PARAM hdrValues,O[header('headerName)]
|
cookie |
SSI |
N |
Non |
Paramètre associé à un cookie. Le nombre d'occurrences est égal au nombre de cookies à envoyer. La directive comment permet, si besoin, de joindre un commentaire au cookie. La directive max_age permet, si besoin, de fixer une limite de temps (exprimée en secondes) au cookie.
ALPHA(256) infCookCli PARAM infCookcli,O[cookie('cook_inf_lastcli'):comment('comment'):max_age(3600)] |
content |
SwCLS |
N |
Non |
Paramètre associé au contenu (corps) de la réponse HTTP. Le format de ce contenu est l'un de ceux définis via l'annotation @Produces. Le contenu à envoyer peut s'appuyer sur l'ensemble des types Adélia suivants (types simples, tables à 1 dimension, LISTE, REF_CLASSE). Il est possible de déclarer plusieurs paramètres en sortie de nature content ; ces derniers sont alors agrégés dans une structure qu'il est possible de nommer à l'aide de l'ordre : SW_CONFIGURER *OPERATION '_root_result_name' 'NomDeLaStructure' |
multipart |
SwCLS |
N |
Non |
Paramètre associé à une partie de contenu de la réponse HTTP pour un message composé de plusieurs ensembles de données regroupées dans un même corps ; le format de ce contenu est nommé multipart. un type mime (Content-Type) peut-être précisé pour chacune des parties. Exemple : REF_CLASSE(COMPUTER) iComputer REF_CLASSE(PRINTER) iPrinter PARAM iComputer,O[multipart('part1'):type('application/xml')] iPrinter,I[multipart('part2'):type('application/json')] ] Note : pour le format produit il faut choisir l'un des types mime multipart existant, à savoir :
Exemple : SW_CONFIGURER *OPERATION '@Produces' 'multipart/form-data' |
attachment |
ALPHA ou |
1 |
Oui |
Paramètre associé à un ou plusieurs fichiers à envoyer (download). Le paramètre est alors soit de type ALPHA, soit une table ALPHA à une dimension, soit une liste d'une zone ALPHA. Le paramètre contient le(s) nom(s) et emplacement(s) du(des) fichier(s) à télécharger. Exemple : ALPHA(256) FileNames(2) BOOL cRet PARAM FileNames,O[attachment] /* Téléchargement des fichiers pic1.jpg et pic2.jpg situés dans le répertoire /* '/images' de l'application web. APPELER_CLASS 'VaToolBx' 'VaToolBxAwsGetRealPath' '/images/pic1.jpg' FileNames(1) cRet APPELER_CLASS 'VaToolBx' 'VaToolBxAwsGetRealPath' '/images/pic2.jpg' FileNames(2) cRet |
HTTPstatus |
NUM_BIN_4 |
1 |
Non |
Paramètre associé au code de status HTTP retourné par le service. Le paramètre de nature HTTPstatus n'est pas obligatoire ; il se substitue au code calculé par défaut et ce qui, dans certains cas, permet de définir un code retour plus pertinent. Exemple : NUM_BIN_4 httpstatus PARAM httpstatus,o[httpstatus] si ok_lecture httpstatus = 200 /* on retourne le code HTTP 200 : OK sinon httpstatus = 404 /* on retourne le code http 404 : non trouvé fin |
Notes :
- Définition des types supportés (sous-ensembles)
Simple => ALPHA|NUM_E|NUM_P|BOOL|NUM_BIN_2|NUM_BIN_4|NUM_BIN_8|DATE|TIME|TIMESTAMP|IMAGE
SSI => ALPHA|NUM_E|NUM_P|BOOL|NUM_BIN_2|NUM_BIN_4|NUM_BIN_8|DATE|TIME|TIMESTAMP
SwCLS => Simple | REF_CLASSE
- Occurrence maximale : indique le nombre maximal d'occurrences d'un paramètre pour une nature donnée.
Par exemple, un seul paramètre de nature attachment est autorisé alors que plusieurs paramètres de nature multipart sont autorisés.
- Occurrence maximale : indique le nombre maximal d'occurrences d'un paramètre pour une nature donnée.
- Valeurs multiples : indique si un même paramètre peut recevoir plusieurs valeurs.
Si c'est le cas, le paramètre doit déclarer une table à unedimension avec un nombre d'éléments supérieur ou égal au nombre de valeurs à recevoir ou, si la nature le permet, une LISTE.
- Valeurs multiples : indique si un même paramètre peut recevoir plusieurs valeurs.
- Les natures content, multipart, et attachment sont exclusives.
Par exemple
PARAM COD_CLI TableAlpha
Autres exemples d'utilisation
Premier cas
* dans le paragraphe DECL d'un programme Visual
* déclaration d'une variable code retour
ALPHA(2) PW_COD_RET
* déclaration d'une liste mémoire
LISTE PW_LST_MEMO PE_NOM_PERSONNE PE_PRN_PERSONNE PE_COD_MATRICUL PE_LIB_VIL_PERS
* déclaration en paramètre de la liste mémoire et d'un code retour
PARAM PW_LST_MEMO PW_COD_RET
Second cas
* dans un programme Visual dans une procédure
Troisième cas
* pour un service Web SOAP
PARAM PCODE_CLIENT,I,CodeDuClient PNOM_CLIENT,O,NomDuClient PADR_CLIENT,O,AdresseDuClient
Quatrième cas
* pour un service Web REST
PARAM PCODE_CLIENT,I[path],CodeDuClient VCLIENT,O[content],Client status,O[HTTPstatus]
PARAM PCODE_CLIENT,I[query:required] PVILLE_CLIENT,I[query:optional('Paris')] VCLIENT,O[content] VHEAD,O[header('Content-Location')]
PARAM PCODINFI,I[cookie('cook-inf-lastcli')] PCODINFO,O[cookie('cook-inf-lastcli'):comment('Informations dernier client'):max_age(3600)]