spacer spacer spacer
spacer spacer spacer
spacer
NASA Jet Propulsion Laboratory, California Institute of Technology Vertical Bar + NASA Homepage

+ NASA en Español

+ Contact NASA

Use and Operation

The Label Template Design Tool (LTDTool) provides a Graphical User Interface (GUI) enabling users to design PDS label templates. This release of the tool allows templates to be created from scratch, from built-in templates or from existing templates and labels that the user may have available.

This section describes how to use LTDTool. The following topics can be found in this section:

Note: The command-line examples in this section have been broken into multiple lines for readability. The commands should be reassembled into a single line prior to execution.

Tool Setup

In order to execute LTDTool, the user's environment must first be configured appropriately. This section describes how to setup the user environment on UNIX-based and Windows machines. In addition to reassembling the command-line examples into a single line as mentioned above, the commands for setting environment variables must not contain space or line continutation characters in the value for the variable.

UNIX-Based Setup

This section details the environment setup for UNIX-based machines providing four different methods:

  • Specify the Shell Script on the Command-Line
  • Set the CLASSPATH Environment Variable
  • Specify the CLASSPATH on the Command-Line
  • Specify the Jar on the Command-Line

Specify the Shell Script on the Command-Line

The preferred method is to specify the shell script, LTDTool , on the command-line. Setting the PATH environment variable to the location of this script, enables the shell script to be executed from any directory location on the user's machine.

The following command demonstrates how to set the PATH environment variable, by appending to its current setting.

[node:~] setenv PATH ${PATH}:\
$HOME/ltdtool-1.0.0/bin
        

The tool can now be executed via the shell script as demonstrated in the following example:

[node:~] LTDTool <command-line arguments>
        

Set the CLASSPATH Environment Variable

An alternative method is to set the CLASSPATH environment variable. The following commands demonstrate how to set this variable, by appending to its current setting.

The first example and preferred method for setting the variable, appends t he executable jar file found in the bin directory:

[node:~] setenv CLASSPATH ${CLASSPATH}:\
$HOME/ltdtool-1.0.0/bin/ltdtool-1.0.0-app.jar

[node:~] echo $CLASSPATH
        

The second example separately appends the dependent jar files, found in the lib directory:

[node:~] setenv CLASSPATH ${CLASSPATH}:\
$HOME/ltdtool-1.0.0/lib/antlr-2.7.6.jar:\
$HOME/ltdtool-1.0.0/lib/commons-cli-1.0.jar:\
$HOME/ltdtool-1.0.0/lib/commons-collections-3.1.jar:\
$HOME/ltdtool-1.0.0/lib/commons-configuration-1.2.jar:\
$HOME/ltdtool-1.0.0/lib/commons-io-1.2.jar:\
$HOME/ltdtool-1.0.0/lib/commons-lang-2.1.jar:\
$HOME/ltdtool-1.0.0/lib/commons-logging-1.0.3.jar:\
$HOME/ltdtool-1.0.0/lib/product-tools-1.1.2.jar:\
$HOME/ltdtool-1.0.0/lib/ltdtool-1.0.0.jar

[node:~] echo $CLASSPATH
        

The second command in both of the examples above, will display the current value of the CLASSPATH variable. Please note that the value for the CLASSPATH variable may not contain space characters. Once the CLASSPATH is set, the tool can be executed with the following command:

[node:~] java gov.nasa.pds.ltdt.LTDTool <command-line arguments>
        

Specify the CLASSPATH on the Command-Line

An alternative method to setting the CLASSPATH variable is to specify the java.ext.dirs Java property on the command-line when running the tool each time. This is done by passing the property via the Java "-D" flag as demonstrated in the following example:

[node:~] java -Djava.ext.dirs=$HOME/ltdtool-1.0.0/lib \
gov.nasa.pds.ltdt.LTDTool <command-line arguments>
        

Specify the Jar on the Command-Line

Another alternative method is to specify the executable jar file on the command-line when running the tool each time. This is done by passing the jar file specification via the Java "-jar" flag as demonstrated in the following example:

[node:~] java -jar \
$HOME/ltdtool-1.0.0/bin/ltdtool-1.0.0-app.jar \
<command-line arguments>
        

Windows Setup

