APP BUILDER ConfiguringComm

8/14/2019 APP BUILDER ConfiguringComm

1/168

BluePhoenix AppBuilder 2.1 .0.

Configuring Communications Guide
http://www.bluephoenixsolutions.com/


2/168

BluePhoenix AppBuilder 2.1.0.Configuring Communications GuideApril, 2003

Corporate Headquarters

BluePhoenix Solutions

Vlierwerf 7B4704 SB RoosendaalThe Netherlands+31 (0) 165 399 401+31 (0) 165 396 308 fax

USA HeadquartersBluePhoenix Solutions USA, Inc.8000 Regency ParkwayCary, NC 27511United States+1 919.380.5100+1 919.380.5111 fax

www.bluephoenixsolutions.com

1992-2003 BluePhoenix Solutions

All rights reserved.

BluePhoenix is a trademark of BluePhoenix Solutions. All other product and company namesmentioned herein are for identification purposes only and are the property of, and may be trademarksof, their respective owners.

Portions of this product may be covered by U.S. Patent Numbers 5,495,222 and 5,495,610 and various

other non-U.S. patents.

The software supplied with this document is the property of BluePhoenix Solutions, and is furnishedunder a license agreement. Neither the software nor this document may be copied or transferred by anymeans, electronic or mechanical, except as provided in the licensing agreement.

BluePhoenix Solutions has made every effort to ensure that the information contained in this documentis accurate; however, there are no representations or warranties regarding this information, includingwarranties of merchantability or fitness for a particular purpose. BluePhoenix Solutions assumes noresponsibi li ty for errors or omissions that may occur in this document. The information in thisdocument is subject to change without prior notice and does not represent a commitment byBluePhoenix Solutions or its representatives.
http://www.bluephoenixsolutions.com/http://www.bluephoenixsolutions.com/


3/168

AppBuilder 2.1.0 Configuring Communications Guide i

TABLE OF

CONTENTS

Table of Contents

AppBuilder 2.1.0 Configuring Communications Guide

1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1

2 Configuring and Managing Communications in Windows . . . . . 2-1

Sett ing Up Windows Communications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1Launching the Communications Setup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2

Understanding the Setup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2Other Init ial Communications Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-5

Managing the System Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5Launching the Service Control. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-6Using the Service Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-6Command Line Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-7Launching the Management Console. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-8Understanding the Console. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-9Edit ing the Configuration File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-10

Viewing Product Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-10

Viewing or Clearing Audit Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-11

Managing the Computers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-11Adding a Computer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-12Refreshing the Computer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-12Removing a Computer.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-12

Managing Servers and Gateways. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-13Creating a Windows Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-13Creating a Windows Gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-14Starting and Stopping a Server or Gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-15Refreshing a Server or Gateway. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-16Pinging a Server or Gateway. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-16Deleting a Server or Gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-16Viewing and Clearing the Trace Log. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-16

Viewing and Modifying Properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-16Using TCP/IP Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-17


4/168

ii AppBuilder 2.1.0 Configuring Communications Guide

Configuring Clients, Servers, and Gateways. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-17Configuring a Java Client for Remote Communications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-17Adding a Server for Client Communications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-19Custom Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-23Configuring a Windows Client for Remote Communications. . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-23Configuring Performance Settings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-25Configuring Security Sett ings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-26Configuring Trace Log File Settings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-27Configure aServer for Remote Communications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-28ConfigureaGateway for Remote Communications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-29

Understanding Routing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-31Edit ing the Route Table. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-31Using Wild Cards and Priority . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-35Understanding Routing Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-37Configuring Routing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-43

3 Conf iguring Communicat ions in UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1

Starting UNIX Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1Creating AppBuilder User Accounts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2Starting the Configurator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2

Understanding the UNIX Configurator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-4

ConfiguringaUNIX Client for RemoteCommunications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-6Configuring Basic Settings of Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-7Configuring Advanced Settings of Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-10Edit ing Client Communications Sett ings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-14Creating a New UNIX Client for Remote Communications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-15

Configuring aUNIX Server for RemoteCommunications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-16Configuring Basic Settings on the Server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-17Configuring Advanced Settings on the Server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-19Editing Server Communications Settings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-20Creating a New UNIX Server for Remote Communications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-21

Configuring aUNIX Host for Messaging Applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-22Configuring a UNIX Messaging Client or Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-22Configuring the UNIX Messaging Agent. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-23

ConfiguringaUNIX Host for Eventing Applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-27Configuring a UNIX Eventing Client or Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-27Configuring the UNIX Eventing Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-28

Configuring a UNIX Batch Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-29

Configuring a UNIX Gateway. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-31

Configuring a UNIX Database. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-31

Completing UNIX Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-32


5/168

Table of Contents iii

4 Configuring Communications on the M ainframe . . . . . . . . . . . . . . . . . . 4-1

Starting Mainframe Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1Viewing and Editing Runtime Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2

Performing Maintenance Operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-4

Configuring LU2 Clients. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-5

Configuring LU6.2 Clients. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-5Communications Manager Usage. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-6

Configuring LU2 Terminal Emulator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-6

Understanding Performance Marshalling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-7

5 Configuring Communications Using MQSeries. . . . . . . . . . . . . . . . . . . . . 5-1

Understanding MQSeries RPC Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1

Meeting Prerequisites for MQSeries RPC. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3

Configuring MQSeries RPC. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3Collect Setup Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3Configure AppBuilder Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-4Configure MQ Server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-5Configure Mainframe MQ Series. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-6Customize Mainframe INI File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-8

Handling Errors in MQSeries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-10

6 Extending Communicat ions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1

Communication Exits in Java. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2Implementing Communications Exits. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2

Authentication Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-3Authentication Sett ings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-4Sample Java Class for Exits. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-5Custom Transport in Java. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-9

Security Exits in C. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-14Authentication. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-14Authorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-16Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-17Setting Up Security Exits. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-18Security Exits Reference for C. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-19AuthentLibMain. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-20AuthorLibMain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-21EncryptLibMain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-22SrvAuthentLibMain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-22SrvAuthorLibMain. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-23RpcEndLibMain. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-24Open Data Encryption Mechanism. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-24dna_BufInit. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-25dna_BufEncode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-26dna_BufDecode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-27dna_BufClose. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-27


6/168

iv AppBuilder 2.1.0 Configuring Communications Guide

Directory Services Exits in C.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-28dna_ExtRoutes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-30dna_ExtSubcells. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-32dna_ExtTriggers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-33dna_ExtEvents. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-34

Database Exits in C. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-35

sdbi_Connect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-36sdbi_StartTxn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-36sdbi_CommitTxn. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-37sdbi_AbortTxn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-37sdbi_Disconnect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-38Sample Database Exit Routines. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-38

Customized Data Types in C. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-40Using Custom Data Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-41Identifying the Data Type. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-41Writing the Marshalling Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-42

Compiling and Linking. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-43Using the Visual C++ Compiler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-44

