Controlling the Database Server

www.mimer.com/developer

Controlling the Database Server - MIMCONTROL

MIMCONTROL functionality is supplied on all platforms as a complete administration tool for managing database servers.

UNIX: The database servers on a UNIX node can be controlled using the mimadmin command (see the mimadmin man-page). This command invokes the MIMCONTROL program, and other programs, as required. The MIMCONTROL command can also be used directly under UNIX.

A database server on UNIX can be administered by the owner of it or by the superuser "root". To change ownership of a database the mimdbfiles command is used (see the mimdbfiles man-page).

When a database server on a UNIX machine is started for the first time, MIMCONTROL will create a default multidefs file containing appropriate default parameter values, based on the amount of memory installed on the machine. Refer to The MULTIDEFS Parameter File for details.

Database server performance can be fine-tuned later by adjusting the parameters as required.

VMS: The database servers for the local databases on a VMS node are controlled by using the MIMCONTROL command directly (as described in this section).

When a database server on a VMS machine is started for the first time, MIMCONTROL will create a default MULTIDEFS file containing appropriate default parameter values, based on the amount of memory installed on the machine. Refer to The MULTIDEFS Parameter File for details.

Database server performance can be fine-tuned later by adjusting the parameters as required.

Win: When a local database is created on a Windows machine using the Mimer Administrator, appropriate default values are supplied for the parameters which control the database server and these can be adjusted later to fine tune server performance. On-line Windows help is provided with the Mimer Administrator.

The MIMCONTROL command can be used in a Command Prompt window on a Windows node to control local database servers.

The Mimer Administrator can also be used to control database servers on Windows platforms.

Windows NT/2000:

Database servers accessible from a Windows NT node are controlled by using the Mimer Controller utility. Refer to the online Windows help provided with the Mimer Controller for further details. You must belong to the administrators group to control database servers.

It is also possible to use Windows NT commands NET START, NET STOP, etc. to control database server processes.

Windows 98:

Database servers for the local databases on a Windows 98 node are started automatically. By right-clicking or double-clicking on the database server icon you can control the database server. Refer to the online Windows help provided with the Mimer SQL database server for further details.

MIMCONTROL Syntax

The MIMCONTROL program is controlled by flagged information specified on the command-line.

The overall syntax for MIMCONTROL (expressed in UNIX-style) is:
 mimcontrol [-bcdekstwA] [-l chan] [database]
 
If the MIMCONTROL command is invoked without any options it displays help on the command-line options.

MIMCONTROL Command-line Arguments
UNIX-style

VMS-style

Function
 -b
 /STATUS/DCL
Output status information about the specified database server as a single-line list suitable for use in a script.

For details about the output string resulting from this option, see MIMCONTROL (/STATUS/DCL or -b).
 -c
 /STATUS
Output status information about the specified database server.

This option can be combined with the -s option, see MIMCONTROL Examples.
 -d
 /DISABLE
Disable new user connections to the database server. Users already connected are not affected.

This option can be combined with the -s, -t and -w options, see MIMCONTROL Examples.
 -e
 /ENABLE
Enable new user connections to the database server.
 -k
 /KILL
Kill the database server immediately. This should only be used in emergency situations when a normal stop using the -t option does not work.

The next time the database is started, all databanks that were open at the time the server was killed will be automatically checked. Connected users will receive an error the next time they attempt to access the database.
 -l chan
 /LOGOUT=chan
Force logout of the specified channel number.

Use channel numbers displayed by the USERS option of the MIMINFO command, see The Users List.
 -s [timeout]
 /START [timeout]
Start the database server.

If the server does not become operational within the specified number of seconds, the server will be killed.

Default timeout is 600 seconds.

This option can be combined with the -c and -d options, see MIMCONTROL Examples.
 -t [timeout]
 /STOP [timeout]
Stop a database server. Any remaining users will be logged out.

If the server does not stop within the specified number of seconds, the server will be killed.

The default timeout is 120 seconds. This option can be combined with the -d and
-w options, see MIMCONTROL Examples.
 -w [timeout]
 /WAIT [timeout]
Wait for all connected users to log out.

If there are still users connected after the timeout period expires, the command fails.

The timeout period should be given in seconds. If no timeout period is specified wait will be performed without any timeout.

This option can be combined with the -d and -t options, see MIMCONTROL Examples.
 -A
 /DUMP
Create a dump directory and produce dumps of all internal database server areas to files in that directory.

The files produced can be examined by using the MIMINFO -f command, see System Information - MIMINFO.
 database
 database
Specifies the name of the database to access.

If a database name is not specified, the default database will be controlled.

The default database is determined by the setting of the MIMER_DATABASE environment variable.

