--------------------------------------------------------------------------------
MODULE    ICUT

-------------------------------------------------------------------------------- REPLACES None, ICUT is a completely new IMP utility.

--------------------------------------------------------------------------------

FUNCTION

--------------------------------------------------------------------------------

FORMAT

--------------------------------------------------------------------------------

PROMPTS

--------------------------------------------------------------------------------

PARAMETERS

--------------------------------------------------------------------------------

COMMAND QUALIFIERS

--------------------------------------------------------------------------------

RESTRICTIONS

--------------------------------------------------------------------------------

DESCRIPTION

--------------------------------------------------------------------------------

EXAMPLES

$ ICUT INPUT OUTPUT /POINTS=5 
ELAPSED:    0 00:00:03.51  CPU: 0:00:00.39  BUFIO: 6  DIRIO: 29  FAULTS: 195 
$

$ ICUT INPUT OUTPUT /LENGTH=300 ELAPSED: 0 00:00:04.05 CPU: 0:00:00.46 BUFIO: 6 DIRIO: 22 FAULTS: 203

$ ICUT INPUT OUTPUT /POINTS=5 /LOG %ICUT-I-CMDQUAL, The following command qualifiers were detected on the command line: /LOG /POINTS . %LSLLIB-I-IFFOPENED, LSL$DATA_ROOT:[LSL.IFF]INPUT.IFF;1 opened for read %LSLLIB-I-IFFOPENED, LSL$DATA_ROOT:[LSL.IFF]OUTPUT.IFF;5 opened for write %ICUT-I-HIGHINFSN, highest FSN from input IFF file is 1 %ICUT-I-OUTFFT, 40 features were written to the output IFF file ELAPSED: 0 00:00:04.35 CPU: 0:00:00.45 BUFIO: 6 DIRIO: 20 FAULTS: 261 $

$ ICUT INPUT OUTPUT /POINTS=5 /FCP=FRED.PAIR ELAPSED: 0 00:00:02.93 CPU: 0:00:00.20 BUFIO: 10 DIRIO: 21 FAULTS: 200 $

$ ICUT INPUT OUTPUT /POINTS=5 /AC=(FSN,FC,Z) /LOG %ICUT-W-INAPAZ, /AC=Z inappropriate without /POINTS=1 %ICUT-I-CANAZ, cancelling /AC =Z %ICUT-I-CMDQUAL, The following command qualifiers were detected on the command line: /AC /AC=FSN /AC=FC /LOG /POINTS . %LSLLIB-I-IFFOPENED, LSL$DATA_ROOT:[LSL.IFF]INPUT.IFF;1 opened for read %LSLLIB-I-IFFOPENED, LSL$DATA_ROOT:[LSL.IFF]OUTPUT.IFF;4 opened for write %ICUT-I-HIGHINFSN, highest FSN from input IFF file is 1 %ICUT-I-OUTFFT, 40 features were written to the output IFF file ELAPSED: 0 00:00:05.38 CPU: 0:00:00.38 BUFIO: 6 DIRIO: 22 FAULTS: 220 $

--------------------------------------------------------------------------------

EXAMPLES - OF BADLY FORMED COMMAND LINE SPECIFICATION

The following examples illustrate badly formed command line specification to ICUT. They illustrate the types of error messages that are likely to be encountered when using ICUT. They will cause an error condition to be generated and will cause ICUT to terminate processing.

$ ICUT From_: %CLI-W-NOCOMD, no command on line - reenter with alphabetic first character ELAPSED: 0 00:00:00.35 CPU: 0:00:00.02 BUFIO: 0 DIRIO: 0 FAULTS: 86

Here the CLI routines have detected a premature termination of the command line and issue a warning message. ICUT then terminates. The minimum information that is required on the command line for ICUT to run is the input and output IFF filenames.

This error can also occur while batch processing if the line being submitted does not contain both the input and output IFF filenames.

$ ICUT NONEXISTENT OUTPUT %ICUT-W-WARNINSUFSWITCH, neither /POINTS or /LENGTH specified %ICUT-I-SETPTS, defaulting to /POINTS=1 %LSLLIB-E-IFFOPEN, IFF error opening file "LSL$IF:NONEXISTENT.IFF;0" for read %IFF-E-OPEN, error opening IFF file -RMS-E-FNF, file not found ELAPSED: 0 00:00:01.77 CPU: 0:00:00.20 BUFIO: 6 DIRIO: 9 FAULTS: 161

$ ICUT INPUT OUTPUT /POINTS=5 /LENGTH=300 %CLI-W-CONFLICT, illegal combination of command elements - check documentation

\POINTS\
ELAPSED: 0 00:00:00.64 CPU: 0:00:00.03 BUFIO: 2 DIRIO: 0 FAULTS: 107

Here ICUT has detected incompatible qualifiers /POINTS and /LENGTH. Since only one of these must be specified, ICUT terminates with an error condition.

$ ICUT INPUT OUTPUT /POINTS=5 /FCP=FRED.PAIR /NEWFC=300 %CLI-W-CONFLICT, illegal combination of command elements - check documentation

\FCP\
ELAPSED: 0 00:00:00.86 CPU: 0:00:00.03 BUFIO: 2 DIRIO: 0 FAULTS: 106

In this example ICUT has detected incompatible qualifiers /FCP and /NEWFC.

Since /FCP defines an input file which contains details on the features to cut, and the feature codes of the resulting output features, /NEWFC is redundant. ICUT terminates with an error condition since it has no way of knowing which of the two qualifiers was actually wanted.

--------------------------------------------------------------------------------

MESSAGES (INFORMATIONAL)

These messages give information only, and require no immediate action by the user (except perhaps to verify that the correct options have been selected). Generally they will only appear if /LOG has been specified on the command line.

--------------------------------------------------------------------------------

MESSAGES (WARNING)

These messages indicate that an error has occurred from which processing is continued. These are accompanied by messages which indicate how the program is dealing with the error. Processing will continue until normal completion or a severe error is detected (see next section). No user action is required until the termination of the program.

--------------------------------------------------------------------------------

MESSAGES (ERROR)

These messages indicate an error in processing which has caused the program to terminate. The most likely causes are a corrupt or otherwise invalid input IFF file, or an error related to command line processing and file manipulation. With the exception of the IFF file closure errors, no output file will be produced if one of these error messages is output.

--------------------------------------------------------------------------------

MESSAGES (OTHER)

In addition to the above messages which are generated by ICUT itself, other messages may be produced by the command line interpreter (CLI) and by Laser-Scan libraries. In particular, messages may be generated by the IFF library. These are introduced by '%IFF' and are documented in the IFF library users guide. In most cases IFF errors will be due to a corrupt input file, and this should be the first area of investigation. If the cause of the error cannot be traced by the user and Laser-Scan are consulted, then the input file should be preserved to facilitate diagnosis.