Example Directory Services Exits. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-44Example Database Exits. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-45

A Code Page Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A-1

Supported Code Pages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-1

Supported Code Page Conversions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-3

B Mainf rame Logon Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-1

Logon Script Reference. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-2

Index


7/168

AppBuilder 2.1.0 Configuring Communications Guide 1-1

CHAPTER

1

INTRODUCTION


AppBuilder is an advanced development environment that uses internal communications for connectingthe various tools and services for mult i-platform deployment. The various platforms and protocols thatcan be used are covered in separate chapters:

Chapter 2, Configuring and Managing Communications in Windows

Chapter 3, Configuring Communications in UNIX

Chapter 4, Configuring Communications on the Mainframe

Chapter 5, Configuring Communications Using MQSeries

The abil it y to interface with the communications facil ities is covered in Chapter 6, ExtendingCommunications.

For information on warning messages or error messages related to communications, refer to theMessages Reference Guide.


8/168

1-2 Introduction


9/168


CHAPTER

2

CONFIGURING AN D M ANAGING

COM M UNICATIONS IN WINDOWS


Use the Management Console to manage and configure aspects of AppBuilder communications on alocal or remote computer. The Management Console enables you to:

configure Java and Windows client communications for application execution

create mult iple AppBuilder application servers and protocol gateways

configure application servers and protocol gateways

manage application servers and protocol gateways view communications error logging and tracing

modify the AppBuilder configuration through the AppBuilder system configuration fi le (hps.ini )

easily modify other AppBuilder-associated configuration (.ini) files through a dedicated ini editor

Refer to:

Sett ing Up Windows Communications

Managing the System Service

Managing the Computers

Managing Servers and Gateways

Configuring Clients, Servers, and Gateways

Understanding Routing

Sett ing Up Window s Communications

Use the AppBuilder Communications Setup program to configure your system and allowcommunication between the various tools and services of the AppBuilder system. This includes:

Launching the Communications Setup

Understanding the Setup

Other Ini tial Communications Configuration

Note Make sure to shut down all AppBuilder communications clients and servers before configuring the host.

Note As with any AppBuilder communications application, the Management Console only works betweenmachines where the code page mapping exists.


10/168

2-2 Configuring and Managing Communications in Windows

Setting Up Windows Communications

Launching the Communications Setup

From the Startmenu, select Start > Programs > AppBuilder > Communications >Communications Setup.

Figure 2-1 Commun icat ions menu

The setup wizard screens are displayed. Refer to the descriptions in Understanding the Setup.

Understanding the Setup

From the Communications Setup wizard, select the scope of the configuration. Refer to Figure2-2.Select Limited for selecting only the protocol or database settings. Select Completeto create a new baseconfiguration and select all the options in the communications setup.

Figure 2-2 Communicat ions Setup - Scope screen

If the AppBuilder Communications service is currently running when you attempt to run the setup, thesystem notifies you and gives you the option to stop the service or stop the setup.

Figure 2-3 Already running dialog

The limited setup includes the following tasks:

Select Protocol

Select Database Management System (DBMS)

The complete setup includes the following tasks:

Select Protocol

Select Code page

Select Eventing Parent

Select Database Management System (DBMS)

Select Setup


11/168


12/168


Setting Up Windows Communications

Select Eventing Parent

Enter the name of the eventing parent (host) in the Hostname field on the Eventing Parent screen.Refer to Figure2-6.This information is only required if global eventing is used. If connecting to a UNIXworkgroup (Freeway) repository, global eventing must be configured.

Figure 2-6 Communications Setup - Eventing Parent screen

Select Database Management System (DBM S)

Select a database management system (DBMS) from the drop-down list on the Database screen.Refer to Figure2-7. If the there is no DBMS installed on this machine or you are not using it,select None.

Figure 2-7 Communications Setup - Database screen


13/168



Other Initial Communications Configuration

Other ways to configure communications involve edit ing the configuration fi les (.ini) on theworkstation. From the Management Console, you can select the icon for the client machine andright-click on the Java icon to edit the appbuilder.ini file with values relating to Java, as shown inFigure2-8. Refer to Launching the Management Consolefor information on logging in to theManagement Console.

Figure 2-8 Ed it ing appbui lder.ini

Edit the appbuilder.ini fi le on the workstation to change some of the configuration of communicationsin AppBuilder. For example, the ABORT_ON_COMM_ERROR value in the NC section ofappbuilder.ini allows you to set whether to abort (terminate) AppBuilder when a communication error

occurs. (This example is shown in Figure2-8.)

In the thin-client environment, the COMM_ERROR_RULE is run as a detached rule like any other thin-client rule. So, if you are using ABORT_ON_COMM_ERROR, then you cannot haveUSE_COMM_ERROR set true and vice versa. The two settings are mutually exclusive.


The AppBuilder system service is a background process that maintains and coordinates the starting andstopping of the various AppBuilder communications servers, gateways, and agents. The service is not aWindows service; it is just a simple process. When you stop the AppBuilder service, you stop anyconfigured servers and gateways as well as the service. The control of the AppBuilder system service ishandled by the Service Control of AppBuilder Communications. The management of communicationsand services is handled by a system administrator through the Management Console.

Use the AppBuilder Communications Service Control to start and stop the AppBuilder system serviceand to check on the status of that service. The AppBuilder system service (or AppBuilder service, forshort) is an executable that runs in the background. It manages the starting and stopping of the variousAppBuilder communications servers. This topic includes:


14/168



Launching the Service Control

Using the Service Control

Command Line Control

The service also automatically starts the AppBuilder service agent that is required for several criticalcommunications tasks:

Receives remote preparation results

Enables remote configuration

Used in Distr ibuted RuleView (debugging)

Handles eventing

Manages AppBuilder servers and gateways

Handles broadcasting for UNIX workgroup (Freeway) repositories

From here you can also launch the Management Console. This includes:

Launching the Management Console

Understanding the Console

Launching the Service Cont rol

From the Startmenu, select Start > Programs > AppBuilder > Communications > Service Control.

Figure 2-9 Commun icat ions menu

This launches the Service Control and automatically starts the AppBuilder service if it is not alreadyrunning. An icon appears in the Windows task bar (typically the lower right of your workstation screen).Refer to the descriptions in Using the Service Control.

Figure 2-10 Icon in example task bar

Using the Service Control

Single-click (right or left mouse button) on the Service Control icon and the Service Control menuappears, as shown in Figure2-11.

Select Service Control

Icon for Service Control


15/168



Figure2-11 Service Control menu

Hiding the Service Control Icon

To remove the Service Control icon from the task bar, select Hide. This only hides the icon from view; itdoes not stop the service. (The service is not interrupted.) To Show the icon again, you can go throughthe menu options again (Start > Programs > AppBuilder > Communications), chooseService Control,and the icon appears again. This Hide option only hides this icon on the task bar for that session. I t doesnot disable the icon indefinitely.

Starting or Stopping the System Service

