web methods mainframe developers guide 65

8/6/2019 Web Methods Mainframe Developers Guide 65

1/178

webMethods Mainfram

Developers Gu

VERSION

webMethods, Inc.

South Tower

3877 Fairfax Ridge Road

Fairfax, VA 22030

USA

703.460.2500

http://www.webmethods.com


2/178

webMethods Administrator, webMethods Broker, webMethods Dashboard, webMethods Developer, webMethods Fabric, webMethods Glue, webMethodsInstaller, webMethods Integration Server, webMethods Mainframe, webMethods Manager, webMethods Mobile, webMethods Modeler, webMethodsMonitor, webMethods Optimize, webMethods Portal, webMethods Trading Networks, and webMethods Workflow are trademarks of webMethods, Inc.webMethods and the webMethods logo are registered trademarks of webMethods, Inc.

Acrobat, Adobe, and Reader are registered trademarks of Adobe Systems Incorporated. Amdocs is a registered trademark, and ClarifyCRM is a trademark ofAmdocs Inc. Ariba is a registered trademark of Ariba, Inc. BEA and BEA WebLogic Server are registered trademarks, and BEA WebLogic Platform is a

trademark of BEA Systems, Inc. BMC Software and PATROL are registered trademarks of BMC Software, Inc. BroadVision is a registered trademark ofBroadVision, Inc. ChemeStandards and CIDX are registered trademarks of Chemical Industry Data Exchange. Unicenter is a trademark of ComputerAssociates International, Inc. PopChart is a registered trademark of CORDA Technologies, Inc. Kenan and Arbor are registered trademarks of CSG Software,Incorporated. SNAP-IX and Data Connection are registered trademarks of Data Connection Corporation. DataDirect, DataDirect Connect, and SequeLink areregistered trademarks of DataDirect Technologies Corp. D & B and D-U-N-S are registered trademarks of Dun & Broadstreet, Inc. Entrust is a registeredtrademark of Entrust, Inc. Hewlett-Packard, HP, HP-UX, and OpenView are trademarks of Hewlett-Packard Company. i2 is a registered trademark of i2Technologies, Inc. AIX, AS/400, CICS, DB2, Domino, IBM, Infoprint, Lotus, Lotus Notes, MQSeries, OS/390, OS/400, RACF, RS/6000, S/390, System/390, VTAM,z/OS, and WebSphere are registered trademarks; and Informix, SQL/400, Communications System for Windows NT, IMS, MVS, SQL/DS, and UniversalDatabase are trademarks of IBM Corporation. InnoDB is a trademark of Innobase Oy. JBoss is a registered trademark, and JBoss Group is a trademark of JBossInc. JD Edwards is a registered trademark of J.D. Edwards & Company and OneWorld is a registered trademark of J.D. Edwards World Source Company.Linux is a registered trademark of Linus Torvalds. X Window System is a trademark of the X.org Foundation. MetaSolv is a registered trademark of MetasolvSoftware, Inc. ActiveX, Microsoft, Outlook, Visual Basic, Windows, and Windows NT are registered trademarks; and SQL Server is a trademark of MicrosoftCorporation. MySQL is a registered trademark of MySQL AB, Ltd. Teradata is a registered trademark of NCR International, Inc. Netscape is a registeredtrademark of Netscape Communications Corporation. ServletExec is a registered trademark, and New Atlanta is a trademark of New AtlantaCommunications, LLC. CORBA is a registered trademark of Object Management Group, Inc. UNIX is a registered trademark of X/Open Company Ltd. Oracleis a registered trademark of Oracle International Corporation. PeopleSoft and Vantive are registered trademarks, and PeopleSoft Pure Internet Architectureand WorldSoftware are trademarks of PeopleSoft, Inc. Infranet and Portal are trademarks of Portal Software, Inc. RosettaNet is a trademark of RosettaNet, anon-profit organization. SAP and R/3 are registered trademarks of SAP AG. Siebel is a registered trademark of Siebel Systems, Inc. SPARC is a registered

trademark, and SPARCStation is a trademark of SPARC International, Inc. SSA Global and SSA Baan are trademarks of SSA Global Technologies, Inc. EJB,Enterprise JavaBeans, Java, JavaServer, JDBC, JSP, J2EE, Solaris, and Sun Microsystems are registered trademarks; and Java Naming and Directory Interface,SOAP with Attachments API for Java, JavaServer Pages and SunSoft are trademarks of Sun Microsystems, Inc. SWIFT and SWIFTNet are registeredtrademarks of Society for Worldwide Interbank Financial Telecommunication SCRL. Sybase is a registered trademark of Sybase, Inc. UCCnet andeBusinessReady are registered trademarks of Uniform Code Council, Inc. Verisign is a registered trademark of Verisign, Inc. VERITAS is a registeredtrademark of VERITAS Operating Corporation, and VERITAS Software and VERITAS Cluster Server are trademarks of VERITAS Software Corporation. W3Cis a registered trademark of Massachusetts Institute of Technology.

All other marks are the property of their respective owners.

Copyright 20022004 by webMethods, Inc. All rights reserved, including the right of reproduction in whole or in part in any form.

Document ID: MF-DG-650-20050415

ICU License - ICU 1.8.1 and later

COPYRIGHT AND PERMISSION NOTICE

Copyright (c) 1995-2002 International Business Machines Corporation and others

All rights reserved.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to dealSoftware without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, and/or sell copies of the Software, permit persons to whom the Software is furnished to do so, provided that the above copyright notice(s) and this permission notice appear in all copies Software and that both the above copyright notice(s) and this permission notice appear in supporting documentation.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THEWARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF THIRD PARTY RIGHTS. IN NOEVENT SHALL THE COPYRIGHT HOLDER OR HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL INDIREOR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN ANACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE ORPERFORMANCE OF THIS SOFTWARE.

Except as contained in this notice, the name of a copyright holder shall not be used in advertising or otherwise to promote the sale, use or other dealings Software without prior written authorization of the copyright holder.


3/178

Con

webMethods Mainframe Developers Guide Version 6.5

Contents

About This Guide. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Document Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Additional Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Chapter 1. Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Basic Steps for Using Developer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Before You Use Developer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Starting Developer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Defining a Host Connection Pool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Creating a Host Connection Pool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Assigning the Properties of a Host Connection Pool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Defining Sessions in the Host Connection Pool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Defining a Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Creating a Transaction Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Defining Input and Output Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Assigning Transaction Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Associating a Transaction with a Host Connection Pool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Chapter 2. Working with Host Connection Pools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

