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
>>-INVOKE-SERVICE(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.
- 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.
- 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.
- 109
- 109 HTTP redirect (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.