--------------------------------------------------------------------------------
MODULE DTITILE

--------------------------------------------------------------------------------
REPLACES PANACEA modules PANTILE and PANULL.

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

FUNCTION

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

FORMAT

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

PROMPTS

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

DTITILE COMMAND DEFAULTS

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

DESCRIPTION

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

GENERAL

TYPICAL COMMAND SEQUENCE

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

DTITILE COMMANDS

_@ COMMAND

--------------------------------------------------------------------------------
_@

--------------------------------------------------------------------------------
FORMAT: _@file-spec

--------------------------------------------------------------------------------
Command parameters:

--------------------------------------------------------------------------------
DESCRIPTION:

DTITILE offers the facility of command input from an indirect command file. The '@' character preceding a file-spec will cause DTITILE to open and read commands from the specified file until:

Nested command files are not supported (i_.e_. a command file containing an '@' command), although sequential '@' commands are supported when read from SYS$COMMAND.

As an aid to batch log interpretation DTITILE will echo all commands read from an indirect command file.

--------------------------------------------------------------------------------
Messages:

The following messages are specific to the _@ command:

*** WARNING *** "@" must precede a file-spec

*** WARNING *** Indirect file error - returning to terminal input

*** ERROR *** Can't open indirect command file 'file-spec'

--------------------------------------------------------------------------------
Examples:


DTITILE> @PRESETS<CR>
DTITILE> ENABLE DIAGNOSTICS
DTITILE> FILEIN AREA1 DTI file LSL$DTI:AREA1.DTI;0 opened for read Header : LSLA Data: REAL Units are DTI Matrix Values Matrix Coverage SW: 1 1 NE: 45 40 Matrix Interval E: 1 N: 1 Value Range : -5.00 to 326421.00
DTITILE> WINDOW 1 1 30 30
DTITILE> FILEOUT AREA15
DTITILE> SIZE 50 50
DTITILE> RETURN
DTITILE>

_! COMMAND

--------------------------------------------------------------------------------
_!

--------------------------------------------------------------------------------
FORMAT: _! [comment text]

--------------------------------------------------------------------------------
Command parameters:

--------------------------------------------------------------------------------
DESCRIPTION:

An exclamation mark is the standard MATRIX package comment delimiter. All text (and numbers) which lie to the right of a '!' character are excluded from command interpretation. Comments are useful for annotating command procedures used in batch processing etc_.

--------------------------------------------------------------------------------
Messages: None.

--------------------------------------------------------------------------------
Examples:


DTITILE> _! a comment for the sake of it<CR>
DTITILE> WINDOW 0.0 0.0 900.0 900.0<CR>
DTITILE>

CANCEL VOID COMMAND

--------------------------------------------------------------------------------
CANCEL VOID

--------------------------------------------------------------------------------
FORMAT: CANCEL VOID void_number

--------------------------------------------------------------------------------
Command parameters:

void_number

--------------------------------------------------------------------------------
DESCRIPTION:

The CANCEL VOID command cancels a previously specified void window. A list of currently defined void windows can be obtained using the SHOW VOIDS command.

--------------------------------------------------------------------------------
Messages:


*** ERROR *** Specifying the command CANCEL

Available CANCEL command qualifiers are:

VOID

The following messages are specific to the CANCEL VOID command:


*** ERROR *** Specifying the command CANCEL VOID
Command requires void_number

*** ERROR *** Specifying the command CANCEL VOID
Void 'void_number' out of range
Use command SHOW VOIDS to list defined voids

*** ERROR *** Specifying the command CANCEL VOID
Void 'void_number' not defined
Use command SHOW VOIDS to list defined voids

--------------------------------------------------------------------------------
Examples:


DTITILE> SHOW VOIDS<CR>

Void number 1 in DTI matrix units 10 10 20 20
Void number 2 in DTI matrix units 35 10 45 20
Void number 3 in DTI matrix units 60 10 75 20

DTITILE> CANCEL VOID 2<CR>
DTITILE> SHOW VOIDS<CR>
Void number 1 in DTI matrix units 10 10 20 20
Void number 2 not currently set
Void number 3 in DTI matrix units 60 10 75 20

DTITILE>

DISABLE ABSOLUTE COMMAND

--------------------------------------------------------------------------------
DISABLE ABSOLUTE

--------------------------------------------------------------------------------
FORMAT: DISABLE ABSOLUTE

--------------------------------------------------------------------------------
Command parameters: None.

--------------------------------------------------------------------------------
DESCRIPTION:

DISABLE ABSOLUTE cancels a previous ENABLE ABSOLUTE command. If DISABLE ABSOLUTE is given, then coordinate values required by the ORIGIN, WINDOW or VOID commands, supplied in metre or projection units, must be specified as an offset from the SW corner of the matrix.
By default values should be specified as absolute coordinates.

