In Mail Express Version 3.2.0 and later, a command-line utility included with the Mail Express Server is provided for performing various database-related tasks. Most common database tasks are handled by the Mail Express Server installer; however, on occasion it may be useful to use the command line utility to verify status or to provision additional databases.
You can use the database utility to perform the following tasks:
Create a database and user with settings appropriate for use by the Mail Express Server. This only creates the database and a database user; it does not create the database objects.
Check the version of the database to see if it is current. This action may be used to see if an upgrade must be performed on a database before it is ready to be used by the local version of the Mail Express Server.
Initialize the database for use by the Mail Express Server. This action can be used to either initialize a new database or upgrade an existing database. When initializing a new database, this action will create the database objects and appropriate default data.
Update the database configuration used by the local Mail Express Server. This action may be used to point the Mail Express Server at an alternate database or to change the credentials used to log in to the database. This action is similar to running the Mail Express Server installer in maintenance mode modify the database configuration.
Display the database configuration currently in use by the local Mail Express Server.
Test the connection to a database.
Perform limited validation of a database and/or database user account to ensure they have settings appropriate for use by the Mail Express Server.
The database utility is executed using the DOS batch file "DBUtil.bat" in the Mail Express's <Installation Directory>\bin directory. For your convenience, the Mail Express Server installer creates a Start menu shortcut that will open a Command Prompt in this directory.
To open the database utility
Open the Mail Express command prompt. By default, it is available at Start > Globalscape > Mail Express > Mail Express Command Prompt. It will be under a different folder if you chose an alternate Start menu group during the Mail Express Server installation.
The utility includes built-in help documentation. Additionally, the utility provides feedback on incorrect or missing command line parameters.
To view help on using the utility
To start the utility, type:
DBUtil.bat –help
For detailed help with the various top level actions, type:
DBUtil.bat –help –action <Action ID>
Where <Action ID> is one of:
CREATE_DATABASE AND USER - creates a database and a user.
CHECK - checks the version of the database to see if it is up to date.
INIT - initializes the database objects and default data.
PROPS - updates the current database settings for use by the Mail Express Server.
DISPLAY - displays the current database settings in use by the Mail Express Server.
CONNECT - tests connecting to a database.
VALIDATE - combines the VALIDATE_DATABASE and VALIDATE_DATABASE_USER actions.
VALIDATE_DATABASE - performs some minor validation of database settings.
VALIDATE_DATABASE_USER - performs some minor validation for the current database user.
Example executions for each of the actions supported by the database utility may be viewed in the command line help for each action.
Command line parameters for the utility are described below. Depending on the action performed, only a subset of the parameters will be applicable.
-help
Description: Display help on the command line. Refer to the “Help” section above for additional information.
-logfile” <file>”
Description: When specified, logs the output of the execution to the specified file.
Default: Not set
Example: -logfile “C:\DBUtil.log”
-errorfile “<file>”
Description: When specified, logs terminal error messages to the specified file.
Default: Not set
Example: -errorfile “C:\DBUtil.err”
-optionsfile “<file>”
Description: When specified, loads command line parameters from the file. The file should specify parameters in a “parameter=value” pair with one pair per line. Parameters specified on the command line override parameters specified in the file.
Default: Not set
Example: -optionsfile “C:\DBUtil.ini”
-ui
Description: When specified, enables the utility to display graphical interface components when necessary. This is mainly for use by external applications such as the Mail Express Server installer that call the utility internally. Currently the ui option is only applicable to the INIT action for displaying upgrade progress graphically.
Default: Not set
-verbose
Description: When specified, enabled debug level logging.
Default: Not set
-useprops
Description: When specified, the current Mail Express Server database configuration values will be used rather than requiring them to be provided on the command line.
Default: Not set
-propfile “<property file>”
Description: If –useprops is set and this value is specified the database connection information will be loaded from this file rather than the default Mail Express Server database configuration file.
Default: None
Example: -useprops –propfile “C:\jdbc.properties”
-action <action id>
Description: Specifies the overall action the utility should perform.
Value values:
CREATE_DATABASE AND USER - creates a database and a user.
CHECK - checks the version of the database to see if it is up to date.
INIT - initializes the database objects and default data.
PROPS - updates the current database settings for use by the Mail Express Server.
DISPLAY - displays the current database settings in use by the Mail Express Server.
CONNECT - tests connecting to a database.
VALIDATE - combines the VALIDATE_DATABASE and VALIDATE_DATABASE_USER actions.
VALIDATE_DATABASE - performs some minor validation of database settings.
VALIDATE_DATABASE_USER - performs some minor validation for the current database user.
Default: None
Example: -action CREATE_DATABASE AND USER
-timeout <seconds>
Description: The timeout in seconds to continue trying to connect to the database. A value of 0 will only attempt to connect once.
Default: 120 seconds
Example: -timeout 5
-server “<server name>”
Description: The database server host or IP address.
Default: None
Example: -server “Jupiter”
-port <port>
Description: The listener port for the database on the database server host.
Default: None
Example: -port 1433
-type <type>
Description: The dialect of the database.
Valid values:
SQLSERVER - a SQL Server/SQL Server Express database
ORACLE10G - an Oracle database
Default: None
Example: -type SQLServer
-instance “<instance name>”
Description: The database server instance name.
Default: None
Example: -instance “MSSQLSERVER”
-database “<database name>”
Description: The name of the database.
Default: None
Example: -database “MAILEXPRESS”
-application “<application name>”
Description: The application name to present to the database for use when identifying connections.
Default: Mail Express Server
Example: -application “ME Server A”
-auth <authentication type>
Description: The type of authentication to use when connecting to the database. SQL Server authentication and Windows authentication are supported.
Valid values:
SQLSERVER –SQL Server authentication.
WINDOWS –Windows authentication.
Default: None
Example: -auth SQLSERVER
-user “<user>”
Description: The login name to use when connecting to the database when –auth is set to SQLSERVER.
Default: None
Example: -user “medatabase”
-pass “<password>”
Description: The password to use when connecting to the database when –auth is set to SQLSERVER.
Default: None
Example: -pass “3qym9NCebHDJ”
-newauth <authentication type>
Description: The type of authentication to be used by the new database user account. Specified when creating database users. SQL Server authentication and Windows authentication are supported.
Valid values:
SQLSERVER –SQL Server authentication.
WINDOWS –Windows authentication.
Default: None
Example: -newauth SQLSERVER
-newuser “<new username>”
Description: The username for the new database user account. Specified when creating database users.
Default: None
Example: -newuser “medb2”
-newpass “<new password>”
Description: The password for the new database user account. Specified when creating new database users and –newauth is set to “SQLSERVER”.
Default: None
Example: -newpass “fkV6ZsX669p3”
-Dme.admin.username “<user>”
Description: The username to use for the initial Mail Express Administration account. Specified when initializing a new database. All –D style parameters must come last when specified on the command line.
Default: None
Example: -Dme.admin.username “meadmin”
-Dme.admin.password “<password>”
Description: The password to use for the initial Mail Express Administration account. Specified when initializing a new database. All –D style parameters must come last when specified on the command line.
Default: None
Example: -Dme.admin.password “wkBG2YxgzBpR”
-Dme.admin.email “<email address>”
Description: The email address to use for the initial Mail Express Administration account. Specified when initializing a new database. All –D style parameters must come last when specified on the command line.
Default: None
Example: -Dme.admin.email “meadmin@example.com”
-Dme.filesystem.root “<path>”
Description: The email attachment directory. Specified when initializing a new database. Supports both local physical drives and UNC-style paths. Mapped drives should be avoided because they only exist for the logon session of the current user. As such they typically will not be available to the Mail Express Server when running as a Windows Service. All –D style parameters must come last when specified on the command line.
Default: None
Example: -Dme.filesystem.root ”\\jupiter\FileStore\MailExpress”