The RTR transaction id is a unique number generated by RTR for each transaction in the RTR virtual network.

In addition, rtr_get_tid() is capable of returning transaction identifiers associated with XA and DECdtm managed transactions when RTR is operating with either of these transaction managers. Return Value
A value indicating the status of the routine. Possible status values are:

RTR_STS_DTXNOSUCHXID	No distributed transaction id found for this channel
RTR_STS_INVARGPTR	Invalid parameter address specified on last call
RTR_STS_INVCHANNEL	Invalid channel argument
RTR_STS_INVFLAGS	Invalid flags argument
RTR_STS_NOCURROU	No router currently available for this frontend
RTR_STS_NOSRVAVL	Service not yet available
RTR_STS_OK	Normal successful completion
RTR_STS_TXNOTACT	No tx currently active on chan No transaction currently active on this channel.

Example

rtr_xid_tid xa_tid; char global_id_buff[64]; char branch_qual_buff[64]; int i, j; /* The server executed an rtr_receive_message. In the * rtr_msgsb_t structure, the msgtype field equals * rtr_mt_msg1_uncertain. This indicates that a recovery * is in process, and RTR did not get a confirmation * that the current transaction had been * completed. RTR is now `replaying' the transaction, * and this is the first message in that transaction. * * Get the transaction id. */ status = rtr_get_tid( &channel, RTR_F_TID_XA, &xa_tid ); check_status(status); /* * Isolate the information in the xa_tid structure. */ if (xa_tid.formatID != RTR_XID_FORMATID_RTR_XA) { printf(errLog, "This channel only for X/Open transactions"); exit(BAD_TXTYPE_CHAN); ) for (i = 0; i < xa_tid.gtrid_length; i++) global_id_buff[i] = xa_tid.data[i]; global_id_buff[i] = 0; for (j = i; j < (xa_tid.gtrid_length + xa_tid.bqual_length); j++) branch_qual_buff[j - i] = xa_tid.data[j]; branch_qual_buff[j] = 0; /* Query the database to see if the transaction whose global_id * and branch qualifier match these had been committed. If so, * ignore; otherwise, continue as though this were the first * time the message was received. */

Open a channel to allow for communication with other applications.

Syntax

status = rtr_open_channel (pchannel, flags, facnam, rcpnam, pevtnum, access, numseg, pkeyseg)

Argument	Data Type	Access
status	rtr_status_t	write
pchannel	rtr_channel_t	write
flags	rtr_ope_flag_t	read
facnam	rtr_facnam_t	read
rcpnam	rtr_rcpnam_t	read
pevtnum	rtr_evtnum_t	read
access	rtr_access_t	read
numseg	rtr_numseg_t	read
pkeyseg	rtr_keyseg_t	read

C Binding

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
)

Arguments

pchannel

A pointer to a location where the channel is returned.

flags

Flags that specify options for the call.

Defined flags are shown in Table 3-6, Table 3-7, and Table 3-8.

Table 3-6 Open Channel Flags (One Required)

Flag	Description
RTR_F_OPE_CLIENT	Indicates that the channel will be used as a client.
RTR_F_OPE_CREATE_PARTITION	Requests that a partition be created. Specify partition key segments and name with the pkeyseg argument. The name is passed using an rtr_keyseg_t descriptor where ks_type = rtr_keyseg_partition and ks_lo_bound point to the name string. On a successful call, a channel is opened on which the completion status can be read from the ensuing message of type rtr_mt_closed . The completion status is found in the status field of the message data of rtr_status_data_t .
RTR_F_OPE_DELETE_PARTITION	Requests that a partition be deleted. Specify partition or name key segments with the pkeyseg argument. The name is passed using an rtr_keyseg_t descriptor where ks_type = rtr_keyseg_partition and ks_lo_bound points to the name string. On a successful call, a channel is opened on which the completion status can be read from the ensuing message of type rtr_mt_closed . The completion status is found in the status field of the message data of rtr_status_data_t .
RTR_F_OPE_SERVER	Indicates that the channel will be used as a server. numseg and pkeyseg must be specified for all servers except call-out servers.

Note Calling rtr_open_channel() with the RTR_F_OPE_FOREIGN_TM flag set causes a local RTR journal scan to occur, if a journal has not already been opened on that node.

The flags in Table 3-8 apply only if RTR_F_OPE_SERVER is set.

Note Server attributes such as key range definition, shadow and standby flags, can be defined and modified outside the application program by the system manager. A server should preferably use specific flags.

Table 3-7 Open Channel Client Flags

