Coordination module routines

Table 3-1 lists the routines used by coordination modules.

**Table 3-1: CM routines**
Routine	Description
cm_callback	Installs or removes a CM event callback handler.
cm_close	Closes an established connection between a CM and OpenSwitch.
cm_connect	Establishes a connection between a CM and OpenSwitch.
cm_connect_enc	Allows the use of encrypted user names and passwords when making a connection.
cm_create	Creates a CM instance.
cm_destroy	Destroys a CM instance.
cm_error	Outputs an error message.
cm_exit	Exits and unallocates CM context.
cm_getcol_data_size	Retrieves the name, datatype, and the maximum length of the specified column present in the specified list.
cm_getcol_metadata	Retrieves column metadata information.
cm_getopt	Parses command line arguments.
cm_get_prop	Retrieves a property of a CM.
cm_get_showquery	Returns the query when executing OpenSwtich process ID.
cm_get_value	Retrieves the mutually-aware configuration value of an OpenSwitch server.
cm_ignore	Ignores OpenSwitch messages matching a given template.
cm_ignore_clear	Sets all fields of a message structure to empty values.
cm_init	Initializes a CM instance.
cm_is_active	Checks if the CM is allowed to perform failback.
cm_optreset	Resets the state of option parsing for cm_getcol_metadata.
cm_ping	Verifies the health of a remote server.
cm_ping_enc	Allows the use of encrypted user names and passwords when pinging.
cm_repeat_ping	Verifies the health of a remote server, repeating if a failure occurs.
cm_repeat_short_ping	Sets a time limit on the duration each ping waits when a failure occurs.
cm_run	Starts the CM.
cm_set_print	Installs an error display function.
cm_set_prop	Sets a property of a CM.
cm_short_ping	Sets a time limit on the number of seconds allowed for the CM to establish its connection.
cm_start	Resumes activity of connections.
cm_stop	Suspends activity of connections.
cm_timer_add	Adds a timed callback.
cm_timer_rem	Removes a timed callback.
cm_unignore	Removes OpenSwitch ignore requests matching template.
cm_version	Returns the pointer to the location of the version string.

cm_callback

Description

Installs or removes a CM event callback handler.

Syntax

CS_RETCODE cm_callback(cm, cb_type, cb_func)
     cm_t *cm;
     CS_INT cb_type;
     CS_VOID *cb_func;

Parameters

cm: A pointer to a CM control structure.

cb_type: The CM event callback handler being installed. Valid values for cb_type are:

Callback type

Description

CM_CB_ASEFAIL

Called by the client connection to report messages or errors when the connection to an Adaptive Server is lost. This callback is recommended for PING_THREAD that may be running inside the coordination module to ping the Adaptive Server. If the callback is not installed, no error or warning messages are reported back to the client if the client loses connection to an Adaptive Server. The callback is only invoked when the severity of the message is greater than or equal to CS_SV_COMM_FAIL.

CM_CB_CTLIB

Called each time an Open Client API error message is generated. If not defined, these messages display to stderr when they are received. Use the cm_set_print function to overwrite this behavior. Equivalent to an Open Client CS_CLIENTMSG_CB command.

CM_CB_LOST

Called by a CM to a remote OpenSwitch server from which the connection is lost. If not defined, these messages are ignored.

CM_CB_MSG

Called each time a message is received from OpenSwitch. If not defined, these messages are displayed to stderr when they are received. Use the cm_set_print function to overwrite this behavior. Equivalent to an Open Client CS_SERVERMSG_CB command.

CM_CB_SERVER

Called by a client connection, requesting the name of a remote server to either log in to or switch to. If not defined, these messages are ignored.

Callback type	Description
CM_CB_ASEFAIL	Called by the client connection to report messages or errors when the connection to an Adaptive Server is lost. This callback is recommended for PING_THREAD that may be running inside the coordination module to ping the Adaptive Server. If the callback is not installed, no error or warning messages are reported back to the client if the client loses connection to an Adaptive Server. The callback is only invoked when the severity of the message is greater than or equal to CS_SV_COMM_FAIL.
CM_CB_CTLIB	Called each time an Open Client API error message is generated. If not defined, these messages display to stderr when they are received. Use the cm_set_print function to overwrite this behavior. Equivalent to an Open Client CS_CLIENTMSG_CB command.
CM_CB_LOST	Called by a CM to a remote OpenSwitch server from which the connection is lost. If not defined, these messages are ignored.
CM_CB_MSG	Called each time a message is received from OpenSwitch. If not defined, these messages are displayed to stderr when they are received. Use the cm_set_print function to overwrite this behavior. Equivalent to an Open Client CS_SERVERMSG_CB command.
CM_CB_SERVER	Called by a client connection, requesting the name of a remote server to either log in to or switch to. If not defined, these messages are ignored.

cb_func: A pointer to a function to be called when a message of cb_type is received. Valid values for cb_func are:

Callback type

Description

Form

CM_CB_CTLIB

Open Client message callback handler

cb_func(CS_CONTEXT *context, CS_CONNECTION *connection, CS_CLIENTMSG *clientmsg, cm_t *cm)

CM_CB_LOST

Connection lost message

cb_func(cm_t *cm)

CM_CB_MSG

Server message callback handler

cb_func(CS_CONTEXT *context, CS_CONNECTION *connection, CS_SERVERMSG *servermsg, cm_t *cm)

CM_CB_SERVER

Server request message callback

cb_func(cm_t *cm, cm_req_srv_t *req)

Callback type	Description	Form
CM_CB_CTLIB	Open Client message callback handler	`cb_func(CS_CONTEXT context, CS_CONNECTION connection, CS_CLIENTMSG clientmsg, cm_t cm)`
CM_CB_LOST	Connection lost message	`cb_func(cm_t *cm)`
CM_CB_MSG	Server message callback handler	`cb_func(CS_CONTEXT context, CS_CONNECTION connection, CS_SERVERMSG servermsg, cm_t cm)`
CM_CB_SERVER	Server request message callback	`cb_func(cm_t cm, cm_req_srv_t req)`

Returns

cm_callback returns these values:

Return value	Meaning
`CS_SUCCEED`	The routine completed successfully.
`CS_FAIL`	The routine failed.

Examples

Example 1

static CS_RETCODE cm_lost_handler( cm )
   cm_t *cm;
{
   fprintf( stderr, "Connection lost!" ); 
   return CS_SUCCEED;
}

main()
{
   CS_RETCODE retcode;
   ...

   retcode = cm_callback( cm, CM_LOST_CB, 
      (CS_VOID*)cm_lost_handler );

   if (retcode != CS_SUCCEED)
   { 
      fprintf( stderr, "cm_callback failed!" );
      exit(1);
   }
   ...
}

Usage

When you create a CM with cm_create, the CM has no callback handlers installed. The default callback actions are performed as described in the Parameters section.

Unlike Open Client, you cannot establish callbacks at the CM context level, so callbacks are not inherited between modules or the context, and must be explicitly set for each module. For more information, see “cm_init”.
To uninstall an existing callback, program an application to call cm_callback with cb_func as NULL. You can install a new callback any time the application is running. New callbacks automatically replace existing callbacks.
Program an application to use the CM_P_USERDATA property to transfer information to a callback routine and the program code that triggered it. The CM_P_USERDATA property allows an application to save user data in internal space and retrieve it later.
If the CM process exits for any reason, such as the OpenSwitch server failing, program the callback to return CS_FAIL to its caller. This return status is necessary for the CM to perform the necessary cleanups before the process exits.

cm_close

Description

Closes an established connection between a CM and OpenSwitch.

Syntax

CS_RETCODE cm_close(cm)
     cm_t *cm;

Parameters

cm: A pointer to a CM control structure.

Returns

cm_close returns these values:

Return value	Meaning
`CS_SUCCEED`	The routine completed successfully.
`CS_FAIL`	The routine failed.

Usage

Closes an existing connection between a CM and a remote OpenSwitch using the cm_connect function.
It is not an error to close a connection that was never opened; that is to say, if cm_connect was never called or has already been closed due to another event, for example, OpenSwitch unexpectedly failing.
Closing the connection associated with a CM does not destroy the CM instance. Use cm_destroy to destroy the CM instance.

