The SET PARTITION command sets various partition-related options.

Format

SET PARTITION partition-name

Description

The SET PARTITION command sets the characteristics of a named partition. Only backend partitions may be manipulated with this command; the command must be entered on the backend where the partition is located.

Use SET PARTITION any time after the partition has been created (either explicitly by CREATE PARTITION or implicitly by starting a server.) Note that the command only takes effect after the first server joins a partition. Any errors encountered at that time will appear as RTR log file entries. Using SET PARTITION to change the state of the system results in a log file entry.

See Chapter 3, Partition Management for a more detailed description of situations where the SET PARTITION command might be used and see Section 2.15, Assignment of Processing States for Partitions for information on how RTR establishes partition states.

Parameters

partition-name

The name of the partition being manipulated. This can be specified as partition_name (if the partition name is unique on the node), or as facility_name:partition_name .

Qualifiers

/FACILITY=facility_name (D)

Determines the facility that the partition command will act on. This is required.

/FAILOVER_POLICY=SHADOW

/FAILOVER_POLICY=STAND_BY (D)

Determines the action to take when the primary partition fails. This qualifier lets the system manager decide which site to make active when the current primary site is lost. The administrator can select failover to a standby or to a remote shadow site.

The default action is to allow a standby of the primary to become the new primary. Optionally, RTR can be set to change state so that the secondary becomes primary, and a standby of the old primary (if any) becomes the new secondary.

If the /FAILOVER qualifier is used once on any backend, it affects all other partition instances with the same key range.

/IGNORE_RECOVERY

/NOIGNORE_RECOVERY (D)

Forces the partition to exit any current wait state it may be in.

If a partition should enter a wait state or fail because of the unavailability of either a local or remote journal, use this command to override the default RTR behavior. It instructs RTR to skip the current step in the recovery process. Since this command bypasses parts of the recovery cycle, use it with caution, and only when availability is more important than consistency in your application databases.

This qualifier applies only to the backend on which the command is entered.

/PRIORITY_LIST=(BE-node1,BE-node2,...)

Sets a relative priority that is used by RTR when selecting a backend member to make active. Enter a list of the backends in your configuration in decreasing order of priority; the relative order of the list will be taken into consideration when RTR is determining on which node to make a partition active. This qualifier applies only to the backend on which the command is entered, and should be entered in the same form on all backends.

It is not an error to enter different versions of the priority list at different backends, but this is not recommended. You should suspend partitions before changing the priority list.

/RECOVERY_RETRY_COUNT=n

If an application server dies while processing a transaction recovered from the journal, RTR will present the transaction to another (concurrent or standby) server. The RECOVERY_RETRY_COUNT indicates the maximum number of times the transaction is presented to a server for recovery before being written to the journal as an exception.

There are two types of recovery operations where transactions are recovered from the journal: local recovery and shadow recovery. Shadow recovery is the process of recovering the remembered transactions written to a primary shadow journal while the secondary shadow site is down.

The SET PARTITION /RECOVERY_RETRY_COUNT parameter does not have any effect on remembered transactions recovered during shadow recovery. That is, if there is a killer transaction remembered in the journal on a primary shadow node, on this node RTR does not count the number of times the transaction is recovered by a recovering secondary shadow node. The way to ensure that a remembered transaction will be exceptioned by RTR is by starting a sufficient number of concurrent servers on the recovering secondary shadow node.

For this reason, the number of concurrent secondary shadow servers started should be greater than the value set for the RECOVERY_RETRY_COUNT on a partition. This will ensure that a remembered (killer) transaction being recovered from a primary shadow journal will be exceptioned if the retry limit is exceeded.

Note that only those transactions that have reached voting stage on a server can be exceptioned. If a server always dies before voting on a transaction, the transaction will be aborted by RTR after the third try. This is a hard-coded limit (the so-called "three strikes and you're out" feature).

/RESTART_RECOVERY

