| Hardis - Séquence de feuilletage |
|---|
| Hardis - Tableau personnalisé | ||||||
|---|---|---|---|---|---|---|
| ||||||
|
...
|
...
|
...
...
Note: With VADELIA batch programs, this instruction is not compatible with the Mobile client generator.
Context for use
SOAP Web Service consumption.
Section for use
All
...
Syntax
WS_CALL WebServiceId OperationId SyncMode ReqId HttpAuthentication Headers Data
...
| Hardis - Tableau personnalisé | ||||||||
|---|---|---|---|---|---|---|---|---|
| ||||||||
|
...
|
...
...
|
...
|
...
|
...
|
...
Description
This instruction calls the WebServiceId Web service's OperationId operation.
The *ASYN directive is used to call the operation asynchronously. If a response is expected use the WS_GET_STATE instruction to determine result availability.
For simultaneous asynchronous calls to a given service, specify a request ID using the *ID directive. This ID lets you identify a request amongst a group of requests and to precisely retrieve its results. If no ID is specified, then ID 1 is used by default. By default, the maximum number of requests is 10. You can modify this number via the <MaxNoSessions> element in the configuration file.
If the Web service requires HTTP authentication, use the *CONNECTION LOGIN directive to specify the authentication mode (*BASIC by default), user name, password and, in the case of *NTLM mode, the domain name. The latter can possibly be decomposed into : domain, workstation, flags. The reserved word *USER can be used to qualify the user's name. *AUTO mode provides, if necessary, BASIC or DIGEST type HTTP authentication.
The *HTTP_HEADERS(LIST(alpha, alpha)) option takes an Adelia memory list composed of 2 ALPHA-type fields as a parameter.
If the list is not empty before the call, the headers are added to the HTTP query.
When returned, if it is successful, the list contains the headers of the HTTP response.
The response headers are not managed in the case of an asynchronous call (*ASYN).
The *HTTP_HEADERS option is ignored when the web service is SOAP RPC/Encoded style with a call in "parameter" mode (a warning message is sent during generation).
Web service operation can be called in "message" mode, or in "parameter" mode. This latter is only possible for an operation with simple (scalar) input parameters: this information is specified in the Web service information.
In "parameter" mode, the effective operation parameters are specified at the end of the instruction. These parameters can be variables, but also constants or reserved words (type ALPHA, NUM_E, NUM_P, NUM_BIN_2, NUM_BIN_4 or NUM_BIN_8).
In "message" mode, the effective parameters (or data) are passed via an XML document. It takes on the form of the SOAP message body and its structure must match that of the 'Example request...' option, available from the Web service modification dialog box.
The XML document is either a file, whose name should be specified in the *SOAPBODY_FILE directive, or a memory area (ALPHA variable or constant or IMAGE variable) that must be used with the *SOAPBODY_MEM directive.
By default, the version of the SOAP envelope created is based on the Web service information registered in the Adelia environment. If no information is provided by the service, the user can add an extra argument using the reserved words *SOAP_ENV_11 and *SOAP_ENV_12. If no information is specified, either by the service or the user, the, a SOAP 1.1 envelope is created.
One or more optional SOAP headers can be added to the message. For this and depending on the nature of the XML document(s) provided (file or memory area), use one of the two directives *SOAPHDR_FILE or *SOAPHDR_MEM.
Notes:
- Calling a Web service operation can take some time, and the call may fail for the following reasons:
- the Web service's location is no longer valid;
- no response was received within the set time (time-out);
- one or more parameters do not match their definitions (type and restriction).
- Calling a Web service operation can take some time, and the call may fail for the following reasons:
- In "parameter" mode, the OperationId name must match an operation declared during service registration. The name is case-sensitive.
- In "message" mode, the OperationId name is not checked during verification. It must, however, correspond to an actual service operation.
- The keywords *ASYN, *ID, *AUTO, *DIGEST and *NTLM are not supported in "parameter" mode if the service's SOAP style is "RPC/Encoded".
...
It is possible to check that the call has been made by testing the *RETURN_CODE reserved word.
If this reserved word returns a value other than *NORMAL, the *RETURN_MSG provides a description of the error.
Example
Examples ("parameter" mode)
...
/* Calling the STRINGMANAGEMENT service's StringLength operation
...
ASS_RET_DEBUG_MSG: = *RETURN_MSG
end
/* Calling the GLOBALWEATHER service's GetWeather operation
...
WS_CALL GLOBALWEATHER GetWeather 'grenoble' 'france'
...
/* Call the MYSERVICE service's oper1 operation with HTTP authentication in AUTO mode.
...
/* authentication information.
WS_CALL MYSERVICE oper1 *CONNECTIONLOGIN(*AUTO, 'username', 'password') Param1 Param2
...
WS_CALL MYSERVICE oper1 *ASYN Param1 Param2
Note: Only non 'RPC/Encoded' style SOAP Web services can make asynchronous calls in 'parameter' mode and then only if the Web service used by the server is compatible.
Examples ("message" mode)
a. Passing the message body (data)
XML document to be used as message body:
...
The default XML document encoding is UTF-8. To change the encoding method, add the XML header specifying the desired encoding to the document:
<?xml version="1.0" encoding="windows-1252"?>
...
<ns:CountryName>france</ns:CountryName>
</ns:GetWeather>
- Use a memory buffer (variable or constant)
...
WS_CALL GLOBALWEATHER GetWeather *SOAPBODY_MEM(varAlpXML)
Constant
WS_CALL GLOBALWEATHER GetWeather *SOAPBODY_MEM('<ns:GetWeatger xmlns:ns="http://www.webserviceX.NET"><ns:CityName>grenoble</ns:CityName><ns:CountryName>france</ns:CountryName></ns:GetWeather>)
...
- Use a file
The file location is specified by means of an alphanumeric variable or constant.
...
WS_CALL GLOBALWEATHER GetWeather *SOAPBODY_FILE(varAlpDir)
...
Constant
WS_CALL GLOBALWEATHER GetWeather *SOAPBODY_FILE('c:\xmlbodies\bodyweather1.xml')
...
b. Passing a SOAP header
It is optionally possible to add one or more headers to the SOAP message to send to the service.
...
WS_CALL GLOBALWEATHER GetWeather *SOAPBODY_FILE(varAlpDir) *SOAPHDR_MEM(varHeader)
Use a table to simultaneously pass several distinct headers:
...
WS_CALL GLOBALWEATHER GetWeather *SOAPBODY_FILE(varAlpDir) *SOAPHDR_MEM(varHeader)
Constant
WS_CALL GLOBALWEATHER GetWeather *SOAPBODY_FILE(varAlpDir) *SOAPHDR_MEM('<reqinfo><timestamp>2012-01-15-09.32.00</timestamp></reqinfo>')
- Use a file
The file location is specified by means of an alphanumeric variable or constant.
...
WS_CALL GLOBALWEATHER GetWeather *SOAPBODY_FILE(varAlpDir) *SOAPHDR_FILE(varHeaderFic)
Constante
WS_CALL GLOBALWEATHER GetWeather *SOAPBODY_FILE(varAlpDir) *SOAPHDR_FILE('c:\xmlheaders\headweather1.xml')
c. Other directives
/* Asynchronous call with a request ID equal to 2.
...
WS_CALL GLOBALWEATHER GetWeather *ASYN *ID(2) *CONNEXIONLOGIN(*AUTO, 'user', 'pwd') *SOAPBODY_MEM(varAlpXML)
/* HTTP BASIC type authentication with connection profile ('user', 'pwd').
WS_CALL GLOBALWEATHER GetWeather *CONNEXIONLOGIN(*BASIC, 'user', 'pwd') *SOAPBODY_MEM(varAlpXML)
/* HTTP NTLM type authentication with connection profile ('user', 'pwd') on the 'domain' windows domain.
WS_CALL GLOBALWEATHER GetWeather *CONNEXIONLOGIN(*NTLM, 'user', 'pwd', 'domain') *SOAPBODY_MEM(varAlpXML)
/* HTTP NTLM type authentication with connection profile ('user', 'pwd') on the 'domain' windows domain, 'ws' workstation.
...
varDomain = 'domain'
varWorkstation = 'ws'
WS_CALL GLOBALWEATHER GetWeather *CONNEXIONLOGIN(*NTLM, 'user', 'pwd', varDomain:varWorkstation) *SOAPBODY_MEM(varAlpXML)
or
WS_CALL GLOBALWEATHER GetWeather *CONNEXIONLOGIN(*NTLM, 'user', 'pwd', 'domain:ws') *SOAPBODY_MEM(varAlpXML)
...
/* Use of *HTTP_HEADERS
ALPHA(64) HdrAttr
...
ADD_TRACE zTrace
END_READ_LST
Example of creating an XML document using Adelia XML instructions
An XML document can be created using Adelia XML instructions. As such, all Adelia types are automatically serialized.
Moreover, the Adelia XML_OPEN instruction can create an XML document either in a file, an ALPHA variable or an IMAGE variable.
Creating an example XML document using Adelia XML instructions.
...
/* XML document contained in an IMAGE variable
IMAGE docXML
/* Creation of an XML document with 'windows-1252' character encoding
XML_OPEN idfx *write *VAR_DOC(XMLdoc) *version('1.0') *file_encoding('windows-1252')
/* Creation of document nodes
...
XML_SET_VAL idfx 'france'
XML_CLOSE idfx
/* Calling the GLOBALWEATHER service's GetWeather operation with
...
WS_CALL GLOBALWEATHER GetWeather *SOAPBODY_MEM(XMLdoc))
| Développer | ||
|---|---|---|
| ||
...