What is a Host Connection Pool? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Creating a Host Connection Pool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Creating Host Connection Pools Manually . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Generating Host Connection Pools from XML Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Assigning Host Connection Pool Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Summary of Host Connection Pool Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Code Pages in Host Connection Pools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Custom End Bracket Count . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Restart Session on Transaction Error . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Creating and Modifying Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Defining General Information about a Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Summary of Session Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Hiding Columns in a Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Defining Session Information Specific to a Host Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Summary of Session Information Specific to a Host Type . . . . . . . . . . . . . . . . . . . . . . . .

Start Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Model Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Common TN3270E Gateway Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .


4/178

C o n t e n t s

4 webMethods Mainframe Developers Guide Version 6.5

Host Connection Pool Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Enabling or Disabling Host Connection Pools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

Uploading Host Connection Pools without Saving . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

Viewing Validation Errors for Host Connection Pools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Host Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43Exporting Host Connection Pools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Chapter 3. Working with Transaction Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

What are Transaction Services? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

Creating a Transaction Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

Creating Transaction Services Manually . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

Generating Transaction Services from XML Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

Creating and Modifying Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

Adding and Deleting Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

Shifting Fields Up and Down . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

Configuring Input and Output Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

Populating or Modifying the Columns of a Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

Modifying Field Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

Modifying the Properties of Multiple Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

Configuring Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

Summary of the Columns in a Record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

Summary of Properties for Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

Using a COBOL OCCURS Clause . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

Record Counter Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

Calculating Offsets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

Creating Transactions for APPC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65Send-Receive Model for APPC and DPL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

Assigning Transaction Service Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

Summary of Transaction Service Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

Code Pages in Transaction Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

Using the Auto Calculate Option for Message-Based Transactions . . . . . . . . . . . . . . . . . . 71

Startup Sequence for LU 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

Synchronization Level for APPC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

Transaction Name for IMS Connect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

Associating a Transaction with a Host Connection Pool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

Transaction Service Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75Enabling or Disabling Transaction Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

Uploading Transaction Services without Saving . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

Viewing Validation Errors for Transaction Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

Exporting Transaction Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78


5/178

Con


Chapter 4. Converting Source Code into Transaction Services . . . . . . . . . . . . . . . . . . . .

What are Transaction Source Files? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Auto-Conversion of Source Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Manual Conversion of Source Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Adding and Deleting Transaction Source Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Adding Transaction Source Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Deleting Transaction Source Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Converting from Source Files to Transaction Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Dragging to the Tree Target . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Dragging to the LU2 Screen Target . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Using the Tree Target Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Using the LU2 Screen Target Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

The LU2 Screen Target Toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Performing Actions in the LU2 Screen Target Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Kinds of Source Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

The Structure of BMS Maps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

The Structure of MFS Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

The Structure of COBOL Copybooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Source-Target Pairs for Conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Dragging BMS Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Dragging MFS FMT Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Dragging MFS MSG Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Dragging COBOL Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Chapter 5. Capturing a Live 3270 Terminal Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

What is the Live 3270 Feature? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A 3270 Screen Versus a 3270 Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Preparations for Live 3270 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Procedure for Capturing a Live 3270 Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

How Data is Formatted . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Field Fill Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Code Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Creating a Live 3270 Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Using Automatic Capture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Using Manual Capture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

The Live 3270 Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Live 3270 Toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Changing Host Connection Pools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Status Bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3270 AID Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Capture Toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .


6/178

C o n t e n t s


Moving the Cursor in the 3270 Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118

Host Connection Pool Administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118

Modifying Transactions During Capture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119

Naming Transaction Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120

Selecting and Clearing Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120Selecting Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120

Clearing Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

Setting Static Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

Viewing Field Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

Logical Units of Work and Screen Settling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

The Rules Used for Field Naming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124

Chapter 6. Using Transaction Groups for Parallel Transactions . . . . . . . . . . . . . . . . . . . . 127

What are Parallel Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

Creating Transaction Groups Manually . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

Generating Transaction Groups from XML Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

Managing Transactions in a Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

Transaction Group Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

Error Handling for Parallel Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

Exporting Transaction Group Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133

Chapter 7. Working with Subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

Managing Subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136

Developing a Publishable Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136

Creating a Flow Service for Subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137

Subscribing a Flow Service to a Transaction Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138

Chapter 8. Setting Options for webMethods Mainframe . . . . . . . . . . . . . . . . . . . . . . . . . . . 139

Setting Options for Source File Conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140

Excluding COBOL REDEFINES Clauses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140

Making Imported Fields Optional . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141

Naming Conventions for Input and Output Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142

Selecting Default Host Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143

Source File Logging Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144

Setting Options for the LU2 Screen Target Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145

Color Information for the LU2 Screen Target Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145

Hiding Static Field Borders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146

Changing Font Information for the LU2 Screen Target Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147

Setting Options for String Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147

Field Justification Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148

Field Fill Value Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148


7/178

Con


Code Page Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Managing Custom Code Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Adding Custom Code Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Deleting Custom Code Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Setting Screen Options for a Live 3270 Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Color Information for the Live 3270 Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Changing Font Information for the Live 3270 Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Setting Additional 3270 Screen Delay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Setting Capture Options for a Live 3270 Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Capturing all Protected and Unprotected Fields as Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Capture the Entire Output Screen in One Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Changing Capture Mode for the Live 3270 Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Changing Field Fill Values Sent to the Mainframe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Prefix for Transaction Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Setting Input and Output Field Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Appendix A. LU 2 Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Keywords for LU 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Aid Identification Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .


8/178

C o n t e n t s



9/178

About This G


About This Guide

The webMethods Mainframe Developers Guide is intended for anyone who needs to use

webMethods Developer to create and modify host transactions for webMethodsMainframe.

This guide assumes you are familiar with the following:

The features of Developer,

The operating system of the computer on which you have installed Developer.

The mainframe computer with which webMethods Mainframe is to communicate

Document Conventions

Addit ional Information

The webMethods Advantage Web site at http://advantage.webmethods.com provides with important sources of information about the webMethods Integration Platform:

Troubleshooting Information. webMethods provides troubleshooting information formany webMethods components in the webMethods Knowledge Base.

Convention Description

Bold Identifies elements on a screen.

Italic Identifies variable information that you must supply orchange based on your specific situation or environment.Identifies terms the first time they are defined in text. Alsoidentifies service input and output variables.

Narrow font Identifies storage locations for services on the webMethodsIntegration Server using the convention folder.subfolder:service.

Typewriter

