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

Previous | Contents | Index

Example 2-3 shows the data type that is returned in the user buffer with message types `rtr_mt_accepted`, `rtr_mt_rejected`, `rtr_mt_opened` and `rtr_mt_closed`. You can find the meaning of `rtr_status_t` using the call `rtr_error_text` .

Example 2-3 Type rtr_status_data_t

                                        /*  Type returned with rtr_mt_rejected,*/
        typedef struct                  /*  rtr_mt_accepted, rtr_mt_opened     */
        {                               /*  and rtr_mt_closed messages.        */
            rtr_status_t    status;     /*  RTR status                         */
            rtr_reason_t    reason;     /*  User-supplied reason               */
        } rtr_status_data_t;

# 2.12 RTR Events

What are events?

An event in RTR is a trigger that causes a notification (also called a "broadcast") to be sent to the application that subscribed to the event. RTR Events are created only by RTR and are used internally by RTR to help manage activities such as site failover. Application developers may subscribe to RTR Events to activate certain processing in their application. User Events are also available to enable application developers to send event notification or broadcast messages to other RTR applications. RTR provides the call `rtr_broadcast_event` to enable an application developer to trigger a User Event.

Events have special characteristics and restrictions:

- Event notification is delivered on a subscription basis using information supplied on the `rtr_open_channel` call.
- Events are not transactional and should not be used to transmit information that is, or will be, part of an RTR transaction.
- A user application can turn on or off the reception of any events, both RTR and user events.
- Events can only be transmitted within the RTR facility in which they are defined. Events cannot be sent between facilities or outside RTR.
- Event notification may include an optional message, which has a size limit of 64K.
- User Events can only be transmitted from frontend-to-backend or from backend-to-frontend. User Events cannot be used for peer-to-peer communication such as from frontend-to-frontend or from backend-to-backend.
- RTR Events are transmitted from RTR-to-frontend or RTR-to-backend.

The list below shows the RTR Events that are available for subscription. These events can be grouped in four basic categories:

- Shadow node activity (failover, failback, recovery complete)
- Standby node activity (become active, become standby, recovery complete)
- Changes in facility state and participants (clients/routers/servers entering or exiting the facility)
- Changes in configuration of partition key ranges (server available, server not available)

## 2.12.1 RTR Event Names and Numbers

RTR sends events to the server either inside or outside a transactional boundary. A transaction is considered to start on receipt of an `rtr_mt_msg1` or `rtr_mt_msg1_uncertain` message, and to end when the transaction is accepted or rejected (receipt of an `rtr_mt_accepted` or `rtr_mt_rejected` message). Events containing information about primary, secondary, or standby servers could arrive outside a transactional boundary. Gain and loss events arrive inside transactional boundaries.

Table 2-5 lists the RTR events that can be received on a channel (associated with the `rtr_mt_rtr_event` message type). Events are listed in order of event number. See the description for `rtr_open_channel` in Chapter 3, RTR Call Reference, for further information.

Table 2-5 RTR Event Names and Numbers
Event Name | Event Number | Description
--- | --- | ---
RTR_EVTNUM_FACREADY | 96 | The facility has become operational.
RTR_EVTNUM_FACDEAD | 97 | The facility is no longer operational.
RTR_EVTNUM_FERTRGAIN | 98 | Frontend link to current router established.
RTR_EVTNUM_FERTRLOSS | 99 | Frontend link to current router lost.
RTR_EVTNUM_RTRBEGAIN | 100 | Current router established link to a backend.
RTR_EVTNUM_RTRBELOSS | 101 | Current router lost link to a backend.
RTR_EVTNUM_KEYRANGEGAIN | 102 | Server(s) for new routing key range are now available.
RTR_EVTNUM_KEYRANGELOSS | 103 | No more servers remain for a particular routing key range.
RTR_EVTNUM_BERTRGAIN | 104 | Backend established link to a router.
RTR_EVTNUM_BERTRLOSS | 105 | Backend lost link to a router.
RTR_EVTNUM_RTRFEGAIN | 106 | Router established link to a frontend.
RTR_EVTNUM_RTRFELOSS | 107 | Router lost link to a frontend.
RTR_EVTNUM_SRPRIMARY | 108 | Server has become primary. 1
RTR_EVTNUM_SRSTANDBY | 109 | Server has become standby.
RTR_EVTNUM_SRSECONDARY | 110 | Server in a shadow pair has become secondary. 1
RTR_EVTNUM_SRSHADOWLOST | 111 | Server in a shadow pair lost its shadow partner. 2
RTR_EVTNUM_SRSHADOWGAIN | 112 | Server in a shadow pair acquired a shadow partner.
RTR_EVTNUM_SRRECOVERCMPL | 113 | Server completed recovery processing.

