Previous | Contents | Index |
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 transaction currently active on this channel |
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.
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
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
)
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.
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.
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-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.
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, because 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
Because 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.
The rtr_open_channel() call opens a channel for communication with other applications on a particular facility.Return Value A value indicating the status of the routine. Possible status values are:The caller of rtr_open_channel() specifies the role (client or server) for which the channel is used.
- Change the rtr_open_channel() call as described in the call description.
- 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.
- RTR allows only one RM instance to be registered for each RTR partition.
- 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.
- Using a multithreaded server application is strongly recommended for better throughput.
RTR_STS_DTXOPENFAIL | Distributed transaction request to open a session to the RM has failed |
RTR_STS_DUPLRMNAME | Duplicate rm partition name |
RTR_STS_INSVIRMEM | Insufficient virtual memory |
RTR_STS_INVACCESS | Invalid access argument |
RTR_STS_INVCHANNEL | Invalid pchannel argument |
RTR_STS_INVEVTNUM | Invalid evtnum argument |
RTR_STS_INVFACNAM | Invalid FACNAM argument |
RTR_STS_INVFLAGS | Invalid flags argument |
RTR_STS_INVKSLENGTH | Invalid ks_length argument |
RTR_STS_INVKSTYPE | Invalid ks_type argument |
RTR_STS_INVNUMSEG | Invalid numseg argument |
RTR_STS_INVPKEYSEG | Invalid pkeyseg argument |
RTR_STS_INVRCPNAM | Invalid rcpnam argument |
RTR_STS_INVRMNAME | Invalid resource manager name |
RTR_STS_INVSVRCLIFLG | Either both /Client and /Server flags were supplied or they were missing |
RTR_STS_JOUNOTFOU |
Journal not found
An attempt was made to open a channel for use by a foreign transaction manager, but no RTR journal was found on this node. |
RTR_STS_MISSINGREQFLG | One of the required flags (Server, Client, Create_Partition, or Delete_Partition) is missing |
RTR_STS_NOACP | No RTRACP process available |
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_RMSTRINGLONG | Resource manager open or close string too long |
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 * that 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);
Previous Next Contents Index