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

Previous | Contents | Index

The way to obtain data is to specify the requirement as parameters to `rtr_request_info()` . RTR then opens a channel on which the requested information can be received by calling `rtr_receive_message()` on the channel. The channel is automatically closed when the requested data (if any) has been completely delivered (that is, an `rtr_mt_closed` message is received on the channel.) You may close the channel earlier, if no more information is needed, by calling `rtr_close_channel()` .

The selection criteria specify an information class, a select item and a value. This is like doing a table lookup, where the class represents the specific table, and the select item and value represent the row and column in the table. For example, the following statement: `rtr_request_info/channel=I/infcla=rtr/selitm=""/ selval="*" /getitms=rtr_version_string` requests information from the RTR (rtr) information class.

The `rtr_request_info()` call accesses the RTR tables in memory as follows:

1. The infcla parameter selects the class to be accessed, for example "rtr".
2. The selitm parameter names the row of the RTR table in memory to be accessed. This can be a null string, for example `selitms=""` to retrieve all data for the class.
3. The selval parameter defines what to search for in the row. For example, in a table containing information about backend transactions, if selitm specifies fac_id indicating that a facility name is the selection criterion, and if selval contains the value "TESTFAC", RTR selects only transactions for the facility TESTFAC.
4. The getitms parameter specifies the items to be returned from the selected row(s). In the example of a table containing information about backend transactions, `rtr_request_info` can specify transaction ID and transaction start time. The data for these items are returned for all transactions matching the selection criteria.

The results of the selection are returned as none, one, or more messages of type `rtr_mt_request_info` , one message being returned for each selected row in the table (in a btx example, one message for each backend transaction).

The contents of these messages are defined by the getitms parameter. For example, if three item names specified for getitms are "item_1,item_2,item_3", then the corresponding `rtr_mt_request_info` message or messages contain three concatenated and null-terminated strings that are the values of those fields, "value1\0value2\0value3\0".

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

RTR_STS_CLASSREQ | At least one data-class definition required
RTR_STS_INVCHANNEL | Invalid pchannel argument
RTR_STS_INVFLAGS | Invalid flags argument
RTR_STS_INVGETITMS | Invalid getitms argument
RTR_STS_INVINFCLA | Invalid information class
RTR_STS_INVSELITM | Invalid selitm argument
RTR_STS_INVSELVAL | Invalid selval argument
RTR_STS_OK | Normal successful completion

## Example

> Programming Example:

>     /*
>        This routine retrieves the facility names of all facilities
>        that have been defined.
>     */

>     #include <string.h>
>     #include <stdio.h>
>     #include "rtr.h"