From the Service Control menu you can start or stop the communications service. Select either

Stop AppBuilder System Serviceor Start AppBuilder System Servicefrom the Service Control menu.

Launching M anagement Console

From the Service Control menu you can launch the AppBuilder Management Console. Refer toLaunching the Management Console.

Comm and Line Control

In the same way that you can use the Service Control to start or stop the AppBuilder service, you canperform these functions from a command line interface.

Service Control Comm and

To control the AppBuilder service, run this command (with any of three parameters) from a commandprompt:

abservice -check

abservice -start

abservice -stop

The first checks (or confirms) that the AppBuilder service is running. The second starts the service if it isstopped. The third stops the service if it is started.

Product Informat ion Command

To see the product version information, run the product information command from a commandprompt:

abprdinf


16/168



When you run this command from the directory where the system configuration fi le (hps.ini) isinstalled (or at least have it defined in the path) you can look at product version information. Thiscommand displays the product version information on the screen and saves the same information to afi le that you can open wi th a text editor.

The file that is created is machinenameinfo.ini wheremachinenameis the name of the machine fromwhich you the command is run. For example, if the machine name is jsmith, the file created would bejsmithinfo.ini. The file is saved in the AppBuilder installation directory.

An example log fi le (or display) could look like this:

[PRODUCT_INFO]

RELEASE=AppBuilder

VERSION=2.1

[PRODUCT.Construction Workbench]

Installed=3-24-2002

Version=AppBuilder20_3

[PRODUCT.Development Kit for Java, HTML, and EJB]

Installed=3-24-2002


[PRODUCT.Freeway Repository]

Installed=3-24-2002


[PRODUCT.Personal Repository]

Installed=3-24-2002


[PRODUCT.TurboCycler SDK]

Installed=3-24-2002


[EFX.D20204n]

Installed=4-13-2002

Launching the Management Console

From the Startmenu, select Start > Programs > AppBuilder > Communications >Management Console. Or from the Service Control, select Launch AppBuilder Management Console.

Figure 2-12 Communicat ions menu

The login dialog is displayed as in Figure2-13so you can login to the local machine configuration.Fill out the user ID and password of the local machine user account and click OK. If the guest accounton a workstation is enabled with no password, then you are not prompted for security when you load

Select Management Console


17/168



that computer into the Management Console. The user ID and password are authenticated against theoperating system. The status of the configuration of communications is shown briefly, as in Figure2-14.

Figure 2-13 Log in dialog

Figure2-14 Launching d ia log

With this, you are logging in to the local computer configuration. This is important to understandbecause if you press Cancel, the Management Console still starts, but the local machine is disabled untilyou issue a refresh, at which point you are prompted to login again.

Understanding the ConsoleThe Management Console window shows a graphical representation of the communications resourcesdefined by the user on Windows (NT or 2000) machines. From this window you can select menuoptions, click on resource icons and manage the resources associated with those icons. Figure2-15illustrates a typical Management Console window.

Figure 2-15 Management Console window example

conner05

mconner

Menus

Resource icons

GraphicalDisplay

mach_fir

mach_second


18/168


Viewing Product Information

From the console, you can select a machine (client, server, or gateway) by clicking on the icon for thatmachine and right-click to select the properties. In this way you can modify the resources. You can addmachines or resources by selecting the icon for the type of resource and selecting the add option fromthe pop-up menu. You can delete a resource by selecting the icon for that resource and pressing theDelete key. If the resource icon has be refreshed, you can see at a glance whether that resource is started(active) or not.

If AppBuilder cannot find a computer (a machine previously added), AppBui lder issues a message andthen leaves the computer in the tree with an 'inactive' icon. The menu selections at this point are alsogreyed out for that machine and you can only remove or refresh the computer. If a refresh finds themachine active, everything returns to normal: the icon is displayed as active and the menu items return.

Editing the Configurat ion File

From the Management Console, you can modi fy the configuration sett ings in the configuration (.ini)file for that resource. To edit the configuration file, select the resource icon of the resource to configureand choose Edit INI Filefrom the menu. You can modi fy the system configuration by editing the system

configuration file, hps.ini. Each tab is a section of the file and you can modify values as needed.Figure 2-16 Example configuration file in editor


You can view information about which AppBuilder products (and which versions) are installed on agiven machine. Right-click on a computer icon in the hierarchy and select View Product Information.For more information about viewing installed product versions, refer to the explanation in theInstallati on Guide for Windows.

Each section of the file isavailable on a tab.

Each variable of that section isavailable in this list.

You can modify the value andclick Set.

If there is help available for thatvalue, it is displayed here.


19/168

Viewing or Clearing Audit Information


View ing or Clearing Audit Information

AppBuilder keeps track of the actions taken when starting or stopping services or modifyingconfiguration (.ini) files. This information is kept in a fi le, called an audit file. To view the fi le, right-clickon a computer and select View Audit Information. AppBuilder loads the file from the local machine or aremote machine and allows you to view it in the system default text editor (such as Notepad). See

Figure2-17for a sample audit file.

Figure2-17 Sample audit fi le

The audit information contains columns of information.

date and time stamp

user ID

action, whether executed, modified, created or deleted

name of the fi le edited or service started or stopped

To clear the file and erase all entries, right-click on a Computer object icon and select Clear AuditInformation. The entries are erased and the only entry left in the log is a message that the audit file was

deleted:

11/12/01-12:03:31- userID- DELETED - cfgclient\auditfile.out

M anaging the Computers

From the Management Console you can perform many administrative functions with the Computerobjects, the highest level in the hierarchy. These include:

Adding a Computer

Refreshing the Computer Removing a Computer

Viewing or Clearing Audit Information


Edit ing the Configuration File


20/168


Managing the Computers

Adding a Computer

You can add a remote computer to the management console by selecting the Computersicon in theconsole window, r ight-clicking and from the pop-up menu, selecting Add Computer. TheAddComputerdialog appears as shown in Figure2-18. Enter the host name (the machine name) and theserver identifier, which defaults to ne20. Click OKwhen done.

Figure 2-18 Add Computer d ialog

When a new computer is added the user is prompted for a user name and password that is vali d for thetarget machine.

Refreshing the Computer

To see the latest updates to the hierarchy of machines and services, you can update the ManagementConsole display. Right-click on a computer icon in the hierarchy and select Refresh Computer. Thisupdates the display and shows any computers that have been added or removed. For a list of informationabout what actions have been taken on this computer, refer to Viewing or Clearing Audit Information.

Removing a Computer

If you have more than one computer displayed in your Management Console, you can remove anycomputer other than your own workstation from the display. Right-click on a computer icon in thehierarchy and selectRemove Computer. You cannot remove your own workstation, from which thisManagement Console is running, from the console display.


21/168




From the Management Console you can perform many administrative functions with the servers andgateways. These include:

Creating a Windows Server

Creating a Windows Gateway Starting and Stopping a Server or Gateway

