| Previous | Contents | Index |
Close a previously opened channel.
status = rtr_close_channel (channel, flags)
Argument Data Type Access status rtr_status_t write channel rtr_channel_t read flags rtr_clo_flag_t read
rtr_status_t rtr_close_channel (
rtr_channel_t channel ,
rtr_clo_flag_t flags
)
channel
The channel identifier (returned earlier by rtr_open_channel() , or rtr_request_info() or rtr_set_info() ).flags
Flags that specify options for the call.The flag RTR_F_CLO_IMMEDIATE is defined for this call.
Normally rtr_close_channel() processes a pending transaction that was in a commit state by forgetting the transaction (removing it from the journal). To close the channel but leave transactions in the journal, use the flag RTR_F_CLO_IMMEDIATE to rtr_close_channel().
In some situations, an accepted transaction cannot be completed and replay is required. For example, a transaction may be accepted but the database becomes unavailable before the transaction is committed to the database. To deal with such a situation, an application can use the close-immediate flag RTR_F_CLO_IMMEDIATE. This closes the channel but leaves the transactions in the journal for use on replay when database access is restored.
The rtr_close_channel() call closes a previously opened channel. A channel may be closed at any time after it has been opened via rtr_open_channel() or rtr_request_info() . If the channel is a server channel, an implicit acknowledgment is sent.Return Value
| RTR_STS_OK | Normal successful completion |
| RTR_STS_INVCHANNEL | Invalid channel argument |
| RTR_STS_INVFLAGS | Invalid flags argument |
/* If the status returned by the previous call is not success, * close now, and exit the program. */ if (status != RTR_STS_OK) { printf(fpLog, "Unexpected error, must close immediately!"); status = rtr_close_channel( channel, RTR_CLO_IMMEDIATE); exit(status); } /* * Normal processing complete, close the channel. */ printf(fpLog, "Closing channel"); status = rtr_close_channel ( channel, RTR_NO_FLAGS );
Return the text associated with an RTR status value.
retval = rtr_error_text (sts)
Argument Data Type Access retval char write sts rtr_status_t read
char *rtr_error_text (
rtr_status_t sts
)
sts
The RTR error number for which the text is required.
The rtr_error_text() call returns a pointer to the text associated with an RTR error number.The text string is a constant. If an invalid value for sts is supplied, a pointer is also returned to an error text.
/* If the status returned by the previous call is not success, * print the message text to the error log, and exit. */ if (status != RTR_STS_OK) { printf(errLog, rtr_error_text(status)); exit(status); }
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-3 shows the flags that are defined.
Table 3-3 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 parameter. 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-4.
Table 3-4 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-3.
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_OK | Normal successful completion |
| RTR_STS_DTXNOSUCHXID | No distributed transaction id found for this channel |
| RTR_STS_INVCHANNEL | Invalid channel argument |
| RTR_STS_INVFLAGS | Invalid flags argument |
| RTR_STS_INVARGPTR | Invalid parameter address specified on last call |
| RTR_STS_TXNOTACT |
No tx currently active on chan
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.The flags that are defined are shown in Table 3-5 and Table 3-6.
Table 3-5 Open Channel Flags Flag Description RTR_F_OPE_CLIENT Indicates that the channel will be used as a client. 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. 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-6 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-6 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_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_DECDTM_MANAGED Indicates that DECdtm manages the channel. Valid only for server channels. 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_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 that to receive named events, the correct event number must also be specified.) Note that 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 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-7 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
Previous Next Contents Index