1 RTR will generate this event between transactional boundaries. This event can be useful to signal the application to begin activities that should only be performed by the primary system, such as processing credit card debits.
2 This event signals that this system is entering remember mode for future catchup of the shadow partner.

## 2.12.2 Developing Applications to Use Events

Subscribing to Events

RTR Events can be used for triggering special application processing based on a change in RTR system status, or for sending notification to the system operator after certain application or RTR conditions that require intervention.

User Events can be used for actions such as broadcasting stock prices to update a price table, or triggering special application processing such as handling a failed transaction. User events can be used to send a message in a one-to-one or a one-to-many method.

Event subscription is established when the `rtr_open_channel` call is executed. See the RTR `rtr_open_channel` call description for details on this call. The `rtr_open_channel` call is as follows:

    rtr_open_channel (channel,
                      flags,
                      facnam,
                      rcpnam,
                      pevtnum,
                      access,
                      numseg,
                      pkeyseg)

Two parameters on the call are used to establish event subscription: rcpnam and pevtnum.

rcpnam is a pointer to an optional channel name for receiving event messages. If a User Event is sent to a particular channel name, only those subscribers that match both name AND event number are notified. For example, a client channel named "New York" and a client channel named "Hong Kong" could both subscribe to receive User Event number 999. If event 999 was triggered by the server using the channel named "Hong Kong," the event would be received only by the "Hong Kong" client. Specify RTR_NO_RCPNAM for this parameter if a name is not used. This parameter is case sensitive.

pevtnum is a pointer to lists of RTR and User event numbers to which the channel wants to subscribe. These lists use the numeric values of the events shown in Table 2-5. Use the special symbols in Table 2-6 to construct the event list.

Table 2-6 Symbols for Event Lists
Symbol | Description
--- | ---
RTR_NO_PEVTNUM | No events selected.
RTR_EVTNUM_USERDEF | Begin User Event list.
RTR_EVTNUM_RTRDEF | Begin RTR Event list.
RTR_EVTNUM_ENDLIST | End of entire list.
RTR_EVTNUM_UP_TO | Specifies an event range in the form x RTR_EVTNUM_UP_TO y.
RTR_EVTNUM_USERBASE | Smallest User Event number (0).
RTR_EVTNUM_USERMAX | Largest User Event number (250).
RTR_EVTNUM_RTRBASE | Smallest RTR Event number.
RTR_EVTNUM_RTRMAX | Largest RTR Event number.

Example 2-4 illustrates how to set up a list of all User Event numbers for the `rtr_open_channel` call.

Example 2-4 User Event Example

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

Example 2-5 illustrates how to set up a list of all RTR and User Event numbers for the `rtr_open_channel` call.

Example 2-5 RTR and User Event Example

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

Sending Events

A broadcast event is triggered when the `rtr_broadcast_event` call is executed. See the `rtr_broadcast_event` call description for details on this call. The `rtr_broadcast_event` call syntax is as follows:

    rtr_broadcast_event (channel,
                         flags,
                         pmsg,
                         msglen,
                         evtnum,
                         rcpspc,
                         msgfmt)

The significant parameters on this call are:

> channel is the channel identifier returned from the `rtr_open_channel` call.
> pmsg is a pointer to the message to be broadcast.
> msglen is the length in bytes of the message.
> evtnum is the User Event number that the application developer has assigned to this event.
> rcpspc is the optional recipient channel name that can be specified with the rcpnam parameter on the `rtr_open_channel` call.

