INTRODUCTION

The Digital Terrain Image (DTI) file is the means by which Laser Scan holds grid based data such as Digital Elevation Models (DEMs), intervisibility matrices and Remotely Sensed Imagery. The structure of this file is described in Appendix A at the end of this chapter.

DTILIB provides a library of functions which enables an applications program to access DTI files, and perform basic I/O operations on both the header and data areas. The following groups of routines are provided within the library:

The library allows up to 9 DTI files to be handled simultaneously.

The library may be found in LSL$LIBRARY:DTILIB.OLB, and its associated common blocks and parameter files in LSL$CMNDTI.

It should be noted that the DTILIB functions utilise the memory mapping routines (eg. VIO$OPEN_SEC) within Laser-Scan's library LSLLIB, along with other LSLLIB I/O functions. An applications program that utilises DTILIB must therefore be linked with LSLLIB. It should also be noted that DTI_LUNs specified in the range 1 to 9, are supplied to the LSLLIB memory mapping routines as luns 0 to 8.

DTILIB is also available in sharable image form. To link with the shareable images on VAX systems, specify LSL$LIBRARY:DTISHR/OPT on the link command lines. Specify LSL$LIBRARY:DTISHR_TV/OPT on the link command lines on AXP systems. Linking with DTISHR also requires that the code be linked with LSLSHR, the sharable image version of LSLLIB. This may be done by adding LSL$LIBRARY:LSLSHR/OPT or LSL$LIBRARY:LSLSHR_TV/OPT to the link command lines on VAX and AXP systems respectively.

A major advantage of DTISHR over DTILIB is that it can be linked with native AXP code, eliminating the need to use VEST (aka DECmigrate). In order for the AXP linker to produce a correctly working executable, it is necessary to link against the supplied dummy versions of any AXP sharable images used. The dummy versions are needed to correctly set up the linkages to shared data (common blocks). This is done by temporarily changing the relevant logical names to point to the dummy images rather than the real ones. The following DCL file shows an example of this being done:


$! Compile all source using /TIE
$!
$  FORTRAN/TIE DTISHR_TEST
$!
$! Redefine logical names to point to dummy sharable images. Done in /USER mode
$! so that definitions revert to normal after the LINK instruction
$!
$  DEFINE/USER LSL$DTISHR_TV LSL$LIBRARY:DTISHR_DUMMY_AXP
$  DEFINE/USER LSL$LSLSHR_TV LSL$LIBRARY:LSLSHR_DUMMY_AXP
$!
$! Link against sharable images using /NONATIVE_ONLY
$!
$  LINK  DTISHR_TEST, -
         LSL$LIBRARY:DTISHR_TV/OPT, -
         LSL$LIBRARY:LSLSHR_TV/OPT/NONATIVE_ONLY

FUNCTION RETURN CODES

All DTILIB routines are declared as INTEGER*4 Functions, and return an error code, which may be looked up in the parameter file LSL$CMNDTI:DTILIBMSG.PAR. DTILIB error parameters have the prefix DTI__.

All routines return DTI__NORMAL if successful. An applications program may specifically test for this code, or simply whether the return is .true. indicating success, or .false. indicating failure. In the event of failure the return code will indicate the reason for failure. The error code DTI__SYSERR indicates a system error. In such cases the system error code will be returned as a function argument.

In order to access the function return message list, and therefore output a message associated with a return code using the LSLLIB facility LSL_PUTMSG, the routine DTI_INIT must be called by an applications program prior to any DTILIB routines. It is conventional to call DTI_INIT at the point in the program where LSL_INIT is called.

Examples showing the two ways in which the return code can be tested are provided below


C	Open as read only a DTI file EXAMPLE on DTI_LUN 1 
	RETVAL = DTI_OPEN (1,'LSL$DTI:EXAMPLE.DTI;1',19,.FALSE.,ERROR)
C
C	Test for success, using DTI__NORMAL
	IF (RETVAL.NE.DTI__NORMAL) THEN
C	
C	Output error message
	   CALL LSL_PUTMSG(RETVAL)
C
C	Test for system error, and output 
	   IF(RETVAL.EQ.DTI__SYSERR)CALL LSL_PUTMSG(ERROR)
	ENDIF
C
C---------------------------------------------------------------------
C	Alternatively......
C	Open as read only a DTI file EXAMPLE on DTI_LUN 1 
	RETVAL = DTI_OPEN (1,'LSL$DTI:EXAMPLE.DTI;1',19,.FALSE.,ERROR)
C
C	Test for success
	IF (.NOT.RETVAL) THEN
C	
C	Output error message
	   CALL LSL_PUTMSG(RETVAL)
C
C	Test for system error, and output 
	   IF(RETVAL.EQ.DTI__SYSERR)CALL LSL_PUTMSG(ERROR)
	ENDIF
C

DTIHDR COMMON BLOCK

DTILIB routines communicate with an applications program either via the function arguments and/or via the common block DTIHDR to be found in LSL$CMNDTI. This common block contains information about each mapped file. In many cases the variables in the common block may be modified by a program, although the user should be aware of possible consequences. An asterisk is placed against those variables that should generally NOT be modified by an applications program once set by the DTILIB functions DTI_OPEN, DTI_CREATE and DTI_EXTEND.

C	DTILIB COMMON DTIHDR
C-----------------------------------------------------------------------
C	Maximum number of DTI files
	INTEGER*4	MAX_DTI			
	PARAMETER	(MAX_DTI=9)
C-----------------------------------------------------------------------
C	Status of DTI LUNs
C
    *	LOGICAL		DTILUN_INUSE(MAX_DTI)	!.true. if in use
C						!.false. if free
    *   LOGICAL		READ_ONLY(MAX_DTI) !.true. if read only access
C					   !.false. if write access
C-----------------------------------------------------------------------
C	Mapped section details
C
    *	INTEGER*4	SEC_ADDR(MAX_DTI) !addr. of start of mapped file
    *	INTEGER*4	SEC_SIZE(MAX_DTI) !size of mapped file(in bytes)
C-----------------------------------------------------------------------
C	DTI file specification details
C
	CHARACTER*128	DTI_NAME(MAX_DTI)	!filename
	INTEGER*4	DTI_NAME_LENGTH(MAX_DTI)!length of filename
C-----------------------------------------------------------------------
C	DTI file header type identifier
C
     *	INTEGER*4	HEADER_TYPE(MAX_DTI)	!1 for MIKE, 2 for UHL1,
C						!3 for TED4, 4 for ALVY
C						!5 for LSLA
C-----------------------------------------------------------------------
C	Byte offset of data area from start of mapped file.
C	ie. length of DTI header
C
     *	INTEGER*4 	DATA_OFFSET(MAX_DTI)	!data offset (in bytes)
C-----------------------------------------------------------------------
C	Data type identifier
C
     *	INTEGER*4	DATA_TYPE(MAX_DTI)	!1 for BYTE, 2 for WORD,
C						!3 for LONGWORD,
C						!4 for REAL, 5 for BIT
C-----------------------------------------------------------------------
C	Number of columns and rows
C
     *	INTEGER*4	X_EXTENT(MAX_DTI) !matrix x size (no. of cols)
     *	INTEGER*4	Y_EXTENT(MAX_DTI) !matrix y size (no. of rows)

C-----------------------------------------------------------------------
C	Matrix x and y grid interval
C
	REAL		X_GRID(MAX_DTI)	   !x grid interval (metres)
	REAL		Y_GRID (MAX_DTI)   !y grid interval (metres)
C-----------------------------------------------------------------------
C	Minimum and maximum data value ranges
C
	REAL		MIN_RVALUE(MAX_DTI)	!min real data value
	REAL		MAX_RVALUE(MAX_DTI)	!max real data value
	INTEGER*4	MIN_LVALUE(MAX_DTI)	!min longword data val
	INTEGER*4	MAX_LVALUE(MAX_DTI)	!max longword data val
	INTEGER*2	MIN_WVALUE(MAX_DTI)	!min byte/word data val
	INTEGER*2	MAX_WVALUE(MAX_DTI)	!max byte/word data val
C-----------------------------------------------------------------------
C	Projection record status.  Indicates whether a projection record
C	was found on opening the DTI file.
C	Projection record details are held in COMMON DTIPROJ
C
	LOGICAL		HAD_PROJ_RECORD(MAX_DTI)
C					!.true. if proj rec was present
C					!.false. if no proj record
C-----------------------------------------------------------------------
C	Geographical (latitude longitude) information for DTED files.
C	Values are recorded in .1 seconds of arc
C
	INTEGER*4	LATREC(4,MAX_DTI)	!latitude and longitude 
	INTEGER*4	LONREC(4,MAX_DTI)	!values of the 4 corners
C						!SW,NW,NE,SE
	INTEGER*4	LATORI(MAX_DTI)		!latitude origin 
	INTEGER*4	LONORI(MAX_DTI)		!longitude origin 
	INTEGER*4	LATINT(MAX_DTI)		!latitude grid interval 
	INTEGER*4	LONINT(MAX_DTI)		!longitude grid interval
C-----------------------------------------------------------------------
C	Absolute SW corner values for non DTED files
C
	REAL		X_OFFSET(MAX_DTI)	!absolute position of
	REAL		Y_OFFSET(MAX_DTI)	!column 1, row 1 (metres)
C-----------------------------------------------------------------------
C	Current rectangular area of interest in the DTI file
C	Specified in matrix units, and set up by applications program.
C	
	INTEGER*4	DTI_WINDOW_SWX(MAX_DTI)!current area of interest
	INTEGER*4	DTI_WINDOW_SWY(MAX_DTI) !in the DTI file, 
	INTEGER*4	DTI_WINDOW_NEX(MAX_DTI) !specified
	INTEGER*4	DTI_WINDOW_NEY(MAX_DTI)	!in matrix units
C-----------------------------------------------------------------------
C	Data order (ie. arrangement of data in the DTI file) 
C
	INTEGER*4	DTI_ORDER_CORNER(MAX_DTI)
C					    	!corner of data origin
C					     	!0 = SW, 1 = NW
C						!2 = NE, 3 = SE
	INTEGER*4	DTI_ORDER_DIRECTION(MAX_DTI)	
C						!0 = clockwise
C						!1 = anticlockwise
C-----------------------------------------------------------------------
	COMMON/DTIHDR/	X_GRID,Y_GRID,MIN_RVALUE,MAX_RVALUE,
     &			MIN_LVALUE,MAX_LVALUE,X_EXTENT,Y_EXTENT,
     &			LATREC,LONREC,LATORI,LONORI,LATINT,LONINT,
     &			SEC_ADDR,SEC_SIZE,DATA_OFFSET,
     &			MIN_WVALUE,MAX_WVALUE,
     &			HEADER_TYPE,DATA_TYPE,DTI_NAME,DTI_NAME_LENGTH,
     &			DTILUN_INUSE,X_OFFSET,Y_OFFSET,
     &			DTI_WINDOW_SWX,DTI_WINDOW_SWY,
     &			DTI_WINDOW_NEX,DTI_WINDOW_NEY,
     &                  READ_ONLY,HAD_PROJ_RECORD,
     &                  DTI_ORDER_CORNER,DTI_ORDER_DIRECTION

DTIPROJ COMMON BLOCK

