# hp Reliable Transaction Router
C Application Programmer's
Reference Manual

Previous | Contents | Index

# Chapter 3
RTR Call Reference

This chapter contains the environmental limits, field length maxima, and syntax definitions for all RTR C programming API calls.

# 3.1 RTR Environmental Limits

RTR deals with several environmental entities that have architectural limits as shown in Table 3-1. Actual limits in a specific configuration are determined by performance.

Table 3-1 Environmental Limits
Component | Limit
--- | ---
BE or TR nodes | 512
Bytes per message | 64000
Channels per application process | 1024
Facilities | 100 to 1000, depending on operating system
FE nodes | 1000
Journal files | 16
Memory per process | OpenVMS: 4GB; UNIX: unlimited; NT: 2GB
Messages per transaction - server to client | unlimited
Messages per transaction - client to server | 65534
Partitions | 65536 (dynamic; default:500)
Processes per node | 1000
Size of journal file | 256MB
Threads per application process (where supported by operating system) | 4096

# 3.2 RTR Maximum Field Lengths

Table 3-2 contains definitions of RTR field length maxima. The file `rtr.h` contains values for these field lengths.

Table 3-2 RTR Maximum Field-Length Definitions
Field Name | Description
--- | ---
RTR_MAX_ACCESS_LEN | Maximum length of access string.
RTR_MAX_BLOB_LEN | Maximum length of data that can be passed in a prepare call.
RTR_MAX_FACNAM_LEN | Maximum length of facility name.
RTR_MAX_FE_NAM_LEN | Maximum length of frontend name.
RTR_MAX_MSGFMT_LEN | Maximum length of message format.
RTR_MAX_MSGLEN | Maximum length of an RTR message.
RTR_MAX_NUMSEG | Maximum number of segments in key.
RTR_MAX_PARNAM_LEN | Maximum length of partition name.
RTR_MAX_RCPNAM_LEN | Maximum length of broadcast recipient name.
RTR_MAX_RCPSPC_LEN | Maximum length for broadcast recipient specification.
RTR_MAX_SELVAL_LEN | Maximum length for selector value.

# 3.3 RTR C API Calls

The calls are presented in alphabetical order.

# rtr_accept_tx

> Accept the transaction currently active on the specified channel.

## Syntax

> status = rtr_accept_tx (channel, flags, reason)

> Argument | Data Type | Access
> --- | --- | ---
> status | rtr_status_t | write
> channel | rtr_channel_t | read
> flags | rtr_acc_flag_t | read
> reason | rtr_reason_t | read

## C Binding

> rtr_status_t rtr_accept_tx (

> rtr_channel_t channel ,
> rtr_acc_flag_t flags ,
> rtr_reason_t reason
> )

## Arguments

> ### channel

> The channel identifier (returned earlier by `rtr_open_channel()` ).

> ### flags

> Flags that specify options for the call.

> Table 3-3 shows the flags that are defined.

> Table 3-3 Accept Transaction Flags
> Flag name | Description
> --- | ---
> RTR_F_ACC_FORGET | Set to prevent receipt of any more messages (or completion status) associated with the transaction. Any such messages are discarded. This flag is valid only on server channels; it has no effect on client channels.
> RTR_F_ACC_INDEPENDENT | Set to indicate this transaction is independent. (See Section 2.15.4 for further information.)

> If you do not require any flags, specify `RTR_NO_FLAGS` for this parameter.

> ### reason

> Optional reason for accepting the transaction. This reason is ORed together with the reasons of the other participants in the transaction and returned in the reason field of the `rtr_status_data_t` structure returned with the `rtr_mt_accepted` message to all participants of the transaction. Specify `RTR_NO_REASON` if no reason is required.

## Description

> The `rtr_accept_tx()` call accepts the transaction currently active on the specified channel. After `rtr_accept_tx()` has been called, the caller may no longer actively participate in the fate of the transaction; that is, messages and the final completion status can still be received, but no further messages may be sent for the transaction. An attempt to send a further message yields an RTR_STS_TXALRACC return status.

Return Value
A value indicating the status of the routine. Possible status values are:

RTR_STS_AMBROUNAM | Ambiguous API routine name for call - supply more characters
RTR_STS_CHANOTOPE | Channel not opened
RTR_STS_INVCHANNEL | Invalid channel argument
RTR_STS_INVFLAGS | Invalid flags argument
RTR_STS_OK | Normal successful completion
RTR_STS_TXALRACC | Transaction already accepted
RTR_STS_TXNOTACT | No transaction currently active on this channel

## Example

>     /*
>      * Client is done with the txn; if the server accepts the
>      * transaction, there is no reason for us to reject it.
>      * Accept it, then go on to a new transaction.
>      */
>     if (msgsb.msgtype == rtr_mt_accepted)
>           {
>                 status = rtr_accept_tx(
>                                 channel,
>                                 RTR_NO_FLAGS,
>                                 RTR_NO_REASON );

>                 check_status( status );
>             }
>             else
>             .
>             .       Issue the error message returned by the
>             .       server, and recover from there.
>             .

### See Also

> `rtr_open_channel()`
> `rtr_reject_tx()`
> `rtr_reply_to_client()`

# rtr_broadcast_event

> Broadcast (send) a user event message.

## Syntax

> status = rtr_broadcast_event (channel, flags, pmsg, msglen, evtnum, rcpspc, msgfmt)

> Argument | Data Type | Access
> --- | --- | ---
> status | rtr_status_t | write
> channel | rtr_channel_t | read
> flags | rtr_bro_flag_t | read
> pmsg | rtr_msgbuf_t | read
> msglen | rtr_msglen_t | read
> evtnum | rtr_evtnum_t | read
> rcpspc | rtr_rcpspc_t | read
> msgfmt | rtr_msgfmt_t | read

## C Binding

> rtr_status_t rtr_broadcast_event (

> rtr_channel_t channel ,
> rtr_bro_flag_t flags ,
> rtr_msgbuf_t pmsg ,
> rtr_msglen_t msglen ,
> rtr_evtnum_t evtnum ,
> rtr_rcpspc_t rcpspc ,
> rtr_msgfmt_t msgfmt
> )

## Arguments

> ### channel

> The channel identifier (returned earlier by `rtr_open_channel()` ).

> ### flags

> No flags are currently defined. Specify `RTR_NO_FLAGS` for this parameter.

> ### pmsg

> Pointer to the message to broadcast.

> ### msglen

> Length in bytes of the message broadcast.

> ### evtnum

> User event number associated with this broadcast. (Recipients must specify this to receive it.) For more information on user event numbers, see Section 2.12.

> ### rcpspc

> Name of the recipient(s). This null-terminated character string contains the name of the recipient(s), specified with the rcpnam parameter on the call to `rtr_open_channel()` .

> Wildcards ( "*" for any sequence of characters, and "%" for any one character) can be used in this string to address more than one recipient. rcpspc is an optional parameter. Specify `RTR_NO_RCPSPC` for this parameter if no rcpspc is required.

> Note To receive named events, the correct event number must also be specified. The event number (evtnum) must be specified by both the sender (rcpspc) and the recipient (rcpnam). Both rcpnam and rcpspc are case sensitive. Both rcpnam and rcpspc default to the case-insensitive channel name if no explicit rcpnam or rcpspc is provided.

> ### msgfmt

> Message format description. This null-terminated character string contains the format description of the message. RTR uses this description to convert the contents of the message appropriately when processing the message on different hardware platforms. See Section 2.14 for information on defining a message format description.

> This parameter is optional. Specify `RTR_NO_MSGFMT` if message content is platform independent, or there is no intent to use other hardware platforms.

## Description

> The `rtr_broadcast_event()` call broadcasts a user event message. The caller must first open a channel (using `rtr_open_channel()` ), before it can send user event messages.

> A client channel can be used to send user event messages to servers.

> A server channel can be used to send user event messages to clients.

Return Value
A value indicating the status of the routine. Possible status values are:

RTR_STS_CHANOTOPE | Channel not opened
RTR_STS_INSVIRMEM | Insufficient virtual memory
RTR_STS_INVCHANNEL | Invalid channel argument
RTR_STS_INVEVTNUM | Invalid evtnum argument
RTR_STS_INVFLAGS | Invalid flags argument
RTR_STS_INVMSGFMT | Invalid msgfmt argument
RTR_STS_INVMSGLEN | Invalid msglen argument
RTR_STS_INVRCPSPC | Invalid rcpspc argument
RTR_STS_NOACP | No RTRACP process available
RTR_STS_OK | Normal successful completion
RTR_STS_WOULDBLOCK | Operation would block. Try again later