font

Identifies characters and values that you must type exactly or

messages that the system displays on the console.

UPPERCASE Identifies keyboard keys. Keys that you must presssimultaneously are joined with the + symbol.

\ Directory paths use the \ directory delimiter unless thesubject is UNIX-specific.

[ ] Optional keywords or values are enclosed in [ ]. Do not typethe [ ] symbols in your own code.
http://advantage.webmethods.com/http://advantage.webmethods.com/cgi-bin/advantage/main.jsp?w=0&s=3232716887&targChanId=-536883032&all=1http://advantage.webmethods.com/cgi-bin/advantage/main.jsp?w=0&s=3232716887&targChanId=-536883032&all=1http://advantage.webmethods.com/


10/178

A b o u t T h i s G u i d e


Documentation Feedback. To provide documentation feedback to webMethods, go to theDocumentation Feedback Form on the webMethods Bookshelf.

Additional Documentation. All webMethods documentation is available on thewebMethods Bookshelf.
http://advantage.webmethods.com/cgi-bin/advantage/main.jsp?w=0&s=3232716999&targChanId=-536883238http://advantage.webmethods.com/cgi-bin/advantage/main.jsp?w=0&s=3232716887&targChanId=-536879873http://advantage.webmethods.com/cgi-bin/advantage/main.jsp?w=0&s=3232716887&targChanId=-536879873http://advantage.webmethods.com/cgi-bin/advantage/main.jsp?w=0&s=3232716887&targChanId=-536879873http://advantage.webmethods.com/cgi-bin/advantage/main.jsp?w=0&s=3232716887&targChanId=-536879873http://advantage.webmethods.com/cgi-bin/advantage/main.jsp?w=0&s=3232716999&targChanId=-536883238


11/178


C H A P T E R

1Getting Started

Basic Steps for Using Developer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Before You Use Developer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Starting Developer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Defining a Host Connection Pool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Defining a Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Associating a Transaction with a Host Connection Pool . . . . . . . . . . . . . . . . . . . . . . . . . . .


12/178

C H A P T E R 1 G e t t i n g S t a r t e d


Basic Steps for Using Developer

webMethods Developer is an integrated development environment. When used withwebMethods Mainframe, Developer allows you to define, modify, and manage thetransactions sent to and received from a mainframe computer. When you definetransactions, you should keep in mind that you are probably reproducing the client end ofinteractions that already exist.

When you use Developer to create transaction services, the basic work flow is as follows:

1 You need to start Developer and open a session with an instance of Integration Server

See Starting Developer on page 13.

2 Define host connection pools to be used by webMethods Mainframe.

A host connection pool is a group of sessions of a similar type. A session is a logicalpipe that defines the characteristics of a connection to a host application region on themainframe; sessions are used to send and receive data. See Defining a Host

Connection Pool on page 14.

3 Define transactions to be used by webMethods Mainframe.

A transaction service describes the input and output fields for an interaction with themainframe computer. See Defining a Transaction on page 18.

4 Associate transaction services with host connection pools.

By making an association, you specify that sessions of a particular host connectionpool can be used to send and receive transactions of a certain type. A transactionservice can be associated with only one host connection pool at a time, but you canswitch the association from one host connection pool to another. Doing so makes iteasy to move from a test region to a production region on the mainframe. SeeAssociating a Transaction with a Host Connection Pool on page 22.

Because you define transactions and host connection pools separately, you can choose theorder in which you create definitions. This freedom allows you to create definitions asinformation is available or to divide work according to the expertise of your developmentstaff.

The remainder of this chapter contains a simplified overview of how to use Developer todevelop transaction services. Subsequent chapters provide more detailed information.

Note: You can reverse the order of steps 2 and 3.


13/178

Before You Use Devel


Before You Use Developer

Developer defines and modifies transactions directly on Integration Server. To useDeveloper, you must:

