Management classes are offered for both new and existing RTR applications. The types of management classes include:

• Setup class:

• Facility classes:

• Partition classes:

• Counter classes:

rtr_status_t GetName( rtr_facnam_t pszFacilityName, const size_t uiFacilityNameSize);

A pointer to a facility name.

An unsigned integer for the facility name size.

Retrieve the name of the facility member.

rtr_status_t HasBackendRole(bool &bHasRole);

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

bHasRole

A boolean that is true or false for HasBackendRole.

Call this method to find out a node is configured as backend.

rtr_status_t HasFrontendRole(bool &bHasRole);

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

bHasRole

A boolean that is true or false for HasFrontendRole.

Call this method to find out if a node is configured as frontend.

rtr_status_t HasRouterRole(bool &bHasRole);

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

bHasRole

A boolean that is true or false for HasRouterRole.

Call this method to find out if a node is configured as router.

rtr_status_t IsConnectedToLocalNode(bool &bIsConnected);

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

bIsConnected

A boolean that is true if the node is connected to the local node.

Call this method to find out if this node is connected to the local node.

rtr_status_t IsLocalNode(bool &bIsLocal);

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

bIsLocal

A boolean that is true if the node is a local node.

Call this method to find out if the node is a local node.

RTRFacilityMember( rtr_const_facnam_t pszFacilityName,
rtr_const_nodnam_t pszMemberName);

pszFacilityName

A null-terminated pointer to a facility name.

A null-terminated string pointer to the name of a facility member.

Call this method to declare a facility member object. The member role type can be:

• 1 (RTRFacilityBackend)
• 2 (RTRFacilityRouter)
• 3 (RTRFacilityFrontend)

rtr_status_t GetMemberList(RTRFacilityMemberArray &aFacilityMembers);

Interpret value for the success or failure of this call.

aFacilityMembers

An array listing a facility's members.

Retrieve a list of nodes and their roles for an existing facility.

RTRFacilityProperties( rtr_const_facnam_t pszFacilityName);

pszFacility

A null-terminated pointer to a facility name.

This method retrieves the properties associated with the facility object.

rtr_status_t SetBalance( bool bBalancingOn );

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

bBalancingOn

A boolean attribute for specifying RTR balancing of client requests for server processing.

Specifies whether router balancing is to be performed.

A key segment describes the data that the RTR application is sending. RTR uses this description for routing the data to an appropriate server. Key segments are of no value unless they are associated with a partition. When creating a partition, the caller is allowed to specify one or more key segments.

The RTRKeySegment class defines key segments (ranges) used in defining RTRPartition objects. RTRPartition objects are used to enable the partitioning of data across multiple servers.

Operations

rtr_pointer_t GetKeySegmentHighValue();

This method returns the upper-bound key value of the key segment.

rtr_keylen_t GetKeySegmentLength();

This method gets the length of the key segment key.

rtr_pointer_t GetKeySegmentLowValue();

This method returns the lower-bound key value of the key segment.

rtr_keylen_t GetKeySegmentOffset();

This method gets the offset of the key segment key within the message stream.

rtr_keyseg_type_t GetKeySegmentType();

• rtr_keyseg_signed
• rtr_keyseg_unsigned
• rtr_keyseg_string

This method gets the data type of the key segment.

RTRKeySegment(rtr_keyseg_type_t keySegmentType,

keySegmentType

• rtr_keyseg_signed
• rtr_keyseg_unsigned
• rtr_keyseg_string

Call this constructor to create an RTRKeySegment object.

rtr_status_t SetKeySegmentHighValue(rtr_const_pointer_t pKeySegmentHighValue );

Interpret value for the success or failure of this call.

pKeySegmentHighValue

This method sets the upper bound of the key range for the key segment.

rtr_status_t SetKeySegmentLength(const rtr_keylen_t keySegmentLength );

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

keySegmentLength

This method sets the length of the keysegment key.

rtr_status_t SetKeySegmentLowValue(rtr_const_pointer_t pKeySegmentLowValue);

Interpret value for the success or failure of this call.

pKeySegmentLowValue

This method sets lower bound of the key range for the key segment.

rtr_status_t SetKeySegmentOffset( const rtr_keylen_t keySegmentOffset );

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

keySegmentOffset

This method sets the offset of the key segment key within the message stream.

rtr_status_t SetKeySegmentType( const rtr_keyseg_type_t keySegmentType);

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

keySegmentType

• rtr_keyseg_signed
• rtr_keyseg_unsigned
• rtr_keyseg_string

This method sets the data type of the key segment.

An RTRKeySegmentArray object contains pointers to array elements.

Operations

bool Add(RTRKeySegment* pFacMember);

pFacMember

Pointer to a facility member.

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.

bool Clear();

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.

bool Insert(size_t n, RTRKeySegment* pFacMember);

n

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

Pointer to a facility member.

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

size_t Remove(const size_t n);

n

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

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.

RTRKeySegmentArray();

Call this method to construct new RTRKeySegmentArray object.

RTRKeySegment*& operator[ ] (size_t n);

n

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

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.

size_t Size() const;

The method returns the number of elements in the array.

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.

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);

