6.1 DESCRIPTION

            This program reads magnetic tapes written on various  instruments

            and transfers them to disk files in the SAD format.  Normally the

            user will specify the instrument/tape format when the program  is

            started  and  from  then  on  the program will act appropriately.

            Details of how to vary the standard manner of tape  handling  are

            given  in  Appendix  A.   Presently,  this  program  is not fully

            functional and not very user friendly.  All transfers to the  SAD

            format from UM CCD's use the program CCDSAD.

                 Current legal instrument/tape formats are:-

                 SAD (or alternatively PDS);

                 FITS (or IPCS);


                 In the case of SPECKLE format (not the  UM  speckle  format)

            tapes, the data is autocorrelated during tape reading.

                                                                Page 2


                 MTREAD prompts the user for a  command  with  the  character

          '/'.  The command entered by the user is made up of two parts:  the

          command name which describes the action to be  carried  out,  e.g.,

          MOVE_TAPE;  and  the  parameters  to  be  used  in carrying out the

          command, e.g., the number of files and/or records.  In the  current

          implementation  only  the  first two characters of the command name

          are used for identification, any extra characters are ignored.

                 Parameter input is via the USRINP  decoding  routines.   The

          parameters  can  be  set  by  allowing  the  computer to prompt for

          compulsory input, or by entering the values with  keywords  in  the

          command  call.   In  some  cases,  e.g., the DIRECTORY command, the

          program  does  not  prompt  for  values  and  default  values   are

          automatically used unless defined by keywords in the command call.

                 Examples  of  command  formats  are  given  below.   Further

          details are given in the USRINP documentation.

          (a) COMMAND (e.g., OP for OPEN_DISK to open a disk file)

              The program will prompt the user for  the  required  parameters

              unless  they are automatically defaulted.  A <CR> in reply to a

              parameter request will cause the default value to be used.

          (b) COMMAND(Key=value(s)) (e.g., OP(FILE=FRED,TYPE=NEW))

              The program accepts the values given with the keywords.

          (c) .COMMAND (e.g., .DU )

              The program will  use  the  parameter  values  saved  from  the

              previous call to the same command.

          (d) .COMMAND(Key=value(s)) (e.g., .DU(LENGTH=30))

              The program executes the last saved sequence changing only  the

              keyword defined.

                                                                Page 3


          **Common Commands**

          HELP                   Lists the available commands.

          FIND_TAPE              Finds file or image on  magnetic  tape  'FF'

                                 and 'FS' will default to this command.

          PRINT_HEADER           Prints out the contents of the header of the

                                 tape file or image.

          OPEN_DISK              Opens a SAD file on disk for writing data.

          TRANSFER_DATA          Transfers file(s) or image(s) from  magnetic

                                 tape to disk.

          DIRECTORY              Gives a list  of  files/images  on  magnetic

                                 tape.    'CATALOG'   will  default  to  this


          MOVE_TAPE              Moves   magnetic   tape   by    number    of


          REWIND_TAPE            Rewinds the magnetic tape.

          EXIT                   Queries rewind and stops the program.

          END                    Stops the program

          **Supplementary Commands**

          SHOW_STATUS            Lists the current status and modes.

          SET_MODE               Allows changing modes.

          DUMP_TAPE              Dumps magnetic tape in HEX or ASCII.

          PAUSE                  Suspends the program

                                                                Page 4



          HE     HELP

          This command lists the available commands.


          FI     FIND_TAPE

          This command finds the defined file/image  (depending  on  transfer

          mode  -  file or image) on the magnetic tape.  If the name is given

          as '*', the program will find the  next  file/image.   The  command

          advances  the  tape one EOF except at the beginning of the tape and

          fills a buffer with the header.  FI only  moves  the  tape  in  the

          forward direction.  Negative numbers and zero are treated as +1.

              Messages and Keywords:

              'FILE NAME?'

              'FILE='                    Enter the file name,  '*'  for  next

                                         file,     or  '  '  for  the current


              'IMAGE NAME?'              This message  appears  only  in  the

                                         image mode

              'IMAGE='                   Enter the image name or '*' for  the

                                         next image.

                                 e.g.,    FI(FILE=FRED,IMAGE=PDS#1)


          PR     PRINT_HEADER

          This command gives the header details for the current tape file  or

          image, in the same format as the DI(MODE=FU) command.  This command

          is useful for verifying the contents  of  the  file  on  unlabelled

          tapes,  e.g.,  FITS  tapes.   In  order  for  the  command  to work

          properly, it must be preceded by FI; if the command follows TR  the

          program will hang up.

                                                                Page 5


          OP     OPEN_DISK

          This command opens a named SAD disk file for output.   The  program

          asks  if  the  file  is  old  or new and checks if the file already

          exists on disk.  If an 'old' file has been opened, it adds data  to

          the already existing file; otherwise it creates a new file.  If the

          data  format  is  SPECKLE  (for  radio  astronomy),  two  files   -

          AUTOCORRELATION and PHASE - are opened.

              Messages and Keywords:

              'ENTER FILE NAME'


              'ENTER FILE TYPE:  'NEW' OR 'OLD''


                 e.g.,    OP(FILE=JIM,TYPE=NEW)


          TR     TRANSFER_DATA

          This command transfers files/images (depending on transfer  mode  -

          file or image) from magnetic tape to the opened disk file.

              Messages and Keywords:


          'TRANSFER='                    Enter  file/image  name(s)   if   in

                                         file/image   mode.    An   '*'  will

                                         transfer  1  file/images  (currently

                                         the only way this command works).

          N.B.  If in the image mode, only images in the current file will be

          transferred  unless  XEOF  is  set  to  .TRUE., i.e., crossing file

          boundaries is enabled.


          DI     DIRECTORY

          This command gives a listing  of  files/images  on  magnetic  tape.

          Default gives a 'STANDARD' listing only, i.e., file names and image

          names.  Alternatives are 'BRIEF' - file names  only,  or  'FULL'  -

          header details.

              Messages and Keywords:

              Note  that  no  prompts  are  printed  by  the  program.    Any

              alterations  to  the  'STANDARD' description require the use of

              keywords with the command.

              'MODE='            Enter 'BR' (Brief)  File names only

                                                                Page 6

                                       'ST' (Standard) File and  Image  names


                                       'FU' (Full) Header details.

              'FILE_SPEC='       Enter file name to be listed.

              'IMAGE_SPEC='      Enter image name to be listed.

                    e.g.,        DI(MODE=FU,FILE_SPEC=FRED)


          MO     MOVE_TAPE

          This command moves the magnetic tape  over  the  stated  number  of

          EOF's and/or physical records.

          N.B.  This  refers  to  physical  end-of-file  marks  and  physical

          records  on  the  magnetic  tape  and  does not take account of the

          different file structure on magnetic tapes.  Thus, to move over one

          RT11   file   which  includes  3  eof's,  the  command  has  to  be


              Messages and Keywords:


              'MOVE='                    N.B.  Both values  must  be  stated,

                                         else   the   tape  movement  may  be

                                         unpredictable.   Thus  enter   '4,0'

                                         rather  than just '4' to move over 4



          RE     REWIND_TAPE

          This command rewinds the magnetic tape.


          EX     EXIT

          This command asks if a rewind of tape is required.  Exits from  the


                                                                Page 7


          EN     END

          This command exits from the program.


          SH     SHOW_STATUS

          This command displays the present status of the program modes.




              MODE                       'FILE' or 'IMAGE'

              XEOF                       if .TRUE.  cross file boundaries

                                         if  .FALSE.   do  not   cross   file


              STRIP_MODE                 if .TRUE.  strip record tags.

                                         if  .FALSE.   do  not  strip  record



          SE     SET_MODE

          This command enables the user to change the default  modes  set  up

          for  the  transfer of data from magnetic tape.  The routine expects

          data to be supplied by keywords.  If no  keyword  is  present,  the

          user is prompted by the following:

              Messages and Keywords:

              'TRANSFER MODE?'

              'MODE='                    Enter 'FILE' or 'IMAGE'.

              'ENTER FILE STRUCTURE'




              'STRIP RECORD TAGS?'

              'STRIP='                'YES' or 'TRUE' or 'NO' or 'FALSE'

              'CROSS FILE BOUNDARIES?'

              'XEOF='                 'YES' or 'TRUE' or 'NO' or 'FALSE'.

                 e.g.,           SE(MODE=IMAGE,XEOF=TRUE)

                                                                Page 8


          DU     DUMP_TAPE

          This command moves the magnetic tape by  the  requested  number  of

          EOF's  and  physical  records  forward or backward from the current

          location and then dumps a stated number of bytes in HEX or ASCII.

          N.B.  The move is  in  terms  of  physical  end-of-file  marks  and

          physical  records on the magnetic tape and does not take account of

          the different file structure on magnetic tapes.  Thus, to move over

          one  RT11  file  which  includes  3  EOF's,  the  command has to be


          Messages and Keywords:


          'MOVE='                        NB it is  advisable  to  enter  both

                                         parameters   or  unpredictable  tape

                                         movement may result.

                                         e.g., '4,0' rather than just '4'.


          'FORMAT='                      Enter 'HEX' [Default] or 'ASCII'.

          'ENTER NO OF BYTES'

          'LENGTH='                      Default is no of bytes  in  physical



          PA     PAUSE

          This command suspends the program.  It can be  restarted  with  the

          'CONTINUE' command.

                                                                Page 9

                     APPENDIX A:  Tape Handling Control Variables

                 Tape format is described by two  parameters,  FILE_STRUCTURE

          and  IMAGE_STRUCTURE.   FILE_STRUCTURE  defines  the  physical file

          structure on the tape, e.g., 'RT11', while IMAGE_STRUCTURE  defines

          the  format  of the images within the files, e.g., 'SAD' or 'FITS'.

          It is possible to have different image structures on tapes with the

          same  file structure and vice versa, e.g., PCA or SAD data can both

          exist within an RT11 file structure; FITS  can  be  written  on  an

          unlabelled or an ANSI labelled tape.

                 Data transfer mode is determined  by  the  status  variables

          XEOF, STRIP_MODE and FILE_MODE all of which are type LOGICAL:

          XEOF           If true, cross end of file marks when searching  for

                         an image.

          STRIP_MODE     If true, strip any tags on logical tape records.

          FILE_MODE      If true, do transfers and searches in terms of whole

                         files,  otherwise  operate in terms of images.  N.B.

                         When interfacing to the user, the LOGICAL file  mode

                         variable  is changed to CHARACTER with values 'FILE'

                         or 'IMAG'.

                 Initially, default modes and status are set up for  PDS  and

          other SAD tapes, e.g., 2DPCA) as follows:

          FILE_STRUCTURE = 'RT11'


          XEOF = .FALSE.           i.e., do not cross file boundaries  during

                                   transfer  of  data  in  image  mode  (when

                                   FILE_MODE=.FALSE.).  Stop when the end  of

                                   file is reached.

          STRIP_MODE = .TRUE.      i.e.,  strip  record   tags   written   on

                                   magnetic tape by PDS program.

          FILE_MODE = .TRUE.       i.e., transfer  by  file  rather  than  by

                                   image.  Expressed in terms of MODE=FILE or

                                   IMAGE as per SET_MODE.

          Similarly the following defaults are set for FITS tapes:

          FILE_STRUCTURE = 'UNLB'  tape is unlabelled


          XEOF = .FALSE.

                                                               Page 10

          STRIPMODE = .FALSE.

          FILEMODE = .FALSE.

                         Speckle tapes use the following parameters:

          FILE_STRUCTURE = 'RT11'


          XEOF= .TRUE.

          STRIP_MODE = .TRUE.

          FILE_MODE = .TRUE.