Example 2-6 shows an example of an `rtr_broadcast_event` call.

Example 2-6 Broadcast Event Example

    if ( bServerShutdown )
    {
    sts = rtr_broadcast_event (
        /* channel */ BY_CHAN_CLIENT(cCurrentChannel,client)->chan,
        /* flags   */ RTR_NO_FLAGS,
        /* pmsg    */ &msgbuf,
        /* msglen  */ cbTotalSize,
        /* evtnum  */ USER_EVT_SHUTDOWN,
        /* rcpnam  */ "*",
        /* msgfmt  */ szMsgFmt);

    exit_if_error ( "rtr_broadcast_event", sts );
    }

Receiving Events

Any RTR transaction, RTR Event, or User Event can be received when the application executes the `rtr_receive_message` call. See the RTR `rtr_receive_message` call description for details on this call. The `rtr_receive_message` call syntax is as follows:

    rtr_receive_message (channel,
                         flags,
                         prcvchan,
                         pmsg,
                         maxlen,
                         timoutms,
                         pmsgsb)

The significant parameters on this call are:

> channel is the channel on which the message is received.
> pmsg is a pointer to an application buffer where the message is written.
> maxlen is the maximum length of the application buffer in bytes.
> pmsgsb is a pointer to a message status block describing the received message.

Notification of Events

If the application has subscribed to events, any call to `rtr_receive_message` can return an event notification, either an RTR Event notification or a User Event notification. The results are described in Table 2-7.

Table 2-7 Event Notifications
If this notification is delivered: | the `rtr_receive_message` call returns a message of type: | and the user/application buffer contains the associated:
--- | --- | ---
RTR Event | `rtr_mt_rtr_event` | event message
User Event | `rtr_mt_user_event` | user broadcast message

When RTR receives a role-gain or role-loss event, it provides both the facility name and the nodename of the node (FE, TR, or BE) that sent the event notification. Only events for roles (FE, TR, BE) provide this additional information. For a definition of roles in RTR, see the Reliable Transaction Router Getting Started manual and the RTR Glossary. In RTR, only facilities have roles. Example 2-7 shows the results of a frontend gain event (FEGAIN, event 106) and a frontend loss event (FELOSS, event 107).

Example 2-7 Frontend Gain and Loss Examples

    RTR> call rece
    %RTR-S-OK, normal successful completion
     channel name:  RTR$DEFAULT_CHANNEL
     msgsb
       msgtype:     rtr_mt_rtr_event
       msglen:      34
       evtnum:      106     (RTR_EVTNUM_RTRFEGAIN)
     message
       facility:    RTR$DEFAULT_FACILITY
           link:    nodename
    RTR> call rece
    %RTR-S-OK, normal successful completion
     channel name:  RTR$DEFAULT_CHANNEL
     msgsb
       msgtype:     rtr_mt_rtr_event
       msglen:      34
       evtnum:      107     (RTR_EVTNUM_RTRFELOSS)
     message
       facility:    RTR$DEFAULT_FACILITY
           link:    nodename

Returned Event Data

Two RTR Events return key range data to the application:

Table 2-8 Events that Return Key Range Data
Event Name | Event Number
--- | ---
RTR_EVTNUM_KEYRANGEGAIN | 102
RTR_EVTNUM_KEYRANGELOSS | 103

The key range data are received in the message returned to the application, with the length of the message specified in the message status block ( `msgsb` ). For example, the following illustrates `rtr_receive_message` usage.

    rtr_status_t
    rtr_receive_message (
      rtr_channel_t      *pchannel,
      rtr_rcv_flag_t     flags,
      rtr_channel_t      *p_rcvchan,
      rtr_msgbuf_t       pmsg,
      rtr_msglen_t       maxlen,
      rtr_timout_t       timoutms,
      rtr_msgsb_t        *p_msgsb
      )

The message status block pointed to by `*p_msgsb` has the following structure:

       typedef struct {
         rtr_msg_type_t   msgtype;
         rtr_usrhdl_t     usrhdl;
         rtr_msglen_t     msglen;
         rtr_tid_t        tid;
         rtr_evtnum_t     evtnum;
       }rtr_msgsb_t;

