# hp Reliable Transaction Router
System Manager's Manual

Previous | Contents | Index

# CLEAR

> The CLEAR command interactively removes one or more displayed items from a monitor picture.

## Format

> CLEAR /qualifier

Command Qualifiers | Defaults
--- | ---
/ALL | /NOALL
/X[=column] | Column of previous item
/Y[=row] | Next free row

## Description

> The CLEAR command enables you to interactively remove one or all of the displayed items from a monitor picture. The picture can then be redisplayed using the MONITOR/RESUME command. See Chapter 7, RTR Monitoring, for a full discussion of monitor pictures.

> Either `/ALL` , or `/X` and `/Y` must be given.

## Qualifiers

> ### /ALL

> ### /NOALL (D)

> Removes all items from the monitor picture. This is usually used when starting the interactive definition of a new picture.

> ### /X=column

> ### /Y=row

> Specify that the item in position ( `column` , `row` ) is to be removed from the monitor picture. This enables mistakes to be corrected when interactively modifying monitor pictures.

> It can also be used to remove unwanted items from predefined monitor pictures.

### Related commands

- DISPLAY BAR
- DISPLAY NUMERIC
- DISPLAY TEXT
- MONITOR
- SHOW DISPLAY

##

### Examples

> See Section A.1, Interactive Definition of a Monitor Picture, for an example of how to use the CLEAR command.

# CREATE FACILITY

> The CREATE FACILITY command creates an RTR facility and prepares it for transaction traffic.

## Format

> CREATE FACILITY [facility_name]

Command Qualifiers | Defaults
--- | ---
/ALL_ROLES=node-list | /NOALL_ROLES
/BACKEND=backend-list | /NOBACKEND
/BALANCE | /NOBALANCE
/CALL_OUT=role-list | /NOCALL_OUT
/CLUSTER | /NOCLUSTER
/FRONTEND=frontend-list | /NOFRONTEND
/NODE[=node-list] | /NODE=default-node
/OUTPUT[=filespec] | /OUTPUT=stdout
/RESOURCE_MANAGER | None
=resource-list |
/ROUTER=router-list | /NOROUTER

## Description

> The CREATE FACILITY command configures (defines on a node) an RTR facility and readies it for transaction traffic (that is, establishes links to the other participating nodes). Links may be established some time after the command executes.

> The command must be issued on all participating nodes before any application programs using the facility are started.

> Defining Roles If the local node has the frontend or backend role, all router nodes must also be defined. If the local node has the router role, all frontend and backend nodes must also be defined. If a node has multiple roles, both of the above rules apply.

> Do not create a large number of facilities with ad hoc names only for testing purposes. See the discussion in Section 3.6.7.

> Using Anonymous Clients RTR supports use of anonymous clients (clients set up using wildcarded node names), but to ensure correct node recognition, include the explicit node name of a known frontend with the wildcard when defining the configuration with a CREATE FACILITY or EXTEND FACILITY command. For example, with Node1 a router, and Node2 both frontend and backend, use the following command on the router: `CREATE FACILITY test /front=(Node2,*)/router=Node1/backend=Node2` This will ensure correct recognition of frontends by the router. The command to use on the frontend/backend would be: `CREATE FACILITY text /front=Node2 /router=Node1/backend=Node2`

## Parameters

> ### facility_name

> Specifies the name of the facility to be created.

> Any application program which uses this facility must specify the same name when it calls `rtr_open_channel()` .

> Facility names can contain up to 30 characters. Letters, numbers and underline characters are all valid, but the first character of a facility name must be a letter.

> Facility names are not case sensitive.

> Foreign Characters Not Supported for RTR Identifiers The supported character set for RTR identifiers such as facility and partition names is ASCII, with uppercase and lowercase letters being equivalent. Eight-bit characters are not supported because of interoperability requirements.

> The default value for `facility_name` is `RTR$DEFAULT_FACILITY` .

> The /ROUTER qualifier, and at least one of /FRONTEND or /BACKEND must be specified.

## Qualifiers

> ### /ALL_ROLES=node-list

> ### /NOALL_ROLES (D)

> Specifies the names of the nodes that are to act as frontend, router and backend in this facility.

