SG24-2144-00

Connecting the Enterprise to the Internet

with MQSeries and VisualAge for Java

December 1997
 SG24-2144-00

International Technical Support Organization

Connecting the Enterprise to the Internet

with MQSeries and VisualAge for Java

December 1997

IBML
 Take Note!

Before using this information and the product it supports, be sure to read the general information
in Appendix C, “Special Notices” on page 205.

First Edition (December 1997)

This edition applies to the following products:

• MQSeries for AIX V5.0
• MQSeries for OS/2 Warp V5.0
• MQSeries for Windows NT V5.0
• VisualAge for Java 1.0 Entry Version
• VisualAge for Java 1.0 Professional Version
• VisualAge for Java 1.0 Enterprise Version

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

Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv
The Team That Wrote This Redbook . . . . . . . . . . . . . . . . . . . . . . xv
Comments Welcome . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii

Chapter 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.1 About MQSeries Version 5 . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.2 About MQSeries and Java . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.3 About VisualAge for Java . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.4 About This Book′s Objectives . . . . . . . . . . . . . . . . . . . . . . . 5
1.5 About Internet Connections . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.5.1 MQSeries Internet Gateway . . . . . . . . . . . . . . . . . . . . . . 7
1.5.2 MQSeries Client for Java . . . . . . . . . . . . . . . . . . . . . . . 8
1.5.3 MQSeries Bindings for Java . . . . . . . . . . . . . . . . . . . . . . 9
1.6 About Connections to the Mainframe . . . . . . . . . . . . . . . . . . . 9
1.7 About Internet Applications . . . . . . . . . . . . . . . . . . . . . . . . . 11

Chapter 2. Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
2.1 IBM Internet Connection Secure Server . . . . . . . . . . . . . . . . . 14
2.1.1 How to Get the ICSS . . . . . . . . . . . . . . . . . . . . . . . . . . 14
2.1.2 Hardware and Software Requirements . . . . . . . . . . . . . . . 14
2.1.3 How to Install the ICSS on a Windows NT System . . . . . . . . . 17
2.2 Netscape Navigator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
2.2.1 How to Get the Browser . . . . . . . . . . . . . . . . . . . . . . . . 24
2.2.2 How to Install the Browser . . . . . . . . . . . . . . . . . . . . . . 24
2.2.3 How to Set Up the Browser for Java . . . . . . . . . . . . . . . . . 25
2.3 Java Development Kit (JDK) 1.1.4 from Sun . . . . . . . . . . . . . . . 26
2.3.1 How to Download the JDK 1.1.4 . . . . . . . . . . . . . . . . . . . . 27
2.3.2 How to Install JDK 1.1.4 . . . . . . . . . . . . . . . . . . . . . . . . 28
2.4 MQSeries Version 5.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
2.4.1 About MQSeries Version 5.0 . . . . . . . . . . . . . . . . . . . . . 29
2.4.2 About the MQSeries Client for Java . . . . . . . . . . . . . . . . . 31
2.4.3 How to Install MQSeries Version 5 . . . . . . . . . . . . . . . . . . 31
2.5 MQSeries Client for Java . . . . . . . . . . . . . . . . . . . . . . . . . . 33
2.5.1 How to Get the MQSeries Client for Java . . . . . . . . . . . . . . 33
2.5.2 Installing the Documentation . . . . . . . . . . . . . . . . . . . . . 34
2.5.3 Installing the MQSeries Client for Java . . . . . . . . . . . . . . . 35
2.5.4 Running the Installation Verification Applet . . . . . . . . . . . . 37

 Copyright IBM Corp. 1997 iii

 2.6 VisualAge for Java Version 1.0 . . . . . . . . . . . . . . . . . . . . . . . 37
2.6.1 VisualAge for Java Entry Version . . . . . . . . . . . . . . . . . . . 38
2.6.2 VisualAge for Java Enterprise Version . . . . . . . . . . . . . . . 39
2.6.3 Setting Up VisualAge for Java . . . . . . . . . . . . . . . . . . . . 40

Chapter 3. MQSeries Overview . . . . . . . . . . . . . . . . . . . . . . . . . 43

3.1 What Is Messaging and Queuing? . . . . . . . . . . . . . . . . . . . . . 44
3.1.1 Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
3.1.2 Queue Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
3.1.3 MQSeries Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
3.2 Message Queues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
3.2.1 Local Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
3.2.2 Remote Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
3.2.3 Transmission Queue . . . . . . . . . . . . . . . . . . . . . . . . . . 48
3.2.4 Dynamic Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
3.2.5 Model Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
3.2.6 Alias Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
3.2.7 Initiation Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
3.2.8 Reply-To Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
3.2.9 Dead-Letter Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
3.3 Creating a Queue Manager . . . . . . . . . . . . . . . . . . . . . . . . . 50
3.4 Manipulating MQM Objects (RUNMQSC) . . . . . . . . . . . . . . . . . 52
3.5 Clients and Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
3.6 How MQSeries Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
3.7 Communication between Queue Managers . . . . . . . . . . . . . . . 58
3.7.1 How to Define a Connection between Two Systems . . . . . . . 59
3.7.2 How to Start Communication Manually . . . . . . . . . . . . . . . 60
3.7.3 How to Start Channels Automatically . . . . . . . . . . . . . . . . 61
3.7.4 How to Start Applications Automatically . . . . . . . . . . . . . . 62
3.7.5 How to Test if the Queue Manager Is Working . . . . . . . . . . . 63
3.8 Communication between Client and Server . . . . . . . . . . . . . . . 64
3.8.1 How to Define a Client/Server Connection . . . . . . . . . . . . . 64
3.8.2 How to Start a Client/Server Connection . . . . . . . . . . . . . . 66
3.8.3 How to Test a Client/Server Connection . . . . . . . . . . . . . . 67
3.8.4 How a Client/Server Connection Works . . . . . . . . . . . . . . . 68
3.9 The Message Queuing Interface (MQI) . . . . . . . . . . . . . . . . . . 72
3.9.1 A Code Fragment . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

Chapter 4. MQFirstSteps for Windows . . . . . . . . . . . . . . . . . . . . . 77

4.1 About MQFirstSteps for Windows . . . . . . . . . . . . . . . . . . . . . 77
4.2 What You Need to Use it . . . . . . . . . . . . . . . . . . . . . . . . . . 77
4.3 How to Get MQFirstSteps for Windows . . . . . . . . . . . . . . . . . . 78
4.4 How to Install MQFirstSteps for Windows . . . . . . . . . . . . . . . . 78
4.5 How to Use MQFirstSteps for Windows . . . . . . . . . . . . . . . . . . 79

iv Connecting to the Internet with MQSeries and VisualAge for Java

 4.5.1 MQFirst Guided Tour . . . . . . . . . . . . . . . . . . . . . . . . . . 80
4.5.2 MQFirst Quick Start . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

Chapter 5. Java and VisualAge for Java Overview . . . . . . . . . . . . . 87

5.1 Some Basics about Java . . . . . . . . . . . . . . . . . . . . . . . . . . 87
5.1.1 Java Is Platform-Independent . . . . . . . . . . . . . . . . . . . . . 87
5.1.2 Java Is Distributed . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
5.1.3 Java Is Secure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
5.1.4 Java Is Robust . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
5.1.5 Java Is Object-Oriented . . . . . . . . . . . . . . . . . . . . . . . . 90
5.2 Applications and Applets . . . . . . . . . . . . . . . . . . . . . . . . . . 92
5.3 A First Try with Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
5.3.1 The Hello World Application . . . . . . . . . . . . . . . . . . . . . . 94
5.3.2 The Hello World Applet . . . . . . . . . . . . . . . . . . . . . . . . . 95
5.4 A First Try with VisualAge for Java . . . . . . . . . . . . . . . . . . . 100
5.4.1 Creating Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
5.4.2 Changing Object Properties . . . . . . . . . . . . . . . . . . . . . 104
5.4.3 Aligning and Resizing Objects . . . . . . . . . . . . . . . . . . . 107
5.4.4 Visual Programming . . . . . . . . . . . . . . . . . . . . . . . . . 108
5.4.5 Testing the Applet . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
5.4.6 Methods Generated by VisualAge for Java . . . . . . . . . . . . 111
5.4.7 Versioning and Exporting a Package . . . . . . . . . . . . . . . 113
5.4.8 Importing a Package . . . . . . . . . . . . . . . . . . . . . . . . . 115

Chapter 6. An MQSeries Application . . . . . . . . . . . . . . . . . . . . . 119

6.1 Creating an Applet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
6.2 Writing a Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
6.2.1 How to Connect Events to a Method . . . . . . . . . . . . . . . . 125
6.2.2 How to Connect Parameter from Property . . . . . . . . . . . . 126
6.3 How to Connect to the Queue Manager . . . . . . . . . . . . . . . . 127
6.4 How to Disconnect from a Queue Manager . . . . . . . . . . . . . . 130
6.5 How to Open a Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
6.6 How to Close a Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
6.7 How to Put a Message Into a Queue . . . . . . . . . . . . . . . . . . 134
6.8 How to Get a Message from a Queue . . . . . . . . . . . . . . . . . 137
6.9 Creating a Java Application Using MQSeries . . . . . . . . . . . . . 139
6.9.1 Writing an MQSeries Server Application . . . . . . . . . . . . . 140
6.10 How to Test the Application . . . . . . . . . . . . . . . . . . . . . . . 142
6.10.1 Preparation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
6.10.2 Testing the Applet . . . . . . . . . . . . . . . . . . . . . . . . . . 143
6.11 How to Test if the MQSeries Client for Java Works . . . . . . . . . 145

Chapter 7. The IMS Bridge and MQSeries . . . . . . . . . . . . . . . . . 149

7.1 The IMS Bridge and OTMA . . . . . . . . . . . . . . . . . . . . . . . . 149

Contents v
 7.2 Benefits of OTMA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
7.3 The IMS Bridge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
7.4 How to Set Up the IMS Bridge . . . . . . . . . . . . . . . . . . . . . . 153
7.5 The IMS Bridge and the Application . . . . . . . . . . . . . . . . . . 156
7.6 Some Tips about Data Conversion . . . . . . . . . . . . . . . . . . . 158
7.7 Some Hints for Implementation . . . . . . . . . . . . . . . . . . . . . 160

Chapter 8. Connecting the Internet to IMS . . . . . . . . . . . . . . . . . 161

8.1 The Purpose of the Example . . . . . . . . . . . . . . . . . . . . . . . 161
8.2 Software and Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
8.2.1 Setting Up MQSeries to Run the Example . . . . . . . . . . . . 163
8.2.2 How We Did It in the Lab . . . . . . . . . . . . . . . . . . . . . . 164
8.2.3 MQSeries Client for Java and MQSeries Bindings . . . . . . . 164
8.3 The Logic of the Java Applet . . . . . . . . . . . . . . . . . . . . . . . 164
8.4 Creating the Java Applet Using VisualAge for Java . . . . . . . . . 165
8.4.1 Start VisualAge for Java . . . . . . . . . . . . . . . . . . . . . . . 165
8.4.2 Add a New Project and Package . . . . . . . . . . . . . . . . . . 165
8.4.3 Quick Start to Create an Applet . . . . . . . . . . . . . . . . . . 166
8.4.4 Building the GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
8.4.5 Import MQSeries Client for Java Classes . . . . . . . . . . . . . 168
8.4.6 Create Instance Variables . . . . . . . . . . . . . . . . . . . . . . 169
8.4.7 Populate the List Box . . . . . . . . . . . . . . . . . . . . . . . . . 169
8.4.8 Program the Clear Button Functions Visually . . . . . . . . . . 170
8.5 Creating the Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
8.5.1 Connect to the Queue Manager . . . . . . . . . . . . . . . . . . 174
8.5.2 Open Input and Output Queues . . . . . . . . . . . . . . . . . . . 176
8.5.3 Format the Message for IMS . . . . . . . . . . . . . . . . . . . . 176
8.5.4 Put the IMS Message on the Queue . . . . . . . . . . . . . . . . 179
8.5.5 Get and Parse a Message . . . . . . . . . . . . . . . . . . . . . . 181
8.5.6 Close Input and Output Queue . . . . . . . . . . . . . . . . . . . 182
8.5.7 Disconnect from the Queue Manager . . . . . . . . . . . . . . . 182
8.5.8 Start Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
8.5.9 Stop Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
8.5.10 Getter Methods for User Data . . . . . . . . . . . . . . . . . . . 183
8.6 Submit Button Connections . . . . . . . . . . . . . . . . . . . . . . . . 184
8.6.1 Connect Button to Method . . . . . . . . . . . . . . . . . . . . . . 184
8.6.2 Connect Input Data with Method . . . . . . . . . . . . . . . . . . 185
8.6.3 Connect Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
8.6.4 Display Method Output in the Applet . . . . . . . . . . . . . . . 187
8.6.5 Connect Button to Text Field . . . . . . . . . . . . . . . . . . . . 189
8.6.6 Reorder Connections . . . . . . . . . . . . . . . . . . . . . . . . . 189
8.7 Creating a Java Application Using VisualAge for Java . . . . . . . 191
8.7.1 Checklist for the Execution . . . . . . . . . . . . . . . . . . . . . 191
8.7.2 How to Create a Non-Visual Application . . . . . . . . . . . . . 191

vi Connecting to the Internet with MQSeries and VisualAge for Java

Appendix A. MQSeries Objects for WWW/IMS Application . . . . . . . . 197
A.1 Definitions for Web Server . . . . . . . . . . . . . . . . . . . . . . . . 197
A.2 Definitions for MVS System . . . . . . . . . . . . . . . . . . . . . . . 200

Appendix B. Diskette Contents . . . . . . . . . . . . . . . . . . . . . . . . 203

Appendix C. Special Notices . . . . . . . . . . . . . . . . . . . . . . . . . 205

Appendix D. Related Publications . . . . . . . . . . . . . . . . . . . . . . 207

D.1 International Technical Support Organization Publications . . . . . 207
D.2 Redbooks on CD-ROMs . . . . . . . . . . . . . . . . . . . . . . . . . . 207
D.3 Other Publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207

How to Get ITSO Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . 209

How IBM Employees Can Get ITSO Redbooks . . . . . . . . . . . . . . . 209
How Customers Can Get ITSO Redbooks . . . . . . . . . . . . . . . . . . 210
IBM Redbook Order Form . . . . . . . . . . . . . . . . . . . . . . . . . . . 211

Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213

List of Abbreviations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219

ITSO Redbook Evaluation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221

Contents vii
viii Connecting to the Internet with MQSeries and VisualAge for Java
Figures

1. MQSeries for Windows NT V5 . . . . . . . . . . . . . . . . . . . . . . . 6

2. MQSeries Internet Gateway . . . . . . . . . . . . . . . . . . . . . . . . 7
3. MQSeries Client for Java . . . . . . . . . . . . . . . . . . . . . . . . . 8
4. Global View of Installed Systems . . . . . . . . . . . . . . . . . . . . 10
5. Connection to IMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
6. Internet Connection Server - Web Page . . . . . . . . . . . . . . . . . 15
7. Internet Connection Server - Files . . . . . . . . . . . . . . . . . . . . 16
8. Internet Connection Server - Select Components . . . . . . . . . . . 17
9. Internet Connection Server - Choose Target Directory . . . . . . . . 18
10. Internet Connection Server - Choose Configuration Parameters . . 20
11. Internet Connection Server - Example of a Front Page . . . . . . . . 22
12. Internet Connection Server - Configuration and Administration . . 23
13. Netscape Navigator Install Window . . . . . . . . . . . . . . . . . . . 25
14. JDK 1.1.4 - Download . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
15. JDK 1.1.4 - Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
16. JDK 1.1.4 - Windows NT Classpath Settings . . . . . . . . . . . . . . 29
17. MQSeries - Select Destination Directory . . . . . . . . . . . . . . . . 32
18. MQSeries - Select Components . . . . . . . . . . . . . . . . . . . . . 33
19. MQSeries Client for Java Documentation (index.html) . . . . . . . . 35
20. VisualAge for Java - Install Directory . . . . . . . . . . . . . . . . . . 38
21. VisualAge for Java - Install Components . . . . . . . . . . . . . . . . 40
22. MQSeries at Runtime . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
23. Program-to-Program Communication - One System . . . . . . . . . 45
24. Program-to-Program Communication - Two Systems . . . . . . . . 45
25. RUNMQSC - Interactive . . . . . . . . . . . . . . . . . . . . . . . . . . 52
26. RUNMQSC - Using Command File . . . . . . . . . . . . . . . . . . . . 53
27. RUNMQSC - Input File . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
28. RUNMQSC - Output File . . . . . . . . . . . . . . . . . . . . . . . . . . 53
29. MQSeries Channels . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
30. MQSeries Parts and Logic . . . . . . . . . . . . . . . . . . . . . . . . 56
31. Communication between Two Queue Managers . . . . . . . . . . . 58
32. Triggering Channels . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
33. Triggering Applications . . . . . . . . . . . . . . . . . . . . . . . . . . 63
34. Testing the Queue Manager . . . . . . . . . . . . . . . . . . . . . . . 64
35. Client/Server Connection . . . . . . . . . . . . . . . . . . . . . . . . . 65
36. Definitions for Server Connection . . . . . . . . . . . . . . . . . . . . 65
37. Testing Client/Server Connection . . . . . . . . . . . . . . . . . . . . 68
38. Verify Installation Applet . . . . . . . . . . . . . . . . . . . . . . . . . . 68
38. Listener Window (RUNMQLSR) . . . . . . . . . . . . . . . . . . . . . . 68
39. Clients and Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
40. Definitions for Two Clients and Server . . . . . . . . . . . . . . . . . 71

 Copyright IBM Corp. 1997 ix

 41. Fragments of an MQSeries Program . . . . . . . . . . . . . . . . . . 74
42. MQFirst - Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
43. MQFirst - Welcome Window . . . . . . . . . . . . . . . . . . . . . . . . 80
44. MQFirst - Sixth Window . . . . . . . . . . . . . . . . . . . . . . . . . . 82
45. MQFirst - Eighth Window . . . . . . . . . . . . . . . . . . . . . . . . . 83
46. MQFirst - Sending and Receiving Messages . . . . . . . . . . . . . . 84
47. MQFirst - Main Window . . . . . . . . . . . . . . . . . . . . . . . . . . 85
48. MQFirst - Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
49. Difference between C And Java Compiler . . . . . . . . . . . . . . . 88
50. A Simple Java Application . . . . . . . . . . . . . . . . . . . . . . . . 94
51. A Simple Java Applet . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
52. HTML File that Calls an Applet . . . . . . . . . . . . . . . . . . . . . . 97
53. VisualAge for Java - Quick Start . . . . . . . . . . . . . . . . . . . . 100
54. VisualAge for Java - Create an Applet . . . . . . . . . . . . . . . . 101
55. VisualAge for Java - Composition Editor . . . . . . . . . . . . . . . 102
56. VisualAge for Java - A GUI . . . . . . . . . . . . . . . . . . . . . . . 103
57. VisualAge for Java - Push Button Properties . . . . . . . . . . . . 105
58. VisualAge for Java - Fonts . . . . . . . . . . . . . . . . . . . . . . . 106
59. VisualAge for Java - Change Bean Name . . . . . . . . . . . . . . 107
60. Visual Programming - Connections . . . . . . . . . . . . . . . . . . 109
61. Appletviewer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
62. VisualAge Generated Methods . . . . . . . . . . . . . . . . . . . . . 111
63. One Method as an Example . . . . . . . . . . . . . . . . . . . . . . . 112
64. Workbench Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
65. SmartGuide - Versioning Selected Items . . . . . . . . . . . . . . . 114
66. SmartGuide - Type of Export . . . . . . . . . . . . . . . . . . . . . . 114
67. SmartGuide - Export to Interchange File . . . . . . . . . . . . . . . 115
68. Import a Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
69. MQSeries Application - Overview . . . . . . . . . . . . . . . . . . . 119
70. MQSeries Application - Client . . . . . . . . . . . . . . . . . . . . . 120
71. MQSeries Application - Server . . . . . . . . . . . . . . . . . . . . . 121
72. MQExample1 - VisualAge Methods Editor . . . . . . . . . . . . . . 123
73. MQExample1 - Creating a New Method . . . . . . . . . . . . . . . . 124
74. MQExample1 - Writing a Method . . . . . . . . . . . . . . . . . . . . 125
75. MQExample1 - Connect Event to Method . . . . . . . . . . . . . . . 126
76. MQExample1 - Set Parameter from Property . . . . . . . . . . . . 127
77. MQExample1 - Connect Queue Manager . . . . . . . . . . . . . . . 128
78. MQExample1 - Method connectToQmgr . . . . . . . . . . . . . . . 129
79. MQExample1 - Disconnect from Queue Manager . . . . . . . . . . 130
80. MQExample1 - Method disconnectFromQmgr . . . . . . . . . . . . 131
81. MQExample1 - Method openQueue . . . . . . . . . . . . . . . . . . 132
82. MQExample1 - Open a Queue . . . . . . . . . . . . . . . . . . . . . 133
83. MQExample1 - Method closeQueue . . . . . . . . . . . . . . . . . . 134
84. MQExample1 - Close Queue . . . . . . . . . . . . . . . . . . . . . . 134

x Connecting to the Internet with MQSeries and VisualAge for Java

85. MQExample1 - Method putMessage . . . . . . . . . . . . . . . . . . 135
86. MQExample1 - Put a Message in a Queue . . . . . . . . . . . . . . 136
87. MQExample1 - Get a Message from a Queue . . . . . . . . . . . . 137
88. MQExample1 - Method receiveMessage . . . . . . . . . . . . . . . 138
89. MQExample2 - VisualAge Projects Window . . . . . . . . . . . . . 140
90. MQExample2 - Method connectToQmgr . . . . . . . . . . . . . . . 141
91. MQExample2 - Connections . . . . . . . . . . . . . . . . . . . . . . . 142
92. MQExample1 - GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
93. MQExample1 - Output . . . . . . . . . . . . . . . . . . . . . . . . . . 145
94. Verify Installation Program (IVP) . . . . . . . . . . . . . . . . . . . . 146
95. Verify Installation Results . . . . . . . . . . . . . . . . . . . . . . . . 147
96. Access to IMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
97. IMS Standard Triggering with MQSeries . . . . . . . . . . . . . . . 153
98. IMS Bridge - The Basic Flow . . . . . . . . . . . . . . . . . . . . . . 154
99. IMS Bridge - Detailed View . . . . . . . . . . . . . . . . . . . . . . . 155
100. Design and Message Flow between WWW and IMS . . . . . . . . 162
101. WWW-IMS Example - Employee Record Layout . . . . . . . . . . . 167
102. Hierarchy - Import MQSeries Client Classes . . . . . . . . . . . . . 168
103. WWW-IMS Example - Populating the List Box . . . . . . . . . . . . 170
104. WWW-IMS Example - Clear Button Connections . . . . . . . . . . . 172
105. WWW-IMS Example - Method connectToQmgr . . . . . . . . . . . . 175
106. WWW-IMS Example - Method openInputQueue . . . . . . . . . . . 175
107. WWW-IMS Example - Method openOutputQueue . . . . . . . . . . 175
108. WWW-IMS Example - Method formatToIMSmessage (Part 1) . . . 177
109. WWW-IMS Example - Method putMessage . . . . . . . . . . . . . . 179
110. WWW-IMS Example - Method retrieveMessage . . . . . . . . . . . 180
111. WWW-IMS Example - Method closeInputQueue . . . . . . . . . . . 182
112. WWW-IMS Example - Method closeOutputQueue . . . . . . . . . . 182
113. WWW-IMS Example - Start Method . . . . . . . . . . . . . . . . . . 183
114. WWW-IMS Example - Stop Method . . . . . . . . . . . . . . . . . . . 183
115. WWW-IMS Example - Getter Methods . . . . . . . . . . . . . . . . . 183
116. WWW-IMS Example - Connect Button to Method . . . . . . . . . . 184
117. WWW-IMS Example - Passing Input Parameters . . . . . . . . . . 185
118. WWW-IMS Example - Passing Parameters to Method . . . . . . . 186
119. WWW-IMS Example - Connecting Methods . . . . . . . . . . . . . . 187
120. WWW-IMS Example - Display IMS Results in Text Area . . . . . . 187
121. WWW-IMS Example - Display Data in Text Fields . . . . . . . . . . 188
122. WWW-IMS Example - Completed Applet . . . . . . . . . . . . . . . 190
123. WWW-IMS Example - Reorder Connections . . . . . . . . . . . . . 190
124. WWW-IMS Example - Business Logic . . . . . . . . . . . . . . . . . 192
125. WWW-IMS Example - Import Bindings . . . . . . . . . . . . . . . . . 193
126. WWW-IMS Example - Business Logic Class . . . . . . . . . . . . . 193
127. WWW-IMS Example - Business Logic Constructor . . . . . . . . . 194
128. WWW-IMS Example - Business Logic Main . . . . . . . . . . . . . . 196

Figures xi
xii Connecting to the Internet with MQSeries and VisualAge for Java
Tables

1. ICSS Directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
2. ICSS Configuration Parameters . . . . . . . . . . . . . . . . . . . . . 20
3. MQSeries Objects for MQM-to-MQM Connection . . . . . . . . . . . 59
4. Start MQM-to-MQM Connection . . . . . . . . . . . . . . . . . . . . . 60
5. MQSeries Definitions to Start Channels . . . . . . . . . . . . . . . . . 61
6. Method connectToQmgr and Parameters . . . . . . . . . . . . . . . 129
7. Method disconnectFromQmgr and Parameters . . . . . . . . . . . 131
8. Method openQueue and Parameters . . . . . . . . . . . . . . . . . 132
9. Method closeQueue and Parameters . . . . . . . . . . . . . . . . . 133
10. Method putMessage and Parameters . . . . . . . . . . . . . . . . . 135
11. Method retrieveMessage and Parameters . . . . . . . . . . . . . . 138
12. Message Layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
13. WWW/IMS Example - Methods . . . . . . . . . . . . . . . . . . . . . 173
14. WWW/IMS Example - Method connectToQmgr and Parameters . 174
15. WWW-IMS Example - Method openInputQueue and Parameters . 176
16. WWW-IMS Example - Method openOutputQueue and Parameters 176
17. WWW-IMS Example - Method formatToIMSmessage and
Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
18. WWW-IMS Example - Method putMessage and Parameters . . . . 179
19. WWW-IMS Example - Method retrieveMessage and Parameters . 181
20. Files on Diskette . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203

 Copyright IBM Corp. 1997 xiii

xiv Connecting to the Internet with MQSeries and VisualAge for Java
Preface

This redbook helps you integrate IBM′s award-winning middleware

MQSeries, the Internet, Java, VisualAge for Java, and existing host
applications. It gives you a broad understanding of what has to be done to
connect Internet/Intranet users to legacy systems in your enterprise.

This book describes how to develop programs that use MQSeries with
VisualAge for Java. It contains examples that help you write your first Java
applet and Java application, with and without VisualAge. Another example
explains, in detail, how to invoke MQSeries APIs. The final example shows
how a Java applet connects to an IMS application via a Java application
running in the Web server.

The Internet technology provides low-cost easy access to global

communications, while MQSeries connectivity provides high integrity with
assured message delivery and time independence.

Java is considered to be the premier programming language for Internet

applications. The MQSeries Client for Java is written in this object-oriented
language. With this software, the user of an internet terminal can become a
true participant in transactions, rather than just a giver and receiver of
information.

VisualAge for Java is the newest member of the IBM VisualAge family. This
development tool helps you to build Java-compatible applications, applets
and JavaBean components. This redbook demonstrates how easy it is to
build graphical user interfaces and internet programs using this powerful
product.

With MQSeries Version 5, IBM delivers the MQSeries bindings for Java.
This software enables you to write Java server applications that use
MQSeries for messaging. This book includes examples on how server
programs make use of the bindings to communicate with clients, other
server programs and the host.

The IMS Bridge is an implementation of Open Transaction Manager Access

(OTMA). It is part of MQSeries for MVS/ESA. This product allows clients to
access IMS applications on the host.

The Team That Wrote This Redbook

This redbook was produced by a team of specialists from around the world
working at the Systems Management and Networking ITSO Center, Raleigh.

 Copyright IBM Corp. 1997 xv

 Frank Brasch is from Munich (Germany) and has been with IBM for 27
years. Since 1997 he has worked in the SW Support MQSeries department.
Before joining the Open Systems Center four years ago, he worked for
about five years in the Education and Research Marketing department in
Munich as a systems engineer for high-end graphics applications on
RS/6000. Prior to that he helped to design, develop and implement the
Directory Assistance System for the German Telekom.

Frank is a co-writer of the redbooks SOMobjects: Management Utilities for

Distributed SOM, GG24-4479 and Internet Application Development with
MQSeries and Java, SC24-4896-0.

Sam Delmer is a systems integrator for IBM Global Services - South and an
MQSeries Certified Specialist. He specializes in bridging SAP to legacy
systems using MQSeries and data interfacing tools. Sam has experience
programming with C, Java, Visual Basic, and Perl and has a background in
UNIX administration. He is currently working on MQSeries design,
development, and implementation for the IBM PCCo SAP project. Sam is
originally from San Antonio, Texas and holds a bachelor′s degree from
Vanderbilt University.

Nobuyuki Ishikawa is a member of Asia Pacific Software Technical Support

in Yamato Laboratory, Japan. He has been providing technical support for
MQSeries in Asia Pacific countries for two years. He has six years of
experience in the networking product development such as LAN bridge,
Wireless LAN and ATM before he joined the current department in 1996. His
areas of expertise include C and C++ programming.

Stanley Tzue-Ing Shieh is a Staff Applications Developer from the VisualAge

for Smalltalk product team in Research Triangle Park, North Carolina. He
has five years of experience in object-oriented programming using Smalltalk
and Java focusing on communications APIs, such as MQSeries, RPC, TCP/IP
and NetBIOS. He has worked at IBM for ten years. His areas of expertise
include National Language Support, DBCS enabling, VSAM programming
and MVS/ESA system programming.

Stanley is a co-writer of the redbook Application Development with

VisualAge for Smalltalk and MQSeries, SG24-2117.

Dieter Wackerow is an Advisory ITSO Specialist for MQSeries at the

Systems Management and Networking ITSO Center, Raleigh, and was the
leader of this project. His areas of expertise include application design and
development for various industries, performance evaluations, capacity
planning, and modelling of computer systems and networks. He also wrote
a simulator for banking hardware and software. He taught classes and has

xvi Connecting to the Internet with MQSeries and VisualAge for Java
 written on performance issues, application development for the banking
industry, and about MQSeries.

Thanks to the following people for their invaluable contributions to this

project:

Linda Robinson
Shawn Walsh
Systems Management and Networking ITSO Center, Raleigh

Grainne Maher
Peter Niblett
Stephen Todd
IBM Hursley, England

Pierangelo Giusta
IBM Italy

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 one of the following ways:
• Fax the evaluation form found in “ITSO Redbook Evaluation” on
page 221 to the fax number shown on the form.
• Use the electronic evaluation form found on the Redbooks Web sites:
For Internet users http://www.redbooks.ibm.com
For IBM Intranet users http://w3.itso.ibm.com
• Send us a note at the following address:
[email protected]

Preface xvii
xviii Connecting to the Internet with MQSeries and VisualAge for Java
Chapter 1. Introduction

This publication provides information resulting from a residency that

explored ways to connect the user of a Web browser to a legacy application
in a mainframe. It discusses Internet browsers and servers, IBM′ s
award-winning middleware MQSeries, the IMS Bridge, and the premier
language for Internet applications, Java.

The project to write this redbook included the newest technology available,
such as MQSeries for Windows Version 5, the MQSeries Client for Java, the
MQSeries Bindings for Java, and VisualAge for Java. The purpose was to
explain how to use these products and to develop some small applications
that use MQSeries over the Internet. The programming language for both
client and server programs was Java. The platform was Windows NT. This
redbook documents the effort of this project. It helps application designers
and developers to get started writing programs with MQSeries and Java.

The programs written for this projects have been tested and perform all
functions required. However, the code is not intended to be state of the art.
The programs are included on a diskette supplied with this book.

1.1 About MQSeries Version 5

MQSeries middleware has earned an industry-leading reputation by
providing a highly reliable, asynchronous communications function for
application-to-application connection. MQ has become essential to
enterprise messaging, covering more than 20 hardware/software platforms
from mainframe to desktop with a single programming interface, allowing
choice and integration of TCP, SNA, NetBIOS, and other protocols in a single
network, while assuring delivery of messages even across temporary
network or system failures. Accessible from most popular programming
languages, MQ can also be used from sophisticated development
environments such as VisualAge for Java, Visual Age Generator, and
through Planetworks′ Interspace from Powerbuilder or Visual Basic.
Sterling Software′s CoolGen (formerly Composer) development also
supports MQSeries asynchronous messaging. Third party support for
MQSeries is very strong, especially in the area of systems management,
including important products from Candle, BMC, Boole & Babbage, and
Tivoli. With over 3,000 customers world-wide in almost every industry, and
with bridges to important environments such as IMS, Lotus Notes, and SAP,
MQSeries is becoming part of the basic fabric of distributed computing.

The latest release of MQSeries is called Version 5, or simply V5. The

following explains the features of the new version.

 Copyright IBM Corp. 1997 1

 MQSeries V5 is ″the next step″ in the evolution of MQSeries enterprise
messaging. The first thing you′ll notice is ″the jump″ from Version 2 to
Version 5. This indicates that MQSeries has ″stepped up″ to the IBM
Software Server standards for product installation, system definition and
operator interface. These changes bring MQSeries into closer integration
with IBM′s DB2, Transaction Server and other Software Server components,
making it simpler to include these products together in an integrated
solution. This entitles MQSeries to join IBM Software Server versioning,
now at V5. Future version levels of MQSeries will correspond to IBM
Software Server versions.

The second thing to notice is that V5 is initially available on five server

platforms. AIX, HP-UX, and Sun Solaris are the three leading suppliers of
UNIX server software today. Windows NT and OS/2 are the primary
Intel-based server operating systems. These 5 platforms are commercially
popular among our MQSeries customers, together with MVS/ESA and
OS/400. Making MQSeries V5 available at the same time on five platforms
should enable many MQSeries installations to make immediate use of the
features of MQSeries V5. MQSeries V5 client support is provided for all five
of the V5 platforms, and also for DOS, Windows 3.1 and Windows 95.

IBM has announced our intention to extend portions of the V5 support to