Interpret value for the success or failure of this call.

pszPartitionName

A null-terminated pointer to a partition name.

A null-terminated pointer to a facility name.

A key segment for the specified partition name.

An array of key segments for the specified partition name.

A boolean attribute for specifying a shadow server.

A boolean attribute for specifying a concurrent server.

A boolean attribute for specifying a standby server.

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.

From the Sample application in the Examples directory:

KeyZeroTo99,false,true,false);

virtual rtr_status_t DeletePartition( rtr_const_parnam_t pszPartitionName,
rtr_const_facnam_t pszFacility );

Interpret value for the success or failure of this call.

pszPartitionName

A null-terminated pointer to a partition name.

A null-terminated pointer to a facility name.

Call this method to delete a partition from a facility.

virtual RTRBackendPartitionProperties*
GetBackendPartitionProperties(rtr_const_parnam_t pszPartitionName);

Pointer to the RTRBackendPartitionProperties object associated with this RTRPartitionManager object.

pszPartitionName

A null-terminated pointer to a partition name.

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

RTRPartitionManager();

This method defines an RTRPartitionManager object.

To use a counter, perform the following steps:

1. Declare the names for counter name and group name.
2. Instantiate the counter using the counter name and group.
3. Set the counter value and test for success.
4. Increment the counter.
5. Get the incremented value.

rtr_status_t Decrement();

Interpret value for the success or failure of this call.

The more specificcounter class error status descriptions for RTR_STSCTRBADREF and RTR_STS_INVOBJFAILCNSTR are:

• RTR_STSCTRBADREF

• RTR_STS_INVOBJFAILCNSTR

Call this method to decrement a numeric counter. Decrement method can be called only after setting value (RTRSignedCounter::SetValue(CounterVal)).

rtr_status_t GetValue(rtr_sgn_32_t &CounterVal);

Interpret value for the success or failure of this call.

The more specificcounter class error status descriptions for RTR_STSCTRBADREF and RTR_STS_INVOBJFAILCNSTR are:

• RTR_STSCTRBADREF

• RTR_STS_INVOBJFAILCNSTR

The object is invalid because the values passed in the constructor were invalid.

CounterVal

A counter value for a specified RTR counter.

Call this method to get a counter value. GetValue can be called only after setting value (SetValue).

rtr_status_t Increment();

Interpret value for the success or failure of this call.

The more specificcounter class error status descriptions for RTR_STSCTRBADREF and RTR_STS_INVOBJFAILCNSTR are:

• RTR_STSCTRBADREF

• RTR_STS_INVOBJFAILCNSTR

The object is invalid because the values passed in the constructor were invalid.

Call this method to increment a numeric counter. This method can be called only after setting value.

rtr_status_t SetValue( rtr_sgn_32_t CounterVal );

Interpret value for the success or failure of this call.

The more specificcounter class error status description for RTR_STS_INVOBJFAILCNSTR is:

The object is invalid because the values passed in the constructor were invalid.

CounterVal

A counter value for a specified RTR counter.

Call this method to set value for a counter. Object should be declared before setting value.

RTRSignedCounter( rtr_const_countername_t pszCounterName ,
rtr_const_countergroupname_t pszCounterGroupName);

pszCounterName

A null-terminated string pointer to the name of an RTR counter.

A null-terminated string pointer to the name of an RTR counter group.

This method used to declare an RTRSignedCounter object. The constructor creates an instance of the RTRSignedCounter class. The application must call SetValue() to initialize the counter.

