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

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

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