The oncmsm utility

Use the oncmsm utility to start or shut down a Connection Manager, load a new configuration file into a Connection Manager to modify the Connection Manager's settings, or update the format of a configuration file.

Syntax

Figure 1: UNIX™ syntax diagram:

1  oncmsm
1 ?   -c  configuration_file?   -n  new_configuration_file
1 
2.1  -r 
2.1  -k 
1 connection_manager_name
Figure 2: Windows™ syntax diagram:

1  oncmsm
2.1   -i   -c  configuration_file
2.1 ?   -c  configuration_file   -n  new_configuration_file
2.1 
2.2.1  -r 
2.2.1  -k 
2.2.1  -u 
2.1 connection_manager_name
2.1  connection_manager_name
1 
Element Purpose Key considerations
-c Starts the Connection Manager or converts a configuration file to the current Connection Manager format.
connection_manager_name Specifies the name of a Connection Manager instance.
-i Installs the Connection Manager as a Windows service. This option is valid for Windows platforms only.
-k Shuts down a specific instance of the Connection Manager.
-n Specifies the name of a converted configuration file.
new_configuration_file The name of file that is output to the $INFORMIXDIR/etc directory as part of the format-conversion process.
configuration_file The name of the configuration file located in the $INFORMIXDIR/etc directory. If the configuration file is not specified, the Connection Manager attempts to load $INFORMIXDIR/etc/cmsm.cfg.
-r Reloads the Connection Manager settings without stopping and restarting the Connection Manager.
-u Uninstall the Connection Manager Windows service. This option is valid for Windows platforms only.

Usage

Run the oncmsm utility from the command line to initialize the Connection Manager. You can add, change, or delete Service Level Agreements (SLAs) while the Connection Manager is running and then reload the configuration file.

The Connection Manager configuration file in versions of HCL OneDB™ Client Software Development Kit (Client SDK) prior to version 3.70.xC3 are incompatible with the current version of the Connection Manager. You must convert configuration files from versions prior to 3.70.xC3. You must have read permission on the configuration file you want to convert and write permission on the configuration file you want to create.

UNIX Only: The following users can run the oncmsm utility:
  • User informix
  • User root, if the user has privileges to connect to the sysadmin database
  • A member of the DBSA group, if the user has privileges to connect to the sysadmin database
Windows Only: The following users can run the oncmsm utility:
  • A member of the Informix-Admin group
  • User administrator, if the user has privileges to connect to the sysadmin database
  • A member of the DBSA group, if the user has privileges to connect to the sysadmin database

You must install the oncmsm utility as a service before you can start it.

The oncmsm utility can be started two ways:
  • Run an oncmsm command.
  • Click Start > Control Panel > Administrative Tools > Services and then start oncmsm.

If you are using multiple Connection Managers, you can run onstat -g cmsm to display the names of Connection Manager instances.

Example 1: Starting a Connection Manager (UNIX)

For the following example the Connection Manager's configuration_file_1 exists in the $INFORMIXDIR/etc directory. To start the Connection Manager, run the following command on the computer that the Connection Manager is installed on:
oncmsm -c configuration_file_1
The Connection Manager starts.

Example 2: Starting a Connection Manager (Windows)

For the following example the Connection Manager's configuration_file_1 exists in the $INFORMIXDIR/etc directory. To start the Connection Manager, run the following commands on the computer that the Connection Manager is installed on:
oncmsm -i -c configuration_file_2
oncmsm connection_manager_2
The Connection Manager named connection_manager_2 starts.

Example 3: Stopping a Connection Manager

To stop the Connection Manager, run the following command on the computer that the Connection Manager is installed on:
oncmsm -k connection_manager_3
The Connection Manager named connection_manager_3 stops.

Example 4: Reloading Connection Manager settings

For the following example, $INFORMIXDIR\etc\configuration_file_4 for a Connection Manager named connection_manager_4 has changed. To update the Connection Manager's settings, run the following command on the computer that connection_manager_4 is installed on:
oncmsm -r connection_manager_4

Example 5: Converting a Connection Manager configuration file to a current format

For the following example the Connection Manager's configuration file that is named cmsm.cfg exists in the $INFORMIXDIR/etc directory. To start the Connection Manager, run the following command on the computer that the Connection Manager is installed on:
oncmsm -n configuration_file_5
The oncmsm utility converts cmsm.cfg to the current configuration file format, and then outputs a file named configuration_file_5 into $INFORMIXDIR/etc/.

Example 6: Converting a specific Connection Manager configuration file to a current format

For the following example the Connection Manager's configuration file that is named configuration_file_4 exists in the $INFORMIXDIR/etc directory. To start the Connection Manager, run the following command on the computer that the Connection Manager is installed on:
oncmsm -c configuration_file_6 -n configuration_file_7
The oncmsm utility converts configuration_file_6 to the current configuration file format and then outputs a file named configuration_file_7 into $INFORMIXDIR/etc/.

Example 7: Uninstalling a Connection Manager (Windows)

For the following example, you have installed a Connection Manager named connection_manager_4 as a Windows service. To unistall the Connection Manager, run the following command on the computer that the Connection Manager is installed on:
oncmsm -u connection_manager_4
The oncmsm utility uninstalls the Connection Manager.