Have access to an instance of Integration Server on which you have a user accounand belong to a group that is a member of the Developers access control list (ACon Integration Server.

Have access to webMethods Mainframe.

You will not be able to use Developer unless these requirements are satisfied. If you dohave access to Integration Server or you do not have an appropriate user account or acrights, see your server administrator.

Start ing Developer

1 Depending on which operating system is running on your workstation, do thefollowing:

Note: Before you attempt to start Developer, make sure the instance of Integration Servto which you want to connect is running.

To start Developer

If you are running... Do this...

Windows 1 On the Start menu, click Programs and then clickwebMethods.

2 Click webMethods Developer.

UNIX 1 Navigate to the directory where you installed Developer

2 In the /bin subdirectory run ./developer.sh.


14/178



3 In the Open Session dialog box, complete the following:

4 Click OK.

Defining a Host Connection Pool

A host connection pool is a group of sessions of a similar type. A session is a logical pipethat defines the characteristics of a connection to a host application region on themainframe, and which is used to send and receive data. Remember that you arereproducing a client-host interaction that already exists on the mainframe computer.Before you begin, you should know the connectivity details of the existing interaction.

You can break the process of defining a host connection pool into a few basic steps,described in the following sections:

1 Creating a Host Connection Pool on page 15.

2 Assigning the Properties of a Host Connection Pool on page 16.

In this field... Specify...

Server Type Integration Server . This choice causes the Developer windowto connect to Integration Server.

Server The name and port number of Integration Server inServerName:PortNum format. The default islocalhost:5555.

Note: Servers to which you have successfully logged on inthe past appear in the Serverlist. You can select a serverfrom this list or type its name and port number

Username The name of a valid user account on this server. The user

name must be a member of a group belonging to theDevelopers ACL.

Password The password for the user account in Username.Passwords are case-sensitive. For information aboutchanging your password, see the webMethods DeveloperUsers Guide.

Uses secure connection Determines whether the session is opened through HTTPor HTTPS. To open a Secure Sockets Layer (SSL) session,select this option.


15/178

Defining a Host Connection


3 Defining Sessions in the Host Connection Pool on page 17.

4 Associating a Transaction with a Host Connection Pool on page 22 (requires anexisting transaction service).

Creating a Host Connection Pool

One way to create a host connection pool is to do so manually.

1 On the File menu, click New.

2 In the New dialog box, select the Mainframe HostPool option and click Next.

3 In the Select Manual or Automatic HostPool Construction dialog box, click the CreateHostPool Shell For Manual Construction option and click Next.

4 In the Name field of the New Mainframe HostPool dialog box, type a unique name for host connection pool.

5 In the navigation tree of the dialog box, select the folder in which the host connecpool is to be stored.

6 Click Next.

7 In the Host Type Selection panel, select the option that describes the type of connectthe host connection pool is to be used for.

8 Click Finish.

For information about Host Types and the connections they represent, see Host Typeon page 43.

You can also generate a host connection pool from an XML file that has been previousexported from Developer. For more information, see Generating Host Connection Pofrom XML Files on page 25.

To create a new host connection pool manually


16/178



Assigning the Properties of a Host Connection Pool

The properties of a host connection pool are determined by the nature of the connectionbetween webMethods Mainframe and the mainframe computer, and by the hostapplication.

1 In the Navigation panel, double-click the host connection pool for which you want toassign properties.

2 In the editor, click the Properties tab to bring it to the front.

3 In the Properties tab, if the Host Type field does not have the correct value, select thecorrect value from the list.

Changing the Host Type may change which properties are available to be assigned ormodified. For information on valid Host Types, see Host Types on page 43.

4 Assign or modify individual host connection pool properties, as appropriate.

5 On the File menu, click Save.

For information on individual host connection pool properties, see Summary of HostConnection Pool Properties on page 27.

Defining Properties of a Host Connection Pool

To assign host connection pool properties

Double-click thehost connection

pool...

...click theProperties tab...

...assign propertiesas needed.


17/178

Defining a Host Connection


Defining Sessions in the Host Connection Pool

The number of sessions in a host connection pool, and their properties, are determinedthe nature of the connection between webMethods Mainframe and the mainframecomputer, and by the host application. It is common for a host connection pool to hav

multiple identical sessions so that a new transaction can be sent without waiting for aprevious transaction to be completed.

1 In the Navigation panel, double-click the host connection pool for which you wandefine sessions.

2 In the editor, click the Session Properties tab.

You are now ready to define host connection pool sessions. The first session is creafor you.

3 Edit the various columns in the row to define the field.

For information on the entries for this panel, see Defining General Information aba Session on page 32.

4 In the bottom panel, modify settings as appropriate for the session.

The settings in the bottom panel of the Session Properties tab represent attributes ofsession selected in the upper panel.

For information on the entries for this panel, see Defining Session InformationSpecific to a Host Type on page 35.

Defining host connection pool sessions

5 To add additional sessions, in the Session Properties tab, click (New).

A new row appears in the Session Properties tab.

To define the sessions of a host connection pool

...and modifysettings in thebottom panel.

...modify thecolumns in the

session...

Click the Newbutton...


18/178



Once you have defined a host connection pool, you can associate it with one or moreexisting transactions, described in Associating a Transaction with a Host ConnectionPool on page 22.

Defining a TransactionA transaction service describes the input and output fields for an interaction with themainframe computer. Remember that you are reproducing a client-host interaction thatalready exists on the mainframe computer. Before you begin, you should know the natureof the input and output fields that are part of this transaction.

You can break the process of defining a transaction into a few basic steps, described in thefollowing sections:

1 Creating a Transaction Service next on this page.

2 You can perform the following procedures in any order:

Defining Input and Output Fields on page 19.

Assigning Transaction Properties on page 21.

3 Associating a Transaction with a Host Connection Pool on page 22 (requires anexisting host connection pool).

Creating a Transaction Service

One way to create a transaction service is to do so manually.


2 In the New dialog box, select the Mainframe Transaction Service option and click Next.

3 In the Select Manual or Automatic Transaction Construction dialog box, select the CreateTransaction Shell for Manual Construction option and click Next.

4 In the Name field of the New Mainframe Transaction dialog box, type a unique name forthe transaction.

Tip! The defining of input and output fields can be time-consuming for transactions withmany fields. If you have access to copies of the files originally used to create thesetransactions on the mainframe (BMS maps, MFS files, or COBOL Copybooks), you canconvert them directly and then make modifications to suit the needs of the current project.See Chapter 4, Converting Source Code into Transaction Services for more information.

To create a new transaction shell for manual construction


19/178

Defining a Transa


5 In the navigation tree of the dialog box, select the folder in which the transaction be stored.

6 Click Next.

7 In the Host Type Selection panel, select the option that describes the type of connect

the transaction is to be used for.

Using the Deferred option, you can begin to define transactions, even if you havelimited knowledge of mainframe connectivity. Team members who have thatknowledge can work separately to define host connection pools.

8 Click Finish.


There are two other ways you can generate transaction services:

From an XML file that has been previously exported from Developer. For moreinformation, see Generating Transaction Services from XML Files on page 47.

From a source file used to create the transactions on the mainframe computer. SeeAuto-Conversion of Source Files on page 80.

Defining Input and Output Fields

Input fields contain information that is to be sent to the mainframe computer as part orequest. Output fields contain information that is to be returned from the mainframecomputer as part of a reply. The following steps are not comprehensive, but will serveshow how to define input and output fields.

1 In the Navigation panel, double-click the transaction for which you want to defininputs.

2 In the editor, click the Fields tab.

3 In the editor, click the Input tab at the top of the panel.

You are now ready to define input fields.

To define input and output fields


20/178



Defining a transaction

4 In the Input tab, click (New).

5 From the list, select a data type for the field.

For a list of valid data types, see Data Types on page 52.

6 In the new field, edit the various columns in the row to define the field.

See Populating or Modifying the Columns of a Field on page 50.

7 In the bottom panel, modify properties for the field.

The settings in the bottom panel of the Input tab represent attributes of the fieldselected in the upper panel.

See Modifying Field Properties on page 54.

Defining Input Fields

Double-click thetransaction...

...click the Fieldstab...

...and click theInput tab.

...and modifysettings in thebottom panel.

...modify thecolumns in the

field...

Click the Newbutton to create a

new field...


21/178

Defining a Transa


8 To define output fields, click the Output tab at the top of the panel and repeat stepthrough step 7 for each field.

Once you have defined input and output fields for a transaction, you can associate it wan existing host connection pool, described in Associating a Transaction with a Host

Connection Pool on page 22.

Assigning Transaction Properties

Before you can associate a transaction with a host connection pool, you must assigncertain properties to it that define how it is sent to, and received from, the mainframecomputer.

1 In the Navigation panel, double-click the transaction service for which you want t

assign properties.2 In the editor, click the Properties tab to make it active.

3 In the Properties tab, if the Host Type field does not have the correct value, select tcorrect value from the list.

4 Assign or modify individual transaction service properties, as appropriate.

See Summary of Transaction Service Properties on page 67.


To assign transaction service properties

Note: If the Host Type has already been assigned during the conversion of source coyou should not change the Host Type to one that is incompatible with the source.


22/178



Assigning transaction properties

Associating a Transaction with a Host Connection Pool

To associate a transaction with a host connection pool, both must already exist. Also, bothmust have the same Host Type assigned.

1 In the Navigation panel, double-click the transaction you want to associate with a hostconnection pool.

2 In the editor, click the Properties tab to make it active.


4 In the Properties tab, select the name of a valid host connection pool from the HostPoolName list.

Only names of host connection pools with compatible Host Types appear in the list. Ifthe list is empty, there are no compatible host connection pools defined.

Double-click thetransaction...

...click theProperties tab...

...select the hostconnection pool

type....

...assign propertiesas needed.

To associate a transaction with a host connection pool


23/178


C H A P T E R

2Working with Host Connection Pools

What is a Host Connection Pool? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Creating a Host Connection Pool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Assigning Host Connection Pool Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Creating and Modifying Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Host Connection Pool Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Enabling or Disabling Host Connection Pools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Uploading Host Connection Pools without Saving . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Viewing Validation Errors for Host Connection Pools . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Host Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Exporting Host Connection Pools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .


24/178

C H A P T E R 2 W o r k i n g w i t h H o s t C o n n e c t i o n P o o l s


What is a Host Connection Pool?

A host connection poolis a group of sessions of a similar type. A session is a logical pipethat defines the characteristics of a connection to a host application region on themainframe, and which is used to send and receive data. By having a number of similarsessions, it is possible for webMethods Mainframe to handle multiple transactions at thesame time.

Developer provides the tools you need to develop and manage your host connection poolsand sessions:

The Properties tab allows you to assign and modify the properties of individual hostconnection pools. See Assigning Host Connection Pool Properties on page 26.

The Session Properties tab allows you to create and modify sessions within a hostconnection pool. See Creating and Modifying Sessions on page 32.

If you are not already familiar with the basic activities involved in creating and defining

host connection pools, see Defining a Host Connection Pool on page 14.

Creating a Host Connection Pool

You can create a host connection pool in either of two ways, either manually or from anXML source file.

By default, when you create a host connection pool it is enabled, which means it isavailable for use with webMethods Mainframe. (Being enabled does not imply that thehost connection pool is valid.) To disable a host connection pool, see Enabling orDisabling Host Connection Pools on page 42.

Creating Host Connection Pools Manually

You can create a host connection pool manually using the following steps.


2 In the New dialog box, select the Mainframe HostPool option and click Next.

3 In the Select Manual or Automatic HostPool Construction dialog box, click the Create

HostPool Shell For Manual Construction option and click Next.

4 In the Name field of the New Mainframe HostPool dialog box, type a unique name for thehost connection pool.

5 In the navigation tree of the dialog box, select the folder in which the host connectionpool is to be stored.

To create a new host connection pool manually


25/178

Creating a Host Connection


6 Click Next.

7 In the Host Type Selection panel, select the option that describes the type of connectthe host connection pool is to be used for.

8 Click Finish.


Once you have created a host connection pool, you are ready to assign properties to it.Assigning Host Connection Pool Properties on page 26.

Generating Host Connection Pools from XML Files

You can generate a host connection pool from an XML file that has been previouslyexported from Developer. For information on exporting host connection pools from

Developer, see Exporting Host Connection Pools on page 44.


2 In the New dialog box, select the Mainframe Hostpool option and click Next.

3 In the Select Manual or Automatic HostPool Construction dialog box, click the GenerateHostpool from Source File option and click Next.

4 In the navigation tree of the dialog box, select the folder in which the host connecpool is to be stored.

5 Click Next.

6 In the Open Source File(s) for Automatic Conversion dialog box, click Open Source.

7 In the Open dialog box, traverse to the XML file and click Open.

You can list multiple XML source files in this dialog box. Each source file creates aseparate host connection pool.

Important! webMethods recommends that you do not attempt to edit an XML filecontaining a host connection pool. You should make changes within Developer beforeexporting the file.

To generate a host connection pool from an XML source file


26/178



8 Click Finish.

Each generated host connection pool has the same name it had when it was exportedfrom Developer. If a host connection pool of the same name already exists, Developerassigns a unique extension.


Assigning Host Connection Pool Propert ies

When you create a host connection pool, as described in Creating a Host ConnectionPool on page 24, you are required to assign a Host Type. Your choice of Host Typeindicates how webMethods Mainframe is supposed to connect to the mainframecomputer (SNA or TCP/IP) and, in most cases, specifies the type of host application (IMSor CICS). Each Host Type has its own set of properties, which you can assign or modify tosuit the specific needs of the host connection pool.

1 In the Navigation panel, double-click the host connection pool for which you want toassign properties.

2 In the editor, click the Properties tab to bring it to the front.


Changing the Host Type may change which properties are available to be assigned ormodified. For information on valid Host Types, see Host Types on page 43.

4 Assign or modify individual host connection pool properties, as appropriate.


To assign host connection pool properties


27/178

Assigning Host Connection Pool Prope


Summary of Host Connection Pool Properties

Some of the following host connection pool properties are common among all Host Tywhile others are used only where appropriate. For more information on the propertiethat are limited to IMS connect, CICS Sockets, and JES Publish, see the webMethods

Mainframe Administrators Guide.

To modify this

property... Do this...

Auto Start Select this option to cause sessions in this host connection pool tobe started when the server initializes. You must also set Auto Starfor each session. See Defining General Information about aSession on page 32.

Buffer Size JES Publish only. Optional value. The maximum size is 32K bytesthe default size is 512 bytes. We recommend that you do not

change this number except on advice from a mainframe systemprogrammer.

Comments Type an optional descriptive comment about the host connectionpool.

Custom EndBracket (EBI)Count

CICS LU 2, IMS LU 2, and TN3270E only. Type the number of endbracket indicators in the initial startup series. The default value is3. See Custom End Bracket Count on page 30.

Data Store IMS Connect only. Type the name of the IMS control region towhich transactions for this pool are targeted.

Data Translation IMS Connect only. Select where data translation is performed. Th

choices are Host Translation and Server Translation (the default).Enable theHostPool for Use

Select this option to make the host connection pool available foruse with webMethods Mainframe. (Being enabled does not implythat the host connection pool is valid.). See Host Connection PooStatus on page 40.

Exit Name IMS Connect only. If you are using the recommended standardIMS Connect exit (by selecting the Standard Exit option), leave thiproperty at the default value of *IRMREQ*. Otherwise enter thename of the IMS Connect exit that you are using.

Group ID IMS Connect only. Type the RACF group user ID if it is requiredThis value can be overridden by a session or by an individual

transaction.

Host Name IMS Connect only. Type either the IP address or the DNS name othe mainframe computer.

Host Port IMS Connect only. Type the port number on which IMS connect othe mainframe is configured to listen. Default value is 801.


28/178



Host Type Select the Host Type to be used for this host connection pool. SeeHost Types on page 43.

IMS Client Name IMS Connect only. Leave this field blank unless the systemadministrator tells you what to enter.

Lock Timeout Type the time in seconds that webMethods Mainframe will waitbefore releasing a locked session. The default is 180 seconds.

PassTicket IMS Connect only. Type the RACF password if it is required. Thisvalue can be overridden by a session or by an individualtransaction.

Password JES Publish only. An optional 8-character value used to identify thenode in an NJE connection. Use the password provided by amainframe system programmer.

Primary CodePage

Select a code page from the Primary Code Page list. The default valueis US English EBCDIC. For LU 2 host connection pools you canalso select a Secondary code page. For all other host connectionpools, you can select only the Primary code page.

For more information, see Code Pages in Host Connection Poolson page 30.

PublishingMethod

JES Publish only. Select the type of document being published.Choices are:

Record Base. Each record or line in the dataset is a separate

publish event. Document (Block). The publish event is made up of all records

or lines of a given data set.

Restart onSession Outage

Select this option to cause webMethods Mainframe to restart asession automatically after it has been disconnected by a host-connection error, such as might occur if a region on the mainframeis shut down. webMethods Mainframe continues to attempt asession restart at intervals specified by the Restart Timeoutproperty.

Restart Sessionon TransactionError

Select this option if webMethods Mainframe is to restart a sessionif a state error occurs. By default, the option is not set. See RestartSession on Transaction Error on page 31.

To modify this



29/178



Restart Timeout Type the time in seconds that webMethods Mainframe is to waitbefore attempting to restart sessions that have been disconnectedby a host-connection error. The default (and minimum) value is 3seconds. This property is not available if the Restart on SessionOutage option is not set.

Retry ConnectionCount

IMS Connect only. Type the number of times webMethodsMainframe is to attempt to open an IP connection, each timewaiting the number of seconds specified by the Retry Timeoutproperty. The default is 10 attempts.

Retry Timeout(seconds)

IMS Connect only. Type the time in seconds webMethodsMainframe is to wait before attempting to open an IP connectionafter the initial attempt failed. The default is 10 seconds. See also,Retry Connection Count.

Secondary CodePage

CICS LU 2, IMS LU 2, and TN3270E only. Select a code page fromthe Secondary Code Page list. The default value is NONE.

For more information, see Code Pages in Host Connection Poolson page 30.

Standard Exit(*IRMREQ*)

IMS Connect only. Select this option to have the host use thestandard IMS Connect exit (*IRMREQ*). If this option is selected,webMethods Mainframe builds all IMS Connect headers andtrailers.

Standard SignOff

Select this option to cause a transaction to issue a standard hostsign-off based on the Host Type.

Standard SignOn

Select this option to cause a transaction to issue a standard hostsign-on based on the Host Type. If no User ID and Password areavailable, this setting is ignored.

TransactionBuffer Size

JES Publish only. The size of the buffer that holds publishtransactions for transmission over the network. The maximum sizis 32K bytes; the default size is 512 bytes. We recommend that yodo not change this number except on advice from a mainframesystem programmer.

Transaction PipeName

IMS Connect only. Type the name of the LTerm override. Leavethis field blank unless the system administrator tells you what to

enter.

To modify this



30/178



Code Pages in Host Connection Pools

A code page maps character codes between Unicode and a localized character set. Unlessyou specify otherwise, the webMethods Mainframe default code page is US EnglishEBCDIC. EBCDIC (extended binary-coded decimal interchange code) is a coded characterset of 256 8-bit characters.

The code page specified in the Properties tab for a host connection pool applies to sessionmanagement activities between webMethods Mainframe and the mainframe computer. Tospecify a code page for a specific transaction service, see Assigning Transaction ServiceProperties on page 67.

For more information about code pages, see the IBM document Character DataRepresentation Architecture (SC09-2190-00).

Custom End Bracket Count

The establishment of an LU 2 session involves the exchange of a series of packets orWelcome screens sent from the host application on the mainframe to the 3270 terminal.Each packet contains an End Bracket Indicator (EBI), which indicates that all informationneeded to paint the screen has been sent.

When webMethods Mainframe acts in the place of an end terminal, it uses the EBI toidentify the end of a transaction. During session startup, webMethods Mainframe countsEBIs to know when a session is properly initialized.

Host systems are often modified such that multiple screens appear before the first screen

that invites user input. If there are more EBIs in session startup than webMethodsMainframe expects, it may send transactions before the session is available; if there arefewer EBIs, webMethods Mainframe continues to wait, assuming the session is not yetavailable.

By default, webMethods Mainframe expects to receive 3 EBIs during session startup. Thecorrect number for the Custom End Bracket Count is the highest value for which the

Use PersistentConnection

IMS Connect only. Select this option if you want to run a persistentconnection (open a connection only once); leave this option clear ifyou want to open a connection for each transaction. Ask yoursystem administrator whether the version of IMS Connect on themainframe computer supports persistent connections.

Note: It is much more efficient to run persistent connections, if thehost system supports them.

User ID IMS Connect only. Type the RACF user ID if it is required. Thisvalue can be overridden by a session or by an individualtransaction.

To modify this



31/178



status at session startup is consistently Available. Use webMethods MainframeAdministrator to display session status as well as to start and stop individual sessions

Use these guidelines to adjust the Custom End Bracket Count value:

For more information on using webMethods Mainframe Administrator to monitor sessstatus and to start and stop sessions, see the webMethods Mainframe Administrators Gu

Restart Session on Transaction Error

For LU 2 connections, webMethods Mainframe issues a state error if the current sessioappears to be in an incorrect state. In many cases such a condition occurs because thesession has been closed; all that is necessary to correct the error is for webMethodsMainframe to restart the session.

If the host application handles a session restart cleanly, you can select this option. If asession restart is likely to require human intervention, do not select this option.

Tip! In most cases, the default Custom End Bracket Count of 3 is the correct choice. Dotry another value unless there is clearly a problem in getting a session to initializeproperly.

If session status is... It means this...

Available You do not need to make any changes. If the sessionconsistently achieves a status of Available after startup, theCustom End Bracket Count is correct.

Session Error If the session consistently or occasionally achieves a status ofSession Errorafter startup, webMethods Mainframe may be

attempting to send a transaction before the session isinitialized.

Increase the Custom End Bracket Count value by 1 and restarContinue increasing the count until session status at startup iPending On and then decrease the count by 1 to achieve asession status of Available.

Pending On If the session achieves a status of Pending On after startup,webMethods Mainframe is waiting for another End BracketIndicator as part of session initialization.

Decrease the Custom End Bracket Count value by 1 and

restart. Continue decreasing the count until session status atstartup is Available.


32/178



Creating and Modifying Sessions

A host connection pool is a group of sessions of a similar type. For example, if the HostType selected for a host connection pool is CICS LU2, all sessions within that hostconnection pool will connect to CICS using the LU 2 screen-based protocol. It is commonto have multiple identical sessions within a host connection pool because it facilitates load

balancing and improves performance.

When you assign sessions to a host connection pool, keep in mind there is no point inassigning more sessions than the network allows. If you are connecting through SNA,make sure the number of sessions you need is configured in the SNA communicationsserver and on the mainframe computer. If you are connecting through TCP/IP, the numberof CICS sessions is limited by the number of concurrent tasks configured in the CICSregion. For IMS, you may be limited by a config entry called maxsoc in the IMS ConnectTCP/IP configuration. If in doubt, check with the system administrators for the networkand the mainframe computer. For more information, see the webMethods Mainframe

Administrators Guide.

Not all sessions within a host connection pool must be identical. You can, for exampleconfigure two groups of sessions with different User IDs and passwords.

The overall procedure for defining sessions has these basic activities:

Add the session and fill in the general columns in the upper portion of the SessionProperties tab. See Defining General Information about a Session on page 32.

Fill in the Host Type-specific fields in the lower portion of the tab. See DefiningSession Information Specific to a Host Type on page 35.

Defining General Information about a Session

When you define a session, the top panel of the Session Properties tab has the sameinformation for virtually all types of sessions.

1 In the Navigation panel, double-click the host connection pool for which you want todefine sessions.

2 In the editor, click the Session Properties tab.

You are now ready to define host connection pool sessions.

3 If you need to create a new session, in the Session Properties tab, click (New).

A new row appears in the Session Properties tab.

To define the general information for a session


33/178

Creating and Modifying Sess


4 In the session row, click the Name column and type the new session name.

For TCP/IP, type a descriptive name. For SNA, type the session or pool name exacas it appears in the SNA communications server configuration.

5 Click the Count column and type the number of sessions.

Type the number of instances of this session. For SNA, the number cannot exceednumber sessions configured in the SNA communications server.

6 Select or clear the Autostart option as appropriate.

Select this option to cause webMethods Mainframe to start this session when itinitializes. You must also select the Auto Start option in the Properties tab of the parhost connection pool. See Summary of Host Connection Pool Properties on pag

If you clear the Autostart option, you need to use webMethods MainframeAdministrator to start the session when it is needed. See the webMethods Mainfram


7 Select or clear the Restart option as appropriate.

Select this option to cause webMethods Mainframe to restart this session after acommunications error. If you clear the Restart option, you need to use webMethodMainframe Administrator to start the session when it is needed. See the webMetho

Mainframe Administrators Guide.

8 Click the User ID column and type the user ID needed for session sign-on.

If no user ID is needed, leave this column blank.

9 Click the Password column and type the password for the user ID.

As you type a password, Developer shows asterisks (*) on the screen as a securitymeasure. If you do not need a password, leave this column blank.

10 If needed, click the Comment column and type descriptive comment about the sess

This entry has no effect on the operation of webMethods Mainframe.


The information you must supply as part of this procedure also appears in Summary

Session Information next in this chapter.

Note: When you add each additional session, the new session is a copy of the lastsession on the list.


34/178



Summary of Session Information

The following table shows general information you can define for a session, as describedin Defining General Information about a Session on page 32.

Hiding Columns in a Session

To make the columns in a field easier to read, you can hide one or more columns.

1 In the editor, click either the Session Properties tab or Fields tab to bring it to the front.

2 Right-click any column header in the tab.

Column Description

Name For TCP/IP, type a descriptive name. For SNA, type the session orpool name exactly as it appears in the SNA communications serverconfiguration.

Count Type the number of instances of this session. For SNA, the numbercannot exceed the number sessions configured in the SNAcommunications server.

Autostart Select this option to cause webMethods Mainframe to start thissession when it initializes. You must also select the Auto Startoption in the Properties tab of the parent host connection pool. See

Summary of Host Connection Pool Properties on page 27.Restart Select this option to cause webMethods Mainframe to restart this

session after a communications error. If you clear the Restartoption, you need to use webMethods Mainframe Administrator tostart the session when it is needed. See the webMethods Mainframe


User ID Type the user ID needed for session signon. If no user ID isneeded, leave this column blank.

Password Type the password for the user ID. As you type a password,Developer shows asterisks (*) on the screen as a security measure.If you do not need a password, leave this column blank.

Comment Type descriptive comment about the session. This entry has noeffect on the operation of webMethods Mainframe.

To hide columns in the Session Properties tab or Fields tab


35/178



3 In the Select Column dialog box, perform either or both of these actions:

4 Click OK.

Defining Session Information Specif ic to a Host Type

When you select an individual session in the Session Properties tab for a host connectiopool, the bottom panel of that tab contains settings for that session. In some cases, youuse this panel to override settings made for the entire host connection pool in theProperties tab. In other cases, the panel provides options that you can only find in this

panel.

1 In the Session Properties tab, select one or more identical sessions.

2 In the bottom panel, modify settings as appropriate for the session.


See Summary of Session Information Specific to a Host Type next in this chapter.

Summary of Session Information Specific to a Host TypeThe following table describes session attributes based on the Host Type specified for tsession:

To do this... Do this...

Make a column visible Select the option for that column.

Hide a column Clear the option for that column

To define session information specific to a Host Type

Attribute/ by Host

Type Description

APPC

Local LU Name Type the LU name on the webMethods Mainframe end of theconnection.

Remote LU Name Type the LU name on the mainframe end of the connection.

Local TP Name Type the Transaction Program name by which the local sessionidentifies itself to the mainframe computer. By default, this nameWMMIS.


36/178



Mode Name Type the mode name used for the LU 6.2 connection. The modename is an 8-byte EBCDIC character string that specifies a set of

networking characteristics defined during configuration. TheValue of the mode name must match the value used by the remoteLU on the mainframe. Common mode names are #BATCH and#INTER.

CICS DPL

Local LU Name Type the LU name on the webMethods Mainframe end of theconnection.

Remote LU Name Type the LU name on the mainframe end of the connection.

Local TP Name Type the Transaction Program name by which the local sessionidentifies itself to the mainframe. By default, this name is WMMIS.

Mirror Transaction Type the name of the CICS mirror transaction program that resideson the mainframe computer. This program routes requests to theCICS application. By default, this name is CSMI.

Mode Name Type the mode name used for the LU 6.2 connection. The modename is an 8-byte EBCDIC character string that specifies a set ofnetworking characteristics defined during configuration. TheValue of the mode name must match the value used by the remoteLU on the mainframe. Common mode names are #BATCH and#INTER.

CICS LUO

Start Type Select one of these ways to initialize the session: Host Init, Init Self,or Send Text. See Start Type on page 39.

Application Name Type the plain-text message that is to be sent under the Init SelfStart Type. See Start Type on page 39.

CICS LU2


Application Name Type the plain-text message that is to be sent under the Init Self orSend Text Start Type. See Start Type on page 39.

Model Type From the list, select the model of display terminal for which theoriginal mainframe transaction was intended. See Model Typeson page 39.

Attribute/ by Host

Type Description


37/178



CICS Publish (For more information about the session attributes, see the webMethodsMainframe Administrators Guide.)

Host Name Type the IP address or the name of the mainframe computer.

Host Port Type the port number that CICS on the mainframe is configuredlisten on.

Host Gateway

Name

Type the name of the CICS transaction that points to the publishgateway program. The name should have from one to fourcharacters.

Publish Config

Name

Type the name of the program on the mainframe computer thatcontains publish configuration data for an instance of the publisgateway.

Sign on in ASCII Select this option to send the signon user data (userid andpassword) in ASCII. This option is required if the CICS TRANUSsetting in the CICS TCP/IP Socket Interface configurationtransaction is YES. The default is to send the data in EBCDIC.

Use ASCII for

Transaction Code

Select this option to send the transaction code in ASCII. Thisoption is required if the CICS TRANTRN setting in the CICSTCP/IP Socket Interface configuration transaction is YES. Thedefault is to send the transaction code in EBCDIC.

CICS Sockets (For more information about the session attributes, see the webMethodsMainframe Administrators Guide.)

Host Name Type the IP address or the name of the mainframe computer.

Host Port Type the port number that CICS on the mainframe is configuredlisten on.

Host Gateway

Name

The name of transaction that points to the transaction serverprogram you have built on the host system. The name should hafrom one to four characters.

Use Persistent

Sockets

Select this option if you want the session to use persistent socke

Sign on in ASCII Select this option to send the signon user data (userid andpassword) in ASCII. This option is required if the CICS TRANUSsetting in the CICS TCP/IP Socket Interface configuration

transaction is YES. The default is to send the data in EBCDIC.

Use ASCII for

Transaction Code

Select this option to send the transaction code in ASCII. Thisoption is required if the CICS TRANTRN setting in the CICSTCP/IP Socket Interface configuration transaction is YES. Thedefault is to send the transaction code in EBCDIC.

Attribute/ by Host

Type Description


38/178



ECI TCP

Host Name Type the IP address or the name of the mainframe computer.Host Port Type the port number that CICS on the mainframe is configured to

listen on.

IMS LUO


Application Name Type the plain-text message that is to be sent under the Init SelfStart Type. See Start Type on page 39.

IMS LU2


Application Name Type the plain-text message that is to be sent under the Host Init,Init Self, or Send Text Start Type. See Start Type on page 39.


TN3270E

Start Type Select one of these ways to initialize the session: Host Init, SendText, or Send Text - OS/390. See Start Type on page 39.

Application Name Type the plain-text message that is to be sent under the Send Textor Send Text - OS/390 Start Type. See Start Type on page 39.


Host Name Type the host name or the IP address of the mainframe computer.

Host Port Type the port number used by TN3270E on the mainframecomputer. The default value is 23.

Device Name Optional value. Type the name of a device on a TN3270E hostgateway that defines a pool on that server.

Attribute/ by Host

Type Description


39/178



Start Type

In SNA, a request to activate a session between primary and secondary logical units (Lis called a BIND. The Start Type option determines how webMethods Mainframe sets uBIND for each session. The Start Type option is only valid for SNA and TN3270E

connections; the option is ignored for TCP/IP connections. For TN3270E, see CommoTN3270E Gateway Properties on page 40.

Model Types

LU 2 transactions are programmed to use particular 3270 terminal types, and if theterminal type information is not available, the transaction will fail. The terminal choicinclude codes for the model size and for whether or not to include extra attribute byte(EABs). Using EABs causes the mainframe system to return double the information thotherwise would return. The additional information pertains to character attributes, sas the use of underscores or colors. If your transactions do not use EABs and you areconcerned about performance, do not select the EAB option.

This Start Type... Creates an SNA BIND in this way...

Host Init When webMethods Mainframe starts a session, the mainframautomatically sends a BIND to the LU.

Init Self webMethods Mainframe sends an INITSELF string with theregion or application name and the mainframe responds witha BIND to the LU. Not available with TN3270E.

Send Text webMethods Mainframe sends a plain-text login message

(USS or Unformatted System Services Logon) and themainframe responds with a BIND to the LU. Type the plain-text message in the Application Name field in the lower panel.

Send Text - OS/390 TN3270E only. Use in place of Send Text, in cases where youare connecting to a TN3270E server directly on OS/390, ratherthan through an SNA communications server. Type the plaintext message in the Application Name field in the lower panel.


40/178



Common TN3270E Gateway Properties

The following table describes properties for commonly used TN3270E gateways:

*See Start Type on page 39.

** See Custom End Bracket Coun

web methods mainframe developers guide 65

Documents