Restarts the recovery cycle. The recovery cycle can be manually restarted with /RESTART. This is useful if the operator previously aborted recovery through use of /IGNORE_RECOVERY. Since this command may result in recovery of transactions from previously inaccessible journals, it should not be used if your applications are sensitive to the order in which transactions are processed by the servers. This qualifier applies only to the backend on which the command is entered.

/RESUME

Resume normal operations (that is, cancel a /SUSPEND command). If the partition is already in the desired state, the command has no effect. This qualifier applies only to the backend on which the command is entered.

/SHADOW

/NOSHADOW (D)

Turns shadowing on or off for the specified partition.

Shadowing for a partition can be turned off only in the absence of an active secondary site, that is, the active member must be running in remember mode. The command will fail if it is entered on either an active primary or secondary. Once shadowing is disabled, the secondary site servers will be unable to start up in shadow mode until shadowing is enabled again.

Shadowing for the partition can be turned on by entering the command at the current active member.

If the /SHADOW qualifier is used once on any backend, it affects all other partition instances with the same key range.

If shadowing is already in the desired mode, the command has no effect.

Note If the SET PARTITION/NOSHADOW command is used on a remembered partition, the operator must take action regarding the remembered transactions in the journal: Either leave them in place pending restoration of future shadow operation or delete them with the SET TRANSACTION command.

/SUSPEND

Stops presenting new transactions on the specified partition until a /RESUME is issued.

Use /SUSPEND to temporarily halt the presentation of new transactions to servers on the backend where the command is entered. The command completes when the processing of all currently active transactions is complete. This qualifier applies only to the backend on which the command is entered.

The optional /TIMEOUT qualifier may be used to limit the time in seconds that the command waits for completion. If the command times out, presentation of new transactions is suspended, but there still exist transactions for which servers have yet to complete processing. The operator must decide to either reenter the command and wait a longer period of time, or resume the partition. Using this command does not affect any transaction timeout value specified by RTR clients, so such transactions may encounter a timeout condition if the partition remains suspended.

If the command times out (cannot be completed within the specified timeout period), transaction presentation remains set to active.

/TIMEOUT

See description for /SUSPEND.

Related commands

• CREATE PARTITION
• SHOW PARTITION

The SET TRANSACTION command sets various transaction-related options.

Format

SET TRANSACTION [transaction-id]

Description

The SET TRANSACTION command allows you to modify the state of a transaction or set of transactions stored in the RTR journal.

Caution The SET TRANSACTION command could damage your journal and compromise database integrity if used incorrectly. Ensure that you fully understand the reason and impact for changing a transaction state before altering your RTR system.

This command is complementary to the DUMP JOURNAL and SHOW TRANSACTION commands in that it gives capability of reading and modifying the status of a transaction status in the RTR journal. For example, if a shadow recovery is known to be unnecessary, you may want to clean up the RTR journal to prevent the committed transactions in the journal from being replayed. Using the SET TRANSACTION command, the RTR administrator is able to delete that set of transactions from the journal.

In addition, the SET TRANSACTION command also helps users to better control the RTR runtime environment in difficult operational situations. For example, a transaction that is still in SENDING state on the backend may appear to be hung and cannot proceed. Using the SET TRANSACTION command, an RTR administrator can abort this transaction "on-the-fly" and free runtime resources.

While the SET TRANSACTION command enables RTR users to have full control of RTR transactions, it introduces the risk that a transaction could be lost or corrupted. The command must be used with discretion and only by experienced RTR system administrators.

After the SET TRANSACTION command completes, you may use the DUMP JOURNAL command to verify the results.

Refer to Chapter 4, Transaction Management, for more information about transaction management and the SET TRANSACTION command.

Usage Notes

The command can only be executed on a backend node on which the journal is located and the RTR log file must be turned on to record the transaction changes. RTR needs to be started before using this command.

