PARAM

	VADELIA	SADELIA	WADELIA	EADELIA
	(I/B) (C/S)	(B) (S)	(I/B) (C/S)	(B) (C/S)

Section for use

DECLARATION

Syntax

PARAM SeriesParam

SeriesParam	→	SeriesParam ParamField \| ParamField

ParamField	→	VarId
	→	VarId, SOAPUsage	(Only with SOAP Web services)
	→	VarId, SOAPUsage, ExportName	(Only with SOAP Web services)

	→	VarIdr, RestUsage	(Only with REST Web services)
	→	VarId, RestUsage, ExportName	(Only with REST Web services)

SOAPUsage	→	I \| O \| B

RestUsage	→	I[NatureI] \| O[NatureO]
NatureI	→	path
	→	query:OptReq
	→	header:OptReq
	→	header(AlphCst):OptReq
	→	form:OptReq
	→	form(AlphCst):OptReq
	→	cookie:OptReq
	→	cookie(AlphCst):OptReq
	→	content
	→	multipart:OptReq
	→	multipart(AlphCst):OptReq
	→	multipart:type(AlphCst):OptReq
	→	multipart(AlphCst):type(AlphCst):OptReq
	→	attachment

OptReq	→	required \| optional \| optional(cst)
cst	→	cstNum \| AlphCst
NatureO	→	header
	→	header(AlphCst)
	→	cookie
	→	cookie(AlphCst)
	→	cookie:comment(AlphCst)
	→	cookie:max_age(NumCst)
	→	cookie(AlphCst):comment(AlphCst):max_age(cstNum)
	→	content
	→	multipart
	→	multipart(AlphCst)
	→	multipart:type(AlphCst)
	→	multipart(AlphCst):type(AlphCst)
	→	attachment
	→	HTTPstatus

Description

Declaration of the parameters for a program or procedure.

This declaration can only be made once for each procedure in the program. Parameters are all declared in the list SeriesParam, which must contain at least one field.

Variables and parameters for programs must be global to the program.

Variables and parameters for procedures must be local to the procedure.

Simple variables can be used, i.e. NUM_E, NUM_P, NUM_BIN_2, NUM_BIN_4, NUM_BIN_8, BOOL, DATE, TIME, TIMESTAMP, ALPHA and IMAGE. These variables can be used in array form. Memory lists can also be set as a parameter.

With reportless VADELIA Batch programs intended for use in Web service production, when the PARAM instruction matches the general declaration paragraph or a public procedure's declaration paragraph, the syntax of the PARAM instruction requires you to add a setting that specifies the parameter usage. The usage is set by specifying one of the following three letters:

- I: input parameter,

- O: output parameter,

- B: input/output parameter (only SOAP service),

Optionally, it is also possible to associate an export name, ExportName, with the parameter. This name is then used instead of the Adelia guide word in the generated Web service's XML diagram (SOAP) or Web service's exchange format (REST). The ExportName is a case-sensitive identifier up to 128 characters in length.

A parameter's type MUST be specified if the parameter is involved in any of the generated Web service's operations, i.e. if the parameter is a parameter of either the program or a public procedure of the program.

In the context of RESTful services, it is possible to add to the kind of parameter a great many types, which are listed below:

For an input parameter (Kind I):

