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

System Interface (sys)
=======================

**Module**: ``utils_sys``

Overview
--------

Provides platform-independent system functions for SPEX, including date/time operations, environment variable access,
and system information retrieval.

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

- Cross-platform system interface
- Date and time functions
- Environment variable access
- System information retrieval
- No external dependencies

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

Functions
~~~~~~~~~

**sys_datum**

.. function:: sys_datum(datum)

   Get current date and time from the operating system

   :param datum: Formatted date and time string (character*24, output)
   :return: None
   
   Returns system date and time in standardized 24-character format.
   
   **Format**: ``DD-MMM-YYYY HH:MM:SS GMT``
   
   **Example**: ``15-JAN-2024 14:30:45 GMT``

**sys_getenv**

.. function:: sys_getenv(ename, evalue, l)

   Retrieve environment variable value

   :param ename: Environment variable name (character(*), input)
   :param evalue: Environment variable value (character(*), output)
   :param l: Length of returned value (integer, output)
   :return: None
   
   Case-sensitive environment variable lookup.
   
   Returns actual length of value for proper string handling.

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

**Get Current Date/Time**

.. code-block:: fortran

   use utils_sys
   character(len=24) :: current_time
   
   ! Get current system time
   call sys_datum(current_time)
   write(*,*) 'Current time:', trim(current_time)

**Read Environment Variables**

.. code-block:: fortran

   use utils_sys
   character(len=256) :: spex_path
   integer :: path_length
   
   ! Get SPEX installation path
   call sys_getenv('SPEX4', spex_path, path_length)
   if (path_length > 0) then
      write(*,*) 'SPEX installed at:', trim(spex_path(1:path_length))
   else
      write(*,*) 'SPEX4 not set'
   endif

**System Information**

.. code-block:: fortran

   use utils_sys
   character(len=24) :: timestamp
   character(len=256) :: username, home_dir
   integer :: username_len, home_len
   
   ! Get system information
   call sys_datum(timestamp)
   call sys_getenv('USER', username, username_len)
   call sys_getenv('HOME', home_dir, home_len)
   
   write(*,*) 'System Info:'
   write(*,*) '  Time: ', trim(timestamp)
   write(*,*) '  User: ', trim(username(1:username_len))
   write(*,*) '  Home: ', trim(home_dir(1:home_len))

Notes
-----

**Platform Independence**

- Abstracts operating system differences
- Consistent behavior across Unix/Linux/Windows
- Handles environment variable syntax differences

**Error Handling**

- No explicit error codes
- Returns empty strings for unset variables
- Length parameter helps detect unset variables

**Performance**

- Fast system calls
- Minimal overhead
- Suitable for frequent calls

**Best Practices**

1. **Check length parameter** to detect unset variables
2. **Use trim()** on returned strings
3. **Handle unset variables** gracefully
4. **Use for logging** and debugging information

See Also
--------

- :doc:`constants` - Mathematical constants
- :doc:`message` - Error reporting
- System documentation for environment variables