--------------------------------------------------------------------------------
Messages:

The following error message is specific to the DISABLE command:


*** ERROR *** Specifying command DISABLE
Available DISABLE command qualifiers are: 
ABSOLUTE    DIAGNOSTICS     NULL_CHECKING     PME  

--------------------------------------------------------------------------------
Examples:


DTITILE> DISABLE ABSOLUTE<CR>
DTITILE>

DISABLE DIAGNOSTICS COMMAND

--------------------------------------------------------------------------------
DISABLE DIAGNOSTICS

--------------------------------------------------------------------------------
FORMAT: DISABLE DIAGNOSTICS

--------------------------------------------------------------------------------
Command parameters: None.

--------------------------------------------------------------------------------
DESCRIPTION:

DISABLE DIAGNOSTICS allows the user to disable a previous ENABLE DIAGNOSTICS command.

--------------------------------------------------------------------------------
Messages:

The following error message is specific to the DISABLE command:


*** ERROR *** Specifying command DISABLE
Available DISABLE command qualifiers are: 
ABSOLUTE    DIAGNOSTICS     NULL_CHECKING     PME  

--------------------------------------------------------------------------------
Examples:


DTITILE> ENABLE DIAGNOSTICS<CR>
DTITILE> DISABLE DIAGNOSTICS<CR>
DTITILE>

DISABLE NULL_CHECKING COMMAND

--------------------------------------------------------------------------------
DISABLE NULL_CHECKING

--------------------------------------------------------------------------------
FORMAT: DISABLE NULL_CHECKING

--------------------------------------------------------------------------------
Command parameters: None.

--------------------------------------------------------------------------------
DESCRIPTION:

DISABLE NULL_CHECKING allows the user to disable a previous ENABLE NULL_CHECKING command.

If null checking is disabled, then during tiling, no checking for null values overwriting actual data posts, will take place. Processing may consequently be quicker.

--------------------------------------------------------------------------------
Messages:

The following error message is specific to the DISABLE command:


*** ERROR *** Specifying command DISABLE
Available DISABLE command qualifiers are: 
ABSOLUTE    DIAGNOSTICS     NULL_CHECKING     PME  

--------------------------------------------------------------------------------
Examples:


DTITILE> DISABLE NULL_CHECKING<CR>
DTITILE>

DISABLE PME COMMAND

--------------------------------------------------------------------------------
DISABLE PME

--------------------------------------------------------------------------------
FORMAT: DISABLE PME

--------------------------------------------------------------------------------
Command parameters: None.

--------------------------------------------------------------------------------
DESCRIPTION:

DISABLE PME allows the user to disable a previous ENABLE PME command.

--------------------------------------------------------------------------------
Messages:

The following error messages are specific to the DISABLE and DISABLE PME commands:


*** ERROR *** Specifying command DISABLE
Available DISABLE command qualifiers are: 
ABSOLUTE    DIAGNOSTICS     NULL_CHECKING     PME  

*** WARNING *** You are not using PME !

--------------------------------------------------------------------------------
Examples:


DTITILE> ENABLE PME<CR>
DTITILE> DISABLE PME<CR>
DTITILE>

ENABLE ABSOLUTE COMMAND

--------------------------------------------------------------------------------
ENABLE ABSOLUTE

--------------------------------------------------------------------------------
FORMAT: ENABLE ABSOLUTE

--------------------------------------------------------------------------------
Command parameters: None.

--------------------------------------------------------------------------------
DESCRIPTION:

If ENABLE ABSOLUTE is given, then coordinate values required by the WINDOW, ORIGIN or VOID commands, supplied in metre or projection units, must be specified as absolute (rather than relative) coordinate values.

For example if the projection indicates U.K. National Grid, then the WINDOW values may be specified as 6 figure National Grid coordinates.
By default window values should be specified as absolute coordinates.

ENABLE ABSOLUTE also controls whether DTITILE attempts to calculate default origins for files based on the origin offset information held in the headers of the files. This option can be disabled using the DISABLE ABSOLUTE command.

--------------------------------------------------------------------------------
Messages:

The following error message is specific to the ENABLE command:


*** ERROR *** Specifying command ENABLE
Available ENABLE command qualifiers are: 
ABSOLUTE    DIAGNOSTICS     NULL_CHECKING     PME  

--------------------------------------------------------------------------------
Examples:


DTITILE> ENABLE ABSOLUTE<CR>
DTITILE>

ENABLE DIAGNOSTICS COMMAND

--------------------------------------------------------------------------------
ENABLE DIAGNOSTICS

