lib/libuif.a
User Input
The UNIX command line form of any TeraScan command is:
command param1=value1 param2=value2 ... file1 file2 ...
Besides command name, there are only two things found on the command line: parameters followed by files. Input files always precede output files on the command line. Parameters are simply named inputs to commands. If parameters are not (or are incorrectly) entered on the command line, users can be prompted for them by name. For example
master_file : char(255) ? [Master] z_variable : char( 15) ? z_index : int ( 1) ? [1] iso_values : real( 30) ? [0]
Prompts include the parameter name, the parameter datatype (char, int, or real), and a default value in brackets, if there is one. The prompt also includes either the maximum number of numeric values for an integer or real parameter, or the maximum number of characters allowed for a string parameter.
Parameters are classified as either NO_DEFAULT, HAS_DEFAULT, or OPTIONAL. These codes are defined in include/uif.h. Users must supply values for parameters with NO_DEFAULT. To accept the default value for a parameter that HAS_DEFAULT, a user enters a blank response. A blank response is entered on the command line as param= . Users are not prompted for an OPTIONAL parameter unless the parameter value was entered on the command line and was found to be erroneous. OPTIONAL parameters always have default values.
Each command is assumed to have one of the following forms, based on what files it expects to find on the command line. These forms are defined in include/uif.h.
FORM_00 0 files in 0 files out FORM_10 1 file in 0 files out FORM_01 0 files in 1 file out FORM_11 1 file in 1 file out FORM_0M 0 files in many files out FORM_M0 many files in 0 files out FORM_M1 many files in 1 file out FORM_MM many files in many files out
For example, a command that modifies a dataset in place will probably have form FORM_10 or FORM_M0. Commands with form FORM_MM either have a single output file or an output directory. This is similar to the UNIX cp command.
Users are prompted for files not (or incorrectly) entered on the command line. Input files are tested for existence. A command's prompt for files reflects its form, although each form does not have a unique prompt. The prompt includes a default response, if there is one, in square brackets. For example:
output file : char(255) ? [Coast]
Users can obtain help for a given parameter by answering a prompt with a ?. Similarly, users can escape to another program by responding ! followed by a program name. Consider the following example in which the user wants to create a new master_file in the midst of running another application:
master_file : char(75) ? [Master] !master
Special Parameter Formats
Standard formats exist for specifying date, time, latitude and longitude valued parameters ([] means optional, (*) means usual output format):
For example, 32 44 19.8 n, 32 44.33 N, and 32.739N are all equivalent latitudes.
Note that times and latitude/longitudes use different conventions. A latitude of 2N means two degrees north. A time of 2 means two seconds, not two hours.
User Output
All non-report user output, including file and parameter prompts, is directed to UNIX stderr and the user's session log, if one is enabled. All user inputs, including the command line and responses to prompts, are also echoed to the user's session log. A user's session log is defined by the UNIX environment variable SESSIONLOG. If this environment variable is defined, session logging is enabled.
Report output is directed either to UNIX stdout or to a printer. Users can redirect stdout if they wish using UNIX shell tools. Otherwise, stdout is piped into UNIX more. Non-printed report output is generally not echoed to the user's session log, though applications can choose to do so.
Most application report output consists of lines no greater than 80 characters long. However, some applications generate wide (or fine print) reports with lines up to 132 characters long. If printed, both standard and wide reports are piped into UNIX lp. However, if the environment variable REPORTLP is defined, printed standard width reports are piped into $REPORTLP. If the environment variable REPORTFINE is defined, printed wide reports are piped into $REPORTFINE.
Interrupts
Interrupt handling is left up to the application. However, most applications respond instantly to interrupts, clean up, and terminate. Other applications must wait for a convenient point at which to handle the interrupt. lib/libuif.a, include/uif.h
cmdform, prmint, prmstr, prmyn, outpstr, report
The command line format for non-display TeraScan functions was chosen for the following reasons:
It is easy to include TeraScan commands in UNIX shell scripts.
It is easy to call TeraScan commands from within windows-based applications.
Last Update: $Date: 1999/05/10 21:16:40 $