| Previous | Contents | Index |
The way to obtain 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 selection criteria specify an information class, a select item and a value. This is like doing a table lookup, where the class represents the specific table, and the select item and value represent the row and column in the table. For example, the following statement: rtr_request_info/channel=I/infcla=rtr/selitm="", selval="*" getitms=rtr_version_string requests information from the RTR (rtr) information class.
The rtr_request_info() call accesses the RTR tables in memory as follows:
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 a btx 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 that 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_INVCHANNEL | Invalid pchannel argument |
| RTR_STS_INVFLAGS | Invalid flags argument |
| RTR_STS_INVGETITMS | Invalid getitms argument |
| RTR_STS_INVSELITM | Invalid selitm argument |
| RTR_STS_INVSELVAL | Invalid selval argument |
| RTR_STS_NOCURROU | No router currently available for this frontend |
| RTR_STS_NOSRVAVL | Service not yet available |
| RTR_STS_OK | Normal successful completion |
Programming Example:
Command Line Example:
/* This routine retrieves the facility names of all facilities that have been defined. */ #include <string.h> #include <stdio.h> #include "rtr.h" void GetFacilityName() { char* itemlist[10]; /* Set the elements in this array to point to each item in getitembuf for later output. */ char* cp = 0; char getitembuf[1024]; rtr_status_t status; rtr_channel_t channel; char msg[1024]; /* Receive message buffer. */ unsigned int getitemcnt = 0; char infcla_buf[4] = "fac"; /* Set info class to Facility class.*/ rtr_msgsb_t txsb; getitembuf[0] = '\0'; /* Set up the request's get-item buffer for requesting the facility name. */ itemlist[getitemcnt] = &getitembuf[strlen(getitembuf)]; strcat(getitembuf, "fdb_f_name"); /* Increment counters. */ getitemcnt++; /* Add second item FE -> TR. ** Code commented out ** */ /* (Demonstrates multi-item request. Uncomment code to use.) strcat(getitembuf, ","); //Add comma separator. itemlist[getitemcnt] = &getitembuf[strlen(getitembuf)]; strcat(getitembuf, "fdb_trsrch"); getitemcnt++; */ /* Call rtr_request_info. */ status = rtr_request_info ( /* *pchannel */ &channel, /* flags */ RTR_NO_FLAGS, /* infcla */ infcla_buf, /* selitm */ "", /* selval */ "*", /* getitms */ getitembuf); if (status != RTR_STS_OK) return; /* Do a receive message to get the information that RTR returns * in response to this request. */ do { status = rtr_receive_message( /* See 'rtr_receive_message'. */ &channel, RTR_NO_FLAGS, RTR_ANYCHAN, msg, sizeof(msg), RTR_NO_TIMOUTMS, &txsb); /* Check for bad return status from rtr_receive_message(). */ if (status != RTR_STS_OK) return; /* Caller expects either an rtr_mt_closed or an rtr_mt_request_info message. */ if (txsb.msgtype == rtr_mt_closed) break; /* End of data, exit loop. Channel closed by RTR. */ if (txsb.msgtype != rtr_mt_request_info) { printf("Unexpected msgtype returned. \n"); break; } else { /* Receive the requested information. Scan through item list, output item and value. */ unsigned int i; for (i=0, cp = msg; i < getitemcnt; i++, cp += strlen(cp)+1) { *(itemlist[i+1]-1) = '\0'; /* Overwrite comma. */ printf("%-8s:%40s\t= '%^s'\n", infcla_buf, itemlist[i], cp); } } } while (1 == 1); return;
RTR> call rtr_request_info/infcla=rtr/selitm="" /selval="*"/getitms=rtr_version_string/chann=D %RTR-S-OK, normal successful completion RTR> call rtr_receive_message/chann=D/tim %RTR-S-OK, normal successful completion channel name: D msgsb msgtype: rtr_mt_request_info msglen: 18 message offset bytes text 000000 52 54 52 20 56 33 2E 32 28 32 33 30 29 20 46 54 RTR V3.2(230) FT 000010 33 00 3.
rtr_close_channel()
rtr_receive_message()
Send a transactional message to a server.
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
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 ,
)
channel
The channel identifier (returned earlier by rtr_open_channel() ).flags
Table 3-25 shows the flags that specify options for the call.
Table 3-25 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 optimization 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_MSGLEN 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.
The rtr_send_to_server() call sends a client's transactional message to a server.Return Value A value indicating the status of the routine. Possible status values are: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.
| 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_INVJOINTXID | Invalid join transaction argument |
| RTR_STS_INVMSGFMT | Invalid msgfmt argument |
| RTR_STS_INVMSGLEN | Invalid msglen argument |
| RTR_STS_NOCURROU | No router currently available for this frontend |
| RTR_STS_NOSRVAVL | Service not yet available |
| RTR_STS_OK | Normal successful completion |
| RTR_STS_REPLYDIFF | Reply from new server did not match earlier reply |
/* The my_msg structure is defined in the user's * application header file. */ typedef struct { rtr_uns_8_t routing_key; rtr_uns_32_t sequence_number; rtr_uns_8_t my_msg_type; string31 last_name; rtr_uns_32_t order_total; rtr_uns_32_t shipping_amt; string16 cc_number; string7 cc_expire; } my_msg; my_msg send_msg; . . Load purchase data into send_msg. . /* * Tell the server to validate the credit card for the * amount of this order. */ my_msg.my_msg_type = VALIDATE_CC; status = rtr_send_to_server( &channel, RTR_NO_FLAGS , &send_msg, sizeof(send_msg), RTR_NO_MSGFMT );
rtr_receive_message()
rtr_open_channel()
Sets or changes a managed object in the RTR environment.
status = rtr_set_info (*pchannel, flags, verb, object, *select_qualifiers, *set_qualifiers)
Argument Data Type Access status rtr_status_t write *pchannel rtr_channel_t write flags rtr_set_flag_t read verb rtr_verb_t read object rtr_managed_object_t read *select_qualifiers rtr_qualifier_value_t read *set_qualifiers rtr_qualifier_value_t read
rtr_status_t rtr_set_info (
rtr_channel_t *pchannel ,
rtr_set_flag_t flags ,
rtr_verb_t verb ,
rtr_managed_object_t object ,
const rtr_qualifier_value_t *select_qualifiers ,
const rtr_qualifier_value_t *set_qualifiers
)
pchannel
Pointer to the channel opened by a successful call to rtr_set_info() .flags
No flags are currently defined. Specify RTR_NO_FLAGS for this argument.verb
Always rtr_verb_set .object
Establishes the type of object to which the call is directed. Values are:
- rtr_partition_object : the target object is a partition
- rtr_transaction_object : the target object is a transaction
select_qualifiers
Pointer to array containing selection qualifiers. Values depend on object type:
For: See the values in: Set Partition Table 3-26 Set Transaction Table 3-27 For example:
typedef struct rtr_qualifier_value_t { rtr_qualifier_t qv_qualifier ; /* Which qualifier this is */ void *qv_value ; /* What value it has */ } rtr_qualifier_value_t ;The last value in the array must be rtr_qualifiers_end (see the example). Specify sufficient descriptors to identify the target object.
Table 3-26 Select Qualifiers for the Set Partition Object Qualifier Value Type Description Example rtr_facility_name const char* Facility name string "facility_name" rtr_partition_name const char* Partition name string "partition_name"
Table 3-27 Select Qualifiers for the Set Transaction Object Qualifier Value Type Description Example rtr_facility_name facname Facility name string "facility_name" rtr_partition_name partname Partition name string "partition_name" rtr_txn_state rtr_txn_jnl_commit Current transaction state See Table 3-28 for valid changes from one state to another. rtr_txn_tid tid Transaction ID 63b01d10,0,0,0,0,2e59,43ea2002 When using the Set Transaction Object, the qualifier rtr_txn_state is required. In addition, when using rtr_txn_state without rtr_facility_name or rtr_partition_name , rtr_txn_tid is required. The qualifiers rtr_facility_name and rtr_partition_name must be used together. You must always provide the current state when making a state change.
Table 3-28 Valid Set Transaction State Changes From (current state): To (new state): ABORT COMMIT DONE EXCEPTION COMMIT YES YES EXCEPTION YES YES PRI_DONE (remember) YES SENDING YES VOTED YES YES set_qualifiers
Pointer to an array containing values of type rtr_qualifier_value_t (see Select Qualifiers above) that describe the desired change to be effected. Table 3-29 and Table 3-30 list qualifiers and value types for the managed object types.
| Qualifier | Value Type | Value | Desired Action |
|---|---|---|---|
| rtr_partition_state | rtr_partition_state_t | rtr_partition_state_suspend | Suspend transaction presentation. |
| rtr_partition_state | rtr_partition_state_t | rtr_partition_state_resume | Resume transaction presentation. |
| rtr_partition_state | rtr_partition_state_t | rtr_partition_state_recover | (Re)start partition recovery. |
| rtr_partition_state | rtr_partition_state_t | rtr_partition_state_exitwait | Exit partition recovery wait/fail state. |
| rtr_partition_state | rtr_partition_state_t | rtr_partition_state_shadow | Enable shadowing. |
| rtr_partition_state | rtr_partition_state_t | rtr_partition_state_noshadow | Disable shadowing. |
| rtr_partition_cmd_timeout_secs | rtr_uns_32_t | unsigned int | Optional partition suspend timeout period (in seconds). |
| rtr_partition_rcvy_retry_count | rtr_uns_32_t | unsigned int | Limit number of recovery replays for a transaction. |
| rtr_partition_failover_policy | rtr_partition_failover_policy_t | rtr_partition_fail_to_standby | Set failover policy to standby. |
| rtr_partition_failover_policy | rtr_partition_failover_policy_t | rtr_partition_fail_to_shadow | Set failover policy to shadow. |
| rtr_partition_failover_policy | rtr_partition_failover_policy_t | rtr_partition_pre32_compatible | Set failover policy as pre-V3.2 compatible. |
For both managed object types, a message of type rtr_mt_closed is returned. See Table 3-30 for the value that can be set for the transaction type.
Completion status is read from message data, which is of type rtr_status_data_t . In addition, a number (type integer) indicating the number of transactions processed is returned. This number can be read from the message following the rtr_status_data_t data item. The last value in the array must be rtr_qualifiers_end .
| Set Qualifier | Set Qualifier Value | Value | Description |
|---|---|---|---|
| rtr_txn_state | rtr_transaction_state_t | rtr_tx_jnl_commit | Set a transaction's state to COMMIT to commit the transaction. |
| rtr_txn_state | rtr_transaction_state_t | rtr_tx_jnl_abort | Set a transaction state to ABORT to abort the transaction. |
| rtr_txn_state | rtr_transaction_state_t | rtr_tx_jnl_exception | Mark this as an exception transaction. |
| rtr_txn_state | rtr_transaction_state_t | rtr_tx_jnl_done | Remove this transaction from the RTR journal; that is, forget this transaction completely. |
The rtr_set_info() call requests a change in a characteristic of the RTR environment. If the call is successful, a channel is opened for asynchronous completion notification. Applications should use the rtr_receive_message() call to retrieve informational messages on the opened channel.
Previous Next Contents Index