[This is prerelease documentation and is subject to change in future releases. Blank topics are included as placeholders.]
The Mx.exe program provides support for several important tasks involving Microsoft code name “M” image files and other general tasks involving the Modeling Services database. These commands can be grouped into two categories.
The following commands support operations related to “M” image files.
-
install
-
uninstall
-
export
-
list
The install command installs image files created by the Microsoft code name “M” compiler into a SQL Server database. Mx.exe takes one or more image files and installs them into a specified database. By default, install works in an incremental fashion: the parts of the image file that have previously been installed in the database are skipped and only the differences are installed. Mx.exe verifies that the matching image file contents and database contents have the same signature. The uninstall command removes a previously installed image from the target database. The export command exports a database schema, extent, or image into a “M” image file. The list command lists all images currently loaded in a database.
The following commands support general tasks associated with the Modeling Services database.
-
create
-
createFolder
-
dropFolder
-
infer
The create command installs a new Modeling Services database to the specified server. The createFolder command creates a new Modeling Services Folder, whereas the dropFolder command removes a Folder. For more information about Modeling Services Folders, see Using Folders and Ids. The infer command infers a catalog from the SQL Server schema information of a non-Modeling Services database.
Command Line Usage
To run Mx.exe, open a Microsoft SQL Server Modeling CTP Command Prompt from the Start Menu. This will automatically place the bin directory in your path.
Each invocation of Mx.exe requires specifying one of the eight main commands. There are global parameters that can be used by all of these commands. There are also specific parameters for some commands that apply only to those commands. The sections that follow describe the global parameters first. There is then a separate section describing the specialized parameters for each command.
Global Parameters
Use the following parameters to specify the database connection, security features, and other options that apply to all command types.
|
Option
|
Alias
|
Description
|
|---|
|
server:
|
s
|
Specifies the SQL Server to connect to. (Default = (local))
|
|
database:
|
d
|
Specifies the target database on the server to work against. The database must exist prior to the connection unless the create option is specified for the install command.
|
|
trustedConnection:
|
t
|
Specifies the security setting for the connection. Possible values include None, Integrated, and SSPI. (Default = Integrated)
|
|
user:
|
u
|
Specifies the user name for the connection. This is required if the trustedConnection option specifies a value of None.
|
|
password:
|
p
|
Specifies the password for the connection. This is required if the trustedConnection option specifies a value of None.
|
|
loginTimeout:
|
lt
|
Specifies the timeout value in seconds for the login when connecting to the server. (Default = 15)
|
|
commandTimeout:
|
ct
|
Specifies the timeout value in seconds for running SQL commands. (Default = 300)
|
|
userInstance
|
ui
|
Specifies whether to redirect the connection from the default SQL Server Express instance to a runtime-initiated instance running under the account of the caller.
|
|
verbose
|
v
|
Specifies to print the verbose output for Mx.exe.
|
|
nologo
|
nologo
|
Hides the program logo.
|
|
?
|
?
|
Displays the command-line help text.
|
|
@<file>
|
@<file>
|
Read <file> for more parameters. For example, if the parameters were contained in the file params.txt, you could pass this file with the following command: mx.exe @params.txt.
|
Install Parameters
The following parameters are used when installing images into a SQL Server 2008 database. Note that the target .mx image files should be listed immediately following the install command and before the list of parameters. This could be one or more .mx files, or it could be a wildcard value, such as *.mx. The following command provides an example of installing a Shape.mx file into a Repository database on the local machine.
mx.exe install Shape.mx -database:Repository
|
Option
|
Alias
|
Description
|
|---|
|
create
|
c
|
Creates the target database.
|
|
force
|
f
|
Performs a forced install. Existing database objects that match image file content are deleted and recreated.
|
|
recurse:
|
r
|
Specifies the image files to reference when resolving dependencies. Wildcards can be used. Multiple image files should be separated by commas.
|
|
ignore
|
ig
|
Ignores missing dependencies that cannot be resolved.
|
|
property:
|
pt
|
Specify a custom property in the form Name=Value.
|
|
targetFolder:
|
tf
|
The Folder name associated with any installed type instances if the associated types use the Folder pattern.
|
Uninstall Parameters
The uninstall command removes an image from a target SQL Server database. The target image must have been installed with the install command. There are no parameters specific to the uninstall command. The following example shows how to use the uninstall command.
mx.exe uninstall Shape -database:Repository
Note that by default, the name of the image is the same as the image file name without the .mx extension. There are times when the uninstall command will be unable to remove an image from the database. In those cases, you have to drop and recreate the target database. For more information, see How to: Update an Existing Model by Recreating the SQL Server Modeling Services Database.
Export Parameters
The export command creates a “M” image file from any SQL Server schema, “M” image, or “M” extent in an existing database. The following example shows how to export a Shape image that was previously installed into a Repository database.
mx.exe export -database:Repository -image:Shape –package:Image -out:NewShapeImage.mx
|
Option
|
Alias
|
Description
|
|---|
|
image:
|
i
|
Exports an image stored in the database to an image file. This requires that the infrastructure tables exist to track loaded images.
|
|
content:
|
co
|
Specifies the type of content to export. Possible values include Schema, Instances, and All. (Default = All)
|
|
module:
|
m
|
Exports one or more “M” modules or SQL Server schemas from the database to an image file. Multiple modules should be separated by commas.
|
|
all
|
all
|
Exports all of the SQL Server constructs in the database that are associated with “M”.
|
|
targetFolder:
|
tf
|
The Folder name associated with any exported type instances if the associated types use the Folder pattern.
|
|
package:
|
ep
|
Specifies the type of file to use for the exported information. Possible values include Text and Image. (Default = Text)
|
|
out:
|
o
|
Specifies the output file to use when writing out the image file. This parameter is required when the export command is used.
|
List
There are no parameters specific to the list command. The following example shows how to use the list command.
mx.exe list –database:Repository
Note that a Modeling Services database can track loaded image files. When the list command is used on a Modeling Services database, it will show the images that were loaded by the Mx.exe tool.
Create Parameters
The create command creates a new Modeling Services database.
mx.exe create -database:Repository
|
Option
|
Alias
|
Description
|
|---|
|
dataFile:
|
df
|
Specify the physical file name for the database.
|
|
dataFileInitialSize:
|
di
|
Specify the initial size of the data file.
|
|
dataFileMaxSize:
|
dm
|
Specify the maximum size to which the data file can grow.
|
|
dataFileGrowth:
|
dg
|
Specify the automatic growth increment of the data file. For set sizes, use KB, MB, GB, or TB following the number (for example, 1GB). For percentages, use the percent sign (for example, 10%).
|
|
logFile:
|
lf
|
Specify the physical file name for the log.
|
|
logFileInitialSize:
|
li
|
Specify the size of the log file.
|
|
logFileMaxSize:
|
lm
|
Specify the maximum size to which the log file can grow.
|
|
logFileGrowth
|
lg
|
Specify the automatic growth increment of the log file. For set sizes, use KB, MB, GB, or TB following the number (for example, 1GB). For percentages, use the percent sign (for example, 10%).
|
|
force
|
f
|
Creates the database even if there is an existing database with the same name. The existing database is dropped during this process.
|
Note that the created database does not contain any models. Adding the standard Base Domain Library (BDL) and other models requires an additional step. For example, the SQL Server Modeling CTP installs several image files (.mx) that you can apply. The BDL is contained by the Repository.mx file. There are also properties associated with the BDL that can be applied with the property option during the installation. The available properties for the Repository.mx file are the following:
-
RepositoryAdminGroupMembers or ram – specifies a comma-separated list of domain accounts to assign to the RepositoryAdministrator role in the database.
-
RepositoryChangeTracking or rct – specifies either the plus sign (+) to enable change tracking or the minus sign (-) to disable change tracking.
-
RepositoryAuditing or ra – specifies either the plus sign (+) to enable auditing or the minus sign (-) to disable auditing.
-
RepositoryChangeDataFileGroup or rcdfg – specifies either the plus sign (+) to create a new file group for CDC data or the minus sign (-) to decline.
-
RepositoryChangeDataPartitionFile or rpf – specifies either the plus sign (+) to create a partition file for CDC data or the minus sign (-) to decline.
-
SchemaPolicy or sp – specifies either the plus sign (+) to enable the schema policy that enforces Modeling Services schema rules or the minus sign (-) to decline.
-
FullRecovery or fr – specifies either the plus sign (+) to enable full recovery or the minus sign (-) to disable it.
The following command demonstrates installing the BDL into an empty Modeling Services instance named Repository. This command uses a property to enable auditing.
mx.exe install Repository.mx -database:Repository -property:ra=+
.gif)
Caution:
|
|---|
|
If the installation of the Base Domain Library image (Repository.mx) or the domain models fails, the Modeling Services database can be left in an intermediate state. In this state future installations of these models can fail. The only solution is to drop and recreate the Modeling Services database.
|
CreateFolder
The createFolder command creates a Modeling Services Folder based on the specified path. Note that the path uses forward slashes when referring to child Folders. The following example creates a new Folder, named MyFolder, as a child of the system-provided Repository Folder.
mx.exe createFolder Repository/MyFolder -database:Repository
DropFolder
The dropFolder command drops a Modeling Services Folder based on the specified path. The following example drops the MyFolder Folder created in the previous section.
mx.exe dropFolder Repository/MyFolder -database:Repository
Infer
The infer command infers an “M” catalog based on the SQL Server schema of a non-Modeling Services database.
mx.exe infer -database:TargetDatabase
See Also