IInstallation Guide: Windows / Binary

MIR/MESA Installation Guide: Windows / Binary

Electronic Radiology Laboratory
Mallinckrodt Institute of Radiology
510 South Kingshighway Blvd.
St. Louis, MO 63110
314.362.6965 (Voice)
314.362.6971 (Fax)

Version 12.1.0
21-October-2008

Introduction

This document describes the installation procedure for MESA software for select MS Windows systems (NT 4.0, Windows 2000). Users reading this document have chosen to install the MESA software using pre-compiled binaries. Installation instructions for Unix binaries or from source code are found in other documents.

Check mark	Task #	Task	Section Reference (this document)
	1	Verify operating system compatibility for MESA test tools
	2	Decide upon the target directory structure you will use (or use defaults)
	3	Verify available disk space
	4	Verify previous versions of MESA test tools are not installed
	5	Install Microsoft SQL Server (server license, not client)
	6	Create SQL ODBC logins and passwords
	7	Install PERL
	8	Install PERL module - date
	9	Install the Sun Java 2 Software Development Kit
	10	Install MESA Test Tool software and scripts (includes necessary CTN software)
	11	Build SQL database tables
	12	Install the MESA Storage files
	13	Create Environment Variables
	14	Begin executing test scripts by referring to IHE Test Plan documents

Target Directory

MESA is designed to be installed in a target directory specified at build time. We use the environment variable MESA_TARGET for this directory; the default value is D:\mesa for Windows XP systems. Once the installation procedure is complete, all software depends only on executables, configuration files, data files in the target directory and files in the storage directory (see 1.2). The target directory contains these subdirectories:

bin	The compiled executable programs
db	Files for controlling database operations (Radiology base)
lib	Shared libraries loaded at runtime
logs	Logfiles for all MESA server applications
runtime	Configuration files for applications
mesa_tests	Scripts/data for test protocol
webmesa	A holding directory used for the second stage of the installation process.

Storage Directory

The MESA storage directory is used to store messages and datasets received from peer applications. For example, the MESA Image Manager will store images received from modalities in this directory. The default for this is D:\mesa\storage. The location of this directory is recorded in the environment variable MESA_STORAGE. We separate this from the target directory to give you more control over disk partitions on your system. The space required for this directory depends on the tests you perform; 100 slices of CT data require much more space than one small Nuclear Medicine study.

Disk Space

Users installing the MESA software will need to be aware of the disk requirements for the system. The table below summarizes the disk requirements for various parts of the system. If you want to use the default target directory and you have insufficient disk space in that partition, you can use soft links in the file system.

Operating System	Software	Space (MB)
Windows XP, 2000, 2000 Server	Perl	30
Windows XP, 2000, 2000 Server	SQL Server	200
Windows XP, 2000, 2000 Server	Java JDK	55
Windows XP, 2000, 2000 Server	MESA Installation in target directory	50
Windows XP, 2000, 2000 Server	MESA Source Code when compiled (can be deleted after installation)	175

Uninstalling Previous Versions

There are no incremental upgrades to the MESA software. Each installation writes over the top of the previous installation (unless you choose to retain the old version in a separate directory). To remove a previous version:

• cd %MESA_TARGET%\db

• perl drop_mesa_tables.pl <sa login> <sa password> <server>

• Use Windows Explorer to delete all directories in %MESA_TARGET%

The first two steps remove existing MESA databases. The parameters <sa login> and <sa password> refer to the system administrator account for SQL Server. The <server> parameter is passed to the isql command and identifies the server name. If you are using interactive SQL (isql) with these parameters, the syntax is:

   isql –U <sa login> -P <sa password> -S <server>

For example:

   isql –U ctn –P ctn –S TBALL

ISQL is the command used by SQL Server 2000. As of 12.1.0, we are encouraging organizations to move to SQL Server 2005 Express. That software uses osql rather than isql. The last step removes the installed binaries, libraries and data files.

MESA Internal Software Packages

The MESA libraries and applications are built on top of several other software packages. This section only describes those packages that are compiled into the MESA software. Sections 4 and 5 will describe other software packages (compilers) used to build MESA.

MIR Central Test Node (CTN) Software

The MIR Central Test Node (CTN) software is a public domain DICOM implementation that was originally funded by the RSNA and is maintained by MIR. This software is written in the “C” programming language and provides libraries that support various parts of the DICOM Standard or natural applications of the DICOM Standard. These include Information Object creation, encoding and parsing, network operations, DIMSE services and network operations. The CTN software also provides a number of simple test programs (transmit this image) and more complete applications (image server).

