Digital PDFs

XX-C96EB-D8

May 2004

21 pages

Original

95.5kB

Document:	HP BridgeWorks Version 3.0A Readme for Windows
Order Number:	XX-C96EB-D8
Revision:	0
Pages:	21
Original Filename:	readme.pdf

OCR Text

HP BridgeWorks Version 3.0A
Readme for Windows
September 2004

HP BridgeWorks Version 3.0A introduces new and innovative features that enable and
support enterprise-level distributed applications, and includes several important bug fixes.
This file contains information that will help you install and use this release of HP
BridgeWorks.

Software Version
HP BridgeWorks Version 3.0A

Hewlett-Packard Company
Palo Alto, Calif.

HP BRIDGEWORKS VERSION 3.0A – README FOR WINDOWS

© 2004 Hewlett-Packard Development Company, L.P.
Intel, Intel Inside, and Itanium are trademarks of Intel Corporation in the U.S. and/or other countries.
Microsoft, Windows, Windows XP, Visual Basic, Visual C++, and Win32 are trademarks of Microsoft
Corporation in the U.S. and/or other countries.
Java and all Java-based marks are trademarks or registered trademarks of Sun Microsystems, Inc. in
the U.S. and other countries.
BEA WebLogic Server is a trademark of BEA Systems Inc.
All other product names mentioned herein may be trademarks of their respective companies.
Confidential computer software. Valid license from HP and/or its subsidiaries required for possession,
use, or copying. Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer
Software Documentation, and Technical Data for Commercial Items are licensed to the U.S.
Government under vendor’s standard commercial license.
Neither HP nor any of its subsidiaries shall be liable for technical or editorial errors or omissions
contained herein. The information in this document is provided “as is” without warranty of any kind
and is subject to change without notice. The warranties for HP products are set forth in the express
limited warranty statements accompanying such products. Nothing herein should be construed as
constituting an additional warranty.

HP BRIDGEWORKS VERSION 3.0A – README FOR WINDOWS

CONTENTS
REQUIREMENTS AND INSTALLATION
1. Platform Requirements
1.1 Targeted Platforms
1.2 Generated Components
2. Installation, Development, and Runtime Requirements
2.1 OpenVMS
2.2 Windows
2.3 Additional OpenVMS Requirements
3. Installation Instructions
3.1 Uninstalling BridgeWorks From Windows
3.2 Installing BridgeWorks on Windows
3.3 Running BridgeWorks on Windows
RELEASE NOTES
4. Version 3.0A New Features Summary
5. Version 3.0 New Features Summary
6. Upgrading from BridgeWorks 2.1 or 2.1A
7. Configuration Considerations and Requirements
8. Known Limitations and Issues in Version 3.0A and 3.0

CONTACT AND SUPPORT INFORMATION

About HP BridgeWorks Version 3.0A Readme for Windows
This Readme file comprises system requirements for both Windows and OpenVMS,
installation instructions for Windows, and release information for both platforms.
For OpenVMS installation instructions, refer to
BWX030A_INSTALLATION_GUIDE.TXT|HTM|PDF|PS, available from the web download
page.
Complete product documentation is available from the online Help installed with the
Windows BridgeWorks kit.

HP BRIDGEWORKS VERSION 3.0A – README FOR WINDOWS

REQUIREMENTS AND INSTALLATION
1. Platform Requirements
HP BridgeWorks is a cross-platform tool. Installation consists of:

An OpenVMS Alpha kit, to be installed on each system on which you intend to run
BridgeWorks-wrapped servers.
A Windows kit for Windows XP or Windows 2000, to be installed on a development
machine, containing the BridgeWorks development tool, plus runtime libraries for
distribution if running Windows-based components.

Important
VAX is not a supported platform in this release. BridgeWorks Version 2.1A will continue to
be available for wrapping VAX-based applications.
1.1 Targeted Platforms
The purpose of BridgeWorks is to encapsulate and distribute an Alpha-based user
application. The server component encapsulates the application; the middle component
distributes it. The source code for both components is generated on the Windows platform
using a GUI-based development tool.
The generated source code for the server component must be built on the OpenVMS
system that hosts the application. The generated source code for the middle component
can be built on a networked Alpha system (clustered or not) or a networked Windows
system.
Server Component
The BridgeWorks-generated server component is a native OpenVMS image installed on
the system running the wrapped application (which can comprise 3GL server routines,
ACMS tasks, DCL procedures, and text files.)
Available on OpenVMS Alpha Version 7.3, 7.3-1, and 7.3-2
Note: OpenVMS Industry Standard 64 (Itanium) Version 8.2 and OpenVMS Alpha
Version 8.2 are not supported in this release.
Middle Component
The BridgeWorks-generated middle component is a JavaBeans, Enterprise JavaBeans
(EJB), or COM server that also acts as a client to the server component to make calls to
OpenVMS server routines, tasks, and procedures.
Available platforms for each component type are:
OpenVMS Alpha Version 7.3, 7.3-1, and 7.3-2
Windows XP and 2000
4