additional platforms in ways that are appropriate to those platforms. No
dates have been set at this time. Addition of some V5 features to other
platforms will be decided on an individual basis, depending on market
requirements.

MQSeries V5 is interoperable with current and previous releases of

MQSeries on all platforms. V5 queue managers will operate at the
MQSeries V2 level for connections to both V1 and V2 queue managers.

What′s new in MQSeries V5?

There are several feature areas for this new release. MQSeries customers
will be pleased to see that many important ″wish list″ features have been
included. These will enable application and system designers to extend
their use of MQSeries to new and additional types of distributed
applications.
1. Major new functions:
• Database-message resource coordination
• Smart distribution for multicast messages
• Performance boosts for distributed messaging
2. Customer requirements addressed:

2 Connecting to the Internet with MQSeries and VisualAge for Java

 • New programming features including support for very large
messages and files, and use of MQSeries with additional
programming languages
• Communications features to simplify administration, as well as to
provide Novell SPX support.
3. IBM Software Server integration.
4. Administration, problem resolution, and security enhancements,
including optional DCE-based connection security for network
applications.

For more information refer to the following URL on the Internet:

http://www.software.ibm.com/ts/mqseries/v5

1.2 About MQSeries and Java

MQSeries provides an excellent infrastructure for access to enterprise
applications and for development of complex Web applications. A service
request from a Web browser can be queued and processed when possible,
thus allowing a timely response to be sent to the end user regardless of
system loading. By placing this queue close to the user in network terms
then the timeliness of the response is not affected by network loading. In
addition the transactional nature of MQSeries messaging means that a
simple request from the browser can be expanded safely into a sequence of
individual backend processes in a transactional manner.

If your enterprise fits any of the following scenarios, you can gain significant
advantages by using MQSeries Client for Java:
• A medium or large enterprise that is introducing intranet-based
client/server solutions. Here Internet technology provides low-cost easy
access to global communications, while MQ connectivity provides high
integrity with assured delivery and time independence.
• A medium or large enterprise with a need for reliable
business-to-business communications with partner enterprises. Here
again, the Internet provides low-cost easy access to global
communications, while MQ connectivity provides high integrity with
assured delivery and time independence.
• A medium or large enterprise that wishes to provide access from the
public Internet to some of their enterprise applications. Here the
Internet provides global reach at a low cost, while MQ connectivity
provides high integrity through the queuing paradigm. In addition to low
cost, the business can achieve improved customer satisfaction through
24 hour a day availability, fast response, and improved accuracy.

Chapter 1. Introduction 3
 • An Internet Service provider, or other Value Added Network provider,
such as EDI brokers. These companies can exploit the low cost and
easy communications provided by the Internet and add the value of high
integrity provided by MQ connectivity. An Internet Service provider who
exploits MQ can immediately acknowledge receipt of input data from a
Web browser, guarantee delivery, and provide an easy way for the user
of the Web browser to monitor the status of the message.

1.3 About VisualAge for Java

Companies from around the world are beginning to reap the benefits of
extending their enterprise applications to the Web. However, the thought of
application re-writes from scratch is, to say the least, daunting. But with
VisualAge for Java, you can extend your existing applications to the Web
seamlessly -- in less time and with less effort.

VisualAge for Java is the newest member of IBM′s VisualAge family. Its
creation is a clear example of IBM′s total commitment to Java technology
and its continued development. VisualAge for Java is a powerful suite of
application development tools that allows you to build complete 100% Pure
Java applications, applets and JavaBeans by using the award-winning
VisualAge ″Construction from Parts″ paradigm.

The underlying strategy of the VisualAge for Java toolset is twofold:

• To enable you to extend your existing server applications to the Internet,
intranet or extranet (an extension of your intranet to include suppliers),
rather than writing new Web applications from scratch.
• To allow you to easily connect an existing Java solution to a server for
access to data, transactions, or applications.

Combining the power of a true ″Rapid Development Environment″ for Java

with the ease of visual programming, VisualAge for Java connects the thin
Java client to existing server applications. In essence, extending your
business to the web.

VisualAge for Java simplifies your Java development process in four major
ways:
1. Client/server programming in Java is made easier through automatic
generation of JavaBean components and middleware code that connects
the Java client to existing transaction, data and application servers.
2. An intelligent development environment enables your enterprise to build
scalable Java solutions that run on Windows 95, Windows NT, OS/2, AIX,
OS/400, and OS/390.

4 Connecting to the Internet with MQSeries and VisualAge for Java

 3. An automatic version control facility which allows you to easily go back
to a working version of your code. This will be enhanced with a fully
integrated repository-based team environment that encourages simple
and easy collaboration and management of development projects.
VisualAge for Java Enterprise customers will receive a copy of the team
repository when it ships late in 1997.
4. An advanced project-based development environment enables
programmers to create Java applications/applets or JavaBean
components using ″Construction from parts.″
VisualAge for Java application program environment lets you build 100%
Pure Java compatible components that enable your applications to run on
any Java (JDK 1.1 compatible) Virtual Machine or Java-enabled browser.

1.4 About This Book′s Objectives

This book is for designers and programmers who want to write client and
server programs that connect to the Internet. We assume that the reader of
this book knows how to work with some of the products we used in this
project, but not all of them. Therefore, we include brief introductions and
inform from where to get the products and how to install them.

We decided to use VisualAge for Java to develop some client and server
programs. Consequently, we explain for new users how to get started with
this technology. Some advanced Java applets and applications show how to
use the MQSeries Client for Java and the MQSeries Bindings for Java.
Programmers who have written MQSeries programs in C or any other
language will have no difficulties using the new Java classes for MQSeries.

The following chapters describe:

• How to get and install all products used in this project, with the
exception of the software running in the host
• The MQSeries architecture and how to connect clients to servers and
servers to servers, including the host
• How you can learn the MQSeries concepts with the new product
MQFirstSteps
• How to write your first Java applet and application
• How to write your first applet with VisualAge for Java
• How to write client and server methods that use MQSeries
• An applet and a Java application that communicate with an IMS
program using the IMS Bridge supplied with MQSeries for MVS/ESA

Chapter 1. Introduction 5
 The examples are on the diskette supplied with this book.

1.5 About Internet Connections

Figure 1. MQSeries for Windows NT V5

6 Connecting to the Internet with MQSeries and VisualAge for Java

 For this book, we concentrate on Java clients connecting to a PC server
(running Windows NT) and a host. Figure 1 shows the possible connections
and network protocols.

There are several ways to connect a client to a server via the Internet or
intranet and use MQSeries for messaging.

1.5.1 MQSeries Internet Gateway

The Internet Gateway is a program that interfaces with the Web server and
provides information or services on requests from a client program. The
MQSeries Internet Gateway provides a bridge between the synchronous
WWW and asynchronous MQSeries applications. The gateway, Web
browser and MQSeries together provide an Internet-connected Web browser
with access to MQSeries applications.

The gateway acts as a mediator between the HTTP server and MQSeries. It
receives data from the HTTP server and packages it into an MQSeries
message. It then waits for the MQSeries reply message and passes it back
to the HTTP server.

The Common Gateway Interface (CGI) is a standard, supported by almost all

Web servers, that defines how information is exchanged between a Web
server and an external program.

Figure 2. MQSeries Internet Gateway

1.5.1.1 How Does the Gateway Work?

The user requests a certain HTML file from the Web server by specifying a
URL. This HTML file usually contains a form, which the user will fill in and

Chapter 1. Introduction 7
 submit to the server. The Web server is configured to recognize the type of
the data sent by the client and will activate the MQSeries Internet Gateway
programs and pass the data in the form of name value pairs using one of
the defined interfaces, such as the CGI.

The gateway will receive this data and create an MQSeries message and
put it into an MQSeries queue. The names of the queue manager and
queue will be supplied by the HTML form.

A Web-aware MQSeries application will read the queue, get the message,
generate a reply in HTML format and then put it into the reply-to queue.
The gateway reads this queue, gets the message, and passes it to the Web
server, which then sends it to the browser.

For more information refer to the redbook Examples of Using MQSeries on

the WWW , SG24-4882.

1.5.2 MQSeries Client for Java

The MQSeries Client for Java is written in the Java programming language.
You can use the client to write both applets and applications. Applets will
download and run inside a Web browser. Applications are installed on the
client machine. The client for Java connects to a queue manager using
TCP/IP.

Figure 3. MQSeries Client for Java

8 Connecting to the Internet with MQSeries and VisualAge for Java

 A client can only communicate with a queue manager that resides on the
same machine as the Web server from which the applet was downloaded. It
is not possible to communicate with a queue manager running locally to the
browser. Figure 3 illustrates the valid connection. All others cause a
security exception. Remember: Java is secure.

We discuss this product in more detail throughout this book.

1.5.3 MQSeries Bindings for Java

The MQSeries Bindings for Java are language bindings that wrap around C
APIs. The bindings are for writing server-side programs only, that is Java
applications, not Java applets. The programming interface is the same as
the MQSeries Client for Java. Programs written with the bindings will not
download and run inside a Web browser.

Later in this book, we describe some MQSeries server programs that use
the bindings.

1.6 About Connections to the Mainframe

Figure 4 on page 10 illustrates the configuration we used in our project.
The applets run in any browser on any platform and connect via TCP/IP to a
queue manager running in a Windows NT Web server. From there we can
build queue manager to queue manager connections to any other server
and to enterprise systems.

In our case, we send messages to an IMS program via the IMS Bridge, an
MQSeries application. We do not need a server program to do this,
however, we choose to. Since the queue manager in the Web server
machine manages all messages from the clients, it may put them either in a
local queue for processing by a server program, or in a transmission queue
destined for the IMS.

The choice is transparent to the applet programmer. He puts a message on

a queue and does not care about the type. He does not have to know if the
message is processed by a program in the Web server or forwarded to IMS.

Figure 5 on page 10 illustrates the two possibilities. The first message from
the applet for IMS is processed by a program in the server machine (it is
logged to a disk). The second one is put in a transmission queue; and the
queue manager forwards it to the mainframe.

Chapter 1. Introduction 9
Figure 4. Global View of Installed Systems

Figure 5. Connection to IMS

10 Connecting to the Internet with MQSeries and VisualAge for Java

1.7 About Internet Applications
Internet applications are available to a world wide market that is always
open. Everyone can come and participate, buying or selling. Internet
applications are simple to handle; the decisive factor is content.

Today, about 50 million users in about 160 countries are connected with
more than 50,000 networks. By the turn of the century, we may see over 500
million users connected with a million networks generating a billion dollars
worth of transactions or more.

Here are some of the Internet applications preferred today:

• Standard Internet applications
Banking
Electronic commerce
• Extended Internet applications
Applications that include suppliers, retailers, branch offices,
business partners
• Applications with a short life
Configurators
• Applications for many users
Tax returns
• Applications seldom used and for which client code is too costly
Opinion surveys

Demonstration
An order entry application featuring clients connecting to a server
program is desribed in the redbook Internet Application Development
with MQSeries and Java , SG24-4896. The demonstration is available on
the intranet.

Chapter 1. Introduction 11
12 Connecting to the Internet with MQSeries and VisualAge for Java
Chapter 2. Installation

Figure 4 on page 10 gives you a good overall view of the hardware

considered for this MQSeries/Java project. We installed the following
software on the workstations:
1. WWW server
• Windows NT Server Version 4.0 + Service Pack 3
• IBM Internet Connection Secure Server for NT V 4.2.1
• Java SDK 1.1.4
• MQSeries for NT Version 5.0
• MQFirst Version 1.0
• Netscape Navigator 4.03
• VisualAge for Java 1.0
The hardware requirements for this system are:
• A minimum of 48 MB of RAM; recommended RAM is 64 MB
• 48-64 MB of memory can be divided between RAM and a swap file
on a hard disk
• Approximately 300 MB of free disk space
• A mouse or compatible pointing device
• Any communication hardware adapter supported by Windows NT
• A graphic adapter that supports at a minimum 1024x768 pixels with
256 colors.
2. Windows NT workstation
• Windows NT Version 4.0 Workstation
• Java SDK 1.1.4
• Netscape Navigator 4.03
3. OS/2 workstation
• OS/2 Warp Version 4.0
• Netscape Navigator Version 2.02
On the MVS/ESA enterprise system is installed:
• IMS
• MQSeries for MVS/ESA Version 1.2

 Copyright IBM Corp. 1997 13

 In the following sections we describe the installation of some of the software
we used on the workstations and how you can get it from the Internet, if
there are Beta versions or evaluation copies.

2.1 IBM Internet Connection Secure Server

This section describes how to obtain, install and administer the IBM Internet
Connection Secure Server (ICSS) for Windows NT 4.0.

For other operating systems, you have to follow the specific instructions for
that operating system.

2.1.1 How to Get the ICSS

Using a Web browser of your choice, look at the Internet Connection Family
Web page at:
http://www.ics.raleigh.ibm.com
Select Internet Connection Secure Server and in the subsequent page
downloads. This leads you to the web page:
http://www.ics.raleigh.ibm.com/icserver/download.htm
This page is shown in Figure 6 on page 15. Here, select the server for your
operating system.

From here select the Internet Connection Secure Server (Version 4.2.1) for
your operating system and follow the instructions as they appear. You have
to register yourself and then, again, select the file you want to download
from a combo box, such as:
ICSS for Windows NT 4.2.1.3 - US English

This program is packaged as a self-extracting zip file of about 7 MB with the

name NT421EPE_ENU.EXE.

2.1.2 Hardware and Software Requirements

The ICSS runs on any PS/2 or personal computer that can support Windows
NT 3.51 or 4.0 with:
• A mouse or compatible pointing device
• Any communication hardware adapter supported by Windows NT
• A minimum of 12 MB of RAM; recommended RAM is 24 MB
• 12-24 MB of memory that can be divided between RAM and a swap file
on a hard disk
• Approximately 11 MB of free disk space

14 Connecting to the Internet with MQSeries and VisualAge for Java

Figure 6. Internet Connection Server - Web Page

• Microsoft Windows NT or NT-J Server or Client (Workstation) 3.51 or 4.0,

with TCP/IP configured
• A partition formatted using either the NT File System (NTFS), or the File
Allocation Table (FAT)
Note: For better file protection NTFS is recommended.

For SNMP support, install the SystemView Agent Developers Toolkit which
you can download from the IBM software download library.

Chapter 2. Installation 15
 The ICSS provides its own version of the Java servlet classes in the
icsclass.zip file, which is part of the product code you download.

Classpath
To use Java servlet support, the CLASSPATH environment variable must
be set as follows before you install the Internet Connection Secure
Server:

CLASSPATH=C:\java_home_directory\lib\classes.zip

When you install the Internet Connection Secure Server, the installation
program will automatically add the icsclass.zip file to your CLASSPATH
environment variable.

Figure 7. Internet Connection Server - Files

16 Connecting to the Internet with MQSeries and VisualAge for Java

 After you download the self-extracting zip file onto your workstation, run the
executable and specify the directory where you want the files to be
unpacked. Specify the /D parameter to ensure the files unpack into the
correct directories, for example:
nt421epe_enu.exe D:\ICSS421 /D
This unpacks the file to the D:\ICSS421 directory. Additional instructions for
unpacking the files are available in ASCII text format at the WWW download
page.

Figure 7 on page 16 shows the contents of the ICSS421 directory after

nt421epe_enu has been unpacked.

2.1.3 How to Install the ICSS on a Windows NT System

Double-click on the Setup icon on the Icss421 window shown in Figure 7 on
page 16.

Figure 8. Internet Connection Server - Select Components

In the window shown in Figure 8, select the components you want to install.
We chose the Internet Connection Server and the Security Files.

Chapter 2. Installation 17
 NT Service
If you select NT Service, the Internet Connection Secure Server will be
fully integrated with the Windows NT operating system. It will operate
like services that are installed by the operating system itself (such as the
FTP server). We didn′t install this service, because we want to do the
administration from the ICSS panels, as shown later in this chapter.

Figure 9. Internet Connection Server - Choose Target Directory

The window shown in Figure 9 gives you the opportunity to change the
default directory for the ICSS from WWW to anything you like. When you
click on N e x t > , you are presented with two windows that let you:
• Select the ICSS components you want to install
• Overwrite the default directories for the components

To change these paths click on Browse and then select the drive and
directory where you want the ICSS directories installed. Usually, the default
will do fine.

A brief description of the contents of the directories is in Table 1 on

page 19.

18 Connecting to the Internet with MQSeries and VisualAge for Java

 Table 1. ICSS Directories
Directory Contents
\ Adm in Administration directory
This directory contains files used by the Internet
Connection Server Configuration and Administration
Forms.
\Bin Executables directory
The Internet Connection Server executable program files
and other related files are installed in this directory.
\CGI-Bin CGI Bin scripts directory
Into this directory, put your script programs that use the
Common Gateway Interface (CGI). Also, the Internet
Connection Server htimage program is installed in this
directory.
\Docs Documentation directory
This directory contains the online documentation for the
product.
\HTML HTML directory
This directory is for your HTML documents. The Internet
Connection Server sample HTML pages and the Internet
Connection Server Front Page are installed in this
directory.
\Icons Icons and Graphics directory
The default directory list icons are installed here. You may
also choose to put your own icon and graphics files on this
directory.
\Labels Labels directory
Here you can find the label text, if your are writing
diskettes and want to have the correct labels.
\Logs Logs directory
This directory is for log files written by the Internet
Connection Server.
\Servlets\Public Servlets directory
This directory is for the public servlets files.

Click on Next to accept the defaults and to continue with the installation.
You will be presented with the window shown in Figure 10 on page 20 to
configure the Internet Connection Secure Server:

Chapter 2. Installation 19
 Figure 10. Internet Connection Server - Choose Configuration Parameters

In the window shown in Figure 10 you can change the default configuration
parameters. Table 2 explains them.

Table 2 (Page 1 of 2). ICSS Configuration Parameters

Parameter Description
Host Name The default value is the host name defined in your
Settings. If you want to use an alias, change this field to a
fully qualified host name that is defined in your domain
name server.
HTTP Port The default value of 80 is the well-known port number for
Hypertext Transfer Protocol (HTTP). Other port numbers
less than 1024 are reserved for other TCP/IP applications.
Port numbers 8080 and 8008 are commonly used for testing
servers.
SSL Port The port you want your server to listen to for requests for
documents protected by the Secure Sockets Layer (SSL)
protocol. The default is 443.
Key Ring File The name of the file where you want to store public/private
key pairs that the server can use for secure
communications.
The default value is WWW\BIN\keyfile.kyr.

20 Connecting to the Internet with MQSeries and VisualAge for Java

 Table 2 (Page 2 of 2). ICSS Configuration Parameters
Parameter Description
Administrator ID The ID of your server administrator. Anyone attempting to
use the Internet Connection Server Configuration and
Administration Forms will be prompted to enter this ID.
The default is webadmin.
Administrator The password you want to use to protect access to the
Password Configuration and Administration Forms. Anyone
attempting to use the Internet Connection Server
Configuration and Administration forms will be prompted to
enter this password. The default is webibm.

To complete the installation follow these steps:

1. From the Internet Connection Server Installation window, click on Finish
to complete installation. A window will inform you how the installation
progresses.
When the installation procedure finished, you will be prompted to reboot
your system before starting the server.
2. Start your server
From the Start menu, select:
• Programs
• IBM Internet Connection Server
• Internet Connection Secure Export Server
You may minimize the ICS window.
3. Connect to your server:
Use your favorite browser to connect to your server′s front page. Type
the URL http://your.server.name, where your.server.name is the fully
qualified name of your host. Type the host name in one of two ways,
such as:
• http://wtr05176.itso.ral.ibm.com
• http://9.24.104.116

Chapter 2. Installation 21
 Figure 11. Internet Connection Server - Example of a Front Page

The front page contains links that let you:

• Access the configuration and administration forms.
• Create sample home pages.
• Access this Web site (Internet Connection Family).
• Read online Internet Connection Server documentation.

Figure 12 on page 23 shows what the Configuration and Administration

page looks like. From here you can set the different parameters you need to
control your Internet Server individually.
Note: To access this page, you need to enter your user ID and password as
specified in Figure 10 on page 20.

22 Connecting to the Internet with MQSeries and VisualAge for Java

 Figure 12. Internet Connection Server - Configuration and Administration

2.2 Netscape Navigator

If you use Java, you need a Java-enabled browser. For our project, we
used:
• Netscape Navigator for OS/2 Version 2.02
• Netscape Navigator for Windows NT Version 3.01
• Netscape Communicator for Windows, Version 4.03

The Netscape Communicator includes the Host On-Demand feature which

we used to connect to the MVS system.

With the Netscape Navigator you receive Netscape′s HTML-enabled mail

and news applications as well as support for plug-in extensions and frames.
You will also be able to take advantage of JavaScript, incorporated with

Chapter 2. Installation 23
 Netscape Navigator, which extends HTML capabilities and allows you to
open and view live Java applets and applications.

2.2.1 How to Get the Browser

In this section we describe how you can download the Netscape product for
OS/2 and Windows NT, but similar to this, you can also download a browser
for Windows 95 or AIX.

2.2.1.1 How to Find the Navigator for OS/2

• Go to http://www.internet.ibm.com.
• Click on the Downloads tab.
• Search for Netscape.
• Select Netscape Navigator for OS/2 Warp. This brings you to the page:
http://www.internet.ibm.com/browsers/netscape/warp
Download the product and you receive a file of about 4.5 MB named
os2us202.exe.
Note: You need OS/2 Warp Version 4 for Java programs and applets.

2.2.1.2 How to Find the Navigator for Windows NT

• Open the Navigator at http://home.netscape/com.
• Click on Download in the header of the page and follow the links to the
products page.
• Select operating system, language, and product.
You then receive file n32e301p.exe which is about 6 MB.
Note: Executing this file starts the installation process.

2.2.2 How to Install the Browser

In OS/2, create a directory and place the files into it using the following
commands:
c:\>md netscape
c:\>cd netscape
c:\netscape>c:\nsos202
c:\netscape>install
Note: Read the read.me file in the netscape directory.

Click on OK in the Install window. The CONFIG.SYS will automatically be

updated.

24 Connecting to the Internet with MQSeries and VisualAge for Java

 Figure 13. Netscape Navigator Install Window

Click on Install if you accept the drive and directory. A window keeps you
informed about the progress of the installation. When the installation is
completed click on Exit.

In Windows NT, execute the .EXE file you downloaded and the installation
will begin.

2.2.3 How to Set Up the Browser for Java

The windows that let you set up your Netscape Navigator for Java are
different for Windows NT and OS/2.

2.2.3.1 OS/2
Bring up the Netscape Navigator, select Network Preferences from the
Options menu and skip to the third notebook page, Proxies. There, select
Manual Proxy Configuration and then click on View.

This brings up a window in which you type in your SOCKS host. Every
region has its own socks server. We use socks.raleigh.ibm.com. Click on
OK to return to the browser′s window.

Chapter 2. Installation 25
 Since we want to use Java we have to ensure that Java is enabled. Select
Security Preferences from the Options menu. In the subsequent window
remove the check mark from Disable Java then close the window.

You have to include the name of the directory that contains your Java
applets in the CLASSPATH statement or applets will not run. Modify the
CLASSPATH statement in the CONFIG.SYS like this:

SET CLASSPATH=
C:\NETSCAPE\njclass.zip;C:\JAVAOS2\lib\jempcl10.zip;c:\myjava;.\.;

2.2.3.2 Windows NT
Bring up the Netscape Communicator and select Preferences from the Edit
menu. In the Preferences window, you can specify what preference
categories you want to edit.

Click on Advanced and ensure that Java is enabled. Next, click on Proxies,
select Manual proxy configuration, and then click on View. In the
subsequent window, type in the Socks field your socks server. Every region
has its own socks server. We use socks.raleigh.ibm.com. The port is 1080.
Click on OK to return to the browser′s window.

You find the classpath environment variable via the windows My Computer,
Control Panel and System in the System Properties window behind the tab
Environment (see Figure 16 on page 29).

CLASSPATH=
.;C:\IBMJAVA\EAB\RUNTIME\IVJEAB.ZIP;C:\IBMJAVA\EAB\RUNTIME\CICSJGATE.ZIP;

2.3 Java Development Kit (JDK) 1.1.4 from Sun

For our installation, we downloaded the actual version of Sun′s Java
Development Kit, Version 1.1.4. We also downloaded the latest fix for the
Netscape Navigator 4.03 to support JDK 1.1 functions. This download can be
done from the URL:

http://developer.netscape.com.

In a later Version of the Netscape Navigator, this fix should be integrated, so

there may be no need for this download.

26 Connecting to the Internet with MQSeries and VisualAge for Java

 Also, the versions of the JDK are changing frequently, so you may get a
newer version (1.2) at the time you read this redbook. However, the
download and install process should be the same as described here.

Figure 14. JDK 1.1.4 - Download

2.3.1 How to Download the JDK 1.1.4

You can download JDK 1.1.4 from the Internet at the URL:
http://java.sun.com/products/jdk/1.1/index.html

In the Web page shown in Figure 14 select an operating system, click on

Download Software, and follow the instructions.

Download the file jdk114.exe in a directory of your choice, for example,

d:\temp. The file size is about 9 MB. You can also download the file
jdk114doc.exe into the same directory if you want to install the
documentation, too.

Chapter 2. Installation 27
2.3.2 How to Install JDK 1.1.4
Start the installation process with a double-click on the icon of the program
jdk114.exe. This invokes the InstallShield Wizard.

First, you will see a welcome window that is followed by Sun′s license
agreement, and then the window shown in Figure 15. Here you select
which components you want to install.

Figure 15. JDK 1.1.4 - Installation

Make your selections, click on Next, and then follow the instructions until the
installation is finished.

At the end, change your system settings by adding the new JDK directory to
your classpath and path, as shown in Figure 16 on page 29.

CLASSPATH=
... ;C:\jdk1.1.4\bin\classes.zip; ...

28 Connecting to the Internet with MQSeries and VisualAge for Java

 Figure 16. JDK 1.1.4 - Windows NT Classpath Settings

2.4 MQSeries Version 5.0

We installed MQSeries for Windows NT Version 5, which includes the Java
client and the Java bindings.

2.4.1 About MQSeries Version 5.0

There are no Versions 3 and 4 for MQSeries for Windows NT, OS/2, AIX,
HP-UX and Sun Solaris. Version 5 implements characteristics in common
with IBM Software Servers; the new version number 5 is in common with
those other servers.

Chapter 2. Installation 29
 With Version 5, MQSeries installation and administration should be more
familiar to those who have experience with other Software Server
components, reducing training requirements. The new features are:
1. IBM Software Server look and feel is used for installation, definition and
administration of MQSeries.
2. Reliability and serviceability characteristics are now compatible with
IBM Software Server standards.
3. MQSeries publications are provided in HTML format, viewable from a
Web browser.
4. Task guides, similar to wizards, are provided for common administration
tasks.

MQSeries V5 also adds a number of customer requested functions which

will simplify MQSeries installation, systems administration, and problem
resolution.

Serviceability of MQSeries continues to improve. V5 introduces new

functions to enable quicker resolution of problems, and simplify collection of
diagnostic information. Even installation is improved by using the
InstallShield of Windows NT.

• During MQ installation, default objects are automatically created. The

separate execution of MQSC is no longer required.
• MQSC syntax and user interaction are improved for definition of
MQSeries resources and issuing commands.

Some of the new functions of MQSeries Version 5 are:

• Transaction (database) coordination
• Message segmentation
• Message groups
• Distribution lists
• Fast channels
• Improved MQSC utility
• SPX support
• MQSeries Internet Gateway
• MQSeries Client for Java
• MQSeries Bindings for Java

30 Connecting to the Internet with MQSeries and VisualAge for Java

2.4.2 About the MQSeries Client for Java
The MQSeries Client for Java requires Java/JDK 1.1.1 or later. As of the
writing of this book the only browser on the market with full support for Java
1.1.1 is Sun′s Hotjava. The current versions of Netscape Communicator and
Internet Explorer do not have the full 1.1.1 engines and will not work with the
MQSeries Client for Java.

The recommended approach until 1.1.1 supporting browsers become

available is to install the JDK, and use the appletviewer supplied as part of
it to test applets.

A Java 1.02 version of the MQSeries Client for Java is available as support
pack. This version works correctly with all of the popular Java-enabled
browsers on the market.

Refer to 2.5, “MQSeries Client for Java” on page 33 for information on how
to obtain and install the support pack.

2.4.3 How to Install MQSeries Version 5

The following describes the installation of MQSeries for Windows NT Version
5. Inserting the CD-ROM in your system starts the installation process. The
first window you see lets you choose one of the following languages:
• English • Italian
• French • Portuguese
• German • Korean
• Spanish • Simplified Chinese
• Japanese • Traditional Chinese

Select a language (English is the default) and click on N e x t > . Now the
Windows NT InstallShield prepares your system to install the product. Click
on N e x t > until you see the Select Destination Directory window shown in
Figure 17 on page 32.

You can go on with the default values or change the directories by clicking
on the Program... or Data... button at the right side of the Destination
Directory field. There are two entries, one for the program files, the other
for the data files.

Usually, you install into the default directory \MQM. Click on the N e x t >
button to bring up the Choose MQSeries Component window shown in
Figure 18 on page 33.

Here you select what parts of the MQSeries Version 5.0 for Windows NT you
want to install. Clicking on the radio buttons will switch on or off the

Chapter 2. Installation 31
 Figure 17. MQSeries - Select Destination Directory

selected components. You can choose some or all of the following

components:
• MQSeries Server for Windows NT
• MQSeries Clients
• MQSeries Toolkit
• MQSeries On-line Documentation
• MQSeries Bindings for Java (includes Java Client)
• MQSeries Internet Gateway
For all components you need approximately 50 MB of free space on your
hard disk. For our project, we installed all components.

Make your selection, click on the N e x t > button and follow the instructions.
If you accept the defaults displayed in the windows that follow, keep clicking
the N e x t > button until the installation is completed.

In the last window, you are asked if you want to restart your system now or
later. Make a decision and click on the Finish button.
Note: You must reboot your system before you can use MQSeries.

32 Connecting to the Internet with MQSeries and VisualAge for Java

 Figure 18. MQSeries - Select Components

2.5 MQSeries Client for Java

The MQSeries Client for Java is part of MQSeries Version 5. However, this
product requires Java 1.1.1. As noted on page 31, there are currently no
browsers available that support this version. Therefore, you may download
the SupportPac MA83 which requires Java Version 1.02.

The MQSeries Client for Java enables Web browsers and Java applets to
issue calls and queries to MQSeries giving access to mainframe and legacy
applications over the Internet without the need for any other MQSeries code
on the client machine.

2.5.1 How to Get the MQSeries Client for Java

You can obtain a copy of the MQSeries for Client SupportPac MA83 from the
Web page of IBM Hursley:
http://www.hursley.ibm.com/mqseries/txppacs/ma83.html
To find out about other SupportPacs link to:
http://www.hursley.ibm.com/mqseries/txppacs/txpsumm.html
If you work for IBM, you may obtain the product by entering the following
command on the command line of your VM system:

Chapter 2. Installation 33
 TOOLS SENDTO WINVMB TOOLS TXPPACS GET MA83 PACKAGE

If you agree with the IBM International Program License Agreement, you will
receive the file MA83.ZIP (about 500 KB in size).

The code is provided in InfoZip compressed format. To unzip these files you
need a program that understands long file names and can re-create
subdirectories. InfoZip does this. You can download it in the form of a
self-extracting executable from the same Web page as the product. The file
name for OS/2 is UNZ520X2.EXE. File names for other platforms may vary.
Note: This is a self-extracting EXE. Execute UNZ520X2 (if you downloaded
the OS/2 version). This will create the file UNZIP.EXE (and several other
files). Use UNZIP.EXE to unzip MA83.ZIP.
unzip MA83

This creates the following files:

mqc4j.zip The executables for the client
mqc4jdoc.zip The documentation in HTML format
ipla IBM International Program License Agreement
li License Agreement in different languages
readme.txt Notes for the installation
Relnotes.txt Release notes for the SDK version of the product (2.0)

Use the UNZIP.EXE again to unzip the documentation and the executables
for the client.

2.5.2 Installing the Documentation

Unzip the documentation file (mqc4jdoc.zip) into a directory that is
accessible to your Web browser and is on a drive that is capable of
supporting long file names. You can use any unzip utility that can handle
long file names and re-create subdirectories. Examples are WinZip and
Info-Zip′s UnZip. (You cannot use PKUNZIP.)
Note: The MQSeries Client for Java Programmers Guide contains links to
the Java SDK documentation. For these links to be enabled, the MQSeries
Client for Java documentation should be installed in the same directory as
the Java SDK documentation.

Open the index.html file in your Web browser and click on the Getting
started with MQSeries Java link to reach the installation instructions. You
find the index.html file in the subdirectory \doc of the directory where you

34 Connecting to the Internet with MQSeries and VisualAge for Java

Figure 19. MQSeries Client for Java Documentation (index.html)

installed the documentation. Figure 19 on page 35 shows the page

index.html.

Chapter 2. Installation 35
2.5.3 Installing the MQSeries Client for Java
MQSeries Client for Java can be installed either on your local hard disk or
on a Web server. Installation on a Web server has the advantage of
allowing you to download and run MQSeries client applications on machines
that do not have the MQSeries Client for Java installed locally.

The MQSeries Client for Java can be run in three different modes:
• From within any Java-enabled browser
• Using an applet viewer
• As a stand-alone Java program

When running from within a browser, the location of the queue managers
that can be accessed may be constrained by the security restrictions of the
browser being used.

Note: If you use an applet viewer or write stand-alone programs, you must
have the Java Developer′s Kit (JDK) installed on the client machine.

The installation depends on the mode you want to use it in.

2.5.3.1 Using a Web Browser

If you intend to run the client from within a Web browser, you must either:
• Unzip the file on your Web server machine into a directory that is
accessible from your Web browser.
• Unzip the file into a directory on your local machine.

When the mqc4j.zip file is unzipped, some files are placed into the current
directory and some files into a subdirectory called com\ibm\mq.
• The files in the root directory are for the installation verification applet
described in the next section.
• The files in the MQ subdirectory constitute the MQSeries Client for Java.

2.5.3.2 Applet Class Directory

When accessing the client from a Web browser, the applet is run from within
an HTML file. This file contains an applet tag that specifies the class to be
loaded and run. If this applet class is stored in a directory X on the Web
server machine, the Java client files must be stored in a directory
x\com\ibm\mq on the same machine.

36 Connecting to the Internet with MQSeries and VisualAge for Java

 2.5.3.3 Using the Applet Viewer