An extension to the CTN software called JAVACTN is used by the MESA software. A small set of Java classes are used to support some DICOM operations, such as Information Object manipulation. This software uses the Java Native Interface (JNI) to provide access to the CTN C libraries.

The CTN software requires some updates to satisfy the MESA design goals. An updated version of the CTN software is included with the MESA distribution.

HL7IMEXA

HL7IMEXA is a table-driven HL7 message builder/parser that has its origins at Columbia University. The Columbia implementation was called HL7IMEX. The software was modified by Allen Rueter of MIR and renamed HL7IMEXA. This software is written in the “C” language and supports message building and parsing, but no network operations. Minor changes are made to this package to support the C++ environment used by MESA and to correct some runtime problems.

Microsoft SQL Server

This relational database is a commercial product from the Microsoft Corporation. This is the database used by the MESA tools for Windows NT 4.0 and 2000 Server installations. This is a licensed product from Microsoft and requires the user to obtain the appropriate software and licenses.

As of 12.1.0, we are encouraging the use of SQL Server 2005 Express. This is a free version from Microsoft that is available from their download website. If you need to use SQL Server 2000, you will need to purchase that license and request a different distribution of MESA tools.

Xerces C

Xerces C is a library maintained by the Apache foundation used to parse XML data. Quoting from the Apache web page:

Xerces (named after the Xerces Blue butterfly) provides world-class XML parsing and generation. Fully-validating parsers are available for both Java and C++, implementing the W3C XML and DOM (Level 1 and 2) standards, as well as the de facto SAX (version 2) standard. The parsers are highly modular and configurable. Initial support for XML Schema (draft W3C standard) is also provided

Apache Tomcat Web Server

The Apache Tomcat web server is maintained by the Apache foundation (www.apache.org). This web server is designed to support Java servlets and provides the mechanism we use for web applications.

ImageMagick

ImageMagick®, version 6.3.0, is a software suite to create, edit, and compose bitmap images. It can read, convert and write images in a variety of formats (about 100) including GIF, JPEG, JPEG-2000, PNG, PDF, PhotoCD, TIFF, and DPX. Use ImageMagick to translate, flip, mirror, rotate, scale, shear and transform images, adjust image colors, apply various special effects, or draw text, lines, polygons, ellipses and Bézier curves. This software is found at http://www.imagemagick.org/script/index.php. Not all tests require this software; please refer to the installation instructions in this document and the test instructions for specific actors.

Installation from Compiled Binaries

Links to Binaries

This section provides links to binary files required for installation.

Author	Package
Microsoft	SQL Server 2000 no longer supported by Microsoft. Use it if you have a licence + copy. Otherwise, use SQL Server 2005 Express
Microsoft	SQL Server 2005 Express Install SQL Server 2005 Express Edition with Advanced Services SP2
MIR/ERL	MIR MESA Software

Database Installation

Microsoft SQL Server Installation: Windows XP, Windows 2000, Windows 2000 Server

The MESA software is tested with Microsoft SQL Server 2000 and SQL Server 2005 Express. The MS SQL Server product provides a setup tool that guides you through the installation process. When the installation is complete, you will be able to interact with the server using interactive SQL and their GUI-based management tools. The MESA software communicates with the server using ODBC, and your PC must be configured to use that channel.

1. Install SQL Server 2000 or SQL Server 2005 Express according to the Microsoft directions. Take note of the server name during the installation. For SQL Server 2005 Express, this might be .\sqlexpress. For SQL Server 2000, this might be your hostname.
2. SQL Server 2005 Express:
   1. Uncheck the box that says "Hide Advanced Features"
   2. Make sure you enable installation of Connectivity Components and Manage Studio Express. You do not need the development kit.
   3. When it asks for the default or named instance, you are free to choose Named Instance. The name that is the default for our installation is SQLExpress. You can pick another name as long as you configure the rest of MESA properly.
   4. For authentication, choose Mixed Mode. Choose a secure password for the sa account.
   5. Use the default collation
   6. Enable User Instances
3. Test the installation and link to the command line tools. If this step fails, the MESA software will not work:
   1. For SQL Server 2005 Express: "osql -E -S %SERVER_NAME%". For example, osql -E -S .\sqlexpress
   2. For SQL Server 2000: "isql -E -S %SERVER_NAME%".
   3. For both tests, you should get a ">" prompt. That means you have linked the client tool to the server, and further MESA software should run.