This section details the environment setup for Windows machines providing four different methods:

  • Specify the Batch File on the Command-Line
  • Set the CLASSPATH Environment Variable
  • Specify the CLASSPATH on the Command-Line
  • Specify the Jar on the Command-Line

Specify the Batch File on the Command-Line

The preferred method is to specify the batch file, LTDTool.bat , on the command-line. Setting the PATH environment variable to the location of this file, enables the batch file to be executed from any directory location on the user's machine.

The following command demonstrates how to set the PATH environment variable, by appending to its current setting.

C:\> set PATH=%PATH%;\
C:\ltdtool-1.0.0\bin
        

The tool can now be executed via the batch file as demonstrated in the following example:

C:\> LTDTool <command-line arguments>
        

Set the CLASSPATH Environment Variable

An alternative method is to set the CLASSPATH environment variable. The following commands demonstrate how to set this variable, by appending to its current setting.

The first example and preferred method for setting the variable, appends the executable jar file found in the bin directory:

C:\> set CLASSPATH=%CLASSPATH%;\
c:\ltdtool-1.0.0\bin\ltdtool-1.0.0-app.jar

C:\> echo %CLASSPATH%
        

The second example separately appends the dependent jar files, found in the lib directory:

C:\> set CLASSPATH=%CLASSPATH%;\
c:\ltdtool-1.0.0\lib\antlr-2.7.6.jar;\
c:\ltdtool-1.0.0\lib\commons-cli-1.0.jar;\
c:\ltdtool-1.0.0\lib\commons-collections-3.1.jar;\
c:\ltdtool-1.0.0\lib\commons-configuration-1.2.jar;\
c:\ltdtool-1.0.0\lib\commons-io-1.2.jar;\
c:\ltdtool-1.0.0\lib\commons-lang-2.1.jar;\
c:\ltdtool-1.0.0\lib\commons-logging-1.0.3.jar;\
c:\ltdtool-1.0.0\lib\product-tools-1.1.2.jar;\
c:\ltdtool-1.0.0\lib\ltdtool-1.0.0.jar

C:\> echo %CLASSPATH%
        

The second command in both of the examples above, will display the current value of the CLASSPATH variable. Please note that the value for the CLASSPATH variable may not contain space characters. Once the CLASSPATH is set, the tool can be executed with the following command:

C:\> java gov.nasa.pds.ltdt.LTDTool <command-line arguments>
        

Another way of setting the CLASSPATH is via the Windows Control Panel . If viewing this document in PDF form, see the appendix for details on this method.

Specify the CLASSPATH on the Command-Line

An alternative method to setting the CLASSPATH variable is to specify the java.ext.dirs Java property on the command-line when running the tool each time. This is done by passing the property via the Java "-D" flag as demonstrated in the following example:

C:\> java -Djava.ext.dirs=c:\ltdtool-1.0.0\lib \
gov.nasa.pds.ltdt.LTDTool <command-line arguments>
        

Specify the Jar on the Command-Line

Another alternative method is to specify the executable jar file on the command-line when running the tool each time. This is done by passing the jar file specification via the Java "-jar" flag as demonstrated in the following example:

C:\> java -jar \
c:\ltdtool-1.0.0\bin\ltdtool-1.0.0-app.jar \
<command-line arguments>
        

Tool Execution

LTDTool can be executed in various ways. This section describes how to run LTDTool and how to generate reports, as well as the behaviors and caveats of the tool.

Command-Line Options

The following table contains command-line options available to LTDTool:

LTDTool Command-Line Options
-p, --project < path > Specify the project directory of a previously saved design session to be resumed.
-d, --dict < .full files > Specify the PDS compliant data dictionary(s) to be imported for use during the design session.
-c, --config < file > Specify a configuration file to set the default values for LTDTool.
-h, --help Display LTDTool usage.
-V, --version Display LTDTool version.

Running LTDTool

This section demonstrates some of the ways that the tool can be executed using the command-line option flags:

  • Initiate a Session from Scratch
  • Initiate a Session from a Previous Project
  • Initiate a Session with a Single Dictionary
  • Initiate a Session with Multiple Dictionaries
  • Changing Tool Behaviors With The Configuration File

