Before you install NeXtMidas for the first time, please familiarize yourself with the system documentation, software license and Java software requirements discussed in this introduction. You should be experienced with the concepts underlying the MIDAS signal processing family. Fundamental understanding of signal processing software is also recommended. All information, illustrations and specifications contained in this guide are based on the latest product information available at the time of publication.
These instructions assume the NeXtMidas software will be installed in a
directory referred to as $NMROOT
. Documentation for the
'SYS'
option tree (including release notes and explain files)
is available in $NMROOT/htdocs/nextmidas.html
. You can view a
full set of documentation after building the system tree in the section
titled Build the NeXtMidas Baseline.
Use of this software implies that you agree to the terms of
the NeXtMidas license ($NMROOT/nxm/sys/copyright.txt
). Please read the
copyright files in the root directory of each installed package before using it.
This document assumes a Java Software Development Kit (JDK, formerly called the J2SDK) is already installed on your system. NeXtMidas requires Java 1.5.x or later (non-beta version only). To see what specific version of Java is installed on your system, type:
<yourJavaHome>/bin/java -version
To install Java, go to java.sun.com and download the most recent JDK(non-beta version). Do not download the JRE. The Java executables do not need to be in your path to run NeXtMidas.
NOTE: For any text in this document containing the following
notation, you must substitute the appropriate update version number
for the notation: <version>
.
For example, if you are installing Version 2.8.0 of the NeXtMidas baseline, the following file name:
nxm<version>.zipbecomes:
nxm280.zip
IMPORTANT: (Windows Requirement Only)
NeXtMidas will NOT compile on Windows if there are spaces in the Java installation pathname. Therefore, the JDK must be installed in a path that contains no spaces. The default installation path for Java on Windows may look like this:
c:\Program Files\Java\JDK<version>
To ensure Java is installed without spaces in the pathname, select a Custom (instead of Typical) installation and Browse to change the installation path to:
c:\Java\JDK<version>
This section explains how to download and install the NeXtMidas code. It directs you through the build, test, and run commands to confirm successful installation. Throughout the instructions, TIPs and NOTEs provide guidance through possible obstacles. If you encounter any problems during or after installation, please check Troubleshooting Tips for solutions to common issues.
NOTE: The initial installation steps (Where to Get the NeXtMidas Code through Set NeXtMidas Environment Variables) require a System Administrator to install and configure the software. Once the variables are set and verified, you can run NeXtMidas on your own.
The NeXtMidas code is available at http://nextmidas.techma.com/. Choose a baseline version and select the appropriate platform (Unix or Windows) distribution file.
To install NeXtMidas, copy the archive file to the location where you wish
to put the top directory of the software tree. There is no "standard"
location, so for the purpose of this installation guideline, assume
the top directory is /opt/midas/nxm<version>
(Windows: c:\midas\nxm<version>
).
Unpacking NeXtMidas creates an nxm<version>
directory
(typically referred to as $NMROOT
) and puts all files beneath
it.
To expand the archive file in Windows, use the zip utility:
unzip nxm<version>.zip
To expand the archive file in Unix, use the tar
utility:
tar xzvf nxm<version>.tar.gz
To expand a JAR archive file (used for NeXtMidas snapshots) in Windows or
Unix, use the jar
tool (this is part of Java):
jar xvf nxm<version>.jar
NOTE: If this is the first time NeXtMidas is installed on this particular machine, you must proceed with First-Time Installation. Otherwise, skip to the section titled Set NeXtMidas Environment Variables.
These procedures explain how to establish a user's home and data directories, which are important the first time NeXtMidas is installed on a machine.
For each user, NeXtMidas writes the execution state files (user command history, etc.) to the HOME directory. Additionally, any user-specific NeXtMidas startup files should be located in the HOME directory. If the directory specified in HOME does not already exist, it should be created now. Remember, there can be no spaces anywhere in the path defined by HOME.
The default directories are defined in the
$NMROOT/nxm/sys/cfg/nmstartup.mm
configuration file.
You can either create these directories on your machine or make a copy
of nmstartup.mm
in your home directory and edit it to
contain the directories you want NeXtMidas to use (the file in your
home directory is automatically loaded by NeXtMidas and
overrides the default settings).
NOTE: You must configure nmstartup.mm
for your
directory structure. In Windows, if the data files are not on the same
drive as the NeXtMidas software you need to specify the drive
letter for each directory used.
The following steps establish default settings for the required directories:
c:\midas\data1
c:\midas\icedisk
mkdir -p /midas/data1
mkdir -p /midas/icedisk
TIP: Set the ownership of these directories appropriately.
For example, create a group called midas
in which all
users are a member. Then set the ownership of these directories to
be owned by the midas
group:
cd /
chgrp -R midas midas
chmod -R g+w midas
NeXtMidas expects to read and write data files for each user in the
AUX.1
directory (AUX.1
is the NeXtMidas
identifier for the first auxiliary, or user, directory). Therefore,
you need a directory for each user under the AUX.1
directory.
This example creates user directories for John Smith
(smithj
) and Sarah Kim (kims
) using the
default system directory (/midas/data1/
):
mkdir -p /midas/data1/smithj
mkdir -p /midas/data1/kims
NOTE: Set the ownership so the user owns their own directory.
chown smithj:smithj /midas/data1/smithj
chown kims:kims /midas/data1/kims
On Windows98, running nmstart.bat
causes an 'Out of
Environment' error. To fix this, edit the system
CONFIG.SYS
file to include the following line:
shell = c:\command.com c:\ /p /e:2048
This increases the environment size to 2048.
NeXtMidas requires several environment variables to be defined before
building or running the software. Create a script or edit your login
script to set the environment variable NMROOT
to point to
the top level directory where NeXtMidas is installed. For the purpose of
this installation guideline, let's continue to assume the top directory is
/opt/midas/nxm<version>
. You may also set up an alias
to easily start a session. Use the command sequence appropriate for your
system:
NeXtMidas requires the C-shell (either csh
or tcsh
). If the default shell is not the C-shell then
start the C-shell before using NeXtMidas.
Set the JAVAHOME
variable to point to the Java
installation directory:
setenv JAVAHOME /opt/jdk1.6.0_19
Set the NeXtMidas NMROOT
environment variable:
setenv NMROOT /opt/midas/nxm<version>
Optional: Alias nmstart
to simplify starting NeXtMidas:
alias nmstart 'source $NMROOT/os/unix/nmstart'
TIP: Verify the environment variables are set correctly:
ls $JAVAHOME
ls $NMROOT
As of NeXtMidas 2.8.3, a Windows Batch File is provided that may be used in place of manual Windows environment variable configuration. Click here for more information, or continue with the following tutorial in order to manually configure NeXtMidas environment variables for Windows.
Set the JAVAHOME
variable to point to the Java
installation directory:
set JAVAHOME=c:\java\JDK<version>
Set the NeXtMidas NMROOT
environment variable:
set NMROOT=c:\midas\nxm<version>
Set the user name (USER
) and the user's home directory
(HOME
):
set USER=user_nameNote that neither the user name or the user's home directory contain spaces.
set HOME=user_home_directory
Optional: Set NMSTART
to simplify
starting NeXtMidas:
set NMSTART=%NMROOT%\os\dos\nmstart.bat
Important Windows Note: All path names, user names and
directory names used for NeXtMidas can not have any spaces in them.
All the environment variables listed above should NOT CONTAIN
SPACES anywhere on the right side of the equals sign (=). The
section, First-Time Installation provides
more details on creating directories defined by USER
and HOME
.
TIP: Verify the environment variables are set correctly:
dir %JAVAHOME%
dir %NMROOT%
A sample batch script has been provided with the NeXtMidas
distribution that simplifies the configuration and startup of NeXtMidas.
The batch file is located at:
%NMROOT%\os\dos\runNeXtMidas.bat.sample
.
To use the batch file to run NeXtMidas, first copy the
%NMROOT%\os\dos\runNeXtMidas.bat.sample
file to
your C:\midas\nxm<version>
directory and rename the
file to runNeXtMidas290.bat
.
copy C:\midas\nxm<version>\os\dos\runNeXtMidas.bat.sample C:\midas\nxm<version>\runNeXtMidas290.bat
Open the newly copied runNeXtMidas290.bat
file with your
favorite text editor and replace JAVAHOME
and
NMROOT
values using the instructions below.
On line 13 of runNeXtMidas290.bat
, set the JAVAHOME
variable to point to the Java installation directory:
set JAVAHOME=c:\java\JDK<version>
On line 14 of runNeXtMidas290.bat
, set the NeXtMidas NMROOT
environment variable:
set NMROOT=c:\midas\nxm<version>
Once finished, you may simply run the runNeXtMidas290.bat
conveniently as a Windows shortcut, via Windows Explorer, or through
the DOS command prompt in place of configuring and typing NMSTART
.
C:\midas\nxm<version>\runNeXtMidas290.bat
To build the NeXtMidas software, you must start an initial session. Once
a session is started, build the system tree using the
"nm make
" command:
nmstart
nm make all
%NMSTART%
nm make all
(After running nmstart
a copyright message appears,
followed by "NeXtMidas not built yet.")
Notes for Building Native Code
The build scripts are configured for the local GNU C Compiler
(gcc
) to compile all the native code each time the
baseline is built. To use an alternate compiler, see the NeXtMidas User's Guide
for details.
The baseline ships with pre-compiled DLLs for the SYS
tree. For most users, these pre-compiled DLLs are sufficient.
However, if you are a Windows software developer and want to compile
the native code locally on your Windows machine, you need a copy of
the GNU C Compiler (gcc
) compiler to compile any
option trees that contain native code. For details on compiling
native code locally on Windows, refer to the appropriate section in
the NeXtMidas User's Guide.
Now that the system tree is built, you may view the NeXtMidas HTML documentation (including release notes and explain files) in a web browser by opening the NeXtMidas home page: $NMROOT/htdocs/nextmidas.html
Building the User-Contributed Library (UCL
) option tree not
only verifies the pre-ship test, but provides a software developer with a
template for building option trees. You may choose to design your own
directory structure or use the UCL
option tree as a
depository. To compile the UCL
, enter the NeXtMidas shell and
type:
nM> make all ucl
Your computer system is now ready to use NeXtMidas. To verify a successful
installation of NeXtMidas, enter the NeXtMidas shell (using
nm
) and run the automated confidence tests:
nm
nM> confidence
This runs a series of non-interactive PASS/FAIL tests and summarizes the
results. The confidence test is considered successful if the summary ends
with "ALL TESTS PASSED
."
NOTE: The following message indicates nmstartup.mm was not set to the right directory (see IMPORTANT note in the First-Time Installation section):
WARNING: CANNOT PERFORM TESTS WRITE PATH /MIDAS/DATA1/<USER> DOES NOT EXIST
Information to run a more interactive set of tests is located in the confidence explain file:
nM> help confidence
When you complete the test segment, exit the shell:
nM> exit
This section explains how to run the NeXtMidas software. If you get error messages, check Troubleshooting Tips about resolving common problems.
To enter the NeXtMidas shell type nm
. This puts you at the
nM>
prompt.
To exit the shell, type exit
at the nM>
prompt.
This simple example shows how to enter the shell, run a command and exit the shell:
user> nm
nM> plot apennyA separate window opens with a picture of President Lincoln on the front of a penny. Clicking on the
X
in the upper right
corner of the plot closes the window and returns you to the prompt.
nM> exit
To run the same plot apenny
command as a single
("one-shot") NeXtMidas command from the operating system prompt, precede
the command with nm
and a space:
user> nm plot apenny
To remove all NeXtMidas variables from the execution window (which were
created by the nmstart
script), type "nmend
" at
the prompt:
user> nmend
To restart NeXtMidas in the window, run nmstart
again:
user> nmstart
Installation Complete!
You installed NeXtMidas, ran the confidence test to verify the baseline content, brought up the NeXtMidas shell to run commands, terminated the NeXtMidas shell, and ran a one-shot command outside the shell. As a novice NeXtMidas user, you are ready to move on.
From the NeXtMidas homepage (
http://nextmidas.techma.com/), go to the NeXtMidas Help page or
view the local copy (which includes all installed option trees) at
$NMROOT/htdocs/help/index.html
. This on-line help system
provides an overview of NeXtMidas concepts and capabilities. Using
HELP/GUI
command is another simple way for beginners to learn
their way around NeXtMidas; this graphic interface lets anyone
look up a detail or two without interrupting their current NeXtMidas session.
user> nm
nM> help/gui
Advanced programmers who want to customize the standard NeXtMidas software should read the appropriate sections in the NeXtMidas User's Guide. It provides several enhancement features to tailor NeXtMidas for your specific needs.
This section provides tips for working around common problems that may occur during or following installation.
All standard distributions of Linux do not include Adobe fonts as defined
in the font.properties
file in the JDK. (The
font.properties
file is typically located in the
$JAVAHOME/jre/lib/
directory in the Linux JDK.)
Therefore, if you issue a PLOT command such as plot apenny
NeXtMidas displays a series of warnings regarding fonts not being found.
For example, it might say:
Font specified in font.properties not found
[--symbol-medium-r-normal--*-%d-*-*-p-*-adobe-fontspecific]
To eliminate the font warning message, edit the
font.properties
file in the JDK you are using and comment
out all references to Adobe fonts.
font.properties
as
font.properties.ORIG
cd $JAVAHOME/jre/lib
cp font.properties font.properties.ORIG
nedit
):
nedit font.propertiesPlace a pound sign (#) in front of each line in the file that contains "
adobe-fontspecific
" and then save the file.
NOTE: You may need to repeat this each time a new JDK is utilized.
It is suggested that the old version of the font.properties
file is backed-up to font.properties.ORIG
.
Since NeXtMidas 2.9.0, NeXtMidas recognizes the backslash ("\") as the start of an escape sequence. This could cause problems with existing Windows macros that have hard-coded a Windows path using backslashes as the path separator. This issue can be resolved in two ways:
nM> env set IOOptions +DisableEscapeSequences nM> env set DefaultTableFlags +DisableEscapeSequences
On some Windows platforms (specifically, Windows XP with JDK 1.4.1) you may see Java errors regarding creating, opening and/or reopening a registry file after installing NeXtMidas and logging in as a user. To fix the problem, the Administrator needs to run a Java demo application (part of the JDK 1.4.1 distribution from Sun) to automatically configure the Windows registry properly for Java.
As an Administrator, log in and use the Java2D demo located in the JDK distribution:
%JAVAHOME%\demo\jfc\Java2D
The demo, named Java2Demo.jar
, includes a
README.txt
file in its directory that explains how to run it.
After running the demo, the registry is properly configured for Java.
After the Administrator logs out, you can log in and run NeXtMidas as a
typical user without registry errors.
During application execution, you might see this message when an application starts:
Warning: Cannot convert string "MetaCtrl<Key>Insert" to type VirtualBinding
To eliminate the warning, update the X-Windows property database to remove the Motif default bindings:
user> xprop -root -remove _MOTIF_DEFAULT_BINDINGS
For large, memory-intensive applications (e.g. displaying large Midas
files with the LIST
command), you can improve runtime
performance by starting the Java interpreter with a larger amount of
memory.
The initial memory allocated to the Java Virtual Machine (JVM) is
increased from the default values by defining the operating system
environment variable NM_USER_JVM_FLAGS
:
setenv NM_USER_JVM_FLAGS "-Xms<init_memory>[k|m]"
set NM_USER_JVM_FLAGS=-Xms<init_memory>[k|m]
<init_memory>
specifies the initial size of
the memory allocation pool. By default,
<init_memory>
is specified in bytes. This value
must be a multiple of 1024 greater than 1 MB. Append the letter k or K
to indicate kilobytes, or m or M to indicate megabytes. The default
value is 2 MB.
The maximum memory size the interpreter uses for dynamically allocated
objects and arrays is increased by adding a JVM argument to the
NM_USER_JVM_FLAGS
environment variable:
setenv NM_USER_JVM_FLAGS "-Xmx<max_memory>[k|m]"
set NM_USER_JVM_FLAGS=-Xmx<max_memory>[k|m]
<max_memory>
specifies the maximum size
in bytes. This value must be a multiple of 1024 greater than 2 MB.
Append the letter k or K to indicate kilobytes, or m or M to indicate
megabytes. The default value is typically 64 MB.
Memory modifying arguments are combined in the
NM_USER_JVM_FLAGS
environment variable. These examples
increase both intial and maximum to 256 MB:
setenv NM_USER_JVM_FLAGS "-Xms256m -Xmx256m"
set NM_USER_JVM_FLAGS=-Xms256m -Xmx256m