Create SQL Server Account Most of the scripts use an account other than the sa account. This will be safer for you in the long run. We create an account called "ctn" with the password "ctn". You can create a different account with your local naming conventions.

1. For SQL Server 2000
   1. Use SQL Server Enterprise Manager and create a new login with password. Choose SQL Server Authentication and enter the appropriate password.
2. For SQL Server 2005 Express
   1. Use SQL Server Management Studio Express and create a new login with a password. Choose SQL Server Authentication and enter the appropriate password. You might want to turn off password expiration.

Configure the ODBC Driver MESA applications use the ODBC driver for connection to the database. You need to configure ODBC using the login/password created above. You could use an existing acount; the example we use is the account ctn with the password ctn. This is an account managed by SQL Server and not Windows.

Open the Control Panel folder and then open ODBC. For 2000 Server, you will find the ODBC control under Administrative Tools in the Control Panel. Select the "System DSN" tab. There will be a list of system data sources. There should be one called LocalServer which uses the SQL Server driver. This entry is created by the SQL Server installation procedure. Our server is configured with these values (set by the SQL Server setup program). You can choose a different login ID and password. The runtime notes will tell you how to communicate your values to the MESA software.

If there is not a data source called LocalServer or some data source that connects to the SQL Server 2005 Express server, you will need to create one.

Variable	Value
Name	LocalServer
Description	<blank>
Which server	local For SQL Server 2005 Express, you will have to type in the server name. There is not drop down entry. Enter .\SQLExpress or the value you used to name your instance.
Verify authenticity by …	SQL Server authentification
Login ID	ctn
Password	ctn

The MESA software runs on the same machine as the SQL Server, so we use the local connection. We do not use the trusted connection option, but you might decide to do so depending on how you want to configure your system.

The database software uses the environment variable SQL_ACCESS to determine the 3 parameters needed to establish the connection to the SQL database. The format of this variable is:

   <server name>:<login>:<password>

We use this at our site: LocalServer:ctn:ctn

If you do not define this environment variable, the LocalServer:ctn:ctn values are used by default. You might choose to use a different login name or password or a different scheme. If you choose to use the Trusted Server feature of the system, you can leave the login and password values blank in the SQL_ACCESS variable: "LocalServer:::".

The SQL Server has security features that allow the administrator to restrict access to tables in the database. You may find that you need to open up access to get the MESA software to operate properly. If the MESA applications complain about access privileges, you will need to use the SQL Enterprise Manager to give you access rights to the databases (insert, delete). There are several methods for allowing access. One simple method is to activate the Manage pulldown (in SQL Enterprise Manager) and select logins. For the login that you are using, alias that login as dbo (stands for database owner) for the databases you are using. That should give you the privileges you need. We also suggest you read the SQL Server documents to understand their security features (they will certainly explain them better than we can).

Perl Installation

Perl is available for Win32 systems at http://www.activestate.com. We are using ActivePerl 5.6 on our systems. The Active State distribution comes in two versions. One requires the MSI installer and the other version has no uninstall feature. If either version is unacceptable to you, you can build the perl from source. Use the stable version (5.6 as of this document) that can be found at http://www.perl.org. We have installed this version in D:\perl.

Additional Perl Modules

Version 8.0.0 of the MESA tools uses additional Perl modules. These can be found on the web distribution page. Install as follows:

Date/Manip.pm	No need to install; included in mesa_tests/actors/rad/common/scripts. If you find a conflict with your perl installation (perl already has this module), remove the MESA copy.

Install Java

Install the Sun Java 2 Software Development Kit (JDK) for version 5.0 or higher. The JRE is not sufficient. You need to obtain this from the Sun web server: www.java.sun.com. We are not allowed to redistribute the JDK.

Sun publishes several different versions of the JDK. As of Nov, 2006, we are using JDK 5.0 Update 9. Other versions would work, but will include more software than is required. We are specifically not using:

• JDK with NetBeans • JDK with Java EE • JRE • Java Source Code

Apache Tomcat Installation

This is only used for the RID profile. The installation is broken. We need to repair the process. Do not install this software.

The Apache Tomcat server is used by the MESA Information Source actor to supply summary information and documents in response to RID queries. Install version 5.0.28 or higher. The installation file that we provide is a Windows installation program from the apache site that is ready for installation.

The table below lists the installation directories that we use for testing. These values are not required, and you might choose different directories.

