# hp Reliable Transaction Router
System Manager's Manual

Previous | Contents | Index

# SET PARTITION

> The SET PARTITION command sets various partition-related options.

## Format

> SET PARTITION partition-name

Command Qualifiers | Defaults
--- | ---
/FACILITY[=facility_name] | /FACILITY=RTR$DEFAULT_FACILITY
/FAILOVER_POLICY= | None
(SHADOW|STAND_BY) |
/IGNORE_RECOVERY | /NOIGNORE_RECOVERY
/PRIORITY_LIST= | None
(BE-node1,BE-node2,...) |
/RECOVERY_RETRY_COUNT=n | No limit
/RESTART_RECOVERY | None
/RESUME | None
/SHADOW | /NOSHADOW
/SUSPEND | None
/TIMEOUT=nn | None (nn in seconds)

## 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

# SET TRANSACTION

> The SET TRANSACTION command sets various transaction-related options.

## Format

> SET TRANSACTION [transaction-id]

Command Qualifiers | Defaults
--- | ---
/BEFORE[=date] | Today
/FACILITY=facility_name | /FACILITY=RTR$DEFAULT_FACILITY
/NEW_STATE=new_state | None
/NODE[=node_list] | /NODE=default_node
/OUTPUT[=filespec] | /OUTPUT=stdout
/PARTITION=partition_name | None
/SINCE[=date] | Today
/STATE=current_state | None
/USER=username | All users

## 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.

# SHOW CHANNEL

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

## Format

> SHOW CHANNEL [channel-name]

Command Qualifiers | Defaults
--- | ---
/ALL_WINDOWS | /NOALL_WINDOWS
/CLUSTER | /NOCLUSTER
/NODE[=node-list] | /NODE=default-node
/OUTPUT[=filespec] | /OUTPUT=stdout

## 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).

# SHOW CLIENT

> The SHOW CLIENT command displays information about client channels.

## Format

> SHOW CLIENT

Command Qualifiers | Defaults
--- | ---
/CLUSTER | /NOCLUSTER
/FACILITY[=facility_name] | /FACILITY="*"
/FULL | None
/IDENTIFICATION=process-id | /NOIDENTIFICATION
/NODE[=node-list] | /NODE=default-node
/OUTPUT[=filespec] | /OUTPUT=stdout

## 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