IBM Developer for z/OS

IBM Developer for z/OS Enterprise Edition

16.0

Developing with Db2, CICS, and IMS

Last updated 2024-10-16

IBM
About this PDF
© International Business Machines Corporation 1992, 2024.

This PDF was generated from the content of the IBM® Developer for z/OS® online documentation. It is
provided for reference only. Many of the links in this PDF do not lead to a target location on the IBM
Developer for z/OS IBM Documentation site. For the most recent content, go to https://www.ibm.com/
docs/en/developer-for-zos/latest.
Some of the content in the IBM Developer for z/OS IBM Documentation site is embedded from other
IBM product documentation sites. Because of this content reuse, the embedded content might not be
included in the generated PDFs.
Developing with Db2 for z/OS
Use Db2® for z/OS Development tooling to connect to Db2 databases on a z/OS system, to run and tune
SQL statements in COBOL, PL/I, and SQL files, and to develop and deploy stored procedures.
For what's new in Db2 for z/OS Development, see “What's new” on page 12.
For notes on workspace migration of Db2 for z/OS Development features, see Db2 for z/OS Development
migration notes.

Before you start

1. Verify that the version of Db2 for z/OS that you want to connect to is supported. See the IBM Software
product compatibility reports. The catalog navigation function requires a connection to Db2 for z/OS
version 12.1.1 or later.
2. Obtain the following information from your Db2 administrator:
• The host name of the z/OS system where Db2 for z/OS is installed.
• The location name and port of the Db2 for z/OS system.
• To use the catalog navigation function your database logon ID must have read access to several Db2
system catalog tables. For more information about accessing system catalog tables, see Enabling
catalog navigation.
• Optional: The port for the SQL Tuning Services server. This server processes the Visual Explain,
Statistics Advisor, and Capture Query Environment tuning features of Db2 for z/OS Development
tooling.
3. If required by your site, obtain a license file for IBM Data Server Driver for JDBC and SQLJ, and import
it into Developer for z/OS. If the license is activated on the Db2 for z/OS system you are connecting to,
then you do not need to do this step. Your Db2 administrator can tell you if this step is necessary. For
help with this step, see Importing a license file.
For more information about the JDBC client license file, see Installing, updating, or upgrading the IBM
Data Server Driver for JDBC and SQLJ on Db2 on Linux, UNIX, and Windows systems.
For information about activating the JDBC license file on the Db2 for z/OS server, see V12R1Mnnn
application compatibility levels for data server clients and drivers.
Tip: If you attempt to connect to Db2 and a license file is required, the product prompts you to import
it.
4. Create a connection to the remote system where Db2 for z/OS is installed.
For instructions, see Creating a connection to a z/OS system or watch this demonstration.

© Copyright IBM Corp. 1992, 2024 1

 Overview and cheat sheets
The Db2 for z/OS Development component provides tools for connecting to Db2 subsystems and SQL
Tuning Services servers, running SQL, and tuning SQL statements, all tightly integrated with the COBOL
and PL/I development tools in the z/OS Projects perspective. This component integrates the tooling for
Db2 for z/OS into the Remote System Environment and the COBOL, PL/I, and z Systems® LPEX editors.

2 Developer for z/OS: Developing with Db2, CICS, and IMS

For a detailed introduction to the tasks you can do with Db2 for z/OS Development tooling, open the
Develop Db2 Applications cheat sheet:
1. From the menu bar, click Help > Cheat Sheets.
2. On the Cheat Sheet Selection window, expand IBM Developer for z/OS, and then select Getting
Started Catalog and click OK. The Cheat Sheets view opens in a new tab.
3. In the left pane of the Getting Started Catalog, expand Getting Started with IBM Developer for
z/OS.
4. Click Develop Db2 Applications.
5. In the right pane of the Cheat Sheets view, click Go to 'Connect to a Db2 for z/OS server'.

Developing with Db2 for z/OS 3

 Connect to a Db2 location
Tip: For more information about connecting with SSL/TSL, auto connect, and other connection options,
see “Connecting to Db2” on page 13. If you want to import database connection profiles from IBM Data
Studio or Eclipse Data tools, see “Importing connection profiles from IBM Data Studio or Eclipse Data
Tools” on page 20.
1. In the Remote Systems view, expand a z/OS system connection, and then expand the Db2 for z/OS
subsystem.
2. Right-click Db2 for z/OS Connections and select New > Db2 for z/OS Connection.
3. Log in to the z/OS system using your Db2 user ID and password.
4. In the Connection information area of the General page of the connection properties window, type
the Location name and Port.
5. In the Authentication information area, choose a login method and enter your authentication
information. For more information about the supported login methods, see “Authenticating with the
database” on page 18.
6. To test the connection settings, click Test Connection.
7. Click Apply and Close.

4 Developer for z/OS: Developing with Db2, CICS, and IMS

Navigating catalogs and queries
After you connect to a Db2 database system, you can expand the connection to browse its catalog and
query history. The Catalog folder also includes a wizard for generating table and view declarations for C,
COBOL, and PL/I programs. To learn more about navigating catalogs, see “Navigating catalogs” on page
23. To learn more about the Declaration Generator, see “Generating declarations” on page 31.

Developing with Db2 for z/OS 5

6 Developer for z/OS: Developing with Db2, CICS, and IMS
Running SQL
You can run SQL from the COBOL, PL/I, SQL, or z Systems LPEX Editor.
1. Open the editor on a file that contains SQL statements.
2. In a COBOL or PL/I file: Select the contents of an SQL statement, and then right-click and select Db2
for z/OS > Run Selected SQL (Ctrl+Alt+R or ⌥+⌘+R).
3. In an SQL file: You can run selected SQL or all SQL in the file:
• Select one or more SQL statements and right-click and select Db2 for z/OS > Run Selected SQL.
• Right-click in the editor and select Db2 for z/OS > Run All SQL.
Tip: For more information about preferences for SQL content, see Defining SQL content types. To set
options for the Run SQL commands, select the Run SQL Options menu item. The context-sensitive
helps describe the options available on the Run SQL Options page.
If any SQL statement takes parameters or contains host variables, a window prompting you to enter
the parameter or variable value opens. If the SQL statement has been run against the active database
recently, the window can be populated with recent values for the Data Type, Null, and Value fields. The
query results are displayed in the Execution Status window and the Remote System Details view. For
more information about viewing and editing table data in this view, see “Viewing and editing table data”
on page 27.

Creating and running SQL scripts

Db2 for z/OS Development tooling includes an SQL editor that you can use to create, edit, run and tune
SQL statements. The editor provides tools for editing, formatting, and real-time syntax checking. You can
run or tune all SQL statements in the editor or selected statements. You can use it not only to edit SQL
files, but also to quickly generate a temporary file for running SQL. For more information about using the
SQL editor, see “Creating and running SQL scripts” on page 33.
1. To open a file in the SQL editor, double-click a local or remote file with the .sql file extension.
2. To generate a temporary file:
a. Select a Db2 for z/OS connection.
b. Right-click and select New SQL Script.

Developing with Db2 for z/OS 7

 Creating, deploying, and calling stored procedures
To create, deploy, and call a stored procedure, you must be connected to a Db2 for z/OS location.
1. Create a file or partitioned data set member with the extension .spsql.
2. Open this file in the SQL editor and add the SQL code for the stored procedure.
Tip: Use the content assist templates createProcedureNative or createProcedureExternal
to create sample procedure content. For more information about templates, see “Defining SQL
templates” on page 51.
3. Right-click anywhere in the body of the stored procedure open in the SQL editor and select Db2 for
z/OS > Deploy Stored Procedure. The Deploy Stored Procedure wizard opens.
4. Specify deployment and routine options on the wizard pages, and then click Deploy. The results of
the deploy operation are shown in the Execution Status window, where you can see any warnings or
errors and link to more information about SQL codes and status.
5. To run a deployed stored procedure routine, right-click anywhere in the body of the stored procedure
and select Db2 for z/OS > Call Stored Procedure. If necessary, the Run Routine window opens
to prompt you for variable or parameter values. The results of the call operation are shown in the
Execution Status window, where you can see any warnings or errors and link to more information
about SQL codes and status.
For more information about these steps, see “Creating, deploying, and running stored procedures” on
page 35.

8 Developer for z/OS: Developing with Db2, CICS, and IMS

Debugging stored procedures
You can use the Debug As > Db2 for z/OS Routine menu action to debug a native SQL stored procedure.
For more information about the debugging process, see “Debugging stored procedures” on page 43.

Connect to an SQL Tuning Services server

To use the Visual Explain, Statistics Advisor, and Capture Query Environment tuning features of Db2 for
z/OS Development tooling, you must connect to an SQL Tuning Services server. Creating a connection is a
two-step process. Both steps are done in the Db2 for z/OS subsystem of a remote system connection.

Developing with Db2 for z/OS 9

 1. Connect to the SQL Tuning Services server:
a. In the Remote Systems view, expand a z/OS system connection, and then expand the Db2 for
z/OS subsystem.
b. Right-click SQL Tuning Services Servers and select New > SQL Tuning Services Server.
c. Log in to the remote system using your Db2 user ID and password.
d. Type the HTTP port range, and then click Test Connection. Developer for z/OS connects to the
tuning server.
2. Associate a database connection profile with a Db2 connection.
a. In the Db2 for z/OS subsystem, expand Db2 for z/OS Connections, right-click a database
connection, and select Properties.
b. From the list of properties pages, click Tuning.
c. From the Database connection profile list, choose a profile. You can also click New to create a
profile.
d. Click Apply and Close.
Tip: For more information about connecting with SSL/TSL, auto connect, and other connection options,
see “Connecting to Db2” on page 13. If you want to import database connection profiles from IBM Data
Studio or Eclipse Data tools, see “Importing connection profiles from IBM Data Studio or Eclipse Data
Tools” on page 20.
For more information about SQL Tuning Services, see these topics:
• Tuning SQL statements
• IBM SQL Tuning Services

Tuning SQL
After you connect to a Db2 SQL Tuning Services server, you can select and tune SQL statements from the
COBOL, PL/I, SQL, or z Systems LPEX Editor.
1. Open the editor on a file that contains SQL statements.

10 Developer for z/OS: Developing with Db2, CICS, and IMS

2. Select an SQL statement, and then right-click and select Db2 for z/OS > Tune Selected SQL
(Ctrl+Alt+T or ⌥+⌘+T).
Tip: To set options for the Tune SQL commands select the Tune SQL Options menu item. The context-
sensitive helps contain descriptions of the options on the Tune SQL Options page.
3. On the Tuning Actions window, select one or more tuning actions, and then click OK.
The tuning data is displayed in the Remote System Details view.
4. To see the output of each tuning action, select it and click Open Results.
For more information about the tuning actions, see these topics:
• Visual Explain
• Statistics Advisor
• Capture Query Environment

Setting trace options for a Db2 for z/OS connection

Db2 for z/OS Development tooling gathers trace data for each connection, and you can set different trace
options for each connection. To set trace options for a Db2 connection, use the connection Properties
window:
1. Right click a Db2 connection and click Properties.
2. Select Tracing.

Limitations and troubleshooting

• When connecting to Db2 over SSL, you might receive a NoSuchAlgorithmException that prevents
the connection from succeeding. This situation is caused by an incompatibility between IBM JDK 11 and
Db2 JDBC driver version v4.29.24. To work around this incompatibility, do one of these options:
– Configure Db2 for z/OS Development to use a later version of the JDBC driver. To obtain a JDBC
driver, go to DB2® JDBC Driver Versions and Downloads for Db2 z/OS. For more information about
installing a JDBC driver into Developer for z/OS, see “Configuring Db2 for z/OS tooling” on page 51.
– Add the JDBC property sslVersion with the value TLSv1.2 to the Optional page of the connection
Properties window:

Developing with Db2 for z/OS 11

What's new
17.0.0
• Deployment of external SQL stored procedures.
• Debugging native and external SQL stored procedures.
• Filtering catalog navigation results by any column type.
• Importing connection profiles from IBM Data Studio.
• Generating declarations (DCLGEN).
• A toolbar for common Db2 for z/OS actions.
• Autofill of prior parameter values when re-executing a query.
• Large object support.
• Consistent feedback from query execution when no rows are returned.
• Viewing multiple result sets returned from a query.

Prior versions
For a list of what's new in product versions prior to version 17.0.0, see Db2 for z/OS Development 16.0.x
change history.

Db2 licensing
Obtaining and configuring a Db2 license
Db2 for z/OS Development tooling uses the IBM Data Server Driver for JDBC and SQLJ (sometimes
referred to as the JDBC driver) to manage connectivity between the Eclipse Java™ platform and the Db2
for z/OS subsystem.
This driver requires a Db2 Connect license to be purchased and either activated on the Db2 for z/OS
server, or imported into the IBM Developer for z/OS client.

12 Developer for z/OS: Developing with Db2, CICS, and IMS

 A Db2 administrator must obtain the Db2 license and either activate it on the host or distribute it to IBM
Developer for z/OS client users before they can connect to a Db2 system.
The Db2 license is available with either of these products:
• IBM Db2 Connect Unlimited Edition for System z (server-side license). See Activating the license
certificate file for Db2 Connect Unlimited Edition for information about obtaining and activating this
license.
• Db2 Connect Enterprise Edition (client-side license). Use the Download License link on this page to
download the license file, and then make this file available to client users. For more information about
importing this license into the Eclipse client, see “Importing a license file” on page 13.

Importing a license file

Db2 for z/OS Development tooling uses the IBM Data Server Driver for JDBC and SQLJ (sometimes
referred to as the JDBC driver) to manage connectivity between the Eclipse Java platform and the Db2 for
z/OS subsystem.
This driver requires a license to be either activated on the Db2 for z/OS server, or imported into the IBM
Developer for z/OS client. Your DB2 administrator can tell you if importing a client license file is necessary.
If you attempt to connect to Db2 and a license file is required, the product prompts you to import it.
1. Obtain the IBM Data Server Driver for JDBC and SQLJ client license file from your Db2 administrator or
the person who manages product licensing at your site.
2. In the Remote Systems view, expand a z/OS system connection, and then expand the Db2 for z/OS
subsystem.
3. Expand Db2 for z/OS Connections.
4. Right-click the Db2 connection and click Import Db2 for z/OS License.
5. In the file system navigation window, navigate to the location of the db2jcc_license_cisuz.jar
file and click Open.
6. Restart the product when prompted.
For more information about the JDBC client license file, see Installing, updating, or upgrading the IBM
Data Server Driver for JDBC and SQLJ on Db2 on Linux, UNIX, and Windows systems.
For information about activating the JDBC license file on the Db2 for z/OS server, see V12R1Mnnn
application compatibility levels for data server clients and drivers.

Database connections
Connecting to Db2
You can connect to a Db2 for z/OS location and to a Db2 Tuning Services server from the Remote Systems
view.

Before you start

1. Verify that the version of Db2 for z/OS that you want to connect to is supported. See the IBM Software
product compatibility reports. The catalog navigation function requires a connection to Db2 for z/OS
version 12.1.1 or later.
2. Obtain the following information from your Db2 administrator:
• The host name of the z/OS system where Db2 for z/OS is installed.
• The location name and port of the Db2 for z/OS system.
• To use the catalog navigation function your database logon ID must have read access to several Db2
system catalog tables. For more information about accessing system catalog tables, see Enabling
catalog navigation.

Developing with Db2 for z/OS 13

 • Optional: The port for the SQL Tuning Services server. This server processes the Visual Explain,
Statistics Advisor, and Capture Query Environment tuning features of Db2 for z/OS Development
tooling.
3. If required by your site, obtain a license file for IBM Data Server Driver for JDBC and SQLJ, and import
it into Developer for z/OS. If the license is activated on the Db2 for z/OS system you are connecting to,
then you do not need to do this step. Your Db2 administrator can tell you if this step is necessary. For
help with this step, see Importing a license file.
For more information about the JDBC client license file, see Installing, updating, or upgrading the IBM
Data Server Driver for JDBC and SQLJ on Db2 on Linux, UNIX, and Windows systems.
For information about activating the JDBC license file on the Db2 for z/OS server, see V12R1Mnnn
application compatibility levels for data server clients and drivers.
Tip: If you attempt to connect to Db2 and a license file is required, the product prompts you to import
it.
4. Create a connection to the remote system where Db2 for z/OS is installed.
For instructions, see Creating a connection to a z/OS system or watch this demonstration.

Connect to a Db2 location

1. In the Remote Systems view, expand a z/OS system connection, and then expand the Db2 for z/OS
subsystem.
2. Right-click Db2 for z/OS Connections and select New > Db2 for z/OS Connection.
3. Log in to the z/OS system using your Db2 user ID and password.
4. In the Connection information area of the General page of the connection properties window, type
the Location name and Port.
5. In the Authentication information area, choose a login method and enter your authentication
information. For more information about the supported login methods, see “Authenticating with the
database” on page 18.
6. To test the connection settings, click Test Connection.
7. Click Apply and Close.

14 Developer for z/OS: Developing with Db2, CICS, and IMS

Tip:
• For information about connecting to a database server with SSL/TSL, see Connecting with SSL/TLS.
• If you attempt to connect to Db2 and a license file is required, the product prompts you to import it.
• To automatically connect when the product starts, open the Preferences window and select Remote
Systems. Then, select the Automatically connect on startup checkbox and click Apply and Close. This
preference takes effect after you restart the workspace.
• To connect one or more database connections, right-click the Db2 for z/OS subsystem of the remote
system connection, and click Connect All. The client attempts to connect to all defined database
connections. If any connection errors occur, the database connections that have errors are flagged with
. To open the error message, right-click the flagged connection and click Show Connection Error.
• If the connection to a database is dropped, the client attempts to automatically reconnect.
• The client uses the Connection keep alive setting in the Db2 for z/OS Preferences page to periodically
poll the active connections to maintain connectivity. If one or more connections begins to fail, it opens a
message window to display the connection errors.

Connect with SSL/TLS

To connect to a Db2 location, you must obtain the number for the secure port from your network
administrator. You must also follow all other instructions in “Before you start” on page 13. For more
information about securing database connections with SSL, see Configuring connections under the IBM
Data Server Driver for JDBC and SQLJ to use SSL.
To connect to a Db2 location over a port secured by SSL/TLS, open the Properties window for the
database connection and specify these options:
Port
In the Port field on the General page, specify a secure port number.
JDBC properties
On the Optional page, specify the JDBC properties for a secure connection. You must define these
properties. Check with your network administrator to know if additional properties are required.

Developing with Db2 for z/OS 15

 Table 1. JDBC properties for a secure database connection
Authentication type Property Value
All sslConnection=true true
Server certificate authentication One of these sets of properties to specify the Db2 server
certificate location:
sslCertLocation
sslTrustStoreLocation and
sslTrustStorePassword
sslTrustStoreLocation,
sslTrustStorePassword
(optional), and
sslTrustStoreType
Client certificate authentication If you’re using the Java KeyStore to store the client certificate, add
these properties:
securityMechanism 18
One of these sets of properties to specify the client certificate
location:
sslKeyStoreLocation and
sslKeyStorePassword
sslKeyStoreLocation
and sslKeyStorePassword
(optional), and
sslKeyStoreType

The following example shows the properties for using the Java truststore and Java KeyStore.

16 Developer for z/OS: Developing with Db2, CICS, and IMS

Connect to an SQL Tuning Services server
To use the Visual Explain, Statistics Advisor, and Capture Query Environment tuning features of Db2 for
z/OS Development tooling, you must connect to an SQL Tuning Services server. Creating a connection is a
two-step process. Both steps are done in the Db2 for z/OS subsystem of a remote system connection.
1. Connect to the SQL Tuning Services server:
a. In the Remote Systems view, expand a z/OS system connection, and then expand the Db2 for
z/OS subsystem.
b. Right-click SQL Tuning Services Servers and select New > SQL Tuning Services Server.
c. Log in to the remote system using your Db2 user ID and password.
d. Type the HTTP port range, and then click Test Connection. Developer for z/OS connects to the
tuning server.
2. Associate a database connection profile with a Db2 connection.
a. In the Db2 for z/OS subsystem, expand Db2 for z/OS Connections, right-click a database
connection, and select Properties.
b. From the list of properties pages, click Tuning.
c. From the Database connection profile list, choose a profile. You can also click New to create a
profile.
d. Click Apply and Close.
Tip: For more information about connecting with SSL/TSL, auto connect, and other connection options,
see “Connecting to Db2” on page 13. If you want to import database connection profiles from IBM Data
Studio or Eclipse Data tools, see “Importing connection profiles from IBM Data Studio or Eclipse Data
Tools” on page 20.

Developing with Db2 for z/OS 17

 For more information about SQL Tuning Services, see these topics:
• Tuning SQL statements
• IBM SQL Tuning Services

When the client connects to a tuning services server, it obtains a session token for the user ID that is
connected. If the token becomes invalid or expires, the client attempts to refresh the session token and
resubmit any failed tuning operation.

Authenticating with the database

Db2 for z/OS Development supports several methods of authenticating with a database system. Learn
how to set up a login method and how various login methods work with other preferences and functions of
Db2 for z/OS Development.

Choosing a login method

Use the General page of the database connection properties window to choose a database login method.
1. In the Remote Systems view, expand a z/OS system connection, and then expand the Db2 for z/OS
subsystem.
2. Expand Db2 for z/OS Connections.
3. Right-click a connection name and select Properties.
4. In the navigation pane on the left, click General.
5. From the Login method list, choose one of these authentication methods:
• Password: Authenticate with the database server by using a RACF user ID and password. The
default user ID and password are the ones that you use to connect to the z/OS system. You can
select the Override checkboxes to specify a different user ID and password.
• PassTicket: Authenticate with the database server by using a RACF PassTicket. Enter your
PassTicket into the PassTicket field. The default user ID is the one that you use to connect to
the z/OS system. You can select the Override checkbox to override e user ID. Consult with your Db2
system programmer to determine if PassTickets are supported.

18 Developer for z/OS: Developing with Db2, CICS, and IMS

 • MFA Token: Use multifactor authentication to connect to the database server. When you select this
option, you log in to the database server with a user ID and password (or overrides), and also provide
an MFA token when you connect. MFA tokens are usually one-time use or have a short use time.
Therefore, you might need to enter a new MFA token for operations that require opening a dedicated
connection such as starting a debug session.

Password and PassTicket authentication considerations

When you authenticate with the database server by using a RACF user ID and password or PassTicket, you
can also use these features of Db2 for z/OS Development.
• Automatically connect on product startup. To automatically connect when the product starts, open the
Preferences window and select Remote Systems. Then, select the Automatically connect on startup
checkbox and click Apply and Close. This preference takes effect after you restart the workspace.
• If the connection to the database server is interrupted or altered, for example, by changing the Db2 for
z/OS Preferences, then Db2 for z/OS Development attempts to reconnect automatically.
• To connect one or more database connections, right-click the Db2 for z/OS subsystem of the remote
system connection, and click Connect All. The client attempts to connect to all defined database
connections. If any connection errors occur, the database connections that have errors are flagged with
. To open the error message, right-click the flagged connection and click Show Connection Error.
• The client uses the Connection keep alive setting in the Db2 for z/OS Preferences page to periodically
poll the active connections to maintain connectivity. If one or more connections begins to fail, it opens a
message window to display the connection errors.

MFA Token authentication considerations

MFA Tokens are single-use or short-term (one minute or less) authentication tokens that you enter in
conjunction with a user ID and password. When a database connection is configured for multifactor
authentication, it prompts you to enter an MFA token when you connect to the database or test a
database connection. MFA tokens are strings generated by an authenticator application, such as IBM
Verify, for identifying yourself to a system, such as a Db2 for z/OS database server.

Actions that consume MFA tokens

Several Db2 for z/OS Development operations might consume an MFA token and prompt you to enter
a token if multifactor authentication is configured.
• Test a database connection using the Test Connection button.
• Connect to a Db2 for z/OS database, either manually or automatically when a database action, such
as Run SQL, Deploy Stored Procedure, or navigating the Catalog, is started.
• Starting a debug stored procedure session.
• Running a tuning service job.
Known limitations
• Use of multifactor authentication with Tuning Services might not function correctly. If you
experience MFA tokens expiring while using Tuning Services, try using the Db2 for z/OS
MFA_AUTHCACHE_UNUSED_TIME configuration parameter to enable a longer token life. For more
information about this parameter, see MFA AUTH UNUSED TIME field.
• If MFA tokens are configured for a short expiration time, the database server established two
connections when initially connecting to the database and reserves the second connection for

Developing with Db2 for z/OS 19

 debug sessions to prevent having to enter a new MFA token. If the secondary connection fails to be
established, you might be prompted to enter a new MFA token each time you start a debug session.
• If, when prompted to ante an MFA token, you click Cancel, Db2 for z/OS Development attempts to
connect to the database with an empty token string.
• Auto connect is not supported for authentication by MFA token. Only manual or on-demand
connections are supported with multifactor authentication.

Importing connection profiles from IBM Data Studio or Eclipse Data Tools
If you defined Db2 for z/OS database connection profiles in either IBM Data Studio or Eclipse Data tools,
you can export them from an IBM Developer for z/OS version 15.0.x or earlier workspace, and then
import them into version 16.0.6 or version 17.0.0. The import wizard supports connection profiles that
are exported from the Data Source Explorer view of the Data perspective.
Restriction: The import wizard does not support connection profiles that are exported from these
locations:
• The Data > Data Descriptors option on the File > Export window.
• The Data Studio Enterprise Deployment > Configurations option on the File > Export window.
• The Export pop-up menu on the Data Project Explorer view.
• The Export toolbar button on the Server Profile Manager view.

Exporting connection profiles

1. In an IBM Developer for z/OS version 15.0.x or earlier workspace, open the Data Source Explorer view
of the Data perspective.
2. Click the Export toolbar button. The Export Connection Profiles window opens.

3. Select the Db2 for z/OS connection profiles you want to export.
4. To choose an export file location and specify an export file name, click Browse. The default folder is
the current workspace folder. The file type for export files is .xml. The following screen capture shows
an example of an export file location.

20 Developer for z/OS: Developing with Db2, CICS, and IMS

5. Select the checkbox to encrypt the export file content or to include the user ID and password to be
used for the connection in the export file.
6. Click OK. The file is saved to the location and file name you specify.

Importing connection profiles

1. In an IBM Developer for z/OS version 16.0.6 or 17.0.0 workspace, click File > Import, and then, in the
Import window, navigate to Db2 for z/OS > Database Connection Profiles and click Next.
2. Click Browse and navigate to the database connection profiles export file that you created in the IBM
Developer for z/OS version 15.0.x or earlier workspace.
3. Click Next. The wizard loads the exported connection profiles into a table. Each profile is highlighted in
the table, and the checkbox beside it is selected.
4. To import all selected profiles, click Next, or to import only specific profiles, clear some checkboxes
and then click Next. The Assign z/OS Connections page opens.
Tip: The Assign z/OS Connections page accommodates several scenarios for assigning z/OS
connections to profiles:
a. If you do not yet have a z/OS connection, or you want to create a new one to import a profile to,
click Create z/OS Connection.
b. If you already have z/OS connections that match the host names in the profiles, then you can click
Suggest z/OS Connection to assign profiles to connections.
c. If you want to import all profiles to the same z/OS connection, then you can select a connection
name from the drop-down list and click Set z/OS Connection.
d. If you need to import the profiles into different z/OS connections, then you can select profiles from
the table, assign connections to them, and then finish the import operation.
The remaining steps in this procedure provide specific instructions for each of these scenarios.
5. Scenario a: To create a z/OS connection before completing the import operation, do these steps:
a. Click Create z/OS Connection, and complete the Remote z/OS System Connection wizard.
For instructions, see Creating a connection to a z/OS system or watch this demonstration.

Developing with Db2 for z/OS 21

 b. Complete one of the next steps, according to the import scenario that is appropriate for your
profiles.
6. Scenario b: To assign the profiles to suggested z/OS connections and complete the import, do these
steps:
a. Click Suggest z/OS Connections, and verify that each profile is assigned to the appropriate z/OS
connection.
b. To complete the import operation, click Finish.
7. Scenario c: To import all profiles to the same z/OS connection, do these steps:
a. In the Set z/OS Connection area, select a connection name from the drop-down list.
b. Click Set z/OS Connection, and verify that each profile is assigned to the z/OS connection that you
selected.
c. To complete the import operation, click Finish.
8. Scenario d: To import the profiles into different z/OS connections, do these steps:
a. Highlight one or more profiles in the table.
b. To assign a z/OS connection to a highlighted profile, in the Set z/OS Connection area, select a
connection name from the drop-down list.
c. Click Set z/OS Connection, and verify that each profile is assigned to the z/OS connection that you
selected.
d. Repeat the highlighting and assigning steps until all profiles are assigned to a connection.
e. To complete the import operation, click Finish.
9. To verify that the profiles were imported into the correct connections, in the Remote Systems view,
expand a connection name, and then expand Db2 for z/OS > Db2 for z/OS Connections. Each
imported connection is given a unique name in the workspace by appending a _<number> as needed
to the connection name.

Demonstration
This animation demonstrates the export and import scenario in which existing z/OS connections
match the host names in the profiles, and the Suggest z/OS Connections function assigns profiles to
connections.

22 Developer for z/OS: Developing with Db2, CICS, and IMS

Associating a source file or script with a Db2 connection
You can associate any local or remote COBOL, PL/I, or SQL file with a Db2 for z/OS connection by using
the Db2 for z/OS > Associate Connection menu option.You can also use this menu option to change the
Db2 connection that is associated with a file or to create a Db2 connection for the file.
1. Open a file that contains SQL statements in the COBOL, PL/I, SQL, or z Systems LPEX Editor.
2. Right-click in the editor and select Associate Connection or use the toolbar menu to select a
connection:

3. To choose or set a different connection for the source file, select a connection from the list.
4. To add a new Db2 for z/OS connection:
a. Open the Db2 connection list.
b. Select Create a Db2 for z/OS connection. The new connection wizard opens.
c. From the Remote z/OS system list, select a z/OS system connection and click Next. The Db2 for
z/OS Connection Properties window opens. For more information about setting properties for a new
Db2 for z/OS connection, see the related information.
Tip: If the z/OS system where the database is located is not in the list, select Create z/OS
connection to add it. This action opens the New Connection wizard. For more information about
creating a connection to a z/OS system, see the related information.

Navigating catalogs
Expand the Catalog folder to browse the database objects for a Db2 for z/OS connection. The catalog
navigation function requires a connection to Db2 for z/OS version 12.1.1 or later.

Developing with Db2 for z/OS 23

 Enabling catalog navigation
To use the catalog navigation function your database logon ID must have read access to several Db2
system catalog tables. If you’re already working with another tool that provides you with access to the
Db2 catalog, it’s likely you already have these privileges. If not, then the database administrator can grant
you access by issuing the following statements. In these sample statements, replace {user ID} with the
logon ID that needs read access.

GRANT SELECT ON SYSIBM.SYSCHECKDEP TO {user ID};

GRANT SELECT ON SYSIBM.SYSCOLUMNS TO {user ID};
GRANT SELECT ON SYSIBM.SYSCONTROLS TO {user ID};
GRANT SELECT ON SYSIBM.SYSDATABASE TO {user ID};
GRANT SELECT ON SYSIBM.SYSDATATYPES TO {user ID};
GRANT SELECT ON SYSIBM.SYSDEPENDENCIES TO {user ID};
GRANT SELECT ON SYSIBM.SYSFOREIGNKEYS TO {user ID};
GRANT SELECT ON SYSIBM.SYSINDEXES TO {user ID};
GRANT SELECT ON SYSIBM.SYSJAROBJECTS TO {user ID};
GRANT SELECT ON SYSIBM.SYSKEYCOLUSE TO {user ID};
GRANT SELECT ON SYSIBM.SYSKEYS TO {user ID};
GRANT SELECT ON SYSIBM.SYSPACKAGE TO {user ID};
GRANT SELECT ON SYSIBM.SYSPACKDEP TO {user ID};
GRANT SELECT ON SYSIBM.SYSPACKLIST TO {user ID};
GRANT SELECT ON SYSIBM.SYSPACKSTMT TO {user ID};
GRANT SELECT ON SYSIBM.SYSPARMS TO {user ID};
GRANT SELECT ON SYSIBM.SYSPLAN TO {user ID};
GRANT SELECT ON SYSIBM.SYSROUTINES TO {user ID};
GRANT SELECT ON SYSIBM.SYSSEQUENCES TO {user ID};
GRANT SELECT ON SYSIBM.SYSSEQUENCESDEP TO {user ID};
GRANT SELECT ON SYSIBM.SYSSTOGROUP TO {user ID};
GRANT SELECT ON SYSIBM.SYSTABCONST TO {user ID};
GRANT SELECT ON SYSIBM.SYSTABLEPART TO {user ID};
GRANT SELECT ON SYSIBM.SYSTABLES TO {user ID};
GRANT SELECT ON SYSIBM.SYSTABLESPACE TO {user ID};
GRANT SELECT ON SYSIBM.SYSTRIGGERS TO {user ID};
GRANT SELECT ON SYSIBM.SYSVARIABLES TO {user ID};
GRANT SELECT ON SYSIBM.SYSVIEWDEP TO {user ID};

24 Developer for z/OS: Developing with Db2, CICS, and IMS

 GRANT SELECT ON SYSIBM.SYSVIEWS TO {user ID};
GRANT SELECT ON SYSIBM.SYSVOLUMES TO {user ID};

Exploring Db2 objects

In the Catalog folder you can:
• Browse Db2 objects such as databases, schemas, storage groups, tables, and more.
• Open these objects in the Remote System Details view and use the view's toolbar to sort, filter, and
navigate the objects.
• Display the properties of selected objects in the Properties view, and edit the Query Filter data.
• Add database objects to the Favorites folder.
• Open and edit table data in the Remote System Details view.

Filtering Db2 objects

You can filter the database objects that show in the Db2 for z/OS database connection Catalog folder.
1. Select the object folder you want to filter.
2. Right-click and select Properties. The Query Filter properties page opens. The fields that are
displayed in the Column filters area are specific to the object type. This screen capture shows the
properties for the Databases folder.

Developing with Db2 for z/OS 25

 3. Enter filtering criteria:
Column Filters: Select the column or columns that you want to filter on. For more information about
the catalog tables and their columns, see Db2 catalog tables.
a. Select a matching criterion. These criteria might be different for different columns. For example, the
matching criteria for the Name includes Starts with, Does not start with, Ends with, Does not end
with, Contains, Does not contain, Equal to, and Not equal to while the Type field includes only
Equal to and Not equal to.
b. Select or type a value or a pattern expression that you want to match. You can use % to match
multiple characters in the filter string or _ to match a single character. Use + as an escape character
to match the % or _ characters. Do not enclose the filter string in quotation marks.
The string you enter is used to generate a matching expression. The string must conform to
the criteria for LIKE or NOT LIKE predicates. For more information about constructing a pattern-
expression, see LIKE predicate.
Examples
• %SMITH% matches the values SMITH, NESMITH, SMITHSON, or NESMITHY. It does not match
the value SMYTHE.
• AB+_C_% matches the values AB_CD or AB_CDE. It does not match the values AB, AB_, or
AB_C.
c. Choose either Match All or Match Any to join the matching criteria with the AND or OR logical
operator.
Use the Max rows field to limit the number of matches that are returned.
Select Include implicit object to include implicitly created objects among the displayed children of
the filter. When this option is enabled, the filter name includes the label Include Implicit in the
Catalog list and Properties view. For more information about implicitly created database objects, see
Implicitly defined table spaces.
Tip: You can also edit the filters in the Properties view:
a. Select a filter in the Catalog folder.
b. In the Properties view, expand Query Filter, and then double-click the cell that contains the value
you want to edit.
4. Click Apply and Close. Folders that have filters applied to them are flagged with the filter string.

26 Developer for z/OS: Developing with Db2, CICS, and IMS

 Tip: You can also edit the filters in the Properties view:
1. Select a filter in the Catalog folder.
2. In the Properties view, expand Query Filter, and then double-click the cell that contains the value you
want to edit.

Opening SQL statements

Use the Open Statements in Editor menu action to open an SQL statement in the SQL editor. This menu
action is available on the following Db2 objects in the Catalog folder:
• The Packages > package_name > Statements folder, and individual statements in the Statements
folder.
• The Stored Procedures > procedure_name > DDL folder, and individual statements in the DDL folder.
• The Views > view_name > DDL folder, and individual statements in the DDL folder.
This screen capture shows the menu action on the Statements folder:

To open SQL statements from the Catalog folder:

1. Select one of the objects that supports the menu action.
2. Right-click and select Open Statements in Editor. The SQL editor opens with the content of the SQL
statements. You can use all of the editor's functions on the content. For more information about the
SQL editor, see “Creating and running SQL scripts” on page 33.
Related information
Db2 catalog

Viewing and editing table data

To view or edit table data in the Remote System Details view, use the View Data and Edit Data menu
actions.

Requirements for editing

A table must contain an index or unique constraint to be editable in the Remote System Details view. If
this requirement is not met, this error message is displayed:

Developing with Db2 for z/OS 27

 Opening table data
1. In the Remote Systems view, expand a z/OS connection name and then expand Db2 for z/OS > Db2
for z/OS Connections > databaseConnectionName > Catalog > Tables.

2. Right-click a table name and select View Data or Edit Data. The table data opens in the Remote
System Details view. The initial row limit is 500 rows. The column headers display the column name,
the data type, and the data length, if relevant.

Editing data
You can edit table data directly in the Remote System Details view, in the Properties view, or in a Table
Cell Editor.
Remote System Details view
• To edit a table cell, do one of these actions:

28 Developer for z/OS: Developing with Db2, CICS, and IMS

 – Click it and type a new value.
Tip: If a table cell contains a character large object (CLOB) or a large string value, the cell displays
an Edit Cell button. To view the cell data, click this button. The large object viewer opens with
the full text value. You can use the Export button to save the full value to a file.

– To locate the first editable cell in the table, place cursor focus in the Remote System Details view
and press Enter.
– To jump to the next editable cell, press the Tab key, or to jump to the previous editable cell, press
Shift+Tab.

• To cancel edits without saving the updates, press Esc.

• To save edits, press Enter.
Properties view
Select a row in the Remote System Details view, and then click a cell in the Value column. To view
CLOB or large text data, click the Edit Cell button.

Table Cell Editor

In both the Remote System Details view and the Properties view, a cell under edit displays an Edit
Cell button. To open the Table Cell Editor, click this button or press Shift+Enter.

Developing with Db2 for z/OS 29

 • To edit the cell value, select Set cell value to the following and type a new value in the text field.
You can also select a new data type from the Data Type list.
• To set the cell value to Null, click Set cell value to Null. If the column does not support null values,
this action is disabled.
• To return the cell to its original value, click Revert cell value to "value".

Other table actions

In the Remote System Details view, you can also undo and redo previous edits; copy, inset, and delete
rows, commit table updates, and change the number of rows that are displayed in the view. To complete
these actions, right-click a row in the view and select an action from the pop-up menu:

Show In > Remote Systems

Opens the table in the Remote Systems view.
Refresh
Reloads the table data into the Remote System Details view. Any uncommitted changes are
discarded, and the previous edit history is cleared.
Undo and Redo
Reverts and restores previous edits. The previous edits are available in the edit history even after you
commit changes. They are not available if you refresh the view or update the query filters.
Copy Row(s)
Copies selected row data to the clipboard.
Insert Row
Adds an empty row to the end of the table. If any columns have default values, the row is populated
with these values. The action is not saved until you select Commit Changes.
Limitation: You must edit at least one cell in the inserted row for the commit to succeed.

30 Developer for z/OS: Developing with Db2, CICS, and IMS

 Delete Row
Deletes the selected row. Rows marked for deletion cannot be edited. The delete action is not saved
until you select Commit Changes. If you delete an inserted row that is not yet committed, the row is
deleted immediately.
Commit Changes
Runs one or more SQL statements to commit the updates that you made to the table. If the updates
result in SQL errors, the Execution Status window opens so that you can review the errors. You must
resolve these errors before you can commit the changes. After the SQL statements run, the queries
are added to the Query History of the Db2 for z/OS connection location. The following image shows
both a successful and an unsuccessful commit in the Query History of a database location:

Update Query Filters

Opens the Properties window for the table so that you can change the maximum number of rows to
display. This actions reloads the table data and discards any uncommitted changes

Generating declarations
Use the Declarations Generator to generate language-specific DECLARE TABLE and DECLARE VIEW
statements for C, COBOL, and PL/I programs. This wizard calls the DCLGEN command to generate these
statements, generate corresponding host variable structures, and place these table and view declarations
into a member of a partitioned data set that you can include in a program.

Prerequisites
The DCLGEN command and the Declarations Generator require the following software levels and
components:
• Db2 13 for z/OS or Db2 12 for z/OS with APAR PH28863/PTF UI74277.
• Installation of Db2-supplied routines using DSNTIJRT.
• A WLM-established stored procedures address space and authorization for the ADMIN_COMMAND_DSN
stored procedure, as described in ADMIN_COMMAND_DSN stored procedure.

Launching and using the Declarations Generator

1. In the Catalog folder of a Db2 for z/O2 database connection, select a table or view.

Developing with Db2 for z/OS 31

 2. Right-click and select Generate Declarations (DCLGEN). The Declaration Generator opens.
3. Use the options page of the wizard to specify the output language for the declaration, the z/OS system,
partitioned data set, and member name for the generated file, and the data structure name and field
names prefix for the declaration.
Language: Choose the source programming language. The DCLGEN command supports C, C++,
COBOL, and PL/I.
Output System: Select a z/OS system. If you are not already connected to the chosen system, the
Connect button is activated so that you can connect.
Output data set: Specify a fully-qualified partitioned data set name to contain the generated include
file. You can either type a file name or click Select to search the z/OS system for a partitioned data set.
If you type a file name, the data set must already be allocated on the z/OS system.
Member: Specify a member name. The wizard can suggest a member name derived from the name of
the table or view.
Password: Enter a password for the file, if needed.
Data structure name: Specify a data structure name for the generated data declaration. The wizard
can suggest a name derived from the name of the table or view. The name can have up to 31
characters. If the data structure name is a single-byte or mixed string and the first character is not
alphabetic, it must be enclosed in apostrophes.
Field names prefix: The prefix can have up to 28 characters. If the prefix is a single-byte or mixed
string and the first character is not alphabetic, it must be enclosed in apostrophes.
For more information about the options you can specify on this page, see DCLGEN (declarations
generator) subcommand (DSN).
4. To specify additional options for the declaration, click Next.
5. Click Finish.
6. The wizard generates a DECLARE TABLE statement and data declaration and saves it in the specified
partitioned data set member.

32 Developer for z/OS: Developing with Db2, CICS, and IMS

Creating and running SQL scripts
Use the SQL editor to create scripts, run and tune SQL statements, and to save scripts to a local or remote
location.

Overview
The SQL editor is the default editor for files with the .sql or .spsql file extension. It provides these
functions:
• Run all SQL statements in the editor or selected statements.
• Tune an SQL statement that is selected in the editor.
• Format the content of the editor using formatting options that are set in the Preferences.
• Associate the SQL file with a Db2 connection. For more information about this function, see “Associating
a source file or script with a Db2 connection” on page 23.
• Save the SQL script to a local or remote location by using the File > Save As menu option.

Getting started
1. Define and connect to a Db2 for z/OS system. For instructions, see “Connect to a Db2 location” on
page 4.
2. If you want to use the SQL tuning tools, connect to the SQL tuning Services server. For instructions, see
“Connect to an SQL Tuning Services server” on page 9.
3. Right-click the connection name and select New SQL Script. The SQL editor opens in the editor area.

Editing SQL
Use these tools for editing SQL:

• Toggle buttons in the tool bar control word wrapping, block selection, and whitespace
characters.
• To expand or collapse SQL statements, click and in the editor margin. To preview a collapsed
statement, hover over the Expand icon.
• To comment out the line that has cursor focus, right-click and select Source > Toggle Line Comment.
• To show information about syntax warnings, hover over the warning icon in the

margin:

Inserting code with content assistance

The SQL editor provides content assistance for built-in functions, built-in stored procedures, and
templates that are defined in the Db2 for z/OS > Db2 Templates Preference page.
1. Click the location where you want to insert the code block. If you know the first few letters of the code
block, you can type them.
2. Press Ctrl+Spacebar. The content assistance window opens with suggestions.
3. To see a preview of a function or template, click its name. A text box opens showing the content of the
template.
4. Double-click a function or template name to include it in the source file.

Developing with Db2 for z/OS 33

 Formatting SQL
The SQL editor includes a formatter that you can configure on the SQL Formatter Preferences page. It
formats the entire contents of the SQL editor with the indentation and statement spacing options you set
on the Preferences page.
1. To set SQL Formatter preferences, open the Preferences window and navigate to z/OS Solutions >
Db2 for z/OS > SQL Formatter.
You can set these options:
Indent using tabs instead of spaces: Select this option to indent SQL statement lines with a tab
character. Clearing this option enables the Indent width option.
Indent width: If you prefer to indent using spaces, specify the number of spaces to indent SQL
statement lines.
Lines between statements: Specify the number of blank lines to insert between SQL statements.
2. Right-click in the SQL editor and select Format SQL. You can also select this menu option from the
Db2 menu or press Ctrl+Shift+F (Windows) or +Shift+F (macOS).

Running SQL
You can run SQL from the COBOL, PL/I, SQL, or z Systems LPEX Editor.
1. Open the editor on a file that contains SQL statements.
2. In a COBOL or PL/I file: Select the contents of an SQL statement, and then right-click and select Db2
for z/OS > Run Selected SQL (Ctrl+Alt+R or ⌥+⌘+R).
3. In an SQL file: You can run selected SQL or all SQL in the file:
• Select one or more SQL statements and right-click and select Db2 for z/OS > Run Selected SQL.
• Right-click in the editor and select Db2 for z/OS > Run All SQL.
Tip: For more information about preferences for SQL content, see Defining SQL content types. To set
options for the Run SQL commands, select the Run SQL Options menu item. The context-sensitive
helps describe the options available on the Run SQL Options page.
If any SQL statement takes parameters or contains host variables, a window prompting you to enter
the parameter or variable value opens. If the SQL statement has been run against the active database
recently, the window can be populated with recent values for the Data Type, Null, and Value fields. The
query results are displayed in the Execution Status window and the Remote System Details view. For
more information about viewing and editing table data in this view, see “Viewing and editing table data”
on page 27.

34 Developer for z/OS: Developing with Db2, CICS, and IMS

 Tuning SQL
After you connect to a Db2 SQL Tuning Services server, you can select and tune SQL statements from the
COBOL, PL/I, SQL, or z Systems LPEX Editor.
1. Open the editor on a file that contains SQL statements.
2. Select an SQL statement, and then right-click and select Db2 for z/OS > Tune Selected SQL
(Ctrl+Alt+T or ⌥+⌘+T).
Tip: To set options for the Tune SQL commands select the Tune SQL Options menu item. The context-
sensitive helps contain descriptions of the options on the Tune SQL Options page.
3. On the Tuning Actions window, select one or more tuning actions, and then click OK.
The tuning data is displayed in the Remote System Details view.
4. To see the output of each tuning action, select it and click Open Results.
For more information about the tuning actions, see these topics:
• Visual Explain
• Statistics Advisor
• Capture Query Environment

Creating, deploying, and running stored procedures

The Db2 for z/OS Development SQL editor supports the creation, deployment, and running of native and
external SQL stored procedures and Java stored procedures.

Creating stored procedures

To get started with Db2 for z/OS Development stored procedure support, do these steps:
1. Create a file or a data set member with the file extension .spsql or .javaspsql, for a Java stored
procedure.
2. Enter the SQL statements for the stored procedure into this file. Make sure your stored procedure
meets these requirements:

Developing with Db2 for z/OS 35

 • For native SQL and Java stored procedures, the file must contain a single CREATE PROCEDURE
statement. If the file contains more than one, only the first CREATE PROCEDURE statement
is deployed. For more information about the CREATE PROCEDURE statement, see CREATE
PROCEDURE in the Db2 for z/OS documentation.
• For Java stored procedures, the .spsql or .javaspsql file contains the SQL statements that
define the creation of the Java stored procedure file. The source code of the Java stored procedure
is located in a .java file. The source may be dependent on one or more .jar files. If the
CREATE PROCECURE statement contains the LANGUAGE JAVA syntax, then the procedure is treated
like a Java stored procedure For more information about Db2 for z/OS support for Java stored
procedures, see Java stored procedures and user-defined functions. For tips on developing Java
stored procedures in IBM Developer for z/OS, see “Developing Java stored procedures” on page
42.
• For external SQL stored procedures, in which the procedure body is an external program that is
written in a programming language such as C, C++, COBOL, or Java, the stored procedure file must
contain either the keyword FENCED or the keyword EXTERNAL.
• The ALTER PROCEDURE statement is not supported.
3. If you want to begin with a sample stored procedure that you can modify, you can copy and paste an
example from “Sample stored procedures” on page 40.
4. You can also use these templates in the SQL Editor content assistant to generate stored procedure
content:
• createProcedureExternal: CREATE PROCEDURE (SQL - external) statement
• createProcedureNative: CREATE PROCEDURE (SQL - native) statement
• createProcedureJavaInOut: CREATE PROCEDURE (Java - IN/OUT parameters) statement
• createProcedureJavaResultSet: CREATE PROCEDURE (Java - return a result set) statement
For more information about Db2 for z/OS stored procedure support, see Implementing Db2 stored
procedures.

Deploying native SQL stored procedures

To deploy a native SQL stored procedure, do these steps:
1. Right-click anywhere in the body of a stored procedure open in the SQL editor and select Db2 for z/OS
> Deploy Stored Procedure. The Deploy Stored Procedure wizard opens.
2. Specify deployment and routine options on the wizard pages, and then click Deploy. For descriptions
of the options you can specify in this wizard, see the list at the end of this procedure.
3. The results of the deploy operation are shown in the Execution Status window, where you can see any
warnings or errors and link to more information about SQL codes and status.
Deployment options
Db2 Connection: Select a connection to a Db2 location to deploy the stored procedure to. The default
is the active connection for the .spsql file, if one is defined.
Target schema: Set the target schema for unqualified stored procedures. The wizard suggests an
initial value that is based on the associated Db2 connection. If you leave this field empty, the
JDBC property currentSchema is used. If the JDBC currentSchema property is not set, the JDBC
connection username is used. If the stored procedure content declares the target schema, it appears
in this field and cannot be changed.
Build owner: Specify the owner of the stored procedure. The wizard suggests an initial value
that is based on the associated Db2 connection. If you leave this field empty, the JDBC property
currentSQLID is used. If currentSQLID is not set, the JDBC connection username is used.
Default path: Specify one or more schemas for resolving an unqualified data type, function, or
procedure that is referenced by the procedure being deployed. Separate multiple schemas with
commas, for example, "ADMF002","ADMF003","ADMF004".

36 Developer for z/OS: Developing with Db2, CICS, and IMS

 Duplicate handling: Choose one of these options to specify how to handle a stored procedure that
already exists:
Alter duplicates: Modifies the CREATE PROCEDURE DDL to ALTER PROCEDURE. Exception: If
you’re using CREATE OR REPLACE PROCEDURE, which is available in Db2 12 function level 507
or later, this option does not result in any modifications. This option is available for native SQL
stored procedures only.
Drop duplicates: Calls DROP PROCEDURE before running the CREATE PROCEDURE DDL. By
default, Db2 activates the first version of a stored procedure.
Treat duplicate deployments as errors: Returns an error. If other versions of the procedure do not
already exist, the procedure is created.
Activate the deployed version: Select this check box to activate the procedure upon deployment.
By default, Db2 activates the first version of a stored procedure. This checkbox is enabled only if the
Duplicate handling option is set to Alter Duplicates. This option is available for native SQL stored
procedures only.
For more information about JDBC properties, see Common IBM Data Server Driver for JDBC and SQLJ
properties for Db2 and Db2 for z/OS servers.
Routine options
Enable debugging: Select this checkbox to specify whether this procedure is available to be
debugged.
Limitation: This checkbox is disabled for Java stored procedures. Debugging Java stored procedures
is not supported.
WLM environment: Specify which Workload Manager environment to use for debugging the
procedure. If the source file declares a WLM environment, it is used as the default and this field
is disabled. If you enable debugging but leave this field empty, the default WLM environment is used.
ASU time limit: Specify the number of CPU seconds permitted for each SQL statement. The default
value of 0 means no time limit. If the source file declares an ASU time limit, it is used as the default
and this field is disabled.
Tip: The WLM environment and ASU time limit fields can be populated with values specified in the
CREATE PROCEDURE statement.
Additional routine options: Specify any additional options that you want to include. Separate each
option with a semicolon. For example: QUALIFIER ADMF002; ISOLATION LEVEL RS.

Deploying external SQL stored procedures

To deploy an external SQL stored procedure, do these steps:
1. Right-click anywhere in the body of a stored procedure open in the SQL editor and select Db2 for z/OS
> Deploy Stored Procedure. The Deploy Stored Procedure wizard opens.
2. Specify deployment, routine, and external options on the wizard pages, and then click Deploy. For
descriptions of the options you can specify in this wizard, see the list at the end of this procedure.
3. The results of the deploy operation are shown in the Execution Status window, where you can see any
warnings or errors and link to more information about SQL codes and status.
Deployment options
Db2 Connection: Select a connection to a Db2 location to deploy the stored procedure to. The default
is the active connection for the .spsql file, if one is defined.
Target schema: Set the target schema for unqualified stored procedures. The wizard suggests an
initial value that is based on the associated Db2 connection. If you leave this field empty, the
JDBC property currentSchema is used. If the JDBC currentSchema property is not set, the JDBC
connection username is used. If the stored procedure content declares the target schema, it appears
in this field and cannot be changed.

Developing with Db2 for z/OS 37

 Build owner: Specify the owner of the stored procedure. The wizard suggests an initial value
that is based on the associated Db2 connection. If you leave this field empty, the JDBC property
currentSQLID is used. If currentSQLID is not set, the JDBC connection username is used.
Default path: Specify one or more schemas for resolving an unqualified data type, function, or
procedure that is referenced by the procedure being deployed. Separate multiple schemas with
commas, for example, "ADMF002","ADMF003","ADMF004".
Duplicate handling: Choose one of these options to specify how to handle a stored procedure that
already exists:
Drop duplicates: Calls DROP PROCEDURE before running the CREATE PROCEDURE DDL. By
default, Db2 activates the first version of a stored procedure.
Treat duplicate deployments as errors: Returns an error. If other versions of the procedure do not
already exist, the procedure is created.
For more information about JDBC properties, see Common IBM Data Server Driver for JDBC and SQLJ
properties for Db2 and Db2 for z/OS servers.
Routine options
Enable debugging: Select this checkbox to specify whether this procedure is available to be
debugged.
Limitation: This checkbox is disabled for Java stored procedures. Debugging Java stored procedures
is not supported.
WLM environment: Specify which Workload Manager environment to use for debugging the
procedure. If the source file declares a WLM environment, it is used as the default and this field
is disabled. If you enable debugging but leave this field empty, the default WLM environment is used.
ASU time limit: Specify the number of CPU seconds permitted for each SQL statement. The default
value of 0 means no time limit. If the source file declares an ASU time limit, it is used as the default
and this field is disabled.
Tip: The WLM environment and ASU time limit fields can be populated with values specified in the
CREATE PROCEDURE statement.
Additional routine options: Specify any additional options that you want to include. Separate each
option with a semicolon. For example: QUALIFIER ADMF002; ISOLATION LEVEL RS.
External options
Build utility: Identifies the Db2 SQL procedure processor, SYSPROC.DSNTPSMP, which is used to
create an external SQL stored procedure.
Precompile options: Specify options for precompiling the C language program that Db2 generates
for the external SQL procedure. Do not specify the HOST option. For a list of these options see SQL
processing options.
Compile options: Specify options for compiling the C language program that Db2 generates for the
external SQL procedure.
Prelink options: Specify options for prelinking the C language program that Db2 generates for the
external SQL procedure.
Link options: Specify options for linking the C language program that Db2 generates for the external
SQL procedure.
Bind optionsSpecify options for binding the external SQL procedure package. Do not specify the
MEMBER or LIBRARY option for the Db2 BIND PACKAGE command. For a list of these options, see
BIND and REBIND options.

Deploying Java stored procedures

To deploy a Java stored procedure, do these steps:

38 Developer for z/OS: Developing with Db2, CICS, and IMS

1. Right-click anywhere in the body of a stored procedure open in the SQL editor and select Db2 for z/OS
> Deploy Stored Procedure. The Deploy Stored Procedure wizard opens.
2. Specify deployment and routine options on the wizard pages, and then click Deploy. For descriptions
of the options you can specify in this wizard, see the list at the end of this procedure. If one or more of
the JAR dependencies defined on the Java Options page of the wizard already exist on the target Db2
for z/OS server, you are prompted to replace the existing JAR IDs.
3. The results of the deploy operation are shown in the Execution Status window, where you can see any
warnings or errors and link to more information about SQL codes and status.
Deployment options
Db2 Connection: Select a connection to a Db2 location to deploy the stored procedure to. The default
is the active connection for the .spsql file, if one is defined.
Target schema: Set the target schema for unqualified stored procedures. The wizard suggests an
initial value that is based on the associated Db2 connection. If you leave this field empty, the
JDBC property currentSchema is used. If the JDBC currentSchema property is not set, the JDBC
connection username is used. If the stored procedure content declares the target schema, it appears
in this field and cannot be changed.
Build owner: Specify the owner of the stored procedure. The wizard suggests an initial value
that is based on the associated Db2 connection. If you leave this field empty, the JDBC property
currentSQLID is used. If currentSQLID is not set, the JDBC connection username is used.
Default path: Specify one or more schemas for resolving an unqualified data type, function, or
procedure that is referenced by the procedure being deployed. Separate multiple schemas with
commas, for example, "ADMF002","ADMF003","ADMF004".
Duplicate handling: Choose one of these options to specify how to handle a stored procedure that
already exists:
Drop duplicates: Calls DROP PROCEDURE before running the CREATE PROCEDURE DDL. By
default, Db2 activates the first version of a stored procedure.
Treat duplicate deployments as errors: Returns an error. If other versions of the procedure do not
already exist, the procedure is created.
For more information about JDBC properties, see Common IBM Data Server Driver for JDBC and SQLJ
properties for Db2 and Db2 for z/OS servers.
Routine options
Enable debugging: Select this checkbox to specify whether this procedure is available to be
debugged.
Limitation: This checkbox is disabled for Java stored procedures. Debugging Java stored procedures
is not supported.
WLM environment: Specify which Workload Manager environment to use for debugging the
procedure. If the source file declares a WLM environment, it is used as the default and this field
is disabled. If you enable debugging but leave this field empty, the default WLM environment is used.
ASU time limit: Specify the number of CPU seconds permitted for each SQL statement. The default
value of 0 means no time limit. If the source file declares an ASU time limit, it is used as the default
and this field is disabled.
Tip: The WLM environment and ASU time limit fields can be populated with values specified in the
CREATE PROCEDURE statement.
Additional routine options: Specify any additional options that you want to include. Separate each
option with a semicolon. For example: QUALIFIER ADMF002; ISOLATION LEVEL RS.
Java options
Each time you run this wizard, the options specified on this page are saved. The page might contain
options from the previous Deploy Stored Procedure operation.

Developing with Db2 for z/OS 39

 Java file path: Specify the Java class file. It must have a public static void method, which works as
an entry point for the stored procedure. The class name, declared package, and method name should
match the external name defined in the CREATE PROCEDURE statement. If the Java class declares a
package path, its location must match the package path to compile properly.
Java archive dependencies: Use this table to add, edit, or remove any compilation and runtime
dependencies that are required by the Java class. Dependent JARs are defined to Db2 if you select
Upload; otherwise, dependent JARs are used only for compilation. Dependent JARs must be defined
in the Java path on the server unless they have already been defined to Db2 by other Java stored
procedures.
Requirement: If a dependent JAR file has its own dependent JAR files, save this JAR file and all its
dependent JAR files on the server and add them to your JAVA path on the server. When you deploy
this stored procedure, clear the Upload option for this JAR file and its dependent JAR files.
Compatible JRE version: Specify a JRE that is at the same level or lower than the JRE version that
is installed on the Db2 for z/OS server. If the specified JRE version is higher than the version on the
server, the stored procedure does not run.
Upload Java source to the database: Select this checkbox to include the associated Java source
file when you deploy the stored procedure. If you do not select this option, you can run the stored
procedure, but cannot view the source in the Catalog folder of the Db2 for z/OS connection in the
Remote Systems view.
Refresh Java WLM environment: Select this checkbox to ensure that the most current version of the
stored procedure is run.

Running stored procedures

Several methods for running stored procedures are available:
• Use the Run As > Db2 for z/OS Routine menu option in the SQL editor pop-up menu.
• Use the Db2 for z/OS > Call Stored Procedure menu option in the SQL editor pop-up menu.
• Use the Run toolbar button.
All methods look for an existing Db2 for z/OS run configuration that matches the file in context. If no
match exists the tooling creates a run configuration for the file in context and uses it. If necessary, the
Run Routine window opens to prompt you for variable or parameter values. If the SQL statement has
been run against the active database recently, the window can be populated with recent values for the
Data Type, Null, and Value fields. The results of the call operation are shown in the Execution Status
window, where you can see any warnings or errors and link to more information about SQL codes and
status. The CALL request is also added to the Query History folder of the Db2 for z/OS connection.

Sample stored procedures

Native SQL stored procedure

CREATE PROCEDURE TAN

(IN X DOUBLE,
OUT RESULT DOUBLE)
VERSION V1
ISOLATION LEVEL CS
LANGUAGE SQL
PACKAGE OWNER SYSADM
WLM ENVIRONMENT FOR DEBUG MODE WLMENV1
ALLOW DEBUG MODE
P1: BEGIN
SET RESULT = TAN(x);
END P1#

External SQL stored procedure

CREATE PROCEDURE TABLENAMES ()

40 Developer for z/OS: Developing with Db2, CICS, and IMS

 RESULT SETS 1
LANGUAGE SQL
FENCED
COLLID TEST
WLM ENVIRONMENT WLMENV1
RUN OPTIONS 'NOTEST(NONE,*,*,*)'
P1: BEGIN
DECLARE cursor1 CURSOR WITH RETURN FOR
SELECT NAME FROM SYSIBM.SYSTABLES;
OPEN cursor1;
END P1#

Java stored procedure

CREATE PROCEDURE USERIBM.JDBC_JSP()

LANGUAGE JAVA
EXTERNAL NAME 'USERIBM.JDBC_JSP:JdbcJavaSP.getEmp(java.sql.ResultSet[])'
PARAMETER STYLE JAVA
WLM ENVIRONMENT WLMJAVA
READS SQL DATA
DYNAMIC RESULT SETS 1

Creating a run configuration

1. To open the Run Configurations window, click Run > Run Configurations.
2. In the navigation list, right-click Db2 for z/OS Routine and select New Configuration. A new
configuration is added to the navigation list as a child of Db2 for z/OS Routine, and the new
configuration page opens in the Run Configurations editor pane.
3. On the new configuration page, click Browse, and then type a search string, such as *.spsql in the
text field. This string matches all stored procedures are defined in a local or remote z/OS project in the
z/OS Projects view.

4. Select a stored procedure from the list and click OK.

5. In the Name field on the new configuration page, type a name for the new configuration.

Developing with Db2 for z/OS 41

 6. To save the run configuration, click Apply.

Mapping remote files

IBM Developer for z/OS defines the SQL editor as the default editor for files with the extension .spsql.
Files or partitioned data sets that define stored procedures must have this file extension. The product
provides a z/OS data set mapping definition called **SPSQL, that maps members of partitioned data sets
with the SPSQL low-level qualifier to workstation files with the .spsql extension. This mapping ensures
that the default editor association is recognized for data set members. To ensure that the file mapping
functions correctly, verify that the **SPSQL z/OS file system mapping precedes the **SQL mapping
in the z/OS File System Mapping view. To change the order of the **SQL and **SPSQL mappings,
right-click the **SPSQL mapping and select Raise Priority.

Developing Java stored procedures

Use these practices for developing Java stored procedures in IBM Developer for z/OS.
• Create an Eclipse Java project to host your development source. Eclipse provides the Java perspective
for the development of Java projects.
1. To open this perspective, click Window > Perspective > Open Perspective, and then select Java
from the list of available perspectives.
2. In the Package Explorer, right-click and select New > Java Project.
For more information about developing Java projects, see the Java development user guide.
• The class name, declared package, and method name should match the external name defined in the
CREATE PROCEDURE statement.
• If the Java class declares a package path, its location must match the package path to compile
correctly.
• You can create a separate folder to host any JAR dependencies your procedure has.
• To configure the Java build path to include any JAR libraries that your Java stored procedures depend
on right-click the project and select Build Path > Configure Build Path.
• A Java stored procedure must have the public static void method, which functions as an entry
point for the stored procedure.
• You can create a separate folder to host the .sql, .spsql, or .javaspsql files that contain the
CREATE PROCEDURE statements used to deploy the Java stored procedure.

42 Developer for z/OS: Developing with Db2, CICS, and IMS

 • The following screen capture shows a sample Java project that contains two stored

procedures:
• Support for Java stored procedures in the SQL editor includes two templates:
createProcedureJavaInOut and createProcedureJavaResultSet. To see the SQL templates,
open the Preferences window, and navigate to z/OS Solutions > Db2 for z/OS > Db2 Templates.
• If you choose to reuse any IBM Data Studio Data Development projects that you might have in
a Developer for z/OS15.0.x workspace, you can import them into the Java Explorer view. Data
Development projects are Java projects.
• If you want to have the Db2 for z/OS Development tooling in the same perspective as your Java
projects, you can add the z/OS Projects view and the Remote Systems view to the Java perspective:
1. Open the Java perspective.
2. From the menu bar, select Window > Show View > Other.
3. In the Show View window, expand Remote Systems, and then select Remote Systems and click
Open.
4. From the menu bar, select Window > Show View > Other.
5. In the Show View window, expand z/Os Project Views, and then select z/Os Projects and click
Open.

Debugging stored procedures

Db2 for z/OS Development tooling provides support for debugging native and external SQL stored
procedures. Learn how to configure and run the debugger for an SQL stored procedure .spsql source
file.

Before you start

1. Verify that the port specified for the debugger session manager is correct. For more information about
this preference setting, see “Configuring Db2 for z/OS tooling” on page 51.
2. Connect to a Db2 for z/OS connection. For more information about creating and connecting to a Db2
for z/OS connection, see “Connecting to Db2” on page 13.
3. Associate the connection with the SQL stored procedure source file. For more information about
associating connections with files, see “Associating a source file or script with a Db2 connection” on
page 23.

Starting a debugging session

1. To start the debugger, do one of these steps:
• Open an .spsql file in the SQL editor, then right-click in the editor and select Debug As > Db2 for
z/OS Routine.

Developing with Db2 for z/OS 43

 • In the z/OS Projects view, right-click an .spsql file and select Debug As > Db2 for z/OS Routine
• In the z/OS Projects view, select an .spsql file, and then do one of these actions: press F11, select
Run > Debug from the main menu, or select from the toolbar.
All of these commands generate a default debug configuration. If you prefer to create a debug
configuration for Db2 for z/OS routines, select Debug As > Debug Configuration.
2. Enter any required input parameters, if prompted, and then click OK. If the SQL statement has been
run against the active database recently, the input parameters can be populated with recent values for
the Data Type, Null, and Value fields.
Results:
• The debugger session manager generates a debug configuration and opens the source code
for the active stack frame in a separate read-only editor, which is different from the one you
might be editing in. The reason for the separate editor is that the local source might contain
changes not present in the deployed source. The read-only editors close automatically when the
debugging session has ended.
• The debugger automatically stops at the first line of the routine.
• If the Debug Perspective is not already open, the workbench prompts you to open it. If you
choose not to open the Debug Perspective, then the Debug view is added to the current
perspective.
• While a debug session is active, the source file in the SQL editor is marked read-only so that you
cannot make changes to it.
• The debug session does not run if there are errors in the source file or if there is already a
stored procedure debug session open. You can run only one debug session at a time. For more
information about debug errors, see “Troubleshooting debugging sessions” on page 47.

Adding breakpoints and stepping through code

Use the debug editor and the Debug view to set breakpoints that determine where the debugger pauses
and to step through the stored procedure code. Breakpoints can only be added to the editors displaying
remote source files. These are initially available while in a debug session. You can view and modify
existing breakpoints in the Breakpoints view. Breakpoints in remote files persist across multiple debug
sessions. You can open the last retrieved remote source content by viewing the source of a breakpoint,
and add or remove breakpoints to that remote source copy outside of a debug session.
The Debug view displays a hierarchical view of the stored procedure as it executes. This hierarchical view
includes the debug target, process, thread, and one or more stack frames displaying the schema, name,
and version of the routines containing the execution source for that frame.
You can use the Breakpoints view to view or manage breakpoints. Clicking a breakpoint in this view
re-opens the read-only debugging source file. For more information about the Breakpoints view, see
Breakpoints View.

44 Developer for z/OS: Developing with Db2, CICS, and IMS

To add a breakpoint, double-click the marker bar at the line where you want to set a breakpoint. To
remove a breakpoint, double-click the marker. You can also use the pop-up menu on the marker bar to
enable and disable breakpoints.
When execution is suspended, you can use these commands in the Debug view:
Resume
Resumes execution until either the next breakpoint or the end of the stored procedure is reached.
Stop
Ends the debug session.
Step Into
Attempts to step into the subroutine at the current line as a new stack frame.
Step Over
Attempts to step to the next instruction of the current stack frame.
Step Return
Attempts to return execution to the parent stack frame.
As you step through the code, the debugger annotates the current instruction of the active top stack
frame and the current instruction in stacks other than the active top stack frame. If you want to customize
the appearance of these annotations, open the Preferences page and navigate to General > Editors
> Text Editors > Annotations. Scroll down to find Debug Call Stack and Debug Current Instruction
Pointer.

SQL query results

When the debugging session ends, the editors displaying the remote source files close, and the results
of the SQL call operation are shown in the Execution Status window, where you can see any warnings or
errors and link to more information about SQL codes and status. The CALL request is also added to the
Query History folder of the Db2 for z/OS connection.

Demonstration
The following animation shows the end-to-end debugging process.

Developing with Db2 for z/OS 45

 Editing variables during a debugging session
When you start a debugging session, you are given the option to open the Debug perspective. This
perspective includes a Variables view that you can use to edit variables as you step through code. The
Variables view lists the variables in scope at the selected stack frame and their values. You can also
display the declared SQL type of variables by selecting Layout > Select Columns from the view's overflow
menu, and then selecting Declared Type from the list.

There are two ways to edit a variable value:

• Click it in the Variables view and type a new value. To set the variable to null, type *NULL*.

46 Developer for z/OS: Developing with Db2, CICS, and IMS

 • Right-click a variable and select Change Value. The Set Variable Value window opens. Type a new
value in the text pane or click Set value to *NULL*.
Only variables at the top frame of the stack can be edited. You cannot edit the diagnostic variables.
Whenever you use the Resume, Step Over, Step Into, or Step Return actions to reach a breakpoint, any
variables that were modified between the resumption and the suspension are highlighted in the variables
view. Newly created variables are not highlighted. The SQL State and SQL Code diagnostic variables are
also highlighted when their values change.
For an overview of the other views in the Debug perspective, see Debugging your application.

Troubleshooting debugging sessions

The following situations can prevent the debugging session from starting:
• The source file is empty or does not contain a CREATE PROCEDURE statement.
• The source that is open in the SQL editor does not resolve to a file in the workspace.
• The content contains syntax errors.
• The source file does not contain SQL. The debugger supports only native SQL stored procedures.
• A debug session is already open.
The following situations can result in warnings, but do not prevent the debugger from starting:
• The source file contains multiple stored procedures. In this case, the debug operation is run on only the
first stored procedure.
• The source file contains other types of SQL statements besides the CREATE PROCEDURE statement. In
this case, the debug operation is run on only the first stored procedure.
Related information
Using the SQL editor
Use the SQL editor to create scripts, run and tune SQL statements, and to save scripts to a local or remote
location.

Tuning SQL statements

Use the Db2 for z/OS > Tune Selected SQL pop-up menu action to open the Tuning Actions window from
an editor.
From the Tuning Actions window, you can choose these actions:
• Visual Explain: Generates a graphical representation of a query path.
• Statistics Advisor: Generates RUNSTATS for a query.
• Capture Query Environment: Captures the runtime environment for a query.

Before you start

IBM Developer for z/OS uses the Db2 for z/OS SQL Tuning Services server to run the tuning actions.
Before you can use these actions, you must create a connection to the SQL Tuning Services server and
configure tuning options.
1. Gather the following information from a Db2 for z/OS administrator:
• The port to use to connect to the server.
• The name of a database connection profile that has EXPLAIN tables configured. During the following
procedure, you can also create a database connection profile and generate EXPLAIN tables for it.
2. To create a connection to the server:
a. In the Remote Systems view, expand a z/OS system connection, and then expand the Db2 for
z/OS subsystem.
b. Right-click SQL Tuning Services Servers and select New > SQL Tuning Services Server.

Developing with Db2 for z/OS 47

 c. Log in to the remote system using your Db2 user ID and password.
d. Type the HTTP port range, and then click Test Connection. Developer for z/OS connects to the
tuning server.
3. To configure tuning services:
a. In the Db2 for z/OS subsystem, expand Db2 for z/OS Connections, right-click a database
connection, and select Properties.
b. From the list of properties pages, click Tuning.
c. From the Database connection profile list, choose a profile. You can also click New to create a
profile.
d. Click Apply and Close.
To learn more about the SQL Tuning Services server, EXPLAIN tables, and database connection profiles,
see these topics:
• Getting started with SQL Tuning Services (links to the IBM Documentation for Db2 for z/OS)
• Investigating SQL performance by using EXPLAIN (links to the IBM Documentation for Db2 for z/OS)
• “Creating a database profile and EXPLAIN tables” on page 48

Tuning SQL
After you connect to a Db2 SQL Tuning Services server, you can select and tune SQL statements from the
COBOL, PL/I, SQL, or z Systems LPEX Editor.
1. Open the editor on a file that contains SQL statements.
2. Select an SQL statement, and then right-click and select Db2 for z/OS > Tune Selected SQL
(Ctrl+Alt+T or ⌥+⌘+T).
Tip: To set options for the Tune SQL commands select the Tune SQL Options menu item. The context-
sensitive helps contain descriptions of the options on the Tune SQL Options page.
3. On the Tuning Actions window, select one or more tuning actions, and then click OK.
The tuning data is displayed in the Remote System Details view.
4. To see the output of each tuning action, select it and click Open Results.
For more information about the tuning actions, see these topics:
• Visual Explain
• Statistics Advisor
• Capture Query Environment

Creating a database profile and EXPLAIN tables

The profile that you associate with a database connection determines the EXPLAIN tables that are
available for tuning SQL queries. For more information about database connection profiles and EXPLAIN
tables, see the related information.

Creating a database connection profile

1. In the Remote Systems view, expand the Db2 for z/OS subsystem.
2. Expand SQL Tuning Services Servers and the server where you want to create a database connection
profile.
3. Right-click Database Connection Profiles and click New > Database Connection Profile. The Create
Database Connection Profile wizard opens.
4. In the Profile name field, type a name for the new database connection profile.
5. Click Next.

48 Developer for z/OS: Developing with Db2, CICS, and IMS

 6. On the Advanced Settings page, you can specify SSL security settings.
7. Click Finish.

Generating EXPLAIN tables for a profile

You must log on to the database with a user ID that is authorized to create EXPLAIN tables. Contact your
Db2 for z/OS administrator for assistance.
1. In the Remote Systems view, expand Db2 for z/OS > SQL Tuning Services Servers, and navigate to a
server where your database connection profile is defined.
2. Right-click the profile and click Create EXPLAIN Tables. The Create EXPLAIN tables wizard opens.
3. Enter values for the EXPLAIN table options and click Next to advance through the wizard pages.
Use this wizard to specify options for an EXPLAIN table. All of the options in this wizard are optional. If
you do not specify any values in this wizard, then the EXPLAIN table is created with default values or
with values inherited from the equivalent database connection options.
For information about EXPLAIN tables, see the related information. "EXPLAIN table options" links to
information about the fields in this wizard.
4. To create the tables, click Finish.
You can also do these tasks with database connection profiles:
• Update the profile to change the name or associate it with a different database connection.
• Share and revoke access to a profile that you created.
• Upgrade all existing EXPLAIN tables to the format for the current Db2 version, and create any missing
tables.
• Drop all existing EXPLAIN tables.
Related information
Investigating SQL performance by using EXPLAIN
Creating EXPLAIN tables
EXPLAIN tables
EXPLAIN table options

Generating a visual representation of a query path

Use the Visual Explain tool to generate a visual representation of a query path.
1. Open the editor on a program file that contains EXEC SQL statements.
2. Select the contents of the EXEC SQL statement, and then right-click and select Db2 for z/OS > Tune
Selected SQL.
Tip: In the z Systems LPEX Editor, use the Db2 menu on the product menu bar.
3. On the Tuning Actions window, select Visual Explain, and then click OK.
The tuning data is displayed in the Remote System Details view.
4. To see the output of the action, select it and click Open Results. The graphical representation of the
query path opens in a browser. From the Visual Explain Viewer, you can open detailed information
about the query and the query environment, search the nodes in the results to display details, and
save the graphical representation as a portable network graphic file.

Developing with Db2 for z/OS 49

Generating RUNSTATS for a query
Use the Statistics Advisor tool to generate RUNSTATS for a query.
1. Open the editor on a program file that contains EXEC SQL statements.
2. Select the contents of the EXEC SQL statement, and then right-click and select Db2 for z/OS > Tune
Selected SQL.
Tip: In the z Systems LPEX Editor, use the Db2 menu on the product menu bar.
3. On the Tuning Actions window, select Statistics Advisor, and then click OK.
The tuning data is displayed in the Remote System Details view.
4. To see the output of the action, select it and click Open Results. The Statistics Advisor window opens
with recommended RUNSTATS commands and command results.
Related information
RUNSTATS commands

Capturing the query environment

Use the Capture Query Environment tool to capture diagnostic information for a query. This action is
helpful if you need to work with the IBM support team to resolve a problem with a query. The tool
generates a .zip file that contains query environment reports that you can open in a browser.
1. Open the editor on a program file that contains EXEC SQL statements.
2. Select the contents of the EXEC SQL statement, and then right-click and select Db2 for z/OS > Tune
Selected SQL.
Tip: In the z Systems LPEX Editor, use the Db2 menu on the product menu bar.
3. On the Tuning Actions window, select Capture Query Environment, and then click OK.
The tuning data is displayed in the Remote System Details view.
4. To see the output of the action, select it and click Open Results. The tool generates a .zip
file named with the job ID of the query for which the data was collected, for example,
1746152697765040128.zip. The Save Captured Query Environment window opens.

50 Developer for z/OS: Developing with Db2, CICS, and IMS

 5. Navigate to a location on your workstation to save the .zip.
6. To see the captured reports, extract the contents of the .zip file.

Configuring Db2 for z/OS tooling

To set general preferences for Db2 for z/OS Development, use the Db2 for z/OS Preferences page.
To open the Db2 for z/OS page of the Preferences window, navigate to z/OS Solutions > Db2 for z/OS.
You can set these preferences:
Log level: Sets the number and level of detail for messages that are written to the log file. The trace
logging option records the highest level of detail, while error records only error messages. To turn off
logging, select off. Messages are written to the metadata/.plugins/com.ibm.systemz.db2/logs
folder of the Eclipse workspace.
HTTP port range: The default port range is 3100-3110.
Character conversion: Select an option for how to handle characters that cannot be converted between
the client and server encodings. The default setting is to replace the character that cannot be converted
with the replacement character �, &#xfffd;. You can choose instead to issue an error message when a
character cannot be converted.
Max heap size (MB): The maximum size megabytes to use for the launched JVM that hosts the Db2 SQL
service. The default is 256.
Connection keep alive: Specify a lower number to send dummy queries more frequently.
Db2 JDBC driver: Displays the installed location of the Db2 JDBC driver. If you have or want to use a
different or more recent JDBC driver, you can enter the location in this field or click Browse to navigate to
the location.
Db2 JDBC driver license: Displays the installed location of the Db2 for z/OS client license. If you have or
want to use a different or more recent JDBC driver license file, you can enter the location in this field or
click Browse to navigate to the location. To import the db2jcc_license_cisuz.jar client license file,
click Import License.
Attention: If you click Restore Defaults on this page, custom driver or license locations are
cleared from these fields.
Debugger session manager port: Specify the port for the debugger session manager. You can specify
multiple values or a range of values, for example, 4555, 4556, 4559-4985. If you specify multiple
ports, the first available port is used. The default value is 4655-4665.
Service status: Displays the current status of the Db2 SQL service.
The Max number of rows returned and Max number of syntax errors fields set maximums for each
query you issue by using the Db2 for z/OS > Run Selected SQL editor command.

Defining SQL templates

Db2 for z/OS Development tooling provides a set of SQL templates that you can add to scripts or stored
procedures by using content assistance. You can also edit these templates or define more SQL templates
in the Preferences window.
To see the SQL templates, open the Preferences window, and navigate to z/OS Solutions > Db2 for z/OS
> Db2 Templates.
Use this page to add, edit, or remove SQL templates from Db2 for z/OS Development tooling content
assistance. The templates in this list are included in the bottom half of the content assistance window,
below the built-in functions and built-in stored procedures. This page includes SQL templates that are
shipped with the product, but you can also create your own templates or remove templates that you
do not need so that they do not appear in the content assistance window. Removed templates are not
deleted; rather they are excluded from the content assistance window. When you select a template in the
list its content is displayed in the Preview field.

Developing with Db2 for z/OS 51

 This information is available for each template:
Name: How the template is identified in the content assistance window.
Context: Identifies the editor where the template is available. Db2 templates are available in the SQL
editor.
Description: Text that is displayed beside the template name in the content assistance window.
Auto Insert: When this field displays on, the template is automatically inserted into a new source file.
Use the buttons beside the template list to do these actions:
New: Add a template.
Edit: Modify a selected template.
Remove: Remove the selected templates.
Restore Removed: Add the last template that was removed back to the list.
Revert to Default: Restore the list of templates to the default list.
Import: Import a template from an XML file.
Export: Export a selected template to an XML file.

Defining SQL content types

Use the Content Types preference page to define file extensions and editors for SQL files.
The Db2 for z/OS Development tooling Db2 for z/OS SQL content types define the following default file
name extensions for SQL files and associates them with editors:

Content Type File Name Extensions Associated Editors

Db2 for z/OS SQL *.ddl, *.sql Db2 for z/OS SQL Editor
Text Editor
Generic Text Editor

Db2 for z/OS SQL Stored *.spsql, *.javaspsql Db2 for z/OS SQL Editor
Procedure
Text Editor
Generic Text Editor

Db2 for z/OS SQL User-Defined *.udfsql Db2 for z/OS SQL Editor
Function
Text Editor
Generic Text Editor

To add more file name extensions or additional editors to these content types, do these steps:
1. In the Preferences window, navigate to General > Content Types.
2. In the Content types list, expand Text and select Db2 for z/OS SQL or one of the subtypes.
3. To add more file name extensions or editors to the File associations or Associated editors lists, click
Add.
Notice: The default file name extensions are locked, as indicated by the Lock icon. You cannot edit
or remove these file name extensions, but you can add new ones to the list.
Related information
Preferences
Content Types

52 Developer for z/OS: Developing with Db2, CICS, and IMS

Exporting Db2 for z/OS preferences
You can use the Preferences window to export the Db2 for z/OS Development preference settings and
share the exported file with specific users or import them into another workspace. The instructions for
sharing preferences with specific users are included in this topic. You can also export them to the host
for distribution to other users by the push-to-client feature. For more information about setting up and
using the push-to-client feature, see Planning a push-to-client environment. In the push-to-client export
wizard, the Db2 for z/OS preferences are on the Global configuration page. For more information about
using the push-to-client export wizard, see Exporting push-to-client configuration files.

Exporting preferences
To export Db2 for z/OS Development preference settings:

1. In the Preferences window, click the icon.

2. On the Export Preferences window, select Db2 for z/OS Preferences. Unless you want to export all
workbench preferences, be sure to clear the Export all checkbox.

3. Click Browse, navigate to the location where you want to save the export file, type a name for the file,
for example, db24zos, and click Save.
4. After you verify that the other settings on this window are correct, for example, the preference
selections and the overwrite option, click Finish. The export file is saved to the location you selected.
It includes the content of these preference pages:
• Db2 for z/OS
• SQL Formatter
• EXEC SQL statements

Importing preferences
To import Db2 for z/OS Development preferences:
1. In the Preferences window, click the icon.
2. On the Import Preferences window, click Browse and select the export file.

Developing with Db2 for z/OS 53

 3. After you verify that the other settings on this window are correct, click Finish. The export file is loaded
into the workspace, and you are prompted to restart the workbench.

54 Developer for z/OS: Developing with Db2, CICS, and IMS

Developing CICS applications
Learn how to develop CICS® applications by using the product.
Related information
Software Product Compatibility Reports

Adding CICS translation support to COBOL and PL/I applications

You can embed EXEC CICS statements into COBOL or PL/I code if you have a CICS translator available. If
your workbench is properly configured, these EXEC CICS statements are automatically expanded during
syntax checks and compilations by your CICS translator.
Related reference
Integrated and separate CICS and Db2 steps

Setting the CICS level for COBOL and PL/I programs

You can set the level of CICS in use at your installation to aid more accurate content assistance and
syntax checking.
When you set the level of CICS in use at your installation, you can take advantage of release-specific
content assistance and syntax checking for your COBOL and PL/I programs. The Developer for z/OS
product uses the CICS level that you specify to do the following operations:
• Set compiler options specific to the release of CICS in use at your installation. These options are used
for local syntax checking. This action is available only on Windows.
Limitations:
– Local syntax check is deprecated. This action is available only on Windows.
– Local syntax checking does not support shift-out-shift-in (SOSI) sources. The importer that is used to
do the local syntax check supports only UTF-8 encoding. Translating CP-930 and other SOSI sources
into UTF-8 alters the column locations for some characters, and this alteration results in unexpected
errors.
• Provide release-specific content assistance in the z Systems LPEX Editor.
To set the level of CICS in use at your installation:
1. Open COBOL Settings properties or PL/I Settings properties page.
2. Click Use CICS.
3. From the list, select the level of CICS.
Related reference
“Default CICS preprocessor options” on page 57
The default preprocessor options are based on the CICS product that is installed on the workstation.
“CICS preprocessor options for syntax checks” on page 55
The Developer for z/OS product sets CICS preprocessor options appropriate to the level of CICS installed
on the workstation or remote system. You can follow several scenarios for local and remote syntax
checking of CICS programs and how the product handles each.

CICS preprocessor options for syntax checks

The Developer for z/OS product sets CICS preprocessor options appropriate to the level of CICS installed
on the workstation or remote system. You can follow several scenarios for local and remote syntax
checking of CICS programs and how the product handles each.
Limitations:
• Local syntax check is deprecated. This action is available only on Windows.

© Copyright IBM Corp. 1992, 2024 55

 • Local syntax checking does not support shift-out-shift-in (SOSI) sources. The importer that is used to do
the local syntax check supports only UTF-8 encoding. Translating CP-930 and other SOSI sources into
UTF-8 alters the column locations for some characters, and this alteration results in unexpected errors.

Local syntax check of a remote CICS program

The following scenarios illustrate how the Developer for z/OS product sets compiler options for a local
syntax check of a remote CICS program:
• On the Runtime Environments page for a remote file, you select CICS (contains EXEC CICS
statements) and specify a level of CICS from the list. The Developer for z/OS product sets compiler
options for the local syntax check according to the remote compiler options specified:
– Ensures CICS TXSeries® 6.1 or higher is installed.
– Changes the compiler options to include CICS('CTSxx'),NOCOMPILE, where xx is the level of CICS
selected from the list.
Note: For PL/I, the compiler option is pp(CICS('CTSxx').
– Ignores Preprocessor options.
– Performs a syntax check with the CICS('CTSxx') or pp(CICS('CTSxx') compiler option, causing the
integrated CICS translator with the specified syntax to be started.
• On the Local Compile Options page for a remote file, you specify the CICS('CTSxx') (for COBOL) or
pp(CICS('CTSxx') (for PL/I) option, where xx is the level of CICS. The Developer for z/OS product uses
the option that is specified for local syntax check using host CICS syntax and does the following
operations:
– Ensures that TXSeries is installed.
– When the CICS compiler option is specified, the Preprocessor options are ignored on a syntax check.
– Performs a syntax check with the CICS('CTSxx') (for COBOL) or pp(CICS('CTSxx') (for PL/I) compiler
option, causing the integrated CICS translator with the specified syntax to be started.

Local syntax check of a local CICS program

The following scenarios illustrate how the Developer for z/OS product sets compiler options for a local
syntax check of a local CICS program:
• On the Local Compile Options page for a local file, you specify that an integrated CICS syntax check
must take place. The Developer for z/OS product sets compiler options for the local syntax check as
follows, ensuring that the integrated preprocessor is used:
– Ensures CICS TXSeries 6.1 or higher is installed.
– Changes the compiler options to include CICS.
– Preprocessor options are ignored on the syntax check.
– Performs the syntax check using the integrated CICS translator.
• On the Local Compile Options page for a local file, you specify the CICS('CTSxx') (for COBOL) or
pp(CICS('CTSxx') (for PL/I) option, where xx is the level of CICS. The Developer for z/OS product sets
compiler options for the local syntax check as follows, ensuring that the integrated preprocessor is used
with the level of CICS Transaction Server syntax specified:
– Ensures that TXSeries 6.1 or higher is installed.
– Ignores Preprocessor options.
– Performs the syntax check using the integrated CICS translator.
• On the Local Compile Options page for a local file, you specify the -p preprocessor option that indicates
use of CICSTCL (CICS Translate Compile Link) with the integrated translator. The Developer for z/OS
product uses the option that is specified for local syntax check with the integrated translator and does
the following operations:
– Ensures that TXSeries 6.1 or higher is installed.

56 Developer for z/OS: Developing with Db2, CICS, and IMS

 – Ignores Preprocessor options.
– Adds the CICS compiler option for syntax check.
– Performs a syntax check with the CICS compiler option, causing the integrated CICS translator to be
started.

Local build of a local CICS program

The following scenarios illustrate how the Developer for z/OS product sets compiler options for a local
build of a local CICS program (building a DLL to run in a region):
• On the Local Compile Options page for a local file, you specify the -p preprocessor option, indicating
use of CICSTCL (CICS Translate Compile Link) with the integrated translator. The Developer for z/OS
product uses the option that is specified for the local build with the integrated translator and runs two
compilation passes as follows:
– Ensures that TXSeries 6.1 or higher is installed.
– On the compilation pass, the Developer for z/OS product:
- Changes options that are fed to the compiler to include CICS.
- Ensures that the integrated translator is called and ignores the Preprocessor field.
- Performs the compilation as though it was a regular (not CICS) compilation.
– On the CICSTCL pass, the Developer for z/OS product:
- Performs the CICSTCL pass with the -p and other options that are specified in the Preprocessor
field.
• On the Local Compile Options page for a local file, you specify the CICS compiler option for completing
a compilation with an integrated CICS translator. The Developer for z/OS product uses the option that is
specified for the local build with the integrated translator and runs two compilation passes as follows:
– Ensures CICS TXSeries 6.1 or higher is installed.
– On the compilation pass, the Developer for z/OS product:
- Passes the CICS compiler option to the compiler.
- Ensures that the integrated translator is called and ignores the Preprocessor field.
- Performs the compilation as though it were a regular (not CICS) compilation.
– On the CICSTCL pass, the Developer for z/OS product:
- Infers, by the presence of the CICS compiler option, that you also mean to use the integrated
translator for the CICSTCL.
- Adds the -p preprocessor option and performs the CICSTCL pass with the -p and other options that
are specified in the Preprocessor options field.
• On the Local Compile Options page for a local file, you specify the CICS('CTSxx') (for COBOL) or
pp(CICS('CTSxx') (for PL/I) option, where xx is the level of CICS. The Developer for z/OS product issues
a warning message and writes a warning to the log. The CICS('CTSxx') or pp(CICS('CTSxx') compiler
option is meant only for syntax checking.
Related tasks
Setting compiler options for show dependencies and remote syntax check
Related reference
“Default CICS preprocessor options” on page 57
The default preprocessor options are based on the CICS product that is installed on the workstation.

Default CICS preprocessor options

The default preprocessor options are based on the CICS product that is installed on the workstation.
Limitations:
• Local syntax check is deprecated. This action is available only on Windows.

Developing CICS applications 57

 • Local syntax checking does not support shift-out-shift-in (SOSI) sources. The importer that is used to do
the local syntax check supports only UTF-8 encoding. Translating CP-930 and other SOSI sources into
UTF-8 alters the column locations for some characters, and this alteration results in unexpected errors.
Compiler options for a local syntax check of a remote file are determined by the options that are specified
on the Procedures and Steps window. The version of CICS that is installed on the workstation determines
the correct preprocessor options for a local syntax check of a remote file. When the Preprocessor check
box on the Local Compile Options page is selected, the following default preprocessor options are set
according to the CICS product that is installed on the workstation.
• COBOL and CICS TX Series 6.1 or higher: CICSNT -lIBMCOB -adesvp
• COBOL and CICS TX Series 5.1: CICSNT -lIBMCOB -adesv
• PL/I and CICS TX Series 6.1 or higher: CICSTNT -lIBMPLI -adesvp
• PL/I and CICS TX Series 5.1: CICSTNT -lIBMPLI -adesvp
• PL/I and CICS TX Series 5.1: CICSTNT -lIBMPLI edf debug source print
If no CICS product is installed and the Preprocessor checkbox is selected, an option for CICS TXSeries
6.1 is generated. Upon compilation, if the correct translator for the product cannot be found, a window
indicating that the translator cannot be found opens a message is written to the log. For TXSeries 6.1 or
higher, the message indicates which version of the CICS translator cannot be found.
If you request a local syntax check of a remote file and the TXSeries 6.1 or higher product is not installed,
the compiler options to start the CICS Translator are not added to the syntax check. The syntax check
returns an error message that EXEC CICS statements were found and you must install CICS TXSeries. If
you request a local syntax check of a remote file and you have TXSeries 6.1 installed, but the level of
TXSeries required for that syntax check is not available, the compiler reports the error. If, for example, you
select a host syntax of CICS Transaction Server 3.2 on the Procedures and Steps page, but your compiler
and integrated translator do not support that level of CICS, you see a message similar to this message:
IGYOS0226-E ERZ004081E: Invalid CICS option 'CTS32' specified.
IGYDS0139-W Diagnostic messages were issued during processing of compiler options. These messages
are located at the beginning of the listing.

Related tasks
“Setting the CICS level for COBOL and PL/I programs” on page 55
You can set the level of CICS in use at your installation to aid more accurate content assistance and
syntax checking.
Related reference
“Default CICS preprocessor options” on page 57
The default preprocessor options are based on the CICS product that is installed on the workstation.

Defining CICS screens with the BMS Map Editor

BMS Screen Design is a function of the BMS Map Editor. This tool provides visual creation and modification
of BMS map sets. A BMS map set defines a screen for a CICS application. The BMS Map Editor is designed
for CICS developers who are familiar with terminal-based tools such as SDF II or GUI-based tools such as
the BMS Map Editor included with VisualAge® COBOL.
For a step-by-step guide through many of the BMS Map Editor options, see the “Using the BMS Map
Editor” on page 63.

What's new
Set auxiliary alignment hairlines in the BMS Map Editor
To add vertical or horizontal guides to the Design page, click the vertical or horizontal ruler. You can
align fields by attaching them to a guide. You can also move a guide on the Design page so that all
fields that are attached to the guide move along with it.
To delete a guide, select it and press the Delete key. Undo/Redo is supported for the guide actions.
The guide is shown only if the ruler is visible. Turning the ruler on or off is available as a preference
option. The default for TUI-based editors is to show the rulers.

58 Developer for z/OS: Developing with Db2, CICS, and IMS

 Ability to copy and move a field by using Ctrl+mouse
You can select and copy one or more fields by using the Ctrl key. Keeping the Ctrl key pressed, select
one or more items and move the mouse to a location on the screen. Then, release first the mouse
button and then the Ctrl key. This action creates a copy of the selected fields at the current mouse
location. The relative locations of the selected fields are retained in the copy.
Note: The standard way of copying an item to the clipboard and then pasting it in the Design page is
still available.

Editor features
BMS map sets and their associated projects are listed in the Project Explorer view. The Palette view
provides both click-and-drop and drag-and-drop access to the BMS map components. The editor provides
more capability with the Outline and Properties views.
The BMS Map Editor provides the following pages for designing and viewing a map set:
Design
Contains the Design canvas and display customization options, including map filtering. Pop-up menus
provide more formatting and display options.
Source
Provides a text editor for editing the map set file code directly. To make this page read-only, set an
option on the BMS Map Editor preference page.
Preview
Provides terminal-style and web preview modes.

Creating and editing map sets

You can use the new map set wizard to create new map set files in an existing local project or remote
MVS™ subproject. You can also create a BMS map set file directly on the remote system.
Within certain perspectives (such as Enterprise Service Tools or Host Access Transformation Services),
you can import an existing file structure into a workspace. You can also use the BMS Map Editor to work
with a map set on the remote system.

Object properties
To see the properties of a field, map, or map set, select the item in the Outline view. The properties are
displayed in the Properties view. You can also view and configure a map set component by using the
Design page menu.

Limitation
Existing BMS maps might contain the keyword SUFFIX= with no specified value. You must specify a value
or remove the keyword.

Creating a BMS map set

The BMS Map Set wizard guides you through the creation of a new map set.
Before you begin, you must create a project in your local workspace or you must create a partitioned data
set (PDS) on a remote system or an MVS subproject.
This topic mentions the EXTATT operand, which is supported for compatibility with previous releases. You
can now define each of the extended attributes individually. For new maps, use the MAPATTS and DSATTS
operands instead.
The MAPATTS operand specifies the attribute types to be included in the physical map. These types can
be one or more of the following values:
• COLOR
• HILIGHT
• OUTLINE

Developing CICS applications 59

 • PS
• SOSI
• TRANSP
• VALIDN
The MAPATTS types must include all the attribute types to be specified for individual fields in the map
(DFHMDF macro).
The DSATTS operand specifies the attribute types to be included in the symbolic description map. These
types can be one or more of the following values:
• COLOR
• HILIGHT
• OUTLINE
• PS
• SOSI
• TRANSP
• VALIDN
Any type included in the DSATTS operand must also be included in the MAPATTS operand.
To create a map set:
1. Click File > New > Other.
You can also use the keystroke combination Ctrl+N.
The "Select a wizard" window opens.
2. In the "Select a wizard" window, expand the z/OS Development category, select z/OS Development
> BMS > Map Set, and click Next.
The "BMS map set file location" window opens.
3. In the "BMS map set file location" window, browse to the folder that you want in a local project or in a
PDS on the remote system, specify the name of the file in which the new map set is to be created, and
click Next.
The .bms file name extension is automatically added to the file name.
• To create a map set with default attributes and extended attributes, click Finish. The map set
creation is complete.
• To specify map set attributes or to link to an MVS subproject, click Next. The BMS Map Set
Attributes window opens. Go to the next step.
4. In the BMS Map Set Attributes window, specify map set attributes:
a) You can specify the following map set attributes:
Name
The name of the map set
Description
A description of the map set
Language
One of the following values:
COBOL
PL/I
C
ASM
Type
One of the following values:
Physical

60 Developer for z/OS: Developing with Db2, CICS, and IMS

 Symbolic
&SYSPARM
Template
Terminal
One of the following values:
ALL
CRLP
DISK
TWX
1050
2740
2770
2780
3780
3270-1
3270-2
INTLU
3767
3770
SCS
2980
2980-4
3270
3601
3653
3650UP
3650
BCHLU
3770B
Mode
One of the following values:
Input and output
Input
Output
b) To create a map that is the size of the map set, select Create full screen map.
c) If you want to add the new .bms file to an existing MVS subproject, select Add to MVS Project, and
click the project name on the list.
d) Choose whether you want to create a map set with default extended attributes.
• To create a map set with default extended attributes, click Finish. The map set creation is
complete.
• To specify extended attributes, click Next. The "Extended attributes" window opens. Go to the
next step.
5. Make choices in the "Extended attributes" window.
a) The Symbolic (DSECT) check boxes are as follows:
__ Extended color
__ Extended highlighting
__ Field outlining
__ Programmed symbol
__ Double byte SOSI

Developing CICS applications 61

 __ Background transparency
__ Validation
b) The Physical (MAP) check boxes are as follows:
__ Extended color
__ Extended highlighting
__ Field outlining
__ Programmed symbol
__ Double byte SOSI
__ Background transparency
__ Validation
c) In the Extended attributes support list, select the blank value or set the EXTATT operand by
choosing one of the following values:
No
Is equivalent to omitting the DSATTS and MAPATTS operands.
Yes
Is equivalent to the following setting (the default):

MAPATTS=(COLOR,HILIGHT,PS,VALIDN)
DSATTS=(COLOR,HILIGHT,PS,VALIDN)

Map only
Is equivalent to the following setting:

MAPATTS=(COLOR,HILIGHT,PS,VALIDN)

If you select the blank value, the EXTATT operand is omitted from the new map set file.
6. Click Finish to finish creating the map set.
A map set file is created.

Editing existing BMS maps

The BMS editor can interpret SDF II repeating blocks as a Developer for z/OS structure using DGI
comments.

Editing Empty BMS Maps

When you open an empty BMS map in Developer for z/OS, the New Mapset Wizard opens immediately.
Using this wizard, you can define the map set with whatever characteristics you want. After completing
the New Mapset Wizard, the empty file is updated with the DFHMSD macros needed, and you can
immediately start working in the Design page of the editor.
Alternatively, if your purpose is to open the editor and paste contents from the clipboard, then click
Cancel when the New Mapset Wizard opens. The Source page of the BMS Editor opens on the empty file.

Editing BMS Maps with SDF II Repeating Blocks

SDF II allows for the definition of repeating blocks of fields in screens and generates a BMS file that
represents the screen. A COBOL data structure generated from this BMS file by SDF II contains an
OCCURS clause representing the repeating block. However, the metadata SDF II uses to create the
COBOL data structure is stored outside of the BMS file. If the same BMS file generated by SDF II is
assembled in Developer for z/OS, a COBOL data structure without an OCCURS clause is created.
To overcome this issue, a REXX exec – DGIDSBMS - was released by SDF II as part of PTF PQ86423. It
takes as input BMS files and COBOL data structures generated by one SDF II environment and produces
as output a newly annotated BMS source file. This BMS source file is imported into a second SDF II
environment, and the annotations, or DGI comments, are used to recreate the metadata needed for
defining the repeating blocks. When the annotated BMS files are opened in Developer for z/OS, the

62 Developer for z/OS: Developing with Db2, CICS, and IMS

 BMS Editor recognizes the DGI-style comments and prompts the user to convert them to a Developer
for z/OS recognizable format. If the comments are converted, the BMS file is updated, and previously
unrecognizable constructs, such as repeating blocks, are recognized by the BMS Editor. The BMS file is
also marked as dirty and left open in the BMS editor.
In addition to repeat blocks, the DGI style comments also provide insight into other SDF II-specific
information related to the BMS file but not contained in the BMS source, such as the presence of field
name prefixes, field level comments, array comments, repeat block comments, alternate map name, and
alternate structure start level used in data structure generation. This SDF II conversion does not support
sub fields. By converting the DGI comments, Developer for z/OS uses this information when editing the
BMS map and also when generating the corresponding symbolic map.
Note: For proper DGI comment conversion, include DGI-style comments as the first line of the BMS map
file.

Generating Existing Maps in Different Languages

Sometimes, generating symbolic maps from BMS files that are in certain languages causes parse errors.
These error occur because the code page is not set to support special characters, such as accents. Setting
the code page to support these characters usually eliminates the parse error and causes the symbolic
map to be generated correctly.
To change the code page on a BMS map:
1. In the Remote Systems view, right-click the BMS map or the PDS that contains the BMS map, and
select Properties.
2. Select Mapping.
3. The third selection down is labeled Code Page. For the Local Code Page, clickOther.
4. From the menu, select the appropriate code page for the BMS map.

Using the BMS Map Editor

This series of steps guides you through some of the features and capabilities of the BMS Map Editor. For
detailed information about procedures and configuration, see the specific topics in the BMS Map Editor
helps.
Note: Regularly save any modifications to a map set.
In Developer for z/OS, the BMS Map Editor is associated with .bms map set files and is available in any
perspective. The editor uses the following views:
• Project Explorer
• Outline
• Palette
• Properties
You can import map set files into certain perspectives, such as Enterprise Service Tools.
You can export maps to a JavaServer Faces Web page and its components.

Creating a project
Map sets can be created only in an existing project. To create a project:
1. From the main menu, select File > New > Project.
2. In the New Project wizard that opens, expand General > Project. Click Next.
3. Type Test project as the project name. Click Finish to close the wizard and create the project.
Test project is listed in the Project Explorer view. To open this view from the main menu, select
Window (on Windows) or IBM Developer for z/OS (on macOS) > Show View > Other and type Project
Explorer as the filter text.

Developing CICS applications 63

 Creating a map set
To create a map set in a project:
1. From the main menu, select File > New > Other.
2. In the New wizard that opens, enter Map Set as the filter text and select BMS > Map Set from the list
of file wizards.
3. Click Next.
4. Select Test project as the parent folder.
5. Type NEWMAPSET as the file name. The .bms extension is automatically added.
6. Click Finish to accept the default configuration.
The map set file NEWMAPSET.BMS is listed in theTest project project in the Project Explorer view.

Adding maps to the map set

To add and modify maps and fields in the map set:
1. Open the map in the editor by double-clicking NEWMAPSET.BMS if it is not already open
2. Start by tagging and dragging the mouse down to and to the right in the Design canvas. Notice the size
and position of the map are shown in the pop-up box.
3. in the Basic drawer of the Palette view, select Map.
4. Move the cursor to the Design canvas, and click to place the map.
You can use the Select tool in the Default drawer to move and resize the map.

Viewing and modifying map properties

Select a map in the Design canvas. The map properties are shown in the Properties view. The selected
map is also highlighted in the Outline view.
To modify map properties from the Design canvas, complete the following steps:
1. In the Outline view, right-click MAP2. The map is highlighted in the Design canvas.

2. Click Toggle Black and White Mode, , in the upper-right corner of the Design canvas to view the
selected map more easily.
3. Right-click the highlighted map in the Design canvas and select Map Properties from the menu to
modify the settings.
To modify map properties under the Source tab, complete the following steps:
1. Click the Source tab below the Design canvas.
2. Locate the Map1 label.
3. Place the cursor in the source code and change the map size parameters to SIZE=(14,60). This
action changes the height of the map to 14 columns and the width to 60 columns. The change is
shown in the Properties view.

Adding and modifying fields

To add and modify a label field:
1. in the Constant Fields drawer of the Palette, select Label.
2. Click in the Design canvas to place the field. If the location is not valid, for example, outside the
boundaries of an existing map, you cannot place the field.

3. If the label field is not shown with the map in the Outline view, select Show Unnamed Fields, , to
show the label field.
4. Left-click the field in the Design canvas and type a new label value.
5. Double-click the field in the Design canvas.

64 Developer for z/OS: Developing with Db2, CICS, and IMS

 6. Add a name for the label field, and click Apply. Click Show Unnamed Fields again; the field is now
shown with its name in the Outline view.
7. Right-click the field in the Outline view. Select Cut to remove the field from its current map.
8. Select a different map in the Outline view. Press Ctrl+V to place the field into that map.
To add and modify a password field:
1. Click the Password field button in the Variable Fields drawer.
2. Place the pointer in the Design canvas. A drop box is added to the pointer.
3. Click and hold the left mouse button at the location that you want.
4. Draw the field to a width of five characters and release the mouse button.
Note: The height in the pop-up box cannot be greater than two characters; the drawn box can be only
0 or 1 character high.
Align the fields by completing the following steps:
1. In the Outline view, select multiple fields by holding the Ctrl key and clicking the field icons.
2. Right-click one of the highlighted fields in the Design canvas, and select Align > Align to Parent > Top.
The fields are aligned to the top of the map.
Use the Shift key with the Select tool to grab and move multiple items in the Design canvas. View the
maps and fields with the other display options to see how they can assist you in modifying maps and
fields.

Filtering and previewing maps

Use the Filters feature to view, prioritize, or hide specific maps within a set:
1. Click Filters above the Design canvas. The name of the current filter is shown below the button.
2. Click New to add a filter.
3. Move maps up or down the filter list, or clear maps.
Note the changes in the Preview pane. Filters display the enabled maps in order, as you look at the
Preview pane or Design canvas (the second map is placed behind the first and the third is placed
behind the second).
4. Click OK to complete the filter modification.
5. Click the list beside the Filters button and select the newly added filter from the list of available filters.
The filtered maps are not shown in the Design canvas or the Outline view.
6. Click the Preview tab. In Normal mode, the filtered maps are not shown.
The Preview page shows maps and fields in Web and Normal mode. Normal mode provides a terminal-
like preview, with full filtering capability. The Web mode shows all maps in a set.

BMS Map Editor features

Design page in BMS Map Editor
The Design page contains the Design canvas, where you can visually edit a map set. You can also
customize the display options for the canvas.

Design canvas
The Design canvas provides the space for customizing a map set. Use the scroll bars to view the entire
visual editing space.
To see the available design, filter, and edit options, right-click the canvas to open the menu.
To add an item to the canvas, click the item icon on the palette and then click the canvas location that you
want. You can also drag the item to the canvas.

Developing CICS applications 65

 When you select an item in the Design canvas, that item is highlighted in the Outline view, and property
value information is shown in the Properties view.

Edit options and keyboard shortcuts

The following table lists the edit options and the corresponding keyboard combinations. These options are
also available from the menu.

Table 2. Design canvas edit options

Option Keyboard shortcut
Undo Ctrl+Z
Redo Ctrl+Y
Cut Ctrl+X
Copy Ctrl+C
Paste Ctrl+V
Delete Delete
Save Ctrl+S

Important: The Undo and Redo operations apply to operations performed in either the Outline view or
the Design canvas. For example, if you cut a field in the Design canvas, the Undo Cut option is enabled in
the Outline view menu.

Selecting and moving items

To select and move items on the Design canvas, use the Palette view Select tool from the Default
drawer. Click the item, hold down the mouse button, and drag the item to a new location. When you
drag an item, a small window shows the location information. For a map, the row and column value are
displayed, along with the height and width of the map. For a field, the row and column value within the
map are displayed, along with the field width.
To select multiple items in sequence, use the Select tool in the Design canvas. Hold down the Ctrl key
and click the items to be selected. You can then click one highlighted item to move the entire group of
selected items.
To draw a box around the items that you want in the Design canvas, press the Shift key while you use the
Select tool.
To draw a box around the items in the Design canvas and have only nodes that are selected, use the
Marquee tool. Then, use the Select tool to create a cursor for moving the items.

Display options
Use the following display options to customize the Design canvas.
Terminal Size
This selector creates maps for several potential CICS screen sizes. The default value is 24 × 80.
Toggle Gridlines
This option hides or shows the grid lines in the Design canvas.
Toggle Samples Values
This option shows the type of data allowable in a variable field and the size of the field. For example, a
numeric field of four units shows a sample value of 9999. An alphanumeric field shows XXXX.
Toggle Black and White Mode
This mode shows fields and maps in a high-contrast canvas.
Zoom Level
This option controls the zoom level of the Design canvas.

66 Developer for z/OS: Developing with Db2, CICS, and IMS

Filters
This option shows a subset of the maps in the Design canvas.
By default, all maps are shown. You can create new filters to display customized groups of maps. You
can also change the order of maps in the list.

Printing
To print the design canvas, click File > Print from the menu bar. You can also use the Ctrl+P key
combination or select Print from the menu.
Note: You cannot print individual maps or fields that are in the design canvas.

Bidirectional options
If you enable bidirectional support, a Toggle Bidirectional Mode button is displayed on the Design page
toolbar.
The following toggle options are available:
Visual Data
Toggles between visual ordering of text and the default logical ordering.
RTL Map Set
Toggles the orientation of the map set and the horizontal ruler between left-to-right to right-to-left.
Symmetric Swapping
Resets swappable characters. For example, in a right-to-left string, the opening parenthesis ( and
closing parenthesis ) are reversed.
Numeric Swapping
Sets an inversion of the screen, which causes Hindi numerals to be replaced by their Arabic
counterparts and Arabic numerals to be replaced by their Hindi counterparts.

Design page menu

The Design page menu provides context-specific field and map display and formatting options and editing
options.
You can also view the “Field properties” on page 80 and “BMS map properties” on page 82 windows, if
you select an item with the cursor.
The “Show Source” on page 68 option shows specific map or field information.
To print the entire design canvas, select Print. You cannot print specific maps or fields.
The field-specific formatting options are as follows:
Format
Includes the following options:
Highlighting
Outline
Intensity
Color
Align
Provides horizontal and vertical alignment options and an Align to Parent menu.
The following general display options are on the toolbar above the Design canvas:
• Show Grid
• Show Sample Values
The Filters menu includes some display options that are not available elsewhere:
• Hide Map or Show Map (based on context)
• Hide All Maps

Developing CICS applications 67

 • Show All Maps
• Configure (opens the Filters window)
The following options are standard editing options:
• Undo and Redo
• Cut, Copy, Paste, and Delete
Important: The Undo and Redo options apply to operations performed in either the Outline view or the
Design canvas. For example, if you cut a field in the Design canvas, the Undo Cut option is enabled in the
Outline view menu.

Bidirectional options
If you enable bidirectional support, a Bidirectional Settings option is displayed on the Design page
menu. The same options are on the bidirectional toggle button.

Label field options

When working with a label field, you might see the following options:
• Right to left Reading order
• Show Unicode control characters
• Insert Unicode control character (with additional options)
These system options are provided by Windows operating system when you are working with text input
fields. For more information, see the Windows documentation.

Show Source
The Show Source option of the Design canvas menu displays the BMS source for a selected map set,
map, or field.
You can also perform this action by pressing Alt+Shift+S.

Source page
The Source page enables you to modify the BMS source macros directly by using a text editor.
Standard editing features are provided, such as Find, Replace, Undo, and Redo. The menu provides
additional options:
• Customized color highlighting.
Items such as macro names, field names, attribute names and values, and comments are colored
differently to help you differentiate parts of a BMS statement. You can customize the colors by using the
“BMS Map Editor preferences” on page 89 window.
• Line numbers
Line numbers are displayed in the left margin of the editor window. You can hide line numbers by using
the “BMS Map Editor preferences” on page 89 window.
• Error markers
If syntax errors are encountered during a save or validation and build operation, an error icon is
displayed in the left margin of the line that contains the error. Errors also are displayed in the Problems
view.

Source page menu in BMS Editor

The Source page menu provides code formatting options and editing options. Changes to the source code
are immediately reflected in the Design canvas and Preview page.
To select a line, click it. To select multiple lines, hold down the Shift key and click each line.

68 Developer for z/OS: Developing with Db2, CICS, and IMS

To move the source code, use the Shift Right and Shift Left actions. If the source syntax is incorrect, an
error icon is displayed beside the line number.
To add code to a snippet drawer, select the text and click Add to Snippets.
To go back to the previously saved file source, use the Revert File option.
To retain your changes, click Save.
Restriction: Save as is not supported for remote resources.

Preview page
The Preview page provides a read-only display of the map set, as it appears in an emulator.

Display options
Use the following display options to customize the map set preview:
Preview Mode
This option shows the map set as it appears in Web or Normal (terminal emulator) form. The Web
option is available even if a Web page is not created from the map set file.
Filters
This option enables you to preview and prioritize a subset of the available maps. By default, all maps
are shown. You create new filters to display customized groupings of maps.
Sample Values
If the Sample Values button is set to true on the Design page, the variable fields are shown with the
sample values in the preview mode.
Click Refresh to update the map set preview.

Filters
Filters enable you to customize your view of a map set by grouping maps together in a display order. Filter
configurations are saved in the current workspace and cannot be transferred to another workspace.
Note: This option is not available for the Source page.
Filters display the enabled maps in order, as you look at the Preview pane or Design canvas. The name of
the current filter is displayed below the button.

Select a filter
Use the Filter tool on the Design page toolbar to select a filter from the list of available filters. If a filter is
currently being applied, the name of the filter is displayed below the button.
Click New to create a filter. Click Remove to delete the current filter.

Select the maps to be revealed by this filter

Set the order of the maps to be shown in the selected filter.
Moving a map higher in the list places it in front of the lower-ordered maps when viewed in the Design or
Preview canvas. For example, the second map is placed behind the first and the third is placed behind the
second. To remove a map from the filter, clear the checkbox.
To remove a map from the filter, clear the box beside the map name. Maps that are not selected do not
affect the display of selected maps that are lower in the priority list.

Developing CICS applications 69

Map set components
You can add and modify several BMS map set components.
BMS maps do not compile properly if they do not contain at least one map in each map set and one field in
each map.

Maps
You can use the Map palette item to create and size maps in a map set.
As you add maps to the Design canvas, the items are displayed in the Outline view. For details about
adding and sizing maps, see “Adding maps” on page 70. You must include at least one map in each map
set for the BMS map to properly compile.
You can also change the order of the palette by using the Customize window.

Adding maps
To create a map in the Design canvas, complete the following steps:
1. Click the Map button in the palette.
2. Place the pointer in the Design canvas.
3. Click and hold the left mouse button at the location that you want.
4. Draw the map (using the pop-up box for sizing information) and release the mouse button.
You can use the Select tool to move and resize maps in the Design canvas.

Constant fields
The constant fields in the palette are protected normal fields. When added to a map, these fields are in
direct-edit mode, so that you can easily edit the label text.
The following constant fields are provided by default:
• Column heading
• Help
• Instructions
• Label
• Title
You can modify the properties of the fields in the “Palette entries preferences” on page 91 preferences.
At least one field must be defined per map.
Click the Constant Fields drawer label to show or hide the item list. You can hide, remove, or change the
order of fields by customizing the “Palette view” on page 77.

Adding fields
As you add fields to the Design canvas, the items are displayed in the Outline view.
Note: You can add fields only to an existing map.
To add a field to a map in the Design canvas:
1. In the Palette view, click the field that you want. The item is highlighted.
2. Place the pointer in the Design canvas. A drop box is added to the pointer.
3. Click and hold the left mouse button at the location that you want.
4. Using the pop-up box for sizing information, draw the field to the width that you want, and release the
mouse button.
Note: The height of the drawn box can be only 0 or 1 character. If the height in pop-up information box
is equal to or greater than two characters, the field is not created.

70 Developer for z/OS: Developing with Db2, CICS, and IMS

You can use the Select tool to move and resize fields in the Design canvas.

Variable fields
The variable fields in the palette are unprotected normal or numeric-only fields. These fields
automatically add a zero-length protected field after the input field; this action prevents unwanted visual
wrapping when the map set is compiled and run on the remote system.
The following variable fields are provided by default:
• Input field
• Numeric field
• Password field
• Message
• Output field
• MDT field
This field has the MDT tag set to TRUE by default.
You can modify the properties of the fields in the “Palette entries preferences” on page 91 preferences.
At least one field must be defined per map.
Click the Variable Fields drawer label to show or hide the item list. You can hide, remove, or change the
order of fields by customizing the “Palette view” on page 77.

Adding fields
As you add fields to the Design canvas, the items are displayed in the Outline view.
Note: You can add fields only to an existing map.
To add a field to a map in the Design canvas:
1. In the Palette view, click the field that you want. The item is highlighted.
2. Place the pointer in the Design canvas. A drop box is added to the simple pointer.
3. Click and hold the left mouse button at the location that you want.
4. Using the pop-up box for sizing information, draw the field to the width that you want, and release the
mouse button.
Note: The height of the drawn box can be only 0 or 1 characters. If the height in pop-up information
box is equal to or greater than two characters, the field is not created.
5. If the field you are adding is an input, numeric, password, or MDT field, a pop-up properties panel is
displayed when you finish drawing the field. Mark the checkbox, Add stopper fields to add a stopper
field to the input field.
You can use the Select tool to move and resize fields in the Design canvas.

Stopper fields
Stopper fields keep input fields from accepting more characters than the defined length of the input field.

Representation of stopper fields

Developer for z/OS recognizes stopper fields as a 0 or 1 length field immediately following a variable field
with the attributes (ASKIP,NORM).
When Developer for z/OS creates a stopper field, it is created as a 0 length field with the attribute ASKIP.
The following is an example of an automatically added stopper field:
DFHMDF POS=(8,38),LENGTH=0,
ATTRB=ASKP

Developing CICS applications 71

 Adding stopper fields
Stopper fields are added by default to input fields, numeric fields, modified data tag (MDT) fields, labeled
input fields, and simple array fields.
To manually add a stopper field:
1. In the Design Page of the BMS Editor, right click the field and select Field Properties from the menu.
(Edit Array if you want to add stopper fields to an entire array.)
2. The Field Properties window opens. Select the Basic page from the left menu of options.
3. Select Add Stopper Fields and click OK to add stopper fields to the field.
Stopper fields can be manually added to complex array fields by selecting the checkbox when the fields
are defined.
Note: If you return to add a stopper field after an array or structure is resolved, some array adjustment
might be needed to account for the extra column the stopper field will take up. Arrays and structures do
not automatically adjust at the addition of a stopper field.

Removing stopper fields

Stopper fields can be removed by clearing the Add stopper fields checkbox under Field Properties for
the field. Alternatively, stopper fields can be removed by selecting the field in the Design Page of the BMS
Editor and pressing delete.

Advanced palette
The Advanced design palette provides specific items for inclusion in a map. These items require a
minimum configuration before you can add them to a map.
Click the Advanced drawer label to show or hide the item list. You can also change the order of options
with the Customize menu option.
Note: You can add fields only to an existing map.
To add an item to a map in the Design canvas:
1. In the Palette view, click the item that you want. The item is highlighted.
2. Move the cursor to the Design canvas. It is not necessary to hold down the mouse button.
3. Click the location that you want on the Design canvas. If a location that you want is not valid, the item
cannot be added to the Design canvas.
4. Set the required properties in the configuration wizard.
As you add maps and fields to the Design canvas, the items are displayed in the Outline view. The
Properties view shows the specific settings for each item.

Labeled Input Field

Use the Labeled Input Field tool to create an input field and an associated label field.
To create a labeled input field in an existing map:
1. Click the cursor on Labeled Input Field in the Advanced palette.
2. Move the cursor to the Design canvas. It is not necessary to hold down the mouse button.
3. Click the location that you want on the Design canvas. If the location is not valid, the fields are not
added to the Design canvas.
You can also draw a sizing box. However, by default the label field is five characters wide and the input
field is one characters wide. Thus, the size of the drawn box does not affect the sizing of the fields.
You can specify the following label field properties:
• Caption

72 Developer for z/OS: Developing with Db2, CICS, and IMS

• Length
• Fill remainder (specifies the character used to fill the remaining label space)
You can specify the following input field properties:
• Name
• Length
• Initial value
• Whether the field is a Password field (check box)
A warning is displayed if the input field cannot fit in the specified location.

Reverse Layout Field

The Reverse Layout Field setting reverses the locations of the input and label fields. To access this
option, you must enable bidirectional support.

Array
Use the Array tool to create a simple or complex array.

Types of arrays
Simple Arrays
A simple array is a single BMS field that repeats either vertically or horizontally.
Complex Arrays
A complex array is a two-dimensional array that is repeated both vertically and horizontally creating
both rows and columns.

Creating simple or complex arrays

To create an array:
1. Click the Array button in the Advanced palette.
2. Click the cursor in the Design canvas. The Create a New Array window opens.
3. For a simple array, select the Simple radio button.
a. Specify the Field name, Comments, Length, Distance between fields in the array, Occurs, and
the Array direction.
b. To add stopper fields to the end of the simple array, select Add stopper fields.
4. For a complex array, select the Complex radio button.
a. Specify values for the Field name, Comments, and Length fields.
b. In Distance between fields in the array specify a distance in terms of rows for vertical arrays or
columns for horizontal arrays.
c. The Occurs value is populated according to the number of fields in each row and column specified
in the table at the bottom of the wizard.
d. In Array Direction, specify the order in which fields are created in the source.
For example, a vertical array has fields defined as follows:

field(1) field(4) field(7)

field(2) field(5) field(8)
field(3) field(6) field(9)

Where field(1) is the first to appear in the source, field(2) the second field to appear in the
source, and so on.
A horizontal array has fields defined as follows:

Developing CICS applications 73

 field(1) field(2) field(3)
field(4) field(5) field(6)
field(7) field(8) field(9)

e. Use the table at the bottom of the Create a Field Array wizard to define the fields to populate
into the complex array. For more information about defining fields, see Defining Fields in Complex
Arrays.
Note: You cannot edit this table to provide the array fields until you have provided the length of
each field
5. Click Finish to create the array.
A warning appears if the array cannot fit in the specified location.
Regardless of the type of array created after the field array is drawn on the canvas, the fields behave as
individual fields and can be edited individually.

Editing Simple or Complex Arrays

The following editing capabilities are available:
• Delete
To delete the array, select any field and then select the Delete key.
• Edit
To edit the array properties, select any field in the array, right-click, and select Edit Array. The Edit
Array wizard is launched. The wizard displays all current array values. Update the values and click
Finish. The array reflects the value changes. The source also reflects these changes.
To change the individual field properties, select the particular field, right-click, and select Field
Properties.
• Select
When you select any field in the array, all fields in the array are selected.
• Move
Select the array and then drag it across the design page to any valid location.

Defining fields for complex arrays

Complex arrays require that the fields be defined by using the table at the bottom of the Create a Field
Array wizard. Fields in complex arrays can be added, edited, and removed.

Adding fields
To add fields to a complex array, click the Add button directly to the right of the table.
1. In the Define Field window that opens, specify a value in the Row Offset field. This value is the offset
from the first row containing an array field. Often, this row corresponds to the location you click in the
Design Panel.
2. Specify a value in the Column Offset field. This value is the offset from the first column containing an
array field. Often, this row corresponds to the location you click in the Design Panel.
3. Specify a value in Number of Fields. This value is the number of times the field repeats.
Note: If the array direction is specified as vertical, then the fields repeat from the top to the bottom of
the BMS map. If the array direction is specified as horizontal, then the fields repeat from the left to the
right of the BMS map.
4. Select Input field if the defined fields are input fields.
5. Select Add Stopper Fields to add stopper fields to the defined fields.
6. Click OK to close the window. The new field is listed in the table.

74 Developer for z/OS: Developing with Db2, CICS, and IMS

Editing fields
To edit fields, select the field in the table and click the Edit button to the right of the table.
Note: When row and column fields are edited, the fields are updated to be placed in the row or column
specified by the edit. Added entries do not have row or column values calculated based on an offset.

Removing fields
To remove a field, select the field in the table and click the Remove button to the right of the table.

Structure
Use the Structure tool to create an array of multiple fields that are repeated vertically on the screen.
To place a structure:
1. Click the Structure button in the Advanced palette.
2. Click the cursor in the Design canvas.
3. Specify the following parameters:
• Structure name
• Occurs
This values specifies the number of times that the defined set of fields is repeated in the structure.
4. Click Add to specify additional fields in the structure.
You can set the following parameters:
• Field name
• Width
• Row offset
• Column offset
• Input field
Note: Once a structure is resolved, changing the input field attribute on fields does not make the
fields appear with a green underline as they would if you initially mark the input field attribute. This
condition does not mean the fields of the structure are not input fields. Instead, it is meant to avoid
possible overriding of individual, visual customization of the fields.
The offset values specify the location of the field in relation to where you click the mouse on the
Design canvas. For example, if you click the mouse at location (4,4) on the canvas, and the field in the
structure has a row offset of 1 and a column offset of 2, then the location of this field is (5,6).
Each field in the structure has the specified row and column offset relative to the original mouse click.
5. Click Finish to create the structure.
A warning opens if the structure cannot fit in the specified location.

Editing structures
The following edit capabilities are available:
• Delete
To delete the structure, select any field, and then select the Delete key.
• Edit
To edit the structure properties, select any field in the array, right-click, and select Edit Structure. The
Edit Structure wizard opens. The wizard displays all current structure values. Update the values and
click Finish. The structure reflects the value changes. The source also reflects these changes.
To change the individual field properties, select the particular field, right-click, and select Field
Properties.

Developing CICS applications 75

 Note: It is recommended to use only the Edit Structure dialog when you are editing the width
of columns in the structure. Editing the structure outside of the Edit Structure dialog can cause
unexpected results.
• Select
When you select any field in the structure, all fields in the structure are selected.
• Move
Select the structure and then drag it across the design page to any valid location.

Basic Map Screen (BMS) Editor icons

The following icons are commonly seen in the BMS Editor palette, the Outline view when a map is open in
the BMS Editor, and the BMS Editor toolbar.

BMS Editor palette

The following icons are commonly seen in the BMS Editor Palette.

Table 3. BMS Editor palette icons

Icon Description Icon Description
Icons found in the Default drawer
Selects a single field in the Design Selects multiple fields in the Design Page.
Page.
Icons found in the Basic drawer
Inserts a map into the map set.

Icons found in the “Constant fields” on page 70 drawer

Creates a column heading in the active Creates a help field in the active map. By
map. By default, column headings are default, help fields are green.
blue.
Creates an instructions field in the Creates a label field in the active map. By
active map. By default, instruction default, label fields are blue.
fields are blue.
Creates a title field in the active map.
By default, title fields are blue.
Icons found in the “Variable fields” on page 71 drawer
Creates an input field in the active Creates a numeric field in the active map.
map. By default, input fields are green By default, stopper fields are included and
with highlighting set to underline and initial values are blue.
include stopper fields.
Creates a password field in the active Creates a message field in the active map.
map. By default, password fields are By default message fields are red.
green with highlighting set to underline
and include stopper fields.
Creates an output field in the active Creates a modified data tag field in the
map. active map.
Icons found in the Advanced drawer
Creates a label field followed by an Creates either a simple or complex array.
input field with a stopper field.

76 Developer for z/OS: Developing with Db2, CICS, and IMS

 Table 3. BMS Editor palette icons (continued)
Icon Description Icon Description
Creates a structure.

BMS Editor toolbar

The following icons are commonly seen in the toolbar on the Design Page of the editor.

Table 4. BMS Editor toolbar icons

Icon Description Icon Description
Toggles the grid lines in the BMS Editor Toggles the initial values that are specified
on and off. for each field on and off.
Toggles the editor between black-and- Zooms in and out in the BMS Editor.
white mode and color mode.
Accesses filters that are defined for
the active map set.

Outline View for BMS maps

The following icons are commonly seen in the Outline view when a map is open in the BMS Editor.

Table 5. Icons in the Outline view

Icon Description Icon Description
The map set A map that is part of the map set

A protected field in a map An unprotected field in a map

Views
The BMS Map Editor provides several editor views.

Palette view
The Palette view provides Design page selection tools and BMS Map Editor map set components.
The Palette view includes the following drawers:
• Default (see “Default drawer” on page 77)
• Basic (see “Maps” on page 70)
• Constant Fields (see “Constant fields” on page 70)
• Variable Fields (see “Variable fields” on page 71)
• Advanced (see “Advanced palette” on page 72)
Click the specific drawer label to show or hide the item list.

Default drawer
The Default drawer contains the Select and Marquee tools that come with Eclipse for editing files
(including BMS map sets) that are based on the Graphical Editing Framework (GEF). For information about
how to use these tools to select and move items, see “Design page in BMS Map Editor” on page 65.

Developing CICS applications 77

 Customizing the Palette view
To add or change drawers or map components, right-click the palette and select Customize.
The following drawer and map component display options can be customized:
Name
The name displayed in the palette.
Description
Text that is displayed when you move the mouse pointer over the palette item.
Hide
A checkbox that prevents the item from being displayed in the palette.
The following drawer options are available:
Open drawer at start-up
The drawer is expanded when the Palette view is shown.
Pin drawer open at start-up
The drawer remains pinned open unless you click the drawer to close it.
You can hide any of the drawers or add new drawers. However, you cannot delete the five initial drawers.
You can change the default display properties for the palette entries from the “BMS Map Editor
preferences” on page 89 window.

Outline view
The Outline view displays map and field information for a specific map set file.
The following display options are available:
• Show Initial Value
Displays the initial value for all fields in the map set.
• Show Unnamed Fields
Displays fields that are not important to the function of the map (that is, unnamed fields).
By default, all fields are shown in the Outline view. Disable this function to hide all unnamed fields in
the Outline view.
• Show Hidden Maps
Displays maps that are hidden in the current filter.
By default, all maps are shown. Turn the function off to remove hidden maps from the Outline display.
When you select an item in the Outline view, that item is highlighted in the Design canvas and the Source
page. The property value information is shown in the Properties view.
The Outline view is displayed by default. You can change the BMS Map Editor preferences to hide this
view.

Pop-up menu and keyboard shortcuts

Table 6 on page 78 lists the context-sensitive right-click edit options and the corresponding keyboard
combinations.

Table 6. Outline view options

Option Keyboard shortcut
Undo Ctrl+Z
Redo Ctrl+Y
Cut Ctrl+X

78 Developer for z/OS: Developing with Db2, CICS, and IMS

Table 6. Outline view options (continued)
Option Keyboard shortcut
Copy Ctrl+C
Paste Ctrl+V
Delete Delete
Save Ctrl+S

Important: The Undo and Redo operations apply to operations performed in either the Outline view or
the Design canvas. For example, if you cut a field in the Design canvas, the Undo Cut option is enabled in
the Outline view menu.
When selecting a map set, you can also choose Generate JSF Web pages from the menu.

Properties view
The Properties view displays property value information for a field or map that is selected in the Design
canvas or the Outline view.
For a map set, the following properties are displayed:
• Language
• Map type
• Name
For a map, the following properties are displayed:
• Column
• Height
• Name
• Row
• Width
For a field, the following properties are displayed:
• Column
• Group name
• Initial value
• Length
• Name
• Occurs
• Row
• Type
The Properties view is displayed by default. You can change the BMS Map Editor preferences to hide this
view.

Developing CICS applications 79

Properties
You can set properties for several BMS components.

Field properties
To open the Field Properties window, double-click a field in the Design canvas or right-click the field and
select Field Properties from the menu.

Basic
You can specify the following basic properties:
• Name
• Comments
• Row
• Column
• Length
• Initial Value
• Color
Select the color that you want. Use the Inherit option to take the value from the parent.

Presentation
You can specify the following presentation properties:
• Intensity
Values are as follows:
– Dark
– Normal
– Bright
• Highlighting
Values are as follows:
– Inherit
The highlighting value is inherited from the parent.
– Off
– Underline
– Reverse
– Blink
• Transparency
Background transparency is determined by terminal capability. Values are as follows:
– Inherit
The transparency value is inherited from the parent.
– Yes
– No
• Border settings are as follows:
– Outline (box)
This option supersedes the other border options.
– Border over

80 Developer for z/OS: Developing with Db2, CICS, and IMS

 – Border under
– Border left
– Border right

Attributes
You can specify the following field attributes:
• Type
Specifies type of field. Values are as follows:
– Protected
– Protected (automatic skip)
– Unprotected
– Unprotected (numeric only)
• Detectable
• Initial cursor
Cursor is initially placed in this field.
• Modified data tag
This tag indicates whether the field has been modified or not. For the read command that CICS normally
uses, this bit determines whether the field is included in the inbound data or not. If the bit is on
(indicating that the field is changed), the 3270 sends the field; if not, the field is not sent.
• Validation
Settings are as follows:
– Must fill
– Must enter
– Trigger
A trigger field causes the terminal to transmit its contents if the operator moves the cursor out of the
field when it is primed.
– User exit

Advanced
You can specify the following advanced properties:
• Group name
• Occurs
This setting specifies the number of times that the field is repeated, as part of an array.
• Picture in
This setting indicates that a COBOL or PL/I picture is applied to the field for an IN or INOUT map.
• Picture out
This setting indicates that a COBOL or PL/I picture is applied to the field for an OUT or INOUT map.
• SOSI
This setting places Shift-Out and Shift-In characters indicating that double-byte characters might be
present.

Developing CICS applications 81

 Comments in the Field Properties window
The Comments property is a field in the Field Properties window of the BMS Map Editor.

Basic
The Comment property associates a comment statement with a field element. The comment length can
be up to 69 characters. When the comment string is entered into the Comments field it is associated with
the BMS field element and the source code is annotated with the comment statement.
You can verify that the association is made by selecting the field element and opening the properties
window. When You change the comments in the properties window, the changes are made in the source
code as well.

Usage
• The BMS Editor automatically creates a comment for each array or structure field. For each of these
fields as with other fields you can create your own comment.
• You can also create a comment that is associated with the overall structure.
• Comments cannot span multiple lines in the source code.
• Any comments associated with BMS variable, array, or structure fields are carried forward into the
generated copybook.

BMS map properties

To open the Map Properties window, double-click a map in the Design canvas or right-click the map and
select Map Properties from the menu.

Basic
You can specify the following basic properties:
• Name
• Row
Specifies row on which formatting of data is to begin. Values are as follows:
– Unspecified
– Row number
– Next
Specifies that formatting of data is to begin on the next available empty line.
– Same
Specifies that formatting of data is to begin on the same line that is used for a preceding BMS
command.
• Column
Specifies the location of the left or right map margin. Values are as follows:
– Unspecified
– Column number
– Next
Specifies that the left or right map margin is to be placed in the next available column from the left or
right on the current line.
– Same
Specifies that the left or right map margin is to be established in the same column as the previous
map.

82 Developer for z/OS: Developing with Db2, CICS, and IMS

• Width
• Height
• Color
Select the color that you want. Use the Inherit option to take the value from the parent.

Presentation
You can specify the following presentation properties:
• Highlighting
Values are as follows:
– Inherit
The highlighting value is inherited from the parent.
– Off
– Underline
– Reverse
– Blink
• Transparency
Background transparency is determined by terminal capability. Values are as follows:
– Inherit
The transparency value is inherited from the parent.
– Yes
– No
• Border settings are as follows:
– Outline (box)
This option supersedes the other border options.
– Border over
– Border under
– Border left
– Border right

Attributes
You can specify the following map attributes:
• Validation
Settings are as follows:
– Must fill
– Must enter
– Trigger
A trigger field causes the terminal to transmit its contents if the operator moves the cursor out of the
field when it is primed.
– User exit
• Horizontal justification
Values are as follows:
– Unspecified

Developing CICS applications 83

 – Left
– Right
• Vertical justification
Values are as follows:
– First
– Last
• Cursor location
Values are as follows:
– Unspecified
– Yes
– No

Supported attributes
You can specify whether to support the following attributes:
• Symbolic map
Settings are as follows:
– Extended color
– Extended highlighting
– Field outlining
– Programmed symbol
Notifies the terminal that the map requires a specific symbol set.
– Double-byte SOSI
Indicates that double-byte characters are delimited by Shift-Out and Shift-In characters.
– Background transparency
Background transparency is determined by terminal capability.
– Validation
• Physical map
Settings are as follows:
– Extended color
– Extended highlighting
– Field outlining
– Programmed symbol
Notifies the terminal that the map requires a specific symbol set.
– Double-byte SOSI
Indicates that double-byte characters are delimited by Shift-Out and Shift-In characters.
– Background transparency
Background transparency is determined by terminal capability.
– Validation
• Extended attributes support
Values are as follows:
– No
– Yes

84 Developer for z/OS: Developing with Db2, CICS, and IMS

 – Map only

Advanced
You can specify the following control properties:
• Unlock keyboard
• Sound alarm
• Reset modified data tag
Resets the tag that indicates whether the map is modified.
• Print length
Values are as follows:
– Unspecified
– L40
– L64
– L80
– HONEOM
• Header
• Trailer
• TIAO prefix
• SOSI
This Shift-Out, Shift-In setting indicates that the map might contain a mixture of EBCDIC and DBCS
data.

Symbolic Map
You can specify the following properties that affect what information is included when a symbolic map is
generated:
Alternate Map Name
Enter or modify an alternative map name. This alternative map name is displayed in the generated
symbolic map. Symbolic map names must conform to the following conventions:
• The first character must be alphabetic: A-Z or a-z.
• Characters must come from the following set: A-Z, a-z, 0-9, $, @, #, - (hyphen) and _ (underscore).
• Length cannot exceed 30 characters.
Alternate Structure Starting Level
Enter or modify an alternative structure starting number. This value must be in the range 01 - 49.
The alternative structure start level defines the level at which the structure starts in the generated
symbolic map.
Attention: Modifications to the alternative map name and the alternative structure start level show
up in the Source page as a comment that looks similar to the following examples:

Alternate Map Name: Alternate Structure Starting Level:

*RDZ*DSECT3 altName mapName *RDZ*DSECT4 altLvl originalLvl mapName

where altName is the alternate map name where altLvl is the alternative structure start
that is set in Properties and mapName is the level that is set in Properties, originalLvl is the
name of the map. original structure start level, and mapName is the
map name.

Developing CICS applications 85

 Modifying or removing these properties by editing the comment does not reliably update the
Properties.
The following methods are more reliable:
• Use the Map Properties window.
1. On the Design page, right-click a BMS map and select Map Properties from the menu.
2. From the list of properties on the left, select Symbolic Map.
3. Update the Alternate Map Name or Alternate Structure Start Level field.
• Save, close, and reopen the BMS map. This action causes a full parse of the source.

Map set properties

To open the Map Set Properties window, by double-click a map set in the Outline view or right-click the
map set and select Map Set Properties from the menu.

Basic
You can specify the following basic properties:
• Name
• Map type
Values are as follows:
– Unspecified
– Symbolic
– Physical
– &SYSPARM
– Template
• Language
Values are as follows:
– Unspecified
– COBOL
– COBOL2
– C
– PL/I
– ASM
• Mode
Values are as follows:
– Unspecified
– Input
– Output
– Input and output
• Terminal
Values are as follows:
– ALL
– CRLP
– DISK
– TWX

86 Developer for z/OS: Developing with Db2, CICS, and IMS

 – 1050
– 2740
– 2770
– 2780
– 3780
– 3270-1
– 3270-2
– INTLU
– 3767
– 3770
– SCS
– 2980
– 2980-4
– 3270
– 3601
– 3653
– 3650UP
– 3650
– BCHLU
– 3770
• Color
Select the color that you want. Use the Inherit option to take the value from the parent.

Presentation
You can specify the following presentation properties:
• Highlighting
Values are as follows:
– Unspecified
– Off
– Underline
– Reverse
– Blink
• Transparency
Background transparency is determined by terminal capability. Values are as follows:
– Yes
– No
• Border settings are as follows:
– Outline (box)
This option supersedes the other border options.
– Border over
– Border under
– Border left
– Border right

Developing CICS applications 87

 • Cursor location

Supported attributes
You can specify whether to support the following attributes:
• Symbolic map
Settings are as follows:
– Extended color
– Extended highlighting
– Field outlining
– Programmed symbol
Notifies the terminal that the map requires a specific symbol set.
– Double-byte SOSI
Indicates that the double-byte characters should be delimited by Shift-Out and Shift-In characters.
– Background transparency
Background transparency is determined by terminal capability.
– Validation
• Physical map
Settings are as follows:
– Extended color
– Extended highlighting
– Field outlining
– Programmed symbol
Notifies the terminal that the map requires a specific symbol set.
– Double-byte SOSI
Indicates that the double-byte characters should be delimited by Shift-Out and Shift-In characters.
– Background transparency
Background transparency is determined by terminal capability.
– Validation
• Extended attributes support
Values are as follows:
– Unspecified
– No
– Yes
– Map only

Advanced
You can specify the following advanced properties:
• Validation
Settings are as follows:
– Must fill
– Must enter
– Trigger

88 Developer for z/OS: Developing with Db2, CICS, and IMS

 – User exit
• Store symbolic maps separately
• Unlock keyboard
• Sound alarm
• Reset modified data tag
Resets the tag that indicates whether the map has or has not been modified.
• Print length
Values are as follows:
– Unspecified
– L40
– L64
– L80
– HONEOM
• SOSI
This Shift-Out, Shift-In setting indicates that the map might contain a mixture of EBCDIC and DBCS
data.
• TIAO prefix

BMS Map Editor preferences

Use the Preferences window for the BMS Map Editor to customize some components of the editor. You
can also right click the design page and select Properties from the pop-up dialog.

General preferences
You can modify the following BMS Map Editor preferences:
• Make source page read-only
Prevents changes from being made directly to the source page.
• Show line numbers in source page
Displays line numbers in the left column of the Source page.
• Automatically open Outline view with editor
Opens the Outline view when the BMS Map Editor is started.
• Automatically open Properties view with editor
Opens the Properties view when the BMS Map Editor is started.
• Automatically open Palette view with editor
Opens the Palette view when the BMS Map Editor is started.
• Naming Conventions
Sets name prefixes for new maps, input fields, and password fields.
Related reference
“Design page preferences” on page 90
You can modify Design Page preferences in the Preferences window. These preferences pertain to the
attributes of the Design Page such as the background color, font types, and visual attributes.
“Source styles preferences” on page 92
You can modify source style preferences in the Preferences window. These preferences pertain to visual
attributes of the source page such as the background and foreground colors and comment color.
“Symbolic map preferences” on page 93

Developing CICS applications 89

 You can modify symbolic map preferences in the Preferences window. These attributes correspond to
specific changes made when the BMS symbolic map is generated.
“Bidirectional settings preferences” on page 90
You can modify the following bidirectional settings preferences in the Preferences window. These
preferences pertain to the display and ordering of bidirectional information, alignment and orientation
of bidirectional fields, and swapping of braces and numeric characters.
“Palette entries preferences” on page 91
You can modify the following options for palette entries in the Preferences window. These preferences
pertain to the colors, highlighting, intensity, and protection of fields created using the palette.

Design page preferences

You can modify Design Page preferences in the Preferences window. These preferences pertain to the
attributes of the Design Page such as the background color, font types, and visual attributes.

Preferences
In the navigation pane of the Preferences window, expand the BMS Map Editor > Design Page category.
You can modify the following Design Page preferences:
• Background color
Sets the background color of the Design canvas.
• Grid color
Sets the color for vertical and horizontal grid lines.
• Highlight fields
Places a box around fields. Select the box color that you want.
• Show rulers
Shows or hides the vertical and horizontal rulers.
• Font name
Sets the font used in the Design canvas.
Note: You should use only monospace fonts.
• Font size
Sets the font size used in the Design canvas (works in conjunction with the Zoom feature).
• Visually demonstrate blinking fields
Fields that are marked as blink are displayed with an italicized font.
Use the Preview pane, part of the BMS Map Editor, to evaluate style changes before applying them.

Bidirectional settings preferences

You can modify the following bidirectional settings preferences in the Preferences window. These
preferences pertain to the display and ordering of bidirectional information, alignment and orientation
of bidirectional fields, and swapping of braces and numeric characters.

Preferences
In the navigation pane of the Preferences window, expand the BMS Map Editor > Design Page >
Bidirectional Settings category.
Select Bidirectional options enabled to allow modification of the following bidirectional language
preferences. When this options is selected, the following set of bidirectional settings are made available in
the BMS editor toolbar. Selected preferences specify the default for each newly loaded map set.

90 Developer for z/OS: Developing with Db2, CICS, and IMS

Enable visual data ordering
Sets the display and editing of bidirectional data in the design form, the field properties window, and
the Properties and Outline views based on visual ordering of bidirectional text instead of the default
logical ordering.
Enable bidirectional settings button
Places a bidirectional settings button on the Design Page options toolbar with the caption "Toggle
bidirectional mode".
Default RTL orientation
Mirrors the orientation of map sets, simulating how the data is displayed on the remote system
terminal when the screen is reversed. This option allows a developer of bidirectional software to
design reversed (right to left) screens.
Default right alignment
Causes the fields added in the Design Page to be right-aligned. In the source file, right-aligned fields
are padded with leading spaces.
Enable symmetric swapping
Causes symmetric swapping for brackets, braces, and parenthesis to be done automatically according
to the currently used language. For example, in a right-to-left string, the parenthesis characters ( and )
are reversed. This option is needed only for Arabic support.
Enable numeric swapping
Causes numeric swapping for numbers from Arabic to Hindi and vice versa to be done automatically
according to the currently used language.

Palette entries preferences

You can modify the following options for palette entries in the Preferences window. These preferences
pertain to the colors, highlighting, intensity, and protection of fields created using the palette.

Preferences
In the navigation pane of the Preferences window, expand the BMS Map Editor > Design Page > Palette
Entries category.
You can modify the following options for the items in the Constant Fields and Variable Fields drawers:
• Default field name
• Color
Values are as follows:
– Blue
– Red
– Pink (magenta)
– Green
– Turquoise (cyan)
– Yellow
– Neutral (white)
• Intensity
Values are as follows:
– Dark
– Normal
– Bright
• Highlighting
Values are as follows:
– Off

Developing CICS applications 91

 – Reverse
– Underline
– Blink
• Protect
Values are as follows:
– Unprotected
– Protected
– Protected (automatic skip)
– Unprotected (numeric only)
• Protect (radio buttons)
– No
– Yes

Source styles preferences

You can modify source style preferences in the Preferences window. These preferences pertain to visual
attributes of the source page such as the background and foreground colors and comment color.

Preferences
In the navigation pane of the Preferences window, expand the BMS Map Editor > Source Styles category.
You can modify the following source style preferences:
• Background color
Sets the background color of the Source page editor. The default is white.
• Foreground colors
Sets foreground color for the following items:
– Default text
Color for default text (all text that is not included in one of the categories listed later in this section).
– Macro names
Color for DFHMSD, DFHMDI, and DFHMDF indicators.
– Attribute names
Color for attribute names.
– Strings
Color for regular strings, such as initial value.
– Comments
Color for comments.
Click Bold to further emphasize any specific foreground item, regardless of color.
Use the Preview pane to evaluate the style changes before applying them.

92 Developer for z/OS: Developing with Db2, CICS, and IMS

 Symbolic map preferences
You can modify symbolic map preferences in the Preferences window. These attributes correspond to
specific changes made when the BMS symbolic map is generated.

Preferences
In the navigation pane of the Preferences window, expand the BMS Map Editor > Symbolic Map
category.
You can modify the following symbolic map preferences:
Always generate alphanumeric data type, including fields defined as numeric
Select this option to generate all data types as alphanumeric when the symbolic map is generated. For
example, numeric fields that generate PIC 9(...) are generated as PIC X(...).
Generate aligned data structure
Select this option to generate a symbolic map as aligned. If this option is unselected, the symbolic
map is generated unaligned.
Generate data structure length field (for COBOL only)
Select this option to create a 01 entry in the generated symbolic map containing the length of the
entire data structure.

Generating Symbolic Map

You can generate a symbolic map in the z/OS Project view or the Remote Systems view.
To generate a symbolic map for either COBOL or PL/I, you need to perform the following tasks:
1. select the BMS file with the file extension as .bms. Then click Generate > Symbolic Map. The
Generate Symbolic Map for COBOL or Generate Symbolic Map for PL/I window displays.
• If the BMS file contains LANG=COBOL or LANG=PLI, the generation function is active.
• If the BMS file does not containsLANG=COBOL or LANG=PLI, the generation function is inactive.
2. In the Generate Symbolic Map window, select a folder as the target to keep the generated symbolic
map. Enter a file name in the Name field. Click OK. The symbolic map is generated and stored in the
folder. A message will inform you when the generaion is completed.
• If the symbolic map is generated from a local COBOL file, the file extension is .CPY.
• If the symbolic map is generated from a local PL/I file, the file extension is .INC.

Creating BMS map set JCL

You can use Job Control Language (JCL) to install physical and symbolic description maps. You can use
the BMS Editor to generate the JCL for a BMS map set in an existing MVS subproject on the remote z/OS
system. For example, the output can be a COBOL copybook and binary object.
Restriction: You can generate the JCL only to an existing partitioned data set (PDS). Create a PDS on the
remote system, if you have not yet done so.
To create the JCL for a map set:
1. Right-click the .bms map set file name in the MVS subproject folder.
2. Select Edit Associated Property Group.
3. on the BMS Settings page, specify the destination library. Set the other options as you want and save
the changes.
4. Right-click the .bms map set file name.
5. Select Generate JCL > For Assemble or Generate JCL > For Assemble Link.
6. In the input window, specify the target PDS and the member name. You can also set a different job
name.

Developing CICS applications 93

 7. Click OK to complete the generation process.
If the member name already exists, you are prompted to overwrite the member.
If the target PDS does not exist, an error message is returned.
To submit the JCL:
1. Right-click the generated JCL file name in the PDS.
2. Select Edit Associated Property Groupand set the values that you want.
3. Right-click the JCL file name and select Submit.
You can find the output in the library that you specified in BMS Settings.
You can test the map in the CICS region with a Send Map command.
Related information
Determining the source of generated JCL

Bidirectional support
The BMS Map Editor supports bidirectional options for Arabic and Hebrew maps. Some features apply
only to Arabic maps, as indicated in the documentation. By default, bidirectional support is not enabled.
For additional information about specific issues related to bidirectional functions and support, see
“Bidirectional considerations” on page 97.
Note: The following conditions apply to the BMS Map Editor bidirectional support:
• All bidirectional maps must have UTF-8 text file encoding.
• The Copy and Paste functions are not supported for bidirectional data.

Enabling bidirectional support

To work with Arabic and Hebrew maps, you must enable bidirectional support in the BMS Map Editor
Preferences window. This step adds a bidirectional mode button to the Design page and options to the
Design menu. Status bar information is given when directly editing a field.
Enable the bidirectional settings that you want before you close the Preferences window.

Bidirectional preferences
The following bidirectional settings are available.
• Enable visual data ordering
Sets visual ordering of text, instead of the default logical ordering.
• Enable bidirectional settings button
Places a Bidirectional settings button on the Design page options bar
• Default RTL orientation
Sets a right-to-left text flow in the display.
• Default right alignment
Causes fields added in the Design view to be right-aligned. In the source file right-aligned fields are
padded with leading spaces.
• Enable symmetric swapping
Resets swappable characters. For example, in a right-to-left string, the parentheses characters ( and )
are reversed.
• Enable numeric swapping

94 Developer for z/OS: Developing with Db2, CICS, and IMS

 Sets an inversion of the screen, which causes Hindi numerals to be replaced by their Arabic
counterparts and the Arabic numerals to be replaced by their Hindi counterparts.
When selected in the Preferences window, the map options are in effect for each newly loaded map set.

Visual input key functions

Visual input key functions allow visual input in input fields and the initial values for labeled input fields.
Table 7 on page 95 shows the key functions and key combinations involving the number pad that are
available if you enable visual data ordering in the preferences.

Table 7. Visual input key functions

Key
Key function Description combination
Push Starts a segment of reversed text and reverts the direction of the Shift+NumLo
cursor. Text is pushed toward the end of the field, and the cursor ck
remains stationary.
EndPush Terminates the current segment of reversed text. The cursor skips Shift+/
to the end of the segment, and its direction is restored.
AutoPush Enables the Push and EndPush functions to be automatically Alt+/
invoked, based on the actual text entered.
FieldReverse Reverses the typing direction and the direction of functions such Alt+NumLock
as Backspace, Delete, Home, and End. However, the function does
not visually invert the contents of the field.
Switch between Switches numerals input between Arabic and Hindi. Alt+*
input of Arabic/
Hindi Numerals

Status bar information

When you click a map set item in the Design canvas, the following bidirectional information is displayed in
the status bar:
• Orientation of the current map set
Status displays either LTR (left-to-right) or RTL.
• Autopush flag
Status displays A when Autopush is enabled (visual mode only).
• The current editing mode
The following mode labels can be displayed independently or in combination.
– None
No bidirectional mode options are enabled.
– Push
Push mode is enabled.
– FldRev
Field Reverse is enabled.
– Hindi
Input is Hindi numerals (Arabic only).

Developing CICS applications 95

 Bidirectional Web page generation options
When generating a JavaServer Faces (JSF) Web page from a BMS map set file, the following bidirectional
output options are available:
• Enable visual data ordering
Creates a visual JSF page with text fields that support visual input.
• Handling Arabic text
Select this option when generating JSF pages to be used in Arabic applications.
In order to have a JSF page layout that is similar to the map set Preview layout, the following
options settings must match the bidirectional preferences used to create the map set. See “Bidirectional
preferences” on page 94 for additional information.
• Visual BMS Map
• Right-to-left orientation
• Symmetric Swapping
• Numeric Swapping
The following features are enabled if you selected visual data ordering when setting the bidirectional
preferences:
• Copy/Paste bidi support
Enables copy/paste to and from the input fields in the JSF page.
• Hints
Enables hints to be displayed beside the input fields in the JSF page.
• Status Line
Enables display of input field status in the browser status bar.
Important: If you select multiple bidirectional attributes while generating a JSF page, script errors might
prevent the JSF page from being executed. To clear such script errors, you must manually edit the JSF
page.

Bidirectional support for BMS visual editing

This topic contains additional information about bidirectional support for the BMS editor.
BMS files are stored on the remote system in visual format. The default bidirectional format for Developer
for z/OS is Smart Logical. You must associate the correct bidirectional conversion tables in the file system
mapping for .bms files, because the default setting does not assume bidirectional conversion.
Visual editing of bidirectional data is enabled after Bidirectional options enabled is selected in
Preferences. To enable this preference, select BMS Map Editor > Design Page > Bidirectional Settings.
Even after visual editing is enabled, bidirectional data is saved in .bms files in Smart Logical format. This
format is very similar to standard Windows logical format, but is based on extensive use of bidirectional
LRM markers.
To edit bidirectional data in the Smart Logical format, use the z Systems LPEX Editor. The LPEX editor
provides a special visual line for this purpose. To access the visual line in LPEX, use the menu to select
Source > Visual edit line, or use the Alt+= key combination. For more information about z Systems LPEX
bidirectional support, see the LPEX documentation.
To edit bidirectional data in the BMS editor Source view, use the Ctrl+NumLock key combination on the
selected line.
Related reference
“Bidirectional settings preferences” on page 90

96 Developer for z/OS: Developing with Db2, CICS, and IMS

You can modify the following bidirectional settings preferences in the Preferences window. These
preferences pertain to the display and ordering of bidirectional information, alignment and orientation
of bidirectional fields, and swapping of braces and numeric characters.

Bidirectional array alignment

In the bidirectional settings, this option is selected by default and determines whether the structure fields
are created from left to right or from right to left.
In LTR Mapset, this structure is created with the same orientation as the map set by selecting this default
option; for example, LTR structure in LTR map set
Figure 1 on page 97 is an example of the array settings.

Figure 1. Example of Array Settings

This structure is created with an orientation opposite to map set when this option is not set to the default;
for example, RTL structure in LTR map set.

Bidirectional considerations
To work with bidirectional text, you must enable bidirectional support. When working with bidirectional
text, you might encounter the following issues.

Visual mode display in the Source page

When working in the Source page editor environment, you can use the Shift+NumLock key combination to
enable or disable the Visual display format for bidirectional data.

Developing CICS applications 97

 Visual mode text entry in the Source page
In Windows, you can directly enter English data in the Source page editor. However, if you are in Visual
mode, you cannot directly type Arabic or Hebrew data in the Source page editor.
To enter or edit bidirectional data when in Visual mode, use the Ctrl+NumLock key combination to open a
pop-up Source page editor. This editor enables Visual ordering of text and Visual input key functions.
If you have selected text in the Source page when you open the editor, it is displayed as initial data in the
pop-up editor. If no text is selected, the editor does not display any initial data.
The data from the Visual editor window is saved in Visual format and placed at the cursor position in the
Source page. If text is selected in the Source page, it is overwritten with the input from the Visual editor.

Error tracing
If general logging is enabled, you can trace bidirectional function errors by checking the log files.
The following bidirectional functions are logged:
• Screen Reverse
• Numerical Swapping
• Symmetrical Swapping
• Push and Autopush
• Switching between Hindi and Arabic numerals
• Field Reverse
• Switching between Visual and Logical modes

Arabic considerations
For Arabic content, the following Seen tail character limitations exist:
• In BMS map set files that are uploaded to the remote system, Seen tail characters are displayed as Seen
3/4 (without tail) in emulators such as Personal Communications or Host On-Demand.
• When downloading a BMS map set file from the remote system, Seen tail characters are not read
correctly.
You can use the BMS Map Editor to replace the empty tail character. Select the Source tab to directly
edit the map code. Put a space character in the location of the empty tail character.

98 Developer for z/OS: Developing with Db2, CICS, and IMS

Developing IMS applications
Learn how to develop IMS applications by using the product.
Related information
Software Product Compatibility Reports

Designing MFS messages for IMS with the MFS Editor

MFS Screen Design is a function of the MFS Editor. This tool allows for visual creation and modification
of MFS messages and device format definitions. By using the MFS Editor, you can create Information
Management System (IMS) applications that deal with simple logical messages instead of device-
dependent data.
MFS functions as an interface between the format of messages at a terminal and the I/O formats in
your program. By using MFS, you can create well-designed screens that improve operator efficiency and
accuracy. With the MFS Editor, you can create and modify MFS messages and device format definitions
visually.

Editor features
The Palette view of the editor provides both click-and-drop and drag-and-drop access to the format
definition components. MFS macros are added and edited using the Outline and Properties views.
The MFS Editor provides the following pages for designing a device format definition.
• Design
Contains the Design canvas and display customization options, including map filtering. More formatting
and display options are opened in the Properties view when a MFS macro is selected.
• Source
Provides a text editor for editing the MFS source code directly.
• Preview
Provides terminal-style and web preview modes of MFS source code.

Object properties
To see the properties of an object, select the item in the Outline view. The properties are displayed in the
Properties view. You can also view and configure a format definition component by using the Design page
menu.

Creating format definitions and messages

You can create device format definitions and associated message definition files using the available
wizards. The MFS Editor is typically accessed within the z/OS Projects perspective.
You can use the New MFS Device Format wizard to create format definition files within an existing local
project, in a remote MVS subproject, or in an existing partitioned data set on a remote system. You can
also use the MFS Editor to work with existing remote .mfs files.

Creating a device format definition

The New MFS Device Format wizard guides you through the creation of a device format definition.
Note: The format definition file can be created directly as a member of an existing partitioned data set on
the remote system. You can then add the file to an existing MVS subproject.
To create a format definition file:
1. Click File > New > Other. You can also use the keystroke combination Ctrl+N.

© Copyright IBM Corp. 1992, 2024 99

 2. Expand the z/OS Development category.
3. Click MFS > MFS Device Format.
4. Click Next.
5. On the MFS File Location page, select a local project or a partitioned data set on the remote system.
This location is where the MFS format definition file is to be created.
6. In the Name field, type a file name for the format definition.
7. To set specific device format attributes, click Next.
8. You can specify the following device format attributes:
Device format name
Type the device format name. This parameter is required. The length is from one to six
alphanumeric characters. This name uniquely identifies this statement, and is referred to by
message descriptors in the SOR= operand of MSG statements.
Description
The description is added to the MFS source code prologue as a comment. This input is optional.
Device type
Specify a 3270 display or printer as the device type. Corresponds to the device attribute, TYPE=.
This parameter is required
Width
Specify the maximum line width for this DEV type as one of the following values:
• Number of print positions per line of input or output data
• Number of punch positions per card of input or output data
• Card width for card reader input data
This parameter is optional and is valid for device types 3270P.
Substitution
Specify the character that MFS uses to replace any X'3F', or null, characters in the input data
stream. Corresponds to the device attribute, SUB=. The character must be specified in the form
X'hh' or C'c', where "hh" is a hexadecimal value and "c" is a character value. This parameter is
optional and is valid for device types 3270 and 3270-An.
Format type
Specify the format as input-only (INPUT), output-only (OUTPUT), or both (INOUT).
Compression
Select the compression from the drop-down list:
• SHORT- MFS removes trailing blanks from short fields.
• FIXED - MFS removes trailing blanks from fixed-length fields.
• ALL - MFS removes trailing blanks from all fields that are presented by the application program.
This setting is optional.
To add the new format definition file to an existing MVS subproject, select Add to MVS subproject
checkbox and then select an MVS subproject from the list.
The list is empty if no z/OS Projects and MVS subprojects are defined for the workspace.
9. Click Finish.
The device format file is created and displayed in the specified location on the local or remote system.

Creating an MFS message definition

The New MFS Message Definition wizard guides you through the creation of a message definition, which
is appended to an existing MFS device format definition file.
To create a MFS message definition:

100 Developer for z/OS: Developing with Db2, CICS, and IMS
1. Click File > New > Other. You can also use the keystroke combination Ctrl+N.
2. Expand the z/OS Development category.
3. Click MFS > MFS Message Definition.
4. Click Next.
5. On the Select the MFS Device Format file page, select the target device format file.
MFS Message Definitions are appended only to MFS device format files with all of the following
characteristics:
• The MFS device format file exists in a local project or PDS that has a z/OS file system mapping to an
extension of MFS.
• The MFS device format file contains correctly formatted MFS source.
• The MFS device format file MFS source contains no parse or syntax errors.
If the file you select in the wizard does not meet all these characteristics, then an error message is
displayed.
6. Click Next.
7. Specify the following message definition attributes:
Message name
Specify the message name. Valid names are from one to eight characters. This entry is required.
Description
The description is added to the MFS source code prologue as a comment. This input is optional.
Type
Select the message type from the drop-down list. Valid values are Input and Output.
Corresponds to the message parameter, TYPE=. This parameter is required.
Fill
Specify the fill character. This input is optional and is valid only for messages of type output.
Corresponds to the message parameter, FILL=. If you specify a fill type of C'c', replace 'c' with
the character to use as the fill value. For example, to specify a fill value of periods, provide the
string: C'.'.
Paging
Specify whether operator logical paging or forward and backward paging, is provided for
messages that are edited by using this control block. The default is for only forward paging of
physical pages to be provided. Corresponds to the message parameter, PAGE=. This option is
available only for the output type and is optional.
Ignore
Specify whether device features are to be ignored for this device. Corresponds to the IGNORE
keyword specified in the SOR= message parameter. This parameter is optional.
8. To specify more message attributes such as the logical page name, segment name, and message
fields, click Next.
9. On the Message Attributes page, specify the following attributes:
Logical page name
Specify a name to uniquely identify this statement. The length is from one to eight alphanumeric
characters. This input is optional. Regardless of whether a logical page name is specified or not,
the MFS message is always created with an LPAGE statement.
Device page name
Select the DPAGE name from the drop-down menu that defines the device format for this logical
page. Only those device fields that are defined in the DPAGE are available to add as message
fields to the logical page. This input is required
Segment name
Specify the segment name. Valid names are from one to eight characters in length. This input is
optional.

Developing IMS applications 101

 Graphic
Mark this checkbox to specify that IMS is to perform uppercase translation on the segment, if
the destination definition requests it. Corresponds to the segment parameter, GRAPHIC=. This
parameter is optional and valid only for input messages.
10. To add message fields, enter values for the following fields, and then click Add. Repeat this step for
each field you want to add to the message.
Message field
Specify the field name. At least one message field must be specified for a MSG statement.
Literal
Specify the literal value to be inserted into the input message. This input is required if no length is
specified for the message field.
Device field names
Select the device field to associate with the message field. The list is populated with only those
device fields that are defined in the specified device page. This input is required when a literal is
specified on a message field.
Length
Specify the message field length. Corresponds to the message field parameter, LTH. This input is
required if no length is specified for the message field.
Justification
Select the field justification, either right or left, from the drop-down list. Corresponds to the
message field parameter, JUST=, and is optional input.
11. Click Finish.
The message definition is created and displayed in the Outline view.

Visually editing an MFS device format

The Design canvas, Palette view, Outline view, and Properties view together provide all the tools that are
needed to edit the macros and fields in an MFS device format visually.
The Design canvas provides the editing space for fields to be graphically represented. Fields can be added
to the active physical page displayed in the Design canvas by drag-and-drop or select-and-click from
the Palette view. The Outline view allows high-level navigation through the layers of the MFS hierarchy,
while the Properties view provides an editable form where the properties of each MFS macro can be
modified and updated. The Source page generates and modifies source automatically for each change
that is performed in these different views.

Palette view
The Palette view provides Design page selection tools and device format definition components.
The Palette view includes three drawers with design tools: Default, Basic, and Advanced. Click a drawer
label to show or hide the item list. The Default drawer contains tools that are used for editing the MFS
files, while the Basic and Advanced drawers provide MFS elements that can be added to the design page.

Add format definition components to the design canvas

You can add items from the Palette view to the Design canvas in two ways:
• Select an item from the Palette; it is highlighted. Draw the element on the Design canvas by clicking and
dragging until the correct sized rectangle is drawn.
• Select an item from the Palette and drag it onto the Design page. When you release the cursor, the
element is created.
After you add an item to the Design canvas, the element is listed in the Outline view, and the
editable properties are displayed in the Properties view. The MFS source code for the element is also
automatically generated. You can view the MFS source by selecting the Source page tab at the bottom of
the editor.

102 Developer for z/OS: Developing with Db2, CICS, and IMS
The design page displays only the lowest level MFS element that is defined in the device format definition.
When an element is added to the design canvas, it updates the source to reflect the addition of the
element. Since added elements immediately update the source, elements added to the design page must
stay in valid MFS hierarchy order. It is invalid for an element that is higher in the hierarchy to be added "on
top" of a lower element in the hierarchy. For example, after an MFS device page is added to a MFS device,
a division cannot be added from the palette view since it is higher in the MFS hierarchy. Depending on the
structure of the device format file, some MFS elements are invalid to add through the Palette view.
Whenever adding an element is invalid, a red prohibited icon is displayed when you hover the cursor over
the design canvas to add an element.
Physical pages are the lowest container of the MFS hierarchy that is displayed on the design page. After a
physical page is added to a device format file, then no container higher in the MFS hierarchy can be added
through the Palette view for that device. Multiple physical pages can be added to the design canvas with
the Palette view, but only if the parent device page has Multiple physical pages checkbox marked in the
Properties view.
It is valid MFS syntax to allow more than one of some constructs. If you want to add more MFS device,
divisions, or device pages, subsequent MFS elements of these types can be created through the Outline
view.

Customizing the Palette view

To add or change drawers or definition components, right-click the palette and select Customize.
To customize a component or drawer, select it from the list to the left and modify the properties that are
listed to the right. The following drawer and component display options can be customized.
Name
The name of the drawer or component that is displayed in the palette
Description
Descriptive text that is displayed when you hover the mouse pointer over the palette item
Hide
Marking this checkbox prevents the item from being displayed in the palette
You can also specify the following drawer options for existing and new drawers.
Hide
The drawer is not displayed in the Palette view.
Open drawer at start-up
The drawer is expanded when the Palette view is shown.
Pin drawer open at start-up
The drawer remains pinned open unless you click the drawer to close it.
You can also add new drawers by clicking the New button to the upper left, rearrange the ordering of
drawers and components by clicking the Move Up and Move Down buttons, and delete components by
selecting the component and clicking Delete. You cannot delete the initial drawers.
Changes that you make to the Palette view through the Customize dialog are kept across the workspace.
You can change the default display properties for the palette entries from the “Preferences” on page 125
dialog.
Related information
“Design page in MFS Editor” on page 119

Developing IMS applications 103

 The Design page contains the Design canvas and an associated Palette view, where you can visually edit a
format definition.

Default drawer
The Default drawer contains the Select and Marquee tools that come with Eclipse for editing files that
are based on the Graphical Editing Framework (GEF), such as MFS files in the MFS editor. You can use
these tools to select and move items in the Design page.

Basic drawer
The Basic design palette drawer contains MFS elements that can be added to the device format
definition.

MFS Device
Use the MFS Device palette item to add devices to a format definition file. This action is equivalent to
creating the DEV statement.
When you add a device to the design canvas, the Outline view is updated.
Note: If a device is already added to the format, then subsequent devices must be added through the
Outline view.
To create a device in the design canvas:
1. Select the MFS Device icon in the palette.
2. Click the left mouse button at any location in the design canvas. The Outline view is updated with a
device icon, and the Properties view is opened.
3. In the MFS Device Properties window, you can specify properties for the device.
Note: When you first create a device, you can select from all supported formats provided in the New
Device dialog. After you resolve the device, in the Properties view, only those device formats that
are similar are available in the drop down menu. For example, if you specify the device type to be
3270P, then in the Properties view after resolution, only device types 3270P, 3270P,1 and 3270P,2
are selectable from the drop-down menu.
Related information
“Device properties” on page 110
When a device is selected in the Outline view, or the DEV statement in the MFS source is selected, the
device properties are displayed in the Properties view.

MFS Division
Use the MFS Division palette item to create divisions in a format definition file. This action is equivalent to
creating the DIV statement.
When you add a division to the design canvas, the Outline view is updated.
Note: If a division exists for the device, then subsequent divisions must be added through the Outline
view.
To create a division in the design canvas:
1. Select the MFS Division icon from the palette.
2. Click the left mouse button at any location in the design canvas. The Outline view is updated with a
device icon, and the Properties view is opened.
3. In the MFS Division Properties window, you can specify many properties.
Related information
“Division properties” on page 112

104 Developer for z/OS: Developing with Db2, CICS, and IMS
When a division is selected in the Outline view, or the DIV statement in the MFS source is selected, the
division properties are displayed in the Properties view.

Device Page
Use the Device Page palette item to create device pages in a format definition file. This action is
equivalent to creating the DPAGE statement.
When you add a device page to the design canvas, the Outline view is updated.
Note: If a device page already exists for the device, then subsequent device pages must be added through
the Outline view.
To create a device page in the design canvas:
1. Click the Device Page button in the palette.
2. Click the left mouse button at the location that you want in the design canvas. The Outline view is
updated with the device page icon, and the Properties view is opened.
3. In the MFS Device Page Properties window, you can specify many different properties.
Related information
“Device page properties” on page 113
When a device page is selected in the Outline view, or the DPAGE statement in the MFS source is selected,
the device page properties are displayed in the Properties view.

Physical page
Use the Physical Page palette item to create physical pages in a format definition file.
As you add physical pages to the design canvas, the Outline view is updated. Physical pages are added to
the device page that is active, or brought to the front.
Note: When you create a device page for the first time, it is automatically resolved with the first physical
page created. You can view the physical page, and other created MFS elements, in the Outline view.
To create a physical page in the design canvas:
1. Click the Physical Page button in the palette.
2. Click the left mouse button at the location that you want in the design canvas.
To change the properties of the physical page, use the Properties view.
To bring a device page to the front:
1. In the Outline view, right click the MFS Device Page that you want to bring to the front.
2. In the right-click menu that opens, select Bring to Front. This action lists the MFS device page and the
physical pages and device fields below it in the hierarchy at the bottom of the Outline view.
Now when you add a physical page, it is automatically added to this device page. You must repeat these
steps if you want to add a physical page to a different device page.
Multiple physical pages can be created for a device page only when the device page properties have the
Multiple physical pages check box marked. Adding physical pages through the outline view or palette
view is disabled until this checkbox is marked.
Related information
“Physical page properties” on page 113
When a physical page is selected in the Outline view the physical page properties are displayed in the
Properties view.

Label field
The label field is a protected normal field.
To create a label field in the design canvas:
1. Click the Label field icon in the palette.

Developing IMS applications 105

 2. Click the left mouse button at the location that you want in the design canvas. The label field is created
at the location and is directly editable.
3. Type a literal for the label field.
Note: Literals are required for label field source to be correctly generated.
To change the properties of a label field, use the Properties view.
Related information
“Field properties” on page 113
When you select a field through the Outline view, on the design canvas, or a DFLD macro in the Source
page, the properties that are associated with the field are populated and displayed in the Properties view.

Input field
The input field is an unprotected normal field.
As you add fields to the design canvas, they are displayed in the Outline view. To create an input field in
the design canvas:
1. Click the Input field icon in the palette.
2. Draw the field in the design canvas where you want to place it.
Note: Input fields are required to have a label, or DFLDNAME for MFS source to be correctly generated.
To change the properties of an input field, use the Properties view.
Related information
“Field properties” on page 113
When you select a field through the Outline view, on the design canvas, or a DFLD macro in the Source
page, the properties that are associated with the field are populated and displayed in the Properties view.

Output field
The output field is an unprotected normal field.
As you add fields to the design canvas, they are displayed in the Outline view. To create an output field in
the design canvas:
1. Click the Output field icon in the palette.
2. Draw the field in the design canvas where you want to place it.
Note: Output fields are required to have a label, or DFLDNAME for MFS source to be correctly
generated.
To change the properties of an output field, use the Properties view.
Related information
“Field properties” on page 113
When you select a field through the Outline view, on the design canvas, or a DFLD macro in the Source
page, the properties that are associated with the field are populated and displayed in the Properties view.

Password field
The Password field in the palette is an unprotected normal field. This field is the location of the IMS
password field for input messages.
As you add fields to the design canvas, they are displayed in the Outline view. To create a password field
in the design canvas:
1. Click the Password field icon in the palette.
2. Draw the field in the design canvas where you want to place it.
Note: Passwords cannot have a length greater than eight for MFS source to be correctly generated.
Alternatively, if you created an input field, you can mark the Password check box in the input field
properties to make the input field a password field.

106 Developer for z/OS: Developing with Db2, CICS, and IMS
To change the properties of a password field, use the Properties view.
Related information
“Field properties” on page 113
When you select a field through the Outline view, on the design canvas, or a DFLD macro in the Source
page, the properties that are associated with the field are populated and displayed in the Properties view.

System Message
The System Message field is an unprotected normal field of length 79.
As you add fields to the design canvas, they are displayed in the Outline view. To create a system
message field in the design canvas:
1. Click the System message field icon in the palette.
2. Draw the field in the design canvas where you want to place it.
Note: System message fields are created with length of 79. If the location on the design page you
select does not have 79 available bytes, then the field is wrapped to the next line.
To change the properties of a system message field, use the Properties view.
Related information
“Field properties” on page 113
When you select a field through the Outline view, on the design canvas, or a DFLD macro in the Source
page, the properties that are associated with the field are populated and displayed in the Properties view.

Advanced drawer
The Advanced design palette provides specific items for inclusion in a device format definition. These
items require some configuration before you can add them to a device format definition.
The Advanced palette includes the Table tool.
Click the Advanced drawer label to show or hide the item list. You can also change the order of options by
using the Customize palette menu option.
To add an item to the design canvas, complete the following steps:
1. In the Palette view, click the item that you want. The item is highlighted.
2. Move the cursor to the design canvas. It is not necessary drag the item to the design canvas.
3. Click the location that you want on the design canvas. If a location that you want is not valid, the item
is not added to the design canvas.
4. Set the required properties in the configuration wizard.
As you add items to the design canvas, the Outline view is updated. The Properties view shows the
specific settings for each item.
Related information
“Table” on page 107
Use the Table tool to create a table. This action is equivalent to coding the DO statement on a device field.

Table
Use the Table tool to create a table. This action is equivalent to coding the DO statement on a device field.
You can modify settings for an existing table by using the Design page tools.
To place a table:
1. Click the Table button in the Advanced palette.
2. Click the left mouse button at the location that you want in the design canvas. An invalid icon is
displayed if the location is not valid.
The Create New Table wizard opens.

Developing IMS applications 107

 Create New Table wizard
1. On the first page, specify the number of rows and columns.
2. Click Next. The second page of the wizard opens, where you can configure the table columns.
3. Specify the following table properties:
• Create header separator row
Mark this checkbox to specify whether a row is to be placed between the header row and the table
data.
• Filler character
Enter a fill character to use to fill the separator row.
4. To create more columns, click Add. The Add Column window opens. You can specify the following
column properties:
• Column header
Enter a column name.
• Width
Enter the column width by number of characters.
• Field name prefix
Enter a prefix for the field names within the new column.
• Input
Select this checkbox to create an input field. Clear the checkbox to create a label field.
5. To change preferences for a specific column, click Edit. The Edit Column window opens. It contains
the same fields as the Add Column window.
6. To change the column position in the table, click the Up and Down buttons. The higher the column in
the list the farther to the left the column is drawn on the design canvas.
7. Click Finish. The table is drawn on the design canvas.
Related information
“Design page in MFS Editor” on page 119
The Design page contains the Design canvas and an associated Palette view, where you can visually edit a
format definition.

Outline view
The Outline view displays format and message information for a specific MFS file in a hierarchical
presentation.
When you select an item in the Outline view, that item is highlighted in the design canvas and the Source
page. The property value information for the item is shown in the Properties view.
The Outline view is displayed by default. You can change the MFS Editor preferences to hide this view.

Navigating the Outline view

The Outline view displays the hierarchy of the MFS format and MFS messages in the file.
For MFS device formats, the top-to-bottom hierarchy that is displayed is: format, device, division, device
page, physical page, device fields.
For MFS message definitions, the top-to-bottom hierarchy that is displayed is: message, logical page,
segment, and message fields.
You can collapse and expand each of these levels to view or hide the levels below.

108 Developer for z/OS: Developing with Db2, CICS, and IMS
Adding device format and message components
When you select a device format or message component in the Outline view, you can add new child
components from the right-click menu. For example, if you select a logical page, you can create a segment
by selecting New segment from the right-click menu.
You cannot create or remove the top level of the MFS device format hierarchy or the MFS message
definition. In the Outline view, these are the format and message components.

Right-click menu and keyboard shortcuts

The following table lists the right-click menu options and the corresponding keyboard combinations:

Table 8. Outline view options

Option Keyboard shortcut
Undo - Performs an undo of the last action in the Ctrl+Z
design canvas or the Outline view.
Redo - Redoes the last action in the design canvas Ctrl+Y
or Outline view.
Cut - Cuts the selected MFS component. This Ctrl+X
action modifies the MFS source to remove the
MFS component and any child component from the
source. The section of source is placed wherever
the MFS component is pasted in the Outline view.
Copy - Copies the selected MFS component and Ctrl+C
any child components to the clipboard. This action
is equivalent to selecting and copying the MFS
component and any child components from the
Source page.
Paste - Pastes the MFS component and any child Ctrl+V
components that are copied to the clipboard into
the MFS source. The paste action is only active
when some MFS component is copied to the
clipboard, and a parent component is selected.
This action is equivalent to pasting MFS source in
the Source page.
Delete - Deletes the MFS component and any child Delete
components. You cannot delete MFS format or MFS
message components because they are the top-
level components of the hierarchy.
Save - Saves the MFS device format file. Ctrl+S
Print Ctrl+P
Show Map - Shows the selected physical page
in the design canvas. The physical page displays
only if it is in the scope of the design canvas. For
example, if there is more than one device in the
MFS format, then only those physical pages that
are part of the device that is in the front have this
option.
Hide Map - Hides the selected physical page in the
design canvas. The physical page can be hidden
only if it is in the scope of the design canvas.

Developing IMS applications 109

 Table 8. Outline view options (continued)
Option Keyboard shortcut
Bring to front - Bring to the front places a
particular component that is displayed on top of
the design canvas. Bring to the front changes the
component on top of the design canvas only if there
is more than one of the selected components. The
component that is to the front is displayed at the
bottom of the outline view.

Important: The Undo and Redo options apply to operations performed in either the Outline view or the
design canvas. If you cut a field in the design canvas, for example, the Undo Cut option is enabled in the
Outline view right-click menu.
Related information
“Design page in MFS Editor” on page 119
The Design page contains the Design canvas and an associated Palette view, where you can visually edit a
format definition.
“Source page” on page 122
Use the Source page to view and modify the MFS source statements directly in a text editor.
“Properties view” on page 110
The Properties view displays property value information for a component that is selected in the design
canvas or the Outline view.
“Preferences” on page 125
You can customize some components of the MFS editor through the MFS Editor Preferences page.

Properties view
The Properties view displays property value information for a component that is selected in the design
canvas or the Outline view.
The Properties view is displayed by default. You can change the MFS Editor preferences to hide this view.
Related information
“Preferences” on page 125
You can customize some components of the MFS editor through the MFS Editor Preferences page.

Format properties
When a format is selected in the Outline view, or the FMT statement in the MFS source is selected, the
format properties are displayed in the Properties view.
The following are the editable properties that can be modified for the format.
Name
Specify an optional name to uniquely identify this format statement. The length is from one to eight
alphanumeric characters.

Device properties
When a device is selected in the Outline view, or the DEV statement in the MFS source is selected, the
device properties are displayed in the Properties view.
The Properties view contains several tabs that contain properties that can be set for the device.

Basic properties
The following are the properties available on the Basic tab and in the New Device dialog that opens when
you select to create a device through the Outline view.

110 Developer for z/OS: Developing with Db2, CICS, and IMS
Name
Specify an optional device name that uniquely identifies this statement. The length is from one to
eight alphanumeric characters.
Width
Specify the maximum line width for this DEV type as one of the following values:
• Number of print positions per line of input or output data
• Number of punch positions per card of input or output data
• Card width for card reader input data
This parameter is optional and is valid for device types 3270P.
Type
Specify a 3270 display or printer as the device type. Corresponds to the device attribute, TYPE=. This
parameter is required
Substitution
Specify the character that MFS uses to replace any X'3F', or null, characters in the input data stream.
Corresponds to the device attribute, SUB=. The character must be specified in the form X'hh' or C'c',
where "hh" is a hexadecimal value and "c" is a character value. This parameter is optional and is valid
for device types 3270 and 3270-An.
DSCA
Specify the default system control area for output messages that use this device format. Corresponds
to the device attribute, DSCA=. This parameter is optional.
The following properties are also listed on the Basic properties tab:
Print lines
Specify the number of lines to be printed when formatting output messages. Corresponds to the
device parameter, PAGE=. This input is optional and valid only for devices that are of type 3270P.
Line format
Specify from the drop-down menu the format control for output messages. Corresponds to the device
parameter, PAGE=. This input is optional and valid only for devices that are of type 3270P.

Advanced properties
The following properties are editable on the Advanced tab.
System message
Select a device field name that is defined in the format from the drop-down menu as the device
field to display IMS system messages. Corresponds to the device parameter, SYSMSG=. This input is
optional and is valid only with 3270 device types.
Pen
Specify an input device field name that is defined in the format. Corresponds to the device parameter,
PEN=. This input is optional and is valid only with devices that are of type 3270.
Card
Specify an input device field name that is defined in the format. This property specifies that the device
has a 3270 operator identification card reader. Corresponds to the device parameter, CARD=. This
input is optional and is valid only with 3270 device types.

Features properties
The following properties are editable on the Features tab.
Card
Mark this checkbox to set the property that specifies that the device has a 3270 operator
identification card reader. Corresponds to the device parameter, FEAT=CARD. This input is optional
and is valid only with devices that are of type 3270.

Developing IMS applications 111

 Pen
Mark this checkbox to specify the presence of the selector light pen detect feature. Corresponds to
the device parameter, FEAT=PEN. This input is optional and is valid only with devices that are of type
3270.
Ignore
Mark this checkbox to specify that device features are to be ignored for this device. Corresponds to
the device parameter, FEAT=IGNORE. This input is optional.
Function Keys
Mark this checkbox to specify that the program uses program function keys. Corresponds to the
device parameter, FEAT=PFK. This input is optional and is valid only with devices that are of type
3270.
Data Entry Keyboard
Mark this checkbox to specify that the device uses the keyboard entry feature. Corresponds to the
device parameter, FEAT=DEKYBD. This input is optional and is valid only with devices that are of type
3270.
Group
Specify an integer value in this input field corresponding to the group number of device features.
Corresponds to the device parameter, FEAT=. Valid input values are 1-10 for devices that are of type
3270 and 1-10, 120, 126, 132 for devices of type 3270P. This input is optional.

Function key properties

The following properties are editable on the Function Key tab. All input fields are used to build the device
parameter, PFK= Program function keys that are added are listed in Function keys. To remove a program
function key, select it from the list and click Remove.
Device field
Specify the name of the input device field that contains the program key literal or control function
data. This input is required to specify the device parameter, PFK=.
Literal
Specify a literal value for the program key function. Click the Add button to add this literal to the list of
program key functions.
Function key
Function key list
Select a control function to add to the PFK from the drop-down menu. Click the Add button to add the
control function to the list of program key functions.
Function keys
The list of PFKs that are defined for the device. The maximum number of user-defined PFKs is
thirty-six.

Division properties
When a division is selected in the Outline view, or the DIV statement in the MFS source is selected, the
division properties are displayed in the Properties view.
The following are the editable properties that can be modified for the division.
Name
Specify an optional name to uniquely identify this statement. The length is from one to eight
alphanumeric characters.
Type
Specify the format as input-only (INPUT), output-only (OUTPUT), or both (INOUT).
Compression
Select the compression from the drop-down list:
• SHORT - MFS removes trailing blanks from short fields.
• FIXED - MFS removes trailing blanks from fixed-length fields.

112 Developer for z/OS: Developing with Db2, CICS, and IMS
 • ALL - MFS removes trailing blanks from all fields presented by the application program.
This option is valid for divisions with a type of OUTPUT.

Device page properties

When a device page is selected in the Outline view, or the DPAGE statement in the MFS source is selected,
the device page properties are displayed in the Properties view.
The following are the editable properties that can be modified for the device page.
Name
Specify an optional name to uniquely identify this format statement. The length is from one to eight
alphanumeric characters.
Fill
Select the type of fill value from the drop down menu. This value is optional.
Value
This input field makes up the second part of the FILL= parameter for the device page. If you specify a
fill of NONE, PT, or NULL, no value input is needed.
Multiple physical pages
Marking this checkbox allows for the creation of more than one physical page for the device page.
Corresponds to the MULT=YES device page parameter. This input is optional; however, adding
subsequent physical pages through the outline view or palette view for a device page is disabled
until this checkbox is marked.

Physical page properties

When a physical page is selected in the Outline view the physical page properties are displayed in the
Properties view.
The following are the editable properties that can be modified for the device page.
You can set the following Basic properties:
Cursor line
Specify the row position of the cursor on the physical page. The cursor line value must be a numeric
value. Corresponds to the device page parameter, CURSOR=.
Cursor column
Specify the column position of the cursor on the physical page. The cursor column value must be a
numeric value. Corresponds to the device page parameter, CURSOR=.
Device field
Specify the device field to be used to contain the cursor position on the physical page. The device field
parameter is only valid if the row and column for the cursor are specified. Corresponds to the device
page parameter, CURSOR=.
All properties are optional and valid only for physical pages in device types 3270 and 3270-An.

Field properties
When you select a field through the Outline view, on the design canvas, or a DFLD macro in the Source
page, the properties that are associated with the field are populated and displayed in the Properties view.

Basic properties
The following properties are editable on the Basic tab of the Properties view:
Label
Specify field name. The length is from one to eight alphanumeric characters. This label corresponds
to the DFLDNAME for the field. This input is required for an input and output field and invalid for a
password and label field.

Developing IMS applications 113

 Value
Specify a literal character string to be presented to the device. This input is required for a label field,
but invalid for an input, output, and password field.
Width
Specify the length of the field. Omit this operand if literal is specified in the positional parameter as
the length of literal is used as the field length.
Row
Specify row in the design canvas on which the field is to appear. This input is required for all fields.
Column
Specify the column in the design canvas on which the field is to appear. This input is required for all
fields.
Page number
Specify the physical page number for an output field. By default, the physical page number is the
number of the physical page to which the field was added. Changing the physical page number moves
the field to the physical page now specified by the physical page number. However, for this change to
display in the design page, you must save, close, and reopen the MFS source. It is invalid to change
the physical page number if it causes the field to overlap with existing fields on the specified physical
page.
Password
This option identifies this field as the location of the IMS password field for input messages. It is
invalid to have a Label, or DFLDNAME, specified for a field that is specified as a password field.

Attributes properties
The following properties are editable on the Attributes properties tab of the Properties view. All
attributes except for Attribute Bytes are optional for devices of type 3270 and 3270-An and invalid
for device types 3270P.
Intensity
Select the display intensity of the field as High, Normal, or Nondisplayable. Corresponds to the field
parameter, ATTR= and the properties HI, NORM, and NODISP.
Detectability
Select the detectability of the field through light pen operations as Deferred, Immediate, or
Nondetectable. Corresponds to the field parameter, ATTR= and the properties DET, IDET, or NODET.
Protected
Select this checkbox to protect the field from modification. Clear the checkbox to remove protection.
Corresponds to the field parameter, ATTR=PROT. Label fields are always protected.
Numeric
Specify whether the field has the numeric attribute. Corresponds to the field parameter, ATTR=NUM.
Modified
This parameter defines whether the field-modified-attribute byte is assumed for this field.
Corresponds to the field parameter, ATTR=MOD.
Strip
Specify whether the pen detect designator byte preceding the input field is to be stripped (STRIP)
before presentation to the application program. Corresponds to the field parameter, ATTR=STRIP.
Attribute bytes
Mark this checkbox to specify whether to use the first byte of this field to display attribute
information when the output message includes attribute information for the field. Marking the
checkbox corresponds to the field parameter, ATTR=YES, and clearing the checkbox corresponds
to the field parameter, ATTR=NO. This input is optional and valid only for devices of type 3270P.

Extended attributes
You can set the following Extended Attributes properties. These properties are valid only on output fields
and correspond to the field parameter EATTR.

114 Developer for z/OS: Developing with Db2, CICS, and IMS
Highlighting
Select the highlighting style from the drop-down list.
Color
Select the color from the drop-down list.
Outline
Select one or more locations to create the field outline.
Program Symbol Buffer
Specifies the program symbol buffer for the IMS application program. You must specify a
corresponding Value.
If you select PX from the drop-down menu, then the value must be a hexadecimal value in the range
of X'40' to X'FE'. If you select PC from the drop-down menu, then the value must be a character
value in the range of X'40' to X'FE'. It is invalid to specify both a program symbol buffer and an
extended graphical character set.
Corresponds to the field parameter values: EATTR=PX'hh' or EATTR=PC'hh'.
Extended Graphical Character Set
Mark the checkbox to specify the use of an extended graphical character set. This value is valid only
on output fields in devices of type 3270.
If you specify an additional value, then it must be a hexadecimal value in the range X'40' to X'FE' or
X'00'.
Corresponds to the field parameter values: EATTR=EGCS'hh'.
EGCS/DBCS Mixed Field
Mark the checkbox to specify if the field contains a mixture of single byte and double byte characters.

Features properties
MFS files with tables are supported in modification mode only. Tables and fields on the Features tab
are inactive if no OPCTL keyword exists on the device field. If an OPCTL keyword exists on the tab of
the Properties view, the fields are populated with the information from the TABLE declaration and are
modifiable.

Message properties
When a message is selected in the Outline view, or the MSG statement in the MFS source is selected, the
message properties are displayed in the Properties view.
The following are editable properties that can be modified for the message.
Name
Specify the message name. Valid names are from one to eight characters. This entry is required.
Type
Select the message type from the drop-down list. Valid values are Input and Output. Corresponds to
the message parameter, TYPE=. This parameter is required.
Fill
Specify the fill character. This input is optional and is valid only for messages of type output.
Corresponds to the message parameter, FILL=. If you specify a fill type of C'c', replace 'c' with the
character to use as the fill value. For example, to specify a fill value of periods, provide the string:
C'.'.
Format
This parameter lists the referenced device format in the SOR= operand. The value is taken from the
FMT label and cannot be modified.
Next Message
Specify a message description name. If the current message is an input message, the message
referenced as Next Message must be an output message. If the current message is an output
message, the message referenced as Next Message must be an input message.

Developing IMS applications 115

 Paging
Specify whether operator logical paging or forward and backward paging, is provided for messages
that are edited by using this control block. The default is for only forward paging of physical pages
to be provided. Corresponds to the message parameter, PAGE=. This option is available only for the
output type and is optional.
Ignore
Specify whether device features are to be ignored for this device. Corresponds to the IGNORE keyword
specified in the SOR= message parameter. This parameter is optional.

Logical page properties

When a logical page is selected in the Outline view, or the LPAGE statement in the MFS source is selected,
the logical page properties are displayed in the Properties view.
The following are the editable properties that can be modified for the logical page.
Name
Specify a name to uniquely identify this statement. The length is from one to eight alphanumeric
characters. This input is optional. Regardless of whether a logical page name is specified or not, the
MFS message is always created with an LPAGE statement.
DPAGE Name
Select the DPAGE name from the drop-down menu that defines the device format for this logical page.
Only those device fields that are defined in the DPAGE are available to add as message fields to the
logical page. This input is required
The following logical page properties are used to describe a conditional test that, if successful, specifies
that the segment and field definitions following the LPAGE are to be used for output editing of the logical
page. These fields correspond to parameters in the COND= logical page attribute.
Message Field
Select the associated message field from the drop-down list. This is the area that is to be used in the
conditional comparison.
Offset
Specify the offset value, which changes the starting position of comparison in the selected message
field. If you wish to start comparison at the beginning of the field, specify an offset value of one.
Operator
Select an operator from the drop-down list. The operator describes what type of comparison is done.
Value
Specify the literal value to be used to compare for the logical page condition.
The final fields deal with formatting the last logical page of an output message and correspond to the
logical page attribute, PROMPT=.
Prompt
Specify the name of a device field in which the prompt value literal is to be displayed when the last
logical page is formatted. This input is optional and valid only for input messages.
Prompt value
Specify the literal value to display in the device field specified in Prompt. This input is required if
Prompt is specified and is valid only for input messages.

Segment properties
When a segment is selected in the Outline view, or the SEG statement in the MFS source is selected, the
segment properties are displayed in the Properties view.
The following are the editable properties that can be modified for the segment.
Name
Specify the segment name. Valid names are from one to eight characters in length. This input is
optional.

116 Developer for z/OS: Developing with Db2, CICS, and IMS
Exit Number
Specify a value in the range from 0 to 127. This value corresponds to exit number attribute in the
segment parameter, EXIT=. This input is optional and valid only for input message segments.
Exit Vector
Specify a value in the range from 0 to 255. This value corresponds to the exit vector attribute in the
segment parameter, EXIT=. This input is required when Exit Number is specified and valid only for
input message segments.
Graphic
Mark this checkbox to specify that IMS is to perform uppercase translation on the segment, if the
destination definition requests it. Corresponds to the segment parameter, GRAPHIC=. This parameter
is optional and valid only for input messages.

Message field properties

When a message field is selected in the Outline view, or the MFLD statement in the MFS source is
selected, the message field properties are displayed in the Properties view.
The following are the editable properties that can be modified for the message field.
Name
Specify the field name. At least one message field must be specified for a MSG statement.
Device Field
Specify the name of the device field to associate with the message field. For input message fields,
input data is extracted from this device field. For output message fields, output data is placed in this
device field. This input is optional when no literal is specified.
Length
Specify the message field length. Corresponds to the message field parameter, LTH. This input is
required if no length is specified for the message field.
Literal
Specify the literal value to be inserted into the input message. This input is required if no length is
specified for the message field.
First Byte
Specify the number of the byte of the input data field that is to be considered the first byte of data for
the message field. For example, if the first byte for the message field is specified as two, then the first
byte of the field is ignored. Corresponds to the positional parameter value on the message attribute,
LTH=. This input is optional and valid for input messages only.
Justify
Select the field justification, either right or left, from the drop-down list. Corresponds to the message
field parameter, JUST=, and is optional input.
System Literal
Select the system literal from the drop-down list. This input is only valid if no literal is specified for an
output message field.
Fill
Select a character to be used to pad this field when the length of the data that is received from the
device is less than the length of this field. Corresponds to the message field attribute, FILL=. This
input is optional and valid for input messages only.
The following are editable properties on the Advanced tab:
Extended Attributes
Specify the number of extended attributes that can be dynamically modified. Valid values are between
one and six. Corresponds to the extended attributes parameter of the message field parameter,
ATTR=. The input is optional.
Exit Number
This parameter sets the exit routine number for the field edit exit routine interface. The range of
values is from 0 to 127. Corresponds to the message field attribute, EXIT=.

Developing IMS applications 117

 Exit Vector
This parameter sets the value to be passed to the exit routine when it is invoked for this field. The
range of values is from 0 to 255. Corresponds to the message field attribute, EXIT=.
Attributes
This option specifies whether the application program can modify the 3270 attributes. Corresponds to
YES value in the message field parameter, ATTR=. This input is optional.
System Control Area
Mark this checkbox to specify that an output field is the system control area.

Message Format Service (MFS) Editor icons

The following icons are commonly seen in the MFS Editor palette, the Outline view when a map is open in
the MFS Editor, and the MFS Editor toolbar.

MFS Editor palette

The following icons are commonly seen in the MFS Palette view.

Table 9. MFS Editor palette icons

Icon Description Icon Description
Icons found in the Default drawer
Use to select a single field in the Use to select multiple fields in the Design
Design Page. Page.
Icons found in the Basic drawer
Use to insert an MFS Device into the Use to insert an MFS Division into the
Design Page. Design Page.
Use to insert a device page into the Use to insert a physical page into the
Design Page. Design Page.
Use to insert a label field into the Use to insert an input field into the Design
Design page. page.
Use to insert a password field into the Use to insert an output field or system
Design page. message field into the Design page.
Icons found in the “Advanced drawer” on page 107 drawer
Use to insert a table into the Design
page.

MFS Editor toolbar

The following icons are commonly seen in the toolbar on the Design page of the editor.

Table 10. MFS Editor toolbar icons

Icon Description Icon Description
This icon acts as a button. Pressing it This icon acts as a button. Pressing it
toggles the grid lines in the MFS Editor toggles the sample values for each field on
on and off. and off.
This icon acts as a button. Pressing it Use this icon to access the different zoom
toggles the editor between black-and- levels for the MFS Editor.
white mode and color mode.

118 Developer for z/OS: Developing with Db2, CICS, and IMS
 Table 10. MFS Editor toolbar icons (continued)
Icon Description Icon Description
Use this icon to access the different
filters that are defined for the active
map set.

Outline View for MFS maps

The following icons are commonly seen in the “Outline view” on page 108 view when a map is open in the
MFS Editor.

Table 11. Icons in the Outline view

Icon Description Icon Description
The MFS Format Definition or A MFS An MFS device in the map
Message Definition
An MFS division in the map An MFS device page in the map

A device page in the map A physical page in the map

A protected or label field in the map, An unprotected or input field in the map
also a message field in a MFS message
definition
An output field in the map A MFS logical page or segment in the MFS
message definition

Editor features
The MFS Editor provides visual editing and modification tools for use with device format definitions.
Additional options and capabilities can be accessed through the available views.
The Palette view provides both click-and-drop and drag-and-drop access to the format definition
components. The editor provides additional capabilities with the Outline and Properties views.

Design page in MFS Editor

The Design page contains the Design canvas and an associated Palette view, where you can visually edit a
format definition.

Design canvas
Use the Design canvas to customize a new format definition or modify an existing format definition. Use
the scroll bars to view the entire visual editing space.
To see the available design, filter, and edit options, right-click the canvas to open the right-click menu.
To add an item to the canvas, click the item icon on the Palette and click the cursor at the canvas location
that you want. You can also drag the item onto the canvas.
Note: When you first create an MFS device format with the MFS Device Format wizard, the lowest level of
the hierarchy that is created is the MFS division. You can view this hierarchy in the Outline view. Before
you can start adding fields to the design page, you must first add a device page and physical page element
to the device format. After the first physical page is created, the highest level of hierarchy that is displayed
in the design page is the physical page level. Subsequent device pages must be created through the
Outline view.

Developing IMS applications 119

 When you select a field in the design canvas, the field is highlighted in the Outline view, and property
value information is shown in the Properties view. If you open the Source page of the MFS editor, the MFS
source corresponding to the MFS field is also highlighted.

Selecting and moving items

There are several ways to select and move items in the Design canvas.
If you want to select and move a single item, use the Palette view Select tool from the Default drawer.
Select the item, press and hold the mouse, and drag the item to the desired location. As the field is
moved, a pop-up dialog opens and shows row, column, and width information.
To select multiple items in sequence, use the Select tool in the Design canvas, press the Ctrl key, and
select the items to move. You can then click one highlighted item and move the entire group of selected
items.
Alternatively, you can draw a box around the items that you want to move in the Design canvas, by
pressing the Shift key while you use the Select tool.
You can also use the Marquee tool in the Design canvas, and then use the Select tool to create a cursor
for moving the selected items.

Edit options and keyboard shortcuts

Table 12 on page 120 lists the edit options and the corresponding keyboard combinations. These options
are also available from the Design page right-click menu.

Table 12. Design canvas edit options

Option Keyboard shortcut
Undo Ctrl+Z
Redo Ctrl+Y
Cut Ctrl+X
Copy Ctrl+C
Paste Ctrl+V
Delete Delete
Save Ctrl+S
Print Ctrl+P

Important: The Undo and Redo operations apply to operations performed in either the Outline view or
the Design canvas. For example, if you cut a field in the design canvas, the Undo Cut option is enabled in
the Outline view pop-up menu.

Printing
To print the design canvas, click File > Print from the menu toolbar. You can also use the Ctrl+P key
combination or select Print from the Design page right-click menu.

Design page customization

Use the tools in the toolbar along the top of the Design canvas to customize the appearance of the Design
canvas.

Bidirectional options
Terminal Size
Select the down arrow to create format definitions for several screen sizes.

120 Developer for z/OS: Developing with Db2, CICS, and IMS
 • 12 × 80
• 24 × 80 (default)
• 32 × 80
• 43 × 80
• 24 × 80
• 27 × 132
Toggle Grid lines
This option hides or shows the grid lines in the design canvas. Grid lines are helpful to verify that fields
are aligned properly.
Toggle Samples Values
This icon, , functions as a button. Pressing it displays the type and amount of data allowable in a
field. For example, a numeric field of 4 units displays a sample value of 9999 and an alphanumeric
field of the same length displays a sample value of XXXX.
Toggle Black and White Mode
This icon, , functions as a button. Pressing it displays the devices and fields in a high-contrast
canvas.
Zoom Level

Use this icon, , to select the zoom level of the design canvas.
Filters
A filter is a group of one or more physical pages that are displayed at a single time. Select the down
arrow next to the filter icon, to see a list of filters that are created. By default, all physical pages are
shown.
Create new filters to display customized groupings of physical pages. You can also change the
ordering of physical pages in the list.
If bidirectional support is enabled, a Toggle Bidirectional Mode button is displayed on the Design page
toolbar.
The following toggle options are available:
• Visual Data
Toggles between visual ordering of text and the default logical ordering.
• RTL Mapset
Toggles the orientation of the screen and the horizontal ruler between left-to-right to right-to-left.
• Symmetric Swapping
Resets swappable characters. For example, in a right-to-left string, the open parenthesis ( and close
parenthesis ) are reversed.
• Numeric Swapping
Sets an inversion of the screen, which causes Hindi numerals to be replaced by their Arabic
counterparts and the Arabic numerals to be replaced by their Hindi counterparts.

Design page right-click menu

The Design page right-click menu provides context-specific editing options and device, field, and page
display and formatting options.
The Show Source option displays the format definition source for a selected field in the Design canvas.
To print the entire design canvas, click Print. When you print this way, nothing but the Design canvas, as it
is displayed, is printed.
To save the current .mfs file, click Save.

Developing IMS applications 121

 The right-click menu also contains formatting options that can be applied to a selected field in the Design
canvas:
• Format
– Includes the following values which are added to the MFS source as extended attributes. You can
also modify these values for fields by using the Properties view.
- Highlighting
- Outline
- Intensity
- Color
• Align
– Provides horizontal and vertical alignment options for multiple selected fields
– Provides an Align to Parent menu. Selected fields when aligned with parent are moved to the
location specified relative to their containing macro.
The Filters menu includes some display options that are not available elsewhere:
• Configure opens the Filters window. This window is also accessible by selecting the drop-down arrow
next to the filters icon and selecting the Filters entry at the bottom of the list.
• Hide Map, which hides the currently displayed map, or Show Map, which displays a currently hidden
map.
• Hide All Maps hides all maps that are present in the device format.
• Show All Maps shows all maps that are present in the device format. Selecting this option displays the
same set of physical pages as the default filter.
The standard editing options include the following options:
• Undo and Redo
• Cut, Copy, Paste, and Delete
Important: The Undo and Redo options apply to operations performed in either the Outline view or the
design canvas. For example, if you delete a field in the design canvas, the Undo Delete option is enabled
in both the Design canvas right-right click menu and the Outline view right-click menu.

Bidirectional options
If you enable bidirectional support in the Preferences page, a Bidirectional Settings option displays
on the Design page right-click menu. These options are the same as the options on the Design page
bidirectional toggle button.
Related information
“Preferences” on page 125
You can customize some components of the MFS editor through the MFS Editor Preferences page.
“Design page in MFS Editor” on page 119
The Design page contains the Design canvas and an associated Palette view, where you can visually edit a
format definition.

Show source
The Show Source option in the design canvas right-click menu displays the format definition source for a
selected field.

Source page
Use the Source page to view and modify the MFS source statements directly in a text editor.
Note: Use the Show Source option from the “Design page right-click menu” on page 121 to view the .mfs
source in a read-only mode while still in the Design canvas.

122 Developer for z/OS: Developing with Db2, CICS, and IMS
When you select a line of MFS source in the Source page, the MFS element that corresponds to the macro
is highlighted in the Outline view. If the Properties view is also open, then the properties of the macro are
also populated and displayed. Changes that are made directly to the source are immediately reflected in
the Design page and Preview pages.
Note: Manual changes done to the MFS source are not validated for semantic and logical correctness.
For example, modifying the length of a field such that it overlaps another, existing field, does not cause
a validation error. Therefore, it is recommended to modify MFS source through the Design page, Outline
view, and Properties view.
Standard editing features are provided, such as Find/Replace, Undo/Redo, Cut, Copy, Paste, and Delete.
Additional editor features are as follows:
• Customized color highlighting
Items such as MFS statement keywords, attribute names and values, strings, and comments are colored
differently, to help you differentiate parts of an MFS source statement. You can customize the colors in
the Preferences dialog.
• Line numbers
Line numbers are displayed in the left margin of the editor window. You can hide line numbers by
modifying the Preferences .
• Error markers
If syntax errors are encountered during a save or a validation and build operation, an error icon is
displayed in the left margin of the line that contains the error. Errors also are displayed in the Problems
view. MFS device format source files that contain syntax errors cannot have an MFS message definition
that is appended to them until the syntax error is resolved.

Source page pop-up menu

The Source page right-click menu provides code formatting options and editing options.
Use the Shift Right and Shift Left options to move the source code.
To add code to a snippet drawer, select the text and click Add to Snippets.
Click Save to retain your changes, or use the Revert File option to go back to the previously saved file
source.

Preview page
Use the Preview page to view a read-only display of the device format definition as it is displayed on a
3270 terminal.

Display options
Use the following display options to customize the definition preview:
Preview Mode
This option shows the device format definition displayed in Web or Normal (terminal emulator) form.
The web option is available even if a web page is not created from the definition file.
Filters
Use this option to preview and prioritize a subset of the available physical pages. By default, all
physical pages are shown. You create new filters to display customized groupings of physical pages.
Click Refresh to update the definition preview.
Related information
“Filters” on page 124
Filters allow customization of the physical pages that are displayed in a format definition open in the
Design canvas or Preview page. Any physical page present in the format definition can be its own filter
or can be a filter with other physical pages. Filter configurations are saved in the current workspace and

Developing IMS applications 123

 are available each time you open the format definition in that same workspace. You cannot transfer filter
definitions to another workspace.

Filters
Filters allow customization of the physical pages that are displayed in a format definition open in the
Design canvas or Preview page. Any physical page present in the format definition can be its own filter
or can be a filter with other physical pages. Filter configurations are saved in the current workspace and
are available each time you open the format definition in that same workspace. You cannot transfer filter
definitions to another workspace.
Note: The filtering option is not available for the Source page.

Select a filter
You can change the filter by clicking the drop-down arrow next to the filter icon and selecting a filter from
the list of available filters. The name of the currently applied filter is displayed below the filter icon on the
Design canvas or Preview page toolbar.

Create a filter
If the list of available filters does not contain the grouping of physical pages you want to display, you can
create a filter.
1. Click the drop-down arrow next to the filter icon, and select Filters. This action opens the Filters
dialog.
You can use the Filters dialog to modify existing filters and create new filters.
2. At the top of the dialog, click New. This action opens the New Filter dialog.
3. Enter a name for the filter, and click OK. The filter name is displayed in the Select a filter menu.
4. Select the name of the physical page in the list to preview it in the Preview window.
5. Mark any checkbox next to physical pages you want to add to the filter.
6. Clear any checkbox next to physical pages you want to remove from the filter.
7. Set the order of the device pages to be shown by the filter by moving a physical page higher or lower in
the list.
Use the Up and Down buttons to change the order of displayed physical pages. The fields of the
physical page listed first for the filter are editable in the Design canvas. Any other physical pages that
are included in the filter are displayed behind the first physical page and are not editable in the Design
canvas unless they are manually brought to the front.

Modify an existing filter

To modify existing filters, you use the Filters dialog.
1. Click the drop-down arrow next to the filter icon, and select Filters.
2. From the Select a filter menu at the top of the Filters dialog, select the filter that you want to modify.
Note: When you are modifying filters, changes are applied only to the filter that is selected in the
Select a filter menu.
3. Mark any checkbox next to physical pages to add the physical page to the filter.
4. Clear any checkbox next to physical pages to remove the physical page from the filter.
5. Change the order of the device pages by using the Up and Down buttons.
6. When you are finished updating the filter, close the Filters dialog. The changes that you entered
automatically saved and the changes are automatically available.

124 Developer for z/OS: Developing with Db2, CICS, and IMS
 Remove an existing filter
Removing an existing filter removes the filter from the list of filters accessible on the Design canvas and
Preview page toolbars. Removing a filter cannot be undone.
To remove an existing filter, you use the Filters dialog.
1. Click the drop-down arrow next to the filter icon, and select Filters.
2. From the Select a filter menu at the top of the Filters dialog, select the filter that you want to remove.
3. Click the Remove button. A prompt opens for you to confirm removal of the filter.
4. Click OK to remove the filter. The filter is no longer displayed in the filters list.

Preferences
You can customize some components of the MFS editor through the MFS Editor Preferences page.
In the left pane of the Preferences window, select MFS Editor to access the Preferences page. You can
also open the preferences by right-clicking the MFS editor design page and selecting Preferences from
the menu.

General preferences
You can modify the following MFS Editor preferences:
• Show line numbers
Displays line numbers in the left column of Source page.
• Open outline
Opens the Outline view when a file is opened in the MFS editor.
• Open properties
Opens the Properties view when a file is opened in the MFS editor.
• Naming conventions
Sets name prefixes for devices, device pages, and input fields.

Design Page
You can modify the following Design page preferences:
• Background color
Sets the background color of the design canvas.
• Grid color
Sets the color for vertical and horizontal grid lines.
• Highlight fields
Places a box around fields. Select the color that you want for the box.
• Show rulers
Shows or hides the vertical and horizontal rulers.
• Font name
Sets the font style and size used in the design canvas.
Note: Use only monospace fonts.
• Font
Sets the font size used in the design canvas (works with the Zoom feature).
• Visually demonstrate blinking fields
Blink fields are displayed with an italicized font.

Developing IMS applications 125

 Use the Preview area to evaluate the style changes before applying them.

Bidirectional settings
Select Bidirectional options enabled to allow the following bidirectional language preferences. The
options specify the default for each newly loaded format definition file.
• Enable visual data ordering Sets the visual ordering of text, instead of the default logical ordering.
• Enable bidirectional settings button Places a Toggle bidirectional mode button on the Design page
toolbar.
• Default RTL orientation Sets a right-to-left text flow in the display. This preference simulates how data
is displayed on a 3270 terminal when the screen is reversed. This option enables the design of reversed
(right-to-left) screens.
• Default right alignment Causes fields added in the Design page to be right-aligned. In the source file
right-aligned fields are padded with leading spaces.
• Enable symmetric swapping Resets swappable characters automatically. In a right-to-left string, for
example, the parentheses characters ( and ) are reversed.
• Enable numeric swapping Automatically sets an inversion of the screen, which causes Hindi numerals
to be replaced by their Arabic counterparts and Arabic numerals to be replaced by their Hindi
counterparts.

MFLD preferences
Select Automatically generate Input and Output MFLD when a DFLD is added to automatically add
MFLD definitions to the input and output messages when a newly created DFLD is added to the Design
page.
Note: The Input MFLD generates the LTH attribute and the Output MFLD generates the LTH and the
ATTR=YES attributes by default. Customization of the attributes that are generated in the MFLD are not
supported.

Source Page
You can modify the following Source page preferences:
• Background color
Sets the background color of the Source page editor. The default is white.
• Foreground
Sets foreground colors for the following items:
– MFS statement keywords
Color for keywords such as DEV, DIV, and DPAGE.
– Attribute names
Color for attribute names.
– Attribute values
Color for attribute values.
– Strings
Color for regular strings, such as initial value.
– Comments
Color for comments.
Click Bold to further emphasize any specific foreground item, regardless of color.
Use the Preview area to evaluate the style changes before applying them.

126 Developer for z/OS: Developing with Db2, CICS, and IMS
 Related information
“Outline view” on page 108
The Outline view displays format and message information for a specific MFS file in a hierarchical
presentation.
“Properties view” on page 110
The Properties view displays property value information for a component that is selected in the design
canvas or the Outline view.

JCL generation
You can generate the job control language (JCL) for an MFS file, either from an existing partitioned data
set on the remote z/OS system or from an MVS subproject.
Before you can create the JCL for an MFS file you must create a property group that specifies the
information that the host needs for JCL generation. To create a property group:
1. In the Property Group Manager view, right-click the host connection for the host that contains the
MFS files for which you want to generate JCL.
2. Select New Property Group. A new property group is opened in the editor.
3. At the bottom of the editor, select the MFS tab. This action opens the MFS settings page of the
property group.
4. From the left menu, select Procedures and Steps. In the main window, expand the procedure name,
ELAXFMFS, and select DFSUPAAO.
5. Scroll down to the Step options panel, and click Edit. This action opens the editable option for the
procedure and step you selected.
6. Enter PDS names that are available under the My Data Sets filter for FORMAT library, Listing output
data set, and SYSLIB library.
7. Save the property group.
After you create a property group, you must associate it with the MFS file or containing PDS before you
generate the JCL.
1. In the Remote System Explorer view, navigate to the MFS file or the PDS containing the MFS for which
you want to generate JCL.
2. Right-click the MFS file or the containing PDS, and select Property group > Associate property group.
The Associate Property Group dialog opens.
3. In this dialog, select the checkbox next to the property group to associate to your MFS file or PDS. Click
OK. The property group is associated to the MFS file or PDS.
Finally, you can generate the JCL for the MFS file.
1. Right-click the MFS file and then click Generate JCL > To Run MFS Gen.
2. Specify the target partitioned data set for the generated JCL and the member name. You can also set a
different job name. This target PDS is where the generated JCL is placed.
3. Click OK to complete the generation process.
If the member name exists, you are prompted to overwrite the member.
If the target partitioned data set does not exist, an error message is displayed.
If the JCL generation is successful, you are immediately prompted to submit the JCL. If you do not submit
the JCL, then you can submit the JCL later by right-clicking the JCL in its PDS and selecting Submit.
You can use the JES subsystem to track any JCL submission process.
Related reference
MFS step options
Related information
Determining the source of generated JCL

Developing IMS applications 127

Bidirectional support
The MFS Editor supports bidirectional options for Arabic and Hebrew device format definitions.
Some features apply only to Arabic format definition, as indicated in the documentation. By default,
bidirectional support is not enabled.
Note: All bidirectional message definitions must have UTF-8 text file encoding.

Enabling bidirectional support

To work with Arabic and Hebrew device formats, you must enable bidirectional support in the
Preferences window. Enabling this functionality adds a bidirectional mode button to the Design page
and options to the Design pop-up menu. Status bar information is provided when directly editing a field.
Enable the bidirectional settings that you want before you close the Preferences window.

Bidirectional preferences
The following bidirectional settings are available:
• Enable visual data ordering Sets the visual ordering of text, instead of the default logical ordering.
• Enable bidirectional settings button Places a Toggle bidirectional mode button on the Design page
toolbar.
• Default RTL orientation Sets a right-to-left text flow in the display. This preference simulates how data
is displayed on a 3270 terminal when the screen is reversed. This option enables the design of reversed
(right-to-left) screens.
• Default right alignment Causes fields added in the Design page to be right-aligned. In the source file
right-aligned fields are padded with leading spaces.
• Enable symmetric swapping Resets swappable characters automatically. In a right-to-left string, for
example, the parentheses characters ( and ) are reversed.
• Enable numeric swapping Automatically sets an inversion of the screen, which causes Hindi numerals
to be replaced by their Arabic counterparts and Arabic numerals to be replaced by their Hindi
counterparts.

Visual input key functions

Visual input key functions allow visual input in input fields and the initial values for labeled input fields
and tables. The following table shows the key functions and key combinations that involve the number
pad that are available if you enable visual data ordering in the preferences.

Table 13. Visual input key functions

Key
Key function Description combination
Push Starts a segment of reversed text and reverts the direction of the Shift+NumLo
cursor. Text is pushed toward the end of the field, and the cursor ck
remains stationary.
EndPush Terminates the current segment of reversed text. The cursor skips Shift+/
to the end of the segment, and its direction is restored.
AutoPush Enables the Push and EndPush functions to be automatically Alt+/
invoked, based on the actual text entered.
FieldReverse Reverses the typing direction and the direction of functions such Alt+NumLock
as Backspace, Delete, Home, and End. However, the function does
not visually invert the contents of the field.

128 Developer for z/OS: Developing with Db2, CICS, and IMS
Table 13. Visual input key functions (continued)
Key
Key function Description combination
Switch between Switches numerals input between Arabic and Hindi. Alt+*
input of Arabic/
Hindi Numerals

Status bar information

When you click a device format component in the design canvas, the following bidirectional information is
displayed in the status bar:
• Orientation of the current device format
Status displays either LTR (left-to-right) or RTL.
• Autopush flag
Status displays A when Autopush is enabled (visual mode only).
• The current editing mode.
The following mode labels can be displayed independently or in combination.
– None
No bidirectional mode options are enabled.
– Push
Push mode is enabled.
– FldRev
Field Reverse is enabled.
– Hindi
Input is Hindi numerals (Arabic only).

Editing bidirectional text

Use the LPEX editor for bidirectional data in Smart Logical format. It is also possible to edit bidirectional
data in the MFS Editor Source view, using the Ctrl+NumLock key combination on the selected line.
Related information
“Preferences” on page 125
You can customize some components of the MFS editor through the MFS Editor Preferences page.
“Design page in MFS Editor” on page 119
The Design page contains the Design canvas and an associated Palette view, where you can visually edit a
format definition.
“Design page right-click menu” on page 121
The Design page right-click menu provides context-specific editing options and device, field, and page
display and formatting options.

Bidirectional support for MFS visual editing

This topic contains additional information about bidirectional support for the MFS editor.
MFS files are stored on the remote system in visual format. The default bidirectional format is Smart
Logical. You must associate the correct bidirectional conversion tables in the file system mapping
for .mfs files because the default setting does not assume bidirectional conversion.
Visual editing of bidirectional data is enabled after Bidirectional options enabled is selected in
Preference. To enable this option, in the left pane of the Preferences window, select MFS Map Editor
> Design Page > Bidirectional Settings.

Developing IMS applications 129

 Even after visual editing is enabled, bidirectional data is saved in .mfs files in Smart Logical format. This
format is similar to standard Windows logical format, but is based on extensive use of bidirectional LRM
markers. For more information about Smart Logical support, see the information about the zIDE tool.
To edit bidirectional data in the Smart Logical format, use the z Systems LPEX editor. The LPEX editor
provides a special visual line for this purpose. To access the visual line in LPEX, use the pop-up menu
to select Source > Visual edit line, or use the Alt+= key combination. For more information about z
Systems LPEX bidirectional support, see the LPEX documentation.
To edit bidirectional data in the MFS editor Source view, use the Ctrl+NumLock key combination on the
selected line.

Settings
To activate bidirectional support, in the left pane of the Preferences window, click MFS Map Editor >
Design Page > Bidirectional Settings and select Bidirectional options enabled.
Under the Bidirectional options enabled checkbox are the following check boxes:
• Enable visual data ordering Sets the visual ordering of text, instead of the default logical ordering.
• Enable bidirectional settings button Places a Toggle bidirectional mode button on the Design page
toolbar.
• Default RTL orientation Sets a right-to-left text flow in the display. This preference simulates how data
is displayed on a 3270 terminal when the screen is reversed. This option enables the design of reversed
(right-to-left) screens.
• Default right alignment Causes fields added in the Design page to be right-aligned. In the source file
right-aligned fields are padded with leading spaces.
• Enable symmetric swapping Resets swappable characters automatically. In a right-to-left string, for
example, the parentheses characters ( and ) are reversed.
• Enable numeric swapping Automatically sets an inversion of the screen, which causes Hindi numerals
to be replaced by their Arabic counterparts and Arabic numerals to be replaced by their Hindi
counterparts.
When Enable bidirectional settings button is selected, the same set of bidirectional settings is made
available in the MFS Editor toolbar. When a bidirectional settings button is enabled, you can dynamically
set the bidirectional options described in this topic.

Bidirectional array alignment

In the Bidirectional settings, this option is selected by default and determines whether the structure
fields are created from left to right or from right to left.
In LTR Mapset, this structure is created with the same orientation as the map set by selecting this default
option; for example, LTR structure in LTR mapset.
The following figure is an example of the left to right bidirectional array alignment settings.

130 Developer for z/OS: Developing with Db2, CICS, and IMS
Figure 2. Example of Bidirectional Array Alignment Settings

This structure is created with an orientation opposite to mapset when this option is not set to the default;
for example, RTL structure in LTR mapset

Developing IMS applications 131

132 Developer for z/OS: Developing with Db2, CICS, and IMS
Developing web services and SOA with Enterprise
Service Tools
Enterprise Service Tools, a component of Developer for z/OS, provides tools for enabling CICS and IMS
applications running on z/OS to participate in a service-oriented architecture (SOA).

Single-service projects
Single-service projects provide an integrated set of programs for generating files needed in developing
Web services, including COBOL or PL/I source code files for runtime-specific request and response XML
message processing and Web service description files (WSDL).
To generate these output files you first select data definitions from high-level-language source code files
(COBOL or PL/I) and from XML schema definitions (from WSDL, XML, or XSD files, depending on the
scenario) and then specify how the fields in the high-level-language data definitions are to be mapped to
the fields in the XML schema definitions.
The generated output files can be used to create a service provider and requester application that invokes
a new or existing CICS application as its program component.
These output files can be generated for the following runtime environments (not all solutions are available
in all runtime environments -- see “Web services development scenarios” on page 134):
• Web Services for CICS Project
• XML Transformation for CICS Project
• IMS Enterprise Suite SOAP Gateway Project
• Batch, TSO, z/OS UNIX System Services Project

Supported runtime environments

This topic describes which runtime environments are supported for programs generated by Enterprise
Service Tools.
The following table shows which runtime environments are supported for programs that you generate
using Enterprise Service Tools:

Table 14. Supported Runtime Environments

Type of project: Supported runtime environments:
Web Services for • CICS Transaction Server for z/OS V3.1 and later
CICS Project
XML • CICS Transaction Server for z/OS V4.1 and later
Transformation for
CICS Project
JSON Services for • CICS Transaction Server for z/OS V4.2 and later
CICS project

© Copyright IBM Corp. 1992, 2024 133

Table 14. Supported Runtime Environments (continued)
Type of project: Supported runtime environments:
IMS Enterprise • Information Management System V10 and later, with integrated IMS Connect and with
Suite SOAP APAR PM11648.
Gateway Project
• IMS Enterprise Suite Version 1.1 SOAP Gateway
• The top-down scenario with IMS Enterprise Suite SOAP Gateway, compiled conversion,
and Enterprise PL/I language (see “IMS Enterprise Suite SOAP Gateway project” on
page 181) requires:
– Information Management System V11 with APAR PM16945.
– IMS Enterprise Suite Version 1.1 SOAP Gateway

Batch, TSO, z/OS Batch, TSO, and z/OS UNIX System Services environments for z/OS
UNIX System
Services Project

Web services development scenarios

This topic describes the Web services development scenarios.
The Web service development scenarios are bottom-up development, meet-in-middle development, and
top-down development (see “Web services development scenarios” on page 136).
Note: For single-service projects there are several project subtypes, based on the runtime environment
for which the project generates output files (shown in the Runtime column of Table 16 on page 135:

Table 15. Categories of Projects

Types of projects included in this
Category: category: Basis for categorization:
Single-service project • Web Services for CICS Project • Each of these types of projects
• XML Transformation for CICS helps you to generate files
Project associated with a single Web
service; and
• IMS Enterprise Suite SOAP
Gateway Project • The development process for
each of these types of projects is
• Batch, TSO, z/OS UNIX System similar.
Services Project

134 Developer for z/OS: Developing with Db2, CICS, and IMS
Table 16. Web Service Development Scenarios for Single-Service Projects in Enterprise Service Tools
Runtime: Tasks you can accomplish:
Web Services • Bottom-up development: Generate a Web service description and runtime-specific request
for CICS and response XML message processing from a high level language data structure. You can
Project use this method to create a service provider program (one that runs using Web Services for
CICS protocols) for an existing CICS application.
• Meet-in-middle development: Define mappings between high level language data
structures and WSDL, XML, or XSD files. You can use this method to generate runtime-
specific request and response XML message processing based on the mappings.
Note: You can use mapping to an Existing Service Interface (meet-in-middle) wizard when
you run the Enterprise Service Tools Wizard Launchpad inside the Enterprise Service
Tools perspective. Access to the wizard is still allowed when you run the wizard outside the
Enterprise Tools perspective (see “Contexts for starting the single-service wizards” on page
194).
• Top-down development: Generate a high-level language structure and runtime-specific
request and response XML message processing from a Web service description (WSDL file).
You can use this method to:
– Create a service provider program (one that runs using Web Services for CICS protocols)
for a new CICS application.
– Create a service provider program (one that runs using Web Services for CICS protocols)
for an existing CICS application.
– Create a service requester program (one that runs using Web Services for CICS
protocols).
See “Web Services for CICS project” on page 176.
XML • Bottom-up development: Generate files for the XML Transformation and runtime-specific
Transformation XML processing from a high level language data structure.
for CICS
• Top-down development: Generate a high-level language structure and runtime-specific
Project
XML processing from an XSD file.
Note: Meet-in-middle development is not supported.

IMS Enterprise • Bottom-up development: Generate a Web service description and runtime-specific request
Suite SOAP and response XML message processing from a high level language data structure. You can
Gateway use this method to create a service provider program (one that runs using IMS Enterprise
Project Suite SOAP Gateway protocols) for an existing IMS application.
• Meet-in-middle development: Define mappings between high level language data
structures and WSDL, XML, or XSD files. You can use this method to generate runtime-
specific request and response XML message processing based on the mappings.
• Top-down development: Create a new service implementation from the information in
a WSDL file (supported only for the IMS Enterprise Suite SOAP Gateway with compiled
conversion and Enterprise PL/I).
See “IMS Enterprise Suite SOAP Gateway project” on page 181.

Developing web services and SOA with Enterprise Service Tools 135
Table 16. Web Service Development Scenarios for Single-Service Projects in Enterprise Service Tools (continued)
Runtime: Tasks you can accomplish:
Batch, TSO, • Bottom-up development: Generate a Web service description and runtime-specific request
z/OS UNIX and response XML message processing from a high level language data structure. You can
System use this method to create a service provider program (one that is not runtime-specific) for
Services an existing CICS application.
Project
• Meet-in-middle development: Define mappings between high level language data
structures and WSDL, XML, or XSD files. You can use this method to generate non-runtime-
specific request and response XML message processing based on the mappings.
See “Batch, TSO, z/OS UNIX System Services project” on page 183.

Web services development scenarios

This topic and its subtopics describe major Web services development scenarios that are typical for a
Service Oriented Architecture (SOA). They also describe how Enterprise Service Tools helps to create
enterprise applications that fit the established patterns of Web services development.

The major Web services development scenarios that are typical for a Service Oriented Architecture are:
• Bottom-up development
• Meet-in-middle development
• Top-down development

Web service development scenarios: Single-service projects

This topic describes bottom-up, meet-in-middle, and top-down development of Web services in the
context of creating a single-service project.

This context applies to the following types of Enterprise Service Tools projects:
• Web services for CICS project
• IMS Enterprise Suite SOAP Gateway project
• Batch, TSO, z/OS UNIX System Services project
(see “Web services development scenarios” on page 134).
Create New Service Interface (bottom-up)
In this scenario you generate a Web service description and runtime-specific XML message processing
artifacts from a high level language data structure. This allows you to expose an application program as a
service provider.
You start with an existing COBOL application, select the interface language structure from it and generate
the needed artifacts to deploy it as a new Web service.
Map to an Existing Service Interface (meet-in-middle)
In this scenario, you define mappings between high level language structures and WSDL, XML, or XSD
files. You also can generate runtime-specific XML message processing based on the mappings.
You start with a WSDL file (or XML or XSD file) that defines the interface to an existing Web service and an
existing COBOL interface definition and mapping together related fields. After mapping is completed, you
generate compiled converters that follow the mappings.
Create New Service Implementation (top-down, CICS only)

136 Developer for z/OS: Developing with Db2, CICS, and IMS
 In this scenario you generate a high level language structure and runtime-specific XML message
processing from a Web service description.
You start with a WSDL document that defines an existing Web service and create a new application from
it that implements some or all of the functionality described in the Web service definition. The tool will
generate a template COBOL program code for either a new Web service provider or a new Web service
consumer. This new program uses language structures that correspond to the message elements for each
operation (operation-->input-->message-->part-->element, where element is an XML Schema type) to
process requests and issue replies.
To assist you in writing the new application, include files containing the language structure definitions are
generated as well as a COBOL template program which includes them.
Related tasks

“Setting preferences for COBOL XML converters” on page 145

Related reference

Create New Service Interface (bottom-up) wizard - Compiled XML conversion

“Create New Service Implementation (top-down)
wizard” on page 222

The Enterprise Service Tools perspective

The Enterprise Service Tools perspective provides views and editors that allow you to develop single-
service projects.
The following topics describe how to use the Enterprise Service Tools perspective.

Opening the Enterprise Service Tools perspective

The first step in using the Enterprise Service Tools is to open the Enterprise Service Tools perspective.
To open the Enterprise Service Tools perspective:
1. From the workbench menu bar, select Window > Perspective > Open Perspective > Other. The Open
Perspective window opens.
2. In the Open Perspective window, select Enterprise Service Tools and click OK.

The views in the Enterprise Service Tools perspective

The Enterprise Service Tools perspective contains views that allow you to develop projects.
To open a view that has been closed see “Opening or reopening a view” on page 144.
The views in Enterprise Service Tools perspective are:
EST Project Explorer:
Located by default on the left side of the Enterprise Service Tools perspective, the EST Project
Explorer view, known simply as the EST Project Explorer, displays a hierarchical and conceptual view
of the projects, subprojects, folders, and component artifacts in your workspace (see “The EST Project
Explorer” on page 138). In this view you can create new artifacts, rename artifacts, open artifacts for
editing, drag artifacts onto the flow editor canvas, or delete artifacts.
Navigator view:
Located by default on a tab behind the EST Project Explorer, the Navigator view displays a hierarchical
view of the actual files and folders in your workspace. You can use the Navigator view to store source
files (such as BMS files, COBOL files, PL/I files, WSDL files, HATS connection files, and HATS screen
files) that contain information that you plan to later import into a project. For example, you might
create a folder called My COBOL Files to contain COBOL source files. (To create a folder, right-click
over the Navigator view and then select New > Other > General > Folder). You can then copy files

Developing web services and SOA with Enterprise Service Tools 137
 from any directory on your hard disk to your My COBOL Files folder in the Navigator view simply by
using the drag feature provided by your operating system's user interface for moving or copying files.
Note: For some types of Enterprise Service Tools artifacts, there is not a one-to-one correspondence
between an artifact displayed in the EST Project Explorer and a single file in the Navigator view. The
information displayed for the artifact in the EST Project Explorer might be distributed among several
files and folders shown in the Navigator view.
Editor area:
Located by default in the central area of the Enterprise Services Tools perspective and extending to
the right side, the editor area provides a rectangular space for various editors that can be opened to
modify the various types of artifacts found in single-service projects.
The editor area is initially blank. You can open an editor by double-clicking an artifact in the EST
Project Explorer or by right-clicking an artifact and then selecting Open or Open With.
Outline view:
Located by default at the lower left of the Enterprise Service Tools perspective, the Outline view
displays information about an item currently being edited in the editor area. Depending on the editor,
the Outline view may allow you to perform editing actions as well as to view information.
Properties view:
Located by default at the lower right of the Enterprise Service Tools perspective the Properties view
displays information about an object selected in the editor area.
Tasks view:
The Tasks view allows you specify and prioritize tasks for your project.
Problems view:
As you work with resources in the workbench, various builders may automatically log problems,
errors, or warnings in the Problems view.

The EST Project Explorer

The EST Project Explorer displays a hierarchical and conceptual view of the projects, subprojects, folders,
subfolders, and artifacts in your workspace.
Version 15.0 and later: Service Flow Modeler is removed from the product, and Enterprise Service Tools
no longer supports service flow projects. If you open the product on a workspace that includes service
flow projects, they are shown in this perspective, but you cannot open or edit them. If you need to work
with the resources in a service flow project, you can open it in another view, such as the Project Explorer,
but the Service Flow Modeler tools are no longer available.
To open the EST Project Explorer if it has been closed see “Opening or reopening a view” on page 144. To
open the EST Project Explorer from another perspective see “Opening the EST Project Explorer view from
another perspective” on page 145.
The EST Project Explorer includes a main window, a toolbar, a drop-down menu, and a pop-up menu. You
can also create a new project by selecting File > New and selecting the type of project that you want to
create.
This help topic contains the following subtopics:
• “Main window” on page 139
• “Toolbar” on page 139
• “Drop-down menu (for creating new projects and artifacts)” on page 140
• “Pop-up menu” on page 141
• “Shortcuts to wizards” on page 143

138 Developer for z/OS: Developing with Db2, CICS, and IMS
Main window
The main window of the EST Project Explorer displays a tree view of the single-service projects that
are contained in your workspace, together with their component subprojects, folders, subfolders, and
artifacts (see “Folders and subfolders in a single-service project” on page 174).
In general, you can perform the following types of actions in the main window:

Table 17. Types of actions that you can perform in the main window
Action: Steps:
To create a new project Use either of the following:
• The drop-down menu (see “Drop-down menu
(for creating new projects and artifacts)” on page
140).
• The pop-up menu (see “Pop-up menu” on page
141).

To create a new subproject or artifact 1. Right-click the appropriate parent item.

2. Select New.
3. Select the type of new item from the contextual
menu.

To perform an action on an existing project, 1. Right-click the item.

subproject, or artifact
2. Select the action from the pop-up menu.

To edit an editable artifact 1. Right-click the item.

2. Select Open or Open With from the pop-up
menu.

To import information 1. Right-click the project, subproject, folder, or

subfolder into which you want to import the
information.
2. Select Import from the pop-up menu.
3. Select the type of item that you want to import.

Toolbar
The toolbar contains icons that affect EST Project Explorer:

Table 18. Icons on the toolbar

Icon: Command: Effect:
Collapse All This command collapses or
uncollapses the tree expansion
state of all resources in the EST
Project Explorer.

Developing web services and SOA with Enterprise Service Tools 139
 Table 18. Icons on the toolbar (continued)
Icon: Command: Effect:
Link editor to EST Project This command toggles whether
Explorer the selected resource in the EST
Project Explorer is automatically
linked to the active editor. When
this option is selected, and you
are using multiple editors in the
editor area:
• Selecting an editor (and
therefore making it topmost) in
the editor area automatically
causes the resource that
is being edited to become
selected in the EST Project
Explorer view.
• Similarly, selecting a resource
in the EST Project Explorer that
is being edited automatically
causes the editor that is
editing the resource to become
selected (topmost) editor in the
editor area.

(Drop-down menu) See “Drop-down menu (for

creating new projects and
artifacts)” on page 140.

Drop-down menu (for creating new projects and artifacts)

To open the drop-down menu:
1. Select an item in the EST Project Explorer.
2. On the toolbar at the top of the EST Project Explorer toolbar, on the right side, click the downward-
pointing triangle icon.
3. The drop-down menu opens.
The drop-down menu contains entries that allow you to create a new project or a new artifact. Some
of the entries on the drop-down menu are always enabled (the entries that create new projects). Other
entries are enabled depending on the type of item that you selected in the EST Project Explorer.
Note:
• All of the entries on the drop-down menu are also available on the pop-up menu (see “Pop-up menu”
on page 141).
• You can also create a new project from the main menu of the workbench by selecting File > New (see
“Shortcuts to wizards” on page 143).
The entries on the drop-down menu are:

Table 19. Entries on the drop-down menu

Menu entry: Description
Web Services for CICS Project Starts the New Web Services for CICS Project
wizard

140 Developer for z/OS: Developing with Db2, CICS, and IMS
Table 19. Entries on the drop-down menu (continued)
Menu entry: Description
JSON Services for CICS Project Starts the New JSON Services for CICS Project
wizard
XML Transformation for CICS Project Starts the New XML Transformation for CICS
Project wizard
IMS Enterprise Suite SOAP Gateway Project Starts the New IMS Enterprise Suite SOAP Gateway
Project wizard
Batch, TSO, z/OS UNIX Project Starts the New Batch, TSO, z/OS UNIX Project
wizard

Pop-up menu
The pop-up menu and its submenus include:
• The main pop-up menu
• The New submenu
• The Import submenu
• The Generate submenu
Some of the entries on the pop-up menu and its submenus are always present and enabled. Other entries
are present and enabled depending on the type of the currently selected item in the EST Project Explorer.
(a) Main pop-up menu:
To open the main pop-up menu:
1. Right-click an item in the EST Project Explorer, or right-click over a blank area anywhere in the EST
Project Explorer.
2. The pop-up menu opens.
The entries that can occur on the main pop-up menu are:

Table 20. Entries on the main pop-up menu

Menu entry: Description
New Opens the New submenu (see (b) New submenu)
Import Opens the Import submenu (see (c) Import
submenu).
Add Subproject Starts the Add a Subproject wizard
Open Opens the selected artifact using the editor that
was most recently used to open that type of
artifact
Open With Opens the Open With submenu, which contains an
entry for each editor capable of opening the type of
artifact selected.
Refresh Updates the EST Project Explorer window
Delete Deletes the selected artifact
Generate Opens the Generate submenu (see (d) Generate
submenu)

Developing web services and SOA with Enterprise Service Tools 141
 Table 20. Entries on the main pop-up menu (continued)
Menu entry: Description
Rename Opens the Rename Resource window
Generate Web Services for CICS resources Opens one of the following wizards:
Generate XML Transformation for CICS resources • Opens the Enterprise Service Tools Wizard
Launchpad, if you have not already used this
Generate IMS Enterprise Suite SOAP Gateway project to generate any resources.
resources
• Opens the Create New Service Interface wizard,
Generate Batch, TSO, z/OS UNIX resources if you have already used this project to generate
resources to create a new service interface.
• Opens the Map an Existing Service Interface
wizard, if you have already used this project to
generate resources to map an existing service
interface.

(b) New submenu:

The entries that appear on the New submenu depend on the type of the currently selected item in the EST
Project Explorer:

Table 21. Entries on the New submenu

Menu entry: Description
Web Services for CICS Project Starts the New Web Services for CICS Project
wizard
XML Transformation for CICS Project Starts the New XML Transformation for CICS
Project wizard
JSON Services for CICS Project Starts the New JSON Services for CICS Project
wizard
IMS Enterprise Suite SOAP Gateway Project Starts the New IMS Enterprise Suite SOAP Gateway
Project wizard
Batch, TSO, z/OS UNIX Project Starts the New Batch, TSO, z/OS UNIX Project
wizard

(c) Import submenu:

The entries that appear on the Import submenu depend on the type of the currently selected item in the
EST Project Explorer:

Table 22. Import submenu

Menu selection: Description:
Import > WSDL Starts the Import Web Services Definitions wizard.
Import > COBOL Starts the Import COBOL Files wizard.
Import > PL/I Starts the Import PL/I Files wizard
Import > BMS Starts the Import BMS wizard.
Import > HATS Connections Starts the Import HATS connection wizard.
Import > HATS Screens Starts the Import HATS Screen wizard.
Import > CICS Web Service Starts the Import Web Service Definitions wizard.

142 Developer for z/OS: Developing with Db2, CICS, and IMS
 When a single-service project is selected in the EST Project Explorer, the Import submenu contains the
following entries:

Table 23. Import submenu when a single-service project is selected

Menu selection: Description:
Import > Source files Starts the Import Source Files wizard

(d) Generate submenu:

The entries that appear on the Generate submenu depend on the type of the currently selected item in
the EST Project Explorer:

Table 24. Generate submenu

Menu selection: Description:
Generate Runtime Code Starts the Generate Runtime Code wizard
Client Requester Starts the Generate Client Requester wizard.

Shortcuts to wizards
To create a new project, or to create certain types of artifacts, you can also launch a wizard from the main
menu of the workbench (see “Shortcut to wizards” on page 143).

Support for WSRR actions on the EST Project Explorer view

This topic describes how WebSphere® Service Registry and Repository (WSRR) is supported in an EST
project explorer.

After installing the WSRR Eclipse user interface product on top of Developer for z/OS, the pop-up menu
for a Web Services Description Language (WSDL) document in EST project explorer shows the actions in
Figure 3 on page 143.

Figure 3. WSRR Actions in EST Project Explorer

For information on how to manage services in WSRR Eclipse user interface, see: http://www-01.ibm.com/
support/knowledgecenter/
For additional information on how to install and configure the Eclipse user interface, see: http://
www-01.ibm.com/support/knowledgecenter/

Shortcuts to wizards and views

You can use File > New to open wizards and Show > View to open views for the Enterprise Service Tools.

Shortcut to wizards
This shortcut is for opening wizards that create new Enterprise Service Tools projects. To use this
shortcut:
1. Make sure that the Enterprise Service Tools perspective is open and that it is the currently selected
perspective.
2. On the main menu of the workbench select File > New.

Developing web services and SOA with Enterprise Service Tools 143
 3. Select the menu item for the wizard that you want to open (see Table 25 on page 144):

Table 25. Items on the File > New menu that start wizards
Menu item: Wizard:
CICS Web Services Project New Web Services for CICS Project
JSON Services for CICS Project New JSON Services for CICS Project
XML Transformation for CICS Project New XML Transformation for CICS Project
IMS Enterprise Suite SOAP Gateway Project New IMS Enterprise Suite SOAP Gateway Project
Batch, TSO, z/OS UNIX Project New Batch, TSO, z/OS UNIX Project

Shortcut to views
When the Enterprise Service Tools perspective is the currently selected perspective, you can open the
following views by selecting Window > Show View on the main menu of the workbench and then
selecting the name of the view:
• EST Project Explorer
• Navigator
• Outline
• Problems
• Properties
• Remote Systems

Resetting the Enterprise Service Tools perspective or opening a view

This topic describes how to reset the Enterprise Service Tools perspective to its default arrangement of
views and how to open or reopen a view in the Enterprise Service Tools perspective.

Resetting the Enterprise Service Tools perspective

Resetting the Enterprise Service Tools perspective restores the views in the perspective to their default
arrangement.
To show the Enterprise Service Tools perspective in its default arrangement of views:
1. Make sure that the Enterprise Service Tools perspective is the currently selected perspective.
2. On the main menu of the workbench, click Window > Reset Perspective.
3. Click OK when the program queries, "Do you want to reset the current Enterprise Service Tools
perspective to its defaults?".

Opening or reopening a view

Select Window > Show View to open or reopen a view in the Enterprise Service Tools perspective.
To open or reopen a view in the Enterprise Service Tools perspective:
1. Make sure that the Enterprise Service Tools perspective is the currently selected perspective.
2. On the main menu of the workbench, select Window > Show View > <EST_view>, where <EST_view>
is one of the following:
• EST Project Explorer
• Navigator
• Outline

144 Developer for z/OS: Developing with Db2, CICS, and IMS
 • Problems
• Properties
• Remote Systems
To open the EST Project Explorer view when the Enterprise Service Tools perspective is not opened or
is not the current perspective, see “Opening the EST Project Explorer view from another perspective” on
page 145.

Opening the EST Project Explorer view from another perspective

Select Window > Show View > Other to open the EST Project Explorer from another perspective.
The EST Project Explorer view is called simply the EST Project Explorer.
To open the EST Project Explorer when the Enterprise Service Tools perspective is not opened or is not
the currently selected perspective:
1. On the main menu of the workbench, select Window > Show View > Other. The Show View window
opens.
2. In the Show View window:
a. Select Enterprise Service Tools > EST Project Explorer.
3. Click OK.

Setting preferences for the Enterprise Service Tools

This topic and its subtopics describe how to set preferences for the Enterprise Service Tools.

Setting overall preferences

To set overall preferences for working with the Enterprise Service Tools:
1. In the left pane of the Preferences window, select Enterprise Service Tools.
2. Change the preferences. The preferences are shown in this table.

Table 26. Overall preferences for Enterprise Service Tools

Option: Effect of this option:
Show file extensions in the EST Project This checkbox controls whether the files in the EST
Explorer view Project Explorer are displayed with or without their file
extensions:
• Select the checkbox to show the file extensions. (This is
the default.)
• Clear the checkbox to hide the file extensions.

3. Click OK when done.

Setting preferences for COBOL XML converters

To set preferences for COBOL XML converters, open the COBOL XML Converters page in the Enterprise
Service Tools preferences.
These preferences affect single-service projects, including:
• Web Services for CICS
• JSON Services forCICS project
• XML Transformation for CICS
• IMS Enterprise Suite SOAP Gateway

Developing web services and SOA with Enterprise Service Tools 145
 • Batch, TSO, z/OS UNIX System Services
These preferences affect how runtime XML conversion programs generated by single-service wizards
in the Enterprise Service Tools convert data between the XML format used in service requests and
responses and the high-level language data structures used by COBOL:
To set generation preferences for runtime XML conversion programs:
1. In the left pane of the Preferences window, select Enterprise Service Tools.
2. Change the preferences:
a. The preferences on the Basic tab are described in the following table:

Preference: Effect of this preference:

Converter program This input field specifies the stem of the program name that is
name prefix included in the IDENTIFICATION DIVISION of each generated COBOL
program. If you type ACCT, for example, the wizard identifies the input
converter program as ACCTI, the output converter program as ACCTO,
and the driver as ACCTD
Author name This input field specifies the character string to be included in the
AUTHOR paragraph of each generated COBOL program.
Request code page This list box specifies the code page to be used for encoding the
request XML message.
Host code page This list box specifies the code page that is used by the z/OS host
system.
Response code page This list box specifies the code page to be used for encoding the
response XML message.
Decimal point is comma This checkbox controls how the comma and period characters are
interpreted in numeric strings:
• When you select this checkbox:
– A comma is interpreted as a decimal point.
– A period is interpreted as a thousands separator.
• When you clear this checkbox (this is the default setting):
– A comma is interpreted as a thousands separator.
– A period is interpreted as a decimal point.

3. The preferences on the Advanced tab are as follows:

• In the Specify XML Schema generation options group:
Generate minimum hierarchy in XML Schemas
This checkbox controls the message format of the generated XML schema and consequently the
parsing and generation of XML in the XML converters. XML converters based on XML schemas
having minimized hierarchies tend to have better performance.
– Select this checkbox if you want the XML converters to be generated so as to use a reduced
XML structure hierarchy, when a more detailed structure hierarchy is not needed to uniquely
identify each element in the structure.
When there are elements with the same tag name, the name of the element that occurs later
in the document is prefixed with as many of its parent tags as are required to produce a unique
name. This method increases the efficiency of message processing clients and reduces the
number and complexity of objects that need to be instantiated.
– Clear this checkbox if you want the wizard to generate an XML schema that represents the full
hierarchy of the language structure.

146 Developer for z/OS: Developing with Db2, CICS, and IMS
Generate groups in XML Schemas
This checkbox controls whether the XML converter includes groups in the generated XML
schemas:
– Select this checkbox if you want the XML converter to include groups in the generated XML
schemas.
– Clear this checkbox if you want the XML converter to include group "contents" inline instead
of using group references. This option is useful for applications that do not support the use of
groups and group references in XML schemas.

Generate short complex type names

The normal method for generating a complex type name is to concatenate the name of the group
to the names of all the parents of the group, with an underscore character "_" after each name
except the last.
However, if this checkbox is selected, then a complex type name is generated by taking just the
name of the group.
For example, in this COBOL group:

01 ServiceRequest.
02 CommonHeader.
05 HeaderType1.
10 Element1 PIC X(10).

the complex XML type name for the HeaderType1 element is:
– servicerequest_commonheader_headertype1 if the checkbox is not selected.
– HeaderType1 if the checkbox is selected.
The shortening of complex type names allows for the generation of more compact client code
(usually, Java class code) from the WSDL and XSD files containing the complex XML types.
The setting of this checkbox has no effect on top-down or meet-in-middle scenarios.
When shortening of a complex type name is attempted, a collision is possible if the short name
of the type already exists as the result of a previously defined type for a group with an identical
name but different parent group names. For example, in the following COBOL structure:

01 ServiceRequest.
02 CommonHeader.
05 HeaderType.
10 Element PIC X(10).
02 SpecificHeader.
05 HeaderType.
10 Element PIC X(10).

the type name of the HeaderType group under SpecificHeader collides with the type name
of the HeaderType group under CommonHeader.
In case of a collision all colliding names keep the original long type names. Thus, based on this
example, the resulting type names are:
– servicerequest_commonheader_headertype and
– servicerequest_specificheader_headertype.
The short name for a complex type is formed by taking the name of the XML element that has
that type, plus some possible modifications. The rules for forming short names are:
a. Take the name of the XML element that has the type (such as HeaderType1).
b. If the name starts with a character that is an invalid character for Java names (for example, a
digit), it is prefixed with a double underscore "__".

Developing web services and SOA with Enterprise Service Tools 147
 c. If a hyphen "-" is present in the original COBOL group name it is replaced with a single
underscore "_".
d. The case of the group name is preserved.
For example, the following group:

03 2-In--B.
04 var2 blank zero pic 999.99.

results in the shortened complex type name __2_In__B.

Generate comments in XSD

Select this checkbox to cause the comments from the COBOL source code file to be generated as
annotation documentation in the generated XSD and WSDL files (see “Including COBOL source
code comments in generated XSD and WSDL files” on page 327)
This option applies only to the bottom-up development scenario for generating a Web service,
and applies only if you specify Compiled XML Conversion.

Generate qualified XML elements in XML schemas

This checkbox allows for generation of qualified XML elements in the XML schemas.
This allows for the option to require all XML elements be qualified with a namespace and
support generation of XML schemas that can be included in other schemas with lesser chance of
namespace collision.

• In the Specify Request XML converter behavior group:

Validate root element namespace name
Select this checkbox to enable validation of the target namespace of the root element in XML
documents. The target namespace of the root element can be found in the XML schema which
defines it.

Use VALUE literals to initialize omitted data items

Select this checkbox to enable initialization for data items in the request language structure that
you have excluded from the Web service input data structure (see “Initializing data items in the
COBOL application's input data structure” on page 325 ).
This option applies only to the bottom-up development scenario for generating a Web service,
and applies only if you specify Compiled XML Conversion.

Use VALUE literals to initialize empty data items

Select this checkbox to enable initialization for data items in the request language structure that
you have included in the Web service input data structure (see “Initializing data items in the
COBOL application's input data structure” on page 325 ).
This option applies only to the bottom-up scenario for generating a Web service, and applies only
if you specify Compiled XML Conversion.

• In the Specify response XML converter behavior group:

Language data
This option controls how the response runtime XML conversion program handles characters in
the response COBOL data that are illegal in the XML 1.0 specification:
– Select Filter characters illegal in XML 1.0 if you want the conversion program to scan both
non-numeric and numeric data in the language structure and convert any character that is
illegal in the XML 1.0 specification to an EBCDIC, ASCII, or UNICODE space (depending on the
response code page).
– Select Halt on characters illegal in XML 1.0 if you want the conversion program to scan both
non-numeric and numeric data in the language structure and cause an exception if characters
illegal in XML 1.0 are found.

148 Developer for z/OS: Developing with Db2, CICS, and IMS
 – Select Do not check for illegal characters if you want the conversion program not to check for
characters that are illegal in the XML 1.0 specification.
For more information see “Options for handling illegal XML characters” on page 325.

• In the Specify compiler-related preferences group::

Optimization
Select whether the optimization option is enabled for the COBOL compiler. When the checkbox
is selected, the COBOL compiler will use optimization in generating runtime code from COBOL
source code.
If you are trying to debug a compile error in your COBOL source code, it is a good idea to clear
this checkbox and recompile. Without optimization turned on, it is easier to determine which part
of the COBOL source code is causing the error.

Specify Enterprise COBOL compiler version

Select the version of the COBOL compiler that you want to use.

4. Click OK when done.

Setting preferences for PL/I XML converters

To set preferences for PL/I XML converters, open the PL/I XML Converters page in the Enterprise Service
Tools preferences.
Setting the preferences for PL/I XML converters affect single-service projects, including:
• Web Services for CICS
• JSON Services forCICS project
• XML Transformation for CICS
• IMS Enterprise Suite SOAP Gateway
• Batch, TSO, and z/OS UNIX System Services
These preferences affect how runtime XML conversion programs generated by single-service project
wizards in the Enterprise Service Tools convert data between the XML format used in service requests and
responses and the high-level language data structures used by PL/I:
To set generation preferences for runtime XML conversion programs:
1. In the left pane of the Preferences window, select PL/I XML Converters
2. Change the preferences:
a. The preferences on the Basic tab are described in the following table:

Preference: Effect of this preference:

Converter program This input field specifies the entry label for the procedure. If you type
name prefix ACCT, for example, the wizard identifies the input converter program
as ACCTI, the output converter program as ACCTO, and the driver as
ACCTD
Author name This input field is embedded as a PL/I comment.
Request code page This list box specifies the code page to be used for encoding the
request XML message.
Host code page This list box specifies the code page that is used by the z/OS host
system.
Response code page This list box specifies the code page to be used for encoding the
response XML message.
3. Click OK when done.

Developing web services and SOA with Enterprise Service Tools 149
Setting preferences for the CICS Web Services Assistant (WSBind)
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” on page 411)
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” on page
262). 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):

150 Developer for z/OS: Developing with Db2, CICS, and IMS
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

Developing web services and SOA with Enterprise Service Tools 151
 • 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. .

152 Developer for z/OS: Developing with Db2, CICS, and IMS
 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

Developing web services and SOA with Enterprise Service Tools 153
 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

154 Developer for z/OS: Developing with Db2, CICS, and IMS
 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.

Developing web services and SOA with Enterprise Service Tools 155
 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.

156 Developer for z/OS: Developing with Db2, CICS, and IMS
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:
• DFHWS2LS: WSDL to high-level language conversion
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

Developing web services and SOA with Enterprise Service Tools 157
 <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.

Setting preferences for the CICS JSON Assistant

To set preferences for the CICS® JSON Assistant, open the Web Services Assistant (WSBind) page in the
Enterprise Service Tools preferences. These options affect the generated JSON and language structure
files.
These preferences affect the generation of resources only when you are generating files for the JSON
Services for CICS runtime environment. These preferences do not affect the generation of resources for
the other runtime environments.
To set preferences for the JSON Services Assistant:
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 JSON services assistant

The preferences on this page affect the values that the Enterprise Service Tools passes as input
parameters to the CICS JSON assistant. The CICS JSON 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 JSON service or for calling an existing JSON Web service.
The CICS JSON assistant is invoked by the following wizards or utilities in the Enterprise Service Tools:
• Create New Service Interface (bottom-up) wizard

158 Developer for z/OS: Developing with Db2, CICS, and IMS
• Create New Service Implementation (top-down) wizard)
Again, the CICS JSON assistant is invoked only when generating output files for the JSON Services for
CICS runtime environment.
The JSON assistant includes two procedures, DFHLS2JS and DFHJS2LS:
• DFHLS2JS generates a JSON service description and a JSON 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).
• DFHJS2LS generates a high level language data structure and a JSON service binding file from a JSON
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).
Limitation:
• JSON-SCHEMA-CODEPAGE of DFHLS2JS is not supported.

Preferences on the Common tab

The preferences on the Common tab are passed to the JSON 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 JSON 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.

Developing web services and SOA with Enterprise Service Tools 159
 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

160 Developer for z/OS: Developing with Db2, CICS, and IMS
 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 JSON Assistant as the parameter: MINIMUM-
RUNTIME-LEVEL)
This preference specifies the minimum CICS runtime environment that the JSON 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 JSON 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 JSON Web service binding file deploys successfully into a CICS TS 3.1 region that
has at least APAR PK15904 applied.
1.2
The generated JSON 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 JSON Web service binding file deploys successfully into a CICS TS 3.2.
2.1
The generated JSON Web service binding file deploys successfully into a CICS TS 3.2 that has
APAR PK59794 applied.
3.0
The generated JSON 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.

Developing web services and SOA with Enterprise Service Tools 161
 CURRENT
The generated JSON 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 JSON Web service binding
file.
CCSID: (This is displayed in the JSON Assistant as the parameter: CCSID)
Specifies the CCSID that is used at run time to encode data between the application program and
the JSON 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 JSON Web service binding file is encoded in
US EBCDIC (Cp037).
User ID: (This is displayed in the JSON 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 JSON 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 JSON 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 JSON 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 JSON 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 JSON 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 JSON 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.

162 Developer for z/OS: Developing with Db2, CICS, and IMS
Preferences on the DFHLS2JS tab
The preferences on the DFHLS2JS tab are passed to the JSON 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 JSON 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.
Date/Time: (This is displayed in the JSON 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.
Overwrite output: (This is displayed in the JSON Assistant as the parameter: OVERWRITE-OUTPUT)
Controls whether existing CICS BUNDLEs on the file system can be overwritten.
• NO
Any existing BUNDLE is not replaced. If an existing BUNDLE is found DFHJS2LS issues error
message DFHPI9689E and terminates.
• YES
Any existing BUNDLE is replaced. If an existing BUNDLE is found then message DFHPI9683W is
issued to inform you that the file has been replaced.
Char occurs: (This is displayed in the JSON 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

Developing web services and SOA with Enterprise Service Tools 163
 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 JSON 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 JSON 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 JSON 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 DFHJS2LS tab

The preferences on the DFHLS2JS tab are passed to the JSON 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 JSON 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 JSON 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.

164 Developer for z/OS: Developing with Db2, CICS, and IMS
 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 array maxItems: (This is displayed in the JSON Assistant as the parameter: DEFAULT-ARRAY-
MAXITEMS)
This preference specifies the maximum array boundary to apply, where no maximum occurrence
information (maxItems) is implied in the JSON schema. If this parameter is not set, no maximum limit
is applied. The value of this parameter can be a positive integer in the range 1 to 2147483647. This
parameter can be combined with use of the INLINE-MAXOCCURS-LIMIT parameter to influence how
JSON arrays are mapped into the language structures.
Default char max length: (This is displayed in the JSON 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 JSON 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 JSON Assistant as the parameter: DEFAULT-FRACTION-
DIGITS)
This preference specifies the default number of fraction digits to use on a JSON decimal schema type.
The default 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 JSON 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 JSON 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:
• DFHWS2LS: WSDL to high-level language conversion
Date/Time: (This is displayed in JSON 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 JSON 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 JSON 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.

Developing web services and SOA with Enterprise Service Tools 165
 Overwrite output: (This is displayed in the JSON Assistant as the parameter: OVERWRITE-OUTPUT)
Controls whether existing CICS BUNDLEs on the file system can be overwritten.
• NO
Any existing BUNDLE is not replaced. If an existing BUNDLE is found DFHJS2LS issues error
message DFHPI9689E and terminates.
• YES
Any existing BUNDLE is replaced. If an existing BUNDLE is found then message DFHPI9683W is
issued to inform you that the file has been replaced.
Char white space: (This is displayed in the JSON Assistant as the parameter: CHAR-WHITE-SPACE)
Specifies how white space in values of type string is handled by CICS. The default is COLLAPSE.
• COLLAPSE
• REPLACE
• PRESERVE
COLLAPSE
Leading, trailing, and embedded white space is removed and all tabs, new lines, and consecutive
spaces are replaced with single space characters.
REPLACE
Any tabs or new lines are replaced with the appropriate number of spaces.
PRESERVE
Retains any white space in the data value.
Underscores as hyphens (This is displayed in the JSON 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.
Integer as PIC 9: (This is displayed in the JSON Assistant as the parameter: INTEGER-AS-PIC9)
For COBOL and DFHJS2LS only. This parameter generates language structures which contain integer
values from the JSON schema as numerals rather than alphanumeric characters.
No array name indexing: (This is displayed in the JSON Assistant as the parameter NO-ARRAY-NAME-
INDEXING)
This preference is for COBOL and PL/I. Ensures that the field names in an array are unique only within
the scope of the higher level structure.
Hyphens as Underscores: (This is displayed in the JSON Assistant as the parameter: HYPHENS-AS-
UNDERSCORES)
For PL/I only. This parameter converts any hyphens in the JSON schema to underscores rather than
the character X, to improve the readability of the generated PL/I language structures.
Less duplicate names: (This is displayed in the JSON 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.
Additional properties default: (This is displayed in the JSON Assistant as the parameter ADDITIONAL-
PROPERTIES-DEFAULT)
It is selectable when the mapping level is 4.2 or higher.
Additional properties settings: (This is displayed in the JSON Assistant as the parameters
ADDITIONAL-PROPERTIES-MAX and ADDITIONAL-PROPERTIES-SIZE)
It is enabled when Additional properties default is selected.
• Additional properties max: You can specify an integer for the maximum number of additional
properties in the range 0-20. The default value is blank, which means unbounded.
• Additional properties size: You can specify an integer for the size in bytes in the range 16-32767.
The default value is 255.

166 Developer for z/OS: Developing with Db2, CICS, and IMS
Setting preferences for the CICS XML Transformation Assistant (XSDBind)
To set preferences for the CICS XML Transformation Assistant (XSDBind), open the XML Assistant
(XSDBind) page in the Enterprise Service Tools preferences. These options affect the generated XSDBind
and language structure files.
These preferences affect the generation of resources only when you are generating files for the XML
Transformation for CICS runtime environment. These preferences do not affect the generation of
resources for the other runtime environments.
To set preferences for the XML Transformation Assistant (XSDBind):
1. In the left pane of the Preferences window, expand Enterprise Service Tools and select XML
Transformation Assistant (XSDBind).
2. Change the preferences (the preferences are described in the following sections).
3. Click OK when done.

The XML transformation assistant

The preferences on this page affect the values that the Enterprise Service Tools passes as input
parameters to the XML transformation assistant. The XML transformation assistant is a set of batch
utilities, provided in CICS Transactions Server V5.2 or later, that generate necessary for creating a new
CICS XML Transformation service.
The XML transformation assistant is invoked by the following wizards or utilities in the Enterprise Service
Tools:
• Create New XML Transformation (bottom-up) wizard
• Create New XML Transformation (top-down) wizard
• Command-line batch processor (see “Batch processor” on page 411)
Note: The Map an Existing Service Interface (meet-in-middle) wizard is not supported.
Again, the XML transformation assistant is invoked only when generating output files for the XML
Transformation for CICS runtime environment.
The XML transformation assistant includes two procedures, DFHLS2SC and DFHSC2LS:
• DFHLS2SC generates an XML schema and an XML binding file from a high level language data structure.
• DFHSC2LS: generates a high level language data structure(s) and an XML binding file from either (1) an
XML schema or (2) the types section of a WSDL file.
The XML transformation assistant is invoked whether you select compiled runtime XML conversion or
interpretive runtime XML conversion (see “Runtime XML conversion: compiled or interpretive” on page
262). The type of XSDBind file generated depends on the type of runtime XML conversion that you select:
• A Native-interface XSDBind file is generated if you select interpretive runtime XML conversion.
• A Vendor-interface XSDBind file is generated if you select compiled runtime XML conversion.
Limitation: XMLCP of DFHLS2SC is not supported.

Preferences on the Common tab

The preferences on the Common tab are passed to the XML transformation 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 XML Transformation 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:

Developing web services and SOA with Enterprise Service Tools 167
 • 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.
• Mapping levels 1.0 to 4.1 are supported in CICS TS 5.3 with APAR PI67641 applied.
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 DFHLS2SC tab and the DFHSC2LS 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.
2.1
Use this mapping level for CICS TS 3.2 and later with APAR PK59794 applied. At this level you can
use the following features:
• INLINE-MAXOCCURS-LIMIT
See the description of the Inline maxOccurs limit preference on the DFHSC2LS tab (see Inline
maxOccurs limit).
Support has been added for the XML schema element <xsd:any> and the data type xsd:anyType
(for DFHSC2LS) (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.

168 Developer for z/OS: Developing with Db2, CICS, and IMS
 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.
Minimum runtime level: (This is displayed in the XML Transformation Assistant as the parameter:
MINIMUM-RUNTIME-LEVEL)
This preference specifies the minimum CICS runtime environment that the XML 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.
3.0
The generated XML 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.
CURRENT
The generated XML binding file deploys successfully into a CICS region at the highest available
runtime level as the one you are using to generate the XML binding file.
CCSID: (This is displayed in the XML Transformation Assistant as the parameter: CCSID)
Specifies the CCSID that is used at run time to encode data between the application program and
the XML 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 XML binding file is encoded in US EBCDIC
(Cp037).
Data Truncation: (This is displayed in the XML Transformation 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 XML Transformation 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 set to DISABLED, data values in application-supplied runtime data that are
inconsistent with the language structure are replaced by default values.

Developing web services and SOA with Enterprise Service Tools 169
 Preferences on the DFHLS2SC tab
The preferences on the DFHLS2SC tab are passed to the XML transformation 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 XML Transformation 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.
Date/Time: (This is displayed in the XML Transformation 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 XML Transformation 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 XML Transformation 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

170 Developer for z/OS: Developing with Db2, CICS, and IMS
 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 XML transformation Assistant as the parameter
TRUNCATE-NULL-ARRAYS)
This preference specifies how structured arrays are processed. If enabled, CICS will attempt to
recognize empty records within an array.
Truncate null array values: (This is displayed in the XML transformation 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 list
separated by commas.
• NULL
0x00, or low-values is treated as empty
• SPACE
0x40 is treated as empty
• ZERO
0xF0 is treated as empty

Preferences on the DFHSC2LS tab

The preferences on the DFHSC2LS tab are passed to the XML transformation assistant only when
the scenario type is Create New XML Transformation (top-down)and the runtime XML conversion type
is interpretive. (The batch processor equivalent of Create New XML Transformation (bottom-up 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 XML Transformation 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 XML Transformation 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.

Developing web services and SOA with Enterprise Service Tools 171
 Default char max length: (This is displayed in the XML Transformation 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 XML Transformation 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 XML Transformation 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 XML Schema. For a full
description see:
• Variable arrays of elements
Date/Time: (This is displayed in the XML Transformation 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 XML Transformation 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
This is the default value. 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 XML Transformation 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.
Less duplicate names (This is displayed in the XML Transformation 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 XML Transformation 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.

172 Developer for z/OS: Developing with Db2, CICS, and IMS
 Hyphen as underscores: (This is displayed in the XML Transformation 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.
Default fraction digits: (This is displayed in the XML Transformation 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.

Developing single-service projects

This section describes how to develop single-service projects.

Introduction to single-service projects

This group of topics describes single-service projects and how to use them.

Single-service projects
A single-service project is a project that generates files for a single Web service or XML transformation.
File generation for a single-service project can be done either through a single-service wizard or through
the batch processor.
Single-service projects can generate files for the runtimes shown in Table 27 on page 173. Notice that a
different type of single-service project is required for each runtime environment:

Table 27. Single-service projects and associated runtime environments

Type of single-service project: Associated runtime environment:
Web Services for CICS project Web services for CICS runtime environment
XML Transformation for CICS project XML Transformation for CICS runtime environment
JSON Services for CICS project JSON Services for CICS runtime environment
IMS Enterprise Suite SOAP Gateway project IMS Enterprise Suite SOAP Gateway runtime
environment
Batch, TSO, z/OS UNIX System Services project Unspecified runtime environment

For more information about the types of single-service projects see the following two topics:
• “The types of single-service projects” on page 176
• “Web services development scenarios” on page 134
A single-service project and its folders and subfolders are displayed in the EST Project Explorer view of
the Enterprise Service Tools perspective (see “Folders and subfolders in a single-service project” on page
174).
You can create multiple single-service projects (of any of the types of single-service project) within
the EST Project Explorer. Each single-service project is self-contained and cannot reference resources
in another single-service project. However, you can copy resources from one single-service project to
another.
To see the actual file structure of your workspace, look in the workbench's Navigator view (see Opening
the Navigator view). You may sometimes want to use the Navigator view to move or copy a file that is not
displayed in the EST Project Explorer.

Developing web services and SOA with Enterprise Service Tools 173
 Folders and subfolders in a single-service project
This topic describes the folders and subfolders in a single-service project.
A single-service project provides an organizational framework for the source files and the generated files
used in the project. A single-service project can contain the following folders and subfolders:
• A Source folder
• A Generation folder
• A Generation\Target subfolder
• A Deployment folder (created when the deployment operations are requested in the generation
wizards)
• A META-INF folder (created when the deployment operations are requested in the generation wizards)
The Source folder holds files that contain source code or other information that Enterprise Service
Tools needs to generate Web service files. You import these source files into your projects using the
Import Source Files wizard. The following table shows the types of files that you might import into the
Source folder, depending on the type of development that you are doing (bottom-up, meet-in-middle, or
top-down):

File extension: Type of file:

.cbl, .cob, .cpy .ccp COBOL source file or copy book
.pli, .mac, .inc PL/I source file or include file
.wsdl File describing the interface of a Web service
.xsd File describing a request or response data mapping

The Generation folder and its Target subfolder contain the files that you generate for the single-service
project. Typically the Generation folder contains the files shown in the following table:

File name: Purpose:

Container.xml Identifies the next two files.
PlatformProperties.xml Contains a list of the properties that you specified
when you generated the output.
ServiceSpecification.xml Contains a Web service specification.

The following table shows the types of files that might be generated in the Generation\Target subfolder,
depending on the type of development that you are doing (bottom-up, meet-in-middle, or top-down):

File extension: Type of file:

.wsdl A file describing the interface of a Web service.
.xsd A request XML schema definition or a response XML schema definition.
.wsbind A Web service binding file.
.cbl A COBOL source file that could be:
• A Web service driver program that includes a request XML converter program
and a response XML converter program; or
• A template file for a service requester program or a service provider
program.

.cpy A COBOL copy book file that contains the request language structure or the
response language structure for a WSDL operation.

174 Developer for z/OS: Developing with Db2, CICS, and IMS
File extension: Type of file:
.pli A PL/I source file that is Web service driver program that includes a request
XML converter program and a response XML converter program.

The Deployment folder (depending on the project) contains:

• .admr file (Application Deployment Manager Manifest) when the project is Web Services for CICS project
or
• .jar file (deployment bundle) when the project is XML Transformation for CICS project
The META-INF folder contains a cics.xml, the bundle manfiest file, for XML Transformation for CICS
resource.

The single-service wizards

Each of the single-service wizards generates a set of Web service files for a particular development
scenario.
The single-service wizards are:
• Create New Service Interface (bottom-up) wizard
• Map to an Existing Service Interface (meet-in-middle) wizard
• Create New Service Implementation (top-down) wizard
• Create New XML Transformation wizard (bottom-up or top-down)
These wizards present similar user interfaces but each offers a different set of pages and options,
depending on the following four parameters (not every possible combination of parameters is supported):
• z/OS runtime: The runtime environment for which the Web service files are to be generated. The
following z/OS runtimes are supported
– Web Services for CICS
– XML Transformation for CICS
– JSON Services for CICS
– IMS Enterprise Suite SOAP Gateway
– Batch, TSO, and z/OS UNIX System Services
• Development scenario: Bottom-up, Meet-in-Middle, or Top-Down.
• Application mode: Service Provider or Service Requester. This parameter determines whether output
files are generated for a Web service provider or a Web service requester.
• Conversion type: Compiled XML Conversion or Interpretive XML Conversion. This parameter specifies
the method used to convert data between XML format and programming language format.
The values for these four factors are set by one of two different methods, depending on the context from
which the single-service wizard is started:
• Single-service project:
If the wizard is started from the context of a single-service project, then the values for all four
factors were specified when the single-service project was created. That is, when you create a new
single-service project you are required to specify a runtime environment, a development scenario, an
application mode, and a conversion type (see “Creating a new single-service project” on page 188).
• Other project perspective or Remote Systems view:
If the wizard is started from either of these contexts then the Wizard Launcher window opens and
prompts you to select values for the four factors. When you click Start then the Wizard Launcher starts
the appropriate wizard based on the selections.

Developing web services and SOA with Enterprise Service Tools 175
 The batch processor
The batch processor is a command-line interface for creating enterprise Web services descriptions and
message converters for CICS® and IMS™ applications.
The batch processor is a command-line alternative to the single-service wizards. It supports the same set
of options as the single-service wizards and generates the same output files. The options are specified
through reusable configuration files.
The advantage of using the batch processor is that you can configure a set of reusable configuration files
once to generate a group of Web services files, and then you can regenerate the group of Web service files
again and again with having to reconfigure all the options.
See “Batch processor” on page 411.

The types of single-service projects

This group of topics describes the types of single-service projects.
Each type of single-service project provides a context for generating Web service files for a particular
runtime environment. The type (target runtime environment) of a single-service project and its
development scenario, application mode, and conversion type are set when the single-service project
is created (see “Creating a new single-service project” on page 188). When a single-service wizard is
launched from a folder in a single-service project, these four characteristics determine which wizard is
started and which options the wizard presents (see “The single-service wizards” on page 175).
Conversion source package file: A conversion source package is a single COBOL or PL/I source code file
that contains the generated conversion programs for converting from XML data to language data and from
language data to the XML data. For Web services scenarios these packages may contain SOAP header and
SOAP fault conversion code and other utility programs (if supported by a specific scenario).

Web Services for CICS project

This topic describes scenarios typical for the Web Services for CICS project.
The following scenarios are supported:
• Scenario: Create New Service Interface (bottom-up)
Generate a Web service description and runtime-specific XML message processing from a high level
language structure. You can use this option when you expose an application program as a service
provider.
There are two conversion type choices available for this scenario and runtime combination. Either
Compiled XML Conversion or Interpretive XML Conversion may be selected from the Web Service
Runtime and Scenario Selection dialog. The choice of conversion type involves considering the
benefits and cost of either technology. Use the following information when making a selection:
Compiled XML Conversion
XML conversion is accomplished using a suite of generated high-level language (HLL) programs. A driver
program interacts with the runtime environment and invokes bundled programs to provide conversion
of XML to and from language structures. The compiled XML conversion type provides more extensive
support for language structure data types and constructs than the interpretive XML conversion type,
however compilation of XML Converters is required and there are more artifacts to manage.
Interpretive XML Conversion
XML conversion is accomplished using generated metadata and an XML conversion component built
into the runtime environment. While the Interpretive XML Conversion type has limited support
for language structure data types and constructs its requires fewer artifacts and does not involve
compilation of XML converters.
Generated artifacts (Interpretive XML Conversion)
– WSBIND file

176 Developer for z/OS: Developing with Db2, CICS, and IMS
 – WSDL document
Generated artifacts (Compiled XML Conversion)
– WSBIND file (Vendor)
– Web Services for CICS Driver Program
– CICS SOAP Request XML Converter
– CICS SOAP Response XML Converter
– WSDL document
– Request XML Schema
– Response XML Schema
• Scenario: Map to an Existing Service Interface (meet-in-the-middle)
Define mappings between high level language structures and WSDL, XML, or XSD files. You can use
this option to generate XML message processing based on the mappings. You use the Create Mappings
wizard to define the mappings and create compiled converters. When the wizard closes the single-
service mapping editor opens so that you can set the mappings.
Generated artifacts (Compiled XML Conversion)
– XML to COBOL mapping (request)
- Web Services for CICS Driver Program
- CICS SOAP Request XML Converter
- WSBIND file (Vendor)
– COBOL to XML mapping (response)
- Web Services for CICS Driver Program
- CICS SOAP Response XML Converter
- WSBIND file (Vendor)
• Scenario: Create New Service Implementation (top-down) Web Services for CICS only
Generate a high level language structure and XML message processing from a Web service description.
You can use this option to (1) Create a new service provider application program (2) Expose an existing
application program as a service provider or (3) Construct a new service requester application program.
The Interpretive XML Conversion type is the only available conversion technology for this runtime
environment and scenario combination. The top-down artifacts are generated through a wizard that
allows you to specify the properties of the new service application. To assist in writing the new service
application described by the Web service description, generation of a new service provider or service
requester template is provided.
Generated Artifacts (Interpretive XML Conversion)
– Service Requester or Provider Template
– COBOL or PL/I Language Structures
– WSBIND file
• Scenario: Create New MTOM/XOP Service Interface (bottom-up)
Generate an MTOM/XOP compatible Web service description and runtime specific XML message
processing from a high-level language data structure. You can use this option when you expose an
application program as a service provider where language structures are transmitted in binary instead of
an XML representation.
The conversion type choice available for this scenario is and runtime combination isInterpretive XML
Conversion.
XML conversion is accomplished using generated metadata and an XML conversion component built
into the runtime environment. While the Interpretive XML Conversion type has limited support

Developing web services and SOA with Enterprise Service Tools 177
 for language structure data types and constructs its requires fewer artifacts and does not involve
compilation of XML converters.
Generated artifacts (Interpretive XML Conversion)
– WSBIND file
– MTOM/XOP document
For additoinal information, see “Generate CICS MTOM/XOP Web Service (Bottom-Up)” on page 271
Related concepts

“Supported runtime environments” on page 133

Related reference

“SOAP for CICS project” on page 178

“IMS Enterprise
Suite SOAP Gateway project” on page 181
“Batch, TSO, z/OS UNIX System Services project” on page 183
“Runtime XML conversion: compiled or interpretive” on page 262

SOAP for CICS project

This topic describes scenarios typical for the SOAP for CICS project.
The SOAP for CICS feature enables existing or new CICS applications, written in any supported
programming language, to communicate outside of the CICS environment using the Simple Object Access
Protocol (SOAP). The feature supports request and response SOAP requests. A user-written (or generated
by Enterprise Services Tools) program known as a message adapter provides a mapping between XML and
the CICS communication area (COMMAREA) used by an application program.
Note: The SOAP for CICS feature is available only with CICS TS V2.2 and 2.3. For later versions of CICS it
is recommended that you use Web services for CICS support provided in these later versions.
The following scenarios are supported:
• Scenario: Create New Service Interface (bottom-up)
Generate a Web service description and runtime-specific XML message processing from a high level
language structure. You can use this option when you expose an application program as a service
provider.
Generated artifacts (Compiled XML Conversion)
– SOAP for CICS Driver Program
– CICS SOAP Request XML Converter
– CICS SOAP Response XML Converter
– WSDL document
– Request XSD
– Response XSD
• Scenario: Map to an Existing Service Interface (meet-in-middle)
Define mappings between high level language structures and WSDL, XML, or XSD files. You can use
this option to generate XML message processing based on the mappings. You can use the Create
Mappings wizard to define the mappings and create compiled converters which are then deployed to
CICS. Selecting Map an Existing Service Interface takes you to a wizard where you select the source
and target for the mapping. After you select the source and target of the mapping, the single-service
mapping editor opens.
Generated artifacts (Compiled XML Conversion)

178 Developer for z/OS: Developing with Db2, CICS, and IMS
 – XML to COBOL mapping (request)
- SOAP for CICS Driver Program
- CICS SOAP Request XML Converter
– COBOL to XML mapping (response)
- SOAP for CICS Driver Program
- CICS SOAP Response XML Converter
Related concepts

“Supported runtime environments” on page 133

Related reference

“Web Services for CICS project” on page 176

“IMS Enterprise
Suite SOAP Gateway project” on page 181
“Batch, TSO, z/OS UNIX System Services project” on page 183

XML Transformation for CICS project

This topic describes scenarios typical for the XML Transformation for CICS project.
The following scenarios are supported:
• Scenario: Create New XML Transformation (bottom-up)
Generate an XML Schema and runtime-specific XML message processing from a high level language
structure. You can use this scenario when your CICS application needs to transform a data structure
into and XML document. You can also transform an XML document that corresponds to the XML Schema
generated from the language structure, into that language structure
There are two conversion type choices available for this scenario and runtime combination. Either
Compiled XML Conversion or Interpretive XML Conversion may be selected in the New project
launchpad. The choice of conversion type involves considering the benefits and cost of either
technology. Use the following information when making a selection:
Compiled XML Conversion
XML conversion is accomplished using a suite of generated high-level language (HLL) programs. A driver
program interacts with the runtime environment and invokes bundled programs to provide conversion
of XML to and from language structures. The compiled XML conversion type provides more extensive
support for language structure data types and constructs than the interpretive XML conversion type,
however compilation of XML Converters is required and there are more artifacts to manage.
Interpretive XML Conversion
XML conversion is accomplished using generated metadata and an XML conversion component built
into the runtime environment. While the Interpretive XML Conversion type has limited support
for language structure data types and constructs its requires fewer artifacts and does not involve
compilation of XML converters.
Generated artifacts (Interpretive XML Conversion)
– XSDBIND file
– XML Schema
Generated artifacts (Compiled XML Conversion)
– XSDBIND file (Vendor)
– XML Transformation for CICS Driver Program
– CICS XML Converter
– XML Schema

Developing web services and SOA with Enterprise Service Tools 179
 • Scenario: Create New XML Transformation (top-down) XML Transformation for CICS only
Generate a high level language structure and XML message processing from an XML schema.
The Interpretive XML Conversion type is the only available conversion technology for this runtime
environment and scenario combination. The top-down artifacts are generated through a wizard that
allows you to specify the properties of the new service application.
Generated Artifacts (Interpretive XML Conversion)
– Language Structures (copybooks)
– XSDBIND file
Related concepts

“Supported runtime environments” on page 133

Related reference

“Batch, TSO, z/OS UNIX System Services project” on page 183

“Runtime XML conversion: compiled or interpretive” on page 262

JSON Services for CICS project

This topic describes scenarios typical for the JSON Services for CICS project.
With this project you can expose CICS applications as web services with JSON payloads, create new
RESTful applications, call existing JSON applications, and convert JSON from any source to and from
application data.
The following scenarios are supported:
• Scenario: Create New Service Interface (bottom-up)
Generate a JSON schema and runtime-specific message processing from a high-level language data
structure. You can use this option when you expose an application program as a service provider.
This scenario uses the Request-Response interaction pattern. With this interaction pattern, an existing
CICS PROGRAM is exposed as a JSON web service. You begin with existing language data structures
and use the wizard to generate the JSON request and response schema.
Generated artifacts
– JSON request file
– JSON response file
– WSBIND file
• Scenario: Create New Service Implementation (top-down)
Generate high-level language data structures and runtime-specific message processing from a JSON
schema. You can use this option to (1) Create a new service provider application program or (2) Expose
an existing application program as a service provider.
There are two interaction pattern choices available for this scenario. Either Request-Response or
RESTful may be selected from the interaction pattern dialog.
Request-Response interaction pattern
New language structures for JSON web services are created using an interface that is described within
existing JSON Request and Response schemas. An application must be created to use the new language
structures. The Request-Response pattern can be used to generate JSON Web Services that target
either Commarea or Channel attached CICS PROGRAMs. This option can only be used in provider mode,
where CICS acts as the server.
RESTful interaction pattern

180 Developer for z/OS: Developing with Db2, CICS, and IMS
 New language structures for JSON web services are created using an interface that is described within
existing JSON Request and Response schemas. The RESTful interaction pattern is used in combination
with HTTP. In this context, the resource's identity is its URI. The data type is its Media Type, and the
actions are made up of the standard HTTP methods (GET, PUT, POST, and DELETE). An application must
be created to use the new language structures, and it has to behave differently depending on the HTTP
method that was used for the incoming request.
Generated artifacts (Request-Response interaction pattern)
– Request file copybook
– Response file copybook
– WSBIND file
Generated artifacts (RESTful interaction pattern)
– Request file copybook
– WSBIND file
Related concepts

“Supported runtime environments” on page 133

Related reference
Rendering data as JSON

IMS Enterprise Suite SOAP Gateway project

This topic describes scenarios typical for the IMS Enterprise Suite SOAP Gateway project
The IMS Enterprise Suite SOAP Gateway is a lightweight Web service solution that enables IMS
applications to interoperate outside of the IMS environment through SOAP to provide and request
services independently of platform, environment, application language, or programming model. You can
enable IMS COBOL and PL/I applications for Web services by using the Enterprise Service Tools to
generate Web service artifacts for IMS COBOL and PL/I applications. You then deploy these Web service
artifacts to the IMS Enterprise Suite SOAP Gateway to make an IMS application available as a Web
service. Different types of client applications, such as Microsoft.NET, Java and third-party applications,
can then submit SOAP requests into IMS to drive the business logic of the COBOL and PL/I applications.
The following scenarios are supported:
• Scenario: Create New Service Interface (bottom-up)
Generate a Web service description and runtime-specific XML message processing from a high level
language structure. You can use this option when you expose an application program as a service
provider.
Generated artifacts (Compiled XML Conversion)
– IMS Enterprise Suite SOAP Gateway Driver Program
– IMS SOAP Request XML Converter
– IMS SOAP Response XML Converter
– IMS Correlator (runtime metadata)
– WSDL document
– Request XSD
– Response XSD

• Scenario: Map to an Existing Service Interface (meet-in-middle)

Define mappings between high level language structures and WSDL, XML, or XSD You can use this
option to generate XML message processing based on the mappings. You can use the Create Mappings
wizard to define the mappings and create compiled converters. Selecting Map an Existing Service

Developing web services and SOA with Enterprise Service Tools 181
 Interface takes you to a wizard where you select the source and target for the mapping. After you select
the source and target of the mapping, the single-service mapping editor opens.
Generated artifacts (Compiled XML Conversion)
– XML to COBOL or PL/I mapping (request message)
- IMS SOAP Driver Program
- IMS SOAP Request XML Converter
- IMS Correlator (runtime metadata)
– COBOL or PL/I to XML (response message)
- IMS SOAP Driver Program
- IMS SOAP Response XML Converter
- IMS Correlator (runtime metadata)

• Scenario: Create New Service Implementation (top-down) IMS Enterprise Suite SOAP Gateway with
Compiled Conversion and Enterprise PL/I language only
Note: Currently this scenario is supported only in the batch processor (see “Batch processor” on page
411).
WSDL2PLI scenario: This scenario is referred to as the WSDL2PLI (WSDL to PL/I) scenario.
In this scenario a new IMS Enterprise Suite SOAP Gateway Web service provider program supporting
one or more operations is created from the information in a WSDL file.
Single-service tools APIs are also provided to handle the transmission and receipt of SOAP language
structures on the IMS Message Queue or in IMS Connect.
Generated artifacts (see “ Output files generated in the WSDL2PLI scenario” on page 404):
– IMS Enterprise Suite SOAP Gateway Driver program supporting multiple operations
– For each operation:
- Request language structure
- Response language structure
- IMS Connect Request Converter
- IMS Connect Response Converter
– Multi-operation, multi-converter IMS Correlator file (runtime metadata)
Components:
– The single-service component that does common processing for this scenario is WSDL2ELS (WSDL to
Enterprise Language structure).
– The single-service component that does PL/I-specific processing for this scenario is WSDL2PLI
(WSDL to PL/I).

Related concepts

“Supported runtime environments” on page 133

Related reference

“SOAP for CICS project” on page 178

“Batch, TSO, z/OS UNIX System Services project” on page 183

182 Developer for z/OS: Developing with Db2, CICS, and IMS
Batch, TSO, z/OS UNIX System Services project
This topic describes scenarios typical for the Batch, TSO, z/OS UNIX System Services project.
Use Batch, TSO, z/OS UNIX System Services runtime environment to generate Web services
components that are not runtime-specific. For example, you can have your own Web service processing
environment (such as SOAP servers) or you want to use XML message-based Web service interface for
program-to-program communication.
The following scenarios are supported:
• Scenario: Create New Service Interface (bottom-up)
Generate a Web service description and XML message processing from a high level language structure.
You can use this option when you expose an application program as a service provider.
Generated artifacts
– Batch Driver Program
– Request XML Converter
– Response XML Converter
– WSDL document
– Request XSD
– Response XSD

• Scenario: Map to an Existing Service Interface (meet-in-middle)

Define mappings between high level language structures and WSDL, XML, or XSD files. You can use this
option to generate XML message processing based on the mappings. Choosing Map an Existing Service
Interface scenario takes you to a wizard where you select the source and target for the mapping. After
you select the source and target of the mapping, the single-service mapping editor opens.
Generated Artifacts (Compiled XML Conversion)
– WSDL to COBOL or PL/I mapping (request)
- Batch Driver Program
- Request XML Converter
– COBOL or PL/I to WSDL (response)
- Batch Driver Program
- Response XML Converter

Related concepts

“Supported runtime environments” on page 133

Related reference

“Web Services for CICS project” on page 176

“SOAP for CICS project” on page 178
“IMS Enterprise
Suite SOAP Gateway project” on page 181

Summary of supported runtime environments, scenarios, and conversion

types
The following table summarizes important information about single-service projects.
Table 28 on page 184 is a summary of the various service interface scenarios and the supported runtime
environments.

Developing web services and SOA with Enterprise Service Tools 183
Table 28. Enablement scenarios for single-service projects
Supported File Supported Runtime
Scenarios Action Description Extensions Environments
Create New Service Create XML Generates a .cbl, .cpy, .cob, .ccp • Web services for
Interface (bottom- conversion artifacts service description CICS
up), Interpretive or (interpretive or and runtime-specific
• IMS Enterprise
Compiled compiled) for XML message
Suite SOAP
target runtime processing from a
Gateway
environment. high level language
structure. You can • Batch, TSO, and
use this option z/OS UNIX System
when you expose an Services
application program
as a service
provider.
Create New Service Create XML Generates a .pli, . inc, .mac • IMS Enterprise
Interface (bottom- conversion artifacts service description Suite SOAP
up), Compiled (compiled only) and runtime-specific Gateway
for target runtime XML message
• Batch, TSO, and
environment. processing from a
z/OS UNIX System
high level language
Services
structure. You can
use this option
when you expose an
application program
as a service
provider.
Create New Service Create XML Generates a .pli, . inc, .mac • Web services for
Interface (bottom- conversion artifacts service description CICS
up), Compiled or (interpretive or and runtime-specific
• IMS Enterprise
Interpretive compiled) for XML message
Suite SOAP
target runtime processing from a
Gateway
environment. high level language
structure. You can • Batch, TSO, and
use this option z/OS UNIX System
when you expose an Services
application program
as a service
provider.

184 Developer for z/OS: Developing with Db2, CICS, and IMS
Table 28. Enablement scenarios for single-service projects (continued)
Supported File Supported Runtime
Scenarios Action Description Extensions Environments
Create New Service (a) Create language Generates a high .wsdl Web services for
Implementation structure include level language CICS
(top-down) files and template structures and
Service Provider or runtime-specific
Service Requester XML message
program in desired processing from
language. (b) a Web service
Create XML description. You can
conversion artifacts use this option
(interpretive to (1) Create a
WSBIND only). new service provider
application program
(2) Expose an
existing application
program as a service
provider or (3)
Construct a new
service requester
application program.
Create New Service From the Generates an IMS .wsdl IMS Enterprise Suite
Implementation information in Enterprise Suite SOAP Gateway
(top-down) a multi-operation SOAP Gateway
WSDL file, create Web service and
Note: Available
a new IMS supporting files
only in the batch
Enterprise Suite (see “ Output files
processor.
SOAP Gateway Web generated in the
service provider WSDL2PLI scenario”
program supporting on page 404).
multiple operations.
Map to an Existing Create XML Define mappings .cbl, .cpy, .cob, .ccp, • Batch, TSO, and
Service Interface conversion artifacts between high level .wsdl, .xml, .xsd z/OS UNIX System
(meet-in-middle), (compiled only) for language structures Services
Compiled request or response and WSDL, XML, or
• Web services for
mapping. XSD files. You can
CICS
use this option to
Generates runtime- • IMS Enterprise
specific XML Suite SOAP
message processing Gateway
based on the
mappings.
Create New Create XML Generates files .cbl, .cpy, .cob, .ccp XML Transformation
XML Transformation conversion artifacts for the XML for CICS
(bottom-up), (compiled) for Transformation and
Compiled target runtime runtime-specific
environment. XML processing from
a high level language
data structure.

Developing web services and SOA with Enterprise Service Tools 185
Table 28. Enablement scenarios for single-service projects (continued)
Supported File Supported Runtime
Scenarios Action Description Extensions Environments
Create New Create XML Generates files cbl, .cpy, .cob, .ccp, . XML Transformation
XML Transformation conversion artifacts for the XML pli, .inc, .mac for CICS
(bottom-up), (interpretive) for Transformation and
Interpretive target runtime runtime-specific
environment. XML processing from
a high level language
data structure.
Create New XML Create XML Generates a high- .xsd, .wsdl XML Transformation
Transformation (top- conversion artifacts level language for CICS
down) (interpretive). structure and
runtime-specific
XML processing from
an XSD or a WSDL
file.

Related concepts

“Runtime XML conversion: compiled or interpretive” on page 262

Related reference

“Bottom-up wizard - Compiled XML conversion” on page 200

“Create New Service Implementation (top-down)
wizard” on page 222
“Map to an Existing Service Interface (meet-in-middle) wizard” on page 227

Table of runtimes, scenarios, languages, conversion types, and modes

This topic shows the supported options for single-service projects.

For more information see the topic describing each type of single-service projects (see “The types of
single-service projects” on page 176).
Table 29 on page 186 shows the types of files that can be selected as source files for the single-service
wizards.

Table 29. File extensions of files that can be selected as source files for the single-service wizards
Development scenario: COBOL: PL/I:
Bottom-Up .cbl, .cpy, .cob, .ccp .pli, . inc, .mac
Top-Down .wsdl .wsdl
.cbl, .cpy, .cob, .ccp, .wsdl, .xml, . pli, .inc, .mac, .wsdl, .xml, .xsd
Meet-in-Middle
xsd

Table 30 on page 187 shows supported combinations of runtime environments, development scenarios,
programming languages, conversion types, and application modes. A em-dash (—) indicates that a
combination is not supported.

186 Developer for z/OS: Developing with Db2, CICS, and IMS
Table 30. Runtimes, development scenarios, programming languages, conversion types, and application
modes
For COBOL: For PL/I:
Develoment
Runtime: Compiled Interpretive Compiled Interpretive
scenario:
conversion: conversion: conversion: conversion:
Web Services • Service • Service
for CICS provider provider
Top-Down — —
• Service • Service
requester requester

• Service
Meet-in-Middle — — —
provider
• Service • Service • Service
Bottom-Up —
provider provider provider
XML • Service • Service
Top-Down — —
Transformatio provider provider
n for CICS2
Meet-in-Middle — — — —
• Service • Service • Service
Bottom-Up —
provider provider provider
JSON Services • Service • Service
Top-Down — —
for CICS provider provider
project
Meet-in-Middle — — — —
• Service • Service
Bottom-Up — —
provider provider
IMS Enterprise • Service
Suite SOAP provider (batch
Top-Down — — —
Gateway processor
only)1

• Service • Service
provider provider
Meet-in-Middle — —
• Service • Service
requester requester

• Service • Service
Bottom-Up — —
provider provider
Meet-in-Middle — — — —
• Service • Service
Bottom-Up — —
provider provider
Batch, TSO, Top-Down — — — —
and Unix
• Service • Service
System Meet-in-Middle — —
provider provider
Services3
• Service • Service
Bottom-Up — —
provider provider

Developing web services and SOA with Enterprise Service Tools 187
 Table 30. Runtimes, development scenarios, programming languages, conversion types, and application
modes (continued)
For COBOL: For PL/I:
Develoment
Runtime: Compiled Interpretive Compiled Interpretive
scenario:
conversion: conversion: conversion: conversion:

1This
scenario is supported only in the batch processor.
2TheTXSeries for Multiplatforms runtime is supported only for the bottom-up scenario, service provider
mode, and interpretive conversion.

Working with single-service projects

This group of topics describes actions you can perform with single-service projects.

Creating a new single-service project

Use one of the new single-service project wizards to create a new single-service project.
To open a new single-service project wizard, follow the steps in one of the methods shown in Table 31 on
page 188.

Table 31. Methods for Launching A New Project Wizard

Method Steps to follow:
Use the main menu of the workbench. 1. Select File > New > Project... >
Enterprise Service Tools > project_type, where
project_type is the type of project that you want
to create (see “Shortcut to wizards” on page
143).
The new single-service wizard opens for the type of
single-service project that you selected.
Use the pop-up menu in the Enterprise Service 1. In the Enterprise Service Tools Project Explorer,
Tools Project Explorer. right-click anywhere over the main window
area. The pop-up menu opens.
2. Select New > project_type, where Project_type
is one of the following:
• Web Services for CICS Project
• XML Transformation for CICS
• JSON Services for CICS project
• IMS Enterprise Suite SOAP Gateway Project
• Batch, TSO, and z/OS UNIX System Services
Project
The new single-service wizard opens for the type of
single-service project that you selected.

188 Developer for z/OS: Developing with Db2, CICS, and IMS
Table 31. Methods for Launching A New Project Wizard (continued)
Method Steps to follow:
Use the drop-down menu in the Enterprise Service 1. In the Enterprise Service Tools Project Explorer,
Tools Project Explorer. select the icon for the drop-down menu (see
“Drop-down menu (for creating new projects
and artifacts)” on page 140). The drop-down
menu opens.
2. Select the type of project that you want to
create:
• Web Services for CICS Project
• JSON Services for CICS project
• IMS Enterprise Suite SOAP Gateway Project
• XML Transformation for CICS
• Batch, TSO, and z/OS UNIX System Services
Project
The new single-service wizard opens for the type of
single-service project that you selected.

The available New Web Service Project wizards are:

• The New Web Services for CICS Project wizard
• The New XML Transformation for CICSProject wizard
• The New JSON Services for CICS project wizard
• The New IMS Enterprise Suite SOAP Gateway Project wizard
• The New Batch, TSO, and z/OS UNIX System Services Project wizard
To create a new single-service project, follow the same steps for the project wizards:
1. On the first page of the wizard, in the Project name: field, enter a project name.
2. In the Development scenario: field, enter the development scenario for which you want the wizard to
generate files:
• Create New Service Interface (bottom-up)
• Create New Service Implementation (top-down)
• Map to an Existing Service Interface (meet-in-middle)
Note: For XML Transformation for CICS projects, the bottom-up and the top-down scenarios are
called "Create New XML Transformation".
3. In the Application mode: field, enter the application mode of the Web service application for which
you want the wizard to generate files:
• Service Provider
• Service Requester
4. In the Conversion type: field, enter the type of data conversion that you want to be used by the
generated Web service files:
• Compiled XML Conversion
• Interpretive XML Conversion
5. The wizard responds with a description of the specifics of the options that have been chosen in the
Scenario description field.
6. Click Next

Developing web services and SOA with Enterprise Service Tools 189
 The wizard creates the new project in the Enterprise Service Tools Project Explorer. If you created a list
of source files to import, the imported source files are copied to the Source folder of the project (see
“Folders and subfolders in a single-service project” on page 174).

Importing source files into a single-service project

Use the Import Source Files wizard to add COBOL or PL/I source files to a single-service project.
Follow these steps to add source files to a single-service project:
1. In the EST Project Explorer, right-click the name of the single-service project to which you want to add
source files.
2. Select Import > Source files. The Import Source Files wizard opens.
3. In the Import Source Files wizard:
a. Create a list of source files to import:
When the user imports a WSDL file into a single-service project, instead of creating a copy of the
WSDL file in the workspace (old behavior), a linked resource is created, which points to the actual
location of the file in the file system. This aids in resolving any imported schemas in the WSDL file.
Note: Because the imported file is a linked resource, deleting the WSDL file or any of the dependent
XSDs in the file system causes the links to be unresolved and causes the Web service wizards to
open with an error.
• Click File System to select source files from your workstation's file system.
• Click Workspace to select source files from your workbench's current workspace.
• Click Remote to select source files from the remote system (see “Importing PL/I source files from
a remote system” on page 192 or “Importing COBOL source files from a remote system” on page
190).
• To remove a file from the list, select the file and click Remove.
b. Select the checkbox Overwrite existing resources without warning if you do not want the wizard
to warn you when you are about to overwrite one source file with another source file of the same
name.
c. Click Finish to import the source files.
The wizard copies the source files into the Source folder of the single-service project (see “Folders and
subfolders in a single-service project” on page 174).

Importing COBOL source files from a remote system

This topic describes how to use the Import Source Files wizard to import COBOL source files from a
remote host system.
The Import Source Files wizard allows you to import files into the Enterprise Service Tools perspective
either from the local file system, from the current workspace, or from a remote host system (see
“Importing source files into a single-service project” on page 190).
This topic describes how to use the Import Source Files wizard to import COBOL source files from a
remote system.

Prerequisite
Before you can import files from a remote system, you must first create a connection to the remote
system (see the topic "Connecting to a remote system" in the online help).
The basic steps for creating a connection to the remote system are as follows:
1. Use the Remote Systems view to create connections to JES, to MVS and (if applicable) to z/OS UNIX
System services.

190 Developer for z/OS: Developing with Db2, CICS, and IMS
2. Use the Remote Systems view to start the new connection to the remote z/OS system.

Requirements for COBOL source files

The Import Source Files wizard has the following requirements for importing COBOL source files from a
remote system:
• The remote file must be mapped to one of the following extensions: .cbl, .cob, ccp or .cpy.
• If the file is mapped to a .cbl, .cob or .ccp extension, then the file is assumed to be a complete
COBOL program that can have dependencies on other files. If the COBOL program does in fact have
dependencies on other files, then you should provide the information about the partitioned data sets
(PDSs) where the copy books exist by setting the SYSLIB for the remote file.
• If the file is mapped to .cpy, it is assumed to be a copy book consisting of only 01 data structures or 01
or 77 elementary data item definitions. If the copy book that you select has references to other copy
books, then their contents must be listed in the copy book that you select.
Note: You can change the default behavior of the file extension by using the File Extension Support table
in the More COBOL options tab of the Importer > Cobol preferences page.

Importing a remote file:

To import a remote file:
1. In the Import Source Files wizard, click Remote. A remote file selection window opens.
2. In the remote file selection window, select either a complete COBOL program or a copy book:
• If you select a complete COBOL program, choose one of the following options:
– Import the selected resource only: Select this option to import only the selected file.
– Import the selected resource and any dependent files: Select this option to import (copy) the
selected file and also import all other files that the selected file has dependencies on.
• If you select a copy book, a message is displayed stating that the selected copy book is expected to
have no dependencies. (You can select to have this message not be displayed again.)

Troubleshooting information for importing COBOL source files

If you encounter errors when trying to download a COBOL source file from a remote system, consult the
following checklist of common problems:
1. The following messages may appear in the Refresh Dependencies Problems window. Click Details to
display the specific error message:
• The following message may appear if the JES subsystem is not connected.

JES subsystem is not connected.

Connect to the subsystem and retry the operation.

• The following message may appear if, for example, you have specified a PDS that does not exist in
the SYSLIB.

The submitted job has ended with a JCL error.

Check the build properties and retry the operation.

2. If you see error messages related to "COPY library not found" when you are try to generate output
files from a single-service project, it is possible that files on which an imported COBOL source file has
dependencies were not imported with the COBOL source file into your Enterprise Service Tools project.
To resolve this problem, provide all the PDSs which contain the dependencies, and import the source
file again.

Developing web services and SOA with Enterprise Service Tools 191
 Related information
Opening the Preferences window

Importing PL/I source files from a remote system

This topic describes how to use the Import Source Files wizard to import PL/I source files from a remote
z/OS system.
The Import Source Files wizard allows you to import files into the Enterprise Service Tools perspective
either from the local file system, from the current workspace, or from a remote z/OS system (see
“Importing source files into a single-service project” on page 190).
This topic describes how to use the Import Source Files wizard to import PL/I source files from a remote
system.

Prerequisite
Before you can import files from a remote system, you must first create a connection to the remote
system (see the topic "Connecting to a remote system" in the online help).
The basic steps for creating a connection to the remote system are as follows:
1. Use the Remote Systems view to create connections to JES, to MVS and (if applicable) to z/OS UNIX
System services.
2. Use the Remote Systems view to start the new connection to the remote z/OS system.

Requirements for PL/I source files

The Import Source Files wizard has the following requirements for importing PL/I source files from a
remote system:
• The remote file must be mapped to one of the following extensions: .pli, .mac or .inc.
• If the file is mapped to a .pli extension, then the file is assumed to be a complete PL/I program that
can have dependencies on other files. If the PL/I program does in fact have dependencies on other files,
then you should provide the information about the partitioned data sets (PDSs) where the files exist by
setting the SYSLIB for the remote file.
• If the file is mapped to a .inc or .mac extension, it is assumed to be a PL/I include file consisting of only
01 data structures. If the include file that you select has references to other include files, then their
contents must be listed in the include file that you select.
Note: You can change the default behavior of the file extension by using the File Extension Support table
in the General tab of the Importer > PL/I preferences page.

Importing a remote file:

To import a remote file:
1. In the Import Source Files wizard, click Remote. A remote file selection window opens.
2. In the remote file selection window, select either a complete PL/I program or a PL/I include file:
• If you select a complete PL/I program, choose one of the following options:
– Import the selected resource only: Select this option to import only the selected file.
– Import the selected resource and any dependent files: Select this option to import (copy) the
selected file and also import all other files that the selected file has dependencies on.
• If you select an include file, a message is displayed stating that the selected include file is expected
to have no dependencies. (You can select to have this message not be displayed again.)

192 Developer for z/OS: Developing with Db2, CICS, and IMS
Troubleshooting information for importing PL/I source files
If you encounter errors when trying to download a PL/I source file from a remote system, consult the
following checklist of common problems:
1. The following messages may appear in the Refresh Dependencies Problems window. Click Details to
display the specific error message:
• The following message may appear if the JES subsystem is not connected.

JES subsystem is not connected.

Connect to the subsystem and retry the operation.

• The following message may appear if, for example, you have specified a PDS that does not exist in
the SYSLIB.

The submitted job has ended with a JCL error.

Check the build properties and retry the operation.

2. If you see error messages related to "Cannot find/open INCLUDE file" when you are try to generate
output files from a single-service project, it is possible that files on which an imported PL/I source file
has dependencies that were not imported with the PL/I source file into your Enterprise Service Tools
project. To resolve this problem, provide all the PDSs which contain the dependencies, and import the
source file again.
Related information
Opening the Preferences window

Copying and pasting source files into a single-service project

Use the Navigator view to copy and paste source files into the Source folder of an existing single-service
project.
CAUTION: In the Enterprise Service Tools, never paste files into a folder unless you are sure that it
is safe to do so. In some folders, pasting files into a folder can corrupt the project.
Follow these steps to copy and paste files into the Source folder of a single-service project:
1. Select the Navigator view of the Enterprise Tools Perspective (see “The views in the Enterprise Service
Tools perspective” on page 137).
2. Do the copy operation:
a. Expand the folder from which you wish to copy files.
Note: For example, you might want to copy generated files (such as .cbl, .cpy, .wsbind, .wsdl, and so
on) from the Generation\Targets folder of another single-service project.
b. Select, then right-click, the files that you want to copy.
c. Click Copy.
3. Do the paste operation:
a. Right-click the Source folder into which you wish to copy the files.
b. Click Paste.
The files are copied into the Source folder.

Setting preferences for single-service projects

This topic provides links to the topics in this documentation that describe how to set preferences for
single-service projects.
To learn about setting preferences for single-service projects, see the following topics in this
documentation:

Developing web services and SOA with Enterprise Service Tools 193
 • “Setting preferences for COBOL XML converters” on page 145
• “Setting preferences for PL/I XML converters” on page 149
• “Setting preferences for the CICS Web Services Assistant (WSBind)” on page 150
• “Setting preferences for the CICS XML Transformation Assistant (XSDBind)” on page 167

Using the single-service wizards

This group of topics describes how to use the single-service wizards.

Starting the single-service wizards

This group of topics describes how to start the single-service wizards.

Contexts for starting the single-service wizards

This topic describes the contexts in which the single-service wizards can be started.
The single-service wizards can be started in the following contexts:
• A single-service project (see “Starting a single-service wizard from a single-service project” on page
194). This is the recommended way of starting the single-service wizards.
Note: If you import files while you are creating a new single-service project then the single-service
wizard opens automatically (see “Automatically launching a generation wizard after the project
creation” on page 200).
• The Remote Systems view (see “Starting a single-service project from the Remote Systems view” on
page 195).
• A folder in a project belonging to a perspective other than the Enterprise Service Tools perspective, such
as:
– A local z/OS project project in the z/OS Projects perspective.
– A General project in the Resource perspective.
See “Starting a single-service wizard in another perspective” on page 198.
In the first context listed above (a single-service project) the single-service wizard opens immediately.
In the other two contexts the Wizard Launcher opens first. It prompts for a runtime environment,
development scenario, application mode, and conversion type and then starts the appropriate single-
service wizard. Also you must select the appropriate source files before starting the Wizard Launcher (see
Table 29 on page 186 in “Table of runtimes, scenarios, languages, conversion types, and modes” on page
186).

Starting a single-service wizard from a single-service project

This topic describes how to start a single-service wizard from a single-service project.
To start a single-service wizard from a single-service project:
1. Right-click the title of the single-service project.
2. Select Generate <runtime> resources, where <runtime> is the runtime environment that was
selected when the project was created.
3. The single-service wizard opens.
Note: In a single-service project the runtime environment, development scenario, application mode,
and conversion type are set when the project is created. Therefore the single-service wizard opens
immediately without needing the Wizard Launcher.
The single-service wizard automatically remembers the values that you specify for the various options on
the wizard pages wizard. These values are preselected the next time that you run the wizard.

194 Developer for z/OS: Developing with Db2, CICS, and IMS
Creation of generation properties files for the batch processor
The single-service wizard automatically creates three generation properties files for the batch processor.
These files contain the values for the various options that you specified as you went through the pages of
the wizard.
You can then use these generation properties files with the batch processor at any time to re-create the
files generated by the single-service wizard.
The default names of the files are:
• Container.xml
• PlatformProperties.xml
• ServiceSpecification.xml
You can specify different names for these files on the Properties tab of the File, data set, or member
selection page of the wizard (see “Properties tab” on page 213).

Starting the wizard from a selected file

Typically the first step in starting a single-service wizard is to right-click the title of the single-service
project (see Step 1 in the steps at the start of this topic). However, you can also start a single-service
wizard by right-clicking a file within a single-service project. That is:
1. Right-click a source file in the single-service project.
2. Click Generate <runtime> resources as you normally would. The wizard opens.
As usual, the wizard automatically remembers the values that you specify for the various options on the
wizard pages wizard. These values are preselected the next time that you run the wizard.
Typically you do not use this method to start a single-service project unless you want to change the main
source file for the single-service project (see “Changing the source file for a single-service wizard” on
page 195).

Changing the source file for a single-service wizard

Whether you start a single-service wizard by right-clicking the project title or by right-clicking a source
file, you might decide later that you want to use a different source file for the same project. For example,
you might be running the bottom-up single-service wizard starting with the source file orderItem.cbl and
then decide to start with the file queryAccount.cbl.
To change source file for a wizard:
1. Right-click a source file that you want to use.
2. Click Generate <runtime> resources as you normally would. The wizard opens.
The single-service wizard discards the file names and the options saved from the previous time that you
ran it and starts over with the newly selected source file.

Starting a single-service project from the Remote Systems view

This topic describes how to start a single-service wizard from the Remote Systems view.
Note: Only the Create New Service Interface (bottom-up) wizard is available when you open the
launchpad from this context.
This topic contains the following subtopics:
• “Starting the single-service wizard” on page 196
• “Differences in the Wizard Launchpad and wizard pages” on page 196
• “Limitations when you open the launchpad from the Remote Systems view” on page 197
• “Error detection and reporting” on page 197

Developing web services and SOA with Enterprise Service Tools 195
 Starting the single-service wizard
To start a single-service wizard from the Remote Systems view:
1. Open the Remote Systems view:
a. On the main menu of the workbench, select Window > Show View > Remote Systems.
b. The Remote Systems view opens.
2. Use the Remote Systems view to create a connection to MVS on the remote z/OS system (see Creating
a connection to a z/OS system).
3. Start the connection (see Connecting to a remote system).
4. Expand MVS Files > My Data Sets.
5. Right-click the partitioned data set that you want to use.
6. Right-click a COBOL data set member file (the file extension must be .cbl, .cob, .ccp, or .cpy).
7. Select Enable Enterprise Web Service. The Wizard Launchpad opens.
8. In the Wizard Launchpad:
a. Select the appropriate runtime environment, development scenario, application mode, and
conversion type.
Note: In this context some of the selections on the Wizard Launchpad and in the Create New
Service Interface (bottom-up) wizard are different. See “Differences in the Wizard Launchpad and
wizard pages” on page 196.
b. Click Start.
9. The single-service wizard opens.

Differences in the Wizard Launchpad and wizard pages

When you open the Wizard Launchpad in this context you encounter the following differences as you work
through the wizard pages:
• On the Enterprise Service Tools Wizard Launchpad, the Save generation properties option is not
supported in this context.
• Warning or prompt about dependencies of copybook files on a COBOL source file:
– If you right-clicked a COBOL source file (extension .cbl, .cob, or .ccp) before opening the launchpad,
then the Create New Service Interface (bottom-up) wizard opens a window with the prompt, "Does
your source file have any dependent files?"
- If your COBOL source file has dependencies on COBOL copybooks, click Yes.
- Otherwise click No.
– If you right-clicked a COBOL copybook file (extension .cpy) before opening the launchpad, then the
Create New Service Interface (bottom-up) wizard opens a window with the prompt, "For successful
generation from this copybook, the copybook should be self-contained".
- Click OK to continue.
• If you selected Compiled XML Conversion in the launchpad:
– For all target runtime environments (Web Services for CICS, IMS Enterprise Suite Soap Gateway, XML
Transformation for CICS, and Batch, TSO, and z/OS UNIX System Services):
- In the File, data set, or member selection page:
• On the XML Converters tab:
– In the Converter file container field, the default file container that is displayed is the PDS that
contains the COBOL source file that you right-clicked before opening the Enterprise Service
Tools Wizard Launchpad. You can type or select a different file container.

196 Developer for z/OS: Developing with Db2, CICS, and IMS
 • On the WSDL and XSD tab:
– The WSDL file container field is empty. You must specify a file container in this field.
– For the Web Services for CICS target runtime environment:
- On the Web Services for CICS page, on the Basic Options tab, the field WSBind file container is
empty. You must specify a file container in this field.
– For the IMS Enterprise Suite SOAP Gateway runtime environment, on the Correlator Properties tab,
the field Correlator file container is empty.
- Specify a PDS that has a record type of VB or VBA.
• If you selected Interpretive XML Conversion in the launchpad:
– On the page DFHLS2WS: High Level Language to WSDL Conversion, on the tab Service Artifacts,
the field File container is empty. You must specify a file container in this field.

Limitations when you open the launchpad from the Remote Systems view
You should be aware of the following limitations when you open the Enterprise Service Tools Wizard
Launchpad from the Remote Systems view:
• The launchpad is available only if you right-click a remote COBOL member on MVS.
• From the launchpad, only the Create New Service Interface (bottom-up) wizard is available.
• On the launchpad, the Save generation properties option is not supported in this context.
• The batch processor does not support this option.

Error detection and reporting

You should be aware of the following information about error detection and error reporting:
• Syntax errors in the COBOL source file or its dependent copybooks are reported in the Remote Error List
view.
• If an error message in the Remote Error List indicates that a COPY item was not found, for example:

IGYLI0049-S, The "COPY" library was not found.

then two possible causes for this error are as follows (there are other possible causes):
– The COBOL source file (extension .cbl, .cob, or .ccp) that you right-clicked before opening the
launchpad has dependencies, but when the Create New Service Interface (bottom-up) wizard
prompted, "Does your source file have any dependent files?", you selected No (see “Differences
in the Wizard Launchpad and wizard pages” on page 196).
– The COBOL copybook file source file (extension .cpy) that you right-clicked before opening the
launchpad has dependencies. You cannot specify a COBOL copybook file unless it has no
dependencies.
• When the wizard is checking dependencies, the wizard can display in the Check Dependencies window
one of the following error messages:
– If the JES system is not connected, then the wizard displays the following error message:

The submitted job as ended with a JCL Error.

Check the build properties and retry the operation.

– If there is a JCL error (for example, you specified a PDS that does not exist in the SYSLIB), then the
wizard displays the following message:

The submitted job as ended with a JCL Error.

Check the build properties and retry the operation.

Developing web services and SOA with Enterprise Service Tools 197
 Starting a single-service wizard in another perspective
This topic describes how to start a single-service wizard in a workbench perspective other than Enterprise
Service Tools.
Note: Although this feature is still supported, the recommended way to start a single-service wizard is
from a single-service project in the Enterprise Service Tools perspective (see “Starting a single-service
wizard from a single-service project” on page 194).

Steps for starting a single-service wizard in another perspective

This topic describes the steps for starting a single-service wizard from a perspective other than Enterprise
Service Tools.
A single-service project can be started from a project in another workbench perspective if the appropriate
source files are present. Examples of such projects are:
• A local z/OS project in the z/OS Projects perspective.
• A General project in the Resource perspective.
Before you can start a single-service wizard, you must create a project and copy the appropriate source
files into it. The following instructions assume that the project is a z/OS project:
1. Create a z/OS project (see “Creating a local z/OS project in the z/OS Projects perspective” on page
198).
2. Copy source files into the project (see “Copying source files into a project using the Navigator view” on
page 199).
Note: If you plan to run the top-down wizard using a WSDL file with imported schemas in the Resource
perspective, copy the whole directory structure into the resource project.
To start a single-service wizard from the z/OS project:
1. Right-click an appropriate source file in a project folder (see Table 29 on page 186 in “Table of
runtimes, scenarios, languages, conversion types, and modes” on page 186).
2. Select Enable Enterprise Web Service. The Wizard Launchpad opens.
3. In the Wizard Launchpad:
a. Select the appropriate runtime environment, development scenario, application mode, and
conversion type (see “Using the Wizard Launchpad” on page 199).
b. Click Start.
4. The single-service wizard opens.

Creating a local z/OS project in the z/OS Projects perspective

Learn how to create a local z/OS project in the z/OS Projects perspective.
1. Right-click the z/OS Projects view and select New > Local z/OS Project. The New Local Project
window opens.
2. Type a name for the project.
3. From the Property Group area, select one of these options:
• Select a property group to associate with the project Select this option and then select a property
group for the new project. You can sort the list by clicking the table headings. To reverse the sort
order, click the table headings again.
• Create a property group and associate it with the project. Click Finish to edit the property group.
Select this option to create a property group for the project. Type a name for the group in the Name
field.
• Do not associate the project with a property group. Select this option to create the project without
associating it with a property group.
4. Click Finish. If you are creating a new property group, the property group editor opens.

198 Developer for z/OS: Developing with Db2, CICS, and IMS
Copying source files into a project using the Navigator view
This topic describes how to copy source files into the workbench's Navigator view, so that you can use the
source files when you run a single-service wizard in a perspective other than the Enterprise Service Tools
perspective.
These instructions assume that the target directory in the Navigator view resides in a local project in the
z/OS Projects view of the z/OS perspective.
To copy the source files:
1. Create a folder for source files in the new local project, if you have not already done so:
• In the z/OS Projects view, right-click the name of the new local project (such as COBOL Project
0001).
• Select New > Folder. The New Folder wizard opens.
• In the New Folder wizard:
a. Select from the list the name of the project in which you want to create the folder.
b. In the Folder name input field, type the name that you want to use for the new folder (such as
Source).
c. Click Finish.
The new folder is created.
2. Open the Navigator view:
a. On the main menu of the workbench, select Window > Show View > Other. The Show View wizard
opens.
b. In the Show View wizard:
i) Select General > Navigator.
ii) Click OK.
The Navigator view opens, showing all the projects in the current workspace.
3. Copy the files into the new folder:
a. In the Navigator view, select the target folder, such as Source. (This is the same folder that you
created in the z/OS Projects view in Step 1, but now you are viewing it in the Navigator view.)
b. From an application in the operating system of the workstation drag the source files into the new
folder in the Navigator view.
Note: If you want to run a top-down scenario using a WSDL file with imported schemas, then you
should copy the whole directory structure into new folder.
4. Close the Navigator view.

Using the Wizard Launchpad

This topic describes how to use the Wizard Launchpad.
The Wizard Launchpad opens when you start a single-service wizard either (a) from a project in a
perspective other than Enterprise Service Tools, or (b) from the Remote Systems view (see “Contexts
for starting the single-service wizards” on page 194).
To use the Wizard Launchpad:
1. Select a runtime environment, a development scenario, an application mode, and a conversion type
(see “The single-service wizards” on page 175).
Note: The launchpad displays only those options that are valid in light of the file that you selected
before starting the launchpad. For example, if you selected a WSDL file then the launchpad does not
display the development scenario Create New Service Interface (bottom-up).
2. Select or clear the Save generation properties checkbox (see the The Save generation properties
check box).

Developing web services and SOA with Enterprise Service Tools 199
 3. Select or clear the Reuse existing generation properties checkbox (see the “The Reuse existing
generation properties checkbox” on page 200 ).
4. Click Start. The appropriate single-service wizard opens.
The values selected on the launchpad in Step 1 determine which single-service wizard is started and
which options it presents.
Note:
• Not all combinations of runtime environment, development scenario, application mode, and conversion
type are available on the Wizard Launchpad (see “Table of runtimes, scenarios, languages, conversion
types, and modes” on page 186).
• The Wizard Launchpad does not support the XML Transformation for CICS runtime.
• Both the Reuse generation properties and the Reuse generation properties options are only available
for local projects.

The Save generation properties checkbox

If you select this checkbox, the single-service wizard that is launched remembers the values of the
options that you select on the wizard pages. When you run the same wizard again the options are set to
the remembered values.

The Reuse existing generation properties checkbox

If you select this checkbox and specify Container.xml you saved with Save generation properties, the
same wizard will be invoked again and the saved options are set the remembered values.

Automatically launching a generation wizard after the project creation

This topic describes the feature to automatically launch the generation wizard after the EST project
creation.
During the Enterprise Services Tools single-service project creation, if the user imports one source file,
the project is created and the generation wizard automatically shows up. If the user imports multiple
source files, the user must select a source file in the next wizard page, after which the project is created
and the generation wizard is automatically displayed. See “Starting the single-service wizards” on page
194.
Scope:
Applicable to:
• Bottom-up development (Enable existing enterprise applications as Web services)
• Top-down development (Create a Web service implementation for a Web service)
Not applicable to: Meet-in-middle development (Map to an Existing Service Interface).

Create New Service Interface (bottom-up) wizards

Use the Create New Service Interface (bottom-up) wizards to generate artifacts with compiled XML
conversion or with interpretive XML conversion.

Bottom-up wizard - Compiled XML conversion

Use the Create New Service Interface (bottom-up) wizard with Compiled XML conversion to generate
files to implement a Web service provider for a specific runtime environment.

Create New Service Interface (bottom-up) wizard

200 Developer for z/OS: Developing with Db2, CICS, and IMS
Overview of bottom-up (compiled) wizard pages
This topic provides an overview of the pages in the wizards with compiled XML conversion.
For this wizard and conversion type, the pages common to all runtimes are as follows:
• Language Structures page
• Generation options page
• File, data set, or member selection page
The pages peculiar to a particular runtime or application mode are:
• Web Services for CICS page
• IMS Enterprise Suite SOAP Gateway Web Service Provider page
• XML Transformation for CICS page
Table 32 on page 201 summarizes which pages and tabs are available for the supported runtime
environments:

Table 32. Bottom-Up Compiled Wizard Page and Tab Overview

Runtime Environment
Wizard Page and Tabs: (See Note)
W I B T
Language structures page:
• Request Language Structure X X X X
• Response Language Structure

Generation options page:

• XML Converters
• WSDL and XSD (not XML Transformation) X X X X X
• XML Schemas (only XML Transformation)
• Advanced Options

Web Services for CICS page:

• Basic Options X
• Advanced Options

IMS Enterprise Suite SOAP Gateway Web Service Provider page:

X
• IMS Correlator file

File, data set, or member selection page:

• XML Converters
X X X X X
• WSDL and XSD
• Properties (Display only)

CICS Deployment Options page:

X
• Specify deployment manifest properties

Language structures page:

X
• Language Structure

Developing web services and SOA with Enterprise Service Tools 201
 Table 32. Bottom-Up Compiled Wizard Page and Tab Overview (continued)
Runtime Environment
Wizard Page and Tabs: (See Note)
W I B T
XML Transformation for CICS page:
• Basic Options X
• Advanced Options

CICS Deployment Options page:

X
• Start Bundle Deployment wizard upon finish

Note:
• W stands for Web Services for CICS
• I stands for IMS Enterprise Suite SOAP Gateway
• B stands for Batch, TSO, and z/OS UNIX System Services
• T stands for XML Transformation for CICS

Language structures page

The Language structures page for compiled conversion lists all the high-level language structures in the
source file that was used to start the wizard. Before starting the wizard when using a source file, ensure
that the source file contains both the request and response language structures for your application.

Follow these steps to complete this page:

1. On the Request Language Structure tab, select the language structure which is the response
language structure of your existing application (that is, the language structure with which your
application is invoked).
2. On the Response Language Structure tab, select the language structure which is the response
language structure of your existing application (that is, the language structure that your application
returns when it terminates). For One-Way (Request only) Web Service Generation, unselect the
"Response Language Structure".
3. Click Change COBOL Preferences or Change PL/I Preferences button to open the desired
preferences page. These preferences control how source files (COBOL or PL/I) are imported (see
“Setting Importer > COBOL preferences” on page 219 or “Setting Importer > PL/I preferences” on
page 220).
Related tasks

“Setting preferences for PL/I XML converters” on page 149

“Setting preferences for COBOL XML converters” on page 145

Generation options page

The Generation options page allows you to select capabilities that you want to be included in the source
code for the request XML converter or the source code for the response XML converter.

To set default values for some of the fields on this page, use the COBOL XML Converters page in the
Preferences window (see “Setting preferences for COBOL XML converters” on page 145). or use the PL/I
XML Converters page in the Preferences window (see “Setting preferences for PL/I XML converters” on
page 149).

202 Developer for z/OS: Developing with Db2, CICS, and IMS
XML Converters tab
The XML Converters tab allows you to specify identification attributes and character encodings.
This tab contains the following fields:
• In the Specify identification attributes group:
Converter program name prefix:
Type the stem of the program name that is included in the IDENTIFICATION DIVISION of each
generated COBOL program. If you type ACCT, for example, the wizard identifies the input converter
program as ACCTI, the output converter program as ACCTO, and the driver as ACCTD.

Author name:
Type the value to be included in the AUTHOR paragraph of each generated COBOL program.

Service program name:

Type the name of the existing application that you want the Web service to invoke.

• In the Specify Enterprise COBOL for z/OS properties group:

Compiler Level:
Type the value of a specific level of the Enterprise COBOL compiler.
XMLPARSE option:
Type the value of the XML parser that is selected for the COBOL XML PARSE statement.
This option is valid only if Compiler Level is set to 4.1 or higher.
Optimization
Select whether the optimization option is enabled for the COBOL compiler. For COBOL compiler
versions 4 and earlier, when the checkbox is selected, the COBOL compiler uses optimization in
generating runtime code from COBOL source code.
If you choose to generate COBOL conversion code for compiling with the Enterprise COBOL compiler
v 5.2, the generated COBOL program has the following COBOL v 5.2 specific characteristics:
– If you choose no optimization by clearing the Optimization selection box on the “XML Converters
tab” on page 203, the OPTIMIZE (or OPT for short) compiler option is generated as “OPT(0)”
unlike COBOL compiler versions 4 and earlier (the no optimization option was generated as
NOOPT). You can achieve the same OPT option behavior by using the Batch processor with the
code generation option by specifying

<CodegenPropertyname="com.ibm.etools.xmlent.ui.GEN_COMPILE_OPTIMIZE"value="false"/>

– If you choose optimization by selecting the Optimization selection box on the “XML Converters
tab” on page 203, the OPTIMIZE compiler option is generated as “OPT(2)” unlike COBOL
compiler versions 4 and earlier (there was only one level of optimization and it was specified
as OPT). You can achieve the same OPT option behavior by using the Batch processor with the
code generation option by specifying

<CodegenPropertyname="com.ibm.etools.xmlent.ui.GEN_COMPILE_OPTIMIZE"value="true"/>

Restriction: There are no options to select intermediate optimization levels that are provided
by the COBOL v 5.2 compiler. COBOL v 5.2 compiler optimization levels other than OPT(0) and
OPT(2) are not supported.
• In the Specify character encodings group:
Request code page
Select the code page for encoding the XML input message.
Note:
– In the Web Services for CICS runtime environment, when compiled conversion is selected, CICS
performs the conversion of the text between the code page used by the Web service client and
the code page used by the Web service.

Developing web services and SOA with Enterprise Service Tools 203
 – In the other runtime environments, when compiled conversion is used, the Web service client is
responsible for the conversion between its own code page and the code page used by the Web
service.

Host code page

Select the code page for the z/OS host system.

Response code page

Select the code page for encoding the XML output message. For One-way this is disabled.
Note:
– In the Web Services for CICS runtime environment, when compiled conversion is selected, CICS
performs the conversion of the text between the code page used by the Web service client and
the code page used by the Web service.
– In the other runtime environments, when compiled conversion is used, the Web service client is
responsible for the conversion between its own code page and the code page used by the Web
service.

Use the host code page as the intermediate encoding for XML
Selecting this option can significantly improve Compiled XML Conversion performance on SBCS
EBCDIC hosts. This option is enabled by default when the host code page is EBCDIC SBCS. Clear
this checkbox only if the names of mapped XML elements or attributes contain characters that do
not exist in the host code page.

WSDL and XSD tab

The WSDL and XSD tab allows you to specify WSDL properties and XML schema definition properties.
This tab contains the following fields:
• In the Specify WSDL properties group:
Service location:
Type the URI of the web service (web service endpoint URI). This URI is used in the binding section
of the WSDL file. In the case of the SOAP binding, this URI is generated into the content of the
soap:address element.

Service name:
Type a name for the web service.
It is a good idea to choose a web service name that is descriptive and that allows for future
development. For example, a service named StockAdvisorService might include related
operations getStockQuote and getHighestPrice.

Operation name:
Type a name for the operation that is provided by the web service that is previously specified in
Service name.
It is a good idea to choose a name that describes the action that is performed by the operation - for
example, getStockQuote.

WSDL namespace:
This value sets the namespace for the generated WSDL file.
Note: Setting a value in this field in the compiled conversion scenario is equivalent to the WSDL-
NAMESPACE parameter of the CICS web services Assistant DFHLS2WS. The default value is
generated by the DFHLS2WS and full description of it can be found in the CICS Transaction Server
V 4.1 IBM Documentation, see http://www-01.ibm.com/support/knowledgecenter/SSGMCP_4.1.0/
com.ibm.cics.ts.webservices.doc/reference/dfhws_ls2ws.html or CICS® Transaction Server for z/OS,
Version 4 Release 1 IBM Documentation.

204 Developer for z/OS: Developing with Db2, CICS, and IMS
 SOAPAction:
Type the value that you want to use for the soapAction attribute of the soap:operation element in
the WSDL file that the wizard generates for the web service. A blank value causes the soapAction
attribute to be set to the empty string.
• In the Specify request XML Schema properties group:
Target namespace:
Type the namespace and schema name of the XML schema that you want to use as the request XML
schema. For example,

http://www.StartAppI.com/schemas/StartAppIInterface

Root element name:

Type the name of the global element that you want to use in the request XML schema. For example,

ProgramPassFields

Note: By default, the source program name and a character designator I for request (formally
Inbound) is used. You can override the default by editing the text in the field.
Whitespace option:
Specifies the conversion treatment for all elements in the generated schema. Select one of the
following values:
– collapse - (1) replace tab, line feed, and carriage return characters with spaces, (2) trim leading
and trailing spaces, and (3) substitute a single space for each contiguous sequence of spaces.
– replace - replace tab, line feed, and carriage return characters with spaces.
– preserve - no whitespace removal nor replacement is performed.
– compact - trim leading and trailing spaces - substitute a single space for each contiguous
sequence of spaces.
• In the Specify response XML Schema properties group:
Target namespace:
Type the namespace and schema name of the XML schema that you want to use as the response
XML schema. For example,

http://www.StartAppO.com/schemas/StartAppOInterface

Root element name:

Type the name of the global element that you want to use in the response XML schema. For
example,

ProgramPassFields

Note: By default, the source program name and a character designator O for response (formally,
Outbound) is used. You can override the default by editing the text in the field.
Whitespace option:
Specifies the conversion treatment for all elements in the generated schema. Select on of the
following values:
– collapse - (1) replace tab, line feed, and carriage return characters with spaces, (2) trim leading
and trailing spaces, and (3) substitute a single space for each contiguous sequence of spaces.
– replace - replace tab, line feed, and carriage return characters with spaces.
– preserve - no whitespace removal nor replacement is performed.
– compact - trim leading and trailing spaces - substitute a single space for each contiguous
sequence of spaces.

Developing web services and SOA with Enterprise Service Tools 205
 Advanced Options tab
The Advanced Options tab allows you to specify XML Schema generation properties, request and
response XML converter behavior, and compiler-related preferences.
This tab contains the following fields:
• In the Specify XML Schema generation properties group:
Generate minimum hierarchy in XML Schemas
This checkbox controls the message format of the generated XML schema and consequently the
parsing and generation of XML in the XML converters. XML converters based on XML schemas having
minimized hierarchies tend to have better performance.
– Select this checkbox if you want the XML converters to be generated so as to use a reduced XML
structure hierarchy, when a more detailed structure hierarchy is not needed to uniquely identify
each element in the structure.
When there are elements with the same tag name, the name of the element that occurs later in
the document is prefixed with as many of its parent tags as are required produce a unique name.
This method increases the efficiency of message processing clients and reduces the number and
complexity of objects that need to be instantiated.
– Clear this checkbox if you want the wizard to generate an XML schema that represents the full
hierarchy of the language structure.

Generate groups in XML Schemas

This checkbox controls whether the XML converter includes groups in the generated XML schemas:
– Select this checkbox if you want the XML converter to include groups in the generated XML
schemas.
– Clear this checkbox if you want the XML converter to include group "contents" inline instead
of using group references. This option is useful for applications that do not support the use of
groups and group references in XML schemas.

Generate short complex type names

The normal method for generating a complex type name is to concatenate the name of the group to
the names of all the parents of the group, with an underscore character "_" after each name except
the last.
However, if this checkbox is selected, then a complex type name is generated by taking just the
name of the group.
For example, in this COBOL group:

01 ServiceRequest.
02 CommonHeader.
05 HeaderType1.
10 Element1 PIC X(10).

the complex XML type name for the HeaderType1 element is:
– servicerequest_commonheader_headertype1 if the checkbox is not selected.
– HeaderType1 if the checkbox is selected.
The shortening of complex type names allows for the generation of more compact client code
(usually, Java class code) from the WSDL and XSD files containing the complex XML types.
The setting of this checkbox has no effect on top-down or meet-in-middle scenarios.
When shortening of a complex type name is attempted, a collision is possible if the short name of
the type already exists as the result of a previously defined type for a group with an identical name
but different parent group names. For example, in the following COBOL structure:

01 ServiceRequest.
02 CommonHeader.

206 Developer for z/OS: Developing with Db2, CICS, and IMS
 05 HeaderType.
10 Element PIC X(10).
02 SpecificHeader.
05 HeaderType.
10 Element PIC X(10).

the type name of the HeaderType group under SpecificHeader collides with the type name of
the HeaderType group under CommonHeader.
In case of a collision all colliding names keep the original long type names. Thus, in this example,
the resulting type names are:
– servicerequest_commonheader_headertype and
– servicerequest_specificheader_headertype.
The short name for a complex type is formed by taking the name of the XML element that has that
type, plus some possible modifications. The rules for forming short names are:
1. Take the name of the XML element that has the type (such as HeaderType1).
2. If the name starts with a character that is an invalid character for Java names (for example, a
digit), it is prefixed with a double underscore "__".
3. If a hyphen "-" is present in the original COBOL group name it is replaced with a single
underscore "_".
4. The case of the group name is preserved.
For example, the following group:

03 2-In--B.
04 var2 blank zero pic 999.99.

results in the shortened complex type name __2_In__B.

Generate comments in XSD
Selecting this checkbox causes the comments from the COBOL source code file to be generated as
annotation documentation in the generated XSD and WSDL files (see “Including COBOL source code
comments in generated XSD and WSDL files” on page 327)
This option applies only to the bottom-up development scenario for generating a Web service, and
applies only if you specify Compiled XML Conversion.

Generate qualified XML elements in XML schemas

This checkbox allows for generation of qualified XML elements in the XML schemas.
This allows for the option to require all XML elements be qualified with a namespace and support
generation of XML schemas that can be included in other schemas with lesser chance of namespace
collision.

• In the Specify XML to language structure converter behavior group:

Validate the target namespace of the root XML element
Select this checkbox to enable validation of the target namespace of the root element in XML
documents. The target namespace of the root element can be found in the XML schema which
defines it.
Initialize language structure members before XML conversion
Select the option to initialize all numeric and non-numeric data items to zeros and spaces
respectively before XML is converted into the language structure.
Use VALUE literals to initialize omitted data items
Select this checkbox to enable initialization for data items in the request language structure that you
have excluded from the Web service input data structure (see “Initializing data items in the COBOL
application's input data structure” on page 325 ).
This option applies only to the bottom-up development scenario for generating a Web service, and
applies only if you specify Compiled XML Conversion.

Developing web services and SOA with Enterprise Service Tools 207
 Use VALUE literals to initialize empty data items
Select this checkbox to enable initialization for data items in the request language structure that
you have included in the Web service input data structure (see “Initializing data items in the COBOL
application's input data structure” on page 325 ).
This option applies only to the bottom-up scenario for generating a Web service, and applies only if
you specify Compiled XML Conversion.

• In the Specify language structure to XML converter behavior group:

Language data
This option controls how the response runtime XML conversion program handles characters in the
response COBOL data that are illegal in the XML 1.0 specification:
– Select Filter characters illegal in XML 1.0 if you want the conversion program to scan both
non-numeric and numeric data in the language structure and convert any character that is illegal
in the XML 1.0 specification to an EBCDIC, ASCII, or UNICODE space (depending on the response
code page).
– Select Halt on characters illegal in XML 1.0 if you want the conversion program to scan both
non-numeric and numeric data in the language structure and cause an exception if characters
illegal in XML 1.0 are found.
– Select Do not check for illegal characters if you want the conversion program not to check for
characters that are illegal in the XML 1.0 specification.
For more information see “Options for handling illegal XML characters” on page 325.

Web Services for CICS page

The Web Services for CICS page is included in the wizard pages when the selected host runtime in the
wizard launchpad is Web Services for CICS.
This page allows you to specify options for the WSBind file that the wizard generates when the host
runtime is set to Web Services for CICS.
Click Change WSBind Preferences at the bottom of the page to modify the Web Services Assistant
(WSBind) preferences (see “Setting preferences for the CICS Web Services Assistant (WSBind)” on page
150).

Basic Options tab

The Basic Options tab allows you to specify the following options for the WSBind file: target information
and application program properties.
This tab contains the following fields:
• In the Specify targets for WSBind file group:
Note: Generate to: Is only applicable to single service Enterprise Service Tools projects.
Generate to:
Same project
Select this when the file container is on the local system (default).
Remote location
Select this when the file container is on a remote system. For additional information, see
“Generation of Enterprise Service Tools artifacts to remote systems” on page 333.
WSBind file container:
Type or select a path for the folder in which you want the WSBind file to be created.

WSBind file name:

Type the name for the WSBind file.

208 Developer for z/OS: Developing with Db2, CICS, and IMS
 Log file name:
Type the name for the CICS Web Services Assistant log file. The log file contains extensive
information regarding generation of the WSBind file.

Overwrite WSBind file

Select this checkbox if you want the wizard to overwrite an existing WSBind file of the same name.

• In the Specify application program properties group:

Program interface:
Select the method by which you want the existing application to be invoked:
– Select COMMAREA to invoke the existing application with the LINK command with the
COMMAREA option.
– Select CHANNEL to invoke the existing application with the LINK command with the CHANNEL
option.
Container name:
Type the container name. (This value is required when the CHANNEL item is selected in the
Program interface list.)

Advanced Options tab

The Advanced Options tab allows you to set options for the Web Services Assistant utility of the IBM
CICS Transaction Server for z/OS V3.1 or V3.2.
The values that you set on this page override, for this particular instance of the wizard, the global values
set for these same options in the Web Services Assistant (WSBind) preferences window.
This tab contains the following fields:
In the Specify Web Services Assistant options group:
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:
Valid characters: A-Z a-z 0-9 $ @ #
In a service provider, this parameter 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 parameter is used to define the USERID attribute of the URIMAP
resource when it is created automatically using the PIPELINE scan command.
Transaction:
Valid characters: A-Z a-z 0-9 $
In a service provider, this parameter 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 parameter
is used to define the TRANSACTION attribute of the URIMAP resource when it is created automatically
using the PIPELINE scan command.
Vendor converter name:
Set the name of the converter program to use when building a vendor style WSBind file. The vendor
style of WSBind file opts out of the CICS supplied XML transformation process, instead CICS links to
a converter program which is responsible for handling the XML to commarea conversion. This method
is used to set the name of the converter program. In the wizard, this value defaults to the name of the
Converter Driver file.

Developing web services and SOA with Enterprise Service Tools 209
 IMS Enterprise Suite SOAP Gateway service provider
The IMS SOAP Gateway Service Provider page is included in the wizard pages when the selected host
runtime is IMS Enterprise Suite SOAP Gateway and the selected application mode is Service Provider
in the wizard launch pad.
This page allows you to specify options for the IMS Correlator file.

IMS Correlator file

The IMS Correlator file tab allows you to specify the service identification properties and the IMS system
interaction properties for the new Web service.
This tab contains the following fields:
• In the Specify service identification properties group:
Note: Generate to: Is only applicable to single service Enterprise Service Tools projects.
Generate to:
Same project
Select this when the file container is on the local system (default).
Remote location
Select this when the file container is on a remote system. For additional information, see
“Generation of Enterprise Service Tools artifacts to remote systems” on page 333.
SOAPAction
Type the value that you want to use for the SOAPAction attribute of the soap:operation element
in the WSDL file that the wizard generates for the Web service.
This value also becomes the name of the correlator file that the wizard generates - see the File
name field.
This value must begin with urn: and must contain only characters that are valid in file names.

File container
Type or the select the path of the folder in which you want the wizard to generate the IMS correlator
file.

File name
This field displays the name of the IMS correlator file that the wizard is to generate. You can modify
this field by changing the name in the SOAPAction field.

Update, Overwrite
These radio buttons are enabled to update or overwrite the IMS correlator file that you specified in
the File container and File name fields:
– Select Update if you want the wizard to do the following:
1. Preserve all the existing entries in the IMS correlator file; and
2. Add or update information for the current Web service and operation on the WSDL and XSD
tab of the Generation Options page of the wizard.
– Select Overwrite if you want the wizard to overwrite the existing IMS correlator file.
Entries in the IMS correlator file are identified by a combination of the Web service name and the
operation name. If you specify a Web service name and an operation name that already exist in the
IMS correlator file, then the wizard initializes the request and response schema properties on this
page with the values from the IMS correlator file.

• In the Specify IMS Enterprise Suite SOAP Gateway and IMS Connect interaction properties group:
Transaction code
Type the name of the IMS transaction that is to be invoked by the Web service.
This name must be alphanumeric and must contain 8 characters or less.

210 Developer for z/OS: Developing with Db2, CICS, and IMS
 Inbound connection bundle
Type the name of the connection bundle that the Web service uses to connect to IMS Enterprise
Suite SOAP Gateway.
Connection bundles are defined in the connection specification XML file maintained by the IMS
Enterprise Suite SOAP Gateway and can be updated using the IMS Enterprise Suite SOAP Gateway
deployment tool
This name must be alphanumeric.

Socket timeout
Type the number of milliseconds that the IMS Enterprise Suite SOAP Gateway should wait for a
response from IMS Connect.

Execution timeout
Type the number of milliseconds that IMS Connect should wait for a response from the IMS
Enterprise Suite SOAP Gateway.
The maximum valid value is 3600000.

LTERM name
Type the LTERM name that is to be used to override the value in the LTERM field of the IMS
application program's I/O PCB.
You can set the value of this property if the client application wants to provide an LTERM override
name. This name is in the IMS application program's I/O PCB, with the intent that the IMS
application makes logic decisions based on the override value.
This name must be alphanumeric and must contain 8 characters or less.

Inbound WS-Security
Select the security token type that IMS Enterprise Suite SOAP Gateway will expect from users.

File, data set, or member selection page

The File, data set, or member selection page allows you to specify a path and file names for the
following items: (a) the new XML converters and converter driver; (b) the new WSDL file and XSD files; and
(c) the generation properties files.
Overwrite files
This checkbox indicates that the wizard overwrites without warning, if files with the same name exist
in the target directory.

XML Converters tab

The XML Converters tab allows you to specify a path and file names for the new XML converters and the
new converter driver.
This tab contains the following fields:
• In the Select targets for the XML conversion programs group:
Note: Generate to: Is only applicable to single service Enterprise Service Tools projects.
Generate to:
Same project
Select this when the file container is on the local system (default).
Remote location
Select this when the file container is on a remote system. For additional information, see
“Generation of Enterprise Service Tools artifacts to remote systems” on page 333.
Converter file container:
Type or select the path of a folder in which you want the wizard to create the converter files.

Developing web services and SOA with Enterprise Service Tools 211
 Converter driver file name:
Type the name of the file that you want to contain the new converter driver. (The converter driver is
the procedure that calls the request converter and the response converter.)
To suppress the generation of this file:
1. Clear the checkbox Generate all to driver, if it is set.
2. Clear the checkbox at the far left of the input field.

Request Converter file name:

Type the name of the file that you want to contain the new request converter. (The request
converter is the procedure that maps the request XML schema definition to a high-level-language
data structure.)
To suppress the generation of this file:
1. Clear the checkbox Generate all to driver, if it is set.
2. Clear the checkbox at the far left of the input field.

Response Converter file name:

Type the name of the file that you want to contain the new response converter. (The response
converter is the procedure that maps a high-level-language data structure to the response XML
schema definition.)
To suppress the generation of this file:
1. Clear the checkbox Generate all to driver, if it is set.
2. Clear the checkbox at the far left of the input field.

Generate all to driver

Select this checkbox to if you want the converter driver, the request converter, and the response
converter to be contained in one file.
Important: Prior to the availability of the "Generate Conversion Code" enhancement, where
combined converters can be generated from two mapping files, it was necessary to manually
combine two separate sets of converter programs for Web services having both request and
response messages.

Overwrite files without warning

This checkbox indicates that the wizard overwrites without warning, if files with the same name
exist in the target directory.

Service Properties tab

The DFHWS2LS Service Properties tab sets properties for the Web Services for CICS application.

On the Service Properties tab, specify the following options:

Local URI:
Type the relative URI that a client will use to access the Web service.

WSDL service:
If the WSDL file that you selected when you started the Enterprise Service Tools Wizard Launchpad
is based on the WSDL 2.0 specification, then this list displays all the services that are supported by
the binding that you selected in the Binding element list.
Select the service that you want the new Web service implementation to offer.

Binding element:
Select the binding in the Web service description that you want to be used to generate the language
structure and Web service binding file.

212 Developer for z/OS: Developing with Db2, CICS, and IMS
Available operations:
This list displays all the available operations in the service that you selected in the WSDL service list.
Select the checkbox beside each operation that you want requesters to be able to request.
Use Select All or Deselect All to select or deselect all the available operations in the list.
Click Change WSBind Preferences at the bottom of the page to modify the Web Services Assistant
(WSBind) preferences (see “Setting preferences for the CICS Web Services Assistant (WSBind)” on page
150).

Properties tab
The Properties tab allows you to specify a path and file names for the new generation properties files.
This tab is present if you started the Enterprise Service Tools Wizard Launchpad from a type of project
other than a single-service project, and if you selected the checkbox Save generation properties on the
launchpad (see “Using the Wizard Launchpad” on page 199).
This tab contains the following fields:
• In the group Select targets for the generation properties files:
Properties file container:
Type or select the path of a folder in which you want the wizard to create the generation properties
files.
Container.xml
Type the name that you want to use for the Container.xml file.

PlatformProperties.xml
Type the name that you want to use for the PlatformProperties.xml file.

ServiceSpecification.xml
Type the name that you want to use for the ServiceSpecification.xml file.

Bottom-up wizard - Interpretive XML Conversion

Use the Create New Service Interface (bottom-up) wizard with Interpretive XML Conversion to
generate files in supported runtime environments.

Overview of bottom-up (interpretive) wizard pages

This topic provides an overview of the pages in the wizards with interpretive XML conversion.
For this wizard and conversion type, Web Services for CICS and XML Transformation for CICS are the only
runtimes supported.
Table 33 on page 213 summarizes the pages and tabs for this wizard:

Table 33. Bottom-Up Interpretive Wizard Page and Tab Overview

Runtime Environment (See
Wizard Page and Tabs: Note)
W I B T M

Language structures page:

- Request Language Structure X X
- Response Language Structure

DFHLS2WS Application and Service properties page:

- Application Properties X X
- Service Properties

Developing web services and SOA with Enterprise Service Tools 213
 Table 33. Bottom-Up Interpretive Wizard Page and Tab Overview (continued)
Runtime Environment (See
Wizard Page and Tabs: Note)
W I B T M

DFHLS2WS Target artifacts page:

- Service Artifacts X X
- Properties (Optional)

CICS Deployment Options page:

X X
- Specify deployment manifest properties

Language structures page:

X
- Language Structure

DFHLS2SC XML Schema (XSD) Properties page:

X
- XSD Properties

DFHLS2SC Target artifacts page:

- Conversion Artifacts X
- Properties

CICS Deployment Options page:

X
- Start Bundle deployment wizard upon finish

Note:
• W stands for Web Services for CICS
• I stands for IMS SOAP Gateway
• B stands for Batch, TSO, and z/OS UNIX System Services
• T stands for XML Transformation for CICS
• M stands for MTOM/XOP (Message Transformation Optimization Mechanism)/(XML-binary
Optimization Package) service

Language structures page

The Language structures page for interpretive conversion lists all the high-level language structures in
the source file that was used to start the wizard. Before starting the wizard, when using a selected source
file, ensure that the source file contains both the request and response language structures for your
application.

Follow these steps to complete this page:

1. On the Request Language Structure tab, select the language structure which is the response
language structure of your existing application (that is, the language structure with which your
application is invoked).
Note: When using the MTOM/XOP (Message Transformation Optimization Mechanism)/(XML-binary
Optimization Package) development scenario, only DATA-STRUCTURE is allowed.
2. On the Response Language Structure tab, select the language structure which is the response
language structure of your existing application (that is, the language structure that your application

214 Developer for z/OS: Developing with Db2, CICS, and IMS
 returns when it terminates). For One-Way (Request only) Web Service Generation, unselect the
"Response Language Structure".
Note: When using the MTOM/XOP (Message Transformation Optimization Mechanism)/(XML-binary
Optimization Package) development scenario, only DATA-STRUCTURE is allowed.
3. Click Change PL/I Preferences or Change COBOL Preferences button to open the desired
preferences page. These preferences control how source files (PL/I or COBOL) are imported (see
“Setting Importer > PL/I preferences” on page 220 or “Setting Importer > COBOL preferences” on
page 219).
Note: The Language structure tree views on this page can show certain data types that are not supported
by the interpretive conversion. These types include the ones described in the topics “Compatibility:
Simple data types” on page 339. These specific types are marked as (contains unsupported types)
or unsupported type in the tree; these selections are automatically disabled. However, there are other
types that are not supported by the interpretive conversion and they are described in the CICS TS 4.1
Documentation, refer to CICS® Transaction Server for z/OS, Version 4 Release 1 IBM Documentation.
These types are not marked as (contains unsupported types) or unsupported type in the tree and the
selection is not automatically disabled. If you leave these data items selected, the generation fails and an
appropriate error message is shown. An error entry is also put into the Remote error list view.
Related concepts

“Introduction to mapping concepts” on page 281

Related tasks

“Bottom-up wizard - Compiled XML conversion” on page 200

“Bottom-up wizard - Interpretive XML Conversion” on page 213
“Create New Service Implementation (top-down)
wizard” on page 222
“The DFHLS2WS Application and Service properties
page” on page 215
“The DFHLS2SC Target artifacts page” on page 257

The DFHLS2WS Application and Service properties page

The DFHLS2WS Application and Service properties page sets properties for the CICS application and for
the Web service.
Follow these steps to complete this page:
1. On the Application Properties tab, specify the following options:
Program name
Specifies the name of the CICS application program that is exposed as a Web service.
Program interface
Specifies how CICS passes data to the target application program.
Note: When using the MTOM/XOP (Message Transformation Optimization Mechanism)/(XML-binary
Optimization Package) development scenario:
• If CHANNEL is selected as the program interface, then the maximum size of an MTOM/XOP
attachment (which is derived from a language structure) is 128 MB. This limitation is the
maximum size of a COBOL data item (PL/I is not supported).
• If COMMAREA is selected as the program interface, then the maximum size of an MTOM/XOP
attachment (which is derived from a language structure) is 32767 bytes. This limitation is the is
the maximum size of a DFHCOMMAREA.
Container name
Specifies the name of the container that holds the high level language structure.

Developing web services and SOA with Enterprise Service Tools 215
 Request Channel
Specifies the location of the request channel description document (the location should be on the
local system).
Note: If this value is used the mapping level must be 3.0 or higher.
Interaction between files referenced in the channel description document and language structure
selection page:
• When the channel description document points to the main source file of the EST project, the
item selections made in the Language structure selection page are PRESERVED.
• When the channel description document points to a source file that is NOT the main source
file of the EST project, the item selections made in the Language structure selection page are
IGNORED.
Response Channel
Specifies the location of the response channel description document (the location should be on the
local system).
Note: If this value is used the mapping level must be 3.0 or higher.
Interaction between files referenced in the channel description document and language structure
selection page:
• When the channel description document points to the main source file of the EST project, the
item selections made in the Language structure selection page are PRESERVED.
• When the channel description document points to a source file that is NOT the main source
file of the EST project, the item selections made in the Language structure selection page are
IGNORED.
2. On the Service Properties tab, specify the following options:
Service Location:
Specifies the URI that a client uses to access the Web service.
Note: TXSeries for Multiplatforms runtime only supports COMMAREA as Program interface.

The DFHLS2WS Target artifacts page

The DFHLS2WS Target artifacts page sets options Web service files that are generated.
To complete this page:
On the Service Artifacts tab, specify the following options:
Note: Generate to: Is only applicable to single service Enterprise Service Tools projects.
Generate to:
Same project
Select this when the file container is on the local system (default).
Remote location
Select this when the file container is on a remote system. For additional information, see “Generation
of Enterprise Service Tools artifacts to remote systems” on page 333.
File container
Specifies the folder in which the Web service files are generated.
WSDL file name
Specifies the name of the WSDL file.
WSBind file name
Specifies the name of the WSBind file.
Log file name
Specifies the name of the log file.

216 Developer for z/OS: Developing with Db2, CICS, and IMS
Overwrite files
This checkbox indicates that the wizard overwrites without warning, if files with the same name exist
in the target directory.

Bottom-up wizard - MTOM/XOP - Interpretive XML Conversion

Use the Create New MTOM/XOP Service Interface (bottom-up) wizard with Interpretive XML
Conversion to generate MTOM/XOP files in supported runtime environments.

Language structures page

The Language structures page for interpretive conversion lists all the high-level language structures in
the source file that was used to start the wizard. Before starting the wizard, when using a selected source
file, ensure that the source file contains both the request and response language structures for your
application.

Follow these steps to complete this page:

1. On the Request Language Structure tab, select the language structure which is the response
language structure of your existing application (that is, the language structure with which your
application is invoked).
Note: When using the MTOM/XOP (Message Transformation Optimization Mechanism)/(XML-binary
Optimization Package) development scenario, only DATA-STRUCTURE is allowed.
2. On the Response Language Structure tab, select the language structure which is the response
language structure of your existing application (that is, the language structure that your application
returns when it terminates). For One-Way (Request only) Web Service Generation, unselect the
"Response Language Structure".
Note: When using the MTOM/XOP (Message Transformation Optimization Mechanism)/(XML-binary
Optimization Package) development scenario, only DATA-STRUCTURE is allowed.
3. Click Change PL/I Preferences or Change COBOL Preferences button to open the desired
preferences page. These preferences control how source files (PL/I or COBOL) are imported (see
“Setting Importer > PL/I preferences” on page 220 or “Setting Importer > COBOL preferences” on
page 219).
Note: The Language structure tree views on this page can show certain data types that are not supported
by the interpretive conversion. These types include the ones described in the topics “Compatibility:
Simple data types” on page 339. These specific types are marked as (contains unsupported types)
or unsupported type in the tree; these selections are automatically disabled. However, there are other
types that are not supported by the interpretive conversion and they are described in the CICS TS 4.1
Documentation, refer to CICS® Transaction Server for z/OS, Version 4 Release 1 IBM Documentation.
These types are not marked as (contains unsupported types) or unsupported type in the tree and the
selection is not automatically disabled. If you leave these data items selected, the generation fails and an
appropriate error message is shown. An error entry is also put into the Remote error list view.
Related concepts

“Introduction to mapping concepts” on page 281

Related tasks

“Bottom-up wizard - Compiled XML conversion” on page 200

“Bottom-up wizard - Interpretive XML Conversion” on page 213
“Create New Service Implementation (top-down)
wizard” on page 222
“The DFHLS2WS Application and Service properties
page” on page 215
“The DFHLS2SC Target artifacts page” on page 257

Developing web services and SOA with Enterprise Service Tools 217
 The DFHLS2WS Application and Service properties page
The DFHLS2WS Application and Service properties page sets properties for the CICS application and for
the Web service.
Follow these steps to complete this page:
1. On the Application Properties tab, specify the following options:
Program name:
Specifies the name of the CICS application program that is exposed as a Web service.
Program interface:
Specifies how CICS passes data to the target application program.
Container name:
Specifies the name of the container that holds the high level language structure.
2. On the Service Properties tab, specify the following options:
Service Location:
Specifies the URI that a client uses to access the Web service.
Operation name:
The value specified for this option is used in the generated WSDL. If a value is not specified,
the default operation name will be used. The default operation name is "CICS program name" +
"Operation".
Request namespace
Specifies the location of the request namespace document.
Response namespace
Specifies the location of the response namespace document.
Click Change WSBind Preferences at the bottom of the page to modify the Web Services Assistant
(WSBind) preferences (see “Setting preferences for the CICS Web Services Assistant (WSBind)” on page
150).

The DFHLS2WS Target artifacts page

The DFHLS2WS Target artifacts page sets options Web service files that are generated.
To complete this page:
On the Service Artifacts tab, specify the following options:
Note: Generate to: Is only applicable to single service Enterprise Service Tools projects.
Generate to:
Same project
Select this when the file container is on the local system (default).
Remote location
Select this when the file container is on a remote system. For additional information, see “Generation
of Enterprise Service Tools artifacts to remote systems” on page 333.
File container:
Specifies the folder in which the Web service files are generated.
WSDL file name:
Specifies the name of the WSDL file.
WSBIND file name:
Specifies the name of the WSBind file.
Log file name:
Specifies the name of the log file.
Overwrite files
This checkbox indicates that the wizard overwrites without warning, if files with the same name exist
in the target directory.

218 Developer for z/OS: Developing with Db2, CICS, and IMS
Setting Importer > COBOL preferences
Use these preferences to control how COBOL files are imported. These settings affect all COBOL files that
you import into the workspace, for any project.
To set preferences for importing COBOL files:
1. In the left pane of the Preferences window, expand Importer and select COBOL.
2. Change the preferences (see the following information).
The options are as follows:
Note: For a more detailed description of these options see the Enterprise COBOL for z/OS Programming
Guide Version 3 Release 4, available from the Enterprise COBOL for z/OS Web site at http://
www-306.ibm.com/software/awdtools/cobol/zos/.
Platform
Specifies the target generation platform. Select the appropriate value from the pull down list.
Code Page Selection
Specifies the code page for the locale. Select the appropriate value from the popup window. See
“Supported code pages (CCSIDs)” on page 429.
Floating point format
Specifies the floating point format. Select the appropriate value from the pull down list.
endian
Select the appropriate value from the available options.
Remote integer endian
Select the appropriate value from the available options.
External decimal sign
Select the appropriate value from the available options.
Specify the COBOL options
QUOTE
Select the appropriate value from the available options.
TRUNC
Select the appropriate value from the available options.
NSYMBOL
Select the appropriate value from the available options.
Compile time locale name
Specifies the compile time locale. Select the appropriate value from the pull down list.
Please see “COBOL importer: Compile-time locale and code page” on page 528 for additional
information.
ASCII code pages
Specifies the ASCII code page. Select the appropriate value from the pull down list.
Error messages language
Specifies the default language for the error messages. Select the appropriate value from the pull
down list.
Currency sign
Specifies the currency sign. Enter the appropriate value in the space provided.
SOSI
Select the checkbox to enable SOSI.
COLLSEQ
Select the appropriate value from the available options.
NCOLLSEQ
Select the appropriate value from the available options.

Developing web services and SOA with Enterprise Service Tools 219
 File Extension Support
Specify the file extension support. To change the value, select support for a specific file extension
and then, using the pulldown arrow, select the new value from the pull down list.
For a more detailed description of these options see the Enterprise COBOL for z/OS Programming Guide
Version 3 Release 4, available from the Enterprise COBOL for z/OS Web site at http://www-306.ibm.com/
software/awdtools/cobol/zos/.

Setting Importer > PL/I preferences

Use these preferences to control how PL/I files are imported. These settings affect all PL/I files that you
import into the workspace, for any project.
To set preferences for importing PL/I files:
1. In the left pane of the Preferences window, expand Importer and select PL/I.
2. Change the preferences (see the following information).
For a more detailed description of these options see the Enterprise PL/I for z/OS Programming Guide
Version 3 Release 6, available from the Enterprise PL/I for z/OS Web site.
On the General tab the options are as follows:
Platform
Specifies the target generation platform. Select the appropriate value from the list.
Code Page
Specifies the code page for the locale. Select the appropriate value from the popup window. See
“Supported code pages (CCSIDs)” on page 429.
Enable IMS support
This option is not used with Enterprise Service Tools single-service projects.
CICS option
Selects the level of CICS translation to be done when imported PL/I source files are processed:
None
No translation.
CICS Transaction Server for z/OS V3.1
The translator for CICS Transaction Server for z/OS V3.1 is used.
CICS Transaction Server for z/OS V3.2
The translator for CICS Transaction Server for z/OS V3.2 is used.
Floating point format
Specifies how the PL/I importer interprets floating point data in the absence of explicit information in
the source code, such as an inline compiler directive or an attribute of the data item.
For example, if this option is set to IEEE Decimal:
• A FLOAT BIN(23) in the source code is interpreted as Enterprise PL/I IEEE Decimal floating point.
• A FLOAT BIN(23) IEEE in the source code is interpreted as Enterprise PL/I IEEE Binary floating
point.
Endian
Select the appropriate value from the available options.
Specify the PL/I options
DBCS option
Select the appropriate value from the available options.
Graphic option
Select the appropriate value from the available options.
File Extension Support
Specify the file extension support. To change the value, select support for a specific file extension and
then, using the pulldown arrow, select the new value from the pull down list.

220 Developer for z/OS: Developing with Db2, CICS, and IMS
On the More PL/I options tab the options are as follows:
Specify the PL/I options
Error message language
Specifies the error message language. Select the appropriate value from the pull down list.
LIMITS
NAME:
Specifies the maximum length of variable names in your program. The maximum value allowed is
100; the minimum value is 31.
EXTNAME:
Specifies the maximum length for EXTERNAL name. The maximum value allowed 100; the
minimum value is 7.
FIXEDBIN:
Select the appropriate value from the pull down list.
FIXEDEC:
Select the appropriate value from the pull down list.
Margins
Left: The column number of the leftmost character (first data byte) that is processed by the
compiler. This value cannot exceed 100.
Right: The column number of the rightmost character (last data byte) that is processed by the
compiler. This value should be greater that the value of Left but the value cannot exceed 200,
except under MVS batch where the value cannot exceed 100.
Macro preprocessor
Select the appropriate value from the available options.
SYSPARM The SYSPARM option allows you to specify the value of the string that is returned by the
macro facility built-in function SYSPARM.
Character conversion
BLANK
Specifies the blank character. Enter the appropriate value in the space provided.
Currency sign
Specifies the currency sign. Enter the appropriate value in the space provided.
NOT
Specifies the character for NOT. Enter the appropriate value in the space provided.
OR
Specifies the character for OR. Enter the appropriate value in the space provided.
NAMES
Select the appropriate value from the available options.
For a more detailed description of these options see the Enterprise PL/I for z/OS Programming Guide
Version 3 Release 6, available from the Enterprise PL/I for z/OS Web site at http://www-306.ibm.com/
software/awdtools/pli/plizos/.

CICS deployment options

This page provides the ability to record the CICS Region and pipeline information in the CICS deployment
manifest file.
The fields on this page are as follows:
Copy the wsbind file to the selected pickup directory: When selected, if the z/OS UNIX System Services
subsystem with the SAME server as of the CICS connection is defined and connected, this function is
available. If this is function is available, the list of CICS System/Region and pipeline information from
the CICS manifest file is provided. If this function is not available, a error message is provided. You can
open the manifest file in the Resource Definition editor, which can be used to define/install/scan CICS
resources.

Developing web services and SOA with Enterprise Service Tools 221
 Generate deployment manifest file: This is the location of the deployment file. Enter path and file
name (.admr extension). Selecting this option enables the options in the Specify deployment manifest
properties group.
Note: In the case where the manifest file already exists in the project, any manual changes made to the
manifest file are preserved when the file is regenerated by selecting Generate Web Services for CICS
resources..
For more information, refer to message ID CRRZX0131W.
In the Specify deployment manifest properties group:
• Target CICS region: Select a CICS region.
• Refresh: After any new CICS Connection(s) are defined via the Define CICS Connection link, select
Refresh to see the new target CICS regions.
• Define CICS connection: Opens the CICS Connection section of the preferences page. Use this to
define a CICS Connection.
• Pickup directory and Pipeline : In order to add the capability to install the web service (that is, scan the
pipeline) , the selected pipeline is recorded in the CICS manifest file.
For more information, refer to http://www-01.ibm.com/support/knowledgecenter/SSGMCP_4.1.0/
com.ibm.cics.ts.resourcedefinition.doc/resources/webservice/dfha4_overview.html.
Related information
Opening the Preferences window

Create New Service Implementation (top-down) wizard

Use the Create New Service Implementation (top-down) wizard to generate artifacts for implementing a
Web service for the Web Services for CICS runtime environment.

The top-down development scenario is available only when the host runtime is Web Services for CICS and
only with interpretive XML conversion.
This wizard provides functionality similar to that of the DFHWS2LS utility in the CICS Web Services
Assistant.

Overview of top-down wizard pages

This topic provides an overview of the pages in the wizards.
This wizard is available only when the selected host runtime in the launchpad is Web Services for CICS
or XML Transformation for CICS.
The wizard has the same pages and tabs whether the selected application mode in the launch pad is
Service Provider or Service Requester.
Table 34 on page 222 summarizes the pages and tabs for this wizard:

Table 34. Top-Down Wizard Page and Tab Overview

Runtime Environment
Wizard Page and Tabs: (See Note)
W I B T

DFHWS2LS Application and

Service properties page:
X
- Application Properties
- Service Properties

222 Developer for z/OS: Developing with Db2, CICS, and IMS
Table 34. Top-Down Wizard Page and Tab Overview (continued)
Runtime Environment
Wizard Page and Tabs: (See Note)
W I B T

DFHWS2LS Target artifacts page:

- Structures
- WSBind X
- Template
- Properties (Optional)

CICS Deployment Options page:

X
- Specify deployment manifest properties

The DFHSC2LS Application and

Transformation properties page:
X
- Application Properties
- Transformation Properties

The DFHSC2LS Target artifacts page:

- Structures
X
- XSDBind
- Properties

CICS Deployment Options page:

X
- Start Bundle deployment wizard upon finish

Note:
• W stands for Web Services for CICS
• I stands for IMS Enterprise Suite SOAP Gateway
• B stands for Batch, TSO, and z/OS UNIX System Services
• T stands for XML Transformation for CICS

The DFHWS2LS Application and Service properties page

The DFHWS2LS Application and Service properties page sets properties for Web Services for CICS.

Note: This wizard provides functionality similar to that of the DFHWS2LS utility in the Web Services for
CICS Assistant.
Click Change WSBind Preferences at the bottom of the page to modify the Web Services Assistant
(WSBind) preferences (see “Setting preferences for the CICS Web Services Assistant (WSBind)” on page
150).

Application Properties tab

The DFHWS2LS Application Properties tab sets properties for the CICS application and for the Web
service.

1. In the Application Properties tab, specify the following options:

Developing web services and SOA with Enterprise Service Tools 223
 Application Language:
Select the high-level language that you want to be used for the generated language structures and
the program template.

Program name:
Type the program name of the new service provider or requester application.

Program interface:
Select the option that you want CICS to use to pass data to the new service provider application.
This field is not available when the selected application mode in the launch pad is Service
Requester.

Container name:
Type the name of the container that holds the high level language structure.
This field is not available when the selected application mode in the launch pad is Service
Requester.

Click Change WSBind Preferences at the bottom of the page to modify the Web Services Assistant
(WSBind) preferences (see “Setting preferences for the CICS Web Services Assistant (WSBind)” on page
150).

Service Properties tab

The DFHWS2LS Service Properties tab sets properties for the Web Services for CICS application.

On the Service Properties tab, specify the following options:

Local URI:
Type the relative URI that a client will use to access the Web service.

WSDL service:
If the WSDL file that you selected when you started the Enterprise Service Tools Wizard Launchpad
is based on the WSDL 2.0 specification, then this list displays all the services that are supported by
the binding that you selected in the Binding element list.
Select the service that you want the new Web service implementation to offer.

Binding element:
Select the binding in the Web service description that you want to be used to generate the language
structure and Web service binding file.

Available operations:
This list displays all the available operations in the service that you selected in the WSDL service list.
Select the checkbox beside each operation that you want requesters to be able to request.
Use Select All or Deselect All to select or deselect all the available operations in the list.
Click Change WSBind Preferences at the bottom of the page to modify the Web Services Assistant
(WSBind) preferences (see “Setting preferences for the CICS Web Services Assistant (WSBind)” on page
150).

The DFHWS2LS Target artifacts page

The DFHWS2LS Target artifacts page sets targets for the WSBind and language structures fields.

Structures tab
The DFHWS2LS Structures tab sets targets for generating language structures files.
On the Structures tab, specify the following options:
Note: Generate to: Is only applicable to single service Enterprise Service Tools projects.
Generate to:
Same project

224 Developer for z/OS: Developing with Db2, CICS, and IMS
 Select this when the file container is on the local system (default).
Remote location
Select this when the file container is on a remote system. For additional information, see “Generation
of Enterprise Service Tools artifacts to remote systems” on page 333.
File container:
Specifies the local or remote folder to which the generated artifacts are written.

Request file prefix:

Specifies a 1 - 6 character prefix used to generate the filenames that contain the high level language
structures for the Web service request.

Response file prefix:

Specifies a 1 - 6 character prefix used to generate the filenames that contain the high level language
structures for the Web service response.

Overwrite files
This checkbox indicates that the wizard overwrites without warning, if files with the same name exist
in the target directory.

WSBind tab
The DFHWS2LS WSBind tab sets targets for WSBind files.
On the WSBind tab, specify the following options:
Note: Generate to: Is only applicable to single service Enterprise Service Tools projects.
Generate to:
Same project
Select this when the file container is on the local system (default).
Remote location
Select this when the file container is on a remote system. For additional information, see “Generation
of Enterprise Service Tools artifacts to remote systems” on page 333.
File container:
Specifies the local or remote folder to which the WSBind file is written.

WSBIND file name:

Specifies the name for the WSBind file.

Log file name:

Specifies the name for the log file.

Overwrite files
This checkbox indicates that the wizard overwrites without warning, if files with the same name exist
in the target directory.

Template tab
The DFHWS2LS Template tab sets the template file names for WSBind files.
On the Template tab, specify the following options:
Note: Generate to: Is only applicable to single service Enterprise Service Tools projects.
Generate to:
Same project
Select this when the file container is on the local system (default).
Remote location

Developing web services and SOA with Enterprise Service Tools 225
 Select this when the file container is on a remote system. For additional information, see “Generation
of Enterprise Service Tools artifacts to remote systems” on page 333.
File container:
Specifies the local or remote folder to which the template file is written.

Template file name:

Specifies the name for the template sfile.

Overwrite files
This checkbox indicates that the wizard overwrites without warning, if files with the same name exist
in the target directory.

Properties tab
The DFHWS2LS Properties tab allows you to specify a path and file names for the new generation
properties files.
This tab contains the following fields:
Properties file container:
Type or select the path of a folder in which you want the wizard to create the generation properties
files.

Container.xml
Type the name that you want to use for the Container.xml file.

PlatformProperties.xml
Type the name that you want to use for the PlatformProperties.xml file.

ServiceSpecification.xml
Type the name that you want to use for the ServiceSpecification.xml file.

CICS deployment options

This page provides the ability to record the CICS Region and pipeline information in the CICS deployment
manifest file.
The fields on this page are as follows:
Copy the wsbind file to the selected pickup directory: When selected, if the z/OS UNIX System Services
subsystem with the SAME server as of the CICS connection is defined and connected, this function is
available. If this is function is available, the list of CICS System/Region and pipeline information from
the CICS manifest file is provided. If this function is not available, a error message is provided. You can
open the manifest file in the Resource Definition editor, which can be used to define/install/scan CICS
resources.
Generate deployment manifest file: This is the location of the deployment file. Enter path and file
name (.admr extension). Selecting this option enables the options in the Specify deployment manifest
properties group.
Note: In the case where the manifest file already exists in the project, any manual changes made to the
manifest file are preserved when the file is regenerated by selecting Generate Web Services for CICS
resources..
For more information, refer to message ID CRRZX0131W.
In the Specify deployment manifest properties group:
• Target CICS region: Select a CICS region.
• Refresh: After any new CICS Connection(s) are defined via the Define CICS Connection link, select
Refresh to see the new target CICS regions.
• Define CICS connection: Opens the CICS Connection section of the preferences page. Use this to
define a CICS Connection.

226 Developer for z/OS: Developing with Db2, CICS, and IMS
 • Pickup directory and Pipeline : In order to add the capability to install the web service (that is, scan the
pipeline) , the selected pipeline is recorded in the CICS manifest file.
For more information, refer to http://www-01.ibm.com/support/knowledgecenter/SSGMCP_4.1.0/
com.ibm.cics.ts.resourcedefinition.doc/resources/webservice/dfha4_overview.html.
Related information
Opening the Preferences window

Map to an Existing Service Interface (meet-in-middle) wizard

Use the Map to an Existing Service Interface wizard to generate Web service files from source and
target XML schema definitions and high-level-language data structures for request mapping and response
mapping.

Overview
The steps for generating service interface files in the meet-in-middle development scenario are as
follows:
1. Generate an initial request mapping session file that contains a source XML schema definition and a
target high-level-language data structure.
2. Generate an initial response mapping session file that contains a source high-level-language data
structure and a target XML schema definition.
3. In the request mapping session file, specify the field-to-field mappings between the source XML
schema definition and the target high-level-language data structure.
4. In the response mapping session file, specify the field-to-field mappings between the source high-
level-language data structure and the target XML schema definition.
5. Generate service interface files from the request mapping session file and the response mapping
session file.
The following table shows the same steps with additional detail:

Input files containing source

data structure and target data
structure:
Development
Step: tool: Source: Target: Files generated: Link:
1) Generate a Create XML, XSD, or CBL Request “1. Generate a
request mapping Mappings WSDL (See Note mapping session request mapping
session file. wizard 1) file session file” on
page 230
2) Generate an Create CBL XML, XSD, or Response “2. Generate a
response Mappings WSDL (See Note mapping session response
mapping session wizard 2) file mapping session
file. file” on page 232
3) Specify the Mapping editor Request mapping session file Request “3. Create data
field-to-field mapping session mappings in the
mappings in the file (with request mapping
request mapping mappings) session file” on
session file: page 234

Developing web services and SOA with Enterprise Service Tools 227
 Input files containing source
data structure and target data
structure:
Development
Step: tool: Source: Target: Files generated: Link:
4) Specify the Mapping editor Response mapping session file Response “4. Create data
field-to-field mapping session mappings in the
mappings in the file (with response
response mappings) mapping session
mapping session file” on page 234
file:
5) Generate the Map to an • Request mapping session file Web service files “5. Generate
service interface Existing Service (with mappings) (See Note service interface
files: Interface 3): .cbl .wsbind . files” on page
• Response mapping session file
(meet-in- wsdl .xml 235
(with mappings)
middle) wizard

Note:
1. For the Web Services for CICS runtime, the source file for an request mapping must be a .WSDL file (cannot
be an XSD file or an XML file).
2. For the Web Services for CICS runtime, the target file for an response mapping must be a .WSDL file (cannot
be an XSD file or an XML file).
3. The number and types of the Web service files that are generated depends on the target runtime
environment.

Overview of the wizards

In Steps 1 and 2 of the meet-in-middle development scenario, you run the CreateMappings wizard twice,
with different inputs, to generate the following files:
• An request mapping session file.
• An response mapping session file.
In Steps 3 and 4 you use the mapping editor to set up mappings in each mapping session file.
In Step 5, you run the Map an Existing Service Interface (meet-in-middle) wizard. This wizard takes the
request and response mapping session files as input and generates source files and control files for a Web
service.
The CreateMappings wizard and the Map an Existing Service Interface (meet-in-middle) wizard are
available in only one of the three contexts described previously (see “Contexts for starting the single-
service wizards” on page 194).
That context is a project other than an Enterprise Service Tools single-service project that contains the
proper source files, such as a local z/OS project in the z/OS Projects perspective.
The following table summarizes this information:

Wizard: View: Type of project:

Create Mappings wizard Any view in which the project is • A project other than an
displayed. Enterprise Service Tools single-
Map an Existing Service Any view in which the project is service project that contains
Interface (meet-in-middle) displayed. the proper source files.
wizard • For example, a local z/OS
project in the z/OS Projects
perspective.

228 Developer for z/OS: Developing with Db2, CICS, and IMS
Files types for the source and target entities in request or response mapping session
files
A mapping session file, whether it is a request mapping session file or a response mapping session file,
always describes a transfer of data between a high-level-language data structure and an XML schema
definition. The XML schema definition can be derived from: (a) an XML schema definition in an XSD file; (b)
an XML schema definition in a WSDL file; or (c) an element in an XML instance document (XML file).
• A request mapping session file must describe a transfer of data from an XML schema definition to a
high-level-language data structure.
• A response mapping session file must describe a transfer of data from a high-level-language data
structure to an XML schema definition.
The high-level-language data structure must be located in a COBOL file (extension .cbl, .cob, .cpy, or .ccp).
The type of file from which the XML schema definition can be taken or derived depends on the host
runtime environment for which the service-interface-output files are being generated:
• If the host runtime environment is Web Services for CICS, then the XML schema definition must be
taken from a WSDL file. (The Web Services for CICS runtime requires a WSBind file, which can be
generated from information in the WSDL file.)
• If the host runtime environment is XML Transformation for CICS, this runtime is not supported for the
meet-in-middle development scenario.
• If the host runtime environment is one of the other runtime environments (IMS Enterprise Suite SOAP
Gateway, or Batch, TSO, and z/OS UNIX System Services) then the XSD schema definition can be
taken from a WSDL file or an XSD file, or can be derived from an XML schema instance document (XML
file).

Table 35. Summary of File Types for the Source and Target Entities when Mapping (Request or Response)
Request mapping - type of file Response mapping - type of file
Runtime: required for data definition: required for data definition:
Source: Target: Source: Target:
Web Services for WSDL .cbl, .cpy, .cob,, .cc .cbl, .cpy, .cob, .cc WSDL
CICS p p
XML Transformation NOT SUPPORTED NOT SUPPORTED NOT SUPPORTED NOT SUPPORTED
for CICS

• IMS Enterprise WSDL, XML, XSD .cbl, .cpy, .cob, .cc .cbl, .cpy, .cob, .cc WSDL, XML, XSD
Suite SOAP p p
Gateway
• Batch, TSO, and
z/OS UNIX System
Services

Types of Web service generated - service provider or service requester

You can generate a service provider for any of the supported runtime environments. But you can generate
a service requester only for the Web Services for CICS runtime environment or the IMS Enterprise Suite
SOAP Gateway runtime environment.

Target runtime environment: Types of Web service generated:

Web Services for CICS: • Service provider
• Service requester

Developing web services and SOA with Enterprise Service Tools 229
 Target runtime environment: Types of Web service generated:
IMS Enterprise Suite SOAP Gateway • Service provider
• Service requester

XML Transformation for CICS Not supported in Meet-in-Middle scenario

Batch, TSO, and z/OS UNIX System Services • Service provider

Mapping
Mapping is the process of relating parts of two existing data structures to one another. Typically, the result
of the mapping process is a generated runtime code that transforms and moves data between mapped
elements. Enterprise Service Tools for mapping allow mapping between data structures defined by an
existing XML schema definition (or some of its derivatives, such as XML instance documents) and data
defined by an existing COBOL data structure.
For example, you might have a COBOL data structure named ACCOUNTINFO containing all the relevant
information about an account, and you want to map just the address information from ACCOUNTINFO into
an element of a complex type named AddressInfo in an XML schema definition. In this situation you want
to create a mapping from certain fields in ACCOUNTINFO to certain fields in AddressInfo.
Request mapping means that the mapping that is done from (a) an XML instance document that a Web
service receives; to (b) a high-level-language data structure that the Web service uses in some way.
For example, if the Web service is a service provider, then the Web service receives a request request
containing an XML instance document, and the Web service maps the information in the XML instance
document to a high-level-language data structure that the Web service then passes to a local application
to process.
Response mapping means the mapping that is done from (a) a high-level-language data structure that a
Web service acquires in some way; to (b) an XML instance document that the Web service sends out.

1. Generate a request mapping session file

Use the Create Mappings wizard to create an request mapping session file.
The first step in the meet-in-middle scenario is to generate a request mapping session file.

Starting the Create Mappings wizard (request mapping)

This topic describes how to start the CreateMappings wizard to create an request mapping session file.
To start the wizard:
1. Expand a project other than an Enterprise Service Tools single-service project, such as a local z/OS
project in the z/OS Projects perspective.
2. Right-click a WSDL, XSD, or XML file.
3. Select Enable Enterprise Web Service. The Enterprise Service Tools Wizard Launchpad opens.
4. In the launchpad:
a. Select the host runtime (see “Using the Wizard Launchpad” on page 199).
b. In the Development scenario list, select Map an Existing Interface (meet-in-middle).
c. Make selections in other fields on the launchpad if you wish (see “Using the Wizard Launchpad” on
page 199).
d. Click Start.
The Create Mappings wizard opens.

230 Developer for z/OS: Developing with Db2, CICS, and IMS
Create Mappings wizard (request mapping): First page
The first page of the Create Mappings wizard (request mapping), titled Create Mappings, allows you to
specify two files that contain the source XML schema definition and the target high-level-language data
structure that you want to use in the request mapping session file.
The XML schema definition can be taken or derived from: (a) an XML schema definition in an XSD file; (b)
an XML schema definition in a WSDL file; or (c) an element in an XML instance document (XML file).
The fields on this page of the wizard are as follows:
Mapping source
Specify a file of type WSDL, XSD, or XML that contains, defines, or provides an instance of the XML
schema definition that you want to use as the source data structure for the request mapping session
file.
Important: If you specify a high-level-language file (such as QueryAccount.cbl) for this field, then
the wizard changes to response mapping mode.

Mapping target:
Specify a high-level-language file (extension .cbl, .cob, .cpy, or .ccp) that contains the data structure
that you want to use as the target data structure for request mapping session file.

When you are finished with this page click Next.

CreateMappings wizard (request mapping): Second page

The second page of the Create Mappings wizard (request mapping), titled Root XML Element and
Language Structure Selection, allows you to select a source XML schema definition and a target high-
level-language data structure from the two files that you specified on the first page of the wizard.

Part of the contents of this page depend on the type of the file that you specified in the Mapping source
field on the first page of the wizard. See the following subtopics:
• “When the Mapping source file is XSD or XML” on page 231
• “When the Mapping source file is WSDL” on page 231

When the Mapping source file is XSD or XML

When the type of the file in Mapping source field on the first page of the wizard is XML or XSD, then the
fields on this page of the wizard are as follows:
Source root element
Select the root element of the XML schema definition that you want to use as the source XML schema
definition for the request mapping session file.

Target language structure

Select the high-level-language data structure that you want to use as the target structure for the
request mapping session file.

When the Mapping source file is WSDL

When the type of the file in Mapping source field on the first page of the wizard is WSDL, then the fields
on this page of the wizard are as follows:
Select the source XML element from the Web service definition (GROUP)
The fields in this group are as follows:
Service
Select the name of a Web service whose information is stored in the WSDL file.

Port
Select a portType associated with the Web service.

Developing web services and SOA with Enterprise Service Tools 231
 Operation
Select an operation belonging to the selected portType.

Message
Select an input message belonging to the selected operation.

Part
Select a part from the selected message.

Selected element
This is the element specified in the selected part.

Target language structure (FIELD)

Select the high-level-language data structure that you want to use as the target structure for the
request mapping session file.

CreateMappings wizard: Third page

The third page of the New XML to COBOL or PL/I Mapping Session wizard (request mapping), titled New
XML to COBOL or PL/I Mapping Session allows you to specify a path and name for the new mapping
session file.
The fields on this page of the wizard are as follows:
Mapping file folder
Specify the path for the folder in which you want the new request mapping session file to be created.

Map file name:

Specify a name for the new request mapping session file.

The new request mapping session file is created with the file extension .mapping.

2. Generate a response mapping session file

Use the New XML to COBOL or PL/I Mapping Session wizard to create an response mapping session file.
The second step in the meet-in-middle scenario is to generate a response mapping session file.

Create Mappings wizard (response mapping)

This topic describes how to start the Create Mappings wizard to create an response mapping session file.
To start the wizard:
1. Expand a project other than an Enterprise Service Tools single-service project, such as a local z/OS
project in the z/OS Projects perspective.
2. Right-click a COBOL source file or copy book.
3. Select Enable Enterprise Web Service. The Enterprise Service Tools Wizard Launchpad opens.
4. In the launchpad:
a. Select the host runtime (see “Using the Wizard Launchpad” on page 199).
b. In the Development scenario list, select Map an Existing Interface (meet-in-middle).
c. Make selections in other fields on the launchpad if you wish (see “Using the Wizard Launchpad” on
page 199).
d. Click Start.
The Create Mappings wizard opens.

232 Developer for z/OS: Developing with Db2, CICS, and IMS
CreateMappings wizard (response mapping): First page
The first page of the New XML to COBOL or PL/I Mapping Session wizard (response mapping) allows you
to specify two files that contain the source high-level-language data structure and the target XML schema
definition that you want to use in the response mapping session file.
The XML schema definition can be taken or derived from: (a) an XML schema definition in an XSD file; (b)
an XML schema definition in a WSDL file; or (c) an element in an XML instance document (XML file).
The fields on this page of the wizard are as follows:
Mapping source
Specify a high-level-language file (extension .cbl, .cob, .cpy, or .ccp) that contains the data structure
that you want to use as the source data structure for the response mapping session file.
Important: If you specify a WSDL, XSD, or XML file for this field, then the wizard changes to request
mapping mode.

Mapping target:
Specify a file of type WSDL, XSD, or XML that contains, defines, or provides an instance of the XML
schema definition that you want to use as the target data structure for the response mapping session
file.
Important: If you specify a high-level-language file (such as QueryAccount.cbl) for this field, then
the wizard changes to response mapping mode.

When you are finished with this page click Next.

Create Mappings wizard (response mapping): Second page

The second page of the Create Mappings wizard (response mapping), titled Root XML element and
Language Structure Selection, allows you to select a source high-level-language data structure and a
target XML schema definition from the two files that you specified on the first page of the wizard.
Part of the contents of this page depend on the type of the file that you specified in the Mapping target
field on the first page of the wizard. See the following subtopics:
• “When the Mapping target file is XSD or XML” on page 233
• “When the Mapping target file is WSDL” on page 233

When the Mapping target file is XSD or XML

When the type of the file in Mapping target field on the first page of the wizard is XML or XSD, then the
fields on this page of the wizard are as follows:
Source language structure
Select the high-level-language data structure that you want to use as the source data structure for the
response mapping session file.

Target root element

Select the root element of the XML schema definition that you want to use as the source XML schema
definition for the response mapping session file.

When the Mapping target file is WSDL

When the type of the file in Mapping target field on the first page of the wizard is WSDL, then the fields on
this page of the wizard are as follows:
Source language structure (FIELD)
Select the high-level-language data structure that you want to use as the source data structure for the
response mapping session file.

Developing web services and SOA with Enterprise Service Tools 233
 Select the target XML element from the Web service definition (GROUP)
Note: This group is present if you specified a file of type WSDL in the Mapping target field on the first
page of the wizard.
The fields in this group are as follows:
Service
Select the name of a Web service whose information is stored in the WSDL file.

Port
Select a portType associated with the Web service.

Operation
Select an operation belonging to the selected portType.

Message
Select an output message belonging to the selected operation.

Part
Select a part from the selected message.

Selected element
This is the element specified in the selected part.

Create Mappings (response mapping): Third page

The third page of the Create Mappings wizard (response mapping) allows you to specify a path and name
for the new mapping session file.
The fields on this page of the wizard are as follows:
Mapping file folder
Specify the path for the folder in which you want the new response mapping session file to be created.

Map file name:

Specify a name for the new response mapping session file.

The new response mapping session file is created with the file extension .mapping.

3. Create data mappings in the request mapping session file

Use the mapping editor to indicate how you want data mapped from the source XML schema definition to
the target data structure in the request mapping session file.
Except for the type of mapping session file that you edit (here, a request mapping session file) this step is
the same for request mapping as for response mapping.
To create the request mappings, see “Using the mapping editor to create data mappings in a mapping
session file” on page 246.

4. Create data mappings in the response mapping session file

Use the mapping editor to indicate how you want data mapped from the source data structure to the
target XML schema definition in the response mapping session file.
Except for the type of mapping session file that you edit (here, an response mapping session file) this step
is the same for request mapping as for response mapping.
To create the response mappings, see “Using the mapping editor to create data mappings in a mapping
session file” on page 246.

234 Developer for z/OS: Developing with Db2, CICS, and IMS
5. Generate service interface files
Use the Map an Existing Service Interface (meet-in-middle) wizard to generate service interface files
from a request mapping session file and a response mapping session file.

Starting the Map an Existing Service Interface (meet-in-middle) wizard

This topic describes how to start the Map an Existing Service Interface (meet-in-middle) wizard to
generate Web service files.
Important: The Map an Existing Service Interface (meet-in-middle) wizard is available only when the
project is not an Enterprise Service Tools single-service project.
To start the wizard:
1. Select the mapping session files for the Web service that you want to create:
Bidirectional Web service:
If you want the meet-in-middle wizard to create a bidirectional Web service, then select an request
mapping session file and an response mapping session file.
Unidirectional Web service:
If you want the meet-in-middle wizard to create a unidirectional Web service, then select just one
mapping session file: either an request mapping session file or an response mapping session file.

2. Right-click anywhere in the view that contains the mapping files.

3. Select Generate Conversion Code. The Enterprise Service Tools Wizard Launchpad opens.
4. In the launchpad:
a. In the Host runtime list, select a host runtime (see “Using the Wizard Launchpad” on page 199).
b. In the Application mode list, select Service Provider or Service Requester.
Note: Currently, the Service Requester option is available in the list only when the host runtime is
IMS Enterprise Suite SOAP Gateway.
c. The Development scenario field is already set to Map to an Existing Service Interface (meet-in-
middle) and is disabled.
d. The Conversion type field is already set to Compiled XML Conversion and is disabled.

5. Click Start.
6. If you selected only one mapping session file before starting the wizard launchpad, then the launchpad
now opens a window with a message stating that selecting a single mapping session file causes the
meet-in-middle wizard to create a unidirectional Web service (see Step 1):

The current selection of a single mapping file generates only

unidirectional conversion code. To generate bidirectional
conversion code, select both inbound and outbound mapping files.

The Map an Existing Service Interface (meet-in-middle) wizard opens.

Overview of wizard pages

This topic provides an overview of the pages in the Map an Existing Service Interface (meet-in-middle)
wizard.
For this wizard, the pages common to all runtimes and application modes are as follows:
• Generation of conversion code
• Generation options
• File, data set, or member selection
The pages peculiar to a particular runtime or application mode are:
• Web Services for CICS page
• IMS Enterprise Suite SOAP Gateway service provider page

Developing web services and SOA with Enterprise Service Tools 235
 • IMS Enterprise Suite SOAP Gateway service requester page
Table 36 on page 236 summarizes which pages and tabs are available for the five runtime environments:

Table 36. Generation of Conversion Code Wizard Page and Tab Overview
Runtime Environment
Wizard Page and Tabs: (See Note)
W I B T

Generation of conversion code:

X X X
- Mapping session files

Generation options:
- XML Converters X X X
- Advanced Options

Web Services for CICS

- Basic Options X
- Advanced Options

IMS Enterprise Suite SOAP Gateway service provider; or

IMS Enterprise Suite SOAP Gateway service requester: X
- IMS Correlator file

File, data set, or member selection:

- XML Converters X X X
- Properties (optional)

Note:
• W stands for Web Services for CICS
• I stands for IMS Enterprise Suite SOAP Gateway
• B stands for Batch, TSO, and z/OS UNIX System Services
• T stands for XML Transformation for CICS (Not available with the meet-in-middle development
scenario)

First page, entitled Generation of conversion code

The first page of the Map to an Existing Service Interface (meet-in-middle) wizard, titled Generation of
Conversion Code, allows you to verify that you have selected the correct mapping session files.
The fields on this page are as follows:
Request mapping file
Verify that this is the request mapping session file that you want to use. If you want to use some other
request mapping session file, click Cancel to close the wizard.

Response mapping file

Verify that this is the response mapping session file that you want to use. If you want to use some
other response mapping session file, click Cancel to close the wizard.

236 Developer for z/OS: Developing with Db2, CICS, and IMS
Generation options page
The second page of the Map to an Existing Service Interface (meet-in-middle) wizard, titled Generation
options, allows you to select capabilities that you want to be included in the source code for the request
XML converter or the response XML converter.
To set default values for some of the fields on this page, use the COBOL XML Converters page in the
Preferences window (see “Setting preferences for COBOL XML converters” on page 145).

XML Converters tab

The XML Converters tab allows you to specify identification attributes and character encodings.
This tab contains the following fields:
• In the Specify identification attributes group:
Converter program name prefix
Type the stem of the program name that is included in the IDENTIFICATION DIVISION of each
generated COBOL program. If you type ACCT, for example, the wizard identifies the input converter
program as ACCTI, the output converter program as ACCTO, and the driver as ACCTD.

Author name
Type the value to be included in the AUTHOR paragraph of each generated COBOL program.

Service program name

Type the name of the existing application that you want the Web service to invoke.

• In the Specify character encodings group:

Request code page
Select the code page for encoding the XML input message.
Note:
– In the Web Services for CICS runtime environment, when compiled conversion is selected, CICS
performs the conversion of the text between the code page used by the Web service client and
the code page used by the Web service.
– In the other runtime environments, when compiled conversion is used, the Web service client is
responsible for the conversion between its own code page and the code page used by the Web
service.

Host code page

Select the code page for the z/OS host system.

Response code page

Select the code page for encoding the XML output message. For One-way this is disabled.
Note:
– In the Web Services for CICS runtime environment, when compiled conversion is selected, CICS
performs the conversion of the text between the code page used by the Web service client and
the code page used by the Web service.
– In the other runtime environments, when compiled conversion is used, the Web service client is
responsible for the conversion between its own code page and the code page used by the Web
service.

Bidi Options
Use the Bidi options button to invoke the Bidi conversion options window.
Note that the Bidi options button is disabled for Host code page selections other than 420 Arabic or
424 Hebrew. It becomes enabled if you select Host code page 420 Arabic or 424 Hebrew.
Based on the selection of a bidirectional language specific code page for the host application (420
Arabic or 424 Hebrew), you can choose any combination of the allowed attributes that describes
what type of transformation will be performed on the text data to convert it from the Unicode-based
(1208 UTF-8 or 1200 UTF-16) XML data to the 420 Arabic or 424 Hebrew text (alphanumeric

Developing web services and SOA with Enterprise Service Tools 237
 and alphabetic) data items in COBOL or, inversely, from the COBOL text data items to XML data in
Unicode.
For a description of the bidirectional language options see “Bidirectional conversion options
window” on page 239.

Advanced Options tab

The Advanced Options tab allows you to specify request and response XML converter behavior and
compiler-related preferences.
This tab contains the following fields:
• In the Specify request XML converter behavior group:
Validate root element namespace name
Select this checkbox to enable validation of the target namespace of the root element in XML
documents. The target namespace of the root element can be found in the XML schema definition
that defines the root element.

Use VALUE literals to initialize omitted data items

Select this checkbox to enable initialization for data items in the request language structure that you
have excluded from the Web service input data structure (see “Initializing data items in the COBOL
application's input data structure” on page 325 ).
This option applies only to the bottom-up development scenario for generating a Web service, and
applies only if you specify Compiled XML Conversion.

Use VALUE literals to initialize empty data items

Select this checkbox to enable initialization for data items in the request language structure that
you have included in the Web service input data structure (see “Initializing data items in the COBOL
application's input data structure” on page 325 ).
This option applies only to the bottom-up scenario for generating a Web service, and applies only if
you specify Compiled XML Conversion.

• In the Specify response XML converter behavior group:

Language data
This option controls how the response runtime XML conversion program handles characters in the
response COBOL data that are illegal in the XML 1.0 specification:
– Select Filter characters illegal in XML 1.0 if you want the conversion program to scan both
non-numeric and numeric data in the language structure and convert any character that is illegal
in the XML 1.0 specification to an EBCDIC, ASCII, or UNICODE space (depending on the response
code page).
– Select Halt on characters illegal in XML 1.0 if you want the conversion program to scan both
non-numeric and numeric data in the language structure and cause an exception if characters
illegal in XML 1.0 are found.
– Select Do not check for illegal characters if you want the conversion program not to check for
characters that are illegal in the XML 1.0 specification.
For more information see “Options for handling illegal XML characters” on page 325.

• In the Specify compiler-related preferences group:

Optimization
Select whether the optimization option is enabled for the COBOL compiler. When the checkbox is
selected, the COBOL compiler will use optimization in generating runtime code from COBOL source
code.
If you are trying to debug a compile error in your COBOL source code, it is a good idea to clear this
checkbox and recompile. Without optimization turned on, it is easier to determine which part of the
COBOL source code is causing the error.

238 Developer for z/OS: Developing with Db2, CICS, and IMS
 Specify COBOL compiler version
Select the version of the COBOL compiler that you want to use. (Same as COBOL_COMPILER_LEVEL
in the batch processor – see COBOL_COMPILER_LEVEL).

Bidirectional conversion options window

The Bidirectional conversion options window opens when you select the Bidi options button on the XML
Converters tab of the Generation options page. The bidirectional conversion options are not available for
IMS Enterprise Suite SOAP Gateway projects.

Enable Bidi conversion

This checkbox controls whether the bidirectional language conversion is performed at run time. For
bidirectional language conversion to take place, this checkbox must be selected for the host data and
for at least one of the request and response message. If these conditions are not met, an error message
is displayed in the error message area of a wizard. If you select Enable Bidi conversion, all of the
conversion attributes listed in the window apply during the conversion process.
Text type
You can select the following bidirectional language text types:
• VISUAL
• LOGICAL
Text orientation
You can select the following text orientation attributes:
• LTR (Left-to-right)
• RTL (Right-to-left)
Symmetric swapping
You can turn Symmetric swapping on or off.
Numeric swapping
You can turn Numeric swapping on or off.
Related tasks

“Using the Wizard Launchpad” on page 199

“Setting preferences for COBOL XML converters” on page 145
Related references
“Bottom-up wizard - Compiled XML conversion” on page 200

“Map to an Existing Service Interface (meet-in-middle) wizard” on page 227

“Create New Service Implementation (top-down)
wizard” on page 222
“Setting Importer > COBOL preferences” on page 219
“Generation options page” on page 237
“Web Services for CICS page” on page 208
“XML Transformation for CICS page” on page 253
“File, data set, or member selection page” on page 244
“XML to COBOL mapping reference” on page 337

Web Services for CICS page

The Web Services for CICS page is included in the wizard pages when the selected host runtime in the
wizard launchpad is Web Services for CICS.
This page allows you to specify options for the WSBind file that the wizard generates when the selected
host runtime is Web Services for CICS.

Developing web services and SOA with Enterprise Service Tools 239
 Click Change WSBind Preferences at the bottom of the page to modify the Web Services Assistant
(WSBind) preferences (see “Setting preferences for the CICS Web Services Assistant (WSBind)” on page
150).

Basic Options tab

The Basic Options tab allows you to specify the following options for the WSBind file: target information,
application program properties, and service interface properties.
This tab contains the following fields:
• In the Specify targets for WSBind file group:
Note: Generate to: Is only applicable to single service Enterprise Service Tools projects.
Generate to:
Same project
Select this when the file container is on the local system (default).
Remote location
Select this when the file container is on a remote system. For additional information, see
“Generation of Enterprise Service Tools artifacts to remote systems” on page 333.
WSBind file container
Type or select a path for the folder in which you want the WSBind file to be created.

WSBind file name

Type the name for the WSBind file.

Log file name

Type the name for the CICS Web Services Assistant log file. The log file contains extensive
information regarding generation of the WSBind file.

Overwrite WSBind file

Select this checkbox if you want the wizard to overwrite an existing WSBind file of the same name.

• In the Specify application program properties group:

Program interface
Select the method by which you want the existing application to be invoked:
– Select COMMAREA to invoke the existing application with the LINK command with the
COMMAREA option.
– Select CHANNEL to invoke the existing application with the LINK command with the CHANNEL
option.
Container name
Type the container name. (This value is required when the CHANNEL item is selected in the
Program interface list.)

• In the Specify service interface properties group:

Local URI
Type the local URI that you want to use for the Web service.

• Change WSBind Preferences

This allows changes to the Web Services Assistant (WSBind) preferences (see “Setting preferences
for the CICS Web Services Assistant (WSBind)” on page 150).

Advanced Options tab

The Advanced Options tab allows you to set options for the Web Services Assistant utility of the IBM
CICS Transaction Server for z/OS V3.1 or V3.2.
The values that you set on this page override, for this particular instance of the wizard, the global values
set for these same options in the Web Services Assistant (WSBind) preferences window.

240 Developer for z/OS: Developing with Db2, CICS, and IMS
This tab contains the following fields:
• In the Specify Web Services Assistant group:
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
Valid characters: A-Z a-z 0-9 $ @ #
In a service provider, this parameter 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 parameter is used to define the USERID attribute of
the URIMAP resource when it is created automatically using the PIPELINE scan command.
Transaction
Valid characters: A-Z a-z 0-9 $
In a service provider, this parameter 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
parameter is used to define the TRANSACTION attribute of the URIMAP resource when it is created
automatically using the PIPELINE scan command.
Vendor converter name
Set the name of the converter program to use when building a vendor style WSBind file. The vendor
style of WSBind file opts out of the CICS supplied XML transformation process, instead CICS links
to a converter program which is responsible for handling the XML to commarea conversion. This
method is used to set the name of the converter program. In the wizard, this value defaults to the
name of the Converter Driver file.
• Change WSBind Preferences
This allows changes to the Web Services Assistant (WSBind) preferences (see “Setting preferences
for the CICS Web Services Assistant (WSBind)” on page 150).

IMS Enterprise Suite SOAP Gateway service provider

The IMS SOAP Gateway Service Provider page is included in the wizard pages when the selected host
runtime is IMS Enterprise Suite SOAP Gateway and the selected application mode is Service Provider
in the wizard launch pad.
This page allows you to specify options for the IMS Correlator file.

IMS Correlator file

The IMS Correlator file tab allows you to specify the service identification properties and the IMS system
interaction properties for the new Web service.
This tab contains the following fields:
• In the Specify service identification properties group:
Note: Generate to: Is only applicable to single service Enterprise Service Tools projects.
Generate to:
Same project
Select this when the file container is on the local system (default).
Remote location
Select this when the file container is on a remote system. For additional information, see
“Generation of Enterprise Service Tools artifacts to remote systems” on page 333.

Developing web services and SOA with Enterprise Service Tools 241
 SOAPAction
Type the value that you want to use for the SOAPAction attribute of the soap:operation element
in the WSDL file that the wizard generates for the Web service.
This value also becomes the name of the correlator file that the wizard generates - see the File
name field.
This value must begin with urn: and must contain only characters that are valid in file names.

File container
Type or the select the path of the folder in which you want the wizard to generate the IMS correlator
file.

File name
This field displays the name of the IMS correlator file that the wizard is to generate. You can modify
this field by changing the name in the SOAPAction field.

Update, Overwrite
These radio buttons are enabled to update or overwrite the IMS correlator file that you specified in
the File container and File name fields:
– Select Update if you want the wizard to do the following:
1. Preserve all the existing entries in the IMS correlator file; and
2. Add or update information for the current Web service and operation on the WSDL and XSD
tab of the Generation Options page of the wizard.
– Select Overwrite if you want the wizard to overwrite the existing IMS correlator file.
Entries in the IMS correlator file are identified by a combination of the Web service name and the
operation name. If you specify a Web service name and an operation name that already exist in the
IMS correlator file, then the wizard initializes the request and response schema properties on this
page with the values from the IMS correlator file.

• In the Specify IMS Enterprise Suite SOAP Gateway and IMS Connect interaction properties group:
Transaction code
Type the name of the IMS transaction that is to be invoked by the Web service.
This name must be alphanumeric and must contain 8 characters or less.

Inbound connection bundle

Type the name of the connection bundle that the Web service uses to connect to IMS Enterprise
Suite SOAP Gateway.
Connection bundles are defined in the connection specification XML file maintained by the IMS
Enterprise Suite SOAP Gateway and can be updated using the IMS Enterprise Suite SOAP Gateway
deployment tool
This name must be alphanumeric.

Socket timeout
Type the number of milliseconds that the IMS Enterprise Suite SOAP Gateway should wait for a
response from IMS Connect.

Execution timeout
Type the number of milliseconds that IMS Connect should wait for a response from the IMS
Enterprise Suite SOAP Gateway.
The maximum valid value is 3600000.

LTERM name
Type the LTERM name that is to be used to override the value in the LTERM field of the IMS
application program's I/O PCB.

242 Developer for z/OS: Developing with Db2, CICS, and IMS
 You can set the value of this property if the client application wants to provide an LTERM override
name. This name is in the IMS application program's I/O PCB, with the intent that the IMS
application makes logic decisions based on the override value.
This name must be alphanumeric and must contain 8 characters or less.

Inbound WS-Security
Select the security token type that IMS Enterprise Suite SOAP Gateway will expect from users.

IMS Enterprise Suite SOAP Gateway service requester

The IMS Enterprise Suite SOAP Gateway Service Requester page is included in the wizard pages when
the selected host runtime is IMS Enterprise Suite SOAP Gateway and the selected application mode is
Service Requester in the wizard launch pad.
This page allows you to specify options for the IMS Correlator file.

IMS Correlator file

The IMS Correlator file tab allows you to specify the service identification properties and the IMS system
interaction properties for the new Web service.
This tab contains the following fields:
• In the Specify service identification properties group:
WSID
This field displays the Web service identifer that is used at run time to identify the Web service. This
Web service identifier must be unique among all Web services deployed to the same IMS Enterprise
Suite SOAP Gateway.
This identifier is fixed to be the name of the mapped WSDL file minus the extension.
Note: Because of this naming convention, and because this identifer must be unique among all Web
services deployed to the same IMS Enterprise Suite SOAP Gateway (see the preceding paragraph),
therefore no two Web services deployed to the IMS Enterprise Suite SOAP Gateway can have
identically named WSDL files.
The IMS Enterprise Suite SOAP Gateway uses this identifier to locate the service that an IMS
application wants to invoke. The outbound XML Converter transmits the WSID to the IMS Enterprise
Suite SOAP Gateway on behalf of the IMS application.

File container
Type or the select the path of the folder in which you want the wizard to generate the IMS correlator
file.

File name
This field displays the name of the IMS correlator file that the wizard is to generate. You can modify
this field by changing the name in the SOAPAction field described previously.

Update, Overwrite
These radio buttons are enabled if the IMS correlator file that you specified in the File container
and File name fields (described previously) already exists:
– Select Update if you want the wizard to do the following:
1. Preserve all the existing entries in the IMS correlator file; and
2. Add or update information for the current Web service and operation on the WSDL and XSD
tab of the Generation Options page of the wizard.
– Select Overwrite if you want the wizard to overwrite the existing IMS correlator file.
Entries in the IMS correlator file are identified by a combination of the Web service name and the
operation name. If you specify a Web service name and an operation name that already exist in the
IMS correlator file, then the wizard initializes the request and response schema properties on this
page with the values from the IMS correlator file.

• In the Specify IMS system interaction properties group:

Developing web services and SOA with Enterprise Service Tools 243
 Transaction code
Type the name of the IMS transaction that handles the response that the Web service receives.
This name must be alphanumeric and must contain 8 characters or less.

Inbound connection bundle

Type the name of the connection bundle that you want the Web service to use in the IMS Enterprise
Suite SOAP Gateway.
This name must be alphanumeric.

Inbound TPIPE name

Type the Tpipe name used with CM0 transactions in IMS.

LTERM name
Type the LTERM name that is to be used to override the value in the LTERM field of the IMS
application program's I/O PCB.
This name must be alphanumeric and must contain 8 characters or less.
Socket timeout
Type the number of milliseconds that the IMS Enterprise Suite SOAP Gateway should wait for a
response from IMS Connect.

Execution timeout
Type the number of milliseconds that IMS Connect should wait for a response from the IMS
Enterprise Suite SOAP Gateway.
The maximum valid value is 3600000.

Callout message type

Select ASYNC Asynchronous or SYNC Synchronous processing. For more information about the
callout message type, see “Support for the IMS Callout (ICAL) call ” on page 279.
Send-only with ACK support
Enable or disable the send-only acknowledgement protocol. If enabled, SOAP Gateway sends the
callout response message to IMS using the send-only with acknowledgement protocol. This option
is available for the synchronous callout message type only.
Callout connection bundles
The name of the connection bundle for IMS Enterprise Suite SOAP Gateway outbound
communication.

Web service timeout

Type the number of milliseconds that the IMS Enterprise Suite SOAP Gateway should wait for a
response from the Web service to which the request is sent.
The maximum valid value is 21474483646.

Callout WS-Security
Select the security token type that IMS Enterprise Suite SOAP Gateway will expect from users.

File, data set, or member selection page

The File, data set, or member selection page allows you to specify a folder and file names of the XML
converters and the converter driver that the wizard creates.

XML Converters tab

The XML Converters tab allows you to specify a path and file names for the new XML converters and the
new converter driver.
This tab contains the following fields:
• In the Select targets for the XML Converters and Converter Driver group:
Generate to
Same project: Select this when the file container is on the local system (default).

244 Developer for z/OS: Developing with Db2, CICS, and IMS
 Remote location: Select this when the file container is on a remote system. For additional
information, see “Generation of Enterprise Service Tools artifacts to remote systems” on page
333.
Note: Generate to: Is only applicable to single service Enterprise Service Tools projects.
Converter file container
Type or select the path of a folder in which you want the wizard to create the converter files.
Converter driver file name
Type the name of the file that you want to contain the new converter driver. (The converter driver is
the procedure that calls the request converter and the response converter.)
To suppress the generation of this file:
1. Clear the checkbox Generate all to driver, if it is set.
2. Clear the checkbox at the far left of the input field.
Request Converter file name
Type the name of the file that you want to contain the new request converter. (The request converter
is the the procedure that maps a high-level-language data structure to the request XML schema
definition.)
To suppress the generation of this file:
1. Clear the checkbox Generate all to driver, if it is set.
2. Clear the checkbox at the far left of the input field.
Response Converter file name
Type the name of the file that you want to contain the new response converter. (The response
converter is the procedure that maps the response XML schema definition to a high-level-language
data structure.)
To suppress the generation of this file:
1. Clear the checkbox Generate all to driver, if it is set.
2. Clear the checkbox at the far left of the input field.
Generate all to driver
Select this checkbox to if you want the converter driver, the request converter, and the response
converter to be contained in one file.
Important: Prior to the availability of the "Generate Conversion Code" enhancement, where
combined converters can be generated from two mapping files, it was necessary to manually
combine two separate sets of converter programs for Web services having both request and
response messages.
Overwrite files without warning
This checkbox indicates that the wizard overwrites without warning, if files with the same name
exist in the target directory.
• In the Enterprise COBOL for z/OS Compiler Options group:
Specify COBOL compiler version
Select the version of the COBOL compiler that you want to use. (Same as COBOL_COMPILER_LEVEL
in the batch processor – see COBOL_COMPILER_LEVEL).
XML Parsing
COMPAT - XML parser Enterprise Service Tools COBOL Version 3
XMLSS - XML parser Enterprise Service Tools COBOL Version 4
Note: This parser is also available in the z/OS XML System Services platform libraries.

Developing web services and SOA with Enterprise Service Tools 245
 Optimization
Select whether the optimization option is enabled for the COBOL compiler. When the checkbox is
selected, the COBOL compiler uses optimization in generating runtime code from COBOL source
code.
If you are trying to debug a compile error in your COBOL source code, it is a good idea to clear this
checkbox and recompile. Without optimization turned on, it is easier to determine which part of the
COBOL source code is causing the error.

Properties tab
The Properties tab allows you to specify a path and file names for the new generation properties files.
This tab is present if you started the Enterprise Service Tools Wizard Launchpad from a type of project
other than a single-service project, and if you selected the checkbox Save generation properties on the
launchpad (see “Using the Wizard Launchpad” on page 199).
This tab contains the following fields:
• In the group Select targets for the generation properties files:
Properties file container:
Type or select the path of a folder in which you want the wizard to create the generation properties
files.
Container.xml
Type the name that you want to use for the Container.xml file.

PlatformProperties.xml
Type the name that you want to use for the PlatformProperties.xml file.

ServiceSpecification.xml
Type the name that you want to use for the ServiceSpecification.xml file.

Using the mapping editor to create data mappings in a mapping session file
The mapping editor allows you to indicate how you want data mapped from a source to a target in a
mapping session file (request or response).
In the Service Requester case:
• In an request mapping session file, the mapping is from a high-level-language data structure to an XML
schema definition.
• In an response mapping session file, the mapping is from the mapping is from an XML schema definition
to a high-level-language data structure.
Important: You should be aware of possible error situations (see “Error situations that you may
encounter in the mapping editor” on page 247).
To specify mappings in a mapping session file:
1. Right-click the mapping session file that you want to edit.
2. Select Open With > Mapping Editor. The mapping editor opens.
3. In the mapping editor:
a. Enlarge the editor area until you can see both the source data (on the left) and the target data (on
the right).
b. For each mapping that you want to create, drag an element in the source data to an element in
the target data. The editor displays a connecting line between the source element and the target
element to indicate that a mapping exists.
Note: The drag operation fails if the source and target elements are incompatible.
Note: Alternatively, you can create a mapping as follows:

246 Developer for z/OS: Developing with Db2, CICS, and IMS
 i) Select the source element.
ii) Press the Ctrl key, and while holding down the Ctrl key select the target element.
iii) Click the icon Create a New Transform. Or, right-click the target element and select Create
Transform.
c. When you are finished creating mappings, close the mapping editor.
The mapping session file now contains the mappings that you created.

Error situations that you may encounter in the mapping editor

This topic describes possible error situations that you may encounter in the mapping editor, and how to
resolve these errors.
This topic contains the following subtopics:
• “Source or target file not present” on page 247
• “Source or target XML schema definition or high-level-language data structure has changed” on page
247

Source or target file not present

A mapping session file (request or response) contains references to the source file and the target file that
you specified in the Create Mappings wizard when you created the mapping session file.
The mapping editor uses these references to read information from the source and target files.
If either of these files has been moved to another directory, or renamed, or deleted, so that the mapping
editor cannot locate the file, then the mapping editor displays an error message.
To resolve this problem, restore the source file or the target file to its original location.
Note: The references in the mapping session file contain the relative paths of the source file and the
target file, relative to the mapping session file. If you move the source file, the target file, and the mapping
session file to another location, but their relative locations in the directory structure are the same, then
the mapping editor can find the source and target files and does not display an error message.

Source or target XML schema definition or high-level-language data structure has

changed
A mapping session file (request or response) contains references to the source and target XML schema
definition or high-level-language data structure that you specified in the Create Mappings wizard when
you created the mapping session file.
The mapping editor uses these references when you create a mapping between a source and a target.
If the source or target XML schema definition or high-level-language data structure has changed, then the
mapping editor displays an error message.
To resolve this problem, use the New XML to COBOL or PL/I Mapping Session wizard recreate the
mapping session file from the source file and the target file, using the file containing the new XML schema
definition or high-level-language data structure.

Create New XML Transformation (bottom-up) wizard

Use the Create New XML Transformation (bottom-up) wizards to generate artifacts for implementing an
XML Transformation for CICS runtime environment.

Bottom-up wizard - Compiled XML conversion

Use the Create New XML Transformation (bottom-up) wizard wizard with Compiled XML conversion to
generate artifacts for implementing an XML Transformation for CICS runtime environment.

Developing web services and SOA with Enterprise Service Tools 247
 Overview of bottom-up (compiled) wizard pages
This topic provides an overview of the pages in the wizards with compiled XML conversion.
For this wizard and conversion type, the pages common to all runtimes are as follows:
• Language Structures page
• Generation options page
• File, data set, or member selection page
The pages peculiar to a particular runtime or application mode are:
• Web Services for CICS page
• IMS Enterprise Suite SOAP Gateway Web Service Provider page
• XML Transformation for CICS page
Table 37 on page 248 summarizes which pages and tabs are available for the supported runtime
environments:

Table 37. Bottom-Up Compiled Wizard Page and Tab Overview

Runtime Environment
Wizard Page and Tabs: (See Note)
W I B T
Language structures page:
• Request Language Structure X X X X
• Response Language Structure

Generation options page:

• XML Converters
• WSDL and XSD (not XML Transformation) X X X X X
• XML Schemas (only XML Transformation)
• Advanced Options

Web Services for CICS page:

• Basic Options X
• Advanced Options

IMS Enterprise Suite SOAP Gateway Web Service Provider page:

X
• IMS Correlator file

File, data set, or member selection page:

• XML Converters
X X X X X
• WSDL and XSD
• Properties (Display only)

CICS Deployment Options page:

X
• Specify deployment manifest properties

Language structures page:

X
• Language Structure

248 Developer for z/OS: Developing with Db2, CICS, and IMS
Table 37. Bottom-Up Compiled Wizard Page and Tab Overview (continued)
Runtime Environment
Wizard Page and Tabs: (See Note)
W I B T
XML Transformation for CICS page:
• Basic Options X
• Advanced Options

CICS Deployment Options page:

X
• Start Bundle Deployment wizard upon finish

Note:
• W stands for Web Services for CICS
• I stands for IMS Enterprise Suite SOAP Gateway
• B stands for Batch, TSO, and z/OS UNIX System Services
• T stands for XML Transformation for CICS

Language structures page

The Language structures page for compiled conversion lists all the high-level language structures in the
source file that was used to start the wizard. Before starting the wizard, when using a selected source file,
ensure that the source file contains the language structure for your application.

Follow these steps to complete this page:

1. In the Language Structure tab, select the language structure for which you want to generate XML
schema and the the transformation code.
2. Click Change PL/I Preferences or Change COBOL Preferences button to open the desired
preferences page. These preferences control how source files (PL/I or COBOL) are imported (see
“Setting Importer > PL/I preferences” on page 220 or “Setting Importer > COBOL preferences” on
page 219).
Note: The Language structure tree views on this page can show certain data types that are not supported
by the compiled conversion. These types include the ones described in the topics “Compatibility:
Simple data types” on page 339. These specific types are marked as (contains unsupported types)
or unsupported type in the tree; these selections are automatically disabled.
However, there are other types that are not supported by the compiled conversion and they are described
in the CICS TS 4.1 Documentation, refer to, XML schema to COBOL mapping or CICS® Transaction Server
for z/OS, Version 4 Release 1 IBM Documentation. These types are not marked as (contains unsupported
types) or unsupported type in the tree and the selection is not automatically disabled. If you leave these
data items selected, the generation fails and an appropriate error message is shown. An error entry is also
put into the Remote error list view.

Generation options page

The Generation options page allows you to select capabilities that you want to be included in the source
code for the XML converter.

XML Converters tab

The XML Converters tab allows you to specify identification attributes and character encodings.
This tab contains the following fields:

Developing web services and SOA with Enterprise Service Tools 249
 • In the Specify identification attributes group:
Converter program name prefix:
Type the stem of the program name that is included in the IDENTIFICATION DIVISION of each
generated COBOL program. If you type ACCT, for example, the wizard identifies the input converter
program as ACCTI, the output converter program as ACCTO, and the driver as ACCTD.
Author name:
Type the value to be included in the AUTHOR paragraph of each generated COBOL program.
• In the Specify Enterprise COBOL for z/OS properties group:
Compiler Level:
Type the value of a specific level of the Enterprise COBOL compiler.
XMLPARSE option:
Type the value of the XML parser selected for the COBOL XML PARSE statement.
This option is valid only if Compiler Level is set to 4.1 or higher.
Optimization
Select whether the optimization option is enabled for the COBOL compiler. When the checkbox is
selected, the COBOL compiler uses optimization in generating runtime code from COBOL source
code.
If you are trying to debug a compile error in your COBOL source code, it is a good idea to clear this
checkbox and recompile. Without optimization turned on, it is easier to determine which part of the
COBOL source code is causing the error.
• In the Specify character encodings group:
XML code page:
Select the code page for encoding the XML data. This setting is used by the generated converter
program depending on whether your application expects to process or produce XML.
Host code page:
Select the code page for the z/OS host system. This code page is used in the generated converter
program to encode the language character data.

XML Schemas tab

The XML Schemas tab allows you to specify XML schema properties.
This tab contains the following fields:
• In the Specify XML Schema properties group:
Target namespace:
Type the namespace and schema name of the XML schema that you want to use as the request XML
schema. For example,

http://www.StartAppI.com/schemas/StartAppIInterface

Root element name:

Type the name of the global element that you want to use in the request XML schema. For example,

ProgramPassFields

Note: By default, the source program name and a character designator I for request (formally
Inbound) is used. You can override the default by editing the text in the field.
Whitespace option:
Specifies the conversion treatment for all elements in the generated schema. Select on of the
following values:
– compact - trim leading and trailing spaces - substitute a single space for each contiguous
sequence of spaces.

250 Developer for z/OS: Developing with Db2, CICS, and IMS
 – collapse - (1) replace tab, line feed, and carriage return characters with spaces, (2) trim leading
and trailing spaces, and (3) substitute a single space for each contiguous sequence of spaces.
– replace - replace tab, line feed, and carriage return characters with spaces.
– preserve - no whitespace removal nor replacement is performed.

Advanced Options tab

The Advanced Options tab allows you to specify XML schema definition properties (this tab is exclusively
for XML Transformation)
This tab contains the following fields:
• In the Specify XML Schema generation options group:
Generate minimum hierarchy in XML Schemas
This checkbox controls the message format of the generated XML schema and consequently the
parsing and generation of XML in the XML converters. XML converters based on XML schemas having
minimized hierarchies tend to have better performance.
– Select this checkbox if you want the XML converters to be generated so as to use a reduced XML
structure hierarchy, when a more detailed structure hierarchy is not needed to uniquely identify
each element in the structure.
When there are elements with the same tag name, the name of the element that occurs later in
the document is prefixed with as many of its parent tags as are required produce a unique name.
This method increases the efficiency of message processing clients and reduces the number and
complexity of objects that need to be instantiated.
– Clear this checkbox if you want the wizard to generate an XML schema that represents the full
hierarchy of the language structure.

Generate groups in XML Schemas

This checkbox controls whether the XML converter includes groups in the generated XML schemas:
– Select this checkbox if you want the XML converter to include groups in the generated XML
schemas.
– Clear this checkbox if you want the XML converter to include group "contents" inline instead
of using group references. This option is useful for applications that do not support the use of
groups and group references in XML schemas.

Generate short complex type names

The normal method for generating a complex type name is to concatenate the name of the group to
the names of all the parents of the group, with an underscore character "_" after each name except
the last.
However, if this checkbox is selected, then a complex type name is generated by taking just the
name of the group.
For example, in this COBOL group:

01 ServiceRequest.
02 CommonHeader.
05 HeaderType1.
10 Element1 PIC X(10).

the complex XML type name for the HeaderType1 element is:
– servicerequest_commonheader_headertype1 if the checkbox is not selected.
– HeaderType1 if the checkbox is selected.
The shortening of complex type names allows for the generation of more compact client code
(usually, Java class code) from the WSDL and XSD files containing the complex XML types.
The setting of this checkbox has no effect on top-down or meet-in-middle scenarios.

Developing web services and SOA with Enterprise Service Tools 251
 When shortening of a complex type name is attempted, a collision is possible if the short name of
the type already exists as the result of a previously defined type for a group with an identical name
but different parent group names. For example, in the following COBOL structure:

01 ServiceRequest.
02 CommonHeader.
05 HeaderType.
10 Element PIC X(10).
02 SpecificHeader.
05 HeaderType.
10 Element PIC X(10).

the type name of the HeaderType group under SpecificHeader collides with the type name of
the HeaderType group under CommonHeader.
In case of a collision, all colliding names keep the original long type names. Thus, in this example,
the resulting type names are:
– servicerequest_commonheader_headertype and
– servicerequest_specificheader_headertype.
The short name for a complex type is formed by taking the name of the XML element that has that
type, plus some possible modifications. The rules for forming short names are:
1. Take the name of the XML element that has the type (such as HeaderType1).
2. If the name starts with a character that is an invalid character for Java names (for example, a
digit), it is prefixed with a double underscore "__".
3. If a hyphen "-" is present in the original COBOL group name it is replaced with a single
underscore "_".
4. The case of the group name is preserved.
For example, the following group:

03 2-In--B.
04 var2 blank zero pic 999.99.

results in the shortened complex type name __2_In__B.

Generate comments in XSD
Select this checkbox to cause the comments from the COBOL source code file to be generated as
annotation documentation in the generated XSD and WSDL files (see “Including COBOL source code
comments in generated XSD and WSDL files” on page 327)
This option applies only to the bottom-up development scenario for generating a Web service, and
applies only if you specify Compiled XML Conversion.

Generate qualified elements in XML Schemas

Select this checkbox to determine the value of the elementFormQualified attribute in XML Schemas
generated by the tool.
Note: This option only affects the "Compiled XML Conversion" conversion type.
• In the Specify XML language structure converter behavior group:
Validate the target namespace name of the root XML element
Select this checkbox to enable validation of the target namespace of the root element in XML
documents. The target namespace of the root element can be found in the XML schema which
defines it.
Initialize language structure members before XML conversion
Select the option to initialize all numeric and non-numeric data items to zeros and spaces
respectively before XML is converted into the language structure.

252 Developer for z/OS: Developing with Db2, CICS, and IMS
 Use VALUE literals to initialize omitted data items
Select this checkbox to enable initialization for data items in the language structure that you have
excluded from the XML transformation input data structure (see “Initializing data items in the
COBOL application's input data structure” on page 325 ).
This option applies only to the bottom-up development scenario for generating an XML
transformation, and applies only if you specify Compiled XML Conversion.

Use VALUE literals to initialize empty data items

Select this checkbox to enable initialization for data items in the language structure that you have
included in the XML transformation input data structure (see “Initializing data items in the COBOL
application's input data structure” on page 325 ).
This option applies only to the bottom-up scenario for generating an XML transformation, and
applies only if you specify Compiled XML Conversion.

• In the Specify language structure to XML converter behavior group:

Language data:
This option controls how the runtime XML conversion program handles characters in the COBOL
data that are illegal in the XML 1.0 specification:
– Select Filter characters illegal in XML 1.0 if you want the conversion program to scan both
non-numeric and numeric data in the language structure and convert any character that is illegal
in the XML 1.0 specification to an EBCDIC, ASCII, or UNICODE space (depending on the code
page).
– Select Halt on characters illegal in XML 1.0 if you want the conversion program to scan both
non-numeric and numeric data in the language structure and cause an exception if characters
illegal in XML 1.0 are found.
– Select Do not check for illegal characters if you want the conversion program not to check for
characters that are illegal in the XML 1.0 specification.
For more information see “Options for handling illegal XML characters” on page 325.

XML Transformation for CICS page

The XML Transformation for CICS page is included in the wizard pages when the selected host runtime in
the wizard launchpad is XML Transformation.
This page allows you to specify options for the XSDBind file that the wizard generates when the host
runtime is set to XML Transformation.
Click Change XSDBind Preferences at the bottom of the page to modify the XML Transformation
Assistant (XSDBind) preferences (see “Setting preferences for the CICS XML Transformation Assistant
(XSDBind)” on page 167).

Basic Options tab

The Basic Options tab allows you to specify the target information for the XSDBind file.
This tab contains the following fields:
• In the Specify targets for XSDBind file group:
XSDBind file container
This field shows the folder where the XSDBind file is generated

XSDBind file name

Type the name of the XSDBind file.

Log file name:

Type the name of the CICS XML Transformation Assistant log file. The log file contains extensive
information regarding generation of the XSDBind file.

Overwrite XSDBind file

Select this checkbox if you want the wizard to overwrite an existing XSDBind file of the same name.

Developing web services and SOA with Enterprise Service Tools 253
 Advanced Options tab
The Advanced Options tab allows you to set options for the XML Transformation Assistant utility of the
IBM CICS Transaction Server for V 4.1.
The values that you set on this page override, for this particular instance of the wizard, the global values
set for these same options in the XML Transformation Assistant (XSDBind) preferences window.
This tab contains the following fields:
• In the Specify XML Assistant options group:
CCSID:
Specifies the CCSID that is used at run time to encode data between the application program
and the XML transformation 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).
Vendor converter name:
Set the name of the converter program to use when building a vendor style XSDBind file. The vendor
style of XSDBind file opts out of the CICS supplied XML transformation process, instead CICS links
to a converter program which is responsible for handling the XML to commarea conversion. This
method is used to set the name of the converter program. If left blank, this value defaults to the
name of the Converter Driver file.
Note: It is recommended that this field be left blank to let the wizard generate the correctly
coordinated artifact names."

File, data set, or member selection page

The File, data set, or member selection page allows you to specify a path and file names for the
following items: (a) the new XML converters and converter driver; (b) the new XSD files; and (c) the
generation properties files.

XML Converters tab

The XML Converters tab allows you to specify a path and file names for the new XML converters and the
new converter driver.
This tab contains the following fields:
• In the Select targets for the XML conversion programs group:
Generate to:
Same project
Select this when the file container is on the local system (default).
Remote location
Select this when the file container is on a remote system. For additional information, see
“Generation of Enterprise Service Tools artifacts to remote systems” on page 333.
Converter file container:
Select or select the path of a folder in which you want the wizard to create the converter files.

Converter driver file name:

Type the name of the file that you want to contain the new converter driver.

XML Converter file name:

Type the name of the file that you want to contain the XML converter.

Data Converter file name:

Select the name of the file that you want to contain the data converter.
To suppress the generation of this file:

254 Developer for z/OS: Developing with Db2, CICS, and IMS
 1. Clear the checkbox Generate all to driver, if it is set.
2. Clear the checkbox at the far left of the input field.

Overwrite files without warning

This checkbox indicates that the wizard overwrites without warning, if files with the same name
exist in the target directory.

XML Schemas tab

The XML Schemas tab tab allows you to specify a path and file names for the XSD file.
This tab contains the following fields:
• In the group Select target for XML Schema:
Interface File container:
Type or select the path of a folder in which you want the wizard to create the interface file.

XSD file name:

Type the name of the XSD file.

• Overwrite files
This checkbox indicates that the wizard overwrites without warning, if files with the same name
exist in the target directory.

Properties tab
The Properties tab displays the path and file names for the new generation properties files.
This tab contains the following fields:
Note: The fields in this tab cannot be changed using this wizard.
• In the group Select targets for the generation properties files:
Properties file container:
Displays the path of a folder that is used to create the generation properties files.

Container.xml
Displays the name that is used for the Container.xml file.

PlatformProperties.xml
Displays the name that is used for the PlatformProperties.xml file.

ServiceSpecification.xml
Displays the name that is used for the ServiceSpecification.xml file.

Overwrite files
This checkbox indicates that the wizard overwrites without warning, if files with the same name
exist in the target directory.

Bottom-up wizard - Interpretive XML conversion

Use the Create New XML Transformation (bottom-up) wizard with Interpretive XML conversion to
generate artifacts for implementing an XML Transformation for CICS runtime environment.

Click Change XSDBind Preferences button to open the preferences page. These preferences control how
XSDBind files are generated (see “Preferences on the DFHLS2SC tab” on page 170).
Related information
Opening the Preferences window

Developing web services and SOA with Enterprise Service Tools 255
 Overview of bottom-up (interpretive) wizard pages
This topic provides an overview of the pages in the wizards with interpretive XML conversion.
For this wizard and conversion type, Web Services for CICS and XML Transformation for CICS are the only
runtimes supported.
Table 38 on page 256 summarizes the pages and tabs for this wizard:

Table 38. Bottom-Up Interpretive Wizard Page and Tab Overview

Runtime Environment (See
Wizard Page and Tabs: Note)
W I B T M

Language structures page:

- Request Language Structure X X
- Response Language Structure

DFHLS2WS Application and Service properties page:

- Application Properties X X
- Service Properties

DFHLS2WS Target artifacts page:

- Service Artifacts X X
- Properties (Optional)

CICS Deployment Options page:

X X
- Specify deployment manifest properties

Language structures page:

X
- Language Structure

DFHLS2SC XML Schema (XSD) Properties page:

X
- XSD Properties

DFHLS2SC Target artifacts page:

- Conversion Artifacts X
- Properties

CICS Deployment Options page:

X
- Start Bundle deployment wizard upon finish

Note:
• W stands for Web Services for CICS
• I stands for IMS SOAP Gateway
• B stands for Batch, TSO, and z/OS UNIX System Services
• T stands for XML Transformation for CICS
• M stands for MTOM/XOP (Message Transformation Optimization Mechanism)/(XML-binary
Optimization Package) service

256 Developer for z/OS: Developing with Db2, CICS, and IMS
Language structures page
The Language structures page for interpretive conversion lists all the high-level language structures in
the source file that was used to start the wizard. Before starting the wizard, when using a selected source
file, ensure that the source file contains the language structure for your application.

Follow these steps to complete this page:

1. In the Language Structure tab, select the language structure for which you want to generate XML
schema and the transformation code.
2. Click Change COBOL Preferences or Change PL/I Preferences button to open the desired
preferences page. These preferences control how source files (COBOL or PL/I) are imported (see
“Setting Importer > PL/I preferences” on page 220 or “Setting Importer > COBOL preferences” on
page 219).
Note: The Language structure tree views on this page can show certain data types that are not supported
by the compiled conversion. These types include the ones described in the topics “Compatibility:
Simple data types” on page 339. These specific types are marked as (contains unsupported types)
or unsupported type in the tree; these selections are automatically disabled.
However, there are other types that are not supported by the compiled conversion and they are described
in the CICS TS 4.1 Documentation, refer to CICS® Transaction Server for z/OS, Version 4 Release 1 IBM
Documentation. These types are not marked as (contains unsupported types) or unsupported type
in the tree and the selection is not automatically disabled. If you leave these data items selected, the
generation fails and an appropriate error message is shown. An error entry is also put into the Remote
error list view.
Related concepts

“Introduction to mapping concepts” on page 281

Related tasks

“Create New XML Transformation (bottom-up)

wizard” on page 247
“Create New XML Transformation (top-down) wizard” on page 258
“The DFHSC2LS Application and Transformation properties page” on page 260

The DFHLS2SC XML Schema (XSD) Properties page

The DFHLS2SC XML Schema (XSD) Properties page sets properties for generating the XML Schema
(XSD) file
Perform the following to complete this page:
In the XSD Properties tab, specify the following options:
Global element name:
Specifies the global element name for the schema.
XSD namespace:
Specifies the XSD namespace.

The DFHLS2SC Target artifacts page

The DFHLS2SC Target artifacts page sets targets for the XSDBind and XSD files

Conversion Artifacts tab

The DFHLS2SC Conversion Artifacts tab sets targets for the XSDBind and language structures fields and
allows you to specify a path and file names for the new generation properties files
Follow these steps to complete this tab:
File container:
This field shows the folder to where the generated artifacts are written.

Developing web services and SOA with Enterprise Service Tools 257
 XSD file:
Specifies the name of the XML schema file

XSDBind file name:

Specifies the name for the XSDBind file.

Log file name:

Specifies the name for the log file.

Overwrite XSDBind file

This checkbox indicates that the wizard overwrites without warning, if files with the same name exist
in the target directory.

Properties tab
The DFHLS2SC Properties tab displays the path and file names for the new generation properties files.
This tab contains the following fields:
Note: The fields in this tab cannot be changed using this wizard.
Properties file container:
Displays the path of a folder that is used to create the generation properties files.
Container.xml
Displays the name that is used for the Container.xml file.

PlatformProperties.xml
Displays the name that is used for the PlatformProperties.xml file.

ServiceSpecification.xml
Displays the name that is used for the ServiceSpecification.xml file.

Overwrite files
This checkbox indicates that the wizard overwrites without warning, if files with the same name exist
in the target directory.

CICS deployment options

This page provides the ability to start the Deploy the CICS Bundle wizard.

Select the Start Bundle deployment wizard upon finish and click Finish
This causes the Deploy the CICS Bundle wizard to open upon exiting from the generation wizard. The
location of the XSDBind and other relevant information is passed to the Deploy the CICS Bundle wizard.
The XSDBind file is copied from the location specified in the generation wizard to the location indicated in
the Deploy the CICS Bundle wizard.

Create New XML Transformation (top-down) wizard

Use the Create New XML Transformation (top-down) wizard to generate files for implementing an XML
Transformation for CICS runtime environment.

The top-down development scenario is available only when the host runtime is CICS and only with
interpretive XML conversion.
This wizard provides functionality similar to that of the DFHSC2LS utility in the CICS XML Transformation
Assistant.

258 Developer for z/OS: Developing with Db2, CICS, and IMS
Overview of top-down wizard pages
This topic provides an overview of the pages in the wizards.
This wizard is available only when the selected host runtime in the launchpad is Web Services for CICS
or XML Transformation for CICS.
The wizard has the same pages and tabs whether the selected application mode in the launch pad is
Service Provider or Service Requester.
Table 39 on page 259 summarizes the pages and tabs for this wizard:

Table 39. Top-Down Wizard Page and Tab Overview

Runtime Environment
Wizard Page and Tabs: (See Note)
W I B T

DFHWS2LS Application and

Service properties page:
X
- Application Properties
- Service Properties

DFHWS2LS Target artifacts page:

- Structures
- WSBind X
- Template
- Properties (Optional)

CICS Deployment Options page:

X
- Specify deployment manifest properties

The DFHSC2LS Application and

Transformation properties page:
X
- Application Properties
- Transformation Properties

The DFHSC2LS Target artifacts page:

- Structures
X
- XSDBind
- Properties

CICS Deployment Options page:

X
- Start Bundle deployment wizard upon finish

Note:
• W stands for Web Services for CICS
• I stands for IMS Enterprise Suite SOAP Gateway
• B stands for Batch, TSO, and z/OS UNIX System Services
• T stands for XML Transformation for CICS

Developing web services and SOA with Enterprise Service Tools 259
 The DFHSC2LS Application and Transformation properties page
The DFHSC2LS Application and Transformation properties page sets the application and transformation
values for the XML transformation.

Application Properties tab

The Application Properties tab allows you to specify the language of the data structure for which to
generate the transformation artifacts.
This tab contains the following field:
Application Language
Select the high-level language that you want to be used for the generated language structures.

Transformation Properties tab

The Transformation Properties tab selects the available elements or available types for the XML
Transformation.

Note: This wizard provides functionality similar to that of the DFHSC2LS utility in the CICS XML
Transformation Assistant.
On the Transformation Properties tab select:
• Available elements: Elements from the source XSD file that you want to generate transformation for.
Note: This option is common. Typically, you would only need to select Elements.
Use Select All or Deselect All to select or deselect all the available elements in the list.
• Available types: Types from the source XSD file that you want to generate transformation for.
Note: This is option not common. Typically, you would only need to select Elements and not Types,
unless you want the generated code to process all elements of a specific type and not others.
Use Select All or Deselect All to select or deselect all the available types in the list.

The DFHSC2LS Target artifacts page

The DFHSC2LS Target artifacts page sets targets for generating the XSDBind and language structures
files.

Structures tab
The DFHSC2LS Structures tab sets targets for generating language structures files.
On the Structures tab, specify the following options:
Generate to:
Same project
Select this when the file container is on the local system (default).
Remote location
Select this when the file container is on a remote system. For additional information, see “Generation
of Enterprise Service Tools artifacts to remote systems” on page 333.
File container:
Specifies the local or remote folder to which the generated artifacts are written.

Language file prefix:

Specifies a 1 - 6 character prefix used to generate the filenames that contain the high level language
structures for the XML transformation.

260 Developer for z/OS: Developing with Db2, CICS, and IMS
Overwrite files
This checkbox indicates that the wizard overwrites without warning, if files with the same name exist
in the target directory.

XSDBind tab
The DFHSC2LS XSDBind tab sets targets for XSDBind files.
On the XSDBind tab, specify the following options:
File container:
Specifies the local folder to which the XSDBind file is written.
XSDBind file name:
Specifies the name for the XSDBind file.
Log file name:
Specifies the name for the log file.
Overwrite files
This checkbox indicates that the wizard overwrites without warning, if files with the same name exist
in the target directory.

Properties tab
The DFHSC2LS Properties tab displays the path and file names for the new generation properties files.
This tab contains the following fields:
Properties file container:
Displays the path of a folder that is used to create the generation properties files.

Container.xml
Displays the name that is used for the Container.xml file.

PlatformProperties.xml
Displays the name that is used for the PlatformProperties.xml file.

ServiceSpecification.xml
Displays the name that is used for the ServiceSpecification.xml file.

Overwrite files
This checkbox indicates that the wizard overwrites without warning, if files with the same name exist
in the target directory.

CICS deployment options

This page provides the ability to start the Deploy the CICS Bundle wizard.

Select the Start Bundle deployment wizard upon finish and click Finish
This causes the Deploy the CICS Bundle wizard to open upon exiting from the generation wizard. The
location of the XSDBind and other relevant information is passed to the Deploy the CICS Bundle wizard.
The XSDBind file is copied from the location specified in the generation wizard to the location indicated in
the Deploy the CICS Bundle wizard.

Generating artifacts remotely

Using Enterprise Service Tools, you can generate artifacts to MVS and z/OS UNIX System Services on a
remote z/OS system.

To generate artifacts to a remote system, use the Browse button on any of the wizard pages that allow
you to browse to a target file container.
This table shows the possible targets for file containers.

Developing web services and SOA with Enterprise Service Tools 261
 Table 40. Possible target(s) for artifacts
Enterprise Service Target
Tools Artifact
MVS Offline MVS Projects/ z/OS UNIX System
Local Projects Projects System Services System
Converters/Driver Y N Y Y
XSD/WSDL Y N N Y
WSBind Y N N Y
XML Correlator Y N Y N

In the container selection window, expand:

• MVS Projects
– To show PDS's that are associated with it.
• MVS Subsystems
– To show filters, which, when expanded, shows the PDSs that are not migrated or on an offline volume
• z/OS UNIX System Services Subsystems
– To show the ROOT, which, when expanded, shows z/OS UNIX System Services folders
• MVS offline Projects
– To show the folders that were FULL PDS's before going offline
• Local Projects
– To show folders
In the file selection page
When you select a remote artifact, Developer for z/OS uses the following naming convention for the
location path for remote artifacts.
1. For z/OS Project PDS -> MVS Project Name/HLQ.PDS.COBOL
2. For MVS File Sub System -> HLQ.PDS.COBOL
3. For z/OS UNIX System Services File Sub System -> /u/temp (the first '/' represents ROOT)

Table 41. Validation rules

Target
Enterprise Service MVS Offline Projects MVS Projects/System z/OS UNIX System
Tools Artifact Services System
Converters/Driver Offline PDS selected PDS selected must have Verify write access
must have record type of record type of F or FB.
F or FB.
XSD/WSDL Not applicable Not applicable Verify write access
WSBind Not applicable Not applicable Verify write access
XML Correlator Offline PDS selected PDS selected must have Verify write access
must have record type of record type of VB or VBA
VB or VBA

Runtime XML conversion: compiled or interpretive

In Enterprise Service Tools for:

262 Developer for z/OS: Developing with Db2, CICS, and IMS
• Web services for CICS project, or
• XML Transformation for CICS project
Two types of runtime XML conversion are provided: Interpretive XML conversion and Compiled XML
conversion. The compiled XML conversion has more capabilities than the interpretive XML conversion.
When you select either of the two types of conversion, the selection applies to both request XML
conversion and response XML conversion for the resulting service provider or service requester.
Runtime XML conversion includes:
• XML to Language Structure conversion (conversion of data from XML format to some high-level language
data format such as a specific COBOL data structure):
– Service provider: The service provider converts the data in a service request from XML format to a
high-level language data format.
– Service requester: The service requester converts the data in a service response from XML format to
a high-level language data format.
• Language Structure to XML conversion (conversion of data from some high-level language data format
such as a specific COBOL data structure to XML format):
– Service provider: The service provider converts the data in a service response from a high-level
language data format to XML format.
– Service requester:The service requester converts the data in a service request from a high-level
language data format to XML format.

Interpretive runtime XML conversion

Note: Interpretive runtime XML conversion is available only in Web services for CICS projects, XML
Transformation for CICS projects and in service flow projects (see “Availability” on page 264 in this topic).
The supported runtime environments (Web services for CICS and XML Transformation for CICS) includes
an interpretive XML converter that can be invoked during the processing of service requests and service
responsesto convert data from XML format to a high-level language data format or from high-level
language data format to XML format. Using the interpretive XML converter has the advantage of freeing
CICS Web service developers from the task of writing their own XML conversion programs.
In both, Web services for CICS and XML Transformation for CICS, the interface that the runtime
environment provides to a Web service that uses interpretive runtime XML conversion is called the Native
interface.
However, using the interpretive XML converter has the following disadvantages:
• The interpretive engine does not support all the data constructs and types in the COBOL language. This
makes it necessary for a CICS developer to write additional code or a wrapper program to process
unsupported types.
• The behavior of the interpretive engine is not configurable, whereas a user may have very specific needs
in processing SOAP messages.
• The interpretive engine cannot be debugged at runtime.

Compiled runtime XML conversion

Note: Interpretive runtime XML conversion is available only in Web services for CICS projects and XML
Transformation for CICS projects(see “Availability” on page 264 in this topic).
If you choose not to use the interpretive XML converter, or if your Web service is not targeted to run in
either the Web services for CICS or XML Transformation for CICS runtime environment, then the following
must be done:
• You must provide an request XML conversion program and an response XML conversion program that
your target runtime environment can invoke to perform conversion of data from XML data format to

Developing web services and SOA with Enterprise Service Tools 263
 high-level language data format and back (perform conversion of data from high-level language data
format to XML data format).
• You use this development method you must write the conversion programs, transfer them to the host,
compile them, and make them known to the target Web service runtime environment.
In both Web services for CICS and XML Transformation for CICS, the combination of the runtime
environment and the user-supplied XML conversion programs is called the Vendor interface.
In this case, the wizards in the Enterprise Service Tools can be very helpful. You can use a wizard in the
Enterprise Service Tools to generate a COBOL source code module that contains a driver program for a
service provider or service requester (a driver program which is highly configurable through options that
you can select when you are going through the wizard) as well as request and response XML conversion
functions (also configurable through the wizard) and other supporting functions. The XML conversion
functions provide broad support for COBOL data constructs and types, so that in most cases you are not
required to write a wrapper program. The entire COBOL program module can be debugged at run time.
The wizard can also generate other files that are required to deploy a Web service on the host.
See the example application provided by the Enterprise Service Tools: “The CICS catalog manager
example application” on page 531.
Note:
1. In the Web services for CICS environment, for the scenario in which you want to create a new Web
service interface for an existing COBOL application (bottom-up scenario), the wizards in the Enterprise
Service Tools provides more functionality than does the batch file (DFHLS2WS) included in the CICS
Web services assistant (see "The CICS Web services assistant", in the CICS Transaction Server for z/OS
Version 4.1 IBM Documentation, available from CICS Transaction Server for z/OS V4.1 - Library).
2. In the XML Transformation for CICS environment, for the scenario in which you want to create a
new XML Transformation for an existing COBOL application (bottom-up scenario), the wizards in the
Enterprise Service Tools provides more functionality than does the batch file (DFHLS2SC) included
in the CICS XML Transformation assistant (see "The CICS Web services assistant", in the CICS
Transaction Server for z/OS Version 4.1 IBM Documentation, available from CICS Transaction Server
for z/OS V4.1 - Library).

Availability
Interpretive runtime XML conversion is currently only available in Web services for CICS projects and XML
Transformation for CICS projects:

Type of project: XML conversion mechanisms:

Web Services for CICS • Create New Service Interface (bottom-up) wizard - You can choose
Project either:
– Interpretive XML conversion; or
– Compiled XML conversion.
• Map an Existing Service Interface (meet-in-middle) wizard:
– Compiled XML conversion only.
• Create New Service Implementation (top-down):
– Interpretive XML conversion only.

264 Developer for z/OS: Developing with Db2, CICS, and IMS
 Type of project: XML conversion mechanisms:
XML Transformation for • Create New Service Interface (bottom-up) wizard - You can choose
CICS Project either:
– Interpretive XML conversion; or
– Compiled XML conversion.
•
• Create New Service Implementation (top-down):
– Interpretive XML conversion only.
Note: Map an Existing Service Interface (meet-in-middle) wizard is not
supported.

IMS Enterprise Suite SOAP Compiled XML conversion

Gateway Project
Batch, TSO, z/OS UNIX Compiled XML conversion
System Services Project

Limitations and restrictions on single-service projects

This topic covers the known limitations and restrictions for single-service projects generated in Developer
for z/OS.
In addition to listing the known limitations and restrictions, this topic also includes suggestions for
resolving some problems.

Limits on the sizes of request and response messages

This topic describes the maximum length of an XML document that can be derived from an inbound or
outbound data structure:

Enterprise COBOL
For Enterprise COBOL V3.4, V4.1, and V4.2 the maximum length of an XML document generated from an
inbound or outbound data structure is (2^25)-6, or 33,554,436 bytes.
If this limit is exceeded then one of the following messages is displayed during code generation:
• CRRZX0078E The length of an XML document that can be derived from the inbound data structure
exceeds 33,554,436 bytes.
• CRRZX0075E The length of an XML document that can be derived from the outbound data structure
exceeds 33,554,436 bytes.

Enterprise PL/I
For Enterprise PL/I V4.1 the maximum length of an XML document generated from an inbound or
outbound data structure is (2^30)-1, or 1,073,741,823 bytes.
If this limit is exceeded then one of the following messages is displayed during code generation:
• CRRZX0125E The length of an XML document that can be derived from the inbound data structure
exceeds 1,073,741,823 bytes.
• CRRZX0124E The length of an XML document that can be derived from the outbound data structure
exceeds 1,073,741,823 bytes

Developing web services and SOA with Enterprise Service Tools 265
 XML attribute support limitation
This topic covers the limitations for XML attribute support.

XML attribute qualification and XMLPARSE(COMPAT) option

Since the Enterprise COBOL built-in XML parser, which is selected by specifying XMLPARSE(COMPAT),
does not support XML namespaces, XML converters based on the COMPAT parser do not properly process
qualified XML attributes.

Mixed content XML elements are not supported by XML2LS

XSD elements with mixed content may contain character data interspersed between child elements.
Mixed content elements are most often used with freeform text such as letters and documents, and
therefore are not particularly applicable to transaction-oriented language structures.
In Figure 4 on page 266, the element deposit_detail has mixed content, a combination of elements and
character data.
As shown in Figure 4 on page 266, in the XML instance, the character content of the element
deposit_detail is "This transaction was initiated online." Even though “mixed” content elements cannot
be mapped using the Mapping Editor, if an element does have mixed content at runtime, the XML2LS
conversion ignores the content and continues processing at the next mapped element.
Additional reasons for avoiding mixed content in Enterprise Web service interfaces:
• Mixed content has no type specification, for example xsd:decimal, xsd:string.
• Mixed content has an unlimited length.

XML Instance:
<deposit_detail>
This transaction was initiated
<deposit_transaction account_number=”1”
currency_type=”USD”>123.45</deposit_transaction>
online.
</deposit_detail>

XML Schema:
<xs:element name=”deposit_detail” >
<xs:complexType mixed=”true”>
<xs:sequence>
<xs:element ref=”deposit_transaction” minOccurs=”1” maxOccurs=”5” />
</xs:sequence>
</xs:complexType>
</xs:element>

Figure 4. Example of XML Attribute Support Limitation for Mixed Content XML Elements

IMS callout function and PL/I language structure limitation

This topic describes the use of the of "LL"and "ZZ" fields in an Enterprise PL/I application with an IMS
callout function.
The LL field in PL/I language structures is treated correctly as 2 bytes by the PL/I XML Converter in IMS
Connect only when the names of the first 2 fields in the language structure exactly match "LL" and "ZZ"
(As shown in the italic strings in the following example).
Typically, the IMS PL/I application has the following PL/I data structure:

DCL 1 INPMSG,
10 LL FIXED BIN(31),
10 ZZ BIT(16),
10 TRANCODE CHAR(8),

266 Developer for z/OS: Developing with Db2, CICS, and IMS
 10 BLANK CHAR(1),
10 INDATA,
30 FUNC CHAR(3),

:
When conversion errors occur with the PL/I XML converter, rename the first two fields to "LL" and "ZZ"
respectively and regenerate the PL/I XML converter.

Meet-in-middle import of source files

In the meet-in-middle development scenario, in the Import source files wizard, importing with the File
System option is not supported.
To perform the needed function, copy all the required files into a general project and then import the files
in the project by selecting Workspace in Import source files wizard.

Bottom-up conflict with old WSDL/XSD files and new WSDL files and XSD
files
In the bottom-up development scenario, using an older version of generated WSDL files and XSD files
with newly generated converters can cause errors at runtime. For example, the following runtime error
message can occur:

IGZ0282S XML to data structure conversion could not

complete in program PGMNAME because no element names
in the XML document were recognized by the converter.

This event is avoided by only using WSDL files and XSD files generated with the "same" converter; WSDL/
XSDs generated with a converter should always be coupled with the converter, that is older converters
should not be used on new files and new converters should not be used on old files.

Scenarios fail that are importing remote (z/OS Unix) WSDL file that contains,
includes, imports, or redefines a schema
In an Enterprise Service Tools single-service project, if you are running (1) Create New Service
Implementation (top-down) scenario or (2) Map to an Existing Service Interface (meet-in-middle)
scenario, with the WSDL file (that was originally imported from a remote location) that contains, includes,
imports, or redefines a schema, fail with an error.
This event is avoided by:
1. Copying all the required files to either:
• the workstation
• a general project in the workspace
2. Importing the local WSDL file into the "Web Services for CICS Project" using:
RMB -> Import -> Source files and try the top-down scenario.
3. Invoking the top-down scenario.

COBOL conversion routines generated by single-service wizards run in z/OS

only
Even though the workstation COBOL compiler supports XML PARSE statements at both compile time and
runtime, the COBOL programs generated by the single-service wizards are designed to run in the z/OS
environment only.

Developing web services and SOA with Enterprise Service Tools 267
 XML element nesting depth
The XML to language structure converter returns the following exception message:

IGZ0291S XML to data structure conversion could not complete

in program program-name because the maximum XML element
nesting depth was exceeded. The error occurred at element
element-name with character content character-content.

The XML to language structure converter could not handle the nesting depth of a particular XML element.
Although there is an allowance for nesting levels beyond that of the original COBOL structure, this
allowance can be exceeded. For example, if an element exists in the request XML document that is not in
the schema, the element causes the nesting depth error if its nesting level is too deep.

FILLER items not in COBOL data structures

Unnamed groups and their elementary items are not available for selection on the data structure
selection page or the mapping session editor because the parent item is filtered out along with its
elementary items.
This event is resolved by editing the COBOL data structure and giving names to the groups and/or
elementary data items that require conversion. Giving a name to the COBOL group makes its non-filler
elementary items available for selection.

Automatic match mapping of COBOL groups containing ODO (OCCURS

DEPENDING ON) items not supported
If a COBOL data item is, or contains, an ODO (OCCURS DEPENDING ON) item, a "Match mapping" action
with a compatible XML structure cannot be performed.
This event is avoided by, manually mapping the ODO object according to the mapping rules, before
attempting the Match mapping action (In the XML document, the element mapped to the COBOL ODO
object item must appear before the XML element that is mapped to the corresponding COBOL ODO
subject).

Case sensitivity of certain text entry fields in the single-service wizards

Folder and file name entries are case sensitive.
This event is avoided by making sure that the folder and file names are entered consistently. For example,
if your folder name shows as MyFolder in the Workbench, you must type MyFolder in an entry field
requesting a folder name. If you enter myfolder, for example, the tools may flag this as an invalid or
nonexistent folder name.

Invalid pointers cause infinite loop

Providing non-null invalid pointers to XML converters or drivers causes an infinite loop. The XML
converters attempt to detect and report null pointers passed by the caller. For non-null invalid pointers,
the XML Converters likely encounter and return, a protection exception (SOC4).

Support for DBCS data members with Web Services for CICS
Support for DBCS (double byte character set) data items in Enterprise Service Tools single-service
projects requires that the request and response XML documents are encoded in UTF-16 or UTF-8.
• With Web Services for CICS runtime

268 Developer for z/OS: Developing with Db2, CICS, and IMS
 Exchange XML in UTF-8 with a client by default while the XML Converter Driver exchanges XML with
CICS in UTF-16; when UNICODE is needed, UTF-16 is the most efficient choice currently for the XML
Converters.
For either runtime, it might be necessary to configure z/OS support for UNICODE with a conversion image
that supports conversion between UNICODE and the DBCS host codepage.

Menu item "Generate -> XML" File does not honor XSD schema restrictions
The menu item Generate -> XML File does not honor restrictions in an XSD schema. Using the Generate
XML File action on an XSD created by Enterprise Service Tools could lead to the generation of invalid XML
files.
To avoid this event, edit the generated XML file so that the tag contents conform to the restrictions
specified in the XSD schema.

XML and Web services batch processor

The following are limitations with the XML and Web Services batch processor:
• Invalid entries in configuration XML may cause null pointer exceptions during the batch process
Invalid entries in the options XML files (Container.xml, PlatformProperties.xml,
ServicesSpecification.xml) may cause null pointer exceptions during the execution of the batch
processor.
To avoid this event, follow the format for correctly specifying entries in the options XML files.
• Specifying data names in mixed case
Even though the COBOL data names are not case sensitive, the exact case must be specified in the
specification xml files. For example, if in the COBOL data source, the data name is called MY-Data, in the
Service specification xml the nativeTypeName attribute must be set to nativeTypeid="MY-Data". If the
exact case is not specified, the data name is not found and the first available level 01 data name is used
by default.
• Specifying directory for input language file location
The location of the COBOL input files can be specified in the importDirectory attribute as an absolute
path, starting with the drive specification (for example, C:\mypath\test).
Try doing either of the following:
– Place the COBOL source files in the same directory from which xsebatch is invoked.
OR
– If a relative path is desired (for example, so that the configuration files and Cobol source code can
be relocated without changing any file locations in the xsebatch configuration files). Perform the
following:
1. In the service specification file, omit the importDirectory attribute in the following elements:
- InputOutputMessage
- InputMessage
- OutputMessage
2. Include the relative pathname as the value of the importFile attribute in the following elements:
- InputOutputMessage
- InputMessage
- OutputMessage
(For example, importFile="cobol_src/DFH0ACDT.cbl" or importFile="../cobol_src/DFH0ACDT.cbl".)
These paths are relative to the location from which xsebatch is invoked.

Developing web services and SOA with Enterprise Service Tools 269
 3. Place the COBOL source files in the same directory from which xsebatch is invoked. Use Table 42
on page 270 as a guide.

Table 42. Example for Specifying Directory for Input Language File Location
Directory: Description:
C:\workspace\account_details Main project
C:\workspace\account_details\cobol_src Subdirectory with COBOL source files to import
C:\workspace\account_details\xsebatch_confi Subdirectory with XML configuration files for
g xsebatch
4. Use the InputOutputMessage element and assign the name of the COBOL file for the importFile
attribute (In the example in Table 42 on page 270 the COBOL source file called DFH0ACTD.cbl in
the cobol_src directory is used):

<InputOutputMessage importFile="../cobol_src/DFH0ACTD.cbl">
</InputOutputMessage>

Restriction on COBOL figurative constants - LOW-VALUE(S) and HIGH-

VALUE(S)
Figurative constants LOW-VALUE(S) and HIGH-VALUE(S) can be present in COBOL data structures used in
the single-service wizards, but their semantic meaning is ignored by the single-service wizards and is not
carried into the artifacts generated by these Enterprise Service Tools single-service wizards.

GB18030 characters in an Enterprise Service Tools single-service project

name
Do not use GB18030 characters when naming an Enterprise Service Tools single-service project. Using
characters from the GB18030 code page in an Enterprise Service Tools single-service project name
causes errors to occur when you run an Enterprise Service Tools single-service wizard on files in the
project.

When migrating version 6.0 mapping files (.cmx files) the source files
referenced by the .cmx file must be in the same folder
The migration process for the old mapping files requires that the referenced mapped source files be in the
same folder as the mapping file. If this requirement is not met, the Mapping migration tool fails with the
following error message:
Resource [filename].mapping is not local
To avoid this event, move the referenced source files into the same folder as the mapping file that is being
migrated.

Global element names in generated XML schemas are not consistent between
Interpretive and Compiled XML conversion types
The web service message root element names in the XML schemas generated by default generation of
Interpretive and Compiled XML conversion do not match.
You may need to change the generation default of the Compiled XML conversion to match the Interpretive
conversion case. Doing this lets you change the conversion type from interpretive to compiled, if needed
later, without having to republish the WSDL file and without changing code in clients of the web service.

270 Developer for z/OS: Developing with Db2, CICS, and IMS
 When generating the artifacts for Compiled XML conversion you can use the wizard to change the root
element name to match the Interpretive XML conversion. This option is called "Root element name" and is
located in the Generation Options page, on the WSDL and XSD options tab, in the request and response
XML Schema properties group.
For example, the COBOL group named A-B-C causes the Interpretive conversion artifacts to have the
message root element name "a_b_c". The default Compiled conversion artifacts have the root element
name "ABC".
If necessary, the ABC can be changed to a_b_c by using the “Root element name” option in the
Generation Options page so that it can match the the WSDL generated for the interpretive conversion.

DBCS characters not allowed in the generated XML converter file name
DBCS characters are not allowed in the names of Partitioned Data Set members on z/OS. Omit DBCS
characters when specifying the name of the XML converter files. In, addition, check that the default file
names suggested by the wizard do not contain DBCS characters.

Compiler Directives for conditional compilation in COBOL is not supported

Compiler Directives for conditional compilation in COBOL is not supported. The COBOL source that
contains conditional compilation cannot be imported.

Array truncation is supported only in Interpretive XML conversion

The custom converter generated by Developer for z/OS does not truncate arrays. The Truncate null
arrays option in the Preferences setting is ignored in the compiled XML conversion. This option is only
valid for Interpretive XML conversion when CICS handles the conversion.

Bottom-up development: Enabling applications as Web services

This group of topics describes how to enable CICS and IMS applications as Web services.
Enabling a CICS application to run as a Web service in the Web services for CICS environment is described
in detail in the tutorial: “The CICS catalog manager example application” on page 531.

Generate CICS MTOM/XOP Web Service (Bottom-Up)

This topic describes the ability for Enterprise Service Tools Single-service projects to create MTOM/XOP
compatible Web service artifacts for CICS runtimes.
The ability to generate an MTOM/XOP compatible Web service description and runtime specific XML
message processing from a high-level language data structure is available. This is used when an
applicative program is exposed by a service provider and transmits language structures in binary instead
of using an XML representation.
Key components are:
• MTOM (Message Transformation Optimization Mechanism) an abstract specification that in this
implementation describes, a technique to optimize SOAP messages where binary objects are used to
carry data instead of the typical XML payload.
• XOP (XML-binary Optimization Package) describes how the binary objects, attached using MTOM, can
be represented in binary octets instead of base64 .
Using MTOM/XOP, a service requester and service provider can exchange the actual binary/native request
and response language structures without having to use an intermediate XML representation. While SOAP
messages are still used in this configuration, the Body of the messages is very brief, essentially containing
a single XML element that references a binary attachment. In this scenario both the requester and
provider are entirely responsible creation of the language structures and must be sensitive to character
encoding differences between the platforms.

Developing web services and SOA with Enterprise Service Tools 271
 Using the Enterprise Service Tools Web Service Wizard:
Available runtime: Web Services for CICS
Available development scenario: Create New MTOM/XOP Service Interface (bottom-up)
Note: Only allowed values: Application Mode: Service Provider and Conversion Type: Interpretive XML
Conversion
Limitations are:
• CICS COBOL MTOM/XOP Service Providers:
– COMMAREA-based: The maximum size of an MTOM/XOP attachment (derived from a language
structure) is 32767 bytes as this is the maximum size of a DFHCOMMAREA.
– CHANNEL-based: The maximum size of an MTOM/XOP attachment (derived from a language
structure) is 128mb, which is the maximum size of a COBOL data item.
– CHANNEL DESCRIPTION DOCUMENT-based: Not supported.
• CICS PL/I MTOM/XOP Service Providers:
– COMMAREA-based: The maximum size of an MTOM/XOP attachment (derived from a language
structure) is 32767 bytes as this is the maximum size of a DFHCOMMAREA.
– CHANNEL-based: The maximum size of an MTOM/XOP attachment (derived from a language
structure) is 32767 bytes as this is the maximum size of a character array in PL/I.
– CHANNEL DESCRIPTION DOCUMENT-based: Not supported
In order to take advantage of MTOM/XOP support in CICS, provider and requester mode Web services
must reside in pipelines that are respectively configured for MTOM/XOP message handling. Figure 5
on page 272 is an example configuration file for a provider-mode pipeline that supports bi-directional
MTOM/XOP messaging.

<?xml version="1.0" encoding="EBCDIC-CP-US"?>

<provider_pipeline xmlns="http://www.ibm.com/software/htp/cics/pipeline"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.ibm.com/software/htp/cics/pipelineprovider.xsd ">
<cics_mtom_handler>
<dfhmtom_configuration version="1">
<mtom_options send_mtom="yes" send_when_no_xop="yes" />
<xop_options apphandler_supports_xop="yes" />
<mime_options content_id_domain="example.org" />
</dfhmtom_configuration>
</cics_mtom_handler>
<service>
<terminal_handler>
<cics_soap_1.1_handler />
</terminal_handler>
</service>
<apphandler>DFHPITP</apphandler>
</provider_pipeline>

Figure 5. Example MTOM/XOP enabled provider-mode pipeline configuration

CICS applies message handlers to the request message in the order the messages appear in the
configuration file; this order is reversed for the response message. In Figure 5 on page 272, MTOM/XOP
message handling is applied first to unpack MTOM attachments from the request message and last to
package MTOM attachments with the response message. To compliment Figure 5 on page 272, Figure
6 on page 273 is a sample configuration file for a requester-mode pipeline that supports bi-directional
MTOM/XOP messaging:

272 Developer for z/OS: Developing with Db2, CICS, and IMS
 <?xml version="1.0" encoding="EBCDIC-CP-US"?>
<requester_pipeline xmlns="http://www.ibm.com/software/htp/cics/pipeline"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.ibm.com/software/htp/cics/pipelinerequester.xsd ">
<service>
<service_handler_list>
<cics_soap_1.1_handler />
</service_handler_list>
</service>
<cics_mtom_handler>
<dfhmtom_configuration version="1">
<mtom_options send_mtom="yes" send_when_no_xop="yes" />
<xop_options apphandler_supports_xop="yes" />
<mime_options content_id_domain="example.org" />
</dfhmtom_configuration>
</cics_mtom_handler>
</requester_pipeline>

Figure 6. Example MTOM/XOP enabled requester-mode pipeline configuration

Enabling an application for the IMS Enterprise Suite SOAP Gateway

The IMS Enterprise Suite SOAP Gateway is a Web service solution that integrates IMS assets in a Service-
Oriented Architecture (SOA) environment.

The SOAP Gateway enables IMS applications to interoperate outside of the IMS environment through
SOAP to provide and request services independent of platform, environment, application language, or
programming model.
You can enable an IMS PL/I application or a COBOL application for Web services by using a wizard from
the Enterprise Service Tools to generate Web service files for the specified IMS application. You then
deploy these Web service files to the SOAP Gateway to make the specified IMS application available
as a Web service. Different types of client applications, such as Microsoft.NET, Java, and third-party
applications, can then submit SOAP requests into IMS to drive the business logic of the PL/I or COBOL
application.
There are two main steps to enabling your IMS application as a Web service running in the IMS Enterprise
Suite SOAP Gateway environment:
1. Use the Create New Service Interface (bottom-up) wizard from the Enterprise Service Tools to
generate Web service files for your IMS application. (The generated files are described in the next
paragraph.)
2. Use the IMS deployment utility to deploy the Web service interface to the SOAP Gateway. (The IMS
deployment utility allows you to define connection and correlation information for the Web service.)
In the first step, you use the Create New Service Interface (bottom-up) wizard from the Enterprise Service
Tools to generate the Web service files from an existing PL/I source file or COBOL source file in your IMS
application. The source file must contain the request and response interface data structures for your IMS
application. In most cases you do not have to modify or add to your existing IMS application source code.
The wizard generates the following Web service files:
• A Web Services Description Language (WSDL) file, which describes the Web service interface of the IMS
application so that the client can communicate with the Web service.
• A correlator file, which contains information that enables the IMS Enterprise Suite SOAP Gateway to set
the IMS properties and call the IMS application.
• A PL/I or COBOL source file that contains a Web service driver and runtime XML conversion programs.
These runtime XML conversion programs convert request and response data in XML format (which is
the format used by SOAP), to and from the request and response interface data structures in your IMS
application (either PL/I or COBOL).

Developing web services and SOA with Enterprise Service Tools 273
 For more information about using the IMS Enterprise Suite SOAP Gateway, including samples, see IMS
Enterprise Suite SOAP Gateway documentation and the IMS Enterprise Suite SOAP Gateway Web site at
http://www.ibm.com/ims.

Overview of creating a service provider from an IMS multisegment MPP using the IMS
Enterprise Suite SOAP Gateway Web service wizard
This topic demonstrates both the tool and runtime aspects of enabling and IMS multisegment MPP as a
Web service. The illustration provided shows: (1) how the language structures and multisegment message
layout of the MPP are represented in a generated XML Schema, and (2) how the XML to Language
Structure converter transforms an XML instance document into IMS multisegment message.

See Figure 7 on page 274.

Figure 7. Overview of creating a service provider from an IMS multisegment MPP using the IMS Enterprise
Suite SOAP Gateway Web service wizard

For more information about using the IMS Enterprise Suite SOAP Gateway, including samples, see IMS
Enterprise Suite SOAP Gateway documentation and the IMS Enterprise Suite SOAP Gateway Web site at
http://www.ibm.com/ims.

274 Developer for z/OS: Developing with Db2, CICS, and IMS
Related concepts

“Generating artifacts remotely” on page 261

Support for Multi-Segment Message Processing Programs in...IMS Enterprise Suite SOAP Gateway Single-
Service Project
“Creation of XML schemas from multiple language structures” on page 310
Related tasks

“Generation of composite XML schemas from multiple language

structures” on page 312
“Specification of multiple request language structures” on page 311
“Specification of Multiple Response Language Structures” on page 311
“Deploying the Web service files to the IMS Enterprise Suite SOAP Gateway” on page 277
“Generating service interface files from the IMS application” on page 275

Generating service interface files from the IMS application

Use the Enterprise Service Tools to generate the artifacts that are needed to enable your existing IMS
PL/I application or COBOL application to run as a Web service in the IMS Enterprise Suite SOAP Gateway
runtime environment.
To generate the artifacts that are needed to enable an existing IMS PL/I application or COBOL application
for the IMS Enterprise Suite SOAP Gateway environment, you must have a PL/I include file or a COBOL
copybook that describes the format of the input and output messages for the IMS application.

Because artifacts generated by the Enterprise Service Tools wizard (the WSDL file, the correlator file, and
either PL/I include file or the COBOL copybook file containing the Web service driver and the runtime XML
conversion programs) must be transferred to a z/OS system, you can use the z/OS Projects perspective
and a local z/OS project in Developer for z/OS to assist with this task.
To generate Web services artifacts for the IMS Enterprise Suite SOAP Gateway runtime environment:
1. To open the z/OS Projects perspective, click the Open Perspective toolbar button, and then
double-click z/OS Projects.
2. Create a local z/OS project:
a. Right-click the z/OS Projects view and select New > Local z/OS Project. The New Local Project
window opens.
b. Type a name for the project.
c. From the Property Group area, select one of these options:
• Select a property group to associate with the project Select this option and then select a
property group for the new project. You can sort the list by clicking the table headings. To
reverse the sort order, click the table headings again.
• Create a property group and associate it with the project. Click Finish to edit the property
group. Select this option to create a property group for the project. Type a name for the group in
the Name field.
• Do not associate the project with a property group. Select this option to create the project
without associating it with a property group.
d. Click Finish. If you are creating a new property group, the property group editor opens.
3. Verify that the Navigator view is open in the z/OS Projects perspective; a Navigator tab should be
visible on the interface. If the Navigator view is not open, follow these steps to open the Navigator
view:
a. In the menu bar of the workbench, select Window > Show View > Other. The Show View wizard
opens.
b. In the Show View wizard, expand General, select Navigator, and click OK.

Developing web services and SOA with Enterprise Service Tools 275
 The Navigator view opens.
4. Import into your local project the file (either the PL/I include file or the COBOL copybook file),
that contains the data structures which describe the input and output data structures of your IMS
application. The imported file should also be visible in the Navigator view.
The files that can be used to import into your local project are:
• COBOL:.cbl, .cpy, .cob, and .ccp
• PL/I: .pli, .inc, and .mac
5. Start the Enterprise Service Tools Wizard Launchpad from the Navigator view:
Note: The following steps are only for the Create New Service (bottom-up) wizard, see Contexts for
starting the single-service wizards when you run the wizard outside the Enterprise Tools Perspective
for additional information.
a. In the Navigator view, right-click the imported source file (PL/I or COBOL) that contains the input
and output data structures of the IMS application.
b. Select Enable Enterprise Web Service.
The Enterprise Service Tools Wizard Launchpad wizard opens.
6. Launch the Create New Service Interface (bottom-up) wizard:
a. In the Enterprise Service Tools Wizard Launchpad wizard, make these selections, and then click
Start:
Runtime: IMS Enterprise Suite SOAP Gateway
Scenario: Create New Service Interface (bottom-up)
Conversion type: Compiled XML Conversion
The Create New Service Interface (bottom-up) wizard opens.
7. On the first page of the wizard (entitled Language structures):
a. Click the button Change PL/I Preferences or Change COBOL Preferences. The Preferences
window opens and displays the PL/I or COBOL preferences in the right pane.
b. In the General tab of the PL/I or COBOL preferences page, expand the Platform list box, select
z/OS, verify or change other entries that apply for your z/OS system and then click OK.
c. In the Request Language Structure tab, select the high-level language structure (PL/I or COBOL)
that is the input structure for your IMS application. By default, the first structure defined in the
program source file is selected.
d. In the Response Language Structure tab, select the high-level language structure (PL/I or
COBOL) that is the input structure for your IMS application. By default, the first structure defined
in the program source file is selected.
e. Click Next.
8. On the second page of the wizard (entitled Generation Options):
a. In the XML Converters tab, make these selections:
Host code page: Select the code page that the host uses.
Request code page: 1208 Unicode, UTF-8
Response code page: 1208 Unicode, UTF-8
Note: At this time the IMS Enterprise Suite SOAP Gateway runtime environment supports only
UTF-8.
b. In the Service Location (Endpoint URI) input field of the WSDL and XSD tab, change the host
name and port name to the location of the IMS Enterprise Suite SOAP Gateway, verify or change
other entries that apply for your z/OS system, and click Next.
Note: This URI specifies the address of the Web service.
9. On the third page of the wizard (entitled IMS Enterprise Suite SOAP Gateway Service Provider):

276 Developer for z/OS: Developing with Db2, CICS, and IMS
 a. In the IMS Correlator file tab, specify any correlator properties that need to be specified for your
IMS Enterprise Suite SOAP Gateway environment. In particular, in the input field File container,
specify the folder and subfolder in which you want the correlator file to be generated.
Note: You can generate artifacts directly to the z/OS UNIX System Services file system (see
“Generating artifacts remotely” on page 261).
b. Click Next.
10. On the fourth page of the wizard (titled File, data set, or member selection):
a. In the XML Converters tab, specify these values:
Converter file container: The folder and subfolder in which you want the converter programs
to be created.
Converter driver file name: The name of the file in which you want the converter programs to
be generated.
Note: Make sure that the checkbox Generate all to driver is selected. This causes all the
generated Web service programs (driver, request converter, and response converter) to be placed
in the same file. You can generate artifacts directly to MVS (see “Generating artifacts remotely” on
page 261).
b. In the WSDL and XSD tab, specify these settings:
WSDL file container: Specify the folder and subfolder in which you want the WSDL and XSD
files to be generated.
WSDL file name: Select this checkbox and .type the name of the file in which you want the
WSDL document to be created.
Request XSD file name: Clear this checkbox.
Response XSD file name: Clear this checkbox.
Note: The XSD files are not required by IMS SOAP Access. However, as an option, you can select
these two checkboxes to cause the two XSD files to be generated. You can generate artifacts
directly to the z/OS UNIX System Services file system (see “Generating artifacts remotely” on
page 261).
c. Click Finish.
The following files are generated:
• The WSDL file (.wsdl).
• The correlator file (.xml).
• The file containing the Web service driver and runtime XML conversion programs (.cbl).
• The request and response XSD files (.xsd).

After you create the service interface files, the next step is to deploy the service interface files to the IMS
Enterprise Suite SOAP Gateway using the IMS SOAP deployment tool (see “Deploying the Web service
files to the IMS Enterprise Suite SOAP Gateway” on page 277).

Deploying the Web service files to the IMS Enterprise Suite SOAP Gateway
This topic provides a brief overview of the tasks required to deploy the generated Web service files to the
IMS Enterprise Suite SOAP Gateway.

For information about completing the IMS Enterprise Suite SOAP Gateway tasks listed in this topic, see
the IMS Enterprise Suite SOAP Gateway web site at http://www.ibm.com/software/data/ims/soap/.
To deploy the generated Web service files to the IMS Enterprise Suite SOAP Gateway:
1. Install the IMS Enterprise Suite SOAP Gateway.
2. Configure IMS Connect for the IMS Enterprise Suite SOAP Gateway. (Note: IMS Connect must be
installed and properly configured.)

Developing web services and SOA with Enterprise Service Tools 277
 3. Locate the Web service files that you generated using the Create New Service Interface (bottom-
up) wizard from the Enterprise Service Tools (see “Generating service interface files from the IMS
application” on page 275).
4. Deploy the Web service files to the IMS Enterprise Suite SOAP Gateway using the IMS Enterprise Suite
SOAP Gateway deployment utility.
5. Create the client application.
6. Run the client application.
Related concepts

“Generating artifacts remotely” on page 261

“Enabling an application for the IMS Enterprise Suite SOAP Gateway” on page 273
Related tasks

“Generating service interface files from the IMS application” on page 275

Support for multisegment message processing programs in IMS Enterprise Suite SOAP
Gateway single-service projects
This topic describes the ability of the Enterprise Service Tools perspective to enable IMS multi-segment
Message Processing Programs (MPPs) as Web services in the bottom-up "Create New Service Interface"
development scenario.
With certain restrictions, the language structure selection panels in the Web service wizard allow multiple
language structures. As part of the page "IMS Message Layouts", two selection tabs are provided; the
Request Message Layout tab and the Response Message Layout tab.
Use the "Request Language Structures" and "Response Language Structures" tabs on the "Language
Structures" page to select the structures that describe the request and response interfaces to the
IMS MPP. When language structures are selected on the language structure tabs, they are entered into
corresponding tables on the "IMS Message Layouts" page.
After selecting the language structures, use the tabs on the "IMS Message Layouts" page to specify
the layout of the request and response messages in detail. Indicate the order and count of each
language structure in their respective messages by using the tables on the "Request Message Layout"
and "Response Message Layout" tabs. The layouts specified in these tables indicate how the XML and
binary messages are structured.

Limitations and Error Conditions

In general, multiple language structure selection and multi-segment support is supported only for IMS
Enterprise Suite SOAP Gateway and IMS MPPs written in COBOL.
The following limitations apply when specifying the IMS message layouts:
• While a language structure can occur more than once, the occurrences MUST be consecutive; they
cannot be interleaved with occurrences of other language structures.
• At most one language structure can occur a variable number of times (variable-count) and may only be
followed by a language structure with a minimum and maximum count of one.
• The total maximum size of the message layout, when represented in either XML or binary format cannot
exceed 32MB when Enterprise COBOL V3R4 or later is used, or 16MB when Enterprise COBOL V3R3 or
earlier is used.
The following limitations apply when selecting multiple language structures:
1. Each language structure must begin with two 2-byte fields (LL and ZZ per IMS).
2. Each language structure cannot exceed 32767 bytes (maximum size of an IMS message segment).
3. At most 256 language structures can be selected for each of the request and response.

278 Developer for z/OS: Developing with Db2, CICS, and IMS
 4. Inter-language structure dependencies are not supported; for example, OCCURS DEPENDING ON
(ODO) subjects in selected language structures cannot specify an ODO object declared outside of the
structure.

Architecture of a bottom-up Web service provider using the IMS Enterprise Suite SOAP
Gateway
This topic provides an overview of the architecture for a Web service provider using IMS Enterprise Suite
SOAP Gateway and created through the bottom-up development scenario.
The following steps describe how a message is processed at runtime:
1. The Web service client application sends a SOAP message to the IMS Enterprise Suite SOAP Gateway
containing input to the IMS application in an XML format.
2. The SOAP Gateway processes the SOAP header and retrieves the appropriate correlation and
connection information for the input request.
3. The SOAP Gateway creates an IMS Connect message, consisting of an IMS Connect header followed by
the input XML data, to IMS Connect using TCP/IP.
4. IMS Connect calls its XML adapter, which in turn calls the XML converter to transform the XML data to
IMS application format.
5. IMS Connect sends the message for further processing. For the remainder of this step the processing
is the same as for a normal transaction flow. The transaction returns its output and the output is
queued to IMS Connect.
6. IMS Connect calls the XML adapter to transform the IMS application data to XML format.
7. IMS Connect sends the output XML message back to the SOAP Gateway using TCP/IP.
8. The SOAP Gateway wraps a SOAP header around the output message.
9. The IMS Enterprise Suite SOAP Gateway sends the SOAP output message back to the client
application.
In this service provider architecture, IMS Message Processing Programs (MPPs) s are not aware that they
are being invoked as Web services and therefore do not have access to the service invocation context.

Meet-in-middle development
This group of topics describes issues involved in meet-in-middle development.

Support for the IMS Callout (ICAL) call

This topic describes the support of the IMS Callout (ICAL) call by the XML converters.

Scenario
When you generate files for a Web service requester for the IMS runtime using the meet-in-middle
scenario and compiled conversion, you can select either the synchronous or the asynchronous type of
callout message.
Asynchronous callout means that the IMS application invokes the Web service requester by issuing an
IMS Insert (ISRT) call, which places the outgoing request message into the IMS message queue. Likewise
when the Web service requester receives the response to the request, it places the incoming response
message into the IMS message queue for the IMS application to retrieve.
Synchronous callout means that the IMS application invokes the Web service requester by issuing an IMS
Callout (ICAL) call, which synchronously invokes the Web service requester with the outgoing request
message. When the Web service requester receives the response to the request, the incoming response
message is returned to the IMS application through the return from the ICAL call.
For the IMS application it is usually much more convenient to issue a synchronous call.
To select asynchronous or synchronous processing:

Developing web services and SOA with Enterprise Service Tools 279
 1. In the graphical user interface, select the appropriate value in the Callout message type list box on
the IMS Enterprise Suite SOAP Gateway Service Requester page of the meet-in-middle wizard.
2. In the batch processor, select the appropriate value in the GEN_IMS_MESSAGE_TYPE attribute in the
CodegenProperty element (see “CodegenProperty” on page 422).

Support for IMS Callout (ICAL)

Compiled XML Conversion artifacts generated by prior versions of Developer for z/OS are compatible with
the ICAL call only if the mapped 01 level language structures begin with LL and ZZ fields.
Because the ICAL call bypasses IMS message queues, the call requires that the request and response
data for the remote web service are entirely contained in at most two 01 level language structures, one for
the request and one for the response. In addition, language structures do not need to begin with LL and
ZZ since these fields are used only with asynchronous messaging; if these fields are defined in an 01 level
language structure used with ICAL, the fields are treated as data.

Support for the nillable attribute

This topic describes the support for the nillable attribute in the COBOL Compiled XML Conversion process.
The nillable attribute can be defined on an xsd:element within an XML schema. It specifies that the xsi:nil
attribute is valid for the element. If an XML schema has defined the nillable attribute as true, it is mapped
as a required attribute and is included in the document, however, its values are nullified. Depending on
the circumstances, the XML conversion process behaves differently when nillable elements are mapped.
The XML2LS (inbound) converter will move all LOW-VALUES to a COBOL field if the following conditions
are met:
1. The XSD element that is mapped to the COBOL field has nillable="true".
2. The XSD element is mapped to a COBOL field of type PIC X, G, or N.
3. The XML element specifies xsi:nil="true" and has a content length of 0 (no character content) at
execution time.
The LS2XML (outbound) converter will generate the xsi:nil="true" attribute(*2) on an XML element if
the following conditions are met:
1. The XSD element to which the COBOL field is mapped specifies nillable="true".
2. The COBOL field to which the XSD element is mapped is of type PIC X, G, or N.
3. The COBOL field contains all LOW-VALUES at execution time.
In Figure 8 on page 281, when the COPY and XSD files are imported and the COBOL field ELE-1 is
mapped to the XSD item ele_1, the following results will be achieved:
• The XML2LS converter will move all LOW-VALUES to ELE-1 if the XML content does not contain
character content like <el1_1 attr_1="01020" xsi:nil="true"/> at execution time.
• The LS2XML converter will generate <el1_1 attr_1="01020" xsi:nil="true"/> if ELE-1
contains all LOW-VALUES at execution time.

280 Developer for z/OS: Developing with Db2, CICS, and IMS
 COPY:
01 STRUCT-1.
05 ATTR-1 PIC X(5).
05 ELE-1 PIC X(10).

XSD:
<?xml version="1.0" encoding="UTF-8" ?>

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:p1="http://www.example.com"
targetNamespace="http://www.example.com"
elementFormDefault="unqualified"
attributeFormDefault="unqualified">

<xs:element name="ele1_detail">
<xs:complexType>
<xs:sequence>
<xs:element name="ele_1" type="p1:ele_1" nillable="true"/>
</xs:sequence>
</xs:complexType>
</xs:element>

<xs:complexType name="ele_1">
<xs:simpleContent>
<xs:extension base="xs:string">
<xs:attribute name="attr-1">
<xs:simpleType>
<xs:restriction base="xs:string">
</xs:restriction>
</xs:simpleType>
</xs:attribute>
</xs:extension>
</xs:simpleContent>
</xs:complexType>

</xs:schema>

Figure 8. xsd:nillable Example

Mapping concepts: XML to COBOL or PL/I

This group of topics describes the concepts for mapping XML Schema structures to COBOL or PL/I data
structures.

Introduction to mapping concepts

This topic describes the basics of mapping.
Mapping refers to the process of copying data from a source location to a target location, and at the same
time converting the data from one type of data format to another. For example, an inbound converter for
a Web service provider copies and converts data from locations in an inbound XML schema data structure
to locations in a COBOL or PL/I language structure. This language structure is then passed to a CICS
application as the input data.
Similarly, in the same scenario, when the same CICS application returns with its output data in a COBOL
or PL/I language structure, an outbound converter for the Web service provider copies and converts the
data from the COBOL or PL/I language data structure to locations in the outbound XML schema data
structure.
A single mapping is a single instance of copying and converting an item of data from XML schema
structure to language structure data, or from language structure to XML schema structure. Such mappings
are defined in the mapping editor.
Mapping is used only in meet-in-middle development scenarios. The main steps in developing a meet-in-
middle project are as follows:
1. Create a meet-in-middle project using a New <runtime> Project wizard.
2. Import source files into the project using the Import Source Files wizard.

Developing web services and SOA with Enterprise Service Tools 281
 3. Create two mapping files using the Create Mappings wizard:
a. A mapping file containing the inbound XML and COBOL (or PL/I) data structures
b. A mapping file containing the outbound XML and COBOL (or PL/I) data structures
4. Specify in each mapping file the source and target data elements.
5. Generate resources for a runtime using the Generate <runtime> Resources wizard (meet-in-middle
wizard).
Mappings can be done for data structures stored in the following types of files:
• COBOL source files (the file extension must be .cbl, .cob, .ccp, or .cpy)
• PL/I source files (the file extension must be .pli, .inc, or .map)
• XML content:
– WSDL documents (the file extension must be .wsdl)
– XML instance documents (the file extension must be .xml)
– XML schema (XSD) documents (the file extension must be .xsd)
Mappings are based on the following data models:
• The language data model for a COBOL or PL/I language structure is expressed as an instance of the
COBOL or PL/I Common Application Metamodel (CAM).
• The XML data model for a given language structure is expressed as an instance of the XML Schema
model (whether it is an XML document, WSDL types definition, or XML Schema representation).

Mapping sessions
This topic describes mapping sessions.
A mapping session is the process of using the mapping editor to create mappings between locations in an
XML schema structure and locations in a COBOL or PL/I data structure.
Mappings are stored in a mapping session file. A request mapping session file contains mappings from
XML to COBOL or PL/I. A response mapping session file contains mappings from COBOL or PL/I to XML.
The contents of a mapping session file is called mapping metadata and includes the names and locations
of the source and target elements and the particulars of each mapping.
To create mapping session files you use the Create Mappings wizard, in which you specify the source and
target elements. You then use the mapping editor to create mappings. For each mapping you connect the
appropriate locations in the source and target elements.
Important: Because a mapping session file contains links to the COBOL and XML files relative to the
workbench project, these links might not resolve correctly if you move the mapping session file to a
different folder. Use caution when moving the mapping session file from the directory where it was
created (relative to the workbench project) or when importing already existing mapping session files into
the workbench. In general, moving or importing a mapping session file works only if the file is moved or
imported into a similar directory structure (relative to the workbench project) with identical subdirectory
names.
Related concepts
“Mapping concepts: XML to COBOL or PL/I” on page 281
Related reference
“XML to COBOL mapping reference” on page 337

Mapping editor
This topic describes the mapping editor for the single-service project tools.

282 Developer for z/OS: Developing with Db2, CICS, and IMS
In the mapping editor you create a mapping by connecting an item on the left side of the editor (the
source of the mapping) to an item on the right side of the editor (the target of the mapping). At runtime
when the mapping is performed the data in the source element is converted to the target format and
stored in the target element.
In a request session the XML structure is displayed on the left side of the editor and the COBOL data
structure is displayed on the right side of the editor. In a response session the positions are reversed:
COBOL or PL/I on the left side; XML on the right side.
An element on the left side is called a sender element. An element on the right side is called a receiver
element. A sender element and a receiver element can be mapped together only if they have type
compatibility (see “XML to COBOL mapping reference” on page 337).
The mapping editor supports one-to-one mapping, that is, mapping that goes between one simple or
complex XML structure and one compatible COBOL or PL/I element or structure. You can have multiple
one-to-mappings in one session. The mapping editor does not support one-to-many mapping or many-to-
many mapping.
For both COBOL and PL/I you can map an XML element to a language variable or data structure.
For COBOL only you can also map an XML attribute to a language variable or data structure. (For
XML attributes see the limitations described in “Mapping XML attributes to COBOL with Compiled XML
Conversion” on page 296.)

Related concepts

“Mapping concepts: XML to COBOL or PL/I” on page 281

Related reference
“XML to COBOL mapping reference” on page 337

Supported mappings between language data types and XML Schema built-in
data types
This topic describes the supported mappings between the data types of the supported languages (COBOL
and PL/I) and the XML Schema built-in datatypes.

COBOL data types

Columns:
0 COBOL Address type
1 COBOL Alphabetic type
2 COBOL Alphanumeric-edited type
3 COBOL Alphanumeric type
4 COBOL DBCS type
5 COBOL External floating-point type
6 COBOL Internal floating-point type
7 COBOL Numeric-edited type
8 COBOL Numeric type
9 COBOL Object reference type
10 COBOL National (Unicode) type

0 = The mapping is not supported.

1 = The mapping is supported.

Developing web services and SOA with Enterprise Service Tools 283
 Table 43. COBOL-XML Schema mappings
XML
Schem
a Type 0 1 2 3 4 5 6 7 8 9 10
string 0 1 1 1 1 0 0 1 1 0 1
boolea 0 1 0 1 0 0 0 0 1 0 0
n
float 0 0 0 0 0 0 1 1 1 0 0
double 0 0 0 0 0 0 1 1 1 0 0
decim 0 0 0 1 0 0 0 1 1 0 0
al
duratio 0 0 0 1 0 0 0 0 0 0 0
n
dataTi 0 0 0 1 0 0 0 0 0 0 0
me
time 0 0 0 1 0 0 0 0 0 0 0
date 0 0 0 1 0 0 0 0 0 0 0
gYear 0 0 0 1 0 0 0 0 0 0 0
Month
gYear 0 0 0 1 0 0 0 0 0 0 0
gMont 0 0 0 1 0 0 0 0 0 0 0
hDay
gDay 0 0 0 1 0 0 0 0 0 0 0
gMont 0 0 0 1 0 0 0 0 0 0 0
h
hexBin 0 0 0 0 0 0 0 0 0 0 0
ary
base6 0 0 0 0 0 0 0 0 0 0 0
4Binar
y
anyUR 0 0 0 1 0 0 0 0 0 0 0
I
QNam 0 0 0 1 0 0 0 0 0 0 0
e
NOTAT 0 0 0 1 0 0 0 0 0 0 0
ION
normal 0 0 0 1 0 0 0 0 0 0 0
izedStr
ing
token 0 0 0 1 0 0 0 0 0 0 0
langua 0 0 0 1 0 0 0 0 0 0 0
ge

284 Developer for z/OS: Developing with Db2, CICS, and IMS
Table 43. COBOL-XML Schema mappings (continued)
XML
Schem
a Type 0 1 2 3 4 5 6 7 8 9 10
IDREF 0 0 0 0 0 0 0 0 0 0 0
S
ENTITI 0 0 0 0 0 0 0 0 0 0 0
ES
NMTO 0 0 0 1 0 0 0 0 0 0 0
KEN
NMTO 0 0 0 0 0 0 0 0 0 0 0
KENS
Name 0 0 0 1 0 0 0 0 0 0 0
NCNa 0 0 0 1 0 0 0 0 0 0 0
me
ID 0 0 0 1 0 0 0 0 0 0 0
IDREF 0 0 0 1 0 0 0 0 0 0 0
ENTIT 0 0 0 0 0 0 0 0 0 0 0
Y
integer 0 0 1 1 0 0 0 1 1 0 0
nonPo 0 0 1 1 0 0 0 1 1 0 0
sitiveI
nteger
Negati 0 0 1 1 0 0 0 1 1 0 0
veInte
ger
long 0 0 1 1 0 0 0 1 1 0 0
int 0 0 1 1 0 0 0 1 1 0 0
short 0 0 1 1 0 0 0 1 1 0 0
byte 0 0 1 1 0 0 0 1 1 0 0
nonNe 0 0 1 1 0 0 0 1 1 0 0
gativeI
nteger
unsign 0 0 1 1 0 0 0 1 1 0 0
edLon
g
unsign 0 0 1 1 0 0 0 1 1 0 0
edInt
unsign 0 0 1 1 0 0 0 1 1 0 0
edShor
ti
unsign 0 0 1 1 0 0 0 1 1 0 0
edByte

Developing web services and SOA with Enterprise Service Tools 285
 Table 43. COBOL-XML Schema mappings (continued)
XML
Schem
a Type 0 1 2 3 4 5 6 7 8 9 10
positiv 0 0 1 1 0 0 0 1 1 0 0
eInteg
er

PL/I data types

Columns:
0 PLI Float type
1 PLI Integer type
2 PLI Packed type
3 PLI Picture type
4 PLI Fixed-length string
5 PLI Variable-length string
6 PLI Picture string type
0 = The mapping is not supported.
1 = The mapping is supported.

Table 44. PL/I-XML Schema mappings

XML
Schema
Type 0 1 2 3 4 5 6
string 1 1 1 1 1 1 1
boolean 0 1 1 1 1 1 1
float 1 0 0 0 0 0 0
double 1 0 0 0 0 0 0
decimal 0 1 1 0 0 0 0
duration 0 0 0 0 0 0 0
dataTime 0 0 0 0 0 0 0
time 0 0 0 0 0 0 0
date 0 0 0 0 0 0 0
gYearMont 0 0 0 0 0 0 0
h
gYear 0 0 0 0 0 0 0
gMonthDay 0 0 0 0 0 0 0
gDay 0 0 0 0 0 0 0
gMonth 0 0 0 0 0 0 0
hexBinary 0 0 0 0 1 0 0
base64Bin 0 0 0 0 0 0 0
ary

286 Developer for z/OS: Developing with Db2, CICS, and IMS
Table 44. PL/I-XML Schema mappings (continued)
XML
Schema
Type 0 1 2 3 4 5 6
anyURI 0 0 0 0 0 0 0
QName 0 0 0 0 0 0 0
NOTATION 0 0 0 0 0 0 0
normalized 0 0 0 0 0 0 0
String
token 0 0 0 0 0 0 0
language 0 0 0 0 0 0 0
IDREFS 0 0 0 0 0 0 0
ENTITIES 0 0 0 0 0 0 0
NMTOKEN 0 0 0 0 0 0 0
NMTOKEN 0 0 0 0 0 0 0
S
Name 0 0 0 0 0 0 0
NCName 0 0 0 0 0 0 0
ID 0 0 0 0 0 0 0
IDREF 0 0 0 0 0 0 0
ENTITY 0 0 0 0 0 0 0
integer 0 1 1 1 1 1 1
nonPositive 0 1 1 1 1 1 1
Integer
NegativeIn 0 1 1 1 1 1 1
teger
long 0 1 1 1 1 1 1
int 0 1 1 1 1 1 1
short 0 1 1 1 1 1 1
byte 0 1 1 1 1 1 1
nonNegativ 0 1 1 1 1 1 1
eInteger
unsignedLo 0 1 1 1 1 1 1
ng
unsignedIn 0 1 1 1 1 1 1
t
unsignedS 0 1 1 1 1 1 1
horti
unsignedB 0 1 1 1 1 1 1
yte

Developing web services and SOA with Enterprise Service Tools 287
 Table 44. PL/I-XML Schema mappings (continued)
XML
Schema
Type 0 1 2 3 4 5 6
positiveInt 0 1 1 1 1 1 1
eger

Isomorphic and nonisomorphic simple mapping

This topic describes isomorphic and nonisomorphic simple mapping.

The single-service project tools support both isomorphic simple mappings and nonisomorphic simple
mappings in both request mappings and response mappings.

Isomorphic and nonisomorphic mapping

A mapping is isomorphic if both the following conditions are met:
• Each composed element (that is, an element that contains other elements) of the XML instance
document starting from the root has one and only one corresponding high-level-language data item
(a COBOL group item or a PL/I item) whose nesting depth is identical to the nesting depth of its XML
equivalent; and
• Each non-composed element (in other words, an element that does not contain other elements) in the
XML instance document starting from the top has one and only one corresponding high-level-language
data item (a COBOL elementary item or a PL/I elementary item) whose nesting depth is identical to the
nesting level of its XML equivalent and whose memory address at run time can be uniquely identified.
A mapping is nonisomorphic if it does not meet the conditions stated above.
Note: Note that an isomorphic mapping can exist between isomorphic subsets of otherwise
nonisomorphic structures.
For examples of isomorphic and nonisomorphic mapping see “XML to COBOL mapping reference” on page
337.

Isomorphic and nonisomorphic simple mapping

An isomorphic simple mapping is a simple mapping in which an XML element and its corresponding
high-level-language data item (COBOL or PL/I) have the following characteristics:
• Their parent structures (an XML document and a COBOL group or a PL/I item) are identical in shape
(isomorphic).
• Their locations within their parent structures are the same.
A nonisomorphic simple mapping is a simple mapping in which an XML element and its corresponding
high-level-language data item (COBOL or PL/I) are not identical in shape (nonisomorphic).

Related concepts

“Mapping concepts: XML to COBOL or PL/I” on page 281

Related reference
“XML to COBOL mapping reference” on page 337

288 Developer for z/OS: Developing with Db2, CICS, and IMS
Mapping COBOL tables to repeatable XML data structures
This topic describes how COBOL tables are mapped to repeatable XML data structures.
This topic describes which types of mappings the COBOL to XML mapping tools allow you to make
between COBOL tables and repeatable XML Schema elements, for both request mappings (mapping a
repeatable XML Schema element to a COBOL table) and response mappings (mapping a COBOL table to
a repeatable XML Schema element). This topic also describes how these mappings are handled by the
runtime environment.
Note: This topic describes only XML Schema elements (typically occurring in a file ending with the
extension .xsd) but similar rules apply also to mapped XML elements that occur in XML instance
documents (extension .xml) and in WSDL documents (extension .wsdl) (see “Mapping concepts: XML to
COBOL or PL/I” on page 281).

Common rules for request and response mappings

A "repeatable XML Schema element" is an XML Schema item that has the maxOccurs attribute either set
to an integer value that is >= 1 or else set to unbounded.
A COBOL table is a COBOL elementary item or group item that includes in its data description either
an OCCURS clause (creating a fixed-length table) or an OCCURS DEPENDING ON clause (creating a
variable-length table). In IBM online help, "ODO" is an abbreviation for OCCURS DEPENDING ON.
Note: The EST tooling environment validates a mapping between a repeatable XML Schema element and
a corresponding COBOL table only when you create the mapping in one of the COBOL to XML mapping
tools. If you create a valid mapping in the mapping tool and then later modify the repeatable XML
Schema element or the corresponding COBOL table so that the mapping is no longer valid, the EST tooling
environment does not display an error message, and result of the mapping at run time is unpredictable.
Tip: Therefore, if you modify a mapped XML Schema element or if you modify the corresponding COBOL
table, you should verify that the mapping is still valid, or else recreate the mapping in one of the XML to
COBOL mapping tools.
The COBOL to XML mapping tools enforce the following rules for both request mappings and response
mappings:
• A repeatable XML Schema element and the corresponding COBOL table occurrence (analogous to an
array element) must have structures that are isomorphic. Otherwise, the mapping tool does not permit
the mapping.
Note: Isomorphic means that the two structures contain subelements that have the same data types
and that occur in the same order (see “Isomorphic and nonisomorphic simple mapping” on page 288).
Thus if the COBOL table occurrence is MY-USER-ENTRY and the corresponding repeatable XML Schema
element is MyUserEntry, then MY-USER-ENTRY and MyUserEntry must be isomorphic.
• If the COBOL table is a variable-length table (that is, if the table's data description contains an OCCURS
DEPENDING ON clause), then the mapping tools enforce the following rules:
– In addition to mapping the repeatable XML Schema element to the corresponding COBOL table, then
you must also create an XML to COBOL mapping between the COBOL item that is the object of the
ODO clause and its corresponding XML Schema element (for a description of the object of the ODO
clause, see the appropriate COBOL documentation for the OCCURS DEPENDING ON clause).
Thus if the object of the ODO clause is NUM-USER-ENTRIES, then you must create a mapping
between the COBOL item NUM-USER-ENTRIES and a corresponding XML Schema element (such as
an element named NumUserEntries).
– In the .xsd file, the XML Schema element that corresponds to the COBOL item that is the object of the
ODO clause must occur before the repeatable XML Schema element that corresponds to the COBOL
table.

Developing web services and SOA with Enterprise Service Tools 289
 Thus if the COBOL table is named USER-ENTRIES and the object of its ODO clause is the item
NUM-USER-ENTRIES, then the XML Schema element that you map to NUM-USER-ENTRIES must
appear in the .xsd file before the XML Schema element that you map to USER-ENTRIES.
Note: The rules for variable-length tables are necessary because of some of the requirements that
COBOL imposes on defining data.
• For multidimensional arrays (also referred to as "nested tables" in COBOL documentation), the XML to
COBOL mapping tools enforce the following rules:
– A repeatable XML Schema element that contains a multidimensional array and the corresponding
COBOL nested table to which you are seeking to map the repeated XML Schema element must have
the same number of array dimensions.
– Each array dimension in the XML Schema data structure must contain the same number of elements
as the corresponding array dimension in the COBOL nested table, and the elements in each
dimension must be isomorphic.
– A mapping between a single dimension of a multidimensional array in an XML Schema element and a
single dimension of a COBOL nested table is not permitted.

Assumptions as to the number of instances

To determine whether a mapping is valid, the XML to COBOL mapping tools make certain assumptions
about the maximum number of instances that can occur for a repeatable XML Schema element or for an
item in a COBOL table.
Note: These same assumptions are made by a single-service wizard when it is defining data areas within
a generated conversion program (either XML to COBOL or COBOL to XML).
The assumptions are as follows:
• For an repeatable XML Schema element, the maximum number of repetitions of the element that can
occur is the integer value stated in the maxOccurs attribute of the element. However, if the maxOccurs
attribute is set to unbounded, then special rules apply (see the remaining sections in this help topic).
• For a fixed-length COBOL table, the maximum number of occurrences of an item that the table can
contain is the value stated in the OCCURS clause. For a variable-length COBOL table, the maximum
number of occurrences of an item that the table can contain is the maximum value stated in the
OCCURS DEPENDING ON clause.

Policy
In determining whether a mapping between a repeatable XML Schema element and a COBOL table is
valid, Enterprise Service Tools implements the following policy:
• The mapping tools are flexible in allowing you to map together two items that potentially can contain
different numbers of elements at run time.
For example, the mapping tools allow you to map a repeatable XML Schema element that can repeat as
many as 30 times to a COBOL table that can contain a maximum of only 20 elements. (This examples
assume that the XML Schema element is isomorphic with the COBOL table item and that the mapping is
otherwise valid).
• At run time, the generated conversion program checks for an inequality between the actual number of
repetitions of the XML Schema element and the actual number of elements that the COBOL table can
contain.
If the conversion program determines that the data cannot be converted (either from XML Schema to
COBOL or from COBOL to XML Schema) because the source data contains more elements than are
available in the target data structure, then at that time the conversion program returns an error code to
the calling program.

290 Developer for z/OS: Developing with Db2, CICS, and IMS
 Mapping request data
Table 45 on page 291 shows which types of mappings the COBOL to XML mapping tools allow you to
make for request data, and also describes how these mappings are handled by the runtime environment.
In this scenario, at run time, the conversion program wants to convert the data contained in the actual
number of repetitions of the repeatable XML Schema element into items in the actual COBOL table.

Table 45. COBOL to XML Mapping Request Data

Maximum possible
number of Does the mapping
repetitions (See tool permit the
Source data area: Target data area: Note) mapping? Runtime results:
Repeatable XML COBOL table LESS THAN OR The mapping is The XML Schema
Schema element, EQUAL TO. permitted. data is converted
with maxOccurs set into occurrences in
• Example: The XML
to an integer value. the COBOL table.
schema element
can repeat up to
20 times, whereas
the COBOL table
can contain up to
30 elements (20
<= 30).

Repeatable XML COBOL table GREATER THAN. The mapping is not • Normally, the XML
Schema element, permitted. Schema data is
• Example: The XML
with maxOccurs set converted into
schema element
to an integer value. occurrences in the
can repeat up to
50 times, whereas COBOL table.
the COBOL table • But if there are
can contain only more repetitions
up to 30 elements of the XML
(50 > 30). Schema element
than there are
available slots in
the COBOL table,
then an error is
generated at run
time.

Repeatable XML COBOL table The XML Schema The mapping is • Normally, the XML
Schema element, element can repeat permitted. Schema data is
with maxOccurs= any number of converted into
unbounded times, whereas occurrences in the
the COBOL table COBOL table.
has a finite
• But if there are
maximum number of
more repetitions
occurrences.
of the XML
• Example: The XML Schema element
schema element than there are
has maxOccurs= available slots in
unbounded, the COBOL table,
whereas the then an error is
COBOL table can generated at run
contain only up to time.
30 elements.

Developing web services and SOA with Enterprise Service Tools 291
Table 45. COBOL to XML Mapping Request Data (continued)
Maximum possible
number of Does the mapping
repetitions (See tool permit the
Source data area: Target data area: Note) mapping? Runtime results:

Note: When you attempt to do the mapping in the mapping tool, is the maximum possible number of
repetitions of the repeatable XML Schema element LESS THAN OR EQUAL TO the maximum possible number
of items in the COBOL table?

Mapping response data

Table 46 on page 292 shows which types of mappings the COBOL to XML mapping tools allow you
to make for response data, and also describes how these mappings are handled by the run time
environment. In this scenario, at run time, the conversion program wants to convert the data contained in
the actual number of COBOL table items into actual repetitions of the repeatable XML Schema element.

Table 46. COBOL to XML Mapping Response Data

Maximum possible
number of Does the mapping
repetitions (See tool permit the
Source data area: Target data area: Note) mapping? Runtime results:
COBOL table Repeatable XML LESS THAN OR The mapping is The occurrences in
Schema element, EQUAL TO. permitted. the COBOL table
with maxOccurs set are converted into
• Example: The
to an integer value. repetitions of the
COBOL table can
repeatable XML
contain up to
Schema element.
30 elements,
whereas the XML
schema element
can repeat up to
50 times (30 <=
50).

COBOL table Repeatable XML GREATER THAN. The mapping is not • Normally, the
Schema element, permitted. occurrences in
• Example: The
with maxOccurs set the COBOL table
COBOL table
to an integer value. are converted into
can contain up
to 30 element, repetitions of the
whereas the XML repeatable XML
schema element Schema element.
can repeat only up • But if there are
to 20 times ( 30 > more occurrences
20). in the COBOL
table than there
are allowed
repetitions of
the XML Schema
element, then an
error is generated
at run time.

292 Developer for z/OS: Developing with Db2, CICS, and IMS
Table 46. COBOL to XML Mapping Response Data (continued)
Maximum possible
number of Does the mapping
repetitions (See tool permit the
Source data area: Target data area: Note) mapping? Runtime results:
COBOL table Repeatable XML The COBOL table The mapping is • The occurrences in
Schema element, has a finite permitted. the COBOL table
with maxOccurs= maximum number are converted into
unbounded of occurrences, repetitions of the
whereas the XML repeatable XML
Schema element Schema element.
can repeat any
number of times.
• Example: The
COBOL table can
contain up to
30 elements,
whereas the XML
schema element
has maxOccurs=
unbounded.

Note: When you attempt to do the mapping in the mapping tool, is the maximum possible number of items in
the COBOL table LESS THAN OR EQUAL TO the maximum possible number of repetitions of the repeatable XML
Schema element?

Automatic group mapping

This topic describes the automatic group mapping feature of the mapping editor.

Automatic group mapping is a feature of the mapping editor that automatically creates mappings between
the members of a user-defined XML complex type and the members of a compatible high-level-language
structure (COBOL or PL/I).
This feature is available with both request mapping files and with response mapping files. To create an
automatic group mapping:
1. Select the XML complex type on one side of the mapping editor.
2. Select a compatible high-level-language element (COBOL or PL/I) on the other side of the mapping
editor.
3. Click the Map the matching elements icon on the mapping editor toolbar.
The mapping editor creates a mapping (that is, a Move transform) between each member of the XML
complex type and the corresponding member of the compatible high-level-language structure.
Note: This feature is not available if the high-level-language data structure contains any element that
already has a mapping.

COBOL data structure

With COBOL data, the data structure must be a COBOL group that is structurally compatible with the XML
complex type. The COBOL group is considered to be structurally compatible if the following conditions are
met:
1. The XML instance document and the COBOL language structure it is being mapped to meet the
following requirements:

Developing web services and SOA with Enterprise Service Tools 293
 a. A composed element is an element containing other elements. Each composed element of the XML
instance document starting from the root has one and only one corresponding COBOL group item
whose nesting depth is identical to the nesting depth of its XML equivalent.
b. A non-composed element is an element that does not contain other elements. Each non-composed
element in the XML instance document starting from the top has one and only one corresponding
COBOL elementary item whose nesting depth is identical to the nesting level of its XML equivalent
and whose memory address at run time can be uniquely identified.
c. For the request mapping, the innermost complex type contains at least one simple type compatible
in type with that of its COBOL mapped item.
d. For the response mapping, every XML complex type must contain the same number of simple types
compatible with that of their COBOL mapped items.
2. The mapped COBOL group does not contain subordinate redefining items. (The mapped group itself
can be a redefining item)
3. The mapped COBOL group does not contain OCCURS DEPENDING ON constructs.

Related concepts

“Mapping concepts: XML to COBOL or PL/I” on page 281

Related reference
“XML to COBOL mapping reference” on page 337

Top-level objects in the mapping editor

This topic describes the top-level objects displayed in the mapping editor.
On the XML side of the mapping editor, the top-level object displayed is an XML element associated with
the source or target XML document.
On the language side, the top-level object is the COBOL or PL/I language structure that you selected in the
Create Mappings wizard.

Mapping XML model group elements

Except for the disjunction (choice) restraint, an XML model group element is mapped without regard to
any specified constraint.

For example, in the case of a sequence constraint, the generated code does not perform any validation on
whether XML elements that are part of a sequence arrive in the request converter in the order specified by
the XML schema's sequence constraint.
In the mapping editor you can map XML elements that are part of the disjunction (choice) group to
COBOL or PL/I items just as you can with other XML elements. The mapping editor user interface provides
facilities to select a specific choice element.
Related concepts

“Mapping concepts: XML to COBOL or PL/I” on page 281

Related reference
“XML to COBOL mapping reference” on page 337

Generate COBOL Mapping

This topic describes the ability to generate a COBOL copybook and mapping files from a WSDL file without
having to start the batch processor.

294 Developer for z/OS: Developing with Db2, CICS, and IMS
The ability to generate a COBOL copybook and related mapping files locally can be accomplished by using
the Generate COBOL Mapping action on any available WSDL file. When run, the action invokes WSDL2ELS
on the selected WSDL file with all default settings specified.

Selecting a WSDL file

To begin, identify a WSDL file to be used to generate the COBOL mapping.
1. Right-click any available local WSDL file from the workspace and select Generate COBOL Mapping
from the menu.
Note: The Generate COBOL Mapping action is not available within the Enterprise Service Tools
perspective.
2. Choose either one of the following actions:
• Service Provider: Input: XML2LS | Output: LS2XML
• Service Requester: Input: LS2XML| Output: XML2LS
The choice of Service Provider versus Service Requester affects the direction of the mapping
After selecting one of the actions, code generation will begin immediately. Once code generation has
completed, a folder is created with the same name and location of the WSDL file. Within the generated
folder, you will find the following artifacts for all operations within the first WSDL service and port that
WSDL2ELS identifies within the WSDL file:
• Mapping: a directory that contains all of the generated mapping session files.
• WSDLfileName.cpy: A COBOL copybook that contains 01 level structures for the input and output
message of each operation.
• WSDLfileName.log: The WSDL2ELS log file.
• WSDLfileName.meta.xml: The WSDL2ELS metadata file; this file can be programmatically consumed
by user-written code to generate other artifacts.
Related concepts
“Generating a conversion program from mapping session files” on page 295
“Mapping concepts: XML to COBOL or PL/I” on page 281
Related reference
“WSDL2ELSSpec” on page 492
“The batch processor” on page 176

Generating a conversion program from mapping session files

This topic describes the conversion program created by the Generate Conversion Code wizard.

The Generate Conversion Code wizard takes either one or two mapping files as input and creates the
following files as output:
• A COBOL or PL/I source code file
• A WSBind file
• A log file
The generated COBOL or PL/I source code file contains a program for converting data from XML format to
an equivalent high-level-language data structure, and also for converting data from a (possibly different)
high-level-language data structure to an equivalent XML format. This program has three main procedures:
• A primary procedure receives conversion requests, calls one of the other procedures to perform the
actual conversion, and returns the reformatted data.

Developing web services and SOA with Enterprise Service Tools 295
 • Two procedures perform the data format conversions. Each procedure implements the conversion that
was described in one of the two input mapping files. Thus:
– One procedure converts data (for example, a customer ID and a request for information about the
customer) from XML format to a high-level-language data structure (COBOL or PL/I).
– Another procedure converts data (for example, detailed customer information) from a high-level-
language data structure (COBOL or PL/I) to XML format.
These conversion procedures can be used to enable a Web service provider or requester to invoke and get
data from an existing CICS application. For example, in the case of a Web service provider:
1. The Web service receives a request in XML format for information about a particular customer ID.
2. The Web service calls the conversion program to the convert the request from XML format to the
high-level-language format expected by the existing CICS application.
3. The Web service calls the CICS application, passing it the request.
4. The CICS application returns with the requested information in a high-level-language data structure.
5. The Web service calls the conversion program to convert the customer information to XML format.
6. The Web service returns the customer information to the remote caller.

Related concepts
“Mapping concepts: XML to COBOL or PL/I” on page 281

Related reference
“XML to COBOL mapping reference” on page 337

Mapping XML attributes to COBOL with Compiled XML Conversion

This topic describes certain limitations and features that apply when XML attributes are mapped to
COBOL data structures with compiled XML conversion in the meet-in-middle scenario.
The information in this topic applies only to XML to COBOL mapping of XML attributes (not XML to PL/I)
and applies whenever the development scenario is meet-in-middle and the conversion type is Compiled
XML Conversion.
The following limitations and features apply:
1. XML attributes contained by repeating leaf XML elements cannot be mapped to nonrepeating
elementary language structure members.
2. XML attributes contained by repeating, leaf XML elements, can be mapped to elementary language
structure members that are contained by a group with equal or greater repetitions.
Note: Dimensions of parent elements and groups must also meet this criteria.
3. XML elements with "mixed" content, mixed="true", are not eligible to be mapped to any language
structure member. For a detailed discussion, refer to “XML attribute support limitation” on page 266.
4. An XML attribute can be mapped to a COBOL ODO (occurs depending on) object only when the
attribute is contained by an XML element that appears before the XML element that is mapped to the
corresponding COBOL ODO subject.

296 Developer for z/OS: Developing with Db2, CICS, and IMS
Working with annotations
This group of topics describes issues involved in working with annotations.

Using source annotations to specify service interface

This topic describes how Enterprise Service Tools users can annotate data definitions to provide service
interface information and customization.
This describes how users of the Enterprise Service Tools can annotate COBOL data definitions to
provide service interface information and customization similar to information and customization in the
batch processor options files. This function is available to the batch processor tools for the "bottom-
up" scenario of developing new service interfaces from COBOL applications utilizing Compiled XML
conversion.
Note: This capability is available through the batch processor configuration files only and only for COBOL
sources.
More specifically, the annotations function provides the capability currently provided by
“ItemExclusionArray” on page 462, “ItemSelectionArray” on page 464, and “XMLNamesArray” on
page 503 elements of the batch processor options files, they allow the user to explicitly exclude
(“ItemExclusionArray” on page 462), include (“ItemSelectionArray” on page 464) and rename
(“XMLNamesArray” on page 503) the desired items in the generated service interface.
Using the example in Figure 9 on page 297. The service creator may want to exclude the "salary" item
and rename the "first-name" to "FirstName" in the service reply. In order to achieve this using the
batch processor option files (“ItemExclusionArray” on page 462, “ItemSelectionArray” on page 464, and
“XMLNamesArray” on page 503 elements) , the service creator needs to input the fragment shown in
Figure 10 on page 297 in the ServiceSpecification.xml.

LINKAGE SECTION.
1 department.
2 member-count pic 9(9) binary.
2 member-details occurs 5 times.
3 first-name pic x(35).
3 last-name pic x(45).
3 contact-phone pic x(25).
3 contact-address pic x(75).
3 promotion-level pic x(20).
3 last-promotion-date pic x(10).
3 salary pic x(3).

Figure 9. Example of COBOL Data Structure for Excluding and Changing Information

<OutputMessage importFile="samp.cpy" importDirectory="C:/Source" nativeTypeName="department">

<ItemExclusionArray>
<ExcludeItem itemName="department.member-details.salary"/>
</ItemExclusionArray>
<XMLNamesArray>
<XMLNameSelection itemName="first-name" XmlName="FirstName"/>
</XMLNamesArray>
</OutputMessage>

Figure 10. Example of Excluding and Changing Information with Option File Elements

Annotating the data structure source allows the users to specify similar type of information directly in the
source of the data declaration rather than in an batch processor option configuration file. This method
keeps the service interface specification and the actual interface in a single source file.

Developing web services and SOA with Enterprise Service Tools 297
 Using the example in Figure 9 on page 297 as a reference, the user can obtain the same results by
including the sample annotations in the source file with the data description, as shown in Figure 11 on
page 298.

@ANN *OMIT salary

@ANN *OLDNAME first-name
@ANN *NEWAME FirstName
@ANN *OPTIONAL FirstName

LINKAGE SECTION.
1 department.
2 member-count pic 9(9) binary.
2 member-details occurs 5 times.
3 first-name pic x(35).
3 last-name pic x(45).
3 contact-phone pic x(25).
3 contact-address pic x(75).
3 promotion-level pic x(20).
3 last-promotion-date pic x(10).
3 salary pic x(3).

Note: The annotations @ANN *OMIT, @ANN *OLDNAME, @ANN *NEWNAMEand @ANN *OPTIONAL
are samples, both the annotation indicator (@ANN) and annotation actions (OMIT, OLDNAME, NEWNAME
and OPTIONAL) are examples for this description. The annotation indicator and annotation action can be
customized to support local/individual requirements.
Figure 11. Example of COBOL Data Structure with Source Annotation Information (See Note)

Annotations for COBOL source files

This topic describes using annotations for COBOL source files.
The annotations in the source files have the following main components:
• Comment indicator
• Annotation indicator
• Annotation content
Note: For different languages the order of the components may vary. For example, when using COBOL,
the comment indicator, may follow the annotation indicator. This topic uses COBOL as source language for
data definition.
In order for the annotations to be ignored by the COBOL compiler, the annotations have to appear as a
comment line. Therefore, COBOL annotations always have an asterisk (*) in column 7 to indicate a COBOL
comment.
The format of the annotation indicator for COBOL annotations have an optional eye-catching format. In
this description, an @ ("at" sign) is used. However, any other character can be defined as the annotation
indicator. The annotation indicator is positioned in column 1 followed by up to 5 alphanumeric characters.
The format of the annotation content is as follows:
1. Action name
2. Data name that the Action name applies to.
To enable the annotation capability, the user has to create a synonym action XML file. The synonym action
XML file is an XML file that defines a set of annotation words that are equivalent, in meaning to the
actions already provided by the “ItemExclusionArray” on page 462,, “ItemSelectionArray” on page 464,
and “XMLNamesArray” on page 503 elements of the batch processor options file.

298 Developer for z/OS: Developing with Db2, CICS, and IMS
The user specifies (creates) the synonym action XML file on the command line when invoking the Batch
processor (xsebatch). The comand is: xsebatch [-annot synFile]. For a complete description of the
xsebatch command, see “Starting the batch processor” on page 413.
If the synonym action XML file is specified in this way, the annotation rules specified in the synonym
action XML file apply to all Batch processor specification files (and therefore all subsequent services)
generated in that particular invocation.
User can override (i.e., change) the synonym action XML file specified on the command line by using the
"annotationsFile" attribute for input and output message elements (InputMessage and OutputMessage) in
the Batch processor option specification file (ServiceSpecification.xml), see “InputMessage” on page 457
and “OutputMessage” on page 473.
When the command line method is used to create and specify the synonym action XML file, the Batch
processor ignores the “ItemExclusionArray” on page 462,, “ItemSelectionArray” on page 464, and
“XMLNamesArray” on page 503 elements of the batch processor options files and instead looks for the
source data annotations that are defined in the synonym action XML file.
Figure 12 on page 299 an example of a synonym action XML file that can be used to direct the processor
to use the indicated annotations present in the COBOL source language sample.

<?xml version="1.0" encoding="UTF-8"?>

<synactions:SynonymActions xmlns:synactions="http://www.ibm.com/xmlent/annot/emf/synactions">
<synactions:ActionGroup lang="COBOL" format="fixed" indicator="@ANN">
<synactions:ExcludeItem>
<synactions:itemName annotatedAs="OMIT"/>
</synactions:ExcludeItem>
<synactions:ItemSelection>
<synactions:itemName annotatedAs="KEEP"/>
<synactions:optional annotatedAs="OPTIONAL"/>
</synactions:ItemSelection>
<synactions:XMLNameSelection>
<synactions:itemName annotatedAs="OLDNAME"/>
<synactions:xmlName annotatedAs="NEWNAME"/>
</synactions:XMLNameSelection>
</synactions:ActionGroup>
</synactions:SynonymActions>

Figure 12. Example of Synonym Action XML File

Figure 13 on page 300 is the XML Schema for the Synonym action XML file.

Developing web services and SOA with Enterprise Service Tools 299
 <?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soannot="http://www.ibm.com/xmlent/annot/emf/synactions"
targetNamespace="http://www.ibm.com/xmlent/annot/emf/synactions">
<xsd:element name="itemName">
<xsd:complexType>
<xsd:attribute use="required" name="annotatedAs" type="xsd:string"/>
</xsd:complexType>
</xsd:element>
<xsd:element name="ExcludeItem">
<xsd:complexType>
<xsd:sequence>
<xsd:element minOccurs="1" maxOccurs="1" ref="soannot:itemName"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="XMLNameSelection">
<xsd:complexType>
<xsd:sequence>
<xsd:element minOccurs="1" maxOccurs="1" ref="soannot:itemName"/>
<xsd:element minOccurs="1" maxOccurs="1" ref="soannot:xmlName"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="ItemSelection">
<xsd:complexType>
<xsd:sequence>
<xsd:element minOccurs="1" maxOccurs="1" ref="soannot:itemName"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="ActionGroup">
<xsd:complexType>
<xsd:sequence>
<xsd:element minOccurs="1" maxOccurs="1" ref="soannot:ExcludeItem"/>
<xsd:element minOccurs="1" maxOccurs="1" ref="soannot:ItemSelection"/>
<xsd:element minOccurs="1" maxOccurs="1" ref="soannot:XMLNameSelection"/>
</xsd:sequence>
<xsd:attribute use="required" name="indicator" type="xsd:string"/>
<xsd:attribute use="optional" name="lang" type="xsd:string"/>
<xsd:attribute use="optional" name="format" type="xsd:string"/>
</xsd:complexType>
</xsd:element>
<xsd:element name="xmlName">
<xsd:complexType>
<xsd:attribute use="required" name="annotatedAs" type="xsd:string"/>
</xsd:complexType>
</xsd:element>
<xsd:element name="SynonymActions">
<xsd:complexType>
<xsd:sequence>
<xsd:element minOccurs="1" maxOccurs="1" ref="soannot:ActionGroup"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:schema>

Figure 13. Synonym Action XML File Schema

Rules and conditions for synonym action files

• Content of the synonym action file must match the schema specified. If it does not, the behavior of the
Batch processor is unpredictable.
• If synonym action file is specified on the command line and there are synonym action files that are
also specified on the annotationsFile attribute, the –annot file from the command line is overridden
by annotation synonyms from the file(s) specified with the annotationsFile attribute. This means that
the annotations specified by the annotationsFile attribute has precedence/priority over the annotations
specified by the command line.

300 Developer for z/OS: Developing with Db2, CICS, and IMS
• If the synonym action file or files are specified (on the command line and/or in the Batch processor
options file) but they do not actually exist, the Batch processor issues a warning and proceeds by
ignoring the specified file.
• Annotations which are not listed in the synonym action file are ignored.
• If the synonym action file is specified on the command line, all occurrences of “ItemExclusionArray”
on page 462,, “ItemSelectionArray” on page 464, and “XMLNamesArray” on page 503 in the batch
processor options files are ignored.
• If the synonym action file is specified on the "annotationsFile" attribute for input and output message
elements , all occurrences of (“ItemExclusionArray” on page 462,, “ItemSelectionArray” on page
464, and “XMLNamesArray” on page 503 in that message specification element (InputMessage or
OutputMessage) are ignored.
• If the synonym action file is specified on the command line or on the "annotationsFile" attribute but no
annotations are found in the source file, an informational message is issued

Rules and conditions for annotating data declarations

• The ampersand sign (&) is reserved and cannot be used as the first character in the annotation
indicator.
• Use and behavior of annotations in the Batch processor is equivalent to the corresponding elements
(“ItemExclusionArray” on page 462, “ItemSelectionArray” on page 464, and “XMLNamesArray” on
page 503) whose meaning the annotations are replacing.
• Except for the required comment indicator ("*" in COBOL) and the reserved & (ampersand sign),
annotations can contain alphanumeric characters valid for the COBOL name set per COBOL standard
and, in the case of annotations that correspond to "xmlName", valid XML names per XML standard.
• All annotations are processed starting at the beginning of the source file, up to but not including either :
– the very first PROCEDURE DIVISION statement. (If the source file does not contain a PROCEDURE
DIVISION, all annotations in the source are processed)
or
– the next available level 01 group after the level 01 group selected for the interface in a particular
message specification.
• For COBOL, the annotation must be specified with the comment indicator in column 7.
• Annotation for a single action word cannot span multiple source lines.
• For COBOL, the source file must be in fixed-format 80-column source COBOL records (per COBOL
specification)
• Annotations specified for "itemName" and "xmlName" of the XMLNameSelection must appear on
consecutive lines. That is, annotation that corresponds to "itemName" must be followed on the next
line by the one corresponding to "xmlName". If this condition is not met, an error message is issued and
the annotation is ignored.
• COBOL COPY statements are not expanded by the annotation processor. This means that annotations
contained within nested copybooks are ignored.
• Care should be taken when supplying the synonym action file for a COBOL source containing pre-
existing content in the indicator area. Some of the pre-existing indicator area content may conflict with
the annotations specified in the synonym actions. Behavior of the annotation processor is unpredictable
in such situations.
• The following are additional rules and conditions when annotations that designate data items as
"optional" are used:
1. COBOL item annotated as "optional" must implicitly or explicitly be included in the interface. In other
words, the COBOL item annotated as "optional" must not be listed on the “ItemExclude” on page
460 parameter. If the COBOL item is listed on the “ItemExclude” on page 460 parameter, a warning
message is issued and the "optional" annotation is ignored.

Developing web services and SOA with Enterprise Service Tools 301
 2. If the annotation that designates a data item as "optional" has a value that does not correspond to a
valid COBOL item name, a warning message is issued.
3. If the COBOL item corresponding to the "optional" parameter is also being renamed by the
“XMLNameSelection” on page 504`element, the "optional" parameter must list the new name for
the COBOL element. If this is not performed, then rule #2 takes effect.
4. Annotations that designate data items as "optional" can appear in any order among other
annotations.
5. Annotations that designate data items as "optional" affect only the generated XML Schemas and not
the generated COBOL converters or the messages that are processed or generated by the converters.
6. Annotations that designate data items as "optional" only apply to the Compiled conversion
scenarios. Optional annotations in the Interpretive conversion scenarios are ignored.
7. Only group items and elementary items (other than Level 01, 77, and 88) can be annotated as
"optional". Annotations are ignored if specified for unsupported items.
8. COBOL items annotated as "optional" can have an OCCURS clause; minOccurs facet for these items
are overwritten and set to 0 instead of the value normally derived from the OCCURS clause.
9. Item names in optional annotations are not case sensitive.

Working with data structures

This group of topics describes issues involved in working with data structures.

Commonly Used Elements and Types

This topic describes how Enterprise Service Tools users can include and reference commonly used
interface elements (which are derived from COBOL copybooks) using standard XSD and WSDL inclusion
mechanisms.

Including and Referencing Commonly Used Elements and Types

Note: This feature applies to the EST Batch processor tools for the "bottom-up" scenario of developing
new service interfaces from COBOL applications utilizing "Compiled XML conversion" technology. It is
available through the Batch processor configuration files only and only for COBOL sources. The generators
used in the Batch generation process must have access to the copybooks referenced in the COBOL
source.
It is common in COBOL application development to create reusable sequences of code by putting them
into “COPY” files (COPY books) and achieve re-use by including the same COPY book in multiple source
files (via the COBOL COPY statement).
Figure 14 on page 302 is a example of a typical sequence of code to re-use is data definition that repeats
in multiple data structures. In this example, the two data definitions re-use the same COPY book named
COMMHDR.

01 departmentUpdateRequest.
COPY COMMHDR.
COPY DEPTBDY.

01 departmentUpdateReply.
COPY COMMHDR.
02 updStatus pic xxx.

Figure 14. Example of COBOL Reuse of Data Definition Element

302 Developer for z/OS: Developing with Db2, CICS, and IMS
Figure 15 on page 303 and Figure 16 on page 303 show of the content of the COMMHDR copybook and
DEPTBDY copybook.

05 commHeader.
10 commId PIC 9(4).
10 commRevDate PIC X(8).
10 commDigest PIC X(40).

Figure 15. Example of COMMHDR Copy Book

2 member-count pic 9(9) binary.

2 dept-details.
3 dept-title pic x(35).
3 dept-id pic x(45).
3 dept-seq pic 9(4).
3 dept-hq pic x(75).

Figure 16. Example of DEPTBDY Copy Book

Background for Including and Referencing Commonly Used Elements and Types
Prior to IBM Developer for z Systems Version 7.5, service interfaces generated from data structures
that referenced COPY books required that complete XML schemas (XSDs) be generated for each data
structure.
When using the input shown in Figure 14 on page 302, previous versions of the Enterprise Service Tools
wizards generated the output shown in Figure 17 on page 304 (departmentUpdateRequest), and Figure
18 on page 305 (departmentUpdateReply).
Note: For documentation purposes, only the partial schema is displayed.

Developing web services and SOA with Enterprise Service Tools 303
 <schema ...
targetNamespace="http://www.TST01I.com/schemas/TST01IInterface"
xmlns="http://www.w3.org/2001/XMLSchema"
xmlns:cbl="http://www.TST01I.com/schemas/TST01IInterface">

<complexType name="departmentUpdateRequest">
<sequence>
<element name="commHeader"
type="cbl:departmentupdaterequest_commheader"/>
<element form="qualified" name="member_count">
<simpleType>
...
</simpleType>
</element>
<element name="dept_details"
type="cbl:departmentupdaterequest_dept__details"/>
</sequence>
</complexType>
<complexType name="departmentupdaterequest_commheader">
<sequence>
<element form="qualified" name="commId">
<simpleType>
...
</simpleType>
</element>
<element form="qualified" name="commRevDate">
<simpleType>
...
</simpleType>
</element>
<element form="qualified" name="commDigest">
<simpleType>
...
</simpleType>
</element>
</sequence>
</complexType>
<complexType name="departmentupdaterequest_dept__details">
<sequence>
...
</sequence>
</complexType>
<element name="departmentUpdateRequest" type="cbl:departmentUpdateRequest">
</schema>

Figure 17. Example of Part of Schema Generated for WSDL Interface Type for departmentUpdateRequest

304 Developer for z/OS: Developing with Db2, CICS, and IMS
 <schema attributeFormDefault="qualified"
elementFormDefault="qualified"
targetNamespace="http://www.TST01O.com/schemas/TST01OInterface"
xmlns="http://www.w3.org/2001/XMLSchema"
xmlns:cbl="http://www.TST01O.com/schemas/TST01OInterface">
<complexType name="departmentUpdateReply">
<sequence>
<element name="commHeader" type="cbl:departmentupdatereply_commheader"/>
<element form="qualified" name="updStatus">
...
</element>
</sequence>
</complexType>
<complexType name="departmentupdatereply_commheader">
<sequence>
<element form="qualified" name="commId">
...
</element>
<element form="qualified" name="commRevDate">
...
</element>
<element form="qualified" name="commDigest">
...
</element>
</sequence>
</complexType>
<element name=" departmentUpdateReply" type="cbl:departmentUpdateReply">
...
</element>
</schema>

Figure 18. Example of Part of Schema Generated for WSDL Interface Type for departmentUpdateReply

As shown in Figure 17 on page 304 and Figure 18 on page 305, the declaration for element commHeader
and for its type are duplicated for both departmentUpdateRequest and for departmentUpdateReply. The
only differences are:
1. The complex type name for each element:
(departmentupdaterequest_commheader. VS. departmentupdatereply_commheader)
and
2. The namespaces for the schemas:
(xmlns:cbl="http://www.TST01I.com/schemas/TST01IInterface. VS. xmlns:cbl="http://
www.TST01O.com/schemas/TST01OInterface) .

Because a single COPY book can be used for multiple services the multiplicity of similarly typed elements
may lead to unnecessary duplication of code generated for the clients from such WSDL or XSD files.
This feature allows users to specify common COPY book and common XSD types and elements that can
be re-used by multiple interfaces without having to have duplicate schema content.

Defining common standard elements and types in generated XSD and WSDL
This topic describes the definition parameters for the feature “Including and Referencing Commonly Used
Elements and Types”.
The common schema content is defined to the xsebatch command line tool through an XML file that
can be specified either on the command line parameter (-commtypes for “Common Types”) or by the
“commTypesFile“ attribute specified in the ServiceSpecification.xml file.
The user can override the commtypes xml file specified with the “commTypesFile“ attribute for input
and output message elements (InputMessage and OutputMessage) in the Batch processor option
specification file (ServiceSpecification.xml).

Developing web services and SOA with Enterprise Service Tools 305
 When the user creates and specifies the commtypes xml file, the WSDL and XSD generation process uses
the information specified in the commtypes file to generate elements, types and schema imports instead
of the imbedded types, elements and namespaces. The list of common types from the command line
parameter can be overridden by the content of the file(s) specified on the commTypesFile attribute.
Table 47 on page 306 is a listing of the elements and attributes of the Common Types Element.

Table 47. Elements and Attributes of the Common Types Element

Element or Attribute Definition
CommTypes Container element for common groups.
CommGroup Group for listing common type information.
lang Specifies the source language of the application
source being processed.
format For source languages that permit fixed or free
source formatting, this attribute must specify
which format is used. Currently this attribute is
reserved and set to "fixed".
CommonType Attributes of this element describe how the
common application source data items should be
processed (see below).
srcName Specifies the source name of the copybook as
it appears in the COBOL application program
source. COPY books specified in the srcName
attribute are not cross-referenced with the COBOL
application source files, but they must be present
and accessible to the Batch processor tool when
the COBOL application source is processed.
nativeName Specifies the COBOL data item name for which the
XML schema reference and type should be taken
from the common schema.
commSchemaLocation Specifies the common schema location attribute
(xsi:schemaLocation) that is generated in the
import statement for the enclosing WSDL or XSD.
Note: For CICS Webservices scenarios this location
must be accessible when the tools are running,
Otherwise an error message are displayed and the
generation process does not complete.

commNamespace Specifies the value of the namespace declaration

that is generated for referring to the common
schema.
xmlElementName Specifies the value of the element name from the
common schema that should be referred to from
the enclosing WSDL or XSD.
commNsPrefix Specifies the value of the namespace prefix that
should be generated to qualify the reference of the
common elements and types.

Figure 19 on page 307 is an example of a commtype xml file used to direct the processor to use common
types, elements, namespaces, in a COBOL source language sample.

306 Developer for z/OS: Developing with Db2, CICS, and IMS
 <?xml version="1.0" encoding="UTF-8"?>
<commtypes:CommonTypes xmlns:commtypes="http://www.ibm.com/xmlent/commxsd/emf/commtypes">
<commtypes:CommGroup lang="COBOL" format="fixed">
<commtypes:CommonType
srcName="COMMHDR"
nativeName="commHeader"
commSchemaLocation="commHeader.xsd"
commNamespace="http://www.sample.com/schemas/commHeader"
xmlElementName="commHeader"
commNsPrefix="hdr1"
/>
</commtypes:CommGroup>
</commtypes:CommonTypes>

Figure 19. Example of a commtype XML File

The commtype xml file schema is shown in Figure 20 on page 307.

<?xml version="1.0" encoding="UTF-8"?>

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:commtypes="http://www.ibm.com/xmlent/commxsd/emf/commtypes"
targetNamespace="http://www.ibm.com/xmlent/commxsd/emf/commtypes">
<xsd:element name="CommGroup">
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="commtypes:CommonType" minOccurs="1" maxOccurs="unbounded"/>
</xsd:sequence>
<xsd:attribute name="lang" type="xsd:string"/>
<xsd:attribute name="format" type="xsd:string"/>
</xsd:complexType>
</xsd:element>
<xsd:element name="CommonTypes">
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="commtypes:CommGroup"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="CommonType">
<xsd:complexType>
<xsd:attribute name="srcName" type="xsd:string"/>
<xsd:attribute name="xmlElementName" type="xsd:string"/>
<xsd:attribute name="nativeName" type="xsd:string"/>
<xsd:attribute name="commSchemaLocation" type="xsd:string"/>
<xsd:attribute name="commNamespace" type="xsd:string"/>
<xsd:attribute name="commNsPrefix" type="xsd:string"/>
</xsd:complexType>
</xsd:element>
</xsd:schema>

Figure 20. A commtype XML File Schema

When the commtype xml file example shown in Figure 19 on page 307 is applied to the sample COBOL
source and copybooks shown in Figure 14 on page 302 in the topic “Commonly Used Elements and
Types” on page 302, then the generated schema for departmentUpdateRequest is shown in Figure 21 on
page 308 and the generated schema for departmentUpdateReply is shown in Figure 22 on page 308.
Note: For documentation purposes, only the partial schema is displayed.
Figure 23 on page 309 shows the commHeader schema.

Developing web services and SOA with Enterprise Service Tools 307
 <schema attributeFormDefault="qualified" elementFormDefault="qualified"
targetNamespace="http://www.TST01I.com/schemas/TST01IInterface"
xmlns="http://www.w3.org/2001/XMLSchema"
xmlns:cbl="http://www.TST01I.com/schemas/TST01IInterface"
xmlns:hdr1="http://www.sample.com/schemas/commHeader">
<import namespace="http://www.sample.com/schemas/commHeader"
schemaLocation="commHeader.xsd"/>
<complexType name="departmentUpdateRequest">
<sequence>
<element ref="hdr1:commHeader"/>
<element form="qualified" name="member_count">
<simpleType>
<restriction base="int">
<minInclusive value="0"/>
<maxInclusive value="999999999"/>
</restriction>
</simpleType>
</element>
<element name="dept_details" type="cbl:departmentupdaterequest_dept__details"/>
</sequence>
</complexType>

Figure 21. Example of Part of Schema Generated for departmentUpdateRequest Element

<schema attributeFormDefault="qualified" elementFormDefault="qualified"

targetNamespace="http://www.TST01O.com/schemas/TST01OInterface"
xmlns="http://www.w3.org/2001/XMLSchema"
xmlns:cbl="http://www.TST01O.com/schemas/TST01OInterface"
xmlns:hdr1="http://www.sample.com/schemas/commHeader">
<import namespace="http://www.sample.com/schemas/commHeader"
schemaLocation="commHeader.xsd"/>
<complexType name="departmentUpdateReply">
<sequence>
<element ref="hdr1:commHeader"/>
<element form="qualified" name="updStatus">
<annotation>
<appinfo source="http://www.wsadie.com/appinfo">
<initialValue kind="SPACE"/>
</appinfo>
</annotation>
<simpleType>
<restriction base="string">
<maxLength value="3"/>
</restriction>
</simpleType>
</element>
</sequence>
</complexType>
<element name="employeeUpdateRequest" type="cbl:departmentUpdateReply">
<annotation>
<documentation source="com.ibm.etools.xmlent.batch">8.0.0.V200803251533</
documentation>
</annotation>
</element>
</schema>

Figure 22. Example of Part of Schema Generated for departmentUpdateReply Element

Figure 23 on page 309 is an example of the schema for the commonHdr.xsd file.

308 Developer for z/OS: Developing with Db2, CICS, and IMS
 <?xml version="1.0" encoding="UTF-8"?><schema attributeFormDefault="qualified"
elementFormDefault="qualified" targetNamespace="http://www.sample.com/schemas/commHeader"
xmlns="http://www.w3.org/2001/XMLSchema" xmlns:cbl="http://www.sample.com/schemas/commHeader">
<complexType name="commheader">
<sequence>
<element name="commId">
<simpleType>
<restriction base="short">
<minInclusive value="0"/>
<maxInclusive value="9999"/>
</restriction>
</simpleType>
</element>
<element name="commRevDate">
<annotation>
<appinfo source="http://www.wsadie.com/appinfo">
<initialValue kind="SPACE"/>
</appinfo>
</annotation>
<simpleType>
<restriction base="string">
<maxLength value="8"/>
</restriction>
</simpleType>
</element>
<element name="commDigest">
<annotation>
<appinfo source="http://www.wsadie.com/appinfo">
<initialValue kind="SPACE"/>
</appinfo>
</annotation>
<simpleType>
<restriction base="string">
<maxLength value="40"/>
</restriction>
</simpleType>
</element>
</sequence>
</complexType>
<element name="commHeader" type="cbl:commheader">
<annotation>
<documentation source="com.ibm.etools.xmlent.batch">8.0.0.V200803251533</documentation>
</annotation>
</element>
</schema>

Figure 23. Example of Schema Generated for commonHdr.xsd File

Rules and Conditions

This topic lists the rules and conditions for the feature “Including and Referencing Commonly Used
Elements and Types”.
The rules and conditions are as follows:
1. Content of the common types XML file must match the schema specified in this document. If it does
not, the behavior of the Batch processor is unpredictable.
2. If common types XML file is specified on the command line and there are common types xml files that
are also specified on the commTypesFile attribute, the common types XML file from the command line
is overridden by the information from the file(s) specified with the commTypesFile attribute
3. If the common types XML file or files are specified (on the command line and/or in the Batch processor
options file) but they do not actually exist, the Batch processor issues a warning and proceeds,
ignoring the specified file(s).
4. If the common types XML file is specified on the commTypesFile attribute for input and output
message elements, common element and type information applies only to the InputMessage or the
OutputMessage for which the commTypesFile attribute is specified.

Developing web services and SOA with Enterprise Service Tools 309
 5. If the common types XML file is specified on the command line or on the commTypesFile attribute but
no items are found in the source file that correspond to any itemName specified in the common types
XML file, a warning message is issued.
6. If common types XML file is specified either on the command line or in the commTypesFile attribute,
and GEN_ELEMENT_FORM_QUALIFIED property of the CodeGenProperty attribute is set to false
(either in the Batch process configuration file or in the GUI preferences for the workspace) the Batch
processor issues a warning and proceeds, ignoring the specified common types XML file(s).

Creation of XML schemas from multiple language structures

This topic introduces multiple-language structure enterprise applications and how the Enterprise Service
Tools component can be used to enable them as Web services.
The Enterprise Service Tools batch processor and single-service project Web service wizards allow
for generation of XML Schemas from collections of language structures. When enabling an enterprise
application as a Web service, it may be that the interface of the application consists of more than one
language structure. In order to expose such an application as a service, in a way that is easily consumable
by a Web client, the tool supports aggregation of multiple language structures into single, composite XML
Schemas for both the request and response message. The process by which this is accomplished depends
on whether the batch processor or the Web service wizard is being used. In general, multiple language
structures are specified in the order their equivalent XML Schema representations should appear in the
composite XML Schema.
An example of a typical application whose interface consists of multiple language structures is an IMS
Message Processing Program or MPP. MPP's typically send and receive messages that consist of multiple
segments. Each segment is an instance of a language structure. For example, an MPP could expect to
receive three segments each being a distinct 01 level language structure: 01 HEADER, 01 BODY, and 01
SUMMARY.
It is also common for multiple instances of a particular 01 level language structure to be present in a
message processed or generated by an MPP. For example, multiple instances of the language structure
01 CUSTOMER-RECORD would be placed one after the other in a response to a query that retrieves
information about more than one customer.
When enabling an IMS MPP as a Web service, the Enterprise Service Tools batch processor and single-
service project Web service wizards generate composite XML Schemas and XML conversion artifacts for
the request and response message of an MPP. The combination of the composite XML Schema and XML
conversion artifacts provides a highly-consumable Web service interface which relieves the client from
having to understand the MPP's complex multisegment runtime message structure.
The ability of the Enterprise Service Tools batch processor to generate composite XML Schemas can be
used independently of generating runtime-specific Web service artifacts. These XML Schemas can then
be used as input to the meet-in-middle or top-down scenarios.
Note: The Enterprise Service Tools mapping editor does not support mapping of multiple language
structures to an XML Schema at this time.
The ability to create XML Schemas from multiple language structures enables Enterprise Service Tools to
support multisegment IMS MPP's in IMS Enterprise Suite SOAP Gateway single-service projects.
Note: Currently, generation of XML Conversion artifacts for multiple language structures is only supported
for IMS Enterprise Suite SOAP Gateway single-service, bottom-up projects.
The following topics give further detail on the specifics of creating XML Schemas and Web service artifacts
for applications whose interface consists of multiple language structures:
• “Specification of multiple request language structures” on page 311
• “Specification of Multiple Response Language Structures” on page 311
• “Generation of composite XML schemas from multiple language structures” on page 312

310 Developer for z/OS: Developing with Db2, CICS, and IMS
Specification of multiple request language structures
If an enterprise applications' input interface is comprised of multiple language structures, it is necessary
to include each of them in the request message that clients will transmit when the application is invoked
as a Web service. To direct the Enterprise Service Tools (EST) Batch processor to incorporate multiple
language structures into the XML Schema (XSD) for the request message—specify multiple, sibling,
InputMessage elements. The order in which the InputMessage elements are specified determines the
order that their equivalent XSD definitions appears in the composite request XSD.
To further customize the request XSD, attributes on the InputMessage element can be specified. These
attributes are:
• xmlEleName - name of the XML element mapped to instances of the language structure
• lowerBound - minimum repetitions of the language structure
• upperBound - maximum repetitions of the language structure
See “InputMessage” on page 457 for the complete description of the InputMessage attributes.
Figure 24 on page 311 demonstrates how to direct the Enterprise Service Tools Batch processor to
incorporate multiple language structures when generating the XSD for the request message of a Web
service.
Note: Generation of XML Conversion artifacts is supported for the IMS Enterprise Suite SOAP Gateway
runtime only when multiple language structures are specified.

<Operation name="PutOrderHistory">
<InputMessage importFile="ORDRSECR.cpy" importDirectory="."
nativeTypeName="ORDRSECR-PUT-HIST-HEAD"
xmlEleName="OrderHistoryHeader" lowerBound="1" upperBound="1">
<ItemSelectionArray>
<ItemSelection itemName="ORDRSECR-PUT-HIST-HEAD.SECURITY-CODE"/>
<ItemSelection itemName="ORDRSECR-PUT-HIST-HEAD.CUSTOMER-ID"/>
<ItemSelection itemName="ORDRSECR-PUT-HIST-HEAD.CUSTOMER-FIRSTNAME"/>
<ItemSelection itemName="ORDRSECR-PUT-HIST-HEAD.CUSTOMER-LASTNAME"/>
</ItemSelectionArray>
</InputMessage>

<InputMessage importFile="ORDRRECS.cpy" importDirectory="."

nativeTypeName="ORDRRECS-HIST-RECORD"
xmlEleName="OrderHistoryRecord" lowerBound="1" upperBound="255">
<ItemSelectionArray>
<ItemSelection itemName="ORDRRECS-HIST-RECORD.ORDER-DATE"/>
<ItemSelection itemName="ORDRRECS-HIST-RECORD.ORDER-ITEM-ID"/>
<ItemSelection itemName="ORDRRECS-HIST-RECORD.ORDER-ITEM-PRICE"/>
<ItemSelection itemName="ORDRRECS-HIST-RECORD.ORDER-ITEM-QTY"/>
<ItemSelection itemName="ORDRRECS-HIST-RECORD.ORDER-ITEM-DESC"/>
</ItemSelectionArray>
</InputMessage>
<OutputMessage ../>
<XseSpec>
<XsdSpecIn xsdEleName="PutOrderHistoryRequest"
targetNamespace="http://www.ibm.com/schemas/weborders"
fileName="PutOrderHistory.xsd"/>
<XsdSpecOut ../>
</XseSpec>
</Operation>

Figure 24. Example of Specifying Multiple Language Structures for the Request Message

Specification of Multiple Response Language Structures

If an enterprise applications' output interface is comprised of multiple language structures, it is necessary
to include each of them in the response message that clients receive when the application is invoked
as a Web service. To direct the Enterprise Service Tools Batch processor to incorporate multiple
language structures into the XML Schema (XSD) for the response message—specify multiple, sibling,

Developing web services and SOA with Enterprise Service Tools 311
 OutputMessage elements. The order in which the OutputMessage elements are specified determines the
order that their equivalent XSD definitions appears in the composite response XSD.
To further customize the response XSD, attributes on the OutputMessage element can be specified. These
attributes are:
• xmlEleName - name of the XML element mapped to instances of the language structure
• lowerBound - minimum repetitions of the language structure
• upperBound - maximum repetitions of the language structure
See “OutputMessage” on page 473 for the complete description of the OutputMessage attributes.
Figure 25 on page 312 demonstrates how to direct the Enterprise Service Tools Batch processor to
incorporate multiple language structures when generating the XSD for the response message of a Web
service.
Note: Generation of XML Conversion artifacts is only supported for the IMS SOAP Gateway runtime when
multiple language structures are specified.

<Operation name="GetOrderHistory">
<InputMessage ../>

<OutputMessage importFile="ORDRSECR.cpy" importDirectory="."

nativeTypeName="ORDRSECR-GET-HIST-HEAD"
xmlEleName="OrderHistoryHeader" lowerBound="1" upperBound="1">
<ItemSelectionArray>
<ItemSelection itemName="ORDRSECR-GET-HIST-HEAD.CUSTOMER-ID"/>
</ItemSelectionArray>
</OutputMessage>

<OutputMessage importFile="ORDRRECS.cpy" importDirectory="."

nativeTypeName="ORDRRECS-HIST-RECORD"
xmlEleName="OrderHistoryRecord" lowerBound="1" upperBound="255">
<ItemSelectionArray>
<ItemSelection itemName="ORDRRECS-HIST-RECORD.ORDER-DATE"/>
<ItemSelection itemName="ORDRRECS-HIST-RECORD.ORDER-ITEM-ID"/>
<ItemSelection itemName="ORDRRECS-HIST-RECORD.ORDER-ITEM-PRICE"/>
<ItemSelection itemName="ORDRRECS-HIST-RECORD.ORDER-ITEM-QTY"/>
<ItemSelection itemName="ORDRRECS-HIST-RECORD.ORDER-ITEM-DESC"/>
</ItemSelectionArray>
</OutputMessage>

<OutputMessage importFile="ORDRSECR.cpy" importDirectory="."

nativeTypeName="ORDRSECR-HIST-SUMMARY"
xmlEleName="OrderHistoryTail" lowerBound="1" upperBound="1">
<ItemSelectionArray>
<ItemSelection itemName="ORDRSECR-HIST-SUMMARY.TOTAL-ORDERS"/>
<ItemSelection itemName="ORDRSECR-HIST-SUMMARY.TOTAL-SPENT"/>
<ItemSelection itemName="ORDRSECR-HIST-SUMMARY.REPORT-DATE"/>
<ItemSelection itemName="ORDRSECR-HIST-SUMMARY.REPORT-TIME"/>
</ItemSelectionArray>
</InputMessage>
</OutputMessage>
<XseSpec>
<XsdSpecIn ../>
<XsdSpecOut xsdEleName="GetOrderHistoryResponse"
targetNamespace="http://www.ibm.com/schemas/weborders"
fileName="GetOrderHistory.xsd"/>
</XseSpec>
</Operation>

Figure 25. Example of Specifying Multiple Language Structures for the Response Message

Generation of composite XML schemas from multiple language structures

This topic describes how composite XML Schemas are generated by the Enterprise Service Tools
batch processor when multiple language structures are specified for the request and response
interfaces of an enterprise application program. The InputMessage and OutputMessage elements of the
ServiceSpecification.xml file are used to specify each language structure for the request and response
messages respectively.

312 Developer for z/OS: Developing with Db2, CICS, and IMS
The Enterprise Service Tools batch processor takes the following steps to generate a composite XML
Schema (assume just the request/input message for these steps):
1. Each InputMessage element is processed and the referenced language structure (nativeTypeName) is
converted into an equivalent complex type and stored in the request XML Schema. The name of each
generated complex type is not settable.
2. For each complex type created in step 1, an XML element is defined and stored in the request XML
Schema. The minOccurs and maxOccurs attributes of each XML element are set to the values of the
lowerBound and upperBound attributes of the corresponding InputMessage element. The name of
each XML element is set to the value of the xmlEleName attribute in the respective InputMessage
element. If the xmlEleName attribute is not specified or its value is non-unique with respect to other
InputMessage elements, a generated name is used.
Note: When the IMS Enterprise Suite SOAP Gateway Web service wizard is used, the xmlEleName
attribute is never specified
3. Once a complex type and an XML element has been defined for each language structure, a single,
top-level complex type is defined that contains all the XML elements in the same order as they
appeared in the series of InputMessage elements.
Note: When the IMS Enterprise Suite SOAP Gateway Web service wizard is used, the order of the
InputMessage element series is determined by the layout specified on the “IMS Message Layouts”
page.
4. A global XML element is defined whose type is the top-level complex type created in step 3. The name
of the global element is set to the value of the XsdSpecIn/@xsdEleName attribute.
Note: A generated named is used when the xsdEleName attribute is not specified.
Table 48 on page 313 illustrates the specification of multiple InputMessage elements and the resulting
composite XML Schema.

Table 48. Example of a Composite XML Schema Resulting from the Specification of Multiple InputMessage
Elements
ServiceSpecification.xml Composite XML Schema

<InputMessage <complexType name="REQ_HEADER">

nativeTypeName="REQ-HEADER" <sequence ../>
xmlEleName="RequestHeader" </complexType>
lowerBound="1" upperBound="1">
<ItemSelectionArray ../> <complexType name="REQ_BODY">
<sequence ../>
<InputMessage </complexType>
nativeTypeName="REQ-BODY"
xmlEleName="REQ-BODY" <complexType name="REQ_SUM">
<sequence ../>
</complexType>
lowerBound="1"upperBound="10">
<ItemSelectionArray ../> <complexType
</InputMessage > name="EIS_COMPOSITE_MESSAGE">
<sequence>
<element name="RequestHeader"
<InputMessage type="p:REQ_HEADER"
nativeTypeName="REQ-SUM" minOccurs="1" maxOccurs="1" />
xmlEleName="RequestSummary" <element name="RequestBody"
lowerBound="1" upperBound="1"> type="p:REQ_BODY"
<ItemSelectionArray ../> minOccurs="1" maxOccurs="10" />
</InputMessage > <element name="RequestSummary"
type="p:REQ_SUMMARY"
<XsdSpecIn minOccurs="1" maxOccurs="1" />
xsdEleName="ServiceRequest" ../> </sequence>
</complexType>

<element name="ServiceRequest"
type="p:EIS_COMPOSITE_MESSAGE" >
</element>

Developing web services and SOA with Enterprise Service Tools 313
 Limitations and Error Conditions
This section describes the batch processor limitations and restrictions on generation of composite XML
Schemas from collections of language structures.
Multiple InputMessage and OutputMessages are not allowed if mapping files are specified instead of
language source files (that is, meet-in-middle is not supported since this function deals with generation of
XSDs).
Multiple InputOutputMessage elements are not supported. Use multiple InputMessage and
OutputMessage elements instead.
A language structure may not be specified more than once in a series of InputMessage or OutputMessage
elements. This means that an XML Schema complex type derived from a language structure cannot
reappear later in an XML message with identical or different field level inclusions and/or exclusions.
All language structures specified on InputMessage and OutputMessage elements (nativeTypeName) must
have unique names regardless of the language source file (importFile) they reside in.
All XML element names specified on InputMessage and OutputMessage elements (xmlEleName) must be
unique with respective to the other InputMessage or OutputMessage elements. It is not an error to have a
XML element name that appears both in a series of InputMessage and OutputMessage elements.
Important: Inter-language structure dependencies are not supported.
For example, an OCCURS DEPENDING ON (ODO) subject cannot refer to an ODO object in another
structure.

Working with the runtime language-XML conversion programs

This group of topics describes how to configure options for the generated runtime XML conversion
programs and how to use the XML conversion utility functions.

Converter runtime storage information utility programs

The request XML and response XML converters provide utility programs for retrieving the sizes of the
respective storage areas which must be provided when the converters are invoked.
There are three storage areas which the caller may need to allocate dynamically before invoking the
converters. These areas are for storing the following structures:
• Request language structure
• Response language structure
• Response XML document
Normally, users of Enterprise Service Tools (EST) need not be concerned with manually allocating these
areas, since the generated converter driver handles the allocation of these areas in a runtime-appropriate
way. If the converters are deployed into a custom runtime environment, the utility programs described
here can be useful to a component which dynamically selects converters to call without having any
knowledge of the language structure definitions on which an XML converter is based.
The IMS XML Adapter for IMS Connect is an example of a component which makes use of the utility
programs. To remain stateless, the IMS XML Adapter relies on the utility programs to determine how
much storage to allocate before invoking the converters.

Request XML and Response XML converter utility programs

The request XML and response XML converters consist of a suite of programs which work together to
perform conversion. The following programs can be called before the main XML conversion program, to
prepare the necessary storage areas or check boundary conditions. Note that the parameters passed to
these programs are by reference and output only.
For COBOL XML converters, the following table can be used for reference:

314 Developer for z/OS: Developing with Db2, CICS, and IMS
Name:
XML to Language Structure Converter:[Program Name Prefix] + 'J'
Description:
Get the required length in bytes of the XML to language structure conversion language structure buffer
Parameters:

Name: Type: Output:

XML2LS-LANG-BUFFER- 4 byte signed binary Required length in bytes of
LENGTH the XML to language structure
conversion buffer language
structure buffer.
XML2LS-PROPERTIES 1 byte binary 8 1-bit Indicators for XML to
language structure conversion.
Bit 8 (x'80') : multisegment
indicator Bit 7..1 : reserved for
future use.

Name:
XML to Language Structure Converter:[Program Name Prefix] + 'L
Description:
Get the required length in bytes of the XML to language structure conversion language structure
buffer.
Parameters:

Name: Type: Output:

LS2XML-LANG-BUFFER- 4 byte signed binary Required length in bytes of
LENGTH the language structure to XML
language structure buffer.
LS2XML-PROPERTIES 1 byte binary 8 1-bit Indicators for language
structure to XML conversion.
Bit 8 (x'80'): multisegment
indicator Bit 7..1 : reserved for
future use.

Name:
XML to Language Structure Converter:[Program Name Prefix] + 'K'
Description:
Get the required length in bytes of the XML to language structure conversion XML buffer.
Parameters:

Name: Type: Output:

LS2XML-XML-BUFFER-LENGTH 4 byte signed binary Required length in bytes of
the language structure to
XML conversion XML document
buffer.

For PL/I XML converters, the following table can be used for reference:
Name:
XML to Language Structure Converter:[Program Name Prefix] + 'J'
Description:
Get request language structure storage requirements

Developing web services and SOA with Enterprise Service Tools 315
 Parameters

Name: Type: Output:

p_instruct_max_size 4 byte signed binary Maximum length in bytes of the
request language structure

Name:
XML to Language Structure Converter:[Program Name Prefix] + 'L
Description:
Get response language structure storage requirements
Parameters:

Name: Type: Output:

p_outstruct_max_size 4 byte signed binary Maximum length in bytes of the
response language structure

Name:
XML to Language Structure Converter:[Program Name Prefix] + 'K'
Description:
Get response XML document storage requirements
Parameters:

Name: Type: Output

p_outxml_max_size 4 byte signed binary Maximum length in bytes of the
response XML document

Maximum length in bytes of a language structure

The maximum length of a language structure uses the upper bound for all the variable length elementary
and group items in the structure. This value represents how much storage would be occupied by the
language structure in the worst case.

Maximum length in bytes of XML messages

Based on the language structure(s) and the generated or mapped XML schema, the tool computes the
maximum number of bytes which could be occupied by a derived XML document. The computation takes
several factors into account. They include:
• Length of the XML element tag names.
• Maximum number of character positions in each data item when convertered to display format.
• Maximum number of bytes required to represent a character in each data item.
• Maximum number of occurrences of each data item.
• Expansion of the 5 predefined entities in XML (<,>,',",&); which are escaped to <, >, ', ", and &.
– For example, a PIC X(5) data item whose contents are a>b>c expand to a>b>c in the response
XML document.
– Therefore, every non-numeric data item is assumed to have an expansion factor of 6, since the length
of the longest entity is 6 characters (").
• Maximum number occurrences of each language structure (IMS multisegment, bottom-up only).
The following shows in depth how the maximum number of bytes occupied by a data item is computed.
Assume that:
• The data item is declared as 05 OUT-ITEM PIC X/N/G(5) OCCURS 3.

316 Developer for z/OS: Developing with Db2, CICS, and IMS
• The data item is mapped to the XML element tag name out-field. Therefore the start and end tags
are <out-field> and <out-field/>.
• When the response code page is UTF-16, 2 bytes are always required per character.
The maximum number of bytes is computed using the following formulas:

[Bytes occupied by XML element start and end tags] +

[Max bytes occupied by data item in display format with entity expansion]
= [Max bytes occupied by field]

[Bytes occupied by XML element start and end tags]

= [((Number of characters in the start tag +
Number of characters in the end tag) *
Number of bytes per character) * (Total number of occurrences)]
= [ ((11 + 12) * (1 or 2)) * 3]
= 69 bytes (SBCS) or 138 bytes (UTF-16)

[Max bytes occupied by data item in display format with entity expansion]
= [((Length of the longest predefined entity *
Number of characters in the field) *
Number of bytes per character)) *
(Total number of occurrences)]
= [ ((6 * 5) * (1 or 2)) * 3 ]
= 90 bytes (SBCS) or 180 bytes (UTF-16)

Thus, using the preceding formulas, there are two possible results for the max number of bytes needed to
represent OUT-ITEM in an XML document:
• For an SBCS response code page, the max is 69 + 90 = 159 bytes.
• For UTF-16 response code page, the max is 138 + 180 = 318 bytes.

COBOL Converter driver aggregate utility program

The COBOL converter driver program suite contains a utility program which provides all the available
information known to the converter. In addition to the information which can be learned from the request
and response converter utility programs, the coded character set identifiers (CCSIDs) of the request XML,
response XML, host, and code pages are also included.
The layout of IMS multisegment message layout is considered when computing the memory requirements
for the language structure and XML buffers.
Name:
Language Structure to XML Conversion:[Program Name Prefix] + 'X'
Description:
1. Get language structure and XML document buffer storage requirements.
2. Get request XML, response XML, host, and code page information.
Parameters:

Name: Type: Output:

XML2LS-LANG-BUFFER- 4 byte signed binary Required length in bytes of
LENGTH the XML to language structure
conversion buffer.
LS2XML-LANG-BUFFER- 4 byte signed binary Required length in bytes of
LENGTH the response language structure
buffer.
LS2XML-XML-BUFFER-LENGTH 4 byte signed binary Required length in bytes of
the language structure ot XML
conversion buffer.

Developing web services and SOA with Enterprise Service Tools 317
 Name: Type: Output:
XML2LS-XML-CCSID 4 byte signed binary Coded CharacterSet IDentifier
for XML to language structure
conversion input.
HOST-LANG-CCSID 4 byte signed binary Coded CharacterSet IDentifier
for language structures.
LS2XML-XML-CCSID 4 byte signed binary Coded CharacterSet IDentifier
for language structure to XML
conversion output.
XML2LS-PROPERTIES 1 byte binary 8 1-bit Indicators for XML to
language structure conversion.
Bit 8 (x'80') : multisegment
indicator Bit 7..1 : reserved for
future use.

LS2XML-PROPERTIES 1 byte binary 8 1-bit Indicators for language

structure to XML conversion.
Bit 8 (x'80'): multisegment
indicator Bit 7..1 : reserved for
future use.

PL/I Converter driver aggregate utility program

The PL/I converter driver program suite contains a utility program which provides all the available
information known to the converter. In addition to the information which can be learned from the request
and response converter utility programs, the coded character set identifiers (CCSIDs) of the request, host
and response code pages are also included.
Name:
Language Structure to XML Conversion:[Program Name Prefix] + 'X'
Description:
1. Get language structure and XML message storage requirements.
2. Get request XML, response XML, host, and code page information.
Parameters:

Name: Type: Output:

p_instruct_max_size 4 byte signed binary Maximum length in bytes of the
response XML document
p_outstruct_max_size 4 byte signed binary Maximum length in bytes of the
response language structure
p_outxml_max_size 4 byte signed binary Maximum length in bytes of an
XML Message derived from the
response language structure
p_inbound_ccsid 4 byte signed binary Coded CharacterSet IDentifier
for request XML
p_host_ccsid 4 byte signed binary Coded CharacterSet IDentifier
for language structures
p_outbound_ccsid 4 byte signed binary Coded CharacterSet IDentifier
for response XML

318 Developer for z/OS: Developing with Db2, CICS, and IMS
Message WSED0325U issued during generation of the COBOL XML Converters
The length of an XML document that can be derived from the response data structure and is sensitive to
value of the compiler level. A limit of 16,777,210 bytes (~16MB) applies to COBOL V3R3 and earlier. A
limit of 33,554,432 bytes (32MB) applies for COBOL V3R4 and later.
As described previously, the tool computes the maximum size of the response XML document. The
response XML converter is bounded in regards to the maximum size of an XML document it can generate.
The upper bound is approximately 16 megabytes, because that is the size of the XML buffer declared
in the converter. Receipt of the message WSED0235U during generation indicates that the response
converter would not be able to buffer the response XML document in the worst case. Taking this into
account, generation is halted to prevent creation of an response XML converter which may fail at run time.
The 16-megabyte upper bound is related to the historic maximum size of a COBOL data item, even though
the maximum has been relaxed to 128-megabyte in the latest release of Enterprise COBOL for z/OS.

COBOL Example conversion routing program using utilities

The following is an example of a program that uses the utility programs to handle conversion of COBOL
XML messages flowing in and out of business programs. The example is stateless in that it doesn't need
to keep record of the language structures associated with each business program. The assumption here is
that every business program reads from an request structure and writes to an response structure.

* *********************************************
* *********************************************************
* *************************************************************
* EXAMPLE CONVERSION ROUTING PROGRAM USING UTILITIES
* *************************************************************
* *********************************************************
* *********************************************
IDENTIFICATION DIVISION.
PROGRAM-ID. 'UTILEXMP'.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 FEEDBACK-CODE.
02 CONDITION-TOKEN-VALUE.
88 CEE000 VALUE X'0000000000000000'.
88 CEE0E7 VALUE X'000101C749C3C5C5'.
03 SEVERITY PIC S9(4) BINARY.
03 MSG-NO PIC S9(4) BINARY.
03 CASE-SEV-CTL PIC X.
03 FACILITY PIC XXX.
02 I-S-INFO PIC S9(9) BINARY.
LOCAL-STORAGE SECTION.
01 INSTRUCT-MAX-SIZE PICTURE S9(9) BINARY.
01 INSTRUCT-HEAP-ID PIC S9(9) BINARY.
01 INSTRUCT-STG-ADDR POINTER.
01 OUTSTRUCT-MAX-SIZE PICTURE S9(9) BINARY.
01 OUTSTRUCT-HEAP-ID PIC S9(9) BINARY.
01 OUTSTRUCT-STG-ADDR POINTER.
01 OUTXML-MAX-SIZE PICTURE S9(9) BINARY.
LINKAGE SECTION.
01 WEB-SERVICE-INTERFACE.
02 SERVICE-ID PIC X(16).
02 XML-INT-LEN PIC S9(9) BINARY.
02 XML-INT-TXT PIC X(32768).
01 INSTRUCT PIC X.
01 OUTSTRUCT PIC X.
PROCEDURE DIVISION USING WEB-SERVICE-INTERFACE.
MAINLINE SECTION.
* -------------------------------------------------------------
* GET MAX SIZE OF INBOUND LANGUAGE STRUCTURE
* -------------------------------------------------------------
EVAULATE SERVICE-ID
WHEN 'EXAMPLE1'
CALL 'CONV1J' USING INSTRUCT-MAX-SIZE
WHEN 'EXAMPLE2'
CALL 'CONV2J' USING INSTRUCT-MAX-SIZE
END-EVAULATE

* -------------------------------------------------------------
* ALLOCATE STORAGE AREA FOR INBOUND LANGUAGE STRUCTURE
* AND ESTABLISH ADDRESSABILITY

Developing web services and SOA with Enterprise Service Tools 319
 * -------------------------------------------------------------
INITIALIZE INSTRUCT-HEAP-ID
CALL 'CEEGTST' USING
INSTRUCT-HEAP-ID INSTRUCT-MAX-SIZE
INSTRUCT-STG-ADDR FEEDBACK-CODE
IF NOT CEE000 OF FEEDBACK-CODE
DISPLAY 'GET HEAP STORAGE FAILED!'
STOP RUN
ELSE
SET ADDRESS OF INSTRUCT
TO INSTRUCT-STG-ADDR
END-IF

* -------------------------------------------------------------
* CALL INBOUND CONVERTER PASSING STORAGE AREA AND XML DOCUMENT
* -------------------------------------------------------------
EVAULATE SERVICE-ID
WHEN 'EXAMPLE1'
CALL 'CONV1I' USING
INSTRUCT XML-INT-LEN XML-INT-TXT OMITTED
RETURNING CONVERTER-RETURN-CODE
WHEN 'EXAMPLE2'
CALL 'CONV2I' USING
INSTRUCT XML-INT-LEN XML-INT-TXT OMITTED
RETURNING CONVERTER-RETURN-CODE
END-EVAULATE

* -------------------------------------------------------------
* GET MAX SIZE OF OUTBOUND LANGUAGE STRUCTURE
* -------------------------------------------------------------
EVAULATE SERVICE-ID
WHEN 'EXAMPLE1'
CALL 'CONV1L' USING OUTSTRUCT-MAX-SIZE
WHEN 'EXAMPLE2'
CALL 'CONV2L' USING OUTSTRUCT-MAX-SIZE
END-EVAULATE

* -------------------------------------------------------------
* ALLOCATE STORAGE AREA FOR OUTBOUND LANGUAGE STRUCTURE
* AND ESTABLISH ADDRESSABILITY
* -------------------------------------------------------------
INITIALIZE OUTSTRUCT-HEAP-ID
CALL 'CEEGTST' USING
OUTSTRUCT-HEAP-ID OUTSTRUCT-MAX-SIZE
OUTSTRUCT-STG-ADDR FEEDBACK-CODE
IF NOT CEE000 OF FEEDBACK-CODE
DISPLAY 'GET HEAP STORAGE FAILED!'
STOP RUN
ELSE
SET ADDRESS OF OUTSTRUCT
TO OUTSTRUCT-STG-ADDR
END-IF

* -------------------------------------------------------------
* CALL BUSINESS PROGRAM PASSING INBOUND LANGUAGE STRUCTURE
* -------------------------------------------------------------
EVAULATE SERVICE-ID
WHEN 'EXAMPLE1'
CALL 'BUSPROG1' USING INSTRUCT OUTSTRUCT
WHEN 'EXAMPLE2'
CALL 'BUSPROG2' USING INSTRUCT OUTSTRUCT
END-EVAULATE

* -------------------------------------------------------------
* MAKE SURE OUTBOUND XML BUFFER IS LARGE ENOUGH TO RETURN
* XML DOCUMENT RESULT
* -------------------------------------------------------------
EVAULATE SERVICE-ID
WHEN 'EXAMPLE1'
CALL 'CONV1K' USING OUTXML-MAX-SIZE
WHEN 'EXAMPLE2'
CALL 'CONV2K' USING OUTXML-MAX-SIZE
END-EVAULATE

IF OUTXML-MAX-SIZE > LENGTH OF XML-INT-TXT

DISPLAY 'OUTBOUND XML BUFFER TOO SMALL!'
STOP RUN
END-IF

* -------------------------------------------------------------
* CALL OUTBOUND CONVERTER TO PRODUCE REPLY XML DOCUMENT
* -------------------------------------------------------------

320 Developer for z/OS: Developing with Db2, CICS, and IMS
 EVAULATE SERVICE-ID
WHEN 'EXAMPLE1'
CALL 'CONV1O' USING
OUTSTRUCT XML-INT-LEN XML-INT-TXT OMITTED
RETURNING CONVERTER-RETURN-CODE
WHEN 'EXAMPLE2'
CALL 'CONV2O' USING
OUTSTRUCT XML-INT-LEN XML-INT-TXT OMITTED
RETURNING CONVERTER-RETURN-CODE
END-EVAULATE

* -------------------------------------------------------------
* CLEAN UP AND RETURN TO CALLER
* -------------------------------------------------------------
CALL 'CEEFRST' USING INSTRUCT-STG-ADDR FEEDBACK-CODE
IF NOT CEE000 OF FEEDBACK-CODE
DISPLAY 'FREE INSTRUCT STORAGE AREA FAILED!'
STOP RUN
END-IF
CALL 'CEEFRST' USING OUTSTRUCT-STG-ADDR FEEDBACK-CODE
IF NOT CEE000 OF FEEDBACK-CODE
DISPLAY 'FREE OUTSTRUCT STORAGE AREA FAILED!'
STOP RUN
END-IF

GOBACK.

END PROGRAM 'UTILEXMP'.

Limitations: The values that are returned by the utility programs can be invalidated by manual
modification of the generated code.

Preferences and options for COBOL XML converters

This group of topics describes preferences and options for COBOL XML converters.

Setting preferences for COBOL XML converters

To set preferences for COBOL XML converters, open the COBOL XML Converters page in the Enterprise
Service Tools preferences.
These preferences affect single-service projects, including:
• Web Services for CICS
• JSON Services forCICS project
• XML Transformation for CICS
• IMS Enterprise Suite SOAP Gateway
• Batch, TSO, z/OS UNIX System Services
These preferences affect how runtime XML conversion programs generated by single-service wizards
in the Enterprise Service Tools convert data between the XML format used in service requests and
responses and the high-level language data structures used by COBOL:
To set generation preferences for runtime XML conversion programs:
1. In the left pane of the Preferences window, select Enterprise Service Tools.
2. Change the preferences:
a. The preferences on the Basic tab are described in the following table:

Preference: Effect of this preference:

Converter program This input field specifies the stem of the program name that is
name prefix included in the IDENTIFICATION DIVISION of each generated COBOL
program. If you type ACCT, for example, the wizard identifies the input
converter program as ACCTI, the output converter program as ACCTO,
and the driver as ACCTD

Developing web services and SOA with Enterprise Service Tools 321
 Preference: Effect of this preference:
Author name This input field specifies the character string to be included in the
AUTHOR paragraph of each generated COBOL program.
Request code page This list box specifies the code page to be used for encoding the
request XML message.
Host code page This list box specifies the code page that is used by the z/OS host
system.
Response code page This list box specifies the code page to be used for encoding the
response XML message.
Decimal point is comma This checkbox controls how the comma and period characters are
interpreted in numeric strings:
• When you select this checkbox:
– A comma is interpreted as a decimal point.
– A period is interpreted as a thousands separator.
• When you clear this checkbox (this is the default setting):
– A comma is interpreted as a thousands separator.
– A period is interpreted as a decimal point.

3. The preferences on the Advanced tab are as follows:

• In the Specify XML Schema generation options group:
Generate minimum hierarchy in XML Schemas
This checkbox controls the message format of the generated XML schema and consequently the
parsing and generation of XML in the XML converters. XML converters based on XML schemas
having minimized hierarchies tend to have better performance.
– Select this checkbox if you want the XML converters to be generated so as to use a reduced
XML structure hierarchy, when a more detailed structure hierarchy is not needed to uniquely
identify each element in the structure.
When there are elements with the same tag name, the name of the element that occurs later
in the document is prefixed with as many of its parent tags as are required to produce a unique
name. This method increases the efficiency of message processing clients and reduces the
number and complexity of objects that need to be instantiated.
– Clear this checkbox if you want the wizard to generate an XML schema that represents the full
hierarchy of the language structure.

Generate groups in XML Schemas

This checkbox controls whether the XML converter includes groups in the generated XML
schemas:
– Select this checkbox if you want the XML converter to include groups in the generated XML
schemas.
– Clear this checkbox if you want the XML converter to include group "contents" inline instead
of using group references. This option is useful for applications that do not support the use of
groups and group references in XML schemas.

Generate short complex type names

The normal method for generating a complex type name is to concatenate the name of the group
to the names of all the parents of the group, with an underscore character "_" after each name
except the last.

322 Developer for z/OS: Developing with Db2, CICS, and IMS
 However, if this checkbox is selected, then a complex type name is generated by taking just the
name of the group.
For example, in this COBOL group:

01 ServiceRequest.
02 CommonHeader.
05 HeaderType1.
10 Element1 PIC X(10).

the complex XML type name for the HeaderType1 element is:
– servicerequest_commonheader_headertype1 if the checkbox is not selected.
– HeaderType1 if the checkbox is selected.
The shortening of complex type names allows for the generation of more compact client code
(usually, Java class code) from the WSDL and XSD files containing the complex XML types.
The setting of this checkbox has no effect on top-down or meet-in-middle scenarios.
When shortening of a complex type name is attempted, a collision is possible if the short name
of the type already exists as the result of a previously defined type for a group with an identical
name but different parent group names. For example, in the following COBOL structure:

01 ServiceRequest.
02 CommonHeader.
05 HeaderType.
10 Element PIC X(10).
02 SpecificHeader.
05 HeaderType.
10 Element PIC X(10).

the type name of the HeaderType group under SpecificHeader collides with the type name
of the HeaderType group under CommonHeader.
In case of a collision all colliding names keep the original long type names. Thus, based on this
example, the resulting type names are:
– servicerequest_commonheader_headertype and
– servicerequest_specificheader_headertype.
The short name for a complex type is formed by taking the name of the XML element that has
that type, plus some possible modifications. The rules for forming short names are:
a. Take the name of the XML element that has the type (such as HeaderType1).
b. If the name starts with a character that is an invalid character for Java names (for example, a
digit), it is prefixed with a double underscore "__".
c. If a hyphen "-" is present in the original COBOL group name it is replaced with a single
underscore "_".
d. The case of the group name is preserved.
For example, the following group:

03 2-In--B.
04 var2 blank zero pic 999.99.

results in the shortened complex type name __2_In__B.

Generate comments in XSD

Select this checkbox to cause the comments from the COBOL source code file to be generated as
annotation documentation in the generated XSD and WSDL files (see “Including COBOL source
code comments in generated XSD and WSDL files” on page 327)
This option applies only to the bottom-up development scenario for generating a Web service,
and applies only if you specify Compiled XML Conversion.

Developing web services and SOA with Enterprise Service Tools 323
 Generate qualified XML elements in XML schemas
This checkbox allows for generation of qualified XML elements in the XML schemas.
This allows for the option to require all XML elements be qualified with a namespace and
support generation of XML schemas that can be included in other schemas with lesser chance of
namespace collision.

• In the Specify Request XML converter behavior group:

Validate root element namespace name
Select this checkbox to enable validation of the target namespace of the root element in XML
documents. The target namespace of the root element can be found in the XML schema which
defines it.

Use VALUE literals to initialize omitted data items

Select this checkbox to enable initialization for data items in the request language structure that
you have excluded from the Web service input data structure (see “Initializing data items in the
COBOL application's input data structure” on page 325 ).
This option applies only to the bottom-up development scenario for generating a Web service,
and applies only if you specify Compiled XML Conversion.

Use VALUE literals to initialize empty data items

Select this checkbox to enable initialization for data items in the request language structure that
you have included in the Web service input data structure (see “Initializing data items in the
COBOL application's input data structure” on page 325 ).
This option applies only to the bottom-up scenario for generating a Web service, and applies only
if you specify Compiled XML Conversion.

• In the Specify response XML converter behavior group:

Language data
This option controls how the response runtime XML conversion program handles characters in
the response COBOL data that are illegal in the XML 1.0 specification:
– Select Filter characters illegal in XML 1.0 if you want the conversion program to scan both
non-numeric and numeric data in the language structure and convert any character that is
illegal in the XML 1.0 specification to an EBCDIC, ASCII, or UNICODE space (depending on the
response code page).
– Select Halt on characters illegal in XML 1.0 if you want the conversion program to scan both
non-numeric and numeric data in the language structure and cause an exception if characters
illegal in XML 1.0 are found.
– Select Do not check for illegal characters if you want the conversion program not to check for
characters that are illegal in the XML 1.0 specification.
For more information see “Options for handling illegal XML characters” on page 325.

• In the Specify compiler-related preferences group::

Optimization
Select whether the optimization option is enabled for the COBOL compiler. When the checkbox
is selected, the COBOL compiler will use optimization in generating runtime code from COBOL
source code.
If you are trying to debug a compile error in your COBOL source code, it is a good idea to clear
this checkbox and recompile. Without optimization turned on, it is easier to determine which part
of the COBOL source code is causing the error.

Specify Enterprise COBOL compiler version

Select the version of the COBOL compiler that you want to use.

4. Click OK when done.

324 Developer for z/OS: Developing with Db2, CICS, and IMS
Options for handling illegal XML characters
The response XML conversion program generated by Enterprise Service Tools attempts to patch up data in
response language structures so that a valid XML message can be produced.

By default the response converter filters characters from the language structure that are illegal in an XML
document. Using the Enterprise Service Tools COBOL generator preferences page, you can configure this
behavior for debugging and performance purposes. In the left pane of the Preferences window, select
Enterprise Service Tools > COBOL XML Converters.
On the preferences page, lists two options that are associated with converter filters.
• Filter characters illegal in XML 1.0 (response)
The default for this option is on. The response converter scans both nonnumeric and non-binary
numeric fields in the language structure. In nonnumeric fields, any character that is illegal in an XML
document according to the XML 1.0 specification is converted to an EBCDIC, ASCII or UNICODE space
(depending on the response code page). For non-binary numeric fields, if the contents of a field is
invalid according to its usage (for example an invalid packed decimal), the field is initialized to zero.
• Halt on characters illegal in XML 1.0 (response)
This option is turned off by default. The response converter scans both nonnumeric and non-binary
numeric fields in the language structure and returns an exception if either characters illegal in XML 1.0
or invalid non-binary numerics are found.
If illegal nonnumeric data is found, a message stating that the language structure to XML conversion
could not complete because the content of a nonnumeric member of the language structure contained
characters that are not legal in an XML document.
If invalid non-binary numeric data is found, a message stating that the language structure to XML
conversion could not complete because the content of a numeric member of the language structure is
invalid.
You can select only one of these options at a time or, you can select neither option for maximum
performance of the response converter.
Note: Disabling both options provides no protection against including illegal characters in the XML
document produced by the response converter.
Related information
Opening the Preferences window

Initializing data items in the COBOL application's input data structure

This topic describes two initialization options that are available when you generate a Web service in a
single-service project using both the bottom-up method and compiled XML conversion.
When you enable either of these two initialization options, VALUE clauses in the request language
structure that you specified for the new Web service are given effect by initialization code that is executed
before the new Web service invokes the existing COBOL application (service provider application or
service requester application).
One of these options enables initialization for data items in the request language structure that you have
included in the Web service input data structure. The other option enables initialization for data items in
the request language structure that you have excluded from the Web service input data structure.
This option is available both in the Create New Service Interface (bottom-up) wizard (see “Setting
preferences for COBOL XML converters” on page 145) and in the command-line batch processor (see
the properties INIT_EMPTY_ITEMS_IN_INTERFACE and INIT_OMITTED_ITEMS_IN_INTERFACE in
“CodegenProperty” on page 422).
This option is available only when you use the compiled conversion option.

Developing web services and SOA with Enterprise Service Tools 325
 Description
The COBOL request language structure that you specify for the new Web service may contain VALUE
clauses that define the initial values for data items in the request language structure (for more information
about the request language structure see “Language structures page” on page 202 for the wizard
interface and “InputMessage” on page 457 for the batch processor command-line interface).
However, in the source code that is generated for the new Web service, these VALUE clauses are not
included in the LINKAGE section that defines the input data structure that the new Web service passes
to the existing COBOL data application (service provider application or service requester application). The
reason is that the COBOL compiler ignores VALUE clauses in a LINKAGE section.
Therefore, to allow you to give effect to these unincluded VALUE clauses if you wish to do so, the two
options described in this help topic cause the Enterprise Service Tools source code generator to add
initialization source code to the new Web service driver. This initialization source code initializes data
items in the input data structure that is passed to the existing COBOL application with the same initial
values that would have existed if the VALUE clauses had been processed.
Note: This option requires that the VALUE literal be defined on one line (no continuation lines).
For information about how to specify these options see the relevant section of the online help either for
the Create New Service Interface (bottom-up) wizard (“Setting preferences for COBOL XML converters”
on page 145) or for the command-line batch processor (“CodegenProperty” on page 422).
The difference between the two options is as follows:
• The INIT_EMPTY_ITEMS_IN_INTERFACE option enables initialization for data items in the request
language structure that you have included in the Web service input data structure.
– Even when this option is enabled, it does not affect a particular COBOL data item unless the
corresponding XML element in the request XML schema definition is empty.
- An element is empty if contains no information other than the name of the data item. Examples of
empty elements:

<element name="userName"></element>
<element name="Department"/>

- For example:
• Suppose the following:
– In the original COBOL data structure the data item Department is initialized to 044 by means
of a VALUE clause.
– The option INIT_EMPTY_ITEMS_IN_INTERFACE is enabled.
– A request is received in which the XML element corresponding to the COBOL data item
Department is empty.
• The result is that Enterprise Service Tools initializes the corresponding data item (Department)
in the input data structure that is passed to the existing COBOL application to the same value
(044) that would have existed if the VALUE clause had been processed.
– Otherwise (that is, if the option is not enabled, or if the option is enabled but the XML element in the
request XML schema definition is not empty) if the XML element does not specify a value for the data
item, then Enterprise Service Tools sets the corresponding data item in the input data structure that
is passed to the existing COBOL application to:
- Blanks if the data item is alphabetic or alphanumeric.
- 0 if the data item is a numeric data item.

• The INIT_OMITTED_ITEMS_IN_INTERFACE option enables initialization for data items in the request
language structure that you have excluded from the Web service input data structure.
Note: If an excluded data item is not initialized using this option, then its contents are undefined.

326 Developer for z/OS: Developing with Db2, CICS, and IMS
For more information about included and excluded data items see “Language structures page” on page
202 for the wizard interface or “InputMessage” on page 457 for the batch processor command-line
interface.

Including COBOL source code comments in generated XSD and WSDL files
This topic describes an option that enables you to add the comments from a COBOL source code file to
the XSD and WSDL files that are created when you generate a Web service using the bottom-up method
and using compiled XML conversion in a single-service project.
This option is available both in the Create New Service Interface (bottom-up) wizard (see “Setting
preferences for COBOL XML converters” on page 145) and in the command-line batch processor (see
the property GEN_COMMENT_IN_XSD in “CodegenProperty” on page 422).
The following table shows the types of files that are used as input files and some of the files that are
generated as output files when you create a Web service using the bottom-up method and using compiled
XML conversion in the batch processor (see “The types of single-service projects” on page 176):

Type of file: Purpose:

Input file: A COBOL source code file or This file contains the request
copybook file language structure and the response
language structure that you specify
for the Web service.
Output WSDL and XSD A WSDL file This file describes the Web service.
files:
Two XSD files These two files describe a message
format that is derived from the
the request language data structure
and the response language data
structure.

When the option described in this topic is enabled, the runtime code generator extracts the comments
from the COBOL source code file and adds the comments to the WSDL file and to the two XSD files
described in the previous table.
The following table describes this option in more detail:

Item: Description:
Which comment lines are • Every comment line is extracted starting at the beginning of the source
extracted: file, and continuing up to but not including whichever of the following
items comes first:
– The very first PROCEDURE DIVISION statement. If the source file does
not contain a PROCEDURE DIVISION statement, then every comment
line is extracted from the source file.
– The next available level 01 group after the level 01 group
selected for the interface.
• Comments are extracted only from the specified COBOL source code file
itself and not from any COPY files that it may reference.
• Only comment lines (created by placing a * in column 7) are extracted.
Comment entries and optional paragraphs are not extracted.

Where the comment lines The extracted comment lines within each level 01 COBOL data item in the
are placed in the XSD and COBOL source code file are added to the documentation element of the
WSDL files: annotation element belonging to the top-level data type derived from
that level 01 COBOL data item.

Developing web services and SOA with Enterprise Service Tools 327
 Item: Description:
Entity references: Characters that are used in XML as pre-defined entity references are
replaced by their expanded forms. For example, an ampersand symbol (&)
is replaced by a string that represents the ampersand entity expansion.
Multibyte characters: Multibyte characters in the text of a COBOL comment must follow the rules
given in the Enterprise COBOL documentation for multibyte characters.
Globalization concerns: The content of the COBOL comment lines is expected to follow the rules
of the Enterprise COBOL version 3.4 and later. No attempts to manipulate,
transform or translate the content (beyond what is described in this section)
is done by the EST generation process.
Invalid XML code points: If invalid XML 1.0 codepoints appear in the COBOL comments and the
copybook is given to the single-service tools for processing, then the
behavior of the tool is unpredictable (The null character (0x00) is an
example of invalid XML content).

Whitespace conversion behavior for COBOL XML converters

This topic describes the capability of the Enterprise Service Tools component to generate XML schemas
and language-structure-to-XML converters that implement standards-compliant whitespace processing.
The Enterprise Service Tools wizards generate language-structure-to-XML converters (LS2XML) in both
the bottom-up and meet-in-middle development scenarios when there is compiled XML conversion. The
LS2XML converters generate XML document instances from language structure instances. The contents of
the language structure fields are converted into XML element content but first go through processing to
remove illegal characters as well as leading and trailing spaces.
Note: Prior versions of the language-structure-to-XML converters implemented nonstandard whitespace
processing. With this now available capability, it is recommended that one of the three standards-
compliant options be selected, although the nonstandard whitespace processing is available through a
compatibility option.
The following whitespace processing options are defined by XML Schema and can be applied to language
data during conversion to XML:
The whiteSpace attribute has the following values :
• preserve - no whitespace removal nor replacement is performed.
• replace - tab, line feed, and carriage return characters with spaces.
Note: The LS2XML converter optionally goes a step further and replaces all characters illegal in XML
with spaces.
• collapse - (1) replace tab, line feed, and carriage return characters with spaces, (2) trim leading and
trailing spaces, and (3) substitute a single space for each contiguous sequence of spaces
Note:
1. By default, the LS2XML converter replaces all characters illegal in XML with spaces before performing
the processing indicated by the specified whiteSpace attribute values. This LS2XML converter can be
configured on the Advanced Options tab of the Generation Options page to either replace, report, or
ignore characters illegal in XML 1.0 in language structure fields.
2. In the Map and Existing Service Interface (meet-in-middle) scenario, selection of a whitespace
processing option is not allowed since the existing XML schema dictates how whitespace should be
handled on a per mapping basis.
The following performance observations are based on the amount of work each whitespace processing
option causes the LS2XML converter to undertake:
• preserve - selecting this option may increase the performance of the LS2XML converter itself, but can
decrease the overall performance of the service as more bytes need to be sent over the network.

328 Developer for z/OS: Developing with Db2, CICS, and IMS
• replace - selecting this option may decrease the performance of the LS2XML converter as each
character needs to be inspected and substituted with a space if it is tab, line feed, or carriage return.
Network performance is unaffected as the message size is not changed.
• collapse - selecting this option may decrease the performance of the LS2XML converter because in
addition to the work required by "replace" leading, trailing, and contiguous sequences of whitespace are
detected and removed. Network performance might be improved as fewer bytes are transmitted over
the network when the document size is decreased by whitespace removal.
Table 49 on page 329 contains an example of the output of the Language Structure to XML Converter
(LS2XML) for each whitespace processing option.

Table 49. Whitespace Processing Examples

Legend/Option Data (See Note)
DISPLAYED AS:
Developer
for z/OS

SUBSTITUTED
.Developer\n.for...z/OS.
CHARACTERS (See
Note):
collapse
Developer.for.z/OS

replace
.Developer..for...z/OS.

preserve
.Developer\n.for...z/OS.

DISPLAYED AS:
Brought to you by:
Developer for z/OS

SUBSTITUTED
\tBrought.to.you.by:\r\t\tDeveloper.for.z/OS\n
CHARACTERS (See
Note):
collapse
Brought.to.you.by:Developer.for.z/OS

replace
.Brought.to.you.by:...Developer.for.z/OS.

preserve
\tBrought.to.you.by:\r\t\tDeveloper.for.z/OS\n

Note: Spaces are indicated with a dot. The characters are: "\t" for tab, "\n" for new line, and "\r" for
carriage return.

Use of namespaces
This topic describes how namespaces are used in request converters and response converters.

For the request conversion (XML to COBOL) only the target namespace of the root element is recognized
by the converter. Target namespaces can be assigned by prefixing an element with a namespace prefix
(forming a QName) or declaring a default namespace. The following restrictions apply:
• No validation of leaf elements. Root element can optionally be validated (See the attribute
GEN_VALIDATE_ROOT_IN_NS in “CodegenProperty” on page 422),
AND

Developing web services and SOA with Enterprise Service Tools 329
 • No distinction can be made for elements that only differ by namespace (For example, elements "q:a"
and "q1:a" where q and q1 are bound to different namespaces in the message are treated as just "a")
For the response conversion (COBOL to XML) the correct qualification prefixes and namespaces are
generated based on the schema(s) for the XML message.
For optimization purposes, if all the elements of the response message are bound to the same namespace
they are implicitly qualified using a default namespace. For example, the response converter generates
the message shown in Figure 26 on page 330.

<?xml version="1.0" encoding="UTF-8"?>

<LONEPost xmlns="http://www.loneI.com/schemas/loneIInterface"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.loneI.com/schemas/loneIInterface LONEI.xsd ">
<Company>IBM</Company>
<Voucher_number>002</Voucher_number>
<Transaction_type>001</Transaction_type>
<Delivery_system>POST</Delivery_system>
<Transfer_date>16002007</Transfer_date>
<Posting_date>17152007</Posting_date>
</LONEPost>

Figure 26. Example of Response Converter Message Using Implicitly Qualified Elements

Instead of the message shown in Figure 27 on page 330.

<?xml version="1.0" encoding="UTF-8"?>

<cbl:LONEPost xmlns:cbl="http://www.loneI.com/schemas/loneIInterface"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.loneI.com/schemas/loneIInterface LONEI.xsd ">
<cbl:Company>IBM</cbl:Company>
<cbl:Voucher_number>002</cbl:Voucher_number>
<cbl:Transaction_type>001</cbl:Transaction_type>
<cbl:Delivery_system>POST</cbl:Delivery_system>
<cbl:Transfer_date>16002007</cbl:Transfer_date>
<cbl:Posting_date>17152007</cbl:Posting_date>
</cbl:LONEPost

Figure 27. Example of Response Converter Message Using Explicitly Qualified Elements

Note: The content of Figure 26 on page 330 and Figure 27 on page 330 is equivalent; however Figure 26
on page 330 is a more efficient use of XML Namespaces.
The response XML converter uses this optimization when possible to reduce the size of XML messages,
this optimization has conservation benefits from CPU time to network bandwidth.
Note: This optimization is only possible if the elementForm values (explicit or implicit) are the same for all
mapped items.
Figure 28 on page 331 is an example of an XML Schema with mixed elementForm values:

330 Developer for z/OS: Developing with Db2, CICS, and IMS
 <schema xmlns="http://www.w3.org/2001/XMLSchema"
xmlns:addr="http://www.address.com/"
targetNamespace="http://www.address.com/"
elementFormDefault="unqualified" attributeFormDefault="unqualified">

<complexType name="USAddress">
<sequence>
<!-- explcit Form="qualified" -->
<element name="name" type="string" form="qualified"/>

<!-- implicit Form="unqualified" -->

<element name="street" type="string"/>
</sequence>
</complexType>
</schema>

Figure 28. Example of XML Schema with Mixed elementForm Values

For the schemas with mixed element qualification, the response converter generates the namespaces
prefixes when required. For the previous schema with mixed element qualification (see Figure 28 on page
331), the response converter generates a message containing the following fragment:

...
<addr:name>addr:name</addr:name> <!-- qualified -->
<street>street</street> <!--unqualified-->
...

COBOL/XML Mapping migration tool

Mapping migration tool gives you the capability to migrate older mapping session files (of type .cmx) to
the new format that was introduced in Version 7.

How to use the Mapping migration tool

The input into the Mapping migration tool is a set of three files:
1. A file representing the "sources" for mapping. It could be a COBOL (complete program or a copy file),
XML, XSD, or WSDL file, for example, "FAU.cbl"
2. A file representing the "targets" for mapping. It could be an XML, XSD, or WSDL file, or a COBOL
(complete program or a copy file), for example, "FAUO.xsd"
3. The pre-Version 7 mapping metadata ".cmx" file (for example fau.cmx) that links the "sources" and the
"targets".
The set of three files (sources, targets, and mapping metadata) must be present in the same folder level
in a project within the workspace. The output of the Mapping migration tool is the new mapping metadata
file, for example "fau.mapping", that is placed in a folder of user's choice.
To invoke the Mapping migration tool, double click the .cmx file.
Press the Browse button to display a browse window. In the window you then can specify target folder
for the migrated mapping session file. You can also overwrite the name of the mapping session file which
by default is set to the name of the file name of the file that is being migrated. The extension of the new
mapping session file must be ".mapping".
To migrate the old ".cmx" file after all the necessary information has been entered, click the Migrate
button. After the old ".cmx" file has been migrated and the new ".mapping" file is created, the new
Mapping editor is automatically open on the new ".mapping" file.

Developing web services and SOA with Enterprise Service Tools 331
 Setting preferences for PL/I XML converters
To set preferences for PL/I XML converters, open the PL/I XML Converters page in the Enterprise Service
Tools preferences.
Setting the preferences for PL/I XML converters affect single-service projects, including:
• Web Services for CICS
• JSON Services forCICS project
• XML Transformation for CICS
• IMS Enterprise Suite SOAP Gateway
• Batch, TSO, and z/OS UNIX System Services
These preferences affect how runtime XML conversion programs generated by single-service project
wizards in the Enterprise Service Tools convert data between the XML format used in service requests and
responses and the high-level language data structures used by PL/I:
To set generation preferences for runtime XML conversion programs:
1. In the left pane of the Preferences window, select PL/I XML Converters
2. Change the preferences:
a. The preferences on the Basic tab are described in the following table:

Preference: Effect of this preference:

Converter program This input field specifies the entry label for the procedure. If you type
name prefix ACCT, for example, the wizard identifies the input converter program
as ACCTI, the output converter program as ACCTO, and the driver as
ACCTD
Author name This input field is embedded as a PL/I comment.
Request code page This list box specifies the code page to be used for encoding the
request XML message.
Host code page This list box specifies the code page that is used by the z/OS host
system.
Response code page This list box specifies the code page to be used for encoding the
response XML message.
3. Click OK when done.

Migration to Updated Compiled XML Conversion Parser (XMLSS)

This topic covers the capability to allow Enterprise Service Tools Single-service projects the choice of a
different Compiled XML Converter to provide XML to Language Structure Conversion for the CICS, IMS,
and Batch runtimes.
With the release of Enterprise COBOL for z/OS Version 4, an additional XML parsing compiler option is
provided. This allows the user the option to choose either of two high-speed XML parsers (XMLSS and
COMPAT). If XMLSS, is specified then the z/OS XML System Services Parser (XMLSS) is used for enhanced
parsing capabilities. If COMPAT is specified, the XML parser that is provided with Enterprise COBOL
Version 3 is used, this option is available to allow for backward compatibility.
In the Enterprise Service Tools single-service projects, the XMLSS option adds improved XML parsing
capabilities, allowing the Compiled XML Conversion to be more efficient and standards compliant. The
enhanced parsing capabilities offered by the XMLSS option includes the following:
• Direct parsing of UTF-8,
• XML Namespaces support.

332 Developer for z/OS: Developing with Db2, CICS, and IMS
 • Pull-parsing of XML fragments (a complete XML document is buffered and is parsed one fragment at a
time from a file or memory).
In the Enterprise Service Tools single-service projects, the XMLSS option removes the following
limitations present in the COMPAT option:
1. Parsing of UTF-8 requires an up-front, expensive, twice-executed, codepage conversion.
2. XML Namespace information is ignored - preventing the XML to language structure converter from
being able to disambiguate elements having identical names but different target namespaces.

Generation of Enterprise Service Tools artifacts to remote systems

This topic describes the ability to generate Enterprise Service Tools artifacts to remote systems (currently
MVS, or z/OS UNIX) using Enterprise Service Tools project.
Note: This is only applicable to single service Enterprise Service Tools projects.

The ability to generate Enterprise Service Tools artifacts to remote systems (currently MVS, or z/OS UNIX)
using Enterprise Service Tools project is supported by selecting a remote location.

Selecting a Remote Location

Selection of the remote system is provided by performing the following:
1. Choosing the Remote location button. When Remote location is specified the Browse... button is
enabled.
2. Selection of the Browse... opens a remote browse dialog where the user can select a remote file
container.

Table 50 on page 333 describes the valid remote destinations for various Enterprise Service Tools artifact
and also supplies the validation rules.

Table 50. Valid Remote Destination Rules

Target
Enterprise Service Tools
Artifact System PDS in MVS Sub-
Projects System Directory in z/OS UNIX
Does not allow an invalid Checks if the user has write
member name. access.
PDS selected must have record Does not allow an invalid File
COBOL or PL/I type of F or FB name.
Acceptable characters are: A-Z a-
z 0-9 . / _

Checks if the user has write

access.
Does not allow an invalid File
XSD/WSDL Not applicable name.
Acceptable characters are: A-Z a-
z 0-9 . / _

Developing web services and SOA with Enterprise Service Tools 333
 Table 50. Valid Remote Destination Rules (continued)
Target
Enterprise Service Tools
Artifact System PDS in MVS Sub-
Projects System Directory in z/OS UNIX
Checks if the user has write
access.
Does not allow an invalid File
WSBind Not applicable name.
Acceptable characters are: A-Z a-
z 0-9 . / _

Does not allow an invalid Checks if the user has write

member name. access.
PDS selected must have record Does not allow an invalid File
XML Correlator type of VB or VBA name.
Acceptable characters are: A-Z a-
z 0-9 . / _

Selecting the remote files in the generated project

To open the remote file in the default editor (i.e., LPEX for COBOL/PLI, WSBind Viewer for wsbind file, etc),
double-click the remote file. During opening of the remote file, if the associated system is not connected,
the user is prompted with username/password dialog.
When the remote file is selected, the file location information for the file is displayed in the properties
view.

Limitations
The following are the limitations of this capability:
1. The generation properties files cannot be used in batch mode.
2. Generating to z/OS UNIX sub-projects is not supported.

Reference information for single-service projects

This section contains reference information for single-service projects.

Web Service Binding File Viewer

The Web Service binding file (WSBind) viewer is an Eclipse based viewer that makes visible the values of
user specified options in a WSBind file.
The viewer is the default viewer for *.wsbind files. The viewer opens automatically when the user double-
clicks on WSBind files in the workspace, or the viewer is launched when you right click an WSBind file in
the workspace and then open with the menu selection "WSBind Viewer".
The Text color preference as assigned in the section of the Web Services Assistant. When WSBind viewer
is opened, Text color value is used to display all values.
The following option values are displayed:
• In the Maintenance Information group:
Time Stamp:
A timestamp for the time that the WSBind file was created.

334 Developer for z/OS: Developing with Db2, CICS, and IMS
 Product:
This is the product version used to generate the WSBind file.

• In the Service Interface and Pipeline Properties group:

Service Mode:
The mode of the Web service represented by the WSBind file, the value can have one of two modes,
either Service Provider or Service Requestor.
Provider URI:
The URI associated with the Service Provider mode Web service. If the WSBind file is for a Service
Requester mode Web Service then nothing is displayed/editable.
Requester URI:
The URI associated with the Service Requester mode. If the WSBind file is for a Service Provider
mode Web service then nothing is displayed/editable.
WSDL binding name:
The local name of the WSDL binding that the WSBind file is associated with.
Operations:
The list of WSDL operation names that the WSBind file supports.
Transaction ID:
For a Service Provider mode Web service, this is the transaction identifier used when a URIMAP is
created during a scan of the pipeline.
User ID:
For a Service Provider mode Web service, this is the optional user identifer used when a URIMAP is
created during a scan of the pipeline.
Syncpoint:
Indicates whether the remote web service can issue a syncpoint.
• In the Required Runtime and Mapping Levels group:
Mapping level:
This field displays the mapping level setting that was in effect when the WSBind file was generated
(see “Setting preferences for the CICS Web Services Assistant (WSBind)” on page 150 and “Setting
preferences for the CICS XML Transformation Assistant (XSDBind)” on page 167). This field can also
display one of the following values:
– XML-ONLY: Indicates that the XML-ONLY option was set for the assistant (see Pass-through XML
and XML-ONLY).
– Vendor mapping: Indicates that this is a vendor-style WSBind file.
Minimum Runtime Level:
The Minimum Runtime Level setting for the WSBind file. This level represents the platform
requirements the WSBind file has on the underlying CICS version. A WSBind file cannot be installed
into a version of CICS that does not support the required minimum runtime level.
Minimum Runtime Level:
The Minimum Runtime Level setting for the WSBind file. This level represents the platform
requirements the WSBind file has on the underlying CICS version. A WSBind file cannot be installed
into a version of CICS that does not support the required minimum runtime level.
• In the Target Program Interface and Properties group:
Program name:
The program name of the CICS program that implements this Service Provider mode Web service.
This value is not displayed in Service Requester mode.
Program Interface:
The program interface for the Service Provider mode Web service. If the WSBind file is for a Service
Requester mode Web service then REQUESTER is displayed.

Developing web services and SOA with Enterprise Service Tools 335
 Container name:
If the program interface for a Service Provider mode Web service is CHANNEL, then this is the name
of the container where the application data is stored.
Request Channel:
The name of the Request Channel Description Document.
Response Channel:
The name of the Response Channel Description Document.
Vendor Converter name:
Name of the converter program to which CICS delegates language structure and XML conversion for
this Web service This value is set for the Compiled XML Conversion type.

Web Service Binding File Editor

The Web Service binding file (WSBind) editor is an Eclipse based editor that allows users to see and
change user specified options in a WSBind file.
The WSBind editor is the default editor for *.wsbind files. The editor is launched when you right click a
WSBind file in the workspace and then open with the menu selection "WSBind Editor". The WSBind editor
is an enhancement to the WSBind viewer, “Web Service Binding File Viewer” on page 334 . A double click
on the *.wsbind file opens the WSBind viewer.
Note: When opening the WSBind editor, warning dialog opens to warn of a synchronization conflict, when
ALL of the following conditions exist:
1. The WSBind file is in Enterprise Service Tools project.
2. The WSBind file is saved.
3. The values of any changed properties are stored in another generation properties file (for example, the
ServiceSpecification.xml file).
The WSBind editor has a Text Color preference as assigned in the section of the Web Services Assistant.
When the WSBind editor is opened, this is the assigned color is used to display editable values.
The available menu selections are standard Eclipse menus, however certain options (such as Print, Find,
and Replace) are not supported.
The following is a list of the fields displayed in the WSBind editor. This is a listing of fields in the display
and details if the field is or is not editable. For a description of the fields refer to “Web Service Binding File
Viewer” on page 334.
• Time Stamp - Editable? - NO
• Product - Editable? - NO
• Service Mode - Editable? - NO
• Provider URI - Editable? - YES
• Requester URI - Editable? - YES
• WSDL binding name - Editable? - NO
• Operations - Editable? - NO
• Transaction ID - Editable? - YES
• User ID - Editable? - YES
• Syncpoint - Editable? - YES:
• Mapping level - Editable? - NO
• Runtime level - Editable? - NO
• Program name - Editable? - YES
• Program Interface - Editable? - NO
• Container name - Editable - NO
• Request Channel - Editable - NO

336 Developer for z/OS: Developing with Db2, CICS, and IMS
 • Response Channel - Editable - NO
• Vendor Converter name - Editable - YES

XML to COBOL mapping reference

This group of topics provides reference information about mappings between XML Schema data types and
Enterprise COBOL data types.

XML Schema data types

This topic shows the built-in primitive and derived XML Schema data types and the values of their facets.

Table 51. Values of the fundamental facets for XML Schema built-in primitive data types
Primitive
Data type ordered bounded cardinality numeric
string false false countably infinite false
boolean false false finite false
float total true finite true
double total true finite true
decimal total false countably infinite true
duration partial false countably infinite false
dateTime partial false countably infinite false
time partial false countably infinite false
date partial false countably infinite false
gYearMonth partial false countably infinite false
gYear partial false countably infinite false
gMonthDay partial false countably infinite false
gDay partial false countably infinite false
gMonth partial false countably infinite false
hexBinary false false countably infinite false
base64Binary false false countably infinite false
anyURI false false countably infinite false
QName false false countably infinite false
NOTATION false false countably infinite false

Table 52. Values of the fundamental facets for XML Schema built-in derived data types
Derived
Data type ordered bounded cardinality numeric
normalizedString false false countably infinite false

Developing web services and SOA with Enterprise Service Tools 337
 Table 52. Values of the fundamental facets for XML Schema built-in derived data types (continued)
Derived
Data type ordered bounded cardinality numeric
token false false countably infinite false
language false false countably infinite false
IDREFS false false countably infinite false
ENTITIES false false countably infinite false
NMTOKEN false false countably infinite false
NMTOKENS false false countably infinite false
Name false false countably infinite false
NCName false false countably infinite false
ID false false countably infinite false
IDREF false false countably infinite false
ENTITY false false countably infinite false
integer total false countably infinite true
nonPositiveInteger total false countably infinite true
negativeInteger total false countably infinite true
long total true finite true
int total true finite true
short total true finite true
byte total true finite true
nonNegativeInteger total false countably infinite true
unsignedLong total true finite true
unsignedInt total true finite true
unsignedShort total true finite true
unsignedByte total true finite true
positiveInteger total false countably infinite true

Enterprise COBOL data types

This topic shows the levels, classes, and categories of data types in Enterprise COBOL for z/OS.

These data types are described in the Enterprise COBOL for z/OS reference manual.

338 Developer for z/OS: Developing with Db2, CICS, and IMS
Table 53. Enterprise COBOL type classes and categories
Level of item Class Category
Elementary Alphabetic Alphabetic
Numeric Numeric
Internal floating-point
External floating-point
Alphanumeric Numeric-edited
Alphanumeric-edited
Alphanumeric
DBCS
National National
Group Alphanumeric Alphabetic
Numeric
Internal floating-point
External floating-point
Numeric-edited
Alphanumeric-edited
Alphanumeric
DBCS
National

Compatibility: Simple data types

This topic describes the compatibility of Enterprise COBOL data classes and categories with simple XML
Schema built-in primitive and derived data types.
Note: Note that you cannot map a COBOL data item that does not have a category and class (for example,
PROCEDURE POINTER).

Table 54 on page 339 shows the compatibility of simple built-in primitive data types:

Table 54. Compatibility of simple XML Schema built-in primitive data types
Default Language
Default XML to
COBOL data Class or Structure to XML
XML Datatype Language Structure
Category Conversion (See Note
Conversion
1)
Alphabetic,
Alphanumeric, National,
string DBCS, Numeric, MOVE, NUMVAL MOVE
Numeric edited (See
Note 2)
boolean Alphabetic, Numeric MOVE, NUMVAL MOVE

Developing web services and SOA with Enterprise Service Tools 339
 Table 54. Compatibility of simple XML Schema built-in primitive data types (continued)
Default Language
Default XML to
COBOL data Class or Structure to XML
XML Datatype Language Structure
Category Conversion (See Note
Conversion
1)
Numeric, Numeric-
float MOVE, NUMVAL MOVE
edited
Numeric, Numeric-
double MOVE, NUMVAL MOVE
edited
Numeric, Numeric-
decimal MOVE, NUMVAL MOVE
edited
duration Alphanumeric, National N/A N/A
dateTime Alphanumeric, National N/A N/A
time Alphanumeric, National N/A N/A
date Alphanumeric, National N/A N/A
gYearMonth Alphanumeric, National N/A N/A
gYear Alphanumeric, National N/A N/A
gMonthDay Alphanumeric, National N/A N/A
gDay Alphanumeric, National N/A N/A
gMonth Alphanumeric, National N/A N/A
hexBinary Alphanumeric, National N/A N/A
base64Binary Alphanumeric, National N/A N/A
anyURI Alphanumeric, National N/A N/A
QName Alphanumeric, National N/A N/A
NOTATION Alphanumeric, National N/A N/A

Note:
1. The mapping tools will not enforce matching rules for user-defined simple XML schema types that
are derived by constraint. For example, if for a base="int", the user defined type has a constraint of
minInclusive value="-99" we may not be able to enforce the minInclusive constraint.
2. Valid MOVEs between numeric and non-numeric types in XML and COBOL follow the rules described
in the COBOL Language Reference Manual.

Table 55 on page 340 shows the compatibility of simple built-in derived data types:

Table 55. Compatibility of simple XML Schema built-in derived data types
Default Language
Default XML to
COBOL data Class or Structure to XML
XML Datatype Language Structure
Category Conversion (See Note
Conversion
1)
Alphabetic,
normalizedString N/A N/A
Alphanumeric, National
Alphabetic,
token N/A N/A
Alphanumeric, National

340 Developer for z/OS: Developing with Db2, CICS, and IMS
Table 55. Compatibility of simple XML Schema built-in derived data types (continued)
Default Language
Default XML to
COBOL data Class or Structure to XML
XML Datatype Language Structure
Category Conversion (See Note
Conversion
1)
Alphabetic,
language N/A N/A
Alphanumeric, National
Alphabetic,
IDREFS N/A N/A
Alphanumeric, National
Alphabetic,
ENTITIES N/A N/A
Alphanumeric, National
Alphabetic,
NMTOKEN N/A N/A
Alphanumeric, National
Alphabetic,
NMTOKENS N/A N/A
Alphanumeric, National
Alphabetic,
Name N/A N/A
Alphanumeric, National
Alphabetic,
NCName N/A N/A
Alphanumeric, National
Alphabetic,
ID N/A N/A
Alphanumeric, National
Alphabetic,
IDREF N/A N/A
Alphanumeric, National
Alphabetic,
ENTITY N/A N/A
Alphanumeric, National
Numeric, Alphanumeric
integer (See Note 2), Numeric- MOVE, NUMVAL MOVE
edited
Numeric, Alphanumeric
nonPositiveInteger (See Note 2), Numeric- MOVE, NUMVAL MOVE
edited
Numeric, Alphanumeric
negativeInteger (See Note 2), Numeric- MOVE, NUMVAL MOVE
edited
Numeric, Alphanumeric
long (See Note 2), Numeric- MOVE, NUMVAL MOVE
edited
Numeric, Alphanumeric
int (See Note 2), Numeric- MOVE, NUMVAL MOVE
edited
Numeric, Alphanumeric
short (See Note 2), Numeric- MOVE, NUMVAL MOVE
edited
Numeric, Alphanumeric
byte (See Note 2), Numeric- MOVE, NUMVAL MOVE
edited

Developing web services and SOA with Enterprise Service Tools 341
 Table 55. Compatibility of simple XML Schema built-in derived data types (continued)
Default Language
Default XML to
COBOL data Class or Structure to XML
XML Datatype Language Structure
Category Conversion (See Note
Conversion
1)
Numeric, Alphanumeric
nonNegativeInteger (See Note 2), Numeric- MOVE, NUMVAL MOVE
edited
Numeric, Alphanumeric
unsignedLong (See Note 2), Numeric- MOVE, NUMVAL MOVE
edited
Numeric, Alphanumeric
unsignedInt (See Note 2), Numeric- MOVE, NUMVAL MOVE
edited
Numeric, Alphanumeric
unsignedShort (See Note 2), Numeric- MOVE, NUMVAL MOVE
edited
Numeric, Alphanumeric
unsignedByte (See Note 2), Numeric- MOVE, NUMVAL MOVE
edited
Numeric, Alphanumeric
positive-Integer (See Note 2), Numeric- MOVE, NUMVAL MOVE
edited

Note:
1. The mapping tools will not enforce matching rules for user-defined simple XML schema types that
are derived by constraint. For example, if for a base="int", the user defined type has a constraint of
minInclusive value="-99" we may not be able to enforce the minInclusive constraint.
2. Valid MOVEs between numeric and non-numeric types in XML and COBOL follow the rules described
in the COBOL Language Reference Manual.

Compatibility: Enterprise COBOL groups and repeating items

This topic describes the compatibility of groups and repeating items in Enterprise COBOL for z/OS with
XML structures.

Compatibility is supported for mapping elementary COBOL groups and data items to simple XML
structures. Selecting or mapping OCCURS DEPENDING ON (ODO) objects is not required in bottom-up or
meet-in-middle scenarios when using Compiled XML Conversion. Table 56 on page 343 shows examples
of compatible items:

342 Developer for z/OS: Developing with Db2, CICS, and IMS
Table 56. Examples of compatible items
Enterprise COBOL group or
repeating item: Sample compatible XML structure:
COBOL Group:
<complexType name="groups_simplegroup">
<sequence>
2 SimpleGroup <element name="deposit_request1">
3 DEPOSIT-REQUEST1 PIC X. <annotation>
<appinfo source="http://www.wsadie.com/appinfo">
<initialValue kind="SPACE"/>
</appinfo>
</annotation>
<simpleType>
<restriction base="string">
<maxLength value="1"/>
</restriction>
</simpleType>
</element>
</sequence>
</complexType>

COBOL Nested groups:

<complexType name="groups_nestedgroup">
<sequence>
2 NestedGroup. <element name="SimpleItem">
3 SimpleItem pic 9. <simpleType>
3 NestingGroup1. <restriction base="short">
5 DEPOSIT-REQUEST2 PIC X. <minInclusive value="0"/>
5 Action-Code2 PIC 999. <maxInclusive value="9"/>
</restriction>
</simpleType>
</element>
<element name="NestingGroup1"
type="cbl:groups_nestedgroup_nestinggroup1"/>
</sequence>
</complexType>
<complexType name="groups_nestedgroup_nestinggroup1">
<sequence>
<element name="deposit_request2">
<annotation>
<appinfo source="http://www.wsadie.com/appinfo">
<initialValue kind="SPACE"/>
</appinfo>
</annotation>
<simpleType>
<restriction base="string">
<maxLength value="1"/>
</restriction>
</simpleType>
</element>
<element name="Action_Code2">
<simpleType>
<restriction base="short">
<minInclusive value="0"/>
<maxInclusive value="999"/>
</restriction>
</simpleType>
</element>
</sequence>
</complexType>

COBOL OCCURS - fixed length array

<element maxOccurs="7" minOccurs="7" name="SimpleArray">
(elementary item): <annotation>
<appinfo source="http://www.wsadie.com/appinfo">
2 SimpleArray occurs 7 times <initialValue kind="SPACE"/>
PIC A. </appinfo>
</annotation>
<simpleType>
<restriction base="string">
<maxLength value="1"/>
</restriction>
</simpleType>
</element>

Developing web services and SOA with Enterprise Service Tools 343
Table 56. Examples of compatible items (continued)
Enterprise COBOL group or
repeating item: Sample compatible XML structure:
COBOL OCCURS - fixed length array
<element maxOccurs="7" minOccurs="7" name="RepeatingGroup"
(group item): type="cbl:Groups_repeatinggroup"/>
<complexType name="Groups_repeatinggroup">
2 RepeatingGroup occurs 7 times. <sequence>
3 DEPOSIT-REQUEST3 PIC X. <sequence>
<element name="deposit_request3">
<annotation>
<appinfo source="http://www.wsadie.com/appinfo">
<initialValue kind="SPACE"/>
</appinfo>
</annotation>
<simpleType>
<restriction base="string">
<maxLength value="1"/>
</restriction>
</simpleType>
</element>
</sequence>
</sequence>
</complexType>

COBOL OCCURS DEPENDING ON -

<element maxOccurs="5" minOccurs="0" name="ODOSimpleArray">
variable length array (elementary <annotation>
item): <appinfo source="http://www.wsadie.com/appinfo">
<dependingOn>depending-on model reference</dependingOn>
</appinfo>
2 Odo-Count PIC 9. </annotation>
2 ODOSimpleArray occurs 0 to 5 <simpleType>
depending on Odo-Count pic <restriction base="short">
9. <minInclusive value="0"/>
<maxInclusive value="9"/>
The following code is generated when </restriction>
</simpleType>
an ODO object is selected as the </element>
interface.

<dependingOn>depending-on model
reference</dependingOn>

344 Developer for z/OS: Developing with Db2, CICS, and IMS
Table 56. Examples of compatible items (continued)
Enterprise COBOL group or
repeating item: Sample compatible XML structure:
COBOL OCCURS DEPENDING ON -
<element maxOccurs="7" minOccurs="0" name="RepeatingGroupODO"
variable length array (group item): type="cbl:Groups_repeatinggroupodo">
<annotation>
2 RepeatingGroupODO occurs <appinfo source="http://www.wsadie.com/appinfo">
0 to 7 times <dependingOn>depending-on model reference</dependingOn>
depending on Odo-Count1. </appinfo>
3 DEPOSIT-REQUEST4 PIC X. </annotation>
3 Action-Code PIC 999. </element>

<complexType name="Groups_repeatinggroupodo">
The following code is generated when <sequence>
an ODO object is selected as the <sequence>
<element name="deposit_request4">
interface. <annotation>
<appinfo source="http://www.wsadie.com/appinfo">
<dependingOn>depending-on model <initialValue kind="SPACE"/>
reference</dependingOn> </appinfo>
</annotation>
<simpleType>
<restriction base="string">
<maxLength value="1"/>
</restriction>
</simpleType>
</element>
<element name="Action_Code">
<simpleType>
<restriction base="short">
<minInclusive value="0"/>
<maxInclusive value="999"/>
</restriction>
</simpleType>
</element>
</sequence>
</sequence>
</complexType>

XML data types derived from Enterprise COBOL data types

This topic describes how the COBOL-to-XML converter generators derive XML schema data types from
Enterprise COBOL for z/OS data types.

Table 57. COBOL to XML type derivation

COBOL Type COBOLUsageValue+ Corresponding XSD Type
COBOL ModelType
properties
COBOL Alphabetic Type
<xsd:simpleType>
<restriction base="xsd:string">
05 Fname PIC A(20).) <length value="n"/>
</restriction>
</simpleType>

COBOL Alphanumeric Type

<xsd:simpleType>
<restriction base="xsd:string">
<length value="n"/>
</restriction>
</simpleType>

Developing web services and SOA with Enterprise Service Tools 345
Table 57. COBOL to XML type derivation (continued)
COBOL Type COBOLUsageValue+ Corresponding XSD Type
COBOL ModelType
properties
COBOL Numeric Type Display/binary
<xsd:simpleType>
+decimal <xsd:restriction base="xsd:decimal">
display, binary, comp, comp-4, <xsd:minInclusive value="xx.x"/>
comp-5 ->display/binary <xsd:maxInclusive value="yy.y"/>
</xsd:restriction>
</xsd:simpleType>

Display/binary
<xsd:simpleType>
+~decimal + number <xsd:restriction base="xsd:short">
of nines <= 4 + sign <xsd:minInclusive value="xx"/>
<xsd:maxInclusive value="yy"/>
</xsd:restriction>
</xsd:simpleType>

Display/binary
<xsd:simpleType>
+~decimal + 4 <xsd:restriction base="xsd:int">
<number of nines <= <xsd:minInclusive value="xx"/>
<xsd:maxInclusive value="yy"/>
9+ sign </xsd:restriction>
</xsd:simpleType>

COBOL Numeric Type Display/binary

<xsd:simpleType>
+~decimal + 9 <xsd:restriction base="xsd:long">
Display, binary, comp, comp-4,
<number of nines <xsd:minInclusive value="xx"/>
comp-5 ->display/binary <xsd:maxInclusive value="yy"/>
+sign </xsd:restriction>
</xsd:simpleType>

Display/binary
<xsd:simpleType>
+~decimal + number <xsd:restriction base="xsd:short">
of nines <= 4 + no <xsd:minInclusive value="xx"/>
<xsd:maxInclusive value="yy"/>
sign </xsd:restriction>
</xsd:simpleType>

Display/binary
<xsd:simpleType>
+~decimal + 4 <xsd:restriction base="xsd:int">
<number of nines <= <xsd:minInclusive value="xx"/>
<xsd:maxInclusive value="yy"/>
9+ no sign </xsd:restriction>
</xsd:simpleType>

Display/binary
<xsd:simpleType>
+~decimal + 9 <xsd:restriction base="xsd:long">
<number of nines + <xsd:minInclusive value="xx"/>
<xsd:maxInclusive value="yy"/>
nosign </xsd:restriction>
</xsd:simpleType>

346 Developer for z/OS: Developing with Db2, CICS, and IMS
Table 57. COBOL to XML type derivation (continued)
COBOL Type COBOLUsageValue+ Corresponding XSD Type
COBOL ModelType
properties
packed-decimal, comp-3 -> packedDecimal If the decimal point is specified:
packedDecimal
<xsd:simpleType>
<xsd:restriction base="xsd:decimal">
<xsd:minInclusive value="xx.x"/>
<xsd:maxInclusive value="yy.y"/>
</xsd:restriction>
</xsd:simpleType>

If the decimal point is not specified:

<xsd:simpleType>
<xsd:restriction base="xsd:short">
<xsd:minInclusive value="xxx"/>
<xsd:maxInclusive value="yyy"/>
</xsd:restriction>
</xsd:simpleType>

comp-1 -> float float

<xsd:simpleType>
<xsd:restriction base="xsd:float">
<xsd:minInclusive value="xx.x"/>
<xsd:maxInclusive value="yy.y"/>
</xsd:restriction>
</xsd:simpleType>

comp-2 -> double double

xsd:simpleType>
<xsd:restriction base="xsd:double">
<xsd:minInclusive value="xx.x"/>
<xsd:maxInclusive value="yy.y"/>
</xsd:restriction>
</xsd:simpleType>

COBOL Alphanumeric-edited
<xsd:simpleType>
Type <restriction base="string">
<length value="n"/>
</restriction>
</simpleType>

COBOL Numeric-edited Type

<xsd:simpleType>
<restriction base="string">
<length value="n"/>
</restriction>
</simpleType>

COBOL DBCS Type DBCS

<xsd:simpleType>
<restriction base="string">
<length value="n"/>
</restriction>
</simpleType>

COBOL External floating point

<xsd:simpleType>
Type <restriction base="string">
<length value="n"/>
</restriction>
</simpleType>

COBOL National (Unicode) Type Data stored in

Unicode format

Developing web services and SOA with Enterprise Service Tools 347
Table 57. COBOL to XML type derivation (continued)
COBOL Type COBOLUsageValue+ Corresponding XSD Type
COBOL ModelType
properties
COBOL Address Type - not supported -
COBOL Object reference Type - not supported -

COBOL Level 88 <xsd:element name="TXN_Resp_Code">

<xsd:annotation>
<xsd:appinfo>
05 TXN-Resp-Code PIC X(3) <level88>Business_Code value "AAA" THRU "XXX"
88 Business-Code </level88>
<level88>Business_Error value "XYX" THRU "ZYX"
value "AAA" THRU "XXX" </level88>
88 Business-Error <level88>Completed_Code value "COM"</level88>
value "XYX" THRU "ZYX" <level88></level88>
<level88></level88>
88 Completed-Code </xsd:appinfo>
value "COM" </xsd:annotation>
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:length value="3"/>
</xsd:restriction>
</xsd:simpleType>
</xsd:element>

Isomorphic and non-isomorphic element mapping for COBOL

Table 58 on page 348 and Figure 29 on page 348 and Figure 30 on page 349 are isomorphic structures
(an XML instance document and a COBOL language structure) and both have isomorphic element
mapping:

Table 58. Example 1 XML Instance of Isomorphic Structure with Isomorphic Element Mapping for COBOL
XML Instance COBOL Data Structure

<x1> 1 A,
<x2>2</x2> 2 B pic 9,
<x3> 2 C,
<x4>4</x4> 3 D pic 9;
</x3>
</x1>

Figure 29. Display 1 XML Instance of Isomorphic Structure with Isomorphic Element Mapping for COBOL

348 Developer for z/OS: Developing with Db2, CICS, and IMS
Figure 30. Example 1 of XML Instance Isomorphic Structure with Isomorphic Element Mapping for COBOL

Table 59 on page 349 and Figure 31 on page 349are two non-isomorphic structures (an XML instance
document and a COBOL language structure) have isomorphic subsets and show isomorphic element
mapping:

Table 59. Example 2 XML Instance of Non-Isomorphic Structure with Isomorphic Element Mapping for
COBOL
XML Instance COBOL Data Structure

<x1> 1 A,
<x2>2</x2> 2 B pic 9,
<x3> 2 C,
<x4>4</x4> 3 D pic 9;
</x3>
</x1>

Figure 31. Example 2 of XML Instance Non-Isomorphic Structure with Isomorphic Element Mapping for
COBOL

Table 60 on page 350 and Figure 32 on page 350 are two isomorphic structures (an XML instance
document and a COBOL language structure) have non-isomorphic element mapping:

Developing web services and SOA with Enterprise Service Tools 349
 Table 60. Example 3 XML Instance of Isomorphic Structure with Non-Isomorphic Element Mapping for
COBOL
XML Instance COBOL Data Structure

<x1> 1 A,
<x2>2</x2> 2 B pic 9,
<x3> 2 C,
<x4>4</x4> 3 D pic 9;
</x3>
</x1>

Figure 32. Example 3 of XML Instance Isomorphic Structure with Non-Isomorphic Element Mapping for
COBOL

Table 61 on page 350 and Figure 33 on page 351 are two non-isomorphic structures (an XML instance
document and a COBOL language structure) have non-isomorphic element mapping:

Table 61. Example 4 XML Instance of Non-Isomorphic Structure with Non-Isomorphic Element Mapping
for COBOL
XML Instance COBOL Data Structure

<x1> 1 A,
<x2>2</x2> 2 B pic 9,
<x3> 2 C,
<x4>4</x4> 3 D pic 9;
</x3>
</x1>

350 Developer for z/OS: Developing with Db2, CICS, and IMS
 Figure 33. Example 4 of XML Instance Non-Isomorphic Structure with Non-Isomorphic Element Mapping for
COBOL

XML to PL/I mapping reference

This group of topics provides reference information about mappings between XML schema data types and
Enterprise PL/I data types.

XML Schema data types

This topic shows the built-in primitive and derived XML Schema data types and the values of their facets.

Table 62. Values of the fundamental facets for XML Schema built-in primitive data types
Primitive
Data type ordered bounded cardinality numeric
string false false countably infinite false
boolean false false finite false
float total true finite true
double total true finite true
decimal total false countably infinite true
duration partial false countably infinite false
dateTime partial false countably infinite false
time partial false countably infinite false
date partial false countably infinite false
gYearMonth partial false countably infinite false
gYear partial false countably infinite false
gMonthDay partial false countably infinite false
gDay partial false countably infinite false

Developing web services and SOA with Enterprise Service Tools 351
 Table 62. Values of the fundamental facets for XML Schema built-in primitive data types (continued)
Primitive
Data type ordered bounded cardinality numeric
gMonth partial false countably infinite false
hexBinary false false countably infinite false
base64Binary false false countably infinite false
anyURI false false countably infinite false
QName false false countably infinite false
NOTATION false false countably infinite false

Table 63. Values of the fundamental facets for XML Schema built-in derived data types
Derived
Data type ordered bounded cardinality numeric
normalizedString false false countably infinite false
token false false countably infinite false
language false false countably infinite false
IDREFS false false countably infinite false
ENTITIES false false countably infinite false
NMTOKEN false false countably infinite false
NMTOKENS false false countably infinite false
Name false false countably infinite false
NCName false false countably infinite false
ID false false countably infinite false
IDREF false false countably infinite false
ENTITY false false countably infinite false
integer total false countably infinite true
nonPositiveInteger total false countably infinite true
negativeInteger total false countably infinite true
long total true finite true
int total true finite true
short total true finite true
byte total true finite true
nonNegativeInteger total false countably infinite true
unsignedLong total true finite true
unsignedInt total true finite true
unsignedShort total true finite true

352 Developer for z/OS: Developing with Db2, CICS, and IMS
Table 63. Values of the fundamental facets for XML Schema built-in derived data types (continued)
Derived
Data type ordered bounded cardinality numeric
unsignedByte total true finite true
positiveInteger total false countably infinite true

Enterprise PL/I variable types

This topic describes the variable types and data attributes of Enterprise PL/I for z/OS that are supported
by the single-service mapping tools and processes.

These types and attributes are described in the Enterprise COBOL for z/OS reference manual.

Table 64. Enterprise PL/I language variable types and data attributes
Variable Type Data Attributes
Area AREA(size)
Coded arithmetic REAL | COMPLEX
FLOAT | FIXED
BINARY | DECIMAL
PRECISION
[SIGNED | UNSIGNED]
Entry ENTRY [RETURNS]
[LIMITED]
File FILE
Format FORMAT
Label LABEL
Locator POINTER | HANDLE |
{OFFSET [(area-variable)]}
Ordinal ORDINAL
Picture PICTURE
REAL | COMPLEX
String BIT | CHARACTER | GRAPHIC | WIDECHAR
[(length)]
[ VARYING | VARYINGZ | NONVARYING]
Task TASK

Arrays: DIMENSION can be added to the declaration of any variable.

Structures and unions:
• For a major structure or union: scope, storage (except INITIAL), alignment, STRUCTURE or UNION, and
the LIKE attributes can be specified.

Developing web services and SOA with Enterprise Service Tools 353
 • For a member that is a structure or a union: alignment, STRUCTURE or UNION, and the LIKE attributes
can be specified.
• Members always have the INTERNAL scope attribute.

Compatibility: Simple data types

This topic describes the compatibility of Enterprise PL/I data types and data attributes with simple XML
Schema built-in primitive and derived data types.

Table 65 on page 354 shows the compatibility of simple built-in primitive data types:

Table 65. Compatibility of simple XML Schema built-in primitive data types
Default Response
Default Request
XML Datatype PL/I Data Attribute Conversion (See Note 1
Conversion (See Note 1)
and 2)
CHARACTER, GRAPHIC,
string memConvert, = memConvert, =
WIDECHAR, BIT
CHARACTER,
boolean memConvert, = memConvert, =
WIDECHAR, BIT
string PICTURE memConvert, PICSEC, = memConvert, =
boolean PICTURE memConvert, PICSEC, = memConvert, =
string FLOAT, FIXED = =
boolean FIXED = =
float FLOAT = =
double FLOAT = =
decimal FIXED = =
CHARACTER, GRAPHIC,
duration N/A N/A
WIDECHAR
CHARACTER, GRAPHIC,
dateTime N/A N/A
WIDECHAR
CHARACTER, GRAPHIC,
time N/A N/A
WIDECHAR
CHARACTER, GRAPHIC,
date N/A N/A
WIDECHAR
CHARACTER, GRAPHIC,
gYearMonth N/A N/A
WIDECHAR
CHARACTER, GRAPHIC,
gYear N/A N/A
WIDECHAR
CHARACTER, GRAPHIC,
gMonthDay N/A N/A
WIDECHAR
CHARACTER, GRAPHIC,
gDay N/A N/A
WIDECHAR
CHARACTER, GRAPHIC,
gMonth N/A N/A
WIDECHAR

354 Developer for z/OS: Developing with Db2, CICS, and IMS
Table 65. Compatibility of simple XML Schema built-in primitive data types (continued)
Default Response
Default Request
XML Datatype PL/I Data Attribute Conversion (See Note 1
Conversion (See Note 1)
and 2)
BIT, GRAPHIC,
hexBinary memConvert, = memConvert, =
WIDECHAR
CHARACTER, GRAPHIC,
base64Binary N/A N/A
WIDECHAR
CHARACTER, GRAPHIC,
anyURI N/A N/A
WIDECHAR
CHARACTER, GRAPHIC,
QName N/A N/A
WIDECHAR
CHARACTER, GRAPHIC,
NOTATION N/A N/A
WIDECHAR

Note:
1. The functions: memConvert and PICSEC are build-in functions provided by the PL/I compiler. The
function: = is a normal PL/I assignment statement.
2. The mapping tools do not enforce matching rules for user-defined simple XML schema types that
are derived by constraint. For example, if for a base="int", the user defined type has a constraint of
minInclusive value="-99" it may not be possible to enforce the minInclusive constraint.

Table 66 on page 355 shows the compatibility of simple built-in derived data types:

Table 66. Compatibility of simple XML Schema built-in derived data types
Default Response
Default Request
XML Datatype PL/I Data Attribute Conversion (See notes
Conversion (See note 1)
1 and 2)
CHARACTER, GRAPHIC,
normalizedString N/A N/A
WIDECHAR
CHARACTER, GRAPHIC,
token N/A N/A
WIDECHAR
CHARACTER, GRAPHIC,
language N/A N/A
WIDECHAR
CHARACTER, GRAPHIC,
IDREFS N/A N/A
WIDECHAR
CHARACTER, GRAPHIC,
ENTITIES N/A N/A
WIDECHAR
CHARACTER, GRAPHIC,
NMTOKEN N/A N/A
WIDECHAR
CHARACTER, GRAPHIC,
NMTOKENS N/A N/A
WIDECHAR
CHARACTER, GRAPHIC,
Name N/A N/A
WIDECHAR

Developing web services and SOA with Enterprise Service Tools 355
 Table 66. Compatibility of simple XML Schema built-in derived data types (continued)
Default Response
Default Request
XML Datatype PL/I Data Attribute Conversion (See notes
Conversion (See note 1)
1 and 2)
CHARACTER, GRAPHIC,
NCName N/A N/A
WIDECHARl
CHARACTER, GRAPHIC,
ID N/A N/A
WIDECHAR
CHARACTER, GRAPHIC,
IDREF N/A N/A
WIDECHAR
CHARACTER, GRAPHIC,
ENTITY N/A N/A
WIDECHAR
CHARACTER,
integer memConvert, = memConvert, =
WIDECHAR
CHARACTER,
nonPositiveInteger memConvert, = memConvert, =
WIDECHAR
CHARACTER,
negativeInteger memConvert, = memConvert, =
WIDECHAR
CHARACTER,
long memConvert, = memConvert, =
WIDECHAR
CHARACTER,
int memConvert, = memConvert, =
WIDECHAR
CHARACTER,
short memConvert, = memConvert, =
WIDECHAR
CHARACTER,
byte memConvert, = memConvert, =
WIDECHAR
CHARACTER,
nonNegativeInteger memConvert, = memConvert, =
WIDECHAR
CHARACTER,
unsignedLong memConvert, = memConvert, =
WIDECHAR
CHARACTER,
unsignedInt memConvert, = memConvert, =
WIDECHAR
CHARACTER,
unsignedShort memConvert, = memConvert, =
WIDECHAR
CHARACTER,
unsignedByte memConvert, = memConvert, =
WIDECHAR
CHARACTER,
positive-Integer memConvert, = memConvert, =
WIDECHAR
integer PICTURE memConvert, PICSEC, = memConvert, =
nonPositiveInteger PICTURE memConvert, PICSEC, = memConvert, =
negativeInteger PICTURE memConvert, PICSEC, = memConvert, =
long PICTURE memConvert, PICSEC, = memConvert, =
int PICTURE memConvert, PICSEC, = memConvert, =

356 Developer for z/OS: Developing with Db2, CICS, and IMS
Table 66. Compatibility of simple XML Schema built-in derived data types (continued)
Default Response
Default Request
XML Datatype PL/I Data Attribute Conversion (See notes
Conversion (See note 1)
1 and 2)
short PICTURE memConvert, PICSEC, = memConvert, =
byte PICTURE memConvert, PICSEC, = memConvert, =
nonNegativeInteger PICTURE memConvert, PICSEC, = memConvert, =
unsignedLong PICTURE memConvert, PICSEC, = memConvert, =
unsignedInt PICTURE memConvert, PICSEC, = memConvert, =
unsignedShort PICTURE memConvert, PICSEC, = memConvert, =
unsignedByte PICTURE memConvert, PICSEC, = memConvert, =
positive-Integer PICTURE memConvert, PICSEC, = memConvert, =
integer FIXED = =
nonPositiveInteger FIXED = =
negativeInteger FIXED = =
long FIXED = =
int FIXED = =
short FIXED = =
byte FIXED = =
nonNegativeInteger FIXED = =
unsignedLong FIXED = =
unsignedInt FIXED = =
unsignedShort FIXED = =
unsignedByte FIXED = =
positive-Integer FIXED = =

Note:
1. The functions: memConvert and PICSEC are built-in functions provided by the PL/I compiler. The
function: = is a normal PL/I assignment statement.
2. The mapping tools do not enforce matching rules for user-defined simple XML schema types that
are derived by constraint. For example, if for a base="int", the user defined type has a constraint of
minInclusive value="-99" it may not be possible to enforce the minInclusive constraint.

Compatibility: Enterprise PL/I structures

This topic describes the compatibility of structures in Enterprise PL/I for z/OS with XML structures.

Compatibility is supported for mapping elementary PL/I structures to simple XML structures. Table 67 on
page 358 shows examples of compatible items:
Note: The current mapping editor cannot perform the mapping from or to a PL/I multidimensional array
element.

Developing web services and SOA with Enterprise Service Tools 357
Table 67. Examples of compatible items
PL/I structure: Sample compatible XML structure:
PL/I Structure:
<complexType name="structures_simplestructure">
<sequence>
<element name="DEPOSIT_REQUEST1">
2 SimpleStructure, <simpleType>
3 DEPOSIT_REQUEST1 CHAR; <restriction base="string">
<maxLength value="1"/>
</restriction>
</simpleType>
</element>
</sequence>
</complexType>

PL/I Nested Structures:

<complexType name="structures_nestedstructure">
<sequence>
<element name="SIMPLEITEM">
2 NestedStructure, <simpleType>
3 SimpleItem FIXED BIN(15), <restriction base="short"/>
3 NestingStructure1, </simpleType>
5 DEPOSIT_REQUEST2 CHAR, </element>
5 Action_Code2 FIXED <element name="NESTINGSTRUCTURE1"
BIN(15);
type="pli:structures_nestedstructure_nestingstructure1"/>
</sequence>
</complexType>
<complexType
name="structures_nestedstructure_nestingstructure1">
<sequence>
<element name="DEPOSIT_REQUEST2">
<simpleType>
<restriction base="string">
<maxLength value="1"/>
</restriction>
</simpleType>
</element>
<element name="ACTION_CODE2">
<simpleType>
<restriction base="short"/>
</simpleType>
</element>
</sequence>
</complexType>

PL/I one dimensional array:

<element maxOccurs="6" minOccurs="6" name="SIMPLEARRAY">
<simpleType>
<restriction base="int"/>
3 SimpleArray(-2:3) FIXED </simpleType>
BIN(31); </element>

358 Developer for z/OS: Developing with Db2, CICS, and IMS
Table 67. Examples of compatible items (continued)
PL/I structure: Sample compatible XML structure:
PL/I multiple dimensional array:
<complexType name="STRUCTURES">
<sequence>
Note: Not currently supported in <element maxOccurs="6" minOccurs="6" name="MULTIARRAY"
mapping editor. type="pli:ArrayOfArrayOfStructures_multiarray"/>
</sequence>
</complexType>
3 MultiArray(-2:3, -1:1, 3) <complexType name="ArrayOfArrayOfStructures_multiarray">
FIXED BIN(31); <sequence>
<element maxOccurs="3" minOccurs="3"
name="ArrayOfArrayOfStructures_multiarray"
type="pli:ArrayOfStructures_multiarray"/>
</sequence>
</complexType>
<complexType name="ArrayOfStructures_multiarray">
<sequence>
<element maxOccurs="3" minOccurs="3"
name="ArrayOfStructures_multiarray">
<simpleType>
<restriction base="int"/>
</simpleType>
</element>
</sequence>
</complexType>

XML data types derived from Enterprise PL/I data types

This topic describes how the PL/I-to-XML converter generators derive XML schema data types from
Enterprise PL/I for z/OS data types.
Note: PL/I XML converter does not support PICTURE data type with the currency symbol.

Table 68. PL/I to XML type derivation, Fixed Binary and Unsigned Fixed Binary
PL/I Type Corresponding XSD Type

Fixed Binary (n) <xsd:simpleType>

where n <= 7 <xsd:restriction base="xsd:byte"/>
<xsd:simpleType>

Fixed Binary (n) <xsd:simpleType>

where 8 <= n <= 15 <xsd:restriction base="xsd:short"/>
</xsd:simpleType>

Fixed Binary (n) <xsd:simpleType>

where 16 <= n <= 31 <xsd:restriction base="xsd:int"/>
</xsd:simpleType>

Fixed Binary (n) <xsd:simpleType>

where 32 <= n <= 63 <xsd:restriction base="xsd:long"/>
</xsd:simpleType>

Unsigned Fixed Binary (n) <xsd:simpleType>

where n <= 8 <xsd:restriction base="xsd:unsignedByte"/>
</xsd:simpleType>

Unsigned Fixed Binary (n) <xsd:simpleType>

where 9 <= n <= 16 <xsd:restriction base="xsd:unsignedShort"/>
</xsd:simpleType>

Developing web services and SOA with Enterprise Service Tools 359
 Table 68. PL/I to XML type derivation, Fixed Binary and Unsigned Fixed Binary (continued)
PL/I Type Corresponding XSD Type

Unsigned Fixed Binary (n) <xsd:simpleType>

where 17 <= n <= 32 <xsd:restriction base="xsd:unsignedInt"/>
</xsd:simpleType>

Unsigned Fixed Binary (n) <xsd:simpleType>

where 33 <= n <= 64 <xsd:restriction base="xsd:unsignedLong"/>
</xsd:simpleType>

Table 69. PL/I to XML type derivation, Binary Float and Decimal float
PL/I Type Corresponding XSD Type

Binary Float (n) <xsd:simpleType>

where n <= 21 <xsd:restriction base="xsd:float"/>
</xsd:simpleType>

Binary Float (n) <xsd:simpleType>

where 22 <= n <= 53 <xsd:restriction base="xsd:double"/>
</xsd:simpleType>

Decimal Float (n) <xsd:simpleType>

where n <= 6 <xsd:restriction base="xsd:float"/>
</xsd:simpleType>

Decimal Float (n) <xsd:simpleType>

where 7 <= n <= 16 <xsd:restriction base="xsd:double"/>
</xsd:simpleType>

Table 70. PL/I to XML type derivation, Fixed Decimal

PL/I Type Corresponding XSD Type

Fixed Decimal (n, m) <xsd:simpleType>

<xsd:restriction base="xsd:decimal">
<xsd:totalDigits value="n"/>
<xsd:fractionDigits value="m"/>
</xsd:restriction>
</xsd:simpleType>

Table 71. PL/I to XML type derivation, Pic

PL/I Type Corresponding XSD Type

Pic '(n)9' <xsd:simpleType>

Pic '(n)A' <xsd:restriction base="xsd:string">
<xsd:length value="n"/>
Pic '(n)X' </xsd:restriction>
</xsd:simpleType>
Note: PICTURE data type with the
currency symbol is not supported.

360 Developer for z/OS: Developing with Db2, CICS, and IMS
Table 72. PL/I to XML type derivation, Bit, Character, Graphic, Widechar
PL/I Type Corresponding XSD Type
Bit (n)
<xsd:simpleType>
<xsd:restriction base="xsd:hexBinary">
where n is a multiple of 8. Other <xsd:length value="m"/>
values are not supported. </xsd:restriction>
</xsd:simpleType>

where m = n/8

Character (n) <xsd:simpleType>

<xsd:restriction base="xsd:string">
<xsd:maxlength value="n"/>
</xsd:restriction>
</xsd:simpleType>

Graphic (n) <xsd:simpleType>

Widechar (n) <xsd:restriction base="xsd:hexBinary">
<xsd:length value="m"/>
</xsd:restriction>
</xsd:simpleType>

where m = 2*n

Isomorphic and non-isomorphic element mapping for PL/I

Table 73 on page 361 and Figure 34 on page 362 are examples of isomorphic structures (an XML instance
document and a PL/I data structure) and both have isomorphic element mapping.

Table 73. Example 1 XML Instance of Isomorphic Structure with Isomorphic Element Mapping for PL/I
XML Instance PL/I Data Structure

<X1> 1 A,
<X2>2</X2> 2 B fixed bin(31),
<X3> 2 C,
<X4>4</X4> 3 D fixed bin(31);
</X3>
</X1>

Developing web services and SOA with Enterprise Service Tools 361
 Figure 34. Example 1 of XML Instance Isomorphic Structure with Isomorphic Element Mapping for PL/I

Table 74 on page 362 and Figure 35 on page 362 are examples of non-isomorphic structures (an XML
instance document and a PL/I data structure) have isomorphic subsets and display isomorphic element
mapping.

Table 74. Example 2 of XML Instance Non-Isomorphic Structure with Isomorphic Element Mapping for
PL/I
XML Instance PL/I Data Structure

<X1> 1 A,
<X2>2</X2> 2 B fixed bin(31),
<X3> 2 C,
<X4>4</X4> 3 D fixed bin(31);
</X3>
<X5>5</X5>
</X1>

Figure 35. Example 2 of XML Instance Non-Isomorphic Structure with Isomorphic Element Mapping for PL/I

362 Developer for z/OS: Developing with Db2, CICS, and IMS
Table 75 on page 363 and Figure 36 on page 363 are isomorphic structures (an XML instance document
and a PL/I data structure) have non-isomorphic element mapping.

Table 75. Example 3 XML Instance of Isomorphic Structure with Non-Isomorphic Element Mapping for
PL/I
XML Instance PL/I Data Structure

<X1> 1 A,
<X2>2</X2> 2 B fixed bin(31),
<X3> 2 C,
<X4>4</X4> 3 D fixed bin(31);
</X3>
</X1>

Figure 36. Example 3 of XML Instance Isomorphic Structure with Non-Isomorphic Element Mapping for PL/I

Table 76 on page 363 and Figure 37 on page 364 are non-isomorphic structures (an XML instance
document and a PL/I data structure) have non-isomorphic element mapping.

Table 76. Example 4 XML Instance of Non-Isomorphic Structure with Non-Isomorphic Element Mapping
for PL/I
XML Instance PL/I Data Structure

<X1 > 1 A,
<X2>2</X2> 2 B fixed bin(31),
<X3> 2 C,
<X4> 3 D fixed bin(31);
<X5>5</X5>
</X4>
</X3>
</X1>

Developing web services and SOA with Enterprise Service Tools 363
 Figure 37. Example 4 of XML Instance Non-Isomorphic Structure with Non-Isomorphic Element Mapping for
PL/I

WSDL2COBOL reference
This group of topics provides reference information for the WSDL2COBOL (top-down) scenario.
The WSDL2COBOL (WSDL to COBOL) scenario is a top-down scenario for the IMS Enterprise Suite SOAP
Gateway runtime. It generates COBOL-based Web service requester artifacts from a WSDL file. The
generated artifacts are for use with the IMS Synchronous callout function.

Enterprise COBOL structures in the WSDL2COBOL scenario

This group of topics describes how Enterprise COBOL for z/OS language structures are generated in the
WSDL2COBOL scenario.
In this scenario the WSDL2COBOL component generates Enterprise COBOL language structures for the
input and output messages of each operation on a specified WSDL Service and Port combination (see
“ServiceImplementationSpec” on page 478). Language structures are written to a single copybook that
begins with an operation-to-language-structure dictionary comment. Each language structure is preceded
by descriptive comments.

Mapping XML schema data types to Enterprise COBOL data declarations

This section describes how XSD built-in primitive and derived data types are mapped to COBOL data
declarations in the WSDL2COBOL scenario.
XML schema data types fall into one of two categories: primitive or derived. A derived data type is created
by extending an existing primitive or extended data type. For example, xsd:integer is a built-in derived
type that is derived from the built-in primitive data type xsd:decimal (xsd:integer is an xsd:decimal with
the fractionDigits facet set to 0).
A derived data type can be created by setting restrictions in the facets of the source data type. Both
primitive and derived built-in data types can be extended by this type of restriction to create custom
reusable simple type definitions.
Note: A full description of how XML schema can be used to define the structure and layout of an
XML document is in the W3C standard specification XML schema Part 1: Structures Second Edition.
Information about how to specify and constrain the data present in an XML document can be found in the
W3C standard specification XML schema Part 2: Data types Second Edition.

364 Developer for z/OS: Developing with Db2, CICS, and IMS
The following tables describe the Enterprise COBOL data declarations that the WSDL2COBOL component
generates for each XSD built-in primitive and derived data type.
Note: The information in this section also applies to user-defined xsd:simpleTypes.

Table 77. XSD to COBOL: Boolean, string and related data types, date and time data types
XSD built-in data type: Enterprise COBOL data declaration:

boolean PIC X Display

Comments:
• X'00' = false, X'01' = true.
• The following facets are not used: whitespace
and pattern.

string If the length facet is specified:

normalizedString PIC X(n1) DISPLAY or PIC N(n2) NATIONAL
token n1 = min (length, 227 -1)
name n2 = min (length, 226 -1)
NMTOKEN
language else if the minLength and maxLength facets are
NCName specified:
ID PIC X(n1) DISPLAY or PIC N(n2) NATIONAL
IDREF n1 = min (max(minLength, maxLength), 227 -1)
anyURL n2 = min (max(minLength, maxLength), 226 -1)
QName
NOTATION
else if the enumeration facet is specified:
PIC X(n1) DISPLAY or PIC N(n2) NATIONAL
n1 = min (max(strlen(enumeration[*])), 227 -1)
n2 = min (max(strlen(enumeration[*])), 226 -1)

else:
PIC X(n1) DISPLAY or PIC N(n2) NATIONAL
n1 = min (defaultCharMaxLength, 227 -1)
n2 = min (defaultCharMaxLength, 226 -1)

Comments:
• PIC N(n2) NATIONAL is generated when the
host code page is DBCS.
• The whiteSpace facet is used by language
structure to XML conversion only.
• The pattern facet is not used.

date PIC X(n1) DISPLAY or PIC N(n2) NATIONAL

dateTime n1 = min (defaultDateTimeLength, 227 -1)
duration n2 = min (defaultDateTimeLength, 226 -1)
gDay
gMonth Comments:
gMonthDay • PIC N(n2) NATIONAL is generated when the
gYear host code page is DBCS.
gYearMonth • The whiteSpace facet is used by language
time structure to XML conversion only.
• The following facets are not used: pattern,
enumeration, maxInclusive, maxExclusive,
minInclusive, and minExclusive.

Developing web services and SOA with Enterprise Service Tools 365
 Table 78. XSD to COBOL: Unsigned integer data types
XSD built-in data type: Enterprise COBOL data declaration:

unsignedByte PIC 9(4) comp-5

Comments:
• The following facets are not used: totalDigits,
fractionDigits, pattern, enumeration, whiteSpace,
maxInclusive, maxExclusive, minInclusive, and
minExclusive.

unsignedShort PIC 9(4) comp-5

Comments:
• The following facets are not used: totalDigits,
fractionDigits, pattern, enumeration, whiteSpace,
maxInclusive, maxExclusive, minInclusive, and
minExclusive.

unsignedInt PIC 9(9) comp-5

Comments:
• The following facets are not used: totalDigits,
fractionDigits, pattern, enumeration, whiteSpace,
maxInclusive, maxExclusive, minInclusive, and
minExclusive.

unsignedLong PIC 9(18) comp-5

Comments:
• The following facets are not used: totalDigits,
fractionDigits, pattern, enumeration, whiteSpace,
maxInclusive, maxExclusive, minInclusive, and
minExclusive.

Table 79. XSD to COBOL: Signed integer data types

XSD built-in data type: Enterprise COBOL data declaration:

Integer PIC s9(n) COMP-3

positiveInteger
negativeInteger If the totalDigits facet is specified:
nonPositiveInteger n = min(totalDigits, 31);
nonNegativeInteger else:
n = min(defaultTotalDigits, 31);

Comments:
• The following facets are not used:
fractionDigits, pattern, enumeration, whiteSpace,
maxInclusive, maxExclusive, minInclusive, and
minExclusive.

366 Developer for z/OS: Developing with Db2, CICS, and IMS
Table 79. XSD to COBOL: Signed integer data types (continued)
XSD built-in data type: Enterprise COBOL data declaration:

byte PIC s9(4) COMP-5

Comments:
• The following facets are not used: totalDigits,
fractionDigits, pattern, enumeration, whiteSpace,
maxInclusive, maxExclusive, minInclusive, and
maxInclusive.

short PIC s9(4) COMP-5

Comments:
• The following facets are not used: totalDigits,
fractionDigits, pattern, enumeration, whiteSpace,
maxInclusive, maxExclusive, minInclusive, and
minExclusive.

int PIC s9(9) COMP-5

Comments:
• The following facets are not used: totalDigits,
fractionDigits, pattern, enumeration, whiteSpace,
maxInclusive, maxExclusive, minInclusive, and
minExclusive.

long PIC s9(18) COMP-5

Comments:
• The following facets are not used:
fractionDigits, pattern, enumeration, whiteSpace,
maxInclusive, maxExclusive, minInclusive, and
minExclusive.

Developing web services and SOA with Enterprise Service Tools 367
 Table 80. XSD to COBOL: Decimal and floating point data types
XSD built-in data type: Enterprise COBOL data declaration:

decimal PIC s9(n) [V9 (m)] COMP-3

if the totalDigits and the fractionDigits facets are

specified:
n = min(totalDigits, 31),
m = min(fractionDigits, 31);

else if the totalDigits facet is specified:

n = min(totalDigits, 31),
m = min(defaultFractionDigits, 31);

else if the fractionDigits facet is specified:

n = min(defaultTotalDigits, 31),
m = min(fractionDigits, 31);

else:
n = min(defaultTotalDigits, 31),
m = min(defaultFractionDigits, 31).

Comments:
• The following facets are not used: pattern,
enumeration, whiteSpace, maxInclusive, and
maxExclusive.

float COMP-1

Comments:
• xsd:float (single-precision floating-point)
is represented in IEEE floating-point, however
COMP-1 is internally represented using IBM
hexadecimal floating-point.
• The following facets are not used:
pattern, enumeration, whiteSpace, maxInclusive,
maxExclusive, minInclusive, and minExclusive.

double COMP-2

Comments:
• xsd:double (double-precision floating-point)
is represented in IEEE floating-point, however
COMP-2 is internally represented using IBM
hexadecimal floating-point.
• The following facets are not used:
pattern, enumeration, whiteSpace, maxInclusive,
maxExclusive, minInclusive, and minExclusive.

368 Developer for z/OS: Developing with Db2, CICS, and IMS
Table 81. XSD to COBOL: Data types not supported
XSD built-in data type: Enterprise COBOL data declaration:

base64Binary Not supported

Comments:
• Encoding and decoding of base64 sequences
is not supported by COBOL Compiled XML
Conversion.

ENTITY Not supported.

Comments:
• Unparsed entities require parsing or generation
of an internal
or external DTD at execution time; this is not
supported by
Compiled XML Conversion.

ENTITIES Not supported.

IDREFS
Comments:
• data types derived by list or union are not
supported. Also see ENTITY.

anySimpleType Not supported.

Comments:
• xsd:anySimpleType is the base type of all built-
in primitive and
derived data types. Therefore XML elements and
attributes that
are of type xsd:anySimpleType can be of any built-
in or user-defined
atomic, list, or union type at execution time.

anyType Not supported.

Comments:
• xsd:anyType is the base type from which all
simple and
complex types are derived. An xsd:anyType type
does not
constrain its content in any way. For example, the
content of
an XML element that is of type xsd:anyType can be
an
arbitrary XML document fragment in one
occurrence and
base64Binary in another.

Developing web services and SOA with Enterprise Service Tools 369
 Creation of COBOL data names
This topic describes how the names of generated Enterprise COBOL data names are formed from XML
elements and XML attributes in the WSDL2COBOL scenario.
When a new Enterprise COBOL data item is created by the WSDL2COBOL file-generation component, it
derives the name for the item from the value of the name attribute in the corresponding XSD element or
XSD attribute declaration.
While Enterprise COBOL supports data names that contain both SBCS and DBCS characters,
WSDL2COBOL supports only the generation of SBCS data names. The maximum length of an Enterprise
COBOL data name is 30 characters, and WSDL2COBOL can be configured to use a smaller maximum via
the WSDL2ELSSpec languageNameLimit attribute. The characters that are valid for an SBCS data name in
Enterprise COBOL are [A-Z], [a-z], [0-9], -, and _1. WSDL2COBOL will preserve the case of XML element
or XML attribute names when forming corresponding COBOL data names. If characters are found in XML
element or XML attributes that are not valid in a COBOL data name, they will each be substituted by an
uppercase 'X'.

XML names and COBOL reserved words

Enterprise COBOL defines several reserved words that may not be used as data names. If the name
attribute of an XSD element or XSD attribute declaration matches an Enterprise COBOL reserved word,
WSDL2COBOL will behave as if the data name is not unique and append an ordinal suffix to it until the
name no longer matches a reserved word and can be uniquely referenced in the COBOL structure.

Suffixes appended to COBOL data names

WSDL2COBOL adds suffixes to certain COBOL data names to draw attention to data items that are
functionally related, or to the XSD construct that a data item corresponds to.

Table 82. Suffixes added to COBOL data names

Suffix: Description:
-att A group or elementary data item that represents
and XML attribute.
-bit An elementary data item that indicates whether an
optional group or data item was received in the
input XML or is to be generated in the output XML.
-cnt An elementary data item that indicates the number
of entries used in the repeating group or data item
that immediately follows it in the structure. The
value of this attribute does not affect the size in
bytes of the parent 01-level structure in memory
or when transmitted over the network. A data item
of this type is generated for the following repeating
group or data item types:
• Nested and non-nested fixed-length arrays
• Nested variable-length arrays

1 While the '_' character is supported in Enterprise COBOL V4R2 data names, WSDL2COBOL will substitute
each '_' with a '-' to ensure that the generated data names are compatible with earlier releases of
Enterprise COBOL.

370 Developer for z/OS: Developing with Db2, CICS, and IMS
Table 82. Suffixes added to COBOL data names (continued)
Suffix: Description:
-lim An elementary data item that serves as the object
of an OCCURS DEPENDING ON subject. The value
of this item must be less than or equal to n in
“ele OCCURS m to n TIMES DEPENDING ON ele-
lim”. The value of this attribute does not affect the
size in bytes of the parent 01-level structure in
memory, however it can make the structure more
efficient to transmit over the network when the
value is less than the limit n.

Mapping XML Schema structures to Enterprise COBOL structures

This topic describes how XSD structures are mapped to COBOL structures in the WSDL2COBOL scenario.
Typically an 01-level COBOL group item is generated to contain subordinate group and elementary items
that correspond to the XML elements and XML attributes contained by a source XSD global element. With
few exceptions, the hierarchy of the generated 01-level group item and its subordinate groups will match
that of the XSD element declaration from which it is derived.
The remainder of this topic uses psudocode to describe how the different types of XSD structures are
mapped to COBOL group and elementary items. The following pseudocode function definitions apply to
the mappings:
• depth(...): return the hierarchical depth of an XSD element or attribute.
• cobolName(...): return a unique COBOL data name derived from the supplied XSD element or attribute.
Uniqueness is determined using the fully qualified path or data name. (See “Creation of COBOL data
names” on page 370).
• cobolType(...):return a COBOL data description derived from the supplied XSD simple type definition.
For user-defined types, derivation is performed using the base built-in or derived simple type. (See
Enterprise COBOL structures in the WSDL2COBOL scenario).

Mapping elementary XML elements

An elementary XML element is one that does not contain other elements, although it can have attributes
and character content.
• This mapping shows the simple case:

Table 83. Elementary XML elements with built-in or derived simple types
Language: Declaration:
XSD <xsd:element name=”eleName1”
type=”simple1” />

COBOL 1. depth(eleName1)
+ ' ' + cobolName (eleName1)
+ ' ' + cobolType (simple1) + ' . '

• An optional elementary XML element contains "minOccurs=0" and "maxOccurs=1":

Table 84. Optional elementary XML elements

Language: Declaration:
XSD <xsd:element name=”eleName1” type=”simple1”
minOccurs=”0” maxOccurs=”1” />

Developing web services and SOA with Enterprise Service Tools 371
 Table 84. Optional elementary XML elements (continued)
Language: Declaration:

COBOL 1. depth(eleName1)
+ ' ' + cobolName (eleName1 + "-bit1")
+ " PIC X DISPLAY."

2. depth(eleName1)
+ ' ' + cobolName (eleName1)
+ ' ' + cobolType (simple1) + ' . '

1See “Suffixes appended to COBOL data names” on page 370.

• A repeating elementary XML element is mapped to an array:

Table 85. Repeating elementary XML elements (arrays)

Language: Declaration:
XSD <xsd:element name=”eleName1” type=”simple1”
minOccurs=”m” maxOccurs=”n” />

COBOL If m = n:

1. depth(eleName1)
+ ' ' + cobolName(eleName1 + '-cnt1')
+ ' PIC S9(9) COMP-5.'

2. depth(eleName1)
+ ' ' + cobolName(eleName1)
+ ' ' + cobolType(simple1)
+ ' OCCURS ' + min(n, defaultMaxOccursLimit)
+ ' TIMES.'

else if m < n && (n > 1 || n = -1):

odoObjectName = cobolName(eleName1 + '-

lim1')

1. depth(eleName1)
+ ' ' + odoObjectName + ' PIC S9(9) COMP-5.'

2. depth(eleName1)
+ ' ' + cobolName(eleName1 + '-cnt1')
+ ' PIC S9(9) COMP-5.'

3. depth(eleName1)
+ ' ' + cobolName(eleName1)
+ ' ' + cobolType(simple1)
+ ' OCCURS ' + m + ' TO '
+ min(n, defaultMaxOccursLimit)
+ ' TIMES DEPENDING ON ' + odoObjectName
+ '.'

1See “Suffixes appended to COBOL data names” on page 370.

• An elementary XML element can contain characters and attributes:

372 Developer for z/OS: Developing with Db2, CICS, and IMS
 Table 86. Elementary XML elements with character and attribute contents
Language: Declaration:

XSD <xsd:element name=”eleName”

type=”complex1” />
<xsd:complexType name=”complexTypeName”>
<xsd:simpleContent>
<xsd:extension base=”simple1”>
<xsd:attribute name=”attName”
type=”simple2” />
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>

COBOL 1. depth(eleName1)
+ ' ' + cobolName(eleName1) + '.'

2. (depth(eleName1) + 1)
+ ' ' + cobolName('text')
+ ' ' + cobolType(simple1) + '.'

3. (depth(eleName1) + 1)
+ ' ' + cobolName(attName1 + '-bit1')
+ ' PIC X DISPLAY.'

4. (depth(eleName1) + 1)
+ ' ' + cobolName(attName1 + '-att1')
+ ' ' + cobolType(simple2) + '.'

1See “Suffixes appended to COBOL data names” on page 370.

Mapping composed XML elements

A composed XML elements is one that can contain further elementary or composed XML elements and
XML attributes.
• This mapping shows the simple case:

Table 87. Composed XML elements with elementary and attribute contents
Language: Declaration:

XSD <xsd:element name=”eleName1”

type=”complex1” />
<xsd:complexType name=”complex1”
mixed=”false”>
<xsd:sequence or all>
<xsd:element name=”eleName2”
type=”simple1” />
</xsd:sequence or all>
<xsd:attribute name=”attName1”
type=”simple2” />
</xsd:complexType>

Developing web services and SOA with Enterprise Service Tools 373
 Table 87. Composed XML elements with elementary and attribute contents (continued)
Language: Declaration:

COBOL 1. depth(eleName1)
+ ' ' + cobolName(eleName1) + '.'

2. (depth(eleName1) + 1)
+ ' ' + cobolName(attName1 + '-bit1')
+ ' PIC X DISPLAY.'

3. (depth(eleName1) + 1)
+ ' ' + cobolName(attName1 + '-att1')
+ ' ' + cobolType(simple2) + '.'

4. depth(eleName2)
+ ' ' + cobolName(eleName2)
+ ' ' + cobolType(simple1) + '.'

1See “Suffixes appended to COBOL data names” on page 370.

• An optional composed XML element contains "minOccurs=0" and "maxOccurs=1":

Table 88. Optional composed XML elements

Language: Declaration:

XSD <xsd:element name=”eleName1”

type=”complex1” minOccurs=”0”
maxOccurs=”1”/>
<xsd:complexType name=”complex1” >
<xsd:sequence or all>
<xsd:element name=”eleName2”
type=”simple1” />
</xsd:sequence or all>
</xsd:complexType>

COBOL 1. depth(eleName1)
+ ' ' + cobolName(eleName1) + '-bit1')
+ ' PIC X DISPLAY.'

2. depth(eleName1)
+ ' ' + cobolName(eleName1) + '.'

3. depth(eleName2)
+ ' ' + cobolName(eleName2)
+ ' ' + cobolType(simple1) + '.'

1See “Suffixes appended to COBOL data names” on page 370.

• A repeating composed XML element is mapped to an array:

374 Developer for z/OS: Developing with Db2, CICS, and IMS
Table 89. Repeating composed XML elements (arrays)
Language: Declaration:

XSD <xsd:element name=”eleName1”

type=”complex1” minOccurs=”m”
maxOccurs=”n”/>
<xsd:complexType name=”complex1”
mixed=”false”>
<xsd:sequence or all>
<xsd:element name=”eleName2”
type=”simple1” minOccurs=”3”
maxOccurs=”3” />
</xsd:sequence or all>
</xsd:complexType>

Developing web services and SOA with Enterprise Service Tools 375
 Table 89. Repeating composed XML elements (arrays) (continued)
Language: Declaration:

COBOL If m = n:

1. depth(eleName1)
+ ' ' + cobolName(eleName1 + '-cnt1')
+ ' PIC S9(9) COMP-5.'

2. depth(eleName1)
+ ' ' + cobolName(eleName1)
+ ' OCCURS ' + n + ' TIMES.'

3. depth(eleName2)
+ ' ' + cobolName(eleName2 + '-cnt1')
+ ' PIC S9(9) COMP-5.'

4. depth(eleName2)
+ ' ' + cobolName(eleName2)
+ ' ' + cobolType(simple1)
+ ' OCCURS ' + min(3, defaultMaxOccursLimit)
+ ' TIMES.'

else if m < n && (n > 1 || n = -1):

odoObjectName = cobolName(eleName1 + '-

lim1')

1. depth(eleName1)
+ ' ' + odoObjectName + ' PIC S9(9) COMP-5.'

2. depth(eleName1)
+ ' ' + cobolName(eleName1 + '-cnt1')
+ ' PIC S9(9) COMP-5.'

3. depth(eleName1)
+ ' ' + cobolName(eleName1)
+ ' OCCURS ' + m + ' TO '
+ min(n, defaultMaxOccursLimit)
+ ' TIMES DEPENDING ON ' + odoObjectName
+ '.'

4. depth(eleName2)
+ ' ' + cobolName(eleName2 + '-cnt1')
+ ' PIC S9(9) COMP-5.'

5. depth(eleName2)
+ ' ' + cobolName(eleName2)
+ ' ' + cobolType(simple1)
+ ' OCCURS ' + min(3, defaultMaxOccursLimit)
+ ' TIMES.'

1See “Suffixes appended to COBOL data names” on page 370.

376 Developer for z/OS: Developing with Db2, CICS, and IMS
 Generated annotations for Enterprise COBOL structures
This topic describes the annotations that are added to generated Enterprise COBOL structures in the
WSDL2COBOL scenario.
The WSDL2COBOL code-generation process adds annotations to the source code to describe the
relationships between the generated language structures and the XML schemas from which they are
derived. The annotations display as language comments immediately preceding the definitions of the
language structures or language structure members to which they apply.
The following annotations are included in the structures generated for Enterprise COBOL. Notice that the
last four annotations in the list are added for variables that have the suffixes -bit, -cnt, -lim (see: “Suffixes
appended to COBOL data names” on page 370)

Table 90. Generated annotations for WSDL2COBOL structures

COBOL data
Annotation: <value>: name suffix:
@XPATH <value> The full path of the XSD element or XSD attribute N/A
declaration that this group or elementary data item is
mapped to.
@PRESENCE <value> The full path of the optional group or elementary data item -bit
that this elementary data item indicates the presence or
absence of.
@COUNT <value> The full path of the group or elementary repeating data -cnt
item that this elementary data item contains the used entry
count of.
@LIMIT <value> The full path of the group or elementary repeating data item -lim
that this elementary data item describes the upper bound
of.

Mapping session files

This group of topics describe the characteristics of the mapping session files that are generated by
WSDL2ELS in the WSDL2PLI and WSDL2COBOL scenarios.

Overview of mapping session files

This topic describes the mapping session files created by the WSDL2ELS component in the WSDL2PLI and
WSDL2COBOL scenarios.
The purpose of the information of this topic is to provide a context for the descriptions of annotations in
the next two topics.
The WSDL2ELS component generates mapping session files for each message input, output, and fault2
message referenced by the set of operations defined by the user-specified combination of WSDL Service
and Port. Mapping session files are unidirectional, mapping either a composite XSD element declaration
to an 01-level language structure or an 01-level language structure to a composite XSD element
declaration. Therefore, at least two mapping session files are generated by WSDL2ELS in the WSDL2PLI
and WSDL2COBOL scenarios when an operation defines both an input and output message.
Each mapping session file describes the mappings that were computed by WSDL2ELS during the process
of generating language structures from a composite XSD element declaration that was referenced by
either an input, output, or fault2 message in a specific WSDL operation. Mapping session files can be
viewed for reference purposes with the Mapping Editor in the RDz workbench.

2 SOAP fault messages are not supported in the WSDL2COBOL scenario.

Developing web services and SOA with Enterprise Service Tools 377
 Mapping session files are generated using a subset of the metadata format defined by the
com.ibm.ccl.mapping framework. This is the same framework that is used when mapping session files
are manually created in the meet-in-middle scenario.
Figure 38 on page 378 shows an example of a mapping session file. The top-level structure is a
mappingRoot element that contains the following elements:
• An input element specifies the location of the source structure of the mapping. In the example below
this is the location of the XSD schema structure named CalculatorInput defined in the types section
of a WSDL file.
• An output element specifies the location of the target structure of the mapping. In the example this is
the location of the PL/I source file Calculator.inc.
• An mappingDeclaration element specifies individual mappings:
Note: There can be multiple mappingDeclaration elements.
– First an input element and an output element specify the source structure and the target structure
for the individual mappings that follow.
– Then one or more mapping elements specify the fields within the source structure and target
structure that are mapped together. In the following example there are two such mapping elements,
each defining an individual mapping.

<ccl:mappingRoot xmlns:ccl="http://www.ibm.com/2006/ccl/Mapping"
domainID="com.ibm.etools.xmlent.mapping.domainxsd2pli" >

<ccl:input path="file:/C:/Calculator.wsdl? http://www.Calculator.com/schemas/

CalculatorInput"/>
<ccl:output path="file:/C:/Calculator.inc"/>

<ccl:mappingDeclaration name="Calculator.mapping">

<ccl:input path="CalculatorInput"/>
<ccl:output path="CALCULATORINPUT"/>

<ccl:mapping>
<ccl:input path="integerArray"/>
<ccl:output path="INTEGERARRAY"/>
</ccl:mapping>

<ccl:mapping>
<ccl:input path="allowOverflow"/>
<ccl:output path="ALLOWOVERFLOW"/>
</ccl:mapping>

</ccl:mappingDeclaration>
</ccl:mappingRoot>

Figure 38. Example contents of a mapping session file

Annotations for the mappingRoot element

This topic describes the annotations that are defined on the mappingRoot element in mapping session
files generated by the WSDL2ELS component in the WSDL2PLI and WSDL2COBOL scenarios.
WSDL2ELS includes annotations on the mappingRoot element in the WSDL2PLI and WSDL2COBOL
scenarios to provide additional information about the mapped WSDL file. The annotations are in form of
key-value pairs.
Table 91 on page 378 describes these annotations:

Table 91. Annotations added to the mappingRoot structure

Key: Description of value:
com.ibm.etools.xmlent.mapping.wsdlLocation The full platform-dependent location of the WSDL
file.

378 Developer for z/OS: Developing with Db2, CICS, and IMS
Table 91. Annotations added to the mappingRoot structure (continued)
Key: Description of value:
com.ibm.etools.xmlent.mapping.wsdlTargetNam The target namespace of the WSDL file.
espace
com.ibm.etools.xmlent.mapping.wsdlServiceNa The WSDL service that the mappingRoot element
me pertains to.
com.ibm.etools.xmlent.mapping.wsdlPortName The WSDL port that the mappingRoot element
pertains to.
com.ibm.etools.xmlent.mapping.wsdlOperation The WSDL Operation that the mappingRoot
Name element pertains to.

Annotations for the mapping element

This topic describes the annotations that are defined on the mapping element in mapping session files
generated by the WSDL2ELS component in the WSDL2PLI and WSDL2COBOL scenarios.
WSDL2ELS includes annotations on the input and output elements contained within each mapping
element if the source or target of the mapping is a language structure or structure member that
has functional relationship with some other language structure or language structure member. The
annotations correspond with suffixes that WSDL2ELS appends to PL/I identifiers and COBOL data names
as described in “Creation of PL/I identifiers” on page 387 and “Creation of COBOL data names” on page
370.
Table 92 on page 379describes these annotations:

Table 92. Annotations generated by WSDL2ELS in the WSDL2PLI scenario

Annotation Key: Value Suffix:
com.ibm.etools.xmlent.mapping.ePliPointerObje _cnt
ct
com.ibm.etools.xmlent.mapping.ePliPresenceO _bit
bject
com.ibm.etools.xmlent.mapping.ePliBase64Bina _buf_len
ryLengthObject
com.ibm.etools.xmlent.mapping.ePliPointerObje _ptr
ct
com.ibm.etools.xmlent.mapping.ePliPoolAreaLo _lim
calReferObject
com.ibm.etools.xmlent.mapping.ePliPoolAreaEx _lim
ternalReferObject
com.ibm.etools.xmlent.mapping.ePliPoolArea
com.ibm.etools.xmlent.mapping.ePliLocalRefer _lim
Object
com.ibm.etools.xmlent.mapping.ePliExternalRef _lim
erObject

Developing web services and SOA with Enterprise Service Tools 379
 Table 93. Annotations generated by WSDL2ELS in the WSDL2COBOL scenario
Annotation Key: Value Suffix:
com.ibm.etools.xmlent.mapping.eCobolCounter -cnt
Object
com.ibm.etools.xmlent.mapping.eCobolPresenc -bit
eObject
com.ibm.etools.xmlent.mapping.eCobolLocalOc -lim
cursObject

WSDL2PLI reference
This group of topics provides reference information for the WSDL2PLI (top-down) scenario.
The WSDL2PLI (WSDL to PL/I) scenario is a top-down scenario for the IMS Enterprise Suite SOAP
Gateway runtime. It generates a PL/I-based Web service provider implementation from a single-operation
or multioperation WSDL file (see WSDL2PLI scenario).

Enterprise PL/I structures in the WSDL2PLI scenario

This group of topics describes how Enterprise PL/I for z/OS language structures are generated in the
WSDL2PLI scenario.
In this scenario the WSDL2PLI component generates Enterprise PL/I language structures for each input
and output message of each operation on the WSDL Service and Port specified in the WSDL source
file. Language structures are written to a single include file that begins with an operation-to-language-
structure dictionary comment. Each language structure is preceded by descriptive comments.

Mapping XML Schema data types to Enterprise PL/I data declarations

This section describes how XSD built-in primitive and derived datatypes are mapped to PL/I data
declarations in the WSDL2PLI scenario.
XML schema datatypes fall into one of two categories: primitive or derived. A derived data type is created
by extending an existing primitive or extended data type. For example, xsd:integer is a built-in derived
type that is derived from the built-in primitive data type xsd:decimal (xsd:integer is an xsd:decimal with
the fractionDigits facet set to 0).
A derived data type can be created by setting restrictions in the facets of the source data type. Both
primitive and derived built-in datatypes can be extended by this type of restriction to create custom
reusable simple type definitions.
Note: A full description of how XML Schema can be used to define the structure and layout of an
XML document is in the W3C standard specification XML Schema Part 1: Structures Second Edition.
Information on how to specify and constrain the data present in an XML document can be found in the
W3C standard specification XML Schema Part 2: Datatypes Second Edition.
The following tables describe the Enterprise PL/I data declarations that the WSDL2PLI component
generates for each XSD built-in primitive and derived data type.
Note: The information in this section also applies to user-defined xsd:simpleTypes.

380 Developer for z/OS: Developing with Db2, CICS, and IMS
Table 94. XSD to PL/I: Boolean, string and related data types, date and time data types
XSD built-in data type: Enterprise PL/I data declaration:

base64Binary (n) BIT(8) ALIGNED

if xs:length facet is specified:

n = xs:length/@value;

else if xs:maxLength facet is specified:

n = xs:maxlength/@value

else if xs:minLength facet is specified:

n = max (xs:minLength/@value, WSDL2ELSSpec/
@defaultBase64BinaryLength)

else
n = WSDL2ELSSpec/
@defaultBase64BinaryLength

boolean BIT(1) ALIGNED

Comments:
• The following facets are not used: whiteSpace
and pattern.

Developing web services and SOA with Enterprise Service Tools 381
 Table 94. XSD to PL/I: Boolean, string and related data types, date and time data types (continued)
XSD built-in data type: Enterprise PL/I data declaration:

string if xs:length is specified:

normalizedString n = min(xs:length/@value, [32767|16383])
token s = size([CHAR|WCHAR](n))
name
NMTOKEN if s > size(OFFSET) and
language n > WSDL2ELSSpec/@inlineStringLengthLimit:
NCName
ID “OFFSET(pool) LOCATES([CHAR|WCHAR]
IDREF (n))”
anyURL
QName else
NOTATION
“[CHAR|WCHAR](n)”

else if xs:minLength and xs:maxLength are

specified:
n = min(max(xs:minLength/@value,
xs:maxLength/@value), [32767|16383])
s = size([CHAR|WCHAR](n) VARYING)

if s > size(OFFSET) and

n > WSDL2ELSSpec/@inlineStringLengthLimit:

"OFFSET(pool) LOCATES([CHAR|WCHAR]
(n)VARYING)”

else

“CHAR(n) VARYING”

else if xs:enumeration facet is specified:

n = min(max(strlen(enumeration[*])),[32767|
16383])
s = size([CHAR|WCHAR](n) VARYING)

if s > size(OFFSET) and

n > WSDL2ELSSpec/@inlineStringLengthLimit:

“OFFSET(pool) LOCATES([CHAR|WCHAR]
(n)VARYING)”

else

“[CHAR|WCHAR](n) VARYING”

else
n = min(WSDL2ELSSpec/
@defaultCharMaxLength,[32767|16383])
s = size([CHAR|WCHAR](n) VARYING)

if s > size(OFFSET) and

n > WSDL2ELSSpec/@inlineStringLengthLimit:

“OFFSET(pool) LOCATES([CHAR|WCHAR]
(n)VARYING)”
382 Developer for z/OS: Developing with Db2, CICS, and IMS else
Table 94. XSD to PL/I: Boolean, string and related data types, date and time data types (continued)
XSD built-in data type: Enterprise PL/I data declaration:

date n = min(WSDL2ELSSpec/
dateTime @defaultDateTimeLength,[32767|16383])
duration s = size([CHAR|WCHAR](n) VARYING)
gDay
gMonth if s > size(OFFSET) and
gMonthDay n > WSDL2ELSSpec/@inlineStringLengthLimit:
gYear
gYearMonth “OFFSET(pool) LOCATES([CHAR|WCHAR]
time (n)VARYING)”

else

“[CHAR|WCHAR](n) VARYING”

Comments:
• WCHAR is generated when hostCCSIDIsDBCS is
true.
• The whiteSpace facet is used by language
structure to XML conversion only.
• The following facets are not used: pattern,
enumeration, maxInclusive, maxExclusive,
minInclusive, and minExclusive.

Table 95. XSD to PL/I: Unsigned integer data types

XSD built-in data type: Enterprise PL/I data declaration:

unsignedByte UNSIGNED FIXED BIN (8)

Comments:
• The following facets are not used: totalDigits,
fractionDigits, pattern, enumeration, whiteSpace,
maxInclusive, maxExclusive, minInclusive, and
minExclusive.

unsignedShort UNSIGNED FIXED BIN (16)

Comments:
• The following facets are not used: totalDigits,
fractionDigits, pattern, enumeration, whiteSpace,
maxInclusive, maxExclusive, minInclusive, and
minExclusive.

Developing web services and SOA with Enterprise Service Tools 383
 Table 95. XSD to PL/I: Unsigned integer data types (continued)
XSD built-in data type: Enterprise PL/I data declaration:

unsignedInt UNSIGNED FIXED BIN (32)

Comments:
• The following facets are not used: totalDigits,
fractionDigits, pattern, enumeration, whiteSpace,
maxInclusive, maxExclusive, minInclusive, and
minExclusive.

unsignedLong UNSIGNED FIXED BIN (64)

Comments:
• Requires compiler option
LIMITS(FIXEDBIN(31,63)).
• The following facets are not used: totalDigits,
fractionDigits, pattern, enumeration, whiteSpace,
maxInclusive, maxExclusive, minInclusive, and
minExclusive.

Table 96. XSD to PL/I: Signed integer data types

XSD built-in data type: Enterprise PL/I data declaration:

Integer FIXED DECIMAL(n, 0)

positiveInteger
negativeInteger If the totalDigits facet is specified:
nonPositiveInteger n = min(totalDigits, 31);
nonNegativeInteger else:
n = min(default_total_digits, 31);

Comments:
• The following facets are not used:
fractionDigits, pattern, enumeration, whiteSpace,
maxInclusive, maxExclusive, minInclusive, and
minExclusive.

byte SIGNED FIXED BIN (7)

Comments:
• The following facets are not used: totalDigits,
fractionDigits, pattern, enumeration, whiteSpace,
maxInclusive, maxExclusive, minInclusive, and
maxInclusive.

short SIGNED FIXED BIN (15)

Comments:
• The following facets are not used: totalDigits,
fractionDigits, pattern, enumeration, whiteSpace,
maxInclusive, maxExclusive, minInclusive, and
minExclusive.

384 Developer for z/OS: Developing with Db2, CICS, and IMS
Table 96. XSD to PL/I: Signed integer data types (continued)
XSD built-in data type: Enterprise PL/I data declaration:

int SIGNED FIXED BIN (31)

Comments:
• The following facets are not used: totalDigits,
fractionDigits, pattern, enumeration, whiteSpace,
maxInclusive, maxExclusive, minInclusive, and
minExclusive.

long SIGNED FIXED BIN (63)

Comments:
• Requires compiler option
LIMITS(FIXEDBIN(31,63)).
• The following facets are not used:
fractionDigits, pattern, enumeration, whiteSpace,
maxInclusive, maxExclusive, minInclusive, and
minExclusive.

Table 97. XSD to PL/I: Decimal and floating point data types
XSD built-in data type: Enterprise PL/I data declaration:

decimal FIXED DECIMAL (n, m)

if the totalDigits and the fractionDigits facets are

specified:
n = min(totalDigits, 31),
m = min(fractionDigits, 31);

else if the totalDigits facet is specified:

n = min(totalDigits, 31),
m = min(default_fraction_digits, 31);

else if the fractionDigits facet is specified:

n = min(default_total_digits, 31),
m = min(fractionDigits, 31);

else:
n = min(default_total_digits, 31),
m = min(default_fraction_digits, 31).

Comments:
• The following facets are not used: pattern,
enumeration, whiteSpace, maxInclusive, and
maxExclusive.

Developing web services and SOA with Enterprise Service Tools 385
 Table 97. XSD to PL/I: Decimal and floating point data types (continued)
XSD built-in data type: Enterprise PL/I data declaration:

float FLOAT BIN(21) IEEE

Comments:
• Native support for IEEE single-precision binary
floating point.
• The following facets are not used:
pattern, enumeration, whiteSpace, maxInclusive,
maxExclusive, minInclusive, and minExclusive.

double FLOAT BIN(53) IEEE

Comments:
• Native support for IEEE double-precision
binary floating point.
• Requires compiler option
LIMITS(FIXEDBIN(31,63)).
• The following facets are not used:
pattern, enumeration, whiteSpace, maxInclusive,
maxExclusive, minInclusive, and minExclusive.

Table 98. XSD to PL/I: Data types not supported

XSD built-in data type: Enterprise PL/I data declaration:

ENTITY Not supported.

COMMENTS:
• Unparsed entities require parsing or generation
of an internal
or external DTD at execution time; this is not
supported by
Compiled XML Conversion.

ENTITIES Not supported.

IDREFS
COMMENTS:
• Datatypes derived by list or union are not
supported. Also see ENTITY.

anySimpleType Not supported.

COMMENTS:
• xsd:anySimpleType is the base type of all built-
in primitive and
derived datatypes. Therefore XML elements and
attributes that
are of type xsd:anySimpleType can be of any built-
in or user-defined
atomic, list, or union type at execution time.

386 Developer for z/OS: Developing with Db2, CICS, and IMS
Table 98. XSD to PL/I: Data types not supported (continued)
XSD built-in data type: Enterprise PL/I data declaration:

anyType Not supported.

COMMENTS:
• xsd:anyType is the base type from which all
simple and
complex types are derived. An xsd:anyType type
does not
constrain its content in any way. For example, the
content of
an XML element that is of type xsd:anyType can be
an
arbitrary XML document fragment in one
occurrence and
base64Binary in another.

Creation of PL/I identifiers

This topic describes how the names of generated Enterprise PL/I major structures, minor structures, and
elementary variables are created in the WSDL2PLI scenario.
When the WSDL2PLI file-generation component creates a new PL/I data item (an elementary variable,
a minor structure, or a major structure) it derives the identifier for the item from the value in the name
attribute of the corresponding XML element.
The valid characters for an identifier in Enterprise PL/I are [A-Z], [a-z], [0-9], _, #, &, and $. The maximum
length of an identifier is 31 characters.
• However, the maximum length of a PL/I identifier can be increased to 100 characters by using the PL/I
compiler option LIMITS, for example: LIMITS(name(100)).
• WSDL2PLI supports generating identifiers up to 100 characters in length by setting the attribute
languageNameLimit of the element WSDL2ELSSpec to 100 (see “WSDL2ELSSpec” on page 492).
• It is important to note that if an XML element or attributes name begins with an underscore character
(_), that character will not be preserved.

Suffixes appended to PL/I identifiers

In addition to the derivation described above, the WSDL2PLI component also adds suffixes to certain PL/I
identifiers to draw attention to variables or structures that are functionally related.

Table 99. Suffixes added to PL/I identifiers

Suffix: Description:
_att A minor structure or elementary variable that
represents an XML attribute.
_att_enm A major structure that contains the PL/I constants
for enumerated strings declared in an anonymous
string data type that is defined in an attribute.
_bit An elementary variable that indicates whether
or not the PL/I minor structure or elementary
variable that immediately follows it in the language
structure was received (input) or is to be generated
(output).

Developing web services and SOA with Enterprise Service Tools 387
 Table 99. Suffixes added to PL/I identifiers (continued)
Suffix: Description:
_buf An array for binary content based on the length
specified in the elementary variable with the suffix
_buf_len.
_buf_len An elementary variable that indicates the size of
decoded binary content in bytes.
_cnt An elementary variable that indicates the number
of entries used in the array that immediately
follows it in the language structure.
_ele_enm A major structure that contains the PL/I constants
for enumerated strings declared in an anonymous
string data type that is defined in an element.
_lim An elementary variable that specifies the upper
bound of a REFER subject (unbounded array) at
execution time.
_ptr An elementary variable that contains the starting
address of the storage allocated for a major
structure that contains REFER subjects. This
variable is to be used with the PL/I ALLOCATE
statement, for example: allocate (struct)
set (@irz_struct_ptr)).
_ref A major structure that contains elementary
variables that serve as REFER objects. The objects
in this structure are read when allocating the
corresponding major structure that contains the
REFER subjects.
_typ_enm A major structure that contains the PL/I constants
for enumerated strings declared in a named
string data type that can be referenced by many
elements or attributes.

Mapping XML Schema structures to PL/I structures

This section describes how XSD structures are mapped to PL/I structures in the WSDL2PLI scenario.
Typically a PL/I major structure (01-level) is generated to contain all of the PL/I minor structures,
elementary variables, and arrays that correspond to XML elements and XML attributes in a source XSD.
With few exceptions, the hierarchy of the PL/I major and minor structures generated from the XSD will
match that of the XSD.
The mappings in the this topic use the following pseudocode function definitions:
• depth(): This function returns the hierarchical depth of an XSD element or attribute.
• pli_name(): This function returns a unique PL/I identifier derived from an XSD element or attribute
name. Uniqueness is determined using the fully qualified path of the identifier. (See “Creation of PL/I
identifiers” on page 387.)
• pli_type(): This function returns a PL/I data declaration derived from an XSD simple type definition.
For user-defined types, derivation is performed using the base built-in or derived simple type. (See
“Enterprise PL/I structures in the WSDL2PLI scenario” on page 380.)

388 Developer for z/OS: Developing with Db2, CICS, and IMS
Mapping elementary XML elements
An elementary XML element is one that does not contain other elements, although it can have attributes
and character content.
• This mapping shows the simple case:

Table 100. Elementary XML elements with built-in or derived simple types
Language: Declaration:
XSD <xsd:element name=”eleName”
type=”simpleTypeName” />
PL/I depth(xsd:element) pli_name(eleName)
pli_type(simpleTypeName)
• An optional elementary XML element contains "minOccurs=0" and "maxOccurs=1":

Table 101. Optional elementary XML elements

Language: Declaration:
XSD <xsd:element name=”eleName”
type=”simpleTypeName” minOccurs=”0”
maxOccurs=”1” />

PL/I depth(xsd:element) (pli_name(eleName)

+ ”_bit1”) BIT(1) ALIGNED,
depth(xsd:element) pli_name(eleName)
pli_type(simpleTypeName)

1See “Suffixes appended to PL/I identifiers” on page 387.

• A repeating elementary XML element is mapped to an array:

Table 102. Repeating elementary XML elements (arrays)

Language: Declaration:
XSD <xsd:element name=”eleName”
type=”simpleTypeName” minOccurs=”m”
maxOccurs=”n” />
PL/I One of the following:
– [ depth(xsd:element) (pli_name(eleName)
+ ”_lim1”) SIGNED FIXED BINARY(31), ]2
– [ depth(xsd:element) (pli_name(eleName)
+ ”_cnt1”) SIGNED FIXED BINARY(31), ]3
– [ depth(xsd:element) pli_name(eleName) (n)
pli_type(simpleTypeName), ]4 or
– [ depth(xsd:element) pli_name(eleName)
(_ref._lim1 REFER _lim1)
pli_type(simpleTypeName) ]5

1See “Suffixes appended to PL/I identifiers” on page 387.

2Generated when maxOccurs > element_max_occurs_limit or maxOccurs=”unbounded”.
3Generated when maxOccurs > 1.
4Generated when maxOccurs <= element_max_occurs_limit.
5Generated when maxOccurs) > element_max_occurs_limit or maxOccurs=”unbounded”.

Developing web services and SOA with Enterprise Service Tools 389
 • An elementary XML element can contain characters and attributes:

Table 103. Elementary XML elements with character and attribute contents
Language: Declaration:

XSD <xsd:element name=”eleName”

type=”complexTypeName” />
<xsd:complexType name=”complexTypeName”>
<xsd:simpleContent>
<xsd:extension base=”simpleTypeName1”>
<xsd:attribute name=”attName”
type=”simpleTypeName2” />
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>

PL/I depth(xsd:element) pli_name(eleName) ,

(depth(xsd:element) + 1) pli_name(“text”)
pli_type(simpleTypeName1),
(depth(xsd:element) + 1) (pli_name(attName) +
“_bit1”) BIT(1) ALIGNED,
(depth(xsd:element) + 1) (pli_name(attName) +
“_att1”) pli_type(simpleTypeName2)

1See “Suffixes appended to PL/I identifiers” on page 387.

Mapping composed XML elements

A composed XML elements is one that can contain further elementary or composed XML elements and
XML attributes.
• This mapping shows the simple case:

Table 104. Composed XML elements with elementary and attribute contents
Language: Declaration:

XSD <xsd:element name=”eleName1”

type=”complexTypeName” />
<xsd:complexType name=”complexTypeName”
mixed=”false”>
<xsd:sequence or all>
<xsd:element name=”eleName2”
type=”simpleTypeName1” />
</xsd:sequence or all>
<xsd:attribute name=”attName1”
type=”simpleTypeName2” use=”optional”/>
</xsd:complexType>

390 Developer for z/OS: Developing with Db2, CICS, and IMS
 Table 104. Composed XML elements with elementary and attribute contents (continued)
Language: Declaration:

PL/I depth(xsd:element) pli_name(eleName1) ,

(depth(xsd:element) + 1) pli_name(eleName2)
pli_type(simpleTypeName1),
(depth(xsd:element) + 1) pli_name(attName1
+ ”_bit1”)) BIT(1) ALIGNED,
(depth(xsd:element) + 1) pli_name(attName1
+ ”_att1”) pli_type(simpleTypeName2)

1See “Suffixes appended to PL/I identifiers” on page 387.

• An optional composed XML element contains "minOccurs=0" and "maxOccurs=1":

Table 105. Optional composed XML elements

Language: Declaration:

XSD <xsd:element name=”eleName1”

type=”complexTypeName” minOccurs=”0”
maxOccurs=”1”/>
<xsd:complexType name=”complexTypeName” >
<xsd:sequence or all>
<xsd:element name=”eleName2”
type=”simpleTypeName” />
</xsd:sequence or all>
</xsd:complexType>

PL/I depth(xsd:element) pli_name(eleName1 +

“_bit1”),
depth(xsd:element) pli_name(eleName1),
(depth(xsd:element) + 1) pli_name(eleName2)
pli_type(simpleTypeName)

1See “Suffixes appended to PL/I identifiers” on page 387.

• A repeating composed XML element is mapped to an array:

Table 106. Repeating composed XML elements (arrays)

Language: Declaration:

XSD <xsd:element name=”eleName1”

type=”complexTypeName” minOccurs=”m”
maxOccurs=”n”/>
<xsd:complexType name=”complexTypeName”
mixed=”false”>
<xsd:sequence or all>
<xsd:element name=”eleName2”
type=”simpleTypeName” minOccurs=”3”
maxOccurs=”3” />
</xsd:sequence or all>
</xsd:complexType>

Developing web services and SOA with Enterprise Service Tools 391
 Table 106. Repeating composed XML elements (arrays) (continued)
Language: Declaration:
PL/I One of the following:
– [ depth(xsd:element) pli_name(eleName1 +
“_lim1”) SIGNED FIXED BINARY(31), ]2
– [ depth(xsd:element) pli_name(eleName1 +
“_cnt1”) SIGNED FIXED BINARY(31), ]3
– [ depth(xsd:element) pli_name(eleName1)
(n), ]4 or
– [ depth(xsd:element) pli_name(eleName1)
(_ref._lim1 REFER _lim1) ]5
– depth(xsd:element) pli_name(eleName2) (3)
pli_type(simpleTypeName)

1See “Suffixes appended to PL/I identifiers” on page 387.

2Generated when maxOccurs > element_max_occurs_limit or maxOccurs=”unbounded”.
3Generated when minOccurs != maxOccurs and maxOccurs > 1.
4Generated when maxOccurs <= element_max_occurs_limit.
5Generated when maxOccurs > element_max_occurs_limit or maxOccurs=”unbounded”.

Working with REFER in generated PL/I structures

This topic describes how the REFER option is used to generate a compatible Enterprise PL/I structure for
a variable-length XML array in the WSDL2PLI scenario.
The information in this topic applies both to:
• The PL/I source code that the WSDL2PLI code-generation process creates automatically.
• PL/I source code that you create to access the automatically generated structures.

A REFER example
A variable-length XSD schema array is one in which maxOccurs="unbounded" or where maxOccurs
exceeds the limit set in the batch-processor property inlineMaxOccursLimit (see “WSDL2ELSSpec” on
page 492). An example of such an array is shown in Figure 39 on page 392:

<!-- XSD declaration: -->

<element name="planets" type="tns:PlanetsType"/>
<complexType name="PlanetsType">
<sequence>
<element name="planet_name" type="string" minOccurs="0" maxOccurs="unbounded"/>
</sequence>
</complexType>

Figure 39. XSD declaration of a variable-length array

To implement the equivalent array in PL/I, the WSDL2PLI code-generation process creates two PL/I
major structures, one for REFER object declarations and one for REFER subject declarations. Figure 40 on
page 393 and Figure 41 on page 393 show the structures that would be generated for the XSD schema
example in Figure 39 on page 392:
• The structure for object declarations specifies the maximum number of array items that can be
allocated. For the significance of the suffixes _ref and _lim see “Creation of PL/I identifiers” on page
387:

392 Developer for z/OS: Developing with Db2, CICS, and IMS
 /* PL/I REFER object declarations: */
01 planets_ref UNALIGNED,
/* number of planet_name entries to allocate space for */
02 planet_name_lim SIGNED FIXED BINARY(31);

Figure 40. Structure for object declarations

• The structure for subject declarations maps the allocated space. For the significance of the suffixes _ptr,
_lim, and _cnt see “Creation of PL/I identifiers” on page 387:

/* PL/I REFER subject declarations: */

01 planets UNALIGNED BASED(planets_ptr),
/* saved number of planet_name refer objects allocated (read-only) */
02 planet_name_lim SIGNED FIXED BINARY(31),
/* count of planet_name array entries used */
02 planet_name_cnt SIGNED FIXED BINARY(31),
/* planet_name array with limit specified at allocation-time */
02 planet_name (planets_ref.planet_name_lim REFER (planets.planet_name_lim)) CHAR(255)
VARYING;

Figure 41. Structure for subject declarations

The source code in the next figure shows how to initialize the structures declared in Figure 40 on page
393 and Figure 41 on page 393. First the number of items to allocate is set and the allocation is done.
Then four of the items in the allocated array are initialized. Finally the number of allocated elements in
use is set.
Note: After the major structure planets is allocated, planets.planet_name_cnt must be set to the
actual number of items in the array. Also the value in planets.planet_name_cnt must not exceed the
value in planets.planet_name_lim.

/* Usage: */
planets_ref.planet_name_lim = 10;
allocate (planets) set (planets_ptr);
planets.planet_name(1) = “Mercury”;
planets.planet_name(2) = “Venus”;
planets.planet_name(3) = “Earth”;
planets.planet_name(4) = “Mars”;
planets.planet_name_cnt = 4;

Figure 42. Initializing the structures for object declarations and subject declarations

A complex REFER example

This example defines a solar system structure containing an unbounded array of planets, with each planet
structure containing an unbounded array of moons:

<!-- XSD declarations: -->

<element name="solar_system" type="tns:SolarSystemType" />
<complexType name="SolarSystemType">
<sequence>
<element name="planet" type="tns:PlanetType" minOccurs="0" maxOccurs="unbounded" />
</sequence>
</complexType>

<complexType name="PlanetType">
<sequence>
<element name="planet_name" type="string" minOccurs="1" maxOccurs="1" />
<element name="moon_name" type="string" minOccurs="1" maxOccurs="unbounded" />
</sequence>
</complexType>

Figure 43. XSD declarations of a variable-length arrays

To implement the equivalent arrays in PL/I, the WSDL2PLI code-generation process creates the two
REFER object declarations and the two REFER subject declarations shown in Figure 44 on page 394 and
Figure 45 on page 394:

Developing web services and SOA with Enterprise Service Tools 393
 • /* PL/I REFER object declarations: */
01 solar_system_ref UNALIGNED,
/* number of planet entries to allocate space for */
02 planet_lim SIGNED FIXED BINARY(31),
/* number of moon_name entries to allocate space for */
2 moon_name_lim SIGNED FIXED BINARY(31);

Figure 44. Object declarations

• /* PL/I REFER subject declarations: */
01 solar_system UNALIGNED BASED(solar_system_ptr),
/* saved number of planet refer objects allocated (read-only) */
02 planet_lim SIGNED FIXED BINARY(31),
/* saved number of moon_name refer object allocated (read-only) */
02 moon_name_lim SIGNED FIXED BINARY(31),
/* count of planet array entries used */
02 planet_cnt SIGNED FIXED BINARY(31),
/* planet array with limit specified at allocation-time */
02 planet(solar_system_ref.planet_lim REFER (solar_system.planet_lim)),
03 planet_name CHAR(255) VARYING,
/* count of moon_name[i] array entries used */
03 moon_name_cnt SIGNED FIXED BINARY(31),
/* moon_name array with limit specified at allocation */
10 moon_name(solar_system_ref.moon_name_lim REFER (solar_system.moon_name_lim))
CHAR(255) VARYING;

Figure 45. Subject declarations

The source code in Figure 46 on page 394 shows how to initialize the structures declared in Figure 44 on
page 394 and Figure 45 on page 394.
Note: After the allocation the count variables planets.planet_cnt,
solar_system.planet(1).moon_name_cnt, and solar_system.planet(2).moon_name_cnt
must be set to the actual number of items in the respective arrays.

/*Usage:*/
/* initialize major structure solar_system */
solar_system_ref.planet_lim = 4;
solar_system_ref.moon_name_lim = 2;
allocate (solar_system) set (solar_system_ptr);
solar_system.planet_cnt = 0;

/* create planet entry */

solar_system.planet(1) = “Earth”;
solar_system.planet(1).moon_name_cnt = 0;
solar_system.planet(1).moon_name(1) = “Luna”;
solar_system.planet(1).moon_name_cnt += 1;
solar_system.planet_cnt +=1; // 1

/* create planet entry */

solar_system.planet(2) = “Mars”;
solar_system.planet(2).moon_name_cnt = 0;
solar_system.planet(2).moon_name(1) = “Phobos”;
solar_system.planet(2).moon_name(2) = “Deimos”;
solar_system.planet(2).moon_name_cnt = 2;
solar_system.planet_cnt +=1; // 2

Figure 46. Initializing the structures for object declarations and subject declarations

Note: With complex REFER subjects such as moon_name shown above, it is necessary to allocate a limit
that satisfies all repetitions of the subject. For example, consider converting the following XML into or out
of major structure solar_system:

<solar_system>
<planet>
<planet_name>Earth</planet_name>
<moon_name>Luna</moon_name>
</planet>
<planet>
<planet_name>Mars</planet_name>
<moon_name>Phobos</moon_name>
<moon_name>Deimos</moon_name>
</planet>
</solar_system>

394 Developer for z/OS: Developing with Db2, CICS, and IMS
The minimum value of the REFER object solar_system_ref.moon_name_lim that will satisfy all repetitions
of planet is 2. Setting the object value to 2 will cause space for two moon_name entries to be allocated for
each planet entry. Because moon_name occurs only once in the first occurrence of the first planet entry,
the counter solar_system.planet(1).moon_name_cnt should be set to 1 so that only the first moon_name
entry is read.

Generated annotations for Enterprise PL/I structures

This topic describes the annotations that are added to generated Enterprise PL/I structures in the
WSDL2PLI scenario.
The WSDL2PLI code-generation process adds annotations to the source code to describe the
relationships between the generated language structures and the XML schemas from which they are
derived. The annotations appear as language comments immediately preceding the definitions of the
language structures or language structure members to which they apply.
The following annotations are included in the structures generated for Enterprise PL/I. Notice that the last
four annotations in the list are added for variables having the suffixes _bit, _cnt, _lim, _ptr (see “Suffixes
appended to PL/I identifiers” on page 387):

Table 107.
Correspondin
g PL/I
identifier
Annotation: <value>: suffix:
@XPATH <value> The full path of the XSD element or attribute declaration N/A
that this structure or structure member is mapped to.
@PRESENCE <value> The full path of the optional member that this member _bit
indicates the presence or absence of.
@COUNT <value> The full path of the array member that this member _cnt
contains the count of.
@LENGTH <value> The full path of the binary content array that this member N/A
contains the size for.
@LIMIT <value> The full path of the array member that this member _lim
describes the upperbound or limit of.
@POINTER <value> The name of the language structure into which this variable _ptr
stores the base address when a REFER object is allocated.

Generate PL/I constants for enumerated strings

This topic describes how to generate constants for strings that include an enumeration facet.
Regardless of whether your XML schema was created with named types or anonymous types, PL/I
constants can be generated for strings that contain an enumeration facet.

Named simple types

When an XML schema is constructed by using named simple types that include an enumeration facet, the
named simple type only needs to be constructed once within the schema. Named types are unique which
allows PL/I constants to be generated only once for enumerated strings. After being generated, they can
be referenced by elements or attributes as many times as needed without the need to regenerate the
constants again, avoiding the issue of duplicate PL/I constants. An example of such a schema is show in
Figure 47 on page 396

Developing web services and SOA with Enterprise Service Tools 395
 <xs:simpleType name="rainbowcolor">
<xs:restriction base="xs:string">
<xs:enumeration value="Violet"/>
<xs:enumeration value="Indigo"/>
<xs:enumeration value="Blue"/>
<xs:enumeration value="Green"/>
<xs:enumeration value="Yellow"/>
<xs:enumeration value="Orange"/>
<xs:enumeration value="Red"/>
</xs:restriction>
</xs:simpleType>

Figure 47. XSD declaration of a named simple type with enumeration

The named simple type rainbowcolor can be referenced numerous times as shown in Figure 48 on
page 396.

<xs:schema xmlns:poc="http://schemas.cs.csg.com/poc"...
<xs:element name="color1" type="poc:rainbowcolor:/>
<xs:element name="color2" type="poc:rainbowcolor:/>
<xs:attribute name="att_color3" type="poc:rainbowcolor:/>

Figure 48. XSD named simple type references

After the XML schema has been defined, the PL/I include file includes the generated PL/I constants for
the named data types with enumeration facets. The naming convention used for this type is <name of
the type>_typ_enm where typ indicates type and enm indicates enumeration. See “Suffixes appended
to PL/I identifiers” on page 387 for more information about these and other suffixes. An example of the
PL/I include file is shown in Figure 49 on page 396.

/*********************************************************************
* PL/I constants for enumerated strings declared in named simple type
* "poc:rainbowcolor".
**********************************************************************/
DCL 01 rainbowcolor_typ_enm,
02 Violet CHAR VALUE('E589969385A3'x),
02 Indigo CHAR VALUE('C99584898796'x),
02 Blue CHAR VALUE('C293A485'x),
02 Green CHAR VALUE('C799858595'x),
02 Yellow CHAR VALUE('E885939396A6'x),
02 Orange CHAR VALUE('D69981958785'x),
02 Red CHAR VALUE('D98584'x);

Figure 49. Generated PL/I constants in the include file (Host code page: SBCS)

Note: If there are two or more simple types that have the same name but different namespaces, all of the
structures are declared in the include file since they could contain different enumerations. To eliminate
confusion between the structures, an incremented value is appended to the end of each structures name
(_enm, _enm1, _enm2) and the comment section of the include file will identify the type.

<xs:element name="color1" type="poc1:rainbowcolor:/>

<xs:element name="color2" type="poc2:rainbowcolor:/>

/***************************************************************
* PL/I constants for enumerated strings declared in named simple type
* "poc1:rainbowcolor".
********************************************************************/
DCL 01 rainbowcolor_typ_enm,
02 Violet CHAR VALUE('E589969385A3'x),
02 Red CHAR VALUE('D98584'x);

/*********************************************************************
* PL/I constants for enumerated strings declared in named simple type
* "poc2:rainbowcolor".
********************************************************************/
DCL 01 rainbowcolor_typ_enm1,
02 Violet CHAR VALUE('E589969385A3'x),
02 Red CHAR VALUE('D98584'x);

Figure 50.

396 Developer for z/OS: Developing with Db2, CICS, and IMS
Anonymous simple types
For anonymous simple types, PL/I constants are generated each time an anonymous instance is
referenced in an element or attribute.

<xs:element name="rcolor">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:enumeration value="Violet"/>
<xs:enumeration value="Red"/>
</xs:restriction>
</xs:simpleType>
</xs:element>

Figure 51. XSD declaration of an anonymous simple type with enumeration

/*********************************************************************
* PL/I constants for enumerated strings declared in an anonymous simpl
* e type for element "rcolor".
********************************************************************/
DCL 01 rcolor_ele_enm,
02 Violet CHAR VALUE('E589969385A3'x),
02 Red CHAR VALUE('D98584'x);

Figure 52. Generated PL/I constants in the include file for an anonymous type

The naming convention used for this type is <name of the element>_[ele/att]_enm where ele
indicates element, att indicates attribute, and enm indicates enumeration. See “Suffixes appended to
PL/I identifiers” on page 387 for more information about these and other suffixes.
Note:
For PL/I constants, when the host code page is:
• DBCS: WCHAR is used and encode VALUEs as UTF-16 hexadecimal literals. The memConvert function
can be used to convert UTF-16 to DBCS when wanted.
• SBCS: CHAR is used and encode VALUEs as hex in the specified target code page.

IMS template generation

IMS PL/I top-down MPP template generation features separation of protocol-level logic from user-written
business logic. The protocol-level logic is generated to be used as-is and effectively shields the user-
written business logic from the details of interacting with the IMS Message Queue and the IRZPWSIO
API. Enhanced separation also allows for easier integration of existing business logic and increases the
portability of new code for any future migrations.
Using the enhanced templates, IMS application programmers may immediately focus on writing or
integrating business logic to process or create the input, output, or fault structures respective to each
operation implemented by the MPP. The following figure illustrates how the separation of protocol-level
logic from business logic is implemented in the enhanced templates.

Developing web services and SOA with Enterprise Service Tools 397
 As shown in the above figure, protocol-level logic exists in code-complete procedures named
OperationNameHandler that are dedicated to handling interactions with the IMS Message
Queue and IRZPWSIO APIs on behalf of the respective user-written business logic in procedures
named OperationNameImpl. All of the user-written business logic must be entered into the
OperationNameImpl procedures. At execution time, OperationNameImpl procedures are invoked by
their respective OperationNameHandler procedure.
The following shows an example of an enhanced template for a WSDL file that includes three operations:
• getteam_1_0
• setteam_1_0
• ping_1_0
The operations getteam_1_0 and setteam_1_0 may issue a SOAP fault.

*process macro not('¬') or('|') rules(nolaxdcl);

*process limits(name(100) extname(8) fixeddec(15,31) fixedbin(31,63));
*process system(IMS) display(std);

/*********************************************************************
* IBM Developer for z/OS
* Enterprise Service Tools (EST)
* Single-service Projects (XSE)
* IMS Enterprise Suite SOAP Gateway
* Web Service Provider Template MPP
*
* Date created: 2011-05-17 11:31:39 PDT
* UUID: be97872d-c773-4e42-b9bd-f8ac4d45c450
* INSTALLATION: 8.3.100
********************************************************************/
WSPOC1Package: package exports(*);

/* IMS PL/I service provider include

*/
%INCLUDE IRZPWSH;

398 Developer for z/OS: Developing with Db2, CICS, and IMS
/* WSDL2ELS language structures
*/
%INCLUDE WSPOC1;

/*-------------------------------------------------------------------*
* Procedure: WSPOC1
* Description: Implementation of a Web service provider MPP for ser
* vice "WS_poc_1" and binding "WS_poc_1_Binding" of the Web service
* definition file "WS_PoC_1.wsdl".
*------------------------------------------------------------------*/
WSPOC1: procedure(iopcb_mask_ptr) options(main);

dcl iopcb_mask_ptr pointer;

dcl host_text_1 char(1024) varying init('');
dcl host_text_2 char(1024) varying init('');

/* Begin mainline logic.

*/
@irz_iopcb_mask_ptr = iopcb_mask_ptr;
@irz_cee_feedback_ptr = addr(@irz_cee_feedback);
call ProcessMessages();

/* End mainline logic.

*/
return;

/*-------------------------------------------------------------------*
* Procedure: ProcessMessages
* Description: Retrieve the IRZPWSIO message header from the IMS Me
* ssage Queue and invoke a handler procedure based on the service c
* ontext.
*------------------------------------------------------------------*/
ProcessMessages: procedure internal;

/* Allocate memory for the IRZPWSIO message header and copy it fro
m the IMS Message Queue.
*/
allocate @irz_async_msg_header set (@irz_async_msg_header_ptr);
call CEETDLI(@irz_dli_get_unique, @irz_iopcb_mask,
@irz_async_msg_header);

/* Branch to a handler procedure corresponding to the operation ci

ted in the service context.
*/
do while(@irz_iopcb_mask.iopcb_status_code =
@irz_dli_status_ok);
select(@irz_async_msg_header.service_name);
when('WS_poc_1') do;
select(@irz_async_msg_header.operation_name);
when('getteam_1_0') do;
call getteam_1_0Handler;
end;
when('setteam_1_0') do;
call setteam_1_0Handler;
end;
when('ping_1_0') do;
call ping_1_0Handler;
end;
otherwise do;
host_text_1 = @irz_async_msg_header.operation_name;
host_text_2 = @irz_async_msg_header.service_name;
call LogEvent(trim(packagename()) || '#'
|| trim(procedurename()) || '(): Error, '
|| 'operation name "' || trim(host_text_1) || '" '
|| 'is not valid for service name "'
|| trim(host_text_2) || '".');
end;
end;
end;
otherwise do;
host_text_1 = @irz_async_msg_header.service_name;
call LogEvent(trim(packagename()) || '#'
|| trim(procedurename()) || '(): Error, '
|| 'service name "' || trim(host_text_1) || '" '
|| 'is not valid or is not implemented by this '
|| 'application.');
end;
end;
call CEETDLI(@irz_dli_get_unique, @irz_iopcb_mask,
@irz_async_msg_header);
end;

Developing web services and SOA with Enterprise Service Tools 399
 if (@irz_iopcb_mask.iopcb_status_code ¬=
@irz_dli_end_messages) then do;
host_text_1 = @irz_iopcb_mask.iopcb_status_code;
call LogEvent(trim(packagename()) || '#'
|| trim(procedurename()) || '(): Error, '
|| 'CEETDLI.GU(@irz_async_msg_header), '
|| 'iopcb_status_code: '
|| trim(host_text_1) || '.');
end;

free @irz_async_msg_header;

return;

end ProcessMessages;

/*-------------------------------------------------------------------*
* Procedure: getteam_1_0Handler
* Description: Get the request language structure for operation "ge
* tteam_1_0" from the IMS Message Queue using the IRZQGETS API, inv
* oke user-written implementation, set the response or fault langua
* ge structure and commit it to the IMS Message Queue using the IRZ
* QSETS API. Finally, deallocate language structures.
*------------------------------------------------------------------*/
getteam_1_0Handler: procedure internal;

/* Get the request language structure from the IMS Message Queue u
sing the IRZQGETS API.
*/
@irz_struct_name = 'getteam_1_0';
@irz_struct_type = @irz_soap_body_struct;
@irz_struct_ptr = null();
@irz_struct_size = 0;
@irz_debug = '0'b;

call IRZQGETSWrapper(procedurename());
if (@return_code = @irz_success) then do;
getteam_1_0_ptr = @irz_struct_ptr;
end; else do;
return;
end;

/* Invoke user-written implementation of operation "getteam_1_0" p

assing pointers to the request, response, and fault language struc
tures.
*/
getteam_1_0Response_ptr = null();
ServiceException_ptr = null();
call getteam_1_0Impl(@irz_iopcb_mask_ptr, getteam_1_0_ptr, getteam_1_
0Response_ptr, ServiceException_ptr);

/* Set the response or fault language structure for operation "get

team_1_0" and commit it to the IMS Message Queue using the IRZQSET
S API.
*/
if (getteam_1_0Response_ptr ¬= null()) then do;
@irz_struct_name = 'getteam_1_0Response';
@irz_struct_type = @irz_soap_body_struct;
@irz_struct_ptr = getteam_1_0Response_ptr;
@irz_struct_size = storage(getteam_1_0Response);
end; else if (ServiceException_ptr ¬= null()) then do;
@irz_struct_name = 'ServiceException';
@irz_struct_type = @irz_soap_fault_struct;
@irz_struct_ptr = ServiceException_ptr;
@irz_struct_size = storage(ServiceException);
end;

@irz_commit_structs = '1'b;
@irz_debug = '0'b;

call IRZQSETSWrapper(procedurename());

/* Deallocate language structures.

*/
if (getteam_1_0_ptr ¬= null()) then do;
call plifree(getteam_1_0_ptr);
getteam_1_0_ptr = null();
end;
if (getteam_1_0Response_ptr ¬= null()) then do;
call plifree(getteam_1_0Response_ptr);
getteam_1_0Response_ptr = null();

400 Developer for z/OS: Developing with Db2, CICS, and IMS
 end;
if (ServiceException_ptr ¬= null()) then do;
call plifree(ServiceException_ptr);
ServiceException_ptr = null();
end;

return;

end getteam_1_0Handler;

/*-------------------------------------------------------------------*
* Procedure: getteam_1_0Impl
* Description: Implement the business logic for operation "getteam_
* 1_0" using the following steps: (1) Process the request language
* structure "getteam_1_0", (2) Allocate and fill in the response la
* nguage structure "getteam_1_0Response" or a fault language struct
* ure from the set {ServiceException}. (3) Finally, set the respect
* ive response or fault language structure pointer before returning
* to the operation handler (Handler) procedure. Note: If an error
* occurs that requires a rollback, use parameter iopcb_mask_ptr to
* access the IOPCB.
*------------------------------------------------------------------*/
getteam_1_0Impl: procedure(iopcb_mask_ptr, getteam_1_0_ptr, getteam_1_0
Response_ptr, ServiceException_ptr) internal;

dcl iopcb_mask_ptr pointer byvalue;

dcl getteam_1_0_ptr pointer byvalue;
dcl getteam_1_0Response_ptr pointer byaddr;
dcl ServiceException_ptr pointer byaddr;

return;

end getteam_1_0Impl;

/*-------------------------------------------------------------------*
* Procedure: setteam_1_0Handler
* Description: Get the request language structure for operation "se
* tteam_1_0" from the IMS Message Queue using the IRZQGETS API, inv
* oke user-written implementation, set the response or fault langua
* ge structure and commit it to the IMS Message Queue using the IRZ
* QSETS API. Finally, deallocate language structures.
*------------------------------------------------------------------*/
setteam_1_0Handler: procedure internal;

/* Get the request language structure from the IMS Message Queue u
sing the IRZQGETS API.
*/
@irz_struct_name = 'setteam_1_0';
@irz_struct_type = @irz_soap_body_struct;
@irz_struct_ptr = null();
@irz_struct_size = 0;
@irz_debug = '0'b;

call IRZQGETSWrapper(procedurename());
if (@return_code = @irz_success) then do;
setteam_1_0_ptr = @irz_struct_ptr;
end; else do;
return;
end;

/* Invoke user-written implementation of operation "setteam_1_0" p

assing pointers to the request, response, and fault language struc
tures.
*/
setteam_1_0Response_ptr = null();
ServiceException_ptr = null();
call setteam_1_0Impl(@irz_iopcb_mask_ptr, setteam_1_0_ptr, setteam_1_
0Response_ptr, ServiceException_ptr);

/* Set the response or fault language structure for operation "set

team_1_0" and commit it to the IMS Message Queue using the IRZQSET
S API.
*/
if (setteam_1_0Response_ptr ¬= null()) then do;
@irz_struct_name = 'setteam_1_0Response';
@irz_struct_type = @irz_soap_body_struct;
@irz_struct_ptr = setteam_1_0Response_ptr;
@irz_struct_size = storage(setteam_1_0Response);
end; else if (ServiceException_ptr ¬= null()) then do;
@irz_struct_name = 'ServiceException';
@irz_struct_type = @irz_soap_fault_struct;
@irz_struct_ptr = ServiceException_ptr;

Developing web services and SOA with Enterprise Service Tools 401
 @irz_struct_size = storage(ServiceException);
end;

@irz_commit_structs = '1'b;
@irz_debug = '0'b;

call IRZQSETSWrapper(procedurename());

/* Deallocate language structures.

*/
if (setteam_1_0_ptr ¬= null()) then do;
call plifree(setteam_1_0_ptr);
setteam_1_0_ptr = null();
end;
if (setteam_1_0Response_ptr ¬= null()) then do;
call plifree(setteam_1_0Response_ptr);
setteam_1_0Response_ptr = null();
end;
if (ServiceException_ptr ¬= null()) then do;
call plifree(ServiceException_ptr);
ServiceException_ptr = null();
end;

return;

end setteam_1_0Handler;

/*-------------------------------------------------------------------*
* Procedure: setteam_1_0Impl
* Description: Implement the business logic for operation "setteam_
* 1_0" using the following steps: (1) Process the request language
* structure "setteam_1_0", (2) Allocate and fill in the response la
* nguage structure "setteam_1_0Response" or a fault language struct
* ure from the set {ServiceException}. (3) Finally, set the respect
* ive response or fault language structure pointer before returning
* to the operation handler (Handler) procedure. Note: If an error
* occurs that requires a rollback, use parameter iopcb_mask_ptr to
* access the IOPCB.
*------------------------------------------------------------------*/
setteam_1_0Impl: procedure(iopcb_mask_ptr, setteam_1_0_ptr, setteam_1_0
Response_ptr, ServiceException_ptr) internal;

dcl iopcb_mask_ptr pointer byvalue;

dcl setteam_1_0_ptr pointer byvalue;
dcl setteam_1_0Response_ptr pointer byaddr;
dcl ServiceException_ptr pointer byaddr;

return;

end setteam_1_0Impl;

/*-------------------------------------------------------------------*
* Procedure: ping_1_0Handler
* Description: Get the request language structure for operation "pi
* ng_1_0" from the IMS Message Queue using the IRZQGETS API, invoke
* user-written implementation, set the response or fault language
* structure and commit it to the IMS Message Queue using the IRZQSE
* TS API. Finally, deallocate language structures.
*------------------------------------------------------------------*/
ping_1_0Handler: procedure internal;

/* No request language structure is defined for operation "ping_1_

0".
*/

/* Invoke user-written implementation of operation "ping_1_0" pass

ing pointers to the request, response, and fault language structur
es.
*/
call ping_1_0Impl(@irz_iopcb_mask_ptr);

/* No response language structure is defined for operation "ping_1

_0". Insert only the IRZPWSIO message header.
*/
call CEETDLI(@irz_dli_insert, @irz_iopcb_mask,
@irz_async_msg_header);

return;

end ping_1_0Handler;

/*-------------------------------------------------------------------*

402 Developer for z/OS: Developing with Db2, CICS, and IMS
 * Procedure: ping_1_0Impl
* Description: Implement the business logic for operation "ping_1_0
* " using the following steps: (1) Process the request language str
* ucture "n/a", (2) Allocate and fill in the response language stru
* cture "n/a" or a fault language structure from the set {}. (3) Fi
* nally, set the respective response or fault language structure po
* inter before returning to the operation handler (Handler) procedu
* re. Note: If an error occurs that requires a rollback, use parame
* ter iopcb_mask_ptr to access the IOPCB.
*------------------------------------------------------------------*/
ping_1_0Impl: procedure(iopcb_mask_ptr) internal;

dcl iopcb_mask_ptr pointer byvalue;

return;

end ping_1_0Impl;

/*-------------------------------------------------------------------*
* Procedure: IRZQGETSWrapper
* Description: Get a language structure from the IMS Message Queue
* using the IRZQGETS API.
*------------------------------------------------------------------*/
IRZQGETSWrapper: procedure(caller_proc_name) internal;

dcl caller_proc_name char(*) byaddr;

@return_code = IRZQGETS(@irz_async_msg_header_ptr,
@irz_iopcb_mask_ptr, @irz_struct_type,
@irz_struct_name, @irz_struct_ptr,
@irz_struct_size, @irz_cee_feedback_ptr,
@irz_debug);

if (@return_code ¬= @irz_success) then do;

call LogEvent(trim(packagename()) || '#'
|| trim(caller_proc_name) || '(): '
|| 'Error, IRZQGETS return code: '
|| trim(@return_code) || '.');
if (@irz_struct_ptr ¬= null()) then do;
call plifree(@irz_struct_ptr);
@irz_struct_ptr = null();
@irz_struct_size = 0;
end;
end;

return;

end IRZQGETSWrapper;

/*-------------------------------------------------------------------*
* Procedure: IRZQSETSWrapper
* Description: Set a language structure and optionally commit it to
* the IMS Message Queue using the IRZQSETS API.
*------------------------------------------------------------------*/
IRZQSETSWrapper: procedure(caller_proc_name) internal;

dcl caller_proc_name char(*) byaddr;

@return_code = IRZQSETS(@irz_async_msg_header_ptr,
@irz_iopcb_mask_ptr, @irz_struct_type,
@irz_struct_name, @irz_struct_ptr,
@irz_struct_size, @irz_commit_structs,
@irz_cee_feedback_ptr, @irz_debug);

if (@return_code ¬= @irz_success) then do;

call LogEvent(trim(packagename()) || '#'
|| trim(caller_proc_name) || '(): '
|| 'Eror, IRZQSETS return code: '
|| trim(@return_code) || '.');
end;

return;

end IRZQSETSWrapper;

/*-------------------------------------------------------------------*
* Procedure: LogEvent
* Description: Common procedure for logging events that may be exte
* nded as needed.
*------------------------------------------------------------------*/
LogEvent: procedure(text) internal;
dcl text char(*) varying byaddr;

Developing web services and SOA with Enterprise Service Tools 403
 put skip list(datetime() || ' ' || text);
put list('');
return;
end LogEvent;

end WSPOC1;

end WSPOC1Package;

Output files generated in the WSDL2PLI scenario

This topic describes the output files generated in the WSDL2PLI scenario.
In the WSDL2PLI scenario the following components interact to produce the output files:
1. The batch processor.
2. The WSDL2ELS component, which does common WSDL-to-programming-language processing.
3. The WSDL2PLI component, which does WSDL-to-Enterprise-PL/I processing.
The sequence of processing is as follows:
1. The batch processor invokes the WSDL2ELS component, passing to it the input parameters specified in
the input properties files.
2. The WSDL2ELS component invokes the WSDL2PLI component:
• Together these two components produce a set of intermediate output files.
• Control is then returned to the batch processor.
3. The batch processor gathers the information in the intermediate output files, processes the
information, and generates the final output files.
The intermediate output files generated by WSDL2ELS and WSDL2PLI components are as follows:
• The mapping session files:
– There are two mapping session files for each operation defined in the WSDL file: one mapping session
file for the inbound message and one for the outbound message.
– Each mapping session file contains:
- Descriptions of the XML data structure and the programming language data structure that are the
source and target of the mapping session.
- A description of each the mapping of data between the source data structure and the target data
structure.

• A WSDL2ELS metadata file that is later used to generate the IMS application template file, the IMS
correlator file, and the XML converter files.
• A log file containing processing information. The name and location of file are specified in the
targetLogFile parameter of the WSDL2ELSSpec element of the ServiceSpecification.xml input file.
The files generated by the batch processor are as follows:
• The file containing the application template program:
– This program is a working template of an application that uses the IMS Web service provider.
– If the original WSDL file contains multiple operations then the template program is multioperation.
• The file or files containing the drivers and converters.
– There is one such file for each operation defined in the WSDL file.
– Each file contains a driver, an inbound converter, and an outbound converter.
• The IMS correlator file:
– This file contains information about using IMS Connect.
– If the WSDL file contains multiple operations then the correlator file is also multioperation.

404 Developer for z/OS: Developing with Db2, CICS, and IMS
 Mapping session files
This group of topics describe the characteristics of the mapping session files that are generated by
WSDL2ELS in the WSDL2PLI and WSDL2COBOL scenarios.

Overview of mapping session files

This topic describes the mapping session files created by the WSDL2ELS component in the WSDL2PLI and
WSDL2COBOL scenarios.
The purpose of the information of this topic is to provide a context for the descriptions of annotations in
the next two topics.
The WSDL2ELS component generates mapping session files for each message input, output, and fault3
message referenced by the set of operations defined by the user-specified combination of WSDL Service
and Port. Mapping session files are unidirectional, mapping either a composite XSD element declaration
to an 01-level language structure or an 01-level language structure to a composite XSD element
declaration. Therefore, at least two mapping session files are generated by WSDL2ELS in the WSDL2PLI
and WSDL2COBOL scenarios when an operation defines both an input and output message.
Each mapping session file describes the mappings that were computed by WSDL2ELS during the process
of generating language structures from a composite XSD element declaration that was referenced by
either an input, output, or fault3 message in a specific WSDL operation. Mapping session files can be
viewed for reference purposes with the Mapping Editor in the RDz workbench.
Mapping session files are generated using a subset of the metadata format defined by the
com.ibm.ccl.mapping framework. This is the same framework that is used when mapping session files
are manually created in the meet-in-middle scenario.
Figure 53 on page 406 shows an example of a mapping session file. The top-level structure is a
mappingRoot element that contains the following elements:
• An input element specifies the location of the source structure of the mapping. In the example below
this is the location of the XSD schema structure named CalculatorInput defined in the types section
of a WSDL file.
• An output element specifies the location of the target structure of the mapping. In the example this is
the location of the PL/I source file Calculator.inc.
• An mappingDeclaration element specifies individual mappings:
Note: There can be multiple mappingDeclaration elements.
– First an input element and an output element specify the source structure and the target structure
for the individual mappings that follow.
– Then one or more mapping elements specify the fields within the source structure and target
structure that are mapped together. In the following example there are two such mapping elements,
each defining an individual mapping.

3 SOAP fault messages are not supported in the WSDL2COBOL scenario.

Developing web services and SOA with Enterprise Service Tools 405
 <ccl:mappingRoot xmlns:ccl="http://www.ibm.com/2006/ccl/Mapping"
domainID="com.ibm.etools.xmlent.mapping.domainxsd2pli" >

<ccl:input path="file:/C:/Calculator.wsdl? http://www.Calculator.com/schemas/

CalculatorInput"/>
<ccl:output path="file:/C:/Calculator.inc"/>

<ccl:mappingDeclaration name="Calculator.mapping">

<ccl:input path="CalculatorInput"/>
<ccl:output path="CALCULATORINPUT"/>

<ccl:mapping>
<ccl:input path="integerArray"/>
<ccl:output path="INTEGERARRAY"/>
</ccl:mapping>

<ccl:mapping>
<ccl:input path="allowOverflow"/>
<ccl:output path="ALLOWOVERFLOW"/>
</ccl:mapping>

</ccl:mappingDeclaration>
</ccl:mappingRoot>

Figure 53. Example contents of a mapping session file

Annotations for the mappingRoot element

This topic describes the annotations that are defined on the mappingRoot element in mapping session
files generated by the WSDL2ELS component in the WSDL2PLI and WSDL2COBOL scenarios.
WSDL2ELS includes annotations on the mappingRoot element in the WSDL2PLI and WSDL2COBOL
scenarios to provide additional information about the mapped WSDL file. The annotations are in form of
key-value pairs.
Table 108 on page 406 describes these annotations:

Table 108. Annotations added to the mappingRoot structure

Key: Description of value:
com.ibm.etools.xmlent.mapping.wsdlLocation The full platform-dependent location of the WSDL
file.
com.ibm.etools.xmlent.mapping.wsdlTargetNam The target namespace of the WSDL file.
espace
com.ibm.etools.xmlent.mapping.wsdlServiceNa The WSDL service that the mappingRoot element
me pertains to.
com.ibm.etools.xmlent.mapping.wsdlPortName The WSDL port that the mappingRoot element
pertains to.
com.ibm.etools.xmlent.mapping.wsdlOperation The WSDL Operation that the mappingRoot
Name element pertains to.

Annotations for the mapping element

This topic describes the annotations that are defined on the mapping element in mapping session files
generated by the WSDL2ELS component in the WSDL2PLI and WSDL2COBOL scenarios.
WSDL2ELS includes annotations on the input and output elements contained within each mapping
element if the source or target of the mapping is a language structure or structure member that
has functional relationship with some other language structure or language structure member. The
annotations correspond with suffixes that WSDL2ELS appends to PL/I identifiers and COBOL data names
as described in “Creation of PL/I identifiers” on page 387 and “Creation of COBOL data names” on page
370.

406 Developer for z/OS: Developing with Db2, CICS, and IMS
Table 109 on page 407describes these annotations:

Table 109. Annotations generated by WSDL2ELS in the WSDL2PLI scenario

Annotation Key: Value Suffix:
com.ibm.etools.xmlent.mapping.ePliPointerObje _cnt
ct
com.ibm.etools.xmlent.mapping.ePliPresenceO _bit
bject
com.ibm.etools.xmlent.mapping.ePliBase64Bina _buf_len
ryLengthObject
com.ibm.etools.xmlent.mapping.ePliPointerObje _ptr
ct
com.ibm.etools.xmlent.mapping.ePliPoolAreaLo _lim
calReferObject
com.ibm.etools.xmlent.mapping.ePliPoolAreaEx _lim
ternalReferObject
com.ibm.etools.xmlent.mapping.ePliPoolArea
com.ibm.etools.xmlent.mapping.ePliLocalRefer _lim
Object
com.ibm.etools.xmlent.mapping.ePliExternalRef _lim
erObject

Table 110. Annotations generated by WSDL2ELS in the WSDL2COBOL scenario

Annotation Key: Value Suffix:
com.ibm.etools.xmlent.mapping.eCobolCounter -cnt
Object
com.ibm.etools.xmlent.mapping.eCobolPresenc -bit
eObject
com.ibm.etools.xmlent.mapping.eCobolLocalOc -lim
cursObject

WSDL2PLI metadata file

This topic describes the metadata file that is generated in the WSDL2PLI scenario.
The WSDL2PLI component generates metadata to record the high-level relationships between the user-
supplied WSDL file and the WSDL2PLI-generated artifacts. The metadata file is in XML format and is used
by the Batch Processor to generate XML Converters, deployment metadata, and template programs. It is
also used by other tools.
Figure 54 on page 408 shows the XML schema for the WSDL2PLI metadata file. The XML schema target
namespace and root element are versioned to make evolution of the metadata format possible in future
releases of Developer for z/OS.

Developing web services and SOA with Enterprise Service Tools 407
 <?xml version="1.0" encoding="utf-8" ?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" targetNamespace="http://www.ibm.com/
8_0_0_0/wsdl2elsmetadata" xmlns:w2e="http://www.ibm.com/8_0_0_0/wsdl2elsmetadata"
attributeFormDefault="qualified"
elementFormDefault="qualified">

<xsd:element name="Wsdl2elsMetadata">
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="w2e:parameters" />
<xsd:element ref="w2e:preferences" />
<xsd:element ref="w2e:service" />
</xsd:sequence>
<xsd:attribute name="version" type="xsd:string" default="8.0.0.0" />
</xsd:complexType>
</xsd:element>

<xsd:element name="parameters">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="sourceWsdlFile" type="xsd:string" />
<xsd:element name="sourceWsdlService" type="xsd:QName" />
<xsd:element name="sourceWsdlPort" type="xsd:string" />
<xsd:element name="targetLanguageFile" type="xsd:string" />
<xsd:element name="targetMappingDirectory" type="xsd:string" />
<xsd:element name="targetMetadataFile" type="xsd:string" />
<xsd:element name="targetLogFile" type="xsd:string" />
</xsd:sequence>
</xsd:complexType>
</xsd:element>

<xsd:element name="preferences">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="enterpriseLanguage" type="xsd:string" />
<xsd:element name="enterpriseEnvironment" type="xsd:string" />
<xsd:element name="isServiceRequester" type="xsd:boolean" />
<xsd:element name="hostCCSIDIsDBCS" type="xsd:boolean" />
<xsd:element name="defaultStringLength" type="xsd:int" />
<xsd:element name="defaultTotalDigits" type="xsd:int" />
<xsd:element name="defaultFractionDigits" type="xsd:int" />
<xsd:element name="defaultDateTimeLength" type="xsd:int" />
<xsd:element name="elementMaxOccursLimit" type="xsd:int" />
<xsd:element name="languageNameLimit" type="xsd:int" />
</xsd:sequence>
</xsd:complexType>
</xsd:element>

<xsd:element name="service">
<xsd:complexType>
<xsd:sequence>
<xsd:element maxOccurs="unbounded" ref="w2e:operation" />
</xsd:sequence>
<xsd:attribute name="name" type="xsd:QName" use="required" />
<xsd:attribute name="port" type="xsd:string" use="required" />
<xsd:attribute name="binding" type="xsd:QName" use="required" />
</xsd:complexType>
</xsd:element>

<xsd:element name="operation">
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="w2e:input" minOccurs="0" />
<xsd:element ref="w2e:output" minOccurs="0" />
<xsd:element ref="w2e:fault" minOccurs="0" maxOccurs="unbounded" />
</xsd:sequence>
<xsd:attribute name="name" type="xsd:string" use="required" />
</xsd:complexType>
</xsd:element>

<xsd:element name="input">
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="w2e:soapHeaderLanguageBinding" minOccurs="0" />
<xsd:element ref="w2e:soapBodyLanguageBinding" minOccurs="1" />
</xsd:sequence>
</xsd:element>

<xsd:element name="output">
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="w2e:soapHeaderLanguageBinding" minOccurs="0" />
<xsd:element ref="w2e:soapBodyLanguageBinding" minOccurs="1" />
</xsd:sequence>
408 Developer</xsd:complexType>
for z/OS: Developing with Db2, CICS, and IMS
</xsd:element>
WSDL2ELS limitations and restrictions
This topic describes limitations and restrictions for the WSDL2ELS component in the WSDL2PLI and
WSDL2COBOL scenarios.

WSDL files
The following limitations and restrictions apply to WSDL files:
• WSDL2ELS supports WSDL 1.0 and 1.1 and SOAP 1.0 and 1.1.
• The WSDL document must have a document-literal wrapped style SOAP binding. The following
conditions can be raised when WSDL2ELS is given a WSDL document with an unsupported SOAP
binding style:
– CRRZX0114E An unsupported SOAP binding style style_name was specified for
Port Binding binding_name of Port port_name of Service service_name.
– CRRZX0116E An unsupported SOAP operation style style_name was specified
for Operation operation_name of Port Binding binding_name of Port
port_name of Service service_name.
– CRRZX0115E An unsupported SOAP body use use_name was specified for
Operation operation_name of Port Binding binding_name of Port port_name of
Service service_name.

XSD structures
The following limitations apply to XSD structures:
• XML schemas must have unique target namespaces within the context of the source WSDL. If
WSDL2ELS detects that an XML schema has a non-unique target namespace then the following
condition is raised:

CRRZX0102E An error occurred while importing a WSDL file. The XML Schema
target namespace target_namespace is not unique within the context of the
WSDL file.
• The XSD built-in type anySimpleType is not supported. If WSDL2ELS detects that an XSD element or
attribute is of this type then the following condition is raised:

CRRZX0121E An unsupported built-in primitive or derived simple type "http://

www.w3.org/2001/XMLSchema:anySimpleType" was specified for XSD XPath:
qualified_element_or_attribute_path.
• The XSD built-in complex type anyType is not supported. If WSDL2ELS detects that an XSD element
declaration or reference is of this type then the following condition is raised:

CRRZX0119E An unsupported complex type "http://www.w3.org/2001/

XMLSchema:anyType" was found at XSD XPath: qualified_element_path.
• The XSD built-in simple type hexBinary is not supported. If WSDL2ELS detects that an XSD element or
attribute is of this type then the following condition is raised:

CRRZX0121E An unsupported built-in primitive or derived simple type

"http://www.w3.org/2001/XMLSchema:hexBinary" was found at XSD XPath:
qualified_element_or_attribute_path.
• The model group compositor choice is not supported. If WSDL2ELS detects that an XSD element
declaration or reference is a member of this compositor then the following condition is raised:

CRRZX0120E An unsupported model group compositor "choice" was specified for

XSD XPath: qualified_element_path.

Developing web services and SOA with Enterprise Service Tools 409
 • Recursive complex type references are not supported. If WSDL2ELS detects that an XSD element
specifies a complex type of which it is already a direct or indirect member, then the following condition
is raised:

CRRZX0117E A recursive reference to complex type qualified_complexType_name

was made by XSD element: qualified_element_name.
• Variable occurrence model group compositors are not supported. If WSDL2ELS detects that an XSD
element is a member of, for example, a variable occurrence compositor, then the following condition is
raised:

CRRZX0123E A variable occurrence model group compositor was specified for

XSD XPath: qualified_element_path.
• The XML schema wildcards anyAttribute and any are not supported. If WSDL2ELS detects a
wildcard while processing an XML schema then the following conditions can be raised:
– CRRZX0122E An unsupported XSD Wildcard "http://www.w3.org/2001/
XMLSchema:any" was found at XSD element: qualified_element_name.
– CRRZX0122E An unsupported XSD Wildcard "http://www.w3.org/2001/
XMLSchema:anyAttribute" was found at XSD element: qualified_element_name.
• WSDL2ELS does not support global element substitution and therefore ignores the
substitutionGroup attribute on XSD element declarations.
• While xs:base64Binary fields can be used to transmit large binary objects into and out of IMS
(WSDL2PLI only), great care should be taken when sizing these fields to avoid negative impacts on
performance.

Enterprise PL/I structures

The following limitations apply to Enterprise PL/I structures:
• A single PL/I major structure (level 01) is generated to contain all of the minor structures and
elementary variables that correspond to XML elements and attributes in the source XML schema. The
maximum size of a PL/I major structure is 231 - 1 bytes.
The characteristics of enterprise language structures might decrease the amount of XML data that can
be parsed or generated. For example, although the literal 'John Doe' requires only 8 bytes to encode in
EBCDIC, saving it in the field “05 cust_name CHAR(255)” requires 255 bytes.
• PL/I major structures support a maximum nesting depth of 15 levels for minor structures, arrays, and
elementary variables. Therefore the maximum supported nesting depth of elementary, composed, and
array XML elements is 15. If WSDL2ELS detects an XSD element declaration with a depth greater than
15 then the following condition is raised:

CRRZX0118E The maximum XSD element hierarchy depth of 15 has been exceeded
at XSD XPath: qualified_element_path.
• WSDL2ELS does not support generation of language structures for SOAP Headers or SOAP Header faults
in the WSDL2PLI scenario.

Enterprise COBOL structures

The following limitations apply to Enterprise COBOL structures:
• WSDL2ELS does not support the generation of language structures for SOAP faults, SOAP Headers, or
SOAP Header faults in the WSDL2COBOL scenario.
• A single COBOL 01-level group item is generated to contain all of the subordinate group and
elementary data items that correspond to XML elements and XML attributes in the source XML
schema. Beginning with Enterprise COBOL V3R4, the maximum size of a COBOL 01-level group
item is 227-1 bytes. Incidentally, the maximum size of the COBOL working-storage, linkage, and
local-storage sections is also 227-1 bytes, therefore it is important to use the WSDL2ELSSpec/

410 Developer for z/OS: Developing with Db2, CICS, and IMS
 @defaultMaxOccursLimit and WSDL2ELSSpec/@defaultCharMaxLength attributes to avoid generating
structures that are unnecessarily large.
• The characteristics of enterprise language structures might decrease the amount of XML data that can
be parsed or generated. For example, although the literal 'John Doe' requires only 8 bytes to encode in
EBCDIC, saving it in the field “05 CUST-NAME PIC X(255)” requires 255 bytes.
• COBOL supports a maximum nesting depth of 49 levels for subordinate group and elementary data
items, and the maximum number of dimensions for an array (table) is limited to 7. Therefore, the
maximum supported total nesting depth of XSD element declarations is 49 with a limit of 7 dimensions
on XSD element arrays. If WSDL2ELS detects that an XSD element declaration exceeds the total nesting
depth limit of 49, or the array dimension limit of 7, WSDL2ELS will terminate with one of the following
messages:
– CRRZX0118E The maximum XSD element hierarchy depth of maximum_depth has
been exceeded at XSD XPath: qualified_element_path.
– CRRZX0135E The maximum XSD element array dimension limit of dimension_limit
has been exceeded at XSD XPath: qualified_element_path.

Batch processor
The batch processor is a command-line utility for generating enterprise Web service description files and
message converter files for CICS and IMS applications.

Web service files generated by the batch processor are identical to those generated in the single-service
projects (see “Web service development scenarios: Single-service projects” on page 136).
The advantages of using the batch processor are (a) that it reads configuration information from
generation properties files that you can save and reuse, and (b) that optionally it can generate Web
service files for multiple Web services in one execution.
The generation properties files for the batch processor are
• Container.xml
• ServiceSpecification.xml
• PlatformProperties.xml
Note: To make the batch processor generate files for more than one Web service, create a separate and
uniquely named ServiceSpecification.xml file for each Web service.
The batch processor supports the following scenario that is not supported by the single-service wizards:
• Create New Service Implementation (top-down) for the IMS Enterprise Suite SOAP Gateway runtime
environment, with Compiled Conversion and Enterprise PL/I language only (see “Generation properties
for the top-down scenario with IMS Enterprise Suite SOAP Gateway, Enterprise PL/I, and compiled
conversion” on page 417).
Related tasks

“Creating and configuring generation properties files” on page 412

“Starting the batch processor” on page 413

Related references

“Container.xml” on page 417

“PlatformProperties.xml” on page 421
“ServiceSpecification.xml” on page 443

Developing web services and SOA with Enterprise Service Tools 411
 Creating and configuring generation properties files
This topic describes how to create generation properties files to use with the batch processor.
Using generation properties files and the batch processor has the following advantages over using the
graphical user interface:
• It allows regeneration of artifacts without having to remember and reenter inputs to the launchpad and
the single-service wizard.
• It provides a record of the options that were specified when the artifacts were generated.

Creating generation properties files with a single-service wizard

To create generation properties with a single-service wizard:
1. Start the Wizard Launchpad from a type of project other than a single-service project.
2. On the launchpad select Save generation properties (see “The Save generation properties checkbox”
on page 200).
3. Start the wizard for the development scenario for which you want to create generation properties files.
4. Work through the pages of the wizard, selecting for each option the value that you want to be specified
in the properties file for the batch processor.
5. On the File, data set, or member selection page, on the Properties tab, specify the path and names
that you want to use for the three generation properties output files (see “Properties tab” on page
213).
6. Click Finish when you are ready to close the wizard.
The wizard does its usual processing and in addition creates the three generation properties files required
by the batch processor, using the values that you specified.
You can now run the batch processor using the three new generation properties files.

Creating generation properties files manually from the sample files

To create generation properties manually from the sample files:
1. Create a input directory to contain the new generation properties files.
2. Copy the following three sample files from the sample directory into the input directory (see “Location
of the sample generation properties files” on page 413):
• PlatformProperties.xml
• ServiceSpecification.xml
• Container.xml
Note: You can rename these files if you like. Be sure to specify the new names when you refer to these
files.
3. Open each sample file with an editor and set the appropriate values for the configurable properties:
• PlatformProperties.xml:
– Set the properties for the target runtime environment.
• ServiceSpecification.xml:
– Set the properties for generating the conversion programs and the service definitions.
– You can override certain properties that were specified in PlatformProperties.xml.
Tip: To generate output files for more than one Web service, create and configure a separate and
uniquely named ServiceSpecification.xml file for each Web service.
• Container.xml

412 Developer for z/OS: Developing with Db2, CICS, and IMS
 – In the GenerationSpecArray element set the platformProperties attribute to the name of the
current PlatformProperties.xml file.
– Add a GenerationSpec element for each set of output files that you want to create and specify the
name of the appropriate ServiceSpecification file.
You can now run the batch processor with the newly configured generation properties files.

Location of the sample generation properties files

The sample files are located in the following directories:
•
For Windows the sample files are located in the following directories:
– plugins_directory\ui_directory\BatchProcessorSamples\EISService
– plugins_directory\ui_directory\BatchProcessorSamples\EISServiceImplementati
on
where plugins_directory is the complete path to the subdirectory named "plugins" within the
product installation directory. For example:

C:\Program Files\IBM\SDPShared\plugins

and where ui_directory is the directory

com.ibm.etools.est.ui_rrrrrr.vyyyymmdd_hhmm

in which rrrrrr is a one-to-eight-character release number and yyyymmdd_hhmm is a time stamp

showing the year, month, day, hour, and minute.
Here are examples of a complete file path for the sample directories in Windows:
– C:\Program
Files\IBM\SDPShared\plugins\com.ibm.etools.est.ui_8.3.0.v20100527_1540\Batc
hProcessorSamples\EISService
– C:\Program
Files\IBM\SDPShared\plugins\com.ibm.etools.est.ui_8.3.0.v20100527_1540\Batc
hProcessorSamples\EISServiceImplementation

Starting the batch processor

The batch processor is a command-line interface for generating the same types of output files as are
generated by the single-service wizards.

Tip: When you run a single-service wizard it automatically creates three generation properties files that
you can use with the batch processor to generate the same files that were generated by the single-service
wizard (see “Creation of generation properties files for the batch processor” on page 195).
Important: Before you run the batch processor, close any running instance of Developer for z/OS that
uses the target workspace.
Start the batch processor by entering the following command from the command line or executing it from
a script. There are three formats of the invocation:

Developing web services and SOA with Enterprise Service Tools 413
 (1) xsebatch -s languageFile [-c | -w serviceName] | [-c -w serviceName]
-f containerFile [-d workspace] [-e WS_installdir] [-verbose]
[-version] [-novalidation] [-overwrite=yes|no] [-annot synFile]
[-commtypes commTypesFile] [-whitespacecompat]

(2) xsebatch -f containerFile [-d workspace] -c [-e WS_installdir] [-verbose]

[-version] [-novalidation] [-whitespacecompat]

(3) xsebatch -s sourceWSDL | -f containerFile [-d workspace] -c

[-e WS_installdir] [-verbose] [-version] [-novalidation]

Figure 55. Formats for the parameters of the batch processor invocation:

Format (1)
In Format (1) the following parameters are required: -s, -c or -w or both, and -f. This format applies to
the bottom-up scenario. The parameters used in Format (1) are:
-s languageFile: This parameter is required unless the same information is specified in the
importFile element. Here languageFile is the language source file that contains the message
definition. You can override this name by specifying values for the elements importDirectory and
inputFile in the MessageSpec element in the ServiceSpecification.xml file.

(-c | (-w serviceName)) | -c -w serviceName: One or both of the -c and the -w

serviceName parameters are required:
• -c causes the set of language converters, the driver, and XML schemas to be generated. You
can override this option by using the generateConverters and the generateSeparateXSD options in
the Container.xml file and in the ServiceSpecification.xml file. The option generateSeparateXSD=true
produces XSD files only if -c (or generateConverters=true) is specified.
• w serviceName causes the service definition files to be generated using the specified name for
the Web service. You can override this option by using the generateWSDL option in the Container.xml
file and in the ServiceSpecification.xml file. The value of this parameter can be overridden by the value
attribute of the EISService element in the ServiceSpecification.xml file. The default value is set to
esvc.

-f containerFile: In Format (1) this parameter is required. It specifies the name of the
Container.xml file that contains the generation options. Most of the elements in this file are optional,
but a few are required and must be specified.

-d workspace: See Format (3).

-e WS_installdir: See Format (3).

-verbose: See Format (3).

-version: See Format (3).

-novalidation: See Format (3).

-overwrite=yes|no: If set to yes then this parameter causes newly generated files to overwrite
existing files of the same names. If set to no then new names are provided for generated files that
would otherwise overwrite existing files. The new name of the file contains an integer number as suffix
that is incremented for each duplicate file until a unique name is found (for example, myfile12o.xsd).
Overwriting converters and the XSD file can be further refined by the value of the overwrite attribute
of the file generation specification elements contained in the XseSpec element (see “XseSpec” on
page 511).

414 Developer for z/OS: Developing with Db2, CICS, and IMS
 -annot synFile: This parameter specifies the absolute path and file name of the synonym action
XML file. The synonym action XML file contains the optional annotation information that can be present
in the source code of the service interface data declarations. When this parameter is specified the
annotation information is included with the service interface data declarations in the generated files.
The information in this file is applied to all source files during the invocation of xsebatch (see “Using
source annotations to specify service interface” on page 297).

-commtypes commTypesFile: This parameter specifies the absolute path and file name of the
common types XML file. The common types XML file describes the common elements and types that
exist among all the various elements and types that are going to be used in the generated files. When
this parameter is specified the generated WSDL and XSD schema refer to the common elements and
types instead of imbedding and potentially duplicating the elements and types. The information in this
file is applied to all source files during the invocation of xsebatch (see “Commonly Used Elements and
Types” on page 302).

-whitespacecompat: This parameter causes any trailing spaces to be trimmed in LS2XML converters
when a whitespace facet is not declared in an XSD element or an attribute. When this option is
not specified, spaces are handled with whitespace="perserve" in the converting elements that are
declared with no whitespace.

Format (2)
In Format (2) the following parameters are required: -d, -c or -e or both. This format applies to the
meet-in-middle scenario. The parameters used in Format (2) are:
-d workspace: See Format (3).

-e WS_installdir: See Format (3).

-verbose: See Format (3).

-version: See Format (3).

-novalidation: See Format (3).

-whitespacecompat: See Format (1).

Format (3)
In Format (3) either the -s parameter or the -f parameter is required and the -c parameter is required.
This format applies to the top-down scenario. The parameters in Format (3) are:
-s sourceWSDL: Either this parameter or the -f parameter is required. sourceWSDL is the name of
the source WSDL file. When this parameter is specified all the generation options and configuration
preferences are set from default values. If the -d parameter is also present then it specifies the
location of the default preferences. Otherwise the default preferences are set by the generation
engines.

-f containerFile: In Format (3) either this parameter or the -s parameter is required. This
parameter specifies the name of the Container.xml file that contains the generation options. Most
of the content of items in this file are optional, but a few are required and must be specified.

-c containerFile: In Format (3) this parameter is required. In Format (3) -c causes the following
artifacts to be generated: language structures, language converters, mapping metadata, a template
program, and runtime (IMS Enterprise Suite SOAP Gateway) metadata.

Developing web services and SOA with Enterprise Service Tools 415
 -d workspace: This parameter specifies the fully qualified path of the workspace to be used for
the import. If this path is not specified on the command line then the default is taken from the
environment variable workspace. If that environment variable is not set then the default is set to the
following:
• %eclipse_root%\workspace

-e WS_installdir: This parameter specifies is the Eclipse subdirectory of the directory in which
Developer for z/OS is installed. If not specified, the default is taken from an environment variable
eclipse_root. If that environment variable is not set then the default is set to the default installation
directory for Developer for z/OS. That directory is recorded during installation by the install process
and is set in the environment variable WDZ71INSTDIR.

Note on directory names for -d and -e: If a directory name contain spaces then it must be placed in
double quotes:
• "c:\my workspace"
Use the double quotes only when specifying values for command line parameters -d and -e. If you
use environment variables, omit double quotes for these values. Do not use a trailing file separator
character in the path names for the -d and -e options nor in the values of the environment variables
workspace and eclipse_root.

verbose: This parameter causes the diagnostic messages to be printed to the console.

version: This parameter causes the version, release, and modification information to be printed to
the console.

novalidation: This parameter turns off the validation of generation property files against an XML
Schema.

Status messages and error messages

You can see the progress of the xsebatch command in the console along with status messages and any
error messages.

Getting the output files

After the xsebatch program has finished running, restart Developer for z/OS to view the generated files in
the workspace, or browse the file system with Windows Explorer.
Related concepts

“Batch processor” on page 411

Related tasks

“Creating and configuring generation properties files” on page 412

Related references

“Container.xml” on page 417

“PlatformProperties.xml” on page 421
“ServiceSpecification.xml” on page 443

416 Developer for z/OS: Developing with Db2, CICS, and IMS
Generation properties for the top-down scenario with IMS Enterprise Suite
SOAP Gateway, Enterprise PL/I, and compiled conversion
This topic lists the generation properties that have a particular setting for the Create New Service
Implementation (top-down) scenario for the IMS Enterprise Suite SOAP Gateway runtime environment,
with compiled conversion and Enterprise PL/I language.
Note: This scenario is currently supported only in the batch processor.
Table 111 on page 417 shows the generation properties that have a particular setting for this scenario:

Table 111. Properties for top-down scenario, IMS SOAP Gateway, PL/I, and compiled conversion
Properties file: Element: Property:
PlatformProperties.xml CodegenPropertyArray type
CodegenPropertyArray. com.ibm.etools.xmlent.ui.GEN_CP_LIST
CodegenProperty
ServiceSpecification.xml EISServiceImplementation runtime
type
EISServiceImplementation. importFile
ServiceImplementationSpec
importDirectory
wsdlServiceName
targetLanguageFile
targetLogFile
targetMappingDirectory
targetMetadataFile
EISServiceImplementation. defaultCharMaxLength
ServiceImplementationSpec.
defaultTotalDigits
WSDL2ELSSpec
defaultFractionDigits
defaultDateTimeLength
InlineMaxOccursLimit
languageNameLimit

Container.xml
Container.xml is the top-level generation properties file used by the batch processor to create enterprise
Web service descriptions (in the “bottom-up” scenario), Web services implementation artifacts (in the
“top-down” scenario), and message converters for CICS and IMS applications.

Purpose
Container.xml contains the generation options and references to the Platform.xml and
ServiceSpecification.xml file.

Elements
Most of the content of items in this file is optional, but a few items are required. You can use the following
elements in the Container.xml document:

Developing web services and SOA with Enterprise Service Tools 417
 • “GenerationSpec” on page 420
• “GenerationSpecArray” on page 419

Sample
The “Container.xml sample” on page 420 illustrates the use of applicable elements and their attributes.

Schema
The “Schema for Container.xml” on page 420 provides the structure for the contents of the Container.xml
document.

BatchSpecContainer
Use this top-level element of the Container.xml document. This element is optional.

Contained by
None

Contains
“GenerationSpecArray” on page 419

Attributes
Fields Description
Internal purpose only.
Attribute: version
Required?: No
Valid values: See Description
Default value: See Description

Internal purpose only.

Attribute: release
Required?: No
Valid values: See Description
Default value: See Description

Internal purpose only.

Attribute: modelId
Required?: No
Valid values: See Description
Default value: See Description

Example

<BatchSpecContainer>
<GenerationSpecArray generateConverters="true"
generateSeparateXSD="true"
generateWSDL="true"
platformProperties="PlatformProperties.xml">
<GenerationSpec name="ServiceSpecification.xml"/>
<GenerationSpec name="ServiceSpecification2.xml"/>
</GenerationSpecArray>
</BatchSpecContainer>

418 Developer for z/OS: Developing with Db2, CICS, and IMS
 GenerationSpecArray
Use this element of the Container.xml document to provide information that globally affects the
generation of converters and service definitions. This element is required.

Contained by
BatchSpecContainer

Contains
“GenerationSpec” on page 420

Attributes
Fields Description
Specifies whether to generate the converter set (request and
Attribute: generateConverters
response converters, driver).
Required?: No
Valid values: true | false Note: The "false" setting of this attribute will cause the
Default value: false generateSeparateXSD attribute to be forced to "false". (This note
does not apply to the top-down scenarios.)

Specifies whether to generate a separate set of XML schemas that

Attribute: generateSeparateXSD
define the message (request and response).
Required?: No
Valid values: true | false Note: The "false" setting of this attribute is enforced if the
Default value: false generateConverters attribute is set to false and as a result, a value
of false is meaningful only if generateWSDL is set to true. A value of
false specifies that the service definition file contains an embedded
schema.
This attribute has no effect in the top-down scenarios.

Specifies whether to generate a service definition.

Attribute: generateWSDL
Required?: No This attribute has no effect in the top-down scenarios.
Valid values: true | false
Default value: false

Specifies the target generation platform.

Attribute: platform
Required?: No Note: OS390 is the currently supported value. Other values are
Valid values: OS390 reserved for future use.
Default value: OS390

Specifies the location of the platform property file. The path can be
Attribute: platformProperties
relative (as in ./PlatformProperties.xml) or absolute.
Required?: Yes
Valid values: See Description
Default value: See Description

Example

<GenerationSpecArray generateConverters="true"
generateSeparateXSD="true"
generateWSDL="true"
platformProperties="Platform.xml">
<GenerationSpec name="ServiceSpecification.xml"/>
</GenerationSpecArray>

Developing web services and SOA with Enterprise Service Tools 419
 GenerationSpec
Use this element to provide information about the ServiceSpecification.xml file, which specifies the
options for generating individual sets of converters and Web Service Definition Language (WSDL) files.

Contained by
“GenerationSpecArray” on page 419

Contains
None

Attributes
Fields Description
Specifies the path of the ServiceSpecification.xml file. This path can
Attribute: name
be either an absolute path or a path relative to the directory in which
Required?: Yes
Container.xml is located.
Default value: None

Example

<GenerationSpecArray
platformProperties="Platform.xml">
<GenerationSpec name="ServiceSpecification.xml"/>
</GenerationSpecArray>

<CodegenPropertyArray type="Cobol">
<CodegenProperty name="com.ibm.etools.xmlent.ui.GEN_PROG_NAME"
value="CWSA"/>
<CodegenProperty name=
"com.ibm.etools.xmlent.ui.GEN_CONVERSION_TYPE"
value="interpretive"/>
</CodegenPropertyArray>

Container.xml sample

<?xml version="1.0" encoding="UTF-8"?>

<BatchSpecContainer xmlns="http:///com/ibm/etools/xmlent/batch/emf/BatchProcessModel.ecore">
<GenerationSpecArray generateConverters="true"
generateSeparateXSD="true"
generateWSDL="true"
platformProperties="PlatformProperties.xml">
<GenerationSpec name="ServiceSpecification.xml"/>
<GenerationSpec name="ServiceSpecification2.xml"/>
</GenerationSpecArray>
</BatchSpecContainer>

Related references

Container.xml

Schema for Container.xml

Figure 56 on page 421 is an example of the schema for Container.xml.

420 Developer for z/OS: Developing with Db2, CICS, and IMS
 <?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
targetNamespace="http:///com/ibm/etools/xmlent/batch/emf/BatchProcessModel.ecore"
xmlns="http:///com/ibm/etools/xmlent/batch/emf/BatchProcessModel.ecore">
<xsd:element name="GenerationSpec">
<xsd:complexType>
<xsd:attribute name="name" type="xsd:string" use="required"/>
</xsd:complexType>
</xsd:element>
<xsd:element name="GenerationSpecArray">
<xsd:complexType>
<xsd:sequence>
<xsd:element maxOccurs="unbounded" minOccurs="1" ref="GenerationSpec"/>
</xsd:sequence>
<xsd:attribute name="platform" type="xsd:string" use="optional"/>
<xsd:attribute name="platformProperties" type="xsd:string" use="required"/>
<xsd:attribute name="generateConverters" type="xsd:boolean" use="optional"/>
<xsd:attribute name="generateSeparateXSD" type="xsd:boolean" use="optional"/>
<xsd:attribute name="generateWSDL" type="xsd:boolean" use="optional"/>
</xsd:complexType>
</xsd:element>
<xsd:element name="BatchSpecContainer">
<xsd:complexType>
<xsd:sequence>
<xsd:element maxOccurs="1" minOccurs="1" ref="GenerationSpecArray"/>
</xsd:sequence>
<xsd:attribute name="version" type="xsd:string" use="optional"/>
<xsd:attribute name="release" type="xsd:string" use="optional"/>
<xsd:attribute name="modelId" type="xsd:string" use="optional"/>
</xsd:complexType>
</xsd:element>
</xsd:schema>

Figure 56. Example of Schema for Container.xml

Related references

Container.xml

PlatformProperties.xml
PlatformProperties.xml is one of the three generation properties files used by the batch processor to
create enterprise Web services descriptions (in the “bottom-up” scenario), Web services implementation
artifacts (in the “top-down” scenario), and message converters for CICS and IMS applications.

Purpose
PlatformProperties.xml has the default options properties that reflect your target run-time environment.
The options affect, for example, the processing of the language types (such as COBOL data types) that
are used in producing XML schema descriptions of Web service messages that are based on that language
type.

Elements
You can use the following elements in the PlatformProperties.xml document:
• “CodegenProperty” on page 422
• “CodegenPropertyArray” on page 433
• “ConnectionProperty” on page 433
• “ConnectionPropertyArray” on page 434
• “ImportProperty” on page 435
• “ImportPropertyArray” on page 438
• “Platform” on page 439
• “PlatformArray” on page 439

Developing web services and SOA with Enterprise Service Tools 421
 Sample
The “PlatformProperties.xml sample” on page 440 illustrates the use of applicable elements and their
attributes.

Schema
The “Schema for PlatformProperties.xml” on page 441 provides the structure for the contents of the
PlatformProperties.xml document.
Related concepts

“Batch processor” on page 411

Related tasks

“Creating and configuring generation properties files” on page 412

“Starting the batch processor” on page 413

Related references

“Container.xml” on page 417

“ServiceSpecification.xml” on page 443

CodegenProperty
Use this element in the PlatformProperties.xml document to specify the properties for generating the
converter code, or in the ServiceSpecification.xml document to override the code generation properties
that you set in PlatformProperties.xml.

Contained by

“CodegenPropertyArray” on page 433

Contains
None

Attributes
Start the value of the name attribute with com.ibm.etools.xmlent.ui.
Table 112 on page 422 shows the attributes for CodegenProperty.

Table 112. Attribute Specifications for CodegenProperty

Fields Description
The value of this attribute directs the Batch Processor to generate
Attribute:
Compiled XML Conversion artifacts that are compatible with or
COBOL_COMPILER_LEVEL
optimized for the specified Enterprise COBOL or PL/I compiler
Valid values: See Description
version.
Default value: 5.2 (COBOL), 4.4 (PL/I)
Valid COBOL values: 3.4, 4.1, 4.2, 5.2
Valid PL/I values: 3.9, 4.1, 4.2, 4.3, 4.4

The generated author name. It must be formed according to COBOL

Attribute: GEN_AUTH_NAME
language rules.
Valid values: See Description
Default value: WSED

422 Developer for z/OS: Developing with Db2, CICS, and IMS
Table 112. Attribute Specifications for CodegenProperty (continued)
Fields Description
The values for this attribute define the bidirectional language
Attribute: GEN_BIDI_HOST
characteristics of the host data. The transformation is done from
Valid values: See Description
request XML data with characteristics specified by GEN_BIDI_OUT
Default value: None
to the host data with characteristics specified by this attribute after
the data is populated and converted to the appropriate bidirectional
language host page. See Supported code pages (CCSIDs).
The values for this attribute are the same as in the description for
GEN_BIDI_IN. If this attribute is specified, you are also required to
specify GEN_BIDI_IN or GEN_BIDI_OUT or both.
Note: If you do not specify either of the required attributes, no
bidirectional language transformation will be performed.

The values for this attribute define the bidirectional language

Attribute: GEN_BIDI_IN
characteristics of the request XML data. The transformation is done
Valid values: See Description
from source messages with these characteristics to the host data
Default value: None
with characteristics specified by GEN_BIDI_HOST after the data is
populated and converted to the appropriate bidirectional language
host page.
See Supported code pages (CCSIDs) If this attribute is specified, you
are also required to specify GEN_BIDI_HOST.
Note: If you do not specify either of the required attributes, no
bidirectional language transformation will be performed.
The values for this attribute can be formed by concatenating the
appropriate transformation attributes as follows:
• "VISUAL" or "LOGICAL" for Text type
• "LTR" or "RTL" for Text orientation
• "SYMSWAP" or blank for Symmetric swapping
• * "NUMSWAP" or blank for Numeric swapping
For example: VISUALRTLSYMSWAP You can specify the
transformation attributes in any order.

The values for this attribute define the bidirectional language

Attribute: GEN_BIDI_OUT
characteristics of the response XML data. The transformation
Valid values: See Description
will be done from host data with characteristics specified by
Default value: None
GEN_BIDI_HOST to the response XML data with characteristics
specified by this attribute before the host data is converted to the
response code page. See Supported code pages (CCSIDs).
If this attribute is specified, you are also required to specify
GEN_BIDI_HOST. If you do not specify either of the required
attributes, no bidirectional language transformation will be
performed. The values for this attribute are the same as in the
description for GEN_BIDI_IN.

The value of this attribute directs the COBOL converter generators to

Attribute:
generate code based on the XML parser selected for the COBOL XML
GEN_COBOL_XMLPARSE_OPTION
PARSE statement.
Valid values: COMPAT, XMLSS
Default value: COMPAT This option is only valid if COBOL_COMPILER_LEVEL is set to 4.1.

Developing web services and SOA with Enterprise Service Tools 423
Table 112. Attribute Specifications for CodegenProperty (continued)
Fields Description
This attribute has an effect only when you are generating a Web
Attribute:
service using the bottom-up method and you are using compiled XML
GEN_COMMENT_IN_XSD
conversion.
Valid values: See Description
Default value: false When this attribute is set to TRUE, the comments from the COBOL
source code file are generated as annotation documentation in the
generated XSD and WSDL files.
See “Including COBOL source code comments in generated XSD and
WSDL files” on page 327 for more information about this attribute.

Specifies the type of conversion services that are generated.

Attribute:
GEN_CONVERSION_TYPE The value interpretive is valid only for the following types of single-
Valid values: See Description service projects:
Default value: compiled
• Web services for CICS project
See “Batch processor options applicable for interpretive conversion
type” on page 527.
For the remaining types of single-service projects the value of this
attribute is always assumed to be compiled, even if you specify
interpretive.
When this attribute is set to interpretive, you can also specify
the name of the log file generated by the Web Services Assistant,
using the logFileName attribute in the WSBindSpec element of
“ServiceSpecification.xml” on page 443.

Code page for the host converter program. See Supported code page
Attribute: GEN_CP_LIST
combinations.
Valid values: See Description
Default value: 1140

This attribute is used to control the format of the decimal fraction

Attribute: GEN_DEC_COMMA
separator. If this option is set to true, the decimal fraction separator
Valid values: See Description
is set to be a comma.
Default value: false

Attribute: This attribute has an effect only when you are generating source code
GEN_ERROR_FEEDBACK_FILE_PATH for a Web service using the bottom-up method and using compiled
Valid values: See Description XML conversion.
Default value: 1140 When this attribute is specified, the source code generator validates
the syntax of the main COBOL input file and its included COBOL files
and, if any COBOL syntax errors are detected, writes appropriate
error information into the output file that you specify.
When you use this attribute:
• Specify the name attribute to enable this option.
• In the value attribute, specify an output file path or file name.
See “Logging syntax errors detected in COBOL input files” on page
525 for more information about this attribute.

424 Developer for z/OS: Developing with Db2, CICS, and IMS
Table 112. Attribute Specifications for CodegenProperty (continued)
Fields Description
The value of this attribute determines the value of the
Attribute:
elementFormQualified attribute in XML Schemas generated by the
GEN_ELEMENT_FORM_QUALIFIED
tool. This option only affects the "Compiled XML Conversion"
Valid values: See Description
conversion type.
Default value: true

This attribute is used to control whether generated XML schemas

Attribute: GEN_FLAT_GEN
have flat or hierarchical structure. If this option is set to true, the
Valid values: See Description
generators are set to generate flat schemas.
Default value: false

Code page for the request (input) message. See Supported code
Attribute: GEN_IN_CP_LIST
pages (CCSIDs).
Valid values: See Description
Default value: 1140 Note: If you are generating artifacts for the IMS Enterprise Suite
SOAP Gateway, you must specify UTF-8 (value="1208") as Code
page for the request (input) message (GEN_IN_CP_LIST) and UTF-8
(value="1208") as Code page for the response (output) message
(GEN_OUT_CP_LIST). Any other values are not allowed and will cause
a runtime error if specified.

The value of this attribute directs the COBOL and PL/I XML converter
Attribute:
generators to generate code that is compatible with the IMS
GEN_IMS_MESSAGE_TYPE
Asynchronous Callout (ASYNC) or IMS Synchronous Callout (SYNC)
Valid values: ASYNC | SYNC
functions.
Default value: ASYNC

If "true" is specified as the value of this attribute, the XML Schema

Attribute:
and XML converter generators will avoid the use of XML Namespaces
GEN_OMIT_XML_NAMESPACES
in XML instances. The specific effects of this option are: XML
Valid values: true | false
Schemas will have a null target namespace, and the response XML
Default value: false
converter will omit namespaces from the generated XML.
Code page for the response (output) message. See Supported code
Attribute: GEN_OUT_CP_LIST
page combinations.
Valid values: See Description
Default value: 1140 Note: If you are generating artifacts for the IMS Enterprise Suite
SOAP Gateway, you must specify UTF-8 (value="1208") as Code
page for the request (input) message (GEN_IN_CP_LIST) and
UTF-8 (value="1208") as Code page for the (output) message
(GEN_OUT_CP_LIST). Any other values are not allowed and will cause
a runtime error if specified.

This attribute is used to control whether the response XML converter

Attribute: GEN_OUT_FILTER
will filter characters in the language structure that are illegal in XML
Valid values: See Description
1.0.
Default value: true

This attribute is used to control whether the response XML converter

Attribute: GEN_OUT_HALT
will halt and report an error if characters illegal in XML 1.0 are found
Valid values: See Description
in the language structure.
Default value:

The generated program name. It must be formed according to COBOL

Attribute: GEN_PROG_NAME
language rules. The default is set to the COBOL copybook (or source
Valid values: See Description
program) file name shortened to 7 characters and converted to
Default value: 1140
uppercase.

Developing web services and SOA with Enterprise Service Tools 425
Table 112. Attribute Specifications for CodegenProperty (continued)
Fields Description
The value of this attribute controls how complex type names are
Attribute:
generated from the COBOL group items. The value of "true" will cause
GEN_SHORT_TYPE_NAMES
the type name to be shortened to contain just the name derived from
Valid values: See Description
the group name itself and not the names of all the parent groups.
Default value: false
The value of "false" will cause the type name to contain the names
derived from all the parent groups. This attribute has no effect on
top-down or meet-in-middle scenarios.
The value of this attribute controls what version of the SOAP protocol
Attribute: GEN_SOAP_VERSION
binding is generated by the single-service project tools in a WSDL
Valid values: See Description
file. The valid values for this option are "1.1", "1.2", and "ALL". When
Default value: See Description
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 GEN_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
minimumRuntimeLevel to a value of 2.0. For additional information,
see the description of the runtimeLevel attribute (runtimeLevel) in the
WSBindSpec function.
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.

This attribute is used to control whether generated XML schemas

Attribute:
have totalDigits and fractionDigits for COBOL numeric data types. If
GEN_TOTAL_FRACTION_DIGITS
this option is set to true, the generators are set to generate total/
Valid values: See Description
fractionDigits. The following rules are applied if the user chooses for
Default value: false
generation of total/fractionDigits
• For COBOL decimal types, generate both totalDigits and
fractionDigits. For example:
– pic 9(13)v9(2): totalDigits = 15, fractionDigits = 2
– pic s99v9: totalDigits = 3, fractionDigits = 1
• For COBOL integer types, generate only totalDigits. For example
– pic 99 or 99v or s99: totalDigits = 2
• Not generated, if the COBOL numeric data item has any "leading or
trailing zeroes". For example:
– pic P9 or 9PP.

426 Developer for z/OS: Developing with Db2, CICS, and IMS
Table 112. Attribute Specifications for CodegenProperty (continued)
Fields Description
The value of this attribute indicates to the batch processor whether
Attribute:
or not to generate Web service artifacts compatible with MTOM
GEN_USE_MTOM_XOP
(Message Transformation Optimization Mechanism)/XOP (XML-binary
Valid values: true | false
Optimization Package). When the value of this attribute is true, the
Default value: false
behavior of the batch processor is modified in the following ways:
• 01 level language structures specified on the InputMessage
and OutputMessage elements are treated as simple 01 level
character arrays before being passed to DFHLS2WS; this occurs
so that they each language structure is represented as a single
xsd:base64binary typed element in the Web service description.
• The value of the attribute XseSpec/WSBindSpec/@charVarying is
assumed to be “true”.
Note: This attribute only affects the output of the batch
processor when GEN_CONVERSION_TYPE = "interpretive" and the
ServiceSpecification.xml/EISService element is used (bottom-up).
For additional description, see “Generate CICS MTOM/XOP Web
Service (Bottom-Up)” on page 271

The value of this attribute controls whether the namespace name

Attribute:
of the top level element of request XML instance documents will
GEN_VALIDATE_ROOT_IN_NS
be validated against the namespace name specified in the request
Valid values: See Description
XML schema. This option only affects the "Compiled XML Conversion"
Default value: false
conversion type.
The value of this attribute controls what version of the WSDL
Attribute: GEN_WSDL_VERSION
(Web service description) is generated by single-service project
Valid values: See Description
tools. Currently the valid values for this option are "1.1" and "2.0".
Default value: 1.1
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, see the description
of the mappingLevel attribute ( mappingLevel) and the runtimeLevel
attribute (runtimeLevel) in the WSBindSpec function.

This attribute is used to control generation of groups in the XML

Attribute: GEN_XSD_GROUPS
schema. If this option is set to true, the XML schema can contain
Valid values: See Description
schema groups and grouprefs.
Default value: false

Developing web services and SOA with Enterprise Service Tools 427
Table 112. Attribute Specifications for CodegenProperty (continued)
Fields Description
In contrast to the INIT_OMITTED_ITEMS_IN_INTERFACE (the next
Attribute:
attribute described in this table), this attribute enables initialization
INIT_EMPTY_ITEMS_IN_INTERFACE
for data items in the request language structure that you have
Valid values: See Description
included in the Web service input data structure.
Default value: false
This attribute applies only to the bottom-up scenario for generating a
Web service, and apply only if you specify Compiled XML Conversion.
When this attribute is enabled, VALUE clauses in the request
language structure that you specified for the new Web service are
given effect by initialization code that is executed before the new
Web service invokes the existing COBOL application (service provider
application or service requester application.
However, even when this attribute is enabled, it does not affect a
particular COBOL data item unless the corresponding XML element in
the request XSD Schema data structure is empty.
VALUE literals must be defined in one line. They must not be
continued.
See “Initializing data items in the COBOL application's input data
structure” on page 325 for more information about this attribute.

In contrast to the INIT_EMPTY_ITEMS_IN_INTERFACE (the previous

Attribute:
attribute described in this table), this attribute enables initialization
INIT_OMITTED_ITEMS_IN_INTERFACE
for data items in the request language structure that you have
Valid values: See Description
excluded from the Web service input data structure.
Default value: false
This attribute applies only to the bottom-up scenario for generating a
Web service, and apply only if you specify Compiled XML Conversion.
When this attribute is enabled, VALUE clauses in the request
language structure that you specified for the new Web service are
given effect by initialization code that is executed before the new
Web service invokes the existing COBOL application (service provider
application or service requester application).
VALUE literals must be defined in one line. They must not be
continued.
See “Initializing data items in the COBOL application's input data
structure” on page 325 for more information about this attribute.

The value of this option is assumed to be false if the host code page is
Attribute:
not a supported EBCDIC SBCS code page; see help topic “Supported
GEN_USE_HOST_CP_INT_XML
code page combinations” on page 430 for a list of supported EBCDIC
Valid values: true | false
SBCS code pages. Set this option to false only when mapping XML
Default value: true
elements or XML attributes whose tag names contain characters that
do not have a representation in the host code page.
Note: This option is currently only supported for COBOL.

Example
Figure 57 on page 429 is an example of CodgenProperty elements within the CodgenPropertyArray
element.

428 Developer for z/OS: Developing with Db2, CICS, and IMS
 <CodegenPropertyArray type="Cobol">
<CodegenProperty name="com.ibm.etools.xmlent.ui.GEN_PROG_NAME" value="XCNV"/>
<CodegenProperty name="com.ibm.etools.xmlent.ui.GEN_CONVERSION_TYPE" value="interpretive"/>
<CodegenProperty name="com.ibm.etools.xmlent.ui.GEN_AUTH_NAME" value="WSED"/>
<CodegenProperty name="com.ibm.etools.xmlent.ui.GEN_DEC_COMMA" value=" false"/>
<CodegenProperty name="com.ibm.etools.xmlent.ui.GEN_FLAT_GEN" value=" false"/>
<CodegenProperty name="com.ibm.etools.xmlent.ui.COBOL_COMPILER_LEVEL" value="3.4"/>
<CodegenProperty name="com.ibm.etools.xmlent.ui.GEN_SHORT_TYPE_NAMES" value="true"/>
<CodegenProperty name="com.ibm.etools.xmlent.ui.GEN_WSDL_VERSION" value="2.0"/>
<CodegenProperty name="com.ibm.etools.xmlent.ui.GEN_SOAP_VERSION" value="1.2"/>

<CodegenProperty name="com.ibm.etools.xmlent.ui.GEN_TOTAL_FRACTION_DIGITS" value="false"/>

<CodegenProperty name="com.ibm.etools.xmlent.ui.GEN_COMMENT_IN_XSD" value="true"/>
<CodegenProperty name="com.ibm.etools.xmlent.ui.GEN_ERROR_FEEDBACK_FILE_PATH" value="c:\Documents
and Settings\My Documents\ErrorFeedBack\SyntaxError.xml"/>
<CodegenProperty name="com.ibm.etools.xmlent.ui.INIT_EMPTY_ITEMS_IN_INTERFACE" value="true"/>
<CodegenProperty name="com.ibm.etools.xmlent.ui.INIT_OMITTED ITEMS_IN_INTERFACE" value="true"/>
<CodegenProperty name="com.ibm.etools.xmlent.ui.GEN_USE_HOST_CP_INT_XML" value="true"/>
</CodegenPropertyArray>

Figure 57. Example of CodegenProperty Elements

Supported code pages (CCSIDs)

CCSID: Description:
37 USA, Canada, etc. EBCDIC
273 Austria, Germany EBCDIC
277 Denmark, Norway EBCDIC
278 Finland, Sweden EBCDIC
280 Italy EBCDIC
284 Spain, Latin America EBCDIC (Spanish)
285 UK EBCDIC
297 France EBCDIC
420 Arabic EBCDIC
424 Hebrew EBCDIC
500 International EBCDIC
813 ISO 8859-7 Greek / Latin ASCII
819 ISO 8859-1 Latin 1 / Open Systems ASCII
838 Thai Host Extended SBCS EBCDIC
870 Latin 2 - Multilingual EBCDIC
871 Iceland EBCDIC
920 ISO 8859-9 Latin 5 ASCII
930 Japanese (Katakana-based) EBCDIC
933 Korean EBCDIC
935 Simplified Chinese EBCDIC
937 Traditional Chinese EBCDIC

Developing web services and SOA with Enterprise Service Tools 429
 CCSID: Description:
939 Japanese (Latin-based) EBCDIC
1025 Cyrillic Multilingual EBCDIC
1026 Turkey Latin 5 EBCDIC
1047 Latin 1 / Open Systems EBCDIC
1112 Baltic, Multilingual EBCDIC
1122 Estonia EBCDIC
1123 Cyrillic Ukraine EBCDIC
1140 USA, Canada, etc. EBCDIC with Euro
1141 Austria, Germany EBCDIC with Euro
1142 Denmark, Norway EBCDIC with Euro
1143 Finland, Sweden EBCDIC with Euro
1144 Italy with EBCDIC Euro
1145 Spain, Latin America EBCDIC (Spanish) with Euro
1146 UK EBCDIC with Euro
1147 France EBCDIC with Euro
1148 International EBCDIC with Euro
1149 Iceland EBCDIC with Euro
1154 Cyrillic Multilingual EBCDIC with EuroCyrillic Multilingual EBCDIC with Euro
1155 Turkey Latin 5 EBCDIC with Euro
1156 Baltic, Multilingual EBCDIC with Euro
1157 Estonia EBCDIC with Euro
1158 Cyrillic Ukraine EBCDIC with Euro
1160 Thai Host EBCDIC with Euro
1200 Unicode, UTF-16
1208 Unicode, UTF-8
1364 Korean EBCDIC with Euro
5026 Japanese (Katakana-based) EBCDIC a subset of 930
5035 Japanese (Latin-based) EBCDIC a subset of 939

Related references

“CodegenProperty” on page 422

Supported code page combinations

This topic describes the supported code page combinations that are available when you select Compiled
XML Conversion in the Enterprise Service Tools Wizard Launchpad. If the runtime environment that you

430 Developer for z/OS: Developing with Db2, CICS, and IMS
are using or the XML conversion program cannot parse a locale-specific code page that you select, you
can specify a Unicode code page instead.

Unicode

The request and response code pages are used with communications between the runtime XML
conversion programs and the runtime environment (Web services for CICS, IMS Enterprise Suite SOAP
Gateway, or Batch, TSO, z/OS UNIX System Services) not between the runtime XML conversion programs
and the client.
If the runtime environment that you are using or the XML conversion program cannot parse a locale-
specific code page that you select, you can specify a Unicode code page instead. In the single-service
wizards, whenever there is a list box of code pages to select from, the list box includes the Unicode
variants (UTF-16 or UTF-8).
In general, the performance of the XML converters is slower when the request and response code pages
are Unicode.
The following table shows the Unicode variant that is available for each type of single-service project:

Type of single-service project: Code page variant available:

Web Services for CICS UTF-16
IMS Enterprise Suite SOAP Gateway UTF-8
XML Transformation for CICS project UTF-16
Batch, TSO, and z/OS UNIX System Services UTF-16 or UTF-8, user written runtime
environment

Single-byte character set (SBCS) combinations

Request: Host: Response:
37, Unicode 37 37, Unicode
273, Unicode 273 273, Unicode
277, Unicode 277 277, Unicode
280, Unicode 280 280, Unicode
284, Unicode 284 284, Unicode
285, Unicode 285 285, Unicode
297, Unicode 297 297, Unicode
Unicode 420 Unicode
Unicode 424 Unicode
500, Unicode 500 500, Unicode
Unicode 838 Unicode
Unicode 870 Unicode
Unicode 871 Unicode
Unicode 1025 Unicode
Unicode 1026 Unicode

Developing web services and SOA with Enterprise Service Tools 431
 Request: Host: Response:
1047, Unicode 1047 1047, Unicode
Unicode 1112 Unicode
Unicode 1122 Unicode
Unicode 1123 Unicode
1140, Unicode 1140 1140, Unicode
1141, Unicode 1141 1141, Unicode
1142, Unicode 1142 1142, Unicode
1143, Unicode 1143 1143, Unicode
1144, Unicode 1144 1144, Unicode
1145, Unicode 1145 1145, Unicode
1146, Unicode 1146 1146, Unicode
1147, Unicode 1147 1147, Unicode
1148, Unicode 1148 1148, Unicode
1149, Unicode 1149 1149, Unicode
Unicode 1153 Unicode
Unicode 1154 Unicode
Unicode 1155 Unicode
Unicode 1156 Unicode
Unicode 1157 Unicode
Unicode 1158 Unicode
Unicode 1160 Unicode

Double-byte character set (DBCS) combinations

Request: Host: Response:
Unicode 930 Unicode
Unicode 933 Unicode
Unicode 935 Unicode
Unicode 937 Unicode
Unicode 939 Unicode
Unicode 1364 Unicode
Unicode 1399 Unicode
Unicode 5026 Unicode
Unicode 5035 Unicode

Related references

432 Developer for z/OS: Developing with Db2, CICS, and IMS
 “CodegenProperty” on page 422

CodegenPropertyArray
Use this element to specify the programming language for the code to be generated and as the
container for the code generation properties for the converter. You can use this element in either
PlatformProperties.xml or ServiceSpecification.xml. If you use it in both documents, the specification
in ServiceSpecification.xml overrides the specification in PlatformProperties.xml.

Contained by

“EISService” on page 453 (in ServiceSpecification.xml)

“Platform” on page 439 (in PlatformProperties.xml)

Contains
“CodegenProperty” on page 422

Attributes
Fields Description
Specifies the implementation language for a new service in a top-
Attribute: type
down scenario.
Valid values: COBOL |
PLI-ENTERPRISE
Required?: No
Default value: COBOL

Example
Figure 58 on page 433 is an example of the CodegenPropertyArray element.

<CodegenPropertyArray type="Cobol">
<CodegenProperty name="com.ibm.etools.xmlent.ui.GEN_PROG_NAME" value="XCNV"/>
<CodegenProperty name="com.ibm.etools.xmlent.ui.GEN_AUTH_NAME" value="WSED"/>
<CodegenProperty name="com.ibm.etools.xmlent.ui.GEN_IN_CP_LIST" value="1140"/>
<CodegenProperty name="com.ibm.etools.xmlent.ui.GEN_CP_LIST" value="1140"/>
<CodegenProperty name="com.ibm.etools.xmlent.ui.GEN_OUT_CP_LIST" value="1140"/>
<CodegenProperty name="com.ibm.etools.xmlent.ui.GEN_DEC_COMMA" value=" false"/>
<CodegenProperty name="com.ibm.etools.xmlent.ui.GEN_FLAT_GEN" value=" false"/>
</CodegenPropertyArray>

Figure 58. Example of CodegenPropertyArray Element

ConnectionProperty
Use this element in the PlatformProperties.xml document to specify the properties for a server
connection, or in the ServiceSpecification.xml document to override the server connection properties
that you set in PlatformProperties.xml. This element is required in the PlatformProperties.xml document.

Contained by
“ConnectionPropertyArray” on page 434

Contains
None

Developing web services and SOA with Enterprise Service Tools 433
 Attributes
Fields Description
Specifies connection protocol and location of the Web service.
Attribute: name
Valid values: See Description
Required?: Yes
Default value: See Description

Examples
Figure 59 on page 434 are Figure 60 on page 434 examples of the ConnectionProperty element.

<ConnectionProperty name="connectionURI"
value="http://sample.connection.uri.com:8888/CICS/XMLS/DFHWSDSH/ACTDSOAP"/>

Figure 59. Example 1 of ConnectionProperty Element

<ConnectionProperty name="connectionURI"
value="http://localhost:8080/imssoap/services/IMSPHBKPort"/ >

Figure 60. Example 2of ConnectionProperty Element

ConnectionPropertyArray
Use this element as the container for connection properties in either PlatformProperties.xml or
ServiceSpecification.xml. If you use it in both documents, the specification in ServiceSpecification.xml
overrides the specification in PlatformProperties.xml. This element is optional in both files.

Contained by

“EISService” on page 453 (in ServiceSpecification.xml)

“Platform” on page 439 (in PlatformProperties.xml)

Contains
“ConnectionProperty” on page 433

Attributes
None

Example
Figure 61 on page 434 is an example of the ConnectionPropertyArray element.

<ConnectionPropertyArray>
<ConnectionProperty name="connectionURI"
value="http://winmvsn0.cpit.hursley.ibm.com:8888/CICS/XMLS/DFHWSDSH/ACTDSOAP"/>
</ConnectionPropertyArray>

Figure 61. Example of ConnectionPropertyArray Element

434 Developer for z/OS: Developing with Db2, CICS, and IMS
 ImportProperty
Use this element to provide information about the compiler options as appropriate for the
programming language that you specify in the ImportPropertyArray element. You can use this
element in the ServiceSpecification.xml document to override the compiler options that you set in
PlatformProperties.xml. If you want to generate language converters, you are required to specify this
element in the PlatformProperties.xml document.

Contained by
“ImportPropertyArray” on page 438

Contains
None

COBOL Attributes
Start the value of the name attribute with com.ibm.etools.cobol.
Note: When generating language converters, the defaults do not apply; ALL properties must be specified.
The valid pairs of names and values for COBOL are shown in Table 113 on page 435.

Table 113. COBOL Attribute Specifications for ImportProperty

Fields Description
Specifies the code page for a locale. From Locale and code pages
Attribute: COBOL_ASCII_CODEPAGE
table, the rightmost code-page entry in ASCII code pages column is
Valid values: 0 | 1 | 2
the default for a given locale name.
Required?: -
Default value: 0 For example: for locale en_US, the Locale and code pages table
specifies:

Locale name: en_US

Language: English
Country or area: United States
ASCII code pages: IBM-437,IBM-850,IBM-1252
Language group: Latin 1

For the en_US locale, the values for COBOL_ASCII_CODEPAGE

correspond to the ASCII code pages as follows:

2 - IBM-437
1 - IBM-850
0 - IBM-1252

Specifies the index number for the locale. From the Locale and code
Attribute:
pages table, you can determine the index number by counting the row
COBOL_COMPILE_TIME_LOCALE
number of the locale name you are interested in. For example:
Valid values: 1 through 50
Required?: - 1 - ar_AA
Default value: 14 14 - en_US
50 - zh_TW

See Locale and code pages for additional information.

Developing web services and SOA with Enterprise Service Tools 435
Table 113. COBOL Attribute Specifications for ImportProperty (continued)
Fields Description
Specifies the language used to display the syntax errors. The values
Attribute:
correspond to the languages as follows:
COBOL_ERROR_MSGS_LANG
Valid values: 0 through 13 0 - en_US
Required?: - 1 - ja_JP
Default value: 0 2 - zh_TW
3 - zh_CN
4 - ko_KR
5 - it_IT
6 - fr_FR
7 - es_ES
8 - de_DE
9 - pt_BR
10 - CS_CZ
11 - HU_HU
12 - PL_PL
13 - RU_RU

The default is en_US. To change this value, use the preferences page.

Specifies the default extension behavior. A file is assumed to be a

Attribute: COBOL_EXTENSION_CBL
complete COBOL program if it has the extension of .cbl, .ccp or .cob.
Valid values: FP | DS
A file is assumed to be a copy book if it has the extension .cpy. If the
Required?: -
file is a copybook member then it should consist of only one or more
Default value: FP
01 language structures or 01 or 77 elementary data item definition.
The user can change the default extension behavior by setting it to
"FP" (Full program) or "DS" (Only language structures).

Specifies the default extension behavior. A file is assumed to be a

Attribute: COBOL_EXTENSION_CCP
complete COBOL program if it has the extension of .cbl, .ccp or .cob.
Valid values: FP | DS
A file is assumed to be a copy book if it has the extension .cpy. If the
Required?: -
file is a copybook member then it should consist of only one or more
Default value: FP
01 language structures or 01 or 77 elementary data item definition.
The user can change the default extension behavior by setting it to
"FP" (Full program) or "DS" (Only language structures).

Specifies the default extension behavior. A file is assumed to be a

Attribute: COBOL_EXTENSION_COB
complete COBOL program if it has the extension of .cbl, .ccp or .cob.
Valid values: FP | DS
Required?: - A file is assumed to be a copy book if it has the extension .cpy. If the
file is a copybook member then it should consist of only one or more
Default value: FP
01 language structures or 01 or 77 elementary data item definition.
The user can change the default extension behavior by setting it to
"FP" (Full program) or "DS" (Only language structures).

Specifies the default extension behavior. A file is assumed to be a

Attribute: COBOL_EXTENSION_CPY
complete COBOL program if it has the extension of .cbl, .ccp or .cob.
Valid values: FP | DS
A file is assumed to be a copy book if it has the extension .cpy. If the
Required?: -
file is a copybook member then it should consist of only one or more
Default value: FP
01 language structures or 01 or 77 elementary data item definition.
The user can change the default extension behavior by setting it to
"FP" (Full program) or "DS" (Only language structures).

Specifies the setting of the COBOL_NSYMBOL compile-time option.

Attribute: COBOL_NSYMBOL
Valid values: NATIONAL | DBCS
Required?: -
Default value: NATIONAL

436 Developer for z/OS: Developing with Db2, CICS, and IMS
Table 113. COBOL Attribute Specifications for ImportProperty (continued)
Fields Description
Specifies the setting of the COBOL_QUOTE compile-time option.
Attribute: COBOL_QUOTE
Valid values: DOUBLE | SINGLE
Required?: -
Default value: DOUBLE

Use this option to list copy books on which a COBOL source file that
Attribute: COBOL_SYSLIB
you are importing has dependencies (see Example).
Valid values: One or more directories
in which copy books are located. The default value is: Directory location of the COBOL source file.
Required?: -
Default value: See Description

Specifies the setting of the COBOL_TRUNC compile-time option.

Attribute: COBOL_TRUNC
Valid values: STD | OPT | BIN
Required?: -
Default value: STD

COBOL Example

<ImportPropertyArray type="Cobol">
<ImportProperty name="com.ibm.etools.cobol.COBOL_TRUNC" value="STD"/>
<ImportProperty name="com.ibm.etools.cobol.COBOL_NSYMBOL" value="DBCS"/>
<ImportProperty name="com.ibm.etools.cobol.COBOL_QUOTE" value="DOUBLE"/>
<ImportProperty name="com.ibm.etools.cobol.COBOL_SYSLIB"
value="C:\cobol\copy books;C:\mycopybooks"/>
</ImportPropertyArray>

PL/I Attributes
Start the value of the name attribute with com.ibm.ccl/pli.
Note: When generating language converters, the defaults do not apply; ALL properties must be specified.
The valid pairs of names and values for PL/I are shown in Table 114 on page 437.

Table 114. PL/I Attribute Specifications for ImportProperty

Fields Description
Specifies the special character to be used as the NOT operator when
Attribute: PLI_NOT
generating and importing sources using the Batch Processor.
Valid values: See Description
Required?: - With Enterprise PL/I, up to 7 alternate characters can be specified
Default value: that the compiler will recognize as the NOT operator, however, when
generating PL/I sources, only the first character in the sequence will
be used.

<ImportProperty name="com.ibm.ccl.pli.PLI_NOT" value="^~¬"/>

Developing web services and SOA with Enterprise Service Tools 437
Table 114. PL/I Attribute Specifications for ImportProperty (continued)
Fields Description
Specifies the special character to be used as the OR operator when
Attribute: PLI_OR
generating and importing sources using the Batch Processor.
Valid values: See Description
Required?: - With Enterprise PL/I, up to 7 alternate characters can be specified
Default value: that the compiler will recognize as the OR operator, however, when
generating PL/I sources, only the first character in the sequence will
be used.

<ImportProperty name="com.ibm.ccl.pli.PLI_OR" value="\|"/>

PL/I Example

<ImportPropertyArray type="Pli">
<ImportProperty name="com.ibm.ccl.pli.PLI_NOT" value="?"/>
<ImportProperty name="com.ibm.ccl.pli.PLI_OR" value="^"/>
</ImportPropertyArray>

Related information
Opening the Preferences window

ImportPropertyArray
Use this element to specify the programming language for the file to be imported and as the container
for import properties. You can use this element in the ServiceSpecification.xml document to override
the programming language that you set in PlatformProperties.xml. If you want to generate language
converters, you are required to specify this element in the PlatformProperties.xml document.

Contained by

“EISProject” on page 452 (in ServiceSpecification.xml)

“Platform” on page 439 (in PlatformProperties.xml)

Contains
ImportProperty

Attributes
Fields Description
Specifies the programming language.
Attribute: type
Valid values: COBOL | Pli
Required?: Yes
Default value: COBOL

Example

<ImportPropertyArray type="Cobol">
<ImportProperty name="com.ibm.etools.cobol.COBOL_TRUNC" value="STD"/>
<ImportProperty name="com.ibm.etools.cobol.COBOL_NSYMBOL" value="DBCS"/>
<ImportProperty name="com.ibm.etools.cobol.COBOL_QUOTE" value="DOUBLE"/>
</ImportPropertyArray>

438 Developer for z/OS: Developing with Db2, CICS, and IMS
 Platform
Use this element to specify the platform for which the Web service will be generated and as a container
for properties that affect global service generation options.

Contained by
“PlatformArray” on page 439

Contains
“ImportPropertyArray” on page 438
“ConnectionPropertyArray” on page 434
“CodegenPropertyArray” on page 433

Attributes
Fields Description
Specifies the target generation platform.
Attribute: name
Valid values: OS390 Note: OS390 is the currently supported value. Other values are
Required?: Yes reserved for future use.
Default value: OS390

Example
Figure 62 on page 439 is an example of the Platform element within the PlatformArray element.

<PlatformArray>
<Platform name="OS390">
<ImportPropertyArray type="Cobol">
<ImportProperty name="com.ibm.etools.cobol.COBOL_TRUNC" value="STD"/>
<ImportProperty name="com.ibm.etools.cobol.COBOL_NSYMBOL" value="DBCS"/>
<ImportProperty name="com.ibm.etools.cobol.COBOL_QUOTE" value="DOUBLE"/>
</ImportPropertyArray>
<ConnectionPropertyArray>
<ConnectionProperty name="connectionURI"
value="http://winmvsn0.cpit.hursley.ibm.com:8888/CICS/XMLS/DFHWSDSH/ACTDSOAP"/>
</ConnectionPropertyArray>
<CodegenPropertyArray type="Cobol">
<CodegenProperty name="com.ibm.etools.xmlent.ui.GEN_PROG_NAME" value="XCNV"/>
<CodegenProperty name="com.ibm.etools.xmlent.ui.GEN_AUTH_NAME" value="WSED"/>
<CodegenProperty name="com.ibm.etools.xmlent.ui.GEN_IN_CP_LIST" value="1140"/>
<CodegenProperty name="com.ibm.etools.xmlent.ui.GEN_CP_LIST" value="1140"/>
<CodegenProperty name="com.ibm.etools.xmlent.ui.GEN_OUT_CP_LIST" value="1140"/>
<CodegenProperty name="com.ibm.etools.xmlent.ui.GEN_DEC_COMMA" value=" false"/>
<CodegenProperty name="com.ibm.etools.xmlent.ui.GEN_FLAT_GEN" value=" false"/>
</CodegenPropertyArray>
</Platform>
</PlatformArray>

Figure 62. Example of Platform Element

PlatformArray
This top-level element of the PlatformProperties.xml document provides information about the target
runtime environment.

Contained by
None

Contains
“Platform” on page 439

Developing web services and SOA with Enterprise Service Tools 439
 Attributes
None

Example
Figure 63 on page 440 is an example of the PlatformArray element.

<PlatformArray>
<Platform name="OS390">
<ImportPropertyArray type="Cobol">
<ImportProperty name="com.ibm.etools.cobol.COBOL_TRUNC" value="STD"/>
<ImportProperty name="com.ibm.etools.cobol.COBOL_NSYMBOL" value="DBCS"/>
<ImportProperty name="com.ibm.etools.cobol.COBOL_QUOTE" value="DOUBLE"/>
</ImportPropertyArray>
<ConnectionPropertyArray>
<ConnectionProperty name="connectionURI"
value=
"http://winmvsn0.cpit.hursley.ibm.com:8888/CICS/XMLS/DFHWSDSH/ACTDSOAP"/>
</ConnectionPropertyArray>
<CodegenPropertyArray type="Cobol">
<CodegenProperty name="com.ibm.etools.xmlent.ui.GEN_PROG_NAME" value="XCNV"/>
<CodegenProperty name="com.ibm.etools.xmlent.ui.GEN_AUTH_NAME" value="WSED"/>
<CodegenProperty name="com.ibm.etools.xmlent.ui.GEN_IN_CP_LIST" value="1140"/>
<CodegenProperty name="com.ibm.etools.xmlent.ui.GEN_CP_LIST" value="1140"/>
<CodegenProperty name="com.ibm.etools.xmlent.ui.GEN_OUT_CP_LIST" value="1140"/>
<CodegenProperty name="com.ibm.etools.xmlent.ui.GEN_DEC_COMMA" value=" false"/>
<CodegenProperty name="com.ibm.etools.xmlent.ui.GEN_FLAT_GEN" value=" false"/>
</CodegenPropertyArray>
</Platform>
</PlatformArray>

Figure 63. Example of PlatformArray Element

PlatformProperties.xml sample
This topic is a sample of the PlatformProperties.xml.

Figure 64 on page 440 is an example of the PlatformProperties.xml.

<?xml version="1.0" encoding="UTF-8"?>

<PlatformArray xmlns="http:///com/ibm/etools/xmlent/batch/emf/BatchProcessModel.ecore">
<Platform name="OS390">
<ImportPropertyArray type="Cobol">
<ImportProperty name="com.ibm.etools.cobol.COBOL_TRUNC" value="STD"/>
<ImportProperty name="com.ibm.etools.cobol.COBOL_NSYMBOL" value="DBCS"/>
<ImportProperty name="com.ibm.etools.cobol.COBOL_QUOTE" value="DOUBLE"/>
</ImportPropertyArray>
<ConnectionPropertyArray>
<ConnectionProperty name="connectionURI"
value="http://sample.connection.uri.com:8888/CICS/XMLS/DFHWSDSH/ACTDSOAP"/>
</ConnectionPropertyArray>
<CodegenPropertyArray type="Cobol">
<CodegenProperty name="com.ibm.etools.xmlent.ui.GEN_PROG_NAME" value="XCNV"/>
<CodegenProperty name="com.ibm.etools.xmlent.ui.GEN_AUTH_NAME" value="WSED"/>
<CodegenProperty name="com.ibm.etools.xmlent.ui.GEN_IN_CP_LIST" value="1140"/>
<CodegenProperty name="com.ibm.etools.xmlent.ui.GEN_CP_LIST" value="1140"/>
<CodegenProperty name="com.ibm.etools.xmlent.ui.GEN_OUT_CP_LIST" value="1140"/>
<CodegenProperty name="com.ibm.etools.xmlent.ui.GEN_DEC_COMMA" value=" false"/>
<CodegenProperty name="com.ibm.etools.xmlent.ui.GEN_FLAT_GEN" value=" false"/>
</CodegenPropertyArray>
</Platform>
</PlatformArray>

Figure 64. Example of PlatformProperties.xml

Related references

440 Developer for z/OS: Developing with Db2, CICS, and IMS
PlatformProperties.xml

Schema for PlatformProperties.xml

Figure 65 on page 442 is the schema for PlatformProperties.xml.

Developing web services and SOA with Enterprise Service Tools 441
 <?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
targetNamespace="http:///com/ibm/etools/xmlent/batch/emf/BatchProcessModel.ecore"
xmlns="http:///com/ibm/etools/xmlent/batch/emf/BatchProcessModel.ecore">
<xsd:element name="CodegenProperty">
<xsd:complexType>
<xsd:attribute name="name" type="xsd:string" use="required" />
<xsd:attribute name="value" type="xsd:string" use="required" />
</xsd:complexType>
</xsd:element>
<xsd:element name="CodegenPropertyArray">
<xsd:complexType>
<xsd:sequence>
<xsd:element maxOccurs="unbounded" minOccurs="1"
ref="CodegenProperty" />
</xsd:sequence>
<xsd:attribute name="type" type="xsd:string" use="optional" />
</xsd:complexType>
</xsd:element>
<xsd:element name="ConnectionProperty">
<xsd:complexType>
<xsd:attribute name="name" type="xsd:string" use="required" />
<xsd:attribute name="value" type="xsd:string" />
</xsd:complexType>
</xsd:element>
<xsd:element name="ConnectionPropertyArray">
<xsd:complexType>
<xsd:sequence>
<xsd:element maxOccurs="unbounded" minOccurs="1"
ref="ConnectionProperty" />
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="ImportProperty">
<xsd:complexType>
<xsd:attribute name="name" type="xsd:string" use="required" />
<xsd:attribute name="value" type="xsd:string" use="required" />
</xsd:complexType>
</xsd:element>
<xsd:element name="ImportPropertyArray">
<xsd:complexType>
<xsd:sequence>
<xsd:element maxOccurs="unbounded" minOccurs="1"
ref="ImportProperty" />
</xsd:sequence>
<xsd:attribute name="type" type="xsd:string" />
</xsd:complexType>
</xsd:element>
<xsd:element name="Platform">
<xsd:complexType>
<xsd:all>
<xsd:element maxOccurs="1" minOccurs="1"
ref="ImportPropertyArray" />
<xsd:element maxOccurs="1" minOccurs="0"
ref="ConnectionPropertyArray" />
<xsd:element maxOccurs="1" minOccurs="0"
ref="CodegenPropertyArray" />
</xsd:all>
<xsd:attribute name="name" type="xsd:string" />
</xsd:complexType>
</xsd:element>
<xsd:element name="PlatformArray">
<xsd:complexType>
<xsd:sequence>
<xsd:element maxOccurs="unbounded" minOccurs="1" ref="Platform" />
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:schema>

Figure 65. Schema for PlatformProperties.xml

Related references

PlatformProperties.xml

442 Developer for z/OS: Developing with Db2, CICS, and IMS
ServiceSpecification.xml
ServiceSpecification.xml is one of the three generation properties files used by the batch processor.

Purpose

Using the ServiceSpecification.xml file, you can specify the options required to generate new Web service
interfaces or Web service implementations. In this file you can also override certain options that you
specify in the PlatformProperties.xml file.
ServiceSpecification.xml allows you to create:
• A Web service interface for existing CICS and IMS applications. The generated artifacts include a Web
service description and message converters. For IMS, the generated artifacts also include the correlator
file.
• A new CICS or IMS service provider application from a Web Service description. The generated artifacts
include language structures, message converters and an application template. For IMS, the generated
artifacts also include the correlator file.
• A new CICS service requester implementation from a Web Service description. The generated artifacts
include language structures, message converters and an application template.

Elements
You can use the following elements in the ServiceSpecification.xml document:
• “ApplicationTemplateSpec” on page 444
• “CodegenProperty” on page 422
• “CodegenPropertyArray” on page 433
• “ConnectionProperty” on page 433
• “ConnectionPropertyArray” on page 434
• “ConverterSpecIn” on page 445
• “ConverterSpecOut” on page 446
• “CorrelatorSpec” on page 447
•
•
• “DriverSpec” on page 449
• “EISProject” on page 452
• “EISService” on page 453
• “EISServiceImplementation” on page 455
• “ElementSelection” on page 456
• “ElementSelectionArray” on page 457
• “ImportProperty” on page 435
• “ImportPropertyArray” on page 438
• “InputMessage” on page 457
• “InputOutputMessage” on page 459
• “ItemExclude” on page 460
• “ItemExclusionArray” on page 462
• “ItemSelection” on page 462
• “ItemSelectionArray” on page 464
• “LanguageStructureSpec” on page 464

Developing web services and SOA with Enterprise Service Tools 443
 • “LanguageStructureSpecIn” on page 465
• “LanguageStructureSpecOut” on page 466
• “MessageSpec” on page 467
• “Operation” on page 469
• “OperationProperty” on page 471
• “OperationPropertyArray” on page 472
• “OperationSelection” on page 472
• “OperationSelectionArray” on page 473
• “OutputMessage” on page 473
• “RedefinesArray” on page 475
• “RedefineSelection” on page 476
• “ServiceImplementationSpec” on page 478
• “ServiceProperty” on page 480
• “ServicePropertyArray” on page 481
• “TypeSelection” on page 482
• “TypeSelectionArray” on page 482
• “WSBindSpec” on page 483
• “XSDBindSpec” on page 496
• “XMLNamesArray” on page 503
• “XMLNameSelection” on page 504
• “XsdSpec” on page 506
• “XsdSpecIn” on page 508
• “XsdSpecOut” on page 509
• “XseSpec” on page 511

Sample
The “ServiceSpecification.xml sample (EISService Element)” on page 512 illustrates the use of applicable
elements and their attributes.

Schema
The “Schema for ServiceSpecification.xml” on page 513 provides the structure for the contents of the
ServiceSpecification.xml document.

ApplicationTemplateSpec
Use this element of the ServiceSpecification.xml document to specify properties of the new application
template generated to assist in implementing a new service provider or service requester based on the
web service description (WSDL).

Contained by
“ServiceImplementationSpec” on page 478

Contains
None

Attributes
Table 115 on page 445 shows the attributes for ApplicationTemplateSpec.

444 Developer for z/OS: Developing with Db2, CICS, and IMS
Table 115. Attribute Specifications for ApplicationTemplateSpec
Fields Description
The filename of the generated application template.
Attribute: fileName
Valid values: See Description The default value is: First 8 characters of the input WSDL file name
Required?: No
Default value: See Description

Specifies whether to overwrite the output file(s) if it exists.

Attribute: overwrite
Valid values: true | false
Required?: No
Default value: true

The name of the main entry point in the generated application

Attribute: programName
template.
Valid values: See Description
Required?: No The default value is: First 8 characters of the input WSDL file name
Default value: See Description

Example
Figure 66 on page 445 is an example of ApplicationTemplateSpec element.

<EISProject xmlns="http:///com/ibm/etools/xmlent/batch/emf/BatchProcessModel.ecore"
name="CICSTopDownSample">

<!-- Generate an implementation of a web service from a WSDL file -->

<EISServiceImplementation runtime="WEB_SERVICES_CICS" type="SERVICE_PROVIDER">
<ServiceImplementationSpec importDirectory="." importFile="ServiceDefinition.wsdl">
<ApplicationTemplateSpec fileName="SERVPROV.cbl" programName="SERVPROV"/>
...
</ServiceImplementationSpec>
</EISServiceImplementation>

</EISProject>

Figure 66. Example of ApplicationTemplateSpec Element

ConverterSpecIn
Use this element of the ServiceSpecification.xml document to specify the generation options for the
request converter.

Contained by
“XseSpec” on page 511

Contains
None

Attributes
Table 116 on page 446 shows the attributes for ConverterSpecIn.

Developing web services and SOA with Enterprise Service Tools 445
Table 116. Attribute Specifications for ConverterSpecIn
Fields Description
Specifies the name of the output file.
Attribute: fileName
Valid values: See Description The default value is: Data source file name concatenated with "I"
Required?: No
Default value: See Description

Specifies whether to overwrite the output file if it exists.

Attribute: overwrite
Valid values: true | false
Required?: No
Default value: true

Specifies the program name of the main program entry.

Attribute: programName
Valid values: See Description The default value is: Value of the CodegenProperty
Required?: No GEN_PROG_NAME concatenated with "I"
Default value: See Description

Indicates whether or not to suppress generation of the compiled

Attribute: suppressGeneration
request XML converter.
Valid values: true | false
Required?: No
Default value: false

Example

<ConverterSpecIn fileName="DFH0CSTDI.cbl" overwrite="true" programName="XCNVI"/>

ConverterSpecOut
Use this element of the ServiceSpecification.xml document to specify the generation options for
theresponse converter.

Contained by
“XseSpec” on page 511

Contains
None

Attributes
Table 117 on page 446 shows the attributes for ConverterSpecOut.

Table 117. Attribute Specifications for ConverterSpecOut

Fields Description
Specifies the name of the output file.
Attribute: fileName
Valid values: See Description The default value is: Data source file name concatenated with "O"
Required?: No
Default value: See Description

446 Developer for z/OS: Developing with Db2, CICS, and IMS
Table 117. Attribute Specifications for ConverterSpecOut (continued)
Fields Description
Specifies whether to overwrite the output file if it exists.
Attribute: overwrite
Valid values: true | false
Required?: No
Default value: true

Specifies the program name of the main program entry.

Attribute: programName
Valid values: See Description The default value is: Value of the CodegenProperty
Required?: No GEN_PROG_NAME concatenated with "O"
Default value: See Description

Indicates whether or not to suppress generation of the response

Attribute: suppressGenration
compiled XML converter.
Valid values: true | false
Required?: No
Default value: false

Example

<ConverterSpecOut fileName="DFH0CSTDO.cbl"
overwrite="true" programName="XCNVO"/>

CorrelatorSpec
Use this element of the ServiceSpecification.xml document to specify the generation options for the IMS
Correlator file. The correlation information is used by the IMS Enterprise Suite SOAP Gateway.

Contained by

“XseSpec” on page 511

“ServiceImplementationSpec” on page 478

Contains
None

Attributes
Table 118 on page 447 shows the attributes for CorrelatorSpec.

Table 118. Attribute Specifications for CorrelatorSpec

Fields Description
The IMS Connect adapter which controls conversion of XML
Attribute: adapterType
messages and execution of XML enabled programs.
Valid values: See Description
Required?: No The default value is: IBM XML Adapter
Default value: See Description

The name of the connection bundle for IMS Enterprise Suite SOAP
Attribute: calloutConnBundleName
Gateway Outbound.
Valid values: See Description
Required?: No
Default value: None

Developing web services and SOA with Enterprise Service Tools 447
Table 118. Attribute Specifications for CorrelatorSpec (continued)
Fields Description
A space-separated list of callout connection bundle names. Callout
Attribute: calloutConnBundleNames
connection bundles contain the connection and security properties
Valid values: See Description
that are used by SOAP Gateway to connect with IMS in the service
Required?: No
requester scenario. Each callout connection bundle name should be
Default value: blank
no longer than 20 characters.
The name of the connection bundle for IMS Enterprise Suite SOAP
Attribute: connectionBundleName
Gateway Inbound.
Valid values: See Description
Required?: No
Default value: None

Send-only with acknowledgement protocol: If this attribute is set

Attribute: calloutSendOnlyWithACK
to true, SOAP Gateway sends the callout response message to
Valid values: true | false
IMS using the send-only with acknowledgement protocol. The final
Required?: No
ACK or NACK message from IMS is not forwarded to the external
Default value: false
client application. The ACK or NACK responses are logged by SOAP
Gateway if the server log level is set to 2 (for NACK responses) or 4
(for ACK and NACK responses).
The security token type to use for WS-Security for the service
Attribute: calloutWSSecurity
requester scenario.
Valid values:
blank
SAML11Token
SAML20Token
Required?: No
Default value: blank

The number of milliseconds for which the IMS Enterprise Suite SOAP
Attribute: calloutWSTimeout
Gateway should wait for a response from the target Web service.
Valid values: See Description
Valid range: Positive integer (in milliseconds).
Required?: No
Default value: 5000

Specifies the time that the IMS Connect waits for a response from
Attribute: executionTimeout
IMS. Valid range: 0-3600000 (in milliseconds).
Valid values: See Description
Required?: No
Default value: 5000

Specifies the name of the output file.

Attribute: fileName
Valid values: See Description The default value is: Data source file name concatenated with "xml"
Required?: No
Default value: See Description

The Tpipe name used with CM0 transactions in IMS.

Attribute: inboundTPIPEName
Valid values: See Description
Required?: No
Default value: None

The LTERM name used to override the value in the LTERM field of the
Attribute: ltermName
IMS application program's I/O PCB.
Valid values: See Description
Required?: No
Default value: None

448 Developer for z/OS: Developing with Db2, CICS, and IMS
Table 118. Attribute Specifications for CorrelatorSpec (continued)
Fields Description
Specifies whether to overwrite the output file if it exists.
Attribute: overwrite
Valid values: true | false
Required?: No
Default value: true

Specifies the time that the IMS Enterprise Suite SOAP Gateway
Attribute: socketTimeout
runtime waits for a response from IMS Connect. Valid range: Positive
Valid values: See Description
integer (in milliseconds).
Required?: No
Default value: 0

Indicates whether or not to suppress generation of the correlator file.

Attribute: suppressGeneration
Valid values: true | false
Required?: No
Default value: false

Attribute: trancode Service Provider: IMS transaction which is providing the Web service.
Valid values: See Description Service Requester: IMS transaction which handles the response from
Required?: No the target Web service.
Default value: None

Attribute: WSSecurity The security token type to use for web services security for the
Valid values: provider scenario.
blank
SAML11Token
SAML20Token
SAML11SignedTokenTrustAny
SAML11SignedTokenTrustOne
SAML20SignedTokenTrustAny
SAML20SignedTokenTrustOne
UserNameToken
Required?: No
Default value: blank

Example

<CorrelatorSpec fileName="IMSPHBK.xml" overwrite="true" trancode="IVTNO"

socketTimeout="0" executionTimeout="0" connectionBundleName="conn1" />

DriverSpec
Use this element of the ServiceSpecification.xml document to specify the generation options for the
converter driver program

Note: In the top-down scenario the DriverSpec specifies the file that contains the entire conversion
package (driver, converters, and utility programs).

Contained by
“XseSpec” on page 511

Developing web services and SOA with Enterprise Service Tools 449
 Contains
None

Attributes
This table shows the attributes for DriverSpec.

Table 119. Attribute Specifications for DriverSpec

Fields Description
Specifies the existing business program that the XML converters call.
Attribute: businessPgmName
This is the program that you are enabling for processing and/or
Valid values: See Description
producing XML messages (to act as a Web service, for example.)
Required?: No
Default value: See Description The default value is: Data source file name up to 7 characters.
Note:
1. If the name is longer than 7 characters only the first 7 characters
are used to form the default. The specified name must follow
COBOL conventions for the program name.
2. If the driver type is XML_TRANSFORM_CICS, the value of this
attribute is ignored.

Specifies the type of drivers and converters to generate for a specific

Attribute: driverType
subsystem (such as CICS, IMS, TSO);
Valid values: BATCH | IMS_SOAP |
IMS_INFO_20 | • BATCH - Basic converter and driver types running in batch, in TSO,
SOAP_FOR_CICS | or in z/OS UNIX System Services.
WEB_SERVICES_CICS | • IMS_SOAP - XML Converters, XML Schemas, WSDL, and Correlator
XML_TRANSFORM_CICS file for deployment into the IMS Enterprise Suite SOAP Gateway
Required?: No runtime environment.
Default value: SOAP_FOR_CICS
• SOAP_FOR_CICS - Converters and drivers to be deployed into a
SOAP for CICS runtime environment.
• WEB_SERVICES_CICS - Converters and drivers to be deployed into
a CICS Web services runtime environment.
• XML_TRANSFORM _CICS - Converters and drivers to be deployed
as a CICS XML TRANSFORM runtime resource for Vendor
transformation.

Specifies the name of the output file.

Attribute: fileName
Valid values: See Description The default value is: Data source file name concatenated with "D"
Required?: No
Default value: See Description

450 Developer for z/OS: Developing with Db2, CICS, and IMS
Table 119. Attribute Specifications for DriverSpec (continued)
Fields Description
Specifies the prefix used to form the names of the generated
Attribute: fileNamePrefix
conversion source packages. A conversion source package is a single
Valid values: See Description.
COBOL or PL/I source file that contains the generated conversion
Required?: No
programs for converting from XML data to language data and from
Default value: See Description.
language data to the XML data. For Web services scenarios these
packages may contain SOAP header and SOAP fault conversion code
and other utility programs (if supported by a specific scenario).
The default value is the name of the input WSDL file up to 6
characters, excluding the file extension.
Note:
• If the name of the input WSDL file is longer than 6 characters, then
the first 6 characters are used to form the default name.
• To avoid name collisions for multiple conversion source packages,
successive package names are formed by appending a hexadecimal
ordinal to the value of fileNamePrefix, up to 7 characters, to
distinguish it from previously generated packages.1. If the number
of possible distinct package names is exhausted then the batch
processor terminates with error CRRZX0130E.
• This attribute is supported only if the driver type is IMS_SOAP. For
all other driver types the value of this attribute is ignored.

Specifies whether to overwrite the output file if it exists.

Attribute: overwrite
Valid values: true | false
Required?: No
Default value: true

Specifies the program name of the main program entry.

Attribute: programName
Valid values: See Description The default value is: Value of the CodegenProperty
Required?: No GEN_PROG_NAME concatenated with "D".
Default value: See Description

Indicates whether or not to suppress generation of the compiled XML

Attribute: suppressGeneration
converter driver.
Valid values: true | false
Required?: No
Default value: false

For XML_TRANSFORM _CICS type converters, specifies the name of

Attribute: xmlContainerName
the CICS container that carries the XML document. Depending on
Valid values: See Description
the direction of the conversion it can contain ether the result of the
Required?: No
conversion or the XML document to be converted. The name must be
Default value: xmlCont
a valid CICS container name of 16 characters or less.
For XML_TRANSFORM _CICS type converters, specifies the name of
Attribute: dataContainerName
the CICS container that carries the language data. Depending on
Valid values: See Description
the direction of the conversion it can contain ether the result of the
Required?: No
conversion or the language data to be converted. The name must be a
Default value: xmlCont
valid CICS container name of 16 characters or less.
1 The attribute fileNamePrefix defaults to a portion of the WSDL file name only if the attribute is not specified
from DriverSpec. For example if @fileNamePrefix="HELLO" but the WSDL file name is MyService.wsdl, the
package names will be HELLOD.pli through HELLOFFD.pli.

Developing web services and SOA with Enterprise Service Tools 451
 Example
The following sample code illustrates a DriverSpec element.

<DriverSpec fileName="IMSPHBKD.cbl" driverType="WEB_SERVICES_CICS"

programName="XCNVD" businessPgmName="IMSPHBK" />

EISProject
Use this top-level element of the ServiceSpecification.xml document to provide information about the
Web service.

Contained by
None

Contains
“CodegenPropertyArray” on page 433
“EISService” on page 453
“ImportPropertyArray” on page 438
“EISServiceImplementation” on page 455

Attributes
Fields Description
Specifies the name of the project that contains the generated files. If
Attribute: name
the project does not exist, it will be created automatically.
Valid values: See Description
Required?: No
Default value: EISProject

Examples
Figure 67 on page 452 areFigure 68 on page 453 examples of the EISProject element.

<EISProject name="CICSSample">
<!-- Use the ImportPropertyArray to override values from PlatformProperties.xml -->
<ImportPropertyArray type="Cobol">
<ImportProperty name="com.ibm.etools.cobol.COBOL_TRUNC" value="BIN" />
<ImportProperty name="com.ibm.etools.cobol.COBOL_NSYMBOL" value="DBCS" />
<ImportProperty name="com.ibm.etools.cobol.COBOL_QUOTE" value="DOUBLE" />
</ImportPropertyArray>
<CodegenPropertyArray type="Cobol">
<CodegenProperty name="com.ibm.etools.xmlent.ui.GEN_PROG_NAME" value="XCNV"/>
<CodegenProperty name="com.ibm.etools.xmlent.ui.GEN_AUTH_NAME" value="WSED"/>
<CodegenProperty name="com.ibm.etools.xmlent.ui.GEN_IN_CP_LIST" value="1140"/>
<CodegenProperty name="com.ibm.etools.xmlent.ui.GEN_CP_LIST" value="1140"/>
<CodegenProperty name="com.ibm.etools.xmlent.ui.GEN_OUT_CP_LIST" value="1140"/>
<CodegenProperty name="com.ibm.etools.xmlent.ui.GEN_DEC_COMMA" value=" false"/>
<CodegenProperty name="com.ibm.etools.xmlent.ui.GEN_FLAT_GEN" value=" false"/>
</CodegenPropertyArray>
<EISService name="CustomerInfo" type="CICS" targetNameSpace="http://cics.sample"
generateConverters="true"
generateSeparateXSD="false"
generateWSDL="true"
portType="myPortType" >
</EISService>
</EISProject>

Figure 67. Example 1 of EISProject Element

452 Developer for z/OS: Developing with Db2, CICS, and IMS
 <EISProject xmlns="http:///com/ibm/etools/xmlent/batch/emf/BatchProcessModel.ecore"
name="CICSTopDownSample">

<!-- Use the CodegenPropertyArray to override values from PlatformProperties.xml -->

<CodegenPropertyArray>
<CodegenProperty name="com.ibm.etools.xmlent.ui.GEN_CONVERSION_TYPE" value="interpretive"/>
</CodegenPropertyArray>

<!-- Generate an implementation of a web service from a WSDL file -->

<EISServiceImplementation type="SERVICE_PROVIDER">
...
</EISServiceImplementation>

<!-- Generate a client to from a WSDL file -->

<EISServiceImplementation type="SERVICE_REQUESTOR">
...
</EISServiceImplementation>

</EISProject>

Figure 68. Example 2 of EISProject Element

EISService
Use this element of the ServiceSpecification.xml document to provide information about the Web service
and as a container for the required Operation containers and, optionally, for the ConnectionPropertyArray
and the ServicePropertyArray.
If this service contains multiple Operations and it is implemented by the CICS Web Services runtime
environment, you can specify an optional WSBindSpec element. In that element, you can specify
properties of the WSBind file representing multi-operation service. The WSBindSpec options provided on
multiple Operations takes precedence over any WSBindSpec options that might be specified on individual
Operations. That is, any WSBindSpec on individual Operations in multi-operation service is ignored.
Note: If you do not specify a WSBindSpec for the EISService with multiple operations, the default values
for multiple Operations are used (see“WSBindSpec” on page 483 description for more information on the
default WSBindSpec values for multiple Operations).
The following is a sample of specifying multiple operations:

<EISProject name="BankPrj">
<EISService name="Bank">
.....
<Operation name="DepositFundsOperation">
....
</Operation>
<Operation name="WithdrawFundsOperation">
....
</Operation>
</EISService>
</EISProject>

The following rules apply when generating multiple Operations:

• Operation names must not contain duplicates
• Driver types must match on all operations
• Target namespaces for types in message specifications must not contain duplicates across multiple
operations
• Output file specifications across multiple Operations must not have duplicate names.
• For unwrapped SOAP messages (which is what the single-service projects GUI tools generate), top-level
elements in the request messages have to be distinct for distinct operations.
Note: Not following these rules will cause the results of the generation process to be unpredictable.
When specifying multiple operations, keep in mind the following restrictions:

Developing web services and SOA with Enterprise Service Tools 453
 • Program interface for the business program implementing multiple operations in CICS must be via
CHANNEL (COMMAREA interfaces are not supported).
• Business program name must be specified in the WSBindSpec element of the EISService container.
Business program names of the DriverSpec elements in the individual operations are ignored.
• Relying on default program names and file names may lead to unpredictable results when the different
parameters come up identical values. For example service name with the name of "Bank" may lead to a
default business program name of BANKSER. If you also specify the router name as BANKSER, you may
have errors when building or using these programs.

Contained by
“EISProject” on page 452

Contains
“ConnectionPropertyArray” on page 434
“Operation” on page 469
“ServicePropertyArray” on page 481
“RouterSpec” on page 476
“WSBindSpec” on page 483

Attributes
Table 120 on page 454 shows the attributes for EISService.

Table 120. Attribute Specifications for EISService

Fields Description
Specifies the name of the Web service. The name of the Web Services
Attribute: name
Definition File (WSDL) that is generated uses this name.
Valid values: See Description
Required?: - The default value: The default is taken from the xsebatch command
Default value: See Description line parameter -w.

Specifies whether to generate the converter set (request and

Attribute: generateConverters
response converters, driver).
Valid values: true | false
Required?: -
Default value: false

Specifies whether to generate a separate set of XML schemas that

Attribute: generateSeparateXSD
define the message request and response).
Valid values: true | false
Required?: - Note: The "false" setting of this attribute is meaningful only if
Default value: false generateWSDL is set to true. A value of false specifies that the service
definition file contains an embedded schema.

Specifies whether to generate a service definition.

Attribute: generateWSDL
Valid values: true | false
Required?: -
Default value: false

Specifies the URI of the location where the output files will be
Attribute: targetFilesURI
generated, relative to the top level project.
Valid values: See Description
Required?: - The default value is: Value of targetNamespace, if specified.
Default value: See Description Otherwise it is set to file: //target.files

454 Developer for z/OS: Developing with Db2, CICS, and IMS
Table 120. Attribute Specifications for EISService (continued)
Fields Description
Specifies the URL of the target namespace.
Attribute: targetNamespace
Valid values: See Description
Required?: -
Default value: svcNS

Specifies the relevant subsystem.

Attribute: type
Valid values: CICS | IMS
Required?: -
Default value: CICS

Example
Figure 69 on page 455 is an example of the EISService element.

<EISProject name="CICSSample">
<EISService name="CustomerInfo" type="CICS" targetNamespace="http://cics.sample"
targetFilesURI="file://my.files"
generateConverters="true"
generateSeparateXSD="false"
generateWSDL="true" >

</EISService>
</EISProject>

Figure 69. Example of EISService Element

EISServiceImplementation
Use this element of the ServiceSpecification.xml document to implement a service provider or
service requester from a web service description (WSDL) file. Also use as a container for the
required ServiceImplementationSpec container and, optionally, for the ConnectionPropertyArray and the
ServicePropertyArray.

Contained by
“EISProject” on page 452

Contains
“ConnectionPropertyArray” on page 434
“ServicePropertyArray” on page 481
“ServiceImplementationSpec” on page 478

Attributes
Table 121 on page 456 shows the attributes for EISServiceImplementation.

Developing web services and SOA with Enterprise Service Tools 455
Table 121. Attribute Specifications for EISServiceImplementation
Fields Description
Specifies the subsystem (such as CICS, IMS, TSO) for which the
Attribute: runtime
artifacts are generated:
Valid values: WEB_SERVICES_CICS
| IMS_SOAP_GATEWAY | • WEB_SERVICES_CICS: The artifacts are deployable to a CICS TS
XML_TRANSFORM_CICS 3.1+ Web services runtime environment.
Required?: - • IMS_SOAP_GATEWAY: The artifacts are deployable into IMS
Default value: WEB_SERVICES_CICS Enterprise Suite SOAP Gateway and IMS Connect.
• XML_TRANSFORM_CICS: The artifacts are deployable to a CICS TS
CICS XML TRANSFORM runtime environment.

Specifies whether to generate artifacts to implement a Service

Attribute: type
Provider or Service Requester based on the input web service
Valid values: SERVICE_PROVIDER
description.
| SERVICE_REQUESTOR
Required?: - Notes:
Default value: SERVICE_PROVIDER
• SERVICE_REQUESTOR mode is referred to as “callout” in IMS-
related scenarios.
• SERVICE_REQUESTOR mode is not supported when the
development scenario is top-down, the target runtime is IMS
Enterprise Suite SOAP Gateway, the conversion type is compiled,
and the language is Enterprise PL/I (see “IMS Enterprise Suite
SOAP Gateway project” on page 181).

Example

<EISProject xmlns="http:///com/ibm/etools/xmlent/batch/emf/BatchProcessModel.ecore"
name="CICSTopDownSample">

<!-- Generate an implementation of a web service from a WSDL file -->

<EISServiceImplementation type="SERVICE_PROVIDER">
...
</EISServiceImplementation>

<!-- Generate a client to from a WSDL file -->

<EISServiceImplementation type="SERVICE_REQUESTOR">
...
</EISServiceImplementation>

</EISProject>

ElementSelection
Use this element, in a top-down scenario, to select an element from those defined in the XSD file or in the
types section of the WSDL file.

Contained by
“ElementSelectionArray” on page 457

Contains
None

456 Developer for z/OS: Developing with Db2, CICS, and IMS
 Attributes
Fields Description
Selects an element to implement from the XSD file or from the types
Attribute: name
section of the WSDL file in a top-down scenario. Specified element
Valid values: elementName
must exist in the XSD or the WSDL file. If the specified element is not
Required?: No
found, an error message is generated.
Default value: None

Example

<ElementSelectionArray>
<ElementSelection name="balance"/>
<ElementSelection name="interestRate"/>
</ElementSelectionArray>

ElementSelectionArray
Use this element, in the top-down scenario, as a container for the ELEMENT selection elements which are
enabled for conversion.

Note: If no ElementSelectionArray is specified in a top-down scenario, all global elements in the XSD file
or in the types section of the WDSL file are used for generating the conversion artifacts.

Contained by
“ServiceSpecification.xml” on page 443

Contains
“ElementSelection” on page 456

Attributes
None

Example

<ElementSelectionArray>
<ElementSelection name="balance"/>
<ElementSelection name="interestRate"/>
</ElementSelectionArray>

InputMessage
Use this element to define messages for ONE-WAY operations or REQUEST_RESPONSE
(SOLICIT_RESPONSE) operations if the input and output messages are of different types. Note that for
ONE_WAY operations, you are allowed to specify only the InputMessage. OutputMessage is not allowed
and will cause unpredictable results during the generation process. To compose a message from multiple
data types, specify additional InputMessage elements (this capability is supported only for the IMS
Enterprise Suite SOAP Gateway runtime). The order in which the InputMessage elements are specified in
the ServiceSpecification.xml determines their order in the composite message.

Contained by
“Operation” on page 469

Contains
“ItemSelectionArray” on page 464
“RedefinesArray” on page 475

Developing web services and SOA with Enterprise Service Tools 457
 “XMLNamesArray” on page 503
“ItemExclusionArray” on page 462

Attributes
Table 122 on page 458 shows the attributes for InputMessage.

Table 122. Attribute Specifications for InputMessage

Fields Description
This attribute has no effect on generated artifacts. It is reserved for
Attribute: name
future use.
Valid values: See Description
Required?: No
Default value: esvc

Specifies the absolute path to location and name in the file system of
Attribute: annotationsFile
the synonym action XML file. The synonym action XML file contains
Valid values: See Description
the optional annotation information that can be present in the
Required?: No
source of the service interface data declarations. If this attribute
Default value: See Description
is not specified, the default is taken from the “-annot” parameter
of the xsebatch invocation. For more information see “Using source
annotations to specify service interface” on page 297.
Specifies the absolute path to location and name in the file system of
Attribute: commTypesFile
the common types xml file. The common types xml file describes the
Valid values: See Description
common element and type information that is used in the generated
Required?: No
WSDL and XSD schema to refer to instead of imbedding and
Default value: See Description
potentially duplicating the types. If this attribute is not specified, the
default is taken from the “-commtypes” parameter of the xsebatch
invocation. For more information, see “Commonly Used Elements and
Types” on page 302.
Specifies the directory for the source file.
Attribute: importDirectory
Valid values: See Description The default value is: The input directory
Required?: No
Default value: See Description

Specifies the file name that contains the data definition to be used in
Attribute: importFile
creating the Web service operation message types.
Valid values: See Description
Required?: Yes (unless the -s Note: Only COBOL data definitions are supported and are subject to
command the restrictions that are specified in the online help.
line option is specified)
The default value is: The name provided in the xsebatch command
Default value: See Description
line parameter -s.

Corresponds to the minOccurs attribute value of the xsd:element

Attribute: lowerBound
that is assigned the complexType derived from the data type
Valid values: 1 to n
specified in the following attributes: importDirectory, importFile, and
Required?: No
nativeTypeName
Default value: 1
Note: This attribute is ignored unless two or more InputMessages are
specified.

458 Developer for z/OS: Developing with Db2, CICS, and IMS
Table 122. Attribute Specifications for InputMessage (continued)
Fields Description
Specifies the name of the data type that is to be imported from the
Attribute: nativeTypeName
importFile, such as DFHCOMMAREA for a CICS COBOL application. An
Valid values: See Description
error message is generated on the console if a parse of the importFile
Required?: No
does not identify the nativeTypeName as a valid data type.
Default value: See Description
The default value is: For COBOL, the name of the first available level
01 data item name.

Corresponds to the minOccurs attribute value of the xsd:element

Attribute: upperBound
that is assigned the complexType derived from the data type
Valid values: 1 to n, -1 (infinite)
specified in the following attributes: importDirectory, importFile, and
Required?: No
nativeTypeName
Default value: 1
Note: This attribute is ignored unless two or more InputMessages are
specified.

Specifies the desired tag name of the xsd:element that is assigned

Attribute: xmlEleName
the complexType derived from the data type specified in the following
Valid values: See Description
attributes: importDirectory, importFile, and nativeTypeName
Required?: No
Default value: See Description Note: This attribute is ignored unless two or more InputMessages are
specified.

Example
Figure 70 on page 459 is an example of InputMessage element.
Note: Another example of an Input message is in “Specification of Multiple Response Language
Structures” on page 311.

Figure 70. Example of InputMessage Element

<InputMessage name="PhoneBookRequest" importDirectory="." importFile="Ex01z.cbl"

commTypesFile=c:/common/commtypesSample.xml nativeTypeName="input-msg">
<RedefinesArray>
<RedefineSelection redefine="input-msg.redParent.redefd"
useRedefinition="input-msg.redParent.redefd2"/>
</RedefinesArray>
<ItemSelectionArray>
<ItemSelection itemName="input-msg.redParent"/>
<ItemSelection itemName="input-msg.in-extn"/>
<ItemSelection itemName="input-msg.in-zip"/>
<ItemSelection itemName="input-msg.in-ll"/>
</ItemSelectionArray>
</InputMessage>

InputOutputMessage
Use this element to define messages for REQUEST-RESPONSE operations if the input and output
messages are of the same type.

Note: In the InputOutputMessage both request and response message definitions come from a single
COBOL source. Because of this, the XsdSpecOut schema specification for the namespace will be ignored
for theresponse schema.

Contained by
“Operation” on page 469

Developing web services and SOA with Enterprise Service Tools 459
 Contains
“ItemSelectionArray” on page 464
“RedefinesArray” on page 475
“XMLNamesArray” on page 503
“ItemExclusionArray” on page 462

Attributes
Table 123 on page 460 shows the attributes for InputOutputMessage.

Table 123. Attribute Specifications for InputOutputMessage

Fields Description
Specifies the file name that contains the data definition to be used in
Attribute: importFile
creating the Web service operation message types.
Valid values: See Description
Required?: Yes (unless the -s Note: Only COBOL data definitions are supported and are subject to
command the restrictions that are specified in the online help.
line option is specified)
The default value is: The name provided in the xsebatch command
Default value: See Description
line parameter -s.

Specifies the name of the data type that is to be imported from the
Attribute: nativeTypeName
importFile, such as DFHCOMMAREA for a CICS COBOL application. An
Valid values: See Description
error message is generated on the console if a parse of the importFile
Required?: No
does not identify the nativeTypeName as a valid data type.
Default value: See Description
The default value is: For COBOL, the name of the first available level
01 data item name.

Example

<InputOutputMessage name="PhoneBookMsg" importDirectory="."

importFile="Ex01z.cbl" nativeTypeName="input-msg">
<RedefinesArray>
<RedefineSelection redefine="input-msg.redParent.redefd"
useRedefinition="input-msg.redParent.redefd2"/>
</RedefinesArray>
<ItemSelectionArray>
<ItemSelection itemName="input-msg.redParent"/>
<ItemSelection itemName="input-msg.in-extn"/>
<ItemSelection itemName="input-msg.in-zip"/>
<ItemSelection itemName="input-msg.in-ll"/>
</ItemSelectionArray>
</InputOutputMessage>

ItemExclude
Use this element to prevent individual data items in the COBOL structure from becoming elements in the
XML message.

The exclusion rules apply as follows:

• Only elementary items can be specified. If a group item is specified for omission, a warning message
will be issued and the specification will be ignored.
• If all elementary items in a group are omitted, the group item will automatically be omitted.
• When an ODO (variable size repeating item) count variable is excluded, its ODO subject must also be
excluded. An error message will be issued if this rule is not followed.
• ItemExclude elements can appear in any order within ItemExclusionArray.

460 Developer for z/OS: Developing with Db2, CICS, and IMS
 • You must specify the data item name as fully qualified by dot-separated parent group names if it
is required to resolve name collisions within the language structure. Otherwise, qualification is not
required. For example, in the following language structure, qualification is required for both elementary
items named "CODE":

01 INPUT-MSG.
02 COUNTRY.
03 CODE pic 999.
02 ACTION.
03 CODE pic 9.

as follows: INPUT-MSG.COUNTRY.CODE if you want to exclude that item and INPUT-MSG.ACTION.CODE

if you want to exclude that item. An error message will be issued if this rule is not followed.
• The values of the ItemExclude attributes are not case-sensitive. For example, specifying
itemName="FoO.bAr" is equivalent to specifying itemName="fOo.BaR"
• A warning message will be issued if an item that is specified in the ItemExclude cannot be found in the
source language structure.

Contained by
“ItemExclusionArray” on page 462

Contains
None

Attributes
Fields Description
Specifies the name of the data item to be selected.
Attribute: itemName
Valid values: See Description
Required?: Yes
Default value: None

Example
For the following COBOL language structure

01 INPUT-MSG.
02 IN-LL PICTURE S9(3) COMP.
02 IN-ZZ PICTURE S9(3) COMP.
02 IN-TRCD PICTURE X(10).
02 IN-CMD PICTURE X(8).
02 IN-NAME PICTURE X(10).
02 IN-EXTN PICTURE X(10).

you can use the following settings to prevent IN-LL, IN-ZZ and IN-EXTN data items from becoming
elements in the generated XML message:

<ItemExclusionArray>
<ItemExclude itemName="IN-LL"/>
<ItemExclude itemName="IN-ZZ"/>
<ItemExclude itemName="IN-EXTN"/>
</ItemInclusionArray>

Developing web services and SOA with Enterprise Service Tools 461
 ItemExclusionArray
Use this element as the container for preventing individual data items in the COBOL structure from
becoming elements in the XML message.

ItemExclusionArray provides an inverse capability to the capability of “ItemSelectionArray” on page

464. Therefore ItemExclusionArray and “ItemSelectionArray” on page 464 cannot both be specified
at the same time for the same message specification. If you use ServiceSpecification.xsd to validate
your settings, your settings will not validate correctly if you specify both ItemExclusionArray and
ItemSelectionArray. If you do not use validation and you specify both ItemExclusionArray and
ItemSelectionArray in your settings you will receive an error message during the execution of the Batch
processor. If the this element is not specified the element selection and inclusion applies based on rules
listed in “ItemSelectionArray” on page 464.

Contained by
“InputMessage” on page 457
“InputOutputMessage” on page 459
“OutputMessage” on page 473

Contains
“ItemExclude” on page 460

Attributes
None

Example
For the following COBOL language structure

1 CBL-STRUCT-AAA.
2 CBL-STRUCT-BBB.
3 CBL-FLD-CCC PIC X(10).
3 CBL-FLD-DDD PIC X(2).
3 CBL-FLD-EEE PIC 9.

you can use the following settings to prevent the last two data items from becoming elements in the
generated XML message:

<ItemExclusionArray>
<ItemExclude itemName="CBL-FLD-DDD"/>
<ItemExclude itemName="CBL-FLD-EEE"/>
</ItemInclusionArray>

ItemSelection
Use this element to select individual data item in the COBOL structure.

The selection rules apply as follows:

• When any item is selected, all parent group items containing the selected item are automatically
selected
• If a selected item contains the REDEFINES clause, it must also be specified in the “RedefineSelection”
on page 476 element for this message specification
• When any group item is selected all its children are automatically selected (any items that contain the
REDEFINES clause are also subject to the preceding rule)

462 Developer for z/OS: Developing with Db2, CICS, and IMS
 • When an ODO (variable size repeating) item is selected, its ODO object (count variable) must also be
selected. Otherwise the results produced by the generated artifacts are undefined
• ItemSelection elements can appear in any order within ItemSelectionArray
• The value of the ItemSelection attribute must specify the data item name prefixed by dot-separated
parent group names.
• The values of the ItemSelection attributes are not case-sensitive. For example, specifying
itemName="FoO.bAr" is equivalent to specifying itemName="fOo.BaR"
• If none of the selected items appear in the language structure, the results produced by the generated
artifacts are undefined.

Contained by
“ItemSelectionArray” on page 464

Contains
None

Attributes
Fields Description
Specifies the name of the data item to be selected.
Attribute: itemName
Valid values: See Description
Required?: Yes
Default value: None

Specifies whether the XML schema element generated from this item
Attribute: optional
is optional. If set to "yes", the corresponding XML schema element
Valid values: yes | no
will have a minOccurs facet generated and set to 0. If this attribute is
Required?: No
not specified, minOccurs facet is not generated.
Default value: None

The value of the attribute must specify the item name qualified by a dot-separated parent names as
shown in the example.

Example
For the following COBOL language structure

01 INPUT-MSG.
02 IN-LL PICTURE S9(3) COMP.
02 IN-ZZ PICTURE S9(3) COMP.
02 IN-TRCD PICTURE X(10).
02 IN-CMD PICTURE X(8).
02 IN-NAME1 PICTURE X(10).
02 redParent.
03 redefd.
04 IN-NAME2 PICTURE X(10).
03 redefd2 redefines redefd.
04 IN-NAME2R PICTURE X(10).
02 IN-EXTN PICTURE X(10).
02 IN-EXTNR redefines in-extn PICTURE X(10).
02 IN-ZIP PICTURE X(7).

The following item selections can be specified:

<ItemSelectionArray>
<ItemSelection itemName="input-msg.redParent"/>
<ItemSelection itemName="input-msg.in-extn"/>
<ItemSelection itemName="input-msg.in-zip"/>

Developing web services and SOA with Enterprise Service Tools 463
 <ItemSelection itemName="input-msg.in-ll" optional="yes"/>
</ItemSelectionArray>

Note: To specify redefd2 redefinition in the redParent group, you need to specify the following
RedefinesArray:
Otherwise, redefd items are selected by default.

<RedefinesArray>
<RedefineSelection redefine="input-msg.redParent.redefd"
useRedefinition="input-msg.redParent.redefd2"/>
</RedefinesArray>

ItemSelectionArray
Use this element as the container for individual data item selections in the COBOL structure.

If the this element is not specified the default element selection rules apply as follows:
• If nativeTypeName of the message specification is not given, the first available LEVEL 01 structure and
all its children are automatically selected according to any rules specified in the “RedefineSelection” on
page 476 section and “ItemSelection” on page 462 section.
• If nativeTypeName of the message specification is given, it is assumed to be a LEVEL 01 structure and
all its children are automatically selected according to any rules specified in the “RedefineSelection” on
page 476 section and “ItemSelection” on page 462 section.
• If the RedefineSelectionArray is given, the items from that array will override the default REDEFINES
behavior (See “RedefineSelection” on page 476 and “ItemSelection” on page 462 section for more
information)

Contained by
“InputMessage” on page 457
“InputOutputMessage” on page 459
“OutputMessage” on page 473

Contains
“ItemSelection” on page 462

Attributes
None

Example

<ItemSelectionArray>
<ItemSelection itemName="input-msg.redParent"/>
<ItemSelection itemName="input-msg.in-extn"/>
<ItemSelection itemName="input-msg.in-zip"/>
<ItemSelection itemName="input-msg.in-ll"/>
</ItemSelectionArray>

LanguageStructureSpec
Use this element to specify properties of the language structures generated from the XML schema or
types section in the Web service description (WSDL) file.

These data structures can be used in an application that utilizes XML transformation; for example, CICS
4.1 XMLTRANSFORM resource.

464 Developer for z/OS: Developing with Db2, CICS, and IMS
 Note: LanguageStructureSpec CANNOT be specified with:
• “LanguageStructureSpecIn” on page 465
• “LanguageStructureSpecOut” on page 466

Contained by
“ServiceImplementationSpec” on page 478

Contains
None

Attributes
Fields Description
A 7 character filename for the generated language structures.
Attribute: fileNamePrefix
Valid values: See Description The default value is: First 6 characters of the input XSD or WSDL file
Required?: No name + 'X'
Default value: See Description

Specifies whether to overwrite the output file(s) if it exists.

Attribute: overwrite
Valid values: true | false
Required?: No
Default value: true

Example
Figure 71 on page 465 is an example of the LanguageStructureSpecIn element.

<EISProject xmlns="http:///com/ibm/etools/xmlent/batch/emf/BatchProcessModel.ecore"
name="CICS2XMLSample">

<!-- Generate an XML transformation from an XML schema (XSD)file -->

<EISServiceImplementation runtime="XML_TRANSFORM_CICS">
<ServiceImplementationSpec importDirectory="." importFile="sample.xsd">
<LanguageStructureSpec fileNamePrefix="SAMPX" />
...
</ServiceImplementationSpec>
</EISServiceImplementation>
</EISProject>

Figure 71. Example of LanguageStructureSpec Element

LanguageStructureSpecIn
Use this element of the ServiceSpecification.xml document to specify properties of the language
structures generated from the input messages in the Web service description (WSDL) file.

Contained by
“ServiceImplementationSpec” on page 478

Contains
None

Developing web services and SOA with Enterprise Service Tools 465
 Attributes
Fields Description
A 6 character filename prefix for the generated language structures
Attribute: fileNamePrefix
representing request messages in the web service description. The
Valid values: See Description
remaining two characters are reserved for suffixing the generated
Required?: No
files with an ordinal based on the number of operations in the web
Default value: See Description
service description.
The default value is: First 5 characters of the input WSDL file name +
'I'

Specifies whether to overwrite the output file(s) if it exists.

Attribute: overwrite
Valid values: true | false
Required?: No
Default value: true

Example
Figure 72 on page 466 is an example of LanguageStructureSpecIn element.

<EISProject xmlns="http:///com/ibm/etools/xmlent/batch/emf/BatchProcessModel.ecore"
name="CICSTopDownSample">

<!-- Generate an implementation of a web service from a WSDL file -->

<EISServiceImplementation runtime="WEB_SERVICES_CICS" type="SERVICE_PROVIDER">
<ServiceImplementationSpec importDirectory="." importFile="ServiceDefinition.wsdl">
<LanguageStructureSpecIn fileNamePrefix="SRVPRI" />
...
</ServiceImplementationSpec>
</EISServiceImplementation>

</EISProject>

Figure 72. Example of LanguageStructureSpecIn Element

LanguageStructureSpecOut
Use this element of the ServiceSpecification.xml document to specify properties of the language
structures generated from the output messages in the Web service description (WSDL) file.

Contained by
“ServiceImplementationSpec” on page 478

Contains
None

Attributes
Fields Description
A 6 character filename prefix for the generated language structures
Attribute: fileNamePrefix
representing request messages in the web service description. The
Valid values: See Description
remaining two characters are reserved for suffixing the generated
Required?: No
files with an ordinal based on the number of operations in the web
Default value: See Description
service description.
The default value is: First 5 characters of the input WSDL file name +
'O'

466 Developer for z/OS: Developing with Db2, CICS, and IMS
Fields Description
Specifies whether to overwrite the output file(s) if it exists.
Attribute: overwrite
Valid values: true | false
Required?: No
Default value: true

Example
Figure 73 on page 467 is an example of LanguageStructureSpecOut element.

<EISProject xmlns="http:///com/ibm/etools/xmlent/batch/emf/BatchProcessModel.ecore"
name="CICSTopDownSample">

<!-- Generate an implementation of a web service from a WSDL file -->

<EISServiceImplementation runtime="WEB_SERVICES_CICS" type="SERVICE_PROVIDER">
<ServiceImplementationSpec importDirectory="." importFile="ServiceDefinition.wsdl">
<LanguageStructureSpecOut fileNamePrefix="SRVPRO" />
...
</ServiceImplementationSpec>
</EISServiceImplementation>

</EISProject>

Figure 73. Example of LanguageStructureSpecOut Element

MessageSpec
Use this element to specify data structures for conversion by the XML transformation.

The XML transformation is supported in CICS Transaction Server 4.1 and later. MessageSpec elements
apply to:
• conversion from XML documents to data structures
• conversion from data structures to XML documents
Note: MessageSpec CANNOT be used with:
• “InputMessage” on page 457
• “OutputMessage” on page 473
• “InputOutputMessage” on page 459 (Deprecated)
The “InputOutputMessage” on page 459 element is being deprecated and should not be used. Instead
use the “InputMessage” on page 457 and “OutputMessage” on page 473 elements and specify identical
parameters.

Contained by
“Operation” on page 469

Contains
“ItemSelectionArray” on page 464
“RedefinesArray” on page 475
“XMLNamesArray” on page 503

Developing web services and SOA with Enterprise Service Tools 467
 Attributes
Table 124 on page 468 shows the attributes for MessageSpec.

Table 124. Attribute Specifications for MessageSpec

Fields Description
This attribute has no effect on generated artifacts. It is reserved for
Attribute: name
future use.
Valid values: See Description
Required?: No
Default value: esvc

Specifies the absolute path to location and name in the file system of
Attribute: annotationsFile
the synonym action XML file. The synonym action XML file contains
Valid values: See Description
the optional annotation information that can be present in the source
Required?: No
of the data declarations. If this attribute is not specified, the default
Default value: See Description
is taken from the "-annot" parameter of the xsebatch invocation. For
more information, see “Using source annotations to specify service
interface” on page 297.
Specifies the absolute path to location and name in the file system of
Attribute: commTypesFile
the common types xml file. The common types xml file describes the
Valid values: See Description
common element and type information that is used in the generated
Required?: No
XSD schema to refer to instead of imbedding and potentially
Default value: See Description
duplicating the types. If this attribute is not specified, the default is
taken from the "-commtypes" parameter of the xsebatch invocation.
For more information, see “Commonly Used Elements and Types” on
page 302.
Specifies the directory for the source file.
Attribute: importDirectory
Valid values: See Description The default value is: The input directory
Required?: No
Default value: See Description

Specifies the file name that contains the language data definitions to
Attribute: importFile
be used in creating the XML data types.
Valid values: See Description
Required?: Yes (unless the -s Note: Only COBOL data definitions are supported and are subject to
command the restrictions that are specified in the online help.
line option is specified)
The default value is: The name provided in the xsebatch command
Default value: See Description
line parameter -s.

Specifies the name of the data type that is to be imported from the
Attribute: nativeTypeName
importFile, such as DFHCOMMAREA for a CICS COBOL application. An
Valid values: See Description
error message is generated on the console if a parse of the importFile
Required?: No
does not identify the nativeTypeName as a valid data type.
Default value: See Description
The default value is: For COBOL, the name of the first available level
01 data item name.

Example
Figure 74 on page 469 is an example of the MessageSpec element.

468 Developer for z/OS: Developing with Db2, CICS, and IMS
 <MessageSpec name="convertThis" importDirectory="." importFile="sample.cbl"
nativeTypeName="input-struc">
<RedefinesArray>
<RedefineSelection redefine="input-msg.redParent.redefd"
useRedefinition="input-msg.redParent.redefd2"/>
</RedefinesArray>
<ItemSelectionArray>
<ItemSelection itemName="input-msg.redParent"/>
<ItemSelection itemName="input-msg.in-extn"/>
<ItemSelection itemName="input-msg.in-zip"/>
<ItemSelection itemName="input-msg.in-ll"/>
</ItemSelectionArray>
</MessageSpec>

Figure 74. Example of MessageSpec Element

Operation
Use this element to specify the type of operation and as the container for operation properties. Note that
only one operation is allowed per service. Specifying more than one operation may cause an invalid WSDL
to be generated.

Contained by
“EISService” on page 453

Contains
“OperationPropertyArray” on page 472
“InputOutputMessage” on page 459 (Deprecated)
“InputMessage” on page 457
“MessageSpec” on page 467
“OutputMessage” on page 473
“XseSpec” on page 511
Note: Operation can contain a “MessageSpec” on page 467 element. If Operation contains a
“MessageSpec” on page 467 element, then Operation CANNOT contain:
• “InputMessage” on page 457
• “OutputMessage” on page 473
• “InputOutputMessage” on page 459 (Deprecated)
If this restriction is not followed, the results of the generation are unpredictable.
The “InputOutputMessage” on page 459 element is being deprecated and should not be used. Instead
use the “InputMessage” on page 457 and “OutputMessage” on page 473 elements and specify identical
parameters.

Attributes
Fields Description
Specifies the name of the operation in the WSDL file.
Attribute: name
Valid values: See Description The default value is: The name attribute for the EISService element
Required?: No concatenated with "Operation"
Default value: See Description
Note: For Web Services that use the CICS Bottom up interpretive
case, the default operation name is CICS program name+"Operation".

Developing web services and SOA with Enterprise Service Tools 469
Fields Description
Specifies whether to generate the converter set (request, response,
Attribute: type
converters, and driver). See Note.
Valid values: REQUEST_RESPONSE |
SOLICIT_RESPONSE | ONE_WAY |
NOTIFICATION
Required?: No
Default value: REQUEST_RESPONSE

Note:
REQUEST_RESPONSE and SOLICIT_RESPONSE operations cause the generation of:
1. a request converter, a response converter, a driver (if the generateConverters option is in effect),
AND
2. a request and response schema (if the generateSeparateXSD option is in effect).
A NOTIFICATION operation causes the generation of:
1. a response converter, a driver (if the generateConverters option is in effect),
AND
2. a response schema (if the generateSeparateXSD option is in effect).
A ONE_WAY operation causes the generation of:
1. a request converter, a driver (if the generateConverters option is in effect),
AND
2. a request schema (if the generateSeparateXSD option is in effect).

Example
Figure 75 on page 471 is an example of Operation element.

470 Developer for z/OS: Developing with Db2, CICS, and IMS
 <Operation name="getCustomerInfo" type="REQUEST_RESPONSE">
<OperationPropertyArray>
<OperationProperty name="soapOpStyle" value="document" />
<OperationProperty name="soapBindingStyle" value="document" />
<OperationProperty name="soapBodyUse" value="literal" />
</OperationPropertyArray>
<InputOutputMessage name="CustomerDetails" importDirectory="." importFile="DFH0ACTD.cbl"
nativeTypeName="DFHCOMMAREA">
<RedefinesArray>
<RedefineSelection redefine="name.info" useRedefinition="name.last-name"/>
<RedefineSelection redefine="address.zip-code" useRedefinition="province"/>
</RedefinesArray>
</InputOutputMessage>
<XseSpec>
<DriverSpec fileName=""DFH0CSTDD.cbl" driverType="IMS SOAP Gateway"
programName="XCNVD" businessPgmName="Ex01" />
<ConverterSpecIn fileName="DFH0CSTDI.cbl" overwrite="true"
programName="XCNVI"/>
<ConverterSpecOut fileName="DFH0CSTDO.cbl" overwrite="true"
programName="XCNVO"/>
<XsdSpecIn fileName="DFH0CSTDI.xsd overwrite="true"
targetNamespace="http://www.DFH0CSTDI.com/schemas/DFH0CSTDIInterface"
xsdNamespace="http://www.w3.org/2001/XMLSchema"
localNamespace="http://www.DFH0CSTDI.com/schemas/DFH0CSTDIInterface"
xsdPrefix="cbl"
xsdElemName="dfhcommarea"/>
<XsdSpecOut fileName="DFH0CSTDO.xsd" overwrite="true"
targetNamespace="http://www.DFH0CSTDO.com/schemas/DFH0CSTDOInterface"
xsdNamespace="http://www.w3.org/2001/XMLSchema"
localNamespace="http://www.DFH0CSTDO.com/schemas/DFH0CSTDOInterface"
xsdPrefix="cbl"
xsdElemName="dfhcommarea"/>
</XseSpec>
</Operation>

Figure 75. Example of Operation Element

OperationProperty
Use this element to specify the properties for an operation.

Contained by
“OperationPropertyArray” on page 472

Contains
None

Attributes
Fields Description
Specifies the URI for the optional SOAP action.
Attribute: soapAction
Valid values: URI
Required?: No
Default value: None

Specifies use of encoding style for SOAP body.

Attribute: soapBodyUse
Valid values: literal | encoded
Required?: No
Default value: literal

Developing web services and SOA with Enterprise Service Tools 471
Fields Description
Specifies the SOAP operation style. The value must match the
Attribute: soapOpStyle
soapBindingStyle in ServiceSpecification.xml.
Valid values: document | rpc
Required?: No
Default value: document

Note: If you are generating artifacts for IMS Enterprise Suite SOAP Gateway you must specify soapAction
property, for example "urn:IMSPHBK". It should match the soapAction value in the CorrelatorSpec
property. If you don't specify this property or if it does not match the CorrelatorSpec, it will cause a
runtime error.

Example

<OperationPropertyArray>
<OperationProperty name="soapOpStyle" value="document" />
<OperationProperty name="soapBodyUse" value="literal" />
<OperationProperty name="soapAction" value="urn:myaction" />
</OperationPropertyArray>

OperationPropertyArray
Use this element as the container for operation properties.

Contained by
“Operation” on page 469

Contains
“OperationProperty” on page 471

Attributes
None

Example

<OperationPropertyArray>
<OperationProperty name="soapOpStyle" value="document" />
<OperationProperty name="soapBindingStyle" value="document" />
<OperationProperty name="soapBodyUse" value="literal" />
</OperationPropertyArray>

OperationSelection
Use this element to select an operation from those defined in the WSDL file.

Contained by
“OperationSelectionArray” on page 473

Contains
None

472 Developer for z/OS: Developing with Db2, CICS, and IMS
 Attributes
Fields Description
Selects an operation to implement from the binding selected in
Attribute: name
the ServicePropertyArray. Specified operation(s) must exist in the
Valid values: operationName
services specified in the Service property array. If the specified
Required?: No
operations are not found, an error message is generated.
Default value: None

Example

<OperationSelectionArray>
<OperationSelection operationName="getBalance"/>
<OperationSelection operationName="getInterestRate"/>
</OperationSelectionArray>

OperationSelectionArray
Use this element as a container for the operation selection elements.

Contained by
“ServiceSpecification.xml” on page 443

Contains
“OperationSelection” on page 472

Attributes
None

Example

<OperationSelectionArray>
<OperationSelection operationName="getBalance"/>
<OperationSelection operationName="getInterestRate"/>
</OperationSelectionArray>

OutputMessage
Use this element to define messages for NOTIFICATION operations or REQUEST_RESPONSE
(SOLICIT_RESPONSE) operations if the input and output messages are of different types. Note that for
NOTIFICATION operations, you are allowed to specify only the OutputMessage. InputMessage is not
allowed and will cause unpredictable results during the generation process. To compose a message from
multiple data types, specify additional OutputMessage elements (this capability is only supported for
the IMS Enterprise Suite SOAP Gateway runtime). The order in which the OutputMessage elements are
specified in Operation element determines their order in the composite message.

Contained by
“Operation” on page 469

Contains
“ItemSelectionArray” on page 464
“RedefinesArray” on page 475
“XMLNamesArray” on page 503
“ItemExclusionArray” on page 462

Developing web services and SOA with Enterprise Service Tools 473
 Attributes
Table 125 on page 474 shows the attributes for OuputMessage.

Table 125. Attribute Specifications for OutputMessage

Fields Description
This attribute has no effect on generated artifacts. It is reserved for
Attribute: name
future use.
Valid values: See Description
Required?: No
Default value: esvc

Specifies the absolute path to location and name in the file system of
Attribute: annotationsFile
the synonym action XML file. The synonym action XML file contains
Valid values: See Description
the optional annotation information that can be present in the
Required?: No
source of the service interface data declarations. If this attribute
Default value: See Description
is not specified, the default is taken from the “-annot” parameter
of the xsebatch invocation. For more information see “Using source
annotations to specify service interface” on page 297.
Specifies the absolute path to location and name in the file system of
Attribute: commTypesFile
the common types xml file. The common types xml file describes the
Valid values: See Description
common element and type information that is used in the generated
Required?: No
WSDL and XSD schema to refer to instead of imbedding and
Default value: See Description
potentially duplicating the types. If this attribute is not specified, the
default is taken from the “-commtypes” parameter of the xsebatch
invocation. For more information see “Commonly Used Elements and
Types” on page 302.
Specifies the directory for the source file.
Attribute: importDirectory
Valid values: See Description The default value is: The input directory
Required?: No
Default value: The input directory

Specifies the file name that contains the data definition to be used in
Attribute: importFile
creating the Web service operation message types.
Valid values: See Description
Required?: Yes (unless the -s Note: Only COBOL data definitions are supported and are subject to
command the restrictions that are specified in the online help.
line option is specified)
The default value is: The name provided in the xsebatch command-
Default value: See Description
line parameter -s.

Corresponds to the minOccurs attribute value of the xsd:element

Attribute: lowerBound
that is assigned the complexType derived from the data type
Valid values: 1 to n
specified in the following attributes: importDirectory, importFile, and
Required?: No
nativeTypeName
Default value: 1
Note: This attribute is ignored unless two or more InputMessages are
specified.

Specifies the name of the data type that is to be imported from the
Attribute: nativeTypeName
importFile, such as DFHCOMMAREA for a CICS COBOL application. An
Valid values: See Description
error message is generated on the console if a parse of the importFile
Required?: No
does not identify the nativeTypeName as a valid data type.
Default value: See Description
The default value is: For COBOL, the name of the first available level
01 data item name.

474 Developer for z/OS: Developing with Db2, CICS, and IMS
Table 125. Attribute Specifications for OutputMessage (continued)
Fields Description
Corresponds to the minOccurs attribute value of the xsd:element
Attribute: upperBound
that is assigned the complexType derived from the data type
Valid values: 1 to n, -1 (infinite)
specified in the following attributes: importDirectory, importFile, and
Required?: No
nativeTypeName
Default value: 1
Note: This attribute is ignored unless two or more InputMessages are
specified.

Specifies the desired tag name of the xsd:element that is assigned

Attribute: xmlEleName
the complexType derived from the data type specified in the following
Valid values: See Description
attributes: importDirectory, importFile, and nativeTypeName
Required?: No
Default value: See Description Note: This attribute is ignored unless two or more OutputMessages
are specified.

Example
Figure 76 on page 475 is an example of OutputMessage element.
Note: Another example of an OutputMessage element is in “Specification of Multiple Response Language
Structures” on page 311.

<OutputMessage name="PhoneBookReply" importDirectory="." importFile="Ex01z.cbl"

commTypesFile=c:/common/commtypesSample.xml nativeTypeName="output-msg">
<RedefinesArray>
<RedefineSelection redefine="output-msg.redParent.redefd"
useRedefinition="output-msg.redParent.redefd2"/>
</RedefinesArray>
<ItemSelectionArray>
<ItemSelection itemName="output-msg.redParent"/>
<ItemSelection itemName="output-msg.in-extn"/>
<ItemSelection itemName="output-msg.in-zip"/>
<ItemSelection itemName="output-msg.in-ll"/>
</ItemSelectionArray>
</OutputMessage>

Figure 76. Eample of OutputMessage Element

RedefinesArray
Use this element as the container for REDEFINE item selections for COBOL.

Note: The default behavior for redefinitions when there are REDEFINES in the data but the
RedefinesArray element is omitted is to use the original definition of the items.

Contained by
“InputMessage” on page 457
“InputOutputMessage” on page 459
“OutputMessage” on page 473

Contains
RedefineSelection

Attributes
None

Developing web services and SOA with Enterprise Service Tools 475
 Example

<RedefinesArray>
<RedefineSelection redefine="name.info" useRedefinition="name.last-name"/>
<RedefineSelection redefine="address.zip-code" useRedefinition="province"/>
</RedefinesArray>

RedefineSelection
Use this element to select redefinitions for an item.

Contained by
“RedefinesArray” on page 475

Contains
None

Attributes
If necessary for uniqueness, qualify the data item names using the period-separated notation. For
example, use name info from the following language structure.

1 name.
2 info pic x(100).
2 last-name redefines info pic x(100).

Fields Description
Specifies the name of the data item to be redefined.
Attribute: redefine
Valid values: See Description Note: Redefinitions of redefined items are not supported.
Required?: Yes
Default value: None

Specifies the name of the data item to be used.

Attribute: useRedefinition
Valid values: See Description
Required?: Yes
Default value: None

Example

<RedefinesArray>
<RedefineSelection redefine="name.info" useRedefinition="name.last-name"/>
<RedefineSelection redefine="address.zip-code" useRedefinition="province"/>
</RedefinesArray>

RouterSpec
Use this element to specify attributes and properties of the router program to route multiple operation
requests for a single end point. This element will be used to name the source file and the program name
for the router program. This element can be specified for multiple operations or for single operations.
If the RouterSpec element is not specified for multiple operations, the default values are derived from
the name element of the EISService element as shown in “XML Schema element for EISService with
RouterSpec and WSBindSpec elements” on page 477. If it is not specified for single operations, no router
program is generated.

Contained by
“EISService” on page 453

476 Developer for z/OS: Developing with Db2, CICS, and IMS
 XML Schema element for EISService with RouterSpec and WSBindSpec elements
Figure 77 on page 477 is and example of an XML Schema element for EISService with RouterSpec and
WSBindSpec elements.

<xsd:element name="EISService">
<xsd:complexType>
<xsd:sequence>
<xsd:element maxOccurs="1" minOccurs="0" ref="ServicePropertyArray"/>
<xsd:element maxOccurs="1" minOccurs="0" ref="ConnectionPropertyArray"/>
<xsd:element maxOccurs="unbounded" minOccurs="0" ref="Operation"/>
<xsd:element maxOccurs="1" minOccurs="0" ref="WSBindSpec"/>
<xsd:element minOccurs="0" ref="RouterSpec"/>
</xsd:sequence>
<xsd:attribute name="generateConverters" type="xsd:boolean" use="optional"/>
<xsd:attribute name="generateSeparateXSD" type="xsd:boolean" use="optional"/>
<xsd:attribute name="generateWSDL" type="xsd:boolean" use="optional"/>
<xsd:attribute name="name" type="xsd:string" use="optional"/>
<xsd:attribute name="targetNamespace" type="xsd:string" use="optional"/>
<xsd:attribute name="type" type="xsd:string" use="optional"/>
<xsd:attribute name="targetFilesURI" type="xsd:string" use="optional"/>
</xsd:complexType>
</xsd:element>

Figure 77. XML Schema Element for EISService with RouterSpec and WSBindSpec Elements

Attributes

Fields Description
Specifies the name of the output file.
Attribute: fileName
Valid values: See Description The default value is: The Service name in the generated WSDL File
Required?: No truncated to 8 characters and concatenated with .CBL file extension.
Default value: See Description

Specifies whether to overwrite the output file if it exists.

Attribute: overwrite
Valid values: true | false
Required?: No
Default value: true

Specifies the program name of the main program entry of the Router.
Attribute: programName
Any program name longer than 8 characters will be truncated to 8
Valid values: See Description
characters.
Required?: No
Default value: See Description The default value is: The Service name in the generated WSDL File
truncated to 7 characters and suffixed with letter "T".

Specifies router type. Currently, only WEB_SERVICES_CICS is

Attribute: type
supported. This type must match driverType attribute for the
Valid values: WEB_SERVICES_CICS
DriverSpec element of each Operation.
Required?: No
Default value: WEB_SERVICES_CICS

Example

<RouterSpec fileName="ROUTER.CBL" programName="ROUTER"/>

<CodegenPropertyArray type="Cobol">
<CodegenProperty name="com.ibm.etools.xmlent.ui.GEN_PROG_NAME"
value="CWSA"/>

Developing web services and SOA with Enterprise Service Tools 477
 <CodegenProperty name=
"com.ibm.etools.xmlent.ui.GEN_CONVERSION_TYPE"
value="interpretive"/>
</CodegenPropertyArray>

ServiceImplementationSpec
Use this element of the ServiceSpecification.xml document to provide information about the service
implementation or, in the case of XML transformations, about the transformation artifacts.

This element must contain one and only one of the following elements:
• WSBindSpec:
Use this element to generate a set of artifacts for a top-down development scenario for Web Services
for CICS.
• XSDBindSpec:
Use this element to generate a set of artifacts for use in an XML transformation, such as a CICS 4.1
XMLTRANSFORM resource.
– Only the “LanguageStructureSpec” on page 464 can be specified in the
“ServiceImplementationSpec” on page 478.
– If any of the following elements are also specified they are ignored:
- “ApplicationTemplateSpec” on page 444
- “LanguageStructureSpecIn” on page 465
- “LanguageStructureSpecOut” on page 466
• WSDL2ELSSpec:
Use this element to generate a set of artifacts for IMS and other non-CICS top-down scenarios (see
WSD2ELSSpec).
– ServiceImplementationSpec can also include the following elements:
- DriverSpec
- CorrelatorSpec

Contained by
“EISServiceImplementation” on page 455

Contains
“ApplicationTemplateSpec” on page 444
“LanguageStructureSpec” on page 464
“LanguageStructureSpecIn” on page 465
“LanguageStructureSpecOut” on page 466
“WSBindSpec” on page 4831
“XSDBindSpec” on page 4962
“WSDL2ELSSpec” on page 4923
“DriverSpec” on page 4493
“CorrelatorSpec” on page 447 3
1See the description of WSBindSpec earlier in this topic.
2See the description of XSDBindSpec earlier in this topic.
3See the description of WSDL2ELSSpec earlier in this topic.

478 Developer for z/OS: Developing with Db2, CICS, and IMS
 Attributes
Fields Description
Specifies the directory for the source file. The path can be either
Attribute: importDirectory
relative to ServiceSpecification.xml or absolute.
Valid values: See Description
Required?: No
Default value: The input directory

Specifies the file name that contains:

Attribute: importFile
Valid values: See Description • a Web service definition (WSDL) file
Required?: Yes (unless the -s
or
command
line option is specified) • an XML schema (XSD) file
Default value: See Description The default value is: The name provided in the xsebatch command-
line parameter -s.

Specifies the WSDL Port name for which to generate service artifacts.
Attribute: wsdlPortName
The Port name must exist in the WSDL otherwise an error message is
Valid values: See Description
displayed.
Required?: Yes
Default value: None

Specifies the WSDL Service name for which to generate service

Attribute: wsdlServiceName
artifacts. The Service name must exist in the WSDL otherwise an error
Valid values: See Description
message is displayed.
Required?: Yes
Default value: None

Examples

<EISProject xmlns="http:///com/ibm/etools/xmlent/batch/emf/BatchProcessModel.ecore"
name="CICSTopDownSample">

<!-- Generate an implementation of a web service from a WSDL file -->

<EISServiceImplementation type="SERVICE_PROVIDER">
<ServiceImplementationSpec importFile="WSAT001.wsdl" importDirectory=".">
<LanguageStructureSpecIn fileNamePrefix="WSATPI"/>
<LanguageStructureSpecOut fileNamePrefix="WSATPO"/>
<WSBindSpec fileName="WSAT001P.wsbind" uri="/cics/services/calculator"
pgmint="1" contid="WSAT001P" logFileName="WSAT001P.log"/>
<ApplicationTemplateSpec fileName="WSAT001P.cbl" programName="WSAT001P"/>
</ServiceImplementationSpec>
</EISServiceImplementation>

</EISProject>

Figure 78. Example 1 of ServiceImplementationSpec Element

Developing web services and SOA with Enterprise Service Tools 479
 <EISProject xmlns="http:///com/ibm/etools/xmlent/batch/emf/BatchProcessModel.ecore"
name="CICSXSDTopDownSample">

<!-- Generate XML conversion artifacts from an XSD file -->

<EISServiceImplementation>
<ServiceImplementationSpec importFile="XSAT001.xsd" importDirectory=".">
<LanguageStructureSpec fileNamePrefix="XSATPI"/>
<XSDBindSpec fileName="XSAT001P.xsdbind" logFileName="WSAT001P.log"/>
</ServiceImplementationSpec>
</EISServiceImplementation>

</EISProject>

Figure 79. Example 2 of ServiceImplementationSpec Element

ServiceProperty
Use this element to specify the properties for a service.

Contained by
“ServicePropertyArray” on page 481

Contains
None

Attributes
Fields Description
Specifies the name of the binding element in the WSDL file.
Attribute: bindingName
Valid values: QNAME The default value is: The name attribute for the EISService element
Required?: No (or if it is not specified, the value of -w parameter from the xsebatch
Default value: See Description command line invocation) concatenated with the UPPER-CASED
value of the type attribute of the EISService element.

Specifies the name of the port element in the WSDL file.

Attribute: portName
Valid values: QNAME The default value is: The name attribute for the EISService element
Required?: No (or if it is not specified, the value of -w parameter from the xsebatch
Default value: See Description command line invocation) concatenated with the UPPER-CASED
value of the type attribute of the EISService element.

Specifies the name of the port type element in the WSDL file.
Attribute: portType
Valid values: QNAME The default value is: The name attribute for the EISService element
Required?: No (or if it is not specified, the value of -w parameter from the xsebatch
Default value: See Description command line invocation) concatenated with the UPPER-CASED
value of the type attribute of the EISService element.

For a top-down scenario this attribute selects a specific service in a

Attribute: selectService
reusable binding. It applies only to WSDL 2.0 bindings and is ignored
Valid values: QNAME
for any prior versions of the WSDL. It is also ignored for any non
Required?: No
top-down scenarios and scenarios that do not support WSDL 2.0.
Default value: None

480 Developer for z/OS: Developing with Db2, CICS, and IMS
Fields Description
Specifies the value of the name attribute of service element in the
Attribute: serviceName
WSDL file.
Valid values: QNAME
Required?: No The default value is: The name attribute for the EISService element
Default value: See Description (or if it is not specified, the value of -w parameter from the xsebatch
command line invocation) concatenated with the UPPER-CASED
value of the type attribute of the EISService element.

Specifies the value of the style attribute of binding element in

Attribute: soapBindingStyle
the WSDL file. The value must match the soapOpStyle.in Operation
Valid values: document | rpc
properties.
Required?: No
Default value: document

Specifies the value for the transport attribute of the binding element
Attribute: soapTransport
in the WSDL file.
Valid values: URI
Required?: No The default value is: http://schemas.xmlsoap.org/soap/http
Default value: See Description

Example
Figure 80 on page 481 is an example of the ServiceProperty element within the ServicePropertyArray
element..

<ServicePropertyArray>
<ServiceProperty name="bindingName" value="myBinding" />
<ServiceProperty name="bindingType" value="SOAP" />
<ServiceProperty name="soapTransport" value="http://schemas.xmlsoap.org/soap/http" />
<ServiceProperty name="soapBindingStyle" value="document" />
<ServiceProperty name="selectService" value="BankAccountServices" />

</ServicePropertyArray>

Figure 80. Example of ServiceProperty Element

ServicePropertyArray
Use this element as a container for the properties for a service.

Contained by
“EISService” on page 453

Contains
“ServiceProperty” on page 480

Attributes
None

Example
Figure 81 on page 482 is an example of the ServicePropertyArray element.

Developing web services and SOA with Enterprise Service Tools 481
 <ServicePropertyArray>
<ServiceProperty name="bindingName" value="myBinding" />
<ServiceProperty name="bindingType" value="SOAP" />
<ServiceProperty name="soapTransport" value="http://schemas.xmlsoap.org/soap/http" />
<ServiceProperty name="soapBindingStyle" value="document" />
</ServicePropertyArray>

Figure 81. Example of ServicePropertyArray Element

TypeSelection
Use this element, in a top-down scenario, to select a type from those defined in the XSD file or in the
types section of the WSDL file.

Contained by
“TypeSelectionArray” on page 482

Contains
None

Attributes
Fields Description
Selects a type to implement from the XSD file or from the types
Attribute: name
section of the WSDL file in a top-down scenario. Specified type must
Valid values: typeName
exist in the XSD or the WSDL file. If the specified type is not found, an
Required?: No
error message is generated.
Default value: None

Example

<TypeSelectionArray>
<TypeSelection name="balanceType"/>
<TypeSelection name="interestRateType"/>
</TypeSelectionArray>

TypeSelectionArray
Use this element, in the top-down scenario, as a container for the TYPE selection elements which are
enabled for conversion.

Note: If no TypeSelectionArray is specified in a top-down scenario, no types are used for generating the
conversion artifacts.

Contained by
“ServiceImplementationSpec” on page 478

Contains
“TypeSelection” on page 482

Attributes
None

482 Developer for z/OS: Developing with Db2, CICS, and IMS
Example

<TypeSelectionArray>
<TypeSelection name="balanceType"/>
<TypeSelection name="interestRateType"/>
</TypeSelectionArray

WSBindSpec
Use this element of the ServiceSpecification.xml document to specify the generation properties for the
Native or Vendor WSBind file.

The WSBind file is used to install a new Web service under CICS Transaction Server version 3.1 and later.
There are two kinds of WSBind files that may be generated: Native WSBind and Vendor WSBind.
The following shows which generation properties are associated with each WSBind file type and examples
of how to specify them.
Native WSBind (Interpretive XML Conversion):
• Characteristics:
– CICS performs XML conversion using an internal mechanism
– Specify @type="interpretive" on the element PlatformProperties.xml/CodegenPropertyArray/
CodegenProperty/@name="com.ibm.etools.xmlent.ui.GEN_CONVERSION_TYPE"
– Specify ServiceSpecification.xml/../WSBindSpec/@businessPgmName="name of CICS program"

• PlatformProperties.xml:

<PlatformArray>
<Platform>
<CodegenPropertyArray>
<CodegenProperty name="com.ibm.etools.xmlent.ui.GEN_CONVERSION_TYPE"
value="interpretive"/>
</CodegenPropertyArray>
</Platform>
</PlatformArray>

• ServiceSpecification.xml (bottom-up):

<EISProject
xmlns="http:///com/ibm/etools/xmlent/batch/emf/BatchProcessModel.ecore"
name="CICSPROGProject">
<EISService name="CICSPROG">
<Operation>
<OutputMessage importFile="CICSPROG.cbl" importDirectory="."
nativeTypeName="DFHCOMMAREA"/>
<InputMessage importFile="CICSPROG.cbl" importDirectory="."
nativeTypeName="DFHCOMMAREA"/>
<XseSpec>
<WSBindSpec fileName="CICSPROG.wsbind"
uri="/cics/services/CICSPROG" logFileName="CICSPROG.log"
businessPgmName="CICSPROG"/>
</XseSpec>
</Operation>
</EISService>
</EISProject>

Vendor WSBind (Compiled XML Conversion):

• Characteristics:
– CICS performs XML conversion using Developer for z/OS generated XML conversion programs
– Specify @type="compiled" on the element PlatformProperties.xml/CodegenPropertyArray/
CodegenProperty/@name="com.ibm.etools.xmlent.ui.GEN_CONVERSION_TYPE"
– Specify ServiceSpecification.xml/../DriverSpec/@driverType="WEB_SERVICES_CICS"
– Specify ServiceSpecification.xml/../DriverSpec/@businessPgmName="name of CICS program".

Developing web services and SOA with Enterprise Service Tools 483
 • PlatformProperties.xml:

<PlatformArray>
<Platform>
<CodegenPropertyArray>
<CodegenProperty name="com.ibm.etools.xmlent.ui.GEN_CONVERSION_TYPE"
value="compiled"/>
</CodegenPropertyArray>
</Platform>
</PlatformArray>

• ServiceSpecification.xml (bottom-up):

<EISProject
xmlns="http:///com/ibm/etools/xmlent/batch/emf/BatchProcessModel.ecore"
name="CICSPROGProject">
<EISService name="CICSPROG">
<Operation>
<OutputMessage importFile="CICSPRG.cbl" importDirectory="."
nativeTypeName="DFHCOMMAREA"/>
<InputMessage importFile="CICSPRG.cbl" importDirectory="."
nativeTypeName="DFHCOMMAREA"/>
<XseSpec>
<DriverSpec fileName="CICSPRGD.cbl" driverType="WEB_SERVICES_CICS"
programName="CICSPRG" businessPgmName="CICSPROG"/>
<ConverterSpecIn fileName="CICSPRGD.cbl" programName="BUP001"/>
<ConverterSpecOut fileName="CICSPRGD.cbl" programName="BUP001"/>
<WSBindSpec fileName="CICSPROG.wsbind" uri="/cics/services/CICSPROG"
logFileName="CICSPROG.log"
mappingLevel="VENDOR" minimumRuntimeLevel="VENDOR"/>
</XseSpec>
</Operation>
</EISService>
</EISProject>

Contained by
“XseSpec” on page 511
“ServiceImplementationSpec” on page 478

Contains
None

Attributes
Table 126 on page 484 shows the attributes for WSBindSpec.

Table 126. Attribute Specifications for WSBindSpec

Fields Description
Controls the maximum size of the pack decimal variable length that
Attribute: arithExtend
is mapping to the COBOL Language structure, If set to YES, it will use
Valid values: NO | YES
31 digits for DECIMAL and INTEGER types. If set to NO (default), the
Required?: No
number of digits remains at 18. This option is available at all mapping
Default value: NO
levels.
Specifies the existing business program that CICS Web services
Attribute: businessPgmName
runtime calls. This is the program that you are enabling for processing
Valid values: See Description
and/or producing XML messages to act as a Web service. This
Required?: No
attribute is only meaningful for CICS native conversion and to specify
Default value: See Description
target business program entry point for multiple operations in the
compiled conversion.
The default value is: The Service name in the generated WSDL File
truncated to 8 characters.

484 Developer for z/OS: Developing with Db2, CICS, and IMS
Table 126. Attribute Specifications for WSBindSpec (continued)
Fields Description
Specifies the CCSID that is used at run time to encode data between
Attribute: ccsid
the application program and the Web services binding file. The value
Valid values: See Description
of this parameter overrides the value of the LOCALCCSID system
Required?: No
initialization parameter. The value must be an EBCDIC CCSID that is
Default value: See Description
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).
Specifies how character arrays in the language structure should be
Attribute: charVarying (EISService)
mapped when the mapping level is 1.2 and higher.
Valid values: NO | NULL |
COLLAPSE | BINARY Note: This parameter does not apply to Enterprise and other PL/I
Required?: No language structures.
Default value: NULL or COLLAPSE
The options you can select are:
(See Description)
• 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. This value is the
default for mapping levels 1.2 and 2.0
• 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.
Required elements:
• PlatformProperties.xml/CodegenPropertyArray/CodegenProperty
@name="CONVERSION_TYPE" @value="interpretive"
• ServiceSpecification.xml/EISService

Developing web services and SOA with Enterprise Service Tools 485
Table 126. Attribute Specifications for WSBindSpec (continued)
Fields Description
Specifies how variable length character data is mapped when the
Attribute: charVarying
mapping level is 1.2 or higher. Variable length binary data types are
(EISServiceImplementation)
always mapped to either a container or a varying structure. If you
Valid values: NO | NULL | YES
do not specify this parameter, the default mapping depends on the
Required?: No
language specified. The options that you can select are:
Default value: NO
• 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 comprises of two related elements - data length and the data.
Required Batch Options:
• PlatformProperties.xml/CodegenPropertyArray/CodegenProperty
@name="CONVERSION_TYPE" @value="interpretive"
• ServiceSpecification.xml/EISService

Specifies the maximum size of binary data and variable length

Attribute: charVaryingLimit
character data that is mapped to the language structure when the
Valid values: See Description
mapping level is 1.2 or higher. If the character or binary data is larger
Required?: No
than the value specified in this parameter, it is mapped to a container
Default value: 32767
and the container name is used in the generated language structure.
The value can range from 0 to the default 32767 bytes.
Required Batch Options:
• PlatformProperties.xml/CodegenPropertyArray/CodegenProperty
@name="CONVERSION_TYPE" @value="interpretive"
• ServiceSpecification.xml/EISService

If the CICS application program (specified DriverSpec/

Attribute: contid
businessPgmName or WSBindSpec/businessPgmName attribute of
Valid values: See Description
the element) communicates via a CHANNEL, specify the name of the
Required?: No (Yes, if pgmint is
CONTAINER expected by program.
set to CHANNEL)
Default value: None (See Note 1)

Attribute: dataTruncation Specifies how truncated data is treated by the CICS native conversion
Valid values: DISABLED | ENABLED mechanism:
Required?: No • If set to ENABLED, CICS tolerates truncated application data and
Default value: DISABLED assumes that the missing data is set to nulls.
• If it is set to DISABLED, CICS rejects the truncated application data
and issues an error message.
Note: The ENABLED setting is only supported at mapping levels 3.0
and higher.

486 Developer for z/OS: Developing with Db2, CICS, and IMS
Table 126. Attribute Specifications for WSBindSpec (continued)
Fields Description

Attribute: dateTime Specifies how the XML elements of xsd:dateTime type are mapped
Valid values: See Description into CICS ASKTIME format. This attribute is only valid for the
Required?: No CICS interpretive conversion type. If it is specified for the Vendor
Default value: See Description (Compiled) conversion type, it is ignored.
This attribute is only valid at Mapping level 3.0 and higher.
If this attribute is specified in a top-down scenario (that is, the
WSBindSpec is specified inside the EISServiceImplementation) then
the valid values are:
• PACKED15 (default)
or
• STRING
If this attribute is specified in a bottom-up (that is, the WSBindSpec is
specified inside the EISService) then the valid values are:
• UNUSED (default)
or
• PACKED15

Specifies the default array length of character data in characters for

Attribute: defaultCharMaxLength
mappings where no length is implied in the Web service description
Valid values: See Description
document, when the mapping level is 1.2 or higher. The value of this
Required?: No
parameter can be a positive integer in the range of 1 to 2147483647.
Default value: 255
Required Batch Options:
• PlatformProperties.xml/CodegenPropertyArray/CodegenProperty
@name="CONVERSION_TYPE" @value="interpretive"
• ServiceSpecification.xml/EISService

Specifies the name of the output file

Attribute: fileName
Valid values: See Description The default value is: Data source file name concatenated with
Required?: No ".wsbind" (See Note 1).
Default value: See Description

This attribute is equivalent to the INLINE-MAXOCCURS-LIMIT

Attribute: inlineMaxOccursLimit
parameter of the CICS Web services Assistant DFHLS2WS. The value
Valid values: 0 through 32767
is used to decide whether or not to in-line variable repeating content
Required?: No
based on the value of the maxOccurs attribute from the source WSDL
Default value: 1
file The full description can be found in the CICS Transaction Server V
5.3 documentation, refer to:
• DFHWS2LS: WSDL to high-level language conversion

Specifies the name of the log file generated by the

Attribute: logFileName
Web Services Assistant. This attribute value is used only
Valid values: See Description
when the following is specified in the PlatformProperties.xml
Required?: No
file: <CodegenPropertyname="com.ibm.etools.xmlent.ui.
Default value: See Description
GEN_CONVERSION_TYPE "value="interpretive"/>
The default value is: fileName concatenated with ".log"

Developing web services and SOA with Enterprise Service Tools 487
Table 126. Attribute Specifications for WSBindSpec (continued)
Fields Description
Specifies the version of the programmatic interface shared between
Attribute: mappingLevel
CICS and the application (see Mapping levels for the CICS assistants).
Valid values: 1.0 | 1.1 | 1.2 |
Generally, it is best to specify the highest mapping level that is
2.0 | 2.1 |2.2 | 3.0 | 4.0
available:
Required?: No • Mapping levels 1.0 to 1.2 are supported in CICS TS 3.1 with APAR
Default value: 2.1 (See Note 1) 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.
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 5 Release 2 Knowledge Center).
1.0
This is the CICS runtime default mapping level. For
more information on mapping levels refer to CICS TS 4.1
documentation at: The CICS web services assistant
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.
For more information on mapping levels refer to CICS TS 4.1
documentation at: The CICS web services assistant
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 of the wizard (see Inline maxOccurs
limit).
• XML-ONLY (also called Pass-through XML)
See the description of the Pass-through XML preference on the
DFHWS2LS tab of the wizard (see Pass-through XML).

• WSDL-NAMESPACE
See the description of the WSDL namespace preference on the
WSDL and XSD tab of the wizard (see WSDL namespace).
488 Developer for z/OS: Developing with Db2, CICS, and IMS
Support has been added for the XML schema element <xsd:any>
Table 126. Attribute Specifications for WSBindSpec (continued)
Fields Description
Specifies whether the default behavior is overridden for the specified
Attribute: mappingOverides
mapping level when generating language structures.
Valid values: See Description
Required?: No The options you can select are:
Default value: See Description
• 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 - 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.

Specifies the minimum CICS runtime environment that the Web

Attribute: minimumRuntimeLevel
service binding file can be deployed into. An error message is
Valid values: MINIMUM |
displayed if a level is selected that does not match the other
1.0 | 1.1 | 1.2 |
parameters specified.
2.0 | 2.1 | 4.0 | CURRENT
Required?: No MINIMUM
Default value: MINIMUM (See Note 1) The lowest possible runtime level of CICS is allocated
automatically given the parameters that are specified.
1.0
The generated Web service binding file deploys successfully into
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
CICS TS 3.1 region that has at least APAR PK15904 applied.
1.2
The generated Web service binding file deploys successfully into
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
CICS TS 3.2.
2.1
The generated Web service binding file deploys successfully into
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
CICS TS 5.2 and 5.3
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.

Developing web services and SOA with Enterprise Service Tools 489
Table 126. Attribute Specifications for WSBindSpec (continued)
Fields Description
Specifies how a generated field name is shortened if it is too long for
Attribute: nameTruncation
use in the specified high-level language. This option is available at all
Valid values: RIGHT | LEFT
mapping levels.
Required?: No
Default value: RIGHT 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.

Specifies whether to overwrite the output file if it exists.

Attribute: overwrite
Valid values: true | false
Required?: No
Default value: true

Specify whether the CICS application program communicates via:

Attribute: pgmint
Valid values: 0 | 1| 2 • 0 - CHANNEL DESCRIPTION DOCUMENT
Required?: No
Use CHANNEL DESCRIPTION DOCUMENT, when a Web service
Default value: 2
uses many containers in its application interface, must first create
a channel description document to describe the containers. The
channel description document is an XML document that conforms
to a schema that is provided by CICS.
CHANNEL DESCRIPTION DOCUMENT is only valid for (1) the CICS
interpretive (bottom-up) conversion type AND (2) mapping level 3.0
and higher.
• 1 - CHANNEL
Use CHANNEL, when a Web service uses one container in its
application interface.
• 2 - DFHCOMMAREA
This is the default.

Attribute: requestChannel If the CICS application program (specified DriverSpec/

Valid values: See Description businessPgmName or WSBindSpec/businessPgmName attribute of
Required?: No (Yes, if pgmint is the element) communicates via a CHANNEL (multiple containers),
set to CHANNEL specify the location of channel description document for the request.
DESCRIPTION DOCUMENT) This attribute is only valid for the CICS interpretive (bottom-up)
Default value: None conversion type. If it is specified for the Vendor (Compiled)
conversion type, it is ignored. This attribute is only valid at mapping
level 3.0 and higher.
Note: The language structure location(s) specified in
the channel description document should be on
the local file system (For example: <structure
location=”c:\MyStructures\copybook.cpy”/>)

490 Developer for z/OS: Developing with Db2, CICS, and IMS
Table 126. Attribute Specifications for WSBindSpec (continued)
Fields Description

Attribute: responseChannel If the CICS application program (specified DriverSpec/

Valid values: See Description businessPgmName or WSBindSpec/businessPgmName attribute of
Required?: No the element) communicates via a CHANNEL (multiple containers),
Default value: None specify the location of channel description document for the
response.
This attribute is only valid for the CICS interpretive (bottom-up)
conversion type. If it is specified for the Vendor (Compiled)
conversion type, it is ignored. This attribute is only valid at mapping
level 3.0 and higher.
Note: The language structure location(s) specified in
the channel description document should be on
the local file system (For example: <structure
location=”c:\MyStructures\copybook.cpy”/>)
If the application uses the same set of containers for the response
as was used for the request, then specify the same value as the
requestChannel

Use this parameter only when directed to do so by IBM support.

Attribute: service
Valid values: See Description Required Batch Options:
Required?: No
• PlatformProperties.xml/CodegenPropertyArray/CodegenProperty
Default value: See Description
– @name="CONVERSION_TYPE"
– @value="interpretive"
• ServiceSpecification.xml/EISService

Indicates whether or not to suppress generation of the Web Services

Attribute: suppressGeneration
binding file (WSBind).
Valid values: true | false
Required?: No
Default value: false

Specifies that the remote web service can issue a syncpoint. This
Attribute: synconreturn
attribute is equivalent to the SYNCONRETURN parameter of the CICS
Valid values: YES | NO
Web services assistant wizard pages DFHLS2WS and DFHWS2LS. The
Required?: No
implication of setting this option to YES is that the remote task is
Default value: NO
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.
In a service provider, this parameter specifies the 1-4 character
Attribute: transaction
name of an alias transaction that can start the pipeline or run a user
Valid values: See Description
application to compose a HTTP response. The value of this parameter
Required?: No
is used to define the TRANSACTION attribute of the URIMAP resource
Default value: See Description
when it is created automatically using the PIPELINE scan command.
Acceptable characters: A-Z a-z 0-9 $

Developing web services and SOA with Enterprise Service Tools 491
Table 126. Attribute Specifications for WSBindSpec (continued)
Fields Description
Desired local URI to for the Web service, for example, "/exampleApp/
Attribute: uri
InquireSingle". Note: this is different that the location of the Web
Valid values: See Description
service for example, http://server:port[local URI]. If you do not
Required?: No
specify this property it must be defined at install time during manual
Default value: See Description
creation of the Web service resource definitions in CICS.
In a service provider, this parameter specifies a 1-8 character user ID
Attribute: userid
which can be used by any Web client. For an application-generated
Valid values: See Description
response or a Web service, the alias transaction is attached under
Required?: No
this user ID. The value of this parameter is used to define the USERID
Default value: See Description
attribute of the URIMAP resource when it is created automatically
using the PIPELINE scan command.
Acceptable characters: A-Z a-z 0-9 $ @ #

Specifies the program name of the main program entry.

Attribute: vendorConverterName
Valid values: See Description The default value is: DriverSpec/@fileName (see Note 1)
Required?: No
Default value: See Description

If this attribute is set to true then CICS does not perform any
Attribute: xmlOnly
transformations to the XML at all and instead requires that the
Valid values: true | false
application work with the contents of the DFHWS-BODY container
Required?: No
directly. For a full description refer to: CICS® Transaction Server for
Default value: false
z/OS, Version 5 Release 2 IBM Documentation

Note: The following WSBind default settings apply when multiple operations are present:
• contid value: Service name in WSDL
• fileName: WSDL file location and WSDL file name with .wsbind extension
• mappingLevel: 1.2
• minimumRuntimeLevel: 1.2
• vendorConverterName: Service name in WSDL truncated to 8 characters

Related reference

CICS Web services assistant:

The CICS web services assistant

Example

<WSBindSpec fileName="CICSPROG.wsbind" uri="/cics/services/CICSPROG"

mappingLevel="VENDOR" logFileName="CICSPROG.log" ccsid="37"
minimumRuntimeLevel="VENDOR" userid="WEBUSER" transaction="WBTR">
</WSBindSpec>

WSDL2ELSSpec
Use this element of the ServiceSpecification.xml document to specify options for generating the artifacts
that implement a service description in a top-down scenario.

Contained by

492 Developer for z/OS: Developing with Db2, CICS, and IMS
 “ServiceImplementationSpec” on page 478

Contains
None

Attributes
Table 127 on page 493 shows the attributes for WSDL2ELSSpec.

Table 127. Attribute specifications for WSDL2ELSSpec

Fields Description
Specifies a value that is applied when elementary language structure
Attribute: defaultCharMaxLength
members are generated for XSD element and attribute declarations
Valid PL/I values: n where 1 <= n <=
of the following types:
(215 – 1)
Valid COBOL values: n where 1 <= n • xsd:string
<= (227 – 1) • xsd:simpleType having xsd:string as its base type but omitting the
Required?: No length or maxLength constraining facets.
Default PL/I value: n = 256
Default COBOL value: n = 256

Specifies a value that is applied when elementary language structure

Attribute: defaultBase64BinaryLength
members are generated for XSD element and attribute declarations
Valid PL/I values: where 1 <= n <=
of the following types:
(230 – 1)
Valid COBOL values: None (not • * xsd:base64Binary
supported • * xsd:simpleType having xsd:base64Binary as its base type but
Required?: No omitting the length or maxLength constraining facets.
Default PL/I value: n = 256
Default COBOL value: None (not
supported)

Specifies a value that is applied when elementary language structure

Attribute: defaultTotalDigits
members are generated for XSD element and attribute declarations
Valid PL/I values: n where 1 <= n <=
of the following types:
31
Valid COBOL values: n where 1 <= n • xsd:decimal
<= 31 • xsd:integer
Required?: No
Default PL/I value: n=31 • xsd:simpleType having either xsd:decimal or xsd:integer as its base
Default COBOL value: n=31 type but omitting the totalDigits constraining facet.

Specifies a value that is applied when elementary language structure

Attribute: defaultFractionDigits
members are generated for XSD element and attribute declarations
Valid PL/I values: n where 0 <= n <=
of the following types:
31
Valid COBOL values: n where 0 <= n • xsd:decimal
<= 31 • xsd:simpleType having xsd:string as its base type but omitting the
Required?: No fractionDigits constraining facet.
Default PL/I value: n = 6
Default COBOL value: n = 6

Developing web services and SOA with Enterprise Service Tools 493
Table 127. Attribute specifications for WSDL2ELSSpec (continued)
Fields Description
Specifies a value that is applied when elementary language structure
Attribute: defaultDateTimeLength
members are generated for XSD element and attribute declarations
Valid PL/I values: n where 1 <= n <=
of the following types:
(215 – 1)
Valid COBOL values: n where 1 <= n • xsd:date, xsd:dateTime, xsd:duration, xsd:gDay, xsd:gMonth,
<= (227 – 1) xsd:gMonthDay, xsd:gYear, xsd:gYearMonth, and xsd:time.
Required?: No • xsd:simpleType having one of the preceding types as its base type
Default PL/I value: n = 64 but omitting the length or maxLength constraining facets.
Default COBOL value: n = 64

Specify whether or not WSDL2ELS should suppress generation of

Attribute:
leading and inline comments when generating language structures
suppressStructureComments
in the WSDL2PLI and WSDL2COBOL scenarios. This option does not
Valid values: true | false
affect the documentation that is generated at the beginning of the
Required?: No
language file.
Default value: False

Specify whether or not WSDL2ELS should suppress generation of

Attribute: suppressPresenceFields
@PRESENCE fields (suffixes -bit, _bit) for XML elements or XML
Valid PL/I values: None (not
attributes when generating language structures.
supported)
Valid COBOL values: true | false Note: This option is not supported in the WSDL2PLI scenario.
Required?: No
Default PL/I value: None (not
supported)
Default COBOL value: False

Specify whether or not WSDL2ELS should suppress generation of

Attribute: suppressCountFields
@COUNT fields (suffixes -cnt, _cnt) for XML element arrays when
Valid PL/I values: None (not
generating language structures.
supported)
Valid COBOL values: true | false Note: This option is not supported in the WSDL2PLI scenario.
Required?: No
Default PL/I value: None (not
supported)
Default COBOL value: False

Specifies the relative path of the file container that contains the
Attribute: fileContainer
generated files. This path is relative to the project that is specified
Valid values: See Description.
in EISProject/@name. For example, the fileContainer "generated", as
Required?: Yes
used in the example below, specifies a directory at the top level of the
Default value: None
project specified in EISProject/@name.
If the directory does not exist it is created. If the directory exists its
contents are overwritten.

494 Developer for z/OS: Developing with Db2, CICS, and IMS
Table 127. Attribute specifications for WSDL2ELSSpec (continued)
Fields Description

Attribute: inlineStringLengthLimit Specifies a value that establishes a limit on the length of XSD element
Valid PL/I values: n where 0 <= n <= and attribute declarations of type “xsd:string” that are eligible to be
32767 mapped inline. XSD elements or attributes that exceed the limit will
Valid COBOL values: None (not be mapped out-of-line using a language-specific mechanism if and
supported) only if an out-of-line mapping has the potential to occupy fewer bytes
Required?: No than an inline mapping.
Default PL/I value: n = 32767 This attribute interacts with attribute defaultCharMaxLength, which
Default COBOL value: None (not provides the default length of XSD element or attribute declarations
supported) of type “xsd:string” that do not specify the length or maxLength
facets.
Note: The default PL/I value of 32767 effectively disables out-of-line
mappings as this is the maximum length in bytes of PL/I CHAR or
WCHAR variables.
Note: This attribute is not supported in the WSDL2COBOL scenario.

Specifies a value that is applied when language structure members

Attribute: inlineMaxOccursLimit
are generated for XSD element declarations that specify the
Valid PL/I values: n where 1 <= n <=
minOccurs and maxOccurs facets. If an XML element specifies a
(231 – 1)
minOccurs or maxOccurs facet value that is greater than the value
Valid COBOL values: None (not
of this attribute, the array that is generated in the language structure
supported)
will have a upper bound that is determined at execution time (for
Required?: No
example, by using REFER in PL/I).
Default PL/I value: n=20
Default COBOL value: None (not
supported)

Attribute: defaultMaxOccursLimit Specifies a value that is applied when language structure members
Valid PL/I values: None (not are generated for XSD element declarations that specify the
applicable) maxOccurs facet.
Valid COBOL values: n where 1 <= n If an XML element specifies a maxOccurs facet value that is
<= (227 – 1) unbounded or exceeds the value of this attribute, the upper bound
Required?: No of the array that is generated in the language structure will be equal
Default PL/I value: None (not to the value of this attribute.
applicable)
Default COBOL value: n=20 Note: This option is not supported in the WSDL2PLI scenario.

Specifies the file name of the generated file into which language
Attribute: languageFileName
structures are written.
Valid values: See Description.
Required?: Yes If the file does not exist it is created. If the file exists it is overwritten.
Default value: None

Specifies a value that is applied when names are derived for language
Attribute: languageNameLimit
structures and language structure members from the names of
Valid PL/I values: n where 1 <= n <=
corresponding XSD element and attribute declarations. For PL/I, if
100
the value of this attribute is greater than 31 then generated language
Valid COBOL values: n where 1 <= n
structures must be compiled with the option “LIMITS(NAME(n))”,
<= 30
where 31 < n <= 100.
Required?: No
Default PL/I value: n=100
Default COBOL value: n=30

Developing web services and SOA with Enterprise Service Tools 495
Table 127. Attribute specifications for WSDL2ELSSpec (continued)
Fields Description
Specifies the file name of the file into which log information is written.
Attribute: logFileName
Valid values: See Description. If the file does not exist it is created. If the file exists it is overwritten.
Required?: Yes
Default value: None

Specifies the relative path of the directory in which the metadata

Attribute: mappingDirectory
file is created. This path is relative to the path that is specified in
Valid values: See Description.
@fileContainer.
Required?: Yes
Default value: None If the directory does not exist it is created. If the directory exists its
contents are overwritten.

Specifies the file name of the file into which WSDL2ELS metadata is
Attribute: metadataFileName
written.
Valid values: See Description.
Required?: Yes If the file does not exist it is created. If the file exists it is overwritten.
Default value: None

Example

<WSDL2ELSSpec
defaultCharMaxLength="256"
defaultBase64BinaryLength="256"
defaultTotalDigits="31"
defaultFractionDigits="6"
defaultDateTimeLength="64"
inlineMaxOccursLimit="20"
languageNameLimit="31"
fileContainer="/generated"
languageFileName="MYAPP.inc"
logFileName="MYAPP.log"
mappingDirectory="metadata/mapping"
metadataFileName="MYAPP_metadata.xml" />

XSDBindSpec
Use this element of the ServiceSpecification.xml document to specify the generation properties for the
Native or Vendor XML binding file (XSDBind file).

The XSDBind file is used to install an XML transformation resource (XMLTRANSFORM) under CICS
Transaction Server version 5.2 and later. The XMLTRANSFORM resource is used by the CICS EXEC APIs,
TRANSFORM XMLTODATA and TRANSFORM DATATOXML.
The XMLTRANSFORM resource can be used to perform the XML transformation in both directions
(DATATOXML and XMLTODATA), for one XML document and for one data structure. This is in contrast
to the WEBSERVICE resource in which transformation to an XML document can be different from the
transformation to a data structure.
There are two kinds of XSDBind files that may be generated: Native XSDBind and Vendor XSDBind.
The following shows which generation properties are associated with each XSDBind file type and
examples of how to specify them.
Native XSDBind (Interpretive XML Conversion):
• Characteristics:
– CICS performs XML conversion using an internal mechanism

496 Developer for z/OS: Developing with Db2, CICS, and IMS
 – Specify @type="interpretive" on the element PlatformProperties.xml/CodegenPropertyArray/
CodegenProperty/@name="com.ibm.etools.xmlent.ui.GEN_CONVERSION_TYPE"
– Include "MessageSpec" inside the element ServiceSpecification.xml/EISProject/EISService/
Operation.

• PlatformProperties.xml:

<PlatformArray>
<Platform>
<CodegenPropertyArray>
<CodegenProperty name="com.ibm.etools.xmlent.ui.GEN_CONVERSION_TYPE"
value="interpretive"/>
</CodegenPropertyArray>
</Platform>
</PlatformArray>

• ServiceSpecification.xml (bottom-up):

<EISProject
xmlns="http:///com/ibm/etools/xmlent/batch/emf/BatchProcessModel.ecore"
name="CICSPROGProject">
<EISService name="CICSPROG">
<Operation>
<MessageSpec importFile="CICSPRG.cbl" importDirectory="."
nativeTypeName="DFHCOMMAREA"/>
<XseSpec>
<XSDBindSpec fileName="CICSPROG.xsdbind" logFileName="CICSPRG.log"/>
</XseSpec>
</Operation>
</EISService>
</EISProject>

Vendor XSDBind (Compiled XML Conversion):

• Characteristics:
– CICS performs XML conversion using the XML conversion programs generated by the single-service
project tools.
– Specify @type="compiled" on the element PlatformProperties.xml/CodegenPropertyArray/
CodegenProperty/@name="com.ibm.etools.xmlent.ui.GEN_CONVERSION_TYPE"
– Include "MessageSpec" inside the element ServiceSpecification.xml/EISProject/EISService/
Operation.
• PlatformProperties.xml:

<PlatformArray>
<Platform>
<CodegenPropertyArray>
<CodegenProperty name="com.ibm.etools.xmlent.ui.GEN_CONVERSION_TYPE"
value="compiled"/>
</CodegenPropertyArray>
</Platform>
</PlatformArray>

• ServiceSpecification.xml (bottom-up):

<EISProject
xmlns="http:///com/ibm/etools/xmlent/batch/emf/BatchProcessModel.ecore"
name="CICSPROGProject">
<EISService name="CICSPROG">
<Operation>
<MessageSpec importFile="CICSPRG.cbl" importDirectory="."
nativeTypeName="FHCOMMAREA"/>
<XseSpec>
<DriverSpec fileName="CICSPRGD.cbl" driverType="XML_TRANSFORM_CICS"
programName="CICSPRG"/>
<ConverterSpecIn fileName="CICSPRGD.cbl" programName="BUP001"/>
<ConverterSpecOut fileName="CICSPRGD.cbl" programName="BUP001"/>
<XSDBindSpec fileName="CICSPROG.xsdbind" logFileName="CICSPROG.log"
mappingLevel="VENDOR" minimumRuntimeLevel="VENDOR"/>
</XseSpec>
</Operation>

Developing web services and SOA with Enterprise Service Tools 497
 </EISService>
</EISProject>

Contained by
“XseSpec” on page 511
“ServiceImplementationSpec” on page 478

Contains
None

Attributes
Table 128 on page 498 shows the attributes for XSDBindSpec.

Table 128. Attribute Specifications for XSDBindSpec

Fields Description
Controls the maximum size of the pack decimal variable length that
Attribute: arithExtend
is mapping to the COBOL Language structure, If set to YES, it will use
Valid values: NO | YES
31 digits for DECIMAL and INTEGER types. If set to NO (default), the
Required?: No
number of digits remains at 18. This option is available at all mapping
Default value: NO
levels.
Specifies the path and name of the bundle directory. If you specify
Attribute: bundle
this value, the XML schema (which you must specify in the XSDSpec
Valid values: See Description
element) and the XML binding file is generated in the bundle directory
Required?: No
and a bundle manifest is also created. The path information on this
Default value: None
parameter overrides any path information on the XSDSpec fileName
attribute and XSDBindSpec fileName attribute.
Specifies the CCSID that is used at run time to encode data
Attribute: ccsid
between the application program and the XML binding file. The value
Valid values: See Description
of this parameter overrides the value of the LOCALCCSID system
Required?: No
initialization parameter. The value must be an EBCDIC CCSID that is
Default value: See Description
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 XML binding file is
encoded in US EBCDIC (Cp037).

498 Developer for z/OS: Developing with Db2, CICS, and IMS
Table 128. Attribute Specifications for XSDBindSpec (continued)
Fields Description
Specifies how character arrays in the language structure should be
Attribute: charVarying (EISService)
mapped when the mapping level is 1.2 or higher .
Valid values: NO | NULL |
COLLAPSE | BINARY Note: This parameter does not apply to Enterprise and other PL/I
Required?: No language structures.
Default value: NULL or COLLAPSE
The options you can select are:
(See Description)
• 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 XML document. The maximum
length of the character string is calculated as one character less
than the length indicated in the language structure. This value is the
default for mapping levels 1.2 and 2.0.
• 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.
Required elements:
• PlatformProperties.xml/CodegenPropertyArray/CodegenProperty
– @name="CONVERSION_TYPE"
– @value="interpretive"
• ServiceSpecification.xml/EISService

Attribute: charVarying Specifies how variable length character data is mapped when the
mapping level is 1.2 or higher. Variable length binary data types are
(EISServiceImplementation)
always mapped to either a container or a varying structure. If you
Valid values: NO | NULL | YES
do not specify this parameter, the default mapping depends on the
Required?: No
language specified. The options that you can select are:
Default value: NO
• 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 comprises of two related elements - data length and the data.
Required Batch Options:
• PlatformProperties.xml/CodegenPropertyArray/CodegenProperty
@name="CONVERSION_TYPE" @value="interpretive"
• ServiceSpecification.xml/EISService

Developing web services and SOA with Enterprise Service Tools 499
Table 128. Attribute Specifications for XSDBindSpec (continued)
Fields Description
Specifies the maximum size of binary data and variable length
Attribute: charVaryingLimit
character data that is mapped to the language structure when the
Valid values: See Description
mapping level is 1.2 or higher. If the character or binary data is larger
Required?: No
than the value specified in this parameter, it is mapped to a container
Default value: 32767
and the container name is used in the generated language structure.
The value can range from 0 to the default 32767 bytes.
Required Batch Options:
• PlatformProperties.xml/CodegenPropertyArray/CodegenProperty
@name="CONVERSION_TYPE" @value="interpretive"
• ServiceSpecification.xml/EISService

Specifies the default array length of character data in characters for

Attribute: defaultCharMaxLength
mappings where no length is implied in the XML schema, when the
Valid values: See Description
mapping level is 1.2 or higher. The value of this parameter can be a
Required?: No
positive integer in the range of 1 to 2147483647.
Default value: 255
Required Batch Options:
• PlatformProperties.xml/CodegenPropertyArray/CodegenProperty
@name="CONVERSION_TYPE" @value="interpretive"
• ServiceSpecification.xml/EISService

Specifies the name of the output file

Attribute: fileName
Valid values: See Description The default value is: Data source file name concatenated with
Required?: No ".xsdbind"
Default value: See Description

This attribute is equivalent to the INLINE-MAXOCCURS-LIMIT

Attribute: inlineMaxOccursLimit
parameter of the CICS XML Assistant DFHLS2SC. The value is used
Valid values: 0 through 32767
to decide whether or not to in-line variable repeating content based
Required?: No
on the value of the maxOccurs attribute from the source WSDL. The
Default value: 1
full description can be found in the CICS Transaction Server V 5.3
IBM Documentation, see:
• DFHSC2LS: XML schema to high-level language conversion

Specifies the name of the log file generated by the

Attribute: logFileName
XML Assistant. This attribute value is used only when
Valid values: See Description
the following is specified in the PlatformProperties.xml
Required?: No
file: <CodegenPropertyname="com.ibm.etools.xmlent.ui.
Default value: See Description
GEN_CONVERSION_TYPE "value="interpretive"/>
The default value is: fileName concatenated with ".log"

500 Developer for z/OS: Developing with Db2, CICS, and IMS
Table 128. Attribute Specifications for XSDBindSpec (continued)
Fields Description
Specifies the version of the programmatic interface shared between
Attribute: mappingLevel
CICS and the application (see CICS® Transaction Server for z/OS,
Valid values: 1.0 | 1.1 | 1.2 |
Version 5 Release 2 IBM Documentation). Generally, it is best to
2.0 | 2.1 |2.2 | 3.0 | 4.0
specify the highest mapping level that is available:
Required?: No
Default value: 2.1 • 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.
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. For
more information on mapping levels refer to CICS TS 4.1
documentation at: The CICS web services assistant
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 DFHLS2SC
tab and the DFHSC2LS 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.
For more information on mapping levels refer to CICS TS 5.3
documentation at: Mapping levels for the CICS assistants
2.1
Use this mapping level for CICS TS 3.2 with APAR PK59794 and
later. At this level you can use the following features:
• INLINE-MAXOCCURS-LIMIT (available on wizard page
DFHSC2LS)
This option allows you to decide whether to map variably
repeating content inline or to use the existing container based
mapping. For additional details, refer to: Mapping levels for the
CICS assistants

Support has been added for xsd:any and xsd:anyType (for

DFHSC2LS), see:Support for xsd:any and xsd:anyType
2.2
Use this mapping level with a CICSS TS 3.2 region that has
APAR PK69738 applied. Mapping level 2.2 provides the following
support: web services and SOA with Enterprise Service Tools 501
Developing
• Elements with fixed values
Table 128. Attribute Specifications for XSDBindSpec (continued)
Fields Description
Specifies whether the default behavior is overridden for the specified
Attribute: mappingOverides
mapping level when generating language structures.
Valid values: See Description
Required?: No The options you can select are:
Default value: See Description
• 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 - 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.

Specifies the minimum CICS runtime environment that the XML

Attribute: minimumRuntimeLevel
binding file can be deployed into. An error message is displayed if a
Valid values: MINIMUM |
level is selected that does not match the other parameters specified.
3.0 | 4.0 | CURRENT
Required?: No MINIMUM
Default value: MINIMUM The lowest possible runtime level of CICS is allocated
automatically given the parameters that are specified.
3.0
The generated XML binding file deploys successfully into CICS TS
4.1
4.0
The generated XML binding file deploys successfully into CICS TS
5.2 and 5.3
CURRENT
The generated XML binding file deploys successfully into a CICS
region at the highest available runtime level as the one you are
using to generate the XML binding file

Specifies how a generated field name is shortened if it is too long for

Attribute: nameTruncation
Valid values: RIGHT | LEFT use in the specified high-level language. This option is available at all
mapping levels.
Required?: No
Default value: RIGHT 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.

Specifies the program name of the main program entry.

Attribute: vendorConverterName
Valid values: See Description The default value is: DriverSpec/@fileName
Required?: No
Default value: See Description

502 Developer for z/OS: Developing with Db2, CICS, and IMS
Table 128. Attribute Specifications for XSDBindSpec (continued)
Fields Description

Attribute: dateTime Specifies how the XML elements of xsd:dateTime type are mapped
Valid values: See Description into CICS ASKTIME format. This attribute is only valid for the
Required?: No CICS interpretive conversion type. If it is specified for the Vendor
Default value: See Description (Compiled) conversion type, it is ignored.
This attribute is only valid at Mapping level 3.0 and higher.
If this attribute is specified in a top-down scenario (that is the
XSDBindSpec is specified inside the EISServiceImplementation) then
the valid values are:
• PACKED15 (default)
or
• STRING
If this attribute is specified in a bottom-up (that is, the XSDBindSpec
is specified inside the EISService) then the valid values are:
• UNUSED (default)
or
• PACKED15

Specifies how truncated data is treated by the CICS native conversion

Attribute: dataTruncation
mechanism:
Valid values: DISABLED | ENABLED
Required?: No • If set to ENABLED, CICS tolerates truncated application data and
Default value: DISABLED assumes that the missing data is set to nulls.
• If set to DISABLED, CICS rejects the truncated data and issues an
error message.
Note: The ENABLED setting is only supported at mapping levels 3.0
and higher.

Related reference

CICS Web services assistant:

The CICS web services assistant

Example

<XSDBindSpec fileName="CICSPROG.xsdbind"
mappingLevel="VENDOR" logFileName="CICSPROG.log" ccsid="37"
minimumRuntimeLevel="VENDOR">
</XSDBindSpec>

XMLNamesArray
Use this element as a container for one or more XMLNameSelection elements.

Contained by

“InputMessage” on page 457

“InputOutputMessage” on page 459
“OutputMessage” on page 473

Developing web services and SOA with Enterprise Service Tools 503
 Contains
“XMLNameSelection” on page 504

Attributes
None

Example

<ItemSelectionArray>
<ItemSelection itemName="A.B.C"/>
</ItemSelectionArray>
<XMLNamesArray>
<XMLNameSelection itemName="A.B.C" xmlName="XMLC"/>
<XMLNameSelection itemName="A.B" xmlName="XMLB"/>
<XMLNameSelection itemName="A" xmlName="XMLA"/>
</XMLNamesArray>

XMLNameSelection
Use this element to provide the mapping of the original COBOL elements to the new XML element names.

There are some important aspects to consider when you use this element:
• No error checking is done to ensure the xmlName attribute value is in fact a valid XML element name.
• Only the batch specification files support alternate name specification. The GUI wizard does not have
that capability.
• The XMLNamesArray and the xsdElemName attributes of the XsdSpec elements should not be used to
alter the same level 01 COBOL item in the same message specification. Use one or the other but not
both in the same specification.
• Element and type names formation is similar to name formation applied to the default names subject to
the following rules:
– If non-level 01 COBOL item name or its alternate name is all upper case, the corresponding XML
schema type if any and the XML element name will be all lower case
– If non-level 01 item name or its alternate name is not all upper case, the corresponding XML schema
type, if any, and the XML element name will preserve the case of the specification
– The case of level 01 item name will always have the case of the original COBOL name of the xmlName
attribute specification
– All hyphens are removed from level 01 item names
– One or more hyphens are replaced by a single underscore in non-level 01 item names. COBOL names
that differ only by the number of hyphens are not supported. The schemas generated from COBOL
data containing items with such names under the same group item will have duplicate element
names and may not be valid

Contained by
“XMLNamesArray” on page 503

Contains
None

504 Developer for z/OS: Developing with Db2, CICS, and IMS
 Attributes
Fields Description
Specifies the name of the COBOL data item for which the alternate
Attribute: itemName
name is desired. The value of this attribute must specify a valid
Valid values: See Description
COBOL data item name prefixed with dot-separated parent names
Required?: Yes
as shown in the following example. Only this COBOL data item is
Default value: None
affected
Specifies the name from which the XML names in generated schemas
Attribute: xmlName
and WSDL files will be derived. This name will be used rather than the
Valid values: See Description
name of the COBOL data item.
Required?: Yes
Default value: None

Example
(1) Assuming the COBOL language structure shown in Figure 82 on page 505

1 A.
2 B.
3 C pic x(10).
3 D pix x(2).

Figure 82. Example of COBOL Language Structures for XMLNameSelection Element

(2) Figure 83 on page 505 is an example of specifying alternate names for the three data items A, B, and
C shown in Figure 82 on page 505.

<ItemSelectionArray>
<ItemSelection itemName="A.B.C"/>
</ItemSelectionArray>
<XMLNamesArray>
<XMLNameSelection itemName="A.B.C" xmlName="XMLC"/>
<XMLNameSelection itemName="A.B" xmlName="XMLB"/>
<XMLNameSelection itemName="A" xmlName="XMLA"/>
</XMLNamesArray>

Figure 83. Example of Alternate Names of COBOL Language Structures for XMLNameSelection Element

(3) Given the specification provided per Figure 82 on page 505 and Figure 83 on page 505, Figure 84 on
page 506 is an example of the schema that is generated.

Developing web services and SOA with Enterprise Service Tools 505
 <?xml version="1.0" encoding="UTF-8"?>
<schema xmlns="http://www.w3.org/2001/XMLSchema" xmlns:cbl="http://www.XC011I.com/schemas/
XC011IInterface"
targetNamespace="http://www.XC011I.com/schemas/XC011IInterface">
<complexType name="XMLA">
<sequence>
<element name="xmlb" type="cbl:xmla_xmlb"/>
</sequence>
</complexType>
<complexType name="xmla_xmlb">
<sequence>
<element name="xmlc">
<annotation>
<appinfo source="http://www.wsadie.com/appinfo">
<initialValue kind="SPACE"/>
</appinfo>
</annotation>
<simpleType>
<restriction base="string">
<maxLength value="10"/>
</restriction>
</simpleType>
</element>
</sequence>
</complexType>
<element name="XMLA" type="cbl:XMLA"/>
</schema>

Figure 84. Example of the Generated Schema for COBOL Language Structures for XMLNameSelection Element

XsdSpec
Use this element to specify properties of the XML schema generated from the data structures.

These XML schemas can be used for validation by an XML transformation; for example, CICS 4.1
XMLTRANSFORM resource.
Note: XsdSpec CANNOT be specified with:
• “XsdSpecIn” on page 508
• “XsdSpecOut” on page 509

Contained by
“XseSpec” on page 511

Contains
None

Attributes
Table 129 on page 506 shows the attributes for XsdSpec.

Table 129. Attribute Specifications for XsdSpec

Fields Description
Specifies the name of the output file.
Attribute: fileName
Valid values: See Description The default value is: Data source file name concatenated with "X"
Required?: No
Default value: See Description

506 Developer for z/OS: Developing with Db2, CICS, and IMS
Table 129. Attribute Specifications for XsdSpec (continued)
Fields Description
Specifies the local namespace.
Attribute: localNamespace
Valid values: See Description Note: Request namespaces have no effect on the code generated in
Required?: No the converter.
Default value: See Description
The default value is: http://www.w3.org/2001/XMLSchema

Specifies whether to overwrite the output file if it exists.

Attribute: overwrite
Valid values: true | false
Required?: No
Default value: true

Specifies the target namespace.

Attribute: targetNamespace
Valid values: See Description The default value is: For a data source file name foo: http://
Required?: No www.fooI.com/schemas/fooIInterface
Default value: See Description

The value of this attribute directs the Batch processor to generate

Attribute: whitespace
XML Schemas and XML converter programs that support the three
Valid values: collapse | replace |
standard whitespace processing options in XML Schema: "preserve",
preserve | compat
"replace", and "collapse". Every element in the generated XML
Required?: No
Schema is assigned the value of this attribute for its whiteSpace
Default value: collapse
option.
To direct the Batch processor to generate XML Schemas and XML
converter programs that are compatible with releases prior to
version 7.5, specify the value "compat".

Specifies the global element name for the schema.

Attribute: xsdElemName
Valid values: See Description The default value is: Value of the nativeTypeName attribute in the
Required?: No message specification.
Default value: See Description

Specifies the xsd namespace.

Attribute: xsdNamespace
Valid values: See Description The default value is: Value of the nativeTypeName attribute in the
Required?: No message specification.
Default value: See Description

Specifies the xsd namespace prefix.

Attribute: xsdPrefix
Valid values: See Description
Required?: No
Default value: cbl

Example
Figure 85 on page 508 is an example of XseSpec element.

Developing web services and SOA with Enterprise Service Tools 507
 <XsdSpec fileName="sample.xsd" overwrite="true"
targetNamespace="http://www.DFH0CSTDI.com/schemas/DFH0CSTDIInterface"
xsdNamespace="http://www.w3.org/2001/XMLSchema"
localNamespace="http://www.DFH0CSTDI.com/schemas/DFH0CSTDIInterface"
xsdPrefix="cbl"
xsdElemName="dfhcommarea"/>

Figure 85. Example of XseSpec Element

XsdSpecIn
Use this element of the ServiceProperties.xml document to specify the generation options for the XML
schema that corresponds to the input language structure.

Contained by
“XseSpec” on page 511

Contains
None

Attributes
Table 130 on page 508 shows the attributes for XsdSpecIn.

Table 130. Attribute Specifications for XsdSpecIn

Fields Description
Specifies the name of the output file.
Attribute: fileName
Valid values: See Description The default value is: Data source file name concatenated with "I"
Required?: No
Default value: See Description

Specifies the local namespace.

Attribute: localNamespace
Valid values: See Description Note: Request namespaces have no effect on the code generated in
Required?: No the request converter.
Default value: See Description
The default value is: http://www.w3.org/2001/XMLSchema

Specifies whether to overwrite the output file if it exists.

Attribute: overwrite
Valid values: true | false
Required?: No
Default value: true

Specifies the target namespace.

Attribute: targetNamespace
Valid values: See Description The default value is: For a data source file name foo: http://
Required?: No www.fooI.com/schemas/fooIInterface
Default value: See Description

508 Developer for z/OS: Developing with Db2, CICS, and IMS
Table 130. Attribute Specifications for XsdSpecIn (continued)
Fields Description
The value of this attribute directs the Batch processor to generate
Attribute: whiteSpace
XML Schemas and XML converter programs that support the three
Valid values: collapse | replace |
standard whitespace processing options in XML Schema: "preserve",
preserve | compat
"replace", and "collapse". Every element in the generated XML
Required?: No
Schema is assigned the value of this attribute for its whiteSpace
Default value: collapse
option. The value of this attribute is ignored when XML converters are
being generated for the "Map and Existing Service Interface" scenario
since the setting in the mapped XML Schema must be assumed.
To direct the Batch processor to generate XML Schemas and XML
converter programs that are compatible with releases prior to
version 7.5, specify the value "compat".

Specifies the global element name for the schema.

Attribute: xsdElemName
Valid values: See Description The default value is: Value of the nativeTypeName attribute in the
Required?: No message specification.
Default value: See Description

Specifies the xsd namespace.

Attribute: xsdNamespace
Valid values: See Description The default value is: Value of the nativeTypeName attribute in the
Required?: No message specification.
Default value: See Description

Specifies the xsd namespace prefix.

Attribute: xsdPrefix
Valid values: See Description
Required?: No
Default value: cbl

Example

<XsdSpecIn fileName="DFH0CSTDI.xsd" overwrite="true"

targetNamespace="http://www.DFH0CSTDI.com/schemas/DFH0CSTDIInterface"
xsdNamespace="http://www.w3.org/2001/XMLSchema"
localNamespace="http://www.DFH0CSTDI.com/schemas/DFH0CSTDIInterface"
xsdPrefix="cbl"
xsdElemName="dfhcommarea"/>

XsdSpecOut
Use this element of the ServiceProperties.xml document to specify the generation options for the XML
schema that corresponds to the output language structure.

Note: If the Output and Input message specifications elsewhere in the same EISService specfication are
combined in a single InputOutputMessage, both request and response message definitions come from a
single COBOL source. Because of this, the XsdSpecOut schema specification for all attributes except the
fileName will be ignored for the response schema. The resulting external XSD file for XsdSpecOut in this
case will be identical to the XSD file resulting from XsdSpecIn. The types section of a resulting WSDL file
will only have one schema type definition (that will be defined by characteristics of the XsdSpecIn).
“XseSpec” on page 511

Contains
None

Developing web services and SOA with Enterprise Service Tools 509
 Attributes
Table 131 on page 510 shows the attributes for XsdSpecOut.

Table 131. Attribute Specifications for XsdSpecOut

Fields Description
Specifies the name of the output file.
Attribute: fileName
Valid values: See Description The default value is: Data source file name concatenated with "O"
Required?: No
Default value: See Description

Specifies the local namespace.

Attribute: localNamespace
Valid values: See Description Note: Request namespaces have no effect on the code generated in
Required?: No the request converter.
Default value: See Description
The default value is: http://www.w3.org/2001/XMLSchema

Specifies whether to overwrite the output file if it exists.

Attribute: overwrite
Valid values: true | false
Required?: No
Default value: true

Indicates whether or not to suppress generation of the response XML

Attribute: suppressGeneration
Schema file.
Valid values: true | false
Required?: No
Default value: false

Specifies the target namespace.

Attribute: targetNamespace
Valid values: See Description The default value is: For a data source file name foo: http://
Required?: No www.fooO.com/schemas/fooIInterface
Default value: See Description

The value of this attribute directs the Batch processor to generate

Attribute: whiteSpace
XML Schemas and XML converter programs that support the three
Valid values: collapse | replace |
standard whitespace processing options in XML Schema: "preserve",
preserve | compat
"replace", and "collapse". Every element in the generated XML
Required?: No
Schema is assigned the value of this attribute for its whiteSpace
Default value: collapse
option. The value of this attribute is ignored when XML converters are
being generated for the "Map and Existing Service Interface" scenario
since the setting in the mapped XML Schema must be assumed.
To direct the Batch processor to generate XML Schemas and XML
converter programs that are compatible with releases prior to
version 7.5, specify the value "compat".

Specifies the global element name for the schema.

Attribute: xsdElemName
Valid values: See Description The default value is: Value of the nativeTypeName attribute in the
Required?: No message specification.
Default value: See Description

Specifies the xsd namespace.

Attribute: xsdNamespace
Valid values: See Description The default value is: Value of the nativeTypeName attribute in the
Required?: No message specification.
Default value: See Description

510 Developer for z/OS: Developing with Db2, CICS, and IMS
Table 131. Attribute Specifications for XsdSpecOut (continued)
Fields Description
Specifies the xsd namespace prefix.
Attribute: xsdPrefix
Valid values: See Description
Required?: No
Default value: cbl

Example

<XsdSpecOut fileName="DFH0CSTDO.xsd" overwrite="true"

targetNamespace="http://www.DFH0CSTDO.com/schemas/DFH0CSTDOInterface"
xsdNamespace=http://www.w3.org/2001/XMLSchema
localNamespace=http://www.DFH0CSTDO.com/schemas/DFH0CSTDOInterface
xsdPrefix="cbl"
xsdElemName="dfhcommarea"/>

XseSpec
Use this element as the container for specifying generation options for the set of converters, driver, and
XSD files.

Contained by
“Operation” on page 469

Contains
“CorrelatorSpec” on page 447
“ConverterSpecIn” on page 445
“ConverterSpecOut” on page 446
“DriverSpec” on page 449
“XsdSpec” on page 506 (See Note)
“XsdSpecIn” on page 508 (See Note)
“XsdSpecOut” on page 509 (See Note)
Note: XseSpec can contain an “XsdSpec” on page 506 element. If XseSpec contains a “XsdSpec” on page
506 element, then XseSpec CANNOT contain the following:
• “XsdSpecIn” on page 508
• “XsdSpecOut” on page 509
If this restriction is not followed the results of the generation are unpredictable.

Attributes
None

Example
Figure 86 on page 511 is an example of XseSpec element.

Figure 86. Example of Xsespec Element

<XseSpec>
<DriverSpec fileName=""DFH0CSTDD.cbl" driverType="SOAP_FOR_CICS"
programName="XCNVD" businessPgmName="Ex01" />
<ConverterSpecIn fileName="DFH0CSTDI.cbl" overwrite="true" programName="XCNVI"/>
<ConverterSpecOut fileName="DFH0CSTDO.cbl" overwrite="true" programName="XCNVO"/>
<XsdSpecIn fileName="DFH0CSTDI.xsd" overwrite="true"
targetNamespace="http://www.DFH0CSTDI.com/schemas/DFH0CSTDIInterface"

Developing web services and SOA with Enterprise Service Tools 511
 xsdNamespace="http://www.w3.org/2001/XMLSchema"
localNamespace="http://www.DFH0CSTDI.com/schemas/DFH0CSTDIInterface"
xsdPrefix="cbl"
xsdElemName="dfhcommarea" />
<XsdSpecOut fileName="DFH0CSTDO.xsd" overwrite="true"
targetNamespace="http://www.DFH0CSTDO.com/schemas/DFH0CSTDOInterface"
xsdNamespace="http://www.w3.org/2001/XMLSchema"
localNamespace="http://www.DFH0CSTDO.com/schemas/DFH0CSTDOInterface"
xsdPrefix="cbl"
xsdElemName="dfhcommarea" />
</XseSpec>

ServiceSpecification.xml sample (EISService Element)

This topic is a sample of the ServiceSpecification.xml. for the the EISService Element

Example of ServiceSpecification.xml for the EISService Element

<?xml version="1.0" encoding="UTF-8"?>

<EISProject xmlns="http:///com/ibm/etools/xmlent/batch/emf/BatchProcessModel.ecore" name="CICSSample">
<!-- Use the ImportPropertyArray to override values from PlatformProperties.xml -->
<ImportPropertyArray type="Cobol">
<ImportProperty name="com.ibm.etools.cobol.COBOL_TRUNC" value="STD" />
<ImportProperty name="com.ibm.etools.cobol.COBOL_NSYMBOL" value="DBCS" />
<ImportProperty name="com.ibm.etools.cobol.COBOL_QUOTE" value="DOUBLE" />
</ImportPropertyArray>
<CodegenPropertyArray type="Cobol">
<CodegenProperty name="com.ibm.etools.xmlent.ui.GEN_PROG_NAME" value="XCNV"/>
<CodegenProperty name="com.ibm.etools.xmlent.ui.GEN_AUTH_NAME" value="WSED"/>
<CodegenProperty name="com.ibm.etools.xmlent.ui.GEN_IN_CP_LIST" value="1140"/>
<CodegenProperty name="com.ibm.etools.xmlent.ui.GEN_CP_LIST" value="1140"/>
<CodegenProperty name="com.ibm.etools.xmlent.ui.GEN_OUT_CP_LIST" value="1140"/>
<CodegenProperty name="com.ibm.etools.xmlent.ui.GEN_DEC_COMMA" value=" false"/>
<CodegenProperty name="com.ibm.etools.xmlent.ui.GEN_FLAT_GEN" value=" false"/>
</CodegenPropertyArray>
<EISService name="CustomerInfo" type="CICS"
targetNamespace="http://cics.sample"
generateConverters="true" generateSeparateXSD="false"
generateWSDL="true" >

<!-- Use the ConnectionPropertyArray to override values from PlatformProperties.xml -->

<ConnectionPropertyArray>
<ConnectionProperty name="connectionURI"
value="http://winmvsn0.cpit.hursley.ibm.com:
8888/CICS/XMLS/DFHWSDSH/ACTDSOAP" />
</ConnectionPropertyArray>

<ServicePropertyArray>
<ServiceProperty name="bindingName" value="myBinding" />
<ServiceProperty name="soapTransport"
value="http://schemas.xmlsoap.org/soap/http" />
<ServiceProperty name="soapBindingStyle" value="document" />
</ServicePropertyArray>

<Operation name="getCustomerInfo" type="REQUEST_RESPONSE">

<OperationPropertyArray>
<OperationProperty name="soapOpStyle" value="document" />
<OperationProperty name="soapBodyUse" value="literal" />
<OperationProperty name="soapAction" value="http://example.com/getCustomerInfo" />
</OperationPropertyArray>

<InputOutputMessage name="CustomerDetails" importDirectory="." importFile="DFH0ACTD.cbl"

nativeTypeName="DFHCOMMAREA">
<RedefinesArray>
<RedefineSelection redefine="name.info" useRedefinition="name.last-name"/>
<RedefineSelection redefine="address.zip-code" useRedefinition="province"/>
</RedefinesArray>
</InputOutputMessage>

<XseSpec>
<DriverSpec fileName=""DFH0CSTDD.cbl" driverType="IMS_SOAP"
programName="XCNVD" businessPgmName="Ex01" />
<ConverterSpecIn fileName="DFH0CSTDI.cbl" overwrite="true" programName="XCNVI"/>
<ConverterSpecOut fileName="DFH0CSTDO.cbl" overwrite="true" programName="XCNVO"/>
<XsdSpecIn fileName="DFH0CSTDI.xsd" overwrite="true"
targetNamespace="http://www.DFH0CSTDI.com/schemas/DFH0CSTDIInterface"
xsdNamespace="http://www.w3.org/2001/XMLSchema"

512 Developer for z/OS: Developing with Db2, CICS, and IMS
 localNamespace="http://www.DFH0CSTDI.com/schemas/DFH0CSTDIInterface"
xsdPrefix="cbl"
xsdElemName="dfhcommarea"
/>
<XsdSpecOut fileName="DFH0CSTDO.xsd"
overwrite="true"
targetNamespace="http://www.DFH0CSTDO.com/schemas/DFH0CSTDOInterface"
xsdNamespace="http://www.w3.org/2001/XMLSchema"
localNamespace="http://www.DFH0CSTDO.com/schemas/DFH0CSTDOInterface"
xsdPrefix="cbl"
xsdElemName="dfhcommarea"
/>
</XseSpec>
</Operation>
</EISService>
</EISProject>

Related references

“ServiceSpecification.xml” on page 443

“EISServiceImplementation” on page 455
“ServiceImplementationSpec” on page 478

Schema for ServiceSpecification.xml

The figure below is the schema for ServiceSpecification.xml:

---------------------------------------------------------------------------------------------------
<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
targetNamespace="http:///com/ibm/etools/xmlent/batch/emf/BatchProcessModel.ecore"
xmlns="http:///com/ibm/etools/xmlent/batch/emf/BatchProcessModel.ecore"
elementFormDefault="qualified">

<xsd:complexType name="LanguageStructureSpecType">
<xsd:attribute name="fileNamePrefix" use="optional">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:maxLength value="6" />
</xsd:restriction>
</xsd:simpleType>
</xsd:attribute>
<xsd:attribute name="overwrite" type="xsd:boolean" use="optional" />
<xsd:attribute name="suppressGeneration" type="xsd:boolean"
use="optional" />
<xsd:attribute name="fileContainer" type="xsd:string"
use="optional" />
</xsd:complexType>

<xsd:complexType name="MessageType">
<xsd:sequence>
<xsd:element maxOccurs="1" minOccurs="0" ref="RedefinesArray" />
<xsd:choice>
<xsd:element maxOccurs="1" minOccurs="0"
ref="ItemSelectionArray" />
<xsd:element maxOccurs="1" minOccurs="0"
ref="ItemExclusionArray" />
</xsd:choice>
<xsd:element maxOccurs="1" minOccurs="0" ref="XMLNamesArray" />
</xsd:sequence>
<xsd:attribute name="importDirectory" type="xsd:string"
use="optional" />
<xsd:attribute name="importFile" type="xsd:string" use="optional" />
<xsd:attribute name="name" type="xsd:string" use="optional" />
<xsd:attribute name="annotationsFile" type="xsd:string"
use="optional" />
<xsd:attribute name="commTypesFile" type="xsd:string"
use="optional" />
<xsd:attribute name="xmlEleName" type="xsd:string" use="optional" />
<xsd:attribute name="nativeTypeName" type="xsd:string"
use="optional" />
<xsd:attribute name="lowerBound" use="optional"
type="xsd:nonNegativeInteger" />
<xsd:attribute name="upperBound" use="optional"
type="xsd:nonNegativeInteger" />

Developing web services and SOA with Enterprise Service Tools 513
 <xsd:attribute name="mappingFile" use="optional" type="xsd:string" />
<xsd:attribute name="mappingDirectory" use="optional" type="xsd:string" />
</xsd:complexType>

<xsd:complexType name="XsdSpecType">
<xsd:attribute name="fileName" type="xsd:string" use="optional" />
<xsd:attribute name="localNamespace" type="xsd:string"
use="optional" />
<xsd:attribute name="overwrite" type="xsd:boolean" use="optional" />
<xsd:attribute name="targetNamespace" type="xsd:string"
use="optional" />
<xsd:attribute name="whiteSpace" use="optional">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:enumeration value="collapse" />
<xsd:enumeration value="replace" />
<xsd:enumeration value="preserve" />
<xsd:enumeration value="compat" />
</xsd:restriction>
</xsd:simpleType>
</xsd:attribute>
<xsd:attribute name="xsdElemName" type="xsd:string" use="optional" />
<xsd:attribute name="xsdNamespace" type="xsd:string"
use="optional" />
<xsd:attribute name="xsdPrefix" type="xsd:string" use="optional" />
<xsd:attribute name="suppressGeneration" type="xsd:boolean"
use="optional" />
<xsd:attribute name="fileContainer" type="xsd:string"
use="optional" />
<xsd:attribute name="remote" type="xsd:boolean"
use="optional" />
</xsd:complexType>

<xsd:complexType name="ConverterSpecType">
<xsd:attribute name="fileName" type="xsd:string" use="optional" />
<xsd:attribute name="overwrite" type="xsd:boolean" use="optional" />
<xsd:attribute name="programName" use="optional">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:maxLength value="8" />
</xsd:restriction>
</xsd:simpleType>
</xsd:attribute>
<xsd:attribute name="suppressGeneration" type="xsd:boolean"
use="optional" />
<xsd:attribute name="fileContainer" type="xsd:string"
use="optional" />
<xsd:attribute name="remote" type="xsd:boolean"
use="optional" />
</xsd:complexType>

<xsd:element name="ConnectionProperty">
<xsd:complexType>
<xsd:attribute name="name" type="xsd:string" use="required" />
<xsd:attribute name="value" type="xsd:string" use="required" />
</xsd:complexType>
</xsd:element>
<xsd:element name="ConnectionPropertyArray">
<xsd:complexType>
<xsd:sequence>
<xsd:element maxOccurs="unbounded" minOccurs="0"
ref="ConnectionProperty" />
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="CorrelatorSpec">
<xsd:complexType>
<xsd:attribute name="fileName" type="xsd:string" use="optional" />
<xsd:attribute name="fileContainer" type="xsd:string"
use="optional" />
<xsd:attribute name="overwrite" type="xsd:boolean" use="optional" />
<xsd:attribute name="soapAction" type="xsd:string" use="optional" />
<xsd:attribute name="adapterType" type="xsd:string"
use="optional" />
<xsd:attribute name="connectionBundleName" use="optional">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:maxLength value="20" />
</xsd:restriction>
</xsd:simpleType>
</xsd:attribute>

514 Developer for z/OS: Developing with Db2, CICS, and IMS
 <xsd:attribute name="calloutConnBundleName" use="optional">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:maxLength value="20" />
</xsd:restriction>
</xsd:simpleType>
</xsd:attribute>
<xsd:attribute name="calloutConnBundleNames" use="optional">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
</xsd:restriction>
</xsd:simpleType>
</xsd:attribute>
<xsd:attribute name="socketTimeout" type="xsd:nonNegativeInteger"
use="optional" />
<xsd:attribute name="executionTimeout" use="optional">
<xsd:simpleType>
<xsd:restriction base="xsd:nonNegativeInteger">
<xsd:maxInclusive value="3600000" />
</xsd:restriction>
</xsd:simpleType>
</xsd:attribute>
<xsd:attribute name="calloutWSTimeout" type="xsd:positiveInteger"
use="optional" />
<xsd:attribute name="inboundTPIPEName" type="xsd:string"
use="optional" />
<xsd:attribute name="ltermName" use="optional">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:maxLength value="8" />
</xsd:restriction>
</xsd:simpleType>
</xsd:attribute>
<xsd:attribute name="trancode" use="optional">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:maxLength value="8" />
</xsd:restriction>
</xsd:simpleType>
</xsd:attribute>
<xsd:attribute name="suppressGeneration" type="xsd:boolean"
use="optional" />
<xsd:attribute name="calloutURI" type="xsd:string" use="optional" />
<xsd:attribute name="remote" type="xsd:boolean"
use="optional" />
<xsd:attribute name="WSSecurity" use="optional">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:enumeration value="SAML11Token"/>
<xsd:enumeration value="SAML20Token"/>
<xsd:enumeration value="SAML11SignedTokenTrustAny"/>
<xsd:enumeration value="SAML11SignedTokenTrustOne"/>
<xsd:enumeration value="SAML20SignedTokenTrustAny"/>
<xsd:enumeration value="SAML20SignedTokenTrustOne"/>
<xsd:enumeration value="UserNameToken"/>
<xsd:enumeration value=""/>
</xsd:restriction>
</xsd:simpleType>
</xsd:attribute>
<xsd:attribute name="calloutWSSecurity" use="optional">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:enumeration value="SAML11Token"/>
<xsd:enumeration value="SAML20Token"/>
<xsd:enumeration value=""/>
</xsd:restriction>
</xsd:simpleType>
</xsd:attribute>
<xsd:attribute name="calloutSendOnlyWithACK" type="xsd:boolean"
use="optional"/>
</xsd:complexType>
</xsd:element>
<xsd:element name="WSBindSpec">
<xsd:complexType>
<xsd:attribute name="fileName" type="xsd:string" use="optional" />
<xsd:attribute name="overwrite" type="xsd:boolean" use="optional" />
<xsd:attribute name="pgmint" type="xsd:int" use="optional" />
<xsd:attribute name="contid" type="xsd:string" use="optional" />
<xsd:attribute name="uri" type="xsd:string" use="optional" />
<xsd:attribute name="ccsid" type="xsd:string" use="optional" />
<xsd:attribute name="mappingLevel" type="xsd:string"
use="optional" />

Developing web services and SOA with Enterprise Service Tools 515
 <xsd:attribute name="suppressGeneration" type="xsd:boolean"
use="optional" />
<xsd:attribute name="minimumRuntimeLevel" type="xsd:string"
use="optional" />
<xsd:attribute name="userid" type="xsd:string" use="optional" />
<xsd:attribute name="transaction" type="xsd:string"
use="optional" />
<xsd:attribute name="charVarying" use="optional">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:enumeration value="NO" />
<xsd:enumeration value="NULL" />
<xsd:enumeration value="COLLAPSE" />
<xsd:enumeration value="BINARY" />
<xsd:enumeration value="YES" />
</xsd:restriction>
</xsd:simpleType>
</xsd:attribute>
<xsd:attribute name="charVaryingLimit" use="optional">
<xsd:simpleType>
<xsd:restriction base="xsd:nonNegativeInteger">
<xsd:maxInclusive value="32767" />
</xsd:restriction>
</xsd:simpleType>
</xsd:attribute>
<xsd:attribute name="defaultCharMaxLength" use="optional">
<xsd:simpleType>
<xsd:restriction base="xsd:positiveInteger">
<xsd:maxInclusive value="2147483647" />
</xsd:restriction>
</xsd:simpleType>
</xsd:attribute>
<xsd:attribute name="charMultiplier" use="optional">
<xsd:simpleType>
<xsd:restriction base="xsd:positiveInteger">
<xsd:maxInclusive value="2147483647" />
</xsd:restriction>
</xsd:simpleType>
</xsd:attribute>
<xsd:attribute name="businessPgmName" type="xsd:string"
use="optional" />
<xsd:attribute name="vendorConverterName" type="xsd:string"
use="optional" />
<xsd:attribute name="xmlOnly" type="xsd:boolean" use="optional" />
<xsd:attribute name="logFileName" type="xsd:string"
use="optional" />
<xsd:attribute name="fileContainer" type="xsd:string"
use="optional" />
<xsd:attribute name="dataTruncation" use="optional">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:enumeration value="DISABLED" />
<xsd:enumeration value="ENABLED" />
</xsd:restriction>
</xsd:simpleType>
</xsd:attribute>
<xsd:attribute name="nameTruncation" use="optional">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:enumeration value="RIGHT" />
<xsd:enumeration value="LEFT" />
</xsd:restriction>
</xsd:simpleType>
</xsd:attribute>
<xsd:attribute name="dateTime" type="xsd:string" use="optional" />
<xsd:attribute name="inlineMaxOccursLimit" use="optional">
<xsd:simpleType>
<xsd:restriction base="xsd:nonNegativeInteger">
<xsd:maxInclusive value="32767" />
</xsd:restriction>
</xsd:simpleType>
</xsd:attribute>
<xsd:attribute name="requestChannel" type="xsd:string"
use="optional" />
<xsd:attribute name="responseChannel" type="xsd:string"
use="optional" />
<xsd:attribute name="service" type="xsd:string" use="optional" />
<xsd:attribute name="synconreturn" use="optional">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:enumeration value="NO" />
<xsd:enumeration value="YES" />

516 Developer for z/OS: Developing with Db2, CICS, and IMS
 </xsd:restriction>
</xsd:simpleType>
</xsd:attribute>
<xsd:attribute name="arithExtend" use="optional">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:enumeration value="NO" />
<xsd:enumeration value="YES" />
</xsd:restriction>
</xsd:simpleType>
</xsd:attribute>
<xsd:attribute name="remote" type="xsd:boolean"
use="optional" />
<xsd:attribute name="pipeline" type="xsd:string"
use="optional" />
<xsd:attribute name="wsdlloc" type="xsd:string"
use="optional" />
<xsd:attribute name="jsonReqSchema" type="xsd:string"
use="optional" />
<xsd:attribute name="jsonRespSchema" type="xsd:string"
use="optional" />
<xsd:attribute name="jsonSchemaRest" type="xsd:string"
use="optional" />
<xsd:attribute name="httpMethods" type="xsd:string"
use="optional" />
<xsd:attribute name="mappingOverrides" type="xsd:string"
use="optional" />
</xsd:complexType>
</xsd:element>
<xsd:element name="XSDBindSpec">
<xsd:complexType>
<xsd:attribute name="bundle" type="xsd:string" use="optional" />
<xsd:attribute name="ccsid" type="xsd:string" use="optional" />
<xsd:attribute name="charVarying" use="optional">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:enumeration value="NO" />
<xsd:enumeration value="NULL" />
<xsd:enumeration value="COLLAPSE" />
<xsd:enumeration value="BINARY" />
<xsd:enumeration value="YES" />
</xsd:restriction>
</xsd:simpleType>
</xsd:attribute>
<xsd:attribute name="charVaryingLimit" use="optional">
<xsd:simpleType>
<xsd:restriction base="xsd:nonNegativeInteger">
<xsd:maxInclusive value="32767" />
</xsd:restriction>
</xsd:simpleType>
</xsd:attribute>
<xsd:attribute name="defaultCharMaxLength" use="optional">
<xsd:simpleType>
<xsd:restriction base="xsd:positiveInteger">
<xsd:maxInclusive value="2147483647" />
</xsd:restriction>
</xsd:simpleType>
</xsd:attribute>
<xsd:attribute name="charMultiplier" use="optional">
<xsd:simpleType>
<xsd:restriction base="xsd:positiveInteger">
<xsd:maxInclusive value="2147483647" />
</xsd:restriction>
</xsd:simpleType>
</xsd:attribute>
<xsd:attribute name="fileName" type="xsd:string" use="optional" />
<xsd:attribute name="inlineMaxOccursLimit" use="optional">
<xsd:simpleType>
<xsd:restriction base="xsd:nonNegativeInteger">
<xsd:maxInclusive value="32767" />
</xsd:restriction>
</xsd:simpleType>
</xsd:attribute>
<xsd:attribute name="logFileName" type="xsd:string"
use="optional" />
<xsd:attribute name="mappingLevel" type="xsd:string"
use="optional" />
<xsd:attribute name="minimumRuntimeLevel" type="xsd:string"
use="optional" />
<xsd:attribute name="nameTruncation" use="optional">
<xsd:simpleType>
<xsd:restriction base="xsd:string">

Developing web services and SOA with Enterprise Service Tools 517
 <xsd:enumeration value="RIGHT" />
<xsd:enumeration value="LEFT" />
</xsd:restriction>
</xsd:simpleType>
</xsd:attribute>
<xsd:attribute name="vendorConverterName" type="xsd:string"
use="optional" />
<xsd:attribute name="dateTime" type="xsd:string" use="optional" />
<xsd:attribute name="dataTruncation" use="optional">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:enumeration value="DISABLED" />
<xsd:enumeration value="ENABLED" />
</xsd:restriction>
</xsd:simpleType>
</xsd:attribute>
<xsd:attribute name="fileContainer" type="xsd:string"
use="optional" />
<xsd:attribute name="arithExtend" use="optional">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:enumeration value="NO" />
<xsd:enumeration value="YES" />
</xsd:restriction>
</xsd:simpleType>
</xsd:attribute>
<xsd:attribute name="remote" type="xsd:boolean"
use="optional" />
<xsd:attribute name="mappingOverrides" type="xsd:string" use="optional" />
</xsd:complexType>
</xsd:element>
<xsd:element name="DriverSpec">
<xsd:complexType>
<xsd:attribute name="driverType" use="optional">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:enumeration value="BATCH" />
<xsd:enumeration value="IMS_SOAP" />
<xsd:enumeration value="IMS_INFO_20" />
<xsd:enumeration value="WEB_SERVICES_CICS" />
<xsd:enumeration value="XML_TRANSFORM_CICS" />
</xsd:restriction>
</xsd:simpleType>
</xsd:attribute>
<xsd:attribute name="fileName" type="xsd:string" use="optional" />
<xsd:attribute name="overwrite" type="xsd:boolean" use="optional" />
<xsd:attribute name="programName" use="optional">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:maxLength value="8" />
</xsd:restriction>
</xsd:simpleType>
</xsd:attribute>
<xsd:attribute name="businessPgmName" use="optional">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:maxLength value="8" />
</xsd:restriction>
</xsd:simpleType>
</xsd:attribute>
<xsd:attribute name="suppressGeneration" type="xsd:boolean"
use="optional" />
<xsd:attribute name="fileContainer" type="xsd:string"
use="optional" />
<xsd:attribute name="fileNamePrefix" use="optional">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:maxLength value="7" />
</xsd:restriction>
</xsd:simpleType>
</xsd:attribute>
<xsd:attribute name="xmlContainerName" use="optional">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:maxLength value="16" />
</xsd:restriction>
</xsd:simpleType>
</xsd:attribute>
<xsd:attribute name="dataContainerName" use="optional">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:maxLength value="16" />

518 Developer for z/OS: Developing with Db2, CICS, and IMS
 </xsd:restriction>
</xsd:simpleType>
</xsd:attribute>
<xsd:attribute name="remote" type="xsd:boolean"
use="optional" />
</xsd:complexType>
</xsd:element>
<xsd:element name="EISProject">
<xsd:complexType>
<xsd:sequence>
<xsd:element maxOccurs="1" minOccurs="0"
ref="ImportPropertyArray" />
<xsd:element maxOccurs="1" minOccurs="0"
ref="CodegenPropertyArray" />
<xsd:choice>
<xsd:element maxOccurs="unbounded" minOccurs="0"
ref="EISService" />
<xsd:element maxOccurs="unbounded" minOccurs="0"
ref="EISServiceImplementation" />
</xsd:choice>
</xsd:sequence>
<xsd:attribute name="name" type="xsd:string" use="optional" />
</xsd:complexType>
</xsd:element>
<xsd:element name="EISService">
<xsd:complexType>
<xsd:all>
<xsd:element maxOccurs="1" minOccurs="0"
ref="ConnectionPropertyArray" />
<xsd:element maxOccurs="1" minOccurs="0" ref="Operation" />
<xsd:element minOccurs="0" ref="RouterSpec" />
<xsd:element minOccurs="0" ref="WSBindSpec" />
<xsd:element maxOccurs="1" minOccurs="0"
ref="ServicePropertyArray" />
</xsd:all>
<xsd:attribute name="generateConverters" type="xsd:boolean"
use="optional" />
<xsd:attribute name="generateSeparateXSD" type="xsd:boolean"
use="optional" />
<xsd:attribute name="generateWSDL" type="xsd:boolean"
use="optional" />
<xsd:attribute name="name" type="xsd:string" use="optional" />
<xsd:attribute name="targetNamespace" type="xsd:string"
use="optional" />
<xsd:attribute name="type" use="optional">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:enumeration value="CICS" />
<xsd:enumeration value="IMS" />
</xsd:restriction>
</xsd:simpleType>
</xsd:attribute>
<xsd:attribute name="targetFilesURI" type="xsd:string"
use="optional" />
<xsd:attribute name="fileContainer" type="xsd:string"
use="optional" />
<xsd:attribute name="targetNameSpace" type="xsd:string"
use="optional" />
</xsd:complexType>
</xsd:element>
<xsd:element name="ImportProperty">
<xsd:complexType>
<xsd:attribute name="name" type="xsd:string" use="required" />
<xsd:attribute name="value" type="xsd:string" use="required" />
</xsd:complexType>
</xsd:element>
<xsd:element name="ImportPropertyArray">
<xsd:complexType>
<xsd:sequence>
<xsd:element maxOccurs="unbounded" minOccurs="0"
ref="ImportProperty" />
</xsd:sequence>
<xsd:attribute name="type" type="xsd:string" use="optional" />
</xsd:complexType>
</xsd:element>
<xsd:element name="ServiceProperty">
<xsd:complexType>
<xsd:attribute name="name" type="xsd:string" use="required" />
<xsd:attribute name="value" type="xsd:string" use="required" />
</xsd:complexType>
</xsd:element>
<xsd:element name="ServicePropertyArray">

Developing web services and SOA with Enterprise Service Tools 519
 <xsd:complexType>
<xsd:sequence>
<xsd:element maxOccurs="unbounded" minOccurs="0"
ref="ServiceProperty" />
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="CodegenProperty">
<xsd:complexType>
<xsd:attribute name="name" type="xsd:string" use="required" />
<xsd:attribute name="value" type="xsd:string" use="required" />
</xsd:complexType>
</xsd:element>
<xsd:element name="CodegenPropertyArray">
<xsd:complexType>
<xsd:sequence>
<xsd:element maxOccurs="unbounded" minOccurs="0"
ref="CodegenProperty" />
</xsd:sequence>
<xsd:attribute name="type" type="xsd:string" use="optional" />
</xsd:complexType>
</xsd:element>
<xsd:element name="InputOutputMessage">
<xsd:complexType>
<xsd:sequence>
<xsd:element maxOccurs="1" minOccurs="0" ref="RedefinesArray" />
<xsd:choice>
<xsd:element maxOccurs="1" minOccurs="0"
ref="ItemSelectionArray" />
<xsd:element maxOccurs="1" minOccurs="0"
ref="ItemExclusionArray" />
</xsd:choice>
<xsd:element maxOccurs="1" minOccurs="0" ref="XMLNamesArray" />
</xsd:sequence>
<xsd:attribute name="importDirectory" type="xsd:string"
use="optional" />
<xsd:attribute name="importFile" type="xsd:string" use="optional" />
<xsd:attribute name="name" type="xsd:string" use="optional" />
<xsd:attribute name="nativeTypeName" type="xsd:string"
use="optional" />
</xsd:complexType>
</xsd:element>
<xsd:element name="ItemSelection">
<xsd:complexType>
<xsd:attribute name="itemName" type="xsd:string" use="required" />
<xsd:attribute name="optional" type="xsd:string" use="optional" />
</xsd:complexType>
</xsd:element>
<xsd:element name="ItemExclude">
<xsd:complexType>
<xsd:attribute name="itemName" type="xsd:string" use="required" />
</xsd:complexType>
</xsd:element>
<xsd:element name="ItemSelectionArray">
<xsd:complexType>
<xsd:sequence>
<xsd:element maxOccurs="unbounded" minOccurs="1"
ref="ItemSelection" />
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="ItemExclusionArray">
<xsd:complexType>
<xsd:sequence>
<xsd:element maxOccurs="unbounded" minOccurs="1"
ref="ItemExclude" />
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="Operation">
<xsd:complexType>
<xsd:sequence>
<xsd:element maxOccurs="1" minOccurs="0"
ref="OperationPropertyArray" />
<xsd:choice>
<xsd:sequence>
<xsd:element ref="InputOutputMessage" maxOccurs="1"
minOccurs="0" />
</xsd:sequence>
<xsd:choice maxOccurs="unbounded">
<xsd:sequence>
<xsd:element name="InputMessage" maxOccurs="1"

520 Developer for z/OS: Developing with Db2, CICS, and IMS
 minOccurs="0" type="MessageType" />
<xsd:element name="OutputMessage" maxOccurs="1"
minOccurs="0" type="MessageType" />
</xsd:sequence>
</xsd:choice>
</xsd:choice>
<xsd:element maxOccurs="1" minOccurs="0" ref="XseSpec" />
<xsd:element maxOccurs="1" minOccurs="0" name="MessageSpec"
type="MessageType" />
</xsd:sequence>
<xsd:attribute name="name" type="xsd:string" use="optional" />
<xsd:attribute name="type" use="optional">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:enumeration value="REQUEST_RESPONSE" />
<xsd:enumeration value="SOLICIT_RESPONSE" />
<xsd:enumeration value="ONE_WAY" />
<xsd:enumeration value="NOTIFICATION" />
</xsd:restriction>
</xsd:simpleType>
</xsd:attribute>
</xsd:complexType>
</xsd:element>
<xsd:element name="OperationProperty">
<xsd:complexType>
<xsd:attribute name="name" type="xsd:string" use="required" />
<xsd:attribute name="value" type="xsd:string" use="required" />
</xsd:complexType>
</xsd:element>
<xsd:element name="OperationPropertyArray">
<xsd:complexType>
<xsd:sequence>
<xsd:element maxOccurs="unbounded" minOccurs="0"
ref="OperationProperty" />
</xsd:sequence>
</xsd:complexType>
</xsd:element>

<xsd:element name="RedefineSelection">
<xsd:complexType>
<xsd:attribute name="redefine" type="xsd:string" use="required" />
<xsd:attribute name="useRedefinition" type="xsd:string"
use="required" />
</xsd:complexType>
</xsd:element>
<xsd:element name="RedefinesArray">
<xsd:complexType>
<xsd:sequence>
<xsd:element maxOccurs="unbounded" minOccurs="1"
ref="RedefineSelection" />
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="XseSpec">
<xsd:complexType>
<xsd:all>
<xsd:element maxOccurs="1" minOccurs="0" ref="DriverSpec" />
<xsd:element maxOccurs="1" minOccurs="0" name="ConverterSpecIn"
type="ConverterSpecType"/>
<xsd:element maxOccurs="1" minOccurs="0" name="ConverterSpecOut"
type="ConverterSpecType"/>
<xsd:element maxOccurs="1" minOccurs="0" name="XsdSpecIn"
type="XsdSpecType" />
<xsd:element maxOccurs="1" minOccurs="0" name="XsdSpecOut"
type="XsdSpecType" />
<xsd:element maxOccurs="1" minOccurs="0" name="XsdSpec"
type="XsdSpecType" />
<xsd:element minOccurs="0" maxOccurs="1" name="DFDLSpecIn"
type="XsdSpecType" />
<xsd:element minOccurs="0" maxOccurs="1" name="DFDLSpecOut"
type="XsdSpecType" />
<xsd:element maxOccurs="1" minOccurs="0" ref="CorrelatorSpec" />
<xsd:element maxOccurs="1" minOccurs="0" ref="WSBindSpec" />
<xsd:element maxOccurs="1" minOccurs="0" ref="XSDBindSpec" />
<xsd:element maxOccurs="1" minOccurs="0"
ref="CICSDeploymentSpec" />
</xsd:all>
</xsd:complexType>
</xsd:element>
<xsd:element name="XMLNameSelection">
<xsd:complexType>
<xsd:attribute name="itemName" type="xsd:string" use="required" />

Developing web services and SOA with Enterprise Service Tools 521
 <xsd:attribute name="xmlName" type="xsd:string" use="required" />
</xsd:complexType>
</xsd:element>
<xsd:element name="XMLNamesArray">
<xsd:complexType>
<xsd:sequence>
<xsd:element maxOccurs="unbounded" minOccurs="1"
ref="XMLNameSelection" />
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="RouterSpec">
<xsd:complexType>
<xsd:attribute name="type" use="optional">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:enumeration value="WEB_SERVICES_CICS" />
</xsd:restriction>
</xsd:simpleType>
</xsd:attribute>
<xsd:attribute name="fileName" use="optional">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<!-- It is set to 12 as it can include file extension (ex: .cbl) -->
<xsd:maxLength value="12" />
</xsd:restriction>
</xsd:simpleType>
</xsd:attribute>
<xsd:attribute name="overwrite" type="xsd:boolean" use="optional" />
<xsd:attribute name="programName" use="optional">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:maxLength value="8" />
</xsd:restriction>
</xsd:simpleType>
</xsd:attribute>
<xsd:attribute name="suppressGeneration" type="xsd:boolean"
use="optional" />
<xsd:attribute name="remote" type="xsd:boolean"
use="optional" />
</xsd:complexType>
</xsd:element>
<xsd:element name="EISServiceImplementation">
<xsd:complexType>
<xsd:all>
<xsd:element maxOccurs="1" minOccurs="0"
ref="ServicePropertyArray" />
<xsd:element maxOccurs="1" minOccurs="0"
ref="ConnectionPropertyArray" />
<xsd:element ref="ServiceImplementationSpec" />
</xsd:all>
<xsd:attribute name="runtime" use="optional">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:enumeration value="WEB_SERVICES_CICS" />
<xsd:enumeration value="IMS_SOAP_GATEWAY" />
<xsd:enumeration value="XML_TRANSFORM_CICS" />
<xsd:enumeration value="BATCH" />
<xsd:enumeration value="JSON_SERVICES_CICS" />
</xsd:restriction>
</xsd:simpleType>
</xsd:attribute>
<xsd:attribute name="type" use="optional">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:enumeration value="SERVICE_PROVIDER" />
<xsd:enumeration value="SERVICE_REQUESTOR" />
</xsd:restriction>
</xsd:simpleType>
</xsd:attribute>
<xsd:attribute name="interactionPattern" use="optional">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:enumeration value="REQUEST_RESPONSE" />
<xsd:enumeration value="RESTFUL" />
</xsd:restriction>
</xsd:simpleType>
</xsd:attribute>
</xsd:complexType>
</xsd:element>
<xsd:element name="ServiceImplementationSpec">
<xsd:complexType>

522 Developer for z/OS: Developing with Db2, CICS, and IMS
 <xsd:all>
<xsd:element maxOccurs="1" minOccurs="0"
ref="OperationSelectionArray" />
<xsd:element maxOccurs="1" minOccurs="0"
name="LanguageStructureSpecIn" type="LanguageStructureSpecType" />
<xsd:element maxOccurs="1" minOccurs="0"
name="LanguageStructureSpecOut" type="LanguageStructureSpecType" />
<xsd:element maxOccurs="1" minOccurs="0"
name="LanguageStructureSpec" type="LanguageStructureSpecType" />
<xsd:element maxOccurs="1" minOccurs="0"
ref="ApplicationTemplateSpec" />
<xsd:element maxOccurs="1" minOccurs="0" ref="WSDL2ELSSpec" />
<xsd:element maxOccurs="1" minOccurs="0" ref="WSBindSpec" />
<xsd:element maxOccurs="1" minOccurs="0" ref="XSDBindSpec" />
<xsd:element maxOccurs="1" minOccurs="0"
ref="CICSDeploymentSpec" />
<xsd:element maxOccurs="1" minOccurs="0" ref="CorrelatorSpec" />
<xsd:element maxOccurs="1" minOccurs="0" ref="DriverSpec" />
<xsd:element maxOccurs="1" minOccurs="0"
ref="ElementSelectionArray" />
<xsd:element maxOccurs="1" minOccurs="0"
ref="TypeSelectionArray" />
</xsd:all>
<xsd:attribute name="importDirectory" type="xsd:string"
use="optional" />
<xsd:attribute name="importFile" type="xsd:string" use="required" />
<xsd:attribute name="wsdlPortName" type="xsd:string" />
<xsd:attribute name="wsdlServiceName" type="xsd:string" />
</xsd:complexType>
</xsd:element>
<xsd:element name="OperationSelectionArray">
<xsd:complexType>
<xsd:sequence>
<xsd:element maxOccurs="unbounded" minOccurs="1"
ref="OperationSelection" />
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="OperationSelection">
<xsd:complexType>
<xsd:attribute name="operationName" type="xsd:string"
use="required" />
</xsd:complexType>
</xsd:element>
<xsd:element name="ApplicationTemplateSpec">
<xsd:complexType>
<xsd:attribute name="fileName" use="optional">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<!-- It is set to 12 as it can include file extension (ex: .cbl) -->
<xsd:maxLength value="12" />
</xsd:restriction>
</xsd:simpleType>
</xsd:attribute>
<xsd:attribute name="overwrite" type="xsd:boolean" use="optional" />
<xsd:attribute name="programName" use="optional">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:maxLength value="8" />
</xsd:restriction>
</xsd:simpleType>
</xsd:attribute>
<xsd:attribute name="suppressGeneration" type="xsd:boolean"
use="optional" />
<xsd:attribute name="fileContainer" type="xsd:string"
use="optional" />
<xsd:attribute name="remote" type="xsd:boolean"
use="optional" />
</xsd:complexType>
</xsd:element>

<xsd:element name="CICSDeploymentSpec">
<xsd:complexType>
<xsd:attribute name="fileName" type="xsd:string" use="optional" />
<xsd:attribute name="suppressGeneration" type="xsd:boolean"
use="optional" />
<xsd:attribute name="fileContainer" type="xsd:string"
use="optional" />
<xsd:attribute name="uploadWSBind" type="xsd:string"
use="optional" />
<xsd:attribute name="pickupDirectory" type="xsd:string"
use="optional" />

Developing web services and SOA with Enterprise Service Tools 523
 <xsd:attribute name="pipeline" type="xsd:string"
use="optional" />
<xsd:attribute name="region" type="xsd:string"
use="optional" />
<xsd:attribute name="userName" type="xsd:string"
use="optional" />
<xsd:attribute name="remote" type="xsd:boolean"
use="optional" />
</xsd:complexType>
</xsd:element>

<xsd:element name="WSDL2ELSSpec">
<xsd:complexType>
<xsd:attribute name="defaultCharMaxLength" use="optional">
<xsd:simpleType>
<xsd:restriction base="xsd:positiveInteger">
<xsd:maxInclusive value="32767" />
</xsd:restriction>
</xsd:simpleType>
</xsd:attribute>
<xsd:attribute name="defaultBase64BinaryLength" type="xsd:positiveInteger"
use="optional" />
<xsd:attribute name="defaultTotalDigits" use="optional">
<xsd:simpleType>
<xsd:restriction base="xsd:positiveInteger">
<xsd:maxInclusive value="31" />
</xsd:restriction>
</xsd:simpleType>
</xsd:attribute>
<xsd:attribute name="defaultFractionDigits" use="optional">
<xsd:simpleType>
<xsd:restriction base="xsd:nonNegativeInteger">
<xsd:maxInclusive value="31" />
</xsd:restriction>
</xsd:simpleType>
</xsd:attribute>
<xsd:attribute name="defaultDateTimeLength" use="optional">
<xsd:simpleType>
<xsd:restriction base="xsd:positiveInteger">
<xsd:maxInclusive value="32767" />
</xsd:restriction>
</xsd:simpleType>
</xsd:attribute>
<xsd:attribute name="fileContainer" type="xsd:string"
use="optional" />
<xsd:attribute name="inlineMaxOccursLimit" use="optional">
<xsd:simpleType>
<xsd:restriction base="xsd:positiveInteger">
<xsd:maxInclusive value="2147483647" />
</xsd:restriction>
</xsd:simpleType>
</xsd:attribute>
<xsd:attribute name="inlineStringLengthLimit" use="optional">
<xsd:simpleType>
<xsd:restriction base="xsd:positiveInteger">
<xsd:maxInclusive value="32767" />
</xsd:restriction>
</xsd:simpleType>
</xsd:attribute>
<xsd:attribute name="defaultMaxOccursLimit" use="optional">
<xsd:simpleType>
<xsd:restriction base="xsd:positiveInteger">
<xsd:minInclusive value="1" />
<xsd:maxInclusive value="134217727" />
</xsd:restriction>
</xsd:simpleType>
</xsd:attribute>
<xsd:attribute name="languageFileName" type="xsd:string"
use="optional" />
<xsd:attribute name="languageNameLimit" use="optional">
<xsd:simpleType>
<xsd:restriction base="xsd:positiveInteger">
<xsd:maxInclusive value="100" />
</xsd:restriction>
</xsd:simpleType>
</xsd:attribute>
<xsd:attribute name="suppressCountFields" type="xsd:boolean"
use="optional"/>
<xsd:attribute name="suppressStructureComments" type="xsd:boolean"
use="optional"/>
<xsd:attribute name="suppressPresenceFields" type="xsd:boolean"
use="optional"/>

524 Developer for z/OS: Developing with Db2, CICS, and IMS
 <xsd:attribute name="logFileName" type="xsd:string"
use="optional" />
<xsd:attribute name="mappingDirectory" type="xsd:string"
use="optional" />
<xsd:attribute name="metadataFileName" type="xsd:string"
use="optional" />
</xsd:complexType>
</xsd:element>
<xsd:element name="ElementSelectionArray">
<xsd:complexType>
<xsd:sequence>
<xsd:element maxOccurs="unbounded" minOccurs="0"
ref="ElementSelection" />
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="ElementSelection">
<xsd:complexType>
<xsd:attribute name="name" type="xsd:string" use="required" />
</xsd:complexType>
</xsd:element>
<xsd:element name="TypeSelectionArray">
<xsd:complexType>
<xsd:sequence>
<xsd:element maxOccurs="unbounded" minOccurs="0"
ref="TypeSelection" />
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="TypeSelection">
<xsd:complexType>
<xsd:attribute name="name" type="xsd:string" use="required" />
</xsd:complexType>
</xsd:element>
</xsd:schema>

---------------------------------------------------------------------------------------------------

Figure 87. Example of Schema for ServiceSpecification.xml

Related references

“ServiceSpecification.xml” on page 443

Logging syntax errors detected in COBOL input files

This topic describes an option that causes the Enterprise Service Tools source code generator to validate
the syntax of your input COBOL source file and its included files, and, if any syntax errors are detected, to
log the appropriate COBOL error information in a XML data structure that is stored in an XML file whose
file path you specify when you enable this option. This option is available only when you generate a Web
service using the bottom-up method and using the batch processor in a single-service project.
This option is available in the command-line batch processor by specifying the value
com.ibm.etools.xmlent.ui.GEN_ERROR_FEEDBACK_FILE_PATH for the name attribute in a
CodeGenProperty element (see “CodegenProperty” on page 422).
The following block of XML text shows the XML DTD for the structure in which the Enterprise Service Tools
source code generator stores the COBOL syntax error information:

<?xml version="1.0" encoding="UTF-8"?>

<!ELEMENT BUILD (PACKAGE)*>
<!ELEMENT PACKAGE (FILEREFERENCETABLE,(MESSAGE)*)>
<!ELEMENT FILEREFERENCETABLE (FILECOUNT,FILE+)>
<!ELEMENT MESSAGE (MESSAGENUMBER,MESSAGETEXT,MESSAGELINE?,MESSAGEFILE?)>
<!ELEMENT FILE (FILENUMBER,FILENAME,INCLUDEDFROMFILE?,INCLUDEDONLINE?)>
<!ELEMENT MESSAGENUMBER (#PCDATA)>
<!ELEMENT MESSAGELINE (#PCDATA)>
<!ELEMENT MESSAGEFILE (#PCDATA)>
<!ELEMENT MESSAGETEXT (#PCDATA)>
<!ELEMENT FILECOUNT (#PCDATA)>
<!ELEMENT FILENUMBER (#PCDATA)>
<!ELEMENT FILENAME (#PCDATA)>
<!ELEMENT INCLUDEDFROMFILE (#PCDATA)> <!-- NOT GENERATED!! -->
<!ELEMENT INCLUDEDONLINE (#PCDATA)> <!-- NOT GENERATED!! -->

Developing web services and SOA with Enterprise Service Tools 525
 Note: The generated error information does not generate the last two XML elements listed shown:

<!ELEMENT INCLUDEDFROMFILE (#PCDATA)> <!-- NOT GENERATED!! -->

<!ELEMENT INCLUDEDONLINE (#PCDATA)> <!-- NOT GENERATED!! -->

The following is a sample XML file generated using the XML DTD previously described.

<?xml version="1.0" encoding="UTF-8"?>

<BUILD>
<PACKAGE>
<FILEREFERENCETABLE>
<FILECOUNT>1</FILECOUNT>
<FILE>
<FILENUMBER>0</FILENUMBER>
<FILENAME>c:\mycobol\MYFILE_01.cbl</FILENAME>
</FILE>
</FILEREFERENCETABLE>
<MESSAGE>
<MESSAGENUMBER>IGYPA3063-S</MESSAGENUMBER>
<MESSAGETEXT>"CALL" or "CANCEL" identifier "CALLDN (ALPHANUMERIC-EDITED)"
was not alphanumeric, zoned decimal nor alphabetic. The statement was
discarded.</MESSAGETEXT>
<MESSAGELINE>228</MESSAGELINE>
<MESSAGEFILE>0</MESSAGEFILE>
</MESSAGE>
</PACKAGE>
</BUILD>

The following table describes the elements in the XML DTD:

Element: Description:
FILEREFERENCETABLE This element contains a description of each source file in which a COBOL syntax
has occurred.
FILECOUNT This element specifies the number of files in the FILEREFERENCETABLE element.
FILE This element describes one file in the FILEREFERENCETABLE element.
FILENUMBER This element specifies an integer identifier for the file being described in a FILE
element.
FILENAME This element specifies the location of the file being described in a FILE element.
MESSAGE This element describes a COBOL syntax error that was encountered in the source
file.
MESSAGENUMBER This element contains the message number of the syntax error being described in a
MESSAGE element.
MESSAGETEXT This element contains the message text of the syntax error being described in a
MESSAGE element.
MESSAGELINE This element contains the number of the line in which the syntax error being
described was detected.
MESSAGEFILE This element contains the identifying file number of the COBOL source file in which
the syntax error being described was detected. This number - an integer - is the
identifying file number that was specified for this file in the FILENUMBER element
of the FILE element.

You should be aware of the following features when you use this option:
• The source code generator validates not only the COBOL source code file that you specify, but also any
COBOL copybook files that are included in the COBOL source file that you specify.
• No output file is generated unless a COBOL syntax error is detected.
You should be aware of the following limitations when you use this option:

526 Developer for z/OS: Developing with Db2, CICS, and IMS
• This option is available only for COBOL source code.
• The source code generator records only files that contain COBOL syntax errors. Files that do not contain
COBOL syntax errors are not included in the generated XML structure.

Batch processor options applicable for interpretive conversion type

The following list of Batch processor configuration elements applies if interpretive conversion type is
specified (the GEN_CONVERSION_TYPE of a CodegenProperty.)
Note: In the following, if an element is listed without child elements or attributes specified, then
all attributes and child elements are applicable and meaningful. If element has only some attributes
and child elements listed, then only those elements are meaningful for interpretive conversion type.
Configuration and generation options that are not listed will not apply and will be ignored if specified.
• GenerationSpecArray
– platform
– platformProperties
• GenerationSpec
• CodegenPropertyArray (In all configuration files)
• CodegenProperty
– GEN_PROG_NAME
– GEN_CONVERSION_TYPE
– GEN_ERROR_FEEDBACK
– GEN_SOAP_VERSION
– GEN_WSDL_VERSION
• PlatformArray
• Platform
• InputMessage
– nativeTypeName
– importDirectory
– importFile
• InputOutputMessage
– nativeTypeName
– importDirectory
– importFile
• OutputMessage
– nativeTypeName
– importDirectory
– importFile
• WSBindSpec (See description in “WSBindSpec” on page 483)
• DriverSpec
– driverType = WEB_SERVICES_CICS
• EISProject
– name
Note: Specifies the project where artifacts are generated. Remote projects are not supported by the
Batch processor

Developing web services and SOA with Enterprise Service Tools 527
 – EISService
- targetFileURI
• ItemExclusionArray
• RedefinesArray
• XMLNamesArray
• Operation
• ServiceImplementationSpec
Note: The rest of the elements and properties for interpretive conversion modules will be ignored if
specified.

Processing empty complex types

This topic describes the behavior of the batch processor when generating IMS PL/I top-down converters
that contain operations with empty input and output messages.
The batch processor supports processing complex types in which one or both operations are empty
and have no language types or mapping session files to import. This support can be used for ping
services to check if a service is alive. When processing non-empty input or output messages, there is no
evident change in the function of the batch processor. Only when empty input and output messages are
encountered does the batch processor function differently
• Empty input message
When an empty input message is processed by the batch processor, the XML to language
structure conversion process is not attempted because the WSDL2PLI metadata attribute,
SoapBodyHasMapping has been defined as false in the XSD instance. This means that the message
does not contain any data and is considered empty, thus requiring no processing. The converter driver
will then populate the symmetric header to provide service context to the Message Processing Program
(MPP).
• Empty output message
When an empty input message is processed by the batch processor, the XML to language
structure conversion process is not attempted because the WSDL2PLI metadata attribute,
SoapBodyHasMapping has been defined as false in the XSD instance. This means that the message
does not contain any data and is considered empty, thus requiring no processing. The converter driver
then copies the markup for the output messages fully qualified global empty element into the IMS
Connect buffer.
When a scenario involving an empty complex type is encountered, the warning message CRRZX0131W is
issued to the user and also recorded in the log to ensure that the empty message was intentional.

COBOL importer: Compile-time locale and code page

This topic describes the compile-time locales and ASCII code pages supported by the COBOL importer.
You can use the information in this topic to select a compile-time locale and ASCII code page in the
following contexts:
• Setting general preferences for the COBOL importer (see “Setting Importer > COBOL preferences” on
page 219).
• Setting a value for the ImportProperty element for the batch processor (see “ImportProperty” on page
435).
You can use the characters that are represented in a supported code page in COBOL names, data
definitions, literals, and comments.
The COBOL importer uses the POSIX-defined locale conventions. The locale value syntax is:

ll_CC.codepageID

528 Developer for z/OS: Developing with Db2, CICS, and IMS
where:
• ll -> A lowercase two-letter ISO language code
• CC - > An uppercase two-letter ISO country code
• codepageID -> The code page to be used for native DISPLAY and DISPLAY-1 data
When specifying locale and code page information, you must code a valid value for the locale name (ll
CC) and a valid code page (codepageID) that corresponds to the locale name, as shown in Table 132 on
page 529.
The locale in effect determines the code page for compiling COBOL source programs (including
alphanumeric literal values). That is, the code page that is used for compilation is based on the locale
setting at compile time. Thus, the evaluation of literal values in the source program is handled with the
locale in effect at compile time.
The default value for Compile time Locale name is en_US. The default value for the ASCII code page is
IBM-1252.
Note: In Table 132 on page 529 for a given locale name, the last ASCII code page listed in the set is the
default.
Table 132 on page 529 shows the locales that COBOL for Windows supports and the code pages that are
valid for each locale.
The first column, Locale name, shows the valid combinations of ISO language code and ISO country code
(language_COUNTRY) that are supported. The second column show the associated language, and the third
column shows the associated country or area.
The fourth column, ASCII code pages, shows the ASCII code pages that are valid as the code page ID for
the locale with the corresponding language_COUNTRY value.

Table 132. COBOL for Windows Supported Locales and Code Pages
Locale name Language Country or ASCII code pages Language
area group
ar_AA Arabic Arabic IBM-864, IBM-1256 Arabic
Countries
be_BY Byelorussian Belarus IBM-866, IBM-1251 Latin 5
bg_BG Bulgarian Bulgaria IBM-855, IBM-1251 Latin 5
ca_ES Catalan Spain IBM-850, IBM-1252 Latin 1
cs_CZ Czech Czech Republic IBM-852, IBM-1250 Latin 2
da_DK Danish Denmark IBM-437, IBM-850, IBM-1252 Latin 1
de_CH German Switzerland IBM-437, IBM-850, IBM-1252 Latin 1
de_DE German Germany IBM-437, IBM-850, IBM-1252 Latin 1
el_GR Greek Greece IBM-1253 Greek
en_AU English Australia IBM-437, IBM-1252 Latin 1
en_BE English Belgium IBM-850, IBM-1252 Latin 1
en_GB English United Kingdom IBM-437, IBM-850, IBM-1252 Latin 1
en_JP English Japan IBM-437, IBM-850, IBM-1252 Latin 1
en_US English United States IBM-437, IBM-850, IBM-1252 Latin 1
en_ZA English South Africa IBM-437, IBM-1252 Latin 1
es_ES Spanish Spain IBM-437, IBM-850, IBM-1252 Latin 1

Developing web services and SOA with Enterprise Service Tools 529
 Table 132. COBOL for Windows Supported Locales and Code Pages (continued)
Locale name Language Country or ASCII code pages Language
area group
fi_FI Finnish Finland IBM-437, IBM-850, IBM-1252 Latin 1
fr_BE French Belgium IBM-437, IBM-850, IBM-1252 Latin 1
fr_CA French Canada IBM-863, IBM-850, IBM-1252 Latin 1
fr_CH French Switzerland IBM-437, IBM-850, IBM-1252 Latin 1
fr_FR French France IBM-437, IBM-850, IBM-1252 Latin 1
hr_HR Croatian Croatia IBM-852, IBM-1250 Latin 2
hu_HU Hungarian Hungary IBM-852, IBM-1250 Latin 2
is_IS Icelandic Iceland IBM-861, IBM-850, IBM-1252 Latin 1
it_CH Italian Switzerland IBM-850, IBM-1252 Latin 1
it_IT Italian Italy IBM-437, IBM-850, IBM-1252 Latin 1
iw_IL Hebrew Israel IBM-862, IBM-1255 Hebrew
ja_JP Japanese Japan IBM-943 Ideographic
languages
lt_LT Lithuanian Lithuania IBM-1257 Lithuanian
lv_LV Latvian Latvia IBM-1257 Latvian
mk_MK Macedonian Macedonia, IBM-855, IBM-1251 Latin 5
nl_BE Dutch Belgium IBM-437, IBM-850, IBM-1252 Latin 1
nl_NL Dutch Netherlands IBM-437, IBM-850, IBM-1252 Latin 1
no_NO Norwegian Norway IBM-437, IBM-850, IBM-1252 Latin 1
pl_PL Polish Poland IBM-852, IBM-1250 Latin 2
pt_BR Portuguese Brazil IBM-850, IBM-1252 Latin 1
pt_PT Portuguese Portugal IBM-860, IBM-850, IBM-1252 Latin 1
ro_RO Romanian Romania IBM-852, IBM-850, IBM-1250 Latin 2
ru_RU Russian Russian IBM-866, IBM-1251 Latin 5
federation
sh_SP Serbian (Latin) Serbia IBM-852, IBM-1250 Latin 2
sk_SK Slovak Slovakia IBM-852, IBM-1250 Latin 2
sl_SL Slovenian Slovenia IBM-852, IBM-1250 Latin 2
sq_AL Albanian Albania IBM-850, IBM-1252 Latin 1
sv_SE Swedish Sweden IBM-437, IBM-850, IBM-1252 Latin 1
th_TH Thai Thailand IBM-874 Thai
tr_TR Turkish Turkey IBM-857, IBM-1254 Turkish
uk_UA Ukranian Ukraine IBM-866, IBM-1251 Latin 5
zh_TW Chinese Taiwan IBM-950 Ideographic
(traditional) languages

530 Developer for z/OS: Developing with Db2, CICS, and IMS
The CICS catalog manager example application
The CICS catalog example application is a working COBOL application that is designed to illustrate best
practice when connecting CICS applications to external clients and servers using Web services for CICS,
and using Web service modules generated by Enterprise Service Tools.

The example is constructed around a simple sales catalog and order processing application, in which the
end user can perform these functions:
• List the items in a catalog.
• Inquire on individual items in the catalog.(inquireSingle)
• Order items from the catalog.
The catalog is implemented as a VSAM file.
Installation of the base catalog manager application is covered in the CICS 5.3 Transaction Server
documentation. A Web client front end is provided with the catalog manager application. Configuration
of the Web client is also described in the CICS 5.3 Transaction Server documentation. The Web client
calls multiple Web Services that are provided by the base catalog example application after it has been
enabled for Web services.

The base application

The base application, with its 3270 user interface, provides functions with which you can list the contents
of a stored catalog, select an item from the list, and enter a quantity to order. The application has a
modular design which makes it simple to extend the application to support newer technology, such as
Web services.

This illustration shows the structure of the base application (for a detailed description of the application
see “Description of the catalog manager application” on page 554).

Figure 88. Structure of the base application

Installing and setting up the base application

Before you can run the base application you must define and populate two VSAM data sets, and install
two transaction definitions.

Developing web services and SOA with Enterprise Service Tools 531
 Creating and defining the VSAM data sets
The example application uses two KSDS VSAM data sets to be defined and populated. One data set
contains configuration information for the example application. The other contains the sales catalog.
1. Locate the JCL to create the VSAM data sets.

During CICS installation, the JCL is placed in the hlq.SDFHSAMP library:

• Member DFH$ECNF contains the JCL to generate the configuration data set.
• Member DFH$ECAT contains the JCL to generate the catalog data set.
2. Modify the JCL and access method services commands.
a) Supply a valid JOB card.
b) Supply a suitable high level qualifier for the data set names in the access method services
commands.
As supplied, the JCL uses a high level qualifier of HLQ.
The following command defines the catalog file:

DEFINE CLUSTER (NAME(hlq.EXMPLAPP.catname)-

TRK(1 1) -
KEYS(4 0) -
RECORDSIZE(80,80) -
SHAREOPTIONS(2 3) -
INDEXED -
) -
DATA (NAME(hlq.EXMPLAPP.catname.DATA) -
) -
INDEX (NAME(hlq.EXMPLAPP.catname.INDEX) -
)

where
• hlq is a high level qualifier of your choice
• catname is a name of your choice. The name used in the example application as supplied is
EXMPCAT.
The following command defines the configuration file:

DEFINE CLUSTER (NAME(hlq.EXMPLAPP.EXMPCONF)-

TRK(1 1) -
KEYS(9 0) -
RECORDSIZE(350,350) -
SHAREOPTIONS(2 3) -
INDEXED -
) -
DATA (NAME(hlq.EXMPLAPP.EXMPCONF.DATA) -
) -
INDEX (NAME(hlq.EXMPLAPP.EXMPCONF.INDEX) -
)

where hlq is a high level qualifier of your choice.

3. Run both jobs to create and populate the data sets.
4. Use the CEDA transaction to create a FILE definition for the catalog file.
a) Enter the following: CEDA DEF FILE(EXMPCAT)G(EXAMPLE).
Alternatively, you can copy the FILE definition from CICS supplied group DFH$EXBS.
b) Enter the following additional attributes:
DSNAME(hlq.EXMPLAPP.EXMPCAT)
ADD(YES)
BROWSE(YES)
DELETE(YES)
READ(YES)

532 Developer for z/OS: Developing with Db2, CICS, and IMS
 UPDATE(YES)
c) Use the default values for all other attributes.
5. Use the CEDA transaction to create a FILE definition for the configuration file.
a) Enter the following: CEDA DEF FILE(EXMPCONF) G(EXAMPLE).
Alternatively, you can copy the FILE definition from CICS supplied group DFH$EXBS.
b) Enter the following additional attributes:
DSNAME(hlq.EXMPLAPP.EXMPCONF)
ADD(YES)
BROWSE(YES)
DELETE(YES)
READ(YES)
UPDATE(YES)
c) Use the default values for all other attributes.

Defining the 3270 interface

The example application is supplied with a 3270 user interface to run the application and to customize it.
The user interface consists of two transactions, EGUI and ECFG.
Use the CEDA transaction to create TRANSACTION definitions for both transactions.
a) To define transaction EGUI, enter the following: CEDA DEF TRANS (EGUI) G(EXAMPLE)
PROG(DFH0XGUI).
b) To define transaction ECFG, enter the following: CEDA DEF TRANS (ECFG) G(EXAMPLE)
PROG(DFH0XCFG)

Use the default values for all other attributes.

Note: The correct operation of the example application does not depend on the names of the
transactions, so you can use different names if you wish.
Alternatively, you can copy the TRANSACTION definitions from CICS supplied group DFH$EXBS.

Completing the installation

To complete the installation, install the RDO group that contains your resource definitions.
Enter the following command at a CICS terminal: CEDA I G(EXAMPLE).

The application is now ready for use.

Web service support for the example application

The Web service support extends the example application, providing a Web client front end and two
versions of a Web service endpoint for the order dispatcher component.

The Web client front end and one version of the Web service endpoint are supplied as enterprise archives
(EARs) that will run in the following environments:
• WebSphere Application Server Version 5 Release 1 or later
• WebSphere Studio Application Developer Version 5 Release 1 or later with a WebSphere unit test
environment
• WebSphere Studio Enterprise Developer Version 5 Release 1 or later with a WebSphere unit test
environment

Developing web services and SOA with Enterprise Service Tools 533
 The second version of the Web service endpoint is supplied as a CICS service provider application
program (DFH0XODE).

Configuring code page support

As supplied, the example application uses two coded character sets. You must configure your system to
enable data conversion between the two character sets.

The coded character sets used in the example application are:

CCSID
Description
037
EBCDIC Group 1: USA, Canada (z/OS), Netherlands, Portugal, Brazil, Australia, New Zealand)
1208
UTF-8 Level 3
Add the following statements to the conversion image for your z/OS system:

CONVERSION 037,1208;
CONVERSION 1208,037;

Installing Web service support

Before you can run the Web service support for the example application, you must create two HFS
directories, and create and install a number of CICS resource definitions.

Creating the HFS directories

Web service support for the example application requires a shelf directory and a pickup directory in the
Hierarchical File System (HFS).

The shelf directory is used to store the Web service binding files that are associated with WEBSERVICE
resources. Each WEBSERVICE resource is, in turn, associated with a PIPELINE. The shelf directory is
managed by the PIPELINE resource and you should not modify its contents directly. Several PIPELINES
can use the same shelf directory, as CICS ensures a unique directory structure beneath the shelf directory
for each PIPELINE.
The pickup directory is the directory that contains the Web service binding files associated with a
PIPELINE. When a PIPELINE is installed, or in response to a PERFORM PIPELINE SCAN command,
information in the binding files is used to dynamically create the WEBSERVICE and URIMAP definitions
associated with the PIPELINE.
The example application uses /var/cicsts for the shelf directory.
A pipeline will read in an XML pipeline configuration file at install time. It is therefore also useful to define
a directory in which to store these.

Creating the PIPELINE definition

The complete definition of a pipeline consists of a PIPELINE resource and a pipeline configuration file.
The file contains the details of the message handlers that will act on Web service requests and responses
as they pass through the pipeline.

The example application uses the CICS-supplied SOAP 1.1 handler to deal with the SOAP envelopes of
inbound and outbound requests. CICS provides sample pipeline configuration files which you can use in
your service provider and service requester.

534 Developer for z/OS: Developing with Db2, CICS, and IMS
More than one WEBSERVICE can share a single PIPELINE, therefore you need define only one pipeline
for the inbound requests of the example application. You must, however, define a second PIPELINE for
the outbound requests as a single PIPELINE cannot be configured to be both a provider and requester
pipeline at the same time.
1. Use the CEDA transaction to create a PIPELINE definition for the service provider.
a) Enter the following: CEDA DEF PIPE(EXPIPE01) G(EXAMPLE).
Alternatively, you can copy the PIPELINE definition from CICS supplied group DFH$EXWS.
b) Enter the following additional attributes:

STATUS(Enabled)
CONFIGFILE(/usr/lpp/cicsts
/samples/pipelines/basicsoap11provider.xml)
SHELF(var/cicsts)
WSDIR(/usr/lpp/cicsts/samples/webservices/wsbind/provider/)

Note: The HFS entries are case sensitive and assume a default CICS HFS install root of /usr/lpp/
cicsts.
2. Use the CEDA transaction to create a PIPELINE definition for the service requester.
a) Enter the following: CEDA DEF PIPE(EXPIPE02) G(EXAMPLE).
Alternatively, you can copy the PIPELINE definition from CICS supplied group DFH$EXWS.
b) Enter the following additional attributes:

STATUS(Enabled)
CONFIGFILE(/usr/lpp/cicsts
/samples/pipelines/basicsoap11requester.xml)
SHELF(var/cicsts)
WSDIR(/usr/lpp/cicsts/samples/webservices/wsbind/requester/)

Note: The HFS entries are case sensitive and assume a default CICS HFS install root of /usr/lpp/
cicsts.

Creating a TCPIPSERVICE
As the client connects to your Web services over an HTTP transport you must define a TCPIPSERVICE to
receive the inbound HTTP traffic.
Use the CEDA transaction to create a TCPIPSERVICE definition to handle inbound HTTP requests.
a) Enter the following: CEDA DEF TCPIPSERVICE(EXMPPPORT) G(EXAMPLE).

Alternatively, you can copy the TCPIPSERVICE definition from CICS supplied group DFH$EXWS.
b) Enter the following additional attributes:
URM(NONE)
PORTNUMBER(port) where port is an unused port number in your CICS system.
PROTOCOL(HTTP)
TRANSACTION(CWXN)
c) Use the default values for all other attributes.

Dynamically installing the WEBSERVICE and URIMAP resources

Each function exposed as a Web service requires a WEBSERVICE resource to map between the incoming
XML of the SOAP BODY and the COMMAREA interface of the program, and a URIMAP resource that routes
incoming requests to the correct PIPELINE and WEBSERVICE. Although you can use RDO to define and
install your WEBSERVICE and URIMAP resources, you can also have CICS create them dynamically when
you install a PIPELINE resource.
Install the PIPELINE resources.

Developing web services and SOA with Enterprise Service Tools 535
 Use the following commands:
CEDA INSTALL PIPELINE(EXPIPE01) G(EXAMPLE)
CEDA INSTALL PIPELINE(EXPIPE02) G(EXAMPLE)
When you install each PIPELINE resource, CICS scans the directory specified in the PIPELINE's WSDIR
attribute (the pickup directory). For each Web service binding file in the directory, that is for each file with
the .wsbind suffix, CICS installs a WEBSERVICE and a URIMAP if one does not already exist. Existing
resources are replaced if the information in the binding file is newer than the existing resources.
When the PIPELINE is later disabled and discarded all associated WEBSERVICE and URIMAP resources
will also be discarded.
If you have already installed the PIPELINE, use the PERFORM PIPELINE SCAN command to initiate the
scan of the PIPELINE's pickup directory.
When you have installed the PIPELINEs, the following WEBSERVICEs and their associated URIMAPs will
be installed in your system:
dispatchOrder
dispatchOrderEndpoint
inquireCatalog
inquireSingle
placeOrder
The names of the WEBSERVICEs are derived from the names of the Web service binding files; the
names of the URIMAPs are generated dynamically. You can view the resources with a CEMT INQUIRE
WEBSERVICE command.
The following display shows the names of the PIPELINE, the URIMAP, and the target program that is
associated with each WEBSERVICE.
Note: In this example, there is no URIMAP or target program displayed for WEBSERVICE(dispatchOrder)
because the WEBSERVICE is for an outbound request.

I WEBS
STATUS: RESULTS - OVERTYPE TO MODIFY
Webs(dispatchOrder ) Pip(EXPIPE02)
Ins Dat(20041203)
Webs(dispatchOrderEndpoint ) Pip(EXPIPE01)
Ins Uri(£539140 ) Pro(DFH0XODE) Com Dat(20041203)
Webs(inquireCatalog ) Pip(EXPIPE01)
Ins Uri(£539141 ) Pro(DFH0XCMN) Com Dat(20041203)
Webs(inquireSingle ) Pip(EXPIPE01)
Ins Uri(£539142 ) Pro(DFH0XCMN) Com Dat(20041203)
Webs(placeOrder ) Pip(EXPIPE01)
Ins Uri(£539150 ) Pro(DFH0XCMN) Com Dat(20041203)

WEBSERVICE(dispatchOrderEndpoint) represents the local CICS implementation of the dispatch order

service.

Creating the WEBSERVICE resources with RDO

As an alternative to using the PIPELINE scanning mechanism to install WEBSERVICE resources, you can
create and install them using Resource Definition Online (RDO).

Important: If you use RDO to define the WEBSERVICE and URIMAP resources, you must ensure that their
Web service binding files are not in the PIPELINE's pickup directory.
1. Use the CEDA transaction to create a WEBSERVICE definition for the inquire catalog function of the
example application.
a) Enter the following: CEDA DEF WEBSERVICE(EXINQCWS) G(EXAMPLE).
b) Enter the following additional attributes:

536 Developer for z/OS: Developing with Db2, CICS, and IMS
 PIPELINE(EXPIPE01)
WSBIND(/usr/lpp/cicsts/samples
/webservices/wsbind/inquireCatalog.wsbind)
2. Repeat the preceding step for each of the following functions of the example application.
WEBSERVICE PIPELINE
Function name attribute WSBIND attribute

INQUIRE SINGLE EXINQSWS EXPIPE01 /usr/lpp/cicsts/samples

ITEM /webservices/wsbind
/provider/inquireSingle.wsbind

PLACE ORDER EXORDRWS EXPIPE01 /usr/lpp/cicsts/samples

/webservices/wsbind
/provider/placeOrder.wsbind

DISPATCH STOCK EXODRQWS EXPIPE02 /usr/lpp/cicsts/samples

/webservices/wsbind
/requester/dispatchOrder.wsbind

DISPATCH STOCK EXODEPWS EXPIPE01 /usr/lpp/cicsts/samples

endpoint (optional) /webservices/wsbind
/provider/dispatchOrderEndpoint.wsbind

Creating the URIMAP resources with RDO

As an alternative to using the PIPELINE scanning mechanism to install URIMAP resources, you can create
and install them using Resource Definition Online (RDO).

Important: If you use RDO to define the WEBSERVICE and URIMAP resources, you must ensure that their
Web service binding files are not in the PIPELINE's pickup directory.
1. Use the CEDA transaction to create a URIMAP definition for the inquire catalog function of the example
application.
a) Enter the following: CEDA DEF URIMAP(INQCURI) G(EXAMPLE).
b) Enter the following additional attributes:

USAGE(PIPELINE)
HOST(*)
PATH(/exampleApp/inquireCatalog)
TCPIPSERVICE(SOAPPORT)
PIPELINE(EXPIPE01)
WEBSERVICE(EXINQCWS)
2. Repeat the preceding step for each of the remaining functions of the example application.
Use the following names for your URIMAPs:

Function URIMAP name

INQUIRE SINGLE ITEM INQSURI
PLACE ORDER ORDRURI
DISPATCH STOCK Not required
DISPATCH STOCK endpoint (optional) ODEPURI

a) Specify the following distinct attributes for each URIMAP:

Developing web services and SOA with Enterprise Service Tools 537
 Function URIMAP name PATH WEBSERVICE
INQUIRE SINGLE INQSURI /exampleApp/inquireSingle EXINQSWS
ITEM
PLACE ORDER ORDRURI /exampleApp/placeOrder EXORDRWS
DISPATCH ODEPURI /exampleApp/dispatchOrder EXODEPWS
STOCK endpoint
(optional)
b) Enter the following additional attributes, which are the same for all the URIMAPs:
USAGE(PIPELINE)
HOST(*)
TCPIPSERVICE(SOAPPORT)
PIPELINE(EXPIPE01)

Completing the installation

To complete the installation, install the RDO group that contains your resource definitions.
Enter the following command at a CICS terminal: CEDA I G(EXAMPLE).

The application is now ready for use.

Configuring the example application

The base application includes a transaction (ECFG) that you can use to configure the example application.

The configuration transaction uses mixed case information. You must use a terminal that can handle
mixed case information correctly.
The transaction lets you specify a number of aspects of the example application. These include:
• The overall configuration of the application, such as the use of Web services
• The network addresses used by the Web services components of the application
• The names of resources, such as the file used for the data store
• The names of programs used for each component of the application
The configuration transaction lets you replace CICS-supplied components of the example application with
your own, without restarting the application.
1. Enter the transaction ECFG to start the configuration application.
CICS displays the following screen:

538 Developer for z/OS: Developing with Db2, CICS, and IMS
 CONFIGURE CICS EXAMPLE CATALOG APPLICATION

Datastore Type ==> VSAM STUB|VSAM

Outbound WebService? ==> NO YES|NO
Catalog Manager ==> DFH0XCMN
Data Store Stub ==> DFH0XSDS
Data Store VSAM ==> DFH0XVDS
Order Dispatch Stub ==> DFH0XSOD
Order Dispatch WebService ==> DFH0XWOD
Stock Manager ==> DFH0XSSM
VSAM File Name ==> EXMPCAT
Server Address and Port ==> myserver:99999
Outbound WebService URI ==> http://myserver:80/exampleApp/dispatchOrder
==>
==>
==>
==>
==>

PF 3 END 12 CNCL

2. Complete the fields.

Datastore Type
Specify STUB if you want to use the Data Store Stub program.
Specify VSAM if you want to use the VSAM data store program.
Outbound WebService
Specify YES if you want to use a remote Web service for your Order Dispatch function, that is, if you
want the catalog manager program to link to the Order Dispatch Web service program.
Specify NO if you want to use a stub program for your Order Dispatch function, that is, if you want
the catalog manager program to link to the Order Dispatch Stub program.
Catalog Manager
Specify the name of the Catalog Manager program. The program supplied with the example
application is DFH0XCMN.
Data Store Stub
If you specified STUB in the Datastore Type field, specify the name of the Data Store Stub
program. The program supplied with the example application is DFH0XSDS.
Data Store VSAM
If you specified VSAM in the Datastore Type field, specify the name of the VSAM data store
program. The program supplied with the example application is DFH0XVDS.
Order Dispatch Stub
If you specified NO in the Outbound WebService field, specify the name of the Order Dispatch
Stub program. The program supplied with the example application is DFH0XSOD.
Order Dispatch WebService
If you specified YES in the Outbound WebService field, specify the name of the program
that functions as a service requester. The program supplied with the example application is
DFH0XWOD.
Stock Manager
Specify the name of the Stock Manager program. The program supplied with the example
application is DFH0XSSM.
VSAM File Name
If you specified VSAM in the Datastore Type field, specify the name of the CICS FILE definition.
The name used in the example application as supplied is EXMPCAT.
Server Address and Port

Developing web services and SOA with Enterprise Service Tools 539
 Outbound WebService URI
If you specified YES in the Outbound WebService field, specify the location of the Web service
that implements the dispatch order function. If you are using the supplied CICS endpoint set this
to: http://myserver:myport/exampleApp/dispatchOrder where myserver and myport
are your CICS server address and port respectively.

Configuring the Web client

Before you can use the Web client, you must configure it to call the appropriate end points in your CICS
system.
1. Enter the following in your Web browser: http://myserver:9080/ExampleAppClientWeb/,
where myserver is the hostname of the server on which the Web service client is installed.

The example application displays the page shown in Figure 89 on page 540:

Figure 89. Welcome Page for the CICS Example Application

2. Click the CONFIGURE button to bring up the configuration page.
The configuration page shown in Figure 90 on page 541 displayed.

540 Developer for z/OS: Developing with Db2, CICS, and IMS
 Figure 90. Configuration Page for the CICS Example Application
3. Enter the new endpoints for the Web service.
There are three endpoints to configure:
Inquire catalog
Inquire item
Place order
a) In the URLs replace the string 'myCicsServer' with the name of the system on which your CICS is
running.
b) Replace the port number '9999' with the port number configured in the TCPIPSERVICE, in the
example this to 30000.
4. Click the SUBMIT button.
The Web application is now ready to run.
Note: The URL that the Web services invoke is stored in an HTTP session. It is therefore necessary to
repeat this configuration step each time a browser is first connected to the client.

Running the example application

You can run the example application in two ways: you can use the BMS interface, and you can use a Web
client.

Developing web services and SOA with Enterprise Service Tools 541
 Running the example application with the BMS interface
The base application can be invoked using its BMS interface.
1. Enter transaction EGUI from a CICS terminal.

The example application displays the following menu:

CICS EXAMPLE CATALOG APPLICATION - Main Menu

Select an action, then press ENTER

Action . . . . 1. List Items

2. Order Item Number ____
3. Exit

F3=EXIT F12=CANCEL

The options on the menu enable you to list the items in the catalog, order an item, or exit the
application.
2. Type 1 and press ENTER to select the LIST ITEMS option.
The application displays a list of items in the catalog.

CICS EXAMPLE CATALOG APPLICATION - Inquire Catalog

Select a single item to order with /, then press ENTER

Item Description Cost Order

-----------------------------------------------------------------
0010 Ball Pens Black 24pk 2.90 /
0020 Ball Pens Blue 24pk 2.90 _
0030 Ball Pens Red 24pk 2.90 _
0040 Ball Pens Green 24pk 2.90 _
0050 Pencil with eraser 12pk 1.78 _
0060 Highlighters Assorted 5pk 3.89 _
0070 Laser Paper 28-lb 108 Bright 500/ream 7.44 _
0080 Laser Paper 28-lb 108 Bright 2500/case 33.54 _
0090 Blue Laser Paper 20lb 500/ream 5.35 _
0100 Green Laser Paper 20lb 500/ream 5.35 _
0110 IBM Network Printer 24 - Toner cart 169.56 _
0120 Standard Diary: Week to view 8 1/4x5 3/4 25.99 _
0130 Wall Planner: Eraseable 36x24 18.85 _
0140 70 Sheet Hard Back wire bound notepad 5.89 _
0150 Sticky Notes 3x3 Assorted Colors 5pk 5.35 _

F3=EXIT F7=BACK F8=FORWARD F12=CANCEL

3. Type / in the ORDER column, and press ENTER to order an item.

The application displays details of the item to be ordered.

542 Developer for z/OS: Developing with Db2, CICS, and IMS
 CICS EXAMPLE CATALOG APPLICATION - Details of your order

Enter order details, then press ENTER

Item Description Cost Stock On Order

-----------------------------------------------------------------------------
0010 Ball Pens Black 24pk 2.90 0011 000

Order Quantity: 5
User Name: CHRISB
Charge Dept: CICSDEV1

F3=EXIT F12=CANCEL

4. If there is sufficient stock to fulfil the order, enter the following information.
a) Complete the ORDER QUANTITY field.
Specify the number of items you want to order.
b) Complete the USERID field.
Enter a 1 to 8-character string. The base application does not check the value that is entered here.
c) Complete the CHARGE DEPT field.
Enter a 1 to 8-character string. The base application does not check the value that is entered here.
5. Press ENTER to submit the order and return to the main menu.
6. Select the EXIT option to end the application.

The Web service enabled application

You can invoke the example application from a Web browser.
1. Enter the following in your Web browser: http://myserver:9080/ExampleAppClientWeb/,
where myserver is the host name of the server on which the Web service client is installed.

The example application displays the page shown in Figure 91 on page 544.

Developing web services and SOA with Enterprise Service Tools 543
 Figure 91. Welcome Page for the CICS Example Application
2. Click the INQUIRE button.
The example application displays the page shown in Figure 92 on page 544.

Figure 92. Inquire Page for the CICS Example Application

3. Enter an item number, and click the SUBMIT button.
Tip: The base application is primed with item numbers in the sequence 0010, 0020, ... through 0210.
The example application displays the page shown in Figure 93 on page 545, which contains a list of
items in the catalog, starting with the item number that you entered.

544 Developer for z/OS: Developing with Db2, CICS, and IMS
 Figure 93. List Items Page for the CICS Example Application
4. Select the item that you want to order.
a) Click the radio button in the Select column for the item you want to order.
b) Click the SUBMIT button.
The example application displays the page shown in Figure 94 on page 546:

Developing web services and SOA with Enterprise Service Tools 545
 Figure 94. Order Details Page for the CICS Example Application
5. To place an order, enter the following information.
a) Complete the Quantity field.
Specify the number of items you want to order.
b) Complete the User Name field.
Enter a 1 to 8-character string. The base application does not check the value that is entered here.
c) Complete the Department Name field.
Enter a 1 to 8-character string. The base application does not check the value that is entered here.
d) Click the SUBMIT button.
The example application displays the page shown in Figure 95 on page 546 to confirm that the order
has been placed:

Figure 95. Order Confirmation Page for the CICS Example Application

546 Developer for z/OS: Developing with Db2, CICS, and IMS
Creating and deploying CICS Web services artifacts
This topic and its subtopics describe how to use the Enterprise Service Tools to create the files needed to
deploy the CICS catalog manager example application as a Web service.

Web services in CICS provides an interpretive engine that converts XML data to and from language
structures. The interpretive engine does not support all the data constructs and types in the COBOL
language, making it necessary for the CICS Web services developer to write additional code or a wrapper
program to process unsupported types. The behavior of the interpretive engine is not configurable,
whereas a user may have very specific needs in processing SOAP messages.
A standard interface between CICS combined with a user supplied program that provides XML conversion
to and from language structures is called the "vendor interface". The vendor interface allows users to have
pluggable XML conversion. XML converters generated by Enterprise Service Tools have broader support
for data constructs and types. We recommend using these XML converters with the vendor interface. For
improved debugging, CICS Transaction Server Version 3.1 treats the compiled converters as user code,
which allows debugging should a failure occur. The interpretive engine cannot be debugged or changed by
the user.
New in CICS Transaction Server Version 3.1, is a batch job called DFHLS2WS (Language Structure to
WSDL) which is equivalent to the bottom-up approach of Web services development . Enterprise Service
Tools, used in combination with the vendor interface as a replacement for DFHLS2WS, provides expanded
functionality to the end user. This combination helps a user to enable Web service interface with a COBOL
data type that is not supported by the CICS interpretive conversion engine, generally without requiring the
user to write any additional wrapper conversion program.
Related concepts

“Artifacts necessary to enable a Web service under CICS” on page 547

Related tasks

“Deploying the Web service artifacts to CICS” on page 550

“Creating Web service artifacts for CICS” on page 548

Artifacts necessary to enable a Web service under CICS

This topic describes the WSBind file, the WSDL file, and the driver and conversion programs generated by
the Enterprise Service Tools wizards.

WSBind file
The WSBind file is a resource that describes to CICS the specifics of the Web service. For example, it
contains information about what the system should do to convert an input XML document to a COBOL
language structure and what to do to convert the output COBOL data to the output XML document.
Enterprise Service Tools can be used to generate both Vendor and Native WSBind files.
The WSBind file is an EBCDIC binary file, CICS expects the WSBind file to be encoded in the EBCDIC
variant used by the region. The extension of the generated WSBind file is always set to .wsbind.
The WSBind File Viewer can be used to display the contents of the WSBind file.

Enterprise Service Tools Converters

In the CICS vendor scenario, CICS delegates conversion of SOAP requests and response messages to
vendor conversion programs. The same wizard in the Enterprise Service Tools that generates the WSBind
file also generates vendor conversion programs suitable for use with the CICS vendor interface. These
vendor conversion programs consist of a driver, a request XML converter and a response XML converter.
The XML converters convert an input XML document to a COBOL language structure and convert the

Developing web services and SOA with Enterprise Service Tools 547
 output COBOL data to the output XML document. The driver program manages the communication
between CICS and the XML converters.

WSDL
The WSDL file describes the Web service to the Web service clients. The same wizard in the Enterprise
Service Tools that generates the WSBind file and the vendor conversion programs also generates the
WSDL file.
The WSDL file can also be used by the CICS system to validate messages received and sent by the Web
service. The validation can be turned on and off when the CICS Web service resource is installed or
configured. Validation is useful when you test or debug your Web service. Validation will slow down the
Web service performance and you may want to turn it off in the production version of the Web service.
Note: Make sure that you use the WSDL file, WSBind file, and XML conversion programs that are
generated from the same language source file (and the same wizard session). Do not mix artifacts from
other sources or tools. For example do not combine XML conversion programs generated by the wizard
from the Enterprise Service Tools with a WSDL file or a WSBind file generated by the DFHLS2WS batch job
(part of the CICS Web service assistant tool that is included in CICS Transaction Server version 3.1 and
later).
Related concepts

“Creating and deploying CICS Web

services artifacts” on page 547

Related tasks

“Deploying the Web service artifacts to CICS” on page 550

“Creating Web service artifacts for CICS” on page 548

Creating Web service artifacts for CICS

This topic describes the development steps that you need to perform to create the needed artifacts to
install a new Web service in CICS using the Enterprise Service Tools perspective.
This process uses the Create New Service Interface (bottom-up) wizard from the Enterprise Service Tools.
Note: You can also achieve these tasks using the batch processor .

Locating the CICS application source and copy books

In order to generate the artifacts needed to enable an application as a Web service, the Create New
Service Interface (bottom-up) wizard must have access to either a complete program or copy book
containing the language structure that is the interface to the application.
Since generated artifacts (the XML converters, the driver, the WSBind file, and the WSDL file) must be
transferred to a z/OS system, you can use the z/OS projects and system perspectives of Developer for
z/OS to assist with this task. Also if your program source and copy books are located on z/OS you can
access them using the z/OS projects perspective.
Create a local project and import the program source files for the CICS program to the project. If the
program source files exist on a remote system, use the Remote Systems view to copy them to your local
project.

Generating the Web services artifacts conversion artifacts

Follow these steps to generate the Web services artifacts:
1. Verify that the Navigator view is open. If the Navigator view is not open, follow these steps to open the
Navigator view:

548 Developer for z/OS: Developing with Db2, CICS, and IMS
 a. In the menu bar of the workbench, select Window > Show View > Other. The Show View wizard
opens.
b. In the Show View wizard:
i) Expand General.
ii) Select Navigator.
iii) Click OK.
The Navigator view opens.
2. Start the Enterprise Service Tools Wizard Launchpad:
a. In the Navigator view, right-click the program source file containing the interface data structure for
the program.
b. Select Enable Enterprise Web Service.
The Enterprise Service Tools Wizard Launchpad opens.
3. Launch the Create New Service Interface (bottom-up) wizard:
a. In the Enterprise Service Tools Wizard Launchpad:
i) In the Runtime list box, select Web Services for CICS.
ii) In the Scenario list box, select Create New Service Interface (bottom-up).
iii) In the Conversion type list box, select Compiled XML Conversion.
iv) Click Start.
The Create New Service Interface (bottom-up) wizard opens.
4. On the first page of the wizard (entitled Language Structures):
a. In the Request Language Structure tab, select the high-level language structure that is the input
structure for the application. By default the first structure defined in the program source file is
selected.
b. In the Response Language Structure tab, select the high-level language structure that is the
output structure for the application. Additional structures are allowed to be selected or omitted.
However, by default the first structure defined in the program source file is selected.
c. Click Next.
5. On the second page of the wizard (entitled Generation Options):
a. In the XML Converters tab:
i) In the Specify identification attributes group, verify or change other entries that apply for
your z/OS system (for example, the name of the CICS application program in "Service program
name:" should be correct).
ii) In the Specify character encodings group, verify or change other entries that apply for your
z/OS system.
b. In the WSDL and XSD tab:
i) In the Service Location field, type the Endpoint URI.
Note: The local portion of the URI (excludes server and port) is used as the default for the local
URI in the WSBind (for example, /exampleApp/inquireSingle).
c. Click Next.
6. On the third page of the wizard (entitled Web Services for CICS):
a. In the Basic Options tab:
i) In the Specify targets for WSBind file group:
a) In the input field WSBind file container, specify the folder and subfolder in which you want
the WSBind file to be generated.

Developing web services and SOA with Enterprise Service Tools 549
 ii) In the Specify application program properties group, if your CICS program communicates via a
channel.
a) Expand the Program interface list box and select CHANNEL.
b) In the Container name field, type the name of the container.
b. In the Advanced Options tab, specify installation options for the CICS Web service. If you do not
specify these properties you might have to define them at install time during the manual creation of
the Web service definitions in CICS.
c. Click Next.
7. On the fourth page of the wizard (titled File, data set, or member selection):
a. In the XML Converters tab:
i) In the Converter file container field, specify the folder and subfolder in which you want the
converter programs to be created.
ii) In the input field Converter driver file name, type the name of the file in which you want the
converter programs to be generated.
Note: By default, all the converter programs (driver, request converter, and response converter)
are placed in the same file. If you clear the checkbox Generate all to driver, you can specify a
different file to contain each converter program, or you can clear the checkbox that precedes a
converter program's name to cause the wizard not to generate that converter program.
b. In the WSDL and XSD tab:
i) In the WSDL file container field, specify the folder and subfolder in which you want the WSDL
and XSD files to be generated.
ii) In each of the input fields WSDL file name, Request XSD file name, and Request XSD file
name, type the name that you want to use for the file. Clear the checkbox that precedes the
request XSD file name or the response XSD file name to cause the wizard not to generate that
file.
c. Click Finish.

The Create New Service Interface (bottom-up) wizard generates the specified output.

Building the XML converters

The XML converters consist of multiple programs that must be compiled and statically linked together
with the converter driver program as the main entry point. Using the z/OS projects perspective create a
remote project that refers to the target system for your Web service. In order to build the XML converters,
a version of Enterprise COBOL that supports XML parsing (version 3.1 or later) is required. Copy the XML
converter files to a remote z/OS system, using the Remote Systems view in the z/OS Projects perspective
(or, you can generate the files directly to the remote system from within the Enable Enterprise Web
Service wizards). Browse for the XML Converter files in the Remote Systems view and add them to the
remote project. Edit the properties of the remote project to reflect the compile and link options specific
to your z/OS system account. The target load library for the remote project should be in the DFHRPL
concatenation of the target CICS region. When the converter programs are generated into separate files,
nominate the converter driver as the main entry point and right-click the remote project to open the
menu. Select rebuild project from the menu. The results of the build, including the compilation listings,
will appear in the remote project.

Deploying the Web service artifacts to CICS

This topic describes how to deploy the Web service artifacts to CICS

550 Developer for z/OS: Developing with Db2, CICS, and IMS
Setting up a CICS Web services provider PIPELINE
A TCPIPSERVICE resource using the HTTP protocol and listening on the desired port must be created and
installed. First, create a PIPELINE resource that uses the previously created TCPIPRESOURCE. Within the
PIPELINE resource definition, the WSDir or "pickup" directory must be defined which enables auto-install
of Web services directly from WSBind files.
You can find detailed information on setting up a provider type PIPELINE in the CICS 3.1 documentation.

Moving generated artifacts to the host system

While building the XML converter programs, you deployed the XML converter load module to the host
system. You now need to transmit the remaining artifacts, the WSBind and WSDL to the WSDir or "pickup"
directory for the CICS PIPELINE under which the Web service will be installed. The "pickup" directory
exists in an HFS on the target system.
Note: Both the WSBind and WSDL files are sensitive to codepage translation. Since the WSBind is in
EBCDIC and the WSDL declares a UTF-8 encoding declaration, you must transmit these files in binary
mode to the host system.

Auto-installing the Web service

After having transmitted the WSBind and WSDL to the PIPELINE pickup directory, you can do an auto-
install if all of the fields on the advanced tab of the WSBind properties page in Developer for z/OS are
completed correctly. You can then issue a

CEMT PERFORM PIPELINE(pipelinename) SCAN

If this completes successfully you should see a new WEBSERVICE resource created by doing a

CEMT INQUIRE WEBSERVICE(*)

The name of the WEBSERVICE is derived from the first 31 characters of the WSBind file name. If you do a

CEMT INQUIRE URIMAP(*)

you will also see that a URIMAP resource is automatically created. The URIMAP resource maps a local
URI to WEBSERVICE resource. By default full WSDL validation is turned off (for performance reasons). To
turn it on you can do a

CEMT SET WEBSERVICE(webservicename)

and change "novalidation" to "validation". Doing this causes CICS to use the provided WSDL to do full
validation of SOAP requests and responses related to this particular WEBSERVICE resource. The location
of the WSDL that CICS uses for validation is visible when viewing a WEBSERVICE resource. If the WSDL
specified in the WSBind file is not found at the expected location in the filesystem, the WSDL entry in the
WEBSERVICE resource will be empty or blank.

Manually installing the Web service

The manual install is recommended for cases where it is not possible to know all of the necessary details
to populate the advanced tab of the WSBind properties page. The WSBind and WSDL need to be moved to
the pickup directory.
The details of creating URIMAP and WEBSERVICE resources manually are explained in depth in the CICS
documentation.

Developing web services and SOA with Enterprise Service Tools 551
 Related concepts

“Artifacts necessary to enable a Web service under CICS” on page 547

“Creating and deploying CICS Web
services artifacts” on page 547

Related tasks

“Creating Web service artifacts for CICS” on page 548

Enabling the catalog example for Web services using Developer for z/OS
You can use Enterprise Service Tools to generate XML conversion artifacts that utilize the CICS vendor
interface to provide conversion services of request and response SOAP messages for the catalog manager
COBOL application.

This section describes how to enable one of the functions of the base application as a Web service. This
Web service, named inquireSingle, provides a Web service client with the ability to query individual items
in the catalog.

Generating Web services artifacts for the inquireSingle Web service

The copy book containing the combined interface definition for the catalog manager is located in the
CICS samples dataset with member name DFH0XCP1. The inquireSingle Web service uses a subset of the
interface definition which can be found in a separate copy book DFH0XCP4.

You can run the Create New Service Interface (bottom-up) wizard against either of these copy books,
keeping in mind that if you choose to go with DFH0XCP1 you should make sure on the first page of
the wizard (entitled Language structures) to select the redefinition CA-INQUIRE-SINGLE REDEFINES
CA-REQUEST-SPECIFIC and all of its child elements.
Note: Filler items are not displayed.
One of the benefits of using Enterprise Service Tools is support for the REDEFINES modifier. You do not
have to factor out your interface definition into separate copy books for each redefinition.
The Create New Service Interface (bottom-up) wizard expects that all imported COBOL language
structures have a level 01 containing element declared. You must add the declaration 01 DFH0XCMN
to the top of whichever copy book you decide to use. The name of the level 01 is important in this case so
that the root element name used by the XML converters matches what is expected by the CICS Web client
for the catalog application.
See “Locating the CICS application source and copy books” on page 548 for how to access the copy books
mentioned in the workspace.
After the source for the copy books is in the workspace, see “Generating the Web services artifacts
conversion artifacts” on page 548 for details on how to generate the XML converters, driver, and WSBind
and WSDL files, using the following inputs to the Create New Service Interface (bottom-up) wizard.
Follow these steps to use the Create New Service Interface (bottom-up) wizard:
1. Verify that the Navigator view is open. If the Navigator view is not open, follow these steps to open the
Navigator view:
a. In the menu bar of the workbench, select Window > Show View > Other. The Show View wizard
opens.
b. In the Show View wizard, expand General, select Navigator, and click OK.
The Navigator view opens.

552 Developer for z/OS: Developing with Db2, CICS, and IMS
2. Start the Enterprise Service Tools Wizard Launchpad:
a. In the Navigator view, right-click DFH0XCP1.cbl.
b. Select Enable Enterprise Web Service.
The Enterprise Service Tools Wizard Launchpad opens.
3. Launch the Create New Service Interface (bottom-up) wizard:
a. In the Enterprise Service Tools Wizard Launchpad, make these selections and click Start:
Runtime: Web Services for CICS
Scenario: Create New Service Interface (bottom-up)
Conversion type: Compiled XML Conversion
The Create New Service Interface (bottom-up) wizard opens.
4. Enter the following values for each page of the wizard. If a value is not specified for a particular input
field or list box selection, then use the default value already displayed for that field or list box.
a. On the Language structures page:
Request language structure: CA-INQUIRE-SINGLE
Response language structure: CA-INQUIRE-SINGLE
b. On the Generation Options XML Converters tab:
Service program name: DFH0XCMN
Request Codpage: Codepage of your CICS system
Host Codepage: Codepage of your CICS system
Response Codepage: Codepage of your CICS system
c. On the Generation Options WSDL and XSD tab Endpoint URI field, specify http://
yourserver:yourport/exampleApp/inquireSingle.
d. On the Web Services for CICS Basic Options tab WSBind file name field, specify
inquireSingle.
e. On the File, data set, or member selection XML Converters tab:
Converter driver file name: DFHXCP4D
Request Converter file name: DFHXCP4I
Response Converter file name: DFHXCP4O
f. On the File, data set, or member selection WSDL and XSD tab WSDL file name field, specify
inquireSingle.
The Create New Service Interface (bottom-up) wizard generates the specified output.

Deploying and installing the inquireSingle Web service

This topic describes how to deploy and install the inquireSingle Web service.

After generating the converters in “Generating Web services artifacts for the inquireSingle Web service”
on page 552, refer to following sections to deploy and install the inquireSingle Web service:
1. To build the converters and deploy the load module to the host system, see “Creating Web service
artifacts for CICS” on page 548.
2. To deploy the WSBind and WSDL files to the "EXPIPE01" PIPELINE WSDir (pickup directory), see
“Deploying the Web service artifacts to CICS” on page 550.
3. To install the new Web service and check if it is in service, see “Deploying the Web service artifacts to
CICS” on page 550.

You can now invoke the inquireSingle Web service from the web client.

Developing web services and SOA with Enterprise Service Tools 553
 Combined interface definition DFH0XCP1
This topic contains a listing of the input and output interface definitions from the CICS samples dataset
with the member name DFH0XCP1.

>> 01 DFH0XCMN.

* Catalogue COMMAREA structure

03 CA-REQUEST-ID PIC X(6).
03 CA-RETURN-CODE PIC 9(2).
03 CA-RESPONSE-MESSAGE PIC X(79).
03 CA-REQUEST-SPECIFIC PIC X(911).
* Fields used in Inquire Catalog
03 CA-INQUIRE-REQUEST REDEFINES CA-REQUEST-SPECIFIC.
05 CA-LIST-START-REF PIC 9(4).
05 CA-LAST-ITEM-REF PIC 9(4).
05 CA-ITEM-COUNT PIC 9(3).
05 CA-INQUIRY-RESPONSE-DATA PIC X(900).
05 CA-CAT-ITEM REDEFINES CA-INQUIRY-RESPONSE-DATA
OCCURS 15 TIMES.
07 CA-ITEM-REF PIC 9(4).
07 CA-DESCRIPTION PIC X(40).
07 CA-DEPARTMENT PIC 9(3).
07 CA-COST PIC X(6).
07 IN-STOCK PIC 9(4).
07 ON-ORDER PIC 9(3).
* Fields used in Inquire Single
03 CA-INQUIRE-SINGLE REDEFINES CA-REQUEST-SPECIFIC.
05 CA-ITEM-REF-REQ PIC 9(4).
05 FILLER PIC 9(4).
05 FILLER PIC 9(3).
05 CA-SINGLE-ITEM.
07 CA-SNGL-ITEM-REF PIC 9(4).
07 CA-SNGL-DESCRIPTION PIC X(40).
07 CA-SNGL-DEPARTMENT PIC 9(3).
07 CA-SNGL-COST PIC X(6).
07 IN-SNGL-STOCK PIC 9(4).
07 ON-SNGL-ORDER PIC 9(3).
05 FILLER PIC X(840).
* Fields used in Place Order
03 CA-ORDER-REQUEST REDEFINES CA-REQUEST-SPECIFIC.
05 CA-USERID PIC X(8).
05 CA-CHARGE-DEPT PIC X(8).
05 CA-ITEM-REF-NUMBER PIC 9(4).
05 CA-QUANTITY-REQ PIC 9(3).
05 FILLER PIC X(888).

Description of the catalog manager application

This topic and its subtopics describe the CICS catalog manager example application.

Components of the base application

This topic describes the components of the base application.

Table 133. Application Components

Type Comment

Member name in SDFHSAMP

DFH0XCMN Cobol Source Source code for the catalog
manager application
DFH0XVDS Cobol Source Source code for the VSAM data-
store module

554 Developer for z/OS: Developing with Db2, CICS, and IMS
Table 133. Application Components (continued)
Type Comment

Member name in SDFHSAMP

DFH0XSDS Cobol Source Source code for the stubbed
data-store module
DFH0XSOD Cobol Source Source code for the stubbed
version of the order dispatch
module
DFH0XWOD Cobol Source Source code for the order
dispatch module that makes an
outbound Web service request
DFH0XODE Cobol Source Source code for the stubbed
version of the order dispatch
endpoint
DFH0XSSM Cobol Source Source code for the stubbed
version of the stock manager
module
DFH0XGUI Cobol Source Source code for the BMS
interface controller application
DFH0XCFG Cobol Source Source code for the application
configuration module
DFH0XCP1 Copybook Cobol copybook definition for
catalog manager inquire and
place order operations
DFH0XCP2 Copybook Cobol copybook definition for
dispatch order and stock
manager operations
DFH0XCP3 Copybook Cobol copybook definition for the
inquire list operation
DFH0XCP4 Copybook Cobol copybook definition for the
inquire single operation
DFH0XCP5 Copybook Cobol copybook definition for the
place order operation
DFH0XCP6 Copybook Cobol copybook definition for the
dispatch order operation
DFH0XCP7 Copybook Cobol copybook definition that is
mapped to a SOAP request for
the dispatch order operation
DFH0XCP8 Copybook Cobol copybook definition that is
mapped to a SOAP response for
the dispatch order operation
DFH0XM1 Copybook Cobol copybook for BMS
interface
DFH0XM2U Copybook Customized Cobol copybook for
BMS inquire interface

Developing web services and SOA with Enterprise Service Tools 555
 Table 133. Application Components (continued)
Type Comment

Member name in SDFHSAMP

DFH0XM3 Copybook Cobol copybook for BMS
interface to configuration module
DFH0XS1 BMS Mapset BMS Mapset for application user
interface
DFH0XS2 BMS Mapset BMS Mapset for the inquire
operation of the application user
interface
DFH0XS3 BMS Mapset BMS Mapset for the configuration
module

Table 134. CICS Resource Definitions

Resource name Resource type Comment
EXAMPLE CICS Resource definition group CICS resource definitions
required for the example
application
EGUI TRANSACTION Transaction to invoke program
DFH0XGUI to start the BMS
interface to the application
(Customizable)
ECFG TRANSACTION Transaction to invoke the
program DFH0XCFG to start
the example configuration BMS
interface (Customizable)
EXMPCAT FILE File definition of the EXMPCAT
VSAM file for the application
catalog (Customizable)
EXMPCONF FILE File definition of the EXMPCONF
application configuration file.

The catalog manager program

The catalog manager is the controlling program for the business logic of the example application, and all
interactions with the example application pass through it.

To ensure that the program logic is simple, the catalog manager performs only limited type checking and
error recovery.
The catalog manager supports a number of operations. Input and output parameters for each operation
are defined in a single data structure, which is passed to and from the program in a COMMAREA.

COMMAREA structures
This topic describes the COMMAREA structures.

* Catalogue COMMAREA structure

03 CA-REQUEST-ID PIC X(6).

556 Developer for z/OS: Developing with Db2, CICS, and IMS
 03 CA-RETURN-CODE PIC 9(2).
03 CA-RESPONSE-MESSAGE PIC X(79).
03 CA-REQUEST-SPECIFIC PIC X(911).
* Fields used in Inquire Catalog
03 CA-INQUIRE-REQUEST REDEFINES CA-REQUEST-SPECIFIC.
05 CA-LIST-START-REF PIC 9(4).
05 CA-LAST-ITEM-REF PIC 9(4).
05 CA-ITEM-COUNT PIC 9(3).
05 CA-INQUIRY-RESPONSE-DATA PIC X(900).
05 CA-CAT-ITEM REDEFINES CA-INQUIRY-RESPONSE-DATA
OCCURS 15 TIMES.
07 CA-ITEM-REF PIC 9(4).
07 CA-DESCRIPTION PIC X(40).
07 CA-DEPARTMENT PIC 9(3).
07 CA-COST PIC X(6).
07 IN-STOCK PIC 9(4).
07 ON-ORDER PIC 9(3).
* Fields used in Inquire Single
03 CA-INQUIRE-SINGLE REDEFINES CA-REQUEST-SPECIFIC.
05 CA-ITEM-REF-REQ PIC 9(4).
05 FILLER PIC 9(4).
05 FILLER PIC 9(3).
05 CA-SINGLE-ITEM.
07 CA-SNGL-ITEM-REF PIC 9(4).
07 CA-SNGL-DESCRIPTION PIC X(40).
07 CA-SNGL-DEPARTMENT PIC 9(3).
07 CA-SNGL-COST PIC X(6).
07 IN-SNGL-STOCK PIC 9(4).
07 ON-SNGL-ORDER PIC 9(3).
05 FILLER PIC X(840).
* Fields used in Place Order
03 CA-ORDER-REQUEST REDEFINES CA-REQUEST-SPECIFIC.
05 CA-USERID PIC X(8).
05 CA-CHARGE-DEPT PIC X(8).
05 CA-ITEM-REF-NUMBER PIC 9(4).
05 CA-QUANTITY-REQ PIC 9(3).
05 FILLER PIC X(888).

* Dispatcher/Stock Manager COMMAREA structure

03 CA-ORD-REQUEST-ID PIC X(6).
03 CA-ORD-RETURN-CODE PIC 9(2).
03 CA-ORD-RESPONSE-MESSAGE PIC X(79).
03 CA-ORD-REQUEST-SPECIFIC PIC X(23).
* Fields used in Dispatcher
03 CA-DISPATCH-ORDER REDEFINES CA-ORD-REQUEST-SPECIFIC.
05 CA-ORD-ITEM-REF-NUMBER PIC 9(4).
05 CA-ORD-QUANTITY-REQ PIC 9(3).
05 CA-ORD-USERID PIC X(8).
05 CA-ORD-CHARGE-DEPT PIC X(8).
* Fields used in Stock Manager
03 CA-STOCK-MANAGER-UPDATE REDEFINES CA-ORD-REQUEST-SPECIFIC.
05 CA-STK-ITEM-REF-NUMBER PIC 9(4).
05 CA-STK-QUANTITY-REQ PIC 9(3).
05 FILLER PIC X(16).

Return codes
Each operation of the catalog manager can return a number of return codes.

Code Explanation

Type
General 00 Function completed without error
Catalog file 20 Item reference not found
21 Error opening, reading, or ending
browse of catalog file
22 Error updating file

Developing web services and SOA with Enterprise Service Tools 557
 Code Explanation

Type
Configuration file 50 Error opening configuration file
51 Data store type was neither STUB
nor VSAM
52 Outbound Web service switch
was neither Y nor N
Remote Web service 30 The EXEC CICS INVOKE
WEBSERVICE command returned
an INVREQ condition
31 The EXEC CICS INVOKE
WEBSERVICE command returned
an NOTFND condition
32 The EXEC CICS INVOKE
WEBSERVICE command returned
a condition other than INVREQ or
NOTFND
Application 97 Insufficient stock to complete
order
98 Order quantity was not a positive
number
99 DFH0XCMN received a
COMMAREA in which the CA-
REQUEST-ID field was not set
to one of the following: 01INQC,
01INQS, or 01ORDR

INQUIRE CATALOG operation

This operation returns a list of up to 15 catalog items, starting with the item specified by the caller.

Input parameters

CA-REQUEST-ID
A string that identifies the operation. For the INQUIRE CATALOG command, the string contains
"01INQC"
CA-LIST-START-REF
The reference number of the first item to be returned.

Output parameters
CA-RETURN-CODE
CA-RESPONSE-MESSAGE
A human readable string, containing "num ITEMS RETURNED" where num is the number of items
returned.
CA-LAST-ITEM-REF
The reference number of the last item returned.
CA-ITEM-COUNT
The number of items returned.

558 Developer for z/OS: Developing with Db2, CICS, and IMS
CA-CAT-ITEM
An array containing the list of catalog items returned. The array has 15 elements; if fewer than 15
items are returned, the remaining array elements contain blanks.

INQUIRE SINGLE ITEM operation

This operation returns a single catalog item specified by the caller.

Input parameters

CA-REQUEST-ID
A string that identifies the operation. For the INQUIRE SINGLE ITEM command, the string contains
"01INQS"
CA-ITEM-REF-REQ
The reference number of the item to be returned.

Output parameters
CA-RETURN-CODE
CA-RESPONSE-MESSAGE
A human readable string, containing RETURNED ITEM: REF=item-reference' where item-
reference is the reference number of the returned item.
CA-SINGLE-ITEM
An array containing in its first element the returned catalog item.

PLACE ORDER operation

This operation places an order for a single item. If the required quantity is not available a message is
returned to the user. If the order is successful, a call is made to the Stock Manager informing it what item
has been ordered and the quantity ordered.

Input parameters

CA-REQUEST-ID
A string that identifies the operation. For the PLACE ORDER operation, the string contains '01ORDR'
CA-USERID
An 8-character user ID which the application uses for dispatch and billing.
CA-CHARGE-DEPT
An 8-character department ID which the application uses for dispatch and billing.
CA-ITEM-REF-NUMBER
The reference number of the item to be ordered.
CA-QUANTITY-REQ
The number of items required.

Output parameters
CA-RETURN-CODE
CA-RESPONSE-MESSAGE
A human readable string, containing 'ORDER SUCCESSFULLY PLACED'.

Developing web services and SOA with Enterprise Service Tools 559
 DISPATCH STOCK operation
This operation places a call to the stock dispatcher program, which in turn dispatches the order to the
customer.

Input parameters

CA-ORD-REQUEST-ID
A string that identifies the operation. For the DISPATCH ORDER operation, the string contains
'01DSPO'
CA-ORD-USERID
An 8-character user ID which the application uses for dispatch and billing.
CA-ORD-CHARGE-DEPT
An 8-character department ID which the application uses for dispatch and billing.
CA-ORD-ITEM-REF-NUMBER
The reference number of the item to be ordered.
CA-ORD-QUANTITY-REQ
The number of items required.

Output parameters
CA-ORD-RETURN-CODE

NOTIFY STOCK MANAGER operation

This operation takes details of the order that has been placed to decide if stock replenishment is
necessary.

Input parameters

CA-ORD-REQUEST-ID
A string that identifies the operation. For the NOTIFY STOCK MANAGER operation, the string contains
'01STKO'
CA-STK-ITEM-REF-NUMBER
The reference number of the item to be ordered.
CA-STK-QUANTITY-REQ
The number of items required.

Output parameters
CA-ORD-RETURN-CODE

BMS presentation manager

The presentation manager is responsible for all interactions with the end user via 3270 BMS panels. No
business decisions are made in this program.

Data handler
The data handler provides the interface between the catalog manager and the data store.

The example application provides two versions of the data handler:

• The first version uses a VSAM file as the data store.
• The second version is a dummy program that always returns the same data on an inquire and does not
store the results of any update requests.

560 Developer for z/OS: Developing with Db2, CICS, and IMS
 Dispatch manager
The dispatch manager is responsible for dispatching the order to the customer once the order has been
confirmed.

The example application provides two versions of the dispatch manager program:
• The first version is a dummy program that returns a correct response to the caller, but takes no other
action.
• The second version is a Web service requester program that makes a request to the endpoint address
defined in the configuration file.

Order dispatch endpoint

The order dispatch program is a Web service provider program that is responsible for dispatching the item
to the customer.

In the example application, the order dispatcher is a dummy program that returns a correct response
to the caller, but takes no other action. It makes it possible for all configurations of the example Web
services to be operable.

Stock manager
The stock manager is responsible for managing the replenishment of the stock.

In the example program, the stock manager is a dummy program that returns a correct response to the
caller, but takes no other action.

Application configuration
The example application includes a program that lets you configure the base application.

File structures and definitions

The CICS catalog manager example application uses two VSAM files: the catalog file which contains the
details of all items stocked and their stock levels, and the configuration file which holds user-selected
options for the application.

Catalog file
The catalog file is a KSDS VSAM file which contains all information relating to the product inventory.

Records in the file have the following structure:

Name COBOL data type Description

WS-ITEM-REF-NUM PIC 9(4) Item reference number
WS-DESCRIPTION PIC X(40) Item description
WS-DEPARTMENT PIC 9(3) Department identification
number
WS-COST PIC ZZZ.99 Item price
WS-IN-STOCK PIC 9(4) Number of items in stock

Developing web services and SOA with Enterprise Service Tools 561
 Name COBOL data type Description
WS-ON-ORDER PIC 9(3) Number of items on order

Configuration file
The configuration file is a KSDS VSAM file which contains information used to configure the example
application.
The configuration file is a KSDS VSAM file with 3 distinct records, General Information, Outbound URL,
and Catalog file information, as shown in the following tables:

Table 135. General information record

Name COBOL data type Description
PROGS-KEY PIC X(9) Key field for the general
information record, containing
'EXMP-CONF'
filler PIC X
DATASTORE PIC X(4) A character string that specifies
the type of data store program to
be used. Values are:
'STUB'
'VSAM'

filler PIC X
DO-OUTBOUND-WS PIC X A character that specifies
whether the dispatch manager is
make an outbound Web service
request. Values are:
'Y'
'N'

filler PIC X
CATMAN-PROG PIC X(8) The name of the catalog manager
program
filler PIC X
DSSTUB-PROG PIC X(8) The name of the dummy data
handler program
filler PIC X
DSVSAM-PROG PIC X(8) The name of the VSAM data
handler program
filler PIC X
ODSTUB-PROG PIC X(8) The name of the dummy order
dispatcher module
filler PIC X
ODWEBS-PROG PIC X(8) The name of the outbound Web
service order dispatcher program
filler PIC X

562 Developer for z/OS: Developing with Db2, CICS, and IMS
Table 135. General information record (continued)
Name COBOL data type Description
STKMAN-PROG PIC X(8) The name of the stock manager
program
filler PIC X(10)

Table 136. Outbound URL record

Name COBOL data type Description
URL-KEY PIC X(9) Key field for the general
information record, containing
'OUTBNDURL'
filler PIC X
OUTBOUND-URL PIC X(255) Outbound URL for the order
dispatcher Web service request

Table 137. Catalog file information

Name COBOL data type Description
URL-FILE-KEY PIC X(9) Key field for the general
information record, containing
'VSAM-NAME'
filler PIC X
CATALOG-FILE-NAME PIC X(8) Name of the CICS FILE resource
used for the catalog file

Developing web services and SOA with Enterprise Service Tools 563
564 Developer for z/OS: Developing with Db2, CICS, and IMS
Documentation notices
© International Business Machines Corporation 1992, 2024.

This information was developed for products and services offered in the US. This material might be
available from IBM in other languages. However, you may be required to own a copy of the product or
product version in that language in order to access it.
IBM may not offer the products, services, or features discussed in this document in other countries.
Consult your local IBM representative for information on the products and services currently available in
your area. Any reference to an IBM product, program, or service is not intended to state or imply that
only that IBM product, program, or service may be used. Any functionally equivalent product, program, or
service that does not infringe any IBM intellectual property right may be used instead. However, it is the
user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service.
IBM may have patents or pending patent applications covering subject matter described in this
document. The furnishing of this document does not grant you any license to these patents. You can
send license inquiries, in writing, to [email protected].
INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS"
WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED
TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A
PARTICULAR PURPOSE. Some jurisdictions do not allow disclaimer of express or implied warranties in
certain transactions, therefore, this statement may not apply to you.
This information could include technical inaccuracies or typographical errors. Changes are periodically
made to the information herein; these changes will be incorporated in new editions of the publication.
IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this
publication at any time without notice.
Any references in this information to non-IBM websites are provided for convenience only and do not in
any manner serve as an endorsement of those websites. The materials at those websites are not part of
the materials for this IBM product and use of those websites is at your own risk.
IBM may use or distribute any of the information you provide in any way it believes appropriate without
incurring any obligation to you.
Licensees of this program who wish to have information about it for the purpose of enabling: (i)
the exchange of information between independently created programs and other programs (including
this one) and (ii) the mutual use of the information which has been exchanged, should contact
[email protected].
Such information may be available, subject to appropriate terms and conditions, including in some cases,
payment of a fee.
The licensed program described in this document and all licensed material available for it are provided by
IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement or any
equivalent agreement between us.
Any performance data and client examples cited are presented for illustrative purposes only. Actual
performance results may vary depending on specific configurations and operating conditions.
Information concerning non-IBM products was obtained from the suppliers of those products, their
published announcements or other publicly available sources. IBM has not tested those products and
cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM
products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of
those products.
Statements regarding IBM's future direction or intent are subject to change or withdrawal without notice,
and represent goals and objectives only. Such statements should not be relied upon when making
purchasing decisions.

© Copyright IBM Corp. 1992, 2024 565

 This information contains examples of data and reports used in daily business operations. To illustrate
them as completely as possible, the examples include the names of individuals, companies, brands, and
products. All of these names are fictitious and any similarity to the names and addresses used by actual
people or business enterprises is entirely coincidental.
COPYRIGHT LICENSE:
This information contains sample application programs in source language, which illustrate programming
techniques on various operating platforms. You may copy, modify, and distribute these sample programs
in any form without payment to IBM, for the purposes of developing, using, marketing or distributing
application programs conforming to the application programming interface for the operating platform
for which the sample programs are written. These examples have not been thoroughly tested under
all conditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of these
programs. The sample programs are provided "AS IS", without warranty of any kind. IBM shall not be
liable for any damages arising out of your use of the sample programs.
Each copy or any portion of these sample programs or any derivative work must include a copyright notice
as follows:

© (your company name) (year).

Portions of this code are derived from IBM Corp. Sample Programs.
© International Business Machines Corporation _enter the year or years_.

Trademarks
IBM, the IBM logo, and ibm.com are trademarks or registered trademarks of International Business
Machines Corporation, registered in many jurisdictions worldwide. Other product and service names
might be trademarks of IBM or other companies. A current list of IBM trademarks is available at
"Copyright and trademark information" at www.ibm.com/legal/copytrade.shtml.

Terms and conditions for product documentation

Permissions for the use of these publications are granted subject to the following terms and conditions.

Applicability
These terms and conditions are in addition to any terms of use for the IBM website.

Personal use
You may reproduce these publications for your personal, noncommercial use provided that all proprietary
notices are preserved. You may not distribute, display or make derivative work of these publications, or
any portion thereof, without the express consent of IBM.

Commercial use
You may reproduce, distribute and display these publications solely within your enterprise provided
that all proprietary notices are preserved. You may not make derivative works of these publications, or
reproduce, distribute or display these publications or any portion thereof outside your enterprise, without
the express consent of IBM.

Rights
Except as expressly granted in this permission, no other permissions, licenses or rights are granted, either
express or implied, to the publications or any information, data, software or other intellectual property
contained therein.

566 Developer for z/OS: Developing with Db2, CICS, and IMS
IBM reserves the right to withdraw the permissions granted herein whenever, in its discretion, the use
of the publications is detrimental to its interest or, as determined by IBM, the above instructions are not
being properly followed.
You may not download, export or re-export this information except in full compliance with all applicable
laws and regulations, including all United States export laws and regulations.
IBM MAKES NO GUARANTEE ABOUT THE CONTENT OF THESE PUBLICATIONS. THE PUBLICATIONS
ARE PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED,
INCLUDING BUT NOT LIMITED TO IMPLIED WARRANTIES OF MERCHANTABILITY, NON-INFRINGEMENT,
AND FITNESS FOR A PARTICULAR PURPOSE.

Documentation notices 567

568 Developer for z/OS: Developing with Db2, CICS, and IMS
Security considerations
This topic highlights some of the security limitations that you might encounter with this application. To
help ensure the security of your installation, customize your security settings and set up user access
controls.

Enabling security during the installation process

Security configuration for Developer for z/OS is addressed in Security definitions. More details on all
security aspects can be found in Security considerations.
Security considerations for Developer for z/OS:
• Installing Developer for z/OS results in a basic configuration with default settings for a basic, secure
setup. Extra configuration tasks, such as configuring SSL, allow for tighter controls. This information is
covered in detail in Security considerations.
Note: Security is not fully enabled during the installation process and must be enabled during
customization after installation is complete. The customization of some security-related aspects must
be completed for the product to work and for certain security features to be enabled. This limitation
applies to silent installations.
• Security for Developer for z/OS on the host is configured through a combination of Developer for z/OS
configuration files and RACF® commands (or other similar security products).
• Developer for z/OS does not provide a login option when the Developer for z/OS host is used as an LDAP
client that accesses a customer-specific LDAP server to get group membership information that is used
to enforce wanted client behavior. LDAP logon information can be provided in a configuration file when
the Developer for z/OS host is used as an LDAP client that accesses public certificate revocation lists
(CRLs).
• Security for Developer for z/OS database authentication is enabled through RACF commands.
• For information about setting up SSL and installing a custom certificate, see these topics in the IBM
Explorer for z/OS documentation: (Optional) ssl.properties, the RSE encrypted communication, RSE -
ssl.properties, and Setting up encrypted communication and X.509 authentication.
• For information about enabling security between the client and server or web client and server, see
Connection flow.
• To configure the security settings of other applications that communicate with Developer for z/OS (Db2
Connect, Debug Tool, Fault Analyzer, File Manager), use the security configuration options available in
those products.
• To verify that you correctly configured the security settings, see Verify the security settings.
• More information:
– With the host connection in Enterprise Service Tools, you can set up a terminal session with a remote
z/OS system. You can configure the session to use SSL, client authentication, and host authentication.
You can use the IBM Key Management tool iKeyman to create a key database file, to create or request
certificates, and to import and export certificates.
Note: Developer for z/OS also uses REXEC, or the more secure SSH, to compile UNIX System Services
projects. For more information, see z/OS UNIX subprojects.

Enabling secure communication between multiple applications

For integrated products, Developer for z/OS provides security for the communications between the
products through the Developer for z/OS communication configuration by using Developer for z/OS tools.
The communication is host only, so there is no encryption.

© Copyright IBM Corp. 1992, 2024 569

 To handle user access controls between products in Developer for z/OS, the receiving application (for
example, JMON) requires authentication, which is done by the calling application (RSE) on the user’s
behalf. Where possible (for example, JMON or CARMA), Developer for z/OS binds to the loopback stack
only, which can be reached only from the same system.
For single-sign on, the user authenticates with RSE. RSE then does authentications on the user’s behalf
for other servers. While the user stays within Developer for z/OS, it all looks like one server, but this
situation is not true for other servers. Users must manually authenticate for other servers outside of
Developer for z/OS.

Ports, protocols, and services

Developer for z/OS internal processes, tasks, or services do not require a fixed user ID. You can create
your own user ID for these processes, tasks, or services, and associate the user ID with them by using
RACF commands. For more information about what ports, protocols, and services Developer for z/OS
uses, see Planning and TCP/IP considerations.
Before you can connect to a remote system from the Developer for z/OS client, you must define
a connection for the remote system and specify connection properties. For more information about
connecting to a remote system and the ports that are used for a connection, see Creating a connection to
a z/OS system.

Customizing your security settings

Customizing your security settings is covered in Security considerations. For more information about
setting and changing passwords, and client certificate authentication, see these topics:
• Connecting to a remote system
• Changing your password
• Creating a connection by using client certificate authentication
• Setting preferences for client certificate authentication
Note: Developer for z/OS uses generated PassTickets and does not store passwords on the host. The
Remote Connection Emulator (RCE) stores SSL-related passwords in the Eclipse Secure Storage. For more
information, see Secure storage in the Eclipse documentation. Clients mask password fields with ***, and
a password that is provided by a client during logon is always transmitted in a masked format, even for
SSL encrypted communication.
To enable multiple levels of security, and determine the implications of each, see the various chapters
about security in the host configuration documentation. Each chapter addresses a specific aspect of
security configuration.
Developer for z/OS relies on the options that are offered by TCP/IP to set up notifications of security
breaches or attempts.
Note: Information about login attempts is stored in the Developer for z/OS server logs, and in various
other places (for example, server log, user logs, audit log, syslog).

Multi-Factor Authentication
Developer for z/OS relies on IBM Explorer for z/OS for multi-factor authentication (MFA) support. For
information about configuring MFA in IBM Explorer for z/OS, see Using Multi-Factor Authentication.

Setting up user roles and access

RACF commands are used for the following purposes:
• Create and delete users and set their access levels.
• Create groups and assign them privileges.
• Establish password rules for users (such as no reuse, minimum length, or character requirements).

570 Developer for z/OS: Developing with Db2, CICS, and IMS
• Setup superuser IDs or IDs with special security privileges.
For more information about RACF, see the Security Server RACF Security Administrator's Guide,
SA23-2289.

Privacy policy considerations

This software offering does not use cookies or other technologies to collect personally identifiable
information.

Security considerations 571

572 Developer for z/OS: Developing with Db2, CICS, and IMS
IBM®

Product Number: 5755-A05

5724-T07