Client-Library application changes

You must modify any application written with Client-Library calls before it can work with Sybase’s Failover software. The following steps describe the modifications:

1. Set the CS_HAFAILOVER property using the ct_config and ct_con_props Client-Library API calls. Legal values for the property are CS_TRUE and CS_FALSE. The default value is CS_FALSE. You can set this property at either the context or the connection level. The following is an example of setting the property at the context level:

   CS_BOOL bhafailover = CS_TRUE;
   retcode = ct_config(context, CS_SET, CS_HAFAILOVER,
   &bhafailover, CS_UNUSED, NULL);
   

   The following shows the property set at the connection level:

   CS_BOOL bhafailover = CS_FALSE;
   

   retcode = ct_con_props(connection, CS_SET,
   CS_HAFAILOVER, &bhafailover, CS_UNUSED, NULL);
   

2. Handle failover messages. As soon as the companion begins to go down, clients receive an informational message that failover is about to occur. Treat this as an informational message in the client error handlers.

3. Confirm failover configuration. Once you have set the failover property and the sql.ini file has a valid entry for the secondary companion server, the connection becomes a failover connection, and the client reconnects appropriately.

   However, if the failover property is set but the sql.ini file does not have an entry for the hafailover server (or vice-versa), it does not become a failover connection. Instead, it is a normal non-high availability connection with the failover property turned off. You must check the failover property to know whether or not the connection is a failover connection. You can do this by calling ct_con_props with an action of CS_GET.

4. Check return codes. When a successful failover occurs, calls to ct_results and ct_send return CS_RET_HAFAILOVER depending on the type of connection:

   • On a synchronous connection, the API call returns CS_RET_HAFAILOVER directly.

   • On an asynchronous connection, the API returns CS_PENDING and the callback function returns CS_RET_HAFAILOVER.

   Depending on the return code, the application can do the required processing, such as sending the next command to be executed.

5. Restore option values. Any set options that you have configured for this client connection (for example, set role) were lost when the client disconnected from the primary companion. Reset these options in the failed-over connection.

6. Rebuild your applications, linking them with the libraries included with the failover software.

   You cannot connect clients with the failover property (for example, isql -Q) until you issue sp_companion resume. If you do try to reconnect them after issuing sp_companion prepare_failback, the client hangs until you issue sp_companion resume.