# 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