Before using this information and the product it supports, read the information in Notices.
This edition applies to the Host Access Toolkit component of Version 8.0 of IBM WebSphere Host On-Demand (program number 5724-F69) and to all subsequent releases and modifications until otherwise indicated in new editions.
This book provides information necessary for you to install the Host Access Toolkit. It is intended for use by programmers and system administrators.
The Host Access Toolkit consists of the following application programming interfaces (APIs):
Programmers can use these APIs to write custom applications to either run with the IBM(R) WebSphere Host On-Demand product (hereafter referred to as Host On-Demand) or run standalone as a custom host access application.
The Host Access Toolkit is available on a separate CD-ROM that is shipped with the Host On-Demand product. This CD-ROM contains all of the Host Access programming API's and documentation necessary for writing Host Access applets and applications.
The following APIs make up the Host Access Toolkit:
The documentation for the Host Access Toolkit programming APIs now pertains only to the supplied libraries, which are in common with Host On-Demand Version 8.0 (HOD). The equivalent APIs for Personal Communications Version 5.8 (PCOMM) are documented separately with that product.
For more detailed information about what's new in each of the APIs, see the following reference publications:
The publications, Web sites, and news groups listed in this section provide helpful information for using the Host Access Toolkit Java APIs.
|
|
You can directly link to most of the resources referenced below; however, if you are viewing the PDF version of this book, you must do so using the browser plugin capability of the Adobe Acrobat Reader |
IBM Host Access Client Package Update Redbook (SG24-6182-01, ISBN 0738427802), available from http://www.redbooks.ibm.com/abstracts/sg246182.html.
Developers using the Host Access Toolkit APIs can make use of a number of Web resources, including the following:
The Sun Microsystems J2EE connector Web site: http://java.sun.com/j2ee/connector/
The following news groups require access to a Usenet newsgroup server and a client news reader:
|
|
For the most up-to-date version of the requirements, see the README file and the Host On-Demand Web site. |
The Host Access Toolkit CD-ROM provides an installation utility for the following operating systems:
Applications or applets developed using the Host Access Toolkit can be ported to other operating systems that support Java; however, installation of the toolkit is not supported on those other systems. The necessary toolkit jar files needed to run your application or applet can be packaged with your application or applet and copied to those other systems according to the terms of your licensing agreement.
This toolkit supports all the operating systems supported by Host On-Demand. For a list of the operating systems supported by Host On-Demand (both for the Host On-Demand server and for the Host On-Demand client), see Planning, Installing, and Configuring Host On-Demand in the Host On-Demand documentation.
A typical installation of the Host Access Toolkit requires 126 MB of disk space.
The Host Access Toolkit supports the following browsers:
The Host Access Beans for Java are now supplied for both JDK 1.1.8 and Java 2 (JDK 1.4.0).
The Java 2 JAR libraries can only be run in a browser that has the Java 2 plug-in enabled or launched in a Java 2 virtual machine. The Java 2 version is Swing-based and should integrate well with other Swing components. There are known issues when building applications or applets that use both AWT components and Swing components. For more information on compatibility between AWT and Swing components, see the Sun Java Web site, java.sun.com.
The Java 2 version of the Host Access Beans offers accessibility, autoIME/on the spot conversion for double-byte character set (DBCS) languages, and print screen enhancements. Pure JDK 1.1 applets and applications that use the Host Access Toolkit JDK 1.1.8 libraries are runtime compatible with the Java 2 Virtual Machine. However, applets and applications built with the Java 2 libraries are strictly incompatible with a JVM version 1.1.
The traditional JDK1.1.8 version of our APIs is most suited for applets intended for JDK1.1-based browsers or for applications launched into a Java Virtual Machine version 1.1. These JDK1.1.8 libraries (JAR and CAB) are compatible with previous versions of the Host Access Toolkit.
|
|
The latest version of the Java Virtual Machine runtime environment for your server can be downloaded from the IBM Developer Kit Porting Web Page: http://www.ibm.com/developerworks/java/jdk/?dwzone=java. |
The basic steps for installing the Host Access Toolkit on a Windows system are as follows:
|
|
If AutoPlay has been turned off, do the following:
|
Previous installations of Host On-Demand do not affect installation of the Host Access Toolkit. Host Access Beans for Java and Host Access Class Library applications and applets written using a previous version of Host On-Demand will work with this version of the Host Access Toolkit.
The following sections describe each application programming interface (API) in the Host Access Toolkit:
The Host Access Class Library (HACL) for Java provides a set of classes and methods that allow the development of platform independent applications that can access host information at the data stream level. HACL implements the core host access function in a complete class model that is independent of any graphical display and only requires a Java-enabled browser or comparable Java environment to operate. The class library represents an object-oriented abstraction of a host connection that includes reading and writing the host presentation space, enumerating the fields in the presentation space, reading the operator information area (OIA) for status information, transferring files, host printing, and performing asynchronous notification of significant events.
With HACL, application developers can write Java applets that manipulate data from the data stream presentation space (such as 3270, 5250, and Virtual Terminal) without requiring the users to have the applets residing on their machines. The presentation space represents a virtual terminal screen that contains both data and associated attributes presented by host applications. HACL Java applets can open a session to the host, wait for incoming host data, get specific strings from the imaginary screen, get associated attributes of the strings, set new string values, send data stream function keys back to the host, and wait for the next host response. After an interaction is complete, the applet can switch to other tasks or simply close the session. The entire operation can be done without ever showing host screens.
Host On-Demand's HACL implementation provides the following additional benefits:
The Host Access Beans for Java provide emulator functions as a set of JavaBeans components. JavaBeans components have configurable properties, use events to communicate, and can be manipulated in visual development environments. (See the Sun JavaBeans API Specification for more information). The Host Access Beans can be used by developers to rapidly develop custom applications that deliver the specific functions they want to include in their host access applications.
Each bean description below is preceded by the icon used to represent the bean in most visual development environments.
 |