When you modify a transaction's state, you must specify the qualifier /PARTITION in addition to the required qualifiers /STATE and /NEW_STATE. Specifying this information ensures that RTR locates the specific transaction branch.

When a transaction's state is changed, the new state is written to the RTR journal synchronously. RTR will try to determine whether the change also affects other portions of the RTR environment. For example, in a runtime situation where RTR routers and RTR backend servers are active, the RTRACP will send the new status to application servers as well as RTR routers to make sure that the change takes effect on all nodes in the RTR facility or facilities.

However, in an off-line situation where an RTR facility has not been created, RTR will simply update the transaction state in place in the RTR journal. The RTR log file must be turned on before using the SET TRANSACTION command to record the state changes. See the SET LOG command.

There are eight legitimate situations where you can change a transaction's state. See Table 8-22.

Parameters

transaction-id

Specifies a particular transaction or transactions whose transaction state you want to change. The transaction_id format is the same as that displayed by the DUMP JOURNAL and SHOW TRANSACTION commands.

If no transaction_id is specified, all transactions (*) that satisfy the specifying qualifiers are processed by the command.

Qualifiers

/BEFORE[=date]

Selects only those transactions whose timestamp is before the specified date. Default is the current date.

/FACILITY

/FACILITY=RTR$DEFAULT_FACILITY (D)

Specifies the name of a facility for selecting transactions. The default facility, RTR$DEFAULT_FACILITY, is used if this qualifier is not specified.

/NEW_STATE

Specifies the new transaction state that selected transactions will be changed to. This qualifier is required and new state value must be specified.

Value of new_state may be one of the following:

ABORT
COMMIT
DONE
EXCEPTION

Note that one cannot always change a transaction's state from one legitimate transaction state to another. Some state changes are not valid. The following table shows state changes that are valid.

Table 8-22 Valid Transaction State Changes

		NEW STATE
Current State	COMMIT	ABORT	EXCEPTION	DONE
SENDING		YES
VOTED	YES	YES
COMMIT			YES	YES
EXCEPTION	YES			YES
PRI_DONE				YES

/NODE[=node-list]

/NODE=default-node (D)

Specifies that the command is executed on all nodes specified in node-list . If node-list is omitted, the command is executed only on the node where the command was issued.

/OUTPUT[=filespec]

/OUTPUT=stdout (D)

Specifies that the resulting information is written to the file filespec . If /OUTPUT or filespec is omitted, the standard or default output is used.

/PARTITION

/PARTITION=partition_name

Specifies the name of a partition within which all transactions are running. A partition name must be supplied.

Use SHOW PARTITION to view the names of the currently active partitions.

/SINCE[=date]

Selects only those transactions whose timestamp is after the specified date. Default is the current date.

/STATE=current_state

Selects a particular transaction or a set of transactions that are in the specified current_state transaction state. This qualifier is required and the current_state value must be specified.

Value of current_state may be one of the following:

SENDING
VOTED
COMMIT
EXCEPTION
PRI_DONE

Use the SHOW TRANSACTION command to help you find what is the current state of a particular transaction.

/USER[=user-id]

/USER=all users (D)

Allows you to select transactions that were initiated by a client process.

If /USER is not specified, transactions for all users are affected.

Related commands

• SHOW TRANSACTION
• DUMP JOURNAL

Examples

 RTR> SET TRANSACTION "50d01f10,0,0,0,0,2166,522b2001" -
 _RTR> /NEW=ABORT /STATE=SENDING /PART=DB_PART
      

Abort this specified transaction running in the DB_PART partition.

 RTR> SET TRANSACTION /NEW=ABORT /STATE=VOTED /PART=DB_PART
      

Abort all transactions that are in VOTED transaction state and are running in DB_PART partition, in the RTR$DEFAULT-FACILITY facility.

For more examples, refer to Chapter 4, Transaction Management.

The SHOW CHANNEL command shows the names and state of channels that have been opened using the CLI API.

