# hp Reliable Transaction Router
System Manager's Manual

Previous | Contents | Index

## 7.2.41 Monitor Stccalls

Displays the history of calls for a specific server transaction controller. Valid only when the application is using the C++ API.

Example 7-40 Monitor Stccalls

     ORTR Call history monitor screen on node:rtrdoc              PID : -ALL-
    Image: -ALL-                                    at 15:45:10 Mon Jul 16 2001
    STC CurrentState :                               #Of Partitions : 0

              PartitionName                                           Channel #

    Calls        Channel #s                   State    Msg/Event    Ch. used Status

## 7.2.42 Monitor Summary

Displays information about the channel, transaction, and system environment, including:

- For server channels:
  - Processes (number of processes hosting server channnels)
  - Active (number of primary active server channels)
  - Secondary active (number of secondary active server channels)
  - Standby (number of standby server channels)
  - Other (number of server channels in states not counted above)
  - All server channels (number of server channels in all states)
- For client channels:
  - Processes (number of processes hosting client channels)
  - Channels: number of client channels
- For all processes: Total processes: number of RTR application processes (clients and servers). To see separation by process, use MONITOR CHANNEL.
- For transaction counts: Active transactions (for each frontend, router, and backend role, displays counts of active transactions with node location and age (in days and clock time as dddd hh:mm::ss) of the oldest transaction)
- For RTR uptime by system: Elapsed time in days and clock time(dddd hh:mm:ss) since RTR was started on the given system

Example 7-41 Monitor Summary

    Environment Summary at 16:00:36 Sat Mar  1 2003
      on node -ALL-

    --Server channels-------     --Client channels-------

              Processes :     2         Processes :     1
                 Active :     6          Channels :     2
       Secondary active :     2
                Standby :     4
                  Other :     1
    All server channels :    13   Total processes :     2

     Active transactions

             Backend :     3       Oldest (on length    ) 0000 00:04:06
              Router :     3       Oldest (on depth     ) 0000 00:04:05
            Frontend :     3       Oldest (on depth     ) 0000 00:04:05

     RTR uptime by system

    depth                0001 02:02:33
    length               0001 02:01:56

## 7.2.43 Monitor System

Displays the state of critical resources within the RTR environment. If a resource has exceeded a predefined threshold, the picture displays a warning indicator.

Example 7-42 Monitor System

                      System Status at 10:27:51 Fri Apr  9 1999
                               node: NODEA

         Resource                OK   Warning
    Facility QUORUM states......          x
    JOURNAL free space..........  x
    Link CONNECTS...............          x
    Link traffic STALLS.........  x
    FLOW control credits........  x
    PARTITION states............  x
    CALL Msg outstanding..........        x
    Transaction QUEUES............ x
    Transaction REJECTS........... x
    Broadcast EVENT discards...... x

       For additional detail about a resource,
       monitor the appropriate subsystem. To
       customize threshold values, edit
       SYSTEM.MON. If viewing this page in a
       browser, follow the hyperlinks above.

Table 7-7 lists the default thresholds.

Table 7-7 Default Thresholds
For this Resource: | A Warning Appears When:
--- | ---
Quorum | Any roles are inquorate
Journal | Journal free space is less than 30% of total
Link Connects | Any link is disconnected
Stalls | 10 second stalls are greater than 1% of all messages sent
Flow | The wait is more than 1 second for 10% of the total credit requests
Partition | Any of the partitions are not in one of the following states: Standby, Active, Pri_act, or Sec_act
Call Msg | Any messages have been pending for more than 30 seconds
Queues | The transaction queue cannot be emptied within 10 seconds
Rejects | The number of rejects (non-user) is greater than 5% of the total transactions processed, or a reject (non-user) has occurred within the last 30 minutes
Event discards | The number of discards is greater than 5% of the total events sent

To customize threshold values, edit the file SYSTEM.MON.

## 7.2.44 Monitor Tps

Displays the transaction processing rate for processes on a specific node, with cumulative totals for all client and server processes. The display also provides a bar graph for each entry.

Example 7-43 Monitor Tps

    TRANSACTION COMMITS BY PROCESS 14:12:48 Wed Nov  3 1999 on nodeA

                                      Commits     Each # is 10tps
    Node, Process ID & name       Absolute   Rate/s   50  100  150  200  250  300
    nodeA  -ALL-    -CLIENTS-         2401   45.0   ####
    nodeA  -ALL-    -SERVERS-         2401   45.0   ####

    nodeA  22941    smith_1           2401   45.0   ####
    nodeA  22933    jones_1           2401   45.0   ####

## 7.2.45 Monitor Tpslo

Displays low end of the transaction processing rate for processes using RTR, with bar graphs. The display is intended for systems with throughput less than 10 tps.

