| Previous | Contents | Index |
Receive a message from RTR or the application.
status = rtr_receive_message (pchannel, flags, prcvchan, pmsg, maxlen, timoutms, pmsgsb)
Argument Data Type Access status rtr_status_t write pchannel rtr_channel_t write flags rtr_rcv_flag_t read prcvchan rtr_channel_t read pmsg rtr_msgbuf_t read maxlen rtr_msglen_t read timoutms rtr_timout_t read pmsgsb rtr_msgsb_t read
rtr_status_t rtr_receive_message (
rtr_channel_t *pchannel ,
rtr_rcv_flag_t flags ,
rtr_channel_t *prcvchan ,
rtr_msgbuf_t pmsg ,
rtr_msglen_t maxlen ,
rtr_timout_t timoutms ,
rtr_msgsb_t *pmsgsb
)
pchannel
The channel identifier on which the message was received.flags
No flags are currently defined. Specify RTR_NO_FLAGS for this parameter.prcvchan
A pointer to a list of channels on which a receive is required. This parameter can be used to select a subset of channels on which messages can be received. Terminate the list with RTR_CHAN_ENDLIST.If no selection is required, that is, a receive from any open channel is acceptable, specify RTR_ANYCHAN for this parameter.
pmsg
Required pointer to the user buffer where the received message is written.maxlen
Size allocated in the user buffer for received messages, in bytes.timoutms
Receive timeout specified in milliseconds. If the timeout expires, the call completes with status RTR_STS_TIMOUT.If no timeout is required, specify RTR_NO_TIMOUTMS.
pmsgsb
Pointer to a message status block describing the received message. The message status block is shown in Figure 3-1.Figure 3-1 RTR Message Status Block
typedef struct /* RTR message status block */ { rtr_msg_type_t msgtype; rtr_usrhdl_t usrhdl; rtr_msglen_t msglen; rtr_tid_t tid; rtr_evtnum_t evtnum; } rtr_msgsb_t ;The msgtype field can assume one of the values listed in Table 2-2, RTR Received Message Types for Servers and Table 2-3, RTR Received Message Types for Clients.
The usrhdl field contains the value supplied with a call to rtr_set_user_handle() .
The msglen field contains the length of the data stored in the user buffer after the call has been executed.
The tid field contains the RTR unique id for the transaction to which this received message belongs.
The evtnum field contains the event number if the msgtype field is rtr_mt_rtr_event or rtr_mt_user_event.
The rtr_receive_message() call is used to receive a message.Return Value A value indicating the status of the routine. Possible status values are:The caller must have previously opened at least one channel (via rtr_open_channel() or rtr_request_info() ).
By default, this function waits for a message to become available if no message is currently ready to be received.
Upon successful return (RTR_STS_OK), the message status block pointed to by pmsgsb contains the description of the message received.
When a client application calls rtr_send_to_server, RTR sends the message from frontend to router. It is the router's job to find out which key range the message belongs to (by looking at the key field in the application message), and then to forward the message to the backend node where the server application for this key range is running. If the router does not know of a backend that has a server running for this key range, then the router aborts the transaction. In this case, the client application receives an rtr_mt_rejected message for this transaction with status RTR_STS_NODSTFND.
If a client application receives an RTR_STS_NODSTFND error, then the client can try to resend the transaction, as the cause may have been only temporary. Note that the reasons the router cannot find a backend node with an appropriate server include:
- The application server for this key range has not been started.
- The link between the router and backend has gone down.
- In unusual circumstances, a transaction can be rejected with RTR_STS_NODSTFND status after the client calls rtr_accept_tx. This can occur for transactions with multiple participants and no timeout specified where the link between the router (which is quorate) and one of and one of the backend participants has gone down for a period greater than the router's transaction replay timeout period. (This can occur even if the messages in the transaction had all been sent with the RTR_F_SEN_EXPENDABLE flag set.)
| RTR_STS_OK | Normal successful completion |
| RTR_STS_ACPNOTVIA | RTR ACP not a viable entity |
| RTR_STS_INVCHANNEL | Invalid channel argument |
| RTR_STS_INVFLAGS | Invalid flags argument |
| RTR_STS_INVMSG | Invalid pmsg argument |
| RTR_STS_INVRMNAME | Invalid resource manager name |
| RTR_STS_TIMOUT | Call to rtr_receive_message timed out |
| RTR_STS_NOACP | No RTRACP process available |
| RTR_STS_TRUNCATED |
Buffer too short for msg
Message has been truncated |
status = rtr_receive_message( &channel, RTR_NO_FLAGS, RTR_ANYCHAN, &receive_msg, sizeof(receive_msg), receive_time_out, &msgsb); check_status( "rtr_receive_message", status ); /* The rtr_msgsb_t tells us what type of * message we are receiving. This server has asked to * be notified when it is time to prepare the transaction. * It should also handle other message types, as well. */ if (rtr_msg_type_t == rtr_mt_prepare) { // Do the work necessary to prepare the transaction // before committing.
Reject the transaction currently active on a channel.
status = rtr_reject_tx (channel, flags, reason)
Argument Data Type Access status rtr_status_t write channel rtr_channel_t read flags rtr_rej_flag_t read reason rtr_reason_t read
rtr_status_t rtr_reject_tx (
rtr_channel_t channel ,
rtr_rej_flag_t flags ,
rtr_reason_t reason
)
channel
The channel identifier (returned earlier by rtr_open_channel() ).flags
Table 3-8 shows the only flag that is defined.
Table 3-8 Reject Transaction Flag Flag name Description RTR_F_REJ_RETRY Specified by a server to indicate that the transaction cannot be processed now, but should be redelivered by RTR later. This is intended for use when a server detects a database deadlock. It is up to the server to handle the retry logic. If you do not require any flags, specify RTR_NO_FLAGS for this parameter.
reason
The reason for the rejection. This rejection reason is returned to the other participants in the transaction. It is returned in the reason field of the structure rtr_status_data_t with the rtr_mt_rejected message. Specify RTR_NO_REASON if no reason is to be supplied.
The rtr_reject_tx() call rejects the transaction which is active on the specified channel.Return Value A value indicating the status of the routine. Possible status values are:When rtr_reject_tx() returns, the channel is no longer associated with the transaction.
| RTR_STS_OK | Normal successful completion |
| RTR_STS_INVCHANNEL | Invalid channel argument |
| RTR_STS_INVFLAGS | Invalid flags argument |
| RTR_STS_TXNOTACT |
No tx currently active on chan
No transaction is currently active on this channel |
rtr_uns_32_t MT_LAST_NAME = 678; /* Defined in user's .h file. */ if (last_name == null) { /* Missing last name! Not everything is ready for * committing the current transaction (e.g., through * validations), and so wishes to reject it, rather than * to commit it. */ status = rtr_reject_tx( &channel, // Same channel it came in on. RTR_F_REJ_RETRY, // Retry from msg1 of txn. MT_LAST_NAME ); // User-defined error code. check_status(status); return; }
Send a server's reply to a client's transactional message.
status = rtr_reply_to_client (channel, flags, pmsg, msglen, msgfmt)
Argument Data Type Access status rtr_status_t write channel rtr_channel_t read flags rtr_rep_flag_t read pmsg rtr_msgbuf_t read msglen rtr_msglen_t read msgfmt rtr_msgfmt_t read
rtr_status_t rtr_reply_to_client (
rtr_channel_t channel ,
rtr_rep_flag_t flags ,
rtr_msgbuf_t pmsg ,
rtr_msglen_t msglen ,
rtr_msgfmt_t msgfmt
)
channel
The channel identifier (returned earlier by rtr_open_channel() ).flags
Table 3-9 shows the flags defined for this call.
Table 3-9 Reply To Client Flag Flag Description RTR_F_REP_ACCEPT The transaction is accepted by this server. This is equivalent to sending a reply to the server and immediately following it with a call to rtr_accept_tx() . This is useful in those cases where the sender knows that the transaction is definitely acceptable. RTR_F_REP_FORGET Set to prevent receipt of any more messages or completion status associated with the transaction after it has been accepted. Using this flag requires that the RTR_F_ACC_FORGET flag be set in the rtr_accept_tx call, indicating that the transaction is to be accepted. RTR_F_REP_INDEPENDENT Set to indicate that this transaction is independent; can only be used with RTR_F_REP_ACCEPT . (See Section 2.16.4, Transaction Independence, for further information.) Specify RTR_NO_FLAGS for this parameter if no flags are required.
pmsg
Pointer to the reply message to be sent.msglen
Length of the message to be sent, in bytes.msgfmt
Message format description. msgfmt is a null-terminated character string containing the format description of the message. RTR uses this description to convert the contents of the message appropriately when processing the message on different hardware platforms. See Section 2.15, RTR Applications in a Multiplatform Environment, for information on defining a message format description.This parameter is optional. Specify RTR_NO_MSGFMT if the message content is platform independent, or other hardware platforms will not be used.
The rtr_reply_to_client() call sends a transactional message back to the client that started the transaction.Return Value A value indicating the status of the routine. Possible status values are:The caller must first obtain a server channel (using the rtr_open_channel() call) and must have received a message from a client using the rtr_receive_message() call.
| RTR_STS_OK | Normal successful completion |
| RTR_STS_INVCHANNEL | Invalid channel argument |
| RTR_STS_INVFLAGS | Invalid flags argument |
| RTR_STS_INVMSGLEN | Invalid msglen argument |
| RTR_STS_INVMSGFMT | Invalid msgfmt argument |
| RTR_STS_INSVIRMEM | Insufficient virtual memory |
/* The purchase_msg structure is defined in the user's * application header file. */ typedef struct { rtr_uns_8_t my_msg_type; string31 last_name; rtr_uns_32_t order_total; rtr_uns_32_t shipping_amt; string7 user_id; } purchase_msg; purchase_msg purch_msg; /* The client has made a request on the server; the server * has fulfilled this request, and now needs to let the * client know the result. * * In this case, the client has asked the server to total * the purchases in the user's shopping cart. The server * is accepting the transaction at this time as well, without * being explicitly asked to. */ purch_msg.my_msg_type = MY_TOTAL_PURCHASES; purch_msg.last_name = cust_last_name; . . Fill the struct based on database query or calculations. . status = rtr_reply_to_client ( channel, RTR_F_REP_ACCEPT, &purch_msg, sizeof(purch_msg), RTR_NO_MSGFMT); check_status(status);
Request information about the RTR environment.
status = rtr_request_info (pchannel, flags, infcla, selitm, selval, getitms)
Argument Data Type Access status rtr_status_t write pchannel rtr_channel_t write flags rtr_req_flag_t read infcla rtr_infoclass_t read selitm rtr_itemcode_t read selval rtr_selval_t read getitms rtr_itemcode_t read
rtr_status_t rtr_request_info (
rtr_channel_t *pchannel ,
rtr_req_flag_t flags ,
rtr_infoclass_t infcla ,
rtr_itemcode_t selitm ,
rtr_selval_t selval ,
rtr_itemcode_t getitms
)
pchannel
Pointer to the channel opened by a successful call to rtr_request_info() .flags
No flags are currently defined. Specify RTR_NO_FLAGS for this parameter.infcla
A null-terminated text string that specifies the information class for which data is requested. For example, to obtain information about a node, use the "rtr" string, or, for a backend, use the "btx" string. Information classes and their specifying strings are listed in Table 3-10.
Table 3-10 Information Classes For this Information Class: Use this string: For valid data: For valid fields, see: Application process "prc" An application process must have been started ( rtr_open_channel called). Table 3-11 Client process "cli" A client channel must have been opened. Table 3-12 Facility "fac" A facility must be defined. Table 3-13 Key segment "ksg" A server channel must have been opened. Table 3-14 Link to a node "lnk" A facility must be defined. Table 3-15 Node or RTRACP "rtr" RTRACP must be running. Table 3-16 Partition on a backend "bpt" A server channel must have been opened. Table 3-17 Partition on a router "rpt" A server channel must have been opened. Table 3-18 Partition history "hpt" A server channel must have been opened. Table 3-19 Server process "srv" A server channel must have been opened. Table 3-20 Transaction on a backend "btx" A transaction must be in progress on the backend. Table 3-21 Transaction on a frontend "ftx" A client application must have a transaction in progress. Table 3-22 Transaction on a router "rtx" A transaction must be in progress on the router. Table 3-23 selitm
Null-terminated text string giving the field names used for selecting information, such as facility name or transaction ID. Use this argument to reduce the amount of information returned. If a null string is specified (""), then all available information for the class is returned. Fields are comma-separated lists and reflect nested data structures. The label is returned in SHOW commands for the given field. To obtain the RTR version number (displayed by SHOW RTR/VERSION), use the field name rtr_version_string.
Table 3-11 Application Process Labels and Fields Label Field "Process-id" "process_id" "Process Name" "process_name"
Table 3-12 Client Process Labels and Fields Label Field "Process-id" "dpb_pid" "Facility" "fdb_f_name" "Channel" "dpb_chan" "Flags" "dpb_dclflg" "State" "dpb_req_sts" "rcpnam" "dpb_evtnam" "User Events" "dpb_user_evtnum" "RTR Events" "dpb_rtr_evtnum"
Table 3-13 Facility Labels and Fields Label Field "Facility" "fdb_f_name" "Frontend" "fdb_attr.fdb_attr_bits.is_fe" "Router" "fdb_attr.fdb_attr_bits.is_rtr" "Backend" "fdb_attr.fdb_attr_bits.is_be" "Reply Checksum" "fdb_attr.fdb_attr_bits.reply_enabled" "Router call-out" "fdb_attr.fdb_attr_bits.tr_call_out" "Backend call-out" "fdb_attr.fdb_attr_bits.be_call_out" "Load balance" "fdb_attr.fdb_attr_bits.feshare" "Quorum-check off" "fdb_attr.fdb_attr_bits.qrt_chk" "FE -> TR" "fdb_trsrch" "Router quorate" "fdb_state.fdb_state_bits.tr_qrt" "Backend quorate" "fdb_state.fdb_state_bits.be_qrt" "Quorum threshold" "fdb_iqt_cnt" "Min bcst rate" "fdb_cn_fct_min_brd_out_rate" "Frontends connected" "fdb_fecnt" "Frontends allowed" "fdb_fecdt" "Load coordinator" "fdb_status.fdb_status_bits.qm_be" "Quorate routers" "fdb_trtot" "Total Frontends" "fdb_fetot" "Current Credit" "fdb_curcdt" "FE -> TR" "fdb_trsrch" "Link to" "fac_ndb" "Frontend" "fac_fe.rol_bits.rol_cfg" "Router" "fac_tr.rol_bits.rol_cfg" "Backend" "fac_be.rol_bits.rol_cfg" "Router -> Frontend" "fac_reasons.fac_reason_bits.trfelnk" "Frontend -> Router" "fac_reasons.fac_reason_bits.fetrlnk" "Backend -> Router" "fac_reasons.fac_reason_bits.betrlnk" "Router -> Backend" "fac_reasons.fac_reason_bits.trbelnk" "Router quorate" "fac_tr.rol_bits.rol_quorum" "Backend -> Router" "fac_reasons.fac_reason_bits.betrlnk" "Router -> Backend" "fac_reasons.fac_reason_bits.trbelnk" "Router quorate" "fac_tr.rol_bits.rol_quorum" "Backend quorate" "fac_be.rol_bits.rol_quorum" "Router current" "fac_tr.rol_bits.rol_cur" "Backend coordinator" "fac_be.rol_bits.rol_qmaster"
Previous Next Contents Index