The onclean utility

Use the onclean utility to force a shut down of the database server when normal shut down with the onmode utility fails or when you cannot restart the server. The onclean utility attempts to clean up shared memory, semaphores, and stops database server virtual processes.

Syntax

On UNIX™ and Linux™, you must be user root or informix to run the onclean command. On Windows™, you must be in the Informix-Admin group to run the command.


1  onclean
1?  % -FILE
option  (1)
1 ?   -k?   -y
2.1  -V
2.1  -version
Notes:
Table 1. Syntax Elements of the onclean Command
Element Purpose
-k Shuts down a server that is online by stopping database server virtual processes and attempting to clean up the remaining semaphores and shared-memory segments, even if they are still running.
-V Displays short version information.
-version Displays full version information.
-y Does not prompt for confirmation.

Usage

Use the onclean utility to stop the database server only if the onmode utility is unable to shut it down or you cannot restart the server. Perhaps the database server shut down in an uncontrolled way and cannot recover, or it is hung. If the database server fails to restart, the previous instance of the database server is still attached to the shared-memory segments. Check the message log to see if the database server shut down abnormally. The onclean utility stops all oninit processes and attempts to remove all shared-memory segments and semaphores that are recorded in the $INFORMIXDIR/etc/.conf.$INFORMIXSERVER file.

Attention: Use the onclean utility with caution. When you run onclean, any pending transactions and processes fail to complete, and user sessions are disconnected abruptly. However, the database server rolls back transactions when it restarts.

The INFORMIXDIR, INFORMIXSERVER, INFORMIXSQLHOSTS, and ONCONFIG environment variables must be set with valid values to run this utility.

The onclean command that you use depends on the situation:

  • If you are not sure whether the database server is offline, use the onclean command without options. If the database server is still online, a message appears directing you to run the onclean -k command.
  • If the database server is offline, use the onclean command.
  • If the database server is online and you are sure that you want to force it to shut down, use the onclean -k command.

You can use the onclean utility only to shut down the local database server; you cannot use it to shut down a remote database server. The onclean utility should not be used to shut down an entire high-availability cluster or a remote database server.

The onclean utility might not be able to clean up shared memory segments that were in use by the database server in every situation. The onclean utility attempts to terminate only oninit processes. The onclean utility does not succeed in the following situations:

  • If a non-database server process is attached to the shared memory segment before running the onclean command, the onclean utility does not stop this process to remove the shared memory segment.
  • The onclean might not be able to guarantee a clean server startup is when an application or database server utility is connected to a network port. If the user tries to initialize a database server instance on the same network port, then the database server cannot start the listener thread and fails to start. The onclean utility does not stop the application to free the network port.

You can automate shutting down the database server with the onshutdown script, which calls the onclean -ky command if necessary.

Return Codes

0
Successful
1
Failure because of one of the following problems:
  • Incorrect environment variable settings
  • Incorrect privileges to run the onclean command
  • Incorrect command syntax
  • Corrupted information
  • Running the onclean command without the -k option on a server that is still online
2
Failure because one or more OS system calls used by onclean returned an error.