--------------------------------------------------------------------------------
MODULE DTI2TEXT

--------------------------------------------------------------------------------
REPLACES None. DTI2TEXT is a completely new MATRIX utility.

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

FUNCTION

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

FORMAT

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

COMMAND QUALIFIERS

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

DTI2TEXT COMMAND DEFAULTS

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

DESCRIPTION

GENERAL

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

DTI2TEXT COMMANDS

_@ COMMAND

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

--------------------------------------------------------------------------------
FORMAT: _@file-spec<CR>

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

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

DTI2TEXT offers the facility of command input from an indirect command file. The '@' character preceding a file-spec will cause DTI2TEXT 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 DTI2TEXT 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:


$ DTI2TEXT<CR>
MATRIX module DTI2TEXT of 13:30:39 18-OCT-87
DTI2TEXT> @PRESETS<CR>
DTI2TEXT> ENABLE DIAGNOSTICS
DTI2TEXT> ENABLE NINT
DTI2TEXT> FILEIN READATA
DTI2TEXT> FILEOUT REALDATA.TXT
DTI2TEXT> UNITS METRES
DTI2TEXT> WINDOW 1 1 100 50
DTI2TEXT> RETURN
DTI2TEXT>

_! COMMAND

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

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

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

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

An exclamation mark is the standard DTM 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:


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

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 WINDOW command supplied in metre or projection units, must be specified as an offset from the SW corner of the matrix.
By default window values should be specified as absolute coordinates.

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

The following error message is specific to the DISABLE command:


*** ERROR *** Specifying command DISABLE

Available DISABLE qualifiers are :
DIAGNOSTICS    NINT    PME     ABSOLUTE

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


DTI2TEXT> DISABLE ABSOLUTE<CR>
DTI2TEXT>

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: None.

The following error message is specific to the DISABLE command:


*** ERROR *** Specifying command DISABLE

Available DISABLE qualifiers are :
DIAGNOSTICS    NINT    PME     ABSOLUTE

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


DTI2TEXT> DISABLE DIAGNOSTICS<CR>
DTI2TEXT>

DISABLE NINT COMMAND

--------------------------------------------------------------------------------
DISABLE NINT

--------------------------------------------------------------------------------
FORMAT: DISABLE NINT

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

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

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

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

The following error message is specific to the DISABLE command:


*** ERROR *** Specifying command DISABLE

Available DISABLE qualifiers are :
DIAGNOSTICS    NINT    PME     ABSOLUTE

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


DTI2TEXT> ENABLE NINT<CR>
DTI2TEXT> DISABLE NINT<CR>
DTI2TEXT>

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 messages are specific to the DISABLE and DISABLE PME commands:


*** ERROR *** Specifying command DISABLE

Available DISABLE qualifiers are :
DIAGNOSTICS    NINT    PME     ABSOLUTE

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

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


DTI2TEXT> ENABLE PME<CR>
DTI2TEXT> DISABLE PME<CR>
DTI2TEXT>

ENABLE ABSOLUTE COMMAND

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

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

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

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

If ENABLE ABSOLUTE is given, then coordinate values required by the WINDOW command, 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.

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 qualifiers are :
DIAGNOSTICS    NINT    PME     ABSOLUTE

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


DTI2TEXT> ENABLE ABSOLUTE<CR>
DTI2TEXT>

ENABLE DIAGNOSTICS COMMAND

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

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

--------------------------------------------------------------------------------
Command parameters:_None.

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

ENABLE DIAGNOSTICS allows the user to enable diagnostic printout.

Because it is usually used in a batch processing environment, by default DTI2TEXT produces minimal diagnostic printout. If however, the user wishes to receive indications of processing progress and of the effect of windowing on data input, diagnostic printout may be selected with the ENABLE DIAGNOSTICS command.

On a heavily loaded computer it may be reassuring to ENABLE DIAGNOSTICS for the conversion stage of DTI2TEXT processing to indicate progress through the data set. A message indicating the current column being converted is issued at approximately each one tenth of the way through the DTI file.

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

The following error message is specific to the ENABLE command:


*** ERROR *** Specifying command ENABLE

Available ENABLE qualifiers are :
DIAGNOSTICS    NINT    PME     ABSOLUTE

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


DTI2TEXT> ENABLE DIAGNOSTICS<CR>
DTI2TEXT>

ENABLE NINT COMMAND

--------------------------------------------------------------------------------
ENABLE NINT

--------------------------------------------------------------------------------
FORMAT: ENABLE NINT

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

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

ENABLE NINT allows the user to enable the conversion of any real data in the DTI file to integer data by rounding to the nearest integer. The rounded numbers will then be output in the same way as integer data from an integer DTI file.

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

The following error message is specific to the ENABLE command:


*** ERROR *** Specifying command ENABLE

Available ENABLE qualifiers are :
DIAGNOSTICS    NINT    PME     ABSOLUTE

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


DTI2TEXT> ENABLE NINT<CR>
DTI2TEXT> FILEIN REALDATA<CR>
DTI2TEXT> FILEOUT ROUNDED<CR>
DTI2TEXT> GO<CR>
DTI2TEXT> DISABLE NINT<CR>
DTI2TEXT>

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 messages are specific to the ENABLE and ENABLE PME commands:


*** ERROR *** Specifying command ENABLE

Available ENABLE qualifiers are :
DIAGNOSTICS    NINT    PME     ABSOLUTE

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

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


