DS1 FEI 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 geared for DS1. The Command Line Utilities Reference should be reviewed for the complete set of FEI command line utilities.

Each FEI command is wrapped as it's utility program so the commands appear to be an extension of your shell envorionment. Each FEI command start with a capital letter, List, for example; and each command is spelled out. If you don't like using the full names or using the convention of starting with a capital letter, create a set of aliases to make you own commands. We could use just the lower case letter "l" for List. Now typing the command l test will list all the files in the test file type:

UNIXprompt > alias l List
UNIXprompt > l test

Just be careful not to use a command that's already defined. Many systems have a "delete" comman d for example, so that's a poor choice for the FEI "Delete" command. (Separating FEI commands from other commands executed from a command window was the rational for starting each FEI command with a capital letter.)

All FEI commands, with the exception of FileTypes, take a file type as the first argument and most of the commands have additional parameters.

Learning Which FileTypes are Available

The files are generated by MIPL Real-Time for DS1 and made available in FEI within seconds of generation. 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 > FileTypes

Which returns 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
	
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 Tar distribution and can be found in $FEI/misc). 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 Stand Alone FEI Client Installation Notes (README) for instructions on setting up the environment or contact Pam Woncik pjw@jpl.nasa.gov for help.

Learning Which FEI Commands are Available

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

UNIXprompt > Fei

Which returns the following:

FileTypes
Lists the file types in your local FEI domain files.

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

Replace
Like Add, but will replace the file if it already exists in FEI.

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

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

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

Display
Writes the contents of a file to STDOUT.

ListAndGet
Combines both list and get functions in an interactive mode.

Subscribe
A subscription service that delivers the file to you.

Delete
An interactive utility that lists files which you can delete.

Rename
Rename a file within a file type.

FileMaker
A testing tool. Creates test files and sends them to FEI.

MakeClean
Deletes all files for a file type.

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

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

UNIXprompt > List

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, List, ListAndGet, and Get.

List Command
The syntax for the List command is:
List <file type> ['<file name expression>'] {[since <date-time>] [long]}
List 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 backets} 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 epression to FEI, the expression must be enclosed by quotes. This is true for the List command and the Get and ListAndGet 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 reqular 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 > List 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 List 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 inclue a file name expression in the command as well.
UNIXprompt > List 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 > List test long since 1998-10-21
    1.  1998-294T13:19:20.736,           36, test_4
	
Get Command

Note: Before you get any files, make a new subdirectory (e.g. "fei_test") and work from there. Get will retrieve files into your current directory, so be sure to change directories (cd) to the location you wish to write the files before executing the Get command.
The syntax for the Get command is:
Get <file type> ['<file name expression>'] {[since <date-time>] [replace|version]}
or Interactive Mode:
Get <file type> {[encrypt] [crc] [compress] [(replace|version)]}
Get 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 > Get 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. Get has an interactive mode, so without the file name expression, Get 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 > Get 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 > Get test test_file.1 replace
got "test_file.1"
UNIXprompt > Get 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 Get command line, and it remains in effect for the entire session.
UNIXprompt > Get 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"
ListAndGet Command

The syntax for the ListAndGet command is: ListAndGet <file type> ['<file name expression>'] {[since <date-time>] [encrypt] [crc] [compress] [replace|version] [long]}
The ListAndGet (obviously) combines the List and Get functions allowing you to see (List) the files avaliable but select (Get) only certain files.
For example List all of todays 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 > ListAndGet 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 Subscribe command is:
Subscribe <file type> {[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>

Subscribe 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. Subscribe 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 Get command, Subscribe will only write to your current directory, so you must change directories (cd) to the loacation you wish to write the files before starting your subscription. Also, Subscribe 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 DS1 Subscriptions

A sample subscription script, and options files ( partial.options, complete.options, complete.csh, place your cursor over these links and hold the shift key while clicking your left mouse button to download these files) have been provided for DS1. With minor changes these scripts will probably work for all users. Contact Pam Woncik pjw@jpl.nasa.gov for information on automating these subscriptions 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 forgound, the subscription process will terminate when you terminate the window (or log off the machine). If you submit a subscription to the forground by accident (forget to put & at the end of the line), simply use <control-c> to kill the subsciption 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 for each of the DS1 file types. 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 an 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 > Subscribe ds1MicasComplete using /usr/local/fei/ds1/complete.options &
UNIXprompt > Subscribe ds1MicasComplete restart using /usr/local/fei/ds1/complete.options &
If the options file is not in the current directory, you must include the absolute path to the file.

Copyright © 1997 The California Institute of Technology