hp Reliable Transaction Router
System Manager's Manual

This command opens a client channel called FIN1CHAN.

RTR> CALL RTR_OPEN_CHANNEL/CLIENT/CHANNEL=FIN1CHAN %RTR-S-OK, Normal successful completion


RTR> CALL RTR_OPEN_CHANNEL/CLIENT/CHANNEL=FIN1CHAN %RTR-S-OK, Normal successful completion

CALL RTR_RECEIVE_MESSAGE

The CALL RTR_RECEIVE_MESSAGE command causes a command server to execute the rtr_receive_message() routine and to display the returned status.

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

Format

CALL RTR_RECEIVE_MESSAGE

Command Qualifiers	Defaults
/CHANNEL_NAME=channel-name	/CHANNEL_NAME=RTR$DEFAULT_CHANNEL
/CLUSTER	/NOCLUSTER
/NODE[=node-list]	/NODE=default-node
/OUTPUT[=filespec]	/OUTPUT=stdout
/TIMEOUT_MS=timoutms	/TIMEOUT_MS=0
/TYPE=data-being-received	/TYPE=string

Description

The CALL RTR_RECEIVE_MESSAGE command causes a command server to call the rtr_receive_message() 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_receive_message() routine itself is described in the C Application Programmer's Reference Manual.
The prototype of rtr_receive_message() is:
rtr_status_t rtr_receive_message ( rtr_channel_t *pchannel, rtr_rcv_flag_t flags, rtr_channel_t *prcvchan, rtr_msgbuf_t pmsg, rtr_msglen_t maxlen, rtr_timout_t timoutms, rtr_msgsb_t *pmsgsb ) ;
Table 8-11 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-11 Parameters for rtr_receive_message
C Parameter Name C Parameter Value Command Line Specification

pchannel [displayed]

flags RTR_NO_FLAGS [none] [D]

prcvchan /CHANNEL=channel_name

pmsg [message displayed, if any]

maxlen RTR_MAX_MSGLEN [reasonable limit for display]

timoutms /TIMEOUT_MS=timoutms

pmsgsb [relevant fields displayed]

type /TYPE=data-being-received

For all messages received, RTR displays the contents of the message status block ( msgsb ) as follows:

Message type (for example, rtr_mt_opened , rtr_mt_msgn )
Message length in bytes
Transaction ID, user handle, and event number are shown if they are relevant for the message type.

For message types that place a status code and reason code in the user buffer, the status code is converted to text and both are shown.
For all other message types, the contents of the user buffer are displayed in hexadecimal and ASCII text.
For certain events (FE, TR, BE GAIN/LOSS), the facility name and nodename of the node that sent the event are displayed.

**Table 8-11 Parameters for rtr_receive_message**
C Parameter Name	C Parameter Value	Command Line Specification
pchannel		[displayed]
flags	RTR_NO_FLAGS	[none] [D]
prcvchan		/CHANNEL=channel_name
pmsg		[message displayed, if any]
maxlen	RTR_MAX_MSGLEN	[reasonable limit for display]
timoutms		/TIMEOUT_MS=timoutms
pmsgsb		[relevant fields displayed]
type		/TYPE=data-being-received

Qualifiers

/CHANNEL_NAME=channel_name

/CHANNEL_NAME=RTR$DEFAULT_CHANNEL
Specifies one or more channels from which a message may be received. To specify two or more channels, enter a comma-separated list, such as /CHANNEL_NAME=(CHAN1,CHAN2,CHAN5). Channel names may include wildcard characters.
channel_name is not case sensitive.
Entering the qualifier without a value (that is, /CHANNEL) is equivalent to /CHANNEL=RTR$DEFAULT_CHANNEL. Omitting the qualifier altogether is equivalent to /CHANNEL=* (that is, receive a message on any defined channel).
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.
Note that this qualifier sets up the prcvchan parameter on the call to rtr_receive_message .
/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.
/TIMEOUT_MS=timoutms

/TIMEOUT_MS=0 (D)
The timoutms argument defines a timeout for the receive, in milliseconds. If the /TIMEOUT_MS qualifier is not used, the timeout value is infinite (no timeout); if the /TIMEOUT_MS qualifier is used with no value (e.g., /TIMEOUT_MS), the timeout is immediate, equivalent of timeout of 0.
Clock granularity is one second (1000 ms). The call completes after either:

the specified timeout or when
a message is available on one of the specified channels

/TYPE=data-being-received

/TYPE=string (D)
The type argument specifies the type of data being received (string, unsigned, signed). If no value is given, it defaults to string type.

Examples

The following example shows two CALL RTR_RECEIVE_MESSAGE commands on RTR$DEFAULT_CHANNEL.