If you intend to run the client from an applet viewer, you must have the Java
run-time environment installed on your machine.

Unzip the file mqc4j.zip to either:

• Your Web server machine into a directory that is accessible from your
Web browser.
• Into a directory on your local machine.

If you have installed the client on your local machine, you must ensure that
the directory in which you unzipped mqc4j.zip is in your CLASSPATH
environment variable.

2.5.3.4 Setting the CLASSPATH Variable

The Java run-time environment uses a variable called CLASSPATH to locate
the files in the Java client. If this variable is already set on your machine,
you have two choices:
1. Unzip the mqc4j.zip file into a directory that is in your CLASSPATH.
2. Add the directory in which you unzipped the file to the end of your
CLASSPATH statement.

Examples:
• On DOS, OS/2, or Windows use the command:
set CLASSPATH=%CLASSPATH%;new_dir
• On AIX use the command:
export CLASSPATH=$CLASSPATH:new_dir
Where new_dir is the directory in which you have installed the Java client
files.
• On Windows NT you should use the system environment settings

If the CLASSPATH variable is not set, make it point to the directory in which
you unzipped mqc4j.zip and also to the directory that contains
lib\classes.zip from your JDK installation.

2.5.4 Running the Installation Verification Applet

A simple installation verification program is provided as part of the
MQSeries client for Java in a file called mqjavac.htm.

The program connects to a given queue manager, executes all the MQ calls,
and produces simple diagnostic messages in the event of any failures.

Chapter 2. Installation 37
 You find a detailed description and an example in 6.11, “How to Test if the
MQSeries Client for Java Works” on page 145.

2.6 VisualAge for Java Version 1.0

If VisualAge for Java is new to you download the Entry Version from the
Web. This is a scaled down version of the Professional Version and limited
to 100 classes. The Entry Version is sufficient to learn the product and to
run the examples discussed in this book. We installed the Enterprise
Version of VisualAge for Java, and for some testing we also installed the
Entry Version.

2.6.1 VisualAge for Java Entry Version

2.6.1.1 How to Get the Entry Version

To download the Entry Version of VisualAge for Java, go to URL
www.software.ibm.com/ad/vajava
Click on Download the FREE Entry Version. Follow the instructions, fill out
the registration form, agree with the licence agreement and download the
program file wEnty100.zip.

Unzip wEnty100.zip in a directory of your choice, such as vajentry. After the

unzip you should see the following content in that directory.

Figure 20. VisualAge for Java - Install Directory

2.6.1.2 How to Install the Entry Version

The hardware requirements for the Entry Version of VisualAge for Java
follow. These are in addition to the requirements for the other software on
your system.
• Processor: Pentium or compatible processor

38 Connecting to the Internet with MQSeries and VisualAge for Java

 • Display: SVGA, 800 x 600 (1024 x 768 recommended)
• CD-ROM drive
• Mouse or other pointing device
• Memory requirements: 32 MB RAM minimum, 48 MB RAM
recommended
• Disk space requirements:
− 45 MB for the tool, toolkit, samples, and tutorial
− 25 MB for documentation
− 30 MB swap/paging space minimum
Note: This is an unsupported trial version of the product which contains an
Integrated Development Environment (IDE) with a Visual Composition Editor
to help programmers rapidly create graphical Java applets and applications.

Before you install the code, read the INSTALL.TXT file entirely for important
information.

Uninstall Beta
Any Beta versions of VisualAge for Java must be uninstalled prior to
installing the Entry Version.

We installed the Entry Version from the CD-ROM, but the installation
process starting from the downloaded file is the same. Just double-click on
the Setup Icon in the setup directory.

After inserting the CD-ROM the installation process starts automatically with
the following screen (which you will not see when starting the installation
from the downloaded version).
Note: If you are installing from a Web downloaded image then be sure to
create a ″tmp″ directory on a FAT or NTFS drive (not HPFS) and unzip the
Web image to yield the actual install programs (″setup.exe″) will not run
from an HPFS drive with a long file name in its directory.

After reading the installation text select Install VisualAge Java and click on
the Next button. If you agree with the licence agreement the InstallShield
will prepare the installation.

Follow the instructions on the screen. You have the option to change the
name of the installation directory. On the last screen, click on Finish.

Chapter 2. Installation 39
 Figure 21. VisualAge for Java - Install Components

2.6.2 VisualAge for Java Enterprise Version

Only IBM employees can download the Enterprise Version from the Intranet.
The Web address is:
http://w3.torolab.ibm.com/groups/java
The size of the file Entpwin.zip is about 50 MB.

The installation procedure of the Enterprise Version is the same as for the
Entry Version described in 2.6.1.2, “How to Install the Entry Version” on
page 38.

2.6.3 Setting Up VisualAge for Java

Everything you do with VisualAge will be saved on your hard drive.
Sometimes it may be desirable to start all over again with a clean work
space. You can do that if you save the following two files immediately after
installation:
c:\IBMVJava\Ide\program> copy IDE.icx IDEsave.icx
c:\IBMVJava\Ide\repository> copy ivj.dat ivjsave.dat
Note: These files are quite large.

40 Connecting to the Internet with MQSeries and VisualAge for Java

Before you can start developing applications that use MQSeries, you have to
import the MQ classes into your work space. Follow these steps:
1. Start Visual Age for Java.
2. Cancel the VisualAge Quick Start menu, if it appears.
3. In the Workbench window, select Import from the File menu.
4. In the SmartGuide - Type of Import window select Class Files and click
on Browse.
5. In the subsequent VisualAge window, select Java class libraries and
click on OK.
6. In the SmartGuide - Type of Import window, click on Next.
7. In the SmartGuide - Import Files and Directories window, click on
Browse.
8. In the Select files and directories to import window, change ″look in″ to:
c:\mqm\java\lib\com\ibm\MQSERVICES
9. Then select all eight class files and click on OK.
10. In the SmartGuide - Import Files and Directories window, click on Finish.
11. After the MQSERVICES are imported, repeat the above steps to import
the classes from the following directories:
c:\mqm\java\lib\com\ibm\Mqbind
c:\mqm\java\lib\com\ibm\Mq

Warning
Import MQSERVICES first or you get many error messages.

Note: The installation and usage of MQFirst is described in Chapter 4,

“MQFirstSteps for Windows” on page 77.

Chapter 2. Installation 41
42 Connecting to the Internet with MQSeries and VisualAge for Java
Chapter 3. MQSeries Overview

MQSeries is IBM′s award winning middleware for commercial messaging

and queuing. It runs on a variety of platforms. The MQSeries products
enable programs to communicate with each other across a network of
unlike components, such as processors, subsystems, operating systems and
communication protocols. MQSeries programs use a consistent application
program interface (API) across all platforms.

Figure 22. MQSeries at Runtime

Figure 22 shows the parts of an MQSeries application at runtime. Programs

use MQSeries API calls, that is the message queue interface (MQI), to
communicate with a queue manager (MQM), the runtime program of
MQSeries. For the queue manager to do its work, it refers to objects, such
as queues and channels. The queue manager itself is an object as well.

The following sections provide a brief overview of MQSeries, including

clients and servers.

 Copyright IBM Corp. 1997 43

3.1 What Is Messaging and Queuing?
Message queuing is a method of program-to-program communication.
Programs within an application communicate by writing and retrieving
application-specific data (messages) to/from queues, without having a
private, dedicated, logical connection to link them.

Messaging means that programs communicate with each other by sending

data in messages and not by calling each other directly.

Queuing means that programs communicate through queues. Programs

communicating through queues need not be executed concurrently.

With asynchronous messaging, the sending program proceeds with its own
processing without waiting for a reply to its message. In contrast,
synchronous messaging waits for the reply before it resumes processing.

MQSeries is used in a client/server or distributed environment. Programs

belonging to an application can run in one workstation or in different
machines on different platforms.

3.1.1 Messages
A message consists of two parts: data that is sent from one program to
another and a message descriptor. The message descriptor identifies the
message (message ID) and contains control information, also called
attributes, such as message type, expiry time, correlation ID, priority, and
the name of the queue for the reply. In MQSeries Version 5, the maximum
message length is 100 MB. Messages can be segmented and grouped.
MQSeries knows four types of messages:
Datagram A message containing information for which no response is
expected.
Request A message for which a reply is requested.
Reply A reply to a request message.
Report A message that describes an event such as the occurrence of an
error.

Application design determines whether a message must reach its

destination under any circumstances, or if it can be discarded when it
cannot get there in time. MQSeries knows persistent and non-persistent
messages. Delivery of persistent messages is assured. They are written to
logs on a hard drive and survive system failures. Non-persistent messages
cannot be recovered after a system restart.

44 Connecting to the Internet with MQSeries and VisualAge for Java

3.1.2 Queue Manager
The heart of MQSeries is its run-time program, the queue manager (MQM).
Its job is to manage queues of messages. Application programs invoke
functions of the queue manager by issuing API calls. For example, the
MQPUT API puts a message on a queue to be read by another program
using the MQGET API. This scenario is shown in Figure 23.

Figure 23. Program-to-Program Communication - One System

A program may send messages to another program that runs in the same
machine as the queue manager, or to a program that runs in a remote
system, such as a server or a host. The remote system has its own queue
manager with its own queues. This scenario is shown in Figure 24.

Figure 24. Program-to-Program Communication - Two Systems

Application programmers do not need to know where the program to which

they are sending messages runs. They put their message on a queue and
let the queue manager worry about the destination machine and how to get
it there.

Chapter 3. MQSeri es Overvi ew 45

 For the queue manager to do its work, it refers to objects that are defined by
an administrator , usually when the queue manager is created or when a
new application is added. The objects are described in the next section.

The functions of a queue manager can be defined as follows:

• It manages queues of messages for application programs.
• It provides an application programming interface, the Message Queue
Interface (MQI).
Note: The Networking Blueprint identifies three communication styles:
− Common Programming Interface - Communications (CPI-C)
− Remote Procedure Call (RPC)
− Message Queue Interface (MQI)
• It uses networking facilities to transfer messages to another queue
manager when necessary.
• It provides additional functions that allow administrators to create and
delete queues, alter the properties of existing queues, and control the
operation of the queue manager. These functions are invoked through
the utility RUNMQSC, which stands for run MQSeries commands.

MQSeries clients do not have a queue manager of their own. Client

machines connect to a queue manager in a server. This MQM manages the
queues for all clients attached to it.

In contrast to MQSeries clients, each workstation that runs MQSeries for

Windows has its own queue manager and queues. MQSeries for Windows
has a single-user queue manager and is not intended to function as a queue
manager for other MQSeries clients.

3.1.3 MQSeries Objects

This section introduces you to queue manager objects, such as queues and
channels. The queue manager itself is an object, too. Usually, an
administrator creates one or more queue mangers and their objects. A
queue manager can own objects of the following types:
• Queues
• Process definitions
• Channels
The objects are common across different MQSeries platforms. There are
other objects that apply to MVS systems only, such as the buffer pool, PSID,
and storage class.

46 Connecting to the Internet with MQSeries and VisualAge for Java

3.1.3.1 Queues
Message queues are used to store messages sent by programs. There are
local queues that are owned by the local queue manager, and remote
queues that belong to a different queue manager. Queues are described in
more detail in 3.2, “Message Queues” on page 48.

3.1.3.2 Channels
Messages are transmitted via channels. A channel is a logical
communication link. In MQSeries, there are two different kinds of channels:
• Message channel
A message channel connects two queue managers via message channel
agents (MQA). Such a channel is unidirectional. It comprises two
message channel agents (MCA), a sender and a receiver, and a
communication protocol. An MCA is a program that transfers messages
from a transmission queue to a communication link or vice versa. For
bidirectional messaging you have to define two channels, a sender
channel and a receiver channel.
• MQI channel
A Message Queue Interface (MQI) channel connects an MQI client to a
queue manager in a server machine. MQI clients don′t have a queue
manager of their own. An MQI channel is bidirectional.
Figure 29 on page 54 shows the use of both channel types. For more
detailed information refer to the MQSeries Intercommunication .

To transmit non-persistent messages, a message channel can run with two

speeds: fast and normal. Fast channels improve performance, but
messages are lost if there is a channel failure.

A channel can use one of the following transport types:

• SNA LU 6.2
• TCP/IP
• NetBIOS
• SPX

Note: MQSeries for Windows Version 2.1 uses message channels to

connect to other machines. Since this product is designed as a single user
system, it does not support MQI channels. MQSeries for Windows supports
only TCP/IP.

Chapter 3. MQSeri es Overvi ew 47

 3.1.3.3 Process Definitions
A process definition object defines an application to a queue manager. For
example, it contains the name of the program to trigger when a message
arrives.
Note: With MQSeries Version 5, process definitions for channels have been
eliminated.

3.2 Message Queues

Queues are defined as objects belonging to a queue manager. MQSeries
knows a number of different queue types, each with a specific purpose.

3.2.1 Local Queue

A queue is local if it is owned by the queue manager to which the
application program is connected. They are used to store messages for
programs that use the same queue manager. For example, program A and
program B each has a queue for incoming messages and another queue for
outgoing messages. Since the queue manager serves both programs, all
four queues are local.
Note: Both programs do not have to run in the same workstation. Client
workstations usually use a queue manager in a server machine.

3.2.2 Remote Queue

A queue is remote if it is owned by a different queue manager. It is the
local definition of a remote queue. A remote queue definition is associated
with a transmission queue.

Applications do not need to know the location of the remote queue.

Programs write messages to queues. The local queue manager is
responsible for forwarding the messages to the remote queue manager.
Note: A program cannot read messages from a remote queue.

3.2.3 Transmission Queue

A remote queue is associated with a transmission queue. Transmission
queues are local and used as an intermediate step when sending messages
to remote queues.

Typically, there is only one transmission queue for each remote queue
manager (or machine). All messages written to queues owned by a remote
queue manager are actually written to the transmission queue for this
remote queue manager. The messages will then be read from the
transmission queue and sent to the remote queue manager.

48 Connecting to the Internet with MQSeries and VisualAge for Java

 Transmission queues are transparent to the application. They are used
internally by the queue manager.
Note: When a program opens a remote queue, the attributes of the queue
are obtained from the transmission queue. Therefore, the results of a
program writing messages to a queue will be affected by the transmission
queue characteristics.

3.2.4 Dynamic Queue

Such a queue is defined on the fly when the application needs it. Dynamic
queues may be retained by the queue manager or automatically deleted
when the application program ends.

Dynamic queues are local queues. They are often used in conversational
applications, to store intermediate results. Dynamic queues can be:
• Temporary queues that do not survive queue manager restarts
• Permanent queues that do survive queue manager restarts

3.2.5 Model Queue

A model queue is not a real queue. It is a collection of attributes that are
used when a dynamic queue is created.

3.2.6 Alias Queue

Alias queues are not real queues but definitions. They are used to assign
different names to the same physical queue. This allows multiple programs
to work with the same queue, accessing it under different names and with
different definitions.

3.2.7 Initiation Queue

An initiation queue is a local queue to which the queue manager writes a
trigger message when certain conditions are met on another local queue, for
example, when a message is put into an empty message queue. Trigger
messages are read by the trigger monitor, an MQSeries application. The
trigger monitor then starts the application that will process the message.
Note: Applications do not need to be aware of initiation queues, but the
triggering mechanism implemented through them is a powerful tool to
design and write asynchronous applications.

3.2.8 Reply-To Queue

A request message must contain the name of the queue into which the
responding program must put the reply message.

Chapter 3. MQSeri es Overvi ew 49

3.2.9 Dead-Letter Queue
A queue manager must be able to handle situations when it cannot deliver a
message. Here are some examples:
• The destination queue is full.
• The destination queue does not exist.
• Message puts have been inhibited on the destination queue.
• The sender is not authorized to use the destination queue.
• The message is too large.
• The message contains a duplicate message sequence number.

These messages are written by the queue manager to a dead-letter queue.

A dead-letter queue is defined when the queue manager is created. It will
be used as a repository for all messages that cannot be delivered.
Note: From the sender′s point of view, only the remote queue manager can
put messages into a dead-letter queue. Messages that cannot be delivered
by the local queue manager (maybe, because the queue is not defined)
cause an error message.

3.3 Creating a Queue Manager

You may create as many queue managers as you like and have them
running at the same time. One of them should be the default queue
manager. Create a queue manager with the command crtmqm; to make it
the default, specify the parameter /q. The following command creates the
default queue manager MYQMGR:
crtmqm /q MYQMGR
Note: Queue manager names are case-sensitive.

There are some default definitions for objects every queue manager needs.
In MQSeries Version 5, 22 objects are created automatically. The file
AMQSCOMA.TST, supplied with prior versions, does not exist any longer.
Most certainly, you will have to create other objects that pertain to the
applications you run.

The following screen shows how to create a default queue manager with the
name MQNT1. The commands you type are shown in bold.

50 Connecting to the Internet with MQSeries and VisualAge for Java


C:\crtmqm /q MQNT1 
MQSeries queue manager created.
Creating or replacing default objects for MQNT1.
Default objects statistics : 22 created. 0 replaced. 0 failed.
Completing setup.
Setup completed.
 
For each queue manager, a directory is created, such as:
C:\MQM\qmgrs\MQNT1
The directory contains, among other things, the default objects and the
qm.ini file. The objects automatically created for you are:
• Queues:
− SYSTEM.ADMIN.CHANNEL.EVENT
− SYSTEM.ADMIN.COMMAND.QUEUE
− SYSTEM.ADMIN.PERFM.EVENT
− SYSTEM.ADMIN.QMGR.EVENT
− SYSTEM.CHANNEL.INITQ
− SYSTEM.CICS.INITIATION.QUEUE
− SYSTEM.DEAD.LETTER.QUEUE
− SYSTEM.DEFAULT.ALIAS.QUEUE
− SYSTEM.DEFAULT.INITIATION.QUEUE
− SYSTEM.DEFAULT.LOCAL.QUEUE
− SYSTEM.DEFAULT.MODEL.QUEUE
− SYSTEM.DEFAULT.REMOTE.QUEUE
− SYSTEM.MQSC.REPLY.QUEUE
• Process:
− SYSTEM.DEFAULT.PROCESS
• Channels:
− SYSTEM.AUTO.RECEIVER
− SYSTEM.AUTO.SVRCONN
− SYSTEM.DEF.RECEIVER
− SYSTEM.DEF.REQUESTER
− SYSTEM.DEF.SENDER
− SYSTEM.DEF.SERVER
− SYSTEM.DEF.SVRCONN

A dead-letter-queue is not automatically created. To create one when you

create the queue manager, specify it as shown in the following example:
crtmqm /q /u system.dead.letter.queue MQNT1

To start the default queue manager issue the command: strmqm.

Chapter 3. MQSeri es Overvi ew 51

3.4 Manipulating MQM Objects (RUNMQSC)
MQSeries provides the utility RUNMQSC to create and delete queue
manager objects and to manipulate them. The queue manager must be
running when you use the utility. RUNMQSC works in two ways:
• You can type the commands.
• You can create a file containing a list of commands and use this file as
input.

The commands in Figure 25 start the default queue manager and create the
local queue QUEUE1 for it. Another command alters the queue manager
properties by defining a dead letter queue.

[C:\]strmqm
MQSeries queue manager running.

[C:\]runmqsc
84H2001,6539-B42 (C) Copyright IBM Corp. 1994, 1997. ALL RIGHTS RESERVED
Starting MQSeries Commands.

define qlocal(′ QUEUE1′ ) replace descr (′ test queue′ )

1 : define qlocal(′ QUEUE1′ ) replace descr (′ test queue′ )
AMQ8006: MQSeries queue created.
alter qmgr deadq(system.dead.letter.queue)
2 : alter qmgr deadq(system.dead.letter.queue)
AMQ8005: MQSeries queue manager changed.
end
3 : end
2 MQSC commands read.
0 commands have a syntax error.
0 commands cannot be processed.

[C:\]

Figure 25. RUNMQSC - Interactive

To start the utility in an interactive mode, type runmqsc. To end it, type end.
This command is new in Version 5, however, Ctrl+C still works.

Another way to create MQSeries objects is by using an input file instead of

typing the commands. Figure 26 on page 53 shows the command that
processes the input file in Figure 27 on page 53. The response from
RUNMQSC (file a.a) is shown in Figure 28 on page 53.

52 Connecting to the Internet with MQSeries and VisualAge for Java

 [C:\]strmqm
MQSeries queue manager running.

[C:\]runmqsc < mycoma.tst > a.a

[C:\]

Figure 26. RUNMQSC - Using Command File

The input file mycoma.tst contains the following lines. The + indicates that
the command continues on the next line.

****************************************************
* File: MYCOMA.TST
****************************************************

DEFINE QLOCAL(′ QUEUE1′ ) REPLACE +

DESCR(′ Test Queue′ )

Figure 27. RUNMQSC - Input File

The output can appear in the window or can be redirected to a file by

specifying a > followed by a file name. The output for the above file would
look like this:

84H2001,6539-B42 (C) Copyright IBM Corp. 1994, 1997. ALL RIGHTS RESERVED
Starting MQSeries Commands.

: ****************************************************
: * File: MYCOMA.TST
: ****************************************************
:
1 : DEFINE QLOCAL (′ QUEUE1′ ) REPLACE +
: DESCR (′ Test Queue′ )
AMQ8006: MQSeries queue created.
:
1 MQSC commands read.
0 commands have a syntax error.

Figure 28. RUNMQSC - Output File

Chapter 3. MQSeri es Overvi ew 53

3.5 Clients and Servers
MQSeries distinguishes clients and servers. Before you install MQSeries
you have to decide if the workstation will be an MQSeries client, an
MQSeries server, or both. With MQSeries for Windows a new term was
introduced, the leaf node (described on page 55). There are two kinds of
clients:
• Slim client or MQSeries client
• Fat client
Fat clients have a local queue manager; slim clients don′t.

When a slim client cannot connect to its server it cannot work, because
queue manager and queues for a slim client reside in the server. Usually,
an MQSeries client is a slim client. Several of these clients share MQSeries
objects, and the queue manager is one of them, in the server they are
attached to.
Note: The MQSeries Client for Java is a slim client.

In some cases it may be advantageous to have queues in the end user′ s

workstation, especially in a mobile environment. That allows you to run
your application when a connection between client and server does not
(temporarily) exist.

You may install client and server software in the same system and use it as
an end user′s workstation. If your operating system is Windows NT you can
install MQSeries for Windows NT V5.0 or MQSeries for Windows V2.1
(MQWin). If your operating system is Windows 95 use MQWin V2.1. This
product has been designed for end users and uses fewer resources.

The difference between an end user′s workstation that is a client and one
that has a queue manager is the way messages are sent. The queues
reside either in the end user′s workstation or in the server.

Figure 29. MQSeries Channels

54 Connecting to the Internet with MQSeries and VisualAge for Java

 Figure 29 shows the use of MQI and message channels.
• MQI channels connect clients to a queue manager in a server machine.
All MQSeries objects for the client reside in the server. MQI channels
are faster than message channels.
• A message channel connects a queue manager to another queue
manager in another system.
The following summarizes the three workstation types:
MQSeries client
A client workstation does not have a queue manager of its own.
It shares a queue manager in a server with other clients. All
MQSeries objects, such as queues, are in the server. Since the
connection between client and server is synchronous, the
application cannot work when the communication is broken. One
could refer to such workstations as ″slim″ clients.
MQSeries server
A workstation can be a client and a server. A server is an
intermediate node between other nodes. It serves clients that
have no queue manager and manages the message flow
between its clients, itself and other servers.
In addition to the server software you may install the client
software, too. This configuration is used in an application
development environment.
Leaf node
MQSeries for Windows was designed for use by a single user. It
has its own ″small footprint″ queue manager with its own objects.
However, it is not an intermediate node between other nodes. It
is called a leaf node. One could also refer to it as a ″fat″ client.
This product is able to queue outbound messages when
connection to a server or host is not available, and inbound
messages when the appropriate application is not active.

3.6 How MQSeries Works

Figure 30 on page 56 elucidates the parts and architecture of MQSeries.
The application program uses the Message Queue Interface (MQI) to
communicate with the queue manager. The MQI is described in more detail
in 3.9, “The Message Queuing Interface (MQI)” on page 72. The queuing
system consists of the following parts:
• Queue Manager (MQM)
• Listener

Chapter 3. MQSeri es Overvi ew 55

 Figure 30. MQSeries Parts and Logic

• Trigger Monitor
• Channel Initiator
• Message Channel Agent (MCA)

When the application program wants to put a message on a queue it issues

an MQPUT API. This invokes the MQI. The queue manager checks if the
queue referenced in the MQPUT is local or remote. If it is a remote queue,

56 Connecting to the Internet with MQSeries and VisualAge for Java

the message is placed into the transmission (xmit) queue. The queue
manager adds a header that contains information from the remote queue
definition, such as destination queue manager name and destination queue
name.

Each remote queue must be associated with an xmit queue. Usually, all
messages destined for one remote machine use the same xmit queue.

Transmission is done via channels. Channels can be started manually or

automatically. To start a channel automatically, the xmit queue must be
associated with a channel initiation queue. Figure 30 on page 56 shows
that the queue manager puts a message into the xmit queue and another
message into the channel initiation queue. This queue is monitored by the
channel initiator .

The channel initiator is an MQSeries program that must be running in order

to monitor initiation queues. When the channel initiator detects a message
in the initiation queue, it starts the message channel agent (MCA) for the
particular channel. This program moves the message over the network to
the other machine, using the sender part of the uni-directional message
channel pair.

On the receiving end, a listener program must have been started. The
listener, also supplied with MQSeries, monitors a specified port, by default
the port dedicated to MQSeries, 1414. When a message arrives, it starts the
message channel agent . The MCA moves the message into the specified
local queue using the receiver part of the message channel pair.
Note: Both channel definitions, sender and receiver, must have the same
name. For the reply, you need another message channel pair.

The program that processes the incoming message can be started manually
or automatically. To start the program automatically, an initiation queue
and a process must be associated with the local queue, and the trigger
monitor must be running.

When the program shall start automatically, the MCA puts the incoming
message into the local queue and a trigger message into the initiation
queue. This queue is monitored by the trigger monitor. This program
invokes the application program specified in the process definition. The
application issues an MQGET API to retrieve the message from the local
queue.

This scenario is described in more detail in the next section.

Chapter 3. MQSeri es Overvi ew 57

3.7 Communication between Queue Managers
In this section, we discuss what you have to define to send messages to a
queue manager that resides in another system. We use message channels
for communication between queue managers (see Figure 29 on page 54).

Each machine has a queue manager installed and each queue manager
manages several local queues. Messages destined for a remote queue
manager are put into a remote queue . A remote queue is not a real queue;
it is the definition of a local queue in the remote machine. A remote queue
is associated with a transmission (xmit) queue which is a local queue.
Usually, there is one xmit queue for each remote queue manager.

Figure 31. Communication between Two Queue Managers

A transmission queue is associated with a message channel. Message

channels are uni-directional, meaning that you have to define two channels

58 Connecting to the Internet with MQSeries and VisualAge for Java

 for a conversational type of communication. Also, you have to define each
channel twice, once in the system that sends the message (sender channel)
and once in the system that receives the message (receiver channel). Each
channel pair (sender and receiver) must have the same name.

3.7.1 How to Define a Connection between Two Systems

Figure 31 on page 58 shows the required MQSeries objects for connecting
two queue managers. In each system we need:
• A remote queue definition that mirrors the local queue in the receiver
machine and links to a transmission queue (Q1 in system A and Q2 in
system B)

Table 3. MQSeries Objects for MQM-to-MQM Connection

Sender (System A) Receiver (System B)

DEFINE QREMOTE(′ Queue1′ ) REPLACE + DEFINE QLOCAL(′ Queue1′ ) REPLACE +

RNAME(′ Queue1′) + DESCR(′ Messages from system A′ )
RQMNAME(SYSTEMB) +
XMITQ(A.TO.B) +
DESCR(′ Queue 1 in system B′ )

DEFINE QLOCAL(A.TO.B) REPLACE +

USAGE(xmitq) +
DESCR(′ Xmit Queue′ )

DEFINE CHANNEL(A.TO.B) + DEFINE CHANNEL(A.TO.B) +

CHLTYPE(sdr) REPLACE + CHLTYPE(rcvr) REPLACE +
TRPTYPE(tcp) CONNAME(9.24.104.116) + TRPTYPE(tcp) +
XMITQ(A.TO.B) + DESCR(′ Receiver channel from A to B′ )
DESCR(′ Sender channel from A to B′ )

DEFINE QLOCAL(′ Queue2′ ) REPLACE + DEFINE QREMOTE(′ Queue2′ ) REPLACE +

DESCR(′ Messages from system B′ ) RNAME(′ Queue2′) +
RQMNAME(SystemA) +
XMITQ(B.TO.A) +
DESCR(′ Queue 2 in system A′ )

DEFINE QLOCAL(B.TO.A) REPLACE +

USAGE(xmitq) +
DESCR(′ Xmit queue′ )

DEFINE CHANNEL(B.TO.A) + DEFINE CHANNEL(B.TO.A) +

CHLTYPE(rcvr) REPLACE + CHLTYPE(sdr) REPLACE +
TRPTYPE(tcp) + TRPTYPE(tcp) CONNAME(WTR5317) +
DESCR(′ Receiver channel from B to A′ ) XMITQ(B.TO.A) +
DESCR(′ Sender channel from B to A′ )

File Name: SytemA.tst File Name: SystemB.tst

Chapter 3. MQSeri es Overvi ew 59

 • A transmission queue that holds all messages destined for the remote
system until the channel transmits them (A.TO.B in system A and
B.TO.A in system B)
• A sender channel that gets messages from the xmit queue and
transmits them to the other system using the existing network (A.TO.B in
system A and B.TO.A in system B)
• A receiver channel that receives messages and puts them into a local
queue (B.TO.A in system A and A.TO.B in system B)
• A local queue from which the program gets its messages (Q2 in system
A and Q1 in system B)

In each system, you must define the appropriate queue manager objects.
The objects are defined in the two .tst files shown in Table 3 on page 59.

3.7.2 How to Start Communication Manually

First, the objects have to be known to the queue managers. Use RUNMQSC
to create the objects. Make sure that the queue manager is running.

Next, start the listeners and the channels. You need to start only the sender
channel in each system. MQSeries starts the receiver.

Table 4 shows the commands to create the objects and to start

communication.

Table 4. Start MQM-to-MQM Connection

Sender (System A) Receiver (System B)
Do the following only once.

strmqm SYSTEMA strmqm SYSTEMB

runmqsc < systema.tst > a.a runmqsc < systemb.tst > a.a

Do this every time when you establish connection.

strmqm SYSTEMA strmqm SYSTEMB

start runmqlsr -t tcp start runmqlsr -t tcp
runmqsc runmqsc
start channel(A.TO.B) start channel(B.TO.A)
Ctrl+C Ctrl+C

Now start the applications in both systems.

Note: If you use the default queue manager you may omit the queue manager
name (SYSTEMA and SYSTEMB) in the strmqm commands.

60 Connecting to the Internet with MQSeries and VisualAge for Java

 In this scenario, you start the channels manually, and the application, too.
In the next section, we show how to start channels automatically.

3.7.3 How to Start Channels Automatically

You can use the channel initiator to start channels. Instead of the
commands shown in Table 4 on page 60 enter the following commands in
both systems:
start runmqlsr -t tcp
start runmqchi
With the first command you start the listener and with the second the
channel initiator program. The channel initiator monitors a channel
initiation queue and starts the proper channel to read in the message. The
default initiation queue is SYSTEM.CHANNEL.INITQ.

You may also start the channel initiator from RUNMQSC. The command is:
start chinit
--OR--
start chinit initq(SYSTEM.CHANNEL.INITQ)

Table 5 shows the xmit queue definitions that start the channels
automatically.

Table 5. MQSeries Definitions to Start Channels

Sender (System A) Receiver (System B)
.. ..
. .
DEFINE QLOCAL(A.TO.B) REPLACE + DEFINE QLOCAL(B.TO.A) REPLACE +
USAGE(xmitq) + USAGE(xmitq) +
TRIGGER TRIGTYPE(every) + TRIGGER TRIGTYPE(every) +
INITQ(SYSTEM.CHANNEL.INITQ) + INITQ(SYSTEM.CHANNEL.INITQ) +
DESCR(′ Xmit Queue′ ) DESCR(′ Xmit queue′ )

Figure 32 on page 62 shows that the queue manager can trigger the
process that starts the channel program in three ways:
• When the first message is put into the transmission queue
• Every time a message is put into the xmit queue
• When the queue contains a specified number of messages

Chapter 3. MQSeri es Overvi ew 61

 Figure 32. Triggering Channels

In order to trigger the channels you have to modify the .tst files shown in
Table 3 on page 59. The changes are shown in bold.

Since messages are placed into the xmit queue sporadically, we trigger the
channel every time a message arrives. We use the default initiation queue
for the trigger message.

3.7.4 How to Start Applications Automatically

This section describes how to trigger an application program that runs in
the server machine. Both triggering and triggered applications can run in
the same machine or in different machines.

Figure 33 on page 63 elucidates what happens when a message arrives

from another system. The application program that has to process the
message can be started manually from the command line or as part of the
startup sequence. Another way is to let the queue manager start it when it
is needed, that is, using the MQSeries triggering mechanism.

In this example, the listener program monitors the port assigned to

MQSeries, 1414, and invokes the message channel agent (MCA) when a
message has arrived. The message is moved into the appropriate local
queue (specified in the message header) and a trigger message is put into
an initiation queue.

62 Connecting to the Internet with MQSeries and VisualAge for Java

 The trigger monitor monitors the initiation (trigger) queue and starts the
program. The program name is specified in the process. The program then
gets the message off the queue.

The next sections describe the MQSeries objects and API sequences in both
sender and receiver systems.

Figure 33. Triggering Applications

3.7.5 How to Test if the Queue Manager Is Working

After you install MQSeries on the server you may want to check if the
installation has been successful. You can do that with sample programs
provided with MQSeries. They are in the directory:
c:\mqm\tools\c\samples\bin
• AMQSPUT puts messages on a queue.
• AMQSGET gets messages from a queue.
You may use one of the default queues when you run the sample programs.
Type the commands shown in bold in Figure 34 on page 64.
• After AMQSPUT is started type a few messages and then press Enter
twice to end it.
• AMQSGET times out after a few seconds.

Chapter 3. MQSeri es Overvi ew 63

 [C:\]strmqm
