SG 244689

Personal Communications Version 4.
3
for Windows 95, 98 and NT
Julian Over, Falk Doege, Olaf Graf, Matthew Radford
International Technical Support Organization
http://www.redbooks.ibm.com
SG24-4689-01
SG24-4689-01
International Technical Support Organization
Personal Communications Version 4.3

for Windows 95, 98 and NT
August 1999
Take Note!
Before using this information and the product it supports, be sure to read the general information in Appendix B,
“Special notices” on page 159.
Second Edition (August 1999)
This edition applies to IBM SecureWay Personal Communications Version 4.3 for Windows 95, 98 and NT.
Comments may be addressed to:

IBM Corporation, International Technical Support Organization
Dept. HZ8 Building 678
P.O. Box 12195
Research Triangle Park, NC 27709-2195
When you send information to IBM, you grant IBM a non-exclusive right to use or distribute the information in any
way it believes appropriate without incurring any obligation to you.
© Copyright International Business Machines Corporation 1996 1999. All rights reserved.
Note to U.S Government Users - Documentation related to restricted rights - Use, duplication or disclosure is subject to restrictions
set forth in GSA ADP Schedule Contract with IBM Corp.
Contents
Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi
The team that wrote this redbook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi
Comments welcome . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii
Chapter 1. Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. . . . . .. . . . . .1
1.1 Installation Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. . . . . .. . . . . .1
1.1.1 Installation Manager highlights . . . . . . . . . . . . . . . . . .. . . . . .. . . . . .1
1.1.2 Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. . . . . .. . . . . .1
1.1.3 Installing products . . . . . . . . . . . . . . . . . . . . . . . . . . . .. . . . . .. . . . . .2
1.2 Installation overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. . . . . .. . . . . .4
1.3 Migration of previous configuration files . . . . . . . . . . . . . . .. . . . . .. . . . . .5
1.3.1 Migrating CM/2 configurations . . . . . . . . . . . . . . . . . . .. . . . . .. . . . . .6
1.3.2 Migrating PCOMM configurations . . . . . . . . . . . . . . . .. . . . . .. . . . . .6
1.4 Unattended (silent) installation . . . . . . . . . . . . . . . . . . . . . .. . . . . .. . . . . .7
1.5 Installation of PCOMM using Microsoft SMS . . . . . . . . . . . .. . . . . .. . . . . .8
1.6 Remote installation using Tivoli Courier . . . . . . . . . . . . . . .. . . . . .. . . . . .8
1.6.1 Using Profile Manager . . . . . . . . . . . . . . . . . . . . . . . . .. . . . . .. . . . . .9
1.7 Configuration file update support . . . . . . . . . . . . . . . . . . . .. . . . . .. . . . . .9
1.7.1 How update files are created . . . . . . . . . . . . . . . . . . . .. . . . . .. . . . . .9
1.7.2 Using update files to change your configuration . . . . .. . . . . .. . . . .10
1.7.3 Using initial definition files to preload a configuration .. . . . . .. . . . .12
1.8 Installation usability improvements . . . . . . . . . . . . . . . . . . .. . . . . .. . . . .12
1.8.1 Validate server when installing client. . . . . . . . . . . . . .. . . . . .. . . . .13
1.8.2 Choose SNA type during a server installation . . . . . . .. . . . . .. . . . .13
1.8.3 Internationalization (I18N) . . . . . . . . . . . . . . . . . . . . . .. . . . . .. . . . .13
1.9 Problem determination . . . . . . . . . . . . . . . . . . . . . . . . . . . .. . . . . .. . . . .13
1.9.1 Installation Manager problems . . . . . . . . . . . . . . . . . .. . . . . .. . . . .13
1.9.2 SSL installation problems . . . . . . . . . . . . . . . . . . . . . .. . . . . .. . . . .14
1.9.3 Silent-installation problems . . . . . . . . . . . . . . . . . . . . .. . . . . .. . . . .15
Chapter 2. Securing your connections - SSL and firewalls .. . . . . .. . . . .17

2.1 SSL - what you need to do . . . . . . . . . . . . . . . . . . . . . . . . .. . . . . .. . . . .17
2.1.1 Managing certificates . . . . . . . . . . . . . . . . . . . . . . . . .. . . . . .. . . . .18
2.1.2 Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. . . . . .. . . . .19
2.1.3 Starting a session . . . . . . . . . . . . . . . . . . . . . . . . . . . .. . . . . .. . . . .19
2.1.4 Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. . . . . .. . . . .19
2.2 Firewall NVT support . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. . . . . .. . . . .20
2.2.1 How it works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. . . . . .. . . . .20
2.2.2 Sample TN3270 connection . . . . . . . . . . . . . . . . . . . .. . . . . .. . . . .23
2.2.3 Problem determination . . . . . . . . . . . . . . . . . . . . . . . .. . . . . .. . . . .25
2.2.4 Sample trace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. . . . . .. . . . .26
Chapter 3. Miscellaneous enhancements . . . . . . . . . . . . . . .. . . . . .. . . . .29

3.1 Enterprise Extender . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. . . . . .. . . . .30
3.2 Connection configuration and usability improvements . . . . .. . . . . .. . . . .31
3.2.1 New Customize Communication user interface . . . . . .. . . . . .. . . . .31
3.2.2 Improved connection messages . . . . . . . . . . . . . . . . .. . . . . .. . . . .32
3.2.3 PCSCC058 message improvements . . . . . . . . . . . . . .. . . . . .. . . . .34
3.2.4 Link reactivation . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. . . . . .. . . . .34
© Copyright IBM Corp. 1996 1999 iii

3.2.5 Adjacent Control Point (CP) name changed . . . . . . . . . . . . . . . . .. . 34
3.2.6 New PCI adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. . 35
3.2.7 FMI auto-reconnect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. . 35
3.3 File transfer improvements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. . 35
3.3.1 File transfer buffer defaults changed . . . . . . . . . . . . . . . . . . . . . .. . 35
3.3.2 CUT mode file transfer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. . 35
3.4 Code page and international support . . . . . . . . . . . . . . . . . . . . . . . . . .. . 36
3.4.1 Euro currency symbol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. . 36
3.4.2 Translation tables for SBCS languages . . . . . . . . . . . . . . . . . . . .. . 37
3.4.3 Extended Katakana support . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. . 37
3.4.4 CStar and RichWin support . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. . 37
3.4.5 Bar code printing (Japan). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. . 38
3.4.6 New national-language support . . . . . . . . . . . . . . . . . . . . . . . . . .. . 38
3.4.7 Things to watch for . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. . 38
3.5 API improvements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. . 38
3.5.1 Wrapper APPC DLLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. . 38
3.5.2 SLI API added . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. . 39
3.5.3 HLLAPI improvements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. . 39
3.5.4 Record VBScript macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. . 40
3.6 New viewer utility for the message and trace-log file . . . . . . . . . . . . . .. . 41
3.7 Other enhancements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. . 43
3.7.1 ARB responsive mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. . 43
3.7.2 PCOMM and Client Access/400 co-existence . . . . . . . . . . . . . . .. . 44
3.7.3 Confirm on Exit GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. . 44
3.7.4 PCOMM on Windows NT - SNA Node must not stop at logoff . . .. . 45
3.7.5 Delete Word Classic function . . . . . . . . . . . . . . . . . . . . . . . . . . . .. . 45
3.7.6 New edit function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. . 46
3.7.7 SNA configuration wizard editing . . . . . . . . . . . . . . . . . . . . . . . . .. . 46
3.7.8 Printer dialog consolidation . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. . 47
3.7.9 Replace IIN support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. . 47
3.7.10 GDDM enhancement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. . 47
3.7.11 Internet Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. . 48
Chapter 4. Load balancing and hot standby . . . .. . . . .. . . . . .. . . . . .. . 49

4.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. . . . .. . . . . .. . . . . .. . 49
4.1.1 Components of an SLP environment . . . . .. . . . .. . . . . .. . . . . .. . 50
4.2 Load balancing . . . . . . . . . . . . . . . . . . . . . . . . .. . . . .. . . . . .. . . . . .. . 51
4.3 Hot Standby. . . . . . . . . . . . . . . . . . . . . . . . . . . .. . . . .. . . . . .. . . . . .. . 52
4.3.1 Client configuration . . . . . . . . . . . . . . . . . .. . . . .. . . . . .. . . . . .. . 52
4.3.2 Server configuration. . . . . . . . . . . . . . . . . .. . . . .. . . . . .. . . . . .. . 54
4.3.3 Troubleshooting . . . . . . . . . . . . . . . . . . . . .. . . . .. . . . . .. . . . . .. . 54
Chapter 5. IPX enhancements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. . 57

5.1 Internal network number . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. . 57
5.2 SAP and SAP agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. . 58
5.3 Hot standby and load balancing over IPX/SPX and TCP/IP . . . . . . . . .. . 59
5.4 Using the NWSAA or IBM Communications Server attachment . . . . . .. . 60
5.5 The bindery user checkbox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. . 62
5.6 Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. . 63
5.6.1 Node Operations Facility on CS/NT . . . . . . . . . . . . . . . . . . . . . . .. . 63
5.6.2 SNA Client Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. . 64
5.6.3 Problems with the user ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. . 66
5.6.4 Problems with the internal network number . . . . . . . . . . . . . . . . .. . 66
iv Personal Communications V4.3 for Windows 95, 98 and NT

5.6.5 IPX clients (NetWare clients/Novell clients) . . . . . . . . . . . . . . . . . . . .69
Chapter 6. VT emulation enhancements . . . . . . . . . .. . . . . .. . . . . .. . . . .71

6.1 Configuration improvements . . . . . . . . . . . . . . . . . .. . . . . .. . . . . .. . . . .71
6.1.1 VT graphics configuration options . . . . . . . . . .. . . . . .. . . . . .. . . . .72
6.1.2 VT local edit configuration options. . . . . . . . . .. . . . . .. . . . . .. . . . .72
6.2 VT keyboard changes . . . . . . . . . . . . . . . . . . . . . . .. . . . . .. . . . . .. . . . .75
6.2.1 Top-row function keys . . . . . . . . . . . . . . . . . . .. . . . . .. . . . . .. . . . .75
6.2.2 Miscellaneous key changes. . . . . . . . . . . . . . .. . . . . .. . . . . .. . . . .75
6.2.3 NUMPAD key changes . . . . . . . . . . . . . . . . . .. . . . . .. . . . . .. . . . .75
6.3 VT 340 text enhancements . . . . . . . . . . . . . . . . . . .. . . . . .. . . . . .. . . . .75
6.3.1 VT text page memory . . . . . . . . . . . . . . . . . . .. . . . . .. . . . . .. . . . .76
6.3.2 VT text-character protection . . . . . . . . . . . . . .. . . . . .. . . . . .. . . . .76
6.3.3 VT text local edit and block transmission . . . . .. . . . . .. . . . . .. . . . .78
6.3.4 VT text - panning and cursor coupling . . . . . . .. . . . . .. . . . . .. . . . .78
6.4 VT graphics enhancements . . . . . . . . . . . . . . . . . . .. . . . . .. . . . . .. . . . .79
6.4.1 VT graphics - ReGIS . . . . . . . . . . . . . . . . . . . .. . . . . .. . . . . .. . . . .79
6.4.2 VT graphics - Sixel . . . . . . . . . . . . . . . . . . . . .. . . . . .. . . . . .. . . . .80
Chapter 7. Database access with PCOMM 4.3 . . . . . . . . . . . .. . . . . .. . . . .83

7.1 Introduction to ODBC . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. . . . . .. . . . .83
7.2 Configuring ODBC data sources . . . . . . . . . . . . . . . . . . . . .. . . . . .. . . . .84
7.2.1 How it works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. . . . . .. . . . .85
7.3 PCOMM ODBC database-configuration requirements . . . . .. . . . . .. . . . .86
7.4 Sample configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. . . . . .. . . . .87
7.4.1 Summary of configuration steps . . . . . . . . . . . . . . . . .. . . . . .. . . . .88
7.4.2 PCOMM SNA Node configuration . . . . . . . . . . . . . . . .. . . . . .. . . . .88
7.4.3 DB2 Client Configuration Assistant . . . . . . . . . . . . . . .. . . . . .. . . . .91
7.5 Database Access Utility . . . . . . . . . . . . . . . . . . . . . . . . . . .. . . . . .. . . . .95
7.5.1 Configuring the Database Access Utility . . . . . . . . . . .. . . . . .. . . . .96
7.6 Problem determination . . . . . . . . . . . . . . . . . . . . . . . . . . . .. . . . . .. . . . .99
7.6.1 DB2 database connection problems . . . . . . . . . . . . . .. . . . . .. . . . .99
7.6.2 CPI-C trace for DB2 . . . . . . . . . . . . . . . . . . . . . . . . . .. . . . . .. . . .101
7.6.3 ODBC trace for DB2 Connect . . . . . . . . . . . . . . . . . . .. . . . . .. . . .101
Chapter 8. Tivoli support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. . . .103

8.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. . . .103
8.2 Installing the IBMPCOMMPlus module on a Tivoli TMR Server . . . .. . . .104
8.3 Functions and tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. . . .108
8.3.1 Using IBM PCOMMPlus functions . . . . . . . . . . . . . . . . . . . . . .. . . .108
8.3.2 IBMPCOMMPlus task and job overview. . . . . . . . . . . . . . . . . .. . . .110
8.3.3 Using IBM PCOMMPlus tasks . . . . . . . . . . . . . . . . . . . . . . . . .. . . .112
8.3.4 Start SNA node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. . . .115
8.3.5 Display SNA node resource . . . . . . . . . . . . . . . . . . . . . . . . . .. . . .117
8.3.6 Modify SNA node resource . . . . . . . . . . . . . . . . . . . . . . . . . . .. . . .117
8.4 PCOMM command-line programs used by Tivoli . . . . . . . . . . . . . . .. . . .118
8.4.1 Syntax of PCOMM command-line programs . . . . . . . . . . . . . .. . . .119
Chapter 9. Java development with Personal Communications . . . .. . . .125

9.1 Using the Host Access Class Library for Java (HACL) . . . . . . . . . .. . . .126
9.1.1 When should I use HACL and Host Access Beans? . . . . . . . .. . . .127
9.2 Setting up the Java environment . . . . . . . . . . . . . . . . . . . . . . . . . . .. . . .129
9.3 Host Access Class Library objects . . . . . . . . . . . . . . . . . . . . . . . . .. . . .131
9.3.1 Connecting to the host . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. . . .133
v
9.3.2 Debugging a HACL applet within Personal Communications . . . . . 136
9.3.3 Navigating the session screens . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
9.3.4 Navigating inside the screens . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
9.3.5 Transferring files from/to the host . . . . . . . . . . . . . . . . . . . . . . . . . 148
9.4 ActiveX controls vs. ActiveX OLE automation objects . . . . . . . . . . . . . . 150
9.4.1 Using the Personal Communications ActiveX Host Access controls 150
9.4.2 Using Host Access controls to communicate with host system . . . . 150
Appendix A. Trace of a connection that uses SSL and SLP. . . . . . . . . . . .153
Appendix B. Special notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .159
Appendix C. Related publications . . . . . . . . . . . . . . . . . . . . . . ...... . . . . . 161

C.1 International Technical Support Organization publications . . . ...... . . . . . 161
C.2 Redbooks on CD-ROMs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ...... . . . . . 161
C.3 Other publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ...... . . . . . 161
How to get ITSO redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163

IBM Redbook fax order form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
ITSO Redbook Evaluation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
vi Personal Communications V4.3 for Windows 95, 98 and NT

Figures
1. PCOMM installation implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Installation Manager options screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
3. Installation Manager installing PCOMM, showing status bar . . . . . . . . . . . . . . . 4
4. PCOMM 4.3 migration utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
5. CM/2 migration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
6. PCOMM migration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
7. Example section of PRODUCT.TXT for silent installation . . . . . . . . . . . . . . . . . 8
8. Example update file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
9. Example update file, showing how to delete keywords . . . . . . . . . . . . . . . . . . 10
10. Example of using update files to update PCOMM client node configurations . 11
11. Example showing the use of template files . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
12. Example of Install.log file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
13. Certificate Management utility, showing well-known CAs . . . . . . . . . . . . . . . . 18
14. Secure session established . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
15. Stage 1: NVT connection to a secure firewall . . . . . . . . . . . . . . . . . . . . . . . . . 21
16. Stage 2: Switching to TN3270 mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
17. Stage 3: Session established - firewall passthru . . . . . . . . . . . . . . . . . . . . . . . 23
18. Configuring a TN3270 connection to a firewall . . . . . . . . . . . . . . . . . . . . . . . . 23
19. Session connected to the firewall. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
20. Connected to the host through the firewall. . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
21. PCOMM trace facility - options for a TN3720/5250 trace. . . . . . . . . . . . . . . . . 26
22. Sample trace, part 1 - socket initialization and NVT-mode indication . . . . . . . 27
23. Sample trace, part 2 - ASCII (NVT/VT) data flow. . . . . . . . . . . . . . . . . . . . . . . 27
24. Sample trace, part 3 - switching from NVT to TN3270 or TN5250 mode. . . . . 28
25. Sample trace, part 4 - TN3270E flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
26. New Customize Communication user interface . . . . . . . . . . . . . . . . . . . . . . . . 32
27. New connection-status bar. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
28. Displaying the status bar history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
29. Status bar history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
30. Log Viewer showing PCSSB101 - emulator status bar history . . . . . . . . . . . . 33
31. Euro-currency keyboard support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
32. SLI trace options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
33. Record VBScript macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
34. VBScript macro editing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
35. PCOMM 4.3 Log Viewer - multiple files open . . . . . . . . . . . . . . . . . . . . . . . . . 42
36. PCOMM Log Viewer - showing trace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
37. Trace Event filter options (right click the event) . . . . . . . . . . . . . . . . . . . . . . . . 43
38. Exit Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
39. New edit options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
40. New edit options - Cut/Copy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
41. Page Setup - Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
42. Internet Service dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
43. Connection types that can use SLP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
44. SLP - how it works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
45. SLP agents. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
46. Telnet3270 SLP configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
47. Telnet3270 hot standby configuration (without SLP) . . . . . . . . . . . . . . . . . . . . 53
48. Basic configuration for QELMU over IP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
49. Advanced QELMU over IP configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
50. SLP network example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
© Copyright IBM Corp. 1996 1999 vii

51. Internal network number - 8 digits required. . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
52. Windows NT Services panel - SAP Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
53. The NWSAA or IBM Communications Server attachment . . . . . . . . . . . . . . . .60
54. First Link Parameters panel - choose the IPX protocol. . . . . . . . . . . . . . . . . . . 60
55. Check the IBM Communications Server box . . . . . . . . . . . . . . . . . . . . . . . . . . 61
56. Specifying the server and user name and the pool type . . . . . . . . . . . . . . . . . . 61
57. IPX login panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
58. Successful connection and status bar information . . . . . . . . . . . . . . . . . . . . . .62
59. Bindery user setting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
60. Node Operations main panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
61. Successful connection (TESTLU02 is green) . . . . . . . . . . . . . . . . . . . . . . . . . .64
62. The Services control panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
63. SNA Node Operations - SNA API Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
64. Enabling SNA API Client Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
65. Defining a user as a member of the IBMCSAPI group . . . . . . . . . . . . . . . . . . . 66
66. NetWare server, active connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .67
67. Internal network name displayed by a NetWare console . . . . . . . . . . . . . . . . . 67
68. External network address . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
69. Internal network address via AUTOEXEC.NCF . . . . . . . . . . . . . . . . . . . . . . . . 68
70. External network address via AUTOEXEC.NCF. . . . . . . . . . . . . . . . . . . . . . . . 68
71. Configuration improvements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .71
72. Advanced VT configuration panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
73. VT text - page-memory modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
74. VT text - local edit and block transmission . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
75. VT Graphics - ReGIS sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
76. VT graphics - sixel example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
77. How ODBC works with a database connection. . . . . . . . . . . . . . . . . . . . . . . . . 84
78. Comparison between PCOMM 4.2 and PCOMM 4.3 database access . . . . . . 85
79. DB2 ODBC connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
80. Sample configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
81. SNA Node configuration example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
82. Mode definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
83. CPI-C Side Information window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .91
84. DB2 Client Configuration - Update Connection SmartGuide - Protocol tab . . .92
85. DB2 Update Connection SmartGuide - APPC tab . . . . . . . . . . . . . . . . . . . . . .92
86. DB2 Update Connection SmartGuide - Target Database tab . . . . . . . . . . . . . . 93
87. DB2 Update Connection SmartGuide - Alias tab . . . . . . . . . . . . . . . . . . . . . . .93
88. DB2 Update Connection SmartGuide - ODBC tab . . . . . . . . . . . . . . . . . . . . . .94
89. Test database connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
90. Client Configuration Assistant window - new database connection definition. . 95
91. Database Access Utility - not connected to data source . . . . . . . . . . . . . . . . . . 96
92. Select Data Source window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
93. Connecting to the host database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .97
94. Query tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
95. Example data that can be retrieved from a host database . . . . . . . . . . . . . . . .99
96. Change User Profile menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
97. DB2 Trace Facility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
98. Saving a DB2 trace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .101
99. PCOMM region of managed nodes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
100.PCOMMPlus module location on CD-ROM . . . . . . . . . . . . . . . . . . . . . . . . . . 105
101.Installing the PCOMMPLus module on a Tivoli TMR server . . . . . . . . . . . . . 105
102.Setting path to IBMPCOMMPlus module for installation . . . . . . . . . . . . . . . . 106
103.Installation selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .107
viii Personal Communications V4.3 for Windows 95, 98 and NT