RTR> CALL RTR_RECEIVE_MESSAGE /TIMEOUT_MS %RTR-S-OK, normal successful completion channel name: RTR$DEFAULT_CHANNEL msgsb msgtype: rtr_mt_rtr_event msglen: 0 evtnum: 113 (RTR_EVTNUM_SRRECOVERCMPL) RTR> CALL RTR_RECEIVE_MESSAGE /TIMEOUT_MS %RTR-S-OK, normal successful completion channel name: RTR$DEFAULT_CHANNEL msgsb msgtype: rtr_mt_msg1 msglen: 55 usrhdl: 0 tid: 1fe5c,495a4,0,0,1bf80,84,36 message offset bytes text 000000 54 68 69 73 20 69 73 20 74 68 65 20 6D 65 73 73 This is the mess 000010 61 67 65 20 74 65 78 74 2E 20 53 6F 6D 65 20 64 age text. Some d 000020 69 67 69 74 73 20 68 65 72 65 3A 20 31 32 33 34 igits here: 1234 000030 35 36 37 38 39 30 00 567890.

 RTR> CALL RTR_RECEIVE_MESSAGE /TIMEOUT_MS
 %RTR-S-OK, normal successful completion
 channel name:  RTR$DEFAULT_CHANNEL
 msgsb
   msgtype:     rtr_mt_rtr_event
   msglen:      0
   evtnum:      113     (RTR_EVTNUM_SRRECOVERCMPL)
 RTR> CALL RTR_RECEIVE_MESSAGE /TIMEOUT_MS
 %RTR-S-OK, normal successful completion
 channel name:  RTR$DEFAULT_CHANNEL
 msgsb
   msgtype:     rtr_mt_msg1
   msglen:      55
   usrhdl:  0
   tid:         1fe5c,495a4,0,0,1bf80,84,36  
 message 
   offset  bytes                                            text
   000000  54 68 69 73 20 69 73 20 74 68 65 20 6D 65 73 73  This is the mess
   000010  61 67 65 20 74 65 78 74 2E 20 53 6F 6D 65 20 64  age text. Some d
   000020  69 67 69 74 73 20 68 65 72 65 3A 20 31 32 33 34  igits here: 1234
   000030  35 36 37 38 39 30 00                             567890.

CALL RTR_REJECT_TX

The CALL RTR_REJECT_TX command causes a command server to execute the rtr_reject_tx() routine and to display the returned status.

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

Format

CALL RTR_REJECT_TX

Command Qualifiers	Defaults
/CHANNEL_NAME=channel-name	/CHANNEL_NAME=RTR$DEFAULT_CHANNEL
/CLUSTER	/NOCLUSTER
/NODE[=node-list]	/NODE=default-node
/OUTPUT[=filespec]	/OUTPUT=stdout
/REASON[=reason]	/REASON=0
/RETRY	/NORETRY

Description

The CALL RTR_REJECT_TX command causes a command server to call the rtr_reject_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_reject_tx() routine itself is described in the C Application Programmer's Reference Manual.
The prototype of rtr_reject_tx() is:
rtr_status_t rtr_reject_tx ( rtr_channel_t channel, rtr_rej_flag_t flags, rtr_reason_t reason ) ;
Table 8-12 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-12 Parameters for rtr_reject_tx
C Parameter Name C Parameter Value Command Line Specification

channel /CHANNEL_NAME=name

flags RTR_NO_FLAGS [none] [D]

RTR_F_REJ_RETRY /RETRY

reason RTR_NO_REASON /NOREASON [D]

reason_value /REASON=reason_value

**Table 8-12 Parameters for rtr_reject_tx**
C Parameter Name	C Parameter Value	Command Line Specification
channel		/CHANNEL_NAME=name
flags	RTR_NO_FLAGS	[none] [D]
	RTR_F_REJ_RETRY	/RETRY
reason	RTR_NO_REASON	/NOREASON [D]
	reason_value	/REASON=reason_value

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.
/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.
/REASON[=reason]

/REASON=0
Use /REASON to supply a value for the reason parameter in the call to rtr_reject_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_reject_tx() .
/RETRY

/NORETRY (D)
Use /RETRY to specify the flags parameter as RTR_F_REJ_RETRY in the call rtr_reject_tx() .
The default value for /RETRY is /NORETRY, which causes the command server to use the value RTR_NO_FLAGS for the flags parameter in the call to rtr_reject_tx() .

Related commands

CALL RTR_OPEN_CHANNEL
CALL RTR_ACCEPT_TX

Examples

Reject the current transaction with a reason of 42.


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

CALL RTR_REPLY_TO_CLIENT

The CALL RTR_REPLY_TO_CLIENT command causes a command server to execute the rtr_reply_to_client() routine and to display the returned status. Replies can be compressed with the compression environment variables. See Section 2.13.2 for more details on how to use these variables.

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

Format

CALL RTR_REPLY_TO_CLIENT [message-field1] [,message-field2,...]

Parameters

