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

Previous | Contents | Index

# rtr_reject_tx

> Reject the transaction currently active on a channel.

## Syntax

> 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

## C Binding

> rtr_status_t rtr_reject_tx (

> rtr_channel_t channel ,
> rtr_rej_flag_t flags ,
> rtr_reason_t reason
> )

## Arguments

> ### channel

> The channel identifier (returned earlier by `rtr_open_channel()` ).

> ### flags

> No flags are currently defined. 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.

## Description

> The `rtr_reject_tx()` call rejects the transaction that is active on the specified channel.

> When `rtr_reject_tx()` returns, the channel is no longer associated with the transaction.

> Once an `rtr_accept()` has been called by the server application, the `rtr_reject_tx()` call is not allowed until the first message of the next transaction is received. An attempt to call `rtr_reject_tx()` yields an `RTR_STS_TXALRACC` return status.

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

RTR_STS_CHANOTOPE | Channel not opened
RTR_STS_DLKTXRES 1 | Deadlock detected, transaction rescheduled
RTR_STS_INVCHANNEL | Invalid channel argument
RTR_STS_INVFLAGS | Invalid flags argument
RTR_STS_OK | Normal successful completion
RTR_STS_TXALRACC | Transaction already accepted
RTR_STS_TXNOTACT | No transaction currently active on this channel

1This status is returned to a client in the status field of a message of type rtr_mt_rejected if a transaction currently being processed has been aborted because of a deadlock with other transactions using the same servers. RTR replays the transaction after the deadlock has been cleared. This condition can be caused by either a classic database deadlock or a potential deadlock that RTR tries to avoid in cases such as concurrent server death or server role change. For more details, see the section in the RTR Application Design Guide, Handling Error Conditions.

## Example

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

### See Also

> `rtr_open_channel()`
> `rtr_accept_tx()`

# rtr_reply_to_client

> Send a server's reply to a client's transactional message.

## Syntax

> 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

## C Binding

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

## Arguments

> ### channel

> The channel identifier (returned earlier by `rtr_open_channel()` ).

> ### flags

> Table 3-10 shows the flags defined for this call.

> Table 3-10 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.15.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.14, 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.

## Description

> The `rtr_reply_to_client()` call sends a transactional message back to the client that started the transaction.

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

> Once an `rtr_accept_tx()` has been called by the server application, the `rtr_reply_to_client()` call is not allowed until the first message of the next transaction is received. An attempt to call `rtr_reply_to_client()` yields an RTR_STS_TXALRACC return status.

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

RTR_STS_CHANOTOPE | Channel not opened
RTR_STS_INSVIRMEM | Insufficient virtual memory
RTR_STS_INVCHANNEL | Invalid channel argument
RTR_STS_INVFLAGS | Invalid flags argument
RTR_STS_INVMSGFMT | Invalid msgfmt argument
RTR_STS_INVMSGLEN | Invalid msglen argument
RTR_STS_NOACP | No RTRACP process available
RTR_STS_OK | Normal successful completion
RTR_STS_TXALRACC | Transaction already accepted
RTR_STS_TXNOTACT | No transaction currently active on this channel

## Example