> Note that the definition order of nodes may be significant. This applies to the order of router node definitions when frontend load balancing is not enabled. Nodes defined with the /ROUTER qualifier have the higher priority and are followed by nodes defined by the /ALL_ROLES qualifier. For example, in this definition:

>     $ RTR CREATE FACILITY /ALL_ROLES=mynode /ROUTER=(anode,bnode)

> The router nodes are in definition order `anode, bnode, mynode` for all frontends except `mynode` . (Any node that has both frontend and router roles selects its own router first.)

> ### /BACKEND=backend-list

> ### /NOBACKEND (D)

> Specifies the names of the nodes that are to act as backends for this facility.

> `Backend-list` is a list of `backend-nodes` separated by commas. If there is more than one `backend-node` , `backend-list` must be enclosed in parentheses.

> `Backend-node` is either the name of a node or `@filespec` , where `filespec` specifies a text file containing a `backend-list` on each line.

> ### /BALANCE

> ### /NOBALANCE (D)

> Specifies that load balancing is enabled for the frontend of the transaction router listed with /ROUTER. See Section 2.8, Router Load Balancing and Flow Control, for details on load balancing.

> It has no significance on a backend node, and is ignored if specified.

> The default behavior (/NOBALANCE) is for a frontend to connect to the preferred router. Preferred routers are selected in the order specified in the /ROUTER qualifier of the CREATE FACILITY command. This preference is subject to the router being available and quorate. Execute this qualifier on the frontend specifying the routers from which the frontend is to randomly select.

> ### /CALL_OUT[=role-list]

> ### /NOCALL_OUT (D)

> Specifies which node roles are to have callout servers running on them.

> `Role-list` is a list of `roles` separated by commas. If `role-list` contains more than one `role` it must be enclosed in parentheses.

> `Role` is one of the keywords `ROUTER` or `BACKEND` .

> The default for `role-list` is `(ROUTER,BACKEND)` .

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

> ### /FRONTEND=frontend-list

> ### /NOFRONTEND (D)

> `Frontend-list` is a list of `frontend-nodes` separated by commas. If there is more than one `frontend-node` , `frontend-list` must be enclosed in parentheses.

> `Frontend-node` is either the name of a node or `@filespec` , where `filespec` specifies a text file containing a `frontend-list` on each line.

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

> ### /RESOURCE_MANAGER=resource-list

> Specifies a list of defined resource managers that this facility may reference. Server applications using this facility and resource manager will receive any recovered transactions when the facility is created. See Appendix C for further information.

> ### /ROUTER=router-list

> ### /NOROUTER (D)

> Specifies the names of the nodes that act as routers for this facility.

> `Router-list` is a list of `router-nodes` separated by commas. If there is more than one `router-node` , `router-list` must be enclosed in parentheses.

> If /NOBALANCE is specified with the CREATE FACILITY command, the order in which router nodes are specified with the /ROUTER qualifier defines the preferred routing order.

> `Router-node` is either the name of a node or `@filespec` , where `filespec` specifies a text file containing a `router-list` on each line.

### Related commands

- DELETE FACILITY
- EXTEND FACILITY
- SHOW FACILITY
- TRIM FACILITY

# CREATE JOURNAL

> The CREATE JOURNAL command creates the RTR recovery journal.

## Format

> CREATE JOURNAL [disk-1] ... [,disk-n]

Command Qualifiers | Defaults
--- | ---
/BLOCKS=nr-blocks | /BLOCKS=1000
/CLUSTER | /NOCLUSTER
/MAXIMUM_BLOCKS=nr-blocks | /MAXIMUM_BLOCKS=1000
/NODE[=node-list] | /NODE=default-node
/OUTPUT[=filespec] | /OUTPUT=stdout
/SUPERSEDE | /NOSUPERSEDE

## Description

> The CREATE JOURNAL command creates RTR's recovery journal files on the specified disks. The target or minimum size of the files is specified using the /BLOCKS qualifier (512-byte blocks). The RTR journaling system extends the journal up to /MAXIMUM_BLOCKS as needed, or trims the journal to /BLOCKS to keep the journal file to this size. Specifying large block values can cause the command to take a long time to complete.

