Reliable Transaction Router
System Manager's Manual
Previous Contents Index

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.

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 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 7-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 7-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 clustering, the /CLUSTER qualifier causes the relevant command to be executed on the local node only.

/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 7-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 C Application Programmer's Reference Manual, section "Defining a Message Format Description" for information on constructing an 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.

/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 channels having a null string rcpnam (the default). A message is sent with the broadcast. 

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

The following command broadcasts user event number 24 to all recipients whose /RECIPIENT_NAME 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.

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 7-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 7-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 clustering, the /CLUSTER qualifier causes the relevant command to be executed on the local node only.

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

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

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 7-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 7-6 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 clustering, the /CLUSTER qualifier causes the relevant command to be executed on the local node only.

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

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
/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 7-7 shows the correspondence between values you supply on the command line and the C language parameter values produced and used for the call.

Table 7-7 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_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.

Previous Next Contents Index