Allows you to execute operating system commands without leaving the RTR utility.

Format

SPAWN [operating-system-command]

Description

The SPAWN command allows you to execute operating system commands without leaving the RTR session. If you specify an operating system command as the parameter to SPAWN, the command is executed in the context of a spawned subprocess. For example, the command "SPAWN mail" invokes the mail utility; when you exit from mail, you return to your RTR session.

If you do not specify a parameter, the SPAWN command enters the operating system command level in the spawned subprocess. You can then enter commands; you can return to your RTR session by exiting the subprocess.

Parameters

operating-system-command

Can be any operating system command.

Qualifiers

/INPUT=file-spec

/NOINPUT (D)

Specifies an input file containing one or more shell commands to be executed by the spawned subprocess. If you specify a command and an input file (with the /INPUT qualifier), the command string is processed before the input file. Once processing of the input file is complete, the subprocess is terminated.

/OUTPUT=file-spec

/OUTPUT=stdout (D)

/NOUTPUT

Requests that the output from the SPAWN operation is written to the file-spec.

Start RTR on one or more nodes.

Format

START RTR

The following qualifiers are only relevant when running on OpenVMS.

Command Qualifiers	Defaults
/ASTLM=ast-limit	Dependent on /LINKS and /PROCESSES values
/BIOLM=io-buffered	Dependent on /LINKS and /PROCESSES values
/BYTLM=buffer-limit	/BYTLM=1,000,000
/CPULM=time-limit	/CPULM=default-time-limit
/DIOLM=io-direct	/Dependent on /LINKS and /PROCESSES values
/ENQLM=enqueue-limit	/ENQLM=2000
/FILLM=file-limit	Dependent on /LINKS and /PROCESSES values
/JTQUOTA=job-table-quota	/JTQUOTA=5000
/LINKS=max-links	/LINKS=512
/PARTITIONS=max-partitions	/PARTITIONS=80
/PGFLQUOTA=page-file	Dependent on /LINKS and /PROCESSES values
/PRCLM=subprocess-limit	/PRCLM=10
/PRIORITY=priority	/PRIORITY=6
/PROCESSES=max-processes	/PROCESSES=64
/TQELM=queue-limit	/TQELM=2000
/WSDEFAULT=working-set	/WSDEFAULT=2000
/WSEXTENT=extent	/WSEXTENT=20000
/WSQUOTA=max-working-set	/WSQUOTA=10000

Description

The START RTR command starts RTR on one or more nodes.

When RTR is started on a node, a detached process called the RTR ACP is created. This process performs transaction and communication activities for all users of RTR running on that node.

The START RTR command must be issued before adding RTR facilities or starting application programs that use RTR.

When running on OpenVMS, the quota qualifiers affect the way the RTR ACP is created. The default values will suffice for many applications. The values for quota qualifiers take effect independently of SYSGEN settings. This means that RTR can be started with different quotas without rebooting the system. The quota qualifiers are similar to those which can be specified with the DCL RUN/DETACHED command.

If you use obsolete RTR Version 2 qualifers with the START RTR command, a warning is issued. Qualifers affected are partitions, cache_pages, and relations. Warnings are also generated if an OpenVMS qualifer is used on a non-OpenVMS platform.

Qualifiers

/ASTLM=ast-limit

/ASTLM=(max-links + max-processes) x 2 + 10 = default ast-limit (D)

Specifies the AST limit for the RTR ACP.

The value for ast-limit must include five for RTR ACP mailbox reads and timer scheduling and a minimum of two per DECNET logical link maintained by RTR.

For example, in a 20-node configuration, a router node needs an ASTLM of at least 45 ( 5 + (20 x 2) ).

In systems where a lot of traffic is expected, defining additional ASTLM quota will enable lookahead I/O to be booked to channels without RTR ACP being held up in a resource wait.

The default value of ast-limit is automatically calculated, based on the value of /LINKS and /PROCESSES.

/BIOLM=io-buffered

/BIOLM=(max-links + max-processes) x 2 + 10 = default io-buffered (D)

Specifies the maximum number of system-buffered I/O operations that the RTR ACP can have outstanding at any one time.

The default value of io-buffered is automatically calculated, based on /LINKS and /PROCESSES values.

/BYTLM=buffer-limit

/BYTLM=1,000,000 (D)

Specifies the maximum amount of memory, in bytes, that the RTR ACP can use for buffered I/O operations or temporary mailbox creation.

This should be sufficiently large to account for lookahead DECNET traffic.

The default for buffer-limit is 1,000,000.

/CLUSTER

/NOCLUSTER (D)

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

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

Note: In environments that do not support clustering, use of the /CLUSTER qualifier will cause the relevant command to be executed on the local node only.

/CPULM=time-limit

/CPULM=default-time-limit (D)

