# hp Reliable Transaction Router
System Manager's Manual

Previous | Contents | Index

If /FORMAT is specified without `fmt-string` , RTR automatically generates a format string. The format string is generated using the parameters given for the qualifiers /SIGNED, /UNSIGNED, /STRING and /LENGTH. The following table shows permitted values for these qualifiers when using /FORMAT without `fmt-string` .

Table 8-3 Generated Format Strings
Data Type | With /LENGTH= | With /NOLENGTH
--- | --- | ---
STRING | =n, "%nC" | "%nC" where n=strlen(string)
SIGNED | =1, "%SB" | "%SL"
SIGNED | =2, "%SW" | "%SL"
SIGNED | =4, "%SL" | "%SL"
UNSIGNED | =1, "%UB" | "%SL"
UNSIGNED | =2, "%UW" | "%SL"
UNSIGNED | =4, "%UL" | "%SL"

Refer to the Reliable Transaction Router C Application Programmer's Reference Manual, section "Defining a Message Format Description" for information on constructing a `fmt-string` parameter.

### /LENGTH_OF_FIELD=field-length

Enter the size of the message field that you want to define. The default for string types is the length of the message entered, plus one (for the zero termination byte). The default for signed and unsigned types is four. This is a positional qualifier; it must immediately follow the message field that it refers to.

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

### /RECIPIENT_SPEC=rcpspc

Enter a string specifying the recipient name. The wildcard characters asterisk (*) and question mark (?) are permitted.

`rcpspc` is case sensitive, but defaults to the case-insensitive channel name if not explicitly defined.

### /TYPE_OF_DATA=STRING|SIGNED|UNSIGNED

### /TYPE_OF_DATA=STRING (D)

Enter the data type of the message field that you want to define. The default is the string type. This is a positional qualifier; it must immediately follow the message field that it refers to.

##

### Examples

> This command broadcasts user event number 23 to all default recipients. The message in quotes is sent with the broadcast.

         RTR> CALL RTR_BROADCAST_EVENT /EVENT_NUMBER=23 "Dollar is up"
         %RTR-S-OK, Normal successful completion

> The following command broadcasts user event number 24 to all recipients whose /RECIPIENT_SPEC matches the DEALER? string (that is, DEALER1, DEALER2, DEALERx). Note that only the event is broadcast; there is no associated message.

         RTR> CALL RTR_BROADCAST_EVENT /EVENT=24/RECIPIENT_SPEC=DEALER?
         %RTR-S-OK, Normal successful completion

> The following example shows a broadcast message containing two fields. The first field is of type unsigned, entered as a hexadecimal number; the second field is of type string.

         RTR> CALL RTR_BROADCAST_EVENT /EVENT=24 0xFA9BC0 /TYPE_OF_
         DATA=UNSIGNED/LENGTH=8,"This field of the message is a string"
         %RTR-S-OK, Normal successful completion

# CALL RTR_CLOSE_CHANNEL

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

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

## Format

> CALL RTR_CLOSE_CHANNEL

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

## Description

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

> The prototype of `rtr_close_channel()` is:

>          rtr_status_t     rtr_close_channel (
>                             rtr_channel_t       channel,
>                             rtr_clo_flag_t      flags
>                             ) ;

> Table 8-4 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-4 Parameters for rtr_close_channel
> C Parameter Name | C 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.

> `channel_name` is not case sensitive.

> The default channel name is RTR$DEFAULT_CHANNEL.

> You may close all the channels belonging to a window using
> CLOSE CHANNEL/CHANNEL_NAME=*.

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

> ### /IMMEDIATE

> ### /IMMEDIATE=RTR_F_CLO_IMMEDIATE (D)

> Specifies the closing of a channel immediately without sending a transaction acknowledgement.

> ### /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 closes the RTR$DEFAULT_CHANNEL.

      RTR> CALL RTR_CLOSE_CHANNEL
      %RTR-S-OK, Normal successful completion

> This command closes the channel named CLIENT1.

      RTR> CALL RTR_CLOSE_CHANNEL/CHANNEL_NAME=CLIENT1
      %RTR-S-OK, Normal successful completion

# CALL RTR_ERROR_TEXT

> The CALL RTR_ERROR_TEXT command causes a command server to execute the `rtr_error_text()` routine and to display the returned error text.

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

## Format

> CALL RTR_ERROR_TEXT

Command Qualifiers | Defaults
--- | ---
/OUTPUT[=filespec] | /OUTPUT=stdout
/STATUS=status-code | None

## Description