All counters are process-specific. All counter names must be unique within the entire process without regard to the group name. For example, it is invalid to have an RTRSignedCounter name "MyCounter" and another RTRStringCounter name "MyCounter."

To use a counter, perform the following steps:

1. Declare the names for counter name and group name.
2. Instantiate the counter using the counter name and group.
3. Set the counter value and test for success.
4. Increment the counter.
5. Get the incremented value.

rtr_status_t GetValue(char * pszCounterVal);

Interpret value for the success or failure of this call.

The more specificcounter class error status descriptions for RTR_STSCTRBADREF and RTR_STS_INVOBJFAILCNSTR are:

• RTR_STSCTRBADREF

• RTR_STS_INVOBJFAILCNSTR

pszCounterVal

A null-terminated string pointer to the name of an RTR counter.

Call this method to get a counter value. GetValue can be called only after setting a value (SetValue).

rtr_status_t SetValue(const char * pszCounterVal);

Interpret value for the success or failure of this call.

The more specificcounter class error status description for RTR_STS_INVOBJFAILCNSTR is:

The object is invalid because the values passed in the constructor were invalid.

pszCounterVal

A null-terminated string pointer to the value of an RTR counter.

Call this method to set a counter value.

RTRStringCounter(const char *pszCounterName ,
const char *pszCounterGroupName);

pszCounterName

A null-terminated string pointer to the name of an RTR counter.

A null-terminated string pointer to the name of an RTR counter group.

This method used to declare an RTRStringCounter object. The constructor creates an instance of the RTRStringCounter class. The application must call SetValue() to initialize the counter.

All counters are process-specific. All counter names must be unique within the entire process without regard to the group name. For example, it is invalid to have an RTRStringCounter name "MyCounter" and another RTRSignedCounter name "MyCounter."

RTRStringCounter *iIntCounter = new
RTRStringCounter("MyCounter2","GroupName",eCtrtype);

To use a counter, perform the following steps:

1. Declare the names for counter name and group name.
2. Instantiate the counter using the counter name and group.
3. Set the counter value and test for success.
4. Increment the counter.
5. Get the incremented value.

rtr_status_t Decrement();

Interpret value for the success or failure of this call.

The more specificcounter class error status descriptions for RTR_STSCTRBADREF and RTR_STS_INVOBJFAILCNSTR are:

• RTR_STSCTRBADREF

• RTR_STS_INVOBJFAILCNSTR

The object is invalid because the values passed in the constructor were invalid.

Call this method to decrement a numeric counter. Decrement method can be called only after setting value.

rtr_status_t GetValue(rtr_uns_32_t &CounterVal);

Interpret value for the success or failure of this call.

The more specific counter class error status descriptions for RTR_STSCTRBADREF and RTR_STS_INVOBJFAILCNSTR are:

• RTR_STSCTRBADREF

• RTR_STS_INVOBJFAILCNSTR

CounterVal

A counter value for a specified RTR counter.

Call this method to get a counter value. GetValue can be called only after setting value (SetValue).

rtr_status_t Increment();

Interpret value for the success or failure of this call.

The more specificcounter class error status descriptions for RTR_STSCTRBADREF and RTR_STS_INVOBJFAILCNSTR are:

• RTR_STSCTRBADREF

• RTR_STS_INVOBJFAILCNSTR

Call this method to increment a numeric counter. This method can be called only after setting value.

rtr_status_t SetValue( rtr_uns_32_t CounterVal );

Interpret value for the success or failure of this call.

The more specificcounter class error status description for RTR_STS_INVOBJFAILCNSTR is:

The object is invalid because the values passed in the constructor were invalid.

CounterVal

A counter value for a specified RTR counter.

Call this method to set value for a counter. Object should be declared before setting value.

RTRUnsignedCounter( rtr_const_countername_t pszCounterName ,
rtr_const_countergroupname_t pszCounterGroupName);

pszCounterName

A null-terminated string pointer to the name of an RTR counter.

A null-terminated string pointer to the name of an RTR counter group.

This method used to declare an RTRUnsignedCounter object. The constructor creates an instance of the RTRUnsignedCounter class. The application must call SetValue() to initialize the counter.

All counters are process-specific. All counter names must be unique within the entire process without regard to the group name. For example, it is invalid to have an RTRUnsignedCounter name "MyCounter" and another RTRStringCounter name "MyCounter."