Contents

FITS File Operations (fitsutils)

Module: utils_fits

Overview

Provides utilities for working with FITS (Flexible Image Transport System) files, the standard astronomical data format. Includes functions for checking FITS files and managing logical units.

Key Features

  • FITS file existence checking

  • FITS file type verification

  • Logical unit management

  • Error handling and reporting

API Reference

Subroutines

fitsgetlun

fitsgetlun(unit, status)

Get a free logical unit number

Parameters:

  • unit – Logical unit number (integer, out)

  • status – Error status (integer, out)

Returns:

None

Finds and returns a free logical unit number between 80 and 140.

Status Codes: - status = 0: Success - status = 1: Failure (too many files open)

fitsexist

fitsexist(fnam, status)

Check if FITS file exists

Parameters:

  • fnam – FITS filename (character(*), in)

  • status – Error status (integer, out)

Returns:

None

Tests whether the specified FITS file exists.

Status Codes: - status = 0: File exists - status = 1: File does not exist

fitstype

fitstype(fnam, hdutype, status)

Check FITS file type

Parameters:

  • fnam – FITS filename (character(*), in)

  • hdutype – HDU type (integer, out)

  • status – Error status (integer, out)

Returns:

None

Tests whether the FITS file is of the desired type.

Status Codes: - status = 0: Success - status = 1: Failure

printerror

printerror(status)

Print FITS error message

Parameters:

status – Error status (integer, in)

Returns:

None

Prints the FITSIO error message corresponding to the status code.

Usage Examples

Getting Logical Unit

use utils_fits
integer :: unit, status

! Get free logical unit
call fitsgetlun(unit, status)

if (status == 0) then
   write(*,*) 'Free logical unit:', unit
else
   write(*,*) 'Error: Too many files open'
endif

Checking FITS File Existence

use utils_fits
integer :: status

! Check if FITS file exists
call fitsexist('observation.fits', status)

if (status == 0) then
   write(*,*) 'FITS file exists'
else
   write(*,*) 'FITS file not found'
endif

Checking FITS File Type

use utils_fits
integer :: status, hdutype

! Check FITS file type
call fitstype('spectrum.fits', hdutype, status)

if (status == 0) then
   write(*,*) 'FITS file type:', hdutype
else
   write(*,*) 'Error checking FITS file type'
endif

Error Handling

use utils_fits
integer :: status

! Simulate an error
status = 107  ! File not found error

! Print error message
call printerror(status)

Notes

Logical Unit Management

  • Finds free units in range 80-140

  • Prevents unit conflicts

  • Automatic unit selection

File Checking

  • Tests file existence

  • Verifies file accessibility

  • Checks file types

Error Handling

  • Standard FITS status codes

  • status = 0 indicates success

  • Non-zero values indicate errors

  • Descriptive error messages

Performance

  • Fast file system operations

  • Minimal overhead

  • Suitable for frequent checks

Best Practices

  1. Check file existence before operations

  2. Get logical units dynamically

  3. Handle errors gracefully

  4. Use for file validation

Common Use Cases

Use Case

Description

Example

File Validation

Check files before processing

Verify input files exist

Unit Management

Get free units dynamically

Prevent unit conflicts

Error Reporting

Display FITS error messages

Debugging assistance

File Type Checking

Verify file compatibility

Validate input formats

See Also

  • File Operations (files) - General file operations

  • ../core/messages - Error reporting

  • FITS Standard Documentation (NASA)

  • CFITSIO Library Documentation