Start of change

INVOKE WEBSERVICE

This command invokes a Web service from a CICS application. The command specifies the name of a WEBSERVICE resource, which contains information about the service to be invoked.

Read syntax diagramSkip visual syntax diagram
INVOKE WEBSERVICE

>>-INVOKE-WEBSERVICE(name)--CHANNEL(name)----------------------->

>--OPERATION(data-area)--+----------------+--------------------><
                         '-URI(data-area)-'   

This command is threadsafe.

Description

INVOKE WEBSERVICE enables a CICS application to act as a Web service requester.

Start of changeThe INVOKE WEBSERVICE command drives the XWBOPEN user exit, which can make the connection to the server go through a proxy server, if required.End of change

Options

CHANNEL(name)
specifies the name of the channel used to pass the containers that hold the data mapped by the application data structure. On return, the same channel holds the response from the Web service, again mapped by the application data structure. The name of the channel can be up to 16 characters. If name is a variable, and it contains a name that is less than 16 characters, then the variable must be padded with trailing blanks.
OPERATION(data-area)
specifies a data area containing the name of the operation that is to be invoked. The name of the operation is contained in the WSDL for the target Web service. The data area must be 255 characters long; if the operation name is less than 255 characters, then the data area must be padded with trailing blanks.
URI(data-area)
specifies a data area containing the URI of the Web service to be invoked. If specified, this option supersedes any URI specified in the WEBSERVICE resource definition. If this option is omitted, then the WEBSERVICE resource definition must include either a provider URI or a provider application name. The data area must be 255 characters long; if the URI is less than 255 characters, then the data area must be padded with trailing blanks.
WEBSERVICE(name)
specifies the name of the WEBSERVICE resource that defines the Web service to be invoked. The WEBSERVICE resource specifies the location of the Web service description, and the Web service binding file that CICS uses when it communicates with the Web service. The name of the WEBSERVICE can be up to 32 characters. If name is a variable, and it contains a name that is less than 32 characters, then the variable must be padded with trailing blanks.

Conditions

INVREQ
RESP2 values:
1
The name specified for the CHANNEL option contains an illegal character or combination of characters.
2
The name specified for the OPERATION option contains an illegal character or combination of characters.
3
The Web service binding file associated with the WEBSERVICE is invalid.
4
The value specified for the URI contained an illegal character or combination of characters.
5
The PIPELINE used by the WEBSERVICE is defined as a service requester pipeline but is invoked in a service provider or vice versa.
6
Start of changeThe invoked WEBSERVICE returned a SOAP fault. The description of the fault is available in its XML format in the container DFHWS-BODY.End of change
7
The URI option was not specified on the command, and the WEBSERVICE definition does not specify a URI or a program name.
8
The WEBSERVICE is not in service
9
The container DFHWS-DATA does not have the correct DATATYPE. For this container, a DATATYPE of BIT must be specified.
10
The PIPELINE used by the WEBSERVICE is not enabled.
11
CICS could not link to the program specified in the WEBSERVICE definition.
12
The containers that the command expects were not on the correct channel.
13
The application data structure contains invalid data that cannot be converted to a SOAP request. No further information is available.
14
Start of changeA conversion error occurred when CICS attempted to convert between the application data structure and the SOAP message. Either the application data structure contains invalid data that cannot be converted to a SOAP request, or data in the SOAP response message cannot be converted into the application's data structure. Some possible causes of this condition are:
  • A value in the SOAP response message is larger than the corresponding field in the application's data structure.
  • When building the SOAP request, the Web services binding file indicates that a data field contains packed decimal or zoned decimal data, and the contents of the field are invalid for this data type.
End of change
15
An unhandled error has occurred in the pipeline. Information about the error is in container DFHERROR.
Start of change16End of change
Start of changeA locally optimized Web service has abended. The underlying unit of work has been backed out.End of change
Start of change17End of change
Start of changeA remote Web service request did not return a response message.End of change
Start of change101End of change
Start of changeThe container DFHWS-BODY does not have the correct DATATYPE. For this container, a DATATYPE of CHAR must be specified.End of change
Start of change103End of change
Start of changeThe container DFHWS-BODY contains no data.End of change
Start of change104End of change
Start of changeEither the container DFHREQUEST or the container DFHWS-BODY is missing.End of change
Start of change105End of change
Start of changeA fault was built within the service requester PIPELINE used by the WEBSERVICE, either while the request was being sent, or while the response was being processed. This condition could indicate that a header processing program has issued a fault.End of change
Start of change106End of change
Start of changeEither the generated SOAP request message was not well formed, or the SOAP response message was not well formed. This condition could indicate that the XML parser returned a fatal error code.End of change
Start of change107End of change
Start of changeEither the generated SOAP request message was not a valid SOAP message, or the SOAP response message was not a valid SOAP message.End of change
NOTFND
RESP2 values:
1
The Web service binding file associated with the WEBSERVICE specifies the name of a SOAP message parsing program supplied by another product, but the parsing program could not be found.
2
The CHANNEL specified could not be located.
3
The OPERATION specified was not in the Web service binding file.
4
The WEBSERVICE specified could not be located.
5
A CONTAINER specified in the Web service binding file could not be located.
Start of changeTIMEDOUTEnd of change
Start of change
62
Timeout on socket receive.
End of change
End of change