HP BRIDGEWORKS VERSION 3.0A – README FOR WINDOWS

1.2 Generated Components
The middle component can expose the application you are encapsulating, or wrapping, to
clients as JavaBeans, EJB, or COM objects. Only the appropriate source code is generated
by BridgeWorks.
Specific limitations are shown below according to component type. Note that COM
connections cannot be generated for ACMS tasks or for structure or array definitions in
3GL server routines. Note that transactions are only available for EJB components.
Component
EJB
JavaBeans
COM

Existing Application
3GL, ACMS, DCL, Files
3GL, ACMS, DCL, Files
3GL, DCL, Files

Transactions
Yes
Not Applicable
No

Structures
Yes
Yes
No

Not supported in this release:
Tru64 UNIX is not available as a target platform for middle components in this release.
Cross-platform limitations apply to COM:
Cross-platform COM connections - where a Windows client communicates with an Alphabased middle component - have produced inconclusive results related to account and
security issues. The following configurations are recommended instead:
1. Windows client to Windows COM middle component.
2. OpenVMS Alpha client to Alpha COM middle component.
Note: Your choice of component architecture should be guided by an understanding of the
relative merits and limitations of each component type for your particular distributed
application needs. It should take into account any preexisting middle-tier application server
and client codebase.

2. Installation, Development, and Runtime Requirements
These are the minimum system requirements needed to install BridgeWorks and to build
and run the generated components. “Optional” requirements represent requirements that
are not needed for every type of connection. However, several such requirements will apply
to your particular platform/component selection.
Make sure you have the latest MUPs, ECOs, and patches for your configuration.
Search for these on the Patch Download page.
http://www2.itrc.hp.com/service/patch/mainPage.do
Always Check Cross-Product Requirements!
Always check for cross-product software requirements, which can change with new
releases. These product requirements may be greater than for BridgeWorks itself.
For example, to run a BridgeWorks-generated EJB component requires OpenVMS
Alpha Version 7.3 or higher and a Java 2 Runtime Environment 1.3.1 or higher.
5

HP BRIDGEWORKS VERSION 3.0A – README FOR WINDOWS

Each Java SDK and RTE has specific ECO requirements. In addition, WebLogic
Server 7.0 (a J2EE 1.2-compliant application server) requires OpenVMS Alpha
Version 7.3 or 7.3-1, the Java 2 SDK 1.3.1-5 or higher, and additional ECOs as
specified. (See Section 2.3: Additional OpenVMS Requirements)
2.1 OpenVMS
Server Component - Installation Requirements
OpenVMS Alpha Version 7.3, 7.3-1, and 7.3-2
4,500 blocks during installation, 3,500 blocks after installation
System requirements vary enormously depending on the way you deploy your
BridgeWorks components.
Server Component - Development Requirements
The C Compiler is required to build all server components:
HP C Version 6.5 for OpenVMS Alpha or higher
Server Component - Optional Development Requirements
For automatic import and build features, you must enable REXEC and FTP
services.
TCP/IP Services for OpenVMS Version 4.2 or higher
TCP/IP for OpenVMS Home Page
http://h71000.www7.hp.com/network/tcpip.html

Server Component - Optional Runtime Requirements
You can choose between non-transport and transport-based options:
Non-Transport-Based Connections
None for Alpha-only, nontransactional connections.
Transport-Based Connections
You can use choose either ICC (Intra-cluster Communications) or RPC, or
both. (If you choose both, the BridgeWorks Manager automatically use
ICC in a cluster configuration and RPC in a noncluster configuration.)
ICC for OpenVMS Alpha Version 7.3 or higher
(Bundled with operating system)
or

HP BRIDGEWORKS VERSION 3.0A – README FOR WINDOWS