Refreshing a Server or Gateway

Pinging a Server or Gateway

Deleting a Server or Gateway

Viewing and Clearing the Trace Log

Viewing and Modifying Properties

Using TCP/IP Services

Creating a Windows Server

From the Management Console you can create a server on Windows (NT or 2000) by selecting theServersicon in the console window, right-clicking and from the pop-up menu, selecting NewServer.

The dialogs appear as shown in Figure2-19. Fill out the information in each dialog. Click Nexttoadvance to the next screen. Click Finishwhen done. The system queries the TCP/IP services file for theserver ID. If it does not already exist, it asks you to enter a port number and add it to the services file.Enter the port number and click OK. Refer to Managing Servers and Gatewaysfor more information.

Figure 2-19 Creating a server - Protocol and subsequent dialogs


22/168



The console then displays the created server as a new icon under theServersicon. The name shown nextto the icon appends either an np (for named pipes) or tcp (for TCP/IP) depending on the protocolyou selected.

When a new server is created, AppBuilder checks the product information to see if it is a departmentalserver. AppBuilder grays out the Edit HPS.INI option because an HPS.INI file is not needed on a

departmental server.

Creating a Window s Gatew ay

From the Management Console you can create a gateway by selecting the Gatewaysicon in the consolewindow, right-clicking and from the pop-up menu, selecting NewGateway.

TheProtocoldialog appears as shown in Figure2-20. Fill out the information about the protocol. ClickOKwhen done. The system queries the TCP/IP services fi le for the gateway server ID. I f it does notalready exist, you must enter a port number and add it to the services file. Enter the port number andclick OK. Refer to Managing Servers and Gatewaysfor more information.

Figure 2-20 Creating a gateway - Protocol and subsequent dialogs

Table 2-1 Properties for creating a server

Dialog field Description

Protocol Host name This defaults to the machine name as is not editable by the user.

Protocol This is user-selectable as either tcpip (for TCP/IP) or NPIPE (for Named Pipes).

Server ID This is a user-defined, unique identifier for this server.

System DBMSThis defaults to the database management system (DBMS) specified when youinstalled AppBuilder, configured communications, and selected a DBMS. This isnot editable by the user.

Database name This is a user-defined, unique identifier for the database.

Port This is a user-defined, unique port number for this server.


23/168



The console then displays the created gateway as a new icon under the Gatewaysicon.

Start ing and Stopping a Server or Gatew ay

From the Management Console you can start or stop an individual server or gateway. When you start aserver or gateway it becomes active and the icon changes to green in the console window. When a serveror gateway is stopped it becomes inactive and the icon changes to red in the console window. This issummarized in Figure2-21.

Figure 2-21 Icon colors

To start a server, right-click on the particular server icon in the console window and select Start Server.

To stop a server, right-click on the particular server icon in the console window and select Stop Server.

To start a gateway, right-click on the particular gateway icon in the console window and selectStart Gateway.

To stop a gateway, right-click on the particular gateway icon in the console window and selectStop Gateway.

Table 2-2 Properties for creating a gateway

Dialog field Description

Protocol Host name This defaults to the machine name and is not edi table by the user.

ProtocolSelect the protocol that this gateway listens on for incoming application servicerequests. This is user-selectable as either tcpip (for TCP/IP) or NPIPE (for

Named Pipes).

Server IDThis is the unique identifier for the TCP/IP port or Named Pipes p ipe name(depending on what protocol was selected) of the gateway.

Single Server Refer to Configuring for a Single Server.

Single Server Host Name host name or machine name (see Table 2-15)

Single Server Protocol tcpip ( for TCP/IP) or NPIPE (for named pipes)

Single Server Code Pageselect from the list of code pages (Refer to Appendix A, Code Page Supportfor a list of supported code pages.)

Single Server ID server ID

Multiple Servers Refer to Configuring for Multiple Servers.

Route Table Refer to Editing the Route Table.

Port This is a user-defined, unique port number for this server.

Active (started) serverhas green icon.

Inactive (stopped) serverhas red icon.


24/168



Refreshing a Server or Gateway

From the Management Console you can refresh the display of a resource (server or gateway). The iconsin the console window show whether a server or gateway was stopped or started as shown in Figure2-21.But this information is not updated dynamically. To view the latest status of a Server or Gateway, refreshthe resource. To refresh the resource (server or gateway), right-click on the particular resource icon inthe Management Console window and select Refresh Serveror Refresh Gateway.

Refreshing the server or gateway icon only updates whether or not the server or gateway is started orstopped. It does not show if the server or gateway has been deleted. Perform a refresh on the computericon to show if a server or gateway has been deleted. Refer to Refreshing the Computer .

Pinging a Server or Gatew ay

From the Management Console you can ping a server or gateway to see whether it is active or not.The system displays an information dialog that tells you whether the server or gateway is active (started)or inactive (stopped). To ping a resource (server or gateway), right-click on the particular resource iconin the Management Console window and select Ping Server or Ping Gateway.

Delet ing a Server or Gatew ay

From the Management Console you can delete a server or gateway. To delete a resource (server orgateway), right-click on the particular resource icon in the Management Console window and selectDelete Server or Delete Gateway.

Refreshing from a server or gateway icon only updates whether or not the server or gateway is started orstopped. It does not show if the server or gateway is deleted. Perform a refresh on the computer icon toshow if a server or gateway is deleted. Refer to Refreshing the Computer .

View ing and Clearing the Trace Log

If a server, gateway, or Windows execution client is configured to produce error logs or trace files, youcan view those files through this tool. AppBuilder loads the file from the local or remote machine andallows you to view it in the system default text editor (such as NotePad).

View ing and Modifying Properties

To view or modify the properties of a server, you can right-click on the server icon and select

Server Properties. To view or modify the properties of a gateway, you can right-click on the gateway icon


25/168



and select Gateway Properties. This is covered in ConfigureaServer for Remote Communicationsand ConfigureaGateway for Remote Communications.

To view or modify the properties of a Java client, you can right-click on the Java client icon and selectCommunications Properties. This is covered in Configuring a Java Client for RemoteCommunications.

To view or modify the propert ies of a Windows client, you can right-click on the Windows client iconand select Client Properties. This is covered in Configuring a Windows Client for RemoteCommunications.

Using TCP/IP Services

Server Side

On the server side, when you either create a new TCP/IP server or modify the server ID or port numberof an existing TCP/IP server, the configurator warns you of any naming conflicts and updates theTCP/IP services file automatically.

Client Side

On the client side, i f you use single-server routing to route service requests to a TCP/IP execution server,the configurator adds an entry for the server in the TCP/IP services file.

By contrast, if you use multiple-server routing to route service requests to an execution server other thanthe default server, the configurator does not update the TCP/IP services fi le for you. Make sure to add anentry for the server in the services file.

Configuring Clients, Servers, and Gatew aysFrom the Management Console, you can configure clients, servers, and gateways for Windows (NT and2000) machines for remote communications. This topic includes:

Configuring a Java Client for Remote Communications

Configuring a Windows Client for Remote Communications

Configure aServer for Remote Communications

Configure aGateway for Remote Communications


For UNIX machines, refer to Chapter 3, Configuring Communications in UNIX .

Configuring a Java Client f or Remot e Comm unications

You can configure a Java client for RPC communication with remote servers. To configure the client,right-click on the Java client icon (Javaunder Clients) and select Communications Properties.


26/168



Figure 2-22 Java Client Communications properties dialog

The properties are described in Table 2-3.

Table 2-3 Java Client properties

Tab Property Description and Valid Values

General General parameters relating to Java client communications.

Logical Unit of Work Select either nonconversational or conversational.

Close Semantics Select commit or abort

RPC Timeout Default is 300 (seconds).

Polling Interval Default is 250 (milliseconds).

Reflection Order Default is Java Order

Tracing Parameters relating to the level of information for debugging.

Debug Level

Determines what level of debug information is available in the traceoutput log file. Choices include: TRACES_NONE - no trace information

ERRORS_ONLY - only error information ERRORS_AND_DATA - error information and data ERRORS_AND_TRACES - all the available information

Trace File Name for the trace output log file. Default is trace.out.

Routing Parameters relating to the routing of communications.

Max Routes Maximum integer number of allowed routes. Default is 2.

Number of Retries Integer number of retries. Default is 0.

Retry Interval Integer number of mil liseconds before retry. Default is 0.

Routes Key Whether to use shortname or longname. Default is shortname.

RoutesFor more general background on routing, refer to UnderstandingRouting.

Rule Name Rule name to use as a route key.

Server Name of the server

Servers Parameters relating to the communications with the server.

Server Name Name of the server

Server Type

Choose one: EJB (see EJB Server) JMS (see JMS Server) NETE (see NetEssential Server) RMI (see RMI Server)


27/168



To add a Java route, from the Routes tab, click New. In the dialog, enter the route key and server name asdescribed in Table2-3.

Figure2-23 Adding a Java route

Adding a Server for Client Com munications

To add a server, from the Servers tab, click New. In the dialog, as shown in Figure2-24,enter a servername and select the server type.

Figure 2-24 Add ing a server

This topic includes adding and configuring:

EJB Server

JMS Server

NetEssential Server

RMI Server

Custom Server


28/168



EJB Server

If you selected an EJB (Enterprise Java Bean) server and typed in a name for that server, a propertiesdialog appears, as shown in Figure2-25.

Figure 2-25 Setting EJB server properties

The properties for this server are summarized in Table2-4.

JMS Server

If you selected a JMS (Java Messaging Service) server and typed in a name for that server, a propertiesdialog appears, as shown in Figure2-26.

Table 2-4 Summary of EJB server properties

Server Property Description

INITIAL_CONTEXT_FACTORYFor WebLogic, select weblogic.jndi.WLInitialContextFactoryFor WebSphere, select com.ibm.ejs.ns.jndi.CNInitialContextFactoryFor WebSphere 4, select com.ibm.websphere.naming.WsnInitialContextFactory

PROVIDER_URLiiop://localhost:900 which is ://:For example,iiop://localhost:900 for WebSpheret3://localhost:7001 for WebLogic


29/168



Figure 2-26 Setting JMS server properties


NetEssential Server

I f you selected a NETE (NetEssential) server and typed in a name for that server, a properties dialogappears, as shown in Figure2-27.

Table 2-5 Summary of JMS server properties


JMS_INITIAL_CONTEXT_FACTORYcom.sun.jndi.fscontext.RefFSContextFactoryName of initial context factory. For use with JNDI.

JMS_PROVIDER_URL Provider URL. For use with JNDI. Example: f ile:/C:/JNDI-Directory.

MQ_QUEUE_MANAGER Name of MQSeries queue manager.

MQ_CHANNEL Name of MQSeries channel.

MQ_RECV_QUEUE Name of MQSeries receiving queue.

MQ_SEND_QUEUE Name of MQSeries sending queue.

MQ_HOST_NAME Host name of the remote machine.

MQ_PORT TCP/IP port to connect.

MQ_CODEPAGE Server code page for local conversion.

MQ_SERVERID Server identifier.

MQ_PROTOCOL

Protocol to use to connect to the server: TCPIP - TCP/IP PMTCPIP - performance marshalled TCP/IP POTCPIP - performance marshalled OpenCOBOL TCP/IP

MQ_TIMEOUT Time to wait before timing out.


30/168



Figure 2-27 Setting NetEssential server properties


RMI Server

If you selected a RMI (remote method invocation) server and typed in a name for that server, aproperties dialog appears, as shown in Figure2-28.

Table 2-6 Summary of NetEssential server properties


HOST_NAME Host name of the remote machine.

PROTOCOL

Protocol to use to connect to the server: TCPIP - TCP/IP PMTCPIP - performance marshalled TCP/IP POTCPIP - performance marshalled OpenCOBOL TCP/IPFor information on performance marshalling, refer to UnderstandingPerformance Marshalling.

PORT TCP/IP port to connect.

CODEPAGE Server code page for local conversion.

SERVERID Server identifier.


31/168



Figure 2-28 Setting RMI server properties


Custom Server

If you selected a Custom server and typed in a name for that server, a properties dialog appears, asshown in Figure2-29.

Figure2-29 Management Console

The Custom Server type can be used to define an external implementation for invoking remoteapplications. This external Java class will be invoked when a call is made to a remote rule.

Summary of CUSTOM Server Properties

CLASS = packagename.classname, This is a Java class that implements the AbfCustomTransportinterface. This class should be included in the class path.

Configuring a Window s Client for Remot e Comm unications

You can configure a Windows client for RPC communication with remote servers. To configure theclient, right-click on the Windows client icon ( Winunder Clients) and select Client Properties.

Table 2-7 Summary of RMI server properties


REGISTRY_URL://:For example,iiop://localhost:900.


32/168



Figure 2-30 Windows Client Communications properties dialog


Table 2-8 Windows Client properties


RoutingSet whether the client routes service request to a single-server ormultiple servers

Single ServerCheck if using single server configuration.Refer to Configuring for a Single Server.

Single Server Hostname host name or machine name (see Table 2-15)

Single Server Protocol tcpip (for TCP/IP) or NPIPE (for named pipes)

Single Server Code Pageselect from the list of code pages (Refer to Appendix A, Code PageSupportfor a list of supported code pages.)


Multiple Servers Check if using multiple server configuration.Refer to Configuring for Multiple Servers.

Client PerformanceSet the performance characteristics for client/server interaction.Refer to Configuring Performance Settings.

Logical unit of work Default is NONCONVERSATIONAL

Close semantics Default is COMMIT

Timeout (Sec.)Default is 300 ms. This determines how long the client, server, orgateway tries to reach the target server before timing out, in seconds.

