Abstract
In this series of articles we are exploring some of the lesser known, but still useful, commands hidden away in your Informix bin directory. The article explores the onclean utility.
It’s often necessary to run more than one database instance on a single server. While this is a useful feature and quite easy to do with IDS, when things go wrong, it’s not always straightforward to tie each oninit binary back to a particular instance, and killing the wrong binary or shared memory segment can be disastrous.
Since IDS 11, the onclean utility has been bundled with the server; this useful little program can help take some of the pain out of cleaning up an instance that has not shut down properly, killing only the relevant server processes, and dropping any attached shared memory segments.
Content
If onmode is not successfully shutting down your instance, or if Informix won’t start and is reporting shared memory issues, onclean may well be able to help. This command should really only be used if onmode is failing to shut IDS down properly though. The command needs to be run as user informix or root, and can have more success at removing shared memory segments than running ipcrm as informix (if you don’t have root access); this is because the program runs with setuid.
Firstly, make sure that INFORMIXDIR, INFORMIXSERVER, and ONCONFIG are set correctly for the instance you need to clean up. The command can be run interactively with just ‘onclean’, but the usual way to run it, if you’re absolutely sure the environment is set correctly for the instance you want to bring down, is as follows:
Copy to Clipboard
The –k means stop all virtual processors (for the current instance)
The –y will prevent the program for asking for confirmation
onclean will attempt to clear any remaining shared memory segments and semaphores, as well as killing the virtual processors (oninit binaries) which should prevent any shared memory issues when restarting the instance. Please bear in mind that this will bring the database server down pretty abruptly, and not allow for any transactions to complete (these should be rolled back during fast recovery on restarting).
Should the command fail, it will return the error code 2 to the operating system if any system calls have failed, and 1 for anything else (such as incorrect syntax or environment).
Conclusion
Used with care, the onclean command can provide an easy to use alternative to the risky process of tracing back binaries and shared memory segments to a particular instance, especially where multiple instances are concerned. The command does bring down the instance immediately though, and should only be used as a last resort when the usual onmode command does not work as expected.
Disclaimer
The code fix suggested above is provided “as is” without warranty of any kind, either express or implied, including without limitation any implied warranties of condition, uninterrupted use, merchantability, fitness for a particular purpose, or non-infringement.
Contact us
If you have any questions regarding onclean or would like to find out more, simply contact us.
