3.0 Getting Started on LAS

3.1 Introduction

In order to use LAS, a user must have an established account on the desired computer and a modified login to access the LAS software. The modifications to a UNIX computer system login file are described in the LAS System Manager's Guide but should be checked with the system manager. These modifications can be made by the system manager or by a knowledgeable user via a text editor. All users should also verify that they have access to sufficient disk space. Since a single image can take anywhere from 10 to over 2 gigabytes, it is essential to establish access to disk space. It is possible to increase this allocation through the system manager.

The LAS system is being developed for UNIX environments. Knowledge of both the operating systems and system utilities is not necessary but will allow a user more flexibility and improve the user's ability to use LAS.

3.2 UNIX Environment

Additional detailed information on the UNIX environment can be found in any of the UNIX manuals that are available for the computer system.

3.2.1 UNIX Log In/System Assignments/Defaults

When the LAS user's UNIX account is established, certain system assignments and defaults are made. In addition, the default .login and .cshrc (or .profile) files (which are shell scripts) are put in the user's root directory. These shell scripts contain the necessary commands to assign the appropriate environment variables to access LAS, TAE, and the other LAS support libraries. In addition, it optionally can place a user directly into a LAS session when the user first logs in so that the user may run a session without having to interface with the UNIX operating system.

3.2.2 Basic UNIX Functions for the LAS User

There are several basic UNIX functions that the LAS user may wish to become familiar with before entering LAS.

The most basic of these is the ls command. This command lists the files in the current working directory or any other specified directory.

The second command is the cd command, invoked by cd <directory specification>. It allows the user to specify a new directory as the current working directory.

For example:

     % cd test/image
Detailed descriptions of these commands and other shell commands can be obtained by using the man command (for manual) while in a shell. The format is man followed by the command name. The command name is required because the command man will not list all the available commands. UNIX does not create multiple versions of the same file but simply overwrites the contents of the original file. Only the last set of parameter values saved will be available in a file, all other saves to this file will be gone.

3.3 Using the System

3.3.1 Logging on the System

In order to use any of the components of LAS, the user must first log on the host computer. Generally, the user is prompted for username, password, account, terminal type, and subsystem. The user is then placed in the host command interpreter mode. Once logged on, the user has the following two options:

3.3.2 Entering and Exiting LAS

To enter LAS, simply type the command las while in the host command interpreter mode, indicated by either the % or $ prompt in UNIX, or other defined system prompt. The user will be placed under the Transportable Applications Executive or TAE umbrella. The TAE user interface is described in detail later in Section 3. Depending on how the system manager has set up LAS on the computer system, a user will go into either a menu or command mode; in either mode, on-line help is available at any point by typing help. To exit from LAS, the user must type exit. This will exit TAE command mode and return to host command interpreter mode. Or alternatively, the user may enter logoff, in either command or menu mode, which will allow the user to exit from LAS and then log off the host computer system. Once the user is in TAE command mode (indicated by the LAS70> prompt), he or she may access the LAS modules in menu mode by typing menu or may access the LAS modules in tutor mode by typing tutor and a specific module name.

Example:

     LAS70> tutor pixcount
NOTE: LAS70> is the default TAE prompt. It may be changed by the system manager or a user may customize one for his/her own account (see Section 3.9).

The first-time user of TAE may want to run through the tutorial supplied by the TAE Support Office. It can be accessed by typing taetutor at the LAS70> prompt. There is also a LAS tutorial which may be accessed by typing nut (new-user tutorial) at the LAS prompt.

3.3.3 Using Host Commands under TAE

One of the features of TAE is that one may enter into the host's command interpreter mode while still running under TAE and execute commands which the host's command interpreter understands. An example would be using the editor in the UNIX shell.

3.3.3.2 Using UNIX Shell Commands under TAE

To execute a UNIX shell command while under TAE, the user types ush (for user shell) while in TAE command mode. The prompt _% (or _$ if the user is using the Bourne shell) will appear indicating that the user can type shell commands. To return to TAE, the user types exit or keys in a CTRL-Z sequence. The following are a few rules which apply to executing shell commands under TAE:

     _%  cd  /edc/applications/smith
See the UNIX manual for cd to get more information (that is, type man cd). The directory will always be set at the directory level the user was at when TAE was initiated, unless the catalog manager module cmset was used. The LAS catalog manager module cmset is the only way to switch directories permanently during a session. To use the cd command, the user must exit LAS, change directories, and re-enter LAS. Upon exiting from TAE, the user is always set back to the directory level where TAE was initiated.

