CALL WEB SERVICE

4D - Documentation   Français   English   German   4th Dimension 2004, Command Theme List   4th Dimension 2004, Command Alphabetical List   4th Dimension 2004, Constant Theme List   Back   Previous   Next

version 2003


CALL WEB SERVICE (accessURL; soapAction; methodName; namespace{; complexType})

ParameterTypeDescription
accessURLStringAccess URL to Web Service
soapActionStringContents of SOAPAction field
methodNameStringName of the method
namespaceStringNamespace
complexTypeLongintConfiguration of complex types
(simple types if omitted)

Description

The CALL WEB SERVICE command is used to call a Web Service by sending an HTTP request. This request contains the SOAP message created previously using the SET WEB SERVICE PARAMETER command.

Any subsequent call to the SET WEB SERVICE PARAMETER command will cause the creation of a new request. The execution of the CALL WEB SERVICE command also erases any result from a previously-called Web Service and replaces it with the new result(s).

In accessURL, pass the complete URL allowing access to the Web Service (do not confuse this URL with that of the WSDL file, which describes the Web Service).

Access in secure mode (SSL): If you want to use a Web Service in secure mode using SSL, pass https:// in front of the URL instead of http://. This configuration automatically enables connection in secure mode.

In soapAction, pass the contents of the SOAPAction field of the request. This field generally contains the value "ServiceName#MethodName".

In methodName, pass the name of the remote method (belonging to the Web Service) that you want to execute.

In namespace, pass the XML namespace used for the SOAP request. For more information about XML namespaces, refer to the Design Mode manual of 4D.

The optional complexType parameter specifies the configuration of the Web Service parameters sent or received (defined using the SET WEB SERVICE PARAMETER and GET WEB SERVICE RESULT commands). The value of the complexType parameter depends on the publication mode of the Web Service (DOC or RPC, see Design Mode manual of 4D) and on its own parameters.

In complexType, you must pass one of the following constants, located in the Web Services (Client) theme:

ConstantTypeValue
Web Service DynamicLongint0 (default)
Web Service Manual InLongint1
Web Service Manual OutLongint2
Web Service ManualLongint3

Each constant corresponds to a Web Services "configuration". A configuration represents the combination of a publication mode (RPC/DOC) and the types of parameters (input/output, simple or complex) implemented.

Note: Remember that the "input" or "output" characteristic of parameters is evaluated from the point of view of the proxy method/Web Service:

an "input" parameter is a value passed to the proxy method and thus to the Web Service,

an "output" parameter is returned by the Web Service and thus by the proxy method (generally via $0).

The following table shows all the possible configurations as well as the corresponding constants:

Input parameters
Output parametersSimpleComplex
SimpleWeb Service DynamicWeb Service Manual In
(RPC mode)(RPC mode)
ComplexWeb Service Manual OutWeb Service Manual
(RPC mode)(RPC or DOC mode)

The five configurations described below can therefore be implemented. In all cases, 4th Dimension will handle the formatting of the SOAP request to be sent to the Web Service as well as its envelope. It is up to you to format the contents of this request according to the configuration used.

Note: Despite the fact that they are complex XML types, data arrays are handled by 4D as simple types.

RPC mode, simple input and output

This configuration is the easiest to use. In this case, the complexType contains the Web Service Dynamic constant or is omitted.

The parameters sent and responses received can be handled directly, without prior processing.

Refer to the example of the command GET WEB SERVICE RESULT.

RPC mode, complex input and simple output

In this case, the complexType parameter contains the Web Service Manual In constant. With this configuration, you must "manually" pass each XML source element in the form of a BLOB to the Web Service, using the SET WEB SERVICE PARAMETER command.

It is up to you to format the initial BLOB as a valid XML element. As its first element, this BLOB must contain the first apparent "child" element of the <Body> element of the final request.

Example

   C_BLOB($1)
   C_BOOLEAN($0)

   SET WEB SERVICE PARAMETER("MyXMLBlob";$1)
   CALL WEB SERVICE("http://my.domain.com/my_service";"MySoapAction";"TheMethod";
                                    "http://my.namespace.com/";Web Service Manual In)
   GET WEB SERVICE RESULT($0;"MyOutputVar";*)

RPC mode, simple input and complex output

In this case, the complexType parameter contains the Web Service Manual Out constant. Each output parameter will be returned by the Web Service in the form of an XML element stored in a BLOB. You retrieve this parameter using the GET WEB SERVICE RESULT command. You can then parse the contents of the BLOB received using the XML commands of 4D.

Example

   C_BLOB($0)
   C_BOOLEAN($1)

   SET WEB SERVICE PARAMETER("MyInputVar";$1)
   CALL WEB SERVICE("http://my.domain.com/my_service";"MySoapAction";"TheMethod";
                                    "http://my.namespace.com/";Web Service Manual Out)
   GET WEB SERVICE RESULT($0;"MyXMLOutput";*)

RPC mode, complex input and output

In this case, the complexType parameter contains the Web Service Manual constant. Each input and output parameter must be stored in the form of XML elements in BLOBs, as described in the two previous configurations.

Example

   C_BLOB($0)
   C_BLOB($1)

   SET WEB SERVICE PARAMETER("MyXMLInputBlob";$1)
   CALL WEB SERVICE("http://my.domain.com/my_service";"MySoapAction";"TheMethod";
                                    "http://my.namespace.com/";Web Service Manual)
   GET WEB SERVICE RESULT($0;"MyXMLOutput";*)

DOC mode

A proxy calling method for a DOC Web Service is similar to a proxy calling method for an RPC Web Service using complex type input and output parameters.

The only difference between these two configurations lies at the level of the XML content of BLOB parameters sent and received. From 4th Dimension's point of view, the building and sending of the SOAP request are identical.

Example

   C_BLOB($0)
   C_BLOB($1)

   SET WEB SERVICE PARAMETER("MyXMLInput";$1)
   CALL WEB SERVICE("http://my.domain.com/my_service";"MySoapAction";"TheMethod";
                                    "http://my.namespace.com/";Web Service Manual)
   GET WEB SERVICE RESULT($0;"MyXMLOutput";*)

Note: In the case of DOC Web Services, the value of the strings ("MyXMLInput" and "MyXMLOutput" above) passed as parameters is of no importance; it is even possible to pass empty strings "". In fact, these values are not used in the SOAP request containing the XML document. It is, nevertheless, mandatory to pass these parameters.

To use a Web Service published in DOC mode (or in RPC mode with complex types), it is advisable to proceed as follows:

Generate the proxy method using the Client Web Services Wizard.

The proxy method will be called in the following manner: $XMLresultBlob:=$DOCproxy_Method($XMLparamBlob)

Familiarize yourself with the contents of SOAP requests to be sent to the Web Service using an on-line test (for instance, http://soapclient.com/soaptest.html). This type of tool is used to generate HTML test forms based on the WSDL of the Web Service.

Copy the XML contents generated from the first child element of <body>.

Write the method enabling you to place the real parameter values into the XML code; this code must then be placed in the $XMLparamBlob BLOB.

To parse the response, you can also use an on-line test, or make use of the WSDL that specifies the returned elements.

See Also

GET WEB SERVICE RESULT, SET WEB SERVICE PARAMETER.

System Variables or Sets

If the request has been correctly routed and the Web Service has accepted it, the system variable OK is set to 1. Otherwise, it is set to 0 and an error is returned.


4D - Documentation   Français   English   German   4th Dimension 2004, Command Theme List   4th Dimension 2004, Command Alphabetical List   4th Dimension 2004, Constant Theme List   Back   Previous   Next