DCE RPC Runtime Services Kit Version 1.5 or higher
DCE for OpenVMS Home Page
http://h71000.www7.hp.com/commercial/dce/dce_index.ht
ml
For DCE RPC
OpenVMS Alpha DCE Denial of Service Security Patch Kit
Alpha Security ECO Kit For SSRT3608
http://www2.itrc.hp.com/service/cki/patchDocDisplay.do?p
atchId=ALP_DCE_030_SSRT3608
Middle Component - Optional Development and Runtime Requirements
For middle components, similar requirements apply during development and at
runtime.
For JavaBeans and EJB components
Java 2 SDK (“JDK”) Standard Edition 1.3.1-7 or higher
Runtime only
Java 2 RTE (JRE) Standard Edition 1.3.1-7 or higher
Java Software Patches (ECOs): See Section 2.3: Additional OpenVMS
Requirements
Java Technology for Alpha Download Page
http://h18010.www1.hp.com/java/download/
For COM components only
COM for OpenVMS Version 1.3
Compaq C++ 6.5 for OpenVMS Alpha
COM Denial of Service ECO kit for SSRT3608
COM for OpenVMS Home Page
http://h71000.www7.hp.com/openvms/products/dcom/
C++ for OpenVMS Home Page
http://h71000.www7.hp.com/commercial/cplus/cplus_index.html
ECO kit for SSRT3608
http://www2.itrc.hp.com/service/cki/patchDocDisplay.do?patchId=D
COM_013_SSRT3608-V0

HP BRIDGEWORKS VERSION 3.0A – README FOR WINDOWS

For EJB components only
A J2EE 1.2-compliant environment
Free 30-day evaluation license available for WebLogic Server.
Download Version 7.0 or 8.1 SP1 for HP OpenVMS.
See Section 2.3: Additional OpenVMS Requirements
BEA WebLogic Server Downloads Page
http://commerce.bea.com/showallversions.jsp?family=WLS
For Transactions (EJB components only)
DECdtm/XA SDK 2.1
This new release of DECdtm/XA ships on OpenVMS Version 7.3-2. It must
be installed as a layered product on OpenVMS Alpha Version 7.3 and 7.3-1.
Note: Version 2.1 is available as a layered product from the BridgeWorks
Download page.
BridgeWorks Home Page
http://www.hp.com/go/bridgeworks
Alpha System Recommendations for Java applications

System speed
System memory

Best
Above 500MHz
1GB or higher

Average
500MHz
512MB

Low
Below 500MHz
Minimum 256MB

“Average” represents the recommended minimums for deploying
Enterprise JavaBeans using BEA WebLogic Server.

For ACMS applications
A properly configured ACMS 4.3-or-later system.
2.2 Windows
Middle Component - Installation Requirements
Windows XP SP1 or Windows 2000 SP2 or higher
Note: 2000 Server or XP Professional recommended in a production
environment. 2003 Server has not been tested.
40MB minimum free disk space
128MB minimum RAM

HP BRIDGEWORKS VERSION 3.0A – README FOR WINDOWS

TCP/IP configured
Internet Explorer 5.5 or higher
Optional Development and Runtime Requirements
For middle components, similar requirements apply during development and at
runtime.
For JavaBeans and EJB components
Java 2 SDK (SDK) Standard Edition 1.3.1 or higher
Runtime only
Java 2 RTE (“JRE”) Standard Edition 1.3.1 or higher
For COM components only
Microsoft Visual C++ 6.0 SP5
Note: Visual C++ .NET is not supported and is not a substitute.
For EJB components only
A J2EE 1.2-compliant environment

2.3 Additional OpenVMS Requirements
ECO Downloads for Java 2 SDKs for OpenVMS
ECO Page for 1.4.2
http://h18010.www1.hp.com/java/download/ovms/1.4.2/sdk1.4.2_patches.h
tml
ECO Page for 1.4.1
http://h18010.www1.hp.com/java/download/ovms/1.4.1/sdk1.4.1_patches.h
tml
ECO Page for 1.4.0
http://h18010.www1.hp.com/java/download/ovms/1.4.0/sdk1.4.0_patches.h
tml
ECO Page for 1.3.1
http://h18010.www1.hp.com/java/download/ovms/1.3.1/sdk1.3.1_patches.h
tml
For BEA WebLogic 7.0 or 8.1 SP1 for OpenVMS
BEA WebLogic 8.1 SP1 for OpenVMS Requirements Page
http://edocs.bea.com/platform/suppconfigs/configs81/hpovms73_alpha/81s
p1.html
9

HP BRIDGEWORKS VERSION 3.0A – README FOR WINDOWS

BEA WebLogic 7.0 for OpenVMS Requirements Page
http://edocs.bea.com/platform/suppconfigs/configs70/hpovms73_alph
a/70sp1.html
3. Installation
Installation involves setting up HP BridgeWorks on (at least) two systems:

Installing the BridgeWorks Manager, development tool utilities, runtime library and
support files on OpenVMS.
(For OpenVMS installation instructions, see the BWX030A_INSTALLATION_GUIDE.TXT
|HTM|PDF|PS, available from the web download page.)

Installing the BridgeWorks development tool, runtime library and support files on
Windows.

Note: The BridgeWorks Version 3.0A Windows kit can only be used in conjunction with the
corresponding Version 3.0A OpenVMS kit. Subsequent field test and production releases
will require both installations to be repeated with the up-to-date kits.
3. 1 Uninstalling BridgeWorks From Windows
You should uninstall Version 3.0 before installing Version 3.0A of BridgeWorks. This is a
required step to ensure all files are properly replaced.
Before you begin
Back up your connection database to preserve your BridgeWorks connection database.

Copy the file BWXData_2_03.mdb to a secure location before uninstalling
BridgeWorks.

Instructions:
HP BridgeWorks should be uninstalled by first using the Windows Control Panel utility and
then removing remaining files and directories as necessary.
Follow the standard Windows uninstall procedure. (The following steps are for
Windows XP; some details may differ for Windows 2000):
1. Click the Windows Start button and click Control Panel.
2. Open Add or Remove Programs, select HP BridgeWorks, and click the
Change/Remove button.
3. Follow any on-screen instructions.
4. When the uninstall is complete, go to the location where BridgeWorks was installed
(usually, C:\Program Files\HP BridgeWorks) and delete all remaining files and
subdirectories EXCEPT for the BWXData_2_03.mdb file.

HP BRIDGEWORKS VERSION 3.0A – README FOR WINDOWS

3.2 Installing BridgeWorks on Windows
IMPORTANT UPGRADE INFORMATION: If your current version of BridgeWorks is 2.1 or
2.1A, the BridgeWorks installation process will automatically prompt you to import your
existing connection definitions into the new Version 3.0 and higher database. Your 2.1/2.1A
connection database will not be affected by this procedure.
This is your ONLY opportunity to import your existing connections unless you rerun the
installation.
Before you begin:

Your Windows user profile should include Administrator privileges to install
BridgeWorks.
Using BridgeWorks with a nonprivileged account
After installing, you can use a nonprivileged user account on Windows XP or 2000 to
run BridgeWorks. However, if you are installing to an NTFS partition on Windows 2000,
you must choose a directory with read and write privileges to do so. (The default
installation location, under \Program Files\ is protected, meaning that only users with
Administrator accounts are able to run BridgeWorks on Windows 2000.)
As with any Windows installation, you are recommended to:
-Do a system backup before proceeding.
-Exit all other Windows applications before installing.
The BridgeWorks setup includes Microsoft’s ODBC 3.0 files. The installation updates
files only if they need to be updated and creates a new ODBC data source called
“BWXData_2_03”. If you have a newer version of ODBC than 3.0, setup will leave this
as is.

Instructions for web download installation
1. Save the BridgeWorks self-extracting archive (BWX030A_Setup.exe) to a temporary
location on your disk by choosing the option to save the program to your disk.
2. In My Computer or Windows Explorer, double-click the downloaded file and wait for the
Setup Wizard to begin.
3. Follow the on-screen instructions in the Setup Wizard to complete the installation. You
will be prompted for any required information, including install location on your
Windows machine.
Note: Choose the Typical or Custom Install to get all the supplied files for tutorials and
examples.
After Installation:
ALWAYS restart J2EE environments, such as BEA WebLogic Server, or other bean
servers, such as Tomcat, after a BridgeWorks installation. Such environments do not
automatically refresh shareable images and libraries without being restarted.

HP BRIDGEWORKS VERSION 3.0A – README FOR WINDOWS

Environment Evaluation Wizard
The Environment Evaluation Wizard (EEW) is a utility included in the Windows kit
for post-installation diagnostics. For more information, see the EEW.chm Help file
that is distributed with the utility in the \HP BridgeWorks\Utilities\EEW directory.
Important: The EEW in this release has not been updated to reflect the current
Version 3.0A requirements.
3.3 Running BridgeWorks on Windows
To start the BridgeWorks development tool:
1. Click the Windows Start button and click Programs.
2. Click the BridgeWorks icon in the HP BridgeWorks program folder.
Using Help
Context-sensitive and reference-based online Help is available from:

The HP BridgeWorks Program Folder:
Click the BridgeWorks Help icon.
The BridgeWorks Development Tool
To get the Help Contents in the main BridgeWorks window, choose Help Topics
from the Help menu. Press F1 for window-level Help.
To search Help
Click the Search tab, type one or more words, and click List Topics.
To get What’s This Help in the BridgeWorks Wizard or a dialog box
Click the ? button once and click a control, or select a control and press F1.
To get Topic Help inside the BridgeWorks Wizard or a dialog box
Click the Help button.
Using the Tutorials and Examples:
In Help, open the Quick-Start Tutorials book in the Contents tree.

