APP BUILDER ConfiguringComm

BluePhoenix AppBuilder 2.1.0.
Configuring Communications Guide
BluePhoenix AppBuilder 2.1.0. Configuring Communications Guide April, 2003 Corporate Headquarters BluePhoenix Solutions Vlierwerf 7B 4704 SB Roosendaal The Netherlands +31 (0) 165 399 401 +31 (0) 165 396 308 fax USA Headquarters BluePhoenix Solutions USA, Inc. 8000 Regency Parkway Cary, NC 27511 United 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 names mentioned herein are for identification purposes only and are the property of, and may be trademarks of, 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 furnished under a license agreement. Neither the software nor this document may be copied or transferred by any means, electronic or mechanical, except as provided in the licensing agreement. BluePhoenix Solutions has made every effort to ensure that the information contained in this document is accurate; however, there are no representations or warranties regarding this information, including warranties of merchantability or fitness for a particular purpose. BluePhoenix Solutions assumes no responsibility for errors or omissions that may occur in this document. The information in this document is subject to change without prior notice and does not represent a commitment by BluePhoenix Solutions or its representatives.
TABLE OF CONTENTS
Table of Contents
AppBuilder 2.1.0 Configuring Communications Guide
1 2
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1 Configuring and Managing Communications in Windows . . . . . 2-1

Setting Up Windows Communications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1 Launching the Communications Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2 Understanding the Setup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2 Other Initial Communications Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5 Managing the System Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5 Launching the Service Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-6 Using the Service Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-6 Command Line Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-7 Launching the Management Console. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-8 Understanding the Console. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-9 Editing the Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-10 Viewing Product Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-10 Viewing or Clearing Audit Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-11 Managing the Computers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-11 Adding a Computer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-12 Refreshing the Computer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-12 Removing a Computer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-12 Managing Servers and Gateways . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-13 Creating a Windows Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-13 Creating a Windows Gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-14 Starting and Stopping a Server or Gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-15 Refreshing a Server or Gateway. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-16 Pinging a Server or Gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-16 Deleting a Server or Gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-16 Viewing and Clearing the Trace Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-16 Viewing and Modifying Properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-16 Using TCP/IP Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-17
Configuring Clients, Servers, and Gateways . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-17 Configuring a Java Client for Remote Communications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-17 Adding a Server for Client Communications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-19 Custom Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-23 Configuring a Windows Client for Remote Communications . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-23 Configuring Performance Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-25 Configuring Security Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-26 Configuring Trace Log File Settings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-27 Configure a Server for Remote Communications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-28 Configure a Gateway for Remote Communications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-29 Understanding Routing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-31 Editing the Route Table. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-31 Using Wild Cards and Priority . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-35 Understanding Routing Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-37 Configuring Routing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-43
Configuring Communications in UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1

Starting UNIX Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1 Creating AppBuilder User Accounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2 Starting the Configurator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2 Understanding the UNIX Configurator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-4 Configuring a UNIX Client for Remote Communications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-6 Configuring Basic Settings of Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-7 Configuring Advanced Settings of Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-10 Editing Client Communications Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-14 Creating a New UNIX Client for Remote Communications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-15 Configuring a UNIX Server for Remote Communications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-16 Configuring Basic Settings on the Server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-17 Configuring Advanced Settings on the Server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-19 Editing Server Communications Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-20 Creating a New UNIX Server for Remote Communications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-21 Configuring a UNIX Host for Messaging Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-22 Configuring a UNIX Messaging Client or Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-22 Configuring the UNIX Messaging Agent. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-23 Configuring a UNIX Host for Eventing Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-27 Configuring a UNIX Eventing Client or Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-27 Configuring 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
ii
Configuring Communications on the Mainframe . . . . . . . . . . . . . . . . . . 4-1

Starting Mainframe Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1 Viewing and Editing Runtime Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2 Performing Maintenance Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-4 Configuring LU2 Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-5 Configuring LU6.2 Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-5 Communications Manager Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-6 Configuring LU2 Terminal Emulator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-6 Understanding Performance Marshalling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-7
Configuring Communications Using MQSeries . . . . . . . . . . . . . . . . . . . . . 5-1

Understanding MQSeries RPC Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1 Meeting Prerequisites for MQSeries RPC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3 Configuring MQSeries RPC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3 Collect Setup Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3 Configure AppBuilder Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-4 Configure MQ Server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-5 Configure Mainframe MQ Series . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-6 Customize Mainframe INI File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-8 Handling Errors in MQSeries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-10
Extending Communications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1

Communication Exits in Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2 Implementing Communications Exits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2 Authentication Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-3 Authentication Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-4 Sample Java Class for Exits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-5 Custom Transport in Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-9 Security Exits in C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-14 Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-14 Authorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-16 Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-17 Setting Up Security Exits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-18 Security Exits Reference for C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-19 AuthentLibMain. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-20 AuthorLibMain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-21 EncryptLibMain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-22 SrvAuthentLibMain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-22 SrvAuthorLibMain. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-23 RpcEndLibMain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-24 Open Data Encryption Mechanism . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-24 dna_BufInit. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-25 dna_BufEncode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-26 dna_BufDecode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-27 dna_BufClose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-27
Table of Contents
iii
Directory Services Exits in C. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-28 dna_ExtRoutes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-30 dna_ExtSubcells . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-32 dna_ExtTriggers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-33 dna_ExtEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-34 Database Exits in C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-35 sdbi_Connect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-36 sdbi_StartTxn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-36 sdbi_CommitTxn. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-37 sdbi_AbortTxn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-37 sdbi_Disconnect. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-38 Sample Database Exit Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-38 Customized Data Types in C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-40 Using Custom Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-41 Identifying the Data Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-41 Writing the Marshalling Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-42 Compiling and Linking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-43 Using the Visual C++ Compiler. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-44 Example Directory Services Exits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-44 Example Database Exits. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-45
Code Page Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-1

Supported Code Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-1 Supported Code Page Conversions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-3
Mainframe Logon Script
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-1
Logon Script Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-2
Index
iv
CHAPTER
INTRODUCTION
AppBuilder is an advanced development environment that uses internal communications for connecting the various tools and services for multi-platform deployment. The various platforms and protocols that can 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 ability to interface with the communications facilities is covered in Chapter 6, Extending Communications. For information on warning messages or error messages related to communications, refer to the Messages Reference Guide.
1-1
1-2
Introduction
CHAPTER
CONFIGURING AND MANAGING COMMUNICATIONS IN WINDOWS
Use the Management Console to manage and configure aspects of AppBuilder communications on a local or remote computer. The Management Console enables you to: configure Java and Windows client communications for application execution create multiple 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 file (hps.ini) easily modify other AppBuilder-associated configuration (.ini) files through a dedicated ini editor
Note Note
Refer to:
Make sure to shut down all AppBuilder communications clients and servers before configuring the host.
As with any AppBuilder communications application, the Management Console only works between machines where the code page mapping exists.
Setting Up Windows Communications Managing the System Service Managing the Computers Managing Servers and Gateways Configuring Clients, Servers, and Gateways Understanding Routing
Setting Up Windows Communications

Use the AppBuilder Communications Setup program to configure your system and allow communication between the various tools and services of the AppBuilder system. This includes: Launching the Communications Setup Understanding the Setup Other Initial Communications Configuration
2-1
Launching the Communications Setup

From the Start menu, select Start > Programs > AppBuilder > Communications > Communications Setup.
Figure 2-1 Communications menu Select Setup
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 Figure 2-2. Select Limited for selecting only the protocol or database settings. Select Complete to create a new base configuration and select all the options in the communications setup.
Figure 2-2 Communications Setup - Scope screen
If the AppBuilder Communications service is currently running when you attempt to run the setup, the system 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)
2-2 Configuring and Managing Communications in Windows
Select Protocol Select one or more protocols from the check boxes on the Protocol screen. Refer to Figure 2-7. Selecting a protocol enables that protocol for AppBuilder communications.
Figure 2-4 Communications Setup - Protocol screen
Select Code page Select the code page from the drop-down list on the Code page screen. Refer to Figure 2-5. The system code page is used by communications to specify the local code page for character encoding. The appropriate tables are enabled for the selected code page.
Figure 2-5 Communications Setup - Code page screen
2-3
Select Eventing Parent Enter the name of the eventing parent (host) in the Hostname field on the Eventing Parent screen. Refer to Figure 2-6. This information is only required if global eventing is used. If connecting to a UNIX workgroup (Freeway) repository, global eventing must be configured.
Figure 2-6 Communications Setup - Eventing Parent screen
Select Database Management System (DBMS) Select a database management system (DBMS) from the drop-down list on the Database screen. Refer to Figure 2-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
2-4
Configuring and Managing Communications in Windows
Managing the System Service
Other Initial Communications Configuration

Other ways to configure communications involve editing the configuration files (.ini) on the workstation. From the Management Console, you can select the icon for the client machine and right-click on the Java icon to edit the appbuilder.ini file with values relating to Java, as shown in Figure 2-8. Refer to Launching the Management Console for information on logging in to the Management Console.
Figure 2-8 Editing appbuilder.ini
Edit the appbuilder.ini file on the workstation to change some of the configuration of communications in AppBuilder. For example, the ABORT_ON_COMM_ERROR value in the NC section of appbuilder.ini allows you to set whether to abort (terminate) AppBuilder when a communication error occurs. (This example is shown in Figure 2-8.) In the thin-client environment, the COMM_ERROR_RULE is run as a detached rule like any other thinclient rule. So, if you are using ABORT_ON_COMM_ERROR, then you cannot have USE_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 and stopping of the various AppBuilder communications servers, gateways, and agents. The service is not a Windows service; it is just a simple process. When you stop the AppBuilder service, you stop any configured servers and gateways as well as the service. The control of the AppBuilder system service is handled by the Service Control of AppBuilder Communications. The management of communications and services is handled by a system administrator through the Management Console. Use the AppBuilder Communications Service Control to start and stop the AppBuilder system service and to check on the status of that service. The AppBuilder system service (or AppBuilder service, for short) is an executable that runs in the background. It manages the starting and stopping of the various AppBuilder communications servers. This topic includes:
2-5
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 critical communications tasks: Receives remote preparation results Enables remote configuration Used in Distributed 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 Control

From the Start menu, select Start > Programs > AppBuilder > Communications > Service Control.
Figure 2-9 Communications menu
Select Service Control
This launches the Service Control and automatically starts the AppBuilder service if it is not already running. 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
Icon for Service Control
Using the Service Control

Single-click (right or left mouse button) on the Service Control icon and the Service Control menu appears, as shown in Figure 2-11.
2-6
Figure 2-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; it does not stop the service. (The service is not interrupted.) To Show the icon again, you can go through the menu options again (Start > Programs > AppBuilder > Communications), choose Service Control, and the icon appears again. This Hide option only hides this icon on the task bar for that session. It does not 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 Service or Start AppBuilder System Service from the Service Control menu.
Launching Management Console

From the Service Control menu you can launch the AppBuilder Management Console. Refer to Launching the Management Console.
Command Line Control

In the same way that you can use the Service Control to start or stop the AppBuilder service, you can perform these functions from a command line interface. Service Control Command To control the AppBuilder service, run this command (with any of three parameters) from a command prompt: abservice -check abservice -start abservice -stop The first checks (or confirms) that the AppBuilder service is running. The second starts the service if it is stopped. The third stops the service if it is started. Product Information Command To see the product version information, run the product information command from a command prompt: abprdinf
2-7
When you run this command from the directory where the system configuration file (hps.ini) is installed (or at least have it defined in the path) you can look at product version information. This command displays the product version information on the screen and saves the same information to a file that you can open with a text editor. The file that is created is machinenameinfo.ini where machinename is the name of the machine from which you the command is run. For example, if the machine name is jsmith, the file created would be jsmithinfo.ini. The file is saved in the AppBuilder installation directory. An example log file (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 Version=AppBuilder20_3 [PRODUCT.Freeway Repository] Installed=3-24-2002 Version=AppBuilder20_3 [PRODUCT.Personal Repository] Installed=3-24-2002 Version=AppBuilder20_3 [PRODUCT.TurboCycler SDK] Installed=3-24-2002 Version=AppBuilder20_3 [EFX.D20204n] Installed=4-13-2002
Launching the Management Console

From the Start menu, select Start > Programs > AppBuilder > Communications > Management Console. Or from the Service Control, select Launch AppBuilder Management Console.
Figure 2-12 Communications menu
Select Management Console
The login dialog is displayed as in Figure 2-13 so 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 account on a workstation is enabled with no password, then you are not prompted for security when you load
2-8
that computer into the Management Console. The user ID and password are authenticated against the operating system. The status of the configuration of communications is shown briefly, as in Figure 2-14.
Figure 2-13 Login dialog
conner05 mconner
Figure 2-14
Launching dialog
With this, you are logging in to the local computer configuration. This is important to understand because if you press Cancel, the Management Console still starts, but the local machine is disabled until you issue a refresh, at which point you are prompted to login again.
Understanding the Console

The Management Console window shows a graphical representation of the communications resources defined by the user on Windows (NT or 2000) machines. From this window you can select menu options, click on resource icons and manage the resources associated with those icons. Figure 2-15 illustrates a typical Management Console window.
Figure 2-15 Management Console window example
Menus mach_fir
Graphical Display mach_second Resource icons
2-9
Viewing Product Information
From the console, you can select a machine (client, server, or gateway) by clicking on the icon for that machine and right-click to select the properties. In this way you can modify the resources. You can add machines or resources by selecting the icon for the type of resource and selecting the add option from the pop-up menu. You can delete a resource by selecting the icon for that resource and pressing the Delete 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), AppBuilder issues a message and then leaves the computer in the tree with an 'inactive' icon. The menu selections at this point are also greyed out for that machine and you can only remove or refresh the computer. If a refresh finds the machine active, everything returns to normal: the icon is displayed as active and the menu items return.
Editing the Configuration File

From the Management Console, you can modify the configuration settings in the configuration (.ini) file for that resource. To edit the configuration file, select the resource icon of the resource to configure and choose Edit INI File from the menu. You can modify 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
Each section of the file is available on a tab.
Each variable of that section is available in this list.
You can modify the value and click Set.
If there is help available for that value, it is displayed here.
Viewing Product Information

You can view information about which AppBuilder products (and which versions) are installed on a given 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 the Installation Guide for Windows.
2-10
Viewing or Clearing Audit Information
Viewing or Clearing Audit Information

AppBuilder keeps track of the actions taken when starting or stopping services or modifying configuration (.ini) files. This information is kept in a file, called an audit file. To view the file, right-click on a computer and select View Audit Information. AppBuilder loads the file from the local machine or a remote machine and allows you to view it in the system default text editor (such as Notepad). See Figure 2-17 for a sample audit file.
Figure 2-17 Sample audit file
The audit information contains columns of information. date and time stamp user ID action, whether executed, modified, created or deleted name of the file edited or service started or stopped To clear the file and erase all entries, right-click on a Computer object icon and select Clear Audit Information. 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
Managing the Computers

From the Management Console you can perform many administrative functions with the Computer objects, the highest level in the hierarchy. These include: Adding a Computer Refreshing the Computer Removing a Computer Viewing or Clearing Audit Information Viewing Product Information Editing the Configuration File
2-11
Managing the Computers
Adding a Computer
You can add a remote computer to the management console by selecting the Computers icon in the console window, right-clicking and from the pop-up menu, selecting Add Computer. The Add Computer dialog appears as shown in Figure 2-18. Enter the host name (the machine name) and the server identifier, which defaults to ne20. Click OK when done.
Figure 2-18 Add Computer dialog
When a new computer is added the user is prompted for a user name and password that is valid for the target machine.
Refreshing the Computer

To see the latest updates to the hierarchy of machines and services, you can update the Management Console display. Right-click on a computer icon in the hierarchy and select Refresh Computer. This updates the display and shows any computers that have been added or removed. For a list of information about 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 any computer other than your own workstation from the display. Right-click on a computer icon in the hierarchy and select Remove Computer. You cannot remove your own workstation, from which this Management Console is running, from the console display.
2-12
Managing Servers and Gateways

From the Management Console you can perform many administrative functions with the servers and gateways. 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 the Servers icon in the console window, right-clicking and from the pop-up menu, selecting New Server. The dialogs appear as shown in Figure 2-19. Fill out the information in each dialog. Click Next to advance to the next screen. Click Finish when done. The system queries the TCP/IP services file for the server 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 Gateways for more information.
Figure 2-19 Creating a server - Protocol and subsequent dialogs
2-13
Table 2-1
Properties for creating a server Description This defaults to the machine name as is not editable by the user. This is user-selectable as either tcpip (for TCP/IP) or NPIPE (for Named Pipes). This is a user-defined, unique identifier for this server. This defaults to the database management system (DBMS) specified when you installed AppBuilder, configured communications, and selected a DBMS. This is not editable by the user. This is a user-defined, unique identifier for the database. This is a user-defined, unique port number for this server.
Dialog field Protocol Host name Protocol Server ID System DBMS Database name Port
The console then displays the created server as a new icon under the Servers icon. The name shown next to the icon appends either an np (for named pipes) or tcp (for TCP/IP) depending on the protocol you selected. When a new server is created, AppBuilder checks the product information to see if it is a departmental server. AppBuilder grays out the Edit HPS.INI option because an HPS.INI file is not needed on a departmental server.
Creating a Windows Gateway

From the Management Console you can create a gateway by selecting the Gateways icon in the console window, right-clicking and from the pop-up menu, selecting New Gateway. The Protocol dialog appears as shown in Figure 2-20. Fill out the information about the protocol. Click OK when done. The system queries the TCP/IP services file for the gateway server ID. If it does not already exist, you must enter a port number and add it to the services file. Enter the port number and click OK. Refer to Managing Servers and Gateways for more information.
Figure 2-20 Creating a gateway - Protocol and subsequent dialogs
2-14
Table 2-2
Properties for creating a gateway Description This defaults to the machine name and is not editable by the user. Select the protocol that this gateway listens on for incoming application service requests. This is user-selectable as either tcpip (for TCP/IP) or NPIPE (for Named Pipes). This is the unique identifier for the TCP/IP port or Named Pipes pipe name (depending on what protocol was selected) of the gateway. Refer to Configuring for a Single Server. host name or machine name (see Table 2-15) tcpip (for TCP/IP) or NPIPE (for named pipes) select from the list of code pages (Refer to Appendix A, Code Page Support for a list of supported code pages.) server ID Refer to Configuring for Multiple Servers. Refer to Editing the Route Table. This is a user-defined, unique port number for this server.
Dialog field Protocol Host name Protocol
Server ID Single Server Single Server Host Name Single Server Protocol Single Server Code Page Single Server ID Multiple Servers Route Table Port
The console then displays the created gateway as a new icon under the Gateways icon.
Starting and Stopping a Server or Gateway

From the Management Console you can start or stop an individual server or gateway. When you start a server or gateway it becomes active and the icon changes to green in the console window. When a server or gateway is stopped it becomes inactive and the icon changes to red in the console window. This is summarized in Figure 2-21.
Figure 2-21 Icon colors
Active (started) server has green icon. Inactive (stopped) server has red icon.
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 select Start Gateway. To stop a gateway, right-click on the particular gateway icon in the console window and select Stop Gateway.
2-15
Refreshing a Server or Gateway

From the Management Console you can refresh the display of a resource (server or gateway). The icons in the console window show whether a server or gateway was stopped or started as shown in Figure 2-21. But this information is not updated dynamically. To view the latest status of a Server or Gateway, refresh the resource. To refresh the resource (server or gateway), right-click on the particular resource icon in the Management Console window and select Refresh Server or Refresh Gateway. Refreshing the server or gateway icon only updates whether or not the server or gateway is started or stopped. It does not show if the server or gateway has been deleted. Perform a refresh on the computer icon to show if a server or gateway has been deleted. Refer to Refreshing the Computer.
Pinging a Server or Gateway

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 icon in the Management Console window and select Ping Server or Ping Gateway.
Deleting a Server or Gateway

From the Management Console you can delete a server or gateway. To delete a resource (server or gateway), right-click on the particular resource icon in the Management Console window and select Delete Server or Delete Gateway. Refreshing from a server or gateway icon only updates whether or not the server or gateway is started or stopped. It does not show if the server or gateway is deleted. Perform a refresh on the computer icon to show if a server or gateway is deleted. Refer to Refreshing the Computer.
Viewing and Clearing the Trace Log

If a server, gateway, or Windows execution client is configured to produce error logs or trace files, you can view those files through this tool. AppBuilder loads the file from the local or remote machine and allows you to view it in the system default text editor (such as NotePad).
Viewing 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
2-16
Configuring Clients, Servers, and Gateways
and select Gateway Properties. This is covered in Configure a Server for Remote Communications and Configure a Gateway for Remote Communications. To view or modify the properties of a Java client, you can right-click on the Java client icon and select Communications Properties. This is covered in Configuring a Java Client for Remote Communications. To view or modify the properties of a Windows client, you can right-click on the Windows client icon and select Client Properties. This is covered in Configuring a Windows Client for Remote Communications.
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 number of an existing TCP/IP server, the configurator warns you of any naming conflicts and updates the TCP/IP services file automatically. Client Side On the client side, if 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 than the default server, the configurator does not update the TCP/IP services file for you. Make sure to add an entry for the server in the services file.

From the Management Console, you can configure clients, servers, and gateways for Windows (NT and 2000) machines for remote communications. This topic includes: Configuring a Java Client for Remote Communications Configuring a Windows Client for Remote Communications Configure a Server for Remote Communications Configure a Gateway for Remote Communications Understanding Routing For UNIX machines, refer to Chapter 3, Configuring Communications in UNIX.
Configuring a Java Client for Remote Communications

You can configure a Java client for RPC communication with remote servers. To configure the client, right-click on the Java client icon ( Java under Clients) and select Communications Properties.
2-17
Figure 2-22
Java Client Communications properties dialog
The properties are described in Table 2-3.

Table 2-3 Tab General Logical Unit of Work Close Semantics RPC Timeout Polling Interval Reflection Order Tracing Java Client properties Property Description and Valid Values General parameters relating to Java client communications. Select either nonconversational or conversational. Select commit or abort Default is 300 (seconds). Default is 250 (milliseconds). Default is Java Order Parameters relating to the level of information for debugging. Determines what level of debug information is available in the trace output 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 Name for the trace output log file. Default is trace.out. Parameters relating to the routing of communications. Max Routes Number of Retries Retry Interval Routes Key Routes Rule Name Server Servers Server Name Maximum integer number of allowed routes. Default is 2. Integer number of retries. Default is 0. Integer number of milliseconds before retry. Default is 0. Whether to use shortname or longname. Default is shortname. For more general background on routing, refer to Understanding Routing. Rule name to use as a route key. Name of the server Parameters relating to the communications with the server. Name of the server Choose one: EJB (see EJB Server) JMS (see JMS Server) NETE (see NetEssential Server) RMI (see RMI Server)
Debug Level
Trace File Routing
Server Type
2-18
To add a Java route, from the Routes tab, click New. In the dialog, enter the route key and server name as described in Table 2-3.
Figure 2-23 Adding a Java route
Adding a Server for Client Communications

To add a server, from the Servers tab, click New. In the dialog, as shown in Figure 2-24, enter a server name and select the server type.
Figure 2-24 Adding a server
This topic includes adding and configuring: EJB Server JMS Server NetEssential Server RMI Server Custom Server
2-19
EJB Server
If you selected an EJB (Enterprise Java Bean) server and typed in a name for that server, a properties dialog appears, as shown in Figure 2-25.
Figure 2-25 Setting EJB server properties
The properties for this server are summarized in Table 2-4.

Table 2-4 Summary of EJB server properties Description For WebLogic, select weblogic.jndi.WLInitialContextFactory For WebSphere, select com.ibm.ejs.ns.jndi.CNInitialContextFactory For WebSphere 4, select com.ibm.websphere.naming.WsnInitialContextFactory iiop://localhost:900 which is <protocol>://<host_name>:<portnumber> For example, iiop://localhost:900 for WebSphere t3://localhost:7001 for WebLogic
Server Property INITIAL_CONTEXT_FACTORY
PROVIDER_URL
JMS Server
If you selected a JMS (Java Messaging Service) server and typed in a name for that server, a properties dialog appears, as shown in Figure 2-26.
2-20
Figure 2-26
Setting JMS server properties

Table 2-5 Summary of JMS server properties Description com.sun.jndi.fscontext.RefFSContextFactory Name of initial context factory. For use with JNDI. Provider URL. For use with JNDI. Example: file:/C:/JNDI-Directory. Name of MQSeries queue manager. Name of MQSeries channel. Name of MQSeries receiving queue. Name of MQSeries sending queue. Host name of the remote machine. TCP/IP port to connect. Server code page for local conversion. Server identifier. Protocol to use to connect to the server: TCPIP - TCP/IP PMTCPIP - performance marshalled TCP/IP POTCPIP - performance marshalled OpenCOBOL TCP/IP Time to wait before timing out.
Server Property JMS_INITIAL_CONTEXT_FACTORY JMS_PROVIDER_URL MQ_QUEUE_MANAGER MQ_CHANNEL MQ_RECV_QUEUE MQ_SEND_QUEUE MQ_HOST_NAME MQ_PORT MQ_CODEPAGE MQ_SERVERID
MQ_PROTOCOL
MQ_TIMEOUT
NetEssential Server
If you selected a NETE (NetEssential) server and typed in a name for that server, a properties dialog appears, as shown in Figure 2-27.
2-21
Figure 2-27
Setting NetEssential server properties

Table 2-6 Summary of NetEssential server properties Description Host name of the remote machine. Protocol to use to connect to the server: TCPIP - TCP/IP PMTCPIP - performance marshalled TCP/IP POTCPIP - performance marshalled OpenCOBOL TCP/IP For information on performance marshalling, refer to Understanding Performance Marshalling. TCP/IP port to connect. Server code page for local conversion. Server identifier.
Server Property HOST_NAME
PROTOCOL
PORT CODEPAGE SERVERID
RMI Server
If you selected a RMI (remote method invocation) server and typed in a name for that server, a properties dialog appears, as shown in Figure 2-28.
2-22
Figure 2-28
Setting RMI server properties

Table 2-7 Summary of RMI server properties Description <protocol>://<host_name>:<portnumber> For example, iiop://localhost:900.
Server Property REGISTRY_URL
Custom Server
If you selected a Custom server and typed in a name for that server, a properties dialog appears, as shown in Figure 2-29.
Figure 2-29 Management Console
The Custom Server type can be used to define an external implementation for invoking remote applications. 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 AbfCustomTransport interface. This class should be included in the class path.
Configuring a Windows Client for Remote Communications

You can configure a Windows client for RPC communication with remote servers. To configure the client, right-click on the Windows client icon (Win under Clients) and select Client Properties.
2-23
Figure 2-30
Windows Client Communications properties dialog

Table 2-8 Tab Routing Single Server Single Server Hostname Single Server Protocol Single Server Code Page Single Server ID Multiple Servers Client Performance Logical unit of work Close semantics Timeout (Sec.) Max number servers Log File Log file name Error level Log file size Backup file name Exits Windows Client properties Property Description and Valid Values Set whether the client routes service request to a single-server or multiple servers Check if using single server configuration. Refer to Configuring for a Single Server. host name or machine name (see Table 2-15) tcpip (for TCP/IP) or NPIPE (for named pipes) select from the list of code pages (Refer to Appendix A, Code Page Support for a list of supported code pages.) server ID Check if using multiple server configuration. Refer to Configuring for Multiple Servers. Set the performance characteristics for client/server interaction. Refer to Configuring Performance Settings. Default is NONCONVERSATIONAL Default is COMMIT Default is 300 ms. This determines how long the client, server, or gateway tries to reach the target server before timing out, in seconds. Default is 100. Set the kind of information to be written to the clients error log (trace) file. Refer to Configuring Trace Log File Settings. Default is C:\AppBuilder\trace.out. Default is ERRORS. Default is 1M. Default is C:\AppBuilder\trace.bak. Set the security exits used by the client (if any). Refer to Configuring Security Settings.
2-24
Table 2-8 Tab
Windows Client properties (Continued) Property Exit ID Value Status Description and Valid Values The unique identifier of the exit. The current value of the exit. The status (enabled or disabled) of the exit. For multiple-server routing. Refer to Configuring for Multiple Servers. For more general background on routing, refer to Understanding Routing.
Route Table
Configuring Performance Settings