cm_connect

Description

Establishes a connection between a CM and OpenSwitch.

Syntax

CS_RETCODE cm_connect(cm, server, username, password)
     cm_t *cm;
     CS_CHAR *server;
     CS_CHAR *username;
     CS_CHAR *password;

Parameters

cm: A pointer to a CM control structure.

server: A pointer to the name of the OpenSwitch server to which to connect. server is the name of the server’s entry in the sql.ini file on Windows and in the interfaces file on UNIX, or in the directory services source. A NULL server value may be supplied only if cm_connect has successfully attached to a remote server in the past. For more information, see the Usage section for this routine.

username: The name to be used to connect to OpenSwitch. This should match the COORD_USER configuration value in the OpenSwitch configuration file. For more information, see the OpenSwitch Administration Guide. A NULL username value may be supplied only if cm_connect has successfully attached to a remote server in the past.

password: The OpenSwitch user password to be used to connect to OpenSwitch. This value should match the COORD_PASSWORD configuration value in the OpenSwitch configuration file. For more information, see the OpenSwitch Administration Guide. A NULL password value may be supplied only if cm_connect has successfully attached to a remote server in the past.

Returns

cm_connect returns these values:

Return value	Meaning
`CS_SUCCEED`	The routine completed successfully.
`CS_FAIL`	The routine failed.

Examples

Example 1

cm_t *cm;
/*
* Create a new coordination module.
*/
cm = cm_create( ... )

...
if (cm_connect( cm, "SYB_SWITCH1", "coord_user",
   "coord_password" ) != CS_SUCCEED)
{
   fprintf( stderr, "cm_connect failed!\n" );
   return CS_FAIL;
}

Usage

The cm_connect function is used to connect an instance of a CM to a remote OpenSwitch server. The username and password parameters are used by the CM to identify itself to OpenSwitch. Supplying a username and password that do not match the COORD_USER and COORD_PASSWORD configuration parameters in OpenSwitch causes cm_connect to return CS_FAIL.
Internally, cm_connect establishes an Open Client connection to the OpenSwitch server, and waits for an acknowledgment by OpenSwitch that the appropriate username and password have been supplied. After connecting, cm_connect registers itself to be aware of several notification procedures, in particular, np_req_srv. For details about np_req_srv, see Chapter 8, “Notifications Procedures” in the OpenSwitch Administration Guide.
Issuing a call to cm_connect while a connection is already established closes the existing connection (internally, using cm_close) before the new connection is attempted.
If cm has been successfully connected to a server in the past using cm_connect, then passing a NULL value for any one of server, username, and password causes the value passed during the previous call to cm_connect to be used.

cm_connect_enc

Description

Similar to cm_connect, except it allows for the use of encrypted user names and passwords.

Syntax

CS_RETCODE CS_PUBLIC cm_connect(cm, server, username,
          password, encrypted)
     cm_t *cm;
     CS_CHAR *server;
     CS_CHAR *username;
     CS_CHAR *password;
     CS_BOOL encrypted;

Parameters

cm: Pointer to a CM control structure.

server: A pointer to the name of the OpenSwitch server to which to connect. server is the name of the server’s entry in the $SYBASE/interfaces file on UNIX, the %SYBASE%\ini\sql.ini file on Windows, or directory services source. A NULL server value may be supplied only if cm_connect_enc has successfully attached to a remote server in the past.

username: The name to be used to connect to OpenSwitch. This should match the COORD_USER configuration value in the OpenSwitch configuration file. For more information, see the OpenSwitch Administration Guide. A NULL username value may be supplied only if cm_connect_enc has successfully attached to a remote server in the past.

password: The OpenSwitch user password to be used to connect to OpenSwitch. This value should match the COORD_PASSWORD configuration value in the OpenSwitch configuration file. For more information, see the OpenSwitch Administration Guide. A NULL password value may be supplied only if cm_connect_enc has successfully attached to a remote server in the past.

encrypted: A Boolean value that defines whether the user name and password are encrypted or not. If encrypted is set to CS_TRUE, all user names and passwords passed to the API must be encrypted. If set to CS_FALSE, none of the user names and passwords should be encrypted.

Returns

cm_connect_enc returns these values:

Return value	Meaning
`CS_SUCCEED`	The routine completed successfully.
`CS_FAIL`	The routine failed.

Examples

Example 1

cm_t *cm;
/*
* Create a new coordination module.*/
cm = cm_create( ... )

...
if (cm_connect_enc( cm, "SYB_SWITCH1", "0x010a60c07b7f86c1d30fac6162ce70400daecdd6749335832fd5c9c613e95ef6","0x010ed474cfcb327562ac19d5c6cad2f04733e321d8983d474744ec3b80888bc0", 1) != CS_SUCCEED)
{
   fprintf( stderr, "cm_connect_enc failed!\n" );
   return CS_FAIL;
}

Usage

Similar to cm_connect with the additional ability to pass in encrypted username (COORD_USER) and password (COORD_PASSWORD).
If encryption is set to true, both username and password must be in encrypted form, and must also be encrypted in the OpenSwitch server.

cm_create

Description

Creates a CM instance.

Syntax

CS_RETCODE cm_create(ctx, cm)
     cm_ctx_t *ctx;
     cm_t *cm;

Parameters

ctx: Pointer to a CM context structure. This context must be allocated and initialized by cm_init prior to calling cm_create.

cm: The address of a pointer variable. cm_create sets cm to the address of a newly allocated cm_t structure.

Returns

cm_create returns these values:

Return value	Meaning
`CS_SUCCEED`	The routine completed successfully. cm contains a pointer to a new cm_t structure.
`CS_FAIL`	The routine failed. The contents of cm are undefined.

Examples

Example 1

cm_t   *cm;

/*
* Create a coordination module context.
*/
...

if (cm_create( ctx, &cm ) != CS_SUCCEED)
{
   fprintf( stderr, "cm_create() failed!\n" );
   return CS_FAIL;
}

Usage

cm_create allocates a new CM to manage a single OpenSwitch server. This CM does nothing until callback handlers are installed using cm_callback and the CM is connected to an OpenSwitch using cm_connect.
The ctx acts as a container for all CMs created with cm_create. This structure may be used to represent a self-contained group of CMs.

cm_destroy

Description

Destroys a CM instance.

Syntax

CS_RETCODE cm_destroy(cm)
     cm_t *cm;

Parameters

cm: A pointer to a CM control structure to be destroyed.

Returns

cm_destroy returns these values:

Return value	Meaning
`CS_SUCCEED`	The routine completed successfully.
`CS_FAIL`	The routine failed.

Examples

Example 1

if (cm_destroy( cm ) != CS_SUCCEED)
{
   fprintf( stderr, "cm_destroy() failed!\n" );
   return CS_FAIL;
}

Usage

cm_destroy frees all resources associated with an instance of a CM cm_t structure. All memory used by the structure is reclaimed, and any active connection to an OpenSwitch server is closed.
After a cm_t structure has been destroyed, it cannot be reused. A new structure must be allocated with cm_create.

cm_error

Description

Prints an error message to stderr.

Syntax

CS_VOID cm_error(fmt, ...)
     CS_CHAR *fmt;

Parameters

fmt: An output format string. This string may contain all of the output format specifications accepted by fprintf(3c).

Returns

None.

Examples

Example 1

cm_error( "Could not open file '%s': %s\n",
   (char*)file_name,
   strerror( errno ) );

Usage

The cm_error function is identical to the standard C printf function. It formats the output according to the fmt string and prints it, by default, to stderr.
To print an error message to a file, use the cm_set_print function instead.

cm_exit

Description

Exits and unallocates CM context.

Syntax

CS_RETCODE cm_exit(ctx)
     cm_ctx_t *ctx;

Parameters

ctx: A pointer to the coordination context structure to be destroyed.

Returns

cm_exit returns these values:

Return value	Meaning
`CS_SUCCEED`	The routine completed successfully.
`CS_FAIL`	The routine failed.

Examples

Example 1

if (cm_exit( ctx ) != CS_SUCCEED)
{
   cm_error( "Unable to destroy context\n" );
   return CS_FAIL;
}