Flag	Description
RTR_F_OPE_FOREIGN_TM	Valid for client channels only. This indicates that the global coordinating transaction manager is a foreign transaction manager (non-RTR), and that all transactions on this channel will be coordinated by the foreign transaction manager. If this flag is set, then calls to rtr_start_tx on this channel must supply a value for the jointxid parameter, which is the ID of the parent transaction.

Table 3-8 Open Channel Server Flags

Flag	Description
RTR_F_OPE_BE_CALL_OUT	The server is a backend callout server. By default a server is not a backend callout server.
RTR_F_OPE_DECDTM_MANAGED	Indicates that DECdtm manages the channel. Valid only for server channels.
RTR_F_OPE_EXPLICIT_ACCEPT	A call to rtr_receive_message() is not to be interpreted as an implicit call of rtr_accept_tx() .
RTR_F_OPE_EXPLICIT_PREPARE	The server needs to receive an explicit prepare message from RTR when each transaction has been completely received. By default, no prepare message is generated.
RTR_F_OPE_NOCONCURRENT	The server may not be concurrent with other servers. By default a server may have other concurrent servers.
RTR_F_OPE_NOSTANDBY	The server may not be (or have) standby(s). By default, servers may have standby(s).
RTR_F_OPE_SHADOW	The server is part of a shadow pair. By default a server is not part of a shadow pair.
RTR_F_OPE_TR_CALL_OUT	The server is a router callout server. By default a server is not a router callout server.
RTR_F_OPE_XA_MANAGED	Associates the channel with the XA protocol.

facnam

A null-terminated string containing the facility name. A facility name is required.

rcpnam

An optional null-terminated string containing the name of the channel. This name is used to receive named event messages. Specify RTR_NO_RCPNAM when named event recipients are not used.

Note To receive named events, the correct event number must also be specified.

These names are additional qualifiers on the event delivery, are matched to the sender name, and are ANDed to the event number for delivery. For example, a client "New York" and a client "Hong Kong" could be set up to both receive event number 100. If the event 100 was generated by the server with the name "Hong Kong," the event would not be received by the "New York" client.

rcpnam is case sensitive.

pevtnum

Optional pointer to a list of event numbers to which the channel wishes to subscribe. There are two types of event: user events and RTR events. This parameter is used to specify all user and RTR events that the channel is to receive.

Start the list of user event numbers with RTR_EVTNUM_USERDEF , and the list of RTR event numbers with RTR_EVTNUM_RTRDEF . End the entire list with RTR_EVTNUM_ENDLIST . Specify a range of event numbers using the constant RTR_EVTNUM_UP_TO between the lower and upper (inclusive) bounds. For example, to specify the list of all user event numbers, use:

rtr_evtnum_t all_user_events[]={ RTR_EVTNUM_USERDEF, RTR_EVTNUM_USERBASE, RTR_EVTNUM_UP_TO, RTR_EVTNUM_USERMAX, RTR_EVTNUM_ENDLIST } ;

For example, to specify the list of all event numbers, use:

rtr_evtnum_t all_events[]={ RTR_EVTNUM_USERDEF, RTR_EVTNUM_USERBASE, RTR_EVTNUM_UP_TO, RTR_EVTNUM_USERMAX, RTR_EVTNUM_RTRDEF, RTR_EVTNUM_RTRBASE, RTR_EVTNUM_UP_TO, RTR_EVTNUM_RTRMAX, RTR_EVTNUM_ENDLIST } ;

Specify RTR_NO_PEVTNUM when the channel is to receive no events. Event names and numbers are listed in Table 2-5, RTR Event Names and Numbers.

access

An optional null-terminated string containing the access parameter. The access parameter is a security key used to authorize access to a facility by clients and servers. Specify RTR_NO_ACCESS when there is no access string.

numseg

The number of key segments defined. The numseg parameter is not required for client channels or callout server channels. (Callout servers always receive all messages.) Specify RTR_NO_NUMSEG when defining client channels.

A key can consist of up to RTR_MAX_NUMSEG segments.

pkeyseg

Pointer to the first block of key segment information. Only the first numseg elements are used. The structure of rtr_keyseg_t is:

typedef struct /* RTR Key Segment Type */ { rtr_keyseg_type_t ks_type ; /* Key segment data type */ rtr_uns_32_t ks_length ; /* Key segment length (bytes) */ rtr_uns_32_t ks_offset ; /* Key segment offset (bytes) */ void *ks_lo_bound ; /* Ptr to key segment low bound */ void *ks_hi_bound ; /* Ptr to key segment high bound */ } rtr_keyseg_t ;

The data type of a key segment can be one of the following:

Table 3-9 Key Segment Data Type

