EXECUTE_HTTP

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

Section for use

All

Syntax

EXECUTE_HTTP *URL(Url) *OPTIONS(Options) *DATA(data) *HEADER(Header) Response *COOKIES(Cookies) *HTTP_CODE (httpCode)

Url	→	<alpha variable> \| <alpha constant>
Options	→	<alpha variable> \| <alpha constant>
Data	→	Type, Value
Type	→	<alpha variable> \| <alpha constant>
Value	→	<alpha variable> \| <alpha constant> \| <image variable> \| <list>
List	→	<Adelia list: alpha, alpha, alpha, image, alpha>
Header	→	<Adelia list: alpha, alpha>
Response	→	RESPONSE(response) \| FILE(fileName)
Response	→	<alphanumeric variable \| <image variable>
FileName	→	<alphanumeric variable> \| <alphanumeric constant>
Cookies	→	<Adelia list: alpha, alpha, alpha, alpha, alpha, bool, bool>
httpCode	→	<numeric variable>

Description

Used to create an HTTP connection with the Web server and transfer data with the indicated URL.

HTTP GET, POST, PUT, HEAD, OPTIONS, DELETE, TRACE and PATCH options are allowed.

In particular, it is possible to:

- establish secure connections via SSL using certificates,
- define a BASIC or DIGEST authentication mode,
- delegate the request to a Proxy
- use cookies.

Click below to rapidly access the description of the different parameters:

-*URL parameter

- *OPTIONS parameter

- *DATA parameter

- *HEADER parameter

- Response parameter

- *COOKIES parameter

- *HTTP_CODE parameter

*URL

The *URL parameter is a variable or alphanumeric constant which defines, as an input, the resource's URL (Uniform Resource Locator) address.

If the port number is not specified in the URL, Adelia uses port 80.

The URL refers to either a resource available via the HTTP or HTTPS protocol or a local resource accessible via FILE://.

Mandatory parameter.

Example:

EXECUTE_HTTP *URL('http://localhost:8080/awstest/ws/personnes/1') *RESPONSE(RESP_VAR)

Back to the list of parameters

*OPTIONS

The *OPTIONS parameter is used to define, as an input, the options of the HTTP request to execute. This contains the option names followed by their value.

The option name and value are separated by a space.

The option names always start with 2 dashes (--).

Option/value pairs are also separated by a space.

Optional parameter.

Example:

--request GET --header Accept: application/json

NB: if the *OPTIONS parameter is not defined or the --request option is not specified, Adelia considers that the HTTP method to execute is GET.

Example:

The EXECUTE_HTTP *url('http://localhost:8080/awstest/ws/people/') *RESPONSE(RESP_VAR) instruction retrieves the list of people returned by the Web service.

The following options are possible:

- Options relating to server authentication during connection via SSL (https):

Option

Value

Description

--cacert

In Windows or Java generation, defines the name of the file containing the certificates.

Remember: the certificates are used to distribute the public key and check the identify of the server to which the user wishes to send private information.

The certificates must be in PEM format.

In AS/400 generation, defines the full path in the IFS of the store containing all the certificates and CA.

If this option is not defined and the '--insecure' option is not set, the default behavior is to:

- In the C/ Windows execution context: use the Adelia runtime file '%adeliws%/certifs/cacert.pem' containing a default CA certificate package.
  If necessary, this file can be updated via the following link: https://curl.haxx.se/docs/caextract.html
- In the Java execution context: use the CA certificate package from the JRE: '%java_home%/jre/lib/security/cacerts'.
- In AS400: use the default system store in '/QIBM/UserData/ICSS/Cert/Server/DEFAULT.KDB'.

If the option is defined several times, only the last one is taken into account.

- Options relating to client authentication during a connection via SSL (https):