Example 7-44 Monitor Tpslo

    TRANSACTION COMMITS BY PROCESS 14:12:48 Wed Nov  3 1999 on nodeA.zko.dec.com

                                        Commits
    Node   ID       Process           Abs.   Rate |  2   4   6   8   10
    nodeA  -ALL-    -CLIENTS-          5      2.0    ##
    nodeA  -ALL-    -SERVERS-          5      2.0    ##

    nodeA  22941    smith_1           10      4.0    ####

## 7.2.46 Monitor Traffic

Displays a list of links to other nodes. Shown for each link are: byte rate, packet rate, message rate and congestion, in both directions. Average packets per second is also shown. Uses counters in the Network I/O (NIO) subsystem.

Example 7-45 Monitor Traffic

    LINK TRAFFIC  Fri Sep 08 2000 14:38:08, NODE: -ALL-

                          Bytes/sec      Packets/sec   Messages/sec   Congestion
                        Rcvd     Sent  Rcvd  Sent  Avrg  Rcvd   Sent  Count Rate
    Total            13465.5  13213.3 123.8 121.2 239.1  53.3   53.3     35  0.0

    NODEA -> NODEA       0.0      0.0   0.0   0.0   0.0   0.0    0.0      0  0.0
    NODEA -> NODEB   10718.0   2705.8  95.1  27.5 118.9  24.9   27.2     28  0.0
    NODEB -> NODEB      41.7     41.7   1.2   1.2   1.4   1.2    1.2      0  0.0
    NODEB -> NODEA    2705.8  10465.8  27.5  92.5 118.8  27.2   24.9      7  0.0

## 7.2.47 Monitor Trans

Displays transaction state for transactions in a facility.

Example 7-46 Monitor Trans

    Monitoring transactions Wed Jan 09 2002 15:21:38, NODE: NODEA
    Transaction ID  (frontend)         Facility               FE-User      State
    46d01f10,0,0,0,0,baa09daa,abf10001 RTR$DEFAULT_FACILITY   RTRCSV_T.1   voting

    Transaction ID  (router)           Facility               FE-User      State
    46d01f10,0,0,0,0,baa09daa,abf10001 RTR$DEFAULT_FACILITY   RTRCSV_T.1   voting

    Transaction ID  (backend)          Facility               FE-User      State
    46d01f10,0,0,0,0,baa09daa,abf10001 RTR$DEFAULT_FACILITY   RTRCSV_T.1   receiving

## 7.2.48 Monitor Upstream

Displays flow-control induced traffic stalls upstream from the controlling backend, between the frontend and the router, and between the router and the backend. Upstream traffic runs towards the backend.

Example 7-47 Monitor Upstream

    FLOW CONTROL UPSTREAM STALLS BY NODE & FACILITY Mon Jul 16 2001 15:42:25, Node:

                                        Txn traffic       Bdcst traffic
                                    fe->tr     tr->be        tr->be
    Node  & Facility              reqs stall  reqs stall  reqs stall     Router used
    rtrdoc   Test                                                        rtrdoc_

## 7.2.49 Monitor V2calls

Displays calls made by applications to the Version 2.0 API.

Example 7-48 Monitor V2calls

    RTR V2 system service calls, Node: NODEA , PID: 00000000, Process name: -ALL-
    Image: -ALL-                                            13:09:18  5-MAR-1999
                       Accept    Reject   Success   Failure   Outstng     Calls
    dcl_tx_prc/server       3         0         4         0         0         4
    dcl_tx_prc/req.         1
    dcl_tx_prc/shut.        0

    start_tx                1         0         1         0         0         1
    start_tx /timeout       0

    enq_tx                  1         0     50395         0         0     50395
    enq_tx /broadcast   25187
    enq_tx /reply       25207

    deq_tx              50381         0     50391         0         2     50393
    deq_tx /reply          12

    commit_tx               1         0         1         0         0         1

    abort_tx                0         0         0         0         0         0

    vote_tx /commit     25187         0     25189         0         0     25189
    vote_tx /abort          0
    vote_tx /forget         2

## 7.2.50 Monitor XA

Displays information about XA call activity when using XA with RTR.

Example 7-49 Monitor XA

    RTR XA Calls    Node: nodea.zko       PID: -ALL-      Process name: -ALL-
    Image: -ALL-                                           11:42:06  Tue 6-Apr-1999

      XA Verb Name  Calls         Success        Readonly           Failure
      open              0               0               0                 0
      close             0               0               0                 0
      start             0               0               0                 0
      end               0               0               0                 0
      prepare           0               0               0                 0
      commit            0               0               0                 0
      rollback          0               0               0                 0
      recovery          0               0               0                 0

                         Rate   0  2  4  6  8 10 12 14 16 18 20    Active
             txn starts   0.0                                        0

