INVOKE SERVICE

Call a service from a CICS® application. The command specifies the name of a service or the CICS resource, such as a WEBSERVICE resource, that contains information about the service to be called.

INVOKE SERVICE

Read syntax diagramSkip visual syntax diagramINVOKESERVICE( data-value) CHANNEL( data-value)OPERATION( data-value)URI( data-value)URIMAP( data-value)SCOPE( data-value)SCOPELEN( data-value)

Conditions: INVREQ, LENGERR, NOTFND, TIMEDOUT

This command is threadsafe.

Description

Use the INVOKE SERVICE command in CICS applications to call a service; for example, the application can act as a web service requester and call an XML-based service, or the application can call another CICS application that is acting as a channel-based service. For more information about these two types of services, see Applications as business services.

Use this command for all new web service applications, rather than the INVOKE WEBSERVICE command, which is a synonym. If you use this command for web services, you must supply specific containers to CICS as input. For more information on writing a web service application, see Creating a web service.

When you invoke the service, you can specify a URIMAP resource that contains the information about the URI of the service. You can specify this information directly on the INVOKE SERVICE command instead of using a URIMAP resource. However, using a URIMAP resource has the following advantages:
  • System administrators can manage any changes to the endpoint of the connection, so you do not need to recompile your applications if the URI of a service provider changes.
  • You can choose to make CICS keep the connections that were opened with the URIMAP resource open after use, and place them in a pool for reuse by the application for subsequent requests, or by another application that calls the same service. Connection pooling is only available when you specify a URIMAP resource that has the SOCKETCLOSE attribute set. For more information about the performance benefits of connection pooling, see Connection pooling for HTTP client performance.

The INVOKE SERVICE command drives the XWBOPEN user exit, which can make the connection to the server go through a proxy server, if required.

Options

CHANNEL(data-value)
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. You can specify the channel name DFHTRANSACTION to use the transaction channel.
OPERATION(data-value)
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.
SERVICE(data-value)
Specifies the name of the service:
  • If you want to invoke a web service, specify the name of the WEBSERVICE resource that defines the web service. 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 resource can be up to 32 characters. The value must be padded with trailing blanks if there are less than 32 characters.
  • If you want to invoke a channel-based service, specify the name of the service. The format of the service is a URI. The name can be up to 32 characters. The value must be padded with trailing blanks if there are less than 32 characters.
SCOPE(data-value)
Acts as a qualifying prefix for the service name. Use SCOPE if you are using the Service Component Architecture (SCA) channel-based services and require an additional prefix to identify the service.
Note: SCOPE only applies to channel-based services.
If you are writing a COBOL program that is translated with the COBOL3 translator option, the length of the data value cannot exceed 160 bytes. If you are using the COBOL2 translator option, you must use a data area instead of a data value.
SCOPELEN(data-value)
A fullword binary value that specifies the length of the scope that prefixes the service name.
URI(data-value)
Specifies a data area containing the URI of the service to be invoked. If specified, this option supersedes any URI specified in the WEBSERVICE resource definition. If you omit both this option and the URIMAP option, the WEBSERVICE binding file associated with the 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, the data area must be padded with trailing blanks. For information about the format of URIs, see The components of a URL.
Do not specify this option for web services that use WS-Addressing.
Do not specify this option if you use connection pooling; use the URIMAP option instead to specify an appropriate URIMAP resource to enable connection pooling.
URIMAP(data-value)
Specifies the name of a URIMAP resource that CICS uses to derive the URI value. Use a URIMAP resource if you want to enable connection pooling, where CICS keeps the client HTTP connection open for this application or another application to reuse. If specified, this option supersedes any URI specified in the WEBSERVICE resource definition. If you omit both this option and the URI option, the WEBSERVICE binding file associated with the resource definition must include either a provider URI or a provider application name.
You must create the URIMAP resource for an HTTP client request with the attribute USAGE(CLIENT). For connection pooling, you must also set the SOCKETCLOSE attribute. The CICS web services assistant does not create the URIMAP resource, so you must define it yourself. For information about creating a URIMAP resource for a client request, see Creating a URIMAP definition for an HTTP request by CICS as an HTTP client.
Do not specify this option for web services that use WS-Addressing.

Conditions

16 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, or the specified host name could not be resolved.
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
The invoked WEBSERVICE returned a SOAP fault. The description of the fault is available in its XML format in the container DFHWS-BODY.
Note: This condition is not raised for XML-ONLY web service invocations.
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
A container does not have the correct DATATYPE. This may be the DFHWS-DATA container, or another container referenced in the application data. The DFHWS-DATA container and most other application data containers must be populated in BIT mode. Any containers that hold XML markup must be populated in CHAR mode.
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
An input error was detected either generating a SOAP request message or processing a SOAP response message. A DFHPIxxxx message is written to MSGUSR to document the problem in more detail. It is likely that the application data structure contains invalid data that cannot be converted to a SOAP request message. For more information, see the error message in the DFH-XML-ERRORMSG container.
14
A 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.
A DFHPIxxxx message is written to MSGUSR to document the problem in more detail. For more information, see the error message in the DFH-XML-ERRORMSG container.
15
An unhandled error has occurred in the pipeline. Information about the error is in container DFHERROR.
16
A locally optimized web service has abended. The underlying unit of work has been backed out.
17
A remote web service request did not return a response message.
18
The container DFHWS-BODY has not been populated by an application for an XML-ONLY WEBSERVICE.
19
A URI or a URIMAP has been specified, but this option is not allowed when the WEBSERVICE resource has a default WS-Addressing endpoint reference or the WS-Addressing context has been built using the WSACONTEXT BUILD API command.
20
The specified URIMAP does not have a valid scheme.
21
The specified URIMAP is not client mode.
22
The specified URIMAP is not enabled.
23
An unspecified transport or link failure occurred when attempting to use the pipeline. CICS issues a message to document the specific problem.
24
z/OS® Connect pipeline was used.
41
The connection has been closed.
101
The container DFHWS-BODY does not have the correct DATATYPE. For this container, a DATATYPE of CHAR must be specified.
103
The container DFHWS-BODY contains no data.
104
Either the container DFHREQUEST or the container DFHWS-BODY is missing.
105
A 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.
106
Either 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.
107
Either the generated SOAP request message was not a valid SOAP message, or the SOAP response message was not a valid SOAP message.
108
An HTTP error has occurred. Use the HTTP status code available in the DFHRESPONSE container to diagnose the cause of the HTTP error.
109
109 HTTP redirect (301, 302, 303, or 307) response was returned. The Location header is available in the DFHWS-LOCATION container.
22 LENGERR
RESP 2 values:
1
Either the SCOPELEN option was not specified or it was not a valid value.
13 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 specified CHANNEL could not be located.
3
The specified OPERATION was not in the web service binding file.
4
The specified WEBSERVICE could not be located.
5
A CONTAINER specified in the web service binding file could not be located.
6
The specified URIMAP could not be located.
124 TIMEDOUT
RESP2 values:
1
An expected timeout has occurred. When the message exchange pattern specifies an optional error response, and an error response is not returned from the remote web service, the timeout is acceptable.
2
An unexpected timeout has occurred. A response was expected from the remote web service, but none was received.
62
An unexpected timeout has occurred on socket receive.