A DTI file with a LSLA type header may optionally contain a DTI Projection Record. The Projection Record holds information about the spheroid and projection system on which the data is recorded, along with data on the location of the SW corner of the matrix and the x and y grid intervals. A Projection Record in a LSLA header record is recognised by means of the identifier '*DTIPROJ'.

The DTILIB routines DTI_READ_PROJ_REC and DTI_WRITE_PROJ_REC are provided to read and write the Projection Record, and transfer details between the file header and the DTILIB common block DTIPROJ. The common block variables may be accessed and modified by an applications program.

C	DTILIB COMMON block DTIPROJ
C
C	Holds details of the DTI Projection Record that may be
C	optionally present as part of a LSLA (or the historical
C	ALVY) style DTI header record.
C	The common variables are filled out when a call to the
C	DTILIB routine DTI_READ_PROJ_REC is made.
C	They may be modified by an applications program, and
C	written to a LSLA DTI file using DTI_WRITE_PROJ_REC.
C	Note: the DTI Projection Record may be located anywhere
C	in the header record, and is identified to the
C	library routines by the keyword '*DTIPROJ'.
C
C----------------------------------------------------------------------
C	DTIPROJ Parameters:
C
	INTEGER*4	DTIPROJ_IDENT1
	PARAMETER	(DTIPROJ_IDENT1='*DTI')
	INTEGER*4	DTIPROJ_IDENT2
	PARAMETER	(DTIPROJ_IDENT2='PROJ')
C	DTI Projection Record Identifier in two parts
C	
	INTEGER*4	NUM_DTI
	PARAMETER	(NUM_DTI=9)
C	Maximum number of DTI files
C
	INTEGER*4	DTIPROJ_RECORD_LENGTH	
	PARAMETER	(DTIPROJ_RECORD_LENGTH=1600)
C	Length of DTI Projection Record in bytes
C
C----------------------------------------------------------------------
C
	INTEGER*4	DTIPROJ_RECORD_OFFSET(NUM_DTI)
C	Byte offset of projection record
C
	REAL*8		DTIPROJ_ORIGIN(2,NUM_DTI)
C	x,y coordinates of matrix point (1,1)
C
	REAL*4 		DTIPROJ_SAMPLE(2,NUM_DTI)
C	x,y grid sample values
C
	INTEGER*4	DTIPROJ_UNITS(NUM_DTI)
C	DTI units code:
C	=   0 Unset
C	=   1 Feet (assuming projection units are metres)
C	=   2 Metres
C	=   3 Seconds of arc (only valid if projection is 100)
C	=   4 Degrees of arc (only valid if projection is 100)
C	=   5 Radians (only valid if projection is 100)
C       = 102 mm on the source document
C	= 104 thousands of an inch on source document
C	= 110 1/10 seconds of arc (only valid if projection is 100)
C
	INTEGER*4	DTIPROJ_SPHEROID(NUM_DTI)
C	DTI spheroid code:
C	=  0 Clarke 1866
C	=  1 Clarke 1880
C	=  2 Bessel
C	=  3 New International 1967
C	=  4 International 1924 (Hayford 1909)
C	=  5 World Geodetic System 72 (WGS 72)
C	=  6 Everest
C	=  7 World Geodetic System 66 (WGS 66)
C	=  8 Geodetic Reference System 1980 (GRS 1980)
C	=  9 Airy
C	= 10 Modified Everest
C	= 11 Modified Airy
C	= 12 Walbeck
C	= 13 Southeast Asia
C	= 14 Australian National
C	= 15 Krassovsky
C	= 16 Hough
C	= 17 Mercury 1960
C	= 18 Modified Mercury 1968
C	= 19 Sphere of radius 6370997 M
C	= 20 Sphere of radius 6371229.3M
C	= 21 Clarke 1880 IGN
C	= 22 World Geodetic System 84 (WGS 84)
C	=101 User specified spheroid 
C
	INTEGER*4	DTIPROJ_PROJECTION(NUM_DTI)
C	DTI projection code:
C	=   0  Unset
C	=   1  Universal Transverse Mercator
C	=   2  State Plane Coordinates
C	=   3  Albers Conical Equal Area
C	=   4  Lambert Conformal Conic
C	=   5  Mercator
C	=   6  Polar Stereographic 
C	=   7  Polyconic
C	=   8  Equidistant Conic
C	=   9  Transverse Mercator
C	=  10* Stereographic
C	=  11* Lambert Azimuthal Equal Area
C	=  12* Azimuthal Equidistant
C	=  13* Gnomonic
C	=  14* Orthographic
C	=  15* General Vertical Near-Side Perspective
C	=  16* Sinusoidal
C	=  17* Equirectangular
C	=  18* Miller Cylindrical
C	=  19* Van der Grinten
C	=  20  Oblique Mercator (Hotine)
C	=  21* Oblique Mercator (Spherical)
C	= 100  Geographic  (ie Latitude and Longitude )
C	= 101  UK national grid  (a special case of 9)
C
	REAL*8		DTIPROJ_USER_SPHEROID(2,NUM_DTI)
C	Details of user specified spheroid.
C	The first real contains the semi-major axis 
C	of the ellipse;
C	The second real contains one of:
C	1) 0.0 to specify a sphere rather than a spheroid
C	2) the semi-minor axis
C	3) the eccentricity squared
C	Note: This system works because e**2 is less than
C	1.0, while the semi-minor axis is greater than 1.
C
	REAL*8		DTIPROJ_PROJ_PARAMS(15,NUM_DTI)
C	Map projection definition parameters
C	The values are dependent on the projection.
C	See GCTPLIB documentation for the values required 
C	for each projection listed above.
C	No values need be given for projections 100 and 101.
C
	COMMON/DTIPROJ/	
     &			DTIPROJ_RECORD_OFFSET,
     &			DTIPROJ_ORIGIN,DTIPROJ_SAMPLE,
     &			DTIPROJ_UNITS,DTIPROJ_SPHEROID,
     &			DTIPROJ_PROJECTION,
     &			DTIPROJ_USER_SPHEROID,
     &			DTIPROJ_PROJ_PARAMS

DTILIB PARAMETER FILES

The following parameter files used by DTILIB are to be found in LSL$CMNDTI, and may be utilised within an applications program.
DTIPAR.PAR

C File contains parameters used by DTILIB functions.
C
C-----------------------------------------------------------------
C	Type Field parameters
C
	INTEGER*4	MIKE_MAKE		!historical
	INTEGER*4	UHL1_MAKE		!historical
	INTEGER*4	TED4_MAKE
	INTEGER*4	ALVY_MAKE		!historical
	INTEGER*4	LSLA_MAKE
C
	PARAMETER (MIKE_MAKE='MIKE')
	PARAMETER (UHL1_MAKE='UHL1')
	PARAMETER (TED4_MAKE='TED4')
	PARAMETER (ALVY_MAKE='ALVY')
	PARAMETER (LSLA_MAKE='LSLA')
C
C-----------------------------------------------------------------
C	HEADER_TYPE parameters
C
	INTEGER*4		DTI_MIKE	!historical
	INTEGER*4		DTI_UHL1	!historical
	INTEGER*4		DTI_TED4	
	INTEGER*4		DTI_ALVY	!historical
	INTEGER*4		DTI_LSLA
C
	PARAMETER (DTI_MIKE = 1)	! HEADER_TYPE for MIKE DTI
	PARAMETER (DTI_UHL1 = 2)	! HEADER_TYPE for UHL1 DTI
	PARAMETER (DTI_TED4 = 3)	! HEADER_TYPE for TED4 DTI
	PARAMETER (DTI_ALVY = 4)	! HEADER_TYPE for ALVY DTI
	PARAMETER (DTI_LSLA = 5)	! HEADER_TYPE for LSLA DTI
C
C-----------------------------------------------------------------
C	DATA_TYPE parameters
C
	INTEGER		DATA_BYTE
	INTEGER		DATA_WORD
	INTEGER		DATA_LONG
	INTEGER		DATA_REAL
	INTEGER		DATA_BIT
C
	PARAMETER (DATA_BYTE = 1)
	PARAMETER (DATA_WORD = 2)
	PARAMETER (DATA_LONG = 3)
	PARAMETER (DATA_REAL = 4)
	PARAMETER (DATA_BIT  = 5)
C
C-----------------------------------------------------------------
C	DTI null data values
	BYTE		DTI_NULL_BYTE
	INTEGER*2	DTI_NULL_WORD
	INTEGER*4	DTI_NULL_LONG
	REAL*4		DTI_NULL_REAL
C
	PARAMETER (DTI_NULL_BYTE = 0)
	PARAMETER (DTI_NULL_WORD = -32767)
	PARAMETER (DTI_NULL_LONG = '80000000'X)	
	PARAMETER (DTI_NULL_REAL = -1.0E-38)
C
C----------------------------------------------------------------
C	UNITS parameters
C
	INTEGER*4	UNITS_DTI
	INTEGER*4	UNITS_MET
	INTEGER*4	UNITS_SEC
	INTEGER*4	UNITS_DEG
	INTEGER*4	UNITS_PROJ
C
	PARAMETER (UNITS_DTI = 1)
	PARAMETER (UNITS_MET = 2)
	PARAMETER (UNITS_SEC = 3)
	PARAMETER (UNITS_DEG = 4)
	PARAMETER (UNITS_PROJ = 5)
C
C-----------------------------------------------------------------
C	LSLA default header size
	INTEGER		DEFAULT_LSLA_HEADER
C
	PARAMETER (DEFAULT_LSLA_HEADER = 32)
C
C	Maximum header size
	INTEGER		MAX_HEADER
C
	PARAMETER (MAX_HEADER=65535)
C-----------------------------------------------------------------
C	
C	Maximum DTI column and row sizes
	INTEGER		DTI_MAX_COLUMNS
	INTEGER		DTI_MAX_ROWS
C
	PARAMETER (DTI_MAX_COLUMNS = 65535)
	PARAMETER (DTI_MAX_ROWS    = 65535)
C---------------------------------------------------------------------
C
C	Corner of data origin parameters (DTI_ORDER_CORNER)
	INTEGER*4	DTI_ORDER_SW	
	INTEGER*4	DTI_ORDER_NW
	INTEGER*4	DTI_ORDER_NE
	INTEGER*4	DTI_ORDER_SE
C
	PARAMETER (DTI_ORDER_SW = 0)
	PARAMETER (DTI_ORDER_NW = 1)
	PARAMETER (DTI_ORDER_NE = 2)
	PARAMETER (DTI_ORDER_SE = 3)
C
C	Data direction parameters (DTI_ORDER_DIRECTION)
	INTEGER*4	DTI_ORDER_CLOCKWISE
	INTEGER*4	DTI_ORDER_ANTICLOCKWISE
C
	PARAMETER (DTI_ORDER_CLOCKWISE = 0)
	PARAMETER (DTI_ORDER_ANTICLOCKWISE = 1)

DTIDEF.PAR


C Parameter File Created 07OC86 for use by DTILIB.
C File contains parameters defining the layout of DTI section files
C All values are offsets in bytes from the start of the file
C
C***********************************************************************
C DMA-type DTIs (for change 2 DTED).  These have a fixed length 
C header of 256 bytes.
C
	PARAMETER DTI_DMA_TYPE =   0	! type field (UHL1)
	PARAMETER DTI_DMA_UHLSZ = 80	! UHL field size