# Chapter 8
RTR Commands

RTR commands can be invoked from the RTR web browser interface or with the RTR CLI. RTR C API calls can also be invoked from these interfaces to facilitate application testing. For example, client applications can be tested before the corresponding server applications have been written by manually entering the server's C API calls, and manual tests can be done between clients and servers.

RTR commands include those used in developing applications as well as commands that let you monitor and manage the operation of a production system. See Section 1.2.1 for instructions on how to start using the RTR web browser and CLI interfaces, and see the Reliable Transaction Router Getting Started manual for an example of a manual demonstration of sending data between a client and a server.

# 8.1 Introduction

The commands that invoke the RTR API calls are similar to the call names. For example, the `rtr_accept_tx()` call is invoked using CALL RTR_ACCEPT_TX at the CLI level.

Where possible, command qualifiers have been given the same names as the parameters to the API calls. See the Reliable Transaction Router C Application Programmer's Reference Manual for details about the parameters to API calls.

Most commands can be issued on remote nodes by using the /NODE=node-list or /CLUSTER qualifiers, or by preceding them with the SET ENVIRONMENT command to specify nodes where commands are to be executed. Commands such as DEFINE KEY are intended for local execution only.

Output from each command can be redirected to another device or file using the /OUTPUT qualifier.

Because the RTR command utility keeps parameter checking to a minimum, "what if" questions can be answered quickly without having to write test programs.

Note In a mixed RTR Version 3 and Version 4 environment, you can execute commands remotely with the /NODE qualifier.

# 8.2 RTR Command Reference

This section describes each command in the RTR command utility.

The command descriptions are presented in alphabetical order.

# ADD FACILITY

> See CREATE FACILITY; ADD FACILITY is retained for compatibility reasons only.

# CALL RTR_ACCEPT_TX

> The CALL RTR_ACCEPT_TX command causes a command server to execute the `rtr_accept_tx()` routine and to display the returned status.

> Note This command is not available in the RTR web browser interface.

## Format

> CALL RTR_ACCEPT_TX

Command Qualifiers | Defaults
--- | ---
/CHANNEL_NAME=channel-name | /CHANNEL_NAME=RTR$DEFAULT_CHANNEL
/CLUSTER | /NOCLUSTER
/FORGET | /NOFORGET
/INDEPENDENT | /NOINDEPENDENT
/NODE[=node-list] | /NODE=default-node
/OUTPUT[=filespec] | /OUTPUT=stdout
/REASON[=reason] | /REASON=0

## Description

> The CALL RTR_ACCEPT_TX command causes a command server to call the `rtr_accept_tx()` routine using values supplied on the command line.

> The numeric status returned from the call is then converted to its textual representation and displayed.

> The `rtr_accept_tx()` routine itself is described in the C Application Programmer's Reference Manual.

> The prototype of `rtr_accept_tx()` is:

>         rtr_status_t   rtr_accept_tx (
>                            rtr_channel_t   channel,
>                            rtr_acc_flag_t  flags,
>                            rtr_reason_t    reason
>                            ) ;

> Table 8-1 shows the correspondence between values you supply on the command line and the C language parameter values produced and used for the call.

> Table 8-1 Parameters for rtr_accept_tx
> C Parameter Name | C Parameter Value | Command Line Specification
> --- | --- | ---
> channel |  | /CHANNEL_NAME=name
> flags | RTR_NO_FLAGS | [none] [D]
> | RTR_F_ACC_FORGET | /FORGET
> reason | RTR_NO_REASON | /NOREASON [D]
> | reason_value | /REASON=reason_value

> Issuing the CALL RTR_ACCEPT_TX command in preference to using the /ACCEPT qualifier with the CALL RTR_SEND_TO_SERVER or CALL RTR_REPLY_TO_CLIENT commands is only necessary when specifying an acceptance "reason" other than the default value of zero (using the /REASON qualifier).

## Qualifiers

> ### /CHANNEL_NAME=channel_name

> ### /CHANNEL_NAME=RTR$DEFAULT_CHANNEL

> Specifies the channel for which the operation is to be performed.

> The command server uses a combination of the channel name and the window from which the call was issued to uniquely identify which channel to use.

> `channel_name` is not case sensitive.

> The default for `channel_name` is RTR$DEFAULT_CHANNEL.

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

> ### /FORGET

> ### /NOFORGET

> Use /FORGET to specify the `flags` parameter as RTR_F_ACC_FORGET in the call `rtr_accept_tx()` .

> The default value for /FORGET is /NOFORGET, which causes the command server to use the value RTR_NO_FLAGS for the `flags` parameter in the call to `rtr_accept_tx()` .

