FEI Version 3 - Quick Start Utilities Tutorial

The reader should have first reviewed the Kerberos Tutorial and understand that having a valid kerberos ticket is required before using FEI.

Only some of the most common FEI command line utilities are described in this Tutorial. The Command Line Utilities Reference should be reviewed for the complete set of FEI command line utilities. And the FEI Brief and FEI Full Overviews should be reviewed if you are not already familiar with FEI Version 3.

Each FEI command is wrapped as it's utility program so the commands appear to be an extension of your shell environment. Each FEI command is prefixed with fei and can be entered in "camel notation" or all lower case: feiList or feilist, for example. Camel Notation is used in all documentation to make it easier to read.

Most FEI commands (exceptions feiFileTypes, feiCheck take a file type as the first argument and most of the commands have additional parameters.

Learning Which File Types are Available

Files generated in MIPL are made available via FEI within seconds of generation. The files are stored or categorized into FEI file types. When retrieving or adding files to FEI you specify the file type it is categorized by and do not need to know the physical location of the data as you do when transferring data using ftp.
To get a simple list of file types in your current FEI domain (categories of data you have access to from your site), type the FEI command:

UNIXprompt > feiFileTypes

This command might return something like the following:
Copyright 1997, The California Institute of Technology. All rights reserved.
FEI API Version 3.0.0, Sep 11, 1997

File types in "feiDomain"
ds1Complete                       ds1MicasComplete              
ds1MicasPartial                   ds1Partial                    
ds1NavComplete                    ds1NavPartial                 
test				  casIss
casVims				  m98_ops_aux_files            
m98_ops_mosaic                    m98_ops_pio_prod             
m98_ops_rac_cahv                  m98_ops_rac_edr              
m98_ops_sci_prod                  m98_ops_ssi_cahv             
m98_ops_ssi_edr                   m98_ops_tiepoint             
m98_ops_xyz                       m98_ops_corr_disparity       
m98_ops_vrml                         
	
This command serves as a quick reminder of the file types available, but does not describe them in any detail.
The first three lines show copyright and FEI version information. Following that is the name of the FEI domain file you are using (this file has been distributed with the FEI Client distribution and can be found in $FEI). Following that are two columns displaying the names of the file types in the domain.
Note: If this command didn't work, your FEI environment could be incorrect. Review the FEI V3 README Installation Notes for instructions on setting up the environment or contact the FEI Administrator for your project (Thuy Nguyen for Cassini. Pam Woncik for Mars Missions, GLL, or DS1) for help.

Learning Which FEI Commands are Available

Type the following command to get a quick list of FEI commands:

UNIXprompt > feiHelp

Which returns the following:

feiFileTypes or feifiletypes
Lists the file types in your local FEI domain files.

feiAdd or feiadd
Add a file to FEI. Two modes: command line and interactive.

feiReplace or feireplace
Like Add, but will replace the file if it already exists in FEI.

feiAccept or feiaccept
Takes a list of file names from STDIN and adds or replaces them in FEI.

feiList or feilist
Lists the files in FEI. Optional file name expression and/or date-time.

feiGet or feiget
Gets files from FEI. Optional file name expression and/or date-time.

feiDisplay or feidisplay
Writes the contents of a file to STDOUT.

feiListGet or feilistget
Combines both list and get functions in an interactive mode.

feiNotify or feinotify
A subscription service that just displays the names of new files.

feiSubscribe or feisubscribe
A subscription service that delivers the file to you.

feiDelete or feidelete
An interactive utility that lists files which you can delete.

feiRename or feirename
Rename a file within a file type.

feiFileMaker or feifilemaker
A testing tool. Creates test files and sends them to FEI.

feiMakeClean or feimakeclean
Deletes all files for a file type.

==> Type a command with no arguments to see its syntax.

The last line displayed (the one beginning with ==>), means you can get an individual command's syntax by just typing the command with no arguments, for example simply typing feiList at the command line:

UNIXprompt > feiList

Commands To List And Get Files

Finding out which files are in FEI and acquiring those files are the two most common user activities. The three most common FEI utilities used to do that are, feiList, feiListGet, and feiGet.

feiList Command
The syntax for the feiList command is:
feiList <file type> ['<file name expression>'] {[since <date-time>] [long]}
feiList returns a list of file names from FEI that are stored in a give file type. Arguments in <angle backets> are names you supply, other words are keywords. An argument in [square brackets] is optional. The list of arguments in {curly brackets} are order independent, meaning you can change their order on the command line and the command should still be able to make sense of them.
As is the case with most FEI commands, the first argument is the file type. The second argument is a file name expression, which is optional. The rest of the arguments are keywords or keyword-value pairs that provide additional information to the command.
A file name expression can be a complete file name or a regular expression, such as part of a file name with one or more asterisk for wildcards (e.g "ATLOAPS*\.pds*"). Note the file name expression is surrounded by quotes when regular expressions are used. This is to prevent the local shell from expanding the expression into a set of file names - which may or may not work depending on what is in you local directory. We want the list generated by FEI, not by the local shell, so the quotes are needed.
So whenever sending a file name expression to FEI, the expression must be enclosed by quotes. This is true for the feiList command and the feiGet and feiListGet commands. Some examples are:

The file name expression "file1" is exactly file1. The expression "file*" is any file name starting with "file...", like file1, file.text, fileName, and so on.
The expression "[fF]ile" is either file or File.
The expression "ATLOAPS*\.pds*" is any file starting with ATLOAPS, followed by zero or more characters, numbers or special characters, followed by a .pds (the period being part of the filename verses a regular expression thus escaped with the backslash \ character first), followed by zero or more characters, numbers or special characters. Files named ATLOAPS003.pds#1, ATLOAPS003.pds#1.mdata, ATLOAPS003.pds#2, ATLOAPS003.pds#2.mdata could be returned when using this expression.
List command Examples:
UNIXprompt > List test
test_file.1
test_file.2
test_file.3
test_4
If we include the "long" keyword, the listing will include the date/time the file was modified in FEI (added, replaced, ...) and the size of the file along with the file name.
UNIXprompt > feiList test long
    1.  1998-264T13:24:18.020,          227, test_file.1
    2.  1998-264T13:24:18.286,           40, test_file.2
    3.  1998-264T13:24:18.466,           36, test_file.3
    4.  1998-294T13:19:20.736,           36, test_4
The file size is given in bytes. The feiList command returns the list sorted by date/time modified, not the filename. This is true whether the "long" option is specified or not.
We can include a file name expression in the command as well.
UNIXprompt > feiList test '*file*' long
    1.  1998-264T13:24:18.020,          227, test_file.1
    2.  1998-264T13:24:18.286,           40, test_file.2
    3.  1998-264T13:24:18.466,           36, test_file.3
	
If we just want to list new files, for example only the files that arrived today, include a date following the "since" keyword:
UNIXprompt > feiList test long since 1998-10-21
    1.  1998-294T13:19:20.736,           36, test_4
	
feiGet Command

Note: Before you get any files, make a new subdirectory (e.g. "fei_test") and work from there. feiGet will retrieve files into your current directory by default, so if you do not wish to specify the output path on the command line be sure to change directories (cd) to the location you wish to write the files before executing the feiGet command.
The syntax for the feiGet command is:
feiGet <file type> ['<file name expression>'] [pathname] {[since <date-time>] [replace|version]}
or Interactive Mode:
feiGet <file type> {[encrypt] [crc] [compress] [(replace|version)]}
feiGet will retrieve a specific file, or group of files denoted by a file name expression, in a give file type from FEI to your current directory.
UNIXprompt > feiGet test '*'
got "test_file.1"
got "test_file.2"
got "test_file.3"
got "test_4"
	
We had to include a file name expression, '*', to get back all of the files, but we didn't have to do that with list. feiGet has an interactive mode, so without the file name expression, feiGet enters that mode, shown later .
If we execute the last command again, we get a different result because the files you want to get already exists in the local directory, and FEI won't overwrite a file unless you give explicit instructions:
UNIXprompt > feiGet test '*'
Skipping file 'test_file.1', since it already exists.
Skipping file 'test_file.2', since it already exists.
Skipping file 'test_file.3', since it already exists.
Skipping file 'test_4', since it already exists.
	
If we want the files anyway, we have two choices: write over them or make a new version of the existing file. To make a new version of a file, FEI adds a unique number string to the end of the existing file name.
UNIXprompt > feiGet test test_file.1 replace
got "test_file.1"
UNIXprompt > feiGet test test_file.1 version
got "test_file.1"
UNIXprompt > ls -1 test_file.1*
-rw-r--r--   1 pjw      users        227 Oct 21 15:42 test_file.1
-rw-r--r--   1 pjw      users        227 Oct 21 15:41 test_file.1.909009776
The preexisting "test_file.1" is now named "test_file.1.909009776".
Interactive mode is entered when no file name expression is entered for the command. In interactive mode you continue to enter commands until you type <enter> or <return> at the prompt. Notice that you can use file name expressions and include <date-time> values at the prompt. If you want files replaced or versions made of exiting files, that keyword must appear on the feiGet command line, and it remains in effect for the entire session.
UNIXprompt > feiGet test version
Press the <enter> or <return> key to exit.
Get: <file name expression> [<date-time>]
Get: test_file.1
got "test_file.1"
Get: test_file*
got "test_file.1"
got "test_file.2"
got "test_file.3"
feiListGet Command

The syntax for the feiListGet command is: feiListGet <file type> ['<file name expression>'] [pathname] {[since <date-time>] [encrypt] [crc] [compress] [replace|version] [long]}
The feiListGet (obviously) combines the feiList and feiGet functions allowing you to see (feiList) the files available but select (feiGet) only certain files.
For example feiList all of today's files and decide to get some of them. In this example we use the "long" keyword so the FEI file modification date and file size are included in the Listing. We also include the keyword "replace" so that existing files are overwritten. And finally use the "since" keyword to list only the files received today.
UNIXprompt > feiListGet test '*' since 1998-10-21 replace long
Press the <enter> or <return> key to skip file.
Type 'g' to get the file.

Get  1998-294T13:19:20.736,           36, test_4: g
got "test_4".
	
The listing returns one line at a time as a prompt. If you want the file, type a g next to the listing, if you don't want the file we just press <enter> or <return>. You can go through the entire list this way until the end, or exit early by entering <control-c>.

Subscription Sessions

The syntax for the feiSubscribe command is:
feiSubscribe <file type> [pathname] {[restart] [using ]}
Options: replace version logFile <file name> displayMessages bell mailMessageTo <email address> mailReportTo <email address> mailReportAt <list of times of day> limitMessages invoke <command>

feiSubscribe sets up a persistent connection with the FEI server and instructs the server to send you a copy of every new/updated file for a given file type. feiSubscribe will send every new/updated file for the file type specified, but with the use of the "options" available, the user can customize their subscription to be quite selective.
Like the feiGet command, feiSubscribe will write to your current directory by default if you do not specify the output [pathname]. Currently, feiSubscribe options are not passed on the command line, but are listed in a separate ASCII file (one option per line) and the name of the "option file" is provided on the Subscribe command line.

Setting Up Basic Subscriptions

You can obtain DS1 and Mars98 subscription related sample scripts and options files by putting your cursor over these links; hold the shift key while clicking your left mouse button and download these file to your local machine.
DS1 examples include:

A script to start DS1 subscription, ds1Subscription.csh
The options used for Partial fileTypes, ds1partial.options
The options used for Complete filetypes, ds1complete.options
A script called for each Complete file received, ds1complete.csh
Mars98 examples include:

A script to create Mars98 directories to store data received via FEI subscription makeFS.csh,
A script to start your Mars98 subscriptions, m98feiSub.csh
Example of simple options to apply to all subscriptions, m98.options
A script to kill all running subscriptions, m98killSubs.csh
A perl script invoked by the subscription, makelinks.pl
A script to run via cron to keep your subscriptions going, subscriptionCK.csh

With minor changes these scripts will probably work for all users on any project. Contact the FEI Administrator for your project (Thuy Nguyen for Cassini, Pam Woncik for Mars Missions, DS1 and GLL) for information on automating these subscription even further using kerberos batch capabilities.
Subscriptions should be submitted a background processes (put an & at the end of the command line). If submitted to the foreground, the subscription process will terminate when you terminate the window (or log off the machine). If you submit a subscription to the foreground by accident (forget to put & at the end of the line), simply use <control-c> to kill the subscription and start it again with the &. Or you can use the UNIX kill command with the processes PID.
Our sample subscriptions included the "restart" keyword which will cause subscriptions to pick-up where they left off if the connection to the FEI server is interrupted.
Also with the sample script are a number of options files. The options used are very basic, users may wish to review the Command Line Utilities Reference for information on other options they may wish to use. If options are used, they must be contained in a file and the file name appears on the command line following the keyword using. This is true in the case where we are restarting a session as well as when starting a new session:
UNIXprompt > feiSubscribe test using /usr/local/fei/options.test &
UNIXprompt >feiSubscribe test restart using /usr/local/fei/options.test &
If the options file is not in the current directory, you must include the absolute path to the file.

Last Updated September 30, 1999
Pamela Woncik pjw@jpl.nasa.gov