3.10  external disk files

 maintains a wide range of disk files for its own use internally. Unless you intend to write programs for  you need not be concerned about their formats or, in many cases, even their existence. However, recent versions of  also support “external” disk files to be read from and written to disk directories controlled by you. You may read and write from/to binary “FITS-disk” files with TPHEAD, UVLOD, IMLOD, FITLD, FITTP, and FITAB.. AIPS and some tasks also allow text files to be read or written from/to disk. For example, all print tasks can be instructed to append their output to user-specified text files. These can be examined later with an editor or written to tape with standard tape utilities. The two PostScript tasks, LWPLA and TVCPS, can be instructed to write their output plots in user-specified text files for later processing and, for example, inclusion in manuscripts. And AIPS itself can be instructed to take its input commands from user-created text files.

3.10.1 Disk text files

The most significant user control over external files is the specification of the file’s full name, i.e., its directory path and its name in that path. You specify the directory path by creating an environment variable (“logical name” in peak) before starting AIPS. The simplest way is to change directory (cd Unix utility) to the area you wish to use and enter

where MYAREA is a logical name of your choosing (but all in upper case). Note that the pwd is surrounded by backward single quote marks. The grammar above is for users of c-shell and tc-shell. Users of korn, bourne, and bash shells would type:

also with backward single quote marks. If you are going to read a text file into , its name must also be in upper-case letters. Finally, inside AIPS, you specify the file with, e.g.,

where 3C123.PRT is any all upper-case file name of your choosing. Note the surrounding quote marks and the colon that separates the logical name and the file name portions. You may put the file anywhere under any name you choose, but we request that you put it an area owned by you, if you have one, or that you use an identifying name and a standard  area set aside for the purpose. Files left around in the  directories are subject to summary deletion. Be sure that  has the privilege to write into your directory; use chmod to allow appropriate write privilege on the directory file (try to avoid world write!). On Unix systems, duplicate file names are not allowed and  tasks will usually die when trying to write a file name that already exists. Print tasks will append to pre-existing files, however. The verb FILEZAP allows you to delete external files from inside AIPS. The name of the file to be deleted is given as an immediate argument.

File names may also be entered as complete path names, so long as they do not require more than 48 characters, the length of the adverb data values. Thus

Note that the trailing quote mark is left off and this is the last command on the input line so that the case is preserved.

Ordinary text files are used in  for a variety of purposes. Every print task offers the option of saving the output in a file specified by OUTPRINT rather than immediately printing and discarding it. Similarly, output PostScript files from LWPLA and TVCPS may be saved in files specified by OUTFILE rather than immediately printing and discarding them. They may be used later in larger displays, or even enclosed as figures in a TEX document such as this ookook. OUTTEXT is used by numerous other tasks, such as SLICE and IMEAN, to write output specific to the tasks which may be of use to other programs.  tables may even be written as text files by task TBOUT, edited by the user, and then read back in by task TBIN. History files may be revised in a similar manner. Adverbs INFILE, INTEXT, CALIN, and INLIST may be used by a number of tasks to specify source models, lists of “star” positions, holography data, and the like. Television color tables are read from and written to disk text files specified with the OFMFILE adverb.

3.10.2 RUN files

RUN files are ordinary text files containing AIPS commands to be executed in sequence in a batch-like manner. They are often used to define procedures which you save in your own area or in an -provided public area with the logical name $RUNFIL. The name of the file must be all upper case letters, followed by a period, followed by your user number as a three-digit “extended-hexadecimal” number with leading zeros. (To translate between decimal and extended hexadecimal, use the  procedures or the AIPS verbs called EHEX and REHEX.) The files are edited from Unix level using emacs, vi, textedit or your other preferred text editor. For example, log in to the aips (or your own) account. From Unix level, type:

to edit with emacs a file called MAPIT for user 121. You may now also use any area of your choosing instead of the public $RUNFIL area. For instructions on the individual editors, consult the appropriate Unix Manuals. Instruction manuals for the GNU emacs editor are available from local computer staff. A SAVE area (§3.5) may be written as a RUN file if you first GET the area and then use SG2RUN.

To use the RUN file, define a logical name as in the previous Section. Then start up AIPS under your user number and enter

where uuu is your user number if extended hexadecimal with leading zeros to make three digits.

3.10.3 FITS-disk files