## Example

>     #define reunion_announcement 678        // In user .h file.

>     rtr_msg_buf_t reunion_msg = "Jones family reunion today!";
>     rtr_rcpspc_t recipients = "*Jones";

>     /*
>      * If today is the date of the Jones family reunion, tell
>      * any client whose last name is Jones that they need to
>      * be there!
>      */
>             if (strcmp(today, reunion_date) == 0)
>             {
>                     status = rtr_broadcast_event(
>                             &channel,
>                             RTR_NO_FLAGS,
>                             reunion_msg,
>                             strlen(reunion_msg),
>                             reunion_announcement,
>                             recipients,
>                             RTR_NO_MSGFMT );

>                     check_status( status );
>     }

### See Also

> `rtr_receive_message()`
> `rtr_open_channel()`

# rtr_close_channel

> Close a previously opened channel.

## Syntax

> status = rtr_close_channel (channel, flags)

> Argument | Data Type | Access
> --- | --- | ---
> status | rtr_status_t | write
> channel | rtr_channel_t | read
> flags | rtr_clo_flag_t | read

## C Binding

> rtr_status_t rtr_close_channel (

> rtr_channel_t channel ,
> rtr_clo_flag_t flags
> )

## Arguments

> ### channel

> The channel identifier (returned earlier by `rtr_open_channel()` , or `rtr_request_info()` or `rtr_set_info()` ).

> ### flags

> Flags that specify options for the call.

> The flag RTR_F_CLO_IMMEDIATE is defined for this call.

> Normally `rtr_close_channel()` processes a pending transaction that was in a commit state by forgetting the transaction (removing it from the journal). To close the channel but leave transactions in the journal, use the flag RTR_F_CLO_IMMEDIATE to `rtr_close_channel()` .

> In some situations, an accepted transaction cannot be completed and replay is required. For example, a transaction may be accepted but the database becomes unavailable before the transaction is committed to the database. To deal with such a situation, an application can use the close-immediate flag RTR_F_CLO_IMMEDIATE. This closes the channel but leaves the transactions in the journal for use on replay when database access is restored. If you do not need any flags, specify RTR_NO_FLAGS for this argument.

## Description

> The `rtr_close_channel()` call closes a previously opened channel. A channel may be closed at any time after it has been opened via `rtr_open_channel()` or `rtr_request_info()` . If the channel is a server channel, an implicit acknowledgment is sent, if you have a current transaction.

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

>     /* If the status returned by the previous call is not success,
>      * close now, and exit the program.
>      */
>     if (status != RTR_STS_OK)
>             {
>             printf(fpLog, "Unexpected error, must close immediately!");
>             status = rtr_close_channel( channel, RTR_CLO_IMMEDIATE);
>             exit(status);
>     }

>     /*
>      * Normal processing complete, close the channel.
>      */
>             printf(fpLog, "Closing channel");
>     status = rtr_close_channel ( channel, RTR_NO_FLAGS );

### See Also

> `rtr_open_channel()`

# rtr_error_text

> Return the text associated with an RTR status value.

## Syntax

> retval = rtr_error_text (sts)

> Argument | Data Type | Access
> --- | --- | ---
> retval | char* | write
> sts | rtr_status_t | read

## C Binding

> char *rtr_error_text (

> rtr_status_t sts
> )

## Arguments

> ### sts

> The RTR error number for which the text is required.

## Description

> The `rtr_error_text()` call returns a pointer to the text associated with an RTR error number.

> The text string is a constant. If an invalid value for sts is supplied, a pointer is also returned to an error text, indicating an invalid value.

## Example

>     /* If the status returned by the previous call is not success,
>      * print the message text to the error log, and exit.
>      */
>     if (status != RTR_STS_OK)
>     {
>         printf(errLog, rtr_error_text(status));
>               exit(status);
>           }

# rtr_ext_broadcast_event

> Broadcast (send) a user event message or an RTR_STS_TIMOUT status if RTR is unable to issue to broadcast message within the specified timeout period. The call is the same as rtr_broadcast_event with the addition of the timeout period, given in milliseconds.

