Any existing application can connect to the Cluster Edition. However, to use extended high-availability (HA) capabilities, you may need to change application code.
For existing HA applications based on existing Adaptive Server HA functionality, no application code changes are required.
Existing non-HA applications may benefit from some aspects of the HA capabilities of the Cluster Edition with no code changes, or minor ones. However, in these cases, failover is not transparent: the application receives an error message when failover is first detected. The user must resubmit the batch or transaction to initiate failover.
To enable failover for non-HA applications:
For isql, specify the -Q option when connecting to Adaptive Server.
For applications linked with Client-Library, set a corresponding connection property that enables failover.
To make failover transparent to users, the application must actively check for failover error status, and automatically resubmit the batch or transaction.
In all cases, you must update the Client-Library version used by the application to use the cluster-related HA capabilities.
To enable failover in Client-Library applications:
Set the CS_HAFAILOVER property at either the context or the connection level using the ct_config or ct_con_props Client-Library API calls:
ct_config (context, action, CS_HAFAILOVER, buf, buflen, &outlen); ct_con_props(connection, action, CS_HAFAILOVER, buf, buflen, &outlen);
See the Client-Library/C Reference Manual for more information about the CS_HAFAILOVER property.
If you attempt to connect to an instance that is down, behavior is the same as with a nonclustered Adaptive Server: Client-Library tries all the query entries for the instance name in the interfaces file until one of them works, or it has none left to try. Include query lines in the client-side interfaces file for all instances. Applications can connect to the cluster, which is represented by a series of interfaces file query entries. For information about the interfaces file, see the Cluster Edition Installation Guide.
When a successful failover occurs, the Client-Library issues a return value named CS_RET_HAFAILOVER, which is specific to several Client-Library API calls, including:
ret = ct_results(cmd, result_type)
ret = ct_send(cmd)
CS_RET_HAFAILOVER is returned from the API call during a synchronous connection (a routine that requires a server response and blocks until the response is received). In an asynchronous connection (a routine that requires a server response returns CS_PENDING immediately), these APIs issue CS_PENDING, and the callback function returns CS_RET_HAFAILOVER. Depending on the return code, the customer can perform the required processing, set up the context, and send the next command to be executed.
Rebuild your applications using the Open Client SDK with a version that is at least equal to the version of the Open Client SDK shipped with the Cluster Edition.
See Using Sybase Failover in a High Availability System for information about configuring applications for high availability.