> The CALL RTR_ERROR_TEXT command causes a command server to call the `rtr_error_text()` routine using the value supplied on the command line.

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

> The prototype of `rtr_error_text()` is:

>                    char    *rtr_error_text (
>                               rtr_status_t    sts
>                               ) ;

> Table 8-5 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-5 Parameters for rtr_error_text
> C Parameter Name | Parameter Value | Command Line Specification
> --- | --- | ---
> sts | 42 | 42 (parameter)

## Qualifiers

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

> ### /STATUS=status-code

> ### No default

> Specifies the `sts` parameter in the `rtr_request_info()` call.

##

### Examples

> This command shows the text associated with error number 4849722.

     RTR> CALL RTR_ERROR_TEXT /STATUS=4849722
     error text        normal successful completion

# CALL RTR_EXT_BROADCAST_EVENT

> The CALL RTR_EXT_BROADCAST_EVENT command causes a command server to execute the `rtr_ext_broadcast_event()` routine and to display the returned status. A timeout can be supplied to eliminate long waits that may be seen with the similar call RTR_BROADCAST_EVENT.

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

## Format

> CALL RTR_EXT_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
/TIMOUTMS=timeout | None
/TYPE_OF_DATA=data type | /TYPE_OF_DATA=STRING

## Description

> The CALL RTR_EXT_BROADCAST_EVENT command causes a command server to call the `rtr_ext_broadcast_event()` routine using values supplied on the command line. In some circumstances, a broadcast event call can wait a long time if RTR runs out of channel credits; it may seem that the application is hanging. To eliminate such a wait, the user can specify a timeout value from which the function will return an RTR_STS_TIMOUT status if RTR is unable to issue the broadcast message within the specified broadcast period.

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

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

> The prototype of `rtr_ext_broadcast_event()` is:

>         rtr_status_t rtr_ext_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,
>                       rtr_timoutms_t    timoutms

>                       ) ;

> Table 8-6 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-6 Parameters for rtr_ext_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*"
> timoutms |  | /TIMOUTMS=1000 (1 sec.)

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.

> If /FORMAT is specified without `fmt-string` , RTR automatically generates a format string. The format string is generated using the parameters given for the qualifiers /SIGNED, /UNSIGNED, /STRING and /LENGTH. The following table shows permitted values for these qualifiers when using /FORMAT without `fmt-string` .

> Table 8-7 Generated Format Strings
> Data Type | With /LENGTH= | With /NOLENGTH
> --- | --- | ---
> STRING | =n, "%nC" | "%nC" where n=strlen(string)
> SIGNED | =1, "%SB" | "%SL"
> SIGNED | =2, "%SW" | "%SL"
> SIGNED | =4, "%SL" | "%SL"
> UNSIGNED | =1, "%UB" | "%SL"
> UNSIGNED | =2, "%UW" | "%SL"
> UNSIGNED | =4, "%UL" | "%SL"

> Refer to the Reliable Transaction Router C Application Programmer's Reference Manual, section "Defining a Message Format Description" for information on constructing a `fmt-string` parameter.

> ### /LENGTH_OF_FIELD=field-length

> Enter the size of the message field that you want to define. The default for string types is the length of the message entered, plus one (for the zero termination byte). The default for signed and unsigned types is four. This is a positional qualifier; it must immediately follow the message field that it refers to.

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

> ### /RECIPIENT_SPEC=rcpspc

> Enter a string specifying the recipient name. The wildcard characters asterisk (*) and question mark (?) are permitted.

> `rcpspc` is case sensitive, but defaults to the case-insensitive channel name if not explicitly defined.

> ### /TIMOUTMS=msec

> Specifies a value in milliseconds for the timeout. RTR returns an error message if RTR is unable to issue the broadcast message within the specified timeout period.

> ### /TYPE_OF_DATA=STRING|SIGNED|UNSIGNED

> ### /TYPE_OF_DATA=STRING (D)

> Enter the data type of the message field that you want to define. The default is the string type. This is a positional qualifier; it must immediately follow the message field that it refers to.

##

### Examples

> The following command broadcasts user event number 40 to all recipients whose /RECIPIENT_SPEC matches the TRADER? string (where ? represents a wildcard), but times out after 1 second if traffic congestion prevents the broadcast.

         RTR> CALL RTR_EXT_BROADCAST_EVENT /EVENT=40-
         RTR_ /RECIPIENT_SPEC=TRADER?/TIMOUTMS=1000
         %RTR-S-OK, Normal successful completion

Previous | Next | Contents | Index