Starting and Stopping the BRM System

1 Starting and Stopping the BRM System

Learn how to start and stop your Oracle Communications Billing and Revenue Management (BRM) system.

Topics in this document:

About Starting and Stopping BRM Components

You start and stop BRM components by using the pin_ctl utility. You can start and stop individual components, or start and stop multiple components in a specified order.

You can start BRM components as user root, user pin, or any other name you choose. If you start both the BRM database and the BRM components with a user name other than root, you have better control over security and administrators that do not have superuser permissions.

Note:

If you use a port number less than 1000 for a component (1023 for the cm_proxy component), you must start that component as the user root. If you use a port number greater than 1024, you do not have to start the component as the user root.

Order of Starting and Stopping Components

You must start and stop BRM components in a specific order. Start the database first and start client applications last. You stop BRM components in the opposite order.

To start multiple components:

Start the BRM database. The BRM database usually starts automatically when the computer is started.
Start the Data Manager (DM) (dm_oracle).

Note:

In multischema systems, you must start all secondary DMs before you start the primary DM.
Start any other DMs, such as dm_fusa and dm_vertex.
Start the daemon or process for any optional features such as tMailer and Popper.
Start the Connection Manager Master Processes (CMMPs) if your system uses them.
Start CM Proxy if your system uses it.
Start the CMs.
Start BRM clients and other programs, such as service integration components.

Components Monitored and Controlled by the pin_ctl Utility

You can use the pin_ctl utility to start and stop the following BRM components:

Connection Manager
CM Master Process (CMMP)
Connection Manager Proxy (cm_proxy)
Data Managers:
- Oracle Data Manager
- Email Data Manager
- EAI Data Manager
- Paymentech Data Manager
- Invoice Data Manager
EAI Java Server
Invoice Formatter
Paymentech Answer Simulator
Batch Controller

You can configure the pin_ctrl utility to start and stop other components. See "Starting and Stopping Optional Components by Using pin_ctl".

Running the pin_ctl Utility

To start a BRM component by using the pin_ctl utility:

Go to the BRM_home/bin directory.
Run the pin_ctl utility with the start action:
```
pin_ctl start component
```
where component is the component you want to start. For example, to start the Oracle DM:
```
pin_ctl start dm_oracle
```

For a list of component names, see "Parameters for Components". To use the pin_ctl utility to start and stop a component that is not included by default, see "pin_ctl".

You have the following options for running the pin_ctl utility:

Get the status of a component:
```
pin_ctl status component
```
Start a component and clear its log files at the same time:
```
pin_ctl cstart component
```
Clear the log files for a component:
```
pin_ctl clear component
```
Get get diagnostic data when starting a component, or getting the status:
```
pin_ctl status -collectdata component
```
Halt a component by running the kill -9 command:
```
pin_ctl halt component
```
Halt and restart a component:
```
pin_ctl restart component
```
Stop a component:
```
pin_ctl stop component
```

Setting Up and Configuring the pin_ctl Utility

Install the pin_ctl utility executable on any system that runs a BRM component.

Each instance of the pin_ctl utility is configured by a pin_ctl.conf file that contains data about the BRM components running on the system.

To run the pin_ctl utility, set the PERL5LIB environment variable to point to the third-party application's install directory. To do so, perform one of the following:

Add the following paths to the PERL5LIB environment variable for the root account on each managed node:
- BRM_home/ThirdPartyApps/tools/PerlLib
- BRM_home/bin
Before you deploy the call_pin_ctl script in BRM_SPI_install_directory/bin, add the following paths to the PERL5LIB variable in the script:
- BRM_home/ThirdPartyApps/tools/PerlLib
- BRM_home/bin

You can configure the pin_ctrl utility as follows:

Customizing the List of Components to Start or Stop

You can customize the components that are included in the pin_ctl utility all component.

Open the pin_ctl.conf file in BRM_home/bin.

Find the following lines in the file:

# List of services to be part of all [Optional].
# Mention the service names separated by a space.
# '=' should be used to create an alias for 'all'.
# For example, all=my_all
# all=my_all dm_oracle dm_email cm cmmp formatter

all dm_oracle dm_email cm cmmp formatter

After all, enter each component that you want to start with the all command:
```
all component1 component2 component3 ...
```
where componentX is the component you want to add. For a list of valid component values, see "pin_ctl".

Note:

Make sure the components are in the order in which you want them started. The order is reversed when the components are stopped.
Save and close the file.

Starting and Stopping Optional Components by Using pin_ctl

The default pin_ctl.conf file is configured to start BRM system components only. To configure pin_ctl.conf to start an optional component, such as the Synchronization Queue DM (dm_aq):

Open the pin_ctl.conf file in BRM_home/bin.
Add the following line to the components list:
```
start_sequence service_name [=alias_name|:java|:app|->dependent_service]
```
where:
- start_sequence is the start and stop sequence number. This determines the order in which components are started or stopped.
- service_name is the name of the optional component.
- =alias name indicates that service_name is different from the standard service name. For example:
  
  cm_1=cm
  
  cm_2=cm
  
  where cm_1 and cm_2 are cm services.
- :java indicates that the component is Java-based.
- :app indicates that the component executable is located in the BRM_home/apps directory.
- ->dependent_service specifies one or more components that service_name is dependent on. This indicates that dependent_service must start before service_name is started.
For example, to add dm_aq to the components list:
```
4 dm_aq
```
Add the following line to the startup configuration section of the file:
```
start_component cpidproc:searchpattern:pidvarname cport:port_number [testnap:directory_name]
```
where:
- start_component is the name of the start command for the optional component, such as start_dm_aq. It must be unique; if not, the last parsed definition is used.
- cpidproc:searchpattern is a simple process name matching filter.
- pidvarname is a partial match for the pidfile variable from ${program_name}. If you enter nothing (which is recommended), the default is PID$, which matches CMPID in $PIN_LOG/cm/cm.pid.
- cport:port_number is the component port number.
- testnap:directory_name runs the testnap utility in the specified directory. The directory is relative to BRM_home/sys.
For example, to enter a startup configuration for dm_aq:
```
start_dm_aq cpidproc:dm_aq: cport:--DM_AQ_PORT__ 
```
Save and close the file.

Creating a Custom Component List

You can create aliases for custom lists of components that are controlled by the pin_ctl utility all component. For example, if you define an alias named my_all, you can start a custom group of components by running the following command:

pin_ctl start my_all

Open the pin_ctl.conf file in BRM_home/bin.

Find the following lines in the file:

# List of services to be part of all [Optional].
#       Mention the service names separated by a space.
# '='   should be used to create an alias for 'all'.
#       For example, all=my_all
# all=my_all dm_oracle dm_email cm cmmp formatter

all dm_oracle dm_email cm cmmp formatter

Add the following line at the end of the section:
```
all=alias component1 component2 ...
```
where:
- alias specifies the name of your customized all command. For example, my_all.
- componentX is the component you want to add. For a list of valid component values, see "pin_ctl".
  
  Note:
  
  Make sure the components are in the order in which you want them started. The order is reversed when the components are stopped by using the custom all command. Use a space to separate component names.
Save and close the file.

Customizing the Components List

The components list in the pin_ctl.conf file lists the BRM system components. For example:

1 dm_oracle
1 dm_email
1 dm_fusa
1 dm_invoice
...

If you have a high-availability system that includes duplicate instances of components, you can edit the pin_ctl.conf file to customize the components list. For example:

1 dmo1=dm_oracle
1 dmo2=dm_oracle
1 dm_eai_1=dm_eai
1 dm_eai_2=dm_eai
2 cm_1=cm->dm_oracle
2 cm_2=cm->dm_oracle
3 cm_proxy_1=cm_proxy
3 cm_proxy_2=cm_proxy
3 cmmp_1=cmmp
3 cmmp_2=cmmp

To customize the component list:

Open the pin_ctl.conf file in BRM_home/bin.

Find the following lines in the file:

