CHAPTER 6 FITS TO SAD TRANSFER 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); SPECKLE In the case of SPECKLE format (not the UM speckle format) tapes, the data is autocorrelated during tape reading. Page 2 6.2.0 COMMAND STRUCTURE 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 6.2.1 SUMMARY OF COMMANDS **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 command MOVE_TAPE Moves magnetic tape by number of files/records. 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 6.2.2 COMMAND DETAILS HE HE HELP This command lists the available commands. FI 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 file. '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 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 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' 'FILE=' 'ENTER FILE TYPE: 'NEW' OR 'OLD'' 'TYPE=' e.g., OP(FILE=JIM,TYPE=NEW) TR 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: 'ENTER NAME(S) FOR TRANSFER' '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 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 (default). '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 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 MO(MOVE=3,0). Messages and Keywords: 'ENTER NO OF FILES AND RECS TO BE MOVED' '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 eof's. RE RE REWIND_TAPE This command rewinds the magnetic tape. EX EX EXIT This command asks if a rewind of tape is required. Exits from the program. Page 7 EN EN END This command exits from the program. SH SH SHOW_STATUS This command displays the present status of the program modes. Displays:- FILE_STRUCTURE IMAGE_STRUCTURE MODE 'FILE' or 'IMAGE' XEOF if .TRUE. cross file boundaries if .FALSE. do not cross file boundaries. STRIP_MODE if .TRUE. strip record tags. if .FALSE. do not strip record tags. SE 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' 'FILE=' 'ENTER IMAGE STRUCTURE' 'IMAGE=' '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 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 MOVE=3,0. Messages and Keywords: 'ENTER NO OF FILES AND RECS TO BE MOVED' 'MOVE=' NB it is advisable to enter both parameters or unpredictable tape movement may result. e.g., '4,0' rather than just '4'. 'ENTER DUMP FORMAT' 'FORMAT=' Enter 'HEX' [Default] or 'ASCII'. 'ENTER NO OF BYTES' 'LENGTH=' Default is no of bytes in physical record. PA 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' IMAGE_STRUCTURE = 'SAD' 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 IMAGE_STRUCTURE= 'FITS' XEOF = .FALSE. Page 10 STRIPMODE = .FALSE. FILEMODE = .FALSE. Speckle tapes use the following parameters: FILE_STRUCTURE = 'RT11' IMAGE_STRUCTURE = 'SPKL' XEOF= .TRUE. STRIP_MODE = .TRUE. FILE_MODE = .TRUE.