WEBSERVICE resource definitions

A WEBSERVICE resource defines aspects of the run time environment for a CICS application program deployed in a web services setting, where the mapping between application data structure and SOAP messages has been generated using the CICS web services assistant. Although CICS provides the usual resource definition mechanisms for WEBSERVICE resources, they are typically installed dynamically, using the output produced by the assistant.

The aspects of the run time environment that are defined by the WEBSERVICE resource are:

A pipeline: Defines the set of message handlers that operate on web service requests and responses. The WEBSERVICE resource specifies a separate PIPELINE resource which, in turn, specifies the pipeline configuration file.
A web service binding file: Contains information that is used at run time to perform the mapping between application data structures and SOAP messages. The web service binding file is generated by the CICS-supplied tools.
A web service description: The web services description is used only when runtime validation of SOAP messages is required. Validation of each message is performed against its schema, which is imbedded within the web service description.

An inbound web service request (that is, a request by which a client invokes a web service in CICS) is associated with a WEBSERVICE resource by the URIMAP resource. The URIMAP identifies the WEBSERVICE resource that applies to the URI in the inbound message; the WEBSERVICE specifies the processing that is to be performed on the message.

Although CICS provides the usual resource definition mechanisms for creating WEBSERVICE resources, and installing them in your CICS region, you can instead use the scanning mechanism to dynamically install WEBSERVICE resources in your running CICS system. The advantages of this approach are that it reduces the amount of resource definition required, and that CICS can make direct use of information provided at development time.

To invoke the scanning mechanism, use the PERFORM PIPELINE command.

The name of a dynamically-installed WEBSERVICE is derived from the name of the web service binding file from which the WEBSERVICE definition is generated, and has a maximum length of 32 characters; the names of WEBSERVICE definitions installed from the CSD or with the EXEC CICS CREATE WEBSERVICE are limited to eight characters. For example, a Webservice binding file whose zFS name is /samples/Webservices/WSDir/InquireSingle.wsbind generates a WEBSERVICE definition named InquireSingle

For information about installing web service resource definitions with CEMT and CEDA, see Installing WEBSERVICE resource definitions. For information about working with BAS, see Working with BAS web service resource definitions.

WEBSERVICE resources in CICS bundles

You can use a CICS bundle to create, edit, and install a WEBSERVICE resource definition. If you create a WEBSERVICE resource in this way, you must use the CICS bundle to manage the lifecycle of that resource, and you cannot manage the resource independently.

You can inquire on a WEBSERVICE resource that is dynamically generated by a CICS bundle, by using the EXEC CICS INQUIRE WEBSERVICE or CEMT INQUIRE WEBSERVICE command. However, you cannot issue a DISCARD command against a dynamically generated WEBSERVICE resource. You must issue the command against the BUNDLE resource, and CICS applies it to the WEBSERVICE resource. For more information about defining resources in CICS bundles, see Defining CICS bundles.

Syntax

Attributes

WEBSERVICE(name)

Specifies the 1-8 character name of the WEBSERVICE resource.

Acceptable characters:

A-Z a-z 0-9 $ @ # . / - _ % & ? ! : | " = ¬ , ; < >

Valid characters are listed as they render when the code page is IBM-037. If a different EBCDIC code page is used, be aware of variant characters, as documented in Variant characters.

It is preferable not to use names that start with DFH because these characters are reserved for use by CICS. CICS can delete or discard them and replace them with CICS resources when you upgrade or provide new function or fixes.

ARCHIVEFILE(hfsfile)

Specifies the 1-255 character fully qualified or relative name of an archive that contains one or more WSDL files. The supported format for the archive is .zip.

For an archive for a WEBSERVICE resource defined by online resource definition, the file path is either fully qualified, if prefixed with a forward slash (/), or is relative to the HOME directory of the CICS region user ID.
For an archive for a WEBSERVICE resource defined in a CICS bundle, the file path is relative to the root directory of the CICS bundle. The zFS file must be packaged in the CICS bundle with the WEBSERVICE resource. For more information, see Referencing zFS artifacts in a bundle.