3.3.4 User Resource Allocation

The LAS user can reserve and make use of special hardware. In order to provide efficient use of the resources available, it is necessary to allocate and schedule the special hardware needed. Typically, the user may reserve time for using the display terminals or having data ingested.

Long-term storage of large amounts of data under the user's directory on the computer system disks is discouraged. Users are encouraged to store on magnetic tape or to archive any data they are not currently using. LAS users should also be aware of their disk space and computer peripheral requirements before starting to process data.

3.3.4.1 Unix Disk File Handling

The UNIX operating system does not have the ability to link disk packs together under one user code. A utility, using the environment variable DATAPATH and a soft link, has been implemented in LAS to handle the situation when a particular user needs room on more than one disk. It physically laces images on disks named in DATAPATH and links them to the working directory by a soft link.

This utility also keeps track of the physical space on the disk so that two images being created at the same time do not allocate the same disk area. One of the "creates" will reserve the disk space and the other will be forced to utilize DATAPATH or to wait for disk space to become available.

Below is the syntax for setting up DATAPATH:

     %setenv DATAPATH "/edc/production/lams:/edc/production3/lams"
The colon is used to separate each of the directories.

NOTES:

  1. This currently only applies to images. The associated files are stored in the working directory.
  2. The directories specified in DATAPATH must exist.
  3. The first fit algorithm is used to determine which disk to use for a particular image.
  4. UNIX operating system commands must not be used when working with these images. For example, if the rm command is used to remove one of these images, the soft link will be deleted, but the physical file will not be deleted. Always use the cmdel function to remove images.

3.4 TAE Interface

3.4.1 Typical LAS Scenario

A LAS session starts when the user enters LAS from the computer system command mode by typing las. Then, depending on the system set-up, the user is prompted with a menu of LAS modules or with the TAE Command Language (TCL) prompt (indicated by LAS70>). In TCL, the user will either select an application module by tutoring on it, use TCL to execute the module directly in command mode, drop into the computer's operating system, or switch into menu mode. The two ways to execute a module directly while in TCL are: (1) enter the module name and the required parameters as a command string or (2) tutor the module, setting the parameters and executing the module. A user may use either menus or TCL interchangeably during the session. The LAS session ends when the user executes the logoff or exit command. The user may switch from menu mode to the TCL command mode by entering a c for command mode in response to the menu mode prompt. Similarly, the user may switch from the TCL command mode to menu mode by typing an m for menu in response to the TCL command mode prompt (LAS70>).

3.4.2 TAE Processing Options

3.4.2.1 Interactive Processing

A user interacting with LAS is considered either a menu user or a TCL user. A menu user invokes applications by locating and selecting them through a series of menus. Menu choices are either applications (that is, a process or a procedure, both known as "procs") to be executed, commands to be executed, or other menus to be displayed.

When an application is selected, TAE automatically enters tutor mode to prompt the user for the need ed parameters. The user may also enter tutor mode from TCL command mode by typing tutor and the module name.

For example:

     LAS70> tutor isoclass
In either case, the user will then be presented with a tutor display consisting of the module parameters and their descriptions. The user then enters values for the parameters by typing <parameter name>=<value>.

For example:

     ?print=lp
The user may obtain additional information on any parameter by typing help <parameter name>. Once all required values are given, the user types run and the module will execute. Tutor mode is probably the most common method of executing LAS modules. While in tutor mode, a user may receive help on individual parameters as well as the module itself, including Algorithm/Description, Error Messages, and User Notes by typing help *.

When a help command is typed in any mode, a help screen is displayed and the user may then request more help or return to normal operations. The types of help information available are:

Under normal tutor mode (screen), the user is presented with a series of screens or pages containing parameter names, descriptions, etc. There is a second type of tutor mode called noscreen mode. It is ideal for nonCRT terminals or CRT terminals not supported by TAE. Noscreen tutor simply presents the user with a list of parameters and a prompt. The user has all the normal options except paging. Noscreen tutoring may be set for the entire interactive session by typing:

     LAS70>let $tutor="noscreen"
or for individual modules by typing:

     LAS70>tutor-noscreen isoclass
Also, in TCL the user may execute a module as a command string in TCL command mode, but the user needs to know the module name and the parameter names and values.

The tutor mode and TCL command mode are described in detail in the TAE User's Reference Manual.