--------------------------------------------------------------------------------
FORMAT: ENABLE DIAGNOSTICS

--------------------------------------------------------------------------------
Command parameters: None.

--------------------------------------------------------------------------------
DESCRIPTION:

ENABLE DIAGNOSTICS allows the user to enable diagnostic printout.

Because DTITILE is usually used in a batch processing environment, by default the utility produces minimal diagnostic printout. If however, the user wishes to receive an indication of processing progress then diagnostic printout may be selected with the ENABLE DIAGNOSTICS command.

On a heavily loaded computer it may be reassuring to ENABLE DIAGNOSTICS for the processing stage to indicate progress through the input data. Messages are issued indicating which input file is currently being processed. The command also enables output of information on the window being applied if the WINDOW command had been invoked for the current input DTI file.

--------------------------------------------------------------------------------
Messages:

The following error message is specific to the ENABLE command:


*** ERROR *** Specifying command ENABLE
Available ENABLE command qualifiers are: 
ABSOLUTE    DIAGNOSTICS     NULL_CHECKING     PME  

--------------------------------------------------------------------------------
Examples:


DTITILE> ENABLE DIAGNOSTICS<CR>
DTITILE>

ENABLE NULL_CHECKING COMMAND

--------------------------------------------------------------------------------
ENABLE NULL_CHECKING

--------------------------------------------------------------------------------
FORMAT: ENABLE NULL_CHECKING

--------------------------------------------------------------------------------
Command parameters: None.

--------------------------------------------------------------------------------
DESCRIPTION:

Sometimes it may be necessary to tile files together in which null values in one file overlap valid data values in the other. In this case it is not desirable that the null values should overwrite the actual data values in the output file produced. If the command ENABLE NULL_CHECKING is given, then DTITILE checks for null values to ensure this does not happen.

Because extra checking is involved, processing time may be greater in this mode of operation.

--------------------------------------------------------------------------------
Messages:

The following error message is specific to the ENABLE command:


*** ERROR *** Specifying command ENABLE
Available ENABLE command qualifiers are: 
ABSOLUTE    DIAGNOSTICS     NULL_CHECKING     PME  

--------------------------------------------------------------------------------
Examples:


DTITILE> ENABLE NULL_CHECKING<CR>
DTITILE>

ENABLE PME COMMAND

--------------------------------------------------------------------------------
ENABLE PME

--------------------------------------------------------------------------------
FORMAT: ENABLE PME

--------------------------------------------------------------------------------
Command parameters: None.

--------------------------------------------------------------------------------
DESCRIPTION:

The ENABLE PME and DISABLE PME commands are reserved for Laser-Scan use. PME is a code optimisation tool and should be invoked by LSL software personnel only.

ENABLE PME causes the PME_INIT routine to be invoked.

--------------------------------------------------------------------------------
Message:

The following error messages are specific to the ENABLE and ENABLE PME commands:


*** ERROR *** Specifying command ENABLE
Available ENABLE command qualifiers are: 
ABSOLUTE    DIAGNOSTICS     NULL_CHECKING     PME  

*** WARNING *** You are already using PME!

--------------------------------------------------------------------------------
Examples:


DTITILE> ENABLE PME<CR>
DTITILE>

FILEIN COMMAND

--------------------------------------------------------------------------------
FILEIN

--------------------------------------------------------------------------------
FORMAT: FILEIN file-spec

--------------------------------------------------------------------------------
COMMAND PARAMETERS:

--------------------------------------------------------------------------------
DESCRIPTION:

The FILEIN command causes the specified file to be opened and used as an input file to DTITILE. A FILEIN command must be issued before the WINDOW or GO commands will be accepted.

An ORIGIN and a WINDOW command may be specified for each input DTI file, before the next file is defined using the FILEIN command.

If origin offset information is present in the header of the file, and the ENABLE ABSOLUTE command has been given, then a default origin is calculated, to allow automatic positioning to take place. Otherwise, the default origin will be the bottom left hand corner of the output DTI file.

By default the window is the total extent of the input file.

--------------------------------------------------------------------------------
Messages:

The following messages are specific to the FILEIN command:

*** ERROR *** Specifying command FILEIN
You must specify a file-spec argument to the FILEIN command

*** ERROR *** Specifying command FILEIN
You have already got eight DTI files open for input

*** ERROR *** Specifying command FILEIN
Unable to interpret input file-spec

*** ERROR *** Specifying command FILEIN
Failed while opening DTI file 'file spec' for input

*** ERROR *** Specifying command FILEIN
File 'file spec' data type 'type' invalid
Only data types 1 2 3 or 4 allowed

*** ERROR *** Specifying command FILEIN
File 'file-spec' data type not compatible with first DTI file

