# hp Reliable Transaction Router
System Manager's Manual

Previous | Contents | Index

# CALL RTR_GET_TID

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

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

## Format

> CALL RTR_GET_TID

Command Qualifiers | Defaults
--- | ---
/CHANNEL_NAME=channel-name | /CHANNEL_NAME=RTR$DEFAULT_CHANNEL
/CLUSTER | /NOCLUSTER
/NODE[=node-list] | /NODE=default-node
/OUTPUT[=filespec] | /OUTPUT=stdout

## Description

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

> The transaction ID returned from the call is converted to its textual representation and displayed.

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

> The prototype of `rtr_get_tid()` is:

>             rtr_status_t    rtr_get_tid (
>                                rtr_channel_t       channel,
>                                rtr_tid_flag_t      flags,
>           void*               ptid
>                                ) ;

> Table 8-8 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-8 Parameters for rtr_get_tid
> C Parameter Name | Parameter Value | Command Line Specification
> --- | --- | ---
> channel |  | /CHANNEL_NAME=name
> flags | RTR_NO_FLAGS | [none] [D]

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

> The default 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.

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

> This command shows the transaction ID active on channel CLIENT1.

     RTR> CALL RTR_GET_TID/CHANNEL=CLIENT1
    %RTR-S-OK, normal successful completion
     tid:           e100b810,0,0,0,0,3bc5,6eb02001

# CALL RTR_GET_USER_CONTEXT

> The CALL RTR_GET_USER_CONTEXT command causes a command server to execute the `rtr_get_user_context()` routine and to display the optional user-defined context associated with the specified RTR channel.

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

## Format

> CALL RTR_GET_USER_CONTEXT

Command Qualifiers | Defaults
--- | ---
/CHANNEL_NAME=channel-name | /CHANNEL_NAME=RTR$DEFAULT_CHANNEL
/NODE[=node-list] | /NODE=default-node
/OUTPUT[=filespec] | /OUTPUT=stdout

## Description

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

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

> The prototype of `rtr_get_user_context()` is:

>             rtr_usrctx_t    rtr_get_user_context (
>                                rtr_channel_t       channel,
>                                ) ;

> Table 8-9 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-9 Parameters for rtr_get_user_context
> C Parameter Name | Parameter Value | Command Line Specification
> --- | --- | ---
> channel |  | /CHANNEL_NAME=name

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

> The default channel name is RTR$DEFAULT_CHANNEL.

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

> This command shows setting and then retrieving the user context on channel CLIENT1.

     RTR> CALL RTR_SET_USER_CONTEXT/CHANNEL=CLIENT1/CONTEXT=567
     %RTR-S-OK, normal successful completion
     RTR> CALL RTR_GET_USER_CONTEXT/CHANNEL=CLIENT1
     User context for channel CLIENT1: 567

# CALL RTR_OPEN_CHANNEL

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

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

## Format

> CALL RTR_OPEN_CHANNEL

Command Qualifiers | Defaults
--- | ---
/ACCEPT_EXPLICIT | /NOACCEPT_EXPLICIT
/ACCESS=access | /NOACCESS
/BE_CALL_OUT | /NOBE_CALL_OUT
/CHANNEL_NAME=channel-name | /CHANNEL_NAME=RTR$DEFAULT_CHANNEL
/CLIENT | /NOCLIENT
/CLUSTER | /NOCLUSTER
/[NO]CONCURRENT | /CONCURRENT
/EVENTS(=event-nr-list) | /NOEVENTS
/FACILITY_NAME[=facility-name] | /FACILITY_NAME=RTR$DEFAULT_FACILITY
/FOREIGN_TM[=tm_id] | /NOFOREIGN_TM
/HIGH_BOUND=high-bound | /HIGH_BOUND=max-value-for-key-type
/KEYn=keysegdesc | /See description
/LENGTH_OF_FIELD=key-field-length | /LENGTH_OF_FIELD=4
/LOW_BOUND=low-bound | /LOW_BOUND=lowest value for key-type
/NODE[=node-list] | /NODE=default-node
/OFFSET_OF_KEY=offset | /OFFSET_OF_KEY=0
/OUTPUT[=filespec] | /OUTPUT=stdout
/PARTITION_NAME=partition-name | None
/PREPARE_EXPLICIT | /NOPREPARE_EXPLICIT
/RECEIVE_REPLIES | /NORECEIVE_REPLIES
/RECIPIENT_NAME=rcpnam | /RECIPIENT_NAME=null
/SERVER | /NOSERVER
/SHADOW | /NOSHADOW
/[NO]STANDBY | /STANDBY
/TR_CALL_OUT | /NOTR_CALL_OUT
/TYPE_OF_FIELD=key-field-type | /TYPE_OF_FIELD=UNSIGNED