Caution
We strongly recommend that you do not change an agent's performance settings without first consulting Customer Support.
You can specify the following performance information, or accept the defaults: Logical unit of work determines how AppBuilder handles pending database transactions: Select NONCONVERSATIONAL if you want AppBuilder to commit pending database transactions after the service request completes and then close the server connection. Select PSEUDOCONVERSATIONAL if you want AppBuilder to commit pending database transactions after the service request completes but leave the server connection open. Select CONVERSATIONAL if you want AppBuilder to commit or abort pending database transactions when the client context closes or as specified explicitly in the code. In the former case, the value of the Close semantics field (see below) determines whether AppBuilder commits or 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. Table 2-9 shows the relationship between the logical unit of work values and their values in previous releases.
Table 2-9 Logical unit of work values In Previous Releases 52LOCAL LOCAL REMOTE
In AppBuilder NONCONVERSATIONAL PSEUDOCONVERSATIONAL CONVERSATIONAL
Close semantics determines how AppBuilder handles pending database transactions when the client context closes. This field is relevant only when the logical unit of work is set to CONVERSATIONAL: Select COMMIT if you want AppBuilder to commit pending database transactions when the client context closes Select ABORT if you want AppBuilder to roll back pending database transactions when the client context closes
2-25
The close semantics setting is irrelevant for gateways and forwarding servers. Timeout determines how long the client, server, or gateway tries to reach the target server before timing out, in seconds. If you set the value to 0, no timeout occurs.
Tip
To prevent a client timing out before a gateway, make sure the client has a greater timeout value than the gateway.
Maximum number of servers determines the maximum number of servers with which the client can communicate. The maximum number of servers setting is irrelevant for gateways, forwarding servers, and agents.
Configuring Security Settings

Security configuration lets you specify the security 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 (with Encryption exit) In the Exits tab (on the client or server) or the Client Exits and Server Exits tabs (on the gateway), you can specify an exit by specifying the Value for a selected Exit ID and set, enable, disable the exit. An example of the interface is shown in Figure 2-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 can specify authentication and authorization exits.
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.
Security configuration also lets you specify an authentication exit for a Windows eventing agent that talks directly over LU6.2 to a security-enabled mainframe environment. See If Your Windows Host Talks to the Mainframe. By default, no security exits are invoked.
2-26
On workstation hosts, security exits take the form of a DLL. For example, you might enter h:\netent40\authen.dll for the authentication exit.
If Your Windows Host Talks to the Mainframe

If your parent machine is a security-enabled mainframe listening over LU6.2, your eventing agent must point to a client-side authentication exit. The authentication exit passes the user name and password to LU6.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 exit you specified for the RPC client. Ignore the prompts for the other exits; these are irrelevant for an eventing agent.
Configuring Trace Log File Settings

You can specify the following information about the log file, or accept the defaults: Log file name full path name (including the drive letter) of the file to which AppBuilder writes messages.
Note
Errors that occur before initialization are reported in the file c:\dnatrace.out.
Error level determines the kind of information that will be written to the log file: Select ERRORS if you want to log errors only. Select ERRORS AND LENGTHS if you want to log input and output view lengths as well as errors. Select ERRORS AND DATA if you want to log input and output view lengths with more data, as well as errors. Lengths are logged with the type of view data and number of bytes written per view determined by the values entered for data dump type, data dump input size, and data dump output size, respectively. Select ERRORS AND TRACES if you want to log trace information for successful and unsuccessful calls as well as errors. For successful calls, it logs the time the function was called, the time the function exited, and input and output view lengths, with the number of bytes to be written per view determined by the values entered for data dump input size and data dump output size. For unsuccessful calls, it also logs errors and status view data. A hex dump is included for both successful and unsuccessful calls.
Note
Select ERRORS AND TRACES only when debugging AppBuilder applications. It can degrade system performance and use excessive disk space.
Log file size is the size of the log file, in bytes. Specify an integer followed by an upper-case K (for kilobytes) or M (for megabytes). When the log file exceeds this size, the information is deleted and stored in the backup log file. Backup file name is the full path name (including the drive letter) of the file to which AppBuilder writes information when the size of the main log file exceeds its maximum size.
2-27
Configure a Server for Remote Communications

You can configure an execution RPC server for use on the local host. You can configure the default execution servers created during installation or create new execution servers. If the server accesses a database, you also have to specify the database name. To configure the server, right-click on the server icon and select Server Properties. Refer to Creating a Windows Server for information on creating a server.
Figure 2-32 Server Communications properties dialog

Table 2-10 Server properties Tab Protocol Protocol hostname Protocol Server ID Server Performance Server type Timeout (Sec.) Services Directory Database System DBMS Database name Log File Log file name Error level Log file size Backup file name Exits Property Description and Valid Values The network protocol for communication with this server. Not editable; just for viewing. Not editable; just for viewing. Not editable; just for viewing. Select the properties related to the performance of the server. Default is FORKING. Alternate choice is BANKING. Default is 600 seconds. Default includes <AppBuilder>\nt\sys\bin and <AppBuilder>\nt\rt\SERVER Set the database to use. Not editable; just for viewing. Enter the database name if any. Set the kind of information to be written to the servers error log (trace) file. Refer to Configuring Trace Log File Settings. Default is C:\AppBuilder\machinename\trace.out. Default is ERRORS. Default is 1M. Default is C:\AppBuilder\machinename\trace.bak. Set the security exits used by the gateway (if any). Refer to Configuring Security Settings.
2-28
Table 2-10 Server properties (Continued) Tab Property Exit ID Value Status Forwarding Use forwarding Try remotely first Try locally first Routing Single Server Hostname Single Server Protocol Single Server Code Page Single Server ID Multiple Servers Description and Valid Values The unique identifier of the exit. The current value of the exit. The status (enabled or disabled) of the exit. Determine forwarding characteristics. Default is not used (unchecked). Venue of Service Execution. If used, select one or the other. Venue of Service Execution. If used, select one or the other. Set whether the client routes service request to a single-server or multiple servers host name or machine name (see Table 2-15) tcpip (for TCP/IP) or NPIPE (for named pipes) select from the list of code pages (Refer to Appendix A, Code Page Support for a list of supported code pages.) server ID Check if using multiple server configuration. Refer to Configuring for Multiple Servers. For multiple-server routing. Refer to Configuring for Multiple Servers. For more general background on routing, refer to Understanding Routing.
Route Table
Configure a Gateway for Remote Communications

Gateway configuration prepares an AppBuilder server to transparently reroute client requests across protocol 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 a gateway, you specify its inbound and outbound characteristics: Inbound characteristics configure the gateway's server-side features; how the gateway handles requests from remote clients Outbound characteristics configure the gateway's client-side features; how the gateway directs requests to remote servers To configure a gateway, right-click on the gateway icon and select Gateway Properties.
2-29
Figure 2-33
Gateway Communications properties dialog

Table 2-11 Gateway properties Tab Protocol Protocol hostname Protocol Server ID Server Performance Server type Timeout (Sec.) Services Directory Client Performance Logical unit of work Close semantics Timeout (Sec.) Max number servers Client Exits Exit ID Value Status Server Exits Exit ID Value Status Database Property Description and Valid Values The network protocol for communication with this gateway. Not editable; just for viewing. Not editable; just for viewing. Not editable; just for viewing. Select the properties related to the performance of the server. Default is FORKING. Alternate choice is BANKING. Default is 600 seconds. Default includes <AppBuilder>\nt\sys\bin and <AppBuilder>\nt\rt\SERVER Set the performance characteristics for client/server interaction. Default is NONCONVERSATIONAL. Default is COMMIT. Default is 300 seconds. Default is 100. Set the security exits used by the client (if any). Refer to Configuring Security Settings. The unique identifier of the exit. The current value of the exit. The status (enabled or disabled) of the exit. Set the security exits used by the gateway (if any). Refer to Configuring Security Settings. The unique identifier of the exit. The current value of the exit. The status (enabled or disabled) of the exit. Set the database to use.
2-30
Understanding Routing
Table 2-11 Gateway properties (Continued) Tab Property System DBMS Database name Log File Log file name Description and Valid Values Not editable; just for viewing. Enter the database name if any. Set the kind of information to be written to the gateways error log (trace) file. Refer to Configuring Trace Log File Settings. Default is <AppBuilder>\machinename\trace.out. Determines what level of debug information is available in the trace output 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. Default is 1M (for 1 megabyte). Specify the path and name of the file to which tracing information is written when the size of the Log file exceeds the Log file size. Default is <AppBuilder>\machinename\trace.bak. For multiple-server routing. Refer to Configuring for Multiple Servers. For more general background on routing, refer to Understanding Routing. Set whether the client routes service request to a single-server or multiple servers Single Server Hostname Single Server Protocol Single Server Code Page Single Server ID Multiple Servers host name or machine name (see Table 2-15) tcpip (for TCP/IP) or NPIPE (for named pipes) select from the list of code pages (Refer to Appendix A, Code Page Support for a list of supported code pages.) server ID Check if using multiple server configuration. Refer to Configuring for Multiple Servers.
Error level
Log file size Backup file name
Route Table
Routing
This topic includes: Editing the Route Table Using Wild Cards and Priority 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 or gateway to the services the client requests. To edit the route table, from the Management Console, select the Windows client icon (Win) and from the right-click menu, select Client Properties. The Windows client properties window is displayed, as shown in Figure 2-34.
2-31
Figure 2-34
Selecting Route Table
Select Route Table tab.
Select Route Table tab.
Table 2-12 Route table entry action Button New Action Brings up a Route Table Entry dialog and allows you to add a new entry to the route table. The new entry appears in the list when you close the Route Table Entry dialog. After selecting one of the entries in the list, you can click this button to bring up the Route Table Entry dialog with the values for this entry. This allows you to edit the values for this entry. The updated entry appears in the list when you close the Route Table Entry dialog. After selecting one of the entries in the list, when you click this button that entry is removed from the list and it is gone from the route table. After selecting one of the entries in the list that is not at the top, click this button to move the entry up one position in the list. Route Table Entry dialog
Edit
Delete Move Up Figure 2-35
2-32
Table 2-13 Route table entry values Field Rule name Description Case-sensitive. The name of the rule to be invoked. Use the short name or the system-assigned name, the system ID, not the long name for the rule. Refer to Using Wild Cards and Priority. 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 ID with 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. 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 Case-sensitive. An alias for an endpoint, in 32 characters or less. The ID of the execution server to which the client routes the service request, as known to the protocol for the route, in 32 characters 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 file name in the server-side Local transaction program path. For OS/400 and iSeries servers listening over LU6.2, the name of the library in which the service resides, followed by a forward slash and the name of the command language program that 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. Optional. The code page in use at the server node. If the code page specified in the route table differs from the code page specified in the LOCAL_ CODEPAGE entry in the NLS section of the clients dna.ini file, the system converts the data to be transmitted to the code page specified in the 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 specified in the LOCAL_CODEPAGE variable of the NLS section of the server dna.ini, the system performs code-page conversion on the server. Conversions to double-byte character sets rely on native operating-system routines. Refer to Appendix A, Code Page Support for a list of supported code pages. Optional. An integer greater than or equal to zero specifying the ordinality of a route. Default is zero, 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 specify the route to every service on a machine that has the values specified in the remaining fields of the route table entry. See the example in Priorities Setting Example. Check this box for data-dependent routing or to allow you to edit any of the fields below.
Host name
Protocol
Server ID
Code page
Priority
Datadependent Static Length
Optional. For data-dependent routing, the length in bytes of the data to be checked. Length is used only if the data are type char.
2-33
Table 2-13 Route table entry values (Continued) Field Description 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. Optional. For data-dependent routing, the symbolic name of the data field to be checked, as it appears in the control-structure array for the service request. For subfields, use a format such as the following:
Type
view1.view2.field1
You can specify an array index in brackets after the subview name: Offset
view1.view2[5].field1
Array element 1 is the first position in the array. Maximum length of any element in the format string 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 the first position in the data. Optional. For data-dependent routing, the lowest value that satisfies the criteria against which the data 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 of error numbers. To specify multiple individual error numbers, separate the numbers with a vertical bar10|11|12. Optional. For data-dependent routing, the highest value that satisfies the criteria against which the data is checked. Double-quoted strings Smith, Chrisare supported. Maximum length is 128 characters. For error-dependent routing, the To field is the highest error number in the range.
From
To
Use a hyphen (-) to specify an unused field, except as described in Using Wild Cards and Priority.
Understanding Route Table Format

