Previous | Contents | Index |
The rtr_set_info() call can manipulate two managed object types:
See Table 3-29 for values that can be set for the partition object
and Table 3-30 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
.
Return Value
A value indicating the status of the routine, normally returned as
function completion status. Possible status values are:
RTR_STS_ALRDYINSTATE+ | Partition is already in the desired state |
RTR_STS_BADPRTSTATE+ | Disallowed attempt to make an illegal or undefined partition state transition |
RTR_STS_FACNAMLON+ | Facility name facility_name is larger than 30 characters |
RTR_STS_FENAMELONG | Frontend name string length greater than permitted maximum |
RTR_STS_INSUFPRIV | Insufficient privileges to run RTR |
RTR_STS_INSVIRMEM | Insufficient virtual memory |
RTR_STS_INVCHANNEL | Invalid channel argument |
RTR_STS_INVFACNAM | Invalid FACNAM argument |
RTR_STS_INVFLAGS | Invalid flags argument |
RTR_STS_INVOBJCT | Specified object type invalid for managed object request |
RTR_STS_INVSTATCHANGE | Invalid to change from the current state to the specified state |
RTR_STS_IVQUAL | Unrecognized qualifier - check validity, spelling, and placement |
RTR_STS_IVVERB | Unrecognized command verb - check validity and spelling |
RTR_STS_NOACTION | No object management action specified - check argument set qualifier |
RTR_STS_NOCURROU | No router currently available for this frontend |
RTR_STS_NODNOTBAC+ | Node not defined as a backend |
RTR_STS_NOSRVAVL | Service not yet available |
RTR_STS_NOSUCHPRTN+ | No such partition in the system |
RTR_STS_OK | Normal successful completion |
RTR_STS_PARTNAMELONG | Partition name too long |
RTR_STS_PRTBADCMD+ | Partition command invalid or not implemented in this version of RTR |
RTR_STS_PRTBADFPOL+ | Unrecognized partition failover policy code |
RTR_STS_PRTLCLRECEXT+ | Partition local recovery terminated by operator |
RTR_STS_PRTMODRMBR+ | Partition must be in remember mode on the active member |
RTR_STS_PRTNOSRVRS+ | Partition has no servers---please start servers and retry |
RTR_STS_PRTNOTBACKEND+ | Partition command must be entered on a backend node |
RTR_STS_PRTNOTSUSP+ | Unable to resume partition that is not suspended |
RTR_STS_PRTNOTWAIT+ | Partition not in a wait state---no action taken |
RTR_STS_PRTRECSTATE+ | Partition must be in remember or active (non-recovery) state |
RTR_STS_PRTRESUMED+ | Partition partition_name resumed by operator operator |
RTR_STS_PRTRUNDOWN+ | Partition is in a rundown prior to deletion -- no action taken |
RTR_STS_PRTSHDRECEXT+ | Partition shadow recovery terminated by operator |
RTR_STS_SETTRANDONE+ | n transaction(s) updated in partition partition_name of facility facility_name |
RTR_STS_SETTRANROUTER+ | Cannot process this command, coordinator router is still available |
RTR_STS_TOOMANCHA | Too many channels already opened |
RTR_STS_TRNOTALL032+ | Not all routers are at the minimum required version of V3.2 |
RTR_STS_VALREQ | Missing qualifier or keyword value---supply all required values |
RTR_STS_WTTR | Not in contact with sufficient router nodes -- please retry later |
/* * 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: for example, 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 that 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 that 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. */
rtr_close_channel()
rtr_receive_message()
rtr_request_info()
Associate a user-defined value (handle) with a transaction.
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
rtr_status_t rtr_set_user_handle (
rtr_channel_t channel ,
rtr_usrhdl_t usrhdl
)
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.
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.Return Value A value indicating the status of the routine. Possible values are: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.
RTR_STS_INVCHANNEL | Invalid channel argument |
RTR_STS_NOCURROU | No router currently available for this frontend |
RTR_STS_NOSRVAVL | Service not yet available |
RTR_STS_OK | Normal successful completion |
/* 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 );
rtr_receive_message()
Register a function to be called when a message arrives and no call to rtr_receive_message() is active.
status = rtr_set_wakeup (void (*wu_rou)(void))
Argument Data Type Access status rtr_status_t write wu_rou procedure read
rtr_status_t rtr_set_wakeup (
procedure void (*wu_rou) (void)
)
void (*wu_rou) (void)
The routine to be called by RTR when no call to rtr_receive_message() is being processed and a message is waiting to be delivered.
The rtr_set_wakeup() call sets the address of a function to be called when no call to rtr_receive_message() is outstanding and a message is waiting to be delivered.Return Value A value indicating the status of the routine. Possible values are:To cancel wakeups, call the routine with an argument of null .
If a wakeup routine has been set using this call, subsequent calls to rtr_set_wakeup() should either disable the wakeup feature (with an argument of null ), or replace the current wakeup routine with another.
Note
The wakeup feature is not required in a threaded application; its functionality can be provided by a dedicated thread that receives and dispatches RTR messages.
RTR_STS_NOCURROU | No router currently available for this frontend |
RTR_STS_NOSRVAVL | Service not yet available |
RTR_STS_OK | Normal successful completion |
/* This client application has written a function that * RTR should call whenever there is a message for it. * The function is a `wake-up' function. */ void wake_me_up(void){ . . . 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 application is using * the message type to dispatch the message to handlers * that the programmer has written. */ select (rtr_msg_type_t){ case rtr_mt_prepare: status = prepare_function(receive_msg, msgsb); break; case rtr_mt_accept: status = accept_function(channel, receive_msg); break; . . Dispatch all possible; send needed parameter info. . } } /* In the main function, tell RTR to call the above function * when there is a message being sent to this application. */ status = rtr_set_wakeup(wake_me_up); sleep(); // Sleep until RTR sends a message.
rtr_receive_message()
Explicitly start a transaction on the specified channel.
status = rtr_start_tx (channel, flags, timoutms, pjointxid)
Argument Data Type Access status rtr_status_t write channel rtr_channel_t read flags rtr_sta_flag_t read timoutms rtr_timout_t read pjointxid rtr_pointer_t read
rtr_status_t rtr_start_tx (
rtr_channel_t channel ,
rtr_sta_flag_t flags ,
rtr_timout_t timoutms ,
rtr_pointer_t pjointxid
)
channel
The channel identifier returned earlier by the rtr_open_channel() call.flags
Flags that specify options for the call. Normally specify RTR_NO_FLAGS for this parameter, unless using nested transactions. Nested transaction flags, listed in Table 3-31, are only valid if the pjointxid parameter does not equal RTR_NO_JOINTXID .
Table 3-31 Nested Transaction Flags Flag Usage RTR_F_STA_TID_DDTM Only used if RTR_F_OPE_FOREIGN_TM is set in the rtr_open_channel call. Indicates that the transaction ID pointed to by the parameter pjointxid is a DECdtm transaction (16 bytes). RTR_F_STA_TID_RTR Only used if RTR_F_OPE_FOREIGN_TM is set in the rtr_open_channel call. Indicates that the transaction ID pointed to by the parameter pjointxid is an RTR transaction (28 bytes). RTR_F_STA_TID_XA Only used if RTR_F_OPE_FOREIGN_TM is set in the rtr_open_channel call. Indicates that the transaction ID pointed to by the parameter pjointxid is an XA transaction.
Note
The flags RTR_F_STA_TID_RTR , RTR_F_STA_TID_XA and RTR_F_STA_DDTM are mutually exclusive.timoutms
Transaction timeout specified in milliseconds. If the timeout time expires, RTR aborts the transaction and returns status RTR_STS_TIMOUT.If no timeout is required, specify RTR_NO_TIMOUTMS .
pjointxid
Pointer to the transaction identifier if the parent transaction.
The rtr_start_tx() call is used to start a transaction explicitly.Return Value A value indicating the status of the routine. Possible status values are:An explicit transaction start is only necessary if one of the following conditions exists:
- either a join to an existing transaction is to be done
- or a transaction timeout is to be specified
Transactions are implicitly started when a message is sent on a currently inactive channel. Implicitly started transactions have no timeout and are not joined to other RTR transactions.
Nested Transaction Usage
If the RTR_F_OPE_FOREIGN_TM flag is set for a channel, then the global coordinating transaction manager for this transaction is a foreign transaction manager. In this case, the application must use the rtr_start_tx() call to start a transaction (the transaction cannot be started implicitly on a first call to rtr_send_to_server() ), and specify the pjointxid parameter.
When a nested transaction is started (pjointxid not equal to RTR_NO_JOINTXID ), then that transaction is given a new RTR transaction ID (which the application can retrieve by calling rtr_get_tid() ). The foreign transaction ID passed in pjointxid is used only to identify the transaction for the foreign transaction manager (for example, when the foreign transaction manager goes through recovery and requests RTR to return all transactions in prepared state).
The channel on which a nested transaction is started must be opened as a client channel, on a node defined with the frontend role, on which an RTR journal is required. If no facilities on that node have the backend role defined, so as to support a journal, RTR opens a local journal on the node.
Each nested transaction is started on a separate client channel. There is no restriction on the levels of nesting for nested transactions, or on the number of nested transactions that can be started and controlled by one global transaction manager.
rtr_xid_t xa_txn; /* This client/server pair handles transactions that contain * multiple messages within each one. Transactions are explicitly * started and prepared, as directed by this client. * * Fill in the information in the XA transaction id struct. * The information will be sent to the server to tag the transaction. */ xa_txn.formatID = RTR_XID_FORMATID_RTR_XA; xa_txn.gtrid_length = 4; xa_txn.bqual_length = 4; strcpy(xa_txn.data, "6789.0003"); /* Start the transaction; specify a timeout so we don't get * stuck waiting forever. */ status = rtr_start_tx( &channel, RTR_F_STA_TID_XA, 1000, &xa_txn ); check_status(status); // May be RTR_STS_TIMEOUT.
rtr_open_channel()
rtr_send_to_server()
Previous | Next | Contents | Index |