# hp Reliable Transaction Router
C++ Foundation Classes

Previous | Contents | Index

# 4.8 RTRKeySegmentArray

An RTRKeySegmentArray object contains pointers to array elements.

Note The RTRKeySegmentArray class requires the holder of the array to clean up (delete) the objects pointed to by the elements of the array; the array does not clean up these objects (does not delete the contents of the array).

# RTRKeySegment Class Members

Construction

Method | Description
--- | ---
RTRKeySegmentArray() | Constructor
~ RTRKeySegment() | Destructor

Operations()

Method | Description
--- | ---
Add(RTRKeySegment) | Add a pointer to the array.
Clear() | Clear the elements of the array.
Insert(size_t, RTRKeySegment) | Insert a pointer to an RTRKeySegment member.
Remove() | Remove an element of the array.
RTRKeySegment operator( size_t) | Return an element of the array which will be a pointer to an RTRKeySegment member.
Size() | Return the number of elements in the array.

# Add()

## RTRKeySegmentArray::Add();

## Prototype

>     bool Add(RTRKeySegment* pFacMember);

## Return Value

> True or False

## Parameters

> ### pFacMember

> Pointer to a facility member.

## Description

> Add a pointer to an RTRKeySegment member to the array. The caller is responsible for creating and destroying the actual object. The array destructor does not destruct the objects pointed to.

## Example

>     bool RTRKeySegmentArray::Add ()
>     {
>     bool bArrayAddStatus;
>     RTRKeySegmentArray ar;
>     RTRKeySegment* pKeySeg;
>     unsigned low=0;
>     unsigned high=10000;
>     pKeySeg = new RTRKeySegment(rtr_keyseg_unsigned, sizeof(unsigned),
>                                  0, &low, &high);
>     if (IsFailure(pKeySeg != NULL))
>     return false;
>     bool bAddOk = ar.Add(pKeySeg);
>     if (IsFailure(bAddOk == true))
>     {
>     delete pKeySeg;
>     return false;
>     }
>     delete pKeySeg;
>     return true;
>     }

# Clear()

## RTRKeySegmentArray::Clear();

## Prototype

>     bool Clear();

## Return Value

> True or False

## Parameters

> None

## Description

> This method clears the elements of the array, resulting in the array having a size of zero. The Clear method does not destroy the objects pointed to.

## Example

>     bool RTRKeySegmentArray::Clear ()
>     {
>     bool bArrayAddStatus;
>     RTRKeySegmentArray ar;
>     RTRKeySegment* pKeySeg0 = NULL;
>     RTRKeySegment* pKeySeg1 = NULL;
>     unsigned low0=0;
>     unsigned high0=10000;
>     unsigned low1=10001;
>     unsigned high1=20000;
>     pKeySeg0 = new RTRKeySegment(rtr_keyseg_unsigned, sizeof(unsigned),
>                                  0, &low0, &high0);
>     if (IsFailure(pKeySeg0 != NULL))
>     return false;
>     bool bAddOk = ar.Add(pKeySeg0);
>     if (IsFailure(bAddOk == true))
>     {
>     delete pKeySeg0;
>     return false;
>     }
>     if (ar.Size() != 1)
>     {
>     delete pKeySeg0;
>     return false;
>     }
>     pKeySeg1 = new RTRKeySegment(rtr_keyseg_unsigned, sizeof(unsigned),
>                                  0, &low1, &high1);
>     if (IsFailure(pKeySeg1 != NULL))
>     {
>     delete pKeySeg0;
>     return false;
>     }
>     bool bInsertOk = ar.Insert(0, pKeySeg1);
>     if (IsFailure(bInsertOk == true))
>     {
>     delete pKeySeg0;
>     delete pKeySeg1;
>     return false;
>     }
>     bool bClearOk = ar.Clear();
>     if (IsFailure(bClearOk == true))
>     {
>     delete pKeySeg0;
>     delete pKeySeg1;
>     return false;
>     }
>     if (IsFailure(ar.Size() == 0))
>     {
>     delete pKeySeg0;
>     delete pKeySeg1;
>     return false;
>     }
>     delete pKeySeg0;
>     delete pKeySeg1;
>     return true;
>     }

# Insert()

## RTRKeySegmentArray::Insert();

## Prototype

>     bool Insert(size_t n, RTRKeySegment* pFacMember);