# The format of entry for each service is ,
# start_sequence service_name [=<alias_name>|:java|:app|-><list of services depends on>]
# The start sequence is a mandatory field, which gives sequence to start/stop [Mandatory].
# Sequence is a numerical value, and starts from 1. The service should be specified
# in the assending order based on the sequence number.
# Mention the service name. This service_name is mandatory field [Mandatory].
# NOTE: Start sequence and Service name should be separated by a space.
# '='   should be used if service name is different with standard service names [Optional].
# For example, cm2=cm
# Here, cm2 is the service which is of cm category.
# This is useful when multiple CMs/DMs are installed.
# :app  should be used if its located in BRM_home/apps directory [Optional].
# :java should be used if its a java based service [optional].
# ->    should be used if the current service has any dependencies [Optional].
# This is generally useful in WINDOWS.

Add the following line for each component in your system:
```
start_sequence service_name [=alias_name|:java|:app|->dependent_service]
```
where:
- start_sequence is the start/stop sequence number.
- service_name is the component name.
- =alias name indicates that service_name is different from the standard service name. For example:
  
  cm_1=cm
  
  cm_2=cm
  
  where cm_1 and cm_2 are cm services.
- :java indicates that the component is Java-based.
- :app indicates that the component executable is located in the BRM_home/apps directory.
- ->dependent_service specifies one or more components that service_name is dependent on. This indicates that dependent_service must start before service_name is started.
Save and close the file.

Customizing the pin_ctl Startup Configuration

The pin_ctl.conf file includes startup configurations for system components. For example:

start_cm          cpidproc:cm:         cport:2224     testnap:test

These configurations are created automatically during installation, but you can change them. For example, if you use a high-availability system with duplicate processes, you should change the component names. In the following example, the Oracle DM name in the component list is dmo1, so the startup configuration has been changed to match:

start_dmo1   cpidproc:dmo1:  cport:12432

Open the pin_ctl.conf file in BRM_home/bin.
Edit the file.

The syntax is as follows:
```
start_component cpidproc:searchpattern:pidvarname cport:port_number [testnap:directory_name]
```
where:
- start_component is the name of the start command. It must be unique; if not, the last parsed definition is used.
- cpidproc:searchpattern is a simple process name matching filter.
- pidvarname is a partial match for the pidfile variable from ${program_name}. If you enter nothing (which is recommended), the default is PID$, which matches CMPID in $PIN_LOG/cm/cm.pid.
- cport:port_number is the component port number. This value is entered automatically during installation.
- testnap:directory_name runs the testnap utility in the specified directory. The directory is relative to BRM_home/sys.
Save and close the file.

Customizing the pin_ctl Utility Environment Variables

Some BRM components need environment variables set before starting. You can edit the pin_ctl.conf file to change the environment variables if yours are different from the default settings.

Open the pin_ctl.conf file in BRM_home/bin.

To define environment variables for BRM components, find the following lines in the file:

# List of all environment variables which needs to be set
# or override during the execution a particular process
# The syntax for setting or overriding the environment variable will be,
# program_name env_platform:OS env_variable:ENV_VAR    env_val:ENV_VAL

#common env_platform:solaris env_variable:EXAMPLE env_val:example

Add the following line for each BRM component that requires an environment variable:
```
component env_platform:operating_system env_variable:environment_variable env_val:value
```
where:
- component is the BRM component that uses the environment variable (for example, cm). Use common to apply the environment variable to the entire system.
  
  For a list of component values, see "Parameters for Components".
- operating_system can be linux, solaris, or common.
- environment_variable specifies the name of the environment variable to set before starting component.
- value specifies the environment variable value.
For example, the following line sets the NLS_LANG environment variable before starting any BRM component:
```
common env_platform:common env_variable:NLS_LANG env_val:AMERICAN_AMERICA.AL32UTF8
```
Save and close the file.

Configuring the Start and Stop Validation Settings for pin_ctl

You can configure the validations pin_ctl performs when starting and stopping components, including the following:

How long the utility waits before checking whether an action is complete.
The maximum number of times the utility checks whether an action is complete.
The home directory for the specified component. This overrides the BRM_home value.
The home log directory for the specified component. This overrides the $PIN_LOG value for the specified component.

To specify the validation settings used when pin_ctl starts and stops components:

