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

See Also

• rtr_receive_message()
• rtr_open_channel()

Sets or changes a managed object in the RTR environment.

Syntax

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

C Binding

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
)

Arguments

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-25
Set Transaction	Table 3-26

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-25 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-26 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-27 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-27 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-28 and Table 3-29 list qualifiers and value types for the managed object types.

Table 3-28 Qualifiers for Set Partition

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 the transaction managed object type, a message of type rtr_mt_closed is returned. See Table 3-29 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.

Table 3-29 Qualifiers for Set Transaction

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.

Description

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.

The rtr_set_info() call can manipulate two managed object types:

• the partition type
• the transaction type

For the partition managed object type, a message of type rtr_mt_closed is returned.

See Table 3-28 for values that can be set for the partition object and Table 3-29 for values that can be set for the transaction object. Completion status is read from message data, which is of type rtr_status_data_t.

Example

/* * This might follow a call to commit the transaction to the database. * If the SQL commit returns an error that is beyond the control of * this application: e.g., database disk full, network to database not * responding, or timeout exceeded, it executes. * * Declarations: */ rtr_tid_t tid; rtr_uns_32_t select_idx; rtr_uns_32_t set_idx; rtr_qualifier_value_t select_qualifiers[8]; rtr_qualifier_value_t set_qualifiers[3]; /* Everyone has voted to accept the transaction, and RTR has told the * server to commit it. The client has moved on to performing the next * transaction. This transaction will be changed from `commit' status * to `exception' status for a later attempt at committing. * * Get the transaction id. */ rtr_get_tid(channel, RTR_F_TID_RTR, &tid); /* Load the rtr_qualifier_value_t structures which contain the * selection criteria for the transaction: `the transaction whose tid * is pointed at by `tid', whose facility name is in `facname', whose * partition name is in `partname', and whose transaction state is * `rtr_txn_jnl_commit' (logged to the journal as committed). */ select_idx = 0; select_qualifiers[select_idx].qv_qualifier = rtr_txn_tid; select_qualifiers[select_idx].qv_value = &tid; select_idx++; /* Facility name */ select_qualifiers[select_idx].qv_qualifier = rtr_facility_name; select_qualifiers[select_idx].qv_value = facname; select_idx++; /* Partition name */ select_qualifiers[select_idx].qv_qualifier = rtr_partition_name; select_qualifiers[select_idx].qv_value = partname; select_idx++; /* Transaction state in journal */ select_qualifiers[select_idx].qv_qualifier = rtr_txn_state; select_qualifiers[select_idx].qv_value = &rtr_txn_jnl_commit; select_idx++; /* Last one on array must be `rtr_qualifiers_end' */ select_qualifiers[ select_idx].qv_qualifier = rtr_qualifiers_end, select_qualifiers[ select_idx].qv_value = NULL; select_idx++; /* Load the * rtr_qualifier_t structs which we will use to set the * new property for the transaction: in this case, only the * state of the transaction. We will change it to * rtr_txn_jnl_exception, or `exception'. */ set_idx = 0; set_qualifiers[set_idx].qv_qualifier = rtr_txn_state; set_qualifiers[set_idx].qv_value = &rtr_txn_jnl_exception; set_idx++; /* Terminate the array with an rtr_qualifiers_end. */ set_qualifiers[set_idx].qv_qualifier = rtr_qualifiers_end; set_qualifiers[set_idx].qv_value = NULL; set_idx++; /* Tell RTR to change the transaction's state. */ status = rtr_set_info( pchannel, RTR_NO_FLAGS, rtr_verb_set, rtr_transaction_object, select_qualifiers, set_qualifiers); check_status(status); /* The server should now look for an * RTR_STS_SETTRADONE message * from RTR, which confirms that it has changed the status. */

See Also

• rtr_close_channel()
• rtr_receive_message()
• rtr_request_info()

Associate a user-defined value (handle) with a transaction.

Syntax

status = rtr_set_user_handle (channel, usrhdl)

Argument	Data Type	Access
status	rtr_status_t	write
channel	rtr_channel_t	read
usrhdl	rtr_usrhdl_t	read

C Binding

rtr_status_t rtr_set_user_handle (

rtr_channel_t channel ,
rtr_usrhdl_t usrhdl
)

Arguments

channel

The channel identifier, returned earlier by the rtr_open_channel() call.

usrhdl

Value to associate with the channel. This value is returned in the usrhdl field of the msgsb message status block when subsequent calls to rtr_receive_message() return messages associated with this channel.

The usrhdl argument can be used to hold a pointer.

Description

The rtr_set_user_handle() call associates a user-defined value (handle) with a channel. An application can either use a handle, or client and servers can act independently.

The current value of a handle is associated with a channel; the current handle value is associated with each operation on the channel. The message status block supplied with a message delivered on the channel contains the user handle value that was current at the time of the associated operation. For example, an rtr_mt_accepted message has the user handle that was current when the corresponding call to rtr_accept_tx() was made, and the rtr_mt_rettosend message has the user handle that was current when the corresponding call to rtr_send_to_server() was made.

Note that the value of a handle is process local, and a different handle would be associated for the same transaction by the client and server. The scope for the user handle is within the process in which the user handle is set.

Example

/* This client does not use nested transactions, and it does * not wait for the mt_accepted message before sending * the next transaction. Instead, it matches each `accepted' * message it receives with a transaction. */ typedef struct { rtr_uns_32_t txn_number; rtr_uns_32_t message_id_sent; char my_record[255]; } txn_handle; /* Allocate and load the txn_handle data structure that * you create. */ txn_handle txn_ident = (txn_handle*)calloc(1, sizeof(txn)); txn_ident->txn_number = ++count; txn_ident->message_id_sent = my_message_id; strcpy(txn_ident->record, my_record); /* Attach this struct to the channel on which we're sending the * transaction. */ status = rtr_set_user_handle( channel, txn_ident );

See Also

• rtr_receive_message()