*** WARNING *** Header mismatch
File 'file-spec' does not have the same header type as the first DTI file

*** WARNING *** Units mismatch
File 'file-spec' does not have the same units as the first DTI file

*** WARNING *** Grid interval mismatch
File 'file-spec' X and/or Y grid not compatible with first DTI file

--------------------------------------------------------------------------------
Examples:

DTITILE> FILEIN AREA1<CR>
DTI file LSL$DTI:AREA1.DTI;0 opened for read
Header  :  LSLA  Data:  REAL
Units are DTI Matrix Values
Matrix Coverage   SW:     1     1  NE:    45    40
Matrix Interval    E:     1         N:     1
Value Range         :     -5.00 to  326421.00
DTITILE>

FILEOUT COMMAND

--------------------------------------------------------------------------------
FILEOUT

--------------------------------------------------------------------------------
FORMAT: FILEOUT file-spec

--------------------------------------------------------------------------------
COMMAND PARAMETERS:

--------------------------------------------------------------------------------
DESCRIPTION:

The FILEOUT command enables specification of the DTI file which is to receive the merged DTI data.

The FILEOUT command must be issued before the GO command.

--------------------------------------------------------------------------------
Messages:

The following messages are specific to the FILEOUT command:

*** ERROR *** You must specify a file-spec argument to the FILEOUT command

*** ERROR *** Unable to interpret output file-spec

--------------------------------------------------------------------------------
Examples:


DTITILE> FILEOUT DUA3:[DEMONSTRATION]IDAHO<CR>
DTITILE>

GO COMMAND

--------------------------------------------------------------------------------
_GO

--------------------------------------------------------------------------------
FORMAT: GO

--------------------------------------------------------------------------------
Command parameters: None

--------------------------------------------------------------------------------
DESCRIPTION:

Before the merge processing takes places, checks will be carried out to ensure that certain preconditions hold. The following checks are performed by the command:-

The command will create the DTI file specified by the FILEOUT command. The format of the new DTI file will be the same as the first input DTI file specified with the FILEIN command. The data area will be initialised with the currently defined null value for the data type.

Merging of the opened input files will proceed in the order in which they were specified.

Upon successful completion of the GO command DTITILE is terminated.

--------------------------------------------------------------------------------
Messages:

The following messages are specific to the GO command:

*** WARNING *** Origin values supplied exceed output file limits
Input file 'file spec' will not be processed

*** WARNING *** The supplied columns and/or rows via SIZE command is too small
The output DTI files will be created with the calculated column and row values.

*** ERROR *** FILEIN command must be used to open the DTI file first

*** ERROR *** FILEOUT command must be used to specify the output DTI file

--------------------------------------------------------------------------------
Examples:


DTITILE> FILEIN SOUTH<CR> DTI file LSL$DTI:SOUTH.DTI;0 opened for read File : LSL$DTI:SOUTH.DTI;0 Header : LSLA Data: WORD Units are DTI Matrix Values Matrix Coverage SW: 1 1 NE: 100 100 Matrix Interval E: 1 N: 1 Value Range : 189 to 326
DTITILE> FILEIN NORTH<CR> DTI file LSL$DTI:NORTH.DTI;0 opened for read File : LSL$DTI:NORTH.DTI;0 Header : LSLA Data: WORD Units are DTI Matrix Values Matrix Coverage SW: 1 1 NE: 100 100 Matrix Interval E: 1 N: 1 Value Range : 234 to 452
DTITILE> ORIGIN 1 200<CR>
DTITILE> FILEOUT FINAL<CR>
DTITILE> GO<CR>
ELAPSED: 00:00:20.04 CPU: 0:00:04.71 BUFIO: 281 DIRIO: 46 FAULTS: 263
_$

HELP COMMAND

--------------------------------------------------------------------------------
HELP

--------------------------------------------------------------------------------
FORMAT: HELP subject

--------------------------------------------------------------------------------
Command parameters:

--------------------------------------------------------------------------------
Description:

The HELP command looks the rest of the line up in the MATRIX HELP library. This library contains a brief summary of the operation of each command.

The information is looked up in the DTITILE section of the MATRIX help library, LSL$HELP:MATRIX.HLB.

--------------------------------------------------------------------------------
Messages:

Where required, warning messages are output via the VMS LBR$OUTPUT_HELP utility.

--------------------------------------------------------------------------------
Examples:


DTITILE> HELP ENABLE PME<CR>

DTITILE

ENABLE

PME


DTITILE>

NULL COMMAND

--------------------------------------------------------------------------------
NULL

--------------------------------------------------------------------------------
FORMAT: NULL null_value

--------------------------------------------------------------------------------
Command parameters: