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 256
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 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.16.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.
Return Value
A value indicating the status of the routine. Possible status values are:
RTR_STS_INVCHANNEL Invalid channel argument
RTR_STS_INVFLAGS Invalid flags argument
RTR_STS_NOCURROU No router currently available for this frontend
RTR_STS_NOSRVAVL Service not yet available
RTR_STS_OK Normal successful completion
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_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.11.

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 that the event number (evtnum) must also be specified by the sender and the recipient.

Note that rcpspc is case sensitive.

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.15 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_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_NOCURROU No router currently available for this frontend
RTR_STS_NOSRVAVL Service not yet available
RTR_STS_OK Normal successful completion

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.

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.
Return Value
A value indicating the status of the routine. Possible status values are:
RTR_STS_INVCHANNEL Invalid channel argument
RTR_STS_INVFLAGS Invalid flags argument
RTR_STS_NOCURROU No router currently available for this frontend
RTR_STS_NOSRVAVL Service not yet 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.

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_get_tid

Return the transaction ID for the current transaction.

Syntax

status = rtr_get_tid (channel, flags, ptid)

Argument Data Type Access
status rtr_status_t write
channel rtr_channel_t read
flags rtr_tid_flag_t read
ptid void* write

C Binding

rtr_status_t rtr_get_tid (


rtr_channel_t channel ,
rtr_tid_flag_t flags ,
void *ptid
)

Arguments

channel

The channel identifier (returned previously by rtr_open_channel() ).

flags

Flags that specify options for the call.

Table 3-4 shows the flags that are defined.

Table 3-4 Get TID Flags
Flag Pointer Data Type Returns
RTR_NO_FLAGS rtr_tid_t RTR transaction ID
RTR_F_TID_RTR rtr_tid_t RTR transaction ID
RTR_F_TID_XA rtr_xid_t XA transaction ID
RTR_F_TID_DDTM rtr_ddtmid_t DECdtm transaction ID

If you do not require any flags, specify RTR_NO_FLAGS for this parameter. Specifying RTR_NO_FLAGS is equivalent to specifying RTR_F_TID_RTR ; this capability is maintained for compatibility with RTR versions earlier than RTR Version 3.2.

The structure rtr_xid_t is based on the X/Open XA specification and is defined as follows: 


   typedef struct rtr_xid_t { 
       long formatID;               /* format identifier */ 
       long gtrid_length;  /* value from 1 through 64 */ 
       long bqual_length;  /* value from 1 through 64 */ 
       char data[RTR_XIDDATASIZE]; 
   } rtr_xid_t;

The XID structure contains a format identifier, two length fields and a data field. The data field comprises at most two contiguous components: a global transaction ID (gtrid) and a branch qualifier (bqual).

The gtrid_length field specifies the number of bytes (1-64) that constitute gtrid, starting at the first byte in data (that is, data[0]). The bqual_length field specifies the number of bytes (1-64) that constitute bqual, starting at the first byte after gtrid (that is, data[gtrid_length]). Neither component in data is null terminated. Any unused bytes in data are undefined.

The contents of data depend on the format of the transaction ID (TX ID), which is specified by the format identification field. Some valid format ID values are shown in Table 3-5.

Table 3-5 Format Identification and Data Content
Format Identification Data Content
RTR_XID_FORMATID_NONE Null XID. No XID has been returned. This will be the value if the call to rtr_get_xid / rtr_get_tid returns an error, for example.
RTR_XID_FORMATID_OSI_CCR The XID is specified using the naming rules specified for OSI CCR atomic action identifiers. RTR does not use this convention directly, but such a transaction ID format can be returned if some other associated transaction or resource manager uses this convention.

If OSI CCR (ISO standard) naming is used, then the XID's formatID element should be set to 0 (zero); if another format is used, then the formatID element should be greater than 0. A value of -1 in formatID means that the XID is null.

RTR_XID_FORMATID_RTR Identifies an RTR transaction ID. In this case, the gtrid_length is 28 and bqual_length is zero. The contents of data can be interpreted using the format defined by rtr_tid_t . Note that one should still use the rtr_get_tid call to get the RTR transaction ID for a transaction active on a channel. The rtr_get_xid call could be used, for example, if a nested transaction is started where the foreign transaction manager is also RTR.
RTR_XID_FORMATID_DDTM Identifies a transaction ID for a transaction that uses a resource managed by DECdtm. The gtrid_length field is 16, and bqual_length is 0.
RTR_XID_FORMATID_RTR_XA Identifies a transaction ID for a transaction started using an XA resource manager.

ptid

A pointer to where the unique transaction ID for the current transaction is returned. Data type depends on any flag that has been set; see Table 3-4.

Description

rtr_get_tid() returns the RTR transaction id for the current transaction.

Previous Next Contents Index