hp Reliable Transaction Router
C++ Foundation Classes
Previous Contents Index

4.3 RTRFacilityManager

The RTRFacilityManager classes enable the creation of facilities specifying roles for frontend, router, and backend. Facilities can be extended by adding roles, trimmed by removing roles, deleted or interrogated for their properties.

RTRFacilityManager Class Members

Construction
Method Description
RTRFacilityManager Constructor
~RTRFacilityManager() Destructor

Operations
Method Description
AddBackend(rtr_const_facnam_t, rtr_const_nodnam_t) Add a backend role to an existing facility.
AddFrontend(rtr_const_facnam_t, rtr_const_nodnam_t) Add a frontend role to an existing facility.
AddRouter(rtr_const_facnam_t, rtr_const_nodnam_t) Add a router role to an existing facility.
CreateFacility(rtr_const_facnam_t, rtr_const_nodnam_t, rtr_const_nodnam_t, bool) Create a facility, designating router and frontend.
CreateFacility(rtr_const_facnam_t, rtr_const_nodnam_t, rtr_const_nodnam_t, bool, bool) Create a facility, designating router and backend.
CreateFacility(rtr_const_facnam_t, rtr_const_nodnam_t, rtr_const_nodnam_t, rtr_const_nodnam_t, bool, bool) Create a facility, designating router, frontend, and backend.
DeleteFacility(rtr_const_facnam_t) Delete a facility.
GetFacilityProperties(rtr_const_facnam_t, RTRFacilityProperties) Retrieve properties for an existing facility.
RemoveBackend(rtr_const_facnam_t, rtr_const_nodnam_t) Remove a backend role from an existing facility.
RemoveFrontend(rtr_const_facnam_t, rtr_const_nodnam_t) Remove a frontend role from an existing facility.
RemoveRouter(rtr_const_facnam_t, rtr_const_nodnam_t) Remove a router role from an existing facility.

AddBackend()

RTRFacilityManager::AddBackend();

Prototype


rtr_status_t AddBackend( rtr_const_facnam_t pszFacilityName, 
                                          rtr_const_nodnam_t pszBackend );

Return Value

rtr_status_t Interpret value for the success or failure of this call.
Status Message
RTR_STS_ENOIPNAM Entered node name does not exist.
RTR_STS_INVBCKENDNAMARG The backend name argument is invalid.
RTR_STS_INVFACNAMEARG The facility name argument is invalid.
RTR_STS_NOSUCHFAC No such facility.
RTR_STS_OK Normal successful completion.
RTR_STS_RTRNOTSTA RTR not started.

Parameters

pszFacilityName

A null-terminated pointer to a facility name.

pszBackend

A pointer to a null-terminated string containing the nodename to add as a backend (BE).

Description

Call this method to extend a backend to a facility. Facility name and backend node names should not be null values. A node does not have to be reachable but must be valid or RTR returns RTR_STS_ENOIPNAM.

The Backend parameter can be a comma-separated list of nodenames.

Example


// Add a Backend 
rtr_status_t stsAddBackend; 
 
stsAddBackend = pFacilityManager->AddBackend("AddBackend", 
                                      m_psTest_ExtraNodeName); 
if ( IsFailure( stsAddBackend == RTR_STS_OK ) ) 
{ 
bOverallResult = false; 
OutputStatus( stsAddBackend ); 
}

AddFrontend()

RTRFacilityManager::AddFrontend();

Prototype


rtr_status_t AddFrontend( rtr_const_facnam_t pszFacilityName, 
                                          rtr_const_nodnam_t pszFrontend );

Return Value

rtr_status_t Interpret value for the success or failure of this call.
Status Message
RTR_STS_ENOIPNAM Entered node name does not exist.
RTR_STS_INVFACNAMEARG The facility name argument is invalid.
RTR_STS_INVFRNTENDNMARG The frontend name argument is invalid.
RTR_STS_NOROUTERS No routers.
RTR_STS_NOSUCHFAC No such facility.
RTR_STS_OK Normal successful completion.
RTR_STS_RTRNOTSTA RTR not started.

Parameters

pszFacilityName

A null-terminated pointer to a facility name.

pszFrontend

A pointer to a null-terminated string containing the nodename to add as a frontend (FE).

Description

Call this method to extend a frontend node for a facility. Facility names and node names should not be null values.

The Frontend parameter can be a comma-separated list of nodenames.

Example


char *pszFacilityName = "Myfacility"; 
char *pszNodeName = "FENodeNamesSeparatedbyComma"; 
sStatus = myFac-> AddFrontend (pszFacilityName,l_ pszNodeName);

AddRouter()

RTRFacilityManager::AddRouter();

Prototype


rtr_status_t AddRouter( rtr_const_facnam_t pszFacilityName, 
                                      rtr_const_nodnam_t pszRouter );

