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