You’ll find complete instructions for building your first JavaBeans, EJB, or COM
connection, including simple clients. Supporting sample files, which are referenced in
the tutorial, are included in the BridgeWorks installation kit.
Important: Disregard references to VAX as a platform for wrapping applications using
BridgeWorks Version 3.0A.
Caution: In Version 3.0A, some published help topics are not fully updated or applicable to
Version 3.0A. Please Refer to “Key Usage Topics” (linked from the Help Welcome page) for
the most important topics. Note: Accuracy of web links cannot be guaranteed.
To check for updated documentation
From Help, click About Help and click the “Check for Updated Documentation” link.
(This opens a BridgeWorks web page from which you can download newer
documentation than in the installation kit if it is available.)

HP BRIDGEWORKS VERSION 3.0A – README FOR WINDOWS

RELEASE

NOTES

BEFORE YOU BEGIN YOUR PROJECT…
There are many more aspects to encapsulating and distributing an application than can be
addressed in these release notes. Please refer to key usage topics, available from the
BridgeWorks Help Welcome Page.
Among these usage topics are:
-

Preparation of 3GL Routines and ACMS Tasks
Transport Options
Scalability and Your Application
Session Options and Your Application
Making Configuration Changes
Working with Rdb and Oracle9i Databases
Debugging Your Server Routines
Using the Bwx Classes
Compiling and Running Java Clients

Performance Disclaimer – Please Read
HP makes no performance claims for BridgeWorks-generated applications.
Performance metrics for HP BridgeWorks are largely dependent on the
underlying cross-platform technologies used by BridgeWorks - including RPC
and ICC transports; COM, Java, and EJB components; J2EE application
servers; and DECdtm and XA protocols for transactions. Given the
complexities of distributed computing and the huge diversity of potential
production environments, including such factors as data throughput and
network speed, it is not possible to make any baseline assertions about the
performance you should expect.
For these reasons, it is strongly recommended that you obtain the advice of a
qualified services consultant before embarking on any major or mission-critical
project.

4. Version 3.0A New Features Summary
Multi-developer Support
The BridgeWorks UI now helps coordinate team members using a shared BridgeWorks
connection database. As developers work with a connection definition within BridgeWorks,
they are registered within the database itself. If other team members attempt to work with
the same connection definition (in that shared database), they are notified that it is being
modified, as well as who is modifying it. BridgeWorks then allows the developer to open the
connection definition in read-only mode.
New Installation Procedures
The OpenVMS kit has been changed to use PCSI, while the Windows kit has been
changed to use the latest Install Shield. The new installation procedures provide the user
with a more robust set of options, including an enhanced uninstall.

HP BRIDGEWORKS VERSION 3.0A – README FOR WINDOWS