Open the pin_ctl.conf file in BRM_home/bin.

Find the following lines in the file:

# This sections will be used to have different settings for each service like
# 1. waittime -- number of seconds to be waited
# 2. iterations -- Number of times to be checked
# 3. pin_home_dir -- BRM_home path
# 4. pin_log_dir -- BRM_home/var/component path
# All these are optional, if these are not set then default values will be used.

Add the following line for each component that you want to override the default values:
```
settings component waittime:wait iterations:value pin_home_dir:path pin_log_dir:log_file_path
```
where:
- component is the BRM component. For a list of valid values, see "Parameters for Components".
- wait is the number of seconds to wait before checking whether an action is complete. The default is 5.
- value is the maximum number of times to check whether an action is complete. The default is 5.
- path is the home directory. This overrides the BRM_home value.
- logpath is the BRM log file home. The default is the value set in the $PIN_LOG environment variable. You must change this only if you use a different directory than the default directory.
For example:
```
settings dm_oracle waittime:5 iterations:5 pin_home_dir:BRM_home pin_log_dir:$PIN_LOG
```
Save and close the file.

Using Custom pin_ctl Configuration Files

You can create custom pin_ctl configuration files to run different configurations of the same system.

Create a custom configuration file in BRM_home/bin. You can copy and rename the pin_ctl.conf file.
Use the -c file_name parameter when you run the pin_ctl utility. For example:
```
pin_ctl cstart all -c pin_ctl_batch.conf 
```

Starting BRM Components Automatically

You can configure BRM components to start automatically when you restart a system by adding component start scripts to the operating system startup scripts, such as the /etc/rc2 script. You can also start components automatically from cron jobs.

Note:

When you set up the BRM system to start automatically, ensure the database starts before any Data Manager that connects to the database. If the DM starts first, it reports an error when it cannot find the database. For more information on component start sequences, see "Order of Starting and Stopping Components".

To add a component to the startup script:

As user root, run the installation script for the component (for example, install_dm_fusa or install_cm).

These scripts are in BRM_home/bin.
(Optional) To avoid problems with file security and permissions, set all component processes to start as user pin (or another name you choose) rather than as user root; add the following line to the initialization file for the operating system, before the lines that start the components:
```
su - pin 
```

Starting Multiple Families of BRM Components on the Same Computer

Each BRM component can be part of a family of components. Each family includes a parent process and one or more child processes. When you start the parent process, BRM starts child processes automatically.

You can run multiple families of a BRM process on the same computer. For example, you can start another instance of the Paymentech DM on a computer that is already running the Paymentech DM.

To run multiple families, put each family in a separate directory with its own configuration file (pin.conf or Infranet.properties). Each family's configuration file must point to a unique port to avoid conflicts when you start the processes. Each configuration file should point to a unique pinlog file as well.

For information on configuring the port and on the location of the log file for a process, see the explanatory text in the configuration file for that process.

Confirming That a BRM Component Started Successfully

To verify that a component started successfully, perform one or more of these checks:

For supported components, use the pin_ctl utility with the status action. See "pin_ctl".
Look for the startup timestamp in the .log file. For more information on BRM log files, see "Using Logs to Monitor Components".
Confirm that the pid file for the component contains the process ID (PID).

pid files are generated in BRM_home/var/component (for example, BRM_home/var/dm_oracle).
Use the ps command to check the component process status.
(Solaris and Linux) You can confirm that a shared memory segment has been allocated for the component process by using the ipcs command.

Note:

The ipcs command does not show the shared memory segment unless you run it as root or pin or you use the -m parameter.

Stopping a Process by Using Commands

In addition to using the pin_ctl utility halt command, you can stop a component with a direct command. Use ps to get the process ID (PID) of the process, and then use the kill command to stop the process.

Note:

Stopping the CM parent also stops the CM children. If you kill a child CM, a new opcode call starts a new child CM. This is because the parent CM is still active, and can automatically start a child CM when you run an opcode.

In rare cases, you might be left with an allocated but unused shared memory block. Use the ipcs command to detect an allocated block; use the ipcrm command to remove it.