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

rtr_set_user_context

Sets the current value of the optional user-defined context associated with the specified RTR channel.

Syntax

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

C Binding

rtr_status_t rtr_set_user_context (


rtr_channel_t channel ,
rtr_usrctx_t usrctx
)

Arguments

channel

The channel whose context is to be set.

usrctx

User-supplied context value.

Description

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

See Also

rtr_get_user_context()

rtr_set_user_handle

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.

Return Value A value indicating the status of the routine. Possible values are:
RTR_STS_CHANOTOPE Channel not opened
RTR_STS_INVCHANNEL Invalid channel argument
RTR_STS_OK Normal successful completion
RTR_STS_TXACTIVE Transaction is active

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()

rtr_set_wakeup

Register a function to be called when a message arrives.

Syntax

status = rtr_set_wakeup (void (*wu_rou)(void))

Argument Data Type Access
status rtr_status_t write
wu_rou procedure read

C Binding

rtr_status_t rtr_set_wakeup (


procedure void (*wu_rou) (void)
)

Arguments

void (*wu_rou) (void)

The routine to be called by RTR when a message is waiting to be delivered.

Description

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 .

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.

Return Value A value indicating the status of the routine. Possible values are:
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

Example


 
#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.

See Also

rtr_receive_message()

rtr_start_tx

Explicitly start a transaction on the specified channel.

Syntax

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

C Binding

rtr_status_t rtr_start_tx (


rtr_channel_t channel ,
rtr_sta_flag_t flags ,
rtr_timout_t timoutms ,
rtr_pointer_t pjointxid
)

Arguments

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.

Description

The rtr_start_tx() call is used to start a transaction explicitly.

An explicit transaction start is only necessary if one of the following conditions exists:

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.

Return Value A value indicating the status of the routine. Possible status values are:
RTR_STS_ACPNOTVIA RTR is no longer a viable entity, restart RTR or application
RTR_STS_INVCHANNEL Invalid channel argument
RTR_STS_INVFLAGS Invalid flags argument
RTR_STS_INVJOINTXID Invalid join transaction argument
The flag RTR_F_OPE_FOREIGN_TM was defined in the call to rtr_open_channel() , but pjointxid is equal to RTR_NO_JOINTXID , or the formatID field of an XA transaction in the pjointxid parameter is equal to RTR_XID_FORMATID_NONE .
RTR_STS_INVOP4SRV Invalid operation for server channel
RTR_STS_INVTIMOUTMS Invalid timoutms argument
RTR_STS_NOACP No RTRACP process available
RTR_STS_NOXACHAN No XA channel available
RTR_STS_OK Normal successful completion
RTR_STS_TRAALRSTA Transaction already started
RTR_STS_VERMISMAT RTR version mismatch
The RTR router is running an older version of RTR that does not support nested transactions.

Example


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. */

See Also

rtr_open_channel()
rtr_send_to_server()

Chapter 4
Compiling and Linking Your Application

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:

  1. Write your application code using RTR calls.
  2. Use RTR data and status types for cross-platform interoperability.
  3. Compile your application code calling in rtr.h using ANSI C include rules. For example, if rtr.h is in the same directory as your C code, compile with the following statement: #include "rtr.h".
  4. Link your object code with the RTR library to produce your application executable.

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.

Table 4-1 Minimum Compiler Versions for Developing RTR Applications
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

4.2 Linking Libraries

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