Dynamic synchronous callout request processing

You can change the target destination from the specified definition in the callout web service WSDL file. You can also specify a different XML converter to use for callout message processing. Use the supported XML tags in the control data area in your ICAL call to specify a different target destination or XML converter.

Starting in IMS 14, in your IMS callout application you can specify additional XML tags in the control data area of the ICAL call, as follows:

LLLL  <tag1> data1 </tag1>  { LLLL <tag2> data2 </tag2> ... }

You can use the following XML tag to specify an XML converter that is different from the defined converter in the callout web service correlator file:

DFSCNVTR: The name of the XML converter to use for callout message processing. When a converter name is specified in this tag, IMS uses this converter instead of the converter that is defined in the OTMA destination descriptor for request processing. This converter also overrides the XML converter information that is specified in the callout web service correlator file in SOAP Gateway for response processing.; The converter name is 1-8 characters and ends with the letter D.

You can use the following XML tags to specify an endpoint URL that is different from the defined URL in the callout web service WSDL file:

Table 1. Target destination specification tags
Tag	Description	Example
DFSHOSTPORT	The host and the port to route the callout request to. The value for the DFSHOSTPORT tag includes the protocol (HTTP or HTTPS), host name, and the port number.	http://host1.company.com:8080
DFSPORTNAME	The port name for the target destination. This port name must be already defined in the `wsdl:port` element, with the corresponding `soap:address` element and its `location` value that is specified in the callout web service WSDL file.	CheckBalancePort
DFSENDPOINTURL	The target endpoint to route the callout request to, overriding the location value that is defined in the `soap:address` element.	http://host1.company.com:8080/axis2/services/SavingService

Dynamic endpoint URL specification

Each callout web service WSDL file contains one or more ports for the callout target destination. Each port has a port name, with the endpoint URL specified in the location of the soap:address element. In the following example, for the port with a port name of HELLOPort, the endpoint URL is http://host1.company.com:8080/axis2/services/HELLOService.

<wsdl:service name="HELLOService">
   <wsdl:port binding="tns:HELLOBinding" name="HELLOPort">
      <soap:address location="http://host1.company.com:8080/axis2/services/HELLOService" />
   </wsdl:port>
</wsdl:service>

To dynamically change the entire endpoint URL at run time, use the DFSENDPOINTURL tag in your ICAL call.

To dynamically change only the host and port, use the DFSHOSTPORT tag. The following example sets the host and the port information in the ICAL control data area:

<DFSHOSTPORT>https://host1.company.com:7777</DFSHOSTPORT>

As a result, the endpoint URL at run time becomes https://host1.company.com:7777/axis2/services/HELLOService.

If multiple ports are available for a web service, use the DFSPORTNAME tag to specify the port name to use to invoke the external web service. In the following example, when the DFSPORTNAME is set to evening, the endpoint URL is set to http://host1.company.com:8080/axis2/services/PMGreeting.

<wsdl:service name="HELLOService">
   <wsdl:port binding="tns:GoodMorning" name="morning">
      <soap:address location="http://host1.company.com:8080/axis2/services/AMGreeting" />
   </wsdl:port>
   <wsdl:port binding="tns:GoodEvening" name="evening">
      <soap:address location="http://host1.company.com:8080/axis2/services/PMGreeting" />
   </wsdl:port>
</wsdl:service>

Table 2. Usage and error scenarios for destination-related tags
Tag	Usage	Error scenarios
DFSENPOINTURL	This tag takes precedence over the DFSPORTNAME or DFSHOSTPORT tag. A value for the tag must be specified. If either the DFSPORTNAME or DFSHOSTPORT tag is also specified, an informational message is issued, informing you of the precedence.	If the tag is present but the value is empty or is not specified, an IOGS1093E error is issued. SOAP Gateway sends a NAK to IMS with extended reason code 1013, and routes the request to the dead letter queue (HWS$DLQ). If the values are invalid or ill-formed, an IOGS1094E or IOGS1095E error message is generated. SOAP Gateway sends a NAK to IMS with extended reason code 1014 or 1015. The request is routed to the dead letter queue.
DFSHOSTPORT	This tag is ignored if the DFSENDPOINTURL tag is specified. If the DFSENDPOINTURL tag is not specified, this tag is processed based on the following rules: A value must be specified and cannot be left blank. Only HTTP and HTTPS protocol are supported. If the protocol is not specified, the default is set to HTTP. If the DFSPORTNAME tag is also present, SOAP Gateway first retrieves the associated endpoint URL from the callout web service WSDL file, and then replaces the host and port portion of the URL with the value that is defined in the DFSHOSTPORT tag. If the DFSPORTNAME tag is not present, SOAP Gateway retrieves the endpoint URL for the first port name from the WSDL file and replaces the host and port with the value that is specified in the DFSHOSTPORT tag.	When the DFSENDPOINTURL tag is not specified, If the DFSHOSTPORT tag is present but the value is empty, SOAP Gateway issues an IOGS1091E error message. A NAK is sent to IMS with extended reason code 1017. The request is routed to the dead letter queue.
DFSPORTNAME	This tag is ignored if the DFSENDPOINTURL tag is specified. If the DFSENDPOINTURL tag is not specified, this tag is processed based on the following rules: A value must be specified and cannot be left blank. The endpoint URL for the specified port name is extracted from the callout web service WSDL file for invoking the external web service. If the DFSHOSTPORT tag is also present, SOAP Gateway first extracts the endpoint URL for the specified port name from the callout web service WSDL file. The host and port value in the DFSHOSTPORT tag is then used, overriding the host and port information in the endpoint URL.	When the DFSENDPOINTURL tag is not specified: If the DFSPORTNAME tag is present but a value is not specified, SOAP Gateway issues an IOGS1090E error message. A NAK is sent to IMS with extended reason code 1011, and the request is routed to the dead letter queue. If the DFSPORTNAME value does not match any port name in the WSDL file, SOAP Gateway issues an IOGS1086E error message. A NAK is sent to IMS with extended reason code 1010, and the request is routed to the dead letter queue.