C
C things outside the UHL
	PARAMETER DTI_DMA_EEXT =  80	! x data extent
	PARAMETER DTI_DMA_NEXT =  82	! y data extent
	PARAMETER DTI_DMA_EINT =  84	! x grid interval
	PARAMETER DTI_DMA_NINT =  88	! y grid interval
	PARAMETER DTI_DMA_WMIN =  92	! min byte or word data value
	PARAMETER DTI_DMA_WMAX =  94	! max byte or word data value
C
	PARAMETER DTI_DMA_LMIN =  96	! min long or real data value
	PARAMETER DTI_DMA_LMAX =  100	! max long or real data value
	PARAMETER DTI_DMA_DTYP =  104	! data type
C
	
	PARAMETER DTI_DMA_DATA = 256	! data area
C
C***********************************************************************
C PAN-type DTIs (sometimes known as MIKE type)
C The header is of a fixed length of 256 bytes.
C Now historical.
C
	PARAMETER DTI_PAN_TYPE =   0	! type field
	PARAMETER DTI_PAN_EEXT =   4	! x data extent
	PARAMETER DTI_PAN_NEXT =   6	! y data extent
	PARAMETER DTI_PAN_EINT =   8	! x grid interval
	PARAMETER DTI_PAN_NINT =  12	! y grid interval
	PARAMETER DTI_PAN_WMIN =  16	! min byte or word data value
	PARAMETER DTI_PAN_WMAX =  18	! max byte or word data value
C
	PARAMETER DTI_PAN_LMIN =  20	! min long or real data value
	PARAMETER DTI_PAN_LMAX =  24	! max long or real data value
	PARAMETER DTI_PAN_DTYP =  28	! data type
C
	PARAMETER DTI_PAN_DATA = 256	! start of data area
C
C***********************************************************************
C DMA DTED change 3/4 type DTI. These start off like the MIKE type
C but then have a DSI and an ACC block.  The header is of a fixed length
C of 3584 bytes.
C
	PARAMETER DTI_TED_TYPE =   0	! type field (TED4)
	PARAMETER DTI_TED_EEXT =   4	! x data extent
	PARAMETER DTI_TED_NEXT =   6	! y data extent
	PARAMETER DTI_TED_EINT =   8	! x grid interval
	PARAMETER DTI_TED_NINT =  12	! y grid interval
	PARAMETER DTI_TED_WMIN =  16	! min byte or word data value
	PARAMETER DTI_TED_WMAX =  18	! max byte or word data value
C
	PARAMETER DTI_TED_LMIN =  20	! min long or real data value
	PARAMETER DTI_TED_LMAX =  24	! max long or real data value
	PARAMETER DTI_TED_DTYP =  28	! data type
C
	PARAMETER DTI_TED_DSI  = 236	! start of DSI record
	PARAMETER DTI_TED_ACC  = 884	! start of ACC record
	PARAMETER DTI_TED_DATA =3584 	! start of data area
C
	PARAMETER DTI_TED_DSISZ= 648 	! size of DSI record
	PARAMETER DTI_TED_ACCSZ=2700 	! size of ACC record
C
C***********************************************************************
C ALVY type DTI files.  These start off like a MIKE type file, but
C have a variable length header defined by a word (30-31) in the header
C Now historical.
C
	PARAMETER DTI_ALV_TYPE =   0	! type field (ALVY)
	PARAMETER DTI_ALV_EEXT =   4	! x data extent
	PARAMETER DTI_ALV_NEXT =   6	! y data extent
	PARAMETER DTI_ALV_EINT =   8	! x data interval
	PARAMETER DTI_ALV_NINT =  12	! y data interval
	PARAMETER DTI_ALV_WMIN =  16	! min byte or word data value
	PARAMETER DTI_ALV_WMAX =  18	! max byte or word data value
C
	PARAMETER DTI_ALV_LMIN =  20	! min long or real data value
	PARAMETER DTI_ALV_LMAX =  24	! max long or real data value
C
	PARAMETER DTI_ALV_DTYP =  28	! data type
	PARAMETER DTI_ALV_DATA =  30	! location of unsigned word defining
					! start of data area (ie. length of
C					! header in bytes)
C
C***********************************************************************
C LSLA type DTI files.  These are identical to the historical ALVY
C type file.  They have a variable length header defined by word (30-31) 
C in the header
C
	PARAMETER DTI_LSLA_TYPE =   0	! type field (LSLA)
	PARAMETER DTI_LSLA_EEXT =   4	! x data extent
	PARAMETER DTI_LSLA_NEXT =   6	! y data extent
	PARAMETER DTI_LSLA_EINT =   8	! x data interval
	PARAMETER DTI_LSLA_NINT =  12	! y data interval
	PARAMETER DTI_LSLA_WMIN =  16	! min byte or word data value
	PARAMETER DTI_LSLA_WMAX =  18	! max byte or word data value
C
	PARAMETER DTI_LSLA_LMIN =  20	! min long or real data value
	PARAMETER DTI_LSLA_LMAX =  24	! max long or real data value
C
	PARAMETER DTI_LSLA_DTYP =  28	! data type
	PARAMETER DTI_LSLA_DORD =  29	! data order values
	PARAMETER DTI_LSLA_DATA =  30	! location of unsigned word defining
					! start of data area (ie. length of
C					! header in bytes)

DOCUMENTATION NOTATION

The following conventions have been followed:

     *	 all arguments are fully declared for each routine

     *	 the following input/output declarations are made:
	 
	 out - this variable will be written to by the routine
	 in  - this variable is read by the routine - it is not written to
     	 i/o - this variable may be both read by the routine, and written to

     *	 the following argument types are used:

	 byte		-  this is a Fortran BYTE (8 bit variable)
	 integer*2	-  this is a Fortran INTEGER*2 (16 bit variable)
	 integer*4	-  this is a Fortran INTEGER*4 (32 bit variable)
	 real		-  this is a Fortran REAL*4 variable
	 real*8         -  this is a Fortran REAL*8 variable
	 logical	-  this is a Fortran LOGICAL variable
	 char    	-  this is a Fortran CHARACTER variable
	 *		-  this may be a byte, integer*2, integer*4 or 
		           real value depending on the type of data
                           held in the DTI file

     *	 arguments are compulsory unless enclosed in square brackets
	 In cases where a number of arguments are optional, then if
	 one optional argument is supplied, the remaining optional
	 arguments should also be present.

LIBRARY INITIALISATION

Before using any of the routines in DTILIB, the library should be initialised by a call to DTI_INIT. This routine ensures that DTILIB error messages will be available to applications programs via a call to LSL_PUTMSG, and also establishes an exit handler to ensure DTI files are correctly unmapped on abnormal porgram exit. The routine takes no arguments.

			CALL DTI_INIT

FILE MANIPULATION

Routines to open, create, extend and close DTI files are provided. These routines interface with the routines in LSLLIB for mapping files into virtual memory.

DTI_OPEN

Opens an existing DTI file on the specified DTI_LUN; extracts header details and places these in common block DTIHDR.

In addition for files with a LSLA header structure, projection record details are placed in common DTIPROJ. Note that the DTIHDR variable HAD_PROJ_RECORD is used to indicate whether a projection record is present in the file. The DTI file is mapped into virtual memory using the LSLLIB function VIO$OPEN_SEC.


	RETVAL = DTI_OPEN ( dti_lun, filename, filename_length, 
                            write, error, [report], [pge_flt_cluster] )


	dti_lun		integer*4	in	LUN on which the file is
						to be opened.

	filename	char*128	in	DTI filename

	filename_length	integer*4	in	length of filename

	write		logical		in	.t. - allow write access 
						to file
						.f. - open for read only

	error		integer*4	out	system error code

	report		logical		in	.t. - output warning message
						if data origin and direction
						values are not default (ie.
						DTI_ORDER_CORNER = 0, and
						DTI_ORDER_DIRECTION = 0)
						.f. - no message is generated

	pge_flt_cluster	integer*4	in	page fault cluster value to be
						passed to VIO$OPEN_SEC to try 
						to improve the performance of
						programs reading large DTI 
						files where the data access
						goes against the natural order
						of the data.
						


Function return codes:

DTI_CREATE

Routine to create a DTI file with the specified name on DTI_LUN.

HEADER_TYPE determines with which type of header the file is created. In the latest implementation of DTILIB, files with a MIKE or ALVY header structure cannot be created using the library. This change is upwards compatible - if an attempt is made to create a file with a MIKE header structure (HEADER_TYPE = 1), the library will create a file with a LSLA header of length 32 bytes, while an attempt to create a file with an ALVY header structure (HEADER_TYPE = 4) will result in a file with a LSLA header.

For a LSLA header the optional argument HEADER_SIZE defines the size of the header. If no value is supplied, a file with a default header length of 32 bytes will be created. For all other types of headers (ie. UHL1 and TED4) the size of the header is fixed.

DATA_TYPE determines the sort of data that will be stored in the data area. and XSIZE and YSIZE determines the size of the data area. Note that if the file is created to hold bit data values, the y size value must be a multiple of 8.

On opening the file, filename specification details are written to the relevant common DTIHDR variables, along with details on the address and size of the memory mapped file. Details on x and y data extent, data type, data offset and header type are written to the mapped file, and to common DTIHDR variables. Note that the x and y grid interval values must be set up in common by an applications program before calling DTI_CREATE if they are to be written to the header of the mapped file.

The file is opened for write access.


	RETVAL = DTI_CREATE ( dti_lun,  filename, filename_length,
			    header_type, [header_size],
			    data_type, xsize, ysize, error )


	dti_lun		integer*4	in	LUN on which the file is
						to be opened.

	filename	char*128	in	DTI filename

	filename_length	integer*4	in	length of filename

	header_type	integer*4	in	1  - (see note above)
						2  - create file with UHL1
						     header structure 
						3  - create file with TED4
						     header structure
                                                4 -  (see note above)
						5  - create file with LSLA
						     header structure
				
	header_size	integer*4	in	optional argument defining
						the size of a LSLA type
						header.			

	data_type	integer*4	in	defines the type of data
						to be held in the file
						1  - byte 
						2  - word
						3  - longword
						4  - real
						5  - bit			
	
	xsize		integer*4	in	x extent of matrix
	    					(number of columns)

	ysize		integer*4	in	y extent of matrix
						(number of rows)

	error		integer*4	out	system error code

Function return codes:

DTI_EXTEND_DATA

Routine to extend a currently mapped DTI file by increasing the number of columns and rows in the matrix. Note that if the file to be extended contains bit data values, the value associated with the argument y_number must be a multiple of 8. The additional columns and rows created in the matrix by this routine will be given an initial value of 0.

The routine interfaces with the LSLLIB function VIO$EXTEND_SEC

The file must have been opened or created with write access.


	RETVAL = DTI_EXTEND_DATA ( dti_lun, x_number, y_number, error )


	dti_lun		integer*4	in	LUN on which the file is
						opened.

	x_number	integer*4	in	number of columns by which
						to extend

	y_number	integer*4	in	number of rows by which 
						to extend

	error		integer*4	out	system error code


Function return codes:

DTI_EXTEND_HEADER

Routine to extend a currently mapped DTI file by increasing the length of the header record. This operation is only permitted on a file with a LSLA header structure. Note that the library routine ensures the position of the data values in the mapped file are correctly adjusted to accommodate the larger header.

The routine interfaces with the LSLLIB function VIO$EXTEND_SEC