Multi and Mixed Character Set Support
Java supports many different characters sets. BridgeWorks now supports the passing of
strings based on these many character sets. This support also includes the mixing of
character sets within a single string.
Better Support for ODS-5 Disks
BridgeWorks has improved its support for the ODS-5 file system. Previously, BridgeWorks
had problems seeing some directories and files with mixed case characters in its name.
Corrected Problems in Version 3.0A
Fixed ACCVIO in BWX$MANAGER
In some rare cases, the BridgeWorks Manager would ACCVIO when it could see,
but not open, a .bwx configuration file. Although the root cause of the problem is
environmental (such as bad file protections on the .bwx files), this has been fixed
so that the Manager no longer crashes.
Fixed FTP (Import) Issues
Various FTP/browsing errors have been resolved during the ANA import
procedure. These errors include files not being displayed in the file browse list, and
a possible BridgeWorks crash in some cases when a specified directory is invalid.
5. Version 3.0 New Features Summary
Support for Cross-Platform Transactions
BridgeWorks now enables two-phase commit transactions that originate from a Java client
and are coordinated by a J2EE transaction manager, such as BEA WebLogic Server.
BridgeWorks supplies all the infrastructure components for OpenVMS integration of
DECdtm-based 3GL or ACMS transactional applications and other resource managers including transaction-aware databases, such as Rdb and Oracle9i.
New Transport Options
An enhanced transport-layer architecture optimizes transport by providing ICC (Intra-cluster
Communications), RPC, or no-transport options. ICC provides clustered OpenVMS
systems with the fastest transport available. RPC transport no longer requires the DCE
RPC developer license.
More-Efficient Runtime Code
BridgeWorks now uses an improved component architecture that uses optimized runtime
libraries and reduces the amount of user-specific generated code. This reduces build times,
simplifies deployment, and improves maintainability.
New Server Management Services
The BridgeWorks Manager provides new directory services and server management for the
middle component. This includes load-balancing capabilities, such as keeping track of
available servers and maintaining pools of free servers (determined by configurable
parameters for minimum, maximum, and idle servers) to speed response times. These
extra capabilities allow some connections to avoid the high cost of process creation at
server startup.
SYSUAF-Based Security
BridgeWorks now supports OpenVMS SYSUAF-based client authentication. This means
that server processes will start up in the BridgeWorks default (SYSTEM or another
14

HP BRIDGEWORKS VERSION 3.0A – README FOR WINDOWS

specified) account, and clients will be able to use a log-in and log-out method to access
other OpenVMS accounts required to use the wrapped application.
Enhanced Structures
An enhanced structures scheme gives you the option of using Java-based get and set
access methods for individual fields. This implementation is consistent with the getter/setter
bean that is recognized by Java IDEs, such as NetBeans. By using enhanced structures,
you can simplify client coding and optimize call-time performance by doing most data
marshaling at the time the values are being read from and written to the client.
Structures Are an Abstract Class
The BwxStructure class is now an abstract class, rather than an interface
wrapper. Generated structure classes now inherit from it, which means it is no
longer, and can no longer, be referenced from a Java client. This greatly simplifies
the use of structures from within Java clients.
New BwxDecimal Class
A new BwxDecimal class is available to Java clients. Previously, OpenVMS
decimal string datatypes were handled as Strings. The BwxDecimal class
makes available the full range of Java’s BigDecimal class operations: basic
arithmetic, scale manipulation, comparison, hashing, and format conversion. (See
Section 5: Upgrading)
Enhanced Exceptions
In V3.0 and higher, BridgeWorks adds enhanced exception handling. There is now
a root exception class, BwxException, and two derived exception classes,
BwxServerException and BwxConnectException. BwxServerException
will be thrown for all server side exceptions, while BwxConnectException will be
thrown for all connection related errors/exceptions. All three exceptions thrown by
BridgeWorks also make available the internal status, the original OS status, the
severity level, and the facility code of the originator of the error. This allows a client
to better differentiate and classify the exceptions, and more easily make decisions
based on them.
6. Upgrading from BridgeWorks 2.1 or 2.1A
Version 3.0A of BridgeWorks has been designed to coexist with previous versions of
BridgeWorks. This is true for the development and the runtime environments. However, the
new scheme is not backward-compatible:

On OpenVMS
Version 3.0 and higher installs an enhanced BridgeWorks Manager. This replaces the
existing Version 2.0/2.1 Manager - using the same process name, BWX$MANAGER - and
renaming the 2.1/2.1A Manager to BWX$MGR_V21. If it is configured to start automatically,
the BWX$MGR_V21 process will continue to be available for 2.1/2.1A connections.
On Windows
The BridgeWorks Windows kit installs in C:\Program Files\HP BridgeWorks by default
(whereas previous versions installed in C:\Program Files\Compaq BridgeWorks by default).
The Version 3.0 and higher registry section is also new. The Version 3.0 and higher
connection database and data source are also named differently. Note that the Version 3.0
and higher database is named BWXData_2_03.mdb (and the Version 2.1/2.1A database
was named BWXData_2_02.mdb).
15

HP BRIDGEWORKS VERSION 3.0A – README FOR WINDOWS

Connection database upgrade
The BridgeWorks installation process prompts you to import existing connections
(in a 2.1 or 2.1A database) into the new database. This is your ONLY opportunity
to perform the automatic import unless you rerun the installation. Your existing
connection database is unaffected. When you generate the code for an existing
connection using Version 3.0 and higher, the new code that will be generated will
be entirely in the new component architecture. It is not backward-compatible.

Extended Method Code
Extended method code (customized middle component code) is no longer supported by
BridgeWorks. Any such code in your existing connections will NOT be saved or
regenerated. To find such code, in \middle directories generated by previous versions of
BridgeWorks, do the following:
1. In a text editor, open COM files named <Interface>_view.cpp or
JavaBeans files named C<Interface>Bean.java or EJB files named
<Interface>EJB.java. (You should find one for each interface defined in
your connection).
2. Look for the comment // To do: add your implementation inside the
*_PRESERVE tags.

