To set preferences for the CICS® Web
Services Assistant (WSBind), open the Web Services Assistant (WSBind)
page in the Enterprise Service Tools preferences. These options affect
the generated WSBind and language structure files.
These preferences affect the generation of resources only when
you are generating files for the Web services for CICS runtime environment. These preferences
do not affect the generation of resources for the other runtime environments.
To set preferences for the Web Services Assistant (WSBind):
- On the workbench menu bar, select . The Preferences window opens.
- In the left pane of the Preferences window, expand Enterprise
Service Tools and select Web Services Assistant
(WSBind).
- Change the preferences (the preferences are described in the
following sections).
- Click OK when done.
The CICS Web
services assistant
The preferences on this page affect the values that the Enterprise
Service Tools passes as input parameters to the CICS Web services assistant. The CICS Web services assistant is
a set of batch utilities, provided in CICS Transactions
Server V3.1, that generate COBOL source files for creating a new Web
service or for calling an existing Web service.
The CICS Web services assistant
is invoked by the following wizards or utilities in the Enterprise
Service Tools:
- Create New Service Interface (bottom-up) wizard
- Map an Existing Service Interface (meet-in-middle) wizard
- Create New Service Implementation (top-down) wizard)
- Command-line batch processor (see Batch processor)
Again, the CICS Web services
assistant is invoked
only when generating output files for
the Web services for CICS runtime
environment.
The Web services assistant includes two procedures, DFHLS2WS and
DFHWS2LS:
- DFHLS2WS generates a Web service description and a Web service
binding file from a high level language data structure. This procedure
is invoked when you want to expose a CICS application
program as a service provider (bottom-up scenario).
- DFHWS2LS generates a high level language data structure and a
Web service binding file from a Web service description. This procedure
is invoked when you want to create a service provider program
for a new or existing CICS application
or when you want to create a service requester program
(top-down scenario).
The CICS Web services assistant
is invoked whether you select compiled runtime XML conversion or interpretive
runtime XML conversion (see
Runtime XML conversion: compiled or interpretive). The type of WSBind
file generated depends on the type of runtime XML conversion that
you select:
- A Native-interface WSBind file is generated if you select interpretive
runtime XML conversion.
- A Vendor-interface WSBind file is generated if you select compiled
runtime XML conversion.
Preferences on the Common tab
The preferences
on the Common tab are passed to the Web services
assistant no matter which runtime scenario you select (bottom-up,
meet-in-middle, top-down) and no matter which runtime XML conversion
type you select (compiled or interpretive):
- Mapping level: (This
is displayed in the Web Services Assistant as the parameter: MAPPING-LEVEL)
- This preference specifies the version of the programmatic interface
shared between CICS and the
application (see CICS®
Transaction Server for z/OS®,
Version 4 Release 1 Information Center). Generally, it
is best to specify the highest mapping level that is available:
- Mapping levels 1.0 to 1.2 are supported in CICS TS 3.1 with APAR PK23547 applied.
- Mapping levels 1.0 to 2.1 are supported in CICS TS 3.2 with APAR PK59794 applied.
- Mapping levels 1.0 to 2.2 are supported in CICS TS 3.2 with APAR PK69738
applied.
- Mapping levels 1.0 to 3.0 are supported in CICS TS 4.1.
The use of old mapping levels is recommended only when regenerating
the XML binding files for XML transformation resources that were previously
deployed with an old mapping level (see CICS®
Transaction Server for z/OS,
Version 4 Release 1 Information Center).
- 1.0
- This is the CICS runtime
default mapping level.
- 1.1
- Use this mapping level if you need to regenerate a binding file
at this specific level.
- 1.2
- This mapping level provides the following features:
- It enables the Char varying parameter on
the DFHLS2WS tab and the DFHWS2LS tab
of the preferences.
- It supports VARYING and VARYINGZ arrays,
Note: Mapping level 1.2 requires APAR PK23547.
- 2.0
- Use this mapping level for CICS TS
3.2.
Note: Use mapping 2.0 if you are deploying the
WSBind file into TXSeries for Multiplatforms.
- 2.1
- Use this mapping level for CICS TS
3.2 and later with APAR PK59794 applied. At this level you can enable
the following features:
- INLINE-MAXOCCURS-LIMIT
See the description
of the Inline maxOccurs limit preference on
the DFHWS2LS tab (see Inline maxOccurs
limit).
- XML-ONLY (also called Pass-through
XML)
See the description of
the Pass-through XML preference on the DFHWS2LS tab
(see Pass-through XML).
- WSDL-NAMESPACE
See the description
of the WSDL namespace preference on the WSDL
and XSD tab (see WSDL
namespace).
Support has been added for the XML schema element <xsd:any>
and the data type xsd:anyType (for DFHWS2LS) (see Support for <xsd:any> and xsd:anyType).
- 2.2
- Use this mapping level with a CICS TS
3.2 region that has APAR PK69738 applied. Mapping level 2.2 provides
the following support:
- Elements with fixed values
- Enhanced support for <xsd:choice> elements
- Abstract data types
- Abstract elements
- Substitution groups
- 3.0
- Use this mapping level for CICS TS
4.1.
- Minimum runtime level: (This
is displayed in the Web Services Assistant as the parameter: MINIMUM-RUNTIME-LEVEL)
- This preference specifies the minimum CICS runtime environment that the Web service
binding file can be deployed into. An error message is displayed if
you select a level that does not match the other parameters that you
have specified.
The value that you select for this preference is
used only if you also select interpretive runtime XML conversion.
If you select compiled runtime XML conversion, then the Enterprise
Service Tools wizard or utility always sets the minimum runtime level
to VENDOR.
- MINIMUM
- The lowest possible runtime level of CICS is allocated automatically given the parameters
that you have specified.
- 1.0
- The generated Web service binding file deploys successfully into
a CICS TS 3.1 region that does
not have APARs PK15904 and PK23547 applied. .
- 1.1
- The generated Web service binding file deploys successfully into
a CICS TS 3.1 region that has
at least APAR PK15904 applied.
- 1.2
- The generated Web service binding file deploys successfully into
a CICS TS 3.1 region that has
both APAR PK15904 and PK23547 applied.
Note: These APARs
are not needed for CICS TS
3.2 and later.
- 2.0
- The generated Web service binding file deploys successfully
into a CICS TS 3.2.
- 2.1
- The generated Web service binding file deploys successfully
into a CICS TS 3.2 that has
APAR PK59794 applied.
- 3.0
- The generated Web service binding file deploys
successfully into CICS TS 4.1
- CURRENT
- The generated Web service binding file deploys successfully into
a CICS region at the highest
available runtime level as the one you are using to generate the Web
service binding file.
- CCSID: (This is displayed in the Web Services
Assistant as the parameter: CCSID)
Specifies the CCSID that is used at run time to encode data
between the application program and the Web services binding file.
The value of this parameter overrides the value of the LOCALCCSID
system initialization parameter. The value must be an EBCDIC CCSID
that is supported by Java™ and z/OS conversion services. If you
do not specify this parameter, the application program uses the CCSID
specified in the system initialization parameter, and the Web service
binding file is encoded in US EBCDIC (Cp037).
- User ID: (This is displayed in the Web Services
Assistant as the parameter: USERID)
In a service provider, this preference specifies a 1-8 character
user ID which can be used by any Web client. For an application-generated
response or a Web service, the alias transaction is attached under
this user ID. The value of this preference is used to define the USERID
attribute of the URIMAP resource when it is created automatically
using the PIPELINE scan command.
Valid characters are A-Z
a-z 0-9 $ @ #.
- Transaction: (This is displayed in the Web Services
Assistant as the parameter: TRANSACTION)
In a service provider, this preference specifies the 1-4 character
name of an alias transaction that can start the pipeline or run a
user application to compose a HTTP response. The value of this preference
is used to define the TRANSACTION attribute of the URIMAP resource
when it is created automatically using the PIPELINE scan command.
Valid
characters are A-Z a-z 0-9 $.
- Service: (This is displayed in the Web Services
Assistant as the parameter: SERVICE)
Use this preference only when directed to do so by IBM® support.
Required
Batch Options:
- PlatformProperties.xml/CodegenPropertyArray/CodegenProperty
- @name="CONVERSION_TYPE"
- @value="interpretive"
- ServiceSpecification.xml/EISService
- Data Truncation: (This is displayed in the Web
Services Assistant as the parameter: DATA-TRUNCATION)
- Selecting this option specifies how the CICS native conversion mechanism
handles truncated data. When set to ENABLED, then CICS accepts truncated aplicatoin data and assumes
that missing data is set to nulls. The ENABLED setting is only supported
at mapping levels 3.0 and higher. When set to DISABLED, then CICS rejects truncated application
data and sends an error message. The default value is DISABLED.
- Syncpoint on return (This is displayed in the
Web Services Assistant as the parameter: SYNCONRETURN)
- Selecting this option specifies that the remote web service can
issue a syncpoint. The implication of setting this option to YES is
that the remote task is committed at return. The remote task is classified
as a separate unit of work (UOW). This means that if the remote web
service updates a recoverable resource and then there is a failure
after it returns, the update cannot be backed out. If this option
is defaulted or set to NO and the remote web service issues a syncpoint,
then the remote task fails with ABEND ADPL. For more information,
see Description of PK406622 on http://www.ibm.com/support/docview.wss?uid=swg1PK40662
Preferences on the DFHLS2WS
tab
The preferences on the DFHLS2WS tab
are passed to the Web services assistant only when the scenario type
is Create New Service Interface (bottom-up) and the runtime XML conversion
type is interpretive. (The batch processor equivalent of Create New
Service Interface (bottom-up) is the EISService element.)
These
preferences are not enabled if the option selected in Mapping
level list box or the Minimum runtime level list
box on the Common tab does not support them.
- Char varying: (This is displayed in the Web Services
Assistant as the parameter: CHAR-VARYING)
- This preference specifies how character arrays in the language
structure are mapped when the mapping level is 1.2 or
higher.
Note: This preference does not apply to Enterprise and
other PL/I language structures.
- NO
- Character arrays are mapped to an xsd:string and are processed
as fixed length fields. The maximum length of the data is equal to
the length of the array.
- NULL
- Character arrays are mapped to an xsd:string and are processed
as null-terminated arrays. CICS adds
a terminating null character when transforming from a SOAP message.
The maximum length of the character string is calculated as one character
less than the length indicated in the language structure.
- COLLAPSE
- Generate XML character data description with the whiteSpace attribute set to "collapse".
This value is only available at mapping levels of 1.2 and higher.
This value is the default for mapping levels 2.1 and higher.
- BINARY
- Any character arrays defined in the language structure are mapped
to fixed length xsd:base64Binary fields in the WSDL rather than to
xsd:string fields.
- SOAP Version (This is displayed in the Web Services
Assistant as the parameter: SOAPVER)
This preference controls what version of the
SOAP protocol binding is generated by the IBM Rational® Developer
for System z® in a WSDL
file. The valid values for this option are "1.1", "1.2", and "ALL".
When a particular version is specified, the SOAP binding conforming
to that SOAP protocol version is generated in the WSDL file. If ALL
is selected , both bindings are generated in the WSDL file.
If this option is not specified by the user, then the
default value of this option depends on the setting of the WSDL
VERSION: If the requested WSDL version is set to 1.1, then the
default value of the SOAP version is set 1.1. If the requested WSDL
version is set to 2.0, then the default value of the SOAP version
is set to 1.2.
In addition, specifying this option
forces the setting of the Minimum Runtime Level to a value of 2.0.
For additional information refer to
Minimum Runtime Level
options.
Note: This option affects only CICS Web services interpretive bottom-up scenario.
For more information on the behavior of the WSBind file with various
SOAP versions, see the CICS TS
3.2 documentation.
- WSDL Version (This is displayed in the Web Services
Assistant as the parameter: WSDL_1.1 or WSDL_2.0)
This preference
controls what version of
the WSDL (Web service description) is generated by IBM Rational Developer
for System z. Currently
the valid values for this option are "1.1" and "2.0". This option
affects only CICS Web services
interpretive bottom-up scenario. Note: Specifying
2.0 as WSDL version forces the minimum runtime level option to be
set to 2.0 regardless of the setting of the WSBind mapping level.
For more information refer to for see the description of the mappingLevel
attribute (see
Mapping
Level Description) and the runtimeLevel attribute (see
Runtime Level Description).
- Date/Time: (This is displayed in
the Web Services Assistant as the parameter: DATETIME)
- This preference specifies XML elements are mapped
in a bottom-up scenario and is only valid for the CICS interpretive type (this preference is ignored
for the vendor compiled conversion type). Selecting this option specifies
how the XML elements of xsd:dateTime type are mapped into CICS ASKTIME format. The valid
values are PACKED15 or UNUSED.
Note: This preference is only available
at mapping level 3.0 and higher.
Preferences on the DFHWS2LS tab
The preferences
on the DFHWS2LS tab are passed to the Web services
assistant only when the scenario type is Create New Service Implementation
(top-down) and the runtime XML conversion type is interpretive. (The
batch processor equivalent of Create New Service Implementation (top-down)
is the EISServiceImplementation element.)
These preferences
are not enabled if the option selected in Mapping level list
box or the Minimum runtime level list box on
the Common tab does not support them.
- Char varying: (This is displayed in the Web Services
Assistant as the parameter: CHAR-VARYING)
- This preference specifies how variable length character data is
mapped when the mapping level is 1.2. Variable length binary data
types are always mapped to either a container or a varying structure.
If you do not specify this parameter, the default mapping depends
on the language specified.
- NO
- Variable length character data is mapped as fixed length strings.
- NULL
- Variable length character data is mapped to null terminated strings.
- YES
- Variable length character data is mapped to a Char varying data
type in PL/I. In the COBOL, C and C++ languages, variable length character
data is mapped to an equivalent representation that composed of two
related elements, data length and the data.
- Char varying limit: (This is displayed in the
Web Services Assistant as the parameter: CHAR-VARYING-LIMIT)
- This preference specifies the maximum size of binary data and
variable length character data that is mapped to the language structure
when the mapping level is 1.2. The value can range from 0 to 32767
bytes. The default value is 32767 bytes.
If the character or binary
data is larger than the value specified in this parameter, it is mapped
to a container and the container name is used in the generated language
structure.
- Default char max length: (This is displayed in
the Web Services Assistant as the parameter: DEFAULT-CHAR-MAXLENGTH)
- This preference specifies the default array length of character
data in characters for mappings where no length is implied in the
Web service description document, when the mapping level is 1.2. The
value can be a positive integer in the range of 1 to 2147483647.
- Char multiplier: (This is displayed in the Web
Services Assistant as the parameter: CHAR-MULTIPLIER)
- This preference specifies the number of bytes to allow for each
character when the mapping level is 1.2. The value of this parameter
can be a positive integer in the range of 1 to 2147483647. All nonnumeric
character-based mappings, are subject to this multiplier. Binary,
numeric, zoned and packed decimal fields are not subject to this multiplier.
This
parameter can be useful if, for example, you are planning to use DBCS
characters where you could opt for a multiplier of 3 to allow space
for potential shift-out and shift-in characters around every double
byte character at run time.
- Inline maxOccurs limit: (This is displayed in
the Web Services Assistant as the parameter: INLINE-MAXOCCURS-LIMIT)
- The value specified by this preference is used to decide whether
or not to in-line variable repeating content based on the value of
the maxOccurs attribute from the source WSDL file. For a full description
see:
- Date/Time: (This is displayed in
the Web Services Assistant as the parameter: DATETIME)
- This preference specifies XML elements are mapped
in a top-down scenario and is only valid for the CICS interpretive type (this preference is ignored
for the vendor compiled conversion type). Selecting this option specifies
how the XML elements of xsd:dateTime type are mapped into CICS ASKTIME format. The valid
values are PACKED15 or UNUSED.
Note: This preference is only available
at mapping level 3.0 and higher.
- Name truncation: (This is displayed in the Web
Services Assistant as the parameter: NAME-TRUNCATION)
- This preference specifies how a generated field
name is shortened if it is too long for use in the specified high-level
language. This option is available at all mapping levels.
- RIGHT
- The field name is truncated from the right and a numeric suffix
is added if necessary.
- LEFT
- The field name is truncated from the left and a numeric suffix
is added if necessary.
- 31 - digit decimal support: (This is displayed in the Web Services
Assistant as the parameter: WIDE-COMP3)
- This preference controls the maximum size of the pack decimal
variable length that is mapping to a COBOL Language structure. If
set to YES, it will use 31 digits for DECIMAL and INTEGER types. If
set to NO (default), the number of digits remains at 18. This option
is available at all mapping levels.
- Pass-through XML (This is displayed in the Web
Services Assistant as the parameter: XML-ONLY)
- When this option is selected CICS does not perform any transformations to
the XML at all and instead requires that the application work with
the contents of the DFHWS-BODY container directly (see http://publib.boulder.ibm.com/infocenter/cicsts/v4r1/topic/com.ibm.cics.ts.webservices.doc/reference/dfhws_ws2ls.html).