104.IBMPCOMMPlus for Tivoli container . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
105.IBMPCOMMPlus Tasks panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
106.PCOMM subscription list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
107.About IBM PCOMMPlus for Tivoli . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
108.Creating a job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
109.Creating a job (2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
110.Interaction of Tivoli server and Tivoli agent on PCOMM node . . . . . . . . . . . 112
111.Executing a task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
112.Issue command dialog box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
113.Example output from dir command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
114.Output from list configuration files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
115.Output from query SNA node status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
116.Start SNA node options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
117.Output from the Start SNA node task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
118.Stop SNA node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
119.Output from stop SNA node. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
120.Display SNA node resource. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
121.Output from display SNA node resource . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
122.Modify SNA node resource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
123.Output from Modify SNA node resource . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
124.Host access through JDBC and HACL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
125.Sample code to start SNA communication, using an ECLSession object . . . 135
126.Running an applet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
127.Standard In pane . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
128.Using an ECLSession object with the SimpleSample class . . . . . . . . . . . . . 138
129.Using an ECLSession object with the SimpleSample class (continued) . . . . 139
130.ConsoleOutput class code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
131.ConsoleOutput class code from Figure 130 on page 140 (continued) . . . . . 141
132.Example of using ECLScreenDesc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
133.Sample code for a simple "callback handler" class . . . . . . . . . . . . . . . . . . . . 143
134.Sample code for a simple "callback handler" class (continued) . . . . . . . . . . 144
135.Modified code to improve the SimpleRecoCallback class . . . . . . . . . . . . . . . 144
136.A "callback handler" class to clear the "More..." screen automatically . . . . . 145
137.Three statements added to the code from Figure 134. . . . . . . . . . . . . . . . . . 145
138.Waiter class, using screen recognition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
139.Synchronous-wait sample code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
140.This sample code belongs to Figure 141. . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
141.Sample code to demonstrate file transfer . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
ix
x Personal Communications V4.3 for Windows 95, 98 and NT
Preface
This edition of the redbook will help you install, configure, administer and use IBM
SecureWay Personal Communications 4.3 for Windows 95, 98 and NT, known as
PCOMM. It is not a comprehensive manual about all the versions of PCOMM; it is
concerned only with features that are new in Version 4.3.
The book describes all the new functions of Personal Communications 4.3, from
the point of view of both administrator and user. It explains how the functions
work and the ways in which they can be configured to suit differing requirements.
Major topics include security, which is becoming more and more important as
host applications are made available on extranets or the Internet, and system
management, which is provided through support of the Tivoli Management
Environment. Also included is information about enhancements to PCOMM’s IP
and IPX connectivity, and the introduction of a Java programming interface.
The team that wrote this redbook

This redbook was produced by a team of specialists from around the world
working at the International Technical Support Organization, Raleigh Center.
Julian Over is a Consulting Systems Engineer in the International Technical

Support Organization, Raleigh Center. He writes extensively and teaches IBM
classes worldwide on all areas of networking. Before joining the ITSO three years
ago, Julian worked in Technical Support in the United Kingdom.
Falk Doege is a networking specialist at CSG in Germany. He has three years of

experience in support of IBM host-connection products. He holds a degree in
Electronics from Ingenieurhochschule, Dresden. His areas of expertise include
Personal Communications, Communications Server, and Host On-Demand.
Olaf Graf is an application development specialist at CSG in Germany. He has

three years of experience in support of the IBM VisualAge product family. He
holds a degree in Electrical Engineering from the Technical University of Ilmenau,
and is a SUN Certified Java Programmer for JDK 1.1. His areas of expertise
include VisualAge for Java, VisualAge for C++, and DB2. He has written
extensively on VisualAge for Java Enterprise V2.0.
Matthew Radford is an Enterprise Communications Specialist in IBM Personal

Software Assist in the United Kingdom. He has five years of experience in
networking, and has a BSC (Hons) in Information Technology from the University
of Glamorgan.
Thanks to the following people for their contributions to this project:
Juan Rodriguez
Jorge Ferrari
Martin Murhammer
International Technical Support Organization, Raleigh Center
Tom Brawn
Personal Communications Development, Raleigh
© Copyright IBM Corp. 1996 1999 xi

Comments welcome
Your comments are important to us!
We want our redbooks to be as helpful as possible. Please send us your

comments about this or other redbooks in any of the following ways:
• Fax the evaluation form found in “ITSO Redbook Evaluation” on page 167 to
the fax number shown on the form.
• Use the online evaluation form found at http://www.redbooks.ibm.com/
• Send your comments in an Internet note to redbook@us.ibm.com
xii Personal Communications V4.3 for Windows 95, 98 and NT

Chapter 1. Installation
Installation of PCOMM is now performed through Installation Manager, a
Java-based program that provides an easy-to-use common front-end for installing
IBM products. Installation Manager lets you install several associated products
through a single interface; it verifies that each product has been properly installed
before proceeding to the next. The CD includes PCOMM for Windows 3.1 and
Installation Manager detects which platform it is running on.
Migrating configuration files from Communications Manager/2 (CM/2) and older

versions of PCOMM to PCOMM 4.3 has been made even easier with the addition
of support for migrating CM/2 Response (RSP), and PCOMM profiles (WS) to
PCOMM 4.3 with a new Migration Utility program. Improvements have also been
made to SNA configuration files. SNA node and session configuration files can
now be distributed as template files to clients, providing the users with default
configuration settings, or SNA configuration update files that can be created to
uniquely configure each user’s SNA node configuration.
PCOMM 4.3 can be installed in a variety of ways. In this chapter we will describe
the different methods that can be used, from a manual installation to distributing
PCOMM across hundreds of clients.
1.1 Installation Manager

Installation Manager is a new front-end for installing software products; it is used
for many IBM products in order to provide a common interface for software
installations.
1.1.1 Installation Manager highlights

• Installs all products through one interface.
PCOMM, DB2 Connect, Adobe Acrobat Reader, and NetWare for SAA or
CS/NT API Client.
• Easy access to product documentation in both PDF and HTML formats.
• One-click Web site access invokes the user’s default Web browser.
• Looks consistent with other SecureWay products.
• Use on all Win32 platforms (95, 98, NT).
1.1.2 Implementation
Installation Manager is written in Java and has several parts:
• SETUP32.EXE - Called from SETUP.EXE, this is a C program that the user
can choose to initiate the installation process.
• Install Splash - Java AWT program that displays the graphical launch screen.
• TaskGuides - Java program that displays Wizard panels to prompt for user
selections, and guide the user through the installation.
• Installation Engine - This is the back-end program that manages the
product-installation processes and displays the progress indicator.
• A Java Run-time Environment (JRE) V1.1.6 is included on the CD.
© Copyright IBM Corp. 1996 1999 1

Initial Setup program
(from root of CD) SETUP.EXE
Determines which program to call
SETUP16 or SETUP32 depending
on your Operating System.
WIN32 NT/95/98 Program

Loads Installation Manager SETUP32.EXE SETUP16.EXE
Installation Manager
and it's JAVA Installation Manager
16 Bit Windows
components "Install Splash"
PCOMM install
"TaskGuides"
"Install Engine" program
(No Installation Manager)
PCOMM Install Shield

program. Add install
parameters here. SETUP.EXE
Figure 1. PCOMM installation implementation
1.1.3 Installing products

The first program that is run is SETUP.EXE, which determines whether
SETUP32.EXE (WIN NT/95/98) or SETUP16.EXE (for 16-bit Windows) should be
used (note that Installation Manager itself runs in 32-bit mode). When Installation
Manager runs, it presents a list of all the available products, and you can choose
which you want to install. Installation Manager helps you choose the type of
installation and prevents you from choosing invalid combinations. Figure 2 shows
the Installation Manager options screen.
2 Personal Communications V4.3 for Windows 95, 98 and NT

Figure 2. Installation Manager options screen
For PCOMM ODBC data access to work properly, it is critical that DB2 be
installed with certain options. To enforce this, the installation of DB2 is
automated. The only option available is to choose where the files are installed.
Installation Manager will check installation prerequisites. For example, with DB2
Connect for Personal Communications, an SNA stack is required. If a supported
stack is not found on the system and PCOMM was not selected for installation
with DB2, PCOMM is automatically added. Another example is if API Client for
NetWare for SAA is chosen, the PCOMM full SNA stack is not installed. The
following stacks are supported:
• PCOMM
• CS/NT Server/Client
• NWSAA
• MS SNA Server/Client
Installation Manager installs the chosen products in the correct order. After each
product has been installed, it is verified. The user is allowed to cancel the whole
installation if one product installation fails or is cancelled (this does not remove
the products that have already been installed). Figure 3 shows PCOMM
installation in progress.
Installation 3
Figure 3. Installation Manager installing PCOMM, showing status bar
Other things to notice include a progress indicator to let the user know the current
installation status of the products. The user will be prompted for only one reboot
after all of the chosen products have been installed. If reboot occurs while
Installation Manager is still in progress, it will pick up where it left off.
1.2 Installation overview

PCOMM can be installed onto a workstation or a server; the installation program
gives you three options:
• Install on a workstation
All the files required for the choices you make during installation are installed
in directories on your workstation.
• Install on a workstation to run from a server
Installs the minimum number of files required for a Personal Communications
client to run from the program files on the server. Your session profiles,
keyboard and macro files, and other configuration information will be stored on
your workstation. Other files, such as device drivers, are installed in the
Windows directories on your workstation. You must know the location of the
Personal Communications program files on the server.
• Install on a server
Most of the Personal Communications program files are copied to the network
drive that you specify. These files must be installed before you can use the
previous option.

Note
You can install Personal Communications on a server only from a Windows
NT, Windows 95, or Windows 98 workstation, although the server can be
running another operating system.
The server's file system must support long filenames.
The server drive specified cannot be referred to by a universal naming
convention (UNC) name; you must use the [d]:\path format.
1.3 Migration of previous configuration files

PCOMM 4.3 will migrate SNA configuration files from earlier versions of Personal
Communications (PCG or ACG), and also response files (RSP) created by
Communications Manager/2.
If back-level configuration files exist in the \private subdirectory when you install
PCOMM, the migration program will start automatically upon reboot; old files are
not deleted or overwritten after migration. Migrating from 16-bit Windows will
result in your being prompted for a CP (Control Point) name. The migration
program can also be started manually from the Personal Communications Admin
& PD Aids folder.
Figure 4. PCOMM 4.3 migration utility
Installation 5
1.3.1 Migrating CM/2 configurations
The migration program has been redesigned for PCOMM 4.3 and now supports
migration of CM/2 (Communications Manager/2) configuration files (RSP). One
WS file will be created for each session defined in the RSP file, and one ACG file
will be created for each RSP file. The program allows migration of a single file or
a directory of files. Command-line functions are also available.
Figure 5. CM/2 migration
The following CM/2 configurations can be migrated:

• 3270 or 5250 emulation through token-ring
• 5250 emulation through twinaxial for AS/400
• 3270 or 5250 emulation using SNA Phone Connection
• 3270 or 5250 emulation through SDLC
• 3270 or 5250 emulation through Ethernet (Etherand) network
• APPC APIs through token-ring or Ethernet (Etherand) network
• 3270 emulation through coaxial (DFT)
1.3.2 Migrating PCOMM configurations

The migration program will also migrate configuration files from previous versions
of PCOMM:

Figure 6. PCOMM migration
1.4 Unattended (silent) installation

Personal Communications can be installed in unattended mode. This lets an
administrator distribute PCOMM to clients without the need for user intervention,
enabling fast distribution of software. Full information on how to do this is
provided in Appendix J, "Using InstallShield Silent" of Personal Communications
V4.3 for Windows NT Reference Volume II, SC31-8682. However there are a few
points to note:
• Running SETUP.EXE with parameters
SETUP.EXE must be run from the \WIN32\INSTALL\ALL\DISK1 directory, not
from the root directory, because they are different programs. Make sure that
the parameters are entered in the correct order. For example, when creating a
response file, type the following:
SETUP -NOINST -R -F1C:\MYDIR\MYFILE.ISS -F2C:\MYDIR\MYLOG.LOG
This will create a response file without installing PCOMM. The NOINST
parameter must be the first.
• Silent installation of PCOMM
Installation of PCOMM and/or another product can be done without using
Installation Manager. In order to install the products individually, use
SETUP.EXE, with its silent-installation parameters. There is also a
silent-installation response file for DB2:
\WIN32\INSTALLDB2CONN\DB2\WINNT95\COMMON\DB2CONPR.RSP
Installation 7
Installation Manager uses this file to install DB2 silently during a normal
installation.
• Silent installation of PCOMM from Installation Manager
Personal Communications can be installed silently using Installation Manager.
You can do this by modifying the file PRODUCT.TXT, located in the \INSTMGR
directory of the CD image code (you must copy the CD-ROM image to a file
server to do this). Make sure that the path of the response file (file.iss) is
correct. In the example section of PRODUCT.TXT, below, PCOMM is installed
using SILENT.ISS, from the server path where the image code is installed,
\PCOMM\WIN32.
ProductName=ProductNamePCOM
ProductKey=PCOM
Version=
Regkey=SOFTWARE\IBM\Personal Communications\CurrentVersion\VersionNumber
Regname=
Regvalue=4300 Combo
RegType=4
Type=current
OS=BOTH
MapperText=MapperTextPCOM
Command=win32\install\all\disk1\setup.exe -s -f1\pcomm\win32\silent.iss -f2d:\pcomm.log -NOREBOOT -SMS
endOfProduct
Figure 7. Example section of PRODUCT.TXT for silent installation
Having edited the file, you can install PCOMM silently by running Installation
Manager and selecting the file.
1.5 Installation of PCOMM using Microsoft SMS

Another method of installing PCOMM is by using Microsoft’s SMS Administrator,
which provides unattended installation of PCOMM and any other products
required. In order to do this, you must create an SMS software package that
contains the PCOMM image code from the CD, and an SMS job. Information on
creating an SMS package and job is contained in Appendix K, "Remote
Installation and Uninstallation of Personal Communications" of Personal
Communications V4.3 for Windows NT Reference Volume II, SC31-8682.
Information is also contained in the Microsoft Systems Management Server
documentation.
1.6 Remote installation using Tivoli Courier

PCOMM can also be installed using Tivoli Courier; this is described in Chapter 8,
“Tivoli support” on page 103. Two methods of remote installation can be
performed:
1. Autopack, which PCOMM does not support
2. Profile Manager: File Package, which is supported

1.6.1 Using Profile Manager
Profile Manager requires silent or unattended installation mode (see Appendix J
of Personal Communications V4.3 for Windows NT Reference Volume II,
SC31-8682 for silent-installation details, or Appendix K for details on creating and
using file packages. The Profile Manager pushes a complete file package, which
is the complete PCOMM installation image, onto Managed Node PCs, which then
run the PCOMM installation silently. It takes a long time, and requires space on
the managed-node PCs for both the installation image and the installed product.
Two samples are provided with PCOMM to assist in Tivoli Courier installation:
• Sample package file on the CD.
<cd-rom>\win32\install\admin\distrib\pcomm.cdf
• Sample batch file for invoking PCOMM silently
<cd-rom>\win32\install\admin\distrib\instpcom.bat
1.7 Configuration file update support

Improvements have been made in PCOMM 4.3 to allow an Administrator to roll
out SNA Node configuration-file (ACG-file) updates for PCOMM client
installations. This is very useful in a large network of PCOMM clients. Personal
Communications uses two new file types to enable this: template files and update
files. Together, they enable an administrator to provide pre-set SNA configuration
values to a client, and to send a single update file to all the clients.
A template contains the configuration elements common to all clients. An update

file contains only those changes necessary for an individual client. A
command-line function combines the template and an update file to produce a
new file that contains the target configuration. In this section, we will give you an
introduction to using these configuration files; please refer to Chapter 6 of
Personal Communications V4.3 for Windows NT Reference Volume I, SC31-8680
for more detail.
1.7.1 How update files are created

An update file has the same format as an ACG file but should contain only the
changes required for the ACG file. For example, if we wanted to change an ACG
file so that we could use ODBC, we would need to add MODE and CPI-C
definitions. This could be done by creating an update file as follows:
Installation 9
MODE=(
MODE_NAME=IBMRDB
AUTO_ACT=0
COMPRESSION=PROHIBITED
COS_NAME=#CONNECT
DEFAULT_RU_SIZE=1
MAX_NEGOTIABLE_SESSION_LIMIT=256
MAX_RU_SIZE_UPPER_BOUND=1024
MIN_CONWINNERS_SOURCE=128
PLU_MODE_SESSION_LIMIT=256
RECEIVE_PACING_WINDOW=3
)
CPIC_SIDE_INFO=(
SYM_DEST_NAME=DB2CPIC
CONVERSATION_SECURITY_TYPE=NONE
MODE_NAME=IBMRDB
PARTNER_LU_NAME=USIBMRA.RALYAS4C
TP_NAME=076b
TP_NAME_TYPE=SNA_SERVICE
)
Figure 8. Example update file
When it is run, the update program, VACGCON, checks to see if the above
definitions existed in the ACG file; if they did not, it would add them. If they did
exist, it would only change those values that were different. That’s how an update
is added to the ACG configuration file. To delete sections of a configuration, the
DELETE keyword should be used. For example, the update file below would undo
our changes to the ACG file by removing the MODE and CPI-C definitions.
MODE=(
MODE_NAME=IBMRDB
DELETE
)
CPIC_SIDE_INFO=(
SYM_DEST_NAME=DB2CPIC
DELETE
)
Figure 9. Example update file, showing how to delete keywords
For more details, please refer to Chapter 6 of Personal Communications V4.3 for
Windows NT Reference Volume I, SC31-8680.
1.7.2 Using update files to change your configuration

An administrator can now roll out a default configuration (common to all clients) in
an ACG or template file, and then distribute unique configuration-update files for
each user. When these two files are combined, a unique client configuration can
be produced. This simplifies the process of configuring PCOMM clients in a large
network.

The update file can add definitions to those in the template file, modify
definitions in the template, or delete definitions from the template. On the
client, the template and update files are merged by running a command line
program, VACGCON, to create and verify a working (ACG) file.
For example, to add the changes in file update.acg to config.acg, and create
the new file as new.acg, you would need to do the following:
Add to the end of config file CONFIG.ACG, the statement:
INCLUDE=UPDATE.CHG;
This tells VACGCON where your update file is.
3. Next run the following:
VACGCON CONFIG.ACG NEW.ACG
This creates a new file called NEW.ACG by merging CONFIG.ACG with
UPDATE.CHG. Your old configuration file, CONFIG.ACG, is not changed.
Note
Before you run VACGCON, make sure that the keyword INCLUDE=<update
file>, followed by a carriage return, has been added to the end of the ACG file.
If, at a later time, configuration updates are required for each PCOMM client,
an administrator can simply roll out a new update file to each client. The
update files can then be combined with the current ACG files to produce new
ACG files for each client. This can avoid your having to reconfigure each
PCOMM client on the network. This is shown in Figure 10.
(1)Implement changes to clients

using (UPDATE.CHG)
(2)Clients create new config file

NEW.ACG using template
UPDATE.CHG
VACGCON HOST.ACG NEW.ACG
Host PCOMM
. 4.3 Client
HOST.ACG,
now becomes NEW.ACG
PCOMM 4.3 Client

T/R Network HOST.ACG,
now becomes NEW.ACG
PCOMM 4.3 Client

HOST.ACG,
Gateway now becomes NEW.ACG
Figure 10. Example of using update files to update PCOMM client node configurations
Installation 11
1.7.3 Using initial definition files to preload a configuration
An administrator can now provide each PCOMM client installation with files that
contain initial SNA node and session parameters. When the user starts the SNA
node, or a session, these settings are loaded into the configuration before the
user starts to configure anything. This reduces the amount of configuration a user
has to do, thus making it easier to configure a connection, and ensuring that
certain important settings are present on each client. When a user later creates a
new configuration, these settings will be preloaded, reducing configuration time
and complexity.
This can be done by creating an ACG and a WS file, and renaming them as
template files (PCSINIT.AC$ and PCSINIT.WS$, respectively). Distributing these
files to the \PRIVATE directory on the client provides the user with initial-definition
files that contain common configuration values.
In Figure 11, each PCOMM client has been provided with an initial-definition file;
these are the same for each client, and contain the destination address of the
gateway and other common connection information. When the user configures a
new session, he has only to provide unique workstation parameters to get a
connection, because the other definitions are already configured.
Attention
To avoid a problem that occurs when a user attempts to create a configuration
from initial definition files, you should get the fix for APAR IC23636; this
prevents the AC$ file from appearing to be unverified and therefore unusable.
Figure 11. Example showing the use of template files
1.8 Installation usability improvements

The following improvements have been made to PCOMM’s installation.

1.8.1 Validate server when installing client
If you choose Install on workstation to run from a server, you will be prompted
to enter the path to the server software. Setup uses this to make some
compatibility checks by comparing the server directory you enter with the
installation being done. The following are checked:
• Are the versions of PCOMM the same?
• Is it the same package (Combo/5250)?
• Does the SNA type match (PCOMM, CS/NT, MS SNA, API Client)?
Information about the server installation is stored in a file called SERVERV.INI,

located in the PCOMM directory on the server.
1.8.2 Choose SNA type during a server installation

When previous versions of PCOMM were installed on a code server, the type of
SNA stack installed was determined by the SNA environment of the installing
machine. For example, if you were installing on the server from a machine with
CS NT installed, the server could only be used by clients that were using the CS
NT client. PCOMM 4.3 installation lets you choose which SNA type to install.
1.8.3 Internationalization (I18N)

Each language is shipped on a separate CD that is localized for that language.
Each CD includes Win32, Win16, and OS/2 code.
Each CD also contains English resources, which are used on machines that
do not have the necessary code-page support for the intended language.
If the native language is not supported, Installation Manager runs in English.
Java translation is accomplished via properties files, using Unicode escape
sequences.
1.9 Problem determination

This section contains useful information to assist in problem determination when
installing PCOMM. It covers Installation Manager, SSL installation, and silent
installation.
1.9.1 Installation Manager problems

Installation Manager creates some helpful files in the TEMP directory:
• IBM_InstallEngine.log
Not very detailed, but shows exceptions encountered when launching
installation programs.
• product.txt
Contains suite information with temp-dir and language-selection run-time
variables inserted.
• suite.vector
Scripting file for InstallEngine. Not readable, but useful for debugging.
• db2conpr.rsp
Installation 13
Response file for silently installing DB2.
If the installation procedure hangs or crashes, try running it from the command
line; this creates a console to display exceptions and errors.
To run the Manager from a command line, go to the \instmgr directory on the CD,
then type:
bin\jre -cp;sguide.jar SmartGuide installPCOMM.sgs
Alternatively, you can install PCOMM directly, bypassing Installation Manager, by

running:
\WIN32\ALL\DISK1\SETUP.EXE
1.9.2 SSL installation problems

SSL (also known as GSK) has its own setup program, which is launched silently
from PCOMM’s installation. Once installed, SSL can be shared by multiple
products. The SSL installation image can be found in the \SSL subdirectory of
PCOMM’s installation image.
If SSL’s silent installation fails, PCOMM displays an error message with a return
code that says that you can continue to install, and recover later by following
instructions in the readme file. Here’s what the return codes mean:
• 1 = error launching the SSL installation
This is often caused by copying the installation image from the CD without the
SSL subdirectory. Verify that the PCOMM installation image has the SSL
subdirectory and all of its contents.
• 2 = error in writing to the SSL response file
See above.
• 10 = time-out
This means that the 6-minute timer ran out. This is usually caused by slow
networks or some other process taking all of the processor’s resources.
• <0 = SSL’s silent installation failed with an Installshield Silent problem
These return codes are the same as PCOMM’s silent-installation failures. See
the reference guide for detailed explanations.
To recover SSL’s installation, try installing it interactively by invoking SSL’s

installation program from the CD-ROM or an equivalent server path:\
• <CD-ROM drive>:\win32\install\all\disk1\ssl\setupssl.exe PCOMM <langid>
where <langid> matches the PCOMM language (see readme.txt for details)
• Respond to SSL’s interactive installation panels and it should complete
successfully.
If the installation still fails, gather the following information:

• Error messages during SSL’s installation.
• See if SSL is already installed on the system.

There may be an incompatibility between the version of SSL already on the
workstation and the one being installed. Get a directory listing of its installation
path, and the contents of the registry key to check:
HKEY_LOCAL_MACHINE\SOFTWARE\IBM\GSK\CurrentVersion
1.9.3 Silent-installation problems

If you have silent-installation problems, check the INSTALL.LOG file. This is created
if you use the -f2 parameter to specify a log file name and path for the installation.
See Figure 12.
[InstallShield Silent]
Version=v3.00.000
File=Log File
[ResponseResult]
ResultCode=0
Figure 12. Example of Install.log file
If there is a problem, an error code is written to the log file, in ResultCode=. Below
is a list of what the ResultCode values mean:
• 0 - Success
• -1 - General error
• -3 - Required data not found in the SETUP.ISS file
• -4 - Not enough memory available
• -5 - File does not exist
• -6 - Cannot write to the response file
• -9 - Not a valid list type (string or number)
• -10 - Data type is invalid
• -11 - Unknown error during setup
• -12 - Dialogs are out of order
For details on troubleshooting, refer to Appendix J, "Using InstallShield Silent" in

Personal Communications V4.3 for Windows NT Reference Volume II,
SC31-8682.
Installation 15
Chapter 2. Securing your connections - SSL and firewalls
Personal Communications 4.3 supports secure connections for 3270, 5250 or VT
sessions to telnet servers by means of Secure Sockets Layer (SSL) 3.0; such
servers might be Communications Server for Windows NT, AIX, OS/390, or
OS/400 V4R4. Connection is established by means of certificate authentication
and data on the connection is encrypted. The Service Location Protocol (SLP)
can be used in conjunction with SSL to discover only secure telnet servers and
ports.
PCOMM provides RC-4, MD-5 or SHA encryption, 128-bit for use in the USA and
elsewhere under licence, and 40-bit for general export.
General information about SSL is available in IBM eNetwork Communications

Server for Windows NT Version 6.0 Enhancements, SG24-5232 and in many
non-IBM publications. Much useful information is also available in IBM
SecureWay Host On-Demand: Enterprise Communications in the Era of Network
Computing, SG24-2149.
Security is implemented by means of SKIT, an IBM architecture that is used in

many products. The version used in PCOMM is very similar to those used in Host
On-Demand, Client Access Express and Communications Server for Windows
NT.
If client machines are to be used on the Internet, the internal network has to be
protected by one or more firewalls, of course. This chapter also explains how
PCOMM works with firewalls.
2.1 SSL - what you need to do

PCOMM provides server authentication and encryption of the session data sent
between it and the telnet server, so a certificate for the server is necessary. A
client certificate is not necessary because PCOMM does not support client
authentication.
A keyring file or key database, PCommClientKeyDb.kdb, is created when you

install PCOMM; it includes the root certificates for some well-known certificate
authorities (CAs). Its default password is pcomm.
Using SSL with PCOMM is described in detail in Appendix N, "Configuring and

Using SSL Security for Personal Communications" of Personal Communications
V4.3 for Windows NT Reference Volume II, SC31-8682, which is on the PCOMM
CD-ROM and can be installed, so we will describe only the general principles
here. The main steps you must follow are:
1. The server administrator must obtain a certificate for the server from a
certificate authority (CA). If the CA is considered well known, which means
that its root certificate is already in the key-database of the server and of
PCOMM, that is usually all that is necessary; the CAs that are well known to
PCOMM are listed in the publication mentioned above, and you can see them
in the certificate management utility. A connection between client and server
will be successful because the same certificate is in both databases.
However, if the certificate is from another CA (referred to as "unknown"), it is

necessary to get the CA’s root certificate as well. It is also possible to create
and use a self-signed certificate, though you should do so only for test
purposes.
2. Add the server certificate and, if appropriate, the unknown CA’s root
certificate, to the key database on the server.
3. In the case of an unknown CA, add the CA’s root certificate to the key
database on the PCOMM client. In the case of a self-signed certificate, add its
root certificate to PCOMM’s key database. You can move the certificate to the
client by any secure means.
4. Configure the PCOMM connection for SSL by checking the appropriate box.
2.1.1 Managing certificates

PCOMM provides three ways of managing certificates; the utilities are in the
PCOMM Utilities folder:
• Certificate Wizard: this provides a simple, guided means of adding a
certificate to the key database.
• Certificate Management: this is a comprehensive tool that lets you create
certificate requests, receive certificates, and create and extract self-signed
certificates. Good Help is provided.
Figure 13. Certificate Management utility, showing well-known CAs
• Command-line: a program, PCSGSK, uses a customizable profile to manage

certificates. The syntax is explained in the publication referred to above.

2.1.2 Configuration
Having fulfilled the certificate requirements, you must configure PCOMM to use
SSL; this is straightforward: simply configure a telnet session in the usual way but
check the box labelled Enable Security. The port number for a secure connection
is usually different from that for a non-secure.
You can combine SSL with SLP, in which case the client will connect only with
servers that fulfill both the security and SLP requirements that you define; SLP is
described in Chapter 4, “Load balancing and hot standby” on page 49.
2.1.3 Starting a session

Start the session in the usual way. You may find that a secure session takes
slightly longer to connect than a non-secure; that is because the SSL negotiation
has to take place before the session can be established.
When you have connected successfully, you will see a normal session window
except that the status bar has a locked padlock in the bottom left-hand corner and
tells you that it is connected to a secure server:
Figure 14. Secure session established
2.1.4 Troubleshooting
If you have a connection problem, you should take a PCOMM TCP/IP trace.
Problems within the SSL code itself are more difficult to resolve; the SSL (SKIT)
layer does not have a tracing utility, so it is difficult to debug SSL handshake
problems. You might have to take a line (sniffer) trace.
Here are some other things to consider:

• A valid certificate must be available in the key databases of the client and the
server.
• The port on the server must be configured as secure.
• A closed lock icon is displayed in the bottom left-hand corner of the session
window if the session is encrypted; there is also information on the status bar.
Note that it is possible to have a session connected to a secure port but not
Securing your connections - SSL and firewalls 19

encrypted; in that case, the lock icon will not be closed. This can happen if the
client and server agree on the type of encryption to be used (RC-4, for
example) but one or the other does not support a valid hashing method (MD-5
or SHA) and NULL hashing is therefore used.
Appendix A, “Trace of a connection that uses SSL and SLP” on page 153 has a
trace of a connection to CS/NT; it is an example of what happens when the client
does not have a valid certificate for a server.
2.2 Firewall NVT support

Support for firewall access using Telnet has been added to PCOMM 4.3 by the
addition of Network Virtual Terminal (NVT) support. This new feature provides the
benefit of being able to get a TN3270/5250 session from anywhere outside an
organization’s intranet (such as the Internet) by going through a secure firewall
with PCOMM. The following levels of PCOMM also provide NVT support:
PCOMM for:
• Win-NT 4.1a CSD 2 : IC20289
• Win-32 4.2 CSD 1 : IC20287
• OS/2 4.1 CSD 3
• OS/2 4.2 GM
2.2.1 How it works

The Network Virtual Terminal protocol communicates in ASCII mode, and is
designed to work between any hosts. The protocol defines the lowest common
features required for a connection, and is supported by all telnet servers and
clients. Refer to Request for Comments (RFC) 854, Telnet Protocol Specification
for more information on NVT and the Telnet protocol.
Firewalls work in two modes: transparent and non-transparent. Transparent mode

is where the firewall is set up so that no authentication is required, and only
certain IP addresses are allowed through. This is like a direct connection;
PCOMM does not need to stay in NVT mode and connects as if directly to a
Telnet server. The destination address of the server would be required, not that of
the firewall.
Non-transparent mode applies when you have to authenticate with the firewall
before you are let through. This is where PCOMM’s new NVT support is used, in
order for an ASCII connection to be made with the firewall so that logon can take
place, before switching to TN3270/5250 when a host connection is made. In this
case, the address of the firewall is required as the destination address; the
address of the server that you wish to connect to is entered in the logon to the
firewall. In this chapter we talk about PCOMM NVT support in order to get a
non-transparent connection through the firewall to a server.
When a Telnet connection is initiated, the communication starts in NVT (ASCII)

mode in order to open the socket connection and establish what options are
required for communication. For example, in previous versions of PCOMM, a
TN3270 Telnet session would start initially in NVT mode to open the connection,
and then switch to TN3270E using IAC DO TN3270E. This behavior has been

changed with PCOMM 4.3 if it is connecting TN3270/5250 through a firewall;
PCOMM’s Telnet session is kept in NVT mode until it has been authenticated by
the firewall (in non-transparent mode).
Connecting through a firewall is simple; no extra configuration is required. Simply

specify the IP address or host name of the firewall as the destination address,
instead of that of the host/gateway. The connection through a firewall can be
explained as three stages. These are:
• Stage 1 - NVT connection to the firewall
• Stage 2 - Switching to TN3270/5250 mode
• Stage 3 - Session established - firewall passthrough
We will talk about each stage, using an example of connecting a PCOMM client
from the Internet through a secure firewall to get a TN3270E session from the
intranet.
Figure 15 shows the first stage of a firewall connection from PCOMM:
Figure 15. Stage 1: NVT connection to a secure firewall
When a session is started, it stays in NVT mode after the socket connection has
been opened, allowing a connection to be established with the firewall. Once a
client gets a connection to a firewall’s Telnet proxy, the proxy prompts for an
authorization and PCOMM displays the firewall’s logon screen.
After logon has been done, the firewall proxy may prompt for a destination
address. The user can specify any Telnet server (3270/5250 host or comms
server/gateway - see the warning on page 22) to connect to. In NVT mode,
character-ECHO is on and communication is in ASCII.
Please note that a Telnet connection using Secure Sockets Layer (SSL) through a
firewall is currently not supported because the NVT protocol does not understand
SSL.

Once a user has been authenticated by the firewall, the destination host begins to
negotiate TN3270 or TN5250 options and the session switches over to the
required EBCDIC mode. See Figure 16.
Attention
If you attempt to connect from PCOMM through a firewall to a CS/NT or CS/2
gateway providing a TN3270/5250 service, you might get a PROG750 in the
OIA of the session screen. This problem has now been fixed but requires you to
install a modified DLL. Connection from PCOMM through a firewall directly to a
host system does not have this problem.
Figure 16. Stage 2: Switching to TN3270 mode
Once a session has been established to the host, the firewall acts merely as a
passthru for the session. See Figure 17.

Figure 17. Stage 3: Session established - firewall passthru
2.2.2 Sample TN3270 connection

Connecting through a firewall with PCOMM 4.3 only requires the IP address/host
name of the firewall to be configured on PCOMM.
Figure 18. Configuring a TN3270 connection to a firewall
Enter the address of the firewall. Backup connections can also be used,
consisting of Telnet servers, LUs or pools, or ports, which Personal
Communications can try to use if the primary connection fails.
Note: Because, in this scenario, we are connecting to a firewall first (PCOMM is

configured for the destination address of a firewall, not of a host/gateway), one of
two results could occur:

1. Connection to the firewall fails when you try to establish the session, or while
you are logging on to the firewall (PCOMM in NVT mode).
PCOMM will attempt to reconnect to the firewall first (two reconnect attempts
are made). PCOMM will then switch to the backup host (this has to be the
destination address of another firewall). Connection to the backup firewall
occurs in NVT mode, the user has to log on to the firewall and specify a
host/gateway destination address before a TN3270/5250 session can be
established (the firewall is in non-transparent mode).
2. A 3270/5250 session is established (the firewall is acting as a passthru link
between the firewall and gateway/host), or the gateway-to-host connection
goes down.
In this scenario, PCOMM first attempts to reconnect to the firewall; if the
firewall is up, a connection will be established to it. However, if you then
specify the address of the host/gateway and it is down, you will not get a
session; PCOMM is unable to switch to the backup host in this case.
Failure-to-connect means:
• The host does not exist.
• The host is unreachable.
• The host is not answering.
Figure 19 shows an active connection to a firewall in non-transparent mode. At

this stage, the connection is in NVT (ASCII) mode with character-ECHO on.
Figure 19. Session connected to the firewall
You may be prompted for a user ID/password and/or the name of the host to
which you want to connect. In Figure 19, we are not prompted for a user
ID/password; this depends on how the firewall is set up.

Note
In the Operator Information Area (OIA), the Control Unit Status is shown as
"B"; this indicates that the session is in NVT mode.
In the example below, we are now connected to the host through the firewall.
Notice that the Control Unit Status field B flag has now changed to M, which
means that we have now switched from NVT mode to a TN3270 data stream and
are connected to the host system. The firewall now acts as a pass-through for the
session.
Figure 20. Connected to the host through the firewall
2.2.3 Problem determination

The best way to resolve any problems with connecting through a firewall is to take
a trace. The PCOMM trace facility can be found by clicking Programs -> IBM
Personal Communications -> Administrative & PD Aids.

Figure 21. PCOMM trace facility - options for a TN3720/5250 trace
Select the options shown above for a TN3270/5250 trace. The trace of a
connection through a firewall is different from a normal Telnet trace; note the
following:
• Connection to a firewall has a different Telnet negotiation sequence.
The trace formatter assumes that the data is always for EBCDIC sessions,
which means that it will try to display ASCII text and graphics as characters in
EBCDIC. Sometimes this results in reports of TN3270/TN5250 control
sequences in NVT sessions.
• Communication to a firewall is a stream of ASCII data with very few control
codes. This occurs because it is in NVT ASCII mode when connecting to the
firewall, and also because of the trace formatting (see above).
• Each client-originated character gets ECHOed back to the client. NVT mode is
half-duplex with ECHO set to on, so each character typed will be echoed back
to the client.
2.2.4 Sample trace

In this section, we take you through a sample trace of connecting to a host
system through a firewall, and point out the control sequences that you should
expect from an NVT trace. Figure 22 shows the start of the trace. Here we can
see the socket initialization in NVT.
Notice, at the end, the data "0x0d-0a"; this is the Carriage-Return/Line-Feed in

ASCII. The arrival of a packet with just "0d-0a" is a reliable indicator that the host
is in ASCII (NVT) mode.

[1] 03/23 11:06:13.10,(001B) len=18, 3270/5250/VT Emulator.Communication
data.0001, 00000085:000000BD
SOCKET CALL: WSAStartup() RC=0
[2] 03/23 11:06:13.16,(001C) len=79, 3270/5250/VT Emulator.Communication

data.0001, 00000085:000000B1
Server Host Name: eagleprt.raleigh.ibm.com
[3] 03/23 11:06:13.17,(001D) len=20, 3270/5250/VT Emulator.Communication

data.0001, 00000085:000000B1
Server IP Address: 9.37.56.105 (class A)
[4] 03/23 11:06:13.17,(001E) len=18, 3270/5250/VT Emulator.Communication

data.0001, 00000085:000000B1
SOCKET CALL: socket() (socket=264)
[5] 03/23 11:06:13.17,(001F) len=18, 3270/5250/VT Emulator.Communication

data.0001, 00000085:000000B1
SOCKET CALL: connect() (socket=264)
[6] 03/23 11:06:13.72,(0020) len=23, 3270/5250/VT Emulator.Communication

data.0001, 00000085:0000009E
Length = 2 Session ID = a
Summary:
[ 3270 (data..) ]
Outbound data :..
00
da
Figure 22. Sample trace, part 1 - socket initialization and NVT-mode indication
In Figure 23, you can see the options from the host only during ASCII (NVT/VT)
emulation. Notice [ 3270 (data...)]; this should be ignored - as mentioned before,
the trace formatter converts the flow to EBCIDIC and sometimes misinterprets
the control flow in NVT mode.

data.0001, 00000085:0000009E
Summary:
[ 3270 (data..) ]
[ IAC WILL ECHO ]
[ IAC WILL SUPRESS-GO-AHEAD ]
[ 3270 (ERASE/WRITE ALTERNATE) ]
Outbound data :./.%........../.../`............?..>/_...
46666256677624676767200ff0ff0004677666632
517c5035352507145719edafb1fb3da8f34e1d5a0
Figure 23. Sample trace, part 2 - ASCII (NVT/VT) data flow
In Figure 24, the trace options indicate a switch from NVT mode to TN3270 mode.
Telnet switches from NVT to TN3270 or TN5250 mode upon negotiation of either
the DO-END-OF-RECORD and/or the DO TRANSMIT-BINARY option.

data.0001, 00000085:0000009E
Summary:
[ IAC DO END-OF-RECORD ]
[ IAC WILL END-OF-RECORD ]
[ IAC DO TRANSMIT-BINARY ]
[ IAC WILL TRANSMIT-BINARY ]
Outbound data :............
ff1ff1ff0ff0
fd9fb9fd0fb0
Figure 24. Sample trace, part 3 - switching from NVT to TN3270 or TN5250 mode
Finally, in Figure 25, we can see that we have switched to a TN3270E data flow.
This can be seen by the [3270...] events and the session screen.

data.0001, 00000085:0000009E
Summary:
[ 3270 (ERASE/WRITE) ]
Outbound data :.G.),.-RUNNING RALVMU .YVM/ESA ONLINE.-... .0
.8WELCOME TO IBM GLOBAL SERVICES
0c15616deddcdc444dcdede44441eed6cec4dddcdc1610541f444444444444444444441fec
dcddc4ed4ccd4cddccd4ecdeccce4444444444444444444
571dbd094559570009135440000d85415210653955d01010d000000000000000000000d865
33645036092407362130259593520000000000000000000
..~ .0___ .8RRR . RESEARCH TRIANGLE
PARK..............................
Figure 25. Sample trace, part 4 - TN3270E flow

Chapter 3. Miscellaneous enhancements
There are many comparatively small enhancements in PCOMM 4.3. Here is a list
of them; more details follow.
• Enterprise Extender DLC - High Performance Routing (HPR) in a TCP/IP
network
• Connection, configuration and usability improvements
• New Customize Communication user interface
• Improved connection messages
• Status bar
• PCSCC058 message improvements
• Link reactivation
• Adjacent Control Point (CP) name changes
• New PCI adapters
• FMI auto-reconnect
• File-transfer improvements
• File-transfer buffer defaults changed
• CUT-mode file transfer
• Code-page and international support
• Euro currency support
• Extended Katakana support
• CStar and RichWin support
• Bar code printing (Japan)
• API/DLL improvements
• Wrapper APPC DLLs
• SLI API added
• HLLAPI improvements
• VB macro script
• New Viewer Utility for the message and trace-log file
• Other enhancements
• ARB Responsive Mode
• PCOMM and CA/400 coexistence
• "Confirm on Exit" GUI
• PCOMM for WinNT - SNA Node must not stop when you log off
• Delete Word Classic function
• New Edit function
• Configuration-wizard profile editing
• Printer-Dialog consolidation
• Replace IIN support

• GDDM and APL characters
• Internet service
3.1 Enterprise Extender

Many organizations have IP networks over which they want to use SNA-based
applications. With the introduction of Enterprise Extender, you can use High
Performance Routing (HPR), which is an SNA concept, in an IP-routed network.
Enterprise Extender allows you:

• To use IP between the origin node and the destination node of an Enterprise
Extender link to transport SNA data (something that AnyNet SNA over IP also
can do).
• To participate as a full APPN node in an APPN network (something that
AnyNet SNA over IP can't do).
• To benefit from the advantages of HPR.
The following documents contain more detailed information that can be useful
when configuring or troubleshooting HPR/IP links:
• High Performance Routing in IP Networks, document number HPRIP-06.
This is a contribution to assist the APPN Implementer's Workshop. It is
available via anonymous ftp from ftp.networking.ibm.com in the directory
/aiw/appn/hpr/.
• eNetwork Communications Server Version 6.0 for Windows NT and eNetwork
Personal Communications Version 4.2 for Windows 95 and Windows NT
Configuration File Reference, SC31-8655.
• Systems Network Architecture Formats, GA27-3136.
• Systems Network Architecture Technical Overview, GC30-3073.
• Inside APPN - The Essential Guide to the Next-Generation SNA, SG24-3669.
While Branch Extender is a new "node type", Enterprise Extender is rather a new
DLC. Enterprise Extender is a way to transport HPR NLPs in UDP packets. The
terms Enterprise Extender and HPR/IP are both used to describe this new
solution. This solution still allows you to take advantage of the HPR benefits in an
IP-routed network:
• Non-disruptive path-switches
• ARB flow/congestion control
• Distinction between high, low, medium and network priority
EEDLC uses IP port numbers 12000-12004 for all communications.
The EEDLC support now provided in PCOMM 4.3 is the same as EEDLC in
Communications Version V6. Please refer to IBM eNetwork Communications
Server for Windows NT Version 6.0 Enhancements, SG24-5232 for detailed
information on configuring and using EEDLC.

3.2 Connection configuration and usability improvements
These include a new user interface for configuring a session, and a new status
bar in the session window that provides improved connection messages. The
following features have been updated/added:
• New Customize Communication user interface
• Improved connection messages
• PCSCC058 message improvements
These features have been added to improve connection configuration, provide

information during the connection process, and to improve error indications in the
event of a failure to connect. Other connection improvements have been added as
well. These are:
• Link reactivation
• Adjacent Control Point (CP) name changed
• New PCI adapters
• FMI auto-reconnect
3.2.1 New Customize Communication user interface

Because of the large number of connections now available with PCOMM 4.3, it
was decided to completely change the configuration panels to accommodate this.
Configuring a connection through PCOMM 4.3 is now made easier with a change
from the old Railroad Track style of configuration to a new design.
Configuration usability has been increased by:

• Reducing the number of connectivity options viewed at one time
• Using controls and labels more consistent with the Configuration Wizard (SNA
config)
• Providing textual confirmation of selected connectivity options and maintaining
the graphical, or pictorial, feedback
• Improving flow during the selection process
The new user interface is started in the same way as previously.
In Figure 26, you can see three combo configuration boxes for type of host,
interface, and attachment. These always show default values that were selected
at initialization; the defaults can only be changed by using a template file to
preload some default configuration settings. See 1.7, “Configuration file update
support” on page 9 for information on how to do this.
Miscellaneous enhancements 31
Figure 26. New Customize Communication user interface
As each host or interface is selected, the interface and attachment combo boxes
change accordingly. Also, the pictorial and textual feedback sections are
automatically updated to explain the configuration you are selecting. Once a
connectivity is chosen, you must configure the Session and Link parameters,
which brings up the appropriate configuration dialog.
3.2.2 Improved connection messages

3.2.2.1 Status bar
A connection-status bar has been added to PCOMM 4.3’s session window.
During the connection process, text is displayed on the status bar, showing the
connection process (Figure 27):
Status bar
Figure 27. New connection-status bar
You can also see a history of the status bar messages; Figure 28 shows this.
Notice also that the text in the status bar changes when you select any option to
display help on that option.

Figure 28. Displaying the status bar history
Selecting Status Bar History brings up the window shown in Figure 29.
Figure 29. Status bar history
Status-bar text is stored in a history buffer and can be saved to the message log
for diagnostic purposes. Opening the message log viewer (Personal
Communications -> Administrative & PD Aids -> Log Viewer), will then show
the status bar history entry. See Figure 30.
Figure 30. Log Viewer showing PCSSB101 - emulator status bar history
3.2.3 PCSCC058 message improvements
In the past, PCSCC058 error messages did not clearly describe what the problem
was. This has been improved with the addition of four new messages that can be
displayed before the PCSCC058 message. These new messages are:
• PCSCC011 - The SNA subsystem could not be started, please check
message log (%s) for more information.
• PCSCC012 - A link error occurred while a connection was being established,
check message log (%s) for more information.
• PCSCC013 - Cannot start connection because the SNA subsystem has not
been started, see message log (%s) for more information.
• PCSCC014 - Cannot start connection because the device is inactive, please
check message log (%s) for more information.
PCSCC058 is still displayed, but the previous message(s) will help determine the
exact cause of the failure.
3.2.4 Link reactivation

Automatic link reactivation is now supported. Parameters have been added to the
SNA Node Configuration files (*.acg) for PORT and LINK_STATION definitions.
These are:
ACTIVATION_DELAY_TIMER
DELAY_APPLICATION_RETRIES
INHERIT_PORT_RETRY_PARMS (Link Station only)
MAX_ACTIVATION_ATTEMPTS
RETRY_LINK_ON_DISCONNECT
RETRY_LINK_ON_FAILED_START
RETRY_LINK_ON_FAILURE
These parameters are not accessible through the GUIs; you must edit the ACG
file to modify them. For information on these parameters, please refer to the
Configuration File Reference online manual.
3.2.5 Adjacent Control Point (CP) name changed

To improve ease of configuration the names for three of the adjacent CP types
have been changed from previous releases of PCOMM:
• "APPN Node" changed to >> "Learn Node"
"Learn" is now the default setting
• "Back-Level LEN Node" changed to >> "Subarea LEN Node"
An Adjacent CP Name is automatically generated when Subarea LEN is set:

Network name from node FQCP name + link name.
• "Host-XID3" changed to >> "HOST-Dependent LU Only"
The new default adjacent CP Type for LUA3270 sessions when NodeID (PUID)
is non-zero is now Subarea LEN (that is, Back-Level LEN); it was previously
HOST-XID3.

The old adjacent CP names can still be used.
3.2.6 New PCI adapters

New adapters supported with PCOMM 4.3 are:
• PCI MPA adapter
• PCI 3270 emulation adapter
Refer to the adapter publications for instructions on installing these adapters

under Windows 95, Windows 98, and Windows NT.
3.2.7 FMI auto-reconnect

FMI sessions now support the auto-reconnect function
If the Microsoft SNA client loses connection to the server, PCOMM will continue
to try and re-establish the session. This is automatic, so no configuration setting
is available.
If the SNA client has a backup server configured and is able to establish a
successful connection with the backup, PCOMM will attempt to establish a new
session with the host, using the new connection.
Support was first added in V4.2 CSD2. APAR IC23030 for V4.3 and IC22990 for
V4.2 CSD2 are available (see the APARs for details).
3.3 File transfer improvements

The following file transfer enhancements have been made:
• File transfer buffer defaults changed
• CUT mode file transfer added
3.3.1 File transfer buffer defaults changed

To improve file transfer performance, changes have been made to the default
buffer values:
The new defaults are:

• 2500 - ASCII1
• 1673 - AS/4002
• 8000 - TCP/IP
• 12288 (12 KB) - all others
3.3.2 CUT mode file transfer

PCOMM's file transfer was written to take advantage of 3270 structured fields
('D0'x) but some customers require connection without using these. To enable
this, the ASCII (CUT) code has been migrated into the DFT design. A new (.WS)
stanza and keyword have been created to enable this new feature; you must add
them manually:
1
Unaltered in V4.3
2
Unaltered, and unalterable
[Transfer]
CUTprotocol=Y
3.3.2.1 If file transfer fails

If a file transfer fails (times out), you can take a trace. The trace or screen will
show "Caaa" from the host after the IND$FILE command has been sent. Potential
problems could be:
• No SF Query Reply sent from PCOMM:
'88...LLLL81950000iiiiooooss01...'
• If a Bind exists (SNA connection), the reason is that the Query bit in the
PSERVIC is turned off (should be 0280):
'31010303B1903080000787A88700020000000000000000...'
3.4 Code page and international support

3.4.1 Euro currency symbol
Support for Euro code pages has been added; Table shows them.
Table 1. Euro code pages
Non-Euro Euro Country
037 1140 Australia, Brazil, Canada, Netherlands, New

Zealand, Portugal, USA
273 1141 Austria, Germany
277 1142 Denmark, Norway
278 1143 Finland, Sweden
280 1144 Italy
284 1145 Spain, Spanish Latin America
285 1146 UK
297 1147 France
500 1148 Belgium, Canada, Switzerland
871 1149 Iceland
500, 1047 924 Multi-lingual
Euro currency keyboard support has also been implemented. This is shown in
Figure 31 on page 37.

.
Figure 31. Euro-currency keyboard support
Euro currency support has been provided by adding a new character to PCOMM’s
fonts. The new code pages and additional keyboard characters work just like
other code pages and characters.
3.4.2 Translation tables for SBCS languages

PCOMM 4.3 uses IBM standard translation tables for SBCS languages, and
Windows native code pages for PC code pages. For previously supported code
pages, you can still use old (non-standard) translation tables by adding the
following setting to PCSWIN.INI:
UseOnlyPCOMM=Yes
Exactly the same functionality is also in 4.2 CSD 2 for Windows 95 and Windows
NT, and in PCOMM 4.2 CSD 1 for OS/2 (except that no PC code page changes
have been implemented).
3.4.3 Extended Katakana support

Extended Katakana support is also referred to as Japanese CP943 support.
Support of this code page allows PCOMM to provide support for all Group-3
countries.
3.4.4 CStar and RichWin support

CStar and RichWin support enables PCOMM 4.3 to provide support for "Shell"
environments that allow for simplified Chinese application support on US English
Microsoft operating systems. Changes were made to "disable" inherent DBCS
functions that CStar and RichWin provide:
• Translation tables
• Code pages
• Fonts
• IME (Input Method Enabler)
3.4.5 Bar code printing (Japan)

Japanese postal bar codes can now be printed on SCS (LU1) printer sessions.
This is supported in both PDT and GDI modes.
3.4.6 New national-language support

This encompasses:
• Code pages
• 275: Brazil - Host
• 943: Japan - PC
• 1252: Latin 1 - PC (Windows Native)
• 1254: Turkey - PC (Windows Native)
• Keyboards
• 457: Poland
• Fonts
• Mincho: Japan Windows 95 and Windows 98 only
• Translations
• Czech, Dutch, Hungarian, Polish, Slovenian
3.4.7 Things to watch for

Things to watch for with code page support are:
• Printer support depends on the printer's ability to print the character.
• You will probably need updated printer driver(s).
• Use of non-PCOMM fonts will require updates from font vendor.
3.5 API improvements
3.5.1 Wrapper APPC DLLs

Wrapper APPC DLL support has been provided to allow applications to use old
DLL names. The APPC DLL support is listed as follows:
Table 2. New APPC DLLs
Was Is
WinAPPC WAPPC32
WinCPIC WCPIC32
WinRUI WinRUI32
WinSLI WinSLI32
WinCSV WinCSV32

Note that the same entry-point names are used in either version, and that both
versions are 32-bit interfaces.
3.5.2 SLI API added

Session Level Interface (SLI) is an API that facilitates the opening and closing of
SNA sessions with host LU types 0, 1, 2, 3 application programs. SLI uses the
RUI API to perform communications input/output. The SLI source code is
common with that in CS NT. The API is documented in eNetwork
Communications Server Version 6.0 for Windows NT and eNetwork Personal
Communications Version 4.3 for Windows 95, Windows 98, and Windows NT
Client/Server Communications Programming, SC31-8479.
3.5.2.1 Tracing SLI applications

To trace SLI applications, set the API entry/exit points in PCOMM's Trace
Facility by selecting the trace points in Figure 32.
Figure 32. SLI trace options
3.5.3 HLLAPI improvements

The following HLLAPI improvements have been made:
3.5.3.1 WinHLLAPI support

Industry-standard WinHLLAPI interface support is provided. This provides
compatibility with Attachmate/Rumba WinHLLAPI applications.
• Both 16-bit and 32-bit versions supported
• WHLLAPI.DLL and WHLAPI32.DLL
3.5.3.2 Industry-standard 32-bit EHLLAPI

The industry-standard 32-bit EHLLAPI is supported providing a 32-bit interface
with the same structure layouts as IBM’s standard 16-bit interface. This is
compatible with Attachmate’s 32-bit industry-standard interface. The DLL used is:
• EHLAPI32.DLL
3.5.3.3 EHLLAPI performance improvements
Improvements have been made to EHLLAPI that greatly improve performance for
most applications. Screen-scraper applications can run up to 2x faster, for
example. Most of the improvements were also shipped in PCOMM 4.2 CSD #1.
Attention
Because of these performance improvements, certain timing-critical
applications may not run correctly. If you experience problems, you should
consider re-writing the application to incorporate a timing delay. Refer to
eNetwork Personal Communications Version 4.3 for Windows 95, Windows 98,
and Windows NT and Version 4.2 for OS/2 Emulator Programming, SC31-8478
for more information.
3.5.3.4 EHLLAPI print notification

EHLLAPI print notification allows print-job completion to be signalled via Start
Host Notify/QueryHostUpdate mechanisms:
• New option 'E' on StartHostNotify
• New RC '44' on QueryHostUpdate
3.5.3.5 DDE Convert

DDE Convert is now supported. This allows DDE applications written for PCOMM
Win16 that use the DDE Convert function to run on Win32.
3.5.4 Record VBScript macros

You now have the choice, when recording macros, to record in either the PCOMM
macro language or VBScript (Visual Basic). This is shown in Figure 33.
Figure 33. Record VBScript macro
VBScript macros use the HACL (Host Access Class Library) interface; the
components involved are PSHSH and PCSMC2VB. You can edit the script by
clicking Assist -> Macro Script Setup, selecting the macro, then clicking
Customize. See Figure 34.

Figure 34. VBScript macro editing
3.6 New viewer utility for the message and trace-log file
Major changes have been made to the PCOMM log viewer to improve usability.
These are:
• It is now a Multiple Document Interface (MDI) application.
Allows multiple log files to be viewed from the same window.
• It has new menu functions.
Supports viewing of trace log (*.tlg) files as well as message (*.mlg) files.
• New pop-up menu when you right-click on a message.
3.6.0.1 Multiple Document Interface (MDI)

This feature allows multiple files of (.MLG - LOG), or (.TLG - TRACE) format to be
opened. See Figure 35 below.
Figure 35. PCOMM 4.3 Log Viewer - multiple files open
3.6.0.2 Trace log (TLG) viewing

A very useful new feature is the ability to open PCOMM traces and then filter out
events to allow easier reading. This, combined with the MDI feature, allows you to
read a trace and MLG (Message Log File) at the same time. You can also sort the
entries into latest-first or oldest-first sequence or into types by clicking any of the
column titles or by right clicking in a column and clicking Sort. Figure 36 shows
an example of a read-in trace file.

Figure 36. PCOMM Log Viewer - showing trace
As mentioned, you can filter out unwanted trace points. To do this, right click on a
message or trace entry. Messages can be filtered by component only but traces
can be filtered by component, by process ID, or by thread ID.
Filter In - Include highlighted item
Filter Out - Exclude highlighted item
Figure 37. Trace Event filter options (right click the event)
3.7 Other enhancements

This section details other miscellaneous enhancements that have been made to
PCOMM 4.3.
3.7.1 ARB responsive mode

ARB responsive mode is a modified algorithm for HPR rate calculations. It
behaves better in mixed (SNA and TCP/IP) traffic networks and is still being
tuned by in-house testing with other products. The shipped product has the
function disabled by default but it can be enabled from the registry. To do so,
change the following value in the registry:
Key is HKEY_LOCAL_MACHINE\SOFTWARE\IBM\Personal Communications\CurrentVersion
The value is set by default to: ForceStandardARB: No; change it to Yes.
This is part of the SNA stack. To trace it, use the IPS trace. Additional RTP
logging can be enabled by changing the following registry key:
HKEY_LOCAL_MACHINE\SOFTWARE\IBM\Personal Communications\CurrentVersion
The value is set by default to: RTPTimesLogging: No; change it to Yes to enable
logging.
3.7.2 PCOMM and Client Access/400 co-existence

PCOMM 4.3 will now co-exist with Client Access Express Version 4 or later. Note
that CA Express provides TCP/IP communication only. The following two cases
are now possible:
1. Install PCOMM Version 4.3 and then install Client Access Express without the
5250 emulator, PC5250.
2. Install Client Access Express without PC5250 and then install PCOMM.
The real advantage is for Client Access users who require 3270 emulation. They
can use PCOMM for all types of emulation and use other functions provided by
Client Access simultaneously.
PCSWS.EXE is invoked from the CA Accessories folder (a /CA parameter is

added during installation). PCOMM mimics PC5250. When PCSWS.EXE is
invoked with the parameter /CA, the AS/400 session has the following changes:
• The Configuration menu-option invokes the PC5250 configuration panel.
• When you click Transfer on the menu or tool bar, Client Access Data Transfer
is invoked instead of APVAFILE file transfer.
• The menu-flow when saving the workstation profile is the same as in PC5250.
• By-pass signon is enabled.
PCSBAT.EXE (to start multiple sessions) is invoked from the CA Accessories

folder (/CA parameter is added during installation). When PCSBAT.EXE is
invoked with the parameter /CA, and if the user selects a workstation profile to be
included in the batch file (using the ADD button), the parameter /CA is added to
the PCSWS.EXE entry.
Note
PCOMM ignores the /CA parameter if Client Access Express is not installed.
No co-existence with other versions of CA (which have SNA) is supported.
3.7.3 Confirm on Exit GUI

A menu-function, Confirm on Exit has been added; this causes a confirmation
window to appear when you close a session. It was previously available by means
of a PCSWIN.INI parameter.
The menu selection is File->Exit Options.

Figure 38. Exit Options
3.7.4 PCOMM on Windows NT - SNA Node must not stop at logoff

Changes have been made so that, if the SNA Node is running on NT 4.0, it will
not be stopped when a logoff occurs. This is useful in the WinFrame (precursor to
Windows Terminal Server) environment because it allows a WinFrame
administrator to log on/off the server without affecting downstream clients.
Note: This setting is not enabled by default and can only be enabled via the
command line. To enable it, type:
CSSTART -a <filename>. (<filename> = the node configuration file)
This sets the SNA Node to be a Windows Service that starts automatically when
the system starts and that will not be affected by a user logoff. You should reboot
after making this change. If no configuration file is specified, it uses the default.
Typing CSSTART /? on a command line will provide help about other options
available with CSSTART:
csstart [-p | -q] [-a] [-m] [-d] [filename]
where:
-p display messages in a pop-up message box.
-q quiet mode, no messages are displayed.
-a enable automatic node start at boot time.
-m manual start, disables automatic start at boot time.
-d set the default configuration file name.
Note
Remember, this setting changes the node service type; it will not start the
node.
3.7.5 Delete Word Classic function

This change brings forward the CM/2 function that allows a user to selectively
replace deleted words with spaces so as to not change indentation. The function
is enabled through the (.WS) file:
[KEYBOARD]
DeleteWordClassic=Y
3.7.6 New edit function
The PCOMM 4.3 edit function has been changed. Click Edit -> Edit Options to
display the new options.
Figure 39. New edit options
You will notice that Cut/Copy options have been added:
Figure 40. New edit options - Cut/Copy
The option Only if a trim-rectangle is marked allows a copy or cut operation if

there is a trim rectangle currently on the host window. Click the box if you want to
copy only the trim rectangle that has been marked on the session screen. The
default is to copy the entire screen if no rectangle is marked.
3.7.7 SNA configuration wizard editing

In previous versions of PCOMM, the SNA configuration wizard didn't allow for
easy re-configuration. Minor changes have been made to correct this. The
changes are:
• Panel flow
• Panel layout
• Terminology
• More consistent look and feel

3.7.8 Printer dialog consolidation
Dialogs invoked by clicking the File->Printer Control->Text and File->Printer
Control->Graphics menu options have been consolidated; a property sheet
(tabbed dialog) is now used. Each session type contains Text, Text Options, and
Graphics tabs. To see this, click File->Page Setup. See Figure 41.
Figure 41. Page Setup - Text
Some parameters formerly in *.WS have been added to the new property sheet:
3.7.9 Replace IIN support

The IBM Global Network (IGN) is replacing all its dial-in gateways with LIG
gateways, which means that the IIN attachment will no longer work. As a result,
you must use one of the following attachment types:
• SBCS countries should use IBM Global Network.
• DBCS countries should use IBM Global Network - SNA Over Async.
3.7.10 GDDM enhancement

Support has been added to provide special GDDM graphics characters. A new
.WS keyword has been added to provide this:
[Edit]
XlateAplChar={SPACE,YES,NONE*} *default - anything else
• Space = convert to space (x'20')
• Yes = use the APL translation table
• None = process as in PCOMM 4.2
Windows must have an APL font available to support this - for example,
IBM3270APL, IBMVT, IBMAPL_VT_NORMAL (TrueType)
To add the PCOMM-supplied fonts, do the following:

1. Click Control Panel > Fonts > File > Install New Font.
2. Choose the PCOMM subdirectory.
3. Select the desired fonts (all is recommended).
4. Click Add.
3.7.11 Internet Service

A utility has been added, the Internet Service, that lets you transmit Information
Bundles to the PCOMM Service team quickly and easily. In the Windows Start
menu, click Programs > IBM Personal Communications > Administrative and
PD Aids > Internet Service. See Figure 42.
You can actually send bundles to

any valid FTP address. Just type a
new one here.
Browse for bundles in PCOMM's

private directory.
Need help? Look at Internet

Service's handy help guide.
Figure 42. Internet Service dialog
The PCOMM bundle file (x23456.ram) is created from the Information Bundler
tool that is one of the Administrative and PD Aids. Use the Internet Service's
Browse window to quickly find any information bundles that you have captured.
The Internet Service provides detailed help to guide you through the process of
transmitting information bundles.

Chapter 4. Load balancing and hot standby
Personal Communications Version 4.3 provides load balancing and hot
standby suppor t for TN3270 and TN5250 connectivity by means of the
Service Location Protocol (SLP); previously, only the Split Stack Client for
CS/NT and NetWare for SAA provided load balancing and hot standby.
Figure 43 shows the three types of connection that can use SLP. Network
resources can be collected together into administrative domains called
scopes. A scope can be thought of as a collection of services within a logical
group.
Figure 43. Connection types that can use SLP
4.1 Overview
The Service Location Protocol (SLP) is defined in Request for Comments
(RFC) 2165. It is a ser vice-discovery method for TCP/IP-based
communications, a simple and lightweight protocol for automatic
adver tisement and maintenance of intranet services and minimizes the use
of broadcast and multicast in the network. SLP uses multicast, which targets
a group of nodes, unlike broadcast, which targets all nodes. The benefit of
multicast is that it sends one packet that all the members of the group
receive but that only the intended recipients read. A multicast packet is not
isolated to a local segment; routers can forward it to whatever subnets are
attached.
Figure 44 on page 50 shows a group of servers that support SLP. Each server
broadcasts its hostname/IP address, scope name, type of service, secure or
non-secure, port numbers, LU-pool names and, for load balancing purposes, its
session load.

If a client were configured for scope1 only, the information returned by its service
request would include server1, server2 and server3 with their ports and the
current load on each. Similarly, if the client were configured for scope2 only, the
information returned would include server4, server5 and server6. However, if the
configuration specified unscoped servers, none would be returned.
Figure 44. SLP - how it works
4.1.1 Components of an SLP environment

There are three main parts of an SLP environment: servers, clients and agents.
4.1.1.1 Clients
Clients request services from servers by multicasting their requirements in terms
of scope, LU pool and security.
4.1.1.2 Servers
Servers respond to requests from clients by returning their capabilities as
described above. At present, only two servers support SLP: IBM Communications
Server for Windows NT (CS/NT) and NetWare for SAA 3.0 or later (NWSAA).
4.1.1.3 Agents
Three types of agent are involved in SLP; please see Figure 45.
User agents Request service information for user applications.
Service agents Adver tise service information.

Directory agents Collect the service information from a service agent in
the intranet. In small installations, there may be no
directory agents, in which case the request message is
sent directly to a service agent.
Figure 45. SLP agents
4.2 Load balancing

Load balancing is an important feature of IP support on NWSAA and CS/NT. It
uses SLP and is supported for LUx API applications through SNA API clients,
3270 emulators, and TN3270 emulators.
PCOMM takes the server list returned by its service request and sorts it by
least-to-most session load, then connects to the server with the least load.
The load for dependent LUs represents a percentage of available resources from
a particular server. The load percentage is calculated by dividing the number of
active application connections by the total number of LUs (0 to 3) available; this
means that, the more LUs there are defined on a server, the less will be the
notified load.
The CS/NT or NWSAA administrator can influence the calculated load by

specifying an LU0-to-3 load balancing weight factor (host-session load factor) to
compensate for differences between two servers, such as available memory,
processor speed, and CPU utilization. He can also use the LU0-to-3 load
Load balancing and hot standby 51

balancing weight factor to balance the loads between Communications Servers
and Novell NetWare for SAA servers.
Note: IP load balancing is based on session load.
Hot standby can be used in conjunction with load balancing.
Figure 46 shows the panel on which Telnet3270 SLP definitions are made. For
Telnet5250, the required definitions are the same except that LU or Pool Name is
replaced by AS/400 Name. The parameters are adequately explained in the Help;
however, please note that, for SPL, you cannot specify the name of an individual
LU - you can specify only the name of an LU pool.
Figure 46. Telnet3270 SLP configuration
4.3 Hot Standby

Hot standby is available with a direct IP connection or, for 3270, with QELMU over
IP; it can be used with or without load balancing or SLP. The principle of hot
standby is that, if the current connection fails, the client will automatically connect
to the next-specified host or LU/Pool but there are some qualifications:
• If the LU-to-LU session fails but the physical link does not, the session will not
move to another host or LU/Pool.
• With SLP, the switch to an alternative server requires that the client go through
the same multicast procedure as for the original connection, so the function
might be called "warm standby".
• For standby to work with SLP, Auto-reconnect must be set On.
4.3.1 Client configuration

In the session configuration, you must provide the server/host name and one or
more backup server/host names. If the session with the first server/host is not
available or goes down, PCOMM attempts to connect to the backup servers in
turn; you can specify up to three.

For 3270, hot standby can also be used for dedicated LUs if you do not use SLP;
up to three backup dedicated LUs can be specified. Alternatively, you can specify
up to three LU pools. Figure 47 illustrates this.
Figure 47. Telnet3270 hot standby configuration (without SLP)
For QELMU over TCP/IP, the configuration is different because other parameters
come into play. You can specify service names and several categories of LU, but
the principles are the same. Figure 48 shows the basic definitions.
Figure 48. Basic configuration for QELMU over IP
In Figure 49, you can see three sets of backup resources.

Figure 49. Advanced QELMU over IP configuration
4.3.2 Server configuration

Configuration of a CS/NT or NetWare server is dealt with in the appropriate
publication and will not be described here.
4.3.3 Troubleshooting
Here are two possible sources of difficulty with SLP:
• Default scope name. An asterisk is a valid scope name but the PCOMM
configuration panels have it as the default. If you use an asterisk but such
a scope does not exist, the OIA shows only "a" and the application hangs;
you cannot disconnect or reconfigure or even close the session - you
must kill the process through the task manager. The only valid default
value is "blank"; this will be fixed in a CSD.
• Routers. In the network shown in Figure 50, port 427, which is used for
multicasts, is not open in the router; as a result, multicasts do not pass to
NET2 and thus servers on NET 2 that specify the scope PRAVIN are not
found. The client on NET 1 can ping all the servers in NET 2 but cannot get a
session from a server there.

Net 2 SLP IP
NW SAA 3.0 provided CS/NT 6.0 provided

scope name "PRAVIN" scope name "PRAVIN"
Router forwards broadcast packets,

IP Router but does not open port 427.
!
Net 1 SLP IP
PComm client uses scopes

CS/NT 6.0 provided
"PRAVIN" and "TESTSCOPE"
scope name "TESTSCOPE"
Figure 50. SLP network example

Chapter 5. IPX enhancements
PCOMM provides many ways to connect to S/390 or AS/400 systems including
IPX/SPX, so it supports protocol independence in mixed TCP/IP, SNA, IPX, and
NetBIOS environments.
PCOMM 4.3 provides load balancing, hot standby, and Service Location Protocol
(SLP) support for LU2 Queue Element/Message Unit (QEL/MU) connectivity to
Communications Server for Windows NT (CS/NT) and NetWare for SAA servers.
"LAN via NetWare for SAA" connectivity has been renamed to "NWSAA or IBM
Communications Server" since CS/NT 6.0 added the support for this connectivity.
A further new feature is that you can specify that a connection be regarded as
suitable for a Bindery user, by checking a box.
5.1 Internal network number

When multiple servers share the same cabling system (called a multiserver
network), all IPX servers must have the same IPX external network number.
However, each server must have a unique IPX internal network number and a
unique node number.
When network cabling systems are connected through routers (internal or

external), each cabling system must have a unique IPX external network number,
and each NetWare 4 server must have a unique IPX internal network number.
The IPX external network number is the first item to be read in a packet
sending/receiving interaction. An internal network number assigns a logical
network for the NetWare server.
Note: You can change the internal network number only on an NT server, not on
a workstation. The following panels illustrate how to change it.

Figure 51. Internal network number - 8 digits required
On a NetWare server, the internal network number is defined in the

AUTOEXEC.NCF.
5.2 SAP and SAP agent

If you want to access CS/NT via IPX, you must have the Service Advertising
Protocol (SAP) agent installed on the NT server.
SAP is a protocol that provides a way for servers to advertise their services on a
NetWare internetwork. Routers send periodic SAP broadcasts to keep all routers
on the internetwork synchronized; they also send SAP update broadcasts
whenever they detect a change in the internetwork configuration.
Workstations can query the network to find a server by broadcasting SAP request
packets. When a workstation logs in to a network, it broadcasts a “Get Nearest
Server” SAP request and attaches to the first server that replies.
NetWare servers on IPX networks broadcast SAP and Routing Information

Protocol (RIP) packets every 60 seconds. These broadcasts circulate current
information about available services and routes within the network. IP networks,
however, do not support SAP/RIP broadcasts. Instead, the SAP and RIP
information for the NetWare/IP internetwork is maintained in a centralized
database called the Domain SAP/RIP Service (DSS).
Note: The acronym SAP is used for several different purposes and is therefore
confusing. In the Windows NT environment as well as in the context of routing
and IPX, SAP is an acronym for Service Advertising Protocol. In NetBeui and
802.2, SAP is an acronym for Service Access Point, in which each link-layer

program identifies itself by registering a unique service access point like port
number in TCP/IP. SAP is also a financial database application software.
Figure 52. Windows NT Services panel - SAP Agent
5.3 Hot standby and load balancing over IPX/SPX and TCP/IP
The NWSAA hot standby feature ensures that connections to a host can continue
to function when a critical server goes down, by triggering the activation of
alternative connections on a backup server. If the active session to the server
goes down because of server or link failure, Personal Communications will try to
reconnect the session with the provided backup server name, service name, or
pool name. Load balancing can be used in conjunction with hot standby.
Load balancing is a key feature of NWSAA that dynamically balances dependent

host-to-workstation sessions by distributing them to host links with the fewest
sessions. The servers participating in load balancing are determined by LU pool
membership: all NWSAA servers with LUs in pools of the same name can be
used for load balancing.
Note: NWSAA 3.0 IPX load balancing is done on SNA link or pool load, unlike
SLP (refer to TCP/IP), which load balances on overall server load.
When NWSAA (using IPX) responds to a request from a client emulator, it sorts
all the links in LU pools in order of load, instead of in alphabetical order. Links
with a higher number of sessions are moved down so that client requests for LU
assignment will be satisfied by the server or link with the least load.
IPX enhancements 59
5.4 Using the NWSAA or IBM Communications Server attachment
In previous releases of PCOMM, there was a LAN via IPX/SPX attachment-type;
in 4.3, this has been changed to NWSAA or Communications Server because
both these servers now accept IPX and TCP/IP connections.
The following panels show how to configure this attachment for CS/NT via IPX.
Figure 53. The NWSAA or IBM Communications Server attachment
For CS/NT access via IPX, you must click Advanced so that you can check the
box IBM Communications Server.
Figure 54. First Link Parameters panel - choose the IPX protocol

If you are configuring for IPX and check IBM Communications Server in the next
panel, you have no hot standby or backup servers. With IPX, these are available
only for NWSAA.
Figure 55. Check the IBM Communications Server box
For Server Name, enter the computer name as defined in Network Properties.
The User Name is the user ID defined by the NT user manager.
The LU Category Any cannot be used for CS/NT access. Use Public, or Pooled
and a pool name.
Figure 56. Specifying the server and user name and the pool type
IPX enhancements 61
When you start the session, you may see an error message on the status bar
because login is required but the login prompt soon comes up.
Figure 57. IPX login panel
Figure 58. Successful connection and status bar information
5.5 The bindery user checkbox

There is a checkbox on the Advanced panel of the NWSAA or IBM
Communications Server attachment that lets you specify the user type as
Bindery. If you do not check this box, then the user is assumed to be defined in an
NDS tree.

Figure 59. Bindery user setting
If the user is logged into a NetWare Server Bindery context (for example,
contextA) and NWSAA is located on a server with a different context (for example,
contextB), check the Bindery User NetWare User Type on the advanced
configuration panel for user to be authenticated as a bindery user. This function
was not available in previous PCOMM releases and many customers asked for it.
5.6 Troubleshooting
CS/NT has many troubleshooting facilities; those that pertain to PCOMM
attachments are mentioned here.
5.6.1 Node Operations Facility on CS/NT

The primary tool is the Node Operations Facility (Node OPS), the main panel of
which is shown below.
IPX enhancements 63
Figure 60. Node Operations main panel
When a connection is successful, the LU icon changes from black to green.
Figure 61. Successful connection (TESTLU02 is green)
5.6.2 SNA Client Services

As shown in the next panel, SNA Client Services must be started; you can
confirm this by clicking Control Panel -> Services.

Figure 62. The Services control panel
The services are configured through SNA Node Operations.
Figure 63. SNA Node Operations - SNA API Clients
IPX enhancements 65
Figure 64. Enabling SNA API Client Services
5.6.3 Problems with the user ID

If the user is defined but is not a member of the IBMCSAPI group, he will get a
login prompt but no session. The symptom of this is that the status bar shows
error code 1415 or 1425.
Figure 65. Defining a user as a member of the IBMCSAPI group
If the user ID is not defined on the NT Server, the likely error message is 1424.
5.6.4 Problems with the internal network number

If the PCOMM client is using IPX and there are no other working clients in the
network, it may be difficult to find the reason why PCOMM does not connect. The
problem may not have anything to do with PCOMM, but it is often difficult to
determine the real cause.
One possible cause is that there is another server that has the same Internal
Network Number as the CS/NT. To check this, you can use a NetWare Server.

You can log in as admin from any computer to find out what systems are active
and what their internal network numbers are and then use LOAD MONITOR and
CONNECTIONS on the NetWare Server Console and press F6 to see the
machines on which a user has logged in. The next panel shows this.
Figure 66. NetWare server, active connections
Here is the information about an NT server with internal network number

08154711. The MAC address is not displayed.
Figure 67. Internal network name displayed by a NetWare console
On a NetWare server we can see the external network number via LOAD
INETCFG or via LOAD INSTALL -> NCF FILE OPTIONS -> EDIT
AUTOEXEC.NCF. The next panel shows information provided by the first of these
commands.
IPX enhancements 67
Figure 68. External network address
AUTOEXEC.NCF also shows the internal network number of a NetWare server:
Figure 69. Internal network address via AUTOEXEC.NCF
This is the external network number in AUTOEXEC.NCF:
Figure 70. External network address via AUTOEXEC.NCF

5.6.5 IPX clients (NetWare clients/Novell clients)
PCOMM as an IPX client requires only an IPX/SPX protocol stack.
On a Windows NT 4.0 workstation without SP, we used the IPX/SPX protocol

stack provided with Windows and the NetWare client provided with Windows. We
also used the NetWare Client 4.11b for Windows NT from Novell’s Web page;
both worked equally well.
On the Windows NT 4.0 server with SP3, running as a CS/NT and as a PCOMM
client, we used the IPX/SPX protocol stack and the NetWare client provided with
Windows.
On Windows 98, we had to use the NetWare Client 3.1 for Win95/98 from Novell’s
Web page.
IPX enhancements 69
Chapter 6. VT emulation enhancements
For connection to ASCII hosts, Personal Communications provides an emulator
for VT340, VT220, VT100, and VT52 terminals. ASCII hosts commonly use these
terminals’ control sequences as standards for session presentation, and many
ASCII-host application programs assume a VT-compatible terminal. Software that
is designed to operate a VT terminal should work correctly with the Personal
Communications VT emulator.
PCOMM 4.3 has several VT-emulation enhancements:

• Code page 437 support
• Advanced configuration panel
• VT local edit options
• VT graphics options
• VT keyboard changes
• Text enhancements for VT340
• Graphics support for VT340
We will discuss each of the enhancements in this chapter.
6.1 Configuration improvements

Numerous configuration options have been added to the Session Parameters
configuration panel for the ASCII host; see Figure 71.
Figure 71. Configuration improvements
Figure 72 shows the new Advanced configuration panel.

Figure 72. Advanced VT configuration panel
6.1.1 VT graphics configuration options

The graphics configuration options are:
• Graphics Cursor: Determines whether the cursor is displayed.
Selecting this option causes the graphics input cursor to be displayed when in
graphics mode.
Enabled: Default, displays cursor while in graphics mode.
Disabled: No cursor is displayed in graphics mode.
• Sixel Scrolling: Determines scrolling in sixel graphics.
Selecting this option causes sixel graphics to advance to the next row when
the last column is reached.
Enabled: Default, sixel images start at the current cursor and scroll when
the bottom margin is reached.
Disabled: Sixel images start in the upper left-hand corner and any attempt
to draw past the bottom margin is ignored.
• Macrograph Reports: Determines the contents of a ReGIS report.
If selected, this option activates macrograph reporting; otherwise, macrograph
reports are rejected.
Enabled: Sends a macrograph report as part of the ReGIS report.
Disabled: Default, no macrograph report is sent.
6.1.2 VT local edit configuration options

• Edit Mode: Determines local-edit availability.
This options indicates whether local editing is available and, if so, what the
current editing mode is. Possible values are Unavailable, Interactive, and Edit.
Unavailable: Default, local edit cannot be used.

Interactive: Shift+Edit key can be used to turn on Edit mode.
Edit: Session is in Edit mode; to switch to Interactive use the Shift+Edit key.
• Erasure Mode: Determines characters to be erased.
This option determines the characters that you or the host can erase when in
Edit mode. Possible values are Unprotected and All.
All: Any character, whether protected or not, can be erased.
Unprotected: Default, only unprotected characters can be erased.
• Edit Key: Determines how the user switches to Edit mode.
This option determines how the VT340 emulation switches between
Interactive and Edit mode. Possible values are Immediate, and Deferred.
Immediate: Default, mode changes to Edit when the Shift+Edit key is
pressed.
Deferred: The host determines when to switch after the user presses the
Shift+Edit key.
• Transmit: Determines when a block of data is transmitted.
This option indicates how a block of data is transmitted to the host when in
Edit mode. Possible values are Immediate or Deferred.
Immediate: Default, data is transmitted when the Transmit key is pressed.
Deferred: When the Transmit key is pressed, a notice is sent to the host,
and the keyboard is locked until the host sends a transmit sequence.
• Application Keys: Determines how the F6 - F20 (unshifted) keys function.
This option determines how the unshifted function keys F6 through F20
operate when in Edit mode. Possible values are Disabled, Immediate, Prefix,
and Suffix.
Disabled: Default, F6 - F20 keys do not work in local-edit mode.
Immediate: When F6-F20 are assigned application functions, these keys
are sent immediately to the host.
Prefix: F6-F20 keys are sent to the host prior to a block of data.
Suffix: F6-F20 keys are sent to the host after a block of data.
• Guarded Area: Determines if protected characters can be sent to the host.
This option indicates whether you can send protected characters to the host.
Possible values are All or Unprotected.
All: Default, all characters are transmitted.
Unprotected: Only unprotected characters are transmitted.
• Selected Area: Determines if only selected characters are transmitted to the
host.
This option indicates whether all characters are sent to the host or only
selected characters. Possible values are All or Selected.
All: Default, All characters are transmitted.
Selected: Only selected areas are transmitted.
• Multiple Area: Determines if multiple selected areas can be transmitted or
only the one where the cursor resides.
VT emulation enhancements 73
This option indicates whether all selected areas on the page are sent to the
host or only the area selected by the cursor. This option is ignored if the
Selected Area field is set to All. Possible values are Multiple and Single.
Multiple: Default, transmits all selected areas.
Single: Transmits only area where the cursor resides.
• VT131 Transfer: Determines whether to use the ANSI style or the VT131 style
of data transmission.
This option indicates the type of data transmission used if the Line Transmit
Mode field is deselected. The size of the block is based on whether the
Transfer Termination Mode field is selected. Possible values are ANSI or
VT131.
ANSI: Default, uses ANSI standard.
VT131: Works like a VT131 terminal.
• Line Transmit Mode: Determines how to send characters.
Selecting this option indicates that characters are sent to the host one line at a
time.
Disabled: Default, sends full or partial page based on Transfer Termination
setting and VT131 Transfer setting.
Enabled: Transmits only a line of characters.
• Transfer Termination Mode: When Line Transmit mode is disabled then this
option determines if the scrolling region or a partial page is transmitted.
Selecting this option indicates that a partial page or the scrolling region is sent
to the host. This field is ignored if the Line Transmit Mode field is selected.
Enabled: Default, the scrolling region will be transmitted.
Disabled: Transmits a block of data based on VT131 Transfer Mode setting.
• EOL Characters: Sets the End of Line indicator.
This option enables you to specify the characters used to indicate the end of a
line (EOL) in a data block. The default value used for VT340 emulation is a
carriage return (CR). You can specify up to six hexadecimal characters.
^M: x'0D' (CR) is the default setting.
The user may enter control characters by keying in the circumflex followed
by the appropriate character.
• EOB Characters: Sets the End of Block indicator.
This option enables you to specify the characters used to indicate the end of a
data block (EOB). There is no default value for this field. You can specify up to
six hexadecimal characters.
The user may enter control characters by keying in the circumflex followed
by the appropriate character.
• Page Coupling: Determines scrolling mechanism when the cursor moves to a
new page in memory.
Selecting this option couples the cursor to the display when the cursor moves
to a new page. The new page appears in the display to keep the cursor visible.
The active screen always has the cursor.

Enabled: Default, displays next page in memory.
Disabled: Cursor moves off of display.
• Space Compression Mode: Determines how blanks and unused fields are
transmitted to the host.
Selecting this option determines how unused character fields and spaces in a
data block are sent to the host.
Disabled: Default, sends a space for every unused character position.
Enabled: A record separator is sent for unused characters and the last field on
a line has an End Of Line character.
6.2 VT keyboard changes

Numerous changes have been made to the VT keyboard layout; these are
outlined below.
6.2.1 Top-row function keys

• F1 key: Base function is now VT Hold; VT Hold function will freeze the screen.
• F2 key: Base function is now VT Compose; this key allows users to compose
key sequences to display characters that do not appear on the keyboard.
• F3 key: Base function is now VT Help; sends the help CSI sequence to the
host.
• F4 key: Base function is now VT Do; sends the Do CSI sequence, which is the
same as F16 (Shift+F4).
• F5 key: Base function is now Break; ends communication with the session.
• Pause key: Now has no function, but used to be Break.
6.2.2 Miscellaneous key changes

• Home key: Shift function is now VT Edit, which is used to shift in and out of
local edit mode.
• Delete key: Shift function is now VT Clear Page/Car field, which is a key used
in local edit. Ctrl function is now Edit-Cut.
6.2.3 NUMPAD key changes

• Num Lock key: Base function is VT PF1, and shift function is now VT Backtab.
• / key: Base function is now VT PF2.
• * key: Base function is now VT PF3.
• - key: Base function is now VT PF4.
• + key: Base function is now "VT numpad," and shift function is now
VT numpad-.
6.3 VT 340 text enhancements

The following VT 340 text enhancements have been made:
• Page memory
• Character protection
• Independent protection
• Visual attribute protection
• Local edit and block transmission
• Panning and cursor coupling
6.3.1 VT text page memory

Page memory is a mechanism used by the emulator to store more than one
screen’s (24x80/132) worth of data. At a given time, only 24 lines of page memory
are visible in the logical/physical display space. The Scrolling and Panning
functions are used to move around the logical display. There are four modes of
page memory. These are:
• Mode 1: 6 pages of 24 lines x 80 or 132 columns
• Mode 4: 1 page of 144 lines x 80 or 132 columns
- 6 pages of 24 lines
x 80 or 132 columns
x 80 or 132 columns
x 80 or 132 columns
- 1 page of 144 lines

x 80 or 132 columns
Figure 73. VT text - page-memory modes
The host application determines whether or not the emulator is using page
memory; it is not a feature that is turned on or off by the end user. Page memory
should not be confused with a feature on most VT emulations known as a History
Window or Logging.
6.3.2 VT text-character protection

VT text-character protection is similar in concept to 3270 protected fields. This
capability enables host applications to designate cells as being protected from
commands and events that would alter their contents. Their are two types of
character protection supported:
• Independent protection
• Visual attribute protection

6.3.2.1 Independent protection
Independent character protection allows the host application to protect characters
in page memory, independent of their visual attributes (bold, underline, blinking,
on so forth).
In normal (interactive) mode, the following control functions cannot change, erase
or move protected characters:
• Erase in display (ED)
• Erase in line (EL)
• Erase character (ECH)
In edit mode, the following control functions will not change, erase or move
protected characters:
• Insert line (IL)
• Insert character (ICH)
• Delete line (DL)
• Delete character (DCH)
6.3.2.2 Visual attribute protection

This style of protection allows the host application to specify character protection
based on the character's visual attributes. These attributes are:
• Normal (no attributes)
• Bold
• Underlined
• Blinking
• Negative
• Invisible
The following control functions cannot change, erase or move visual protected
characters:
• Insert line (IL)
• Insert character (ICH)
• Delete line (DL)
• Delete character (DCH)
• Erase display (ED)
• Erase in line (EL)
• Erase character (ECH)
6.3.2.3 VT text protection style differences

The two character-protection styles, Independent and Visual-Attribute, differ in
three basic ways:
1. Independent protection lets you protect characters independent of their visual
character attributes. Visual-attribute protection applies to characters with the
same visual character attribute.
2. You can use independent protection in any operating mode (interactive or
edit). Visual-attribute protection is only available in edit mode.
3. The state of Independent protection mode is dependent on the current erasure
mode (ERM) setting. Visual-attribute protection mode is not bound to the ERM
setting.
6.3.3 VT text local edit and block transmission
The VT340 emulation can operate as an interactive (echo mode) or editing (block
mode) terminal. An interactive terminal immediately sends each character typed
to the host. An editing terminal stores each character typed in local page memory
and displays that character on screen. Then, when the transmit key is pressed,
the data is sent in a block to the host.
Interactive mode is the default when the terminal is first started. Edit mode is
made available via the Edit mode field on the Customize Communication
configuration panel. If available, switching between edit mode and interactive
mode is accomplished via a host command (DECEDM) or the Shift+Home keys.
Currently, the home key is assigned the VT Edit key function.
Note
Edit mode is not an optional mode. It must be supported by the host
application or the terminal will not work properly.
Three new OIA messages have been added to support local editing. These are:
1. Indicator for whether or not in Edit mode
2. Insert/Overstrike indicator
3. Page-number indicator
This is shown in Figure 74 below.
#2 Insert or Overstrike #1 Edit mode indicator #3 Page indicator

indicator(Columns 30-39) (Columns 66-69) (Columns 71,72)
Figure 74. VT text - local edit and block transmission
6.3.4 VT text - panning and cursor coupling

Panning is the movement of the user window through page memory. By panning,
the user is able to view different parts of page memory. Data is not lost in page
memory, rather the view window is simply moved. Panning is different from
scrolling because:
• Scrolling moves the data between the margins of a page.
• Data that is scrolled beyond the margins is lost from page memory.
A coupled cursor is a cursor that appears to drag the user window through page
memory. When the host application writes data to an area of page memory that is
not currently visible, the view window will pan to that area to display the newly
written data.

Page memory, character protection, local edit, block transmission, panning, and
cursor coupling all work together to create a solution for block mode host
applications. This is very similar in concept to the 3270 session.
Note
PCOMM 4.3 does not need to use panning, and cursor coupling functions, as
PCOMM’s implementation sizes the window to match the line-length (24, 36, 72
or 144).
6.4 VT graphics enhancements

Graphics enhancements have been added to VT in PCOMM 4.3. These are:
• ReGIS Graphics
• Sixel Graphics
• Graphics Behavior
• The VT emulation is in text mode at startup.
• Graphics modes are entered and exited via host commands.
• When in a graphics mode, all data from the host is interpreted as graphics
data, until the graphics mode terminator sequence is received.
• When the terminator is received, the emulation goes back to text-mode
operation.
6.4.1 VT graphics - ReGIS

ReGIS is a graphics instruction set for building geometric images. The building
blocks of these images are standard geometric forms: dots, lines, curves, circles
and arcs. In addition to the geometric forms are text characters and shading.
ReGIS allows for user input via a pointing device, such as the mouse.
ReGIS graphics mode entry and exit:

• Entry: <esc> P or (DCS) followed by P1 then a p
P1 is a mode switch that determines whether command state information is
retained.
• Exit: <esc> \ or (ST)
When ReGIS mode is started, the virtual screen and physical screen space is
limited to what is visible in the PCOMM client's window:
• The default mapping space is 800 pixels across by 480 pixels down.
• The upper-left corner of the screen is coordinate 0,0.
The ReGIS instruction set can be divided into 11 distinct command sets:
1. Screen control (S)
2. Write control (W)
3. Position (P)
4. Vector control (V)
5. Curve command (C)
6. Text command (T)
7. Load command (L) not supported
8. Macrograph facility (@)
9. Report command (R)
10.Polygon fill (F)
11.Re-synchronization (;)
Each of the commands can have many options. The entire ReGIS data stream is
in a somewhat readable ASCII data format. For example:
• This command draws a circle 'C[+50]'
• These commands move the cursor to coordinate 100,100 and draw a line that
is 100 pixels in length 'P[100,100]V[-100]'
Beneath the 11 command types are 60 options. Some of the options are shared
across the command types, while others are unique to a command. Some of the
suboptions have suboptions themselves. The complexity of understanding issues
with ReGIS is in the combination of different commands and their effect on the
display space. See Figure 75.
Figure 75. VT Graphics - ReGIS sample
6.4.2 VT graphics - Sixel

A sixel is a group of six pixels in a vertical column. A collection of sixel data is
really bitmap data that defines a graphic image. A sixel data stream can be
processed when the terminal emulation is in normal text mode only.
Sixel data stream introducer: <esc>P or (DCS) followed by P1; P2; P3; then a q.
• P1 is the pixel aspect ratio.
• P2 is the background color mode.
• P3 is the horizontal grid size parameter.

The sixel data stream terminator is <esc> \ or (ST).
As the sixel data is processed, it is possible for the sixel to display beyond the
bottom margin; if so, the display is scrolled. See Figure 76.
Figure 76. VT graphics - sixel example
Chapter 7. Database access with PCOMM 4.3
Database access has been improved. PCOMM 4.3 comes shipped with DB2
Connect 5.2 for Personal Communications, which is a light version of DB2
Connect and has been provided with Personal Communications for ODBC
database access. DB2 comes with ODBC V3 driver support, enabling an ODBC
connection to any DB2 database by using only one driver. ODBC is an API that
provides a powerful means of communicating with a database; with ODBC, a user
can access a database on a host from a PC using any ODBC-enabled
application, for example, Lotus 1-2-3. This allows full access to a remote
database using SQL to perform functions such as querying the data on a
database and displaying it in a spreadsheet, and the ability to change data on the
database from the PC application.
DB2 Connect implements the Distributed Relational Database Architecture

(DRDA) to reduce the cost and complexity of accessing data stored in DB2 for
AS/400, OS/390, MVS/ESA, VSE and VM, and other DRDA-compliant database
servers. By fully exploiting the DRDA architecture, DB2 Connect offers a
well-performing, low-cost solution with the system-management characteristics
that customers demand.
This chapter describes how ODBC is implemented with PCOMM 4.3 and gives an
example of how to configure a connection to a DB2 database on an AS/400,
using ODBC.
7.1 Introduction to ODBC

ODBC is an industry-standard application programming interface (API) that
provides a solution to a common problem—how to write programs that access a
Database Management System (DBMS) without making them dependent on
specific DBMS designs. ODBC provides API access to SQL-accessible
databases, allowing application programs to use SQL to access data from many
kinds of sources. The independence of the access method from the original
design of the database means that developers can design and produce a single
version of an application that can work with, for example, DB2, Oracle, or Sybase
data, without requiring a separate version for each DBMS. Users simply add
database drivers to link the application to their choice of DBMS.
Previously, with PCOMM 4.2, two ODBC drivers were provided (for MVS and for
AS/400). Configuration of an ODBC data source was through the ODBC
Administrator. This has changed with PCOMM 4.3; ODBC access is now through
one ODBC driver provided by DB2 Connect.
Note: This does not provide TCP/IP connectivity for database access; the
full-product version of DB2 Connect would be required for this.
Figure 77 shows how ODBC is implemented with PCOMM 4.2 and PCOMM 4.3;
You can see that a DB2 ODBC driver is used for PCOMM 4.3 database access.

Figure 77. How ODBC works with a database connection
7.2 Configuring ODBC data sources

An ODBC data source is a standard ODBC term for a collection of parameters
that a PC needs to know in order to establish database connectivity with a
specific database on the host. Figure 78 shows a comparison between the ODBC
implementation in PCOMM 4.2 and the new implementation in PCOMM 4.3; as
you can see, only one ODBC driver is now required.

Figure 78. Comparison between PCOMM 4.2 and PCOMM 4.3 database access
7.2.1 How it works

ODBC support is provided by DB2 (not by PCOMM as with Version 4.2). DB2 has
changed the way that the ODBC data source is configured. The configuration of
data sources is done through the DB2 Client Configuration Assistant (CCA). DB2
calls the data-source a database connection; however, it is the same thing.
When a configuration is created using DB2 CCA, the configuration is stored

internally within DB2 instead of by the ODBC Driver Manager, as it was with
PCOMM 4.2. DB2 places the data-source name into the ODBC Driver Manager
as a reference to its configuration information. This means that the ODBC
Administrator contains only the name of the data source, and not the actual
parameters (that is, connection information). The name refers to the location of
the configuration parameters so that the DB2 ODBC driver can get them.
Figure 79 shows how ODBC works with PCOMM 4.3.
Database access with PCOMM 4.3 85

Figure 79. DB2 ODBC connection
For example, if your application makes a request to use ODBC, the request
enters the ODBC Driver Manager and chooses which data source to use for its
connection. The ODBC Driver Manager then calls DB2CLI.DLL as the driver. DB2
then goes to its configuration information and looks up the data-source
parameters for the data source specified when the database connection was
created. This means that DB2 is keeping track of all data sources itself internally,
referring them to their appropriate ODBC name in the driver manager.
Attention
It is recommended that you use DB2 Client Configuration Assistant (CCA) to
add and configure your data sources.
7.3 PCOMM ODBC database-configuration requirements

Because OS/400 is DRDA compliant from V4R2, only one driver is now required
for connections to both MVS and AS/400 systems. Conversely, earlier versions of
OS/400 cannot be used for ODBC access with PCOMM 4.3; PCOMM V4.2 is
required.
The addition and configuration of DB2 database connections are handled using
DB2’s Client Configuration Assistant (CCA), and not the ODBC Administrator as
with PCOMM 4.2. When you configure DB2 database connections using DB2’s
CCA, it automatically creates and registers ODBC data sources for the
connection. The names of the data sources it creates can be modified, as before,
using CCA.

To connect to an AS/400, the following information is required:
• LAA or MAC address of the AS/400
• Fully Qualified CP name of the AS/400
• Mode definition
• CPI-C Side information for the new mode definition
• Transaction Program name from the AS/400:
• X'07F6C4C2' or RDB_NAME for DB2 for VSE and VM
• DB2DRDA for DB2 for OS/390
Note
DB2 Connect for Personal Communications allows an APPC ODBC

connection only. Configuration for a TCP/IP ODBC connection with
this version of DB2 is not possible; the full version of DB2 Connect is
required for this. However, a configuration can be done using Anynet
SNA over IP to provide support for TCP/IP networks.
7.4 Sample configuration

In this section we guide you through a sample configuration for ODBC access,
using DB2 Connect for Personal Communications. This sample is for configuring
the PCOMM 4.3 SNA node and a data source, using DB2 CCA. In a LAN
environment, this could be automated by creating a DB2 client configuration file
and SNA node configuration file that could be rolled out to users. For information
regarding DB2 and SNA node distribution, refer to the online books, DB2
Information Centre and 2.6 Configuration File Update Support, respectively.
Figure 81 refers to the sample configuration that will be created. Because ODBC
is an open API, any application written to use ODBC can be used, such as
Microsoft Access or Excel, or Personal Communications’ own ODBC application,
Database Access. The program allows data to be retrieved from the host
database using SQL queries. There is a sample configuration for the program that
can be used with this database configuration. Please refer to 7.5, “Database
Access Utility” on page 95 for more information on this program and how it can be
configured to access a host database.

A S /4 0 0
A P P C /C P I-C
O D B C D ri v e r :
D B 2 C L I.D L L
(D B 2 C l ie n t )
O D B C D ri v e r M a n a g e r
M ic r o s o ft L o tu s J o e 's
Access A p p ro a c h App
or o r 1 -2 - 3
Excel
Figure 80. Sample configuration
7.4.1 Summary of configuration steps

1. PCOMM SNA Node Configuration
The PCOMM SNA Node must be configured first. When defining the local
Fully Qualified CP name, make sure that it is not changed in the future if you
are connecting to the same AS/400. Otherwise, the controller definition on the
AS/400 will have to be reset, since it ties the name to the MAC/LAA address at
the first connection.
2. DB2 Client Configuration Assistant
Make sure that DB2 Connect for Personal Communications has been installed.
This is an option in the installation program and is not installed by default.
Configuring ODBC requires the Client Configuration Assistant (located in the
DB2 for NT folder). Selecting Add Database starts the Add Database wizard,
which guides you through configuring an ODBC database connection (the first
time you launch the CCA, the wizard starts automatically).
7.4.2 PCOMM SNA Node configuration

1. Configure node.
Configure the local FQ CP name as shown in Figure 81.

Figure 81. SNA Node configuration example
2. Configure devices.
Configure Client’s LAN device here.
3. Configure connections.
Configure the link to the AS/400 here. You must provide the MAC/LAA address
of the AS/400. On the Advanced tab, enter the Adjacent CP name for the
AS/400. The Adjacent CP type can be left at Learn.
4. Configure modes
Create a new Mode definition called IBMRDB; this is the DRDA mode used on
the AS/400. Select BLANK, and View->Change->Add. Change the Mode
name to IBMRDB, and keep all other parameters at their defaults. See Figure
82.

Figure 82. Mode definition
5. Configure CPI-C side information

Enter the CPI-C symbolic destination name here; this will be used later to
configure ODBC in the DB2 Client Configuration Assistant. The Transaction
Program (TP) name will also need to be entered for the new Mode definition
IBMRDB. In this sample, we will use 076DB, which is a Service TP for DB2 on
the AS/400 (the Service TP box must be checked).
Check with the system administrator if you are unsure what TP name to use;
there is more information on choosing Transaction Program names in various
DB2 publications. See Figure 83.

Figure 83. CPI-C Side Information window
7.4.3 DB2 Client Configuration Assistant

Start the DB2 Client Configuration Assistant (located in the DB2 for Windows
folder).
1. Choose Add database to start the Add Database SmartGuide wizard.
2. Select Manually configure a connection to a DB2 database, then click
Next.
3. From the Protocol tab choose APPC.
Note: You cannot use a TCP/IP connection unless the full DB2 Connect
product is installed. See Figure 84.

Figure 84. DB2 Client Configuration - Update Connection SmartGuide - Protocol tab
4. APPC tab: Enter the symbolic destination name (CPI-C name) here. This is
the symbolic destination name that was configured under the PCOMM SNA
Node configuration in the CPI-C Side Information. See Figure 85.
Figure 85. DB2 Update Connection SmartGuide - APPC tab

5. Target Database tab: Enter the database name here. See Figure 86.
Figure 86. DB2 Update Connection SmartGuide - Target Database tab
6. Alias tab: You can enter an Alias name for your database connection here.
Figure 87. DB2 Update Connection SmartGuide - Alias tab

7. ODBC tab: Check the Register this database for ODBC check box, and
choose whether the data source is to be for this machine or for the current
user. See Figure 88:
Figure 88. DB2 Update Connection SmartGuide - ODBC tab
Make sure that the SNA node configuration is correct, and that you have an
Active link to the AS/400. To do this, click PCOMM SNA Node Operations ->
Start the Node, and check that the upstream link is active by clicking View
Connections. Next, test your database connection. To do this select Done; you
are then given the opportunity to test the database connection. Click Test
Connection. See Figure 89:
Figure 89. Test database connection
When the database configuration has been tested, you will be shown the main
Client Configuration Assistant screen again, with the new database connection
definition. See Figure 90:

Figure 90. Client Configuration Assistant window - new database connection definition
7.5 Database Access Utility

The Database Access Utility can be found in the IBM Personal Communications
Utilities folder; it has not changed from PCOMM 4.2. Database Access lets you
access host or PC databases and retrieve data, using ODBC drivers. See Figure
91. If you specify the conditions for accessing data in each window, the desired
query is created automatically.

Figure 91. Database Access Utility - not connected to data source
From Database Access, you can perform any of the following actions:
• You can see and modify the SQL statements that are created automatically.
• You can see available database-table lists.
• You can copy spreadsheet data to the clipboard.
• You can show data in the grid in the main window spreadsheet, send data to
other applications (for example Lotus 1-2-3 or Microsoft Excel), or send data
to a printer.
• If you want to know the meaning of items in the windows, you can see an
explanation when you select the item and then click Help.
The Database Access Utility acts like any other ODBC application program, and
simply pipes standard functional requests into the ODBC Driver Manager. The
ODBC Driver Manager would then pass those requests to the specified ODBC
driver.
7.5.1 Configuring the Database Access Utility

Before you configure the Database Access Utility, prepare a data source by
configuring an SNA emulator session or an SNA Node configuration to an
AS/400. To configure the utility, select Query > Data Source then, from the
screen shown in Figure 92, click Machine Data Source to select the data source
that you configured.

Figure 92. Select Data Source window
Finally, you will be prompted to connect to the database on the host. First, select
the database name that was created using DB2 CCA (ELCRTP06 in this
example), then enter the user ID and password to connect. See Figure 93.
Figure 93. Connecting to the host database

Once connected, Database Access will show "Connected" at the top of the
screen. You can now query data on the host. An example of this is shown in
Figure 94. Selecting Query-> Tables from the menu will show the tables in the
database.
Figure 94. Query tables
Now you can run a query on a table to display its contents. See Figure 95.

Figure 95. Example data that can be retrieved from a host database
7.6 Problem determination

If you encounter problems, you can check the DB2/PCOMM configuration by
looking at the following:
• For PCOMM SNA configuration, check the SNA node configuration; make sure
you check the additional Mode definition, and the CPI-C destination.
• For DB2 Connect Client configuration, connection, and ODBC parameters
check the Client Configuration Assistant (CCA). You can also use the CCA to
test your connections.
7.6.1 DB2 database connection problems

When testing a DB2 database connection, you might come across the following
common problems. Note that error codes can be looked up in the DB2
Information Centre. The troubleshooting tab is good for locating information on
APPC, CPI-C, SQL and other error messages. SNA sense codes can be looked
up in the Display Sense Data utility in the PCOMM Admin & PD Aids folder.
1. SQL30082N Reason "0" SQLSTATE=08001
In this example, we had not established a connection to the host. Through the
SNA Node Operations panel, check that the link is Active.
2. SQL1338N The Symbolic destination name "NAME" was not found
In the example, we had established a link to the host, but the CPI-C
configuration is incorrect. This could be because of a corrupted SNA node
configuration file, or because the CPI-C side information was not configured

properly. Make sure that the CPI-C name in the DB2 Client Configuration
Assistant matches the CPI-C name in the SNA node configuration.
3. SQL30081N Sense Code:10086021 SQLSTATE=8001
This is a CPI-C communications error. Looking up the sense code indicates
that the Transaction program is not recognized. This could be due to DB2 not
being started on the AS/400 or the TP name being wrong. This needs to be
checked on the AS/400.
4. SQL0332N Reason "3" SQLSTATE=57017 - source codepage 1252, Host codepage
65535
This is a problem at the AS/400. The AS/400 has a system-wide character-set
ID called QCCSID, which is initially set to 65535. If a user profile has a CCSID
value of *SYSVAL, it will use the system-wide value (65535) but DB2
Connection attempts will fail with the above error. To resolve this problem, it is
best to change the CCSID value in the user profile (change the QCCSID
(system) value only if you want to change the CCSID value system wide). To
change the user profile CCSID, type CHGUSRPRF on the AS/400, or select
the menu option to change the user profile, then press F10 for additional
parameters. You will then see the coded character-set ID. Change the value
from *SYSVAL to the correct client code page value (for example, 037 for
United States). You should now be able to connect. Please refer to the DB2
publications for more help.
Message queue . . . . . . . . . OVERJ Name, *SAME, *USRPRF

Library . . . . . . . . . . . QUSRSYS Name, *LIBL, *CURLIB
Delivery . . . . . . . . . . . . *NOTIFY *SAME, *NOTIFY, *BREAK...
Severity code filter . . . . . . 0 0-99, *SAME
Print device . . . . . . . . . . *WRKSTN Name, *SAME, *WRKSTN, *SYSVAL
Output queue . . . . . . . . . . *WRKSTN Name, *SAME, *WRKSTN, *DEV
Library . . . . . . . . . . . Name, *LIBL, *CURLIB
Attention program . . . . . . . *SYSVAL Name, *SAME, *NONE...
Sort sequence . . . . . . . . . *SYSVAL Name, *SAME, *SYSVAL, *HEX...
Language ID . . . . . . . . . . *SYSVAL *SAME, *SYSVAL...
Country ID . . . . . . . . . . . *SYSVAL *SAME, *SYSVAL...
Coded character set ID . . . 37 *SAME,*SYSVAL, *HEX.
Character identifier control . . *SYSVAL *SAME, *SYSVAL, *DEVD...
Figure 96. Change User Profile menu
5. ODBC driver changes

A change has been made to the DB2 ODBC driver from the PCOMM 4.2
ODBC drivers; the new DB2 driver requires one of two conditions to be met in
order to modify any existing data on the host.
- The host database to be updated must have journaling turned on.
- The commit level on the client (PC) must be set to NO COMMIT.
See "Isolation Levels" in the DB2 Connect publications.

7.6.2 CPI-C trace for DB2
The DB2 Trace Facility can be used for CPI-C tracing; this is located by clicking
DB2 for Windows -> Problem Determination. Select Start to start the trace,
and Stop -> Save As to save the trace buffer to file. See Figure 97:
Figure 97. DB2 Trace Facility
The trace can be saved as a formatted trace file or as a control-flow trace file.
See Figure 98:
Figure 98. Saving a DB2 trace
7.6.3 ODBC trace for DB2 Connect

To do a DB2 ODBC trace you must add some parameters to the DB2CLI.INI file,
located in the install directory (SQLLIB by default). The DB2 ODBC trace is more
detailed than many ODBC trace facilities.
[COMMON]
TRACE=1
TRACEFLUSH=1
TRACEFILENAME=E:\SQLLIB\TRACES\MYTRACEFILE.CLI
TRACEFLUSH causes each execution to delete the existing trace log and create
a new one. Without this option set, the traces would be appended to each other. If
you wish to save the trace to a directory instead add:
[COMMON]
TRACE=1
TRACEPATHNAME=E:\SQLLIB\TRACES

Note
In either example, if the specified directory does not exist, the trace
logs will not be saved.

Chapter 8. Tivoli support
Personal Communications 4.3 includes Tivoli Management Environment (TME)
Plus module support. This is called the IBMPCOMMPlus module. The Plus
module is added to Tivoli to provide extra management functions for a specific
product, in this case PCOMM. There is a variety of Plus modules available for
Tivoli; Communications Server V6 also has a Tivoli Plus module - refer to Chapter
19 in IBM eNetwork Communications Server for Windows NT V6.0
Enhancements, SG24-5232 for information on this. The PCOMM Plus module
allows an administrator at an enterprise level to manage tasks such as:
• Distribute, install, and uninstall
• Start, stop, and query the server
• List configuration files
This chapter provides an overview of the new features in PCOMM 4.3 to support
the Tivoli environment:
• Plus module - for administering PCOMM
• Command-line programs - for local and Plus-module use
For software distribution (Tivoli Courier - for installing PCOMM), refer to Chapter
1, “Installation” on page 1.
8.1 Overview
Tivoli is IBM’s premier enterprise-management solution. This is the brand-name
of a set of products that provide systems-management capabilities across
multiple platforms. Tivoli includes a structured framework that provides core
services and capabilities for management applications and a growing set of
applications that take advantage of the framework.
Tivoli defines three types of node within a Tivoli Management Region (TMR):
• TMR Tivoli server - one server per TMR. It runs Tivoli Framework and other
Tivoli products.
TMR servers maintain the TMR server database and coordinate all
communications with TME 10 managed nodes.
• Managed node - up to 200 nodes per TMR. It runs Tivoli Framework.
It runs the same software on a TMR server (installed remotely from the
server). Managed nodes maintain their own databases, which can be
accessed by the TMR server. PCOMM and the PCOMMPlus module can be
installed on a managed node.
• PC managed node, which runs Tivoli Agent.
Tivoli Framework provides the Tivoli management services used by the Tivoli
applications. Tivoli supports Plus modules. These modules can be written to
integrate application specific management requirements with the Tivoli
Framework, thus providing application management capabilities using the Tivoli
interface and services. All Plus modules have a similar installation and user
interface because they are integrated into Tivoli. This means that Tivoli

administrators are already familiar with the types of interaction available from the
Plus modules, making them easy to use.
PCOMM itself is not Tivoli ready, but it does support various Plus-module
functions, such as application launching, administration tasks, subscriptions lists
and software distribution.
8.2 Installing the IBMPCOMMPlus module on a Tivoli TMR Server

To install and use the IBMPCOMMPlus module, a Tivoli configuration must be set
up. This should consist of one Tivoli TMR Server, and one or more managed
nodes. A Region should be created, containing the PCOMM PC managed nodes.
Figure 99 shows an example of two-node PCOMM policy PC managed nodes
available for use with the Plus module:
Figure 99. PCOMM region of managed nodes
To create a managed node, the Tivoli Remote Execution Service (TRIP) must be
installed on the managed node first. The managed node is then created from the
TMR Server Region. Please refer to the Tivoli TME10 Framework planning and
installation manual for detailed information on creating managed nodes and
installing/configuring your Tivoli environment.
The IBMPCOMMPlus module for Tivoli is shipped with PCOMM 4.3, on the
CD-ROM. Figure 100 shows where the Plus module is located.

Figure 100. PCOMMPlus module location on CD-ROM
Note that the files are in the format of a Tivoli Installable image. To install the
IBMPCOMMPlus module, do as follows:
1. Make sure that the IBMPCOMM.IMAGE directory is accessible to the Tivoli
Server; you can install directly from the CD-ROM or from a server drive.
2. Select Desktop->Install->Install Product... from the Tivoli desktop.
Figure 101. Installing the PCOMMPLus module on a Tivoli TMR server
Tivoli support 105

3. Set the source location for the IBMPCOMMPlus module’s install image. In this
example the CD-ROM image has been copied to a directory on the Tivoli
server. Next, click Set Media & Close to close the File Browser dialog box.
Figure 102. Setting path to IBMPCOMMPlus module for installation

4. The IBMPCOMMPlus module should now be displayed for installation.
Figure 103. Installation selection
5. Click IBMPCOMMPlus for Tivoli in the Select Product to Install list. Make
sure that the Clients to Install On window contains the target node (TMR
server or managed node). Then click Install & Close to start the installation.
You will see a panel that contains messages, which vary according to whether
you already have the Plus module installed and according to how the installation
goes.
When installation of the IBMPCOMMPlus module has finished, and all of the
install dialog boxes have been closed, an icon is added to the Tivoli Plus panel.
Tivoli support 107

Figure 104. IBMPCOMMPlus for Tivoli container
8.3 Functions and tasks

The IBMPCOMMPlus for Tivoli panel consists of icons, split into two categories:
functions and tasks. Functions are performed locally on the Tivoli Server, while
tasks are used for remote management. There are three functions and seven
administrative tasks. Figure 105 shows the Plus module functions and tasks:
Figure 105. IBMPCOMMPlus Tasks panel
8.3.1 Using IBM PCOMMPlus functions

The PCOMMPlus module has three objects for performing functions. Note that
these are not Tivoli Administrative Tasks.

8.3.1.1 PCOMM SNA Node Operations
This is merely a shortcut to PCOMM SNA Node Operations on the Tivoli TMR
Server. This is not a remote operation but is available if PCOMM is installed on
the Tivoli TMR Server.
Note
Make sure that all PCOMM nodes that require management by the Plus module
are registered with the Subscription List function.
8.3.1.2 PCOMM subscription list

This is the administrator-defined list of PCOMM nodes. Before any PCOMM task
can be used, it is important to make sure that you subscribe the PCOMM nodes
you wish to manage with the PCOMMPlus module. This is where the PCOMM
subscription list is used. Figure 106 shows the PCOMM Subscribers panel:
Figure 106. PCOMM subscription list
The list on the right shows the available subscribers. From this list you can select
the PCOMM nodes you want to manage with the PCOMMPlus module, and add
them to the list on the left. The PCOMM nodes in the Available list come from the
policy region. Clicking Set Subscriptions & Close will then set your
subscriptions.
8.3.1.3 About IBMPCOMMPlus

This function displays information about the PCOMM Plus module installed on the
Tivoli Server.
Tivoli support 109

Figure 107. About IBM PCOMMPlus for Tivoli
8.3.2 IBMPCOMMPlus task and job overview

Tivoli Tasks are short-running programs that perform a specific function on one or
more PCOMM nodes. Tasks are associated with an executable file. A Tivoli task
definition includes a list of PCOMM nodes or other run-time information. In order
to automate a task, you must create a job, which is associated to a task but
contains predefined information (what target PCOMM nodes to operate on).
Although a job is predefined, the user is still given the option to modify the list of
PCOMM nodes before the job is executed. Figure 108 shows the Task Library
panel. To create a job, select Create -> Job.
Figure 108. Creating a job
Figure 109 shows the next panel that you will see. This panel allows you to
specify the properties of the job you wish to create, including a list of PCOMM
nodes on which to run this job.

Figure 109. Creating a job (2)
Tasks targeting one or more of the same nodes must be run separately, otherwise
the result can be unpredictable. This is a known, but not well documented Tivoli
restriction.
Figure 110 shows how Tivoli sends tasks to the PCOMM SNA Node (Tivoli
Agent). A PCOMM command-line program, cs*.exe, is used for each of the tasks.
Tivoli support 111

Figure 110. Interaction of Tivoli server and Tivoli agent on PCOMM node
8.3.3 Using IBM PCOMMPlus tasks

There are seven administrative tasks available for use. This section gives an
introduction to each task and how to use it. When executing a task, you will be
prompted for the subscribed PCOMM nodes you want to execute the task on; by
default, the tasks use the nodes in the subscription list.
Figure 111 shows the Execute Task panel. You must select your subscribed
PCOMM nodes in the Execution Targets section. One of the Output Destinations
must be selected; Display on Desktop displays the output on your screen.

Figure 111. Executing a task
8.3.3.1 Issue command

Double-click Issue command from the panel shown in Figure 105 on page 108.
Use this task to issue any DOS command. You should not use the PCOMM
commands (see 8.4.1, “Syntax of PCOMM command-line programs” on page
119) manually with this task. Note the use of the PCOMM_ROOT environment
variable in the DIR command. When PCOMM is installed on a node this
environment variable is set as a System Environment Variable. IBM PCOMMPlus
uses this to identify where PCOMM is installed on each node. Figure 112 shows
the Issue command dialog box. The command entered would get a directory
output of the \Personal Communications\*.exe directory on the PCOMM node.
The output is shown in Figure 113 on page 114.
Figure 112. Issue command dialog box
Tivoli support 113

Figure 113 on page 114 shows the output from the command we issued in Figure
112. Notice that the output looks ragged because Tivoli uses a proportional font.
There is also a Save to File button at the bottom of these output panels that
allows you to save the output to a file.
Figure 113. Example output from dir command
8.3.3.2 List configuration files

This task issues a DIR command on the \PRIVATE directory for the SNA Node
files only (*.ACG), and displays the returned information; see Figure 114 for the
output. You will notice that this is similar to doing the DIR command as we did in
Figure 112 on page 113.
Figure 114. Output from list configuration files

8.3.3.3 Query SNA node status
This task uses the PCOMM command-line program CSQUERY.EXE, on the
PCOMM target nodes, and displays the output. See Figure 115 for the output.
Figure 115. Output from query SNA node status
8.3.4 Start SNA node

This task uses the PCOMM command-line program CSSTART.EXE on the
PCOMM target nodes to start the specified SNA node configuration file, and
displays the output; see Figure 116 for the options panel.
Figure 116. Start SNA node options
The options in the panel are as follows:

• Start configuration
Starts a specified configuration file or, if no name is specified, starts the SNA
node with the default configuration file.
• Set Start at boot time
This sets the SNA node to be started automatically, with the default or
specified configuration file, whenever the system is booted.
• Reset Start at boot time
Tivoli support 115

This resets the automatic service back to a manual service so that the node
will no longer be automatically started at bootup. A reboot is needed to enable
this.
• Set default configuration
Sets the specified configuration file to be the default configuration file. If no file
name is specified, the default configuration file will be used.
Figure 117. Output from the Start SNA node task
8.3.4.1 Stop SNA node

This task uses the PCOMM command-line program CSSTOP.EXE on the
PCOMM target nodes to stop the SNA node, and displays the output. Figure 118
shows the confirmation dialog box.
Figure 118. Stop SNA node
Figure 119. Output from stop SNA node

8.3.5 Display SNA node resource
This task uses the PCOMM command-line program CSDSPY.EXE on the
PCOMM target nodes, and returns the information. Figure 120 shows the dialog
box.
Figure 120. Display SNA node resource
Enter the type of resource you want to display; you can enter the optional (case
sensitive) Resource id and select the Output detail level. Refer to 8.4.1.4,
“CSDSPY.EXE” on page 121 for more information. If you leave the Resource id
blank, information on all resources of the type selected is displayed. Figure 121
shows the output.
Figure 121. Output from display SNA node resource
8.3.6 Modify SNA node resource

This task uses the PCOMM command-line program CSMODIFY.EXE on the
PCOMM target nodes, and displays the returned information. Figure 122 on page
118 shows the dialog.
Tivoli support 117

Figure 122. Modify SNA node resource
Enter the type of Resource you want to change, followed by the Resource id
(case sensitive), then select the action to be performed. Refer to 8.4.1.5,
“CSMODIFY.EXE” on page 123 for more information. See Figure 123 for the
output.
Figure 123. Output from Modify SNA node resource
8.4 PCOMM command-line programs used by Tivoli

The PCOMMPlus module tasks are listed below. Notice the five tasks that use
PCOMM command-line programs:
• Issue command
Issue any DOS command.
• List configuration files
Lists all PCOMM *.acg files.
• Query SNA node status
Uses CSQUERY.EXE 1.
• Start SNA node
Uses CSSTART.EXE 1 .
• Stop SNA node
Uses CSSTOP.EXE 1 .
1
Updated from PCOMM V4.2 to V4.3; interfaces to the SNA stack.

• Display SNA node resource
Uses CSDSPY.EX 2.
• Modify SNA node resource
Uses CSMODIFY.EXE2 .
Also new for PCOMM 4.3 is the NOPAPI.DLL. This is the SNA Node Operations
API for the CSDSPY.EXE and CSMODIFY.EXE commands. For more information,
see 8.4.1.6, “NOPAPI.DLL” on page 124.
8.4.1 Syntax of PCOMM command-line programs

Here is a list of the PCOMM command-line programs, with their syntax. The
PCOMM Tivoli Tasks use these programs, which can also be used individually on
the PCOMM client.
8.4.1.1 CSSTART.EXE
2
New for PCOMM 4.3; interfaces to SNA Node Operations API.
Tivoli support 119

8.4.1.2 CSSTOP.EXE
Function:
Stops the SNA node
Syntax:
csstop [-h] | [-p | -q]1
-h display help
-p display messages in a popup message box
-q quiet mode, no messages are displayed
_________________
1. Specifying no switches, or the -p or -q switch, stops the SNA node.
8.4.1.3 CSQUERY.EXE
Function:
Displays the status of the SNA node - whether it is stopped or
running. Also displays the default and active (if applicable)
config-file specifications.
Syntax:
csquery [-h] | [-p | -q]1
-h display help
-p display messages in a popup message box
-q quiet mode, no messages are displayed
_________________
1. Specifying no switches, or the -p or -q switch, queries the SNA node .

8.4.1.4 CSDSPY.EXE
Function:
Displays information about SNA node resources
Syntax:
csdspy [-h] | [ resource [resource_id] [-d#] ]
-h display help
resource resource type1
resource_id resource identifier2
-d# level of detail: # = 1 (min), 2 (normal), 3 (max)
_________________
1. The mandatory resource type specifies a 3-character abbreviation.
2. The optional resource identifier specifies a specific resource.
Tivoli support 121

resource
One of the following 3-character abbreviation codes:
code resource type code resource type

AIL AnyNet IP to LU Mapping FPT Focal Points
ASC AnyNet Sockets Connections LU0 Local LU 0 to 3
ASD AnyNet Sockets Devices L62 Local LU 6.2
ASR AnyNet Sockets Routes L6S LU 6.2 Sessions
CNT Connection networks MOD Modes
CON Connections NOD Node
CPS CPI-C Side Information PLU Partner LU 6.2
DLC Data Link Controls RTP RTP Connections
DEV Devices TRP Transaction programs
DPU DLUR PUs
resource_id1
An optional resource-specific identifier:
A case-sensitive attribute value (for example, LU001 or LINK0001)
that identifies the resource to be displayed--i.e., this is the first
attribute value that CSDSPY displays for the resource.
-d#
The level of output detail. # is a number: 1, 2, or 3, where:
1 is the lowest level, the first attribute of each resource is displayed
2 is an intermediate level of detail (the default)
3 shows all information about the resources
_________________
1. The resource id, if used, must be spelled correctly, including case. An incorrect
resource id will result in nothing being displayed.

8.4.1.5 CSMODIFY.EXE
Function:
Modifies the state of an SNA resource
Syntax:
csmodify [-h] | [ resource resource_id action ]
-h display help
resource resource type1
resource_id resource identifier2
action action to perform on the resource3
_________________
1. The mandatory resource type specifies a 3-character abbreviation.
2. The mandatory resource identifier specifies a specific resource.
3. The mandatory action specifies a 2-character abbreviation.
resource
code resource type actions allowed
CON Connections SN, SI, ST, DL
CPS CPI-C Side Information DL
DLC Data Link Controls SN, SI, ST, DL
DEV Devices SN, SI, ST, DL
DPU DLUR PUs SN, SI, ST
LU0 Local LU 0 to 3 DL (only if the LU is not in use)
L62 Local LU 6.2 DL
RTP RTP Connections PS
Tivoli support 123

resource_id1
A mandatory resource-specific identifier:
A case-sensitive attribute value (for example, LU001 or LINK0001)
that identifies the resource to be modified--i.e., this is the first
attribute value that CSDSPY displays for the resource.
action
code action
SN Stop Normal
SI Stop Immediate
ST Start
DL Delete
PS Path Switch
_________________
1. The resource id must be spelled correctly including case. An incorrect resource id will
result in an error being displayed.
8.4.1.6 NOPAPI.DLL
Function:
Provides an API to the SNA Node Operations component for
the CSDSPY.EXE and CSMODIFY.EXE programs.
Supports the same set of SNA node resources as the SNA
Node Operations program, PCSNOPS.EXE.1
_________________
1. CSDSPY.EXE supports the same set of resourses as PCSNOPS.EXE. However,
CSMODIFY.EXE supports only a subset of the resources -- e.g., CSMODIFY.EXE
supports connections, but not LU 6.2 sessions.

Chapter 9. Java development with Personal Communications
A lot of work has been done developing applications on the host. Over the years,
millions of lines of code have been written, resulting in a huge collection of
reliable, powerful programs which run an important part of today’s business
worldwide.
Many of these applications are accessible from 3270 or 5250 clients like Personal
Communications, Host On-Demand and others. Much work has been spent to
enable these clients to send data from/to the host as well as performing very
sophisticated tasks on the workstation side with and without user interaction.
But the world has changed dramatically over the last 5-10 years. New design
paradigms have been introduced, from both the development and the user
interface point of view. New computer architectures and concepts become more
and more important for this new world.
New applications can follow the client/server or network-computing concepts

brought to us by the advocates of object-oriented and distributed programming,
componentware, new graphical user interfaces, internet applications, and others.
But what about legacy applications? Must we re-develop host applications in only
a few years, or die? Or can we move these applications step by step?
Actually, there are several ways to move legacy applications, addressing several
development needs.
1. First of all, you can isolate the business logic on the host side and implement
new code around this logic. Probably the most consistent way needs the
highest effort, applicable only for a few very special situations where
re-developing from scratch is more costly.
2. Second, you can analyze the programs running on the host. For instance, you
may find that the program runs under the control of CICS. Installing the CICS
Universal Client or any similar product allows you to write new non-CICS
applications that gain access to CICS facilities and data using the ECI and EPI
programming interfaces. The new applications must not only run on the host
but on any other operating system where a CICS client is available.
In a similar way, extending CICS, you can manage other host resources like
databases (DB2, IMS, etc.), message queuing (MQSeries), and others from
any client you like. Visit the appropriate websites for the newest information:
http://www.software.ibm.com/ts/
http://www.software.ibm.com/mqseries/
http://www.software.ibm.com/ts/cics/
http://www.hursley.ibm.com/cwuf/
http://www.software.ibm.com/data/
http://www.software.ibm.com/data/db2/
http://www.software.ibm.com/data/ims/
http://www.software.ibm.com/network/
http://www.s390.ibm.com/java/
http://www.as400.ibm.com/java/javahome.htm
3. Third, you can improve the transfer of a non-specific data stream between the
host and the client using APIs like APPC, CPI-C, jCPIC or SRPI. This works
well with both existing and new host applications, but requires that both sides

of the application (client and server) be written and therefore needs some
changes within the host application.
4. Last, but not least, you can use the Host Access Class Library (HACL)
available for both C++ and Java. This class library presents a complete
object-oriented abstraction of a host session that includes: reading and writing
the host presentation space (screen), enumerating the fields on the screen,
reading the Operator Information Area (OIA) for status information,
transferring files, and performing asynchronous notification of significant
events. In fact, this is the easiest and fastest way to transform host
applications into Web-ready applications. It gives developers the chance to
embed the host screen seamlessly into a Web page using Java, or to hide the
host screen completely and only process the data provided with the session.
Moreover, it needs no changes on the host side and can be used with any
3270 or 5250 application.
In addition to HACL and gaining from its features, Personal Communications
provides other new and powerful programming capabilities:
• VBScript - in addition to macros, normal users can simply create and
modify their own scripts, based on Microsoft’s Visual Basic Script
specification. The VBScript recorder provided is probably the easiest way
to automate daily work.
• Host Access Beans for Java support - these beans simplify the
development of GUI and non-GUI applications in a visual development
environment.
• ActiveX support - this allows easy access from Visual Basic and other tools
to PCOMM (includes both ActiveX OLE Automation objects and ActiveX
Host Access controls); see 9.4, “ActiveX controls vs. ActiveX OLE
automation objects” on page 150 for an introduction.
9.1 Using the Host Access Class Library for Java (HACL)
Some people may ask "What’s going on in this crazy world - is Java really the
coolest stuff, or only marketing hype?" But whatever Java is supposed to be, we
cannot ignore the momentum. Java is on the way to becoming a very effective
development and execution environment. It’s more than just a new programming
language - even today, Java supports the integration of virtually any enterprise
resource, any user interface, and any computer architecture better than all other
programming languages.
First shipped with Host On-Demand, the Java support has been added to
Personal Communications V4.3. It is based on a very powerful API called Host
Access Class Library for Java, and its companion Host Access Beans for Java.
The Host Access Class Library (HACL) is an object-oriented library for accessing
host data, typically used to automate user interaction with a terminal emulator. It
essentially gives the programmer complete read and write access to the emulator
sessions. Host Access Beans based on HACL are visual components that can be
manipulated inside a Visual Development Environment to visually construct host
access programs.
Personal Communications is not the only product which provides Host Access
Class Library support; other products are:
• IBM Communications Server for Windows NT

• IBM Host On-Demand
• Tivoli NetView Java 3270 Client
Read This!
Although the HACL versions provided with Host
On-Demand and Personal Communications 4.3 are
assumed to be 100% portable, there are some small
differences.
The HACL version provided by Host On-Demand is a

pure Java implementation which only supports TCP/IP
connections. The HACL version provided by PCOMM
maps internally to native interfaces, which gives you
more variety in the networking protocols supported. The
Implementations are described in the HACL Reference
documents shipped with each product.
9.1.1 When should I use HACL and Host Access Beans?

Probably the most common scenario is writing Java programs that gain from
CICS functionality on the host. This needs a product called CICS Transaction
Gateway installed somewhere in your network including the host1, and adds Java
and internet related functions to the CICS Universal Client (see page 125). HACL
or Host Access Bean-based programs can connect directly to the gateway, and
be mixed with additional Java support provided by the CICS Transaction Gateway.
No changes on the host are needed.
A second common scenario is demonstrated in Figure 124. It compares two ways

of accessing host data and applications.
One way is a client/server solution which allows direct access to the host
database from your Java program. The only requirement is a local database
client, or a database gateway running a JDBC daemon somewhere in your
network. In other words, just install DB2 Connect V5.2 for Personal
Communications. This will make it easy to access DB2 on the mainframe, the
AS/400 2, or any other platform via JDBC 3.
JDBC is the standard way to access relational databases in Java; DB2 Connect
provides two JDBC drivers, one for local and one for remote access. Originally,
JDBC was only specified for dynamic database access using X/Open’s Call Level
Interface (CLI) specification. The DB2 JDBC driver also implements a technology
called SQLJ specified by Oracle which allows programming Static SQL for faster
database access.
JDBC sounds good for new applications, but it only keeps the data and not the
application code. If you don’t want to touch millions of legacy applications but only
1
Some major improvements have been introduced in the new CICS Transaction Server V1.3 for OS/390. Visit the appropriate Web sites
for more information.
2 Another way to access AS/400 databases directly without using DB2 Connect is a JDBC driver provided by the AS/400 Toolbox for
Java. Visit http://www.as400.ibm.com/toolbox/javatool.htm, or see Chapter 12 "Database On-Demand" in IBM

SecureWay Host On-Demand: Enterprise Communications in the Era of Network Computing, SG24-2149 for more information.
3 JDBC is the standard way to access relational databases in Java but does not support non-relational databases. IMS users can install
the IBM IMS client for Java to access applications and data, and the IBM IMS TOC Connector for Java for transaction support.
Java development with Personal Communications 127

want to improve their interface and bring them into the new world of the Internet
and Java, there are some better approaches, such as HACL and Host Access
Beans.
Figure 124. Host access through JDBC and HACL
Figure 124 demonstrates access to host data in two ways: 1) Direct access via
JDBC to the database in a client/server environment. 2) Access via Host Access
Class Library using a terminal emulator in a traditional host environment. It
demonstrates both local and remote access (*needs only one of the telnet
servers TN3270, TN3270E, TN5250, VT340, VT100, VT52, etc.).
The low-level approach using HACL as shown in Figure 124 provides the basics
for any other development. From the coding point of view, this approach is
probably the most powerful and fastest, and allows unrestricted access to all
features provided by the underlying library with little code overhead.
On the other hand, the high-level approach eases developing applications and
applets that work well in visual development environments like Sun's Bean
Development Kit (BeanBox), IBM’s VisualAge for Java, SunSoft's Java Studio,
Lotus Development's BeanMachine, Symantec's Visual Cafe, Inprise's JBuilder,
and others. For more information, visit the Host Access Beans Hints and Tips
Web page:
http://www.software.ibm.com/network/hostondemand/library/publications/beans.ht
ml

Host Access Beans and Data Access Beans4 support developers who still think in
more "traditional" ways. If you are new to host or database programming, or have
to develop smaller programs, you should first review if the functions they provide
meet your needs. Host Access Beans are also an excellent choice to quickly
transform existing legacy applications into fully-functional Web applications.
The restriction on going this way is that any improvement will require you to code
all of the infrastructure by hand; that is, you will not be able to benefit from other
developer’s work. People who are familiar with object-oriented concepts, or
working on large projects, may find Enterprise Java Beans, or vendor-specific
Frameworks more useful. But because this approach is considerably more
abstract, the learning curve is much higher, and you must spend much more time
really understanding the concepts behind object orientation. The advantage,
however, is that you don’t have to deal with low-level APIs or infrastructure
designs, so you can save a lot of time in large projects, especially if you already
know the basics.
Ideally, you would only need to deal with business objects. The mapping of the
persistent state of your business objects to databases, as well as the transaction
handling, the management of multiple users accessing the same data
concurrently, and a lot of other tasks are done automatically. Moreover this
addresses problems like resource management if you cannot keep all objects in
memory at the same time, as well as remote management and error detection.
You can run your code within application servers like IBM WebSphere Advanced
or Enterprise edition, manage it with system management tools like Tivoli, and
easily integrate it into your corporate network.
At this time, IBM provides no direct support for running HACL-based applications
inside an Enterprise Java Bean environment, but because the concept is
well-documented, it should be easy to bring HACL and Enterprise Java Beans
together.
9.2 Setting up the Java environment

In Personal Communications, the Java HACL classes can be found in the
pcseclj.jar archive located in the root directory where Personal Communications
is installed. Add this file to your Java classpath, in order for the Java Compiler
( javac) and Java Runtime Environment ( java) to find the Java HACL classes
contained in this archive. When you use a development tool you should consult
your tool's documentation for help in importing the pcseclj.jar archive.
To add the pcseclj.jar archive to the classpath environment variable:

• On Windows 95/98:
Modify your autoexec.bat to add a "SET CLASSPATH=<pathname of
pcseclj.jar>;" statement or modify an existing "SET CLASSPATH" statement to
include the archive.
• On Windows NT:
Open your System Properties, select the Environment tab and add a
CLASSPATH environment variable with a value of <pathname of pcseclj.jar>;
4 Actually, Data Access Beans are features of VisualAge for Java V2, both Professional and Enterprise edition. Similar functionality can
be found in almost all other development tools which address enterprise needs. Ask your tool vendor for details.

or modify an existing CLASSPATH environment variable value to include the
archive.
Read This!
Host On-Demand and Personal Communications 4.3
provide the same set of classes. If you are installing
these products on the same system, caution should be
used when modifying the global CLASSPATH
environment to make sure your applications are using
the correct product's Java classes.
If you have installed both products and experience

problems running either Host On-Demand or your Java
HACL or Host Access Beans programs, check the
CLASSPATH environment variable to see if you are
picking up the correct Java archive.
Compiling Java code needs the Java compiler javac, and executing requires the
runtime environment java (sometimes referred to as JRE). To invoke them call:
• For .java files (compile):
javac -verbose <package name> \<Java file name> .java
• For .class files (execute):
java -verbose package name>.<class file name>
<package name> is a string you specified as package name in your Java code.
Using packages is optional but must be in sync with the directory structure on
your disk. For example, when the specified package name is mypackage the Java
environment is looking for the classes included in the subdirectory mypackage\
starting from the current directory. You can specify an assembled package name,
but this means that classes in the package mypackage.next must be included in
the mypackage\next\ subdirectory. You may use Java archives (.jar or .zip) to hide
the directory structure.
<file name> is the file name of your Java file (with extension .java), or class file
(with the extension .class). Be aware that Java is case sensitive, and normally the
name of a class must be exactly the same as its file name.
Troubleshooting:
• Don’t touch file names, or move files to another subdirectory inside the Java
file tree! Move the whole directory if needed.
• Expect problems with file systems that do not support long file names, for
example, diskettes. Be careful when using them to save files temporarily.
• Use the -verbose option extensively when the system can’t find a class or
something it requires.
• Start both compiler and runtime environment from the root directory of the
Java file tree (or where the Java archive is located), unless you use special
command line options (-d or -classpath).

• You can pass the classpath as command line parameter using the -classpath
option. That’s useful when modifying the system’s classpath is not possible. In
this case, javac and java ignore the system’s classpath completely, you must
add all Java libraries needed.
• Java files normally depend on each other. When you experience problems
compiling files you may have to change the compile order for these files.
• When a program doesn’t behave as expected, try to disable the just-in-time
compiler. See the program options to learn how.
• Java archives (.zip and .jar files) have a very similar structure to regular zip
files. When you need information about the structure of a Java archive one
way to do so is by unpacking with a common unzip program.
9.3 Host Access Class Library objects

The following extract of the HACL online documentation is a brief overview of the
Host Access Class Library classes:
• ECLConnection represents the connection information for a session with a
particular host and contains information such as the connection status, the
type of connection (for example, 3270 or 5250), and the name of the session.
• ECLCommNotify is the notification interface that must be implemented to be
notified whenever a connection is disconnected from or connected to a host. It
can be used to monitor the status of a connection, for example, to take action
when a connection is disconnected unexpectedly.
• ECLErr provides a method for returning runtime error information from Host
Access Class Library classes. ECLErr is thrown by HACL objects when a
problem is encountered. ECLErr contains the runtime error information and
also provides methods that applications can use for problem determination so
that the appropriate action can be taken.
• ECLField contains information about a single field on the screen, such as the
field attributes, field color, position on the screen or length. A method is also
supplied to update input fields.
• ECLFieldList contains a collection of ECLField objects. When the Refresh
method is called, the current host screen is examined, and the list of fields is
extracted and used to build the list of ECLField objects. An application can use
this collection to manage fields without having to build the list itself.
• ECLOIA provides access to operator status information such as shift
indicators, input inhibited conditions and communications errors.
• ECLOIANotify is the notification interface that must be implemented to be
notified whenever the OIA is updated.
• ECLPS represents the presentation space (screen) of a single connection. It
contains methods for obtaining a copy of the screen contents in the form of
data planes. Each plane represents a specific aspect of the presentation
space, such as the text, field attributes and color attributes. Methods are
provided for searching for strings in the presentation space, sending
keystrokes to the host, getting and setting the host cursor position, and many
other functions. Also provided is an ECLFieldList object that can be used to
enumerate the list of fields on the screen.

• ECLPSEvent encapsulates a PS event and includes information about
New
which area of the presentation space has changed.
• ECLPSListener is the listener interface that must be implemented to
New
receive ECLPSEvents.
• ECLPSNotify is the notification interface that must be implemented to Depre-
be notified whenever the host presentation space is updated. cated
• ECLPSUpdate contains information about the changed or dirty area of

New
the presentation space based on a given ECLPSEvent.
• ECLRecoNotify is the notification interface that must be implemented
New
to be notified whenever screens are recognized.
• ECLScreenDesc contains the data which describes a particular
New
screen. This class can be used to perform advanced screen
recognition.
• ECLScreenReco contains the methods for adding and removing
New
screen descriptions and provides asynchronous notification when
screens are recognized.
• ECLSession contains a collection of all the connection-specific objects.
ECLSession can be used to easily create a complete set of objects for a
particular connection. ECLSession inherits from ECLConnection, and it is the
only access point for the methods in ECLConnection.
• ECLXfer initiates file transfers to or from the host over the connection.
• ECLXferEvent provides file transfer progress information.
New
• ECLXferListener is the listener interface which must be implemented

New
to receive ECLXferEvents.
For more information review the online reference that comes with the product. A
step-by-step tutorial shows what’s necessary to write and compile a Java HACL
application. Be aware that although the library interface is 100% portable
between Host On-Demand and Personal Communications there are minor
differences.
The documentation resides in the Personal Communications\doc\hacl\ directory,

and can also be found on:
http://www.software.ibm.com/network/pcomm/library/publications/pcomm_43/enu/Ha
cl/ECLReference.html
Additional code samples, suggestions and answers to frequently asked questions

can be found at this site:
http://www.software.ibm.com/network/technology/hacl/.
Other excellent sources of Java-related topics from IBM are:

http://www.ibm.com/java/
http://www.alphaworks.ibm.com/
http://www.software.ibm.com/vadd/
http://www.software.ibm.com/ad/vajava/
News groups and discussion forums can be found on:

http://ncc.hursley.ibm.com/javainfo/interact/newspage.html

http://pokstr01.pok.ibm.com/ (IBM internal)
http://tr2.fishkill.ibm.com (IBM internal)
Tip
We recommend the excellent introduction to the Host
Access Class Library for Java and the Host Access
Beans for Java in Chapters 10 and 11 of IBM SecureWay
Host On-Demand: Enterprise Communications in the Era
of Network Computing, SG24-2149-00.
Especially when you are familiar with other APIs like

EHLLAPI, you will find the appropriate information to see
what has changed, and which situations you should be
careful about.
9.3.1 Connecting to the host

Establishing a host connection requires you to set up an ECLSession object.
Within the ECLSession object, a complete set of connection-specific objects will
be created and initialized for a particular connection (see Figure 125 on page
135).
This can be done in several steps, though you can usually let most properties
default:
1. Define the behavior and characteristics of the session by passing an instance
of Properties to the constructor of ECLSession. The Properties object must
contain all configuration information. Configuration information includes the
host, port, session name, presentation space size (for example, 24 rows by 80
columns), some SSL features, and the host code page. Properties may
depend on the session type chosen. You can run several sessions at the same
time connecting the same or different hosts, and using the same or different
session types.
HACL architecture is not limited to 26 sessions; it uses the concept of a
session name which is simply a string that identifies a session. But because
the HACL implementation provided by Personal Communications maps
internally to this product, in fact, this restriction is only obsolete for the HACL
implementation provided by Host On-Demand.
At least the following properties must be specified:
• SESSION_TYPE - Type of session to establish unless you use the default.
The following session types are valid: 3270 (default), 5250, VT, CICS, 3270
Printer.
• SESSION_HOST - In Host On-Demand, specify the TCP/IP name or
address of a host to which the session will be established. For CICS
sessions, it should be the host name or address of the CICS Transaction
Gateway.
In Personal Communications, specify the name of the workstation profile
(.WS file) which contains the Session configuration information. You may
include or not include the .ws profile extension when setting the Host
property.

• SESSION_APPLET - Instance of java.applet.Applet when the session is
created within the context of a browser. The Applet parameter is needed to
load messages and display help text.
Other properties are useful for debugging:
• SESSION_TRACE - Activates the Log/Trace facility and starts tracing for
the specified components. This window allows you to select numerous
trace options to help in problem determination. A trace level from 1 to 3 can
also be specified for each separate component using the following syntax:
"ECLSession=x", where x is the trace level.
• SESSION_PS_DEBUGGER - Activates the Presentation Space Debugger
facility which can display all of the planes associated with the presentation
space while the HACL session is active. The value itself can be any string
and is ignored.
You can hard code the properties in the program (see Figure 125, step 1a), or
load them from a property file with any name (see Figure 125, 1b). Every
property in this file occupies one line of the input stream. A line that contains
only whitespace or whose first non-whitespace character is an ASCII # or ! is
ignored.
See the following sample content:
SESSION_HOST = localhost
SESSION_PS_DEBUGGER = ON
SESSION_TRACE = SESSION_TRACE_PS
2. Set up a new instance of ECLSession. This creates and initializes a virtual
emulation session with a host. Whenever something goes wrong an ECLErr
exception will be thrown.
3. Start the communication, execute your user-defined code, and stop
communication. You should free resources associated with the session when
no longer needed.

import com.ibm.eNetwork.ECL.*;
import java.util.Properties;
import java.io.FileInputStream;
public class SimpleSample {
static public void main (String [] argv) {
Properties configData = new Properties(); // Properties to startup ECL session

ECLSession myECLSession = null; // Virtual emulation session
// Step 1a: Initialize all session startup parameters
// Need to specify at least session host

configData.put(ECLSession.SESSION_HOST, "localhost");
// Useful options for debugging, uncomment in production environment

configData.put(ECLSession.SESSION_PS_DEBUGGER, "ON");
configData.put(ECLSession.SESSION_TRACE, ECLSession.SESSION_TRACE_PS);
// Step 1b: Alternatively, set up new properties object from file

// try {
// configData.load(new FileInputStream("localhost.properties"));
// } catch(Exception e) {
// System.out.println("Read properties file: " + e.getMessage());
// }
try {
// Step 2: Create, initialize virtual emulation session with a host
myECLSession = new ECLSession(configData);
// Step 3: Start the LU, execute userdefined code, stop communication

myECLSession.StartCommunication(); // Start SNA communication
...
...
(your code)
...
...
myECLSession.StopCommunication(); // Stop SNA communication
myECLSession.dispose(); // Free resources associated with the session
} catch (ECLErr e) {
System.out.println("Session error: " + e.getMessage());
}
}
}
Figure 125. Sample code to start SNA communication, using an ECLSession object
An ECLSession object has no associated graphical user interface (GUI). In other

words, creating an instance of ECLSession does not cause an emulation screen
to display.
ECLSession inherits from ECLConnection , and it is the only access point for the
methods in ECLConnection. ECLConnection represents the connection
information for a session with a particular host and contains information such as
the connection status, the type of connection (for example, 3270 or 5250), and
the name of the session. More useful methods can be found by reviewing the
product information for the ECLConnection class, too.
Once an ECLSession object has been constructed, you can get instances of
ECLPS (presentation space), ECLOIA (operator information area), and ECLXfer
(file transfer) from the ECLSession instance.

Read This!
Be aware that you must specify the TCP/IP name or
address of a host to which the session will be established
(Host On-Demand), or the name of the workstation profile
(.WS file without extension) which contains the Session
configuration information (Personal Communications).
9.3.2 Debugging a HACL applet within Personal Communications

Not only can you test your program running as an applet or application, and use
the SESSION_TRACE and the SESSION_PS_DEBUGGER properties described
on page 134, but you can also run it from within Personal Communications as
shown as in Figure 126.
Figure 126. Running an applet
Choosing Run Java Applet... from the Assist menu of the session window shown
in Figure 126 brings up a dialog-box which lets you specify the name of an applet
class file (with or without extension). This class file must be located in the private
subdirectory of your Personal Communications installation directory.
At this time, it’s just a feature of Personal Communications. No Java console or

other sophisticated functionality are provided. Any output or error messages must
be logged in a log file. Once called, the applet class will be passed to the Java
Runtime Environment in the directory Personal Communications\jre\ together with
predefined classpath settings. This restricts the use of additional Java archives or
directories.
All necessary classes must be located in the Personal Communications\private\

directory. An applet can consist of one or more Java classes. Using a package
needs a related subdirectory under Personal Communications\private\ to move
your class in there (see 9.2, “Setting up the Java environment” on page 129).
Follow the package name structure; for example, create a subdirectory called
Personal Communications\private\mypackage\ for a class within the package

mypackage. Enter the full package and class name, for example,
mypackage.SimpleSample in the Run Java Applet dialog box, with or without
extension .class.
To load and run successfully, the applet must implement the ECLAppletInterface
interface to accept an ECLSession object, and have a default constructor. When
the Java program is run, Personal Communications will call the Init(...) method of
the program, passing an ECLSession object that corresponds to the Personal
Communications session currently active. You can then invoke methods against
the ECLSession object to interact with that Personal Communications session.
Sounds very powerful for test purposes ... if we could only escape the restrictions
this feature of Personal Communications currently has. We can, and the code
from Figure 128 on page 138 to Figure 131 on page 141 does the job for us. Of
course, these four figures look like a lot of code but help to save much more code.
First at all, the code provided is a modification of code from earlier in this book. It
can run as both an application and as applet within Personal Communications or
from a Web browser. It always picks up the right methods. Second, it redirects the
standard input, standard output, and standard errors to a window!
Want to test a new HACL feature? No problem. Instead of writing a large

application just for navigating to the right screen inherit from SimpleSample.
Reimplement the perform method ... and you have done your job for today.
To test what you have written, just open a PCOMM session, go to the right
screen, then run your applet. You can watch the messages and follow the
program flow in the Standard Out pane interactively, or enter information you want
to pass to the applet in the Standard In pane (see Figure 127). In either case, you
are informed immediately.
Figure 127. Standard In pane
It looks crude but is powerful behind the scenes. To reduce the lines of code
needed, we only implemented a simple interface.

import java.util.Properties;
import java.applet.Applet;
public class SimpleSample

extends Applet implements ECLAppletInterface {
// Set up a global ConsoleWindow (nice for testing, see text)

final static ConsoleWindow log = new ConsoleWindow("HACL.log");
public SimpleSample() { // Default constructor

}
...A PLACEHOLDER for three methods from Figure on page 139 ...
// Initialize all session startup parameters, start communication

protected ECLSession start(Applet applet) throws Exception {
Properties configData = new Properties(); // Properties for ECL session

// Step 1a: Initialize all session startup parameters
// Need to specify at least session host

configData.put(ECLSession.SESSION_HOST, "localhost");
// Useful options for debugging, uncomment in production environment

// configData.put(ECLSession.SESSION_PS_DEBUGGER, "ON");
// configData.put(ECLSession.SESSION_TRACE, ECLSession.SESSION_TRACE_PS);
// Step 1b: Alternatively, set up new properties object from file

// try {
// configData.load(new FileInputStream("localhost.properties"));
// } catch(Exception e) {
// log.println("Read properties file: " + e.getMessage());
// }
// Needed when the program is running as applet (see text)

if (applet != null)
configData.put(ECLSession.SESSION_APPLET, applet);
// Step 2: Establish virtual emulation session with a host

myECLSession = new ECLSession(configData);
// Step 3: Start the communication

myECLSession.StartCommunication();
System.out.println("Communication started");
return myECLSession;
}
// Perform additional code

protected void perform(ECLSession myECLSession) throws Exception {
// Step 3 (cont.): Put your own code in

System.out.println("Session performed");
}
// Stop SNA communication and free resources

protected void stop(ECLSession myECLSession) throws Exception {
// Step 3 (cont.): This completes our job

myECLSession.StopCommunication(); // Stop SNA communications
myECLSession.dispose(); // Free resources associated with the session
System.out.println("Communication stopped");
}
}
Figure 128. Using an ECLSession object with the SimpleSample class

Figure 128 shows modified sample code from Figure 125 on page 135. Now, this
code can run as an application as well as an applet within Personal
Communications or any Java 1.1-enabled Web browser. Don’t forget to add the
code from Figure 129.
// Init method called within the context of a web browser

public void init() {
try {
myECLSession = start(this);
perform(myECLSession);
stop(myECLSession);
System.out.println("ECL error: message number - " + e.GetMsgNumber());
System.out.println("Message text: " + e.GetMsgText());
} catch(Exception e) {
System.out.println("Unspecified error: " + e.getMessage());
}
}
// Init method called within Personal Communications

public void init(ECLSession myECLSession) {
try {
perform(myECLSession);
}
}
// Main method called when code is running as an application

static public void main(String[] argv) {
SimpleSample mySimpleSample = new SimpleSample();

try {
myECLSession = mySimpleSample.start(null);
mySimpleSample.perform(myECLSession);
mySimpleSample.stop(myECLSession);
}
}
Figure 129. Using an ECLSession object with the SimpleSample class (continued)
The code-excerpt shown in Figure 129 completes the modified SimpleSample

class code from Figure 128. It demonstrates the three ways to call the
SimpleSample class. Moreover, when an ECL exception is thrown it prints both
message number and message text returned in the current default language.
The ConsoleOutput class (see Figure 130) is designed to start as a sub window
from an applet or application. Be aware that in the current implementation closing
the frame window finishes the whole program. If you experience any problems
feel free to change the code.

import java.awt.*;
import java.awt.event.*;
import java.io.*;
// ---------------------------------------------------------------------
// Redirect Standard In/Out/Err to a Frame, useful for tests with PCOMM
// ---------------------------------------------------------------------
public class ConsoleWindow extends Frame {
TextArea outText = null;

TextArea inText = null;
PipedOutputStream outPipe = null;
PrintWriter log = null;
FileOutputStream fos = null;
class MyOutputStream extends OutputStream {
public void write(int b) throws IOException {

print("" + (char)b); // Append character to the output area
}
}
...This is a PLACEHOLDER for the code from Figure 131 on page 141 ...
// Dispose window and close log file

public void dispose() {
try {
if (log != null)
log.close();
if (fos != null)
fos.close();
} catch (IOException e) {
println("Cannot close log file");
}
super.dispose();
System.exit(0); // Your program exits when you close the window !!
}
// Two private methods append strings to the output area

private void print(String text) {
outText.append(text);
if (log != null)
log.print(text);
}
private void println(String text) {

outText.append(text + "\n");
if (log != null)
log.println(text);
}
}
Figure 130. ConsoleOutput class code
The ConsoleOutput class allows you to redirect standard in ("System.in"),

standard out ("System.out"), and standard err ("System.err") to a frame window.
Moreover, all messages will be logged in a log file. Don’t forget to add the code
from Figure 131 on page 141, too.

public ConsoleWindow(String logFileName) {
// GUI part - show two panels for both Standard Out and Standard In -
Button inButton = new Button("Clean Input");
Button outButton= new Button("Clean Output");
Panel inPanel = new Panel(new BorderLayout());
Panel outPanel = new Panel(new BorderLayout());
Label inLabel = new Label("Standard In");
Label outLabel = new Label("Standard Out");
outText = new TextArea();

outText.setEditable(false);
outLabel.setBackground(Color.lightGray);
outPanel.add(outLabel, "North");
outPanel.add(outText, "Center");
outPanel.add(outButton, "South");
inText = new TextArea();
inLabel.setBackground(Color.lightGray);
inPanel.add(inLabel, "North");
inPanel.add(inText, "Center");
inPanel.add(inButton, "South");
setLayout(new GridLayout(2, 1));

setSize(400, 400);
setTitle("Console V0.1 - Tiny window to watch program flow");
add(outPanel);
add(inPanel);
setVisible(true);
addWindowListener(new WindowAdapter() {
public void windowClosing(WindowEvent e) {
dispose(); // Your application window wouldn’t close otherwise
}
});
inButton.addActionListener(new ActionListener() {
public void actionPerformed(ActionEvent e) {
inText.setText(""); // Clean input area
}
});
outButton.addActionListener(new ActionListener() {
public void actionPerformed(ActionEvent e) {
outText.setText(""); // Clean output area
}
});
inText.addKeyListener( new KeyAdapter() {
public void keyTyped(KeyEvent evt) {
try {
outPipe.write(evt.getKeyChar()); // Writes input to "Standard In"
println("Error writing to console standard in");
}
}
});
// Open file for log messages --------------------------------------

try {
fos = new FileOutputStream(logFileName);
log = new PrintWriter(fos, true);
println("Cannot open log file " + logFileName);
}
// Redirect System.in, System.out and System.err -------------------

// Although the class type PrintStream is deprecated we must use it.
try { )
outPipe = new PipedOutputStream();
System.setIn(new BufferedInputStream(new PipedInputStream(outPipe)));
System.setOut(new PrintStream(new MyOutputStream(), true));
System.setErr(new PrintStream(new MyOutputStream(), true));
println("Error redirecting Standard In/Out/Err");
}
}
Figure 131. ConsoleOutput class code from Figure 130 on page 140 (continued)

9.3.3 Navigating the session screens
Once the session has been established, perhaps the most important but also
most difficult task is navigating the session screens. This is due to the fact that
updating a session screen is usually a very time-consuming business. Waiting for
a new screen may freeze your application for just a second or take ages.
Incomplete refreshed sessions cause problems never expected. But the really
bad news is that response time is unpredictable, and dozens of very angry users
may be affected.
One of the main concerns a class library should have is simplicity.
Navigating the session screens with the previous release of HACL assumed
monitoring the notification of any event that happened to both presentation
screen (ECLPS) and operator information area (ECLOIA), and validating if the
expected screen had been received. Every event that occurred needed checking
to ensure the screen was not inhibited (ECLOIA) as well as if the current screen
appearance was identical to that defined (ECLPS). For every definition included,
for example, the appearance of a screen-specific string at a screen-specific
position, you had to write code to look for it.
In this respect, you needed to code every single step. In addition, because events
your code was to listen for occurred very often a lot of unnecessary event
processing could reduce the performance of your program dramatically.
A good demonstration of this is the implementation of the Waiter class in Chapter

10 of IBM SecureWay Host On-Demand: Enterprise Communications in the Era of
Network Computing , SG24-2149-00.
A major improvement in the new release of Host Access Class Library, called
Screen Recognition Technology, addresses exactly this problem. It is supported
by two new classes and one new interface (ECLScreenDesc, ECLScreenReco,
ECLRecoNotify).
All you have to do is set up an object of the ECLScreenReco class. Setting up the
object means registering a presentation space (ECLPS) object it is monitoring for,
and also providing a description of the screen you are interested in
(ECLScreenDesc) plus the related "callback handler". After registering, the
methods of the callback handler are asynchronously called back whenever the
related screen appears in the presentation space. Multiple ECLPS objects can be
monitored at the same time, while multiple screen descriptions and related
callback handlers can be registered. Because you get informed asynchronously,
that is, in a separate thread, it makes automated screen processing easy. Later
we will give an example on page 144.
Now let’s see how to implement screen recognition:

1. The class used to "describe" a screen is ECLScreenDesc. It uses all four
major planes of the presentation space to describe it (TEXT, FIELD, EXFIELD,
COLOR), as well as the cursor position. Using the methods provided by this
object allows you to set up a detailed description of what a given screen "looks
like" in a host application. You don’t need to write boring code that checks a
screen (see Figure 132).
You can specify an attribute at a given screen position and a given plane, a
specific cursor position, the total number of fields or only the number of input

fields, and a string somewhere on the screen or at a given position or screen
rectangle, case sensitive or not. You can also turn on waiting on OIA inhibit
status.
2. In addition to ECLScreenDesc, you need a "callback handler" class which
implements the ECLRecoNotify interface. Its methods only get called when the
desired screen appears (NotifyEvent), or an error (NotifyError) or a stop
(NotifyStop) occurs, reducing event processing to the minimum (see Figure
133).
3. Think of an object of the ECLScreenReco class as a unique "recognition set".
The ECLScreenReco class contains the methods for adding and removing
descriptions of screens. It also contains the logic for recognizing those
screens and for asynchronously calling the methods back to your handler code
for those screens (see Figure 134).
An ECLScreenReco object can have multiple ECLPS objects that it watches
for screens, multiple screens, and multiple callback points to call when it sees
a screen in any of the ECLPS objects.
...
...
...
// Say the screen is identified by a cursor position, a key wordsomewhere on
// the screen, don’t care if the operator information area is inhibited or not.
ECLScreenDesc myScreenDesc = new ECLScreenDesc();
myScreenDesc.AddCursorPos(23, 1); // cursor on right position ?

myScreenDesc.AddString("LOGON"); // String LOGON somewhere on the screen ?
myScreenDesc.AddOIAInhibitStatus(ECLScreenDesc.DONTCARE);
...
...
...
Figure 132. Example of using ECLScreenDesc
The sample code shown in Figure 132 sets up a new screen description based on
an ECLScreenDesc object. You can test this code excerpt by adding it to the
perform method in Figure 128 on page 138. Adapt the description so that it
matches your screen, or you will never hear from your application again!
class SimpleRecoCallback implements ECLRecoNotify {
public void NotifyEvent(ECLPS ps, ECLScreenDesc sd) {

// Code here for the specific screen
System.out.println("Notify");
}
public void NotifyError(ECLPS ps, ECLScreenDesc sd, ECLErr e) {

// Error handling
System.out.println("Error");
}
public void NotifyStop(ECLScreenDesc sd, int Reason) {

// Possible stop monitoring, not essential
System.out.println("Stop");
}
}
Figure 133. Sample code for a simple "callback handler" class

...
...
...
// We need the presentation space object to monitor for
ECLPS myECLPS = myECLSession.GetPS();
// Set up a new callback handler object

SimpleRecoCallback myCallback = new SimpleRecoCallback();
// Set up HACL screen recognition object, starts monitoring here

ECLScreenReco myScreenReco = new ECLScreenReco();
myScreenReco.AddPS(myECLPS);
myScreenReco.RegisterScreen(myScreenDesc, myCallback);
// CODE NOT NECCESSARY, avoids that the program test finishes early.
System.in.read();
myScreenReco.UnregisterScreen(myScreenDesc, myCallback);
...
...
...
Figure 134. Sample code for a simple "callback handler" class (continued)
Figure 134 shows sample code for a screen recognition set based on an
ECLScreenReco object. This code excerpt assumes that you have already
created a session object myECLSession and a screen description object
myScreenDesc. To test the code put it into the code from Figure 128 on page 138
below the code from Figure 132.
After demonstrating the basics of screen recognition we are going to add code to
automate some work. Whenever the "More..." screen occurs it should be cleared
automatically sending the ECLPS.CLEAR_STR keystroke to the host.
1. First, modify the SimpleRecoCallback class to make it more handy. The new
class can serve as a base class for several "callback handlers" and allows
them to act both as screen description class and as callback handler class.
Moreover, it provides a default implementation of the Notify... methods.
public class SimpleRecoCallback extends ECLScreenDesc implements ECLRecoNotify {

// Code here for the specific screen
System.out.println("Notify");
}

// Error handling
}

}
}
Figure 135. Modified code to improve the SimpleRecoCallback class
2. Next, derive a new class MoreCallback from SimpleRecoCallback. This class

uses the NotifyEvent to clear the screen as well as two constructors to add the

proper screen description. The first constructor looks for the string "More..." at
any place in the presentation space, the second one only in the last row.
class MoreCallback extends SimpleRecoCallback {
try {
ps.SendKeys(ps.CLEAR_STR); //Clear the screen
System.out.println("Notify: clear ’More...’ screen");
System.out.println("Exception "+ e.getMessage());
}
}
public MoreCallback() {
AddString("More...");
}
public MoreCallback(ECLPS ps) {

AddStringInRect("More...", ps.GetSizeRows(), 0,
ps.GetSizeRows(), ps.GetSizeCols());
}
}
Figure 136. A "callback handler" class to clear the "More..." screen automatically
3. Add three statements to the code from Figure 134.
...
...
...
// We need the presentation space object to monitor for
// Set up two new callback handler objects

SimpleRecoCallback myCallback = new SimpleRecoCallback();
MoreCallback myMoreCallback = new MoreCallback(myECLPS);
// Set up HACL screen recognition object, starts monitoring here

ECLScreenReco myScreenReco = new ECLScreenReco();
myScreenReco.AddPS(myECLPS);
myScreenReco.RegisterScreen(myScreenDesc, myCallback);
myScreenReco.RegisterScreen(myMoreCallback, myMoreCallback);
// CODE NOT NECESSARY, avoids that the program test finishes early.
System.in.read();
myScreenReco.UnregisterScreen(myScreenDesc, myCallback);
myScreenReco.UnregisterScreen(myMoreCallback, myMoreCallback);
...
...
...
Figure 137. Three statements added to the code from Figure 134.
The last example in this chapter demonstrates how to reimplement the Waiter
class based on the screen recognition technology (see Figure 138). The Waiter
class was originally introduced in the redbook IBM SecureWay Host On-Demand:
Enterprise Communications in the Era of Network Computing, SG24-2149.

package hodred;
class Waiter implements ECLRecoNotify {
ECLScreenReco myScreenReco; // My screen recognition

ECLScreenDesc myScreenDesc; // My screen descriptor
ECLSession myECLSession; // Local instance copy of ECLSession
public Waiter(ECLSession session, ScreenState state) {
// The ECL Session object passed in is used as the noti-

// fication object when the proper host screen is received.
myECLSession = session;
// Set up HACL screen recognition object, starts monitoring

myScreenReco = new ECLScreenReco();
myScreenReco.AddPS(session.GetPS());
}
public void lookfor(Compare cmpIn) {
// Set up HACL screen description object. Say the screen

// is identified by a key word at predefined row and column
myScreenDesc = new ECLScreenDesc();
myScreenDesc.
AddString(cmpIn.stCompare, cmpIn.iRowCompare, cmpIn.iColCompare);
// Add screen description to screen recognition object

myScreenReco.RegisterScreen(myScreenDesc, this);
}
private synchronized void checkAll(ECLScreenDesc sd) {

// Assumes that the desired screen has been received,
// Unregisters screen description not longer needed
myScreenReco.UnregisterScreen(sd, this);
myECLSession.notify();
Test.say("Synch complete. Sent notify to wakeup master.");
}
public void done() {

// Just for compatibility
}

// Notify event, we have found our screen
checkAll(sd);
}

// Error handling, should detect a loss of connection
Test.say("NotifyError! " + e.getMessage());
}

}
}
Figure 138. Waiter class, using screen recognition
Figure 138 shows reimplementation of the Waiter class using screen recognition
technology. The state machine has been temporarily removed because it needs
code changes in several classes to keep it.
If you experience problems, first check:

• When the appearance or the order of a host screen has been modified it’s
likely that you will have to adapt the screen descriptions in your client
application. A problem may occur when changes on the host have been made
without notifying the application owner on the client.
• Preferably, screen descriptions should include data displayed at the bottom of
the host screen; this avoids the possibility of the application’s detecting only
the first in a series of buffers being received. By default, an object of
ECLScreenDesc checks that the host system has finished returning data and
has signalled that the keyboard can be unlocked.
• Dealing with a large number of host-screen manipulations can be difficult for a
program but such complexity can sometimes be reduced significantly with
minor modifications to the host application. For example, in a VM environment,
sending a host command to execute "CP SET MSG OFF" can eliminate
spurious host messages that can potentially interrupt the HACL program.
• When entering data for transmission to the host, it’s often easier to clear an
input field beforehand, so as to be sure that it is empty. Likewise, it’s often
easier to fill in the input field completely with trailing blanks to force an
automatic tab to the next field.
• Because much of the complexity of a HACL application is involved with the
sequence of host screens, some mechanism is generally necessary to track
the host-screen status. This can be as simple as a series of boolean flags, or
as sophisticated as a full state machine.
9.3.4 Navigating inside the screens

The new release of the Host Access Class Library simplifies this task by using
one of the Wait... or WaitWhile... methods provided by the ECLPS (presentation
space) and the ECLOIA (operator information area) classes.
Methods from ECLPS wait synchronously until an attribute, the cursor, a string, a
string in a specified rectangle, or a screen described by ECLScreenDesc,
appears/disappears in the presentation space. Where applicable, methods expect
the change to occur at a given row and column position. Methods regard the OIA
input state.
Methods from ECLOIA wait synchronously until the host application or host
system is available, the input isn’t inhibited, or a transition is taking place from
host system to host application or vice versa. Many of the methods mentioned
wait indefinitely, while others let you specify a time-out value.
These methods work very well for short running tasks, or tasks that can time out
(see Figure 139). If using these methods for long running tasks you should
probably run a separate thread while waiting to see what changes occur.
Elsewhere any user interaction with the application is disabled. In some cases,
hard-killing a non-responding application is the only way to stop it. Therefore, a
better solution for long running tasks is an asynchronous event notification as
shown in 9.3.3, “Navigating the session screens” on page 142.

public class WaitSample extends SimpleSample {
try {
myECLPS.WaitForCursor(23, 16, 1000, true);
myECLPS.WaitWhileString("DEMO");
} catch (InterruptedException e) {
System.out.println("Wait Exception" + e.getMessage());
}
super.perform(myECLSession);
}
}
Figure 139. Synchronous-wait sample code
Figure 139 shows sample code that waits synchronously until the cursor appears
at a given position and the OIA input is not inhibited; it waits for a maximum of
1000 milliseconds. It then waits until the string "DEMO" is no longer in the
presentation space, and the OIA input is not inhibited, then waits an infinite time.
9.3.5 Transferring files from/to the host

Running an application to transfer files is perhaps the most frequent task
encountered. HACL allows transfers with TN3270, TN3270E and CICS sessions.
Moreover, you can track the progress of the file transfer using the classes
ECLXferListener and ECLXferEvent .
For additional options see the online documentation of the ECLXfer class.
public class FileTransferSample extends SimpleSample {
FileTransfer ft = new FileTransfer(myECLSession);
ft.start();
synchronized (ft) {
try {
while (ft.STATE == false) {
if (System.in.available() > 0) {
ft.Cancel();
System.out.println("Key pressed, transfer aborted");
}
ft.wait(100);
}
} catch (InterruptedException e) {
System.out.println("Wait Exception" + e.getMessage());
}
}
super.perform(myECLSession);
}
}
Figure 140. This sample code belongs to Figure 141.

import com.ibm.eNetwork.ECL.event.*;
class FileTransfer extends Thread implements ECLXferListener {

private ECLSession s; // Instance copy of the ECLSession object
private ECLXfer xfer; // Xfer object
public boolean STATE; // public "state machine"
public FileTransfer(ECLSession s1) {

s = s1;
STATE = false;
}
public void Cancel() throws ECLErr {

xfer.Cancel();
}
public void run() {
xfer = s.GetXfer();
xfer.RegisterXferEvent(this);
try {
// Send/receive 'C:\autoexec.bat' to/from host as 'temp text a'

xfer.SendFile("c:\\autoexec.bat", "temp text a", "(ASCII CRLF");
xfer.ReceiveFile("temp text a", "c:\\autoexec.res", "(ASCII CRLF");
System.out.println("File transfer: " + e.GetMsgText());
} catch (Exception e) {
if ((s.GetConnType() != ECLSession.SESSION_TYPE_3270) ||
(s.GetConnType() != ECLSession.SESSION_TYPE_CICS))
System.out.println
("File transfer is only supported for 3270 and CICS sessions.");
else
System.out.println(e.getMessage());
}
STATE = true;
xfer.UnregisterXferEvent(this);
synchronized (this) {
notify();
}
}
public void XferNotifyEvent(ECLXferEvent evt) {
if (evt.IsReceive() == true) {
System.out.println("Host file name: "+evt.GetSourceFile() );
System.out.println("PC file name: "+evt.GetTargetFile() );
System.out.println(evt.GetBytesSent()+" of "+evt.GetBytesToSend()+"
received.");
} else {
System.out.println("PC file name: "+evt.GetSourceFile() );
System.out.println("Host file name: "+evt.GetTargetFile() );
System.out.println(evt.GetBytesSent()+" of "+evt.GetBytesToSend()+" sent.");
}
}
public void XferNotifyError(ECLXfer xfer, ECLErr err) {

// Error handling
}
public void XferNotifyStop(ECLXfer xfer, int reason) {

}
}
Figure 141. Sample code to demonstrate file transfer

9.4 ActiveX controls vs. ActiveX OLE automation objects
Wondering how Java and ActiveX fit together? Actually, ActiveX support is based
on the JavaBeans Bridge for ActiveX from SUN. For more information about this
bridge see the Web site:
http://java.sun.com/beans/software/bridge/
Personal Communications 4.3 provides two types of ActiveX objects:

• ActiveX OLE Automation objects
• ActiveX Host Access controls
The ActiveX OLE Automation objects provide the HACL API in the ActiveX
environment. Generally, these objects should be used when you desire a
non-visual programming API to interact with the host.
The ActiveX Host Access controls provide visual components that can be visually
manipulated within Visual Development Environments such as Visual Basic.
These objects should be used when you want to present emulator-like visual
objects to the user.
9.4.1 Using the Personal Communications ActiveX Host Access controls

Personal Communications 4.3 provides a set of ActiveX Host Access controls for
use in ActiveX development environments. The following controls are available:
• IBM Host Access Terminal
• IBM Host Access Session
• IBM Host Access Screen
• IBM Host Access KeyPad
• IBM Host Access KeyRemap
• IBM Host Access FileTransfer
• IBM Host Access Macro
• IBM Host Access MacroManager
By default, the Host Access controls are NOT enabled. This can be changed by
adding the Personal Communications Host Access control archive (pcseclj.jar) to
the classpath environment variable on your system (see 9.2, “Setting up the Java
environment” on page 129).
Note that enabling the Host Access controls by modifying the global CLASSPATH
environment variable can cause compatibility problems with Host On-Demand.
Once you have enabled the Host Access controls, you may use them as you
would any other ActiveX control. See your ActiveX development-tool
documentation for help.
9.4.2 Using Host Access controls to communicate with host system

To connect to a host, your Host Access controls program first has to create either
a Terminal or Session ActiveX control. A Terminal control would be used when
you want a visible display of the session. A Session control should be used when
you don't want the session to be visible to the user. The Terminal/Session is the

connection to your host. You need to set the Host property of Terminal/Session
control to the name of the Personal Communications .ws profile that you want to
use when starting up your session. Normally these .ws profile files are found in
the ..\private subdirectory of the Personal Communications install directory.
Note that it is not necessary to use the .ws profile extension when setting the
Host property. See your ActiveX tool documentation for help on setting ActiveX
control properties, or see the Host Access Beans for Java online reference for
information about other Terminal/Session properties.

Appendix A. Trace of a connection that uses SSL and SLP
In the following example, there are two CS/NTs. Both support SLP and are
configured for scope name TESTSCOPE. Both servers have a secure port
configured, 0815. The user on the PCOMM client has imported a self-signed
certificate for Server 1 (IP address 9.24.106.49) but not for Server 2 (IP address
9.24.106.155).
When the client’s session starts, Server 2, which has the lower load in relation to
load balancing, answers first, but because the client does not have its certificate,
the connection is not established.
The client then tries to connect to Server 1; since it has this server’s certificate
and the scope name is valid, the session is established.
A trace of this sequence of events follows.

data.0001, 00000076:00000097
SK-Init call: +lpSKITInitData = 0x00146108
-lpSKITInitData:
+sec_types = 0x1caa2800
+keyring = 0x1caa2820
+keyring_pw = 0x00000000
+keyring_stash = 0x1caa3c60
V2_session_timeout = 0
+LDAP_server = 0x00000000
LDAP_port = 0
+LDAP_user = 0x00000000
+LDAP_password = 0x00000000
LDAP_CA_roots = 0
auth_type = 0

data.0001, 00000076:00000097
SK-Init call: +lpSKITInitData = 0x00146108
-lpSKITInitData:
+sec_types = 0x1caa2800
+keyring = 0x1caa2820
+keyring_pw = 0x00000000
+keyring_stash = 0x1caa3c60
+LDAP_server = 0x00000000
LDAP_port = 0
+LDAP_user = 0x00000000
+LDAP_password = 0x00000000
LDAP_CA_roots = 0
auth_type = 0

data.0001, 00000076:00000097
SOCKET CALL: WSAStartup() RC=0

data.0001, 00000076:00000098
Server Host Name: 9.24.106.155

data.0001, 00000076:00000098

data.0001, 00000076:00000098

data.0001, 00000076:00000098

data.0001, 00000076:00000098
SK-Get Cipher Info call: SecurityLvl = 0

data.0001, 00000076:00000098
SK-Get Cipher Info ERROR: skit_get_cipher_info(), rc = -28
(SKIT_BAD_PARAMETER)

data.0001, 00000076:00000098
SK-Socket Init call: +skitSocInitData = 0x00154a18
-skitSocInitData:
fd = 0x0000028c
hs_type = 0x00000000
+DName = 0x00000000
+sec_type = 0x00000000
+cipher_specs = 0x00000000
+v3cipher_specs = 0x00000000
skread = 0x1ca99870
skwrite = 0x1ca998a0
cipherSelected =
[11] 03/12 10:36:15.09,(000A) len=20, 3270/5250/VT Emulator.Communication

data.0001, 00000076:00000098
SK-Socket Init ERROR: skit_secure_soc_init(), failureReasonCode =
-11 (SKIT_ERROR_BAD_MESSAGE)

data.0001, 00000076:00000097
SOCKET CALL: closesocket() RC=0

data.0001, 00000076:0000009A
Server Host Name: 9.24.106.49

data.0001, 00000076:0000009A

data.0001, 00000076:0000009A

data.0001, 00000076:0000009A

data.0001, 00000076:0000009A
SK-Get Cipher Info call: SecurityLvl = 0

data.0001, 00000076:0000009A
SK-Get Cipher Info ERROR: skit_get_cipher_info(), rc = -28
(SKIT_BAD_PARAMETER)

data.0001, 00000076:0000009A
-skitSocInitData:
fd = 0x000002a4
hs_type = 0x00000000
+DName = 0x00000000
+sec_type = 0x00000000
skread = 0x1ca99870
cipherSelected =

data.0001, 00000076:0000009A
-skitSocInitData:
fd = 0x000002a4
hs_type = 0x00000000
+DName = 0x00000000
+sec_type = 0x74c41034
skread = 0x1ca99870
cipherSelected =

data.0001, 00000076:00000054
Summary:
[ IAC DO TN3270E ]
Outbound data :...
ff2
fd8

data.0001, 00000076:00000054
Trace of a connection that uses SSL and SLP 155

Summary:
[ IAC WILL TN3270E ]
Inbound data :...
ff2
fb8

data.0001, 00000076:00000054
Summary:
[ IAC SB TN3270E SEND DEVICE-TYPE IAC SE ]
Outbound data :......0
ff200ff
fa882f0

data.0001, 00000076:00000054
Summary:
[ IAC SB TN3270E DEVICE-TYPE REQUEST IBM-3278-2-E IAC SE ]
Inbound data :......(..........0
ff200444233332324ff
fa82792dd3278d2d5f0

data.0001, 00000076:00000054
Summary:
[ IAC SB TN3270E DEVICE-TYPE IS IBM-3278-2-E CONNECT TEST002 IAC SE ]
Outbound data :.......(...................0
ff200444233332324054553332ff
fa82492dd3278d2d5145340020f0

data.0001, 00000076:00000054
Summary:
[ IAC SB TN3270E FUNCTIONS BIND-IMAGE RESPONSES SYSREQ IAC SE ]
Inbound data :........0
ff200000ff
fa837024f0
[27] 03/12 10:36:17.17,(001A) len=31, 3270/5250/VT Emulator.Communication

data.0001, 00000076:00000054
Summary:
[ IAC SB TN3270E FUNCTIONS SYSREQ BIND-IMAGE RESPONSES SYSREQ IAC SE ]
Outbound data :.........0
ff200000ff
fa834024f0

data.0001, 00000076:00000054
Summary:
[ TN3270E (BIND-IMAGE) ]
[ IAC EOR ]
Outbound data :...............g8.........&.&....SCPCMS05...

000003000b938008f0008000015150000ecdcdeff0fe
300001133100001782020000080803008237342050ff

data.0001, 00000076:00000054
Summary:
[ TN3270E (3270-DATA) ]
Outbound data :......3..
000000ffe
00000d3ff

data.0001, 00000076:00000054
Summary:
[ TN3270E (3270-DATA) ]
[ IAC EOR ]
Outbound data :.....3.. .1B........
00000f0040fc000ff0fe
002013060012051ff2ff

data.0001, 00000076:00000097
Summary:
[ TN3270E (RESPONSE) ]
[ IAC EOR ]
Inbound data :........
000000fe
200010ff

data.0001, 00000076:00000097
Summary:
[ TN3270E (3270-DATA) ]
[ IAC EOR ]
Inbound data :.....h..aa...&....
...0.......aw......&...&....af...411223344556677..ag..0112244.ah.....ar....aeb
................1.C..
0000080188000501004000f000108018a00000050105010188000fffffffffffffff008800ffff
fff008800000890001888001000000000b0200f0c03
00000807111000081104000309070011600b100008000806160804112233445566770d17400112
24407180120619000b1520900000700029051013316
..a..aefghrwy..
00888888889aafe
0d10015678968ff

data.0001, 00000076:00000054
Summary:
[ TN3270E (3270-DATA) ]
Outbound data :.....=G. .8VM/ESA ONLINE.8.AJ.8- Poughkeepsie, N.Y. -
.H*** ** .B/.8Internat
Trace of a connection that uses SSL and SLP 157

000007c1441fed6cec4dddcdc1f1cd1f644d9a889889a8864d4e4464444444444444441c555444
4444444444444554444444444444441c61fc9a8998a
00202e7100d85415210653955d8111d8000764782557295b05b8b00000000000000000d8ccc000
0000000000000cc000000000000000121d895359513
ional Technical .H*** ** * **** ** ********
**** .C1.8 Support Organization .H******** ** *

Appendix B. Special notices
This publication is intended to help customers, business partners and IBM
personnel to install, administer and use Personal Communications. The
information in this publication is not intended as the specification of any
programming interfaces that are provided by Personal Communications. See the
PUBLICATIONS section of the IBM Programming Announcement for Personal
Communications for more information about what publications are considered to
be product documentation.
References in this publication to IBM products, programs or services do not imply

that IBM intends to make these available in all countries in which IBM operates.
Any reference to an IBM product, program, or service is not intended to state or
imply that only IBM's product, program, or service may be used. Any functionally
equivalent program that does not infringe any of IBM's intellectual property rights
may be used instead of the IBM product, program or service.
Information in this book was developed in conjunction with use of the equipment
specified, and is limited in application to those specific hardware and software
products and levels.
IBM may have patents or pending patent applications covering subject matter in
this document. The furnishing of this document does not give you any license to
these patents. You can send license inquiries, in writing, to the IBM Director of
Licensing, IBM Corporation, North Castle Drive, Armonk, NY 10504-1785 USA.
Licensees of this program who wish to have information about it for the purpose
of enabling: (i) the exchange of information between independently created
programs and other programs (including this one) and (ii) the mutual use of the
information which has been exchanged, should contact IBM Corporation, Dept.
600A, Mail Drop 1329, Somers, NY 10589 USA.
Such information may be available, subject to appropriate terms and conditions,

including in some cases, payment of a fee.
The information contained in this document has not been submitted to any formal
IBM test and is distributed AS IS. The information about non-IBM ("vendor")
products in this manual has been supplied by the vendor and IBM assumes no
responsibility for its accuracy or completeness. The use of this information or the
implementation of any of these techniques is a customer responsibility and
depends on the customer's ability to evaluate and integrate them into the
customer's operational environment. While each item may have been reviewed by
IBM for accuracy in a specific situation, there is no guarantee that the same or
similar results will be obtained elsewhere. Customers attempting to adapt these
techniques to their own environments do so at their own risk.
Any pointers in this publication to external Web sites are provided for
convenience only and do not in any manner serve as an endorsement of these
Web sites.
Any performance data contained in this document was determined in a controlled

environment, and therefore, the results that may be obtained in other operating
environments may vary significantly. Users of this document should verify the
applicable data for their specific environment.

Reference to PTF numbers that have not been released through the normal
distribution process does not imply general availability. The purpose of including
these reference numbers is to alert IBM customers to specific information relative
to the implementation of the PTF when it becomes available to each customer
according to the normal IBM PTF distribution process.
The following terms are trademarks of the International Business Machines

Corporation in the United States and/or other countries:
AIX AnyNet
APPN AS/400
AT CICS
CT DB2
Distributed Relational Database Architecture DRDA
eNetwork GDDM
IBM Global Network IBM
IMS MQ
MQSeries MVS/ESA
Netfinity NetView
OS/2 OS/390
OS/400 RS/6000
S/390 SecureWay
SP System/390
VisualAge VM/ESA
VTAM XT
3090 400
The following terms are trademarks of other companies:
C-bus is a trademark of Corollary, Inc. in the United States and/or other countries.
Java and all Java-based trademarks and logos are trademarks or registered
trademarks of Sun Microsystems, Inc. in the United States and/or other countries.
Microsoft, Windows, Windows NT, and the Windows logo are trademarks of
Microsoft Corporation in the United States and/or other countries.
PC Direct is a trademark of Ziff Communications Company in the United States

and/or other countries and is used by IBM Corporation under license.
ActionMedia, LANDesk, MMX, Pentium and ProShare are trademarks of Intel

Corporation in the United States and/or other countries.
UNIX is a registered trademark in the United States and/or other countries

licensed exclusively through X/Open Company Limited.
SET and the SET logo are trademarks owned by SET Secure Electronic
Transation LLC.
Other company, product, and service names may be trademarks or service marks
of others.

Appendix C. Related publications
The publications listed in this section are considered particularly suitable for a
more detailed discussion of the topics covered in this redbook.
C.1 International Technical Support Organization publications

For information on ordering these ITSO publications see “How to get ITSO
redbooks” on page 163.
• Inside APPN - The Essential Guide to the Next-Generation SNA, SG24-3669
• IBM eNetwork Communications Server for Windows NT Version 6.0
Enhancements, SG24-5232
• IBM SecureWay Host On-Demand: Enterprise Communications in the Era of
Network Computing, SG24-2149
C.2 Redbooks on CD-ROMs

Redbooks are also available on the following CD-ROMs. Click the CD-ROMs
button at http://www.redbooks.ibm.com/ for information about all the CD-ROMs
offered, updates and formats.
CD-ROM Title Collection Kit
Number
System/390 Redbooks Collection SK2T-2177
Networking and Systems Management Redbooks Collection SK2T-6022
Transaction Processing and Data Management Redbooks Collection SK2T-8038
Lotus Redbooks Collection SK2T-8039
Tivoli Redbooks Collection SK2T-8044
AS/400 Redbooks Collection SK2T-2849
Netfinity Hardware and Software Redbooks Collection SK2T-8046
RS/6000 Redbooks Collection (BkMgr Format) SK2T-8040
RS/6000 Redbooks Collection (PDF Format) SK2T-8043
Application Development Redbooks Collection SK2T-8037
C.3 Other publications

These publications are also relevant as further information sources:
• eNetwork Communications Server Version 6.0 for Windows NT and eNetwork
Personal Communications Version 4.2 for Windows 95 and Windows NT
Configuration File Reference , SC31-8655
• eNetwork Communications Server Version 6.0 for Windows® NT and
eNetwork Personal Communications Version 4.3 for Windows 95, Windows 98,
and Windows NT Client/Server Communications Programming, SC31-8479
• eNetwork Personal Communications Version 4.3 for Windows 95, Windows 98,
and Windows NT and Version 4.2 for OS/2 Emulator Programming,
SC31-8478
• Systems Network Architecture Formats, GA27-3136 (Note that this volume is
only available in softcopy format as part of the SK2T-6012-22 CD-ROM.)
• Systems Network Architecture Technical Overview, GC30-3073

• High Performance Routing in IP Networks, document number HPRIP-06,
available via anonymous ftp from ftp.networking.ibm.com in the directory
/aiw/appn/hpr/
• Personal Communications V4.3 for Windows NT Reference Volume I,
SC31-8680
• Personal Communications V4.3 for Windows NT Reference Volume II,
SC31-8682

How to get ITSO redbooks
This section explains how both customers and IBM employees can find out about ITSO redbooks, redpieces, and
CD-ROMs. A form for ordering books and CD-ROMs by fax or e-mail is also provided.
• Redbooks Web Site http://www.redbooks.ibm.com/
Search for, view, download or order hardcopy/CD-ROM redbooks from the redbooks web site. Also read
redpieces and download additional materials (code samples or diskette/CD-ROM images) from this redbooks site.
Redpieces are redbooks in progress; not all redbooks become redpieces and sometimes just a few chapters will
be published this way. The intent is to get the information out much quicker than the formal publishing process
allows.
• E-mail Orders
Send orders via e-mail including information from the redbooks fax order form to:
e-mail address
In United States usib6fpl@ibmmail.com
Outside North America Contact information is in the “How to Order” section at this site:
http://www.elink.ibmlink.ibm.com/pbl/pbl/
• Telephone Orders
United States (toll free) 1-800-879-2755
Canada (toll free) 1-800-IBM-4YOU
Outside North America Country coordinator phone number is in the “How to Order” section at
this site:
• Fax Orders
United States (toll free) 1-800-445-9269
Canada 1-403-267-4455
Outside North America Fax phone number is in the “How to Order” section at this site:
This information was current at the time of publication, but is continually subject to change. The latest information for
customer may be found at http://www.redbooks.ibm.com/ and for IBM employees at http://w3.itso.ibm.com/.
IBM Intranet for Employees

IBM employees may register for information on workshops, residencies, and redbooks by accessing the IBM
Intranet Web site at http://w3.itso.ibm.com/ and clicking the ITSO Mailing List button. Look in the Materials
repository for workshops, presentations, papers, and Web pages developed and written by the ITSO technical
professionals; click the Additional Materials button. Employees may also view redbook. residency, and workshop
announcements at http://inews.ibm.com/.

IBM Redbook fax order form
Please send me the following:
Title Order Number Quantity
First name Last name
Company
Address
City Postal code Country
Telephone number Telefax number VAT number
Invoice to customer number
Credit card number
Credit card expiration date Card issued to Signature
We accept American Express, Diners, Eurocard, Master Card, and Visa. Payment by credit card not
available in all countries. Signature mandatory for credit card payment.

Index
E
A edit function 46
ACG file 6 EHLLAPI
Adjacent Control Point (CP) name 34 industry-standard 39
APL 30 EHLLAPI print notification 40
APPC DLLs 38 Enterprise Extender 30
APPN 30 Enterprise Extender DLC 29
APPN Node 34 euro-currency symbol 29, 36
ARB Responsive Mode 29 Extended Katakana 37
ARB responsive mode 43
ASCII host 71
automatic link reactivation 34 F
file transfer
buffer sizes 35
B CUT mode 35
Back-Level LEN Node 34 file-transfer improvements 35
barcode printing 29 file-transfer-buffer defaults 35
barcode printing (Japan) 38 firewall access 20
FMI auto-reconnect 35
C
CA 17 H
CA/400 29 High Performance Routing (HPR) 29
Certficate Management 18 HLLAPI improvements 39
certificate authority (CA) 17 HOST-Dependent LU Only 34
Certificate Wizard 18 Host-XID3 34
Client Access/400 44 hot standby 49
Client Configuration Assistant 91 hot standby (TCP/IP) 52
CM/2 6 HPR/IP 30
coexistence, PCOMM and CA/400 29
coexistence, PCOMM and Client Access/400 44
Communications Manager/2 6 I
Confirm on Exit 44 IBMPCOMMPlus 103
CSDSPY.EXE 117, 121 IBMPCOMPlus module, installing 104
CSMODIFY.EXE 117, 123 IBMRDB 89
CSQUERY.EXE 115, 120 IIN 29
CSSTART -a 45 Installation Manager 1
CSSTART.EXE 115
CSSTOP.EXE 116, 120 J
CStar 29, 37 Japanese CP943 37
Customize Communication, new interface 31 Java Run-time Environment 1
CUT-mode file transfer 35
L
D Learn Node 34
Database Access Utility 95 link reactivation 34
Database Management System 83 load balancing 49
DB2 83 load balancing (TCP/IP) 51
DB2 Client Configuration Assistant (CCA) 85
DB2 Connect 83
DBMS 83 M
DDE convert 40 Managed node 103
DECEDM 78 MD-5 20
Delete Word Classic 45 message/trace, new viewer facility 41
Delete Word Classic function 29 miscellaneous enhancements 43
directory agent (SLP) 51 Multiple Document Interface (MDI) 41
Distributed Relational Database Architecture 83
DRDA 83

N Subarea LEN Node 34
national-language support (new) 38 Sybase 83
Network Virtual Terminal (NVT) 20
NOAPI.DLL 124 T
NOPAPI.DLL 119 Tivoli 103
NVT 20 Courier 103
Execute Task panel 112
O Framework 103
ODBC 83 functions and tasks 108
Adjacent CP name 89 IBMPCOMMPlus tasks and jobs 110
Client Configuration Assistant 91 Issue command 113
CPI-C Side Information 90 List configuration files 114
data source 84 Management Environment (TME) 103
DB2 Trace Facility 101 Management Region (TMR) 103
installation 3 Remote Execution Service (TRIP) 104
Mode definition 89 TMR server 103
problem determination 99 using IBM PCOMMPlus 108
SNA Node Configuration 88 using IBM PCOMMPlus tasks 112
SNA Node configuration 88 Tivoli Agent 103
SNA sense codes 99 trace, for firewall connection 25
Transaction Program (TP) 90 trace, new viewer facility 41
ODBC Driver Manager 86 translation tables, standard 37
Oracle 83
U
P Unattended installation 7
PC managed node 103 user agent (SLP) 50
PCI adapters 35
PCOMM SNA Node Operations 109 V
PCOMM Subscription List 109 VBScript macros 40
PCommClientKeyDb.kdb 17 Viewer utility 29
PCSCC058 message 29, 34 message/trace 41
PCSGSK 18 VT
PCSWIN.INI 37 cursor coupling 78
problem determination (firewall) 25 panning 78
PROG750 22 VT 340 75
VT Clear Page/Car Field 75
R VT Compose 75
ReGIS Graphics 79 VT Do 75
RichWin 29, 37 VT Edit 75
RSP file 6 VT Help 75
VT Hold 75
VT text-character protection 76
S VT100 71
scope (SLP) 49 VT131 Transfer 74
Secure Sockets Layer (SSL) 17, 21 VT220 71
service agent (SLP) 50 VT340 71
Service Location Protocol (SLP) 17, 49 VT52 71
Session-Level Interface (SLI) 39
SHA 20
silent installation 7 W
Sixel 72, 80 WinFrame 45
Sixel Graphics 79 WinHLLAPI 39
SKIT 17, 19
SLI API 29, 39
SLP 49
SNA Node, prevent from stopping 45
SQL 83
SSL 17

ITSO Redbook Evaluation
Personal Communications Version 4.3 for Windows 95, 98 and NT
SG24-4689-01
Your feedback is very important to help us maintain the quality of ITSO redbooks. Please complete this
questionnaire and return it using one of the following methods:
• Use the online evaluation form found at http://www.redbooks.ibm.com
• Fax this form to: USA International Access Code + 1 914 432 8264
• Send your comments in an Internet note to redbook@us.ibm.com
Which of the following best describes you?

_ Customer _ Business Partner _ Solution Developer _ IBM employee
_ None of the above
Please rate your overall satisfaction with this book using the scale:
(1 = very good, 2 = good, 3 = average, 4 = poor, 5 = very poor)
Overall Satisfaction __________
Please answer the following questions:
Was this redbook published in time for your needs? Yes___ No___
If no, please explain:
What other redbooks would you like to see published?
Comments/Suggestions: (THANK YOU FOR YOUR FEEDBACK!)

Personal Communications Version 4.3 for Windows 95, 98 and NT SG24-4689-01
Printed in the U.S.A.
SG24-4689-01

SG 244689

Загружено:

Сведения о документе

Исходное описание:

Оригинальное название

Авторское право

Доступные форматы

Поделиться этим документом

Поделиться или встроить документ

Параметры публикации

Этот документ был вам полезен?

Это неприемлемый материал?

Авторское право:

Доступные форматы

SG 244689

Загружено:

Авторское право:

Доступные форматы

Personal Communications Version 4.

Julian Over, Falk Doege, Olaf Graf, Matthew Radford

International Technical Support Organization

Personal Communications Version 4.3

Second Edition (August 1999)

Comments may be addressed to:

Chapter 2. Securing your connections - SSL and firewalls .. . . . . .. . . . .17

Chapter 3. Miscellaneous enhancements . . . . . . . . . . . . . . .. . . . . .. . . . .29

© Copyright IBM Corp. 1996 1999 iii

Chapter 4. Load balancing and hot standby . . . .. . . . .. . . . . .. . . . . .. . 49

Chapter 5. IPX enhancements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. . 57

iv Personal Communications V4.3 for Windows 95, 98 and NT

Chapter 6. VT emulation enhancements . . . . . . . . . .. . . . . .. . . . . .. . . . .71

Chapter 7. Database access with PCOMM 4.3 . . . . . . . . . . . .. . . . . .. . . . .83

Chapter 8. Tivoli support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. . . .103

Chapter 9. Java development with Personal Communications . . . .. . . .125

Appendix A. Trace of a connection that uses SSL and SLP. . . . . . . . . . . .153

Appendix B. Special notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .159

Appendix C. Related publications . . . . . . . . . . . . . . . . . . . . . . ...... . . . . . 161

How to get ITSO redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163

ITSO Redbook Evaluation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167

vi Personal Communications V4.3 for Windows 95, 98 and NT

© Copyright IBM Corp. 1996 1999 vii

viii Personal Communications V4.3 for Windows 95, 98 and NT

The team that wrote this redbook

Julian Over is a Consulting Systems Engineer in the International Technical

Falk Doege is a networking specialist at CSG in Germany. He has three years of

Olaf Graf is an application development specialist at CSG in Germany. He has

Matthew Radford is an Enterprise Communications Specialist in IBM Personal

Thanks to the following people for their contributions to this project:

© Copyright IBM Corp. 1996 1999 xi

We want our redbooks to be as helpful as possible. Please send us your

xii Personal Communications V4.3 for Windows 95, 98 and NT

Migrating configuration files from Communications Manager/2 (CM/2) and older

1.1 Installation Manager

1.1.1 Installation Manager highlights

© Copyright IBM Corp. 1996 1999 1

WIN32 NT/95/98 Program

PCOMM Install Shield

Figure 1. PCOMM installation implementation

1.1.3 Installing products

2 Personal Communications V4.3 for Windows 95, 98 and NT

1.2 Installation overview

4 Personal Communications V4.3 for Windows 95, 98 and NT

1.3 Migration of previous configuration files

Figure 4. PCOMM 4.3 migration utility

Figure 5. CM/2 migration

The following CM/2 configurations can be migrated:

1.3.2 Migrating PCOMM configurations

6 Personal Communications V4.3 for Windows 95, 98 and NT

1.4 Unattended (silent) installation

Figure 7. Example section of PRODUCT.TXT for silent installation

1.5 Installation of PCOMM using Microsoft SMS

1.6 Remote installation using Tivoli Courier

8 Personal Communications V4.3 for Windows 95, 98 and NT

1.7 Configuration file update support

A template contains the configuration elements common to all clients. An update

1.7.1 How update files are created

Figure 8. Example update file

Figure 9. Example update file, showing how to delete keywords

1.7.2 Using update files to change your configuration

10 Personal Communications V4.3 for Windows 95, 98 and NT