Reliable Transaction Router
Application Programmer's Reference Manual
Previous Contents Index

Table 3-14 Key Segment Labels and Fields
Lable Field
"Facility" "fdb_f_name"
"Data Type" "ksd_dtyp"
"Length" "ksd_length"
"Offset" "ksd_offset"

Table 3-15 Node Links Labels and Fields
Label Field
"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-16 Node and ACP Labels and Fields
Label Field
"Network state" "ncf_isolated"
"Auto isolation" "ncf_isol_ebld"
"Inactivity timer/s" "ncf_lw_inact"

Table 3-17 Partition on a Backend Labels and Fields
Label Field
"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-18 Partition on a Router Labels and Fields
Label Field
"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-19 Partition History Labels and Fields
Label Field
"Partition name" "$name"
"Facility" "phr_fdb"
"Low Bound" "phr_krd.krd_low_bound"
"High Bound" "phr_krd.krd_high_bound"
"Journal location" "phr_journal_entry.record_1_location"
"Record version" "phr_version"
"Creation time" "phr_creation_time"

Table 3-20 Server Process Labels and Fields
Label Field
"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-21 Transaction on a Backend Labels and Fields
Label Field
"Tid" "tb_txdx.tx_id"
"Facility" "fac_id"
"Frontend" "fe_node_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-22 Transaction on a Frontend Labels and Fields
Label Field
"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-23 Transaction on a Router Labels and Fields
Label Field
"Tid" "tb_txdx.tx_id"
"Facility" "fac_id"
"FE-User" "tb_txdx.fe_user"
"State" "state"
"Start time" "tb_txdx.tx_start_time"
"Frontend" "fe_node_id"
"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

The rtr_request_info() call can be used by an application program 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.

The mechanism for obtaining data is to specify the requirement as parameters to rtr_request_info() . RTR then opens a channel on which the requested information can be received by calling rtr_receive_message() on the channel. The channel is automatically closed when the requested data (if any) has been completely delivered (that is, an rtr_mt_closed message is received on the channel.) You may close the channel earlier, if no more information is needed, by calling rtr_close_channel() .

The data available from RTR may be viewed as a set of tables, one table per information class. Each column in a table may be thought of as a named item; each row in the table is an instance of the particular RTR object. For example, the table containing information about backend transactions has a row for each active transaction. Each column in the table holds an item of information about the transaction such as the facility name, transaction ID, and router associated with that transaction. The rtr_request_info() call accesses the RTR tables in the following way:

  1. The infcla parameter selects the table to be accessed.
  2. The selitm parameter names the column of the table to be accessed.
  3. The selval parameter defines what to search for in the column. For example, in a table containing information about backend transactions, if selitm specifies fac_id indicating that a facility name is the selection criterion, and if selval contains the value "TESTFAC", only transactions for the facility TESTFAC are selected.
  4. The getitms parameter defines the items to be returned from the selected row(s). In our example of a table containing information about backend transactions, items such as the transaction ID and transaction start time could be selected. These items would be returned for all transactions matching the selection criteria.

The results of the selection are returned as none, one, or more messages of type rtr_mt_request_info , one message being returned for each selected row in the table (in our example, one message for each backend transaction).

The contents of these messages are defined by the getitms parameter. For example, if three item names specified for getitms are "item_1,item_2,item_3", then the corresponding rtr_mt_request_info message or messages contain three concatenated and null-terminated strings which are the values of those fields, "value1\0value2\0value3\0".

Return Value A value indicating the status of the routine. Possible status values are:
RTR_STS_OK Normal successful completion
RTR_STS_INVCHANNEL Invalid pchannel argument
RTR_STS_INVFLAGS Invalid flags argument
RTR_STS_INVSELITM Invalid selitm argument
RTR_STS_INVSELVAL Invalid selval argument
RTR_STS_INVGETITMS Invalid getitms argument

Example


char* itemlist[10];     /* Set the elements in this array to point 
                         * to each item in itembuf, for later output. 
                         */ 
char* cp = NULL; 
char* itembuf[255]; 
 
/* This server wants to get the facility id of all 
 * of the facilities that have been defined. 
 */ 
