Skip to main content

SOAPCALL

result := SOAPCALL( [ recset, ] url, service, instructure, [ transform, ] DATASET(outstructure) | outstructure [, options ] [, UNORDERED | ORDERED( bool ) ] [, STABLE | UNSTABLE ] [, PARALLEL [ ( numthreads ) ] ] [, ALGORITHM( name ) ] );

SOAPCALL( [ recset, ] url, service, instructure, [ transform, ] [ options ] [, UNORDERED | ORDERED( bool ) ] [, STABLE | UNSTABLE ] [, PARALLEL [ ( numthreads ) ] ] [, ALGORITHM( name ) ] );

resultThe attribute name for the resulting recordset or single record.
recsetOptional. The input recordset. If omitted, the single input record must be defined by default values for each field in the instructure parameter.
urlA 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. If calling an ESP Web service, you can append the ver_=n.nn parameter to specify the version of the service. For example:
SOAPCALL('http://127.0.0.1:8010/Wsdfu/?ver_=1.22', 
         'DFUSearchData', 
         instructure,DATASET(outsructure));
serviceA 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.
instructureA 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 lowercase 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.
transformOptional. 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.
outstructureA 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.
optionsA comma-delimited list of optional specifications from the list below.
UNORDEREDOptional. Specifies the output record order is not significant.
ORDEREDSpecifies the significance of the output record order.
boolWhen False, specifies the output record order is not significant. When True, specifies the default output record order.
STABLEOptional. Specifies the input record order is significant.
UNSTABLEOptional. Specifies the input record order is not significant.
PARALLELOptional. Try to evaluate this activity in parallel.
numthreadsOptional. Try to evaluate this activity using numthreads threads.
ALGORITHMOptional. Override the algorithm used for this activity.
nameThe algorithm to use for this activity. Must be from the list of supported algorithms for the SORT function's STABLE and UNSTABLE options.
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(period)Specifies the amount of time to attempt the read before failing. The period is a real number where the integer portion specifies seconds. Setting to zero (0) indicates waiting forever. If omitted, the default is three hundred (300).
TIMELIMIT(period)Specifies the total amount of time allowed for the SOAPCALL. The period is a real number where the integer portion specifies seconds. If omitted, the default is zero (0) indicating no limit.
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.
TRIMSpecifies all trailing spaces are removed from strings before output.
RESPONSE (NOTRIM) Sets flag to prevent space stripping on the response.
NAMESPACE (namespace)Specifies the top level namespace for the SOAP request.
LITERALSpecifies the service is not necessarily implemented in ESP.
SOAPACTION (value)Specifies a value where that value is a string expression typically containing a URN or URL that is required by the web service for proper interoperability.
LOGIf specified, writes details to the log file of the engine (hThor, Thor, or Roxie) to which the SOAPCALL is submitted.
LOG (MIN)Specifies to write minimal details of the SOAPCALL to a log file.
LOG (expression)Specifies to add the expression to the log when performing a SOAPCALL.
ENCODINGSpecifies that the Web service being called requires a different message format, where type information is embedded in the XML.
HTTPHEADERSpecifies header information to be passed to the service. SOAPCALL supports multiple instances of the HTTPHEADER option if you need to specify multiple key/value header strings.

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 In 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)));

//Using HTTPHEADER to pass Authorization info
OUTPUT(SOAPCALL(ds, ip, svc, inRecord, t(LEFT),DATASET(outRecord), ONFAIL(SKIP),
                HTTPHEADER('Authorization','Basic dXNlcm5hbWU6cGFzc3dvcmQ='),
                HTTPHEADER('MyLiteral','FOO')));

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