Specifies the maximum amount of CPU time (in delta time) allocated to the RTR ACP. The unit of time-limit is ten milliseconds. When the time expires, the RTR ACP is deleted.

The default value is established at system generation time.

A time-limit limit of 0 indicates that CPU time is not restricted.

/DIOLM=io-direct

/DIOLM=(max-links + max-processes) x 2 + 10 = default io-direct (D)

Specifies the maximum number of direct I/O operations that the RTR ACP can have outstanding at any one time.

If you do not specify a direct I/O quota, the default value established at system generation time is used.

The default for io-direct is automatically calculated based on the values for /LINKS and /PROCESSES.

/ENQLM=enqueue-limit

/ENQLM=2000 (D)

Specifies the maximum number of locks that the RTR ACP can have outstanding at any one time.

The default for enqueue-limit is 2000.

/FILLM=file-limit

/FILLM=(max-links + max-processes) + 10 = default file-limit (D)

Specifies the maximum number of files that the RTR ACP can have open at any one time.

The default value of file-limit is automatically calculated, based on the values of /LINKS and /PROCESSES.

/JTQUOTA=job-table-quota

/JTQUOTA=5000 (D)

Allows you to specify a quota the job-wide logical name table for the RTR ACP.

The default for job-table-quota is 1024.

/LINKS=max-links

/LINKS=512 (D)

Specifies the maximum number of nodes with which this node can communicate. The default for max-links is 512.

/NODE[=node-list]

/NODE=default-node-list (D)

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

/OUTPUT[=file-spec]

/OUTPUT=stdout (D)

Specifies that the resulting information is written to the file file-spec. If /OUTPUT or file-spec is omitted then the standard or default output is used.

/PGFLQUOTA=page-file

/PGFLQUOTA=((max-links + max-processes) x 400) + 16000 =default pages (D)

Specifies the maximum number of pages allocated in the paging file for the RTR ACP.

The paging file quota is the amount of secondary storage available during execution of the RTR ACP image.

Note that a shortage of virtual memory may produce spurious error messages.

The default value of page-file is automatically calculated, based on the values of /LINKS and /PROCESSES.

/PRCLM=subprocess-limit

/PRCLM=10 (D)

Specifies the maximum number of subprocesses that the RTR ACP can create.

The default for subprocess-limit is 10.

/PRIORITY=priority

/PRIORITY=6 (D)

Requires alter priority (ALTPRI) privilege to set the priority higher than your current process.

Specifies the base priority at which the RTR ACP executes.

The priority value is a decimal number from 0 through 31, where 31 is the highest priority and 0 is the lowest. Normal priorities range from 0 through 15; real-time priorities range from 16 through 31.

Higher priorities result in faster response, but lower priorities may be more CPU efficient and give a higher overall throughput.

/PROCESSES=max-processes

/PROCESSES=64 (D)

Specifies the maximum number of processes that can use RTR on this node. The max-processes value is set to the maximum number of processes allowed by OpenVMS. The default is 64.

/TQELM=queue-limit

/TQELM=2000 (D)

Specifies the maximum number of timer queue entries that the RTR ACP can have outstanding at any one time. This number includes timer requests and scheduled wakeup requests.

The default for queue-limit is 2000.

/WSDEFAULT=working-set

/WSDEFAULT=2000 (D)

Specifies the default working set size for the image running in the RTR ACP.

working-set cannot be greater than the working set quota (specified with the /WSQUOTA qualifier).

The default for working-set is 2000.

/WSEXTENT=extent

/WSEXTENT=20,000 (D)

Specifies the maximum size to which the image running in the RTR ACP can increase its physical memory size.

The default for extent is 20,000.

/WSQUOTA=max-working-set

/WSQUOTA=10,000 (D)

Specifies the maximum size to which the image being executed in the RTR ACP process can increase its working set size.

The default for max-working-set is 10,000 pages.

Related Commands

• SHOW RTR
• STOP RTR

Examples

See Chapter 2, Starting and Setting Up RTR, for examples of how to use the START RTR command.

Stop RTR on one or more nodes.

Format

STOP RTR

Description

The STOP RTR command stops RTR in an orderly manner.

Alternatively, RTR can be stopped in an abrupt manner (/ABORT), and any applications using RTR are forced to exit.

Qualifiers

/ABORT

Specifying /ABORT causes RTR to stop, regardless of the state of any RTR user applications. Applications using RTR are forced to exit.

Note This qualifier supersedes the /NOCONFIRM of earlier versions of RTR.

/CLUSTER

/NOCLUSTER (D)

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

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

Note: In environments that do not support clustering, use of the /CLUSTER qualifier will cause the relevant command to be executed on the local node only.

/NODE[=node-list]

/NODE=default-node-list (D)

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

