Commands Reference, Volume 5

topsvcsctrl Command

Purpose

Starts the topology services subsystem.

Syntax

topsvcsctrl { -a | -s | -k | -d | -c | -u | -t | -o | -r | -h }

Description

The topsvcsctrl control script controls the operation of the topology services subsystem. The subsystem is under the control of the system resource controller (SRC) and belongs to a subsystem group called topsvcs. This script is normally started by the HACMP/ES startup process.

An instance of the topology services subsystem runs on every node of a cluster.

From an operational point of view, the topology services subsystem group is organized as follows:

Subsystem: topology services
Subsystem group: topsvcs
SRC subsystem: topsvcs
The topsvcs subsystem is associated with the hatsd daemon and the topsvcs script. The topsvcs script configures and starts the hatsd daemon. The subsystem name on the nodes is topsvcs. There is one of each subsystem per node and it is associated with the cluster to which the node belongs.
Daemons: hatsd
Provides the topology services. The topsvcs script configures and starts the hatsd daemon.

The topsvcsctrl script is not normally executed from the command line. It is normally called by the HACMP/ES startup command.

The topsvcsctrl script provides a variety of controls for operating the topology services subsystems:

Adding, starting, stopping, and deleting the subsystems
Cleaning up the subsystems, that is, deleting them from all system partitions
Turning tracing on and off
Refreshing the subsystem

Before performing any of these functions, the script obtains the current cluster name (using the cllsclstr command) and the node number (using the clhandle command). If the node number is 0, the control script is running on the control workstation.

Except for the clean and unconfigure functions, all functions are performed within the scope of the current system partition.

Adding the subsystem: When the -a flag is specified, the control script uses the mkssys command to add the topology services subsystem to the SRC. The control script operates as follows:

It makes sure the topsvcs subsystem is stopped.
It removes the topsvcs subsystem from the SRC (in case it is still there).
It adds the topsvcs subsystem to the SRC.

Starting the subsystem: When the -s flag is specified, the control script uses the startsrc command to start the topology services subsystem, topsvcs.

Stopping the subsystem: When the -k flag is specified, the control script uses the stopsrc command to stop the topology services subsystem, topsvcs.

Deleting the subsystem: When the -d flag is specified, the control script uses the rmssys command to remove the topology services subsystem from the SRC. The control script operates as follows:

It makes sure that the topsvcs subsystem is stopped.
It removes the topsvcs subsystem from the SRC using the rmssys command.
It removes the port number from the /etc/services file.

Cleaning up the subsystems: When the -c flag is specified, the control script stops and removes the topology services subsystems for all clusters partitions from the SRC. The control script operates as follows:

It stops all instances of subsystems in the clusters, using the stopsrc -g topsvcs command.
It removes all entries for the topsvcs subsystem from the /etc/services file.

Turning tracing on: When the -t flag is specified, the control script turns tracing on for the hatsd daemon, using the traceson command.

Turning tracing off: When the -o flag is specified, the control script turns tracing off (returns it to its default level) for the hatsd daemon, using the tracesoff command.

Refreshing the subsystem: When the -r flag is specified, the control script refreshes the subsystem, using the topsvcs refresh command and the refresh command. It rebuilds the information about the node and adapter configuration in the global object data manager (ODM) and signals the daemon to read the rebuilt information.

Logging: While it is running, the topology services daemon (hatsd) provides information about its operation and errors by writing entries in a log file called /var/ha/log/topsvcs.cluster_name.

Flags

-a: Adds the subsystem.
-s: Starts the subsystem.
-k: Stops the subsystem.
-d: Deletes the subsystem.
-c: Cleans the subsystems.
-u: ?
-t: Turns tracing on for the subsystem.
-o: Turns tracing off for the subsystem.
-r: Refreshes the subsystem.
-h: Writes the script's usage statement to standard output.

Security

You must be running with an effective user ID of root to use this script.

Exit Status

0: Indicates that the script completed successfully.
1: Indicates that an error occurred.

Environment Variables

HB_SERVER_SOCKET: This environment variable should be set before this command can be executed. It must be set to the location of the UNIX-domain socket used by topology services clients to connect to the topology services daemon. This environment variable must be set to /var/ha/soc/hats/server_socket.partition name.
HA_SYSPAR_NAME: If HB_SERVER_SOCKET is not set, then HA_SYSPAR_NAME must be set to the partition name.

Restrictions

This command is valid in an HACMP environment only.

Use this command only under the direction of the IBM Support Center.

Standard Output

When the -h flag is specified, this command's usage statement is written to standard output. All verbose messages are written to standard output.

Standard Error

This script writes error messages (as necessary) to standard error.

Examples

To add the topology services subsystem to the SRC, enter:
```
topsvcsctrl -a
```
To start the topology services subsystem, enter:
```
topsvcsctrl -s
```
To stop the topology services subsystem, enter:
```
topsvcsctrl -k
```
To delete the topology services subsystem from the SRC, enter:
```
topsvcsctrl -d
```
To clean up the topology services subsystem, enter:
```
topsvcsctrl -c
```
To turn tracing on for the topology services daemon, enter:
```
topsvcsctrl -t
```
To turn tracing off for the topology services daemon, enter:
```
topsvcsctrl -o
```

Location

/usr/sbin/rsct/bin/topsvcsctrl: Contains the topsvcsctrl script

Files

/var/ha/log/topsvcs.cluster_name: Contains the log of the hatsd daemon on the cluster named cluster_name

Related Information

Commands: lssrc, startsrc, stopsrc

Scripts: topsvcs