Usage

A coordination context is used to encapsulate multiple OpenSwitch connections.
ctx must point to a valid coordination context structure allocated using cm_init.
Attempting to call cm_exit while any CMs exist within the context returns an error. cm_destroy must be used to destroy existing CMs prior to calling cm_exit.

cm_getcol_data_size

Description

Retrieves the name, the datatype, and the maximum length of the specified column present in the specified list.

Syntax

CS_RETCODE cm_getcol_data_size(col_list, col_name, col_type, col_size)
     cm_col_mtdata *col_list;
     CS_CHAR *col_name;
     CS_CHAR *col_type;
     CS_INT *col_size;

Parameters

col_list: A linked list containing the name, datatype, and maximum length of the entries in the metadata.

col_name: The name of the column that matches the name field of the linked list.

col_type: Provides the data type of the column. It stores CHAR for character datatype or INTEGER for numeric datatype.

col_size: Provides the size of the column.

Returns

cm_getcol_data_size returns these values:

Return value	Meaning
`CS_SUCCEED`	The routine completed successfully.
`CS_FAIL`	The routine failed.

Examples

Example 1

/*

* Get the information related to the cache column
   related to the pool structure of the OpenSwitch.

*/

cm_getcol_data_size(list_col_metad, "cache", type,
  &size);

Description

Retrieves column metadata information. The information includes name, datatype, and the maximum length of the column.

Syntax

CS_INT cm_getcol_metadata(cm, type, col_list)
     cm_t  *cm;
     CS_INT type;
     cm_col_mtdata **col_list;

Parameters

cm: A pointer to a CM control structure.

type: Indicates the type of information requested. Valid values for type are:

Type

Description

POOL_T_TYPE

To display pool related information.

SERVER_T_TYPE

To display server related information.

RMON_T_TYPE

To display OpenSwitch resource monitoring thread related information.

DBG_T_TYPE

To display OpenSwitch debugging flags related information.

POOLSERVER_T_TYPE

To obtain the servers present in a particular pool.

VERSION_T_TYPE

To display OpenSwitch version number.

WHO_T_TYPE

To display detailed information about user connections to OpenSwitch.

Type	Description
POOL_T_TYPE	To display pool related information.
SERVER_T_TYPE	To display server related information.
RMON_T_TYPE	To display OpenSwitch resource monitoring thread related information.
DBG_T_TYPE	To display OpenSwitch debugging flags related information.
POOLSERVER_T_TYPE	To obtain the servers present in a particular pool.
VERSION_T_TYPE	To display OpenSwitch version number.
WHO_T_TYPE	To display detailed information about user connections to OpenSwitch.

col_list: A pointer (to a pointer) to the list of columns that contain the column’s metadata. The cm_col_metadata structure is defined as:

typedef struct cm_col_metadata {

    CS_CHAR    name[CS_MAX_NAME]; /* Name of the column */

    CS_CHAR    datatype[CS_MAX_TYPE]; /* Datatype */

    CS_INT     maxlength; /* Maximum length of the column*/

    struct     cm_col_metadata *next; /* Next pointer*/

} cm_col_mtdata;

Returns

cm_getcol_metdata returns these values:

Return value	Meaning
`CS_SUCCEED`	The routine completed successfully.
`CS_FAIL`	The routine failed.

Examples

Example 1

/*
 * Get the column metadata information related to the pool structure of the OpenSwitch.
*/

fprintf( stderr, "Information related to the columns present in the pool structure %s: \n", (char *)data);

num_col = cm_getcol_metadata(cm, POOL_T_TYPE, &list_col_metad);

fprintf( stderr, "The number of columns present in the pool structure of the OpenSwitch is %d\n", num_col);

cm_getopt

Description

Parses command line arguments.

Syntax

CS_INT cm_getopt(argc, argv, optstring)
     CS_INT argc;
     CS_CHAR *argv[ ];
     CS_CHAR *optstring;

Parameters

argc: The number of arguments held in the command line vector argv.

argv: Command line argument vector containing arguments.

optstring: Contains the option letters recognized by the command using cm_getopt. If a letter is followed by a colon, the option is expected to have an argument. If the letter is followed by a semicolon, an option is allowed but not required. If there is no character after the letter, an option is not allowed.

Returns

cm_getopt returns these values:

Return value	Meaning
`'?'`	An invalid option was supplied.
`EOF`	The last option was processed.
`char`	The command line option parsed.

Examples

Example 1