The DEFAULT setting in SQLHOSTS is not used for MIMCONTROL.
UNIX: The UNIX-style command-line flags must be used on a UNIX machine.

VMS: Either the UNIX-style or the VMS-style command-line flags may be used on a VMS machine - see the Mimer SQL VMS Guide for more details.

Win: The UNIX-style command-line flags can be used from a Command Prompt window.

MIMCONTROL (/STATUS/DCL or -b)

The "mimcontrol -b" ("MIMCONTROL/STATUS/DCL") command is a special form of the "mimcontrol -c" ("MIMCONTROL/STATUS") command which returns the database server status information in the form of a single string containing a comma-separated list which is useful when writing scripts.

UNIX: On UNIX, the string returned from mimcontrol -b can be piped and processed as required. The UNIX command cut can be used to extract the list elements, e.g. the following command which will print the second list element:

# mimcontrol -b | cut -f2 -d ','

VMS: On VMS, the MIMCONTROL command is silent and sets the DCL symbol MIMER_STATUS to the value of the status string.

The lexical function F$ELEMENT() can be used to extract the list elements.

Win: On Windows, the string returned from "mimcontrol -b" can be piped and processed as required, depending on the script language being used.

Status String Components

The status string has the following components:
 server-state,logins,db-directory,connections,server-pid,start-date
 
Each component is described below:

server-state

The server-state value shows the state of the database server. The value is one of "stopped", "starting", "running", stopping" or "crashing".

logins

The logins value is either "enabled" if new logins are permitted or "disabled" if the server has been ordered to reject new logins.

db-directory

The db-directory field shows the home directory for the database.

connections

The connections field shows the number of clients connected to the server.

server-pid

The server-pid field gives the process id of the database server process.

start-date

The start-date field gives the date and time when the database server was started.

Note: If the database server is not operational, the status string will contain only the first three fields.

MIMCONTROL Examples

The parameter options can be combined in the following ways ("HOTEL" is the example database used, equivalent examples are given in both VMS-style and UNIX-style):
Start a database server, but disallow new logins immediately:
 MIMCONTROL/START/DISABLE HOTEL
 mimcontrol -sd hotel
 
Start a database server and output a status message for the newly started server:
 MIMCONTROL/START/STATUS HOTEL
 mimcontrol -sc hotel
 
Disable new user connections, then wait for up to three minutes for all users to log out.:
 MIMCONTROL/DISABLE/WAIT=180 HOTEL
 mimcontrol -dw 180 hotel
 

   The exit code from the MIMCONTROL command is "success" if all users logged out within the three minute timeout period. 


   If the timeout period expires and there are still users logged in on the system, the MIMCONTROL command will exit with a "warning" status code.
The following command will wait for all users to log out of the system:
 MIMCONTROL/WAIT/STOP HOTEL
 mimcontrol -wt hotel
 

   When all users are logged out, the system will be stopped. If the wait timeout period expires, the MIMCONTROL command will exit with a "warning" status code without stopping the system.
The following command is similar to the previous one, but will ensure that no new users log in to the system while waiting for all users to log out:
 MIMCONTROL/DISABLE/WAIT/STOP HOTEL
 mimcontrol -dwt hotel
MIMCONTROL Exit Codes

The MIMCONTROL command returns a status code to the environment executing the command. The status code can be examined by scripts.

VMS: On VMS, the status codes correspond to the VMS condition code severity levels.

Use the $SEVERITY symbol in DCL command procedures.

The following return codes are used:

UNIX/Windows

VMS

Usage

0 (success)

1 (success)

This code is used when the MIMCONTROL command has executed all options with no problems.

1 (warning)

0 (warning)

The warning code is used when there was a timeout in one of the options. The complete sequence of options may not have been executed.

> 1 (error)

2 (error)

The error code is used when the specified command could not be executed at all. For instance, if there was an illegal combination of options, or if the specified database name was not found.

If an "error" status code is returned, an informational error message will also be produced.

UNIX: The database servers on a UNIX node can be controlled using the mimadmin command (see the mimadmin man-page). This command invokes the MIMCONTROL program, and other programs, as required. The MIMCONTROL command can also be used directly under UNIX. A database server on UNIX can be administered by the owner of it or by the superuser "root". To change ownership of a database the mimdbfiles command is used (see the mimdbfiles man-page). When a database server on a UNIX machine is started for the first time, MIMCONTROL will create a default multidefs file containing appropriate default parameter values, based on the amount of memory installed on the machine. Refer to The MULTIDEFS Parameter File for details. Database server performance can be fine-tuned later by adjusting the parameters as required.

VMS: The database servers for the local databases on a VMS node are controlled by using the MIMCONTROL command directly (as described in this section). When a database server on a VMS machine is started for the first time, MIMCONTROL will create a default MULTIDEFS file containing appropriate default parameter values, based on the amount of memory installed on the machine. Refer to The MULTIDEFS Parameter File for details. Database server performance can be fine-tuned later by adjusting the parameters as required.