Existing clients
Required changes to existing client code have been minimized as much as possible. In
fact, COM clients should not require any revision. Java clients previously compiled in the
2.1/2.1A environment will continue to compile and run in the BridgeWorks 2.1/2.1A
environment.
However, when an existing Java client is recompiled in the Version 3.0 and higher
environment, it will always require a change to its import statements.
New Package Statement
To use the BridgeWorks-supplied type classes, your client package statements
must be changed from:
import com.compaq.bwx.Bwx<Type>;
to:
import com.hp.bwx.Bwx<Type>;
Example of updated statements:
import com.hp.bwx.BwxLong;
import com.hp.bwx.BwxDecimal;
See Help: Using the Bwx Classes
Further changes are required if your existing clients use the BwxStructure class, or the
BwxString class for decimal string types.
New BwxStructure Class
The BwxStructure class now offers two modes of use: enhanced and standard.
If you are writing new Java clients, you are recommended to use the new
Enhanced mode. If you have existing clients, you can continue using the previous
structure wrapping scheme by making the following change:
16

HP BRIDGEWORKS VERSION 3.0A – README FOR WINDOWS

Upgrade Step
If you have existing clients, remove explicitly declared BwxStructure
parameters. The structure methods exposed by the middle component now
inherit all the properties of the BwxStructure class.
For example, in 2.1/2.1A, initializing and declaring structures was a twostep process:
structarraystruct mySt = new structarraystruct();
. . . . . .
BwxStructure p1 = new BwxStructure(mySt);
In Version 3.0 and higher, only the first step is required.
Error handling
BridgeWorks Version 3.0 and higher rearranges and adds exception classes in
order to better differentiate them for the client. However, depending on the current
exception handling used in the client, this may require changes to the client.
If the client code generically catches the Exception class, then no changes are
required. However, if the client code currently catches the BwxServerException
class explicitly, then this will minimally need to be changed to BwxException.
Optionally, you can add handlers to catch BwxException,
BwxServerException, and BwxConnectException independently. This allows
more flexibility in handling these different exception types.
All structures now require client error-handling code. This includes structure code
that previously did not throw exceptions in your clients.
Upgrade Step
The structure constructor ( new ) should always be in a try/catch block or in
a routine that can throw an exception to its calling routine.
See Help: Using the BwxStructure Class
New BwxDecimal Class
Previously, when building a Java client for a BridgeWorks connection, OpenVMS
decimal string datatypes were handled as Strings. This limited the range of
mathematical operations that you could perform on them. The BwxDecimal class
makes available the full range of Java’s BigDecimal class operations.
Upgrade Step
Change references to BwxString classes to BwxDecimal classes. The
BwxDecimal constructor can take BwxString or a regular String as an
argument.
Note: Clients can only pass in formats recognizable by the Java
BigDecimal class. For example, “+100.0”, but not “100.0+”.
See Help: Using the BwxDecimal Class

HP BRIDGEWORKS VERSION 3.0A – README FOR WINDOWS

New Component Build Commands
Build scripts have been streamlined and simplified, and now employ a simpler naming
scheme:
Server Component Build Script
BUILD_SERVER.COM
Middle Component Build Scripts
BUILD_<type>_MIDDLE.COM
build_<type>_middle.bat
where <type> can be jb for JavaBeans, ejb for Enterprise JavaBeans,
and com for COM.

BridgeWorks Middle Component and Client Support Files
In the case of JavaBeans and EJB connections, many support files previously generated
per connection are now included in a static file, BwxUtil.jar. (This reduces build times,
simplifies deployment, and improves maintainability.) On OpenVMS Alpha systems, this file
is installed in SYS$LIBRARY. On Windows, the default installation location for this file is in
\Program Files\HP BridgeWorks\lib. Middle component build commands use this library,
and your client compilation and run commands must include a reference to it also.
See Help: Compiling and Running Java Clients

7. Configuration Considerations and Requirements
ICC Startup File Should Be Enabled
When using ICC transport, it is highly recommended that you invoke the ICC$STARTUP file
by adding ICC$STARTUP in your SYSTARTUP_VMS.COM file.
Manager Requires LOG_IO Privilege
The server component uses an event mechanism to notify the BridgeWorks Manager when
it becomes free for new connections. The event mechanism makes use of a mailbox for
communicating with the Manager. OpenVMS requires the LOG_IO privilege for all mailbox
operations. The Manager and server now make extensive use of mailboxes to propagate
information about reservations, so the LOG_IO privilege is mandatory for both server and
Manager processes.
Making configuration changes
All server processes that the BridgeWorks Manager starts are detached processes running
out of the account specified in the server's configuration file (<CNXNAME>.BWX). Many
aspects of the server configuration for a particular connection are controlled by the
Manager according to your customizable configuration settings. For example, you can
effect per connection stack-size adjustments using the configuration file. The default is for
DECThreads to use the system’s default stack size. However, higher values will be
required for some connections, including ones where Oracle9i participates in XA
transactions.
See Help: Making Configuration Changes
18