The file must have been opened or created with write access.


	RETVAL = DTI_EXTEND_HEADER ( dti_lun, number_bytes, error )


	dti_lun		integer*4	in	LUN on which the file is
						opened.

	number_bytes	integer*4	in	number of bytes by which 
						to extend the header

	error		integer*4	out	system error code


Function return codes:

DTI_CLOSE

Routine to close a currently opened DTI file, and free the DTI LUN for further use. It interfaces with the LSLLIB routine VIO$CLOSE_SEC.

If update is requested, header details in common DTIHDR are written to the mapped file before closing. If HAD_PROJ_RECORD is set to true for this file, the projection record of the mapped file is also updated before close, using the values in common DTIPROJ.


	RETVAL = DTI_CLOSE  ( dti_lun, update, clear_common, error )

	
	dti_lun		integer*4	in	LUN on which the file is
						opened.

	update		logical		in	If .true. update the
						header details of the 
						mapped file before closing.
	
	clear_common	logical		in	If .true. clear the variables
						in common DTIHDR and DTIPROJ
						relating to this file.

	error		integer*4	out	system error code

Function return codes:

DTILIB UTILITIES

A number of utility programs are provided within DTILIB.

DTI_NEXT_LUN

Routine to return the number of the next free DTI_LUN.

	RETVAL = DTI_NEXT_LUN ( dti_lun )


	dti_lun		integer*4	out	number of next free LUN

				
Function return codes:

DTI_PRINT_HEADER

Routine to output header details of the DTI file opened on the specified DTI_LUN. The details may be output in matrix units, metres or in the case of a DTI file with a TED4 or UHL1 header in degrees, minutes and seconds, or seconds.

If the DTIHDR variables DTI_WINDOW_SWX, DTI_WINDOW_SWY, DTI_WINDOW_NEX and DTI_WINDOW_NEY have been set up by an applications program, then details of the current DTI area of interest are included (see example below).

The optional rotation argument is necessary to calculate the correct geographical coordinates (in metres, latlong, seconds or projection units) if the DTI file is rotated with respect to the geographical origin. Note that the rotation argument has no effect on DTI matrix coordinates.


	RETVAL = DTI_PRINT_HEADER ( dti_lun, units, [offset], [rotation] )

	
	dti_lun		integer*4	in 	LUN on which the DTI file
						is opened

	units		integer*4	in	1 = matrix units
						2 = metres
						3 = seconds
						4 = deg, min, sec
						5 = projection units

	offset 		logical*4	in	if .t. or the argument is not
						supplied, absolute coordinate
						values are output by adding 
						X_OFFSET and Y_OFFSET
						if .f. coordinate values 
						relative to a matrix origin of
						0,0 are output

	rotation	integer*4	in      0 - SW
						1 - NW
						2 - NE
						3 - SE
						If the argument is not
						supplied, 0 is assumed.

Function return codes:

An example of how the header details are output is given below: 

LSL$DTI:TEST.DTI	
Header: TED4	 Data: WORD

Units are degrees, minutes, seconds

Matrix Origin      SW:  56 36 00N   5 15 00W
Matrix Coverage    SW:  56 36 00N   5 15 00W    NE:  56 58 12N   5 00 00W
Matrix Window      SW:  56 36 00N   5 15 00W    NE:  56 40 00N   4 32 16W
Matrix Interval	    E:	   2		 	 N:     1

Value Range	     :     0  to  1340

DTI_PRINT_PROJECTION

Routine to print projection details derived from a Projection Record of the DTI file opened on DTI_LUN. Note: The projection details are printed from the DTIPROJ common block, and not from the header of the mapped DTI file.

	RETVAL = DTI_PRINT_PROJECTION ( dti_lun )

	
	dti_lun		integer*4	in 	LUN on which the DTI file
						is opened


Function return codes:

An example of how the projection record details are output is given below: 

Spheroid      :   9 (Airy)
Projection    : 101 (UK national grid)

Units         :   2 (Metres)
Local Origin  :      440000.000 (Eastings)     80000.000 (Northings)
Sample values :	         50.000 (Eastings)        50.000 (Northings)

DTI_UNITS

Routine to test whether UNITS is valid for the file opened on DTI_LUN, or in the case where the UNITS argument is passed with a value of 0, to return a suitable default UNITS value. If the passed UNITS value is not valid for the DTI file, the function returns the error code DTI__INVUNITS.

The following rules are applied when testing the validity of UNITS:

The following rules are applied when returning a default UNITS value:

	RETVAL  = DTI_UNITS ( dti_lun, units )


	dti_lun		integer*4	in	LUN on which the DTI file
						is open

	units		integer*4       i/o	0 = derive a default unit
						type value (returned in units)
						1 = matrix 
						2 = metres
						3 = seconds of arc
						4 = latlong (degrees, minutes
						    and seconds)
						5 = projection

Function return codes:

DTI_MATRIX_TO_UNITS

Routine to convert DTI matrix column and row values to the specified units of measurement.

The optional rotation argument is necessary to calculate the correct geographical coordinates (in metres, latlong, seconds or projection units) if the DTI file is rotated with respect to the geographical origin.

Note that if latlong units are specified then coordinates are returned as seconds of arc.


	RETVAL  = DTI_MATRIX_TO_UNITS ( dti_lun, x_matrix, y_matrix, 
			                units, [rotation], [offset], 
					x_coord, y_coord )


	dti_lun		integer*4	in	LUN on which the DTI file
						is open
	x_matrix	real*4		in      x matrix coordinate (column)

	y_matrix	real*4		in      y matrix coordinate (row)

	units		integer*4       in	conversion units (ie. units 
					        of measurement of output
						coordinates)			
						1 = matrix 
						2 = metres
						3 = seconds of arc
						4 = latlong (degrees, minutes
						    and seconds)
						5 = projection

	rotation	integer*4	in      0 - SW
						1 - NW
						2 - NE
						3 - SE
						If the argument is not
						supplied, 0 is assumed.

	offset 		logical*4	in	if .t. or the argument is not
						supplied, absolute coordinate
						values are output by adding 
						X_OFFSET and Y_OFFSET
						if .f. coordinate values 
						relative to a matrix origin of
						0,0 are output

	x_coord		real*8		out     x coordinate in specified units

	y_coord		real*8		out     y coordinate in specified units

Function return codes:

DTI_UNITS_TO_MATRIX

Routine to convert x and y coordinates in the specified units of measurement to DTI matrix row and column values.

The optional rotation argument is necessary to calculate the correct matrix coordinates if the DTI file is rotated with respect to the geographical origin.

Note that if latlong units are specified then coordinates are assumed to be in seconds of arc.


	RETVAL  = DTI_UNITS_TO_MATRIX ( dti_lun, x_coord, y_coord, 
                                        units, [rotation], [offset], 
                                        x_matrix, y_matrix)


	dti_lun		integer*4	in	LUN on which the DTI file
						is open

	x_coord		real*8		in      x coordinate in specified units

	y_coord		real*8		in      y coordinate in specified units

	units		integer*4       in	1 = matrix 
						2 = metres
						3 = seconds of arc
						4 = latlong (degrees, minutes
						    and seconds)
						5 = projection

	rotation	integer*4	in      0 - SW
						1 - NW
						2 - NE
						3 - SE
						If the argument is not
						supplied, 0 is assumed.

	offset 		logical*4	in	if .t. or the argument is not
						supplied, absolute coordinate
						values are output by adding 
						X_OFFSET and Y_OFFSET
						if .f. coordinate values 
						relative to a matrix origin of
						0,0 are output

	x_matrix	real*4		out     x matrix coordinate (column)

	y_matrix	real*4		out     y matrix coordinate (row)

Function return codes:
  • DTI__NORMAL Success (units are valid)
  • DTI__INVUNITS Units not valid for the DTI file
  • DTI__BADLUN DTI_LUN out of range (1:9)
  • DTI__LUNUNUSED No file opened on DTI_LUN
  • DTI__BADUNITS Units value is invalid (not in range 0 to 5)
  • DTI__BADROTATION Unrecognised rotation type

DTI_WIN_MATRIX_TO_UNITS

Routine to convert two DTI matrix coordinates defining the south-west and north-east coordinates of an area of interest, into the specified units of measurement defining the same area.

The optional rotation argument is necessary to calculate the correct geographical coordinates (in metres, latlong, seconds or projection units) if the DTI file is rotated with respect to the geographical origin.

Note that if latlong units are specified then coordinates are returned as seconds of arc.


	RETVAL  = DTI_WIN_MATRIX_TO_UNITS ( dti_lun, x_matrix_sw, y_matrix_sw, 
					    x_matrix_ne, y_matrix_ne
			                    units, [rotation], [offset], 
					    x_coord_sw, y_coord_sw 
					    x_coord_ne, y_coord_ne )


	dti_lun		integer*4	in	LUN on which the DTI file
						is open

	x_matrix_sw	integer*4	in      sw x matrix coordinate (column)
						
	y_matrix_sw	integer*4	in      sw y matrix coordinate (row)

	x_matrix_ne	integer*4	in      ne x matrix coordinate (column)
						
	y_matrix_ne	integer*4	in      ne y matrix coordinate (row)

	units		integer*4       in	1 = matrix 
						2 = metres
						3 = seconds of arc
						4 = latlong (degrees, minutes
						    and seconds)
						5 = projection

	rotation	integer*4	in      0 - SW
						1 - NW
						2 - NE
						3 - SE
						If the argument is not
						supplied, 0 is assumed.

	offset 		logical*4	in	if .t. or the argument is not
						supplied, absolute coordinate
						values are output by adding 
						X_OFFSET and Y_OFFSET
						if .f. coordinate values 
						relative to a matrix origin of
						0,0 are output

	x_coord_sw	real*8		out     sw x coordinate in 
						specified units

	y_coord_sw	real*8		out     sw y coordinate in 
						specified units

	x_coord_ne	real*8		out     ne x coordinate in 
						specified units

	y_coord_ne	real*8		out     ne y coordinate in 
						specified units

Function return codes:
  • DTI__NORMAL Success (units are valid)
  • DTI__INVUNITS Units not valid for the DTI file
  • DTI__BADLUN DTI_LUN out of range (1:9)
  • DTI__LUNUNUSED No file opened on DTI_LUN
  • DTI__BADUNITS Units value is invalid (not in range 0 to 5)
  • DTI__BADROTATION Unrecognised rotation type
  • DTI__BADWINDOW Invalid window column and row values

DTI_WIN_UNITS_TO_MATRIX

Routine to convert two coordinates in the specified units, defining the south-west and north-east coordinates of an area of interest into DTI matrix coordinates defining the same area.

The optional rotation argument is necessary to calculate the correct matrix coordinates if the DTI file is rotated with respect to the geographical origin.

