Manually switches user connections to an alternate Adaptive Server.
You can also use the OpenSwitch Manager to switch connections between
Adaptive Servers. See “Switching connections from Adaptive Server” for more information.
rp_switch [pool_name], [src_server], [spid], [dst_server], [grace_period], [force]
All connections established through the pool_name you specify are switched to the server specified by dst_server. If you do not supply this parameter, or specify NULL, all pools are assumed.
All the connections that are currently established to this remote server (src_server) switch to the dst_server. If you do not supply this parameter, or specify NULL, all servers are assumed.
The OpenSwitch spid to be switched to the remote server dst_server. If you do not supply this parameter, or specify NULL, all spids are assumed.
The remote server to which all connections identified by pool_name, srv_server, and spid should be switched. If you do not supply this parameter, or specify NULL or “”, the connections are switched to the first available server as identified by their associated pool.
Use care when specifying this parameter. No verification is performed for dst_server. Passing an invalid value causes all incoming client connections to be lost.
The maximum number of seconds to wait before forcefully switching busy connections. A value of 0 indicates that no grace period is to be enforced.
If passed with a value of 1, all connections are forcefully switched, even if they are currently busy (either actively in the middle of communicating with a remote server, or in the middle of an open transaction). If you do not supply a value, or specify NULL, the value defaults to 0.
Causes OpenSwitch spid number 8 to be switched to the remote server SYB_SERV1. If the spid does not successfully switch in 60 seconds, its current query is canceled and the client receives a “deadlock” message, and the connection is then switched.
rp_switch NULL, NULL, 8, "SYB_SERV1", 60, 0
Switches all connections established through POOL_A to SYB_SERV1 immediately. Any busy connections receive a “deadlock” message and the current query is canceled.
rp_switch "POOL_A", NULL, NULL, "SYB_SERV1", 0, 1
Switches all connections to SYB_SERV1, established through POOL_A to SYB_SERV2, within 60 seconds.
rp_switch "POOL_A", "SYB_SERV1", NULL, "SYB_SERV2", 60, 0
Switches all connections in POOL_A to the next available server (as defined by the mode of the pool) within 60 seconds.
rp_switch "POOL_A", NULL, NULL, NULL, 60, 0
Switches all existing connections to OpenSwitch to the next available server within the pool associated with each connection. There is no limit on how long the switching process is to take.
rp_switch
A call to rp_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 the following conditions:
If the connection is completely idle, it is switched immediately.
If the connection is busy (either communicating with a remote server or involved in an open transaction) and grace_period is zero (0) and force is zero (0), the connection switches as soon as it becomes idle.
If the connection is busy, and grace_period is a positive value and force is 0, the connection switches as soon as it becomes idle, or if the number of seconds specified in grace_period pass before it becomes idle, the current query is canceled, and a “deadlock” message is issued to the client, and then its connection is switched.
If the connection is busy and force has a value of 1, the connection immediately cancels its query, receives a “deadlock” message, then switches the connection.
Use caution when specifying the dst_server parameter. No verification is performed for this parameter. The administrator must verify that the dst_server is UP and that its entry exists in the sql.ini (Windows) or interfaces (UNIX) file before executing rp_switch to switch connections to it.
If the dst_server being passed to does not exist, is not running, or cannot be connected to, all the switched connections, as well as the incoming client connections are lost.
dst_server does not need to be a server within the pool of a given connection, or even a server within any pool. It simply must be a valid server.
If force is 1, then grace_period must be 0, since 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 rp_stop, a LOCKED pool, or a LOCKED src_server is processed as soon as the connection becomes unblocked. Existing connections that are not blocked are switched immediately to the next available server, or the dst_server if it is specified.
The user performing the switch cannot do so while passing through OpenSwitch. The switch does not complete because the connection is not idle.
An invalid value was supplied for the force parameter:
rp_switch: @force must be 0 or 1
Valid values are 0 and 1.
A nonzero value was supplied for grace_period, and a value of 1 was supplied for the force parameter:
rp_switch: @grace_period must be 0 when @force is 1.
The supplied pool_name does not exist:
rp_switch: Invalid pool name 'pool_name'.
Use rp_pool_help to list valid pools.
The supplied server name is not known among the existing remote servers:
rp_switch: Invalid source server name 'src_server'.
Use rp_server_status to list valid servers.
The procedure ran normally, and n spids have been requested to switch:
rp_switch: Queued switch request for n spids.