3.4.2.2 Noninteractive Processing

Noninteractive processing involves primarily three batch processing methods and a fourth method using a TAE script file. The batch mode includes using the TAE batch command,the TAE runtype command, a TAE proc file, and the enable-script command. LAS batch jobs generate files with .log extensions, with .log being the primary product of the batch run.

TAE batch Command

The first method of running batch mode uses the TAE batch command. Only one LAS module can be run at a time. The following example shows how a user might run the module list in batch mode.

Example:

LAS70>TUTOR LIST

(While in tutor mode, set the following parameter, save this setup to a file, and exit the module.)

IN=VALDEZ.LANDCOV

PRINT=LP

SAVE LIST

EXIT

Note the save list command creates the file list.par.

LAS70>TUTOR BATCH-SUBMIT

(While in tutor mode, type the following.)

PROC=LIST

SAVEFILE=LIST

RUNTYPE=BATCH

RUN

Note the savefile value (list) is from the save statement in the first segment of this example.

This creates list.job and submits it to batch queue. After the job is completed, a file called list.log remains; this file is the log or standard output file of the run. List.job is deleted after the job finishes, but list.log remains under the user's account.

TAE runtype Command

The second method uses the TAE runtype command. This method also creates the log file, proc.log. This command is useful when a user wants to run one LAS module in batch mode from command mode without saving the .par file. The saved parameter file from the first method could also be used to demonstrate the second method. The second method can be done in any one of the following ways:

LAS70> LIST |RUNTYPE=BATCH| VALDEZ.LANDCOV LP

or

LAS70> LIST |RUNTYPE=BATCH RESTORE=LIST|

or

LAS70> TUTOR LIST |RUNTYPE=BATCH|

(where the parameters for in and print were saved in a parameter file called list)

In the first example, a listing of the image valdez.landcov is printed to the line printer in batch mode. The second example uses the parameter file saved from a tutor session. The third example puts the user in a tutor session for list, but the module will be executed in batch mode.

TAE Procedure Proc File

The third method uses the TAE proc file. In this method the user sets up a proc file via the host editor (vi under UNIX) and then executes the proc in batch mode. Several LAS commands or modules can be strung together in the proc file. The proc file cannot have the same name as an existing module under LAS and must have the .pdf extension. This batch job creates a log file under the proc name; qlist.log is created by this method in the following example.

%vi  qlist.pdf 

procedure help=*

body

LIST IN=VALDEZ.LANDCOV +

PRINT=LP

PIXCOUNT-NO IN=VALDEZ.LANDCOV

end-proc

exit

LAS70> QLIST |RUNTYPE=BATCH|

This example produces the same results as the example in method 1 and 2.

TAE Script File

Another processing option uses a TAE script file. There are two ways to set up script files. The first way is to use the host editor to create a file of LAS modules as they would appear if the user was running in command mode.

%vi  test.scr

LIST IN=VALDEZ.LANDCOV

PRINT=LP

PIXCOUNT-NO IN=VALDEZ.LANDCOV PRINT=LP

exit

In this example, a script file is created called test.scr and executed interactively via the enable-script command. Script files may only be run interactively.

3.4.3 TAE Utilities

A TCL command line is either the invocation of a proc or a TAE intrinsic command. The following TCL intrinsic commands are most often used in TCL. These utilities are available on both VAX and UNIX computer systems; however, the delgbl utility is currently not available under UNIX operating systems. The TAE User's Reference Manual describes the commands in more detail.

Command-Description

abort-Terminate current proc (after CTRL-C interrupt)

batch-Batch queue manipulation

continue-Continue (after CTRL-C interrupt)

ush-Switch to the UNIX shell

defcmd-Define command

delcmd-Delete command definition

delgbl-Delete global

display-Display variable value

disable-Disable logging

enable-Enable logging, script

exit-Terminate TAE

help-Obtain help information

let-Assign a value to a variable

logoff-Logoff TAE

menu-Enter menu mode

setlib-Set library search order

show-Show status

tutor-Enter tutor mode

3.5 LAS Alias Commands