MQSeries queue manager started.
[C:\]cd mqm\tools\c\samples\bin
[C:\mqm\tools\c\samples\bin]amqsput SYSTEM.DEFAULT.LOCAL.QUEUE
Sample AMQSPUT0 start
target queue is SYSTEM.DEFAULT.LOCAL.QUEUE
111111
222222
333333
<--- 2 x Enter ends AMQSPUT
Sample AMQSPUT0 end

[C:\mqm\tools\c\samples\bin]amqsget SYSTEM.DEFAULT.LOCAL.QUEUE
Sample AMQSGET0 start
message <111111>
message <222222>
message <333333>
no more messages <--- Wait for time out
Sample AMQSGET0 end

[C:\mqm\tools\c\samples\bin]endmqm /i MYQMGR
MQSeries queue manager ending.
MQSeries queue manager ended.

[C:\mqm\tools\c\samples\bin]

Figure 34. Testing the Queue Manager

3.8 Communication between Client and Server

In this section, we discuss what you have to do to define and test the
connection between an MQ client and its MQ server. A more detailed
description is provided in publication MQSeries Clients , GC33-1632.

3.8.1 How to Define a Client/Server Connection

The following describes MQM objects and other definitions needed for a
client/server connection. You have to know the transmission protocol (for
example, TCP/IP) and the addresses of the systems you want to connect,
such as:
• 9.24.104.206 for the server
• 9.24.104.116 for the client

64 Connecting to the Internet with MQSeries and VisualAge for Java

Figure 35. Client/Server Connection

3.8.1.1 Definition in the Server

Define the queues that the application needs and a channel of the type
server connection. The queue manager definitions are in the file
javacoma.tst, shown in Figure 36.

********************************************************************/
* File: JAVACOMA.TST */
********************************************************************/

DEFINE QLOCAL(′ JAVAQ1′ ) REPLACE +

DESCR(′ Queue for Java Application′ )

DEFINE CHANNEL(′ JAVACH1′ ) CHLTYPE(SVRCONN) REPLACE +

TRPTYPE(TCP) MCAUSER(′ ′ )

Figure 36. Definitions for Server Connection

Chapter 3. MQSeri es Overvi ew 65

 We define a queue for the application to put messages in and an MQI
channel of the type server connection. Create the objects by issuing the
command:
runmqsc < javacoma.tst > a.a

3.8.1.2 Definitions in the Client

Define an environment variable for the MQSeries client that defines the
connection on the client side. Set the variable with the following command
or place the command in the CONFIG.SYS.
set MQSERVER=JAVACH1/TCP/9.24.104.206(1414)

Notes:
1. MQSERVER is the name of the environment variable.
2. JAVACH1 is the name of the channel to be used for communication
between client and server. The channel must be defined in the server.
3. TCP denotes that TCP/IP is to be used to connect to the machine with
the address following the parameter.
4. (1414) is the default port number for MQSeries. You may omit this
parameter if the listener on the server side uses this default, too.

Java Client: For the MQSeries Client for Java, the environment variables are
set in the applet code. An applet can run in any machine, such as a
network station, and it has no access to a disk drive in the workstation. :
The example below shows what statements to include in your Java program:
import com.ibm.mq.*;
..
.
MQEnvironment.hostname = ″9.24.104.456″;
MQEnvironment.channel = ″JAVACH1″ ;
MQEnvironment.port = 1414;
..
.

3.8.2 How to Start a Client/Server Connection

Before you can start the application in the client you have to start a program
in the server that listens to the communication link between client and
server. MQSeries provides a program that does just that, the listener called
runmqlsr.

You start the listener with the following command:

start runmqlsr /t tcp /m JAVAMQM /p 1414

66 Connecting to the Internet with MQSeries and VisualAge for Java

 Notes:
1. start creates a new window for the listener.
2. runmqlsr is the name of the listener program.
3. /t tcp defines that there is a TCP/IP connection between client and
server.
4. /m JAVAMQM specifies the name of the queue manager the client connects
to. If omitted, the default queue manager is used.
5. /p 1414 defines the TCP/IP port number. 1414 is the default assigned to
MQSeries applications; hence, you may omit this parameter.
The server is now ready to process MQI calls from the application running
in the client.

3.8.3 How to Test a Client/Server Connection

With the steps described above communication between client and server is
established. You can test the connection using programs provided with
MQSeries. They are in the directory:
c:\mqm\tools\c\samples\bin
• AMQSPUTC puts messages on a queue.
• AMQSGETC gets messages from a queue.
Note: The ″C″ stands for client.

On the server machine, execute the following commands:

strmqm
start runmqlsr -t tcp

On the client machine, type the commands shown in bold in Figure 37 on

page 68.
• After AMQSPUTC is started type a few messages and then press Enter
twice to end it.
• AMQSGETC times out after a few seconds.

Chapter 3. MQSeri es Overvi ew 67

 [C:\mqm\tools\c\samples\bin]amqsputc JAVAQ1
Sample AMQSPUT0 start
target queue is JAVAQ1
111111
222222
333333
<--- 2 x Enter ends AMQSPUTC
Sample AMQSPUT0 end

[C:\mqm\tools\c\samples\bin]amqsgetc JAVAQ1
Sample AMQSGET0 start
message <111111>
message <222222>
message <333333>
no more messages <--- Wait for time out
Sample AMQSGET0 end

[C:\mqm\tools\c\samples\bin]

Figure 37. Testing Client/Server Connection

On the server machine, you see the following listener window after
completion of the two programs:


RUNMQLSR.EXE

11/19/96 14:54:10 Channel program started

11/19/96 14:54:28 Channel program ended normally
11/19/96 14:55:20 Channel program started
11/19/96 14:55:49 Channel program ended normally
 
Figure 38. Listener Window (RUNMQLSR)

3.8.4 How a Client/Server Connection Works

This section describes how to trigger an application program that runs in
the server machine. Since there are MQI channels of the type server
connection between clients and server, all clients use the queue manager in
the server machine. When a client puts a message on a queue it has to be
read and processed by some program. This program can be started when
the server starts or the queue manager starts it when it is needed, that is
using the MQSeries triggering mechanism.

68 Connecting to the Internet with MQSeries and VisualAge for Java

Figure 39. Clients and Server

Figure 39 shows two clients connected to a server. Both clients request

services from the same program (Appl S1). Since that application runs in
the same system as the queue manager, we have only local queues. Some
queues are specifically for a particular client, for example, QA1 is the reply
queue for client A and QA2 is the reply queue for client B. Other queues
are used by both clients and server. For example, QS1 is used as output
queue for both clients and as input queue for the server program.

The next sections describe the MQSeries objects and API sequences in both
client and server.

Chapter 3. MQSeri es Overvi ew 69

 3.8.4.1 How a Client Sends a Request
The client starts a program that puts a message on a queue. For this
function five MQSeries API calls are executed:
• MQCONN connects to the queue manager in the server.
• MQOPEN opens the message queue for output (QS1).
• MQPUT puts the message on the queue.
• MQCLOSE closes the queue (QS1).
• MQDISC disconnects from the queue manager (JAVAMQM).

Of course, the program can put many message in the queue before it closes
it and disconnects. Closing the queue and disconnecting from the queue
manager could be done when the application ends.

The MQSeries client code that runs in the client machine processes the API
calls and routes them to the machine defined in the environment variable,
such as:
set MQSERVER=JAVACH1/TCP/9.24.1104.206

3.8.4.2 How the Server Receives a Request

In the server machine, the following queue manager objects are needed:
• A channel, JAVACH1, of the type server connection.
• A local queue, QS1, into which the clients put their messages.
• An initiation queue into which the queue manager puts a trigger
message when a request for queue QS1 has arrived. We use the default
initiation queue.
• A process definition, process.S1, that contains the name of the program
to be started when the trigger event occurs (S1).
• One or more queues in which the program puts the reply messages
(QA1 and QB1).

The definitions for the objects are shown in Figure 40 on page 71.

In the server machine, two programs have to be started:

• The listener with the command runmqlsr /t tcp
• The trigger monitor with the command start runmqtrm
The listener listens for messages on the channel and puts them on the
queue QS1. Since QS1 is triggered, the MQM puts a trigger message on the
trigger queue each time a message is put on QS1. When a message is

70 Connecting to the Internet with MQSeries and VisualAge for Java

 DEFINE CHANNEL(′ JAVACH1′ ) CHLTYPE(SVRCONN) REPLACE +
TRPTYPE(TCP) MCAUSER(′ ′ )

DEFINE QLOCAL(′ QS1′ ) REPLACE +

DESCR(′ Queue for Server Application′) +
TRIGTYPE(EVERY) +
TRIGGER INITQ (system.default.initiation.queue) +
PROCESS (process.S1)

DEFINE PROCESS(process.S1) REPLACE +

DESCR(′ Process to start server program′) +
APPLTYPE (OS2) +
APPLICID(′ c:\mqtest\s1.exe′ )

DEFINE QLOCAL(′ QA1′ ) REPLACE +

DESCR(′ Reply queue for client A′ )

DEFINE QLOCAL(′ QB1′ ) REPLACE +

DESCR(′ Reply queue for client B′ )

Figure 40. Definitions for Two Clients and Server

placed on the trigger queue, the trigger monitor starts the program defined
in the process.

The server program S1 connects to the queue manager, opens the queue
QS1 and issues an MQGET to read the message.

3.8.4.3 How the Server Sends a Reply

After processing the request it puts the reply in the reply queue for the
client. To do this it has to open the output queue (QA1 or QB1) and issue
an MQPUT.

Since several clients use the same server application, it is advisable to give
the server a ″return address,″ that is, the names of the queue and the queue
manager that will receive the reply message. These fields are in the header
of the request message, containing the reply-to-queue manager and
reply-to-queue (here, QA1 or QB1). It is the responsibility of the client
program to specify these values.

Usually, the server program stays active and waits for more messages, at
least for a certain time. For how long can be specified in the wait option of
the MQGET API.

Chapter 3. MQSeri es Overvi ew 71

 3.8.4.4 How the Client Receives a Reply
The client program knows the name of its input queue, here QA1 or QB1.
The application can use two modes of communication:
• Conversational
If the application uses this mode of communication with the server
program, it waits for the message to arrive before it continues
processing. This means, the reply queue is open and an MQGET with
wait option has been issued.
The client application must be able to deal with two possibilities:
− The message arrives in time.
− The timer expires and no message is there.
• True asynchronous
When using this mode, the client does not care when the request
message arrives. Usually, the user clicks on a push button in a menu
window to activate a program that checks the reply queue for messages.
If a message is present, this or another program can process the reply.

3.9 The Message Queuing Interface (MQI)

A program talks directly to its local queue manager. It resides in the same
processor or domain (for clients) as the program itself. The program uses
the Message Queuing Interface (MQI). The MQI is a set of API calls that
request services from the queue manager.
Note: When the connection between a client and its server is broken, no
APIs can be executed, since all objects reside in the server.

There are 13 APIs. The most important ones are:

MQPUT Put a message on a queue.
MQGET Get a message from a queue.

The other calls are used less frequently:

MQCONN Establishes connection with a queue manager using the
standard bindings.
MQCONNX Establish connection with a queue manager using fastpath
bindings. Fastpath puts and gets are faster, but the application
must be well behaved. Application and queue manager run in
the same process. When the application crashes it takes the
queue manager down with it. This API call is new in MQSeries
Version 5.

72 Connecting to the Internet with MQSeries and VisualAge for Java

 MQBEGIN This API begins a unit of work that is coordinated by the queue
manager, and that may involve external XA compliant resource
managers. This API has been introduced with MQSeries
Version 5. It is used to coordinate MQ and DB2 transactions.
MQOPEN Open or obtain access to a queue.
MQCLOSE Close a queue.
MQDISC Disconnect from the queue manager.
MQPUT1 Open a queue, put a message on it and close the queue. This
is a combination of MQOPEN, MQPUT and MQCLOSE.
MQINQ Request information about the queue manager or one of its
objects, such as the number of messages in a queue.
MQSET Change some attributes of a queue.
MQCMIT A syncpoint has been reached. Messages put as part of a unit
of work are made available to other applications. Messages
retrieved as part of a unit of work are deleted.
MQBACK The queue manager has to back out all message puts and gets
that have occurred since the last syncpoint. Messages put as
part of a unit of work are deleted. Messages retrieved as part
of a unit of work are reinstated on the queue.

3.9.1 A Code Fragment

The code fragment in Figure 41 on page 74 shows the APIs to put a
message on one queue and get the reply from another queue.
Note: The fields CompCode and Reason will contain completion codes for
the APIs. You can find them in the Application Programming Reference .
1 This statement connects the application to the queue manager with the
name MYQMGR. If the parameter QMName does not contain a name,
then the default queue manager is used. MQ stores in the variable
HCon the handle of the queue manager. This handle must be used in
all subsequent APIs.
2 To open a queue the queue name must be moved into the object
descriptor that will be used for that queue. This statement opens
QUEUE1 for output only (open option MQOO_OUTPUT). Returned are
the handle to the queue and values in the object descriptor. The handle
Hobj1 must be specified in the MQPUT.

Chapter 3. MQSeri es Overvi ew 73

 MQHCONN HCon; // Connection handle
MQHOBJ HObj1; // Object handle for queue 1
MQHOBJ HObj2; // Object handle for queue 2
MQLONG CompCode, Reason; // Return codes
MQLONG options;
..
.
MQOD od1 = {MQOD_DEFAULT}; // Object descriptor for queue 1
MQOD od2 = {MQOD_DEFAULT}; // Object descriptor for queue 2
MQMD md = {MQMD_DEFAULT}; // Message descriptor
MQPMO pmo = {MQPMO_DEFAULT}; // Put message options
MQGMO gmo = {MQPMO_DEFAULT}; // Get message options
..
.
// 1 Connect application to a queue manager.
strcpy (QMName,″MYQMGR″ ) ;
MQCONN (QMName, &HCon, &CompCode, &Reason);

// 2 Open a queue for output

strcpy (od1.ObjectName,″QUEUE1″ ) ;
MQOPEN (HCon,&od1, MQOO_OUTPUT, &Hobj1, &CompCode, &Reason);

// 3 Put a message on the queue

MQPUT (HCon, Hobj1, &md, &pmo, 100, &buffer, &CompCode, &Reason);

// 4 Close the output queue

MQCLOSE (HCon, &Hobj1, MQCO_NONE, &CompCode, &Reason);

// 5 Open input queue

options = MQOO_INPUT_AS_Q_DEF;
strcpy (od2.ObjectName, ″QUEUE2″ ) ;
MQOPEN (HCon, &od2, options, &Hobj2, &CompCode, &Reason);

// 6 Get message