[message-field1] [,message-field2...]
Specify the message to be sent 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
/ACCEPT	/NOACCEPT
/CHANNEL_NAME=channel-name	/CHANNEL_NAME=RTR$DEFAULT_CHANNEL
/CLUSTER	/NOCLUSTER
/FORMAT[=fmt-string]	/NOFORMAT
/INDEPENDENT	/NOINDEPENDENT
/LENGTH_OF_FIELD=msg length	Depends on data type.
/NODE[=node-list]	/NODE=default-node
/OUTPUT[=filespec]	/OUTPUT=stdout
/TYPE_OF_DATA=data type	/TYPE_OF_DATA=STRING

Description

The CALL RTR_REPLY_TO_CLIENT command causes a command server to call the rtr_reply_to_client() 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_reply_to_client() routine itself is described in the C Application Programmer's Reference Manual.
The prototype of rtr_reply_to_client() is:
rtr_status_t rtr_reply_to_client ( rtr_channel_t channel, rtr_rep_flag_t flags, rtr_msgbuf_t pmsg, rtr_msglen_t msglen, rtr_msgfmt_t msgfmt ) ;
Table 8-13 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-13 Parameters for rtr_reply_to_client
C Parameter Name C Parameter Value Command Line Specification

channel /CHANNEL_NAME=name

flags RTR_NO_FLAGS none [D]

RTR_F_REP_ACCEPT /ACCEPT

pmsg, msglen, msgfmt ¹ [message definition parameter list with positional qualifiers.]

**Table 8-13 Parameters for rtr_reply_to_client**
C Parameter Name	C Parameter Value	Command Line Specification
channel		/CHANNEL_NAME=name
flags	RTR_NO_FLAGS	none [D]
	RTR_F_REP_ACCEPT	/ACCEPT
pmsg, msglen, msgfmt ¹		[message definition parameter list with positional qualifiers.]

¹ 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

/ACCEPT

/NOACCEPT
The /ACCEPT qualifier sets the flag RTR_F_REP_ACCEPT in the call to reply_to_client() . It means the transaction is accepted by this server.
/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.
/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.

/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-14 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.
/INDEPENDENT

/NOINDEPENDENT
Use the /INDEPENDENT qualifier to specify the flags parameter RTR_F_REP_INDEPENDENT in the call to rtr_reply_to_client() .
/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.
/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.

**Table 8-14 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"

Related commands

CALL RTR_SEND_TO_SERVER
CALL RTR_RECEIVE_MESSAGE

Examples

The following example replies a message to the client.


RTR> CALL RTR_REPLY_TO_CLIENT "Getting that info for you" %RTR-S-OK, Normal successful completion

The following example shows a message of type unsigned and entered as a hexadecimal number.


RTR> CALL RTR_REPLY_TO_CLIENT "0xFA9BC0"/TYPE_OF_DATA=UNSIGNED %RTR-S-OK, Normal successful completion

Contents

Index

hp Reliable Transaction RouterSystem Manager's Manual

CALL RTR_RECEIVE_MESSAGE

Format

Description

Qualifiers

/CHANNEL_NAME=channel_name

/CHANNEL_NAME=RTR$DEFAULT_CHANNEL

/CLUSTER

/NOCLUSTER (D)

/NODE[=node-list]

/NODE=default-node (D)

/OUTPUT[=filespec]

/OUTPUT=stdout (D)

/TIMEOUT_MS=timoutms

/TIMEOUT_MS=0 (D)

/TYPE=data-being-received

/TYPE=string (D)

Examples

CALL RTR_REJECT_TX

Format

Description

Qualifiers

/CHANNEL_NAME=channel_name

/CHANNEL_NAME=RTR$DEFAULT_CHANNEL

/CLUSTER

/NOCLUSTER (D)

/NODE[=node-list]

/NODE=default-node (D)

/OUTPUT[=filespec]

/OUTPUT=stdout (D)

/REASON[=reason]

/REASON=0

/RETRY

/NORETRY (D)

Related commands

Examples

CALL RTR_REPLY_TO_CLIENT

Format

Parameters

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

Description

Qualifiers

/ACCEPT

/NOACCEPT

/CHANNEL_NAME=channel_name

/CHANNEL_NAME=RTR$DEFAULT_CHANNEL

/CLUSTER

/NOCLUSTER (D)

/FORMAT[=fmt-string]

/NOFORMAT (D)

/INDEPENDENT

/NOINDEPENDENT

/LENGTH_OF_FIELD=field-length

/NODE[=node-list]

/NODE=default-node (D)

/OUTPUT[=filespec]

/OUTPUT=stdout (D)

/TYPE_OF_DATA=STRING|SIGNED|UNSIGNED

/TYPE_OF_DATA=STRING (D)

Related commands

Examples

hp Reliable Transaction Router
System Manager's Manual