WS_CALL

Context for use

SOAP Web Service consumption.

Section for use

All

Syntax

WS_CALL WebServiceId OperationId SyncMode ReqId HttpAuthentication Headers Data

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 *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).

• • 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

/* Pass a single parameter

WS_CALL STRINGMANAGEMENT StringLength string_chs:

if *return_code <> *normal

    ASS_RET_CODE: = *RETURN_CODE

    ASS_RET_DEBUG_MSG: = *RETURN_MSG

end

/* Calling the GLOBALWEATHER service's GetWeather operation

/* Pass 2 ALPHA parameters

WS_CALL GLOBALWEATHER GetWeather 'grenoble' 'france'

/* Call the MYSERVICE service's oper1 operation with HTTP authentication in AUTO mode.

/* AUTO mode determines whether HTTP authentication is necessary and, if so, decides whether BASIC or DIGEST mode should be used. The connection is then established in the required mode with

/* authentication information.

WS_CALL MYSERVICE oper1 *LOGIN(*AUTO, 'username', 'password') Param1 Param2

/* Call the MYSERVICE service's oper1 operation asynchronously.

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:

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

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

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

</ns:GetWeather>

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:GetWeather xmlns:ns="http://www.webserviceX.NET">

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

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

</ns:GetWeather>

- Use a memory buffer (variable or constant)

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>'

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.

Variable

ALPHA(128) varAlpDir

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

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.

- Use a memory buffer (variable or constant)

Variable

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

WS_CALL GLOBALWEATHER GetWeather *SOAPBODY_FILE(varAlpDir) *SOAPHDR_MEM(varHeader)

Use a table to simultaneously pass several distinct headers:

ALPHA(1500) varthead(2)

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

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

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.

Variable

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

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.

/* Automatic HTTP authentication with connection profile ('user', 'pwd').

WS_CALL GLOBALWEATHER GetWeather *ASYN *ID(2) *LOGIN(*AUTO, 'user', 'pwd') *SOAPBODY_MEM(varAlpXML)

/* HTTP BASIC type authentication with connection profile ('user', 'pwd').

WS_CALL GLOBALWEATHER GetWeather *LOGIN(*BASIC, 'user', 'pwd') *SOAPBODY_MEM(varAlpXML)

/* HTTP NTLM type authentication with connection profile ('user', 'pwd') on the 'domain' windows domain.

WS_CALL GLOBALWEATHER GetWeather *LOGIN(*NTLM, 'user', 'pwd', 'domain') *SOAPBODY_MEM(varAlpXML)

/* HTTP NTLM type authentication with connection profile ('user', 'pwd') on the 'domain' windows domain, 'ws' workstation.

ALPHA(32) varDomain

ALPHA(32) varWorkstation

varDomain = 'domain'

varWorkstation = 'ws'

WS_CALL GLOBALWEATHER GetWeather *LOGIN(*NTLM, 'user', 'pwd', varDomain:varWorkstation) *SOAPBODY_MEM(varAlpXML)

or

WS_CALL GLOBALWEATHER GetWeather *LOGIN(*NTLM, 'user', 'pwd', 'domain:ws') *SOAPBODY_MEM(varAlpXML)

/* Use of *HTTP_HEADERS

ALPHA(64) HdrAttr

ALPHA(128) HdrValue

LIST lHeaders HdrAttr HdrValue

HdrAttr = 'JWT1'

HdrValue = 'My token1'

INSERT_ELT lHeaders

HdrAttr = 'JWT2'

HdrValue = 'My token2'

INSERT_ELT lHeaders

SW_CALL WSABCD OpenSession *HTTP_HEADERS(lHeaders)

READ_LST lHeaders

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

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.

/* Declaration of an XML_IDF with service-specific formats

/* web for serializing TIME and TIMESTAMP types.

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

/* 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_CREATE_NODE idfx *FILS 'ns:GetWeather'

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

XML_CREATE_NODE idfx *FILS 'ns:CityName'

XML_SET_VAL idfx 'grenoble'

XML_CREATE_NODE idfx *FRERE 'ns:CountryName'

XML_SET_VAL idfx 'france'

XML_CLOSE idfx

/* Calling the GLOBALWEATHER service's GetWeather operation with

/* the previously created document.

WS_CALL GLOBALWEATHER GetWeather *SOAPBODY_MEM(XMLdoc))

↑ Top of page