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

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

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

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

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