| Note |
|---|
|
Before using this information and the product it supports, read the information in Appendix B, Notices. |
Fourth Edition (September 2002)
This edition applies to the Host Access Toolkit component of IBM(R) Host On-Demand Version 7.0, and to all subsequent releases and modifications until otherwise indicated in new editions.
© Copyright International Business Machines Corporation 2000, 2002. All rights reserved.
U.S. Government Users Restricted Rights -- Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
Introducing the Host Access Toolkit
Planning for the Host Access Toolkit
Installing the Host Access Toolkit
Migrating from a previous version of the Host Access Toolkit
Introducing the Host Access Toolkit Application Programming Interfaces
Appendix A. Installing the iSeries Toolbox for Java
This book provides information necessary for you to install the Host Access Toolkit. It is intended for use by programmers and system administrators.
Information that is specific to Host On-Demand and Screen Customizer is
identified by using the following icons:
|
| This icon is used to denote information unique to Host On-Demand. |
|
| This icon is used to denote information unique to Screen Customizer. |
The Host Access Toolkit consists of the Host Access Class Library application programming interface (API), the Host Access Beans for Java(TM) API, and the Host On-Demand Java 2 Enterprise Edition (J2EE) Connector API. Programmers can use these APIs to write custom applications to either run with the IBM WebSphere Host On-Demand (hereafter referred to as Host On-Demand) product 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:
Additional and improved support items of note for the toolkit are:
Host On-Demand macros now support extraction of the following host screen information in addition to text:
Host On-Demand stores the screen attributes as planes.
The Screenable interface is supported along with the older Streamable screen interface. Its advantages over the Streamable interface include the following:
Macro functionality has been enhanced to support the following:
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 Redbook (SG24-6182-00, ISBN 0738424242), 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.
A typical installation of the Host Access Toolkit requires 110 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.3.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:
|
Applications or applets written for HACL are portable between Host
On-Demand and Personal Communications.
|
| The API books describe functionality for both the Host On-Demand and Personal Communications environments. Functions specific to Personal Communications are flagged. However, these books are not meant to serve as the documentation for Personal Communications support. Please refer to the version of the books supplied with your version of Personal Communications to determine the specific functions supported in that environment. |
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. |
|
|
 | CustomTerminal - This visual bean is installed with Screen Customizer and provides a customizable graphical interface for displaying host data. Only KeyPad, KeyRemap and FileTransfer beans can be wired to this bean. |
|
|
 | 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 CustomTerminal bean is wired similarly to the Terminal bean;
however, only KeyPad, KeyRemap, and FileTransfer beans can be wired to the
CustomTerminal 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 services 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.