Note: The command-line examples below are executing LTDTool via the batch/shell script. Alternatively, the java -jar or java gov.nasa.pds.ltdt.LTDTool c ommand can be used to execute the tool as mentioned in the Tool Setup section. Make sure the user environment is configured properly prior to calling the tool with your preferred method.

Initiate a Session from Scratch

The following command demonstrates initiation of a design session with no arguments:

[node:~] LTDTool
        

Initiate a Session from a Previous Project

The following command demonstrates initiation of a design session from a previously saved project:

[node:~] LTDTool -p /home/user/template1/
        

Initiate a Session with a Single Dictionary

The following command demonstrates initiation of a new design session with the import of a single data dictionary:

[node:~] LTDTool -d pdsdd.full 
        

Initiate a Session with Multiple Dictionaries

The following command demonstrates initiation of a new design session with the import of a multiple data dictionaries:

[node:~] LTDTool -d pdsdd.full, localdd.full 
        

Changing Tool Behaviors With The Configuration File

A configuration file can be specified on the command-line to change the default behaviors of the tool and to also provide users a way to initiate a design session with a single flag. For more details on how to setup the configuration file, see the Using a Configuration File section.

The following command demonstrates initiation of a design session using a configuration file:

[node:~] LTDTool -c config.txt
        

Using a Configuration File

A configuration file is used to set the default behaviors of the tool. It consists of a text file made up of keyword/value pairs. The configuration file follows the syntax of the stream parsed by the Java Properties.load(java.io.InputStream) method.

Blank lines and lines which begin with the hash character "#" are ignored. Values may be separated on different lines if a backslash is placed at the end of the line that continues below. Escape sequences for special characters like a line feed, a tabulation or a unicode character, are allowed in the values and are specified in the same notation as those used in Java strings (e.g. \n, \t, \r).

Since backslashes (\) have special meanings in a configuration file, keyword values that contain this character will not be interpreted properly by LTDTool even if it is surrounded by quotes. A common example would be a Windows path name (e.g. c:\template1). Use the forward slash character instead (c:/template1) or escape the backslash character (c:\\template1).

Note: Any flag specified on the command-line takes precedence over any equivalent settings placed in the configuration file.

The following table contains valid keywords that can be specified in the configuration file:

Keyword Associated Flag Valid Value(s)
ltdtool.project -p Specify previously saved project directory.
ltdtool.dict -d Specify dictionary files.

The following example demonstrates how to set a configuration file:

# This is a LTDTool configuration file          

ltdtool.project = /home/user/template1/
        

This is equivalent to running the tool with the following flags:

-p /home/user/template1/
        

The following example demonstrates how to set a configuration file with multiple values for a keyword:

# This is a LTDTool configuration file with multiple values

ltdtool.dict = pdsdd.full, localdd.full
        

This is equivalent to running the tool with the following flags:

-d pdsdd.full, localdd.full
        

The following example demonstrates how to set a configuration file with multiple values that span across multiple lines:

# This is a LTDTool configuration file with multiple values
# that span across multiple lines

ltdtool.dict = pdsdd.full, \
             localdd.full
        

Tool Interface

The Graphical User Interface (GUI) of LTDTool allows the user to design one label template per session. After launching the tool with one of the methods described in the Tool Execution section above, the following window should appear on the user's desktop:

The main window of the tool consists of the following panes:

  • Template Editor

    This pane contains the active label template for the current design session. This pane is populated through the Create New Project or Open Project menu options under the File menu.

  • Validation Status

    This pane contains the validation report from the last request to validate the active label template. This pane is populated through the Validate menu option under the Tools menu.

  • Data Dictionary Listing

    This pane contains the objects, elements or both from the PDS compliant data dictionaries that have been imported through the Import menu option under the Data Dictionary menu.

  • Definition Details

    This pane contains the definition of the object or element currently highlighted in the Data Dictionary Listing pane. In an effort to alleviate the need to horizontally scroll in this pane, the < CR > < LF > characters have been stripped from the object and element descriptions. Descriptions that contain paragraph breaks and bulleted lists will be a little harder to read without the added white space.