Format

SHOW CHANNEL [channel-name]

Description

The SHOW CHANNEL command shows the channel type (client or server), the channel name and owner process-id for channels opened using the CLI API.

Parameters

channel-name

Specifies the name of the channel to be displayed. channel-name can contain wildcards. If channel-name is omitted, all declared channels for this window (terminal or virtual terminal) are displayed.

Qualifiers

/ALL_WINDOWS

/NOALL_WINDOWS

Specifies that channels opened in all windows (terminals or virtual terminals) are shown.

/CLUSTER

/NOCLUSTER (D)

Specifies that the command is executed on all the nodes in the cluster.

If neither /NODE nor /CLUSTER is specified, the command is executed on the nodes specified by the latest SET ENVIRONMENT command. If no SET ENVIRONMENT command has been entered, the command is executed only on the node where the command was issued.

Note In environments that do not support remote command capability, the /CLUSTER qualifier causes the relevant command to be executed on the local node only. See Section 1.4 for more information.

/NODE[=node-list]

/NODE=default-node (D)

Specifies that the command is executed on all nodes specified in node-list . If node-list is omitted, the command is executed only on the node where the command was issued.

/OUTPUT[=filespec]

/OUTPUT=stdout (D)

Specifies that the resulting information is written to the file filespec . If /OUTPUT or filespec is omitted, the standard or default output is used.

Related commands

• CALL RTR_OPEN_CHANNEL
• CALL RTR_CLOSE_CHANNEL

Examples

 RTR> SHOW CHANNEL/ALL_WINDOWS  (1)
  
 Channel type Channel name                (Owner pid)   
 server         RTR$DEFAULT_CHANNEL             (28879)  (2)
 client         CLI_CHN                         (28879)  (3)
 client         CLI_CHN2                        (26225)  (4)
 
      

1. Displays information about all declared channels.
2. The channel called RTR$DEFAULT_CHANNEL is open as a server channel.
3. The channel called CLI_CHN is open as a client channel.
4. The channel called CLI_CHN2 is open as a client channel, and has been opened by another process (in another window).

The SHOW CLIENT command displays information about client channels.

Format

SHOW CLIENT

Description

The SHOW CLIENT command displays information about client channels.

Information such as PID, key range, state, event mask and event name are displayed.

Qualifiers

/CLUSTER

/NOCLUSTER (D)

Specifies that the command is executed on all the nodes in the cluster.

If neither /NODE nor /CLUSTER is specified, the command is executed on the nodes specified by the latest SET ENVIRONMENT command. If no SET ENVIRONMENT command has been entered, the command is executed only on the node where the command was issued.

Note In environments that do not support remote command capability, the /CLUSTER qualifier causes the relevant command to be executed on the local node only. See Section 1.4 for more information.

/FACILITY

/FACILITY="*" (D)

Specifies the facility name for which information should be displayed.

By default, information is displayed for all facilities.

/FULL

none (D)

Specifies a detailed listing of client information.

/IDENTIFICATION=process-id

/NOIDENTIFICATION (D)

Specifies the PID of the process for which information is displayed. The default (/NOIDENTIFICATION) displays information for all clients.

/NODE[=node-list]

/NODE=default-node (D)

Specifies that the command is executed on all nodes specified in node-list . If node-list is omitted, the command is executed only on the node where the command was issued.

/OUTPUT[=filespec]

/OUTPUT=stdout (D)

Specifies that the resulting information is written to the file filespec . If /OUTPUT or filespec is omitted, the standard or default output is used.

Examples

 RTR> SHOW CLIENT/FULL  (1)
  
 Process-id:      9234          Facility:       TEST43  (2)
 Channel:         500           Flags:             CLI  (3)
 State:           declared      rcpnam:       "V3TEST" (4)
 User Events:     255           RTR Events:          0 (5)
  
 
      

---

Previous

Next

Contents

Index