main( argc, argv ) 	int   argc;
   char *argv[];
{
   extern CS_INT cm_optind;
   extern CS_INT cm_optarg;

   CS_INT   c;
   CS_INT   aflg = 0;
   CS_INT   bflg = 0;
   CS_INT   errflg = 0;
   CS_CHAR *ofile = NULL;

   while ((c = cm_getopt(argc, argv, 
      "abo:")) != EOF)
   {
      switch(c)
      {
         case 'a':
            if (bflg)
               errflg++;
            else
               aflg++;
            break;
         case 'b':
            if (aflg)
               errflg++;
            else
               bflg++;
            break;
         case 'o':
            ofile = cm_optarg;
            printf("ofile = %s\n", ofile);
            break;
         case '?':
            errflg++;
      }

      if (errflg)
      {
         fprintf(stderr,
            "usage: cmd [-a|-b] [-o "
            "<filename>] files...\n" );
         exit (2);
      }

      for (; cm_optind < argc; cm_optind++)
      {
         printf("%s\n", argv[cm_optind]);
         return 0;
      }
}

The code fragment shows how to process the arguments for a command that can take the mutually exclusive options a and b, and the option o, which requires an argument:

Usage

cm_getopt returns the next option letter in argv that matches a letter in optstring.
If an option accepts an argument (the option letter is followed by a colon or a semicolon in optstring), the contents of the argument are found in the global variable cm_optarg. If an argument is optional and is not supplied, cm_optarg is NULL.
cm_getopt places in the cm_optind the argv index of the next argument to be processed. cm_optind is external and is initialized to 1 before the first call of cm_getopt. When all options have been processed, up to the first nonoptional argument, cm_getopt returns EOF.
The cm_optreset function may be used to reset the state of cm_getopt.

cm_get_prop

Description

Retrieves a property of a CM.

Syntax

CS_RETCODE cm_get_prop(cm, prop, value)
     cm_t *cm;
     CS_INT prop;
     CS_VOID *value;

Parameters

cm: A pointer to a CM control structure.

prop: The name of the property to be retrieved. Valid values for prop are:

Prop

Description

CM_P_ASYNC

Checks to see if asynchronous notification is set in the connection between the CM and OpenSwitch.

CM_P_USERDATA

Retrieves a pointer from the CM control structure previously attached using cm_set_prop(CM_P_USERDATA). This property may be used to pass data between CM callbacks.

CM_P_NAME

Retrieves the name of the OpenSwitch server to which the CM is connected. If the module has never been connected, an empty string is returned.

Prop	Description
CM_P_ASYNC	Checks to see if asynchronous notification is set in the connection between the CM and OpenSwitch.
CM_P_USERDATA	Retrieves a pointer from the CM control structure previously attached using cm_set_prop(CM_P_USERDATA). This property may be used to pass data between CM callbacks.
CM_P_NAME	Retrieves the name of the OpenSwitch server to which the CM is connected. If the module has never been connected, an empty string is returned.

value: A pointer to a memory location in which the CM property is retrieved. Valid values for value are:

If prop is:

value will be:

CM_P_ASYNC

A pointer to a CS_BOOL value.

CM_P_USERDATA

A pointer to a void pointer (CS_VOID**).

CM_P_NAME

A pointer to an array of CS_CHAR of length 31 or greater.

If *prop* is:	*value* will be:
CM_P_ASYNC	A pointer to a CS_BOOL value.
CM_P_USERDATA	A pointer to a void pointer (CS_VOID**).
CM_P_NAME	A pointer to an array of CS_CHAR of length 31 or greater.

Returns

cm_get_prop returns these values:

Return value	Meaning
`CS_SUCCEED`	The routine completed successfully.
`CS_FAIL`	The routine failed.

Examples

Example 1

CS_CHAR  cm_name[31];

if (cm_get_prop( cm, CM_P_NAME, cm_name )
   != CS_SUCCEED)
{
   cm_error("Unable to retrieve CM_P_NAME prop \n");
   return CS_FAIL;
}
else
{
   fprintf( stdout,
   "module name: %s\n", (char*)cm_name );
}

Usage

Although the contents of all CM data structures are transparent (versus opaque), fields within the data structures should never be accessed directly. Instead, the cm_get_prop or cm_set_prop functions should be used. This allows the internal definitions to be changed in future releases without affecting existing code.

cm_get_showquery

Description

Returns the query when the OpenSwitch process ID is executed.

Syntax

CS_RETCODE cm_get_showquery (cm, spid, query)
     cm_t *cm;
     CS_INT spid;
     CS_CHAR *query;

Parameters

cm: A pointer to a CM control structure.

spid: Valid OpenSwitch process ID.

query: A buffer to hold the returned query string.

Returns

cm_get_showquery returns these values:

Return value	Meaning
`CS_SUCCEED`	The routine completed successfully.
`CS_FAIL`	The routine failed.

Examples

Example 1

If(cm_get_showquery( cm, 7, query) !=CS_SUCCEED)
{
     cm_error(“cm_get_showquery()failed\n” )
}

Usage

The returned query is stored in the assigned buffer.

cm_get_value

Description

Because mutually-aware OpenSwitch servers do not currently support removing or adding Adaptive Servers to pools, before adding or removing a server, use this API to retrieve the mutually-aware configuration value of an OpenSwitch server. See the OpenSwitch Administration Guide for details about using mutually-aware OpenSwitch servers.

If you select Use Mutual Aware Support? in the configuration GUI (MUTUAL_AWARE=1 in the OpenSwitch configuration file), servers can neither be added or removed from a pool.

Syntax

CS_RETCODE CS_PUBLIC cm_get_value(cm, parm_name,
           parm_value) 
     cm_t *cm; 
     CS_CHAR *parm_name; 
     CS_CHAR *parm_value;

Parameters

cm: A pointer to a CM control structure.

parm_name: Name of a configuration variable as listed in the configuration file.

parm_value: Returns the value of the configuration parameter specified for parm_value.

Examples

Example 1

If(cm_get_value( cm, "DEBUG", parm_val ) !=CS_SUCCEED)

{

     cm_error(“Unable to retrieve the value of the 'DEBUG' configuration

               parameter\n” );

     return CS_FAIL;

}

Usage

Sample cm1.c file

The cm1.c sample has been modified such that, when a primary server is detected to be down, cm1 not only marks it as down, but also removes it from the pool. When the primary server comes back up, cm1 marks it as up and adds it to the end of the pool. This way, new clients can continue to be redirected to the secondary server until the administrator deems it appropriate to switch back all the connections by manually executing the failback sequence as described below:

rp_server_status sec_ASE, LOCKED – prevents more new clients from going to the secondary Adaptive Server

rp_stop NULL, sec_ASE, NULL – stops all connections on the secondary Adaptive Server

rp_server_status sec_ASE, DOWN – makes the secondary Adaptive Server unavailable to any new connections in the future

rp_server_status pri_ASE, UP – sets the primary Adaptive Server up for accepting new connections

rp_switch NULL, sec_ASE, NULL, pri_ASE, 0, 1 – switches all the connections back from the secondary to the primary Adaptive Servers

rp_start NULL, sec_ASE, NULL – restarts all the stopped connections

These changes does not apply to mutually-aware setups. If MUTUAL_AWARE is set to 1, cm1 only marks the primary server as down when it detects a failure, but does not remove the server from the pool. When the server comes back up in a mutually aware setup, cm1 marks the server as up, and the primary server begins accepting connections right away.

If the administrator does not want to use this configuration, the administrator can modify the cm_time_ping() function in cm1.c to comment out the call to cm_server_status. By doing this, the cm1 program does not failback the connections automatically, thus allowing the administrator to control when the failback occurs when they execute the failback sequence mentioned above.

cm_ignore

Description

Ignores OpenSwitch messages matching a given template to prevent it from invoking the corresponding callback handler as installed by cm_callback.

Syntax

CS_RETCODE cm_ignore(cm, msg_type, msg)      cm_t *cm;      CS_INT msg_type;      CS_VOID *msg;

Parameters

cm

A pointer to a CM control structure.

msg_type

The type of message being passed through the msg argument. The only valid value for msg_type is:

msg_type

Description

CM_CB_SERVER

A server-name request message

msg

A pointer to a cm_req_srv_st structure, which is defined as:

typedef struct cm_req_srv_st {

    CS_INT     spid; /* OpenSwitch spid number */

    CS_CHAR    username[31]; /* Name of the user */

    CS_CHAR    appname[31]; /* Application they are running */

    CS_CHAR    hostname[31]; /* Host client is running on */

    CS_CHAR    database[31]; /* Host client is running on */

    CS_CHAR    pool[31]; /* Pool the user is in */

    CS_INT     rsn_code; /* Reason for request (see cm_rsn.h) */

    CS_CHAR    rsn_text[256]; /* Description of reason */

    CS_CHAR    cur_server[31]; /* Current server they are using */

    CS_CHAR    nxt_server[31]; /* Server they want to go too */

} cm_req_srv_t;

Returns

cm_ignore returns these values:

Return value

Meaning

CS_SUCCEED

The routine completed successfully.

CS_FAIL

The routine failed.

Examples

Example 1

cm_req_srv_t m;

cm_ignore_clear( cm, CM_CB_SERVER, (CS_VOID*)&m );\

/*Ignore all incoming messages from Adaptive Server

  "SYB_ASE1".

*/

strcpy( (char*)m.cur_server, "SYB_ASE1" );

if (cm_ignore( cm, CM_CB_SERVER, (CS_VOID*)&m )

   != CS_SUCCEED)

{

   cm_error( "Can't ignore msgs from SYB_ASE1\n" );

   return CS_FAIL;

}

Usage

When an Adaptive Server fails, all the connected clients as well as the clients attempting to connect to it receive the same error message. To prevent these similar errors from triggering the failover process multiple times, you can code the CM so it acknowledges only the first lost connection message received and ignores subsequent similar messages on the same server. When the failed server has recovered fully, the CM can unset the previous ignore message so that no messages are ignored.

The cm_ignore_clear, cm_ignore, and cm_unignore functions cause a CM to automatically discard messages received from OpenSwitch according to a message template.

The cm_ignore_clear function establishes an empty message template. After it has been used to clear the msg structure, the data structure fields that are to be ignored may be set. By passing this populated data structure template to cm_ignore, all future messages matching the template are automatically discarded by the CM until cm_unignore is called with an identical template.

Messages are ignored only when all fields of the incoming message exactly match all populated fields of the template message. There is currently no facility for providing “or” logic within a single template. This may be achieved only by passing multiple templates to cm_ignore, or by implementing a separate mechanism.

See also

cm_ignore_clear, cm_unignore

cm_ignore_clear

Description

Sets all fields of a message structure to empty values.

Syntax

CS_RETCODE cm_ignore_clear(cm, msg_type, msg)      cm_t *cm;      CS_INT msg_type;      CS_VOID *msg;

Parameters

cm

A pointer to a CM control structure.

msg_type

the type of message being passed through the msg argument. Valid values for msg_type are:

msg_type

Description

CM_CB_SERVER

A server-name request message

msg

a pointer to a cm_req_srv_st structure, which is defined as:

typedef struct cm_req_srv_st {

    CS_INT     spid; /* OpenSwitch spid number */

    CS_CHAR    username[31]; /* Name of the user */

    CS_CHAR    appname[31]; /* Application they are running */

    CS_CHAR    hostname[31]; /* Host client is running on */

    CS_CHAR    database[31]; /* Host client is running on */

    CS_CHAR    pool[31]; /* Pool the user is in */

    CS_INT     rsn_code; /* Reason for request (see cm_rsn.h) */

    CS_CHAR    rsn_text[256]; /* Description of reason */

    CS_CHAR    cur_server[31]; /* Current server they are using */

    CS_CHAR    nxt_server[31]; /* Server they want to go too */

} cm_req_srv_t;

Returns

cm_ignore_clear returns these values:

Return value

Meaning

CS_SUCCEED

The routine completed successfully.

CS_FAIL

The routine failed.

Examples

Example 1

cm_req_srv_t m;

cm_ignore_clear( cm, CM_CB_SERVER, (CS_VOID*)&m );

/*

* Ignore all messages coming generated from SQL

* Server "SYB_ASE1".

*/

strcpy( (char*)m.cur_server, "SYB_ASE1" );

if (cm_ignore( cm, CM_CB_SERVER, (CS_VOID*)&m )

   != CS_SUCCEED)

{

   cm_error( "Can't ignore msgs from SYB_ASE1\n" );

   return CS_FAIL;

}

Usage

When an Adaptive Server fails, all the connected clients as well as the clients attempting to connect to it receive the same error message. To prevent these similar errors from triggering the failover process multiple times, you can code the CM so it acknowledges only the first lost connection message received and ignores subsequent similar messages on the same server. When the failed server has recovered fully, the CM can then unset the previous ignore message so that no messages are ignored.

The cm_ignore_clear function establishes an empty message template. After you use it to clear the msg structure, set the data-structure fields to ignore. By passing this populated data-structure template to cm_ignore, all future messages matching the template are automatically discarded by the CM until cm_unignore is called with an identical template.

Messages are ignored only when all fields of the incoming message match exactly all populated fields of the template message. There is currently no facility for providing “or” logic within a single template. This may be achieved only by passing multiple templates to cm_ignore, or by implementing a separate mechanism.

See also

cm_ignore, cm_unignore

cm_init

Description

Initializes a CM context.

Syntax

CS_RETCODE cm_init(cm_ctx )      cm_ctx_t *cm_ctx;

Parameters

cm_ctx

The address of a cm_ctx_t pointer. cm_init sets *cm_ctx to the address of a newly allocated cm_ctx_t structure.

Returns

cm_init returns these values:

Return value

Meaning

CS_SUCCEED

The routine completed successfully.

CS_FAIL

The routine failed.

Examples

Example 1

cm_ctx_t *ctx;

if (cm_init( &ctx ) != CS_SUCCEED)

{

   cm_error( "Unable to allocate context\n" );

   return CS_FAIL;

}

Usage

A CM context structure is used to manage zero or more CMs. It provides a handle for manipulating multiple CMs as a single entity. For example, you can use a CM program to manage multiple OpenSwitch servers at the same time. To do this, you must create multiple CMs, each one connecting to a different OpenSwitch. Multiple CMs are particularly useful in a redundancy setup to eliminate the single point of failure that a single OpenSwitch might pose.

After a CM context structure has been allocated, individual CM managers may be allocated using cm_create.

A CM context structure may be destroyed using cm_exit.

Usually, only one CM context exists per executable.

Common reasons for failure include:

Memory allocation failure

A problem with the Open Client installation

See also

cm_create, cm_exit

cm_is_active

Description

Checks if the CM is allowed to perform failback.

Syntax

CS_RETCODE CS_PUBLIC cm_is_active(cm, is_active)      cm_t *cm;      CS_BOOL *is_active;

Parameters

cm

A pointer to a CM control structure.

is_active

Address of the Boolean variable.

Returns

cm_is_active returns these values:

Return value

Meaning

CS_SUCCEED

The routine completed successfully.

CS_FAIL

The routine failed.

Examples

Example 1

if cm_is_active(cm, &is_active) != CS_SUCCEED)