Win: When a local database is created on a Windows machine using the Mimer Administrator, appropriate default values are supplied for the parameters which control the database server and these can be adjusted later to fine tune server performance. On-line Windows help is provided with the Mimer Administrator. The MIMCONTROL command can be used in a Command Prompt window on a Windows node to control local database servers. The Mimer Administrator can also be used to control database servers on Windows platforms. Windows NT/2000: Database servers accessible from a Windows NT node are controlled by using the Mimer Controller utility. Refer to the online Windows help provided with the Mimer Controller for further details. You must belong to the administrators group to control database servers. It is also possible to use Windows NT commands NET START, NET STOP, etc. to control database server processes. Windows 98: Database servers for the local databases on a Windows 98 node are started automatically. By right-clicking or double-clicking on the database server icon you can control the database server. Refer to the online Windows help provided with the Mimer SQL database server for further details.

UNIX-style	VMS-style	Function
-b	/STATUS/DCL	Output status information about the specified database server as a single-line list suitable for use in a script. For details about the output string resulting from this option, see MIMCONTROL (/STATUS/DCL or -b).
-c	/STATUS	Output status information about the specified database server. This option can be combined with the -s option, see MIMCONTROL Examples.
-d	/DISABLE	Disable new user connections to the database server. Users already connected are not affected. This option can be combined with the -s, -t and -w options, see MIMCONTROL Examples.
-e	/ENABLE	Enable new user connections to the database server.
-k	/KILL	Kill the database server immediately. This should only be used in emergency situations when a normal stop using the -t option does not work. The next time the database is started, all databanks that were open at the time the server was killed will be automatically checked. Connected users will receive an error the next time they attempt to access the database.
-l chan	/LOGOUT=chan	Force logout of the specified channel number. Use channel numbers displayed by the USERS option of the MIMINFO command, see The Users List.
-s [timeout]	/START [timeout]	Start the database server. If the server does not become operational within the specified number of seconds, the server will be killed. Default timeout is 600 seconds. This option can be combined with the -c and -d options, see MIMCONTROL Examples.
-t [timeout]	/STOP [timeout]	Stop a database server. Any remaining users will be logged out. If the server does not stop within the specified number of seconds, the server will be killed. The default timeout is 120 seconds. This option can be combined with the -d and -w options, see MIMCONTROL Examples.
-w [timeout]	/WAIT [timeout]	Wait for all connected users to log out. If there are still users connected after the timeout period expires, the command fails. The timeout period should be given in seconds. If no timeout period is specified wait will be performed without any timeout. This option can be combined with the -d and -t options, see MIMCONTROL Examples.
-A	/DUMP	Create a dump directory and produce dumps of all internal database server areas to files in that directory. The files produced can be examined by using the MIMINFO -f command, see System Information - MIMINFO.
database	database	Specifies the name of the database to access. If a database name is not specified, the default database will be controlled. The default database is determined by the setting of the MIMER_DATABASE environment variable. The DEFAULT setting in SQLHOSTS is not used for MIMCONTROL.

UNIX: The UNIX-style command-line flags must be used on a UNIX machine.

VMS: Either the UNIX-style or the VMS-style command-line flags may be used on a VMS machine - see the Mimer SQL VMS Guide for more details.

Win: The UNIX-style command-line flags can be used from a Command Prompt window.

UNIX: On UNIX, the string returned from mimcontrol -b can be piped and processed as required. The UNIX command cut can be used to extract the list elements, e.g. the following command which will print the second list element: # mimcontrol -b \| cut -f2 -d ','

VMS: On VMS, the MIMCONTROL command is silent and sets the DCL symbol MIMER_STATUS to the value of the status string. The lexical function F$ELEMENT() can be used to extract the list elements.

Win: On Windows, the string returned from "mimcontrol -b" can be piped and processed as required, depending on the script language being used.

VMS: On VMS, the status codes correspond to the VMS condition code severity levels. Use the $SEVERITY symbol in DCL command procedures.

UNIX/Windows	VMS	Usage
0 (success)	1 (success)	This code is used when the MIMCONTROL command has executed all options with no problems.
1 (warning)	0 (warning)	The warning code is used when there was a timeout in one of the options. The complete sequence of options may not have been executed.
> 1 (error)	2 (error)	The error code is used when the specified command could not be executed at all. For instance, if there was an illegal combination of options, or if the specified database name was not found. If an "error" status code is returned, an informational error message will also be produced.

Upright Database Technology AB
Voice: +46 18 780 92 00
Fax: +46 18 780 92 40
dbtechnology@upright.se