Note that if latlong units are specified then coordinates are assumed to be in seconds of arc.

	RETVAL  = DTI_WIN_UNITS_TO_MATRIX ( dti_lun, x_coord_sw, y_coord_sw, 
					    x_coord_ne, y_coord_ne
			                    units, [rotation], [offset], 
					    x_matrix_sw, y_matrix_sw 
					    x_matrix_ne, y_matrix_ne )


	dti_lun		integer*4	in	LUN on which the DTI file
						is open

	x_coord_sw	real*8		in	sw x coordinate in 
						specified units

	y_coord_sw	real*8		in	sw y coordinate in 
						specified units

	x_coord_ne	real*8		in	ne x coordinate in 
						specified units

	y_coord_ne	real*8		in	ne y coordinate in 
						specified units

	units		integer*4       in	1 = matrix 
						2 = metres
						3 = seconds of arc
						4 = latlong (degrees, minutes
						    and seconds)
						5 = projection

	rotation	integer*4	in      0 - SW
						1 - NW
						2 - NE
						3 - SE
						If the argument is not
						supplied, 0 is assumed.

	offset 		logical*4	in	if .t. or the argument is not
						supplied, absolute coordinate
						values are output by adding 
						X_OFFSET and Y_OFFSET
						if .f. coordinate values 
						relative to a matrix origin of
						0,0 are output

	x_matrix_sw	integer*4	out     sw x matrix coordinate (column)
						
	y_matrix_sw	integer*4	out     sw y matrix coordinate (row)

	x_matrix_ne	integer*4	out     ne x matrix coordinate (column)
						
	y_matrix_ne	integer*4	out     ne y matrix coordinate (row)

Function return codes:
  • DTI__NORMAL Success (units are valid)
  • DTI__INVUNITS Units not valid for the DTI file
  • DTI__BADLUN DTI_LUN out of range (1:9)
  • DTI__LUNUNUSED No file opened on DTI_LUN
  • DTI__BADUNITS Units value is invalid (not in range 0 to 5)
  • DTI__BADROTATION Unrecognised rotation type
  • DTI__BADWINDOW Invalid window column and row values

DTI_MINMAX_DATA

Routine to scan the all nodes in the data area and determine the minimum and maximum data values. The routine updates the relevant entries in DTIHDR, and if UPDATE is true, also writes the new values to the mapped DTI file.

	RETVAL  = DTI_MINMAX_DATA ( dti_lun, update, error )


	dti_lun		integer*4	in	LUN on which the DTI file
						is open

	update		logical		in	If .true. update the minimum
						and maximum data values in the 
						header of mapped file. 

	error		integer*4	out	system error code


Function return codes:
  • DTI__NORMAL Success
  • DTI__BADLUN DTI_LUN out of range (1:9)
  • DTI__LUNUNUSED No file opened on DTI_LUN
  • DTI__READONLY Update of the mapped file header was requested, but only read access to the file is permitted
  • DTI__SYSERR System error while updating the file header

DTI_WINDOW_MINMAX

Routine to scan all nodes in a DTI window (rectangular area of interest) and determine the minimum and maximum data values. The window bottom lefthand and top righthand column and row values are extracted from the DTIHDR common block variables DTI_WINDOW_SWX, DTI_WINDOW_SWY, DTI_WINDOW_NEX and DTI_WINDOW_NEY. The minimum and maximum values are returned as function arguments.

	RETVAL  = DTI_WINDOW_MINMAX ( dti_lun, min_value, max_value )


	dti_lun		integer*4	in	LUN on which the DTI file
						is open

	min_value	*               out     minimum data value


	max_value       *               out     maximum data value


Function return codes:
  • DTI__NORMAL Success
  • DTI__BADLUN DTI_LUN out of range (1:9)
  • DTI__LUNUNUSED No file opened on DTI_LUN
  • DTI__BADWINDOW Window values in DTIHDR are invalid

READ HEADER ROUTINES

A series of functions to read values from the header of the DTI file are provided. The routines use a byte offset to point to the relevant location in the header.

DTI_READ_HEADER

Routine to read the header (x,y extent, grid intervals, minimum and maximum data values, header size, data type and if appropriate latitude and longitude values) of a DTI file. The values are placed in DTIHDR. The routine is called by DTI_OPEN, but may also be called by an applications program.

	RETVAL  = DTI_READ_HEADER ( dti_lun, error )


	dti_lun		integer*4	in	LUN on which the DTI file
						is open

	error		integer*4	out	system error code

Function return codes:
  • DTI__NORMAL Success
  • DTI__BADLUN DTI_LUN out of range (1:9)
  • DTI__LUNUNUSED No file opened on DTI_LUN
  • DTI__SYSERR System error while reading from the DTI header

DTI_READ_PROJ_REC

Routine to read a DTI Projection Record. This record may only be present in an LSLA type DTI header. The start of the record is identified by means of the identifier '*DTIPROJ'. The routine transfers the Projection Record details, include the record's byte offset to the DTILIB common block DTIPROJ.

	RETVAL = DTI_READ_PROJ_REC ( dti_lun, error )


	dti_lun		integer*4	in	LUN on which the DTI file
						is open

	error		integer*4	out	system error code


Function return codes:
  • DTI__NORMAL Success
  • DTI__BADLUN DTI_LUN out of range (1:9)
  • DTI__LUNUNUSED No file opened on DTI_LUN
  • DTI__BADHEADER The file opened on DTI_LUN is not an LSLA type file
  • DTI__NOPROJREC No projection record was found in the header
  • DTI__SYSERR System error while reading from the DTI header

DTI_READ_DSI

Routine to read the DSI record of a TED4 type DTI header, and extract the latlong origin and corner values, and grid intervals. The values are placed in DTIHDR. The routine is called by DTI_OPEN, but may also be called by an applications program.

	RETVAL  = DTI_READ_DSI ( dti_lun )


	dti_lun		integer*4	in	LUN on which the DTI file
						is open

Function return codes:
  • DTI__NORMAL Success
  • DTI__BADLUN DTI_LUN out of range (1:9)
  • DTI__LUNUNUSED No file opened on DTI_LUN
  • DTI__BADHEADER The file opened on DTI_LUN is not a TED4 type file
  • DTI__BADDSI DSI record did not conform to the usual format

DTI_READ_UHL

Routine to read the UHL record of a UHL1 type DTI header, and extract the latlong corner values, and grid intervals. The values are placed in DTIHDR. The routine is called by DTI_OPEN, but may also be called by an applications program.

Note that the routine sets the latlong origin values in DTIHDR to be equal to the latlong S.W. corner.


	RETVAL  = DTI_READ_UHL ( dti_lun )


	dti_lun		integer*4	in	LUN on which the DTI file
						is open

Function return codes:
  • DTI__NORMAL Success
  • DTI__BADLUN DTI_LUN out of range (1:9)
  • DTI__LUNUNUSED No file opened on DTI_LUN
  • DTI__BADHEADER The file opened on DTI_LUN is not a UHL1 type file
  • DTI__BADUHL The UHL record did not conform to the usual format

DTI_READ_BYTE_HEADER

Routine to read a byte value from the header area.

	RETVAL  = DTI_READ_BYTE_HEADER ( dti_lun, value, byte_offset, error )


	dti_lun		integer*4	in	LUN on which the DTI file
						is open

	value		byte	  	out	value of byte

	byte_offset	integer*4	in	offset in header specified
						in bytes

	error		integer*4	out	system error code

Function return codes:
  • DTI__NORMAL Success
  • DTI__BADLUN DTI_LUN out of range (1:9)
  • DTI__LUNUNUSED No file opened on DTI_LUN
  • DTI__BADHEADOFF Byte offset out of range (0:Header Size-1)
  • DTI__SYSERR System error while reading from the DTI header record

DTI_READ_WORD_HEADER

Routine to read a word (INTEGER*2) from the header area

	RETVAL  = DTI_READ_WORD_HEADER ( dti_lun, value, byte_offset, error )


	dti_lun		integer*4	in	LUN on which the DTI file
						is open

	value		integer*2  	out	value of word

	byte_offset	integer*4	in	offset in header specified
						in bytes

	error		integer*4	out	system error code

Function return codes:
  • DTI__NORMAL Success
  • DTI__BADLUN DTI_LUN out of range (1:9)
  • DTI__LUNUNUSED No file opened on DTI_LUN
  • DTI__BADHEADOFF Byte offset out of range (0:Header Size-2)
  • DTI__SYSERR System error while reading from the DTI header record

DTI_READ_LONG_HEADER

Routine to read a longword (INTEGER*4) from the header area

	RETVAL  = DTI_READ_LONG_HEADER ( dti_lun, value, byte_offset, error )


	dti_lun		integer*4	in	LUN on which the DTI file
						is open

	value		integer*4  	out	value of longword

	byte_offset	integer*4	in	offset in header specified
						in bytes

	error		integer*4	out	system error code

Function return codes:
  • DTI__NORMAL Success
  • DTI__BADLUN DTI_LUN out of range (1:9)
  • DTI__LUNUNUSED No file opened on DTI_LUN
  • DTI__BADHEADOFF Byte offset out of range (0:Header Size-4)
  • DTI__SYSERR System error while reading from the DTI header record

DTI_READ_REAL_HEADER

Routine to read a real value from the header area

	RETVAL  = DTI_READ_REAL_HEADER ( dti_lun, value, byte_offset, error )


	dti_lun		integer*4	in	LUN on which the DTI file
						is open

	value		real	  	out	value of real 

	byte_offset	integer*4	in	offset in header specified
						in bytes

	error		integer*4	out	system error code

Function return codes:
  • DTI__NORMAL Success
  • DTI__BADLUN DTI_LUN out of range (1:9)
  • DTI__LUNUNUSED No file opened on DTI_LUN
  • DTI__BADHEADOFF Byte offset out of range (0:Header Size-4)
  • DTI__SYSERR System error while reading from the DTI header record

DTI_READ_REAL8_HEADER

Routine to read a real value from the header area

	RETVAL  = DTI_READ_REAL8_HEADER ( dti_lun, value, byte_offset, error )


	dti_lun		integer*4	in	LUN on which the DTI file
						is open

	value		real*8	  	out	value of real*8 

	byte_offset	integer*4	in	offset in header specified
						in bytes

	error		integer*4	out	system error code

Function return codes:
  • DTI__NORMAL Success
  • DTI__BADLUN DTI_LUN out of range (1:9)
  • DTI__LUNUNUSED No file opened on DTI_LUN
  • DTI__BADHEADOFF Byte offset out of range (0:Header Size-8)
  • DTI__SYSERR System error while reading from the DTI header record

READ DATA ROUTINES

A series of functions to read values from the DTI data area are provided. The routines are passed a x and y position defining the location of the value to be read.

DTI_READ_DATA

Generic routine to read a value from the data area. The routine determines the type of data stored in the file, and calls the appropriate DTILIB reading routine (see below).

	RETVAL  = DTI_READ_DATA (dti_lun, value, x_position, y_position)
	
	dti_lun		integer*4	in	LUN on which the DTI file
						is open

	value		*		out	data value

	x_position	integer*4	in	column 

	y_position	integer*4	in	row 


Function return codes:
  • DTI__NORMAL Success
  • DTI__BADLUN DTI_LUN out of range (1:9)
  • DTI__LUNUNUSED No file opened on DTI_LUN
  • DTI__BADDATAPOS The x and y position does not lie within the data area

DTI_READ_BIT_DATA

Routine to read a bit value from the data area.

	RETVAL  = DTI_READ_BIT_DATA ( dti_lun, value, x_position, y_position )
	

	dti_lun		integer*4	in	LUN on which the DTI file
						is open

	value		byte		out	value of bit (0 or 1)

	x_position	integer*4	in	column 

	y_position	integer*4	in	row 