> The /MAXIMUM_BLOCKS qualifier specifies the maximum size that the journal file can extend to; the RTR journaling system will not extend the journal file beyond this size. If the journal file grows to the maximum size specified, RTR processing stops because transactions cannot be safeguarded if they cannot be written to the journal file.

> /BLOCKS and /MAXIMUM_BLOCKS are positional qualifiers, so the journal files need not have the same size on each disk.

> The CREATE JOURNAL command checks that a journal does not already exist for the node. An error occurs if a journal does exist, unless the /SUPERSEDE qualifier is specified.

> When the /SUPERSEDE qualifier is specified, any previously existing journal files are deleted. For this reason the CREATE JOURNAL/SUPERSEDE command should not be issued on a node being started up after a failure if the transactions interrupted by the failure need to be recovered. The CREATE JOURNAL command is often entered automatically from a startup command procedure.

> RTR only uses journal files on nodes that are configured to run servers, that is, on backends and on routers with callout servers.

## Parameters

> ### disk-1, ... disk-n

> Specifies a list of disk names where the new journal is to reside.

> If no disks are specified, the issuer's current default disk is used.

> Spreading the journal over more than one physical disk can improve performance if I/O to the journal file becomes a bottleneck.

> Table 8-20 Platform-Specific Information
> Platform | Journal Root | Finding Disks | Notes
> --- | --- | --- | ---
> UNIX | /rtrjnl | Use `df` | Enter disk names as thay appear in `/dev` . Enclose disk names in quotes and separate names with commas. The journals reside in subdirectories of the `/rtrjnl` .
> OpenVMS | [RTRJNL] | Use SHOW DEVICE. | If the SYSTEM account has insufficient disk quota for journal file creation, you must have the EXQUOTA privilege for the command to complete successfully.
> Windows | rtrjnl | Use the Desktop. | On shared SCSI disks in a Microsoft Cluster Server Environment, the cluster nodenames and disk names must be all uppercase, for example, //CLUSTERNODENAME/DISKNAME.

## Qualifiers

> ### /BLOCKS[=nr-blocks]

> ### /BLOCKS=1000 (D)

> Specifies the target size of the journal file in 512-byte blocks. This qualifier can be applied locally to each disk or globally for all disks. The maximum number of blocks that can be specified is 524287 blocks on a single disk.

> ### /MAXIMUM_BLOCKS[=nr-blocks]

> ### /MAXIMUM_BLOCKS=1000 (D)

> Specifies the maximum size that the journal file can use, up to 524287 blocks on each disk. This qualifier can be applied locally to each disk or globally for all disks.

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

> ### /SUPERSEDE

> ### /NOSUPERSEDE (D)

> Specifies how to handle the case where a journal already exists.

> If /SUPERSEDE is specified, a journal is created whether or not a journal previously existed (unless the previously existing journal is currently in use). The previous contents of the journal, if any, are destroyed.

> If /NOSUPERSEDE is specified (default), a journal is created only if no journal previously existed.

### Related commands

- DELETE JOURNAL
- MODIFY JOURNAL
- SHOW JOURNAL

## Examples

     RTR> CREATE JOURNAL /SUPERSEDE DISK1$:/BLOCK=1000/MAXIMUM_BLOCK=10000, -
     _RTR> DISK2$:/BLOCK=2000/MAXIMUM_BLOCK=200000

> This command deletes any existing journal files and then creates new ones on DISK1$ and DISK2$. The target sizes of the journal files are 1000 and 2000 blocks, and the maximum sizes are 10,000 and 200,000 blocks respectively.

     RTR> CREATE JOURNAL "/dev/rz3a", "/dev/rz2c" /BLOCK=1000 /MAXIMUM_BLOCK=2000

> This command creates journal files on `/dev/rz3a` and `/dev/rz2c` . The target sizes of the journal files is 1000 blocks and the maximum size of the journal on `/dev/rz2c` is 2000 blocks.

# CREATE PARTITION

> The CREATE PARTITION command creates an RTR partition.

## Format

> CREATE PARTITION [partition_name]

Command Qualifiers | Defaults
--- | ---
/CLUSTER | /NOCLUSTER
/CONCURRENT | /NOCONCURRENT
/FACILITY=facility-name | /FACILITY=RTR$DEFAULT_FACILITY
/KEYn=keysegdesc | See description
/NODE[=node-list] | /NODE=default-node
/OUTPUT[=filespec] | /OUTPUT=stdout
/RESOURCE_MANAGER=rmname | None
/SHADOW | /NOSHADOW
/STANDBY | /STANDBY

