NeXtMidas Installation Guide

Introduction

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.

Documentation

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.

Software License

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.

System Requirement

This document assumes a Java Development Kit (JDK) is already installed on your system. NeXtMidas requires Java 1.7.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.oracle.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 3.6.1 of the NeXtMidas baseline, the following file name:

nxm<version>.zip
becomes:
nxm361.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>

Installing NeXtMidas

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.

Where to Get the NeXtMidas Code

The NeXtMidas code is available at http://nextmidas.techma.com/. Choose a baseline version and select the appropriate platform (Unix or Windows) distribution file.

Open the NeXtMidas Distribution

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:

For tar.gz archive:
  tar xzvf nxm<version>.tar.gz (-or-)
  gunzip -c nxm<version>.tar.gz | tar xvf -

For tar.xz archive:
  tar xJvf nxm<version>.tar.xz (RHEL/CentOS 6+ using capital 'J' option) (-or-)
  unxz -c nxm<version>.tar.xz | tar xvf -

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.

First-Time Installation

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.

  1. Create HOME directories. (Windows only)

    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.

  2. Ensure NeXtMidas directories are created.

    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. Insert the following line in the file: debug on trace. 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:

    • Windows
      c:\midas\data1
      c:\midas\icedisk
    • Unix
      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:

      chgrp -R midas /midas
      chmod -R g+w /midas
  3. Create a data directory for each user.

    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/):

    • Unix
      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

Set NeXtmidas Environment Variables

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:

Build the NeXtMidas Baseline

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:

(After running nmstart a copyright message appears, followed by "NeXtMidas not built yet.")

Notes for Building Native Code

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

Build the User-Contributed Library (UCL) (OPTIONAL)

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> path add ucl 
nM> make all ucl

Test NeXtMidas

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

Run NeXtMidas

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:

  1. Start the shell.
    user> nm
  2. Plot a file.
    nM> plot apenny
    A 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.
  3. Exit the shell:
    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.

On-Line Help

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.

Troubleshooting Tips

This section provides tips for working around common problems that may occur during or following installation.

"font.properties not found" Error (Linux Only)

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.

  1. Save the original font.properties as font.properties.ORIG
    cd $JAVAHOME/jre/lib
    cp font.properties font.properties.ORIG
  2. Edit the file (you may use your favorite editor in place of nedit):
    nedit font.properties
    Place 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.

Invalid Escape Sequence Errors (Windows Only)

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:

  1. (Recommended) In each case that is causing issues, escape the backslash, e.g. the String "my\windows\path" should be written as "my\\windows\\path"
  2. Disable the functionality, both in the environment and in NeXtMidas Tables:
        nM> env set IOOptions +DisableEscapeSequences
        nM> env set DefaultTableFlags +DisableEscapeSequences

Improve Runtime Performance

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.

  1. Increase Initial Java Memory Size:

    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:

    • Unix
      setenv NM_USER_JVM_FLAGS "-Xms<init_memory>[k|m]"
    • Windows
      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.
  2. Increase Maximum Java Memory Size:

    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:

    • Unix
      setenv NM_USER_JVM_FLAGS "-Xmx<max_memory>[k|m]"
    • Windows
      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.
  3. Increase Both Initial Memory and Maximum Memory Size:

    Memory modifying arguments are combined in the NM_USER_JVM_FLAGS environment variable. These examples increase both initial and maximum to 256 MB:

    • Unix
      setenv NM_USER_JVM_FLAGS "-Xms256m -Xmx256m"
    • Windows
      set NM_USER_JVM_FLAGS=-Xms256m -Xmx256m