Max number servers Default is 100.

Log FileSet the kind of information to be written to the clients error log (trace)file. Refer to Configuring Trace Log File Settings.

Log file name Default is C:\AppBuilder\trace.out.

Error level Default is ERRORS.

Log file size Default is 1M.

Backup file name Default is C:\AppBuilder\trace.bak.

ExitsSet the security exits used by the client (if any).Refer to Configuring Security Settings.


33/168



Configuring Performance Set tings

You can specify the following performance information, or accept the defaults:

Logical unit of workdetermines how AppBuilder handles pending database transactions:

Select NONCONVERSATIONAL if you want AppBuilder to commit pending databasetransactions after the service request completes and then close the server connection.

Select PSEUDOCONVERSATIONALif you want AppBuilder to commit pending databasetransactions after the service request completes but leave the server connection open.

Select CONVERSATIONALif you want AppBuilder to commit or abort pending databasetransactions when the client context closes or as specified explicitly in the code. In the formercase, the value of the Close semantics field (see below) determines whether AppBuilder commitsor aborts pending transactions. The server connection closes when the client context closes.

The logical unit of work setting is irrelevant for gateways and forwarding servers.

Table2-9shows the relationship between the logical unit of work values and their values in previous

releases.

Close semanticsdetermines how AppBuilder handles pending database transactions when theclient context closes. This field is relevant only when the logical unit of work is set toCONVERSATIONAL:

Select COMMITif you want AppBuilder to commit pending database transactions when the

client context closes

Select ABORTif you want AppBuilder to roll back pending database transactions when the clientcontext closes

Exit ID The unique identifier of the exit.

Value The current value of the exit.

Status The status (enabled or disabled) of the exit.

Route TableFor multiple-server routing. Refer to Configuring for Multiple Servers.For more general background on routing, refer to UnderstandingRouting.

Caution We strongly recommend that you do not change an agent's performance settings without f irstconsulting Customer Support.

Table 2-9 Logical unit of work values

In AppBuilder In Previous Releases

NONCONVERSATIONAL 52LOCAL

PSEUDOCONVERSATIONAL LOCAL

CONVERSATIONAL REMOTE

Table 2-8 Windows Client properties (Continued)



34/168



The close semantics setting is irrelevant for gateways and forwarding servers.

Timeoutdetermines how long the client, server, or gateway tries to reach the target server beforetiming out, in seconds. If you set the value to 0, no timeout occurs.

Maximum number of serversdetermines the maximum number of servers with which the clientcan communicate. The maximum number of servers setting is irrelevant for gateways, forwardingservers, and agents.

Configuring Security Set tings

Security configuration lets you specify the securi ty exits the client, gateway, or forwarding server uses to:

Obtain authentication information (with Authentication exit)

Obtain authorization information (with Authorization exit)

Log remote service usage (with RPC-end exit)

Require encrypt and decrypt passwords (wi th Encryption exit)

In the Exits tab (on the client or server) or the Client Exits and Server Exits tabs (on the gateway), youcan specify an exit by specifying the Value for a selected Exit ID and set, enable, disable the exit. Anexample of the interface is shown in Figure2-31.

Figure 2-31 Client Exits tab example

In the Clients Exits tab, you can specify any of the four types of exits. In the Server Security tab, you canspecify authentication and authorization exits.

Security configuration also lets you specify an authentication exit for a Windows eventing agent thattalks directly over LU6.2 to a securi ty-enabled mainframe environment. SeeIf Your Windows HostTalks to the Mainframe . By default, no security exits are invoked.

Tip To prevent a client timing out before a gateway, make sure the client has a greater timeout value than thegateway.

Note A gateway or forwarding server uses different security exits on the client and server sides.Do not specify the same security exits on each side.


35/168



On workstation hosts, security exits take the form of a DLL. For example, you might enterh:\netent40\authen.dll for the authentication exit.

If Your Windows Host Talks to t he M ainframe

If your parent machine is a security-enabled mainframe listening over LU6.2, your eventing agent mustpoint to a client-side authentication exit. The authentication exit passes the user name and password toLU6.2. There is no need to code a server-side exit.

If you configured the host for RPCs as well as eventing, enter the path name of the authentication exityou specified for the RPC client. Ignore the prompts for the other exits; these are irrelevant for aneventing agent.

Configuring Trace Log File Sett ings

You can specify the following information about the log file, or accept the defaults:

Log file namefull path name (including the drive letter) of the file to which AppBuilder writesmessages.

Error leveldetermines the kind of information that wi ll be written to the log file:

Select ERRORSif you want to log errors only.

Select ERRORS AND LENGTHSif you want to log input and output view lengths as well aserrors.

Select ERRORS AND DATAif you want to log input and output view lengths with more data, aswell as errors. Lengths are logged wi th the type of view data and number of bytes written per viewdetermined by the values entered for data dump type, data dump input size, and data dump

output size, respectively.

Select ERRORS AND TRACESif you want to log trace information for successful andunsuccessful calls as well as errors. For successful calls, it logs the time the function was called, thetime the function exited, and input and output view lengths, with the number of bytes to bewritten per view determined by the values entered for data dump input size and data dumpoutput size. For unsuccessful calls, it also logs errors and status view data. A hex dump is includedfor both successful and unsuccessful calls.

Log file sizeis the size of the log file, in bytes. Specify an integer followed by an upper-case K (forkilobytes) or M (for megabytes). When the log file exceeds this size, the information is deleted andstored in the backup log file.

Backup file nameis the full path name (including the drive letter) of the file to which AppBuilderwrites information when the size of the main log file exceeds its maximum size.

Note Errors that occur before initialization are reported in the f ile c:\dnatrace.out.

Note Select ERRORS AND TRACES only when debugging AppBuilder applications. It can degrade systemperformance and use excessive disk space.


36/168



Configure a Server for Remote Communications

You can configure an execution RPC server for use on the local host. You can configure the defaultexecution servers created during installation or create new execution servers. If the server accesses adatabase, you also have to specify the database name. To configure the server, right-click on the servericon and select Server Properties. Refer to Creating a Windows Server for information on creating aserver.

Figure 2-32 Server Communications properties dialog


Table 2-10 Server properties


Protocol The network protocol for communication with this server.

Protocol hostname Not editable; just for viewing.

Protocol Not editable; just for viewing.Server ID Not editable; just for viewing.

ServerPerformance

Select the properties related to the performance of the server.

Server type Default is FORKING. Alternate choice is BANKING.

Timeout (Sec.) Default is 600 seconds.

Services DirectoryDefault includes \nt\sys\bin and\nt\rt\SERVER

Database Set the database to use.

System DBMS Not editable; just for viewing.

Database name Enter the database name if any.

Log File Set the kind of information to be written to the servers error log(trace) file. Refer to Configuring Trace Log File Settings.

Log file name Default is C:\AppBuilder\machinename\trace.out.

Error level Default is ERRORS.