{

   cm_error("cm_is_active failed.\n" );

   return CS_FAIL;

}

if ( is_active == CS_TRUE) {    /* CM is connected to Primary OpenSwitch companion */)    cm_error("\nOpenSwitch is Primary Companion. \n"); else {    /* CM is connected to Secondary OpenSwitch companion */)    cm_error("\nOpenSwitch is Secondary Companion. \n"); }

Usage

In a mutually-aware support, cm_is_active is used to check if the CM is allowed to perform failback.

is_active is the address of the Boolean variable, which should be non NULL for normal operation.

Boolean variable is set to CS_TRUE if the CM is allowed to perform failback. Otherwise, Boolean variable is set to CS_FALSE.

In a non-MAS, Boolean variable is always set to CS_TRUE.

This routine can be used in the failback timer.

cm_optreset

Description

Resets the state of option parsing for cm_getopt.

Syntax

CS_RETCODE cm_optreset()

Parameters

None.

Returns

cm_optreset returns these values:

Return value

Meaning

CS_SUCCEED

The routine completed successfully.

CS_FAIL

The routine failed.

Examples

Example 1

if (cm_optreset()!=CS_SUCCEED)

{

   cm_error( "Cannot reset options\n" );

   return CS_FAIL;

}

Usage

The cm_getopt function is a utility function similar to the standard UNIX libc function call, getopt(3c). Each subsequent call to cm_getopt parses the next command line option.

cm_getopt and cm_optreset provide a more portable interface than getopt(3c) and are recommended instead.

Calling cm_optreset resets the state of cm_getopt to start at the beginning of the supplied command line options.

See also

cm_getopt

cm_ping

Description

Verifies the health of a remote server by checking if it responds to a user connection and a simple request.

Syntax

CS_RETCODE cm_ping(cm, server, username, password, database)      cm_t *cm;      CS_CHAR *server;      CS_CHAR *username;      CS_CHAR *password;      CS_CHAR *database;

Parameters

cm

Pointer to a CM control structure.

server

The name of the remote server to ping, as listed in the interfaces file on UNIX and in the sql.ini file on Windows.

username

The user name used to connect to the remote server to perform the argv. This user name must exist on the remote server and have access to the database specified by the database argument.

password

The user password used to connect to the remote server.

database

If not NULL, the name of the database to ping on the remote server.

Returns

cm_ping returns these values:

Return value

Meaning

CS_SUCCEED

The routine completed successfully. The Adaptive Server was successfully pinged and appears to be available.

CS_FAIL

The routine failed or the Adaptive Server was not available.

Examples

Example 1

if (cm_ping( cm, "SYB_ASE1", "bob", "bobs_password",

   "pubs2" ) != CS_SUCCEED)

{

   cm_error( "Server SYB_ASE1 is dead.\n" );

   return CS_FAIL;

}

Usage

cm_ping is a utility function used to ping a remote server.

A server is considered to be alive if:

A connection is successfully established to server using username and password, and

If the database is not NULL, a use database command succeeds, or

If the database is NULL, a select @@spid statement succeeds.

When the network between the CM host and the remote server goes down, cm_ping can take as long as 60 seconds to return a failure. To be notified of the failure sooner than that, use cm_short_ping instead and specify a time-out value you want for your systems.

To ping the server more than once before taking the necessary failover actions, use cm_repeat_ping or cm_repeat_short_ping. These functions ping the remote server up to the specified number of times before returning a failure.

Use cm_ping only on Sybase products that support use database and select @@spid.

See also

cm_repeat_ping, cm_repeat_short_ping, cm_short_ping

cm_ping_enc

Description

Similar to cm_ping, except it allows for the 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 neither maxretry or timeout are greater than zero.

Syntax

CS_RETCODE CS_PUBLIC cm_ping_enc(cm, server, username,            password, database, timeout, maxretry, waitsec, encrypted)      cm_t *cm;      CS_CHAR *server;      CS_CHAR *username;      CS_CHAR *password;      CS_CHAR *database;      CS_INT timeout;      CS_INT maxretry;      CS_INT waitsec;      CS_BOOL encrypted;

Parameters

cm

A pointer to a CM control structure.

server

The name of the remote server to ping, as listed in the interfaces (UNIX) and sql.ini (Windows) files.

username

The user name to connect to the remote server to perform the ping.

password

The user password to use to connect to the remote server.

database

If not NULL, the name of the database to ping on the remote server.

timeout

The timeout value in seconds for the CM to connect to the servername specified. If the connection is not established within the amount of time specified, this function returns CS_FAIL. Set this value slightly longer than the usual amount of time it takes for the CM host to ping the server host under normal operating conditions.