Data Type	Description
rtr_keyseg_foreign_tm_id	Foreign transaction manager identifier.
rtr_keyseg_partition	Partition name, the name of the partition assigned.
rtr_keyseg_rmname	Resource manager name, the name of the foreign resource manager.
rtr_keyseg_signed	Signed
rtr_keyseg_string	ASCII string
rtr_keyseg_unsigned	Unsigned

The pkeyseg parameter is not required for client channels or callout server channels. (Callout servers always receive all messages.) Specify RTR_NO_PKEYSEG when defining client channels. The ks_type field can be one of the data types shown in Table 3-9.

If an rtr_keyseg_t of rtr_keyseg_string is specified, then it is up to the application programmer to ensure that the key value is valid for the complete range of the key length.

For example, if the key length is 4, and server code includes a statement like:

strcpy(keyvalue, "k");

with keyvalue passed as one of the bounds values, then potentially the bound value can differ from one open channel call to the next, since the two bytes following the "k" will contain uninitialized values but still form part of the key-bound definition. (In this case, one should clear the keyvalue buffer before copying the bounds values.)

A call to rtr_open_channel() may be used to create a named partition or to open a server channel associated with an existing named partition. To do this, supply a partition name when opening a server channel. The pkeyseg argument specifies an additional item of type rtr_keyseg_t , assigning the following values:

• ks_type = rtr_keyseg_partition , indicating that a partition name is being passed
• ks_lo_bound should point to the null-terminated string to use for the partition name

Note When using the RTR CLI, if a key-bound value length is less than the key length, the key bound is automatically null-padded to the required length. For example, RTR> call rtr_open_channel/server/type=string/low=1/high=2 Since no key length is specified, the length defaults to four. The low and high bound values are automatically null-padded to four bytes by RTR.

The key segment array may not contain more than RTR_MAX_NUMSEG elements.

Description

The rtr_open_channel() call opens a channel for communication with other applications on a particular facility.

The caller of rtr_open_channel() specifies the role (client or server) for which the channel is used.

For use with XA:

1. Change the rtr_open_channel() call as described in the call description.
2. Remove unnecessary SQL calls from server code such as commit or rollback in a two-phase commit environment. If these calls remain in your application code, they may cause vendor-specific warnings.
3. RTR allows only one RM instance to be registered for each RTR partition.
4. Only one transaction is processed on an RTR channel at any given time. This implies that a server process or a thread of control can only open one channel to handle a single XA request.
5. Using a multi-threaded server application is strongly recommended for better throughput.

Examples

Examples show the following:

• A simple client application
• A simple server application
• An application using XA
• An application using partition names

Example 3-1 Client Application

rtr_channel_t channel; rtr_status_t status; rtr_string_t user_name; /* Get the user's name through login or other user interface */ user_name = <input data> /* Open client application's channel to the router; * use the facility named `CCardPurchases', and the user's * name to identify this client. * * This client will receive messages only, no events, * and is going to use a foreign transaction manager * which implements the X/Open standard transaction * formats. */ status = rtr_open_channel( &channel, RTR_F_OPE_CLIENT | RTR_F_OPE_FOREIGN_TM, "CCardPurchases", user_name, RTR_NO_PEVTNUM, NULL, RTR_NO_NUMSEG , RTR_NO_PKEYSEG ); check_status(status);

Example 3-2 Server Application

*************************************************************************** /* Open a channel in a server application. This server will * handle only records where the last name begins with A. * It also wants an explicit message sent when it is time * to prepare the transaction, and one when it is time to * vote whether to accept or reject the transaction. */ rtr_channel_t channel; rtr_status_t status; rtr_keyseg_t p_keyseg[1]; rtr_string_t last = "A"; /* * Use this rtr_keyseg_t structure to define this server as * handling only those records whose last name begins * with `A'. */ p_keyseg[0].ks_type = rtr_keyseg_string; p_keyseg[0].ks_length = 1; p_keyseg[0].ks_offset = 0; p_keyseg[0].ks_lo_bound = last; p_keyseg[0].ks_hi_bound = last; /* Open the channel as a server which wants explicit ACCEPT and * PREPARE messages. It is a member of the CcardPurchases * facility, accepts no events (only messages) and we are * sending 1 rtr_keyseg_t structure which defines those * messages to be handled by this server. * * Note also that we are specifying that this channel * will be `XA managed'; that is, the transaction manager * will be one which implements the X/Open standard. */ status = rtr_open_channel( &channel, RTR_F_OPE_SERVER | RTR_F_OPE_EXPLICIT_ACCEPT | RTR_F_OPE_EXPLICIT_PREPARE | RTR_OPE_XA_MANAGED, "CCardPurchases", NULL, RTR_NO_PEVTNUM, NULL, 1, p_keyseg); check_status(status);

---

Previous

Next

Contents

Index