Log file size Default is 1M.

Backup file name Default is C:\AppBuilder\machinename\trace.bak.

ExitsSet the security exits used by the gateway (if any).Refer to Configuring Security Settings.


37/168



Configure a Gatew ay for Remote Communications

Gateway configuration prepares an AppBuilder server to transparently reroute client requests acrossprotocol boundaries. The default configuration does not include a gateway. You can use the procedures

in this section to create one or to configure an existing gateway. Refer to Creating a Windows Server for information on creating a gateway.

Gateways have dual personalities: they have characteristics of both server and client. To configure agateway, you specify its inboundand outboundcharacteristics:

Inboundcharacteristics configure the gateway's server-side features; how the gateway handlesrequests from remote clients

Outboundcharacteristics configure the gateway's client-side features; how the gateway directsrequests to remote servers

To configure a gateway, right-click on the gateway icon and select Gateway Properties.




Forwarding Determine forwarding characteristics.

Use forwarding Default is not used (unchecked).

Try remotely first Venue of Service Execution. If used, select one or the other.

Try locally first Venue of Service Execution. If used, select one or the other.


Single ServerHostname

host name or machine name (see Table 2-15)


Single Server CodePage

select from the list of code pages (Refer to Appendix A, CodePage Supportfor a list of supported code pages.)


Multiple ServersCheck if using multiple server configuration.Refer to Configuring for Multiple Servers.

Route TableFor multiple-server routing. Refer to Configuring for MultipleServers.For more general background on routing, refer toUnderstanding Routing.

Table 2-10 Server properties (Continued)



38/168



Figure 2-33 Gateway Communications properties dialog


Table 2-11 Gateway properties


Protocol The network protocol for communication with this gateway.

Protocol hostname Not editable; just for viewing.

Protocol Not editable; just for viewing.

Server ID Not editable; just for viewing.

ServerPerformance

Select the properties related to the performance of the server.

Server type Default is FORKING. Alternate choice is BANKING.


Services Directory Default includes \nt\sys\bin and\nt\rt\SERVER

Client Performance Set the performance characteristics for client/server interaction.

Logical unit of work Default is NONCONVERSATIONAL.

Close semantics Default is COMMIT.


Max number servers Default is 100.

Client ExitsSet the security exits used by the client (if any).Refer to Configuring Security Settings.




Server ExitsSet the security exits used by the gateway (if any).Refer to Configuring Security Settings.




Database Set the database to use.


39/168




This topic includes:

Editing the Route Table

Using Wild Cards and Prior ity

Understanding Routing Types

Configuring Routing

Editing the Route Table

The route table is a simple text file used for RPCs. The route table identifies the routes from the client orgateway to the services the client requests. To edit the route table, from the Management Console, selectthe Windows client i con (Win) and from the right-click menu, select Client Properties. The Windowsclient properties window is displayed, as shown in Figure2-34.

System DBMS Not editable; just for viewing.

Database name Enter the database name if any.

Log FileSet the kind of information to be written to the gateways error log(trace) file. Refer to Configuring Trace Log File Settings.

Log file name Default is \machinename\trace.out.

Error level

Determines what level of debug information is available in the traceoutput log file. Default is ERRORS. Choices include: ERRORS - logs only error information ERRORS_AND_DATA - logs error information and reporting

on input/output view data on the client side ERRORS_AND_LENGTH - logs error information and

input/output view lengths ERRORS_AND_TRACING - all the available information.

Log file size Default is 1M (for 1 megabyte).

Backup file nameSpecify the path and name of the file to which tracing information iswritten when the size of the Log f ile exceeds the Log file size.Default is \machinename\trace.bak.

Route TableFor multiple-server routing. Refer to Configuring for MultipleServers.For more general background on routing, refer toUnderstanding Routing.


Single ServerHostname

host name or machine name (see Table 2-15)


Single Server CodePage

select from the list of code pages (Refer to Appendix A, CodePage Supportfor a list of supported code pages.)


Multiple ServersCheck if using multiple server configuration.

Refer to Configuring for Multiple Servers.

Table 2-11 Gateway properties (Continued)



40/168



Figure 2-34 Selecting Route Table

Figure 2-35 Route Table Entry dialog

Table 2-12 Route table entry action

Button Action

NewBrings up a Route Table Entry dialog and allows you to add a new entry tothe route table. The new entry appears in the list when you close theRoute Table Entry dialog.

Edit

After selecting one of the entries in the list, you can click this button tobring up the Route Table Entry dialog with the values for this entry. Thisallows you to edit the values for this entry. The updated entry appears inthe list when you close the Route Table Entry dialog.

DeleteAfter selecting one of the entries in the list, when you click this button thatentry is removed from the list and it is gone from the route table.

Move UpAfter selecting one of the entries in the list that is not at the top, click thisbutton to move the entry up one position in the list.

Select Route Tabletab.

Select Route Tabletab.


41/168



Table 2-13 Route table entry values

Field Description

Rule nameCase-sensitive. The name of the rule to be invoked. Use the short name or the system-assignedname, the system ID, not the long name for the rule. Refer to Using Wild Cards and Priority.

Host name

Case-sensitive. The ID of the server machine as known to the protocol for the route, in 32

characters or less. For TCP/IP, the host name of the machine in the hosts file. For TCP/IP, you can obtain the host name with the Network Information Service (NIS) or the

Domain Name Server (DNS). You can obtain the Server IDwith NIS. For Named Pipes, the Machine ID or, if a requested service resides on the same machine as

the client, LOCAL. For LU6.2, the client-side Partner LU alias. For LU2, the value substituted for HOSTNAME in the LU2 logon scripta CICS region name,

for example. If HOSTNAME is not in use, any value.

Protocol

Case-sensitive. The network protocol for the route. lu2 - for LU2 lu62 - for LU6.2 NPIPE - for Named Pipes pmlu2 - for performance marshalling LU2 pmlu62 - for performance marshalling LU6.2

pmtcpip - for performance marshalling TCP/IP potcpip - for performance marshalling TCP/IP for OpenCOBOL tcpip - for TCP/IP

Server ID

Case-sensitive. An alias for an endpoint, in 32 characters or less. The ID of the execution serverto which the client routes the service request, as known to the protocol for the route, in 32characters or less: For UNIX, and Windows family servers listening over TCP/IP, the server name in the services

file. For Windows family servers listening over Named Pipes, the server pipe name. For UNIX, and Windows family servers listening over LU6.2, the server-side TP name.

For AIX autostart servers listening over LU6.2, specify the fi le name in the server-side Localtransaction program path.

For OS/400 and iSeries servers listening over LU6.2, the name of the library in which theservice resides, followed by a forward slash and the name of the command language programthat starts the server.

For mainframe CICS servers listening over LU2 or LU6.2, the server-side CICS transaction ID. For IMS servers listening over LU2, the server-side IMS transaction code. For IMS servers listening over LU6.2, the server-side TP name in the APPC/MVS TP profile.