maxretry

If failure occurs, the number of times the CM retries to check the server health. If the CM succeeds immediately, cm_ping_enc returns immediately without retrying.

waitsec

The duration, in seconds, that the CM should wait between each retry. If the CM succeeds immediately, cm_ping_enc returns without waiting.

encrypted

A Boolean value that defines whether or not the username and password are encrypted. If encrypted is set to CS_TRUE, all user names and passwords passed to cm_ping_enc must be encrypted. If set to CS_FALSE, none of the user names and passwords should be encrypted.

Returns

cm_ping_enc returns these values:

Return value

Meaning

CS_SUCCEED

The routine completed successfully. The Adaptive Server was successfully pinged and appears to be available.

CS_FAIL

The routine failed or the Adaptive Server was not available.

Examples

Example 1

if (cm_ping_enc( cm, "SYB_ASE1"   "0x010373d3657426eafbc917cf04a17456e5347612cd91e756c  8b6afddb0325574",   "0x010d43e3555092fafc20955d5647496877186a433f006d7e0  7df70ae39a7cf3b", pubs2", 30, 3, 20,1 ) != CS_SUCCEED)

{    cm_error( "Server SYB_ASE1 is dead.\n" );    return CS_FAIL; }

Usage

Same as cm_repeat_short_ping, with the additional ability to support encrypted user name and password.

See the “Usage” section for cm_repeat_short_ping.

See also

cm_repeat_ping, cm_short_ping, cm_repeat_short_ping

cm_repeat_ping

Description

Verifies the health of a remote server, repeating up to the specified number of times if a failure is encountered.

Syntax

CS_RETCODE cm_repeat_ping(cm, server, username, password, database, maxretry, waitsec)      cm_t *cm;      CS_CHAR *server;      CS_CHAR *username;      CS_CHAR *password;      CS_CHAR *database;      CS_INT maxretry;      CS_INT waitsec;

Parameters

cm

Pointer to a CM control structure.

server

The name of the remote server to ping, as listed in the UNIX interfaces file or the Windows sql.ini file.

username

The user name used to connect to the remote server to perform the ping. This user name must exist on the remote server and have access to the database specified by the database argument.

password

The user password to be used to connect to the remote server.

database

If not NULL, the name of the database to ping on the remote server.

maxretry

If a failure is encountered, the number of times this function retries before returning. If the ping succeeds immediately, cm_repeat_ping returns without retrying.

waitsec

The duration in seconds this function waits between each retry. If the ping succeeds immediately, cm_repeat_ping returns without waiting.

Returns

cm_repeat_ping returns these values:

Return value

Meaning

CS_SUCCEED

The routine completed successfully. The Adaptive Server was successfully pinged and appears to be available.

CS_FAIL

The routine failed or the Adaptive Server was not available.

Examples

Example 1

if (cm_repeat_ping( cm, "SYB_ASE1", "bob", "bobs_password", "pubs2", 3, 5 )

   != CS_SUCCEED)

{

    cm_error( "Failed to connect to SYB_ASE1 after 3 retries.\n" );

    return CS_FAIL;

}

Usage

cm_repeat_ping is a utility function that can ping a remote server. If the ping succeeds, cm_repeat_ping returns immediately. If the ping fails, cm_repeat_ping sleeps for a specified duration (waitsec), then tries to ping the server again. This process repeats until the maximum number of retries (maxretry) completes.

A server is considered to be alive if:

A connection is successfully established to server using username and password, and

If the database is not NULL, a use database command succeeds, or

If the database is NULL, a select @@spid statement succeeds.

You can use cm_repeat_ping only on Sybase products that support use database and select @@spid.

See also

cm_ping, cm_short_ping, cm_repeat_short_ping

cm_repeat_short_ping

Description

Similar to cm_repeat_ping, except that cm_repeat_short_ping also sets a time limit on the duration each ping waits when a failure occurs.

Syntax

CS_RETCODE cm_repeat_short_ping(cm, server, username, password, database, timeout, maxretry, waitsec)      cm_t *cm;      CS_CHAR *server;      CS_CHAR *username;      CS_CHAR *password;      CS_CHAR *database;      CS_INT timeout;      CS_INT maxretry;      CS_INT waitsec;

Parameters

cm

Pointer to a CM control structure.

server

The name of the remote server to ping, as listed in the interfaces (UNIX) or sql.ini (Windows) file.

username

The user name used to connect to the remote server to perform the ping. This user name must exist on the remote server and have access to the database specified by the database argument.

password

The user password used to connect to the remote server.

database

If not NULL, the name of the database to ping on the remote server.

timeout

The timeout value in seconds for the user to connect to the servername specified to determine the health of the server. If the connection fails within the amount of time specified by this value, this function returns CS_FAIL. Set this value to a number slightly longer than the usual amount of time it takes the CM host to ping the host of the server under normal operating conditions.

maxretry

If a failure is encountered, the number of times this function retries before returning. If the ping succeeds immediately, cm_repeat_short_ping returns without retrying.

waitsec

The duration in seconds this function waits between each retry. If the ping succeeds immediately, cm_repeat_short_ping returns without waiting.

Returns

cm_repeat_short_ping returns these values:

Return value

Meaning

CS_SUCCEED

The routine completed successfully. The Adaptive Server was successfully pinged and appears to be available.

CS_FAIL

The routine failed, or the Adaptive Server was not available, or the host of the Adaptive Server was down and inaccessible through the network.

Examples

Example 1

if (cm_repeat_short_ping( cm, "SYB_ASE1", "bob", "bobs_password", "pubs2",     15, 3, 5 ) != CS_SUCCEED)

{

cm_error( "Failed to access server SYB_ASE1 after 3 tries.\n");

/* Optional: Do further checks to determine the root cause */

sprintf(cmd, “ping server1”);

if (system(cmd) != 0)

{

cm_error( “Host of SYB_ASE1 not responding.\n” );

}

return CS_FAIL;

}

Usage

cm_repeat_short_ping is a utility function that can ping a remote server. If the ping succeeds, cm_repeat_short_ping returns immediately. If the ping fails, or a duration of timeout elapses without a response from the remote server, cm_repeat_short_ping sleeps for a specified duration (waitsec), then tries to ping the server again. This process repeats until the maximum number of retries (maxretry) is carried out.

A server is considered to be alive if:

A connection is successfully established to the server using username and password, and

The database is not NULL, a use database command succeeds, or

The database is NULL, a select @@spid statement succeeds.

You can use cm_repeat_short_ping only on Sybase products that support use database and select @@spid.

cm_repeat_short_ping can return false failures if timeout is set to a value that is too small, or if the network is sluggish. Sybase recommends that you perform further analysis to determine the precise reason for its failure before triggering a failover.

See also

cm_ping, cm_short_ping

cm_run

Description

Starts the CM.

Syntax

CS_RETCODE cm_run(ctx)      cm_ctx_t *ctx;

Parameters

ctx

Pointer to a CM context structure.

Returns

cm_run returns this value:

Return value

Meaning

CS_FAIL

cm_run failed or a callback handler returned CS_FAIL.

Examples

Example 1

if (cm_run( ctx ) != CS_SUCCEED)

{

   cm_error( "coordination module done.\n" );

   return CS_FAIL;

}

Usage

cm_run acts as the main dispatch loop for the CM. It waits for incoming OpenSwitch events and dispatches them to the appropriate event handler installed with cm_callback.

cm_run does not exit unless an internal error is encountered, or if a callback handler returns a CS_FAIL.

cm_run may be called even when no CMs are connected to an OpenSwitch server. In this case, only timed callbacks installed with cm_timer_add are executed.

See also

cm_timer_add

cm_set_print

Description

Installs an error display function.

Syntax

CS_RETCODE cm_set_print(print_func)      cm_printerr_fn *print_func;

Parameters

print_func

A NULL, or a pointer to a function of the form:

CS_RETCODE print_func( str )    CS_CHAR *str;

Returns

cm_set_print returns these values:

Return Value

Meaning

CS_SUCCEED

The routine completed successfully.

CS_FAIL

The routine failed.

Examples

Example 1

CS_RETCODE print_func( str )

   CS_CHAR *str;

{

   fputs( str, stdout );

   return CS_SUCCEED;

}

...

if (cm_set_print( print_func ) != CS_SUCCEED)

{

   cm_error( "Unable to install print_func\n" );

   return CS_FAIL;

}

Usage

By default, cm_error and all internal error messages display to stderr. The cm_set_print function may be used to replace the default display method with a custom function; for example, to write messages to a log file.

If a NULL print_func is supplied, the default display method is used.

See also

cm_error

cm_set_prop

Description

Sets the prop attribute of a coordination module cm to value. The meaning of value depends on which property is being manipulated.

Syntax

CS_RETCODE cm_set_prop(cm, prop, value)      cm_t *cm;      CS_INT prop;      CS_VOID *value;

Parameters

cm

a pointer to a CM control structure, which is the structure used to represent a CM.

prop

The name of the property to be set. Valid values for prop are:

Prop

Description

CM_P_USERDATA

Allows a user-created application to store a value that may be used by the callback function at a later time. Callback routines are asynchronous and are defined using cm_callback as the function to call back for a particular event.

CM_P_ASYNC

A Boolean value that turns on or off whether notifications are sent directly at the time of receipt.

value

The value to which the specified prop is being set.

If prop is:

value can be:

CM_P_USERDATA

A pointer to data to be passed to the callback function when executed.

CM_P_ASYNC

CS_FALSE – to place notifications in a queue to be sent one at a time. This is the default.

CS_TRUE – to send notifications directly at the time of receipt.

Returns

cm_set_prop returns these values:

Return value

Meaning

CS_SUCCEED

The routine completed successfully.

CS_FAIL

The routine failed.

Examples

Example 1

CS_VOID *data;

data = (CS_VOID*)strdup( "STRING" );

if (cm_set_prop(cm, CM_P_USERDATA, data )

   != CS_SUCCEED)

{

   cm_error("Unable to set USERDATA property\n");

   return CS_FAIL;

}

Usage

Although the contents of all CM data structures are transparent (versus opaque), do not directly access fields within the data structures. Instead, use the cm_get_prop or cm_set_prop routines. This allows the internal definitions to be changed in future releases without affecting existing code.

See also

cm_get_prop

cm_short_ping

Description

Verifies the health of a remote server by checking if it responds to a user connection and a simple request within a specified amount of time.

Syntax

CS_RETCODE cm_short_ping(cm, server, username, password,           database, timeout)      cm_t *cm;      CS_CHAR *server;      CS_CHAR *username;      CS_CHAR *password;      CS_CHAR *database;      CS_INT timeout;

Parameters

cm

Pointer to a CM control structure.

server

The name of the remote server to ping, as listed in the interfaces (UNIX) or sql.ini (Windows) file.

username

The user name used to connect to the remote server to perform the ping. This user name must exist on the remote server and have access to the database specified by the database argument.

password

The user password to use to connect to the remote server.

database

If not NULL, the name of the database to ping on the remote server.

timeout

The timeout value in seconds for the user to connect to the servername specified to determine the health of the server. If the connection is not established within the amount of time specified, this function returns CS_FAIL. Set this value slightly longer than the usual amount of time it takes for the CM host to ping the server host under normal operating conditions.

Returns

cm_short_ping returns these values:

Return value

Meaning

CS_SUCCEED

The routine completed successfully. The Adaptive Server was successfully pinged and appears to be available.

CS_FAIL

The routine failed or the Adaptive Server was not available. Alternatively, the host of the Adaptive Server was not responding or inaccessible through the network.

Examples

Example 1

if (cm_short_ping( cm, "SYB_ASE1", "bob", "bobs_password", "pubs2", 15 )!=

    CS_SUCCEED)

{

       cm_error( "Failed to access server SYB_ASE1 within 15 seconds.\n");

       /* Optional: Do further checks to determine the root cause */

       sprintf(cmd, "ping server1");

       if (system(cmd) != 0)

       {

                cm_error( "Host of SYB_ASE1 not responding.\n" );

       }

       return CS_FAIL;

}

Usage

cm_short_ping can ping a remote server.

A server is considered to be alive if:

A connection is successfully established to the server using username and password, and

The database is not NULL, a use database command succeeds, or

The database is NULL, a select @@spid statement succeeds.

You can use cm_short_ping only on Sybase products that support use database and select @@spid.

cm_short_ping can return false failures if the timeout value is set too low or if the network is slow. Therefore, Sybase recommends that you perform further analysis to determine the reason for a failure before triggering a failover.

cm_start

Description

Resumes activity of connections.

Syntax

CS_RETCODE cm_start(cm, pool, server, spid)      cm_t *cm;      CS_CHAR *pool;      CS_CHAR *server;      CS_INT spid;

Parameters

cm

A pointer to a CM control structure.

pool

The name of the pool in which the connections should be started. Supplying only this argument starts all connections within the pool.

server

Resumes connections to the remote server. Supplying only this argument starts all connections to the server.

spid

Starts the connection identified within OpenSwitch by spid.

If you specify a spid value of -1 or NULL and do not specify any value for pool or server, OpenSwitch starts all connections

If you specify values for pool, server, or both parameters, OpenSwitch starts the connection after it verifies that the values you specify in the pool and server parameters exactly match the names of the pool and server that connect to the spid you specify.

If you specify values for pool, server, or both parameters, and there is no exact match between the actual pool and server names and the pool and server parameters you specify, OpenSwitch does not start the connection.

Returns

cm_start returns these values:

Return Value

Meaning

CS_SUCCEED

The routine completed successfully.

CS_FAIL

The routine failed.

Examples

Example 1

if (cm_start( cm, NULL, "SYB_ASE1", -1)

   != CS_SUCCEED)

{

   cm_error(

   "Can't start connections on SYB_ASE1\n" );

   return CS_FAIL;

}

Usage

cm_start is used to resume connections in OpenSwitch that were previously stopped using cm_stop.

cm_start is implemented in terms of the rp_start registered procedure within OpenSwitch. For details, see the OpenSwitch Administration Guide.

Passing a NULL value for pool or server or a value of -1 for spid acts as a wildcard for that field, indicating that all client connections match.

If no arguments are supplied to cm_start, all connections are started within OpenSwitch.

spid refers to the OpenSwitch process ID, not the process ID in the remote Adaptive Server; these two values are not the same.

Starting a connection that was not stopped has no effect.

See also

cm_stop

cm_stop

Description

Suspends connection activity.

Syntax

CS_RETCODE cm_stop(cm, pool, server, spid, flags)      cm_t *cm;      CS_CHAR *pool;      CS_CHAR *server;      CS_INT spid;      CS_INT flags;

Parameters

cm

A pointer to a CM control structure.

pool

The name of the pool in which the connections should be stopped. Supplying only this argument stops all connections within the pool.

server

Suspends connections to the remote server. Supplying only this argument stops all connections to the server.

spid

Stops the connection identified within OpenSwitch by spid.

If you specify a spid value of -1 or NULL and do not specify any value for pool or server, OpenSwitch stops all connections

If you specify a value for pool, server, or both parameters, OpenSwitch stops the connection after it verifies that the values you specify in the pool and server parameters exactly match the names of the pool and server that connect to the spid you specify.

If you specify values for pool, server, or both parameters, and there is no exact match between the actual pool and server names and the pool and server parameters you specify, OpenSwitch does not stop the connection.

flags

Symbolic options that indicate how to stop connections. These options may be used with “or” statements. Valid values for flags are:

Status

Description

CM_IGNTRAN

Stops connections even if they are in the middle of a transaction. Without this flag, cm_stop waits for the current transaction to complete.

CM_IGNFAIL

Causes stopped connections to ignore the failure of a Adaptive Server; that is, failure messages are broadcast to the CM due to the failure, and a reconnect attempt is made when cm_start is issued.

Returns

cm_stop returns these values:

Return value

Meaning

CS_SUCCEED

The routine completed successfully.

CS_FAIL

The routine failed.

Examples

Example 1

if (cm_stop( cm, NULL, "SYB_ASE1", -1, CM_IGNTRAN)

   != CS_SUCCEED)

{

   cm_error(

   "Can't stop connections on SYB_ASE1\n" );

   return CS_FAIL;

}

Usage

cm_stop is used to suspend connections in OpenSwitch. Connections matching pool, server, and spid are stopped as soon as their transactions have completed (unless the CM_IGNTRAN flag is supplied) and as soon as the currently executing query has completed.

cm_stop is implemented in terms of the rp_stop registered procedure within OpenSwitch. For more details, see the OpenSwitch Administration Guide.

Passing a NULL value for pool or server or a value of -1 for spid acts as a wildcard for that field, indicating that all client connections match.

spid refers to the OpenSwitch process ID, not the process ID in the remote Adaptive Server; these two values are not the same.

Stopping a connection that is already stopped has no effect.

cm_stop applies only to connections that are already established in the OpenSwitch server. It does not apply to connections established after it is called.

See also

cm_start

cm_timer_add

Description

Adds a timed callback.

Syntax

CS_RETCODE cm_timer_add(cm, name, ms, func, data, flags)      cm_t *cm;      CS_CHAR *name;      CS_INT ms;      cm_timer_cb *func;      CS_VOID *data;      CS_INT flags;

Parameters

cm

A pointer to a CM control structure.

name

The symbolic name for the callback.

ms

the number of milliseconds until the callback is executed.

func

A pointer to a callback function.

data

A pointer to data to be passed to the callback function when executed.

flags

Flags to affect the manner in which the timer callback is executed. The only valid value for flags is:

flag

Description

CM_TF_ONCE

The callback is called only once, at which time it is removed from the list of active callback functions and can be reinstalled only by calling cm_timer_add again.

Returns

cm_timer_add returns these values:

Return value

Meaning

CS_SUCCEED

The routine completed successfully.

CS_FAIL

The routine failed.

Examples

Example 1

CS_RETCODE cb_func( cm, name, data )

   cm_t *cm;

   CS_CHAR *name;

   CS_VOID *data;

{

   printf( "%s: data is %s\n",

      (char*)name, (char*)data );

   return CS_SUCCEED;

}

if (cm_timer_add( cm, "Callback #1", (CS_INT)30000,

   (cm_timer_cb*)cb_func,

   (CS_VOID*)NULL, (CS_INT)0)

   != CS_SUCCEED)

{

   cm_error(

   "Unable to install Callback #1\n" );

   return CS_FAIL;

}

Usage

A timed callback is a function that is called automatically every n milliseconds by the CM. Timed callbacks supply a mechanism for polling various system resources.

Timed callbacks are executed synchronously. Therefore, the granularity of the timer varies with the activity of the CM and the number of timer callbacks installed. Do not use timed callbacks where great precision of timing is expected.

The name of the callback is used to determine which callback handler is removed by cm_timer_rem.

A return value of CS_SUCCEED from a timer callback function indicates that the function completed normally. Returning CS_FAIL causes the CM to exit, and cm_run to return CS_FAIL.

See also

cm_timer_rem, cm_run

cm_timer_rem

Description

Removes a timed callback.

Syntax

CS_RETCODE cm_timer_rem(cm, name)      cm_t *cm;      CS_CHAR *name;

Parameters

cm

A pointer to a CM control structure.

name

The symbolic name for the callback to be removed.

Returns

cm_timer_rem returns these values:

Return value

Meaning

CS_SUCCEED

The routine completed successfully.

CS_FAIL

The routine failed.

Examples

Example 1

if (cm_timer_rem( cm, "Callback #1" )

   != CS_SUCCEED)

{

   cm_error(

   "Unable to de-install Callback #1\n" );

   return CS_FAIL;

Usage

A timed callback is a function that is automatically called every n milliseconds by the CM.

Timed callbacks are executed synchronously. Therefore, the granularity of the timer varies with the activity of the CM and the number of timer callbacks installed. Do not use timed callbacks where great precision of timing is expected.

The name of the callback supplied to cm_timer_rem must match the name specified for cm_timer_add.

See also

cm_timer_add

cm_unignore

Description

Removes OpenSwitch ignore requests matching template.

Syntax

CS_RETCODE cm_unignore (cm, msg_type, msg)      cm_t *cm;      CS_INT msg_type;      CS_VOID *msg;

Parameters

cm

Pointer to a CM control structure.

msg_type

The type of message being passed through the msg argument. The only valid value for msg_type is:

msg_type

Description

CM_CB_SERVER

A server-name request message

msg

A pointer to a valid data structure of the type identified by msg_type.

Returns

cm_unignore returns these values:

Return value

Meaning

CS_SUCCEED

The routine completed successfully.

CS_FAIL

The routine failed.

Examples

Example 1

cm_req_srv_t m;

cm_ignore_clear( cm, CM_CB_SERVER, (CS_VOID*)&m );

/*

* "Unignores" all messages coming generated

* from Adaptive Server "SYB_ASE1".

*/

strcpy( (char*)m.cur_server, "SYB_ASE1" );

if (cm_unignore( cm, CM_CB_SERVER, (CS_VOID*)&m )

   != CS_SUCCEED)

{

   cm_error(

   "Can't unignore msgs from SYB_ASE1\n" );

   return CS_FAIL; }

Usage

Because one message is received for each OpenSwitch client connection that is lost due to an Adaptive Server failure, you may want to pay attention only to the first message received and, following the failover, ignore any subsequent messages from that Adaptive Server until it is recovered.

The cm_ignore_clear, cm_ignore, and cm_unignore functions are used to cause a CM to automatically discard messages received from OpenSwitch according to a message template.

The cm_ignore_clear function establishes an empty message template. After it has been used to clear the msg structure, the data structure fields that are to be ignored may be set. By passing this populated data structure template to cm_ignore, all future messages matching the template are automatically discarded by the CM until cm_unignore is called with an identical template.

Messages are ignored only when all fields of the incoming message match exactly all populated fields of the template message. There is no facility for providing “or” logic within a single template. You can do this only by passing multiple templates to cm_ignore or by implementing a separate mechanism.

See also

cm_ignore_clear, cm_ignore

cm_version

Description

Returns a pointer to the location of the version string and displays the version information for the CM.

Syntax

CS_CHAR *cm_version()

Parameters

None.

Examples

Example 1

Sybase Coordination Module/15.0/B/SPARC/Solaris 2.8/0/OPT/Mon Mar 22

12:30:52 2005

Confidential property of Sybase, Inc.

Copyright 1987 - 2005

Sybase, Inc. All rights reserved.

Unpublished rights reserved under U.S. copyright laws.

This software contains confidential and trade secret information of Sybase,

Inc. Use, duplication or disclosure of the software and documentation by

the U.S. Government is subject to restrictions set forth in a license

agreement between the Government and Sybase, Inc. or other written

agreement specifying the Government's rights to use the software and any

applicable FAR provisions, for example, FAR 52.227-19.

Sybase, Inc. One Sybase Drive, Dublin, CA 94568, USA

Copyright © 2009. Sybase Inc. All rights reserved.

View this document as PDF

Return value	Meaning
`CS_SUCCEED`	The routine completed successfully. The Adaptive Server was successfully pinged and appears to be available.
`CS_FAIL`	The routine failed or the Adaptive Server was not available.

Prop	Description
CM_P_USERDATA	Allows a user-created application to store a value that may be used by the callback function at a later time. Callback routines are asynchronous and are defined using cm_callback as the function to call back for a particular event.
CM_P_ASYNC	A Boolean value that turns on or off whether notifications are sent directly at the time of receipt.

If *prop* is:	*value* can be:
CM_P_USERDATA	A pointer to data to be passed to the callback function when executed.
CM_P_ASYNC	CS_FALSE – to place notifications in a queue to be sent one at a time. This is the default. CS_TRUE – to send notifications directly at the time of receipt.

Status	Description
CM_IGNTRAN	Stops connections even if they are in the middle of a transaction. Without this flag, cm_stop waits for the current transaction to complete.
CM_IGNFAIL	Causes stopped connections to ignore the failure of a Adaptive Server; that is, failure messages are broadcast to the CM due to the failure, and a reconnect attempt is made when cm_start is issued.