Setting preferences for the CICS Web Services Assistant (WSBind)

Edit online

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):
  1. In the left pane of the Preferences window, expand Enterprise Service Tools and select Web Services Assistant (WSBind).
  2. Change the preferences (the preferences are described in the following sections).
  3. 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 V5.3 with APAR PI67641 or later, 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.
Limitation:
  • WSDLCP of DFHLS2WS is not supported.

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 5 Release 4 IBM® Documentation). 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.
  • Mapping levels 1.0 to 4.0 are supported in CICS TS 5.2. and 5.3
  • Mapping level 4.1 is compatible with a CICS TS 5.3 region with APAR PI67641 applied, and higher.
  • Mapping level 4.2 is compatible with CICS TS V5.4 with APAR PI86039 applied, and higher.
  • Mapping level 4.3 is compatible with CICS TS V5.4 with APAR PI88519, and higher.

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.

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.
4.0
Use this mapping level with a CICS TS 5.2 region or later. At this level, the following features are available:
  • DFHLS2SC and DFHLS2WS support the COBOL OCCURS DEPENDING ON clause and also supports mapping of COBOL character arrays into XML strings. You can set this behavior by using the CHAR-OCCURS parameter on the CICS assistants.
  • CICS web services support the conversion of application data that is encoded using UTF-16 Unicode.

For more information, see Mapping levels for the CICS assistants.

4.1
Use this mapping level with a CICS TS 5.3 region with APAR PI67641 or later. With this runtime level, the following features are available:
  • TRUNCATE-NULL-ARRAYS and TRUNCATE-NULL-ARRAY-VALUES parameters are supported by DFHLS2SC, DFHLS2WS, and DFHLS2JS.
4.2
Use this mapping level with CICS TS V5.4 with APAR PI86039 applied, and higher. This runtime level is primarily for use with DFHJS2LS, but is also included in the CICS web services assistants, XML assistants, and JSON assistants. It implements support for Additional Properties in JSON, and also adds support for the following three parameters for DFHJS2LS:
  • ADDITIONAL-PROPERTIES-DEFAULT
  • ADDITIONAL-PROPERTIES-MAX
  • ADDITIONAL-PROPERTIES-SIZE
4.3
Use this mapping level with CICS TS V5.4 with APAR PI88519, and higher. This runtime level is primarily for use with DFHJS2LS, but is also included in the CICS web services assistants, XML assistants, and JSON assistants. This mapping level implements support for multidimensional arrays in JSON.l.
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
4.0
The generated web service binding file deploys successfully into a CICS TS 5.2 region or later. With this runtime level, you can use a mapping level of 4.0 or earlier for the MAPPING-LEVEL parameter.
4.1
The generated web service binding file deploys successfully into a CICS TS 5.3 region or later. With this runtime level, you can use a mapping level of 4.1 or earlier for the MAPPING-LEVEL parameter.
4.2
The generated web service binding file deploys successfully into a CICS TS V5.4 with APAR PI86039 applied, and higher. With this runtime level, you can use a mapping level of 4.2 or earlier for the MAPPING-LEVEL parameter.
4.3
The generated web service binding file deploys successfully into a CICS TS V5.4 with APAR PI88519 applied, and higher. With this runtime level, you can use a mapping level of 4.3 or earlier for the MAPPING-LEVEL parameter.
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 application 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.
Data screening: (This is displayed in the Web Services Assistant as the parameter:DATA-SCREENING)
Select this option to specify whether application supplied data is screened for errors. When it is set to ENABLED, any application-supplied runtime data that is inconsistent with the language structure, is treated as an error and message DFHPI1010 is issued. An error response is returned to the application. When it is set to DISABLED, data values in application-supplied runtime data that are inconsistent with the language structure are replaced by default values.
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.

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 in a WSDL file by the single-service project tools. 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 Developer for z/OS. 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.
Char occurs: (This is displayed in the Web Services Assistant as the parameter: CHAR-OCCURS)
This preference specified how character arrays in the language structure are mapped when the mapping level is 4.0 or higher. For example, PIC X OCCURS 20 . This parameter is only for use by the COBOL language.
  • ARRAY

    Character arrays are mapped to an XML array, which means that every character is mapped as an individual XML element. This also applies on the behavior at mapping levels 3.0 and earlier.

  • STRING

    This option is default. Character arrays are mapped to an XML string, which means that the entire COBOL array is mapped as a single XML element.