Table 3.4-1 Tomcat Installation Directories

System	Director
Windows 2000	C:\tomcat\Jakarta-5.0.28

JDBC Installation

This is only for testing the RID profile. The installation is broken for SQL Server 2005 Express. Do not install this software. We will repair the instructions.

The RID tests use Java servlets communicating with the SQL Server database through a JDBC connection. This requires the installation of the JDBC driver from Microsoft. The software version that you will need is SQL Server 2000 Driver for JDBC Service Pack 1 You can find this software on the Microsoft website. Follow these steps on the Microsoft web page:

1. Select Downloads (left flap)

2. Select Drivers (left flap)

3. In the search page, enter JDBC for the Keyword and select “Go”

4. You should see the list of drivers

We are testing with Service Pack 3.

Install the software per Microsoft’s instructions. On our system, the software is installed in C:\Program Files\Microsoft SQL Server 2000 Driver for JDBC. That installation directory is not important.

Copy the 3 jar files in the JDBC distribution lib directory to %TOMCAT_HOME%\common\lib. These three files are:

• msbase.jar • mssqlserver.jar • msutil.jar

OpenLDAP

OpenLDAP for PWP tests has been tested only on RedHat Linux systems. Contact the Project Manager for Internet testing.

Agfa/Philips DVT

This is not longer needed for testing. You will test using a different tool from the Gazelle project. You are not required to install for MESA testing.

The DICOM Validation Tool (DVT) is a software utility and a set of .NET components that will assist in testing DICOM conformance. MESA will use DVT to validate DICOM objects. You can download DVT at http://www.dvtk.org.

Install DVT by double-clicking on the downloaded exe file and follow the instructions. Install DVT in the default directory.

ImageMagick

Only install for testing the NMI profile.

The ImageMagick software is found at http://www.imagemagick.org/script/index.php. This software is currently used to support tests of Acquisition Modalities in the NMI profile. Do not install this software unless that is relevant to your system.

The ImageMagick web site provides 4 binary installation versions. We chose this following version: ImageMagick-6.3.0-5-Q16-windows-static.exe Follow their installation instructions. Make sure the PATH variable is updated with the path to the ImageMagick executables. The MESA scripts make no assumptions about the location of the software and rely on the PATH variable.

MESA Installation

The pre-compiled version of MESA software is distributed as a zip file. This software can be installed using a normal account with no system privileges. All software is installed in the target directory (%MESA_TARGET%) and no files are installed in any system directories. No changes are made to the Registry.

Open the zip archive for the MESA binary distribution. Extract the files to the MESA default directory (D:\mesa). You may choose a different disk (and/or path); just be sure to adjust the direct names given below and to set the runtime environment when you use the software.

Completion for Sites Requiring Tomcat (e.g., RID Profile)

Complete the installation by copying MESA files to the Tomcat directory. You need to set the environment variables TOMCAT_HOME and MESA_TARGET appropriately. In the directory %MESA_TARGET%\webmesa\mesa-iti:

1. Edit the file web_w32_sqlserver.xml (use notepad).

2. Find the two different initialization parameters whose param-name is logPath. Change the first part of the param-value from D:\mesa to the directory where the MESA software is installed (i.e., the value for %MESA_TARGET%). Leave the segment that says \logs\info_src.log as is.

3. Find the two different initialization parameters whose param-name is jdbcConnectURL. Change the values for ServerName, User and Password in the URL to appropriate values for your system. If you use our normal conventions, these values would be LocalServer, ctn, ctn.

4. Find the one initialization parameter whose param-name is imagePath. Change the param-value to the partition and directory where you have chosen to install the MESA storage data. The default value is D:\mesa\storage.

5. To complete this installation step:

   cd %MESA_TARGET%\webmesa\mesa-iti
   install.bat

Build Databases

The installation procedure assumes you will build databases needed for all MESA tests. The first step is to create 15 databases for the various MESA actors/simulators.

You can use the SQL Enterprise Manager to create the databases or use two perl scripts provided with the MESA tols. If you choose to create by hand, use the SQL Enterprise Manager to create the following databases:

1. adt, expmgr, exprcr. imgmgr, info_src
2. mod1, mod2, ordfil, ordplc, pd_supplier
3. rpt_manager, rpt_repos, syslog, wkstation, xref_mgr

Each database should be at least 5 MB in size. For each database, add the SQL server account configured in section 5.2 above as a db_owner. This will allow you to add and remove tables.

