1. Accessing current release bulletin information
A more recent version of this release bulletin may be available on the Web. To check for critical product or document information added after the release of the product CD, use the Sybase Technical Library Product Manuals Web site.
Accessing release bulletins at the Technical Library Product Manuals Web site
Go to Product Manuals.
Follow the links to the appropriate Sybase product.
Select the Release Bulletins link.
Select the Sybase product version from the Release Bulletins list.
From the list of individual documents, select the link to the release bulletin for your platform. You can either download the PDF version or browse the document online.
2. Product summary
Windows 2000 version 5.0, Service Pack 4
Windows NT 4.0, Service Pack 6
SUN Solaris 2.8, patch level 20 or higher
IBM AIX 4.3.3 and 5.1
HP Tru64 Unix 5.0A
Linux Red Hat AS 2.1, glibc-2.2.4-32.15, kernel level 2.4.9e.40enterprise#1 smp.
Also enclosed is the Replication Coordination Module (RCM), a coordination module for OpenSwitch Server version 12.5.1, which is compatible with the following platform and operating system configurations:
HP9000/700, HP9000/800, or 64-bit HP9000 D, K, V Series running HP-UX 11.0 or HP-UX 11.0 with 64-bit runtime kernel
IBM AIX 4.3.3 and 5.1
Sun Solaris 2.8
Windows NT 4.0 Service Pack 6
Windows 2000 version 5.0, Service Pack 4
Linux Red Hat AS 2.1
The RCM application contains the following files:
rcm.exe – RCM executable.
rcm.loc – RCM locales files.
osw_rcm.cfg – sample OpenSwitch configuration file.
rcm.cfg – sample RCM configuration files.
Run_rcm_name – run script that calls the RCM executable.
3. Special upgrade instructions
The internal structure of the coordination module library in OpenSwitch 12.5.1 has changed and some APIs have been added, so after installing OpenSwitch 12.5.1, you must rebuild your existing coordination module applications with the new header files and coordination module library.
See the sample Makefile in $OPENSWITCH/sample for an example of how to modify your Makefile.
See the Installation Guide for upgrade instructions.
4. Changed functionality in this version
4.1 New command line options for OpenSwitch
Some command line options have been added:
-Efilename – allows encryption of user names and passwords in the OpenSwitch configuration file.
-p – allows you to encrypt a particular string. The output is written only to the console.
For information about command line options, see Chapter 3, “Starting and Stopping OpenSwitch” in the OpenSwitch Administration Guide.
4.2 Multithreaded coordination module
The coordination module library libcm has changed from a single-threaded model to a multithreaded model. When libcm was single-threaded, it monitored all incoming notifications, check message queues, and timer queues for each of the coordination module instances serially. With the single-threaded model, if the coordination module needs to deal with multiple OpenSwitch servers, it could hang in many places because the processing of one coordination module connection could delay the processing of the others.
With the multithreaded model, a thread is created for each coordination module instance within the context to receive and process notifications, messages, and timers from one OpenSwitch server. These threads run independently and are not affected by the processing of callbacks on the other threads. Therefore, the notifications and messages from different OpenSwitch servers are handled simultaneously, and server failures are detected instantaneously without any delays introduced by the coordination module.
4.2.1 Recompiling the coordination module
Check your coordination module source code to ensure that these rules are followed:
Callback handlers always return CS_SUCCEED or CS_FAIL. Returning CS_SUCCEED from a callback ensures that the coordination module program continues to run. Returning CS_FAIL from a callback causes the cm_run function to return, and the whole program to exit after calling cm_destroy and cm_exit. Under no circumstance should a callback handler call exit() directly to exit the program.
At cleanup, cm_destroy is called only once for each coordination module instance that was created using cm_create(). If cm_destroy is called multiple times on the same coordination module instance, it can free memory that was already freed, causing undefined behavior on some platforms.
The library path (LD_LIBRARY_PATH on Sun Solaris, Linux, and HP Tru 64 UNIX; LIBPATH on AIX; SHLIB_PATH on HP; and PATH on Windows) is pointing to the new libraries released with OpenSwitch 12.5.1, which are located in OpenSwitch-12_5/lib and OCS-12_5/lib on UNIX and OpenSwitch-12_5\lib and OCS-12_5\dll on Windows. The new libcm requires the OCS libraries from OCS 12.5.1 ESD#3 or above to work properly.
After verifying that your coordination module program adheres to these set of rules you must recompile your coordination module with the newest cm.h header file (located in $OPENSWITCH/include on UNIX and %OPENSWITCH%\include on Windows) and link it with the newest libraries.
If you need to modify your coordination module program to adhere to these rules, use the cm1.c program in the $OPENSWITCH/sample directory as a guide.
When linking the coordination module on Sun Solaris and HP Tru 64 UNIX platforms, you must add -lrt to the link line in your Makefile. As an example, see the OSW_LIBS in the sample Makefile located in $OPENSWITCH/sample
4.3 Timeout support in the coordination module
You can now define timeout values other than the 60-second default for the coordination module applications’ connections to the OpenSwitch server. See the timeval variable in the cml.c sample located in $OPENSWITCH/sample on UNIX and %OPENSWITCH%\sample on Windows for an example of how to set this in your application.
For information about compiling the coordination module, see the Coordination Module Reference Manual.
4.4 New configuration options
There are new configuration options in OpenSwitch 12.5.1. If you are using the configuration file from your previous OpenSwitch installation, add the new configuration options that are applicable to your environment.
The new configuration options and their default settings are:
USERNAME_PASSWORD_ENCRYPTED = 0
USE_AND_TO_POOL_ATTRIB = 0
USE_AND_TO_RMON_ATTRIB = 0
NOWAIT_ON_LOCKED = 0
SHOW_CONNECT_ERROR = 0
4.5 New coordination mode
The coordination mode indicates how Adaptive Server should respond in the presence of a coordination module. OpenSwitch 12.5.1 has a new coordination mode:
ENFORCED – the presence of a coordination module is required. If a coordination module is unavailable when a client makes a request, the request is refused and an informational message is sent back to the client.
ENFORCED is the recommended coordination mode in the configuration of OpenSwitch when using the RCM. the coordination mode ALWAYS still works correctly, but ENFORCED is recommended.
4.6 Warnings of capabilities of TDS level change during failover
During a failover, OpenSwitch verifies that the capabilities and tabular data stream (TDS) level of the new Adaptive Server Enterprise match those of the Adaptive Server the connection was originally established with. If they do not match, a warning is written to the log file. If an application has problems because of this difference, terminate, then restart, the application.
4.7 User name and password encryption
You can configure OpenSwitch to use encrypted user names and passwords for the user name and password entries in the OpenSwitch configuration file. See Chapter 4, “Using the Configuration File” in the OpenSwitch Administration Guide.
4.8 New coordination module APIs
There are six new coordination module APIs:
cm_short_ping – sets a time limit on the number of seconds the coordination module is allowed to establish its connection to the Adaptive Server Enterprise server before determining that it is inaccessible. Use cm_short_ping if you want notification of a failure between the coordination module host and the Adaptive Server host sooner than the cm_ping standard of 60 seconds.
cm_repeat_ping – verifies the health of a remote server, repeating up to the specified number of times if a failure occurs.
cm_repeat_short_ping – similar to cm_repeat_ping, except it also sets a time limit on the duration each ping waits when a failure occurs.
cm_version – displays the coordination module version information.
cm_connect_enc – similar to cm_connect, except it allows use of encrypted user names and passwords.
cm_ping_enc – allows for use of encrypted user names and passwords. Calls cm_repeat_short_ping if maxretry and timeout are greater than zero, cm_repeat_ping if maxretry is greater than zero and timeout is not, and cm_short_ping if either maxretry or timeout are zero, or maxretry is zero and timeout is greater than zero.
See the Coordination Module Reference Manual for more information.
4.9 Starting OpenSwitch as a service on Windows
In OpenSwitch 12.5.1, you can start OpenSwitch as a service on Windows. See “Starting OpenSwitch” in the Installation Guide for instructions on how to start OpenSwitch as a service on Windows.
5. Known problems
5.1 Known problems with OpenSwitch 12.5.1
This section describes known problems in OpenSwitch 12.5.1.
5.1.1 Error in configuring the sample Replication Server when Replication Server is installed in the same SYBASE location as ASE and OpenSwitch
[CR #355040] If ASE, OpenSwitch, and Replication Server are installed in the same SYBASE location, Replication Server throws an error in configuring its sample Replication Server. This happens only when OpenSwitch is configured to use the ASE that already has an entry in the interfaces file on UNIX and sql.ini file on Windows.
Workaround: Before installing Replication Server in the same installation location as OpenSwitch, check the $SYBASE/interfaces file on UNIX and %SYBASE%\ini\sql.ini on Windows and remove any duplicate server name entries if they exist.
5.1.2 Client connects to OpenSwitch even if invalid CMON user name is specified
[CR #352059] The client connects to OpenSwitch as a normal user (connected to the primary Adaptive Server) even if an invalid CMON user name is specified in the OpenSwitch configuration file. This leaves the client in an undefined state when OpenSwitch is configured for HAFailover mode and a failover occurs to the secondary Adaptive Server.
Workaround: Specify a valid CMON user name in the OpenSwitch configuration file. The CMON user name is valid if that user is a valid Adaptive Server user.
5.1.3 CMON_USER and CMON_PASSWORD not configurable
[CR #314085] Currently, CMON_USER/CMON_PASSWORD are configurable at the OpenSwitch level ([CONFIG] section), which applies to all servers, and are not configurable in the [SERVER] section, which applies to the server only. This functionality is scheduled to be in a future release.
5.2 Known problems with Replication Coordination Module
5.2.1 On HP platforms, RCM may hang after execution of a user-defined executable/script
[CR #353088] The RCM allows execution of user-defined executables/scripts when certain major events occur. For example, a user can specify that an e-mail be sent if the RCM loses its connection to OpenSwitch. RCM may hang after execution of this user-defined script.
When running on an HP platform and detecting an RCM event, RCM correctly runs the specified user-defined executable/script and continues processing the tasks pertaining to the event, but then RCM fails to detect any subsequent events.
Workaround: Do not run a user-defined executable/script when encountering RCM events.
6. Product compatibilities
OpenSwitch 12.5.1 is compatible with:
Adaptive Server Enterprise versions 12.0, 12.5, 12.5.1, and 12.5.2
Replication Coordination Module 12.5 and 12.5.1
OpenSwitch version 12.5 and 12.5.1
Adaptive Server Enterprise versions 12.0, and 12.5, 12.5.1, and 12.5.2
Replication Server versions 12.0 through 12.6
7. Documentation updates and clarifications
This section discusses documentation updates and clarifications.
7.1 Administration Guide
7.1.1 Pool connection caching, Maintaining properties, options, and database context in cached connections
The connection’s server name, user name, and password are fixed when the cache is established. However, you can change other connection properties dynamically when the connection is opened. For example:
Server-side connections options – ct_options calls set language commands or equivalent ODBC calls. All affect the server’s response to commands sent on the connection.
Database context – different applications from the same user may use different databases. You can avoid problems by explicitly setting the database within your applications when caching is turned on.
Connection properties – connection properties affect client-side connection behavior.
Set any options and properties that your code requires when you obtain a connection.
If your application may share cached connections with other applications, set changed properties and options back to the original values before releasing the connection.
If your application is the only allowed connection to a cached pool, and no other components use the same pool, then you do not need to set options and properties back to the original values; however, you should still set the database context every time you are reconnected, even if you are using cached connections.
8. Technical support
Each Sybase installation that has purchased a support contract has one or more designated people who are authorized to contact Sybase Technical Support. If you have any questions about this installation or if you need assistance during the installation process, ask the designated person to contact Sybase Technical Support or the Sybase subsidiary in your area.
9. Other sources of information
The Getting Started CD contains release bulletins and installation guides in PDF format, and may also contain other documents or updated information not included on the Technical Library CD. It is included with your software. To read or print documents on the Getting Started CD, you need Adobe Acrobat Reader (downloadable at no charge from the Adobe Web site, using a link provided on the CD).
The Technical Library CD contains product manuals and is included with your software. The DynaText reader (included on the Technical Library CD) allows you to access technical information about your product in an easy-to-use format.
Refer to the Technical Library Installation Guide in your documentation package for instructions on installing and starting the Technical Library.
The Technical Library Product Manuals Web site is an HTML version of the Technical Library CD that you can access using a standard Web browser. In addition to product manuals, you will find links to EBFs/Updates, Technical Documents, Case Management, Solved Cases, newsgroups, and the Sybase Developer Network.
To access the Technical Library Product Manuals Web site, go to Product Manuals.
9.1 Sybase certifications on the Web
Technical documentation at the Sybase Web site is updated frequently.
Finding the latest information on product certifications
Point your Web browser to Technical Documents.
Select Products from the navigation bar on the left.
Select a product name from the product list and click Go.
Select the Certification Report filter, specify a time frame, and click Go.
Click a Certification Report title to display the report.
Creating a personalized view of the Sybase Web site (including support pages)
Set up a MySybase profile. MySybase is a free service that allows you to create a personalized view of Sybase Web pages.
Point your Web browser to Technical Documents.
Click MySybase and create a MySybase profile.
9.2 Sybase EBFs and software maintenance
Finding the latest information on EBFs and software maintenance
Point your Web browser to the Sybase Support Page.
Select EBFs/Maintenance. Enter user name and password information, if prompted (for existing Web accounts) or create a new account (a free service).
Select a product.
Specify a time frame and click Go.
Click the Info icon to display the EBF/Maintenance report, or click the product description to download the software.