## Description

> The CREATE PARTITION command defines an RTR partition. The partition characteristics that may be defined include key range or ranges and whether attached server processes can be shadows or standbys.

> The command must be issued before any server application programs using the partition are started.

## Parameters

> ### partition_name

> Specifies the name of the partition to be created. Partition names must be unique within a facility.

> Any application program which uses this partition must specify the same name when it calls `rtr_open_channel()` .

> Partition names can contain up to 63 characters. Letters, numbers and underline characters are all valid. The first character of a partition name can be a letter or a number.

> If a partition name already exists in the facility, the command fails.

> The default value for `partition_name` is RTR$DEFAULT_PARTITION.

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

> ### /CONCURRENT (D)

> ### /NOCONCURRENT

> Specifies that concurrent servers are allowed for this partition.

> ### /FACILITY

> Specifies the name of the facility in which the partition is being created.

> ### /KEYn=keysegdesc

> Specifies a partition key segment. Up to 9 key segments may be defined for a partition (KEY1, KEY2,... up to KEY9). If more than 9 key segments are required, a named partition can be created using the `rtr_open_channel()` call.

> The syntax of the KEYn qualifier is:

>             /KEYn=  (type_of_key=[signed|unsigned|string], -
>                      length_of_key=nnnn, -
>                      offset_of_key=nnnn, -
>                      low_bound=[string|nnnn] -
>                      high_bound=[string|nnnn]

> `type_of_key=` Specifies the field type of the key. The `key-type` must be one of `unsigned` , `signed` or `string` . The default is `unsigned` .

> `length_of_key=nnnn` Specifies the length of the key field in enqueued messages in bytes. For signed or unsigned ints, length may be either 1, 2, 4 or 8 bytes. The default value for `key-length` is 4 bytes.

> `offset_of_key=nnnn` Specifies the offset of the key within the messages in bytes. The default is zero, that is, the key is at the start of the messages.

> `low_bound=` Specifies the lower bound of the key range that servers in the partition will service. The interpretation of `low-bound` depends on the key type; if the key is of type string, it is interpreted as text, otherwise it is interpreted as a numeric value. The default for `low-bound` is the smallest possible value that can fit in the specified key type.

> If the key bound value length is less than the key length (given in `length_of_key` ), the key bound will automatically be null-padded to the required length.

> `high_bound=` Specifies the upper bound of the key range that servers in the partition will service. The interpretation of `high-bound` depends on the key type. If the key is of type string, it is interpreted as text, otherwise it is interpreted as a numeric value. The default for `high-bound` is the largest possible value that can fit in the specified key type.

> If the key bound value length is less than the key length (given in `length_of_key` ), the key bound will automatically be null-padded to the required length.

> If the specified key range overlaps that of an existing partition in the facility, or if the key segment description conflicts with an existing definition, the command fails.

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

> ### /RESOURCE_MANAGER

> Specifies that the partition will be managed by an underlying resource manager, `rmname` , via the XA protocol.

> When you specify the XA-managed attribute for a partition at the command line, the attribute remains until the partition goes away. A partition can be managed by only one resource manager. When creating a new partition, do not use an existing resource manager name unless the partition previously using the resource manager name has been deleted.

> ### /SHADOW

> ### /NOSHADOW (D)

> Specifies that shadow servers are allowed for this partition.

> ### /STANDBY (D)

> ### /NOSTANDBY

> Specifies that standby servers are allowed for this partition.

### Related commands

- CREATE FACILITY
- SET PARTITION

##

### Examples

>     RTR> CREATE PARTITION myPartition/facility=myFacility/-
>     _RTR> Key1=(length=1, type=signed,low=1,high=1)/NOSTANDBY
>     %RTR-I-PRTCREATE, partition created

>     RTR> CREATE PARTITION ab/facility=ABC/NOSTANDBY/key1=(type=string,-
>     _RTR> length=2,offset=0,low="AB",high="CD")
>     %RTR-I-PRTCREATE, partition created

Previous | Next | Contents | Index