10.4 Output File Name when Opening an Existing File

An optional output filename may be specified in parentheses immediately following the base file name to be opened. This is mainly useful in those cases where CFITSIO creates a temporary copy of the input FITS file before it is opened and passed to the application program. This happens by default when opening a network FTP or HTTP-type file, when reading a compressed FITS file on a local disk, when reading from the stdin stream, or when a column filter, row filter, or binning specifier is included as part of the input file specification. By default this temporary file is created in memory. If there is not enough memory to create the file copy, then CFITSIO will exit with an error. In these cases one can force a permanent file to be created on disk, instead of a temporary file in memory, by supplying the name in parentheses immediately following the base file name. The output filename can include the '!' clobber flag.

Thus, if the input filename to CFITSIO is: file1.fits.gz(file2.fits) then CFITSIO will uncompress `file1.fits.gz' into the local disk file `file2.fits' before opening it. CFITSIO does not automatically delete the output file, so it will still exist after the application program exits.

The output filename "mem://" is also allowed, which will write the output file into memory, and also allow write access to the file. This 'file' will disappear when it is closed, but this may be useful for some applications which only need to modify a temporary copy of the file.

In some cases, several different temporary FITS files will be created in sequence, for instance, if one opens a remote file using FTP, then filters rows in a binary table extension, then create an image by binning a pair of columns. In this case, the remote file will be copied to a temporary local file, then a second temporary file will be created containing the filtered rows of the table, and finally a third temporary file containing the binned image will be created. In cases like this where multiple files are created, the outfile specifier will be interpreted the name of the final file as described below, in descending priority:

• as the name of the final image file if an image within a single binary table cell is opened or if an image is created by binning a table column.
• as the name of the file containing the filtered table if a column filter and/or a row filter are specified.
• as the name of the local copy of the remote FTP or HTTP file.
• as the name of the uncompressed version of the FITS file, if a compressed FITS file on local disk has been opened.
• otherwise, the output filename is ignored.

The output file specifier is useful when reading FTP or HTTP-type FITS files since it can be used to create a local disk copy of the file that can be reused in the future. If the output file name = `*' then a local file with the same name as the network file will be created. Note that CFITSIO will behave differently depending on whether the remote file is compressed or not as shown by the following examples:

• ftp://remote.machine/tmp/myfile.fits.gz(*) - the remote compressed file is copied to the local compressed file `myfile.fits.gz', which is then uncompressed in local memory before being opened and passed to the application program.

• ftp://remote.machine/tmp/myfile.fits.gz(myfile.fits) - the remote compressed file is copied and uncompressed into the local file `myfile.fits'. This example requires less local memory than the previous example since the file is uncompressed on disk instead of in memory.

• ftp://remote.machine/tmp/myfile.fits(myfile.fits.gz) - this will usually produce an error since CFITSIO itself cannot compress files.

The exact behavior of CFITSIO in the latter case depends on the type of ftp server running on the remote machine and how it is configured. In some cases, if the file `myfile.fits.gz' exists on the remote machine, then the server will copy it to the local machine. In other cases the ftp server will automatically create and transmit a compressed version of the file if only the uncompressed version exists. This can get rather confusing, so users should use a certain amount of caution when using the output file specifier with FTP or HTTP file types, to make sure they get the behavior that they expect.