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

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 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 6-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 6-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 then the command is executed on the nodes specified by the latest SET ENVIRONMENT command. If no SET ENVIRONMENT command has been entered then the command is executed only on the node where the command was issued.

Note: In environments that do not support clustering, use of the /CLUSTER qualifier will cause the relevant command to be executed on the local node only.

/IMMEDIATE

/IMMEDIATE=RTR$DEFAULT_CHANNEL

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

Use /IMMEDIATE=RTR_F_CLO_IMMEDIATE to close the channel and recover any accepted transactions on this channel to an alternate server channel.

/NODE[=node-list]

/NODE=default-node-list (D)

Specifies that the command is executed on all nodes specified in node-list. If node-list is omitted then the command is executed only on the node where the command was issued.

/OUTPUT[=file-spec]

/OUTPUT=stdout (D)

Specifies that the resulting information is written to the file file-spec. If /OUTPUT or file-spec is omitted then 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

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

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 Application Programmer's Reference Manual.

The prototype of rtr_error_text() is:

char *rtr_error_text ( rtr_status_t sts ) ;

Table 6-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 6-5 Parameters for rtr_error_text

C Parameter Name	Parameter Value	Command Line Specification
sts	42	42 (parameter)

Qualifiers

/OUTPUT[=file-spec]

/OUTPUT=stdout (D)

Specifies that the resulting information is written to the file file-spec. If /OUTPUT or file-spec is omitted then 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

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

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 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 6-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 6-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 then the command is executed on the nodes specified by the latest SET ENVIRONMENT command. If no SET ENVIRONMENT command has been entered then the command is executed only on the node where the command was issued.

Note: In environments that do not support clustering, use of the /CLUSTER qualifier will cause the relevant command to be executed on the local node only.

/NODE[=node-list]

/NODE=default-node-list (D)

Specifies that the command is executed on all nodes specified in node-list. If node-list is omitted then the command is executed only on the node where the command was issued.

/OUTPUT[=file-spec]

/OUTPUT=stdout (D)

Specifies that the resulting information is written to the file file-spec. If /OUTPUT or file-spec is omitted then 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

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

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 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 6-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 6-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() .

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

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 call-out 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 then the command is executed on the nodes specified by the latest SET ENVIRONMENT command. If no SET ENVIRONMENT command has been entered then the command is executed only on the node where the command was issued.

Note: In environments that do not support clustering, use of the /CLUSTER qualifier will cause the relevant command to be executed on the local node only.

/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 TXs on this channel will be coordinated by the FTM. If this qualifier is set, then calls to rtr_start_tx on this channel must supply a value for the jointxid parameter, which is the TXID of the TX.

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

It is recommended that operators or script programs using nested transactions 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, then 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 in order that 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 then 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 may 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 one of 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 then 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 then 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 use of 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 then 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.

---

Previous

Next

Contents

Index