Code page

Optional. The code page in use at the server node. If the code page specified in the route tablediffers from the code page specified in the LOCAL_ CODEPAGE entry in the NLS section of theclients dna.ini file, the system converts the data to be transmitted to the code page specified inthe route table. If you enter a hyphen (-) and the code page specified in the LOCAL_CODEPAGE variable in the NLS section of the client dna.ini differs from the code page specifiedin the LOCAL_CODEPAGE variable of the NLS section of the server dna.ini, the systemperforms code-page conversion on the server. Conversions to double-byte character sets rely onnative operating-system routines. Refer to Appendix A, Code Page Supportfor a list ofsupported code pages.

Priority

Optional. An integer greater than or equal to zero specifying the ordinality of a route. Default iszero, which specifies that a route has highest priority. A hyphen or blank is equivalent to zero. As

noted in Using Wild Cards and Priority,the keyword $ANY in the Service field lets you specifythe route to every service on a machine that has the values specified in the remaining fields ofthe route table entry. See the example in Priorities Setting Example.

Data-dependent

Check this box for data-dependent routing or to allow you to edit any of the fields below.

Static

LengthOptional. For data-dependent routing, the length in bytes of the data to be checked. Length isused only if the data are type char.


42/168



Use a hyphen (-) to specify an unused field, except as described in Using Wild Cards and Priori ty.

Understanding Route Table Format

A route table is a simple text f ile with two kind of l ines:

Route entriesbegin in column one and consist of eleven case-sensitive fields separated by whitespace. The fields include the name of the service, the machine it executes on, the protocol andchannel of the server connection, and the priority and data-dependency of the route. An optional orunused field is denoted by a hyphen (-).

Route table fields correspond to the sett ings in the communications configuration file (dna.ini).You can use dna.ini for RPC routing if you prefer, but this restricts you to specifying only a singleroute from the local host.

Comment linesbegin with a pound sign (#) in column one.

The route table for a communications client is initially empty except for commented copyrightinformation.

Initializing the Route Table

By default, an RPC client obtains routing information from the dna.ini fi le. To enable route tablerouting, you have two choices: reconfigure the client with the host configuration tool, or set thefollowing variables in the ROUTING section of the client dna.ini fi le. To edit the dna.ini fi le, select themachine icon in the Management Console and select Edit INI Properties.

Clients obtain the path to the dna.ini fi le from an environment variable named DNAINI. Make sure youset the path to the dna.ini in the client environment:

SET DNAINI=path.

Type

Optional. For data-dependent routing, the type of data at the specified offset. Can be: char (for character data) long (for a four-byte integer) short (for a two-byte integer)Int is integer and is the same as long.

Offset

Optional. For data-dependent routing, the symbolic name of the data f ield to be checked, as itappears in the control-structure array for the service request. For subfields, use a format such asthe following:

view1.view2.field1

You can specify an array index in brackets after the subview name:

view1.view2[5].field1

Array element 1 is the first position in the array. Maximum length of any element in the formatstring is 32 characters. Maximum length of the entire format string is 64 characters.For error-dependent routing, the Offset field must be set to the keyword DNAERROR.The Offset field may be set to the offset from the beginning of the data structure. Offset 0 is thefirst position in the data.

From

Optional. For data-dependent routing, the lowest value that satisfies the criteria against which thedata is checked. Double-quoted strings Smith, Chrisare supported. Maximum length is 128

characters. For error-dependent routing, the From field is the lowest error number in a range oferror numbers. To specify multiple individual error numbers, separate the numbers with a verticalbar10|11|12.

ToOptional. For data-dependent routing, the highest value that satisfies the criteria against whichthe data is checked. Double-quoted strings Smith, Chrisare supported. Maximum length is128 characters. For error-dependent routing, the To field is the highest error number in the range.

Table 2-13 Route table entry values (Continued)

Field Description


43/168



UNIX clients set this variable in their startup script. Refer to Chapter 3, Configuring Communicationsin UNIXfor more information about configuring UNIX clients.

Using Wild Cards and Priority

You can use wild cards in the route table. In place of a rule name entry of a route table, you can use thekeyword $ANY to indicate every route that matches all of the values specified in the remaining fields. Forexample, the route table entry

$ANY - - - - - AIX_1 lu62 READLU62 - 1

refers to every rule on the AIX_1 machine that l istens on the READLU62 channel over LU6.2.

$ANY allows you to implement complex routing schemes with just a few route table entriessometimesas few as one. Consider the gateway example in the Gateway Routingsection (Figure2-40): two clientscall the RDB_READ service and a gateway reroutes the request to another machine. While the exampleshows how to implement simple gateway routing, it is not realistic. More typically, multiple clientseach calling multiple serviceswould route requests to the gateway.

Rather than creating a route table with an entry for each service, you can use $ANY to reroute everyrequest with a single entry. Not only is the route table easier to create, it is easier to maintain. In fact,when new services are introduced into the system, you may not need to update the route table at all.

Figure2-36recasts the gateway example from the previous section using $ANY. A single route tableentry on the Windows NT gateway forwards requests from multiple Windows clients to the mainframeserver. The route priority determines when the $ANY route is evaluated.

Table 2-14 Settings in Routing section of dna.ini

Variable Setting for route table routing

NAME_SERVICE ROUTE_TABLE

DNA_MAX_ROUTESMaximum number of routes the system attempts for a given service request.The default is 1.

DNA_NO_OF_RETRIES Number of times the system retries an individual route. The default is 0.

DNA_RETRY_INTERVAL

Number of seconds between the failure of a route and a retry. The default is0. For each retry, the retry interval increments by a factor of two: if set to 10seconds, it increments to 20 seconds after the first retry, 40 seconds afterthe second retry, and so forth.

ROUTETBL

Full pathname of the route table. The default route table name is rtable. Thedefault location is platform-specific: On Windows, the default location is: \nt\rt\rtable On UNIX hosts, the default location is:

$HOME/nes_apps//rtable On mainframe hosts, the default location is:

.rtable


44/168



Figure 2-36 Wild card rout ing

Of course, the clients in this figure could use $ANY in their route tables, since the service requests are allrouted to the same server, namely, the Windows NT gateway:

$ANY - - - - - Win_N npipe AB_GATE IBM437 1

Priorities Setting Example

For example, the following entry refers to every service on the AIX_1 machine that listens on theREADLU62 channel over LU6.2:

$ANY - - - - - AIX_1 lu62 READLU62 - 1

Each route would have a priori ty of 1, unless the route was explicitly specified with a higher priori ty:

# try RDB_READ on AIX_1 machine first, then use $ANY

# routes to try alternate machines

RDB_READ - - - - - AIX_1 lu62 READLU62 - 0

$ANY - - - - - AIX_1 lu62 READLU62 - 2

$ANY - - - - - Win_1 t

Documents

APP BUILDER ConfiguringComm