Login Register Lost Password? Contact Us Blog Home

SOAPCALL

result := SOAPCALL( [ recset, ] url, service, instructure, [ transform, ] DATASET(outstructure) | outstructure [, options ]);

SOAPCALL( [ recset, ] url, service, instructure, [ transform, ] [ options ] );

result The attribute name for the resulting recordset or single record.
recset Optional. The input recordset. If omitted, the single input record must be defined by default values for each field in the instructure parameter.
url A string containing a pipe-delimited ( | ) list of URLs that host the service to invoke (may append repository module names). This is intended to provide a means for the client to conduct a Federated search where the request is sent to each of the target systems in the list. These URLs may contain standard form usernames and passwords, if required. The default username/password are those contained in the workunit.
service A string expression containing the name of the service to invoke. This may be in the form module.attribute if the service is on a Roxie platform.
instructure A RECORD structure containing the input field definitions from which the XML input to the SOAP service is constructed. The name of the tags in the XML are derived from the names of the fields in the input record; this can be overridden by placing an xpath on the field ( {xpath('tagname')} — see the XPATH Support section of the RECORD Structure discussion). If the recset parameter is not present, each field definition must contain a default value that will constitute the single input record. If the recset parameter is present, each field definition must contain a default value unless a transform is also specified to supply that data values.
transform Optional. The TRANSFORM function to call to process the instructure data. This eliminates the need to define default values for all fields in the instructure RECORD structure. The transform function must take at least one parameter: a LEFT record of the same format as the input recset. The resulting record set format must be the same as the input instructure.
DATASET (outstructure) Specifies recordset result in the outstructure format.
outstructure A RECORD structure containing the output field definitions. If not used as a parameter to the DATASET keyword, this specifies a single record result. Each field definition in the RECORD structure must use an xpath attribute ( {xpath('tagname')} ) to eliminate case sensitivity issues.
options A comma-delimited list of optional specifications from the list below.
Return: SOAPCALL returns either a set of records, a single record, or nothing.

SOAPCALL is a function or action that calls a SOAP (Simple Object Access Protocol) service.

Valid options are:

RETRY(count) Specifies re-attempting the call count number of times if non-fatal errors occur. If omitted, the default is three (3).
TIMEOUT(seconds) Specifies the number of seconds to attempt the read before failing. Setting to zero (0) indicates waiting forever . If omitted, the default is three hundred (300).
HEADING(prefix,suffix) Specifies tags to wrap around the XML input fields. If omitted, the default is: HEADING('','').
XPATH(xpath) Specifies the path used to access rows in the output. If omitted, the default is: 'serviceResponse/Results/Result/Dataset/Row'.
MERGE(n) Specifies processing n records per batch (the blocking). If omitted, the default is 1 (values other than 1 may be incompatible with non-Roxie services). Valid for use only if the recset parameter is also present.
PARALLEL(n) Specifies the number of concurrent threads to have processing Data Delivery Engine queries, to a maximum of 50 (the default is 2). This is intended to limit the number of concurrent sessions.
ONFAIL(transform) Specifies either the transform function to call if the service fails for a particular record, or the keyword SKIP. The TRANSFORM function must produce a resultype the same as the outstructure and may use FAILCODE and/or FAILMESSAGE to provide details of the failure.
TRIM Specifies all trailing spaces are removed from strings before output.
NAMESPACE (namespace) Specifies the top level namespace for the SOAP request.
LITERAL Specifies the service is not necessarily implemented in ESP.

SOAPCALL Function

This form of SOAPCALL, the function, may take as input either a single record or a recordset, and both types of input can result in either a single record or a recordset.

The outstructure output record definition may contain an integer field with an XPATH of "_call_latency" to receive the time, in seconds, for the call which generated the row (from creating the socket to receiving the response). The latency is placed in every row the call returned, so if a call took 90 seconds and returned 11 rows then you will see 11 rows with 90 in the _call_latency field.

Example:

OutRec1 := RECORD
  STRING500 OutData{XPATH('OutData')};
  UNSIGNED4 Latency{XPATH('_call_latency')};
END;
ip := 'http://127.0.0.1:8022/';
ips := 'https://127.0.0.1:8022/';
ipspw := 'https://username:password@127.0.0.1:8022/';
svc := 'MyModule.SomeService';

//1 rec in, 1 rec out
OneRec1 := SOAPCALL(ips,svc,{STRING500 InData := 'Some Input Data'},OutRec1);

//1 rec in, recordset out
ManyRec1 := SOAPCALL(ip,svc,{STRING500 InData := 'Some Input Data'},DATASET(OutRec1));

//recordset in, 1 rec out
OneRec2 := SOAPCALL(InputDataset,ip,svc,{STRING500 InData},OutRec1);

//recordset in, recordset out
ManyRec2 := SOAPCALL(InputDataset,ipspw,svc,{STRING500 InData := 'Some Input Data'},DATASET(OutRec1));

//TRANSFORM function usage example
namesRecord := RECORD
  STRING20 surname;
  STRING10 forename;
  INTEGER2 age := 25;
END;
ds := DATASET('x',namesRecord,FLAT);

inRecord := RECORD
  STRING name{xpath('Name')};
  UNSIGNED6 id{XPATH('ADL')};
END;
outRecord := RECORD
  STRING name{xpath('Name')};
  UNSIGNED6 id{XPATH('ADL')};
  REAL8 score;
END;
inRecord t(namesRecord l) := TRANSFORM
  SELF.name := l.surname;
  SELF.id := l.age;
END;
outRecord genDefault1() := TRANSFORM
  SELF.name := FAILMESSAGE;
  SELF.id := FAILCODE;
  SELF.score := (REAL8)FAILMESSAGE('ip');
END;
outRecord genDefault2(namesRecord l) := TRANSFORM
  SELF.name := l.surname;
  SELF.id := l.age;
  SELF.score := 0;
END;

ip := 'http://127.0.0.1:8022/';
svc:= 'MyModule.SomeService';
OUTPUT(SOAPCALL(ip, svc,{ STRING20 surname := 'Halligan',STRING20 forename := 'Kevin';},
DATASET(outRecord), ONFAIL(genDefault1())));

OUTPUT(SOAPCALL(ds, ip, svc, inRecord, t(LEFT),DATASET(outRecord), ONFAIL(genDefault2(LEFT))));

OUTPUT(SOAPCALL(ds, ip, svc, inRecord, t(LEFT),DATASET(outRecord), ONFAIL(SKIP)));

SOAPCALL Action

The second form of SOAPCALL, the action, may take as input either a single record or a recordset. Neither type of input produces any returned result—it simply launches the specified SOAP service, providing it input data.

Example:

//1 rec in, no result
SOAPCALL( 'https://127.0.0.1:8022/','MyModule.SomeService',{STRING500 InData := 'Some Input Data'});

//recordset in, no result
SOAPCALL( InputDataset,'https://127.0.0.1:8022/','MyModule.SomeService',{STRING500 InData});

See Also: RECORD Structure, TRANSFORM Structure