The value specified must be a valid name for a UNIX file:

It must not contain embedded space characters.
It must not contain consecutive instances of the / character.
It is case-sensitive.

Acceptable characters:

A-Z a-z 0-9 . / _ # @ -

Valid characters are listed as they render when the code page is IBM-037. If a different EBCDIC code page is used, be aware of variant characters, as documented in Variant characters.

GROUP(groupname)

Every resource definition must have a GROUP name. The resource definition becomes a member of the group and is installed in the CICS system when the group is installed.

Acceptable characters:

A-Z 0-9 $ @ #

Valid characters are listed as they render when the code page is IBM-037. If a different EBCDIC code page is used, be aware of variant characters, as documented in Variant characters.

Any lowercase characters that you enter are converted to uppercase.

The GROUP name can be up to eight characters in length. Lowercase characters are treated as uppercase characters.

DESCRIPTION(text)

You can provide a description of the resource that you are defining in this field. The description text can be up to 58 characters in length. There are no restrictions on the characters that you can use. However, if you use parentheses, ensure that for each left parenthesis there is a matching right parenthesis. If you use the CREATE command, for each single apostrophe in the text, code two apostrophes.

PIPELINE(pipelinename)

Specifies the 1-8 character name of the PIPELINE resource with which this WEBSERVICE resource is associated.

Acceptable characters:

A-Z 0-9 $ @ #

Valid characters are listed as they render when the code page is IBM-037. If a different EBCDIC code page is used, be aware of variant characters, as documented in Variant characters.

Unless you are using the CREATE command, any lowercase characters that you enter are converted to uppercase.

VALIDATION(NO|YES)

Specifies whether full validation of SOAP messages against the corresponding schema in the web service description should be performed at run time. Validating a SOAP message against its schema incurs considerable processing overhead, and you should normally specify VALIDATION(NO).

Full validation ensures that all SOAP messages that are sent and received are valid XML with respect to the XML schema. If VALIDATION(NO) is specified, checking is performed to ensure that the message contains well-formed XML, but there is no guarantee that the XML is valid.

WSBIND(hfsfile)

Specifies the 1-255 character fully-qualified or relative name of the web service binding file on z/OS UNIX.

For a web service binding file for a WEBSERVICE resource defined by online resource definition, the file path is either fully qualified, if prefixed with a forward slash (/), or is relative to the HOME directory of the CICS region user ID.
For a web service binding file for a WEBSERVICE defined in a CICS bundle, the file path is relative to the root directory of the CICS bundle. The zFS file must be packaged in the CICS bundle with the WEBSERVICE resource. For more information, see Referencing zFS artifacts in a bundle.

The value specified must be a valid name for a UNIX file:

It must not contain embedded space characters.
It must not contain consecutive instances of the / character.
It is case-sensitive.

Acceptable characters:

A-Z a-z 0-9 . / _ # @ -

Valid characters are listed as they render when the code page is IBM-037. If a different EBCDIC code page is used, be aware of variant characters, as documented in Variant characters.

WSDLFILE(hfsfile)

Specifies the 1-255 character fully-qualified or relative name of the web service description (WSDL) file on z/OS UNIX. This file is used when full runtime validation is active.

For a web service description file for a WEBSERVICE resource defined by online resource definition, the file path is either fully qualified, if prefixed with a forward slash (/), or is relative to the HOME directory of the CICS region user ID.
For a web service description file for a WEBSERVICE resource defined in a CICS bundle, the file path is relative to the root directory of the CICS bundle. The zFS file must be packaged in the CICS bundle with the WEBSERVICE resource. For more information, see Referencing zFS artifacts in a bundle.

The value specified must be a valid name for a UNIX file:

It must not contain embedded space characters.
It must not contain consecutive instances of the / character.
It is case-sensitive.

Acceptable characters:

A-Z a-z 0-9 . / _ # @ -

Valid characters are listed as they render when the code page is IBM-037. If a different EBCDIC code page is used, be aware of variant characters, as documented in Variant characters.