>     /* 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);

### See Also

> `rtr_receive_message()`
> `rtr_open_channel()`
> `rtr_accept_tx()`

# rtr_request_info

> Request information about the RTR environment.

## Syntax

> 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

## C Binding

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

## Arguments

> ### pchannel

> Pointer to the channel opened by a successful call to `rtr_request_info()` .

> ### flags

> No flags are defined for this call. Use `RTR_NO_FLAGS` for this parameter.

> ### infcla

> A null-terminated text string that specifies the type of information for which data are requested. Table 3-11 lists information types and their specifying information class strings. Within an information class, you retrieve a specific datum with selitm, selval, and getitms parameters specified as strings. Data returned by `rtr_request_info` are valid only under certain conditions as listed in Table 3-11. For example, to obtain information about a node, use the "rtr" string; RTRACP must be running for data to be valid.

> Table 3-11 Information Classes
> For this type of information: | Use this Information Class string: | To obtain valid data: | For available items and strings, see:
> --- | --- | --- | ---
> Application process | prc | An application process must have been started ( `rtr_open_channel` called). | Table 3-12
> Client process | cli | A client channel must have been opened. | Table 3-13
> Facility | fac | A facility must be defined. | Table 3-14
> Key segment | ksg | A server channel must have been opened. | Table 3-15
> Link to a node | lnk | A facility must be defined. | Table 3-16
> Node or RTRACP | rtr | RTRACP must be running. | Table 3-17
> Partition on a backend | bpt | A server channel must have been opened. | Table 3-18
> Partition on a router | rpt | A server channel must have been opened. | Table 3-19
> Partition history | hpt | A server channel must have been opened. | Table 3-20
> Server process | srv | A server channel must have been opened. | Table 3-21
> Transaction on a backend | btx | A transaction must be in progress on the backend. | Table 3-22
> Transaction on a frontend | ftx | A client application must have a transaction in progress. | Table 3-23
> Transaction on a router | rtx | A transaction must be in progress on the router. | Table 3-24

> ### selitm

> Null-terminated text string giving the strings used to select information such as facility name or transaction ID. Use this argument to reduce the amount of information returned. If you specify a null string (""), all available information for the class is returned. A string containing multiple items should be a comma-separated list. Some SHOW commands display the same data. For example, to obtain the RTR version number (displayed by `SHOW RTR/VERSION` ), use the string `rtr_version_string` from the "rtr" information class.

> Table 3-12 Application Process ("prc") Strings
> For this selitm: | Use this string:
> --- | ---
> Process-id | process_id
> Process Name | process_name

> Table 3-13 Client Process ("cli") Strings
> For this selitm: | Use this string:
> --- | ---
> 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-14 Facility ("fac") Strings
> For this selitm: | Use this string:
> --- | ---
> 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

> Table 3-15 Key Segment ("ksg") Strings
> For this selitm: | Use this string:
> --- | ---
> Facility | fdb_f_name
> Data Type | ksd_dtyp
> Length | ksd_length
> Offset | ksd_offset

> Table 3-16 Node Links ("lnk") Strings
> For this selitm: | Use this string:
> --- | ---
> To Node | ndb_name
> Address | ndb_idp
> Outgoing message sequence nr | ndb_xcnt
> Incoming message sequence nr | ndb_rcnt
> Current receive buffer size | ndb_credit
> Current transmit buffer size | ndb_cdt_out
> Current number of link users | ndb_reasons
> Write buffer timed out | ndb_status.wbuftmo
> Write buffer full, may be sent | ndb_status.wbufrdy
> Write buffer allocated | ndb_status.wbufalc
> I/O error detected in write | ndb_status.wrerror
> I/O error detected in read | ndb_status.rderror
> Pipe temporarily blocked | ndb_status.blocked
> Connection broken | ndb_status.aborted
> Write issued, not completed | ndb_status.writing
> Read is pending | ndb_status.reading
> Node initiated the connection | ndb_status.initiator
> Connection established | ndb_status.connected
> Connection in progress | ndb_status.connecting
> Node is configured | ndb_status.configured
> Autoisolation enabled | ndb_attr.attr_bits.isol_ebld
> Link disabled | ndb_attr.attr_bits.disabled
> Link isolated | ndb_attr.attr_bits.isolated
> In facility | fac_ifn
> 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 quorate | fac_be.rol_bits.rol_quorum
> Router current | fac_tr.rol_bits.rol_cur
> Backend coordinator | fac_be.rol_bits.rol_qmaster

> Table 3-17 Node and ACP ("rtr") Strings
> For this selitm: | Use this string:
> --- | ---
> Network state | ncf_isolated
> Auto isolation | ncf_isol_ebld
> Inactivity timer/s | ncf_lw_inact
> RTR Version Number | rtr_version_string

> Table 3-18 Partition on a Backend ("bpt") Strings
> For this selitm: | Use this string:
> --- | ---
> Partition name | $name
> Facility | ppb_fdbptr
> State | ppb_pst.prt_ps
> Low Bound | ppb_krd.krd_low_bound
> High Bound | ppb_krd.krd_high_bound
> Active Servers | srb_active_q.#crm_server_block
> Free Servers | srb_free_q.#crm_server_block
> Transaction presentation | tx_presentation_state
> Last Rcvy BE | last_lcl_rec_be
> Txns Active | tkb_q.#crm_tx_kr_block
> Txns Rcvrd | rec_be_txs
> Failover policy | ppb_failover_policy
> Key range ID | ppb_krid

> Table 3-19 Partition on a Router ("rpt") Strings
> For this selitm: | Use this string:
> --- | ---
> Facility | fdb_f_name
> State | krb_sts
> Low Bound | krb_low_bound
> High Bound | krb_high_bound
> Failover policy | krb_failover_policy
> Backends | bpsb_ndbptr
> States | bpsb_pst.prt_ps
> Primary Main | krb_pri_act_bpsbptr.bpsb_ndbptr
> Shadow Main | krb_sec_act_bpsbptr.bpsb_ndbptr

> Table 3-20 Partition History ("hpt") Strings
> For this selitm: | Use this string:
> --- | ---
> Partition name | $name
> Facility | phr_fdb
> Low Bound | phr_krd.krd_low_bound
> High Bound | phr_krd.krd_high_bound
> Creation time | phr_creation_time

> Table 3-21 Server Process ("srv") Strings
> For this selitm: | Use this string:
> --- | ---
> Process-id | dpb_pid
> Facility | fdb_f_name
> Channel | dpb_chan
> Flags | dpb_dclflg
> State | ppb_pst.prt_ps
> Low Bound | ppb_krd.krd_low_bound
> High Bound | ppb_krd.krd_high_bound
> rcpnam | dpb_evtnam
> User Events | dpb_user_evtnum
> RTR Events | dpb_rtr_evtnum
> Partition-Id | dpb_krid

> Table 3-22 Transaction on a Backend ("btx") Strings
> For this selitm: | Use this string:
> --- | ---
> Tid | tb_txdx.tx_id
> Facility | fac_id
> FE-User | tb_txdx.fe_user
> State | state
> Start time | tb_txdx.tx_start_time
> Router | tr_ndbptr
> Invocation | invocation
> Active-Key-Ranges | #crm_tx_kr_block
> Recovering-Key-Ranges | #crm_tr_block
> Total-Tx-Enqs | nr_tx_enqs
> Key-Range-Id | kr_id
> Server-Pid | pid
> Server-State | sr_state
> Journal-Node | jnl_node_id
> Journal-State | jnl_state
> First-Enq | first_enq_nr
> Nr-Enqs | nr_enqs
> Nr-Replies | nr_replys

> Table 3-23 Transaction on a Frontend ("ftx") Strings
> For this selitm: | Use this string:
> --- | ---
> Tid | tb_txdx.tx_id
> Facility | fac_id
> FE-User | tb_txdx.fe_user
> State | state
> Start time | tb_txdx.tx_start_time
> Router | tr_ndbptr
> Nr-Enqs | enqs_from_rq
> Nr-Replies | replys_rcvd

> Table 3-24 Transaction on a Router ("rtx") Strings
> For this selitm: | Use this string:
> --- | ---
> Tid | tb_txdx.tx_id
> Facility | fac_id
> FE-User | tb_txdx.fe_user
> State | state
> Start time | tb_txdx.tx_start_time
> FE-Connected | fe_ndbptr
> Total-Tx-Enqs | nr_tx_enqs
> First-Enq | first_enq_nr
> Nr-Enqs | nr_enqs
> Backend | be_ndbptr
> Key-Range-State | kr_state
> Key-Range-Id | kr_id
> Journal-State | be_state

> ### selval

> Null-terminated text string; contains a value for the item named in selitm. For example, if selitm specifies fac_id indicating that a facility name is used for the selection, and selval contains the string "TESTFAC", then only information for facility TESTFAC is returned. Wildcards can be used in this specification.

> ### getitms

> Null-terminated text string containing a comma-separated list of items whose values are returned. For each instance that matches the selection criterion, the values of the items specified by getitms are returned in a message of type `rtr_mt_request_info` .

## Description

> An application program can use the `rtr_request_info()` call to interrogate the RTR environment and retrieve information about facilities, transactions, key ranges, and so on. The call accesses data maintained by RTR on behalf of application programs, and data maintained by the RTR ACP itself.

> Previous | Next | Contents | Index