# hp Reliable Transaction Router
C++ Foundation Classes

Previous | Contents | Index

# RTR()

## RTR::RTR();

## Prototype

>     RTR();

## Return Value

> None

## Parameters

> None

## Description

> Call this method to declare an RTR object.

## Example

>     RTR *myRTR = new RTR();

# Start()

## RTR::Start();

## Prototype

>     rtr_status_t Start();

## Return Value

> rtr_status_t Interpret value for the success or failure of this call.

Status | Message
--- | ---
RTR_STS_ ACPDIED | The RTR ACP is no longer running, restart RTR.
RTR_STS_ ACPNOTVIA | ACP is no longer a viable entity.
RTR_STS_ BYTLMNSUFF | Insufficient process quota bytlm, required 100000.
RTR_STS_ ERRSTAACP | Unable to start ACP.
RTR_STS_ EXWSMAX | Requested memory quotas exceed the system limit WSMAX.
RTR_STS_OK | Normal successful completion.

## Parameters

> None

## Description

> Call this method to start RTR on a node.

## Example

>         // declare RTR object.
>         RTR *myRTR = new RTR();
>         rtr_status_t sStatus;
>         sStatus = myRTR->Start();

# StartWebServer()

## RTR::StartWebServer();

## Prototype

>     rtr_status_t StartWebServer(bool bAuthentication = true,
>                                 bool bReadOnlyAccess = false);

## Return Value

> rtr_status_t Interpret value for the success or failure of this call. RTR_STS_OK is the normal successful completion.

## Parameters

> ### bAuthentication

> A boolean attribute for specifying and controlling the web server user authentication. The default setting is for the server to perform user authentication using the username and password. This may be disabled, allowing anyone with a browser to access the management component.

> ### bReadOnlyAccess

> A boolean attribute for specifying read-only access to the web browser RTR management component. A server started with the StartWebServer method servers status and monitor pages but does not permit any changes to be made to the configuration. By specifying read-only access for server operation, no shadowing or journaling 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 server. The message is still needed in the journal to allow recovery of in-flight transactions.

## Description

> Call this method to start RTR on a web server. This starts a user's HTTP server component, thus enabling usage of the web browser RTR management component for the calling user.

## Example