## Syntax

> status = rtr_ext_broadcast_event (channel, flags, pmsg, msglen, evtnum, rcpspc, msgfmt, timoutms)

> Argument | Data Type | Access
> --- | --- | ---
> status | rtr_status_t | write
> channel | rtr_channel_t | read
> flags | rtr_bro_flag_t | read
> pmsg | rtr_msgbuf_t | read
> msglen | rtr_msglen_t | read
> evtnum | rtr_evtnum_t | read
> rcpspc | rtr_rcpspc_t | read
> msgfmt | rtr_msgfmt_t | read
> timoutms | rtr_timout_t | read

## C Binding

> rtr_status_t rtr_ext_broadcast_event (

> rtr_channel_t channel ,
> rtr_bro_flag_t flags ,
> rtr_msgbuf_t pmsg ,
> rtr_msglen_t msglen ,
> rtr_evtnum_t evtnum ,
> rtr_rcpspc_t rcpspc ,
> rtr_msgfmt_t msgfmt ,
> rtr_timout_t timoutms
> )

## Arguments

> ### channel

> The channel identifier (returned earlier by `rtr_open_channel()` ).

> ### flags

> No flags are currently defined. Specify `RTR_NO_FLAGS` for this parameter.

> ### pmsg

> Pointer to the message to broadcast.

> ### msglen

> Length in bytes of the message to be broadcast.

> ### evtnum

> User event number associated with this broadcast. (Recipients must specify this to receive it.) For more information on user event numbers, see Section 2.12.

> ### rcpspc

> Name of the recipient(s). This null-terminated character string contains the name of the recipient(s), specified with the rcpnam parameter on the call to `rtr_open_channel()` .

> Wildcards ( "*" for any sequence of characters, and "%" for any one character) can be used in this string to address more than one recipient. rcpspc is an optional parameter. Specify `RTR_NO_RCPSPC` for this parameter if no rcpspc is required.

> Note To receive named events, the correct event number must also be specified. The event number (evtnum) must be specified by both the sender (rcpspc) and the recipient (rcpnam). Both rcpnam and rcpspc are case sensitive. Both rcpnam and rcpspc default to the case-insensitive channel name if no explicit rcpnam or rcpspc is provided.

> ### msgfmt

> Message format description. This null-terminated character string contains the format description of the message. RTR uses this description to convert the contents of the message appropriately when processing the message on different hardware platforms. See Section 2.14 for information on defining a message format description.

> This parameter is optional. Specify `RTR_NO_MSGFMT` if message content is platform independent, or there is no intent to use other hardware platforms.

> ### timoutms

> Timeout value in milliseconds that the call will wait before tiing out. Returns status RTR_STS_TIMOUT if RTR is unable to process the call. If no timeout is needed, specify RTR_NO_TIMOUTMS.

## Description

> The `rtr_ext_broadcast_event()` call broadcasts a user event message. The caller must first open a channel (using `rtr_open_channel()` ), before it can send user event messages.

> A client channel can be used to send user event messages to servers.

> A server channel can be used to send user event messages to clients.

> In some circumstances, a broadcast event can wait a long time if RTR runs out of channel credits; it may seem that the application is hanging. To eliminate such a wait, the application can specify a timeout value from which the call returns an RTR_STS_TIMOUT status if RTR is unable to issue the broadcast message within the specified timeout period.

Return Value
A value indicating the status of the routine. Possible status values are:

RTR_STS_CHANOTOPE | Channel not opened
RTR_STS_INSVIRMEM | Insufficient virtual memory
RTR_STS_INVCHANNEL | Invalid channel argument
RTR_STS_INVEVTNUM | Invalid evtnum argument
RTR_STS_INVFLAGS | Invalid flags argument
RTR_STS_INVMSGFMT | Invalid msgfmt argument
RTR_STS_INVMSGLEN | Invalid msglen argument
RTR_STS_INVRCPSPC | Invalid rcpspc argument
RTR_STS_NOACP | No RTRACP process available
RTR_STS_WOULDBLOCK | Operation would block. Try again later
RTR_STS_OK | Normal successful completion

Previous | Next | Contents | Index