$ DTI2TEXT<CR>
MATRIX module DTI2TEXT of 13:30:39 18-OCT-87
DTI2TEXT> ENABLE PME<CR>

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 DTI2TEXT. A FILEIN command must be issued before the WINDOW or GO commands will be accepted.

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

The following messages are specific to the FILEIN command:

*** WARNING *** You must specify a file-spec argument to the FILEIN command
*** ERROR *** Unable to interpret input file-spec

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

DTI2TEXT> FILEIN REAL<CR>
DTI file LSL$DTI:REAL.DTI;0 opened for read
File    :  LSL$DTI:REAL.DTI;0
Header  :  LSLA  Data:  REAL
Units are Metres
Matrix Coverage   SW:       0.00       0.00    NE:      49.00      49.00
Matrix Interval    E:       1.00                N:       1.00
Value Range         :     -5.00 to  326421.00
DTI2TEXT>

FILEOUT COMMAND

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

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

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

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

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

The FILEOUT command must be issued before the GO command.

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

The following messages are specific to the FILEOUT command:


*** WARNING *** You must specify a file-spec argument to the FILEOUT command
*** ERROR *** Unable to interpret output file-spec
*** ERROR *** in opening output file
*** ERROR *** in selecting output file
*** ERROR *** Not possible to open file

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


DTI2TEXT> FILEOUT DUA3:[DEMONSTRATION]IDAHO<CR>
Text output file 'file-spec' opened
DTI2TEXT>

FORMAT COMMAND

--------------------------------------------------------------------------------
FORMAT

--------------------------------------------------------------------------------
FORMAT: FORMAT format

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

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

The FORMAT command allows the user to specify a format for the text output file records (one record per line of the file) in terms of a FORTRAN like format definition.

The syntax of the format definition is :

<number of fields> ["F"|"I"] <field width> ["." number of decimal places]

The format definition will be parsed at the time it is input. It will be checked to make sure that it is compatible with the data in the DTI file, in terms of whether it is real or integer and whether it is wide enough to accommodate the longest number in the file, when the GO command is issued. The maximum record length allowed is 256 characters.

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

Current format is 'format' Enter new format, or press <return> to invoke default (10F8.3 or 10I8). New format, eg 12F6.2 or 8I10 ?

*** ERROR *** Error reading format

*** ERROR *** Illegal user defined format 'format', default format reinstated

With indirect file input:

*** ERROR *** Must specify format with format command

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


DTI2TEXT> FORMAT 20I4<CR>
DTI2TEXT> SHOW FORMAT<CR> Current user defined format (20I4)
DTI2TEXT>

GO COMMAND

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

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

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

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

This will carry out the conversion from a previously specified DTI input file to a previously specified text output file under the conditions set up using any other commands, for example to specify a diagnostic printout or rounding of real input data to the nearest integer.

Before the conversion takes places, checks will be carried out to ensure that certain preconditions hold. For example that the input and output files have been opened, and that any user defined or default format is compatible with the data range and type in the DTI file.

A single session with DTI2TEXT may involve a number of successive conversions of different DTI files. In such cases, all the conditions set up to govern one conversion will persist when it is complete, with the exceptions of the files specified and any window defined within the input file.

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

Messages connected with checking the format :
*** ERROR *** Require real format for real data
*** ERROR *** Require integer format for rounded real data
*** ERROR *** Require integer format for integer data
*** ERROR *** Text field format too narrow, please redefine

Other messages
*** ERROR *** Please check that text output file is open
*** ERROR *** Please check that DTI input file is open
*** ERROR *** Error in selecting output file 'file-spec'
*** ERROR *** Error reading column 'integer' of DTI file 'file-spec'
*** ERROR *** Error closing text output file 'file-spec'
*** ERROR *** Error closing DTI input file 'file-spec'
*** ERROR *** Unrecognised datatype in DTI file
*** ERROR *** Cannot write line to output file 'file-spec'

In addition to these there are the diagnostic printout messages which will be given if diagnostics are enabled. These consist of the file specifications of the input and output files, the header details of the DTI file, and messages indicating which group of columns, of those being processed, has been reached by the conversion command.

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

DTI2TEXT> FILEIN TST
DTI2TEXT> FILEOUT TST
DTI2TEXT> GO<CR>
Converting from DTI file LSL$DTI:TST.DTI;0 to text file TST.DAT.
Details of input DTI file :
File    :  LSL$DTI:TST.DTI;0
Header  :  LSLA  Data:  WORD
Units are DTI Matrix Values
Matrix Coverage   SW:     1     1  NE:    71    71
Matrix Window     SW:     1     1  NE:    50    50
Matrix Interval    E:     1         N:     1
Value Range         :   139   to    192
   Converting columns          1 to          4
   Converting columns          5 to          8
   Converting columns          9 to         12
   Converting columns         13 to         16
   Converting columns         17 to         20
   Converting columns         21 to         24
   Converting columns         25 to         28
   Converting columns         29 to         32
   Converting columns         33 to         36
   Converting columns         37 to         40
   Converting columns         41 to         44
   Converting columns         45 to         48
   Converting columns         49 to         50
DTI2TEXT>

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 DTI2TEXT 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:


DTI2TEXT> HELP ENABLE NINT<CR>

DTI2TEXT

ENABLE

NINT


DTI2TEXT>

NULL COMMAND

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

--------------------------------------------------------------------------------
FORMAT: NULL value

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