Function return codes:
  • DTI__NORMAL Success
  • DTI__BADLUN DTI_LUN out of range (1:9)
  • DTI__LUNUNUSED No file opened on DTI_LUN
  • DTI__DATAMISMATCH The DTI file is not set up to contain bit data
  • DTI__BADDATAPOS The x and y position does not lie within the data area

DTI_READ_BYTE_DATA

Routine to read a byte value from the data area.

	RETVAL  = DTI_READ_BYTE_DATA ( dti_lun, value, x_position, y_position )
	

	dti_lun		integer*4	in	LUN on which the DTI file
						is open

	value		byte		out	value of byte

	x_position	integer*4	in	column 

	y_position	integer*4	in	row 


Function return codes:
  • DTI__NORMAL Success
  • DTI__BADLUN DTI_LUN out of range (1:9)
  • DTI__LUNUNUSED No file opened on DTI_LUN
  • DTI__DATAMISMATCH The DTI file is not set up to contain byte data
  • DTI__BADDATAPOS The x and y position does not lie within the data area

DTI_READ_WORD_DATA

Routine to read a word (INTEGER*2) from the data area.

	RETVAL  = DTI_READ_WORD_DATA ( dti_lun, value, x_position, y_position )

	
	dti_lun		integer*4	in	LUN on which the DTI file
						is open

	value		integer*2	out	value of word 		

	x_position	integer*4	in	column

	y_position	integer*4	in	row


Function return codes:
  • DTI__NORMAL Success
  • DTI__BADLUN DTI_LUN out of range (1:9)
  • DTI__LUNUNUSED No file opened on DTI_LUN
  • DTI__DATAMISMATCH The DTI file is not set up to contain word data
  • DTI__BADDATAPOS The x and y position does not lie within the data area

DTI_READ_LONG_DATA

Routine to read a longword (INTEGER*4) from the data area.

	RETVAL  = DTI_READ_LONG_DATA ( dti_lun, value, x_position, y_position )
	

	dti_lun		integer*4	in	LUN on which the DTI file
						is open

	value		integer*4	out	value of longword

	x_position	integer*4	in	column

	y_position	integer*4	in	row


Function return codes:
  • DTI__NORMAL Success
  • DTI__BADLUN DTI_LUN out of range (1:9)
  • DTI__LUNUNUSED No file opened on DTI_LUN
  • DTI__DATAMISMATCH The DTI file is not set up to contain longword data
  • DTI__BADDATAPOS The x and y position does not lie within the data area

DTI_READ_REAL_DATA

Routine to read a real value from the data area.

	RETVAL  = DTI_READ_REAL_DATA ( dti_lun, value, x_position, y_position )

	
	dti_lun		integer*4	in	LUN on which the DTI file
						is open

	value		real		out	real value 		

	x_position	integer*4	in	column

	y_position	integer*4	in	row


Function return codes:
  • DTI__NORMAL Success
  • DTI__BADLUN DTI_LUN out of range (1:9)
  • DTI__LUNUNUSED No file opened on DTI_LUN
  • DTI__DATAMISMATCH The DTI file is not set up to contain real data
  • DTI__BADDATAPOS The x and y position does not lie within the data area

WRITE HEADER ROUTINES

A number of routines to write information to the header area of the DTI file are provided.

DTI_WRITE_HEADER

Routine to write the DTI header, consisting of header type, x,y extent, grid intervals, minimum and maximum data values, header size, data type, and if appropriate latitude and longitude values, to a mapped DTI file. The values to be written are passed via DTIHDR. The routine is called by DTI_CLOSE if the option to update is selected, and may be called by an applications program.


	RETVAL = DTI_WRITE_HEADER ( dti_lun, error )
 

	dti_lun		integer*4	in	LUN on which the DTI file
						is open

	error		integer*4	out	system error code


Function return codes:
  • DTI__NORMAL Success
  • DTI__BADLUN DTI_LUN out of range (1:9)
  • DTI__LUNUNUSED No file opened on DTI_LUN
  • DTI__READONLY Only read access to the file is permitted
  • DTI__SYSERR System error writing the header values to the file

DTI_WRITE_PROJ_REC

Routine to write a DTI Projection Record. This record may only be written to an LSLA type DTI header. The start of the record is identified by means of the identifier '*DTIPROJ'. The routine extracts Projection Record details from the DTILIB common block DTIPROJ.

Note that if the optional argument BYTE_OFFSET is not supplied, the Projection Record is written to the byte offset specified in the variable DTIPROJ_RECORD_OFFSET.


	RETVAL = DTI_WRITE_PROJ_REC ( dti_lun, [byte_offset], error )


	dti_lun		integer*4	in	LUN on which the DTI file
						is open

	byte_offset	integer*4	in      offset in header specified
						in bytes

	error		integer*4	out	system error code


Function return codes:
  • DTI__NORMAL Success
  • DTI__BADLUN DTI_LUN out of range (1:9)
  • DTI__LUNUNUSED No file opened on DTI_LUN
  • DTI__BADHEADER The file opened on DTI_LUN is not a LSLA type file
  • DTI__BADHEADOFF Byte offset out of range (0:Header Size-1)
  • DTI__HEADTOOSMALL The file header is too small to hold a Projection Record (ie. Less than DEFAULT_LSLA_HEADER + DTIPROJ_RECORD_LENGTH)
  • DTI__READONLY Only read access to the file is permitted

DTI_WRITE_DSI

Routine to write the latlong origin and corner values, grid interval in seconds and data extent values, to the DSI record of a TED4 type DTI file. The routine is called by DTI_WRITE_HEADER, but may also be called by an applications program.

	RETVAL  = DTI_WRITE_DSI ( dti_lun, error )


	dti_lun		integer*4	in	LUN on which the DTI file
						is open

	error		integer*4	out	system error code


Function return codes:
  • DTI__NORMAL Success
  • DTI__BADLUN DTI_LUN out of range (1:9)
  • DTI__LUNUNUSED No file opened on DTI_LUN
  • DTI__BADHEADER The file opened on DTI_LUN is not a TED4 type file
  • DTI__READONLY Only read access to the file is permitted
  • DTI__SYSERR System error writing the header values to the file

DTI_WRITE_UHL

Routine to write the latlong S.W. corner values, and grid intervals to the UHL record of a UHL1 type DTI file.

The routine is called by DTI_WRITE_HEADER, but may also be called by an applications program.


	RETVAL  = DTI_WRITE_UHL ( dti_lun, error )


	dti_lun		integer*4	in	LUN on which the DTI file
						is open

	error		integer*4	out	system error code


Function return codes:
  • DTI__NORMAL Success
  • DTI__BADLUN DTI_LUN out of range (1:9)
  • DTI__LUNUNUSED No file opened on DTI_LUN
  • DTI__BADHEADER The file opened on DTI_LUN is not a UHL1 type file
  • DTI__READONLY Only read access to the file is permitted
  • DTI__SYSERR System error writing the header values to the file

DTI_WRITE_BYTE_HEADER

Routine to write a byte value into the header area

	RETVAL  = DTI_WRITE_BYTE_HEADER ( dti_lun, value, byte_offset, error )


	dti_lun		integer*4	in	LUN on which the DTI file
						is open

	value		byte	  	in	value of byte

	byte_offset	integer*4	in	offset in header specified
						in bytes

	error		integer*4	out	system error code

Function return codes:
  • DTI__NORMAL Success
  • DTI__BADLUN DTI_LUN out of range (1:9)
  • DTI__LUNUNUSED No file opened on DTI_LUN
  • DTI__BADHEADOFF Byte offset out of range (0:Header Size-1)
  • DTI__READONLY Only read access to the file is permitted
  • DTI__SYSERR System error writing the header values to the file

DTI_WRITE_WORD_HEADER

Routine to write a word (INTEGER*2) into the header area

	RETVAL  = DTI_WRITE_WORD_HEADER ( dti_lun, value, byte_offset, error )


	dti_lun		integer*4	in	LUN on which the DTI file
						is open

	value		integer*2  	in	value of word

	byte_offset	integer*4	in	offset in header specified
						in bytes

	error		integer*4	out	system error code

Function return codes:
  • DTI__NORMAL Success
  • DTI__BADLUN DTI_LUN out of range (1:9)
  • DTI__LUNUNUSED No file opened on DTI_LUN
  • DTI__BADHEADOFF Byte offset out of range (0:Header Size-2)
  • DTI__READONLY Only read access to the file is permitted
  • DTI__SYSERR System error writing the header values to the file

DTI_WRITE_LONG_HEADER

Routine to write a longword (INTEGER*4) into the header area

	RETVAL  = DTI_WRITE_LONG_HEADER ( dti_lun, value, byte_offset, error )


	dti_lun		integer*4	in	LUN on which the DTI file
						is open

	value		integer*4	in	value of longword

	byte_offset	integer*4	in	offset in header specified
						in bytes

	error		integer*4	out	system error code

Function return codes:
  • DTI__NORMAL Success
  • DTI__BADLUN DTI_LUN out of range (1:9)
  • DTI__LUNUNUSED No file opened on DTI_LUN
  • DTI__BADHEADOFF Byte offset out of range (0:Header Size-4)
  • DTI__READONLY Only read access to the file is permitted
  • DTI__SYSERR System error writing the header values to the file

DTI_WRITE_REAL_HEADER

Routine to write a real value into the header area

	RETVAL  = DTI_WRITE_REAL_HEADER ( dti_lun, value, byte_offset, error )


	dti_lun		integer*4	in	LUN on which the DTI file
						is open

	value		real	  	in	value of real

	byte_offset	integer*4	in	offset in header specified
						in bytes

	error		integer*4	out	error number

Function return codes:
  • DTI__NORMAL Success
  • DTI__BADLUN DTI_LUN out of range (1:9)
  • DTI__LUNUNUSED No file opened on DTI_LUN
  • DTI__BADHEADOFF Byte offset out of range (0:Header Size-4)
  • DTI__READONLY Only read access to the file is permitted
  • DTI__SYSERR System error writing the header values to the file

DTI_WRITE_REAL8_HEADER

Routine to write a real value into the header area

	RETVAL  = DTI_WRITE_REAL8_HEADER ( dti_lun, value, byte_offset, error )


	dti_lun		integer*4	in	LUN on which the DTI file
						is open

	value		real*8	  	in	value of real*8

	byte_offset	integer*4	in	offset in header specified
						in bytes

	error		integer*4	out	error number

Function return codes:
  • DTI__NORMAL Success
  • DTI__BADLUN DTI_LUN out of range (1:9)
  • DTI__LUNUNUSED No file opened on DTI_LUN
  • DTI__BADHEADOFF Byte offset out of range (0:Header Size-8)
  • DTI__READONLY Only read access to the file is permitted
  • DTI__SYSERR System error writing the header values to the file

WRITE DATA ROUTINES

Routines to write to the DTI data area are provided. The routines are passed a x and y data position defining the location at which to write.

DTI_WRITE_DATA

Generic routine to write a value to the data area. The routine determines the type of data stored in the file, and calls the appropriate DTILIB writing routine (see below).

	RETVAL  = DTI_WRITE_DATA ( dti_lun, value, x_position, y_position )

	
	dti_lun		integer*4	in	LUN on which the DTI file
						is open

	value		*		in	data value

	x_position	integer*4	in	column

	y_position	integer*4	in	row