A route table is a simple text file with two kind of lines: Route entries begin in column one and consist of eleven case-sensitive fields separated by white space. The fields include the name of the service, the machine it executes on, the protocol and channel of the server connection, and the priority and data-dependency of the route. An optional or unused field is denoted by a hyphen (-). Route table fields correspond to the settings 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 single route from the local host. Comment lines begin with a pound sign (#) in column one. The route table for a communications client is initially empty except for commented copyright information.
Initializing the Route Table

By default, an RPC client obtains routing information from the dna.ini file. To enable route table routing, you have two choices: reconfigure the client with the host configuration tool, or set the following variables in the ROUTING section of the client dna.ini file. To edit the dna.ini file, select the machine icon in the Management Console and select Edit INI Properties. Clients obtain the path to the dna.ini file from an environment variable named DNAINI. Make sure you set the path to the dna.ini in the client environment: SET DNAINI=path.
2-34 Configuring and Managing Communications in Windows
UNIX clients set this variable in their startup script. Refer to Chapter 3, Configuring Communications in UNIX for more information about configuring UNIX clients.
Table 2-14 Settings in Routing section of dna.ini Variable NAME_SERVICE DNA_MAX_ROUTES DNA_NO_OF_RETRIES Setting for route table routing ROUTE_TABLE Maximum number of routes the system attempts for a given service request. The default is 1. Number of times the system retries an individual route. The default is 0. Number of seconds between the failure of a route and a retry. The default is 0. For each retry, the retry interval increments by a factor of two: if set to 10 seconds, it increments to 20 seconds after the first retry, 40 seconds after the second retry, and so forth. Full pathname of the route table. The default route table name is rtable. The default location is platform-specific: On Windows, the default location is: <AppBuilder>\nt\rt\rtable On UNIX hosts, the default location is: $HOME/nes_apps/<client_dir>/rtable On mainframe hosts, the default location is: <HIGH_LEVEL_QUALIFIER>.rtable
DNA_RETRY_INTERVAL
ROUTETBL
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 the keyword $ANY to indicate every route that matches all of the values specified in the remaining fields. For example, the route table entry $ANY - - - - - AIX_1 lu62 READLU62 - 1 refers to every rule on the AIX_1 machine that listens on the READLU62 channel over LU6.2. $ANY allows you to implement complex routing schemes with just a few route table entriessometimes as few as one. Consider the gateway example in the Gateway Routing section (Figure 2-40): two clients call the RDB_READ service and a gateway reroutes the request to another machine. While the example shows how to implement simple gateway routing, it is not realistic. More typically, multiple clients each 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 every request 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. Figure 2-36 recasts the gateway example from the previous section using $ANY. A single route table entry on the Windows NT gateway forwards requests from multiple Windows clients to the mainframe server. The route priority determines when the $ANY route is evaluated.
2-35
Figure 2-36
Wild card routing
Of course, the clients in this figure could use $ANY in their route tables, since the service requests are all routed 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 the READLU62 channel over LU6.2: $ANY - - - - - AIX_1 lu62 READLU62 - 1 Each route would have a priority of 1, unless the route was explicitly specified with a higher priority: # try RDB_READ on AIX_1 machine first, # routes to try alternate machines RDB_READ - - - - - AIX_1 lu62 READLU62 $ANY - - - - AIX_1 lu62 READLU62 $ANY - - - - Win_1 tcpip READTCP then use $ANY - 0 - 2 - 1
2-36
A $ANY route with a priority equal to that of an explicitly specified but otherwise identical route is ignored: # ignore $ANY route for all RDB_READ service requests $ANY - - - - AIX_1 lu62 READLU62 - 0 RDB_READ - - - - - AIX_1 lu62 READLU62 - 0 A $ANY entry is ignored if it has the same priority as a previous $ANY entry, even if the entries refer to different routes: $ANY - - - - - WinNT_1 tcpip READTCP - 0 $ANY - - - - - AIX_1 lu62 READLU62 - 0 The second $ANY entry is ignored. Use a higher priority instead: $ANY - - - - - WinNT_1 tcpip READTCP - 0 $ANY - - - - - AIX_1 lu62 READLU62 - 1
Understanding Routing Types

Programs that use remote procedure calls (RPCs) execute synchronously: clients request a service, wait for a response, and continue processing only after receiving it. AppBuilder applications can route service requests in their program code, but more typically use initialization file (dna.ini) routing or a route table on the client. This topic describes how you initialize the route table and create route table entries for server and gateway routing. You can modify route tables at runtime without interrupting network service. This topic includes: Alternate Routing where the repeated failure of a service route results in the use of a lower-priority route Data-Dependent Routing where a service route is dependent on the data being passed by the client Error-Dependent Routing where a service route is dependent on the kind of error that the client encountered Gateway Routing where a service route connects disparate machine types across a network or between networks An example of a client-server application may involve several platforms. For example, a client program on a Windows NT machine may use the database-read service, RDB_READ. Service requests are routed to an HP-UX workstation over a TCP/IP connection and to an AIX workstation over an LU6.2 connection.
Alternate Routing
Alternate routing allows you to direct a service request to another machine or to other machines if the primary server is down or otherwise unreachable. AppBuilder implements alternate routing by assigning a priority to each instance of the service request in the route table. Higher priority routes are tried first, followed by lower-priority routes. Consider the configuration in Figure 2-37. Let us suppose you want the service RDB_READ on the IBM AIX machine to be executed only if the call to the service on the Windows machine fails. Also, you want the system to retry the Windows route twice before attempting to use a different route.
2-37
Figure 2-37
Alternate routing
You must specify two routing parameters in the dna.ini file and then create the necessary route table entries. Follow these steps: 1. Specify the following values in the ROUTING section of the clients dna.ini file: DNA_MAX_ROUTES=2 DNA_NO_OF_RETRIES=2 The first value specifies the maximum number of routes the system attempts for a given request for the RDB_READ service. The second value specifies the number of times the system retries an attempt. 2. Create two entries in the clients route table: one for the first priority route and one for the second priority route. Use the Management Console to Edit the Route Table. (Refer to Editing the Route Table.) The last field in the each route table entry specifies the priority: RDB_READ - - - - - WINNT_1 tcpip READTCP - 1 RDB_READ - - - - - AIX_1 tcpip READTCP ISO438 2
2-38
Fields containing hyphens (-) are unused. The remaining fields have the following meanings: RDB_READ is the name of the service. WINNT_1 and AIX_1 are the IDs of the server machines as known to the protocols they use to communicate with the client: for the Windows NT machine, use the host name of the server machine in the client \tcpip\etc\hosts file; for the AIX machine, use the client-side profile name. tcpip is the network protocol (TCP/IP) for the routes. READTCP is the channel (or server ID) the server listens on: respectively, the TCP/IP service name in the client \tcpip\etc\services file on Windows NT. ISO438 is the code page in use at the AIX server node. 1 and 2 are the relative priorities of the route table entries. When you run the application, the system retries the TCP/IP route to the Windows NT server two times after the initial failure (three times total). After the third failure, it attempts to access the service on the AIX machine. It retries that route twice on failure as well.
Data-Dependent Routing
Data-dependent routing allows you to choose a service route based on the data being passed by the client. For example, suppose the service routes in our sample application are of equal priority but you want the database on the Windows NT machine to contain information only on customers whose names begin with the letters A through M, and the database on the AIX machine to contain information on all other customers.
Figure 2-38 Data-dependent routing
You can test the input in the route table entry for each server and determine if the data matches your criteria.
2-39
Follow these steps: 1. In the clients dna.ini file, specify the maximum number of routes the system attempts for a given request for the RDB_READ service: DNA_MAX_ROUTES=2 2. Specify the data-dependency of the service routes in the route table entries for each service request. Use the Management Console to Edit the Route Table. (Refer to Editing the Route Table.) RDB_READ 1 last_name char A M WinNT_1 tcpip READTCP - 1 RDB_READ 1 last_name char N Z AIX_1 tcpip READTCP ISO438 1 Field 1 and fields 7-11 are the same as before. Fields 2-6 have the following meanings: 1 is the length of the data to be checked, in bytes last_name is the symbolic name of the data field to be checked, as it appears in the controlstructure array for the service request char (character) is the type of data in the specified field A and N are the lowest values that satisfy the criteria for each route M and Z are the highest values that satisfy the criteria for each route When you run the application, the system uses the TCP/IP route to the Windows NT server if the server input begins with the letters A through M, and the TCP/IP route to the AIX server route if the input begins with N through Z. To specify data containing spaces, enclose the string in double quotes, for example, Smith, Chris. You can include a double-quoted string in either limit field.
Error-Dependent Routing
Error-dependent routing is similar to data-dependent routing, but uses an AppBuilder error code instead of client data to base the routing decision. Suppose our sample application performs errorhandling with the CHK_STAT service. The Windows NT server handles the class of errors denoted by AppBuilder communications error codes 105 through 110, and the AIX server handles the class of errors denoted by error codes 10, 11, and 12.
2-40
Figure 2-39
Error-dependent routing
Like data-dependent routing, you can specify the routing criteria in the route table entry. Errordependent routing fields replace data-dependent routing fields in these entries: set the data offset field to the keyword DNAERROR, and specify the error number range in the from and to fields. Use the Management Console to Edit the Route Table. (Refer to Editing the Route Table.) CHK_STAT - DNAERROR - 105 110 WinNT_1 tcpip STAT_TCP - 1 CHK_STAT - DNAERROR - 10|11|12 - AIX_1 tcpip STAT_LU ISO438 1 As shown above, you can specify multiple individual error codes in the from field by separating the error numbers with a vertical bar.
Gateway Routing
A gateway is a server that translates protocol information from one network format into anotherit reroutes client requests rather than fulfilling them directly. You specify the routing information for a gateway not only on the client machine, but on the gateway machine as well. Suppose our client program executes on a series of Windows machines in a TCP/IP network, while the RDB_READ service executes on a mainframe running CICS. Since TCP/IP is not available for mainframe, we need a gateway to connect to the mainframe over another network protocol. Figure 2-40 shows how you might accomplish this using a Windows NT gateway with a connection over LU6.2.
2-41
Figure 2-40
Gateway routing
To set up the gateway: 1. In the dna.ini file on both the client and gateway machines, specify the maximum number of routes the system attempts from either machine: DNA_MAX_ROUTES=1 2. Create an entry for the route to the gateway in the route table on the client machines. Use the Management Console to Edit the Route Table. (Refer to Editing the Route Table.) RDB_READ - - - - - Win_N tcpip READNP IBM437 1 The fields have the following meanings: RDB_READ is the name of the service Win_N is the Machine ID for the machine on which the gateway resides tcpip (for TCP/IP) is the network protocol for the route READNP is the channel (or server ID) the gateway listens on IBM437 is the code page in use at the gateway node 1 is the priority of the route entry 3. Create an entry for the route to the mainframe server in the route table on the gateway machine. Use the Management Console to Edit the Route Table. (Refer to Editing the Route Table.) RDB_READ - - - - - MVS_1 lu62 READLU62 IBM037 1 The fields have the following meanings:
2-42
RDB_READ is the name of the service MVS_1 is the ID of the server machine as known to the protocol for the route: for LU6.2, the client-side Partner LU alias lu62 is the network protocol for the route READLU62 is the channel (or server ID) the server listens on: for LU6.2, the CICS transaction ID IBM037 is the code page in use at the server node 1 is the priority of the route entry When you run the application, the gateway reroutes client requests to the mainframe server. Forwarding Servers A forwarding server has the characteristics of both an execution sever and a gateway. It services client requests if the service DLL is stored locally; otherwise, it forwards the request to a different server. In some situations, you can use a forwarding server as an alternative to priority-based routing. Suppose you wanted to test a subset of an applications services on server 1, while continuing to maintain the entire set of services on server 2. The forwarding server acts as a gateway when the DLLs for the larger set are not found. As long as you specify the route to the services in the route table on server 1, the system will look for the services on server 2. In addition, you can also configure a reverse forwarding server. A reverse forwarding server looks for the service at the remote location before it looks for it locally.
Configuring Routing
This topic includes: Configuring for a Single Server Configuring for Multiple Servers
Configuring for a Single Server

If you want the client to route service requests to a single server, you can specify that the configuration be Single Server. By default, an AppBuilder client is configured to route service request to the execution server running on the machines RPC parent. In single-server routing, the client obtains routing information from the communications configuration file, dna.ini. The host name (or parent name) can be changed. If you want the client to route service requests to a different host, clear the current host name and enter a new one. The form of the name depends on the protocol as defined in Table 2-15.
Table 2-15 Host name by protocol Protocol TCP/IP Named Pipes Host name Host name of the machine in the hosts file Named Pipes Machine ID or, if a requested service resides on the same machine as the client, LOCAL
2-43
To configure this value, refer to Configuring a Windows Client for Remote Communications for an explanation of how to get to the Routing Tab in the Client Properties.
Configuring for Multiple Servers

If you want the client to route service requests to multiple servers, select Multiple Servers. In multipleservice routing, the client obtains routing information from a route table. Enter the full path name (including drive letter) of the route table in the Route Table field.
2-44
CHAPTER
CONFIGURING COMMUNICATIONS IN UNIX
This section describes how to set up a UNIX workstation as an AppBuilder communications client, execution server, or both. It lets you add the workstation to the agent hierarchy and configure it for use in messaging and eventing applications. It also lets you configure the workstation as a batch server or gateway. These topics include: Starting UNIX Configuration Understanding the UNIX Configurator Configuring a UNIX Client for Remote Communications Configuring a UNIX Server for Remote Communications Configuring a UNIX Host for Messaging Applications Configuring a UNIX Host for Eventing Applications Configuring a UNIX Batch Server Configuring a UNIX Gateway Configuring a UNIX Database Completing UNIX Configuration You can set up a different configuration for each workstation user. All users on a workstation share the same agent and database configurations. The UNIX configurator provides two configuration options: quick configuration and custom configuration. This section describes custom configuration only. For details on quick configuration, see the Installation Guide for UNIX.
Note
Shut down the AppBuilder client you want to configure before running the configurator. You must shut down a server only if you are changing the protocol it uses.
Starting UNIX Configuration

UNIX workstations are often shared by several users. Before you can configure the workstation, you must make sure that each UNIX user is also a AppBuilder user. This topic describes how you create AppBuilder users and start the configurator. Creating AppBuilder User Accounts Starting the Configurator
3-1
Creating AppBuilder User Accounts

When you install AppBuilder software on a UNIX host, user appbuilder owns AppBuilder files and directories. The appbuilder account is reserved for the AppBuilder administrator. This is a privileged account that can configure all AppBuilder features, including the database and agent. Other users have limited configuration choices. Before another user can run the configurator, you must set up the users account with the mknesuser utility. Log in as root, then enter the following command: Only root has the privilege to change another users .profile; user appbuilder does not. $ mknesuser The following prompt is displayed: Enter a user name (? for list or Enter to Exit): user_name Enter a UNIX user name, user_name, for example, or a question mark to see a list of all users. The utility updates the users .profile, defining AppBuilder environment variables and adding <AppBuilder>/nete/ bin to the users path, where AppBuilder is the install directory. Updating User Accounts The updnesuser utility allows you to update a user account. Use this utility when you install a new AppBuilder software release and want to make sure that all AppBuilder user accounts point to the right area. The utility updnesuser displays the menu as shown in Figure 3-1.
Figure 3-1 Utility updnesuser menu
You can update a list of users (L), yourself (C), or a specific user (S). To update anyone but yourself, you must run the utility as root. When the user runs the configurator, AppBuilder clients and servers will be created by default in $HOME/nes_apps. We recommend that users run quick configuration first, to establish a base configuration consisting of a default RPC client and server.
Starting the Configurator

Log in as appbuilder or another valid AppBuilder user. The appbuilder user is the only user who can configure the agent and database. Enter the following command to start the configurator: $ necfg
3-2
Configuring Communications in UNIX
The system displays the welcome screen shown in Figure 3-2. Press the space bar to choose Custom configuration and then press Enter.
Figure 3-2 Welcome screen
If you have trouble starting the configurator, check the environment variables TERM and TERMINFO. vt100 and xterm are the most common choices for TERM. The NetEssential Objects screen is displayed next, as shown in Figure 3-3. The screen you see may differ, depending on the protocols installed on your host. There is one server/agent pair per protocol. The NetEssential Objects screen provides access to the configuration options for each AppBuilder feature: The Default RPC Client option allows you to configure the client created during installation. See Configuring a UNIX Client for Remote Communications. The Default RPC Server option allows you to configure the execution server created during installation. See Configuring a UNIX Server for Remote Communications. The System Service Agent option allows you to configure the agent for messaging and eventing applications. See Configuring a UNIX Host for Messaging Applications and Configuring a UNIX Host for Eventing Applications. The New Object (Create) option allows you to create a new client, execution server, gateway, or batch server. See Configuring a UNIX Batch Server and Configuring a UNIX Gateway. The Database (DBMS) configuration option allows you to configure the database that your servers access. See Configuring a UNIX Database.
3-3
Understanding the UNIX Configurator
Figure 3-3
Communication Objects screen
The following sections describe each of these procedures. Be sure to review the usage notes before proceeding. When you finish using the configurator, be sure to perform the tasks in Completing UNIX Configuration. Typically, you do not have to perform all of the procedures in this chapter. Configure only the features that your host needs to use.

The configurator is organized as a series of menu and edit screens. This topic includes: General Navigation Using the Action Menu Setting up Servers Renaming Client or Servers Agent Restrictions
General Navigation
You navigate and edit in the screens as follows: To move between menu options, use the up-arrow and down-arrow keys. You can use the space bar instead of the down-arrow key if you prefer. To select a menu item directly, type the first character of the option name; this character is highlighted in the display. When multiple options begin with the same character, typing the character toggles through them. To edit a configuration value, press the F2 function key. The word EDIT appears in the upper left-hand corner of the screen, as shown in Figure 3-4.
3-4
Figure 3-4
Edit mode example screen
Use the left-arrow and right-arrow keys to move the cursor in edit mode, then type over the current value. Press F2 again to exit edit mode; this is required before you can accept a new value. To accept a value and continue the configuration, press Enter. You can use the right-arrow key instead of Enter if you prefer, except in edit mode. To save your changes and continue the configuration, use the Save changes option in the object configuration menu. To cancel your changes, use the Abandon changes option. To return to the previous screen, use the Backspace key. To exit the configurator, type X or press the F3 function key. To get help on prompts, press the F1 function key. (Help is not available for every prompt.) Press F2 or Esc to exit help mode.
Using the Action Menu

You can configure, launch, shut down, or delete a client or server from its Action menu, as shown in Figure 3-5.
Figure 3-5 Typical action menu
3-5
Configuring a UNIX Client for Remote Communications
Note that: When you launch a client, the configurator executes the script $HOME/nes_apps/<client_name>/ ne_client. This script must be updated to point to the client executable. When you delete a client or server, the configurator removes the corresponding subdirectory from $HOME/nes_apps. When you launch a client or server from the configurator, it runs as a background process. $HOME/nes_apps is a default location that you can change when you create a new object.
Setting up Servers
When you create a new server (rather than configure an existing one), the configurator creates a subdirectory under $HOME/nes_apps for the server executable and runtime files. Typically, the directory name is the same as the server ID.
Renaming Client or Servers

You can rename any client or server. Renaming a server changes only its long namethe name used to identify it in configurator menus; the server ID does not change.
Agent Restrictions
You cannot create a new agent or delete the default agent. Rerun quick configuration to create a server/ agent pair for a newly installed network protocol. See Handling Server/Agent Pairs for details. How the Configurator Updates TCP/IP Files When you create a new TCP/IP server or modify the server ID or port number of an existing TCP/IP server, the configurator creates a file named new_services_file in your home directory. This file contains the same entries as /etc/services plus the new or updated entries. The root user must replace /etc/services with new_services_file when the configuration is complete. When you create an autostart server, the configurator creates a file named new_inetd.conf_file in your home directory. This file contains the same entries as /etc/inetd.conf plus an entry for the new server. The root user must replace /etc/inetd.conf with new_inetd.conf_file when the configuration is complete.

RPC client configuration prepares a AppBuilder client for RPC communication with remote servers. You can configure the default client created during installation or create a new client. To begin configuring the default client: 1. 2. Select Default RPC Client from the NetEssential Objects menu. Select Configure Default RPC Client from the Default RPC Client Action menu.
The Default RPC Client Configuration menu is displayed, as shown in Figure 3-6. You can choose to configure basic options, configure advanced options, or edit the communication initialization file (dna.ini) on the client and set individual configuration variables. For more information on each of these refer to the following:
3-6 Configuring Communications in UNIX
Configuring Basic Settings of Client Configuring Advanced Settings of Client Editing Client Communications Settings Creating a New UNIX Client for Remote Communications To configure an RPC client, you must provide information in the following categories: Routingwhether the client routes service requests to a single server or multiple servers, and for single-server routing, the destination of service requests Securitysecurity exits used by the client (if any) Performanceperformance characteristics for client/server interaction Tracingkind of information to be written to the clients error log (trace) file
Figure 3-6 Client configuration menu
Configuring Basic Settings of Client

Basic configuration lets you configure the clients routing method, routing destination, and network protocol for communication with remote servers. Configuring the Routing Method Configuring the LU6.2 Mode Name Configuring the Default Routing Choose Basic Configuration from the Default RPC Client Configuration menu, then choose RPC - Remote Proc Call from the Basic Configuration menu. The routing options menu is displayed, as shown in Figure 3-7.
3-7
Figure 3-7
Routing options
Configuring the Routing Method

By default, a AppBuilder client is configured to route service requests to a single server only, namely, the execution server running on the machines RPC parent. In single-server routing, the client obtains routing information from the dna.ini file. To specify a different routing method, choose Routing type from the routing options menu. The routing method screen is displayed, as shown in Figure 3-8: Choose Multiple hosts (route table routing) to route service requests to multiple hosts. Use Advanced configuration to specify additional routing parameters, as described on Configuring Advanced Settings of Client. Choose External name service to use an external name service to obtain routing information. If you choose route-table routing, you must create route table entries when you are done configuring the workstation. If you choose external name service routing, refer to Configuring Routing in Chapter 2, Configuring and Managing Communications in Windows for details about the setup procedure. In particular, make sure your custom directory service function is installed.
3-8
Figure 3-8
Routing method selection screen
Configuring the LU6.2 Mode Name

For all routing methods, if the client communicates with the remote system over LU6.2, you must specify an APPC mode name, or accept the default. The default mode name is BLANK. To specify a different mode name, choose LU6.2 protocol mode name from the routing options menu. The mode name screen is displayed, where you can specify a different value. For OS/400 (iSeries) systems, you must set the mode name to QPCSUPP on the client and server sides of the connection.
Configuring the Default Routing

To configure default routingto route service requests to a different server, for examplechoose Default Routing from the routing options menu. The default routing configuration screen is displayed, as shown in Figure 3-9. This option is available only if Routing type is set to One host (dna.ini routing). Specify the following information about the route, or accept the defaults: Host namethe host name of the machine to which the client routes service requests. For TCP/IP, the host name of the machine in the hosts file. For LU6.2, the client-side Partner LU alias. Code pagethe code page for the language in use on the server host (optional). The configurator detects as many code pages as it can, but there may be others. See Appendix A, Code Page Support for more information on supported code pages. Protocolthe protocol for communication between the client and server. Server IDthe ID of the server to which the client routes service requests. For TCP/IP, the server name in the services file. The default is nete. TCP port numberthe servers TCP/IP port number in the services file. The default is 3090.
3-9
Figure 3-9
Default routing screen
Configuring Advanced Settings of Client

Advanced configuration lets you configure the clients security, performance, and tracing (error-logging) features. To configure the clients advanced features, return to the Default RPC Client Configuration menu (Figure 3-6). Choose Advanced Configuration from the menu. In the Advanced Configuration menu, choose the option for the feature you want to configure. This topic includes: Configuring Security Information for an RPC Client Configuring Performance Information for an RPC Client Configuring the Trace File for an RPC Client
Configuring Security Information for an RPC Client

Choose Security from the Advanced Configuration menu. The security configuration screen is displayed, as shown in Figure 3-10.
3-10
Figure 3-10
RPC client security screen
This screen allows you to identify the exits the client uses to: Obtain authentication and authorization information Encrypt and decrypt passwords Log remote service usage (RPC-end exit) By default, clients do not invoke any security exits. The RPC-end exit is also referred to as the client trace exit. For each security exit, specify the exits full path name. On UNIX hosts, security exits take the form of a DLL. For example, you might enter <home_dir>/nete/bin/authen.dll for the authentication exit. For details on the purpose, use, and coding of security exits, refer to Chapter 6, Extending Communications.
Configuring Performance Information for an RPC Client

Choose Client Performance from the Advanced Configuration menu. The performance configuration screen is displayed, as shown in Figure 3-11.
3-11
Figure 3-11
RPC client performance screen
You can specify the following performance characteristics, or accept the defaults: Polling interval (LU6.2 only)determines how long the client waits before polling for data, in milliseconds. The default is 250. A polling interval below 100 may degrade the performance of other processes on the machine. Timeoutdetermines how long the client tries to reach the server before timing out, in seconds. The default is 600. Set the timeout value to 0 if you do not want the client to time out. The outbound side of a gateway may also have a timeout value. To prevent the client timing out before the gateway, make sure the client has a greater timeout value than the gateway. Data optimizationdetermines if the client transmits an optimized control-structure array to the server. An optimized control-structure array does not include all of the control information normally sent to the server (such as field names): Select Service Request to optimize the data sent with static service requests, global events, and messages Select Dynamic Request to optimize the data sent with dynamic service requests By default, both optimizations are enabled. Maximum number of routesmaximum number of routes AppBuilder attempts for a given service request. The default is 1. Number of retries per routenumber of times AppBuilder retries a route. The default is 0; if the first attempt fails, no further attempts are made. Retry intervalnumber of seconds between the failure of a route and a retry. The default is 0 (retry immediately). For each retry, the retry interval increments by a factor of two: if set to 10 seconds initially, it increments to 20 seconds after the first retry, 40 seconds after the second retry, and so forth.
Configuring the Trace File for an RPC Client

Choose Tracing from the Advanced Configuration menu to configure the clients error-logging features. The trace file configuration screen is displayed, as shown in Figure 3-12.
3-12
Figure 3-12
RPC client trace file screen
You can specify the following information about the trace file, or accept the defaults: Trace file namefull path name of the file to which AppBuilder writes messages. Errors that occur before initialization are reported in the file /tmp/dnatrace.out file. Level of loggingdetermines the kind of information that will be written to the trace file: Input and output views hold logically related data sent to or received from a service. For details, see Chapter 6, Extending Communications. Select ERRORS if you want to log errors only. Select ERRORS AND LENGTHS if you want to log errors, the time the unsuccessful function was called, the time the function exited, and input/output view lengths. Select ERRORS AND DATA if you want, in addition to the information provided by ERRORS AND LENGTHS, a hex dump of the view data, with the type of view data and number of bytes written per view determined by the values entered for Data dump type, Data dump input size, and Data dump output size. Select ERRORS AND TRACES if you want, in addition to the information provided by ERRORS AND DATA, trace information for successful calls. For both successful and unsuccessful calls, AppBuilder provides a hex dump of the input and output view, with the number of bytes to be written per view determined by the values entered for Data dump input size and Data dump output size. For unsuccessful calls, AppBuilder also logs status view data. A hex dump is included in the trace file output if a network call was made in the course of processing. The default is ERRORS.
Note
Select ERRORS AND TRACES only when debugging AppBuilder applications. It can degrade system performance and use excessive disk space.
Data dump typedetermines the types of view data written to the trace file. Choose one of the following: INPUT for input views OUTPUT for output views
AppBuilder 2.1.0 Configuring Communications Guide 3-13
BOTH for both input views and output views Data dump input sizedetermines the number of bytes written to the trace file for each input view. The default is 512 bytes. The complete input view is written if the value is greater than the number of bytes in the view. Valid only if level of logging is ERRORS AND DATA or ERRORS AND TRACES, and the data dump type is INPUT or BOTH. Data dump output sizedetermines the number of bytes written to the log file for each output view. The default is 512 bytes. The complete output view is written if the value is greater than the number of bytes in the view. Valid only if level of logging is ERRORS AND DATA or ERRORS AND TRACES, and the data dump type is OUTPUT or BOTH. Size of log filesize of the trace file, in bytes. Specify an integer followed by an upper-case K (for kilobytes) or M (for megabytes). The default is 1M. When the trace file exceeds this size, the information is deleted and stored in the backup trace file. Backup trace filefull path name of the file to which AppBuilder writes information when the size of the main trace file exceeds its maximum size. The default backup trace file is named trace.bak.
Editing Client Communications Settings

To configure the client dna.ini file, return to the Default RPC Client Configuration menu Figure 3-6. Choose dna.ini edit from the menu. The dna.ini file settings screen is displayed, as shown in Figure 3-13.
Figure 3-13 dna.ini file settings screen
This screen allows you to set any variable in the clients dna.ini file, by section. Table 3-1 lists a few clientside variables that you may want to set now.
3-14
Table 3-1 Section DNA
Client DNA variables Variable Maximum servers Description Maximum number of servers the client can communicate with. The default is 50. Determines how AppBuilder handles pending database transactions. Specify: NONCONVERSATIONAL if you want AppBuilder to commit pending database transactions after the service request completes and then close the server connection. Table 2-2 shows the relationship between the Logical unit of work values and their values in previous releases. PSEUDOCONVERSATIONAL if you want AppBuilder to commit pending database transactions after the service request completes but leave the server connection open. CONVERSATIONAL if you want AppBuilder to commit or abort pending database transactions when the client context closes or as specified explicitly in the code. The server connection closes when the client context closes. Set Logical unit of work to NONCONVERSATIONAL for communications with the mainframe. Determines how AppBuilder handles pending database transactions when the client context closes. This field is relevant only when Logical unit of work (see above) is set to CONVERSATIONAL. The default is COMMIT. Specify ABORT if you want AppBuilder to roll back pending database transactions when the client context closes. Full path name of the route table. The default is:
DNA
Logical unit of work
DNA
Close semantics
ROUTING
Route table name
$HOME/nes_apps/default_client/rtable
Creating a New UNIX Client for Remote Communications

Configuring a new RPC client is similar to configuring the default client. You must perform a few preliminary steps and then follow the procedures in the preceding sections to finish the configuration. From the NetEssential Objects menu (Figure 3-3), choose New Object (Create). The New Object screen is displayed, as shown in Figure 3-14.
Figure 3-14 New object screen
Choose Client from the menu, then enter the following information:
Configuring a UNIX Server for Remote Communications
Object long namea descriptive name used to identify the client in configurator menus. Parent directoryfull path name of the directory in which you want the client directory to be located. Object namename of the client directory. The client directory is used to store runtime files, the client trace file, and so forth. Enter a leaf name only, not a full path name. The client directory is located in the parent directory specified in the previous step. When the new client Action menu appears, choose Configure new_client and then follow the procedures in Configuring Basic Settings of Client and Configuring Advanced Settings of Client to configure the clients basic and advanced features.

RPC server configuration prepares a AppBuilder execution server for use on the local host. You can configure the default execution servers created during installation or create new execution servers. You can also configure an execution server as a forwarding server. If the server accesses a database, you also have to specify the database name. To begin configuring the default RPC server: 1. 2. Select Default RPC Server from the NetEssential Objects menu (Figure 3-3). Select Configure Default RPC Server from the Default RPC Server Action menu.
The Default RPC Server Configuration menu is displayed, similar to the screen shown for the client configuration in Figure 3-6. You can choose to configure basic options, advanced options, or edit the communication initialization file (dna.ini) on the client and set individual configuration variables. For more information on each of these refer to the following: Configuring Basic Settings on the Server Configuring Advanced Settings on the Server Editing Server Communications Settings Creating a New UNIX Server for Remote Communications To configure an RPC server, you must provide information in the following categories: Protocolnetwork protocol for communication between the server and clients Performanceserver type and performance characteristics Securitysecurity exits used by the server (if any) Tracingkind of information to be written to the servers error log (trace) file
3-16
Configuring Basic Settings on the Server

Basic configuration lets you configure the servers protocol, type, database, and forwarding characteristics. Choose Basic Configuration from the Default RPC Server Configuration menu, then choose RPC Remote Proc Call from the Basic Configuration menu. Refer to Configuring Forwarding Information for an RPC Server. The basic configuration menu is displayed, as shown in Figure 3-15.
Figure 3-15 RPC server basic configuration screen
You can specify the following server configuration information, or accept the defaults: Protocolthe network protocol for communication between the server and clients. Server IDthe ID of the server. For TCP/IP, the service name in the services file. For LU6.2, the server-side TP name. The default is nete. For LU6.2, the server ID is provided for information only. The configurator does not update SNA with the specified TP name. Port numberthe servers TCP/IP port number in the services file. The default is 3090. Server typethe type of server. Your choices are: forking, banking, and autostart. The default is banking. Database namethe name of the database the server accesses. For an Oracle local instance, enter N/A (it must be capital N/A because it is case sensitive); otherwise enter the remote instance. Local code pagecode page for the language in use on the server machine. The configurator detects as many code pages as it can, but there may be others. See Appendix A, Code Page Support for more information on supported code pages. Server DLL directoryfull path names of the directories where the DLLs invoked by the server are stored. Separate directory structures with a comma (,).
3-17
Banking server setupthe following choices are available only if the server type is set to banking: Pre-spawned banking serversnumber of worker processes to be spawned by the banker when started. The default is 5. Maximum banking server instancesmaximum number of worker processes in the system, including prespawned workers and dynamically spawned workers. The default is 15 Dynamic banking server timeoutamount of time, in seconds, that a dynamically spawned worker process can remain idle before being killed. The default is 60.
Configuring Forwarding Information for an RPC Server

A forwarding server has the characteristics of both an execution server and a gateway. You can configure a forwarding server to: Process requests if the service DLLs are stored locally; otherwise forward the requests to a remote server Forward requests to a remote server; if the service DLLs are not found there, then process the requests locally To set up a forwarding server, choose Forwarding Setup in the RPC server basic configuration menu (Figure 3-15). The forwarding setup screen is displayed, as shown in Figure 3-16.
Figure 3-16 Forwarding server setup screen
Choose Function as a forwarding server? in the forwarding setup menu, then specify Yes at the prompt. 1. Choose Forwarding choice in the forwarding setup menu, then choose: Local first, then remote if you want the server to attempt to satisfy requests locally before attempting to satisfy them remotely Remote first, then local if you want the server to attempt to satisfy requests remotely before attempting to satisfy them locally 2. Choose Forwarding routing in the forwarding setup menu. The routing method screen is displayed, as shown in Figure 3-8. Configuring the forwarding servers routing options is identical to configuring the routing options for an RPC client. See Configuring the Routing Method for a complete description.
3-18
Configuring Advanced Settings on the Server

Advanced configuration lets you configure the servers security, performance, and tracing (errorlogging) features. It also lets you configure a forwarding servers client-side security and performance characteristics. To configure the servers advanced features, return to the Default RPC Server Configuration menu. Choose Advanced Configuration from the menu. In the Advanced Configuration menu, choose the option for the feature you want to configure. This topic includes: Configuring Security Information for an RPC Server Configuring Performance Information for an RPC Server Configuring Client-Side Security and Performance Information for a Forwarding Server Configuring the Trace File for an RPC Server
Configuring Security Information for an RPC Server

Choose Security from the Advanced Configuration menu. The security configuration screen is displayed, as shown in Figure 3-17. This screen allows you to identify the security exits the server uses to obtain authentication and authorization information. By default, servers do not invoke any security exits. For each security exit, specify the exits full path name. On UNIX hosts, security exits take the form of a DLL. For example, you might enter <home_dir>/nete/bin/authen_srv.dll for the authentication exit. For details on the purpose, use, and coding of security exits, refer to Chapter 6, Extending Communications.
Figure 3-17 Server security screen
Configuring Performance Information for an RPC Server

Choose Performance from the Advanced Configuration menu, then choose Server performance in the advanced configuration performance screen. The performance configuration screen is displayed, as shown in Figure 3-18.
3-19
Figure 3-18
RPC server performance screen
You can specify the following performance characteristics, or accept the defaults: Polling interval (LU6.2 only)determines how long the server waits before polling for data, in milliseconds. The default is 250. A polling interval below 100 may degrade the performance of other processes on the machine. Timeoutdetermines how long the server waits for the client before timing out, in seconds. The default is 600. Set the timeout value to 0 if you do not want the server to time out.
Configuring Client-Side Security and Performance Information for a Forwarding Server

Choose Security or Performance, as appropriate, from the Advanced Configuration menu, then choose the client-side setup option for the selected feature. The configuration screens are identical to the RPC clients. See Configuring Security Information for an RPC Client and Configuring Performance Information for an RPC Client for complete descriptions.
Configuring the Trace File for an RPC Server

Choose Tracing from the Advanced Configuration menu to configure the servers error-logging features. The configuration screen is identical to the RPC clients. See Configuring the Trace File for an RPC Client for a complete description.
Editing Server Communications Settings

To configure the server dna.ini file, return to the Default RPC Server Configuration menu. Choose dna.ini edit from the menu. The dna.ini file settings screen is displayed, as shown in Figure 3-13. This screen allows you to set any variable in the servers dna.ini file, by section. Table 3-2 lists a few server-side variables that you may want to set now. If you configured a forwarding server, you may want to set some of the variables in Table 3-1 as well.
3-20
Refreshing an Executing Server Initialization Values

You can refresh an executing servers initialization values with the kill command. After you edit settings in the server dna.ini file, issue the command: kill -1 pid where pid is the process ID of the server.
Table 3-2 Section DNA_SERVER Server DNA variables Variable Services per server Description Maximum number of services the server can invoke per connection. The default is 100. Do not set this value too conservatively for your application. The system memory allocated per service at initialization is minimal. COMMIT (the default) tells the server to commit the transaction before replying to the client. ABORT tells the server to commit the transaction only if the reply to the client succeeds. Server close semantics is irrelevant when the logical unit of work is set to CONVERSATIONAL (see Table 3-1).
DNA_SERVER
Server close semantics
Creating a New UNIX Server for Remote Communications

Creating a new RPC server is similar to creating a new RPC client. You must perform a few preliminary steps and then follow the procedures in the preceding sections to finish the configuration From the NetEssential Objects menu (Figure 3-3), choose New Object (Create). The configuration screens for a new server are identical to those for an RPC client. See Creating a New UNIX Client for Remote Communications for a complete description. When you create a new server, it is best to use the server ID as the name of the server directory.
Handling Server/Agent Pairs

Be aware that you often must create a new agent when you create a new execution server. If the execution server listens over a different protocol from any other server on the same hostLU6.2, for example and its clients talk only over LU6.2, then, to configure the host for messaging and eventing, you must create an agent that also listens over LU6.2. The default configuration uses this model: there is one server/agent pair for each protocol detected on the host. In fact, if you install a new protocol, the easiest way to add a new server/agent pair is to rerun quick configuration. Note that you are not required to follow this model: if a client talks over multiple protocols, its local agent may be able to access an existing agent on the server. That is, if the clients in our example talk over TCP/IP as well as LU6.2, their agents can access the agent on the server over TCP/IP. For more information, see Configuring the UNIX Eventing Agent.
3-21
Configuring a UNIX Host for Messaging Applications

Messaging configuration prepares a AppBuilder host to send and/or receive messages. To configure a host for messaging applications, you must provide information in the following categories: Client configurationidentifies the RPC clients messaging protocol Server configurationidentifies the RPC servers messaging protocol Agent configurationidentifies the agents network protocol and performance characteristics, and its parent in the agent hierarchy This topic includes: Configuring a UNIX Messaging Client or Server Configuring the UNIX Messaging Agent Configuring a UNIX Eventing Client or Server Configuring the UNIX Eventing Agent
Configuring a UNIX Messaging Client or Server

AppBuilder clients and servers send and receive messages using: Native messagingmessage queues are created on demand in shared memory MQSeries messagingpreallocated message queues are created in shared memory or on disk By default, a AppBuilder client or server is configured to use native messaging. To use MQSeries messaging instead of, or in addition to, native messaging, select Messaging from the client or servers Basic Configuration menu. The Messaging configuration screen is displayed, as shown in Figure 3-19.
Figure 3-19 Messaging configuration screen
3-22
Choose the messaging protocol you want to enable or disable and then respond to the Use messaging_method prompt with a Yes or No answer. If you enable MQSeries messaging, you also must provide the name of the MQSeries queue manager. The MQSeries queue manager does not have to be present when you configure the client, but must be present at run time. For information about setting up the queue manager, see Chapter 5, Configuring Communications Using MQSeries AppBuilder obtains queue routing information from a route table. Applications use the same route table for both RPC and message routingonly the entry format differs. If you choose AppBuilder native and/ or MQSeries messaging, you must create route table entries when you are done configuring the workstation.
Configuring the UNIX Messaging Agent

To configure the messaging agent, you must identify its parent/child relationships: how does the agent reach its network parent? how do its network children reach the agent? You also must decide if the agent is going to be the root of the hierarchy: an agent with children but no parent. To begin configuring the agent, make the following menu selections: You cannot create more than one agent per protocol. 1. 2. Select System Service Agent from the NetEssential Objects menu (Figure 3-3). Select Configure System Service Agent from the System Service Agent Action menu.
The System Service Agent Configuration menu is displayeda similar screen is shown in Figure 3-6. You can choose to configure basic options, advanced options, or edit dna.ini. The following sections describe the configuration options in each category.
Basic Configuration
Basic configuration allows you to configure the agents protocol characteristics, server type, and parent in the agent hierarchy. Choose Basic Configuration from the System Service Agent Configuration menu, then choose Eventing/Messaging from the Basic Configuration menu. The basic configuration menu is displayed, as shown in Figure 3-20.
3-23
Figure 3-20
Agent basic configuration screen
You can specify the following agent configuration information, or accept the defaults: Server IDthe ID of the agent. For TCP/IP, the service name in the services file. For LU6.2, the server-side TP name. The default is ne20. For LU6.2, the server ID is provided for information only. The configurator does not update SNA with the specified TP name. Port numberthe agents TCP/IP port number in the services file. The default is 3088. Server typethe type of server. Your choices are: forking, banking, and autostart. The default is autostart. Banking server settingsthe following choices are available only if the server type is set to banking: Pre-spawned banking serversnumber of worker processes to be spawned by the banker when started. The default is 5. Maximum banking server instancesmaximum number of worker processes in the system, including prespawned workers and dynamically spawned workers. The default is 15 Dynamic banking server timeoutamount of time, in seconds, that a dynamically spawned worker process can remain idle before being killed. The default is 60.
Configuring the Agents Relationship with its Parent

To configure the agents relationship with its parent, choose Parent settings in the agent basic configuration menu (Figure 3-20). The agent hierarchy setup screen is displayed, as shown in Figure 3-21.
3-24
Figure 3-21
Agent hierarchy setup screen
If the agent is the root of the AppBuilder hierarchy (an agent with no parent), choose A. Be the root of the NetEssential hierarchy. The configurator does not prevent you from creating two (or more) top-level agents. If you change the top-level agent, be sure to reconfigure the previous top-level agent. If the agent is an intermediate or leaf node, choose B. Be an intermediate or leaf node. To configure the node: 1. 2. Choose the network protocol for communication between the agent and its parent in the protocol screen. Enter the protocol-specific host name of the parent in the host name screen. For TCP/IP, the host name of the machine in the hosts file. For LU6.2, the client-side Partner LU alias. The default is the host name of the machine to which RPCs are routed, as specified in the RPC client configuration. The configurator validates the host name of the parent against the hosts file. If the host name is invalid, you cannot continue to step 3. Add the parents host name to the hosts file and rerun the configurator. If the host does not have connectivity with its parent (if the agent on the parent is not running, for example), you must perform additional steps to complete the configuration. 3. You can specify the following information about the agents parent in the parent settings screen, or accept the defaults: Protocol-independent namea descriptive name used to identify the parent machine across protocols. By default, the protocol-independent name is the same as the protocol-specific host name. Server IDthe ID of the agent on the parent machine. For TCP/IP, the server name in the services file. The default is ne20. Port numberthe TCP/IP port number of the agent on the parent machine. The default is 3088. Code pagecode page for the language in use on the parent machine. The configurator detects as many code pages as it can, but there may be others. See Appendix A, Code Page Support for more information on supported code pages.
3-25
Advanced Configuration
Advanced configuration allows you to configure the agents security, performance, and tracing (errorlogging) features. To configure the agents advanced features, return to the System Service Agent Configuration menu. Choose Advanced Configuration from the menu. In the Advanced Configuration menu, choose the option for the feature you want to configure. Configuring Security Information for a Messaging Agent This option is relevant for AIX and HP-UX only. If the parent machine is a security-enabled mainframe listening over LU6.2, the agent must point to a client-side authentication exit. The authentication exit passes the user name and password to LU6.2. There is no need to code a server-side exit. Choose Security from the Advanced Configuration menu, then Client-side security exit. The client-side security screen is displayeda similar screen is shown in Figure 3-10. Choose Authentication exit, then specify the exits full path name at the prompt. On UNIX hosts, security exits take the form of a DLL. For example, you might enter <install_dir>/nete/ bin/authen.dll. If you configured the host for RPCs as well as messaging and eventing, enter the path name of the authentication exit you specified for the RPC client. Ignore the prompts for the other exits; these are irrelevant for a messaging/eventing agent. For details on the purpose, use, and coding of security exits, refer to Chapter 6, Extending Communications. Configuring performance information for a messaging agent Configuring the agents performance features is similar on the inbound side to configuring the performance features of an RPC server and on the outbound side to configuring the performance features of an RPC client. Choose Performance from the Advanced Configuration menu, then choose Server-side performance for inbound configuration or Client-side performance for outbound configuration. The configuration screens are identical to the RPC servers and RPC clients. See Configuring Performance Information for an RPC Client and Configuring Performance Information for an RPC Server for complete descriptions. We strongly recommend that you do not change the agents performance settings without first consulting Customer Support. Configuring the trace file for a messaging agent Choose Tracing from the Advanced Configuration menu to configure the agents error-logging features. The configuration screen is identical to the RPC clients. See Configuring the Trace File for an RPC Client for a complete description. Setting dna.ini variables for a messaging/eventing agent You typically have no reason to edit an agents dna.ini file for messaging or eventing
3-26
Configuring a UNIX Host for Eventing Applications

Eventing configuration prepares a AppBuilder host to run programs that post and receive event data (global eventing) and use triggers (implicit eventing). To configure a host for eventing applications, you must provide information in the following categories: Client configurationidentifies the RPC clients eventing methods Server configurationidentifies the RPC servers eventing methods Agent configurationidentifies the agents protocol and performance information, and its parent in the agent hierarchy
Configuring a UNIX Eventing Client or Server

AppBuilder clients and servers use: Global (explicit) eventingevent-handling logic is embedded in program code Implicit eventingevent-handling logic is embedded in runtime files By default, a UNIX client is configured for global eventing only. To use implicit eventing instead of, or in addition to, global eventing, select Eventing from the client or servers Basic Configuration menu. The Eventing configuration screen is displayed, as shown in Figure 3-22. Choose the eventing feature you want to enable or disable and then respond to the Use eventing_method prompt with a Yes or No answer. If you enable implicit eventing, you must set the [IMPLICIT_EVENTS] event table and trigger table variables, as described in Editing Settings for Eventing.
Figure 3-22 Eventing setup screen
3-27
Editing Settings for Eventing

To configure the eventing client or servers communications configuration file (dna.ini), return to the RPC client or server Configuration menu. Choose dna.ini edit from the menu. The dna.ini file settings screen is displayed, as shown in Figure 3-13. This screen allows you to set any variable in the client or servers dna.ini file, by section. Table 3-3 lists the variables you need to set if you plan to use implicit eventing.
Table 3-3 Section IMPLICIT_EVENTS IMPLICIT_EVENTS Eventing client and server dna.ini variables Variable Event table Trigger table Description Full pathname of the event table. Full pathname of the trigger table. Number of times a client or server looks up a service name in the route table when the same service is a trigger on one host and an action on another. The default is 2: one lookup for the initial invocation, and one additional lookup. Never set the number of event stacks to 0.
IMPLICIT_EVENTS
Event stacks
Configuring the UNIX Eventing Agent

Configuring the eventing agent is identical to configuring the messaging agent, except that you must specify the event subsystem and notification exit for the agent. Choose Basic Configuration from the System Service Agent Configuration menu, then choose Eventing/Messaging from the Basic Configuration menu. You cannot create more than one agent per protocol. The basic configuration menu is displayed, as shown in Figure 3-20. In the basic configuration menu, choose Eventing setup. The eventing setup screen is displayed, as shown in Figure 3-23. You can specify the following eventing configuration information, or accept the defaults: IPC keyshared memory segment used by the agent to store event information. The IPC key is the decimal equivalent of the segments hexadecimal address: 1096, say, for the hexadecimal address 0x448. You can use the UNIX ipcs command to obtain a list of hex addresses already in use. Maximum event viewsnumber of shared memory segments available to the system for global eventing, in addition to the segment specified by the IPC key. The default is 100. Event subsystemsan event notification exit is identified to AppBuilder in a subsystem. Choose Eventing Subsystems from the eventing setup menu, then choose New Subsystem (Create) from the subsystems menu. Enter the following information: Subsystem IDstring that identifies the name of a site-specific event subsystem. The name is passed in the subsystem argument of the dna_RegisterEvent function Notification exitfull path name of the notification exit DLL used by agents to retrieve event information.
3-28
Configuring a UNIX Batch Server
Repeat this procedure to create additional subsystems. You can specify as many event subsystems as necessary; you typically specify a different notification exit for each subsystem. You can also modify an existing subsystem by choosing it from the menu. Notification exits do not have to be present when you configure the client, but must be present at run time. For details on the purpose, use, and coding of notification exits, refer to Chapter 6, Extending Communications. The remainder of the eventing agent configuration is identical to the messaging agent configuration, described in Configuring the UNIX Messaging Agent. In fact, if you have already configured the messaging agent and are satisfied with your choices, the configuration is complete. There is no need for additional configuration, since the eventing agent and messaging agent is always the same.
Figure 3-23 Eventing local setup screen

Batch server configuration prepares a AppBuilder execution server that invokes a single service DLL at run time. The DLL is invoked when the batch server is started, not when a client makes a request. The default configuration does not include a batch server. You can use the procedures in this section to create one or to configure an existing batch server. To create a new batch server, choose New Object (Create) from the NetEssential Objects menu (Figure 3-3), then choose Batch Server in the New Object menu. The screens for a new batch server are identical to those for an RPC client. See Creating a New UNIX Client for Remote Communications for a complete description. When you create a new server, it is best to use the server ID as the name of the server directory.
3-29
To configure a new batch server, choose Configure in the batch server configuration screen that appears when you create a new batch server. To configure an existing batch server, choose the server in the NetEssential Objects menu, then choose Configure in the batch server configuration screen. You can choose to configure basic options, advanced options, or edit dna.ini. The following sections describe the configuration options in each category.
Basic Configuration for Batch Server

Basic configuration lets you specify the DLL to invoke when the batch server is started, and whether the server accesses a database. Choose Basic Configuration from the Batch Server Configuration menu, then choose RPC Remote Proc Call from the Basic Configuration menu. The basic configuration menu is displayed, as shown in Figure 3-24.
Figure 3-24 Batch server basic configuration screen
Enter the following information about the batch server: Databasename of the database that the server accesses (if any) Batch rulefull path name of the service DLL to invoke when the batch server is started
Advanced Configuration for Batch Server

Configuring the advanced features of a batch server is similar to configuring the advanced features of an RPC server. See Configuring Advanced Settings on the Server for a complete description. Setting dna.ini Variables for Batch Server or Gateway You typically have no reason to edit a batch server or gateways dna.ini file.
3-30
Configuring a UNIX Gateway
Configuring a UNIX Gateway

Gateway configuration prepares a AppBuilder server to transparently reroute client requests across protocol 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. To create a new gateway, choose New Object (Create) from the NetEssential Objects menu (Figure 3-3), then choose Gateway Server in the New Object menu. The screens for a new gateway are identical to those for an RPC client. See Creating a New UNIX Client for Remote Communications for a complete description. When you create a new server, it is best to use the server ID as the name of the server directory. To configure a new gateway, choose Configure in the gateway configuration screen that appears when you create a new gateway. To configure an existing gateway, choose the gateway in the NetEssential Objects menu, then choose Configure in the gateway configuration screen. You can choose to configure basic options, advanced options, or edit dna.ini. Configuring a gateway is similar to configuring a forwarding server: you must specify the protocol for inbound and outbound service requests; the host to which outbound service requests are directed; the routing method (dna.ini, route-table, or external name service routing); and so forth. The one difference, of course, is that a gateway always forwards service requests, so you will not be asked if you want the gateway to forward RPCs, nor will you be asked what database the server accesses. See Configuring a UNIX Server for Remote Communications for a complete description.
Configuring a UNIX Database

Database configuration identifies the database your servers access and prepares it for their use. To begin configuring the database, make the following menu selections: 1. 2. Select Database (DBMS) from the NetEssential Objects menu (Figure 3-3). Select Database from the Database Action menu.
The DBMS Type screen is displayed, as shown in Figure 3-25. Database choices vary, depending on the availability of any DBMS on your system. Decide which DBMS you want to configure, and then refer to one of the sections below to continue. Select No Database Configuration if no DBMS is available or if you want to disable database access.
3-31
Completing UNIX Configuration
Figure 3-25
DBMS type screen
Configuring DB2 for AIX

Choose DB2 for AIX from the DBMS Type menu. When the DB2/6000 configuration screen appears, enter the following information, or accept the defaults: Database directoryfull path name of the DB2 active instance; typically, the value of the DB2INSTHOME environment variable. DB2 profilefull path name of the DB2 .profile. DB2 loginfull path name of the DB2 .login file. DB2 databasename of the DB2 database manager.
Configuring Oracle
Choose Oracle RDBMS from the DBMS Type menu. When the Oracle configuration screen appears, enter the following information, or accept the defaults: Oracle directoryfull path name of the Oracle home directory; typically, the value of the ORACLE_HOME environment variable. Oracle ownerUNIX user who owns the Oracle instance used by AppBuilder processes; typically, the value of the ORACLE_OWNER environment variable. Oracle databasename of the Oracle database manager; typically, the value of the ORACLE_SID environment variable.

The configurator creates a startup script for each execution server, agent, batch server, and gateway on the local host. The script is stored in the servers directory area under $HOME/nes_apps.
3-32
By default, all servers, except autostart servers, must be started manually either from the configurator or with the server startup script. If you want a server to start when UNIX is booted, you must add its startup script to your site-specific rc file, such as /etc/rc.0 (HP-UX) or /etc/rc.local (AIX). Refer to your operating system documentation for details on this procedure. Finally, be sure to follow through with these post-configuration tasks: As root, copy new_services_file to /etc/services if you created a new TCP/IP server or modified an existing server ID or port. As root, copy new_inetd.conf_file to /etc/inetd.conf if you created a new autostart server. Use the necfg.as.root utility, in the <home_dir>/nete/bin directory, to update /etc/services and /etc/ inetd.conf at the same time. Run the utility as the user who created or modified the server information, not as root. You must supply the root password before the files are copied, however. If you created or changed any server IDs or ports, be sure to propagate the information to any other host in your network that needs to access the server. If you changed the default port that a TCP/IP agent listens on, for example, you must make sure that other agents know about the change or they wont be able to reach the agent. Similarly, if you created a new execution server, you must make sure that clients can reach the server over the configured port. If the configurator was unable to reach the agent on the parent, you must update the parents subcell table before your system will run properly. You can update the subcell table manually, or you can rerun the configurator after fixing the problem that caused the update to fail. Here are a few reasons why the update may have failed: The agent on the parent machine was not running. The configurator was unable to log in because you didnt provide a valid user name or password. A network error prevented the configurator from contacting the parent. Make sure security and notification exits are installed at the configured locations before run time. See Chapter 6, Extending Communications. Create the MQSeries queue manager if you configured the host for MQSeries messaging. See Chapter 5, Configuring Communications Using MQSeries For external directory service routing, make sure your custom directory service function is installed.
3-33
3-34
CHAPTER
CONFIGURING COMMUNICATIONS ON THE MAINFRAME
This section describes how to use the AppBuilder communications administration utility (admin utility) for mainframes running mainframe CICS. The admin utility provides an easy way to view and edit AppBuilder runtime files, control the MQSeries queue manager, and perform miscellaneous maintenance operations. This section also describes how to set up AppBuilder communications clients for LU2 and LU6.2 connections to mainframe servers, and how to configure mainframe servers for use in messaging and eventing applications. This topic includes: Starting Mainframe Configuration Performing Maintenance Operations Configuring LU2 Clients Configuring LU6.2 Clients Understanding Performance Marshalling
Starting Mainframe Configuration

The mainframe admin utility is a panel-driven application for mainframe CICS. The transaction NEAD (short for NetEssential Administration) allows you to run this application. NetEssential is the name for the AppBuilder communications. The transaction can be found in the sample resource definitions. It runs the program NEADMAIN and the mapset is NEADMAP. Figure 4-1 shows the main panel displayed when you run the NEAD transaction. The following sections describe the menu options.
4-1
Figure 4-1
Admin utility main menu
Viewing and Editing Runtime Files

Options 2 through 6 on the main menu invoke a scrollable display of the data in each runtime file. You can view and edit DNA.INI (the initialization file), the route table, the subcell table, and the trigger and event tables. For each file, a record is limited to one line on the display. Due to space limitations on the display screen, only selected fields are displayed and some fields might be truncated. You can select any record to view in full, modify, or delete. You can also add new records to the file. For example, Figure 4-2 shows a sample display of the Initialization File screen:
Figure 4-2 Initialization file screen
4-2
Configuring Communications on the Mainframe
To VIEW, DELETE, or MODIFY a record, you must select it first by placing an uppercase or lowercase s (S or s) in the area to the records left. The selected record will then be displayed on a panel by itself, which shows all fields in their entirety. If you choose the MODIFY option, you can change the data, as needed. Before any data is actually modified or deleted, however, you must confirm the request by pressing the appropriate PF key. For example, Figure 4-3 shows the panel that would be displayed if you selected the fourth record on the panel above and pushed PF6 for MODIFY:
Figure 4-3 Modifying an initialization value
To use the ADD option, it is not necessary to select a record first. If you do not select a record, a blank panel appears where you can fill in the desired data. If you select a record first, the new record is initialized with the data from the selected record. For all files except the initialization file, new records are added immediately after the selected record, or at the end of the file if no record was selected. For the initialization file, records are stored alphabetically based on the section and variable name. The admin utility operates in much the same way for all other runtime files. There is, however, one feature for the subcell table editor that deserves mentioning. Figure 4-4 shows a sample subcell table menu.
4-3
Performing Maintenance Operations
Figure 4-4
Subcell table screen
Notice the entry consisting of a string of asterisks (*****), right after the AS400-1 entry. The setup utility replaces any line that starts with an asterisk with the asterisk string shown above. Lines beginning with an asterisk have a special meaning in a subcell table. We strongly recommend that you read this appendix before attempting to modify the subcell table. The admin utility makes no attempt to validate data. It is the administrators responsibility to ensure that the data is correct. This is not unlike other AppBuilder communications platforms where the runtime files are plain text files that the administrator can view and change with any text editor.
Performing Maintenance Operations

Option 1 on the main menu invokes the Operations menu shown in Figure 4-5. Maintenance operations include starting and stopping the queue manager; dumping and resetting shared memory; and caching the initialization file. The following sections describe each of these tasks.
4-4
Configuring LU2 Clients
Figure 4-5
Admin utility operations screen
Caching the Initialization File

Option 6 on the Operations menu caches the initialization file (DNA INI) for better performance. This is the same function provided by the DNAINIRD program, which should be run at CICS startup via a PLT entry.
Configuring LU2 Clients

If a client machine requests services from mainframe CICS over LU2, the runtime interpretation of a script file constitutes the connection between the client process and the mainframe. This section describes the delivered logon and logoff script files, which must be customized, and the NetEssential script language.
Initializing the Scripts

Specify in the [LU2] SCRIPT_DIR variable in DNA.INI on the client machine the path to the directory that contains the LU2 logon and logoff scripts. Use the variables [LU2] LOGON_SCRIPT and [LU2] LOGOFF_SCRIPT in the client DNA.INI to identify the files that contain the scripts. The system supplies default logon and logoff scripts named MFLOGON.SCR and MFLOGOFF.SCR, respectively.
Configuring LU6.2 Clients

If a client requests services from mainframe CICS over LU6.2, specify an LU6.2 Mode name in the [LU6.2] MODE_NAME variable in DNA.INI on the client machine.
4-5
Configuring LU2 Terminal Emulator
If the local LU on an OS/2 client is different from the default, set the APPCLLU variable in the config.sys file on the client machine as follows: SET APPCLLU=local LU alias Make sure to specify the local LU alias in lower case. The Communications Manager requires only that LU names be specified in upper case; aliases need not be. If you use Microsoft SNA Server on Windows NT, you must use the default LU. If you use IBM Communications Server, you must set the APPCLLU variable to the local LU alias in the environment settings on the client machine. The value is case-sensitive.
Communications Manager Usage

When overseeing communications between OS/2 and the mainframe, the system cannot cause mainframe CICS to acquire an LU6.2 session. It is your responsibility to set up Communication Manager/2 subsystem management and CICS to acquire a session automatically. For connections to mainframe CICS, make sure to revise the Communication Manager/2 configuration: Use a text editor to open the NDF file. The path to the file is: CM/2_DRIVE_LETTER:\CMLIB\CONFIGURATION_NAME.NDF Add a CNOS entry like this: CNOS LOCAL_LU_ALIAS(MYALIAS) FQ_PARTNER_LU_NAME(PARTLU) MODE_NAME(UCSMOD) SET_NEGOTIABLE(YES) PLU_MODE_SESSION_LIMIT(2) MIN_CONWINNERS_SOURCE(1) MIN_CONWINNERS_TARGET(1) AUTO_ACTIVATE(1);
Save the file and, with the CMLIB directory current, enter this statement at the command line: CMVERIFY CONFIGURATION_NAME
Configuring LU2 Terminal Emulator

To configure the terminal emulator for mainframe communications over LU2, from the Management Console display, click on the icon for the Windows client and select Edit INI from the pop-up menu. This opens the dna.ini file in the INI file editor. Refer to Managing Servers and Gateways in Chapter 2, Configuring and Managing Communications in Windows for an explanation of how to use the INI file editor. Click on the LU2 tab, and select the LU2_IDLL value, as shown in Figure 4-6. In the Value field, select the drop-down menu and select the value. PCSHLL32 is for IBM Personal Communications (PComm). EHLAPI32 is for NetManage Rumba (Rumba). ACS3EHAP is for Attachmate EXTRA! (Extra). Click OK when done.
4-6
Understanding Performance Marshalling
Figure 4-6
Selecting the terminal emulator for LU2
Click the LU2 tab.
Click the LU2_IDLL value.
Click the drop-down menu and select a value.

In general, marshalling is the process by which local data is converted into data for another environment in a distributed system and packaged for transmission to that environment. Thus, marshalling involves the conversion of data types and code pages between environments. In AppBuilder, this typically means converting between workstation ASCII data and mainframe EBCDIC data for transmission of data between these environments. Applications distributed over heterogeneous networks often have unique data-handling requirements, because the architectures or operating systems on which they run manage memory and data in different ways. Intel- and RISC-based systems represent bytes in inverted order (little-endian versus big-endian as shown in Figure 4-7).
Figure 4-7 Byte-order data conversion
Some systems require alignment bytes; some do not. Converting incompatible data types in program code is inconvenient and error-prone. In the typical case, you need to anticipate the possibility that platform-specific code may make programs non-portable to other systems.
4-7
The AppBuilder marshalling feature handles data conversion for you. It resolves incompatibilities between data definitions across systems by converting a representation specific to the sending platform to a platform-independent AppBuilder representation and then to a representation specific to the receiving platform. Where data translation is inappropriate, it supports the transmission of opaque, or untranslated, data. You can also use the feature to create custom data types in cases where data need to be manipulated between platforms for security or other reasons. AppBuilder marshalling handles byte-order and ASCII-to-EBCDIC conversions, and accounts for alignment bytes as necessary. Conventional support is provided for code-page conversions and single-byte and double-byte character sets. Code-page conversion is typically performed on the server, but administrators may use the routing mechanism to specify that conversion take place on clients. AppBuilder data types are based on the External Data Representation (XDR) for network representation of standard data types, enhanced for self-describing data. AppBuilder supports transmission of binary large objects (BLOBs) as native data types.
Performance Marshalling for CICS

AppBuilder handles full marshalling at the workstation so that the resource usage on the mainframe (CICS only) for marshalling is reduced. Since the client marshals the data to the format that the mainframe is expecting, the processing time in CICS to unmarshal the data is reduced, thus optimizing performance and reducing cost. This is why we refer to the process as performance marshalling. Performance marshalling is only valid when communicating with CICS on the mainframe. It is configured on the client side by specifying any of the protocols summarized in Table 4-1. The advantage of performance marshalling is the reduction of mainframe processing time. The trade-off is that there can be an increase in the amount of data being sent from the client. For example, variable character (VarChar) fields are fully expanded during marshalling. If the network bandwidth is more of an issue than CICS processing time, and if there are a large number of VarChar fields used in the views, then performance marshalling could actually increase the amount of network traffic. The client also must be configured to use the mainframe code page. The Java client only supports TCPIP. This allows Java applications to talk directly to CICS via TCPIP.
Table 4-1 Performance marshalling protocols Description Performance marshalling protocol for LU2 messages from a C client to a COBOL host in CICS on the mainframe. It is used to call CICS rules prepared with AppBuilder. Performance marshalling protocol for LU6.2 messages from a C client to a COBOL host in CICS on the mainframe. It is used to call CICS rules prepared with AppBuilder. Performance marshalling protocol for TCP/IP messages from a Java or C client to a COBOL host in CICS on the mainframe. It is used to call CICS rules prepared with AppBuilder. Performance marshalling protocol for TCP/IP messages from a Java client to a COBOL host in CICS on the mainframe for OpenCOBOL. It is used to call CICS rules using OpenCOBOL. Performance marshalling for OpenCOBOL is not available for C clients. In the DNA.INI under the DNA section the following must be added to send over 64k successfully. PERMORMANCE_MARSHALLING_VERSION=2
Protocol name PMLU2
PMLU62
PMTCPIP
POTCPIP
Note
OpenCOBOL rules and runtime-managed-COBOL rules must be marshalled and invoked differently. Because of these differences, a particular CICS region should only have one type of generated COBOL.
4-8
For OpenCOBOL you must set the time and date delimiters in the dna.ini file. Refer to the Road Map to OpenCOBOL for instructions.
Check Setting
You must have the value of DYNAMIC_DATA_OPTIMIZE set to Y (the default value) in the communications configuration file, dna.ini. AppBuilder uses performance marshalling to optimize the sending of data and if you set this value to N, performance marshalling fails. To edit the dna.ini file, use the Management Console. Refer to Editing the Configuration File in Chapter 2, Configuring and Managing Communications in Windows.
4-9
4-10
CHAPTER
CONFIGURING COMMUNICATIONS USING MQSERIES
One of the many ways that AppBuilder provides extended connectivity for applications that run on multiple architectures in an enterprise is with MQSeries RPC support. This enables AppBuilder generated Java programs to make remote rule calls using JMS (Java Messaging Service) to a mainframe running MQSeries. This topic includes: Understanding MQSeries RPC Operation Meeting Prerequisites for MQSeries RPC Configuring MQSeries RPC The typical configurations of MQSeries RPC are shown in Figure 5-1.
Figure 5-1 MQSeries RPC configurations
Understanding MQSeries RPC Operation

The data from the Java rule (views and fields) become a message that is put on a queue using JMS. This message is then transmitted to the mainframe AppBuilder Input Queue managed by a Queue Manager connected to CICS. The incoming message triggers the AppBuilder MQ Processor that moves the message from the AppBuilder Input Queue to the AppBuilder Process Queue and the appropriate transaction (rule) is executed. The rule reads the data from the AppBuilder Process Queue and writes data to an Output Queue. The name of the Output Queue and Queue Manager are provided in the incoming message in the ReplyTo Queue and ReplyToQueueManager fields as part of the header.
5-1
Understanding MQSeries RPC Operation
Figure 5-2
Queue management process
Referring to the numbered steps in Figure 5-2, here is what occurs: 1. 2. The JMS client writes a message to the queue. This may be a local or remote queue. The message is transmitted to the Input Queue managed by the Queue Manager connected to CICS. The incoming message causes the IBM-supplied Trigger Monitor for CICS (Transaction ID CKTI) to invoke the AppBuilder MQ Processor (DNALSTMQ). In an effort to increase performance, this should be defined as TRIGGER=FIRST, as the AppBuilder MQ Processor waits for a configurable time-out for the next message. The AppBuilder MQ Processor moves the message to a Process Queue within a Logical Unit-of-Work (LUW) to ensure it is copied and deleted. The message is browsed and the relevant user information (user ID, password, transaction-ID, etc.) is extracted. Based on the extracted information, the AppBuilder MQ Processor starts the user application (the rule), passing it the necessary information so it knows which message (messageID) from which queue (Process Queue) to process. When requested, the AppBuilder Run-Time (MQ Run-Time) reads the data in the Process Queue. The output of the application is written to the Output Queue. The details (Queue Manager name, Queue name, etc.) are provided in the incoming message. The Output Queue may be a local or remote queue. The message is transmitted to the Response Queue requested by the client program. Typically this is the same Queue Manager it is connected to, from which the request originated.
3.
4.
5. 6. 7.
Remember: All messages that the AppBuilder MQ Processor cannot process should be moved to a (configurable) dead-letter queue. The moving of the messages from the Input Queue to the separate Process Queue ensures that each message gets processed once and only once. Thus, messages remaining in the Process Queue for too long probably indicates a problem. This is straight-forward and simple to monitor. The level of security, whether a verification based on user ID and password sent by the client is done, can be set using the setting LISTEN_SECURITY in the configuration file dna.ini. (Refer to Customize Mainframe INI File.)
5-2 Configuring Communications Using MQSeries
Meeting Prerequisites for MQSeries RPC
Meeting Prerequisites for MQSeries RPC

Before you can use the MQSeries RPC, you must have the following software on these machines: On Mainframe (CICS) On the mainframe in the CICS region, you must have the IBM MQSeries CICS Adapter with an initiation queue and CKTI running. For more information about the IBM MQSeries CICS adapter, refer to Part 3. MQSeries and CICS in the MQSeries for OS/390 System Management Guide by IBM. That guide contains details on how to set up, customize, and operate the CICS Adapter. It is available in electronic form on the IBM Web site. (Refer to our Customer Service Web site for a link.) On MQ Server On the MQ Server, you must have IBM MQSeries V5R2 with MQSeries Support Pac MA88 (which includes MQSeries classes for Java that add JMS support to MQSeries). For more information on this software, refer to MQSeries classes for Java and MQSeries classes for Java Message Service. This is available in electronic form on the IBM Web site. (Refer to our Customer Service Web site for a link.) On Java Workstation The following JAR files, which are part of the MA88 Support Pac installed on the server, must be in the classpath environment variable: com.ibm.mqjms.jar com.ibm.mq.jar jms.jar
Configuring MQSeries RPC

The configuration includes: Collect Setup Information Configure AppBuilder Server Configure MQ Server Configure Mainframe MQ Series Customize Mainframe INI File
Collect Setup Information

The following information is needed to setup and configure MQSeries RPC for Appbuilder. Blank lines are provided for you to enter the information. (A) (B) (C) Mainframe host name: ____________________ Mainframe Queue Manager name: ________________________ Mainframe CICS Initiation Queue name: ________________________
5-3
(D) (E) (F) (G) (H) (I) (J) (K) (L) (M) (N) (O)
Mainframe AppBuilder Input Queue name: ________________________ Mainframe AppBuilder Process Queue name: ________________________ Mainframe AppBuilder Reply Queue name: ________________________ Mainframe AppBuilder Dead-Letter Queue name: ________________________ Server host name running MQSeries Queue Manager: ________________________ Server Queue Manager name: ______________________ Local transmission queue on server for outgoing messages: ___________________ Local queue for remote messages: _______________________________ Channel name from server to mainframe: __________________________ Local queue name on the server for incoming messages: _________________________ Channel name from mainframe to server: __________________________ Channel name on server for JMS messages: _________________________
On the Server sending side, the following needs to be defined: Local transmission queue for outgoing messages Remote queue where the messages are sent Channel to the mainframe Queue Manager Local queue for the incoming messages Channel from the mainframe Queue Manager Channel for JMS messages
Configure AppBuilder Server

The method for invoking remote rules is controlled in the appbuildercom.ini file. For MQSeries RPCs, this file can be configured to contain the information needed by JMS to make the RPC call using MQ or to point to a JNDI that then contains this information. The values in appbuildercom.ini that can be configured are summarized in Table 5-1. Examples are given in Example appbuildercom.ini Settings.
Table 5-1 Value MQ_QUEUE_MANAGER MQ_CHANNEL MQ_SEND_QUEUE MQ_RECV_QUEUE MQ_HOST_NAME MQ_PORT MQ_CODEPAGE MQ_SERVERID MQ_PROTOCOL MQ_TIMEOUT AppBuilder server settings Description Name of server MQSeries Queue Manager Channel defined on the Server used by JMS Queue on Server used to send messages to the mainframe Queue on Server where messages from the mainframe arrive MQSeries Server name Port that the MQSeries server is listening on. Default MQ Series value is 1414 Code page on the mainframe Unique identifier for this server JMS or PMJMS. PMJMS is the performance marshalling feature that marshals the view data on the client Time in seconds a rule waits for a response from the mainframe
5-4
Configuring Communications Using MQSeries
Example appbuildercom.ini Settings The following example shows a portion of an appbuildercom.ini without using JNDI. [SERVER.JMS] TYPE=JMS MQ_QUEUE_MANAGER=QM1 MQ_CHANNEL=JMS.CHANNEL MQ_SEND_QUEUE=AB.SENDQ MQ_RECV_QUEUE=AB.RECVQ MQ_HOST_NAME=hostname MQ_PORT=1414 MQ_CODEPAGE=IBM037 MQ_SERVERID=JMSRPC MQ_PROTOCOL=JMS MQ_TIMEOUT=0
(I) (O) (K) (M) (H)
The following example shows a portion of an appbuildercom.ini that uses JNDI to store the information needed by JMS. [SERVER.JMS] TYPE=JMS JMS_INITIAL_CONTEXT_FACTORY=com.sun.jndi.fscontext.RefFSContextFactory JMS_PROVIDER_URL=file:/C:/JNDI-Directory MQ_CODEPAGE=IBM037 MQ_SERVERID=JMSRPC MQ_PROTOCOL=JMS MQ_TIMEOUT=0 If JNDI is being used, then the MQ JMS Administration tool must be used to define a MQQueueConnectionFactory with the name 'AppbQCF' and two MQQues named 'AppbSendQ' and 'AppbRecvQ'. The MQ JMS Administration tool is supplied with MQSeries and is documented in the MQ Series Using Java manual (SC34-5456-02) available at IBMs Web site. A sample of the definitions required are: def qcf(AppbQCF) qmanager(QM1) transport(client) hostname(hostname) channel(JMS.CHANNEL) port(1414) def q(AppbSendQ) qmgr(QM1) queue(AB.SENDQ)
The routing section can be updated to use the new server. [ROUTES] ; $ANY specifies the default server entry for all remote rules $ANY=JMS
Configure MQ Server
To configure the MQ Server, several definitions must be configured. The following definitions can be used; customize the values for your environment. The letters in parentheses correspond to the values you should have obtained from Collect Setup Information. DEFINE QLOCAL('AB.SENDQ.XMIT') + (J) DESCR('AppBuilder transmit queue for MQSeries RPCs') +
5-5
USAGE(XMITQ) REPLACE
DEFINE QREMOTE('AB.SENDQ') + (K) DESCR('Remote AppBuilder queue for MQSeries RPCs') + RNAME('CICS02.ABMQ.INPUTQ') + (D) RQMNAME(CSQ) + (B) XMITQ('AB.SENDQ.XMIT') + (K) REPLACE DEFINE CHL('QM1.CSQ.TCP') + CHLTYPE(SDR) + TRPTYPE(TCP) + CONNAME(TREX) + XMITQ(AB.SENDQ.XMIT) + REPLACE (L)
(A) (J)
DEFINE QLOCAL(AB.RECVQ) + (M) DESCR('AppBuilder queue to receive from Mainframe') REPLACE DEFINE CHL(CSQ.QM1.TCP) + CHLTYPE(rcvr) + TRPTYPE(TCP) + REPLACE (N)
DEFINE CHL('JMS.CHANNEL') + (O) CHLTYPE(SVRCONN) + TRPTYPE(TCP) + MCAUSER(' ') + DESCR('Channel for AppBuilder JMS Messages') REPLACE
Configure Mainframe MQ Series

To configure the mainframe MQ Series, several definitions must be configured. The following definitions can be used; customize the values for your environment. The letters in parentheses correspond to the values you should have obtained from Collect Setup Information. DEFINE QLOCAL(CICS02.ABMQ.DEADLETTERQ) + (G) DESCR('AppBuilder Dead-Letter Queue') + REPLACE DEFINE QLOCAL(CICS02.ABMQ.REPLYQ) + (F) DESCR('AppBuilder Reply Queue - Local') + REPLACE DEFINE QLOCAL(CICS02.ABMQ.PROCESSQ) + DESCR('AppBuilder Process Queue') + REPLACE DEFINE QLOCAL(CICS02.ABMQ.INPUTQ) + DESCR('AppBuilder Input Queue') + (E)
(D)
5-6
PROCESS(DNALSTMQ) + INITQ(CICS02.INITQ) TRIGGER + TRIGTYPE TRIGDPTH TRIGMPRI REPLACE DEFINE CHL(QM1.CSQ.TCP) + CHLTYPE(rcvr) + TRPTYPE(TCP) + REPLACE
+ (FIRST) + (1) + (0) +
(C)
(L)
DEFINE QLOCAL(QM1) + DESCR( 'Xmit Queue to QM1' ) + USAGE( XMITQ ) + REPLACE DEFINE CHL(CSQ.QM1.TCP) + CHLTYPE(SDR) + TRPTYPE(TCP) + CONNAME(HOSTNAME) + XMITQ(QM1) + REPLACE DEFINE PROCESS(DNALSTMQ) DESCR('AppBuilder APPLTYPE(CICS) APPLICID(NETQ) REPLACE + MQ Processor') + + +
(I)
(N)
(H) (I)
With regard to the definition for the AppBuilder MQ Processor, consider the following: The process name 'DNALSTMQ' must match the process name specified in the definition for the AppBuilder Input Queue (CICS02.ABMQ.INPUTQ). The APLICID, in our case 'NETQ', is the actual CICS transaction ID that should point to the supplied AppBuilder program 'DNALSTMQ'. Both the program ('DNALSTMQ') and transaction ID ('NETQ') must be defined to CICS. See the sample definitions. Here are some sample definitions for CICS. DEFINE PROGRAM(DNALSTMQ) GROUP(gggggggg) DESCRIPTION('AppBuilder MQ Processor') LANGUAGE(C) RELOAD(No) RESIDENT(Yes) USAGE(Normal) DATALOCATION(Any) EXECKEY(User) DEFINE TRANSACTION(NETQ) GROUP(gggggggg) DESCRIPTION('AppBuilder MQ Processor') PROGRAM(DNALSTMQ) TWASIZE(00000)
5-7
PROFILE(DFHCICST) STATUS(Enabled) TASKDATALOC(Any) TASKDATAKEY(User)
Customize Mainframe INI File

It is possible to customize AppBuilder MQ for performance and configuration. You may use the standard AppBuilder mechanisms and tools to maintain the DNA INI settings. The AppBuilder MQ settings are in the MQMSG section of the mainframe DNA INI. The following entries must be added to the mainframe DNA INI file using the NEAD transaction: MQMSG MQMSG MQMSG MQMSG MQMSG MQMSG MQMSG MQMSG MQMSG DEADLETTER_QUEUENAME DEBUGLVL DLQ_FORWARD LISTEN_SECURITY LISTEN_TIMEOUT MAX_MESSAGE_LENGTH PROCESS_QUEUE_EXPIRY PROCESS_QUEUENAME REPLY_QUEUENAME (G) 0 DEFAULT YES 30 80000 (E) (M)
The following provides a detailed description of the possible settings for AppBuilder MQ. DEADLETTER_QUEUENAME Possible Values Default Value Valid (existing) queue name ABMQ.DEADLETTERQ
This specifies the name of the queue to which unprocessable messages are forwarded. Messages that cannot be processed may be forwarded to this queue for investigation. By default, if a reply message was successfully generated to notify the client, messages are not forwarded. (They are deleted.) It is possible to force or suppress the forwarding of messages to this dead-letter queue. See DLQ_FORWARD for details. DLQ_FORWARD Possible Values YES, NO, or blank
Default Value blank (This means delete if the reply was successfully generated, otherwise forward to the dead-letter queue.) This either forces or suppresses forwarding unprocessable messages to a dead-letter queue. This forwarding occurs when sending the error reply message to the client was unsuccessful. If successful, the unprocessable message is deleted. This default behavior can be customized via this parameter. If an error message cannot be returned to the client, the message is forwarded to the dead-letter queue, unless it is set to NO. Specify NO to suppress and YES to force the message to be forwarded to the dead-letter queue, as specified in the DEADLETTER_QUEUENAME parameter.
5-8
LISTEN_SECURITY Possible Values Default Value YES, NO, or PART YES
Indicates the required level of user verification. YES implies that the incoming user ID and password are verified. By specifying PART (partial), no verification is done, but the transaction is started with the incoming user ID. NO causes the user identifier to be ignored and not used. LISTEN_TIMEOUT Possible Values Default Value Positive number (seconds) 30
Specifies timeout for the AppBuilder MQ Listener to wait for a new message to arrive on the input queue. In order to avoid the overhead involved with starting the AppBuilder MQ Listener transaction for every message, after initial invocation the Listener waits the specified number of seconds for a new message. If none arrive, the Listener terminates. MAX_MESSAGE_LENGTH Possible Values Default Value Positive number (bytes) Queue definition/100,000
Specifies the size of buffers to allocate for messages. MQSeries messages can be up to 4 MB. However, most application's message size is much lower. To reduce unnecessary storage, use this parameter to specify the size of buffer to allocate. If not specified, the maximum-message-size value specified for the (input) queue is used. If inquiring of the queue's attributes are unsuccessful, a default of 100 KB is used. PROCESS_QUEUE_EXPIRY Possible Values Default Value Number (seconds) or blank blank (delete messages)
The AppBuilder MQ Listener forwards messages from the input queue to the Process Queue for processing by the rule's transaction. These operations are committed, causing the message to be deleted from the Input Queue. If errors occur starting the transaction, these messages potentially remain in the process queue forever. By default the AppBuilder MQ Listener deletes the message from the process queue if a reply error message is successfully generated to notify the client. Specifying a negative number or zero implies unlimited expiration (that is, it does not expire), whereas any positive number is used as an expiration period - in seconds - for messages in the Process Queue. An empty or blank value results in the default behavior and the message is deleted. PROCESS_QUEUENAME Possible Values Default Value Valid (existing) queue name ABMQ.PROCESSQ
The queue used for forwarding messages to be processed by the rule's transaction.
5-9
Handling Errors in MQSeries
REPLY_QUEUENAME Possible Values Default Value Valid (existing) queue name ABMQ.REPLYQ
Generally, the incoming message (in the header) contains a value in the ReplyTo Queue and ReplyToQueueManager fields, specifying the appropriate values to be used for the reply messages. If the ReplyToQueue was not specified in the incoming message, the value in this parameter is used. DEBUGLVL Possible Values "ERRORS" or "0", "ERRORS_AND_LENGTHS" or "1", "ERRORS_AND_DATA" or "2", "ERRORS_AND_TRACES" or "3" "ERRORS" or "0"
Default Value
This sets the debug and trace level to assist troubleshooting AppBuilderMQ Listener related problems. This is used in conjunction with the global setting in the TRACING section. The values specified are compared and, if the AppBuilder MQ Listener's level is not lower, debug trace messages are output. Table 5-2 summarizes when the trace messages are output based on the two debug level settings: this one in the MQMSG section and one in the TRACING section. This allows the AppBuilder MQ Listener trace to be forced or suppressed separately from (though configured in conjunction with) the global setting.
Table 5-2 Trace Messages Output Cases [TRACING] DEBUGLVL Values 0 No No No Yes 1 No No No Yes 2 No No No Yes 3 Yes Yes Yes Yesa
DNA INI Section [MQMSG] DEBUGLVL Values 0 1 2 3
a. This is the only case that produces the AppBuilder MQ Started trace message.
Handling Errors in MQSeries

When certain errors are detected while processing the incoming message, the AppBuilder MQ Listener attempts to rollback (syncpoint rollback) all operations, including MQSeries. After this, the Listener terminates. By far, the most common errors to cause a rollback are those detected when forwarding a message to the dead-letter queue. If this is the only message in the input (trigger) queue, such rollbacks cause MQSeries to consider this as a "new" message. As such, the AppBuilder MQ Listener is restarted. It encounters the same error(s), rollback and terminate, and is restarted. This happens repeatedly, endlessly, until another message is put on the queue or the Listener is stopped. One way to minimize this is to ensure that the dead-letter queue name and option are correctly set. There are DNA INI settings that affect the AppBuilder MQ Listener error handling and dead-letter queue configuration. Refer to Customize Mainframe INI File.
5-10
CHAPTER
EXTENDING COMMUNICATIONS
An exit is a program external to an application that performs some task specific to a security subsystem, directory services mechanism, DBMS, or operating system. When AppBuilder communications detects an exit, it leaves the application (exits) to execute the external program. The interruption in the processing flow of the application allows system-specific processing to take place. AppBuilder communications provides the necessary open interfaces to external products. You can perform many tasks that are usually specific to a given platformsecurity, directory services, database access, and data marshallingwithout compromising the overall platform-independent nature of your application. While the interfaces are packaged in different formats, each is simply an easy way to do system-dependent coding outside your application. This topic describes how to extend AppBuilder communications to accomplish these tasks in the Java application environment: Communication Exits in Java
This topic also describes how to extend AppBuilder communications to accomplish these tasks in the C application environment: Security Exits in C - how to use external security Directory Services Exits in C - how to use directory services Database Exits in C - how to access unsupported database management systems Customized Data Types in C - how to handle customized data types
In C, communications exits are implemented in two formats: The authentication, authorization, tracing, and password encryption exits are implemented in dynamic link libraries (DLLs) whose presence AppBuilder communications detects at run time. Templates and make files for the exits are provided with the product. You customize the templates and compile them for the client or server platforms they execute on. The data encryption, directory services, and open database interconnection exits are made available in shared libraries that are already linked to AppBuilder communications. You customize the shared library for the task you want to perform, rebuild the library, and substitute it for the library supplied with the product.
Regardless of the format, each exit has an entry point whose name is recognized at run time. For example, the entry point for the client authentication exit is called AuthentLibMain. This topic assumes knowledge of the C programming language. References to dna in the product (typically in file names and command prefixes) are to the abbreviation of its former name, Dynamic Network Architecture.
6-1
Communication Exits in Java
Implementing Communications Exits

AppBuilder has several communications exits that can be used in Java clients. There is a Java class in the <AppBuilder>/JAVA/RT directory. It is a sample Java class to be used for implementing communication exits for Java clients. A listing is given in Sample Java Class for Exits. To implement a communications exit for a Java client, you must modify a special Java class, compile it with the Java compiler, and place the resulting Java class file in the Java classpath. In addition, you must modify the appbuildercom.ini file to indicate the name of the Java class which contains the exit logic. These steps are explained in detail in Implementing Communications Exits. The Java class that provides the exit logic must extend the NeteClientExit class. The class below is a sample Java class which does just this. This file contains the definition of the Login class, which provides logic for the following communications exits in the indicated methods: Authentication getLoginInfo() Authorization isAuthorised() Encryption (password only) encryptPasswd() Decryption (password only) decryptPasswd() RPC End RpcEndStatus() Encoding/Compressing Data encodeData() Decoding Data decodeData()
You can rename this file. However, if you rename it, you must also modify the name of the Java class it contains. For example, if you change the name of the file to "UserExitExample.java", you must change the name of the Java class to UserExitExample. For more information on authentication exits, refer to: Authentication Overview Authentication Settings
Implementing Communications Exits

Assuming that you have renamed the file and the Java class as indicated above, here are the steps required to implement communications exits for Java clients: 1. 2. Modify one or more of the methods in the UserExitExample class (listed above) to provide the appropriate exit logic. Compile this file using the Java compiler (javac). The easiest way is to open a command window, switch to the directory that contains this file, and run the following: javac UserExitExample.java If there are no errors in the logic you have provided, the Java compiler will generate the file UserExitExample.class and place it in the current directory. When you execute the javac command at a DOS prompt, if there are no errors, it returns to a command prompt with no indication that anything has happened even though the file was compiled. 3. Place the resulting UserExitExample.class in a directory that is in the Java classpath. (If you have left UserExitExample.java in the <AppBuilder>\JAVA\RT directory, it is already in the classpath, since that directory is automatically added to the classpath by the AppBuilder installer.)
6-2
Extending Communications
Authentication Overview
4.
Finally, modify the GENERAL section of appbuildercom.ini (located by default in <AppBuilder>\JAVA\RT) to specify the Java class names for the exits. In our example you would specify: [GENERAL] USER_EXITS=UserExitExample
Authentication Overview
The AppBuilder currently allows user authentication with the following: QUERY_AUTHENTICATION_ON_STARTUP - an INI setting that can be enabled to prompt a dialog at startup to enter the user identifier and password. QueryUserAuthentication an ObjectSpeak method on the Rule, that throws up a logon dialog for the user identifier and password. SetUserAuthentication an ObjectSpeak method on the Rule to set the user identifier and password programmatically. NetEssential Exit An external exit program is invoked during the remote rule call and this can return a vector of triplets (target system, user identifier, and password). If a remote rule call is made to a workstation defined in this vector, the given triplet is used. If the target workstation is not found in the vector, AppBuilder uses a user identifier and password with a null workstation from the vector if given. If no such triplet is defined, it uses the user identifier and password given through one of the above methods. When there is no valid triplet and no input from the Rule, then a null user identifier and password is sent to the remote rule.
Default Authentication
With default authentication, use the ObjectSpeak methods SetUserAuthentication and QueryUserAuthentication. The SetUserAuthentication exit applies to the entire Java platform for a particular session, the entire session, with a system level call. The QueryUserAuthentication exit brings up a dialog, so it is only supported on the Java client. The values can be null (blank). This results in an absence of authentication, and thus no authentication information (user ID and password) is sent to the remote server. Refer to the ObjectSpeak Reference Guide in the section on the Rule object for details on these methods.
Authentication Exit
Call an authentication exit to get a vector of LoginInfo objects each containing a ServerName (the server name), UserID (the user identifier), and Password (a password). Call a Java class and provide a vector with these three. Each time a remote rule is called, AppBuilder calls the user exit specified in the appbuildercom.ini file to retrieve this list. From this list, and the specified default authentication it selects the authentication to use for a specific server. This call applies to all sessions. (There is no way to specify a particular session.) The user exit Java class is specified in the appbuildercom.ini file. The way AppBuilder handles authentication is to first determine on which server a particular rule is running. Looking in the ROUTE section of the appbuildercom.ini file, it can find out the name of the server. Then it looks for that server name in the SERVER section to see how authentication is set (with user ID and password). It looks for specific authentication in the vector if there is a match of the server name. If not set, it uses the Default Authentication (see above). If not in the list, it sets it to blank, or no authentication. The values can be null (blank). This results in an absence of authentication, and thus no
6-3
Authentication Settings
security. For the log-in vector, it is possible to have the server name with a user ID and password set to null.
Implementation Differences
There are several configurations possible in Java. These include thick Java clients running with EJBs and thin HTML clients running with servlets. The way authentication is specified is different for each. For Thick Client (EJBs) For Enterprise Java Beans (EJBs) in multi-tier systems, where a client calls a server that calls a higher server, use the communications exit to specify authentication. Specify the servers by name and the user ID and password for each server. Once the system finds authentication for the first server, that becomes the default for that server and it goes to the next level server. For Thin Clients (HTML) For thin HTML clients and servlets only, use default authentication because you can set user (session) specific security.
Authentication Settings
A new AppBuilder INI setting AUTH_TYPE will be introduced which can take the following values: DIALOG Setting EXIT Setting NONE Setting There are three mechanisms for setting up authentication in developing Java applications. The first is default authentication using Java client (ObjectSpeak) methods. The second is the authentication exit in the internal communications of AppBuilder. The third is no authentication at all.
DIALOG Setting
When it is set to DIALOG, if a QueryUserAuthentication is invoked, it will prompt for a logon dialog and will set a triplet (null, user identifier, and password) in the root context for the application and this will get used in all remote rule calls. The same triplet also can be set through the SetUserAuthentication. If both SetUserAuthentication and QueryUserAuthentication are not invoked until the remote rule call, instead of invoking the NetEssential Exit, a logon dialog will be displayed to enter the same triplet. Moreover, this vector will be cached for reuse on all subsequent remote rule calls. This vector can be refreshed with an explicit QueryUserAuthentication or SetUserAuthentication call. The DIALOG could be used on the Java client to prompt for the user identifier and password. For thin-client or gateways, the DIALOG does not make sense to use because you would not want a dialog to appear on the server. However, if it is set to DIALOG in those environments, AppBuilder prompts a dialog to get the user identifier and password.
6-4
Sample Java Class for Exits
EXIT Setting
If AUTH_TYPE is set to EXIT, QueryUserAuthentication will invoke the NetEssential Exit. The exit can return a vector of triplets that will be saved with the Root context for the application and all the remote rule calls will use the appropriate triplet. The SetUserAuthentication method can be invoked any time to reset the existing (null, user identifier, password) triplet. If the user authentication has not taken place prior to the remote rule call, the NetEssential Exit will be invoked to get the vector of triplets. The vector will be cached and reused on all subsequent remote rule calls. The vector can be changed with an explicit QueryUserAuthentication or SetUserAuthentication from the Rule. This is the default. If there is a requirement to use a combination of Dialog and Exit, the AUTH_TYPE should be set to EXIT and within the exit program, a custom Java dialog class or the following AppBuilder Java classes could be used to get the user identifier and password, as shown in the Example. Example public class AbfLoginDialog extends JDialog { /** a constructor */ public AbfLoginDialog(JFrame userFrame); /** method displays a logon dialog and returns the user identifier and password entered or null if canceled. */ public LoginInfo showDialog(); } public class LoginInfo implements Serializable { /** a method to get the login name as string public String getUserId(); /** a method to get the password as string public String getPassword(); }
*/
*/
NONE Setting
The value of NONE can be used for a quick Development/Testing of the application with no authentication or a null triplet (null, null, null). A SetUserAuthentication can still be invoked to set a (null, user identifier, and password) triplet when AUTH_TYPE is set to NONE and this will be the triplet used in all remote rule calls.

Here is a listing of the sample Java class. */ import appbuilder.nete.*; import java.util.*; public class UserExitExample extends NeteClientExit {
6-5
// Authentication exit protected Vector getLoginInfo() { // This authentication set within appbuilder rules using // the default login dialog or the SetUserAuthentication function // is the default LoginInfo. // // This vector overrides this setting on a per server basis /* String serverId, userName, passwd; Vector m_logins = new Vector(2); // serverName is specified in the AppBuilderCom.ini : // [SERVER.<server>] section // as SERVERID // a null or blank server name indicates the default server serverId userName passwd = "pcio"; // refers to SERVERID // in the [SERVER.nete] section = "aUser"; = "somePassword";
m_logins.add( new LoginInfo( serverId, userName, passwd ) );
serverId userName passwd
= null; // for all other systems = "anotherId"; = "somePassword";
m_logins.add( new LoginInfo( serverId, userName, passwd ) );
return m_logins; */ // return reference to vector containing one or more login // information structures return null; }
// Authorisation exit protected boolean isAuthorised( AuthoriseArg arg ) { // SAMPLE CODE
6-6
// ) == 0 ) // == 0 ) ) // // //
if ( (arg.getStatus().gettargetMachine().compareTo( "nysvr" && (arg.getStatus().gettargetServerId().compareTo( "nete" ) { return true; }
// return true if authorized, false otherwise return true; }
// Encryption exit protected String encryptPasswd( String arg ) { // // // // } SAMPLE String String return CODE unencryptedPassword = arg; encryptedPassword = // do encryption here encryptedPassword;
// Decryption exit protected String decryptPasswd( String arg ) { // // // // SAMPLE String String return CODE encryptedPassword = arg; encryptedPassword = // do encryption here decryptedPassword
return arg; }
// RPC End exit protected void RpcEndStatus( RpcEndExitArg arg ) { // provide logic here }
// Encoding Data/Compressing exit protected DataBuffer encodeData( DataBuffer inBuf ) { // SAMPLE code - begin // // create a new output DataBuffer object; // DataBuffer is just a wrapper class for the // byte buffer with start index and the buffer length.
6-7
// // public // public // public // public // public // public // // // // // //
void DataBuffer( ) a default constructor void DataBuffer( int len ) a new byte buffer is allocated for the given length void init( byte[] buf ) uses the given buffer, start=0 and length=buf.length byte[] getBuffer() returns the current buffer int getStart() returns the start index int getLength() returns the buffer length
byte[] encodedBuf = new byte[32760]; invoke the encode method with inBuf info, start index should be used because the buffer might have data which should not be encoded. int len = encodeMethod( inBuf.getBuffer(), inBuf.getStart(), inBuf.getLength(), encodeBuf );
// // DataBuffer outBuf = new DataBuffer( ); // outBuf.init( encodedBuf, 0, len ); // // return outBuf; // // SAMPLE CODE - end return null; }
// Decoding Data exit protected DataBuffer decodeData( DataBuffer inBuf ) { // SAMPLE code - begin // // create a new output DataBuffer object; // DataBuffer is just a wrapper class for the // byte buffer with start index and the buffer length // Following are the public methods in DataBuffer... // // public void DataBuffer( ) a default constructor // public void DataBuffer( int len ) a new byte buffer is allocated for the given length // public void init( byte[] buf ) uses the given buffer, start=0 and length=buf.length // public byte[] getBuffer() returns the current buffer // public int getStart() returns the start index // public int getLength() returns the buffer length //
6-8
Custom Transport in Java
// byte[] decodedBuf = new byte[32760]; // invoke the decode method with inBuf info // int len = decodeMethod( inBuf.getBuffer(), inBuf.getStart(), inBuf.getLength(), decodedBuf ); // // DataBuffer outBuf = new DataBuffer( ); // outBuf.init( decodedBuf, 0, len ); // // return outBuf; // // SAMPLE CODE - end return null; }

Java client applications can invoke remote rules through various protocols incluing NetEssential, MQ, RMI, EJB and Web Services. The AppBuilder provides support for handling the communication when any one of the above mentioned protocols are used. There might be situations where a different protocol needs to be used to go against a third-party server application. AppBuilder provides a Custom Transport feature to handle these unsupported protocols. The AppBuilder client can be configured to invoke an external Java class, which provides an implementation to handle communications to the remote application. This class should implement a Java interface, AbfCustomTransport with couple of methods, / ********************************************************************* * init - method to initialize various arguments * @param sessionId - an unique session ID * @param shortName - short Name for the service(remote rule) * @param longName - long Name for the service(remote rule) * @param auth - authentication info for the service * @return - None ********************************************************************/ public void init( int sessionId , String shortName , String longName , AbfLoginInfo auth ); / ********************************************************************* * run - method to invoke the remote application * @param input - input data in the form of view/struct * @param output - output data in the form of view/struct. This will * - get filled when the method returns. * @param inout - flag to indicate if both input and output are same * @return - the output data gets filled when the method returns
6-9
********************************************************************/ public void run( AbfStruct input , AbfStruct output , boolean inout ) throws NeteException; Refer to the ObjectSpeak Reference Guide for details on AbfStruct, and to this document for AbfLoginInfo methods. The init() method is called to initialize various arguments to the remote call. It is followed by a method call, run() which can be used to execute the remote call. The run() method has the input and output views. The run() implementation should use Java reflection to traverse the input/output structures. Here is an example Java class that implements the AbfCustomTransport interface, traverses these views recursively, and displays the data. import import import import import java.lang.reflect.*; java.io.*; appbuilder.util.*; appbuilder.nete.AbfLoginInfo; appbuilder.nete.AbfCustomTransport;
public class CustomTransportExample implements AbfCustomTransport { public void init( int id, String shortName, String longName, AbfLoginInfo login ) { System.out.println( "MyTransport.init - " + id + " Name:[" + shortName +", " + longName + "] " ); } public void run( AbfStruct in, AbfStruct out, boolean inout ) { System.out.println( "MyTransport.run" ); try { displayStruct(in); } catch( Exception e ) { System.out.println( "Exception from displayStruct: " + e.getMessage() ); } } protected void displayStruct( AbfDataObject aStruct ) throws Exception { AbfDataObject data = null; // throw runtime exception in case of null reference at any level during reflection. if (aStruct == null) throw new NullPointerException("Given Struct is NULL"); System.out.println( "Struct Name:" + aStruct.getClass().getName() ); // check if the object is a primitive if (displayField(aStruct)) return;
6-10
// check if it is an array object if ( aStruct instanceof appbuilder.util.AbfArray ) { AbfArray arrObj = (AbfArray) aStruct; int arrlen = arrObj.getOccurs(); System.out.println( "Occurs: " + arrlen ); // This dataChange event is relevant only for the output view. // When the data is updated after a remote call, all the associated // GUI can be refreshed with a call to fireAbfDataChange(). However, // when processing an array with many rows of data, it is better to // refresh the GUI after filling all rows of data. This call will // temporarily stop the listeneres arrObj.firePreAbfDataChange(); for (int i=1; i <= arrlen; i++) { AbfDataObject eltobj = arrObj.getElem(i); displayStruct(eltobj); } // All rows of data filled in, restart the fireListeners arrObj.fireAbfDataChange(); } else // fields or non-occuring views { if (! (aStruct instanceof appbuilder.util.AbfStruct) ) { if (displayField(aStruct)) { System.out.println( "a Field: " + data ); } } Field[] fields = aStruct.getClass().getFields(); // skip unaccessible fields(non public). Non static checking? for (int i=0; i<fields.length; i++) { try { Object fldObj = fields[i].get(aStruct); if ( !(fldObj instanceof appbuilder.util.AbfDataObject) ) continue; // skip if not AbfDataObject AbfDataObject abfObj = (AbfDataObject)fldObj; System.out.println( "Struct/Field: " + abfObj.getClass().getName() ); // a abf view object... displayStruct( abfObj ); } catch (IllegalAccessException e) { throw new Exception( "Illegal Access Exception: displayStruct 1" ); } }
6-11
} } protected boolean displayField( Object ob) throws Exception { boolean aprim = true; if ( ! (ob instanceof AbfDataObject) ) return false; // not a AB primitive AbfDataObject data = (AbfDataObject)ob; System.out.println( "Struct/Field: " + ob.getClass().getName() ); if ( ob instanceof AbfString) { AbfString abfStr = (AbfString) ob; switch ( abfStr.getType() ) { case AbfString.DBCS: System.out.println( "DBCS MaxLen:" + abfStr.getMaxLength() * 2 + " <" + abfStr + ">" ); break; case AbfString.MIXED: System.out.println( "MIXED MaxLen:" + " <" + abfStr + ">" ); break; abfStr.getMaxLength() +
case AbfString.VARCHAR: // Varchar described using two dit slots, one for length field // and 2nd for the string contents. // Write length field. Note: Although written as a short, // if data is aligned then will actually be written as int System.out.println( "VarChar MaxLen:" + abfStr.getMaxLength() + " Actual Len:" + abfStr.getCurLength() + " <" + abfStr + ">" ); break; default: System.out.println( "CHAR MaxLen: " + " <" + abfStr + ">" ); break; } } else if ( ob instanceof AbfBoolean) { AbfBoolean b = (AbfBoolean)ob; System.out.println( "BOOL: " + b ); } else if ( ob instanceof AbfShortInt) { AbfShortInt s = (AbfShortInt)ob; System.out.println( "SHORT: " + s ); } else if ( ob instanceof AbfLongInt) { AbfLongInt l = (AbfLongInt)ob; abfStr.getMaxLength() +
6-12
System.out.println( "LONG: " + l ); } else if ( ob instanceof AbfDate) { AbfDate d = (AbfDate)ob; System.out.println( "DATE: " + d.getYear().toInt() + "/" + d.getMonth().toInt() + "/" + d.getDay().toInt() ); } else if ( ob instanceof AbfTime) { AbfTime t = (AbfTime)ob; System.out.println( "TIME: " + t.getHour().toInt() + "/" + t.getMin().toInt() + "/" + t.getSec().toInt() ); } else if ( ob instanceof AbfBlob) { AbfBlob b = (AbfBlob) ob; System.out.println( "BLOB: " + b ); if ( b.getType() == AbfBlob.TEXT ) {} else if ( b.getType() == AbfBlob.IMAGE ) {} } else if ( ob instanceof AbfTimestamp ) { AbfTimestamp t = (AbfTimestamp)ob; // could be netetimestamp object System.out.println( "TIMESTAMP: " + t.getDate().getYear().toInt() + "/" + t.getDate().getMonth().toInt() + "/" + t.getDate().getDay().toInt() + "/" + t.getTime().getHour().toInt() + "/" + t.getTime().getMin().toInt() + "/" + t.getTime().getSec().toInt() + "/" + t.getTime().getMilsec().toInt() + "/" + t.getFraction().toInt() ); } else if ( ob instanceof AbfDecimal ) { AbfDecimal d = (AbfDecimal) ob; System.out.println( "DECIMAL: " + d ); if ( d.getMode() == AbfDecimal.DEC ) {} else {} } else aprim = false; if ( aprim ) { // The datachange should be fired only when the data changes // in the output view to automatically refresh the associated GUI. // When reading the input view, this is not required. data.fireAbfDataChange(); } return aprim; } }
6-13
Security Exits in C
Authentication
To enable Custom Transport, Use the Management console to create a new server entry using the CUSTOM type. A route entry should be defined to use this server type. Make sure the Custom transport java class is included in the classpath of the execution environment.
Security Exits in C
Secure distributed applications in C Language use three related mechanisms to protect against unauthorized access to data and services: Authentication establishes the identity of application users. It insures that users are who they say they are by requiring a password as proof of identity. Authorization establishes the permissions of users. It insures that users can execute only the application services and controls they are authorized to execute. Encryption protects application data from being accessed outside the program. It insures that even if intruders were to break into the network, they cannot read the data and login information the application transmits.
Each of these mechanisms is widely available in distributed computing. AppBuilder provides an interface to a series of program exits in an intelligent and integrated way that let you transmit security information to the security subsystems in use at your site. These topics of authentication, authorization, and encryption describe how you can use the communications exits to secure a distributed application.
Authentication
Authentication tests the identities of application users. It answers the question, Are you who you say you are? by requiring you to produce a password as proof of the identity you claim. The problem and its solution are familiar ones to computer users. What makes the problem troublesome in distributed computing is the existence of multiple systems for which user identities must be established. The problem is compounded by directory services mechanisms that require the security system to make decisions as to which identity it should use. AppBuilder provides the solution to these problems. Consider the distributed application shown in Figure 6-1. A Windows client program, CUST_LST, calls the service DB_QUERY on an NT machine running an Oracle database, and the services DB_ADD and DB_DEL on a Sun operating system machine running a Sybase database. The user of the program is known to the application and the Oracle database as JAMESB. The user is known to the Sybase database as JBOND.
6-14
Authentication
Security Exits in C
Figure 6-1
Handling multiple security identifiers
This configuration is typical of directory services load-balancing schemes and poses no issues for security as long as the user manually signs on to the remote databases. But manual sign on is a chore, and asking users to remember multiple login IDs and passwords invites errors and user downtime. This is also needlessly expensive because a connection is required for each sign on. Lets look at how this application might satisfy its security needs more efficiently: 1. 2. 3. Elicit JAMESBs login ID in the client program. Transmit JAMESBs login ID to Oracle for DB_QUERY requests. Transmit JBONDs login ID to Sybase for DB_ADD or DB_DEL requests.
The first problem, of course, is how the application obtains JBONDs login ID. The second problem is how the application decides whether to transmit JAMESB or JBOND. A similar problem arises when the user logs on to a gateway as JAMESB and on to the server to which requests are forwarded as JBOND. Authentication Exit A communications authentication exit on the client side maps user IDs to protocol-specific host destinations. It lists login ID, password, and destination mappings, like these for our sample application: JAMESB 007SPY NT_1 JBOND GOLDENI SUN_1 You typically read the mappings from a file or from another program. Your application continues to elicit JAMESBs login information at startup, to test whether the user should be given access to the application. An authentication exit is capable of returning multiple user ID and password combinations for use by AppBuilder when communicating with different systems. The first array entry is a default. The 'login_struct' pointer returned to AppBuilder by the exit should point to an array of 'dna_LoginStruct' structures. AppBuilder does not pre-determine how many entries there are in this array. Instead, it requires that the last entry is flagged by each of the three pointers in that entry being set to NULL. For the remainder of the entries, each contains a system name, a user ID and a password. When AppBuilder needs to communicate with another system, it scans the entries looking for a match for the system name. (Note, it does a case sensitive search.) If found, the user ID and password from that entry is used when communicating with that system. If no match for the system name is found, the user ID and password from the first entry is used as a default, regardless of its system name. Hence, for most authentication exit implementations, only two array entries are usually returned: the 'default' entry and the end-flag entry.
6-15
Security Exits in C
Authorization
AppBuilder also connects to the database on behalf of an AppBuilder application. From the array returned by the authentication exit, it has the user ID and password needed to perform the connection. It uses the value of WORKSTATION_ID from the AE Runtime section of the system initialization file (hps.ini) as the 'system'. In the same way that it looks for a user ID and password for a remote system, if no matching system name for the workstation ID is found, the first entry (the default) is used. For most implementations of authentication exits, this is the user's mainframe user ID and password. So, if different user IDs are required for mainframe and local databases, the authentication exit should return a array as follows: (null-string) workstation id NULL mf-userid db-userid NULL mf-password db-password NULL
Since the first entry is used as a default entry, its 'system' is irrelevant and is usually specified as a null-string. At client initialization, AppBuilder detects the presence of the exit and reads the login information/ destination mappings into memory. When the client program makes a service request, AppBuilder compares the destination of the request with the destinations received from the exit and determines the correct user identity to transmit. When the server connection is opened, AppBuilder automatically passes the login information to: A server-side DBMS, via the database connection exit described in Database Exits in C. A third-party security subsystem, via LU2 or LU6.2 A communications server authentication exit, if you do further processing on the server side (see Client- and Server-side Authorization and Encryption)
Passing authentication information to a DBMS
Figure 6-2
A security ticket is a virtual ID and password for an external security system. If you use a security ticket instead of a user name and password to authenticate a user, you can code a client-side authentication exit that retrieves the ticket and passes it to each client and server exit that needs it.
Authorization
Authorization establishes your permissions as the user with the identity given at authentication. It insures that you can execute only the application services you are authorized to execute. Following the example from the Authentication section, JAMESB might be permitted to create and query accounts but not delete them, in which case you would give him authorization to execute DB_ADD and DB_QUERY but not DB_DEL.
6-16
Encryption
Security Exits in C
Authorization Exit A communications authorization exit on the client or server side maps user identities to application services: JAMESB DB_ADD JAMESB DB_QUERY JBOND DB_ADD JBOND DB_QUERY Again, you read the mappings from a file or from another program. When the client program makes a service request, AppBuilder determines the user identity sent with the request based on the information in the client or server authentication exit. The authorization exit receives the user information and compares the names of the authorized services for that user with the name of the requested service to determine whether the request should be fulfilled. Client- and Server-side Authorization Authorization checks are typically performed on the server, after a service request is transmitted. You can avoid the expense of opening unnecessary server connections by having authorization performed on the client, before the service request is sent. Client-side authorization is especially useful when you are using a gateway to forward service requests to another server. Why have server-side authorization at all? Because client-side authorization is intrinsically less secure; an initialization file variable determines whether AppBuilder detects the client authorization exit in the first place. Unless you protect against users tampering with the initialization fileby putting it on a protected network file server, for examplethe end user can gain access to every service on the server simply by manipulating the variable. Figure 6-3 shows client- and server-side authorization.
Figure 6-3 Client- and server-side authorization
Constraint-based validation is also available. You can make a users authorization to access a requested service conditional on the input data being passed with the request. You could grant the user authorization to update records only within a specified range. If a request is made to update a record outside that range, access to the service is denied.
Encryption
It is not enough to protect against unauthorized access to data by users of your application if a network intruder outside your application can read the format of the data and the user login information you are
6-17
Security Exits in C
Setting Up Security Exits
transmitting. Encryption insures that even if intruders were to break into your network, they cannot read the data and user information your application transmits. A communications encryption exit on the client side encrypts the users password; a server-side authentication exit decrypts the password. Figure 6-4 shows the encryption exit mechanism.
Figure 6-4 Encryption exit
Open Data Encryption Mechanism You can use the open data encryption mechanism to encrypt application data. The data encryption mechanism is open in the sense that you choose the encoding and decoding algorithms that best suit your needs. Use trace exits (also called RPC-end exits) on the client or server side to log service usage or take some other action based on the status of an ending RPC.
Setting Up Security Exits

Templates for the security exits are provided with the product in the samples directory. You customize the templates to obtain the authentication and authorization information required by the security setup at your site. The data encryption mechanism requires you to build your own encryption library and to customize exported entry points into the library, as described in Open Data Encryption Mechanism. You can use the security exits in any combination. You typically use the client authentication exit to elicit login information for the remaining exits, but you can also modify login information in the client authorization or server authentication exits. To see a list of the entry points, refer to Security Exits Reference for C. A typical security and tracing setup looks like this: 1. An authentication routine on the client machine elicits an array of security entries. Each item holds the name of an available remote system and the user login ID and password for that system. The entry point is named AuthentLibMain. For security systems that use a ticket (see the topic box), the authentication routine transmits the ID and password to the security system. On receipt of the ID and password, the ticket is returned. 2. An authorization routine on the client machine tests the users authorization to access a remote service. In some cases, the routine uses the security ticket to test the users authorization. The entry point is named AuthorLibMain. An encryption routine on the client machine encrypts the user password for network transmission. The entry point is named EncryptLibMain.
3.
6-18
Security Exits Reference for C
Security Exits in C
4.
An authentication routine on the server machine decrypts the user password for the security subsystem on that machine, and checks the login ID and password for validity. In some cases, the routine uses the security ticket to test the users authenticity. The entry point is named SrvAuthentLibMain. An authorization routine on the server machine tests the users authorization to access a service. In some cases, the routine uses the security ticket to test the users authorization. The entry point is named SrvAuthorLibMain. A trace routine on the client or server machine logs service usage. The entry point is named RpcEndLibMain.
5.
6.
You write the routines in C and compile and link themin a load module for mainframe, an EXE file for OS/400, a DLL otherwisefor the operating systems in use at your site. Make sure to specify the linked modules path and filename in the following variables in the DNA_EXITS section of the dna.ini file on the client or server machine. An empty variable (the default) means that the referenced exit is not invoked. DNA_AUTHENT_EXIT points to the client authentication exit DNA_AUTHOR_EXIT points to the client authorization exit DNA_ENCRYPT_EXIT points to the encryption exit DNA_RPC_END_EXIT points to the trace exit SRV_AUTHENT_EXIT points to the server authentication exit SRV_AUTHOR_EXIT points to the server authorization exit
You can use the custom configuration tools on PC and UNIX hosts to point to the locations of the exits. Linking Security Exits on the Mainframe In the mainframe runtime for C applications (C370), the exits must be statically linked into the DNACSV00 executable (HPSDNA00 for AppBuilder applications). Instead of specifying the path of the exits in the security exit variables in dna.ini file, you must specify the value STATIC_LINK. In the mainframe runtime (LE370), the exits are dynamically linked. Specify the paths of the exits as described above. Messaging and Eventing in Security-enabled Environments If the parent of a node is a security-enabled mainframe listening over LU6.2, the messaging and eventing agent at the node must point to a client-side authentication exit. The authentication exit passes the user name and password to LU6.2. There is no need to code a server-side exit. The custom configurators for the agent prompt you to enter the full pathname of the exit. If you use the child node for RPCs as well as messaging and eventing, enter the pathname you specified for the RPC client.
Security Exits Reference for C

Security entry points include: AuthentLibMain AuthorLibMain EncryptLibMain
6-19
Security Exits in C
AuthentLibMain
SrvAuthentLibMain SrvAuthorLibMain RpcEndLibMain
AuthentLibMain
Purpose Elicit an array of security entries for network transmission. Each item holds the name of an available remote system and the user login ID and password for that system. For details on authentication, see Authentication. Prototype #include <dna.h> int AuthentLibMain(Authent_LibFuncs_t func_type, void *authent_args_ptr); Formal Arguments func_type Structure of type Authent_LibFuncs_t that identifies the functions called from the entry point: typedef enum { GET_LOGIN_CALL, FREE_LOGIN } Authent_LibFuncs_t; authent_args_ptr Pointer to a structure of type dna_LoginArgs_t: typedef struct { dna_LoginStruct **login_struct; dna_ClntId_ptr_t client_id; dna_SecCookie_t **sec_ticket; } dna_LoginArgs_t; In dna_loginArgs_t: dna_LoginStruct holds security data: the target system (which has a maximum size of 32 bytes) and the user ID and password for the target system (which each have a maximum size of 15 bytes). dna_ClntId_ptr_t identifies the client ID passed to dna_InitClient. For security systems that use a ticket (see the topic box), dna_SecCookie_t holds the ticket and its data description. It is your responsibility to allocate one more structure than is required to hold security data, and to set the pointers in the additional structure to NULL. Return Values LOGON_SUCCESS LOGON_FAILURE
6-20
AuthorLibMain
Security Exits in C
AuthorLibMain
Purpose Test the users authorization to access a remote service. For details on authorization, see Authorization. Prototype #include <dna.h> int AuthorLibMain(Author_LibFuncs_t func_type, void *author_args_ptr); Formal Arguments func_type Structure of type Author_LibFuncs_t that identifies the function called from the entry point: typedef enum { CHECK_AUTHOR_CALL } Author_LibFuncs_t; author_args_ptr Pointer to a structure of type dna_ChkAuthorArgs_t: typedef struct { dna_LoginStruct *login_struct; dna_StatusView *status_view; void *input_view; dna_ClntId_ptr_t client_id; dna_SecCookie_t *sec_ticket; Data_Info_t *input_ctrl; } dna_ChkAuthorArgs_t; In dna_ChkAuthorArgs_t: dna_LoginStruct holds security data elicited by the client authentication exit (see AuthentLibMain) dna_StatusView holds the status view input_view is a void pointer to the input view of a remote service request dna_ClntId_ptr_t identifies the client ID passed to dna_InitClient For security systems that use a ticket (see the topic box), dna_SecCookie_t holds the ticket and data description elicited by the client authentication exit Data_Info_t holds the input data description Do not change the status view or input data. You can (but typically do not) change the security data. Return Values AUTHOR_SUCCESS AUTHOR_FAILURE
6-21
Security Exits in C
EncryptLibMain
EncryptLibMain
Purpose Encrypt the user password for network transmission. The routine should encrypt in place, and encrypt to valid characters only (not binary). For details on encryption, see Encryption. Prototype #include <dna.h> int EncryptLibMain(Encrypt_LibFuncs_t func_type, void *encrypt_args_ptr); Formal Arguments func_type Structure of type Encrypt_LibFuncs_t that identifies the function called from the entry point: typedef enum { ENC_PASSWD_CALL } Encrypt_LibFuncs_t; encrypt_args_ptr Pointer to a structure of type dna_EncPasswdArgs_t that points, in turn, to the address of an area that holds the password elicited by the client authentication exit. Return Values ENCPASSWD_SUCCESS ENCPASSWD_FAILURE
SrvAuthentLibMain
Purpose Decrypt the user password for the security subsystem on the server machine, and check the user login ID and password for validity. For details on authentication, see Authentication. Prototype #include <dna.h> int SrvAuthentLibMain(srv_Authent_Funcs_t func_type, void *authent_args_ptr); Formal Arguments func_type Structure of type srv_Authent_Funcs_t that identifies the function called from the entry point: typedef enum { SRV_CHK_USER_CALL } srv_Authent_Funcs_t; authent_args_ptr Pointer to a structure of type srv_ChkUserArgs_t: typedef struct {
6-22
SrvAuthorLibMain
Security Exits in C
srv_ChkUserStruct *userinfo; } srv_ChkUserArgs_t; srv_ChkUserStruct holds: The user ID and password elicited by the client authentication exit dna_SecCookie_t. For security systems that use a ticket (see the topic box), dna_SecCookie_t holds the ticket and data description elicited by the client authentication exit. AppBuilder retains changes that the routine makes to the password but not to the user ID. If the server is a gateway or calls other remote services, the changed password will be used. Return Values SRV_CHKUSER_SUCCESS SRV_CHKUSER_FAILURE
SrvAuthorLibMain
Purpose Test the users authorization to access a service. For details on authorization, see Authorization. Prototype #include <dna.h> int SrvAuthorLibMain(srv_Author_Funcs_t func_type, void *author_args_ptr); Formal Arguments func_type Structure of type srv_Author_Funcs_t that identifies the function called from the entry point: typedef enum { SRV_CHK_SERV_CALL } srv_Author_Funcs_t; authent_args_ptr Pointer to a structure of type srv_ChkServArgs_t: typedef struct { srv_ChkServStruct *servinfo; void *input_view; void *hps_cntxt; Data_Info_t *input_ctrl; } srv_ChkServArgs_t; In srv_ChkServArgs_t: srv_ChkServStruct holds: The user ID and password elicited by the client authentication exit. The name of the requested service. The client ID passed to dna_InitClient.
6-23
Security Exits in C
RpcEndLibMain
dna_SecCookie_t. For security systems that use a ticket (see the topic box), dna_SecCookie_t holds the ticket and data description elicited by the client authentication exit. input_view is a void pointer to the input view of a remote service request. hps_cntxt is a void pointer to the mainframe context. Irrelevant. Data_Info_t holds the input data description. Do not change the security data or input data. Return Values SRV_CHKSERV_SUCCESS SRV_CHKSERV_FAILURE
RpcEndLibMain
Purpose Log service usage or take some other action based on the status of an ending service request. Prototype #include <dna.h> int RpcEndLibMain(RpcEnd_LibFuncs_t func_type, void *rpcend_args_ptr); Formal Arguments func_type Structure of type RpcEnd_LibFuncs_t that identifies the function called from the entry point: typedef enum { END_EXIT_CALL } RpcEnd_LibFuncs_t; rpcend_args_ptr Pointer to a structure of type dna_EndExitArgs_t: typedef struct { dna_StatusView *status_view; } dna_EndExitArgs_t; dna_StatusView holds the status view. Return Values DNA_RPC_SUCCESS DNA_RPC_FAILURE
Open Data Encryption Mechanism

For data encryption, you build your own encryption library and customize exported entry points into the library. The library is named:
6-24
dna_BufInit
Security Exits in C
dnaenc.dll for PC platforms dnaenc.sl for UNIX platforms
Once created, this library should replace the empty version shipped with the product. Templates for the data encryption mechanism are provided with the product in the samples directory.
Note
You can also use the data encryption mechanism to compress data.
The entry points into the library are as follows: dna_BufInit dna_BufEncode dna_BufDecode dna_BufClose
Make sure to include the header file dnaenc.h. The following structure in dnaenc.h is used for encoding and decoding data: typedef struct { unsigned char *data; unsigned long buffer_length; } dna_UserBuf_t; Return codes in dnaenc.h are as follows: #define #define #define #define DNAENC_ERROR -1 DNAENC_SUCCESS 0 DNAENC_NO_CUSTOMIZE DNAENC_CUSTOMIZE 1
The data encryption mechanism is not supported on LU2. If you use the mechanism on LU2, only the initialization and close functions are called.
dna_BufInit
Purpose Initialize data encryption. Call this function on a client when a connection to a new server is about to be established, or on a server when a new connection is being initiated by a client. Prototype #include <dnaenc.h> int DNA_ENTRY dna_BufInit(void **user_context,int flags, dna_Binding_t *binding); Formal Arguments user_context Address of a void pointer to a user-defined structure. The routine is expected to create a context that will be passed to subsequent routinesfor example, it may keep the address of memory it allocates to encode or decode data and/or a key used to encrypt or decrypt the data.
6-25
Security Exits in C
dna_BufEncode
flags Identifies the calling program. 1 means that a client is invoking the routine, 0 means that a server is invoking the routine.
binding For clients, pointer to a structure that contains service binding information. You can use this argument to select an encryption key.
Return Values An integer equal to DNAENC_CUSTOMIZE if data encoding should take place, DNAENC_NO_CUSTOMIZE if data encoding/decoding should not take place, or DNAENC_ERROR.
dna_BufEncode
Purpose Encode (encrypt or compress) the transmitted data. You can encode data transmitted from a client to a server, or from a server to a client. Prototype #include <dnaenc.h> int DNA_ENTRY dna_BufEncode(void *user_context, dna_UserBuf_t * in_buffer, dna_UserBuf_t * enc_buffer); Formal Arguments user_context Pointer to a user-defined structure, as returned to dna_BufInit. in_buffer Pointer to the buffer for the input data. The routine encodes the data in this buffer and puts the results in enc_buffer. enc_buffer Pointer to the buffer for the encoded data. The routine fills in this structure with a pointer to the encoded data and the encoded data length. Note that you are responsible for allocating and freeing the buffer for the encoded data. Set enc_buffer->data to the allocated buffer and enc_buffer->buffer_length to the encoded data size. Return Values DNAENC_ERROR DNAENC_SUCCESS
6-26
dna_BufDecode
Security Exits in C
dna_BufDecode
Purpose Decode (decrypt or decompress) the transmitted data. You can decode data transmitted from a client to a server, or from a server to a client. Prototype #include <dnaenc.h> int DNA_ENTRY dna_BufDecode(void *user_context, dna_UserBuf_t * enc_buffer, dna_UserBuf_t * dec_buffer); Formal Arguments user_context Pointer to a user-defined structure, as returned to dna_BufInit. enc_buffer Pointer to the buffer for the encoded data. The routine decodes the data in this buffer and puts the results in dec_buffer. dec_buffer Pointer to the buffer for the decoded data. The routine fills in this structure with a pointer to the decoded data and the decoded data length. Note that you are responsible for allocating and freeing the buffer for the decoded data. Set dec_buffer->data to the allocated buffer and dec_buffer->buffer_length to the decoded data size. Return Values DNAENC_ERROR DNAENC_SUCCESS
dna_BufClose
Purpose Clean up after the connection to a peer is broken down and encoding/decoding is complete. Prototype #include <dnaenc.h> int DNA_ENTRY dna_BufClose(void *user_context); Formal Arguments user_context Pointer to a user-defined structure, as returned to dna_BufInit. The user-defined data may reference memory to be freed.
6-27
Directory Services Exits in C
dna_BufClose
Return Values DNAENC_ERROR DNAENC_SUCCESS

In AppBuilder communications, remote procedure calls (RPCs), messaging, global eventing, and implicit eventing all use directory services to determine the target of a communications call: RPCs use a route table to identify a requested service Messaging uses a route table to identify local and remote queues and a subcell table to identify the routes to the children of the local host Global eventing uses a subcell table to identify the routes to the children of the local host Implicit eventing uses a subcell table to identify the routes to the children of the local host, a trigger table to identify the triggering service, and an event table to identify the triggered service, message, or event
This topic looks at how you use communications exits to adapt the directory services interface to external directory service schemes. Figure 6-5 shows how the directory services exits fit into the processing flow of your application.
Figure 6-5 Directory services exits
The exits are made available in the form of export functions in the external directory services shared library. You customize the shared library, rebuild it, and substitute it for the library supplied with the product. The library is named libextds, and is already linked to AppBuilder communications when you receive the product. See Compiling and Linking for information about compilation. The entry points into the library are as follows: dna_ExtRoutes dna_ExtSubcells dna_ExtTriggers dna_ExtEvents
Make sure to include the header files marshall.h and extds.h. The following structure in extds.h is used for service request routing:
6-28
dna_BufClose
typedef struct { char service[TBL_SERVICE_LEN]; char datalen[TBL_RDLEN_LEN]; char datastart[TBL_RDOFFS_LEN]; char datatype[TBL_DTYPENAME_LEN]; char datavalstart[TBL_RANGELEN_LEN]; char datavalend[TBL_RANGELEN_LEN]; char host[TBL_HOSTNAME_LEN]; char protocol[TBL_PROTOCOL_LEN]; char serverid[TBL_SERVERID_LEN]; char codepage[TBL_CODEPAGE_LEN]; char priority[TBL_PRIORITY_LEN]; } route_binding_t; The following structure in extds.h is used for subcell table routing: typedef struct { char generic_hostname[TBL_HOSTNAME_LEN]; /* protocol-independent */ char hostname[TBL_HOSTNAME_LEN]; /* protocol-specific */ char protocol[TBL_PROTOCOL_LEN]; char serverid[TBL_SERVERID_LEN]; char codepage[TBL_CODEPAGE_LEN]; } subcell_binding_t; The following structure in extds.h is used for trigger information: typedef struct event_struct { long event_id ; char event_name[IMPLEVT_LEN] ; char data_len[DATA_DEP_LEN]; char data_offs[DATA_DEP_OFF]; char data_type[DATA_DEP_TYP]; char data_low_limit[DATA_DEP_RANGE]; char data_high_limit[DATA_DEP_RANGE]; } evtmEvent_t ; The following structure in extds.h is used for action information: typedef struct evtmAction_t { long event_id; char event_name[IMPLEVT_LEN]; char event_type[IMPLEVT_LEN]; char event_attribute[IMPLEVT_LEN]; char subsys[IMPLEVT_LEN]; char action_name[IMPLEVT_LEN]; char action_host[IMPLEVT_LEN]; char locality[VIEW_ATTR_LEN]; char view_choice[VIEW_ATTR_LEN]; char view_replace[VIEW_ATTR_LEN]; } evtmAction_t; Return codes in extds.h are as follows: #define EXTDS_SUCCESS #define EXTDS_FAILURE 0 1
If you use external directory services, make sure to set up the configuration file dna.ini as follows:
6-29
dna_ExtRoutes
[ROUTING] NAME_SERVICE = EXTERNAL [IMPLICIT_EVENTS] EVENT_SERVICE = EXTERNAL [SMA] SMA_SUBCELL_TABLE = EXTERNAL Note that if you use external directory services for any of the features on a host, you must use it for all of them. You cannot use external directory services for subcell table routing, for example, while using comunications directory services for RPC routing.
dna_ExtRoutes
Purpose Identify the route to a service or message queue. Prototype #include <marshall.h> #include <extds.h> int dna_ExtRoutes(char *servicename, Data_Info_t *indit, void *indata,route_binding_t *bind_list, long numroutes,long *num_routes); Formal Arguments servicename String that identifies the name of the service or message queue. indit Pointer to the control-structure array for the service request input view. Used for data-dependent routing. Irrelevant for messaging. indata Pointer to the service request input view. Used for data-dependent routing. Irrelevant for messaging. bind_list Pointer to a preallocated, empty array of size num_routes that you must modify to hold binding information. numroutes Number of parallel or alternative routes allowed by AppBuilder communications. num_routes Pointer to the number of bindings the exit provides in bind_list.
6-30
dna_ExtRoutes
Return Values EXTDS_SUCCESS EXTDS_FAILURE Example with dna_ExtRoutes int dna_ExtRoutes(char void long { route_binding_t *b = int i; *servicename, Data_Info_t *indit, *indata, route_binding_t *bind_list, numroutes, long *num_routes) bind_list;
printf("\nGet into externalized route service. \n"); printf("servicename: %s. servicename\n"); printf("route1: knuth, tcpip, dna_single_tst. \n"); /* construct one route for "servicename" */ strcpy(b->service, servicename); strcpy(b->datalen, "2"); strcpy(b->datastart, "input.parm1"); strcpy(b->datatype, "short"); strcpy(b->datavalstart, "100"); strcpy(b->datavalend, "1000"); strcpy(b->host,"knuth"); strcpy(b->protocol,"tcpip"); strcpy(b->serverid,"dna_single_tst"); b->codepage[0] = '\0'; strcpy(b->priority, "1"); b++; printf("route2: nasdaq, tcpip, dna_single_tst. \n"); /* construct 2nd route for "servicename" */ strcpy(b->service, servicename); strcpy(b->datalen, "-"); strcpy(b->datastart, "-"); strcpy(b->datatype, "-"); strcpy(b->datavalstart, "-"); strcpy(b->datavalend, "-"); strcpy(b->host,"nasdaq"); strcpy(b->protocol,"tcpip"); strcpy(b->serverid,"dna_single_tst"); b->codepage[0] = '\0'; strcpy(b->priority, "2"); *num_routes = 2; printf("\nExit sample externalized directory service. \n"); return EXTDS_SUCCESS; }
6-31
dna_ExtSubcells
dna_ExtSubcells
Purpose Identify the routes to the children of the local host. Prototype #include <marshall.h> #include <extds.h> int dna_ExtSubcells(subcell_binding_t *binding,long max_bindings, long descend_flag,long *num_subcells); Formal Arguments binding Pointer to a preallocated, empty array of size max_bindings that you must modify to hold binding information. max_bindings Maximum number of bindings that can be stored in the binding table. descend_flag Identifies whether to route to immediate children only. 1 means route to all descendants, 0 means route to immediate children only. num_subcells Pointer to the number of bindings the exit provides in the binding argument. Return Values EXTDS_SUCCESS EXTDS_FAILURE Example with dna_ExtSubcells int dna_ExtSubcells(subcell_binding_t *binding, long max_bindings, long descend_flag, long *num_subcells) { int dna_ExtRoutes(char *servicename, Data_Info_t *indit, void *indata, route_binding_t *bind_list, long numroutes, long *num_routes) { strcpy(bind_list[0].servicename, servicename); strcpy(bind_list[0].host, "athena"); strcpy(bind_list[0].protocol, "NEMSG"); strcpy(bind_list[0].serverid, "Q1"); strcpy(bind_list[0].datalen, "-"); strcpy(bind_list[0].datatype, "-"); strcpy(bind_list[0].datavalstart, "-"); strcpy(bind_list[0].datavalend, "-"); bind_list[0].codepage='\0'; *num_routes=1; return EXTDS_SUCCESS;
6-32
dna_ExtTriggers
} }
dna_ExtTriggers
Purpose Identify the triggering service. Prototype #include <marshall.h> #include <extds.h> int dna_ExtTriggers(char *service_name,char *trigger_type, evtmEvent_t *event_list, long maxevents,long *num_events); Formal Arguments service_name - String that identifies the name of the triggering service. trigger_type - String that identifies the trigger type. START_RULE means that initiation of the triggering service is postponed until the associated action is complete, END_RULE means that initiation of the action is postponed until the triggering service is complete. event_list - Pointer to a preallocated, empty array of size max_events that you must modify to hold a list of all events that will be triggered by execution of the triggering service. max_events -Maximum number of events that can be stored in event_list. num_events - Pointer to the number of triggered events the exit provides in event_list.
Return Values EXTDS_SUCCESS EXTDS_FAILURE Example with dna_ExtTriggers int dna_ExtTriggers(char *service_name, char *trigger_type, evtmEvent_t *event_list, long maxevents, long *num_events) { evtmEvent_t *e = event_list; printf("\nGet into sample trigger directory service. \n"); if ((!strcmp(service_name, "ADD")) && (!strcmp(trigger_type, "end_rule"))) { printf("trigger EVENT_2\n"); e->event_id = 2; strcpy(e->event_name, "EVENT_2"); strcpy(e->data_len, "-"); strcpy(e->data_offs, "-"); strcpy(e->data_type, "-"); strcpy(e->data_low_limit, "-"); strcpy(e->data_high_limit, "-"); *num_events = 1; }
dna_ExtEvents
else *num_events = 0; printf("\nExit externalized trigger directory service. \n"); return EXTDS_SUCCESS; }
dna_ExtEvents
Purpose Identify the triggered service, message, or event. This exit is called each time an event is triggered. Prototype #include <marshall.h> #include <extds.h> int dna_ExtEvents(evtmEvent_t *a_event,evtmAction_t *a_action, long *num_actions); Formal Arguments a_event Pointer to the trigger information returned by dna_ExtTriggers. Use this information to identify the event to be triggered. a_action Pointer to the action information for the identified event. num_actions Address that identifies whether the action information can be used to post an event. 1 means yes, 0 means no. Return Values EXTDS_SUCCESS EXTDS_FAILURE Example with dna_ExtEvents int dna_ExtEvents(evtmEvent_t *a_event, evtmAction_t *a_action, long *num_actions) { evtmAction_t *a = a_action; printf("\nGet into externalized event directory service. \n"); a->event_id = 2; strcpy(a->event_name, "EVENT_2"); strcpy(a->event_type, "-"); strcpy(a->event_attribute, "nontran_sync"); strcpy(a->subsys, "-"); strcpy(a->action_name, "IMP_IO_O"); strcpy(a->action_host, "-"); strcpy(a->locality, "-"); strcpy(a->view_choice, "io_o"); strcpy(a->view_replace, "y");
6-34
dna_ExtEvents
Database Exits in C
*num_actions = 1; printf("\nGet into externalized event directory service. \n"); return EXTDS_SUCCESS;. }
Database Exits in C
Database connects, starts, commits, aborts, and disconnects are by far the most DBMS-dependent operations a database program uses. For supported DBMSs, AppBuilder communications exits in C manage these operations for you. If you are not using a supported DBMS, you must customize the exits with the DBMS-specific code for these operations. Figure 6-6 shows how the database exits fit into the processing flow of your application. Refer to the Third-Party Support Matrix (available on the Customer Support Web site) for details about which databases at which release are supported.
Figure 6-6 Database exits
The exits are made available in the form of export functions in the SDBI (database interface) library. You customize the shared library, rebuild it, and substitute it for the library supplied with the product. The library is named libsdbi, and is already linked to AppBuilder communications when you receive the product. The exits are available on the server side only. See Compiling and Linking for information about compilation. The entry points into the library are as follows: sdbi_Connect sdbi_StartTxn sdbi_CommitTxn sdbi_AbortTxn sdbi_Disconnect
Make sure to include the header files stdio.h, stdlib.h, and sdbi.h. The connection exit returns connection information to AppBuilder. It uses the following data structure: typedef struct { HWND sdbi_handle; char *sdbi_dbname; char *sdbi_userid; char *sdbi_passwd; sdbi_Output_t sdbi_output; } sdbi_Connect_t; The remaining exits return success or failure to AppBuilder. They use the following data structure: typedef struct { long sdbi_sqlcode;
Database Exits in C
sdbi_Connect
} sdbi_Output_t; Be sure to include all the exits! The SDBI library supplied with the product contains exits for Informix isolation-mode processing in addition to the routines described above. Because AppBuilder invokes all the exits, it is important to include all nine routines in your customized shared library. The unused exits can be emptya single statement that returns control works.
sdbi_Connect
Purpose Open a database connection. Use the security exits to pass login information to your DBMS. For details, see Security Exits in C. Prototype #include <stdio.h> #include <stdlib.h> #include <sdbi.h> short sdbi_Connect(sdbi_Connect_t *sdbiconn); Formal Arguments sdbconn Pointer to connection information. Example with sdbi_Connect short sdbi_Connect(sdbi_Connect_t *sdbiconn) { printf("declaring myself connected\n"); sdbiconn->sdbi_output.sdbi_sqlcode = 0; return(0); }
sdbi_StartTxn
Purpose Start a database transaction. Prototype #include <stdio.h> #include <stdlib.h> #include <sdbi.h> short sdbi_StartTxn(sdbi_Output_t *sdbiout); Formal Arguments sdbiout
6-36
sdbi_CommitTxn
Database Exits in C
Pointer to the DBMS error code for a start transaction operation. Example with sdbi_StartTxn short sdbi_StartTxn(sdbi_Output_t *sdbiout) { printf("declaring a begin transaction\n"); sdbiout->sdbi_sqlcode = 0; return(0); }
sdbi_CommitTxn
Purpose Commit a database transaction. Prototype #include <stdio.h> #include <stdlib.h> #include <sdbi.h> short sdbi_CommitTxn(sdbi_Output_t *sdbiout); Formal Arguments sdbiout Pointer to the DBMS error code for a commit transaction operation. Example with sdbi_CommitTxn short sdbi_CommitTxn(sdbi_Output_t *sdbiout) { printf("declaring a commit transaction\n"); sdbiout->sdbi_sqlcode = 0; return(0); }
sdbi_AbortTxn
Purpose Abort a database transaction. Prototype #include <stdio.h> #include <stdlib.h> #include <sdbi.h> short sdbi_AbortTxn(sdbi_Output_t *sdbiout);
6-37
Database Exits in C
sdbi_Disconnect
Formal Arguments sdbiout Pointer to the DBMS error code for an abort transaction operation. Example with sdbi_AbortTxn short sdbi_AbortTxn(sdbi_Output_t *sdbiout) { printf("declaring a abort transaction\n"); sdbiout->sdbi_sqlcode = 0; return(0); }
sdbi_Disconnect
Purpose Disconnect from a database. Prototype #include <stdio.h> #include <stdlib.h> #include <sdbi.h> short sdbi_Disconnect(sdbi_Output_t *sdbiout); Formal Arguments sdbiout Pointer to a the DBMS error code for a disconnect operation. Example short sdbi_Disconnect(sdbi_Output_t *sdbiout) { printf("declaring myself disconnected\n"); sdbiout->sdbi_sqlcode = 0; return(0); }
Sample Database Exit Routines

The following sample routines show how you might code the exits for Oracle, a supported DBMS. Follow the examples for the DBMS you are using. #include <stdio.h> #include <stdlib.h> #include <sdbi.h> EXEC SQL INCLUDE SQLCA;
6-38
Database Exits in C
short sdbi_Connect(sdbi_Connect_t *sdbiconn) { EXEC SQL BEGIN DECLARE SECTION; char connect_id[5]; EXEC SQL END DECLARE SECTION; printf("connecting\n"); strcpy(connect_id, "/"); EXEC SQL CONNECT :connect_id; sdbiconn->sdbi_output.sdbi_sqlcode = sqlca.sqlcode; return(sqlca.sqlcode == 0 ? 0 : -1); } short sdbi_Disconnect(sdbi_Output_t *sdbiout) { printf("disconnecting\n"); EXEC SQL COMMIT WORK RELEASE; sdbiout->sdbi_sqlcode = sqlca.sqlcode; return(sqlca.sqlcode == 0 ? 0 : -1); } int sdbi_SetIsolationMode_CS(sdbi_Output_t *sdbiout) { printf("declaring isolation to be set to cursor stability\n"); sdbiout->sdbi_sqlcode = 0; return(0); } int sdbi_SetIsolationMode_RR(sdbi_Output_t *sdbiout) { printf("declaring isolation to be set to repeatable read\n"); sdbiout->sdbi_sqlcode = 0; return(0); } int sdbi_SetIsolationMode_DR(sdbi_Output_t *sdbiout) { printf("declaring isolation to be set to dirty read\n"); sdbiout->sdbi_sqlcode = 0; return(0); } int sdbi_SetIsolationMode_CR(sdbi_Output_t *sdbiout) { printf("declaring isolation to be set to committed read\n"); sdbiout->sdbi_sqlcode = 0; return(0); } short sdbi_StartTxn(sdbi_Output_t *sdbiout) { printf("beginning transaction\n");
6-39
Customized Data Types in C
printf("Note: Oracle requires no start transaction exit"); sdbiout->sdbi_sqlcode = 0; return(0); } short sdbi_CommitTxn(sdbi_Output_t *sdbiout) { printf("committing transaction\n"); EXEC SQL COMMIT WORK; sdbiout->sdbi_sqlcode = sqlca.sqlcode; return(sqlca.sqlcode == 0 ? 0 : -1); return(0); } short sdbi_AbortTxn(sdbi_Output_t *sdbiout) { printf("rolling back transaction\n"); EXEC SQL ROLLBACK WORK; sdbiout->sdbi_sqlcode = sqlca.sqlcode; return(sqlca.sqlcode == 0 ? 0 : -1); return(0); }

The communications marshalling primitives convert data representations specific to the sending platform to platform-independent AppBuilder communications representations. Unmarshalling primitives convert these representations to representations specific to the receiving platform. This topic looks at how you use the system primitives to marshal and unmarshal data types other than the AppBuilder communications standard data types. You customize the shared library for the marshalling functions, rebuild it, and substitute it for the library supplied with the product. In most situations you need only: Identify the new data type to a system table Write customized encoding and decoding routines that call the system primitives Compile the new code and link it into the system network library
AppBuilder communications data types are based on the External Data Representation (XDR) for network representation of standard data types. For a discussion of customer data types, see Using Custom Data Types. For identifying the new data type, see Identifying the Data Type. For writing customized routines, see Writing the Marshalling Functions. For compilation instructions, see Compiling and Linking.
For more information on marshalling, refer to Understanding Performance Marshalling.
6-40
Using Custom Data Types
Using Custom Data Types

If the customized data type is simply an aggregate of existing standard types, the encoding and decoding functions contain only calls to primitive functions. If you create one 64-bit timestamp, for instance, interpreted as composed of two long integers (as opposed to the 96-bit timestamp), the marshalling function on the sending side issues two calls to the primitive function that marshals a long integer. On the receiving side, the unmarshalling function issues two calls to the primitive function that unmarshals a long integer. If the customized data type requires additional manipulationsay, the conversion of a mainframe-based eight-byte character array so that the array appears in inverted order on the workstationthe encoding and decoding functions must do the required manipulation, and the order of events is crucial: If manipulation is at the sending side, the customized marshalling function manipulates the data, then invokes the primitive marshalling functions to send the data If manipulation is at the receiving side, the customized unmarshalling function invokes the primitive unmarshalling functions to accept the data as transmitted, then does the manipulation
To call either primitive or customized functions, AppBuilder reads a table that associates each data type with a pair of pointers, one to a marshalling function, one to an unmarshalling function. Access to the table is by an integer key, which represents a data type as expressed in the control-structure array. Specify a new key when you add a new data type, as described in Identifying the Data Type. Platform-specific versions of the customized functions must be installed on every platform that handles the customized data type.
Identifying the Data Type

Identify a customized data type by adding an entry for it in the system marshalling table and incrementing the value of the #define statement MARSH_TYPES_COUNT in the table. The value must reflect the new number of entries. The source for the system marshalling table is in a platform-specific location, as shown in Table 6-1.
Table 6-1 System marshalling table location
Platform Mainframe UNIX Windows
Table location data set SAMP255, member DNA@MRSH $DNADIR/misc, member dna_mrsh.c \dna\make, member dna_mrsh.c
Each entry in the table is of the type: typedef struct { short Data_Type; char Data_Type_Desc[32]; marsh_func_ptr Marsh_Func_Ptr; marsh_func_ptr Unmarsh_Func_Ptr; } MarshFuncStruct; The items in MarshFuncStruct (the marshalling function structure) are summarized in Table 6-2.
6-41
Writing the Marshalling Functions
Table 6-2
Marshalling function structure items
Item Data_Type Data_Type_Desc Marsh_Func_Ptr Unmarsh_Func_Ptr
Description #define value for the data type, as shown in marshall.h. Customized data types may have a value between DataType_N and DataType_Z, inclusive String that identifies the type description, in quotes Pointer to the marshalling function for the data type Pointer to the unmarshalling function for the data type
The definition for the type marsh_func_ptr follows: typedef int (*marsh_func_ptr)(void *, void *, unsigned short);

Include the prototypes for customized marshalling and unmarshalling functions in dna_mrsh.c or a header file. The prototypes for the functions, whether primitive or customized, are as follows: int dna_Marshall_<lowercase-description-string> (void *handle, void *data, unsigned short data_len); int dna_UnMarshall_<lowercase-description-string> (void *handle, void *data, unsigned short data_len); For example: int dna_Marshall_short(void *handle, void *data, unsigned short data_len); int dna_UnMarshall_long(void *handle, void *data, unsigned short data_len); The formal arguments are summarized in
Table 6-3 Formal arguments for marshalling and unmarshalling functions
Argument handle
Description Pointer to a system-assigned value, to be passed when making calls to other marshalling functions Pointer to an area that contains data in a platform-specific representation In the marshalling function, the parameter points to an area that contains the data to be converted to a system representation. In the unmarshalling function, the parameter points to an area that contains the data that the function converted from a system representation. Number of bytes of data
data
data_len
The customized routines should return 0 for failure, 1 for success, as do the primitives they call. If you include multiple primitive functions in the customized marshalling and unmarshalling routines, make sure the data area pointer and data length passed to the primitive functions are appropriate for the segment of the data they handle, as shown in the Example of Customized Marshalling.
6-42
Compiling and Linking
Example of Customized Marshalling This is an example of a customized marshalling routine. #include <my_mrsh.h> int dna_Marshall_mytype(void *handle, void *data, unsigned short data_len) { char *data_ptr; unsigned short tempdata_len; data_ptr = (char *)data; tempdata_len = 50; if (1 != dna_Marshall_chararr(handle, data, tempdata_len)); return 0; data_ptr = data_ptr + 50; tempdata_len = 4; if (1 != dna_Marshall_long(handle, data_ptr, tempdata_len)); return 0; data_ptr = data_ptr + 4; tempdata_len = 2; if (1 != dna_Marshall_short(handle, data_ptr, tempdata_len)); return 0; data_ptr = data_ptr + 2; if (1 != dna_Marshall_short(handle, data_ptr, tempdata_len)); return 0; return 1; } To protect against a change in system architecture, the system provides the intermediate functions: dna_GetMarshFunction(short DataType); dna_GetUnMarshFunction(short DataType); each of which returns either a pointer to a primitive function or, on failure, NULL. The sole argument in each is the data type of interest, following the data types listed in marshall.h.

This topic looks at how you compile and link directory services exits, database exits, and data marshalling routines for the supported execution platforms with AppBuilder communications. It also describes important usage differences between the command line and graphical user interfaces for the Visual C++ compiler. For security exit compilation in general, see the code samples provided with the product. Using the Visual C++ Compiler Example Directory Services Exits Example Database Exits
6-43
Using the Visual C++ Compiler
Using the Visual C++ Compiler

The procedures described in the code samples for compiling and linking Windows applications show the required options for the Visual C++ command line compiler and linker. These procedures are written according to Visual C++ 6.0. If you use the graphical user interface for the Visual C++ compiler and linker, you must ensure that the compiler and linker options match exactly those given for command line compiling and linking. You can verify the current option settings by checking them in the IDE. Visual C++ shows the current settings in the IDE whenever a build option is selected. Table 6-4 shows options you should not use to compile and link applications in Visual C++ .
Table 6-4 Visual C++ options to disable
Feature Function-level linking Minimal rebuild Incremental compilation Incremental link
Default in IDE disabled enabled disabled enabled
Command Line Option /Gy /Gm /Gi /incremental:yes
Table 6-5 shows options you should use to compile and link applications in Visual C++.
Table 6-5 Required Visual C++ options
Feature Runtime DLL Calling convention Structure packing
Default in IDE /ML [cdecl] /Zp8
Required Option /MD /Gz [stdcall /Zp1
To edit the settings in the IDE follow these steps: 1. 2. 3. 4. Make sure to add the module definition (.DEF) file for each exit to the project with the /Insert/Files Into Project command. A sample module definition file appears in the code samples. In the Project menu, select the Settings menu item. In the C/C++ tab, select the category Customize. In the Link tab, select the category General.
Example Directory Services Exits

This example shows a makefile for the directory services shared library. There are statements for the IBM AIX platform, the Sun Solaris platform, and the Hewlett-Packard HP-UX platform. Adapt the example to the platform on which you are executing the exits. # extds.h, marshall.h, and extds.exp are in nete release # include directory AIX_CC=/bin/cc AIX_LD=/bin/ld AIX_CFLAG= -qlanglvl=ansi -DRS6000 -DUNIX -DAIX AIX_IFLAG=-I./ -I../include AIX_LIB=-lc AIX_LDFLAG=-bE:extds.exp -bM:SRE AIX_LIBEXTDS=extds.so AIX_TGT=libextds_shar
6-44
Example Database Exits
SOLARIS_CC=/opt/SUNWspro/bin/cc SOLARIS_LD=/opt/SUNWspro/bin/cc SOLARIS_CFLAG= -Xa -Kpic -DSOLARIS -DSUN -DUNIX -DSVR4 SOLARIS_IFLAG=-I./ -I../include SOLARIS_LIB=-ldl SOLARIS_LDFLAG=-G SOLARIS_LIBEXTDS=libextds.so SOLARIS_TGT=libextds HP-UX_CC=/bin/cc HP-UX_LD=/bin/ld HP-UX_CFLAG= -Ac -Ae +Z -DHP_UX -DUNIX -DSVR4 HP-UX_IFLAG=-I./ -I../include HP-UX_LIB=-lc HP-UX_LDFLAG=-b HP-UX_LIBEXTDS=libextds.sl HP-UX_TGT=libextds
all: make -f extds.mk "OS=$(OS)" "CC=$($(OS)_CC)" "LD=$($(OS)_LD)" \ "CFLAG=$($(OS)_CFLAG)" "IFLAG=$($(OS)_IFLAG)" \ "LIBEXTDS=$($(OS)_LIBEXTDS)" "LIBS=$($(OS)_LIB)" \ "LDFLAG=$($(OS)_LDFLAG)" \ $($(OS)_TGT) libextds: extds.o $(LD) -o $(LIBEXTDS) extds.o $(LDFLAG) $(LIBS) extds.o: extds.c extds.h marshall.h $(CC) -c $(CFLAG) $(IFLAG) extds.c libextds_shar: libextds /bin/ar vr libextds.a $(LIBEXTDS) install: clean:

This example shows a makefile for database exits. Adapt the example to the platform on which you are executing the exits. The example DLLs are listed in EXECUTABLESyou can assign them different names, if needed. The entry points must be specified exactly as shown. DNADIR = /u/nes/ne30 PROC = proc PROFLAGS = PARSE=NONE MODE=ANSI IRECLEN=200 ORECLEN=200 SERVICE_CFLAGS = -DUNIX -DTSERVER -D__SERV__ -D__CONNECTION__ \ -I$(DNADIR)/include -I. CFLAGS DFLAGS IFLAGS HDRS = LIBS = = -DORACLE $(SERVICE_CFLAGS) = = -I./ -I$(DNADIR)/include -lc
6-45
CC = FULLY_QUALIFIED_COMPILER_NAME $(CFLAGS) $(DFLAGS) $(IFLAGS) LD = FULLY_QUALIFIED_LINKER_NAME EXECUTABLES = apendbg.dll all: ${EXECUTABLES} clean sdbi_emp.o: sdbi_emp.c $(CC) -c sdbi_emp.c sdbi_ora.c: sdbi_ora.pc $(PROC) $(PROFLAGS) INAME=sdbi_ora.pc ONAME=sdbi_ora.c sdbi_ora.o: sdbi_ora.c $(CC) -c sdbi_ora.c libsdbi_emp.a: sdbi_emp.o $(LD) -o libsdbi.a sdbi_emp.o -bE:sdbi.exp -bM:SRE -lc mv libsdbi.a libsdbi_emp.a libsdbi_ora.a: sdbi_ora.o $(LD) -o libsdbi.a sdbi_ora.o -bE:sdbi.exp -bM:SRE \ -L$(ORACLE_HOME)/lib \ -lsql $(ORACLE_HOME)/lib/osntab.o -lsqlnet -lora \ -lpls -lnlsrtl3 -lc3v6 -lcore3 \ -lm -lld -lm -lc mv libsdbi.a libsdbi_ora.a opendbq.dll:opendbq.pc $(PROC) $(PROFLAGS) INAME=opendbq.pc ONAME=opendbq.c $(CC) $(CFLAGS) -c -DRULE_HEADER=\"VOPENDBQ.h\" \ opendbq.c $(DNADIR)/misc/srv_gen.c $(LD) -o opendbq.dll opendbq.o srv_gen.o $(SERVICE_LFLAGS) \ -bI:opendbq.imp -L. -lc clean:
6-46
APPENDIX
CODE PAGE SUPPORT
AppBuilder lets you off-load code-page conversions to clients or servers as appropriate. At runtime, it compares two code-page references on the local machine: The LOCAL_CODEPAGE variable in the NLS section of DNA.INI The Code Page field in the route table, or the corresponding variable in ROUTING section of dna.ini, SMA section of dna.ini, or the call to the functions dna_BoundServiceRequest or dna_BoundDynamicRequest. If the values are different, it converts the data to be transmitted to the route table or corresponding value. If the value is a hyphen (-) in the route table, blank in dna.ini, or the null character in the function call, no conversion occurs. The system then compares two code-page references on the remote machine: The LOCAL_CODEPAGE variable in the NLS section of dna.ini A code page identifier in the transmitted data If the values are different, AppBuilder converts the transmitted data to the code page specified in dna.ini. It is usually more efficient to perform code-page conversion on the client. Conversions to double-byte character sets rely on native operating-system routines. AppBuilder sends text files in ASCII format. If the destination is a mainframe, it converts the text to EBCDIC.
Supported Code Pages

The first column in Table A-1 displays the valid code page names for the AppBuilder communications software. Names used in UNIX and OS/2 may be useful for low-level communication routines but are not valid in AppBuilder.
A-1
Supported Code Pages
Table A-1 Unicode Name for Java Cp037 Cp0280 Cp284 Cp285
Communications supported code pages
AppBuilder Name IBM037 IBM280 IBM284 IBM285 IBM290
UNIX Name IBM-037 IBM-280 IBM-284 IBM-285 IBM-290 IBM-437 IBM-500 IBM-833 IBM-836 IBM-850 IBM-860 IBM-863 IBM-865 IBM-930 IBM-932 IBM-933 IBM-939 IBM-942 IBM-949 IBM-1004 IBM-1027 IBM-1041 IBM-1088 IBM-1115 IBM-eucJP IBM-eucKR ISO8859-1
OS/2 Name 37 280 284 285 290 437 500 833 836 850 860 863 865 930 932 933 939 942 949 1004 1027 1041 1088 1115 NA NA 8859
Use in AppBuilder Mainframe: U.S. English Mainframe: Italian Mainframe: Spanish Mainframe: U.K. English Mainframe: Single-byte Katakana Windows: U.S. English Mainframe: German Mainframe: Single-byte Korean Mainframe: Single-byte simplified Chinese Windows: Multilingual Windows: Portuguese Windows: French Canadian Windows: Nordic Mainframe: Kanji Windows: Kanji Mainframe: Korean Mainframe: Kanji OS/2: Kanji OS/2: Korean Windows: U.S. English Mainframe: Single-byte Japanese Latin Windows: Single-byte Japanese Latin Windows: Single-byte Korean Windows: Single-byte simplified Chinese AIX: Kanji AIX: Kanji UNIX: U.S. English
Cp437 Cp500
IBM437 IBM500 IBM833 IBM836
Cp850 Cp860 Cp863 Cp865 Cp930 IBM932 Cp933 Cp939 Cp942 Cp949
IBM850 IBM860 IBM863 IBM865 IBM930 IBM932 IBM933 IBM939 IBM942 IBM949 IBM1004 IBM1027 IBM1041 IBM1088 IBM1115 IBMeucJP IBMeucKR ISO8859-1
Table A-2 Unicode Name for Java
Runtime supported code pages
AppBuilder Name IBM1250 IBM1253 IBM0852 IBM0869
UNIX Name IBM-1250 IBM-1253 IBM-0852 IBM-0869
OS/2 Name 1250 1253 0852 0869
Use in AppBuilder Windows: Czech Windows: Greek OS/2: Czech OS/2: Greek
A-2
Code Page Support
Supported Code Page Conversions

The top or horizontal axis in Table A-3 lists the code pages available in client environments. The side or vertical axis lists the code pages available in server environments.
Table A-3 Supported code page conversions ISO8859-1 X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X IBMeucJP IBM1004 IBM1027 IBM1041 IBM1088 IBM1115
A-3
IBM037
IBM280
IBM284
IBM285
IBM290
IBM437
IBM500
IBM833
IBM836
IBM850
IBM860
IBM863
IBM865
IBM930
IBM932
IBM933
Code Page IBM037 IBM280 IBM284 IBM285 IBM290 IBM437 IBM500 IBM833 IBM836 IBM850 IBM860 IBM863 IBM865 IBM930 IBM932 IBM933 IBM949 IBM1004 IBM1027 IBM1041 IBM1088 IBM1115 IBMeucJP ISO8859-1
X X X X X X X
X X X X X X X
X X X X X
X X X X X X
X X
X X X
X X
X X
IBM949
A-4
Code Page Support
APPENDIX
MAINFRAME LOGON SCRIPT
Use the LU2 scripting language described in this section to configure the mainframe logon. Change the MFLOGON.SCR file that comes with the BluePhoenix AppBuilder standard installation to reflect site-specific logon procedures. If the script-mediated logon is unsuccessful, try adding WAIT commands or increasing the WAIT and WAITSTRING values. Every non-blank line in a logon or logoff script must begin with a comment marker (//) or a verb. The verbs in the AppBuilder logon script language are: COMPARE CONNECTPS DISCONNECTPS DOWNLOAD_FILE FINDSTRING GETCURSOR GOTO IF INC RETURN Return values are not available to the script. When a verb returns a non-zero value, AppBuilder quits interpreting the script and writes an error message to the file identified in the TRCFILE variable in the TRACING section of the communications configuration file dna.ini. An error code is set for use by the client application. SEND SESSION_LIST SET SETCURSOR SETNETNAME SETTERMID WAIT WAITSTRING WRITE
B-1
Logon Script Reference

In the following descriptions, a parameter value can be a literal. Character or string literals must be in quotes.
COMPARE
Compares a string with the data that begins at the current cursor position on the host display. The value is 0 if identical, non-zero otherwise. COMPARE string; For example: COMPARE "000";
CONNECTPS
Establishes a connection between the client application and one of the session IDs supplied by SESSION_LIST. The value is 0 if successful, non-zero otherwise. CONNECTPS;
DISCONNECTPS
Drops the connection between the client application and the terminal session. The value is 0 if success, non-zero otherwise. DISCONNECTPS;
DOWNLOAD_FILE
Downloads a file from the host. DOWNLOAD_FILE file; For example: DOWNLOAD_FILE "HS01";
FINDSTRING
Searches the host display for a string. The value is 0 if success, non-zero otherwise. FINDSTRING string; For example: FINDSTRING "READY";
B-2
GETCURSOR
Returns the current cursor position on the host display into variables x and y.The value is 0 for success, non-zero otherwise. GETCURSOR x y; For example: GETCURSOR SYSVAR1 SYSVAR7;
GOTO
Transfers flow of control to the line that contains the specified label. GOTO label; For example: GOTO SUCCESS;
IF
Performs a logical operation on two simple expressions and executes the specified command when the result of the logical operation is true. The following operands are valid: EQ, LT, GT, NE, LE, GE. IF expression operand expression command; For example: IF STATUSLEVEL EQ 0 GOTO SUCCESS;
INC
Increments a system variable by an integer value or the contents of another system variable. INC x integer or y; For example: INC SYSVAR2 20;
RETURN
Ends execution of the script file. The value is 0 if success, non-zero otherwise. RETURN 0;
SEND
Sends one or more keystrokes to the connected terminal session: LEFT_TAB, RIGHT_TAB, CLEAR, ENTER, CURSOR_LEFT, CURSOR_RIGHT, CURSOR_UP, CURSOR_DOWN, NEW_LINE, SPACE, RESET, HOME, PA1 through PA3, PF1 through PF24, PLUS, END, and SYSREQ. Use the variable HOSTNAME as shown in the example below if you want to send the value specified in the route table Host field. The value is 0 if success, non-zero otherwise.
B-3
SEND one_or_more_keystrokes; For example: SEND HOSTNAME ENTER Make sure to put spaces around keywords (except at the end of a line). The following example shows the correct syntax: SEND "LOGON APPLID(" HOSTNAME ")" ENTER; As the example shows, the keyword HOSTNAME must be surrounded by spaces. You do not need to put a space after ENTER because it comes at the end of the line.
SESSION_LIST
Lists the sessions available for CONNECTPS to use. SESSION_LIST list_of_session_IDs; For example: SESSION_LIST "A" "B" "C" "D";
SET
Initializes a system variable with an integer value or the contents of another system variable. SYSVAR1 through SYSVAR9 are available for use as system variables. SET x integer or y; For example: SET SYSVAR2 SYSVAR1;
SETCURSOR
Sets the cursor position. SETCURSOR row_number column_number For example: SETCURSOR 4 20;
SETNETNAME
Sets the network name. SETNETNAME
SETTERMID
Sets the terminal identifier. SETTERMID
B-4
WAIT
Waits for the number of seconds specified. WAIT number_of_seconds; For example: WAIT 2;
WAITSTRING
Waits for the specified number of seconds until the specified string appears on the host screen. Follow this command with a WAIT 2. The value is 0 if the string appears within the time specified, non-zero otherwise. WAITSTRING string number_of_seconds; For example: WAITSTRING "LOGONID" 20; WAIT 2;
WRITE
Copies text to the host screen at the current cursor location. The value is 0 if successful, non-zero otherwise. WRITE one_or_more_strings For example: WRITE "CACF" USERID PASSWORD NEWPASSWORD "1" "0" "0";
B-5
B-6
Index
INDEX
A
abort transaction exit 6-37 abprdinf command, find product version 2-7 abservice command, AppBuilder service 2-7 adding a JMS server 2-20 adding a NetEssential server 2-21 adding an EJB server 2-20 adding an RMI server 2-22, 2-23 admin utility for MVS 4-1 agent configuring on a UNIX host 3-23, 3-28 alternate routing 2-37 AppBuilder Management Console, see Management Console. AppBuilder MQ Listener debug trace level 5-10 process queue expiry 5-9 rollback 5-10 timeout value 5-9 AppBuilder MQ Processor 5-2 AppBuilder MQ Processor (DNALSTMQ) 5-2 AppBuilder Run-Time 5-2 AppBuilder service control 2-7 AppBuilder system service defined 2-5 appbuildercom.ini file 6-3 APPCLLU 4-6 ASCII format sent A-1 ASCII to EBCDIC conversion 4-7 Attachmate EXTRA! 4-6 audit information 2-11 authentication 6-4, 6-14 authentication exit 2-27, 6-4, 6-20 Authentication exit (Java) 6-2, 6-6 AuthentLibMain 6-20 Authorisation exit (Java) 6-2, 6-6 authorization 6-16 authorization exit 6-21, 6-23 AuthorLibMain 6-21
Buffer Close exit 6-27 buffer close exit 6-27
C
C370 runtime, linking security exits 6-19 character encoding A-1, A-3 CICS performance marshalling 4-8 CICS, linking security exits 6-19 Clear Audit Information 2-11 clear trace log 2-16 client configuring on a UNIX host 3-6, 3-22, 3-27 configuring on Java 2-17 configuring on Windows 2-23 client configuration EJB server 2-20 JMS server 2-20 NETE server 2-21 RMI server 2-22, 2-23 Client Exits tab 2-26 close semantics 2-25 UNIX server 3-21 code page 2-33 conversion A-1, A-3 conversion in UNIX 3-9, 3-17, 3-25 identifier A-1 support A-1 commit transaction exit 6-37 communications administration 2-1 exits 6-1 Management Console 2-9 MQSeries RPC support 5-1 on mainframe 4-1 on UNIX 3-1 routing 2-31 setup 2-1 system service 2-5 communications configuration file (dna.ini) 2-34, 3-6, 3-16, 6-19, 6-29 communications exits Java clients 6-2 COMPARE - logon script B-2 compiler, Visual C++ 6-44
B
backup log file, path name 2-27 batch server configuring on a UNIX host 3-29
compiling and linking exit routines 6-43 Compression exit (Java) 6-2, 6-7 computer clear audit info 2-11 refresh 2-12 remove 2-12 view audit info 2-11 view product information 2-10 computer inactive 2-10 configuration, gateway 2-29 configure RPC client 2-17, 2-23 configure terminal emulator 4-6 connection exit 6-36 CONNECTPS - logon script B-2 console actions 2-15 clear audit info 2-11 clear trace log 2-16 delete server or gateway 2-16 edit configuration (.ini) file 2-10 modify server or gateway properties 2-16 pinging server or gateway 2-16 refresh computer 2-12 refreshing server, gateway 2-16 remove computer 2-12 starting, stopping server 2-15 view audit info 2-11 view product information 2-10 view trace log 2-16 constraint-based validation 6-17 converting to EBCDIC A-1 creating a gateway 2-14 creating a server 2-13 Custom Server configuration 2-23 customized data types creating 6-40
D
data encryption 6-18, 6-24 data types, custom 6-40 database configuration for UNIX 3-31 database connect 6-16 database exits coding 6-36 compiling and linking 6-45 disconnection 6-37 discussed 6-35 examples 6-38 database interface 6-35 data-dependent routing 2-39 DB2, configuring communications for 3-32 dead-letter queue 5-2, 5-8
debug information 2-18, 3-7, 3-10, 3-12, 3-16, 3-19, 3-20, 3-26, 5-10 debug level 2-18, 3-7, 3-10, 3-12, 3-13, 3-16, 3-19, 3-20, 3-26, 5-10 decoding data exit 6-27 Decoding Data exit (Java) 6-2, 6-8 decrypting user info 6-22 decrypting user info exit 6-22 Decryption exit (Java) 6-2, 6-7 default entry in authentication exit 6-15 delete server or gateway 2-16 directory services exits coding 6-30 compiling and linking 6-44 configuring on a UNIX host 3-8 discussed 6-28 disconnect exit 6-38 DISCONNECTPS - logon script B-2 display of inactive computer 2-10 DNA INI file on mainframe caching 4-5 MQMSG settings 5-8 dna.h 6-25 dna.ini file 2-34, 3-6, 3-16, 5-2, 6-29, A-1 security exit variables 6-19 TRACING section B-1 UNIX client 3-14 UNIX eventing client or server 3-28 UNIX server 3-20 DNA@MRSH member 6-41 DNA_AUTHENT_EXIT 6-19 DNA_AUTHOR_EXIT 6-19 dna_BoundDynamicRequest A-1 dna_BoundServiceRequest A-1 dna_BufClose 6-27 dna_BufDecode 6-27 dna_BufEncode 6-26 dna_BufInit 6-25 DNA_ENCRYPT_EXIT 6-19 dna_ExtEvents 6-34 dna_ExtRoutes 6-30 dna_ExtSubcells 6-32 dna_ExtTriggers 6-33 dna_GetMarshFunction 6-43 dna_GetUnMarshFunction 6-43 dna_Marshall 6-42 DNA_MAX_ROUTES setting in dna.ini 2-35 DNA_NUMBER_OF_RETRIES setting in dna.ini 2-35 DNA_RETRY_INTERVAL setting in dna.ini 2-35 DNA_RPC_END_EXIT 6-19 DNA_SERVER setting in dna.ini 3-21 dna_UnMarshall 6-42 DNAINIRD program 4-5
ii
DNALSTMQ 5-2 DOWNLOAD_FILE - logon script B-2
External Data Representation (XDR) 4-8, 6-40 Extra emulator 4-6
E
EBCDIC, converting to A-1 Edit INI from console 2-10 EJB (Enterprise Java Bean) 2-20 EJB server 2-20 emulator 4-6 encoding (character) support A-1 encoding data exit 6-26 Encoding Data exit (Java) 6-2, 6-7 encrypting user info exit 6-22 encryption 6-17, 6-24 open data 6-18 Encryption exit (Java) 6-2, 6-7 EncryptLibMain 6-22 end-flag entry in authentication exit 6-15 entry point 6-1 error handling (MQSeries RPC) 5-10 error log (trace) file 3-7, 3-10, 3-12, 3-16, 3-19, 3-20, 3-26 error-dependent routing 2-40 eventing configuring on a UNIX host 3-27 execution server configuring on a UNIX host 3-16, 3-22, 3-27 exit Exit ID, Value, and Status 2-26 exit configuration directory services 3-8 notification 3-28 security 3-10, 3-19 Exit ID 2-26 exits 2-26 buffer clean-up 6-27 Buffer Close 6-27 compiling and linking 6-45 compiling directory services 6-44 database 6-35 decode data 6-27 decrypt user info 6-22 directory services 6-28 discussed 6-1 encode data 6-26 encrypting user info 6-22 ending service request action 6-24 initialize 6-25 Java 6-2 RPC end 6-18 security 6-14 trace 6-18 user authentication 6-20 user authorization 6-21, 6-23 Exits tab 2-26 extds.h 6-28
F
file appbuildercom.ini 6-3 dna.ini 2-34, 3-6, 3-16, 5-2, 6-19, 6-29, A-1, B-1 dna.ini in UNIX 3-14 hps.ini 2-1, 2-8, 2-10, 6-16 trace 3-13 FINDSTRING - logon script B-2 forwarding server configuring on a UNIX host 3-16
G
gateway configuration 2-29 configuring on a UNIX host 3-31 creating 2-14 delete 2-16 modify 2-16 ping 2-16 properties 2-15 protocol 2-15 refresh 2-16 starting 2-15 stopping 2-15 GETCURSOR - logon script B-3 global eventing configuring on a UNIX host 3-27 GOTO - logon script B-3
H
Hide Service Control 2-7 hiding Service Control 2-7 hps.ini file 2-1, 2-8, 2-10, 6-16
I
IBM Personal Communications emulator 4-6 IBM-supplied trigger monitor 5-2 IF - logon script B-3 implicit eventing configuring on a UNIX host 3-27 IMS logon/logoff scripts for LU2 4-5 inactive icon 2-10 inbound characteristics 2-29 INC - logon script B-3 initializing data encryption exit 6-25 installed product information 2-10 interval retry 2-35
Index
iii
IPC_KEY 3-28
J
Java custom transport 6-9 Java client 6-2 properties 2-18 Java clients communications exits 6-2 Java compiler 6-2 Java exit 6-2 Authentication 6-2, 6-6 Authorisation 6-2, 6-6 Compression 6-2, 6-7 Decoding Data 6-2, 6-8 Decryption 6-2, 6-7 Encoding Data 6-2, 6-7 Encryption 6-2, 6-7 RPC End 6-2, 6-7 Trace 6-7 JMS (Java Messaging Service) 2-20, 5-1 JMS server 2-20
LOGON_SCRIPT 4-5 LU2 client configuration 4-5 LU2 communications 4-6 LU2_IDLL values 4-6 LU6.2 2-27
M
mainframe admin utility 4-1 DNA INI file 5-8 logon/logoff scripts for LU2 4-5 make files 6-43 Management Console 2-1, 2-6 launching 2-7, 2-8 marshall.h 6-28, 6-43 marshalling coding 6-41 customizing 6-40 defined 4-7 functions 6-42 performance marshalling 4-8 primitives 6-40 see customized data types marshalling table 6-41 messaging configuring on a UNIX host 3-22 MQSeries 3-22 native 3-22 mknesuer utility 3-2 MODE_NAME 4-5 modify properties of server or gateway 2-16 MQ Processor 5-2 MQ Run-Time 5-2 MQMSG section of DNA INI 5-8 MQSeries messaging configuration 3-23 MQSeries RPC 5-1 process overview 5-2 typical configurations 5-1 multiple-server routing 2-17 MVS CICS admin utility 4-1
L
launching Management Console 2-7, 2-8 LE370 runtime, linking security exits 6-19 level of logging 2-27, 3-13 linking security exits in CICS 6-19 Listener, MQ 5-9, 5-10 LOCAL_CODEPAGE variable A-1 log, clearing or viewing 2-16 logical unit of work values, table of 2-25 LOGOFF_SCRIPT 4-5 Logon scripting command COMPARE B-2 CONNECTPS B-2 DISCONNECTPS B-2 DOWNLOAD_FILE B-2 FINDSTRING B-2 GETCURSOR B-3 GOTO B-3 IF B-3 INC B-3 RETURN B-3 SEND B-3 SESSION_LIST B-4 SET B-4 SETCURSOR B-4 SETNETNAME B-4 SETTERMID B-4 WAIT B-5 WAITSTRING B-5 WRITE B-5
N
NEAD transaction 4-1 NEADMAIN program 4-1 NEADMAP mapset 4-1 necfg.as.root utility 3-33 NetEssential server 2-21 NetManage Rumba 4-6 network protocol 2-13, 2-14, 2-15, 2-28, 2-30 New Gateway 2-14 New Server 2-13 new_inetd.conf_file 3-6
iv
new_services_file 3-6 notification exit configuring on a UNIX host 3-28
O
open data encryption 6-18, 6-24 OpenCOBOL performance marshalling 4-8 Oracle, configuring communications for 3-32 ORACLE_HOME environment variable 3-32 ORACLE_SID environment variable 3-32 outbound characteristics 2-29
P
password 2-26 password encryption 6-17 PComm emulator 4-6 Performance Marshalling overview 4-7 performance marshalling defined 4-8 protocols 4-8 ping server or gateway 2-16 pointers 6-15 polling interval 2-18, 3-12, 3-20 primitives marshalling Process Queue 5-2 product version information 2-7 properties custom server 2-23 Java client 2-18 properties for gateway 2-15 properties of server 2-14 protocol 2-13, 2-14, 2-15, 2-28, 2-30 gateway 2-15 server 2-14 protocol-independent host name 3-25 protocols performance marshalling 4-8
remote procedure calls (RPCs) 2-37 Remove Computer from console 2-12 retries, number of 2-35 retry interval 2-35 RETURN - logon script B-3 RMI (remote method invocation) 2-22 RMI server 2-22, 2-23 route table A-1 alternate 2-37 data-dependency 2-39 error-dependency 2-40 ROUTETBL setting in dna.ini 2-35 routes maximum number of 2-35 ROUTETBL variable in dna.ini 2-35 routing multiple-server 2-17 single-server 2-17 RPC defined 2-37 end exit 6-18, 6-24 RPC client configuration on Windows 2-17, 2-23 configuring on a UNIX host 3-6 RPC End exit (Java) 6-2, 6-7 RPC server configuring on a UNIX host 3-16, 3-22, 3-27 RPC timeout 2-18, 3-12 RpcEndLibMain 6-24 RpcEndLibMain exit 6-24 Rumba emulator 4-6
S
SCRIPT_DIR 4-5 SDBI (database interface library) 6-35 sdbi.h 6-35 security configuration 2-26 security exits 2-24, 2-26, 6-14 coding 6-18 configuring on a UNIX host 3-10, 3-19 dna.ini variables 6-19 SEND - logon script B-3 server configuring on a UNIX host 3-16, 3-22, 3-27 creating 2-13 delete 2-16 EJB server 2-20 ID 2-17 JMS server 2-20 modify 2-16 NETE server 2-21 ping 2-16
Q
quick configuration 3-1
R
rc file (UNIX) 3-33 reflection order 2-18 Refresh Computer display in console 2-12 refresh Management Console 2-10 refresh server or gateway 2-16
Index
properties 2-14 protocol 2-14 refresh 2-16 RMI server 2-22, 2-23 starting 2-15 stopping 2-15 server close semantics 3-21 Server Exits tab 2-26 server/agent pairs 3-3, 3-6, 3-21 Service Control 2-5 command line 2-7 hiding icon 2-7 menu 2-6 services per server setting in dna.ini 3-21 SESSION_LIST - logon script B-4 SET - logon script B-4 SETCURSOR - logon script B-4 SETNETNAME- logon script B-4 SETTERMID - logon script B-4 single-server routing 2-17 size of log file 2-27 SRV_AUTHENT_EXIT 6-19 SRV_AUTHOR_EXIT 6-19 SrvAuthentLibMain 6-22 SrvAuthorLibMain 6-23 start transaction exit 6-36 starting System Service 2-7 starting, stopping gateway 2-15 STATIC_LINK 6-19 stdio.h 6-35 stdlib.h 6-35 stopping System Service 2-7 subcell table mainframe format 4-3 subsystem for eventing 3-28 supported code page A-3 supported code pages A-1 system configuration (hps.ini file) 2-10 system marshalling table 6-41 System Service starting and stopping 2-7 system service defined 2-5 system table (for marshalling) 6-41
Trace exit (Java) 6-7 trace exits 6-18 trace file configuring on a UNIX host 3-12 trace file name 3-13 trace log, clearing or viewing 2-16 trace output log file 2-18, 3-7, 3-10, 3-12, 3-16, 3-19, 3-20, 3-26, 5-10 tracing 2-18, 3-7, 3-10, 3-12, 3-16, 3-19, 3-20, 3-26, 5-10 TRACING section 5-10, B-1 Transport custom in Java 6-9 Trigger Monitor for CICS 5-2 triggers configuring on a UNIX host 3-27 typical configurations, MQSeries RPC 5-1
U
unmarshalling see marshalling updating communications software 3-2 updnesuser utility 3-2 user authentication exit 6-20 user authorization exit 6-21, 6-23 user info encrypting exit 6-22 UserExitExample.class 6-2 using Service Control 2-6
V
verification setting 5-2 version information 2-7, 2-10 view audit information 2-11 view product information 2-10 view trace log 2-16 Visual C++ compiler 6-44
W
WAIT - logon script B-5 WAITSTRING- logon script B-5 workstation ID for exit 6-16 WRITE- logon script B-5
T
TCP/IP server 2-17 TERM environment variable 3-3 terminal emulator 4-6 TERMINFO environment variable 3-3 ticket 6-16, 6-18, 6-20, 6-21, 6-23, 6-24 timeout RPC 2-18, 3-12
X
XDR 4-8, 6-40
vi

APP BUILDER ConfiguringComm

Caricato da

Informazioni sul documento

Descrizione originale:

Copyright

Formati disponibili

Condividi questo documento

Condividi o incorpora il documento

Opzioni di condivisione

Hai trovato utile questo documento?

Questo contenuto è inappropriato?

Copyright:

Formati disponibili

APP BUILDER ConfiguringComm

Caricato da

Copyright:

Formati disponibili

BluePhoenix AppBuilder 2.1.0.

Configuring Communications Guide

AppBuilder 2.1.0 Configuring Communications Guide

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

AppBuilder 2.1.0 Configuring Communications Guide

Configuring Communications in UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1

AppBuilder 2.1.0 Configuring Communications Guide

Configuring Communications on the Mainframe . . . . . . . . . . . . . . . . . . 4-1

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

Extending Communications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1

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

Mainframe Logon Script

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

AppBuilder 2.1.0 Configuring Communications Guide

AppBuilder 2.1.0 Configuring Communications Guide

AppBuilder 2.1.0 Configuring Communications Guide

CONFIGURING AND MANAGING COMMUNICATIONS IN WINDOWS

AppBuilder 2.1.0 Configuring Communications Guide

Setting Up Windows Communications

AppBuilder 2.1.0 Configuring Communications Guide

Setting Up Windows Communications

Launching the Communications Setup

Understanding the Setup

Setting Up Windows Communications

AppBuilder 2.1.0 Configuring Communications Guide

Setting Up Windows Communications

Configuring and Managing Communications in Windows

Managing the System Service

Other Initial Communications Configuration

Managing the System Service

AppBuilder 2.1.0 Configuring Communications Guide

Managing the System Service

Launching the Service Control

Select Service Control

Icon for Service Control

Using the Service Control

Configuring and Managing Communications in Windows

Managing the System Service

Service Control menu

Hiding the Service Control Icon

Starting or Stopping the System Service

Launching Management Console

Command Line Control

AppBuilder 2.1.0 Configuring Communications Guide

Managing the System Service

Launching the Management Console

Select Management Console

Configuring and Managing Communications in Windows

Managing the System Service

Understanding the Console

Graphical Display mach_second Resource icons

AppBuilder 2.1.0 Configuring Communications Guide

Viewing Product Information

Editing the Configuration File

Each section of the file is available on a tab.

Each variable of that section is available in this list.

You can modify the value and click Set.

If there is help available for that value, it is displayed here.

Viewing Product Information

Configuring and Managing Communications in Windows

Viewing or Clearing Audit Information

Viewing or Clearing Audit Information

Managing the Computers