e*Way Intelligent Adapter for CICS User’s Guide (Monk Version)
iWay Transaction Adapter for CICS User's Guide
-
Upload
leandro-gabriel-lopez -
Category
Documents
-
view
241 -
download
0
Transcript of iWay Transaction Adapter for CICS User's Guide
-
7/28/2019 iWay Transaction Adapter for CICS User's Guide
1/192
iWay TransactionAdapter for CICS User's Guide
Version 5 Release 5 Service Manager (SM)
iWay
DN3501778.1106
-
7/28/2019 iWay Transaction Adapter for CICS User's Guide
2/192
EDA, EDA/SQL, FIDEL, FOCCALC, FOCUS, FOCUS Fusion, FOCUS Vision, Hospital-Trac, Information Builders, theInformation Builders logo, Parlay, PC/FOCUS, SmartMart, SmartMode, SNAPpack, TableTalk, WALDO, Web390,WebFOCUS and WorldMART are registered trademarks, and iWay and iWay Software are trademarks of InformationBuilders, Inc.
Due to the nature of this material, this document refers to numerous hardware and software products by theirtrademarks. In most, if not all cases, these designations are claimed as trademarks or registered trademarks by therespective companies. It is not this publishers intent to use any of these names generically. The reader is thereforcautioned to investigate all claimed trademark rights before using any of these names other than to refer to theproduct described.
Copyright 2006, by Information Builders, Inc. and iWay Software. All rights reserved. Patent Pending. This manuaor parts thereof, may not be reproduced in any form without the written permission of Information Builders, Inc.
-
7/28/2019 iWay Transaction Adapter for CICS User's Guide
3/192
iWay
Contents
Preface................................................................................................................7
Documentation Conventions..............................................................................................8
Related Publications..........................................................................................................
Customer Support.............................................................................................................
Help Us to Serve You Better...............................................................................................
User Feedback................................................................................................................1
iWay Software Training and Professional Services..............................................................1
1. Introducing the iWay Transaction Adapter for CICS......................................13Overview.........................................................................................................................1
The iWay Transaction Adapter for CICS.............................................................................1
CICS Programs........................................................................................................1
Software Requirements for the Adapter.....................................................................16
Deployment Information for Your iWay Adapter..................................................................1
iWay Service Manager..............................................................................................1
iWay Explorer..........................................................................................................18
iWay Business Services Provider (iBSP).....................................................................18
iWay Enterprise Connector for J2EE Connector Architecture (JCA)................................1
Information Roadmap......................................................................................................1
2. Configuring the Adapter................................................................................21
Starting iWay Explorer (Java Servlet).................................................................................2
Configuring a Connection to CICS.....................................................................................2
Managing a Connection to CICS.......................................................................................3
3. Creating XML Schemas and iWay Business Services....................................37
Creating an Adapter Transaction.......................................................................................3Sample Program IWAYSRV0.....................................................................................39
Cobol Descriptions for Input and Output Communications...........................................4
Modifying COBOL DD Field Definitions.......................................................................4
Creating Schemas for an Adapter Transaction...................................................................4
iWay Transaction Adapter for CICS User's Guide
-
7/28/2019 iWay Transaction Adapter for CICS User's Guide
4/192
Understanding iWay Business Services.............................................................................48
Creating a Web Service............................................................................................48
Testing the Web Service...........................................................................................5
Generating WSDL From a Web Service......................................................................5
Identity Propagation.................................................................................................5
Creating an Event Port.....................................................................................................5
Creating an Event Port From the iWay Events Tab.......................................................5
Managing an Event Port...................................................................................................7
Creating a Channel..........................................................................................................7
Managing a Channel........................................................................................................7
4. Configuring the Adapter in iWay Designer.....................................................81
Using the Adapter in iWay Designer..................................................................................8
A. Configuring the Adapter in an iWay Environment..........................................89
Configuring the Adapter in Service Manager......................................................................9
Configuring the Adapter in Adapter Manager......................................................................9
B. Configuring VTAM for AnyNet........................................................................97
VTAM and AnyNet Configuration Requirements..................................................................98
TCP 6.2 AnyNet Set-up Samples for the VTAM Administrator...............................................98
TCP 6.2 AnyNet Set-up Samples for the CICS Administrator................................................9
Post-Configuration Steps...............................................................................................10Error Conditions............................................................................................................10
VTAM BIND Failures...............................................................................................10
Connect Failures Module BPX1AI0..........................................................................108
C. Running the Adapter Using LU6.2 Communication......................................109
MVS OS/390 APPC Communication...............................................................................110
LU6.2 Set up on MVS............................................................................................110
LU6.2 Set up on CICS............................................................................................11
Microsoft SNA Server Communication.............................................................................11LU6.2 Setup on a Windows SNA Server...................................................................11
Application Run-Time Requirements................................................................................11
4 iWay Softwar
Contents
-
7/28/2019 iWay Transaction Adapter for CICS User's Guide
5/192
D. Running the Adapter Using TCP/IP Communication....................................117
MVS OS/390 TCP/IP Communication.............................................................................11
TCP/IP Requirements............................................................................................118
E. Using Adabas/Natural Programs.................................................................119Overview.......................................................................................................................12
Installing the Adabas/Natural Interface...........................................................................12
Writing and Configuring a Natural Program......................................................................12
F. Installing the Sample IWAYIVP and IWAYSRV0 Programs in CICS..............129
Installing and Configuring IWAYIVP..................................................................................130
Installing and Configuring IWAYSRV0..............................................................................133
G. Sample Requests, Schemas, and Cobol File Descriptions..........................137
Request Document for the Generic Transaction, IWAYIVP.................................................13
Request Schema for IWAYIVP.........................................................................................13
Response Schema for IWAYIVP......................................................................................140
Request Documents for IWAYSRV0.................................................................................14
Request Schema for IWAYSRV0.....................................................................................142
Response Schema for IWAYSRV0...................................................................................14
Request Document for AASNATN....................................................................................14
Request Schema for AASNATN.......................................................................................14
Response Schema for the Program AASNATN..................................................................14Sample Cobol File Descriptions......................................................................................14
H. Sample Programs........................................................................................149
IWAYIVP Program..........................................................................................................150
IWAYSRV0 Program.......................................................................................................15
IWAYEVT0 Program........................................................................................................156
IWAYEVT1 Program........................................................................................................16
Natural Program............................................................................................................17
I. Debugging and Troubleshooting...................................................................185
Troubleshooting............................................................................................................186
Data Type Conversions..................................................................................................18
iWay Transaction Adapter for CICS User's Guide
Contents
-
7/28/2019 iWay Transaction Adapter for CICS User's Guide
6/192
Reader Comments...........................................................................................191
6 iWay Softwar
Contents
-
7/28/2019 iWay Transaction Adapter for CICS User's Guide
7/192
iWay
Preface
This documentation describes how to configure and use the iWay Transaction Adapter forCICS.
How This Manual Is Organized
This manual includes the following chapters:
ContentsChapter/Appendix
Introduces the adapter environment.Introducing the iWayTransaction Adapter forCICS
1
Describes how to configure a connection to theadapter.
Configuring the Adapter2
Describes how to create transactions and events forthe adapter. It also provides information on how touse the generated schemas to listen for events inCICS and create iWay Business Services, whichexpose functionality as Web services.
Creating XML Schemas andiWay Business Services
3
Describes how to configure the adapter in iWayDesigner.
Configuring the Adapter iniWay Designer
4
Describes how to configure the adapter in the ServiceManager or Adapter Manager console.
Configuring the Adapter inan iWay Environment
A
Provides examples of the major VTAM nodes forAnyNet operation and connection and sessiondefinitions required for the adapter to connect toCICS.
Configuring VTAM for AnyNetB
Contains technical information that you can use asa guide to ensure LU6.2 communication to the CICS
region.
Running the Adapter UsingLU6.2 Communication
C
Contains technical information that you can use asa guide to ensure TCP/IP communication to the CICSregion.
Running the Adapter UsingTCP/IP Communication
D
iWay Transaction Adapter for CICS User's Guide
-
7/28/2019 iWay Transaction Adapter for CICS User's Guide
8/192
ContentsChapter/Appendix
Describes how to use Adabas/Natural programs withthe iWay Transaction Adapter for CICS.
Using Adabas/NaturalPrograms
E
Describes how to verify correct installation of theadapter.
Installing the SampleIWAYIVP and IWAYSRV0Programs in CICS
F
Provides documents and schemas for the sampleprograms and the Cobol descriptions used as inputfor the sample CICS transactions.
Sample Requests,Schemas, and Cobol FileDescriptions
G
Describes sample CICS programs provided with theinstallation.
Sample ProgramsH
Includes tips and techniques for debugging theadapter.
Debugging andTroubleshooting
I
Documentation Conventions
The following table lists and describes the conventions that apply in this manual.
DescriptionConvention
Denotes syntax that you must enter exactly as shown.THIS TYPEFACE orthis typeface
Represents a placeholder (or variable), a cross-reference, or an
important term. It may also indicate a button, menu item, or dialogbox option you can click or select.
this typeface
Indicates a default setting.underscore
Highlights a file name or command.this typeface
Indicates keys that you must press simultaneously.Key + Key
Indicates two or three choices; type one of them, not the braces.{ }
Separates mutually exclusive choices in syntax. Type one of them,not the symbol.
|
Indicates that you can enter a parameter multiple times. Type onlythe parameter, not the ellipsis points (...).
...
8 iWay Softwar
Documentation Conventions
-
7/28/2019 iWay Transaction Adapter for CICS User's Guide
9/192
DescriptionConvention
Indicates that there are (or could be) intervening or additionalcommands.
.
.
.
Related Publications
To view a current listing of our publications and to place an order, visit our World Wide Wesite, http://www.iwaysoftware.com. You can also contact the Publications Order Departmenat (800) 969-4636.
Customer Support
Do you have questions about this product?
Call Information Builders Customer Support Services (CSS) at (800) 736-6130 or (212) 7366130. Customer Support Consultants are available Monday through Friday between 8:00A.M. and 8:00 P.M. EST to address all your questions. Information Builders consultants caalso give you general guidance regarding product capabilities and documentation. Be prepareto provide your six-digit site code (xxxx.xx) when you call.
You can also access support services electronically, 24 hours a day, with InfoResponseOnline. InfoResponse Online is accessible through our World Wide Web site,http://techsupport.iwaysoftware.com/. You can connect to the tracking system and knownproblem database at the Information Builders support center. Registered users can open,
update, and view the status of cases in the tracking system and read descriptions of reportesoftware issues. New users can register immediately for this service. The technical supporsection also provides usage techniques, diagnostic tips, and answers to frequently askedquestions.
To learn about the full range of available support services, ask your Information Buildersrepresentative about InfoResponse Online, or call (800) 969-INFO.
Help Us to Serve You Better
To help our consultants answer your questions effectively, be prepared to providespecifications and sample files and to answer questions about errors and problems.
The following tables list the environment information our consultants require.
Platform
Operating System
iWay Transaction Adapter for CICS User's Guide
Preface
http://www.iwaysoftware.com/http://techsupport.iwaysoftware.com/http://techsupport.iwaysoftware.com/http://www.iwaysoftware.com/ -
7/28/2019 iWay Transaction Adapter for CICS User's Guide
10/192
OS Version
JVM Vendor
JVM Version
The following table lists the deployment information our consultants require.
For example, JCA, Business Services Provider, iWayService Manager
Adapter Deployment
For example, WebSphereContainer
Version
Enterprise Information
System (EIS) - if any
EIS Release Level
EIS Service Pack
EIS Platform
The following table lists iWay-related information needed by our consultants.
iWay Adapter
iWay Release Level
iWay Patch
The following table lists the types of iWay Explorer. Specify the version (and platform, ifdifferent than listed previously) in the columns provided.
PlatformVersioniWay Explorer Type
Swing
Servlet
ASP
Eclipse
Embedded in iWay Designer
The following table lists additional questions to help us serve you better.
Error/Problem Details or InformationRequest/Question
Did the problem arise througha service or event?
10 iWay Softwar
Help Us to Serve You Better
-
7/28/2019 iWay Transaction Adapter for CICS User's Guide
11/192
Error/Problem Details or InformationRequest/Question
Provide usage scenarios orsummarize the applicationthat produces the problem.
When did the problem start?Can you reproduce thisproblem consistently?
Describe the problem.
Describe the steps toreproduce the problem.
Specify the error message(s).
Anychange in theapplication environment:software configuration,EIS/database configuration,application, and so forth?
Under what circumstancedoes the problem not occur?
Following is a list of error/problem files that might be applicable.
Input documents (XML instance, XML schema, non-XML documents)
Transformation files
Error screen shots
Error output files
Trace files
Service Manager package to reproduce problem
Custom functions and agents in use
Diagnostic Zip
Transaction log
For information on tracing, see the iWay Service Manager User's Guide.
iWay Transaction Adapter for CICS User's Guide 1
Preface
-
7/28/2019 iWay Transaction Adapter for CICS User's Guide
12/192
User Feedback
In an effort to produce effective documentation, the Documentation Services staff welcomeyour opinions regarding this manual. Please use the Reader Comments form at the end ofthis manual to communicate suggestions for improving this publication or to alert us to
corrections. You can also go to our Web site, http://www.iwaysoftware.com and use theDocumentation Feedback form.
Thank you, in advance, for your comments.
iWay Software Training and Professional Services
Interested in training? Our Education Department offers a wide variety of training coursesfor iWay Software and other Information Builders products.
For information on course descriptions, locations, and dates, or to register for classes, visour World Wide Web site, http://www.iwaysoftware.com/support/education.html, or call (800
969-INFO to speak to an Education Representative.
Interested in technical assistance for your implementation? Our Professional Servicesdepartment provides expert design, systems architecture, implementation, and projectmanagement services for all your business integration projects. For information, visit ourWorld Wide Web site, http://www.iwaysoftware.com/support/services.html.
12 iWay Softwar
User Feedback
http://www.iwaysoftware.com/http://www.iwaysoftware.com/support/education.htmlhttp://www.iwaysoftware.com/support/services.htmlhttp://www.iwaysoftware.com/support/services.htmlhttp://www.iwaysoftware.com/support/education.htmlhttp://www.iwaysoftware.com/ -
7/28/2019 iWay Transaction Adapter for CICS User's Guide
13/192
iWay
Introducing the iWay Transaction Adapter for
CICS
1
Topics:This section describes the iWayTransaction Adapter for CICS. Theadapter supports automatic transactioninvocation, message transformation, anderror recovery. The adapter enablesapplications to call CICS programs and
to work with the native features andsyntax of CICS .
Overview
The iWay Transaction Adapter for CICS
Deployment Information for Your iWay
Adapter
Information Roadmap
iWay Transaction Adapter for CICS User's Guide 1
-
7/28/2019 iWay Transaction Adapter for CICS User's Guide
14/192
Overview
The iWay Transaction Adapter for CICS enables you to execute Customer Information ControSystem (CICS) programs. The advantages of using this adapter include:
No modification required to existing CICS programs.
No installation of new code required on CICS.
Adapter processing performed off of the mainframe.
Configuration by metadata--no coding required.
Support for older versions of CICS.
Support for CICS COMMAREA programs.
The following diagram illustrates the framework for executing CICS programs with iWay
Explorer and the iWay Transaction Adapter for CICS.
The following bidirectional scenarios are supported by the adapter:
CICS services
CICS events
14 iWay Softwar
Overview
-
7/28/2019 iWay Transaction Adapter for CICS User's Guide
15/192
The iWay Transaction Adapter for CICS
In this section:
CICS Programs
Software Requirements for the Adapter
The following diagram shows how to use AnyNet to connect to the CICS region. When usinCICS Transaction Server Version 2 Release 2 or higher, you can use straight TCP/IP (optional
The adapter is the component that connects to CICS. It is hosted in a container that support
events. The adapter enables the following functions:
Connecting to CICS.
Executing COMMAREA programs.
Mapping XML messages to and from CICS data structures.
Listening for events triggered in CICS.
The adapter enables you to invoke a CICS program by sending a request and retrieving theresponse.
The adapter sends the request to execute a transaction over the Multi-Platform TransportNetwork (MPTN, also known as AnyNet). This enables the adapter to use TCP/IP to sendthe request although CICS is expecting LU6.2 (also known as APPC).
The adapter attaches the CICS Mirror transaction, CPMI, which is the standard ExternalCommunication Interface (ECI) transaction for ASCII clients.
iWay Transaction Adapter for CICS User's Guide 1
Introducing the iWay Transaction Adapter for CICS
-
7/28/2019 iWay Transaction Adapter for CICS User's Guide
16/192
At design time, you describe the request and response messages by mapping them to Cobodescriptions.
Note:
Because distributed transactions are not supported, the synchronization level fordistributed is CONFIRM.
Currently, an extended call (executing several program calls in one unit of work) is notsupported.
CICS Programs
The two main types of CICS programs are:
COMMAREA programs that are designed to be called by other CICS programs.
3270 programs that read and write terminal screen maps using Basic Mapping Suppor
(BMS).
Because the adapter can execute only COMMAREA programs, this distinction is important
To execute 3270 programs, you require a screen scraper such as the iWay Terminal EmulatioAdapter for 3270. For many years CICS applications were structured so that the businessprocessing, as opposed to the screen dialogue, was in COMMAREA programs. Therefore, imany cases, executing a COMMAREA program is recommended for application integration
Software Requirements for the Adapter
The following are the software requirements for the adapter:
OS/390 v2.6 or higher; or z/OS.
TCP/IP communication available to the adapter.
VTAM AnyNet option (for CICS Transaction Server Version 2 Release 1 or earlier).
One of the following releases of CICS:
CICS Transaction Server for z/OS, Version 2 Release 2.
CICS Transaction Server for z/OS, Version 2 Release 3.
CICS Transaction Server for OS/390, Version 1 Release 2 or higher.
IBM CICS/ESA, Version 4 Release 1.
CICS Transaction Server for VSE/ESA, Version 1.1.0 or higher.
CICS for VSE/ESA, Version 2.3.
16 iWay Softwar
The iWay Transaction Adapter for CICS
-
7/28/2019 iWay Transaction Adapter for CICS User's Guide
17/192
CICS for IBM OS/400, Version 4.4.
TXSeries, Version 4.2 (HP-UX); TXSeries, Version 4.3 with PTF 4 (Windows NT, AIX,SunSM Solaris operating environment); or TXSeries, Version 5.0 (AIX and Windows
For Adabas/Natural execution, Adabas and Natural must be installed and configuredwithin the CICS region.
Deployment Information for Your iWay Adapter
In this section:
iWay Service Manager
iWay Explorer
iWay Business Services Provider (iBSP)
iWay Enterprise Connector for J2EE Connector Architecture (JCA)
Your iWay adapter works in conjunction with one of the following components:
iWay Service Manager
iWay Business Services Provider (iBSP)
Enterprise Connector for J2EE Connector Architecture (JCA)
When hosted in an iWay environment, the adapter is configured through iWay Service Manage
and iWay Explorer. iWay Explorer is used to configure system connections, create Webservices, and configure event capabilities. Service Manager can access this configurationinformation through the iWay55sm repository to create a robust integration solution.
When the adapter is hosted in a third-party application server environment, you can configuriWay Explorer to work in a Web services environment or in conjunction with the iWay Connectofor JCA. When working in a JCA environment, the connector uses the Common Client Interfac(CCI) to provide fast integration services using adapters instead of using Web services.
iWay Service Manager
iWay Service Manager is the heart of the Universal Adapter Framework and is an open
transport service bus. Service Manager uses graphical tools to create sophisticated integratioservices without writing custom integration code by:
Creating metadata from target applications.
Transforming and mapping interfaces.
iWay Transaction Adapter for CICS User's Guide 1
Introducing the iWay Transaction Adapter for CICS
-
7/28/2019 iWay Transaction Adapter for CICS User's Guide
18/192
Managing stateless processes.
Its capability to manage complex adapter interactions makes it ideally suited to be thefoundation of a service-oriented architecture
iWay Explorer
iWay Explorer uses a tree metaphor to introspect a system for metadata. The explorer enableyou to create XML schemas and Web services for the associated object. In addition, youcan create ports and channels to listen for events in a system. External applications thataccess a system through the adapter use either XML schemas or Web services to pass datbetween the external application and the adapter.
iWay Business Services Provider (iBSP)
The iWay Business Services Provider (iBSP) exposesas Web servicesenterprise assetthat are accessible from adapters regardless of the programming language or the particulaoperating system.
iBSP simplifies the creation and execution of Web services when running:
Custom and legacy applications.
Database queries and stored procedures.
Packaged applications.
Terminal emulation and screen-based systems.
Transactional systems.
Coupled with a platform and language independent messaging protocol called SOAP (SimplObject Access Protocol), XML enables application development and integration by assemblinpreviously built components from multiple Web services.
iWay Enterprise Connector for J2EE Connector Architecture
(JCA)
The iWay Enterprise Connector for J2EE Connector Architecture (JCA) enables developers oJCA-compliant applications to deploy iWay adapters as JCA resources. The connector issupported on J2EE-compliant application servers, such as your application server. The
Connector for JCA is distributed as a standard Resource Adapter Archive (RAR) for deploymento the application server. Thus, the connector can be used in systems that are non-compliantalthough services such as pooled connections are not available.
18 iWay Softwar
Deployment Information for Your iWay Adapter
-
7/28/2019 iWay Transaction Adapter for CICS User's Guide
19/192
Information Roadmap
The following table lists the location of deployment and user information for components othe iWay Transaction Adapter for CICS.
Chapter/ManualDeployment Option
Appendix A of this guide
iWay Service Manager User's Guide
iWay Service Manager
Chapters 4 and 5 of this guide
iWay 5.5 SM Installation and Configuration
iWay Explorer
iWay 5.5 SM Installation and Configuration
manual
iWay Business Services Provider (iBSP)
iWay Connector for J2EE Connector
Architecture User's Guide
iWay 5.5 SM Installation and Configuration
manual
iWay Enterprise Connector for J2EEConnector Architecture (JCA)
iWay Transaction Adapter for CICS User's Guide 1
Introducing the iWay Transaction Adapter for CICS
-
7/28/2019 iWay Transaction Adapter for CICS User's Guide
20/192
20 iWay Softwar
Information Roadmap
-
7/28/2019 iWay Transaction Adapter for CICS User's Guide
21/192
iWay
Configuring the Adapter2
Topics:At design time, you use iWay Explorer(Java Servlet) to create the configurationand metadata the adapter requires atrun time. This section describes how toconfigure a connection to CICS.
Starting iWay Explorer (Java Servlet)
Configuring a Connection to CICS
Managing a Connection to CICS
iWay Transaction Adapter for CICS User's Guide 2
-
7/28/2019 iWay Transaction Adapter for CICS User's Guide
22/192
Starting iWay Explorer (Java Servlet)
How to:
Start iWay Explorer (Java Servlet)
iWay Explorer (Java Servlet) is a GUI tool that works in conjunction with adapters to createschemas and Web services for use with iWay components or other XML or Web servicesbased programs. iWay Explorer is a Web application accessible through a Web browser. Itmust be deployed through an application server or servlet container. For more informationon configuring iWay Explorer, see the iWay 5.5 SM Installation and Configurationdocumentation. Before you can use iWay Explorer, you must start iWay 5.5 Service Manage
How to Start iWay Explorer (Java Servlet)Procedure:
To start iWay Explorer (Java Servlet):
1. Ensure the server is started where iWay Explorer is running.
2. Type the following URL in your browser window
http://hostname:port/iwae/index.html
where:
hostname
Is the name of the server where Service Manager is installed.
port
Is the SOAP port number for the server. The default SOAP port is 9000.
iWay Explorer opens.
The Available Hosts drop-down list appears in the upper-right corner. Three tabs appeanear the top of the iWay Explorer window. From left to right they are:
iWay Adapters, where you create and manage connections to CICS.
iWay Events, where you configure CICS event listening.
iWay Business Services, where you create and view business services.
The left pane of the window contains an expandable list of adapter nodes (based onthe adapters installed), events, or business services, depending on the tab that isselected. The right pane provides the details of the selected adapter, event, or servicand is the work area where you define and modify adapter functions and services.
22 iWay Softwar
Starting iWay Explorer (Java Servlet)
-
7/28/2019 iWay Transaction Adapter for CICS User's Guide
23/192
The Available Hosts drop-down list specifies to which Servlet iBSP instance or JCAinstance you connect.
For more information on accessing different instances of a JCA installation or a ServleiBSP, see the iWay 5.5 SM Installation and Configuration documentation.
You are now ready to define a target to CICS.
Configuring a Connection to CICS
How to:
Configure a Connection to CICS
Set Connection Parameters for AnyNet
Set Connection Parameters for SNA
Set Connection Parameters for TCP/IP
Set Advanced Parameters
Connect to a Defined CICS Target
To access CICS, you must configure a connection through the adapter, known as a target.After the connection is created, it is automatically saved. You must establish a connectioto CICS every time you start iWay Explorer or after disconnecting from a target.
How to Configure a Connection to CICSProcedure:
To configure a connection to CICS:
1. In the left pane of iWay Explorer, expand the iWay Adapters node.
2. Select the CICS node.
3. In the right pane, move your pointer over Operations and select Define a new target.
iWay Transaction Adapter for CICS User's Guide 2
Configuring the Adapter
-
7/28/2019 iWay Transaction Adapter for CICS User's Guide
24/192
The Add a new CICS target dialog box opens in the right pane, as shown in the followinimage.
a. In the Target Name field, type a name for the new target, for example,CICS_Connection.
b. In the Description field, type a brief description (optional).
c. From the Target Type drop-down list, select the type of target, for example, AnyNet
4. Click Next.
The Set connection info pane opens for the selected target.
Note: The CICS connection parameters are consistent with those found in your CICSsystem. For more information on parameter values that are specific to your CICSconfiguration, consult your CICS system administrator. This information should be thesame for all transactions and messages in a single CICS system.
a. If you selected AnyNet as the type of target, proceed to How to Set ConnectionParameters for AnyNet on page 25.
b. If you selected SNA as the type of target, proceed to How to Set ConnectionParameters for SNA on page 28.
c. If you selected TCP/IP as the type of target, proceed to How to Set ConnectionParameters for TCP/IPon page 30.
24 iWay Softwar
Configuring a Connection to CICS
-
7/28/2019 iWay Transaction Adapter for CICS User's Guide
25/192
How to Set Connection Parameters for AnyNetProcedure:
If you selected CICS via AnyNet, the Set connection info pane opens. It contains ConnectionRegion, and Advanced tabs. The Connection tab displays by default.
The following image shows the Set connection info pane that opens to the Connection tabwhich contains three text fields for entry and three active buttons (Back, Finish, and Cancel
1. Type values for the connection parameters.
The following table lists and defines the connection parameters.
DescriptionParameter
Host name, or IP address, for the computer where CICS is running.Host
Network qualifier for VTAM.VTAMNetworkQualifier
iWay Transaction Adapter for CICS User's Guide 2
Configuring the Adapter
-
7/28/2019 iWay Transaction Adapter for CICS User's Guide
26/192
DescriptionParameter
The AnyNet option always communicates back to the callingenvironment on a specific AnyNet port (usually, 397). Therefore, the
server platform must not use other products that also require theservices of the AnyNet port.
On certain platforms such as UNIX, port numbers between 0 and 1023are privileged, meaning that these ports are used to connect toservices that require system-level privileges, such as Telnet, FTP, andSMTP daemons. Port numbers above 1023 are generally associatedwith processes that do not require special privileges. In these cases,assign an AnyNet port of 1024.
AnyNet Port
For information on the relationship of these parameters to the CICS VTAM definitions
using AnyNet, see Configuring VTAM for AnyNet on page 97.
2. Click the Region tab.
The following image shows the Set connection info pane open to the Region tab. Thistab contains seven fields for entry and three active buttons (Back, Finish, and Cancel)
26 iWay Softwar
Configuring a Connection to CICS
-
7/28/2019 iWay Transaction Adapter for CICS User's Guide
27/192
3. Type values for the region parameters.
The following table lists and describes the region parameters.
DescriptionParameter
Valid user ID for CICS.
If you specify the user ID and password, then the CICS connectiondefinition for this LU must be specified with ATTACHSEC(VERIFY).
If you specify the user ID only (with no password), then the CICSconnection definition for this LU must be specified withATTACHSEC(IDENTIFY).
If you specify neither the user ID nor the password, then the CICSconnection definition for this LU must be specified with
ATTACHSEC(LOCAL).
User ID
Valid password associated with the CICS user ID. For more information,see the User ID parameter.
Password
VTAM applid to connect to the CICS system.CICS LU
LU of the SNA access point to which you have access (for example,SNA server).
Local LU
Log mode for the connection to CICS, for example, PARALLEL.LogMode
Select the codepage from the drop-down menu. Cp500 is the defaultvalue.Codepage
Number of sessions for the AnyNet connection. 2 is the default value.Number ofSessions
4. For advanced parameters, including parameters for executing Adabas/Natural programssee How to Set Advanced Parameters on page 31. Otherwise, click Finish.
The newly created connection, CICS_Connection, appears as a node under the CICSservice adapter. The configuration information is stored in the repository for the
configuration you defined during installation.
iWay Transaction Adapter for CICS User's Guide 2
Configuring the Adapter
-
7/28/2019 iWay Transaction Adapter for CICS User's Guide
28/192
How to Set Connection Parameters for SNAProcedure:
If you selected CICS via SNA, the Set connection info pane opens with the Connection tabactive, as shown in the following image. The Connection tab contains six fields for entry anthree active buttons (Back, Finish, and Cancel).
For more information, see Running the Adapter Using LU6.2 Communication on page 109.
1. Type values for the connection parameters.
The following table lists and describes the SNA parameters.
DescriptionParameter
VTAM applid to connect to the CICS system.CICS LU
LU of the SNA access point to which you have access, for example,SNA server.
Local LU
Log mode for the connection to CICS, for example, PARALLEL.LogMode
28 iWay Softwar
Configuring a Connection to CICS
-
7/28/2019 iWay Transaction Adapter for CICS User's Guide
29/192
DescriptionParameter
Valid user ID for CICS.
If you specify the user ID and password, then the CICS connectiondefinition for this LU must be specified with ATTACHSEC(VERIFY).
If you specify the user ID only (with no password), then the CICSconnection definition for this LU must be specified withATTACHSEC(IDENTIFY).
If you specify neither the user ID nor the password, then the CICSconnection definition for this LU must be specified withATTACHSEC(LOCAL).
User ID
Valid password associated with the CICS user ID. For more information,see the User ID parameter.
Password
Select the codepage from the drop-down menu. Cp500 is the defaultvalue.
Codepage
2. For advanced parameters, including parameters for executing Adabas/Natural Programssee How to Set Advanced Parameters on page 31. Otherwise, click Finish.
The newly created connection, CICS_Connection, appears as a node under the CICSservice adapter. The configuration information is stored in the repository for theconfiguration you defined during installation.
iWay Transaction Adapter for CICS User's Guide 2
Configuring the Adapter
-
7/28/2019 iWay Transaction Adapter for CICS User's Guide
30/192
How to Set Connection Parameters for TCP/IPProcedure:
If you selected CICS via TCP/IP, the Set connection info pane opens, with the Connectiontab active, as shown in the following image. The Connection tab contains five fields for entrand three active buttons (Back, Finish, and Cancel).
For more information, see Running the Adapter Using TCP/IP Communication on page 117
1. Type values for the connection parameters.
The following table lists and describes the TCP/IP parameters.
DescriptionParameter
Host name, or IP address, for the computer where CICS is running.Host
TCP port that CICS is listening on for ECI or DPL connections.Port
30 iWay Softwar
Configuring a Connection to CICS
-
7/28/2019 iWay Transaction Adapter for CICS User's Guide
31/192
DescriptionParameter
Valid user ID for CICS.
The user ID and password fields correspond to the values provided onthe CICS TCP/IP service resource definition, using the ECI option, asone of the following:
If you specify both the user ID and the password, then the CICS TCP/IPservice resource definition must be set to ATTACHSEC(VERIFY).
If you specify neither the user ID nor the password, then the CICSTCP/IP resource service definition must be set to ATTACHSEC(LOCAL).
User ID
Valid password associated with the CICS user ID. For additionalinformation, see the User ID parameter.
Password
Select the codepage from the drop-down menu. Cp500 is the defaultvalue.
Codepage
2. For advanced parameters, including parameters for executing Adabas/Natural Programssee How to Set Advanced Parameters on page 31. Otherwise, click Finish.
The newly created connection, CICS_Connection, appears as a node under the CICSservice adapter. The configuration information is stored in the repository for theconfiguration you defined during installation.
How to Set Advanced ParametersProcedure:
1. Click theAdvanced tab.
iWay Transaction Adapter for CICS User's Guide 3
Configuring the Adapter
-
7/28/2019 iWay Transaction Adapter for CICS User's Guide
32/192
The following image shows the Set connection information on the Advanced tab. TheAdvanced tab contains five text fields for entry and three active buttons (Back, Finish,and Cancel).
2. Enter values for the Advanced parameters.
The following table lists and defines the Advanced parameters.
DescriptionParameter
Amount of time in milliseconds that the adapter waits for a completedresponse from CICS. 10,000 milliseconds is the default value.
ConnectionTime Limit(ms)
Name of the Natural subsystem on which the Natural program you wishto invoke resides. For example, for Natural Version 3.14, the nucleusis N314re.
NaturalNucleus
CICS program that calls the Natural CICS Interface. The name of the
proxy provided by iWay Software is AASNATC.
Proxy
Program
32 iWay Softwar
Configuring a Connection to CICS
-
7/28/2019 iWay Transaction Adapter for CICS User's Guide
33/192
DescriptionParameter
String that represents the default logon parameters. It can be modifieddepending on installation requirements.
The CICS/Natural Bridge enables Natural programs to be invoked bythe adapter through CICS using the Software AG Natural CICS Interface.
Note: The Software AG Natural CICS Interface requires a programmatic"logon" to the Natural System.
NaturalLogon
Parameters
An alternative transaction ID to the CPMI (ECI) mirror Transaction ID.This ID must be defined to CICS and point to the CICS mirror programDFHMIRS.
CICS Mirror
For additional information on executing Adabas/Natural programs, see Using
Adabas/Natural Programs on page 119
3. Click Finish.
The newly created connection, CICS_Connection, appears as a node under the CICSservice adapter. The configuration information is stored in the repository for theconfiguration you defined during installation.
How to Connect to a Defined CICS TargetProcedure:
To connect to a defined CICS target:
1. In the left pane, expand the iWay Adapters node.
2. Expand the CICS node.
3. Click the target name under the CICS node, for example, CICS_Connection.
4. Move your pointer over Operations and select Connect.
The Connect to CICS_Connection pane opens, populated with values you entered forthe connection parameters.
5. Verify your connection parameters. If required, provide the password.
6. Click OK.
iWay Transaction Adapter for CICS User's Guide 3
Configuring the Adapter
-
7/28/2019 iWay Transaction Adapter for CICS User's Guide
34/192
The x icon disappears, indicating that the node is connected, as shown in the followinimage.
Managing a Connection to CICS
How to:
Disconnect From a Connection to CICS
Edit a Connection to CICS
Delete a Connection to CICS
To manage CICS connections, you can:
Disconnect from a connection that is not currently in use.
Although you can maintain multiple open connections to different transaction processinsystems, it is recommended to disconnect from connections not in use.
Edit a connection to change its properties.
Delete a connection that is no longer required.
How to Disconnect From a Connection to CICSProcedure:
To disconnect from a connection to CICS:
1. In the left pane, expand the iWay Adapters node.
2. Expand the CICS node.
3. Click the connection, for example, CICS_Connection, move your pointer over Operationsand select Disconnect.
Disconnecting from CICS drops the connection with CICS, but the node remains.
34 iWay Softwar
Managing a Connection to CICS
-
7/28/2019 iWay Transaction Adapter for CICS User's Guide
35/192
The x icon appears, indicating that the node is disconnected, as shown in the followinimage.
How to Edit a Connection to CICSProcedure:
To edit a connection to CICS:
1. In the left pane of iWay Explorer, expand the iWay Adapters node.
2. Expand the CICS node and select the defined target you want to edit, for example,CICS_Connection.
3. In the right pane, move the pointer over Operations and select Edit.
The following image shows the Edit pane that opens on the right containing three field(Target Name, Description, and Target Type) and two active buttons (Next and Cancel)
4. Modify the target information as required and then click Next.
The Set connection info pane opens in the right pane containing the Connection, Regionand Advanced tabs.
5. Modify the information as required and then, click Finish.
iWay Transaction Adapter for CICS User's Guide 3
Configuring the Adapter
-
7/28/2019 iWay Transaction Adapter for CICS User's Guide
36/192
How to Delete a Connection to CICSProcedure:
To delete a connection to CICS:
1. In the left pane, expand the iWay Adapters node.
2. Expand the CICS node.
3. Click the connection, for example, CICS_Connection, move your pointer over Operationsand select Delete.
A message appears, prompting you to confirm the deletion of the node.
4. Click OK.
The node disappears from the list of available connections.
36 iWay Softwar
Managing a Connection to CICS
-
7/28/2019 iWay Transaction Adapter for CICS User's Guide
37/192
iWay
Creating XML Schemas and iWay Business
Services
3
Topics:The following topics describe how to useiWay Explorer (Java Servlet) to createCICS transactions and generate requestand response XML schemas for new orexisting transactions. These schemasare used to represent a transaction for
integration with external systems.
Creating an Adapter Transaction
Creating Schemas for an AdapterTransaction
Understanding iWay Business ServicesIn addition, this section explains how touse the generated schemas to listen forevents in CICS and create iWay BusinessServices, which expose functionality asWeb services.
Creating an Event Port
Managing an Event Port
Creating a Channel
Managing a Channel
iWay Transaction Adapter for CICS User's Guide 3
-
7/28/2019 iWay Transaction Adapter for CICS User's Guide
38/192
Creating an Adapter Transaction
In this section:
Sample Program IWAYSRV0
Cobol Descriptions for Input and Output Communications
Modifying COBOL DD Field Definitions
How to:
Create an Adapter Transaction
After you create a connection to CICS, you can add adapter transactions using iWay Explore(Java Servlet). A single CICS connection may be associated with multiple transactions. Eactransaction represents one service offered by CICS and consists of a program and its
metadata.A generic transaction is automatically added and represents CICS services whose data winot be mapped to XML. You can use a generic transaction for programs that accept no inpuand for programs that return no output or when it is acceptable to return a non-formattedanswer set.
For example, the supplied program IWAYIVP connects to CICS and returns "Congratulationson successful adapter installation and configuration. Because IWAYIVP requires no input ooutput, you do not require Cobol descriptions for the input or output. One request andresponse schema is applicable for this program. The request schema for the generictransaction is in Sample Requests, Schemas, and Cobol File Descriptions on page 137.
Using the generic transaction, the XML request document that is received must include thname of the program to be called in the element. The payload to be sent athe COMMAREA must be in the tag, which can be a maximum of 32,500 bytes
The generic response schema is constructed from the data received from CICS. If the element has more than 80 bytes, the received COMMAREA is split into 80-byte messages. Illegal XML characters ('
-
7/28/2019 iWay Transaction Adapter for CICS User's Guide
39/192
Sample Program IWAYSRV0
iWay Software supplies the IWAYSRV0 and IWAYIVP programs with the adapter. This documenuses the IWAYSRV0 program for illustration purposes and as a reference for the adapter.IWAYSRV0 is an example of a program that returns one of two possible record layouts
depending on what is passed in the request.
If the value for the field COMMAND is 'SHORT', the program returns 40 bytes of data.
If the value for the field COMMAND is 'LONG', the program returns 60 bytes of data.
Sample request documents are in Sample Requests, Schemas, and Cobol File Descriptionson page 137, with a sample response schema for the IWAYSRV0 program. You specify thoutput as explained in Creating an Adapter Transaction on page 38. You must know the fielin the Cobol description that can be used as a record type and the value of that field. Youspecify the value of the field to create the appropriate response schema. This is also truefor events to determine what layout is returned from CICS when you configure a CICS event
How to Create an Adapter TransactionProcedure:
To create an adapter transaction:
1. Click the iWay Adapters tab.
a. Expand the CICS node and connect to a CICS target, for example, CICS_Connection
b. Expand the node to which you connected.
The Transaction node appears under the connected node.
2. Click Transactions, move your pointer over Operations, and selectAdd Service.
iWay Transaction Adapter for CICS User's Guide 3
Creating XML Schemas and iWay Business Services
-
7/28/2019 iWay Transaction Adapter for CICS User's Guide
40/192
The Add Service pane opens on the right, as shown in the following image. It containsthe parameters that enable you to map the Cobol descriptions for the CICS transaction
3. To map the Cobol descriptions for the CICS transaction, type values for the parameters
The following table lists and describes the fields on the Add Service pane.
DescriptionField
Name of the adapter transaction you are creating, for example,IWAYSRV0. Use this name in the attribute.
NodeName
40 iWay Softwar
Creating an Adapter Transaction
-
7/28/2019 iWay Transaction Adapter for CICS User's Guide
41/192
DescriptionField
Name of the program to be called in CICS, for example, IWAYSRV0. TheIWAYSRV0 program appears in Sample Programs on page 149.
ProgramName
Location of the Cobol description that describes the COMMAREA of theCICS program to execute.
It is converted by the adapter to an XML schema that the adapter usesto map from XML to the format required by CICS at run time.
InputCOBOLDataDescription
Size of the COMMAREA (in bytes) for programs that expect a specificsize. By default, the adapter passes 32,500 to the program. For bestperformance, specify a number that can accommodate the larger of theinput COMMAREA or output COMMAREA. For example, to run IWAYSRV0,specify 60.
Size ofCOMMAREA
Run-time location of the Natural program to execute.
Specify a value for this field only if the adapter is expected to executeAdabas/Natural programs.
NaturalLibrary
When this parameter is selected, the adapter creates request andresponse schemas that reflect Cobol group levels (for example, 05, 10,20, and so on). The Cobol grouping is reflected in the XML request andresponse schemas.
You must select this parameter when Cobol input or output descriptionscontain the Cobol OCCURS or REDEFINES statement.
Note: When this parameter is selected and there is an OCCURS Cobolstatement, you cannot test run an adapter transaction. iWay Explorerreturns an "OCCURS in COBOL Data Description" error message.
Use datastructureinformationfrom Cobol
iWay Transaction Adapter for CICS User's Guide 4
Creating XML Schemas and iWay Business Services
-
7/28/2019 iWay Transaction Adapter for CICS User's Guide
42/192
DescriptionField
Path that corresponds to the message you want returned from the CICSprogram.
If the program can return multiple types of messages, for each outputCobol description, enter the Cobol description field and value todetermine the schema to use for a particular message.
iWay Explorer creates the schema to use for a particular message basedon the contents of a field that is returned. For example, a program calledIWAYSRV0_IN.CBL populates the COMMAREA field called COMMAND.Depending on program logic, iWay Explorer creates the correct responseschema.
Inbound COBOL - IWAYSRV0_IN.CBL
Outbound COBOL (1) - IWAYSRV0_OUT_L.CBL
Field: RECORDTYPE
Value: L
Outbound COBOL (2) - IWAYSRV0_OUT_S.CBL
Field: RECORDTYPE
Value: S
The IWAYSRV0_OUT_L and IWAYSRV0_OUT_S Cobol descriptions appearin Sample Requests, Schemas, and Cobol File Descriptions on page 137.
OutputCOBOL
DataDescriptioncontainsthefollowingcolumns:
COBOLDataDescription
Field
Value
Important: When connecting to a remote server, the location path of the Coboldescription must match the operating system path of the machine on which the CICSadapter has been installed. For example, d:\iWay55\Cobol\ is a Windows path, wherea
/iWay55/Cobol/ is a UNIX path.
4. Click Update.
The new CICS transaction, for example, IWAYSRV0, is added under the Transactions node
for the current connection.
42 iWay Softwar
Creating an Adapter Transaction
-
7/28/2019 iWay Transaction Adapter for CICS User's Guide
43/192
Cobol Descriptions for Input and Output Communications
The following are considerationiBSPs for Cobol descriptions for input and outputcommunications. You must use the following syntax for binary, packed, and float fields fothe Cobol descriptions for the adapter transaction input and output formats.
For a binary field:
05 BINARY-FIELD PIC S9(n) COMP.
For a packed-decimal field:
05 PACKED-FIELD PIC S9(n) COMP-3.
Note: Underscores are not supported in Cobol descriptions.
Modifying COBOL DD Field Definitions
How to:Modify COBOL DD Field Definitions
Using iWay Explorer, you can indicate that alpha type fields derived from COBOL DD inputwill be represented in XML by hex character strings. Specifically, this feature allows you tochange the mapping for PIC X fields from XML type string to type hexBinary. As a resultarbitrary binary data can be transmitted in an XML supported format to CICS applications.This feature is useful when sending flag bits.
The following is an input example:
FLAG1 PIC X
02 to transmit byte X02
The following is an output example:
CHARS PIC X 4
AAAA is returned as C1C1C1C1
How to Modify COBOL DD Field DefinitionsProcedure:
To modify COBOL DD field definitions:
1. Open iWay Explorer and connect to your CICS target.
iWay Transaction Adapter for CICS User's Guide 4
Creating XML Schemas and iWay Business Services
-
7/28/2019 iWay Transaction Adapter for CICS User's Guide
44/192
2. Expand the Transactions node and select a defined transaction.
3. Right-click the transaction and select Modify DD from the menu.
A sequence of Modify DD dialog boxes open representing the input and output recordlayouts for the transaction. Each layout includes the Use as Binary column, which allowyou to modify an Alpha field.
4. Select the Alpha field in the table that you want to use as Binary.
5. Click the Use as Binarycolumn and selectyes or no from the drop-down list.
6. Click Next to browse through the remaining input and output record layouts for thetransaction.
7. Click Done when you are finished to save the Alpha field modifications you made.
44 iWay Softwar
Creating an Adapter Transaction
-
7/28/2019 iWay Transaction Adapter for CICS User's Guide
45/192
HexBinary support is available for input and output transaction records. In particular,input RecType fields can also be defined with binaryValue arguments. In this case,the 'Value' data must be specified as the hexadecimal representation of the expectedfield.
8. Right-click the transaction in the left pane and select Edit from the menu.
The Edit dialog box opens.
Note: Hexadecimal values must be specified before any modifications to Alpha fieldsare performed. This is required because the Edit dialog box only saves dialog input wheyou click Update. As a result, the internal COBOL DD representation to be recreated anany prior Alpha field modifications would be lost.
iWay Transaction Adapter for CICS User's Guide 4
Creating XML Schemas and iWay Business Services
-
7/28/2019 iWay Transaction Adapter for CICS User's Guide
46/192
Creating Schemas for an Adapter Transaction
How to:
Create Schemas for an Adapter Transaction
iWay Explorer stores the schemas it creates in subdirectories under the iWay home directorof the machine where it is installed. The exact location of the schemas differs dependingon whether you deploy iWay Explorer with an iBSP or a JCA configuration.
When the adapter is used with an iBSP configuration, iWay Explorer stores the schemaunder a \schemas subdirectory of the iWay home directory, for example,
C:\Program
Files\iway55sm\config\base\wsdl\schemas\service\CICS\CICS_Connection
where:
CICS_Connection
Is the name of the connection to the CICS system as defined in iWay Explorer. Underthis directory, iWay Explorer creates subdirectories containing schemas.
When the adapter is used with a JCA configuration, iWay Explorer stores the schemaunder a \schemas subdirectory of the iWay home directory, for example,
C:\Program Files\iWay55sm\config\base\schemas\CICS\CICS_Connection
where:
CICS_Connection
Is the name of the connection to the CICS system as defined in iWay Explorer. iWayExplorer stores the schemas in this directory.
How to Create Schemas for an Adapter TransactionProcedure:
To create schemas for an adapter transaction:
1. In the left pane, select the transaction for which you want to generate schemas.
2. In the right pane, move the pointer over Operations and select Generate Schema.
The adapter generates the schemas for the selected Cobol descriptions and associate
them with the transaction. The schemas generated for the sample Cobol descriptionsappear in Sample Requests, Schemas, and Cobol File Descriptions on page 137.
46 iWay Softwar
Creating Schemas for an Adapter Transaction
-
7/28/2019 iWay Transaction Adapter for CICS User's Guide
47/192
The Schemas table appears in the right pane. The following image shows the Schemapane, which consists of four rows (Request, Response, Event, EventReply) and threecolumns (Part, Root Tag and Schema). Only the Request and Response rows areapplicable.
a. To view the request schema, click the ellipsis symbol that is located in the Schemcolumn of the Request row.
b. To view the response schema, click the ellipsis symbol that is located in the Schemcolumn of the Response row.
3. To exit the Schemas pane, click OK.
iWay Transaction Adapter for CICS User's Guide 4
Creating XML Schemas and iWay Business Services
-
7/28/2019 iWay Transaction Adapter for CICS User's Guide
48/192
Understanding iWay Business Services
In this section:
Creating a Web Service
Testing the Web Service
Generating WSDL From a Web Service
Identity Propagation
How to:
Create a Web Service
Test the Web Service
Generate WSDL From a Web Service
Example:
Viewing WSDL Generated from a Web Service
iWay Explorer provides developers with a simple, consistent mechanism for extending thecapabilities of the adapter. The iWay Business Services Provider (iBSP) exposes functionalitas Web services. It serves as a gateway to heterogeneous back-end applications anddatabases.
A Web service is a self-contained, modularized function that can be published and accesseacross a network using open standards. It is the implementation of an interface by a
component and is an executable entity. For the caller or sender, a Web service can beconsidered as a "black box" that may require input and delivers a result. A Web serviceintegrates within an enterprise as well as across enterprises on any communication technologstack, whether asynchronous or synchronous, in any format.
Note: In a J2EE Connector Architecture (JCA) implementation of iWay adapters, Web serviceare not available. When the adapters are deployed to use the iWay Connector for JCA, theCommon Client Interface provides integration services using the iWay adapters. For moreinformation, see the iWay 5.5 SM Installation and Configuration documentation and the iWaConnector for J2EE Connector Architecture User's Guide.
Creating a Web Service
After you connect to your application system and create an XML schema for a transactionyou can create a Web service. The following procedure describes how to create a Web servicusing iWay Explorer.
48 iWay Softwar
Understanding iWay Business Services
-
7/28/2019 iWay Transaction Adapter for CICS User's Guide
49/192
How to Create a Web ServiceProcedure:
To create a Web service:
1. Click the Iway Adapters tab.
The iWay Adapters window opens.
a. In the left pane, expand the CICS node.
b. Connect to a CICS target, for example, CICS_Connection.
c. Expand the node to which you connected.
The Transaction node appears under the connected node.
2. Click Transactions and then select the transaction for which you want to create a Webservice.
3. In the right pane, move your cursor over Operations and select Create iWay BusinessServices.
The Create Web Service pane opens on the right, where you enter information that isspecific to the Web service you are defining, as shown in the following image.
a. In the Service Name field, type a descriptive name for the Web service.
b. In the Description field, type a brief description for the Web service (optional).
iWay Transaction Adapter for CICS User's Guide 4
Creating XML Schemas and iWay Business Services
-
7/28/2019 iWay Transaction Adapter for CICS User's Guide
50/192
c. In the License field, select one or more license codes to assign to the Web ServiceTo select more than one, hold down the Ctrl key and click the licenses.
4. Click Next.
Another pane with the Method Name and Description fields opens, where you enterinformation that is specific to the method you are defining, as shown in the followingimage.
a. In the Method Name field, type a descriptive name for the method.
b. In the Description field, type a brief description for the method.
5. Click Finish.
The iWay Business Services Provider tab opens. The Web service is created and publisheto the iWay Business Services Provider. iWay Explorer displays the newly created Web Servicunder the iWay Business Services folder.
Testing the Web Service
After you create a business service, you can test it to ensure that it functions properly. iWaprovides a test tool for testing the business service.
How to Test the Web ServiceProcedure:
To test the Web service:
50 iWay Softwar
Understanding iWay Business Services
-
7/28/2019 iWay Transaction Adapter for CICS User's Guide
51/192
1. If you are not on the iWay Business Services tab of iWay Explorer, click the tab to accesbusiness services.
a. If it is not expanded, expand the list of business services under iWay BusinessServices.
b. Expand the Services node.
2. Select the name of the business service you want to test.
The business service name appears as a link in the right pane.
3. In the right pane, click the named business services link.
The test option appears in the right pane.
4. In the input xml field, either type a sample XML document that queries the service, orbrowse to the location of an XML instance and click Upload.
The following is an example of an XML document that queries the service.
SHORT
LONG
5. Click Invoke.
The result appears in the right pane.
Generating WSDL From a Web Service
The Web Service Description Language (WSDL) file is an XML file that describes the Webservice documents and provides access to the service, such as iWay run-time environment
iWay Transaction Adapter for CICS User's Guide 5
Creating XML Schemas and iWay Business Services
-
7/28/2019 iWay Transaction Adapter for CICS User's Guide
52/192
How to Generate WSDL From a Web ServiceProcedure:
To generate WSDL from a Web service:
1. If you are not already on the iWay Business Services tab, click the tab to access busines
services.
2. In the left pane, expand the list of services to display the iWay Business Services forwhich you want to generate WSDL.
3. Select the business service.
The link for the service appears in the right pane.
a. Right-click the Service Description link and choose Save Target As.
b. Choose a location for the file and specify.wsdl for the extension.
Note: The file extension must be .wsdl.
4. Click Save.
52 iWay Softwar
Understanding iWay Business Services
-
7/28/2019 iWay Transaction Adapter for CICS User's Guide
53/192
Viewing WSDL Generated from a Web ServiceExample:
After generating a WSDL file from the IWAYSRV0.ibs serialized object, the IWAYSRV0. wsdfile looks similar to the following image.
iWay Transaction Adapter for CICS User's Guide 5
Creating XML Schemas and iWay Business Services
-
7/28/2019 iWay Transaction Adapter for CICS User's Guide
54/192
Identity Propagation
If you test or execute a Web service using a third party XML editor, for example XMLSPY,the Username and Password values that you specify in the SOAP header must be valid anare used to connect to CICS. The user name and password values that you provided for
CICS during target creation using iWay Explorer are overwritten for this Web service requestThe following is a sample SOAP header that is included in the WSDL file for a Web service
String
String
String
String
String
String
String
Note: You can remove the following tags from the SOAP header, as they are not required.
String
String
54 iWay Softwar
Understanding iWay Business Services
-
7/28/2019 iWay Transaction Adapter for CICS User's Guide
55/192
Creating an Event Port
In this section:
Creating an Event Port From the iWay Events Tab
How to:
Create an Event Port for File
Create an Event Port for iBSP
Create an Event Port for MSMQ
Create an Event Port for JMSQ
Create a Port for SOAP
Create an Event Port for HTTP
Create an Event Port for MQSeries
Events are generated by the CICS transaction processing system as a result of activity onthat system. You can use events to trigger an action in your application. For example, theCICS application program can generate an event when customer information is updated. Ifyour application performs an action when this occurs, your application is a consumer of thievent.
The adapter can capture events using TCP/IP. For more information about additional protocolscontact iWay Software Customer Support Services.
The following is an overview of creating an event through the adapter:1. Create the CICS application program.
For example, a program can be triggered by certain criteria and publish information tothe specific protocol, such as TCP/IP. The application program that is written for theevent passes data to a TCP/IP port.
2. Configure the connection using iWay Explorer to create the event schema from a CoboFile Description.
The Cobol File Description describes the format and layout of the data that is passed bthe TCP/IP program to the TCP/IP port.
3. Configure an iWay port and channel using iWay Explorer.
After the event schema is created, you can configure an iWay port and channel usingiWay Explorer. The port you specify is the same port to which the CICS application evenprogram is writing the event data.
iWay Transaction Adapter for CICS User's Guide 5
Creating XML Schemas and iWay Business Services
-
7/28/2019 iWay Transaction Adapter for CICS User's Guide
56/192
For details on creating an iWay event port, see Creating an Event Port From the iWay EventTab on page 56. For details on creating a channel, see Creating a Channel on page 72.
iWay Explorer enables you to create event ports from the iWay Adapters tab or from the iWaEvents tab. This topic explains how to create an event port using both methods and how t
modify and delete an existing port.
Creating an Event Port From the iWay Events Tab
The following procedures describe how to create an event port from the iWay Events tab oiWay Explorer for various dispositions.
The following dispositions are available when using iWay Explorer in conjunction with aniBSP deployment.
File
iBSP
MSMQ
JMSQ
SOAP
HTTP
MQ Series
The following dispositions are available when using iWay Explorer in conjunction with a JCAconnector deployment.
File
JMSQ
HTTP
MQ Series
How to Create an Event Port for FileProcedure:
To create an event port for File:
1. In the left pane of iWay Explorer, select the iWay Events tab.
2. Expand the CICS node.
3. Select the ports node.
56 iWay Softwar
Creating an Event Port
-
7/28/2019 iWay Transaction Adapter for CICS User's Guide
57/192
The following image shows the ports node highlighted in the left pane and the Operationmenu options (Add a new port and Refresh) in the right pane.
4. Move the pointer over Operations and selectAdd a new port.
The Create New Port pane opens on the right, as shown in the following image.
a. In the Port Name field, type a name for the event port.
b. In the Description field, type a brief description for the port (optional).
c. From the Disposition Protocol drop-down list, select FILE.
iWay Transaction Adapter for CICS User's Guide 5
Creating XML Schemas and iWay Business Services
-
7/28/2019 iWay Transaction Adapter for CICS User's Guide
58/192
d. In the Disposition field, specify a destination file to which the event data is written
When pointing iWay Explorer to an iBSP deployment, specify the destination fileusing the following format:
ifile://[location];errorTo=[pre-defined port name or another
disposition url]
When pointing iWay Explorer to a JCA deployment, provide the full path to thedirectory.
The following table lists and describes the parameters for the File disposition:
DescriptionParameter
Destination and file name of the document where event data iswritten, for example, D:\in\x.txt
Location
Location to which error logs are sent. Optional.
Predefined port name or another disposition URL. The URL mustbe complete, including the protocol.
ErrorTo
5. Click OK.
The port appears under the ports node in the left pane. In the right pane, a table appearthat summarizes the information associated with the event port you created.
You are ready to associate the event port with a channel. For more information, see Creatina Channel on page 72.
How to Create an Event Port for iBSPProcedure:
To create an event port for iBSP:
1. In the left pane of iWay Explorer, select the iWay Events tab.
2. Expand the CICS node.
3. Select the ports node.
4. Move the pointer over Operations and selectAdd a new port.
58 iWay Softwar
Creating an Event Port
-
7/28/2019 iWay Transaction Adapter for CICS User's Guide
59/192
The Create New Port pane opens on the right, as shown in the following image.
a. In the Port Name field, type a name for the event port.
b. In the Description field, type a brief description for the port (optional).
c. From the Disposition Protocol drop-down list, select iBSE.
d. In the Disposition field, enter an iBSP destination in the following format:
ibse:[svcName].[mthName];responseTo=[pre-defined port name or
another disposition url];errorTo=[pre-defined port name or another
disposition url]
The following table lists and describes the parameters for the iBSP disposition:
DescriptionParameter
Name of the service created with iBSP.svcName
Name of the method created for the Web service.mthName
Location to which responses are posted. Optional.
Predefined port name or another disposition URL. The URL mustbe complete, including the protocol.
responseTo
Location to which error logs are sent. Optional.
Predefined port name or another disposition URL. The URL mustbe complete, including the protocol.
errorTo
iWay Transaction Adapter for CICS User's Guide 5
Creating XML Schemas and iWay Business Services
-
7/28/2019 iWay Transaction Adapter for CICS User's Guide
60/192
5. Click OK.
The port appears under the ports node in the left pane. In the right pane, a table appearthat summarizes the information associated with the event port you created.
You are ready to associate the event port with a channel. For more information, see Creatina Channel on page 72.
How to Create an Event Port for MSMQProcedure:
To create an event port for MSMQ:
1. In the left pane of iWay Explorer, select the iWay Events tab.
2. Expand the CICS node.
3. Select the ports node.
4. Move the pointer over Operations and selectAdd a new port.
The Create New Port pane opens on the right, as shown in the following image.
a. In the Port Name field, type a name for the event port.
b. In the Description field, type a brief description for the port (optional).c. From the Disposition Protocol drop-down list, select MSMQ.
60 iWay Softwar
Creating an Event Port
-
7/28/2019 iWay Transaction Adapter for CICS User's Guide
61/192
d. In the Disposition field, enter an MSMQ destination in the following format:
msmq:/[machineName]/private$/qName;errorTo=[pre-defined port name
or another disposition url]
Note: This syntax is for a private queue. Private queues are queues that are not
published in Active Directory. They appear only on the local computer that containthem. Private queues are accessible only by Message Queuing applications thatrecognize the full path name or format name of the queue.
The following table lists and describes the parameters for the MSMQ disposition.
DescriptionParameter
Machine name where the Microsoft Queuing system is running.machineName
Name of the private queue where messages are placed.qName
Location to which error logs are sent. Optional.
Predefined port name or another disposition URL. The URL mustbe complete, including the protocol.
errorTo
5. Click OK.
The port appears under the ports node in the left pane. In the right pane, a table appearthat summarizes the information associated with the event port you created.
You are now ready to associate the event port with a channel. For more information, seeCreating a Channel on page 72.
How to Create an Event Port for JMSQProcedure:
To create an event port for JMSQ:
1. In the left pane of iWay Explorer, select the iWay Events tab.
2. Expand the CICS node.
3. Select the ports node.
4. Move the pointer over Operations and selectAdd a new port.
iWay Transaction Adapter for CICS User's Guide 6
Creating XML Schemas and iWay Business Services
-
7/28/2019 iWay Transaction Adapter for CICS User's Guide
62/192
The Create New Port pane opens on the right, as shown in the following image.
a. In the Port Name field, type a name for the event port.
b. In the Description field, type a brief description for the port (optional).
c. From the Disposition Protocol drop-down list, selectJMSQ.
62 iWay Softwar
Creating an Event Port
-
7/28/2019 iWay Transaction Adapter for CICS User's Guide
63/192
d. In the Disposition field, enter a JMS destination.
When pointing iWay Explorer to an iBSP deployment, use the following format.
jmsq:[myQueueName]@[myQueueFac];jndiurl=[myurl];
jndifactory=[myfactory];user=[user];password=[xxx];
errorTo=[pre-defined port name or another disposition url]
When pointing iWay Explorer to a JCA deployment, use the following format.
jms:jmsqueue@jmsfactory;jndiurl=;jndifactory=;
The following table lists and describes the parameters for the JMSQ disposition.
DescriptionParameter
JNDI name of a queue to which events are emitted.myQueueName
or
jmsqueue
Resource that contains information about the JMS Server.myQueueFac
or
jmsfactory
URL to use to contact the JNDI provider. The syntax of thisURL depends on the JNDI provider being used. This valuecorresponds to the standard JNDI property,
java.naming.provider.url
jndiurl
Is JNDI context.INITIAL_CONTEXT_FACTORY and is providedby the JNDI service provider.
jndifactory
Valid user name required to access a JMS server.user
Valid password required to access a JMS server.password
Location to which error logs are sent. Optional.
Predefined port name or another disposition URL. The URLmust be complete, including the protocol.
errorTo
5. Click OK.
The port appears under the ports node in the left pane. In the right pane, a table appearthat summarizes the information associated with the event port you created.
iWay Transaction Adapter for CICS User's Guide 6
Creating XML Schemas and iWay Business Services
-
7/28/2019 iWay Transaction Adapter for CICS User's Guide
64/192
You are now ready to associate the event port with a channel. For more information, seeCreating a Channel on page 72.
How to Create a Port for SOAPProcedure:
To create an event port for SOAP:
1. In the left pane of iWay Explorer, select the iWay Events tab.
2. Expand the CICS node.
3. Select the ports node.
4. Move the pointer over Operations and selectAdd a new port.
The Create New Port pane opens on the right, as shown in the following image.
a. In the Port Name field, type a name for the event port.
b. In the Description field, type a brief description for the port (optional).
c. From the Disposition Protocol drop-down list, select SOAP.
64 iWay Softwar
Creating an Event Port
-
7/28/2019 iWay Transaction Adapter for CICS User's Guide
65/192
d. In the Disposition field, enter a SOAP destination in the following format.
soap:[wsdl-url];soapaction=[myaction];
method=[web service method];namespace=[namespace];
responseTo=[pre-defined port name or another disposition URL];
errorTo=[pre-defined port name or another disposition url]
The following table lists and describes the parameters for the SOAP disposition.
DescriptionParameter
URL to the WSDL file that is required to create the SOAP message,for example:
wsdl-url
http://localhost:7001/ibse/IBSEServlet/test/
webservice.ibs?wsdl
where:
webservice
Is the name of the Web service you created using iWay Explorer.
This value can be found by navigating to the iWay Business Servicestab and opening the Service Description link in a new window. TheWSDL URL appears in the Address field.
You can also open the WSDL file in a third party XML editor (forexample, XMLSPY) and view the SOAP request settings to find thisvalue.
iWay Transaction Adapter for CICS User's Guide 6
Creating XML Schemas and iWay Business Services
-
7/28/2019 iWay Transaction Adapter for CICS User's Guide
66/192
DescriptionParameter
Method that is called by the SOAP disposition. For example:
webservice.method@test@@
where:
webservice
Is the name of the Web service you created using iWay Explorer.
method
Is the method being used.
test
Is the license that is being used by the Web service.
This value can be found by navigating to the iWay Business Servicestab, opening the Service Description link in a new window, andperforming a search for soapAction.
You can also open the WSDL file in a third party XML editor (forexample, XMLSPY) and view the SOAP request settings to find thisvalue.
soapaction
Web service method you are using. This value can be found in theWSDL file.
method
XML namespace you are using. This value can be found in the
WSDL file.
namespace
Location to which responses are posted. Optional.
Predefined port name or another disposition URL. The URL mustbe complete, including the protocol.
responseTo
Location to which error logs are sent. Optional.
Predefined port name or another disposition URL. The URL mustbe complete, including the protocol.
errorTo
5. Click OK.
The port appears under the ports node in the left pane. In the right pane, a table appearthat summarizes the information associated with the port you created.
66 iWay Softwar
Creating an Event Port
-
7/28/2019 iWay Transaction Adapter for CICS User's Guide
67/192
You are now ready to associate the event port with a channel. For more information, seeCreating a Channel on page 72.
How to Create an Event Port for HTTPProcedure:
To create an event port for HTTP:
1. In the left pane of iWay Explorer, select the iWay Events tab.
2. Expand the CICS node.
3. Select the ports node.
4. Move the pointer over Operations and selectAdd a new port.
The Create New Port pane opens on the right, as shown in the following image.
a. In the Port Name field, type a name for the event port.
b. In the Description field, type a brief description for the port (optional).
c. From the Disposition Protocol drop-down list, select HTTP.
iWay Transaction Adapter for CICS User's Guide 6
Creating XML Schemas and iWay Business Services
-
7/28/2019 iWay Transaction Adapter for CICS User's Guide
68/192
d. In the Disposition field, enter an HTTP destination.
When pointing iWay Explorer to an iBSP deployment, use the following format.
http://[myurl];responseTo=[pre-defined port name or another
disposition url];
When pointing iWay Explorer to a JCA deployment, use the following format.
http://host:port/uri
The following table lists and describes the parameters for the HTTP disposition wheusing an iBSP deployment.
DescriptionParameter
URL target for the post operation, for example,
http://myhost:1234/docroot
myurl
Location to which responses are posted. Optional.
Predefined port name or another disposition URL. The URL mustbe complete, including the protocol.
responseTo
The following table lists and describes the parameters for the HTTP disposition wheusing a JCA deployment:
DescriptionParameter
Combination of the name of the host on which the Web serverresides and the port on which the server is listening for the postoperation.
host:port
Universal resource identif