Digital PDFs

XX-94118-95

September 2004

12 pages

Original

64.2kB

Document:	HP BridgeWorks Version 3.0A Release Notes for OpenVMS
Order Number:	XX-94118-95
Revision:	0
Pages:	12
Original Filename:	bwx030a_release_notes.pdf

OCR Text

HP BridgeWorks Version 3.0A
Release Notes for OpenVMS
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 – RELEASE NOTES FOR OPENVMS

© 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 – RELEASE NOTES FOR OPENVMS

CONTENTS
RELEASE NOTES
1. Version 3.0A New Features Summary
2. Version 3.0 New Features Summary
3. Upgrading from BridgeWorks 2.1 or 2.1A
4. Configuration Considerations and Requirements
5. Known Limitations and Issues in Version 3.0A and 3.0
CONTACT AND SUPPORT INFORMATION

About HP BridgeWorks Version 3.0A Release Notes for OpenVMS
These Release Notes contain BridgeWorks Version 3.0A release information for both OpenVMS
and Windows.
For the OpenVMS installation instructions - including instructions for running the BridgeWorks
Manager and process quota recommendations - refer to
BWX030A_INSTALLATION_GUIDE.TXT|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 – RELEASE NOTES FOR OPENVMS

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.

1. 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.
Multi and Mixed Character Set Support
Java supports many different characters sets. BridgeWorks now supports the passing of strings
4

HP BRIDGEWORKS VERSION 3.0A – RELEASE NOTES FOR OPENVMS

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.

2. 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 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.

HP BRIDGEWORKS VERSION 3.0A – RELEASE NOTES FOR OPENVMS

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.

3. 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 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).
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
6

HP BRIDGEWORKS VERSION 3.0A – RELEASE NOTES FOR OPENVMS

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:
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.

HP BRIDGEWORKS VERSION 3.0A – RELEASE NOTES FOR OPENVMS

For example, in 2.1/2.1A, initializing and declaring structures was a two-step
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

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
8

HP BRIDGEWORKS VERSION 3.0A – RELEASE NOTES FOR OPENVMS

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

4. 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

5. Known Limitations and Issues in Version 3.0A and 3.0
Transaction Support for WebLogic
Although BridgeWorks Version 3.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
9

HP BRIDGEWORKS VERSION 3.0A – RELEASE NOTES FOR OPENVMS

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.
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).

HP BRIDGEWORKS VERSION 3.0A – RELEASE NOTES FOR OPENVMS

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 notransport 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 – RELEASE NOTES FOR OPENVMS

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/