File Operations (files)¶

Module: utils_files

Overview¶

Provides object-oriented file operations for SPEX, including opening, closing, reading, and writing files with comprehensive error handling. Supports various file formats used in X-ray astronomy.

Key Features¶

Object-oriented file handling with type(files)
Comprehensive error checking and status reporting
Support for multiple file formats and types
Automatic file management and cleanup
Integration with SPEX file naming conventions

File Type Codes¶

Code	Description	Common Usage
`1`	General data file	ASCII data, configuration files
`2`	SPEX spectral file	.spo files
`3`	SPEX response file	.res files
`4`	FITS file	Astronomical data formats
`5`	QDP file	Plotting data formats

File Status Codes¶

Code	Description	Behavior
`1`	OLD	Open existing file (read mode)
`2`	NEW	Create new file (write mode)
`3`	REPLACE	Overwrite existing file

API Reference¶

Type¶

files

File handling object with the following components:

Component	Type	Description
`lu`	integer	Logical unit number
`fits`	logical	.true. if FITS format

Methods¶

open

file_handler%open(runam, extension, itype, istat, ier)

Open a file with specified parameters

Parameters:

runam – Base filename (without extension) (character(*))
extension – File extension (character(*))
itype – File type code (integer)
istat – File status code (integer)
ier – Error status (integer, output)

Returns:

None

Opens file and sets logical unit. Returns error in ier.

close

file_handler%close(ier)

Close the currently open file

Parameters:: ier – Error status (integer, output)
Returns:: None

Closes file and releases resources.

getlun

file_handler%getlun(ier)

Get the logical unit number

Parameters:: ier – Error status (integer, output)
Returns:: None

Returns logical unit in file_handler%lu.

read

file_handler%read(variables)

Read data from file (generic interface)

Parameters:: variables – Variables to read (various types)
Returns:: None

Supports multiple data types and formats.

write

file_handler%write(variables)

Write data to file (generic interface)

Parameters:: variables – Variables to write (various types)
Returns:: None

Supports multiple data types and formats.

Usage Examples¶

Basic File Operations

use utils_files
type(files) :: file_handler
integer :: status, file_type, file_status

! Open a new data file
file_type = 1       ! General data file
file_status = 2     ! NEW file
call file_handler%open('mydata', 'dat', file_type, file_status, status)
if (status /= 0) then
   write(*,*) 'Error opening file:', status
else
   write(*,*) 'File opened successfully, LU:', file_handler%lu

   ! Close the file when done
   call file_handler%close(status)
endif

Reading SPEX Spectral File

use utils_files
type(files) :: spo_file
integer :: status, file_type, file_status

! Open existing SPEX spectral file
file_type = 2       ! SPEX spectral file
file_status = 1     ! OLD file
call spo_file%open('source1', 'spo', file_type, file_status, status)
if (status == 0) then
   write(*,*) 'SPO file opened successfully'
   ! Read data...
   call spo_file%close(status)
endif

Writing Response File

use utils_files
type(files) :: res_file
integer :: status, file_type, file_status

! Create new response file
file_type = 3       ! SPEX response file
file_status = 2     ! NEW file
call res_file%open('rgs1', 'res', file_type, file_status, status)
if (status == 0) then
   write(*,*) 'Response file created'
   ! Write data...
   call res_file%close(status)
endif

File Type Detection

use utils_files
type(files) :: auto_file
integer :: status, file_type, file_status

! Open file with automatic type detection
file_type = 1       ! Default to general file
file_status = 1     ! OLD file

! Try different extensions
call auto_file%open('data', 'fits', file_type, file_status, status)
if (status == 0) then
   write(*,*) 'FITS file detected'
   auto_file%fits = .true.
else
   call auto_file%open('data', 'spo', file_type, file_status, status)
   if (status == 0) then
      write(*,*) 'SPO file detected'
   endif
endif

Error Handling Pattern

use utils_files
use utils_message
type(files) :: data_file
type(message) :: mesg
integer :: status, file_type, file_status

! Open file with comprehensive error handling
file_type = 1
file_status = 1
call data_file%open('input', 'dat', file_type, file_status, status)

if (status /= 0) then
   call mesg%sper('Failed to open input file')
else
   ! Process file...
   call data_file%close(status)
   if (status /= 0) then
      call mesg%spwarn('Warning: File close error')
   endif
endif

Batch File Processing

use utils_files
use utils_list
type(files) :: file_handler
type(list) :: file_list
character(len=80) :: filename
integer :: i, status, file_type, file_status

! Add files to process
call file_list%append('data1.spo')
call file_list%append('data2.spo')

! Process each file
file_type = 2       ! SPEX spectral files
file_status = 1     ! OLD files

do i = 1, file_list%nelements
   call file_list%get(i, filename)
   ! Extract base name and extension
   call file_handler%open(trim(filename), '', file_type, file_status, status)
   if (status == 0) then
      write(*,*) 'Processing:', trim(filename)
      ! Process file...
      call file_handler%close(status)
   endif
enddo

Notes¶

File Naming Convention

SPEX uses runam + extension naming
runam is the base name (e.g., ‘source1’)
extension is the file type (e.g., ‘spo’, ‘res’, ‘fits’)
Full filename: runam + ‘.’ + extension

Error Handling

Always check status after file operations
status = 0 indicates success
Non-zero values indicate specific errors
Use message object for consistent error reporting

Memory Management

Files object automatically manages resources
close() releases file handles and memory
No explicit deallocation needed

Performance Considerations

File operations are I/O bound (disk speed)
Opening/closing files has overhead
For multiple operations, keep files open
Use appropriate file types for data

Best Practices

Always check error status after file operations
Use proper file types for different data formats
Close files explicitly when done
Use meaningful filenames for debugging
Handle errors gracefully in production code
Document file formats in code comments

Common File Types in SPEX

Extension	Type Code	Description
`.spo`	2	SPEX spectral data
`.res`	3	Response matrices
`.fits`	4	FITS format files
`.qdp`	5	QDP plotting files
`.dat`	1	General data files

SPEX 4.0 documentation