>     void GetFacilityName()
>     {
>       char* itemlist[10];   /* Set the elements in this array to point to
>                             each item in getitembuf for later output. */
>       char* cp = 0;
>       char getitembuf[1024];
>       rtr_status_t status;
>       rtr_channel_t channel;
>       char msg[1024];                        /* Receive message buffer. */

>       unsigned int getitemcnt = 0;
>       char infcla_buf[4] = "fac";  /* Set info class to Facility class.*/
>        rtr_msgsb_t txsb;

>       getitembuf[0] = '\0';

>      /* Set up the request's get-item buffer for
>         requesting the facility name. */

>       itemlist[getitemcnt] = &getitembuf[strlen(getitembuf)];
>       strcat(getitembuf, "fdb_f_name");

>      /* Increment counters. */
>       getitemcnt++;

>       /* Add second item FE -> TR. ** Code commented out ** */
>       /* (Demonstrates multi-item request. Uncomment code to use.)
>       strcat(getitembuf, ",");           //Add comma separator.
>       itemlist[getitemcnt] = &getitembuf[strlen(getitembuf)];
>       strcat(getitembuf, "fdb_trsrch");
>       getitemcnt++;
>       */

>       /* Call rtr_request_info. */
>       status = rtr_request_info (
>                            /* *pchannel    */ &channel,
>                             /* flags                */ RTR_NO_FLAGS,
>                             /* infcla               */ infcla_buf,
>                             /* selitm               */ "",
>                             /* selval               */ "*",
>                             /* getitms              */ getitembuf);

>       if (status != RTR_STS_OK)  return;

>       /* Do a receive message to get the information that RTR returns
>        * in response to this request.
>        */
>       do
>       {
>               status = rtr_receive_message(
>                             /* See 'rtr_receive_message'. */
>                                     &channel,
>                                     RTR_NO_FLAGS,
>                                     RTR_ANYCHAN,
>                                     msg,
>                                     sizeof(msg),
>                                     RTR_NO_TIMOUTMS,

>                                     &txsb);

>     /* Check for bad return status from rtr_receive_message(). */
>               if (status != RTR_STS_OK)  return;

>     /* Caller expects either an rtr_mt_closed
>        or an rtr_mt_request_info message. */
>               if (txsb.msgtype == rtr_mt_closed) break;
>                              /* End of data, exit loop.
>                                 Channel closed by RTR. */
>               if (txsb.msgtype != rtr_mt_request_info)
>               {
>                       printf("Unexpected msgtype returned. \n");
>                       break;
>               }
>               else
>               {
>                       /* Receive the requested information.
>                          Scan through item list, output item and value.
>                       */
>                 unsigned int i;
>                 for (i=0, cp = msg; i < getitemcnt; i++, cp += strlen(cp)+1)
>                       {
>                           *(itemlist[i+1]-1) = '\0'; /* Overwrite comma. */

>                               printf("%-8s:%40s\t= '%^s'\n",
>                                          infcla_buf,
>                                              itemlist[i],
>                                              cp);
>                       }
>               }
>       } while (1 == 1);
>       return;

> Command Line Example:

>     RTR> call rtr_request_info/infcla=rtr/selitm=""
>              /selval="*"/getitms=rtr_version_string/chann=D
>     %RTR-S-OK, normal successful completion

>     RTR> call rtr_receive_message/chann=D/tim
>     %RTR-S-OK, normal successful completion
>      channel name:  D
>      msgsb
>        msgtype:     rtr_mt_request_info
>        msglen:      18
>      message
>        offset  bytes                                            text
>     000000  52 54 52 20 56 33 2E 32 28 32 33 30 29 20 46 54  RTR V3.2(230) FT
>     000010  33 00                                            3.

### See Also

> `rtr_close_channel()`
> `rtr_receive_message()`

# rtr_send_to_server

> Send a transactional message to a server.

## Syntax

> status = rtr_send_to_server (channel, flags, pmsg, msglen, msgfmt)

> Argument | Data Type | Access
> --- | --- | ---
> status | rtr_status_t | write
> channel | rtr_channel_t | read
> flags | rtr_sen_flag_t | read
> pmsg | rtr_msgbuf_t | read
> msglen | rtr_msglen_t | read
> msgfmt | rtr_msgfmt_t | read

## C Binding

> rtr_status_t rtr_send_to_server (

> rtr_channel_t channel ,
> rtr_sen_flag_t flags ,
> rtr_msgbuf_t pmsg ,
> rtr_msglen_t msglen ,
> rtr_msgfmt_t msgfmt ,
> )

## Arguments

> ### channel

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

> ### flags

> Table 3-25 shows the flags that specify options for the call.

> Table 3-25 Send to Server Flags
> Flag name | Description
> --- | ---
> RTR_F_SEN_ACCEPT | This is the last message of the transaction, and the tx is accepted. This optimization avoids the need for a separate call to `rtr_accept_tx()` in those cases where the sender knows this is the last (or only) message in the transaction.
> RTR_F_SEN_READONLY | Specifies a read-only server operation. Hence no shadowing or journalling is required. (The message is still written to the journal but is not played to a shadow and is purged after the transaction is completed on the primary. The message is still needed in the journal to allow recovery of in-flight transactions.)
> RTR_F_SEN_RETURN_TO_SENDER | The message is to be returned to the sender if undeliverable.
> RTR_F_SEN_EXPENDABLE | The whole transaction is not aborted if this send fails.

> Specify RTR_NO_FLAGS for this parameter if no flags are required.

> ### pmsg

> Pointer to the message to be sent.

> ### msglen

> Length in bytes of the message to be sent, up to `RTR_MAX_MSGLEN` bytes. The value of `RTR_MAX_MSGLEN` is defined in `rtr.h` .

> ### msgfmt

> Message format description. msgfmt is a null-terminated character string containing 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, RTR Applications in a Multiplatform Environment, for information on defining a message format description.

> This parameter is optional. Specify `RTR_NO_MSGFMT` if the message content is platform independent, or it is not intended to be used on other hardware platforms.

## Description

> The `rtr_send_to_server()` call sends a client's transactional message to a server.

> The caller must first open a client channel (using the `rtr_open_channel()` call), before it can send transactional messages.

> If no transaction is currently active on the channel, a new transaction is started.

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_INVFLAGS | Invalid flags argument
RTR_STS_INVJOINTXID | Invalid join transaction argument
RTR_STS_INVMSGFMT | Invalid msgfmt argument
RTR_STS_INVMSGLEN | Invalid msglen argument
RTR_STS_NOACP | No RTRACP process available
RTR_STS_NOXACHAN | No XA channel available
RTR_STS_OK | Normal successful completion
RTR_STS_REPLYDIFF | Reply from new server did not match earlier reply

## Example

>     /* The my_msg structure is defined in the user's
>      * application header file.
>      */
>     typedef struct {
>                     rtr_uns_8_t     routing_key;
>                     rtr_uns_32_t    sequence_number;
>                     rtr_uns_8_t     my_msg_type;
>                     string31        last_name;
>                     rtr_uns_32_t    order_total;
>                     rtr_uns_32_t    shipping_amt;
>                     string16        cc_number;
>                     string7         cc_expire;
>             } my_msg;

>             my_msg send_msg;

>             .
>             .       Load purchase data into send_msg.
>             .
>     /*
>      * Tell the server to validate the credit card for the
>      * amount of this order.
>      */
>     my_msg.my_msg_type = VALIDATE_CC;
>     status = rtr_send_to_server(
>                     channel,
>                     RTR_NO_FLAGS ,
>                     &send_msg,
>                     sizeof(send_msg),
>                     RTR_NO_MSGFMT );

### See Also

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

# rtr_set_info

> Sets or changes a managed object in the RTR environment.

## Syntax

> status = rtr_set_info (*pchannel, flags, verb, object, *select_qualifiers, *set_qualifiers)

> Argument | Data Type | Access
> --- | --- | ---
> status | rtr_status_t | write
> *pchannel | rtr_channel_t | write
> flags | rtr_set_flag_t | read
> verb | rtr_verb_t | read
> object | rtr_managed_object_t | read
> *select_qualifiers | rtr_qualifier_value_t | read
> *set_qualifiers | rtr_qualifier_value_t | read

## C Binding

> rtr_status_t rtr_set_info (

> rtr_channel_t *pchannel ,
> rtr_set_flag_t flags ,
> rtr_verb_t verb ,
> rtr_managed_object_t object ,
> const rtr_qualifier_value_t *select_qualifiers ,
> const rtr_qualifier_value_t *set_qualifiers
> )

## Arguments

> ### pchannel

> Pointer to the channel opened by a successful call to `rtr_set_info()` .

> ### flags

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

> ### verb

> Always `rtr_verb_set` .

> ### object

> Establishes the type of object to which the call is directed. Values are:
> - `rtr_partition_object` : the target object is a partition
> - `rtr_transaction_object` : the target object is a transaction

> ### select_qualifiers

> Pointer to array containing selection qualifiers. Values depend on object type:

> For: | See the values in:
> --- | ---
> Set Partition | Table 3-26
> Set Transaction | Table 3-27

> For example:

>     typedef struct rtr_qualifier_value_t {
>         rtr_qualifier_t qv_qualifier ;    /* Which qualifier this is */
>         void *qv_value ;                  /* What value it has */
>         } rtr_qualifier_value_t ;

> The last value in the array must be `rtr_qualifiers_end` (see the example). Specify sufficient descriptors to identify the target object.

> Table 3-26 Select Qualifiers for the Set Partition Object
> Qualifier | Value Type | Description | Example
> --- | --- | --- | ---
> rtr_facility_name | const char* | Facility name string | "facility_name"
> rtr_partition_name | const char* | Partition name string | "partition_name"

> Table 3-27 Select Qualifiers for the Set Transaction Object
> Qualifier | Value Type | Description | Example
> --- | --- | --- | ---
> rtr_facility_name | facname | Facility name string | "facility_name"
> rtr_partition_name | partname | Partition name string | "partition_name"
> rtr_txn_state | rtr_txn_jnl_commit | Current transaction state | See Table 3-28 for valid changes from one state to another.
> rtr_txn_tid | tid | Transaction ID | 63b01d10,0,0,0,0,2e59,43ea2002

> When using the Set Transaction Object, the qualifier `rtr_txn_state` is required. In addition, when using `rtr_txn_state` without `rtr_facility_name` or `rtr_partition_name` , `rtr_txn_tid` is required. The qualifiers `rtr_facility_name` and `rtr_partition_name` must be used together. You must always provide the current state when making a state change.

> Table 3-28 Valid Set Transaction State Changes
> From (current state): | To (new state): |  |  |
> --- | --- | --- | --- | ---
> | ABORT | COMMIT | DONE | EXCEPTION
> COMMIT |  |  | YES | YES
> EXCEPTION |  | YES | YES |
> PRI_DONE (remember) |  |  | YES |
> SENDING | YES |  |  |
> VOTED | YES | YES |  |

> ### set_qualifiers

> Pointer to an array containing values of type rtr_qualifier_value_t (see Select Qualifiers above) that describe the desired change to be effected. Table 3-29 and Table 3-30 list qualifiers and value types for the managed object types.

Table 3-29 Qualifiers for Set Partition
Qualifier | Value Type | Value | Desired Action
--- | --- | --- | ---
rtr_partition_state | rtr_partition_state_t | rtr_partition_state_suspend | Suspend transaction presentation.
rtr_partition_state | rtr_partition_state_t | rtr_partition_state_resume | Resume transaction presentation.
rtr_partition_state | rtr_partition_state_t | rtr_partition_state_recover | (Re)start partition recovery.
rtr_partition_state | rtr_partition_state_t | rtr_partition_state_exitwait | Exit partition recovery wait/fail state.
rtr_partition_state | rtr_partition_state_t | rtr_partition_state_shadow | Enable shadowing.
rtr_partition_state | rtr_partition_state_t | rtr_partition_state_noshadow | Disable shadowing.
rtr_partition_cmd_timeout_secs | rtr_uns_32_t | unsigned int | Optional partition suspend timeout period (in seconds).
rtr_partition_rcvy_retry_count | rtr_uns_32_t | unsigned int | Limit number of recovery replays for a transaction.
rtr_partition_failover_policy | rtr_partition_failover_policy_t | rtr_partition_fail_to_standby | Set failover policy to standby.
rtr_partition_failover_policy | rtr_partition_failover_policy_t | rtr_partition_fail_to_shadow | Set failover policy to shadow.
rtr_partition_failover_policy | rtr_partition_failover_policy_t | rtr_partition_pre32_compatible | Set failover policy as pre-V3.2 compatible.

For both managed object types, a message of type `rtr_mt_closed` is returned. See Table 3-30 for the value that can be set for the transaction type.

Completion status is read from message data, which is of type
`rtr_status_data_t` . In addition, a number (type integer) indicating the number of transactions processed is returned. This number can be read from the message following the `rtr_status_data_t` data item. The last value in the array must be `rtr_qualifiers_end` .

Table 3-30 Qualifiers for Set Transaction
Set Qualifier | Set Qualifier Value | Value | Description
--- | --- | --- | ---
rtr_txn_state | rtr_transaction_state_t | rtr_tx_jnl_commit | Set a transaction's state to COMMIT to commit the transaction.
rtr_txn_state | rtr_transaction_state_t | rtr_tx_jnl_abort | Set a transaction state to ABORT to abort the transaction.
rtr_txn_state | rtr_transaction_state_t | rtr_tx_jnl_exception | Mark this as an exception transaction.
rtr_txn_state | rtr_transaction_state_t | rtr_tx_jnl_done | Remove this transaction from the RTR journal; that is, forget this transaction completely.

## Description

> The `rtr_set_info()` call requests a change in a characteristic of the RTR environment. If the call is successful, a channel is opened for asynchronous completion notification. Applications should use the `rtr_receive_message()` call to retrieve informational messages on the opened channel.

> The `rtr_set_info()` call can manipulate two managed object types:

> - Partition type
> - Transaction type

> See Table 3-29 for values that can be set for the partition object and Table 3-30 for values that can be set for the transaction object. Completion status is read from message data, which is of type `rtr_status_data_t` .

Return Value
A value indicating the status of the routine, normally returned as function completion status. Possible status values are:

RTR_STS_ALRDYINSTATE+ | Partition is already in the desired state
RTR_STS_BADPRTSTATE+ | Disallowed attempt to make an illegal or undefined partition state transition
RTR_STS_FACNAMLON+ | Facility name facility_name is larger than 30 characters
RTR_STS_FENAMELONG | Frontend name string length greater than permitted maximum
RTR_STS_INSUFPRIV | Insufficient privileges to run RTR
RTR_STS_INSVIRMEM | Insufficient virtual memory
RTR_STS_INVCHANNEL | Invalid channel argument
RTR_STS_INVFACNAM | Invalid FACNAM argument
RTR_STS_INVFLAGS | Invalid flags argument
RTR_STS_INVOBJCT | Specified object type invalid for managed object request
RTR_STS_INVSTATCHANGE | Invalid to change from the current state to the specified state
RTR_STS_IVQUAL | Unrecognized qualifier - check validity, spelling, and placement
RTR_STS_IVVERB | Unrecognized command verb - check validity and spelling
RTR_STS_NOACTION | No object management action specified - check argument set qualifier
RTR_STS_NODNOTBAC+ | Node not defined as a backend
RTR_STS_NOSUCHPRTN+ | No such partition in the system
RTR_STS_OK | Normal successful completion
RTR_STS_PARTNAMELONG | Partition name too long
RTR_STS_PRTBADCMD+ | Partition command invalid or not implemented in this version of RTR
RTR_STS_PRTBADFPOL+ | Unrecognized partition failover policy code
RTR_STS_PRTLCLRECEXT+ | Partition local recovery terminated by operator
RTR_STS_PRTMODRMBR+ | Partition must be in remember mode on the active member
RTR_STS_PRTNOSRVRS+ | Partition has no servers---please start servers and retry
RTR_STS_PRTNOTBACKEND+ | Partition command must be entered on a backend node
RTR_STS_PRTNOTSUSP+ | Unable to resume partition that is not suspended
RTR_STS_PRTNOTWAIT+ | Partition not in a wait state---no action taken
RTR_STS_PRTRECSTATE+ | Partition must be in remember or active (non-recovery) state
RTR_STS_PRTRESUMED+ | Partition partition_name resumed by operator operator
RTR_STS_PRTRUNDOWN+ | Partition is in a rundown prior to deletion -- no action taken
RTR_STS_PRTSHDRECEXT+ | Partition shadow recovery terminated by operator
RTR_STS_SETTRANDONE+ | n transaction(s) updated in partition partition_name of facility facility_name
RTR_STS_SETTRANROUTER+ | Cannot process this command, coordinator router is still available
RTR_STS_TOOMANCHA | Too many channels already opened
RTR_STS_TRNOTALL032+ | Not all routers are at the minimum required version of V3.2
RTR_STS_VALREQ | Missing qualifier or keyword value---supply all required values
RTR_STS_WTTR | Not in contact with sufficient router nodes -- please retry later

+Returned in status field of rtr_status_data_t data returned with the rtr_mt_closed message. Indicates outcome of request.

## Example

>     /*
>      * This might follow a call to commit the transaction to the database.
>      * If the SQL commit returns an error that is beyond the control of
>      * this application: for example, database disk full, network to
>      * database not responding, or timeout exceeded, it executes.
>      *
>      * Declarations:
>      */
>     rtr_tid_t             tid;
>     rtr_uns_32_t          select_idx;
>     rtr_uns_32_t          set_idx;
>     rtr_qualifier_value_t select_qualifiers[8];
>     rtr_qualifier_value_t set_qualifiers[3];

>     /* Everyone has voted to accept the transaction, and RTR has told the
>      * server to commit it. The client has moved on to performing the next
>      * transaction. This transaction will be changed from `commit' status
>      * to `exception' status for a later attempt at committing.
>      *
>      * Get the transaction id. The channel has previously been
>      * declared in an rtr_open_channel call.
>      */

>     rtr_get_tid(channel, RTR_F_TID_RTR, &tid);

>     /* Load the rtr_qualifier_value_t structures that contain the
>      * selection criteria for the transaction: `the transaction whose tid
>      * is pointed at by `tid', whose facility name is in `facname', whose
>      * partition name is in `partname', and whose transaction state is
>      * `rtr_txn_jnl_commit' (logged to the journal as committed).
>      */
>     select_idx = 0;
>     select_qualifiers[select_idx].qv_qualifier = rtr_txn_tid;
>     select_qualifiers[select_idx].qv_value = &tid;
>     select_idx++;

>     /* Facility name
>      */
>     select_qualifiers[select_idx].qv_qualifier =
>                                rtr_facility_name;
>     select_qualifiers[select_idx].qv_value = facname;
>     select_idx++;

>     /* Partition name
>      */
>     select_qualifiers[select_idx].qv_qualifier = rtr_partition_name;
>     select_qualifiers[select_idx].qv_value = partname;
>     select_idx++;

>     /* Transaction state in journal
>      */
>     select_qualifiers[select_idx].qv_qualifier = rtr_txn_state;
>     select_qualifiers[select_idx].qv_value = &rtr_txn_jnl_commit;
>     select_idx++;

>     /* Last one on array must be `rtr_qualifiers_end'
>      */
>     select_qualifiers[ select_idx].qv_qualifier =
>                                rtr_qualifiers_end,
>     select_qualifiers[ select_idx].qv_value  = NULL;
>     select_idx++;

>     /* Load the
>      * rtr_qualifier_t structs that we will use to set the
>      * new property for the transaction: in this case, only the
>      * state of the transaction. We will change it to
>      * rtr_txn_jnl_exception, or `exception'.
>      */
>     set_idx = 0;

>     set_qualifiers[set_idx].qv_qualifier = rtr_txn_state;
>     set_qualifiers[set_idx].qv_value = &rtr_txn_jnl_exception;
>     set_idx++;

>     /* Terminate the array with an rtr_qualifiers_end.
>      */
>     set_qualifiers[set_idx].qv_qualifier =
>                         rtr_qualifiers_end;
>     set_qualifiers[set_idx].qv_value = NULL;
>     set_idx++;

>     /* Tell RTR to change the transaction's state.
>      */
>     status = rtr_set_info( &pchannel,
>                             RTR_NO_FLAGS,
>                             rtr_verb_set,
>                             rtr_transaction_object,
>                             select_qualifiers,
>                             set_qualifiers);

>     check_status(status);

>     /* The server should now look for an
>      * RTR_STS_SETTRADONE message
>      * from RTR, which confirms that it has changed the status.
>      */

### See Also

> `rtr_close_channel()`
> `rtr_receive_message()`
> `rtr_request_info()`

Previous | Next | Contents | Index