Char usage: (This is displayed in the Web Services Assistant as the parameter: CHAR-USAGE)
In COBOL, the national data type, PIC N, can be used for UTF-16 or DBCS data. This setting is controlled by the NSYMBOL compiler option. You must set the CHAR-USAGE parameter on the assistant to the same value as the NSYMBOL compiler option to ensure that the data is handled appropriately. This is typically set to CHAR-USAGE=NATIONAL when you use UTF-16.
  • DBCS

    Data from PIC ( n ) fields is treated as DBCS encoded data.

  • NATIONAL

    This is the default value. Data from PIC ( n ) fields is treated as UTF-16 encoded data.

Truncate null arrays: (This is displayed in the Web Services Assistant as the parameter TRUNCATE-NULL-ARRAYS)
This preference specifies how structured arrays are processed. If it is enabled, CICS will attempt to recognize empty records within an array.
Truncate null array values: (This is displayed in the Web Services Assistant as the parameter TRUNCATE-NULL-ARRAY-VALUES)
This preference specifies which values are treated as empty for TRUNCATE-NULL-ARRAYS processing. If all of the bytes of storage in a record of a structured array contain nulls, the entire record is considered to be empty. One or more of the NULL, SPACE, and ZERO values can be specified in a comma separated list.
  • NULL: 0x00, or low-values is treated as empty
  • SPACE: 0x40 is treated as empty
  • ZERO: 0xF0 is treated as empty

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.
Default fraction digits: (This is displayed in the Web Services Assistant as the parameter: DEFAULT-FRACTGION-DIGITS)
This parameter specifies the default number of fraction digits to use in the JSON decimal schema type. The default value is 3. For COBOL, the valid range is 0 to 17, or 0 to 30 if parameter WIDE-COMP3 is being used. For C or PL/I, the valid range is 0 to 30.
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 DFHWS2LS: WSDL to high-level language conversion).
Treat EPR as <xsd:any> type (This is displayed in the Web Services Assistant as the parameter: WSADDR-ERP-ANY)
Specifies whether CICS transforms a WS-Addressing endpoint reference (EPR) into its components parts in the language structures or treats the EPR as an <xsd:any> type. Treating the EPR as an <xsd:any> type means that the WSACONTEXT BUILD API can use the EPR XML directly. This option is not selected by default.
  • FALSE

    DFHWS2LS behaves typically, transforming the XML to a high-level language structure.

  • TRUE

    Setting this option to TRUE means that at runtime CICS treats the whole EPR as an <xsd:any> type and places the EPR XML into a container that can be referenced by the application. The application can use the EPR XML with the WSACONTEXT BUILD API to construct an EPR in the addressing context.

Less duplicate names (This is displayed in the Web Services Assistant as the parameter: LESS-DUP-NAMES)
For PL/I only. This parameter generates non-structural structure field names with _value at the end of the name to enable direct referencing to the field. The suffix _value is appended only when there is a name conflict between the structural name and non-structural name.
Underscores as hyphens (This is displayed in the Web Services Assistant as the parameter: UNDERSCORES-AS-HYPHENS)
For COBOL only. This parameter converts any underscores in the WSDL document to hyphens, rather than the character X, to improve the readability of the generated COBOL language structures. If any field name clashes occur, the fields are numbered to ensure they are unique.
No array name indexing (This is displayed in the Web Services Assistant as the parameter NO-ARRAY-NAME-INDEXING)
This preference is for PL/I only. Ensures that the field names in an array are unique only within the scope of the higher level structure.
Hyphen as underscores: (This is displayed in the Web Services Assistant as the parameter: HYPHEN-AS-UNDERSCORES)
For PL/I only. This parameter converts any hyphens in the WSDL document to underscores rather than the character X, to improve the readability of the generated PL/I language structures. This option is not selected by default.