| Previous | Contents | Index |
#define reunion_announcement 10 /* In user .h file. */ rtr_msg_buf_t reunion_msg = "Jones family reunion today!"; rtr_rcpspc_t recipients = "*Jones"; rtr_timout_t = 1000 /* 1 second to time out */ /* * If today is the date of the Jones family reunion, tell * any client whose last name is Jones that they need to * be there! */ if (strcmp(today, reunion_date) == 0) { status = rtr_ext_broadcast_event( &channel, RTR_NO_FLAGS, reunion_msg, strlen(reunion_msg), reunion_announcement, recipients, RTR_NO_MSGFMT, timoutms ); check_status( status ); }
rtr_broadcast_event()
rtr_receive_message()
rtr_open_channel()
Return the transaction ID for the current transaction.
status = rtr_get_tid (channel, flags, ptid)
Argument Data Type Access status rtr_status_t write channel rtr_channel_t read flags rtr_tid_flag_t read ptid void* write
rtr_status_t rtr_get_tid (
rtr_channel_t channel ,
rtr_tid_flag_t flags ,
void *ptid
)
channel
The channel identifier (returned previously by rtr_open_channel() ).flags
Flags that specify options for the call.Table 3-4 shows the flags that are defined.
Table 3-4 Get TID Flags Flag Pointer Data Type Returns RTR_NO_FLAGS rtr_tid_t RTR transaction ID RTR_F_TID_RTR rtr_tid_t RTR transaction ID RTR_F_TID_XA rtr_xid_t XA transaction ID RTR_F_TID_DDTM rtr_ddtmid_t DECdtm transaction ID If you do not require any flags, specify RTR_NO_FLAGS for this argument. Specifying RTR_NO_FLAGS is equivalent to specifying RTR_F_TID_RTR ; this capability is maintained for compatibility with RTR versions earlier than RTR Version 3.2.
The structure rtr_xid_t is based on the X/Open XA specification and is defined as follows:
typedef struct rtr_xid_t { long formatID; /* format identifier */ long gtrid_length; /* value from 1 through 64 */ long bqual_length; /* value from 1 through 64 */ char data[RTR_XIDDATASIZE]; } rtr_xid_t;The XID structure contains a format identifier, two length fields and a data field. The data field comprises at most two contiguous components: a global transaction ID (gtrid) and a branch qualifier (bqual).
The gtrid_length field specifies the number of bytes (1-64) that constitute gtrid, starting at the first byte in data (that is, data[0]). The bqual_length field specifies the number of bytes (1-64) that constitute bqual, starting at the first byte after gtrid (that is, data[gtrid_length]). Neither component in data is null terminated. Any unused bytes in data are undefined.
The contents of data depend on the format of the transaction ID (TX ID), which is specified by the format identification field. Some valid format ID values are shown in Table 3-5.
Table 3-5 Format Identification and Data Content Format Identification Data Content RTR_XID_FORMATID_NONE Null XID. No XID has been returned. This will be the value if the call to rtr_get_xid / rtr_get_tid returns an error, for example. RTR_XID_FORMATID_OSI_CCR The XID is specified using the naming rules specified for OSI CCR atomic action identifiers. RTR does not use this convention directly, but such a transaction ID format can be returned if some other associated transaction or resource manager uses this convention. If OSI CCR (ISO standard) naming is used, then the XID's formatID element should be set to 0 (zero); if another format is used, then the formatID element should be greater than 0. A value of -1 in formatID means that the XID is null.
RTR_XID_FORMATID_RTR Identifies an RTR transaction ID. In this case, the gtrid_length is 28 and bqual_length is zero. The contents of data can be interpreted using the format defined by rtr_tid_t . Note that one should still use the rtr_get_tid call to get the RTR transaction ID for a transaction active on a channel. The rtr_get_xid call could be used, for example, if a nested transaction is started where the foreign transaction manager is also RTR. RTR_XID_FORMATID_DDTM Identifies a transaction ID for a transaction that uses a resource managed by DECdtm. The gtrid_length field is 16, and bqual_length is 0. RTR_XID_FORMATID_RTR_XA Identifies a transaction ID for a transaction started using an XA resource manager.
ptid
A pointer to where the unique transaction ID for the current transaction is returned. Data type depends on any flag that has been set; see Table 3-4.
rtr_get_tid() returns the RTR transaction ID for the current transaction.Return ValueThe 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.
| RTR_STS_CHANOTOPE | Channel not opened |
| 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_NOXACHAN | No XA channel 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. */
Retrieve the optional user-defined context associated with the specified RTR channel.
user_context = rtr_get_user_context (channel )
Argument Data Type Access user_context rtr_usrctx_t write channel rtr_channel_t read
rtr_usrctx_t rtr_get_user_context (
rtr_channel_t channel
)
channel
The channel whose context is to be returned.Usage example:
struct { rtr_channel_t chan; int state, ... } context[10]; *ctx; rtr_channel_t chan; rtr_open_channel(&ctx[4].chan, ...); rtr_receive_message(&chan, ...); ctx = rtr_get_user_context(chan); if (ctx->state) { ... }
The rtr_get_user_context() call retrieves the user context for a channel. The default value of the user context is the value of the pchannel argument passed to RTR at the time the channel was opened using one of the following calls or routines:Return Valuertr_open_channel()
rtr_request_info()
rtr_set_info()The context value may optionally be changed at any later time using rtr_set_user_context() , provided the channel is still open.
The routine returns the user context of the specified channel.
| RTR_NO_USER_CONTEXT | The specified channel was not declared or has closed |
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_RECEIVE_REPLIES The server, a backend callout server, can receive server-to-client messages. 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 recipient. This name is used to receive named event messages. Specify RTR_NO_RCPNAM when named event recipients are not used.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.
Note
- To receive named events, the correct event number must also be specified. The event number (evtnum) must be specified by both the sender (rcpspc) and the recipient (rcpnam).
- Both rcpnam and rcpspc are case sensitive.
- Both rcpnam and rcpspc default to the case-insensitive channel name if no explicit rcpnam or rcpspc is provided.
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:
Previous Next Contents Index