The SOAP Client API is used for handling, building and accessing complex types required to perform a SOAP request. It allows you to build a structures to access their elements and to build values suitable for passing to the SOAP_CLIENT() function. It also allows to de-serialize a SOAP response to a soap_parameter and access its members and attributes safely.

Vectors are used to pass or retrieve a complex type using SOAP These vectors contain special content or UDTs. In SOAP, structures are allowed to have multiple members of the same name, or conditional members (choices). Thus it is not possible to cover all variants of XSD types with UDTs (which would be the most elegant way to represent structures). So to cover all variants of structure handling or to express structures containing attributes, we have to use vectors. Since we used a special structure with vectors for expressing such complex types we introduce the following API to deal with them.

The base of API is a UDT 'soap_parameter':

create type soap_parameter as
		(
		  s any default null,
		  param_type int default 1,
		  param_xsd varchar default null,
		  ver int default 11
		)
		temporary self as ref
;

Its members are:

Its Constructors are:

constructor method soap_complex_parameter ()
Instantiate an empty structure placeholder;

constructor method soap_simple_parameter (val any),
Instantiate an empty simple type placeholder

constructor method soap_array_parameter (n int),
Instantiate an array placeholder

constructor method soap_single_parameter (elm soap_parameter),
Instantiate an element of containing a type of 'elm'

Its Methods are:

method get_length () returns any,
Returns the  length of the parameter

method add_member (name varchar, val any) returns any,
Add a new member element to the structure placeholder

method set_member (name varchar, val any) returns any
Sets the value of an existing member by name or will add a new member  if  the member does not exist

method set_member (pos int, val any) returns any,
the same as above but using ordinal position of the member;

method get_member (name varchar) returns any,
Returns a member's value by name

method get_member (pos int) returns any,
Returns member value by ordinal position

method get_value () returns any,
Returns value for simple types. Only for simple type is applicable

method set_value (val any) returns any,
Sets the value of a simple type

method set_attribute (name varchar, val any) returns any,
Set an attribute value of a structure or simple type

method get_attribute (name varchar) returns any,
Return an attribute value of a structure or simple type

method get_call_param (name varchar) returns any,

Serializes the parameter in a form suitable for passing to the SOAP_CLIENT() function. When several parameters needs to be passed to it, then result of those calls must be concatenated (see vector_concat()) Important: set_xsd have to be called with valid ExQName, before doing get_call_param call.

method set_xsd (xsd varchar) returns any,

Establish a SOAP data-type Expanded QName, referencing the data kept in the soap_parameter. This is a reference to a SOAP complex data-type already defined with soap_dt_define () function (see function reference). This method only sets the relation between data kept in soap_parameter and doesn't check its validity unless serialize is performed. The data-type Expanded QName also will be included into output of the get_call_param method.

<xsd:complexType
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    name="SOAPComplexType"
    targetNamespace="http://soapinterop.org/xsd">
 <xsd:sequence>
	<xsd:element minOccurs="1" maxOccurs="1" name="varInt" type="xsd:int" />
	<xsd:element minOccurs="0" maxOccurs="1" name="varString" type="xsd:string" />
	<xsd:element minOccurs="1" maxOccurs="1" name="varFloat" type="xsd:float" />
 </xsd:sequence>
</xsd:complexType>

declare s soap_parameter ;
s := new soap_parameter ();
s.set_xsd ('http://soapinterop.org/xsd:SOAPComplexType');
s.add_member ('varString', 'string');
s.serialize ('mystruct'); -- will generate an error as, varInt and varFloat are
			              -- missing but they are declared as minOccurs="1"

s.add_member ('varInt', 123);
s.add_member ('varFloat', 3.14);
s.serialize ('mystruct');

<mystruct><varInt>123</varInt><varFloat>3.14</varFloat></mystruct>

par := s.get_call_param ('par1');

(
  ("par1", "http://soapinterop.org/xsd:SOAPComplexType" ), -- designates parameter par1, with type SOAPComplexType
  (<COMPOSITE>, "",	-- this is a marker that it's a struct
	"varInt", 123, 	-- the members name/value pairs follows
	"varFloat", 3.14
  )
)

Further methods are:

method deserialize (xs any, elem varchar) returns any,

Deserializes a element 'elem' from 'xs' (XML tree object) the the soap_parameter.

method serialize (tag varchar) returns any,

Returns an XML document representing the data kept into the soap_parameter.

method set_struct (s any) returns any

Explicitly sets the structure/array/simple type kept in the soap_parameter UDT. This can be used to disassemble a nested complex type into its components.

declare ret any;
declare pa soap_parameter;

pa := new soap_parameter ();
pa.add_member ('varString', 'My String');
pa.add_member ('varInt', 12345);
pa.add_member ('varFloat', 3.1415926);
pa.set_xsd ('http://soapinterop.org/xsd:SOAPStruct');

ret := SOAP_CLIENT (url=>'http://.../interop',
  operation=>'echoStruct', parameters=>pa.get_call_param ('inputStruct'));

pa := new soap_parameter ();
pa.set_xsd ('http://soapinterop.org/xsd:SOAPStruct');
pa.deserialize (ret, 'CallReturn');
return pa.get_member ('varString');

declare ret any;
declare doc, pa soap_parameter;

doc := new soap_parameter ('The document content');
doc.set_attribute ('ID', uuid());
doc.set_xsd ('http://soapinterop.org/xsd:x_Document');

ret := SOAP_CLIENT (url=>'http://.../r3/Compound1', operation=>'echoDocument',
  parameters=>doc.get_call_param ('x'), style=>1);

pa := new soap_parameter ();
pa.set_xsd ('http://soapinterop.org/xsd:Document');
pa.deserialize (ret, 'result_Document');
dbg_obj_print (pa.s);

return pa.get_attribute ('ID');

	See Also:
	SOAP_CLIENT()