# hp Reliable Transaction Router
C Application Programmer's
Reference Manual

Previous | Contents | Index

## Example

>     #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 );
>     }

### See Also

> `rtr_broadcast_event()`
> `rtr_receive_message()`
> `rtr_open_channel()`

# rtr_get_tid

> Return the transaction ID for the current transaction.

## Syntax

> 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

## C Binding

> rtr_status_t rtr_get_tid (

> rtr_channel_t channel ,
> rtr_tid_flag_t flags ,
> void *ptid
> )

## Arguments

> ### 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.

## Description

> `rtr_get_tid()` returns the RTR transaction ID for the current transaction.

> 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_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

## 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.
>      */

# rtr_get_user_context

> Retrieve the optional user-defined context associated with the specified RTR channel.

## Syntax

> user_context = rtr_get_user_context (channel )

> Argument | Data Type | Access
> --- | --- | ---
> user_context | rtr_usrctx_t | write
> channel | rtr_channel_t | read

## C Binding

> rtr_usrctx_t rtr_get_user_context (

> rtr_channel_t channel
> )

## Arguments

> ### 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) { ... }

## Description

> 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:

> > `rtr_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.

Return Value
A value indicating the status of the routine. Possible status values are:

RTR_NO_USER_CONTEXT | The specified channel was not declared or has closed

# rtr_open_channel

> 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.

> 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