Function return codes:
  • DTI__NORMAL Success
  • DTI__BADLUN DTI_LUN out of range (1:9)
  • DTI__LUNUNUSED No file opened on DTI_LUN
  • DTI__BADDATAPOS The x and y position does not lie within the data area
  • DTI__BADDATAVALUE Data value is invalid for bit data. A value of 0 or 1 is required.
  • DTI__READONLY Only read access to the file is permitted

DTI_WRITE_BIT_DATA

Routine to write a bit value to the data area.

	RETVAL  = DTI_WRITE_BIT_DATA ( dti_lun, value, x_position, y_position )

	
	dti_lun		integer*4	in	LUN on which the DTI file
						is open

	value		byte		in	bit value as byte (0 or 1)

	x_position	integer*4	in	column

	y_position	integer*4	in	row


Function return codes:
  • DTI__NORMAL Success
  • DTI__BADLUN DTI_LUN out of range (1:9)
  • DTI__LUNUNUSED No file opened on DTI_LUN
  • DTI__DATAMISMATCH The DTI file is not set up to contain bit data
  • DTI__BADDATAPOS The x and y position does not lie within the data area
  • DTI__BADDATAVALUE Data value is invalid for bit data. Value of 0 or 1 required.
  • DTI__READONLY Only read access to the file is permitted

DTI_WRITE_BYTE_DATA

Routine to write a byte value to the data area.

	RETVAL  = DTI_WRITE_BYTE_DATA ( dti_lun, value, x_position, y_position )

	
	dti_lun		integer*4	in	LUN on which the DTI file
						is open

	value		byte		in	byte value

	x_position	integer*4	in	column

	y_position	integer*4	in	row


Function return codes:
  • DTI__NORMAL Success
  • DTI__BADLUN DTI_LUN out of range (1:9)
  • DTI__LUNUNUSED No file opened on DTI_LUN
  • DTI__DATAMISMATCH The DTI file is not set up to contain byte data
  • DTI__BADDATAPOS The x and y position does not lie within the data area
  • DTI__READONLY Only read access to the file is permitted

DTI_WRITE_WORD_DATA

Routine to write a word (INTEGER*2) to the data area.

	RETVAL  = DTI_WRITE_WORD_DATA ( dti_lun, value, x_position, y_position )

	
	dti_lun		integer*4	in	LUN on which the DTI file
						is open

	value		integer*2	in	value of word

	x_position	integer*4	in	column

	y_position	integer*4	in	row

Function return codes:
  • DTI__NORMAL Success
  • DTI__BADLUN DTI_LUN out of range (1:9)
  • DTI__LUNUNUSED No file opened on DTI_LUN
  • DTI__DATAMISMATCH The DTI file is not set up to contain word data
  • DTI__BADDATAPOS The x and y position does not lie within the data area
  • DTI__READONLY Only read access to the file is permitted

DTI_WRITE_LONG_DATA

Routine to write a longword (INTEGER*4) to the data area.

	RETVAL  = DTI_WRITE_LONG_DATA ( dti_lun, value, x_position, y_position )

	
	dti_lun		integer*4	in	LUN on which the DTI file
						is open

	value		integer*4	in	value of longword

	x_position	integer*4	in	column

	y_position	integer*4	in	row

Function return codes:
  • DTI__NORMAL Success
  • DTI__BADLUN DTI_LUN out of range (1:9)
  • DTI__LUNUNUSED No file opened on DTI_LUN
  • DTI__DATAMISMATCH The DTI file is not set up to contain longword data
  • DTI__BADDATAPOS The x and y position does not lie within the data area
  • DTI__READONLY Only read access to the file is permitted

DTI_WRITE_REAL_DATA

Routine to write a real value to the data area.

	RETVAL  = WRITE_REAL_DATA ( dti_lun, value, x_position, y_position )

	
	dti_lun		integer*4	in	LUN on which the DTI file
						is open

	value		real	    	in	value of real

	x_position	integer*4   	in	column

	y_position	integer*4   	in	row


Function return codes:
  • DTI__NORMAL Success
  • DTI__BADLUN DTI_LUN out of range (1:9)
  • DTI__LUNUNUSED No file opened on DTI_LUN
  • DTI__DATAMISMATCH The DTI file is not set up to contain real data
  • DTI__BADDATAPOS The x and y position does not lie within the data area
  • DTI__READONLY Only read access to the file is permitted

COPY HEADER FUNCTIONS

Routines to copy the header details from one mapped file to another mapped file, and to copy from a user byte array to the header area or from the header area to a user byte array are provided.

DTI_COPY_BYTE_HEADER

Function to transfer byte data from the DTI header area to a user byte array, or from a byte array to the DTI header area.

	RETVAL = DTI_COPY_BYTE_HEADER ( dti_lun, user_array, to,
				      number_bytes, byte_offset, error )

	dti_lun		integer*4	in	LUN on which the DTI file
						is open

	user_array	byte 		i/o	user byte array 

	to		logical		in	.t. copy from user array
						to header area
						.f. copy from header area
						to user array
						
	number_bytes	integer*4	in	number of bytes to transfer

	byte_offset	integer*4	in	offset in header specified
						in bytes

	error		integer*4	out	system error code

	
Function return codes:
  • DTI__NORMAL Success
  • DTI__BADLUN DTI_LUN out of range (1:9)
  • DTI__LUNUNUSED No file opened on DTI_LUN
  • DTI__BADHEADOFF Byte offset out of range (0:Header Size-number_bytes)
  • DTI__SYSERR System error writing to or reading from the DTI header
  • DTI__READONLY Transfer to the DTI file was requested, but only read access to the file is permitted

DTI_COPY_HEADER

Function to copy part of the header of one mapped DTI file to another mapped DTI file. The two files must have the same type of header structure.

How much and which part of the header is copied is determined by the header types. If both files have a UHL1 header then the UHL field is transferred; if both files have a DTED header then the DSI and ACC fields are transferred, and if both files have a LSLA header then the free format part of the header is copied. In addition for LSLA files, details from any projection record are copied from the input to the output file (and transferred to the relevant DTIPROJ variables), along with the data order values.

NB. The extent, grid and minimum and maximum data values contained in the first part of the header are not copied by the function. To transfer grid and minmax values from the source DTI file, to the destination DTI file, an applications program should transfer the values via common DTIHDR and select the update option in DTI_CLOSE.


	RETVAL  = DTI_COPY_HEADER  ( from_dti_lun, to_dti_lun, error,
                                     [projection] )

	
	from_dti_lun	integer*4	in	LUN on which DTI file with
						header to copy is opened

	to_dti_lun	integer*4	in	LUN on which DTI file to
						receive header is opened

	error		integer*4	out	system error code

	projection	logical*4	in      if .t. or absent, copy
						the projection record
						information
						if. f. don't transfer
						projection record data

Function return codes:
  • DTI__NORMAL Success
  • DTI__BADLUN DTI_LUN out of range (1:9)
  • DTI__LUNUNUSED No file opened on one of the specified LUNs
  • DTI__HEADMISMATCH The two files have different header structures
  • DTI__BADHEADSIZE The size of the header opened on to_dti_lun is smaller than the header of the file opened on from_dti_lun
  • DTI__SYSERR System error occurred during read or write
  • DTI__READONLY Only read access to the output file is permitted

COPY DATA FUNCTIONS

A series of routines to allow an array of data to be written to the data area, or data to be transferred from the data area to a user array are provided.

DTI_COPY_DATA

Generic function to copy data values from the data area to a user array, or from a user array to the data area. The function determines the type of data stored in the file, and calls the appropriate data copying routines (see below).

	RETVAL  = DTI_COPY_DATA  ( dti_lun, user_array, to, 
				   x_start, y_start, 
				   x_number, y_number, error )
	
	dti_lun		integer*4	in	LUN on which the DTI file
						is open

	user_array	* 		i/o	user array 

	to		logical		in	.t. copy from user array
						to data area
						.f. copy from data area
						to user array
						
	x_start		integer*4	in	start column

	y_start		integer*4	in	start row

	x_number	integer*4	in	number of columns of data to
						transfer

	y_number	integer*4	in	number of rows of data to
						transfer

	error		integer*4	out	system error code


Function return codes:
  • DTI__NORMAL Success
  • DTI__BADLUN DTI_LUN out of range (1:9)
  • DTI__LUNUNUSED No file opened on DTI_LUN
  • DTI__BADDATAPOS x_start or y_start outside data area
  • DTI__BADDATAEXT Rectangular area of interest does not lie within the data area
  • DTI__READONLY Transfer to the DTI file was requested, but only read access to the file is permitted
  • DTI__SYSERR System error occurred during read or write

DTI_COPY_BIT_DATA

Function to copy bit data from the DTI data area to a user byte array, or from a byte array to the DTI data area. Note that for efficiency the routine will copy the bit data as a series of bytes, consisting of 8 bits. For this reason the function must be supplied with a y_start value that is a bit offset from the start of the data area that coincides with the start of a byte (eg. 1,9,17), and a y_number value that is a multiple of 8. The same restrictions do no apply to the values associated with the arguments x_start and x_number.

	RETVAL  = DTI_COPY_BIT_DATA  ( dti_lun, user_array, to, 
				      x_start, y_start, 
				      x_number, y_number, error )
	
	dti_lun		integer*4	in	LUN on which the DTI file
						is open

	user_array	byte 		i/o	user byte array 

	to		logical		in	.t. copy from user array
						to data area
						.f. copy from data area
						to user array
						
	x_start		integer*4	in	start column

	y_start		integer*4	in	start row

	x_number	integer*4	in	number of columns of data to
						transfer

	y_number	integer*4	in	number of rows of data to
						transfer

	error		integer*4	out	system error code


Function return codes:
  • DTI__NORMAL Success
  • DTI__BADLUN DTI_LUN out of range (1:9)
  • DTI__LUNUNUSED No file opened on DTI_LUN
  • DTI__DATAMISMATCH The DTI file is not set up to contain bit data
  • DTI__BADDATAPOS x_start or y_start outside data area
  • DTI__BADDATAEXT Rectangular area of interest does not lie within the data area
  • DTI__INVYSTART Y start is invalid for bit data. The value must represent a bit offset that coincides with a byte boundary.
  • DTI__INVYEXTENT Y extent is invalid for bit data. The value supplied with y_number should be a multiple of 8.
  • DTI__READONLY Transfer to the DTI file was requested, but only read access to the file is permitted
  • DTI__SYSERR System error occurred during read or write

DTI_COPY_BYTE_DATA

Function to copy byte data from the DTI data area to a user byte array, or from a byte array to the DTI data area.

	RETVAL  = DTI_COPY_BYTE_DATA  ( dti_lun, user_array, to, 
				      x_start, y_start, 
				      x_number, y_number, error )
	
	dti_lun		integer*4	in	LUN on which the DTI file
						is open

	user_array	byte 		i/o	user byte array 

	to		logical		in	.t. copy from user array
						to data area
						.f. copy from data area
						to user array
						
	x_start		integer*4	in	start column

	y_start		integer*4	in	start row

	x_number	integer*4	in	number of columns of data to
						transfer

	y_number	integer*4	in	number of rows of data to
						transfer

	error		integer*4	out	system error code


Function return codes:
  • DTI__NORMAL Success
  • DTI__BADLUN DTI_LUN out of range (1:9)
  • DTI__LUNUNUSED No file opened on DTI_LUN
  • DTI__DATAMISMATCH The DTI file is not set up to contain byte data
  • DTI__BADDATAPOS x_start or y_start outside data area
  • DTI__BADDATAEXT Rectangular area of interest does not lie within the data area
  • DTI__READONLY Transfer to the DTI file was requested, but only read access to the file is permitted
  • DTI__SYSERR System error occurred during read or write