gmo.Options = MQGMO_NO_WAIT;
buflen = sizeof(buffer - 1);
memcpy (md.MsgId, MQMI_NONE, sizeof(md.MsgId);
memset (md.CorrelId, 0x00, sizeof(MQBYTE24));
MQGET (HCon, Hobj2, &md, &gmo, buflen, buffer, 100, &CompCode, &Reason);

// 7 Close the input queue

options = 0;
MQCLOSE (HCon, &Hobj2,options, &CompCode, &Reason);

// 8 Disconnect from queue manager

MQDISC (HCon, &CompCode, &Reason);

Figure 41. Fragments of an MQSeries Program

74 Connecting to the Internet with MQSeries and VisualAge for Java

3 MQPUT places the message assembled in a buffer on a queue.
Parameters for MQPUT are:
• The handle of the queue manager (from MQCONN)
• The handle of the queue (from MQOPEN)
• The message descriptor
• A structure containing options for the put (refer to the Application
Programming Reference )
• The message length
• The buffer containing the data

4 This statement closes the output queue. Since the queue is predefined
no close processing takes place (MQOC_NONE).
5 This statement opens QUEUE2 for input only using the queue-defined
defaults. You could also open a queue for browsing, meaning that the
message will not be removed.
6 For the get, the nowait option is used. The MQGET needs the length of
the buffer as input parameter. Since there is no message ID or
correlation ID specified, the first message from the queue is read.
You may specify a wait interval (in milliseconds) here. You can check
the return code to find out if the time has expired and no message
arrived.
7 This statement closes the input queue.
8 The application disconnects from the queue manager.

Communication between programs is time-independent . The sender can

continue processing without waiting for a reply. The receiving program
does not even have to run. MQSeries holds the messages until it is ready
to process them.

MQSeries applications are message-driven . The arrival of a message

triggers an event. Just like clicking on a push button in a GUI invokes some
procedure, a message starts a program that processes the message data.

Chapter 3. MQSeri es Overvi ew 75

76 Connecting to the Internet with MQSeries and VisualAge for Java
Chapter 4. MQFirstSteps for Windows

There is now an easy way to learn MQSeries, to check if an MQSeries

installation was successful, and to test the connection between two queue
managers.

MQFirstSteps for Windows (MQFirst) is a new product. The application is

written in Visual Basic and is available on the Internet as a technology
demonstration. As of the writing of this book it is available as a Beta
version.

MQFirst introduces MQSeries, by letting you learn MQSeries concepts and

explore MQSeries messaging before needing to learn any commands.

MQFirst is aimed at any user who is new to MQSeries, or is teaching others

about MQSeries. Users can include application developers, system
administrators, technology evaluators, and system designers.

4.1 About MQFirstSteps for Windows

Using MQSeries, MQFirst demonstrates how you can exchange messages
between two or more MQFirst applications running on the same workstation
or on different workstations.

To demonstrate the exchange of messages, MQFirst automatically

configures MQSeries objects - yes it does the hard work for you. It explains
each configuration as it takes place so that you can learn about the
terminology and concepts involved. It couldn′t be easier.

To help you understand the overall configuration, it also provides you with
an interactive diagram that identifies each object it configures. MQFirst
uses MQI calls and MQSeries commands to configure the objects. You can
view these commands at any time, and save them in a file for future use.

Finally, MQFirst leads the way for further learning about MQSeries
depending on your needs.

4.2 What You Need to Use it

Before starting MQFirst, we recommend you have the following:
1. Two workstations running any combination of the following MQSeries
products:
• MQSeries for Windows NT V2.0.1

 Copyright IBM Corp. 1997 77

 • MQSeries for Windows NT V5
• MQSeries for Windows V2.1 (free trial version on the WWW)
2. A TCP/IP network which connects the machines running MQSeries
As a minimum, you must have one workstation with either of the following
MQSeries products:
• MQSeries for Windows NT V2.0.1
• MQSeries for Windows NT V5
• MQSeries for Windows V2.1

4.3 How to Get MQFirstSteps for Windows

Download MQFirstSteps from the Internet. The URL is:
http://www/software.ibm.com/ts/mqseries/beta/mqfirst

Before downloading MQFirst, you must complete and submit a registration

form. This will be presented to you when you click on Download at the
bottom of the Web page.

The file you download is mqfirst.zip and needs about 2.7 MB.

4.4 How to Install MQFirstSteps for Windows

To install MQFirst onto a hard drive:
1. Prepare a hard disk directory for the installation files.
2. Copy mqfirst.zip to the prepared directory.
3. Unzip mqfirst.zip using InfoZip′ s Unzip using the following command:
unzip mqfirst.zip
This creates a directory called mqfirst, and places two zip files (disk1.zip
and disk2.zip) within it.
4. Make the hard disk directory (mqfirst) current, and run the command:
unzip disk1.zip
The directory disk1 is created, and the files are extracted into it.
5. Do likewise for disk2.zip.
6. Delete mqfirst.zip, disk1.zip and disk2.zip.
7. Make disk1 the current directory and run setup.
8. Follow the online instructions.

78 Connecting to the Internet with MQSeries and VisualAge for Java

 To install MQFirst onto floppy disks:
1. Prepare and label two 1.44 M B floppy diskettes. Label diskette 1 as
MQFDSK1 and label diskette 2 as MQFDSK2.
2. Follow the instructions for the hard drive installation steps 1, 2 and 3.
3. Copy disk1.zip to the diskette labelled MQFDSK1 and disk2.zip to the
diskette labelled MQFDSK2.
4. To use the diskettes to install MQFirst, copy the zip files to a prepared
hard drive, and then unzip them and run setup as described in steps 4-8
on the previous page.

Figure 42. MQFirst - Installation

4.5 How to Use MQFirstSteps for Windows

With MQFirst you can test the correct installation of MQSeries on one
system, that means the system your are sitting in front of, or on two
systems. If you want to work with two systems then you have to install
MQSeries and MQFirst on both systems. Refer to 4.4, “How to Install
MQFirstSteps for Windows” on page 78 on how to install the product.

To run the program, click on Start, then on Programs and then on MQSeries
FirstSteps for Windows.

Chapter 4. MQFirstSteps for Windows 79

 Figure 43. MQFirst - Welcome Window

MQFirst presents a welcome window, which lets you choose between two
options:
• Click on Guide Me when MQSeries is new to you.
• Click on Quick Start to quickly configure an MQSeries system.

Stop Queue Manager

Make sure that no queue manager is running when you run MQFirst.

4.5.1 MQFirst Guided Tour

The guided tour presents you with nine windows that lead you through the
application.

On the bottom of each window is a message area. You specify what kind of
status messages you want to see:
• Messages displayed by the application (MQFirst)
• Messages related to MQI calls
• Messages from the MQSC utility
• All messages
The first messages appear in the fifth window.

80 Connecting to the Internet with MQSeries and VisualAge for Java

Step through the guided tour by clicking on the Next button. Read the text
displayed in the windows and, if needed, key in some information.

The first four windows tell you about some MQSeries basics and how to
proceed with the guided tour.

On page four, MQFirst tells you that it needs a queue manager to connect
to. It uses the machine name as queue manager name. You cannot change
the name.

Click on Next and MQFirst tries to connect to the queue manager. If it does
not exist, MQFirst creates it and its objects, including a dead letter queue.

On the fifth page, it displays the following messages:

Connecting to queue manager ′ brasch′
Creating queue manager ′ brasch′
Command run:crtmqm -qz -u SYSTEM.DEAD.LETTER.QUEUE -c″Created ... ″ brasch
brasch
Queue manager created.
Starting queue manager ′ brasch′ .
Command run:strmqm brasch
Queue manager started.
MQI :MQCONN(QMgr:′ brasch′ )
Connected to queue manager ′ brasch′

MQFirst uses the command server to create the objects it needs. When you
click on Next on page 5, MQFirst checks whether the command server is
running or not. If not, MQFirst issues an strmqcsr command to start it. In
the message area, three more messages are displayed:
Starting the command server.
Command run:strmqcsr brasch
Command server is OK.

MQFirst tells you on page six, shown in Figure 44 on page 82, that channel
definitions are needed at both ends of the link. You see a graph that
elucidates the sender and receiver. The programs that transfer the
messages over the network are called message channel agents (MCA).

The listener program listens for incoming messages and activates the
receiving MCA when a message has arrived.

The graph shows also a transmission queue on the sender side and three
local queues from which the applications get their messages.

Click on Next and MQFirst prepares for remote operations, even though you
can run it in one machine. You see three more messages on page 7:

Chapter 4. MQFirstSteps for Windows 81

 Figure 44. MQFirst - Sixth Window

MQSC:+ Define a generic receive channel at the local end

Receiver channel ′ brasch′ is OK.
Ensuring the channel listener is running.

MQFirst also displays the names of the queue manager and queue it wants
to use for incoming messages. You may change the queue name from
default to anything you like. When the queue is created you see the
following messages:
MQSC:+ Define a local queue ′ MQFIRST.default′
MQI :MQOPEN(Queue:′ MQFIRST.default′ ) for exclusive input

In the eighth window, you are asked to provide the queue manager name
and a queue name for outgoing messages. If you want to work only with a
local queue manager (running the verification of the installation only on one
system), key in your local queue manager name.
Note: As soon as you enter the local queue manager name, the queue
name changes from default to defaultother.

82 Connecting to the Internet with MQSeries and VisualAge for Java

Figure 45. MQFirst - Eighth Window

MQFirst creates now the second queue and displays the following
messages:
MQSC:+ Define a local queue ′ MQFIRST.defaultother′
MQI :MQOPEN(Queue:′ MQFIRST.defaultother′ ) for output
Ready to exchange messages with ′ defaultother′ .

If you are running MQFirst in two machines, then you can test the
connection when you key in the name of the remote MQ Queue Manager.

You are now ready to send and receive messages. In this example, we use
one machine with one queue manager.

Click on Next and the window shown in Figure 46 on page 84 will appear.
Type your first message in the message text field at the top of the window.
Also, mark Request Automatic Replies To Messages You Send. MQFirst then
automatically replies to the message you send (echo).

Chapter 4. MQFirstSteps for Windows 83

 Figure 46. MQFirst - Sending and Receiving Messages

Now click on Put Message and MQSeries puts the message in the queue
with the name default. You will see the reply in the lower message area of
the window.

Send some additional messages and see on the ninth MQFirst page a
message displayed for each MQPUT issued.

Now close the message window. You just completed your first connection
with MQSeries by clicking some buttons.

When MQFirst ends the message exchange, it displays the following

messages:
Message exchange with defaultother has finished.
MQI :MQCLOSE(Queue:′ MQFIRST.defaultother′ )

To end the guided tour through MQFirst click on Finish.

Next, you see the main window of MQFirst. That is the window you would
have seen had you selected Quick Start instead of Guided Tour.

84 Connecting to the Internet with MQSeries and VisualAge for Java

4.5.2 MQFirst Quick Start
Here you can specify the objects directly. Use this approach if you are
somewhat familiar with MQSeries, the queue manager and its objects.

The main window, shown in Figure 47, contains six tabs:

Messaging Define the queue manager, its objects and queues for incoming
and outgoing messages, send and receive messages.
Diagram Displays a diagram of the MQSeries objects which are being
used to exchange messages.
Definitions MQSeries commands which were processed to define the
objects. You can save them as a .tst file.
Glossary Explains MQSeries specific terminology.
Settings Define if you want the messages you sent echoed back and if you
want timestamps associated with the messages.
What Next? Some hints for using MQSeries.

Figure 47. MQFirst - Main Window

Chapter 4. MQFirstSteps for Windows 85

 Figure 48. MQFirst - Connections

The connections are displayed only after a message exchange takes place.
Move the cursor over one of the objects in the graph and MQFirst will
display object type and name.

The objects generated by MQFirst for one workstation are as follows:

*
* MQSC file created by MQFirst
*
* Define a generic receiver channel at the local end
* to receive messages from remote queue managers
DEFINE CHANNEL(′ wtr05176′ ) CHLTYPE(RCVR) +
TRPTYPE(TCP) REPLACE
* Define a local queue ′ MQFIRST.default′
DEFINE QLOCAL(′ MQFIRST.default′) +
USAGE(NORMAL) GET(ENABLED) PUT(ENABLED) REPLACE
* Define a local queue ′ MQFIRST.defaultother′
DEFINE QLOCAL(′ MQFIRST.defaultother′) +
USAGE(NORMAL) GET(ENABLED) PUT(ENABLED) REPLACE

86 Connecting to the Internet with MQSeries and VisualAge for Java

Chapter 5. Java and VisualAge for Java Overview

This chapter is a brief introduction into Java and is intended for those
readers who have no experience with this evolving programming language.

5.1 Some Basics about Java

The following shows what Java is and why you should learn Java or use
Java with your browser:

• Java is a programming language, developed by Sun Microsystems.

• Java is an object-oriented programming language.
• Java was modeled after Smalltalk and C++.
• Java is easier than C++.
• Java is platform-independent.
• Java is operating system-independent.
• Java is an interpreter language.
• Java is a secure language.
• Java is distributed.
• Java is robust.
• Java is the ideal programming language for Internet applications.

5.1.1 Java Is Platform-Independent

You can write Java programs with an editor of your choice. The source
code is plain ASCII code. This source code you can transfer to any system
that can read ASCII code. Then you can compile this code using the Java
compiler for that system. The compiler generates Java bytecode. The
bytecode again can be transferred to any Java-enabled operating system to
run it, or if it is an applet, to run it within a Java-enabled browser.

Figure 49 on page 88 shows how Java and C programs are compiled and
distributed. It shows that the bytecode generated by any Java compiler will
run on any machine that supports Java.

 Copyright IBM Corp. 1997 87

 Figure 49. Difference between C A n d Java Compiler

5.1.2 Java Is Distributed

Java is inherently distributed. The Java class libraries contain a lot of
routines for coping with TCP/IP protocols such as FTP and HTTP. Java
programs can access URLs as easily as a file system.

88 Connecting to the Internet with MQSeries and VisualAge for Java

 In our case, writing an applet using the MQSeries client for Java. The user
can download the Java bytecode of our program from the Internet and run it
on his or her own system. That means that anyone with access to your Web
server can load and run your applet with no prior installation needed on his
or her machine. When an update to the program is required, you simply
update the applet on your Web server and the user automatically receives
the latest version the next time he or she accesses the applet. This
significantly reduces cost for program service and updates.

5.1.3 Java Is Secure

Java is intended to run in networked/distributed environments, and a lot of
emphasis has been placed on security. Java programs cannot overrun their
runtime stack, cannot corrupt memory outside of their process space, and
when downloaded via the Internet, cannot even read or write local files. So
Java is the ideal language for the upcoming network computer.

5.1.4 Java Is Robust

Java puts a lot of emphasis on early checking for possible problems,
dynamic (runtime) checking, and the elimination of situations that are error
prone. Java uses a concept of references that eliminates the possibility of
overwriting memory and corrupting data.

The following features are what make it robust:

• Java eliminates pointer manipulation, so that the memory usage is
encapsulated in classes specifically built for that purpose.
• Java maintains runtime integrity by ensuring that distribution and
dynamic linking have not introduced errors into the code (in addition to
type checking at compile time). The interpreter ensures that the
bytecode has not been tampered with and that transmission errors are
not modifying the code.
• Java eliminates the common problems of out-of-bounds array access
a t t e m p t s i n C a n d C + + . Java always catches accesses to invalid array
elements. Some are caught at compile time, others at runtime when
computing index values.
• Java supports multithreading by providing synchronization modifiers in
the language. At the object level, threaded applications can inherit
classes specifically created for that purpose. The priority of specific
threads can be set by applications to suit specific needs, allowing
unique modes of preemptive multitasking.

Chapter 5. Java and VisualAge for Java Overview 89

5.1.5 Java Is Object-Oriented
Like Smalltalk and C++, Java is an object-oriented programming
language. However, it is not hybrid like C++. Java uses the concepts of
classes and objects, instances, interfaces, methods, single inheritance,
encapsulation and polymorphism. There are many books about
object-oriented technology out in the world, so we are not going to explain
what object-oriented technology means.

With Java you already get a lot of classes for the main functions you need.
So it is easy to start writing your first application or applet. The following
packages are included in Java:
• Language Package (java.lang.class)
This package provides the elementary classes for strings, arrays and
elementary data types.
• Utility Package (java.util.class)
This package includes classes for the support of handling vectors,
stacks, hash tables, encoding and decoding.
• I/O Package (java.io.class)
With this package you get classes for standard input and output, as well
as file I/O.
• Applet Package (java.applet.class)
This package provides support to interact with the browser.
• Abstract Window Toolkit (AWT) Package (java.awt.class)
This package was used mainly by us to build the GUI (graphical user
interface). It provides support to control the visual aspects of your
application or applet. Objects such as buttons, scroll bars, text fields,
lists and fonts are available in this class.
• Network Package (java.net.class)
For communication with other applications, this package provides the
basic support to communicate with peer programs over the network, as
well as standard protocols, such as TCP, FTP and URL access.

In the JDK Version 1.1 are some enhancements of existing classes, some
new features and also some performance improvements. The new features
are:

90 Connecting to the Internet with MQSeries and VisualAge for Java

• Internationalization
This allows the development of localizable applets and message
support, the display of UNICODE characters, and locale-sensitive date,
time, time zone and number handling.
• Security and Signed Applets
The Java Security API is designed to allow developers to incorporate
both low-level and high-level security functionality into their Java
applications.
• AWT Enhancements
These include a richer infrastructure for larger-scale GUI development,
including APIs for printing, scrolling, menus, clipboard, imaging and
graphics enhancements, and more flexible font support for
internationalization.
• JavaBeans Support
The JavaBeans APIs define a software component model to create and
ship Java components that can be composed together into applications
by end users.
• JAR File Format
JAR (Java Archive) is a platform-independent file format that aggregates
many files into one. Java applets and components (class files, images
and sounds) can be bundled in a JAR file and therefore downloaded
with higher speed.
The JAR format also supports compression, for even higher speed.
• Math Package
The Math Package provides two new classes, BigInteger and
BigDecimal.
• Remote Method Invocation
RMI enables the programmer to create distributed Java-to-Java
applications, in which the methods of remote Java objects can be
invoked from other Java virtual machines, possibly on different hosts.
• Object Serialization
Object Serialization extends the core Java Input/Output classes with
support for objects.
• Reflection
This enables Java code to discover information about the fields,
methods and constructors of loaded classes.

Chapter 5. Java and VisualAge for Java Overview 91

 • JDBC - Java Database Connectivity
Java Database Connectivity is a standard SQL database access
interface, providing uniform access to a wide range of relational
databases.
• Inner Classes
Provides a simpler syntax for the creation of adapter classes. An
adapter class is a class that implements an interface (or class) and
delegates the flow of control back to an enclosing ″main″ object.
• Java Native Interface
With JNI you have a standard programming interface for writing Java
native methods and embedding the Java VM into native applications.
The primary goal is binary compatibility of native method libraries
across all Java VM implementations on one platform.
Note: In our applet we use the MQSeries Client for Java classes instead of
the network package.

Remember these features, because in the next section we develop a small

application to become familiar with the real world of Java programming. We
start with an application that we know from other languages, the Hello World
application. We create and analyze the statements in the next section.

5.2 Applications and Applets

You can create two types of programs with Java: an application and an
applet. The main difference between them is the way the program is run.

A Java application is a regular program like a C or C++ program with a

main statement. However, unlike C or C++, a Java application requires an
interpreter. The JDK and OS/2 Warp Version 4.0 include a Java interpreter
called JAVA.EXE (or JAVAPM.EXE for programs that use the AWT classes).

A Java applet is a more restricted program. Because an applet is intended

to be delivered over the Internet, it is small and does not have access to all
the functions available to regular programs. This restriction gives a Java
applet the security level required to avoid intentional data corruption and
malicious programming, such as viruses.

A Java applet is usually run by a Java-enabled browser, such as Netscape

Navigator Version 2.02 (or higher) or Microsoft Internet Explorer Version 3.0
(or higher).

92 Connecting to the Internet with MQSeries and VisualAge for Java

 The JDK and also OS/2 Warp Version 4.0 include an applet viewer
(APPLETVIEWER.EXE resp. APPLET.EXE) that allow you to run a Java applet
without a Java-enabled browser. This is very helpful when you are testing
an applet. You will see this later, when we write an applet.

Once loaded, the program runs inside a Java virtual machine. The virtual
machine is a controlled environment where the Java bytecode is interpreted
and translated into machine language.

5.3 A First Try with Java

In this section we create a small Java application and a small applet. For
both application and applet, we at first create a directory structure that
holds our examples. After completing them, your directory (folder) should
look like this.

Let us create the application step by step.

First, create a directory to store your HTML files and your Java applet and
application files.
[C:\]md myjava
[C:\]cd myjava
[C:\myjava]
Ensure that the name of the directory is in the CLASSPATH environment
variable in the CONFIG.SYS:
SET CLASSPATH=C:\NETSCAPE\njclass.zip;C:\JAVAOS2\lib\jempcl10.zip;c:\myjava;.\.;
Now using your favorite editor, type the source code of your first Java
application.

Chapter 5. Java and VisualAge for Java Overview 93

5.3.1 The Hello World Application
The following code demonstrates a simple Java application. The file
extension of the source code is always .java, such as Hello.java.

class Hello {
public static void main (String args[]) {
System.out.println(″Hello World!″ ) ;
System.out.println(″Welcome to MQSeries Client for Java.″ )
}
}

Figure 50. A Simple Java Application

Now let us analyze the source code of Hello.java:

• The first statement, class Hello, declares a Java class called Hello. The
outer curly braces, { and }, define the scope of the code that belongs to
the Hello class.
• The second line defines a method. In this example, several Java
keywords are used to define it:
− public indicates that this method can be invoked from any other
class.
− static specifies that this method applies to the class globally,
instead of at the instance level.
− void indicates that this method does not return any value.
− main makes this program an application. It tells the Java interpreter
to call this method when the program is loaded.
− The next two lines print the text written between the double quotes.
Each line invokes the println method of the PrintStream class. The
PrintStream class is instantiated as out of the class named System.
The System class is instantiated as System.
Note: All Java statements end with a semicolon.

Compile the application with the Java compiler:

[C:\myjava]javac Hello.java
The compiler creates the file Hello.class. To run the application invoke the
Java interpreter:
[C:\myjava]java Hello
Note: The interpreter does not need the extension class to find the
application. As a result you will see the following lines in your window:

94 Connecting to the Internet with MQSeries and VisualAge for Java


[C:\myjava]javac Hello.java 
[C:\myjava]java Hello
Hello World!
Welcome to MQSeries Client for Java.

[C:\myjava]
 
5.3.2 The Hello World Applet
An applet is always called from within an HTML file. Therefore, we have to
create two files:
1. The Java program HelloWorld.java
2. The HTML file HelloWorld.html

5.3.2.1 Writing a Java Applet

This is the applet HelloWorld.java:

import java.awt.Graphics;
public class HelloWorld extends java.applet.Applet {
public void init () {
resize (300,200);
}
public void paint (Graphics g) {
g.drawRect(0,0,getSize().width - 1, getSize().height - 1);
g.drawString(″Hello World!″, 25, 25);
g.drawString(″Welcome to MQSeries Client for Java.″,25,50);
}
}

Figure 51. A Simple Java Applet

Now let us analyze the source code of HelloWorld.java.

• import java.awt.Graphics;
The first line imports the java.awt package that contains the graphics
classes. You need them when you want to draw something on the
screen. Packages are the means by which several different Java
classes can be stored together. java.awt refers to the Abstract Window
Toolkit (awt) package.
• public class HelloWorld extends java.applet.Applet
The second line declares the public class HelloWorld as an applet. The
word main is absent from this statement. The parameter extends

Chapter 5. Java and VisualAge for Java Overview 95

 indicates that the class inherits from the java.applet.Applet class. Java
allows single inheritance.
• public void init()
This is the initialization method. This is the first called method of an
instance of a class. Here you could initialize variables. Be aware that if
this class is inherited by another class, this method can be overridden in
that class and, therefore, is never called.
• resize(300, 200);
With this line you define the size of the applet in pixels.
Note: This value has no effect inside a browser, only in the applet
viewer.
• public void paint(Graphics g)
This second method is called by the AWT when the applet needs to be
drawn or redrawn. In our example, we write (draw) two character
strings and a box around them. To do that we use two drawing methods
of the graphics class.
• g.drawRect(0,0,getSize().width - 1, getSize().height - 1);
The first statement in the paint method draws a rectangle just inside the
applet. drawRect has four parameters, the coordinates for the top left
corner (0,0), and the width and height of the rectangle, all values in
pixels. Width and height depend on the size of the applet.
• g.drawString(″Hello World!″, 25, 25);
g.drawString(″Welcome to MQSeries client for Java.″,25,50);
The two drawString methods cause the text between the double quotes
to be displayed. The first parameter following the text is the left side of
the text, the second is the baseline for the string.
Note: g is an instance of the graphics class.

5.3.2.2 Compiling an Applet

Compile the applet with the Java compiler:
[C:\myjava]javac HelloWorld.java
The compiler creates the file HelloWorld.class.

Note: Depending on the eight character long names in a FAT file system,
you should rename the ....jav files after downloading on a hard disk to the
original names as described in this book.

96 Connecting to the Internet with MQSeries and VisualAge for Java

If compilation fails, make sure you typed in and named the program exactly
as shown above. One of the most common mistakes in the beginning is to
forget a semicolon on the end of a statement or mismatch within the pair of
{ } .

5.3.2.3 Writing an HTML File that Calls an Applet

Applets are always called from an HTML file. The following file,
HelloWorld.html, calls the HelloWorld applet.

<HTML>
<HEAD><TITLE>A Simple Program</TITLE>
</HEAD>
<BODY>
Here is the output of my program:
<APPLET CODE=″HelloWorld.class″ WIDTH=300 HEIGHT=200>
</APPLET>
</BODY>
</HTML>

Figure 52. HTML File that Calls an Applet

The file HelloWorld.html in Figure 52 calls the applet ″HelloWorld.class″ with

this statement:
<applet code=″HelloWorld.class″ width=150 height=50>

The keywords mean:

applet Is the tag that calls a Java applet.
code Defines the full name of the Java applet.
width Defines the width of the applet window.
height Defines the height of the applet window.
The other HTML keywords define the rest of the page.

Note: For more detail about HTML you should look in book stores. You will
find a lot of good books about HTML. Look for the newest release numbers.

5.3.2.4 Executing an Applet

You can run the applet two ways:
• From an applet viewer
• From a Java-enabled browser
In either case you load the HTML file first and let it display the applet. If you
use the applet viewer, you will see only the applet and not the other

Chapter 5. Java and VisualAge for Java Overview 97

 contents of the HTML file. To view the applet with the applet viewer enter
on the command line:
[C:]applet \myjava\HelloWorld.html

-- or --

[C:\myjava]applet HelloWorld.html
Note: In some operating systems the name of the appletviewer EXE is
applet, in others appletviewer.

Once you have successfully completed all the above steps, you should see
the applet in your window:

Important
Do not invoke the applet viewer from the HTML directory if you might
want to reload the applet. Because of the way the class loader works,
an applet can′t be reloaded (for example, after you make changes to its
code) when you invoke the applet viewer from the directory that contains
the applet′s compiled code.

98 Connecting to the Internet with MQSeries and VisualAge for Java

To view the applet with a browser type the file name and its full path:
file:///c:/myjava/HelloWorld.html
The Netscape Navigator displays the applet as shown on page 99. Note that
the applet appears to the right of the text. To draw the applet below the text
insert a <p> tag before the <APPLET> tag in the HTML file in Figure 52
on page 97.

5.3.2.5 You Did It

This should only be the start to your next and more complex and powerful
applet.

In this redbook we don′t describe the Java language in more detail, because
there are so many good books available.

If you are familiar with programming in C, you should have a look at the
book Java in a Nutshell by David Flanagan (ISBN 1-56592-183-6).

But if you are a beginner, you can try the book Teach Yourself Java in 21
Days by Laura Lemay and Charles L.Perkins (ISBN 1-57521-030-4).

Chapter 5. Java and VisualAge for Java Overview 99

5.4 A First Try with VisualAge for Java
To start VisualAge for Java (VAJAVA) on Windows NT, select from the start
menu:
VisualAge for Java for Windows
VisualAge for Java
First, you see the Workbench window shown in Figure 53. The Workbench
window is used to access other windows, to create program elements, and
view the contents of program elements.

The VisualAge Quick Start window aids you in selecting what to do next. It
provides a fast path to creating applets, classes, and interfaces. It is
automatically shown when VisualAge for Java is started for the first time.
You may decide whether you want to see it every time the program starts or
not.

Since we want to create an applet, we chose Create a new applet.

Figure 53. VisualAge for Java - Quick Start

100 Connecting to the Internet with MQSeries and VisualAge for Java
In the next window, shown in Figure 54 on page 101, type the names of the
following:
• Applet (VAJavaTestView)
• Project (MQandJava)
• Package (Example)
VisualAge for Java suggests that you give your applets (and all other
classes) names that begin with a capital letter. Class names are
case-sensitive, and cannot contain spaces. If a class name consists of
multiple words, do not type spaces between the words, but instead
capitalize the first letter of each word.

Next, mark the check box that lets you design your applet visually and click
on Finish.

Figure 54. VisualAge for Java - Create an Applet

VisualAge for Java now creates the project, package and applet you
specified in the previous window and opens the Composition Editor with an
empty work area as shown in Figure 55 on page 102.

When you build your new applet in the Visual Composition Editor, you are
visually manipulating JavaBeans. These JavaBeans (or, simply, beans) are
represented as classes when you examine your applet in the Workbench.
When working with beans in VisualAge for Java, you use the following
fundamental techniques:

Chapter 5. Java and VisualAge for Java Overview 101

 Figure 55. VisualAge for Java - Composition Editor

• Dragging beans
• Selecting multiple beans
• Displaying pop-up menus

When you build a Graphical User Interface (GUI), you work with categories
of beans. These are shown on the left side of the Composition Editor. The
left column contains the categories and the column to the right of it contains
the beans (parts in VisualAge for Smalltalk).

To place a bean in the working area, click on it and then click in the work
area where you want to place it. If you want to place the same bean
several times in the GUI, activate the Sticky radio button, But don′t forget to
deactivate the button if you don′t need it any longer.

To select multiple beans, hold down the control (Ctrl) key and click mouse
button 1 on the items you want to select. This is of use if you want, for
example, to align different fields (labels and text fields) with the buttons on
top of the work area.

102 Connecting to the Internet with MQSeries and VisualAge for Java
 To display a pop-up menu, click mouse button 2 on the object.

5.4.1 Creating Objects

The first GUI we want to build is shown in Figure 56. It contains two
different push buttons, labels, and text fields, and also a Variable bean in
the white space outside the GUI area. The GUI is inside the rectangle
marked with a dotted line.

Figure 56. VisualAge for Java - A GUI

In the following we describe how to create the GUI step-by-step.

1. Click on this icon representing the Data Entry category from the
container on the left. This category contains three beans.

2. Then select the text field from the right column of the beans
palette.
3. Check Sticky below the beans palette and with the left mouse button,
click where in the work area you want to place the first and the second

Chapter 5. Java and VisualAge for Java Overview 103

 text field. The pointer changes to cross-hair, indicating that it is now
loaded with the bean you selected.
Note: The dotted rectangle on the free-form surface is now your new
applet bean VAJavaTestView.
To change the size of the text field:

4. From the same category select the Label bean and place two
labels in the GUI in the same fashion as for the text field in the previous
step.
Don′t worry about their exact positions. Later you will learn how to use
the tools from the tool bar to match sizes and align beans.

5. To add buttons, select the button category.

6. Click on the push button symbol and add two buttons to the
applet between the text fields.

7. To add the non-visual variable (object) to the applet, select the

Models category.

8. Place the variable into the white space outside the applet.
This is a non-visual bean that does not belong in the GUI.
Note: Don′t forget to unmark the sticky check box.

You have now placed all parts into your GUI. The next step is to change the
properties of the various parts.

5.4.2 Changing Object Properties

How an object appears is defined in the Properties window. You can
display a Properties window in two ways:
• Double-click with the left mouse button on the object.
• Click with the right mouse button on the object and select Properties.

104 Connecting to the Internet with MQSeries and VisualAge for Java
Figure 57. VisualAge for Java - Push Button Properties

1. Change the name of the buttons.

On the left side of the window, you see the name of the properties. The
right side contains values that you may change. To change a value,
click on the property. You will notice that the background on the left
side changes to blue, showing that this field is now active.
In the Properties window for the left button of your GUI, change the text
in the button (label) from Button1 to Send. Select label and type Send.
2. Change the beanName from Button1 to SendButton
3. Change the font.
To do this, highlight font and click on the button to the right of Abcde.
This displays the Font window shown in Figure 58 on page 106.

Chapter 5. Java and VisualAge for Java Overview 105

 Figure 58. VisualAge for Java - Fonts

In the Fonts window, you can set the font attributes. We selected:
Font Name timesroman
Style Bold
Point Size 14
When you are done, click on OK.
4. Change properties of the second push button.
Don′t close the Properties window yet. Click on the right push button
and the Properties windows displays the properties of Button2. Name
the bean ReceiveButton, give it the label Receive and the same fonts as
the Send button.
In the same manner you can change the labels, so that they look as
shown in Figure 56 on page 103. The font is the same as for the push
buttons. Now close the Properties window.
5. Change the name of the variable.
Next, change the name of the non-visual object to MessageQueue. With
the right mouse button, click on Object1 and select Change BeanName.
You are now presented with the Bean Name Change Request window
shown in Figure 59 on page 107. Type the new name and click on OK.

106 Connecting to the Internet with MQSeries and VisualAge for Java
 Figure 59. VisualAge for Java - Change Bean Name

5.4.3 Aligning and Resizing Objects

Now we explain how to align and resize the objects in your GUI.
1. If the labels don′ t show completely, follow these steps:
• Select the label.
• Click on one of the corners of the label.
• Hold down the mouse button.
• Drag the corner until you have the right size.
• Release the mouse button.
2. You can resize the text fields and radio buttons the same way. Make
the upper text field the size you like.
3. Now we make both text fields the same width.
• Click on the lower text field to make it active.
• Press and hold down the Ctrl key.
• Click on the upper text field so that both become active.

• Click on the Match Width button and the width of both

fields will be the same.
4. Next, use the Match Height button to give the fields the same height.
5. Now we left-justify the labels and text fields.
• Click on the first label and move it to a position you like.
• Press and hold down the Ctrl key.
• Click on all fields you want to align, the first label last.

• Click on the Align Left button and all fields are aligned with
the field on the top.

Chapter 5. Java and VisualAge for Java Overview 107

 6. Before you align the push buttons, make them the same size as
described for the fields above. Then activate both buttons and click on

the Distribute Horizontally button. The buttons now are aligned

equally in the GUI area.

You have now finished with the alignment of the objects. The GUI should
now look like the one shown in Figure 56 on page 103.

5.4.4 Visual Programming

Now we can start with the visual programming, that is, connecting beans. In
this example, we will not write methods. VisualAge for Java will do that for
us.

We explain how to make an event-to-method connection with parameters.

To make such a connection for the Send button, follow these steps:
1. Select the Send button, then click mouse button 2.
2. From the pop-up menu, select Connect and then
actionPerformed(java.awt.event.ActionEvent).
The mouse pointer changes to a spider, indicating that you are in the
process of making a connection.
Note: If you accidentally started a wrong connection, press the Esc key
to cancel.
3. To complete the connection, click mouse button 1 on the object
MessageQueue and select this from the pop-up.
A green dashed line appears, which means that more information is
necessary. In this case, the value of the parameter for the connection
(method) is missing.

To specify what data has to be put into the variable MessageQueue, we

make a parameter-from-property connection:
1. Move the mouse pointer over the dashed event-to-method connection
line.
2. Click mouse button 2, select Connect from the pop-up and then value.
3. Click mouse button 1 on the SendTextField, and select text from the
pop-up menu.

To program the Receive button, follow these steps:

108 Connecting to the Internet with MQSeries and VisualAge for Java
 1. Select the Receive button and click mouse button 2.
2. Select Connect, then actionPerformed(java.awt.event.ActionEvent).
3. Click mouse button 1 over the ReceiveTextField, then select text from
the pop-up menu.
Again, a dashed line appears. The value of the parameter for the
getMessageQueue method is missing. A parameter-from-property
connection that specifies what to get must be programmed.
4. Move the mouse pointer on top of the dashed connection line.
5. Click mouse button 2, select Connect and then value from the pop-up.
6. Click mouse button 1 on the MessageQueue object and select text from
the pop-up.
Now your applet should look like the one in Figure 60.

Figure 60. Visual Programming - Connections

The next step is to test the applet.

Chapter 5. Java and VisualAge for Java Overview 109

5.4.5 Testing the Applet

When you click on this test button in the Icon Menu Bar, VisualAge
for Java will:
• Save your code.
• Compile and generate runtime code.
• Display a Setting window which lets you change width and height of the
applet.
Click on Run and the appletviewer starts the applet.

Figure 61. Appletviewer

To test your applet:

• Key in some text in the Send Message Field
• Click on the Send button (the GUI does′t change)
• Click on the Receive button
• The text appears in the Receive Message Field.
It works! First you put some text into the variable MessageQueue and then
you moved the text from the variable into the Receive Message Field
without writing a line of code.

110 Connecting to the Internet with MQSeries and VisualAge for Java
5.4.6 Methods Generated by VisualAge for Java
Let us look at the methods VisualAge for Java generated as we built the GUI
and connected the beans. The complete list of this methods is shown in
Figure 62.

Figure 62. VisualAge Generated Methods

Chapter 5. Java and VisualAge for Java Overview 111

 Figure 63. One Method as an Example

As an example, we show in Figure 63 the method

actionPerformed(java.awt.event.ActionEvent). Note that its name is
highlighted in the top half of the window. The source code is in the bottom
half.

You can see that in this (and also in the other) method is indicated where
you can type your own Java code. We will do that in the next example in
Chapter 6, “An MQSeries Application” on page 119.

Before we start something new, let us export the applet.

112 Connecting to the Internet with MQSeries and VisualAge for Java
5.4.7 Versioning and Exporting a Package
You can export a package or a class. Before you can export a package or a
class you have to give it a version number.

Figure 64. Workbench Window

To assign a version number follow these steps:

• Select the package or applet in the workbench window, such as Example
or VAJavaTestView.
• Click on Selected in the menu. Figure 64 shows the applet
VAJavaTestView selected for versioning.
• Select Version from the pop-up.
• The SmartGuide presents you with the Versioning window shown in
Figure 65 on page 114. The radio button Automatic should be selected,
and the version should be 1.0.
Note: You can change the version only when Automatic is not selected.
• Click on Finish to complete the process.

Chapter 5. Java and VisualAge for Java Overview 113

 Figure 65. SmartGuide - Versioning Selected Items

Figure 66. SmartGuide - Type of Export

114 Connecting to the Internet with MQSeries and VisualAge for Java
 Now you can export the package Example.
• Highlight its name in the Projects window.
• Select File from the menu bar.
• Select Export from the menu. The SmartGuide displays the window
shown in Figure 66.
• Activate the Interchange-File radio button.
• Click on Next. The SmartGuide displays the window shown in Figure 67
on page 115.
• Type a file name, such as fbexamp1.dat, or browse to find a directory
and name.
• Click on Finish and the SmartGuide will create the file.

Figure 67. SmartGuide - Export to Interchange File

5.4.8 Importing a Package

After exporting a package, you also should learn how to import a package in
a project, so that you can do it later, if you want to import our examples in
your project.

The following steps describe how to import a package:

Chapter 5. Java and VisualAge for Java Overview 115

 • Insert the diskette containing the file(s) you want to import into your
diskette drive.
• Select Import from the File menu..
• Type the project name into the Project field.
• Click on Interchange File (import into repository only).
• Click on N e x t > .
• Type the file name, such as A:\MQEXMP11.dat into the File field.
• Click on the Packages radio button.
• Click on the Update push button.
• In the list box, select the file name you want to import, such as
MQRedbookExample 1.1.
• Click on Finish.

Now the example has been stored in your repository. The following steps
describe how you import the package MQRedbookExample into your work
space.
• Click on the Projects tab in the Workbench window.
• Click on your project to highlight it.
• Click the right mouse button (button 2).
• Select Add Package from the pop-up menu.
• In the Add Package window, select the radio button for Add package(s)
from the repository.
• Click on Browse.
• Select the package MQRedbookExample from the available package
names list.
• Select version 1.1 from Editions list.
• Click on the > > button.
• Highlight MQRedbookExample 1.1 in the Editions to Add list.
• Click on OK.
• Click on Finish in the Add package window.

Figure 68 on page 117 shows that the package containing the examples is
added to your project.

116 Connecting to the Internet with MQSeries and VisualAge for Java
Figure 68. Import a Package

Chapter 5. Java and VisualAge for Java Overview 117

118 Connecting to the Internet with MQSeries and VisualAge for Java
Chapter 6. An MQSeries Application

In this chapter, we describe how to develop a small MQSeries application

with VisualAge for Java. Figure 69 illustrates the application.

Figure 69. MQSeries Application - Overview

The application consists of two programs:

1. A Java applet, MQExample1, that communicates with a server program
2. A Java application, MQExample2, that represents the server program

In this chapter, you will learn how to:

• Create a graphical user interface (GUI)
• Write methods in VisualAge for Java
• Connect an event to a method
• Write methods that:
− Connect to a queue manager
− Open a queue
− Put a message on a queue
− Get a message from a queue
− Close a queue
− Disconnect from the queue manager

 Copyright IBM Corp. 1997 119

 Figure 70. MQSeries Application - Client

The two programs are very basic and demonstrate only the use of the
MQSeries APIs. Both applet and server programs have a GUI in which the
user can enter all values necessary to build a connection. This makes the
application flexible so that it can be used as an installation verification
program.

Figure 70 shows the applet and Figure 71 on page 121 shows the GUI of the
server program.

Throughout the rest of this chapter we describe how to build both programs
and how to run them.

120 Connecting to the Internet with MQSeries and VisualAge for Java
Figure 71. MQSeries Application - Server

The programs can run in one or two machines depending on the MQSeries
definitions you provide. You can also test the applet in the machine where
the queue manager is installed. That is usually the case in a test
environment. You may also run the programs independently of each other.

Diskette
This application is on the diskette that accompanies this book.

5.4.8, “Importing a Package” on page 115 explains how to import the

example and 6.10, “How to Test the Application” on page 142 describes
how to run it.

Chapter 6. An MQSeries Application 121

6.1 Creating an Applet
Figure 70 on page 120 shows the Graphical User Interface (GUI) for the
applet. It contains the following objects:

6 push buttons to invoke MQSeries functions:

• Connect to a queue manager
• Open a queue for input and output
• Put a message on the queue
• Get a message from the queue
• Close the queue
• Disconnect from the queue manager

5 text fields to name the objects used by the MQSeries APIs:

• Queue manager
• Channel of type SVRCONN between client and queue manager
• TCP/IP host name of the server
• TCP/IP port number (1414 is the default for MQSeries)
• Queue that holds the messages

2 text fields to type an input message and to display an output

message

7 labels to identify the text fields.

Place these objects into the GUI as shown in Figure 70 on page 120. How
to do that is described in 5.3, “A First Try with Java” on page 93. Don′ t
forget to match the sizes of the objects and align them.

Of course, you can use different fonts and choose different arrangements of
the fields and buttons.
Note: To give the user some control over the server program, we built a
GUI for it, too. The server program is an application and not and applet.
Refer to 6.9.1, “Writing an MQSeries Server Application” on page 140 for
more information.

122 Connecting to the Internet with MQSeries and VisualAge for Java
6.2 Writing a Method
After the GUI is created, you must write some methods that invoke the
MQSeries APIs. Unlike VisualAge for Smalltalk, VisualAge for Java does not
have MQSeries beans.

Before we write the methods associated with the push buttons, let us
discuss, in general, how to create a method, how it gets invoked and how it
obtains data from the text fields.

Figure 72. MQExample1 - VisualAge Methods Editor

To create a new method follow these steps:

1. Click on the Methods tab to switch from the composition editor to the
methods editor shown in Figure 72.
2. Click the right mouse button or click on Methods in the menu bar. Then
select New Method. The SmartGuide then displays the Create Method
window shown in Figure 73 on page 124.
3. Now enter the name of the method and its parameters.
4. Select one of the Access Modifiers, such as the default public.

Chapter 6. An MQSeries Application 123

 Figure 73. MQExample1 - Creating a New Method

5. Click on Finish.
6. From the methods listed on the Methods tab, select the method you just
created.
7. This displays the Java-generated method skeleton in the Source field.
Here you add the code for the method.
8. After you have completed the source code, click the right mouse button
and select Save to save and compile the source code.

The methods we have to write for this application invoke seven MQSeries
APIs which will be discussed later. The methods and their parameters are:
• connectToQmgr(String queueManagerName, String hostname, String
channel, String portnumber)
• disconnectFromQmgr()
• openQueue(String queueName, String queueManagerName)
• putMessage(String inputMessage)
• retrieveMessage()
• closeQueue()
• disconnectFromQmgr()
Other methods will be generated by VisualAge for Java.

124 Connecting to the Internet with MQSeries and VisualAge for Java
 Figure 74. MQExample1 - Writing a Method

6.2.1 How to Connect Events to a Method

After writing a method, you connect GUI events, such as clicking on a push
button to the method. You do this in the Visual Composition editor, shown
in Figure 75 on page 126.
1. Select the button you want to connect to a method.
2. Click right mouse button.
3. Select Connect from the menu.
4. Select an event, such as actionPerformed(java.awt.event.ActionEvent).
The cursor changes to a spider.
5. Draw a line (drop the spider) in the white space outside of the applet
area and click the left mouse button.
6. From the menu, select All Features.
7. From the list of methods, select the name of the method you want to
connect to and click on OK.
Then you can make an Event-to-Method connection.

Chapter 6. An MQSeries Application 125

 Figure 75. MQExample1 - Connect Event to Method

6.2.2 How to Connect Parameter from Property

After having connected an event to a method, you can specify from where to
get the parameters the method expects. For this example, all parameters
have to be typed by the applet user into text fields. Therefore, we connect
one or more text fields to the connection lines between the push buttons
and methods. This is called a parameter-from-property connection.

You make such a connection in the following way:

1. Select a text field whose value you want to get as a parameter.
2. Click right mouse button.
3. Select Connect from the menu.
4. From the subsequent menu, select the property text.
5. Draw a line to the event-to-method connection line.
6. Select the parameter name of method, such as QueueName.

126 Connecting to the Internet with MQSeries and VisualAge for Java
 Figure 76 on page 127 shows the Visual Composition editor after the
connection is completed. You may connect the text of several text fields
with the method. VisualAge for Java generates the code that gives the text
of those fields to the method as parameters whenever the associated event,
that is, a mouse click occurs.

Figure 76. MQExample1 - Set Parameter from Property

6.3 How to Connect to the Queue Manager

To connect to a queue manager, you must write a method which uses the
MQSeries for Java class library. The class hierarchy is:

Chapter 6. An MQSeries Application 127

 java.lang.Object
java.awt.Component
java.awt.Container
java.awt.Panel
java.applet.Applet
MQRedbookExample.MQExample1
MQRedbookExample.MQExample1 imports com.ibm.mq.*.

The following steps describe how to create the part of the applet shown in
Figure 77.

Figure 77. MQExample1 - Connect Queue Manager

1. If you have not already done so, use the Visual Composition editor to
create the appropriate text fields that will contain the parameter values
required to connect to a queue manager. These are:
• Queue manager name
• Channel name
• Host name
• Port number
2. Create a push button that initiates the connection to the queue manager.
3. Use the Methods editor to create the new method connectToQmgr using
the parameters shown in the table below.

128 Connecting to the Internet with MQSeries and VisualAge for Java
 4. Write the source code shown in Figure 78 on page 129.

Table 6. Method connectToQmgr and Parameters

Method connectToQmgr()
Input String queueManagerName QMgr name
String hostname TCP/IP host name
String channel Channel of type SVRCONN
String portnumber TCP/IP port (default 1414)
Return void
Flow

public void connectToQmgr(String queueManagerName, String ...) {

try {
int portnum;
try { // convert String to Int
portnum = new Integer(portnumber).intValue();
}
catch (NumberFormatException ex) {
portnum = 1414; // set port to default value
}
// setup MQEnvironment
//
MQEnvironment.hostname = hostname;
MQEnvironment.channel = channel;
MQEnvironment.port = portnum;
//
// connect to Queue Manager
//
qMgr = new MQQueueManager(queueManagerName);
System.out.println(″Connected to Queue Manager: ″ +
queueManagerName + ″Channel Name: ″ +
channel = ″TCP/IP Port Number: ″ +
portnum);
}
catch (MQException ex) {
System.out.println(″An MQ error occured: CC: ″ +
ex.completionCode +
″Reason Code: ″ + ex.reasonCode);
}
}

Figure 78. MQExample1 - Method connectToQmgr

Chapter 6. An MQSeries Application 129

 • The first part of the code converts the string port number into an
integer.
• Three environment variables are set up, the strings hostname and
channel, and the integer with the port number.
• To connect to the queue manager, a new MQQueueManager object
is created.
• The exception handler displays a message if the connect failed.
5. In the Visual Composition editor, make an event-to-method connection
between the push button and the connectToQmgr method.
6. Make four parameter-from-property connections between each text field
and the event-to-method connection line.

6.4 How to Disconnect from a Queue Manager

This is a simple function. We need a push button that calls a method that
performs an MQDISC call. No parameters are required. Figure 79 shows
that a second push button has been added to the applet. The Disconnect
button is connected to a method.

Figure 79. MQExample1 - Disconnect from Queue Manager

The following steps describe how to disconnect from a queue manager.

1. If you have not already done so, use the Visual Composition editor to
create a push button that will cause a disconnect.
2. Use the Methods editor to create the method disconnectFromQMgr.
3. Write the source code as shown in Figure 80 on page 131.

130 Connecting to the Internet with MQSeries and VisualAge for Java
 Table 7. Method disconnectFromQmgr and Parameters
Method disconnectFromQmgr()
Input none
Return void
Flow

The program contains a try and catch block. The try block calls the
disconnect() method of the queue manager object. The exception
handler displays a message when the disconnect fails.

public void disconnectFromQmgr() {

try {
qMgr.disconnect();
System.out.println(″Disconnect from Queue Manager″ ) ;
}
catch (MQException ex) {
System.out.println(″An MQ error occured: CC: ″ +
ex.completionCode +
″Reason Code: ″ + ex.reasonCode);
}
return;
}

Figure 80. MQExample1 - Method disconnectFromQmgr

4. Make an event-to-method connection between the push button and the

disconnectFromQmgr method.

6.5 How to Open a Queue

To open a queue you need to know the name of the queue manager and the
queue name. In this example, both parameters are entered by the operator
and used in the method that is invoked when the Open push button is
clicked.

To add a push button that opens a queue you specify in the applet follow
these steps:
1. Use the Visual Composition editor to add to the GUI a text field for the
queue name. The queue manager name is in the same field that is
used for the connect.
2. Create a push button that initiates the opening of the queue.
3. Use the Methods editor to create the method openQueue.

Chapter 6. An MQSeries Application 131

 4. Write the source code as shown in Figure 81 on page 132 using the
parameters listed in Table 8 on page 132.

Table 8. Method openQueue and Parameters

Method openQueue()
Input String queueName Name of the queue
String queueManagerName Name of the queue manager
Return void
Flow

• The openQueue method in Figure 81 sets the input options in

oprnOptions in a way that the queue can be used for input and
output.
• Then the accessQueue() method of the queue manager object is
called to create an MQQueue object.
• The queue name is accessQueue.
• The exception handler displays the return codes when the open
fails.

public void openQueue(String queueName, String queueManagerName){

try {
int oprnOptions = MQC.MQOO_INPUT_AS_Q_DEF | MQC.MQOO_OUTPUT ;
accessQueue = qMgr.accessQueue(queueName, openOptions);
System.out.println(″Open Queue:″ + queueName);
}
catch (MQException ex) {
System.out.println(″An MQ error occured: CC: ″ +
ex.completionCode +
″Reason Code: ″ + ex.reasonCode);
}
}

Figure 81. MQExample1 - Method openQueue

5. Use the Visual Composition editor to make an event-to-method

connection between the push button and openQueue method.
6. Make a parameter-from-property connection between the Queue
Manager Name text field and the event-to-method connection.
7. Make a parameter-from-property connection between the Queue Name
text field and the event-to-method connection.

132 Connecting to the Internet with MQSeries and VisualAge for Java
 Figure 82. MQExample1 - Open a Queue

6.6 How to Close a Queue

Closing the queue is also simple. For this example, we click on a push
button to invoke the method that closes the queue. No parameters are
necessary.
1. Use the Visual Composition editor to create a push button to initiate the
closing of a queue.
2. Use the Methods editor the create the new method closeQueue.
3. Write source code as shown in Figure 83 on page 134.

Table 9. Method closeQueue and Parameters

Method closeQueue()
Input none
Return void
Flow

• In the try block, the close() method of the object accessQueue is

called.
• The exception handler displays the return codes in case the close
fails.

Chapter 6. An MQSeries Application 133

 public void close() {
try {
accessQueue.close();
System.out.println(″Close Queue″ ) ;
}
catch (MQException ex) {
System.out.println(″An MQ error occured: CC: ″ +
ex.completionCode +
″Reason Code: ″ + ex.reasonCode);
}
}

Figure 83. MQExample1 - Method closeQueue

4. Use the Visual Composition editor to make an event-to-method

connection between the push button and the closeQueue method.
Figure 84 shows the push button and the connection.

Figure 84. MQExample1 - Close Queue

6.7 How to Put a Message Into a Queue

In this example, the applet user can type some text into a text field. This
data becomes the message that is put into the specified queue. The
following steps tell you how to do this.
1. In not already done, use the Visual Composition editor to create:
• A text field into which the user can type the message

134 Connecting to the Internet with MQSeries and VisualAge for Java
 • A push button that initiates putting message in the queue
2. Use the Methods editor to create the new method putMessage.
3. Write the source code as shown in Figure 85 using the parameters in
the table below.

Table 10. Method putMessage and Parameters

Method putMessage()
Input String inputMessage The message data to be put
into the queue
Return void
Flow

public void putMessage(String inputMessage) {

try {
// create new message object
MQMessage inputMsg = new MQMessage();
// write message into the buffer as UTF Format
inputMsg.writeUTF(inputMessage);
// create new PutMessageOption object
MQPutMessageOptions pmo = new MQPutMessageOptions();
// put the message now in the queue
accessQueue.put(inputMsg, pmo);
System.out.println(″Message has been put into the queue″ ) ;
}
catch (MQException ex) {
System.out.println(″An MQ error occured: CC: ″ +
ex.completionCode +
″Reason Code: ″ + ex.reasonCode);
}
catch (java.io.IOException ex) {
System.out.println(″An IO error occured while writing
messege into the queue″ ) ;
}
}

Figure 85. MQExample1 - Method putMessage

• First create a new MQMessage object with the name inputMsg. This
message will hold the data the applet user types.
• The method receives the user data as parameter inputMessage.
Write the message data into the buffer, inputMsg, using the
writeUTF() method of the message object.

Chapter 6. An MQSeries Application 135

 • Next create a new MQPutMessageOption object.
• Then call the put() method of queue object accessQueue to put the
message on the queue.
• The exception handler displays a message when the put fails. The
program also displays a message when an error occurrs after
writing the message data to the buffer.
4. Use the Visual Composition editor to make an event-to-method
connection between the push button and the putMessage method.
5. Then make a parameter-from-property connection between the Input
Message text field and the event-to-method connection.
Figure 86 shows what has been added to the applet.

Figure 86. MQExample1 - Put a Message in a Queue

136 Connecting to the Internet with MQSeries and VisualAge for Java
6.8 How to Get a Message from a Queue
In this example, the applet user can click on the Receive button to get a
message from the specified queue and display the data in the Output
Message text field. The following steps tell you how to do this.
1. If not already done, add two objects to the GUI:
• A text field to display the received message
• A push button that initiates getting a message from the queue

Figure 87. MQExample1 - Get a Message from a Queue

2. Use the Methods editor to create the new method retrieveMessage.

Chapter 6. An MQSeries Application 137

 3. Write the method as shown in Figure 88 on page 138 using the
parameters shown in the table below.

Table 11. Method retrieveMessage and Parameters

Method retrieveMessage()
Input none
Return String outputMessage The message retrieved from
the queue
Flow

public void retrieveMessage() {

try {
// create a new message object
MQMessage outputMsg = new MQMessage();
// create new GetMessageOption object
MQGetMessageOptions gmo = new MQGetMessageOptions();
// get the message from the queue
accessQueue.get(outputMsg, gmo);
System.out.println(″Message has been gotten from the queue″ ) ;
// read the message from the buffer in UTF Format
outputMessage = outpuMsg.readUTF();
}
catch (MQException ex) {
System.out.println(″An MQ error occurred: CC: ″ +
ex.completionCode +
″Reason Code: ″ + ex.reasonCode);
}
catch (java.io.IOException ex) {
System.out.println(″An IO error occurred while reading
a message from the queue″ ) ;
}
return outputMessage;
}

Figure 88. MQExample1 - Method receiveMessage

• First create a new MQMessage object with the name outputMsg. It

will hold the message to be gotten from the queue.
• Next create a new MQGetMessageOption object with the name gmo.
• Now call the get() method of the queue object accessQueue to get
the message from the queue.

138 Connecting to the Internet with MQSeries and VisualAge for Java
 • The readUTF() method of the message object reads the message
from the buffer and stores the data in outputMessage. This field will
be used to display the data.
• When an exception occurs an error message will be displayed.
4. Use the Visual Composition editor to make an event-to-method
connection between the push button and the receiveMessage method.
5. To display the message returned in outputMessage in the Output
Message text field, you must connect the text property of the text field
and normalResult of the event-to-method connection between the button
and the method.
• Click on the event-to-method connection between the Receive button
and the method.
• Select Connect from the menu and then normalResult.
• Drop the spider into the Output Message field and select text from
the pop-up.
You just built an event-to-method connection between the
event-to-method connection and the Output Message text field.

6.9 Creating a Java Application Using MQSeries

Like MQSeries applications written in the C language, there is no difference
between client and server code from the application programmer′s point of
view. When using C, you link your program with either the mqm (server) or
mqic (client) library.

For applets (MQSeries Client for Java), you use the mq class library; for
MQSeries server programs (Java applications) you use the bindings in the
mqbind class library instead.

If you write an applet or an MQSeries client application you have to import

com.ibm.mq.*. at the beginning of your code:
import com.ibm.mq.*;

If you write an MQSeries server application , you have to import

com.ibm.mqbind:
import com.ibm.mqbind.*;

Figure 89 on page 140 shows MQExample2, an applet that runs in the

server and, therefore, uses the bindings.

Chapter 6. An MQSeries Application 139

 Unlike the MQSeries Client for Java, the MQSeries bindings ignore most of
the parameters provided by the MQEnvironment because the server can
connect directly to a queue manager.

Figure 89. MQExample2 - VisualAge Projects Window

6.9.1 Writing an MQSeries Server Application

The second program, MQExample2, has similar functions as the MQSeries
Client for Java applet, MQExample1. However, the GUI has fewer text fields,
because there is no need for the TCP/IP hostname, the channel name, or
the port number. This information is only used for a client connection.

Figure 71 on page 121 and Figure 91 on page 142 show the user interface
for the server application. It contains:

6 push buttons to invoke MQSeries functions:

• Connect to a queue manager
• Open a queue

140 Connecting to the Internet with MQSeries and VisualAge for Java
 • Put a message in the queue
• Get a message from the queue
• Close the queue
• Disconnect from the queue manager

2 text fields to name the objects used by the MQSeries APIs:

• Queue manager
• Queue that holds the messages

2 text fields to type an input message and to display an output

message

4 labels to identify the text fields.

Since the MQSeries functions for the client and server are the same and
Java is object oriented, we can re-use the methods created for the client
application. However, there is one exception. The method that connects to
the queue manager does not need the environment settings.

public void connectToQmgr(String queueManagerName) {

try {
// connect to Queue Manager
qMgr = new MQQueueManager(queueManagerName);
System.out.println(″Connected to Queue Manager: ″ +
queueManagerName );
}
catch (MQException ex) {
System.out.println(″An MQ error occured: CC: ″ +
ex.completionCode +
″Reason Code: ″ + ex.reasonCode);
}
}

Figure 90. MQExample2 - Method connectToQmgr

Chapter 6. An MQSeries Application 141

 Figure 91. MQExample2 - Connections

Finally, make the event-to-method and parameter-from-property connections

to connect the push buttons with the appropriate methods. Figure 91 shows
the result.

6.10 How to Test the Application

The MQSeries Client for Java applet can run on the same machine where
you have created the queue manager. You can test how it exchanges
messages with the server application or you can test it alone. In both cases
one local queue is needed to hold the messages.

The diskette provides three sample definition (.tst) files for running client
and server programs on the same machine, and for running the applet and
the application in two machines.

142 Connecting to the Internet with MQSeries and VisualAge for Java
6.10.1 Preparation
Before you test the applet prepare your system with the following steps:
• Make sure that the queue manager is running: strmqm
• Make sure that the Server Connection Channel (SVRCONN) is created
on the MQ Server. You can use SYSTEM.DEF.SVRCONN which is
created as one of the default objects, or you create your own, such as:
DEFINE CHANNEL(MQVAJ.CH1) REPLACE +
CHLTYPE(SVRCONN) +
TRPTYPE(TCP) MCAUSER(′ ′) +
DESCR(′ Server channel for client′ )
• Make sure that a local queue is defined. You may use
SYSTEM.DEFAULT.LOCAL.QUEUE or define your own, such as:
DEFINE QLOCAL(ISHI.SENDQ) REPLACE +
DESCR(′ Queue for input from Java client′ )
• Make sure that the MQSeries channel listener is running:
start runmqlsr -t tcp

6.10.2 Testing the Applet

To start the applet MQExample1 in the appletviewer type:
appletviewer MQExample1.html

To start the server program, open another window and type the command:
java MQExample2

Then fill in the text fields in one or both applets and click on the buttons to
test the MQSeries functions. When the applet is running, you will see a GUI
as shown in Figure 92 on page 144.
• In the Queue Manager Name field, enter the queue manager name to
which you want to connect. If you test both client and server programs,
enter the same name.
• In the Channel Name field, enter the channel name to be used to
connect to the queue manager.
• In the TCP/IP Host Name field, type the TCP/IP host name in which the
queue manager is running.
• In the TCP/IP port number field, type the port number to be used. The
default is 1414.
• Click on the Connect button to connect to the queue manager.

Chapter 6. An MQSeries Application 143

 Figure 92. MQExample1 - GUI

• In the Queue Name field, enter the name of the queue you want to open.
If you test both client and server programs, enter the same name.
• Click on the Open button to open the queue.
• Type some text in the Input Message text field.
• Click on the Send button to put the message in the queue.
• Click on the Receive button to get the message from the queue. This
will display the message in the Output Message text field.

Start your appletviewer from a command prompt in a window and you will
see the various messages produced by the methods. The messages are
only for demonstration purposes. They allow you to see what happens in

144 Connecting to the Internet with MQSeries and VisualAge for Java
 the program when you step from connect to disconnect. Figure 93 on
page 145 shows the messages you see when you get and put a message.

C:\myjava>appletviewer MQExample1.html
Connected to Queue Manager: WTR05405 TCP/IP hostname: wtr05405 Channel
name SYSTEM.DEF.SVRCONN TCP/IP port number 1414
Queue Opened: SYSTEM.DEFAULT.LOCAL.QUEUE
Message hat been put
Message has been gotten
Close Queue
Disconnect from Queue Manager

Figure 93. MQExample1 - Output

6.11 How to Test if the MQSeries Client for Java Works

The MQSeries Client for Java provides a test program you may use to check
if the client/server connection works correctly. From a Java-enabled
browser, such as the Netscape Navigator, connect to a machine that has the
client installed, for example:
http://mercury.itos.ral.ibm.com/mqjavac.html
The HTML file displays the applet shown in Figure 94 on page 146.

To verify your MQSeries Client for Java installation, proceed as follows:

1. In the Hostname entry field, enter the TCP/IP host name of the machine
on which your MQSeries queue manager is running. If you downloaded
this page from a Web server, you may find that the Hostname field has
already been filled in for you.
Note: When you download an applet from a Web server, you can only
communicate with an MQSeries Queue Manager running on the same
machine as the Web server.
2. In the Port entry field, enter the port on which your queue manager
listens for connection requests. The MQSeries default is 1414.
3. In the queue manager entry field, enter the name of the queue manager
to which you wish to connect. If you leave this field blank, the client will
connect to the default queue manager of the target machine.
4. In the channel entry field, enter the name of the MQSeries channel that
the client should use when connecting. Remember that channel names
are case sensitive.

Chapter 6. An MQSeries Application 145

 Figure 94. Verify Installation Program (IVP)

5. The program uses the SYSTEM.DEFAULT.LOCAL.QUEUE that is created

when you create the queue manager.
6. Click on the Test Connection button. A dialog box appears displaying
the results of the test. If the test fails for any reason, please take the
corrective action suggested in the results window and try again.
7. If the window shows the results as shown in Figure 95 on page 147, you
have successfully communicated with your queue manager using the
MQSeries Client for Java.

146 Connecting to the Internet with MQSeries and VisualAge for Java
Figure 95. Verify Installation Results

Chapter 6. An MQSeries Application 147

148 Connecting to the Internet with MQSeries and VisualAge for Java
Chapter 7. The IMS Bridge and MQSeries

This chapter provides a brief description of the IMS bridge and the Open
Transaction Manager Access (OTMA) facility.

7.1 The IMS Bridge and OTMA

Figure 96 on page 150 shows that IMS supports access to the IMS Queue
from VTAM by means of the so called Device Dependent Modules (DDM).
There is one DDM for every LU type that IMS supports.
• The transport layer is done by the Cross System Coupling Facility (XCF)
and not by the network.
• IMS is one of the members of the XCF group.
• The other member of the group is any MVS application that must join
the same XCF group.
• The XCF group members that IMS communicates with, are called OTMA
Clients . IMS is the Server .

Notes:
1. XCF is a communication protocol that allows two different MVS
applications to communicate. The two applications can stay on different
MVS systems provided those MVS systems belong to the same Sysplex
(that means they can communicate over XCF).
2. OTMA and the IMS bridge are implementations of the the XCF protocol.

Through OTMA, clients can send transactions to IMS and receive output
from IMS applications or IMS itself.

OTMA carries on an extension, or prefix, that contains some information that

must be supplied together with the IMS transaction code and the IMS user
data.

Discussing this in great detail is out of the scope of this redbook. However,
you should consider that the prefix contains information such as:
• The user ID that originated the transaction.
• The Tpipe, a term introduced with OTMA, that in the OTMA world takes
the place of the traditional LTERM. In contrast to LTERM, Tpipes do not
need to be assigned in IMS, as they are automatically allocated.
• The type of the message, such as IMS command or IMS transaction.

 Copyright IBM Corp. 1997 149

 Figure 96. Access to IMS

• A variable portion of user data, that is usually used by the client to

correlate output and input. For example, an OTMA client could store
here the IP address of the message originator. The OTMA prefix will

150 Connecting to the Internet with MQSeries and VisualAge for Java
 again be available to the client when the IMS response comes back. So
the client will be able to remember to what IP address the output has to
be sent.

7.2 Benefits of OTMA

For our example, the OTMA Client is the IMS Bridge.

• Existing IMS applications can run without modification and interact with
OTMA clients.
• An OTMA client can submit an IMS transaction and issue commands,
such as /DIS A.
• Messages that go through OTMA can have an extension in the User
Data Section of the message prefix. This allows the client to correlate
the input with the output.
• An OTMA client can implement functions that IMS does not provide.
• OTMA is out of the scope of a traditional COBOL programmer.

Remark
It is the ultimate responsibility of the client application to deliver the
output to the originating end user. IMS cannot deliver it, as it is only
aware of the client.

Figure 96 on page 150 shows, in general, the access to IMS. You can
access IMS from a device through VTAM. In this case OTMA is not
involved. From the same device, you can go through a client that exploits
OTMA. In this case, the device is supported by the client that converses
with IMS through OTMA.

7.3 The IMS Bridge

The IMS Bridge has been the first implementation of OTMA; that is, the IMS
Bridge is MQSeries OTMA support . It is part of MQSeries for MVS/ESA 1.1.4
and higher versions.

MQSeries for MVS/ESA behaves like the client side of an OTMA connection.
It allows any MQI application to integrate IMS transactions. Unlike native
OTMA, the IMS Bridge is simple to use.

Theoretically, the application programmer does not require knowledge of

the OTMA protocol, even though he may build the OTMA header. He could

Chapter 7. The IMS Bridge and MQSeries 151

 ignore the header or, in the end-user application, place it in the MQSeries
message. If it is not there, the IMS Bridge uses defaults.

IMS and MQSeries have interfaced since the first release of MQSeries for
MVS/ESA (1993), through the so called IMS adapter . The IMS adapter is
equivalent to the CICS adapter . The IMS adapter allows an IMS application
to issue MQI verbs, such as MQCONN, MQGET and MQPUT.

An IMS application can be started through the MQSeries trigger service.

This means that an IMS MPP program can be triggered when an MQSeries
message arrives at a queue that is intended to be served by IMS. The
standard trigger mechanism through an Initiation Queue applies.

Figure 97 on page 153 summarizes the (traditional MQSeries) trigger

process of an IMS transaction through the standard trigger mechanism.

With the IMS Bridge, an IMS application can get and put messages to an
MQSeries queue without using explicit MQI verbs. Remember, the IMS
Bridge is an OTMA implementation.

When a generic MQ application sends a message to the MQ queue that is

targeted for IMS, the IMS bridge puts that message into the IMS message
queue, and IMS can schedule the application.

The original message should always contain the return address, that is the
ReplyTo information in the Message Descriptor.

The IMS application can get the incoming message through the standard
IMS interface (GU IOPCB). OTMA and IMS take care of the ″triggering″ and
getting the message to the IMS application.

The IMS application produces its output through the standard IMS interface
(ISTR IOPCB).

The IMS Bridge (and OTMA) maps the IMS outgoing message to a
MQSeries message that is sent to the ReplyToQ and ReplyToQMgr specified
in the incoming message.

The originating generic MQ application can retrieve the response from IMS
with an MQGET call.

The IMS Bridge introduces implicit MQI support. This means that any
application can interact with an IMS application issuing MQI verbs. The IMS
Bridge maps the MQSeries message to an incoming IMS message and
again it maps the outgoing IMS message to an MQSeries queue.

152 Connecting to the Internet with MQSeries and VisualAge for Java
 Figure 97. IMS Standard Triggering with MQSeries

The IMS application is not aware that the partner is an MQI application. To
be more precise, the IMS application is not aware that the transaction has
been entered through OTMA. The same IMS transaction could have been
scheduled either from an old 3270 terminal or from an MQI application in a
client/server environment.

Summary: The IMS Bridge, that is part of MQSeries for MVS/ESA, behaves
like an OTMA client. This means that it communicates to IMS OTMA
through the XCF interface. Figure 98 on page 154 shows the basic flow.

7.4 How to Set Up the IMS Bridge

The IMS Bridge code is part of MQSeries for MVS/ESA and is automatically
installed during the MQSeries installation.

Chapter 7. The IMS Bridge and MQSeries 153

 Figure 98. IMS Bridge - The Basic Flow

IMS and MQSeries communicate over the IMS Bridge, provided that they
belong to the same XCF group. IMS and MQSeries can belong either to the
same MVS system or to different MVS systems that are part of the same
sysplex. In any case, there is no need of a coupling facility, and XCF does
not require it.

The XCF group does not need to be predefined in MVS. It is created as

soon as either IMS or MQSeries joins it.

In order to make IMS and MQSeries communicate, mind what follows:

• In the MQSeries startup parameters, update the macro CSQ6SYSP to
identify:
− The XCF group name MQSeries will have to join (IMS will have to
join the same group)
− The MQSeries member name in the XCF group
− There are more optional parameters not discussed here

154 Connecting to the Internet with MQSeries and VisualAge for Java
Figure 99. IMS Bridge - Detailed View

• In the IMS startup parameters, the following information must be

supplied:
− Specify the XCF group name IMS will have to join to (parameter
G R N A M E = ) . This must match the group name supplied by
MQSeries.
− The IMS member name in the XCF group is automatically set to the
IMS ACB Name (IMS Applid).
− Turn OTMA on by means of the IMS parameter O T M A = Y .
If not, it may be turned on after IMS is started with the command
/STA OTMA.
Note: For further information refer to the MQSeries for MVS/ESA
System Management Guide , SC33-0806, and the IMS/ESA V5 Installation
Guide, Volume 2 , SC26-8024.

Chapter 7. The IMS Bridge and MQSeries 155

 MQSeries for MVS/ESA must know that a queue has to be managed by the
IMS Bridge. To achieve this you have to:
• Define a storage class on any page set that contains the fields
XCFGNAME and XCFMNAME. These fields allow you to point to the XCF
group (XCFGNAME) and to the IMS member name that must be reached
(XCFMNANE).
• Define one or more queues over that storage class.
Messages put to the queue that is defined over that storage class are
automatically ″MQgot″ by the IMS Bridge and transmitted to IMS.

Figure 99 on page 155 illustrates what has been discussed so far.

7.5 The IMS Bridge and the Application

There are two types of messages an MQI application can send to the IMS
Bridge:
• Messages containing IMS data and the IMS Bridge header (MQIIH) are
structured as follows:
<MQIIH> <LLZZ> <Trancode> <IMS user data>
• Messages without the IMS Bridge header have this structure:
<LLZZ> <Trancode> <IMS user data>

If present, the header MQIIH is used by the MQSeries IMS Bridge. An

MQIIH should be and probably will always be present. Messages coming
back from the IMS Bridge have the same format:
• If the original messages had an MQIIH, the response will have it, too.
• If the original message did not have an MQIIH, neither will the response.

The fields LL and ZZ have the traditional IMS meaning:

LL Length of the IMS message
ZZ Reserved by IMS, should be passed as binary 0
If the MQSeries Bridge header MQIIH is not specified, IMS makes the
following assumptions:
• The transaction code is non-conversational.
• The transaction is in commit mode 0 (commit then send).
• The Format field of the Message Descriptor is passed to the IMS
application as the Map Name.
• The security mode is MQISS_CHECK

156 Connecting to the Internet with MQSeries and VisualAge for Java
The message that is passed to IMS can be built from several segments
which must be concatenated. Examples of how such a message could look
are:
<MQIIH> <LLZZ> <Trancode> <IMS user data> <LLZZ> <Data> ....

<LLZZ> <Trancode> <IMS user data> <LLZZ> <Data> ....

The following shows the parts of an MQ message with an MQIIH that is sent
to IMS:

Table 12. Message Layout

MQMD MQIIH IMS Message
MsgType Format
ReplyToQ ReplyToFormat
ReplyToQMgr LTermOverride LL ZZ Data LL ZZ Data
Format MFSMapName
UserIdentifier Authenticator
..
Persistence .
MsgId
Correlid
..
.

Note: For the complete details of the fields contained in the Message
Descriptor and IMS Header, refer to the MQSeries Application Programming
Reference , SC33-1673.

Table 12 shows some of the most important fields. For example, note that
the UserIdentifier of the message is part of the standard Message
descriptor. This field will definitely be passed on to the IMS application if
the proper security options are in effect, and it is carried in the Message
Descriptor, as is usual in the MQSeries world.

The IMS header contains other information that is more specific to the IMS
world. If for example, the IMS program that has to be run has some
dependencies on the LTERM or the MOD name, this information can be
supplied with the fields LTermOverride and MFSMapName.

The field Authenticator can contain the user password that allows IMS to
identify the user ID when the appropriate security options are set.

Through the fields TranState and TranInstanceId, the MQI program that is
partner of IMS can understand whether or not the IMS application is in
conversation, as this word is defined in IMS.

Chapter 7. The IMS Bridge and MQSeries 157

 The field CommitMode allows the IMS partner program to choose how IMS
should manage the commit protocol. The choices are:
• COMMIT_THEN_SEND:
IMS commits the program updates and queues the output to the IMS
queue. Then OTMA begins to send the output to the IMS Bridge. ″IMS
people″ will see that this is the traditional IMS way to manage the
output.
• SEND_THEN_COMMIT:
IMS sends the output to the IMS Bridge and then it begins to commit.
This option causes a longer occupancy of the IMS MPP region, but it is
the only one available with fastpath and conversational transactions.

The incoming message (request) should always contain the following two
fields:
• Reply-To-Queue
• Reply-To-Queue Manager

This ″return address″ allows the IMS Bridge to send responses back to the
originating system. The response includes:
• Replies from the IMS application
• Messages from IMS when it is not able to complete the transaction, for
example the transaction is stopped.

If the IMS Bridge is not able to put the reply message on the reply-to-queue,
for any reason, such as the reply-to-queue has not been supplied, it puts it
into the Dead-Letter queue. If this also fails, the traffic between IMS and the
IMS Bridge could stop, so impacting the entire system.

7.6 Some Tips about Data Conversion

It is recommended that data conversion is carried out by MQSeries for MVS.

The incoming message is converted when it is put on the queue whose

Storage Class has the XCF information associated with it.

The outgoing message is converted by the host sender channel which

should have CONVERT(YES) specified.

Conversion is done automatically (no exit required) if:

• The messages have the standard structure:
<MQIIH> <LLZZ> <IMS Data>

158 Connecting to the Internet with MQSeries and VisualAge for Java
 • The Message Descriptor specifies Format=MQFMT_IMS
• The IMS Header MQIIH specifies both:
Format=MQFMT_IMS_VAR_STRING
ReplyToFormat=MQFMT_IMS_VAR_STRING

We recommend not to underestimate the conversion problem that must be

done, so that the message is received by IMS in the proper format.

When using messages structured with the MQIIH, we recommend that the
IMS part is all text, apart from LL and ZZ fields. This is quite common in the
IMS world, as the IMS users, usually, send text data to the IMS transactions.

If this assumption applies, the Format field in the Message descriptor must
be MQFMT_IMS, while the Format field in the MQIIH must be
MQFMT_IMS_VAR_STRING. This way, conversion is done automatically for
IMS by MQSeries.

It could happen that the incoming message originated in a non-MVS

machine, such as AIX. Nevertheless, the message should be forwarded
through a channel with the option CONVERT(NO), and allow the host to
convert it. If the channel had CONVERT(YES), the non-MVS machine could
try to translate the message, and this could lead to some mistake if the
MQSeries installed on that machine does not have the capability to translate
this particular format.

Response messages also need to be translated. Do not forget that

response messages still have the structure MQIIH + LLZZ + IMS data.
That′s why the field ReplyToFormat exists. The translation of response
messages should be done again by the host, using the CONVERT(YES)
option of the host sender channel.

If the incoming message has the format LLZZ + IMS data, that is, there is
no MQIIH header, the Format field of the Message descriptor should be
MQFMT_IMS_VAR_STRING. The same recommendation applies: messages
should always be translated at the host.

If the IMS message is not made up of text only, but, for example, it contains
binary and packed decimals, it should be translated under user
responsibility. The user should supply the conversion exits, possibly in the
host environment, with a conversion logic that is user-dependent.

Chapter 7. The IMS Bridge and MQSeries 159

7.7 Some Hints for Implementation
IMS and MQSeries share the concept of asynchronous application design.
So they have been well accepted by IMS customers since the beginning.

IMS applications can be interfaced over a variety of protocols, like APPC or

DCE. APPC is generally considered hard to program and many developers
tend not to use it.

On the opposite side, the MQI is considered to have a user friendly

interface, is easy to understand and easy to program. Additionally,
MQSeries offers a robust asynchronous environment, that allows the
customer to design connectionless applications.

Sometimes, the IMS Bridge has been used to interface IMS transactions
with other IMS transactions, even in the same IMS system. This can happen
when there is a need to implement the concept of ″workflow management″
where the business is divided into ″business requests″. A business request
is typically made up by more than one IMS transaction. Consider the
example of opening a new checking account at a bank. The teller should
run the transaction that collects general data about the customer, such as
name, address and so on. Then the teller should enter the transaction that
opens a new account. After that he should probably run the transaction that
delivers the check books.

Probably, all these transactions already exit in the bank information system,
and they could be reused.

A possible solution is to have a BMP that collects business requests from

the network. MQSeries could be used to connect branch offices with the
host.

When the BMP has received the request and validated it, it starts a MPP
region that could take the charge of the business request. This MPP
program, in turn, can use the IMS Bridge to schedule the existing IMS
transactions that make up the business request. If this program is smart
enough, it could start all the transactions at the same time, getting the
answers when all of them have finished. This could lead to a higher
parallelism of the business.

There are other customers who have decided to use the IMS Bridge instead
of the MQSeries trigger mechanism, because of the better scheduling
mechanism that IMS offers compared with the mechanism offered by the
MQSeries trigger.

160 Connecting to the Internet with MQSeries and VisualAge for Java
Chapter 8. Connecting the Internet to IMS

In Chapter 6, “An MQSeries Application” on page 119, we covered how to

use the MQSeries Client for Java for functions such as connect to and
disconnect from a queue manager, open and close a queue, and put and get
messages. We will build on this knowledge and put it to use to write a
real-world application.

In this chapter, we describe how to write a program, with VisualAge for Java
and MQSeries, that connects the user of an Internet or Intranet terminal to a
legacy system, in this case IMS on MVS. In the following sections, we
discuss:
• The purpose of the applet and application
• What software is needed
• What to do before running the example
• The logic of the applet
• How to create the applet with VisualAge for Java
• The logic of the Java application
• How to create the application with VisualAge for Java

8.1 The Purpose of the Example

We write this example to demonstrate how to use MQSeries and Java as a
way to access enterprise data over the Internet. VisualAge for Java is the
programming language of choice.

The user of the example is able to access an IMS application from a Web
browser. A Java applet runs within the browser and displays a GUI
containing an employee record request form. The user inputs fields and
submits the form. The request is sent to an MQSeries queue on the Web
server. There, a Java application is triggered which gets the message off
the queue, logs the transaction to a file, and forwards the message to a
queue on the MVS system. The IMS application retrieves the message,
processes the request, and sends the reply back to an MQSeries queue on
the Web server. The Java applet then gets the reply message off the queue
and displays the result within the Web browser.

Figure 100 on page 162 illustrates the message flow. If you want to run this
example on your system you need to implement (or model) a similar
systems design.

 Copyright IBM Corp. 1997 161

Figure 100. Design and Message Flow between WWW and IMS

We use the typical 3-tier architecture:

1. The first tier or presentation logic is the applet running within the Web
browser.
2. The middle tier or business logic is a Java application running in a
Windows NT server.
3. The third tier or data logic is the IMS application on MVS.

8.2 Software and Setup

To run this example, you need the following software:
1. For the first tier or client, which can be any system that is Java-enabled,
you need one of the following:
• A Web browser
• An applet viewer (provided with the JDK)
2. On the middle tier, which runs on Windows NT, you need:
• A Web server
• MQSeries Version 5

162 Connecting to the Internet with MQSeries and VisualAge for Java
 3. On the third tier, the MVS system, the following is required:
• IMS
• IMS Bridge
• IMS sample application IVTNO (shipped with the product)
• MQSeries Server
4. For development install on any platform which supports VisualAge for
Java:
• VisualAge for Java 1.1
• JDK (we are using 1.1.4)

8.2.1 Setting Up MQSeries to Run the Example

Two MQSeries MQSC definition files are shown in Appendix A, “MQSeries
Objects for WWW/IMS Application” on page 197 and supplied on the
diskette. One is for the Web server and one for the mainframe. You have to
modify some attributes and replace them with values that fit your own
MQSeries environment, such as ConnectionName in the channel definition.

With the file WEBSRVR.TST, you create the queue manager objects for the
Web server machine. The file can be run through the runmqsc facility. This
assumes that a queue manager is running on the Web server.
WEBSRVR.TST creates the following objects:
• Three local queues used by the application and applet
• One transmission queue
• One sender channel to MVS system
• One receiver channel from MVS system
• One process for triggering the channel

Use the file MVS.TST on the MVS system. Run it through the batch utility on
MVS or define the objects through the MQSeries panels. Again, you need to
have a functioning queue manager on this system. MVS.TST contains
definitions for the following:
• One local queue used by the IMS Bridge
• One transmission queue
• One sender channel to Web server machine
• One receiver channel from Web server machine
• One process for triggering the channel

Chapter 8. Connecting the Internet to IMS 163

8.2.2 How We Did It in the Lab
We modeled the three tiers in the lab by using the applet viewer to run the
applet from a client on Windows NT (not using the MQSeries server). The
Java applet connected to another Windows NT machine which had an
MQSeries server installed. The MQSeries queue manager on that system
communicated with a queue manager on MVS.
Note: We did not use the Web server in the example. This could easily be
implemented by configuring the Web server to access the HTML page. We
used the applet viewer to access the HTML page instead.

8.2.3 MQSeries Client for Java and MQSeries Bindings

The Java bindings, included with Version 5, are used for writing Java
applications. Java applications do not run in a Web browser. You have to
import com.ibm.mqbind into your Java application in order to enable your
application to communicate with MQSeries. Your application must run on a
machine where an MQSeries server is installed.

The MQSeries Client for Java is used to write Java applets. You have to
import com.ibm.mq in your applet program in order to communicate with
MQSeries as a client. You do not need an MQSeries server on the machine
where the applet runs.

8.3 The Logic of the Java Applet

Below is the HTML file that loads the applet:
<HTML>
<HEAD>
<TITLE>MQTelephone</TITLE>
</HEAD>
<BODY>
<APPLET code=″EmployeeRecord.class″ height=″430″ width=″649″>
</APPLET>
</BODY>
The applet loads and displays the GUI shown in Figure 101 on page 167.
The program logic is as follows:
• It connects to the queue manager in the Web server via a client
connection.
• It opens the input and output queues.
• The user types data into the input fields and selects an action from a
choice list.
• When the user clicks on the Submit button, the program reads the user
data from the text fields.

164 Connecting to the Internet with MQSeries and VisualAge for Java
 • It creates a message, formatting the user data into a valid IMS
transaction.
• The message is put on the output queue, destined for the IMS
application in the host.
Note: The queues for the client application are managed by the MQM
that resides in the Web server machine.
• It waits until the reply message from IMS arrives in the input queue
located in the Web server machine.
• It parses the reply message and displays the result of the requested
action in the text fields of the applet.

8.4 Creating the Java Applet Using VisualAge for Java

Before you proceed with this example you should have read Chapter 5,
“Java and VisualAge for Java Overview” on page 87 and Chapter 6, “An
MQSeries Application” on page 119 to become familiar with VisualAge for
Java.

8.4.1 Start VisualAge for Java

Bring up VisualAge for Java from the Start menu or from an icon. The
executable is in the following (default) directory:
C:\IBMVJava\Ide\program\IDE.EXE

8.4.2 Add a New Project and Package

Click on Cancel in the VisualAge Quick Start menu if it comes up on your
screen.

To add a new project for development of the applet, follow these steps:
• With the right mouse button, click on the upper half of the Workbench
window.
• Select Add Project from the pop-up.
• Type a name, such as RedbookExamples, in the subsequent SmartGuide
- Add Project window.
• Click on Finish and the project will be created.

Then add a new package for the applet in the following way:
• Make sure that the newly created project is highlighted.
• With the right mouse button, click on the upper half of the Workbench
window.

Chapter 8. Connecting the Internet to IMS 165

 • Select Add Package from the pop-up.
• Type a name, such as mqjava, in the subsequent SmartGuide - Add
Package window.
• Click on Finish to create the project.

8.4.3 Quick Start to Create an Applet

Using the VisualAge Quick Start window is a quick way to start building an
applet. Follow these steps:
• In the Workbench, make sure that the correct package is selected.
• Select Quick Start from the Window menu.
• In the Quick Start window, select Create a new applet and click on OK.
• In the SmartGuide - Create Applet window, type the name of the applet,
such as EmployeeRecord.
• In the same window, enter the names of the project and package you
have chosen previously.
• Select Design the applet visually.
• Click on Finish.
Now you should see the Visual Composition editor with nothing but a dotted
square in it that marks the boundaries of the applet.

8.4.4 Building the GUI

Use the Visual Composition editor to build the GUI portion of the applet that
will be displayed within the Web browser. As described in 5.4.1, “Creating
Objects” on page 103, you choose from the icons on the left hand side of
the editor. The right side is the actual working area in which you develop
your applet. The GUI is the area within the dotted square.

To display a button, for example, click first on the button category icon in
the left of the two columns. Then choose from the right column a button
type, such as the push button. Click on it and move the cursor in the white
space in the editor. To drop the object, click the left mouse button. This
creates a button in the GUI. You can move or resize it within the dotted
rectangle.

Before you start building the GUI, you may want to enlarge the editor
window and also the viewable area of the applet. To make the GUI bigger,
click somewhere inside the dotted rectangle so that small black squares
appear in each corner. Then grab one of the black corners and drag it until
you think the size is right.

166 Connecting to the Internet with MQSeries and VisualAge for Java
Figure 101. WWW-IMS Example - Employee Record Layout

The GUI in Figure 101 on page 167 contains:

4 text fields for the name, phone extension and ZIP code

2 push buttons to submit a request and to clear the GUI

6 labels that describe the fields and the applet itself

1 choice list from which the user can choose an action

Chapter 8. Connecting the Internet to IMS 167

 1 text area to display messages from IMS

If you want to change the text properties for the labels and buttons
double-click on the object and change the text field (for labels) and label
field (for buttons).

8.4.5 Import MQSeries Client for Java Classes

You must import the MQSeries Client for Java classes into your applet in
order for the applet to use MQI APIs.

Figure 102. Hierarchy - Import MQSeries Client Classes

• Click on the Hierarchy tab in the editor window.

• Expand the class hierarchy from java.lang.Object to
mqjava.EmployeeRecord by clicking on the + sign.
• Click on mqjava.EmployeeRecord. This displays the code VisualAge for
Java generated.
• Add the statement that imports the MQSeries Client for Java classes, as
shown in bold below.
import java.applet.*;
import java.awt.*;
import com.ibm.mq.*;
/**
* This applet was generated by a SmartGuide.
*
*/
public class EmployeeRecord extends Applet {
}

168 Connecting to the Internet with MQSeries and VisualAge for Java
 The applet needs the classes to communicate with MQSeries via the
client connection.

8.4.6 Create Instance Variables

We have to define some instance variables for the class that will be used by
various methods in the applet. In the same window used above, add the
following statements to the body of the source code:
private MQQueue accessInputQueue = null;
private MQQueue accessOutputQueue = null;
private MQQueueManager qMgr = null;
private String OutExtension = null;
private String OutFirstName = null;
private String OutLastName = null;
private String OutZipCode = null;

Now save the code. With the right mouse button, click somewhere in the
source code area and select Save from the menu. You also want to save
the workspace.

8.4.7 Populate the List Box

The choice list box allows the user to add and delete employees, and to
update and display information in their records. We have to write the code
that will populate the list box with text that specifies one of these actions.
This is done in the getChoice1() method associated with the list. Choice1 is
the default bean name if their is only one choice list. If you change this
name in the Properties window of the object the method name will change,
too.

We add one item for each of the four actions to the list
DISPLAY
ADD
UPDATE
DELETE
• You can open the method getChoice1() three ways:
− From the Projects tab in the Workbench
− From the Methods tab in the editor window
− From the Hierarchy tab in the editor window
Scroll down to the method getChoice1() and click on it. The code
generated by VisualAge will appear.
• Add your (user) code as shown in bold in Figure 103 on page 170.

Chapter 8. Connecting the Internet to IMS 169

 private Choice getChoice1() {
if (ivjChoice1 == null) {
try {
ivjChoice1 = new jawa.awt.Choice();
ivjChoice1.setName(″Choice1″ ) ;
ivjChoice1.setBounds=(220, 274, 125, 30);
// user code begin {1}
ivjChoice.addItem(″DISPLAY ″ ) ;
ivjChoice.addItem(″ADD ″);
ivjChoice.addItem(″UPDATE ″ ) ;
ivjChoice.addItem(″DELETE ″ ) ;
// user code end
} catch (java.lang.Throwable ivjExc) {
// user code begin {2}
// user code end
}
};
return ivjChoice1;
}

Figure 103. WWW-IMS Example - Populating the List Box

• Make sure that these four strings are exactly 8 characters long. Pad
them with blanks at the end. This is important for the message format
we send to IMS.
• Now you can test if the list box works. Go to the Visual Composition

editor and click on the Test button , then on Run in the

subsequent window and the applet will appear. You should be able to
select any of the four functions.

8.4.8 Program the Clear Button Functions Visually

When the Clear button is pressed, all fields in the GUI will be cleared and
the choice list set to the default. We need to build Event-to-Method
connections between the Clear button and the text fields, text area, and
choice box. We specify that, when the actionPerformed event occurs, the
event method clears the fields with a value specified as a parameter.
• Click on the Visual Composition tab.
• Build the connection between the Clear button and the text field Last
Name as follows:
− With the left mouse button, click on the Clear button.

170 Connecting to the Internet with MQSeries and VisualAge for Java
− With the right mouse button, click once on the Clear button again.
− From the menus choose Connect and then
actionPerformed(java.awt.event.ActionEvent).
− The pointer changes to a spider. Move the spider into the text field
Last Name and click the left mouse button.
− From the menu, select text.
− You should now see a dotted line from the Clear button to the text
field. Click once with the left mouse button on the line so that it is
highlighted.
− With the right mouse button, click on the same line and choose
Properties from the menu. You will see the Event-to-method
connection properties.

− Click on the Set Parameters button in that window.

− With the left mouse button, click on the field directly under the value
column.
− Type in a single space and then hit OK.

− Hit OK again to get out of the dialogue window. The line should now
be solid instead of dashed.

Chapter 8. Connecting the Internet to IMS 171

 Figure 104. WWW-IMS Example - Clear Button Connections

• Repeat the above steps to create connections from the Clear button to
the other three text fields.
• In the same way, build a connection between the Clear button and the
text area on the bottom of the GUI. .
• Create another actionPerformed connection from the Clear button to the
choice list. Instead of specifying ″text″ as the method, choose
select(java.lang.String).
• Double click on the resulting dashed line to bring up the
event-to-method dialogue window.
• Click on the Set Parameters button and type as value for str DISPLAY,
followed by one space. The value must be eight characters long.

172 Connecting to the Internet with MQSeries and VisualAge for Java
 • Click on OK and again in the next window. This will cause the list box
to show DISPLAY when the clear button is pressed.
Figure 104 on page 172 shows the connections we just made.

Now save the GUI. From the file menu, choose Save Bean. You can run the
applet developed so far and test if the clear functions work.

Select Test from the Tools menu or click on the test button shown
on the left. In the subsequent Settings window, click on Run.

8.5 Creating the Methods

We need methods that execute MQSeries functions, such as connecting to
the queue manager and opening queues, and for the processing initiated by
the Submit button. No methods are required for the Clear button functions.
We programmed them visually in the previous section.

The methods we have to write are in Table 13.

Table 13 (Page 1 of 2). WWW/IMS Example - Methods

Method Name Description Called by
connectToQmgr Connect to the queue start()
manager
openInputQueue Open an input queue start()
openOutputQueue Open an output queue start()
FormatToIMSmessage Formats the message into
an IMS transaction
putMessage Puts a message on the
queue for IMS
retrieveMessage Get a message from a
queue and parse it
closeInputQueue Close an input queue stop()
closeOutputQueue Close an output queue stop()
disconnectFromQmgr Disconnect from the queue stop()
manager
start Applet starts Java
stop Applet stops Java
GetLastName Get last name from input retrieveMessage

Chapter 8. Connecting the Internet to IMS 173

 Table 13 (Page 2 of 2). WWW/IMS Example - Methods
Method Name Description Called by
GetFirstName Getter first name from retrieveMessage
input
GetExtension Getter extension from input retrieveMessage
GetZipCode Getter zip code from input retrieveMessage

8.5.1 Connect to the Queue Manager

Before we can do any messaging we have to connect to a queue manager.
In this first method, we set up the MQSeries environment for the client and
then create a new queue manager object. By creating a new queue
manager object, the Java program is connecting to the specified queue
manager. Any MQExceptions are caught. The method is executed when the
applet starts.

Table 14. WWW/IMS Example - Method connectToQmgr and Parameters

Method connectToQmgr()
Input String queueManagerName QMgr name
String hostname TCP/IP host name
String channel Channel of type SVRCONN
String portnumber TCP/IP port (default 1414)
Return void

Create the method connectToQmgr with the following steps:

• Click on the Methods tab to bring up the methods editor. You will see a
list of all methods generated for the applet by VisualAge for Java.
• From the Methods menu select New Method.
• In the SmartGuide window, shown in Figure 73 on page 124, type the
name of the method and the parameters from Table 14.
void connectToQmgr (String queueManagerName, String hostname,
String channel, String portnumber)
Note: Write it in one line!
• Click on Next and then on Finish. VisualAge for Java creates the
method, adds it name to the methods list, and displays the skeleton
code it generated in the bottom of the window.
• You now can insert the code shown in Figure 105 on page 175.

174 Connecting to the Internet with MQSeries and VisualAge for Java
 try {
int portnum;
try {
portnum = new Integer(portnumber).intValue(); // convert String to Int
} catch (NumberFormatException ex) {
portnum = 1414; // set port to default value
}
// setup MQEnvironment
MQEnvironment.hostname = hostname;
MQEnvironment.channel = channel;
MQEnvironment.port = portnum;
// connect to Queue Manager
qMgr = new MQQueueManager(queueManagerName);
}
catch (MQException ex) {
System.out.println(″An MQ error occured : Completion code″ + ex.completionCode +
″ Reason code ″ + ex.reasonCode);
}

Figure 105. WWW-IMS Example - Method connectToQmgr

try {
int openOptions = MQC.MQOO_INPUT_AS_Q_DEF | MQC.MQOO_FAIL_IF_QUIESCING;
accessInputQueue = qMgr.accessQueue(queueName,openOptions);
}
catch (MQException ex){
System.out.println(″An MQ error occured : Completion code″
+ ex.completionCode + ″ Reason code ″ + ex.reasonCode);
}

Figure 106. WWW-IMS Example - Method openInputQueue

try {
int openOptions = MQC.MQOO_OUTPUT | MQC.MQOO_FAIL_IF_QUIESCING;
accessOutputQueue = qMgr.accessQueue(queueName,openOptions);
}
catch (MQException ex){
System.out.println(″An MQ error occured : Completion code″
+ ex.completionCode + ″ Reason code ″ + ex.reasonCode);
}

Figure 107. WWW-IMS Example - Method openOutputQueue

Chapter 8. Connecting the Internet to IMS 175

8.5.2 Open Input and Output Queues
The two methods used to open input and output queues are created in the
same fashion as the previous one. Their parameters are in Table 15 and
Table 16. The code to add to the skeleton generated by VisualAge for Java
is in Figure 106 on page 175 and Figure 107 on page 175.

Table 15. WWW-IMS Example - Method openInputQueue and Parameters

Method openInputQueue()
Input String queueName Name of input queue
String queueManagerName Name of queue manager
Return void

Table 16. WWW-IMS Example - Method openOutputQueue and Parameters

Method openOutputQueue()
Input String queueName Name of input queue
String queueManagerName Name of queue manager
Return void

8.5.3 Format the Message for IMS

We need a method that formats the MQSeries message into an IMS
transaction. The IMS sample application expects the message in a specific
format or it will not work. Table 17 shows what parameters are needed.

Table 17. WWW-IMS Example - Method formatToIMSmessage and Parameters

Method formatToIMSMessage()
Input String LastName Last name from GUI
String FirstName First name from GUI
String Extension Phone extension from GUI
String ZipCode ZIP code from GUI
String Command Command from choice list
Return inputMsg Message queue object for
putMessage()

The code is in Figure 108 on page 177.

176 Connecting to the Internet with MQSeries and VisualAge for Java
 Notes:
1. First we create the string FormattedIMSData. Later we move into it the
message sent to IMS.
2. Then we convert all user input to uppercase.
3. We make sure that the input fields are 10 characters long, except the zip
code which is seven characters long. Longer fields are truncated,
shorter fields padded with blanks. This is required because the IMS
bridge expects the message in a particular format. Refer to 7.5, “The
IMS Bridge and the Application” on page 156.
4. Next, we move the fields into the string created earlier in the format that
the IMS Bridge expects. At the beginning is the transaction code IVTNO.
5. Then we create a new message object and write into the message
buffer LLZZ followed by the string FormattedIMSData. In this example,
we do not define an IMS header (IIH); the IMS Bridge will use the
default.
6. The message queue object is returned for processing by the
putMessage method.

public MQMessage formatToIMSmessage(String LastName, String FirstName,

String Extension, String ZipCode, String Command) {
// Create String variable to hold formatted data passed in by user

String FormattedIMSData;

// Uppercase all inputs

LastName = LastName.toUpperCase();
FirstName = FirstName.toUpperCase();
Extension = Extension.toUpperCase();
ZipCode = ZipCode.toUpperCase();
Command = Command.toUpperCase();

// Make sure the strings are the required length

if (LastName.length() > 10) {

LastName=LastName.substring(0,10);
}
else while (LastName.length() < 10) {
LastName=LastName.concat(″ ″);
}

Figure 108 (Part 1 of 2). WWW-IMS Example - Method formatToIMSmessage (Part 1)

Chapter 8. Connecting the Internet to IMS 177

 if (FirstName.length() > 10) {
FirstName=FirstName.substring(0,10);
}
else while (FirstName.length() < 10) {
FirstName=FirstName.concat(″ ″);
}
if (Extension.length() > 10) {
Extension=Extension.substring(0,10);
}
else while (Extension.length() < 10) {
Extension=Extension.concat(″ ″);
}
if (ZipCode.length() > 7) {
ZipCode=ZipCode.substring(0,7);
}
else while (ZipCode.length() < 7) {
ZipCode=ZipCode.concat(″ ″);
}

// Put user data in string for later use

FormattedIMSData = ″IVTNO ″ + Command + LastName + FirstName
+ Extension + ZipCode;
// ITVNO = 10 chars
// Create new message object for putting message
MQMessage inputMsg = new MQMessage();
try {
// Write message into the message buffer
// No MQIIH structure is defined

inputMsg.writeShort(59); // LL
inputMsg.writeByte(01); // ZZ
inputMsg.writeByte(01); // ZZ
inputMsg.writeString(FormattedIMSData);
}
catch (java.io.IOException ex) {
System.out.println(″An I/O error occurred while
writing message to the buffer: error code″ + ex);
}

// Return formatted message ready for IMS

return inputMsg;
}

Figure 108 (Part 2 of 2). WWW-IMS Example - Method formatToIMSmessage (Part 1)

178 Connecting to the Internet with MQSeries and VisualAge for Java
8.5.4 Put the IMS Message on the Queue
This method is executed after the message has been assembled by the
formatting method discussed above. As input, it receives the complete
message.

Table 18. WWW-IMS Example - Method putMessage and Parameters

Method putMessage()
Input MQMessage toIMSMsg Message put together by
formatToIMSmessage
Return messageID Message ID of the message
sent to IMS

Important data in the message descriptor is the return address (queue and
queue manager name). The program returns the message ID that will be
used by the retrieveMessage method.

public byte[ ] putMessage ( MQMessage toIMSMsg) {

try {
// create new PutMessageOption object
MQPutMessageOptions pmo = new MQPutMessageOptions();
pmo.options = MQC.MQPMO_NO_SYNCPOINT ;

// Build the message descriptor

toIMSMsg.messageType=MQC.MQMT_REQUEST;
toIMSMsg.replyToQueueManagerName = ″ABCDEFGH″ ;
toIMSMsg.replyToQueueName = ″fromIMSqueue″ ;
toIMSMsg.format = ″MQIMSVS″ ;
toIMSMsg.messageId = MQC.MQMI_NONE;
toIMSMsg.report = MQC.MQRO_COPY_MSG_ID_TO_CORREL_ID;

// put the message into the queue

accessOutputQueue.put(toIMSMsg,pmo);
}
catch (MQException ex) {
System.out.println(″An MQ error occured : Completion code″
+ ex.completionCode + ″ Reason code ″ + ex.reasonCode);
}
return(toIMSMsg.messageId);
}

Figure 109. WWW-IMS Example - Method putMessage

Chapter 8. Connecting the Internet to IMS 179

 public String retrieveMessage (byte[ ] putMsgId ) {

// Create string for final output

String DataForDisplay = ″ ″ ;

try {
// create new message object for getting message
MQMessage fromIMSMsg = new MQMessage();

// Set msgid to correlid

fromIMSMsg.correlationId = putMsgId;

// create new GetMessageOption object

MQGetMessageOptions gmo = new MQGetMessageOptions();
gmo.options = MQC.MQGMO_WAIT| MQC.MQGMO_ACCEPT_TRUNCATED_MSG |
MQC.MQGMO_CONVERT | MQC.MQGMO_NO_SYNCPOINT;
gmo.waitInterval = 15000; // set wait to 15 sec

// get the message from the queue

accessInputQueue.get(fromIMSMsg,gmo);

// read in the error(return) message from the IMS application

fromIMSMsg.seek(4); // offset the first 4 bytes
DataForDisplay = fromIMSMsg.readString(40);

// now read in the output data that we are looking for

fromIMSMsg.seek(52); // offset 52 bytes
OutLastName = fromIMSMsg.readString(10); // read in the last name
OutFirstName = fromIMSMsg.readString(10); // read in the first name
OutExtension = fromIMSMsg.readString(10); // read in the extension
OutZipCode = fromIMSMsg.readString(7); // read in the zip code
}
catch (MQException ex) {
System.out.println(″An MQ error occured : Completion code″
+ ex.completionCode + ″ Reason code ″ + ex.reasonCode);
DataForDisplay = ″The connection to IMS was broken.
Cannot process request now.″ ;
}
catch (java.io.IOException ex) {
System.out.println(″An I/O error occured while writing message
to the buffer: error code″ + ex);
}
return DataForDisplay;
}

Figure 110. WWW-IMS Example - Method retrieveMessage

180 Connecting to the Internet with MQSeries and VisualAge for Java
 The format of the IMS message is:

HDR IMS info LLZZ Last First Phone Zip

name Name
4 44 8 10 10 10 7

8.5.5 Get and Parse a Message

This method gets a message sent by IMS from the queue and displays its
contents in the applet. The program issues an MQGET and waits up to 15
seconds for the reply from the host, then it times out and assumes that the
connection to IMS is broken.

Table 19. WWW-IMS Example - Method retrieveMessage and Parameters

Method retrieveMessage()
Input byte [ ] putMSGId Message ID of reply message
Return DataForDisplay Text to be displayed in the text
box

The code for this method is in Figure 110 on page 180.

Notes:
1. A string to hold the message from IMS is defined.
2. A new message object, fromIMSMsg, is created.
3. The message ID given by the putMessage method is stored as
correlation ID in the message header of the message object.
4. In the get message options, it is specified to wait up to 15 seconds for
the message to arrive. Data has to be converted by MQSeries.
5. The message is gotten from the queue and stored in the message object
fromIMSMsg.
6. The first four bytes are skipped, and the following 40 bytes are displayed
in the text area.
7. From the data IMS prepared, four fields are extracted and displayed in
the text fields.
8. If the reply from the host does not arrive in time, an error message is
displayed in the text area.

Chapter 8. Connecting the Internet to IMS 181

8.5.6 Close Input and Output Queue
The methods to close the input and output queues are straight forward. No
parameters are necessary. The code is shown in Figure 111 and
Figure 112.

public void closeInputQueue ( ) {

try {
accessInputQueue.close();
}
catch (MQException ex) {
System.out.println(″An MQ error occurred : Completion code″
+ ex.completionCode + ″ Reason code ″ + ex.reasonCode);
}
}

Figure 111. WWW-IMS Example - Method closeInputQueue

public void closeOutputQueue ( ) {

try {
accessOutputQueue.close();
}
catch (MQException ex) {
System.out.println(″An MQ error occurred : Completion code″
+ ex.completionCode + ″ Reason code ″ + ex.reasonCode);
}
}

Figure 112. WWW-IMS Example - Method closeOutputQueue

8.5.7 Disconnect from the Queue Manager

This method is shown in Figure 80 on page 131.

8.5.8 Start Method

This method is invoked when the applet starts and when the user clicks on
Back in a browser to return to the applet. It calls three methods and
provides the necessary parameters.

8.5.9 Stop Method

This method is executed when the user switches to another HTML page. It
closes the queue and disconnects from the queue manager.

182 Connecting to the Internet with MQSeries and VisualAge for Java
 public void start() {

connectToQmgr(″WTR05402″, ″WTR05402″, ″SYSTEM.DEF.SVRCONN″, ″1414″);

openOutputQueue(″toIMS″, ″WTR05402″ ) ;
openInputQueue(″fromIMSqueue″, ″WTR05402″ ) ;
}

Figure 113. WWW-IMS Example - Start Method

public void stop() {

closeOutputQueue();
closeInputQueue();
disconnectFromQmgr();
}

Figure 114. WWW-IMS Example - Stop Method

8.5.10 Getter Methods for User Data

Since the user data is private data to the class, we can use ″getter
methods″ as shown in Figure 115 to extract the values. The methods are
called from the retrieveMessage method to extract data to be displayed in
the text fields.

public String getLastName( ) {

return OutLastName;
}

public String getFirstName() {

return OutFirstName;
}

public String getExtension() {

return OutExtension;
}

public String getZipCode() {

return OutZipCode;
}

Figure 115. WWW-IMS Example - Getter Methods

Chapter 8. Connecting the Internet to IMS 183

8.6 Submit Button Connections
The Submit button initiates all processing required to send a request and
receive a reply from the IMS application. It invokes three methods which
perform the following:
1. Get the information from the input field and build a message that the
IMS program can work with. The message is handed over to the next
method.
2. Put the message on the queue and hand the message ID over to the
next message.
3. Wait for a reply message and display its contents in the applet. Display
an error message when the message does not arrive within 15 seconds.

8.6.1 Connect Button to Method

First, create an event-to-method connection between the Submit button and
the formatToIMSmessage method.
• Bring up the Visual Composition editor.
• With the left mouse button click on the Submit button.
• With the right mouse button click on the Submit button.
• From the menus select Connect and then actionPerformed.
• Drag the spider to the white area outside the border of the applet
(dotted line) and drop it by clicking the left mouse button.
• From the menu, select All Features.
• Scroll down the methods column until you find the method
formatToIMSmessage. Select it and click on OK.
• You should now see a dotted line running from the Submit button to the
white space outside the applet.

Figure 116. WWW-IMS Example - Connect Button to Method

184 Connecting to the Internet with MQSeries and VisualAge for Java
8.6.2 Connect Input Data with Method
The formatToIMSmessage method takes five parameters as input. These
are last name, first name, extension, zip code and command. We build a
parameter-from-property connection between these fields and the
connection line we have just built.
• With the right mouse button, click on the dotted connection line between
the Submit button and the formatToIMSmessage method.
• Select Connect and then lastName from the menus.
• Drag the spider into the text field for the last name and drop it by
clicking the left mouse button.
• From the subsequent menu, select text. You should now see a purple
line going from the dotted Event-to-Method connection to the text field.

Repeat the above steps for the first name, extension and Zip code in order
to pass these parameters to formatToIMSmessage. Select from the Connect
pop-up either firstName, extension or zipCode.

To connect the command, select command from the Connect menu. In the
last step, choose selectedItem instead of text.

With these connections we are able to build the message. Your GUI should
now show the connections below.

Figure 117. WWW-IMS Example - Passing Input Parameters

8.6.3 Connect Methods

The output of the formatToIMSmessage method is the input for the
putMessage method. This is the actual message object built for the IMS

Chapter 8. Connecting the Internet to IMS 185

 application. We build an event-to-method connection to the putMessage
method.
• Select the green line that represents the event-to-method connection
from the Submit button to the formatToIMSmessage method.
• Click on the same line with the right mouse button and select Connect
and then Normal Result from the menus.
• Drag the spider outside the applet border and drop it by clicking the left
mouse button.
• Choose All features from the resultant menu.
• In the subsequent window, scroll through the methods until you find
putMessage Select it and click on OK.
• You should now see another green line. You may move this line until it
looks like the figure below.

Figure 118. WWW-IMS Example - Passing Parameters to Method

The output of the putMessage method is the message ID. It is used by the
the retrieveMessage method to make sure that it gets the right reply
message off the queue. Thus, we create another connection from the
putMessage method to the retrieveMessage method.
• With the right mouse button click on the green line that represents the
method connection from formatToIMSmessage to putMessage. You built
this connection in the previous step.
• From the menus, select Connect and then normal result.
• Drop the spider again in the white area outside the dotted line border of
the applet.
• Select All Features from the menu.
• Select retrieveMessage from the methods list and click on OK.

186 Connecting to the Internet with MQSeries and VisualAge for Java
 Figure 119. WWW-IMS Example - Connecting Methods

The three arrows on the left side point to the following three methods (from
top to bottom):
1. formatToIMSmessage
2. putMessage
3. retrieveMessage

8.6.4 Display Method Output in the Applet

The retrieveMessage method gets a particular message off the queue and
parses out the IMS information we wish to display in the Text area of the
applet. Therefore, we create a connection from the output of the
retrieveMessage method to the Text area box at the bottom of the applet.

Figure 120. WWW-IMS Example - Display IMS Results in Text Area

• With the right mouse button, click on the green line that you created
above, representing the method connection from putMessage to
retrieveMessage.

Chapter 8. Connecting the Internet to IMS 187

 • From the menu, select Connect and then normalResult.
• Drop the spider in the Text area box.
• Select text from the menu.

In the above step, we displayed the IMS return information in the Text Area.
Now display the last name, first name, extension and zip code in the
relevant Text fields. To do this, we make use of the getter methods we
created earlier (Figure 115 on page 183).

Figure 121. WWW-IMS Example - Display Data in Text Fields

• With the right mouse button, click on the Submit button.

• From the menu, choose Connect and then actionPerformed.
• Drop the spider somewhere outside the border of the applet.
• From the menu, select All Features, then getFirstName from the
methods, and click on OK.

You might want to drag this connection to another area of the screen to get
it away from the other connections. You do this by selecting the connection,
holding down the mouse button, and dragging. This is purely cosmetic and
does not affect the functioning of the program.
• With the right mouse button, click on the getter method connection.

188 Connecting to the Internet with MQSeries and VisualAge for Java
 • Choose Connect and normalResult.
• Drop the spider in the text field and select text from the menu.

Repeat the above steps to create connections for first name, extension and
zip code.

The seven arrows on the left in Figure 122 on page 190 point to the
following methods:
1. getLastName
2. getFirstName
3. getExtension
4. getZipCode
5. formatToIMSmessage
6. putMessage
7. retrieveMessage
Note: We have cleaned up some of the connections for clarity.

8.6.5 Connect Button to Text Field

Since the response time from IMS can be up to 15 seconds, we want to tell
the user to be patient. As soon as the Submit button is clicked, we display
the message ″Submitted to IMS for processing. Please wait 15 seconds...″.
• With the right mouse button click on the Submit button.
• From the menu, select Connect and then action performed.
• Drop the spider in the Text area and select text.
• Click on the connection and select Properties.
• In the subsequent window, select Set parameters.
• In the next window type the message and click on OK.
Your GUI design should now be complete and resemble Figure 122 on
page 190.

8.6.6 Reorder Connections

The order of the connection from the Submit button is important. You can
look at the order when you click with the right mouse button on the Submit
button and then select Reorder Connections From from the menu.

Chapter 8. Connecting the Internet to IMS 189

 Figure 122. WWW-IMS Example - Completed Applet

Figure 123. WWW-IMS Example - Reorder Connections

190 Connecting to the Internet with MQSeries and VisualAge for Java
8.7 Creating a Java Application Using VisualAge for Java
The Java application demonstrates how to implement the Java bindings
provided with MQSeries Version 5. You could write a Java application to
implement the business logic (middle tier) of a three-tier environment.
Typically, that would be a server program. In this example, we use the Java
application to take a request message from the client, log it to a file, and
then send it to IMS.

This is a very limited middle tier application, but it shows the use of the
bindings.

8.7.1 Checklist for the Execution

Before you try to run the application make sure that:
• The queue manager is running on both the MVS and Web server
machines.
• You have defined the necessary queue manager objects on both
machines from the definition files described in 8.2.1, “Setting Up
MQSeries to Run the Example” on page 163.
• Both channel initiators are running.
• The listener is running on the Web server machine.

8.7.2 How to Create a Non-Visual Application

• On the Workbench, click on the Create Class or Interface button

or select Create new class interface from the Quick Start menu.
• In SmartGuide window, shown in Figure 124 on page 192, type a class
name, such as BusinessLogic, and a package, such as mqjava. Also,
mark the button labelled Write source code for the class.

Chapter 8. Connecting the Internet to IMS 191

 Figure 124. WWW-IMS Example - Business Logic

• Import the MQSeries Bindings for Java, com.ibm.mqbind, and java-io as

shown in Figure 125 on page 193.
• Click on Finish and VisualAge creates the class.

Now write the source code and create a constructor named public
BusinessLogic as shown in Figure 126 on page 193 through Figure 128 on
page 196.

192 Connecting to the Internet with MQSeries and VisualAge for Java
 Figure 125. WWW-IMS Example - Import Bindings

import com.ibm.mqbind.*
import java.io.*

/**
* This class was generated by a SmartGuide.
*
*/
public class BusinessLogic {
private String qManager = ″MQNT1″ ; // define name of queue manager object
// to connect to.

private MQQueueManager qMgr; // define a queue manager object

Figure 126. WWW-IMS Example - Business Logic Class

Chapter 8. Connecting the Internet to IMS 193

 /**
* This method was created by a SmartGuide.
*/
public BusinessLogic() {
{
try {
// Create a connection to the queue manager
qMgr = new MQQueueManager(qManager);

// Set up the options on the queue we wish to open...

// Note: All MQ Options are prefixed with MQC in Java.

int openOptions = MQC.MQOO_INPUT_AS_Q_DEF | MQC.MQOO_OUTPUT;

// Specify the queue that we wish to open, and the open options

MQQueue inputq = qMgr.accessQueue(″toIMSqueue″ ,

openOptions,
null, // default q manager
null, // no dynamic q name
null); // no alternate user id

MQMessage retrievedMessage = new MQMessage();

// Set the get message options..

// Accept the defaults, same as MQGMO_DEFAULT

MQGetMessageOptions gmo = new MQGetMessageOptions();

// Get the message off the queue..

inputq.get(retrievedMessage, gmo);

// Prove we have the message by displaying the UTF message text

String msgText = retrievedMessage.readLine();

System.out.println(″The message is: ″ + msgText);

// Write the message out to a file

BufferedWriter bw = new BufferedWriter(new FileWriter(″Transact.out″, true));

bw.write(msgText,0,msgText.length());
bw.newLine();
bw.close();

Figure 127 (Part 1 of 2). WWW-IMS Example - Business Logic Constructor

194 Connecting to the Internet with MQSeries and VisualAge for Java
 // Specify the queue that we wish to open for output, and the open options...

MQQueue outputq = qMgr.accessQueue(″fromIMSqueue″ ,

openOptions,
null, // default q manager
null, // no dynamic q name
null); // no alternate user id

// specify the message options (accept default MQPMO_DEFAULT)

MQPutMessageOptions pmo = new MQPutMessageOptions();

// put the message on the queue

outputq.put(retrievedMessage,pmo);
System.out.println(″Successful put message.″ ) ;

// Close the queues

inputq.close();
outputq.close();

// Disconnect from the queue manager

qMgr.disconnect();
}

// If an error has occurred in the above, try to identify what went wrong.
// Was it an MQ error?

catch (MQException ex) {

System.out.println(″An MQ error occurred : Completion code ″ +
ex.completionCode +
″ Reason code ″ + ex.reasonCode);
}
// Was it a Java buffer space error?
catch (IOException ex) {
System.out.println(″An error occurred while writing to message buffer:″ + +
ex);
ex.printStackTrace();
}
} // end of constructor
}

Figure 127 (Part 2 of 2). WWW-IMS Example - Business Logic Constructor

Chapter 8. Connecting the Internet to IMS 195

 /**
* This method was created by a SmartGuide.
* @param args java.lang.String[]
*/
public static void main(String args[]) {
// Create a new instance of the sample program
BusinessLogic logic = new BusinessLogic();
}

Figure 128. WWW-IMS Example - Business Logic Main

196 Connecting to the Internet with MQSeries and VisualAge for Java
Appendix A. MQSeries Objects for WWW/IMS Application

A.1 Definitions for Web Server

********************************************************************/
* */
* Program name: WEBSRVR */
* */
* Description: Sample MQSC source defining MQM sample queues */
* Can be processed, with changes as needed, after */
* starting the MQM */
* */
* Statement: Licensed Materials - Property of IBM */
* */
* (C) Copyright IBM Corp. 1994, 1997 */
* */
* */
* 10/24/97 Created by Sam Delmer/IBM Global Services */
********************************************************************/
* */
* Function: */
* */
* */
* WEBSRVR is a sample MQSC file to create or reset sample MQI */
* objects of the Message Queue Manager (MQM). */
* It includes the definitions of objects used by the MQSeries / */
* IMS sample application. This file creates the objects needed */
* by the queue manager on the web server machine. */
* */
********************************************************************/
* */
* WEBSRVR is sample data for the MQSC utility */
* */
********************************************************************/

********************************************************************/
* Define one local queue for output from the java client. */
* This queue is only used in the java bindings example. */
********************************************************************/
DEFINE QLOCAL (′ toIMSqueue′) +
LIKE(SYSTEM.DEFAULT.LOCAL.QUEUE) +
DESCR(′ Queue used by Redbook example′ ) SHARE REPLACE

 Copyright IBM Corp. 1997 197

 ********************************************************************/
* Define one local queue for input to the java client. */
* This queue is used in both examples. */
********************************************************************/
DEFINE QLOCAL (′ fromIMSqueue′) +
LIKE(SYSTEM.DEFAULT.LOCAL.QUEUE) +
DESCR(′ Queue used by Redbook example′ ) SHARE REPLACE

********************************************************************/
* Define one remote queue for output from the java client. */
* This queue is used in the example without the java bindings. */
********************************************************************/
DEFINE QREMOTE (′ toIMS′) +
LIKE(SYSTEM.DEFAULT.REMOTE.QUEUE) +
DESCR(′ Remote def used by Redbook example′) +
RNAME(′ IMS.SAMP.REQUEST′) +
RQMNAME(CSQ2) +
XMITQ(CSQ2) REPLACE

********************************************************************/
* Define one transmission queue used for communication with MVS */
* This queue is used in both examples. */
********************************************************************/
DEFINE QLOCAL (′ CSQ2′) +
LIKE(SYSTEM.DEFAULT.LOCAL.QUEUE) +
DESCR(′ Transmission queue for Redbook example to CSQ2 queue manager′) +
TRIGGER PROCESS(′ WTR05402.TO.CSQ2′) +
TRIGTYPE(FIRST) INITQ(SYSTEM.CHANNEL.INITQ) +
USAGE(XMITQ) +
REPLACE

********************************************************************/
* Define one process used to trigger channel. You do not need */
* this if you use MQSeries Version 5 */
********************************************************************/
DEFINE PROCESS(′ WTR05402.TO.CSQ2′) +
DESCR(′ Process used to trigger channel′) +
USERDATA(′ WTR05402.TO.CSQ2′) +
REPLACE

198 Connecting to the Internet with MQSeries and VisualAge for Java
********************************************************************/
* Define one sender channel to MVS system. */
********************************************************************/
DEFINE CHANNEL(′ WTR05402.TO.CSQ2′ ) CHLTYPE(SDR) +
DESCR(′ Channel from MQ on web server to MQ on MVS′) +
TRPTYPE(TCP) XMITQ(′ CSQ2′) +
CONNAME(9.24.104.74) REPLACE

********************************************************************/
* Define one receiver channel from MVS system. */
********************************************************************/
DEFINE CHANNEL(′ CSQ2.TO.WTR05402′ ) CHLTYPE(RCVR) +
DESCR(′ Channel from MQ on MVS to MQ on web server′) +
TRPTYPE(TCP) REPLACE

********************************************************************/

Appendix A. MQSeries Objects for WWW/IMS Application 199

A.2 Definitions for MVS System
********************************************************************/
* */
* Program name: MVS */
* */
* Description: Sample MQSC source defining MQM sample queues */
* Can be processed, with changes as needed, after */
* starting the MQM */
* */
* Statement: Licensed Materials - Property of IBM */
* */
* (C) Copyright IBM Corp. 1994, 1997 */
* */
* */
* 10/24/97 Created by Sam Delmer/IBM Global Services */
********************************************************************/
* */
* Function: */
* */
* */
* MVS is a sample MQSC file to create or reset sample */
* MQI resources of the Message Queue Manager (MQM). */
* It includes definitions of objects used by the MQSeries/IMS */
* sample application. This file creates the objects needed by */
* the queue manager on the MVS system where IMS resides. This */
* file should be converted to the format needed by the batch */
* utility on MVS. */
* */
********************************************************************/
* */
* MVS is sample data for the MQSC utility */
* */
********************************************************************/

********************************************************************/
* Define a storage class for use by the IMS bridge. */
********************************************************************/
DEFINE STGCLASS(IMSBRDG) PSID(1) +
XCFGNAME(IMSBRDG) XCFMNAME(RAIIMS51)

********************************************************************/
* Define one local queue for input to the IMS Bridge. */
********************************************************************/
DEFINE QLOCAL (IMS.SAMP.REQUEST) +
DESCR(′ Queue used by Redbook example′) +
STGCLASS(IMSBRDG) NOTRIGGER SHARE REPLACE

200 Connecting to the Internet with MQSeries and VisualAge for Java
********************************************************************/
* Define one transmission queue used for commun. with Web Server.*/
********************************************************************/
DEFINE QLOCAL (′ WTR05402′) +
DESCR(′ Transmission queue for Redbook example to WTR05402 queue manager′) +
TRIGGER PROCESS(′ CSQ2.TO.WTR05402′) +
TRIGTYPE(F) INITQ(SYSTEM.CHANNEL.INITQ) +
USAGE(XMITQ) +
REPLACE

********************************************************************/
* Define one process used to trigger channel. */
********************************************************************/
DEFINE PROCESS(′ CSQ2.TO.WTR05402′) +
DESCR(′ Process used to trigger channel′) +
APPLICID(′ CSQX START′) +
USERDATA(′ CSQ2.TO.WTR05402′) +
REPLACE

********************************************************************/
* Define one sender channel to web server system. */
********************************************************************/
DEFINE CHANNEL(′ CSQ2.TO.WTR05402′ ) CHLTYPE(SDR) +
DESCR(′ Channel from MQ on MVS to MQ on web server′) +
TRPTYPE(TCP) XMITQ(′ WTR05402′) +
CONNAME(9.24.105.82)

********************************************************************/
* Define one receiver channel from web server system. */
********************************************************************/
DEFINE CHANNEL(′ CSQ2.TO.WTR05402′ ) CHLTYPE(RCVR) +
DESCR(′ Channel from MQ on web server to MQ on MVS′) +
TRPTYPE(TCP)

********************************************************************/

Appendix A. MQSeries Objects for WWW/IMS Application 201

202 Connecting to the Internet with MQSeries and VisualAge for Java
Appendix B. Diskette Contents

The diskette contains the examples developed in this book. Table 20 lists
the directories and the file names.
Note: The diskette can store only file names in 8.3 format. Make sure that
you change the file name when you copy the files onto your own system.

Table 20. Files on Diskette

Real file name File name on diskette Description
Programs from Chapter 6, “An MQSeries Application” on page 119
MQEXMP11.dat same All VisualAge for Java applications in the
chapter
MQExample1.class MQEx1.cla The applet executes specific MQSeries
functions initiated by push buttons, and puts
MQExample1.java MQEx1.jav
and gets messages. It uses the MQSeries
Client for Java.
MQExample1.html MQEx1.htm HTML file that displays the applet
MQExample1
MQExample2.class MQEx2.cla The server application with a GUI executes
specific MQSeries functions initiated by push
MQExample2.java MQEx2.jav
buttons, and puts and gets messages. It uses
the MQSeries Bindings for Java.
MQEXMP1.tst same MQSC file with definitions to run both client
and server in the same machine
MQEXMP2a.tst same MQSC files with definitions for client and
server running in different machines
MQEXMP2b.tst same
Programs from Chapter 8, “Connecting the Internet to IMS” on page 161
IMSWWW.dat same All VisualAge for Java applications in the
chapter
EmployeeRecord.class EmpR.cla Applet that communicates with the server and
IMS
EmployeeRecord.java EmpR.jav
EmployeeRecord.html EmpR.htm HTML file that displays the applet
EmployeeRecord
BusinessLogic.class BusL.cla Java server application that communicates
with the EmployeeRecord applet and IMS
BusinessLogic.java BusL.jav
WEBSRVR.tst same MQSC file with definitions for the queue
manager in the Web server
MVS.tst same MQSC file with definitions for the queue
manager in the MVS system

 Copyright IBM Corp. 1997 203

204 Connecting to the Internet with MQSeries and VisualAge for Java
Appendix C. Special Notices

This publication is intended to help application programmers to write

programs with VisualAge and MQSeries. The information in this publication
is not intended as the specification of any programming interfaces that are
provided by VisualAge for Java and MQSeries. See the PUBLICATIONS
section of the IBM Programming Announcement for MQSeries and
VisualAge for Java 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, 500 Columbus Avenue,
Thornwood, NY 10594 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 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

 Copyright IBM Corp. 1997 205

 attempting to adapt these techniques to their own environments do so at
their own risk.

The following document contains examples of data and reports used in daily
business operations. To illustrate them as completely as possible, the
examples contain the names of individuals, companies, brands, and
products. All of these names are fictitious and any similarity to the names
and addresses used by an actual business enterprise is entirely
coincidental.

The following terms are trademarks of the International Business Machines

Corporation in the United States and/or other countries:

AIX CICS
DB2 IBM
IMS IMS/ESA
MQ MQSeries
MVS/ESA OS/2
OS/390 OS/400
PS/2 SupportPac
SystemView VisualAge
VTAM

The following terms are trademarks of other companies:

C-bus is a trademark of Corollary, Inc.

Java and HotJava are trademarks of Sun Microsystems, Incorporated.

Microsoft, Windows, Windows NT, and the Windows 95 logo are trademarks
or registered trademarks of Microsoft Corporation.

PC Direct is a trademark of Ziff Communications Company and is used

by IBM Corporation under license.

Pentium, MMX, ProShare, LANDesk, and ActionMedia are trademarks or

registered trademarks of Intel Corporation in the U.S. and other
countries.

UNIX is a registered trademark in the United States and other

countries licensed exclusively through X/Open Company Limited.

Other company, product, and service names may be trademarks or

service marks of others.

206 Connecting to the Internet with MQSeries and VisualAge for Java
Appendix D. Related Publications

The publications listed in this section are considered particularly suitable for
a more detailed discussion of the topics covered in this redbook.

D.1 International Technical Support Organization Publications

For information on ordering these ITSO publications see “How to Get ITSO
Redbooks” on page 209.
• Internet Application Development with MQSeries and Java , SG24-4896
• Examples of Using MQSeries in WWW , SG24-4882
• Application Development with VisualAge for Smalltalk and MQSeries ,
SG24-2117
• VisualAge: Concepts and Features , GG24-3946
• MQSeries for Windows Version 2.1 in a Mobile Environment , SG24-2103

D.2 Redbooks on CD-ROMs

Redbooks are also available on CD-ROMs. Order a subscription and
receive updates 2-4 times a year at significant savings.

CD-ROM Title Subscription Collection Kit

Number Number
System/390 Redbooks Collection SBOF-7201 SK2T-2177
Networking and Systems Management Redbooks Collection SBOF-7370 SK2T-6022
Transaction Processing and Data Management Redbook SBOF-7240 SK2T-8038
AS/400 Redbooks Collection SBOF-7270 SK2T-2849
RS/6000 Redbooks Collection (HTML, BkMgr) SBOF-7230 SK2T-8040
RS/6000 Redbooks Collection (PostScript) SBOF-7205 SK2T-8041
Application Development Redbooks Collection SBOF-7290 SK2T-8037
Personal Systems Redbooks Collection SBOF-7250 SK2T-8042

D.3 Other Publications

These publications are also relevant as further information sources:
• MQSeries Application Programming Reference , SC33-1673
• MQSeries Application Programming Guide , SC33-0807
• MQSeries Command Reference , SC33-1369
• MQSeries Clients , GC33-1632
• MQSeries Intercommunication , SC33-1872
• MQSeries Planning Guide , GC33-1349

 Copyright IBM Corp. 1997 207

 • MQSeries for Windows NT V5.0 Quick Beginnings , GC33-1871

208 Connecting to the Internet with MQSeries and VisualAge for Java
How to Get ITSO Redbooks

This section explains how both customers and IBM employees can find out about ITSO redbooks,
CD-ROMs, workshops, and residencies. A form for ordering books and CD-ROMs is also provided.

This information was current at the time of publication, but is continually subject to change. The
latest information may be found at http://www.redbooks.ibm.com.

How IBM Employees Can Get ITSO Redbooks

Employees may request ITSO deliverables (redbooks, BookManager BOOKs, and CD-ROMs) and
information about redbooks, workshops, and residencies in the following ways:
• PUBORDER — to order hardcopies in United States
• GOPHER link to the Internet - type GOPHER.WTSCPOK.ITSO.IBM.COM
• Tools disks
To get LIST3820s of redbooks, type one of the following commands:
TOOLS SENDTO EHONE4 TOOLS2 REDPRINT GET SG24xxxx PACKAGE
TOOLS SENDTO CANVM2 TOOLS REDPRINT GET SG24xxxx PACKAGE (Canadian users only)
To get BookManager BOOKs of redbooks, type the following command:
TOOLCAT REDBOOKS
To get lists of redbooks, type one of the following commands:
TOOLS SENDTO USDIST MKTTOOLS MKTTOOLS GET ITSOCAT TXT
TOOLS SENDTO USDIST MKTTOOLS MKTTOOLS GET LISTSERV PACKAGE
To register for information on workshops, residencies, and redbooks, type the following command:
TOOLS SENDTO WTSCPOK TOOLS ZDISK GET ITSOREGI 1998
For a list of product area specialists in the ITSO: type the following command:
TOOLS SENDTO WTSCPOK TOOLS ZDISK GET ORGCARD PACKAGE
• Redbooks Web Site on the World Wide Web
http://w3.itso.ibm.com/redbooks
• IBM Direct Publications Catalog on the World Wide Web
http://www.elink.ibmlink.ibm.com/pbl/pbl
IBM employees may obtain LIST3820s of redbooks from this page.
• REDBOOKS category on INEWS
• Online — send orders to: USIB6FPL at IBMMAIL or DKIBMBSH at IBMMAIL
• Internet Listserver
With an Internet e-mail address, anyone can subscribe to an IBM Announcement Listserver. To
initiate the service, send an e-mail note to [email protected] with the keyword
subscribe in the body of the note (leave the subject line blank). A category form and detailed
instructions will be sent to you.

 Copyright IBM Corp. 1997 209

How Customers Can Get ITSO Redbooks
Customers may request ITSO deliverables (redbooks, BookManager BOOKs, and CD-ROMs) and
information about redbooks, workshops, and residencies in the following ways:
• Online Orders — send orders to:

IBMMAIL Internet
In United States: usib6fpl at ibmmail [email protected]
In Canada: caibmbkz at ibmmail [email protected]
Outside North America: dkibmbsh at ibmmail [email protected]

• Telephone orders

United States (toll free) 1-800-879-2755

Canada (toll free) 1-800-IBM-4YOU

Outside North America (long distance charges apply)

(+45) 4810-1320 - Danish (+45) 4810-1020 - German
(+45) 4810-1420 - Dutch (+45) 4810-1620 - Italian
(+45) 4810-1540 - English (+45) 4810-1270 - Norwegian
(+45) 4810-1670 - Finnish (+45) 4810-1120 - Spanish
(+45) 4810-1220 - French (+45) 4810-1170 - Swedish

• Mail Orders — send orders to:

I B M Publications I B M Publications IBM Direct Services

Publications Customer Support 144-4th Avenue, S.W. Sortemosevej 21
P.O. Box 29570 Calgary, Alberta T2P 3N5 DK-3450 Allerød
Raleigh, NC 27626-0570 Canada D enmark
USA

• Fax — send orders to:

United States (toll free) 1-800-445-9269

Canada 1-403-267-4455
Outside North America (+45) 48 14 2207 (long distance charge)

• 1-800-IBM-4FAX (United States) or (+1)001-408-256-5422 (Outside USA) — ask for:

Index # 4421 Abstracts of new redbooks
Index # 4422 IBM redbooks
Index # 4420 Redbooks for last six months
• Direct Services - send note to [email protected]
• On the World Wide Web
Redbooks Web Site http://www.redbooks.ibm.com
IBM Direct Publications Catalog http://www.elink.ibmlink.ibm.com/pbl/pbl
• Internet Listserver
With an Internet e-mail address, anyone can subscribe to an IBM Announcement Listserver. To
initiate the service, send an e-mail note to [email protected] with the keyword
subscribe in the body of the note (leave the subject line blank).

210 Connecting to the Internet with MQSeries and VisualAge for Java
IBM Redbook 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.

How to Get ITSO Redbooks 211

212 Connecting to the Internet with MQSeries and VisualAge for Java
Glossary

Application Programming Interface (API). An or the Intranet. Plain text (ASCII format) and
Application Programming Interface consists of binary files can be send.
the functions and variables that programmers
are allowed to use in their applications. encapsulation. Encapsulation is an
object-oriented programming technique that
applet. A Java program that runs within the makes an object′s data private or protected and
Web browser, providing executable content, but allows programmers to access and manipulate
having no access to the PC environment. the data only through method calls.
Applets can be embedded within existing HTML
documents and allows the user to interact with Firewall. A security scheme to protect one or
them. Applet can also run without a browser, more computer within the Internet from intrusion
you than have to use an applet viewer. by other external computer. A firewall is a
invisible boundary created by software.
application. A Java program that runs outside a Computer within a firewall can share resources
Web browser, having access to the entire PC and have access to other computer, which
environment. Applications commonly run from computer outside the firewall can′t. External
within a shell environment, or from the requests can be examined and filtered before
command line. they are allowed to go through the firewall and
than have also access to the resources within
asynchronous messaging. A method of the firewall.
communication between programs in which
programs place messages on message queues. host. A term referring to a computer (′of every
With asynchronous messaging, the sending size′) that is connected to the Internet or the
program proceeds with its own processing Intranet.
without waiting for a reply to its message.
HotJava. A Web browser developed by Sun
browser. A browser is a synonym of Web Microsystems, the first ′Java-enabled′ Web
browser or Client browser. It is a program with browser.
a graphical interface. Commonly used browsers
are: HTML. HTML (Hypertext Markup Language) is a
language used to define information that is to be
• IBM WebExplorer
displayed on the World Wide Web.
• MS Internet Explorer
instance. An instance is an object. When a
• Netscape Navigator
class is instantiated to produce an object, we
• Sun HotJava say that the object is an instance of the class.

class. A class is an encapsulated collection of Internet. The largest computer network of the
data, and methods to operat e on the data. A world. It is a network of networks (a network
class may be instantiated to produce an object can be a single computer) linked together to
that is an instance of the class. form a collective entity. They all communicate
via the TCP/IP protocol. Other names are:
client. In MQSeries, a client is a run-time Superhighway, Datahighway, The Net or
component that provides access t o queuing CyberSpace.
services on a server for local user applications.
interface. An interface is a special type of class
Email. Electronic mail (also e-mail) is a text which contains only abstract methods and no
message delivering method across the Internet instance variables. An interfaces provides a

 Copyright IBM Corp. 1997 213

common set of methods that can be managers. It allows application programs to
implemented by subclasses of a number of access message queuing services.
different classes.
message queuing. A programming technique in
Intranet. It follows the same rules as the which each program within an application
Internet, but is not an open network. It′s only communictes with the other programs by putting
operates within an enterprise network protected messages on queues.
by a firewall against the Internet.
messaging. See synchronous messaging and
Java. An object-oriented, secure and portable asynchronous messaging .
programming language, comparable with C++
without the complex parts of C++ like pointers method. Method is the object-oriented
and memory management. Java is an programming term for a function or procedure.
interpreter language thats needs a virtual java
engine to run. Many Web browser have a MQI. Message queue interface.
built-in Java engine.
MQI channel. Connects an MQSeries client to a
Java Developers Kit (JDK). A package of queue manager on a server system. It transfers
software distributed by Sun Microsystems for only MQI calls and responses in a bidirectional
Java developers. It includes the Java manner.
interpreter, Java classes and Java developmetn
tools: compiler, debugger, disassembler, MQSC. MQSeries commands.
appletviewer, stub file generator, and
documentation generator. MQSeries. A family of IBM licensed programs
that provide message queuing services.
message. In message queuing applications, a
communication sent between programs. There MQSeries client. Part of an MQSeries product
are persistent and non-persistent messages. that can be installed on a system without
installing the full queue manager. The
message channel. In distributed message MQSeries client accepts MQI calls from
queuing, a mechanism for moving messages applications and communicates with a queue
from one queue manager to another. A manager on a server system.
message channel comprises two message
channel agents (a sender and a receiver) and a MQSeries commands (MQSC). Commands that
communication link. are used to manipulate MQSeries objects.

message channel agent. A program that object. (1) In Java, an object is an instance of a
transmits messages from a transmission queue class. A class models a group of things; an
to a communication link, or from a object models a particular member of that
communication link to a destination queue. group.
(2) in MQSeries, an object is a queue manager,
message channel interface. The MQSeries a queue, or a channel.
interface to which application programs that
transmit messages between an MQSeries queue package. A package in Java is a way of giving
manager and another messaging system must a piece of Java code access to a specific set of
conform. A part of the MQSeries Framework. classes. Java code that is part of a particular
package has access to all the classes in the
message queue. Synonym for queue. package and to all non-private A private field is
not visible outside its own class .
message queue interface. The programming
interface provided by the MQSeries queue

214 Connecting to the Internet with MQSeries and VisualAge for Java
protected. A protected field is only visible subclass. A subclass is a class that extends
within its own class, within subclasses, or within another. The subclass inherits the protected
packages of which the class is a part. methods and variables of its superclass.

public. A public class or interface is visible superclass. A superclass is a class that is

everywhere. A public method or variable is extended by some other class. The superclass′ s
visible everywhere that its class is visible. protected methods and variables are available
to the subclass.
queue. A queue is an MQSeries object.
Message queuing applications can put messages Synchronous messaging. A method of
on, and get messages from, a queue. communication between programs in which
programs place messages on message queues.
queue manager. A queue manager is a system With synchronous messaging, the sending
program the provides message queuing services program waits for a reply to its message before
to applications. resuming its own processing.

server. (1)In MQSeries a server is a queue Web. A short name for the World-Wide Web
manager that provides message queuing (WWW). You can think about the web as a
services to client applications running on a spider web, which connects thousands of
remote workstation. computer together.
(2) More generally a server is a program that
responds to requests for information in the Web browser. A program that formats and
particular two-program information flow model displays information that is distributed on the
of client/server. World Wide Web.
(3)The computer on which a server program
runs. Web server. A program that serves HTML
pages to the Web browser. See also Web
socket. A mechanism to allow processes to browser.
communicate with one other over the Internet.
They are the core functionality behind the World Wide Web (Web). The World Wide Web is
TCP/IP protocol. an Internet service, based on a common set of
protocols, which allows a particularly configured
server computer to distribute documents across
the Internet in a standard way.

Glossary 215
216 Connecting to the Internet with MQSeries and VisualAge for Java
List of Abbreviations

API Application JNI Java Native Interface

Programming Interface
LTERM logical terminal
BMP Batch Message
LU logical unit
Processing, region (IMS)
MCA message channel agent
CGI Common Gateway
Interface MPP Message Processing
Program
CGM computer graphics
metafile MQ Message Queuing

DDM Device Dependent MQI Message Queuing

Modules Interface

DNS Domain Name Server MQM MQ queue manager

DOS Disk Operating System MVS Multiple Vitual Storage

FTP File Transfer Protocol NNTP Network News Transfer

Protocol
GIF graphic interchange
format OTMA Open Transaction
Manager Access
GUI graphical user interface
PID program identification
HPFS High Performance File
number
System
SDK Software Development
HTML HyperText Mark-up
Kit
Language
SGML Standard Generalized
HTTP HyperText Transfer
Mark-up Language
Protocol
SMTP Simple Mail Transfer
IBM International Business
Protocol
Machines Corporation
SLIP Serial Line Internet
ICCS IBM Internet Connection
Protocol
Secure Server
SSL Secure Socket Layer
IMS Information
Management System TCP/IP Transmission Control
Protocol / Internet
ITSO International Technical
Protocol
Support Organization
URL Uniform Resource
IVP Installation Verification
Locator
Program
VM Virtual Machine (Java)
JDBC Java Database
Connectivity WWW World Wide Web

JDK Java Development Kit XCF Cross System Coupling

Facility

 Copyright IBM Corp. 1997 217

218 Connecting to the Internet with MQSeries and VisualAge for Java
Index

bindings 139
Special Characters example 141
<APPLET> 97 button category 104
bytecode 87, 89, 93

A
abbreviations 217 C
acronyms 217 channel 47, 54, 129, 143, 145
actionPerformed 108 how to start 61
add package to workspace 116 initiation queue 57
administrator ID 21 message channel 47
administrator password 21 MQI channel 47
alias queue 49 o v e r v i e w 57
align objects 107 process definition 57
AMQSCOMA.TST 50 transport types
AMQSGET 63 MQWin 47
example 63 triggering 62
AMQSGETC 67 channel initiator 56, 57, 61
AMQSPUT 63 channel name 143
example 63 channel pair 57, 59
AMQSPUTC 67 class (Java) 94
API 43 class library 88
example code 73 classes 90
list of all 72 CLASSPATH 16, 26, 37, 93
applet 89 Windows NT 29
height 97 client 54, 55
test 110 client connection
vie w 97 client/server
width 97 connection 64
applet class directory 36 fat client 54
applet vs application 92 slim client 54
application solutions 3
triggering 62 start connection 67
application vs applet 92 test connection 67
assure delivery 3 test connection (IVP) 145
asynchronous messaging 44 clients and servers 54
awt 95 close queue 133
AWT enhancements 91 connections 134
example 134
method 133, 134
B com.ibm.mq 139
beans 101 com.ibm.mqbind 139
bibliography 207

 Copyright IBM Corp. 1997 219

com\ib m\mq 36
commands 52 D
define queue 52 data conversion 158
e n d m q m 64 database connectivity 92
example 60 datagram 44
runmqchi 61 DDM 149
runmqlsr 60 dead-letter queue 50
runmqsc 60 dead-letter-queue 51
start channel 60 default queue manager 50, 60
communication define
between queue managers 58 XCF group 154
program-to-program 45 define channel 65, 143
compile applet 96 define queue 52, 65, 143
compiler Demonstration 11
Java versus C 88 destination queue
javac 94 does not exist 50
composition editor 101 is full 50
CONFIG.SYS 24, 26, 66 not authorized 50
configuration put inhibited 50
Internet Connection Server 20 directory
MQFirst 77 c o m \ i b m \ m q 36
connect to queue manager HTML documents 19
server method 141 Internet Connection Secure Server 18
connection MQSeries Client for Java documentation 34
between two systems 59 disconnect 130
event to method 108, 125, 136 disconnectFromQmgr
parameter from property 126, 136 example 131
to queue manager 127 diskette contents 203
method 129 distributed application 88
connectToQmgr documentation
example 129 MQSeries client for Java 35
conversion 158 draw rectangle 96
CPI-C 46 draw string 96
create dynamic queue 49
applet 100, 122
application 139
GUI 103
E
ENDMQM
method 123
example 64
new application 46
environment
objects 103
settings in applet 129
using RUNMQSC 52
environment variable
queue manager 50
CLASSPATH 37
crtmqm
for Java client 66
example 52
MQSERVER 66
CSQ6SYSP macro 154
export package 113

220 Connecting to the Internet with MQSeries and VisualAge for Java
extends 96 import package 115
IMS adapter 152
IMS Bridge 149, 151
F basic flow 154
fat client 54 implicit MQI support 152
fonts 106 message structure 156
front page 22 setup 153
index.html 34, 35
InfoZip 34
G UNZ520X2 34
get message 137 unzip 34
connections 137 infrastructure 3
method 138 initiation queue 49
global communication 3 inner classes 92
glossary 213 installation 13
graphics 96 Internet Connection Secure Server 14
GUI 90, 103 JDK 1.1.4 26
guided tour 80 MQFirst 78
MQSeries Client for Java
client code 36
H documentation 34
height of applet 97
MQSeries V5 29
Hello World applet 95
Netscape Navigator 23
Hello World application 94
verification 37
hostname 20, 21, 129, 145
VisualAge for Java 38
Hotjava 31
internationalization 91
how MQSeries works 55
Internet applications 11
How to get
Internet Connection Server
ICSS 14
administration page 23
JDK 27
download 14
MQFirst 78
front page 22
MQSeries Client for Java 33
installation 17
Netscape 24
Internet connections 6
VisualAge for Java 38
Internet Gateway 7
HTML
interpreter 92
call applet 97
java 94
directory 19
ivj.dat 40
HTTP port 20
IVP 37

I J
IDE.icx 40
JAR file format 91
im p ort
Java
mq classes 41, 139
a first try 93
mqbind classes 41, 139
basics 87
mqservices 41
classes 90
compiler 94

Index 221
Java (continued)
interpreter 92, 94 M
o v e r v i e w 87 MA83 files 34
packages 90 MA83.ZIP 34
platform independence 87 main 94
sample applet 95 manipulate MQM objects 52
sample application 94 match height 107
versus C 88 math package 91
virtual machine 93 message 44
Java client 66 descriptor 44
Java command 143 layout (IMS) 157
Java database connectivity 92 sequence number 50
Java native interface 92 structure for IMS 156
java.applet.class 90 types 44
java.awt.class 90 message channel 47, 55
JAVA.EXE 92 message channel agent 57
java.io.class 90 message channel agent (MCA) 56
java.lang.class 90 message driven 75
java.net.class 90 message queues 48
java.util.class 90 message queuing 44
javac 94 message too large 50
JAVAPM.EXE 92 messaging 44
JDBC 92 messaging and queuing 44
JDK 36 method
download 27 close queue 133, 134
installation 26, 28 connect to queue manager 129
jdk114.exe 27 disconnect 130
get message 138
open queue 132
K put message 135
key ring file 20 server
connect to queue manager 141
method invocation (remote) 91
L middleware 43
leaf node 54, 55 model category 104
left-justify 107 MQBACK 73
links to Java SDK 34 MQBEGIN 73
listener 56, 66, 70 mqbind 139
how to start 60, 61 mqc4jdoc.zip 34
in MQSeries system 57 MQCLOSE 73
what it does 62 MQCMIT 73
local queue 48, 143 MQCONN 72
low cost 3 MQCONNX 72
MQDISC 73
MQEnvironment 129
MQException 129

222 Connecting to the Internet with MQSeries and VisualAge for Java
MQFirst MQSeries V5
guided tour 80 Bindings for Java 30
installation 78 Client for Java 30
quick start 85 database coordination 30
mqfirst.zip 78 description 1
MQGET 57, 72 distribution lists 30
MQI 43, 46, 55 fast channels 30
MQI calls 72 improved MQSC utility 30
examples 73 installation 31
MQI channel 47, 55 Internet Gateway 30
MQIIH 156 languages 31
MQINQ 73 major new functions 2
M Q M 43, 45 message groups 30
MQOPEN 73 message segmentation 30
MQPUT 56, 72 select components 33
MQPUT1 73 select destination directory 32
MQQueue object 132 SPX support 30
MQSeries 43 What′s new 29
API 43 MQSERVER 66
at runtime 43 mqservices 41
channels 54 MQSET 73
client 55
concepts 77
configuration 77 N
how it works 55 n32e301p.exe 24
IMS Bridge 151 NetBIOS 47
installation 29 Netscape Navigator 23
objects 46 download 24
OTMA support 151 install 24
o v e r v i e w 43 install window 25
port 1414 57 setup for Java 25
principle 45 network computer 89
queue manager 45 network preferences 25
se rve r 55 non-persistent message 44
Web page 33 non-visual bean 104
MQSeries Client for Java 31, 33 NT Service 18
advantages 3 NT421EPE_ENU.EXE 14
documentation 34, 35 NTFS 15, 39
how to get it 33
modes 36
appletviewer 37 O
Web browser 36 object properties 104
positioning 3 object serialization 91
recommendation 31 object-oriented 90
required JDK 31 objective 5
support pack MA83 33 objects
required 59

Index 223
objects (MQM) 46 queue (continued)
open queue 131 r e m o t e 48
connections 132 reply-to 49
method 132 transmission 48
OTMA 149 queue manager 45, 48, 145
OTMA client 149 connect 128
overview create 50
channels 57 default 50
IMS Bridge 149 disconnect 130
Java 87 functions 46
MQSeries 43 object manipulation 52
VisualAge for Java 87 objects 46
queuing 44
queuing system 55
P quick start (MQFirst) 85
package 101 quick start (VisualAge) 100
paint 96
persistent message 44
platform independence 87 R
port 66, 67, 129, 145 receiveMessage
port 1080 26 example 138
port 1414 57 reflection 91
println 94 remote method invocation 91
PrintStream 94 remote queue 48, 57, 59
process definition 48 what is it 58
program-to-program communication 45 reply message 44
project 101, 140 reply-to queue 49
proxy 25, 26 report message 44
public 94 repository 116
put message 134 request message 44
connections 136 resize 96
method 135 resize objects 107
putMessage return codes 73
example 135 robustness 89
RPC 46
RUNMQCHI 61
Q RUNMQLSR 60, 66
queue 47 RUNMQSC 46, 60
alias 49 example 53
close 133 interactive 52
dead-letter 50
define 52
dynamic 49 S
initiation 49 sample program
local 48 Hello World applet 95
example 53 Hello World application 94
open 131 VisualAge for Java 119

224 Connecting to the Internet with MQSeries and VisualAge for Java
sample programs trigger message 70
MQSeries APIs 73 trigger monitor 56, 57, 70
scenarios 3 trigger type 61
security 89, 91 triggering 62, 68
security preferences 26 tst files 142
se rve r 54, 55
server application 140
s er v er connection 65 U
how to test 67, 145 uni-directional 58
MQSeries client for Java 145 unit of work 73
triggering 62, 68 UNZ520X2 34
signed applets 91 unzip 34
slim client 54 URL
SNA LU 6.2 47 for Internet Connection Family 14
socks server 25, 26 for JDK 26
SPX 47 for MQSeries Client for Java 33
SSL port 20 for Netscape 24
start for server 21
applet 97 for support packs 33
channel 57, 60, 61 JDK 27
channel initiator 61 MQFirst 78
communication 60 MQSeries V5 3
ICSS 21 VisualAge for Java 38
IMS application 152
listener 61
MQFirst 79 V
server program 143 variable 106
VisualAge for Java 100 verify installation 37
static 94 versioning 113
Sun Java Development Kit 27 view applet 97
SupportPac MA83 33 Visual Age for Java
SupportPacs link 33 start 41
SVRCONN 65 visual programming 108
synchronous messaging 44 VisualAge
syncpoint 73 project 140
VisualAge for Java 38
a first try 100
T disk space requirements: 39
TCP/IP 47, 88 entry version 38
test application 142 example 119
test button 110 hardware requirements 38
test connection 63, 146 installation 38, 40
text field 103 o v e r v i e w 4, 87
time independent 75 setup 40
transmission queue 48, 57 uninstall beta 39
trigger 152 VTAM 149
channel program 61

Index 225
W
wEnty100.zip. 38
width of applet 97
workbench 101
workspace
add package 116
writeUTF() 135

X
XCF 149
XCF group 149
xmit queue 48, 57, 58

226 Connecting to the Internet with MQSeries and VisualAge for Java
ITSO Redbook Evaluation

Connecting the Enterprise to the Internet with MQSeries and VisualAge for Java
SG24-2144-00

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.com
• Fax this form to: USA International Access Code + 1 914 432 8264
• Send your comments in an Internet note to [email protected]

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

_____________________________________________________________________________________________________

_____________________________________________________________________________________________________

_____________________________________________________________________________________________________

_____________________________________________________________________________________________________

_____________________________________________________________________________________________________

 Copyright IBM Corp. 1997 227

IBML 

Printed in U.S.A.

SG24-2144-00