## Return Value

> True or False

## Parameters

> ### n

> The element in the array (ar[0] is the first element). The element is a pointer to an object.

> ### pFacMember

> Pointer to a facility member.

## Description

> Insert a pointer to an RTRKeySegment member into the nth position, moving the remainder of the array to make room.

## Example

>     bool RTRKeySegmentArray::Insert ()
>     {
>     bool bArrayAddStatus;
>     RTRKeySegmentArray ar;
>     RTRKeySegment* pKeySeg0;
>     RTRKeySegment* pKeySeg1;
>     unsigned low0=0;
>     unsigned low1=10001;
>     unsigned high0=10000;
>     unsigned high1=20000;
>     pKeySeg0 = new RTRKeySegment(rtr_keyseg_unsigned, sizeof(unsigned),
>                                  0, &low0, &high0);
>     if (IsFailure(pKeySeg0 != NULL))
>     return false;
>     bool bAddOk = ar.Add(pKeySeg0);
>     if (IsFailure(bAddOk == true))
>     {
>     delete pKeySeg0;
>     return false;
>     }
>     if (ar.Size() != 1)
>     {
>     delete pKeySeg0;
>     return false;
>     }
>     pKeySeg1 = new RTRKeySegment(rtr_keyseg_unsigned, sizeof(unsigned),
>                                  0, &low1, &high1);
>     if (IsFailure(pKeySeg1 != NULL))
>     {
>     delete pKeySeg0;
>     return false;
>     }
>     bool bInsertOk = ar.Insert(0, pKeySeg1);
>     if (IsFailure(bInsertOk == true))
>     {
>     delete pKeySeg0;
>     delete pKeySeg1;
>     return false;
>     }
>     delete pKeySeg0;
>     delete pKeySeg1;
>     return true;
>     }

# Remove()

## RTRKeySegmentArray::Remove(const size_t n);

## Prototype

>     size_t Remove(const size_t n);

## Return Value

> size_t The amount of allocated space.

## Parameters

> ### n

> The element in the array (ar[0] is the first element). The element is a pointer to an object.

## Description

> This method removes the nth element of the array. Calling this method does not destroy the object pointed to; the caller needs to delete the contents.

## Example

>     bool RTRKeySegmentArray::Remove ()
>     {
>     bool bArrayAddStatus;
>     RTRKeySegmentArray ar;
>     RTRKeySegment* pKeySeg;
>     unsigned low=0;
>     unsigned high=10000;
>     pKeySeg = new RTRKeySegment(rtr_keyseg_unsigned, sizeof(unsigned),
>                                 0, &low, &high);
>     if (IsFailure(pKeySeg != NULL))
>     return false;
>     bool bAddOk = ar.Add(pKeySeg);
>     if (IsFailure(bAddOk == true))
>     {
>     delete pKeySeg;
>     return false;
>     }
>     bool bRemoveOk = ar.Remove(0);
>     if (IsFailure(bRemoveOk == true))
>     {
>     delete pKeySeg;
>     return false;
>     }
>     delete pKeySeg;
>     return true;
>     }

# RTRKeySegmentArray()

## RTRKeySegmentArray::RTRKeySegmentArray();

## Prototype

>     RTRKeySegmentArray();
>     virtual ~RTRKeySegmentArray();

## Return Value

> None

## Parameters

> None

## Description

> Call this method to construct new RTRKeySegmentArray object.

## Example

>     Test_RTRKeySegmentArray::Test_RTRKeySegmentArray ()
>     {
>     }

# Operator()

## RTRKeySegmentArray::operator();

## Prototype

>     RTRKeySegment*& operator[ ] (size_t n);

## Return Value

> Returns the nth element of the array.

## Parameters

> ### n

> The element in the array (ar[0] is the first element). The element is a pointer to an object.

## Description

> This operator returns the nth element of the array which will be a pointer to an RTRKeySegment member. This operator can also be used to set the nth element of the array. The existing element pointed to is not destroyed; the caller must delete this.

## Example