FITS is an IAU-endorsed binary format standard for astronomical data heavily used by  for almost all of its data on disk and magnetic tape. In fact, it is the only format written by  except for simple tape copying. The basic FITS paper (by Wells, Greisen, and Harten) appeared in Astronomy & Astrophysics Supplement Series, Volume 44, pages 363–374, 1981. The newsgroup sci.astro.fits is devoted to discussion of FITS. World-wide web users can access the FITS home page at http://fits.gsfc.nasa.gov/fits_home.html

 also supports the FITS format written to disk in exactly the same form as it is written to magnetic tape. The tasks FITTP and FITAB may be instructed to write their output files on disk rather than on tape. Likewise, TPHEAD, FITLD, UVLOD, IMLOD, and PRTTP can read from disk. To write to a FITS-disk file, specify:

and to read from a FITS-disk file, you specify:

where you must specify filename with environment variables (“logical names” in peak), e.g.,

in exactly the same way as described for text files in §3.10.1. There is a standard public area, called logically FITS, which you may use for reading and writing FITS-disk files. FITTP will use this area if you do not specify a logical name. Be aware that older files will be purged from this public area when space is needed. Note too that FITTP will write only one disk file per execution; the DOALL option is disabled when writing to disk.

There is a package of procedures to assist in writing and reading more than one FITS-disk file at a time. Enter RUN WRTPROCS to define the procedures. The procedure FITDISK will write a single disk catalog file to a disk file using a name based on the  file name parameters. You may then construct loops invoking FITDISK to write multiple files. For example:

Such file names are useful for their mnemonic content, but must be read back one at a time. The procedure WRTDISK will dump a range of catalog numbers to disk under names that allow the procedure READISK to read them back as a group. These two procedures are particularly useful when moving your data between computer architectures (e.g., from a Solaris to a Linux computer). Note that there is a stand-alone program REBYTE which can do the conversion directly including files of all types.

FITLD can read multiple disk files in either the normal FITS format (as written by FITTP) or the special FITS format written by the VLBA correlator. The only requirement for this operation is that file names end in sequential numbers beginning with 1. FITAB has the ability to write special FITS files with visibility data in tables. These files may be broken up into multiple files, called “pieces,” for size and reliability considerations. These pieces, when written to disk, have names ending in sequential numbers. Special code in FITLD and UVLOD recognize these pieces and read the requested number of them as if they were in one file.

Remote FITS-disk files may be read in much the same manner as remote magnetic tapes. Type HELP DATAIN  C R or HELP DATAOUT  C R for details.

FITS-disk files are written as Fortran files and hence are available also to user-coded programs. The Fortran specifications for the file are ACCESS=’DIRECT’, RECL=2880, FORM=’UNFORMATTED’ in the OPEN statement for Unix systems. Most Fortrans cannot read or write files larger than 2 Gigabytes, so  now reads and writes these files with C subroutines. Users may also, of course, code programs to create such files to be read by FITLD, IMLOD or UVLOD. Consult GOING AIPS, Volume 2, Chapter 13 for details on how to do this.

One of the main uses for FITS-disk files is to transfer data over the Internet between computers. For example, to transfer a file from rhesus (in Charlottesville) to kiowa (at the AOC), log in to rhesus, change to the directory in which you wish to store the file (for example, cd $FITS  C R), and enter:

The file should then be in the desired directory. You may have to rename it, however, to a name in all upper-case letters since that may be required by . (See §3.10.1 for a trick that allows you to use lower-case letters in file names.) The file format will be correct. In general it is better to use the ftp program to “get” files instead of “put”ting them; things tend to go faster that way.

An alternative to using ftp is to use the rcp (remote copy) Unix utility or to write the output file directory in the appropriate area on the other computer. In order to do this, you have to have accounts on both machines, and you should have set up a .rhosts file (see the Unix manual page on rhosts for instructions). Once you know this works (test it via, e.g., rsh rhesus whoami), the syntax for the remote copy is:

(this shows how you would copy it from rhesus to kiowa). A secure copy (scp) would be better if you have set up the secure connection capability.

If you wish to copy a FITS-disk file from one machine to another within a site, check if you can just use the Unix cp command; this is often possible if the remote disk is mounted (or can be auto-mounted) via NFS (the Network File System).

FITS files may be compressed with standard utility programs such as gzip. This does not produce much compression for files written with full dynamic range and floating-point format. However, FITAB offers the option of writing images (not uv data) which are quantized at some suitable level. These are capable of significant compression even if they are in floating-point format.

3.10.4 Other binary data disk files

Data written by the on-line system of the VLA are now often found in disk files rather than on tape. These data are available from an archive of all VLA data. See