>     bool RTR::StartWebServer()
>     {
>         bool bOverallResult = true;
>         RTR MyRTR;
>     rtr_status_t stsStartWebServer;
>     stsStartWebServer = MyRTR.StartWebServer();
>     if (IsFailure(stsStartWebServer == RTR_STS_OK))
>     {
>         bOverallResult = false;
>         OutputStatus(stsStartWebServer);
>     }

# Stop()

## RTR::Stop();

## Prototype

>     rtr_status_t Stop();

## Return Value

> rtr_status_t Interpret value for the success or failure of this call.

Status | Description
--- | ---
RTR_STS_ ACPDIED | The RTR ACP is no longer running, restart RTR.
RTR_STS_OK | Normal successful completion.
RTR_STS_ RTRNOTRUN | RTR not running.

## Parameters

> None

## Description

> Call this method to stop RTR on a node. Calling this method stops all RTR activity on the computer where it is called. Any running applications receive the error indication RTR_STS_NOACP. All facilities, links, and partitions are destroyed.

## Example

>         // declare RTR object
>         RTR *myRTR = new RTR();
>         rtr_status_t sStatus;
>         sStatus = myRTR->Stop();

# StopWebServer()

## RTR::StopWebServer();

## Prototype

>     rtr_status_t StopWebServer();

## Return Value

> rtr_status_t Interpret value for the success or failure of this call.

Status | Message
--- | ---
RTR_STS_ NFW | Operation requires SETPRV privilege.
RTR_STS_OK | Normal successful completion.
RTR_STS_SRVDISCON | Server disconnected on node 'nodename.'

## Parameters

> None

## Description

> Call this method to stop RTR on a web server.

## Example

>     rtr_status_t stsStopWebServer;
>     stsStopWebServer = MyRTR.StopWebServer();
>     if (IsFailure(stsStopWebServer == RTR_STS_OK || stsStopWebServer ==
>     RTR_STS_SRVDISCON))
>     {   bOverallResult = false;
>         OutputStatus(stsStopWebServer);
>     }

# 4.2 RTRBackendPartitionProperties

This class holds and makes available the properties of its associated RTRBackendPartition object. This allows the RTR application to Get and Set various attributes of an RTR partition. This class may be called by both new C++ API and legacy applications.

# RTRBackendPartitionProperties Class Members

Construction

Method | Description
--- | ---
RTRBackendPartitionProperties(const char) | Constructor
~RTRBackendPartitionProperties(const char) | Destructor

Operations()

Method | Description
--- | ---
GetFacilityName(rtr_facnam_t, const size_t) | Gets the facility name associated with the RTRPartition object this RTRPartitionProperties object describes.
GetNumberOfRecoveredTransactions (rtr_uns_32_t) | Gets the number of recovered transactions associated with the RTRPartition object this RTRPartitionProperties object describes.
GetPartitionName(rtr_parnam_t, const size_t) | Gets the partition name associated with the RTRPartition object this RTRPartitionProperties object describes.
GetRetryCount(rtr_uns_32_t) | Gets the number of retrys associated with the RTRPartition object this RTRPartitionProperties object describes.
SetFailoverPolicy(const eRTRFailoverPolicy) | Defines the policy that RTR should take when a primary partition fails.
SetPriorityList(const char) | Sets a relative priority used by RTR when selecting a backend member to make active.
SetRecoveryRetryCount (rtr_uns_32_t) | Indicates the maximum number of times that a transaction should be presented for recovery before being written to the journal as an exception.

# GetFacilityName()

## RTRBackendPartitionProperties::GetFacilityName();

## Prototype

>     rtr_status_t GetFacilityName(rtr_facnam_t pszFacilityName,
>                                 const size_t uiFacilityNameSize);

## Return Value

> rtr_status_t Interpret value for the success or failure of this call.

Status | Message
--- | ---
RTR_STS_ APPBUFFTOOSMALL | The application buffer is too small.
RTR_STS_INVARGPTR | Invalid parameter address specified on last call.
RTR_STS_OK | Normal successful completion.

## Parameters

> ### pszFacilityName

> Pointer to a zero-terminated string receiving the facility name for the RTRPartition this RTRPartitionProperties object describes.

> ### uiFacilityNameSize

> An unsigned integer for the size of the specified facility name. The maximum string length is RTR_MAX_FACNAM_LEN.

## Description

> Gets the facility name associated with the RTRPartition object this RTRPartitionProperties object describes.

## Example

>     // declare a partition properties object.
>     rtr_status_t sStatus;
>     RTRBackendPartitionProperties *pPartProperties =
>         PartitionManager.GetBackendPartitionProperties("MyPartition");
>     char *pszFacilityName = new char[RTR_MAX_FACNAM_LEN+1];
>     sStatus = pPartProperties->GetFacilityName(pszFacilityName,
>                                                 RTR_MAX_FACNAM_LEN+1);

# GetNumberOfRecoveredTransactions()

## RTRBackendPartitionProperties::GetNumberOfRecoveredTransactions()

## Prototype

>     rtr_status_t GetNumberOfRecoveredTransactions(rtr_uns_32_t
>                                                   &uiNumberRecoveredTxns);

## Return Value

> Interpret value for the success or failure of this call. RTR_STS_OK is the normal successful completion.

## Parameters

> ### uiNumberRecoveredTxns

> A referenced value of type rtr_uns_32_t which receives the number of recovered transactions.

## Description

> Gets the number of recovered transactions associated with the RTRPartition object this RTRPartitionProperties object describes.

> For more information, see the RTR System Manager's Manual.

## Example

>     // declare a partition properties object.
>     rtr_status_t sStatus;
>     RTRBackendPartitionProperties *pPartProperties =
>         PartitionManager.GetBackendPartitionProperties()"MyPartition");
>     rtr_uns_32_t iNumberRecoveredTxns
>     sStatus = pPartProperties->
>                 GetNumberOfRecoveredTransactions(iNumberRecoveredTxns);

# GetPartitionName()

## RTRBackendPartitionProperties::GetPartitionName();

## Prototype

>     rtr_status_t GetPartitionName(rtr_parnam_t pszPartitionName
>                                   const size_t uiPartitionNameSize);

## Return Value

> rtr_status_t Interpret value for the success or failure of this call.

Status | Message
--- | ---
RTR_STS_APPBUFFTOOSMALL | The application buffer is too small.
RTR_STS_INVARGPTR | Invalid parameter address specified on last call.
RTR_STS_OK | Normal successful completion.

## Parameters

> ### pszPartitionName

> Pointer to a null-terminated string receiving the partition name for the RTRPartition this RTRPartitionProperties object describes.

> ### uiPartitionNameSize

> An unsigned integer for the size of the specified partition name.

## Description

> Gets the partition name associated with the RTRPartition object this RTRPartitionProperties object describes.

## Example

>     // declare a partition properties object.
>     rtr_status_t sStatus;
>     RTRBackendPartitionProperties *pPartProperties =
>          PartitionManager.GetBackendPartitionProperties("MyPartition");
>     char *pszPartitionName = new char[RTR_MAX_PARNAM_LEN+1];
>     sStatus = pPartProperties->GetPartitionName(pszPartitionName,
>                                                 RTR_MAX_PARNAM_LEN+1);

# GetRetryCount()

## RTRBackendPartitionProperties::GetRetryCount();

## Prototype

>     rtr_status_t GetRetryCount(rtr_uns_32_t &uiRetryCount);

## Return Value

> rtr_status_t Interpret value for the success or failure of this call. RTR_STS_OK is the normal successful completion.

## Parameters

> ### uiRetryCount

> A referenced value of type rtr_uns_32_t which receives the number of retries.

## Description

> Gets the number of times a transaction has been retried after a failure.

## Example

>     // declare a partition properties object.
>     rtr_status_t sStatus;
>     RTRBackendPartitionProperties *pPartProperties =
>     PartitionManager.GetBackendPartitionProperties("MyPartition");
>     rtr_uns_32_t iRetryCount;
>     sStatus = pPartProperties->GetRetryCount(iRetryCount);