DTI_COPY_WORD_DATA

Function to copy word data (INTEGER*2) from the DTI data area to a user word array, or from a word array to the DTI data area.

	RETVAL  = DTI_COPY_WORD_DATA  ( dti_lun, user_array, to, 
  				      x_start, y_start,
			              x_number, y_number, error )

	
	dti_lun		integer*4	in	LUN on which the DTI file
						is open

	user_array	integer*2	i/o	user word array 

	to		logical		in	.t. copy from user array
						to data area
						.f. copy from data area
						to user array
						
	x_start		integer*4	in	start column

	y_start		integer*4	in	start row

	x_number	integer*4	in	number of columns of data to
						transfer

	y_number	integer*4	in	number of rows of data to
						transfer

	error		integer*4	out	system error code


Function return codes:
  • DTI__NORMAL Success
  • DTI__BADLUN DTI_LUN out of range (1:9)
  • DTI__LUNUNUSED No file opened on DTI_LUN
  • DTI__DATAMISMATCH The DTI file is not set up to contain word data
  • DTI__BADDATAPOS x_start or y_start outside data area
  • DTI__BADDATAEXT Rectangular area of interest does not lie within the data area
  • DTI__READONLY Transfer to the DTI file was requested, but only read access to the file is permitted
  • DTI__SYSERR System error occurred during read or write

DTI_COPY_LONG_DATA

Function to copy longword data (INTEGER*4) from the DTI data area to a user longword array, or from a longword array to the DTI data area.

	RETVAL  = DTI_COPY_LONG_DATA  ( dti_lun, user_array, to, 
  				      x_start, y_start,
			              x_number, y_number, error )

	
	dti_lun		integer*4	in	LUN on which the DTI file
						is open

	user_array	integer*4	i/o	user longword array 

	to		logical		in	.t. copy from user array
						to data area
						.f. copy from data area
						to user array
						
	x_start		integer*4	in	start column

	y_start		integer*4	in	start row

	x_number	integer*4	in	number of columns of data to
						transfer

	y_number	integer*4	in	number of rows of data to
						transfer

	error		integer*4	out	system error code


Function return codes:
  • DTI__NORMAL Success
  • DTI__BADLUN DTI_LUN out of range (1:9)
  • DTI__LUNUNUSED No file opened on DTI_LUN
  • DTI__DATAMISMATCH The DTI file is not set up to contain longword data
  • DTI__BADDATAPOS x_start or y_start outside data area
  • DTI__BADDATAEXT Rectangular area of interest does not lie within the data area
  • DTI__READONLY Transfer to the DTI file was requested, but only read access to the file is permitted
  • DTI__SYSERR System error occurred during read or write

DTI_COPY_REAL_DATA

Function to copy real data from the DTI data area to a user real array, or from a real array to the DTI data area.

	RETVAL  = DTI_COPY_REAL_DATA  ( dti_lun, user_array, to, 
  				      x_start, y_start,
			              x_number, y_number, error )

	
	dti_lun		integer*4	in	LUN on which the DTI file
						is open
	
	user_array	real		i/o	user real array 

	to		logical		in	.t. copy from user array
						to data area
						.f. copy from data area
						to user array
						
	x_start		integer*4	in	start column

	y_start		integer*4	in	start row

	x_number	integer*4	in	number of columns of data to
						transfer

	y_number	integer*4	in	number of rows of data to
						transfer

	error		integer*4	out	system error code


Function return codes:
  • DTI__NORMAL Success
  • DTI__BADLUN DTI_LUN out of range (1:9)
  • DTI__LUNUNUSED No file opened on DTI_LUN
  • DTI__DATAMISMATCH The DTI file is not set up to contain real data
  • DTI__BADDATAPOS x_start or y_start outside data area
  • DTI__BADDATAEXT Rectangular area of interest does not lie within the data area
  • DTI__READONLY Transfer to the DTI file was requested, but only read access to the file is permitted
  • DTI__SYSERR System error occurred during read or write

INITIALISE DATA AREA

A number of routines which enable the whole or part of the data area to be set to a particular value are provided.

DTI_INIT_DATA

Generic function to set a rectangular area in the DTI data area to a specified value. The routine determines the type of data stored in the file, and calls the appropriate data initialisation routine (see below).

	RETVAL  = DTI_INIT_DATA ( dti_lun, value, 
				  [x_position], [,y_position],
				  [x_number], [y_number] )
	
	dti_lun		integer*4	in	LUN on which the DTI file
						is open

	value		*		in	data value

	x_position	integer*4	in	start column

	y_position	integer*4	in	start row

	x_number	integer*4	in	number of columns

	y_number	integer*4	in	number of rows


Function return codes:
  • DTI__NORMAL Success
  • DTI__BADLUN DTI_LUN out of range (1:9)
  • DTI__LUNUNUSED No file opened on DTI_LUN
  • DTI__BADATAPOS Start column and row values do not lie within the data area
  • DTI__BADDATAEXT Rectangular area of interest does not lie within the data area
  • DTI__BADDATAVALUE Data value is invalid for bit data. A value of 0 or 1 is required.
  • DTI__READONLY Only read access to the file is permitted
  • DTI__MISSARGS Some but not all of the optional arguments are present

DTI_INIT_BIT_DATA

Routine to set a rectangular area in the DTI data area to a specified bit value. If the optional arguments x_position, y_position, x_number and y_number are missing, the whole of the data area is set to the supplied value.

	RETVAL  = DTI_INIT_BIT_DATA ( dti_lun, value, 
				     [x_position], [y_position],
				     [x_number], [y_number] )

	dti_lun		integer*4	in	LUN on which the DTI file
						is open

	value		byte		in	bit value as byte (0 or 1)

	x_position	integer*4	in	start column

	y_position	integer*4	in	start row

	x_number	integer*4	in	number of columns

	y_number	integer*4	in	number of rows


Function return codes:
  • DTI__NORMAL Success
  • DTI__BADLUN DTI_LUN out of range (1:9)
  • DTI__LUNUNUSED No file opened on DTI_LUN
  • DTI__DATAMISMATCH The DTI file is not set up to contain bit data
  • DTI__BADATAPOS Start column and row values do not lie within the data area
  • DTI__BADDATAEXT Rectangular area of interest does not lie within the data area
  • DTI__BADDATAVALUE Data value is invalid for bit data. A value of 0 or 1 is required.
  • DTI__READONLY Only read access to the file is permitted
  • DTI__MISSARGS Some but not all of the optional arguments are present

DTI_INIT_BYTE_DATA

Routine to set a rectangular area in the DTI data area to a specified byte value. If the optional arguments x_position, y_position, x_number and y_number are missing, the whole of the data area is set to the supplied value.

	RETVAL  = DTI_INIT_BYTE_DATA ( dti_lun, value, 
				      [x_position], [y_position],
				      [x_number], [y_number] )
	
	dti_lun		integer*4	in	LUN on which the DTI file
						is open

	value		byte		in	byte value

	x_position	integer*4	in	start column

	y_position	integer*4	in	start row

	x_number	integer*4	in	number of columns

	y_number	integer*4	in	number of rows


Function return codes:
  • DTI__NORMAL Success
  • DTI__BADLUN DTI_LUN out of range (1:9)
  • DTI__LUNUNUSED No file opened on DTI_LUN
  • DTI__DATAMISMATCH The DTI file is not set up to contain byte data
  • DTI__BADATAPOS Start column and row values do not lie within the data area
  • DTI__BADDATAEXT Rectangular area of interest does not lie within the data area
  • DTI__READONLY Only read access to the file is permitted
  • DTI__MISSARGS Some but not all of the optional arguments are present

DTI_INIT_WORD_DATA

Routine to set a rectangular area in the DTI data area to a specified word (INTEGER*2) value. If the optional arguments x_position, y_position, x_number and y_number are missing, the whole of the data area is set to the supplied value.

	RETVAL  = DTI_INIT_WORD_DATA ( dti_lun, value, 
				      [x_position], [y_position],
				      [x_number], [y_number] )
	
	dti_lun		integer*4	in	LUN on which the DTI file
						is open

	value		integer*2	in	word value

	x_position	integer*4	in	start column

	y_position	integer*4	in	start row

	x_number	integer*4	in	number of columns

	y_number	integer*4	in	number of rows


Function return codes:
  • DTI__NORMAL Success
  • DTI__BADLUN DTI_LUN out of range (1:9)
  • DTI__LUNUNUSED No file opened on DTI_LUN
  • DTI__DATAMISMATCH The DTI file is not set up to contain word data
  • DTI__BADATAPOS Start column and row values do not lie within the data area
  • DTI__BADDATAEXT Rectangular area of interest does not lie within the data area
  • DTI__READONLY Only read access to the file is permitted
  • DTI__MISSARGS Some but not all of the optional arguments are present

DTI_INIT_LONG_DATA

Routine to set a rectangular area in the DTI data area to a specified longword (INTEGER*4) value. If the optional arguments x_position, y_position, x_number and y_number are missing, the whole of the data area is set to the supplied value.

	RETVAL  = DTI_INIT_LONG_DATA ( dti_lun, value, 
				      [x_position], [y_position],
				      [x_number], [y_number] )
	
	dti_lun		integer*4	in	LUN on which the DTI file
						is open

	value		integer*4	in	longword value

	x_position	integer*4	in	start column

	y_position	integer*4	in	start row

	x_number	integer*4	in	number of columns

	y_number	integer*4	in	number of rows


Function return codes:
  • DTI__NORMAL Success
  • DTI__BADLUN DTI_LUN out of range (1:9)
  • DTI__LUNUNUSED No file opened on DTI_LUN
  • DTI__DATAMISMATCH The DTI file is not set up to contain longword data
  • DTI__BADATAPOS Start column and row values do not lie within the data area
  • DTI__BADDATAEXT Rectangular area of interest does not lie within the data area
  • DTI__READONLY Only read access to the file is permitted
  • DTI__MISSARGS Some but not all of the optional arguments are present

DTI_INIT_REAL_DATA

Routine to set a rectangular area in the DTI data area to a specified real value. If the optional arguments x_position, y_position, x_number and y_number are missing, the whole of the data area is set to the supplied value.

	RETVAL  = DTI_INIT_REAL_DATA ( dti_lun, value, 
				      [x_position], [y_position],
				      [x_number], [y_number] )
	
	dti_lun		integer*4	in	LUN on which the DTI file
						is open

	value		real		in	real value

	x_position	integer*4	in	start column

	y_position	integer*4	in	start row

	x_number	integer*4	in	number of columns

	y_number	integer*4	in	number of rows


Function return codes:
  • DTI__NORMAL Success
  • DTI__BADLUN DTI_LUN out of range (1:9)
  • DTI__LUNUNUSED No file opened on DTI_LUN
  • DTI__DATAMISMATCH The DTI file is not set up to contain real data
  • DTI__BADATAPOS Start column and row values do not lie within the data area
  • DTI__BADDATAEXT Rectangular area of interest does not lie within the data area
  • DTI__READONLY Only read access to the file is permitted
  • DTI__MISSARGS Some but not all of the optional arguments are present