Type	Types supported	Occ. max	Optional	Multiple values	Comments
path	SSI	N	No	no	Parameter associated with a variable cited via an @Path annotation. Example: /car/{idcar}/{idcolor} The number of occurrences is equal to the number found of {variable} in the URI. Example: PARAM idcar,I[path] idcolor,I[path]
query	SSI or SSI_1D	N	Yes	yes	Parameter associated with a parameter of a URL. Example: /car?id=10&color=blue The number of occurrences is equal to the number found of parameter variables in the URL. Example: /car?id=10&color=blue PARAM id,I[query:required] color,I[query:optional('red')] It is possible to have several parameter variables with the same name and therefore to retrieve a collection of values. The parameter declared must then be a table of dimension 1. Example: /car?color=blue&color=green&color=red ALPHA(32) color(5) PARAM color,I[query:required],color For a parameter with the ParamName internal name not defining an external name, the parameter name to write in the URL's parameter string must be: pmPARAMNAME. Example: 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 or SSI_1D	N	Yes	Yes	Parameter associated with an HTTP header. The number of occurrences is equal to the number of headers to be retrieved. It is possible to have several header fields with the same name and therefore to retrieve a collection of values. The parameter declared must then be a table of dimension 1. Example: ALPHA(256) hdrCT PARAM hdrCT,I[header('Content-Type'):required]
form	SSI	N	Yes	No	Parameter associated with an HTTP form field. Example: ALPHA(256) CliName PARAM CliName,I[form('name'):required]
cookie	SSI	N	Yes	No	Parameter associated with a cookie. The number of occurrences is equal to the number of cookies to be retrieved. Example: ALPHA(256) infCookCli PARAM infCookcli,I[cookie('cook_inf_lastcli'):required]
content	SwCLS	1	No	No	Parameter associated with the content (body) of the HTTP query. The format of this content is one of those defined via the @Consumes annotation. The content can be retrieved in a simple type or an Adelia class.
multipart	SwCLS	N	Yes	No	Parameter associated with part of the contents of the HTTP query in the case of a message consisting of several data sets grouped together in one body; the format of this content is named multipart. Each identified part of the content may be associated with a parameter; a mime type (Content-Type) can be specified for each of the parts. Example: REF_CLASS(COMPUTER) iComputer REF_CLASS(PRINTER) iPrinter PARAM iComputer,I[multipart('id1'):type('application/xml'):required] iPrinter,I[multipart('id2'):type('application/json'):optional] Notes: for the consumed format, you must choose one of the existing multipart mime types, i.e: multipart/form-data multipart/mixed multipart/alternative multipart/related Example: WS_CONFIGURE OPERATION '@Consumes' 'multipart/form-data' In the case of an optional parameter, a default value can only be specified for the ALPHA, DATE , TIME and TIMESTAMP types. Example:* DATE iDate PARAM iDate,I[multipart('id1'):optional(19980712)]
attachment	ALPHA or ALPHA(n) or LIST	1	No	Yes	Parameter associated with one or more files to be retrieved (upload). The parameter is then either of the ALPHA type, or a one-dimensional ALPHA table, or a list of an ALPHA zone. The parameter contains the name(s) and location(s) of the file(s) uploaded. The target directory for storing attached file is by default the directory defined by the environment variable java.temp of the JVM. The VaToolBxWSSetAttachmentDirectory function is used to change this location and must be called before the call of the service procedure, i.e. in the INIT_PGM block of the program, which is declared beforehand as a service initialisation block: WS_CONFIGURE SERVICE '_init_pgm_as_method' 'false Example: WS_CONFIGURE OPERATION '@Consumes' 'multipart/form-data' ALPHA(256) FileName LIST LstAttachedFiles FileName PARAM LstAttachedFiles,I[attachment] ... [DECL_PGM] WS_CONFIGURE *SERVICE '_init_pgm_as_method' 'false' [INIT_PGM] CALL_CLASS 'VaToolBx' 'VaToolBxWSSetAttachmentDirectory" 'c:\temp\files'

Notes:

Definition of types supported (subsets)

SSI_1D => SimpleWithoutImage(N)

SwCLS => Simple | REF_CLASS

Maximum occurrence: specifies the maximum number of occurrences of a parameter for a particular type. For example, only one content type parameter is authorized whereas several query type parameters are authorized.

REF_CLASS(CLIENT) iClient

PARAM iClient,I[content]

ALPHA(18) CliCode

ALPHA(50) CliName

PARAM CliCode,I[path] CliName,i[path]

Optional: if the parameter can be optional you have to specify whether it is required or optional. In the latter case, it is possible to assign a default value to it.

NUM_BIN_4 PersCode

ALPHA(32) GroupCode

BOOL Active

DATE Since

PARAM PersCode,I[query:required] GroupCode,I[query:optional('HardisGroup')] Active,I[query:optional(true)] Since,I[query:optional(19950325)]