Return Value

rtr_status_t Interpret value for the success or failure of this call.
Status Message
RTR_STS_FACEXTENDED Router added successfully.
RTR_STS_INVFACNAMEARG The facility name argument is invalid.
RTR_STS_INVROUTRNAMEARG The router name argument is invalid.
RTR_STS_NOFRONTEN No frontends specified.
RTR_STS_NOSUCHFAC No such facility.
RTR_STS_OK Normal successful completion.
RTR_STS_RTRNOTSTA RTR not started.

Parameters

pszFacilityName

A null-terminated pointer to a facility name.

pszRouter

A null-terminated pointer to a facility member with a router (TR) role.

Description

Call this method to extend a router for a facility. Facility name and node names should not be null values.

Example


char *pszFacilityName = "Myfacility"; 
char *pszNodeName = "FENodeNamesSeparatedbyComma"; 
sStatus = myFac-> AddRouter (pszFacilityName,l_ pszNodeName);

CreateFacility()

RTRFacilityManager::CreateFacility();

Prototype


rtr_status_t CreateFacility( rtr_const_facnam_t pszFacilityName, 
                                           rtr_const_nodnam_t pszRouter, 
                                           rtr_const_nodnam_t pszFrontend, 
                                           bool bEnableRouterCallout); 
 
rtr_status_t CreateFacility(  rtr_const_facnam_t pszFacilityName, 
                                            rtr_const_nodnam_t pszRouter, 
                                            rtr_const_nodnam_t pszBackend, 
                                            bool bEnableRouterCallout, 
                                            bool bEnableBackendCallout ); 



rtr_status_t CreateFacility( rtr_const_facnam_t pszFacilityName, 
                                           rtr_const_nodnam_t pszRouter, 
                                           rtr_const_nodnam_t pszFrontend, 
                                           rtr_const_nodnam_t pszBackend, 
                                           bool bEnableRouterCallout, 
                                           bool bEnableBackendCallout);

Return Value

rtr_status_t Interpret value for the success or failure of this call.
Status Message
RTR_STS_DUPNODNAM Duplicate node names in list.
RTR_STS_INVBCKENDNAMARG The backend name argument is invalid.
RTR_STS_INVFACNAMEARG The facility name argument is invalid.
RTR_STS_INVFRNTENDNMARG The frontend name argument is invalid.
RTR_STS_INVROUTRNAMEARG The router name argument is invalid.
RTR_STS_OWNNODMIS Executing node is not specified as frontend, router, or backend.
RTR_STS_NOBACKEND No backend specified in facility.
RTR_STS_NOFRONTEN No frontend specified in facility.
RTR_STS_NOROUTERS No routers specified in facility.
RTR_STS_OK Normal successful completion.
RTR_STS_OWNNODMIS Executing node is not specified as Frontend ,router or backend.
RTR_STS_JOUNOTFOU Journal file not found.

Parameters

pszFacilityName

A null-terminated pointer to a facility name.

pszRouter

A null-terminated pointer to a facility member with a router (TR) role.

pszFrontend

A null-terminated pointer to a facility member with a frontend (FE) role.

pszBackend

A null-terminated pointer to a facility member with a backend (BE) role.

bEnableRouterCallout

A boolean attribute for specifying a callout router.

bEnableBackendCallout

A boolean attribute for specifying a callout backend.

Description

Call this method to create a facility. There are three versions of the CreateFacility method. One version designates router, frontend, and backend nodes. One version designates router and frontend nodes. One version designates router and backend nodes. For these last two versions, the CreateFacility method requires the router name to be non-local.

For example, the following two calls would succeed: 


stsCreateFacility 
pFacilityManager->CreateFacility("FacilityWithoutBackend", 
                                 "router_nonlocal_nodename", 
                                 "frontend_local_nodename", 
                                  true); 
stsCreateFacility 
pFacilityManager->CreateFacility("FacilityWithoutFrontend", 
                                 "router_nonlocal_nodename", 
                                 "backend_local_nodename", 
                                  true);

These two calls would return the RTR_STS_xxx errors indicated: 


stsCreateFacility 
pFacilityManager->CreateFacility("FacilityWithoutBackend", 
                                 "router_local_nodename", 
                                 "frontend_local_nodename", 
                                  true); 
NOBACKEND 
No backends specified

Explanation: No backends were specified on a CREATE FACILITY command and the node where the command was executed was specified as being a router. This error message is displayed by the RTR utility. 


stsCreateFacility 
pFacilityManager->CreateFacility("FacilityWithoutFrontend", 
                                 "router_local_nodename", 
                                 "backend_local_nodename", 
                                  true); 
NOFRONTEN 
No frontends specified