Create Databases with MESA Script For this, you need to know where the SQL Server software is installed. The default is C:\Program Files\Microsoft SQL Server. Use a Command Prompt/DOS window and set the directory to %MESA_TARGET\db. Execute the perl script:

 perl generate_create_scripts.pl

This script will prompt you for the location of the SQL server installation and then write one SQL file with commands to create the required databases (not tables yet). It will list the folder and database names for the 15 databases.

Then, execute this perl script:

 perl create_db.pl server_name

For SQL Express, server name might be something like .\sqlexpress.

This script drops the existing databases and then creates new ones. That means the first time you run it, you will see error messages about databases that do not exist. Either ignore those messages or run the script twices to make sure you see no error messages.

Build Database Tables Once the databases have been built, you need to create the tables in the databases. Use a DOS window and set the directory to %MESA_TARGET%\db. Execute the perl script:

   perl create_mesa_tables.pl <login> <password> <server>

In the example that we use, login and password are both “ctn”. As mentioned previously, the login that you choose will need db_owner rights to create tables in the database. The server parameter is passed with the –S switch to isql; it is the name you have given your SQL server.

Load Databases with Test Data

The ITI tests require some initial data in the SQL database. There are two SQL files to load with this test data. You can load these using the command line, SQL interpreter (isql) or the SQL Query Analyzer. The data should be loaded into the info_src table:

   isql –S <server> -Ulogin –Ppassword –D info_src < load_rid_data.sql
   isql –S <server> -Ulogin –Ppassword –D info_src < load_doc_reference.sql

5 Install the MESA Storage Directory

The MESA storage directory is separate from the MESA_TARGET directory. We distribute separate zip files for installation. Use the table below to determine which files are appropriate for your installation.

Table 5.1-1 MESA Storage Files

MESA Tests	Storage File Name
All	MESA-storage-A (version)
Radiology/Mammography	MESA-storage-B (version)

To create the storage directory:

1. Set the environment variable $MESA_STORAGE

2. Create the top level storage directory

3. mkdir %MESA_STORAGE%

4. Install the MESA-A storage files (all domains)

5. Install the MESA-B storage files (if necessary)

6. Edit the file %MESA_STORAGE%\ecg\ecg20304.xml. This file has URLs that refer to the server info-src. Replace the server name with the name of the system running the Tomcat server in all URLs, or make a hostname entry to map the name info-src to that system.

Runtime Notes

There are environment variables that need to be set when you run the test scripts. These are discussed in previous sections of the document and listed again in the table below.

Variable	Value
MESA_TARGET	D:\mesa (or another value of your choosing)
MESA_STORAGE	D:\mesa\storage (or another value of your choosing)
PATH	should include %MESA_TARGET%\bin and the path to perl
JAVA_HOME	D:\jdk1.3 (or another value of your choosing)
JAR_DIRECTORY	%MESA_TARGET%\lib
MESA_SQL_LOGIN	ctn (or other login of your choosing)
MESA_SQL_PASSWORD	ctn (or other password of your choosing)
MESA_SQL_SERVER_NAME	The name of installed SQL Server. This is not LocalServer. The default chosen by Microsoft is the hostname of your computer. Please check to be sure.
SQL_ACCESS	LocalServer:ctn:ctn (consistent with values above)
MESA_OS	WINDOWS_NT (use this value; do not substitute, even on XP and 2000 systems)

Installation Test: MESA Class A Tests

Beginning with the 10.3.0 release, we have added an installation test to make sure that variables are set properly and the databases are installed. All actors tested with the MIR MESA software should run the tests documented in this section:

MESA Test 1: Installation Test

MESA Test 1 examines environment variables, some folders in the MESA_STORAGE area and checks that the databases can be opened by the MESA applications.

Instructions

To run this test, follow these steps using a DOS window or terminal emulator:

1. Set the current directory to $MESA_TARGET/mesa_tests/common/actors/all

2. Run the test script as follows:

   perl 1/eval_1.pl

Evaluation

The output of test 1 will be stored in 1/mir_mesa_1.xml. Examine the file. There will be several warning messages. The installation test is complete when the mir_mesa_1.xml file contains no error messages and will indicate "Pass".

When the mir_mesa_1.xml file shows no error messages, submit that file to the Project Manager for evaluation. Upload that file into the Kudu or Gazelle tool as appropriate.

Do not email this file to the Project Manager unless you are looking for support help with installation problems.