When an event number is 102 or 103, RTR returns key range data (the low and high bounds) in the message, padded as required for data marshalling and interoperability. The key range data can be examined by the application. For more detail on data marshalling and formatting, see Section 2.14.

Bounds data are treated as if defined as a structure. For example, if there are two key segments defined as `rtr_uns_8_t` and `rtr_uns_32_t` , then the bounds data are copied to outbuf as if they were contained in the structure; that is, the 32-bit ints are correctly aligned in the structure and the structure size is a multiple of four. For example,

           struct{
             rtr_uns_8_t  low_bound_1;
             rtr_uns_32_t low_bound_2;
             rtr_uns_8_t  hi_bound_1;
             rtr_uns_32_t hi_bound_2;
           }

The "four-byte-alignment-fits-all" requirement is enforced for interoperability; no padding is allowed.

Example 2-8, which can be run manually from the RTR CLI, illustrates the return of key range data with the RTR Event `RTR_EVTNUM_KEYRANGELOSS` . The RTR CLI interprets the format of this message as appropriate. In Example 2-8, the format is string or ASCII data, the default.

Example 2-8 Returned Event Key Range Data Example

    RTR> crea fac jws/all=sucre
    %RTR-S-FACCREATED, facility jws created
    RTR> crea part ab/fac=jws/noshadow/nostandby-
     /key1=(type=string,length=2,offset=0,low="AB",high="CD")
    %RTR-I-PRTCREATE, partition created
    RTR> rtr_open/chan=s/server/noshadow/nostandby/part=ab/fac=jws
    %RTR-S-OK, normal successful completion
    RTR> rtr_rec/chan=s/time=10
    %RTR-S-OK, normal successful completion
     channel name:  S
     msgsb
       msgtype:     rtr_mt_opened
       msglen:      8
     message
       status:      normal successful completion
       reason:      0x00000000
    RTR> rtr_open/chan=c/client/event=(102,103)/fac=jws
    %RTR-S-OK, normal successful completion
    RTR> rtr_rec/chan=c/time=10
    %RTR-S-OK, normal successful completion
     channel name:  C
     msgsb
       msgtype:     rtr_mt_opened
       msglen:      8
     message
       status:      normal successful completion
       reason:      0x00000000
    RTR> rtr_close/chan=s
    %RTR-S-OK, normal successful completion
    RTR> rtr_rec/chan=c/time=10
    %RTR-S-OK, normal successful completion
     channel name:  C
     msgsb
       msgtype:     rtr_mt_rtr_event
       msglen:      4
       evtnum:      103     (RTR_EVTNUM_KEYRANGELOSS)
     message
       ks_lo_bound: 0x4241
       ks_hi_bound: 0x4443
    RTR> reca
    RTR> rtr_rec/chan=c/time=10
    %RTR-E-TIMOUT, call to rtr_receive_message timed out

Design consideration: When an RTR application executes an `rtr_receive_message` call, the programmer could incorrectly anticipate that a particular message type may be received and only write instructions to respond to the expected message. However, an RTR or User Event could be received on any instance of the `rtr_receive_message` call (as could other unanticipated RTR messages). Therefore, as a general application design guideline, the application developer should always program the application so that it can properly handle any type of message that could be received by the `rtr_receive_message` call.

Events are delivered in the order in which they are broadcast; therefore event serialization will be preserved for a particular user. However, RTR does not enforce any particular serialization across different subscribers, so different subscribers could receive event notifications in any order.

Example 2-9 shows an `rtr_receive_message` call in use.

Example 2-9 Receive Message Example

    status = rtr_receive_message( &channel,
                                  RTR_NO_FLAGS,
                                  RTR_ANYCHAN,
                                  &receive_msg,
                                  RTR_ANYCHAN,
                                  &receive_msg,
                                  sizeof(receive_msg),
                                  receive_time_out,
                                  &msgsb);

    check_status( "rtr_receive_message", status );

Previous | Next | Contents | Index