This section describes registered procedures for OpenSwitch coordination modules (CM). CM registered procedures are issued programatically within the user code to implement registered procedure calls (RPCs) via a CM.
All cm_rp_* calls return these values:
Value |
Description |
|---|---|
|
The routine completed successfully. |
|
The routine failed. |
Registered procedure |
Description |
|---|---|
Kills client connections within OpenSwitch. |
|
Sets the status of a given pool. |
|
Cancels the processing of a client connection. |
|
Reads the OpenSwitch configuration file at runtime. |
|
Displays a list of coordination modules that are currently connected to the OpenSwitch server. |
|
Enables or disables OpenSwitch debugging messages. |
|
Deletes allocated list. |
|
Dumps the thread and/or mutex information. |
|
Displays the requested information provided by the registered procedures. |
|
Resumes the activity of the OpenSwitch server after a user has performed some manual intervention. |
|
Displays registered procedures and their respective parameters. |
|
Queues text messages to broadcast to one or more client connections. |
|
Adds a connection attribute or value to a pool. |
|
Adds the status of the server within the pool. |
|
Displays or sets the pool cache setting. |
|
Creates a new pool. |
|
Drops the existing pool. |
|
Displays information about the pools. |
|
Removes a connection attribute or value from a pool. |
|
Removes the server from the pool. |
|
Displays or sets the status of the server present in the pool. |
|
Sends a notification to the secondary replication coordination module (RCM) telling it to establish a connection to the primary OpenSwitch. |
|
Displays a list of RCMs with which OpenSwitch is familiar. |
|
Shuts down a given RCM. |
|
Starts a given RCM. |
|
Displays the current set of attribute/value pairs being used by the resource governor thread. |
|
Sets or displays a configuration parameter’s value. |
|
Displays a query being executed by the specified spid. |
|
Shuts down an OpenSwitch server. |
|
Displays the version number of OpenSwitch. |
|
Displays detailed information about user connections to OpenSwitch. |
|
Sets the status of a given remote server. |
|
Responds to a CM_CB_SERVER message. |
|
Switches connections between servers. |
Shuts down client connections within OpenSwitch.
CS_RETCODE cm_kill(cm, pool, server, spid) cm_t *cm; CS_CHAR *pool; CS_CHAR *server; CS_INT spid;
A pointer to a CM control structure.
The name of the pool in which the connections should be shut down. Supplying only this argument causes all connections within pool to be shut down.
Shuts down connections to the remote server. Supplying only this argument causes all connections to the server to be shut down.
Shuts down the connection identified within the OpenSwitch by spid. If this argument is specified, pool and server are ignored. An spid of -1 indicates that all connections matching the pool name and server name are to be shut down.
cm_kill returns these values:
Return value |
Meaning |
|---|---|
|
The routine completed successfully. |
|
The routine failed. |
if (cm_kill( cm, NULL, "SYB_ASE1", -1) != CS_SUCCEED)
{
cm_error(
"Can't kill connections to SYB_ASE1\n" );
return CS_FAIL;
}
cm_kill is used to shut down client connections to the remote server through OpenSwitch.
If no arguments are supplied to cm_kill, all connections are shut down within OpenSwitch. Use this procedure with caution.
cm_kill is implemented in terms of the rp_kill 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.
As with Adaptive Server, shutting down a connection causes it to be forcefully removed from the OpenSwitch server, and no messages are delivered to the client.
Sets the status of a given pool.
CS_RETCODE cm_pool_status(cm, pool, status) cm_t *cm; CS_CHAR *pool; CS_INT status;
Pointer to a CM control structure.
The name of the pool that is to have its status set.
A symbolic value representing the status to which pool is to be set. Valid values for status are:
Status |
Description |
|---|---|
CM_UP |
The pool is immediately available for use. |
CM_DOWN |
The pool is unavailable, and is not considered for use by any new client connections established to OpenSwitch. New client connections are failed over to the next available pool if one is configured. |
CM_LOCKED |
The pool is available, but any new incoming connections are blocked (or stopped) until the status is changed to CM_UP or CM_DOWN. But if the NOWAIT_ON_LOCKED parameter is set to 1 in the OpenSwitch configuration, clients are rejected immediately, a descriptive message is sent, and blocked connections appear to the client application to have stopped responding until the pool is unlocked. |
cm_pool_status returns these values:
Return value |
Meaning |
|---|---|
|
The routine completed successfully. |
|
The routine failed. |
if (cm_pool_status( cm, "POOLA", CM_DOWN )
!= CS_SUCCEED)
{
cm_error( "Could not mark POOLA as DOWN\n" );
return CS_FAIL;
}
cm_pool_status uses the rp_pool_status registered procedure within OpenSwitch to function. For more details, see the OpenSwitch Administration Guide.
Changing the status of a pool does not affect users who are currently using the pool. The pool status applies only to connections actively being established to OpenSwitch, or existing connections that are in the process of switching or performing a failover.
Connections that are currently blocked on a locked pool are blocked until either the pool is unlocked or until the client application performs a disconnect. Administrative requests made of the connection, such as a call to cm_switch, or cm_stop, are queued until the pool changes status.
To stop all activity on a given pool, use cm_pool_status with the CM_LOCKED argument followed by a call to cm_stop.
Uses rp_cancel to cancel the processing of a client connection.
CS_RETCODE CS_PUBLIC cm_rp_cancel(cm, pool, server, spid, why) cm_t *cm; CS_CHAR *pool; CS_CHAR *server; CS_INT spid; CS_CHAR *why;
Pointer to a CM control structure.
Cancels connections to a pool you specify. Supplying only this argument cancels all connections within the pool you specify.
Cancels connections to a remote server you specify. Supplying only this argument cancels all connections to the remote server you specify.
Cancels the connection identified within the OpenSwitch server by spid.
If spid is -1 or NULL, and you do not specify any value for both pool and server, OpenSwitch cancels all connections of all spids.
If you specify values for pool, server, or both parameters, OpenSwitch cancels 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 cancel the connection.
Message to be sent to the user of a cancelled query.
if (cm_rp_cancel(cm,(char *)NULL, (char *)NULL, -1, "OpenSwitch") !=
CS_SUCCEED)
{
cm_error(“Unable to cancel all the connections connected to
the OpenSwitch.\n”);
return CS_FAIL;
}
Cancels all the connections to the OpenSwitch server.
if (cm_rp_cancel(cm,”POOL1”, (char *)NULL, -1, "OpenSwitch") != CS_SUCCEED)
{
cm_error(“Unable to cancel all the connections connected to ‘POOL1’
of the OpenSwitch.\n”);
return CS_FAIL;
}
Cancels all OpenSwitch connections to “POOL1.”
if (cm_rp_cancel(cm,”POOL1”,“ASE”,17,"OpenSwitch") != CS_SUCCEED)
{
cm_error(“Unable to cancel the connection having spid ‘17’ connected
to server ‘ASE’ of pool ‘POOL1’ of the OpenSwitch.\n”);
return CS_FAIL;
}
Cancels a connection where spid 17 is connected to server “ASE” in “POOL1.”
Uses rp_cfg within OpenSwitch to read the OpenSwitch configuration file at runtime.
CS_RETCODE CS_PUBLIC cm_rp_cfg (cm, cfg_file) cm_t *cm; CS_CHAR *cfg_file;
Pointer to a CM control structure.
The name of the configuration file to be read. Passing a file name of NULL, default, or an empty string causes the previously processed configuration file to be read.
if (cm_rp_cfg(cm, "default")!= CS_SUCCEED)
{
cm_error(“Unable to read configuration File\n”);
return CS_FAIL;
}
Reads the configuration file at runtime.CM application
Uses rp_cm_list to display a list of coordination modules connected to the OpenSwitch server.
CS_RETCODE CS_PUBLIC cm_rp_cm_list (cm) cm_t *cm;
Pointer to a CM control structure.
if (cm_rp_cm_list(cm) != CS_SUCCEED)
{
cm_error(“Unable to display the CM list\n”);
return CS_FAIL;
}
Displays all the coordination modules that are currently connected to the OpenSwitch server.
Uses rp_debug within a coordination module to enable or disable OpenSwitch debugging messages.
CS_RETCODE CS_PUBLIC cm_rp_debug(cm, flags, state) cm_t *cm; CS_CHAR *flags; CS_CHAR *state;
pointer to a CM control structure.
A list of one or more single-character option flags. Each flag is a toggle; supplying it once enables the option, supplying it again disables the option. Passing an empty option (“ ”) lists the debugging flags that are currently enabled. The following table shows the valid debugging flags.
Value |
Description |
|---|---|
a |
Enables all possible debugging flags. |
b |
Displays attempts to set or test configuration options as described in the configuration file. |
c |
Displays information about result handling of client-side cursors. |
d |
Logs access to data items attached to each thread's user data. |
D |
Displays information about the handling of dynamic SQL statements. |
e |
Logs all error messages passing through the OpenSwitch error handlers, even those that are normally suppressed. |
f |
Shows connection progress information when OpenSwitch is interacting with the coordination module. |
g |
Displays operations involving security negotiations. |
h |
Displays messages when entering each event handler. |
i |
Displays progress information concerning the switching process during a call to rp_switch, such as success or failure of each switch, and which connections fail to go idle within the specified period of time. |
j |
Shows the connection caching activity. |
k |
Displays activity of the timer thread (the thread that is responsible for calling timed callbacks within OpenSwitch). |
l |
Dumps every SQL statement issued through the SRV_LANGUAGE event handler to log_file. |
m |
Displays every memory allocation and de-allocation (more extensive information may be made available at compile time). |
n |
Displays receipt and handling of cancel or attention requests from client connections. |
o |
Displays a message each time a command line option value is set or tested. |
p |
Displays manipulation, use, and assignments of server pools. |
q |
Displays information about the connection monitor activity. |
r |
Displays current state and actions of the internal resource monitoring thread. |
s |
Shows access and release of shared and exclusive internal locks (used to prevent concurrent access to internal data structures). |
S |
Logs SQL statements that are replayed during failover. |
t |
Displays activities of the timer thread that is responsible for periodically waking other sleeping threads. |
u |
Displays information about result sets being returned to client threads. |
x |
Displays mutex accesses (more detailed view on shared locks). |
State of the flags.
if (cm_rp_debug(cm,"i", "on") != CS_SUCCEED)
{
cm_error(“Unable to set ‘i’ debugging options\n”);
return CS_FAIL;
}
Sets the “i” debugging options.
if (cm_rp_debug(cm,"i", "off") != CS_SUCCEED)
{
cm_error(“Unable to reset ‘i’ debugging options\n”);
return CS_FAIL;
}
Resets the “i” debugging options.
Uses rp_del_list to free the memory allocated in the cm_rp_get_help API.
CS_RETCODE cm_rp_del_list(list, type) CS_VOID** list; CS_INT type;
Identifies the list to be deleted.
Indicates the list type. The valid values are:
Type |
Description |
|---|---|
CM_INFO |
Indicating an information list is being deleted. |
CM_METADATA |
Indicating a metadata list is to be deleted. |
if (list_pool_info) != NULL)
{
cm_rp_del_list((CS_VOID **)%list_pool_info, CM_INFO);
}
Delete pool structure list.
if (list_col_metad) != NULL)
{
cm_rp_del_list((CS_VOID **)&list_pool_metad, CM_METADATA);
}
Delete column metadata structure list.
Invoke this function after obtaining the information from cm_rp_get_help to delete the allocated list and to avoid the memory leaks.
Uses rp_dump to dump the thread and/or mutex information.
CS_RETCODE CS_PUBLIC cm_rp_dump(cm, what, sendtolog) cm_t *cm; CS_INT what; CS_INT sendtolog;
Pointer to a CM control structure.
Valid values are:
CM_THREAD – to dump information about all threads
CM_MUTEX – to dump information about all mutexes
CM_ALL – to dump information about all OpenSwitch threads and mutexes.
If sendtolog is nonzero, the output is directed to the OpenSwitch log; otherwise, the output is directed to the caller.
if (cm_rp_dump(cm, CM_ALL, 0) != CS_SUCCEED)
{
cm_error(“Unable to dump information\n”);
return CS_FAIL;
}
Dumps threads and mutex information.
Uses different registered procedures to display the requested information that these CM registered procedures provide:
cm_rp_pool_cache
cm_rp_pool_help
cm_rp_rmon
cm_rp_debug
cm_rp_pool_server_status
cm_rp_version
cm_rp_who
cm_osw_info* cm_rp_get_help(cm, type, name) cm_t *cm; CS_INT *type; CS_CHAR *name;
Pointer to a CM control structure.
Identifies the type of requested information. 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. |
Name of server or pool.
A pointer to a cm_infogateway structure, which is defined as:
typedef struct cm_infogateway {
CS_CHAR name[CS_MAX_NAME]; /* Name of the column*/
CS_CHAR value[CS_MAX_VALUE]; /* Value of column*/
struct cm_infogateway *next; /* Next pointer*/
} cm_osw_info;
cm_osw_info *list_pool_info = NULL;
list_pool_info = cm_rp_get_help(cm, POOL_T_TYPE, (char*)data);
cm_rp_debug, cm_rp_pool_cache, cm_rp_pool_help, cm_rp_pool_server_status, cm_rp_rmon, cm_rp_version, cm_rp_who
Uses rp_go to resume the activity of the OpenSwitch after a user has performed some manual intervention.
CS_RETCODE CS_PUBLIC cm_rp_go(cm) cm_t *cm;
Pointer to a CM control structure.
if (cm_rp_go(cm) != CS_SUCCEED)
{
cm_error(“Unable to resumes the activity of the OpenSwitch after a user
has done some manual intervention \n”);
return CS_FAIL;
}
Resumes the activity of the OpenSwitch after a user has performed some manual intervention.
Uses rp_help to display registered procedures and their respective parameters.
CS_RETCODE CS_PUBLIC cm_rp_help(cm) cm_t *cm;
Pointer to a CM control structure.
if (cm_rp_help(cm) != CS_SUCCEED)
{
cm_error(“Unable to display the list of the registered procedures and
their respective parameters.\n”);
return CS_FAIL;
}
Displays a list of the registered procedures and their parameters.
Uses rp_msg within OpenSwitch to queue text messages to broadcast to one or more client connections.
CS_RETCODE CS_PUBLIC cm_rp_msg(cm, pool, server, spid, msg) cm_t *cm; CS_CHAR *pool; CS_CHAR *server; CS_INT spid; CS_CHAR *msg;
Pointer to a CM control structure.
The name of the pool to which the message should be delivered. If only pool is specified, the message is sent to all connections within the pool.
Sends the message to current connections to a server you specify with this parameter. If only server is specified, the message is sent to all current connections to the server.
The OpenSwitch process ID of the client connection to receive the message.
If spid is -1 or NULL and you do not specify any value for both pool and server, the message is sent to all the spids connected to server in the pool.
If you specify a value for pool, server, or both parameters, OpenSwitch sends the message 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 send the message.
The text of the message to be delivered.
if (cm_rp_msg(cm,(char *)NULL, (char *)NULL, -1, "All connections will
shut down in 5 minutes") != CS_SUCCEED)
{
cm_error(“Unable to send message to all the connections connected
to the OpenSwitch.\n”);
return CS_FAIL;
}
Sends a message to all the OpenSwitch connections.
if (cm_rp_msg(cm,”POOL1”, (char *)NULL, -1, "All connections will shut
down in 5 minutes") != CS_SUCCEED)
{
cm_error(“Unable to send message to all the connections connected to
‘POOL1’ of the OpenSwitch.\n”);
return CS_FAIL;
}
Sends a message to all OpenSwitch connections to “POOL1.”
if (cm_rp_msg(cm,”POOL1”, “ASE”,17, "All connections will shut down in
5 minutes") != CS_SUCCEED)
{
cm_error(“Unable to send message to the connection having spid ‘17’
connected to server ‘ASE’ of ‘POOL1’ of the OpenSwitch.\n”);
return CS_FAIL;
}
Sends a message to the OpenSwitch connection spid 17 connected to server “ASE” in “POOL1”.
Uses rp_pool_addattrib to add a connection attribute or value to a pool.
CS_RETCODE CS_PUBLIC cm_rp_pool_addattrib(cm, pool, attrib, value) cm_t *cm; CS_CHAR *pool; CS_INT attrib; CS_CHAR *value;
Pointer to a CM control structure.
Name of the pool to which attributes are being added.
Name of the attribute to be added to the pool. The valid values are:
CM_USERNAME
CM_APPNAME
CM_HOSTNAME
A standard SQL wildcard expression used to match attrib.
if (cm_rp_pool_addattrib(cm,"POOL1", CM_APPNAME, "isql")!= CS_SUCCEED)
{
cm_error(“Unable to add ‘appname’ attribute.\n”);
return CS_FAIL;
}
Adds the “appname” attribute with a value of “isql” to “POOL1.”
Uses rp_pool_addserver to add the status of the server within the pool.
CS_RETCODE CS_PUBLIC cm_rp_pool_addserver(cm, pool, server, rel_server, status, position) cm_t *cm; CS_CHAR *pool; CS_CHAR *server; CS_CHAR *rel_server; CS_INT status; CS_INT position;
Pointer to a CM control structure.
Name of the pool to which the server is being added.
Name of the server to be added.
Name of an existing server name within the pool, relative to the server being added.
Status of the server being added. Valid values for status are:
CM_UP
CM_DOWN
CM_LOCKED.
Position of the server relative to rel_server. Valid values are:
CM_HEAD
CM_BEFORE
CM_AFTER
CM_TAIL.
if (cm_rp_pool_addserver(cm,"POOL1", "ase2","ase1",CM_UP,CM_AFTER) !=
CS_SUCCEED)
{
cm_error(“Unable to add server ‘ase2’ with status ‘UP’ after ‘ase1’ in the pool POOL1’\n”); return CS_FAIL;
}
Adds server “ase2” after “ase1” with an UP status in “POOL1.”
Uses rp_pool_cache to display or set the pool cache.
CS_RETCODE CS_PUBLIC cm_rp_pool_cache(cm, pool, cache) cm_ t *cm; CS_CHAR *pool; CS_INT cache;
Pointer to a CM control structure.
Name of the pool to be cached.
The number of seconds that connection caches are held in the pool. Setting this to a value to zero (0) disables future connection caching. If this value is set to -1, it displays the cache values for the pools.
if (cm_rp_pool_cache(cm, (char *)NULL, 30) != CS_SUCCEED)
{
cm_error(“Unable to set cache value for all the pools\n”);
return CS_FAIL;
}
Sets the cache value for all pools.
if (cm_rp_pool_cache(cm, (char *)NULL, -1) != CS_SUCCEED)
{
cm_error(“Unable to display the cache value for all the pools\n”);
return CS_FAIL;
}
Displays the cache values.
Uses rp_pool_create to create a new pool.
CS_RETCODE CS_PUBLIC cm_rp_pool_create(cm, pool, rel_pool, position, status, mode) cm_t *cm; CS_CHAR *pool; CS_CHAR *rel_pool; CS_INT position; CS_INT status; CS_INT mode;
Pointer to a CM control structure.
Name of the pool to be created.
Name of an existing pool, relative to the pool being created.
Position of pool relative to rel_pool. The valid values are CM_HEAD, CM_BEFORE, CM_AFTER, and CM_TAIL.
The initial status of the pool. The valid values are CM_UP, CM_DOWN, or CM_LOCKED.
Mode of the pool. The valid values are CM_CHAINED or CM_BALANCED.
if (cm_rp_pool_create(cm,"POOL2","POOL1",CM_BEFORE, CM_UP, CM_CHAINED) !=
CS_SUCCEED)
{
cm_error(“Unable to create ‘POOl2’ before ‘POOL1’ in CHAINED mode having status ‘UP’\n”); return CS_FAIL;
}
Creates “POOL2” before “POOL1” in CHAINED mode with an UP status.
Uses rp_pool_drop to drop the existing pool.
CS_RETCODE CS_PUBLIC cm_rp_pool_drop(cm, pool) cm_t *cm; CS_CHAR *pool;
Pointer to a CM control structure.
Name of the pool to be dropped.
if (cm_rp_pool_drop(cm,"POOL1") != CS_SUCCEED)
{
cm_error(“Unable drop pool ‘POOL1’ \n”);
return CS_FAIL;
}
Drops “POOL1.”
Uses rp_pool_help to display information about pools.
CS_RETCODE CS_PUBLIC cm_rp_pool_help(cm, pool) cm_t *cm; CS_CHAR *pool;
Pointer to a CM control structure.
The name of the pool that is displaying information.
if (cm_rp_pool_help(cm,"POOL1") != CS_SUCCEED)
{
cm_error(“Unable to display information for the pool ‘POOL1’ \n”);
return CS_FAIL;
}
Displays information about “POOL1.”
if (cm_rp_pool_help(cm, (char *)NULL) != CS_SUCCEED)
{
cm_error(“Unable to display information about all the pools \n”);
return CS_FAIL;
}
Displays information about all pools.
Uses rp_pool_remattrib to remove a connection attribute or value from a pool.
CS_RETCODE CS_PUBLIC cm_rp_pool_remattrib(cm, pool, attrib, value) cm_t *cm; CS_CHAR *pool; CS_INT attrib; CS_CHAR *value;
Pointer to a CM control structure.
Name of the pool from which attributes are being removed.
Name of the attribute to be deleted from the pool. The valid values are CM_USERNAME, CM_APPNAME, or CM_HOSTNAME.
A standard SQL wildcard expression used to match attrib.
if (cm_rp_pool_remattrib(cm,"POOL1", CM_APPNAME, "isql") != CS_SUCCEED)
{
cm_error(“Unable to remove ‘appname’ attribute.\n”);
return CS_FAIL;
}
Removes the “appname” attribute with the value of “isql” from “POOL1.”
Uses rp_pool_remserver to remove the server from the pool.
CS_RETCODE CS_PUBLIC cm_rp_pool_remserver(cm, pool, server) cm_t *cm; CS_CHAR *pool; CS_CHAR *server;
Pointer to a CM control structure.
Name of the pool from which server is to be removed.
Name of the server to be removed.
if (cm_rp_pool_remserver(cm,"POOL1", "ase2") != CS_SUCCEED)
{
cm_error(“Unable to remove server ‘ase2’ from the pool ‘POOL1’\n”);
return CS_FAIL;
}
Removes server “ase2” from “POOL1.”
Uses rp_pool_server_status to display or set the status of the server present in the pool.
CS_RETCODE CS_PUBLIC cm_rp_pool_server_status(cm, pool, server, status) cm_ t *cm; CS_CHAR *pool; CS_CHAR *server; CS_INT status;
Pointer to a CM control structure.
The name of the pool.
The name of the server. If server name is NULL, then cm_rp_pool_server_status displays the status of all servers present in the pool.
The status of the server. Valid status values are CM_UP, CM_DOWN, and CM_LOCKED.
if (cm_rp_pool_server_status(cm, "POOL1", "ase1", CM_DOWN) != CS_SUCCEED)
{
cm_error(“Unable to set the status of the server ‘ase1’ present
in the pool ‘POOL1’.\n”);
return CS_FAIL;
}
Sets the status of server “ase1,” which is present in “POOL1,” to DOWN.
Issue rp_rcm_connect_primary through a registered procedure call to a secondary OpenSwitch to send a notification to the secondary RCM telling it that the primary OpenSwitch has restarted and it can re-establish a monitoring connection.
CS_RETCODE CS_PUBLIC cm_rp_rcm_connect_primary(cm) cm_t *cm;
Pointer to a CM control structure.
if (cm_rp_rcm_connect_primary(cm) != CS_SUCCEED)
{
cm_error(“Unable to send the notification.\n”);
return CS_FAIL;
}
Sends the notification to the secondary RCM.
Used when the primary OpenSwitch starts after the secondary replication coordination module has already been running.
Uses rp_rcm_list to display a list of RCMs with which OpenSwitch is familiar.
CS_RETCODE CS_PUBLIC cm_rp_rcm_list(cm) cm_t *cm;
Pointer to a CM control structure.
if (cm_rp_rcm_list(cm) != CS_SUCCEED)
{
cm_error(“Unable to display the RCM list\n”);
return CS_FAIL;
}
Displays the RCM list known to OpenSwitch.
Uses rp_rcm_shutdown to shut down a given RCM.
CS_RETCODE CS_PUBLIC cm_rp_rcm_shutdown(cm, rcm_name) cm_t *cm; CS_CHAR *rcm_name;
Pointer to a CM control structure.
Name of the RCM to be shut down.
if (cm_rp_rcm_shutdown(cm, “rcm1”) != CS_SUCCEED)
{
cm_error(“Unable to shutdown the ‘rcm1’\n”);
return CS_FAIL;
}
Shuts down “rcm1.”
Uses rp_rcm_startup to start the RCM.
CS_RETCODE CS_PUBLIC cm_rp_rcm_startup(cm, rcm_path, rcm_cfg, rcm_log, rcm_retries, rcm_redundant) cm_ t *cm; CS_CHAR *rcm_path; CS_CHAR *rcm_cfg; CS_CHAR *rcm_log; CS_INT rcm_retries; CS_INT rcm_redundant;
Pointer to a CM control structure.
Used to specify the path of the RCM. The default value is $OPENSWITCH/bin/rcm on UNIX and %OPENSWITCH%\bin\rcm.exe on Windows.
Used to specify the path of the RCM configuration file. The default is the RCM_CFG_FILE value in the OpenSwitch configuration file.
Used to specify the path of the RCM log file. The default is the RCM_LOG_FILE value in the OpenSwitch configuration file.
Used to specify the number of retry attempts made to start an RCM if the RCM exits for reasons other than a user-requested shutdown. If rcm_retries is -1, the default is the RCM_RETRIES value in the OpenSwitch configuration file.
Used to specify whether the RCM is redundant. If rcm_redundant is -1, the default is the RCM_SECONDARY value in the OpenSwitch configuration file.
if (cm_rp_rcm_startup(cm, (char *)NULL, (char *)NULL, (char *)NULL, -1,-1)
!= CS_SUCCEED)
{
cm_error(“Unable to start the RCM\n”);
return CS_FAIL;
}
Starts the RCM that is present in $OPENSWITCH/bin/rcm (UNIX) or %OPENSWITCH%\bin\rcm.exe (Windows).
Uses rp_rmon within OpenSwitch to display the current set of attribute and value pairs being used by the resource governor thread. See “[LIMIT_RESOURCE]” in Chapter 5, “Using the Configuration File,” of the OpenSwitch Administration Guide for more information about resource monitoring.
CS_RETCODE CS_PUBLIC cm_rp_rmon(cm) cm_t *cm;
Pointer to a CM control structure.
if (cm_rp_rmon(cm) != CS_SUCCEED)
{
cm_error(“Unable to display information about the resource governor
thread. \n”);
return CS_FAIL;
}
Displays information about the resource governor thread.
Uses rp_set to set or display a configuration parameter’s value.
CS_RETCODE CS_PUBLIC cm_rp_set(cm, parm_name, parm_value) cm_t *cm; CS_CHAR *parm_name; CS_CHAR *parm_value;
Pointer to a CM control structure.
Name of a configuration variable as listed in the configuration file.
Value to which the parameter is to be set. If a NULL parm_value is supplied, the value of parm_name displays.
if (cm_rp_set(cm,"TEXTSIZE","104857") != CS_SUCCEED)
{
cm_error(“Unable to set the ‘TEXTSIZE’ configuration
parameter\n”);
return CS_FAIL;
}
Sets the value of the TEXTSIZE configuration parameter.
if (cm_rp_set(cm,"TEXTSIZE",(char*)NULL) != CS_SUCCEED)
{
cm_error (“Unable to display the value of the ‘TEXTSIZE’
configuration parameter.\n”);
return CS_FAIL;
}
Displays the value of the TEXTSIZE configuration parameter.
Uses rp_showquery within OpenSwitch to display a query being executed by the specified spid.
CS_RETCODE CS_PUBLIC cm_rp_showquery(cm, spid) cm_t *cm; CS_INT spid;
Pointer to a CM control structure.
The OpenSwitch spid executing a query.
if (cm_rp_showquery(cm, 7) != CS_SUCCEED)
{
cm_error(“Unable to display query being executed by a spid ‘7’\n”);
return CS_FAIL;
}
Displays the query being executed by spid 7.
Uses rp_shutdown within OpenSwitch to shut down an OpenSwitch server.
CS_RETCODE CS_PUBLIC cm_rp_shutdown(cm) cm_t *cm;
Pointer to a CM control structure.
if (cm_rp_shutdown(cm) != CS_SUCCEED)
{
cm_error(“Unable to shutdown the OpenSwitch\n”);
return CS_FAIL;
}
Shuts down the OpenSwitch server.
Uses rp_version to display the OpenSwitch version number.
CS_RETCODE CS_PUBLIC cm_rp_version(cm) cm_t *cm;
Pointer to a CM control structure.
if (cm_rp_version(cm) != CS_SUCCEED)
{
cm_error(“Unable to display version number of the OpenSwitch\n”);
return CS_FAIL;
}
Displays the OpenSwitch version number.
Uses rp_who to display detailed information about user connections to OpenSwitch.
CS_RETCODE CS_PUBLIC cm_rp_who(cm, spid) cm_t *cm; CS_INT spid;
Pointer to a CM control structure.
The OpenSwitch spid value to display. “-1” displays information about all spids connected to OpenSwitch.
if (cm_rp_who(cm, 7) != CS_SUCCEED)
{
cm_error(“Unable to display information about spid ‘7’.\n”);
return CS_FAIL;
}
Displays information about a specific spid; for example, spid 7.
if (cm_rp_who(cm, -1) != CS_SUCCEED)
{
cm_error(“Unable to display information about all the spids.\n”);
return CS_FAIL;
}
Displays information about all spids connected to OpenSwitch.
Sets the status of a given remote server.
CS_RETCODE cm_server_status(cm, server, status) cm_t *cm; CS_CHAR *server; CS_INT status;
Pointer to a CM control structure.
The name of the server that is to have its status set.
A symbolic value representing the status to which the server is to be set. Valid values for status are:
Status |
Description |
|---|---|
CM_UP |
The server is immediately available for use. |
CM_DOWN |
The server is unavailable, and is not to be considered for use by any new client connections established to the OpenSwitch server. |
CM_LOCKED |
The server is available, but any new, incoming connections through the pool are blocked (or stopped) until the status is changed to CM_UP or CM_DOWN, unless the NOWAIT_ON_LOCKED parameter is set to 1in the OpenSwitch configuration, in which case clients are rejected immediately and a descriptive message is sent. Blocked connections appear to the client application to be not responding until the pool is unlocked. |
cm_server_status returns these values:
Return value |
Meaning |
|---|---|
|
The routine completed successfully. |
|
The routine failed. |
if (cm_server_status( cm, "SYB_ASE1", CM_DOWN )
!= CS_SUCCEED))
{
cm_error( "Could not mark SYB_ASE1 as DOWN\n" );
return CS_FAIL;
}
cm_server_status uses the rp_server_status registered procedure within OpenSwitch to function. For more details, see the OpenSwitch Administration Guide.
Changing the status of a server does not affect users who are currently using the server. The server status applies only to connections actively being established to OpenSwitch, or to existing connections that are in the process of switching or performing a failover.
Connections that are currently blocked on a LOCKED server remain blocked until the server is unlocked or until the client application performs a disconnect. This means that any administrative requests made of the connection, such as a call to, or cm_stop, are queued until the server changes status.
To stop all activity on a given server, use cm_server_status with the CM_LOCKED argument followed by a call to cm_stop.
Sets a remote server name for a client to connect to within OpenSwitch in response to a CM_CB_SERVER message.
CS_RETCODE cm_set_srv(cm, spid, server) cm_t *cm; CS_INT spid; CS_CHAR *server;
A pointer to a CM control structure.
The OpenSwitch process ID of the connection to be routed.
The name of the server to which the spid is to be routed.
cm_set_srv returns these values:
Return value |
Meaning |
|---|---|
|
The routine completed successfully. |
|
The routine failed. |
if (cm_set_srv( cm, (CS_INT)10, "SYB_ASE1" )
!= CS_SUCCEED)
{
cm_error("To send spid 10 to SYB_ASE1\n");
return CS_FAIL;
}
This function may be used in response
to a CM_CB_SERVER request,
and is used to respond to the calling spid with
the name of the server that should be used. Usually, the spid that
issued the CM_CB_SERVER notification blocks
waiting for either this function to respond with the name of the server
that it should use, or cm_kill to kill
the spid, or cm_switch to switch it
to another server.
cm_set_srv utilizes the rp_set_srv registered procedure to function. For more information, see the OpenSwitch Administration Guide.
Calling cm_set_srv on an spid that is not actively waiting for a response from a CM does not return an error, and the call has no effect. cm_switch may be used both to switch connections that are not waiting for a response from the CM and those that are.
cm_callback, cm_switch, cm_kill
Switches connections between servers.
CS_RETCODE cm_switch(cm, pool_name, src_server, spid, dst_server, grace_period, force) cm_t *cm; CS_CHAR *pool_name; CS_CHAR *src_server; CS_INT spid; CS_CHAR *dst_server; CS_INT grace_period; CS_BOOL force;
A pointer to a CM control structure.
Switches all connections established through pool_name to the server specified by dst_server. If this parameter is NULL, all pools are assumed.
Switches all connections currently established to the remote server src_server to dst_server. If this parameter is NULL, all servers are assumed.
Switches the named OpenSwitch spid to the remote server dst_server.
If you specify a spid value of -1 or NULL and do not specify any value for pool_name or src_server, OpenSwitch switches all connections to dst_server.
If specify a value for pool_name, src_server, or both parameters, OpenSwitch switches the connection between servers after it verifies that the values you specify in the pool_name and src_server parameters exactly match the names of the pool and server that connect to the spid you specify.
If you specify values for pool_name, src_server, or both parameters, and there is no exact match between the actual pool name and server name and the pool_name and src_server parameters you specify, OpenSwitch does not switch the connection.
The name of the remote server to which all connections identified by pool_name, src_server, and spid should be switched. If this parameter is NULL, or has a blank value, the connections are switched to the next server as identified by their associated pool.
The maximum number of seconds that rp_switch should wait before forcefully switching busy connections. A value of 0 (seconds) indicates that no grace period is to be granted.
whether to force connections to switch, even if they are currently busy (either actively communicating with a remote server, or in the middle of an open transaction). Values are:
CS_TRUE – to force connection switching.
CS_FALSE – to not force connection switching.
cm_switch returns these values:
Return value |
Meaning |
|---|---|
|
The routine completed successfully. |
|
The routine failed. |
if (cm_switch( cm, NULL, "SYB_ASE1", -1,
"SYB_ASE2", 0, 1)
!= CS_SUCCEED)
{
cm_error(
"Can't switch from SYB_ASE1 to SYB_ASE2\n" );
return CS_FAIL;
}
cm_switch uses the OpenSwitch registered procedure rp_switch. For details, see the OpenSwitch Administration Guide.
A call to cm_switch causes a switch request to be issued to all connections matching pool_name, src_server, or spid. The switch request is processed by each connection under these conditions:
If the connection is completely idle (is not communicating with a remote server and is not involved in an open transaction), the connection is silently switched immediately
If the connection is busy (either communicating with a remote server or involved in an open transaction), grace_period is 0, and force is 0, the connection switches as soon as it becomes idle.
If the connection is busy, grace_period is a positive value, and force is 0, the connection switches as soon as it becomes idle. Otherwise, if grace_period seconds pass before it becomes idle, its current query is canceled, and a “deadlock” message is issued to the client. The connection is then switched.
If the connection is busy and force is 1, the connection immediately has its query canceled, and receives a “deadlock” message. The connection is then switched.
The validity of dst_server is not checked. Passing an invalid value, for example, an Adaptive Server name that does not exist, causes all incoming client connections to be lost. Use caution when specifying this parameter.
dst_server does not need to be a server within the pool of a given connection, or a server within any pool. It must be a valid server.
If force is 1, then grace_period must be zero (0), because grace_period does not make sense in this context.
A switch request issued to a connection that is blocked due to either a call to cm_stop, a locked pool, or a locked server is processed as soon as the connection becomes unblocked. Forcing a switch has no effect on a blocked connection until it becomes unblocked.