# RTRBackendPartitionProperties()

## RTRBackendPartitionProperties::RTRBackendPartitionProperties();

## Prototype

>     RTRBackendPartitionProperties( rtr_const_parnam_t pszPartitionName );
>     virtual ~RTRBackendPartitionProperties();

## Return Value

> None

## Parameters

> ### pszPartitionName

> Pointer to a zero-terminated string containing the partition name for which this RTRPartitionProperties object is being created.

## Description

> Call this constructor to create an RTRPartitionProperties object for the partition named.

## Example

>     // Create BackendPartitionProperties object
>     RTRBackendPartitionProperties *pBEPartitionProperties;
>     pBEPartitionProperties = pPartitionManager->
>                GetBackendPartitionProperties(GetDefaultPartitionName());
>     if (IsFailure(pBEPartitionProperties != NULL))
>     {
>     bOverallResult = false;
>     cout << endl << "        In Test_GetFacilityName(),
>         pPartitionManager->GetBackendPartitionProperties()
>             call failed." << endl;
>     delete pPartitionManager;
>     return bOverallResult; }

# SetFailoverPolicy()

## RTRBackendPartitionProperties::SetFailoverPolicy();

## Prototype

>     rtr_status_t SetFailoverPolicy(const eRTRFailoverPolicy eFailoverPolicy);

## Return Value

> rtr_status_t Interpret value for the success or failure of this call.

Status | Message
--- | ---
RTR_STS_OK | Normal successful completion.
RTR_STS_PRTBADCMD | Partition command invalid or not implemented in this version of RTR.

## Parameters

> ### eRTRFailoverPolicy

> An attribute for specifying an RTR failover policy:

> 1 = RTRFailOverToShadow

> 2 = RTRFailOverToStandBy

## Description

> Determines the action to take when the primary partition fails. The default action is to allow a standby of the primary to become the new primary. Optionally, RTR can be set to change state so that the secondary becomes primary, and a standby of the old primary (if any) becomes the new secondary.

## Example

>     // declare a partition properties object.
>     rtr_status_t sStatus;
>     RTRBackendPartitionProperties *pPartProperties =
>           PartitionManager.GetBackendPartitionProperties("MyPartition");
>     const RTRFailoverPolicy eFailoverPolicy = RTRFailOverToShadow;
>     sStatus = pPartProperties->SetFailoverPolicy(eFailoverPolicy);

# SetPriorityList()

## RTRBackendPartitionProperties::SetPriorityList();

## Prototype

>     rtr_status_t SetPriorityList(const char *pszPriorityList);

## Return Value

> rtr_status_t Interpret value for the success or failure of this call.

Status | Message
--- | ---
RTR_STS_OK | Normal successful completion.
RTR_STS_PRTBADCMD | Partition command invalid or not implemented in this version of RTR.

## Parameters

> ### pszPriorityList

> A null-terminated string pointer to a priority list.

## Description

> Sets a relative priority used by RTR when selecting a backend member to make active. List the backends in your configuration in decreasing order of priority; the order of the list is taken into consideration when RTR is decides where to make a partition active.

> Suspend partitions before changing the priority list. It is not an error to enter different versions of the priority list at different backends, but this is not recommended. If calling SetPriorityList, it is recommended to call SetPriorityList programmatically before you register the partition with the server transaction controller.

## Example

>     // declare a partition properties object.
>     rtr_status_t sStatus;
>     RTRBackendPartitionProperties *pPartProperties =
>          PartitionManager.GetBackendPartitionProperties("MyPartition");
>     char *pszPriorityList = "depth,length"; // list of BE for prioirty
>     sStatus = pPartProperties->SetPriorityList(pszPriorityList);

# SetRecoveryRetryCount()

## RTRBackendPartitionProperties::SetRecoveryRetryCount();

## Prototype

>     rtr_status_t SetRecoveryRetryCount(rtr_uns_32_t & uiRetryCount);

## Return Value

> rtr_status_t Interpret value for the success or failure of this call.

Status | Message
--- | ---
RTR_STS_OK | Normal successful completion
RTR_STS_APPBUFFTOOSMALL | The application buffer is too small.

## Parameters

> ### uiRetryCount

> A referenced value of type rtr_uns_32_t that receives the number of retries.

## Description

> Call this method to set the recovery retry count. The recovery retry count indicates the maximum number of times that a transaction should be presented for recovery before being written to the journal as an exception. Once a transaction has been recorded as an exception, it is no longer considered eligible for recovery and will require manual processing by a qualified individual.

## Example

>     // declare a partition properties object.
>     rtr_status_t sStatus;
>     RTRBackendPartitionProperties *pPartProperties =
>         PartitionManager.GetBackendPartitionProperties("MyPartition");
>     rtr_uns_32_t iRetryCount=10; // #of times to retry before giveup.
>     sStatus = pPartProperties->SetRecoveryRetryCount(iRetryCount);

Previous | Next | Contents | Index