> ### /INDEPENDENT

> ### /NOINDEPENDENT

> Use the /INDEPENDENT qualifier to specify the flags parameter RTR_F_ACC_INDEPENDENT in the call to `rtr_accept_tx()` .

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

> ### /REASON[=reason]

> ### /REASON=0

> Use /REASON to supply a value for the `reason` parameter in the call to `rtr_accept_tx()` .

> The default value for /REASON is 0, which causes the command server to use the value RTR_NO_REASON for the `reason` parameter in the call to `rtr_accept_tx()` .

### Related commands

- CALL RTR_OPEN_CHANNEL
- CALL RTR_REJECT_TX

##

### Examples

> Accept the current transaction with a reason of 42.

      RTR> CALL RTR_ACCEPT_TX /REASON=42
      %RTR-S-OK, normal successful completion

# CALL RTR_BROADCAST_EVENT

> The CALL RTR_BROADCAST_EVENT command causes a command server to execute the `rtr_broadcast_event()` routine and to display the returned status.

> Note This command is not available in the RTR web browser interface.

## Format

> CALL RTR_BROADCAST_EVENT [message-field1] [,message-field2,...]

## Parameters

> ### [message-field1] [,message-field2...]

> Specify the message to be sent (if any) as one or more comma-separated parameter values. You can use the /TYPE_OF_DATA and /LENGTH_OF_DATA positional qualifiers on each parameter value to specify the data type and length of each field.

Command Qualifiers | Defaults
--- | ---
/CHANNEL_NAME=channel-name | /CHANNEL_NAME=RTR$DEFAULT_CHANNEL
/CLUSTER | /NOCLUSTER
/EVENT_NUMBER=evtnum | None
/FORMAT=fmt-string | /NOFORMAT
/LENGTH_OF_FIELD=msg length | Depends on data type.
/NODE[=node-list] | /NODE=default-node
/OUTPUT[=filespec] | /OUTPUT=stdout
/RECIPIENT_SPEC=rcpspc | /NORECIPIENT_SPEC
/TYPE_OF_DATA=data type | /TYPE_OF_DATA=STRING

## Description

> The CALL RTR_BROADCAST_EVENT command causes a command server to call the `rtr_broadcast_event()` routine using values supplied on the command line.

> The numeric status returned from the call is then converted to its textual representation and displayed.

> The `rtr_broadcast_event()` routine itself is described in the Reliable Transaction Router C Application Programmer's Reference Manual.

> The prototype of `rtr_broadcast_event()` is:

>         rtr_status_t rtr_broadcast_event (
>                       rtr_channel_t     channel,
>                       rtr_bro_flag_t    flags,
>                       rtr_msgbuf_t      pmsg,
>                       rtr_msglen_t      msglen,
>                       rtr_evtnum_t      evtnum,
>                       rtr_rcpspc_t      rcpspc,
>                       rtr_msgfmt_t      msgfmt
>                       ) ;

> Table 8-2 shows the correspondence between values you supply on the command line and the C language parameter values produced and used for the call.

> Table 8-2 Parameters for rtr_broadcast_event
> C Parameter Name | C Parameter Value | Command Line Specification
> --- | --- | ---
> channel |  | /CHANNEL_NAME=name
> flags | RTR_NO_FLAGS | [none] [D]
> pmsg, msglen, msgfmt 1 |  | [message definition parameter list with positional qualifiers ]
> evtnum | 42 | /EVENT_NUMBER=42
> rcpspc | "workstat*" | /RECIPIENT_SPEC= "workstat*"

1 The actual values used for `pmsg`, `msglen` and `msgfmt` are based upon the message definition you specify as a command line parameter.

The command server uses message data specified as command line parameter values to generate a record containing the message data (for the `pmsg` parameter), the message length (for the `msglen` parameter), and a record type description (for the `msgfmt` parameter).

## Qualifiers

> ### /CHANNEL_NAME=channel-name

> ### /CHANNEL_NAME=RTR$DEFAULT_CHANNEL

> Specifies the channel for which the operation is to be performed.

> The command server uses a combination of the channel name and the window from which the call was issued to uniquely identify which channel to use.

> `channel_name` is not case sensitive.

> The default for `channel-name` is RTR$DEFAULT_CHANNEL.

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

> ### /EVENT_NUMBER=user-event-number

> The user event number associated with this broadcast, in the range of RTR_EVTNUM_USERBASE to RTR_EVTNUM_USERMAX (i.e. 0 to 250).

> ### /FORMAT[=fmt-string]

> ### /NOFORMAT (D)

> Specifies that a format string should be sent with this message.

> Previous | Next | Contents | Index