Session - This non-visual bean provides methods and properties for setting up and establishing communications with the host system. The Session bean fires events that allow listeners to be notified of presentation space, operator information area (OIA), and communication changes. | |
 |
Screen - This visual bean provides the graphical interface for displaying the host data from a Session bean. The Screen bean listens to presentation space, OIA, and GUI events fired by the Session bean and interprets the events to display the main text area and the operator information area. It fires keystroke events to registered listeners, and also provides the clipboard cut, copy, and paste functions. | |
 |
Terminal - This visual bean combines the Session and Screen beans to provide a composite bean that encompasses both the communication with the host and the graphical interface for displaying the host data. | |
 |
KeyPad - This visual bean provides a simple grid of buttons which invoke various host functions. | |
 |
KeyRemap - This visual bean provides keyboard remap capability. Using KeyRemap, keystrokes can be mapped to alternate characters or directly to host functions. | |
 |
FileTransfer - This visual bean provides a toolbar interface for transferring files to and from a host. | |
 |
Macro - This non-visual bean records
and plays a single macro. Macro employs advanced screen recognition technology
to reliably navigate host applications in any environment. Macro also provides
the ability to prompt for user input and extract the following information
from the screen during playback:
|
|
 |
MacroManager - This visual bean provides a toolbar interface for managing multiple macros. The MacroManager bean allows you to record, play, load, delete and edit multiple macros. | |
 |
Color Remap - This visual bean provides a simple interface for modifying the colors displayed by the Screen or Terminal beans. |
|
 |
HostPrintSession - This non-visual bean extends the Session bean and provides a simple interface for creating and customizing 3270 and 5250 printer sessions. | |
 |
HostPrintTerminal - This visual bean includes the HostPrintSession bean and provides an interface for creating and customizing a 3270 or a 5250 printer sesison. At run-time, the HostPrintTerminal bean visually displays information about the status of print jobs and the connection with the host. | |
 |
