The oninit utility

The oninit utility starts the database server.

On UNIX, Linux, and Mac OS X, you must be logged in as user root, user informix, or the non-root database server owner to run the oninit utility. User informix should be the only member of the group informix. Run the oninit command from the command line. You can allow users who belong to the DBSA group to run the oninit command. See Allow DBSA group users to run the oninit command (UNIX).

On Windows, HCL Informix® runs as a Windows service. Any user who has appropriate permissions to start a Windows service is able to start the HCL Informix service. The Services control application runs the oninit utility with any options that you supply.

Syntax

Read syntax diagramSkip visual syntax diagram
>>-oninit--+-------------------------+-------------------------->
           |                     (1) |   
           '-|  -FILE option   |-----'   

>--+-------------------------------------------+---------------><
   +-| Other options for starting the server |-+   
   +-| Initialize disk space |-----------------+   
   '- -PHY-------------------------------------'   

Other options for starting the server

|--+-+-----+--+--------------------------+-+--+-------------+--->
   | '- -j-'  |      .-600-------------. | |  +- -SDS=alias-+   
   |          '- -w--+-+-------------+-+-' |  '- -D---------'   
   |                   '-max_seconds-'     |                    
   '-+- -s-+-------------------------------'                    
     '- -S-'                                                    

>--+-----------------------+--+-----+--+-----+--+-----+---------|
   |        .-,--------.   |  '- -p-'  '- -y-'  '- -v-'   
   |        V          |   |                              
   '- -U--+---username-+-+-'                              
          '-" "----------'                                

Initialize disk space

|-- -i--+-----+--+-----+--+-----+------------------------------->
        +- -j-+  '- -y-'  '- -v-'   
        '- -s-'                     

>--+--------------------------+--+-----------------------+------|
   |      .-600-------------. |  |        .-,--------.   |   
   '- -w--+-+-------------+-+-'  |        V          |   |   
            '-max_seconds-'      '- -U--+---username-+-+-'   
                                        '-" "----------'     

Notes:
  1. See The -FILE option.
Table 1. oninit command elements
Element Purpose Key Considerations
-D Starts the database server with Enterprise Replication and high-availability cluster replication disabled.  
-i Initializes disk space for the root dbspace so that it can be used by the database server and starts the database server. Disk space needs to be initialized only once to prepare data storage for the server.

By default, to prevent data loss, you cannot reinitialize disk space. To reinitialize disk space for an existing root dbspace, you must set the FULL_DISK_INIT configuration parameter to 1 and then run the oninit -i command.

See Initialize disk space for the root dbspace.

-j Starts the server in administration mode. See Start the server in administration mode.
-p Starts the database server without deleting temporary tables. If you use this option, the database server starts more rapidly, but space used by temporary tables left on disk is not reclaimed.
-PHY Starts the server as of most current checkpoint. The -PHY option is used to tell the server to do only physical recovery without logical recovery. This option is normally used to start a secondary server. You must run one of the following commands to connect the secondary server to the primary server:
onmode -d secondary
onmode -d RSS
The connection of the secondary server to the primary server fails if the most recent checkpoint on the primary server was not performed on the secondary server.
-s Starts the server in quiescent mode. The database server must be shut down when you use this option.

When the database server is in quiescent mode, only the user informix can access the database server.

-S Starts database server in quiescent mode as a standard server with high-availability data replication disabled. When the database server is in quiescent mode, only the user informix can access the database server.
-SDS=alias For shared disk servers, starts the current server and specifies the primary server with the alias name. When both the primary server and all of the SDS servers are down, use the -SDS=alias option to start the designated SDS server as the primary server. The -SDS=alias flag cannot be combined with the -i flag.
-U username Specifies which users can access the server in administration mode for the current session. The informix user and members of the DBSA group are always administration mode users.

See Start the server in administration mode.

-v Displays verbose informational messages while the server is starting.  
-w max_seconds Starts the database server and waits to indicate success or failure until the server is completely started in online mode or the number of seconds specified by max_seconds elapses. The default number of seconds to wait is 600.

This option is not valid on secondary servers in a high-availability cluster.

See Start the server with a script.

-y Prevents verification prompts. The -y option automatically answers yes to all the verification prompts.

Usage

By default, the oninit utility shows verification prompts during server startup. You can suppress verification prompts by including the -y option. You can view verbose informational messages by including the -v option. On UNIX, Linux, and Mac OS X, oninit output is shown to standard output. On Windows, you can view oninit output by setting the ONINIT_STOUT environment variable to save the output to a file.

You can start the server in different operating modes. By default, if you run the oninit command without options, the server starts in online mode. When the database server is in online mode, all authorized users can access the server.

If you run an oninit -FILE command, you do not need to set local environment variables before you start the database server. The database server automatically uses the environment variables that are set as values in the onconfig file.

Start the server in administration mode

Administration mode is an administrator-only mode you can use to perform maintenance operations including those that require running SQL or DDL commands. When in administration mode, the database server only accepts connection requests from the following users:

  • The informix user
  • Members of the DBSA group
  • Users specified by the oninit -U command or the onmode -j -U command, for the current session. The -U option overrides any users listed by the ADMIN_MODE_USERS configuration parameter in the onconfig file.
  • Users specified by the ADMIN_MODE_USERS configuration parameter

Use the -U option with a list of comma-separated user names to add administration mode users, such as: Karin,Sarah,Andrew.

Use the -U " " option to remove all administration mode users except the informix user and members of the DBSA group: oninit -U " ".

Initialize disk space for the root dbspace

The first time you install HCL Informix on your system, disk space for the root dbspace for the database server needs to be initialized. The root dbspace is specified by the ROOTPATH configuration parameter.

If you performed a typical installation and chose to create a database server or you performed a customer installation, disk space was automatically initialized. Otherwise, you must initialize disk space by running the oninit -i command.

If the DISK_ENCRYPTION configuration parameter is set when you initialize the root dbspace, the root dbspace is encrypted.

If necessary, you can reinitialize disk space. Reinitializing disk space destroys all existing data managed by the database server. The database server must be offline when you reinitialize.

By default, you cannot reinitialize a root dbspace that is being used by the database server. Disk initialization fails if a page zero exists at the root path location (at the first page of the first chunk location). You can allow disk reinitialization of an existing root dbspace by setting the FULL_DISK_INIT configuration parameter to 1.

Start the server with a script

You can use the oninit -w command in customized startup scripts and to automate startup. The -w option forces the server to wait until startup is completely successfully before indicating that the server is in online mode by returning to the shell prompt with a return code of 0. If the server is not in online mode within the timeout period, the server returns a return code of 1 to the shell prompt and writes a warning message in the online log.

The default timeout is 600 seconds (10 minutes), which you can modify to any integer value.

After running the following command, if the server fails to start within 60 seconds, a code of 1 is returned to the prompt:

oninit -w 60

To determine the reason for the server failing to start, check the online log. You might need to increase the timeout value. When you use the oninit -w command in a script, you can check whether the server is online with the onstat - (Print output header) command.

Allow DBSA group users to run the oninit command (UNIX)

To allow users who belong to the DBSA group, other than the user informix, to run the oninit command, log in as the user root and change the permissions on the oninit utility in the $INFORMIXDIR/bin directory from 6754 to 6755.


Copyright© 2020 HCL Technologies Limited