>     bool Test_RTRKeySegmentArray::arrayoper()
>     {
>     bool bArrayAddStatus;
>     RTRKeySegmentArray ar;
>     RTRKeySegment* pKeySeg;
>     unsigned low=0;
>     unsigned high=10000;
>     pKeySeg = new RTRKeySegment(rtr_keyseg_unsigned, sizeof(unsigned),
>                                 0, &low, &high);
>     if (IsFailure(pKeySeg != NULL))
>     return false;
>     bool bAddOk = ar.Add(pKeySeg);
>     if (IsFailure(bAddOk == true))
>     {
>     delete pKeySeg;
>     return false;
>     }
>     if (ar.Size() != 1)
>     {
>     delete pKeySeg;
>     return false;
>     }
>     RTRKeySegment* pSeg0 = ar[0];
>     if (IsFailure(pSeg0 != NULL))
>     {
>     delete pKeySeg;
>     return false;
>     }
>     delete pKeySeg;
>     return true;
>     }

# Size()

## RTRKeySegmentArray::Size();

## Prototype

>     size_t Size() const;

## Return Value

> size_t The amount of space to be allocated.

## Parameters

> None

## Description

> The method returns the number of elements in the array.

## Example

>     bool RTRKeySegmentArray::Size ()
>     {
>     bool bArrayAddStatus;
>     RTRKeySegmentArray ar;
>     RTRKeySegment* pKeySeg;
>     unsigned low=0;
>     unsigned high=10000;
>     pKeySeg = new RTRKeySegment(rtr_keyseg_unsigned, sizeof(unsigned),
>                                 0, &low, &high);
>     if (IsFailure(pKeySeg != NULL))
>     return false;
>     bool bAddOk = ar.Add(pKeySeg);
>     if (IsFailure(bAddOk == true))
>     {
>     delete pKeySeg;
>     return false;
>     }
>     if (ar.Size() != 1)
>     {
>     delete pKeySeg;
>     return false;
>     }
>     delete pKeySeg;
>     return true;
>     }

# 4.9 RTRPartitionManager

The RTRPartitionManager allows the RTR applictaion to create, delete and obtain properties for a partition.

A partition is composed of one or more key segments. These key segments define the location of data within the applications message, the type of the data and a range of values for the data. RTR uses this information to perform its data routing. One or more partitions can be registered with a server transaction controller.

The key segments are associated with a partition when the partition is created. A partition exists within one facility. A facility can have many partitions.

# RTRPartitionManager Class Members

Construction

Method | Description
--- | ---
RTRPartitionManager() | Constructor
~RTRPartitionManager() | Destructor

Operations

Method | Description
--- | ---
CreateBackendPartition(rtr_const_parnam_t, rtr_const_facnam_t, RTRKeySegment, const bool, const bool, const bool) | Creates a partition on a backend within an existing facility.
CreateBackendPartition(rtr_const_parnam_t, rtr_const_facnam_t, RTRKeySegmentArray, const bool, const bool, const bool) | Creates a partition on a backend within an existing facility.using an RTRKeySegmentArray.
DeletePartition(rtr_const_parnam_t, rtr_const_facnam_t) | Deletes a partition.
GetBackendPartitionProperties(rtr_const_parnam_t) | Retrieves properties for a partition on a backend.

# CreateBackendPartition()

## RTRPartitionManager::CreateBackendPartition();

## Prototype

>     virtual rtr_status_t CreateBackendPartition(
>                                       rtr_const_parnam_t pszPartitionName,
>                                       rtr_const_facnam_t pszFacilityName,
>                                       RTRKeySegment &KeySegment,
>                                       const bool bShadow = false,
>                                       const bool bConcurrent = true,
>                                       const bool bStandby = true);
>     virtual rtr_status_t CreateBackendPartition(
>                                       rtr_const_parnam_t pszPartitionName,
>                                       rtr_const_facnam_t pszFacilityName,
>                                       RTRKeySegment &KeySegmentArray,
>                                       const bool bShadow = false,
>                                       const bool bConcurrent = true,
>                                       const bool bStandby = true);

## Return Value

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

Status | Message
--- | ---
RTR_STS_INVFACNAMEARG | The facility name argument is invalid.
RTR_STS_INVKEYSEGPTARG | Invalid key segment object pointer argument.
RTR_STS_INVPARTNAMEARG | The partition name argument is invalid.
RTR_STS_MAXPARTREG | Maximum partition limit.
RTR_STS_OK | Normal successful completion.

## Parameters

> ### pszPartitionName

> A null-terminated pointer to a partition name.

> ### pszFacilityName

