Previous | Contents | Index |
Sets the current value of the optional user-defined context associated with the specified RTR channel.
status = rtr_set_user_context (channel, usrctx)
Argument Data Type Access status rtr_status_t write channel rtr_channel_t read usrctx rtr_usrctx_t read
rtr_status_t rtr_set_user_context (
rtr_channel_t channel ,
rtr_usrctx_t usrctx
)
channel
The channel whose context is to be set.usrctx
User-supplied context value.
Sets the current value of the optional user-defined context associated with the specified RTR channel. The user context value may be subsequently retrieved using rtr_get_user_context(). The context value rtr_no_user_context is reserved.Return Value A value indicating the status of the routine. Possible values are:
RTR_STS_INVCHANNEL | Invalid channel argument |
RTR_STS_OK | Normal successful completion |
rtr_get_user_context()
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_CHANOTOPE | Channel not opened |
RTR_STS_INVCHANNEL | Invalid channel argument |
RTR_STS_OK | Normal successful completion |
RTR_STS_TXACTIVE | Transaction is active |
/* 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.
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 a message is waiting to be delivered.
The rtr_set_wakeup() call sets the address of a function to be called when a message is waiting to be delivered. To cancel wakeups, call the routine with an argument of null .Return Value A value indicating the status of the routine. Possible values are:Execution of the specified wakeup indicates that you may have messages.
At the time of the execution of the wakeup there may be 0, 1 or more messages available. Each incoming application message does not generate a separate wakeup callback, so following a wakeup callback a program should call rtr_receive_message( ..., timoutms=0, ...) in a loop at some point to ensure that no message is left uncollected.
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.
For details and restrictions on using the RTR wakeup handler rtr_set_wakeup , see the discussion in Section 2.9.
RTR_STS_ACPNOTVIA | RTR ACP no longer a viable entity, restart RTR or application |
RTR_STS_BYTLMNSUFF | Insufficient process quota bytlm, required 100000 |
RTR_STS_INVCHANNEL | Invalid channel argument |
RTR_STS_NOACP | No RTRACP process available |
RTR_STS_OK | Normal successful completion |
#include <stdlib.h> void app_wakeup_routine (void) { /* NB This is called from an AST, ALRM or IO signal handler, * or another thread depending on the platform. * Although RTR blocks signals, ASTs and the wakeup thread * until it is safe and convenient, * you may prefer to just set a flag or generate an event and * perform the receive_message in your main thread instead. */ /* Get all outstanding rtr messages */ do { sts = rtr_receive_message(..., /* timoutms */ 0 ) ; check ( sts ) ; process_message () ; } while ( sts != RTR_STS_TIMOUT ) ; } static void app_cancel_wakeup (void) { rtr_set_wakeup( NULL ); } main () { sts = rtr_set_wakeup( app_wakeup_routine ); atexit(app_cancel_wakeup); . . }If RTR data is available when rtr_set_wakeup is called, the application's wakeup routine is called immediately.
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.timoutms
Transaction timeout specified in milliseconds. If the transaction is not accepted by all participants within the specified timeout period, RTR aborts the transaction and reports a status of RTR_STS_TIMOUT.The granularity of the underlying timer is 1 second. Fractional values of the timoutms argument are rounded up to the next whole second. A value of 0 causes an immediate transaction abort.
If no timeout is required, specify RTR_NO_TIMOUTMS .
pjointxid
Pointer to the transaction identifier of 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:
- a join to an existing transaction is to be done
- 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.
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. May not complete immediately. */ 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()
All client and application programs must be written using C, C++, or a language that can use RTR API calls. Include the RTR data types and error messages file rtr.h in your compilation so that it will be appropriately referenced by your application. For each client and server application, your compilation/link process is as follows:
This process is illustrated in Figure 4-1. In this figure, Library represents the RTR C API shareable images (OpenVMS), DLLs (Win32), and shared libraries (UNIX).
Figure 4-1 Compile Sequence
4.1 Compilers
Compilers commonly used in developing RTR applications include those in
Table 4-1. For additional information, see the Reliable
Transaction Router Software Product Description.
Operating System | Compiler | Compiler Version |
---|---|---|
Microsoft Windows | Microsoft Visual C++ (Microsoft Visual Studio 6.0) | Version 6.0 SP6 |
OpenVMS Alpha | Compaq C | Version 6.2-006 |
OpenVMS VAX | Compaq C | Version 6.2-003 |
Sun | Forte Compilers | Version 6.0 |
Tru64 UNIX | Compaq C | Version 6.3-126 |
To compile and link a C RTR application, use command lines as shown below. Separate examples are shown for use of RTR with threaded or unthreaded libraries. You may need to specify library directories explictly if the RTR header files and libraries are not installed in the same directory or in system directories.
Windows
> cl /c /MT yourapp.c > link yourapp.obj /out:yourapp.exe rtrdll.lib |
Tru64 UNIX
Single-threaded:
# cc -o yourapp -lrtr yourapp.c |
Multi-threaded:
# cc -o yourapp -pthread -lrtr_r yourapp.c |
OpenVMS Alpha
Single-threaded:
$ cc yourapp.c $ link yourapp,sys$input/opt SYS$SHARE:librtr/share ^Z |
Multi-threaded:
$ cc yourapp.c $ link yourapp,sys$input/opt SYS$SHARE:librtr_r/share ^Z |
OpenVMS VAX
Single-threaded:
$ cc yourapp.c $ link yourapp,sys$input/opt SYS$SHARE:librtr/share ^Z |
Multi-threaded:
$ cc yourapp.c $ link yourapp,sys$input/opt SYS$SHARE:librtr_r/share ^Z |
Sun
Single-threaded:
$ cc -o yourapp -lrtr yourapp.c |
Multi-threaded:
$ cc -o yourapp -mt -lrtr_r yourapp.c |
Previous | Next | Contents | Index |