The main window also consists of the following menus:

  • File
    • Create New Project...

      This menu option displays a dialog window enabling the user to create a new project from one of the provided templates in order to initiate a design session. The user may also create a new project by opening another label or template file from disk from within this dialog window. The user will be prompted to save any modifications made to the current project.

    • Open Project...

      This menu option displays a dialog window enabling the user to open a previously saved project in order to initiate a design session. The user will be prompted to save any modifications made to the current project.

    • Save Project

      This menu option saves the current state of the design session in the current project directory.

    • Save Project As...

      This menu option saves the current state of the design session in a new project directory. The name specified for the project becomes the of the directory where the project files will reside.

    • Close Project

      This menu option closes the project associated with the current desi gn session. The user will be prompted to save any modifications made to the project.

    • Export Template...

      This menu option exports the label template associated with the current design session to a file and directory specified by the user.

    • Export WDD...

      This menu option exports the Working Data Dictionary (WDD) associated with the current design session to a file and directory specified by the user.

    • Print

      This feature has not been implemented yet.

    • Quit LTDTool

      This menu option exits the tool application. The user will be prompted to save any modifications made to the current project.

  • Edit

    This menu consists of the standard options (Undo, Redo, Cut, Copy, Paste and Select All) which function as they do in any other application.

    There is one slight quirk regarding the use of the Undo function when it is performed immediately following the use of the Reformat function. All of the changes related to the reformatting of a template are considered one change when undoing them, but there is an intermediate step where the template is blanked out thus requiring the Undo function to be performed a second time to return the template back to its original format.

  • Dictionary
    • Import...

      This menu option imports a PDS compliant data dictionary from a file.

    • Add Object...

      This menu option adds a new object definition to the Working Data Dictionary (WDD) for the current design session.

    • Add Element...

      This menu option adds a new element definition to the Working Data Dictionary (WDD) for the current design session.

    • Modify Object/Element...

      This menu option modifies the currently selected object or element definition from the Data Dictionary Listing pane and adds or modifies it in the Working Data Dictionary (WDD) for the current design session.

  • Tools
    • Validate

      This menu option generates a test label from the active label template and submits it for validation. The resulting validation report is displayed in the Validation Status pane. Because the substitution variables are replaced with representative values, some the validation messages may reference label content that was not part of the original template.

    • Reformat

      This menu option reformats the active label template by aligning the equal signs, properly indenting nested objects/elements and inserting appropriate spacing after comments.

  • Help
    • About LTDTool

      This menu option displays a message dialog detailing the current version of the tool along with the build date and copyright statement.

Common Errors

At this point in development there is a single common error that several users have encountered. The error is as follows:

[node:~] java gov.nasa.pds.ltdt.LTDTool ...
Exception in thread "main" java.lang.NoClassDefFoundError:
gov/nasa/pds/ltdt/LTDTool
      

The actual class name may vary but the above error is the result of the CLASSPATH environment variable not being set correctly . Verify that the variable contains all of the specified jar files and that there are no space characters in the value. See either the UNIX-Based Setup or Windows Setup section for details.

Mac OS X Quirks

There a couple of quirks to be aware of when executing LTDTool on the Mac OS X platform. The first is that the Max OS X platform provides the standard menu bar at the top of the desktop for Java applications. The Quit option from that menu should not be used to quit the application. Use of that Quit option will cause the application to exit without prompting the user to save any modifications to the current project. Please use the Quit option from the File menu within the LTDTool window which prompt the user to save any modifications and exit the application properly.

The other quirk is related to the fact that each line in a label template should be terminated with a combination of the < CR > < LF > (carriage return and line feed) characters, which is a DOS/Windows artifact. The effect of this is that there appears to be an extra space at the end of each line in the label template. Before appending any content to a line, make sure the cursor is placed immediately after the last visible character in the line. The quirk is that if content is appended on a line after the < CR > < LF > characters, it will get moved to the next line when the Reformat function is performed.

FirstGov Logo
+ Freedom of Information Act

+ NASA 2003 Strategic Plan

+ NASA Privacy Statement, Disclaimer, and

   Accessiblity Certification


+ Copyright/Image Use Policy
NASA Logo
Curator: Emily.S.Law

NASA Official: William Knopf

Last Updated: 24 March 2008

+ Comments and Questions
spacer
spacer spacer spacer
spacer spacer spacer