## Description

> The CALL RTR_OPEN_CHANNEL command causes a command server to call the `rtr_open_channel()` 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_open_channel()` routine itself is described in the C Application Programmer's Reference Manual.

> The prototype of `rtr_open_channel()` is:

>         rtr_status_t     rtr_open_channel  (
>                             rtr_channel_t       *pchannel,
>                             rtr_ope_flag_t      flags,
>                             rtr_facnam_t        facnam,
>                             rtr_rcpnam_t        rcpnam,
>                             rtr_evtnum_t        *pevtnum,
>                             rtr_access_t        access,
>                             rtr_numseg_t        numseg,
>                             rtr_keyseg_t        *pkeyseg
>                             ) ;

> Table 8-10 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-10 Parameters for rtr_open_channel
> C Parameter Name | C Parameter Value | Example
> --- | --- | ---
> channel |  | /CHANNEL_NAME=name
> flags | RTR_NO_FLAGS | none [D]
> | RTR_F_OPE_CLIENT | /CLIENT
> | RTR_F_OPE_SERVER | /SERVER
> | RTR_F_OPE_BE_CALL_OUT | /BE_CALL_OUT
> | RTR_F_OPE_NOCONCURRENT | /NOCONCURRENT
> | RTR_F_OPE_EXPLICIT_PREPARE | /PREPARE_EXPLICIT
> | RTR_F_OPE_EXPLICIT_ACCEPT | /ACCEPT_EXPLICIT
> | RTR_F_OPE_FOREIGN_TM | /FOREIGN=tm_id
> | RTR_F_OPE_RECEIVE_REPLIES | /RECEIVE_REPLIES
> | RTR_F_OPE_SHADOW | /SHADOW
> | RTR_F_OPE_NOSTANDBY | /NOSTANDBY
> | RTR_F_OPE_TR_CALL_OUT | /TR_CALL_OUT
> facnam | "CASHFACIL" | /FACILITY_NAME=CASHFACIL
> rcpnam | "CLI6CHAN" | /RECIPIENT_NAME=CLI6CHAN
> pevtnum | [All events. See /EVENTS] | /EVENTS=(USER,RTR)
> access | J67TF098 | /ACCESS=J67TF098
> numseg | 1 |
> pkeyseg |  |
> -> ks_type | rtr_keyseg_string | /TYPE_OF_FIELD=STRING
> -> ks_length | 10 | /LENGTH_OF_FIELD=10
> -> ks_offset | 2 | /OFFSET_OF_KEY=2
> -> ks_lo_bound | "AAAAAAAAAA" | /LOW_BOUND="AAAAAAAAAA"
> -> ks_hi_bound | "NNNNNNNNNN" | /HIGH_BOUND="NNNNNNNNNN"

## Qualifiers

> ### /ACCEPT_EXPLICIT

> ### /NOACCEPT_EXPLICIT

> Specifies that the RTR_F_OPE_EXPLICIT_ACCEPT flag is set in the call to `rtr_open_channel()` . This qualifier specifies that the server will accept transactions only by making an explicit call to `rtr_accept_tx` .

> ### /ACCESS=access

> ### /NOACCESS (D)

> Specifies an access string (that is, a password). All application programs (clients and servers) must specify the same access string for a given facility.

> ### /BE_CALL_OUT

> ### /NOBE_CALL_OUT (D)

> Valid for server channels only. Specifies that the RTR_F_OPE_BE_CALL_OUT flag is set in the `flags` parameter in the call to `rtr_open_channel()` . The channel is opened as a backend callout server.

> ### /CHANNEL_NAME=channel-name

> ### /CHANNEL_NAME=RTR$DEFAULT_CHANNEL

> Specifies the name of the window's channel for use in subsequent operations on this channel.

> `channel_name` is not case sensitive. The default channel name is RTR$DEFAULT_CHANNEL.

> ### /CLIENT

> ### /NOCLIENT

> Specifies that the RTR_F_OPE_CLIENT flag is set on the call to `rtr_open_channel()` . The channel is opened as a client.

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

> Specifying /NOCONCURRENT sets the RTR_F_OPE_NOCONCURRENT flag in the call to `rtr_open_channel()` , and the server may not be concurrent with other servers. By default, a server may have other concurrent servers.

> ### /EVENTS=event-nr-list

> ### /NOEVENTS (D)

> The /EVENTS qualifier specifies that broadcast events are received on the channel. To subscribe to all user and RTR events, enter the qualifier with no arguments. Enter /EVENTS=RTR to receive the full range of RTR events only. Enter /EVENTS=USER to receive the full range of USER events only. Specify particular ranges of event numbers using arguments in the following format:

> /EVENTS=(RTR, `n` , TO, `m` , USER, `p` , TO, `q` )

> where `n` , `m` , `p` and `q` are event numbers. The default is to listen to no events.

> ### /FACILITY_NAME=facility-name

> ### /FACILITY=RTR$DEFAULT_FACILITY (D)

> Specifies the name of the facility for which the channel is declared. An application must specify the facility name when using the RTR CLI. The default facility name is RTR$DEFAULT_FACILITY.

> ### /FOREIGN_TM[=tm_id]

> ### /NOFOREIGN_TM (D)

> Valid for client channels only. This indicates that the global coordinating Transaction Manager (TM) is a Foreign TM (denoted as FTM), and that all transactions on this channel will be coordinated by the FTM. If this qualifier is set, calls to `rtr_start_tx` on this channel must supply a value for the `jointxid` parameter, which is the TXID of the transaction.

> A TM identifier can also be passed in as parameter. It must be in the range of 0 to 65535. Default value is 0.

> Operators or script programs using nested transactions should specify a TM identifier, particularly if more than one process opens RTR client channels using the same FTM on the one node, or if different types of FTMs are used on the same node. When a process that has open FTM client channels fails, the FTM must be able to find out from RTR what state the transactions are in that were active in that process. Thus the FTM must be able to identify itself to RTR so RTR can find out what transactions were active for that FTM channel. Generally, FTM client channels opened in the same process (and for the same FTM) can have a common TM identifier, but FTM client channels opened in separate processes should have different TM identifiers.

> Calling CALL RTR_OPEN_CHANNEL with the FOREIGN_TM qualifier specified will cause a local journal scan to occur if a journal has not already been opened on that node.

> ### /HIGH_BOUND=high-bound

> ### /HIGH_BOUND=max-val-for-key-type (D)

> Specifies the upper bound of the key range that the server handles. 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_FIELD), the key bound will automatically be null-padded to the required length.

> ### /KEYn=keysegdesc

> Specifies a partition key segment. Up to eight key segments can be defined for a partition (KEY1, KEY2,... up to KEY8).

> The syntax of the `keyn` qualifier is:

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

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

> `length_of_key=nnnn` Specifies the length of the key field in enqueued messages in bytes. Use this qualifier only if the key field type is `string` , since the key length is in other cases implied by the key type. The default value for `key-length` is four 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.

> Note The `/KEYn=keysegdesc` qualifier is an alternative to using the `/xxx_OF_FIELD` qualifier.

> ### /LENGTH_OF_FIELD=key-field-length

> ### /LENGTH_OF_FIELD=4 (D)

> Specifies the length of the key field in the enqueued messages in bytes. Use this qualifier only if the key field type is `string` , since the key length is in all other cases implied by the key type. The default value for `key-length` is four bytes.

> ### /LOW_BOUND=low-bound

> ### /LOW_BOUND=min-val-for-key-type (D)

> Specifies the lower bound of the key range that the server handles. 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_FIELD), the key bound will automatically be null-padded to the required length.

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

> ### /OFFSET_OF_KEY=offset

> ### /OFFSET_OF_KEY=0 (D)

> 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. The qualifier /KEYn must be used to specify more than one key segment definition.

> ### /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_NAME=partition-name

> Enables a system manager to specify a particular named partition.

> ### /PREPARE_EXPLICIT

> ### /NOPREPARE_EXPLICIT

> Specifies that the flag RTR_F_OPE_EXPLICIT_PREPARE is set in the call to `rtr_open_channel()` . This qualifier specifies that the server will receive prepare messages (messages of type `rtr_mt_prepare` ).

> ### /RECEIVE_REPLIES

> ### /NORECEIVE_REPLIES (D)

> Enables, for a backend callout server, server-to-client messages (replies) to be received. This can be useful in a shadow environment where shadowing servers are expected to reply consistently.

> ### /RECIPIENT_NAME=rcpnam

> ### /RECIPIENT_NAME=null (D)

> Specifies an optional name for broadcast reception to be associated with the channel. Only broadcasts matching this name are delivered on the channel. To receive named events, the correct event number must also be specified.

> RECIPIENT_NAME is case sensitive but defaults to the case-insensitive channel name if not explictly defined. If /RECIPIENT_NAME is supplied without a qualifier value, its value defaults to the value of /CHANNEL_NAME. Not supplying the /RECIPIENT_NAME qualifier has the same effect as specifying a null string. Wildcard characters cannot be used for this qualifier. (However, senders of broadcasts can use wildcards when specifying /RECIPIENT_SPEC with the RTR_BROADCAST_EVENT call or command).

> ### /SERVER

> ### /NOSERVER (D)

> Specifies that the RTR_F_OPE_SERVER flag is set in the call to `rtr_open_channel()` . Use this qualifier to declare the channel as a server.

> ### /SHADOW

> ### /NOSHADOW (D)

> Valid for server channels only. The /SHADOW qualifier specifies that the RTR_F_OPE_SHADOW flag is set in the call to `rtr_open_channel()` . The server is part of a shadow pair.

> ### /STANDBY (D)

> ### /NOSTANDBY

> Valid for server channels only. The /NOSTANDBY qualifier specifies that the flag RTR_F_OPE_NOSTANDBY is set in the call to `rtr_open_channel()` , and the server may not be (or have) standbys. By default, servers may have standbys.

> ### /TR_CALL_OUT

> ### /NOTR_CALL_OUT (D)

> Specifies that the RTR_F_OPE_TR_CALL_OUT flag is set in the call to `rtr_open_channel()` , and the server is a router callout server. By default, a server is not a router callout server.

> ### /TYPE_OF_FIELD=key-field-type

> ### /TYPE_OF_FIELD=UNSIGNED (D)

> Specifies the field type of the key. The `key-type` must be one of UNSIGNED, SIGNED or STRING. The default is UNSIGNED.

### Related commands

- CALL RTR_CLOSE_CHANNEL

##

### Examples

> This command opens a server channel called RTR$DEFAULT_CHANNEL that may not have concurrent servers, explicitly accepts transactions and listens for all RTR events.

     RTR> CALL RTR_OPEN_CHANNEL/SERVER/NOCONCURRENT/ACCEPT_EXPLICIT/EVENTS=RTR
     %RTR-S-OK, Normal successful completion

> Previous | Next | Contents | Index