> A null-terminated pointer to a facility name.

> ### KeySegment

> A key segment for the specified partition name.

> ### KeySegmentArray

> An array of key segments for the specified partition name.

> ### bShadow

> A boolean attribute for specifying a shadow server.

> ### bConcurrent

> A boolean attribute for specifying a concurrent server.

> ### bStandby

> A boolean attribute for specifying a standby server.

## Description

> CreateBackendPartition method creates an RTR backend partition. The partition characteristics that may be defined include key range or ranges and whether attached server process can be shadows or standbys. The command must be issued before any server application programs using the partition are started.

## Example

>     RTRKeySegment *pCharacterStringSegment = new RTRKeySegment(
>                                    rtr_keyseg_string, 1,0,"y","z");

>     RTRPartitionManager PartitionManager;

>     sStatus = PartitionManager.CreateBackendPartition(

>                                                "MyPartition",
>                                                "myfac",
>                                                &pCharacterStringSegment,
>                                                false,true,true);
>     // boolean parameters are for specifying shadow, concurrent, standby

> From the Sample application in the Examples directory:

>     RTRPartitionManager PartitionManager;
>     sStatus = PartitionManager.CreateBackEndPartition(  ABCPartition1,
>                                                         ABCFacility,
>                                           KeyZeroTo99,false,true,false);

# DeletePartition()

## RTRPartitionManager::DeletePartition();

## Prototype

>     virtual rtr_status_t DeletePartition( rtr_const_parnam_t pszPartitionName,
>                                           rtr_const_facnam_t pszFacility );

## Return Value

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

Status | Message
--- | ---
RTR_STS_INVFACNAMEARG | The facility name argument is invalid.
RTR_STS_INVPARTNAMEARG | The partition name argument is invalid.
RTR_STS_OK | Normal successful completion.
RTR_STS_PRTNDELETED | Deletion of partition failed with error.

## Parameters

> ### pszPartitionName

> A null-terminated pointer to a partition name.

> ### pszFacility

> A null-terminated pointer to a facility name.

## Description

> Call this method to delete a partition from a facility.

## Example

>     Char *pszFac = "MyFacility";
>     Char *pszPartition = "MyPartitionName";
>     sStatus = PartitionManager.DeletePartition(pszFac,pszPartition);

# GetBackendPartitionProperties()

## RTRPartitionManager::GetBackendPartitionProperties();

## Prototype

>     virtual RTRBackendPartitionProperties*
>          GetBackendPartitionProperties(rtr_const_parnam_t pszPartitionName);

## Return Value

> RTRBackendPartitionProperties* Pointer to the RTRBackendPartitionProperties object associated with this RTRPartitionManager object.

Status | Message
--- | ---
RTR_STS_OK | Normal successful completion.
RTR_STS_INVPARTNAMEARG | The partition name argument is invalid.

## Parameters

> ### pszPartitionName

> A null-terminated pointer to a partition name.

## Description

> This method retrieves the properties associated with the RTRPartitionManager object. These properties are contained within an associated
> RTRBackendPartitionProperties object.

## Example

>     RTRBackendPartitionProperties *pPartProperties =
>     PartitionManager.GetBackendPartitionProperties("MyPartition");

# RTRPartitionManager()

## RTRPartitionManager::RTRPartitionManager();

## Prototype

>     RTRPartitionManager();
>     virtual ~RTRPartitionManager();

## Return Value

> None

## Parameters

> None

## Description

> This method defines an RTRPartitionManager object.

## Example

>         RTRPartitionManager PartitionManager;

# 4.10 RTRSignedCounter

To use a counter, perform the following steps:

- Declare the names for counter name and group name.
- Instantiate the counter using the counter name and group.
- Set the counter value and test for success.
- Increment the counter.
- Get the incremented value.

# RTRSignedCounter Class Members

Construction

Method | Description
--- | ---
RTRSignedCounter( rtr_const_countername_t, rtr_const_countergroupname_t) | Constructor
~RTRSignedCounter() | Destructor

Operations

Method | Description
--- | ---
Decrement() | Decrement the value managed by the counter class.
GetValue(rtr_sgn_32_t) | Retrieve the value managed by the counter class.
Increment() | Increment the value managed by the counter class.
SetValue(rtr_sgn_32_t) | Set the value managed by the counter class.

Previous | Next | Contents | Index