Converter - The Converter bean performs a codepage-to-codepage conversion. For the Arabic and Hebrew languages, Converter performs certain BIDI-specific transformations, including logical-to-visual transformations, visla-to-logical transformations, and Lam-Alef processing (Arabic only). |
The following diagram shows the major events that are passed between each of the Host Access Beans and the composition of the Terminal bean.
The HostPrintSession bean is actually an extension to the Session bean; however, it is shown separately in the diagram to indicate the events that HostPrintTerminal listens for.
Host On-Demand offers accessibility features to help users who have physical disabilities (such as restricted mobility, limited or no vision, or limited or no hearing) use host sessions successfully. Features include keyboard equivalents for all actions (mouseless operation), support for display system settings for size, font, and color for user interface controls, and descriptive text for selected graphics.
The following visual Host Access Beans for Java have accessibility features built into their graphical user interfaces:
To use these accessibility features, you must have the Java 2 plug-in installed. Note that some beans (such as the FileTransfer bean) do not fully support all accessibility features.
Host On-Demand J2EE Connector is based on version 1.0 of the Sun J2EE Connector Architecture Specification. Before the J2EE Connector architecture was introduced, there was no standard architecture for integrating heterogeneous Enterprise Information Systems (EIS). Host On-Demand users had to use Host Access Class Library (HACL) to access hosts; other vendors provide specific architectures for this purpose. J2EE Connector architecture provides a standard set of Application Programming Interfaces (APIs) allowing developers to quickly connect and integrate their applications with virtually any backend EIS, and to any application servers conforming to the J2EE Connector architecture.
The Host On-Demand J2EE Connector provides access to 3270, 5250, Customer Information and Control System (CICS), and Virtual Terminal (VT) hosts from the Internet. The Host On-Demand J2EE Connector is a Java programming interface which conforms to the J2EE Connector Specification version 1.0 from Sun Microsystems, and the Common Client Interface (CCI) infrastructure. This interface is intended for use with these products to develop applications in a consistent manner with other connectors.
An application or servlet uses the Host On-Demand J2EE Connector classes for host access over TCP/IP using standard telnet protocols: TN3270, TN5250, CICS or VT emulation. For 3270 and 5250 hosts, a telnet server gateway (such as IBM's Communications Server family of products) is used to translate the incoming telnet stream into an SNA datastream. Host On-Demand supports encryption of the datastream for telnet servers which support Secure Sockets Layer (SSL).
The Host On-Demand J2EE Connector provides a set of Resource Adapters which communicate to 3270, 5250, CICS, and VT hosts. These Resource Adapters (.RAR files) are deployed to a conforming application server; users then write applications or servlets using the application programming interfaces (APIs) provided by Host On-Demand J2EE Connector in WebSphere Studio Application Developer - Integrated Edition (WSAD-IE). WSAD-IE and its tools are used to write and test user applications and servlets. These applications and servlets are then deployed to an application server that supports the J2EE Connector architecture, such as WebSphere Application Server.
J2EE Connector is just one of the programming environments that Host Access Toolkit users can use to develop customized applications, applets, and servlets. In other environments, where the customer needs the complete functionality of Host On-Demand, the HACL and JavaBeans interface should be used.
For more information on the J2EE Connector architecture, see the Sun J2EE Connector Architecture Web site at http://java.sun.com/j2ee/connector/.
The iSeries Toolbox for Java is shipped on the Host Access Toolkit CD-ROM. It consists of a set of Java classes that enable you to write client/server applications and applets that work with data residing on your iSeries system. You can also run these applications on the OS/400 Java Virtual Machine (JVM).
The Toolbox uses iSeries servers as access points to the system. Each server runs as a separate job on the iSeries, and each job sends and receives datastreams on a socket connection.
The access classes provide low-level access to the following iSeries resources:
Graphical programming interfaces are available for:
The following files are located on the Host Access Toolkit CD, not the OS/400 CD:
To install the iSeries Toolbox for Java on your workstation, unzip the appropriate files. For example, if you want to install the code and the English version of the Programmers Guide, unzip jt400_all.zip and jt400_doc_en.zip .
|
|
You must use a utility that supports long filenames. |
For additional information on the toolbox, see http://www.as400.ibm.com/toolbox.
This information was developed for products and services offered in the U.S.A. IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service.
IBM may have patents or pending patent applications covering subject
matter described 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:
IBM Director of Licensing
IBM Corporation
North Castle Drive
Armonk, NY 10504-1785
U.S.A.
For license inquiries regarding double-byte (DBCS) information, contact
the IBM Intellectual Property Department in your country or send inquiries,
in writing, to:
IBM World Trade Asia Corporation
Licensing
2-31 Roppongi 3-chome, Minato-ku
Tokyo 106, Japan
The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.
This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice.
This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice.
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
Department T01
Building B062
P.O. Box 12195
Research Triangle Park, NC 27709-2195
U.S.A.
Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee.
The licensed program described in this information and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement, or any equivalent agreement between us.
Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products.
Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk.
IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you.
If you are viewing this information softcopy, the photographs and color illustrations may not appear.
The following terms are trademarks of the IBM Corporation in the United States or other countries or both:
Lotus(R) and Domino(TM) are trademarks or registered trademarks of Lotus Development Corporation in the United States, or other countries, or both.
Java, JavaBeans JDK(TM) and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States, other countries, or both.
Microsoft(R), Windows, Windows NT, and the Windows logo are registered trademarks of Microsoft Corporation in the United States, other countries, or both.
Other company, product, and service names may be trademarks or service marks of others.