/OUTPUT[=file-spec]

/OUTPUT=stdout (D)

Specifies that the resulting information is written to the file file-spec. If /OUTPUT or file-spec is omitted then the standard or default output is used.

Related Commands

• SHOW RTR
• START RTR

Examples

See Chapter 2, Starting and Setting Up RTR, for examples of how to use the STOP RTR command.

Removes nodes or roles or both from an existing facility definition.

Format

TRIM FACILITY [facility_name]

Description

The TRIM FACILITY command removes nodes or roles or both from an RTR facility definition. A node can be removed from a facility or a role can be removed from a node. For example, a node having both router and frontend roles can be trimmed to have only a router role.

A TRIM FACILITY command resulting in the removal of all roles is equivalent to a DELETE FACILITY command.

A frontend role can be removed from a node with the router role as long as there is at least one other frontend defined.

A backend role can be removed from a node with the router role as long as at least one other backend is defined. A command to remove a backend role should be executed on all router nodes to avoid problems with inconsistent facility definitions.

If a router role is removed, then the node from which it is removed will discard its knowledge of other backends and frontends in the facility. If the router role is re-added to the node (using EXTEND FACILITY), this information will have to be specified again.

In order to have a consistent facility definition across the nodes of the facility (avoiding problems with attaining quorum), the command to remove a router role must be executed on all relevant nodes. This means executing the command on the node losing the router role, plus all backend and frontend nodes which know about this router.

As with CREATE or MODIFY FACILITY, nodes or roles may be specified which are superfluous. That is, you may specify backend nodes on a node which only has a frontend role, and frontend nodes may be specified on a node which only has a backend role. This permits a single RTR management command to be issued on many nodes, and each node only accepts those parts of the command which are relevant to it.

When using this command, the facility being extended may lose quorum until the affected nodes agree upon the new facility definition. During this time server applications will not be presented with any new transactions.

RTR MONITOR QUORUM displays a monitor picture which allows the quorum negotiations to be observed. You can use this after using a TRIM FACILITY command; once quorum has been re-attained, the participating nodes return to the quorate state.

For example, in a three node facility called facnam, the nodes FE and NFE have only frontend roles, and node FETRBE has frontend, router and backend roles. This facility could have been created as follows:

% RTR RTR> SET ENVIRONMENT /NODE=(FE,FETRBE,NFE) RTR> CREATE FACILITY facnam /FRONTEND=(NFE,FE,FETRBE) - /ROUTER=FETRBE - /BACKEND=FETRBE

The frontend node NFE can be removed from the facility as follows:

% RTR RTR> SET ENVIRONMENT /NODE=(FETRBE,NFE) RTR> TRIM FACILITY facnam /FRONTEND=NFE

Parameters

facility_name

Specifies the name of the facility to be trimmed.

The default value for facility_name is RTR$DEFAULT_FACILITY.

Qualifiers

/BACKEND=backend-list

/NOBACKEND (D)

Specifies the names of the nodes where backend roles for this facility are removed.

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

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

/CLUSTER

/NOCLUSTER (D)

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

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

Note: In environments that do not support clustering, use of the /CLUSTER qualifier will cause the relevant command to be executed on the local node only.

/FRONTEND=frontend-list

/NOFRONTEND (D)

Specifies the names of nodes where the frontend role is removed for this facility. frontend-list is a list of frontend-nodes separated by commas. If there is more than one frontend-node, then frontend-list must be enclosed in parentheses.

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

/NODE[=node-list]

/NODE=default-node-list (D)

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

/OUTPUT[=file-spec]

/OUTPUT=stdout (D)

Specifies that the resulting information is written to the file file-spec. If /OUTPUT or file-spec is omitted then the standard or default output is used.

/ROUTER=router-list

/NOROUTER (D)

Specifies the names of the nodes where the router role is removed for this facility.

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

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

Related Commands

• SHOW FACILITY
• DELETE FACILITY
• CREATE FACILITY
• EXTEND FACILITY

The UNREGISTER RESOURCE MANAGER command unregisters an instance of a resource manager.

Format

UNREGISTER RESOURCE MANAGER [resource_name]

UNREGISTER RM [resource_name]

Description

The UNREGISTER RESOURCE MANAGER command unregisters an instance of a resource manager. The command succeeds only when no facility references it. To unregister a resource manager instance, you must first delete all facilities that reference it. To see what facilities reference a specific resource manager, use the command SHOW RM/FULL. Refer to Appendix C, XA Support for support information about XA.

Parameters

resource_name

Specifies the name of the resource to be unregistered.

Resource names can contain up to 32 characters. This argument is required.

Related Commands

• REGISTER RESOURCE MANAGER
• SHOW RESOURCE MANAGER

Examples

UNREGISTER RM rmi_1