.. SPDX-FileCopyrightText: 1992-2026 NWO-I/SRON Space Research Organisation Netherlands
..
.. SPDX-License-Identifier: CC-BY-4.0

Temporary File Management (scratch)
===================================

**Module**: ``utils_scratch``

Overview
--------

Provides utilities for managing temporary scratch files in SPEX, primarily for logging and system operations. The scratch module creates temporary log files that are automatically cleaned up when SPEX exits.

Key Features
------------

- Automatic temporary log file management
- Session-based scratch file tracking
- Automatic cleanup on SPEX exit
- Integration with SPEX logging system
- Error handling and reporting

API Reference
-------------

Subroutines
~~~~~~~~~~~

**init**

.. function:: scr%init(ier)

   Initialize scratch file system

   :param ier: Error status (integer, output)
   :return: None
   
   Sets up temporary scratch files for logging and system operations.
   
   **Status Codes**:
   - ``ier = 0``: Success
   - ``ier ≠ 0``: Failure (cannot create scratch files)

**addlog**

.. function:: scr%addlog(string)

   Add message to scratch log file

   :param string: Message to add (character(*))
   :return: None
   
   Writes a string to the scratch log file.

**addsys**

.. function:: scr%addsys(string)

   Add message to scratch system file

   :param string: Message to add (character(*))
   :return: None
   
   Writes a string to the scratch system file.

**final**

.. function:: scr%final()

   Clean up scratch files

   :return: None
   
   Closes and deletes all scratch files. This should only happen at successful exit of SPEX.

Usage Examples
--------------

**Basic Scratch File Initialization**

.. code-block:: fortran

   use utils_scratch
   integer :: ier
   
   ! Initialize scratch file system
   call scr%init(ier)
   if (ier == 0) then
      write(*,*) 'Scratch files initialized successfully'
   else
      write(*,*) 'Error: Cannot create scratch files'
   endif

**Adding Messages to Scratch Files**

.. code-block:: fortran

   use utils_scratch
   integer :: ier
   
   ! Initialize scratch system
   call scr%init(ier)
   if (ier == 0) then
      ! Add messages to log and system files
      call scr%addlog('Starting data processing...')
      call scr%addsys('System initialized')
      
      ! ... perform operations ...
      
      call scr%addlog('Data processing completed')
      call scr%addsys('System shutting down')
      
      ! Clean up scratch files
      call scr%final()
   endif

**Error Handling with Scratch Files**

.. code-block:: fortran

   use utils_scratch
   use utils_message
   integer :: ier
   type(message) :: mesg
   
   ! Initialize with error handling
   call scr%init(ier)
   if (ier /= 0) then
      call mesg%sper('Failed to initialize scratch files')
      call mesg%sper('Check directory write permissions')
   else
      ! Add log messages
      call scr%addlog('Application started')
      
      ! ... perform operations ...
      
      ! Add system messages
      call scr%addsys('Operation completed successfully')
      
      ! Clean up
      call scr%final()
   endif

**Integration with SPEX Workflow**

.. code-block:: fortran

   use utils_scratch
   use utils_message
   integer :: ier
   type(message) :: mesg
   
   ! Initialize scratch files at start of SPEX session
   call scr%init(ier)
   if (ier == 0) then
      call scr%addlog('SPEX session started')
      call scr%addsys('System ready')
      
      ! ... SPEX operations ...
      
      ! Log important events
      call scr%addlog('Data loaded successfully')
      call scr%addsys('Memory allocated')
      
      ! ... more operations ...
      
      ! Final cleanup when SPEX exits
      call scr%final()
   else
      call mesg%sper('SPEX cannot start: scratch file initialization failed')
   endif

Notes
-----

**Scratch File Management**

- Scratch files are automatically created with unique names based on process ID
- Files are stored in the current working directory with names like ``spexsysXXXXXXXXXX.dum`` and ``spexlogXXXXXXXXXX.dum``
- All scratch files are automatically deleted on ``scr%final()``
- Scratch files are used primarily for logging and system operations

**Error Handling**

- Check ``ier`` after initialization
- ``ier = 0`` indicates success
- Non-zero values indicate errors (usually permission issues)
- Use ``mesg%sper()`` for error reporting

**Performance Considerations**

- Scratch files use disk I/O for logging
- Minimal performance impact for normal operations
- Files are small and temporary
- Automatic cleanup prevents disk space issues

**Best Practices**

1. **Always initialize** scratch system at SPEX startup
2. **Always clean up** with ``scr%final()`` at SPEX exit
3. **Use for logging** important events and system messages
4. **Check initialization errors** and handle gracefully
5. **Use with message system** for consistent error reporting

**Common Use Cases**

.. list-table::
   :widths: 20 30 50
   :header-rows: 1

   * - Use Case
     - Description
     - Example
   * - **SPEX Session Logging**
     - Track SPEX operations and events
     - Startup, data loading, processing steps
   * - **System Monitoring**
     - Record system state and operations
     - Memory allocation, file operations
   * - **Error Diagnosis**
     - Capture debug information
     - Problem analysis and troubleshooting
   * - **Session Tracking**
     - Monitor SPEX workflow progression
     - Step-by-step operation logging

See Also
--------

- :doc:`files` - General file operations
- :doc:`../core/message` - Error handling and reporting
- :doc:`../core/system` - System operations