Explanation: No frontends were specified on a CREATE FACILITY command and the node where the command was executed was specified as being a router. This error message is displayed by the RTR utility.

Example


    RTRFacilityManager::CreateFacilityWithAllRoles_3() 
    { 
    bool bOverallResult = true; 
    //Create facility manager, abort if fails 
        RTRFacilityManager * pFacilityManager; 
        pFacilityManager = new RTRFacilityManager; 
    if ( IsFailure(pFacilityManager != NULL) ) 
        { 
    return false; 
        } 
    // Create the facility 
        rtr_status_t stsCreateFacility; 
    stsCreateFacility = 
        pFacilityManager->CreateFacility("FacilityWithAllRoles_3", 
                                          GetDefaultRouterName(), 
                                          GetDefaultFrontendName(), 
                                          GetDefaultBackendName(), 
                                          true, 
                                          false); 
        // If facility creation is not successful, report it 
        if ( IsFailure( stsCreateFacility == RTR_STS_OK ) ) 
    { 
    bOverallResult = false; 
    OutputStatus( stsCreateFacility ); 
    } 
        else // Delete a successfully created facility 
        { 
        rtr_status_t stsDeleteFacility; 
    stsDeleteFacility = 
            pFacilityManager->DeleteFacility("FacilityWithAllRoles_3"); 
        if ( IsFailure( stsDeleteFacility == RTR_STS_OK ) ) 
        { 
        bOverallResult = false; 
        OutputStatus( stsDeleteFacility ); 
        } 
        } 
    // Cleanup and return 
        delete pFacilityManager; 
    return bOverallResult; 
    }

An example from the Sample application in the Examples directory: 


    inline rtr_status_t CreateFacility() 
    { 
    // Create a Facility 
        rtr_status_t sStatus; 
        RTRFacilityManager FacilityManager; 
    // Get the local node name to create the facility. 
        char nodename[ABCMAX_STRING_LEN]; 
        gethostname(&nodename[0],ABCMAX_STRING_LEN); 
    // Create the facility specifying that the local node has all roles. 
        sStatus = 
    FacilityManager.CreateFacility(ABCFacility,nodename,nodename, 
                                   nodename,true,false); 
    print_status_on_failure(sStatus); 
    return sStatus; 
    }

For more information on creating a facility, see the RTR System Manager's Manual .

DeleteFacility()

RTRFacilityManager::DeleteFacility();

Prototype


rtr_status_t DeleteFacility( rtr_const_facnam_t pszFacilityName );

Return Value

rtr_status_t Interpret value for the success or failure of this call.
Status Message
RTR_STS_FACDELETE Facility deleted successfully
RTR_STS_INVFACNAMEARG The facility name argument is invalid.
RTR_STS_NOSUCHFAC No such facility available
RTR_STS_OK Normal successful completion
RTR_STS_RTRNOTSTA RTR not started

Parameters

pszFacilityName

A null-terminated pointer to a facility name.

Description

Call this method to delete a facility. This does not clean out the journal; transactions that are to be processed stay in the journal. However, the facility must be recreated before you can process the transactions stored in the journal.

For more information on creating a facility, see the RTR System Manager's Manual .

Example


 rtr_status_t sStatus; 
 char *pszFacilityName = "Myfacility"; 
 sStatus = myFac->DeleteFacility(pszFacilityName);

GetFacilityProperties()

RTRFacilityManager::GetFacilityProperties();

Prototype


rtr_status_t GetFacilityProperties( rtr_const_facnam_t pszFacilityName, 
                                    RTRFacilityProperties *&pFacProp);

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_INVFACPROPPTARG Invalid facility properties object pointer argument.
RTR_STS_INVSTRINGPTRARG The string pointer argument is invalid - string too long.
RTR_STS_OK Normal successful completion

Parameters

pszFacilityName

A null-terminated pointer to a facility name.

pFacProp

Pointer to properties for a given facility.

Description

Retrieve properties for an existing facility. Caller must delete pFacProp later.

Example


    // Create a FacilityProperties object to get the properties from. 
    RTRFacilityProperties *pFacilityProperties = 
                    new RTRFacilityProperties("GetFacilityProperties"); 
    if ( IsFailure(pFacilityProperties != NULL) ) 
      { 
        //Can't continue, so cleanup and return 
        delete pFacilityManager; 
        return false; 
    } 
    rtr_status_t stsGetFacilityProperties; 
    stsGetFacilityProperties = 
        pFacilityManager->GetFacilityProperties("GetFacilityProperties", 
                                                pFacilityProperties); 
    if ( IsFailure( stsGetFacilityProperties == RTR_STS_OK ) ) 
      { 
        bOverallResult = false; 
        OutputStatus( stsGetFacilityProperties ); 
    }

Previous Next Contents Index