HP BRIDGEWORKS VERSION 3.0A – README FOR WINDOWS

8. Known Limitations and Issues in Version 3.0A and 3.0
Transaction Support for WebLogic
Although BridgeWorks V3.0 and higher works with BEA WebLogic Version 6.1 and higher,
the transaction support within BridgeWorks does not work properly with WebLogic Version
7.0 and higher. In particular, when two EJBs are called as part of the same transaction, and
both are part of the same Domain, the transaction fails when the second EJB is called. This
is an identified problem in WebLogic. The HP BridgeWorks engineering team is currently
working with the WebLogic team to resolve this issue.
Workaround: Use WebLogic Version 6.1. If you are using WebLogic Version 7.0
or higher, specify a unique domain name for each EJB type. This forces WebLogic
to use two Phase Commit Transactions when multiple EJBs are used in the same
transaction.
Transactions Fail if WebLogic’s JTA Health Monitor Times Out
Recent versions of WebLogic may mark a Resource Manager (RM), including the
BridgeWorks RM, as bad if a transaction takes too long. This is caused by the internal
timeout value of WebLogic's JTA health monitor. (By default, the JTA health monitor
timeout value is set to two minutes within WebLogic, which is a different value than the
normal transaction timeout.) Once this timeout occurs, all further attempted transactions
may fail. The only way to clear this condition is to restart WebLogic.
Workaround: Override the JTA health monitor timeout value by adding the
following lines to WebLogic's config.xml file, within the section for the domain
that you are using:
<JTA
MaxXACallMillis="240000"
/>
Handling Cluster Transition Delays
When running a BridgeWorks-generated EJB within an OpenVMS Cluster, the delay
caused by a cluster transition may sometimes cause the server process supporting the EJB
to crash. If this happens, the Java client that initiated the connection will get a Java
exception returned for that EJB session.
Workaround: You can design your client to recover from the failed connection
exception and reestablish a new connection. Since the EJB remains active, the
BridgeWorks Manager will start up a new user server process to do a retry of the
failed session or to service a subsequent EJB sessions.
COM-Related
A number of limitations and other errors related to COM connections are under
investigation and have not been resolved in this release.
COM on OpenVMS Middle Component
Account and security issues related to running unauthenticated COM middle
components on OpenVMS from a Windows client are under investigation. For this
release, you are recommended to build and run COM middle components on
Windows systems.

HP BRIDGEWORKS VERSION 3.0A – README FOR WINDOWS

Log File Cleanup
In BridgeWorks V3.0 and higher, all server processes generate a log file (in addition to the
BridgeWorks Manager log file). By default, the Manager removes these server logs
periodically. To keep the logs, set the logging level to 2 or higher:
$ DEFINE /SYSTEM BWX$LOGLEVEL 2
Note: This logging level is more verbose and log files can become large rapidly
(depending on the number of server being started).
Generated Code to Wrapper C++ Needs Modifying
In order to wrapper C++ applications, C extern statements must be removed from the
generated .c and .h files. (These statements normally prevent name mangling of 3GL
routine signatures.)
No-Transport Option Is Not Applicable to Single-Threaded Applications
Do not attempt to run a nonthreadsafe application (such as a COBOL-based application) in
a no-transport environment. In the BridgeWorks no-transport option, the wrapped
application image is loaded directly into the same process as the JVM. If the JVM is part of
a larger environment, like BEA WebLogic or Tomcat, this will likely result in a handled
exception when the COBOL application is accessed.

HP BRIDGEWORKS VERSION 3.0A – README FOR WINDOWS

CONTACT AND SUPPORT INFORMATION
Software Support Contract
Standalone software support is available for HP BridgeWorks. For more information,
contact your local HP support center at:
http://welcome.hp.com/country/us/en/contact_us.html
General Comments and Feedback
You may submit your technical suggestions and feedback to the BridgeWorks engineering
team by sending mail to:
BridgeWorks@hp.com
Please do not use email for time-critical technical support questions, as response from the
BridgeWorks engineering team is on a time-available basis only.
If you would like to provide comments or general feedback about the e-Business offerings
on OpenVMS, please send mail to:
OpenVMS.eBusiness@hp.com
BridgeWorks Home Page
http://www.hp.com/go/bridgeworks/