Option	Value	Description
--cert	<Certificate File Name>	In Windows or Java generation, defines the file containing the client certificate to use. The file may contain the private key concatenated with the client certificate (certificatechain file). It may only contain the certificate. In this case, the --key option must be used to define the private key. In AS/400 generation, defines the client certificate label used when it was imported into the DCM. The certificate in PEM or PKCS#12 format must contain the private key when importing into the DCM. If the private key is password protected, you will be asked to enter the password when importing. More information in the Adelia Wiki. Remember: the client certificate enables the server to check that the client is what it claims to be. If the option is defined several times, only the last one is taken into account.
--cert-type	PEM \| DER	Type of certificate provided. If no format is specified, PEM format is used. If the option is defined several times, only the last one is taken into account. Not used in AS/400 generation.
--key	<private key file name>	Name of the file containing the private key. Not used in AS/400 generation.
--key-type	PEM \| DER	Private key format. If no format is specified, PEM format is used. Not used in AS/400 generation.
--pass	<passphrase>	Secret phrase to protect the private key. Remember: the passphrase is equivalent to a highly secure password for encoding the private key. This is necessary for loading the private key when it is encoded. If the option is defined several times, only the last one is taken into account. Not used in AS/400 generation.

- Options relating to a connection via SSL (https):

Option	Value	Description
--insecure	No value to indicate	The server identity and certificate are not checked. However, the transferred data is always encrypted.
--tlsv1	No value to indicate	Uses the TLSv1 version of SSL.
--tlsv1.0	No value to indicate	Uses the TLSv1.0 version of SSL.
--tlsv1.1	No value to indicate	Uses the TLSv1.1 version of SSL.
--tlsv1.2	No value to indicate	Uses the TLSv1.2 version of SSL.
--sslv2	No value to indicate	Uses the SSLV2 version of SSL.
--sslv3	No value to indicate	Uses the SSLV3 version of SSL.

- Options relating to using a proxy:

Option	Parameters	Description
--proxy	<http://[user:password@] ProxyHostName [:PortNumber>	Defines the address of the proxy to use. This can be: preceded by a username and password, followed by a port number. If the port number is not specified, Adelia uses port number 1080. The username and password can be defined via the --proxy-user option. NB: the proxy must be an HTTP proxy. If the option is defined several times, only the last one is taken into account.
--proxy-digest	No value to indicate	Uses DIGEST authentication mode to connect to the proxy server.
--proxy-basic	No value to indicate	Uses BASIC authentication mode to connect to the proxy server. Note: In Java generation, the BASIC authentication mode does not work by default. This is due to the fact that Oracle JDK 8u11 disables BASIC authentication by default. However, it is possible to enable it again by setting the system property jdk.http.auth.tunneling.disabledSchemes at JVM start => '-Djdk.http.auth.tunneling.disabledSchemes=""'. It is recommended to use the DIGEST authentication mode in production (see https://www.oracle.com/technetwork/java/javase/8u111-relnotes-3124969.html).
--proxy-user	<user:password>	Username and password for authentication at the proxy server. If the option is defined several times, only the last one is taken into account.
--proxy-header	<proxyHeaderName: value>	Headers to include in the HTTP request to the proxy server. The option must be repeated as many times as there are headers to include. Example: EXECUTE_HTTP URL('http://exemple.fr/aws_resource') OPTIONS('--proxy-header Cache-Control: proxy-revalidate --proxy-header Transfer-Encoding: chunked') *RESPONSE(RESP_VAR)

- Option relating to cookies:

Option

Parameters

Description

--cookie

<name1=value1 ; name2=value2>

List of cookies to send to the server, which must have been sent previously by the server.

If the option is defined several times, only the last one is taken into account.

- Options relating to authentication:

Option	Parameters	Description
--user	<user : password>	Username and password for authentication at the Web server. If the option is defined several times, only the last one is taken into account.
--digest	No value to indicate	Uses DIGEST authentication mode to connect to the server.
--basic	No value to indicate	Uses BASIC authentication mode to connect to the server.
--anyauth	No value to indicate	Uses the most secure authentication mode of the methods called by the remote site.

- Option relating to the request header:

Option

Parameters

Description

--header

<headerName: value>

Headers to include in the HTTP request to the server.

The option must be repeated as many times as there are headers to include.

Example:

EXECUTE_HTTP *URL('http://exemple.fr/aws_resource') *OPTIONS('--header Content-Type: application/json --header Transfer-Encoding: chunked') *RESPONSE(RESP_VAR)

NB: this option does not include the response Header. The latter are written in the *HEADER parameter..

- Specific options for managing conversions in AS/400 or in Unicode generation:

By default on the AS/400, all "alpha" input values are converted from the current EBCDIC code or Unicode page (in the case of Unicode generation) to the ISO 819 code page, and the received data is converted from the ISO 819 code page to the current EBCDIC code or Unicode page (in the case of Unicode generation).

Option	Parameters	Description
--conv-utf8	<option name> or *DATA	Converts the associated value of the option or data to send from the current EBCDIC or Unicode page into UTF8.
--no-conv	<option name> or *DATA	No conversion is carried out between the EBCDIC or Unicode and ISO 819 code pages.
--conv-utf8	*RESPONSE	Converts the received response from UTF8 into the current EBCDIC code or Unicode page.
--no-conv	*RESPONSE	No conversion is performed on the received response.

The option names must be entered without the "--" characters.

In Java and Windows, you can change the conversion mode for the sent and received data.

By default, in Java, the data to send are converted from UTF16 into the current code page (ANSI/ASCII), and the received data are converted from the current code page (ANSI/ASCII) into UTF16.

Option	Parameters	Description
--conv-utf8	*DATA	Convert the data to send from UTF16 into UTF8.
--conv-utf8	*RESPONSE	Converts the received response from UTF8 into UTF16.
--no-conv	DATA RESPONSE	No conversion is carried out between UTF16 and the current code page.

By default, in Windows (Unicode), the data to send are converted from Unicode into the current code page (ANSI), and the received data are converted from the current code page into Unicode.

Option	Parameters	Description
--conv-utf8	*DATA	Convert the data to send from Unicode into UTF8.
--conv-utf8	*RESPONSE	Converts the received response from UTF8 into Unicode.
--no-conv	DATA RESPONSE	No conversion is carried out between Unicode and the current code page.

By default, in Windows (not Unicode), no conversion is carried out on data to send / to receive.

Option	Parameters	Description
--conv-utf8	*DATA	Convert the data to send from the current code page (ANSI) into UTF8.
--conv-utf8	*RESPONSE	Converts the received response from UTF8 into the current code page (ANSI).

Example: ... *OPTIONS( ... --no-conv *RESPONSE –no-conv *DATA)

Miscellaneous options:

Option	Parameters	Description
--location	No value to indicate	Authorizes protocol redirection (e.g. http to https). If the server returns a 3xx HTTP code, Adelia automatically redirects the request to the new location.
--request	GET GET \| PUT \| POST \| DELETE \| HEAD \| OPTIONS \| TRACE \| PATCH	HTTP method to use.
--compressed	br \| deflate \| gzip \| no value or one or more of these values and separeted by a comma	A compressed response is accepted according to the specified algorithm (br or/and deflate or/and gzip). "--compressed" (without value) is equivalent to "–compressed br,deflate,gzip". Examples: --compressed gzip ==> A compressed response is accepted according to the gzip algorithm --compressed br,deflate ==> A compressed response is accepted according to the br or deflate algorithm. --compressed ==> A compressed response is accepted according to the br or deflate, or gzip algorithm.
--http1.0	No value to indicate	The HTTP protocol version to use is HTTP 1.0.
--http1.1	No value to indicate	The HTTP protocol version to use is HTTP 1.1.
--connect-timeout	<timeout>	Defines a maximum time (in milliseconds) for the server connection step. If this time is exceeded, the *RETURN_CODE reserved word receives the error code 28. If the option is defined several times, only the last one is taken into account.
--max-time	<timeout>	Defines a maximum time (in milliseconds) for the whole operation: connection + data transfer. If this time is exceeded, the *RETURN_CODE reserved word receives the error code 28. If the option is defined several times, only the last one is taken into account.
--user-agent	<agent utilisateur>	Alpha string enabling the client application to identify itself with the server. If the option is defined several times, only the last one is taken into account. Example: EXECUTE_HTTP URL('http://exemple.fr/aws_ressource') OPTIONS('--requestGET --user-agent Mozilla/4.0') *RESPONSE(RESP_VAR)

Back to the list of parameters

*DATA

The *DATA parameter defines the input data to send to the servers.

It has two fields (type and value) which are used to define the type of delivery and the data to send.

The type field defines the delivery method to execute:

Delivery method	Description
DATA	Sends binary data in the case where the value field is an Image variable, or sends alphanumeric data in other cases. In this case, the value field can be either an alpha variable or an alpha constant containing the data, or a list. When the value field is a list, this must be organized as follows: Column 1 => Alphanumeric field containing the field name. Column 2 => Alphanumeric field containing the type of value: A \| F A: the value to send is contained in the alpha-type column 3. F: the value to send is contained in the file whose name is contained in column 3. Column 3 => Alphanumeric field containing either the value or the name of a file. Column 4 => Image type field. Column 5 => Alphanumeric field. Value unknown. When several name/value pairs are defined using the list, the data to send is assembled and separated by the & character. Adelia sends data using the MIME type application/x-www-form-urlencoded.
DATA-FILE	Identical to the DATA type, with the slight difference of when the value field is an alpha variable or alpha constant, it contains the name of a file containing the data to send.
DATA-URLENCODE	Identical to the DATA type to which URL encoding is applied: URL ENCODING. All the characters are converted into '%NN' (where NN is the hexadecimal code of the character), except for the following characters: a-z, A-Z, 0-9, '-', '.', '_' and '~'. Note that this parameter is ignored when the value field is an Image variable.
DATA-URLENCODE-FILE	Identical to the DATA-URLENCODE type, with the slight difference of when the value field is an alpha variable or alpha constant, this contains the name of a file containing the data to send.
FORM	Similar to an HTML form, the data is sent using the MIME type multipart/form-data. A list of name/value pairs to send to the server can be defined. In an HTML form, name represents the name of a form field and value represents its value. The value field must be a list organized as follows: Column 1 => Alphanumeric field containing the field name. Column 2 => Alphanumeric field containing the type of value: A \| F \| I A: the value to send is contained in the alpha-type column 3. F: the value to send is contained in the file whose name is contained in column 3. I: the value to send is contained in the image-type column 4. Column 3 => Alphanumeric field containing either the value or the name of a file. Column 4 => Image type field. Column 5 => Alphanumeric field indicating the content type of the value (e.g. 'image.png'). Optional input, by default: "text/plain" for an alphanumeric field. Note that if the " --conv-utf8" option is set on DATA parameter, for an alphanumeric field, the "charset=utf-8" attribute is added or substituted for Content-type* . The value field may also be an alpha variable, alpha constant or an image containing the data to send. In this case, the field name is forced to "name". For an alphanumeric variable the Content-type automatically has the value "text/plain", or "text/plain;charset=utf-8", depending on the presence of the "--conv-utf8" option on the DATA parameter. When this delivery type is used, the HTTP method must be the POST method. It is not necessary to define it in the OPTIONS parameter.
FORM-FILE	Identical to the FORM type, with the slight difference of when the value field is an alpha variable or alpha constant, this contains the name of a file containing the data to send.

Back to the list of parameters

*HEADER

The *HEADER parameter is an Adelia list containing the headers associated with the response made by the server to the client.

Each element of the list is made up of the header name and value.

Column 1	→	Alphanumeric field containing the header name.

Column 2	→	Alphanumeric field containing the header value.

Optional parameter.

Back to the list of parameters

Response

The Response parameter contains the response made by the server to the client.

- If the parameter is encapsulated by *RESPONSE, it represents either an alphanumeric variable or an image-type variable.
  The variable receives the content of the response.
- If the parameter is encapsulated by *FILE, it represents an alphanumeric variable or an alphanumeric constant which defines the name of the file in which the response is written.

Optional parameter.

Back to the list of parameters

*COOKIES

The *COOKIES parameter is an input/output list.

As an input, the list may contain cookies to send to the server, retrieved for example in response to a previous request. Added to this are cookies returned by the server as an output.

Optional parameter.

The list must contain seven columns and have the following structure:

Column 1	→	Alphanumeric field containing the cookie name.

Column 2	→	Alphanumeric field containing the cookie value.

Column 3	→	Alphanumeric field containing the expiration date beyond which the cookie must no longer be sent.Corresponds to the expires option of the Set-Cookie header.The Date field must have the following format:

Date	→	EEE, dd MMM yyyy HH:mm:ss
EEE	→	Day of the week (in 3 characters): Mon \| Tue \| Wed \| Thu \| Fri \| Sat \| Sun
dd	→	Day of the month: from 01 to 31
MMM	→	Month (in 3 characters): Jan \| Feb \| Mar \| Apr \| May \| Jun \| Jul \| Aug \| Sep \| Oct \| Nov \| Dec
yyyy	→	Year (in 4 figures)
HH	→	Hour: from 0 to 23
mm	→	Minutes
ss	→	Seconds

Column 4	→	Alphanumeric field containing the path, which must exist in the requested resource in order for the cookie to be sent.Corresponds to the path option of the Set-Cookie header.

Column 5	→	Alphanumeric field containing the domain for which the cookie must be sent.Corresponds to the domain option of the Set-Cookie header.

Column 6	→	Booleen field used to block (or not) the sending of a cookie over an insecure connection.Corresponds to the secure option of the Set-Cookie header.

Column 7	→	Booleen field used to block (or not) the reading of a cookie by a JavaScript script, browser side.Corresponds to the httpOnly option of the Set-Cookie header.

Back to the list of parameters

*HTTP_CODE

The *HTTP_CODE parameter receives the HTTP code of the request result in return.

Optional parameter.

In the event of an internal error or due to incorrect parameter passing, this parameter may not be updated.

If this happens, reserved word *RETURN_CODE can be tested after executing the instruction. If the operation has been carried out successfully, *RETURN_CODE returns *NORMAL.

Click here to see the list of return codes

-1	Invalid parameters.
0	The instruction was executed correctly.
1	The protocol defined in the URL is not supported.
2	Internal error.
3	The URL is not correct.
4	At least one of the options defined in the *OPTIONS parameter is not correct.
5	The proxy was not found.
6	The resource defined in the URL was not found.
7	Unable to connect to the destination server or proxy server.
9	Access to the resource is not authorized.
18	The transferred data size exceeds the limits.
23	Error when retrieving data in the data parameter.
25	Unable to start data upload.
26	Error when reading the data to send.
27	A memory allocation request has failed.
28	The specified wait time for executing the request has been reached (timeout).
30	Error when adding a section to a multipart/form-data.
34	POST HTTP method error.
35	Error during secure connection (SSL). The error may be due to a certificate, user authority or password problem.
37	Unable to open the file indicated in the URL after 'FILE://'. This may be due to an authority problem or error in the access path definition.
43	Error when calling an internal function.
47	The redirection limit has been exceeded.
48	One of the options passed in the *OPTIONS parameter is unknown.
51	The remote server certificate is incorrect.
52	No information has been returned by the server.
55	Error when sending data.
56	Error when receiving data.
58	Error relating to the client's certificate.
60	The certificates listed in the command do not enable the server to be authenticated.
61	Transfer data encoding is not recognized.
65	Error when re-sending data.
67	The connection was refused by the server.
75	Conversion error relating to the data conversion options.
77	Error when reading the file containing the certificates for server authentication. The indicated directory is incorrect or the user does not have access rights.
78	The resource identified by the URL does not exist.
80	Secure connection closing has failed.
88	Error during chunked transfer.
100	Error when decoding private key.

Back to the list of parameters

Trace mode

All the information sent and received when executing the HTTP request can be traced by enabling "DEBUG" mode in the "com.hardis.adelia.varuntme.executeHttp" logger of the log4c.xml file in a Windows or AS/400 environment and the "com.hardis.adelia.lang.dataTransfer.ExecuteHttp" logger of the log4j2.xml file in a Java environment.

In a Windows or AS/400 environment, more information can be obtained by enabling the "TRACE" level of the specific logger. In this case, the information is contained in the Windows file '%TMP%\executeHttpDumpl<PID>' (where PID is the identifier of the current process) and AS/400 file '/tmp/executeHttpDumpl<PID>' (where PID is the AS/400 JOB number).

Example

* Consumption of a Web service: retrieval of a person's details (GET-type operation)

EXECUTE_HTTP *URL('http://localhost :8080/demo/rest/people/1') *OPTIONS('--header Accept: application/json') *RESPONSE(RESP_VAR) *HTTP_CODE(HTTP_WCODE)

* Consumption of a Web service: updating of a person's details (PUT-type operation)

EXECUTE_HTTP *URL('http://localhost :8080/demo/rest/people/1') *OPTIONS('--request PUT --header Content-Type: application/json --header Accept: application/json') *DATA('DATA' , '{"PERSON": {"NumIdentif":1, "Name":"SMITH", "First name":"JOHN"}}') *RESPONSE(RESP_VAR) *HTTP_CODE(HTTP_WCODE)

* Sending of an image as an attachment (POST-type operation with parameter in multipart/form-data)

EXECUTE_HTTP *URL('http://localhost :8080/demo/rest/uploadimage') *DATA('FORM-FILE' , 'C:\images\voiture.png') *HTTP_CODE(HTTP_WCODE)

↑ Top of page