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


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.


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


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


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


Contents


6/192

Reader Comments...........................................................................................191

6 iWay Softwar

Contents


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



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


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


Preface
http://www.iwaysoftware.com/http://techsupport.iwaysoftware.com/http://techsupport.iwaysoftware.com/http://www.iwaysoftware.com/


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


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


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/


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



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


15/192


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.


Introducing the iWay Transaction Adapter for CICS


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



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:



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 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.




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.


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


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


Chapters 4 and 5 of this guide

iWay 5.5 SM Installation and Configuration

iWay Explorer


manual


iWay Connector for J2EE Connector

Architecture User's Guide


manual

iWay Enterprise Connector for J2EEConnector Architecture (JCA)




20/192

20 iWay Softwar

Information Roadmap


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



22/192


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



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.


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.


Configuring the Adapter


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



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




26/192


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



27/192

3. Type values for the region parameters.

The following table lists and describes the region parameters.


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.




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.


The following table lists and describes the SNA parameters.


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



29/192



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.




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


The following table lists and describes the TCP/IP parameters.


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



31/192



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.


How to Set Advanced ParametersProcedure:

1. Click theAdvanced tab.




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.


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



33/192


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.


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.




34/192

The x icon disappears, indicating that the node is connected, as shown in the followinimage.


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:



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



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.




36/192

How to Delete a Connection to CICSProcedure:

To delete a connection to CICS:



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



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



38/192


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 ('


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.


Creating XML Schemas and iWay Business Services


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



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




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



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.




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



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.




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


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.




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



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).




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



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




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



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.




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



55/192


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.




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.


3. Select the ports node.

56 iWay Softwar



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.




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:


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:





58 iWay Softwar



59/192




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:


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.


responseTo



errorTo




60/192

5. Click OK.


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:







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



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.


Machine name where the Microsoft Queuing system is running.machineName

Name of the private queue where messages are placed.qName



errorTo

5. Click OK.


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:








62/192




c. From the Disposition Protocol drop-down list, selectJMSQ.

62 iWay Softwar



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.


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


Predefined port name or another disposition URL. The URLmust be complete, including the protocol.

errorTo

5. Click OK.





64/192


How to Create a Port for SOAPProcedure:

To create an event port for SOAP:








c. From the Disposition Protocol drop-down list, select SOAP.

64 iWay Softwar



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.


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.




66/192


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



responseTo



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



67/192


How to Create an Event Port for HTTPProcedure:

To create an event port for HTTP:








c. From the Disposition Protocol drop-down list, select HTTP.




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.


URL target for the post operation, for example,

http://myhost:1234/docroot

myurl



responseTo

The following table lists and describes the parameters for the HTTP disposition wheusing a JCA deployment:


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