Aliases or strings are assigned by a user to be used as abbreviated names of images or files with long or complicated names. Aliases can be from one to eight characters in length and can include spatial or spectral windowing information. Aliases are only expanded for those parameters describing input or output filenames. When a dollar sign ($) is encountered in such a name, the alias name beginning with $ is replaced by the alias text string. If the alias name $ny had been created for the text newyork, then a filename parameter specification containing the string $ny would be expanded to newyork. When one of these filename parameters requires a dollar sign in its specification that has nothing to do with an alias, it can be delimited by an additional dollar sign. For example, in=proj$$path would be interpreted as in=proj$disk[user.name]file.dat if path had been defined to be equal to disk[user.name]file.dat.

  • To assign an alias to a name, use the command in the format:

    CMALIAS-CREATE $quickie long.hard.to.remember.name

  • To use the alias, simply type your string preceded by a $ wherever you would normally use the name.

    IN=$quickie or IN="$quickie(100,100,512,512)"

  • To assign an alias to a spatial window specification, use the command cmalias-create in the format:

    CMALIAS-CREATE $win (1024,1024,1000,1000:1,2,3)

  • To use the alias, simply type your string preceded by a $ wherever you would normally use the window.

    IN=newyork$win

    --Upon execution, newyork$win will be expanded to newyork(1024,1024,1000,1000:1,2,3)

  • To delete an alias name, use the command cmalias-delete in the format:

    CMALIAS-DELETE $quickie

  • To delete all aliases associated with a specific image name, since you can assign more than one to a single image, use the command cmalias-delete in the format:

    CMALIAS-DELETE long.hard.to.remember.name

  • To change an existing alias name to a new alias, use the command cmalias-create and cmalias-delete as follows:

    CMALIAS-CREATE  $newquick   $quickie

    CMALIAS-DELETE $quickie

  • To list all existing alias names, use the command cmalias-list in the format:

    CMALIAS-LIST

    All aliases are stored in the cm subdirectory under the user's root name.

    3.6 Data Transfer

    LAS contains software that transfers data from tape to disk, disk to disk, or disk to tape. It handles many types of tape files in a variety of formats.

    Before running data transfers, users should verify that they have adequate disk and tape space to contain the output files that will be generated. The disk files handled by data transfer modules are compatible with LAS file format. LAS software also exists to transfer data between computer systems on a local area network. These modules are site specific and may not be available at your site. Contact your LAS system manager for more information. More details about data transfer are explained in the individual user's guides.

    Each computer represents data types such as integer and real*4 differently. The LAS input and output modules have the ability to convert data types from one computer representation to another. Many of the LAS modules also provide the ability to set or convert from one data type to another on the same computer system by use of the odtype parameter. The conversion from a higher (real) to lower (byte) data type is done by truncation and not scaling. Converting a real image to a byte image will set all pixel values below 0 and above 255 to 0 and 255, respectively. The map module should be used for rescaling of data.

    3.7 Command Syntax

    LAS is composed of several components; each has its own capabilities. Each of these components has a command interface, and this interface will serve as a starting point for defining the component's syntax.

    3.7.1 LAS/TAE

    The command syntax for LAS will be that syntax needed to run the LAS application modules which are run under TAE.

    Examples of sequences of terminal display screens that the user will see when using the command or tutor mode are given. The LAS module pixcount is used in these examples. A menu interface also exist that can be accessed by typing menu at the LAS prompt.

    LAS70> TUTOR PIXCOUNT (Accessing pixcount in tutor mode)

    LAS70>PIXCOUNT-NO IN="MADTOWN.TM(200,300,1024,1027:2)" + 
        PRINT=(TERM,LP,MADTOWN)(Accessing pixcount in command mode)
    

    LAS70> PIXCOUNT-NO |RUNTYPE=BATCH| IN="MADTOWN.TM(200 300 1024 1027:2)"+
            PRINT=(TERM,LP,MADTOWN) (Accessing pixcount in batch mode)
    

    3.7.2 Software Packages Interfaced with LAS

    In order to use SAS, ARC/INFO, or other software packages interfaced with LAS, a user should consult with the local system manager for access information to each specific system. LAS interfaces to these software packages through the labeled table (LT). In some instances, the use of the LT is hidden from the user as in the case of the gof2stat module. The user should be familiar with the manuals and documentation of the systems that he or she is transferring data between, especially each system's limitations or system requirements.

    3.8 Error Handling and Aborting Processes

    All LAS errors during the interactive LAS session (nonbatch) will be displayed on the terminal in a uniform format. A fatal error will abort the module that is currently being executed and control is passed back to TAE. LAS was designed to produce uniform error messages. The format for each error message is a key followed by a short description of the error. An example might be:

    [copy-read] "Error encountered reading from input file"

    The key is composed of a module or subroutine name followed by a dash "-" and a short descriptor of the error such as "read" for a read error. In the example, an error occurred reading a file in the LAS copy module. Further information on the error can be found by looking at the error message section of the user guide for the particular module. The user guide for any module may be viewed by typing help <module name>. All messages will be logged to the session log file; the command enable-log initiates the session logging and disable-log disables it. The session log or session history provides a record of the user's session. It contains a chronological listing of the modules run, the values of the module's parameters, and any informational or error messages that were generated. A session history is always created and is written into a file called session.tsl unless the user changes the $LOG global.

    A CTRL-C sequence suspends the currently running module. If the command abort is entered at the CTRL-C interrupt prompt, the module is aborted and the user will be sent back to the previous system status prior to the running of the module. The user may also use the help or continue commands at the CTRL-C interrupt. Help lists the processing choices at the interrupt while continue will restart the module at the point it was suspended.

    3.9 Procedure Definition Files

    TAE provides the ability for users to create their own procedure definition files (PDFs) or allows them to be modified using the computer system editor. Most users will find PDFs a convenient way of stringing together multiple LAS modules into a single module or for customizing their processing environments. The specified examples illustrate a ulogon and ulogoff PDF file. The ulogon.pdf sets several global variables using the let command and defines several commands with the defcmd command. The ulogoff.pdf disables session logging, freeing it to be printed. Appendix B contains a list of all the global variables used in LAS. Since the ulogon and ulogoff PDFs are run at the beginning and ending of a user's session, respectively, they are ideal for customizing a user's environment. Conversely, a user would need to type these commands at the start of a new session to have access to the same capabilities. The specified examples illustrate PDFs for exiting a LAS session and for computing a vegetative index for Landsat images, respectively. The details of the individual commands can be found in the TAE User's Reference Manual.

    
    procedure help=*

    REFGBL ($PROMPT,$MINMAX,$PRINTER)

    body

    LET $PROMPT="DR_LAS" LET $MINMAX="NO"

    LET $PRINTER="HP-L"

    defcmd pix, string="pixcount-no print=lp"

    putmsg-notrace "---------------------------","ulogon-msg"

    putmsg-notrace " Log enabled, printer=hp-1","ulogon-msg"

    putmsg-notrace " Defined commands are: pix","ulogon-msg"

    enable-log

    end-proc

    Example of ulogon PDF

    procedure help=*

    body

    ! Disable session history and print it

    disable-log

    print session.tsl

    end-proc

    Example of ulogon PDF

    PROCEDURE HELP=*

    REFGBL ($BECHO,$ECHO)

    BODY

    LET _ONFAIL = "RETURN"

    LET $ECHO = "YES"

    LET $BECHO = "YES"

    !Band 2 for MSS scene

    unary-sca in="xx(:2)" +

    out=temp1 +

    scoff=(a,b)

    unary-sca in=temp1 +

    out=temp2 +

    scoff=(a,b)

    cmdel-file temp1 n

    !Band 4 of MSS scene

    unary-sca in="xx(:4)" +

    out=temp3 +

    scoff=(a,b)

    unary-sca in=temp3 +

    out=temp4 +

    scoff=(a,b)

    cmdel-file temp3 n

    normd in=(temp2,temp4) +

    out=temp5 +

    odtype=byte +

    scalfact=100

    cmdel-file temp2 n

    cmdel-file temp4 n

    math-mul in="temp5 loc.mask" +

    out=xx7

    cmdel-file temp5 n

    END-PROC

    Example of a PDF which calculates a vegetative index

    3.10 Problem Reporting and Enhancement Requests

    Users encountering problems with the LAS software should file problem reports. Blank problem reports are available from the local LAS user representative or system manager. They should be filled out with the requested information and then returned to your LAS user representative for evaluation and resolution. The user should include with the problem report any pertinent information related to the problem such as printouts, hard copies of terminal displays, session histories, exact error messages, and the computer system on which the error occurred. Suggestions for enhancements to LAS modules or for new capabilities should be written up and submitted to the local person responsible for LAS. If a local site would like to do the implementation or do their own software development, they should use the standards established in the LAS 7.0 Programmer's Guide. Software adhering to these standards can then be reviewed and included in the baseline version of LAS. Computer software that does not meet these standards will be included in the LAS Contributed Library. The Contributed Library is distributed with LAS but is not supported and is made available under a "user beware" category. The guidelines and procedures for software development are described in detail in the LAS 7.0 Programmer's Guide.