Multiple values: indicates whether the same parameter can receive several values. If this is the case the parameter must declare a one-dimensional table with the number of elements greater than or equal to the number of values to be received or, when the type permits, a LIST.

NUM_BIN_4 PersCodes[10]

PARAM PersCodes,I[query:required]

The form, content, multipart and attachment types are exclusive.

For an output parameter (Kind O):

Type	Types supported	Occ. max	Multiple values	Comments
header	SSI or SSI_1D	N	Yes	Parameter associated with an HTTP header. The number of occurrences is equal to the number of header fields to be sent. Example: ALPHA(256) hdrLocation PARAM hdrLocation,O[header('Content-Location')] If the parameter is a one-dimensional array, then each value in the array is passed in the form of a header of the same name. Example: ALPHA(32) hdrValues(2) hdrValues(1)=value1 hdrValues(2)=value2 PARAM hdrValues,O[header('headerName)] → headerName : value1, value2
cookie	SSI	N	No	Parameter associated with a cookie. The number of occurrences is equal to the number of cookies to be sent. The directive comment is used, if necessary, to attach a comment to the cookie. The directive max_age is used, if necessary, to set a time limit (in seconds) for the cookie. Example: ALPHA(256) infCookCli PARAM infCookcli,O[cookie('cook_inf_lastcli'):comment('comment'):max_age(3600)]
content	SwCLS	N	No	Parameter associated with the content (body) of the HTTP answer. The format of this content is one of those defined via the @Produces annotation. The content to be sent can be based on all of the following Adelia types (simple types, one-dimensional arrays, LIST, REF_CLASS). It is possible to declare several output parameters of the content type; these are then aggregated into a structure that can be named with the order: WS-CONFIGURE *OPERATION '_root_result_name' 'StrucureName'
multipart	SwCLS	N	No	Parameter associated with part of the contents of the HTTP answer for a message consisting of several data sets grouped together in one body; the format of this content is named multipart. Each identified part of the content may be associated with a parameter; a mime type (Content-Type) may be specified for each of the parts. Example: REF_CLASS(COMPUTER) iComputer REF_CLASS(PRINTER) iPrinter PARAM iComputer,O[multipart('part1'):type('application/xml')] iPrinter,I[multipart('part2'):type('application/json')] ] Note: for the produced format you must choose one of the existing multipart mime types, namely: multipart/form-data multipart/mixed multipart/alternative multipart/related Example: WS_CONFIGURE *OPERATION '@Produces' 'multipart/form-data'
attachment	ALPHA or ALPHA(n) or LIST	1	Yes	Parameter associated with one or more files to be sent (download). The parameter is then either of the ALPHA type, or a one-dimensional ALPHA table, or a list of an ALPHA zone. The parameter contains the name(s) and location(s) of the file(s) to be downloaded. Example: ALPHA(256) FileNames(2) BOOL cRet PARAM FileNames,O[attachment] /* Downloading files pic1.jpg and pic2.jpg located in the directory /* '/images' of the web application. CALL_CLASS 'VaToolBx' 'VaToolBxAwsGetRealPath' '/images/pic1.jpg' FileNames(1) cRet CALL_CLASS 'VaToolBx' 'VaToolBxAwsGetRealPath' '/images/pic2.jpg' FileNames(2) cRet
HTTPstatus	NUM_BIN_4	1	No	Parameter associated with the HTTP status code returned by the service. The httpStatus type parameter is not compulsory; it replaces the code calculated by default and which, in some cases, makes it possible to define a more appropriate return code. Example: NUM_BIN_4 httpstatus PARAM httpstatus,o[httpstatus] if ok_read httpstatus = 200 /* the code HTTP 200 is returned: OK else httpstatus = 404 /* the code HTTP 404 is returned: not found end

Notes:

Definition of types supported (subsets)

SwCLS => Simple | REF_CLASS

Maximum occurrence: specifies the maximum number of occurrences of a parameter for a particular type.
For example, only one attachment type parameter is authorized whereas several multipart type parameters are authorized.

Multiple values: indicates whether the same parameter can receive several values.
If this is the case the parameter must declare a one-dimensional table with the number of elements greater than or equal to the number of values to be received or, when the type permits, a LIST.