strcpy(itembuf, "fac_id"); 
itembuf[strlen(fac_id)] = 0; 
status = rtr_request_info  ( 
        /* *pchannel    */ &channel, 
        /* flags        */ RTR_NO_FLAGS, 
        /* infcla       */ "fac", 
        /* selitm       */ "", 
        /* selval       */ "*", 
        /* getitms      */ itembuf); 
 
check_status(status); 
 
/* Now do a receive message to get the information that RTR will send 
 * back in response to this request. 
 */ 
do { 
    status = rtr_receive_message(       
     /* See `rtr_receive_message'. */ 
        &channel, 
        RTR_NO_FLAGS, 
        RTR_ANYCHAN, 
        pmsg, 
        sizeof(pmsg), 
        RTR_NO_TIMOUTMS, 
        &txsb); 
 
/* Check for bad return status from rtr_receive_message() */ 
    check_status(status); 
 
/* Caller can expect an rtr_mt_closed, or rtr_mt_request_info 
 * message. 
 */ 
    if (txsb.msgtype == rtr_mt_closed) 
    { 
/* Channel closed by RTR; no more data for this item */ 
 
/* Channel closed by RTR; no more data for this item */ 
    break; 
    } 
 
    if (txsb.msgtype != rtr_mt_request_info) 
    { 
    fprint( logFile, "Unexpected msgtype returned\n"); 
  break; 
    } 
    else 
    { 
/* Receive the requested information. 
 * Scan through item list and print the item and value. 
 */ 
 for (i = 0, cp = pmsg; i < itemcnt; i++, cp += strlen(cp)+1) 
 { 
    *(itemlist[i+1]-1) = '\0'; /* Overwrite trailing comma. */ 
    printf("%-8s:%40s\t= '%s'\n", 
        infcla_buf, 
        itemlist[i], 
        cp); 
        } 
    } 
} while(1==1);

See Also

rtr_send_to_server

Send a transactional message to a server.

Syntax

status = rtr_send_to_server (channel, flags, pmsg, msglen, msgfmt)

Argument Data Type Access
status rtr_status_t write
channel rtr_channel_t read
flags rtr_sen_flag_t read
pmsg rtr_msgbuf_t read
msglen rtr_msglen_t read
msgfmt rtr_msgfmt_t read

C Binding

rtr_status_t rtr_send_to_server (


rtr_channel_t channel ,
rtr_sen_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-24 shows the flags that specify options for the call.

Table 3-24 Send to Server Flags
Flag name Description
RTR_F_SEN_ACCEPT This is the last message of the transaction, and the tx is accepted. This optimisation avoids the need for a separate call to rtr_accept_tx() in those cases where the sender knows this is the last (or only) message in the transaction.
RTR_F_SEN_READONLY Specifies a read-only server operation. Hence no shadowing or journalling is required. (The message is still written to the journal but is not played to a shadow and is purged after the transaction is completed on the primary. The message is still needed in the journal to allow recovery of in-flight transactions.)
RTR_F_SEN_RETURN_TO_SENDER The message is to be returned to the sender if undeliverable.
RTR_F_SEN_EXPENDABLE The whole transaction is not aborted if this send fails.

Specify RTR_NO_FLAGS for this parameter if no flags are required.

pmsg

Pointer to the message to be sent.

msglen

Length in bytes of the message to be sent, up to RTR_MAX_MSGLEN bytes. The value of RTR_MAX_MSGLLEN is 64000 and is defined in rtr.h.

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 it is not intended to be used on other hardware platforms.

Description

The rtr_send_to_server() call sends a client's transactional message to a server.

The caller must first open a client channel (using the rtr_open_channel() call), before it can send transactional messages.

If no transaction is currently active on the channel, a new transaction is started.

Nested Transaction Usage
If the RTR_F_SEN_ACCEPT flag is specified in the call to rtr_send_to_server() on a channel opened with RTR_F_OPE_FOREIGN_TM, then RTR does an implicit prepare of the transaction. That is, no additional call to rtr_prepare_tx() is required.

Note that no prepare data can be passed to RTR if using the implicit prepare method.

If rtr_start_tx() has not been called before calling rtr_send_to_server(), then the error RTR_STS_INVJOINTXID is returned.
Return Value A value indicating the status of the routine. Possible status values are:
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
RTR_STS_INVJOINTXID Invalid join transaction argument
RTR_STS_REPLYDIFF Reply from new server did not match earlier reply

Example

Previous Next Contents Index